@_mustachio/openauth 0.12.0 → 0.13.1

package/src/methods/saml-sp/types.ts

@@ -25,10 +25,7 @@
  *   - `unspecified`    — IdP picks; pass through verbatim.
  */
 export type SamlNameIdFormat =
-  | "persistent"
-  | "transient"
-  | "emailAddress"
-  | "unspecified"
+  "persistent" | "transient" | "emailAddress" | "unspecified"
 
 /**
  * One field's source. Either the assertion's NameID or a named
@@ -36,8 +33,7 @@ export type SamlNameIdFormat =
  * multiple attributes with the same `Name` but different `NameFormat`.
  */
 export type SamlAttributeRef =
-  | { source: "nameId" }
-  | { source: "attribute"; name: string; format?: string }
+  { source: "nameId" } | { source: "attribute"; name: string; format?: string }
 
 /**
  * How the SAML method translates a verified assertion into the
@@ -152,6 +148,80 @@ export type SamlSpConfig = {
   idpInitiated?: SamlIdpInitiatedConfig
   /** Clock skew allowance for `NotBefore` / `NotOnOrAfter`. Seconds. */
   clockSkewSeconds?: number
+  /**
+   * Override the derived SP entityID.
+   *
+   * By default the entityID is derived as
+   * `<issuerUrl>/<tenantId>/<methodId>` (SAML-AD5) — stable, no config
+   * required, and guaranteed to match what SP metadata publishes. Set
+   * this **only** to adopt an entityID that already exists at the IdP,
+   * so an existing SAML app can be migrated without the customer
+   * editing their production SSO config.
+   *
+   * The override flows through every consumer at once — `AuthnRequest`
+   * issuer, `AudienceRestriction` validation, SP metadata, and logout
+   * messages — so the anti-drift invariant holds either way. Changing
+   * it on a live connection invalidates the IdP-side trust config;
+   * treat it as an IdP-coordination event.
+   */
+  spEntityId?: string
+  /**
+   * Set `ForceAuthn="true"` on the outbound `AuthnRequest`, asking the
+   * IdP to re-authenticate the user even if it has a live session.
+   * Default `false`.
+   *
+   * Note that this is a *request*: SAML gives the IdP no obligation to
+   * honour it, and there is no way to verify from the Response that it
+   * did. Do not treat a successful assertion as proof of fresh
+   * authentication.
+   */
+  forceAuthn?: boolean
+  /**
+   * Request specific authentication context classes (e.g. MFA) from
+   * the IdP via `<RequestedAuthnContext>`.
+   *
+   * **Omitted ⇒ no `RequestedAuthnContext` element is sent at all**,
+   * which lets the IdP apply its own sign-on policy. That is the right
+   * default for nearly every deployment: a `RequestedAuthnContext` the
+   * IdP cannot satisfy exactly is answered with `NoAuthnContext`
+   * instead of a login, and an MFA policy at the IdP is a common way
+   * to *not* satisfy `PasswordProtectedTransport` under
+   * `Comparison="exact"`.
+   *
+   * Set it only when the IdP has told you which class refs it honours.
+   * `comparison` maps to the `Comparison` attribute and defaults to
+   * `"exact"`; `"minimum"` is usually the safer choice when requesting
+   * MFA.
+   *
+   * Requesting a context does **not** verify one was used — read
+   * `SamlSpProperties.authnContextClassRef` for what the IdP actually
+   * asserted.
+   */
+  requestedAuthnContext?: {
+    /** Full URNs, e.g. `urn:oasis:names:tc:SAML:2.0:ac:classes:MultiFactorAuthn`. */
+    classRefs: ReadonlyArray<string>
+    comparison?: "exact" | "minimum" | "maximum" | "better"
+  }
+  /**
+   * Require the `<saml:Assertion>` itself to carry a valid XML-DSig.
+   * **Defaults to `true` and should stay that way** — the identity,
+   * conditions, and audience all live inside the assertion, so signing
+   * it is what actually binds them.
+   *
+   * Set `false` only for an IdP that signs the outer `<Response>` and
+   * nothing else, and only together with `requireSignedResponse: true`.
+   * The schema refuses to let both be off.
+   */
+  requireSignedAssertion?: boolean
+  /**
+   * Require the outer `<samlp:Response>` to carry a valid XML-DSig.
+   * Default `false` — requiring it is stricter than the Okta / Entra
+   * default and would reject the majority of real IdPs. Enable it for
+   * an IdP that signs the Response, either as defence in depth
+   * alongside a signed assertion or (with
+   * `requireSignedAssertion: false`) as the only signature on offer.
+   */
+  requireSignedResponse?: boolean
 }
 
 /**
@@ -197,6 +267,27 @@ export type SamlSpProperties = {
   sessionIndex?: string
   /** Unix ms — the assertion's `AuthnInstant`. */
   authnInstant: number
+  /**
+   * Unix ms — the `AuthnStatement/@SessionNotOnOrAfter` the IdP
+   * asserted, when it supplied one. This is the IdP's own view of when
+   * its session for this user expires.
+   *
+   * The library does **not** act on it: token and session lifetimes are
+   * host policy, and this library owns no session. Hosts that want
+   * "when their IdP session ends, ours ends" should clamp their own
+   * session/token TTL to this value in the `success` callback.
+   */
+  sessionNotOnOrAfter?: number
+  /**
+   * The `AuthnContext/AuthnContextClassRef` the IdP actually asserted —
+   * i.e. how it says it authenticated the user. Absent when the
+   * assertion carries none.
+   *
+   * This is the value to check for step-up decisions ("was this really
+   * MFA?"). `SamlSpConfig.requestedAuthnContext` only *asks*; this is
+   * the answer, and the two can differ.
+   */
+  authnContextClassRef?: string
   raw: {
     responseXml: string
   }

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"
 
@@ -186,9 +187,7 @@ export type RegisterClientRequest = {
   response_types?: string[]
   /** RFC 7591 §2 — `"none"` = public client, otherwise confidential. */
   token_endpoint_auth_method?:
-    | "none"
-    | "client_secret_basic"
-    | "client_secret_post"
+    "none" | "client_secret_basic" | "client_secret_post"
   scope?: string
   /** OIDC RP-Initiated Logout 1.0 §2. */
   post_logout_redirect_uris?: string[]
@@ -280,6 +279,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/result.ts

@@ -11,8 +11,7 @@
 import type { AuthError } from "./error"
 
 export type Result<T, E = AuthError> =
-  | { ok: true; value: T }
-  | { ok: false; error: E }
+  { ok: true; value: T } | { ok: false; error: E }
 
 export const ok = <T>(value: T): Result<T, never> => ({ ok: true, value })
 export const err = <E>(error: E): Result<never, E> => ({ ok: false, error })