@_mustachio/openauth 0.10.0 → 0.12.0

package/src/client.ts

@@ -91,6 +91,14 @@ export interface Tokens {
    * The number of seconds until the access token expires.
    */
   expiresIn: number
+
+  /**
+   * The OIDC `id_token` (signed JWT), present when `scope=openid` was granted.
+   *
+   * Refresh-grant rotation reissues this with a stable `auth_time` per
+   * OIDC Core §12 and deliberately omits the original `nonce`.
+   */
+  idToken?: string
 }
 
 interface ResponseLike {
@@ -178,6 +186,18 @@ export interface AuthorizeOptions {
    * If there's only one provider configured, the user will be redirected to that.
    */
   provider?: string
+  /**
+   * OAuth scopes to request, e.g. `["openid", "email", "profile"]`.
+   *
+   * Pass `openid` to request an `id_token` at `/token` (OIDC Core §2). Pass
+   * `email` / `profile` / `phone` / `address` to opt into the standard §5.4
+   * profile claim sets on the id_token and `/userinfo` response.
+   *
+   * Accepts an array or a pre-joined space-separated string. When omitted,
+   * no `scope` is sent — the IdP's default grant applies, which typically
+   * does NOT include `openid` and therefore does NOT issue an id_token.
+   */
+  scope?: string | string[]
 }
 
 export interface AuthorizeResult {
@@ -588,6 +608,12 @@ export function createClient(input: ClientInput): Client {
       result.searchParams.set("response_type", response)
       result.searchParams.set("state", challenge.state)
       if (opts?.provider) result.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")
@@ -648,6 +674,9 @@ export function createClient(input: ClientInput): Client {
           access: json.access_token as string,
           refresh: json.refresh_token as string,
           expiresIn: json.expires_in as number,
+          ...(typeof json.id_token === "string"
+            ? { idToken: json.id_token as string }
+            : {}),
         },
       }
     },
@@ -691,6 +720,9 @@ export function createClient(input: ClientInput): Client {
           access: json.access_token as string,
           refresh: json.refresh_token as string,
           expiresIn: json.expires_in as number,
+          ...(typeof json.id_token === "string"
+            ? { idToken: json.id_token as string }
+            : {}),
         },
       }
     },

package/src/domain/authorize.ts

@@ -221,6 +221,10 @@ export async function startAuthorize(
     prompt: req.prompt,
     uiLocales: req.uiLocales,
     nonce,
+    ...(req.nonce !== undefined ? { appNonce: req.nonce } : {}),
+    ...(req.claimsRequest !== undefined
+      ? { claimsRequest: req.claimsRequest }
+      : {}),
     clientPkce: req.codeChallenge
       ? { challenge: req.codeChallenge, method: "S256" }
       : undefined,
@@ -387,6 +391,11 @@ async function issueCodeFromInlineSuccess(
       context: flow.context ?? null,
       providerSubject: result.providerSubject,
       properties: result.properties,
+      ...(flow.appNonce !== undefined ? { appNonce: flow.appNonce } : {}),
+      ...(flow.claimsRequest !== undefined
+        ? { claimsRequest: flow.claimsRequest }
+        : {}),
+      authTime: Math.floor(now / 1000),
       expiresAt: now + AUTH_CODE_TTL_MS,
     },
     AUTH_CODE_TTL_MS,

package/src/domain/callback.ts

@@ -58,6 +58,21 @@ export type HandleCallbackInput = {
   /** The raw `Request` for the upstream provider's redirect. */
   rawRequest: Request
   cookies: ReadonlyMap<string, string>
+  /**
+   * Resolved tenant for this request. The SP-initiated path derives
+   * the tenant from the consumed flow and ignores this. The
+   * **IdP-initiated** path (unsolicited POST, no flow) has nothing to
+   * derive from, so it uses this — populated by the HTTP layer from
+   * the tenant middleware. Absent ⇒ IdP-initiated is not attempted.
+   */
+  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.
+   */
+  issuerUrl?: string
 }
 
 export type HandleCallbackDeps = {
@@ -81,24 +96,73 @@ 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,
 ): Promise<Result<CallbackOutput, AuthError>> {
   const url = new URL(input.rawRequest.url)
-  const state = url.searchParams.get("state")
-  if (!state) {
-    return err(authError.invalidRequest("missing state parameter", "state"))
-  }
-  const envelopeRes = await verifyStateEnvelope(state, deps.stateKeys)
-  if (isErr(envelopeRes)) {
+  const state = await extractCallbackState(input.rawRequest)
+  // A SAML IdP-initiated POST may legitimately carry a `RelayState`
+  // (Okta/Entra deep-link tokens), so "RelayState present" does NOT
+  // imply "framework state envelope present". The envelope is only
+  // real if it MAC-verifies. When there is no verifiable envelope —
+  // none at all, or a value that fails verification — first try
+  // IdP-initiated (the only flowless path). Only if that is not a
+  // clean candidate do we emit the original error/audit, unchanged
+  // for every method that did not opt into `unsolicitedCallback`.
+  const envelopeRes = state
+    ? await verifyStateEnvelope(state, deps.stateKeys)
+    : null
+  if (envelopeRes === null || isErr(envelopeRes)) {
+    const idp = await tryIdpInitiated(input, deps, url)
+    if (idp) return idp
+    if (!state) {
+      return err(authError.invalidRequest("missing state parameter", "state"))
+    }
+    // State present but no valid envelope and not an IdP-init
+    // candidate — the original tampered/expired-envelope behaviour.
     await safeAudit(deps, {
       kind: "flow_replay_attempt",
       tenantId: null,
       flowId: "unknown",
       timestamp: deps.clock(),
     })
-    return err(authError.invalidRequest(envelopeRes.error.description, "state"))
+    return err(
+      authError.invalidRequest(
+        envelopeRes && isErr(envelopeRes)
+          ? envelopeRes.error.description
+          : "invalid state",
+        "state",
+      ),
+    )
   }
   const envelope = envelopeRes.value
 
@@ -207,6 +271,11 @@ async function translate(
           context: flow.context ?? null,
           providerSubject: result.providerSubject,
           properties: result.properties,
+          ...(flow.appNonce !== undefined ? { appNonce: flow.appNonce } : {}),
+          ...(flow.claimsRequest !== undefined
+            ? { claimsRequest: flow.claimsRequest }
+            : {}),
+          authTime: Math.floor(now / 1000),
           expiresAt: now + AUTH_CODE_TTL_MS,
         },
         AUTH_CODE_TTL_MS,
@@ -258,6 +327,150 @@ async function translate(
   }
 }
 
+/**
+ * IdP-initiated (unsolicited) SAML SSO — SAML-AD7, the one carve-out
+ * vs. OAuth/OIDC methods. There is no AuthnRequest, no MAC state
+ * envelope, and no flow record, so none of `handleCallback`'s gates
+ * apply. Returns `null` when this is **not** a clean IdP-init candidate
+ * (so the caller emits the normal "missing state" error — the
+ * conservative default); otherwise a final `CallbackOutput`.
+ *
+ * Trust chain (no flow to lean on):
+ *   - the assertion itself is signature/issuer/audience/conditions
+ *     verified by the method (`consumeAssertion`, IdP-init mode) plus
+ *     explicit assertion-ID replay dedup;
+ *   - the RP binding is NOT attacker-influenced — it comes from the
+ *     method's `unsolicitedBinding` (operator config), and is then
+ *     re-validated here against the tenant's registered client +
+ *     redirect URIs (open-redirect defence-in-depth). `RelayState` is
+ *     never interpreted as a redirect.
+ */
+async function tryIdpInitiated(
+  input: HandleCallbackInput,
+  deps: HandleCallbackDeps,
+  url: URL,
+): Promise<Result<CallbackOutput, AuthError> | null> {
+  if (input.rawRequest.method !== "POST") return null
+  if (!input.tenant || !input.issuerUrl) return null
+
+  const segments = url.pathname.split("/").filter(Boolean)
+  if (segments.length < 2 || segments[0] !== "cb") return null
+  const methodId = segments[1]!
+
+  const methodRes = await deps.methodCache.resolve(
+    input.tenant.config,
+    methodId,
+  )
+  if (isErr(methodRes)) return null
+  const method = methodRes.value
+  if (method.unsolicitedCallback !== true) return null
+
+  const callbackUrl = `${url.protocol}//${url.host}/cb/${methodId}`
+  const dispatched = await dispatchMethod({
+    method,
+    route: "GET /callback",
+    tenant: input.tenant,
+    request: input.rawRequest,
+    subPath: "/callback",
+    flow: null,
+    cookies: input.cookies,
+    sessionStore: deps.sessionStore,
+    dispatch: { state: "", callbackUrl, issuerUrl: input.issuerUrl },
+  })
+  if (isErr(dispatched)) return err(dispatched.error)
+
+  const result = dispatched.value
+  if (result.kind === "challenge") {
+    return ok({
+      kind: "challenge",
+      response: result.response,
+      setCookies: result.setCookies ?? [],
+      ...(result.cache !== undefined ? { cache: result.cache } : {}),
+    })
+  }
+  if (result.kind === "denied") {
+    await safeAudit(deps, {
+      kind: "authorize_failed",
+      tenantId: input.tenant.id,
+      clientId: "idp-initiated",
+      methodId,
+      methodKind: method.kind,
+      flowId: "idp-initiated",
+      reason: result.reason,
+      timestamp: deps.clock(),
+    })
+    return ok({
+      kind: "denied",
+      reason: result.reason,
+      setCookies: result.setCookies ?? [],
+    })
+  }
+  if (result.kind === "error") return err(result.error)
+
+  // success — must carry the operator-configured RP binding.
+  const binding = result.unsolicitedBinding
+  if (!binding) {
+    return err(
+      authError.internalError(
+        `method "${methodId}" handled an unsolicited callback but returned ` +
+          `no unsolicitedBinding`,
+      ),
+    )
+  }
+  // Open-redirect defence-in-depth: the binding is operator config, but
+  // still validate it against the tenant's registered client exactly
+  // as /authorize validates an RP's redirect_uri.
+  const client = input.tenant.config.clients.find(
+    (c) => c.id === binding.clientId,
+  )
+  if (!client) {
+    return err(
+      authError.invalidRequest(
+        `IdP-initiated binding references unknown client "${binding.clientId}"`,
+      ),
+    )
+  }
+  if (!client.redirectUris.includes(binding.redirectUri)) {
+    return err(
+      authError.invalidRequest(
+        `IdP-initiated redirect_uri "${binding.redirectUri}" is not ` +
+          `registered for client "${binding.clientId}"`,
+      ),
+    )
+  }
+
+  const code = (deps.newCodeId ?? randomToken)()
+  const now = deps.clock()
+  const saved = await saveEncryptedCode(
+    code,
+    {
+      tenantId: input.tenant.id,
+      clientId: binding.clientId,
+      appRedirectUri: binding.redirectUri,
+      // No RP-supplied OAuth state in an unsolicited flow; RelayState
+      // is opaque and intentionally NOT echoed as `state`.
+      appState: null,
+      scopes: binding.scopes,
+      methodId,
+      methodKind: method.kind,
+      context: input.tenant.request.custom ?? null,
+      providerSubject: result.providerSubject,
+      properties: result.properties,
+      authTime: Math.floor(now / 1000),
+      expiresAt: now + AUTH_CODE_TTL_MS,
+    },
+    AUTH_CODE_TTL_MS,
+    { keyStore: deps.keyStore, tokenStore: deps.tokenStore },
+  )
+  if (isErr(saved)) return err(saved.error)
+  return ok({
+    kind: "issue-code",
+    code,
+    appRedirectUri: binding.redirectUri,
+    appState: null,
+  })
+}
+
 function normalizePath(p: string): string {
   return p.replace(/\/+$/, "")
 }

package/src/domain/client-credentials.ts

@@ -54,6 +54,8 @@ export type ClientCredentialsDeps = {
   issuerUrl: string
   clock: () => number
   newRefreshFamily?: () => string
+  /** See `IdPOptions.customScopeClaims`. Forwarded to `mintTokens`. */
+  customScopeClaims?: Record<string, ReadonlyArray<string>>
 }
 
 export async function clientCredentialsGrant(

package/src/domain/discovery.ts

@@ -19,11 +19,37 @@ export type DiscoveryDocument = {
   jwks_uri: string
   revocation_endpoint: string
   introspection_endpoint: string
+  /** OIDC RP-Initiated Logout 1.0 §2. */
+  end_session_endpoint: string
+  /** RFC 7591 §3.1. */
+  registration_endpoint: string
+  /** RFC 9126 §5. */
+  pushed_authorization_request_endpoint: string
+  /**
+   * RFC 9126 §5. True iff every client on this tenant is required to use
+   * PAR. We advertise `false` at the tenant level — the per-client toggle
+   * is read at request time.
+   */
+  require_pushed_authorization_requests: boolean
+  /** RFC 9449 §5.1 — DPoP algorithms accepted on proof JWTs. */
+  dpop_signing_alg_values_supported: string[]
   response_types_supported: string[]
   grant_types_supported: string[]
   subject_types_supported: string[]
   id_token_signing_alg_values_supported: string[]
   scopes_supported: string[]
+  /** OIDC Core §3 — registered claim names the IdP can return. */
+  claims_supported: string[]
+  /** OIDC Core §5.5 — `claims` request parameter is honored. */
+  claims_parameter_supported: boolean
+  /** OIDC Core §6.1 — JAR (`request` parameter). Not implemented. */
+  request_parameter_supported: boolean
+  /** OIDC Core §6.2 — JAR (`request_uri` parameter). Not implemented. */
+  request_uri_parameter_supported: boolean
+  /** OIDC Core §6.2 — whether `request_uri` values must be pre-registered. */
+  require_request_uri_registration: boolean
+  /** OIDC Core §3.1.2.1 — UI locales the OP can render. */
+  ui_locales_supported?: string[]
   token_endpoint_auth_methods_supported: string[]
   code_challenge_methods_supported: string[]
 }
@@ -38,14 +64,30 @@ export type DiscoveryDeps = {
     jwks: string
     revoke: string
     introspect: string
+    endSession: string
+    par: string
+    register: string
   }>
   /** Advertised scopes. Defaults to `["openid", "email", "profile"]`. */
   scopes?: string[]
+  /** Advertised UI locales. Defaults to `["en"]`. */
+  uiLocales?: string[]
+  /**
+   * Host-supplied scope → claim-names map. Each key adds a scope to
+   * `scopes_supported`; the union of values augments `claims_supported`.
+   * Mirrors `IdPOptions.customScopeClaims`.
+   */
+  customScopeClaims?: Record<string, ReadonlyArray<string>>
 }
 
 export function buildDiscoveryDocument(deps: DiscoveryDeps): DiscoveryDocument {
   const base = deps.issuerUrl.replace(/\/+$/, "")
   const p = deps.paths ?? {}
+  const customScopeKeys = Object.keys(deps.customScopeClaims ?? {})
+  const customClaimNames = new Set<string>()
+  for (const list of Object.values(deps.customScopeClaims ?? {})) {
+    for (const name of list) customClaimNames.add(name)
+  }
   return {
     issuer: deps.issuerUrl,
     authorization_endpoint: `${base}${p.authorize ?? "/authorize"}`,
@@ -54,15 +96,51 @@ export function buildDiscoveryDocument(deps: DiscoveryDeps): DiscoveryDocument {
     jwks_uri: `${base}${p.jwks ?? "/.well-known/jwks.json"}`,
     revocation_endpoint: `${base}${p.revoke ?? "/revoke"}`,
     introspection_endpoint: `${base}${p.introspect ?? "/introspect"}`,
+    end_session_endpoint: `${base}${p.endSession ?? "/end_session"}`,
+    registration_endpoint: `${base}${p.register ?? "/register"}`,
+    pushed_authorization_request_endpoint: `${base}${p.par ?? "/par"}`,
+    require_pushed_authorization_requests: false,
+    dpop_signing_alg_values_supported: ["ES256", "EdDSA"],
     response_types_supported: ["code"],
     grant_types_supported: [
       "authorization_code",
       "refresh_token",
       "client_credentials",
     ],
-    subject_types_supported: ["public"],
+    subject_types_supported: ["public", "pairwise"],
     id_token_signing_alg_values_supported: ["ES256", "EdDSA"],
-    scopes_supported: deps.scopes ?? ["openid", "email", "profile"],
+    scopes_supported: [
+      ...(deps.scopes ?? ["openid", "email", "profile"]),
+      ...customScopeKeys,
+    ],
+    claims_supported: [
+      "sub",
+      "iss",
+      "aud",
+      "exp",
+      "iat",
+      "auth_time",
+      "nonce",
+      "amr",
+      "at_hash",
+      "email",
+      "email_verified",
+      "name",
+      "given_name",
+      "family_name",
+      "preferred_username",
+      "picture",
+      "locale",
+      "phone_number",
+      "phone_number_verified",
+      "address",
+      ...customClaimNames,
+    ],
+    claims_parameter_supported: true,
+    request_parameter_supported: false,
+    request_uri_parameter_supported: false,
+    require_request_uri_registration: false,
+    ui_locales_supported: deps.uiLocales ?? ["en"],
     token_endpoint_auth_methods_supported: [
       "client_secret_basic",
       "client_secret_post",