cursedbelt-server 4.13.0 → 4.14.0

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

@@ -0,0 +1,742 @@
+import { describe, expect, test } from 'bun:test';
+import { mkdtempSync, writeFileSync } from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
+import path from 'node:path';
+import {
+  buildConsentUrl,
+  CANONICAL_CREDENTIAL_KEYS,
+  createGoogleTokenMinter,
+  describeScopeFailure,
+  exchangeAuthCode,
+  expandTilde,
+  type FetchLike,
+  GOOGLE_AUTH_ENDPOINT,
+  GOOGLE_REVOKE_ENDPOINT,
+  GOOGLE_TOKEN_ENDPOINT,
+  parseEnvFile,
+  probeCredentialExchange,
+  readGoogleCredentials,
+  readSecret,
+  refreshAccessToken,
+  resolveGoogleCredentials,
+  revokeGoogleToken,
+} from './googleOAuth';
+
+/**
+ * The union of the two app-side suites this module was lifted from (task 099), plus a failure
+ * path for every public function that can fail.
+ */
+
+/** A consumer with history: the canonical name first, a historical alias behind it. */
+const ALIASED_KEYS = {
+  clientId: ['GOOGLE_OAUTH_CLIENT_ID', 'GMAIL_CLIENT_ID'],
+  clientSecret: ['GOOGLE_OAUTH_CLIENT_SECRET', 'GMAIL_CLIENT_SECRET'],
+  refreshToken: ['GOOGLE_OAUTH_REFRESH_TOKEN', 'GMAIL_REFRESH_TOKEN'],
+};
+
+const secretsFileWith = (body: string): string => {
+  const dir = mkdtempSync(path.join(tmpdir(), 'google-oauth-'));
+  const file = path.join(dir, 'app.env');
+  writeFileSync(file, body);
+  return file;
+};
+
+const NO_FILE = path.join(tmpdir(), 'google-oauth-no-such-dir', 'missing.env');
+
+const tokenResponse = (over: Record<string, unknown> = {}) =>
+  Response.json({ access_token: 'at-1', expires_in: 3600, scope: 's1 s2', ...over });
+
+const refusal = () =>
+  Response.json({ error: 'invalid_grant', error_description: 'Token has been expired or revoked.' }, { status: 400 });
+
+const offline: FetchLike = async () => {
+  throw new Error('getaddrinfo ENOTFOUND oauth2.googleapis.com');
+};
+
+// ─── endpoints ───────────────────────────────────────────────────────────────
+
+describe('endpoints', () => {
+  test("are Google's, over https", () => {
+    for (const url of [GOOGLE_TOKEN_ENDPOINT, GOOGLE_AUTH_ENDPOINT, GOOGLE_REVOKE_ENDPOINT]) {
+      const u = new URL(url);
+      expect(u.protocol).toBe('https:');
+      expect(u.hostname.endsWith('.googleapis.com') || u.hostname === 'accounts.google.com').toBe(true);
+    }
+  });
+});
+
+// ─── env file ────────────────────────────────────────────────────────────────
+
+describe('parseEnvFile', () => {
+  test('tolerates comments, quotes, blanks and `export`', () => {
+    expect(parseEnvFile('# note\n\nexport A="one"\nB=\'two\'\nC=three\nnot a line\n')).toEqual({
+      A: 'one',
+      B: 'two',
+      C: 'three',
+    });
+  });
+
+  test('CRLF line endings do not leak a carriage return into a value', () => {
+    expect(parseEnvFile('A=one\r\nB="two"\r\n')).toEqual({ A: 'one', B: 'two' });
+  });
+
+  test('garbage parses to nothing rather than throwing', () => {
+    expect(parseEnvFile('=\nlower=case\n  # A=commented\n\u0000\n')).toEqual({});
+  });
+});
+
+describe('expandTilde', () => {
+  test('expands a leading ~/ and leaves everything else alone', () => {
+    expect(expandTilde('~/x/y.env')).toBe(path.join(homedir(), 'x/y.env'));
+    expect(expandTilde('/abs/y.env')).toBe('/abs/y.env');
+    expect(expandTilde('rel/~/y.env')).toBe('rel/~/y.env');
+  });
+});
+
+describe('readSecret', () => {
+  test('env beats the file, and the file answers when env is silent', () => {
+    const file = secretsFileWith('MAPS_KEY=from-file\nHOME_ADDR="1 Main St"\n');
+    expect(readSecret('MAPS_KEY', { env: { MAPS_KEY: ' from-env ' }, secretsFile: file })).toBe('from-env');
+    expect(readSecret('HOME_ADDR', { env: {}, secretsFile: file })).toBe('1 Main St');
+  });
+
+  test('a missing key, a missing file and no file at all are all "" — never a throw', () => {
+    const file = secretsFileWith('A=1\n');
+    expect(readSecret('B', { env: {}, secretsFile: file })).toBe('');
+    expect(readSecret('A', { env: {}, secretsFile: NO_FILE })).toBe('');
+    expect(readSecret('A', { env: {} })).toBe('');
+  });
+
+  test('a whitespace-only env value does not shadow the file', () => {
+    const file = secretsFileWith('A=real\n');
+    expect(readSecret('A', { env: { A: '   ' }, secretsFile: file })).toBe('real');
+  });
+});
+
+// ─── credentials ─────────────────────────────────────────────────────────────
+
+describe('readGoogleCredentials', () => {
+  test('a PARTIAL credential is the same as none', () => {
+    const file = secretsFileWith('GOOGLE_OAUTH_CLIENT_ID=cid\nGOOGLE_OAUTH_CLIENT_SECRET=sec\n');
+    expect(readGoogleCredentials({ env: {}, secretsFile: file })).toBeNull();
+  });
+
+  test('an unreadable secrets file is no credential, not a throw', () => {
+    expect(readGoogleCredentials({ env: {}, secretsFile: NO_FILE })).toBeNull();
+  });
+
+  test('reads the canonical names by default', () => {
+    expect(CANONICAL_CREDENTIAL_KEYS.refreshToken).toEqual(['GOOGLE_OAUTH_REFRESH_TOKEN']);
+    expect(
+      readGoogleCredentials({
+        env: {
+          GOOGLE_OAUTH_CLIENT_ID: 'cid',
+          GOOGLE_OAUTH_CLIENT_SECRET: 'sec',
+          GOOGLE_OAUTH_REFRESH_TOKEN: 'rt',
+          GMAIL_REFRESH_TOKEN: 'not-listed',
+        },
+      }),
+    ).toEqual({ clientId: 'cid', clientSecret: 'sec', refreshToken: 'rt' });
+  });
+
+  test('env beats the file, and an earlier key name beats a later alias', () => {
+    const file = secretsFileWith(
+      'GOOGLE_OAUTH_CLIENT_ID=from-file\nGMAIL_CLIENT_ID=alias\n' +
+        'GOOGLE_OAUTH_CLIENT_SECRET=sec\nGOOGLE_OAUTH_REFRESH_TOKEN=rt\n',
+    );
+    const creds = readGoogleCredentials({
+      env: { GOOGLE_OAUTH_CLIENT_SECRET: 'from-env' },
+      secretsFile: file,
+      keys: {
+        clientId: ['GOOGLE_OAUTH_CLIENT_ID', 'GMAIL_CLIENT_ID'],
+        clientSecret: ['GOOGLE_OAUTH_CLIENT_SECRET'],
+        refreshToken: ['GOOGLE_OAUTH_REFRESH_TOKEN'],
+      },
+    });
+    expect(creds).toEqual({ clientId: 'from-file', clientSecret: 'from-env', refreshToken: 'rt' });
+  });
+
+  test('an alias is used when the canonical name is absent', () => {
+    const file = secretsFileWith('GMAIL_CLIENT_ID=cid\nGMAIL_CLIENT_SECRET=sec\nGMAIL_REFRESH_TOKEN=rt\n');
+    expect(readGoogleCredentials({ env: {}, secretsFile: file, keys: ALIASED_KEYS })).toEqual({
+      clientId: 'cid',
+      clientSecret: 'sec',
+      refreshToken: 'rt',
+    });
+  });
+});
+
+describe('resolveGoogleCredentials — WHICH name carried it', () => {
+  /**
+   * 🔴 The measured bug, in one test. Two refresh tokens for the identical client in one file;
+   * the preferred name wins by being PRESENT and nothing anywhere said the other one existed.
+   */
+  test('names the winner and lists the spellings it shadowed', () => {
+    const file = secretsFileWith(
+      'GOOGLE_OAUTH_CLIENT_ID=cid\nGOOGLE_OAUTH_CLIENT_SECRET=sec\n' +
+        'GOOGLE_OAUTH_REFRESH_TOKEN=dead\nGMAIL_REFRESH_TOKEN=live\n',
+    );
+    const r = resolveGoogleCredentials({ env: {}, secretsFile: file, keys: ALIASED_KEYS });
+    expect(r.credentials?.refreshToken).toBe('dead');
+    expect(r.used.refreshToken).toEqual({ name: 'GOOGLE_OAUTH_REFRESH_TOKEN', from: 'file' });
+    expect(r.shadowed.refreshToken).toEqual(['GMAIL_REFRESH_TOKEN']);
+  });
+
+  test("says an override came from the ENV, not from the owner's 0600 file", () => {
+    const file = secretsFileWith(
+      'GOOGLE_OAUTH_CLIENT_ID=cid\nGOOGLE_OAUTH_CLIENT_SECRET=sec\nGOOGLE_OAUTH_REFRESH_TOKEN=rt\n',
+    );
+    const r = resolveGoogleCredentials({
+      env: { GOOGLE_OAUTH_REFRESH_TOKEN: 'from-env' },
+      secretsFile: file,
+      keys: ALIASED_KEYS,
+    });
+    expect(r.used.refreshToken).toEqual({ name: 'GOOGLE_OAUTH_REFRESH_TOKEN', from: 'env' });
+  });
+
+  test('a partial credential names every spelling that supplies nothing', () => {
+    const file = secretsFileWith('GOOGLE_OAUTH_CLIENT_ID=cid\nGOOGLE_OAUTH_CLIENT_SECRET=sec\n');
+    const r = resolveGoogleCredentials({ env: {}, secretsFile: file, keys: ALIASED_KEYS });
+    expect(r.credentials).toBeNull();
+    expect(r.used.refreshToken).toBeNull();
+    expect(r.missing).toEqual(['GOOGLE_OAUTH_REFRESH_TOKEN', 'GMAIL_REFRESH_TOKEN']);
+  });
+
+  test('nothing at all names all three halves as missing', () => {
+    const r = resolveGoogleCredentials({ env: {}, secretsFile: NO_FILE });
+    expect(r.credentials).toBeNull();
+    expect(r.missing).toEqual(['GOOGLE_OAUTH_CLIENT_ID', 'GOOGLE_OAUTH_CLIENT_SECRET', 'GOOGLE_OAUTH_REFRESH_TOKEN']);
+  });
+});
+
+// ─── consent ─────────────────────────────────────────────────────────────────
+
+describe('buildConsentUrl', () => {
+  const url = (over: Partial<Parameters<typeof buildConsentUrl>[0]> = {}): URL =>
+    new URL(
+      buildConsentUrl({
+        clientId: 'cid',
+        redirectUri: 'https://app.example.com/api/oauth/callback',
+        scopes: ['https://www.googleapis.com/auth/youtube.readonly'],
+        state: 'st-1',
+        ...over,
+      }),
+    );
+
+  test("targets Google's consent endpoint and carries the caller's state verbatim", () => {
+    const u = url();
+    expect(`${u.origin}${u.pathname}`).toBe(GOOGLE_AUTH_ENDPOINT);
+    expect(u.searchParams.get('state')).toBe('st-1');
+    expect(u.searchParams.get('client_id')).toBe('cid');
+    expect(u.searchParams.get('redirect_uri')).toBe('https://app.example.com/api/oauth/callback');
+    expect(u.searchParams.get('response_type')).toBe('code');
+    expect(u.searchParams.get('include_granted_scopes')).toBe('true');
+  });
+
+  /**
+   * The two parameters without which the grant dies quietly: no `offline` means no refresh
+   * token at all, and no `consent` means Google declines to re-issue one on a SECOND connect.
+   */
+  test('always asks for offline access, and forces a fresh refresh token by default', () => {
+    const u = url();
+    expect(u.searchParams.get('access_type')).toBe('offline');
+    expect(u.searchParams.get('prompt')).toBe('consent');
+  });
+
+  test('an explicit prompt is honoured', () => {
+    expect(url({ prompt: 'select_account' }).searchParams.get('prompt')).toBe('select_account');
+  });
+
+  test('scopes are space-joined, as Google expects', () => {
+    expect(url({ scopes: ['a', 'b'] }).searchParams.get('scope')).toBe('a b');
+  });
+});
+
+describe('exchangeAuthCode', () => {
+  const exchange = (fetchImpl: FetchLike): ReturnType<typeof exchangeAuthCode> =>
+    exchangeAuthCode({
+      clientId: 'cid',
+      clientSecret: 'sec',
+      redirectUri: 'https://app.example.com/cb',
+      code: 'the-code',
+      fetchImpl,
+    });
+
+  test('posts the code as form-encoded to the token endpoint and returns the tokens', async () => {
+    let sentBody = '';
+    let sentUrl = '';
+    const result = await exchange(async (url, init) => {
+      sentUrl = url;
+      sentBody = String(init?.body ?? '');
+      return Response.json({ access_token: 'at', refresh_token: 'rt', expires_in: 1234, scope: 's1 s2' });
+    });
+    expect(result).toEqual({
+      status: 'ok',
+      accessToken: 'at',
+      refreshToken: 'rt',
+      expiresInSeconds: 1234,
+      grantedScopes: ['s1', 's2'],
+    });
+    expect(sentUrl).toBe(GOOGLE_TOKEN_ENDPOINT);
+    const params = new URLSearchParams(sentBody);
+    expect(params.get('grant_type')).toBe('authorization_code');
+    expect(params.get('code')).toBe('the-code');
+    expect(params.get('redirect_uri')).toBe('https://app.example.com/cb');
+  });
+
+  /**
+   * A re-consent that returns no `refresh_token` must leave the field ABSENT rather than
+   * empty: a caller that stored `""` over a working refresh token would break the connection
+   * at the moment it looked like it was being repaired.
+   */
+  test('omits refreshToken entirely when Google did not re-issue one', async () => {
+    const result = await exchange(async () => Response.json({ access_token: 'at', expires_in: 60 }));
+    expect(result.status).toBe('ok');
+    expect(result).not.toHaveProperty('refreshToken');
+  });
+
+  test('a 400 is `refused`, names what Google said and what to do about it', async () => {
+    const result = await exchange(async () =>
+      Response.json({ error: 'invalid_grant', error_description: 'Bad Request' }, { status: 400 }),
+    );
+    if (result.status !== 'unavailable') throw new Error(`expected unavailable, got ${result.status}`);
+    expect(result.cause).toBe('refused');
+    expect(result.reason).toContain('Bad Request');
+    expect(result.fix).toContain('redirect URI');
+  });
+
+  test('a 400 with only `error` still names it', async () => {
+    const result = await exchange(async () => Response.json({ error: 'invalid_client' }, { status: 401 }));
+    if (result.status !== 'unavailable') throw new Error('expected unavailable');
+    expect(result.reason).toContain('invalid_client');
+  });
+
+  test('a 200 with no access_token is a failure, not an empty success', async () => {
+    const result = await exchange(async () => Response.json({ expires_in: 60 }));
+    expect(result.status).toBe('unavailable');
+  });
+
+  test('an unreachable Google is `transport`, reported, never thrown', async () => {
+    const result = await exchange(offline);
+    if (result.status !== 'unavailable') throw new Error('expected unavailable');
+    expect(result.cause).toBe('transport');
+    expect(result.reason).toContain('ENOTFOUND');
+  });
+
+  /**
+   * 🔴 A parse failure must never MASK a refusal. Google answers a revoked or already-used
+   * grant with a 400 whose body is sometimes not JSON (regression caught 2026-08-14).
+   */
+  test('a non-JSON body on a REFUSAL still reads as a refusal', async () => {
+    const result = await exchange(async () => new Response('<html>400</html>', { status: 400 }));
+    if (result.status !== 'unavailable') throw new Error('expected unavailable');
+    expect(result.cause).toBe('refused');
+    expect(result.reason).toContain('HTTP 400');
+    expect(result.fix).toContain('redirect URI');
+  });
+
+  test('a non-JSON body on a 200 is reported as exactly that', async () => {
+    const result = await exchange(async () => new Response('<html>ok?</html>', { status: 200 }));
+    if (result.status !== 'unavailable') throw new Error('expected unavailable');
+    expect(result.cause).toBe('transport');
+    expect(result.reason).toContain('not JSON');
+  });
+});
+
+// ─── refresh ─────────────────────────────────────────────────────────────────
+
+describe('refreshAccessToken', () => {
+  const creds = { clientId: 'cid', clientSecret: 'sec', refreshToken: 'rt-secret' };
+
+  test('posts grant_type=refresh_token and reports the lifetime', async () => {
+    let params = new URLSearchParams();
+    const result = await refreshAccessToken({
+      ...creds,
+      fetchImpl: async (_url, init) => {
+        params = new URLSearchParams(String(init?.body ?? ''));
+        return tokenResponse({ expires_in: 1800 });
+      },
+    });
+    expect(result).toEqual({ status: 'ok', accessToken: 'at-1', expiresInSeconds: 1800, grantedScopes: ['s1', 's2'] });
+    expect(params.get('grant_type')).toBe('refresh_token');
+    expect(params.get('refresh_token')).toBe('rt-secret');
+  });
+
+  test('a missing expires_in is assumed to be an hour', async () => {
+    const result = await refreshAccessToken({ ...creds, fetchImpl: async () => Response.json({ access_token: 'a' }) });
+    expect(result.status === 'ok' && result.expiresInSeconds).toBe(3600);
+  });
+
+  test('a revoked token is `refused` with the default re-consent remedy, and no secret in it', async () => {
+    const result = await refreshAccessToken({ ...creds, fetchImpl: async () => refusal() });
+    if (result.status !== 'unavailable') throw new Error('expected unavailable');
+    expect(result.cause).toBe('refused');
+    expect(result.reason).toContain('expired or revoked');
+    expect(result.fix).toContain('re-run consent');
+    expect(JSON.stringify(result)).not.toContain('rt-secret');
+    expect(JSON.stringify(result)).not.toContain('"sec"');
+  });
+
+  test("the caller's refusalFix replaces the default", async () => {
+    const result = await refreshAccessToken({ ...creds, refusalFix: 'press Connect', fetchImpl: async () => refusal() });
+    expect(result.status === 'unavailable' && result.fix).toBe('press Connect');
+  });
+
+  test('offline is `transport`, never thrown', async () => {
+    const result = await refreshAccessToken({ ...creds, fetchImpl: offline });
+    expect(result.status === 'unavailable' && result.cause).toBe('transport');
+  });
+});
+
+// ─── revoke ──────────────────────────────────────────────────────────────────
+
+describe('revokeGoogleToken', () => {
+  test('posts the token to the revoke endpoint and reports success', async () => {
+    let body = '';
+    let sentUrl = '';
+    const ok = await revokeGoogleToken('rt', {
+      fetchImpl: async (url, init) => {
+        sentUrl = url;
+        body = String(init?.body ?? '');
+        return new Response(null, { status: 200 });
+      },
+    });
+    expect(ok).toBe(true);
+    expect(sentUrl).toBe(GOOGLE_REVOKE_ENDPOINT);
+    expect(new URLSearchParams(body).get('token')).toBe('rt');
+  });
+
+  /** A disconnect must never be blocked by Google being unreachable. */
+  test('never throws when Google is unreachable', async () => {
+    await expect(revokeGoogleToken('rt', { fetchImpl: offline })).resolves.toBe(false);
+  });
+
+  test('a 400 (already forgotten) is `false`, not a throw', async () => {
+    await expect(
+      revokeGoogleToken('rt', { fetchImpl: async () => Response.json({ error: 'invalid_token' }, { status: 400 }) }),
+    ).resolves.toBe(false);
+  });
+
+  test('an empty token is a no-op', async () => {
+    let called = false;
+    const ok = await revokeGoogleToken('', {
+      fetchImpl: async () => {
+        called = true;
+        return new Response(null, { status: 200 });
+      },
+    });
+    expect(ok).toBe(false);
+    expect(called).toBe(false);
+  });
+});
+
+// ─── minter ──────────────────────────────────────────────────────────────────
+
+describe('createGoogleTokenMinter', () => {
+  const creds = { clientId: 'cid', clientSecret: 'sec', refreshToken: 'rt' };
+
+  test("no credential is `unconfigured` and carries the caller's own remedy", async () => {
+    const minter = createGoogleTokenMinter({
+      credentials: null,
+      label: 'the dashboard',
+      setupFix: 'run bun run google:consent',
+      fetchImpl: async () => {
+        throw new Error('must not be called');
+      },
+    });
+    const result = await minter.token();
+    if (result.status !== 'unconfigured') throw new Error(`expected unconfigured, got ${result.status}`);
+    expect(result.reason).toContain('the dashboard');
+    expect(result.fix).toBe('run bun run google:consent');
+  });
+
+  test('reads env + secrets file under the given keys when no credential is supplied', async () => {
+    const file = secretsFileWith('GMAIL_CLIENT_ID=cid\nGMAIL_CLIENT_SECRET=sec\nGMAIL_REFRESH_TOKEN=from-alias\n');
+    let sent = '';
+    const minter = createGoogleTokenMinter({
+      env: {},
+      secretsFile: file,
+      keys: ALIASED_KEYS,
+      fetchImpl: async (_url, init) => {
+        sent = new URLSearchParams(String(init?.body ?? '')).get('refresh_token') ?? '';
+        return tokenResponse();
+      },
+    });
+    expect((await minter.token()).status).toBe('ok');
+    expect(sent).toBe('from-alias');
+  });
+
+  test('an unreadable secrets file is `unconfigured`, and makes no call', async () => {
+    let calls = 0;
+    const minter = createGoogleTokenMinter({
+      env: {},
+      secretsFile: NO_FILE,
+      fetchImpl: async () => {
+        calls += 1;
+        return tokenResponse();
+      },
+    });
+    expect((await minter.token()).status).toBe('unconfigured');
+    expect(calls).toBe(0);
+  });
+
+  test('caches the access token until shortly before it expires, then re-mints', async () => {
+    let calls = 0;
+    const clock = { now: 1_000_000 };
+    const minter = createGoogleTokenMinter({
+      credentials: creds,
+      now: () => clock.now,
+      fetchImpl: async () => {
+        calls += 1;
+        return tokenResponse({ access_token: `at-${calls}` });
+      },
+    });
+    expect(await minter.token()).toMatchObject({ accessToken: 'at-1' });
+    clock.now += 3000_000; // still inside 3600s - 60s margin
+    await minter.token();
+    expect(calls).toBe(1);
+    clock.now += 600_000; // past the margin
+    expect(await minter.token()).toMatchObject({ accessToken: 'at-2' });
+    expect(calls).toBe(2);
+  });
+
+  test('a token shorter-lived than the margin is never cached', async () => {
+    let calls = 0;
+    const minter = createGoogleTokenMinter({
+      credentials: creds,
+      now: () => 5,
+      fetchImpl: async () => {
+        calls += 1;
+        return tokenResponse({ expires_in: 30 });
+      },
+    });
+    await minter.token();
+    await minter.token();
+    expect(calls).toBe(2);
+  });
+
+  test('invalidate() forces the next call to re-mint', async () => {
+    let calls = 0;
+    const minter = createGoogleTokenMinter({
+      credentials: creds,
+      fetchImpl: async () => {
+        calls += 1;
+        return tokenResponse();
+      },
+    });
+    await minter.token();
+    minter.invalidate();
+    await minter.token();
+    expect(calls).toBe(2);
+  });
+
+  test('a refused refresh token is `unavailable`, `refused`, carries setupFix, and never echoes the credential', async () => {
+    const minter = createGoogleTokenMinter({
+      credentials: { clientId: 'cid', clientSecret: 'sec-value', refreshToken: 'rt-value' },
+      setupFix: 're-consent',
+      fetchImpl: async () => new Response('nope', { status: 400 }),
+    });
+    const result = await minter.token();
+    if (result.status !== 'unavailable') throw new Error('expected unavailable');
+    expect(result.cause).toBe('refused');
+    expect(result.fix).toBe('re-consent');
+    expect(JSON.stringify(result)).not.toContain('rt-value');
+    expect(JSON.stringify(result)).not.toContain('sec-value');
+  });
+
+  test('a failure is not cached — the next call tries again', async () => {
+    let calls = 0;
+    const minter = createGoogleTokenMinter({
+      credentials: creds,
+      fetchImpl: async () => {
+        calls += 1;
+        return calls === 1 ? refusal() : tokenResponse();
+      },
+    });
+    expect((await minter.token()).status).toBe('unavailable');
+    expect((await minter.token()).status).toBe('ok');
+  });
+
+  test('offline is `unavailable` with cause `transport`', async () => {
+    const result = await createGoogleTokenMinter({ credentials: creds, fetchImpl: offline }).token();
+    expect(result.status === 'unavailable' && result.cause).toBe('transport');
+  });
+
+  test('a token response with no access_token is a failure, not an empty success', async () => {
+    const minter = createGoogleTokenMinter({
+      credentials: creds,
+      fetchImpl: async () => Response.json({ expires_in: 3600 }),
+    });
+    expect((await minter.token()).status).toBe('unavailable');
+  });
+
+  test('grantedScopes is empty when the token could not be minted at all', async () => {
+    const minter = createGoogleTokenMinter({ credentials: null, fetchImpl: async () => tokenResponse() });
+    expect(await minter.grantedScopes()).toEqual([]);
+  });
+
+  test('methods survive being destructured', async () => {
+    const { token, grantedScopes } = createGoogleTokenMinter({
+      credentials: creds,
+      fetchImpl: async () => tokenResponse(),
+    });
+    expect((await token()).status).toBe('ok');
+    expect(await grantedScopes()).toEqual(['s1', 's2']);
+  });
+});
+
+// ─── probe ───────────────────────────────────────────────────────────────────
+
+describe('probeCredentialExchange — a present value is not a working one', () => {
+  const aliased = (body: string, fetchImpl: FetchLike) =>
+    probeCredentialExchange({
+      env: {},
+      secretsFile: secretsFileWith(body),
+      keys: ALIASED_KEYS,
+      label: 'the digest',
+      setupFix: 'run get-refresh-token.sh',
+      fetchImpl,
+    });
+
+  const refusesAllBut = (livingToken: string) => {
+    const seen: string[] = [];
+    return {
+      seen,
+      fetchImpl: async (_url: string, init?: RequestInit) => {
+        const sent = new URLSearchParams(String(init?.body ?? '')).get('refresh_token') ?? '';
+        seen.push(sent);
+        return sent === livingToken
+          ? tokenResponse({ scope: 'gmail.readonly calendar.events' })
+          : Response.json({ error: 'invalid_grant', error_description: 'Bad Request' }, { status: 400 });
+      },
+    };
+  };
+
+  /**
+   * 🔴 THE PLANTED DEAD TOKEN — the exact state measured 2026-09-15. The canonical name is
+   * dead, the alias beside it is alive, and the diagnosis has to name BOTH or it sends the
+   * owner to a browser to fix something a one-line edit fixes.
+   */
+  test('a refused canonical token names it AND the untried alias', async () => {
+    const { seen, fetchImpl } = refusesAllBut('live');
+    const probe = await aliased(
+      'GOOGLE_OAUTH_CLIENT_ID=cid\nGOOGLE_OAUTH_CLIENT_SECRET=sec\n' +
+        'GOOGLE_OAUTH_REFRESH_TOKEN=dead\nGMAIL_REFRESH_TOKEN=live\n',
+      fetchImpl,
+    );
+    expect(probe.status).toBe('refused');
+    expect(probe.refreshTokenName).toBe('GOOGLE_OAUTH_REFRESH_TOKEN');
+    expect(probe.shadowedRefreshTokenNames).toEqual(['GMAIL_REFRESH_TOKEN']);
+    expect(probe.summary).toContain('GOOGLE_OAUTH_REFRESH_TOKEN');
+    expect(probe.summary).toContain('GMAIL_REFRESH_TOKEN');
+    expect(probe.summary).toContain('never tried');
+    // The remedy must NOT be "re-consent" first — that is the wrong forty minutes.
+    expect(probe.fix).toContain('GMAIL_REFRESH_TOKEN');
+    expect(probe.fix.indexOf('GMAIL_REFRESH_TOKEN')).toBeLessThan(probe.fix.indexOf('get-refresh-token.sh'));
+    // It exchanged the one it would actually USE, and did not go hunting for a working
+    // alias behind the owner's back.
+    expect(seen).toEqual(['dead']);
+    // And no credential value ever reaches the sentence.
+    expect(JSON.stringify(probe)).not.toContain('dead');
+  });
+
+  test('a refused token with no alias is `refused` with the plain setup remedy', async () => {
+    const probe = await aliased(
+      'GOOGLE_OAUTH_CLIENT_ID=cid\nGOOGLE_OAUTH_CLIENT_SECRET=sec\nGOOGLE_OAUTH_REFRESH_TOKEN=dead\n',
+      refusesAllBut('live').fetchImpl,
+    );
+    expect(probe.status).toBe('refused');
+    expect(probe.fix).toBe('run get-refresh-token.sh');
+    expect(probe.summary).not.toContain('never tried');
+  });
+
+  test('a credential Google takes is `ok` and still says which name proved it', async () => {
+    const { fetchImpl } = refusesAllBut('live');
+    const probe = await aliased('GMAIL_CLIENT_ID=cid\nGMAIL_CLIENT_SECRET=sec\nGMAIL_REFRESH_TOKEN=live\n', fetchImpl);
+    expect(probe.status).toBe('ok');
+    expect(probe.refreshTokenName).toBe('GMAIL_REFRESH_TOKEN');
+    expect(probe.shadowedRefreshTokenNames).toEqual([]);
+    expect(probe.summary).toContain('GMAIL_REFRESH_TOKEN');
+    expect(probe.grantedScopes).toEqual(['gmail.readonly', 'calendar.events']);
+    expect(probe.fix).toBe('');
+  });
+
+  test('an `ok` that shadows an alias says the alias is never reached', async () => {
+    const probe = await aliased(
+      'GOOGLE_OAUTH_CLIENT_ID=cid\nGOOGLE_OAUTH_CLIENT_SECRET=sec\n' +
+        'GOOGLE_OAUTH_REFRESH_TOKEN=live\nGMAIL_REFRESH_TOKEN=other\n',
+      refusesAllBut('live').fetchImpl,
+    );
+    expect(probe.status).toBe('ok');
+    expect(probe.summary).toContain('never reached');
+  });
+
+  /** 🔴 An offline laptop has proved NOTHING about the credential and must not be reported
+   *  as a dead grant — that is the false bell that gets a real one muted. */
+  test('a machine that could not reach Google is `unreachable`, not `refused`', async () => {
+    const probe = await aliased(
+      'GOOGLE_OAUTH_CLIENT_ID=cid\nGOOGLE_OAUTH_CLIENT_SECRET=sec\nGOOGLE_OAUTH_REFRESH_TOKEN=rt\n',
+      offline,
+    );
+    expect(probe.status).toBe('unreachable');
+    expect(probe.summary).toContain('NOT tested');
+  });
+
+  test('no credential at all is `unconfigured` with the setup remedy, and no call', async () => {
+    let calls = 0;
+    const probe = await aliased('GOOGLE_OAUTH_CLIENT_ID=cid\n', async () => {
+      calls += 1;
+      return tokenResponse();
+    });
+    expect(probe.status).toBe('unconfigured');
+    expect(probe.summary).toContain('GOOGLE_OAUTH_REFRESH_TOKEN');
+    expect(probe.fix).toBe('run get-refresh-token.sh');
+    expect(calls).toBe(0);
+  });
+
+  test('supplied credentials report no env names — it never read any', async () => {
+    const probe = await probeCredentialExchange({
+      credentials: { clientId: 'cid', clientSecret: 'sec', refreshToken: 'rt' },
+      env: { GOOGLE_OAUTH_REFRESH_TOKEN: 'ignored' },
+      fetchImpl: async () => refusal(),
+    });
+    expect(probe.status).toBe('refused');
+    expect(probe.refreshTokenName).toBe('');
+    expect(probe.summary).not.toContain('GOOGLE_OAUTH_REFRESH_TOKEN');
+
+    const none = await probeCredentialExchange({ credentials: null, fetchImpl: async () => tokenResponse() });
+    expect(none.status).toBe('unconfigured');
+    expect(none.summary).not.toContain('nothing supplies');
+  });
+});
+
+// ─── 403 → remedy ────────────────────────────────────────────────────────────
+
+describe('describeScopeFailure', () => {
+  test('a missing scope names the scope, what IS granted, and the consent command', () => {
+    const { reason, fix } = describeScopeFailure({
+      api: 'Cloud Monitoring',
+      needed: 'https://www.googleapis.com/auth/monitoring.read',
+      granted: ['https://www.googleapis.com/auth/gmail.readonly'],
+      httpStatus: 403,
+      consentCommand: 'bun run google:consent',
+    });
+    expect(reason).toContain('does NOT include');
+    expect(reason).toContain('monitoring.read');
+    expect(reason).toContain('gmail.readonly');
+    expect(fix).toContain('bun run google:consent');
+  });
+
+  test('a 403 on a GRANTED scope points at the API being disabled, not at consent', () => {
+    const { reason, fix } = describeScopeFailure({
+      api: 'Cloud Monitoring',
+      needed: 'scope-a',
+      granted: ['scope-a'],
+      httpStatus: 403,
+      consentCommand: 'bun run google:consent',
+    });
+    expect(reason).toContain('may be disabled');
+    expect(fix).toContain('Library');
+    expect(fix).not.toContain('google:consent');
+  });
+});