cursedbelt-server 4.13.1 → 4.14.0

package/src/server/google-oauth/googleOAuth.ts

@@ -0,0 +1,750 @@
+/**
+ * `cursedbelt-server/google-oauth` — the ONE Google OAuth implementation in this generation:
+ * consent URL, authorization-code exchange, refresh-token exchange, revocation, credential
+ * reading from env + a 0600 env file, a cached access-token minter, a live credential probe
+ * and the 403-to-remedy sentence.
+ *
+ * ── Why it is here ──────────────────────────────────────────────────────────
+ * Two apps held byte-for-byte copies of it (task 099, census entry 407), one of which had
+ * already forked ahead of the other with the credential-resolution half. Two copies of a
+ * credential parser are two answers to "which env keys are canonical", and the drift costs a
+ * sign-in. This file is the union of both, with the stricter body wherever they differed.
+ *
+ * ── Nothing here knows who is calling ───────────────────────────────────────
+ * No app name, no hostname, no secrets path, no env-file location and no scope list is
+ * baked in. The caller supplies the secrets file, the env-var names it accepts
+ * ({@link CredentialKeys}), the label a failure sentence names and the remedy it offers.
+ *
+ * ── Two ways a refresh token arrives, one exchange ──────────────────────────
+ *   · {@link readGoogleCredentials} + {@link createGoogleTokenMinter} serve a consumer whose
+ *     refresh token is a 0600 file on the machine, minted once by hand.
+ *   · {@link buildConsentUrl} + {@link exchangeAuthCode} serve a consumer that obtains the
+ *     refresh token AT RUNTIME from a browser consent and stores it itself. Feed it straight
+ *     back in — `createGoogleTokenMinter({ credentials })` — so a consenting app still has
+ *     exactly one `grant_type=refresh_token` POST.
+ *
+ * ── Failure is always LOUD, and never a secret ──────────────────────────────
+ * Every failure is a typed result carrying the exact remedy; nothing here throws. A
+ * credential that cannot be read, a token Google refuses, or a scope that was never granted
+ * must NEVER look like "nothing to report". No credential value is ever logged, returned in
+ * an error string, or thrown — Google's `error_description` is echoed because it describes
+ * the REQUEST, never the secret.
+ *
+ * ── A leaf ──────────────────────────────────────────────────────────────────
+ * One file, node builtins only, listed in `leafSubpathsImportNothing.spec.ts`. It is one file
+ * on purpose: the leaf fixture copies exactly the exported file, so a sibling import would be
+ * a red, and a single module cannot have the import cycle the old three-file split existed to
+ * avoid.
+ */
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import path from 'node:path';
+
+// ─── Endpoints ───────────────────────────────────────────────────────────────
+
+export const GOOGLE_TOKEN_ENDPOINT = 'https://oauth2.googleapis.com/token';
+export const GOOGLE_AUTH_ENDPOINT = 'https://accounts.google.com/o/oauth2/v2/auth';
+export const GOOGLE_REVOKE_ENDPOINT = 'https://oauth2.googleapis.com/revoke';
+
+// ─── Shared shapes ───────────────────────────────────────────────────────────
+
+/**
+ * Deliberately looser than `typeof fetch`.
+ *
+ * Every caller here passes one URL string and an init, and `typeof fetch` also carries Bun's
+ * `preconnect` property — so typing the seam as `typeof fetch` makes `async () =>
+ * Response.json(…)` a compile error in every test that fakes it, for a capability no code
+ * path uses.
+ */
+export type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;
+
+/**
+ * An environment to read credentials from. `process.env` satisfies it, and so does a plain
+ * object in a test — deliberately not `NodeJS.ProcessEnv`, so a consumer's declarations do not
+ * need `@types/node` to type-check against this one.
+ */
+export type EnvLike = Readonly<Record<string, string | undefined>>;
+
+/** `process.env` where there is a `process`; an empty env where there is not. */
+const ambientEnv = (): EnvLike => (typeof process !== 'undefined' ? process.env : {});
+
+export interface GoogleCredentials {
+  clientId: string;
+  clientSecret: string;
+  refreshToken: string;
+}
+
+/**
+ * WHICH KIND of `unavailable`, structurally rather than by reading the sentence.
+ *
+ * 🔴 A caller that treats these two alike rings the wrong alarm. `refused` is Google saying no
+ * to a credential the owner has to act on; `transport` is a machine that could not reach
+ * Google — a laptop on a train — and a bell claiming a dead grant every time the wifi drops is
+ * how a real credential alarm gets ignored.
+ */
+export type UnavailableCause = 'transport' | 'refused';
+
+/** Everything below `ok` carries the exact remedy — never a quiet empty result. */
+export type TokenResult =
+  | { status: 'ok'; accessToken: string; grantedScopes: string[] }
+  | { status: 'unconfigured'; reason: string; fix: string }
+  | { status: 'unavailable'; reason: string; fix: string; cause?: UnavailableCause };
+
+// ─── Env-file reading ────────────────────────────────────────────────────────
+
+/** `~/x` → `<home>/x`. Anything else is returned unchanged. */
+export const expandTilde = (p: string): string =>
+  p.startsWith('~/') ? path.join(homedir(), p.slice(2)) : p;
+
+/**
+ * Parse a `KEY=value` env file, tolerating quotes, blanks, `export`, `#` comments and CRLF.
+ *
+ * 🔴 CRLF is split on, not trimmed afterwards. Both app copies split on `\n` alone, and `.`
+ * does not match `\r`, so `(.*)$` failed on EVERY line of a CRLF file: a secrets file saved by
+ * a Windows editor parsed to `{}` and read as "no credential on this machine" — `unconfigured`,
+ * with the setup remedy, for a file that held all three values. Pinned in the spec.
+ */
+export function parseEnvFile(text: string): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const line of text.split(/\r?\n/)) {
+    if (/^\s*#/.test(line)) continue;
+    const m = /^\s*(?:export\s+)?([A-Z0-9_]+)\s*=\s*(.*)$/.exec(line);
+    if (m?.[1]) out[m[1]] = (m[2] ?? '').trim().replace(/^["']|["']$/g, '');
+  }
+  return out;
+}
+
+/** The parsed secrets file, or `{}` when there is none or it cannot be read. Never throws. */
+const readEnvFile = (secretsFile: string | undefined): Record<string, string> => {
+  if (!secretsFile) return {};
+  try {
+    return parseEnvFile(readFileSync(expandTilde(secretsFile), 'utf8'));
+  } catch {
+    return {};
+  }
+};
+
+/** Read any other key — env first, then the same secrets file (an API key, an address). */
+export function readSecret(name: string, options: { env?: EnvLike; secretsFile?: string } = {}): string {
+  const fromEnv = (options.env ?? ambientEnv())[name]?.trim();
+  if (fromEnv) return fromEnv;
+  return readEnvFile(options.secretsFile)[name]?.trim() ?? '';
+}
+
+// ─── Credential resolution ───────────────────────────────────────────────────
+
+/**
+ * The env-var names a caller will accept for each half of the credential, most canonical
+ * FIRST. A consumer with historical aliases lists them after its canonical names; a new
+ * consumer passes one name each.
+ */
+export interface CredentialKeys {
+  clientId: readonly string[];
+  clientSecret: readonly string[];
+  refreshToken: readonly string[];
+}
+
+export const CANONICAL_CREDENTIAL_KEYS: CredentialKeys = {
+  clientId: ['GOOGLE_OAUTH_CLIENT_ID'],
+  clientSecret: ['GOOGLE_OAUTH_CLIENT_SECRET'],
+  refreshToken: ['GOOGLE_OAUTH_REFRESH_TOKEN'],
+};
+
+export interface ReadCredentialsOptions {
+  env?: EnvLike;
+  /** A 0600 file outside every checkout. `~` is expanded. The caller decides where it is. */
+  secretsFile?: string;
+  keys?: CredentialKeys;
+}
+
+/** Which name supplied one half of a credential, and where that name was read from. */
+export interface CredentialSource {
+  name: string;
+  from: 'env' | 'file';
+}
+
+/**
+ * WHICH NAMES a credential actually came out of.
+ *
+ * 🔴 Why this is not a debugging nicety. A credential list is a PREFERENCE order, so a value
+ * under the preferred name wins merely by existing — it is never checked against the value
+ * under the alias. Measured 2026-09-15: one 0600 file held two different refresh tokens for
+ * the identical client and account, the canonical name was dead (`invalid_grant`) and the
+ * alias beside it exchanged fine. Every call took the dead one and reported "the grant has
+ * been revoked, re-consent" — a sentence that was false, sent the owner to a browser, and
+ * cost forty minutes of not believing it. `shadowed` makes that a five-second diagnosis.
+ */
+export interface GoogleCredentialResolution {
+  /** The same value `readGoogleCredentials` returns — null if any half is missing. */
+  credentials: GoogleCredentials | null;
+  /** The name that supplied each half, or null when no listed name had a value. */
+  used: {
+    clientId: CredentialSource | null;
+    clientSecret: CredentialSource | null;
+    refreshToken: CredentialSource | null;
+  };
+  /** Names holding a value that lost to an earlier one. Never a value, only a name. */
+  shadowed: {
+    clientId: string[];
+    clientSecret: string[];
+    refreshToken: string[];
+  };
+  /** Every listed name for a half that nothing supplied — the `unconfigured` detail. */
+  missing: string[];
+}
+
+/**
+ * Read a Google OAuth credential AND report which names carried it.
+ *
+ * Precedence: env overrides the secrets file, and earlier key names override later aliases.
+ */
+export function resolveGoogleCredentials(options: ReadCredentialsOptions = {}): GoogleCredentialResolution {
+  const env = options.env ?? ambientEnv();
+  const keys = options.keys ?? CANONICAL_CREDENTIAL_KEYS;
+  const fromFile = readEnvFile(options.secretsFile);
+  const read = (names: readonly string[]): { value: string; used: CredentialSource | null; shadowed: string[] } => {
+    let used: CredentialSource | null = null;
+    let value = '';
+    const shadowed: string[] = [];
+    for (const n of names) {
+      const fromEnv = env[n]?.trim();
+      const v = fromEnv || fromFile[n]?.trim();
+      if (!v) continue;
+      // The FIRST name that has a value wins. The rest are recorded rather than discarded —
+      // that list is the whole diagnosis when Google refuses the winner.
+      if (used === null) {
+        used = { name: n, from: fromEnv ? 'env' : 'file' };
+        value = v;
+      } else {
+        shadowed.push(n);
+      }
+    }
+    return { value, used, shadowed };
+  };
+  const clientId = read(keys.clientId);
+  const clientSecret = read(keys.clientSecret);
+  const refreshToken = read(keys.refreshToken);
+  const complete = Boolean(clientId.value && clientSecret.value && refreshToken.value);
+  return {
+    credentials: complete
+      ? { clientId: clientId.value, clientSecret: clientSecret.value, refreshToken: refreshToken.value }
+      : null,
+    used: { clientId: clientId.used, clientSecret: clientSecret.used, refreshToken: refreshToken.used },
+    shadowed: {
+      clientId: clientId.shadowed,
+      clientSecret: clientSecret.shadowed,
+      refreshToken: refreshToken.shadowed,
+    },
+    missing: [
+      ...(clientId.used ? [] : keys.clientId),
+      ...(clientSecret.used ? [] : keys.clientSecret),
+      ...(refreshToken.used ? [] : keys.refreshToken),
+    ],
+  };
+}
+
+/**
+ * Read a Google OAuth credential — env overriding the secrets file, and earlier key names
+ * overriding later aliases.
+ *
+ * Returns null when any of the three is missing. A PARTIAL credential is the same as none:
+ * two of three cannot mint a token, and treating it as present would turn a setup mistake
+ * into an `unavailable` ("Google refused it") instead of the `unconfigured` ("you have not
+ * finished setting it up") that names the real fix.
+ */
+export function readGoogleCredentials(options: ReadCredentialsOptions = {}): GoogleCredentials | null {
+  return resolveGoogleCredentials(options).credentials;
+}
+
+// ─── Consent + token endpoint ────────────────────────────────────────────────
+
+export interface ConsentUrlOptions {
+  clientId: string;
+  /**
+   * Must match an Authorized redirect URI on the OAuth client EXACTLY — Google compares the
+   * string, not the URL. A trailing slash is a different URI.
+   */
+  redirectUri: string;
+  scopes: readonly string[];
+  /** The caller's CSRF/binding token. Google hands it back on the callback verbatim. */
+  state: string;
+  /**
+   * `consent` (the default) forces Google to re-issue a refresh token.
+   *
+   * 🔴 Not a preference. Google issues `refresh_token` only on the FIRST consent for a
+   * client+account pair; a second connect without this returns an access token and nothing
+   * else, so an app that stored only what arrived would be connected for an hour and then
+   * permanently unable to refresh.
+   */
+  prompt?: 'consent' | 'select_account' | 'none';
+}
+
+/** The URL to send the browser to. Pure — no network, so a caller can test its own wiring. */
+export function buildConsentUrl(options: ConsentUrlOptions): string {
+  const params = new URLSearchParams({
+    client_id: options.clientId,
+    redirect_uri: options.redirectUri,
+    response_type: 'code',
+    scope: options.scopes.join(' '),
+    // Without `offline` Google issues no refresh token at all and the grant dies with the
+    // first access token.
+    access_type: 'offline',
+    include_granted_scopes: 'true',
+    prompt: options.prompt ?? 'consent',
+    state: options.state,
+  });
+  return `${GOOGLE_AUTH_ENDPOINT}?${params.toString()}`;
+}
+
+export interface ExchangeOptions {
+  clientId: string;
+  clientSecret: string;
+  redirectUri: string;
+  code: string;
+  fetchImpl?: FetchLike;
+  timeoutMs?: number;
+}
+
+export type AuthCodeResult =
+  | {
+      status: 'ok';
+      accessToken: string;
+      /**
+       * Absent when Google chose not to re-issue one. A caller that already holds a refresh
+       * token for this account must KEEP it rather than storing an empty string — see
+       * {@link ConsentUrlOptions.prompt}.
+       */
+      refreshToken?: string;
+      expiresInSeconds: number;
+      grantedScopes: string[];
+    }
+  | {
+      status: 'unavailable';
+      reason: string;
+      fix: string;
+      /** See {@link UnavailableCause}. Always set by this module; optional in the type. */
+      cause?: UnavailableCause;
+    };
+
+/**
+ * The one POST to Google's token endpoint, whichever grant is being exercised.
+ *
+ * Both grants send form-encoded parameters to the same URL and get back the same body shape,
+ * so they share a reader. What differs is the SENTENCE a failure produces, which is why the
+ * remedies are parameters.
+ */
+async function postTokenRequest(
+  params: Record<string, string>,
+  options: {
+    fetchImpl?: FetchLike;
+    timeoutMs?: number;
+    /** e.g. "exchange the consent code" — completes "could not reach Google to …". */
+    what: string;
+    refusalFix: string;
+  },
+): Promise<AuthCodeResult> {
+  const doFetch = options.fetchImpl ?? fetch;
+  let res: Response;
+  try {
+    res = await doFetch(GOOGLE_TOKEN_ENDPOINT, {
+      method: 'POST',
+      headers: { 'content-type': 'application/x-www-form-urlencoded' },
+      body: new URLSearchParams(params).toString(),
+      signal: AbortSignal.timeout(options.timeoutMs ?? 30_000),
+    });
+  } catch (err) {
+    return {
+      status: 'unavailable',
+      cause: 'transport',
+      reason: `could not reach Google to ${options.what}: ${err instanceof Error ? err.message : String(err)}`,
+      fix: "check this machine's internet connection and try again",
+    };
+  }
+
+  type TokenBody = {
+    access_token?: unknown;
+    refresh_token?: unknown;
+    expires_in?: unknown;
+    scope?: unknown;
+    error?: unknown;
+    error_description?: unknown;
+  };
+  /**
+   * 🔴 A parse failure must NEVER mask a refusal. Google answers a revoked refresh token with
+   * a 400 whose body is sometimes not JSON at all, and reporting that as "the response was
+   * not JSON" sends the owner looking at a transport problem for what is a re-consent. So the
+   * STATUS is read first and the body is only ever a source of detail.
+   */
+  const body = (await res.json().catch(() => null)) as TokenBody | null;
+
+  if (!res.ok || typeof body?.access_token !== 'string' || body.access_token.length === 0) {
+    const detail =
+      (typeof body?.error_description === 'string' && body.error_description) ||
+      (typeof body?.error === 'string' && body.error) ||
+      `HTTP ${res.status}`;
+    return res.ok && body === null
+      ? {
+          status: 'unavailable',
+          cause: 'transport',
+          reason: "Google's token response was not JSON",
+          fix: 'try again; this is almost always transient',
+        }
+      : {
+          status: 'unavailable',
+          cause: 'refused',
+          reason: `Google refused the request: ${detail}`,
+          fix: options.refusalFix,
+        };
+  }
+
+  return {
+    status: 'ok',
+    accessToken: body.access_token,
+    ...(typeof body.refresh_token === 'string' && body.refresh_token ? { refreshToken: body.refresh_token } : {}),
+    expiresInSeconds: typeof body.expires_in === 'number' ? body.expires_in : 3600,
+    grantedScopes: typeof body.scope === 'string' ? body.scope.split(/\s+/).filter(Boolean) : [],
+  };
+}
+
+/** Trade the `?code=` Google sent to the callback for tokens. */
+export function exchangeAuthCode(options: ExchangeOptions): Promise<AuthCodeResult> {
+  return postTokenRequest(
+    {
+      code: options.code,
+      client_id: options.clientId,
+      client_secret: options.clientSecret,
+      redirect_uri: options.redirectUri,
+      grant_type: 'authorization_code',
+    },
+    {
+      ...(options.fetchImpl ? { fetchImpl: options.fetchImpl } : {}),
+      ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
+      what: 'exchange the consent code',
+      // `invalid_grant` here almost always means the code was already used or the
+      // redirect_uri does not match the one registered.
+      refusalFix: "confirm this app's redirect URI is listed on the OAuth client, then press Connect again",
+    },
+  );
+}
+
+export interface RefreshOptions {
+  clientId: string;
+  clientSecret: string;
+  refreshToken: string;
+  fetchImpl?: FetchLike;
+  timeoutMs?: number;
+  /** What to tell the owner when Google refuses the token — usually "re-consent". */
+  refusalFix?: string;
+}
+
+/**
+ * Trade a stored refresh token for a fresh access token, REPORTING ITS LIFETIME.
+ *
+ * The uncached half of {@link createGoogleTokenMinter}, exported because a consumer that
+ * PERSISTS the access token has to know when it dies — a caller that guesses an hour is a
+ * caller whose token is occasionally already dead when it is used.
+ */
+export function refreshAccessToken(options: RefreshOptions): Promise<AuthCodeResult> {
+  return postTokenRequest(
+    {
+      client_id: options.clientId,
+      client_secret: options.clientSecret,
+      refresh_token: options.refreshToken,
+      grant_type: 'refresh_token',
+    },
+    {
+      ...(options.fetchImpl ? { fetchImpl: options.fetchImpl } : {}),
+      ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
+      what: 'refresh the access token',
+      refusalFix: options.refusalFix ?? 'the refresh token may have been revoked — re-run consent',
+    },
+  );
+}
+
+/**
+ * Best-effort revocation on disconnect. NEVER throws and never reports failure as a blocker:
+ * the local record is deleted either way, and a disconnect that refuses because Google was
+ * unreachable leaves the owner holding a connection they asked to end. Google having already
+ * forgotten the token answers 400, which is the same outcome as success from here — `false`
+ * says only "Google did not confirm it".
+ */
+export async function revokeGoogleToken(
+  token: string,
+  options: { fetchImpl?: FetchLike; timeoutMs?: number } = {},
+): Promise<boolean> {
+  if (!token) return false;
+  const doFetch = options.fetchImpl ?? fetch;
+  try {
+    const res = await doFetch(GOOGLE_REVOKE_ENDPOINT, {
+      method: 'POST',
+      headers: { 'content-type': 'application/x-www-form-urlencoded' },
+      body: new URLSearchParams({ token }).toString(),
+      signal: AbortSignal.timeout(options.timeoutMs ?? 15_000),
+    });
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+
+// ─── The cached minter ───────────────────────────────────────────────────────
+
+export interface TokenMinterOptions {
+  /**
+   * Supplied directly (a consenting app's stored refresh token). `null` means "there are
+   * none"; `undefined` means "read them from `env` + `secretsFile` under `keys`".
+   */
+  credentials?: GoogleCredentials | null;
+  env?: EnvLike;
+  secretsFile?: string;
+  keys?: CredentialKeys;
+  fetchImpl?: FetchLike;
+  timeoutMs?: number;
+  now?: () => number;
+  /**
+   * What to tell the owner when the credential is missing or Google refuses it. Each consumer
+   * mints its token a different way, so the remedy is theirs.
+   */
+  setupFix?: string;
+  /** Named in the failure sentences, e.g. "the digest" or "the YouTube connection". */
+  label?: string;
+}
+
+export interface GoogleTokenMinter {
+  /** A valid access token, or a typed failure carrying the remedy. */
+  token(): Promise<TokenResult>;
+  /**
+   * The scopes Google says this grant actually has. Empty when the token could not be minted
+   * at all — callers must distinguish "no scopes" from "could not ask".
+   */
+  grantedScopes(): Promise<string[]>;
+  /** Drop the cached token — for a test, or after a 401 that suggests a stale one. */
+  invalidate(): void;
+}
+
+const DEFAULT_LABEL = 'this app';
+const DEFAULT_SETUP_FIX = 're-run the one-time Google consent for this app';
+/** A token is never handed out so close to expiry that the call it is used for could land after it dies. */
+const EXPIRY_MARGIN_MS = 60_000;
+
+/**
+ * A short-lived access token, cached in memory until {@link EXPIRY_MARGIN_MS} before it
+ * expires.
+ *
+ * The refresh token is exchanged on demand rather than held as a long-lived bearer, and the
+ * cache exists because one caller makes several calls across several APIs — minting per call
+ * would make the caller's latency proportional to its call count.
+ */
+export function createGoogleTokenMinter(options: TokenMinterOptions = {}): GoogleTokenMinter {
+  const timeout = options.timeoutMs ?? 30_000;
+  const now = options.now ?? Date.now;
+  const label = options.label ?? DEFAULT_LABEL;
+  const fix = options.setupFix ?? DEFAULT_SETUP_FIX;
+
+  let cached: { accessToken: string; scopes: string[]; expiresAt: number } | null = null;
+
+  const mint = async (): Promise<TokenResult> => {
+    const creds =
+      options.credentials !== undefined
+        ? options.credentials
+        : readGoogleCredentials({ env: options.env, secretsFile: options.secretsFile, keys: options.keys });
+    if (!creds) {
+      return {
+        status: 'unconfigured',
+        reason: `no Google OAuth credential for ${label} is on this machine yet`,
+        fix,
+      };
+    }
+    const refreshed = await refreshAccessToken({
+      clientId: creds.clientId,
+      clientSecret: creds.clientSecret,
+      refreshToken: creds.refreshToken,
+      ...(options.fetchImpl ? { fetchImpl: options.fetchImpl } : {}),
+      timeoutMs: timeout,
+      refusalFix: fix,
+    });
+    if (refreshed.status !== 'ok') return refreshed;
+
+    cached = {
+      accessToken: refreshed.accessToken,
+      scopes: refreshed.grantedScopes,
+      expiresAt: now() + Math.max(0, refreshed.expiresInSeconds * 1000 - EXPIRY_MARGIN_MS),
+    };
+    return { status: 'ok', accessToken: cached.accessToken, grantedScopes: cached.scopes };
+  };
+
+  // Closures, not `this`: `const { token } = minter` must keep working.
+  const token = async (): Promise<TokenResult> => {
+    if (cached && now() < cached.expiresAt) {
+      return { status: 'ok', accessToken: cached.accessToken, grantedScopes: cached.scopes };
+    }
+    return await mint();
+  };
+
+  return {
+    token,
+    async grantedScopes(): Promise<string[]> {
+      const t = await token();
+      return t.status === 'ok' ? t.grantedScopes : [];
+    },
+    invalidate() {
+      cached = null;
+    },
+  };
+}
+
+// ─── The live probe ──────────────────────────────────────────────────────────
+
+/**
+ * What an EXCHANGE of the credential a caller is about to use actually did.
+ *
+ * Deliberately not a `TokenResult`: no access token comes out of here, because a probe that
+ * handed one back would become a second minting path with its own cache.
+ */
+export interface CredentialProbe {
+  /**
+   * FOUR states, and the split between the last two is the load-bearing one: `refused` is
+   * Google saying no to this credential and is the owner's to fix; `unreachable` is this
+   * machine's network and fixes itself.
+   */
+  status: 'ok' | 'unconfigured' | 'refused' | 'unreachable';
+  /** The env name whose refresh token was exchanged. "" when none was found or credentials were supplied. */
+  refreshTokenName: string;
+  /** Other names for the refresh token that hold a value and were NOT used. */
+  shadowedRefreshTokenNames: string[];
+  /** What Google says this grant carries. Empty unless `status` is "ok". */
+  grantedScopes: string[];
+  /** One sentence for a bell, a boot log or a health body. Never a credential value. */
+  summary: string;
+  /** The exact next action. "" when `status` is "ok". */
+  fix: string;
+}
+
+/**
+ * 🔴 EXCHANGE the credential rather than assuming a present value is a working one.
+ *
+ * `readGoogleCredentials` cannot tell a dead value from a live one, because "present" is all
+ * it ever asked. The probe does the one thing that answers the question: a real
+ * `grant_type=refresh_token` POST, reported with the NAME it used and the names it shadowed.
+ * It is safe to run at boot — it mints a short-lived access token, drops it, and never throws.
+ */
+export async function probeCredentialExchange(options: TokenMinterOptions = {}): Promise<CredentialProbe> {
+  const label = options.label ?? DEFAULT_LABEL;
+  const setupFix = options.setupFix ?? DEFAULT_SETUP_FIX;
+  // A caller that supplied the credential directly has no names to report, and must not be
+  // told about env vars it never read.
+  const supplied = options.credentials !== undefined;
+  const resolution = supplied
+    ? null
+    : resolveGoogleCredentials({ env: options.env, secretsFile: options.secretsFile, keys: options.keys });
+  const credentials = supplied ? (options.credentials ?? null) : (resolution?.credentials ?? null);
+  const refreshTokenName = resolution?.used.refreshToken?.name ?? '';
+  const shadowed = resolution?.shadowed.refreshToken ?? [];
+
+  if (!credentials) {
+    const missing = resolution?.missing ?? [];
+    return {
+      status: 'unconfigured',
+      refreshTokenName,
+      shadowedRefreshTokenNames: shadowed,
+      grantedScopes: [],
+      summary:
+        `no Google OAuth credential for ${label} is on this machine yet` +
+        (missing.length > 0 ? ` — nothing supplies ${missing.join(' or ')}` : ''),
+      fix: setupFix,
+    };
+  }
+
+  const refreshed = await refreshAccessToken({
+    clientId: credentials.clientId,
+    clientSecret: credentials.clientSecret,
+    refreshToken: credentials.refreshToken,
+    ...(options.fetchImpl ? { fetchImpl: options.fetchImpl } : {}),
+    timeoutMs: options.timeoutMs ?? 30_000,
+    refusalFix: setupFix,
+  });
+
+  // The name is on BOTH outcomes on purpose. A green probe that does not say which of two
+  // spellings it proved is a green probe that proves nothing about the other one.
+  const used = refreshTokenName ? ` using ${refreshTokenName}` : '';
+  const one = shadowed.length === 1;
+  if (refreshed.status === 'ok') {
+    const alsoSet =
+      shadowed.length > 0
+        ? ` ${shadowed.join(' and ')} also hold${one ? 's' : ''} a value for the same credential and ${one ? 'is' : 'are'} never reached.`
+        : '';
+    return {
+      status: 'ok',
+      refreshTokenName,
+      shadowedRefreshTokenNames: shadowed,
+      grantedScopes: refreshed.grantedScopes,
+      summary: `Google exchanged ${label}'s refresh token${used} — ${refreshed.grantedScopes.length} scope(s) granted.${alsoSet}`,
+      fix: '',
+    };
+  }
+
+  // A machine that could not reach Google has proved nothing about the credential, and must
+  // not be reported as though it had.
+  if (refreshed.cause === 'transport') {
+    return {
+      status: 'unreachable',
+      refreshTokenName,
+      shadowedRefreshTokenNames: shadowed,
+      grantedScopes: [],
+      summary: `${refreshed.reason} — ${label}'s credential was NOT tested, so this says nothing about whether it works.`,
+      fix: refreshed.fix,
+    };
+  }
+
+  // 🔴 "The grant has been revoked" is the WRONG diagnosis when a second, untried value for
+  // the same credential is sitting in the same file.
+  const alsoUntried =
+    shadowed.length > 0
+      ? ` ${shadowed.join(' and ')} also hold${one ? 's' : ''} a value for the same credential and ${one ? 'was' : 'were'} never tried.`
+      : '';
+  return {
+    status: 'refused',
+    refreshTokenName,
+    shadowedRefreshTokenNames: shadowed,
+    grantedScopes: [],
+    summary: `${refreshed.reason}${used} — ${label}'s Google calls will all fail until this is fixed.${alsoUntried}`,
+    fix:
+      shadowed.length > 0
+        ? `Before re-consenting, check whether ${shadowed.join(' or ')} holds the live grant: the preferred name ${refreshTokenName} wins by being PRESENT, not by working. Leaving exactly one of those names set resolves it either way. Otherwise: ${setupFix}`
+        : setupFix,
+  };
+}
+
+// ─── 403 → remedy ────────────────────────────────────────────────────────────
+
+/**
+ * Turn a Google 403 into something the owner can act on.
+ *
+ * A missing scope is the single most likely failure after the owner consents once and the app
+ * later grows a capability. Naming the MISSING scope and the re-consent command is the
+ * difference between a two-minute fix and an evening.
+ *
+ * 🔴 The two branches say genuinely different things: `ACCESS_TOKEN_SCOPE_INSUFFICIENT` is a
+ * consent problem fixed in a browser, while a 403 on a granted scope is an API that is not
+ * ENABLED on the project, fixed in a different console page entirely.
+ */
+export function describeScopeFailure(options: {
+  api: string;
+  needed: string;
+  granted: readonly string[];
+  httpStatus: number;
+  /** The command that re-runs consent, e.g. `bun run google:consent`. */
+  consentCommand: string;
+}): { reason: string; fix: string } {
+  const has = options.granted.includes(options.needed);
+  if (!has && options.granted.length > 0) {
+    return {
+      reason: `${options.api} refused the call (HTTP ${options.httpStatus}): the grant on this machine does NOT include ${options.needed}. It has: ${options.granted.join(', ')}`,
+      fix: `run ${options.consentCommand} and approve ${options.needed}. The existing token keeps working for everything it already covers, so nothing else breaks while you do it.`,
+    };
+  }
+  return {
+    reason: `${options.api} refused the call (HTTP ${options.httpStatus}) even though ${options.needed} appears to be granted — the API may be disabled for this Google Cloud project`,
+    fix: `open Google Cloud Console → APIs and Services → Library and confirm the ${options.api} API is ENABLED for the project that owns this OAuth client`,
+  };
+}