dsh-lan-peers 0.0.0-stage → 0.3.1

package/DESIGN.md

@@ -0,0 +1,150 @@
+# dsh-lan-peers — 局域网 DSH 协同插件 · 设计说明 v0.1
+
+> 两个（或多个）DSH 实例在同一局域网内，完成**一次性配对**后即可互相派发任务并取回结果。
+> 本文是双方实现共同遵守的契约；MVP 只要求两件事：**互认** + **互问**。
+
+## 1. 范围（MVP）
+
+必须做到：
+1. 任一实例可发现/登记对端（先做显式登记 + `/v1/health` 探活，不做 mDNS）。
+2. 通过一次性配对码建立共享密钥，双方各自落盘。
+3. 每次请求双向 HMAC 签名校验（防伪造、防重放、防篡改）。
+4. `lan_peer_ask`：把一段 prompt 发给对端 agent，等它跑完，取回最终回复文本。
+5. 两个工具（模型可见）：`lan_peers`、`lan_peer_ask`。
+
+明确不做（后续版本）：mDNS 自动发现、多跳路由、共享任务板、权限细粒度代理、请求流式输出。
+
+## 2. 术语
+
+- **实例**：一个正在运行的 DSH（instanceId = uuid v4，首次启动生成并持久化）。
+- **对端**：已配对成功的另一实例，含 `peerId / name / baseUrl / secret`。
+- **配对码**：6 位数字 + 10 分钟有效期，一次性。
+
+## 3. 身份与配对
+
+每个实例首次启动生成：
+- `instanceId`（uuid）
+- `selfSecret`（32 字节随机，base64url）——用于自己作为服务端时校验对方？**不需要**；自密钥仅用于记录本机身份。
+- `pairingCode`（按需生成，10 分钟 TTL，用后即焚）
+
+配对流程（A 主动配对 B）：
+1. 在 A 上执行 `lan-peers pair --url http://B:7788 --code 123456 --name B的显示名`。
+2. A → B：`POST /v1/pair`，body `{code, peerId: A.instanceId, peerName: A.name, secret: <A 生成给 B 用的密钥 S>}`。
+3. B 校验 `code`（存在、未过期、未使用），把 `{peerId: A, name, secret: S}` 写入 `peers.json`，返回 `{peerId: B.instanceId, peerName: B.name, secret: <B 生成给 A 用的密钥 T>}`。
+4. A 保存 `{peerId: B, name, baseUrl, secret: T}`。
+5. 之后：A→B 的请求用 `T` 签名；B→A 的请求用 `S` 签名。两把密钥不同，天然双向。
+
+配对码生成：`lan-peers code` → 打印 123456（同时写入状态文件）。
+
+## 4. 请求签名
+
+所有 `/v1/*`（除 `/v1/health`）都必须带：
+
+```
+X-Peer-Id:   <发送方 instanceId>
+X-Peer-Ts:   <毫秒时间戳>
+X-Peer-Nonce: <16 字节随机 hex，单次使用>
+X-Peer-Sign: base64url(HMAC-SHA256(secret, canonical))
+```
+
+`canonical` = 五行，`\n` 连接、无尾随换行：
+
+```
+<METHOD 大写>
+<path，含 query，不含 host>
+<X-Peer-Ts>
+<X-Peer-Nonce>
+<sha256(body) 的 hex；GET 用 sha256("")>
+```
+
+校验方：
+1. `|now - ts| <= 60_000`，否则 401 `clock-skew`。
+2. nonce 在 120s 窗口内未见过（内存 Set + 定期清理），否则 401 `replay`。
+3. 用对应 `secret` 重算签名，`timingSafeEqual` 比对，否则 401 `bad-signature`。
+4. 失败一律返回 `401 {"error": "..."}`，不泄露细节。
+
+## 5. 端点
+
+| 方法 | 路径 | 认证 | 说明 |
+|---|---|---|---|
+| GET | `/v1/health` | 否 | `{name, instanceId, version, capability: ["ask","pair"], peers: <已配对数量>}` |
+| POST | `/v1/pair` | 配对码 | 见 §3 |
+| POST | `/v1/ask` | 是 | body `{requestId, prompt, timeoutSec?}` → `202 {sessionId}` |
+| GET | `/v1/answer?sessionId=<id>` | 是 | `{status: "running"\|"done"\|"error", reply?, error?}` |
+| GET | `/v1/peers` | 是 | `{peers:[{peerId,name,baseUrl}]}`（对端视角） |
+
+`/v1/ask` 语义：
+- 接收方用**专用工作区** `lanPeers.workspace`（默认 `~/.dsh/lan-peers/workspace`）建会话；
+- 会话预设 `lanPeers.agentPreset`（默认 `standard`），权限预设 `lanPeers.permission`（默认 `read-only`）；
+- `allowRemotePrompts`（默认 **false**）为 false 时直接 403 `disabled`；
+- 同一 `requestId` 幂等：重复提交返回同一 sessionId；
+- 超时 `timeoutSec`（默认 300，上限 900）后 `answer` 返回 `error: timeout`。
+
+`/v1/answer` 读取：会话 `turnOutline` 最后一轮的 `response` → `done`；`running` 为 true → `running`。
+
+## 6. 模型可见工具
+
+- `lan_peers`：无参数，返回 `[{name, peerId, online, lastSeen}]`（oneline 探活，2s 超时）。
+- `lan_peer_ask`：参数 `{peer: string, prompt: string, timeoutSec?: number}`，返回 `{peer, status, reply}`；超时返回 `status: "timeout"`，不抛异常中断回合。
+
+工具描述要写明：跨机调用会消耗对端额度，且对方可能拒绝。
+
+## 7. 配置（cordis config）
+
+```yaml
+- id: lan-peers
+  name: dsh-lan-peers
+  config:
+    name: "fn-302"              # 本机显示名
+    listenPort: 7788            # 监听 0.0.0.0
+    stateDir: "~/.dsh/lan-peers"
+    allowRemotePrompts: false   # 默认拒绝远端派单
+    workspace: "~/.dsh/lan-peers/workspace"
+    agentPreset: "standard"
+    permission: "read-only"
+    trustedCidrs: ["192.168.5.0/24"]   # 监听层白名单
+```
+
+## 8. 存储
+
+```
+~/.dsh/lan-peers/
+  state.json     0600  {instanceId, name, createdAt, pairingCode?: {code, expiresAt}}
+  peers.json     0600  {peers: {<peerId>: {name, baseUrl, secret, addedAt, lastSeen}}}
+  workspace/           远端任务会话的工作目录
+```
+
+## 9. 安全默认
+
+- 默认 `allowRemotePrompts: false`，装完不会自动被别人驱动。
+- 远端会话默认 `read-only` 权限 + 专用 workspace，避免对端在你机器上写文件。
+- 只监听局域网网段（`trustedCidrs`），公网 IP 直接拒。
+- 密钥只落 0600 文件，日志不得打印 secret / 签名原文。
+
+## 10. 分工
+
+| 半边 | 负责 | 产出 |
+|---|---|---|
+| **host half**（NAS 端 agent） | 签名校验、配对、`/v1/ask` 建会话、`/v1/answer` 取回复 | `host/` 目录 + 单测 |
+| **client half**（本机） | 签名发送、`lan_peers` / `lan_peer_ask` 工具、`pair` / `code` CLI | `client/` 目录 + 单测 |
+
+两侧共用同一份 `protocol.md`（签名与端点契约），代码不共享。
+
+## 11. 验收用例
+
+1. `GET /v1/health` 无认证 200，`peers` 计数正确。
+2. 错误签名 → 401 `bad-signature`；重放同一 nonce → 401 `replay`；时间偏移 5 分钟 → 401 `clock-skew`。
+3. `allowRemotePrompts=false` 时 `POST /v1/ask` → 403 `disabled`。
+4. 打开开关后 `ask` → 202，轮询 `answer` 直到 `done`，`reply` 非空。
+5. `lan_peer_ask` 工具超时返回 `status: "timeout"`，不抛异常。
+6. 两个实例互相 `pair` 后，各自 `peers.json` 都有对方，且密钥不同。
+
+## 4.1 报文加密（v1）
+
+- 头：X-Peer-Enc: v1
+- 密钥：HKDF-SHA256(secret, salt='dsh-lan-peers/v1', info='dsh-lan-peers/body-encryption/v1') → 32B
+- 算法：AES-256-GCM，随机 12B nonce，报文 = base64url(nonce ‖ ciphertext ‖ tag)
+- 签名对象是明文 JSON：接收方先解密、再验签
+- 响应：{enc:'v1', data:'<base64url>'}，同一方向密钥加密
+- requireEncryption 默认 true：缺 X-Peer-Enc 的认证请求 → 400 encryption-required
+- 未加密：/v1/health（探活）与 /v1/pair（尚无共享密钥，只应在可信局域网配对）

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-lan-peers contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,155 @@
-# Temporary Holding Version
+# 局域网 DSH 协同插件 · dsh-lan-peers
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+让同一局域网内的多个 **DeepSeek Harness (DSH)** 实例互认并协同：一次性配对码建立双向密钥，之后一个 agent 可以直接把任务派给另一个 agent，并取回它的回复。
+
+```
+┌──────────────┐   签名 + AES-256-GCM 加密    ┌──────────────┐
+│  DSH (A)     │ ───────────────────────────▶ │  DSH (B)     │
+│ lan_peer_ask │   POST /v1/ask                │  :7788       │
+│              │ ◀─────────────────────────── │  peer server │
+└──────────────┘   GET  /v1/answer (加密)      └──────────────┘
+```
+
+## 能力
+
+| 面 | 内容 |
+|---|---|
+| 模型工具 | `lan_peers`（列出伙伴 + 在线探测）、`lan_peer_ask`（给伙伴派单并取回结果） |
+| 界面 | Web / 桌面窗口左下角的 **🔗 伙伴** 面板：改设备名、生成临时配对码、添加伙伴 |
+| 认证 | 一次性 6 位配对码（10 分钟、单次），每对伙伴两把独立密钥 |
+| 传输 | HMAC-SHA256 请求签名（±60s 时钟窗 + nonce 防重放），请求与响应体积用 **AES-256-GCM** 加密 |
+| 隔离 | 默认拒绝远端派单；可配 CIDR 白名单；专用工作目录 |
+
+## 环境要求
+
+- DSH `>= 0.2.0-rc.2`（已在 0.2.1-rc.2 的 Node 版与桌面版上验证）
+- Node.js 22 / 24（插件本身无第三方依赖，只用 Node 内置模块）
+
+## 安装
+
+### 1. 装包
+
+```bash
+# 从 tarball（releases 产出的 dsh-lan-peers-x.y.z.tgz）
+dsh plugin --profile web add /path/to/dsh-lan-peers-0.3.0.tgz
+
+# 或本地目录（开发时）
+dsh plugin --profile web add link:/path/to/dsh-lan-peers
+
+# 或发布 registry 之后
+dsh plugin --profile web add dsh-lan-peers
+```
+
+这一步只把包放进 profile 的 `node_modules` 与 `package.json`。
+
+### 2. 必须把插件登记为 profile bundle
+
+**最容易踩的坑**：只写 `cordis.patch.yml` 的插件行，桌面版不会加载（网页版有时会，行为不一致）。把包名加进 profile 的 `dsh.profile.bundles`：
+
+```jsonc
+// ~/.dsh/profiles/web/package.json
+{
+  "dsh": {
+    "profile": {
+      "bundles": [
+        "@deepseek-ai/dsh-base",
+        "@deepseek-ai/dsh-web-app",
+        // …
+        "dsh-lan-peers"       // ← 加这一行
+      ]
+    }
+  }
+}
+```
+
+### 3. 配置
+
+包自带的 `cordis.patch.yml` 会插入一行默认配置（端口 7788、拒绝远端派单）。要改就在 profile 的 `cordis.patch.yml` 里按 id 覆盖：
+
+```yaml
+- id: lan-peers
+  name: dsh-lan-peers
+  config:
+    name: my-nas                  # 显示给伙伴的名字
+    listenPort: 7788              # 监听 0.0.0.0:<port>
+    stateDir: ~/.dsh/lan-peers    # 身份与伙伴表位置
+    workspace: ~/.dsh/lan-peers/workspace   # 远端派单会话的工作目录
+    allowRemotePrompts: false     # 默认关；打开后才接受别人的派单
+    requireEncryption: true       # 默认开；旧版本对端会被拒绝
+    trustedCidrs: ["192.168.5.0/24"]  # 可选，限制来源网段
+    agentPreset: standard
+```
+
+各平台的参考覆盖片段在 `overlays/`：
+
+- `overlays/web.patch.yml` —— 网页版（浏览器访问）
+- `overlays/desktop.patch.yml` —— 桌面版（Electron）
+
+### 4. 重启 DSH
+
+```bash
+# 网页版：重启 dsh web
+# 桌面版：退出并重新打开应用
+```
+
+重启后 `http://<本机IP>:7788/v1/health` 应返回 `{"name":"…","capability":["ask","pair"]}`。
+
+> 桌面版 profile 由 Electron 独占管理，`dsh plugin --profile desktop` 会被拒绝。请按 `overlays/desktop.patch.yml` 手工编辑 `~/.dsh/profiles/desktop/{package.json,cordis.patch.yml}`，然后重启应用。
+
+## 配对
+
+**界面**：左下角 🔗 伙伴 → 「生成配对码」，把 6 位码给对方；对方在「添加伙伴」里填本机地址（如 `192.168.5.51:7788`）+ 码。两个方向各配一次，双方都能主动派单。
+
+**命令行**：
+
+```bash
+npx dsh-lan-peers code  --state-dir ~/.dsh/lan-peers
+npx dsh-lan-peers pair  --url http://192.168.5.51:7788 --code 123456 --name my-nas
+npx dsh-lan-peers peers --probe
+```
+
+## 使用
+
+模型侧（会话里直接说）：
+
+> 用 lan_peer_ask 问 fn-302：`/vol5/main` 下 `pwd` 输出什么？
+
+命令行：
+
+```bash
+npx dsh-lan-peers ask --peer fn-302 "在 /vol5/main 执行 pwd" --timeout 120
+```
+
+对端会在自己的 `workspace` 里建真实会话、由对端模型执行，然后把最终回复加密回传。
+
+## 安全模型
+
+- 配对码 6 位、10 分钟、一次性；每个伙伴两条独立密钥（我签给你的 / 你签给我的）。
+- 每条认证请求验签：五行 canonical、±60s 时钟窗、nonce 防重放、定时安全比较。
+- **报文加密**：`/v1/ask`、`/v1/answer`、`/v1/peers` 的请求体与响应体用 AES-256-GCM 加密，密钥由该方向 HMAC 密钥经 HKDF 派生；缺 `X-Peer-Enc` 的请求返回 `400 encryption-required`。
+- `/v1/health` 公开；`/v1/pair` 因尚无共享密钥仍是明文——**只应在可信局域网内配对**。
+- 管理接口（改名/发码/配对）只在 `/api/lan-peers/*` 且要求 Host 为回环地址，局域网访问 403。
+- `allowRemotePrompts` 默认 `false`：装完不会自动被别人驱动。
+
+## 故障排查
+
+| 现象 | 原因 / 处理 |
+|---|---|
+| 装完没有 7788 监听、日志无输出 | 插件没进 `dsh.profile.bundles`（安装第 2 步） |
+| 启动日志 `is incompatible with dsh …` | 插件 `engines.dsh` 高于本机运行时；升级 DSH 或改 `engines` |
+| `EADDRINUSE ... :7788` | 同机跑了两个 DSH 实例；给其中一个改 `listenPort` |
+| 面板看不到 | 注入只对 HTTP 页面生效；桌面窗口是 `dsh-app://`，走 `lib/client.js` 客户端插件，需重启应用 |
+| `400 encryption-required` | 对端是加密前的旧版本，两端都升级 |
+| `401 bad-signature` / `clock-skew` / `replay` | 两端时钟偏差超过 60s、密钥不一致，或 nonce 重放 |
+
+## 开发
+
+```bash
+node --test host/test/auth.test.mjs host/test/api.test.mjs   # 协议/端点
+node --test lib/wire-crypto.test.mjs                          # 加密
+node host/server.mjs --port 7799 --state-dir /tmp/lp          # 独立 host（内存 runner）
+```
+
+## 许可
+
+MIT

package/client/cli.mjs

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+// dsh-lan-peers — client half CLI.
+//   node cli.mjs code  [--host http://127.0.0.1:7788]
+//   node cli.mjs pair  --url http://PEER:7788 --code 123456 [--name 本机名] [--peer-name 对端名]
+//   node cli.mjs peers [--probe]
+//   node cli.mjs ask   --peer <peerId|name> "prompt" [--timeout 300]
+import crypto from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { newSecret } from './protocol.mjs';
+import { callPeer } from './peer-call.mjs';
+
+const DEFAULT_STATE_DIR = path.join(os.homedir(), '.dsh', 'lan-peers');
+
+function parseArgs(argv) {
+  const out = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg.startsWith('--')) {
+      const key = arg.slice(2);
+      const next = argv[i + 1];
+      if (next === undefined || next.startsWith('--')) out[key] = true;
+      else {
+        out[key] = next;
+        i++;
+      }
+    } else out._.push(arg);
+  }
+  return out;
+}
+
+const stateDir = (args) => path.resolve(args['state-dir'] || DEFAULT_STATE_DIR);
+const readJson = (file, fallback) => {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return fallback;
+  }
+};
+const writeJson = (file, value) => {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(value, null, 2), { mode: 0o600 });
+  fs.renameSync(tmp, file);
+};
+
+function identity(dir) {
+  const file = path.join(dir, 'state.json');
+  const state = readJson(file, {});
+  if (!state.instanceId) {
+    state.instanceId = crypto.randomUUID();
+    state.name = state.name || os.hostname();
+    state.createdAt = new Date().toISOString();
+    writeJson(file, state);
+  }
+  return state;
+}
+
+async function signedCall({ baseUrl, secret, senderId, method = 'GET', apiPath, body }) {
+  return callPeer({ baseUrl, secret, senderId, method, apiPath, body, timeoutMs: 60_000 });
+}
+
+async function cmdCode(args) {
+  // The code lives in state.json, which the host process re-reads; issuing it via
+  // the host CLI keeps one writer instead of racing the running server.
+  const pkgRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+  const out = execFileSync(process.execPath, [
+    path.join(pkgRoot, 'host', 'server.mjs'),
+    '--code',
+    '--state-dir',
+    stateDir(args),
+  ], { encoding: 'utf8' });
+  const match = /(\d{6})/.exec(out);
+  if (!match) throw new Error(out.trim() || 'no pairing code');
+  console.log(`配对码: ${match[1]}   有效期: 10 分钟，一次性`);
+  console.log(`对方把它填进「添加伙伴」里即可配对（地址填本机 http://<ip>:7788）`);
+}
+
+async function cmdPair(args) {
+  const dir = stateDir(args);
+  const me = identity(dir);
+  const url = String(args.url || '').replace(/\/$/, '');
+  const code = String(args.code || '');
+  const name = String(args.name || me.name || os.hostname());
+  if (!url || !code) throw new Error('用法: pair --url http://PEER:7788 --code 123456 [--name 本机名]');
+
+  const secret = newSecret();
+  const res = await fetch(`${url}/v1/pair`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ code, peerId: me.instanceId, peerName: name, secret }),
+  });
+  const body = await res.json();
+  if (!res.ok) throw new Error(`配对失败: ${res.status} ${body.error || ''}`.trim());
+
+  const peersFile = path.join(dir, 'peers.json');
+  const store = readJson(peersFile, { peers: {} });
+  const previous = store.peers[body.peerId] || {};
+  // Two secrets per peer: `secret` is what the peer issued to us (we sign with
+  // it), `inboundSecret` is what we issued to the peer (we verify with it).
+  // Keeping both is what makes the pairing mutual in both directions.
+  store.peers[body.peerId] = {
+    ...previous,
+    name: args['peer-name'] || body.peerName || body.peerId,
+    baseUrl: url,
+    secret: body.secret,
+    inboundSecret: secret,
+    addedAt: previous.addedAt || new Date().toISOString(),
+  };
+  writeJson(peersFile, store);
+  console.log(`已配对: ${store.peers[body.peerId].name} (${body.peerId})`);
+}
+
+async function cmdPeers(args) {
+  const dir = stateDir(args);
+  const store = readJson(path.join(dir, 'peers.json'), { peers: {} });
+  const entries = Object.entries(store.peers || {});
+  if (entries.length === 0) {
+    console.log('（尚未配对任何对端）');
+    return;
+  }
+  for (const [peerId, peer] of entries) {
+    let status = 'unknown';
+    if (args.probe) {
+      try {
+        const res = await fetch(`${peer.baseUrl}/v1/health`, { signal: AbortSignal.timeout(2000) });
+        status = res.ok ? 'online' : `http ${res.status}`;
+      } catch {
+        status = 'offline';
+      }
+    }
+    console.log(`${peer.name}\t${peer.baseUrl}\t${peerId}\t${status}`);
+  }
+}
+
+async function cmdAsk(args) {
+  const dir = stateDir(args);
+  const me = identity(dir);
+  const prompt = args._.join(' ').trim();
+  if (!args.peer || !prompt) throw new Error('用法: ask --peer <peerId|name> "prompt"');
+  const store = readJson(path.join(dir, 'peers.json'), { peers: {} });
+  const match = Object.entries(store.peers || {}).find(
+    ([peerId, peer]) => peerId === args.peer || peer.name === args.peer,
+  );
+  if (!match) throw new Error(`未知对端: ${args.peer}`);
+  const [peerId, peer] = match;
+
+  const requestId = `req-${crypto.randomUUID()}`;
+  const accepted = await signedCall({
+    baseUrl: peer.baseUrl,
+    secret: peer.secret,
+    senderId: me.instanceId,
+    method: 'POST',
+    apiPath: '/v1/ask',
+    body: { requestId, prompt, timeoutSec: Number(args.timeout || 300) },
+  });
+  const sessionId = accepted.sessionId;
+  process.stderr.write(`已派单 → ${peer.name} (session ${sessionId})\n`);
+
+  const deadline = Date.now() + Number(args.timeout || 300) * 1000;
+  const started = Date.now();
+  while (Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, 1500));
+    const answer = await signedCall({
+      baseUrl: peer.baseUrl,
+      secret: peer.secret,
+      senderId: me.instanceId,
+      method: 'GET',
+      apiPath: `/v1/answer?sessionId=${encodeURIComponent(sessionId)}`,
+    });
+    process.stderr.write('.');
+    if (answer.status === 'done') {
+      process.stderr.write('\n');
+      console.log(answer.reply);
+      return;
+    }
+    if (answer.status === 'error') {
+      process.stderr.write('\n');
+      throw new Error(`对端返回错误: ${answer.error}`);
+    }
+  }
+  console.log(`timeout after ${Math.round((Date.now() - started) / 1000)}s`);
+  process.exitCode = 2;
+}
+
+const commands = { code: cmdCode, pair: cmdPair, peers: cmdPeers, ask: cmdAsk };
+
+const args = parseArgs(process.argv.slice(2));
+const command = commands[args._[0]];
+if (!command) {
+  console.error('用法: cli.mjs <code|pair|peers|ask> [options]');
+  process.exit(1);
+}
+args._ = args._.slice(1);
+command(args).catch((error) => {
+  console.error(String(error.message || error));
+  process.exit(1);
+});

package/client/peer-call.mjs

@@ -0,0 +1,50 @@
+// dsh-lan-peers · one signed + encrypted peer call.
+//
+// The signature covers the *plaintext* JSON body (so the host can verify after
+// decrypting), while the wire carries only AES-256-GCM ciphertext. Replay and
+// clock checks still ride on the ts/nonce inside the canonical string.
+import { ENC_VERSION, decryptJson, encryptBytes } from '../lib/wire-crypto.mjs';
+import { canonical, newNonce, sign } from './protocol.mjs';
+
+export async function callPeer({
+  baseUrl,
+  secret,
+  senderId,
+  method = 'GET',
+  apiPath,
+  body,
+  timeoutMs = 30_000,
+}) {
+  const plain = body === undefined ? Buffer.alloc(0) : Buffer.from(JSON.stringify(body));
+  const ts = Date.now();
+  const nonce = newNonce();
+  const signature = sign(secret, canonical(method, apiPath, ts, nonce, plain));
+  const wire = plain.length ? Buffer.from(encryptBytes(secret, plain), 'utf8') : Buffer.alloc(0);
+
+  const res = await fetch(new URL(apiPath, baseUrl).toString(), {
+    method,
+    headers: {
+      'Content-Type': plain.length ? 'application/octet-stream' : 'application/json',
+      'X-Peer-Id': senderId,
+      'X-Peer-Ts': String(ts),
+      'X-Peer-Nonce': nonce,
+      'X-Peer-Sign': signature,
+      'X-Peer-Enc': ENC_VERSION,
+    },
+    body: wire.length ? wire : undefined,
+    signal: AbortSignal.timeout(timeoutMs),
+  });
+
+  const text = await res.text();
+  let json;
+  try {
+    json = JSON.parse(text);
+  } catch {
+    throw new Error(`HTTP ${res.status}: ${text.slice(0, 120)}`);
+  }
+  if (json && json.enc === ENC_VERSION && typeof json.data === 'string') {
+    json = decryptJson(secret, json.data);
+  }
+  if (!res.ok) throw new Error(`${res.status} ${json?.error || ''}`.trim());
+  return json;
+}

package/client/protocol.mjs

@@ -0,0 +1,56 @@
+// dsh-lan-peers — wire protocol helpers (client half).
+// The contract lives in DESIGN.md §4: a five-line canonical string signed with
+// HMAC-SHA256 over a per-peer secret, base64url encoded.
+import crypto from 'node:crypto';
+
+export const MAX_SKEW_MS = 60_000;
+export const NONCE_TTL_MS = 120_000;
+
+export const sha256Hex = (buf) => crypto.createHash('sha256').update(buf).digest('hex');
+
+/** Canonical string: METHOD \n PATH \n TS \n NONCE \n sha256hex(body). */
+export function canonical(method, path, ts, nonce, body) {
+  return [method.toUpperCase(), path, String(ts), nonce, sha256Hex(body ?? Buffer.alloc(0))].join('\n');
+}
+
+/** HMAC-SHA256(secret, canonical) as base64url. The host half keys with the
+ * secret's UTF-8 bytes by default (DESIGN §4 + server config
+ * `secretKeyEncoding`), so the client must do the same. */
+export function sign(secret, canonicalString) {
+  return crypto
+    .createHmac('sha256', Buffer.from(secret, 'utf8'))
+    .update(canonicalString, 'utf8')
+    .digest('base64url');
+}
+
+export function newSecret() {
+  return crypto.randomBytes(32).toString('base64url');
+}
+
+export function newNonce() {
+  return crypto.randomBytes(16).toString('hex');
+}
+
+/** Constant-time comparison of two base64url signatures. */
+export function sameSignature(a, b) {
+  const left = Buffer.from(a, 'utf8');
+  const right = Buffer.from(b, 'utf8');
+  return left.length === right.length && crypto.timingSafeEqual(left, right);
+}
+
+/**
+ * Verify an inbound request the way the host half must. Returns null when the
+ * request is valid, otherwise a short reason code.
+ */
+export function verifyRequest({ method, path, ts, nonce, body, signature, secret, seenNonces = new Map(), now = Date.now() }) {
+  const stamp = Number(ts);
+  if (!Number.isFinite(stamp) || Math.abs(now - stamp) > MAX_SKEW_MS) return 'clock-skew';
+  if (typeof nonce !== 'string' || nonce.length < 8) return 'bad-nonce';
+  const seenAt = seenNonces.get(nonce);
+  if (seenAt !== undefined && now - seenAt <= NONCE_TTL_MS) return 'replay';
+  const expected = sign(secret, canonical(method, path, stamp, nonce, body));
+  if (!sameSignature(expected, signature ?? '')) return 'bad-signature';
+  seenNonces.set(nonce, now);
+  for (const [key, at] of seenNonces) if (now - at > NONCE_TTL_MS) seenNonces.delete(key);
+  return null;
+}