Deploying Zero-TOTP

Introduction

Zero-TOTP is a self-hosted, privacy-focused two-factor authentication (2FA) application that implements zero-knowledge encryption for your TOTP secrets. Unlike traditional authenticator apps that store secrets in plaintext or cloud-synced services that can access your data, Zero-TOTP encrypts all secrets client-side before they ever reach the server.

Built with security as the primary concern, Zero-TOTP ensures that even the server administrator cannot access your 2FA secrets. The application uses strong cryptographic algorithms to derive encryption keys from your password, and all encryption/decryption happens in your browser.

Key highlights of Zero-TOTP:

• Zero-Knowledge Architecture: Your TOTP secrets are encrypted before leaving your browser
• Self-Hosted Control: Run your own authentication server without trusting third parties
• Cross-Device Sync: Access your 2FA codes from any device through the web interface
• End-to-End Encryption: Even server administrators cannot read your secrets
• Open Source: Fully auditable codebase for security verification
• Simple Interface: Clean, minimalist design focused on usability
• Backup Support: Export encrypted backups for disaster recovery
• QR Code Scanning: Add new accounts by scanning QR codes directly in the browser

This guide walks through deploying Zero-TOTP on Klutch.sh using Docker, providing you with a secure, self-hosted alternative to cloud-based authenticator apps.

Why Deploy Zero-TOTP on Klutch.sh

Deploying Zero-TOTP on Klutch.sh provides several advantages for secure 2FA management:

Privacy by Design: Combined with Zero-TOTP’s zero-knowledge encryption, your 2FA secrets remain private even on hosted infrastructure.

HTTPS by Default: Klutch.sh provides automatic SSL certificates, ensuring secure transmission of encrypted data.

Always Accessible: Access your 2FA codes from anywhere, on any device, without local app installations.

Reliable Hosting: Your authentication service remains available when you need it most, without managing your own infrastructure.

Environment Variable Security: Store any server-side secrets securely through Klutch.sh’s environment variable system.

Custom Domains: Use your own domain for a professional, memorable URL for accessing your 2FA codes.

Prerequisites

Before deploying Zero-TOTP on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your configuration
• Basic understanding of Docker and containerization
• Understanding of TOTP-based two-factor authentication
• (Optional) A custom domain for your Zero-TOTP instance

Understanding Zero-TOTP Architecture

Zero-TOTP implements a client-side encryption model:

Client-Side Encryption: All encryption and decryption of TOTP secrets happens in the browser using JavaScript cryptography APIs.

Key Derivation: Your master password is used to derive an encryption key using PBKDF2 or similar algorithms. The password never leaves your device.

Encrypted Storage: Only encrypted blobs are stored on the server. The server handles authentication and storage but never sees plaintext secrets.

TOTP Generation: Time-based one-time passwords are generated in the browser using the decrypted secrets.

Preparing Your Repository

Create a GitHub repository containing your Zero-TOTP deployment configuration.

Repository Structure

zero-totp-deploy/
├── Dockerfile
├── config/
│   └── settings.json
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile for Zero-TOTP:

FROM node:18-alpine

# Install dependencies
RUN apk add --no-cache python3 make g++

# Create app directory
WORKDIR /app

# Clone Zero-TOTP repository
RUN apk add --no-cache git \
    && git clone https://github.com/zero-totp/zero-totp.git . \
    && rm -rf .git

# Install dependencies
RUN npm ci --only=production

# Build the application
RUN npm run build

# Set environment variables
ENV NODE_ENV=production
ENV PORT=3000
ENV DATABASE_URL=${DATABASE_URL}

# Expose the application port
EXPOSE 3000

# Start the application
CMD ["npm", "start"]

Environment Variables Reference

Variable	Required	Default	Description
DATABASE_URL	Yes	-	Database connection string for persistent storage
SESSION_SECRET	Yes	-	Secret key for session encryption
PORT	No	3000	Port for the web server
BASE_URL	No	-	Base URL for the application

Deploying Zero-TOTP on Klutch.sh

Generate Security Keys

Generate a secure session secret for your deployment:

openssl rand -hex 32

Save this value for the environment variables configuration.

Push Your Repository to GitHub

Initialize your repository and push to GitHub with your Dockerfile and configuration files.

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project named “zero-totp” or similar.

Create a New App

Within your project, create a new app and connect your GitHub repository.

Configure HTTP Traffic

Zero-TOTP serves its web interface over HTTP:

• Select HTTP as the traffic type
• Set the internal port to 3000

Set Environment Variables

Configure the following environment variables:

Variable	Value
SESSION_SECRET	Your generated session secret
DATABASE_URL	Database connection string
BASE_URL	https://your-app-name.klutch.sh

Attach Persistent Volumes

Add persistent storage for the database:

Mount Path	Recommended Size	Purpose
/app/data	1 GB	SQLite database and application data

Deploy Your Application

Click Deploy to build and start your Zero-TOTP instance.

Access Zero-TOTP

Once deployment completes, access your instance at https://your-app-name.klutch.sh and create your account.

Initial Setup

Creating Your Account

1. Navigate to your Zero-TOTP instance
2. Click Register to create a new account
3. Choose a strong master password - this encrypts all your TOTP secrets
4. Complete the registration process

Adding TOTP Accounts

Add your first 2FA account:

1. Click Add Account or the plus icon
2. Scan the QR code from the service you’re setting up
3. Alternatively, manually enter the secret key
4. Verify the generated code works before completing setup

Organizing Accounts

Zero-TOTP allows you to organize accounts:

• Create categories or folders for different types of services
• Add custom icons or labels
• Search and filter your accounts

Security Best Practices

Master Password Security

• Use a strong, unique master password
• Consider using a passphrase for better memorability
• Never reuse this password elsewhere
• Store a backup securely (physical or encrypted digital)

Backup Your Data

Create regular encrypted backups:

1. Export your encrypted vault from the settings
2. Store backups in multiple secure locations
3. Test backup restoration periodically

Browser Security

Since encryption happens in the browser:

• Keep your browser updated
• Avoid using Zero-TOTP on public or shared computers
• Consider using a dedicated browser profile
• Clear session data after use on shared devices

Troubleshooting Common Issues

Cannot Access Account

Solutions:

• Verify you’re using the correct master password
• Check that the server is running and accessible
• Clear browser cache and try again

TOTP Codes Not Working

Solutions:

• Verify your device time is accurate (TOTP is time-sensitive)
• Ensure the secret was entered correctly
• Check if the service supports 6-digit vs 8-digit codes

Browser Compatibility Issues

Solutions:

• Update to a modern browser version
• Enable JavaScript and Web Crypto API
• Disable browser extensions that might interfere

Additional Resources

• Zero-TOTP GitHub Repository
• TOTP Wikipedia
• RFC 6238 - TOTP Specification

Conclusion

Deploying Zero-TOTP on Klutch.sh gives you a secure, self-hosted two-factor authentication solution with zero-knowledge encryption. Your TOTP secrets remain encrypted and private, accessible only to you with your master password. Combined with Klutch.sh’s reliable hosting and automatic HTTPS, you get a 2FA solution you can trust and access from anywhere.