okooooooo/2fauth-worker

0 Fork 0

Files

T

nap0o 9905d78e1a feat: 用环境变量控制日志输出级别

2026-03-15 13:32:30 +08:00

16 KiB

Raw Blame History

2FAuth Worker

English | 中文

High-security, lightweight Two-Factor Authentication (2FA/TOTP) management system supporting both Cloudflare Serverless and Docker private deployment.

Click here for LIVE DEMO

💡 Tip: The demo site has open enrollment enabled; data can be modified or deleted. For official deployment, please ensure you configure the allowed users whitelist.

🌟 Why choose 2FAuth Worker?

Whether you're leveraging Cloudflare's free tier or deploying on your own NAS/mini-PC, 2FAuth Worker provides the most secure and convenient 2FA management experience.

🕊️ True "Dual-Mode" Deployment

Cloudflare Lovers: One-click deployment to Cloudflare Workers – zero cost, zero maintenance, and global acceleration.
Private Cloud Geeks: Supports Docker deployment. Keep your data locked on your own hardware; it even works in offline local networks.

📱 Smooth PWA Experience

Immersive Experience: Install it to your desktop or mobile home screen for a distraction-free environment without browser bars.
Offline Ready: Thanks to advanced Service Worker caching, it opens instantly and generates accurate codes even in extreme environments without internet (like basements or airplanes).

🛡️ "Smart Shield" Security (Health Shield)

Built-in intelligent health checks. If the system detects critical missing keys or improper configurations, it will immediately "shut down" access to prevent your data from being exposed in an insecure environment.

📦 The Ultimate "Undo Button" (Multi-channel Backup)

Supports automatic backups via WebDAV, S3 cloud storage, or Telegram bots. If you lose your phone, reinstall your OS, or even lose your Cloudflare account, you can recover everything instantly from your backup.

Click to view: Product Feature Comparison

Feature	2FAuth Worker (This Project)	Google / MS Auth	Authy	2FAS / Aegis	1Password / Bitwarden
Data Ownership	✅ Full Control (Private/NAS)	❌ Tied to Big Tech	❌ Vendor-locked	✅ Local/Private Cloud	⚠️ Third-party Hosted
Cross-Platform	✅ Web+PWA (Universal)	⚠️ Mobile App only	❌ Desktop App closed	⚠️ Mobile App only	✅ Full Platform Support
Recovery	✅ Auto Backups (TG/S3)	⚠️ Manually Exporting	✅ Cloud Sync	⚠️ Manage Files Manually	✅ Cloud Sync
Privacy	✅ Anonymous, No Tracking	⚠️ Tied to Big Tech ID	⚠️ Forced Phone Bind	✅ No Tracking	✅ Safe but high profile
Offline Support	✅ Yes (PWA Cache)	✅ Yes	✅ Yes	✅ Yes	✅ Yes
Cost	✅ $0 (CF Serverless)	✅ Free	✅ Free	✅ Free	💰 Subscription based
Vendor Risk	✅ Source in Hand	⚠️ Forced migration risks	🚨 Feature shutdowns (PC)	✅ Open-source control	⚠️ Subscription/Closed

🎯 Summary: 2FAuth Worker combines the multi-device convenience of 1Password with the privacy of open-source apps, and the zero cost of Serverless. Automatic Telegram backup completely eliminates "data loss anxiety" common in both web and mobile apps, making security truly accessible.

🚀 Deployment Guide (Choose One)

Option A: Cloudflare Worker (Fastest, Recommended for Beginners)

The most hassle-free way. No server required; Cloudflare hosts it for you for free.

1. One-click Auto Deploy

Fork this repository, and give it a Star! ⭐
Click the deploy button below

2. Notes & Authorization

In the deployment wizard, you need to authorize Cloudflare to read this repository.

Click to view: Authorization Guide Diagrams

3. Deployment Flow

Click in sequence: Continue with GitHub -> Select your forked repository (2fauth-worker) -> Next -> Deploy -> Continue to project -> Settings

Click to view: Detailed deployment steps diagram

4. Add the following Variables and Secrets in `Settings`

ENCRYPTION_KEY: A random key with at least 32 characters.
JWT_SECRET: A random JWT secret with at least 32 characters.
OAUTH_ALLOWED_USERS: your_email@example.com
OAUTH_GITHUB_CLIENT_ID: Your CLIENT_ID
OAUTH_GITHUB_CLIENT_SECRET: Your CLIENT_SECRET
OAUTH_GITHUB_REDIRECT_URI: Your Callback URL

Click to view: Add Variables and Secrets Diagram

Option B: Docker (For NAS / Private Server Users)

If you want absolute control over your data or need to run it in a local network.

⚠️ Important Security Notice: To provide the highest level of security, this image runs strictly as a non-privileged user (node, UID 1000) to prevent container escape risks. You MUST create the data directory and set the correct permissions on your host machine before starting the container, otherwise you will encounter Permission Denied errors.

0. Prepare Data Directory (Required)

mkdir -p data && sudo chown -R 1000:1000 data

1. Using Docker Compose (Recommended)

Create docker-compose.yml on your server:

services:
  2fauth:
    image: nap0o/2fauth-worker:latest
    container_name: 2fauth-worker
    ports:
      - "3000:3000"
    volumes:
      - ./data:/app/data
    environment:
      # Core Secrets
      - ENCRYPTION_KEY=Your_32_Character_Random_Key
      - JWT_SECRET=Your_32_Character_Random_JWT_Secret
      - OAUTH_ALLOWED_USERS=your_email@example.com
      # Configure at least one provider (GitHub example)
      - OAUTH_GITHUB_CLIENT_ID=your_id
      - OAUTH_GITHUB_CLIENT_SECRET=your_secret
      - OAUTH_GITHUB_REDIRECT_URI=[https://your-domain.com/oauth/callback](https://your-domain.com/oauth/callback)
      - LOG_LEVEL=info
    restart: unless-stopped

Run docker compose up -d.

2. Using Docker Run

docker run -d --name 2fauth-worker \
  -p 3000:3000 \
  -v $(pwd)/data:/app/data \
  -e ENCRYPTION_KEY=Your_32_Character_Random_Key \
  -e JWT_SECRET=Your_32_Character_Random_JWT_Secret \
  -e OAUTH_ALLOWED_USERS=your_email@example.com \
  -e OAUTH_GITHUB_CLIENT_ID= \
  -e OAUTH_GITHUB_CLIENT_SECRET= \
  -e OAUTH_GITHUB_REDIRECT_URI=[https://your-domain.com/oauth/callback](https://your-domain.com/oauth/callback) \
  -e LOG_LEVEL=info \
  nap0o/2fauth-worker:latest

Option C: GitHub Actions (For Advanced Users)

Choose this for continuous deployment or more precise database management.

1. Prerequisites

Create a D1 database named 2fauth-db in Storage & Databases -> D1 SQL Database and record its Database ID.

Click to view: Specific steps to create D1 SQL Database

Obtain a Cloudflare API Token (requires Edit Cloudflare Workers permissions).

Click to view: Steps to obtain Cloudflare Worker Deployment Token

Log in to Cloudflare Dashboard
Go to API Tokens
Click "Create Token"
Choose "Edit Cloudflare Workers" template
Configure "Account Resources" and "Zone Resources"
Click "Continue to summary" and "Create Token"
Copy the generated token

2. Repository Configuration

Fork this repository.
Go to Settings -> Secrets and variables -> Actions.
Add the following secrets:

CLOUDFLARE_ACCOUNT_ID: Your CF Account ID.
CLOUDFLARE_API_TOKEN: Your API Token.
CLOUDFLARE_D1_DATABASE_ID: Your D1 Database ID.
CLOUDFLARE_D1_DATABASE_NAME: 2fauth-db.
ENCRYPTION_KEY: A 32+ character random key.
JWT_SECRET: A 32+ character random JWT secret.
OAUTH_ALLOWED_USERS: your_email@example.com
OAUTH_GITHUB_CLIENT_ID: Your ID
OAUTH_GITHUB_CLIENT_SECRET: Your Secret
OAUTH_GITHUB_REDIRECT_URI: Your Callback URL

Click to view: Secrets Configuration Example

3. Trigger Deployment

Go to the Actions page, manually run the Deploy to Cloudflare Workers workflow, or push code to the main branch.

Click to view: Manual Deployment Example

🧩 Environment Variables Configuration

Regardless of the deployment method, these parameters are critical:

Variable	Function	Recommendation
`ENCRYPTION_KEY`	Core: Database encryption key	DO NOT CHANGE after setup! Requirement: 32+ characters.
`JWT_SECRET`	Auth Token Secret	Requirement: 32+ characters.
`OAUTH_ALLOWED_USERS`	Whitelist: Access Control	Emails or Telegram IDs, separated by commas.

Variable Mapping for Different Providers (Choose at least one):

Provider	Client ID Variable	Client Secret Variable	Redirect URI (Example: `https://xxx.dev/oauth/callback`)
GitHub	`OAUTH_GITHUB_CLIENT_ID`	`OAUTH_GITHUB_CLIENT_SECRET`	`OAUTH_GITHUB_REDIRECT_URI`
Telegram	`OAUTH_TELEGRAM_BOT_NAME`	`OAUTH_TELEGRAM_BOT_TOKEN`	Not required for Telegram
Google	`OAUTH_GOOGLE_CLIENT_ID`	`OAUTH_GOOGLE_CLIENT_SECRET`	`OAUTH_GOOGLE_REDIRECT_URI`
Cloudflare Access	`OAUTH_CLOUDFLARE_CLIENT_ID`	`OAUTH_CLOUDFLARE_CLIENT_SECRET`	`OAUTH_CLOUDFLARE_REDIRECT_URI` (requires `OAUTH_CLOUDFLARE_ORG_DOMAIN`)
Gitee	`OAUTH_GITEE_CLIENT_ID`	`OAUTH_GITEE_CLIENT_SECRET`	`OAUTH_GITEE_REDIRECT_URI`
NodeLoc	`OAUTH_NODELOC_CLIENT_ID`	`OAUTH_NODELOC_CLIENT_SECRET`	`OAUTH_NODELOC_REDIRECT_URI`

Visit GitHub Settings -> Developer Settings -> OAuth Apps -> New OAuth App.
Authorization callback URL must be: https://your-domain.com/oauth/callback.
Fill Client ID, Client Secret and OAUTH_GITHUB_REDIRECT_URI into environment variables.

Click to view: Github OAuth Configuration Diagram

Search and add @BotFather on Telegram, following prompts to create a bot.
Record the Token (OAUTH_TELEGRAM_BOT_TOKEN) and Username (OAUTH_TELEGRAM_BOT_NAME).
You MUST send the /setdomain command to @BotFather, select your bot, and enter your application domain (without https://).
Since this is a Serverless architecture, you need to manually register the Webhook.
Replace <Token> and <Domain> in the link below and visit it once in your browser:
https://api.telegram.org/bot<Token>/setWebhook?url=https://<Domain>/api/telegram/webhook
Fill OAUTH_TELEGRAM_BOT_TOKEN, OAUTH_TELEGRAM_BOT_NAME into environment variables.

Enter Cloudflare Zero Trust Dashboard -> Access -> Applications.
Create a SaaS application (Select "SaaS").
Configure Application:
- Name: Anything, e.g., 2fauth
- Authentication Protocol: OIDC
- Redirect URL: https://your-domain.com/oauth/callback
Copy and save Client ID and Client Secret.
Access Policy -> Click create new policy -> Add policy:
- Policy: Allow
- Selector: Everyone
No additional configuration needed, click next through to completion.
Fill OAUTH_CLOUDFLARE_CLIENT_ID, OAUTH_CLOUDFLARE_CLIENT_SECRET, OAUTH_CLOUDFLARE_REDIRECT_URI and OAUTH_CLOUDFLARE_ORG_DOMAIN into environment variables.

Click to view: Cloudflare Access OAuth Configuration Diagram

🔒 Security Auditing

To protect your account security, 2FAuth Worker implements a "Multi-Lock" strategy:

At-Rest Encryption: All TOTP seeds stored in the database are encrypted using AES. Even if the database file is leaked, unauthorized parties cannot obtain raw keys without the ENCRYPTION_KEY.
Whitelist-Only Access: Traditional registration is disabled. Only accounts in the OAUTH_ALLOWED_USERS list can access the system.
Smart Shield Persistence (Health Shield): The system continuously monitors the runtime environment. If any anomalies are detected, it enters protection mode and refuses to generate verification codes.
End-to-End Isolation: Sensitive frontend logic is strictly filtered to prevent XSS (Cross-Site Scripting) attacks.
Privacy First: This project contains no tracking code, analytics tools, or third-party cookies. Your data is yours alone.

📊 Click to view the real-time security audit report generated by GitHub Actions

🛠️ Local Development

# 1. Clone and install dependencies
git clone https://github.com/nap0o/2fauth-worker.git
cd 2fauth-worker
npm install

# 2. Configure environment
cp example.dev.vars .dev.vars

# 3. Initialize local SQLite Sandbox
npx wrangler d1 execute 2fauth-db-dev --local --env dev --file=backend/schema.sql

# 4. Start dev server
npm run dev

📄 License

This project is open-sourced under the GNU AGPL v3 license. Since this software involves 2FA security and network services, we maintain open-source fairness: if you run a modified version of this project on a server and provide services to the public, you must open your source code to the users.

16 KiB Raw Blame History Unescape Escape