@_mustachio/openauth 0.9.2 → 0.11.0

package/src/domain/register.ts

@@ -0,0 +1,168 @@
+/**
+ * Dynamic Client Registration (RFC 7591).
+ *
+ * The host owns persistence — this module validates the wire request,
+ * mints a fresh `client_id` (and `client_secret` for confidential
+ * clients), invokes the host's `registerClient` hook with a structured
+ * `ClientConfig`, and builds the §3.2.1 response.
+ *
+ * Per RFC 7591:
+ *  - §2: registration request body is JSON, fields include
+ *    `client_name`, `redirect_uris`, `grant_types`, `response_types`,
+ *    `token_endpoint_auth_method`, `scope`, etc.
+ *  - §3.2.1: response is JSON with `client_id`, optional
+ *    `client_secret`, `client_id_issued_at`, optional
+ *    `client_secret_expires_at`, and the registered metadata.
+ *  - §3.2.2: structural problems → `invalid_client_metadata` /
+ *    `invalid_redirect_uri`. We collapse to `invalid_request` for
+ *    consistency with the rest of the library's error mapping.
+ */
+import { authError, type AuthError } from "../types/error"
+import type {
+  RegisterClient,
+  RegisterClientRequest,
+  RegisterClientResponse,
+} from "../types/idp"
+import type { Result } from "../types/result"
+import { err, isErr, ok } from "../types/result"
+import type { TenantContext } from "../types/tenant"
+
+import { randomId, randomToken } from "./crypto"
+import { hashClientSecret } from "./token"
+
+export type RegisterDeps = {
+  registerClient?: RegisterClient
+  clock: () => number
+  /** Test override for deterministic client_id. */
+  newClientId?: () => string
+  /** Test override for deterministic client_secret. */
+  newClientSecret?: () => string
+}
+
+export async function registerNewClient(
+  request: RegisterClientRequest,
+  tenant: TenantContext,
+  deps: RegisterDeps,
+): Promise<Result<RegisterClientResponse, AuthError>> {
+  if (!deps.registerClient) {
+    return err(
+      authError.invalidRequest(
+        "dynamic client registration is not enabled on this deployment",
+      ),
+    )
+  }
+
+  // RFC 7591 §2 — redirect_uris is REQUIRED for any client that uses a
+  // redirect-based grant. We accept the field as required at the wire
+  // level (schema enforces) and validate non-empty here.
+  if (
+    !Array.isArray(request.redirect_uris) ||
+    request.redirect_uris.length === 0
+  ) {
+    return err(
+      authError.invalidRequest(
+        "redirect_uris must be a non-empty array",
+        "redirect_uris",
+      ),
+    )
+  }
+  for (const uri of request.redirect_uris) {
+    try {
+      // Reject relative / opaque URIs eagerly so the host gets a clean
+      // structural rejection instead of a runtime surprise at /authorize.
+      // RFC 7591 §2 leaves URI scheme to grant-type semantics; we follow
+      // the OAuth 2.1 BCP and require absolute URIs.
+      void new URL(uri)
+    } catch {
+      return err(
+        authError.invalidRequest(
+          `redirect_uri "${uri}" is not a valid absolute URI`,
+          "redirect_uris",
+        ),
+      )
+    }
+  }
+
+  const authMethod = request.token_endpoint_auth_method ?? "client_secret_basic"
+  const isPublic = authMethod === "none"
+  const clientId = (deps.newClientId ?? randomId)()
+  const grantTypes = request.grant_types ?? ["authorization_code"]
+  const responseTypes = request.response_types ?? ["code"]
+  const scopes = request.scope
+    ? request.scope.split(/\s+/).filter(Boolean)
+    : ["openid"]
+
+  let secret: string | undefined
+  let secretHash: string | undefined
+  if (!isPublic) {
+    secret = (deps.newClientSecret ?? randomToken)()
+    secretHash = await hashClientSecret(secret)
+  }
+
+  const clientPartial = {
+    id: clientId,
+    name: request.client_name ?? clientId,
+    redirectUris: request.redirect_uris,
+    // Default scopes overlap with what the IdP advertises; hosts may
+    // override during the hook call before persisting.
+    scopes,
+    grantTypes: grantTypes.filter(
+      (g): g is "authorization_code" | "refresh_token" | "client_credentials" =>
+        g === "authorization_code" ||
+        g === "refresh_token" ||
+        g === "client_credentials",
+    ),
+    ...(request.post_logout_redirect_uris !== undefined
+      ? { postLogoutRedirectUris: request.post_logout_redirect_uris }
+      : {}),
+    ...(request.sector_identifier_uri !== undefined
+      ? { sectorIdentifier: request.sector_identifier_uri }
+      : {}),
+  }
+
+  const clientConfig = isPublic
+    ? {
+        ...clientPartial,
+        type: "public" as const,
+        pkceRequired: true as const,
+      }
+    : {
+        ...clientPartial,
+        type: "confidential" as const,
+        secretHash: secretHash!,
+        pkceRequired: true,
+      }
+
+  const hookResult = await deps.registerClient({
+    tenant,
+    request,
+  })
+  // The hook may either:
+  //  - persist `clientConfig` as-is (most common) and return it,
+  //  - synthesize its own (host-owned id generation, custom scopes) and
+  //    return that — in which case the secret we minted is moot.
+  // We trust the hook's returned client + secret as authoritative.
+  void clientConfig
+
+  if (isErr(hookResult)) return err(hookResult.error)
+  const persisted = hookResult.value.client
+  const persistedSecret = hookResult.value.secret
+
+  const issuedAt = Math.floor(deps.clock() / 1000)
+  return ok({
+    client_id: persisted.id,
+    ...(persistedSecret !== undefined
+      ? { client_secret: persistedSecret }
+      : {}),
+    client_id_issued_at: issuedAt,
+    // RFC 7591 §3.2.1: `0` = no expiry.
+    client_secret_expires_at: 0,
+    redirect_uris: persisted.redirectUris,
+    grant_types: persisted.grantTypes,
+    response_types: responseTypes,
+    token_endpoint_auth_method: authMethod,
+    ...(request.client_name !== undefined
+      ? { client_name: request.client_name }
+      : {}),
+  })
+}

package/src/domain/revoke.ts

@@ -0,0 +1,161 @@
+/**
+ * `/revoke` endpoint logic (RFC 7009).
+ *
+ * Access tokens are stateless JWTs in this IdP; revocation has to wait
+ * for natural expiry. `tokenTypeHint: "access_token"` resolves to a
+ * no-op per RFC 7009 §2.2 (invalid hint is ignored).
+ *
+ * Refresh tokens are server-side state. RFC 7009 §2.2 requires the
+ * authorization server to verify that the presented token was issued to
+ * the authenticated client and refuse otherwise. We implement this via
+ * `peekRefresh` (non-destructive) → ownership check → `consumeRefresh`
+ * (destructive). The peek/consume race is benign: if a concurrent caller
+ * consumes the token in between, our consume returns `invalid_grant`,
+ * which RFC 7009 §2.2 says we treat as a successful no-op.
+ *
+ * Anonymous revoke (no `client_id`) is permitted only for tokens issued
+ * to public clients. Confidential-client tokens MUST authenticate per
+ * RFC 7009 §2.1.
+ */
+import type { AuditLog } from "../ports/audit-log"
+import type { ConfigStore } from "../ports/config-store"
+import type { TokenStore } from "../ports/token-store"
+import type { AuthError } from "../types/error"
+import { authError } from "../types/error"
+import type { Result } from "../types/result"
+import { err, isErr, ok } from "../types/result"
+import type { TenantId } from "../types/tenant"
+
+import { safeAudit } from "./audit"
+import { verifyClientCredentials } from "./client-auth"
+
+export type RevokeRequest = {
+  token: string
+  /** RFC 7009 hint: `"access_token"` or `"refresh_token"`. */
+  tokenTypeHint?: "access_token" | "refresh_token"
+  /** Optional — required when revoking a confidential client's token. */
+  clientId?: string
+  clientSecret?: string
+}
+
+export type RevokeDeps = {
+  tokenStore: TokenStore
+  configStore: ConfigStore
+  auditLog?: AuditLog
+  clock: () => number
+}
+
+/**
+ * Revoke a single refresh token. Anonymous revokes are accepted for
+ * public-client tokens; confidential-client tokens require valid
+ * credentials.
+ */
+export async function revokeToken(
+  req: RevokeRequest,
+  deps: RevokeDeps,
+): Promise<Result<void, AuthError>> {
+  if (req.tokenTypeHint === "access_token") {
+    return ok(undefined)
+  }
+
+  // RFC 7009 §2.2: unknown tokens are successful no-ops. Peek tells us
+  // the token's owner without consuming so we can authenticate first.
+  const peek = await deps.tokenStore.peekRefresh(req.token)
+  if (isErr(peek)) {
+    return ok(undefined)
+  }
+  const payload = peek.value
+
+  // Load the issuing client so we can decide whether auth is required.
+  const tenantCfg = await deps.configStore.getTenantConfig(payload.tenantId)
+  if (isErr(tenantCfg)) {
+    // Tenant evaporated. Treat as no-op — caller can't usefully retry.
+    return ok(undefined)
+  }
+  const client = tenantCfg.value.clients.find((c) => c.id === payload.clientId)
+  if (!client) {
+    return ok(undefined)
+  }
+
+  // Confidential clients MUST authenticate per RFC 7009 §2.1.
+  if (client.type === "confidential") {
+    if (!req.clientId || !req.clientSecret) {
+      return err(
+        authError.invalidClient(
+          "confidential client must authenticate to revoke its tokens",
+        ),
+      )
+    }
+  }
+
+  // If a client_id was presented but it doesn't own the token, RFC 7009
+  // §2.2 still wants a successful no-op response — surfacing
+  // `invalid_grant` here would let a different client probe for token
+  // existence. Audit the attempt so operators can spot abuse.
+  if (req.clientId !== undefined && req.clientId !== payload.clientId) {
+    await safeAudit(deps, {
+      kind: "custom",
+      type: "revoke_wrong_client_attempt",
+      tenantId: payload.tenantId,
+      data: {
+        presentedClientId: req.clientId,
+        tokenClientId: payload.clientId,
+        subjectId: payload.subjectId,
+      },
+      timestamp: deps.clock(),
+    })
+    return ok(undefined)
+  }
+
+  // Credentials presented by the owning client must validate. Anonymous
+  // revoke of a public-client token is permitted.
+  if (req.clientId !== undefined) {
+    const authErr = await verifyClientCredentials(client, req.clientSecret)
+    if (authErr) return err(authErr)
+  }
+
+  const consumed = await deps.tokenStore.consumeRefresh(req.token, {
+    reuseWindowMs: 0,
+  })
+  if (isErr(consumed)) {
+    return ok(undefined)
+  }
+  await safeAudit(deps, {
+    kind: "token_revoked",
+    tenantId: payload.tenantId,
+    clientId: payload.clientId,
+    subjectId: payload.subjectId,
+    family: payload.family,
+    reason: "client_revoke",
+    timestamp: deps.clock(),
+  })
+  return ok(undefined)
+}
+
+/**
+ * Revoke every refresh token for a `(tenantId, subjectId)` pair and emit
+ * a `token_revoked` audit event with `reason: "subject_revoke"`.
+ *
+ * Public primitive exposed for host-driven "log me out of all devices"
+ * flows. Not called from the reuse-detection path — that stays at
+ * family-scope per OAuth 2.0 Security BCP §4.13.2 (revoking sibling
+ * families would punish legitimate other-device sessions sharing the
+ * same subject). See ARCHITECTURE.md §"Reuse detection scope".
+ */
+export async function revokeAllForSubject(
+  tenantId: TenantId,
+  subjectId: string,
+  deps: { tokenStore: TokenStore; auditLog?: AuditLog; clock: () => number },
+): Promise<Result<void, AuthError>> {
+  const res = await deps.tokenStore.revokeBySubject(tenantId, subjectId)
+  if (isErr(res)) return err(res.error)
+  await safeAudit(deps, {
+    kind: "token_revoked",
+    tenantId,
+    clientId: null,
+    subjectId,
+    reason: "subject_revoke",
+    timestamp: deps.clock(),
+  })
+  return ok(undefined)
+}

package/src/domain/state-envelope.ts

@@ -0,0 +1,142 @@
+/**
+ * MAC-signed `state` envelope used by the tenant-recovery chain.
+ *
+ * Format (intentionally compact, well under 256 base64url bytes):
+ *
+ *   `<b64u(payloadJson)>.<b64u(hmacSha256(payloadJson, key[kid]))>`
+ *
+ * where `payloadJson` is canonical JSON over `{tenantId, flowId, nonce, kid}`.
+ *
+ * **Nothing sensitive is in the envelope** — only the minimal recovery
+ * tuple. Sensitive data (`clientPkce`, `appRedirectUri`, scopes, etc.)
+ * lives in the server-side `FlowRecord`, identified by `flowId`.
+ *
+ * See `ARCHITECTURE.md` §"Tenant recovery across redirects" and plan
+ * §"Crypto — HMAC-SHA-256".
+ */
+import { authError, type AuthError } from "../types/error"
+import type { Result } from "../types/result"
+import { err, ok } from "../types/result"
+import type {
+  StateEnvelope,
+  StateKey,
+  StateKeyRing,
+  TenantId,
+} from "../types/tenant"
+import { asTenantId } from "../types/tenant"
+
+import { base64url, hmacSign, hmacVerify, importHmacKey, utf8 } from "./crypto"
+
+/**
+ * Serialize envelope fields in a fixed order so the MAC input is
+ * deterministic regardless of object-key insertion order.
+ */
+function canonicalize(env: StateEnvelope): string {
+  return JSON.stringify({
+    tenantId: env.tenantId,
+    flowId: env.flowId,
+    nonce: env.nonce,
+    kid: env.kid,
+  })
+}
+
+/** Mint a signed state string for the given envelope under the active key. */
+export async function mintStateEnvelope(
+  envelope: Omit<StateEnvelope, "kid">,
+  keyRing: StateKeyRing,
+): Promise<string> {
+  const active = keyRing.active
+  const stamped: StateEnvelope = { ...envelope, kid: active.kid }
+  const payloadBytes = utf8.encode(canonicalize(stamped))
+  const key = await importHmacKey(active.key, ["sign"])
+  const sig = await hmacSign(key, payloadBytes)
+  return `${base64url.encode(payloadBytes)}.${base64url.encode(sig)}`
+}
+
+/**
+ * Verify and parse a state string. Returns `unknown_state` on malformed
+ * input, unknown `kid`, or signature mismatch.
+ *
+ * The MAC verification step uses `crypto.subtle.verify`, which is
+ * timing-safe by spec.
+ */
+export async function verifyStateEnvelope(
+  state: string,
+  keyRing: StateKeyRing,
+): Promise<Result<StateEnvelope, AuthError>> {
+  if (typeof state !== "string" || !state.includes(".")) {
+    return err(authError.unknownState("malformed state"))
+  }
+  const dotIdx = state.indexOf(".")
+  const headerB64u = state.slice(0, dotIdx)
+  const sigB64u = state.slice(dotIdx + 1)
+  if (!headerB64u || !sigB64u || sigB64u.includes(".")) {
+    return err(authError.unknownState("malformed state"))
+  }
+
+  let payloadBytes: Uint8Array
+  let sigBytes: Uint8Array
+  try {
+    payloadBytes = base64url.decode(headerB64u)
+    sigBytes = base64url.decode(sigB64u)
+  } catch {
+    return err(authError.unknownState("malformed state encoding"))
+  }
+
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(utf8.decode(payloadBytes))
+  } catch {
+    return err(authError.unknownState("malformed state payload"))
+  }
+  if (!isEnvelopeShape(parsed)) {
+    return err(authError.unknownState("state payload missing fields"))
+  }
+
+  const candidate = findKey(keyRing, parsed.kid)
+  if (!candidate) {
+    return err(authError.unknownState(`unknown state kid "${parsed.kid}"`))
+  }
+
+  const key = await importHmacKey(candidate.key, ["verify"])
+  const okSig = await hmacVerify(key, sigBytes, payloadBytes)
+  if (!okSig) {
+    return err(authError.unknownState("state signature mismatch"))
+  }
+
+  // Cross-check that the payload's `kid` matches the verifying key — guards
+  // against a malicious sender re-encoding the header to claim a different
+  // key was used while the MAC was actually computed under another.
+  if (parsed.kid !== candidate.kid) {
+    return err(authError.unknownState("state kid drift"))
+  }
+
+  return ok({
+    tenantId: asTenantId(parsed.tenantId),
+    flowId: parsed.flowId,
+    nonce: parsed.nonce,
+    kid: parsed.kid,
+  })
+}
+
+function findKey(ring: StateKeyRing, kid: string): StateKey | undefined {
+  return ring.verify.find((k) => k.kid === kid)
+}
+
+type EnvelopeShape = {
+  tenantId: TenantId & string
+  flowId: string
+  nonce: string
+  kid: string
+}
+
+function isEnvelopeShape(value: unknown): value is EnvelopeShape {
+  if (!value || typeof value !== "object") return false
+  const v = value as Record<string, unknown>
+  return (
+    typeof v.tenantId === "string" &&
+    typeof v.flowId === "string" &&
+    typeof v.nonce === "string" &&
+    typeof v.kid === "string"
+  )
+}