@desplega.ai/agent-swarm 1.119.6 → 1.121.0

package/src/oauth/ensure-token.ts

@@ -1,12 +1,17 @@
 import {
   acquireOAuthRefreshLock,
+  getAuthorizationById,
+  getDefaultAuthorizationIdForProvider,
   getOAuthApp,
-  getOAuthTokens,
-  isTokenExpiringSoon,
+  getOAuthAppById,
+  markAuthorizationRefreshFailed,
+  type OAuthAuthorization,
   releaseOAuthRefreshLock,
+  updateAuthorizationTokens,
 } from "../be/db-queries/oauth";
-import type { OAuthApp, OAuthTokens } from "../tracker/types";
-import { type OAuthProviderConfig, refreshAccessToken } from "./wrapper";
+import type { OAuthApp } from "../tracker/types";
+import { registerVolatileSecret, scrubSecrets } from "../utils/secret-scrubber";
+import { type OAuthProviderConfig, performTokenRefreshRequest } from "./wrapper";
 
 function parseMetadata(metadataJson: string | null | undefined): Record<string, unknown> {
   try {
@@ -31,9 +36,11 @@ function stringRecord(value: unknown): Record<string, string> | undefined {
  */
 export function oauthAppRowToProviderConfig(app: OAuthApp): OAuthProviderConfig {
   const metadata = parseMetadata(app.metadata);
-  const extraParams =
-    stringRecord(metadata.extraParams) ??
-    (typeof metadata.actor === "string" ? { actor: metadata.actor } : undefined);
+  const liftedExtraParams = stringRecord(parseMetadata(app.extraParamsJson));
+  const extraParams = {
+    ...(typeof metadata.actor === "string" ? { actor: metadata.actor } : {}),
+    ...liftedExtraParams,
+  };
 
   return {
     provider: app.provider,
@@ -46,37 +53,66 @@ export function oauthAppRowToProviderConfig(app: OAuthApp): OAuthProviderConfig
       .split(",")
       .map((scope) => scope.trim())
       .filter(Boolean),
-    extraParams,
-    // Standard OAuth wants space-separated scopes; the wrapper's comma
-    // default exists only for Linear, which has its own dedicated flow.
-    scopeSeparator: " ",
-    ...(metadata.tokenAuthStyle === "basic" ? { tokenAuthStyle: "basic" as const } : {}),
-    ...(metadata.tokenBodyFormat === "json" ? { tokenBodyFormat: "json" as const } : {}),
-    requiresRefreshTokenRotation: app.provider === "jira",
+    extraParams: Object.keys(extraParams).length > 0 ? extraParams : undefined,
+    scopeSeparator: app.scopeSeparator,
+    tokenAuthStyle: app.tokenAuthStyle,
+    tokenBodyFormat: app.tokenBodyFormat,
+    requiresRefreshTokenRotation: app.requiresRefreshTokenRotation,
   };
 }
 
-const refreshLocks = new Map<string, Promise<void>>();
-const REFRESH_LOCK_TTL_MS = 2 * 60 * 1000;
-const REFRESH_LOCK_WAIT_MS = 30 * 1000;
-const REFRESH_LOCK_POLL_MS = 250;
+// ─── Typed refresh error ─────────────────────────────────────────────────────
+
+export type OAuthRefreshFailureReason = "refresh_rejected" | "lock_timeout" | "no_refresh_token";
 
 /**
- * Build an OAuthProviderConfig from the oauth_apps table for any provider.
+ * Thrown by the authorization-keyed refresh path when an expiring authorization
+ * cannot be refreshed. Carries structured context so downstream surfaces (the
+ * credential broker → script failedBindings, HTTP endpoints, alerting) can
+ * report *which* authorization broke and *why* instead of a silent drop.
+ *
+ * Shape precedent: {@link CodexOAuthRefreshError} in
+ * src/providers/codex-oauth/storage.ts.
  */
-function getOAuthConfig(provider: string): OAuthProviderConfig | null {
-  const app = getOAuthApp(provider);
-  return app ? oauthAppRowToProviderConfig(app) : null;
+export class OAuthRefreshError extends Error {
+  constructor(
+    public readonly authorizationId: string,
+    public readonly appId: string,
+    public readonly reason: OAuthRefreshFailureReason,
+    public readonly authorizationLabel: string,
+    message?: string,
+  ) {
+    super(message ?? `OAuth authorization '${authorizationLabel}' refresh failed (${reason})`);
+    this.name = "OAuthRefreshError";
+  }
 }
 
-async function withProviderRefreshLock<T>(provider: string, fn: () => Promise<T>): Promise<T> {
-  const previous = refreshLocks.get(provider) ?? Promise.resolve();
+function authorizationLabelFor(app: OAuthApp, authorization: OAuthAuthorization): string {
+  const base = app.displayName?.trim() || app.provider;
+  return authorization.label && authorization.label !== "default"
+    ? `${base} (${authorization.label})`
+    : base;
+}
+
+// ─── Refresh locks (in-process queue + cross-process DB lock) ─────────────────
+
+const refreshLocks = new Map<string, Promise<void>>();
+const REFRESH_LOCK_TTL_MS = 2 * 60 * 1000;
+const REFRESH_LOCK_WAIT_MS = 30 * 1000;
+const REFRESH_LOCK_POLL_MS = 250;
+const DEFAULT_REFRESH_BUFFER_MS = 5 * 60 * 1000;
+
+async function withAuthorizationRefreshLock<T>(
+  authorizationId: string,
+  fn: () => Promise<T>,
+): Promise<T> {
+  const previous = refreshLocks.get(authorizationId) ?? Promise.resolve();
   let release!: () => void;
   const current = new Promise<void>((resolve) => {
     release = resolve;
   });
   const next = previous.catch(() => undefined).then(() => current);
-  refreshLocks.set(provider, next);
+  refreshLocks.set(authorizationId, next);
 
   await previous.catch(() => undefined);
 
@@ -84,8 +120,8 @@ async function withProviderRefreshLock<T>(provider: string, fn: () => Promise<T>
     return await fn();
   } finally {
     release();
-    if (refreshLocks.get(provider) === next) {
-      refreshLocks.delete(provider);
+    if (refreshLocks.get(authorizationId) === next) {
+      refreshLocks.delete(authorizationId);
     }
   }
 }
@@ -94,120 +130,307 @@ function sleep(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
-function tokenRowChanged(current: OAuthTokens | null, observed: OAuthTokens | null): boolean {
-  if (!observed) return current !== null;
-  if (!current) return true;
-  return (
-    current.accessToken !== observed.accessToken ||
-    current.refreshToken !== observed.refreshToken ||
-    current.expiresAt !== observed.expiresAt
-  );
-}
-
 /**
- * Ensure a valid OAuth token exists for the given provider.
- * If the token is expiring soon, attempt to refresh it.
- * Call this before any API interaction with an OAuth-protected service.
+ * An authorization needs a refresh when it is expiring within `bufferMs`, is
+ * already in a non-terminal broken state (`refresh-failed` / `expired`), or
+ * when `force` is set — so the sweep and on-demand resolution retry broken
+ * rows each pass and self-heal once the provider recovers.
  *
- * Reactive variant — never throws. Refresh failures are logged so a single
- * dead-token incident doesn't tear down an unrelated request path. Use
- * {@link ensureTokenOrThrow} from keepalive contexts where you want a dead
- * refresh token to surface as an alert.
- *
- * @param bufferMs - How far ahead to check for expiry. Default 5 min (reactive use).
- *                   Keepalive callers should pass a larger value (e.g. 13h) to force
- *                   a proactive refresh well before the token actually expires.
+ * A NULL `expiresAt` means the provider issued a non-expiring token (e.g. the
+ * GitHub OAuth preset, which has no refresh token). It is treated as "does not
+ * expire / never proactively refresh" — NOT as expired. Refreshing it would
+ * mark it `refresh-failed` (no refresh token to rotate) while the token is
+ * still valid. Only an explicit `force` (manual refresh) or a broken status
+ * refreshes such a row.
  */
-export async function ensureToken(provider: string, bufferMs?: number): Promise<void> {
-  try {
-    await ensureTokenOrThrow(provider, bufferMs);
-  } catch (err) {
-    console.error(
-      `[OAuth] Failed to refresh ${provider} token:`,
-      err instanceof Error ? err.message : err,
-    );
-  }
+function authorizationNeedsRefresh(
+  authorization: OAuthAuthorization,
+  bufferMs = DEFAULT_REFRESH_BUFFER_MS,
+  force = false,
+): boolean {
+  if (authorization.status === "refresh-failed" || authorization.status === "expired") return true;
+  if (force) return true;
+  if (!authorization.expiresAt) return false;
+  const expiresAt = new Date(authorization.expiresAt).getTime();
+  if (Number.isNaN(expiresAt)) return true;
+  return expiresAt - Date.now() < bufferMs;
 }
 
-/**
- * Buffer large enough that any stored expiry counts as "expiring soon",
- * turning {@link ensureTokenOrThrow} into an unconditional refresh.
- */
-const FORCE_REFRESH_BUFFER_MS = 1000 * 60 * 60 * 24 * 365 * 100; // ~100 years
+// ─── Refresh notification (cached provider-client invalidation) ──────────────
+//
+// A background sweep or another request path can rotate an authorization's
+// access token while a module-level SDK client still holds the stale one (the
+// Linear `LinearClient` cache is the canonical case). Listeners registered here
+// fire after every successful persist so those caches can invalidate — closing
+// the staleness gap that used to require a reactive `resetLinearClient()` call
+// on the same code path as the refresh.
+
+export interface AuthorizationRefreshedEvent {
+  authorizationId: string;
+  appId: string;
+  provider: string;
+}
+
+type AuthorizationRefreshedListener = (event: AuthorizationRefreshedEvent) => void;
+
+const authorizationRefreshedListeners = new Set<AuthorizationRefreshedListener>();
 
 /**
- * Force a refresh of the stored token regardless of remaining lifetime,
- * going through the exact same in-process queue + DB refresh-lock path as
- * {@link ensureTokenOrThrow}. Used by the manual refresh endpoint and the
- * background refresh sweep's keep-alive path.
- *
- * Like {@link ensureTokenOrThrow}, stays silent (no throw) when the provider
- * has no app config or no stored refresh token — callers that need those to
- * be errors must pre-check.
+ * Subscribe to successful authorization token refreshes. Returns an
+ * unsubscribe function. Listeners must be cheap + non-throwing (throws are
+ * caught and logged so one bad listener can't fail a refresh).
  */
-export async function forceRefreshTokenOrThrow(provider: string): Promise<void> {
-  await ensureTokenOrThrow(provider, FORCE_REFRESH_BUFFER_MS);
+export function onAuthorizationRefreshed(listener: AuthorizationRefreshedListener): () => void {
+  authorizationRefreshedListeners.add(listener);
+  return () => {
+    authorizationRefreshedListeners.delete(listener);
+  };
 }
 
+function notifyAuthorizationRefreshed(event: AuthorizationRefreshedEvent): void {
+  for (const listener of authorizationRefreshedListeners) {
+    try {
+      listener(event);
+    } catch (err) {
+      console.error(
+        scrubSecrets(
+          `[OAuth] authorization-refreshed listener failed for ${event.provider}: ${
+            err instanceof Error ? err.message : String(err)
+          }`,
+        ),
+      );
+    }
+  }
+}
+
+// ─── Authorization-keyed core ────────────────────────────────────────────────
+
 /**
- * Strict variant of {@link ensureToken}: throws on refresh failure of a
- * configured provider so callers (keepalive, alerting) can react.
+ * Strict authorization-keyed refresh. Refreshes the given authorization if it
+ * is expiring (or already broken), persisting `status='active'` +
+ * `lastRefreshedAt` on success and `status='refresh-failed'` +
+ * `lastErrorMessage` (scrubbed) + a thrown {@link OAuthRefreshError} on
+ * failure.
  *
- * Stays silent (no throw) when the provider isn't configured or no refresh
- * token is stored — those are "not connected" states, not failures, and
- * shouldn't page anyone.
+ * Stays silent (no throw, no status change) when the authorization is missing,
+ * revoked, or has no provider-facing app config — those are "not connected"
+ * states, not refresh failures.
  */
-export async function ensureTokenOrThrow(provider: string, bufferMs?: number): Promise<void> {
-  if (!isTokenExpiringSoon(provider, bufferMs)) return;
-  const observedTokens = getOAuthTokens(provider);
+export async function ensureAuthorizationTokenOrThrow(
+  authorizationId: string,
+  bufferMs?: number,
+  force = false,
+): Promise<void> {
+  const initial = getAuthorizationById(authorizationId);
+  if (!initial || initial.status === "revoked") return;
+  if (!authorizationNeedsRefresh(initial, bufferMs, force)) return;
 
-  await withProviderRefreshLock(provider, async () => {
+  await withAuthorizationRefreshLock(authorizationId, async () => {
     const waitStartedAt = Date.now();
 
-    while (isTokenExpiringSoon(provider, bufferMs)) {
-      const tokens = getOAuthTokens(provider);
-      if (tokenRowChanged(tokens, observedTokens)) return;
+    while (true) {
+      const current = getAuthorizationById(authorizationId);
+      if (!current || current.status === "revoked") return;
+      // Another caller refreshed (tokenVersion bumped) since this call loaded
+      // the row — its work satisfies ours. Without this check a waiter that
+      // force-refreshes would rotate again immediately after the winner,
+      // burning provider refresh calls.
+      if (current.tokenVersion !== initial.tokenVersion) return;
+      if (!authorizationNeedsRefresh(current, bufferMs, force)) return;
+
+      const app = getOAuthAppById(current.appId);
+      // No provider-facing app config (missing, or a DCR/MCP app): nothing this
+      // path can refresh — leave status untouched.
+      if (!app || app.mcpServerId !== null) return;
 
-      const config = getOAuthConfig(provider);
-      if (!config || !tokens?.refreshToken) {
-        console.warn(
-          `[OAuth] ${provider} token expiring but cannot refresh (missing config or refresh token)`,
-        );
-        return;
+      if (!current.refreshToken) {
+        const label = authorizationLabelFor(app, current);
+        const message = `OAuth authorization '${label}' cannot refresh: no refresh token stored`;
+        markAuthorizationRefreshFailed(authorizationId, message);
+        throw new OAuthRefreshError(authorizationId, app.id, "no_refresh_token", label, message);
       }
 
-      const lockOwner = acquireOAuthRefreshLock(provider, REFRESH_LOCK_TTL_MS);
+      const lockOwner = acquireOAuthRefreshLock(`authz:${authorizationId}`, REFRESH_LOCK_TTL_MS);
       if (!lockOwner) {
         if (Date.now() - waitStartedAt > REFRESH_LOCK_WAIT_MS) {
-          throw new Error(`Timed out waiting for ${provider} OAuth token refresh lock`);
+          const label = authorizationLabelFor(app, current);
+          const message = `Timed out waiting for OAuth refresh lock for '${label}'`;
+          markAuthorizationRefreshFailed(authorizationId, message);
+          throw new OAuthRefreshError(authorizationId, app.id, "lock_timeout", label, message);
         }
         await sleep(REFRESH_LOCK_POLL_MS);
         continue;
       }
 
       try {
-        const lockedTokens = getOAuthTokens(provider);
-        if (
-          !isTokenExpiringSoon(provider, bufferMs) ||
-          tokenRowChanged(lockedTokens, observedTokens)
-        ) {
-          return;
-        }
+        // Re-read under the cross-process lock: another node may have refreshed
+        // (tokenVersion bumped → no longer expiring) or revoked while we waited.
+        const locked = getAuthorizationById(authorizationId);
+        if (!locked || locked.status === "revoked") return;
+        if (locked.tokenVersion !== initial.tokenVersion) return;
+        if (!authorizationNeedsRefresh(locked, bufferMs, force)) return;
+
+        const lockedApp = getOAuthAppById(locked.appId);
+        if (!lockedApp || lockedApp.mcpServerId !== null) return;
 
-        const lockedConfig = getOAuthConfig(provider);
-        if (!lockedConfig || !lockedTokens?.refreshToken) {
-          console.warn(
-            `[OAuth] ${provider} token expiring but cannot refresh (missing config or refresh token)`,
+        if (!locked.refreshToken) {
+          const label = authorizationLabelFor(lockedApp, locked);
+          const message = `OAuth authorization '${label}' cannot refresh: no refresh token stored`;
+          markAuthorizationRefreshFailed(authorizationId, message);
+          throw new OAuthRefreshError(
+            authorizationId,
+            lockedApp.id,
+            "no_refresh_token",
+            label,
+            message,
           );
-          return;
         }
 
-        await refreshAccessToken(lockedConfig, lockedTokens.refreshToken);
-        console.log(`[OAuth] ${provider} token refreshed successfully`);
-        return;
+        const config = oauthAppRowToProviderConfig(lockedApp);
+        try {
+          const refreshed = await performTokenRefreshRequest(config, locked.refreshToken);
+          const persisted = updateAuthorizationTokens(authorizationId, {
+            accessToken: refreshed.accessToken,
+            refreshToken: refreshed.refreshToken ?? locked.refreshToken,
+            expiresAt: refreshed.expiresAt,
+            scope: refreshed.scope ?? null,
+            expectedTokenVersion: locked.tokenVersion,
+          });
+          if (!persisted) {
+            // Optimistic-concurrency loss to a concurrent writer — re-evaluate.
+            continue;
+          }
+          notifyAuthorizationRefreshed({
+            authorizationId,
+            appId: lockedApp.id,
+            provider: lockedApp.provider,
+          });
+          return;
+        } catch (err) {
+          const label = authorizationLabelFor(lockedApp, locked);
+          // The provider token endpoint can echo the submitted refresh_token /
+          // client_secret back in an invalid_grant body (which lands in
+          // err.message). scrubSecrets only knows env/vendor-fixed shapes, so
+          // register this attempt's own secrets as volatile before scrubbing —
+          // otherwise they'd be persisted to lastErrorMessage and surfaced in
+          // the UI tooltip.
+          if (locked.refreshToken)
+            registerVolatileSecret(locked.refreshToken, "oauth-refresh-token");
+          if (locked.accessToken) registerVolatileSecret(locked.accessToken, "oauth-access-token");
+          if (lockedApp.clientSecret)
+            registerVolatileSecret(lockedApp.clientSecret, "oauth-client-secret");
+          const message = scrubSecrets(err instanceof Error ? err.message : String(err));
+          markAuthorizationRefreshFailed(authorizationId, message);
+          if (err instanceof OAuthRefreshError) throw err;
+          throw new OAuthRefreshError(
+            authorizationId,
+            lockedApp.id,
+            "refresh_rejected",
+            label,
+            message,
+          );
+        }
       } finally {
-        releaseOAuthRefreshLock(provider, lockOwner);
+        releaseOAuthRefreshLock(`authz:${authorizationId}`, lockOwner);
       }
     }
   });
 }
+
+/**
+ * Reactive authorization-keyed refresh — never throws. Refresh failures are
+ * persisted (`refresh-failed`) by {@link ensureAuthorizationTokenOrThrow} and
+ * logged here so a single dead-token incident doesn't tear down an unrelated
+ * request path.
+ */
+export async function ensureAuthorizationToken(
+  authorizationId: string,
+  bufferMs?: number,
+): Promise<void> {
+  try {
+    await ensureAuthorizationTokenOrThrow(authorizationId, bufferMs);
+  } catch (err) {
+    console.error(
+      scrubSecrets(
+        `[OAuth] Failed to refresh authorization ${authorizationId}: ${err instanceof Error ? err.message : String(err)}`,
+      ),
+    );
+  }
+}
+
+/**
+ * Force a refresh of a specific authorization regardless of remaining lifetime,
+ * through the same lock + persistence path. Used by the manual refresh endpoint
+ * and the background sweep.
+ */
+export async function forceRefreshAuthorizationOrThrow(authorizationId: string): Promise<void> {
+  // `force` refreshes regardless of remaining lifetime — including non-expiring
+  // (NULL expiresAt) tokens, which the buffer path deliberately skips.
+  await ensureAuthorizationTokenOrThrow(authorizationId, undefined, true);
+}
+
+// ─── Provider-string compatibility wrappers ──────────────────────────────────
+//
+// Resolve a provider to its migrated `default` authorization and delegate to
+// the authorization-keyed core. Tracker callers migrate off these in step-8.
+
+/**
+ * Reactive per-provider refresh — never throws. See {@link ensureToken} history:
+ * refresh failures are logged, not surfaced.
+ */
+export async function ensureToken(provider: string, bufferMs?: number): Promise<void> {
+  try {
+    await ensureTokenOrThrow(provider, bufferMs);
+  } catch (err) {
+    console.error(
+      `[OAuth] Failed to refresh ${provider} token:`,
+      err instanceof Error ? err.message : err,
+    );
+  }
+}
+
+/**
+ * Strict per-provider refresh. Delegates to the default authorization.
+ *
+ * Stays silent (no throw) when the provider isn't connected (no app / no
+ * default authorization) or the default authorization has no stored refresh
+ * token — those are "not connected" states, preserved for legacy tracker /
+ * oauth-access-token callers. A genuine provider rejection still throws.
+ */
+export async function ensureTokenOrThrow(provider: string, bufferMs?: number): Promise<void> {
+  const authorizationId = getDefaultAuthorizationIdForProvider(provider);
+  if (!authorizationId) return;
+  try {
+    await ensureAuthorizationTokenOrThrow(authorizationId, bufferMs);
+  } catch (err) {
+    if (err instanceof OAuthRefreshError && err.reason === "no_refresh_token") {
+      // Legacy provider-string semantics: a provider with no refresh token is
+      // "not connected", not a refresh failure — stay silent.
+      return;
+    }
+    throw err;
+  }
+}
+
+/**
+ * Force-refresh a provider's default authorization. Silent when not connected.
+ */
+export async function forceRefreshTokenOrThrow(provider: string): Promise<void> {
+  const authorizationId = getDefaultAuthorizationIdForProvider(provider);
+  if (!authorizationId) return;
+  try {
+    await forceRefreshAuthorizationOrThrow(authorizationId);
+  } catch (err) {
+    if (err instanceof OAuthRefreshError && err.reason === "no_refresh_token") return;
+    throw err;
+  }
+}
+
+/**
+ * Build an OAuthProviderConfig from the oauth_apps table for any provider.
+ * Retained for callers that only need the provider config (not a refresh).
+ */
+export function getOAuthConfig(provider: string): OAuthProviderConfig | null {
+  const app = getOAuthApp(provider);
+  return app ? oauthAppRowToProviderConfig(app) : null;
+}

package/src/oauth/identity-capture.ts

@@ -0,0 +1,103 @@
+import { scrubSecrets } from "@/utils/secret-scrubber";
+import { assertOAuthEgressUrlSafe } from "./app-validation";
+
+/**
+ * Best-effort account identity captured after a successful token exchange.
+ * Display-only — never used for authorization decisions.
+ */
+export interface CapturedIdentity {
+  accountEmail: string | null;
+  /** JSON string of the raw identity claims we surfaced (email/login/sub). */
+  identityJson: string;
+}
+
+const IDENTITY_FETCH_TIMEOUT_MS = 5_000;
+
+function pickString(value: unknown): string | null {
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+
+/** Extract the display-relevant identity fields from a claims/userinfo object. */
+function extractIdentity(source: Record<string, unknown>): CapturedIdentity | null {
+  const email = pickString(source.email);
+  const login = pickString(source.login) ?? pickString(source.preferred_username);
+  const sub = pickString(source.sub) ?? pickString(source.id);
+  if (!email && !login && !sub) return null;
+  const claims: Record<string, string> = {};
+  if (email) claims.email = email;
+  if (login) claims.login = login;
+  if (sub) claims.sub = sub;
+  return { accountEmail: email, identityJson: JSON.stringify(claims) };
+}
+
+/** Decode a JWT id_token payload without signature verification (display-only). */
+function decodeIdToken(idToken: string): CapturedIdentity | null {
+  const parts = idToken.split(".");
+  const payloadSegment = parts[1];
+  if (!payloadSegment) return null;
+  try {
+    const payload = Buffer.from(
+      payloadSegment.replace(/-/g, "+").replace(/_/g, "/"),
+      "base64",
+    ).toString("utf8");
+    const parsed = JSON.parse(payload);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+    return extractIdentity(parsed as Record<string, unknown>);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Capture the connected account's identity after a token exchange. Prefers a
+ * `userinfoUrl` probe (Bearer), falling back to decoding an OIDC `id_token`.
+ * All failures are swallowed (scrubbed log) — identity capture must NEVER fail
+ * the OAuth callback. Returns null when nothing could be captured.
+ */
+export async function captureIdentity(input: {
+  userinfoUrl?: string | null;
+  accessToken: string;
+  idToken?: string | null;
+}): Promise<CapturedIdentity | null> {
+  try {
+    if (input.userinfoUrl) {
+      // Fail-closed host re-check at egress: we are about to send a live bearer.
+      assertOAuthEgressUrlSafe(input.userinfoUrl);
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), IDENTITY_FETCH_TIMEOUT_MS);
+      try {
+        const response = await fetch(input.userinfoUrl, {
+          headers: {
+            authorization: `Bearer ${input.accessToken}`,
+            accept: "application/json",
+          },
+          signal: controller.signal,
+          // Never follow a redirect: a public userinfoUrl could 302 the bearer
+          // toward an internal metadata endpoint. A 3xx is not `.ok`, so it is
+          // simply ignored below.
+          redirect: "manual",
+        });
+        if (response.ok) {
+          const data = (await response.json()) as unknown;
+          if (data && typeof data === "object" && !Array.isArray(data)) {
+            const identity = extractIdentity(data as Record<string, unknown>);
+            if (identity) return identity;
+          }
+        }
+      } finally {
+        clearTimeout(timer);
+      }
+    }
+
+    if (input.idToken) {
+      return decodeIdToken(input.idToken);
+    }
+  } catch (err) {
+    console.warn(
+      scrubSecrets(
+        `[oauth] identity capture failed: ${err instanceof Error ? err.message : String(err)}`,
+      ),
+    );
+  }
+  return null;
+}