@_mustachio/openauth 0.9.2 → 0.11.0

package/src/http/context.ts

@@ -0,0 +1,90 @@
+/**
+ * Shared deps + per-request context for the HTTP layer.
+ *
+ * `HttpDeps` is constructed once by `createIdP` and threaded through every
+ * handler. `HttpVars` is the per-request Hono-variable shape: tenant
+ * resolution, parsed cookies, optional recovery info from the callback chain.
+ */
+import type { Context } from "hono"
+
+import type { AuditLog } from "../ports/audit-log"
+import type { ConfigStore } from "../ports/config-store"
+import type { KeyStore } from "../ports/key-store"
+import type { MethodStore } from "../ports/method-store"
+import type { SessionStore } from "../ports/session-store"
+import type { TokenStore } from "../ports/token-store"
+import type { MethodCache } from "../domain/method-cache"
+import type { AuthError } from "../types/error"
+import type {
+  ExchangeAudience,
+  PersistUpstreamTokens,
+  RegisterClient,
+  RenderPicker,
+  SuccessMapInput,
+} from "../types/idp"
+import type { Result } from "../types/result"
+import type { SubjectClaim } from "../types/subject"
+import type {
+  StateKeyRing,
+  TenantContext,
+  TenantId,
+  TenantRecovery,
+} from "../types/tenant"
+
+import type { CookieDefaults } from "./cookies"
+
+/** Long-lived deps the HTTP layer shares across requests. */
+export type HttpDeps = {
+  configStore: ConfigStore
+  tokenStore: TokenStore
+  sessionStore: SessionStore
+  keyStore: KeyStore
+  methodStore?: MethodStore
+  auditLog?: AuditLog
+  methodCache: MethodCache
+  stateKeys: StateKeyRing
+  /** Resolves the issuer URL — string or per-request function. */
+  resolveIssuer: (req: Request) => string
+  /** Optional partitioned-host helper (recovery #2). */
+  callbackHostFor?: (tenantId: TenantId) => string
+  resolveTenant: (req: Request) => Promise<Result<TenantId, AuthError>>
+  success: (input: SuccessMapInput) => Promise<SubjectClaim>
+  persistUpstreamTokens?: PersistUpstreamTokens
+  exchangeAudience?: ExchangeAudience
+  renderPicker?: RenderPicker
+  registerClient?: RegisterClient
+  /** Builds `TenantContext.request.custom` for every request. See `IdPOptions.buildCustomContext`. */
+  buildCustomContext?: (
+    req: Request,
+  ) => Record<string, unknown> | Promise<Record<string, unknown>>
+  clock: () => number
+  cookieDefaults: CookieDefaults
+  /** See `IdPOptions.customScopeClaims`. */
+  customScopeClaims?: Record<string, ReadonlyArray<string>>
+}
+
+/** Per-request variables populated by middleware. */
+export type HttpVars = {
+  /** Parsed `Cookie:` header. */
+  cookies: Map<string, string>
+  /** Populated by the tenant middleware. May be `null` for unauthenticated public endpoints. */
+  tenant: TenantContext | null
+  /** Outcome of the callback-recovery chain on `/cb/*` requests. */
+  recovery: TenantRecovery | null
+  /** Issuer URL for this request — pre-resolved by middleware. */
+  issuerUrl: string
+}
+
+export type HttpEnv = {
+  Variables: HttpVars
+}
+
+export type HttpContext = Context<HttpEnv>
+
+/** Convenience: build the initial `HttpVars` value for a request. */
+export function initialVars(
+  issuerUrl: string,
+  cookies: Map<string, string>,
+): HttpVars {
+  return { cookies, tenant: null, recovery: null, issuerUrl }
+}

package/src/http/cookies.ts

@@ -0,0 +1,167 @@
+/**
+ * Cookie parsing + serialization for the HTTP layer.
+ *
+ * The framework owns cookie policy (per `ARCHITECTURE.md` §"Response
+ * sanitization"). Methods never set cookies through `Response.headers`; they
+ * return `SetCookie[]` data and this module renders them. We additionally
+ * strip method-returned `Set-Cookie` / security / `Cache-Control` headers so
+ * methods cannot bypass policy.
+ */
+import type { SetCookie } from "../types/method"
+
+/** Parse an incoming `Cookie:` header into a read-only map. */
+export function parseCookieHeader(header: string | null): Map<string, string> {
+  const out = new Map<string, string>()
+  if (!header) return out
+  for (const part of header.split(";")) {
+    const trimmed = part.trim()
+    if (!trimmed) continue
+    const eq = trimmed.indexOf("=")
+    if (eq === -1) {
+      out.set(trimmed, "")
+      continue
+    }
+    const name = trimmed.slice(0, eq).trim()
+    const raw = trimmed.slice(eq + 1).trim()
+    const value =
+      raw.startsWith('"') && raw.endsWith('"') ? raw.slice(1, -1) : raw
+    try {
+      out.set(name, decodeURIComponent(value))
+    } catch {
+      out.set(name, value)
+    }
+  }
+  return out
+}
+
+export type CookieDefaults = {
+  /** Secure flag default. Production should pass `true`. */
+  secure?: boolean
+  domain?: string
+  path?: string
+}
+
+const RESERVED_PREFIX = /^(auth|idp)\./
+
+/**
+ * Characters explicitly forbidden in a cookie name. RFC 6265 §4.1.1 defers
+ * to RFC 2616's `token` grammar (no separators, no CTLs); rather than the
+ * full grammar we reject the chars most likely to corrupt the header on
+ * splice: `=`, `;`, `,`, and any whitespace. Method-returned cookie names
+ * are the realistic source of bad input here — internal callers use fixed
+ * `auth.*` / `idp.*` names that pass.
+ */
+const INVALID_COOKIE_NAME = /[=;,\s]/
+
+function assertValidCookieName(name: string): void {
+  if (!name || INVALID_COOKIE_NAME.test(name)) {
+    throw new TypeError(
+      `invalid cookie name ${JSON.stringify(name)} — must be non-empty and contain no '=', ';', ',' or whitespace`,
+    )
+  }
+}
+
+/**
+ * Serialize a single `SetCookie` data instruction into a `Set-Cookie` header
+ * string. Enforces framework policy:
+ *   - `Secure` forced on if `defaults.secure === true`.
+ *   - `SameSite` defaults to `Lax` if unspecified.
+ *   - `HttpOnly` defaults to `true` for any cookie name in the `auth.*` /
+ *     `idp.*` reserved namespace.
+ *   - `null` value → `Max-Age=0` to clear.
+ */
+export function serializeSetCookie(
+  cookie: SetCookie,
+  defaults: CookieDefaults = {},
+): string {
+  assertValidCookieName(cookie.name)
+  const parts: string[] = []
+  const value = cookie.value ?? ""
+  parts.push(`${cookie.name}=${encodeURIComponent(value)}`)
+
+  const path = cookie.path ?? defaults.path ?? "/"
+  parts.push(`Path=${path}`)
+
+  const domain = cookie.domain ?? defaults.domain
+  if (domain) parts.push(`Domain=${domain}`)
+
+  if (cookie.value === null) {
+    parts.push("Max-Age=0")
+  } else if (cookie.maxAge !== undefined) {
+    parts.push(`Max-Age=${cookie.maxAge}`)
+  }
+
+  const secure = cookie.secure ?? defaults.secure ?? false
+  if (secure) parts.push("Secure")
+
+  const httpOnly = cookie.httpOnly ?? RESERVED_PREFIX.test(cookie.name)
+  if (httpOnly) parts.push("HttpOnly")
+
+  const sameSite = cookie.sameSite ?? "lax"
+  parts.push(`SameSite=${sameSite.charAt(0).toUpperCase() + sameSite.slice(1)}`)
+
+  return parts.join("; ")
+}
+
+/** Headers the framework strips from any method-returned `Response`. */
+const STRIPPED_HEADERS = [
+  "set-cookie",
+  "set-cookie2",
+  "strict-transport-security",
+  "content-security-policy",
+  "content-security-policy-report-only",
+  "x-frame-options",
+  "x-content-type-options",
+  "referrer-policy",
+  "permissions-policy",
+  "cache-control",
+] as const
+
+export type ApplyOptions = {
+  setCookies?: SetCookie[]
+  cookieDefaults?: CookieDefaults
+  /** When set, framework writes this `Cache-Control` value. Default `no-store`. */
+  cacheControl?: string
+}
+
+/**
+ * Sanitize a method-returned `Response` and apply framework-owned headers.
+ *
+ * Returns a new `Response` so the original is left untouched. When the
+ * method's response carried any of the stripped headers, emit a
+ * `console.warn` so a programmer notices their header got dropped
+ * silently. (Per ARCHITECTURE.md §"Response sanitization"; switches to
+ * the Logger port when that lands in Phase 8.)
+ */
+export function applyResponsePolicy(
+  response: Response,
+  opts: ApplyOptions = {},
+): Response {
+  const headers = new Headers(response.headers)
+  const stripped: string[] = []
+  for (const h of STRIPPED_HEADERS) {
+    if (headers.has(h)) {
+      stripped.push(h)
+      headers.delete(h)
+    }
+  }
+  if (stripped.length > 0) {
+    console.warn(
+      `[openauth] dropped method-returned header(s) ${stripped.join(", ")} — the framework owns cookie/security/cache headers; methods should return cookies via MethodResult.setCookies.`,
+    )
+  }
+
+  headers.set("Cache-Control", opts.cacheControl ?? "no-store")
+
+  if (opts.setCookies) {
+    for (const c of opts.setCookies) {
+      headers.append("Set-Cookie", serializeSetCookie(c, opts.cookieDefaults))
+    }
+  }
+
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers,
+  })
+}

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