@_mustachio/openauth 0.9.2 → 0.11.0

package/src/domain/jwt.ts

@@ -0,0 +1,185 @@
+/**
+ * JWT signing + verification for access tokens, plus the JWKS document
+ * builder consumed by `/.well-known/jwks.json`.
+ *
+ * Per AD9 / AD11, access tokens are JWTs (ES256 default; Ed25519 supported).
+ * Refresh tokens are opaque server-side records — they do NOT pass through
+ * this module.
+ */
+import type { JWK, KeyLike } from "jose"
+import { importJWK, jwtVerify, SignJWT } from "jose"
+
+import type { AccessTokenClaims, IdTokenClaims } from "../types/token"
+import type { SigningKey } from "../ports/key-store"
+
+/**
+ * Sign an access-token claim set under the supplied private key. `kid` is
+ * stamped into the JWT header so verifiers can look up the right public
+ * key from JWKS.
+ */
+export async function signAccessToken(
+  claims: AccessTokenClaims,
+  privateKey: KeyLike,
+  alg: string,
+  kid: string,
+): Promise<string> {
+  return new SignJWT(claims as unknown as Record<string, unknown>)
+    .setProtectedHeader({ alg, typ: "JWT", kid })
+    .sign(privateKey)
+}
+
+/**
+ * Sign an OIDC `id_token` claim set (OIDC Core §2). Header `typ` is
+ * `"JWT"` per common practice; OIDC Core does not mandate `"id_token"`.
+ * The claims object is verified by the caller to include `iss`, `sub`,
+ * `aud`, `exp`, `iat` (REQUIRED per §2).
+ */
+export async function signIdToken(
+  claims: IdTokenClaims,
+  privateKey: KeyLike,
+  alg: string,
+  kid: string,
+): Promise<string> {
+  return new SignJWT(claims as unknown as Record<string, unknown>)
+    .setProtectedHeader({ alg, typ: "JWT", kid })
+    .sign(privateKey)
+}
+
+/**
+ * Verify an OIDC `id_token` against the IdP's published signing keys.
+ * Used at `/end_session` to validate `id_token_hint` and by adjacent
+ * domain code that needs to introspect a previously-issued id_token.
+ *
+ * Same algorithm-confusion defenses as `verifyAccessToken`: only the
+ * asymmetric allow-list (`ES256`, `EdDSA`) accepted; `alg: "none"`
+ * rejected explicitly.
+ *
+ * `acceptExpired` relaxes the `exp` check — required at `/end_session`
+ * per OIDC RP-Initiated Logout 1.0 §2, where logout often follows token
+ * expiry and the spec permits accepting an expired hint. The signature
+ * + issuer + audience checks remain strict.
+ */
+export async function verifyIdToken(
+  token: string,
+  keys: ReadonlyArray<SigningKey>,
+  options: {
+    issuer?: string
+    audience?: string
+    acceptExpired?: boolean
+  } = {},
+): Promise<IdTokenClaims> {
+  const algorithms = Array.from(
+    new Set(keys.map((k) => k.alg).filter((a) => ASYMMETRIC_ALGS.has(a))),
+  )
+  const { payload } = await jwtVerify<IdTokenClaims>(
+    token,
+    async (header) => {
+      if (!header.alg || header.alg === "none") {
+        throw new Error(`verifyIdToken: refusing alg "${header.alg ?? ""}"`)
+      }
+      const match = keys.find((k) => k.kid === header.kid)
+      if (!match) {
+        throw new Error(`verifyIdToken: unknown kid "${header.kid}"`)
+      }
+      if (match.alg !== header.alg) {
+        throw new Error(
+          `verifyIdToken: header.alg "${header.alg}" does not match key alg "${match.alg}"`,
+        )
+      }
+      const imported = await importJWK(
+        match.publicJwk as unknown as JWK,
+        match.alg,
+      )
+      return imported as KeyLike
+    },
+    {
+      algorithms,
+      ...(options.issuer ? { issuer: options.issuer } : {}),
+      ...(options.audience ? { audience: options.audience } : {}),
+      // jose checks `exp` against `currentDate + clockTolerance`. A huge
+      // tolerance effectively disables the expiry check while preserving
+      // signature + issuer + audience validation.
+      ...(options.acceptExpired
+        ? { clockTolerance: Number.MAX_SAFE_INTEGER }
+        : {}),
+    },
+  )
+  return payload
+}
+
+/** Allow-list of asymmetric `alg` values the IdP issues + accepts. */
+const ASYMMETRIC_ALGS: ReadonlySet<string> = new Set(["ES256", "EdDSA"])
+
+/**
+ * Verify a JWT access token using a list of trusted signing keys (from
+ * `KeyStore.signingKeys()`). Looks up by `kid` in the JWT header.
+ *
+ * Algorithm enforcement: the allow-list is derived from the loaded
+ * `SigningKey.alg` values, intersected with the asymmetric allow-list
+ * (`ES256`, `EdDSA`). Symmetric (`HS*`) and `none` are filtered out, so a
+ * symmetric key accidentally landing in the store does not open an
+ * alg-confusion path. The kid resolver also rejects `alg: "none"`
+ * explicitly as defense in depth — `jose` already refuses tokens whose
+ * header `alg` is outside `algorithms`, but a future call site that
+ * dropped the option would still be safe.
+ *
+ * Returns the typed claims on success. Throws (via `jose`) on any
+ * signature, expiry, or alg-mismatch failure — callers wrap in `try` and
+ * convert to `Result`.
+ */
+export async function verifyAccessToken(
+  token: string,
+  keys: ReadonlyArray<SigningKey>,
+  options: { issuer?: string; audience?: string } = {},
+): Promise<AccessTokenClaims> {
+  const algorithms = Array.from(
+    new Set(keys.map((k) => k.alg).filter((a) => ASYMMETRIC_ALGS.has(a))),
+  )
+  const { payload } = await jwtVerify<AccessTokenClaims>(
+    token,
+    async (header) => {
+      if (!header.alg || header.alg === "none") {
+        throw new Error(`verifyAccessToken: refusing alg "${header.alg ?? ""}"`)
+      }
+      const match = keys.find((k) => k.kid === header.kid)
+      if (!match) {
+        throw new Error(`verifyAccessToken: unknown kid "${header.kid}"`)
+      }
+      if (match.alg !== header.alg) {
+        throw new Error(
+          `verifyAccessToken: header.alg "${header.alg}" does not match key alg "${match.alg}"`,
+        )
+      }
+      const imported = await importJWK(
+        match.publicJwk as unknown as JWK,
+        match.alg,
+      )
+      return imported as KeyLike
+    },
+    {
+      algorithms,
+      ...(options.issuer ? { issuer: options.issuer } : {}),
+      ...(options.audience ? { audience: options.audience } : {}),
+    },
+  )
+  return payload
+}
+
+/**
+ * Build the JWKS document for `/.well-known/jwks.json`. Includes active +
+ * recently-rotated keys (the overlap window) so consumers caching JWKS
+ * continue to verify tokens signed under a just-retired key until they
+ * refresh.
+ */
+export function buildJwksDocument(keys: ReadonlyArray<SigningKey>): {
+  keys: JWK[]
+} {
+  return {
+    keys: keys.map((k) => ({
+      ...k.publicJwk,
+      kid: k.kid,
+      alg: k.alg,
+      use: "sig",
+    })) as JWK[],
+  }
+}

package/src/domain/logout.ts

@@ -0,0 +1,180 @@
+/**
+ * `/end_session` endpoint logic — OIDC RP-Initiated Logout 1.0.
+ *
+ * The OP validates the optional `id_token_hint`, validates the optional
+ * `post_logout_redirect_uri` against the client's registered list,
+ * revokes the subject's refresh tokens (when a subject is identified),
+ * and either redirects the user-agent back to the RP with `state` echoed
+ * or returns a generic "logged out" acknowledgement.
+ *
+ * Per §2:
+ *  - `id_token_hint` (RECOMMENDED): a previously-issued id_token. The
+ *    OP MUST verify the signature; expiry MAY be tolerated because
+ *    logout commonly follows token expiry. We accept expired hints but
+ *    enforce signature + issuer.
+ *  - `client_id` (OPTIONAL): when both this and `id_token_hint` are
+ *    present, the OP MUST verify the client_id matches the hint's `aud`.
+ *  - `post_logout_redirect_uri` (OPTIONAL): MUST be exact-match against
+ *    the resolved client's `postLogoutRedirectUris`. If the URI is not
+ *    registered, the OP MUST NOT redirect — surface a non-redirecting
+ *    error instead, otherwise the endpoint becomes an open redirector.
+ *  - `state` (OPTIONAL): echoed back in the redirect.
+ *
+ * Front-channel / back-channel logout (RP notification of OP-initiated
+ * logout) is out of scope for this minimal endpoint. Hosts that need it
+ * can layer their own notification fan-out on top of `session_logout`
+ * audit events.
+ */
+import type { AuditLog } from "../ports/audit-log"
+import type { ConfigStore } from "../ports/config-store"
+import type { KeyStore } from "../ports/key-store"
+import type { TokenStore } from "../ports/token-store"
+import { authError, type AuthError } from "../types/error"
+import type { Result } from "../types/result"
+import { err, isErr, ok } from "../types/result"
+import type { ClientConfig, TenantContext } from "../types/tenant"
+
+import { safeAudit } from "./audit"
+import { verifyIdToken } from "./jwt"
+import { revokeAllForSubject } from "./revoke"
+
+export type EndSessionRequest = {
+  idTokenHint?: string
+  clientId?: string
+  postLogoutRedirectUri?: string
+  state?: string
+}
+
+export type EndSessionDeps = {
+  configStore: ConfigStore
+  tokenStore: TokenStore
+  keyStore: KeyStore
+  auditLog?: AuditLog
+  issuerUrl: string
+  clock: () => number
+}
+
+export type EndSessionOutput =
+  /** Redirect the user-agent back to the RP. */
+  | { kind: "redirect"; url: string }
+  /**
+   * No `post_logout_redirect_uri` was supplied (or it wasn't registered).
+   * Caller should render a minimal "logged out" page or return 200.
+   */
+  | { kind: "ok"; subjectId?: string }
+
+/**
+ * Process an `/end_session` request and return an outcome the HTTP
+ * adapter can translate into a `Response`. Pure domain — no Hono types,
+ * no `Response` construction here.
+ */
+export async function endSession(
+  req: EndSessionRequest,
+  tenant: TenantContext,
+  deps: EndSessionDeps,
+): Promise<Result<EndSessionOutput, AuthError>> {
+  // 1. Verify the id_token_hint (if present). Tolerate expiry per §2.
+  let hintSubject: string | undefined
+  let hintAud: string | undefined
+  if (req.idTokenHint) {
+    const keysRes = await deps.keyStore.signingKeys()
+    if (isErr(keysRes)) return err(keysRes.error)
+    try {
+      const claims = await verifyIdToken(req.idTokenHint, keysRes.value, {
+        issuer: deps.issuerUrl,
+        acceptExpired: true,
+      })
+      hintSubject = claims.sub
+      hintAud = claims.aud
+    } catch (e) {
+      const reason = e instanceof Error ? e.message : String(e)
+      return err(
+        authError.invalidRequest(
+          `id_token_hint failed signature/issuer verification: ${reason}`,
+          "id_token_hint",
+        ),
+      )
+    }
+  }
+
+  // 2. If both client_id and id_token_hint are present, they MUST agree
+  //    (§2). Disagreement is `invalid_request` — never a redirect.
+  if (req.clientId && hintAud && req.clientId !== hintAud) {
+    return err(
+      authError.invalidRequest(
+        "client_id does not match id_token_hint.aud",
+        "client_id",
+      ),
+    )
+  }
+
+  // 3. Resolve the client for redirect-URI validation. Prefer explicit
+  //    client_id, fall back to the hint's aud.
+  const resolvedClientId = req.clientId ?? hintAud
+  let client: ClientConfig | undefined
+  if (resolvedClientId) {
+    client = tenant.config.clients.find((c) => c.id === resolvedClientId)
+    if (!client) {
+      return err(
+        authError.invalidRequest(
+          `unknown client "${resolvedClientId}"`,
+          "client_id",
+        ),
+      )
+    }
+  }
+
+  // 4. Validate post_logout_redirect_uri. MUST be exact-match against
+  //    the client's registered list (§2). No client → no validatable URI.
+  if (req.postLogoutRedirectUri) {
+    if (!client) {
+      return err(
+        authError.invalidRequest(
+          "post_logout_redirect_uri requires identifying the client via client_id or id_token_hint",
+          "post_logout_redirect_uri",
+        ),
+      )
+    }
+    const registered = client.postLogoutRedirectUris ?? []
+    if (!registered.includes(req.postLogoutRedirectUri)) {
+      return err(
+        authError.invalidRequest(
+          "post_logout_redirect_uri is not registered for this client",
+          "post_logout_redirect_uri",
+        ),
+      )
+    }
+  }
+
+  // 5. Revoke the subject's tokens. Only possible when an id_token_hint
+  //    identified a subject. Without a hint, /end_session is essentially
+  //    a session-cookie clear (which the framework doesn't yet own); we
+  //    still return a successful redirect/ok so RPs can complete UX.
+  if (hintSubject) {
+    const revoked = await revokeAllForSubject(tenant.id, hintSubject, {
+      tokenStore: deps.tokenStore,
+      ...(deps.auditLog ? { auditLog: deps.auditLog } : {}),
+      clock: deps.clock,
+    })
+    if (isErr(revoked)) return err(revoked.error)
+  }
+
+  await safeAudit(deps, {
+    kind: "session_logout",
+    tenantId: tenant.id,
+    ...(resolvedClientId ? { clientId: resolvedClientId } : {}),
+    ...(hintSubject ? { subjectId: hintSubject } : {}),
+    timestamp: deps.clock(),
+  })
+
+  // 6. Build the redirect or signal "ok" for the caller to render.
+  if (req.postLogoutRedirectUri) {
+    const url = new URL(req.postLogoutRedirectUri)
+    if (req.state !== undefined) url.searchParams.set("state", req.state)
+    return ok({ kind: "redirect", url: url.toString() })
+  }
+  return ok({
+    kind: "ok",
+    ...(hintSubject ? { subjectId: hintSubject } : {}),
+  })
+}

package/src/domain/method-cache.ts

@@ -0,0 +1,220 @@
+/**
+ * `MethodCache` — loads `AuthMethodFactory` builds per
+ * `(tenantId, MethodConfig.id)` and caches the result.
+ *
+ * Responsibilities per plan §"Per-tenant config → typed method config":
+ *  1. Look up the factory by `MethodConfig.kind`. Unknown kind → audit
+ *     `unknown_method_kind`, treat instance as disabled.
+ *  2. Validate `MethodConfig.config` against `factory.configSchema`.
+ *     Failure → audit `invalid_method_config`, treat instance as disabled.
+ *  3. Call `factory.build({ id, kind, tenantId, config })`. Verify the
+ *     returned `AuthMethod` has `id` / `kind` matching the inputs. Mismatch
+ *     → audit `factory_id_mismatch`, fail the load.
+ *  4. Cache per `(tenantId, MethodConfig.id)`. The cache is in-process —
+ *     TTL is governed by the `ConfigStore` invalidation hook in Phase 3+;
+ *     in Phase 2 / tests, manual `invalidate(tenantId)` is sufficient.
+ */
+import type { AuditLog } from "../ports/audit-log"
+import { authError, type AuthError } from "../types/error"
+import type { AnyAuthMethodFactory, AuthMethod } from "../types/method"
+import type { Result } from "../types/result"
+import { err, ok } from "../types/result"
+import type { MethodConfig, TenantConfig, TenantId } from "../types/tenant"
+
+export type MethodCacheOptions = {
+  factories: Record<string, AnyAuthMethodFactory>
+  auditLog?: AuditLog
+  /** Injectable clock for audit timestamps. */
+  now: () => number
+}
+
+export class MethodCache {
+  #factories: Record<string, AnyAuthMethodFactory>
+  #auditLog?: AuditLog
+  #now: () => number
+  #cache = new Map<string, AuthMethod>()
+  /** Negative-cache: instances we know are disabled (config invalid / unknown kind). */
+  #disabled = new Set<string>()
+
+  constructor(opts: MethodCacheOptions) {
+    this.#factories = opts.factories
+    this.#auditLog = opts.auditLog
+    this.#now = opts.now
+  }
+
+  /**
+   * Load (or fetch from cache) the `AuthMethod` for the given tenant +
+   * tenant-local method instance id. Returns `method_not_found` for any
+   * disabled / unknown / invalid-config path.
+   */
+  async resolve(
+    tenant: TenantConfig,
+    methodId: string,
+  ): Promise<Result<AuthMethod, AuthError>> {
+    const cacheKey = this.#key(tenant.id, methodId)
+    const hit = this.#cache.get(cacheKey)
+    if (hit) return ok(hit)
+    if (this.#disabled.has(cacheKey)) {
+      return err(
+        authError.methodNotFound(
+          `method "${methodId}" is disabled or has invalid config`,
+          { methodId },
+        ),
+      )
+    }
+
+    const cfg = tenant.methods.find((m) => m.id === methodId)
+    if (!cfg) {
+      return err(
+        authError.methodNotFound(`method "${methodId}" not configured`, {
+          methodId,
+        }),
+      )
+    }
+    if (!cfg.enabled) {
+      return err(
+        authError.methodNotFound(`method "${methodId}" is disabled`, {
+          methodId,
+        }),
+      )
+    }
+
+    const built = await this.#build(tenant.id, cfg)
+    if (built.ok) {
+      this.#cache.set(cacheKey, built.value)
+    } else {
+      this.#disabled.add(cacheKey)
+    }
+    return built
+  }
+
+  /** Drop cached instances for a tenant. Called on config invalidation. */
+  invalidate(tenantId: TenantId, methodId?: string): void {
+    if (methodId !== undefined) {
+      const key = this.#key(tenantId, methodId)
+      this.#cache.delete(key)
+      this.#disabled.delete(key)
+      return
+    }
+    for (const k of [...this.#cache.keys()]) {
+      if (k.startsWith(`${tenantId}\0`)) this.#cache.delete(k)
+    }
+    for (const k of [...this.#disabled]) {
+      if (k.startsWith(`${tenantId}\0`)) this.#disabled.delete(k)
+    }
+  }
+
+  /** List all enabled methods for a tenant — used by method-selection UI. */
+  async listAvailable(tenant: TenantConfig): Promise<AuthMethod[]> {
+    const results: AuthMethod[] = []
+    for (const cfg of tenant.methods) {
+      if (!cfg.enabled) continue
+      const m = await this.resolve(tenant, cfg.id)
+      if (m.ok) results.push(m.value)
+    }
+    return results
+  }
+
+  async #build(
+    tenantId: TenantId,
+    cfg: MethodConfig,
+  ): Promise<Result<AuthMethod, AuthError>> {
+    const factory = this.#factories[cfg.kind]
+    if (!factory) {
+      await this.#audit({
+        kind: "unknown_method_kind",
+        tenantId,
+        methodId: cfg.id,
+        methodKind: cfg.kind,
+        timestamp: this.#now(),
+      })
+      return err(
+        authError.methodNotFound(
+          `no factory registered for kind "${cfg.kind}"`,
+          {
+            methodId: cfg.id,
+            methodKind: cfg.kind,
+          },
+        ),
+      )
+    }
+
+    // Standard Schema v1: `validate` may return a Result or a Promise<Result>.
+    // Successful Result has `{ value }`; failure has `{ issues }`.
+    let parsed = factory.configSchema["~standard"].validate(cfg.config)
+    if (parsed instanceof Promise) parsed = await parsed
+    if ("issues" in parsed && parsed.issues) {
+      await this.#audit({
+        kind: "invalid_method_config",
+        tenantId,
+        methodId: cfg.id,
+        methodKind: cfg.kind,
+        errorPath: parsed.issues
+          .map((issue) =>
+            (issue.path ?? [])
+              .map((segment) =>
+                typeof segment === "object"
+                  ? String(segment.key)
+                  : String(segment),
+              )
+              .join("."),
+          )
+          .join(","),
+        timestamp: this.#now(),
+      })
+      return err(
+        authError.methodNotFound(
+          `invalid method config for "${cfg.id}" (kind "${cfg.kind}")`,
+          { methodId: cfg.id, methodKind: cfg.kind },
+        ),
+      )
+    }
+
+    let method: AuthMethod
+    try {
+      method = await factory.build({
+        id: cfg.id,
+        kind: cfg.kind,
+        tenantId,
+        config: parsed.value,
+      })
+    } catch (e) {
+      return err(
+        authError.internalError(
+          `factory "${cfg.kind}" build threw for instance "${cfg.id}"`,
+          e,
+        ),
+      )
+    }
+
+    if (method.id !== cfg.id || method.kind !== cfg.kind) {
+      await this.#audit({
+        kind: "factory_id_mismatch",
+        tenantId,
+        methodId: cfg.id,
+        expectedKind: cfg.kind,
+        actualKind: method.kind,
+        timestamp: this.#now(),
+      })
+      return err(
+        authError.internalError(
+          `factory "${cfg.kind}" returned AuthMethod with id/kind ${method.id}/${method.kind}; expected ${cfg.id}/${cfg.kind}`,
+        ),
+      )
+    }
+    return ok(method)
+  }
+
+  #key(tenantId: TenantId, methodId: string): string {
+    return `${tenantId}\0${methodId}`
+  }
+
+  async #audit(event: Parameters<AuditLog["log"]>[0]): Promise<void> {
+    if (!this.#auditLog) return
+    try {
+      await this.#auditLog.log(event)
+    } catch {
+      // Audit failure must not break the hot path.
+    }
+  }
+}

package/src/domain/method-dispatch.ts

@@ -0,0 +1,95 @@
+/**
+ * Method dispatch — invoke a method's route handler, then enforce the
+ * `saveMethodState` durability contract.
+ *
+ * Per `ARCHITECTURE.md`: when a method handler returns
+ * `{ kind: "challenge", saveMethodState }`, the framework MUST persist
+ * `methodState` via `SessionStore.updateFlowMethodState` **before**
+ * surfacing the response. Centralizing that here keeps the
+ * happens-before contract uniform across every call site.
+ */
+import type { SessionStore } from "../ports/session-store"
+import { authError, type AuthError } from "../types/error"
+import type { FlowRecord } from "../types/flow"
+import type {
+  AuthMethod,
+  MethodContext,
+  MethodDispatchData,
+  MethodResult,
+} from "../types/method"
+import type { Result } from "../types/result"
+import { err, isErr, ok } from "../types/result"
+import type { TenantContext } from "../types/tenant"
+
+export type RouteKey = `${"GET" | "POST"} ${string}`
+
+export type DispatchInput = {
+  method: AuthMethod
+  route: RouteKey
+  tenant: TenantContext
+  request: Request
+  subPath: string
+  flow: FlowRecord | null
+  cookies: ReadonlyMap<string, string>
+  sessionStore: SessionStore
+  /** Populated at `GET /authorize`; null on callbacks. */
+  dispatch: MethodDispatchData | null
+}
+
+/**
+ * Invoke the named route on the method. If the result is a challenge with
+ * `saveMethodState`, persist it to `SessionStore` and only then return.
+ * The framework owns this happens-before guarantee so methods cannot
+ * accidentally surface a redirect before the upstream verifier is durable.
+ */
+export async function dispatchMethod(
+  input: DispatchInput,
+): Promise<Result<MethodResult<unknown, unknown>, AuthError>> {
+  const handler = input.method.routes[input.route]
+  if (!handler) {
+    return err(
+      authError.invalidRequest(
+        `method "${input.method.id}" has no handler for route "${input.route}"`,
+      ),
+    )
+  }
+
+  const ctx: MethodContext<unknown> = {
+    request: input.request,
+    subPath: input.subPath,
+    tenant: input.tenant,
+    flow: input.flow,
+    methodState: input.flow?.methodState ?? null,
+    cookies: input.cookies,
+    dispatch: input.dispatch,
+  }
+
+  let result: MethodResult<unknown, unknown>
+  try {
+    result = await handler(ctx)
+  } catch (e) {
+    return err(
+      authError.serverError(
+        `method "${input.method.id}" handler threw on route "${input.route}"`,
+        e,
+      ),
+    )
+  }
+
+  if (result.kind === "challenge" && result.saveMethodState !== undefined) {
+    if (!input.flow) {
+      return err(
+        authError.internalError(
+          `method "${input.method.id}" returned saveMethodState without an active flow`,
+        ),
+      )
+    }
+    const persisted = await input.sessionStore.updateFlowMethodState(
+      input.flow.flowId,
+      result.saveMethodState,
+    )
+    if (isErr(persisted)) return err(persisted.error)
+  }
+
+  return ok(result)
+}