@_mustachio/openauth 0.9.2 → 0.11.0

package/src/http/handlers/token.ts

@@ -0,0 +1,300 @@
+/**
+ * `POST /token` handler.
+ *
+ * Accepts `application/x-www-form-urlencoded` (RFC 6749 §3.2). Discriminates
+ * on `grant_type`:
+ *   - `authorization_code` → `exchangeCode`
+ *   - `refresh_token`      → `refreshTokens`
+ *
+ * `client_credentials` arrives in Phase 5 alongside the m2m method.
+ *
+ * Client authentication: secrets can ride either in the form body
+ * (`client_secret`) or in the `Authorization: Basic` header. Both are
+ * accepted; the header takes precedence.
+ *
+ * The token endpoint does NOT consult the tenant middleware — every code /
+ * refresh token carries its tenant on its payload, so the auth-code or
+ * refresh-token snapshot is authoritative.
+ */
+import { clientCredentialsGrant } from "../../domain/client-credentials"
+import { canonicalHtu, verifyDpopProof } from "../../domain/dpop"
+import { exchangeCode } from "../../domain/token"
+import { exchangeToken } from "../../domain/token-exchange"
+import { refreshTokens } from "../../domain/refresh"
+import { isErr } from "../../types/result"
+import { authError } from "../../types/error"
+
+import type { HttpContext, HttpDeps } from "../context"
+import { tokenEndpointErrorResponse } from "../errors"
+import { injectResolverHints } from "../resolver"
+import { tokenRequestSchema } from "../schemas/token"
+
+export function makeTokenHandler(deps: HttpDeps) {
+  return async (c: HttpContext): Promise<Response> => {
+    const body = await readFormBody(c.req.raw)
+    if (!body) {
+      return tokenEndpointErrorResponse(
+        authError.invalidRequest(
+          "body must be application/x-www-form-urlencoded",
+        ),
+      )
+    }
+
+    // `Authorization` carries Basic client auth on /token. DPoP travels in
+    // its own `DPoP:` header (RFC 9449 §5) — never inside `Authorization`.
+    // Parsing Basic first lets a confidential client present its secret
+    // alongside a DPoP proof.
+    const basic = parseBasicAuth(c.req.header("authorization") ?? null)
+    if (basic) {
+      body.set("client_id", basic.id)
+      body.set("client_secret", basic.secret)
+    }
+
+    // RFC 9449 §5.1 — verify any presented DPoP proof against this
+    // request's actual method + URI. Absent header is fine here (the
+    // grant-specific path enforces `dpopRequired`).
+    const dpopHeader = c.req.header("dpop") ?? null
+    let dpopJkt: string | undefined
+    if (dpopHeader) {
+      const dpopRes = await verifyDpopProof(
+        {
+          proofJwt: dpopHeader,
+          htu: canonicalHtu(c.req.url),
+          htm: "POST",
+          nowSec: Math.floor(deps.clock() / 1000),
+        },
+        { tokenStore: deps.tokenStore },
+      )
+      if (isErr(dpopRes)) {
+        // RFC 9449 §11.1 replay → first-class audit event so operators /
+        // SIEM can spot stolen-key probing distinct from generic proof
+        // verification failures.
+        const errVal = dpopRes.error
+        if (
+          errVal.code === "invalid_dpop_proof" &&
+          errVal.replaySignal &&
+          deps.auditLog
+        ) {
+          await deps.auditLog.log({
+            kind: "dpop_replay_detected",
+            tenantId: null,
+            jtiPrefix: errVal.replaySignal.jti.slice(0, 16),
+            timestamp: deps.clock(),
+          })
+        }
+        return tokenEndpointErrorResponse(errVal)
+      }
+      dpopJkt = dpopRes.value.jkt
+    }
+
+    const parsed = tokenRequestSchema.safeParse(
+      Object.fromEntries(body.entries()),
+    )
+    if (!parsed.success) {
+      const first = parsed.error.issues[0]
+      // RFC 6749 §5.2 maps grant_type problems to `unsupported_grant_type`.
+      if (first?.path[0] === "grant_type") {
+        return tokenEndpointErrorResponse(
+          authError.unsupportedGrantType(
+            first.message ?? "unsupported grant_type",
+          ),
+        )
+      }
+      return tokenEndpointErrorResponse(
+        authError.invalidRequest(first?.message ?? "invalid request"),
+      )
+    }
+    const req = parsed.data
+
+    if (req.grant_type === "authorization_code") {
+      const result = await exchangeCode(
+        {
+          grantType: "authorization_code",
+          code: req.code,
+          redirectUri: req.redirect_uri,
+          clientId: req.client_id,
+          ...(req.client_secret !== undefined
+            ? { clientSecret: req.client_secret }
+            : {}),
+          ...(req.code_verifier !== undefined
+            ? { codeVerifier: req.code_verifier }
+            : {}),
+          ...(dpopJkt !== undefined ? { dpopJkt } : {}),
+        },
+        {
+          configStore: deps.configStore,
+          tokenStore: deps.tokenStore,
+          keyStore: deps.keyStore,
+          ...(deps.auditLog ? { auditLog: deps.auditLog } : {}),
+          success: deps.success,
+          ...(deps.persistUpstreamTokens
+            ? { persistUpstreamTokens: deps.persistUpstreamTokens }
+            : {}),
+          issuerUrl: c.get("issuerUrl"),
+          clock: deps.clock,
+          ...(deps.customScopeClaims !== undefined
+            ? { customScopeClaims: deps.customScopeClaims }
+            : {}),
+        },
+      )
+      if (isErr(result)) return tokenEndpointErrorResponse(result.error)
+      return jsonResponse(result.value)
+    }
+
+    if (req.grant_type === "client_credentials") {
+      // Resolve tenant — client_credentials carries no auth code, so we
+      // call the user-supplied resolver against the /token request. The
+      // canonical resolver pattern (INTEGRATION.md §5.1) reads `client_id`
+      // from URL search params, but the m2m grant carries client_id in the
+      // form body / Basic auth — never the URL. Inject the parsed
+      // `client_id` into a synthesized request so resolvers using the
+      // canonical pattern work for m2m without an extra hook.
+      const tenantRes = await deps.resolveTenant(
+        injectResolverHints(c.req.raw, { client_id: req.client_id }),
+      )
+      if (isErr(tenantRes)) {
+        return tokenEndpointErrorResponse(tenantRes.error)
+      }
+      const params: Record<string, string> = {}
+      for (const [k, v] of body.entries()) {
+        if (typeof v === "string") params[k] = v
+      }
+      const result = await clientCredentialsGrant(
+        {
+          grantType: "client_credentials",
+          clientId: req.client_id,
+          clientSecret: req.client_secret,
+          ...(req.scope !== undefined ? { scope: req.scope } : {}),
+          params,
+        },
+        {
+          configStore: deps.configStore,
+          tokenStore: deps.tokenStore,
+          keyStore: deps.keyStore,
+          ...(deps.auditLog ? { auditLog: deps.auditLog } : {}),
+          methodCache: deps.methodCache,
+          success: deps.success,
+          ...(deps.persistUpstreamTokens
+            ? { persistUpstreamTokens: deps.persistUpstreamTokens }
+            : {}),
+          issuerUrl: c.get("issuerUrl"),
+          clock: deps.clock,
+          ...(deps.customScopeClaims !== undefined
+            ? { customScopeClaims: deps.customScopeClaims }
+            : {}),
+        },
+        tenantRes.value,
+      )
+      if (isErr(result)) return tokenEndpointErrorResponse(result.error)
+      return jsonResponse(result.value)
+    }
+
+    if (req.grant_type === "refresh_token") {
+      const refreshResult = await refreshTokens(
+        {
+          grantType: "refresh_token",
+          refreshToken: req.refresh_token,
+          ...(req.scope !== undefined ? { scope: req.scope } : {}),
+          ...(req.client_id !== undefined ? { clientId: req.client_id } : {}),
+          ...(req.client_secret !== undefined
+            ? { clientSecret: req.client_secret }
+            : {}),
+          ...(dpopJkt !== undefined ? { dpopJkt } : {}),
+        },
+        {
+          configStore: deps.configStore,
+          tokenStore: deps.tokenStore,
+          keyStore: deps.keyStore,
+          ...(deps.auditLog ? { auditLog: deps.auditLog } : {}),
+          issuerUrl: c.get("issuerUrl"),
+          clock: deps.clock,
+          ...(deps.customScopeClaims !== undefined
+            ? { customScopeClaims: deps.customScopeClaims }
+            : {}),
+        },
+      )
+      if (isErr(refreshResult))
+        return tokenEndpointErrorResponse(refreshResult.error)
+      return jsonResponse(refreshResult.value)
+    }
+
+    // RFC 8693 token-exchange. Delegation (actor_token) is out of scope;
+    // reject up front so we don't silently accept an actor and ignore it.
+    if (req.actor_token !== undefined) {
+      return tokenEndpointErrorResponse(
+        authError.invalidRequest(
+          "actor_token (delegation) is not supported; only impersonation / audience-switch is in scope",
+        ),
+      )
+    }
+    const exchangeResult = await exchangeToken(
+      {
+        grantType: req.grant_type,
+        subjectToken: req.subject_token,
+        audience: req.audience,
+        ...(req.scope !== undefined ? { scope: req.scope } : {}),
+        ...(req.client_id !== undefined ? { clientId: req.client_id } : {}),
+        ...(req.client_secret !== undefined
+          ? { clientSecret: req.client_secret }
+          : {}),
+      },
+      {
+        configStore: deps.configStore,
+        tokenStore: deps.tokenStore,
+        keyStore: deps.keyStore,
+        ...(deps.auditLog ? { auditLog: deps.auditLog } : {}),
+        ...(deps.exchangeAudience
+          ? { exchangeAudience: deps.exchangeAudience }
+          : {}),
+        issuerUrl: c.get("issuerUrl"),
+        clock: deps.clock,
+        ...(deps.customScopeClaims !== undefined
+          ? { customScopeClaims: deps.customScopeClaims }
+          : {}),
+      },
+    )
+    if (isErr(exchangeResult)) {
+      return tokenEndpointErrorResponse(exchangeResult.error)
+    }
+    return jsonResponse(exchangeResult.value)
+  }
+}
+
+function jsonResponse(body: unknown): Response {
+  return new Response(JSON.stringify(body), {
+    status: 200,
+    headers: {
+      "content-type": "application/json",
+      "cache-control": "no-store",
+      pragma: "no-cache",
+    },
+  })
+}
+
+async function readFormBody(req: Request): Promise<URLSearchParams | null> {
+  const ct = req.headers.get("content-type") ?? ""
+  if (!ct.toLowerCase().startsWith("application/x-www-form-urlencoded")) {
+    return null
+  }
+  const text = await req.text()
+  return new URLSearchParams(text)
+}
+
+function parseBasicAuth(
+  header: string | null,
+): { id: string; secret: string } | null {
+  if (!header) return null
+  const m = /^Basic\s+(.+)$/i.exec(header)
+  if (!m || !m[1]) return null
+  try {
+    const decoded = atob(m[1])
+    const colon = decoded.indexOf(":")
+    if (colon === -1) return null
+    return {
+      id: decodeURIComponent(decoded.slice(0, colon)),
+      secret: decodeURIComponent(decoded.slice(colon + 1)),
+    }
+  } catch {
+    return null
+  }
+}

package/src/http/handlers/userinfo.ts

@@ -0,0 +1,90 @@
+/**
+ * OIDC `/userinfo` handler (OIDC Core §5.3). Accepts `GET` or `POST` per
+ * the spec. Supports both `Authorization: Bearer ...` (RFC 6750) and
+ * `Authorization: DPoP ...` (RFC 9449) — the domain layer enforces the
+ * proof match against the access token's `cnf.jkt` when bound.
+ */
+import { canonicalHtu } from "../../domain/dpop"
+import { userinfo } from "../../domain/userinfo"
+import { isErr } from "../../types/result"
+
+import type { HttpContext, HttpDeps } from "../context"
+
+export function makeUserinfoHandler(deps: HttpDeps) {
+  return async (c: HttpContext): Promise<Response> => {
+    const auth = extractAuthorization(c.req.header("authorization") ?? null)
+    if (!auth) {
+      return wwwAuthenticateResponse(
+        "Bearer",
+        "invalid_token",
+        "missing bearer / DPoP token",
+        401,
+      )
+    }
+
+    const dpopProof = c.req.header("dpop") ?? undefined
+    const res = await userinfo(
+      {
+        accessToken: auth.token,
+        scheme: auth.scheme,
+        ...(dpopProof !== undefined ? { dpopProof } : {}),
+        htu: canonicalHtu(c.req.url),
+        htm: c.req.method.toUpperCase(),
+        nowSec: Math.floor(deps.clock() / 1000),
+      },
+      {
+        keyStore: deps.keyStore,
+        tokenStore: deps.tokenStore,
+        issuerUrl: c.get("issuerUrl"),
+        ...(deps.customScopeClaims !== undefined
+          ? { customScopeClaims: deps.customScopeClaims }
+          : {}),
+      },
+    )
+    if (isErr(res)) {
+      const error = res.error
+      const scheme = auth.scheme
+      const wireError =
+        error.code === "invalid_dpop_proof"
+          ? "invalid_dpop_proof"
+          : "invalid_token"
+      return wwwAuthenticateResponse(scheme, wireError, error.description, 401)
+    }
+
+    return new Response(JSON.stringify(res.value), {
+      status: 200,
+      headers: {
+        "content-type": "application/json",
+        "cache-control": "no-store",
+      },
+    })
+  }
+}
+
+function extractAuthorization(
+  header: string | null,
+): { scheme: "Bearer" | "DPoP"; token: string } | null {
+  if (!header) return null
+  const m = /^(Bearer|DPoP)\s+(.+)$/i.exec(header)
+  if (!m || !m[1] || !m[2]) return null
+  const scheme = m[1].toLowerCase() === "dpop" ? "DPoP" : "Bearer"
+  return { scheme, token: m[2] }
+}
+
+function wwwAuthenticateResponse(
+  scheme: "Bearer" | "DPoP",
+  error: string,
+  description: string,
+  status: number,
+): Response {
+  return new Response(
+    JSON.stringify({ error, error_description: description }),
+    {
+      status,
+      headers: {
+        "content-type": "application/json",
+        "www-authenticate": `${scheme} error="${error}"`,
+      },
+    },
+  )
+}

package/src/http/middleware/error.ts

@@ -0,0 +1,26 @@
+/**
+ * Global error middleware. Catches thrown values and serializes them as
+ * OAuth-compliant responses. Inside handlers we route through `Result<T,
+ * AuthError>` instead — this is the last-resort net for unexpected throws.
+ */
+import type { MiddlewareHandler } from "hono"
+
+import { authError } from "../../types/error"
+
+import type { HttpDeps, HttpEnv } from "../context"
+import { tokenEndpointErrorResponse } from "../errors"
+
+export function errorMiddleware(_deps: HttpDeps): MiddlewareHandler<HttpEnv> {
+  return async (_c, next) => {
+    try {
+      await next()
+    } catch (e) {
+      return tokenEndpointErrorResponse(
+        authError.serverError(
+          e instanceof Error ? e.message : "unexpected error",
+          e,
+        ),
+      )
+    }
+  }
+}

package/src/http/middleware/tenant.ts

@@ -0,0 +1,165 @@
+/**
+ * Tenant resolution + callback-recovery middleware.
+ *
+ * Phase 3 ships the mac-state recovery path. Mechanisms #2 (partitioned
+ * host) and #3 (`flowId`-in-URI) are scaffolded but not yet plumbed end-to-
+ * end (per plan §"Phase 2 — Deferred"); the framework currently falls back
+ * to `resolveTenant` when the state envelope is absent or invalid, so users
+ * who want partitioned-host deployments can implement the lookup inside
+ * their own `resolveTenant`.
+ *
+ * Order on `/cb/*`:
+ *   1. If `state` MAC-verifies → `mac-state`. `resolveTenant` is NOT called.
+ *   2. Else fall through to `resolveTenant` (host-plus-* deployments do the
+ *      host inspection there).
+ *
+ * Order on all other paths: `resolveTenant` directly.
+ */
+import type { MiddlewareHandler } from "hono"
+
+import { verifyStateEnvelope } from "../../domain/state-envelope"
+import { isErr } from "../../types/result"
+import type {
+  TenantConfig,
+  TenantContext,
+  TenantId,
+  TenantRecovery,
+} from "../../types/tenant"
+
+import { parseCookieHeader } from "../cookies"
+import type { HttpDeps, HttpEnv } from "../context"
+import {
+  authorizeDirectErrorResponse,
+  tokenEndpointErrorResponse,
+} from "../errors"
+import { authError } from "../../types/error"
+
+function isCallbackPath(pathname: string): boolean {
+  return pathname.startsWith("/cb/")
+}
+
+/**
+ * Initial pass — parse cookies + resolve issuer URL. Runs unconditionally.
+ */
+export function bootstrapMiddleware(
+  deps: HttpDeps,
+): MiddlewareHandler<HttpEnv> {
+  return async (c, next) => {
+    const cookies = parseCookieHeader(c.req.header("cookie") ?? null)
+    c.set("cookies", cookies)
+    c.set("issuerUrl", deps.resolveIssuer(c.req.raw))
+    c.set("tenant", null)
+    c.set("recovery", null)
+    await next()
+  }
+}
+
+/**
+ * Tenant + recovery resolution middleware. Mount on routes that need a
+ * tenant in scope (`/authorize`, method dispatch, `/cb/*`). Token endpoints
+ * derive tenant from the auth code's snapshot — they skip this middleware.
+ */
+export function tenantMiddleware(deps: HttpDeps): MiddlewareHandler<HttpEnv> {
+  return async (c, next) => {
+    const url = new URL(c.req.url)
+
+    if (isCallbackPath(url.pathname)) {
+      const recovery = await runCallbackRecovery(c.req.raw, deps)
+      c.set("recovery", recovery)
+      if (recovery.kind !== "fresh-request") {
+        const cfg = await deps.configStore.getTenantConfig(recovery.tenantId)
+        if (isErr(cfg)) {
+          return tokenEndpointErrorResponse(cfg.error)
+        }
+        const customCb = deps.buildCustomContext
+          ? await deps.buildCustomContext(c.req.raw)
+          : {}
+        c.set(
+          "tenant",
+          buildTenantContext(c.req.raw, recovery.tenantId, cfg.value, customCb),
+        )
+        return next()
+      }
+    }
+
+    const resolved = await deps.resolveTenant(c.req.raw)
+    if (isErr(resolved)) {
+      // For /authorize, surface as plain text (open-redirector defense — we
+      // don't have a verified RP yet). For other paths, JSON suffices.
+      if (url.pathname === "/authorize") {
+        return authorizeDirectErrorResponse(resolved.error)
+      }
+      return tokenEndpointErrorResponse(resolved.error)
+    }
+    const tenantId = resolved.value
+    const cfg = await deps.configStore.getTenantConfig(tenantId)
+    if (isErr(cfg)) {
+      const err =
+        cfg.error.code === "tenant_not_found"
+          ? authError.invalidRequest(cfg.error.description, "tenant")
+          : cfg.error
+      if (url.pathname === "/authorize") {
+        return authorizeDirectErrorResponse(err)
+      }
+      return tokenEndpointErrorResponse(err)
+    }
+    const custom = deps.buildCustomContext
+      ? await deps.buildCustomContext(c.req.raw)
+      : {}
+    c.set("tenant", buildTenantContext(c.req.raw, tenantId, cfg.value, custom))
+    await next()
+  }
+}
+
+function buildTenantContext(
+  req: Request,
+  id: TenantId,
+  config: TenantConfig,
+  custom: Record<string, unknown>,
+): TenantContext {
+  return {
+    id,
+    config,
+    request: { raw: req, custom },
+  }
+}
+
+async function runCallbackRecovery(
+  req: Request,
+  deps: HttpDeps,
+): Promise<TenantRecovery> {
+  const state = await extractStateParam(req)
+  if (state) {
+    const env = await verifyStateEnvelope(state, deps.stateKeys)
+    if (env.ok) {
+      return {
+        kind: "mac-state",
+        tenantId: env.value.tenantId,
+        flowId: env.value.flowId,
+      }
+    }
+  }
+  return { kind: "fresh-request" }
+}
+
+/**
+ * Pull `state` from the query for GET callbacks, or from a form body for
+ * POST callbacks (Apple's `response_mode=form_post`). The body is cloned
+ * so the handler can still read it.
+ */
+async function extractStateParam(req: Request): Promise<string | null> {
+  const url = new URL(req.url)
+  const fromQuery = url.searchParams.get("state")
+  if (fromQuery) return fromQuery
+  if (req.method !== "POST") return null
+  const ct = req.headers.get("content-type") ?? ""
+  if (!ct.toLowerCase().startsWith("application/x-www-form-urlencoded")) {
+    return null
+  }
+  try {
+    const text = await req.clone().text()
+    return new URLSearchParams(text).get("state")
+  } catch {
+    return null
+  }
+}

package/src/http/resolver.ts

@@ -0,0 +1,34 @@
+/**
+ * Helpers that prepare a `Request` for the host-supplied
+ * `IdPOptions.resolveTenant` hook.
+ *
+ * The canonical resolver reads `client_id` from URL search params
+ * (INTEGRATION.md §5.1). On endpoints where `client_id` is carried in
+ * the form body / Basic-auth header rather than the URL (m2m at
+ * `/token`, introspect at `/introspect`, revoke at `/revoke`) the
+ * framework parses the body first and then injects the parsed
+ * `client_id` into a synthesized request so the resolver still sees
+ * what it expects.
+ */
+
+/**
+ * Build a new `Request` whose URL search params carry the supplied
+ * resolver hints. Existing query params win — hosts can still override
+ * via the URL. Headers are copied so Basic-auth-based resolvers still
+ * see the original `Authorization`. The body is intentionally dropped:
+ * the original is already consumed by the handler and resolvers must
+ * not depend on body state.
+ */
+export function injectResolverHints(
+  original: Request,
+  hints: Record<string, string>,
+): Request {
+  const url = new URL(original.url)
+  for (const [k, v] of Object.entries(hints)) {
+    if (!url.searchParams.has(k)) url.searchParams.set(k, v)
+  }
+  return new Request(url.toString(), {
+    method: original.method,
+    headers: original.headers,
+  })
+}