feat(auth): session controls — idle / absolute / concurrent (ADR-0069 D4, P2)

[os-zhuang]

ADR-0069 P2 / D4 — session controls: idle timeout, absolute max lifetime, and a concurrent-session cap.

What

Three new auth settings (all 0 = off):

• session_idle_timeout_minutes — sign a user out after inactivity. Enforced in customSession: touches sys_session.last_activity_at (throttled to ~once a minute) and revokes the session once the idle window is exceeded.
• session_absolute_max_hours — cap total session lifetime regardless of refresh; revoked once created_at is older than the cap.
• max_concurrent_sessions_per_user — on sign-in, keep the newest N live sessions and revoke the rest (oldest first).

New sys_session columns back this: last_activity_at, revoked_at, revoke_reason.

Mechanism (no client change)

Revocation expires the session in place (expires_at → past + revoked_at/revoke_reason), so better-auth returns no session on the next request → the Console's existing 401 → login redirect handles it. Idle/absolute run in customSession (the per-request session-validation seam); the concurrent cap runs in the sign-in after-hook.

Note: there is a one-request grace for idle/absolute (the request that trips the limit resolves, then revokes — the next request is rejected). And better-auth garbage-collects expired sessions, so the revoke_reason audit is best-effort; the enforcement (session killed) is not.

ADR-0049

Default-off / additive (no upgrade behavior change); each setting ships with its enforcement. The existing native session.expiresIn/updateAge and /revoke-other-sessions are kept as-is.

Verification

• Unit: plugin-auth 203 + service-settings 129 + platform-objects 63 green; full build incl. strict DTS green. New tests cover idle revoke, absolute revoke, last_activity touch, already-revoked no-op, and concurrent-cap oldest-eviction.
• Live dogfood:
  • Concurrent: cap=2 + 3 sign-ins → the oldest session is revoked (get-session → no user; DB revoke_reason=concurrent_cap), the 2 newest stay alive.
  • Idle: idle=15m with a back-dated last_activity_at → the session is killed on the next request (get-session → no user).

ADR-0069 status

P1 complete; enforced MFA complete across all surfaces (+ Console UI). P2 now adds session controls. Remaining on #2375: P2 IP allowlist + OIDC trust-list UI, and P3 SAML.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
spec	Ready	Preview, Comment	Jun 27, 2026 5:39pm

[github-actions]

📓 Docs Drift Check

This PR changes 3 package(s): @objectstack/platform-objects, @objectstack/plugin-auth, packages/services.

15 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/concepts/implementation-status.mdx (via @objectstack/plugin-auth)
• content/docs/concepts/packages.mdx (via @objectstack/platform-objects, @objectstack/plugin-auth)
• content/docs/concepts/setup-app.mdx (via @objectstack/platform-objects)
• content/docs/getting-started/cli.mdx (via @objectstack/plugin-auth)
• content/docs/guides/auth-sso.mdx (via @objectstack/plugin-auth)
• content/docs/guides/authentication.mdx (via @objectstack/plugin-auth)
• content/docs/guides/kernel-services.mdx (via @objectstack/plugin-auth)
• content/docs/guides/packages.mdx (via @objectstack/platform-objects, @objectstack/plugin-auth, packages/services)
• content/docs/guides/plugins.mdx (via @objectstack/plugin-auth)
• content/docs/guides/production-readiness.mdx (via @objectstack/plugin-auth)
• content/docs/guides/runtime-services/audit-service.mdx (via packages/services)
• content/docs/guides/runtime-services/index.mdx (via packages/services)
• content/docs/guides/runtime-services/settings-service.mdx (via packages/services)
• content/docs/protocol/objectos/i18n-standard.mdx (via packages/services)
• content/docs/releases/v9.mdx (via @objectstack/plugin-auth)

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.