gogcli-mcp 4.2.5 → 4.4.0

package/src/send-confirm-token.ts

@@ -0,0 +1,167 @@
+import { createHash, createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+import { readEnvVar } from '@chrischall/mcp-utils';
+
+// ============================================================================
+// THE TOKEN FALLBACK for the Gmail dispatch rail (gmail-dispatch-guard.ts).
+//
+// A client with no MCP elicitation (claude.ai, measured) cannot be shown the
+// confirmation prompt, so every send is refused there. With
+// GOG_SEND_CONFIRM_FALLBACK=token the rail instead runs two phases: phase 1
+// returns the full preview plus a token and sends nothing; phase 2 presents the
+// token, the tool RE-READS what it would send, and dispatches only if that still
+// hashes to what the token was issued for.
+//
+// WHAT THIS DOES AND DOES NOT PROVE. Unlike elicitation, the approval here is a
+// tool argument, so the gate is the model honouring "show this to the user and
+// wait". The token cannot make the model ask; what it guarantees is that what
+// is sent matches what was previewed — a draft edited in a mail client (its
+// messageId rotates), a changed recipient or body, or a swapped attachment
+// between the two calls all refuse. Caller-supplied files are bound by content
+// hash; a stored draft's attachments by name and size, since Gmail's
+// attachment ids are unstable and any edit rotates the messageId anyway. One
+// approval acts once, for one tool, account and target, within the TTL — per
+// PROCESS: spent tokens live in memory, so with a shared GOG_CONFIRM_SECRET a
+// restart or a second instance would accept a spent token again until it
+// expires. That is why the mode is opt-in.
+// ============================================================================
+
+export type ConfirmTokenError = 'DRAFT_CHANGED' | 'TOKEN_EXPIRED' | 'TOKEN_REUSED' | 'TOKEN_INVALID';
+
+/** What a token is bound to. Every field must match on phase 2. */
+export interface ConfirmBinding {
+  tool: string;
+  account: string;
+  /** The draftId / messageId / query the dispatch acts on. */
+  target: string;
+  /** A version of the target that rotates on edit — a draft's messageId. */
+  revision?: string;
+  /** {@link hashSendPayload} of the canonical send payload. */
+  payloadHash: string;
+}
+
+export type ConfirmTokenVerdict =
+  | { ok: true }
+  | { ok: false; error: ConfirmTokenError; reason?: 'payload-changed' | 'message-id-rotated' };
+
+export const CONFIRM_TOKEN_TTL_DEFAULT_SECONDS = 600;
+
+const PREFIX = 'gct1';
+
+type Claims = { t: string; a: string; g: string; r?: string; h: string; iat: number; exp: number; n: string };
+
+let secret: Buffer | undefined;
+// nonce → expiry (ms). Entries are dropped once they would have expired
+// anyway, so the set is bounded by the tokens spent within one TTL. In memory
+// only: see the header on GOG_CONFIRM_SECRET and restarts.
+const spent = new Map<string, number>();
+
+/** GOG_SEND_CONFIRM_FALLBACK=token turns the fallback on. Anything else is off. */
+export function sendConfirmFallbackEnabled(): boolean {
+  return readEnvVar('GOG_SEND_CONFIRM_FALLBACK')?.trim().toLowerCase() === 'token';
+}
+
+export function confirmTokenTtlSeconds(): number {
+  const raw = readEnvVar('GOG_CONFIRM_TTL_SECONDS')?.trim();
+  if (raw && /^\d+$/.test(raw)) {
+    const n = Number(raw);
+    if (n > 0) return n;
+  }
+  return CONFIRM_TOKEN_TTL_DEFAULT_SECONDS;
+}
+
+// GOG_CONFIRM_SECRET ends in _SECRET, so runner.ts strips it from every gog
+// child — it never leaves this process.
+function hmacKey(): Buffer {
+  if (!secret) {
+    const configured = readEnvVar('GOG_CONFIRM_SECRET');
+    secret = configured ? Buffer.from(configured, 'utf8') : randomBytes(32);
+  }
+  return secret;
+}
+
+/** Test seam: forget the secret (a "restart") and every spent token. */
+export function resetConfirmTokenState(): void {
+  secret = undefined;
+  spent.clear();
+}
+
+// Sorted keys, undefined dropped: the same payload re-read on phase 2 must
+// hash identically however its object was assembled.
+function canonicalize(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(canonicalize);
+  if (value && typeof value === 'object') {
+    const out: Record<string, unknown> = {};
+    for (const key of Object.keys(value as Record<string, unknown>).sort()) {
+      const v = (value as Record<string, unknown>)[key];
+      if (v !== undefined) out[key] = canonicalize(v);
+    }
+    return out;
+  }
+  return value;
+}
+
+/** SHA-256 (hex) of the canonical JSON of a send payload. */
+export function hashSendPayload(payload: unknown): string {
+  return createHash('sha256').update(JSON.stringify(canonicalize(payload))).digest('hex');
+}
+
+function sign(body: string): string {
+  return createHmac('sha256', hmacKey()).update(`${PREFIX}.${body}`).digest('base64url');
+}
+
+export function issueConfirmToken(binding: ConfirmBinding, now = Date.now()): { token: string; expiresAt: string } {
+  const exp = now + confirmTokenTtlSeconds() * 1000;
+  const claims: Claims = {
+    t: binding.tool,
+    a: binding.account,
+    g: binding.target,
+    ...(binding.revision === undefined ? {} : { r: binding.revision }),
+    h: binding.payloadHash,
+    iat: now,
+    exp,
+    n: randomBytes(16).toString('base64url'),
+  };
+  const body = Buffer.from(JSON.stringify(claims), 'utf8').toString('base64url');
+  return { token: `${PREFIX}.${body}.${sign(body)}`, expiresAt: new Date(exp).toISOString() };
+}
+
+function signatureMatches(body: string, sig: string): boolean {
+  const expected = Buffer.from(sign(body), 'utf8');
+  const actual = Buffer.from(sig, 'utf8');
+  return expected.length === actual.length && timingSafeEqual(expected, actual);
+}
+
+function parseClaims(body: string): Claims | undefined {
+  try {
+    return JSON.parse(Buffer.from(body, 'base64url').toString('utf8')) as Claims;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Check a phase-2 token against the binding recomputed from a fresh re-read.
+ * Only an `ok` verdict consumes the token; a DRAFT_CHANGED leaves it unspent,
+ * because the approval it carries is still true of the content it names.
+ */
+export function verifyConfirmToken(token: string, binding: ConfirmBinding, now = Date.now()): ConfirmTokenVerdict {
+  for (const [nonce, exp] of spent) if (exp < now) spent.delete(nonce);
+
+  const parts = token.split('.');
+  if (parts.length !== 3 || parts[0] !== PREFIX || !parts[1] || !parts[2]) return { ok: false, error: 'TOKEN_INVALID' };
+  const [, body, sig] = parts as [string, string, string];
+  if (!signatureMatches(body, sig)) return { ok: false, error: 'TOKEN_INVALID' };
+  const claims = parseClaims(body);
+  if (!claims) return { ok: false, error: 'TOKEN_INVALID' };
+
+  if (claims.t !== binding.tool || claims.a !== binding.account || claims.g !== binding.target) {
+    return { ok: false, error: 'TOKEN_INVALID' };
+  }
+  if (spent.has(claims.n)) return { ok: false, error: 'TOKEN_REUSED' };
+  if (now > claims.exp) return { ok: false, error: 'TOKEN_EXPIRED' };
+  if (claims.r !== binding.revision) return { ok: false, error: 'DRAFT_CHANGED', reason: 'message-id-rotated' };
+  if (claims.h !== binding.payloadHash) return { ok: false, error: 'DRAFT_CHANGED', reason: 'payload-changed' };
+
+  spent.set(claims.n, claims.exp);
+  return { ok: true };
+}

package/src/tools/api.ts

@@ -1,6 +1,48 @@
 import { McpServer } from '@modelcontextprotocol/server';
 import { z } from 'zod';
-import { accountParam, runOrDiagnose } from './utils.js';
+import { errorResult } from '@chrischall/mcp-utils';
+import { accountParam, errorText, runOrDiagnose } from './utils.js';
+import { assertSafeForwardedArgs } from '../arg-guard.js';
+import { confineAtFile } from '../file-roots.js';
+import { pos } from '../argv.js';
+import type { GogArg } from '../runner.js';
+import { gatedElsewhere } from '../dispatch-confirmation.js';
+
+// Gmail methods gog_api_call refuses outright (audit SEC-2). `allowWrite` is a
+// boolean the MODEL sets, so it cannot stand in for the user's confirmation of
+// a send: `*.send` must go through gog_gmail_send / gog_gmail_drafts_send, which
+// ask the user. Forwarding addresses, auto-forwarding, filters (which can
+// forward) and delegates route FUTURE mail to someone else and are refused for
+// the same reason. --gmail-no-send is pinned on as a runtime backstop too.
+const GMAIL_API_BLOCKED = /(?:\.send$|forwarding|filters\.create|filters\.update|delegates\.create)/i;
+
+// The same reasoning for every other action the dispatch rail gates (#400):
+// the dedicated tool asks the user, so the raw API method must not be a way
+// around it. Anchored on a `.` or the start so a Discovery id with the API
+// prefix (`chat.spaces.messages.create`) matches too.
+const DISPATCH_API_BLOCKED: Record<string, Array<{ method: RegExp; does: string; tool: string }>> = {
+  chat: [{ method: /(?:^|\.)spaces\.messages\.create$/i, does: 'posts a Chat message', tool: 'gog_chat_messages_send / gog_chat_dm_send' }],
+  drive: [{ method: /(?:^|\.)permissions\.(?:create|update)$/i, does: 'grants access to a file', tool: 'gog_drive_share' }],
+  classroom: [
+    { method: /(?:^|\.)courses\.announcements\.create$/i, does: 'posts to a class', tool: 'gog_classroom_announcements_create' },
+    { method: /(?:^|\.)invitations\.create$/i, does: 'invites someone to a class', tool: 'gog_classroom_invitations_create' },
+  ],
+  calendar: [
+    { method: /(?:^|\.)events\.(?:insert|import|quickadd)$/i, does: 'can put an event on guests\' calendars', tool: 'gog_calendar_create' },
+    { method: /(?:^|\.)events\.(?:update|patch)$/i, does: 'can change what guests see', tool: 'gog_calendar_update / gog_calendar_respond' },
+  ],
+};
+
+export function refusedApiCall(api: string, method: string): string | undefined {
+  const name = api.trim().toLowerCase();
+  const m = method.trim();
+  if (name === 'gmail' && GMAIL_API_BLOCKED.test(m)) {
+    return `gmail ${method} is not available through gog_api_call: it sends or forwards mail. `
+      + 'Use gog_gmail_send / gog_gmail_drafts_send (which ask the user to confirm) or the dedicated gog_gmail_* tool.';
+  }
+  const hit = (Object.hasOwn(DISPATCH_API_BLOCKED, name) ? DISPATCH_API_BLOCKED[name] : [])!.find((b) => b.method.test(m));
+  return hit ? gatedElsewhere(`${name} ${m}`, 'gog_api_call', hit.does, hit.tool) : undefined;
+}
 
 // Generic Google Discovery API access (gog 0.31). gog_api_list / gog_api_describe
 // are read-only Discovery lookups; gog_api_call is a Discovery-backed escape
@@ -15,7 +57,7 @@ export function registerApiTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ all, account }) => {
-    const args = ['api', 'list'];
+    const args: GogArg[] = ['api', 'list'];
     if (all) args.push('--all');
     return runOrDiagnose(args, { account });
   });
@@ -30,13 +72,13 @@ export function registerApiTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ api, version, method, account }) => {
-    const args = ['api', 'describe', api, version];
-    if (method) args.push(method);
+    const args: GogArg[] = ['api', 'describe', pos(api), pos(version)];
+    if (method) args.push(pos(method));
     return runOrDiagnose(args, { account });
   });
 
   server.registerTool('gog_api_call', {
-    description: 'Call any Discovery-described Google API method directly — an escape hatch for endpoints gog has no dedicated tool for. Find the exact api/version/method/params with gog_api_describe first. Read methods (GET/LIST) run as-is. Mutating methods (POST/PUT/PATCH/DELETE) are refused unless you set allowWrite=true — keep it false to preview, or set dryRun=true to print the intended request without sending it.',
+    description: 'Call any Discovery-described Google API method directly — an escape hatch for endpoints gog has no dedicated tool for. Find the exact api/version/method/params with gog_api_describe first. Read methods (GET/LIST) run as-is. Mutating methods (POST/PUT/PATCH/DELETE) are refused unless you set allowWrite=true — keep it false to preview, or set dryRun=true to print the intended request without sending it. Gmail send and forwarding methods (users.messages.send, users.drafts.send, forwarding/auto-forwarding, filters, delegates) are refused — use the dedicated gog_gmail_* tools, which ask the user to confirm. So are the other methods a dedicated tool asks about: Chat spaces.messages.create, Drive permissions.create/update, Classroom courses.announcements.create and invitations.create, and Calendar events.insert/import/quickAdd/update/patch.',
     annotations: { destructiveHint: true },
     inputSchema: z.object({
       api: z.string().describe('Discovery API name (e.g. drive, gmail, calendar)'),
@@ -50,7 +92,18 @@ export function registerApiTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ api, version, method, params, body, scope, allowWrite, dryRun, account }) => {
-    const args = ['api', 'call', api, version, method];
+    try {
+      assertSafeForwardedArgs([api, version, method]);
+      const refusal = refusedApiCall(api, method);
+      if (refusal) throw new Error(refusal);
+      // gog reads `@path` from the host for --body (and --params): confine it
+      // like every other server-side path (SEC-3/SEC-4).
+      if (body) confineAtFile(body, 'body');
+      if (params) confineAtFile(params, 'params');
+    } catch (err) {
+      return errorResult(errorText(err));
+    }
+    const args: GogArg[] = ['api', 'call', pos(api), pos(version), pos(method)];
     if (params) args.push(`--params=${params}`);
     if (body) args.push(`--body=${body}`);
     if (scope) args.push(`--scope=${scope}`);
@@ -60,6 +113,6 @@ export function registerApiTools(server: McpServer): void {
     if (dryRun) args.push('--dry-run');
     // Fleet convention: --force is appended LAST (after --dry-run when both are set).
     if (allowWrite) args.push('--force');
-    return runOrDiagnose(args, { account });
+    return runOrDiagnose(args, { account, gmailNoSend: true });
   });
 }

package/src/tools/appscript.ts

@@ -7,6 +7,9 @@ import {
   paginationParams,
   pushPaginationFlags,
 } from './utils.js';
+import { pos } from '../argv.js';
+import { confinePath } from '../file-roots.js';
+import type { GogArg } from '../runner.js';
 
 // Google Apps Script (gog >= 0.38.0 for pull/deployments/versions).
 //
@@ -40,7 +43,7 @@ export function registerAppScriptTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ scriptId, account }) => {
-    return runOrDiagnose(['appscript', 'get', scriptId], { account });
+    return runOrDiagnose(['appscript', 'get', pos(scriptId)], { account });
   });
 
   server.registerTool('gog_appscript_content', {
@@ -54,7 +57,7 @@ export function registerAppScriptTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ scriptId, account }) => {
-    return runOrDiagnose(['appscript', 'content', scriptId], { account });
+    return runOrDiagnose(['appscript', 'content', pos(scriptId)], { account });
   });
 
   server.registerTool('gog_appscript_pull', {
@@ -68,12 +71,13 @@ export function registerAppScriptTools(server: McpServer): void {
     annotations: { destructiveHint: true },
     inputSchema: z.object({
       scriptId: scriptIdParam,
-      dir: z.string().describe('Destination directory, resolved on the machine where gog runs'),
+      dir: z.string().describe('Destination directory, resolved on the machine where gog runs; must be inside the server\'s GOG_FILE_ROOTS directories'),
       overwrite: z.boolean().optional().describe('Overwrite files that already exist in dir'),
       account: accountParam,
     }),
   }, async ({ scriptId, dir, overwrite, account }) => {
-    const args = ['appscript', 'pull', scriptId, dir];
+    confinePath(dir, 'dir');
+    const args: GogArg[] = ['appscript', 'pull', pos(scriptId), pos(dir)];
     if (overwrite) args.push('--overwrite');
     return runOrDiagnose(args, { account });
   });
@@ -90,7 +94,7 @@ export function registerAppScriptTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ title, parentId, account }) => {
-    const args = ['appscript', 'create', `--title=${title}`];
+    const args: GogArg[] = ['appscript', 'create', `--title=${title}`];
     if (parentId) args.push(`--parent-id=${parentId}`);
     return runOrDiagnose(args, { account });
   });
@@ -107,7 +111,7 @@ export function registerAppScriptTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ scriptId, max, pageToken, page, all, account }) => {
-    const args = ['appscript', 'deployments', scriptId];
+    const args: GogArg[] = ['appscript', 'deployments', pos(scriptId)];
     pushPaginationFlags(args, { max, pageToken, page, all });
     return runOrDiagnose(args, { account });
   });
@@ -123,7 +127,7 @@ export function registerAppScriptTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ scriptId, max, pageToken, page, all, account }) => {
-    const args = ['appscript', 'versions', scriptId];
+    const args: GogArg[] = ['appscript', 'versions', pos(scriptId)];
     pushPaginationFlags(args, { max, pageToken, page, all });
     return runOrDiagnose(args, { account });
   });
@@ -161,7 +165,7 @@ export function registerAppScriptTools(server: McpServer): void {
         throw new Error(`params must be a JSON ARRAY of positional arguments, e.g. '["a", 1]' — Apps Script takes positional arguments, not named ones. Received: ${params}`);
       }
     }
-    const args = ['appscript', 'run', scriptId, functionName];
+    const args: GogArg[] = ['appscript', 'run', pos(scriptId), pos(functionName)];
     if (params !== undefined) args.push(`--params=${params}`);
     if (devMode) args.push('--dev-mode');
     return runOrDiagnose(args, { account });

package/src/tools/auth.ts

@@ -3,6 +3,11 @@ import { z } from 'zod';
 import { run } from '../runner.js';
 import { errorResult, rawTextResult } from '@chrischall/mcp-utils';
 import { errorText, formatAuthHealth, registerRunTool } from './utils.js';
+import { pos } from '../argv.js';
+import type { GogArg } from '../runner.js';
+
+/** The `gog auth` subcommands gog_auth_run may run — account management only. */
+export const AUTH_RUN_SUBCOMMANDS: readonly string[] = ['list', 'status', 'services', 'remove', 'alias'];
 
 // Register the auth tools with a specific least-privilege default `services`.
 // Kept internal so the exported `registerAuthTools` stays a bare
@@ -109,7 +114,7 @@ function registerAuthToolsWith(server: McpServer, defaultServices: string): void
     }),
   }, async ({ email, services = defaultServices, extraScopes }) => {
     try {
-      const args = ['auth', 'add', email, '--services', services];
+      const args: GogArg[] = ['auth', 'add', pos(email), '--services', services];
       // --force-consent rides along with extraScopes and only with them. Google
       // re-prompts for a NEW scope only when consent is forced; without it the
       // account can come back still missing the scope, with a success message —
@@ -147,7 +152,7 @@ function registerAuthToolsWith(server: McpServer, defaultServices: string): void
       // (the whole point when recovering from a dead one). redactMode 'tokens'
       // keeps the consent URL's scope names intact (the shared redactor mangles
       // them) while still stripping any real token — a step-1 URL carries none.
-      const args = ['auth', 'add', email, '--remote', '--step', '1', '--services', services, '--force-consent'];
+      const args: GogArg[] = ['auth', 'add', pos(email), '--remote', '--step', '1', '--services', services, '--force-consent'];
       if (extraScopes) args.push(`--extra-scopes=${extraScopes}`);
       return rawTextResult(await run(args, { redactMode: 'tokens' }));
     } catch (err) {
@@ -178,7 +183,7 @@ function registerAuthToolsWith(server: McpServer, defaultServices: string): void
     }),
   }, async ({ email, redirectUrl, services = defaultServices, extraScopes }) => {
     try {
-      const args = ['auth', 'add', email, '--remote', '--step', '2', '--auth-url', redirectUrl,
+      const args: GogArg[] = ['auth', 'add', pos(email), '--remote', '--step', '2', '--auth-url', redirectUrl,
         '--services', services, '--force-consent'];
       if (extraScopes) args.push(`--extra-scopes=${extraScopes}`);
       return rawTextResult(await run(args));
@@ -187,10 +192,15 @@ function registerAuthToolsWith(server: McpServer, defaultServices: string): void
     }
   });
 
+  // Account management only (audit SEC-3). `auth tokens export` writes a
+  // long-lived refresh token to a file, and `credentials` / `keyring` /
+  // `tokens import` handle the OAuth client secret and the token store — none of
+  // that belongs behind a model-callable escape hatch. `add` has its own tools.
   registerRunTool(server, {
     service: 'auth',
     examples: '"remove", "alias", "list"',
     omitAccount: true,
+    allowedSubcommands: AUTH_RUN_SUBCOMMANDS,
     note: 'For browser-based authorization, use gog_auth_add instead.',
   });
 }