@_mustachio/openauth 0.13.2 → 0.14.0

package/dist/types/types/method.d.ts

@@ -107,6 +107,17 @@ export type MethodHandler<P, S> = (ctx: MethodContext<S>) => Promise<MethodResul
 export type MethodContext<S = unknown> = {
     /** The raw Web Fetch `Request`. Web standard, not Hono `Context`. */
     request: Request;
+    /**
+     * The issuer URL of this IdP, always present.
+     *
+     * Distinct from `dispatch.issuerUrl`, which is only populated for
+     * `GET /authorize`. Methods that render their own URLs — a form action
+     * re-rendered on a validation error, say — need it on every route, and
+     * must build those URLs with `mountedPath` so they carry the
+     * deployment's mount prefix. `ctx.request.url` is not a substitute: a
+     * proxy-stripped inbound URL has already lost that prefix.
+     */
+    issuerUrl: string;
     /** Path within the method's mount, e.g. `"/callback"` (without the `/<id>` prefix). */
     subPath: string;
     tenant: TenantContext;

package/dist/types/types/method.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"method.d.ts","sourceRoot":"","sources":["../../../src/types/method.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"method.d.ts","sourceRoot":"","sources":["../../../src/types/method.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,uBAAuB,CAAA;AAE/C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAA;AACxC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAA;AACxC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAA;AACtC,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AAEnE;;;;;;;;;GASG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO,IAAI;IACjD;;;OAGG;IACH,EAAE,EAAE,MAAM,CAAA;IACV;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,UAAU,CAAA;IAChB;;;;;OAKG;IACH,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAA;IAC3C;;;;;;;;;;;;;;OAcG;IACH,YAAY,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;IACpC;;;;;;;;;;;;;OAaG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAA;IAC7B;;;;OAIG;IACH,MAAM,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAA;CACrB,CAAA;AAED,MAAM,MAAM,aAAa,CAAC,CAAC,EAAE,CAAC,IAAI,CAChC,GAAG,EAAE,aAAa,CAAC,CAAC,CAAC,KAClB,OAAO,CAAC,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAA;AAEhC;;;;;;;;;;GAUG;AACH,MAAM,MAAM,aAAa,CAAC,CAAC,GAAG,OAAO,IAAI;IACvC,qEAAqE;IACrE,OAAO,EAAE,OAAO,CAAA;IAChB;;;;;;;;;OASG;IACH,SAAS,EAAE,MAAM,CAAA;IACjB,uFAAuF;IACvF,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,aAAa,CAAA;IACrB,2EAA2E;IAC3E,IAAI,EAAE,UAAU,GAAG,IAAI,CAAA;IACvB;;;OAGG;IACH,WAAW,EAAE,CAAC,GAAG,IAAI,CAAA;IACrB,6DAA6D;IAC7D,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACpC;;;;;;OAMG;IACH,QAAQ,EAAE,kBAAkB,GAAG,IAAI,CAAA;IACnC;;;;;;;;;;;;;;OAcG;IACH,aAAa,EAAE,aAAa,CAAA;CAC7B,CAAA;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B;;;OAGG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAA;IACrE;;;;OAIG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAA;IACzC,gEAAgE;IAChE,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAA;CAC3C,CAAA;AAED,4EAA4E;AAC5E,MAAM,MAAM,kBAAkB,GAAG;IAC/B;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAA;IACnB,iFAAiF;IACjF,SAAS,EAAE,MAAM,CAAA;CAClB,CAAA;AAED;;;;GAIG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO;AAC/C;;;;;;;;GAQG;AACD;IACE,IAAI,EAAE,WAAW,CAAA;IACjB,wEAAwE;IACxE,QAAQ,EAAE,QAAQ,CAAA;IAClB,UAAU,CAAC,EAAE,SAAS,EAAE,CAAA;IACxB,eAAe,CAAC,EAAE,CAAC,CAAA;IACnB,iEAAiE;IACjE,KAAK,CAAC,EAAE,WAAW,CAAA;IACnB;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,EAAE;QACP,MAAM,CAAC,EAAE,MAAM,CAAA;QACf,YAAY,CAAC,EAAE,MAAM,CAAA;KACtB,CAAA;CACF;AACH;;;;GAIG;GACD;IACE,IAAI,EAAE,SAAS,CAAA;IACf,2EAA2E;IAC3E,eAAe,EAAE,MAAM,CAAA;IACvB,UAAU,EAAE,CAAC,CAAA;IACb,UAAU,CAAC,EAAE,SAAS,EAAE,CAAA;IACxB;;;;;;;;;;;OAWG;IACH,kBAAkB,CAAC,EAAE;QACnB,QAAQ,EAAE,MAAM,CAAA;QAChB,WAAW,EAAE,MAAM,CAAA;QACnB,MAAM,EAAE,MAAM,EAAE,CAAA;KACjB,CAAA;CACF;AACH,6EAA6E;GAC3E;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,SAAS,EAAE,CAAA;CAAE;AAC9D,kFAAkF;GAChF;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,SAAS,CAAA;CAAE,CAAA;AAEvC;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,sDAAsD;IACtD,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,8BAA8B;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,qCAAqC;IACrC,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,8BAA8B;IAC9B,SAAS,CAAC,EAAE,OAAO,CAAA;CACpB,CAAA;AAED;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG;IACtB,IAAI,EAAE,MAAM,CAAA;IACZ,8CAA8C;IAC9C,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,QAAQ,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAA;CACrC,CAAA;AAED;;;;GAIG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE;IAChC,QAAQ,EAAE,MAAM,CAAA;IAChB,YAAY,EAAE,MAAM,CAAA;IACpB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAC/B,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC,CAAA;AAEnC;;;;;;;;;;;;;;GAcG;AAMH,MAAM,MAAM,oBAAoB,GAAG,iBAAiB,CAClD,GAAG,EAAE,6CAA6C;AAClD,GAAG,EAAE,2BAA2B;AAChC,GAAG,CACJ,CAAA;AAED,MAAM,MAAM,iBAAiB,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO,EAAE,GAAG,GAAG,OAAO,IAAI;IACvE,2FAA2F;IAC3F,IAAI,EAAE,MAAM,CAAA;IAEZ;;;;;;;;;;;;OAYG;IACH,YAAY,EAAE,EAAE,CAAC,cAAc,CAAC,OAAO,EAAE,GAAG,CAAC,CAAA;IAE7C;;;;;OAKG;IACH,KAAK,EAAE,CAAC,KAAK,EAAE;QACb,6EAA6E;QAC7E,EAAE,EAAE,MAAM,CAAA;QACV,mEAAmE;QACnE,IAAI,EAAE,MAAM,CAAA;QACZ,QAAQ,EAAE,QAAQ,CAAA;QAClB,wCAAwC;QACxC,MAAM,EAAE,GAAG,CAAA;KACZ,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAA;CAChC,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@_mustachio/openauth",
-  "version": "0.13.2",
+  "version": "0.14.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -11,6 +11,7 @@
     "build": "bun run script/build.ts",
     "build:watch": "bun run script/build-watch.ts",
     "test": "bun test",
+    "typecheck": "tsc --noEmit -p tsconfig.test.json",
     "preview:ui": "bun --hot run script/preview-ui.ts"
   },
   "sideEffects": false,

package/src/client.ts

@@ -149,6 +149,37 @@ export interface ClientInput {
    * ```
    */
   issuer?: string
+  /**
+   * The client secret, for **confidential** clients only.
+   *
+   * Supply this for a server-side app registered as a confidential client;
+   * `exchange()` and `refresh()` then authenticate at `/token`. Omit it for
+   * public clients (SPA, mobile, CLI) — a secret cannot be kept in code
+   * that ships to users, and the IdP requires PKCE there instead.
+   *
+   * Without this, a confidential client's `exchange()` is rejected with
+   * `invalid_client`: the token endpoint has no way to authenticate it.
+   *
+   * @example
+   * ```ts
+   * {
+   *   clientID: "my-server-app",
+   *   clientSecret: process.env.CLIENT_SECRET
+   * }
+   * ```
+   */
+  clientSecret?: string
+  /**
+   * How to present `clientSecret` at the token endpoint.
+   *
+   * `client_secret_basic` (the default) sends HTTP Basic credentials, which
+   * is what RFC 6749 §2.3.1 prefers and what the IdP parses first.
+   * `client_secret_post` puts them in the form body. Both are advertised in
+   * discovery as `token_endpoint_auth_methods_supported`.
+   *
+   * @default "client_secret_basic"
+   */
+  tokenEndpointAuthMethod?: "client_secret_basic" | "client_secret_post"
   /**
    * Optionally, override the internally used fetch function.
    *
@@ -159,18 +190,6 @@ export interface ClientInput {
 }
 
 export interface AuthorizeOptions {
-  /**
-   * Enable the PKCE flow. This is for SPA apps.
-   *
-   * ```ts
-   * {
-   *   pkce: true
-   * }
-   * ```
-   *
-   * @default false
-   */
-  pkce?: boolean
   /**
    * The provider you want to use for the OAuth flow.
    *
@@ -306,7 +325,13 @@ export interface VerifyOptions {
    */
   issuer?: string
   /**
-   * @internal
+   * The audience to require on the token.
+   *
+   * Defaults to this client's `clientID`, which is what the IdP puts in
+   * `aud` for an ordinary login. Set this when verifying a token minted
+   * for a **resource** — an `/authorize` call that passed `audience` puts
+   * that value in `aud` instead, so a resource server verifying it must
+   * name itself here.
    */
   audience?: string
   /**
@@ -320,9 +345,14 @@ export interface VerifyOptions {
 
 export interface VerifyResult<T extends SubjectSchema> {
   /**
-   * This is always `undefined` when the verify is successful.
+   * This is always `false` when the verify is successful.
+   *
+   * A literal, not an optional — `err?: undefined` would leave the
+   * property present on this arm, so `"err" in result` narrowed nothing
+   * and callers had to test truthiness instead. Matches `ExchangeSuccess`
+   * and `RefreshSuccess`.
    */
-  err?: undefined
+  err: false
   /**
    * Returns the refreshed tokens only if they’ve been refreshed.
    *
@@ -365,40 +395,30 @@ export interface VerifyError {
  */
 export interface Client {
   /**
-   * Start the autorization flow. For example, in SSR sites.
+   * Start the authorization code flow.
    *
    * ```ts
-   * const { url } = await client.authorize(<redirect_uri>, "code")
+   * const { challenge, url } = await client.authorize(<redirect_uri>)
+   * // store `challenge`, then redirect the user to `url`
    * ```
    *
-   * This takes a redirect URI and the type of flow you want to use. The redirect URI is the
-   * location where the user will be redirected to after the flow is complete.
-   *
-   * Supports both the _code_ and _token_ flows. We recommend using the _code_ flow as it's more
-   * secure.
-   *
-   * :::tip
-   * This returns a URL to redirect the user to. This starts the OAuth flow.
-   * :::
-   *
-   * This returns a URL to the auth server. You can redirect the user to the URL to start the
-   * OAuth flow.
+   * Returns the URL to send the user to, and a `challenge` carrying the
+   * CSRF `state` and the PKCE `verifier`. Persist the challenge (a cookie
+   * server-side, `sessionStorage` in a SPA) and hand the verifier back to
+   * {@link Client.exchange} when the user returns.
    *
-   * For SPA apps, we recommend using the PKCE flow.
-   *
-   * ```ts {4}
-   * const { challenge, url } = await client.authorize(
-   *   <redirect_uri>,
-   *   "code",
-   *   { pkce: true }
-   * )
-   * ```
+   * **PKCE is always used.** The IdP requires it for public clients, and
+   * OAuth 2.1 §7.5.1 recommends it for confidential ones too, so there is
+   * no reason to offer it as a toggle. Before 0.14.0 it was opt-in and
+   * off by default, which meant the documented server-side flow could not
+   * complete against a public client at all.
    *
-   * This returns a redirect URL and a challenge that you need to use later to verify the code.
+   * Only the authorization code flow is supported. The implicit flow
+   * (`response_type=token`) is removed in OAuth 2.1 and the IdP rejects
+   * it with `unsupported_response_type`.
    */
   authorize(
     redirectURI: string,
-    response: "code" | "token",
     opts?: AuthorizeOptions,
   ): Promise<AuthorizeResult>
   /**
@@ -593,74 +613,76 @@ export function createClient(input: ClientInput): Client {
     return result
   }
 
-  const result = {
-    async authorize(
-      redirectURI: string,
-      response: "code" | "token",
-      opts?: AuthorizeOptions,
+  /**
+   * Client authentication for the token endpoint (RFC 6749 §2.3.1).
+   * Applied only when a `clientSecret` is configured; public clients
+   * authenticate with PKCE instead and send neither.
+   */
+  function applyClientAuth(
+    headers: Record<string, string>,
+    body: URLSearchParams,
+  ) {
+    const secret = input.clientSecret
+    if (secret === undefined) return
+    if (
+      (input.tokenEndpointAuthMethod ?? "client_secret_basic") ===
+      "client_secret_post"
     ) {
-      const result = new URL(issuer + "/authorize")
+      body.set("client_secret", secret)
+      return
+    }
+    // §2.3.1 requires form-urlencoding each half before base64.
+    const cred = `${encodeURIComponent(input.clientID)}:${encodeURIComponent(secret)}`
+    headers["authorization"] = `Basic ${btoa(cred)}`
+  }
+
+  const result = {
+    async authorize(redirectURI: string, opts?: AuthorizeOptions) {
+      const wk = await getIssuer()
+      const url = new URL(wk.authorization_endpoint)
+      // PKCE unconditionally: required by the IdP for public clients, and
+      // recommended for confidential ones by OAuth 2.1 §7.5.1.
+      const pkce = await generatePKCE()
       const challenge: Challenge = {
         state: crypto.randomUUID(),
+        verifier: pkce.verifier,
       }
-      result.searchParams.set("client_id", input.clientID)
-      result.searchParams.set("redirect_uri", redirectURI)
-      result.searchParams.set("response_type", response)
-      result.searchParams.set("state", challenge.state)
-      if (opts?.provider) result.searchParams.set("provider", opts.provider)
+      url.searchParams.set("client_id", input.clientID)
+      url.searchParams.set("redirect_uri", redirectURI)
+      url.searchParams.set("response_type", "code")
+      url.searchParams.set("state", challenge.state)
+      url.searchParams.set("code_challenge_method", "S256")
+      url.searchParams.set("code_challenge", pkce.challenge)
+      if (opts?.provider) url.searchParams.set("provider", opts.provider)
       if (opts?.scope !== undefined) {
         const scope = Array.isArray(opts.scope)
           ? opts.scope.join(" ")
           : opts.scope
-        if (scope) result.searchParams.set("scope", scope)
-      }
-      if (opts?.pkce && response === "code") {
-        const pkce = await generatePKCE()
-        result.searchParams.set("code_challenge_method", "S256")
-        result.searchParams.set("code_challenge", pkce.challenge)
-        challenge.verifier = pkce.verifier
-      }
-      return {
-        challenge,
-        url: result.toString(),
+        if (scope) url.searchParams.set("scope", scope)
       }
-    },
-    /**
-     * @deprecated use `authorize` instead, it will do pkce by default unless disabled with `opts.pkce = false`
-     */
-    async pkce(
-      redirectURI: string,
-      opts?: {
-        provider?: string
-      },
-    ) {
-      const result = new URL(issuer + "/authorize")
-      if (opts?.provider) result.searchParams.set("provider", opts.provider)
-      result.searchParams.set("client_id", input.clientID)
-      result.searchParams.set("redirect_uri", redirectURI)
-      result.searchParams.set("response_type", "code")
-      const pkce = await generatePKCE()
-      result.searchParams.set("code_challenge_method", "S256")
-      result.searchParams.set("code_challenge", pkce.challenge)
-      return [pkce.verifier, result.toString()]
+      return { challenge, url: url.toString() }
     },
     async exchange(
       code: string,
       redirectURI: string,
       verifier?: string,
     ): Promise<ExchangeSuccess | ExchangeError> {
-      const tokens = await f(issuer + "/token", {
+      const wk = await getIssuer()
+      const body = new URLSearchParams({
+        code,
+        redirect_uri: redirectURI,
+        grant_type: "authorization_code",
+        client_id: input.clientID,
+      })
+      if (verifier) body.set("code_verifier", verifier)
+      const headers: Record<string, string> = {
+        "Content-Type": "application/x-www-form-urlencoded",
+      }
+      applyClientAuth(headers, body)
+      const tokens = await f(wk.token_endpoint, {
         method: "POST",
-        headers: {
-          "Content-Type": "application/x-www-form-urlencoded",
-        },
-        body: new URLSearchParams({
-          code,
-          redirect_uri: redirectURI,
-          grant_type: "authorization_code",
-          client_id: input.clientID,
-          code_verifier: verifier || "",
-        }).toString(),
+        headers,
+        body: body.toString(),
       })
       const json = (await tokens.json()) as any
       if (!tokens.ok) {
@@ -698,15 +720,24 @@ export function createClient(input: ClientInput): Client {
           }
         }
       }
-      const tokens = await f(issuer + "/token", {
+      const wk = await getIssuer()
+      // `client_id` was previously omitted here too. The IdP rejects a
+      // confidential client's refresh outright when the request carries no
+      // client identity (RFC 6749 §6), so rotation was unreachable for
+      // exactly the clients that most need it.
+      const body = new URLSearchParams({
+        grant_type: "refresh_token",
+        refresh_token: refresh,
+        client_id: input.clientID,
+      })
+      const headers: Record<string, string> = {
+        "Content-Type": "application/x-www-form-urlencoded",
+      }
+      applyClientAuth(headers, body)
+      const tokens = await f(wk.token_endpoint, {
         method: "POST",
-        headers: {
-          "Content-Type": "application/x-www-form-urlencoded",
-        },
-        body: new URLSearchParams({
-          grant_type: "refresh_token",
-          refresh_token: refresh,
-        }).toString(),
+        headers,
+        body: body.toString(),
       })
       const json = (await tokens.json()) as any
       if (!tokens.ok) {
@@ -733,55 +764,40 @@ export function createClient(input: ClientInput): Client {
     ): Promise<VerifyResult<T> | VerifyError> {
       const jwks = await getJWKS()
       try {
-        // Two issuer shapes are supported:
-        //
-        //   1. New `createIdP` — `AccessTokenClaims.claim = { type,
-        //      properties }`. No `mode` claim.
-        //   2. Legacy `issuer({...})` — `payload.type` / `payload.properties`
-        //      at the top level, gated by `payload.mode === "access"` so the
-        //      same key ring couldn't sign a refresh token that verified as
-        //      an access token.
+        // RFC 9068 §4 / RFC 7519 §4.1.3 — `aud` MUST be checked. Until
+        // 0.14.0 only `iss` was, so any client sharing an issuer accepted
+        // any other client's token: a confused deputy across every RP on
+        // the deployment.
         //
-        // Prefer the nested shape, fall back to the top-level shape.
+        // The IdP sets `aud` to the requested `audience` when one was
+        // asked for at /authorize, and to the client id otherwise — so a
+        // resource server verifying a resource-scoped token passes its own
+        // identifier via `options.audience`, and everyone else gets the
+        // right default for free.
         const result = await jwtVerify<{
           claim?: {
             type: keyof T
             properties: v1.InferInput<T[keyof T]>
           }
-          mode?: "access" | "refresh"
-          type?: keyof T
-          properties?: v1.InferInput<T[keyof T]>
         }>(token, jwks, {
           issuer,
+          audience: options?.audience ?? input.clientID,
         })
         const claim = result.payload.claim
-        let subjectType: keyof T | undefined
-        let subjectProperties: v1.InferInput<T[keyof T]> | undefined
-        if (claim && typeof claim.type === "string") {
-          // New shape — `mode` is not emitted; nested claim is authoritative.
-          subjectType = claim.type
-          subjectProperties = claim.properties
-        } else if (
-          result.payload.mode === "access" &&
-          typeof result.payload.type === "string"
-        ) {
-          // Legacy shape — keep the mode gate so a refresh-token payload
-          // signed under the same keys does not verify as an access token.
-          subjectType = result.payload.type
-          subjectProperties = result.payload.properties
-        }
-        if (subjectType === undefined) {
+        if (!claim || typeof claim.type !== "string") {
           return { err: new InvalidSubjectError() }
         }
+        const subjectType = claim.type
         const schema = subjects[subjectType]
         if (!schema) {
           return { err: new InvalidSubjectError() }
         }
-        const validated = await schema["~standard"].validate(subjectProperties)
+        const validated = await schema["~standard"].validate(claim.properties)
         if (validated.issues) {
           return { err: new InvalidSubjectError() }
         }
         return {
+          err: false,
           aud: result.payload.aud as string,
           subject: {
             type: subjectType,

package/src/domain/authorize.ts

@@ -51,6 +51,7 @@ import { safeAudit } from "./audit"
 import { randomId, randomToken } from "./crypto"
 import { MethodCache } from "./method-cache"
 import { dispatchMethod } from "./method-dispatch"
+import { callbackTarget } from "./mount"
 import { mintStateEnvelope } from "./state-envelope"
 import { saveEncryptedCode } from "./token"
 
@@ -200,10 +201,19 @@ export async function startAuthorize(
   const nonce = (deps.newNonce ?? randomToken)()
   const flowTtl = deps.flowTtlMs ?? DEFAULT_FLOW_TTL_MS
   const now = deps.clock()
-  const callbackHost =
-    deps.callbackHostFor?.(tenant.id) ?? new URL(deps.issuerUrl).host
-  const callbackPath = `/cb/${methodId}`
-  const callbackUrl = `${new URL(deps.issuerUrl).protocol}//${callbackHost}${callbackPath}`
+  // Source of truth for callback derivation — every other site that needs
+  // this URL goes through `callbackTarget` so they cannot drift apart.
+  // Note `path` is the *inbound* route (no mount prefix; the proxy strips
+  // it before we see the request) while `url` is the public form.
+  const {
+    host: callbackHost,
+    path: callbackPath,
+    url: callbackUrl,
+  } = callbackTarget({
+    issuerUrl: deps.issuerUrl,
+    methodId,
+    callbackHost: deps.callbackHostFor?.(tenant.id),
+  })
 
   const record: FlowRecord = {
     flowId,
@@ -262,6 +272,7 @@ export async function startAuthorize(
     flow: record,
     cookies: input.cookies,
     sessionStore: deps.sessionStore,
+    issuerUrl: deps.issuerUrl,
     dispatch: {
       state: stateEnvelope,
       callbackUrl,
@@ -402,6 +413,16 @@ async function issueCodeFromInlineSuccess(
     { keyStore: deps.keyStore, tokenStore: deps.tokenStore },
   )
   if (isErr(saved)) return err(saved.error)
+  await safeAudit(deps, {
+    kind: "authorize_succeeded",
+    tenantId: flow.tenantId,
+    clientId: flow.clientId,
+    methodId: flow.methodId,
+    methodKind: flow.methodKind,
+    flowId: flow.flowId,
+    providerSubject: result.providerSubject,
+    timestamp: now,
+  })
   return ok({
     kind: "issue-code",
     code,

package/src/domain/callback.ts

@@ -35,8 +35,9 @@ import { safeAudit } from "./audit"
 import { randomToken } from "./crypto"
 import { MethodCache } from "./method-cache"
 import { dispatchMethod } from "./method-dispatch"
+import { callbackTarget } from "./mount"
 import { saveEncryptedCode } from "./token"
-import { verifyStateEnvelope } from "./state-envelope"
+import { extractCallbackState, verifyStateEnvelope } from "./state-envelope"
 import { AUTH_CODE_TTL_MS } from "./authorize"
 
 export type CallbackOutput =
@@ -67,12 +68,13 @@ export type HandleCallbackInput = {
    */
   tenant?: TenantContext
   /**
-   * Per-request issuer URL (HTTP layer). Used only by the
-   * IdP-initiated path to derive the SP entityID / ACS — the same
-   * derivation the AuthnRequest and metadata paths use, so the values
-   * cannot drift.
+   * Per-request issuer URL (HTTP layer). The IdP-initiated path derives
+   * the SP entityID / ACS from it — the same derivation the AuthnRequest
+   * and metadata paths use, so the values cannot drift — and every
+   * dispatched method receives it as `MethodContext.issuerUrl` to build
+   * mount-prefixed URLs of its own.
    */
-  issuerUrl?: string
+  issuerUrl: string
 }
 
 export type HandleCallbackDeps = {
@@ -96,34 +98,6 @@ export type HandleCallbackDeps = {
   ) => Record<string, unknown> | Promise<Record<string, unknown>>
 }
 
-/**
- * The framework's MAC state 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
- * pre-existing behaviour when the query param is absent.
- */
-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.includes("application/x-www-form-urlencoded")) return null
-  try {
-    const body = await req.clone().text()
-    const form = new URLSearchParams(body)
-    const v = form.get("state") ?? form.get("RelayState")
-    return v && v.length > 0 ? v : null
-  } catch {
-    return null
-  }
-}
-
 export async function handleCallback(
   input: HandleCallbackInput,
   deps: HandleCallbackDeps,
@@ -241,6 +215,7 @@ export async function handleCallback(
     flow,
     cookies: input.cookies,
     sessionStore: deps.sessionStore,
+    issuerUrl: input.issuerUrl,
     dispatch: null,
   })
   if (isErr(dispatched)) return err(dispatched.error)
@@ -282,6 +257,16 @@ async function translate(
         { keyStore: deps.keyStore, tokenStore: deps.tokenStore },
       )
       if (isErr(saved)) return err(saved.error)
+      await safeAudit(deps, {
+        kind: "authorize_succeeded",
+        tenantId: flow.tenantId,
+        clientId: flow.clientId,
+        methodId: flow.methodId,
+        methodKind: flow.methodKind,
+        flowId: flow.flowId,
+        providerSubject: result.providerSubject,
+        timestamp: now,
+      })
       return ok({
         kind: "issue-code",
         code,
@@ -351,7 +336,7 @@ async function tryIdpInitiated(
   url: URL,
 ): Promise<Result<CallbackOutput, AuthError> | null> {
   if (input.rawRequest.method !== "POST") return null
-  if (!input.tenant || !input.issuerUrl) return null
+  if (!input.tenant) return null
 
   const segments = url.pathname.split("/").filter(Boolean)
   if (segments.length < 2 || segments[0] !== "cb") return null
@@ -365,7 +350,14 @@ async function tryIdpInitiated(
   const method = methodRes.value
   if (method.unsolicitedCallback !== true) return null
 
-  const callbackUrl = `${url.protocol}//${url.host}/cb/${methodId}`
+  // Derived from `issuerUrl`, not the inbound request URL: a path-mounted
+  // deployment sees a proxy-stripped pathname, so rebuilding from `url`
+  // would emit a callback URL missing the mount prefix.
+  const { url: callbackUrl } = callbackTarget({
+    issuerUrl: input.issuerUrl,
+    methodId,
+    callbackHost: url.host,
+  })
   const dispatched = await dispatchMethod({
     method,
     route: "GET /callback",
@@ -375,6 +367,7 @@ async function tryIdpInitiated(
     flow: null,
     cookies: input.cookies,
     sessionStore: deps.sessionStore,
+    issuerUrl: input.issuerUrl,
     dispatch: { state: "", callbackUrl, issuerUrl: input.issuerUrl },
   })
   if (isErr(dispatched)) return err(dispatched.error)
@@ -463,6 +456,17 @@ async function tryIdpInitiated(
     { keyStore: deps.keyStore, tokenStore: deps.tokenStore },
   )
   if (isErr(saved)) return err(saved.error)
+  await safeAudit(deps, {
+    kind: "authorize_succeeded",
+    tenantId: input.tenant.id,
+    clientId: binding.clientId,
+    methodId,
+    methodKind: method.kind,
+    // Unsolicited: there is no FlowRecord, so no flowId to correlate on.
+    flowId: "",
+    providerSubject: result.providerSubject,
+    timestamp: now,
+  })
   return ok({
     kind: "issue-code",
     code,

package/src/domain/client-credentials.ts

@@ -25,7 +25,7 @@ import { authError, type 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, TenantId } from "../types/tenant"
 import type { TokenResponse } from "../types/token"
 
@@ -33,6 +33,8 @@ import { verifyClientCredentials } from "./client-auth"
 import { randomId } from "./crypto"
 import { mintTokens } from "./token"
 import { MethodCache } from "./method-cache"
+import { safeAudit } from "./audit"
+import { validateSubjectClaim } from "./subject"
 
 export type ClientCredentialsRequest = {
   grantType: "client_credentials"
@@ -50,6 +52,8 @@ export type ClientCredentialsDeps = {
   auditLog?: AuditLog
   methodCache: MethodCache
   success: (input: SuccessMapInput) => Promise<SubjectClaim>
+  /** Host-declared subject schemas; the claim is validated against them. */
+  subjects: SubjectSchema
   persistUpstreamTokens?: PersistUpstreamTokens
   issuerUrl: string
   clock: () => number
@@ -156,6 +160,21 @@ export async function clientCredentialsGrant(
     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: tenant.id,
+      clientId: client.id,
+      subjectType: checked.error.rejection.subjectType,
+      reason: checked.error.rejection.reason,
+      detail: checked.error.rejection.detail,
+      timestamp: deps.clock(),
+    })
+    return err(checked.error)
+  }
+  claim = checked.value
+
   // 6. Mint access only — RFC 6749 §4.4.3 says client_credentials SHOULD
   //    NOT issue a refresh token. `skipRefresh: true` keeps the token-
   //    store from accumulating orphaned rows that the response would