@_mustachio/openauth 0.9.2 → 0.11.0

package/src/domain/method-route.ts

@@ -0,0 +1,213 @@
+/**
+ * `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,
+          ...(final.appNonce !== undefined ? { appNonce: final.appNonce } : {}),
+          ...(final.claimsRequest !== undefined
+            ? { claimsRequest: final.claimsRequest }
+            : {}),
+          authTime: Math.floor(now / 1000),
+          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/par.ts

@@ -0,0 +1,141 @@
+/**
+ * Pushed Authorization Requests (RFC 9126).
+ *
+ * The RP submits the full `/authorize` parameter set to `POST /par` along
+ * with its client credentials. The OP authenticates the client, stores
+ * the payload under an opaque `request_uri`, and returns it with an
+ * `expires_in`. The RP then redirects the user-agent to
+ * `GET /authorize?client_id=...&request_uri=...` and the OP rehydrates
+ * the original parameter set.
+ *
+ * Per RFC 9126 §3:
+ *  - Response is HTTP 201 with `application/json` body
+ *    `{request_uri, expires_in}`.
+ *  - `request_uri` MUST be of the form
+ *    `urn:ietf:params:oauth:request_uri:<opaque>` (§2.2).
+ *  - Default TTL is 60 seconds — same as auth-code TTL.
+ *
+ * Per RFC 9126 §4:
+ *  - At `/authorize`, `request_uri` is one-shot — consumed and discarded
+ *    on first use.
+ *  - Parameters in the PAR record take precedence; additional `/authorize`
+ *    parameters MAY be merged but MUST NOT contradict (we strictly use
+ *    the PAR'd set and ignore any additional ones except `client_id`).
+ *
+ * Client authentication (§2):
+ *  - Public clients: `client_id` only.
+ *  - Confidential clients: `client_id` + `client_secret` (Basic or form).
+ */
+import type { AuditLog } from "../ports/audit-log"
+import type { ConfigStore } from "../ports/config-store"
+import type { SessionStore } from "../ports/session-store"
+import { authError, type AuthError } from "../types/error"
+import type { Result } from "../types/result"
+import { err, isErr, ok } from "../types/result"
+import type { TenantContext } from "../types/tenant"
+
+import { verifyClientCredentials } from "./client-auth"
+import { randomToken } from "./crypto"
+
+export const PAR_URI_PREFIX = "urn:ietf:params:oauth:request_uri:"
+export const DEFAULT_PAR_TTL_MS = 60 * 1000
+
+export type ParRequest = {
+  clientId: string
+  /** Confidential-client secret. */
+  clientSecret?: string
+  /** Raw `/authorize` parameter record, posted by the RP. */
+  params: Record<string, string>
+}
+
+export type ParResponse = {
+  request_uri: string
+  expires_in: number
+}
+
+export type ParDeps = {
+  configStore: ConfigStore
+  sessionStore: SessionStore
+  auditLog?: AuditLog
+  clock: () => number
+  /** Test override. */
+  newRequestUriSuffix?: () => string
+  ttlMs?: number
+}
+
+/**
+ * Process a `POST /par` request. Authenticates the client, validates the
+ * `client_id` consistency, and persists the parameter set.
+ */
+export async function pushAuthorizationRequest(
+  req: ParRequest,
+  tenant: TenantContext,
+  deps: ParDeps,
+): Promise<Result<ParResponse, AuthError>> {
+  if (!deps.sessionStore.savePar || !deps.sessionStore.consumePar) {
+    return err(
+      authError.invalidRequest(
+        "session adapter does not implement PAR storage",
+      ),
+    )
+  }
+
+  // 1. Client authentication. The `client_id` in the body must match the
+  //    authenticating client.
+  const client = tenant.config.clients.find((c) => c.id === req.clientId)
+  if (!client) {
+    return err(authError.invalidClient(`unknown client "${req.clientId}"`))
+  }
+  if (client.type === "confidential") {
+    const authErr = await verifyClientCredentials(client, req.clientSecret)
+    if (authErr) return err(authErr)
+  } else if (req.clientSecret !== undefined) {
+    return err(
+      authError.invalidClient("public client must not present client_secret"),
+    )
+  }
+
+  // 2. Sanity-check the body: client_id in body must match — the RFC
+  //    requires it (§2). RP shouldn't be authenticating one client and
+  //    pushing params for a different one.
+  if (req.params.client_id && req.params.client_id !== req.clientId) {
+    return err(
+      authError.invalidRequest(
+        "client_id in body conflicts with authenticated client",
+        "client_id",
+      ),
+    )
+  }
+  // RFC 9126 §2.1: `request_uri` MUST NOT appear in a PAR request body.
+  if ("request_uri" in req.params) {
+    return err(
+      authError.invalidRequest(
+        "request_uri MUST NOT be present in a PAR request",
+        "request_uri",
+      ),
+    )
+  }
+
+  // 3. Mint request_uri + persist.
+  const suffix = (deps.newRequestUriSuffix ?? randomToken)()
+  const requestUri = PAR_URI_PREFIX + suffix
+  const ttl = deps.ttlMs ?? DEFAULT_PAR_TTL_MS
+  const now = deps.clock()
+  const saved = await deps.sessionStore.savePar(
+    requestUri,
+    {
+      requestUri,
+      params: { ...req.params, client_id: req.clientId },
+      clientId: req.clientId,
+      issuedAt: now,
+      expiresAt: now + ttl,
+    },
+    ttl,
+  )
+  if (isErr(saved)) return err(saved.error)
+
+  return ok({
+    request_uri: requestUri,
+    expires_in: Math.floor(ttl / 1000),
+  })
+}

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

package/src/domain/refresh.ts

@@ -0,0 +1,210 @@
+/**
+ * `/token` endpoint logic for `grant_type=refresh_token`.
+ *
+ * Rotation semantics (plan §"Cross-cutting Decisions" + §"Port consistency
+ * contracts"):
+ *
+ *  - Refresh tokens rotate on every use. The presented token is consumed
+ *    (CAS); a fresh refresh token is issued, keyed by the same `family`.
+ *  - If the same token is presented a second time within the reuse window
+ *    (default 60 s), the family is revoked and the request is rejected
+ *    with `invalid_grant`. Audit: `refresh_reuse_detected`.
+ *  - Outside the reuse window the row should be GC'd; presentation
+ *    returns `invalid_grant` ("unknown token").
+ */
+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 } from "../types/result"
+import type { TenantContext } from "../types/tenant"
+import type { TokenResponse } from "../types/token"
+
+import { safeAudit } from "./audit"
+import { verifyClientCredentials } from "./client-auth"
+import { mintTokens } from "./token"
+
+export type RefreshGrantRequest = {
+  grantType: "refresh_token"
+  refreshToken: string
+  /** Optional per RFC 6749 — narrow scope. If absent, original scopes are reused. */
+  scope?: string
+  /** Confidential clients authenticate at /token. */
+  clientId?: string
+  clientSecret?: string
+  /**
+   * RFC 9449 §6 — JWK thumbprint of the DPoP proof presented on this
+   * refresh request. MUST match `RefreshTokenPayload.dpopJkt` when the
+   * original grant was DPoP-bound; presence is REQUIRED for bound
+   * tokens, OPTIONAL otherwise.
+   */
+  dpopJkt?: string
+}
+
+export type RefreshTokensDeps = {
+  configStore: ConfigStore
+  tokenStore: TokenStore
+  keyStore: KeyStore
+  auditLog?: AuditLog
+  issuerUrl: string
+  clock: () => number
+  /** Reuse-detection window (ms). Default 60 s. */
+  reuseWindowMs?: number
+  newRefreshToken?: () => string
+  /** See `IdPOptions.customScopeClaims`. Forwarded to `mintTokens`. */
+  customScopeClaims?: Record<string, ReadonlyArray<string>>
+}
+
+export async function refreshTokens(
+  req: RefreshGrantRequest,
+  deps: RefreshTokensDeps,
+): Promise<Result<TokenResponse, AuthError>> {
+  // Peek before consuming so we can authenticate the client without
+  // burning the token on auth failures (RFC 6749 §6).
+  const peek = await deps.tokenStore.peekRefresh(req.refreshToken)
+  if (isErr(peek)) return err(peek.error)
+  const peekedPayload = peek.value
+
+  const tenantCfg = await deps.configStore.getTenantConfig(
+    peekedPayload.tenantId,
+  )
+  if (isErr(tenantCfg)) return err(tenantCfg.error)
+
+  // Authenticate the *presenting* client first, then check ownership.
+  // Wrong-secret, wrong-client, and unknown-presenting-client all collapse
+  // to the same `invalid_grant` response so an attacker holding a stolen
+  // refresh token cannot probe candidate `client_id` values: every
+  // misroute looks identical on the wire (RFC 6749 §5.2; H4 of the
+  // post-rebuild review).
+  const INVALID_REFRESH_DESC = "refresh token is invalid"
+  const client = tenantCfg.value.clients.find(
+    (c) => c.id === peekedPayload.clientId,
+  )
+  if (!client) {
+    return err(authError.invalidGrant(INVALID_REFRESH_DESC))
+  }
+
+  if (req.clientId !== undefined) {
+    const presenting = tenantCfg.value.clients.find(
+      (c) => c.id === req.clientId,
+    )
+    if (!presenting) {
+      return err(authError.invalidGrant(INVALID_REFRESH_DESC))
+    }
+    const authErr = await verifyClientCredentials(presenting, req.clientSecret)
+    if (authErr) return err(authError.invalidGrant(INVALID_REFRESH_DESC))
+    if (req.clientId !== peekedPayload.clientId) {
+      return err(authError.invalidGrant(INVALID_REFRESH_DESC))
+    }
+  } else if (client.type === "confidential") {
+    return err(authError.invalidGrant(INVALID_REFRESH_DESC))
+  }
+
+  // RFC 9449 §5 — when the refresh token is DPoP-bound, verify the
+  // presented DPoP thumbprint matches BEFORE consuming. Consuming first
+  // would burn the token on a wrong-key probe AND trip reuse-detection
+  // on a subsequent legitimate retry with the right key.
+  if (peekedPayload.dpopJkt !== undefined) {
+    if (req.dpopJkt === undefined) {
+      return err(
+        authError.invalidDpopProof(
+          "refresh token is DPoP-bound; request is missing a DPoP proof",
+        ),
+      )
+    }
+    if (req.dpopJkt !== peekedPayload.dpopJkt) {
+      return err(
+        authError.invalidDpopProof(
+          "refresh token DPoP jkt does not match the original binding",
+        ),
+      )
+    }
+  }
+
+  const consumed = await deps.tokenStore.consumeRefresh(req.refreshToken, {
+    reuseWindowMs: deps.reuseWindowMs,
+  })
+  if (isErr(consumed)) {
+    if (consumed.error.code === "invalid_grant" && consumed.error.reuseSignal) {
+      // Reuse-detection signal arrives typed on the AuthError. tenantId /
+      // subjectId come from the signal when the adapter emits it; we fall
+      // back to the peeked payload's fields for adapters that don't
+      // (older 4th-party adapters that satisfy the port without the
+      // structured carrier). `family` always prefers the signal — it's
+      // the discriminating identifier the adapter knows.
+      const signal = consumed.error.reuseSignal
+      await safeAudit(deps, {
+        kind: "refresh_reuse_detected",
+        tenantId: peekedPayload.tenantId,
+        clientId: peekedPayload.clientId,
+        family: signal.family,
+        timestamp: deps.clock(),
+      })
+    }
+    return err(consumed.error)
+  }
+  const payload = consumed.value
+
+  // Narrow scope if requested (must be subset of original).
+  const requestedScopes = req.scope
+    ? req.scope.split(" ").filter(Boolean)
+    : payload.scopes
+  for (const s of requestedScopes) {
+    if (!payload.scopes.includes(s)) {
+      return err(
+        authError.invalidScope(
+          `requested scope "${s}" not granted by original refresh token`,
+        ),
+      )
+    }
+  }
+
+  const tenant: TenantContext = {
+    id: payload.tenantId,
+    config: tenantCfg.value,
+    request: { raw: new Request("about:blank"), custom: {} },
+  }
+
+  return mintTokens({
+    tenant,
+    claim: payload.claim,
+    payload: {
+      tenantId: payload.tenantId,
+      clientId: payload.clientId,
+      // Carry original method provenance forward — descendant tokens
+      // surface the method that started the chain via `mid` / `mkind`,
+      // not the grant-type literal "refresh".
+      methodId: payload.methodId,
+      methodKind: payload.methodKind,
+      scopes: requestedScopes,
+      audience: payload.audience,
+      // `auth_time` is stable across refresh rotations per OIDC Core §12;
+      // refresh does not re-authenticate the user. `nonce` is deliberately
+      // NOT carried forward — the nonce was bound to the original
+      // `/authorize` request and should not reappear on rotated id_tokens.
+      authTime: payload.authTime,
+      // Preserve DPoP binding across refresh rotation (§6.1).
+      ...(payload.dpopJkt !== undefined ? { dpopJkt: payload.dpopJkt } : {}),
+      // Preserve OIDC §5.5 claims-parameter intent across refresh (§12).
+      ...(payload.claimsRequest !== undefined
+        ? { claimsRequest: payload.claimsRequest }
+        : {}),
+    },
+    family: payload.family,
+    deps,
+  }).then(async (result) => {
+    if (result.ok) {
+      await safeAudit(deps, {
+        kind: "token_refreshed",
+        tenantId: payload.tenantId,
+        clientId: payload.clientId,
+        subjectId: payload.subjectId,
+        family: payload.family,
+        timestamp: deps.clock(),
+      })
+    }
+    return result
+  })
+}