Skip to content

feat(auth): two-factor sign-in (TOTP) with a reminder until it's on (v0.472.0) - #909

Merged
vikasprogrammer merged 1 commit into
mainfrom
feat/two-factor
Nov 20, 2026
Merged

vikasprogrammer merged 1 commit into
mainfrom
feat/two-factor

Conversation

@vikasprogrammer

Copy link
Copy Markdown
Owner

What

Opt-in TOTP two-factor sign-in for console members, plus a reminder for everyone who hasn't turned it on — on every new sign-in and/or every N days (workspace setting, default both, 7 days).

Why

Login is magic-link and links leak: self-service recovery DMs them to Slack/Discord and writes them to server.log. A second factor on the human's phone means a leaked link alone signs nobody in.

How

  • Login flow: a link used by a 2FA member mints a pending session (auth_sessions.mfa_pending, 10 min). resolveSession/presence ignore it, so the member API, terminal proxy and nginx auth_request all see "logged out". /api/auth/me 401s with mfaRequired so the console shows a code screen. Public POST /api/auth/2fa/verify swaps it for a fresh sid. Wrong codes are capped at 5 per pending session (then it's destroyed) and 20 per IP per 15 min.
  • At rest: the secret is sealed under the vault master key, recovery codes are stored as SHA-256 hashes, and a used TOTP step can't be replayed.
  • Self-service (Profile): set up with a QR code or a manual key, get 10 recovery codes (copy/download), move to a new phone, make new codes, turn off. Every action after setup needs a current code.
  • Admin: a 2FA badge on the Team page. Reset 2FA: admins can reset members, only owners can reset admins/owners, nobody resets themselves this way. agent-os 2fa-reset <email> is the last resort from the box.
  • Reminder: twoFactor.nag on /api/auth/me opens a dialog with "Set it up" / "Not now". "Not now" quiets it for the rest of that login and restarts the N-day clock. Cadence is set in Settings → Governance → Two-factor reminders, which also shows how many members have 2FA on.
  • Zero new deps: TOTP uses node:crypto. The QR code comes from a small server-side encoder (src/governance/qr.ts), checked bit-for-bit against qrencode -l M for v1/v9/v13.

Verification

  • scripts/two-factor-test.cjs: 59 assertions covering the RFC 6238 vectors, the QR matrix vs qrencode, at-rest storage, the pending-session gate, lockout, recovery-code burn, role rules for reset, the policy cadences, and cleanup on member removal. Added to test:governance.
  • Full npm run test:governance passes (conformance 159/159).
  • Headless-browser QA of the reminder dialog, QR setup, recovery codes, enabled state, challenge screen (desktop + 390px), wrong-code error and the policy card.

Not in scope (follow-ups)

  • Enforcing 2FA (blocking members who haven't turned it on) — this PR only reminds.
  • WebAuthn / passkeys.

🤖 Generated with Claude Code

…v0.472.0)

A magic link can leak (the recovery path DMs it to chat and logs it), so a
member can now require an authenticator-app code as well. A link used by a
2FA member mints a pending session every gate refuses until
POST /api/auth/2fa/verify swaps it for a fresh one. Recovery codes, admin
reset, `agent-os 2fa-reset`, and a reminder dialog on every new sign-in
and every N days (Settings → Governance). Zero new dependencies.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@vikasprogrammer
vikasprogrammer merged commit d45ca85 into main Nov 20, 2026
1 check passed
@vikasprogrammer
vikasprogrammer deleted the feat/two-factor branch November 20, 2026 10:35
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant