pombus 0.1.3 → 0.1.5

package/dist/http/store-do.js

@@ -0,0 +1,64 @@
+// R2c — the client the Worker uses to reach the OAuth store, which in production lives inside ONE
+// Durable Object (do-class.ts OAuthStoreDO). Every isolate resolves the SAME instance by name, so the
+// three hops of the OAuth flow share state — the isolate-hop `invalid_grant` that blocked a deploy is
+// gone. This file holds NO cloudflare:workers import: it only needs the shape of a DurableObjectNamespace
+// and a stub, so it loads fine under `node --test` (the DO class itself, which does import the runtime,
+// is isolated in do-class.ts and never on the test path). Types are a tiny local declaration because the
+// npx package does not depend on @cloudflare/workers-types (its stack is fixed: tsc + node --test).
+// --- the Worker-side client -----------------------------------------------------------------------
+/** OAuthStoreLike backed by the singleton Durable Object. Each call is a one-line RPC delegation to the
+ *  stub; all the logic (single-use, expiry, caps, rate-limit) stays in the OAuthStore the DO wraps, so
+ *  nothing here needs a test of its own beyond the DO shell's by-reading review. */
+export class DurableObjectStore {
+    stub;
+    constructor(ns) {
+        // One fixed name → one DO instance for the whole Worker. Its input gate serializes every method, so
+        // the store's get-then-delete (takeCode/takeRequest) stays atomic across concurrent isolates.
+        this.stub = ns.get(ns.idFromName("oauth"));
+    }
+    putRequest(id, r) {
+        return this.stub.putRequest(id, r);
+    }
+    takeRequest(id) {
+        return this.stub.takeRequest(id);
+    }
+    putCode(code, c) {
+        return this.stub.putCode(code, c);
+    }
+    takeCode(code) {
+        return this.stub.takeCode(code);
+    }
+    tokenRoom() {
+        return this.stub.tokenRoom();
+    }
+    putToken(token, t) {
+        return this.stub.putToken(token, t);
+    }
+    getToken(token) {
+        return this.stub.getToken(token);
+    }
+    attachOrg(token, orgId, entry, ownerHash) {
+        return this.stub.attachOrg(token, orgId, entry, ownerHash);
+    }
+    setActiveOrg(token, orgId) {
+        return this.stub.setActiveOrg(token, orgId);
+    }
+    getActiveChild(token) {
+        return this.stub.getActiveChild(token);
+    }
+    putLink(linkToken, accessToken) {
+        return this.stub.putLink(linkToken, accessToken);
+    }
+    takeLink(linkToken) {
+        return this.stub.takeLink(linkToken);
+    }
+    putClient(clientId, redirectUris) {
+        return this.stub.putClient(clientId, redirectUris);
+    }
+    getClient(clientId) {
+        return this.stub.getClient(clientId);
+    }
+    reset() {
+        return this.stub.reset();
+    }
+}

package/dist/http/worker.js

@@ -0,0 +1,238 @@
+// R3 — the Pombus MCP server over Streamable-HTTP in a Worker, behind a DELEGATING OAuth 2.1 front.
+//
+// The human consent no longer runs here: the Worker 302s to the WEBMAIL (mail.pombus.com) and the
+// webmail — the origin that holds the human's session cookie and the toggle-based consent screen —
+// mints the scoped child key and hands it back via a single-use handoff the Worker redeems over the WEB
+// service binding. The agent never sees the child key; the Worker holds the opaque access token → child
+// key mapping (oauth.ts, a per-org token-set: Model D multi-org).
+//
+// Two credential paths (AgentMail parity):
+//   - `authorization: Bearer <access-token>`  → the OAuth/multi-org path: resolve the ACTIVE org's child
+//     key from the token-set, expose the org tools (list/select_organization).
+//   - `x-api-key: <pod-key>`                   → the key IS the credential (one org, stdio/Cursor/Windsurf
+//     style); org tools are NOT exposed. No token-set, no multi-org.
+//   - BOTH headers present                     → 400 invalid_request (ambiguous; refuse).
+//
+// OAuth surfaces (no Bearer required; they ISSUE/complete the Bearer): GET /authorize (302 to webmail),
+// GET /authorize/return (webmail bounce-back), POST /token (redeem). Everything else is the MCP endpoint
+// and is fail-closed: no valid credential → 401, the Server is never built, the core never touched.
+//
+// Transport: WebStandardStreamableHTTPServerTransport (SDK 1.32.1), stateless (one per request).
+//
+// Log hygiene (AGENTS.md §5): this worker logs NOTHING — no access token, child key, handoff, signature,
+// mailbox content or URL.
+import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+import { CoreClient } from "../client.js";
+import { buildServer } from "../server.js";
+import { store as defaultStore, validateAccessToken, handleAuthorizeGet, handleAuthorizeReturn, handleToken, handleRegister, DEFAULT_CLIENTS, } from "./oauth.js";
+import { DurableObjectStore } from "./store-do.js";
+import { renderRoot } from "./root.js";
+import { pickLocale, parseAcceptLanguage } from "./oauth-i18n.js";
+/** Resolve the OAuth store: the test seam first, else the bound Durable Object, else the module singleton. */
+function resolveStore(env) {
+    if (env.__store)
+        return env.__store;
+    if (env.OAUTH_STORE)
+        return new DurableObjectStore(env.OAUTH_STORE);
+    return defaultStore;
+}
+/** Resolve the WEB service binding: the test seam first, else the wrangler binding (may be undefined —
+ *  /token then fail-closes to 503). */
+function resolveWeb(env) {
+    return env.__web ?? env.WEB;
+}
+/** Resolve the Bearer ACCESS TOKEN on an MCP request to the child key of its ACTIVE org, or null to
+ *  refuse. The single fail-closed decision point for the Bearer path; the returned value is the minted
+ *  child key (NEVER log it). getActiveChild (oauth.ts) is the only source — org↔org isolation hinges on it. */
+export function authorize(req, env) {
+    return validateAccessToken(req.headers.get("authorization"), resolveStore(env));
+}
+/** 401 with the RFC 6750 challenge carrying the resource_metadata pointer (RFC 9728). Content-free. */
+function unauthorized(origin) {
+    return new Response(null, {
+        status: 401,
+        headers: {
+            "www-authenticate": `Bearer resource_metadata="${origin}/.well-known/oauth-protected-resource"`,
+        },
+    });
+}
+/** 200 JSON for a discovery metadata document. Public, short-cacheable, content-free of any secret. */
+function metadata(doc) {
+    return new Response(JSON.stringify(doc), {
+        status: 200,
+        headers: { "content-type": "application/json", "cache-control": "public, max-age=3600" },
+    });
+}
+/** Assemble the OAuth handler dependencies from the Worker env: the fixed client registry, the store,
+ *  the core seams, and the R3 webmail seams (consent URL, HMAC secret, WEB binding). */
+function oauthDeps(env) {
+    const web = resolveWeb(env);
+    return {
+        clients: DEFAULT_CLIENTS,
+        store: resolveStore(env),
+        ...(env.__coreFetch !== undefined ? { coreFetch: env.__coreFetch } : {}),
+        ...(env.POMBUS_API_BASE !== undefined ? { coreBaseUrl: env.POMBUS_API_BASE } : {}),
+        ...(env.WEB_CONSENT_URL !== undefined ? { webConsentUrl: env.WEB_CONSENT_URL } : {}),
+        ...(env.MCP_WEB_LINK_SECRET !== undefined ? { webLinkSecret: env.MCP_WEB_LINK_SECRET } : {}),
+        ...(web !== undefined ? { web } : {}),
+    };
+}
+/** 503 with a Retry-After, no body — the last-resort envelope for ANY unexpected throw inside fetch (a
+ *  store/DO RPC rejection is the real case). Collapsing every internal failure into one content-free 503
+ *  denies an availability oracle: 503 is honestly "unavailable", NOT the 401/403 a caller uses to infer
+ *  credential state, NOR the 200/302 of success. Nothing logged, no .message/.stack serialized. */
+function unavailable() {
+    return new Response(null, { status: 503, headers: { "retry-after": "60" } });
+}
+/** Origins allowed to call this Worker from a browser: itself (the webmail return lands here as a
+ *  top-level navigation, not a fetch, so it carries no Origin anyway) and the origins of the registered
+ *  OAuth callbacks. The MCP Streamable-HTTP spec requires validating Origin (DNS-rebinding fence).
+ *  Non-browser clients send no Origin and are judged by their credential alone. */
+export function originAllowed(req) {
+    const origin = req.headers.get("origin");
+    if (origin === null)
+        return true;
+    if (origin === new URL(req.url).origin)
+        return true;
+    return DEFAULT_CLIENTS.some((c) => c.redirectUris.some((u) => new URL(u).origin === origin));
+}
+export default {
+    async fetch(req, env) {
+        // One top-level try/catch is the last line of defence: the store is a Durable Object reached by RPC,
+        // so the `await`s below can REJECT when the DO is unavailable. The catch collapses any such throw
+        // into one content-free 503 (see unavailable()). The NORMAL error paths (401/400/302/503) return in
+        // their own flows and never fall through.
+        try {
+            const url = new URL(req.url);
+            const path = url.pathname;
+            // A foreign browser origin gets a content-free 403 before anything else (OAuth surfaces included).
+            if (!originAllowed(req))
+                return new Response(null, { status: 403 });
+            // --- OAuth surfaces (no Bearer required; they issue/complete the Bearer). AWAIT them so a store
+            // RPC rejection inside a handler lands in the top-level catch (→ one 503), not as an un-awaited
+            // rejected promise that escapes this try. ---
+            if (path === "/authorize") {
+                if (req.method === "GET")
+                    return await handleAuthorizeGet(req, oauthDeps(env));
+                // POST /authorize (the R2e paste-key approve) is GONE — the human decides on the webmail now.
+                return new Response(null, { status: 405, headers: { allow: "GET" } });
+            }
+            if (path === "/authorize/return") {
+                if (req.method === "GET")
+                    return await handleAuthorizeReturn(req, oauthDeps(env));
+                return new Response(null, { status: 405, headers: { allow: "GET" } });
+            }
+            if (path === "/token") {
+                if (req.method === "POST")
+                    return await handleToken(req, oauthDeps(env));
+                return new Response(null, { status: 405, headers: { allow: "POST" } });
+            }
+            // --- Discovery (RFC 9728 + RFC 8414) — PUBLIC metadata, origin-derived, no secret. ---
+            const origin = url.origin;
+            if (path === "/.well-known/oauth-protected-resource") {
+                if (req.method !== "GET")
+                    return new Response(null, { status: 405, headers: { allow: "GET" } });
+                return metadata({ resource: origin, authorization_servers: [origin] });
+            }
+            if (path === "/.well-known/oauth-authorization-server") {
+                if (req.method !== "GET")
+                    return new Response(null, { status: 405, headers: { allow: "GET" } });
+                return metadata({
+                    issuer: origin,
+                    authorization_endpoint: `${origin}/authorize`,
+                    token_endpoint: `${origin}/token`,
+                    registration_endpoint: `${origin}/register`,
+                    response_types_supported: ["code"],
+                    grant_types_supported: ["authorization_code"],
+                    code_challenge_methods_supported: ["S256"],
+                    token_endpoint_auth_methods_supported: ["none"],
+                });
+            }
+            // --- Dynamic Client Registration (RFC 7591) — PUBLIC. ---
+            if (path === "/register") {
+                if (req.method === "POST")
+                    return await handleRegister(req, oauthDeps(env));
+                return new Response(null, { status: 405, headers: { allow: "POST" } });
+            }
+            // --- Friendly root page — ONLY for a human browser (GET + Accept text/html + no credential). A
+            // real MCP client POSTs with Accept json/event-stream and a credential, so it never matches. The
+            // gate is deliberately narrow so it can never become an auth bypass. ---
+            if (req.method === "GET" &&
+                !req.headers.get("authorization") &&
+                !req.headers.get("x-api-key") &&
+                (req.headers.get("accept") ?? "").includes("text/html")) {
+                const locale = pickLocale([parseAcceptLanguage(req.headers.get("accept-language"))]);
+                return new Response(renderRoot(locale), {
+                    status: 200,
+                    headers: {
+                        "content-type": "text/html; charset=utf-8",
+                        "x-content-type-options": "nosniff",
+                        "cache-control": "no-store",
+                    },
+                });
+            }
+            // --- MCP endpoint (everything else) — requires a valid credential on exactly ONE of the two paths. ---
+            const bearer = req.headers.get("authorization");
+            const apiKeyHeader = req.headers.get("x-api-key");
+            // Both credentials at once is ambiguous (which org/scope?) — refuse rather than pick (fail-closed).
+            if (bearer && apiKeyHeader) {
+                return new Response(JSON.stringify({ error: "invalid_request" }), {
+                    status: 400,
+                    headers: { "content-type": "application/json", "cache-control": "no-store" },
+                });
+            }
+            // The credential the core will see, and whether this is the multi-org (Bearer) path.
+            let apiKey;
+            let orgTools;
+            if (apiKeyHeader) {
+                // x-api-key: the pod-key IS the credential (one org, stdio/Cursor style). No token-set lookup,
+                // no org tools. A blank header is no credential.
+                apiKey = apiKeyHeader.trim() || null;
+                orgTools = false;
+            }
+            else {
+                // Bearer: resolve the ACTIVE org's child key from the token-set. Org tools exposed.
+                apiKey = await authorize(req, env);
+                orgTools = true;
+            }
+            // Fail-closed: refuse BEFORE building the Server. No credential never resolves scope, never touches
+            // the core, never learns whether any inbox exists — the 401 is content-free.
+            if (!apiKey)
+                return unauthorized(origin);
+            const client = new CoreClient({
+                apiKey,
+                ...(env.POMBUS_API_BASE !== undefined ? { baseUrl: env.POMBUS_API_BASE } : {}),
+                ...(env.__coreFetch !== undefined ? { fetchImpl: env.__coreFetch } : {}),
+            });
+            // On the Bearer path the org tools need the token-set: pass the store + the access token so
+            // list/select_organization can read and re-point the set. The access token is parsed from the
+            // Authorization header exactly as validateAccessToken did (kept tiny — no second source of truth).
+            const orgSession = orgTools ? bearerOrgSession(bearer, resolveStore(env)) : undefined;
+            let server;
+            try {
+                server = await buildServer(client, orgSession ? { orgSession } : {});
+            }
+            catch {
+                // buildServer's only outward call is /auth/me (scope resolve). A failure there → content-free 401
+                // (the core's anti-enumeration rule; never distinguishes rejected key from unreachable core).
+                return unauthorized(origin);
+            }
+            const transport = new WebStandardStreamableHTTPServerTransport({ enableJsonResponse: true });
+            await server.connect(transport);
+            return transport.handleRequest(req);
+        }
+        catch {
+            return unavailable();
+        }
+    },
+};
+/** Build the org-session handle for the Bearer path: the store + the opaque access token the org tools
+ *  operate on. Returns undefined when the header has no Bearer token (then no org tools). The access
+ *  token is NEVER logged. */
+function bearerOrgSession(authorizationHeader, store) {
+    const m = /^Bearer (.+)$/.exec((authorizationHeader ?? "").trim());
+    const token = m?.[1]?.trim();
+    if (!token)
+        return undefined;
+    return { store, accessToken: token };
+}

package/dist/i18n.js

@@ -50,6 +50,36 @@ const MESSAGES = {
         "pt-BR": "Caixa criada: ",
         "es-419": "Casilla creada: ",
     },
+    init_inbox_needs_domain: {
+        "en-US": "--create-inbox needs --domain <your verified domain>: an extra inbox can only be created on a domain you own and have verified in Pombus.",
+        "pt-BR": "--create-inbox precisa de --domain <seu domínio verificado>: uma caixa adicional só pode ser criada em um domínio seu, já verificado no Pombus.",
+        "es-419": "--create-inbox necesita --domain <tu dominio verificado>: una casilla adicional solo se puede crear en un dominio tuyo, ya verificado en Pombus.",
+    },
+    init_inbox_bad_domain: {
+        "en-US": "--domain must be a domain name such as acme.com (no @, no spaces, no URL).",
+        "pt-BR": "--domain precisa ser um nome de domínio, como acme.com (sem @, sem espaços, sem URL).",
+        "es-419": "--domain debe ser un nombre de dominio, como acme.com (sin @, sin espacios, sin URL).",
+    },
+    init_inbox_platform_domain: {
+        "en-US": "That is the Pombus domain: your @pombus.com inbox is the one from signup, and an API key cannot create more. Use --domain with a domain you own and have verified.",
+        "pt-BR": "Esse é o domínio do Pombus: sua caixa @pombus.com é a do cadastro, e uma chave de API não cria outras. Use --domain com um domínio seu, já verificado.",
+        "es-419": "Ese es el dominio de Pombus: tu casilla @pombus.com es la del registro, y una clave de API no crea otras. Usa --domain con un dominio tuyo, ya verificado.",
+    },
+    init_inbox_domain_not_verified: {
+        "en-US": "That domain is not verified in your Pombus space yet. Verify it under Domains, then run init again.",
+        "pt-BR": "Esse domínio ainda não está verificado no seu espaço do Pombus. Verifique em Domínios e rode o init de novo.",
+        "es-419": "Ese dominio aún no está verificado en tu espacio de Pombus. Verifícalo en Dominios y vuelve a ejecutar init.",
+    },
+    init_inbox_limit: {
+        "en-US": "Your plan's inbox limit is reached. Delete an inbox or upgrade your plan in Pombus, then run init again.",
+        "pt-BR": "Você chegou ao limite de caixas do seu plano. Apague uma caixa ou mude de plano no Pombus e rode o init de novo.",
+        "es-419": "Llegaste al límite de casillas de tu plan. Borra una casilla o cambia de plan en Pombus y vuelve a ejecutar init.",
+    },
+    init_inbox_missing_permission: {
+        "en-US": "This API key cannot create inboxes. Use a key with the inbox-create permission (Pombus › Keys), or drop --create-inbox.",
+        "pt-BR": "Esta chave de API não pode criar caixas. Use uma chave com a permissão de criar caixa (Pombus › Chaves) ou tire o --create-inbox.",
+        "es-419": "Esta clave de API no puede crear casillas. Usa una clave con el permiso de crear casilla (Pombus › Claves) o quita --create-inbox.",
+    },
     init_config_written: {
         "en-US": "MCP config written for ",
         "pt-BR": "Config MCP gravada para ",
@@ -95,6 +125,12 @@ const MESSAGES = {
 const INSTALLER_CODES = [
     "init_prompt_key",
     "init_inbox_created",
+    "init_inbox_needs_domain",
+    "init_inbox_bad_domain",
+    "init_inbox_platform_domain",
+    "init_inbox_domain_not_verified",
+    "init_inbox_limit",
+    "init_inbox_missing_permission",
     "init_config_written",
     "init_key_power",
     "init_restart_client",

package/dist/init.js

@@ -6,7 +6,8 @@
 // and is reused. The function takes its side-effects as injected dependencies (key source, fetch,
 // HOME, output sink) so a test drives the whole flow against a fake core and a temp HOME without
 // ever touching real stdin/stdout/disk.
-import { CoreClient } from "./client.js";
+import { domainToASCII } from "node:url";
+import { CoreClient, CoreError } from "./client.js";
 import { ScopeBinding } from "./scope.js";
 import { clientTargets, printableCodexToml, printableJson, writeJsonConfig, ConfigWriteError, } from "./clients.js";
 import { humanMessage, resolveLocale } from "./i18n.js";
@@ -18,6 +19,18 @@ export async function runInit(opts) {
     const locale = opts.locale ?? resolveLocale();
     const out = opts.out ?? ((l) => process.stderr.write(l + "\n"));
     const say = (code, suffix = "") => out(humanMessage(code, locale) + suffix);
+    // --create-inbox needs --domain: an extra inbox only exists on a verified domain of your own. Refuse
+    // BEFORE the key prompt and any request, with the rule spelled out (the core would answer a bare 403).
+    const rawDomain = (opts.domain ?? "").trim();
+    if (opts.createInbox && !rawDomain) {
+        say("init_inbox_needs_domain");
+        throw new InitAbort("init_inbox_needs_domain");
+    }
+    const domain = normalizeDomain(rawDomain);
+    if (opts.createInbox && !looksLikeDomain(domain)) {
+        say("init_inbox_bad_domain");
+        throw new InitAbort("init_inbox_bad_domain");
+    }
     // --print with no key: emit the placeholder block for every known client and stop. No network, no
     // disk. This is the "I just want the snippet" path and the safe landing for uncertain detection.
     const key = (opts.apiKey ?? "").trim() || (opts.print ? "" : await requireKey(opts));
@@ -35,7 +48,21 @@ export async function runInit(opts) {
     let inboxId = scope.fixedInboxId;
     let inboxEmail = null;
     if (opts.createInbox) {
-        const created = await client.post("/inboxes", {});
+        let created;
+        try {
+            created = await client.post("/inboxes", { domain });
+        }
+        catch (e) {
+            // The refusals a person can act on (INBOX_REFUSALS) get their own line (the key was fine — /auth/me passed
+            // above). Anything else rethrows to the CLI's generic handler.
+            const why = e instanceof CoreError ? (e.coreCode ?? e.code) : "";
+            const human = INBOX_REFUSALS[why];
+            if (human) {
+                say(human);
+                throw new InitAbort(human);
+            }
+            throw e;
+        }
         inboxId = typeof created.inbox_id === "string" ? created.inbox_id : inboxId;
         inboxEmail = typeof created.email === "string" ? created.email : null;
         if (inboxEmail)
@@ -149,6 +176,30 @@ function emptyPrintResult() {
         printedFor: [],
     };
 }
+/** The core's create-inbox refusals a person can act on -> their human line. `platform_inbox_not_allowed`,
+ *  `inbox_limit` and `missing_permission` arrive as a 403 (collapsed to not_found, real code in coreCode);
+ *  `domain_not_verified` as a 422. */
+const INBOX_REFUSALS = {
+    platform_inbox_not_allowed: "init_inbox_platform_domain",
+    domain_not_verified: "init_inbox_domain_not_verified",
+    inbox_limit: "init_inbox_limit",
+    missing_permission: "init_inbox_missing_permission",
+};
+/** `--domain` as the core stores it: lowercase, no trailing dot, IDN in punycode (`café.com` ->
+ *  `xn--caf-dma.com`). ASCII is restricted to letters/digits/dot/hyphen BEFORE the conversion, because
+ *  `domainToASCII` parses a URL host and would silently cut `acme.com/x` down to `acme.com`. The caller
+ *  passes it already trimmed. */
+export function normalizeDomain(raw) {
+    const d = raw.toLowerCase();
+    if (!/^[a-z0-9.\-\u{80}-\u{10ffff}]+$/u.test(d))
+        return "";
+    return domainToASCII(d).replace(/\.$/, "");
+}
+/** A basic domain-name shape (labels of letters/digits/hyphens, a dot, a TLD) — catches a typo or a flag
+ *  swallowed as the value BEFORE any request. The core is the authority on whether it is verified. */
+function looksLikeDomain(d) {
+    return d.length <= 253 && /^([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z][a-z0-9-]{0,61}[a-z0-9]$/.test(d);
+}
 /** A clean, key-free abort for a missing prerequisite (the CLI turns it into exit code 1). */
 export class InitAbort extends Error {
     code;

package/dist/server.js

@@ -11,9 +11,9 @@ 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";
+import { specByName, toolDescriptors, callTool, callOrgTool, isOrgTool, ToolArgError, } from "./tools.js";
 const SERVER_NAME = "pombus";
-const SERVER_VERSION = "0.1.3";
+const SERVER_VERSION = "0.1.5";
 /** 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. */
@@ -47,21 +47,34 @@ export async function runMcpServer() {
 /** 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) {
+export async function buildServer(client, opts = {}) {
     const scope = await ScopeBinding.resolve(client);
+    const orgTools = opts.orgSession !== undefined;
+    const ctx = {
+        client,
+        scope,
+        ...(opts.orgSession !== undefined ? { orgSession: opts.orgSession } : {}),
+    };
     const server = new Server({ name: SERVER_NAME, version: SERVER_VERSION }, { capabilities: { tools: {} } });
     server.setRequestHandler(ListToolsRequestSchema, async () => ({
-        tools: toolDescriptors(scope),
+        tools: toolDescriptors(scope, { orgTools }),
     }));
     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 name = req.params.name;
         const args = (req.params.arguments ?? {});
         try {
-            const value = await callTool(spec, args, { client, scope });
+            // The org tools (Bearer path only) are resolved outside the REST gate: they carry no core
+            // permission. On the x-api-key path orgTools is false, so a call to one is "unknown" below.
+            if (orgTools && isOrgTool(name)) {
+                const value = await callOrgTool(name, args, ctx);
+                return { content: [{ type: "text", text: toText(value) }] };
+            }
+            // 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(name, scope);
+            if (!spec)
+                return toolError(`unknown tool: ${name}`);
+            const value = await callTool(spec, args, ctx);
             return { content: [{ type: "text", text: toText(value) }] };
         }
         catch (e) {

package/dist/tools.js

@@ -613,7 +613,8 @@ export const TOOL_TABLE = [
     {
         name: "create_inbox",
         title: "Create inbox",
-        description: "Create a new inbox in the pod.",
+        description: "Create a new inbox in the pod, on one of the pod's own VERIFIED domains (`domain` is required; " +
+            "an inbox on the platform domain cannot be created with an API key).",
         method: "POST",
         path: "/pods/{pod_id}/inboxes",
         requiredPerm: "inbox_create",
@@ -622,7 +623,7 @@ export const TOOL_TABLE = [
         annotations: { destructiveHint: false, idempotentHint: false, openWorldHint: true },
         params: [
             { name: "username", in: "body", type: "string" },
-            { name: "domain", in: "body", type: "string" },
+            { name: "domain", in: "body", type: "string", required: true },
             { name: "display_name", in: "body", type: "string" },
         ],
     },
@@ -931,25 +932,135 @@ function gatedTable(scope) {
     return TOOL_TABLE.filter((t) => isExposed(t, scope));
 }
 /** Build the MCP Tool descriptor list for the given scope: the gated subset, read tools carrying the
- *  anti-injection notice and readOnlyHint. */
-export function toolDescriptors(scope) {
-    return gatedTable(scope).map((t) => ({
+ *  anti-injection notice and readOnlyHint. On the OAuth/Bearer path (opts.orgTools) the two
+ *  organization tools are appended — they are NOT in TOOL_TABLE (no REST route, no core permission) and
+ *  so never leak onto the x-api-key path. */
+export function toolDescriptors(scope, opts = {}) {
+    const rest = gatedTable(scope).map((t) => ({
         name: t.name,
         title: t.title,
         description: t.readOnly ? t.description + EXTERNAL_CONTENT_NOTICE : t.description,
         inputSchema: buildSchema(t, scope),
         annotations: { title: t.title, readOnlyHint: t.readOnly, ...t.annotations },
     }));
+    return opts.orgTools ? [...rest, ...orgToolDescriptors()] : rest;
 }
-/** Resolve a tool by name, honouring the gate: a tool the key may not use is not found, exactly as it
- *  is absent from ListTools. This keeps CallTool and ListTools coherent — the gate is one function. */
+/** Resolve a REST tool by name, honouring the gate: a tool the key may not use is not found, exactly as
+ *  it is absent from ListTools. The org tools are resolved separately (they live outside TOOL_TABLE). */
 export function specByName(name, scope) {
     const def = TOOL_TABLE.find((t) => t.name === name);
     if (!def)
         return undefined;
     return isExposed(def, scope) ? def : undefined;
 }
-/** Run a tool's one REST request. Exposed so the server adapter and tests invoke it uniformly. */
+/** Run a REST tool's one request. Exposed so the server adapter and tests invoke it uniformly. */
 export function callTool(def, args, ctx) {
     return dispatch(def, args, ctx);
 }
+// ---- organization tools (R3 multi-org, Bearer path ONLY) -----------------------------------------
+// The two tools that let an agent see and switch which authorized org its token-set is pointed at. They
+// are NOT REST calls and carry no core permission: they read/mutate the token-set in the store via
+// ctx.orgSession. They are exposed ONLY when orgTools is on (the OAuth/Bearer path) — on the x-api-key
+// path there is one org and no set, so they do not exist. The invariant they protect (Model D): the
+// worker never retains the human's identity, so list_organizations lists ONLY the authorized orgs
+// (token.orgs), never the human's whole org universe; select_organization for an org OUTSIDE the set
+// NEVER falls back to another child key — it returns an authorize_url to re-run consent for that org.
+export const ORG_TOOL_NAMES = ["list_organizations", "select_organization"];
+/** The MCP descriptors for the two org tools. */
+export function orgToolDescriptors() {
+    return [
+        {
+            name: "list_organizations",
+            title: "List organizations",
+            description: "List the organizations this connection is authorized to act for, and which one is active. " +
+                "Only organizations you have authorized appear here.",
+            inputSchema: { type: "object", properties: {}, required: [], additionalProperties: false },
+            annotations: { title: "List organizations", readOnlyHint: true, openWorldHint: false },
+        },
+        {
+            name: "select_organization",
+            title: "Select organization",
+            description: "Switch the active organization. Pass an organization id or label from list_organizations. If " +
+                "it is one you have already authorized, the switch is instant. If not, this returns " +
+                "status 'authorization_required' with an authorize_url: open it (signed in to Pombus) to grant " +
+                "this connection access to that organization, then it becomes selectable.",
+            inputSchema: {
+                type: "object",
+                properties: { organization: { type: "string", description: "Organization id or label." } },
+                required: ["organization"],
+                additionalProperties: false,
+            },
+            annotations: { title: "Select organization", readOnlyHint: false, openWorldHint: false },
+        },
+    ];
+}
+/** Is `name` one of the org tools? */
+export function isOrgTool(name) {
+    return ORG_TOOL_NAMES.includes(name);
+}
+/** Run an org tool against the token-set. Requires ctx.orgSession (the Bearer path); without it the
+ *  tool does not exist, so this throws the same "unknown" shape a REST miss would (defense in depth —
+ *  it is never reached because the gate hides the tool on the x-api-key path). */
+export async function callOrgTool(name, args, ctx) {
+    const session = ctx.orgSession;
+    if (!session)
+        throw new ToolArgError("orgSession"); // unreachable on the x-api-key path (tool hidden)
+    const { store, accessToken } = session;
+    if (name === "list_organizations") {
+        const tok = await store.getToken(accessToken);
+        const orgs = tok ? Object.entries(tok.orgs) : [];
+        return {
+            organizations: orgs.map(([orgId, e]) => ({
+                orgId,
+                label: e.label,
+                active: tok ? orgId === tok.activeOrg : false,
+            })),
+        };
+    }
+    // select_organization
+    const requested = str(args["organization"]) ?? "";
+    if (!requested)
+        throw new ToolArgError("organization");
+    const tok = await store.getToken(accessToken);
+    if (!tok)
+        throw new ToolArgError("organization"); // token gone — the agent re-authorizes anyway
+    // Match by orgId first, then by (unique) label — a human passes whichever list_organizations showed.
+    let targetOrgId;
+    if (tok.orgs[requested]) {
+        targetOrgId = requested;
+    }
+    else {
+        const byLabel = Object.entries(tok.orgs).filter(([, e]) => e.label === requested);
+        if (byLabel.length === 1)
+            targetOrgId = byLabel[0][0];
+    }
+    if (targetOrgId) {
+        await store.setActiveOrg(accessToken, targetOrgId);
+        return { status: "active", orgId: targetOrgId };
+    }
+    // The org is NOT in the authorized set. NEVER fall back to another org's child key (SEC4): mint a
+    // single-use link_token tied to THIS access token and hand back an authorize_url the agent re-runs
+    // the OAuth flow against (with its own client_id/redirect/PKCE) carrying the link_token, so /token
+    // attaches the newly consented org to the SAME access token. The url is relative — the MCP client
+    // already knows this server's origin from the connection it is calling.
+    const linkToken = randomToken();
+    await store.putLink(linkToken, accessToken);
+    return {
+        status: "authorization_required",
+        link_token: linkToken,
+        authorize_url: `/authorize?link_token=${encodeURIComponent(linkToken)}`,
+        message: "Start the OAuth authorization flow against authorize_url (append your client_id, redirect_uri, " +
+            "response_type=code, PKCE and state as usual) while signed in to Pombus, to authorize this " +
+            "organization. The link_token ties the new organization to your current connection.",
+    };
+}
+/** A cryptographically-random opaque token (32 bytes → 43 base64url chars). Local to the tools layer so
+ *  the org link_token does not reach back into oauth.ts; identical generation. */
+function randomToken() {
+    const b = new Uint8Array(32);
+    crypto.getRandomValues(b);
+    let s = "";
+    for (const x of b)
+        s += String.fromCharCode(x);
+    return btoa(s).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}