gogcli-mcp 2.19.2 → 2.21.0

package/src/google-token.ts

@@ -0,0 +1,225 @@
+import { readEnvVar } from '@chrischall/mcp-utils';
+
+/**
+ * Mint short-lived Google access tokens from a long-lived refresh token, so a
+ * hosted gog's identity belongs to the REGISTRATION rather than to the machine
+ * the binary runs on (#241).
+ *
+ * The shape of the problem: `gog` reads credentials from a keyring at
+ * `GOG_HOME`, on the box where it executes — which is why one Fly volume ended
+ * up being every registration's identity. But `gog --access-token` bypasses the
+ * keyring entirely, and #235 already carries such a token to the box per
+ * request. The only missing piece was that an access token lives about an hour,
+ * so it cannot be the thing you STORE. A refresh token can.
+ *
+ * So the refresh token stays here, in the child's environment, and only a
+ * one-hour access token ever crosses the wire. That is strictly better than the
+ * arrangement it replaces, where a permanent credential sat on a shared volume.
+ */
+
+const TOKEN_ENDPOINT = 'https://oauth2.googleapis.com/token';
+
+/**
+ * Replace a token this long before it actually expires. A token that dies
+ * mid-flight is a failure the caller can do nothing about, and the exchange is
+ * cheap next to a failed tool call.
+ */
+const EXPIRY_MARGIN_MS = 120_000;
+
+interface CachedToken {
+  accessToken: string;
+  expiresAt: number;
+}
+
+/**
+ * Keyed by the CREDENTIAL, never a single "current token".
+ *
+ * A module-level current-token would be correct for one stdio process and
+ * silently wrong everywhere else: a Worker isolate serves many callers, so the
+ * first caller's identity would be handed to everyone after them. That is the
+ * same failure as the captured executor in #235 and the ambient store in #233 —
+ * three bugs, one shape, which is why this one is keyed from the start.
+ *
+ * The key is a hash rather than the token itself so that nothing which dumps or
+ * iterates this map (a heap snapshot, a debugger, a future logging line) puts a
+ * live credential in front of someone.
+ */
+const cache = new Map<string, CachedToken>();
+
+/**
+ * Exchanges currently in flight, so concurrent callers share ONE of them.
+ *
+ * Without this, `get` → `await exchange` → `set` has an await between the miss
+ * and the fill: every caller that arrives during that window also misses, and
+ * they all hit Google's token endpoint together. One process per caller hides
+ * it, but a Worker isolate serving many callers — or simply several tool calls
+ * in flight — turns a single refresh into a stampede, and being rate-limited
+ * for it produces exactly the intermittent auth failures this was meant to end.
+ *
+ * Keyed identically to `cache`, so two different credentials never wait on each
+ * other's exchange.
+ */
+const inFlight = new Map<string, Promise<CachedToken>>();
+
+/** Test seam: both maps are process-wide, so they do not unwind between tests. */
+export function clearAccessTokenCache(): void {
+  cache.clear();
+  inFlight.clear();
+}
+
+/**
+ * WebCrypto rather than `node:crypto`: this module is reachable from the Worker
+ * build, which has no node builtins. Both runtimes expose `crypto.subtle`.
+ */
+async function cacheKey(refreshToken: string, clientId: string): Promise<string> {
+  // NUL-separated, spelled as an escape so this source file stays text: it
+  // keeps a (clientId, refreshToken) pair from colliding with a different
+  // pair whose concatenation happens to match. Neither value can contain a
+  // NUL, which is what makes the boundary unambiguous.
+  const data = new TextEncoder().encode(`${clientId}\u0000${refreshToken}`);
+  const digest = await crypto.subtle.digest('SHA-256', data);
+  return Array.from(new Uint8Array(digest), (b) => b.toString(16).padStart(2, '0')).join('');
+}
+
+/**
+ * What a token source is: something that answers "who is this call acting as",
+ * or throws trying. It never answers `undefined` after being configured —
+ * see the failure note below.
+ */
+export type AccessTokenSource = () => Promise<string | undefined>;
+
+export interface TokenEnv {
+  GOG_ACCESS_TOKEN?: string;
+  GOG_REFRESH_TOKEN?: string;
+  GOG_CLIENT_ID?: string;
+  GOG_CLIENT_SECRET?: string;
+  [key: string]: string | undefined;
+}
+
+/**
+ * Build the token source for this environment, or `undefined` when nothing is
+ * configured — which leaves the backend acting as itself, exactly as every
+ * registration did before this existed.
+ *
+ * Precedence puts a directly-supplied `GOG_ACCESS_TOKEN` first: someone who
+ * already holds a token should not need an OAuth client to use it, and it keeps
+ * the #230 path working untouched.
+ */
+export function makeAccessTokenSource(env: TokenEnv): AccessTokenSource | undefined {
+  const direct = readEnvVar('GOG_ACCESS_TOKEN', { env });
+  if (direct) return async () => direct;
+
+  const refreshToken = readEnvVar('GOG_REFRESH_TOKEN', { env });
+  if (!refreshToken) return undefined;
+
+  const clientId = readEnvVar('GOG_CLIENT_ID', { env });
+  const clientSecret = readEnvVar('GOG_CLIENT_SECRET', { env });
+
+  // A refresh token with no OAuth client cannot mint anything, and the WRONG
+  // repair is to treat it as unconfigured: that falls back to the backend's own
+  // identity, which is the precise confusion this feature exists to remove. So
+  // the source exists and throws when used — `tools/list` still works, the
+  // server still starts, and the first tool call says what is missing.
+  if (!clientId || !clientSecret) {
+    const missing = [!clientId && 'GOG_CLIENT_ID', !clientSecret && 'GOG_CLIENT_SECRET']
+      .filter(Boolean)
+      .join(' and ');
+    return async () => {
+      throw new Error(
+        `GOG_REFRESH_TOKEN is set but ${missing} is not, so no access token can be minted. ` +
+          'Set the OAuth client alongside the refresh token, or unset GOG_REFRESH_TOKEN to use the backend’s own identity.',
+      );
+    };
+  }
+
+  return async () => {
+    const key = await cacheKey(refreshToken, clientId);
+    const hit = cache.get(key);
+    if (hit && hit.expiresAt - EXPIRY_MARGIN_MS > Date.now()) return hit.accessToken;
+
+    // Join the exchange already running for this credential, or start the one
+    // everyone else will join.
+    let pending = inFlight.get(key);
+    if (!pending) {
+      pending = exchange(refreshToken, clientId, clientSecret)
+        .then((minted) => {
+          cache.set(key, minted);
+          return minted;
+        })
+        // Dropped whether it resolved OR threw. Keeping a rejected promise here
+        // would make one transient failure permanent for every later caller —
+        // the opposite of the "failures are not cached" rule above.
+        .finally(() => inFlight.delete(key));
+      inFlight.set(key, pending);
+    }
+    const minted = await pending;
+    return minted.accessToken;
+  };
+}
+
+/**
+ * Exchange refresh -> access.
+ *
+ * THROWS on every failure, and never returns `undefined`. Returning nothing
+ * would let the call proceed as the backend's identity, and the caller would
+ * read someone else's mailbox while everything looked like success — the same
+ * reasoning that made a malformed token a 400 rather than an ignore in #235.
+ *
+ * Nothing here is cached on failure either, so a transient Google outage does
+ * not become a sticky one.
+ */
+async function exchange(refreshToken: string, clientId: string, clientSecret: string): Promise<CachedToken> {
+  let res: Response;
+  try {
+    res = await fetch(TOKEN_ENDPOINT, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+      body: new URLSearchParams({
+        grant_type: 'refresh_token',
+        refresh_token: refreshToken,
+        client_id: clientId,
+        client_secret: clientSecret,
+      }).toString(),
+    });
+  } catch (err) {
+    throw new Error(
+      `the Google token exchange could not be reached: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+
+  const body = (await res.json().catch(() => ({}))) as {
+    access_token?: string;
+    expires_in?: number;
+    error?: string;
+    error_description?: string;
+  };
+
+  if (!res.ok) {
+    // invalid_grant is the one worth naming, because it is not a bug and not
+    // transient: the credential is gone and a human has to enrol again. Google
+    // expires refresh tokens after 7 days while a consent screen is still in
+    // "Testing" mode, which is how this fleet has usually met it.
+    if (body.error === 'invalid_grant') {
+      throw new Error(
+        'the stored refresh token has expired or been revoked, so this account must be re-authorized ' +
+          '(commonly the 7-day limit on OAuth consent screens still in "Testing" mode). ' +
+          'Re-enrol with gog_auth_add_url + gog_auth_add_complete and store the new refresh token.',
+      );
+    }
+    // The refresh token is deliberately absent from this message — it is a
+    // long-lived credential and an error string travels into logs and model
+    // context.
+    throw new Error(
+      `the access token could not be refreshed (HTTP ${res.status}${body.error ? `, ${body.error}` : ''})`,
+    );
+  }
+
+  if (!body.access_token) {
+    throw new Error('the access token could not be refreshed: Google returned no access_token');
+  }
+
+  // Default to an hour if Google omits expires_in; the margin above covers the
+  // difference between that guess and reality.
+  const expiresInMs = (body.expires_in ?? 3600) * 1000;
+  return { accessToken: body.access_token, expiresAt: Date.now() + expiresInMs };
+}

package/src/remote-runner.ts

@@ -1,5 +1,6 @@
 import { readEnvVar } from '@chrischall/mcp-utils';
 import { setDefaultGogExecutor } from './runner.js';
+import { makeAccessTokenSource } from './google-token.js';
 import { makeFlyExecutor } from './connector-runtime.js';
 
 /**
@@ -54,6 +55,23 @@ export function useRemoteGogRunner(env: NodeJS.ProcessEnv = process.env): boolea
   // nothing — either alone is a misconfiguration, and silently spawning
   // instead would hide it until someone wondered why the binary was needed.
   if (!endpoint || !key) return false;
-  setDefaultGogExecutor(makeFlyExecutor(endpoint.replace(/\/+$/, ''), key));
+  // Whose Google identity this process acts as (#230). The backend holds ONE
+  // identity on its volume, so without this every caller of a hosted gog acts
+  // as whoever seeded it. Under mcp-host's `perUserChild` this process belongs
+  // to a single caller and its environment carries that caller's token, so
+  // forwarding it is the whole of "act as the person calling you".
+  //
+  // Read per call rather than captured here, because the executor outlives any
+  // one request and the claim being made is about a request. Absent when unset,
+  // which is every registration that predates per-caller auth.
+  //
+  // The source also covers the case where the registration stores a REFRESH
+  // token instead (#241) — the identity then belongs to the registration rather
+  // than to the backend's volume, and the short-lived token it mints is the
+  // only thing that crosses the wire. `undefined` when neither is configured,
+  // which leaves the backend acting as itself exactly as before.
+  setDefaultGogExecutor(
+    makeFlyExecutor(endpoint.replace(/\/+$/, ''), key, makeAccessTokenSource(env)),
+  );
   return true;
 }

package/src/tools/auth.ts

@@ -14,7 +14,12 @@ function registerAuthToolsWith(server: McpServer, defaultServices: string): void
     `Google API is not enabled on the OAuth client's project makes Google reject the WHOLE request ` +
     `with invalid_scope.`;
   server.registerTool('gog_auth_list', {
-    description: 'List all Google accounts stored in gogcli. Use this to check which accounts are configured and available.',
+    description:
+      'List the Google accounts stored in gogcli, with their scopes. This reads local ' +
+      'configuration only — it does not contact Google and does NOT tell you whether an account ' +
+      'still works: a signed-out account whose refresh token expired or was revoked is listed here ' +
+      'exactly like a healthy one, scopes and all. Use gog_auth_health to check whether an account ' +
+      'can actually authenticate.',
     annotations: { readOnlyHint: true },
     inputSchema: {},
   }, async () => {

package/src/tools/utils.ts

@@ -135,7 +135,18 @@ export function errorText(err: unknown): string {
   return err instanceof Error ? `Error: ${err.message}` : String(err);
 }
 
-const AUTH_ERROR_PATTERN = /\b(401|unauthorized|token.*(expired|revoked)|invalid_grant)\b/i;
+// Google saying "not authenticated" in its own words. Definitive: a retry
+// cannot turn a 401 into a success, so this outranks the transient signal below.
+const DEFINITE_AUTH_PATTERN = /\b(401|unauthorized|invalid_grant)\b/i;
+
+// A message that TALKS about an expired token. Suggestive, not definitive — and
+// it used to be `/token.*(expired|revoked)/`, whose greedy `.*` matched a token
+// mentioned anywhere and an expiry mentioned anywhere later in the same line
+// ("page token accepted; the export link has expired"). Now the two words must
+// actually be about each other.
+const STALE_TOKEN_PATTERN = /\b(?:access[ _-]?)?token\b[^.;\n]{0,40}\b(?:has\s+)?(?:been\s+)?(?:expired|revoked)\b|\b(?:expired|revoked)\s+(?:access[ _-]?)?token\b/i;
+
+const AUTH_ERROR_PATTERN = new RegExp(`${DEFINITE_AUTH_PATTERN.source}|${STALE_TOKEN_PATTERN.source}`, 'i');
 
 // A DEAD refresh token — the whole account is signed out, not just a stale
 // access token that would refresh silently. This is the recurring account-wide
@@ -207,8 +218,19 @@ export function formatAccountList(raw: string): string {
 export async function diagnose(err: unknown): Promise<CallToolResult> {
   const errText = errorText(err);
   const isInvalidGrant = INVALID_GRANT_PATTERN.test(errText);
-  const isAuthError = AUTH_ERROR_PATTERN.test(errText);
-  const isTransientError = !isAuthError && TRANSIENT_ERROR_PATTERN.test(errText);
+
+  // Precedence, and the reason for it. Reporting needs-auth is EXPENSIVE to be
+  // wrong about: re-authorization is a manual, human step, and it does not fix
+  // a 429. So a transient signal beats a merely SUGGESTIVE auth signal (a
+  // message that mentions an expired token) — the reported bug was servers
+  // flapping into needs-auth and working again seconds later, which is what
+  // being told to re-auth over a rate-limit looks like.
+  //
+  // It does NOT beat a definitive one. A literal 401 or invalid_grant is Google
+  // saying the credential will not work, and calling that "retry" would loop a
+  // caller forever against a request that can never succeed.
+  const isTransientError = !DEFINITE_AUTH_PATTERN.test(errText) && TRANSIENT_ERROR_PATTERN.test(errText);
+  const isAuthError = !isTransientError && AUTH_ERROR_PATTERN.test(errText);
   const isGridLimitError = GRID_LIMIT_ERROR_PATTERN.test(errText);
   const hint = isInvalidGrant
     ? INVALID_GRANT_HINT

package/src/worker.ts

@@ -38,7 +38,7 @@ import { gogAuth, type GogProps } from './connector-auth.js';
 // connector with all ~360 tools at once. Add whichever paths you want as separate
 // connectors in claude.ai (each authorizes with the same connector key).
 
-const VERSION = '2.19.2'; // x-release-please-version
+const VERSION = '2.21.0'; // x-release-please-version
 
 // Build an McpAgent subclass whose init() registers `registrars` onto its server,
 // each handler wrapped in the ALS scope carrying the per-session Fly executor.

package/tests/connector-runtime.test.ts

@@ -120,6 +120,57 @@ describe('makeFlyExecutor', () => {
     expect(init.body).toBe(JSON.stringify({ args: ['sheets', 'get', 'A1'] }));
   });
 
+  // A hosted gog authenticates as whoever seeded the Fly volume, not as the
+  // person calling it (#230). mcp-host can give each caller their own child
+  // carrying their own GOG_ACCESS_TOKEN, so the missing link is the child
+  // handing that token to the backend for ITS call only — never as something
+  // ambient on the box, which would be the same shared identity from the other
+  // direction.
+  describe('per-request access token', () => {
+    function okFetch() {
+      const fetchMock = vi.fn(async () => ({ ok: true, json: async () => ({ stdout: 'ok' }) }));
+      vi.stubGlobal('fetch', fetchMock);
+      return fetchMock;
+    }
+    function bodyOf(fetchMock: { mock: { calls: unknown[][] } }, i = 0): Record<string, unknown> {
+      const [, init] = fetchMock.mock.calls[i] as [string, RequestInit];
+      return JSON.parse(init.body as string) as Record<string, unknown>;
+    }
+
+    it('sends the token with the request when one is available', async () => {
+      const fetchMock = okFetch();
+      const exec = makeFlyExecutor(ENDPOINT, KEY, () => 'ya29.caller-token');
+      await exec(['auth', 'status'], {});
+      expect(bodyOf(fetchMock)).toEqual({ args: ['auth', 'status'], accessToken: 'ya29.caller-token' });
+    });
+
+    it('omits the field entirely when there is no token', async () => {
+      // Absent, not null or "": the backend distinguishes "act as the caller"
+      // from "act as the box", and a present-but-empty field would be a third
+      // state neither side has a meaning for.
+      const fetchMock = okFetch();
+      for (const provider of [undefined, () => undefined, () => '']) {
+        vi.clearAllMocks();
+        const exec = makeFlyExecutor(ENDPOINT, KEY, provider as (() => string | undefined) | undefined);
+        await exec(['auth', 'status'], {});
+        expect(bodyOf(fetchMock)).toEqual({ args: ['auth', 'status'] });
+      }
+    });
+
+    it('reads the token per CALL, not once when the executor is built', async () => {
+      // The whole contract is "this token belongs to this request". Reading it
+      // once at construction would pin the first caller's identity onto an
+      // executor that outlives them — exactly the bug this closes, rebuilt.
+      const fetchMock = okFetch();
+      const tokens = ['first', 'second'];
+      const exec = makeFlyExecutor(ENDPOINT, KEY, () => tokens.shift());
+      await exec(['auth', 'status'], {});
+      await exec(['auth', 'status'], {});
+      expect(bodyOf(fetchMock, 0).accessToken).toBe('first');
+      expect(bodyOf(fetchMock, 1).accessToken).toBe('second');
+    });
+  });
+
   // Everything below is the file-arg wire contract. The Worker has no filesystem
   // and no gog binary, so a GogFileArg must cross the wire STRUCTURED and be
   // materialized on the Fly runner. If this layer ever flattened it back into an