@_mustachio/openauth 0.13.3 → 0.15.0

package/src/domain/register.ts

@@ -136,17 +136,36 @@ export async function registerNewClient(
   const hookResult = await deps.registerClient({
     tenant,
     request,
+    client: clientConfig,
+    ...(secret !== undefined ? { secret } : {}),
   })
-  // 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)
+
+  // The host returns what it actually persisted — normally `clientConfig`
+  // unchanged, sometimes adjusted (narrowed scopes, host-owned id). That
+  // return is authoritative; the framework does not second-guess it.
   const persisted = hookResult.value.client
-  const persistedSecret = hookResult.value.secret
+  // The plaintext may only be reused when the host persisted *our* hash;
+  // if it substituted its own, our secret would not verify and the RP
+  // would receive a credential that silently never works.
+  const keptOurSecret =
+    persisted.type === "confidential" &&
+    clientConfig.type === "confidential" &&
+    persisted.secretHash === clientConfig.secretHash
+  const persistedSecret =
+    hookResult.value.secret ?? (keptOurSecret ? secret : undefined)
+
+  // RFC 7591 §3.2.1 — a confidential client must leave registration with
+  // a usable secret. Better to fail loudly than to hand back a client
+  // that cannot authenticate.
+  if (persisted.type === "confidential" && persistedSecret === undefined) {
+    return err(
+      authError.serverError(
+        "registerClient persisted a confidential client with a substituted " +
+          "secretHash but returned no matching plaintext secret",
+      ),
+    )
+  }
 
   const issuedAt = Math.floor(deps.clock() / 1000)
   return ok({

package/src/domain/state-envelope.ts

@@ -140,3 +140,43 @@ function isEnvelopeShape(value: unknown): value is EnvelopeShape {
     typeof v.kid === "string"
   )
 }
+
+/**
+ * Pull the MAC state envelope off an inbound callback request.
+ *
+ * The envelope normally rides `?state=` on the upstream redirect.
+ * POST-binding callbacks carry it in the form body instead: OAuth
+ * `response_mode=form_post` uses `state`, SAML's HTTP-POST binding uses
+ * `RelayState`. Read the query first (cheap, the common case) and fall
+ * back to a **cloned** body read so the downstream method handler still
+ * gets an unconsumed request body (it needs it for `code` /
+ * `SAMLResponse`).
+ *
+ * Any body-parse failure degrades to "no state" — identical to the
+ * behaviour when the query param is simply absent.
+ *
+ * **This is the single extraction point**, shared by the tenant
+ * middleware and the callback domain. They ran near-identical copies
+ * until 0.14.0, and the middleware copy — which runs *first* — read only
+ * `state`. SP-initiated SAML callbacks therefore fell through to
+ * `resolveTenant`, breaking the documented guarantee that callbacks
+ * recover the tenant without it. Keep exactly one of these.
+ */
+export async function extractCallbackState(
+  req: Request,
+): Promise<string | null> {
+  const fromQuery = new URL(req.url).searchParams.get("state")
+  if (fromQuery) return fromQuery
+  if (req.method !== "POST") return null
+  const ct = req.headers.get("content-type") ?? ""
+  if (!ct.toLowerCase().includes("application/x-www-form-urlencoded")) {
+    return null
+  }
+  try {
+    const form = new URLSearchParams(await req.clone().text())
+    const v = form.get("state") ?? form.get("RelayState")
+    return v && v.length > 0 ? v : null
+  } catch {
+    return null
+  }
+}

package/src/domain/subject.ts

@@ -0,0 +1,103 @@
+/**
+ * Subject-claim validation at issuance.
+ *
+ * `IdPOptions.subjects` is a required option, and until 0.14.0 nothing on
+ * the server read it: `createIdP` accepted the schema and signed whatever
+ * `success()` returned. Two things went wrong as a result.
+ *
+ * First, the failure surfaced in the wrong place. `client.verify()` does
+ * validate against the same schema, so a malformed claim was caught by the
+ * relying party — after the token had been signed, written into the refresh
+ * payload, and handed to anything else holding it. Validating here turns a
+ * late failure in another service into an immediate local one.
+ *
+ * Second, the types were unsound. `SubjectPayload` declares
+ * `properties: v1.InferOutput<T[type]>` — the schema's *parsed output* —
+ * but with no parse anywhere the runtime value was the raw input. Any
+ * schema carrying a transform or a default had a declared type that lied.
+ * Returning the validated value is what makes that declaration true, and
+ * it makes the issued token agree with what `client.verify()` will hand
+ * back to the RP.
+ *
+ * Standard Schema keeps this validator spec-neutral (zod, valibot,
+ * arktype) and adds no dependency the public surface didn't already have.
+ */
+import type { AuthError } from "../types/error"
+import { authError } from "../types/error"
+import type { Result } from "../types/result"
+import { err, ok } from "../types/result"
+import type { SubjectClaim, SubjectSchema } from "../types/subject"
+
+/** Why a claim was rejected — enough for an operator, never the values. */
+export type SubjectClaimRejection = {
+  reason: "unknown-type" | "invalid-properties"
+  /** The offending `claim.type`. Host-declared, safe to log. */
+  subjectType: string
+  /** Standard Schema issue path, or the list of declared types. */
+  detail: string
+}
+
+/**
+ * Validate the host's `SubjectClaim` against its own declared schema.
+ *
+ * On success the returned claim carries the **parsed** properties, which
+ * is what gets signed and persisted. On failure the caller emits an
+ * `invalid_subject_claim` audit event and returns a server error: the
+ * host's callback broke its own contract, which is a deployment fault,
+ * not something the relying party did wrong.
+ */
+export async function validateSubjectClaim(
+  subjects: SubjectSchema,
+  claim: SubjectClaim,
+): Promise<
+  Result<SubjectClaim, AuthError & { rejection: SubjectClaimRejection }>
+> {
+  const declared = Object.keys(subjects)
+  const subjectType = typeof claim?.type === "string" ? claim.type : ""
+
+  const schema = subjectType ? subjects[subjectType] : undefined
+  if (!schema) {
+    return err(
+      Object.assign(
+        authError.serverError(
+          `success() returned subject type "${subjectType}", which is not declared in \`subjects\``,
+        ),
+        {
+          rejection: {
+            reason: "unknown-type" as const,
+            subjectType,
+            detail: `declared: ${declared.join(", ") || "(none)"}`,
+          },
+        },
+      ),
+    )
+  }
+
+  const validated = await schema["~standard"].validate(claim.properties)
+  if (validated.issues) {
+    // Paths only — the values themselves may be personal data.
+    const detail =
+      validated.issues
+        .map((i) => (i.path ?? []).map(String).join(".") || "(root)")
+        .join(", ") || "(root)"
+    return err(
+      Object.assign(
+        authError.serverError(
+          `success() returned properties that violate the "${subjectType}" schema`,
+        ),
+        {
+          rejection: {
+            reason: "invalid-properties" as const,
+            subjectType,
+            detail,
+          },
+        },
+      ),
+    )
+  }
+
+  return ok({
+    type: subjectType,
+    properties: validated.value,
+  } as SubjectClaim)
+}

package/src/domain/token-exchange.ts

@@ -36,7 +36,7 @@ import type { ConfigStore } from "../ports/config-store"
 import type { KeyStore } from "../ports/key-store"
 import type { TokenStore } from "../ports/token-store"
 import { authError, type AuthError } from "../types/error"
-import type { ExchangeAudience } from "../types/idp"
+import type { ExchangeAudience, OnTokenIssued } from "../types/idp"
 import type { Result } from "../types/result"
 import { err, isErr, ok } from "../types/result"
 import type { SubjectClaim } from "../types/subject"
@@ -73,6 +73,8 @@ export type ExchangeTokenDeps = {
   exchangeAudience?: ExchangeAudience
   issuerUrl: string
   clock: () => number
+  /** See `IdPOptions.onTokenIssued`. Threaded to `mintTokens`. */
+  onTokenIssued?: OnTokenIssued
   newRefreshFamily?: () => string
   /** See `IdPOptions.customScopeClaims`. Forwarded to `mintTokens`. */
   customScopeClaims?: Record<string, ReadonlyArray<string>>

package/src/domain/token.ts

@@ -24,10 +24,14 @@ import type { TokenStore } from "../ports/token-store"
 import type { ConfigStore } from "../ports/config-store"
 import type { AuthError } from "../types/error"
 import { authError } from "../types/error"
-import type { PersistUpstreamTokens, SuccessMapInput } from "../types/idp"
+import type {
+  OnTokenIssued,
+  PersistUpstreamTokens,
+  SuccessMapInput,
+} from "../types/idp"
 import type { Result } from "../types/result"
 import { err, isErr, ok } from "../types/result"
-import type { SubjectClaim } from "../types/subject"
+import type { SubjectClaim, SubjectSchema } from "../types/subject"
 import type { TenantContext } from "../types/tenant"
 import type {
   AccessTokenClaims,
@@ -50,6 +54,7 @@ import {
 import { buildIdTokenClaims, shouldIssueIdToken } from "./id-token"
 import { signAccessToken, signIdToken } from "./jwt"
 import { validatePkce } from "./pkce"
+import { validateSubjectClaim } from "./subject"
 
 /**
  * Encrypt a `CodePayload` with the active `KeyStore` encryption key and
@@ -104,9 +109,17 @@ export type ExchangeCodeDeps = {
   keyStore: KeyStore
   auditLog?: AuditLog
   success: (input: SuccessMapInput) => Promise<SubjectClaim>
+  /**
+   * The host's declared subject schemas. The claim `success()` returns is
+   * validated against these before anything is signed — see
+   * `domain/subject.ts` for why that is the library's job.
+   */
+  subjects: SubjectSchema
   persistUpstreamTokens?: PersistUpstreamTokens
   issuerUrl: string
   clock: () => number
+  /** See `IdPOptions.onTokenIssued`. Threaded to `mintTokens`. */
+  onTokenIssued?: OnTokenIssued
   newRefreshToken?: () => string
   /** Test override. */
   newRefreshFamily?: () => string
@@ -204,6 +217,23 @@ export async function exchangeCode(
     return err(authError.serverError("success callback threw", e))
   }
 
+  const checked = await validateSubjectClaim(deps.subjects, claim)
+  if (isErr(checked)) {
+    await safeAudit(deps, {
+      kind: "invalid_subject_claim",
+      tenantId: payload.tenantId,
+      clientId: payload.clientId,
+      subjectType: checked.error.rejection.subjectType,
+      reason: checked.error.rejection.reason,
+      detail: checked.error.rejection.detail,
+      timestamp: deps.clock(),
+    })
+    return err(checked.error)
+  }
+  // Parsed value from here on, so the token matches what the schema
+  // declares and what `client.verify()` returns to the RP.
+  claim = checked.value
+
   // 7. Optional upstream-tokens hook (runs after success, before
   //    mint — failed mints below should NOT roll back this hook because
   //    by contract the hook itself decides whether to persist).
@@ -285,6 +315,7 @@ export async function mintTokens(args: {
     auditLog?: AuditLog
     issuerUrl: string
     clock: () => number
+    onTokenIssued?: OnTokenIssued
     newRefreshToken?: () => string
     /**
      * Host-supplied vendor scope → claim-names map merged into the
@@ -314,6 +345,27 @@ export async function mintTokens(args: {
     receivingClient?.sectorIdentifier,
   )
 
+  // Hand the host the derived subject id *before* anything durable is
+  // written. `subjectId` exists nowhere else — it is signed as `sub` and
+  // is the key `revokeBySubject` takes — so a host that misses it holds a
+  // token it can never revoke. Running after `saveRefresh` and aborting
+  // on failure would leave precisely that: a live chain with no record.
+  if (deps.onTokenIssued) {
+    try {
+      await deps.onTokenIssued({
+        tenant,
+        clientId: payload.clientId,
+        subjectId,
+        claim,
+        // No refresh row is written when `skipRefresh` is set, so there
+        // is no chain for the host to revoke by family.
+        ...(skipRefresh ? {} : { family }),
+      })
+    } catch (e) {
+      return err(authError.serverError("onTokenIssued hook threw", e))
+    }
+  }
+
   const keyRes = await deps.keyStore.currentSigningKey()
   if (isErr(keyRes)) return err(keyRes.error)
   const signingKey = keyRes.value

package/src/http/context.ts

@@ -16,6 +16,8 @@ import type { SessionStore } from "../ports/session-store"
 import type { TokenStore } from "../ports/token-store"
 import type { MethodCache } from "../domain/method-cache"
 import type { AuthError } from "../types/error"
+import type { OnTokenIssued } from "../types/idp"
+import type { SubjectSchema } from "../types/subject"
 import type {
   ExchangeAudience,
   LogoutEventInput,
@@ -52,6 +54,10 @@ export type HttpDeps = {
   resolveIssuer: (req: Request) => string
   /** Optional partitioned-host helper (recovery #2). */
   callbackHostFor?: (tenantId: TenantId) => string
+  /** Host-declared subject schemas, validated at issuance. */
+  subjects: SubjectSchema
+  /** See `IdPOptions.onTokenIssued`. */
+  onTokenIssued?: OnTokenIssued
   resolveTenant: (req: Request) => Promise<Result<TenantId, AuthError>>
   success: (input: SuccessMapInput) => Promise<SubjectClaim>
   /** See `IdPOptions.onLogout` — upstream Single Logout host hook. */

package/src/http/handlers/token.ts

@@ -127,11 +127,13 @@ export function makeTokenHandler(deps: HttpDeps) {
           keyStore: deps.keyStore,
           ...(deps.auditLog ? { auditLog: deps.auditLog } : {}),
           success: deps.success,
+          subjects: deps.subjects,
           ...(deps.persistUpstreamTokens
             ? { persistUpstreamTokens: deps.persistUpstreamTokens }
             : {}),
           issuerUrl: c.get("issuerUrl"),
           clock: deps.clock,
+          ...(deps.onTokenIssued ? { onTokenIssued: deps.onTokenIssued } : {}),
           ...(deps.customScopeClaims !== undefined
             ? { customScopeClaims: deps.customScopeClaims }
             : {}),
@@ -174,11 +176,13 @@ export function makeTokenHandler(deps: HttpDeps) {
           ...(deps.auditLog ? { auditLog: deps.auditLog } : {}),
           methodCache: deps.methodCache,
           success: deps.success,
+          subjects: deps.subjects,
           ...(deps.persistUpstreamTokens
             ? { persistUpstreamTokens: deps.persistUpstreamTokens }
             : {}),
           issuerUrl: c.get("issuerUrl"),
           clock: deps.clock,
+          ...(deps.onTokenIssued ? { onTokenIssued: deps.onTokenIssued } : {}),
           ...(deps.customScopeClaims !== undefined
             ? { customScopeClaims: deps.customScopeClaims }
             : {}),
@@ -208,6 +212,7 @@ export function makeTokenHandler(deps: HttpDeps) {
           ...(deps.auditLog ? { auditLog: deps.auditLog } : {}),
           issuerUrl: c.get("issuerUrl"),
           clock: deps.clock,
+          ...(deps.onTokenIssued ? { onTokenIssued: deps.onTokenIssued } : {}),
           ...(deps.customScopeClaims !== undefined
             ? { customScopeClaims: deps.customScopeClaims }
             : {}),
@@ -248,6 +253,7 @@ export function makeTokenHandler(deps: HttpDeps) {
           : {}),
         issuerUrl: c.get("issuerUrl"),
         clock: deps.clock,
+        ...(deps.onTokenIssued ? { onTokenIssued: deps.onTokenIssued } : {}),
         ...(deps.customScopeClaims !== undefined
           ? { customScopeClaims: deps.customScopeClaims }
           : {}),

package/src/http/middleware/tenant.ts

@@ -17,7 +17,10 @@
  */
 import type { MiddlewareHandler } from "hono"
 
-import { verifyStateEnvelope } from "../../domain/state-envelope"
+import {
+  extractCallbackState,
+  verifyStateEnvelope,
+} from "../../domain/state-envelope"
 import { isErr } from "../../types/result"
 import type {
   TenantConfig,
@@ -174,7 +177,7 @@ async function runCallbackRecovery(
   req: Request,
   deps: HttpDeps,
 ): Promise<TenantRecovery> {
-  const state = await extractStateParam(req)
+  const state = await extractCallbackState(req)
   if (state) {
     const env = await verifyStateEnvelope(state, deps.stateKeys)
     if (env.ok) {
@@ -187,25 +190,3 @@ async function runCallbackRecovery(
   }
   return { kind: "fresh-request" }
 }
-
-/**
- * Pull `state` from the query for GET callbacks, or from a form body for
- * POST callbacks (Apple's `response_mode=form_post`). The body is cloned
- * so the handler can still read it.
- */
-async function extractStateParam(req: Request): Promise<string | null> {
-  const url = new URL(req.url)
-  const fromQuery = url.searchParams.get("state")
-  if (fromQuery) return fromQuery
-  if (req.method !== "POST") return null
-  const ct = req.headers.get("content-type") ?? ""
-  if (!ct.toLowerCase().startsWith("application/x-www-form-urlencoded")) {
-    return null
-  }
-  try {
-    const text = await req.clone().text()
-    return new URLSearchParams(text).get("state")
-  } catch {
-    return null
-  }
-}

package/src/index.ts

@@ -73,17 +73,16 @@ export type {
 
 export type {
   ExchangeAudience,
-  FailureEvent,
   IdP,
   IdPOptions,
   LogoutEventInput,
   LogoutHookResult,
+  OnTokenIssued,
   PersistUpstreamTokens,
   RegisterClient,
   RegisterClientRequest,
   RegisterClientResponse,
   RenderPicker,
-  SuccessEvent,
   SuccessMapInput,
 } from "./types/idp"
 
@@ -285,6 +284,8 @@ export function createIdP(opts: IdPOptions): IdP {
     ...(opts.callbackHostFor ? { callbackHostFor: opts.callbackHostFor } : {}),
     resolveTenant: opts.resolveTenant,
     success: opts.success,
+    subjects: opts.subjects,
+    ...(opts.onTokenIssued ? { onTokenIssued: opts.onTokenIssued } : {}),
     ...(opts.onLogout ? { onLogout: opts.onLogout } : {}),
     ...(opts.persistUpstreamTokens
       ? { persistUpstreamTokens: opts.persistUpstreamTokens }

package/src/ports/audit-log.ts

@@ -28,13 +28,24 @@ export type AuditEvent =
       flowId: string
     }
   | {
+      /**
+       * A method authenticated the end user and an authorization code was
+       * minted. Completes the `authorize_started` / `authorize_failed`
+       * pair, which shipped without it.
+       */
       kind: "authorize_succeeded"
       tenantId: TenantId
       clientId: string
       methodId: string
       methodKind: string
       flowId: string
-      subjectId: string
+      /**
+       * The **upstream** identifier the method returned. Deliberately not
+       * `subjectId`: the OIDC subject is derived from the host's
+       * `success()` claim at `/token`, which has not run yet. Correlate
+       * with `token_issued.subjectId` via `clientId` + `flowId`.
+       */
+      providerSubject: string
     }
   | {
       kind: "authorize_failed"
@@ -162,6 +173,20 @@ export type AuditEvent =
       /** Zod error path string. Never the raw config blob. */
       errorPath: string
     }
+  | {
+      /**
+       * `IdPOptions.success` returned a claim that violates the host's
+       * own `subjects` schema. A deployment fault, not RP behaviour —
+       * token issuance is refused. Carries paths, never values.
+       */
+      kind: "invalid_subject_claim"
+      tenantId: TenantId
+      clientId: string
+      subjectType: string
+      reason: "unknown-type" | "invalid-properties"
+      /** Standard Schema issue path, or the declared type list. */
+      detail: string
+    }
   | {
       kind: "unknown_method_kind"
       tenantId: TenantId