Repository navigation
v1.1.0
What's new
Multi-factor authentication replaces 2FA — and passkeys are now a first-class sign-in factor.
- Passkeys (WebAuthn). Enroll a passkey (Touch ID / Windows Hello / security key) alongside or instead of an authenticator app, then confirm with it at sign-in and on sensitive actions. Passkey step-up authorizes one sensitive action per verification. On IP-only installs (no domain) passkeys are unavailable by design — authenticator-app MFA keeps working, and the installer summary tells you which mode applies.
- Mandatory MFA enrollment. The password step now only starts a login attempt. An admin with no factor is forced through enrollment before any session is issued; every later sign-in requires a passkey/authenticator code, with one-time recovery codes as fallback. Configuration → Security can require
any(default),totp,passkey, orboth; passkey-requiring policy safely degrades on IP-only deployments instead of locking anyone out. - Recovery codes. 12-character, single-use, salted at rest, and now accepted at sign-in (not just step-up). Regenerate them from Profile after a fresh MFA check. A super admin can reset another admin's MFA — every factor is cleared, their sessions are revoked, and they re-enroll at next sign-in.
- MFA management UI. Profile lists factors with last use, adds/removes passkeys and the authenticator app (step-up gated), shows remaining recovery codes, and warns when an account was left without a factor. The step-up dialog offers "Use passkey" or an authenticator/recovery code.
- 2FA → MFA rename. Routes (
/mfa-verify,/mfa-setup), JSON fields (pending_mfa,is_pending_mfa), cookie (wgc_mfa_pending), audit actions and all user-facing copy.
Security & correctness
- Login can never mint a session without a proven factor; the session middleware rejects pending login rows.
- MFA attempts are bounded per pending login (5 failures → 429 + lockout), and the IP brake resets only after a completed MFA login.
- Enrollment secrets are server-generated and stored encrypted; WebAuthn challenges are cookie-bound, single-use and short-lived.
- WebAuthn credential flags (including backup-eligible) are persisted raw and restored correctly; sign-count/clone-warning are written back after each login.
- Adding/removing factors or resetting MFA revokes other sessions and clears step-up stamps.
- Backup restore re-runs migrations so the new MFA tables exist immediately.
Dependencies
- Added
github.com/go-webauthn/webauthn v0.18.2(BSD-3) and@simplewebauthn/browser 14.0.0(MIT, zero dependencies, dynamically imported). - Upgraded Go modules (pgx 5.12, x/net 0.62, WireGuard) and frontend packages to their latest releases.
Upgrade notes
- No manual database steps. Migration 028 is additive and runs on boot. Existing authenticator-app users keep their factors; the first sign-in after upgrading shows the new MFA challenge.
- Breaking API rename: the old
/api/auth/2fa/*endpoints and 2FA JSON fields are gone (no aliases, by design). A tab left open mid-login across the upgrade must sign in again; active sessions survive. - Passkeys need a real domain. They are unavailable on IP-only installs. Changing
CONSOLE_DOMAINlater orphans previously registered passkeys — the installer now warns about this (authenticator-app MFA and recovery codes keep working). VERSIONis 1.1.0; the one-line installer picks it up automatically.
Verification
- Backend: build + vet clean;
go test ./internal/...green (13 MFA unit tests, 7 WebAuthn unit tests); full e2e against PostgreSQL 18 13/13 suites green — including passkey enrollment/login, one-shot passkey step-up, recovery-code login single-use, last-factor guard, reset-revokes-sessions and 5×wrong-code → 429. - Frontend: 33 files / 236 tests green,
tsc+ production build clean. - Installer/shell tests green; browser demo exercised 12/12 flows end-to-end (forced passkey enrollment → passkey login → add authenticator app via passkey step-up → authenticator login → recovery-code login → regenerate codes) with no console errors.