@_mustachio/openauth 0.9.2 → 0.11.0

package/src/http/handlers/authorize.ts

@@ -0,0 +1,362 @@
+/**
+ * `GET /authorize` handler.
+ *
+ * Parse + validate query → call `startAuthorize` → serialize the typed
+ * `AuthorizeOutput` per OAuth 2.1 §4.1.2:
+ *   - `challenge`           → method's response, sanitized + framework cookies.
+ *   - `issue-code`          → 302 to `appRedirectUri` with `code` + `state`.
+ *   - `denied`              → redirect with OAuth `access_denied`.
+ *   - `select-method`       → host-supplied `renderPicker`, or the bundled
+ *                             default in `ui/picker.ts`.
+ *
+ * Errors that occur **before** we have a verified RP redirect_uri (unknown
+ * client, mismatched redirect, etc.) surface as plain-text 400 — never a
+ * 302 — to avoid open-redirector behavior.
+ */
+import { isErr } from "../../types/result"
+import { startAuthorize } from "../../domain/authorize"
+import { asTenantId } from "../../types/tenant"
+import { authError } from "../../types/error"
+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 type { HttpContext, HttpDeps } from "../context"
+import {
+  authorizeDirectErrorResponse,
+  authorizeRedirectErrorResponse,
+  isNonRecoverable,
+} from "../errors"
+import {
+  authorizeQuerySchema,
+  authorizeRequestUriQuerySchema,
+} from "../schemas/authorize"
+
+export function makeAuthorizeHandler(deps: HttpDeps) {
+  return async (c: HttpContext): Promise<Response> => {
+    const tenant = c.get("tenant")
+    if (!tenant) {
+      return authorizeDirectErrorResponse(
+        authError.invalidRequest("tenant unresolved"),
+      )
+    }
+
+    const url = new URL(c.req.url)
+    const raw = Object.fromEntries(url.searchParams.entries())
+
+    // 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"
+      return authorizeDirectErrorResponse(
+        authError.invalidRequest(first?.message ?? "invalid request", field),
+      )
+    }
+    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({
+        code: "invalid_request",
+        description: `unsupported response_type "${q.response_type}" — OAuth 2.1 is code-only`,
+        field: "response_type",
+      })
+    }
+
+    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,
+      redirectUri: q.redirect_uri,
+      responseType: "code",
+      scopes: q.scope ?? [],
+      state: q.state ?? null,
+      ...(q.audience !== undefined ? { audience: q.audience } : {}),
+      ...(q.method_id !== undefined ? { methodId: q.method_id } : {}),
+      ...(q.code_challenge !== undefined
+        ? { codeChallenge: q.code_challenge }
+        : {}),
+      ...(q.code_challenge_method !== undefined
+        ? { codeChallengeMethod: q.code_challenge_method }
+        : {}),
+      ...(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(
+      {
+        request,
+        rawRequest: c.req.raw,
+        tenant,
+        cookies: c.get("cookies"),
+      },
+      {
+        sessionStore: deps.sessionStore,
+        tokenStore: deps.tokenStore,
+        keyStore: deps.keyStore,
+        methodCache: deps.methodCache,
+        stateKeys: deps.stateKeys,
+        issuerUrl: c.get("issuerUrl"),
+        clock: deps.clock,
+        ...(deps.auditLog ? { auditLog: deps.auditLog } : {}),
+        ...(deps.callbackHostFor
+          ? {
+              callbackHostFor: (id: string) =>
+                deps.callbackHostFor!(id as never),
+            }
+          : {}),
+      },
+    )
+
+    if (isErr(result)) {
+      const err = result.error
+      if (isNonRecoverable(err)) {
+        return authorizeDirectErrorResponse(err)
+      }
+      return authorizeRedirectErrorResponse(
+        err,
+        q.redirect_uri,
+        q.state ?? null,
+      )
+    }
+
+    const out = result.value
+    switch (out.kind) {
+      case "challenge": {
+        // Framework stamps the `idp.flow` cookie so credential POSTs to
+        // `/m/<methodId>/<sub>` can identify the in-flight flow.
+        const flowCookie = {
+          name: "idp.flow",
+          value: out.flowId,
+          path: "/",
+          httpOnly: true,
+          sameSite: "lax" as const,
+          maxAge: 60 * 10,
+        }
+        return applyResponsePolicy(out.response, {
+          setCookies: [flowCookie, ...out.setCookies],
+          cookieDefaults: deps.cookieDefaults,
+          cacheControl: cacheControlFor(out.cache),
+        })
+      }
+      case "issue-code": {
+        const redirect = new URL(out.appRedirectUri)
+        redirect.searchParams.set("code", out.code)
+        if (out.appState !== null)
+          redirect.searchParams.set("state", out.appState)
+        return applyResponsePolicy(
+          new Response(null, {
+            status: 302,
+            headers: { location: redirect.toString() },
+          }),
+          {
+            setCookies: [clearFlowCookie()],
+            cookieDefaults: deps.cookieDefaults,
+          },
+        )
+      }
+      case "denied":
+        return applyResponsePolicy(
+          authorizeRedirectErrorResponse(
+            { code: "access_denied", description: out.reason },
+            q.redirect_uri,
+            q.state ?? null,
+          ),
+          {
+            setCookies: [clearFlowCookie(), ...out.setCookies],
+            cookieDefaults: deps.cookieDefaults,
+          },
+        )
+      case "select-method": {
+        const pickerCtx: PickerContext = {
+          clientId: q.client_id,
+          redirectUri: q.redirect_uri,
+          state: q.state ?? null,
+          scope: q.scope ? q.scope.join(" ") : null,
+          nonce: q.nonce ?? null,
+          codeChallenge: q.code_challenge ?? null,
+          codeChallengeMethod: q.code_challenge_method ?? null,
+          audience: q.audience ?? null,
+          prompt: q.prompt ? q.prompt.join(" ") : null,
+          uiLocales: q.ui_locales ? q.ui_locales.join(" ") : null,
+        }
+        const methods: PickerMethod[] = out.methods.map((m) => ({
+          id: m.id,
+          kind: m.kind,
+          type: m.type,
+        }))
+        const render = deps.renderPicker ?? renderDefaultPicker
+        return await render(methods, pickerCtx)
+      }
+    }
+  }
+}
+
+/**
+ * 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",
+    value: null,
+    path: "/",
+    httpOnly: true,
+    sameSite: "lax" as const,
+    maxAge: 0,
+  }
+}
+
+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

@@ -0,0 +1,77 @@
+/**
+ * `GET /cb/:methodId` handler — upstream-provider callback.
+ *
+ * The tenant middleware has already run the recovery chain; `c.get("recovery")`
+ * carries the outcome. The handler delegates to `handleCallback` which
+ * performs the state-flow consistency check, dispatches the method's `GET
+ * /callback`, and either mints the auth code or returns an interstitial
+ * challenge.
+ */
+import { handleCallback } from "../../domain/callback"
+import { isErr } from "../../types/result"
+
+import { applyResponsePolicy } from "../cookies"
+import type { HttpContext, HttpDeps } from "../context"
+import { authorizeDirectErrorResponse } from "../errors"
+
+export function makeCallbackHandler(deps: HttpDeps) {
+  return async (c: HttpContext): Promise<Response> => {
+    const result = await handleCallback(
+      { rawRequest: c.req.raw, cookies: c.get("cookies") },
+      {
+        configStore: deps.configStore,
+        sessionStore: deps.sessionStore,
+        tokenStore: deps.tokenStore,
+        keyStore: deps.keyStore,
+        ...(deps.auditLog ? { auditLog: deps.auditLog } : {}),
+        methodCache: deps.methodCache,
+        stateKeys: deps.stateKeys,
+        ...(deps.buildCustomContext
+          ? { buildCustomContext: deps.buildCustomContext }
+          : {}),
+        clock: deps.clock,
+      },
+    )
+
+    if (isErr(result)) {
+      // The callback URL does not carry an RP redirect URI — surface plain
+      // text and let the operator inspect logs / audit for context.
+      return authorizeDirectErrorResponse(result.error)
+    }
+
+    const out = result.value
+    switch (out.kind) {
+      case "issue-code": {
+        const redirect = new URL(out.appRedirectUri)
+        redirect.searchParams.set("code", out.code)
+        if (out.appState !== null)
+          redirect.searchParams.set("state", out.appState)
+        return new Response(null, {
+          status: 302,
+          headers: {
+            location: redirect.toString(),
+            "cache-control": "no-store",
+          },
+        })
+      }
+      case "challenge":
+        return applyResponsePolicy(out.response, {
+          setCookies: out.setCookies,
+          cookieDefaults: deps.cookieDefaults,
+          cacheControl: out.cache
+            ? out.cache.maxAge === 0
+              ? "no-store"
+              : "no-store"
+            : "no-store",
+        })
+      case "denied":
+        return applyResponsePolicy(
+          new Response(`access_denied: ${out.reason}`, {
+            status: 403,
+            headers: { "content-type": "text/plain" },
+          }),
+          { setCookies: out.setCookies, cookieDefaults: deps.cookieDefaults },
+        )
+    }
+  }
+}

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

@@ -0,0 +1,49 @@
+/**
+ * Public metadata handlers.
+ *
+ *   GET /.well-known/openid-configuration
+ *   GET /.well-known/oauth-authorization-server  (alias of the OIDC doc)
+ *   GET /.well-known/jwks.json
+ *
+ * Discovery is cacheable; JWKS is cacheable with a short TTL (the framework
+ * rotates signing keys monthly per cross-cutting decisions). We advertise
+ * `Cache-Control: public, max-age=60` on both — clients can re-fetch on
+ * `kid` miss.
+ */
+import { buildDiscoveryDocument, buildJwks } from "../../domain/discovery"
+import { isErr } from "../../types/result"
+
+import type { HttpContext, HttpDeps } from "../context"
+import { tokenEndpointErrorResponse } from "../errors"
+
+export function makeDiscoveryHandler(deps: HttpDeps) {
+  return async (c: HttpContext): Promise<Response> => {
+    const doc = buildDiscoveryDocument({
+      issuerUrl: c.get("issuerUrl"),
+      ...(deps.customScopeClaims !== undefined
+        ? { customScopeClaims: deps.customScopeClaims }
+        : {}),
+    })
+    return new Response(JSON.stringify(doc), {
+      status: 200,
+      headers: {
+        "content-type": "application/json",
+        "cache-control": "public, max-age=60",
+      },
+    })
+  }
+}
+
+export function makeJwksHandler(deps: HttpDeps) {
+  return async (_c: HttpContext): Promise<Response> => {
+    const res = await buildJwks(deps.keyStore)
+    if (isErr(res)) return tokenEndpointErrorResponse(res.error)
+    return new Response(JSON.stringify(res.value), {
+      status: 200,
+      headers: {
+        "content-type": "application/json",
+        "cache-control": "public, max-age=60",
+      },
+    })
+  }
+}