@_mustachio/openauth 0.9.1 → 0.10.0

package/src/domain/callback.ts

@@ -0,0 +1,263 @@
+/**
+ * `handleCallback` — process the upstream provider's redirect back to the
+ * IdP. The framework:
+ *
+ *   1. Recovers `(tenantId, flowId)` from the MAC-bound `state` envelope.
+ *   2. Atomically `consumeFlow(flowId)` — single delete-on-read, returns
+ *      the full `FlowRecord`.
+ *   3. Runs the **state-flow consistency check** (tenant, nonce, host,
+ *      path). Any mismatch → `invalid_request` + corresponding audit.
+ *   4. Loads tenant config + resolves the method via `MethodCache`.
+ *   5. Dispatches the method's `GET /callback` handler.
+ *   6. On `success`, snapshots the in-memory `FlowRecord` into the
+ *      auth-code payload via `TokenStore.saveCode` and returns
+ *      `issue-code`. `methodState` is NOT snapshotted.
+ *
+ * Phase 2 implements the `mac-state` recovery only. Recovery mechanisms
+ * #2 (partitioned-host) and #3 (`flowId`-in-URI) are wired in Phase 3
+ * alongside the HTTP layer that knows the request's host / path /
+ * registered redirect URIs.
+ */
+import type { ConfigStore } from "../ports/config-store"
+import type { KeyStore } from "../ports/key-store"
+import type { SessionStore } from "../ports/session-store"
+import type { TokenStore } from "../ports/token-store"
+import type { AuditLog } from "../ports/audit-log"
+import type { AuthError } from "../types/error"
+import { authError } from "../types/error"
+import type { FlowRecord } from "../types/flow"
+import type { MethodResult, SetCookie, CachePolicy } from "../types/method"
+import type { Result } from "../types/result"
+import { err, isErr, ok } from "../types/result"
+import type { StateKeyRing, TenantContext } from "../types/tenant"
+
+import { safeAudit } from "./audit"
+import { randomToken } from "./crypto"
+import { MethodCache } from "./method-cache"
+import { dispatchMethod } from "./method-dispatch"
+import { saveEncryptedCode } from "./token"
+import { verifyStateEnvelope } from "./state-envelope"
+import { AUTH_CODE_TTL_MS } from "./authorize"
+
+export type CallbackOutput =
+  | {
+      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 HandleCallbackInput = {
+  /** The raw `Request` for the upstream provider's redirect. */
+  rawRequest: Request
+  cookies: ReadonlyMap<string, string>
+}
+
+export type HandleCallbackDeps = {
+  configStore: ConfigStore
+  sessionStore: SessionStore
+  tokenStore: TokenStore
+  /** Needed for at-rest encryption of the code payload — see `domain/token.ts`. */
+  keyStore: KeyStore
+  auditLog?: AuditLog
+  methodCache: MethodCache
+  stateKeys: StateKeyRing
+  clock: () => number
+  newCodeId?: () => string
+  /**
+   * Build the `TenantContext.request.custom` blob. Wired through from
+   * `IdPOptions.buildCustomContext` by the HTTP layer; if absent the
+   * blob is `{}`.
+   */
+  buildCustomContext?: (
+    req: Request,
+  ) => Record<string, unknown> | Promise<Record<string, unknown>>
+}
+
+export async function handleCallback(
+  input: HandleCallbackInput,
+  deps: HandleCallbackDeps,
+): Promise<Result<CallbackOutput, AuthError>> {
+  const url = new URL(input.rawRequest.url)
+  const state = url.searchParams.get("state")
+  if (!state) {
+    return err(authError.invalidRequest("missing state parameter", "state"))
+  }
+  const envelopeRes = await verifyStateEnvelope(state, deps.stateKeys)
+  if (isErr(envelopeRes)) {
+    await safeAudit(deps, {
+      kind: "flow_replay_attempt",
+      tenantId: null,
+      flowId: "unknown",
+      timestamp: deps.clock(),
+    })
+    return err(authError.invalidRequest(envelopeRes.error.description, "state"))
+  }
+  const envelope = envelopeRes.value
+
+  const flowRes = await deps.sessionStore.consumeFlow(envelope.flowId)
+  if (isErr(flowRes)) {
+    await safeAudit(deps, {
+      kind: "flow_replay_attempt",
+      tenantId: envelope.tenantId,
+      flowId: envelope.flowId,
+      timestamp: deps.clock(),
+    })
+    return err(authError.invalidRequest(flowRes.error.description, "state"))
+  }
+  const flow = flowRes.value
+
+  // 3. State-flow consistency check.
+  if (envelope.tenantId !== flow.tenantId) {
+    await safeAudit(deps, {
+      kind: "flow_tenant_mismatch",
+      stateTenantId: envelope.tenantId,
+      flowTenantId: flow.tenantId,
+      flowId: flow.flowId,
+      timestamp: deps.clock(),
+    })
+    return err(authError.invalidRequest("tenant mismatch", "state"))
+  }
+  if (envelope.nonce !== flow.nonce) {
+    return err(authError.invalidRequest("nonce mismatch", "state"))
+  }
+  if (url.host !== flow.callbackHost) {
+    await safeAudit(deps, {
+      kind: "flow_callback_mismatch",
+      tenantId: flow.tenantId,
+      flowId: flow.flowId,
+      expected: { host: flow.callbackHost, path: flow.callbackPath },
+      actual: { host: url.host, path: url.pathname },
+      timestamp: deps.clock(),
+    })
+    return err(authError.invalidRequest("host mismatch", "state"))
+  }
+  if (normalizePath(url.pathname) !== normalizePath(flow.callbackPath)) {
+    await safeAudit(deps, {
+      kind: "flow_callback_mismatch",
+      tenantId: flow.tenantId,
+      flowId: flow.flowId,
+      expected: { host: flow.callbackHost, path: flow.callbackPath },
+      actual: { host: url.host, path: url.pathname },
+      timestamp: deps.clock(),
+    })
+    return err(authError.invalidRequest("path mismatch", "state"))
+  }
+
+  // 4. Load tenant + resolve method.
+  const cfgRes = await deps.configStore.getTenantConfig(flow.tenantId)
+  if (isErr(cfgRes)) return err(cfgRes.error)
+  const tenant: TenantContext = {
+    id: flow.tenantId,
+    config: cfgRes.value,
+    request: {
+      raw: input.rawRequest,
+      custom: deps.buildCustomContext
+        ? await deps.buildCustomContext(input.rawRequest)
+        : {},
+    },
+  }
+  const methodRes = await deps.methodCache.resolve(cfgRes.value, flow.methodId)
+  if (isErr(methodRes)) return err(methodRes.error)
+
+  // 5. Dispatch.
+  const dispatched = await dispatchMethod({
+    method: methodRes.value,
+    route: "GET /callback",
+    tenant,
+    request: input.rawRequest,
+    subPath: "/callback",
+    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: HandleCallbackDeps,
+): Promise<Result<CallbackOutput, AuthError>> {
+  switch (result.kind) {
+    case "success": {
+      const code = (deps.newCodeId ?? randomToken)()
+      const now = deps.clock()
+      const saved = await saveEncryptedCode(
+        code,
+        {
+          tenantId: flow.tenantId,
+          clientId: flow.clientId,
+          appRedirectUri: flow.appRedirectUri,
+          appState: flow.appState,
+          scopes: flow.scopes,
+          audience: flow.audience,
+          clientPkce: flow.clientPkce,
+          methodId: flow.methodId,
+          methodKind: flow.methodKind,
+          context: flow.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: flow.appRedirectUri,
+        appState: flow.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":
+      await safeAudit(deps, {
+        kind: "authorize_failed",
+        tenantId: flow.tenantId,
+        clientId: flow.clientId,
+        methodId: flow.methodId,
+        methodKind: flow.methodKind,
+        flowId: flow.flowId,
+        reason: result.error.code,
+        timestamp: deps.clock(),
+      })
+      return err(result.error)
+  }
+}
+
+function normalizePath(p: string): string {
+  return p.replace(/\/+$/, "")
+}

package/src/domain/client-auth.ts

@@ -0,0 +1,116 @@
+/**
+ * Shared client-authentication helpers.
+ *
+ * `/token`, `/revoke`, `/introspect`, and refresh-token rotation all need
+ * to validate presented credentials against a `ClientConfig`. The logic is
+ * the same in every case:
+ *
+ *  - **Public clients** MUST NOT present a `client_secret` (RFC 6749 §2.3).
+ *  - **Confidential clients** MUST present a `client_secret`, hashed and
+ *    compared in constant time against `ClientConfig.secretHash`.
+ *
+ * Credentials may ride either in the form body (`client_id`,
+ * `client_secret`) or in an `Authorization: Basic` header
+ * (RFC 6749 §2.3.1). Both encodings are accepted; the header takes
+ * precedence when both are present.
+ *
+ * The hashing function lives in `./token.ts` (`hashClientSecret`) to keep
+ * the legacy phase-2 SHA-256 / base64url format in one place; production
+ * deployments migrate to argon2id later in the rebuild.
+ */
+import { authError, type AuthError } from "../types/error"
+import type { ClientConfig } from "../types/tenant"
+
+import { timingSafeEqualStr } from "./crypto"
+import { hashClientSecret } from "./token"
+
+export type ClientCredentials = {
+  /** Client identifier (always present when credentials are presented). */
+  clientId: string
+  /** Confidential clients only. */
+  clientSecret?: string
+}
+
+/**
+ * Validate presented credentials against `client`. Returns `null` on
+ * success, `AuthError` on rejection.
+ *
+ * Public clients pass when no secret is presented. Confidential clients
+ * require both a secret and a matching `secretHash`.
+ */
+export async function verifyClientCredentials(
+  client: ClientConfig,
+  presentedSecret: string | undefined,
+): Promise<AuthError | null> {
+  if (client.type === "public") {
+    if (presentedSecret) {
+      return authError.invalidClient(
+        "public clients must not present a client_secret",
+      )
+    }
+    return null
+  }
+  if (!presentedSecret) {
+    return authError.invalidClient("confidential client requires client_secret")
+  }
+  const supplied = await hashClientSecret(presentedSecret)
+  if (!timingSafeEqualStr(supplied, client.secretHash)) {
+    return authError.invalidClient("client_secret mismatch")
+  }
+  return null
+}
+
+/**
+ * Parse an `Authorization: Basic <base64>` header.
+ *
+ * Returns `null` for missing / non-Basic headers and for any decoding
+ * failure; callers fall back to form-body credentials.
+ */
+export function parseBasicAuth(
+  header: string | null,
+): ClientCredentials | null {
+  if (!header) return null
+  const match = /^Basic\s+(.+)$/i.exec(header)
+  if (!match || !match[1]) return null
+  let decoded: string
+  try {
+    decoded = atob(match[1])
+  } catch {
+    return null
+  }
+  const colon = decoded.indexOf(":")
+  if (colon === -1) return null
+  let clientId: string
+  let clientSecret: string
+  try {
+    clientId = decodeURIComponent(decoded.slice(0, colon))
+    clientSecret = decodeURIComponent(decoded.slice(colon + 1))
+  } catch {
+    return null
+  }
+  return { clientId, clientSecret }
+}
+
+/**
+ * Merge form-body credentials with an optional `Authorization: Basic`
+ * header. The header wins per RFC 6749 §2.3 when both are present.
+ *
+ * Returns `null` when neither source supplies a `client_id` — callers
+ * then decide whether that's permissible (anonymous revoke is OK; the
+ * token endpoint isn't).
+ */
+export function resolveClientCredentials(input: {
+  authorizationHeader: string | null
+  bodyClientId: string | undefined
+  bodyClientSecret: string | undefined
+}): ClientCredentials | null {
+  const basic = parseBasicAuth(input.authorizationHeader)
+  if (basic) return basic
+  if (!input.bodyClientId) return null
+  return {
+    clientId: input.bodyClientId,
+    ...(input.bodyClientSecret !== undefined
+      ? { clientSecret: input.bodyClientSecret }
+      : {}),
+  }
+}

package/src/domain/client-credentials.ts

@@ -0,0 +1,178 @@
+/**
+ * `/token` endpoint logic for `grant_type=client_credentials` (RFC 6749 §4.4).
+ *
+ * Steps:
+ *   1. Authenticate the client. Must be confidential and must declare
+ *      `client_credentials` in `grantTypes`.
+ *   2. Resolve the tenant's m2m method. The plan models m2m as a method
+ *      with a `client` fn and no routes; we look for the unique
+ *      `type === "m2m"` instance on the tenant. Zero or multiple → error.
+ *   3. Call `method.client({ clientID, clientSecret, params })`. On
+ *      success the method returns the `P` properties it would have
+ *      emitted on a `success` MethodResult.
+ *   4. Invoke the user's `success` callback to mint the subject claim
+ *      with `methodKind = method.kind`, `methodId = method.id`.
+ *   5. `mintTokens` — access token only (no refresh per §4.4.3).
+ *
+ * The framework rejects requests presenting `scope` beyond what
+ * `ClientConfig.scopes` allows.
+ */
+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 { 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, TenantId } from "../types/tenant"
+import type { TokenResponse } from "../types/token"
+
+import { verifyClientCredentials } from "./client-auth"
+import { randomId } from "./crypto"
+import { mintTokens } from "./token"
+import { MethodCache } from "./method-cache"
+
+export type ClientCredentialsRequest = {
+  grantType: "client_credentials"
+  clientId: string
+  clientSecret: string
+  scope?: string
+  /** Extra params (audience, resource, etc.). Forwarded to `method.client`. */
+  params?: Record<string, string>
+}
+
+export type ClientCredentialsDeps = {
+  configStore: ConfigStore
+  tokenStore: TokenStore
+  keyStore: KeyStore
+  auditLog?: AuditLog
+  methodCache: MethodCache
+  success: (input: SuccessMapInput) => Promise<SubjectClaim>
+  persistUpstreamTokens?: PersistUpstreamTokens
+  issuerUrl: string
+  clock: () => number
+  newRefreshFamily?: () => string
+}
+
+export async function clientCredentialsGrant(
+  req: ClientCredentialsRequest,
+  deps: ClientCredentialsDeps,
+  tenantId: TenantId,
+): Promise<Result<TokenResponse, AuthError>> {
+  // 1. Tenant + client lookup.
+  const tenantCfg = await deps.configStore.getTenantConfig(tenantId)
+  if (isErr(tenantCfg)) return err(tenantCfg.error)
+  const client = tenantCfg.value.clients.find((c) => c.id === req.clientId)
+  if (!client) {
+    return err(authError.invalidClient(`unknown client "${req.clientId}"`))
+  }
+  if (client.type !== "confidential") {
+    return err(
+      authError.invalidClient(
+        "client_credentials requires confidential client",
+      ),
+    )
+  }
+  if (!client.grantTypes.includes("client_credentials")) {
+    return err(
+      authError.unauthorizedClient(
+        `client "${client.id}" is not authorized for client_credentials`,
+      ),
+    )
+  }
+  const authErr = await verifyClientCredentials(client, req.clientSecret)
+  if (authErr) return err(authErr)
+
+  // 2. Scope validation.
+  const requestedScopes = req.scope
+    ? req.scope.split(" ").filter(Boolean)
+    : client.scopes
+  for (const s of requestedScopes) {
+    if (!client.scopes.includes(s)) {
+      return err(authError.invalidScope(`scope "${s}" not allowed for client`))
+    }
+  }
+
+  // 3. Resolve m2m method instance.
+  const m2mCfgs = tenantCfg.value.methods.filter(
+    (m) => m.type === "m2m" && m.enabled,
+  )
+  if (m2mCfgs.length === 0) {
+    return err(authError.methodNotFound("no enabled m2m method on tenant", {}))
+  }
+  if (m2mCfgs.length > 1) {
+    return err(
+      authError.methodNotFound(
+        "multiple m2m methods configured — only one supported",
+        {},
+      ),
+    )
+  }
+  const methodCfg = m2mCfgs[0]!
+  const methodRes = await deps.methodCache.resolve(
+    tenantCfg.value,
+    methodCfg.id,
+  )
+  if (isErr(methodRes)) return err(methodRes.error)
+  const method = methodRes.value
+  if (!method.client) {
+    return err(
+      authError.methodNotFound(
+        `m2m method "${methodCfg.id}" did not register a client fn`,
+        { methodId: methodCfg.id, methodKind: method.kind },
+      ),
+    )
+  }
+
+  // 4. Dispatch the method's client fn.
+  const clientResult = await method.client({
+    clientID: req.clientId,
+    clientSecret: req.clientSecret,
+    params: req.params ?? {},
+  })
+  if (isErr(clientResult)) return err(clientResult.error)
+
+  // 5. Build subject claim via user's success callback.
+  const tenant: TenantContext = {
+    id: tenantCfg.value.id,
+    config: tenantCfg.value,
+    request: { raw: new Request("about:blank"), custom: {} },
+  }
+  let claim: SubjectClaim
+  try {
+    claim = await deps.success({
+      tenant,
+      methodId: method.id,
+      methodKind: method.kind,
+      providerSubject: req.clientId,
+      properties: clientResult.value,
+      context: null,
+    })
+  } catch (e) {
+    return err(authError.serverError("success callback threw", e))
+  }
+
+  // 6. Mint access only — RFC 6749 §4.4.3 says client_credentials SHOULD
+  //    NOT issue a refresh token. `skipRefresh: true` keeps the token-
+  //    store from accumulating orphaned rows that the response would
+  //    otherwise strip.
+  const minted = await mintTokens({
+    tenant,
+    claim,
+    payload: {
+      tenantId: tenant.id,
+      clientId: client.id,
+      methodId: method.id,
+      methodKind: method.kind,
+      scopes: requestedScopes,
+      ...(client.scopes.includes("audience") ? {} : {}),
+    },
+    family: (deps.newRefreshFamily ?? randomId)(),
+    skipRefresh: true,
+    deps,
+  })
+  if (isErr(minted)) return err(minted.error)
+  return ok(minted.value)
+}