@_mustachio/openauth 0.9.1 → 0.10.0

package/src/http/errors.ts

@@ -0,0 +1,98 @@
+/**
+ * Map an `AuthError` into a standards-compliant HTTP response.
+ *
+ * Two surfaces:
+ *   - **Token / introspect / revoke endpoints (RFC 6749 §5.2).** JSON body
+ *     `{ "error": "...", "error_description": "..." }` with the spec status
+ *     codes (`invalid_client` → 401, server-side → 500, the rest → 400).
+ *   - **Authorize endpoint (RFC 6749 §4.1.2.1).** Recoverable errors redirect
+ *     back to the relying party with `error` + `error_description` + the
+ *     echoed `state`. Non-recoverable errors (unknown client, unregistered
+ *     redirect_uri) surface as plain text to avoid open-redirector behavior.
+ *
+ * `internal_error` is framework-internal; the HTTP layer always rewrites it
+ * to `server_error` before responding to the client.
+ */
+import type { AuthError, AuthErrorCode } from "../types/error"
+
+const TOKEN_STATUS: Partial<Record<AuthErrorCode, number>> = {
+  invalid_client: 401,
+  server_error: 500,
+  internal_error: 500,
+  tenant_not_found: 400,
+}
+
+/** Public OAuth error code emitted on the wire. Strips framework-internal. */
+export function publicErrorCode(code: AuthErrorCode): string {
+  if (code === "internal_error") return "server_error"
+  if (code === "tenant_not_found") return "invalid_request"
+  if (code === "method_not_found") return "invalid_request"
+  if (code === "unknown_state") return "invalid_request"
+  return code
+}
+
+export function tokenEndpointErrorResponse(error: AuthError): Response {
+  const status = TOKEN_STATUS[error.code] ?? 400
+  const body = {
+    error: publicErrorCode(error.code),
+    error_description: error.description,
+  }
+  const headers = new Headers({
+    "content-type": "application/json",
+    "cache-control": "no-store",
+    pragma: "no-cache",
+  })
+  if (status === 401) {
+    headers.set("www-authenticate", `Basic realm="oauth"`)
+  }
+  return new Response(JSON.stringify(body), { status, headers })
+}
+
+/**
+ * Redirect back to the RP with the OAuth error in the query (RFC 6749
+ * §4.1.2.1). Returns `null` if the error is non-recoverable — the caller
+ * should render a plain-text response instead.
+ */
+export function authorizeRedirectErrorResponse(
+  error: AuthError,
+  appRedirectUri: string,
+  appState: string | null,
+): Response {
+  const url = new URL(appRedirectUri)
+  url.searchParams.set("error", publicErrorCode(error.code))
+  url.searchParams.set("error_description", error.description)
+  if (appState !== null) url.searchParams.set("state", appState)
+  return new Response(null, {
+    status: 302,
+    headers: { location: url.toString(), "cache-control": "no-store" },
+  })
+}
+
+/**
+ * Plain-text fallback for errors that occur before a valid `redirect_uri`
+ * has been established — open-redirector defense.
+ */
+export function authorizeDirectErrorResponse(error: AuthError): Response {
+  const body = `${publicErrorCode(error.code)}: ${error.description}`
+  return new Response(body, {
+    status: 400,
+    headers: { "content-type": "text/plain", "cache-control": "no-store" },
+  })
+}
+
+/**
+ * Errors that must never round-trip through `appRedirectUri` because the URI
+ * itself is what failed validation.
+ */
+export function isNonRecoverable(error: AuthError): boolean {
+  if (error.code === "invalid_client") return true
+  if (error.code === "tenant_not_found") return true
+  if (error.code === "method_not_found") return true
+  if (
+    error.code === "invalid_request" &&
+    (error as { field?: string }).field === "redirect_uri"
+  ) {
+    return true
+  }
+  return false
+}

package/src/http/handlers/authorize.ts

@@ -0,0 +1,221 @@
+/**
+ * `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 } 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 } 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())
+    const parsed = authorizeQuerySchema.safeParse(raw)
+    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
+
+    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",
+      })
+    }
+
+    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 } : {}),
+    }
+
+    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)
+      }
+    }
+  }
+}
+
+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/metadata.ts

@@ -0,0 +1,44 @@
+/**
+ * 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") })
+    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",
+      },
+    })
+  }
+}

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

@@ -0,0 +1,115 @@
+/**
+ * `GET|POST /m/:methodId/*` — the credential-flow dispatch endpoint.
+ *
+ * Methods that need POST routes (`password` `/login`, `code` `/send`+`/verify`,
+ * `passkey` `/authenticate-options` etc.) declare them on
+ * `AuthMethod.routes`. The HTTP layer mounts those routes here. The
+ * `domain/method-route.handleMethodRoute` orchestrator handles flow lookup
+ * + dispatch + result translation.
+ */
+import { handleMethodRoute } from "../../domain/method-route"
+import { authError } from "../../types/error"
+import { isErr } from "../../types/result"
+
+import { applyResponsePolicy } from "../cookies"
+import type { HttpContext, HttpDeps } from "../context"
+import { authorizeDirectErrorResponse } from "../errors"
+
+export function makeMethodRouteHandler(deps: HttpDeps) {
+  return async (c: HttpContext): Promise<Response> => {
+    const tenant = c.get("tenant")
+    if (!tenant) {
+      return authorizeDirectErrorResponse(
+        authError.invalidRequest("tenant unresolved"),
+      )
+    }
+    const cookies = c.get("cookies")
+    const flowId = cookies.get("idp.flow")
+    if (!flowId) {
+      return authorizeDirectErrorResponse(
+        authError.invalidRequest("missing flow cookie", "flow"),
+      )
+    }
+
+    // /m/<methodId>/<subPath>
+    const url = new URL(c.req.url)
+    const segments = url.pathname.split("/").filter(Boolean)
+    if (segments.length < 3 || segments[0] !== "m") {
+      return authorizeDirectErrorResponse(
+        authError.invalidRequest("malformed method route", "path"),
+      )
+    }
+    const methodId = segments[1]!
+    const subPath = "/" + segments.slice(2).join("/")
+    const httpMethod = c.req.method.toUpperCase() === "POST" ? "POST" : "GET"
+
+    const result = await handleMethodRoute(
+      {
+        rawRequest: c.req.raw,
+        tenant,
+        methodId,
+        subPath,
+        httpMethod,
+        flowId,
+        cookies,
+      },
+      {
+        sessionStore: deps.sessionStore,
+        tokenStore: deps.tokenStore,
+        keyStore: deps.keyStore,
+        ...(deps.auditLog ? { auditLog: deps.auditLog } : {}),
+        methodCache: deps.methodCache,
+        clock: deps.clock,
+      },
+    )
+
+    if (isErr(result)) 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 applyResponsePolicy(
+          new Response(null, {
+            status: 302,
+            headers: { location: redirect.toString() },
+          }),
+          {
+            setCookies: [clearFlowCookie()],
+            cookieDefaults: deps.cookieDefaults,
+          },
+        )
+      }
+      case "challenge":
+        return applyResponsePolicy(out.response, {
+          setCookies: out.setCookies,
+          cookieDefaults: deps.cookieDefaults,
+        })
+      case "denied":
+        return applyResponsePolicy(
+          new Response(`access_denied: ${out.reason}`, {
+            status: 403,
+            headers: { "content-type": "text/plain" },
+          }),
+          {
+            setCookies: [clearFlowCookie(), ...out.setCookies],
+            cookieDefaults: deps.cookieDefaults,
+          },
+        )
+    }
+  }
+}
+
+function clearFlowCookie() {
+  return {
+    name: "idp.flow",
+    value: null,
+    path: "/",
+    httpOnly: true,
+    sameSite: "lax" as const,
+    maxAge: 0,
+  }
+}