@_mustachio/openauth 0.9.1 → 0.10.0

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

package/src/domain/method-route.ts

@@ -0,0 +1,208 @@
+/**
+ * `handleMethodRoute` — the third pipeline.
+ *
+ * `/authorize` and `/cb/:methodId` are the two pipelines that produce a
+ * flow record and consume it respectively. Credential-style methods
+ * (password, code, passkey) additionally need a way to make in-flight
+ * POSTs against the IdP — submitting a login form, asking for a one-time
+ * code, completing a WebAuthn ceremony. The HTTP layer mounts these at
+ * `/m/<methodId>/<subPath>` and delegates here.
+ *
+ * Responsibilities:
+ *   1. Read `flowId` from the framework-set HttpOnly `idp.flow` cookie.
+ *      No cookie → `invalid_request` (the user lost their flow).
+ *   2. `SessionStore.readFlow(flowId)` — peek, do not consume. Methods may
+ *      need multiple round trips before completing (e.g. send-code →
+ *      verify-code).
+ *   3. Tenant must match the cookie's flow. If the request's tenant
+ *      (resolved via `resolveTenant`) disagrees with the flow's tenant,
+ *      audit `flow_tenant_mismatch` and reject. This is the same invariant
+ *      the upstream-callback path enforces.
+ *   4. Dispatch the method's `<METHOD> <subPath>` route.
+ *   5. Translate `MethodResult`:
+ *      - `challenge` → return response (methodState merged before send).
+ *      - `success`   → `consumeFlow`, snapshot into auth code, return
+ *                      `issue-code` for the HTTP layer to redirect.
+ *      - `denied`    → return reason; HTTP layer renders.
+ *      - `error`     → propagated.
+ */
+import type { AuditLog } from "../ports/audit-log"
+import type { KeyStore } from "../ports/key-store"
+import type { SessionStore } from "../ports/session-store"
+import type { TokenStore } from "../ports/token-store"
+import { authError, type AuthError } from "../types/error"
+import type { FlowRecord } from "../types/flow"
+import type { MethodResult, CachePolicy, SetCookie } from "../types/method"
+import type { Result } from "../types/result"
+import { err, isErr, ok } from "../types/result"
+import type { TenantContext } from "../types/tenant"
+
+import { safeAudit } from "./audit"
+import { AUTH_CODE_TTL_MS } from "./authorize"
+import { randomToken } from "./crypto"
+import { MethodCache } from "./method-cache"
+import { dispatchMethod, type RouteKey } from "./method-dispatch"
+import { saveEncryptedCode } from "./token"
+
+export type MethodRouteOutput =
+  | {
+      kind: "issue-code"
+      code: string
+      appRedirectUri: string
+      appState: string | null
+    }
+  | {
+      kind: "challenge"
+      response: Response
+      setCookies: SetCookie[]
+      cache?: CachePolicy
+    }
+  | { kind: "denied"; reason: string; setCookies: SetCookie[] }
+
+export type HandleMethodRouteInput = {
+  rawRequest: Request
+  tenant: TenantContext
+  /** Tenant-local instance id (`MethodConfig.id`) parsed from the URL. */
+  methodId: string
+  /** Path within the method's mount, e.g. `"/login"`. */
+  subPath: string
+  /** HTTP method of the incoming request: `"GET"` or `"POST"`. */
+  httpMethod: "GET" | "POST"
+  /** flowId from the `idp.flow` cookie. */
+  flowId: string
+  cookies: ReadonlyMap<string, string>
+}
+
+export type HandleMethodRouteDeps = {
+  sessionStore: SessionStore
+  tokenStore: TokenStore
+  /** Needed for at-rest encryption of the code payload — see `domain/token.ts`. */
+  keyStore: KeyStore
+  auditLog?: AuditLog
+  methodCache: MethodCache
+  clock: () => number
+  newCodeId?: () => string
+}
+
+export async function handleMethodRoute(
+  input: HandleMethodRouteInput,
+  deps: HandleMethodRouteDeps,
+): Promise<Result<MethodRouteOutput, AuthError>> {
+  // 1. Peek at the flow record.
+  const flowRes = await deps.sessionStore.readFlow(input.flowId)
+  if (isErr(flowRes)) return err(flowRes.error)
+  const flow = flowRes.value
+
+  // 2. Tenant must match.
+  if (flow.tenantId !== input.tenant.id) {
+    await safeAudit(deps, {
+      kind: "flow_tenant_mismatch",
+      stateTenantId: input.tenant.id,
+      flowTenantId: flow.tenantId,
+      flowId: flow.flowId,
+      timestamp: deps.clock(),
+    })
+    return err(authError.invalidRequest("tenant mismatch", "flow"))
+  }
+
+  // 3. Resolve the method.
+  if (flow.methodId !== input.methodId) {
+    return err(
+      authError.invalidRequest(
+        `method "${input.methodId}" does not own flow "${flow.flowId}" (expected "${flow.methodId}")`,
+        "methodId",
+      ),
+    )
+  }
+  const methodRes = await deps.methodCache.resolve(
+    input.tenant.config,
+    input.methodId,
+  )
+  if (isErr(methodRes)) return err(methodRes.error)
+
+  // 4. Dispatch.
+  const route: RouteKey = `${input.httpMethod} ${input.subPath}`
+  const dispatched = await dispatchMethod({
+    method: methodRes.value,
+    route,
+    tenant: input.tenant,
+    request: input.rawRequest,
+    subPath: input.subPath,
+    flow,
+    cookies: input.cookies,
+    sessionStore: deps.sessionStore,
+    dispatch: null,
+  })
+  if (isErr(dispatched)) return err(dispatched.error)
+  return translate(dispatched.value, flow, deps)
+}
+
+async function translate(
+  result: MethodResult<unknown, unknown>,
+  flow: FlowRecord,
+  deps: HandleMethodRouteDeps,
+): Promise<Result<MethodRouteOutput, AuthError>> {
+  switch (result.kind) {
+    case "success": {
+      const consumed = await deps.sessionStore.consumeFlow(flow.flowId)
+      if (isErr(consumed)) return err(consumed.error)
+      // Use the consumed record (the one we already had via readFlow may be
+      // slightly stale relative to the most recent updateFlowMethodState).
+      const final = consumed.value
+      const code = (deps.newCodeId ?? randomToken)()
+      const now = deps.clock()
+      const saved = await saveEncryptedCode(
+        code,
+        {
+          tenantId: final.tenantId,
+          clientId: final.clientId,
+          appRedirectUri: final.appRedirectUri,
+          appState: final.appState,
+          scopes: final.scopes,
+          audience: final.audience,
+          clientPkce: final.clientPkce,
+          methodId: final.methodId,
+          methodKind: final.methodKind,
+          context: final.context ?? null,
+          providerSubject: result.providerSubject,
+          properties: result.properties,
+          expiresAt: now + AUTH_CODE_TTL_MS,
+        },
+        AUTH_CODE_TTL_MS,
+        { keyStore: deps.keyStore, tokenStore: deps.tokenStore },
+      )
+      if (isErr(saved)) return err(saved.error)
+      return ok({
+        kind: "issue-code",
+        code,
+        appRedirectUri: final.appRedirectUri,
+        appState: final.appState,
+      })
+    }
+    case "challenge":
+      return ok({
+        kind: "challenge",
+        response: result.response,
+        setCookies: result.setCookies ?? [],
+        ...(result.cache !== undefined ? { cache: result.cache } : {}),
+      })
+    case "denied":
+      await safeAudit(deps, {
+        kind: "authorize_failed",
+        tenantId: flow.tenantId,
+        clientId: flow.clientId,
+        methodId: flow.methodId,
+        methodKind: flow.methodKind,
+        flowId: flow.flowId,
+        reason: result.reason,
+        timestamp: deps.clock(),
+      })
+      return ok({
+        kind: "denied",
+        reason: result.reason,
+        setCookies: result.setCookies ?? [],
+      })
+    case "error":
+      return err(result.error)
+  }
+}

package/src/domain/pkce.ts

@@ -0,0 +1,37 @@
+/**
+ * PKCE validation. OAuth 2.1 mandates the `S256` method; `plain` is **not**
+ * supported by this IdP.
+ */
+import { base64url, sha256, timingSafeEqualStr, utf8 } from "./crypto"
+
+/**
+ * Compute the S256 challenge for a verifier. Used at `/token` to recompute
+ * the expected challenge from the supplied `code_verifier` and compare it
+ * (timing-safe) against the challenge stashed in the auth-code payload.
+ */
+export async function s256Challenge(verifier: string): Promise<string> {
+  return base64url.encode(await sha256(utf8.encode(verifier)))
+}
+
+/**
+ * Verify a `code_verifier` against a previously-stored `code_challenge`.
+ *
+ * - Returns `false` on any length / character anomaly without computing the
+ *   hash — these are public-shape checks, not secret-dependent.
+ * - Uses a constant-time compare for the recomputed challenge.
+ */
+export async function validatePkce(
+  verifier: string,
+  challenge: string,
+): Promise<boolean> {
+  if (
+    typeof verifier !== "string" ||
+    typeof challenge !== "string" ||
+    verifier.length < 43 ||
+    verifier.length > 128
+  ) {
+    return false
+  }
+  const computed = await s256Challenge(verifier)
+  return timingSafeEqualStr(computed, challenge)
+}