@_mustachio/openauth 0.9.2 → 0.10.0

package/src/http/handlers/revocation.ts

@@ -0,0 +1,151 @@
+/**
+ * RFC 7009 `/revoke` and RFC 7662 `/introspect` HTTP shims.
+ *
+ * Both accept `application/x-www-form-urlencoded`. Client credentials
+ * may ride in the form body (`client_id`, `client_secret`) or in an
+ * `Authorization: Basic` header (RFC 6749 §2.3.1); the header wins when
+ * both are present.
+ *
+ * Revoke: anonymous calls are permitted for tokens issued to public
+ * clients (RFC 7009 §2.1). Confidential-client tokens require auth.
+ *
+ * Introspect: client auth is REQUIRED (RFC 7662 §2.1). Anonymous calls
+ * are rejected at this layer with `invalid_client`.
+ */
+import { resolveClientCredentials } from "../../domain/client-auth"
+import { introspect } from "../../domain/introspect"
+import { revokeToken } from "../../domain/revoke"
+import { authError } from "../../types/error"
+import { isErr } from "../../types/result"
+
+import type { HttpContext, HttpDeps } from "../context"
+import { tokenEndpointErrorResponse } from "../errors"
+import { injectResolverHints } from "../resolver"
+import { introspectBodySchema, revokeBodySchema } from "../schemas/revocation"
+
+export function makeRevokeHandler(deps: HttpDeps) {
+  return async (c: HttpContext): Promise<Response> => {
+    const body = await readForm(c.req.raw)
+    if (!body) {
+      return tokenEndpointErrorResponse(
+        authError.invalidRequest(
+          "body must be application/x-www-form-urlencoded",
+        ),
+      )
+    }
+    const parsed = revokeBodySchema.safeParse(
+      Object.fromEntries(body.entries()),
+    )
+    if (!parsed.success) {
+      return tokenEndpointErrorResponse(
+        authError.invalidRequest(parsed.error.issues[0]?.message ?? "invalid"),
+      )
+    }
+    const creds = resolveClientCredentials({
+      authorizationHeader: c.req.header("authorization") ?? null,
+      bodyClientId: parsed.data.client_id,
+      bodyClientSecret: parsed.data.client_secret,
+    })
+    const res = await revokeToken(
+      {
+        token: parsed.data.token,
+        ...(parsed.data.token_type_hint
+          ? { tokenTypeHint: parsed.data.token_type_hint }
+          : {}),
+        ...(creds ? { clientId: creds.clientId } : {}),
+        ...(creds?.clientSecret !== undefined
+          ? { clientSecret: creds.clientSecret }
+          : {}),
+      },
+      {
+        tokenStore: deps.tokenStore,
+        configStore: deps.configStore,
+        ...(deps.auditLog ? { auditLog: deps.auditLog } : {}),
+        clock: deps.clock,
+      },
+    )
+    if (isErr(res)) return tokenEndpointErrorResponse(res.error)
+    // RFC 7009 §2.2: success returns 200 with empty body.
+    return new Response(null, {
+      status: 200,
+      headers: { "cache-control": "no-store" },
+    })
+  }
+}
+
+export function makeIntrospectHandler(deps: HttpDeps) {
+  return async (c: HttpContext): Promise<Response> => {
+    const body = await readForm(c.req.raw)
+    if (!body) {
+      return tokenEndpointErrorResponse(
+        authError.invalidRequest(
+          "body must be application/x-www-form-urlencoded",
+        ),
+      )
+    }
+    const parsed = introspectBodySchema.safeParse(
+      Object.fromEntries(body.entries()),
+    )
+    if (!parsed.success) {
+      return tokenEndpointErrorResponse(
+        authError.invalidRequest(parsed.error.issues[0]?.message ?? "invalid"),
+      )
+    }
+    const creds = resolveClientCredentials({
+      authorizationHeader: c.req.header("authorization") ?? null,
+      bodyClientId: parsed.data.client_id,
+      bodyClientSecret: parsed.data.client_secret,
+    })
+    if (!creds) {
+      // RFC 7662 §2.1 — endpoint MUST require some form of auth.
+      return tokenEndpointErrorResponse(
+        authError.invalidClient("introspection requires client authentication"),
+      )
+    }
+    // Resolve the presenter's tenant from the request the same way the
+    // m2m grant does — by injecting client_id into the URL so a
+    // canonical search-param resolver works for introspect too.
+    const tenantRes = await deps.resolveTenant(
+      injectResolverHints(c.req.raw, { client_id: creds.clientId }),
+    )
+    if (isErr(tenantRes)) {
+      return tokenEndpointErrorResponse(
+        authError.invalidClient(`unknown client "${creds.clientId}"`),
+      )
+    }
+    const res = await introspect(
+      {
+        token: parsed.data.token,
+        ...(parsed.data.token_type_hint
+          ? { tokenTypeHint: parsed.data.token_type_hint }
+          : {}),
+        clientId: creds.clientId,
+        ...(creds.clientSecret !== undefined
+          ? { clientSecret: creds.clientSecret }
+          : {}),
+        presenterTenantId: tenantRes.value,
+      },
+      {
+        keyStore: deps.keyStore,
+        configStore: deps.configStore,
+        issuerUrl: c.get("issuerUrl"),
+      },
+    )
+    if (isErr(res)) return tokenEndpointErrorResponse(res.error)
+    return new Response(JSON.stringify(res.value), {
+      status: 200,
+      headers: {
+        "content-type": "application/json",
+        "cache-control": "no-store",
+      },
+    })
+  }
+}
+
+async function readForm(req: Request): Promise<URLSearchParams | null> {
+  const ct = req.headers.get("content-type") ?? ""
+  if (!ct.toLowerCase().startsWith("application/x-www-form-urlencoded")) {
+    return null
+  }
+  return new URLSearchParams(await req.text())
+}

package/src/http/handlers/token.ts

@@ -0,0 +1,244 @@
+/**
+ * `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 { 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",
+        ),
+      )
+    }
+
+    const basic = parseBasicAuth(c.req.header("authorization") ?? null)
+    if (basic) {
+      body.set("client_id", basic.id)
+      body.set("client_secret", basic.secret)
+    }
+
+    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 }
+            : {}),
+        },
+        {
+          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,
+        },
+      )
+      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,
+        },
+        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 }
+            : {}),
+        },
+        {
+          configStore: deps.configStore,
+          tokenStore: deps.tokenStore,
+          keyStore: deps.keyStore,
+          ...(deps.auditLog ? { auditLog: deps.auditLog } : {}),
+          issuerUrl: c.get("issuerUrl"),
+          clock: deps.clock,
+        },
+      )
+      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,
+      },
+    )
+    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,66 @@
+/**
+ * OIDC `/userinfo` handler (OIDC Core §5.3). Accepts `GET` or `POST` per
+ * the spec.
+ */
+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 bearer = extractBearer(c.req.header("authorization") ?? null)
+    if (!bearer) {
+      const r = new Response(
+        JSON.stringify({
+          error: "invalid_token",
+          error_description: "missing bearer token",
+        }),
+        {
+          status: 401,
+          headers: {
+            "content-type": "application/json",
+            "www-authenticate": 'Bearer realm="userinfo"',
+          },
+        },
+      )
+      return r
+    }
+
+    const res = await userinfo(bearer, {
+      keyStore: deps.keyStore,
+      issuerUrl: c.get("issuerUrl"),
+    })
+    if (isErr(res)) {
+      // OIDC userinfo returns 401 on invalid token (vs. 400 elsewhere).
+      const err = res.error
+      return new Response(
+        JSON.stringify({
+          error: "invalid_token",
+          error_description: err.description,
+        }),
+        {
+          status: 401,
+          headers: {
+            "content-type": "application/json",
+            "www-authenticate": `Bearer error="invalid_token"`,
+          },
+        },
+      )
+    }
+
+    return new Response(JSON.stringify(res.value), {
+      status: 200,
+      headers: {
+        "content-type": "application/json",
+        "cache-control": "no-store",
+      },
+    })
+  }
+}
+
+function extractBearer(header: string | null): string | null {
+  if (!header) return null
+  const m = /^Bearer\s+(.+)$/i.exec(header)
+  return m?.[1] ?? null
+}

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,
+  })
+}