kv-file implements enterprise security standards to protect files stored on self-hosted servers from unauthorized access, offline password cracking, and credential theft.

1. Two-Factor Authentication (TOTP)

Enhance your account security by requiring a 6-digit Time-based One-Time Password (RFC 6238) whenever logging in:

bash
┌─────────────────────────────────────────────────────────────┐
│                     1. Enter Credentials                    │
│                  Username + Argon2id Password               │
└──────────────────────────────┬──────────────────────────────┘
                               │ Credentials Verified
┌──────────────────────────────▼──────────────────────────────┐
│                  2. Two-Factor Challenge                    │
│            6-Digit Authenticator Code (or Recovery Key)     │
└──────────────────────────────┬──────────────────────────────┘
                               │ Validated (RFC 6238 TOTP)
┌──────────────────────────────▼──────────────────────────────┐
│                    3. Authenticated Session                 │
│              Issues 128-Bit Session Token & Cookie          │
└─────────────────────────────────────────────────────────────┘

Enabling 2FA on Your Account

  1. Open Settings (gear icon in TitleBar) and navigate to the Account tab.
  2. Click Enable Two-Factor Authentication to launch the wizard (TwoFactorSetupModal).
  3. Scan QR Code: Scan the QR code using your preferred authenticator app:
    • Google Authenticator
    • 1Password / Bitwarden
    • Apple Keychain (iOS / macOS)
    • Microsoft Authenticator / Authy
  4. Manual Key: Alternatively, copy the base32 secret key into your authenticator.
  5. Verification: Enter the 6-digit verification code generated by your app.
  6. Recovery Codes: Download or copy your 10 one-time recovery backup codes. Store them in a secure vault. If you ever lose access to your authenticator device, recovery codes allow emergency account restoration.

2. Password Hashing: Argon2id

Passwords are never stored in plaintext or with deprecated algorithms like MD5 or SHA-256.

  • Algorithm: Argon2id (winner of the Password Hashing Competition).
  • GPU & ASIC Resistance: Employs memory-hard and time-hard parameters to render brute-force and dictionary attacks computationally infeasible.
  • Unique Salt: Every account password is generated with a cryptographically secure 128-bit random salt.

3. Session Management & Defense

  • Opaque Session Tokens: Authentication tokens are high-entropy 128-bit UUIDs stored securely in memory and SQLite.
  • Automatic Timeout: Inactive sessions expire according to server policies.
  • Single-Click Invalidation: Logging out via the UI or API immediately purges the session token server-side.
  • Brute-Force Rate Limiting: Consecutive failed login attempts trigger progressive throttling to defeat credential stuffing bots.

4. 2FA API Endpoints

POST/api/v1/auth/2fa/setup
bash
# Generate a new 2FA secret and QR code URI
curl -X POST http://localhost:8866/api/v1/auth/2fa/setup \
  -H "Authorization: Bearer <session-token>"
POST/api/v1/auth/2fa/enable
bash
# Verify code and enable 2FA
curl -X POST http://localhost:8866/api/v1/auth/2fa/enable \
  -H "Authorization: Bearer <session-token>" \
  -H "Content-Type: application/json" \
  -d '{"code":"123456"}'