@_mustachio/openauth 0.12.0 → 0.13.0

package/src/ports/CONSISTENCY.md

@@ -15,31 +15,34 @@ overspecifies adapters that don't need that on the read-eventual paths
 
 ## Per-method consistency contracts
 
-| Port           | Method                                                              | Required                                                                                                               | Why                                                                                                                                                                                                                                                                    |
-| -------------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `TokenStore`   | `saveCode(code, payload, ttl)`                                      | **Strong, atomic.** Payload **encrypted at rest** with a key from `KeyStore`; `ttl ≤ 60 s` (framework refuses larger). | Code must be created exactly once and visible to the next `consumeCode` on any node. Payload may carry upstream tokens — see _Code payload confidentiality_ in plan.                                                                                                   |
-| `TokenStore`   | `consumeCode(code)`                                                 | **Strong, CAS.** Returns the **decrypted** payload on success.                                                         | Single-use; second consumption must fail deterministically. Race with itself must resolve to one winner.                                                                                                                                                               |
-| `TokenStore`   | `saveRefresh(refresh, payload)`                                     | **Strong, atomic.**                                                                                                    | New refresh tokens issued during rotation must be immediately retrievable on the next request.                                                                                                                                                                         |
-| `TokenStore`   | `consumeRefresh(refresh, options)`                                  | **Strong, CAS with reuse-detection window** (default 60 s).                                                            | Core of refresh-token rotation security. Concurrent presentations resolve to one winner; reuse within the window triggers the revoke chain.                                                                                                                            |
-| `TokenStore`   | `peekRefresh(refresh)`                                              | **Eventual acceptable.** Non-destructive read; must never mark the token consumed.                                     | Used by `/revoke` for token-to-client binding (RFC 7009 §2.2) and by the refresh-grant for client auth + audit fields. Race losers fall through to `consumeRefresh`, which is the strong gate, so a stale peek can only delay — not bypass — single-use enforcement.   |
-| `TokenStore`   | `revokeFamily(family)`                                              | Strong preferred; eventual acceptable with documented SLA.                                                             | Reuse-detection must invalidate the whole chain. Brief lag is tolerable.                                                                                                                                                                                               |
-| `TokenStore`   | `revokeBySubject(tenant, subject)`                                  | Strong preferred; eventual acceptable with documented SLA.                                                             | Revocation must propagate quickly. A few seconds of lag is tolerable.                                                                                                                                                                                                  |
-| `SessionStore` | `saveFlow(flowId, payload, ttl)`                                    | **Strong, atomic.** `ttl == expiresAt - createdAt`.                                                                    | Flow record must be visible on the callback request to `consumeFlow`.                                                                                                                                                                                                  |
-| `SessionStore` | `updateFlowMethodState(flowId, state)`                              | **Strong, atomic.** Resolves **before** the user-agent redirect is sent.                                               | Upstream PKCE verifier / nonce must be durably persisted before the redirect, otherwise the callback cannot validate.                                                                                                                                                  |
-| `SessionStore` | `consumeFlow(flowId)`                                               | **Strong, atomic delete-on-read** that **returns the full `FlowRecord`** (`CAS` or `DELETE … RETURNING`).              | Single-use; concurrent consumption resolves to one winner. The record is returned so the framework can snapshot fields into the auth-code payload before disposal.                                                                                                     |
-| `SessionStore` | `savePar(uri, payload, ttl)` (optional)                             | **Strong, atomic.** `ttl` default 60 s.                                                                                | RFC 9126 §3 — the PAR record must be visible to the next `consumePar` on any node. One-shot read.                                                                                                                                                                      |
-| `SessionStore` | `consumePar(uri)` (optional)                                        | **Strong, atomic delete-on-read.**                                                                                     | RFC 9126 §4 — `request_uri` is single-use; concurrent presentations of the same uri resolve to one winner. Same semantics as `consumeFlow`.                                                                                                                            |
-| `SessionStore` | `createSession / readSession / revokeSession` (optional long-lived) | **Strong.**                                                                                                            | Session creation must be immediately readable on the next request.                                                                                                                                                                                                     |
-| `SessionStore` | `saveScratch / readScratch / deleteScratch` (optional)              | **Strong, TTL-respecting.** Implement the trio together; partial implementations are not supported.                    | Backs `MethodContext.methodScratch` for methods that need cross-flow per-instance state (e.g. SAML SP assertion-ID replay protection). Keys arrive already namespaced by `(tenantId, methodId)` — the adapter stores opaque key/value pairs.                            |
-| `TokenStore`   | `recordDpopJti(jti, ttlMs)` (optional)                              | **Strong, atomic record-or-fail.**                                                                                     | RFC 9449 §11.1 — replay protection requires single-use enforcement on the jti within the TTL window. A re-presentation must return `invalid_grant` deterministically. Adapters without this method cannot satisfy DPoP and the verifier surfaces `invalid_dpop_proof`. |
-| `KeyStore`     | `currentSigningKey()` / `currentEncryptionKey()`                    | Strong.                                                                                                                | Active key must be unambiguous.                                                                                                                                                                                                                                        |
-| `KeyStore`     | `signingKeys()` (JWKS)                                              | Eventual OK (with TTL).                                                                                                | Verifiers tolerate brief JWKS lag during rotation.                                                                                                                                                                                                                     |
-| `KeyStore`     | `getEncryptionKey(kid)`                                             | Strong.                                                                                                                | Required to decrypt code payloads encrypted under non-current keys during the overlap window.                                                                                                                                                                          |
-| `ConfigStore`  | `getTenantConfig(id)`                                               | **Eventual + bounded staleness (TTL ≤ 60 s).** Invalidation hook fires on update.                                      | Read-heavy, write-rare. Aggressive caching is desirable.                                                                                                                                                                                                               |
-| `ConfigStore`  | `putTenantConfig(config)`                                           | **Strong write + immediate invalidation** of cached entries for the affected `TenantId`.                               | Subsequent `getTenantConfig` must reflect the new value once the write resolves.                                                                                                                                                                                       |
-| `MethodStore`  | `getMethodConfig` / `listMethods`                                   | Same as `ConfigStore.getTenantConfig`.                                                                                 | Subset of tenant config.                                                                                                                                                                                                                                               |
-| `MethodStore`  | `putMethodConfig` / `deleteMethodConfig`                            | Strong write + immediate invalidation.                                                                                 | Console-driven mutations must take effect on the next request.                                                                                                                                                                                                         |
-| `AuditLog`     | `log(event)`                                                        | Append-only, durable. Cross-instance ordering **not** required (consumers sort by `timestamp` + `actor`).              | Loss = audit gap; ordering is a UI / SIEM concern.                                                                                                                                                                                                                     |
+| Port            | Method                                                              | Required                                                                                                               | Why                                                                                                                                                                                                                                                                    |
+| --------------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `TokenStore`    | `saveCode(code, payload, ttl)`                                      | **Strong, atomic.** Payload **encrypted at rest** with a key from `KeyStore`; `ttl ≤ 60 s` (framework refuses larger). | Code must be created exactly once and visible to the next `consumeCode` on any node. Payload may carry upstream tokens — see _Code payload confidentiality_ in plan.                                                                                                   |
+| `TokenStore`    | `consumeCode(code)`                                                 | **Strong, CAS.** Returns the **decrypted** payload on success.                                                         | Single-use; second consumption must fail deterministically. Race with itself must resolve to one winner.                                                                                                                                                               |
+| `TokenStore`    | `saveRefresh(refresh, payload)`                                     | **Strong, atomic.**                                                                                                    | New refresh tokens issued during rotation must be immediately retrievable on the next request.                                                                                                                                                                         |
+| `TokenStore`    | `consumeRefresh(refresh, options)`                                  | **Strong, CAS with reuse-detection window** (default 60 s).                                                            | Core of refresh-token rotation security. Concurrent presentations resolve to one winner; reuse within the window triggers the revoke chain.                                                                                                                            |
+| `TokenStore`    | `peekRefresh(refresh)`                                              | **Eventual acceptable.** Non-destructive read; must never mark the token consumed.                                     | Used by `/revoke` for token-to-client binding (RFC 7009 §2.2) and by the refresh-grant for client auth + audit fields. Race losers fall through to `consumeRefresh`, which is the strong gate, so a stale peek can only delay — not bypass — single-use enforcement.   |
+| `TokenStore`    | `revokeFamily(family)`                                              | Strong preferred; eventual acceptable with documented SLA.                                                             | Reuse-detection must invalidate the whole chain. Brief lag is tolerable.                                                                                                                                                                                               |
+| `TokenStore`    | `revokeBySubject(tenant, subject)`                                  | Strong preferred; eventual acceptable with documented SLA.                                                             | Revocation must propagate quickly. A few seconds of lag is tolerable.                                                                                                                                                                                                  |
+| `SessionStore`  | `saveFlow(flowId, payload, ttl)`                                    | **Strong, atomic.** `ttl == expiresAt - createdAt`.                                                                    | Flow record must be visible on the callback request to `consumeFlow`.                                                                                                                                                                                                  |
+| `SessionStore`  | `updateFlowMethodState(flowId, state)`                              | **Strong, atomic.** Resolves **before** the user-agent redirect is sent.                                               | Upstream PKCE verifier / nonce must be durably persisted before the redirect, otherwise the callback cannot validate.                                                                                                                                                  |
+| `SessionStore`  | `consumeFlow(flowId)`                                               | **Strong, atomic delete-on-read** that **returns the full `FlowRecord`** (`CAS` or `DELETE … RETURNING`).              | Single-use; concurrent consumption resolves to one winner. The record is returned so the framework can snapshot fields into the auth-code payload before disposal.                                                                                                     |
+| `SessionStore`  | `savePar(uri, payload, ttl)` (optional)                             | **Strong, atomic.** `ttl` default 60 s.                                                                                | RFC 9126 §3 — the PAR record must be visible to the next `consumePar` on any node. One-shot read.                                                                                                                                                                      |
+| `SessionStore`  | `consumePar(uri)` (optional)                                        | **Strong, atomic delete-on-read.**                                                                                     | RFC 9126 §4 — `request_uri` is single-use; concurrent presentations of the same uri resolve to one winner. Same semantics as `consumeFlow`.                                                                                                                            |
+| `SessionStore`  | `createSession / readSession / revokeSession` (optional long-lived) | **Strong.**                                                                                                            | Session creation must be immediately readable on the next request.                                                                                                                                                                                                     |
+| `SessionStore`  | `saveScratch / readScratch / deleteScratch` (optional)              | **Strong, TTL-respecting.** Implement the trio together; partial implementations are not supported.                    | Backs `MethodContext.methodScratch` for methods that need cross-flow per-instance state (e.g. SAML SP assertion-ID replay protection). Keys arrive already namespaced by `(tenantId, methodId)` — the adapter stores opaque key/value pairs.                           |
+| `TokenStore`    | `recordDpopJti(jti, ttlMs)` (optional)                              | **Strong, atomic record-or-fail.**                                                                                     | RFC 9449 §11.1 — replay protection requires single-use enforcement on the jti within the TTL window. A re-presentation must return `invalid_grant` deterministically. Adapters without this method cannot satisfy DPoP and the verifier surfaces `invalid_dpop_proof`. |
+| `KeyStore`      | `currentSigningKey()` / `currentEncryptionKey()`                    | Strong.                                                                                                                | Active key must be unambiguous.                                                                                                                                                                                                                                        |
+| `KeyStore`      | `signingKeys()` (JWKS)                                              | Eventual OK (with TTL).                                                                                                | Verifiers tolerate brief JWKS lag during rotation.                                                                                                                                                                                                                     |
+| `KeyStore`      | `getEncryptionKey(kid)`                                             | Strong.                                                                                                                | Required to decrypt code payloads encrypted under non-current keys during the overlap window.                                                                                                                                                                          |
+| `ConfigStore`   | `getTenantConfig(id)`                                               | **Eventual + bounded staleness (TTL ≤ 60 s).** Invalidation hook fires on update.                                      | Read-heavy, write-rare. Aggressive caching is desirable.                                                                                                                                                                                                               |
+| `ConfigStore`   | `putTenantConfig(config)`                                           | **Strong write + immediate invalidation** of cached entries for the affected `TenantId`.                               | Subsequent `getTenantConfig` must reflect the new value once the write resolves.                                                                                                                                                                                       |
+| `MethodStore`   | `getMethodConfig` / `listMethods`                                   | Same as `ConfigStore.getTenantConfig`.                                                                                 | Subset of tenant config.                                                                                                                                                                                                                                               |
+| `MethodStore`   | `putMethodConfig` / `deleteMethodConfig`                            | Strong write + immediate invalidation.                                                                                 | Console-driven mutations must take effect on the next request.                                                                                                                                                                                                         |
+| `AuditLog`      | `log(event)`                                                        | Append-only, durable. Cross-instance ordering **not** required (consumers sort by `timestamp` + `actor`).              | Loss = audit gap; ordering is a UI / SIEM concern.                                                                                                                                                                                                                     |
+| `ScimDirectory` | `createUser` / `replaceUser` / `patchUser` / `deleteUser`           | **Strong, read-your-writes.**                                                                                          | A SCIM client issues `GET /Users?filter=userName eq "…"` immediately after a create to confirm it; an eventually-consistent read there makes the client create the user a second time. Duplicate users are the classic SCIM failure and are painful to unpick.         |
+| `ScimDirectory` | `getUser` / `findUsers`                                             | **Read-your-writes for the tenant's own recent writes**; otherwise eventual is acceptable.                             | Same reason. Cross-tenant staleness is harmless — SCIM reads are always tenant-scoped.                                                                                                                                                                                 |
+| `ScimDirectory` | uniqueness of `userName`                                            | **Host-enforced.** Return `authError.conflict(...)` on collision.                                                      | The library stores no user rows, so it cannot enforce uniqueness. A host that checks-then-writes without a constraint will race under Okta's initial import, which is heavily concurrent.                                                                              |
 
 ## Implications for adapter choice
 

package/src/ports/scim-directory.ts

@@ -0,0 +1,166 @@
+/**
+ * `ScimDirectory` — the host's user directory, as SCIM needs to see it.
+ *
+ * This is the boundary from `SCIM-AD2`: the library owns the SCIM
+ * protocol (routing, bearer auth, schema validation, PATCH
+ * normalization, error envelope, pagination, discovery docs) and the
+ * host owns every byte of persistence. The library stores no user data.
+ *
+ * That split is not a compromise — it is the same protocol-over-
+ * host-owned-state shape as `ConfigStore`, `MethodStore` and the
+ * `success` callback. The host's Users table is the host's.
+ *
+ * **Consistency:** read-your-writes is required. A SCIM client
+ * (notably Okta) will `GET /Users?filter=userName eq "…"` immediately
+ * after a `POST /Users` to confirm the create; an eventually-consistent
+ * read there produces duplicate users. See `ports/CONSISTENCY.md`.
+ *
+ * **Errors.** SCIM clients retry `5xx` and give up on `4xx`, so which
+ * error you return decides whether a failure is surfaced to an admin or
+ * retried forever:
+ *
+ *   - `authError.conflict(...)` → `409 uniqueness`. A collision only you
+ *     can detect, because only you store the rows.
+ *   - `authError.invalidRequest(...)` → `400 invalidValue`. A
+ *     **permanent** rejection — you understood the request and will
+ *     never accept it. Use it when `addMembers` names a user you do not
+ *     have (an IdP's group push can reference a member its user push
+ *     filtered out, or one deleted between operations), or when the data
+ *     violates a constraint you cannot satisfy.
+ *   - anything else → `500`, which the client retries. Correct for a
+ *     transient fault, and far better than reporting a success you did
+ *     not perform — but returning it for a permanent problem means the
+ *     IdP retries the same doomed request indefinitely.
+ *
+ * Your message is passed through on both `4xx` paths; it is what an IdP
+ * admin reads in the provisioning log, so make it specific.
+ */
+import type { Result } from "../types/result"
+import type {
+  ScimGroupPatch,
+  ScimGroupQuery,
+  ScimGroupRecord,
+  ScimGroupWrite,
+  ScimPage,
+  ScimUserPatch,
+  ScimUserQuery,
+  ScimUserRecord,
+  ScimUserWrite,
+} from "../types/scim"
+import type { TenantId } from "../types/tenant"
+
+export type ScimDirectory = {
+  /** `null` (not an error) when no user has that id in this tenant. */
+  getUser(
+    tenantId: TenantId,
+    id: string,
+  ): Promise<Result<ScimUserRecord | null>>
+
+  /**
+   * Query users. `query.startIndex` is 1-based and `query.count` is
+   * already clamped; `query.totalResults` in the response must be the
+   * full match count, not the page length.
+   */
+  findUsers(
+    tenantId: TenantId,
+    query: ScimUserQuery,
+  ): Promise<Result<ScimPage<ScimUserRecord>>>
+
+  /**
+   * Create a user. Return `conflict` if `userName` (or another
+   * uniqueness constraint of yours) is already taken — the library
+   * cannot check that for you.
+   */
+  createUser(
+    tenantId: TenantId,
+    user: ScimUserWrite,
+  ): Promise<Result<ScimUserRecord>>
+
+  /**
+   * Full replace (`PUT`). Attributes absent from `user` are cleared, per
+   * RFC 7644 §3.5.1 — this is a replace, not a merge. Use `patchUser`
+   * for partial updates.
+   */
+  replaceUser(
+    tenantId: TenantId,
+    id: string,
+    user: ScimUserWrite,
+  ): Promise<Result<ScimUserRecord>>
+
+  /**
+   * Apply a normalized delta. Present key ⇒ set; absent ⇒ leave alone;
+   * `null` ⇒ clear. The library has already resolved SCIM path
+   * expressions, so no parsing is needed here.
+   *
+   * `{ active: false }` is the ordinary deprovisioning signal and is
+   * usually the single most important operation to implement correctly.
+   */
+  patchUser(
+    tenantId: TenantId,
+    id: string,
+    patch: ScimUserPatch,
+  ): Promise<Result<ScimUserRecord>>
+
+  /**
+   * Hard delete (`DELETE`). Distinct from deactivation on purpose
+   * (`SCIM-AD8`): the library will not quietly turn a destructive
+   * request into a soft one. Hosts that do not want cascading deletes
+   * should implement this as a tombstone and say so in their runbook —
+   * but that decision is theirs to make explicitly, not the library's to
+   * make silently.
+   */
+  deleteUser(tenantId: TenantId, id: string): Promise<Result<void>>
+
+  // ─── Groups ───
+  //
+  // Optional as a set: a host that only needs user provisioning can omit
+  // all six, and `/scim/v2/Groups` then answers 501 instead of failing
+  // at runtime. Implement all of them or none — a half-implemented
+  // Groups surface fails an IdP's group push in confusing ways.
+
+  getGroup?(
+    tenantId: TenantId,
+    id: string,
+  ): Promise<Result<ScimGroupRecord | null>>
+
+  /**
+   * `query.excludeMembers` is set when the client asked for
+   * `excludedAttributes=members`. Honour it by not loading membership —
+   * Okta sets it while enumerating groups, and ignoring it turns a cheap
+   * listing into a fan-out read per group.
+   */
+  findGroups?(
+    tenantId: TenantId,
+    query: ScimGroupQuery,
+  ): Promise<Result<ScimPage<ScimGroupRecord>>>
+
+  createGroup?(
+    tenantId: TenantId,
+    group: ScimGroupWrite,
+  ): Promise<Result<ScimGroupRecord>>
+
+  /** Full replace, including membership. */
+  replaceGroup?(
+    tenantId: TenantId,
+    id: string,
+    group: ScimGroupWrite,
+  ): Promise<Result<ScimGroupRecord>>
+
+  /**
+   * Apply a normalized group delta.
+   *
+   * Exactly one membership shape arrives at a time: `members` (replace
+   * everything) or `addMembers` / `removeMembers` (incremental). The
+   * incremental form exists so a 20,000-member group does not have to be
+   * read and rewritten to add one person — see `SCIM-AD9`. Adding an
+   * existing member or removing an absent one must succeed quietly;
+   * IdPs retry and expect idempotence.
+   */
+  patchGroup?(
+    tenantId: TenantId,
+    id: string,
+    patch: ScimGroupPatch,
+  ): Promise<Result<ScimGroupRecord>>
+
+  deleteGroup?(tenantId: TenantId, id: string): Promise<Result<void>>
+}

package/src/ports/session-store.ts

@@ -122,11 +122,7 @@ export type SessionStore = {
    * `MethodContext.methodScratch` at call time. Implement all three
    * methods together — partial implementations are not supported.
    */
-  saveScratch?(
-    key: string,
-    value: string,
-    ttlMs: number,
-  ): Promise<Result<void>>
+  saveScratch?(key: string, value: string, ttlMs: number): Promise<Result<void>>
   readScratch?(key: string): Promise<Result<string>>
   deleteScratch?(key: string): Promise<Result<void>>
 }

package/src/types/error.ts

@@ -50,6 +50,12 @@ export type AuthError =
   // endpoints. Use for control-flow signalling that should never escape to a
   // standards-compliant client.
   | { code: "internal_error"; description: string; cause?: unknown }
+  // Uniqueness / state conflict. Raised by hosts from `ScimDirectory`
+  // when a create or update collides with an existing record — only the
+  // host can know, since only the host stores the rows. The SCIM layer
+  // renders it as `409` with `scimType: "uniqueness"`. It has no OAuth
+  // endpoint mapping and should never reach one.
+  | { code: "conflict"; description: string; attribute?: string }
   // RFC 9449 §5.2 — DPoP proof verification failed (bad signature, htm/htu
   // mismatch, iat outside window, replayed jti, missing/mismatched cnf.jkt).
   // Returned as a 400 with `error="invalid_dpop_proof"` on form-body
@@ -130,6 +136,11 @@ export const authError = {
     code: "invalid_target",
     description,
   }),
+  conflict: (description: string, attribute?: string): AuthError => ({
+    code: "conflict",
+    description,
+    ...(attribute !== undefined ? { attribute } : {}),
+  }),
   internalError: (description: string, cause?: unknown): AuthError => ({
     code: "internal_error",
     description,

package/src/types/idp.ts

@@ -7,6 +7,7 @@ import type { AuditLog } from "../ports/audit-log"
 import type { ConfigStore } from "../ports/config-store"
 import type { KeyStore } from "../ports/key-store"
 import type { MethodStore } from "../ports/method-store"
+import type { ScimDirectory } from "../ports/scim-directory"
 import type { SessionStore } from "../ports/session-store"
 import type { TokenStore } from "../ports/token-store"
 
@@ -280,6 +281,17 @@ export type IdPOptions = {
   auditLog?: AuditLog
   /** Optional — falls back to `ConfigStore` for `MethodConfig` lookups. */
   methodStore?: MethodStore
+  /**
+   * The host's user directory, as SCIM needs to see it. Supply it to
+   * serve `/scim/v2/*`; omit it and those routes answer 501 regardless
+   * of per-tenant config.
+   *
+   * The library owns the SCIM protocol and stores no user data — every
+   * read and write goes through this port to the host's own tables. See
+   * `SCIM-AD2` in `docs/plans/claude/scim-plan.md` and
+   * `INTEGRATION.md` § SCIM.
+   */
+  scimDirectory?: ScimDirectory
 
   /** Issuer URL. Function form lets multi-tenant deployments derive it per request. */
   issuerUrl: string | ((req: Request) => string)

package/src/types/scim.ts

@@ -0,0 +1,280 @@
+/**
+ * SCIM 2.0 — public types.
+ *
+ * The library is the SCIM **Service Provider** (the system being
+ * provisioned into); corporate IdPs are the SCIM clients. Inbound only —
+ * we never originate provisioning traffic. See `SCIM-AD1` in
+ * `docs/plans/claude/scim-plan.md`.
+ *
+ * These types are the whole contract between the library's protocol
+ * layer and the host's data layer. No SCIM JSON shape, path expression,
+ * or filter string reaches the host: it receives validated, normalized
+ * values and returns records. See `SCIM-AD2`.
+ *
+ * Plain TypeScript, no third-party types, no Node APIs — SCIM is JSON
+ * over HTTP, so unlike SAML this surface lives on the root entry and
+ * stays edge-clean.
+ */
+
+/** RFC 7643 §4.1.2 — a multi-valued attribute entry. */
+export type ScimMultiValue = {
+  value: string
+  /** e.g. `"work"` / `"home"` / `"mobile"`. */
+  type?: string
+  /** At most one entry per attribute should be primary. */
+  primary?: boolean
+}
+
+/** RFC 7643 §4.1.1 — the `name` complex attribute. */
+export type ScimName = {
+  formatted?: string
+  familyName?: string
+  givenName?: string
+  middleName?: string
+  honorificPrefix?: string
+  honorificSuffix?: string
+}
+
+/**
+ * RFC 7643 §4.3 — the enterprise user extension
+ * (`urn:ietf:params:scim:schemas:extension:enterprise:2.0:User`).
+ * Okta and Entra both populate parts of this; `department` and
+ * `manager` are the ones hosts usually care about.
+ */
+export type ScimEnterpriseUser = {
+  employeeNumber?: string
+  costCenter?: string
+  organization?: string
+  division?: string
+  department?: string
+  /** `manager.value` is the manager's SCIM `id`. */
+  manager?: { value?: string; displayName?: string }
+}
+
+/**
+ * A user as the **host** stores it. Returned from every `ScimDirectory`
+ * read and write.
+ *
+ * `id` is the host's stable identifier and becomes the SCIM resource id
+ * in URLs — it must be opaque, stable, and URL-safe.
+ *
+ * `externalId` is the **IdP's** identifier for the same person. It is
+ * what reconciliation depends on in practice (a user can change
+ * `userName`; `externalId` survives), so hosts should persist and index
+ * it even though SCIM marks it optional.
+ */
+export type ScimUserRecord = {
+  id: string
+  externalId?: string
+  userName: string
+  /** `false` is the normal deprovisioning signal — see `SCIM-AD8`. */
+  active: boolean
+  name?: ScimName
+  displayName?: string
+  emails?: ScimMultiValue[]
+  phoneNumbers?: ScimMultiValue[]
+  enterprise?: ScimEnterpriseUser
+  /** Unix ms. Surfaced as `meta.created` when present. */
+  createdAt?: number
+  /** Unix ms. Surfaced as `meta.lastModified` when present. */
+  updatedAt?: number
+}
+
+/**
+ * A validated create / replace payload. Same shape as a record minus
+ * the host-assigned `id` and timestamps.
+ *
+ * `active` is always present: SCIM defaults it to `true` on create, and
+ * resolving that default in the library rather than the host keeps the
+ * semantics in one place.
+ *
+ * Note there is no `password` field, deliberately — see `SCIM-AD1`
+ * non-goals. A `password` in the payload is refused, not silently
+ * dropped.
+ */
+export type ScimUserWrite = {
+  externalId?: string
+  userName: string
+  active: boolean
+  name?: ScimName
+  displayName?: string
+  emails?: ScimMultiValue[]
+  phoneNumbers?: ScimMultiValue[]
+  enterprise?: ScimEnterpriseUser
+}
+
+/**
+ * A **normalized** PATCH delta (`SCIM-AD6`).
+ *
+ * The library resolves `urn:ietf:params:scim:api:messages:2.0:PatchOp`
+ * operations — including path expressions like
+ * `emails[type eq "work"].value` and the different shapes Okta and Entra
+ * emit for the same intent — into this flat delta. The host never parses
+ * a SCIM path.
+ *
+ * Present key ⇒ set to that value. Absent key ⇒ leave untouched.
+ * `null` ⇒ the attribute was removed and should be cleared.
+ */
+export type ScimUserPatch = {
+  externalId?: string | null
+  userName?: string
+  active?: boolean
+  name?: ScimName | null
+  displayName?: string | null
+  emails?: ScimMultiValue[] | null
+  phoneNumbers?: ScimMultiValue[] | null
+  enterprise?: ScimEnterpriseUser | null
+}
+
+/**
+ * Attributes the filter subset may reference (`SCIM-AD3`).
+ *
+ * `emails.value` is the normalized form of the complex path Entra emits
+ * (`emails[type eq "work"].value`) — the host matches on any email
+ * value and need not model the `type` qualifier.
+ */
+export type ScimFilterAttribute =
+  | "id"
+  | "userName"
+  | "externalId"
+  | "active"
+  | "emails.value"
+  /** Groups only. */
+  | "displayName"
+
+/**
+ * The parsed filter, as a small typed tree. The host never receives the
+ * raw filter string — parsing is the library's job, and an expression
+ * outside the supported subset is rejected with `400 invalidFilter`
+ * before the port is called.
+ */
+export type ScimFilter =
+  | { op: "eq"; attribute: ScimFilterAttribute; value: string | boolean }
+  | { op: "and"; left: ScimFilter; right: ScimFilter }
+
+/** Input to `ScimDirectory.findUsers`. */
+export type ScimUserQuery = {
+  /** Absent ⇒ unfiltered list. */
+  filter?: ScimFilter
+  /**
+   * **1-based**, per RFC 7644 §3.4.2.4 — not zero. Already clamped to
+   * `>= 1` by the library.
+   */
+  startIndex: number
+  /** Page size, already clamped to the connection's configured maximum. */
+  count: number
+}
+
+/**
+ * One page of results. `totalResults` is the count of everything
+ * matching the filter, not the size of `resources` — SCIM clients use it
+ * to drive pagination, so a host that returns the page size here will
+ * make Okta loop or stop early.
+ */
+export type ScimPage<T> = {
+  resources: T[]
+  totalResults: number
+}
+
+/**
+ * One group membership entry. `value` is the member's SCIM `id` — for
+ * us always a User id, since we do not support nested groups.
+ */
+export type ScimGroupMember = {
+  value: string
+  /** Human label the IdP supplied. Advisory; not authoritative. */
+  display?: string
+}
+
+/** A group as the **host** stores it. */
+export type ScimGroupRecord = {
+  id: string
+  externalId?: string
+  displayName: string
+  /**
+   * Omit when the caller asked for `excludedAttributes=members`, which
+   * Okta does while enumerating groups. Distinguish "not requested"
+   * (omit) from "no members" (`[]`) — returning `[]` for the former
+   * tells the client the group was emptied.
+   */
+  members?: ScimGroupMember[]
+  /** Unix ms → `meta.created`. */
+  createdAt?: number
+  /** Unix ms → `meta.lastModified`. */
+  updatedAt?: number
+}
+
+/** A validated group create / replace payload. */
+export type ScimGroupWrite = {
+  externalId?: string
+  displayName: string
+  /** Full membership for a create or replace. */
+  members?: ScimGroupMember[]
+}
+
+/**
+ * A normalized group PATCH.
+ *
+ * Membership is handled differently from every user attribute, and
+ * deliberately so (`SCIM-AD9`). For a user, the library resolves a
+ * targeted patch into the complete new value because the lists involved
+ * are small and bounded. Group membership is neither: resolving
+ * "add one member" against a 20,000-member group would mean reading all
+ * 20,000 rows and handing them back on every single change.
+ *
+ * So the client's *intent* is preserved instead. `addMembers` /
+ * `removeMembers` are incremental and let the host issue one insert or
+ * delete; `members` is a full replacement. They are mutually exclusive
+ * — the library never emits `members` alongside either incremental
+ * field, so a host can branch on which is present without ordering
+ * concerns.
+ */
+export type ScimGroupPatch = {
+  displayName?: string
+  externalId?: string | null
+  /** Replace the entire membership with exactly these members. */
+  members?: ScimGroupMember[]
+  /** Add these members, leaving existing ones alone. Idempotent. */
+  addMembers?: ScimGroupMember[]
+  /** Remove these member ids. Removing a non-member is not an error. */
+  removeMembers?: string[]
+}
+
+/** Input to `ScimDirectory.findGroups`. */
+export type ScimGroupQuery = {
+  filter?: ScimFilter
+  /** 1-based. */
+  startIndex: number
+  count: number
+  /**
+   * `true` when the client sent `excludedAttributes=members`. The host
+   * may skip loading membership entirely — Okta sets this while
+   * enumerating groups, and honouring it is the difference between a
+   * cheap listing and a fan-out read per group.
+   */
+  excludeMembers: boolean
+}
+
+/**
+ * Per-tenant SCIM connection config, carried on `TenantConfig.scim`.
+ *
+ * SCIM is not an `AuthMethod` — no `/authorize`, no flow, no user agent
+ * — so it is tenant-level config rather than a `MethodConfig`
+ * (`SCIM-AD5`).
+ */
+export type ScimConfig = {
+  /** `false` (or absent config) ⇒ `/scim/v2/*` responds 403 for this tenant. */
+  enabled: boolean
+  /**
+   * Hash of the bearer token issued to the IdP, produced with
+   * `hashClientSecret` — the same treatment as
+   * `ClientConfig.secretHash`. Never store the raw token.
+   */
+  tokenHash: string
+  /**
+   * Largest page this connection will return, whatever the client asks
+   * for. Defaults to 100; hard-capped at 500 so a hostile or
+   * misconfigured `count` cannot ask the host for an unbounded read.
+   */
+  maxPageSize?: number
+}

package/src/types/tenant.ts

@@ -11,6 +11,7 @@
  * providers carries only `{ tenantId, flowId, nonce, kid }`. Everything else
  * lives in the server-side `FlowRecord` (see `./flow.ts`).
  */
+import type { ScimConfig } from "./scim"
 
 /**
  * Branded tenant id — **opaque to the framework**.
@@ -199,6 +200,15 @@ export type TenantConfig = {
   refreshTtl?: number
   /** Override default access-token TTL (seconds). */
   accessTtl?: number
+  /**
+   * SCIM 2.0 provisioning for this tenant. Absent or `enabled: false` ⇒
+   * `/scim/v2/*` answers 403 for this tenant.
+   *
+   * Tenant-level rather than a `MethodConfig` because SCIM is not an
+   * auth method — no `/authorize`, no flow, no user agent. See
+   * `SCIM-AD5` in `docs/plans/claude/scim-plan.md`.
+   */
+  scim?: ScimConfig
 }
 
 /**