@sixthsummit/ship-api 0.0.0-stage → 4.1.1

package/lib/modules/oauth/services/OAuthConnectionService.ts

@@ -0,0 +1,147 @@
+import { DrizzleEntityService } from "@sixthsummit/ship-api/app/services/DrizzleEntityService";
+// eslint-disable-next-line @typescript-eslint/no-restricted-imports -- conditional provider/account lookups + upsert; candidate for a QueryOptions refactor
+import { and, eq } from "drizzle-orm";
+import {
+  authorizationHeader,
+  isActive,
+  isExpired,
+  isExpiringSoon,
+  needsRefresh,
+  type OAuthConnection,
+  oauthConnections,
+} from "../schema.js";
+
+/**
+ * v4 `OAuthConnectionService` — extends `DrizzleEntityService` for
+ * CRUD on the oauth_connections table, plus connection-management
+ * helpers that v3 spread across `OAuthService.ts`.
+ *
+ * Inherits get / getAll / list / count / create / update / delete
+ * (with soft-delete + audit-column auto-stamping) from the base. Adds:
+ *
+ *   - findByAccountAndProvider(accountId, providerCode)
+ *   - upsertTokens(...) — atomic insert-or-update on the unique
+ *     (accountId, providerCode) composite, used by adapter callbacks
+ *   - clearTokens(id) — disconnect: nulls out access/refresh/expires
+ *     without deleting the row (preserves provider linkage history)
+ *   - status helpers re-exposed: isExpired / isExpiringSoon /
+ *     isActive / needsRefresh / authorizationHeader (delegate to the
+ *     module-level pure functions in schema.ts)
+ *
+ * Token rotation flows in via `upsertTokens` from adapter callbacks
+ * (`oauth/{provider}/callback`); refresh flows in via the same path
+ * from a worker that polls `expiresAt` indexes for soon-to-expire
+ * tokens.
+ */
+export class OAuthConnectionService extends DrizzleEntityService<
+  typeof oauthConnections,
+  { oauthConnections: typeof oauthConnections }
+> {
+  protected getTable() {
+    return oauthConnections;
+  }
+
+  protected override getDefaultSearchFields(): readonly string[] {
+    return ["providerCode", "providerAccountId"];
+  }
+
+  protected override getDefaultRelations(): readonly string[] {
+    return ["account"];
+  }
+
+  /**
+   * Look up the row keyed by (accountId, providerCode). Returns `null`
+   * when the account hasn't connected the provider.
+   */
+  async findByAccountAndProvider(
+    accountId: string,
+    providerCode: string,
+  ): Promise<OAuthConnection | null> {
+    const rows = await this.db
+      .select()
+      .from(oauthConnections)
+      .where(
+        and(
+          eq(oauthConnections.accountId, accountId),
+          eq(oauthConnections.providerCode, providerCode),
+        ),
+      )
+      .limit(1);
+    return (rows[0] as OAuthConnection | undefined) ?? null;
+  }
+
+  /**
+   * Upsert pattern keyed on the unique (accountId, providerCode)
+   * composite — used by adapter callback handlers when a user grants
+   * access (insert) or re-grants (update). Drizzle's `onConflictDoUpdate`
+   * matches the unique index and updates the same fields on conflict.
+   */
+  async upsertTokens(values: {
+    accountId: string;
+    providerCode: string;
+    accessToken?: string;
+    refreshToken?: string;
+    expiresAt?: Date;
+    scope?: string;
+    tokenType?: string;
+    providerAccountId?: string;
+    metadata?: Record<string, unknown>;
+  }): Promise<OAuthConnection> {
+    const insertValues = {
+      accountId: values.accountId,
+      providerCode: values.providerCode,
+      accessToken: values.accessToken ?? null,
+      refreshToken: values.refreshToken ?? null,
+      expiresAt: values.expiresAt ?? null,
+      scope: values.scope ?? null,
+      tokenType: values.tokenType ?? null,
+      providerAccountId: values.providerAccountId ?? null,
+      metadata: values.metadata ?? {},
+    };
+    const [row] = await this.db
+      .insert(oauthConnections)
+      .values(insertValues as never)
+      .onConflictDoUpdate({
+        target: [oauthConnections.accountId, oauthConnections.providerCode],
+        set: {
+          accessToken: insertValues.accessToken,
+          refreshToken: insertValues.refreshToken,
+          expiresAt: insertValues.expiresAt,
+          scope: insertValues.scope,
+          tokenType: insertValues.tokenType,
+          providerAccountId: insertValues.providerAccountId,
+          metadata: insertValues.metadata,
+        } as never,
+      })
+      .returning();
+    return row as OAuthConnection;
+  }
+
+  /**
+   * Clear tokens (disconnect) without deleting the row — preserves the
+   * provider-account-ID linkage so a later reconnect doesn't create a
+   * stale duplicate.
+   */
+  async clearTokens(id: string): Promise<OAuthConnection | null> {
+    const [row] = await this.db
+      .update(oauthConnections)
+      .set({
+        accessToken: null,
+        refreshToken: null,
+        expiresAt: null,
+        scope: null,
+        tokenType: null,
+      } as never)
+      .where(eq(oauthConnections.id, id))
+      .returning();
+    return (row as OAuthConnection | undefined) ?? null;
+  }
+
+  // Re-export the module-level status helpers so callers don't have to
+  // import them separately when they already hold a service reference.
+  isExpired = isExpired;
+  isExpiringSoon = isExpiringSoon;
+  isActive = isActive;
+  needsRefresh = needsRefresh;
+  authorizationHeader = authorizationHeader;
+}

package/lib/modules/oauth/state.ts

@@ -0,0 +1,234 @@
+import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+
+/**
+ * Opaque state primitive for the OAuth `state` parameter.
+ *
+ * The framework owns this end-to-end: adapters round-trip the string
+ * verbatim, never inspect it. The routes layer:
+ *
+ *   1. Builds a `StatePayload` describing what user is connecting and
+ *      to which provider.
+ *   2. Calls `signState(payload, secret)` → opaque token to embed in
+ *      the authorize URL.
+ *   3. On callback, calls `verifyState(state, secret)` → recovers the
+ *      payload, throws on tamper / expiry.
+ *
+ * Encoding: `base64url(payloadJson) . base64url(hmacSha256(payloadJson, secret))`
+ *
+ * Why HMAC-SHA256 instead of ES256/JWT:
+ *   - State payloads are tiny (account-id + provider + nonce + ts);
+ *     JWT's overhead doesn't add value.
+ *   - HMAC-SHA256 is timing-safe-comparable in stdlib without
+ *     additional ceremony.
+ *   - No external key-rotation infrastructure needed; secret comes
+ *     from the framework's existing JWT signing-key plumbing.
+ *
+ * Replay protection: timestamp window (default 10 minutes). The OAuth
+ * `code` itself is single-use at the provider — the upstream rejects
+ * code reuse even if state were replayable. The window is the
+ * defense against a leaked state being used minutes later by the
+ * attacker before the legitimate user finishes the flow.
+ *
+ * Tamper protection: HMAC over the full payload-JSON. Any byte change
+ * in the encoded payload fails verification.
+ */
+
+export interface StatePayload {
+  /** Framework-owned subject — typically `accounts.id`. */
+  accountId: string;
+  /** Provider being connected, matches `providerCode` on the connection row. */
+  providerCode: string;
+  /**
+   * Caller-defined return-target after callback completes (e.g. the
+   * page the user was on when they hit "connect"). Sanitize at the
+   * routes layer before redirecting.
+   */
+  returnTo?: string;
+  /**
+   * Free-form caller-defined extras the framework round-trips. Used
+   * by routes that initiate OAuth as part of a larger flow (e.g.
+   * onboarding wizard step IDs).
+   */
+  extras?: Record<string, unknown>;
+  /**
+   * PKCE code-verifier (raw, base64url-encoded, 43–128 chars). The
+   * framework generates this in the authorize handler, derives the
+   * SHA-256 challenge for the upstream provider, and signs the
+   * verifier into state so the callback can pass it back to the
+   * adapter's `exchangeCodeForTokens` (F12).
+   */
+  codeVerifier?: string;
+  /**
+   * Per-state opaque nonce, populated by `signState` (16 random
+   * base64url bytes). `signState` ignores this when supplied by
+   * the caller — it always generates a fresh nonce. `verifyState`
+   * surfaces the recovered nonce so the routes layer can use it as
+   * a single-use JTI against a short-TTL replay cache (F16).
+   */
+  nonce?: string;
+}
+
+interface SignedStatePayload extends StatePayload {
+  /** Issued-at unix milliseconds. */
+  iat: number;
+  /** Opaque random nonce — defends against replay within the window. */
+  nonce: string;
+}
+
+export class InvalidStateError extends Error {
+  constructor(reason: string) {
+    super(`OAuth state invalid: ${reason}`);
+    this.name = "InvalidStateError";
+  }
+}
+
+export interface SignStateOptions {
+  /** Override the unix-ms-now used for `iat`. Tests inject a fixed clock. */
+  now?: () => number;
+}
+
+export interface VerifyStateOptions {
+  /**
+   * Acceptable age in milliseconds. Default 10 minutes. The state is
+   * rejected when (now - iat) exceeds this.
+   */
+  maxAgeMs?: number;
+  /** Override the now-source. Tests pin time. */
+  now?: () => number;
+}
+
+const DEFAULT_MAX_AGE_MS = 10 * 60 * 1000;
+
+/**
+ * State-signing secret. A single string is the simple path; an ordered
+ * array enables zero-downtime rotation — the **head** is the active
+ * signing key, every entry is accepted on verify. Standard rotation
+ * pattern:
+ *
+ *   1. Prepend the new key to the head: `[ "new", "old" ]`.
+ *   2. Wait at least `maxAgeMs` (default 10 minutes) for any in-flight
+ *      old-key states to expire.
+ *   3. Drop the old key from the tail: `[ "new" ]`.
+ *
+ * `defineEnv` is the boundary that turns env vars into this shape;
+ * consumers typically expose `OAUTH_STATE_SECRET` as a single string
+ * during steady-state and switch to a JSON-array env (or split into
+ * `OAUTH_STATE_SECRET_NEW` + `OAUTH_STATE_SECRET_OLD` parsed into an
+ * array in `environment.ts`) during a rotation window.
+ */
+export type StateSecret = string | readonly string[];
+
+/**
+ * Returns the head (active signing) key. Throws when no usable key is
+ * available — empty string, empty array, or array of empty strings.
+ */
+function resolveSigningKey(secret: StateSecret): string {
+  if (typeof secret === "string") {
+    if (!secret) throw new Error("signState: secret is required");
+    return secret;
+  }
+  for (const candidate of secret) {
+    if (typeof candidate === "string" && candidate.length > 0) return candidate;
+  }
+  throw new Error("signState: secret is required");
+}
+
+/**
+ * Returns every non-empty key in the verification set, head first.
+ * Throws when the set is empty (same error as v0.1's single-string
+ * "secret is required" path so existing callers see a familiar error).
+ */
+function resolveVerificationKeys(secret: StateSecret): readonly string[] {
+  if (typeof secret === "string") {
+    if (!secret) throw new Error("verifyState: secret is required");
+    return [secret];
+  }
+  const out = secret.filter((k) => typeof k === "string" && k.length > 0);
+  if (out.length === 0) throw new Error("verifyState: secret is required");
+  return out;
+}
+
+export function signState(
+  payload: StatePayload,
+  secret: StateSecret,
+  opts: SignStateOptions = {},
+): string {
+  const signingKey = resolveSigningKey(secret);
+  const now = opts.now?.() ?? Date.now();
+  const signed: SignedStatePayload = {
+    ...payload,
+    iat: now,
+    nonce: randomBytes(16).toString("base64url"),
+  };
+  const json = JSON.stringify(signed);
+  const payloadEncoded = Buffer.from(json, "utf8").toString("base64url");
+  const sig = createHmac("sha256", signingKey).update(payloadEncoded).digest("base64url");
+  return `${payloadEncoded}.${sig}`;
+}
+
+export function verifyState(
+  state: string,
+  secret: StateSecret,
+  opts: VerifyStateOptions = {},
+): StatePayload {
+  if (!state) throw new InvalidStateError("missing state");
+  const verificationKeys = resolveVerificationKeys(secret);
+
+  const dot = state.indexOf(".");
+  if (dot === -1) throw new InvalidStateError("malformed state");
+  const payloadEncoded = state.slice(0, dot);
+  const sigSupplied = state.slice(dot + 1);
+  const supplied = Buffer.from(sigSupplied, "base64url");
+
+  // Iterate every key to completion even after a match. Short-circuiting
+  // on first match would leak via wall-clock timing which position in
+  // the rotation set matched — narrowing the search for any known-leaked
+  // tail key. The keyset is small (1–3 in practice) and HMAC-SHA256 over
+  // a ~1KB payload is microseconds; the cost of constant-time is
+  // negligible. Per-iteration HMAC compare is already timing-safe via
+  // `timingSafeEqual`; this loop wraps it in a constant-iteration outer.
+  let matched = false;
+  for (const key of verificationKeys) {
+    const expected = createHmac("sha256", key).update(payloadEncoded).digest("base64url");
+    const expectedBytes = Buffer.from(expected, "base64url");
+    if (supplied.length === expectedBytes.length && timingSafeEqual(supplied, expectedBytes)) {
+      matched = true;
+      // No `break` — keep iterating to flatten the timing profile.
+    }
+  }
+  if (!matched) {
+    throw new InvalidStateError("signature mismatch");
+  }
+
+  let parsed: SignedStatePayload;
+  try {
+    const json = Buffer.from(payloadEncoded, "base64url").toString("utf8");
+    parsed = JSON.parse(json) as SignedStatePayload;
+  } catch {
+    throw new InvalidStateError("payload not valid JSON");
+  }
+
+  if (
+    typeof parsed.accountId !== "string" ||
+    typeof parsed.providerCode !== "string" ||
+    typeof parsed.iat !== "number" ||
+    typeof parsed.nonce !== "string"
+  ) {
+    throw new InvalidStateError("payload missing required fields");
+  }
+
+  const now = opts.now?.() ?? Date.now();
+  const maxAgeMs = opts.maxAgeMs ?? DEFAULT_MAX_AGE_MS;
+  const age = now - parsed.iat;
+  if (age < 0) throw new InvalidStateError("state issued in the future");
+  if (age > maxAgeMs) throw new InvalidStateError("state expired");
+
+  return {
+    accountId: parsed.accountId,
+    providerCode: parsed.providerCode,
+    returnTo: parsed.returnTo,
+    extras: parsed.extras,
+    codeVerifier: parsed.codeVerifier,
+    nonce: parsed.nonce,
+  };
+}

package/lib/modules/oauth/stateJtiCache.ts

@@ -0,0 +1,85 @@
+/**
+ * `StateJtiCache` — single-use bookkeeping for OAuth state nonces (F16).
+ *
+ * The framework's signed state already defends against tampering and
+ * carries a 10-minute expiry window. Inside that window, single-use
+ * is enforced *only* by the upstream provider invalidating the
+ * authorization code on exchange — fine when providers behave, but:
+ *
+ *   - Some providers retry on idempotent failures (e.g. transient
+ *     network errors on the framework's token-exchange request)
+ *     instead of invalidating eagerly.
+ *   - A downstream adapter retry against a failed exchange can resend
+ *     the same state.
+ *   - A leaked-then-replayed state from logs / browser history / a
+ *     misconfigured proxy that records query strings is theoretically
+ *     replayable until the 10-minute window closes.
+ *
+ * This cache closes the within-window window: every successful state
+ * verification records the nonce (acting as a JTI) with a short TTL.
+ * A second use of the same nonce is rejected as a replay.
+ *
+ * Default in-memory implementation; multi-instance deployments need
+ * a shared backing (Redis, etc.) to enforce single-use across nodes.
+ * Surface the interface so a custom implementation can plug in.
+ */
+
+export interface StateJtiCache {
+  /**
+   * Atomic check + record. Returns `true` when `jti` was seen
+   * within the last `ttlMs` (treat as replay; reject); returns
+   * `false` when `jti` is fresh (record it and let the call
+   * proceed). Same-tick semantics: within a single event-loop tick,
+   * concurrent `seenAndRecord` calls behave like CAS (exactly one
+   * returns `false`).
+   */
+  seenAndRecord(jti: string, ttlMs?: number): boolean;
+}
+
+/**
+ * Default in-memory implementation. A `Map<string, number>` where
+ * the value is the entry's expiration epoch (ms). Pruned
+ * opportunistically on each call — no separate timer thread.
+ *
+ * Process lifecycle: entries reset on process restart. State has a
+ * 10-minute expiry, so a restart effectively widens the replay
+ * window to 10 minutes (not unlimited). Multi-instance consumers
+ * (behind a load balancer) need a shared cache to enforce
+ * single-use across nodes; swap in a Redis-backed implementation
+ * of `StateJtiCache` to do so.
+ */
+export class InMemoryStateJtiCache implements StateJtiCache {
+  private readonly entries = new Map<string, number>();
+  private lastPruneAt = 0;
+
+  /** Default TTL = 60 s (≈ longest reasonable OAuth round-trip). */
+  static readonly DEFAULT_TTL_MS = 60_000;
+
+  /** Run a prune at most every `PRUNE_INTERVAL_MS` to amortize cost. */
+  private static readonly PRUNE_INTERVAL_MS = 5_000;
+
+  seenAndRecord(jti: string, ttlMs = InMemoryStateJtiCache.DEFAULT_TTL_MS): boolean {
+    const now = Date.now();
+    this.maybePrune(now);
+
+    const existing = this.entries.get(jti);
+    if (existing !== undefined && existing > now) {
+      return true; // replay
+    }
+    this.entries.set(jti, now + ttlMs);
+    return false;
+  }
+
+  /** Exposed for tests; not part of the public contract. */
+  _size(): number {
+    return this.entries.size;
+  }
+
+  private maybePrune(now: number): void {
+    if (now - this.lastPruneAt < InMemoryStateJtiCache.PRUNE_INTERVAL_MS) return;
+    this.lastPruneAt = now;
+    for (const [jti, expiresAt] of this.entries) {
+      if (expiresAt <= now) this.entries.delete(jti);
+    }
+  }
+}

package/lib/modules/oauth/verifyIdToken.ts

@@ -0,0 +1,178 @@
+import { AuthenticationError } from "@sixthsummit/ship-api/http/errors/AuthenticationError";
+import type { JWTPayload, JWTVerifyOptions } from "jose";
+import { createRemoteJWKSet, errors as joseErrors, jwtVerify } from "jose";
+
+/**
+ * Key resolver accepted by `jose.jwtVerify` — a literal key, a
+ * `JWKSet` instance returned from `createRemoteJWKSet` /
+ * `createLocalJWKSet`, or a callable that yields one per JWS
+ * header.
+ */
+export type IdTokenKeyInput = Parameters<typeof jwtVerify>[1];
+
+/**
+ * `verifyIdToken` — OIDC `id_token` verification helper (F13).
+ *
+ * **`@internal` — no adapter currently consumes `id_token` as an
+ * identity decision.** The existing adapters resolve the provider
+ * account id via `/userinfo` over a Bearer-authenticated access
+ * token, not via id_token claims. This helper exists so any future
+ * code path that promotes id_token claims to identity decisions
+ * (e.g. `email_verified`, `sub` lookup without a userinfo round-trip)
+ * MUST route through it instead of decoding the JWT directly.
+ *
+ * Verifies, in order:
+ *   1. Signature against the provider's JWKS (RS256 / ES256 — `jose`
+ *      picks the algorithm from the JWS header).
+ *   2. `iss` (issuer) matches `expectedIssuer`.
+ *   3. `aud` (audience) matches `expectedAudience`.
+ *   4. `exp` / `nbf` / `iat` against the current clock (configurable
+ *      tolerance, default 30s — matches `JwtSigner`'s P0-F9 default).
+ *   5. `nonce` claim equals `expectedNonce` (constant-time string
+ *      compare). This is the defense the helper is named for: without
+ *      a nonce check, an attacker who captures a victim's id_token in
+ *      one OIDC flow can replay it into a separate framework-initiated
+ *      flow to impersonate the victim's identity decision.
+ *
+ * Throws `AuthenticationError` on any failure — caller surfaces this
+ * through the framework's standard error path.
+ *
+ * JWKS fetches are cached per-URI inside the module (`jose`'s
+ * `createRemoteJWKSet` does this internally — same `URL` value
+ * resolves to the same JWKS instance across the process lifetime).
+ *
+ * Future call-site contract: any code path that promotes id_token
+ * claims to a security decision (account lookup, `email_verified`
+ * gating, role assignment) MUST call this helper with the nonce
+ * the framework signed into state for the originating flow. The
+ * routes layer already round-trips a `nonce` field in the signed
+ * `StatePayload` — wire the nonce echo there when an adapter
+ * actually consumes id_token.
+ */
+
+export interface VerifyIdTokenOptions {
+  /** Raw id_token JWS (`xxxx.yyyy.zzzz`). */
+  idToken: string;
+  /**
+   * Provider's JWKS endpoint URL (e.g. `https://www.googleapis.com/oauth2/v3/certs`)
+   * **OR** a pre-built key/JWKS resolver from `jose`. Production
+   * code typically passes the URL string; tests + advanced callers
+   * pass a `createLocalJWKSet({ keys: [...] })` or a literal
+   * `CryptoKey` to avoid the network round-trip.
+   *
+   * When a URL string is supplied, the helper memoizes the
+   * `createRemoteJWKSet` instance per URL across the process so
+   * repeated calls against the same provider don't refetch keys per
+   * request.
+   */
+  key: string | IdTokenKeyInput;
+  /**
+   * Nonce echoed from the framework-signed OAuth state. Compared
+   * against the JWT's `nonce` claim. Required — passing an empty
+   * string is a configuration error and rejects every token.
+   */
+  expectedNonce: string;
+  /**
+   * Expected `iss` claim (e.g. `https://accounts.google.com`,
+   * `https://login.microsoftonline.com/<tenant>/v2.0`). The provider
+   * documents the exact issuer string.
+   */
+  expectedIssuer: string;
+  /**
+   * Expected `aud` claim — typically the OAuth client_id for which
+   * the token was minted.
+   */
+  expectedAudience: string;
+  /**
+   * Clock-skew tolerance in seconds. Default 30 — matches `JwtSigner`'s
+   * post-F9 default and NIST SP 800-63B §5.1.1.2 guidance.
+   */
+  clockToleranceSec?: number;
+}
+
+const DEFAULT_CLOCK_TOLERANCE_SEC = 30;
+
+const jwksCache: Map<string, ReturnType<typeof createRemoteJWKSet>> = new Map();
+
+function jwksFor(uri: string): ReturnType<typeof createRemoteJWKSet> {
+  const cached = jwksCache.get(uri);
+  if (cached) return cached;
+  const set = createRemoteJWKSet(new URL(uri));
+  jwksCache.set(uri, set);
+  return set;
+}
+
+/**
+ * Constant-time string equality. Both inputs must be the same length
+ * to avoid early-return timing leaks. Mismatched lengths return false
+ * immediately — the nonce we generate is a fixed-length base64url
+ * value, so an attacker who supplies a shorter or longer string
+ * always loses on length alone.
+ */
+function constantTimeStringEqual(a: string, b: string): boolean {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) {
+    diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  }
+  return diff === 0;
+}
+
+export async function verifyIdToken(opts: VerifyIdTokenOptions): Promise<JWTPayload> {
+  if (!opts.idToken) throw new AuthenticationError("verifyIdToken: missing idToken");
+  if (!opts.expectedNonce) {
+    throw new AuthenticationError("verifyIdToken: expectedNonce is required");
+  }
+  if (!opts.expectedIssuer) {
+    throw new AuthenticationError("verifyIdToken: expectedIssuer is required");
+  }
+  if (!opts.expectedAudience) {
+    throw new AuthenticationError("verifyIdToken: expectedAudience is required");
+  }
+
+  const key: IdTokenKeyInput = typeof opts.key === "string" ? jwksFor(opts.key) : opts.key;
+  const verifyOpts: JWTVerifyOptions = {
+    issuer: opts.expectedIssuer,
+    audience: opts.expectedAudience,
+    clockTolerance: opts.clockToleranceSec ?? DEFAULT_CLOCK_TOLERANCE_SEC,
+  };
+
+  let payload: JWTPayload;
+  try {
+    const result = await jwtVerify(opts.idToken, key, verifyOpts);
+    payload = result.payload;
+  } catch (err) {
+    throw classifyVerifyError(err);
+  }
+
+  const nonceClaim = payload.nonce;
+  if (typeof nonceClaim !== "string" || nonceClaim.length === 0) {
+    throw new AuthenticationError("verifyIdToken: id_token missing nonce claim");
+  }
+  if (!constantTimeStringEqual(nonceClaim, opts.expectedNonce)) {
+    throw new AuthenticationError("verifyIdToken: nonce mismatch");
+  }
+
+  return payload;
+}
+
+function classifyVerifyError(err: unknown): AuthenticationError {
+  if (err instanceof joseErrors.JWTExpired) {
+    return new AuthenticationError("verifyIdToken: id_token expired");
+  }
+  if (err instanceof joseErrors.JWTClaimValidationFailed) {
+    return new AuthenticationError(`verifyIdToken: claim invalid (${err.claim})`);
+  }
+  if (err instanceof joseErrors.JWSSignatureVerificationFailed) {
+    return new AuthenticationError("verifyIdToken: signature verification failed");
+  }
+  if (err instanceof joseErrors.JWKSNoMatchingKey) {
+    return new AuthenticationError("verifyIdToken: no matching JWKS key");
+  }
+  return new AuthenticationError(
+    `verifyIdToken: ${err instanceof Error ? err.message : String(err)}`,
+  );
+}
+
+/** Exposed for tests; do not depend on this outside the framework. */
+export const _internals = { jwksCache, DEFAULT_CLOCK_TOLERANCE_SEC };