pombus 0.0.0-stage → 0.1.0

package/dist/bin.js

@@ -0,0 +1,157 @@
+#!/usr/bin/env node
+// The `pombus` CLI entrypoint. Three subcommands:
+//   - `pombus mcp`    — the stdio MCP server a client invokes (F4).
+//   - `pombus init`   — the installer: read key, (opt) create inbox, write MCP config (F5).
+//   - `pombus doctor` — validate the key and report its scope (F5).
+// Flag parsing is a tiny manual argv walk (ponytail: no commander/yargs). `--help` prints usage.
+//
+// parseArgs is exported and pure; main() runs ONLY when this file is the process entrypoint (guarded
+// at the bottom), so a test can import parseArgs without the CLI firing.
+import { createInterface } from "node:readline";
+import { argv } from "node:process";
+import { fileURLToPath } from "node:url";
+import { CoreError, readApiKey } from "./client.js";
+import { runMcpServer } from "./server.js";
+import { runInit, InitAbort } from "./init.js";
+import { runDoctor } from "./doctor.js";
+import { humanCodeForBoot, humanMessage, resolveLocale } from "./i18n.js";
+const VALID_LOCALES = ["en-US", "pt-BR", "es-419"];
+/** Parse argv (the slice AFTER `node bin.js`). Unknown flags are ignored rather than fatal — a thin
+ *  installer should not reject a future client's extra flag. `--locale`/`--client` take the next arg
+ *  or an `=value`. An invalid locale is dropped (falls back to env detection). */
+export function parseArgs(argv) {
+    const out = {
+        cmd: undefined,
+        createInbox: false,
+        print: false,
+        help: false,
+        locale: undefined,
+        client: undefined,
+    };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (!out.cmd && !a.startsWith("-")) {
+            out.cmd = a;
+            continue;
+        }
+        if (a === "--create-inbox")
+            out.createInbox = true;
+        else if (a === "--print" || a === "--dry-run")
+            out.print = true;
+        else if (a === "--help" || a === "-h")
+            out.help = true;
+        else if (a === "--locale" || a.startsWith("--locale=")) {
+            const v = a.includes("=") ? a.slice(a.indexOf("=") + 1) : argv[++i];
+            if (v && VALID_LOCALES.includes(v))
+                out.locale = v;
+        }
+        else if (a === "--client" || a.startsWith("--client=")) {
+            const v = a.includes("=") ? a.slice(a.indexOf("=") + 1) : argv[++i];
+            if (v)
+                out.client = v;
+        }
+    }
+    return out;
+}
+const USAGE = [
+    "usage: pombus <command> [options]",
+    "",
+    "commands:",
+    "  mcp       run the stdio MCP server (invoked by your client)",
+    "  init      write the Pombus MCP config into your client",
+    "  doctor    check your API key and report its scope",
+    "",
+    "init options:",
+    "  --create-inbox     create a new inbox and bind the config to it",
+    "  --print            print the config block instead of writing it",
+    "  --client <id>      target one client (claude-code|cursor|gemini|codex)",
+    "  --locale <loc>     en-US | pt-BR | es-419",
+].join("\n");
+async function main() {
+    const args = parseArgs(process.argv.slice(2));
+    if (args.help || !args.cmd) {
+        process.stdout.write(USAGE + "\n");
+        process.exitCode = args.cmd ? 0 : 2;
+        return;
+    }
+    if (args.cmd === "mcp") {
+        await runMcpServer();
+        return;
+    }
+    if (args.cmd === "init") {
+        await runInit({
+            apiKey: readApiKey() ?? undefined,
+            createInbox: args.createInbox,
+            print: args.print,
+            ...(args.client !== undefined ? { client: args.client } : {}),
+            ...(args.locale !== undefined ? { locale: args.locale } : {}),
+            home: undefined, // defaults to os.homedir() inside clients.ts
+            promptKey: promptKeyHidden,
+        });
+        return;
+    }
+    if (args.cmd === "doctor") {
+        const res = await runDoctor({
+            apiKey: readApiKey() ?? undefined,
+            ...(args.locale !== undefined ? { locale: args.locale } : {}),
+        });
+        process.exitCode = res.ok ? 0 : 1;
+        return;
+    }
+    process.stderr.write(`unknown command: ${args.cmd}\n` + USAGE + "\n");
+    process.exitCode = 2;
+}
+/** Read a key from the TTY without echoing it. readline writes the prompt; we mute the output stream
+ *  while the user types so the secret never lands in the terminal scrollback. The prompt text itself
+ *  is written before muting so the user still sees it. Falls back to a normal (echoing) read when
+ *  stdin is not a TTY (piped input) — there is nothing to hide there. */
+async function promptKeyHidden() {
+    const locale = resolveLocale();
+    const prompt = humanMessage("init_prompt_key", locale);
+    const input = process.stdin;
+    const output = process.stdout;
+    const rl = createInterface({ input, output, terminal: true });
+    // Mute: replace the interface's write of typed characters with nothing, but keep the initial prompt.
+    output.write(prompt);
+    const rlAny = rl;
+    const originalWrite = rlAny._writeToOutput;
+    rlAny._writeToOutput = () => {
+        /* swallow keystroke echo */
+    };
+    try {
+        const answer = await new Promise((res) => rl.question("", res));
+        output.write("\n");
+        return answer;
+    }
+    finally {
+        if (originalWrite)
+            rlAny._writeToOutput = originalWrite;
+        rl.close();
+    }
+}
+/** True when this module is the process entrypoint (run as `node bin.js` / the `pombus` bin), as
+ *  opposed to being imported by a test. Compares the resolved module path to argv[1]. */
+function isEntrypoint() {
+    const invoked = argv[1];
+    if (!invoked)
+        return false;
+    try {
+        return fileURLToPath(import.meta.url) === invoked;
+    }
+    catch {
+        return false;
+    }
+}
+if (isEntrypoint()) {
+    main().catch((e) => {
+        // Last-resort guard: never print the key or a stack that could carry one. Localize the REAL cause
+        // when it is a CoreError (a human ran us); a clean InitAbort already printed its own line.
+        if (e instanceof InitAbort) {
+            process.exitCode = 1;
+            return;
+        }
+        const code = e instanceof CoreError ? humanCodeForBoot(e.code) : "unknown";
+        process.stderr.write(humanMessage(code) + "\n");
+        process.exitCode = 1;
+    });
+}

package/dist/bin.test.js

@@ -0,0 +1,33 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { parseArgs } from "./bin.js";
+test("parseArgs: command + flags", () => {
+    const a = parseArgs(["init", "--create-inbox", "--print"]);
+    assert.equal(a.cmd, "init");
+    assert.equal(a.createInbox, true);
+    assert.equal(a.print, true);
+});
+test("parseArgs: --dry-run is an alias for --print", () => {
+    assert.equal(parseArgs(["init", "--dry-run"]).print, true);
+});
+test("parseArgs: --locale with a space or an = ", () => {
+    assert.equal(parseArgs(["init", "--locale", "pt-BR"]).locale, "pt-BR");
+    assert.equal(parseArgs(["init", "--locale=es-419"]).locale, "es-419");
+});
+test("parseArgs: an invalid locale is dropped (falls back to env detection)", () => {
+    assert.equal(parseArgs(["init", "--locale", "klingon"]).locale, undefined);
+});
+test("parseArgs: --client selects one target", () => {
+    assert.equal(parseArgs(["init", "--client", "cursor"]).client, "cursor");
+    assert.equal(parseArgs(["init", "--client=codex"]).client, "codex");
+});
+test("parseArgs: --help, and no command", () => {
+    assert.equal(parseArgs(["--help"]).help, true);
+    assert.equal(parseArgs(["doctor", "-h"]).help, true);
+    assert.equal(parseArgs([]).cmd, undefined);
+});
+test("parseArgs: an unknown flag is ignored, not fatal", () => {
+    const a = parseArgs(["init", "--some-future-flag", "--print"]);
+    assert.equal(a.cmd, "init");
+    assert.equal(a.print, true);
+});

package/dist/client.js

@@ -0,0 +1,142 @@
+// HTTP client for the Pombus REST core. The MCP server is a pure client: it never opens SQLite,
+// never parses MIME. It holds the API key, signs every request with a Bearer header, and translates
+// the core's HTTP contract into a shape the tool layer can hand back to the model.
+//
+// Security invariants enforced here (audited by pombus-sec):
+//   - the key lives ONLY in the Authorization header; it is never placed in a URL, an argv, a log
+//     line, or a thrown error message.
+//   - an auth/permission failure (401/403) and a missing resource (404) collapse to ONE opaque
+//     error for the model (`not_found`), so the server never confirms an inbox exists to a caller
+//     that cannot reach it — the same anti-enumeration rule the core applies.
+//   - network/transport errors report the failure TYPE only, never the request URL (which carries
+//     query values) or the key.
+const DEFAULT_BASE = "https://mail-api.pombus.com/v0";
+/** A failure the tool layer surfaces to the model. `code` is stable and locale-free; it maps to an
+ *  i18n message only when a human sees it. Never carries the key, the URL, or a server detail that
+ *  would distinguish "forbidden" from "not found". */
+export class CoreError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "CoreError";
+        this.code = code;
+    }
+}
+/** Resolve the core base URL from an explicit option or the environment, else the production default.
+ *  Trailing slash trimmed so path joins never double up. */
+export function resolveBaseUrl(explicit) {
+    const raw = (explicit ?? process.env["POMBUS_API_BASE"] ?? DEFAULT_BASE).trim();
+    return raw.replace(/\/+$/, "");
+}
+/** Read the API key from the environment. Returns null when absent — the caller decides how to fail
+ *  (the server refuses to start without it). The value is never logged by this module. */
+export function readApiKey() {
+    const k = (process.env["POMBUS_API_KEY"] ?? "").trim();
+    return k.length > 0 ? k : null;
+}
+export class CoreClient {
+    apiKey;
+    baseUrl;
+    fetchImpl;
+    constructor(opts) {
+        this.apiKey = opts.apiKey;
+        this.baseUrl = resolveBaseUrl(opts.baseUrl);
+        // Node >=20 ships a global fetch; the option exists only so tests can inject a fake core.
+        this.fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+    }
+    /** Build an absolute URL from a path and query params. Values are URL-encoded. The API key is
+     *  NEVER a query param — it only ever rides in the Authorization header (keyHygiene). */
+    url(path, query) {
+        const u = new URL(this.baseUrl + path);
+        if (query) {
+            for (const [k, v] of Object.entries(query)) {
+                if (v !== undefined && v !== "")
+                    u.searchParams.set(k, String(v));
+            }
+        }
+        return u.toString();
+    }
+    /** One request. On a non-2xx the core body is parsed for its stable `code`; 401/403/404 all map to
+     *  `not_found` so the model can never tell "you may not" from "it does not exist". Other statuses
+     *  keep their code for diagnostics but still never leak the key or the URL. */
+    async request(method, path, opts = {}) {
+        const url = this.url(path, opts.query);
+        const init = {
+            method,
+            headers: {
+                authorization: `Bearer ${this.apiKey}`,
+                accept: "application/json",
+                ...(opts.body !== undefined ? { "content-type": "application/json" } : {}),
+            },
+        };
+        if (opts.body !== undefined)
+            init.body = JSON.stringify(opts.body);
+        // A corporate proxy is honoured by Node's own undici dispatcher (HTTPS_PROXY / NODE_USE_ENV_PROXY);
+        // we do not re-implement it.
+        let res;
+        try {
+            res = await this.fetchImpl(url, init);
+        }
+        catch (e) {
+            // Transport failure: report the TYPE, never the URL (it carries query values) or the key.
+            throw new CoreError("network", `request failed: ${errName(e)}`);
+        }
+        if (res.ok) {
+            if (res.status === 204)
+                return undefined;
+            const text = await res.text();
+            if (!text)
+                return undefined;
+            try {
+                return JSON.parse(text);
+            }
+            catch {
+                throw new CoreError("bad_response", "core returned a non-JSON body");
+            }
+        }
+        // Anti-enumeration: do NOT distinguish "forbidden" from "not found" to the model.
+        if (res.status === 401 || res.status === 403 || res.status === 404) {
+            throw new CoreError("not_found", "resource not found");
+        }
+        // Other errors: a stable code from the core body when present, else the status. The message is
+        // generic; the body is read but only its `code`/`detail` string is used, never echoed verbatim
+        // if it could carry caller input.
+        const code = await safeCode(res);
+        throw new CoreError(code, `core error (${res.status})`);
+    }
+    get(path, query) {
+        return this.request("GET", path, { query });
+    }
+    post(path, body) {
+        return this.request("POST", path, { body });
+    }
+    patch(path, body) {
+        return this.request("PATCH", path, { body });
+    }
+    delete(path, body) {
+        return this.request("DELETE", path, { body });
+    }
+}
+/** The error constructor name only — never the message, which could carry a URL or system path. */
+function errName(e) {
+    if (e && typeof e === "object" && "name" in e && typeof e.name === "string") {
+        return e.name;
+    }
+    return "Error";
+}
+/** Extract a stable short code from a core error body without echoing attacker-influenced text. */
+async function safeCode(res) {
+    try {
+        const text = await res.text();
+        if (!text)
+            return "core_error";
+        const body = JSON.parse(text);
+        const raw = typeof body.code === "string" ? body.code : typeof body.detail === "string" ? body.detail : "";
+        // Only accept a conservative identifier shape; anything else collapses to a generic code so a
+        // reflected body can't smuggle content into our error.
+        return /^[a-z][a-z0-9_]{0,39}$/.test(raw) ? raw : "core_error";
+    }
+    catch {
+        return "core_error";
+    }
+}

package/dist/clients.js

@@ -0,0 +1,187 @@
+// Client config — where `pombus init` writes (or prints) the MCP server block, and how it writes it
+// safely. The MCP block shape is the Resend/Postmark standard every client understands:
+//   { "command": "npx", "args": ["-y", "pombus", "mcp"], "env": { "POMBUS_API_KEY": "<key>" } }
+//
+// SECURITY (audited by pombus-sec, the write is the sharp edge of this slice):
+//   - MERGE, never clobber: the existing config is parsed and ONLY the `pombus` entry under
+//     `mcpServers` is added/updated; every other key the user has is preserved byte-for-byte on the
+//     parts we don't touch.
+//   - ATOMIC: write to a temp file in the SAME directory, fsync, then rename over the target. A crash
+//     mid-write never leaves a truncated config (rename is atomic on the same filesystem).
+//   - 0600: the file that carries the key is chmod'd to owner-only where the OS supports it (POSIX);
+//     on Windows chmod is a no-op and NTFS inherits the user profile ACL, so we do not pretend.
+//   - NEVER the project repo: only a path under the user's HOME. We refuse any target we cannot place
+//     inside os.homedir(), falling back to --print instead of guessing.
+//   - PRINT fallback: a client whose format we will not write by hand (Codex: TOML, which we will not
+//     serialize without a parser — ponytail forbids the dep, and a half-escaped TOML path is a known
+//     way to wedge the client) is PRINT-only. So is any client whose config dir we cannot resolve.
+import { mkdirSync, readFileSync, writeFileSync, renameSync, chmodSync, rmSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, dirname, resolve, sep } from "node:path";
+/** Resolve the table of known clients for a given HOME. Taking `home` as an argument (not calling
+ *  os.homedir() inline) is what lets a test point the whole table at a temp dir. */
+export function clientTargets(home = homedir()) {
+    return [
+        {
+            id: "claude-code",
+            label: "Claude Code",
+            mode: "json",
+            // code.claude.com/docs/en/mcp-quickstart: user-scoped servers live under the `mcpServers` key of
+            // ~/.claude.json (on Windows %USERPROFILE%\.claude.json). This file also holds other Claude Code
+            // state, which is exactly why we merge-only the mcpServers entry and never rewrite the rest.
+            path: join(home, ".claude.json"),
+            source: "code.claude.com/docs/en/mcp-quickstart",
+        },
+        {
+            id: "cursor",
+            label: "Cursor",
+            mode: "json",
+            // cursor.com/docs/mcp: global servers live in ~/.cursor/mcp.json under a top-level mcpServers.
+            path: join(home, ".cursor", "mcp.json"),
+            source: "cursor.com/docs/mcp",
+        },
+        {
+            id: "gemini",
+            label: "Gemini CLI",
+            mode: "json",
+            // geminicli.com/docs/reference/configuration: user settings at ~/.gemini/settings.json, MCP under
+            // the top-level mcpServers object (same shape as the others).
+            path: join(home, ".gemini", "settings.json"),
+            source: "geminicli.com/docs/reference/configuration",
+        },
+        {
+            id: "codex",
+            label: "Codex CLI",
+            mode: "print",
+            // community.openai.com: Codex reads ~/.codex/config.toml — a TOML file under an [mcp_servers.*]
+            // table. We do NOT write TOML (no parser without a dep; a mis-escaped Windows path is a known way
+            // to wedge the Codex app). So Codex is print-only: we show the block and let the user paste it.
+            path: join(home, ".codex", "config.toml"),
+            source: "community.openai.com/t/codex-config-toml-mcp",
+        },
+    ];
+}
+/** The MCP server block, exactly the Resend/Postmark shape. `key` may be a placeholder for --print. */
+export function serverBlock(key) {
+    return { command: "npx", args: ["-y", "pombus", "mcp"], env: { POMBUS_API_KEY: key } };
+}
+/** The pretty JSON a --print or a print-only client shows: the standard mcpServers wrapper with the
+ *  single pombus entry, so the user can paste it straight in. */
+export function printableJson(key) {
+    return JSON.stringify({ mcpServers: { pombus: serverBlock(key) } }, null, 2);
+}
+/** The TOML a Codex user pastes by hand (we print, never write it). Kept tiny and literal — this is
+ *  display text, not a serializer: a fixed three-line table with a JSON-encoded env map, which TOML
+ *  accepts as an inline table only in its own syntax, so we emit the explicit sub-table form. */
+export function printableCodexToml(key) {
+    // Backslashes in a Windows npx path are not an issue here: `npx` is a bare command, and the key is a
+    // conservative token. We still single-quote the key (TOML literal string) so no escape is needed.
+    return [
+        "[mcp_servers.pombus]",
+        'command = "npx"',
+        'args = ["-y", "pombus", "mcp"]',
+        "",
+        "[mcp_servers.pombus.env]",
+        `POMBUS_API_KEY = '${key}'`,
+    ].join("\n");
+}
+/** Raised when a write target is unsafe (outside HOME) or unreadable in a way we refuse to overwrite.
+ *  The caller turns it into a --print fallback, never a crash. */
+export class ConfigWriteError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.name = "ConfigWriteError";
+        this.code = code;
+    }
+}
+/** True when `target` is inside `home` (defense against a client table — or a tampered HOME env — that
+ *  would place a write in the project repo or elsewhere). Path-prefix check after resolving both. */
+export function isInsideHome(target, home) {
+    const h = resolve(home);
+    const t = resolve(target);
+    return t === h || t.startsWith(h + sep);
+}
+/** Merge the pombus server block into a client's JSON config and write it atomically with 0600.
+ *  - Reads the existing file (missing file => start from {}); a present-but-corrupt file is NOT
+ *    silently overwritten — we throw so the user's broken-but-real config is never destroyed.
+ *  - Sets config.mcpServers.pombus = block, leaving every other key untouched.
+ *  - Idempotent: running twice yields the same single entry (object key assignment, not append).
+ *  Returns nothing; throws ConfigWriteError on an unsafe/corrupt target. */
+export function writeJsonConfig(path, home, key) {
+    if (!isInsideHome(path, home))
+        throw new ConfigWriteError("outside_home");
+    let root;
+    let existing = null;
+    try {
+        existing = readFileSync(path, "utf8");
+    }
+    catch {
+        existing = null; // ENOENT (or unreadable): treat as a fresh file.
+    }
+    if (existing === null || existing.trim() === "") {
+        root = {};
+    }
+    else {
+        try {
+            const parsed = JSON.parse(existing);
+            if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+                throw new ConfigWriteError("corrupt_config");
+            }
+            root = parsed;
+        }
+        catch (e) {
+            if (e instanceof ConfigWriteError)
+                throw e;
+            // Real config that we cannot parse: refuse to clobber it. The caller falls back to --print.
+            throw new ConfigWriteError("corrupt_config");
+        }
+    }
+    const servers = asObject(root["mcpServers"]);
+    servers["pombus"] = serverBlock(key);
+    root["mcpServers"] = servers;
+    const body = JSON.stringify(root, null, 2) + "\n";
+    atomicWrite(path, body);
+}
+/** mcpServers must be an object; a non-object (someone set it to a string/array) is replaced with a
+ *  fresh object holding our entry rather than throwing — we never want to fail install on a weird but
+ *  non-fatal shape, and the rest of the file is preserved. */
+function asObject(v) {
+    return v !== null && typeof v === "object" && !Array.isArray(v)
+        ? v
+        : {};
+}
+/** Atomic file write with owner-only perms. Temp file in the SAME directory so rename stays on one
+ *  filesystem (atomic); 0600 on the temp BEFORE rename so the key never sits world-readable even for an
+ *  instant; chmod again after rename for the case where the target already existed with looser perms.
+ *  On Windows chmod is a no-op — NTFS inherits the profile ACL, so we do not fake a guarantee. */
+function atomicWrite(path, body) {
+    const dir = dirname(path);
+    mkdirSync(dir, { recursive: true });
+    const tmp = join(dir, `.pombus-${process.pid}-${Date.now()}.tmp`);
+    try {
+        writeFileSync(tmp, body, { mode: 0o600 });
+        try {
+            chmodSync(tmp, 0o600);
+        }
+        catch {
+            /* non-POSIX: best effort */
+        }
+        renameSync(tmp, path);
+        try {
+            chmodSync(path, 0o600);
+        }
+        catch {
+            /* non-POSIX: best effort */
+        }
+    }
+    catch (e) {
+        try {
+            rmSync(tmp, { force: true });
+        }
+        catch {
+            /* temp may not exist */
+        }
+        throw e;
+    }
+}

package/dist/doctor.js

@@ -0,0 +1,34 @@
+// `pombus doctor` — a cheap, read-only health check. Validates the key against GET /v0/auth/me
+// (via ScopeBinding.resolve) and tells the human, in i18n, whether the key works and at what scope, or
+// what is wrong (no key / invalid key / core unreachable). One request, no writes.
+import { CoreClient, CoreError } from "./client.js";
+import { ScopeBinding } from "./scope.js";
+import { humanCodeForBoot, humanMessage, resolveLocale } from "./i18n.js";
+export async function runDoctor(opts) {
+    const locale = opts.locale ?? resolveLocale();
+    const out = opts.out ?? ((l) => process.stderr.write(l + "\n"));
+    const key = (opts.apiKey ?? "").trim();
+    if (!key) {
+        out(humanMessage("no_api_key", locale));
+        return { ok: false, scope: null, code: "no_api_key" };
+    }
+    const client = new CoreClient({
+        apiKey: key,
+        ...(opts.baseUrl !== undefined ? { baseUrl: opts.baseUrl } : {}),
+        ...(opts.fetchImpl !== undefined ? { fetchImpl: opts.fetchImpl } : {}),
+    });
+    try {
+        const scope = await ScopeBinding.resolve(client);
+        // doctor_ok's message ends with "Scope: " — append the resolved scope type (a stable, non-secret
+        // identifier: inbox/domain/pod/organization). Not localized: it is an API constant, not prose.
+        out(humanMessage("doctor_ok", locale) + scope.scopeType);
+        return { ok: true, scope: scope.scopeType, code: "doctor_ok" };
+    }
+    catch (e) {
+        // Same bridge the server boot uses: a rejected key (not_found) => auth_failed, unreachable core =>
+        // network, anything else => unknown. Never leaks the key or a URL (CoreError carries only a code).
+        const code = e instanceof CoreError ? humanCodeForBoot(e.code) : "unknown";
+        out(humanMessage(code, locale));
+        return { ok: false, scope: null, code };
+    }
+}