MFA enforcement

​

Why this exists

​

How the step-up proof works (server-issued HMAC cookie)

1. Admin signs in with email + password (or Google OAuth).
2. If the user has MFA enabled, the JWT carries mfaPending = true.
3. Admin attempts a state-changing API call. Middleware validates the kaireon_stepup cookie. If the cookie is absent, expired, tampered, or signed for a different user, middleware returns 403 MFA_REQUIRED:
   {
     "error": {
       "code": "MFA_REQUIRED",
       "message": "Admin accounts require MFA verification within the last 15 minutes for write operations.",
       "status": 403,
       "hint": "POST /api/v1/auth/mfa with { action: 'verify', token: '<TOTP>' } (or complete a WebAuthn verify). The server sets a signed step-up cookie on success — no client-side session.update is needed."
     }
   }
   
4. Client calls POST /api/v1/auth/mfa with { action: "verify", token: "<6-digit TOTP>" } (or completes a WebAuthn verify-finish ceremony). On success the server mints a kaireon_stepup cookie:
   • Format: base64url(JSON{sub, iat}).<hex HMAC-SHA256> — signed with NEXTAUTH_SECRET
   • The cookie is httpOnly, sameSite=strict, secure in production
   • TTL: 15 minutes (STEP_UP_TTL_MS = 15 * 60 * 1000)
5. Subsequent admin writes pass as long as the cookie is fresh. No session.update() call is needed — the cookie is the sole freshness proof.

​

Step-up TTL

​

What’s bypassed

• GET / HEAD / OPTIONS requests — no enforcement (read-only)
• Non-admin users — no enforcement (the gate is admin-only)
• Users with MFA not enabled — no enforcement (mfaPending is false)
• /api/v1/auth/mfa itself — must be reachable to do the verify
• /api/auth/* (NextAuth handlers) — needed for sign-in flow
• API-key-authenticated server-to-server calls — these don’t carry a JWT and are gated separately by API-key scope

​

Kill switch (incident only)

​

Tenant-wide mandatory MFA enrollment (a separate control)

​

How it’s configured

​

What it gates

{
  "error": {
    "code": "MFA_ENROLLMENT_REQUIRED",
    "message": "This tenant requires all users to enroll in MFA before performing write actions.",
    "status": 403,
    "hint": "POST /api/v1/auth/mfa with { action: 'enroll' } to begin TOTP setup (or complete WebAuthn registration), then verify to finish enrollment."
  }
}

​

Enrollment UI

• Status overview — whether MFA is enrolled, an “Authenticator app” badge, a passkey count badge, and (once TOTP is enabled) a remaining backup-codes count. When the tenant requires MFA, an inline note tells an unenrolled user they need to set it up before they can make changes.
• Authenticator app (TOTP) — scan a QR code (or enter the manual secret) from action: "setup", then confirm with a 6-digit code via action: "enable". A fresh set of backup codes is generated and shown once at that point (the codes returned by setup are never persisted, so they’re never shown). action: "disable" requires a valid current TOTP code; disabling doesn’t touch WebAuthn credentials.
• Passkeys / security keys (WebAuthn) — register via the standard register/begin → register/finish ceremony. There’s no delete route for a registered passkey yet.

​

Enrolling clears the gate quickly — flipping the tenant flag doesn’t

​

Kill switch

​

Operator runbook

​

What’s in scope

• ✅ Edge middleware enforcement on all state-changing requests to /api/*
• ✅ Server-issued HMAC-SHA256 kaireon_stepup cookie (minted by TOTP/WebAuthn verify)
• ✅ 15-minute sliding-window TTL validated in the Edge runtime via Web Crypto
• ✅ MFA_ENFORCEMENT_DISABLED env kill switch
• ✅ Source-level regression tests covering the middleware path
• ✅ MFA verify endpoint at POST /api/v1/auth/mfa
• ✅ WebAuthn verify-finish also mints the step-up cookie on success

​

Out of scope (later)

• Per-tenant TTL configuration
• Audit log entry on every verify (currently logged at info via logger)
• IP-based step-up (require fresh verify when source IP changes mid-session)

​

What’s already shipped

• ✅ WebAuthn / Passkey support — registration is a two-step ceremony at POST /api/v1/auth/webauthn/register/begin (server issues a challenge) and POST /api/v1/auth/webauthn/register/finish (client posts the attestation). Verification follows the same pattern: POST /api/v1/auth/webauthn/verify/begin then POST /api/v1/auth/webauthn/verify/finish. Implements the same mfaVerifiedAt JWT claim as TOTP, so once a passkey is registered the middleware treats both factors equivalently.
• ✅ TOTP + backup codes
• ✅ Step-up verify endpoint at POST /api/v1/auth/mfa

​

How it’s wired

• The edge middleware (src/middleware.ts) is the single enforcement point for state-changing requests on /api/*. It imports verifyStepUpTokenAsync from src/lib/auth/step-up-edge.ts (Web Crypto only — no node:crypto in the Edge bundle).
• POST /api/v1/auth/mfa (src/app/api/v1/auth/mfa/route.ts) calls mintStepUpToken from src/lib/auth/step-up.ts on a valid TOTP/backup-code verify and sets the kaireon_stepup cookie on the response. No session.update() is called or required.
• The WebAuthn verify-finish route likewise calls mintStepUpToken on a valid assertion.
• A regression test covers the middleware enforcement path end-to-end.