hostpad 0.2.0

package/README.md

@@ -0,0 +1,64 @@
+# hostpad
+
+HostPad 的 Mac 端伴侣：**MCP 服务器 + iPhone 加密同步桥**，让 AI agent（ZCode / Claude 等）直接在你的 iPhone 上开发、调试、迭代 iOS 工具（HTML/JS 小工具，跑在 [HostPad App] 里）。
+
+单进程双面：
+
+- **对 AI agent**：MCP stdio 服务器（JSON-RPC 2.0），9 个工具
+- **对 iPhone**：WebSocket 同步桥（协议 v1.3，X25519 + HKDF + AES-256-GCM 全程加密）
+
+## 快速开始
+
+```bash
+# 1. 启动（打印局域网 ws 地址）
+npx hostpad
+
+# 2. iPhone 上安装 HostPad App，首页「服务器」填 ws://<Mac 的 IP>:8787
+# 3. 首次连接手机屏显 6 位配对码，让 agent 调 MCP pair 工具确认
+```
+
+接进 MCP 客户端：
+
+```json
+{
+  "mcpServers": {
+    "hostpad": { "command": "npx", "args": ["-y", "hostpad"] }
+  }
+}
+```
+
+## MCP 工具（9 个）
+
+| 工具 | 作用 |
+|------|------|
+| `list_devices` | 列出连接的 iPhone（配对状态 / 设备名 / 地址） |
+| `pair` | 用手机屏显的 6 位配对码确认配对 |
+| `create_tool` / `update_tool` / `list_tools` / `delete_tool` | 管理工具（update 为覆盖合并：只传改动文件，推送即热重载） |
+| `reload` | 重推工具（激活） |
+| `get_logs` | 读手机回流的日志环形缓冲（工具 console.* 与系统事件，游标分页） |
+| `rpc_call` | 调用手机上运行中工具的 `onMessage` 处理器，返回值回传 |
+
+典型闭环：`create_tool`（写）→ 手机热加载 → `get_logs` 读 `loaded` / console 输出 → `update_tool` 增量迭代 → `rpc_call` 驱动交互。
+
+## 命令行
+
+```
+npx hostpad [--port 8787] [--tools ./tools] [--insecure] [--pair-code 123456] [--state <path>]
+```
+
+- `--insecure`：明文模式（本地快迭代；默认加密 + 配对）
+- `--pair-code`：固定配对码（自动化测试）
+- 防暴力：同 IP 配对失败 5 次锁 60s；配对码 60s 过期、一次性
+
+## 安全模型
+
+- 全程应用层加密：auth token、配对码、日志、工具源码不落明文到局域网
+- 防被动嗅探与重放；主动 MITM 仅在配对窗口理论可行（6 位码人工比对缓解）
+- 配对 token 双端持久（手机 Keychain / Mac `--state` 文件），一次配对长期免证
+
+## 环境要求
+
+- Node ≥ 18（零第三方依赖之外仅 `ws`）
+- iPhone 端需 HostPad App
+
+License: 目前未授权发布（UNLICENSED），供 HostPad 项目配套使用。

package/bin/hostpad.js

@@ -0,0 +1,208 @@
+#!/usr/bin/env node
+// hostpad — MCP 服务器 + WebSocket 桥（M2.3）
+// AI agent 经 MCP stdio 驱动；iPhone App 连 ws://<Mac IP>:<port>（协议 v1.3，默认加密）。
+'use strict';
+const os = require('node:os');
+const readline = require('node:readline');
+const { createBridge } = require('../lib/bridge.js');
+const { createMcpServer } = require('../lib/mcp.js');
+
+// ---------- 参数 ----------
+function arg(name, def) {
+  const i = process.argv.indexOf('--' + name);
+  return i >= 0 && process.argv[i + 1] && !process.argv[i + 1].startsWith('--')
+    ? process.argv[i + 1] : def;
+}
+const PORT = parseInt(arg('port', '8787'), 10);
+const TOOLS = arg('tools', './tools');
+const STATE = arg('state', null);
+const INSECURE = process.argv.includes('--insecure');
+const PAIR_CODE = arg('pair-code', null);
+const AUTO_CONFIRM = parseInt(arg('auto-confirm', '0'), 10);
+
+if (process.argv.includes('--help') || process.argv.includes('-h')) {
+  console.log(`hostpad — HostPad 的 MCP 服务器 + 手机同步桥
+
+用法：npx hostpad [--port 8787] [--tools ./tools] [--insecure] [--pair-code 123456] [--auto-confirm 800]
+
+  --port        WebSocket 桥端口（默认 8787）
+  --tools       工具目录（默认 ./tools）
+  --insecure    明文模式（本地快迭代/soak 用；默认加密 + 配对）
+  --pair-code   固定配对码（自动化用）
+  --auto-confirm <ms>  出现待配对设备后 ms 毫秒自动确认（需 --pair-code；自动化用）
+
+MCP 客户端（ZCode/Claude 等）配置：
+  { "mcpServers": { "hostpad": { "command": "npx", "args": ["-y", "hostpad"] } } }
+
+手机端：App 连接 ws://<本机局域网IP>:<port>`);
+  process.exit(0);
+}
+
+// ---------- 桥 ----------
+const bridge = createBridge({
+  port: PORT,
+  toolsDir: TOOLS,
+  statePath: STATE ?? require('node:path').join(__dirname, '..', '.hostpad-state.json'),
+  secure: !INSECURE,
+  pairCode: PAIR_CODE,
+  log: (...a) => console.error('[bridge]', ...a), // stdout 留给 MCP 协议
+});
+
+if (AUTO_CONFIRM > 0 && PAIR_CODE) {
+  setInterval(() => {
+    if (bridge.listDevices().some((d) => d.pairing)) {
+      bridge.pairConfirm(PAIR_CODE).catch(() => {});
+    }
+  }, AUTO_CONFIRM);
+}
+
+// ---------- MCP 工具面 ----------
+const fileSchema = {
+  type: 'array',
+  description: '工具文件（path 相对工具根，不得含 .. 或绝对路径）',
+  items: {
+    type: 'object',
+    properties: { path: { type: 'string' }, content: { type: 'string' } },
+    required: ['path', 'content'],
+  },
+};
+const tools = [
+  {
+    name: 'list_devices',
+    description: '列出当前连接的 iPhone 设备（配对状态、设备名、地址）',
+    inputSchema: { type: 'object', properties: {} },
+    handler: async () => ({ devices: bridge.listDevices() }),
+  },
+  {
+    name: 'pair',
+    description: '确认配对：输入手机屏幕上显示的 6 位配对码',
+    inputSchema: {
+      type: 'object',
+      properties: { code: { type: 'string', description: '6 位配对码' } },
+      required: ['code'],
+    },
+    handler: async ({ code }) => bridge.pairConfirm(String(code)),
+  },
+  {
+    name: 'create_tool',
+    description: '创建工具并推送到手机（推送即激活）。manifest: {id,name,version,entry,permissions?}',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        manifest: {
+          type: 'object',
+          properties: {
+            id: { type: 'string' }, name: { type: 'string' },
+            version: { type: 'string' }, entry: { type: 'string' },
+            permissions: { type: 'array', items: { type: 'string' } },
+          },
+          required: ['id', 'name', 'version', 'entry'],
+        },
+        files: fileSchema,
+      },
+      required: ['manifest', 'files'],
+    },
+    handler: async ({ manifest, files }) => {
+      const tool = bridge.createTool(manifest, files);
+      return { id: tool.manifest.id, files: tool.files.length };
+    },
+  },
+  {
+    name: 'update_tool',
+    description: '更新工具并推送（覆盖合并：只传要改的文件）。可只改 manifest 或只改 files',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        toolId: { type: 'string' },
+        manifest: { type: 'object' },
+        files: fileSchema,
+      },
+      required: ['toolId'],
+    },
+    handler: async ({ toolId, manifest, files }) => {
+      const tool = bridge.updateTool(toolId, { manifest, files });
+      return { id: tool.manifest.id, files: tool.files.length };
+    },
+  },
+  {
+    name: 'list_tools',
+    description: '列出 Mac 侧工具目录中的全部工具',
+    inputSchema: { type: 'object', properties: {} },
+    handler: async () => ({ tools: bridge.listTools() }),
+  },
+  {
+    name: 'delete_tool',
+    description: '删除工具（Mac 侧目录 + 通知手机删除本地副本）',
+    inputSchema: {
+      type: 'object',
+      properties: { toolId: { type: 'string' } },
+      required: ['toolId'],
+    },
+    handler: async ({ toolId }) => { bridge.deleteTool(toolId); return { deleted: toolId }; },
+  },
+  {
+    name: 'reload',
+    description: '重推工具（reason=watch，手机端会激活）。不传 toolId 则全部重推',
+    inputSchema: {
+      type: 'object',
+      properties: { toolId: { type: 'string' } },
+    },
+    handler: async ({ toolId }) => ({ pushed: bridge.reload(toolId) }),
+  },
+  {
+    name: 'get_logs',
+    description: '读取手机回流的日志环形缓冲（工具 console.* 与系统事件）。since 用上一批最后一行的 t 做游标',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        since: { type: 'number', description: '只取 t 大于该值的行（毫秒时间戳）' },
+        toolId: { type: 'string' },
+        limit: { type: 'number' },
+      },
+    },
+    handler: async (args) => ({
+      logs: bridge.getLogs({ since: args?.since ?? 0, toolId: args?.toolId ?? null, limit: args?.limit ?? 200 }),
+    }),
+  },
+  {
+    name: 'rpc_call',
+    description: '调用手机上当前运行工具的 onMessage 处理器（与页面按钮事件同路）；handler 的返回值会回传',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        toolId: { type: 'string' },
+        name: { type: 'string', description: '消息名（对应 host.ui.onMessage 的 msg.name）' },
+        values: { type: 'object', description: '附带值（对应 msg.values）' },
+        timeoutMs: { type: 'number' },
+      },
+      required: ['toolId', 'name'],
+    },
+    handler: async ({ toolId, name, values, timeoutMs }) => bridge.rpcCall(
+      toolId, name,
+      // 协议 values 为字符串表（与页面表单事件 msg.values 语义一致）
+      Object.fromEntries(Object.entries(values ?? {}).map(([k, v]) => [k, String(v)])),
+      { timeoutMs: timeoutMs ?? 5000 },
+    ),
+  },
+];
+
+const mcp = createMcpServer({
+  tools,
+  write: (line) => process.stdout.write(line + '\n'),
+});
+
+// ---------- stdio ----------
+const rl = readline.createInterface({ input: process.stdin });
+rl.on('line', (line) => { mcp.handleLine(line); });
+rl.on('close', () => { bridge.stop().then(() => process.exit(0)); });
+
+// ---------- 启动 ----------
+bridge.start().then(() => {
+  const nets = Object.values(os.networkInterfaces()).flat()
+    .filter((n) => n && n.family === 'IPv4' && !n.internal)
+    .map((n) => n.address);
+  console.error(`[hostpad] 桥就绪 ws://0.0.0.0:${bridge.port}${INSECURE ? '（明文模式）' : '（加密+配对）'}`);
+  for (const ip of nets) console.error(`[hostpad] 手机连接：ws://${ip}:${bridge.port}`);
+  console.error(`[hostpad] 工具目录：${require('node:path').resolve(TOOLS)}`);
+  console.error('[hostpad] MCP stdio 就绪（agent 请经 stdin/stdout 对话）');
+});

package/lib/bridge.js

@@ -0,0 +1,408 @@
+// M2.3 Task 4：WebSocket 桥——MCP 服务器与 iPhone App 之间的同步通道（协议 v1.3）。
+// 安全模式：hello → secure-start（X25519+HKDF+AESGCM）→ 密道内 auth/配对；
+// 增量推送：连接内 per-tool 记「最后已发 hashes」，push 只带变更文件 + 全量 hashes；
+// rpc：agent → 设备（rpc 帧）→ handler 返回值经 rpc-result 回传，5s 超时。
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { WebSocketServer } = require('ws');
+const C = require('./crypto.js');
+const { createRateLimiter, createCodeStore } = require('./ratelimit.js');
+const { createToolStore } = require('./tools.js');
+
+function createBridge({
+  port = 8787,
+  host = '0.0.0.0',
+  toolsDir,
+  statePath,
+  secure = true,
+  pairCode = null,
+  maxPairFails = 5,
+  lockMs = 60_000,
+  logsCap = 1000,
+  watch = true,
+  log = console.log,
+} = {}) {
+  const store = createToolStore(toolsDir);
+  const ratelimiter = createRateLimiter({ maxFails: maxPairFails, lockMs });
+  const codeStore = createCodeStore({ ttl: 60_000 });
+
+  // ---------- 设备 token 状态（兼容 M1 字符串数组） ----------
+  function loadState() {
+    try {
+      const raw = JSON.parse(fs.readFileSync(statePath, 'utf8'));
+      return (raw.tokens || []).map((t) =>
+        typeof t === 'string' ? { token: t, deviceId: '?', name: '?', pairedAt: 0 } : t);
+    } catch { return []; }
+  }
+  let tokens = loadState();
+  function saveState() {
+    fs.writeFileSync(statePath, JSON.stringify({ tokens }, null, 2));
+  }
+
+  // ---------- 连接与内存态 ----------
+  let wss = null;
+  const conns = new Set();          // 已建立 ws 的连接（含未认证）
+  const logs = [];                  // 日志环形缓冲 {t, toolId, level, text, ts}
+  const pendingRpc = new Map();     // rpcId → {resolve, reject, timer, conn}
+  const pendingReload = new Map();  // pushId → {t0, toolId, reason}
+  let soakWaiter = null;            // {toolId, resolve}（server.js shim 压测用）
+  let heartbeat = null;
+  let watcher = null;
+
+  const authedConns = () => [...conns].filter((c) => c.authed);
+
+  function sendTo(conn, obj) {
+    if (conn.ws.readyState !== 1) return;
+    const json = JSON.stringify(obj);
+    if (conn.secure) conn.ws.send(C.encryptFrame(conn.secure.serverToApp, json));
+    else conn.ws.send(json);
+  }
+
+  // ---------- 推送 ----------
+
+  function pushTool(conn, toolId, reason, { force = false } = {}) {
+    const tool = store.read(toolId);
+    if (!tool) return null;
+    const hashes = store.hashes(toolId);
+    const manifestJSON = JSON.stringify(tool.manifest);
+    const prev = conn.sent.get(toolId);
+    let delta = false;
+    let files = tool.files;
+    if (reason !== 'initial' && prev) {
+      const changed = tool.files.filter((f) => prev.hashes[f.path] !== hashes[f.path]);
+      const removed = Object.keys(prev.hashes).filter((p) => !(p in hashes));
+      if (!force && changed.length === 0 && removed.length === 0 && prev.manifestJSON === manifestJSON) {
+        return null; // 无变化不推（fs.watch 与显式推送去重的关键）
+      }
+      delta = true;
+      files = changed; // 删除经 hashes 键集表达，无需带文件
+    }
+    const pushId = crypto.randomUUID();
+    sendTo(conn, {
+      type: 'push', pushId, reason, toolId,
+      manifest: tool.manifest, files, hashes, delta,
+    });
+    conn.sent.set(toolId, { pushId, hashes, manifestJSON });
+    pendingReload.set(pushId, { t0: Date.now(), toolId, reason });
+    log(`[push] ${toolId} ${reason} pushId=${pushId.slice(0, 8)} files=${files.length}${delta ? '（增量）' : ''}`);
+    return pushId;
+  }
+
+  function pushToAuthed(toolId, reason, opts) {
+    for (const conn of authedConns()) pushTool(conn, toolId, reason, opts);
+  }
+
+  function pushAll(conn, reason) {
+    for (const id of store.list()) pushTool(conn, id, reason);
+  }
+
+  // ---------- 配对 ----------
+
+  function startPairing(conn) {
+    conn.pair = null;
+    const pairId = crypto.randomUUID();
+    const code = codeStore.issue(pairId, pairCode);
+    conn.pair = { pairId };
+    sendTo(conn, { type: 'pair-challenge', pairId, code });
+    log(`[pair] 设备 ${conn.device?.name ?? conn.ip} 显示配对码（60s 有效）`);
+  }
+
+  /** MCP pair(code)：对任一待配对连接校验配对码；错误计失败，达到阈值锁定 IP */
+  function pairConfirm(code) {
+    return new Promise((resolve, reject) => {
+      for (const conn of conns) {
+        if (!conn.pair || conn.authed) continue;
+        if (codeStore.verify(conn.pair.pairId, code)) {
+          ratelimiter.reset(conn.ip);
+          const token = crypto.randomUUID();
+          tokens.push({
+            token,
+            deviceId: conn.device?.id ?? '?',
+            name: conn.device?.name ?? '?',
+            pairedAt: Date.now(),
+          });
+          saveState();
+          conn.authed = true;
+          const pairId = conn.pair.pairId;
+          conn.pair = null;
+          sendTo(conn, { type: 'pair-granted', pairId, token });
+          log(`[pair] ✓ 配对成功 ${conn.device?.name ?? conn.ip}`);
+          pushAll(conn, 'initial');
+          resolve({ ok: true, device: conn.device });
+          return;
+        }
+        // 该连接的码被消费但不匹配：清掉待配对态，手机重新 auth 可再触发
+        conn.pair = null;
+        ratelimiter.fail(conn.ip);
+        if (ratelimiter.isLocked(conn.ip)) {
+          conn.ws.close(4003, 'locked');
+          reject(new Error('IP 已锁定（配对失败次数过多），60s 后自动解除'));
+          return;
+        }
+      }
+      reject(new Error('配对码不符或已过期'));
+    });
+  }
+
+  // ---------- rpc ----------
+
+  function rpcCall(toolId, name, values, { timeoutMs = 5000 } = {}) {
+    return new Promise((resolve, reject) => {
+      const conn = authedConns()[0];
+      if (!conn) { reject(new Error('无已连接设备')); return; }
+      const rpcId = crypto.randomUUID();
+      const timer = setTimeout(() => {
+        pendingRpc.delete(rpcId);
+        reject(new Error('rpc 超时'));
+      }, timeoutMs);
+      pendingRpc.set(rpcId, {
+        resolve, reject, timer, conn,
+        settle: (result) => {
+          clearTimeout(timer);
+          pendingRpc.delete(rpcId);
+          if (result.ok) resolve({ ok: true, result: result.result });
+          else reject(new Error(result.error || 'rpc 失败'));
+        },
+      });
+      sendTo(conn, { type: 'rpc', rpcId, toolId, name, values: values ?? {} });
+    });
+  }
+
+  // ---------- 连接处理 ----------
+
+  function handleFrame(conn, f) {
+    if (f.type === 'hello') {
+      if (!secure || conn.state !== 'new') return;
+      let eph, rand;
+      try {
+        eph = Buffer.from(f.eph, 'base64');
+        rand = Buffer.from(f.rand, 'base64');
+        if (eph.length !== 32 || rand.length !== 32) throw new Error('bad');
+      } catch { conn.ws.close(4000, 'bad hello'); return; }
+      const kp = C.makeKeyPair();
+      const srvRand = crypto.randomBytes(32);
+      const shared = C.sharedSecret(kp.privateKey, eph);
+      conn.device = f.device ?? null;
+      conn.state = 'secure';
+      // secure-start 是握手帧，必须明文发出（客户端拿到 eph/rand 才能派生密钥）
+      conn.ws.send(JSON.stringify({
+        type: 'secure-start',
+        eph: kp.publicKeyRaw.toString('base64'),
+        rand: srvRand.toString('base64'),
+      }));
+      conn.secure = C.deriveKeys(shared, rand, srvRand);
+      return;
+    }
+    if (f.type === 'auth') {
+      if (f.device) conn.device = f.device; // 明文模式下连接即 authed，设备信息仍要记录
+      if (conn.authed) return;
+      if (!secure) {
+        conn.authed = true;
+        if (!conn.initialPushed) { conn.initialPushed = true; pushAll(conn, 'initial'); }
+        return;
+      }
+      if (conn.state !== 'secure') return;
+      const entry = tokens.find((t) => t.token === f.token);
+      if (entry) {
+        conn.authed = true;
+        log(`[auth] token ✓ ${conn.device?.name ?? ''}（配对于 ${new Date(entry.pairedAt).toLocaleString()}）`);
+        pushAll(conn, 'initial');
+      } else {
+        log('[auth] 无有效 token → 发起配对');
+        startPairing(conn);
+      }
+      return;
+    }
+    if (f.type === 'ping') { if (conn.authed) sendTo(conn, { type: 'pong' }); return; }
+    if (f.type === 'log') {
+      if (!conn.authed) return;
+      logs.push({
+        t: Date.now(), toolId: f.toolId ?? '?', level: f.level ?? '?',
+        text: f.text ?? '', ts: f.ts, device: conn.device?.name,
+      });
+      if (logs.length > logsCap) logs.splice(0, logs.length - logsCap);
+      if (Number.isFinite(f.ts)) log(`[log] ${f.toolId ?? '?'} ${f.level ?? '?'} +${Date.now() - f.ts}ms ${f.text ?? ''}`);
+      else log(`[log] ${f.toolId ?? '?'} ${f.level ?? '?'} ${f.text ?? ''}`);
+      if (f.level === 'system' && f.text === 'loaded' && pendingReload.has(f.pushId)) {
+        const p = pendingReload.get(f.pushId);
+        pendingReload.delete(f.pushId);
+        log(`[reload] ${p.toolId} ${p.reason} → ${Date.now() - p.t0}ms`);
+        if (soakWaiter && soakWaiter.toolId === p.toolId) {
+          soakWaiter.resolve({ ok: true, ms: Date.now() - p.t0 });
+          soakWaiter = null;
+        }
+      }
+      return;
+    }
+    if (f.type === 'need-full') {
+      for (const [toolId, e] of conn.sent) {
+        if (e.pushId !== f.pushId) continue;
+        const tool = store.read(toolId);
+        if (!tool) return;
+        sendTo(conn, {
+          type: 'push', pushId: f.pushId, reason: 'watch', toolId,
+          manifest: tool.manifest, files: tool.files, hashes: store.hashes(toolId), delta: false,
+        });
+        log(`[push] ${toolId} need-full 重发（同 pushId）`);
+        return;
+      }
+      return;
+    }
+    if (f.type === 'rpc-result') {
+      const p = pendingRpc.get(f.rpcId);
+      if (p) p.settle({ ok: Boolean(f.ok), result: f.result, error: f.error });
+    }
+  }
+
+  function onConnection(ws, req) {
+    const ip = (req.socket.remoteAddress || '?').replace(/^::ffff:/, '');
+    if (ratelimiter.isLocked(ip)) {
+      log(`[conn] ${ip} 锁定期内连接，拒绝`);
+      ws.close(4003, 'locked');
+      return;
+    }
+    const conn = {
+      ws, ip, state: 'new', secure: null, authed: !secure,
+      device: null, pair: null, initialPushed: false,
+      sent: new Map(), // toolId → {pushId, hashes, manifestJSON}
+    };
+    conns.add(conn);
+    log(`[conn] +1（共 ${conns.size}）from ${ip}`);
+    ws.isAlive = true;
+    ws.on('pong', () => { ws.isAlive = true; });
+
+    if (!secure) {
+      sendTo(conn, { type: 'plain' });
+      conn.initialPushed = true;
+      pushAll(conn, 'initial'); // M1 开发态语义：连接即全量
+    }
+
+    ws.on('message', (data, isBinary) => {
+      let obj = null;
+      if (isBinary) {
+        if (!conn.secure) return; // 通道未建立前的二进制：忽略
+        try { obj = JSON.parse(C.decryptFrame(conn.secure.appToServer, data)); } catch { return; }
+      } else {
+        if (conn.secure) return; // 通道建立后的明文：忽略（防御）
+        try { obj = JSON.parse(data.toString()); } catch { return; }
+      }
+      handleFrame(conn, obj);
+    });
+    ws.on('close', () => {
+      conns.delete(conn);
+      for (const [rpcId, p] of pendingRpc) {
+        if (p.conn === conn) { clearTimeout(p.timer); p.reject(new Error('设备断开')); pendingRpc.delete(rpcId); }
+      }
+      log(`[conn] -1（剩 ${conns.size}）`);
+    });
+    ws.on('error', (e) => log(`[conn] error ${e.message}`));
+  }
+
+  // ---------- 生命周期 ----------
+
+  async function start() {
+    wss = new WebSocketServer({ port, host });
+    await new Promise((resolve) => wss.on('listening', resolve));
+    wss.on('connection', onConnection);
+
+    heartbeat = setInterval(() => {
+      for (const ws of wss.clients) {
+        if (!ws.isAlive) { ws.terminate(); continue; }
+        ws.isAlive = false;
+        ws.ping();
+      }
+    }, 10_000);
+
+    if (watch) {
+      const debounce = new Map();
+      try {
+        watcher = fs.watch(toolsDir, { recursive: true }, (_event, filename) => {
+          if (!filename) return;
+          const toolId = filename.split(path.sep)[0];
+          if (toolId.startsWith('.')) return;
+          clearTimeout(debounce.get(toolId));
+          debounce.set(toolId, setTimeout(() => {
+            if (!fs.existsSync(path.join(toolsDir, toolId, 'manifest.json'))) return;
+            pushToAuthed(toolId, 'watch');
+          }, 200));
+        });
+      } catch (e) { log(`[warn] fs.watch 不可用: ${e.message}`); }
+    }
+  }
+
+  function stop() {
+    clearInterval(heartbeat);
+    try { watcher?.close(); } catch {}
+    for (const [, p] of pendingRpc) { clearTimeout(p.timer); p.reject(new Error('bridge 停止')); }
+    pendingRpc.clear();
+    return new Promise((resolve) => {
+      for (const ws of wss?.clients ?? []) ws.terminate();
+      wss?.close(() => resolve());
+    });
+  }
+
+  // ---------- 对 MCP / shim 暴露的 API ----------
+
+  return {
+    store,
+    get port() { return wss ? wss.address().port : port; },
+    start, stop,
+    listDevices() {
+      return [...conns].map((c) => ({
+        deviceId: c.device?.id ?? '(未认证)',
+        name: c.device?.name ?? '(未认证)',
+        proto: '1.3',
+        authed: c.authed,
+        pairing: Boolean(c.pair),
+        address: c.ip,
+      }));
+    },
+    pairConfirm,
+    createTool(manifest, files) {
+      const tool = store.create(manifest, files);
+      pushToAuthed(manifest.id, 'watch', { force: true });
+      return tool;
+    },
+    updateTool(id, patch) {
+      const tool = store.update(id, patch);
+      pushToAuthed(id, 'watch', { force: true });
+      return tool;
+    },
+    listTools() {
+      return store.list().map((id) => {
+        const t = store.read(id);
+        return { id, name: t.manifest.name, version: t.manifest.version, files: t.files.length };
+      });
+    },
+    deleteTool(id) {
+      store.remove(id);
+      for (const conn of authedConns()) {
+        conn.sent.delete(id);
+        sendTo(conn, { type: 'delete', toolId: id });
+      }
+    },
+    reload(toolId) {
+      const ids = toolId ? [toolId] : store.list();
+      for (const id of ids) pushToAuthed(id, 'watch', { force: true });
+      return ids;
+    },
+    getLogs({ since = 0, toolId = null, limit = 200 } = {}) {
+      return logs
+        .filter((l) => l.t > since && (!toolId || l.toolId === toolId))
+        .slice(-limit);
+    },
+    rpcCall,
+    waitForLoaded(toolId, timeoutMs) {
+      return new Promise((resolve) => {
+        soakWaiter = { toolId, resolve };
+        setTimeout(() => {
+          if (soakWaiter?.resolve === resolve) { soakWaiter = null; resolve({ ok: false, ms: -1 }); }
+        }, timeoutMs);
+      });
+    },
+  };
+}
+
+module.exports = { createBridge };

package/lib/crypto.js

@@ -0,0 +1,81 @@
+// M2.3 Task 1：同步协议 v1.3 的密码学原语（Node 端，与 App 端 CryptoKit 实现互操作）
+// 密钥派生：X25519 共享密钥 → HKDF-SHA256(ikm=共享密钥, salt=appRand‖srvRand, info, L=64)
+//           → appToServer(前32) ‖ serverToApp(后32)
+// 密文帧：  0x01 ‖ nonce(12B 每帧随机) ‖ AES-256-GCM(ct ‖ tag16)，无 AAD
+'use strict';
+const crypto = require('node:crypto');
+
+const HKDF_INFO = 'hostpad-sync-v1.3';
+const FRAME_MAGIC = 0x01;
+const NONCE_LEN = 12;
+const TAG_LEN = 16;
+
+// x25519 原始密钥的 DER 包装（node crypto 只接受 KeyObject）
+const PKCS8_PREFIX = Buffer.from('302e020100300506032b656e04220420', 'hex');
+const SPKI_PREFIX = Buffer.from('302a300506032b656e032100', 'hex');
+
+/** 生成一次性握手密钥对（X25519） */
+function makeKeyPair() {
+  const { privateKey, publicKey } = crypto.generateKeyPairSync('x25519');
+  return { privateKey, publicKeyRaw: publicKeyRaw(publicKey) };
+}
+
+/** KeyObject 公钥 → 32B 原始表示 */
+function publicKeyRaw(publicKey) {
+  const der = publicKey.export({ format: 'der', type: 'spki' });
+  return Buffer.from(der.subarray(der.length - 32));
+}
+
+/** 原始 32B 公钥 → KeyObject（对端 hello/secure-start 帧里是 base64 原始字节） */
+function publicKeyFromRaw(raw) {
+  if (!Buffer.isBuffer(raw) || raw.length !== 32) {
+    throw new Error('bad peer public key length');
+  }
+  return crypto.createPublicKey({
+    key: Buffer.concat([SPKI_PREFIX, raw]), format: 'der', type: 'spki',
+  });
+}
+
+/** X25519(私钥, 对端公钥原始 32B) → 32B 共享密钥 */
+function sharedSecret(privateKey, peerPublicKeyRaw) {
+  return crypto.diffieHellman({
+    privateKey, publicKey: publicKeyFromRaw(peerPublicKeyRaw),
+  });
+}
+
+/**
+ * HKDF-SHA256 派生双向会话密钥。
+ * salt 固定为 appRand(32) ‖ srvRand(32)（App 的随机量在前，与角色无关）。
+ */
+function deriveKeys(shared, appRand, srvRand) {
+  const okm = Buffer.from(crypto.hkdfSync('sha256',
+    shared, Buffer.concat([appRand, srvRand]), HKDF_INFO, 64));
+  return { appToServer: okm.subarray(0, 32), serverToApp: okm.subarray(32, 64) };
+}
+
+/** JSON 明文 → 密文帧（0x01‖nonce‖ct‖tag） */
+function encryptFrame(key, json) {
+  const nonce = crypto.randomBytes(NONCE_LEN);
+  const cipher = crypto.createCipheriv('aes-256-gcm', key, nonce);
+  const ct = Buffer.concat([cipher.update(json, 'utf8'), cipher.final()]);
+  return Buffer.concat([Buffer.from([FRAME_MAGIC]), nonce, ct, cipher.getAuthTag()]);
+}
+
+/** 密文帧 → JSON 明文；magic/长度/认证任一失败即 throw */
+function decryptFrame(key, frame) {
+  if (!Buffer.isBuffer(frame) || frame.length < 1 + NONCE_LEN + TAG_LEN || frame[0] !== FRAME_MAGIC) {
+    throw new Error('bad frame');
+  }
+  const nonce = frame.subarray(1, 1 + NONCE_LEN);
+  const body = frame.subarray(1 + NONCE_LEN);
+  const ct = body.subarray(0, body.length - TAG_LEN);
+  const tag = body.subarray(body.length - TAG_LEN);
+  const decipher = crypto.createDecipheriv('aes-256-gcm', key, nonce);
+  decipher.setAuthTag(tag);
+  return Buffer.concat([decipher.update(ct), decipher.final()]).toString('utf8');
+}
+
+module.exports = {
+  HKDF_INFO, makeKeyPair, publicKeyRaw, publicKeyFromRaw,
+  sharedSecret, deriveKeys, encryptFrame, decryptFrame,
+};

package/lib/mcp.js

@@ -0,0 +1,92 @@
+// M2.3 Task 5：MCP stdio 服务器——JSON-RPC 2.0（换行分隔 JSON）的最小实现。
+// 只实现 MCP 的核心面：initialize / notifications/* / tools/list / tools/call；
+// 不引 SDK（agent 侧零新增依赖），未知 method → -32601，坏行静默丢弃。
+'use strict';
+
+const SUPPORTED_PROTOCOLS = ['2024-11-05', '2025-03-26', '2025-06-18'];
+const DEFAULT_PROTOCOL = '2024-11-05';
+
+function createMcpServer({ tools, write, serverInfo }) {
+  const info = serverInfo ?? { name: 'hostpad-agent', version: '0.2.0' };
+  const byName = new Map(tools.map((t) => [t.name, t]));
+
+  function respond(msg) { write(JSON.stringify(msg)); }
+
+  async function handleLine(line) {
+    if (typeof line !== 'string' || !line.trim()) return;
+    let f;
+    try { f = JSON.parse(line); } catch { return; }
+    if (f.jsonrpc !== '2.0' || typeof f.method !== 'string') return;
+    const isNotification = f.id === undefined || f.id === null;
+    const id = f.id ?? null;
+
+    try {
+      switch (f.method) {
+        case 'initialize': {
+          const requested = f.params?.protocolVersion;
+          respond({
+            jsonrpc: '2.0', id,
+            result: {
+              protocolVersion: SUPPORTED_PROTOCOLS.includes(requested) ? requested : DEFAULT_PROTOCOL,
+              capabilities: { tools: {} },
+              serverInfo: info,
+            },
+          });
+          return;
+        }
+        case 'tools/list':
+          respond({
+            jsonrpc: '2.0', id,
+            result: {
+              tools: tools.map((t) => ({
+                name: t.name, description: t.description, inputSchema: t.inputSchema,
+              })),
+            },
+          });
+          return;
+        case 'tools/call': {
+          const tool = byName.get(f.params?.name);
+          if (!tool) {
+            if (!isNotification) respond({
+              jsonrpc: '2.0', id,
+              error: { code: -32602, message: `未知工具: ${f.params?.name}` },
+            });
+            return;
+          }
+          let result;
+          try {
+            result = await tool.handler(f.params?.arguments ?? {});
+            respond({
+              jsonrpc: '2.0', id,
+              result: { content: [{ type: 'text', text: JSON.stringify(result ?? null) }] },
+            });
+          } catch (e) {
+            respond({
+              jsonrpc: '2.0', id,
+              result: {
+                isError: true,
+                content: [{ type: 'text', text: `Error: ${e.message}` }],
+              },
+            });
+          }
+          return;
+        }
+        default:
+          // notifications（无 id）不应答，避免对端等回包
+          if (!isNotification) respond({
+            jsonrpc: '2.0', id,
+            error: { code: -32601, message: `method not found: ${f.method}` },
+          });
+      }
+    } catch (e) {
+      if (!isNotification) respond({
+        jsonrpc: '2.0', id,
+        error: { code: -32603, message: `internal error: ${e.message}` },
+      });
+    }
+  }
+
+  return { handleLine };
+}
+
+module.exports = { createMcpServer };

package/lib/ratelimit.js

@@ -0,0 +1,55 @@
+// M2.3 Task 2：配对防暴力原语（内存态，进程重启即清——v1 口径）
+'use strict';
+
+/**
+ * IP 维度失败限速：达到 maxFails 次失败后锁定 lockMs；
+ * 锁定期内新的失败不追加计数（冻结），锁过期自动清零。
+ */
+function createRateLimiter({ maxFails = 5, lockMs = 60_000, now = Date.now } = {}) {
+  const state = new Map(); // ip -> { fails, lockedUntil }
+  return {
+    fail(ip) {
+      const s = state.get(ip) ?? { fails: 0, lockedUntil: 0 };
+      if (s.lockedUntil > now()) return; // 锁内冻结
+      s.fails += 1;
+      if (s.fails >= maxFails) {
+        s.lockedUntil = now() + lockMs;
+        s.fails = 0; // 锁过期后从零计
+      }
+      state.set(ip, s);
+    },
+    isLocked(ip) {
+      const s = state.get(ip);
+      return Boolean(s && s.lockedUntil > now());
+    },
+    failures(ip) {
+      const s = state.get(ip);
+      return s && s.lockedUntil > now() ? 0 : (s?.fails ?? 0);
+    },
+    reset(ip) { state.delete(ip); },
+  };
+}
+
+/**
+ * 配对码：6 位、ttl 内有效、verify 一次性（成功即消费）。
+ * 同一 pairId 重复 issue 覆盖旧码。
+ */
+function createCodeStore({ ttl = 60_000, now = Date.now } = {}) {
+  const codes = new Map(); // pairId -> { code, expiresAt }
+  return {
+    issue(pairId, fixedCode) {
+      const code = fixedCode || String(Math.floor(100000 + Math.random() * 900000));
+      codes.set(pairId, { code, expiresAt: now() + ttl });
+      return code;
+    },
+    verify(pairId, code) {
+      const entry = codes.get(pairId);
+      if (!entry) return false;
+      codes.delete(pairId); // 一次性：无论成败都消费
+      if (now() > entry.expiresAt) return false;
+      return entry.code === String(code).trim();
+    },
+  };
+}
+
+module.exports = { createRateLimiter, createCodeStore };

package/lib/tools.js

@@ -0,0 +1,116 @@
+// M2.3 Task 3：agent 侧工具目录管理。
+// 目录布局 <toolsDir>/<id>/{manifest.json, <files>…}；写走原子替换（tmp+rename）。
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+
+const ID_RE = /^[A-Za-z0-9._-]+$/;
+
+function assertManifest(m) {
+  if (!m || typeof m !== 'object') throw new Error('manifest 必须是对象');
+  for (const key of ['id', 'name', 'version', 'entry']) {
+    if (typeof m[key] !== 'string' || !m[key]) throw new Error(`manifest 缺字段: ${key}`);
+  }
+  if (!ID_RE.test(m.id)) throw new Error(`manifest.id 非法: ${m.id}`);
+}
+
+function assertFilePath(p) {
+  if (typeof p !== 'string' || !p) throw new Error(`非法文件路径: ${p}`);
+  if (path.isAbsolute(p) || p.split('/').includes('..')) throw new Error(`非法文件路径: ${p}`);
+}
+
+function sha256Hex(content) {
+  return crypto.createHash('sha256').update(content, 'utf8').digest('hex');
+}
+
+function writeFileAtomic(file, content) {
+  const tmp = `${file}.tmp-${process.pid}-${Date.now()}`;
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(tmp, content);
+  fs.renameSync(tmp, file);
+}
+
+function createToolStore(toolsDir) {
+  const toolDir = (id) => path.join(toolsDir, id);
+
+  function readRaw(id) {
+    const dir = toolDir(id);
+    if (!fs.existsSync(path.join(dir, 'manifest.json'))) return null;
+    const manifest = JSON.parse(fs.readFileSync(path.join(dir, 'manifest.json'), 'utf8'));
+    const files = [];
+    const walk = (rel) => {
+      for (const name of fs.readdirSync(path.join(dir, rel))) {
+        const relPath = rel ? `${rel}/${name}` : name;
+        const abs = path.join(dir, relPath);
+        if (fs.statSync(abs).isDirectory()) { walk(relPath); continue; }
+        if (relPath === 'manifest.json') continue;
+        files.push({ path: relPath, content: fs.readFileSync(abs, 'utf8') });
+      }
+    };
+    walk('');
+    return { manifest, files };
+  }
+
+  return {
+    dir: toolsDir,
+
+    list() {
+      if (!fs.existsSync(toolsDir)) return [];
+      return fs.readdirSync(toolsDir, { withFileTypes: true })
+        .filter((d) => d.isDirectory() && ID_RE.test(d.name))
+        .map((d) => d.name)
+        .sort();
+    },
+
+    read(id) { return readRaw(id); },
+
+    hashes(id) {
+      const tool = readRaw(id);
+      if (!tool) return {};
+      const h = {};
+      for (const f of tool.files) h[f.path] = sha256Hex(f.content);
+      return h;
+    },
+
+    create(manifest, files) {
+      assertManifest(manifest);
+      if (!Array.isArray(files) || files.length === 0) throw new Error('manifest.entry 需要文件');
+      for (const f of files) assertFilePath(f.path);
+      if (!files.some((f) => f.path === manifest.entry)) throw new Error('manifest.entry 需在 files 中');
+      const dir = toolDir(manifest.id);
+      if (fs.existsSync(path.join(dir, 'manifest.json'))) {
+        throw new Error(`工具已存在: ${manifest.id}`);
+      }
+      fs.mkdirSync(dir, { recursive: true });
+      for (const f of files) writeFileAtomic(path.join(dir, f.path), f.content);
+      writeFileAtomic(path.join(dir, 'manifest.json'), JSON.stringify(manifest, null, 2));
+      return readRaw(manifest.id);
+    },
+
+    update(id, { manifest, files } = {}) {
+      const existing = readRaw(id);
+      if (!existing) throw new Error(`not found: ${id}`);
+      const nextManifest = manifest ? { ...existing.manifest, ...manifest, id } : existing.manifest;
+      assertManifest(nextManifest);
+      if (files) {
+        if (!Array.isArray(files) || files.length === 0) throw new Error('files 不能为空');
+        for (const f of files) assertFilePath(f.path);
+        // 覆盖合并语义：只写传入文件，未提及的保留（agent 常只改一两个文件）
+        const merged = new Map(existing.files.map((f) => [f.path, f.content]));
+        for (const f of files) merged.set(f.path, f.content);
+        if (!merged.has(nextManifest.entry)) throw new Error('manifest.entry 需在 files 中');
+        const dir = toolDir(id);
+        for (const f of files) writeFileAtomic(path.join(dir, f.path), f.content);
+      }
+      writeFileAtomic(path.join(toolDir(id), 'manifest.json'), JSON.stringify(nextManifest, null, 2));
+      return readRaw(id);
+    },
+
+    remove(id) {
+      fs.rmSync(toolDir(id), { recursive: true, force: true });
+    },
+  };
+}
+
+module.exports = { createToolStore };

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "hostpad",
+  "version": "0.2.0",
+  "description": "HostPad 的 MCP 服务器 + iPhone 同步桥：AI agent 经 MCP 管理与调试 iOS 工具（写→推→读日志闭环）",
+  "license": "UNLICENSED",
+  "bin": {
+    "hostpad": "./bin/hostpad.js",
+    "hostpad-dev": "./server.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "server.js"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test test/"
+  },
+  "dependencies": {
+    "ws": "^8.18.0"
+  }
+}

package/server.js

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+// HostPad 开发态同步服务（M1 命令口径不变，内核已换成 lib/bridge.js）
+//
+// 用法：
+//   node server.js                        # 明文开发态：连接即全量同步（免认证）
+//   node server.js --pairing              # 加密 + 配对模式（新设备需 6 位码，在本终端输入确认）
+//   node server.js --pairing --pair-code 123456 --auto-confirm 800   # 自动化配对
+//   node server.js --soak 100             # 压测：push→loaded 100 轮（预算 <1000ms）
+//
+// 正式的 agent 入口是 bin/hostpad.js（MCP 服务器，`npx hostpad`）。
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const readline = require('node:readline');
+const { createBridge } = require('./lib/bridge.js');
+
+const argv = process.argv.slice(2);
+function arg(name, def) {
+  const i = argv.indexOf('--' + name);
+  return i >= 0 && argv[i + 1] && !argv[i + 1].startsWith('--') ? argv[i + 1] : def;
+}
+const TOOLS_DIR = path.resolve(arg('dir', './tools'));
+const PORT = parseInt(arg('port', '8787'), 10);
+const SOAK_N = parseInt(arg('soak', '0'), 10);
+const SOAK_INTERVAL = parseInt(arg('interval', '400'), 10);
+const SOAK_TIMEOUT = parseInt(arg('soak-timeout', '4000'), 10);
+const PAIRING = argv.includes('--pairing');
+const FIXED_CODE = arg('pair-code', null);
+const AUTO_CONFIRM_MS = parseInt(arg('auto-confirm', '0'), 10);
+
+const bridge = createBridge({
+  port: PORT,
+  toolsDir: TOOLS_DIR,
+  statePath: path.join(__dirname, '.hostpad-state.json'),
+  secure: PAIRING,
+  pairCode: FIXED_CODE,
+});
+
+console.log(`[agent] tools=${TOOLS_DIR}`);
+console.log(`[agent] 模式：${PAIRING ? '加密+配对（新设备需 6 位码）' : '明文开发态（免认证）'}`);
+
+// 配对确认：优先自动（固定码），否则终端交互
+let rl = null;
+const stdinWaiters = [];
+function askStdin(prompt) {
+  if (!rl) {
+    rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    rl.on('line', (line) => { const w = stdinWaiters.shift(); if (w) w(line); });
+  }
+  process.stdout.write(prompt);
+  return new Promise((resolve) => stdinWaiters.push(resolve));
+}
+if (PAIRING && AUTO_CONFIRM_MS > 0 && FIXED_CODE) {
+  setInterval(() => {
+    if (bridge.listDevices().some((d) => d.pairing)) bridge.pairConfirm(FIXED_CODE).catch(() => {});
+  }, AUTO_CONFIRM_MS);
+} else if (PAIRING) {
+  setInterval(() => {
+    if (bridge.listDevices().some((d) => d.pairing)) {
+      askStdin('> ').then((line) => bridge.pairConfirm(line).catch((e) => console.log(`[pair] ✗ ${e.message}`)));
+    }
+  }, 500);
+}
+
+bridge.start().then(() => {
+  console.log(`[agent] listening ws://0.0.0.0:${bridge.port}`);
+  console.log('[agent] watching for changes…（改 tools/ 下任意文件即热推送）');
+  if (SOAK_N > 0) runSoak().catch((e) => { console.log('[soak] error', e); process.exit(2); });
+});
+
+// ---------- 压测（M1 验收口径：push→loaded 连续 N 次 0 失败） ----------
+function sleep(ms) { return new Promise((r) => setTimeout(r, ms)); }
+
+async function runSoak() {
+  const dir = bridge.store.list().map((id) => path.join(TOOLS_DIR, id))
+    .find((d) => {
+      try {
+        const m = JSON.parse(fs.readFileSync(path.join(d, 'manifest.json'), 'utf8'));
+        return fs.readFileSync(path.join(d, m.entry), 'utf8').includes('SOAK_MARKER');
+      } catch { return false; }
+    });
+  if (!dir) { console.log('[soak] 没有含 SOAK_MARKER 的工具，无法压测'); process.exit(2); }
+  const manifest = JSON.parse(fs.readFileSync(path.join(dir, 'manifest.json'), 'utf8'));
+  const entryPath = path.join(dir, manifest.entry);
+  const template = fs.readFileSync(entryPath, 'utf8');
+  console.log(`[soak] tool=${manifest.id} cycles=${SOAK_N} interval=${SOAK_INTERVAL}ms timeout=${SOAK_TIMEOUT}ms`);
+  console.log('[soak] 等待 App 连接…');
+  while (bridge.listDevices().filter((d) => d.authed).length === 0) await sleep(200);
+  await sleep(500);
+
+  const results = [];
+  for (let i = 1; i <= SOAK_N; i++) {
+    fs.writeFileSync(entryPath, template.replace(/SOAK_MARKER/g, `#${i}`)); // 触发 watch → push
+    const r = await bridge.waitForLoaded(manifest.id, SOAK_TIMEOUT);
+    results.push(r);
+    console.log(`[soak] ${i}/${SOAK_N} ${r.ok ? `${r.ms}ms` : `FAIL（>${SOAK_TIMEOUT}ms）`}`);
+    await sleep(SOAK_INTERVAL);
+  }
+
+  const ok = results.filter((r) => r.ok).map((r) => r.ms).sort((a, b) => a - b);
+  const fails = results.length - ok.length;
+  const avg = ok.length ? Math.round(ok.reduce((a, b) => a + b, 0) / ok.length) : 0;
+  const p95 = ok.length ? ok[Math.min(ok.length - 1, Math.floor(ok.length * 0.95))] : 0;
+  const max = ok.length ? ok[ok.length - 1] : 0;
+  console.log('\n===== SOAK RESULT =====');
+  console.log(`cycles=${results.length} ok=${ok.length} fail=${fails}（验收线：0 失败）`);
+  console.log(`reload latency: avg=${avg}ms p95=${p95}ms max=${max}ms（预算 <1000ms）`);
+  console.log('=======================');
+  process.exit(fails > 0 ? 1 : 0);
+}