@_mustachio/openauth 0.10.0 → 0.12.0

package/src/http/handlers/authorize.ts

@@ -17,18 +17,24 @@ import { isErr } from "../../types/result"
 import { startAuthorize } from "../../domain/authorize"
 import { asTenantId } from "../../types/tenant"
 import { authError } from "../../types/error"
-import type { AuthorizationRequest } from "../../types/authorization"
+import type {
+  AuthorizationRequest,
+  ClaimsRequest,
+} from "../../types/authorization"
 import type { PickerContext, PickerMethod } from "../../types/picker"
 import { renderPicker as renderDefaultPicker } from "../../ui/picker"
 
-import { applyResponsePolicy } from "../cookies"
+import { applyResponsePolicy, cacheControlHeader } from "../cookies"
 import type { HttpContext, HttpDeps } from "../context"
 import {
   authorizeDirectErrorResponse,
   authorizeRedirectErrorResponse,
   isNonRecoverable,
 } from "../errors"
-import { authorizeQuerySchema } from "../schemas/authorize"
+import {
+  authorizeQuerySchema,
+  authorizeRequestUriQuerySchema,
+} from "../schemas/authorize"
 
 export function makeAuthorizeHandler(deps: HttpDeps) {
   return async (c: HttpContext): Promise<Response> => {
@@ -41,7 +47,51 @@ export function makeAuthorizeHandler(deps: HttpDeps) {
 
     const url = new URL(c.req.url)
     const raw = Object.fromEntries(url.searchParams.entries())
-    const parsed = authorizeQuerySchema.safeParse(raw)
+
+    // RFC 9126 §4: rehydrate a PAR record when `request_uri` is present.
+    // The user-agent URL carries only `client_id` + `request_uri`; the
+    // stored params drive the rest of the request through the standard
+    // parser below.
+    let workingRaw: Record<string, string> = raw
+    if (raw.request_uri !== undefined) {
+      const parParsed = authorizeRequestUriQuerySchema.safeParse(raw)
+      if (!parParsed.success) {
+        return authorizeDirectErrorResponse(
+          authError.invalidRequest(
+            parParsed.error.issues[0]?.message ?? "invalid request",
+            parParsed.error.issues[0]?.path[0]?.toString() ?? "request",
+          ),
+        )
+      }
+      if (!deps.sessionStore.consumePar) {
+        return authorizeDirectErrorResponse(
+          authError.invalidRequest(
+            "session adapter does not support PAR",
+            "request_uri",
+          ),
+        )
+      }
+      const par = await deps.sessionStore.consumePar(parParsed.data.request_uri)
+      if (isErr(par)) {
+        return authorizeDirectErrorResponse(
+          authError.invalidRequest(
+            "unknown or expired request_uri",
+            "request_uri",
+          ),
+        )
+      }
+      if (par.value.clientId !== parParsed.data.client_id) {
+        return authorizeDirectErrorResponse(
+          authError.invalidRequest(
+            "request_uri belongs to a different client",
+            "request_uri",
+          ),
+        )
+      }
+      workingRaw = par.value.params
+    }
+
+    const parsed = authorizeQuerySchema.safeParse(workingRaw)
     if (!parsed.success) {
       const first = parsed.error.issues[0]
       const field = first?.path[0]?.toString() ?? "request"
@@ -51,6 +101,20 @@ export function makeAuthorizeHandler(deps: HttpDeps) {
     }
     const q = parsed.data
 
+    // RFC 9126 §2 per-client PAR enforcement: refuse direct `/authorize`
+    // when the client requires PAR and `request_uri` was absent.
+    if (raw.request_uri === undefined) {
+      const client = tenant.config.clients.find((c) => c.id === q.client_id)
+      if (client?.requirePushedAuthorizationRequests) {
+        return authorizeDirectErrorResponse(
+          authError.invalidRequest(
+            "this client requires Pushed Authorization Requests (RFC 9126)",
+            "request_uri",
+          ),
+        )
+      }
+    }
+
     if (q.response_type !== "code") {
       // OAuth 2.1: only `code` is supported. Implicit (`token`) is removed.
       return authorizeDirectErrorResponse({
@@ -60,6 +124,17 @@ export function makeAuthorizeHandler(deps: HttpDeps) {
       })
     }
 
+    let claimsRequest: ClaimsRequest | undefined
+    if (q.claims !== undefined) {
+      const parsedClaims = parseClaimsParameter(q.claims)
+      if (!parsedClaims.ok) {
+        return authorizeDirectErrorResponse(
+          authError.invalidRequest(parsedClaims.error, "claims"),
+        )
+      }
+      claimsRequest = parsedClaims.value
+    }
+
     const request: AuthorizationRequest = {
       tenantId: asTenantId(tenant.id),
       clientId: q.client_id,
@@ -78,6 +153,7 @@ export function makeAuthorizeHandler(deps: HttpDeps) {
       ...(q.prompt !== undefined ? { prompt: q.prompt } : {}),
       ...(q.ui_locales !== undefined ? { uiLocales: q.ui_locales } : {}),
       ...(q.nonce !== undefined ? { nonce: q.nonce } : {}),
+      ...(claimsRequest !== undefined ? { claimsRequest } : {}),
     }
 
     const result = await startAuthorize(
@@ -133,7 +209,7 @@ export function makeAuthorizeHandler(deps: HttpDeps) {
         return applyResponsePolicy(out.response, {
           setCookies: [flowCookie, ...out.setCookies],
           cookieDefaults: deps.cookieDefaults,
-          cacheControl: cacheControlFor(out.cache),
+          cacheControl: cacheControlHeader(out.cache),
         })
       }
       case "issue-code": {
@@ -189,6 +265,71 @@ export function makeAuthorizeHandler(deps: HttpDeps) {
   }
 }
 
+/**
+ * Parse + validate the OIDC Core §5.5 `claims` parameter. Accepts a
+ * JSON string; verifies it's an object whose `userinfo` / `id_token`
+ * values, if present, are objects mapping claim names to `null` or
+ * `{essential?, value?, values?}` entries. Returns a discriminated
+ * `{ok, value}` shape so the caller can map failure → `invalid_request`
+ * without dragging the AuthError import into this helper.
+ */
+function parseClaimsParameter(
+  raw: string,
+): { ok: true; value: ClaimsRequest } | { ok: false; error: string } {
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch (e) {
+    return {
+      ok: false,
+      error: `claims parameter is not valid JSON: ${e instanceof Error ? e.message : String(e)}`,
+    }
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    return { ok: false, error: "claims parameter must be a JSON object" }
+  }
+  const obj = parsed as Record<string, unknown>
+  const result: ClaimsRequest = {}
+  for (const section of ["userinfo", "id_token"] as const) {
+    const v = obj[section]
+    if (v === undefined) continue
+    if (!v || typeof v !== "object" || Array.isArray(v)) {
+      return {
+        ok: false,
+        error: `claims.${section} must be a JSON object`,
+      }
+    }
+    const sectionMap: Record<
+      string,
+      { essential?: boolean; value?: unknown; values?: unknown[] } | null
+    > = {}
+    for (const [name, entry] of Object.entries(v)) {
+      if (entry === null) {
+        sectionMap[name] = null
+        continue
+      }
+      if (typeof entry !== "object" || Array.isArray(entry)) {
+        return {
+          ok: false,
+          error: `claims.${section}.${name} must be null or a JSON object`,
+        }
+      }
+      const e = entry as Record<string, unknown>
+      const normalized: {
+        essential?: boolean
+        value?: unknown
+        values?: unknown[]
+      } = {}
+      if (typeof e.essential === "boolean") normalized.essential = e.essential
+      if ("value" in e) normalized.value = e.value
+      if (Array.isArray(e.values)) normalized.values = e.values
+      sectionMap[name] = normalized
+    }
+    result[section] = sectionMap
+  }
+  return { ok: true, value: result }
+}
+
 function clearFlowCookie() {
   return {
     name: "idp.flow",
@@ -200,22 +341,3 @@ function clearFlowCookie() {
   }
 }
 
-function cacheControlFor(
-  cache:
-    | {
-        maxAge?: number
-        sMaxAge?: number
-        isPrivate?: boolean
-        immutable?: boolean
-      }
-    | undefined,
-): string {
-  if (!cache) return "no-store"
-  if ((cache.maxAge ?? -1) === 0) return "no-store"
-  const parts: string[] = []
-  if (cache.isPrivate) parts.push("private")
-  if (cache.maxAge !== undefined) parts.push(`max-age=${cache.maxAge}`)
-  if (cache.sMaxAge !== undefined) parts.push(`s-maxage=${cache.sMaxAge}`)
-  if (cache.immutable) parts.push("immutable")
-  return parts.length ? parts.join(", ") : "no-store"
-}

package/src/http/handlers/callback.ts

@@ -16,8 +16,16 @@ import { authorizeDirectErrorResponse } from "../errors"
 
 export function makeCallbackHandler(deps: HttpDeps) {
   return async (c: HttpContext): Promise<Response> => {
+    const tenant = c.get("tenant")
     const result = await handleCallback(
-      { rawRequest: c.req.raw, cookies: c.get("cookies") },
+      {
+        rawRequest: c.req.raw,
+        cookies: c.get("cookies"),
+        // Only the IdP-initiated (no-state) path reads these; the
+        // SP-initiated path derives tenant from the consumed flow.
+        ...(tenant ? { tenant } : {}),
+        issuerUrl: c.get("issuerUrl"),
+      },
       {
         configStore: deps.configStore,
         sessionStore: deps.sessionStore,

package/src/http/handlers/end-session.ts

@@ -0,0 +1,106 @@
+/**
+ * `GET|POST /end_session` — OIDC RP-Initiated Logout 1.0 §2.
+ *
+ * Per spec, both GET (query) and POST (form body) are supported. The
+ * tenant is resolved via the standard `tenantMiddleware`; the issuer URL
+ * is taken from the per-request context.
+ *
+ * Outputs follow `domain/logout.ts`:
+ *  - `redirect` → 302 to the validated `post_logout_redirect_uri` with
+ *    `state` echoed when present.
+ *  - `ok` → 200 with a minimal plain-text body. Hosts that need a styled
+ *    "logged out" page can layer their own handler over `/end_session`.
+ *  - errors → 400 with a JSON OAuth-style body (never 302; an unregistered
+ *    `post_logout_redirect_uri` would otherwise be an open redirector).
+ */
+import { endSession } from "../../domain/logout"
+import { authError } from "../../types/error"
+import { isErr } from "../../types/result"
+
+import { applyResponsePolicy } from "../cookies"
+import type { HttpContext, HttpDeps } from "../context"
+import { tokenEndpointErrorResponse } from "../errors"
+import { endSessionParamsSchema } from "../schemas/end-session"
+
+export function makeEndSessionHandler(deps: HttpDeps) {
+  return async (c: HttpContext): Promise<Response> => {
+    const tenant = c.get("tenant")
+    if (!tenant) {
+      return tokenEndpointErrorResponse(
+        authError.invalidRequest("tenant unresolved"),
+      )
+    }
+
+    // GET → query; POST → form body. Anything else → 400.
+    let raw: Record<string, string>
+    const httpMethod = c.req.method.toUpperCase()
+    if (httpMethod === "GET") {
+      raw = Object.fromEntries(new URL(c.req.url).searchParams.entries())
+    } else if (httpMethod === "POST") {
+      const ct = (c.req.header("content-type") ?? "").toLowerCase()
+      if (!ct.startsWith("application/x-www-form-urlencoded")) {
+        return tokenEndpointErrorResponse(
+          authError.invalidRequest(
+            "POST /end_session requires application/x-www-form-urlencoded body",
+          ),
+        )
+      }
+      raw = Object.fromEntries(new URLSearchParams(await c.req.raw.text()))
+    } else {
+      return tokenEndpointErrorResponse(
+        authError.invalidRequest(`unsupported method "${httpMethod}"`),
+      )
+    }
+
+    const parsed = endSessionParamsSchema.safeParse(raw)
+    if (!parsed.success) {
+      return tokenEndpointErrorResponse(
+        authError.invalidRequest(
+          parsed.error.issues[0]?.message ?? "invalid request",
+        ),
+      )
+    }
+    const q = parsed.data
+
+    const res = await endSession(
+      {
+        ...(q.id_token_hint !== undefined
+          ? { idTokenHint: q.id_token_hint }
+          : {}),
+        ...(q.client_id !== undefined ? { clientId: q.client_id } : {}),
+        ...(q.post_logout_redirect_uri !== undefined
+          ? { postLogoutRedirectUri: q.post_logout_redirect_uri }
+          : {}),
+        ...(q.state !== undefined ? { state: q.state } : {}),
+      },
+      tenant,
+      {
+        configStore: deps.configStore,
+        tokenStore: deps.tokenStore,
+        keyStore: deps.keyStore,
+        ...(deps.auditLog ? { auditLog: deps.auditLog } : {}),
+        issuerUrl: c.get("issuerUrl"),
+        clock: deps.clock,
+      },
+    )
+
+    if (isErr(res)) return tokenEndpointErrorResponse(res.error)
+
+    if (res.value.kind === "redirect") {
+      return applyResponsePolicy(
+        new Response(null, {
+          status: 302,
+          headers: { location: res.value.url },
+        }),
+        { setCookies: [], cookieDefaults: deps.cookieDefaults },
+      )
+    }
+    return new Response("Logged out.", {
+      status: 200,
+      headers: {
+        "content-type": "text/plain; charset=utf-8",
+        "cache-control": "no-store",
+      },
+    })
+  }
+}

package/src/http/handlers/metadata.ts

@@ -16,9 +16,14 @@ import { isErr } from "../../types/result"
 import type { HttpContext, HttpDeps } from "../context"
 import { tokenEndpointErrorResponse } from "../errors"
 
-export function makeDiscoveryHandler(_deps: HttpDeps) {
+export function makeDiscoveryHandler(deps: HttpDeps) {
   return async (c: HttpContext): Promise<Response> => {
-    const doc = buildDiscoveryDocument({ issuerUrl: c.get("issuerUrl") })
+    const doc = buildDiscoveryDocument({
+      issuerUrl: c.get("issuerUrl"),
+      ...(deps.customScopeClaims !== undefined
+        ? { customScopeClaims: deps.customScopeClaims }
+        : {}),
+    })
     return new Response(JSON.stringify(doc), {
       status: 200,
       headers: {

package/src/http/handlers/method-route.ts

@@ -7,11 +7,15 @@
  * `domain/method-route.handleMethodRoute` orchestrator handles flow lookup
  * + dispatch + result translation.
  */
-import { handleMethodRoute } from "../../domain/method-route"
+import {
+  handleMethodRoute,
+  handlePublicMethodRoute,
+} from "../../domain/method-route"
+import type { RouteKey } from "../../domain/method-dispatch"
 import { authError } from "../../types/error"
 import { isErr } from "../../types/result"
 
-import { applyResponsePolicy } from "../cookies"
+import { applyResponsePolicy, cacheControlHeader } from "../cookies"
 import type { HttpContext, HttpDeps } from "../context"
 import { authorizeDirectErrorResponse } from "../errors"
 
@@ -23,6 +27,75 @@ export function makeMethodRouteHandler(deps: HttpDeps) {
         authError.invalidRequest("tenant unresolved"),
       )
     }
+
+    // Public fast-path (additive — leaves the cookie-gated path below
+    // byte-identical for every non-public request). Only a clean hit —
+    // well-formed `/m/<id>/<sub>`, method resolves, and the resolved
+    // method explicitly lists this route key in `publicRoutes` — is
+    // diverted here, cookie-free. Anything else falls through to the
+    // original flow-cookie-gated logic with its original error
+    // ordering. `methodCache.resolve` is a cache lookup; the duplicate
+    // resolve on the gated path is a cache hit.
+    {
+      const u = new URL(c.req.url)
+      const segs = u.pathname.split("/").filter(Boolean)
+      if (segs.length >= 3 && segs[0] === "m") {
+        const methodId = segs[1]!
+        const subPath = "/" + segs.slice(2).join("/")
+        const httpMethod =
+          c.req.method.toUpperCase() === "POST" ? "POST" : "GET"
+        const routeKey = `${httpMethod} ${subPath}` as RouteKey
+        const resolved = await deps.methodCache.resolve(
+          tenant.config,
+          methodId,
+        )
+        if (
+          !isErr(resolved) &&
+          resolved.value.publicRoutes?.includes(routeKey)
+        ) {
+          const issuerUrl = c.get("issuerUrl")
+          const callbackHost =
+            deps.callbackHostFor?.(tenant.id) ?? new URL(issuerUrl).host
+          // Mirrors the ACS URL derivation in domain/authorize.ts
+          // (callbackHost/path/url). Source of truth is there; the
+          // metadata.test.ts anti-drift test asserts the emitted
+          // entityID/ACS equal what buildAuthnRequestRedirect derives.
+          const callbackUrl = `${new URL(issuerUrl).protocol}//${callbackHost}/cb/${methodId}`
+          const pub = await handlePublicMethodRoute(
+            {
+              rawRequest: c.req.raw,
+              tenant,
+              method: resolved.value,
+              route: routeKey,
+              subPath,
+              dispatch: { state: "", callbackUrl, issuerUrl },
+            },
+            {
+              sessionStore: deps.sessionStore,
+              tokenStore: deps.tokenStore,
+              clock: deps.clock,
+              ...(deps.auditLog ? { auditLog: deps.auditLog } : {}),
+              ...(deps.onLogout ? { onLogout: deps.onLogout } : {}),
+            },
+          )
+          if (isErr(pub)) return authorizeDirectErrorResponse(pub.error)
+          if (pub.value.kind === "denied") {
+            return applyResponsePolicy(
+              new Response(`access_denied: ${pub.value.reason}`, {
+                status: 403,
+                headers: { "content-type": "text/plain" },
+              }),
+              { cookieDefaults: deps.cookieDefaults },
+            )
+          }
+          return applyResponsePolicy(pub.value.response, {
+            cacheControl: cacheControlHeader(pub.value.cache),
+            cookieDefaults: deps.cookieDefaults,
+          })
+        }
+      }
+    }
+
     const cookies = c.get("cookies")
     const flowId = cookies.get("idp.flow")
     if (!flowId) {

package/src/http/handlers/par.ts

@@ -0,0 +1,84 @@
+/**
+ * `POST /par` — Pushed Authorization Requests (RFC 9126 §2).
+ *
+ * Body: `application/x-www-form-urlencoded` carrying the same parameter
+ * set the RP would otherwise put on `GET /authorize`, plus `client_id`
+ * and optionally `client_secret`. Client credentials may alternatively
+ * ride in `Authorization: Basic` (RFC 6749 §2.3.1).
+ *
+ * Response: HTTP 201, JSON `{request_uri, expires_in}` on success.
+ */
+import { resolveClientCredentials } from "../../domain/client-auth"
+import { pushAuthorizationRequest } from "../../domain/par"
+import { authError } from "../../types/error"
+import { isErr } from "../../types/result"
+
+import type { HttpContext, HttpDeps } from "../context"
+import { tokenEndpointErrorResponse } from "../errors"
+import { parBodySchema } from "../schemas/par"
+
+export function makeParHandler(deps: HttpDeps) {
+  return async (c: HttpContext): Promise<Response> => {
+    const tenant = c.get("tenant")
+    if (!tenant) {
+      return tokenEndpointErrorResponse(
+        authError.invalidRequest("tenant unresolved"),
+      )
+    }
+    const ct = (c.req.header("content-type") ?? "").toLowerCase()
+    if (!ct.startsWith("application/x-www-form-urlencoded")) {
+      return tokenEndpointErrorResponse(
+        authError.invalidRequest(
+          "body must be application/x-www-form-urlencoded",
+        ),
+      )
+    }
+    const raw = Object.fromEntries(
+      new URLSearchParams(await c.req.raw.text()).entries(),
+    )
+    const parsed = parBodySchema.safeParse(raw)
+    if (!parsed.success) {
+      return tokenEndpointErrorResponse(
+        authError.invalidRequest(
+          parsed.error.issues[0]?.message ?? "invalid request",
+        ),
+      )
+    }
+    const creds = resolveClientCredentials({
+      authorizationHeader: c.req.header("authorization") ?? null,
+      bodyClientId: parsed.data.client_id,
+      bodyClientSecret: parsed.data.client_secret,
+    })
+    const clientId = creds?.clientId ?? parsed.data.client_id
+
+    // Strip auth-only fields from the param record we persist — they
+    // belong to `/par`, not to the rehydrated `/authorize` request.
+    const { client_secret: _strip, ...paramsForAuthorize } = parsed.data
+    void _strip
+
+    const res = await pushAuthorizationRequest(
+      {
+        clientId,
+        ...(creds?.clientSecret !== undefined
+          ? { clientSecret: creds.clientSecret }
+          : {}),
+        params: paramsForAuthorize,
+      },
+      tenant,
+      {
+        configStore: deps.configStore,
+        sessionStore: deps.sessionStore,
+        ...(deps.auditLog ? { auditLog: deps.auditLog } : {}),
+        clock: deps.clock,
+      },
+    )
+    if (isErr(res)) return tokenEndpointErrorResponse(res.error)
+    return new Response(JSON.stringify(res.value), {
+      status: 201,
+      headers: {
+        "content-type": "application/json",
+        "cache-control": "no-store",
+      },
+    })
+  }
+}

package/src/http/handlers/register.ts

@@ -0,0 +1,70 @@
+/**
+ * `POST /register` — RFC 7591 Dynamic Client Registration.
+ *
+ * Body: `application/json`. Tenant resolved via the standard middleware.
+ * The framework validates structure here and defers persistence to the
+ * `IdPOptions.registerClient` hook (in `domain/register.ts`).
+ *
+ * Per RFC 7591 §3.2.1, success returns HTTP 201 with JSON body.
+ */
+import { registerNewClient } from "../../domain/register"
+import { authError } from "../../types/error"
+import type { RegisterClientRequest } from "../../types/idp"
+import { isErr } from "../../types/result"
+
+import type { HttpContext, HttpDeps } from "../context"
+import { tokenEndpointErrorResponse } from "../errors"
+import { registerBodySchema } from "../schemas/register"
+
+export function makeRegisterHandler(deps: HttpDeps) {
+  return async (c: HttpContext): Promise<Response> => {
+    const tenant = c.get("tenant")
+    if (!tenant) {
+      return tokenEndpointErrorResponse(
+        authError.invalidRequest("tenant unresolved"),
+      )
+    }
+    const ct = (c.req.header("content-type") ?? "").toLowerCase()
+    if (!ct.startsWith("application/json")) {
+      return tokenEndpointErrorResponse(
+        authError.invalidRequest("body must be application/json"),
+      )
+    }
+    let raw: unknown
+    try {
+      raw = await c.req.raw.json()
+    } catch (e) {
+      const reason = e instanceof Error ? e.message : String(e)
+      return tokenEndpointErrorResponse(
+        authError.invalidRequest(`malformed JSON: ${reason}`),
+      )
+    }
+    const parsed = registerBodySchema.safeParse(raw)
+    if (!parsed.success) {
+      return tokenEndpointErrorResponse(
+        authError.invalidRequest(
+          parsed.error.issues[0]?.message ?? "invalid request",
+        ),
+      )
+    }
+    // Schema is `.passthrough()` (RFC 7591 allows extension metadata
+    // fields); the declared `RegisterClientRequest` fields are all
+    // statically present in `parsed.data`. This cast just drops the
+    // passthrough's `[k: string]: unknown` index signature so the
+    // downstream domain function sees the typed contract.
+    const request = parsed.data as RegisterClientRequest
+
+    const res = await registerNewClient(request, tenant, {
+      ...(deps.registerClient ? { registerClient: deps.registerClient } : {}),
+      clock: deps.clock,
+    })
+    if (isErr(res)) return tokenEndpointErrorResponse(res.error)
+    return new Response(JSON.stringify(res.value), {
+      status: 201,
+      headers: {
+        "content-type": "application/json",
+        "cache-control": "no-store",
+      },
+    })
+  }
+}