gogcli-mcp 4.2.4 → 4.3.0

package/src/run-path-guard.ts

@@ -0,0 +1,118 @@
+// GOG_FILE_ROOTS for the escape hatches (audit SEC-3/SEC-4).
+//
+// The structured tools confine every server-side path they accept, but a
+// `gog_<service>_run` forwards a model-supplied string[] verbatim, and gog reads
+// and writes local files through it just as readily: `drive upload
+// <gog's credentials.json>`, `gmail drafts create --attach=~/.ssh/id_rsa`,
+// `docs export --out=~/.zshrc`. Left open, that is the read-and-exfiltrate and
+// write-anywhere primitive the roots exist to close, and GOG_FILE_ROOTS would
+// only look like a boundary. So, before an escape hatch runs:
+//
+// - subcommands whose local path is a POSITIONAL are refused outright. Which
+//   positional is the path depends on the command, and kong lets flags sit
+//   anywhere, so it cannot be picked out reliably; each has a dedicated tool
+//   that confines it.
+// - every path-bearing FLAG value (`--out`, `--attach`, `--file`, `--*-file`,
+//   `--out-dir`, `--dir`, an `@file` JSON input, ...) must resolve inside the
+//   roots, whether it is attached (`--out=x`) or the next token (`--out x`).
+// - the short spellings `-o` / `-f` are refused, since a cluster (`-yf x`,
+//   `-o/etc/x`) hides the value; the long form is confined instead.
+// - flags that make gog RUN a local program (`--on-change`, `--on-new`,
+//   `--mmdc`) are refused: a model-chosen shell command is a strictly worse
+//   primitive than a path.
+//
+// Kept out of runner.ts for the same reason as arg-guard.ts: tool tests
+// automock the runner, and this has to run for real in the tool handlers.
+
+import { confinePath } from './file-roots.js';
+
+/** Escape-hatch subcommands whose local path is positional, and the tool to use instead. */
+const POSITIONAL_PATH_SUBCOMMANDS: Readonly<Record<string, Readonly<Record<string, string>>>> = {
+  appscript: { pull: 'gog_appscript_pull' },
+  drive: { upload: 'gog_drive_upload', sync: 'gog_drive_sync_push' },
+  gmail: { import: 'gog_gmail_import' },
+  slides: {
+    'add-slide': 'gog_slides_add_slide',
+    'insert-image': 'gog_slides_insert_image',
+    'replace-slide': 'gog_slides_replace_slide',
+  },
+};
+
+/** Long flags (lower-case, no dashes) whose value is a local path (from `gog schema`, v0.41.0). */
+const PATH_FLAGS = new Set(['out', 'output', 'out-dir', 'output-dir', 'dir', 'worker-dir', 'attach', 'file', 'key', 'cert', 'replacements']);
+
+/** Per service: flags that look like paths but carry Drive file IDs. */
+const ID_FLAGS: Readonly<Record<string, ReadonlySet<string>>> = {
+  drive: new Set(['file', 'filter-file']),
+};
+
+/** Flags whose value gog executes as a local command or program. */
+const EXEC_FLAGS = new Set(['on-change', 'on-new', 'mmdc']);
+
+// Single-dash clusters containing -o (--out) or -f (--file).
+const SHORT_PATH_CLUSTER = /^-(?!-)[A-Za-z]*[of]/;
+
+const LONG_FLAG = /^--([A-Za-z0-9][A-Za-z0-9-]*)(?:=([\s\S]*))?$/;
+
+function isPathFlag(service: string, name: string): boolean {
+  if (ID_FLAGS[service]?.has(name)) return false;
+  return PATH_FLAGS.has(name) || name.endsWith('-file');
+}
+
+function confineFlagValue(flag: string, value: string): void {
+  // `-` is stdin/stdout, which never names a file on the host.
+  if (value === '-') return;
+  confinePath(value, flag);
+  // kong splits a repeatable ([]string) flag on commas, so `--attach=a,b` is
+  // two paths: each must be inside the roots too.
+  for (const part of value.split(',')) {
+    if (part !== '' && part !== '-') confinePath(part, flag);
+  }
+}
+
+/** The dedicated tool to use when `gog <service> <subcommand>` is refused for a positional path, else undefined. */
+export function positionalPathTool(service: string, subcommand: string): string | undefined {
+  return POSITIONAL_PATH_SUBCOMMANDS[service]?.[subcommand];
+}
+
+/**
+ * Throw unless every local path in an escape-hatch call (`gog <service>
+ * <subcommand> ...args`) lies inside GOG_FILE_ROOTS (or the private attachment
+ * download root), and nothing in it would run a local program.
+ */
+export function assertRunPathsConfined(service: string, subcommand: string, args: readonly string[]): void {
+  const dedicated = positionalPathTool(service, subcommand);
+  if (dedicated) {
+    throw new Error(
+      `gog ${service} ${subcommand} reads or writes a local path given as a positional argument, so it is not available through gog_${service}_run. Use ${dedicated}, which confines the path to GOG_FILE_ROOTS.`,
+    );
+  }
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (SHORT_PATH_CLUSTER.test(arg)) {
+      throw new Error(
+        `The flag ${arg} is not allowed here: spell a path flag out as --out or --file (e.g. --out=<path>) so its path can be checked against GOG_FILE_ROOTS.`,
+      );
+    }
+    const match = LONG_FLAG.exec(arg);
+    if (!match) continue;
+    const name = match[1].toLowerCase();
+    if (EXEC_FLAGS.has(name)) {
+      throw new Error(`The flag --${name} is not allowed here: it runs a local program chosen by the caller.`);
+    }
+    const isJson = name.endsWith('-json');
+    if (!isJson && !isPathFlag(service, name)) continue;
+    let value = match[2];
+    if (value === undefined) {
+      value = args[i + 1];
+      if (value === undefined) continue;
+      i++;
+    }
+    if (isJson) {
+      // Inline JSON passes; `@path` reads a file, `@-` reads stdin.
+      if (value.startsWith('@')) confineFlagValue(`--${name}`, value.slice(1));
+      continue;
+    }
+    confineFlagValue(`--${name}`, value);
+  }
+}

package/src/runner.ts

@@ -2,6 +2,10 @@ import type { ChildProcess } from 'node:child_process';
 import { delimiter, join } from 'node:path';
 import { currentCallSignal, killOnCancel, parseBoolEnv, readEnvVar, redactSecrets as redactSharedSecrets } from '@chrischall/mcp-utils';
 import { naiveSourceTimeZone } from './timestamps.js';
+import { forbiddenArgReason } from './arg-guard.js';
+import { isGogPositional, type GogPositional } from './argv.js';
+
+export type { GogPositional } from './argv.js';
 
 export type Spawner = (
   command: string,
@@ -55,10 +59,10 @@ export interface GogFileArg {
   positional?: boolean;
 }
 
-export type GogArg = string | GogFileArg;
+export type GogArg = string | GogFileArg | GogPositional;
 
 export function isGogFileArg(arg: GogArg): arg is GogFileArg {
-  return typeof arg !== 'string';
+  return typeof arg !== 'string' && arg.kind === 'file';
 }
 
 export interface RunOptions {
@@ -97,6 +101,15 @@ export interface RunOptions {
   // (see OPAQUE_FIELD_VALUE) — so a field carrying real prose, which is where a
   // real leaked token would live, still gets redacted normally.
   opaqueFields?: readonly string[];
+  // Inject gog's global --gmail-no-send, which blocks every Gmail send
+  // (send, reply, forward, drafts send, users.messages.send via api call) at
+  // runtime. Set by the escape hatches so none of them can dispatch mail
+  // around the confirmation rail.
+  gmailNoSend?: boolean;
+  // Ceiling on the bytes gog may write to stdout. Past it the child is killed
+  // and the call rejects, so one oversized download (a multi-GB Drive file read
+  // through runBinary) cannot exhaust this process's memory.
+  maxOutputBytes?: number;
 }
 
 const TIMEOUT_MS = 30_000;
@@ -107,7 +120,7 @@ const TIMEOUT_MS = 30_000;
 // so the requirement change is surfaced in the release notes (see
 // .github/release.yml). This is the single source of truth for the required
 // version; keep the README/CLAUDE.md mention in sync.
-export const MIN_GOG_VERSION = '0.40.0';
+export const MIN_GOG_VERSION = '0.41.0';
 
 // Interpret the GOG_READONLY kill-switch. `readEnvVar` already treats blank
 // values, 'undefined'/'null' sentinels, and unresolved .mcpb placeholders
@@ -300,8 +313,8 @@ function formatTimeout(ms: number): string {
 // plain argv, and remove the temp dir afterwards — on success, on a non-zero
 // exit, and on timeout alike. A leaked temp file holds user email content.
 async function spawnWithTempFiles(
-  args: GogArg[],
-  opts: { timeout?: number; interactive?: boolean; spawner?: Spawner; binary?: boolean },
+  args: Array<string | GogFileArg>,
+  opts: { timeout?: number; interactive?: boolean; spawner?: Spawner; binary?: boolean; maxOutputBytes?: number },
 ): Promise<string> {
   const { mkdtemp, mkdir, writeFile, rm } = await import('node:fs/promises');
   const { tmpdir } = await import('node:os');
@@ -350,8 +363,8 @@ async function spawnWithTempFiles(
 // to happen synchronously within the `run()` call, which the fake-timer tests
 // in tests/runner.test.ts depend on.
 function spawnExecutor(
-  args: GogArg[],
-  opts: { timeout?: number; interactive?: boolean; spawner?: Spawner; binary?: boolean },
+  args: Array<string | GogFileArg>,
+  opts: { timeout?: number; interactive?: boolean; spawner?: Spawner; binary?: boolean; maxOutputBytes?: number },
 ): Promise<string> {
   if (args.some(isGogFileArg)) {
     return spawnWithTempFiles(args, opts);
@@ -365,9 +378,9 @@ function spawnExecutor(
 // injected `spawner` bypasses the real child_process spawn.
 async function spawnGog(
   fullArgs: string[],
-  opts: { timeout?: number; interactive?: boolean; spawner?: Spawner; binary?: boolean },
+  opts: { timeout?: number; interactive?: boolean; spawner?: Spawner; binary?: boolean; maxOutputBytes?: number },
 ): Promise<string> {
-  const { timeout, interactive = false, spawner, binary = false } = opts;
+  const { timeout, interactive = false, spawner, binary = false, maxOutputBytes } = opts;
   const spawn = spawner ?? (await import('node:child_process')).spawn as unknown as Spawner;
   const effectiveTimeout = timeout ?? TIMEOUT_MS;
 
@@ -404,7 +417,19 @@ async function spawnGog(
       reject(new Error(`gog timed out after ${formatTimeout(effectiveTimeout)}`));
     }, effectiveTimeout);
 
-    child.stdout!.on('data', (chunk: Buffer) => { stdoutChunks.push(chunk); });
+    let stdoutBytes = 0;
+    child.stdout!.on('data', (chunk: Buffer) => {
+      if (settled) return;
+      stdoutBytes += chunk.length;
+      if (maxOutputBytes !== undefined && stdoutBytes > maxOutputBytes) {
+        settled = true;
+        stopWatching();
+        child.kill();
+        reject(new Error(`gog output exceeded the limit: more than ${maxOutputBytes} bytes`));
+        return;
+      }
+      stdoutChunks.push(chunk);
+    });
     child.stderr!.on('data', (chunk: Buffer) => { stderrChunks.push(chunk); });
 
     child.on('close', (code: number | null) => {
@@ -458,12 +483,51 @@ async function spawnGog(
 // Assemble the full gog argv: the always-injected flags (--json/--color=never,
 // --no-input unless interactive, --readonly when opted in), --account, then the
 // caller's args. Shared by run() and runBinary() so both get identical flags.
+// Split the caller's argv into flag position and positional position.
+// pos()-marked values, positional file args, and anything after an explicit
+// `--` are positionals; they go after ONE `--` at the very end, in their
+// original order, so a value that starts with '-' is data, never a flag
+// (audit BUG-1). Commands and flags keep their relative order. With nothing
+// positional the argv is returned unchanged — no `--` at all.
+function placePositionals(args: GogArg[]): { flags: Array<string | GogFileArg>; positionals: Array<string | GogFileArg> } {
+  const flags: Array<string | GogFileArg> = [];
+  const positionals: Array<string | GogFileArg> = [];
+  let afterSeparator = false;
+  for (const arg of args) {
+    if (arg === '--') {
+      afterSeparator = true;
+    } else if (isGogPositional(arg)) {
+      positionals.push(arg.value);
+    } else if (afterSeparator || (isGogFileArg(arg) && arg.positional)) {
+      positionals.push(arg);
+    } else {
+      flags.push(arg);
+    }
+  }
+  return { flags, positionals };
+}
+
+// Refuse a safety-control override sitting in FLAG position. The tool layer
+// already vets model-supplied escape-hatch args (arg-guard.ts); this is the
+// backstop for every other path, so no tool can hand gog a `--readonly=false`
+// that would override the `--readonly` injected below (gog takes the LAST
+// value of a repeated flag). Positionals are exempt: after `--` they are data.
+function assertNoSafetyOverrides(flags: Array<string | GogFileArg>): void {
+  for (const arg of flags) {
+    if (typeof arg !== 'string') continue;
+    const reason = forbiddenArgReason(arg);
+    if (reason) throw new Error(reason);
+  }
+}
+
 function assembleArgs(
   args: GogArg[],
-  opts: { account?: string; interactive: boolean; readonly: boolean },
-): GogArg[] {
+  opts: { account?: string; interactive: boolean; readonly: boolean; gmailNoSend: boolean },
+): Array<string | GogFileArg> {
+  const { flags, positionals } = placePositionals(args);
+  assertNoSafetyOverrides(flags);
   const effectiveAccount = opts.account ?? readEnvVar('GOG_ACCOUNT');
-  const fullArgs: GogArg[] = ['--json', '--color=never'];
+  const fullArgs: Array<string | GogFileArg> = ['--json', '--color=never'];
   if (!opts.interactive) {
     fullArgs.push('--no-input');
   }
@@ -473,15 +537,19 @@ function assembleArgs(
   if (opts.readonly || readonlyEnvEnabled()) {
     fullArgs.push('--readonly');
   }
+  if (opts.gmailNoSend) {
+    fullArgs.push('--gmail-no-send');
+  }
   if (effectiveAccount) {
     fullArgs.push('--account', effectiveAccount);
   }
-  fullArgs.push(...args);
+  fullArgs.push(...flags);
+  if (positionals.length > 0) fullArgs.push('--', ...positionals);
   return fullArgs;
 }
 
 export async function run(args: GogArg[], options: RunOptions = {}): Promise<string> {
-  const { account, spawner, interactive = false, timeout, readonly = false, redactMode = 'full', opaqueFields } = options;
+  const { account, spawner, interactive = false, timeout, readonly = false, redactMode = 'full', opaqueFields, gmailNoSend = false } = options;
   const base = redactMode === 'tokens' ? redactGoogleTokens : redactSecrets;
   // Only OUTPUT carries opaque payloads. An error message is prose by
   // definition, so it always takes the plain redactor — exempting a field there
@@ -490,7 +558,7 @@ export async function run(args: GogArg[], options: RunOptions = {}): Promise<str
     ? (text: string): string => redactPreservingOpaqueFields(text, opaqueFields, base)
     : base;
 
-  const fullArgs = assembleArgs(args, { account, interactive, readonly });
+  const fullArgs = assembleArgs(args, { account, interactive, readonly, gmailNoSend });
 
   // Redaction wraps the spawn: a successful `gog auth tokens` (or any command
   // echoing a credential) would otherwise return raw Google tokens (ya29.…/1//…)
@@ -511,7 +579,7 @@ export async function run(args: GogArg[], options: RunOptions = {}): Promise<str
 // would corrupt. No redaction: the base64 of a user's own binary file is opaque
 // and has no token shapes to leak.
 export async function runBinary(args: GogArg[], options: RunOptions = {}): Promise<string> {
-  const { account, spawner, timeout, readonly = false } = options;
-  const fullArgs = assembleArgs(args, { account, interactive: false, readonly });
-  return spawnExecutor(fullArgs, { timeout, interactive: false, spawner, binary: true });
+  const { account, spawner, timeout, readonly = false, gmailNoSend = false, maxOutputBytes } = options;
+  const fullArgs = assembleArgs(args, { account, interactive: false, readonly, gmailNoSend });
+  return spawnExecutor(fullArgs, { timeout, interactive: false, spawner, binary: true, maxOutputBytes });
 }

package/src/tools/api.ts

@@ -1,6 +1,27 @@
 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';
+
+// 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;
+
+export function refusedApiCall(api: string, method: string): string | undefined {
+  if (api.trim().toLowerCase() === 'gmail' && GMAIL_API_BLOCKED.test(method.trim())) {
+    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.';
+  }
+  return 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 +36,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 +51,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.',
     annotations: { destructiveHint: true },
     inputSchema: z.object({
       api: z.string().describe('Discovery API name (e.g. drive, gmail, calendar)'),
@@ -50,7 +71,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 +92,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.',
   });
 }

package/src/tools/calendar.ts

@@ -3,6 +3,8 @@ import { z } from 'zod';
 import { viewParam, resolveView } from '@chrischall/mcp-utils';
 import { accountParam, runOrDiagnose, registerRunTool, pageTokenParam, pageAliasParam, resolvePageToken } from './utils.js';
 import { annotateTruncatedList } from '../pagination.js';
+import { pos } from '../argv.js';
+import type { GogArg } from '../runner.js';
 
 // Reminder params, shared by create and update (gog >= 0.38.0 for
 // --no-reminders). An event's reminders are one of THREE states, and the two
@@ -33,7 +35,7 @@ const reminderParams = {
 // The one place the three states become argv. Kept together so create and
 // update cannot drift apart on the empty-array case.
 function pushReminderFlags(
-  args: string[],
+  args: GogArg[],
   p: { reminders?: string[]; noReminders?: boolean },
 ): void {
   if (p.noReminders) {
@@ -107,8 +109,8 @@ export function registerCalendarTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ calendarId, from, to, days, today, query, max, pageToken, page, all, eventTypes, timezone, view, account }) => {
-    const args = ['calendar', 'events'];
-    if (calendarId) args.push(calendarId);
+    const args: GogArg[] = ['calendar', 'events'];
+    if (calendarId) args.push(pos(calendarId));
     if (from) args.push(`--from=${from}`);
     if (to) args.push(`--to=${to}`);
     if (days !== undefined) args.push(`--days=${days}`);
@@ -141,7 +143,7 @@ export function registerCalendarTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ calendarId, eventId, timezone, account }) => {
-    const args = ['calendar', 'event', calendarId, eventId];
+    const args: GogArg[] = ['calendar', 'event', pos(calendarId), pos(eventId)];
     if (timezone) args.push(`--timezone=${timezone}`);
     return runOrDiagnose(args, { account });
   });
@@ -164,7 +166,7 @@ export function registerCalendarTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ calendarId, summary, from, to, description, location, attendees, allDay, timezone, withZoom, reminders, noReminders, account }) => {
-    const args = ['calendar', 'create', calendarId, `--summary=${summary}`, `--from=${from}`, `--to=${to}`];
+    const args: GogArg[] = ['calendar', 'create', pos(calendarId), `--summary=${summary}`, `--from=${from}`, `--to=${to}`];
     if (description) args.push(`--description=${description}`);
     if (location) args.push(`--location=${location}`);
     if (attendees) args.push(`--attendees=${attendees}`);
@@ -197,7 +199,7 @@ export function registerCalendarTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ calendarId, eventId, summary, from, to, description, location, attendees, addAttendees, attachments, withZoom, regenerateZoom, removeZoom, removeMeet, reminders, noReminders, account }) => {
-    const args = ['calendar', 'update', calendarId, eventId];
+    const args: GogArg[] = ['calendar', 'update', pos(calendarId), pos(eventId)];
     if (summary !== undefined) args.push(`--summary=${summary}`);
     if (from !== undefined) args.push(`--from=${from}`);
     if (to !== undefined) args.push(`--to=${to}`);
@@ -225,7 +227,7 @@ export function registerCalendarTools(server: McpServer): void {
   }, async ({ calendarId, eventId, account }) => {
     // gog gates this delete behind a confirmation; the runner injects
     // --no-input, so without --force it refuses at runtime.
-    return runOrDiagnose(['calendar', 'delete', calendarId, eventId, '--force'], { account });
+    return runOrDiagnose(['calendar', 'delete', pos(calendarId), pos(eventId), '--force'], { account });
   });
 
   server.registerTool('gog_calendar_respond', {
@@ -239,7 +241,7 @@ export function registerCalendarTools(server: McpServer): void {
       account: accountParam,
     }),
   }, async ({ calendarId, eventId, status, comment, account }) => {
-    const args = ['calendar', 'respond', calendarId, eventId, `--status=${status}`];
+    const args: GogArg[] = ['calendar', 'respond', pos(calendarId), pos(eventId), `--status=${status}`];
     if (comment) args.push(`--comment=${comment}`);
     return runOrDiagnose(args, { account });
   });