pombus 0.1.3 → 0.1.5

package/README.md

@@ -28,9 +28,14 @@ uses TOML, so `init` prints the block for you to paste).
 ```sh
 npx pombus init --print                 # print the config block, write nothing
 npx pombus init --client cursor         # target one client
-npx pombus init --create-inbox          # create an inbox during setup
+npx pombus init --create-inbox --domain acme.com   # create an inbox on YOUR verified domain
 ```
 
+`--create-inbox` needs `--domain`: an extra inbox can only be created on a domain
+you own and have verified in Pombus. (Your account's `@pombus.com` inbox is the one
+from signup; an API key cannot create more of those —
+`403 platform_inbox_not_allowed`.)
+
 ## Commands
 
 | Command         | What it does                                                        |

package/dist/bin.js

@@ -23,6 +23,7 @@ export function parseArgs(argv) {
     const out = {
         cmd: undefined,
         createInbox: false,
+        domain: undefined,
         print: false,
         help: false,
         locale: undefined,
@@ -50,6 +51,14 @@ export function parseArgs(argv) {
             if (v)
                 out.client = v;
         }
+        else if (a === "--domain" || a.startsWith("--domain=")) {
+            // `--domain --print` must not swallow the next flag as the value: a value starting with "-" is
+            // left for the loop (domain stays unset -> init explains --domain is needed).
+            const next = argv[i + 1];
+            const v = a.includes("=") ? a.slice(a.indexOf("=") + 1) : next && !next.startsWith("-") ? argv[++i] : "";
+            if (v)
+                out.domain = v;
+        }
     }
     return out;
 }
@@ -62,7 +71,8 @@ const USAGE = [
     "  doctor    check your API key and report its scope",
     "",
     "init options:",
-    "  --create-inbox     create a new inbox and bind the config to it",
+    "  --create-inbox     create a new inbox and bind the config to it (needs --domain)",
+    "  --domain <name>    your verified domain the new inbox is created on",
     "  --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",
@@ -82,6 +92,7 @@ async function main() {
         await runInit({
             apiKey: readApiKey() ?? undefined,
             createInbox: args.createInbox,
+            ...(args.domain !== undefined ? { domain: args.domain } : {}),
             print: args.print,
             ...(args.client !== undefined ? { client: args.client } : {}),
             ...(args.locale !== undefined ? { locale: args.locale } : {}),

package/dist/client.js

@@ -16,10 +16,16 @@ const DEFAULT_BASE = "https://mail-api.pombus.com/v0";
  *  would distinguish "forbidden" from "not found". */
 export class CoreError extends Error {
     code;
-    constructor(code, message) {
+    /** The core's OWN stable code behind a collapsed 401/403/404 (e.g. `platform_inbox_not_allowed`).
+     *  For the HUMAN installer only (`pombus init`), which runs with the user's own key and must say WHY;
+     *  never surfaced to the model — server.ts modelError() prints `code` alone, so the anti-enumeration
+     *  collapse above stands for every tool call. */
+    coreCode;
+    constructor(code, message, coreCode) {
         super(message);
         this.name = "CoreError";
         this.code = code;
+        this.coreCode = coreCode;
     }
 }
 /** Resolve the core base URL from an explicit option or the environment, else the production default.
@@ -41,8 +47,11 @@ export class CoreClient {
     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;
+        // The option exists only so tests can inject a fake core. The default must be BOUND to globalThis:
+        // the workerd (Cloudflare Workers) native fetch requires `this === globalThis`, so a detached
+        // reference throws `TypeError: Illegal invocation` in production. Node's undici tolerates a
+        // detached fetch, which is why the omission passed every node:test — see client.test.ts.
+        this.fetchImpl = opts.fetchImpl ?? globalThis.fetch.bind(globalThis);
     }
     /** 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). */
@@ -96,7 +105,7 @@ export class CoreClient {
         }
         // 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");
+            throw new CoreError("not_found", "resource not found", await safeCode(res));
         }
         // 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

package/dist/http/do-class.js

@@ -0,0 +1,77 @@
+// R2c — the Durable Object shell. This is the ONE place that imports cloudflare:workers, so it is the
+// ONE file the `node --test` runner must never load: `cloudflare:workers` throws
+// ERR_UNSUPPORTED_ESM_URL_SCHEME in Node. It is kept off the test import graph (only do-entry.ts, the
+// wrangler main, pulls it) and off `tsc`'s unresolved-module error by the ambient declaration below.
+//
+// Why this exists: Cloudflare Workers do NOT pin the same isolate across the three hops of the OAuth
+// flow, so an in-isolate OAuthStore loses the authorization code between POST /authorize and POST
+// /token → `invalid_grant` in production. ONE Durable Object instance fixes it: every isolate reaches
+// the same object (DurableObjectStore resolves it by a fixed name), and the DO's input gate serializes
+// calls so single-use take-and-delete stays atomic.
+//
+// MEMORY, not ctx.storage (deliberate, do not "fix"): the store holds each token-set's minted childKeys
+// (one per authorized org, inside every OrgEntry) and the ownerHash that gates attachOrg. Persisting
+// them to ctx.storage would put those secrets on disk at rest — a worse security posture. In memory they
+// never touch disk. The only cost is benign: if the DO is evicted after a long idle, live tokens vanish
+// and the agent re-authorizes (a UX degradation, never a security failure). So this class does NOT touch
+// ctx.storage at all.
+//
+// This shell carries NO logic and logs NOTHING: every method is a 1:1 pass-through to the in-memory
+// OAuthStore it wraps. All behaviour under test (single-use, expiry, caps, PKCE, scope, rate-limit)
+// lives in OAuthStore (oauth.ts), proven in node. The shell is workerd-specific and verified by reading
+// plus the founder's `wrangler dev` smoke — it has no automated test, by design (no Miniflare is added;
+// the package's stack is fixed, AGENTS.md §4).
+// The runtime base class comes from `cloudflare:workers`, declared minimally in
+// cloudflare-workers.d.ts (the npx package has no @cloudflare/workers-types; see that file).
+import { DurableObject } from "cloudflare:workers";
+import { OAuthStore, } from "./oauth.js";
+/** The singleton OAuth store as a Durable Object. Its public methods ARE the RPC surface the Worker's
+ *  DurableObjectStore calls on the stub; each forwards straight to the wrapped in-memory OAuthStore. */
+export class OAuthStoreDO extends DurableObject {
+    store = new OAuthStore();
+    putRequest(id, r) {
+        return this.store.putRequest(id, r);
+    }
+    takeRequest(id) {
+        return this.store.takeRequest(id);
+    }
+    putCode(code, c) {
+        return this.store.putCode(code, c);
+    }
+    takeCode(code) {
+        return this.store.takeCode(code);
+    }
+    tokenRoom() {
+        return this.store.tokenRoom();
+    }
+    putToken(token, t) {
+        return this.store.putToken(token, t);
+    }
+    getToken(token) {
+        return this.store.getToken(token);
+    }
+    attachOrg(token, orgId, entry, ownerHash) {
+        return this.store.attachOrg(token, orgId, entry, ownerHash);
+    }
+    setActiveOrg(token, orgId) {
+        return this.store.setActiveOrg(token, orgId);
+    }
+    getActiveChild(token) {
+        return this.store.getActiveChild(token);
+    }
+    putLink(linkToken, accessToken) {
+        return this.store.putLink(linkToken, accessToken);
+    }
+    takeLink(linkToken) {
+        return this.store.takeLink(linkToken);
+    }
+    putClient(clientId, redirectUris) {
+        return this.store.putClient(clientId, redirectUris);
+    }
+    getClient(clientId) {
+        return this.store.getClient(clientId);
+    }
+    reset() {
+        return this.store.reset();
+    }
+}

package/dist/http/do-entry.js

@@ -0,0 +1,10 @@
+// R2c — the wrangler `main`. It exists so the Durable Object class is a named export of the deployed
+// entry (wrangler requires the DO class to be exported from main) WITHOUT putting the toxic
+// cloudflare:workers import on the test path: the tests import ./worker.js directly and never touch this
+// file, so `node --test` never loads do-class.js. workerd loads this module and sees both the fetch
+// handler and OAuthStoreDO.
+//
+// Keep this file a pure re-export — no logic. The worker's fetch handler stays in worker.ts (fully
+// tested in node); the DO shell stays in do-class.ts (workerd-only).
+export { default } from "./worker.js";
+export { OAuthStoreDO } from "./do-class.js";

package/dist/http/oauth-i18n.js

@@ -0,0 +1,69 @@
+// OAuth i18n — the locale machinery + the root-page copy, in the three mandated locales (AGENTS.md §2):
+// en-US, pt-BR, es-419. Keyed by a stable, locale-free id; nothing visible is hardcoded.
+//
+// R3 note: the consent screen moved to the WEBMAIL (the Worker delegates the human decision), so the
+// consent dictionary that used to live here is gone. What remains is used by the Worker itself: the
+// locale negotiation (pickLocale / parseAcceptLanguage) and the friendly root page (ROOT_TEXT), both
+// consumed by root.ts and worker.ts.
+export const OAUTH_LOCALES = ["en-US", "pt-BR", "es-419"];
+/** Match a single raw tag ("pt", "pt-BR", "es-419", "en-GB"...) to one of the three supported locales
+ *  by language prefix (region only matters for Spanish, which is always es-419). Returns null when it
+ *  matches none — so a garbage ?hl= simply doesn't resolve and the caller falls through to the next
+ *  source (the lixo is NEVER reflected). This is the one place the prefix rule lives. */
+function matchLocale(raw) {
+    const v = (raw ?? "").trim().toLowerCase();
+    if (v.startsWith("pt"))
+        return "pt-BR";
+    if (v.startsWith("es"))
+        return "es-419";
+    if (v.startsWith("en"))
+        return "en-US";
+    return null;
+}
+/** Pick the screen locale by precedence: scan the sources in order and take the FIRST that resolves to
+ *  a supported locale; en-US is the last resort. The caller passes, in order of strength:
+ *    [ ?hl= , Accept-Language , ?locale= ]
+ *  — the human's explicit click, then their browser default, then the agent's hint. A source that
+ *  matches nothing is skipped, so a garbage value never wins and never surfaces. */
+export function pickLocale(sources) {
+    for (const s of sources) {
+        const m = matchLocale(s);
+        if (m)
+            return m;
+    }
+    return "en-US";
+}
+/** Extract the highest-priority language tag from an Accept-Language header — just the first tag,
+ *  before the first comma or ';q='. ponytail: we don't parse the full q-value list; the browser lists
+ *  its preferred language first, and if that first tag matches none of our three, pickLocale falls
+ *  through to the next source anyway. Returns null for an empty/absent header. */
+export function parseAcceptLanguage(header) {
+    const first = (header ?? "").split(",")[0]?.split(";")[0]?.trim();
+    return first ? first : null;
+}
+/** The friendly root page (R2d) — the page a HUMAN sees if they open the MCP endpoint in a browser
+ *  (a real MCP client never hits it: it GETs with Accept text/html and no Bearer). Three locales like
+ *  everything else; keyed by a stable id. Content-free of any secret — it only names the product and
+ *  how to use the endpoint. */
+export const ROOT_TEXT = {
+    root_title: {
+        "en-US": "Pombus — MCP endpoint",
+        "pt-BR": "Pombus — endpoint MCP",
+        "es-419": "Pombus — endpoint MCP",
+    },
+    root_heading: {
+        "en-US": "This is the Pombus MCP endpoint",
+        "pt-BR": "Este é o endpoint MCP do Pombus",
+        "es-419": "Este es el endpoint MCP de Pombus",
+    },
+    root_body: {
+        "en-US": "Add this URL to your AI client (Claude and others) as a remote MCP connector. It is an API surface, not a website.",
+        "pt-BR": "Adicione esta URL ao seu cliente de IA (Claude e outros) como conector MCP remoto. É uma superfície de API, não um site.",
+        "es-419": "Agrega esta URL a tu cliente de IA (Claude y otros) como conector MCP remoto. Es una superficie de API, no un sitio web.",
+    },
+    root_site: {
+        "en-US": "Learn more at pombus.com",
+        "pt-BR": "Saiba mais em pombus.com",
+        "es-419": "Más información en pombus.com",
+    },
+};