pombus 0.0.1 → 0.1.0

package/dist/installer.test.js

@@ -0,0 +1,344 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, readFileSync, writeFileSync, rmSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { runInit } from "./init.js";
+import { runDoctor } from "./doctor.js";
+import { clientTargets, writeJsonConfig, isInsideHome, printableJson, printableCodexToml, ConfigWriteError, } from "./clients.js";
+import { FakeCore, authMeInbox, authMePod, createdInbox } from "./testutil.js";
+// Obviously-fake tokens — never a real secret (AGENTS.md §9).
+const BROAD_KEY = "pk_test_broad_pod_scope_FAKE";
+const BASE = "https://core.test/v0";
+/** A temp HOME, cleaned up after each use. */
+function tempHome() {
+    const home = mkdtempSync(join(tmpdir(), "pombus-home-"));
+    return { home, cleanup: () => rmSync(home, { recursive: true, force: true }) };
+}
+/** A line sink that records init/doctor human output for assertions. */
+function sink() {
+    const lines = [];
+    return { lines, out: (l) => lines.push(l) };
+}
+// ---------------------------------------------------------------------------------------------------
+// clients.ts — the write is the sharp edge: merge, idempotent, atomic-ish, 0600, never outside HOME.
+// ---------------------------------------------------------------------------------------------------
+test("writeJsonConfig MERGES — preserves every existing key, adds only mcpServers.pombus", () => {
+    const { home, cleanup } = tempHome();
+    try {
+        const path = join(home, ".claude.json");
+        writeFileSync(path, JSON.stringify({
+            projects: { "/some/proj": { history: [1, 2, 3] } },
+            theme: "dark",
+            mcpServers: { other: { command: "node", args: ["x.js"] } },
+        }));
+        writeJsonConfig(path, home, BROAD_KEY);
+        const after = JSON.parse(readFileSync(path, "utf8"));
+        // Untouched keys survive byte-for-value.
+        assert.deepEqual(after["projects"], { "/some/proj": { history: [1, 2, 3] } });
+        assert.equal(after["theme"], "dark");
+        // The pre-existing OTHER server survives; ours is added alongside.
+        assert.deepEqual(after["mcpServers"]["other"], { command: "node", args: ["x.js"] });
+        assert.deepEqual(after["mcpServers"]["pombus"], {
+            command: "npx",
+            args: ["-y", "pombus", "mcp"],
+            env: { POMBUS_API_KEY: BROAD_KEY },
+        });
+    }
+    finally {
+        cleanup();
+    }
+});
+test("writeJsonConfig is IDEMPOTENT — running twice yields exactly one pombus entry", () => {
+    const { home, cleanup } = tempHome();
+    try {
+        const path = join(home, ".cursor", "mcp.json");
+        writeJsonConfig(path, home, BROAD_KEY);
+        writeJsonConfig(path, home, BROAD_KEY);
+        const after = JSON.parse(readFileSync(path, "utf8"));
+        const servers = after["mcpServers"];
+        assert.deepEqual(Object.keys(servers), ["pombus"]);
+    }
+    finally {
+        cleanup();
+    }
+});
+test("writeJsonConfig creates a fresh file when none exists (and its parent dir)", () => {
+    const { home, cleanup } = tempHome();
+    try {
+        const path = join(home, ".gemini", "settings.json");
+        writeJsonConfig(path, home, BROAD_KEY);
+        const after = JSON.parse(readFileSync(path, "utf8"));
+        assert.equal(after["mcpServers"]["pombus"]["env"]["POMBUS_API_KEY"], BROAD_KEY);
+    }
+    finally {
+        cleanup();
+    }
+});
+test("writeJsonConfig REFUSES to clobber a corrupt existing config (never destroys real state)", () => {
+    const { home, cleanup } = tempHome();
+    try {
+        const path = join(home, ".claude.json");
+        writeFileSync(path, "{ this is not valid json ");
+        assert.throws(() => writeJsonConfig(path, home, BROAD_KEY), (e) => e instanceof ConfigWriteError && e.code === "corrupt_config");
+        // The broken file is left exactly as it was — not overwritten.
+        assert.equal(readFileSync(path, "utf8"), "{ this is not valid json ");
+    }
+    finally {
+        cleanup();
+    }
+});
+test("writeJsonConfig REFUSES a target outside HOME (never writes into a project repo)", () => {
+    const { home, cleanup } = tempHome();
+    try {
+        const outside = join(tmpdir(), "not-home-" + process.pid, "mcp.json");
+        assert.throws(() => writeJsonConfig(outside, home, BROAD_KEY), (e) => e instanceof ConfigWriteError && e.code === "outside_home");
+    }
+    finally {
+        cleanup();
+    }
+});
+test("isInsideHome accepts HOME and children, rejects siblings and the project tree", () => {
+    const home = join(tmpdir(), "h");
+    assert.ok(isInsideHome(join(home, ".cursor", "mcp.json"), home));
+    assert.ok(isInsideHome(home, home));
+    assert.ok(!isInsideHome(join(tmpdir(), "hother", "x.json"), home));
+    assert.ok(!isInsideHome("/etc/mcp.json", home));
+});
+test("the config file carrying the key is 0600 on POSIX (owner-only)", { skip: process.platform === "win32" }, () => {
+    const { home, cleanup } = tempHome();
+    try {
+        const path = join(home, ".cursor", "mcp.json");
+        writeJsonConfig(path, home, BROAD_KEY);
+        const mode = statSync(path).mode & 0o777;
+        assert.equal(mode, 0o600, `expected 0600, got ${mode.toString(8)}`);
+    }
+    finally {
+        cleanup();
+    }
+});
+test("the client table: claude-code/cursor/gemini are WRITE (json), codex is PRINT (toml)", () => {
+    const home = join(tmpdir(), "h");
+    const t = clientTargets(home);
+    const by = Object.fromEntries(t.map((c) => [c.id, c]));
+    assert.equal(by["claude-code"].mode, "json");
+    assert.equal(by["cursor"].mode, "json");
+    assert.equal(by["gemini"].mode, "json");
+    assert.equal(by["codex"].mode, "print");
+    // Every target carries a cited source and a path under HOME.
+    for (const c of t) {
+        assert.ok(c.source.length > 0, `${c.id} missing source`);
+        assert.ok(isInsideHome(c.path, home), `${c.id} path escapes HOME`);
+    }
+});
+test("printable blocks: JSON has the standard mcpServers wrapper; Codex TOML is a [mcp_servers.pombus] table", () => {
+    const j = JSON.parse(printableJson("<KEY>"));
+    assert.deepEqual(j.mcpServers.pombus, {
+        command: "npx",
+        args: ["-y", "pombus", "mcp"],
+        env: { POMBUS_API_KEY: "<KEY>" },
+    });
+    const toml = printableCodexToml("<KEY>");
+    assert.ok(toml.includes("[mcp_servers.pombus]"));
+    assert.ok(toml.includes('command = "npx"'));
+    assert.ok(toml.includes("POMBUS_API_KEY = '<KEY>'"));
+});
+// ---------------------------------------------------------------------------------------------------
+// runInit key contract (option A): the key the user provided is persisted verbatim — no mint, no
+// narrowing. The agent is the account's full operator and runs with the key the user chose to give.
+// ---------------------------------------------------------------------------------------------------
+test("init persists EXACTLY the provided key — never mints a new one (no POST /api-keys)", async () => {
+    const { home, cleanup } = tempHome();
+    try {
+        // --create-inbox on a pod key: an inbox is created, but the key written is still the given one.
+        const fake = new FakeCore()
+            .on("GET", (u) => u.pathname.endsWith("/auth/me"), authMePod())
+            .on("POST", (u) => u.pathname.endsWith("/inboxes"), createdInbox("inb_new", "agent@pombus.com"));
+        const { out } = sink();
+        const res = await runInit({
+            apiKey: BROAD_KEY,
+            createInbox: true,
+            client: "cursor",
+            home,
+            baseUrl: BASE,
+            fetchImpl: fake.fetch,
+            locale: "en-US",
+            out,
+        });
+        assert.deepEqual(res.written, ["cursor"]);
+        assert.equal(res.inboxId, "inb_new"); // --create-inbox still works, independent of the key
+        const cfg = JSON.parse(readFileSync(join(home, ".cursor", "mcp.json"), "utf8"));
+        assert.equal(cfg.mcpServers.pombus.env.POMBUS_API_KEY, BROAD_KEY, "the provided key is persisted as-is");
+        // No key was minted — the installer never hits POST /api-keys.
+        assert.ok(!fake.requests.some((r) => r.method === "POST" && r.url.includes("/api-keys")));
+    }
+    finally {
+        cleanup();
+    }
+});
+test("init with an inbox-scoped key persists it as-is (no /api-keys call)", async () => {
+    const { home, cleanup } = tempHome();
+    try {
+        const fake = new FakeCore().on("GET", (u) => u.pathname.endsWith("/auth/me"), authMeInbox("inb_fixed"));
+        const { out } = sink();
+        const res = await runInit({
+            apiKey: BROAD_KEY, // the value is opaque to init; it is written verbatim
+            client: "cursor",
+            home,
+            baseUrl: BASE,
+            fetchImpl: fake.fetch,
+            locale: "en-US",
+            out,
+        });
+        assert.deepEqual(res.written, ["cursor"]);
+        assert.ok(!fake.requests.some((r) => r.url.includes("/api-keys")));
+        const cfg = JSON.parse(readFileSync(join(home, ".cursor", "mcp.json"), "utf8"));
+        assert.equal(cfg.mcpServers.pombus.env.POMBUS_API_KEY, BROAD_KEY);
+    }
+    finally {
+        cleanup();
+    }
+});
+// ---------------------------------------------------------------------------------------------------
+// --print writes NOTHING.
+// ---------------------------------------------------------------------------------------------------
+test("init --print writes NO file and emits the block", async () => {
+    const { home, cleanup } = tempHome();
+    try {
+        const fake = new FakeCore().on("GET", (u) => u.pathname.endsWith("/auth/me"), authMeInbox("inb_fixed"));
+        const { lines, out } = sink();
+        const res = await runInit({
+            apiKey: BROAD_KEY,
+            print: true,
+            client: "cursor",
+            home,
+            baseUrl: BASE,
+            fetchImpl: fake.fetch,
+            locale: "en-US",
+            out,
+        });
+        assert.equal(res.printed, true);
+        assert.deepEqual(res.written, []);
+        // No config file was created.
+        assert.throws(() => readFileSync(join(home, ".cursor", "mcp.json"), "utf8"));
+        assert.ok(lines.some((l) => l.includes('"pombus"')));
+    }
+    finally {
+        cleanup();
+    }
+});
+test("init --print with NO key emits a placeholder block, makes no network call, writes nothing", async () => {
+    const { home, cleanup } = tempHome();
+    try {
+        const fake = new FakeCore().on("GET", () => true, { json: {} });
+        const { lines, out } = sink();
+        const res = await runInit({
+            print: true,
+            client: "cursor",
+            home,
+            baseUrl: BASE,
+            fetchImpl: fake.fetch,
+            locale: "en-US",
+            out,
+        });
+        assert.equal(res.printed, true);
+        assert.equal(fake.requests.length, 0, "no network call without a key");
+        assert.ok(lines.some((l) => l.includes("<YOUR_POMBUS_API_KEY>")));
+    }
+    finally {
+        cleanup();
+    }
+});
+test("init on a PRINT-only client (codex) prints TOML and writes no file", async () => {
+    const { home, cleanup } = tempHome();
+    try {
+        const fake = new FakeCore().on("GET", (u) => u.pathname.endsWith("/auth/me"), authMeInbox("inb_fixed"));
+        const { lines, out } = sink();
+        const res = await runInit({
+            apiKey: BROAD_KEY,
+            client: "codex",
+            home,
+            baseUrl: BASE,
+            fetchImpl: fake.fetch,
+            locale: "en-US",
+            out,
+        });
+        assert.deepEqual(res.written, []);
+        assert.deepEqual(res.printedFor, ["codex"]);
+        assert.throws(() => readFileSync(join(home, ".codex", "config.toml"), "utf8"));
+        assert.ok(lines.some((l) => l.includes("[mcp_servers.pombus]")));
+    }
+    finally {
+        cleanup();
+    }
+});
+// ---------------------------------------------------------------------------------------------------
+// doctor — reports scope / errors, read-only.
+// ---------------------------------------------------------------------------------------------------
+test("doctor reports the scope of a valid key", async () => {
+    const fake = new FakeCore().on("GET", (u) => u.pathname.endsWith("/auth/me"), authMePod());
+    const { lines, out } = sink();
+    const res = await runDoctor({ apiKey: BROAD_KEY, baseUrl: BASE, fetchImpl: fake.fetch, locale: "en-US", out });
+    assert.equal(res.ok, true);
+    assert.equal(res.scope, "pod");
+    assert.ok(lines.some((l) => l.includes("pod")));
+    // Read-only: the single request was the /auth/me GET.
+    assert.equal(fake.requests.length, 1);
+    assert.equal(fake.requests[0].method, "GET");
+});
+test("doctor with no key reports no_api_key and makes no network call", async () => {
+    const fake = new FakeCore().on("GET", () => true, { json: {} });
+    const { out } = sink();
+    const res = await runDoctor({ baseUrl: BASE, fetchImpl: fake.fetch, locale: "en-US", out });
+    assert.equal(res.ok, false);
+    assert.equal(res.code, "no_api_key");
+    assert.equal(fake.requests.length, 0);
+});
+test("doctor with an invalid key reports auth_failed (401/403/404 collapse to not_found -> auth_failed)", async () => {
+    const fake = new FakeCore().on("GET", (u) => u.pathname.endsWith("/auth/me"), { status: 401, json: { code: "unauthorized" } });
+    const { out } = sink();
+    const res = await runDoctor({ apiKey: "pk_test_bad_FAKE", baseUrl: BASE, fetchImpl: fake.fetch, locale: "en-US", out });
+    assert.equal(res.ok, false);
+    assert.equal(res.code, "auth_failed");
+});
+test("doctor with an unreachable core reports network", async () => {
+    const fetchImpl = async () => {
+        throw new TypeError("fetch failed");
+    };
+    const { out } = sink();
+    const res = await runDoctor({ apiKey: "pk_test_x_FAKE", baseUrl: BASE, fetchImpl, locale: "en-US", out });
+    assert.equal(res.ok, false);
+    assert.equal(res.code, "network");
+});
+// ---------------------------------------------------------------------------------------------------
+// the key never leaks into human output (log hygiene, AGENTS.md §5).
+// ---------------------------------------------------------------------------------------------------
+test("no human line printed by init or doctor ever contains the BROAD key", async () => {
+    const { home, cleanup } = tempHome();
+    try {
+        const fake = new FakeCore()
+            .on("GET", (u) => u.pathname.endsWith("/auth/me"), authMePod())
+            .on("POST", (u) => u.pathname.endsWith("/inboxes"), createdInbox("inb_new", "agent@pombus.com"));
+        const initSink = sink();
+        await runInit({
+            apiKey: BROAD_KEY,
+            createInbox: true,
+            client: "cursor",
+            home,
+            baseUrl: BASE,
+            fetchImpl: fake.fetch,
+            locale: "pt-BR",
+            out: initSink.out,
+        });
+        for (const l of initSink.lines)
+            assert.ok(!l.includes(BROAD_KEY), `broad key leaked: ${l}`);
+        const docSink = sink();
+        const fake2 = new FakeCore().on("GET", (u) => u.pathname.endsWith("/auth/me"), authMePod());
+        await runDoctor({ apiKey: BROAD_KEY, baseUrl: BASE, fetchImpl: fake2.fetch, locale: "es-419", out: docSink.out });
+        for (const l of docSink.lines)
+            assert.ok(!l.includes(BROAD_KEY), `broad key leaked (doctor): ${l}`);
+    }
+    finally {
+        cleanup();
+    }
+});

package/dist/scope.js

@@ -0,0 +1,118 @@
+// Scope binding — the core of F4's access rule (strategy doc 4.2/4.3, adoption spec line 104):
+// the model NEVER supplies a raw inbox_id that escapes the API key's scope.
+//
+// On boot the server calls GET /v0/auth/me and learns the key's scope:
+//   - inbox / domain key  -> a single inbox is implied. The inbox_id is DERIVED from the scope and the
+//     tools that need one do NOT accept it as an argument at all. The model cannot address any other
+//     inbox because the parameter does not exist in the tool schema.
+//   - pod / organization key -> the key can see many inboxes. `list_inboxes` enumerates the ones the
+//     key may reach; a tool that needs an inbox_id accepts only an id the server has seen in that
+//     enumeration, validated against the allowed set before any request leaves the process.
+//
+// The core already fences every route by scope (authz_inbox), so this layer is defense in depth plus
+// an honest tool schema: the key's authority — not the model's argument — decides which inbox is read.
+/** The resolved binding the tool layer consults. `fixedInboxId` set => single-inbox key: tools drop
+ *  the inbox_id parameter entirely. Otherwise => multi-inbox key: tools require a listed inbox_id,
+ *  checked via `allows`. `permissions` drives the catalog gate; `podId` lets pod-scoped tools derive
+ *  the pod from the key's own scope instead of taking it as a free model argument. */
+export class ScopeBinding {
+    scopeType;
+    fixedInboxId;
+    // The key's permission set, verbatim from /auth/me. null = master (full access); an object = scoped.
+    permissions;
+    // The pod the key is bound to, when it is pod/inbox/domain-scoped. An org (master) key has none, so a
+    // pod-scoped tool must then take a validated pod_id argument. Pod-scoped tools NEVER take a free
+    // pod_id when this is set — the key's own pod is used, so the model can't address another tenant.
+    podId;
+    // The set of inbox ids the key has been observed to reach, grown lazily by list_inboxes. A pod/org
+    // key can reach ids not yet listed; `allows` therefore also confirms unknown ids against the core
+    // (fail-closed) rather than rejecting them for being unseen.
+    seen = new Set();
+    constructor(scopeType, fixedInboxId, permissions, podId) {
+        this.scopeType = scopeType;
+        this.fixedInboxId = fixedInboxId;
+        this.permissions = permissions;
+        this.podId = podId;
+    }
+    /** True when the key binds exactly one inbox (inbox or domain... no: domain reaches many). Only an
+     *  inbox-scoped key is truly single. A domain key reaches every inbox of its domain, so it is
+     *  multi-inbox like a pod key. */
+    get isSingleInbox() {
+        return this.fixedInboxId !== null;
+    }
+    /** The catalog gate: does the key hold the permission a tool requires? A master key (permissions ===
+     *  null) holds everything. A scoped key holds `perm` when its object has it true — with ONE mirror of
+     *  the core's rule (api.py:1331-1334): message_send satisfies message_reply, so a key that can send
+     *  can also reply. Tools whose gate is false are never REGISTERED (hidden, not registered-then-403). */
+    gateAllows(requiredPerm) {
+        if (this.permissions === null)
+            return true; // master key
+        if (requiredPerm === null)
+            return true; // a tool with no gated route (none scope)
+        if (this.permissions[requiredPerm] === true)
+            return true;
+        if (requiredPerm === "message_reply" && this.permissions["message_send"] === true)
+            return true;
+        return false;
+    }
+    /** Call /v0/auth/me and build the binding. An inbox key yields a fixed inbox_id; every other scope
+     *  is multi-inbox and the inbox_id must be supplied-and-validated per call. Captures the key's
+     *  permissions (catalog gate) and pod_id (pod-scoped tools derive the pod from the scope). */
+    static async resolve(client) {
+        const me = await client.get("/auth/me");
+        const permissions = me.permissions ?? null;
+        const podId = me.pod_id ?? null;
+        if (me.scope_type === "inbox" && me.inbox_id) {
+            return new ScopeBinding("inbox", me.inbox_id, permissions, podId);
+        }
+        // domain / pod / organization: no single implied inbox.
+        return new ScopeBinding(me.scope_type, null, permissions, podId);
+    }
+    /** Record inbox ids returned by list_inboxes so later calls can validate against the enumeration. */
+    remember(ids) {
+        for (const id of ids)
+            this.seen.add(id);
+    }
+    /** Resolve the inbox_id a tool will act on. For a single-inbox key the model's argument (if any) is
+     *  IGNORED and the fixed id is used — the model can never widen past its scope. For a multi-inbox
+     *  key the argument is required and must be an id the key can reach: known from a prior list, or
+     *  confirmed against the core (which fences by scope and 404s an inbox outside it). Returns the id,
+     *  or throws a stable `not_found` (never distinguishing "unknown" from "forbidden"). */
+    async resolveInboxId(client, requested) {
+        if (this.fixedInboxId !== null)
+            return this.fixedInboxId;
+        const id = (requested ?? "").trim();
+        if (!id)
+            throw new ScopeError("inbox_required");
+        if (this.seen.has(id))
+            return id;
+        // Not seen yet. Confirm it against the core: get_inbox 404s (via not_found) for any inbox the key
+        // may not reach, so a hostile id never turns into a cross-tenant read. On success, remember it.
+        await client.get(`/inboxes/${encodeURIComponent(id)}`); // throws CoreError('not_found') if out of scope
+        this.seen.add(id);
+        return id;
+    }
+    /** Resolve the pod_id a pod-scoped tool acts on. Same discipline as resolveInboxId: when the key is
+     *  itself pod/inbox/domain-scoped the model's argument is IGNORED and the key's own pod is used — it
+     *  cannot address another tenant. Only a master (org) key, which binds no single pod, must supply a
+     *  pod_id; it is then validated against the core (get_pod 404s -> not_found for an unknown pod) so a
+     *  forged id never turns into a cross-tenant action. */
+    async resolvePodId(client, requested) {
+        if (this.podId !== null)
+            return this.podId;
+        const id = (requested ?? "").trim();
+        if (!id)
+            throw new ScopeError("pod_required");
+        await client.get(`/pods/${encodeURIComponent(id)}`); // throws CoreError('not_found') if out of scope
+        return id;
+    }
+}
+/** A scope-layer failure the tool layer maps to an i18n message for a human. Locale-free, key-free. */
+export class ScopeError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.name = "ScopeError";
+        this.code = code;
+    }
+}

package/dist/security.test.js

@@ -0,0 +1,111 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { CoreClient, CoreError } from "./client.js";
+import { ScopeBinding } from "./scope.js";
+import { specByName, callTool } from "./tools.js";
+import { buildServer } from "./server.js";
+import { FakeCore, authMeInbox, authMePod } from "./testutil.js";
+const KEY = "pk_live_secret_do_not_log_abcdef";
+async function ctxFor(fake) {
+    const client = new CoreClient({ apiKey: KEY, baseUrl: "https://core.test/v0", fetchImpl: fake.fetch });
+    const scope = await ScopeBinding.resolve(client);
+    return { client, scope };
+}
+test("the API key rides ONLY in the Authorization header — never in a URL", async () => {
+    const fake = new FakeCore()
+        .on("GET", (u) => u.pathname.endsWith("/auth/me"), authMeInbox("inb_x"))
+        .on("GET", () => true, { json: { ok: true } });
+    const ctx = await ctxFor(fake);
+    await callTool(specByName("list_messages", ctx.scope), {}, ctx);
+    await callTool(specByName("get_message", ctx.scope), { message_id: "m1" }, ctx);
+    assert.ok(fake.requests.length >= 2);
+    for (const r of fake.requests) {
+        assert.ok(!r.url.includes(KEY), `key leaked into URL: ${r.url}`);
+        assert.equal(r.headers["authorization"], `Bearer ${KEY}`);
+        // No other header carries it.
+        for (const [k, v] of Object.entries(r.headers)) {
+            if (k !== "authorization")
+                assert.ok(!v.includes(KEY), `key leaked into header ${k}`);
+        }
+    }
+});
+test("a transport error message never contains the key or the URL", async () => {
+    const fetchImpl = async () => {
+        throw new TypeError("fetch failed: connect ECONNREFUSED https://core.test/v0?api_key=" + KEY);
+    };
+    const client = new CoreClient({ apiKey: KEY, baseUrl: "https://core.test/v0", fetchImpl });
+    await assert.rejects(() => client.get("/inboxes"), (e) => {
+        assert.ok(e instanceof CoreError);
+        assert.ok(!e.message.includes(KEY), "key must not appear in the error");
+        assert.ok(!e.message.includes("core.test"), "URL must not appear in the error");
+        assert.equal(e.code, "network");
+        return true;
+    });
+});
+test("auth failure does NOT reveal whether an inbox exists (403 and 404 collapse to not_found)", async () => {
+    const forbidden = new FakeCore()
+        .on("GET", (u) => u.pathname.endsWith("/auth/me"), authMePod())
+        .on("GET", (u) => /\/inboxes\/inb_q$/.test(u.pathname), { status: 403, json: { code: "forbidden" } });
+    const missing = new FakeCore()
+        .on("GET", (u) => u.pathname.endsWith("/auth/me"), authMePod())
+        .on("GET", (u) => /\/inboxes\/inb_q$/.test(u.pathname), { status: 404, json: { code: "not_found" } });
+    const errOf = async (fake) => {
+        const ctx = await ctxFor(fake);
+        try {
+            await callTool(specByName("get_thread", ctx.scope), { inbox_id: "inb_q", thread_id: "t1" }, ctx);
+            return "no-error";
+        }
+        catch (e) {
+            return e.code ?? "unknown";
+        }
+    };
+    // A key denied the inbox (403) and a key facing a missing inbox (404) get the IDENTICAL answer, so
+    // the model can never use the error to enumerate which inboxes exist.
+    assert.equal(await errOf(forbidden), "not_found");
+    assert.equal(await errOf(missing), "not_found");
+});
+test("end-to-end over MCP: list tools and call one through the real server adapter", async () => {
+    const fake = new FakeCore()
+        .on("GET", (u) => u.pathname.endsWith("/auth/me"), authMeInbox("inb_e2e"))
+        .on("GET", (u) => /\/inboxes\/inb_e2e\/threads$/.test(u.pathname), {
+        json: { threads: [{ tid: "thr_1" }] },
+    });
+    const core = new CoreClient({ apiKey: KEY, baseUrl: "https://core.test/v0", fetchImpl: fake.fetch });
+    const server = await buildServer(core);
+    const [clientT, serverT] = InMemoryTransport.createLinkedPair();
+    const client = new Client({ name: "test-client", version: "0" });
+    await Promise.all([server.connect(serverT), client.connect(clientT)]);
+    const listed = await client.listTools();
+    assert.ok(listed.tools.some((t) => t.name === "list_threads"));
+    // Single-inbox key: no tool exposes inbox_id.
+    for (const t of listed.tools) {
+        const props = (t.inputSchema?.properties ?? {});
+        assert.ok(!("inbox_id" in props));
+    }
+    const res = await client.callTool({ name: "list_threads", arguments: {} });
+    assert.equal(res.isError ?? false, false);
+    const content = res.content;
+    const payload = JSON.parse(content[0].text);
+    assert.equal(payload.threads[0].tid, "thr_1");
+    await client.close();
+    await server.close();
+});
+test("end-to-end: a core error surfaces as an isError tool result with a stable code (no leak)", async () => {
+    const fake = new FakeCore()
+        .on("GET", (u) => u.pathname.endsWith("/auth/me"), authMeInbox("inb_e2e"))
+        .on("GET", () => true, { status: 404, json: { code: "not_found" } });
+    const core = new CoreClient({ apiKey: KEY, baseUrl: "https://core.test/v0", fetchImpl: fake.fetch });
+    const server = await buildServer(core);
+    const [clientT, serverT] = InMemoryTransport.createLinkedPair();
+    const client = new Client({ name: "test-client", version: "0" });
+    await Promise.all([server.connect(serverT), client.connect(clientT)]);
+    const res = await client.callTool({ name: "get_message", arguments: { message_id: "m_x" } });
+    assert.equal(res.isError, true);
+    const content = res.content;
+    assert.equal(content[0].text, "error: not_found");
+    assert.ok(!content[0].text.includes(KEY));
+    await client.close();
+    await server.close();
+});

package/dist/server.js

@@ -0,0 +1,94 @@
+// The MCP server — a thin stdio adapter over the tool catalog. It registers the tools the scope
+// allows, dispatches CallTool to the matching handler, and translates failures into a tool error the
+// model can read. It never reimplements core logic; every call is one REST request.
+//
+// Log hygiene (AGENTS.md §5, audited by pombus-sec): the stdio stream IS the MCP channel, so nothing
+// but protocol frames may touch stdout. Diagnostics go to stderr, and NOTHING we print ever includes
+// the API key — the key lives only in the client's Authorization header, never in an argument, a URL,
+// or an error message surfaced here.
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { CoreClient, CoreError, readApiKey } from "./client.js";
+import { ScopeBinding, ScopeError } from "./scope.js";
+import { specByName, toolDescriptors, callTool, ToolArgError } from "./tools.js";
+const SERVER_NAME = "pombus";
+const SERVER_VERSION = "0.1.0";
+/** Build and connect the MCP server over stdio. Fails fast (before connecting) when the key is absent,
+ *  so a misconfigured client sees a clear stderr line instead of a server that answers every tool with
+ *  an auth error. */
+export async function runMcpServer() {
+    const { humanMessage, humanCodeForBoot } = await import("./i18n.js");
+    const apiKey = readApiKey();
+    if (!apiKey) {
+        // Human-facing, localized, to stderr — never stdout (would corrupt the MCP stream).
+        process.stderr.write(humanMessage("no_api_key") + "\n");
+        process.exitCode = 1;
+        return;
+    }
+    const client = new CoreClient({ apiKey });
+    let server;
+    try {
+        // buildServer resolves the key's scope (one /v0/auth/me call). A human runs the server, so a boot
+        // failure here is human-facing: localize the REAL cause — a rejected key (auth_failed) or an
+        // unreachable core (network) — instead of a generic line. CoreError already carries only a safe,
+        // key-free code.
+        server = await buildServer(client);
+    }
+    catch (e) {
+        const code = e instanceof CoreError ? humanCodeForBoot(e.code) : "unknown";
+        process.stderr.write(humanMessage(code) + "\n");
+        process.exitCode = 1;
+        return;
+    }
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+/** Build the Server bound to a given core client. Exposed so tests drive it with a fake core and
+ *  without a real stdio transport. Resolves the key's scope up front (one /v0/auth/me call) so the
+ *  tool schemas can omit inbox_id for a single-inbox key. */
+export async function buildServer(client) {
+    const scope = await ScopeBinding.resolve(client);
+    const server = new Server({ name: SERVER_NAME, version: SERVER_VERSION }, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: toolDescriptors(scope),
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (req) => {
+        // specByName honours the gate: a tool the key may not use is "unknown" here, exactly as it is
+        // absent from ListTools — the model can neither see nor call a tool outside its permissions.
+        const spec = specByName(req.params.name, scope);
+        if (!spec)
+            return toolError(`unknown tool: ${req.params.name}`);
+        const args = (req.params.arguments ?? {});
+        try {
+            const value = await callTool(spec, args, { client, scope });
+            return { content: [{ type: "text", text: toText(value) }] };
+        }
+        catch (e) {
+            return toolError(modelError(e));
+        }
+    });
+    return server;
+}
+/** Serialize a handler result for the model. undefined (e.g. a 204) becomes an explicit ok marker. */
+function toText(value) {
+    if (value === undefined)
+        return JSON.stringify({ ok: true });
+    return JSON.stringify(value);
+}
+/** A CallTool result flagged as an error (isError), carrying model-facing en-US text. */
+function toolError(text) {
+    return { isError: true, content: [{ type: "text", text }] };
+}
+/** Map a thrown error to a stable, locale-free string for the model. Never leaks the key or a URL:
+ *  CoreError/ScopeError/ToolArgError already carry only a safe code; anything else collapses to a
+ *  generic message so an unexpected throw can't smuggle a secret into the tool output. */
+function modelError(e) {
+    if (e instanceof CoreError)
+        return `error: ${e.code}`;
+    if (e instanceof ScopeError)
+        return `error: ${e.code}`;
+    if (e instanceof ToolArgError)
+        return `error: ${e.code}`;
+    return "error: internal";
+}