stack/docs/requirements/identity-lifecycle.md

Identity Account-Lifecycle Contract

Status: DRAFT — awaiting ratification (webui-audit S2, contract 4 of 9). Authority: PRD D10 (better-auth is the account system of record), Q1 ruled O1 by Jason 2026-08-26 (webui-audit T10). This document turns that ruling into enforceable policy. It also carries the bootstrap/first-admin invariant from issue #1430, folded in here after PR #1431's independent review showed the quick-fix approach was insufficient.

Scope: account creation, bootstrap, federated login, account linking, claim mapping, and deactivation. Out of scope: RBAC grant semantics (contract 2), wizard UX flow (contract 3), hierarchy schema (contract 1).

1. System of record

1. better-auth's tables (users, accounts, sessions, verifications) are the only account system of record. All foreign keys reference users.id.
2. External IdPs (Authentik or any OIDC provider) are login methods, attached through better-auth's generic-OAuth plugin (packages/auth/src/sso.ts). They never own accounts. Removing an IdP removes a login method, not users.
3. The forward-auth perimeter shim is a deployment measure. Once in-app OIDC is configured for a deployment, the shim is demoted: it may stay as network perimeter, but no application code may read identity from its headers.

2. Registration gating

Measured current state on next: emailAndPassword.enabled: true with no gating — anyone who can reach the Gateway can create an account via POST /api/auth/sign-up/email and receives role member.

Contract:

1. A single server-side setting registration_mode with values open | invite | closed. It lives in the database (admin-mutable at runtime), not in env config.
2. Default after bootstrap: closed. The wizard (contract 3) may set it during setup; Enterprise mode defaults to closed with OIDC JIT enabled.
3. closed blocks self-service email/password sign-up. It does not block admin-created users or OIDC JIT (§4), each gated separately.
4. invite requires a single-use, expiring invite token bound to an email address. Invite issuance is an admin operation and is audit-logged.
5. Enforcement point: a better-auth hook (or equivalent middleware executed inside the auth handler path), not a Gateway route guard in front of it — the raw /api/auth/* handler must be incapable of bypassing the gate.

3. Bootstrap / first-admin invariant (from #1430)

Invariant: the system transitions from zero users to one admin user exactly once per bootstrap epoch, atomically, regardless of concurrency or which code path writes users.

Constraints any implementation MUST satisfy (each traces to a verified defect in PR #1431's review, fleet/lanes/webui-audit/findings/pr1431-review.md):

1. All-writer coverage or database enforcement. The invariant must hold against every user-creating path: bootstrap setup, better-auth sign-up, OIDC JIT, and admin creation. An advisory lock taken only in the bootstrap controller does not satisfy this; a concurrent sign-up can commit between the locked count and the admin insert. Acceptable mechanisms: a partial unique index / constraint-backed one-row bootstrap_state table whose transition insert races safely at the database level, or registration_mode enforcement (§2) that provably closes every non-bootstrap writer while the epoch is open.
2. Pool safety. No design may hold a pooled connection inside a transaction while awaiting a write that acquires a second connection from the same pool (DB_POOL_MAX=1 is a supported configuration; better-auth's drizzleAdapter(db) uses the root pool, not the caller's transaction).
3. Re-runnability (D4). Bootstrap is not a one-shot: after the first-admin epoch completes, re-running the wizard reconfigures the system but never re-opens the zero-user transition. "Setup already completed" is a stable, testable state, and factory-reset (a future, explicitly destructive operation) is the only way to open a new epoch.
4. Atomic outcome. The first-admin transition either yields admin user + initial credential/token together or nothing observable. A failure may not strand an admin user without its token such that setup can never retry (the pre-existing failure mode noted in the #1431 review).

4. JIT provisioning (OIDC first login)

1. A successful OIDC login with no matching account creates a user just-in-time only when jit_provisioning is enabled (per-provider flag, default off).
2. JIT users receive role member, never an elevated role, regardless of IdP claims (§5).
3. An optional per-provider email-domain allowlist constrains JIT. Empty allowlist with JIT on means any authenticated subject at that IdP gets an account — permitted, but the wizard must present it as an explicit choice.
4. JIT is disabled while the bootstrap epoch is open (§3.1).

5. Claim mapping

1. Mapped at first login and refreshed at each login: email, email_verified, display name, avatar.
2. Never mapped from IdP claims: role and any future authorization attribute. Authorization lives in the system of record and in the RBAC layer (contract 2). An IdP group/role claim may at most be recorded for audit; it grants nothing.
3. Email change at the IdP does not silently rebind the account (§6.3).

6. Account linking trust

1. Linking an OIDC identity to an existing account happens only in one of two ways: (a) explicit link initiated by the logged-in user from settings, or (b) automatic link when the IdP asserts a verified email exactly matching an existing account and the provider is marked trusted_for_linking (per-provider flag, default off).
2. Untrusted-provider email collision produces a login error naming the conflict, not an auto-link and not a duplicate account.
3. A linked identity whose IdP email later diverges from the account email keeps working (the link is by provider subject id, not email) but the divergence is surfaced in the user's settings and audit log.
4. Unlinking the last login method that the user can actually use is refused unless a password is set first.

7. Deactivation propagation

1. Deactivation (better-auth admin ban) is authoritative and immediate: all sessions for the user are revoked at ban time, and banned users fail every guard, including active websocket sessions, within one heartbeat interval.
2. Deactivation at an external IdP does not propagate automatically in this contract's scope (no SCIM). Operational rule: removing a user from the IdP without banning them in Mosaic leaves any password or other linked login method usable — the admin guide must state this. SCIM/webhook-driven propagation is future work and out of scope here.
3. Deletion is not deactivation. Account deletion semantics (FK fan-out across the 21 referencing tables) are deferred to the custody contract (contract 7 / D14); until ratified, deactivation is the only supported removal operation.

8. Verification requirements

1. The bootstrap invariant (§3) requires a real-PostgreSQL two-connection concurrency test (pattern: apps/gateway/src/agent/connector-lease.postgres.integration.test.ts, runs in the ci-postgres CI step). Mocked-transaction specs are supplementary; they cannot prove serialization.
2. Registration gating (§2) requires spec coverage of all three modes against the raw /api/auth/ handler path, not only against Gateway controllers.
3. Linking (§6) requires specs for: trusted auto-link, untrusted collision error, and last-usable-method unlink refusal.

Ruling request

Ratify sections 1–8 as written, with one decision embedded: registration defaults to closed after bootstrap (§2.2) — say "agreed" or name the mode you want as the default.