@_mustachio/openauth 0.13.3 → 0.15.0

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

@@ -413,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

@@ -37,7 +37,7 @@ 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 =
@@ -98,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,
@@ -285,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,
@@ -474,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

@@ -22,10 +22,14 @@ 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 { 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, TenantId } from "../types/tenant"
 import type { TokenResponse } from "../types/token"
 
@@ -33,6 +37,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,9 +56,13 @@ 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
+  /** See `IdPOptions.onTokenIssued`. Threaded to `mintTokens`. */
+  onTokenIssued?: OnTokenIssued
   newRefreshFamily?: () => string
   /** See `IdPOptions.customScopeClaims`. Forwarded to `mintTokens`. */
   customScopeClaims?: Record<string, ReadonlyArray<string>>
@@ -156,6 +166,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

package/src/domain/method-route.ts

@@ -192,6 +192,16 @@ async function translate(
         { keyStore: deps.keyStore, tokenStore: deps.tokenStore },
       )
       if (isErr(saved)) return err(saved.error)
+      await safeAudit(deps, {
+        kind: "authorize_succeeded",
+        tenantId: final.tenantId,
+        clientId: final.clientId,
+        methodId: final.methodId,
+        methodKind: final.methodKind,
+        flowId: final.flowId,
+        providerSubject: result.providerSubject,
+        timestamp: now,
+      })
       return ok({
         kind: "issue-code",
         code,

package/src/domain/refresh.ts

@@ -17,6 +17,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 { OnTokenIssued } from "../types/idp"
 import type { Result } from "../types/result"
 import { err, isErr } from "../types/result"
 import type { TenantContext } from "../types/tenant"
@@ -50,6 +51,8 @@ export type RefreshTokensDeps = {
   auditLog?: AuditLog
   issuerUrl: string
   clock: () => number
+  /** See `IdPOptions.onTokenIssued`. Threaded to `mintTokens`. */
+  onTokenIssued?: OnTokenIssued
   /** Reuse-detection window (ms). Default 60 s. */
   reuseWindowMs?: number
   newRefreshToken?: () => string
@@ -57,6 +60,26 @@ export type RefreshTokensDeps = {
   customScopeClaims?: Record<string, ReadonlyArray<string>>
 }
 
+/**
+ * Requested scopes must be a subset of what the grant carries (RFC 6749
+ * §6). Returns the error rather than throwing so both call sites -- the
+ * pre-consume gate and the post-consume re-check -- read identically.
+ */
+function validateRequestedScopes(
+  requested: string | undefined,
+  granted: string[],
+): AuthError | null {
+  if (!requested) return null
+  for (const s of requested.split(" ").filter(Boolean)) {
+    if (!granted.includes(s)) {
+      return authError.invalidScope(
+        `requested scope "${s}" not granted by original refresh token`,
+      )
+    }
+  }
+  return null
+}
+
 export async function refreshTokens(
   req: RefreshGrantRequest,
   deps: RefreshTokensDeps,
@@ -123,6 +146,16 @@ export async function refreshTokens(
     }
   }
 
+  // Scope narrowing is validated against the *peeked* grant, before the
+  // token is consumed. Same reasoning as the client-auth and DPoP gates
+  // above: a request the grant cannot satisfy must not burn the token,
+  // or a client typo makes the next legitimate refresh look like theft
+  // and can revoke the whole family. `consumeRefresh` stays the
+  // authoritative atomic gate immediately below (TokenStore port:
+  // "callers race peekRefresh then consumeRefresh").
+  const scopeErr = validateRequestedScopes(req.scope, peekedPayload.scopes)
+  if (scopeErr) return err(scopeErr)
+
   const consumed = await deps.tokenStore.consumeRefresh(req.refreshToken, {
     reuseWindowMs: deps.reuseWindowMs,
   })
@@ -147,19 +180,18 @@ export async function refreshTokens(
   }
   const payload = consumed.value
 
-  // Narrow scope if requested (must be subset of original).
+  // Re-check against the consumed payload, which the port declares
+  // authoritative. In practice this cannot diverge from the peeked
+  // grant -- rotation preserves scopes -- so this is defence in depth,
+  // not the user-facing gate; that already ran above without burning.
+  const authoritativeScopeErr = validateRequestedScopes(
+    req.scope,
+    payload.scopes,
+  )
+  if (authoritativeScopeErr) return err(authoritativeScopeErr)
   const requestedScopes = req.scope
     ? req.scope.split(" ").filter(Boolean)
     : payload.scopes
-  for (const s of requestedScopes) {
-    if (!payload.scopes.includes(s)) {
-      return err(
-        authError.invalidScope(
-          `requested scope "${s}" not granted by original refresh token`,
-        ),
-      )
-    }
-  }
 
   const tenant: TenantContext = {
     id: payload.tenantId,