@_mustachio/openauth 0.13.3 → 0.14.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.ts

@@ -27,7 +27,7 @@ import { authError } from "../types/error"
 import type { 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 +50,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,6 +105,12 @@ 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
@@ -204,6 +211,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).

package/src/http/context.ts

@@ -16,6 +16,7 @@ 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 { SubjectSchema } from "../types/subject"
 import type {
   ExchangeAudience,
   LogoutEventInput,
@@ -52,6 +53,8 @@ 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
   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,6 +127,7 @@ export function makeTokenHandler(deps: HttpDeps) {
           keyStore: deps.keyStore,
           ...(deps.auditLog ? { auditLog: deps.auditLog } : {}),
           success: deps.success,
+          subjects: deps.subjects,
           ...(deps.persistUpstreamTokens
             ? { persistUpstreamTokens: deps.persistUpstreamTokens }
             : {}),
@@ -174,6 +175,7 @@ export function makeTokenHandler(deps: HttpDeps) {
           ...(deps.auditLog ? { auditLog: deps.auditLog } : {}),
           methodCache: deps.methodCache,
           success: deps.success,
+          subjects: deps.subjects,
           ...(deps.persistUpstreamTokens
             ? { persistUpstreamTokens: deps.persistUpstreamTokens }
             : {}),

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,7 +73,6 @@ export type {
 
 export type {
   ExchangeAudience,
-  FailureEvent,
   IdP,
   IdPOptions,
   LogoutEventInput,
@@ -83,7 +82,6 @@ export type {
   RegisterClientRequest,
   RegisterClientResponse,
   RenderPicker,
-  SuccessEvent,
   SuccessMapInput,
 } from "./types/idp"
 
@@ -285,6 +283,7 @@ export function createIdP(opts: IdPOptions): IdP {
     ...(opts.callbackHostFor ? { callbackHostFor: opts.callbackHostFor } : {}),
     resolveTenant: opts.resolveTenant,
     success: opts.success,
+    subjects: opts.subjects,
     ...(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

package/src/types/idp.ts

@@ -46,30 +46,6 @@ export type SuccessMapInput = {
   context: Record<string, unknown> | null
 }
 
-/**
- * Optional observation hook payload — fires after the subject claim has
- * already been minted. **Does not** influence the issued subject; use it
- * for audit, analytics, side effects only.
- */
-export type SuccessEvent = SuccessMapInput & {
-  /** The final subject claim that became the JWT `sub`. */
-  claim: SubjectClaim
-}
-
-/**
- * Optional observation hook payload — fires on a failed auth attempt.
- * Carries enough id information for operators to find the offending flow
- * / config row without leaking secrets.
- */
-export type FailureEvent = {
-  tenantId: TenantId | null
-  clientId: string | null
-  methodId?: string
-  methodKind?: string
-  flowId?: string
-  error: AuthError
-}
-
 /**
  * Input to the optional `IdPOptions.onLogout` hook.
  *
@@ -217,19 +193,41 @@ export type RegisterClientResponse = {
 /**
  * Optional Dynamic Client Registration hook. Hosts that want to expose
  * RFC 7591 client provisioning supply this; the framework validates the
- * wire format, then defers persistence to the host. If absent, the
- * `/register` endpoint returns `invalid_request` so RPs receive a clear
- * "not enabled" signal rather than a 404.
+ * wire format and mints credentials, then defers **persistence** to the
+ * host. If absent, the `/register` endpoint returns `invalid_request` so
+ * RPs receive a clear "not enabled" signal rather than a 404.
  *
- * The hook receives the parsed request, the resolved tenant, and the
- * plaintext client secret (if any) the framework minted — hosts hash it
- * with `hashClientSecret` before storing on `ClientConfig.secretHash`,
- * then return the final `ClientConfig` along with the secret in the
- * `RegisterClientResponse` so the RP can record it.
+ * The library owns credential generation — entropy, hashing, and the
+ * `ClientConfig` discriminated union, which requires `pkceRequired: true`
+ * as a literal on public clients and a `secretHash` on confidential ones.
+ * Those are protocol and security concerns, and making every host
+ * reimplement them is how they get done wrong. The host owns the table:
+ * write `client` through your own `ConfigStore` and return it.
+ *
+ * Before 0.14.0 this hook received only `{ tenant, request }` and the
+ * framework discarded what it had generated, so hosts had to mint their
+ * own — contradicting both this doc comment and `ARCHITECTURE.md`.
+ *
+ * Return the config you actually persisted. Adjusting it first is fine
+ * (narrowing `scopes`, substituting your own `id`); if you replace `id`
+ * or `secretHash`, return the matching plaintext as `secret` so the RP
+ * receives something that works.
  */
 export type RegisterClient = (input: {
   tenant: TenantContext
   request: RegisterClientRequest
+  /**
+   * Framework-minted `ClientConfig`, ready to persist as-is. Public
+   * clients carry `pkceRequired: true`; confidential clients carry
+   * `secretHash` for `secret` below.
+   */
+  client: ClientConfig
+  /**
+   * Plaintext secret matching `client.secretHash`. Present only for
+   * confidential clients. Return it in the result so the RP can record
+   * it — this is the only time it exists.
+   */
+  secret?: string
 }) => Promise<Result<{ client: ClientConfig; secret?: string }, AuthError>>
 
 /**
@@ -328,12 +326,6 @@ export type IdPOptions = {
 
   theme?: ThemeConfig
 
-  hooks?: {
-    /** Observation only — does NOT influence the subject. */
-    onSuccess?: (event: SuccessEvent) => Promise<void>
-    onFailure?: (event: FailureEvent) => Promise<void>
-  }
-
   /**
    * Optional hook fired when an upstream provider signals that a
    * federated session ended — SAML front-channel Single Logout today.
@@ -342,9 +334,9 @@ export type IdPOptions = {
    * 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`.
+   * Unlike `AuditLog` (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