[Auth] ADR-0069 remaining — session-validation gate (password expiry + enforced MFA), session controls, IP allowlist, OIDC/SAML

[os-zhuang]

Follow-up to ADR-0069 tracking issue #2281. Collects everything not yet built. The P1 password-policy + anti-brute-force surface is now shipped; what remains is the session-validation gate (P1 leftover), defense-in-depth (P2), and federation breadth (P3).

✅ Already shipped (context)

• D1 breached-password reject (HIBP) — feat(plugin-auth): reject breached passwords via HIBP (ADR-0069 D1, P1) #2361
• D2 account lockout + rate-limit tuning — feat(plugin-auth): account lockout + rate-limit tuning (ADR-0069 D2, P1) #2365
• D1 password complexity — feat(plugin-auth): password complexity policy (ADR-0069 D1, P1) #2368
• D1 password history / no-reuse — feat(plugin-auth): password history / no-reuse (ADR-0069 D1, P1) #2371

Pattern established for all of the above: setting (auth manifest) → bindAuthSettings patch → enforcement seam (better-auth before/after hook or native plugin), default-off, ADR-0049-compliant.

---

🔑 P1 leftover — the session-validation gate (do these together)

Both remaining P1 items enforce at authenticated-request / session-validation time (not the auth endpoints), which today has no denial path. resolveExecutionContext (packages/runtime/src/security/resolve-execution-context.ts) is explicitly "never throws"; the shared authz resolver is resolveAuthzContext (packages/core/src/security/resolve-authz-context.ts); denial happens downstream in SecurityPlugin / the dispatcher. There is no existing MFA/step-up or password-age gate. Building this seam is the bulk of the work and is shared by both items below, so they should land as one focused effort.

• D1 — password expiry [custom][field]. Setting password_expiry_days (0 = off). Field sys_user.password_changed_at (stamp on every successful sign-up / change / reset). On authenticated requests, if now - password_changed_at > expiry → force /change-password (PASSWORD_EXPIRED). (The history PR feat(plugin-auth): password history / no-reuse (ADR-0069 D1, P1) #2371 already touches the change/reset hooks — stamping can be added there.)
• D3 — enforced MFA [custom][field]. Settings mfa_required (global) + mfa_grace_period_days (default 7); per-org sys_organization.require_mfa; field sys_user.mfa_required_at. The twoFactor plugin already provides TOTP enroll/verify — requiring it is the gap: a session whose user has two_factor_enabled = false (and whose grace window has elapsed) is gated out of all protected resources until enrollment + verification. The /two-factor/* enrollment endpoints and /sign-out do not flow through resolveExecutionContext, so they need no allowlist there.
  • Needs an objectui follow-up: the Console must handle an MFA_REQUIRED response by showing the TOTP-enrollment prompt, otherwise flipping mfa_required on bricks the UI for un-enrolled users. Backend gate is default-off so existing envs are unaffected.

Reuse, don't reinvent (verified against better-auth 1.6.20): TOTP/2FA mechanism, session.freshAge (re-auth freshness), revokeSessionsOnPasswordReset, password.hash/verify are all native — only the enforcement/requirement layer is custom.

---

🛡️ P2 — defense in depth (after the gate exists)

• D4 session controls [custom][field] — idle timeout, absolute max lifetime, concurrent-session cap; fields sys_session.{last_activity_at, revoked_at, revoke_reason}. (multiSession + session.expiresIn/updateAge/freshAge are native; idle/absolute/concurrent caps are custom and also ride the authenticated-request seam.)
• D5 IP allowlist [custom][field] — sys_organization.allowed_ip_ranges (+ optional per-user); Hono auth-route middleware before the better-auth handler (trust-proxy-aware client-IP extraction), reject with IP_NOT_ALLOWED.
• D6 OIDC trust-list UI [native] — surface admin-managed OIDC providers (issuer / client / scopes / allowed domains) instead of env-only genericOAuth.

🌐 P3 — federation breadth

• SAML 2.0 — not in better-auth core; assess @better-auth/sso vs a custom plugin. Do not ship a SAML settings surface before an enforcing impl (ADR-0049).
• Broader settings-driven social providers; per-org override UI polish.

---

Suggested order

1. The session-validation gate (D1 expiry + D3 MFA) — unblocks the rest and is the biggest single piece.
2. D4 session controls (reuses the same authenticated-request seam).
3. D5 IP allowlist (independent — Hono middleware).
4. D6 OIDC trust-list UI.
5. P3 SAML assessment.

Out of scope (separate ADRs): SCIM/provisioning (done — ADR-0071 #2356), passkeys/WebAuthn, a dedicated security-events audit stream.

[os-zhuang]

Session-validation gate infrastructure + password expiry shipped in #2388 (REST surface, enforceAuth). Remaining on this seam: enforced MFA (D3) reuses it (in progress), and the dispatcher/MCP gate path is still TODO.

[os-zhuang]

Enforced MFA (D3) shipped in #2390 — completes the session-validation gate. ADR-0069 P1 is now complete (HIBP / lockout+rate-limit / complexity / history / expiry / MFA). Remaining on this issue: per-org sys_organization.require_mfa, the objectui TOTP-enroll prompt on 403 MFA_REQUIRED, the dispatcher/MCP gate path, and P2/P3.

[os-zhuang]

✅ objectui remediation UI shipped in objectstack-ai/objectui#2037 — the Console now detects 403 MFA_REQUIRED / PASSWORD_EXPIRED and shows a full-screen guided flow (TOTP enrollment with QR + backup codes, or expired-password change), then reloads. Browser-verified end-to-end (enroll → verify real TOTP → gate clears → app loads). Enforced MFA is now usable end-to-end. Remaining: per-org require_mfa, dispatcher/MCP gate path, P2/P3.

[os-zhuang]

✅ Per-org sys_organization.require_mfa + the dispatcher/MCP gate shipped in #2395. Enforced MFA is now complete across all surfaces (global + per-org enforcement; REST/Console gate #2388; dispatcher/MCP gate; objectui remediation UI objectstack-ai/objectui#2037). Remaining on this issue is P2 (session controls / IP allowlist / OIDC trust-list) and P3 (SAML).