gogcli-mcp 4.2.5 → 4.4.0

package/src/tools/utils.ts

@@ -5,6 +5,8 @@ import { run } from '../runner.js';
 import type { GogArg } from '../runner.js';
 import { normalizeTimestamps } from '../timestamps.js';
 import { stripConsumedPageToken } from '../pagination.js';
+import { assertSafeForwardedArgs, assertSafeSubcommand } from '../arg-guard.js';
+import { assertRunPathsConfined, positionalPathTool } from '../run-path-guard.js';
 
 // Byte size at or below which a payload stays on the plain inline flag.
 //
@@ -110,7 +112,7 @@ export const paginationParams = {
 // Append pagination flags to an argv array. Mirrors the shape of
 // paginationParams above. Use together to keep call sites concise.
 export function pushPaginationFlags(
-  args: string[],
+  args: GogArg[],
   p: { max?: number; pageToken?: string; page?: string; all?: boolean },
 ): void {
   if (p.max !== undefined) args.push(`--max=${p.max}`);
@@ -122,6 +124,14 @@ export function pushPaginationFlags(
 // Register a `gog_<service>_run` escape-hatch tool. 11 services currently
 // register an identical-shape tool; this factory keeps them in lockstep.
 // Pass `omitAccount: true` only for auth, which doesn't take --account.
+//
+// THE ARGS ARE MODEL-SUPPLIED AND FORWARDED VERBATIM, so every call is vetted
+// before gog sees it (audit SEC-1): a safety-control override
+// (`--readonly=false`, `--disable-commands=`, `--account=…`, a bare `--`, …) is
+// refused rather than forwarded, and the subcommand must be a plain word.
+// `allowedSubcommands` narrows a service to a named subset (auth: never
+// `tokens export`), `vet` lets a service refuse specific shapes, and
+// `gmailNoSend` pins gog's own `--gmail-no-send` on.
 export function registerRunTool(
   server: McpServer,
   options: {
@@ -130,11 +140,33 @@ export function registerRunTool(
     omitAccount?: boolean;
     /** Extra sentence appended to the description (used by auth to point to gog_auth_add). */
     note?: string;
+    /** When set, only these subcommands may run; everything else is refused. */
+    allowedSubcommands?: readonly string[];
+    /** Service-specific refusal: return a reason to refuse, or undefined to allow. */
+    vet?: (subcommand: string, args: readonly string[]) => string | undefined;
+    /** Inject gog's --gmail-no-send, so no send can be smuggled through this tool. */
+    gmailNoSend?: boolean;
   },
 ): void {
-  const { service, examples, omitAccount = false, note } = options;
+  const { service, examples, omitAccount = false, note, allowedSubcommands, vet, gmailNoSend = false } = options;
+  // The examples go straight into the schema the model reads, so every one must
+  // be a subcommand this tool actually runs. A stale example (#391: drive
+  // "upload" after #390 refused it) fails here, at registration, not in use.
+  for (const [, example] of examples.matchAll(/"([^"]+)"/g)) {
+    const refused = (allowedSubcommands && !allowedSubcommands.includes(example))
+      || vet?.(example, [])
+      || positionalPathTool(service, example);
+    if (refused) {
+      throw new Error(`gog_${service}_run example "${example}" is refused by the tool itself; list a subcommand it runs.`);
+    }
+  }
   const baseDescription = `Run any gog ${service} subcommand not covered by the other tools. Run \`gog ${service} --help\` for the full list of subcommands, or \`gog ${service} <subcommand> --help\` for flags on a specific subcommand.`;
-  const description = note ? `${baseDescription} ${note}` : baseDescription;
+  const restriction = allowedSubcommands
+    ? ` Only these subcommands are available: ${allowedSubcommands.join(', ')}.`
+    : '';
+  const safety = ' Flags that override server safety controls (--readonly, --enable-commands, --disable-commands, --account, --access-token, --home, --client, --gmail-no-send, --no-input) and a bare "--" are refused.'
+    + ' Local file paths (--out, --out-dir, --attach, --file, --*-file, @file JSON) must be inside GOG_FILE_ROOTS; subcommands that take a local path positionally (e.g. drive upload) are refused in favour of their dedicated tools.';
+  const description = `${baseDescription}${restriction}${safety}${note ? ` ${note}` : ''}`;
   const inputSchema: Record<string, z.ZodTypeAny> = {
     subcommand: z.string().describe(`The gog ${service} subcommand to run, e.g. ${examples}`),
     args: z.array(z.string()).describe('Additional positional args and flags'),
@@ -148,7 +180,21 @@ export function registerRunTool(
     inputSchema: z.object(inputSchema),
   }, async (rawArgs) => {
     const { subcommand, args, account } = rawArgs as { subcommand: string; args: string[]; account?: string };
-    return runOrDiagnose([service, subcommand, ...args], { account });
+    try {
+      assertSafeSubcommand(subcommand);
+      assertSafeForwardedArgs(args);
+      if (allowedSubcommands && !allowedSubcommands.includes(subcommand)) {
+        throw new Error(
+          `gog ${service} ${subcommand} is not available through gog_${service}_run. Allowed: ${allowedSubcommands.join(', ')}.`,
+        );
+      }
+      const refusal = vet?.(subcommand, args);
+      if (refusal) throw new Error(refusal);
+      assertRunPathsConfined(service, subcommand, args);
+    } catch (err) {
+      return errorResult(errorText(err));
+    }
+    return runOrDiagnose([service, subcommand, ...args], gmailNoSend ? { account, gmailNoSend } : { account });
   });
 }
 
@@ -359,7 +405,7 @@ function isRejectedFieldMask(err: unknown): boolean {
 
 async function runProjected(
   args: GogArg[],
-  options: { account?: string; lossless?: boolean; fieldsMask?: string },
+  options: { account?: string; lossless?: boolean; fieldsMask?: string; gmailNoSend?: boolean },
 ): Promise<string> {
   const { fieldsMask } = options;
   if (!fieldsMask) return run(args, options);
@@ -377,7 +423,7 @@ async function runProjected(
 
 export async function runOrDiagnose(
   args: GogArg[],
-  options: { account?: string; lossless?: boolean; fieldsMask?: string; stripMedia?: boolean },
+  options: { account?: string; lossless?: boolean; fieldsMask?: string; stripMedia?: boolean; gmailNoSend?: boolean },
 ): Promise<CallToolResult> {
   try {
     // The single seam every tool's output passes through. Normalizing here —

package/tests/arg-guard.test.ts

@@ -0,0 +1,80 @@
+import { describe, it, expect } from 'vitest';
+import { forbiddenArgReason, assertSafeForwardedArgs, assertSafeSubcommand } from '../src/arg-guard.js';
+
+describe('forbiddenArgReason', () => {
+  // Each of these would let a model-supplied arg override a control the
+  // operator (or this wrapper) set: gog takes the LAST value of a repeated flag,
+  // so `--readonly=false` after the injected `--readonly` turns writes back on.
+  it.each([
+    '--readonly',
+    '--readonly=false',
+    '--readonly=0',
+    '--enable-commands=gmail.send',
+    '--enable-commands-exact=gmail send',
+    '--disable-commands=',
+    '--disable-commands',
+    '--access-token=ya29.x',
+    '--home=/tmp/other',
+    '--account=attacker@example.com',
+    '--account',
+    '--acct=attacker@example.com',
+    '--client=other',
+    '--gmail-no-send=false',
+    '--no-input=false',
+    '--non-interactive=false',
+    '--noninteractive=false',
+    '--READONLY=false',
+    '--Account=attacker@example.com',
+    '-a',
+    '-aattacker@example.com',
+    '-ja',
+    '--',
+  ])('rejects %j', (arg) => {
+    expect(forbiddenArgReason(arg)).toMatch(/not allowed/);
+  });
+
+  it.each([
+    'msg1',
+    '--title=New',
+    '--max=5',
+    '-y',
+    '-5',
+    'has:attachment',
+    'a--readonly',
+    '',
+    // Legitimate command flags that merely share a leading word with a control
+    // (gog_zoom_auth_setup builds the first three). Matched as bare prefixes
+    // they were refused, so zoom auth setup could never run.
+    '--account-id=abc',
+    '--client-id=x',
+    '--client-secret=y',
+    '--home-dir=x',
+    '--readonly-note=x',
+  ])('allows %j', (arg) => {
+    expect(forbiddenArgReason(arg)).toBeUndefined();
+  });
+
+  it('names the separator specifically for a bare --', () => {
+    expect(forbiddenArgReason('--')).toMatch(/"--"/);
+  });
+});
+
+describe('assertSafeForwardedArgs', () => {
+  it('passes a clean list', () => {
+    expect(() => assertSafeForwardedArgs(['file1', '--parent=x'])).not.toThrow();
+  });
+
+  it('throws naming the first offending arg', () => {
+    expect(() => assertSafeForwardedArgs(['x', '--readonly=false'])).toThrow(/--readonly=false/);
+  });
+});
+
+describe('assertSafeSubcommand', () => {
+  it.each(['archive', 'mark-read', 'labels', 'add-tab'])('allows %j', (s) => {
+    expect(() => assertSafeSubcommand(s)).not.toThrow();
+  });
+
+  it.each(['--readonly=false', '-a', '', 'Send Now', '../x'])('rejects %j', (s) => {
+    expect(() => assertSafeSubcommand(s)).toThrow(/subcommand/);
+  });
+});

package/tests/attachment-root.test.ts

@@ -0,0 +1,130 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtemp, mkdir, writeFile, rm, stat, symlink, chmod, utimes, readdir } from 'node:fs/promises';
+import { tmpdir, userInfo } from 'node:os';
+import { join } from 'node:path';
+import {
+  ATTACHMENT_DOWNLOAD_ROOT,
+  ATTACHMENT_TTL_MS,
+  ensurePrivateDir,
+  sweepExpiredDownloads,
+  removeDownload,
+  prepareDownloadRoot,
+} from '../src/attachment-root.js';
+
+let scratch: string;
+beforeEach(async () => {
+  scratch = await mkdtemp(join(tmpdir(), 'gog-attroot-test-'));
+});
+afterEach(async () => {
+  await rm(scratch, { recursive: true, force: true });
+});
+
+// SEC-6: downloads used to land in a fixed, shared /tmp/gog-attachments that
+// nothing ever emptied — predictable, pre-creatable by another local user, and
+// a growing pile of medical/financial attachments.
+describe('ATTACHMENT_DOWNLOAD_ROOT', () => {
+  it('is per-user, under the OS temp dir, not the shared /tmp/gog-attachments', () => {
+    expect(ATTACHMENT_DOWNLOAD_ROOT).not.toBe('/tmp/gog-attachments');
+    expect(ATTACHMENT_DOWNLOAD_ROOT.startsWith(tmpdir())).toBe(true);
+    expect(ATTACHMENT_DOWNLOAD_ROOT).toContain(String(userInfo().uid));
+  });
+});
+
+describe('ensurePrivateDir', () => {
+  it('creates the directory owner-only (0700)', async () => {
+    const dir = join(scratch, 'root');
+    await ensurePrivateDir(dir);
+    expect((await stat(dir)).mode & 0o777).toBe(0o700);
+  });
+
+  it('tightens an existing directory of ours that others could read', async () => {
+    const dir = join(scratch, 'loose');
+    await mkdir(dir, { mode: 0o755 });
+    await chmod(dir, 0o755);
+    await ensurePrivateDir(dir);
+    expect((await stat(dir)).mode & 0o777).toBe(0o700);
+  });
+
+  it('refuses a symlink planted where the root should be', async () => {
+    const target = join(scratch, 'elsewhere');
+    await mkdir(target);
+    const dir = join(scratch, 'planted');
+    await symlink(target, dir);
+    await expect(ensurePrivateDir(dir)).rejects.toThrow(/not a real directory/);
+  });
+
+  it('refuses a regular file in its place', async () => {
+    const dir = join(scratch, 'file');
+    await writeFile(dir, 'x');
+    await expect(ensurePrivateDir(dir)).rejects.toThrow(/not a real directory/);
+  });
+
+  it('refuses a directory owned by another user', async () => {
+    const dir = join(scratch, 'theirs');
+    await mkdir(dir);
+    await expect(ensurePrivateDir(dir, { uid: userInfo().uid + 1 })).rejects.toThrow(/owned by another user/);
+  });
+
+  it('surfaces an error other than "already exists"', async () => {
+    await expect(ensurePrivateDir(join(scratch, 'missing-parent', 'root'))).rejects.toThrow(/ENOENT/);
+  });
+});
+
+describe('sweepExpiredDownloads', () => {
+  it('removes entries older than the TTL and keeps fresh ones', async () => {
+    const old = join(scratch, 'm-old');
+    const fresh = join(scratch, 'm-new');
+    await mkdir(old);
+    await mkdir(fresh);
+    await writeFile(join(old, 'a.pdf'), 'x');
+    const past = new Date(Date.now() - ATTACHMENT_TTL_MS - 60_000);
+    await utimes(old, past, past);
+    const removed = await sweepExpiredDownloads(scratch);
+    expect(removed).toBe(1);
+    expect(await readdir(scratch)).toEqual(['m-new']);
+  });
+
+  it('is a no-op on a missing root', async () => {
+    expect(await sweepExpiredDownloads(join(scratch, 'nope'))).toBe(0);
+  });
+});
+
+describe('removeDownload', () => {
+  it('deletes the file and the now-empty directories up to the root', async () => {
+    const file = join(scratch, 'm1', 'a1', 'x.pdf');
+    await mkdir(join(scratch, 'm1', 'a1'), { recursive: true });
+    await writeFile(file, 'x');
+    await removeDownload(file, scratch);
+    expect(await readdir(scratch)).toEqual([]);
+  });
+
+  it('keeps a directory that still holds another download', async () => {
+    await mkdir(join(scratch, 'm1'), { recursive: true });
+    await writeFile(join(scratch, 'm1', 'keep.pdf'), 'k');
+    await writeFile(join(scratch, 'm1', 'x.pdf'), 'x');
+    await removeDownload(join(scratch, 'm1', 'x.pdf'), scratch);
+    expect(await readdir(join(scratch, 'm1'))).toEqual(['keep.pdf']);
+  });
+
+  it('never touches a path outside the root', async () => {
+    const outside = join(scratch, 'outside.txt');
+    await writeFile(outside, 'x');
+    const root = join(scratch, 'root');
+    await mkdir(root);
+    await removeDownload(outside, root);
+    await removeDownload(join(root, '..', 'outside.txt'), root);
+    expect((await stat(outside)).isFile()).toBe(true);
+  });
+
+  it('ignores a file that is already gone', async () => {
+    await expect(removeDownload(join(scratch, 'gone', 'x'), scratch)).resolves.toBeUndefined();
+  });
+});
+
+describe('prepareDownloadRoot', () => {
+  it('ensures the root is private and sweeps it', async () => {
+    const root = join(scratch, 'prep');
+    await prepareDownloadRoot(root);
+    expect((await stat(root)).mode & 0o777).toBe(0o700);
+  });
+});

package/tests/attachments.test.ts

@@ -9,6 +9,7 @@ import {
   INLINE_ATTACHMENT_LIMITS_TEXT,
 } from '../src/attachments.js';
 import type { GogFileArg } from '../src/runner.js';
+import { pos } from '../src/argv.js';
 
 const b64 = (s: string): string => Buffer.from(s, 'utf8').toString('base64');
 const PNG = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
@@ -166,6 +167,13 @@ describe('inlineAttachmentArgs', () => {
       .toThrow(/too large to send/);
   });
 
+  it('counts a pos()-marked sibling at its UTF-8 length', () => {
+    const each = Buffer.alloc(Math.floor((MAX_INLINE_ATTACHMENT_TOTAL_BYTES - 4096) / 3)).toString('base64');
+    const attachments = Array.from({ length: 3 }, (_, i) => ({ filename: `f${i}.bin`, contentBase64: each }));
+    expect(() => inlineAttachmentArgs('attach', attachments, ['chat', 'messages', 'send', pos('x'.repeat(4 * 1024 * 1024))]))
+      .toThrow(/would fit on their own/);
+  });
+
   it('ignores small sibling args, which the JSON reserve already covers', () => {
     const chunk = Buffer.alloc(Math.floor(MAX_INLINE_ATTACHMENT_TOTAL_BYTES / 4)).toString('base64');
     const two = Array.from({ length: 2 }, (_, i) => ({ filename: `f${i}.bin`, contentBase64: chunk }));

package/tests/blob-upload.test.ts

@@ -2,7 +2,7 @@ import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import { createServer, type IncomingMessage, type Server, type ServerResponse } from 'node:http';
 import type { AddressInfo } from 'node:net';
 import { mkdtemp, mkdir, writeFile, symlink, truncate, rm } from 'node:fs/promises';
-import { tmpdir } from 'node:os';
+import { tmpdir, userInfo } from 'node:os';
 import { join } from 'node:path';
 import {
   uploadToBlobStore,
@@ -147,11 +147,12 @@ describe('uploadToBlobStore', () => {
     });
 
     it('confines to the real attachment root when no root is given', async () => {
-      expect(ATTACHMENT_DOWNLOAD_ROOT).toBe('/tmp/gog-attachments');
+      // Per-user and private now (SEC-6), not the shared /tmp/gog-attachments.
+      expect(ATTACHMENT_DOWNLOAD_ROOT).toBe(join(tmpdir(), `gogcli-mcp-attachments-${userInfo().uid}`));
 
       const err = await failure(uploadToBlobStore(request({ path: '/etc/passwd' })));
 
-      expect(err.message).toContain('must be inside /tmp/gog-attachments');
+      expect(err.message).toContain(`must be inside ${ATTACHMENT_DOWNLOAD_ROOT}`);
       expect(received).toHaveLength(0);
     });
   });

package/tests/file-roots.test.ts

@@ -0,0 +1,101 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtemp, mkdir, rm, symlink, writeFile } from 'node:fs/promises';
+import { homedir, tmpdir } from 'node:os';
+import { delimiter, join } from 'node:path';
+import { confinePath, confinePaths, confineAtFile, defaultFileRoot, fileRoots, FILE_ROOTS_ENV } from '../src/file-roots.js';
+import { ATTACHMENT_DOWNLOAD_ROOT } from '../src/attachment-root.js';
+
+let scratch: string;
+let saved: string | undefined;
+beforeEach(async () => {
+  scratch = await mkdtemp(join(tmpdir(), 'gog-roots-test-'));
+  saved = process.env[FILE_ROOTS_ENV];
+  process.env[FILE_ROOTS_ENV] = scratch;
+});
+afterEach(async () => {
+  if (saved === undefined) delete process.env[FILE_ROOTS_ENV];
+  else process.env[FILE_ROOTS_ENV] = saved;
+  await rm(scratch, { recursive: true, force: true });
+});
+
+describe('fileRoots', () => {
+  it('reads a path-delimited list from GOG_FILE_ROOTS, ignoring blanks', () => {
+    process.env[FILE_ROOTS_ENV] = `/a${delimiter} ${delimiter}/b`;
+    expect(fileRoots()).toEqual(['/a', '/b']);
+  });
+
+  it('defaults to a dedicated directory under the home directory', () => {
+    delete process.env[FILE_ROOTS_ENV];
+    expect(defaultFileRoot()).toBe(join(homedir(), 'gogcli-mcp-files'));
+    expect(fileRoots()).toEqual([defaultFileRoot()]);
+  });
+
+  it('treats an unresolved .mcpb placeholder as unset', () => {
+    process.env[FILE_ROOTS_ENV] = '${user_config.gog_file_roots}';
+    expect(fileRoots()).toEqual([defaultFileRoot()]);
+  });
+});
+
+// SEC-3/SEC-4: every model-supplied server path — attach, localPath, out,
+// outDir — is a read or write primitive on the host. ~/.ssh, gog's keyring,
+// /proc/<pid>/environ and ~/Library/LaunchAgents are all one argument away.
+describe('confinePath', () => {
+  it('accepts a path inside a root and returns it unchanged', () => {
+    const p = join(scratch, 'report.pdf');
+    expect(confinePath(p, 'attach')).toBe(p);
+  });
+
+  it('accepts a not-yet-existing output path inside a root', () => {
+    expect(confinePath(join(scratch, 'new', 'out.csv'), 'out')).toBe(join(scratch, 'new', 'out.csv'));
+  });
+
+  it('accepts the private attachment download directory', () => {
+    const p = join(ATTACHMENT_DOWNLOAD_ROOT, 'm1', 'a.pdf');
+    expect(confinePath(p, 'attach')).toBe(p);
+  });
+
+  it.each([
+    ['/etc/passwd'],
+    [join(homedir(), '.ssh', 'id_rsa')],
+    ['/proc/self/environ'],
+  ])('refuses %s, naming the parameter and GOG_FILE_ROOTS', (p) => {
+    expect(() => confinePath(p, 'attach')).toThrow(/attach .* is outside the directories .* GOG_FILE_ROOTS/);
+  });
+
+  it('refuses a .. walk out of the root', () => {
+    expect(() => confinePath(join(scratch, '..', 'x'), 'out')).toThrow(/outside/);
+  });
+
+  it('refuses a symlink inside the root that points outside it', async () => {
+    const outside = await mkdtemp(join(tmpdir(), 'gog-roots-outside-'));
+    try {
+      await writeFile(join(outside, 'secret'), 's');
+      await mkdir(join(scratch, 'd'));
+      await symlink(join(outside, 'secret'), join(scratch, 'd', 'link'));
+      expect(() => confinePath(join(scratch, 'd', 'link'), 'localPath')).toThrow(/outside/);
+    } finally {
+      await rm(outside, { recursive: true, force: true });
+    }
+  });
+
+  it('refuses gog\'s "-" (stdin) unless the parameter allows stdout', () => {
+    expect(() => confinePath('-', 'file')).toThrow(/outside/);
+    expect(confinePath('-', 'out', { allowDash: true })).toBe('-');
+  });
+});
+
+describe('confinePaths', () => {
+  it('checks every path and tolerates undefined', () => {
+    expect(() => confinePaths(undefined, 'attach')).not.toThrow();
+    expect(() => confinePaths([join(scratch, 'a'), '/etc/hosts'], 'attach')).toThrow(/\/etc\/hosts/);
+  });
+});
+
+describe('confineAtFile', () => {
+  it('confines the path of an @file value and passes inline JSON through', () => {
+    expect(confineAtFile('[{"a":1}]', 'cellsJson')).toBe('[{"a":1}]');
+    expect(confineAtFile(`@${join(scratch, 'c.json')}`, 'cellsJson')).toBe(`@${join(scratch, 'c.json')}`);
+    expect(() => confineAtFile('@/etc/passwd', 'cellsJson')).toThrow(/cellsJson/);
+    expect(() => confineAtFile('@-', 'cellsJson')).toThrow(/outside/);
+  });
+});