@happyvertical/smrt-users 0.39.14 → 0.39.16

package/AGENTS.md

@@ -6,7 +6,7 @@ Multi-tenant user management with RBAC, hierarchical tenants, session handling,
 
 | Model | Key Pattern |
 |-------|-------------|
-| User | Auth identity. `profileId` is plain string (not FK) to smrt-profiles. Email auto-lowercased. |
+| User | Auth identity. `profileId` is a unique cross-package reference to smrt-profiles (one User per non-null Profile). Email auto-lowercased; readonly nullable unique `emailKey` is derived on save for durable normalized uniqueness. |
 | AccessRequest | "Request access / waitlist" record captured before a `User` exists. CLOSED generated surface (`api`/`mcp`/`cli` = `[]`) — all access via `AccessRequestService`. Email normalized + indexed; JSON `requestContext` (NOT `context` — reserved for slug scoping). |
 | Tenant | **STI** + hierarchical parent-child. `hierarchyPath` (materialized path), `hierarchyLevel`. Max depth 10. |
 | Session | Server-side. Secure UUID. TTL in **seconds** (not ms). Status auto-updates to EXPIRED on access. |
@@ -240,6 +240,65 @@ the package root).
   refuses to provision a user when the IdP explicitly returns
   `email_verified: false` (opt out with `{ allowUnverifiedEmail: true }`). An
   absent claim makes no assertion and is not enforced.
+- **Verified-email Profile reuse is fail-closed.** The typed canonical scenarios
+  live in
+  `packages/profiles/src/testing/oidcProvisioningDecisionMatrix.ts`; both
+  package suites execute that matrix and public docs reference it rather than
+  maintaining another behavioral table. Default provisioning reuses only one
+  unowned, global `Person`. Tenant-scoped, non-Person, duplicate-email,
+  and already-owned matches fail before User/session creation. An existing
+  issuer/subject link without a User must still be the unique global Person for
+  the current verified claim email; once owned, the stable issuer/subject link
+  reuses its canonical Person and owner.
+  Issuer and subject are opaque, case-sensitive identifiers; preserve their
+  exact value and use trim only to reject blank claims.
+- **`resolveProfile` is the application reconciliation boundary.** The
+  SvelteKit handlers, `OidcLoginService`, and `getOrCreateFromOidc` accept the
+  same hook inside the provisioning transaction. The service/handler path
+  supplies protocol-validated claims; direct collection callers must validate
+  and trust their claim source before calling `getOrCreateFromOidc`.
+  Token/userinfo merging keeps `email` and `email_verified` paired to the same
+  claim source; verification is never borrowed across sources.
+  Resolver reads/writes use the supplied `db`, and the hook must be idempotent
+  because a concurrent unique-key conflict can retry it. `undefined` chooses
+  the secure default and `null` rejects, including exact issuer/subject reuse.
+  For a new identity, a supplied Profile is still validated as the unique,
+  unowned global Person for the verified email. For an exact existing identity,
+  it must be the already-linked Profile and cannot rebind identity authority;
+  stable-link owner and canonical-Person checks still apply. The hook receives a
+  separate frozen claims snapshot; internal retry and persistence state is not
+  exposed for mutation.
+- **OIDC first login is atomic.** The Profile, `OidcIdentity`, and User are one
+  transaction. The database arbiters are `OidcIdentity.identityKey`,
+  private `oidc_profile_email_reservations.email_key`, `User.emailKey`, and the
+  unique `User.profileId`; local callbacks acquire exact issuer/subject and normalized
+  email locks in deterministic order so changed email claims also serialize.
+  SQLite and DuckDB callbacks additionally serialize transactions per database
+  URL because one adapter cannot safely overlap unrelated root transactions;
+  PostgreSQL deadlock and serialization errors use a bounded transaction retry.
+  Newly provisioned Profiles use non-semantic per-profile slugs so equal IdP
+  display names cannot trigger a natural-key upsert;
+  run
+  `smrt db:status`, `smrt db:migrate`, then `smrt db:status` before deployment.
+  Stop or upgrade old writers first. Before migration, group
+  non-null `users.profile_id` values, then reconcile duplicates. After
+  migration, run public `backfillProfileEmailKeys(db)` followed by
+  `backfillUserEmailKeys(db)` from one deploy process. Both use the shared
+  TypeScript `normalizeIdentityEmail()` implementation transactionally and are
+  idempotent; the User backfill fails before writes if normalized duplicates
+  remain. Every OIDC path requires the Profile email-key readiness marker;
+  creating a User or checking User email uniqueness additionally requires the
+  User marker. A stable issuer/subject with an existing owning User skips only
+  the User email-key lookup and marker. Full scans remain in the explicit deploy
+  step; guarded runtime paths use indexed keys and validate only returned
+  candidates. Multiple null links remain valid.
+  Legacy race keys backfill only after canonical validation. Pass a root
+  database on adapters such as DuckDB that cannot create nested savepoints.
+  Root adapters must expose `beginTransaction`; transaction-only handles are
+  ambiguous and fail closed before provisioning writes. Caller-owned
+  transactions never run `_smrt_backfills` DDL and require that table to
+  already exist; use the root database when initialization or recovery is
+  needed.
 
 ## Gotchas
 

package/README.md

@@ -374,6 +374,137 @@ can pass `transactionCookieSecret` to the route helpers. On success it creates
 or reuses a SMRT `Profile`, links an `OidcIdentity`, creates or reuses a `User`,
 records `lastLoginAt`, and sets the standard SMRT session cookie.
 
+The typed [OIDC provisioning decision matrix](../profiles/src/testing/oidcProvisioningDecisionMatrix.ts)
+is the canonical behavior contract shared with Profiles. Its executable rows
+declare exact reuse and new-identity outcomes, resolver invocation and
+rebinding, ownership/collision failures, readiness, retries, adapter support,
+public errors, and permitted Profile/OIDC identity/User/session creation. For a
+new identity, the Users path is deliberately fail-closed before User or session
+creation unless the selected Profile is the one safe, unowned global `Person`
+allowed by that matrix. An exact issuer/subject link may instead continue to
+its already-owned canonical global `Person`, but it cannot be rebound.
+
+Canonical Profile failures use `CanonicalPersonProfileError` from
+`@happyvertical/smrt-profiles`, with codes `ambiguous_email`, `email_mismatch`,
+`email_key_backfill_required`, `missing_profile`, `non_person`,
+`reservation_conflict`, or `tenant_scoped`.
+User ownership/provisioning failures use `OidcProvisioningError`, with codes
+`ambiguous_identity`, `concurrency_conflict`, `profile_owned`, `rejected`,
+`transaction_required`, `user_email_backfill_required`, or
+`user_email_conflict`. `completeOidcLogin()` rejects with the full error. The
+ready-made callback handler passes that error to a configured `failureRedirect`
+callback; without one it returns a generic 401 and does not expose account,
+resolver, or database details to the browser.
+
+Applications that already own an identity-reconciliation policy can provide a
+`resolveProfile` hook without replacing transaction cookies, token exchange,
+claim verification, or session creation:
+
+```typescript
+// src/routes/auth/[provider]/callback/+server.ts
+import { createOidcCallbackHandler } from '@happyvertical/smrt-users/sveltekit';
+
+export const GET = createOidcCallbackHandler({
+  db: { type: 'postgres', url: process.env.DATABASE_URL! },
+  resolveProfile: async ({ claims, db }) => {
+    // All reads and writes must use this transaction-bound `db` handle.
+    const profile = await resolveApplicationIdentity({ claims, db });
+
+    // undefined: use SMRT's secure default
+    // null: reject this login
+    // Profile: select an application-reconciled canonical global Person
+    return profile;
+  },
+  successRedirect: '/dashboard',
+});
+```
+
+The service and SvelteKit handler run the hook after protocol claim validation
+and inside the same provisioning transaction as OIDC identity and User
+creation. Direct `UserCollection.getOrCreateFromOidc()` callers must first
+validate and trust their supplied claims. The hook may run again after a
+concurrent unique-key conflict, so it must be idempotent. For a new
+issuer/subject, a supplied Profile is still validated as the unique, unowned
+global `Person` for a verified email; resolver reuse is rejected unless
+`email_verified` is exactly `true`. For an exact existing issuer/subject,
+`null` still rejects login, a supplied Profile must be the already-linked
+Profile and cannot rebind it, and stable-link owner/canonical-Person checks
+still apply. The resolver receives a separate frozen claims snapshot; retry
+locks, identity lookups, and persistence retain SMRT's immutable internal
+snapshot.
+
+When userinfo supplies a missing email, its `email_verified` value travels with
+that email as one source-bound pair. SMRT never borrows a verification flag
+from the ID token for a userinfo address, or from userinfo for an ID-token
+address.
+
+The concurrency guarantee uses four database arbiters: nullable unique
+`OidcIdentity.identityKey`, private unique
+`oidc_profile_email_reservations.email_key`, nullable unique `User.emailKey`,
+and unique `User.profileId`. `User.emailKey` is derived from the trimmed,
+lowercase email on every save, preventing independent database connections from
+creating ambiguous User rows for the same address. Profile and User keys share
+the exported TypeScript `normalizeIdentityEmail()` implementation; identity
+lookups never depend on adapter-specific SQL `lower()` or `trim()` behavior.
+Before trusting those keys, identity lookup verifies that every stored key
+on a returned candidate still equals the application-normalized source email.
+Every OIDC path validates or synchronizes its canonical Profile and therefore
+requires the Profile email-key readiness marker. Creating a User or checking
+User email uniqueness additionally requires the User email-key marker. A stable
+issuer/subject that already has an owning User skips only the User email-key
+lookup and marker. Full table validation stays in the explicit backfill, while
+guarded runtime paths use only indexed candidate rows.
+In-process callbacks also acquire the exact issuer/subject and normalized email
+locks in deterministic order, including when the same subject presents changed
+email claims on independent database handles. SQLite and DuckDB also acquire a
+database-URL transaction lock because one adapter cannot safely overlap
+unrelated root transactions; PostgreSQL deadlock and serialization failures use
+a bounded transaction retry. New OIDC Profiles use non-semantic unique slugs,
+so equal IdP display names cannot overwrite one another through SMRT's
+natural-key upsert.
+Existing installations must run `smrt db:status`, `smrt db:migrate`, then
+`smrt db:status` before deploying this users version; legacy identities reserve
+an address only after the Profile passes canonical validation, and existing
+issuer/subject reuse synchronizes that reservation with the Profile's current
+stored email. Stop or upgrade old Profile and User writers before migration.
+Before migration, find duplicate ownership links:
+
+```sql
+SELECT profile_id, COUNT(*) AS user_count
+FROM users
+WHERE profile_id IS NOT NULL
+GROUP BY profile_id
+HAVING COUNT(*) > 1;
+```
+
+Reconcile every result before applying the unique Profile constraint; legacy
+empty-string Profile placeholders should be normalized to `NULL`. Multiple
+`NULL` links remain valid. After the schema migration, populate both durable
+keys from a single deploy process:
+
+```typescript
+import { backfillProfileEmailKeys } from '@happyvertical/smrt-profiles';
+import { backfillUserEmailKeys } from '@happyvertical/smrt-users';
+
+await backfillProfileEmailKeys(database);
+await backfillUserEmailKeys(database);
+```
+
+The supported backfills are transactional and idempotent. The User backfill
+fails without changing rows if legacy emails are still ambiguous; reconcile
+the reported normalized keys and rerun it. All OIDC paths require the Profile
+marker; paths that create a User or arbitrate User email uniqueness also require
+the User marker. Run both before enabling OIDC provisioning. Pass the
+root database to provisioning on adapters such as DuckDB that do not support
+nested savepoints; root adapters must expose `beginTransaction`. A handle
+exposing only `transaction()` is ambiguous and fails closed before resolver
+writes rather than risking a nested transaction that could roll back
+caller-owned work. A transaction-bound handle reads an existing
+`_smrt_backfills` table but never attempts tracker DDL; pass the root database
+when initialization or recovery is needed. OIDC `iss` and `sub` are preserved as exact opaque,
+case-sensitive identifiers (trim is used only to reject blank claims), so
+whitespace-distinct subjects never reuse one another.
+
 With `postgresRls: true`, SMRT opens a request-scoped Postgres transaction,
 loads the session, resolves permissions, and sets session variables used by the
 generated RLS helpers:
@@ -447,7 +578,7 @@ TenantService supports three modes: `flexible` (no auto-create), `personal` (aut
 
 | Export | Description |
 |--------|-------------|
-| `User` | Auth identity. Email auto-lowercased. `profileId` links to smrt-profiles (plain string). |
+| `User` | Auth identity. Email auto-lowercased. `profileId` is a unique cross-package Profile reference (one User per non-null Profile). |
 | `Tenant` | Organizational boundary. STI. Hierarchical via `parentTenantId`/`hierarchyPath`. |
 | `Role` | Permission template. `tenantId = null` for system roles. `isSystem` blocks deletion. |
 | `Permission` | Named capability. Slug format: `resource.action`. |
@@ -480,6 +611,9 @@ TenantService supports three modes: `flexible` (no auto-create), `personal` (aut
 | `generatePostgresPermissionSql()`, `applyPostgresPermissionPolicies()` | Preview or apply Postgres RLS helper functions and table policies. |
 | `SessionService` | High-level session management. `createSession()`, `loadSessionContext()`, `destroySession()`. |
 | `OidcLoginService` | Generic OIDC authorization-code login with PKCE for Kanidm, Dex, and other standards-compliant providers. |
+| `backfillUserEmailKeys` | Idempotently populate durable normalized-email keys after migrating legacy Users; fails closed on duplicates. |
+| `OidcProfileResolver` | Transaction-bound pre-provision hook for application identity reconciliation. |
+| `NormalizedOidcClaims` | Frozen resolver claims with required normalized `email`. |
 | `withSessionPermissionContext()` | Loads a session, optionally enters tenancy context, and exposes a request-scoped database/permission context. |
 | `getCurrentSessionPermissionContext()`, `getRequestScopedDatabase()` | Read the active request/session context inside app code. |
 | `TenantService` | Policy-driven tenant lifecycle. `ensureTenantForUser()`, `createTenantWithOwnership()`. |