@_mustachio/openauth 0.10.0 → 0.12.0

package/src/domain/register.ts

@@ -0,0 +1,168 @@
+/**
+ * Dynamic Client Registration (RFC 7591).
+ *
+ * The host owns persistence — this module validates the wire request,
+ * mints a fresh `client_id` (and `client_secret` for confidential
+ * clients), invokes the host's `registerClient` hook with a structured
+ * `ClientConfig`, and builds the §3.2.1 response.
+ *
+ * Per RFC 7591:
+ *  - §2: registration request body is JSON, fields include
+ *    `client_name`, `redirect_uris`, `grant_types`, `response_types`,
+ *    `token_endpoint_auth_method`, `scope`, etc.
+ *  - §3.2.1: response is JSON with `client_id`, optional
+ *    `client_secret`, `client_id_issued_at`, optional
+ *    `client_secret_expires_at`, and the registered metadata.
+ *  - §3.2.2: structural problems → `invalid_client_metadata` /
+ *    `invalid_redirect_uri`. We collapse to `invalid_request` for
+ *    consistency with the rest of the library's error mapping.
+ */
+import { authError, type AuthError } from "../types/error"
+import type {
+  RegisterClient,
+  RegisterClientRequest,
+  RegisterClientResponse,
+} from "../types/idp"
+import type { Result } from "../types/result"
+import { err, isErr, ok } from "../types/result"
+import type { TenantContext } from "../types/tenant"
+
+import { randomId, randomToken } from "./crypto"
+import { hashClientSecret } from "./token"
+
+export type RegisterDeps = {
+  registerClient?: RegisterClient
+  clock: () => number
+  /** Test override for deterministic client_id. */
+  newClientId?: () => string
+  /** Test override for deterministic client_secret. */
+  newClientSecret?: () => string
+}
+
+export async function registerNewClient(
+  request: RegisterClientRequest,
+  tenant: TenantContext,
+  deps: RegisterDeps,
+): Promise<Result<RegisterClientResponse, AuthError>> {
+  if (!deps.registerClient) {
+    return err(
+      authError.invalidRequest(
+        "dynamic client registration is not enabled on this deployment",
+      ),
+    )
+  }
+
+  // RFC 7591 §2 — redirect_uris is REQUIRED for any client that uses a
+  // redirect-based grant. We accept the field as required at the wire
+  // level (schema enforces) and validate non-empty here.
+  if (
+    !Array.isArray(request.redirect_uris) ||
+    request.redirect_uris.length === 0
+  ) {
+    return err(
+      authError.invalidRequest(
+        "redirect_uris must be a non-empty array",
+        "redirect_uris",
+      ),
+    )
+  }
+  for (const uri of request.redirect_uris) {
+    try {
+      // Reject relative / opaque URIs eagerly so the host gets a clean
+      // structural rejection instead of a runtime surprise at /authorize.
+      // RFC 7591 §2 leaves URI scheme to grant-type semantics; we follow
+      // the OAuth 2.1 BCP and require absolute URIs.
+      void new URL(uri)
+    } catch {
+      return err(
+        authError.invalidRequest(
+          `redirect_uri "${uri}" is not a valid absolute URI`,
+          "redirect_uris",
+        ),
+      )
+    }
+  }
+
+  const authMethod = request.token_endpoint_auth_method ?? "client_secret_basic"
+  const isPublic = authMethod === "none"
+  const clientId = (deps.newClientId ?? randomId)()
+  const grantTypes = request.grant_types ?? ["authorization_code"]
+  const responseTypes = request.response_types ?? ["code"]
+  const scopes = request.scope
+    ? request.scope.split(/\s+/).filter(Boolean)
+    : ["openid"]
+
+  let secret: string | undefined
+  let secretHash: string | undefined
+  if (!isPublic) {
+    secret = (deps.newClientSecret ?? randomToken)()
+    secretHash = await hashClientSecret(secret)
+  }
+
+  const clientPartial = {
+    id: clientId,
+    name: request.client_name ?? clientId,
+    redirectUris: request.redirect_uris,
+    // Default scopes overlap with what the IdP advertises; hosts may
+    // override during the hook call before persisting.
+    scopes,
+    grantTypes: grantTypes.filter(
+      (g): g is "authorization_code" | "refresh_token" | "client_credentials" =>
+        g === "authorization_code" ||
+        g === "refresh_token" ||
+        g === "client_credentials",
+    ),
+    ...(request.post_logout_redirect_uris !== undefined
+      ? { postLogoutRedirectUris: request.post_logout_redirect_uris }
+      : {}),
+    ...(request.sector_identifier_uri !== undefined
+      ? { sectorIdentifier: request.sector_identifier_uri }
+      : {}),
+  }
+
+  const clientConfig = isPublic
+    ? {
+        ...clientPartial,
+        type: "public" as const,
+        pkceRequired: true as const,
+      }
+    : {
+        ...clientPartial,
+        type: "confidential" as const,
+        secretHash: secretHash!,
+        pkceRequired: true,
+      }
+
+  const hookResult = await deps.registerClient({
+    tenant,
+    request,
+  })
+  // The hook may either:
+  //  - persist `clientConfig` as-is (most common) and return it,
+  //  - synthesize its own (host-owned id generation, custom scopes) and
+  //    return that — in which case the secret we minted is moot.
+  // We trust the hook's returned client + secret as authoritative.
+  void clientConfig
+
+  if (isErr(hookResult)) return err(hookResult.error)
+  const persisted = hookResult.value.client
+  const persistedSecret = hookResult.value.secret
+
+  const issuedAt = Math.floor(deps.clock() / 1000)
+  return ok({
+    client_id: persisted.id,
+    ...(persistedSecret !== undefined
+      ? { client_secret: persistedSecret }
+      : {}),
+    client_id_issued_at: issuedAt,
+    // RFC 7591 §3.2.1: `0` = no expiry.
+    client_secret_expires_at: 0,
+    redirect_uris: persisted.redirectUris,
+    grant_types: persisted.grantTypes,
+    response_types: responseTypes,
+    token_endpoint_auth_method: authMethod,
+    ...(request.client_name !== undefined
+      ? { client_name: request.client_name }
+      : {}),
+  })
+}

package/src/domain/token-exchange.ts

@@ -74,6 +74,8 @@ export type ExchangeTokenDeps = {
   issuerUrl: string
   clock: () => number
   newRefreshFamily?: () => string
+  /** See `IdPOptions.customScopeClaims`. Forwarded to `mintTokens`. */
+  customScopeClaims?: Record<string, ReadonlyArray<string>>
 }
 
 export async function exchangeToken(
@@ -203,6 +205,15 @@ export async function exchangeToken(
       methodId: subjectClaims.mid ?? "token_exchange",
       methodKind: subjectClaims.mkind ?? "token_exchange",
       scopes: requestedScopes,
+      // Carry the original end-user auth_time across the audience swap.
+      // Per OIDC Core §12, switching audience is NOT a re-authentication
+      // — the user logged in once, and downstream id_token consumers rely
+      // on auth_time being stable to detect actual re-auth events. When
+      // absent (subject was a client_credentials / m2m token), mintTokens
+      // correctly skips id_token issuance.
+      ...(subjectClaims.auth_time !== undefined
+        ? { authTime: subjectClaims.auth_time }
+        : {}),
       ...(subjectClaims.aud !== undefined &&
       subjectClaims.aud !== callerClient.id
         ? { audience: subjectClaims.aud }

package/src/domain/token.ts

@@ -47,7 +47,8 @@ import {
   sha256,
   utf8,
 } from "./crypto"
-import { signAccessToken } from "./jwt"
+import { buildIdTokenClaims, shouldIssueIdToken } from "./id-token"
+import { signAccessToken, signIdToken } from "./jwt"
 import { validatePkce } from "./pkce"
 
 /**
@@ -88,6 +89,13 @@ export type TokenAuthCodeRequest = {
   clientSecret?: string
   /** Required if the original `/authorize` request had a `code_challenge`. */
   codeVerifier?: string
+  /**
+   * RFC 9449 §6 — the JWK thumbprint of the presented DPoP proof. Set by
+   * the HTTP layer after verifying the `DPoP:` header against this
+   * request's actual method + URI. The domain binds the issued access
+   * token to this thumbprint via `cnf.jkt`.
+   */
+  dpopJkt?: string
 }
 
 export type ExchangeCodeDeps = {
@@ -102,6 +110,11 @@ export type ExchangeCodeDeps = {
   newRefreshToken?: () => string
   /** Test override. */
   newRefreshFamily?: () => string
+  /**
+   * Host-supplied vendor scope → claim-names map. Forwarded to `mintTokens`
+   * for id_token + /userinfo scope-gating. See `IdPOptions.customScopeClaims`.
+   */
+  customScopeClaims?: Record<string, ReadonlyArray<string>>
 }
 
 export async function exchangeCode(
@@ -141,6 +154,17 @@ export async function exchangeCode(
   const authResult = await verifyClientCredentials(client, req.clientSecret)
   if (authResult) return err(authResult)
 
+  // RFC 9449 §5.2 — if the client is configured to require DPoP, a
+  // bearer-only request (no DPoP header → no `dpopJkt` threaded in) is
+  // refused with `invalid_dpop_proof` before any token is minted.
+  if (client.dpopRequired && req.dpopJkt === undefined) {
+    return err(
+      authError.invalidDpopProof(
+        `client "${client.id}" requires DPoP-bound tokens`,
+      ),
+    )
+  }
+
   // 4. Redirect URI binding.
   if (payload.appRedirectUri !== req.redirectUri) {
     return err(authError.invalidGrant("redirect_uri mismatch with auth code"))
@@ -198,11 +222,14 @@ export async function exchangeCode(
     }
   }
 
-  // 8. Mint access + refresh.
+  // 8. Mint access + refresh (+ id_token if `openid` scope was granted).
   const minted = await mintTokens({
     tenant,
     claim,
-    payload,
+    payload: {
+      ...payload,
+      ...(req.dpopJkt !== undefined ? { dpopJkt: req.dpopJkt } : {}),
+    },
     deps,
     family: (deps.newRefreshFamily ?? randomId)(),
   })
@@ -219,7 +246,30 @@ export async function mintTokens(args: {
   payload: Pick<
     CodePayload,
     "tenantId" | "clientId" | "methodId" | "methodKind" | "scopes" | "audience"
-  >
+  > & {
+    /**
+     * Present on `authorization_code` and `refresh_token` grants where an
+     * end-user actually authenticated. Absent on `client_credentials`
+     * (no end-user) — and absent means no `id_token` is emitted even if
+     * the requested scopes nominally include `openid`.
+     */
+    authTime?: number
+    /** RP's OIDC `nonce` from `/authorize`, when present. */
+    appNonce?: string
+    /**
+     * DPoP key thumbprint (RFC 9449 §6.1). When present, the access
+     * token's `cnf.jkt` claim is set and `token_type` flips to `"DPoP"`;
+     * the saved refresh-token payload's `dpopJkt` is set so refresh
+     * rotation re-enforces sender constraint.
+     */
+    dpopJkt?: string
+    /**
+     * OIDC Core §5.5 — RP-requested claims from `/authorize`. Carried
+     * into the id_token and forward across refresh rotations (§12) so
+     * later /userinfo calls keep returning the requested fields.
+     */
+    claimsRequest?: import("../types/authorization").ClaimsRequest
+  }
   family: string
   /**
    * `client_credentials` grants (RFC 6749 §4.4.3) and other paths where a
@@ -236,6 +286,11 @@ export async function mintTokens(args: {
     issuerUrl: string
     clock: () => number
     newRefreshToken?: () => string
+    /**
+     * Host-supplied vendor scope → claim-names map merged into the
+     * id_token + /userinfo scope-gating. See `IdPOptions.customScopeClaims`.
+     */
+    customScopeClaims?: Record<string, ReadonlyArray<string>>
   }
 }): Promise<Result<TokenResponse, AuthError>> {
   const { tenant, claim, payload, deps, family, skipRefresh } = args
@@ -248,12 +303,22 @@ export async function mintTokens(args: {
       ? tenant.config.refreshTtl * 1000
       : DEFAULT_REFRESH_TTL_MS
   const now = deps.clock()
-  const subjectId = await deriveSubjectId(claim)
+  // OIDC Core §8.1 — `sectorIdentifier` from the receiving client drives
+  // pairwise vs public subject derivation. Look it up off the tenant
+  // config (already loaded by the grant flow). Absent = public.
+  const receivingClient = tenant.config.clients.find(
+    (c) => c.id === payload.clientId,
+  )
+  const subjectId = await deriveSubjectId(
+    claim,
+    receivingClient?.sectorIdentifier,
+  )
 
   const keyRes = await deps.keyStore.currentSigningKey()
   if (isErr(keyRes)) return err(keyRes.error)
   const signingKey = keyRes.value
 
+  const userinfoClaimNames = Object.keys(payload.claimsRequest?.userinfo ?? {})
   const claims: AccessTokenClaims = {
     iss: deps.issuerUrl,
     sub: subjectId,
@@ -265,6 +330,9 @@ export async function mintTokens(args: {
     mkind: payload.methodKind,
     scope: payload.scopes.join(" "),
     claim,
+    ...(payload.authTime !== undefined ? { auth_time: payload.authTime } : {}),
+    ...(payload.dpopJkt !== undefined ? { cnf: { jkt: payload.dpopJkt } } : {}),
+    ...(userinfoClaimNames.length > 0 ? { uic: userinfoClaimNames } : {}),
   }
 
   let accessToken: string
@@ -295,6 +363,14 @@ export async function mintTokens(args: {
       family,
       methodId: payload.methodId,
       methodKind: payload.methodKind,
+      // Carry the original end-user auth time forward. Refresh-grant
+      // reissue uses this verbatim so `id_token.auth_time` is stable per
+      // OIDC Core §12 (refresh does not re-authenticate the user).
+      authTime: payload.authTime ?? Math.floor(now / 1000),
+      ...(payload.dpopJkt !== undefined ? { dpopJkt: payload.dpopJkt } : {}),
+      ...(payload.claimsRequest !== undefined
+        ? { claimsRequest: payload.claimsRequest }
+        : {}),
       issuedAt: now,
       expiresAt: now + refreshTtl,
     }
@@ -302,6 +378,41 @@ export async function mintTokens(args: {
     if (isErr(saved)) return err(saved.error)
   }
 
+  // OIDC id_token issuance — only when the grant carried an end-user
+  // (`authTime` present) AND `openid` scope was granted. Client-credentials
+  // never satisfies the first condition; refresh + code do.
+  let idToken: string | undefined
+  if (payload.authTime !== undefined && shouldIssueIdToken(payload.scopes)) {
+    const idClaims = await buildIdTokenClaims({
+      issuerUrl: deps.issuerUrl,
+      audience: payload.clientId,
+      subjectId,
+      claim,
+      scopes: payload.scopes,
+      authTime: payload.authTime,
+      ...(payload.appNonce !== undefined ? { appNonce: payload.appNonce } : {}),
+      now,
+      methodKind: payload.methodKind,
+      accessToken,
+      ...(payload.claimsRequest !== undefined
+        ? { claimsRequest: payload.claimsRequest }
+        : {}),
+      ...(deps.customScopeClaims !== undefined
+        ? { customScopeClaims: deps.customScopeClaims }
+        : {}),
+    })
+    try {
+      idToken = await signIdToken(
+        idClaims,
+        signingKey.privateKeyRef as Parameters<typeof signIdToken>[1],
+        signingKey.alg,
+        signingKey.kid,
+      )
+    } catch (e) {
+      return err(authError.serverError("id_token sign failed", e))
+    }
+  }
+
   await safeAudit(deps, {
     kind: "token_issued",
     tenantId: payload.tenantId,
@@ -310,14 +421,17 @@ export async function mintTokens(args: {
     methodKind: payload.methodKind,
     subjectId,
     refreshTokenIdHash: refresh ? await hashTokenForAudit(refresh) : "",
+    ...(idToken !== undefined ? { idTokenIssued: true } : {}),
+    ...(payload.dpopJkt !== undefined ? { dpopBound: true } : {}),
     timestamp: now,
   })
 
   return ok({
     access_token: accessToken,
-    token_type: "Bearer",
+    token_type: payload.dpopJkt !== undefined ? "DPoP" : "Bearer",
     expires_in: Math.floor(accessTtl / 1000),
     ...(refresh !== undefined ? { refresh_token: refresh } : {}),
+    ...(idToken !== undefined ? { id_token: idToken } : {}),
     scope: payload.scopes.join(" "),
   })
 }
@@ -336,11 +450,23 @@ export async function hashClientSecret(plain: string): Promise<string> {
 /**
  * Derive a stable subject id from the issued `SubjectClaim`. Hash inputs
  * are canonicalized so reordered `properties` keys hash identically.
+ *
+ * OIDC Core §8.1 — when `sectorIdentifier` is supplied, the derivation
+ * mixes it in so the resulting `sub` is **pairwise**: identical across
+ * clients sharing that sector, distinct across sectors. Absent =
+ * **public** subject (same `sub` for every RP).
  */
-async function deriveSubjectId(claim: SubjectClaim): Promise<string> {
+async function deriveSubjectId(
+  claim: SubjectClaim,
+  sectorIdentifier?: string,
+): Promise<string> {
   const c = claim as { type: string; properties: Record<string, unknown> }
   const ordered = canonicalize(c.properties)
-  return base64url.encode(await sha256(`${c.type}\0${ordered}`)).slice(0, 22)
+  const seed =
+    sectorIdentifier !== undefined
+      ? `${sectorIdentifier}\0${c.type}\0${ordered}`
+      : `${c.type}\0${ordered}`
+  return base64url.encode(await sha256(seed)).slice(0, 22)
 }
 
 function canonicalize(value: unknown): string {

package/src/domain/userinfo.ts

@@ -1,7 +1,23 @@
 /**
- * `/userinfo` endpoint logic (OIDC Core §5.3). Verifies the bearer access
- * token and returns the inlined `SubjectClaim` claims.
+ * `/userinfo` endpoint logic (OIDC Core §5.3). Verifies the presented
+ * access token, optionally enforces a DPoP proof binding (RFC 9449 §7),
+ * and returns the inlined `SubjectClaim` claims, scope-gated per OIDC
+ * Core §5.4.
+ *
+ * Profile / email / phone / address claims appear in the response only
+ * when (a) the access token's `scope` includes the granting scope and
+ * (b) the value exists on `SubjectClaim.properties`. Other properties
+ * (host-specific subject fields like `userId`, `roles`, …) are returned
+ * under `properties` and not subject to OIDC scope gating — they're
+ * outside §5.4's universe.
+ *
+ * DPoP at the resource server (RFC 9449 §7):
+ *  - If the access token has a `cnf.jkt` claim, the request MUST carry a
+ *    matching `DPoP:` proof whose `ath` equals SHA-256(access_token).
+ *  - If no `cnf.jkt`, the access token is plain Bearer and any DPoP
+ *    proof is silently ignored at this layer (host can still enforce).
  */
+import type { TokenStore } from "../ports/token-store"
 import type { KeyStore } from "../ports/key-store"
 import { authError, type AuthError } from "../types/error"
 import type { Result } from "../types/result"
@@ -9,13 +25,16 @@ import { err, isErr, ok } from "../types/result"
 import type { SubjectClaim } from "../types/subject"
 import type { AccessTokenClaims } from "../types/token"
 
+import { computeAth, verifyDpopProof } from "./dpop"
+import { pickScopedClaims } from "./id-token"
 import { verifyAccessToken } from "./jwt"
+import type { ScopedProfileClaims } from "../types/token"
 
-export type UserinfoResponse = {
+export type UserinfoResponse = ScopedProfileClaims & {
   sub: string
   /** Subject type discriminator (e.g. `"user"` / `"admin"`). */
   subject_type: string
-  /** Inlined claim properties. */
+  /** Inlined claim properties, host-specific and not gated by OIDC scope. */
   properties: Record<string, unknown>
   /** Scope granted to this access token. */
   scope?: string
@@ -23,11 +42,34 @@ export type UserinfoResponse = {
 
 export type UserinfoDeps = {
   keyStore: KeyStore
+  /** Required when DPoP-bound tokens are accepted. */
+  tokenStore?: TokenStore
   issuerUrl?: string
+  /**
+   * Host-supplied vendor scope → claim-names map. Merged into the
+   * scope-gated /userinfo response just as it is for id_token. See
+   * `IdPOptions.customScopeClaims`.
+   */
+  customScopeClaims?: Record<string, ReadonlyArray<string>>
+}
+
+export type UserinfoInput = {
+  /** Access token from `Authorization: Bearer ...` or `Authorization: DPoP ...`. */
+  accessToken: string
+  /** `Authorization`-scheme as presented. Defaults to `"Bearer"`. */
+  scheme?: "Bearer" | "DPoP"
+  /** Raw `DPoP:` header from the request, if any. */
+  dpopProof?: string
+  /** Canonical request URI for DPoP `htu` check (scheme + host + path). */
+  htu?: string
+  /** Request method for DPoP `htm` check, uppercase. */
+  htm?: string
+  /** Wall clock seconds for DPoP `iat` window. */
+  nowSec?: number
 }
 
 export async function userinfo(
-  bearerToken: string,
+  input: UserinfoInput,
   deps: UserinfoDeps,
 ): Promise<Result<UserinfoResponse, AuthError>> {
   const keysRes = await deps.keyStore.signingKeys()
@@ -35,22 +77,95 @@ export async function userinfo(
 
   let claims: AccessTokenClaims
   try {
-    claims = await verifyAccessToken(bearerToken, keysRes.value, {
+    claims = await verifyAccessToken(input.accessToken, keysRes.value, {
       ...(deps.issuerUrl ? { issuer: deps.issuerUrl } : {}),
     })
   } catch {
     return err(authError.invalidGrant("access token invalid or expired"))
   }
 
+  // RFC 9449 §7 — DPoP-bound tokens require a matching proof at the RS.
+  const boundJkt = claims.cnf?.jkt
+  if (boundJkt !== undefined) {
+    if (input.scheme !== "DPoP") {
+      return err(
+        authError.invalidDpopProof(
+          'access token is DPoP-bound; Authorization scheme must be "DPoP"',
+        ),
+      )
+    }
+    if (!input.dpopProof) {
+      return err(
+        authError.invalidDpopProof(
+          "access token is DPoP-bound; request is missing a DPoP proof",
+        ),
+      )
+    }
+    if (!input.htu || !input.htm || input.nowSec === undefined) {
+      return err(
+        authError.invalidDpopProof(
+          "userinfo dpop verification requires htu, htm, and nowSec",
+        ),
+      )
+    }
+    if (!deps.tokenStore) {
+      return err(
+        authError.invalidDpopProof(
+          "userinfo dpop verification requires a token-store (jti replay protection)",
+        ),
+      )
+    }
+    const expectedAth = await computeAth(input.accessToken)
+    const dpopRes = await verifyDpopProof(
+      {
+        proofJwt: input.dpopProof,
+        htu: input.htu,
+        htm: input.htm,
+        nowSec: input.nowSec,
+        expectedAth,
+      },
+      { tokenStore: deps.tokenStore },
+    )
+    if (isErr(dpopRes)) return err(dpopRes.error)
+    if (dpopRes.value.jkt !== boundJkt) {
+      return err(
+        authError.invalidDpopProof(
+          "dpop proof key does not match access token cnf.jkt",
+        ),
+      )
+    }
+  } else if (input.scheme === "DPoP") {
+    // Token isn't bound but caller used the DPoP scheme — reject so a
+    // confused-deputy can't accidentally rely on RS-side enforcement.
+    return err(
+      authError.invalidGrant(
+        "access token is not DPoP-bound; use Authorization: Bearer",
+      ),
+    )
+  }
+
   const claim = claims.claim as SubjectClaim & {
     type: string
     properties: Record<string, unknown>
   }
 
+  const scopes = claims.scope ? claims.scope.split(" ").filter(Boolean) : []
+  // OIDC Core §5.5 — claims the RP requested via `claims=...userinfo:...`
+  // bypass scope gating. Names were captured into `uic` at mint time so
+  // the resource server doesn't need to re-resolve the original /authorize
+  // request.
+  const scopedClaims = pickScopedClaims(
+    claim,
+    scopes,
+    claims.uic ?? [],
+    deps.customScopeClaims ?? {},
+  )
+
   return ok({
     sub: claims.sub,
     subject_type: claim.type,
     properties: claim.properties,
     scope: claims.scope,
+    ...scopedClaims,
   })
 }

package/src/http/context.ts

@@ -17,7 +17,10 @@ import type { MethodCache } from "../domain/method-cache"
 import type { AuthError } from "../types/error"
 import type {
   ExchangeAudience,
+  LogoutEventInput,
+  LogoutHookResult,
   PersistUpstreamTokens,
+  RegisterClient,
   RenderPicker,
   SuccessMapInput,
 } from "../types/idp"
@@ -48,15 +51,22 @@ export type HttpDeps = {
   callbackHostFor?: (tenantId: TenantId) => string
   resolveTenant: (req: Request) => Promise<Result<TenantId, AuthError>>
   success: (input: SuccessMapInput) => Promise<SubjectClaim>
+  /** See `IdPOptions.onLogout` — upstream Single Logout host hook. */
+  onLogout?: (
+    input: LogoutEventInput,
+  ) => Promise<LogoutHookResult> | LogoutHookResult
   persistUpstreamTokens?: PersistUpstreamTokens
   exchangeAudience?: ExchangeAudience
   renderPicker?: RenderPicker
+  registerClient?: RegisterClient
   /** Builds `TenantContext.request.custom` for every request. See `IdPOptions.buildCustomContext`. */
   buildCustomContext?: (
     req: Request,
   ) => Record<string, unknown> | Promise<Record<string, unknown>>
   clock: () => number
   cookieDefaults: CookieDefaults
+  /** See `IdPOptions.customScopeClaims`. */
+  customScopeClaims?: Record<string, ReadonlyArray<string>>
 }
 
 /** Per-request variables populated by middleware. */

package/src/http/cookies.ts

@@ -7,7 +7,7 @@
  * strip method-returned `Set-Cookie` / security / `Cache-Control` headers so
  * methods cannot bypass policy.
  */
-import type { SetCookie } from "../types/method"
+import type { CachePolicy, SetCookie } from "../types/method"
 
 /** Parse an incoming `Cookie:` header into a read-only map. */
 export function parseCookieHeader(header: string | null): Map<string, string> {
@@ -117,6 +117,24 @@ const STRIPPED_HEADERS = [
   "cache-control",
 ] as const
 
+/**
+ * Serialize a `MethodResult.challenge`'s `CachePolicy` into a
+ * `Cache-Control` header value. The framework owns this header (methods
+ * cannot set it directly — see `STRIPPED_HEADERS`); a method opts into
+ * caching via the typed `cache` field and this renders it. Absent /
+ * `maxAge: 0` ⇒ `no-store` (the safe default for auth UI).
+ */
+export function cacheControlHeader(cache: CachePolicy | undefined): string {
+  if (!cache) return "no-store"
+  if ((cache.maxAge ?? -1) === 0) return "no-store"
+  const parts: string[] = []
+  if (cache.isPrivate) parts.push("private")
+  if (cache.maxAge !== undefined) parts.push(`max-age=${cache.maxAge}`)
+  if (cache.sMaxAge !== undefined) parts.push(`s-maxage=${cache.sMaxAge}`)
+  if (cache.immutable) parts.push("immutable")
+  return parts.length ? parts.join(", ") : "no-store"
+}
+
 export type ApplyOptions = {
   setCookies?: SetCookie[]
   cookieDefaults?: CookieDefaults