Skip to content

Two-factor authentication (TOTP) support #5

Description

@Manak-hash

Problem

Single password is the only authentication factor. For admins running LinkBreeze on a public IP, 2FA would significantly improve security.

Proposed solution

Implement TOTP-based 2FA using a library like otplib:

  1. Setup flow: Admin goes to Settings → Security → Enable 2FA. Shows a QR code with the TOTP secret. User scans with Authenticator app (Google Authenticator, Authy, etc.), enters a code to verify.
  2. Login flow: After password check, if 2FA is enabled, prompt for TOTP code. Verify before creating session.
  3. Recovery codes: Generate one-time backup codes on setup.

Schema changes needed

Add to users table:

  • totp_secret (text, nullable) — encrypted TOTP secret
  • totp_enabled (boolean, default false)
  • recovery_codes (text, nullable) — JSON array of hashed codes

Acceptance criteria

  • TOTP setup with QR code in admin panel
  • TOTP verification on login
  • Recovery codes generated and usable
  • Ability to disable 2FA (requires current code)
  • Documented in SECURITY.md

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or requestsecuritySecurity-related improvement

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions