@_mustachio/openauth 0.9.2 → 0.10.0

package/src/domain/token.ts

@@ -0,0 +1,357 @@
+/**
+ * `/token` endpoint logic for `grant_type=authorization_code`.
+ *
+ * Steps:
+ *   1. Authenticate client (public: id only; confidential: id + secret).
+ *   2. `TokenStore.consumeCode(code)` — strong CAS; returns the decrypted
+ *      `CodePayload`.
+ *   3. Verify the consumed code matches the request (`client_id`,
+ *      `redirect_uri`). Any mismatch → `invalid_grant`.
+ *   4. Verify PKCE if the code carries a `clientPkce` (RP→IdP PKCE).
+ *   5. Call the user's `success` callback with `SuccessMapInput` to mint
+ *      the `SubjectClaim` — the same role the legacy `auth.success`
+ *      callback plays in `issuer.ts`.
+ *   6. (Optional) `persistUpstreamTokens` hook — runs here, not at
+ *      callback time, so failed exchanges don't pollute the secrets store.
+ *   7. Mint access (JWT, ES256) + refresh (random opaque) tokens, save
+ *      refresh, audit `token_issued`.
+ *
+ * Refresh-grant logic lives in `./refresh.ts`. Revocation in `./revoke.ts`.
+ */
+import type { AuditLog } from "../ports/audit-log"
+import type { KeyStore } from "../ports/key-store"
+import type { TokenStore } from "../ports/token-store"
+import type { ConfigStore } from "../ports/config-store"
+import type { AuthError } from "../types/error"
+import { authError } from "../types/error"
+import type { PersistUpstreamTokens, SuccessMapInput } from "../types/idp"
+import type { Result } from "../types/result"
+import { err, isErr, ok } from "../types/result"
+import type { SubjectClaim } from "../types/subject"
+import type { TenantContext } from "../types/tenant"
+import type {
+  AccessTokenClaims,
+  CodePayload,
+  RefreshTokenPayload,
+  TokenResponse,
+} from "../types/token"
+
+import { safeAudit } from "./audit"
+import { verifyClientCredentials } from "./client-auth"
+import {
+  base64url,
+  decryptPayload,
+  encryptPayload,
+  randomId,
+  randomToken,
+  sha256,
+  utf8,
+} from "./crypto"
+import { signAccessToken } from "./jwt"
+import { validatePkce } from "./pkce"
+
+/**
+ * Encrypt a `CodePayload` with the active `KeyStore` encryption key and
+ * persist it via `tokenStore.saveCode`. Centralizes the encrypt-then-store
+ * pattern so adapters never see plaintext (M1).
+ */
+export async function saveEncryptedCode(
+  code: string,
+  payload: CodePayload,
+  ttl: number,
+  deps: { keyStore: KeyStore; tokenStore: TokenStore },
+): Promise<Result<void, AuthError>> {
+  const keyResult = await deps.keyStore.currentEncryptionKey()
+  if (isErr(keyResult)) return err(keyResult.error)
+  let ciphertext: string
+  try {
+    ciphertext = await encryptPayload(
+      payload,
+      keyResult.value.kid,
+      keyResult.value.keyRef as Uint8Array,
+    )
+  } catch (e) {
+    return err(authError.internalError("saveEncryptedCode: encrypt failed", e))
+  }
+  return deps.tokenStore.saveCode(code, ciphertext, ttl)
+}
+
+export const DEFAULT_ACCESS_TTL_MS = 15 * 60 * 1000
+export const DEFAULT_REFRESH_TTL_MS = 30 * 24 * 60 * 60 * 1000
+
+export type TokenAuthCodeRequest = {
+  grantType: "authorization_code"
+  code: string
+  redirectUri: string
+  clientId: string
+  /** Confidential clients only. */
+  clientSecret?: string
+  /** Required if the original `/authorize` request had a `code_challenge`. */
+  codeVerifier?: string
+}
+
+export type ExchangeCodeDeps = {
+  configStore: ConfigStore
+  tokenStore: TokenStore
+  keyStore: KeyStore
+  auditLog?: AuditLog
+  success: (input: SuccessMapInput) => Promise<SubjectClaim>
+  persistUpstreamTokens?: PersistUpstreamTokens
+  issuerUrl: string
+  clock: () => number
+  newRefreshToken?: () => string
+  /** Test override. */
+  newRefreshFamily?: () => string
+}
+
+export async function exchangeCode(
+  req: TokenAuthCodeRequest,
+  deps: ExchangeCodeDeps,
+): Promise<Result<TokenResponse, AuthError>> {
+  // 1. Consume code (atomic; failure here means unknown / consumed / expired).
+  //    The adapter returns the ciphertext blob verbatim — encryption is
+  //    the domain's job (M1), so decrypt here before reading any field.
+  const consumed = await deps.tokenStore.consumeCode(req.code)
+  if (isErr(consumed)) return err(consumed.error)
+  let payload: CodePayload
+  try {
+    payload = await decryptPayload<CodePayload>(consumed.value, async (kid) => {
+      const keyResult = await deps.keyStore.getEncryptionKey(kid)
+      if (isErr(keyResult)) {
+        throw new Error(`unknown encryption kid ${kid}`)
+      }
+      return keyResult.value.keyRef as Uint8Array
+    })
+  } catch (e) {
+    return err(authError.internalError("exchangeCode: decrypt failed", e))
+  }
+
+  // 2. Load tenant + client.
+  const tenantCfg = await deps.configStore.getTenantConfig(payload.tenantId)
+  if (isErr(tenantCfg)) return err(tenantCfg.error)
+  const client = tenantCfg.value.clients.find((c) => c.id === payload.clientId)
+  if (!client) {
+    return err(authError.invalidClient(`unknown client "${payload.clientId}"`))
+  }
+
+  // 3. Client auth.
+  if (client.id !== req.clientId) {
+    return err(authError.invalidGrant("client_id mismatch with auth code"))
+  }
+  const authResult = await verifyClientCredentials(client, req.clientSecret)
+  if (authResult) return err(authResult)
+
+  // 4. Redirect URI binding.
+  if (payload.appRedirectUri !== req.redirectUri) {
+    return err(authError.invalidGrant("redirect_uri mismatch with auth code"))
+  }
+
+  // 5. PKCE check (RP → IdP).
+  if (payload.clientPkce) {
+    if (!req.codeVerifier) {
+      return err(authError.invalidGrant("missing code_verifier"))
+    }
+    const pkceValid = await validatePkce(
+      req.codeVerifier,
+      payload.clientPkce.challenge,
+    )
+    if (!pkceValid) {
+      return err(authError.invalidGrant("PKCE verification failed"))
+    }
+  }
+
+  // 6. Build the subject claim via user's success callback.
+  const tenant: TenantContext = {
+    id: payload.tenantId,
+    config: tenantCfg.value,
+    request: { raw: new Request("about:blank"), custom: {} },
+  }
+  let claim: SubjectClaim
+  try {
+    claim = await deps.success({
+      tenant,
+      methodId: payload.methodId,
+      methodKind: payload.methodKind,
+      providerSubject: payload.providerSubject,
+      properties: payload.properties,
+      context: payload.context ?? null,
+    })
+  } catch (e) {
+    return err(authError.serverError("success callback threw", e))
+  }
+
+  // 7. Optional upstream-tokens hook (runs after success, before
+  //    mint — failed mints below should NOT roll back this hook because
+  //    by contract the hook itself decides whether to persist).
+  if (deps.persistUpstreamTokens) {
+    try {
+      await deps.persistUpstreamTokens({
+        tenant,
+        methodId: payload.methodId,
+        methodKind: payload.methodKind,
+        providerSubject: payload.providerSubject,
+        properties: payload.properties,
+        subjectClaim: claim,
+      })
+    } catch (e) {
+      return err(authError.serverError("persistUpstreamTokens hook threw", e))
+    }
+  }
+
+  // 8. Mint access + refresh.
+  const minted = await mintTokens({
+    tenant,
+    claim,
+    payload,
+    deps,
+    family: (deps.newRefreshFamily ?? randomId)(),
+  })
+  return minted
+}
+
+/**
+ * Shared mint logic used by both `exchangeCode` and `refreshTokens` (which
+ * passes its previous `family` through to preserve the rotation chain).
+ */
+export async function mintTokens(args: {
+  tenant: TenantContext
+  claim: SubjectClaim
+  payload: Pick<
+    CodePayload,
+    "tenantId" | "clientId" | "methodId" | "methodKind" | "scopes" | "audience"
+  >
+  family: string
+  /**
+   * `client_credentials` grants (RFC 6749 §4.4.3) and other paths where a
+   * refresh token is not appropriate set `skipRefresh: true`. The response
+   * then omits `refresh_token` and **no row is written** to `TokenStore`,
+   * so the durable store doesn't accumulate orphaned refresh entries that
+   * the response strips and discards.
+   */
+  skipRefresh?: boolean
+  deps: {
+    keyStore: KeyStore
+    tokenStore: TokenStore
+    auditLog?: AuditLog
+    issuerUrl: string
+    clock: () => number
+    newRefreshToken?: () => string
+  }
+}): Promise<Result<TokenResponse, AuthError>> {
+  const { tenant, claim, payload, deps, family, skipRefresh } = args
+  const accessTtl =
+    tenant.config.accessTtl !== undefined
+      ? tenant.config.accessTtl * 1000
+      : DEFAULT_ACCESS_TTL_MS
+  const refreshTtl =
+    tenant.config.refreshTtl !== undefined
+      ? tenant.config.refreshTtl * 1000
+      : DEFAULT_REFRESH_TTL_MS
+  const now = deps.clock()
+  const subjectId = await deriveSubjectId(claim)
+
+  const keyRes = await deps.keyStore.currentSigningKey()
+  if (isErr(keyRes)) return err(keyRes.error)
+  const signingKey = keyRes.value
+
+  const claims: AccessTokenClaims = {
+    iss: deps.issuerUrl,
+    sub: subjectId,
+    aud: payload.audience ?? payload.clientId,
+    exp: Math.floor((now + accessTtl) / 1000),
+    iat: Math.floor(now / 1000),
+    tid: payload.tenantId,
+    mid: payload.methodId,
+    mkind: payload.methodKind,
+    scope: payload.scopes.join(" "),
+    claim,
+  }
+
+  let accessToken: string
+  try {
+    accessToken = await signAccessToken(
+      claims,
+      // jose's KeyLike covers both CryptoKey (Web Crypto) and the
+      // node:crypto KeyObject — the in-memory KeyStore stashes the result
+      // of generateKeyPair directly.
+      signingKey.privateKeyRef as Parameters<typeof signAccessToken>[1],
+      signingKey.alg,
+      signingKey.kid,
+    )
+  } catch (e) {
+    return err(authError.serverError("access token sign failed", e))
+  }
+
+  let refresh: string | undefined
+  if (!skipRefresh) {
+    refresh = (deps.newRefreshToken ?? randomToken)()
+    const refreshPayload: RefreshTokenPayload = {
+      tenantId: payload.tenantId,
+      clientId: payload.clientId,
+      subjectId,
+      claim,
+      scopes: payload.scopes,
+      audience: payload.audience,
+      family,
+      methodId: payload.methodId,
+      methodKind: payload.methodKind,
+      issuedAt: now,
+      expiresAt: now + refreshTtl,
+    }
+    const saved = await deps.tokenStore.saveRefresh(refresh, refreshPayload)
+    if (isErr(saved)) return err(saved.error)
+  }
+
+  await safeAudit(deps, {
+    kind: "token_issued",
+    tenantId: payload.tenantId,
+    clientId: payload.clientId,
+    methodId: payload.methodId,
+    methodKind: payload.methodKind,
+    subjectId,
+    refreshTokenIdHash: refresh ? await hashTokenForAudit(refresh) : "",
+    timestamp: now,
+  })
+
+  return ok({
+    access_token: accessToken,
+    token_type: "Bearer",
+    expires_in: Math.floor(accessTtl / 1000),
+    ...(refresh !== undefined ? { refresh_token: refresh } : {}),
+    scope: payload.scopes.join(" "),
+  })
+}
+
+/**
+ * Phase 2 client-secret hash format: SHA-256 over UTF-8 bytes, base64url.
+ *
+ * Production deployments will move to argon2id (per cross-cutting
+ * decisions) in Phase 8. The storage shape (`ClientConfig.secretHash:
+ * string`) is unchanged; only the hashing function swaps.
+ */
+export async function hashClientSecret(plain: string): Promise<string> {
+  return base64url.encode(await sha256(utf8.encode(plain)))
+}
+
+/**
+ * Derive a stable subject id from the issued `SubjectClaim`. Hash inputs
+ * are canonicalized so reordered `properties` keys hash identically.
+ */
+async function deriveSubjectId(claim: SubjectClaim): Promise<string> {
+  const c = claim as { type: string; properties: Record<string, unknown> }
+  const ordered = canonicalize(c.properties)
+  return base64url.encode(await sha256(`${c.type}\0${ordered}`)).slice(0, 22)
+}
+
+function canonicalize(value: unknown): string {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    return JSON.stringify(value)
+  }
+  const obj = value as Record<string, unknown>
+  const keys = Object.keys(obj).sort()
+  return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalize(obj[k])}`).join(",")}}`
+}
+
+async function hashTokenForAudit(token: string): Promise<string> {
+  return base64url.encode(await sha256(utf8.encode(token))).slice(0, 16)
+}

package/src/domain/userinfo.ts

@@ -0,0 +1,56 @@
+/**
+ * `/userinfo` endpoint logic (OIDC Core §5.3). Verifies the bearer access
+ * token and returns the inlined `SubjectClaim` claims.
+ */
+import type { KeyStore } from "../ports/key-store"
+import { authError, type AuthError } from "../types/error"
+import type { Result } from "../types/result"
+import { err, isErr, ok } from "../types/result"
+import type { SubjectClaim } from "../types/subject"
+import type { AccessTokenClaims } from "../types/token"
+
+import { verifyAccessToken } from "./jwt"
+
+export type UserinfoResponse = {
+  sub: string
+  /** Subject type discriminator (e.g. `"user"` / `"admin"`). */
+  subject_type: string
+  /** Inlined claim properties. */
+  properties: Record<string, unknown>
+  /** Scope granted to this access token. */
+  scope?: string
+}
+
+export type UserinfoDeps = {
+  keyStore: KeyStore
+  issuerUrl?: string
+}
+
+export async function userinfo(
+  bearerToken: string,
+  deps: UserinfoDeps,
+): Promise<Result<UserinfoResponse, AuthError>> {
+  const keysRes = await deps.keyStore.signingKeys()
+  if (isErr(keysRes)) return err(keysRes.error)
+
+  let claims: AccessTokenClaims
+  try {
+    claims = await verifyAccessToken(bearerToken, keysRes.value, {
+      ...(deps.issuerUrl ? { issuer: deps.issuerUrl } : {}),
+    })
+  } catch {
+    return err(authError.invalidGrant("access token invalid or expired"))
+  }
+
+  const claim = claims.claim as SubjectClaim & {
+    type: string
+    properties: Record<string, unknown>
+  }
+
+  return ok({
+    sub: claims.sub,
+    subject_type: claim.type,
+    properties: claim.properties,
+    scope: claims.scope,
+  })
+}

package/src/http/context.ts

@@ -0,0 +1,86 @@
+/**
+ * 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,
+  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
+  /** Builds `TenantContext.request.custom` for every request. See `IdPOptions.buildCustomContext`. */
+  buildCustomContext?: (
+    req: Request,
+  ) => Record<string, unknown> | Promise<Record<string, unknown>>
+  clock: () => number
+  cookieDefaults: CookieDefaults
+}
+
+/** 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,
+  })
+}