gogcli-mcp 2.29.0 → 2.30.0

package/tests/blob-upload.test.ts

@@ -0,0 +1,204 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { uploadToBlobStore, RUNNER_UPLOAD_TIMEOUT_MS } from '../src/blob-upload.js';
+
+// A minted PUT URL, with the two shapes the scrubber has to recognise: the
+// whole string, and the bare signature it carries.
+const SIG = 'AbCdEf-_1234';
+const PUT_URL = `https://host.example/b/reg_1/gmail/m1/Guest%20Copy.pdf?exp=1757000000000&sig=${SIG}`;
+
+const ENV = { GOG_RUNNER_URL: 'https://runner.example', GOG_RUNNER_KEY: 'runner-key' };
+
+const REQUEST = { path: '/tmp/gog-attachments/m1/Guest_Copy.pdf', url: PUT_URL, contentType: 'application/pdf' };
+
+function answers(status: number, body: unknown, ok = status >= 200 && status < 300) {
+  return vi.fn(async () => ({
+    ok,
+    status,
+    text: async () => (typeof body === 'string' ? body : JSON.stringify(body)),
+  }));
+}
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  vi.unstubAllEnvs();
+});
+
+describe('uploadToBlobStore', () => {
+  it('POSTs the path, the URL and the content type to the runner, bearing its key', async () => {
+    const fetchMock = answers(200, { ok: true, status: 200, bytes: 99723 });
+    vi.stubGlobal('fetch', fetchMock);
+
+    const outcome = await uploadToBlobStore(REQUEST, { env: { ...ENV, GOG_RUNNER_URL: 'https://runner.example//' } });
+
+    expect(outcome).toEqual({ bytes: 99723, status: 200 });
+    const [url, init] = fetchMock.mock.calls[0] as [string, RequestInit];
+    // Trailing slashes trimmed — `<endpoint>//upload` is a different route.
+    expect(url).toBe('https://runner.example/upload');
+    expect(init.method).toBe('POST');
+    expect(init.headers).toMatchObject({
+      Authorization: 'Bearer runner-key',
+      'Content-Type': 'application/json',
+    });
+    expect(JSON.parse(init.body as string)).toEqual({
+      path: REQUEST.path,
+      url: PUT_URL,
+      contentType: 'application/pdf',
+    });
+    // A deadline of our own: the runner's 120 s is an INACTIVITY timer and
+    // cannot bound a transfer that keeps dribbling, so nothing else protects
+    // the MCP caller from a request that never ends.
+    expect(init.signal).toBeInstanceOf(AbortSignal);
+  });
+
+  it('refuses, without dialling, when no gog runner is configured', async () => {
+    const fetchMock = answers(200, { ok: true });
+    vi.stubGlobal('fetch', fetchMock);
+
+    await expect(uploadToBlobStore(REQUEST, { env: { GOG_RUNNER_URL: ENV.GOG_RUNNER_URL } }))
+      .rejects.toThrow(/GOG_RUNNER_URL.*GOG_RUNNER_KEY/s);
+    await expect(uploadToBlobStore(REQUEST, { env: { GOG_RUNNER_KEY: ENV.GOG_RUNNER_KEY } }))
+      .rejects.toThrow(/GOG_RUNNER_URL.*GOG_RUNNER_KEY/s);
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it('reports the blob store\'s own verdict when the runner relays a refusal', async () => {
+    vi.stubGlobal('fetch', answers(422, {
+      error: 'the blob store refused the upload with 403: forbidden',
+      status: 403,
+      retryable: false,
+    }));
+
+    await expect(uploadToBlobStore(REQUEST, { env: ENV }))
+      .rejects.toThrow(/the blob store refused the upload with 403: forbidden/);
+  });
+
+  it('names the runner\'s status when it answers with no error text', async () => {
+    vi.stubGlobal('fetch', answers(502, { retryable: true }));
+
+    await expect(uploadToBlobStore(REQUEST, { env: ENV })).rejects.toThrow(/502/);
+  });
+
+  it('survives an answer that is not JSON at all (a proxy\'s HTML error page)', async () => {
+    vi.stubGlobal('fetch', answers(504, '<html>gateway timeout</html>'));
+
+    // The body is quoted, not parsed — and the throw is about the upload, never
+    // a SyntaxError from somewhere inside this module.
+    await expect(uploadToBlobStore(REQUEST, { env: ENV })).rejects.toThrow(/504/);
+  });
+
+  // A signed URL is a credential with up to 24 h of anybody-who-holds-it access
+  // to the object. The runner scrubs its own words, but the far side's text is
+  // a third party's and may quote the request URL straight back — and an error
+  // thrown here is the one value on this path that is expected to be logged.
+  it('never lets the signed URL, or its bare signature, into the error it throws', async () => {
+    vi.stubGlobal('fetch', answers(422, { error: `refused: PUT ${PUT_URL} (sig ${SIG})`, status: 403 }));
+
+    const err = await uploadToBlobStore(REQUEST, { env: ENV }).catch((e: Error) => e);
+    expect(err).toBeInstanceOf(Error);
+    expect((err as Error).message).not.toContain(PUT_URL);
+    expect((err as Error).message).not.toContain(SIG);
+    expect((err as Error).message).toContain('<signed url>');
+  });
+
+  it('scrubs a transport failure too — a rejected fetch may quote the URL', async () => {
+    vi.stubGlobal('fetch', vi.fn(async () => {
+      throw new Error(`connect ECONNREFUSED while sending ${PUT_URL}`);
+    }));
+
+    const err = await uploadToBlobStore(REQUEST, { env: ENV }).catch((e: Error) => e);
+    expect((err as Error).message).not.toContain(PUT_URL);
+    expect((err as Error).message).not.toContain(SIG);
+    expect((err as Error).message).toContain('ECONNREFUSED');
+  });
+
+  it('reports a transport failure that threw something other than an Error', async () => {
+    vi.stubGlobal('fetch', vi.fn(async () => { throw 'socket hang up'; }));
+
+    await expect(uploadToBlobStore(REQUEST, { env: ENV })).rejects.toThrow(/socket hang up/);
+  });
+
+  // The response ARRIVES and then its body fails to read — a severed or
+  // truncated answer. That is a third shape of transport failure, and the
+  // module's contract is about every one of them: nothing it throws carries the
+  // URL. undici's own body errors ('terminated', 'Premature close') happen to
+  // name nothing, so this is the guarantee being a property of the function
+  // rather than a fact about today's runtime.
+  it('scrubs a body that fails to read, as it scrubs a failed dial', async () => {
+    vi.stubGlobal('fetch', vi.fn(async () => ({
+      ok: true,
+      status: 200,
+      text: async () => { throw new Error(`terminated while reading ${PUT_URL}`); },
+    })));
+
+    const err = await uploadToBlobStore(REQUEST, { env: ENV }).catch((e: Error) => e);
+    expect(err).toBeInstanceOf(Error);
+    expect((err as Error).message).not.toContain(PUT_URL);
+    expect((err as Error).message).not.toContain(SIG);
+    expect((err as Error).message).toContain('terminated');
+  });
+
+  it('reports a body read that rejected with something other than an Error', async () => {
+    vi.stubGlobal('fetch', vi.fn(async () => ({
+      ok: true,
+      status: 200,
+      text: async () => { throw 'premature close'; },
+    })));
+
+    await expect(uploadToBlobStore(REQUEST, { env: ENV })).rejects.toThrow(/premature close/);
+  });
+
+  // The whole-string replacement is what does the work for a URL with no `sig`
+  // at all — and a URL that is not parseable must still be redacted rather than
+  // throwing on the way to a redaction.
+  it('scrubs a URL that carries no signature and does not parse', async () => {
+    const odd = 'not a url at all';
+    vi.stubGlobal('fetch', answers(422, { error: `refused: ${odd}`, status: 400 }));
+
+    const err = await uploadToBlobStore({ ...REQUEST, url: odd }, { env: ENV }).catch((e: Error) => e);
+    expect((err as Error).message).not.toContain(odd);
+    expect((err as Error).message).toContain('<signed url>');
+  });
+
+  // `split('')` cuts a message into single characters and interleaves the
+  // replacement between every one of them, so an empty needle does not redact a
+  // message, it destroys it. Today's one call site always mints a URL first —
+  // this is a property of the function, which is why it is asserted on it.
+  it('an empty URL leaves the message intact rather than shredding it', async () => {
+    vi.stubGlobal('fetch', answers(422, { error: 'the blob store refused the upload', status: 403 }));
+
+    const err = await uploadToBlobStore({ ...REQUEST, url: '' }, { env: ENV }).catch((e: Error) => e);
+    expect((err as Error).message).toContain('the blob store refused the upload');
+    expect((err as Error).message).not.toContain('<signed url>');
+  });
+
+  it('reads the ambient environment, and its own deadline, when given neither', async () => {
+    const fetchMock = answers(200, { ok: true, status: 200, bytes: 12 });
+    vi.stubGlobal('fetch', fetchMock);
+    vi.stubEnv('GOG_RUNNER_URL', ENV.GOG_RUNNER_URL);
+    vi.stubEnv('GOG_RUNNER_KEY', ENV.GOG_RUNNER_KEY);
+
+    await expect(uploadToBlobStore(REQUEST)).resolves.toEqual({ bytes: 12, status: 200 });
+    expect((fetchMock.mock.calls[0] as [string, RequestInit])[0]).toBe('https://runner.example/upload');
+  });
+
+  it('exposes its deadline as a constant rather than a literal at the call site', () => {
+    expect(RUNNER_UPLOAD_TIMEOUT_MS).toBeGreaterThan(30_000);
+  });
+
+  // The rule this repo already applies at the other hop (`DEADLINE_GRACE_MS` in
+  // connector-runtime.ts: 30 s backend budget + 5 s): the CALLER's deadline sits
+  // ABOVE the backend's own, so the backend loses the race only when it
+  // genuinely cannot answer. The doc block here cited that rule while the
+  // numbers inverted it — 90 s against the runner's 120 s — so a socket that
+  // went quiet was aborted on this side 30 s before the runner's own timer could
+  // name it, turning "the upload timed out after 120000ms" into exactly the
+  // opaque client abort the rule exists to prevent.
+  //
+  // Restated rather than imported: `fly-gog-runner/server.mjs` must not be
+  // pulled into the Worker bundle (the same reason the attachment ceilings are
+  // restated in attachments.ts), so the two move by hand and this is the guard.
+  it('sits above the runner\'s own upload timeout, so the runner answers first', () => {
+    const UPLOAD_TIMEOUT_MS_ON_THE_BOX = 120_000; // server.mjs UPLOAD_TIMEOUT_MS
+    expect(RUNNER_UPLOAD_TIMEOUT_MS).toBeGreaterThan(UPLOAD_TIMEOUT_MS_ON_THE_BOX);
+  });
+});

package/tests/blob-urls.test.ts

@@ -0,0 +1,319 @@
+import { describe, it, expect, afterEach, vi } from 'vitest';
+import { createHmac } from 'node:crypto';
+import {
+  blobStoreFromEnv,
+  createBlobUrlMinter,
+  readPayload,
+  writePayload,
+  BLOB_URL_MAX_TTL_MS,
+  BLOB_URL_CEILING_MARGIN_MS,
+  BLOB_URL_DEFAULT_TTL_MS,
+} from '../src/blob-urls.js';
+
+// ---------------------------------------------------------------------------
+// Fixtures. These are VECTORS: the signatures below were computed against the
+// payload shapes as mcp-host's `blob-key.ts` spells them, independently of this
+// module's code. If a future edit changes how a payload is assembled — a
+// separator, the order of the fields, the encoding of the MAC — these stop
+// matching. That is the point.
+// ---------------------------------------------------------------------------
+
+const BASE_URL = 'https://mcp.example.com/b/reg_0123456789abcdef01234567';
+const SIGNING_KEY = 'test-blob-signing-key';
+const REGISTRATION_ID = 'reg_0123456789abcdef01234567';
+const REST = 'gmail/attachments/report.pdf';
+const OBJECT_KEY = `${REGISTRATION_ID}/${REST}`;
+const EXP = 1767225600000;
+const NOW = EXP - BLOB_URL_DEFAULT_TTL_MS;
+
+/** base64url(HMAC-SHA256(SIGNING_KEY, `<key>\n<exp>`)). */
+const READ_SIG = 'KrMn62kcDi-i9wW3JLvbZJdas4gP-EQuYoO-XMhcpNQ';
+/** base64url(HMAC-SHA256(SIGNING_KEY, `put\0<key>\0application/pdf\0<exp>`)). */
+const WRITE_PDF_SIG = 'qHPIRvchnjsbE8lam5dft3pIDBZu6Ae0HWZIG7kC9DQ';
+/** The same key and exp, signed for `text/plain` instead. */
+const WRITE_TEXT_SIG = 'FHtUlUVeEuREdbdKENy8rDU2ZETBQKF6V9IfaIWwWWo';
+
+function sign(payload: string): string {
+  return createHmac('sha256', SIGNING_KEY)
+    .update(payload, 'utf8')
+    .digest('base64url');
+}
+
+const minter = () => createBlobUrlMinter({ baseUrl: BASE_URL, signingKey: SIGNING_KEY });
+
+function params(url: string): URLSearchParams {
+  return new URL(url).searchParams;
+}
+
+afterEach(() => {
+  vi.unstubAllEnvs();
+});
+
+// ---------------------------------------------------------------------------
+
+describe('payload shapes', () => {
+  it('signs a read as `<key>\\n<exp>` — a newline, never a NUL', () => {
+    const payload = readPayload(OBJECT_KEY, EXP);
+    expect(payload).toBe('reg_0123456789abcdef01234567/gmail/attachments/report.pdf\n1767225600000');
+    expect(payload).toContain('\n');
+    expect(payload).not.toContain('\0');
+  });
+
+  it('signs a write as `put\\0<key>\\0<ct>\\0<exp>` — NUL-separated, content type inside', () => {
+    const payload = writePayload(OBJECT_KEY, 'application/pdf', EXP);
+    // The NUL is written as a `\u0000` escape, never `\0`: `\0` followed by a
+    // DIGIT is a legacy octal escape, so `'\01767…'` is U+0001 + "767…" — the
+    // vector then silently pins the wrong bytes (it did, on this test's first run).
+    expect(payload).toBe(
+      'put\u0000reg_0123456789abcdef01234567/gmail/attachments/report.pdf\u0000application/pdf\u00001767225600000',
+    );
+    expect(payload.split('\0')).toEqual([
+      'put',
+      OBJECT_KEY,
+      'application/pdf',
+      String(EXP),
+    ]);
+    expect(payload).not.toContain('\n');
+  });
+
+  it('never lets the two shapes converge', () => {
+    expect(readPayload(OBJECT_KEY, EXP)).not.toBe(writePayload(OBJECT_KEY, 'application/pdf', EXP));
+    // A read signature must be unreplayable as a write, whatever the content type.
+    expect(sign(readPayload(OBJECT_KEY, EXP))).not.toBe(
+      sign(writePayload(OBJECT_KEY, '', EXP)),
+    );
+  });
+});
+
+describe('createBlobUrlMinter', () => {
+  it('takes the registration id from the base URL\'s last path segment', () => {
+    expect(minter().registrationId).toBe(REGISTRATION_ID);
+  });
+
+  it('mints a GET URL matching the pinned read vector', () => {
+    const url = minter().getUrl(REST, { now: NOW });
+    expect(url).toBe(
+      `${BASE_URL}/gmail/attachments/report.pdf?exp=${EXP}&sig=${READ_SIG}`,
+    );
+    expect(params(url).get('sig')).toBe(sign(readPayload(OBJECT_KEY, EXP)));
+  });
+
+  it('mints a PUT URL matching the pinned write vector', () => {
+    const target = minter().putUrl(REST, 'application/pdf', { now: NOW });
+    expect(target.url).toBe(
+      `${BASE_URL}/gmail/attachments/report.pdf?exp=${EXP}&sig=${WRITE_PDF_SIG}`,
+    );
+    expect(params(target.url).get('sig')).toBe(
+      sign(writePayload(OBJECT_KEY, 'application/pdf', EXP)),
+    );
+  });
+
+  it('carries the content type it signed BACK with the URL', () => {
+    // The one field the gateway checks that no test in this repo can: it
+    // rebuilds the payload from the PUT's own `content-type` header
+    // (`gateway/src/blob.ts`, defaulting to application/octet-stream when the
+    // header is absent), so a caller that drops the header, lets an HTTP
+    // library default it, or re-cases it gets a 404 signature mismatch. Handing
+    // back a URL alone makes that a thing the uploader has to REMEMBER; handing
+    // back the pair makes it a thing it cannot drop.
+    const target = minter().putUrl(REST, 'application/pdf', { now: NOW });
+    expect(target.contentType).toBe('application/pdf');
+    expect(Object.keys(target).sort()).toEqual(['contentType', 'url']);
+  });
+
+  it('changes the signature when the content type changes', () => {
+    const pdf = params(minter().putUrl(REST, 'application/pdf', { now: NOW }).url).get('sig');
+    const text = params(minter().putUrl(REST, 'text/plain', { now: NOW }).url).get('sig');
+    expect(pdf).toBe(WRITE_PDF_SIG);
+    expect(text).toBe(WRITE_TEXT_SIG);
+    expect(pdf).not.toBe(text);
+  });
+
+  it('builds the object key as `<registrationId>/<rest>`, slashes and all', () => {
+    const url = minter().getUrl('a/b/c.pdf', { now: NOW });
+    // Raw, not `new URL(url).pathname` — same reason as the encoding cases below.
+    expect(url.split('?')[0]).toBe(`${BASE_URL}/a/b/c.pdf`);
+    expect(params(url).get('sig')).toBe(
+      sign(readPayload(`${REGISTRATION_ID}/a/b/c.pdf`, EXP)),
+    );
+  });
+
+  it('percent-encodes each URL segment while signing the logical key', () => {
+    const url = minter().getUrl('in box/a b.pdf', { now: NOW });
+    // Asserted on the RAW string the module returned, never through
+    // `new URL(url).pathname`: the parser percent-encodes a space itself on the
+    // way in, so a parsed pathname reads identically whether this module
+    // encoded anything or not — deleting `encodeURIComponent` from the wire
+    // left that assertion green (the one mutation of 25 that survived review).
+    expect(url).toBe(
+      `${BASE_URL}/in%20box/a%20b.pdf?exp=${EXP}&sig=${sign(readPayload(`${REGISTRATION_ID}/in box/a b.pdf`, EXP))}`,
+    );
+    // The gateway decodes per segment before it verifies, so the SIGNED key is
+    // the logical one — an encoded key here would 404 on every space.
+    expect(params(url).get('sig')).toBe(
+      sign(readPayload(`${REGISTRATION_ID}/in box/a b.pdf`, EXP)),
+    );
+  });
+
+  it('percent-encodes a `#` on the wire, so the query is still a query', () => {
+    // `Invoice #1234.pdf` is an ordinary Gmail attachment name, and it is the
+    // case a URL parser will NOT repair for us: unencoded, everything from the
+    // `#` is a FRAGMENT, so `?exp=&sig=` never reaches the gateway and the
+    // answer is 403 "missing signature" with nothing to debug. `?` truncates
+    // the path the same way. Raw string again, for the reason above.
+    const url = minter().getUrl('Invoice #1234.pdf', { now: NOW });
+    expect(url).toBe(
+      `${BASE_URL}/Invoice%20%231234.pdf?exp=${EXP}&sig=${sign(readPayload(`${REGISTRATION_ID}/Invoice #1234.pdf`, EXP))}`,
+    );
+    expect(url).not.toContain('#');
+    expect(params(url).get('sig')).toBe(
+      sign(readPayload(`${REGISTRATION_ID}/Invoice #1234.pdf`, EXP)),
+    );
+  });
+
+  it('tolerates a trailing slash on the base URL', () => {
+    const m = createBlobUrlMinter({ baseUrl: `${BASE_URL}/`, signingKey: SIGNING_KEY });
+    expect(m.registrationId).toBe(REGISTRATION_ID);
+    expect(m.getUrl(REST, { now: NOW })).toBe(
+      `${BASE_URL}/gmail/attachments/report.pdf?exp=${EXP}&sig=${READ_SIG}`,
+    );
+  });
+
+  it('defaults the expiry to one hour', () => {
+    const exp = Number(params(minter().getUrl(REST, { now: NOW })).get('exp'));
+    expect(exp - NOW).toBe(BLOB_URL_DEFAULT_TTL_MS);
+    expect(BLOB_URL_DEFAULT_TTL_MS).toBe(60 * 60 * 1000);
+  });
+
+  it('honours a shorter ttl', () => {
+    const exp = Number(params(minter().getUrl(REST, { now: NOW, ttlMs: 5000 })).get('exp'));
+    expect(exp).toBe(NOW + 5000);
+  });
+
+  it('clamps the expiry UNDER the gateway\'s 24-hour ceiling rather than trusting the caller', () => {
+    const exp = Number(
+      params(minter().getUrl(REST, { now: NOW, ttlMs: 7 * 24 * 60 * 60 * 1000 })).get('exp'),
+    );
+    expect(exp).toBe(NOW + BLOB_URL_MAX_TTL_MS - BLOB_URL_CEILING_MARGIN_MS);
+    expect(BLOB_URL_MAX_TTL_MS).toBe(24 * 60 * 60 * 1000);
+  });
+
+  it('never mints an exp AT the ceiling, so a clock a hair ahead is not a 403', () => {
+    // `blob.ts` refuses with a strict `exp > Date.now() + MAX_TTL_MS`, judged on
+    // the GATEWAY's clock against an exp computed on the CHILD's. Landing
+    // exactly on the ceiling leaves zero skew budget: one millisecond of the
+    // child running ahead is a hard 403 "expiry out of range", whose message
+    // names no cause the caller can act on. And BLOB_URL_MAX_TTL_MS is exported,
+    // so `ttlMs: BLOB_URL_MAX_TTL_MS` is the natural way to ask for the longest
+    // legal link — the API invites exactly the request that would break.
+    for (const ttlMs of [BLOB_URL_MAX_TTL_MS, BLOB_URL_MAX_TTL_MS + 1, Number.MAX_SAFE_INTEGER]) {
+      const exp = Number(params(minter().getUrl(REST, { now: NOW, ttlMs })).get('exp'));
+      expect(exp).toBeLessThan(NOW + BLOB_URL_MAX_TTL_MS);
+      expect(exp).toBe(NOW + BLOB_URL_MAX_TTL_MS - BLOB_URL_CEILING_MARGIN_MS);
+    }
+    expect(BLOB_URL_CEILING_MARGIN_MS).toBeGreaterThan(0);
+  });
+
+  it('clamps a zero or negative ttl up to one second, never to an already-dead link', () => {
+    expect(Number(params(minter().getUrl(REST, { now: NOW, ttlMs: 0 })).get('exp'))).toBe(NOW + 1000);
+    expect(Number(params(minter().getUrl(REST, { now: NOW, ttlMs: -1 })).get('exp'))).toBe(NOW + 1000);
+  });
+
+  it('reads the clock when no `now` is given', () => {
+    vi.useFakeTimers();
+    try {
+      vi.setSystemTime(NOW);
+      expect(minter().getUrl(REST)).toBe(
+        `${BASE_URL}/gmail/attachments/report.pdf?exp=${EXP}&sig=${READ_SIG}`,
+      );
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it.each([
+    'https://mcp.example.com/b/',
+    'https://mcp.example.com/b',
+    'https://mcp.example.com/',
+    'https://mcp.example.com',
+  ])('refuses the base URL %j — no registration id in the path', (baseUrl) => {
+    expect(() => createBlobUrlMinter({ baseUrl, signingKey: 'k' }))
+      .toThrow(/registration id/i);
+  });
+
+  it('refuses a base URL that is not a URL', () => {
+    expect(() => createBlobUrlMinter({ baseUrl: 'not a url', signingKey: 'k' }))
+      .toThrow(/MCP_BLOB_BASE_URL/);
+  });
+
+  it('refuses an empty signing key', () => {
+    expect(() => createBlobUrlMinter({ baseUrl: BASE_URL, signingKey: '' }))
+      .toThrow(/MCP_BLOB_SIGNING_KEY/);
+  });
+
+  it.each([
+    ['', 'empty'],
+    ['/', 'empty segment'],
+    ['a//b', 'empty segment'],
+    ['../etc/passwd', 'traversal'],
+    ['a/./b', 'traversal'],
+    ['a/../b', 'traversal'],
+  ])('refuses the object path %j (%s)', (rest) => {
+    // The gateway refuses these outright rather than normalising them, so a URL
+    // minted for one would 404 at the door. Fail here, where the message can say why.
+    expect(() => minter().getUrl(rest, { now: NOW })).toThrow(/object path/i);
+  });
+
+  // EVERY refusal this module makes, not only the one easiest to reach. The key
+  // is a credential and so is a signed URL, while an error message is the one
+  // value here that is EXPECTED to be logged — so the guard has to bind the
+  // constructor's three refusals as well as the mint-time one. With only the
+  // `../escape` case it did not: rewriting the unparseable-base-URL throw to
+  // interpolate `config.signingKey` left the whole suite green.
+  it.each([
+    ['empty signing key', () => createBlobUrlMinter({ baseUrl: BASE_URL, signingKey: '' })],
+    ['unparseable base URL', () => createBlobUrlMinter({ baseUrl: 'not a url', signingKey: SIGNING_KEY })],
+    ['base URL with no registration id', () => createBlobUrlMinter({ baseUrl: 'https://mcp.example.com/b/', signingKey: SIGNING_KEY })],
+    ['refused object path', () => minter().getUrl('../escape', { now: NOW })],
+  ])('never puts the signing key or a signed URL in the error for a %s', (_label, refuse) => {
+    try {
+      refuse();
+      expect.unreachable('should have thrown');
+    } catch (err) {
+      expect(String(err)).not.toContain(SIGNING_KEY);
+      expect(String(err)).not.toContain('sig=');
+    }
+  });
+});
+
+describe('blobStoreFromEnv', () => {
+  it('returns the pair when both variables are set', () => {
+    vi.stubEnv('MCP_BLOB_BASE_URL', BASE_URL);
+    vi.stubEnv('MCP_BLOB_SIGNING_KEY', SIGNING_KEY);
+    expect(blobStoreFromEnv()).toEqual({ baseUrl: BASE_URL, signingKey: SIGNING_KEY });
+  });
+
+  it('returns undefined on a local stdio install, where neither is set', () => {
+    vi.stubEnv('MCP_BLOB_BASE_URL', '');
+    vi.stubEnv('MCP_BLOB_SIGNING_KEY', '');
+    expect(blobStoreFromEnv()).toBeUndefined();
+  });
+
+  it('returns undefined when only the base URL is set', () => {
+    vi.stubEnv('MCP_BLOB_BASE_URL', BASE_URL);
+    vi.stubEnv('MCP_BLOB_SIGNING_KEY', '');
+    expect(blobStoreFromEnv()).toBeUndefined();
+  });
+
+  it('returns undefined when only the signing key is set', () => {
+    vi.stubEnv('MCP_BLOB_BASE_URL', '');
+    vi.stubEnv('MCP_BLOB_SIGNING_KEY', SIGNING_KEY);
+    expect(blobStoreFromEnv()).toBeUndefined();
+  });
+
+  it('treats an unresolved .mcpb placeholder as unset', () => {
+    vi.stubEnv('MCP_BLOB_BASE_URL', '${user_config.blob_base_url}');
+    vi.stubEnv('MCP_BLOB_SIGNING_KEY', SIGNING_KEY);
+    expect(blobStoreFromEnv()).toBeUndefined();
+  });
+});

package/tests/runner.test.ts

@@ -499,7 +499,7 @@ describe('run', () => {
     }
   });
 
-  it('strips GOOGLE_APPLICATION_CREDENTIALS and *_TOKEN/*_SECRET/*_API_KEY/*_PRIVATE_KEY vars', async () => {
+  it('strips GOOGLE_APPLICATION_CREDENTIALS and *_TOKEN/*_SECRET/*_KEY/*_CREDENTIALS vars', async () => {
     const spawner = makeSpawner(0, '{}');
     const snapshot = {
       GOOGLE_APPLICATION_CREDENTIALS: process.env.GOOGLE_APPLICATION_CREDENTIALS,
@@ -532,6 +532,67 @@ describe('run', () => {
     }
   });
 
+  // The suffix list was `_TOKEN|_SECRET|_API_KEY|_PRIVATE_KEY` — four spellings
+  // of "a key", none of which is a bare `_KEY`. Two credentials this repo hands
+  // its own process sit in exactly that gap: `MCP_BLOB_SIGNING_KEY` (mints the
+  // signed blob URLs a `deliver="url"` download is uploaded to) and
+  // `GOG_RUNNER_KEY` (the bearer for the Fly backend, and for `POST /upload`,
+  // which is arbitrary-gog-argv on that box). Neither is anything `gog` reads.
+  it('strips a bare *_KEY var — the host signing key and the runner bearer', async () => {
+    const spawner = makeSpawner(0, '{}');
+    const snapshot = {
+      MCP_BLOB_SIGNING_KEY: process.env.MCP_BLOB_SIGNING_KEY,
+      GOG_RUNNER_KEY: process.env.GOG_RUNNER_KEY,
+      STRIPE_KEY: process.env.STRIPE_KEY,
+      AWS_CREDENTIALS: process.env.AWS_CREDENTIALS,
+    };
+    process.env.MCP_BLOB_SIGNING_KEY = 'blob-signing-secret';
+    process.env.GOG_RUNNER_KEY = 'runner-bearer-secret';
+    process.env.STRIPE_KEY = 'sk-live-secret';
+    process.env.AWS_CREDENTIALS = '/path/to/creds';
+    try {
+      await run(['docs', 'cat', 'id'], { spawner });
+      const envPassed = (spawner as ReturnType<typeof vi.fn>).mock.calls[0][2].env as NodeJS.ProcessEnv;
+      expect(envPassed.MCP_BLOB_SIGNING_KEY).toBeUndefined();
+      expect(envPassed.GOG_RUNNER_KEY).toBeUndefined();
+      expect(envPassed.STRIPE_KEY).toBeUndefined();
+      // `_CREDENTIALS`, generalising the one named GOOGLE_APPLICATION_CREDENTIALS.
+      expect(envPassed.AWS_CREDENTIALS).toBeUndefined();
+    } finally {
+      for (const [k, v] of Object.entries(snapshot)) {
+        if (v === undefined) delete process.env[k];
+        else process.env[k] = v;
+      }
+    }
+  });
+
+  // The CONTROL on widening, and the reason the list is not simply "anything
+  // that smells like a credential": `GOG_KEYRING_PASSWORD` is how gog decrypts
+  // its own file keyring (`GOG_KEYRING_BACKEND=file`), so a `_PASSWORD` rule
+  // would strip the one credential the child legitimately needs and turn every
+  // call into an auth failure. `GOG_KEYRING_BACKEND` is the same story without
+  // the secret.
+  it('keeps the credentials gog itself reads from the environment', async () => {
+    const spawner = makeSpawner(0, '{}');
+    const snapshot = {
+      GOG_KEYRING_PASSWORD: process.env.GOG_KEYRING_PASSWORD,
+      GOG_KEYRING_BACKEND: process.env.GOG_KEYRING_BACKEND,
+    };
+    process.env.GOG_KEYRING_PASSWORD = 'keyring-pass';
+    process.env.GOG_KEYRING_BACKEND = 'file';
+    try {
+      await run(['docs', 'cat', 'id'], { spawner });
+      const envPassed = (spawner as ReturnType<typeof vi.fn>).mock.calls[0][2].env as NodeJS.ProcessEnv;
+      expect(envPassed.GOG_KEYRING_PASSWORD).toBe('keyring-pass');
+      expect(envPassed.GOG_KEYRING_BACKEND).toBe('file');
+    } finally {
+      for (const [k, v] of Object.entries(snapshot)) {
+        if (v === undefined) delete process.env[k];
+        else process.env[k] = v;
+      }
+    }
+  });
+
   it('redacts Bearer with quoted/encoded characters', async () => {
     const stderrLeak = 'http 401: header was Bearer eyJ.test+slash/equal=padding more text';
     const spawner = makeSpawner(1, '', stderrLeak);

package/tests/zod-single-copy.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, it } from 'vitest';
+import { createRequire } from 'node:module';
+import { realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+// The zod counterpart of sdk-single-copy.test.ts, guarding the invariant that
+// broke dependabot #333: the whole monorepo must resolve ONE copy of zod.
+//
+// Same shape of failure, a different package. `@cloudflare/vitest-pool-workers`
+// (a root devDependency) declares zod as an **exact** pin, so it takes the
+// hoisted root slot that `@chrischall/mcp-utils` and the MCP SDK resolve their
+// zod peer from. The moment our workspaces ask for a newer zod than that pin,
+// each nests its own copy — and because a `ZodType` carries brand-bearing
+// internals, TypeScript compares the two NOMINALLY: every schema our tools hand
+// `registerTool` fails with `TS2322: Type 'ZodString' is not assignable to type
+// 'AnySchema'`, with no API change and nothing to fix in the source. #333 split
+// the tree exactly that way and produced 11,024 type errors from a bump of one
+// patch-level dependency.
+//
+// Read the resolved paths in such an error, not the signature.
+//
+// This asserts resolution identity rather than a version string: the failure is
+// "two copies", not "the wrong version", and pinning a version here would just
+// have to be edited on every future bump.
+describe('zod is installed exactly once', () => {
+  const here = createRequire(import.meta.url);
+
+  // `import.meta.resolve`, not `require.resolve`, to reach the dependency's own
+  // entry: these packages are ESM-only, so their `exports` maps carry no
+  // `require` condition and CJS resolution of the bare specifier throws.
+  const resolveFrom = (specifier: string): string =>
+    realpathSync(createRequire(fileURLToPath(import.meta.resolve(specifier))).resolve('zod'));
+
+  it('resolves to the same file for this package and for @chrischall/mcp-utils', () => {
+    // mcp-utils declares zod as a peer, and its `accountParam` / `viewParam` /
+    // `paginationParams` helpers build the very schemas our registrars pass to
+    // `registerTool`, so its copy is the one they must be typed against.
+    expect(resolveFrom('@chrischall/mcp-utils')).toBe(realpathSync(here.resolve('zod')));
+  });
+
+  it('resolves to the same file for the MCP SDK, which types every tool schema', () => {
+    // `registerTool` accepts the raw shape and infers the handler's argument
+    // types from it; a second copy makes every one of those schemas foreign.
+    expect(resolveFrom('@modelcontextprotocol/sdk/server/mcp.js')).toBe(
+      realpathSync(here.resolve('zod')),
+    );
+  });
+
+  it('resolves to the same file for @cloudflare/vitest-pool-workers, which exact-pins zod', () => {
+    // The exact pin here is what captured the root hoist slot in #333, and it
+    // is why the root `overrides` block carries a zod entry.
+    expect(resolveFrom('@cloudflare/vitest-pool-workers')).toBe(
+      realpathSync(here.resolve('zod')),
+    );
+  });
+});