Security 0.9.27: fix GHSA-63gr-g7jc-v8rg — HTTP MCP missing auth

The optional --http / MCP_HTTP=1 transport listened on all interfaces
with no Authorization check, so any LAN client could initialize a
session and invoke master-key-only tools (setup_email_relay,
delete_agent, cleanup_agents, etc.) using the server's own master key.

Fix:
- Default-bind /mcp to 127.0.0.1 (override with --host= or MCP_HTTP_HOST)
- Require Authorization: Bearer <token> on every /mcp request
- Token auto-minted to ~/.agenticmail/mcp-http-token (chmod 600), or
  supplied via --token= / MCP_HTTP_TOKEN
- --insecure opt-out for sandboxed test environments only, with a loud
  warning at startup
- /health stays open (returns only session count)
- Stdio mode (the default) was never affected

Release: mcp 0.9.27, claudecode 0.2.32, codex 0.1.26, cli 0.9.101

Author: ope-olatunji

agenticmail/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agenticmail/cli",
-  "version": "0.9.100",
+  "version": "0.9.101",
   "description": "Email, SMS & phone-call infrastructure for AI agents — real email addresses, phone numbers, and agent-driven outbound voice calls",
   "type": "module",
   "main": "dist/index.js",
@@ -38,8 +38,8 @@
     "json5": "^2.2.3"
   },
   "optionalDependencies": {
-    "@agenticmail/claudecode": "^0.2.31",
-    "@agenticmail/codex": "^0.1.25"
+    "@agenticmail/claudecode": "^0.2.32",
+    "@agenticmail/codex": "^0.1.26"
   },
   "devDependencies": {
     "tsup": "^8.4.0",

packages/claudecode/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agenticmail/claudecode",
-  "version": "0.2.31",
+  "version": "0.2.32",
   "description": "Claude Code integration for AgenticMail — surfaces every AgenticMail agent as a native Claude Code subagent so any Claude Code session can delegate to them with the Agent tool",
   "type": "module",
   "main": "dist/index.js",
@@ -48,7 +48,7 @@
   },
   "dependencies": {
     "@agenticmail/core": "^0.9.37",
-    "@agenticmail/mcp": "^0.9.26",
+    "@agenticmail/mcp": "^0.9.27",
     "@anthropic-ai/claude-agent-sdk": "^0.2.140"
   },
   "peerDependencies": {

packages/codex/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agenticmail/codex",
-  "version": "0.1.25",
+  "version": "0.1.26",
   "description": "OpenAI Codex CLI integration for AgenticMail — surfaces every AgenticMail agent as a native Codex subagent and wires the dispatcher daemon to the Codex SDK",
   "type": "module",
   "main": "dist/index.js",
@@ -46,7 +46,7 @@
   },
   "dependencies": {
     "@agenticmail/core": "^0.9.37",
-    "@agenticmail/mcp": "^0.9.26",
+    "@agenticmail/mcp": "^0.9.27",
     "@iarna/toml": "^2.2.5"
   },
   "peerDependencies": {

packages/mcp/README.md

@@ -8,6 +8,18 @@ The MCP (Model Context Protocol) server for [AgenticMail](https://github.com/age
 
 When connected, your AI agent can send emails and texts, check inboxes, reply to messages, receive verification codes, manage contacts, schedule emails, assign tasks to other agents, and more — all through natural language. The server provides 100 tools that cover every email, SMS, and agent management operation.
 
+## ✨ Security — 0.9.27
+
+**Fixes [GHSA-63gr-g7jc-v8rg](https://github.com/agenticmail/agenticmail/security/advisories/GHSA-63gr-g7jc-v8rg)** — missing authentication on the optional Streamable HTTP transport (`--http` / `MCP_HTTP=1`).
+
+- `--http` mode now **binds to `127.0.0.1` by default** and **requires `Authorization: Bearer <token>`** on every `/mcp` request.
+- The bearer token is auto-minted on first start and persisted to `~/.agenticmail/mcp-http-token` (chmod 600). Override with `MCP_HTTP_TOKEN` env or `--token=<value>`.
+- Bind to other interfaces with `--host=0.0.0.0` or `MCP_HTTP_HOST=...` — startup logs an explicit warning when the endpoint is reachable from the network.
+- `--insecure` brings back the old no-auth behavior for sandboxed test environments only. Startup prints a loud warning.
+- Stdio mode (the default) was never affected.
+
+If you weren't using `--http` / `MCP_HTTP=1`, no action is needed.
+
 ## ✨ What's new in 0.9.0
 
 - **🧠 `get_thread_id` + `save_thread_memory`** — two new tools in the `multi_agent_extras` tier. Workers call `get_thread_id({uid})` once after reading a new message, then `save_thread_memory({threadId, summary, commitments?, openQuestions?, lastAction?, lastUid?})` at end-of-wake. The dispatcher reads the memory back into the next wake's prompt automatically. Pairs with the dispatcher-side ThreadCache to flatten wake cost — agents no longer have to re-read 10 prior messages every time.
@@ -114,6 +126,20 @@ For desktop AI applications, add to your MCP configuration file. Example paths:
 
 ¹ Either `AGENTICMAIL_API_KEY` OR `AGENTICMAIL_MASTER_KEY` (or `AGENTICMAIL_ACCOUNT_KEYS_JSON`) must be set, but you don't strictly need all three.
 
+### Optional Streamable HTTP transport (`--http`)
+
+Most users should stick with the default stdio transport — that's what every MCP client config above uses. For environments that need a long-lived HTTP endpoint (browser-based clients, remote-development tunnels, multi-host setups), pass `--http`:
+
+```bash
+agenticmail-mcp --http                       # 127.0.0.1:8014, auth required
+agenticmail-mcp --http --port=9001
+agenticmail-mcp --http --host=0.0.0.0        # expose on network (token still required)
+agenticmail-mcp --http --token=mcphttp_xxx   # use a known token instead of the minted one
+agenticmail-mcp --http --insecure            # sandbox/test only — disables auth
+```
+
+The token is read from (in order): `--token=...` flag, `MCP_HTTP_TOKEN` env, `~/.agenticmail/mcp-http-token` (auto-minted on first run). Clients must send `Authorization: Bearer <token>` on every request to `/mcp`. `GET /health` stays open and returns only the session count.
+
 ### Per-call identity switching (`_account`)
 
 Every tool's input schema accepts an optional `_account: "<name>"` parameter. When passed, the server resolves that name to an apiKey (from `AGENTICMAIL_ACCOUNT_KEYS_JSON`, then falling back to a live master-keyed lookup of `/accounts`) and runs the call as that agent. Without `_account`, the call uses `AGENTICMAIL_API_KEY` as the default identity.

packages/mcp/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agenticmail/mcp",
-  "version": "0.9.26",
+  "version": "0.9.27",
   "mcpName": "io.github.agenticmail/mcp",
   "description": "MCP server for AgenticMail — give any AI client real email, SMS, and phone call-control capabilities",
   "type": "module",

packages/mcp/src/index.ts

@@ -6,7 +6,10 @@ import { toolDefinitions, handleToolCall } from './tools.js';
 import { resourceDefinitions, handleResourceRead } from './resources.js';
 import { setTelemetryVersion } from '@agenticmail/core';
 import { createServer } from 'node:http';
-import { randomUUID } from 'node:crypto';
+import { randomUUID, timingSafeEqual } from 'node:crypto';
+import { readFileSync, writeFileSync, mkdirSync, existsSync, chmodSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join as joinPath } from 'node:path';
 import { z, type ZodTypeAny } from 'zod';
 import { coerceToArray, coerceToObject, coerceToNumber, coerceToBoolean } from './coerce.js';
 
@@ -299,12 +302,85 @@ function createMcpServer(): McpServer {
 const args = process.argv.slice(2);
 const httpFlag = args.includes('--http');
 const portArg = args.find(a => a.startsWith('--port='));
+const hostArg = args.find(a => a.startsWith('--host='));
+const tokenArg = args.find(a => a.startsWith('--token='));
+const insecureFlag = args.includes('--insecure');
 const httpPort = portArg ? parseInt(portArg.split('=')[1], 10) : (parseInt(process.env.MCP_PORT || '', 10) || 8014);
+// Default-bind to loopback. Override with --host=0.0.0.0 or MCP_HTTP_HOST
+// to expose on other interfaces. Historical behavior (pre-fix for
+// GHSA-63gr-g7jc-v8rg) was to bind all interfaces, which exposed the
+// admin-tool surface to the LAN.
+const httpHost = hostArg ? hostArg.split('=')[1] : (process.env.MCP_HTTP_HOST || '127.0.0.1');
+
+/**
+ * Resolve the bearer token required to call /mcp in HTTP mode.
+ *
+ * Resolution order:
+ *   1. --token=<value> CLI flag
+ *   2. MCP_HTTP_TOKEN env var
+ *   3. Persistent file at ~/.agenticmail/mcp-http-token (auto-minted on
+ *      first run, chmod 600). Survives restarts so a user can wire the
+ *      token into their MCP client config once and forget it.
+ *
+ * Returns null only when --insecure is passed. That flag is the explicit
+ * opt-out and prints a loud warning at startup so it can't happen by
+ * accident.
+ */
+function resolveHttpToken(): string | null {
+  if (insecureFlag) return null;
+  if (tokenArg) return tokenArg.split('=').slice(1).join('=');
+  if (process.env.MCP_HTTP_TOKEN) return process.env.MCP_HTTP_TOKEN;
+  const dir = joinPath(homedir(), '.agenticmail');
+  const file = joinPath(dir, 'mcp-http-token');
+  if (existsSync(file)) {
+    try {
+      const t = readFileSync(file, 'utf8').trim();
+      if (t) return t;
+    } catch { /* fall through to mint */ }
+  }
+  const minted = 'mcphttp_' + randomUUID().replace(/-/g, '');
+  try {
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(file, minted + '\n', { mode: 0o600 });
+    chmodSync(file, 0o600);
+  } catch (err) {
+    console.error('[agenticmail-mcp] WARN: could not persist auth token to', file, '—', (err as Error).message);
+  }
+  return minted;
+}
+
+/**
+ * Constant-time bearer-token check. Returns true iff the request carries
+ * `Authorization: Bearer <expected>`. Length-safe so an attacker can't
+ * distinguish "wrong token" from "wrong length" via timing.
+ */
+function checkAuth(req: import('node:http').IncomingMessage, expected: string): boolean {
+  const header = req.headers['authorization'];
+  if (typeof header !== 'string') return false;
+  const m = header.match(/^Bearer\s+(.+)$/i);
+  if (!m) return false;
+  const got = Buffer.from(m[1]);
+  const want = Buffer.from(expected);
+  if (got.length !== want.length) return false;
+  return timingSafeEqual(got, want);
+}
 
 if (httpFlag || process.env.MCP_HTTP === '1') {
   // ─── HTTP/Streamable HTTP Transport ───────────────────────────────
   // Supports both SSE streaming and direct JSON responses per MCP spec.
-  // Usage: agenticmail-mcp --http [--port=8014]
+  // Usage: agenticmail-mcp --http [--port=8014] [--host=127.0.0.1]
+  //        [--token=<bearer>] [--insecure]
+  //
+  // Security model (post-GHSA-63gr-g7jc-v8rg):
+  //   - Binds to 127.0.0.1 by default so the admin-tool surface is not
+  //     reachable from other hosts on the network.
+  //   - Requires `Authorization: Bearer <token>` on every /mcp request.
+  //     Token is auto-minted on first run and stored at
+  //     ~/.agenticmail/mcp-http-token (chmod 600). Override with
+  //     MCP_HTTP_TOKEN or --token=.
+  //   - --insecure disables both bind-restriction warnings and the auth
+  //     check. Reserved for sandboxed test environments only.
+  const authToken = resolveHttpToken();
   const server = createMcpServer();
 
   // Map of session ID -> transport for stateful connections
@@ -328,6 +404,21 @@ if (httpFlag || process.env.MCP_HTTP === '1') {
       return;
     }
 
+    // Authentication gate — every /mcp request (POST/GET/DELETE) must
+    // present the bearer token. Skipped only when --insecure was passed
+    // (authToken === null), which is logged loudly at startup.
+    if (authToken !== null && !checkAuth(req, authToken)) {
+      res.writeHead(401, {
+        'Content-Type': 'application/json',
+        'WWW-Authenticate': 'Bearer realm="agenticmail-mcp"',
+      });
+      res.end(JSON.stringify({
+        error: 'Unauthorized. Send Authorization: Bearer <token>. ' +
+               'Token is at ~/.agenticmail/mcp-http-token or in MCP_HTTP_TOKEN.',
+      }));
+      return;
+    }
+
     // Handle DELETE for session termination
     if (req.method === 'DELETE') {
       const sessionId = req.headers['mcp-session-id'] as string | undefined;
@@ -392,11 +483,29 @@ if (httpFlag || process.env.MCP_HTTP === '1') {
     res.end(JSON.stringify({ error: 'Method not allowed. Use POST /mcp for JSON-RPC, GET /mcp for SSE stream.' }));
   });
 
-  httpServer.listen(httpPort, () => {
+  httpServer.listen(httpPort, httpHost, () => {
+    const displayHost = httpHost === '0.0.0.0' || httpHost === '::' ? 'localhost' : httpHost;
     console.log(`🎀 AgenticMail MCP Server (Streamable HTTP)`);
-    console.log(`   Endpoint: http://localhost:${httpPort}/mcp`);
-    console.log(`   Health:   http://localhost:${httpPort}/health`);
+    console.log(`   Endpoint: http://${displayHost}:${httpPort}/mcp`);
+    console.log(`   Health:   http://${displayHost}:${httpPort}/health`);
+    console.log(`   Bind:     ${httpHost}`);
     console.log(`   Transport: Streamable HTTP (SSE + JSON responses)`);
+    if (authToken === null) {
+      console.log('');
+      console.log('   ⚠️  --insecure: bearer-token auth DISABLED on /mcp.');
+      console.log('   ⚠️  Anyone who can reach the port can call master-key tools.');
+      console.log('   ⚠️  Do not run this mode on untrusted networks.');
+    } else {
+      console.log(`   Auth:     Bearer token required on /mcp`);
+      console.log('');
+      console.log('   Connect an MCP client with:');
+      console.log(`     Authorization: Bearer ${authToken}`);
+      if (httpHost !== '127.0.0.1' && httpHost !== 'localhost' && httpHost !== '::1') {
+        console.log('');
+        console.log(`   ⚠️  Bound to ${httpHost} — endpoint is reachable from the network.`);
+        console.log('   ⚠️  Make sure the bearer token above is treated as a secret.');
+      }
+    }
   });
 
   // Graceful shutdown