fde2e-bu 0.0.0 → 1.3.0

package/src/mcp/config-cli.mjs

@@ -0,0 +1,172 @@
+// mcp add/list/remove 子命令（task 3.3）——cli 层薄封装：解析参数 → 调 config.mjs
+// 编辑层 → 打印结果。--home/--dir 重定向根（测试沙箱），默认真实家目录/当前工作区。
+// r1 P1-4：--scope local（claude projects[cwd]；codex/gemini 不支持→如实跳过）；
+// r1 P2：list 输出 env 值脱敏（***尾4 / 已配置），不回显完整令牌。
+import { homedir } from 'node:os';
+import { resolve, dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parse, UsageError, csvList, assertFlags, assertNoPositionals } from '../args.mjs';
+import { DEFAULT_SERVER } from './bridge.mjs';
+import { SCOPES, buildEntry, jsonUpsert, jsonRemove, claudeLocalUpsert, claudeLocalRemove, codexUpsert, codexRemove, readTargetEntry, targetsFor, allTargets, SERVER_KEY } from './config.mjs';
+
+const CLIENTS = ['claude', 'codex', 'gemini'];
+
+// C1 flag 面（P2-6）：add/list/remove 各自合法集——不适用 flag 一律 exit 2，
+// 不再「解析了但静默忽略」（如 `mcp list --profile-id x` 此前被接受且无效果）。
+const HOME_DIR_HELP = {
+  home: { type: 'string' },
+  dir: { type: 'string' },
+  help: { type: 'boolean', short: 'h' },
+};
+const MCP_SUBS = {
+  add: {
+    options: {
+      client: { type: 'string' },
+      scope: { type: 'string' },
+      ...HOME_DIR_HELP,
+      server: { type: 'string' },
+      'profile-id': { type: 'string' },
+      cmd: { type: 'string' },
+    },
+    flags: ['client', 'scope', 'home', 'dir', 'server', 'profile-id', 'cmd', 'help'],
+  },
+  list: {
+    // list 只读全部落点；--client 作为显示过滤（此前被解析后丢弃）
+    options: { client: { type: 'string' }, ...HOME_DIR_HELP },
+    flags: ['client', 'home', 'dir', 'help'],
+  },
+  remove: {
+    // --scope 收窄要清理的落点层级（此前被解析后丢弃）
+    options: { client: { type: 'string' }, scope: { type: 'string' }, ...HOME_DIR_HELP },
+    flags: ['client', 'scope', 'home', 'dir', 'help'],
+  },
+};
+
+const binPath = join(dirname(dirname(dirname(fileURLToPath(import.meta.url)))), 'bin.js'); // cli/src/mcp → cli/bin.js
+
+function parseClients(raw) {
+  const list = raw ? csvList(String(raw)) : [...CLIENTS];
+  const bad = list.filter((c) => !CLIENTS.includes(c));
+  if (bad.length > 0) throw new UsageError(`未知 --client：${bad.join(',')}（可用：${CLIENTS.join(',')}）`);
+  return list;
+}
+
+// ---------- r1 P2：list 脱敏 ----------
+
+/** env 值脱敏：令牌类键直接「已配置」；其余 `***<尾4>`（短值全遮）。不回显完整令牌。 */
+function maskEnvValue(key, value) {
+  const v = String(value);
+  if (/token|key|secret|password/i.test(key)) return '(已配置)';
+  return v.length > 4 ? `***${v.slice(-4)}` : '***';
+}
+
+/** JSON 条目脱敏拷贝（只动 env 值，形状原样）。 */
+function maskJsonEntry(entry) {
+  if (!entry || typeof entry !== 'object' || !entry.env) return entry;
+  const env = {};
+  for (const [k, v] of Object.entries(entry.env)) env[k] = maskEnvValue(k, v);
+  return { ...entry, env };
+}
+
+/** codex TOML 块脱敏：env = { K = "v", ... } 行内值替换（其余行字节不动）。 */
+function maskTomlEntry(text) {
+  return text
+    .split('\n')
+    .map((line) => (/^env = \{/.test(line.trim())
+      ? line.replace(/([A-Za-z_][A-Za-z0-9_]*) = "([^"]*)"/g, (_m, k, v) => `${k} = "${maskEnvValue(k, v)}"`)
+      : line))
+    .join('\n');
+}
+
+/** 落点读取（claude local 走 projects[cwd] 面；其余按 JSON/TOML 面）——list/status 共用。 */
+const readTarget = readTargetEntry;
+
+/** 落点写入/移除（同上分面）。 */
+function writeTarget(t, entry) {
+  if (t.client === 'codex') return codexUpsert(t.path, entry);
+  if (t.client === 'claude' && t.kind === 'local') return claudeLocalUpsert(t.path, t.cwd, entry);
+  return jsonUpsert(t.path, entry);
+}
+
+function removeFromTarget(t) {
+  if (t.client === 'codex') return codexRemove(t.path);
+  if (t.client === 'claude' && t.kind === 'local') return claudeLocalRemove(t.path, t.cwd);
+  return jsonRemove(t.path);
+}
+
+/**
+ * @param {string|undefined} sub
+ * @param {string[]} rest
+ * @returns {number} exit code
+ */
+export function cmdMcp(sub, rest, helpText) {
+  const spec = MCP_SUBS[sub];
+  if (!spec) {
+    throw new UsageError(`未知子命令：mcp ${sub ?? ''}（可用：serve/add/list/remove）`, { exitCode: 2 });
+  }
+  assertFlags(rest, spec.flags, `mcp ${sub}`, { help: helpText });
+  const { positionals, values } = parse(rest, { options: spec.options, help: helpText });
+  if (values.help) {
+    console.log(helpText);
+    return 0;
+  }
+  assertNoPositionals(positionals, `mcp ${sub}`, { help: helpText });
+  const home = values.home ? resolve(String(values.home)) : homedir();
+  const dir = values.dir ? resolve(String(values.dir)) : process.cwd();
+  const clients = parseClients(values.client);
+  const scope = values.scope ? String(values.scope) : 'user';
+  if (values.scope !== undefined && !SCOPES.includes(scope)) {
+    throw new UsageError(`--scope 取值 ${SCOPES.join('|')}（收到 ${scope}）`);
+  }
+
+  switch (sub) {
+    case 'add': {
+      const entry = buildEntry({
+        cmd: values.cmd ? String(values.cmd) : undefined,
+        binPath,
+        server: values.server ? String(values.server) : undefined,
+        profileId: values['profile-id'] ? String(values['profile-id']) : undefined,
+      });
+      for (const t of targetsFor({ home, dir, scope, cwd: dir })) {
+        if (!clients.includes(t.client)) continue;
+        if (t.skip) {
+          console.log(`跳过 ${t.client}（${scope}）：${t.skip}`);
+          continue;
+        }
+        writeTarget(t, entry);
+        console.log(`已注册 ${t.client}（${t.kind}）：${t.path}${t.note ? `——${t.note}` : ''}`);
+      }
+      console.log(`条目：${JSON.stringify(entry)}`);
+      return 0;
+    }
+    case 'list': {
+      const targets = allTargets(home, dir).filter((t) => clients.includes(t.client));
+      let registered = 0;
+      for (const t of targets) {
+        const entry = readTarget(t);
+        const mark = entry ? '✓' : '✗';
+        if (entry) registered++;
+        console.log(`${mark} ${t.client.padEnd(6)} ${t.kind.padEnd(7)} ${t.path}`);
+        if (entry) {
+          const shown = typeof entry === 'string' ? maskTomlEntry(entry) : JSON.stringify(maskJsonEntry(entry));
+          console.log(`    ${shown.replace(/\n/g, '\n    ')}`);
+        }
+      }
+      console.log(`已注册 ${registered}/${targets.length} 落点（server 名：${SERVER_KEY}；桥服务缺省 ${DEFAULT_SERVER}）`);
+      return 0;
+    }
+    case 'remove': {
+      // --scope 收窄层级（缺省全清）；kind 与 scope 同名映射（user/project/local）
+      const targets = allTargets(home, dir)
+        .filter((t) => clients.includes(t.client))
+        .filter((t) => values.scope === undefined || t.kind === scope);
+      for (const t of targets) {
+        const removed = removeFromTarget(t);
+        console.log(`${removed ? '已移除' : '未注册（幂等跳过）'} ${t.client} ${t.kind}：${t.path}`);
+      }
+      return 0;
+    }
+    default:
+      throw new UsageError(`未知子命令：mcp ${sub ?? ''}（可用：serve/add/list/remove）`, { exitCode: 2 });
+  }
+}

package/src/mcp/config.mjs

@@ -0,0 +1,257 @@
+// mcp add/list/remove 的配置编辑层（task 3.3）——三家 MCP 客户端，声明式配置为真源，
+// CLI 只是编辑器（调研 A 节）。写入形状对齐各家官方文档：
+//   claude  user    ~/.claude.json   → { mcpServers: { "fde2e-bu": {command,args,env} } }（顶层）
+//           project ./.mcp.json      → 同上（入库共享，客户端首次使用需用户批准）
+//           local   ~/.claude.json   → projects[<cwd>].mcpServers["fde2e-bu"]（r1 P1-4）
+//   codex   user    ~/.codex/config.toml → [mcp_servers.fde2e-bu] command/args/env（TOML
+//                                           手写片段编辑：只动本表块，其余字节不动）；
+//                                           无 project/local 级（project 请求降级写 user）
+//   gemini  user    ~/.gemini/settings.json → { mcpServers: { ... } }（r1 P2）
+//           project ./.gemini/settings.json → 同上（gemini 缺省 project 语义）
+// 纪律：--home/--dir 显式重定向根目录（测试与沙箱用，绝不隐式碰真实家目录）；
+// JSON 走读-改-写只触碰 mcpServers["fde2e-bu"] 键（claude local＝projects[cwd] 下同键），
+// 用户已有配置原样保留。
+import { existsSync, readFileSync, mkdirSync, writeFileSync, renameSync, chmodSync, unlinkSync } from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
+import { randomBytes } from 'node:crypto';
+
+export const SERVER_KEY = 'fde2e-bu';
+
+// ---------- C4 原子写 / 0600（P2-10） ----------
+
+/**
+ * 原子落盘：同目录 temp（`.tmp-<pid>-<rand>`）→ writeFileSync(mode 0600) →
+ * renameSync → chmodSync 0600。异常清理 temp，原文件保持旧内容（不留半截写）。
+ * 既有文件权限也被收紧到 0600（含 env 令牌，宁紧勿松）。
+ * @param {string} path 目标文件
+ * @param {string} text 完整内容
+ */
+export function atomicWrite(path, text) {
+  const dir = dirname(path);
+  mkdirSync(dir, { recursive: true });
+  const tmp = join(dir, `.tmp-${process.pid}-${randomBytes(6).toString('hex')}`);
+  try {
+    writeFileSync(tmp, text, { encoding: 'utf8', mode: 0o600 }); // temp 恒为新建文件 → mode 生效
+    renameSync(tmp, path);
+    chmodSync(path, 0o600); // rename 已保留 0600；此处兜底既有文件的旧权限也被收紧
+  } catch (err) {
+    try {
+      if (existsSync(tmp)) unlinkSync(tmp);
+    } catch { /* 清理失败不掩盖原始错误 */ }
+    throw err;
+  }
+}
+
+/** 注册条目：默认 node+bin 绝对路径（本地开发零假设）；--cmd 给 bare 命令名。 */
+export function buildEntry({ cmd, binPath, server, profileId }) {
+  const entry = cmd
+    ? { command: cmd, args: ['mcp', 'serve'] }
+    : { command: process.execPath, args: [binPath, 'mcp', 'serve'] };
+  const env = {};
+  if (server) env.BU_BRIDGE_SERVER = server;
+  if (profileId) env.BU_BRIDGE_PROFILE_ID = profileId;
+  if (Object.keys(env).length > 0) entry.env = env;
+  return entry;
+}
+
+// ---------- JSON 配置（claude user / claude project / gemini） ----------
+
+function readJsonSafe(path) {
+  if (!existsSync(path)) return {};
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf8'));
+    return parsed && typeof parsed === 'object' ? parsed : {};
+  } catch {
+    throw new Error(`配置文件不是合法 JSON（拒绝盲写覆盖）：${path}`);
+  }
+}
+
+function writeJson(path, data) {
+  atomicWrite(path, `${JSON.stringify(data, null, 2)}\n`); // C4：temp+rename+0600 原子落盘
+}
+
+/** JSON 面 add：读-改-写只触碰 mcpServers[SERVER_KEY]。 */
+export function jsonUpsert(path, entry) {
+  const data = readJsonSafe(path);
+  if (!data.mcpServers || typeof data.mcpServers !== 'object') data.mcpServers = {};
+  data.mcpServers[SERVER_KEY] = entry;
+  writeJson(path, data);
+  return path;
+}
+
+/** JSON 面 remove：返回是否实际移除（幂等）。 */
+export function jsonRemove(path) {
+  if (!existsSync(path)) return false;
+  const data = readJsonSafe(path);
+  if (!data.mcpServers || !(SERVER_KEY in data.mcpServers)) return false;
+  delete data.mcpServers[SERVER_KEY];
+  if (Object.keys(data.mcpServers).length === 0) delete data.mcpServers; // 不留空壳键
+  writeJson(path, data);
+  return true;
+}
+
+/** JSON 面读取：条目或 null。 */
+export function jsonGet(path) {
+  if (!existsSync(path)) return null;
+  const data = readJsonSafe(path);
+  return data?.mcpServers?.[SERVER_KEY] ?? null;
+}
+
+// ---------- claude local（r1 P1-4）：~/.claude.json 的 projects[<cwd>].mcpServers ----------
+
+/** claude local 面 add：projects[<cwd>].mcpServers[SERVER_KEY]（cwd 以 resolve 归一为键）。 */
+export function claudeLocalUpsert(path, cwd, entry) {
+  const data = readJsonSafe(path);
+  if (!data.projects || typeof data.projects !== 'object') data.projects = {};
+  const key = resolve(cwd);
+  if (!data.projects[key] || typeof data.projects[key] !== 'object') data.projects[key] = {};
+  const proj = data.projects[key];
+  if (!proj.mcpServers || typeof proj.mcpServers !== 'object') proj.mcpServers = {};
+  proj.mcpServers[SERVER_KEY] = entry;
+  writeJson(path, data);
+  return path;
+}
+
+/** claude local 面 remove：返回是否实际移除（幂等；不留空 mcpServers/projects 壳键）。 */
+export function claudeLocalRemove(path, cwd) {
+  if (!existsSync(path)) return false;
+  const data = readJsonSafe(path);
+  const key = resolve(cwd);
+  const proj = data.projects?.[key];
+  if (!proj || !proj.mcpServers || !(SERVER_KEY in proj.mcpServers)) return false;
+  delete proj.mcpServers[SERVER_KEY];
+  if (Object.keys(proj.mcpServers).length === 0) delete proj.mcpServers;
+  if (Object.keys(proj).length === 0) delete data.projects[key];
+  if (Object.keys(data.projects).length === 0) delete data.projects;
+  writeJson(path, data);
+  return true;
+}
+
+/** claude local 面读取：条目或 null。 */
+export function claudeLocalGet(path, cwd) {
+  if (!existsSync(path)) return null;
+  const data = readJsonSafe(path);
+  return data?.projects?.[resolve(cwd)]?.mcpServers?.[SERVER_KEY] ?? null;
+}
+
+// ---------- TOML（codex ~/.codex/config.toml） ----------
+
+const tomlStr = (v) => `"${String(v).replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+
+/** 生成 codex 表块（env 用行内表——codex 官方 config 文档形态）。 */
+export function codexTomlBlock(entry) {
+  const lines = [`[mcp_servers.${SERVER_KEY}]`];
+  lines.push(`command = ${tomlStr(entry.command)}`);
+  lines.push(`args = [${entry.args.map(tomlStr).join(', ')}]`);
+  if (entry.env && Object.keys(entry.env).length > 0) {
+    lines.push(`env = { ${Object.entries(entry.env).map(([k, v]) => `${k} = ${tomlStr(v)}`).join(', ')} }`);
+  }
+  return lines.join('\n');
+}
+
+/** TOML 面 add：移除既有本表块（含其子表）后追加新块；文件其余内容字节不动。 */
+export function codexUpsert(path, entry) {
+  const prev = existsSync(path) ? readFileSync(path, 'utf8') : '';
+  const stripped = stripCodexBlock(prev);
+  const block = codexTomlBlock(entry);
+  const next = stripped.length > 0
+    ? `${stripped.replace(/\n+$/, '')}\n\n${block}\n`
+    : `${block}\n`;
+  atomicWrite(path, next); // C4：TOML 同样走原子写
+  return path;
+}
+
+/** TOML 面 remove：剥离本表块（幂等；返回是否实际移除）。 */
+export function codexRemove(path) {
+  if (!existsSync(path)) return false;
+  const prev = readFileSync(path, 'utf8');
+  const next = stripCodexBlock(prev);
+  if (next === prev) return false;
+  atomicWrite(path, next); // C4：TOML remove 同样原子写
+  return true;
+}
+
+/** 剥离 [mcp_servers.fde2e-bu]（及其点号子表）块：从表头行删到下一个顶格 [ 之前。 */
+export function stripCodexBlock(text) {
+  const lines = text.split('\n');
+  const out = [];
+  let inBlock = false;
+  const own = new RegExp(`^\\[mcp_servers\\.${SERVER_KEY}(\\.[\\w.-]+)?\\]`);
+  for (const line of lines) {
+    if (inBlock) {
+      if (/^\[/.test(line)) { inBlock = false; } else continue; // 块内行（含键值/注释/空行）删除
+    }
+    if (!inBlock && own.test(line.trim()) && line.trim().startsWith('[')) {
+      inBlock = true;
+      continue;
+    }
+    if (!inBlock) out.push(line);
+  }
+  // 收敛删除块造成的多余连续空行（最多保留单个空行分隔）
+  return out.join('\n').replace(/\n{3,}/g, '\n\n').replace(/^\n+/, '');
+}
+
+/** TOML 面读取：表块文本或 null（与 stripCodexBlock 同款行扫描，避免正则歧义）。 */
+export function codexGet(path) {
+  if (!existsSync(path)) return null;
+  const lines = readFileSync(path, 'utf8').split('\n');
+  const own = new RegExp(`^\\[mcp_servers\\.${SERVER_KEY}\\]`);
+  const start = lines.findIndex((l) => own.test(l.trim()));
+  if (start === -1) return null;
+  const out = [lines[start]];
+  for (let j = start + 1; j < lines.length; j++) {
+    if (/^\[/.test(lines[j])) break;
+    out.push(lines[j]);
+  }
+  return out.join('\n').trimEnd();
+}
+
+/** 落点条目读取（按 client/kind 分面）——mcp list 与 status 注册清单共用：
+ *  codex 返回 TOML 块文本，claude local 走 projects[cwd]，其余按 JSON 面。 */
+export function readTargetEntry(t) {
+  if (t.client === 'codex') return codexGet(t.path);
+  if (t.client === 'claude' && t.kind === 'local') return claudeLocalGet(t.path, t.cwd);
+  return jsonGet(t.path);
+}
+
+// ---------- 三家目标路径（r1：scope 矩阵三家如实化） ----------
+
+export const SCOPES = ['user', 'project', 'local'];
+
+/**
+ * add 用目标集：按 scope × client 展开；不支持组合带 skip 标记（cli 层如实提示不写）。
+ *  - claude：user→~/.claude.json（顶层 mcpServers）；project→dir/.mcp.json；
+ *            local→~/.claude.json projects[cwd].mcpServers（cwd＝--dir 或 process.cwd()）
+ *  - codex ：仅 user（~/.codex/config.toml）；project 请求降级写 user（note 如实）；
+ *            local 不支持（skip）
+ *  - gemini：user→home/.gemini/settings.json；project→dir/.gemini/settings.json；
+ *            local 不支持（skip）
+ * @param {{ home: string, dir: string, scope?: 'user'|'project'|'local', cwd?: string }} roots
+ */
+export function targetsFor({ home, dir, scope = 'user', cwd = dir }) {
+  const t = [];
+  // claude 三级
+  if (scope === 'project') t.push({ client: 'claude', kind: 'project', path: join(dir, '.mcp.json') });
+  else if (scope === 'local') t.push({ client: 'claude', kind: 'local', path: join(home, '.claude.json'), cwd: resolve(cwd) });
+  else t.push({ client: 'claude', kind: 'user', path: join(home, '.claude.json') });
+  // codex：只认 user（project 降级写 user；local 跳过）
+  t.push(scope === 'local'
+    ? { client: 'codex', kind: 'user', path: join(home, '.codex', 'config.toml'), skip: 'codex 不支持 local scope（只有 user 级 ~/.codex/config.toml）' }
+    : { client: 'codex', kind: 'user', path: join(home, '.codex', 'config.toml'), ...(scope === 'project' ? { note: 'codex 无 project 级，已写 user' } : {}) });
+  // gemini：user/project 两级
+  if (scope === 'local') t.push({ client: 'gemini', kind: 'project', path: join(dir, '.gemini', 'settings.json'), skip: 'gemini 不支持 local scope（user=~/.gemini/settings.json / project=.gemini/settings.json）' });
+  else t.push({ client: 'gemini', kind: scope, path: scope === 'user' ? join(home, '.gemini', 'settings.json') : join(dir, '.gemini', 'settings.json') });
+  return t;
+}
+
+/** list/remove 用：全部落点全展开（claude user/project/local＋codex user＋gemini user/project＝6）。 */
+export function allTargets(home, dir, cwd = dir) {
+  return [
+    { client: 'claude', kind: 'user', path: join(home, '.claude.json') },
+    { client: 'claude', kind: 'project', path: join(dir, '.mcp.json') },
+    { client: 'claude', kind: 'local', path: join(home, '.claude.json'), cwd: resolve(cwd) },
+    { client: 'codex', kind: 'user', path: join(home, '.codex', 'config.toml') },
+    { client: 'gemini', kind: 'user', path: join(home, '.gemini', 'settings.json') },
+    { client: 'gemini', kind: 'project', path: join(dir, '.gemini', 'settings.json') },
+  ];
+}

package/src/mcp/http.mjs

@@ -0,0 +1,250 @@
+// mcp serve --http（change bu-bind-http-publish A4）——node:http 单端点 JSON-RPC，
+// 与 stdio 共用 handleMessage/handleAsyncMessage（src/mcp/serve.mjs 单源）。
+//
+// 安全三重门（design §3；不做 SSE/会话——面向脚本集成的最小面）：
+//   1. Host 头 ∈ 回环集合（127.0.0.1/localhost/[::1]，可带 :port）否则 403
+//      ——防 DNS rebinding；
+//   2. Origin 在场时必须 http://127.0.0.1[:port] / http://localhost[:port] 否则 403
+//      （无 Origin 放行——curl/服务间调用没有 Origin）；
+//   3. Authorization: Bearer <token> 恒时比较匹配否则 401（/healthz 免 token）。
+// 只 listen 127.0.0.1（缺省端口 8791；--port 0＝临时端口）。日志/启动信息全走
+// stderr——stdout 纪律不受影响。
+import http from 'node:http';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+import { atomicWrite } from './config.mjs';
+import { resolveConfigDir } from '../configdir.mjs';
+import { handleAsyncMessage, rpcError } from './serve.mjs';
+import { bridgeEnv } from './bridge.mjs';
+import { pairingDefaultProfileId } from '../nm/host.mjs';
+import pkg from '../../package.json' with { type: 'json' };
+
+export const SERVER_NAME = 'fde2e-bu';
+export const DEFAULT_HTTP_PORT = 8791;
+/** 请求体上限：单条 JSON-RPC 远用不到 1MB，4MB 已是宽容上限（防无界读）。 */
+const MAX_BODY_BYTES = 4 * 1024 * 1024;
+
+// ---------- 门 1/2（纯函数，可测） ----------
+
+/** Host 头白名单：127.0.0.1 / localhost / [::1]，均可带 :port；大小写不敏感。 */
+export function hostHeaderAllowed(hostHeader) {
+  if (typeof hostHeader !== 'string' || hostHeader === '') return false;
+  const h = hostHeader.trim().toLowerCase();
+  if (h.startsWith('[')) { // IPv6 字面量：[::1] 或 [::1]:port
+    const close = h.indexOf(']');
+    if (close === -1) return false;
+    const hostPart = h.slice(0, close + 1);
+    const rest = h.slice(close + 1);
+    return hostPart === '[::1]' && (rest === '' || /^:\d+$/.test(rest));
+  }
+  const bare = h.replace(/:\d+$/, '');
+  return bare === '127.0.0.1' || bare === 'localhost';
+}
+
+/** Origin 门：无 Origin 放行；在场必须 http://127.0.0.1[:port]/http://localhost[:port]。 */
+export function originHeaderAllowed(origin) {
+  if (origin === undefined || origin === '') return true;
+  const o = String(origin).trim().toLowerCase();
+  if (o === 'http://127.0.0.1' || o === 'http://localhost') return true;
+  return /^http:\/\/(127\.0\.0\.1|localhost)(:\d+)?$/.test(o);
+}
+
+/** Bearer 恒时比较（长度不同直接拒绝，不进 timingSafeEqual）。
+ *  P2-11：scheme 按 RFC 7235 大小写不敏感（bearer/bEaReR 均可）；token 仍精确比较。 */
+export function bearerOk(authorizationHeader, token) {
+  if (typeof authorizationHeader !== 'string' || token === undefined || token === null) return false;
+  const m = /^Bearer\s+(.+)$/i.exec(authorizationHeader.trim());
+  if (!m) return false;
+  const a = Buffer.from(m[1], 'utf8');
+  const b = Buffer.from(String(token), 'utf8');
+  return a.length === b.length && timingSafeEqual(a, b);
+}
+
+// ---------- token 三源 ----------
+
+/**
+ * token 解析：--token > BU_MCP_TOKEN > <configDir>/token（无则生成 32B hex 原子写
+ * 0600——atomicWrite 底座同 pairing/客户端配置）。
+ * @returns {{ token:string, source:string, generated?:true }}
+ */
+export function resolveHttpToken({ tokenFlag, env = process.env, configDir } = {}) {
+  if (tokenFlag !== undefined && String(tokenFlag) !== '') return { token: String(tokenFlag), source: '--token' };
+  if (env.BU_MCP_TOKEN) return { token: String(env.BU_MCP_TOKEN), source: 'BU_MCP_TOKEN' };
+  const dir = configDir ?? resolveConfigDir({ env });
+  const p = join(dir, 'token');
+  if (existsSync(p)) {
+    const existing = readFileSync(p, 'utf8').trim();
+    if (existing !== '') return { token: existing, source: p };
+  }
+  const token = randomBytes(32).toString('hex');
+  atomicWrite(p, `${token}\n`);
+  return { token, source: p, generated: true };
+}
+
+// ---------- HTTP server ----------
+
+/** 读请求体（带上限；超限 reject code=413——响应与切断的时序由调用方负责：
+ *  必须先把 413 回执写完再 destroy，抢跑会让客户端只见 ECONNRESET）。 */
+function readBody(req) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    let size = 0;
+    let over = false;
+    req.on('data', (c) => {
+      if (over) return; // 超限后继续排空（不累积），防止客户端上行阻塞
+      size += c.length;
+      if (size > MAX_BODY_BYTES) {
+        over = true;
+        const err = new Error(`请求体超 ${MAX_BODY_BYTES}B 上限`);
+        err.status = 413;
+        reject(err);
+        return;
+      }
+      chunks.push(c);
+    });
+    req.on('end', () => { if (!over) resolve(Buffer.concat(chunks).toString('utf8')); });
+    req.on('error', (err) => { if (!over) reject(err); });
+  });
+}
+
+function sendJson(res, status, obj) {
+  const body = JSON.stringify(obj);
+  res.writeHead(status, { 'content-type': 'application/json' });
+  res.end(body);
+}
+
+/**
+ * 造 HTTP MCP server（只绑 127.0.0.1；listen/close 由调用方控制——测试可注入）。
+ * @param {{ token?: string, version?: string, env?: object }} [settings]
+ *   env＝bridgeEnv 产物（execute 派发用；缺省 bridgeEnv()）。
+ * @returns {{ server: http.Server, state: object, close: () => Promise<void> }}
+ */
+export function createHttpMcpServer(settings = {}) {
+  const token = settings.token;
+  const version = settings.version ?? pkg.version;
+  const env = settings.env ?? bridgeEnv();
+  const state = { initialized: false, version, env };
+
+  const server = http.createServer(async (req, res) => {
+    const pathname = (req.url ?? '/').split('?')[0];
+    try {
+      // 门 1：Host（防 DNS rebinding）——一切路由共用
+      if (!hostHeaderAllowed(req.headers.host)) {
+        return sendJson(res, 403, { error: 'Host 头不在回环白名单（127.0.0.1/localhost/[::1]）' });
+      }
+      // 门 2：Origin（在场必须回环 http；无 Origin 放行）
+      if (!originHeaderAllowed(req.headers.origin)) {
+        return sendJson(res, 403, { error: 'Origin 不被接受（仅 http://127.0.0.1[:port] / http://localhost[:port]）' });
+      }
+      // 免 token 探活
+      if (req.method === 'GET' && pathname === '/healthz') {
+        return sendJson(res, 200, { ok: true, server: SERVER_NAME, version });
+      }
+      if (req.method === 'POST' && (pathname === '/' || pathname === '/mcp')) {
+        // 门 3：Bearer token
+        if (!bearerOk(req.headers.authorization, token)) {
+          return sendJson(res, 401, { error: 'Bearer token 缺失或不匹配（Authorization: Bearer <token>）' });
+        }
+        let body;
+        try {
+          body = await readBody(req);
+        } catch (err) {
+          // P2-10：413 必须可达——先把回执完整写出（connection:close 明示不复用），
+          // flush 回调里再切断剩余上行；直接 destroy 会抢在响应刷盘前杀连接，
+          // 客户端只见 ECONNRESET 而收不到 413。
+          if (err.status === 413) {
+            res.writeHead(413, { 'content-type': 'application/json', connection: 'close' });
+            res.end(JSON.stringify({ error: err.message }), () => req.destroy());
+            return;
+          }
+          return sendJson(res, err.status ?? 400, { error: err.message });
+        }
+        let msg;
+        try {
+          msg = JSON.parse(body);
+        } catch {
+          return sendJson(res, 200, rpcError(null, -32700, 'Parse error: 请求体不是合法 JSON'));
+        }
+        if (Array.isArray(msg)) {
+          return sendJson(res, 200, rpcError(null, -32600, 'Invalid Request: JSON-RPC batching 已在 MCP 2025-06-18 移除'));
+        }
+        let responses;
+        try {
+          responses = await handleAsyncMessage(msg, state, env);
+        } catch (err) {
+          return sendJson(res, 200, rpcError(
+            msg && typeof msg === 'object' && 'id' in msg ? msg.id : null,
+            -32603,
+            `Internal error: ${err?.message ?? err}`,
+          ));
+        }
+        if (responses.length === 0) {
+          res.writeHead(204); // 通知（无 id）→ 无应答体
+          return res.end();
+        }
+        return sendJson(res, 200, responses[0]); // 单条消息至多一条应答
+      }
+      return sendJson(res, 404, { error: `Not Found: ${req.method} ${pathname}` });
+    } catch (err) {
+      // 路由层兜底（不崩服务）
+      try {
+        sendJson(res, 500, { error: `Internal error: ${err?.message ?? err}` });
+      } catch { /* 响应已提交则放弃 */ }
+    }
+  });
+
+  const close = () => new Promise((resolve) => {
+    server.close(() => resolve());
+    if (typeof server.closeAllConnections === 'function') server.closeAllConnections(); // 闲置 keep-alive 不拖关闭
+  });
+  return { server, state, close };
+}
+
+/**
+ * serve --http 主入口：解析 token → listen 127.0.0.1 → stderr 打印地址+token →
+ * 等待 SIGINT/SIGTERM/服务关闭，优雅 close 后返回 0。
+ * @param {{ port?: number, token?: string, configDir?: string, env?: object,
+ *           stderr?: object }} [opts]
+ */
+export async function runHttpServe({ port = DEFAULT_HTTP_PORT, token: tokenFlag, configDir, env = process.env, stderr = process.stderr } = {}) {
+  const resolvedToken = resolveHttpToken({ tokenFlag, env, configDir });
+  // P1-1：BU_BRIDGE_PROFILE_ID 未设置时回退本机配对（与 stdio runServe 同语义；
+  // 回退在 run* 层，bridgeEnv 纯函数不变）
+  let bridge = bridgeEnv(env);
+  if (!bridge.profileId) {
+    const fallback = pairingDefaultProfileId(configDir ?? resolveConfigDir({ env }));
+    if (fallback) {
+      bridge = { ...bridge, profileId: fallback };
+      stderr.write(`fde2e-bu: BU_BRIDGE_PROFILE_ID 未设置——profileId 取自本机配对（fde2e-bu bind）：${fallback}\n`);
+    }
+  }
+  const { server, close } = createHttpMcpServer({ token: resolvedToken.token, env: bridge });
+  await new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(port, '127.0.0.1', () => resolve());
+  });
+  const actualPort = server.address().port;
+  stderr.write(`fde2e-bu mcp serve --http 监听 http://127.0.0.1:${actualPort}（仅回环；缺省端口 ${DEFAULT_HTTP_PORT}，0=临时）\n`);
+  // P2-13：token 打印收敛——只有「本次自动生成（新写文件）」才回显完整值（否则用户
+  // 无从得知新生成的 token）；--token/env/既有文件来源只打尾 4 位＋来源（完整值不再
+  // 落日志——日志会被采集/转发，泄漏面收敛到生成那一刻）。
+  if (resolvedToken.generated) {
+    stderr.write(`token（来源 ${resolvedToken.source}，本次自动生成（0600））：${resolvedToken.token}\n`);
+  } else {
+    stderr.write(`token=****${resolvedToken.token.slice(-4)}（来源 ${resolvedToken.source}——完整值不回显，见上述文件/参数）\n`);
+  }
+  stderr.write('端点：POST / 与 POST /mcp（单条 JSON-RPC；通知 204）；GET /healthz 免 token。stdio 仍是 MCP 客户端主通道。\n');
+  await new Promise((resolve) => {
+    let done = false;
+    const finish = () => {
+      if (done) return;
+      done = true;
+      close().then(() => resolve());
+    };
+    process.once('SIGINT', finish);
+    process.once('SIGTERM', finish);
+    server.once('close', finish);
+  });
+  return 0;
+}