@_mustachio/openauth 0.11.0 → 0.13.0

package/src/ports/session-store.ts

@@ -101,6 +101,30 @@ export type SessionStore = {
     ttl: number,
   ): Promise<Result<void>>
   consumePar?(requestUri: string): Promise<Result<ParRecord>>
+
+  /**
+   * Optional: per-method-instance scratch storage. Survives across flows
+   * (unlike `methodState`, which is per-flow). Use cases include cross-flow
+   * deduplication state — e.g., a SAML SP method remembering recently-seen
+   * assertion IDs for replay protection.
+   *
+   * The framework scopes keys per `(tenantId, methodId)` before calling
+   * these — adapters see opaque, already-namespaced keys and store the
+   * UTF-8 string value verbatim. Methods JSON-encode if they want object
+   * state.
+   *
+   * Strong consistency + TTL respect (same semantics as flow records).
+   * `readScratch` returns `unknown_state` if the key is missing or
+   * expired. `deleteScratch` is idempotent.
+   *
+   * Adapters without these methods cannot host methods that depend on
+   * scratch; the framework surfaces a clear `unsupported` error through
+   * `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>>
+  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"
 
@@ -69,6 +70,56 @@ export type FailureEvent = {
   error: AuthError
 }
 
+/**
+ * Input to the optional `IdPOptions.onLogout` hook.
+ *
+ * Fires when an upstream provider notifies this IdP that a federated
+ * session has ended — today, a SAML front-channel `LogoutRequest`
+ * delivered to the SP's SLS endpoint. By the time this runs the library
+ * has already cryptographically verified the upstream logout message
+ * (XML-DSig via the SAML method), so the hook is purely the host's
+ * teardown point.
+ *
+ * The library deliberately does **not** know which OIDC `subject` an
+ * upstream identifier (`nameId`) maps to — that mapping lives in the
+ * host's `success` callback, not the library. So the host clears its
+ * own session and returns the subject (if any) whose library-issued
+ * tokens should be revoked; the library then runs the same
+ * `revokeAllForSubject` primitive `/end_session` uses. Returning
+ * nothing skips library-side revocation (the host handled everything,
+ * or there is nothing to revoke).
+ *
+ * Method-agnostic on purpose: any federation method that can verify an
+ * upstream logout signal reuses this. SAML SLO is the first caller;
+ * OIDC back-channel logout would be the next.
+ */
+export type LogoutEventInput = {
+  tenant: TenantContext
+  methodId: string
+  methodKind: string
+  /** What kind of upstream logout this is. Extensible discriminant. */
+  reason: "upstream_slo"
+  /**
+   * Upstream subject identifier from the verified logout message
+   * (SAML `LogoutRequest/NameID`). Absent if the message omitted it.
+   */
+  nameId?: string
+  /**
+   * Upstream session index from the verified logout message
+   * (SAML `SessionIndex`), when present. Lets a host that tracks
+   * per-session state scope its teardown.
+   */
+  sessionIndex?: string
+}
+
+/**
+ * Return of `IdPOptions.onLogout`. `revokeSubject` names the OIDC
+ * subject whose library-issued refresh tokens the library should
+ * revoke (the host resolves it from `nameId` — only the host has that
+ * map). Omit / return nothing to skip library-side revocation.
+ */
+export type LogoutHookResult = { revokeSubject?: string } | void
+
 /**
  * Optional hook called at `/token` time, after PKCE has succeeded and
  * after the `success` callback has produced a `SubjectClaim`, but
@@ -230,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)
@@ -259,6 +321,30 @@ export type IdPOptions = {
     onFailure?: (event: FailureEvent) => Promise<void>
   }
 
+  /**
+   * Optional hook fired when an upstream provider signals that a
+   * federated session ended — SAML front-channel Single Logout today.
+   * The library has already verified the signed logout message; this
+   * hook is where the host tears down its own session and names the
+   * OIDC subject (if any) whose library-issued tokens to revoke. See
+   * the `LogoutEventInput` / `LogoutHookResult` type docs.
+   *
+   * Unlike `hooks.onSuccess`/`onFailure` (observation only) this hook
+   * **influences** library behaviour — its return drives token
+   * revocation — so it sits at the top level alongside `success`.
+   *
+   * Absent ⇒ the library still verifies the logout, emits a
+   * `session_logout` audit event, and returns the protocol
+   * `LogoutResponse`, but performs no token revocation (it cannot map
+   * the upstream id to a subject without the host).
+   *
+   * If it throws, the SLS endpoint fails closed with an internal error
+   * rather than acknowledging a logout it could not fully process.
+   */
+  onLogout?: (
+    input: LogoutEventInput,
+  ) => Promise<LogoutHookResult> | LogoutHookResult
+
   /**
    * Optional escape hatch for high-sensitivity deployments — see the
    * `PersistUpstreamTokens` type doc.

package/src/types/method.ts

@@ -56,6 +56,37 @@ export type AuthMethod<P = unknown, S = unknown> = {
    * same factory get distinct URL spaces).
    */
   routes: Record<string, MethodHandler<P, S>>
+  /**
+   * Opt-in allowlist of route keys (same `"GET /metadata"` string form
+   * as `routes` keys) that the framework dispatches **without** a flow
+   * cookie or flow record — anonymous, unauthenticated GETs. The sole
+   * intended use is publishing static, per-instance descriptive
+   * documents (SAML SP metadata XML). The handler receives
+   * `ctx.flow === null` and `ctx.methodState === null` and MUST be a
+   * pure function of `ctx.tenant` + `ctx.dispatch` + its captured
+   * config — it must not assume an authenticated principal.
+   *
+   * Absent (the default for every method) ⇒ behaviour is unchanged:
+   * every `/m/<id>/*` request requires the `idp.flow` cookie. The
+   * cookie gate is skipped *only* for a route key a method explicitly
+   * lists here — fail-closed by construction.
+   */
+  publicRoutes?: ReadonlyArray<string>
+  /**
+   * Opt-in: this method instance handles **unsolicited** upstream
+   * callbacks — a `POST /cb/<methodId>` carrying a provider assertion
+   * with no framework state envelope and no prior flow (SAML
+   * IdP-initiated SSO). When `true`, the framework, instead of
+   * rejecting a stateless callback, dispatches `GET /callback` with
+   * `flow === null` and a derived `dispatch` (issuer/ACS); the handler
+   * verifies the assertion and returns `success` **with
+   * `unsolicitedBinding`**. Absent (every method's default) ⇒ a
+   * stateless callback stays an `invalid_request` (the conservative
+   * default — many deployments do not want IdP-initiated). General
+   * capability, not SAML-specific; set per instance (a SAML instance
+   * sets it only when its config enables IdP-initiated).
+   */
+  unsolicitedCallback?: boolean
   /**
    * Token-exchange function for the `/token` endpoint when the method
    * participates in client-credentials-style flows (e.g. `m2m`). Most
@@ -102,6 +133,47 @@ export type MethodContext<S = unknown> = {
    * and the relevant data is on `flow`).
    */
   dispatch: MethodDispatchData | null
+  /**
+   * Per-method-instance scratch storage scoped to
+   * `(tenant.id, method.id)`. Survives across flows — distinct from
+   * `methodState`, which is per-flow.
+   *
+   * Most methods do NOT need this. It exists for cross-flow
+   * deduplication patterns such as SAML SP assertion-ID replay
+   * protection.
+   *
+   * Backed by `SessionStore.{saveScratch,readScratch,deleteScratch}`
+   * when those optional methods are implemented. Against adapters that
+   * don't implement them, every call returns
+   * `{ ok: false, error: unsupported }` — the method should surface a
+   * `MethodResult.error` with a clear message, not silently degrade.
+   */
+  methodScratch: MethodScratch
+}
+
+/**
+ * Caller-facing API for per-method-instance scratch. The framework
+ * scopes user-supplied keys with a `(tenantId, methodId)` prefix before
+ * delegating to `SessionStore` — adapters never see raw method keys.
+ *
+ * Values are UTF-8 strings; methods JSON-encode if they want to stash
+ * objects. Keeping the port-level type narrow simplifies adapter
+ * implementations (one TEXT column, one Dynamo `S` attribute, etc.).
+ */
+export type MethodScratch = {
+  /**
+   * Persist `value` under `key` with the given TTL. Overwrites prior
+   * value for the same key. `ttlMs` must be positive.
+   */
+  put(key: string, value: string, ttlMs: number): Promise<Result<void>>
+  /**
+   * Read the value previously stored at `key`. Returns `unknown_state`
+   * if the key is missing or expired (the underlying adapter MAY
+   * lazily evict expired entries on read).
+   */
+  get(key: string): Promise<Result<string>>
+  /** Idempotent. Resolves `ok` whether the key existed or not. */
+  delete(key: string): Promise<Result<void>>
 }
 
 /** Framework-supplied data available to the method at `/authorize` time. */
@@ -143,6 +215,27 @@ export type MethodResult<P = unknown, S = unknown> =
       saveMethodState?: S
       /** Serialized into a `Cache-Control` header by the framework. */
       cache?: CachePolicy
+      /**
+       * Verified upstream-logout notification. Set **only** by a
+       * flowless **public** logout route (e.g. SAML front-channel SLS)
+       * once it has cryptographically verified the inbound logout
+       * message. The method stays port-free — it proves authenticity
+       * and builds the protocol response (`response` = the signed
+       * `LogoutResponse` redirect / ack); the privileged side effect
+       * runs in the framework.
+       *
+       * When present on a public route the framework fires
+       * `IdPOptions.onLogout` and, if that returns `{ revokeSubject }`,
+       * runs `revokeAllForSubject` — then returns `response`. Ignored
+       * on non-public (flow-bearing) routes: an authenticated method
+       * route never logs anyone out. Mirrors the Phase 2 V′ pattern
+       * (`success.unsolicitedBinding`): an optional field on an
+       * existing variant, not a new `MethodResult` kind.
+       */
+      logout?: {
+        nameId?: string
+        sessionIndex?: string
+      }
     }
   /**
    * Authentication succeeded. The HTTP layer hands `providerSubject` +
@@ -155,6 +248,23 @@ export type MethodResult<P = unknown, S = unknown> =
       providerSubject: string
       properties: P
       setCookies?: SetCookie[]
+      /**
+       * RP binding for a **flowless** (unsolicited / IdP-initiated)
+       * authentication. Consulted **only** when the method ran with no
+       * `flow` (e.g. an unsolicited SAML Response — see
+       * `AuthMethod.unsolicitedCallback`). On the normal SP-initiated
+       * path a `flow` exists and this is ignored; on the flowless path
+       * it is **required** (the framework has no pending RP request to
+       * read `client_id` / `redirect_uri` / `scope` from, so the method
+       * supplies the operator-configured defaults). The framework still
+       * validates `clientId` / `redirectUri` against the tenant's
+       * registered client before issuing a code.
+       */
+      unsolicitedBinding?: {
+        clientId: string
+        redirectUri: string
+        scopes: string[]
+      }
     }
   /** User refused / failed auth in a non-error way (e.g. consent declined). */
   | { kind: "denied"; reason: string; setCookies?: SetCookie[] }

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
 }
 
 /**