dsh-mobile-plugin 0.5.23 → 0.5.26

package/lib/mobile/sync-inbox-store.js

@@ -0,0 +1,181 @@
+'use strict';
+
+/**
+ * 同步收件箱：按 `instanceId` 存密文记录的磁盘小仓库（`$DSH_HOME/storages/mobile-plugin/sync-inbox.json`）。
+ *
+ * 每台电脑给「共享同步组」当一次中转点：别的手机把一条条**已用 SGK 加密**的记录写进来，本机
+ * 只存不读、看不懂内容。记录的形状是 `{ cid, blob, createdAt }`：`cid` 是内容标识（去重键），
+ * `blob` 是 base64 的密文，`createdAt` 由本仓库在写入时打上。
+ *
+ * 三条限制决定了它是一个「短时邮箱」而不是数据库：
+ *  · **TTL 24 小时**：过期的记录在读写时顺手清掉。同步只在手机回前台时跑一次，一天足够；
+ *    再久的记录没有意义，留着只会让文件慢慢变大。
+ *  · **单条 blob 上限 8KB**：记录只是「设备清单的一项 / 一条删除指令」，本该很小；超过这个量
+ *    说明写错了东西，整条拒收。
+ *  · **单次最多 16 条**：一次同步一批设备，超过就该分批。
+ *
+ * 落盘口径照 `mobile-stats.json` 那一套：整份读、整份原子写（临时文件 + rename）。**读坏文件
+ * 时 write 绝不覆盖**——那会把盘上还没发出去的记录静默清空；读失败只有 `read()` 退化成空表。
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { dshHome } = require('../shared/paths');
+
+/** 文件格式版本：将来改结构时据此决定丢弃还是迁移。 */
+const VERSION = 1;
+
+/** 记录存活上限：24 小时。 */
+const TTL_MS = 24 * 60 * 60 * 1000;
+
+/** 单条 blob（base64 密文串）的字节上限。 */
+const MAX_BLOB_BYTES = 8 * 1024;
+
+/** 单次写入最多接收的记录条数。 */
+const MAX_RECORDS_PER_WRITE = 16;
+
+/** cid 的长度上限：它只是去重键，不拼路径，但也不该是无限长的串。 */
+const MAX_CID_LEN = 200;
+
+/**
+ * 单实例最多留多少条：TTL 已经把它压到一天的量，这一道只是文件体积的兜底（超了丢最老的）。
+ * 一条 8KB 封顶时，512 条约 4MB，仍可接受。
+ */
+const MAX_STORED_PER_INSTANCE = 512;
+
+/** 收件箱文件：跟其它移动端插件状态放同一个目录（`storages/mobile-plugin/`）。 */
+function defaultFile() {
+  return path.join(dshHome(), 'storages', 'mobile-plugin', 'sync-inbox.json');
+}
+
+/**
+ * 建一个收件箱 store。默认读 `defaultFile()` 的真实时钟；测试可注入 `file` / `now` / `ttlMs`。
+ *
+ * @param {object} [options]
+ * @param {string} [options.file]        落盘文件（测试用）
+ * @param {() => number} [options.now]   当前时刻的取值器
+ * @param {number} [options.ttlMs]       记录存活时长
+ */
+function createSyncInboxStore(options = {}) {
+  const now = typeof options.now === 'function' ? options.now : Date.now;
+  const ttlMs = Number.isFinite(options.ttlMs) && options.ttlMs > 0 ? options.ttlMs : TTL_MS;
+  const file = options.file || defaultFile();
+
+  /** 读盘并解析。文件不存在 → 空库；存在但读不懂 → 抛错（write 会用它，绝不能吞成空库）。 */
+  function readRaw() {
+    let text;
+    try {
+      text = fs.readFileSync(file, 'utf8');
+    } catch (error) {
+      if (error && error.code === 'ENOENT') return { version: VERSION, instances: {} };
+      throw error;
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(text);
+    } catch (error) {
+      throw Object.assign(new Error(`同步收件箱文件已损坏：${error.message}`), { code: 'sync-inbox-corrupt' });
+    }
+    if (!parsed || typeof parsed !== 'object' || !parsed.instances || typeof parsed.instances !== 'object') {
+      throw Object.assign(new Error('同步收件箱文件形状不对'), { code: 'sync-inbox-corrupt' });
+    }
+    return parsed;
+  }
+
+  /** 只留形状对、未过期的记录。 */
+  function prune(list) {
+    const cutoff = now() - ttlMs;
+    return list.filter((record) => (
+      record
+      && typeof record === 'object'
+      && typeof record.cid === 'string'
+      && typeof record.blob === 'string'
+      && Number.isFinite(record.createdAt)
+      && record.createdAt > cutoff
+    ));
+  }
+
+  /** 原子写：先临时文件再 rename，写一半断电也不留半份 JSON。 */
+  function save(db) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(db), { mode: 0o600 });
+    fs.renameSync(tmp, file);
+  }
+
+  /**
+   * 读某实例的记录：`since` 之后、未过期的，按 `createdAt` 升序。
+   * 读盘失败按空表（首页拉不到不该把同步引擎整个卡死）。
+   *
+   * @param {string} instanceId
+   * @param {number} [since] 毫秒时间戳，只取严格晚于它的记录
+   * @returns {Array<{cid: string, blob: string, createdAt: number}>}
+   */
+  function read(instanceId, since) {
+    let db;
+    try {
+      db = readRaw();
+    } catch {
+      return [];
+    }
+    const list = Array.isArray(db.instances[String(instanceId || '')]) ? db.instances[String(instanceId || '')] : [];
+    const sinceMs = Number.isFinite(since) && since > 0 ? since : 0;
+    return prune(list)
+      .filter((record) => record.createdAt > sinceMs)
+      .sort((a, b) => a.createdAt - b.createdAt)
+      .map((record) => ({ cid: record.cid, blob: record.blob, createdAt: record.createdAt }));
+  }
+
+  /**
+   * 写一批记录：按 cid 去重、裁掉越界 / 过期的，返回被接收的 cid 列表。
+   *
+   * **读坏文件会抛错、不覆盖**：盘上那份可能还有别的手机没取走的东西，绝不能当成空库重写。
+   *
+   * @param {string} instanceId
+   * @param {Array<{cid: string, blob: string}>} records
+   * @returns {string[]} 接收到的 cid（重复的也算「已在库里」）
+   */
+  function write(instanceId, records) {
+    const db = readRaw();
+    const id = String(instanceId || '');
+    const byCid = new Map(prune(Array.isArray(db.instances[id]) ? db.instances[id] : []).map((r) => [r.cid, r]));
+    const accepted = [];
+    const at = now();
+    let added = 0;
+    for (const record of Array.isArray(records) ? records : []) {
+      if (!record || typeof record !== 'object') continue;
+      const cid = typeof record.cid === 'string' ? record.cid : '';
+      const blob = typeof record.blob === 'string' ? record.blob : '';
+      if (!cid || cid.length > MAX_CID_LEN || !blob) continue;
+      if (Buffer.byteLength(blob, 'utf8') > MAX_BLOB_BYTES) continue;
+      if (byCid.has(cid)) {
+        accepted.push(cid);
+        continue;
+      }
+      if (added >= MAX_RECORDS_PER_WRITE) break;
+      byCid.set(cid, { cid, blob, createdAt: at });
+      accepted.push(cid);
+      added += 1;
+    }
+    let list = [...byCid.values()].sort((a, b) => a.createdAt - b.createdAt);
+    if (list.length > MAX_STORED_PER_INSTANCE) list = list.slice(list.length - MAX_STORED_PER_INSTANCE);
+    db.version = VERSION;
+    db.instances[id] = list;
+    save(db);
+    return accepted;
+  }
+
+  return { read, write };
+}
+
+module.exports = {
+  createSyncInboxStore,
+  defaultFile,
+  VERSION,
+  TTL_MS,
+  MAX_BLOB_BYTES,
+  MAX_RECORDS_PER_WRITE,
+  MAX_CID_LEN,
+  MAX_STORED_PER_INSTANCE,
+};

package/lib/mobile/sync.js

@@ -0,0 +1,124 @@
+'use strict';
+
+/**
+ * 设备批量同步的两组接口（`/api/mobile/v1/sync/*`，见 docs/device-batch-sync.md）。
+ *
+ *  · `POST /sync/tickets` —— 已配对的设备替同步组里将来新增的手机申领一次性入场券，连同这台
+ *    电脑的概况（名字 / 实例号 / 中转地址 / 直连候选 …）一起回给导出方，拼进二维码。
+ *  · `POST /sync/inbox` —— 别的手机把 SGK 加密的记录写进本机收件箱。
+ *  · `GET  /sync/inbox` —— 取 `since` 之后、未过期的记录。
+ *
+ * 宿主只存不读收件箱：它不认识 SGK、解不开 blob。真正的内容加解密、去重与「哪条该做什么」
+ * 全在手机上（见契约的「自动同步」节）。这里只做两件事：发券、存取密文。
+ *
+ * 三个 handler 都要求已配对（路由表里走 `guarded`），否则任何人都能领走配对资格、或往这台
+ * 电脑的收件箱塞东西。
+ */
+
+const { sendJson, readJsonBody } = require('../shared/http-util');
+const { MAX_RECORDS_PER_WRITE } = require('./sync-inbox-store.js');
+
+/**
+ * 构造同步那组 handler。依赖由移动端路由表装配时注入。
+ *
+ * @param {object} deps
+ * @param {object} deps.state           宿主状态（instanceId / name / relayUrl / lanEnabled …）
+ * @param {object} deps.ticketStore     一次性券表（transfer-tickets.js）
+ * @param {object} deps.inboxStore      同步收件箱 store（sync-inbox-store.js）
+ * @param {(port: number) => Array<object>} [deps.safeLanCandidates] 直连候选（与 /connection-info 同一份）
+ * @param {(port: number) => Array<object>} [deps.safeIpv6Candidates] IPv6 直连候选
+ * @param {() => number} [deps.lanPortInUse] 宿主实绑的直连端口
+ * @param {() => string} [deps.hostPlatform] 宿主系统标识
+ * @param {(message: string) => void} [deps.log]
+ */
+function createSyncHandlers(deps = {}) {
+  const state = deps.state || {};
+  const ticketStore = deps.ticketStore || null;
+  const inboxStore = deps.inboxStore || null;
+  const log = typeof deps.log === 'function' ? deps.log : () => {};
+  const instanceIdOf = () => String(state.instanceId || '');
+
+  /** 这台电脑给手机的概况：新手机配对前靠它知道对面是谁、该往哪拨。 */
+  function hostSummary() {
+    const port = typeof deps.lanPortInUse === 'function' ? deps.lanPortInUse() : state.lanPort;
+    // 直连候选与 /connection-info、/pair 那份同口径：关掉局域网直连时两份都为空。
+    const lanUrls = state.lanEnabled && typeof deps.safeLanCandidates === 'function'
+      ? deps.safeLanCandidates(port).map((candidate) => candidate && candidate.url).filter(Boolean)
+      : [];
+    const ipv6Candidates = state.lanEnabled && typeof deps.safeIpv6Candidates === 'function'
+      ? deps.safeIpv6Candidates(port).map((candidate) => candidate && candidate.url).filter(Boolean)
+      : [];
+    const hostPlatform = typeof deps.hostPlatform === 'function' ? deps.hostPlatform() : (state.hostPlatform || process.platform);
+    return {
+      name: state.name || '',
+      instanceId: instanceIdOf(),
+      // 券只能走协议 v2 的 sealed 配对，所以这里报协议 2。
+      proto: 2,
+      relayUrl: state.enabled ? (state.relayUrl || null) : null,
+      lanUrls,
+      ipv6Candidates,
+      hostPlatform,
+    };
+  }
+
+  /** POST /sync/tickets：申领一次性入场券（count 默认 1、封顶 8）。 */
+  async function handleMintTickets(_ctx, req, res) {
+    if (req.method !== 'POST') { sendJson(res, 405, { ok: false, error: 'method not allowed' }); return; }
+    if (!ticketStore) { sendJson(res, 503, { ok: false, error: 'ticket store unavailable' }); return; }
+    // 空体是合法的（count 缺省 1）；读不懂 / 太大也按空对象、让 count 走默认，不因多要一个字段就失败。
+    const body = (await readJsonBody(req, 16 * 1024)) || {};
+    const tickets = ticketStore.mint(instanceIdOf(), body && body.count, {
+      ttlMs: body && body.ttlMs,
+      reusable: body && body.reusable,
+    });
+    sendJson(res, 200, { ok: true, host: hostSummary(), tickets });
+  }
+
+  /** POST /sync/inbox：写入一批密文记录，回被接收的 cid 列表。 */
+  async function handleInboxWrite(_ctx, req, res) {
+    if (!inboxStore) { sendJson(res, 503, { ok: false, error: 'inbox store unavailable' }); return; }
+    const body = await readJsonBody(req);
+    if (!body || !Array.isArray(body.records)) {
+      sendJson(res, 400, { ok: false, error: 'records 必须是数组' });
+      return;
+    }
+    if (body.records.length > MAX_RECORDS_PER_WRITE) {
+      sendJson(res, 400, { ok: false, error: `单次最多写 ${MAX_RECORDS_PER_WRITE} 条记录` });
+      return;
+    }
+    let accepted;
+    try {
+      accepted = inboxStore.write(instanceIdOf(), body.records);
+    } catch (error) {
+      // 读坏盘时 store 会抛错（绝不覆盖已有记录）；这里是那条错误落到请求上的地方。
+      log('sync inbox write failed:', error && error.message);
+      sendJson(res, 500, { ok: false, error: 'internal error' });
+      return;
+    }
+    sendJson(res, 200, { ok: true, accepted });
+  }
+
+  /** GET /sync/inbox?since=<ms>：取 `since` 之后、未过期的记录。 */
+  async function handleInboxRead(_ctx, req, res) {
+    if (!inboxStore) { sendJson(res, 503, { ok: false, error: 'inbox store unavailable' }); return; }
+    let since = 0;
+    try {
+      const query = new URL(req.url || '/', 'http://x').searchParams.get('since');
+      if (query !== null) since = Number(query);
+    } catch { /* 畸形 URL 当 since=0，返回全部未过期的 */ }
+    if (!Number.isFinite(since) || since < 0) since = 0;
+    const records = inboxStore.read(instanceIdOf(), since);
+    sendJson(res, 200, { ok: true, records });
+  }
+
+  /** 同一条路径上按 method 分派写 / 读（宿主 webServer 一个路径只能挂一个 handler）。 */
+  async function handleInbox(ctx, req, res) {
+    if (req.method === 'POST') return handleInboxWrite(ctx, req, res);
+    if (req.method === 'GET') return handleInboxRead(ctx, req, res);
+    sendJson(res, 405, { ok: false, error: 'method not allowed' });
+  }
+
+  return { handleMintTickets, handleInbox, handleInboxWrite, handleInboxRead };
+}
+
+module.exports = { createSyncHandlers };

package/lib/mobile/transfer-tickets.js

@@ -0,0 +1,107 @@
+'use strict';
+
+/**
+ * 一次性入场券（transfer ticket）的进程内 TTL 表。
+ *
+ * 设备批量导入/导出时，手机 A 向某台电脑申领一张入场券，塞进二维码交给手机 B；B 拿这张券
+ * 走一次正常配对（`/pair` 带 `ticketId`），配对成功券即作废。券的内容与配对票据同一种原语
+ * （32 字节 base64url，用来派生 pairKey），但**不进 state、不落盘**——它只活在这台电脑的内存
+ * 里、只活很短一段时间（默认 10 分钟）。
+ *
+ * 为什么一次性 + 短 TTL：券等价于「可以跟这台电脑配一次对」的资格。二维码要在屏幕上长显，
+ * 截图 / 偷看都可能发生；配对成功立刻 `consume`，同一张券就配不了第二台手机；短 TTL 让一张
+ * 没被用掉的券自己过期。这是拿「可用窗口」换「被截屏后的暴露面」的取舍：窗口之外，即使券
+ * 泄露也换不到任何东西。
+ *
+ * 进程内表：插件重载即清空——券本来就是为了下一次配对临时生成的，没配上的重扫一张新的即可。
+ */
+
+const crypto = require('node:crypto');
+
+/** 默认有效期：10 分钟。够用户扫完码、走完配对，又不至于让一张漏出去的券长期可用。 */
+const DEFAULT_TTL_MS = 10 * 60 * 1000;
+
+/** 单次最多发几张：一张码换一台新手机，一次导出最多扩 8 台，再多该分批或先看是不是刷券。 */
+const MAX_COUNT = 8;
+
+/** 单张券有效期上限（24 小时）：自动同步收件箱里的券要活到后开 App 的手机来取，封顶一天。 */
+const MAX_TTL_MS = 24 * 60 * 60 * 1000;
+
+/** 键的分隔符：instanceId 与 ticketId 都来自内部生成，用不可见字符只为拼出唯一键。 */
+const SEP = '\u0000';
+
+/**
+ * 建一张券表。默认用真实时钟与 10 分钟 TTL；测试可注入 `now` / `ttlMs` 观察过期。
+ *
+ * @param {object} [options]
+ * @param {number} [options.ttlMs]  券的有效期（毫秒）
+ * @param {() => number} [options.now] 当前时刻的取值器（测试用）
+ */
+function createTransferTickets(options = {}) {
+  const now = typeof options.now === 'function' ? options.now : Date.now;
+  const ttlMs = Number.isFinite(options.ttlMs) && options.ttlMs > 0 ? options.ttlMs : DEFAULT_TTL_MS;
+
+  /** 键 → { ticket, expiresAt }。键把实例号也编进去：两张不同宿主的券不会互相顶掉。 */
+  const table = new Map();
+  const keyOf = (instanceId, ticketId) => `${String(instanceId || '')}${SEP}${ticketId}`;
+
+  /**
+   * 发券：返回 [{ ticket, ticketId }]，`count` 默认 1、封顶 `MAX_COUNT`。
+   *
+   * `opts.ttlMs` 覆盖单张券的有效期（封顶 `MAX_TTL_MS`）；`opts.reusable` 为真时这张券
+   * **可被多台手机各用一次、配对成功后不作废**（到期才失效）。两种券用途不同：
+   *  · 导出二维码里的是**一次性短券**（默认），防截图；
+   *  · 自动同步收件箱里的是**可复用长券**（24h 内多台组内手机各领一次），因为它只经 SGK
+   *    密文投递、不暴露给外人，短 TTL 反而会让后开 App 的手机永远配不上、多台手机只有
+   *    第一台抢得到。
+   */
+  function mint(instanceId, count, opts = {}) {
+    prune();
+    const n = Number.isInteger(count) && count > 0 ? Math.min(count, MAX_COUNT) : 1;
+    const wantTtl = Number.isFinite(opts.ttlMs) && opts.ttlMs > 0 ? opts.ttlMs : ttlMs;
+    const life = Math.min(wantTtl, MAX_TTL_MS);
+    const reusable = opts.reusable === true;
+    const issued = [];
+    const expiresAt = now() + life;
+    for (let i = 0; i < n; i += 1) {
+      const ticket = crypto.randomBytes(32).toString('base64url');
+      const ticketId = crypto.randomBytes(16).toString('base64url');
+      table.set(keyOf(instanceId, ticketId), { ticket, expiresAt, reusable });
+      issued.push({ ticket, ticketId });
+    }
+    return issued;
+  }
+
+  /** 取券：不存在或已过期都返回 null（过期的顺手清掉）。 */
+  function resolve(instanceId, ticketId) {
+    if (typeof ticketId !== 'string' || !ticketId) return null;
+    const key = keyOf(instanceId, ticketId);
+    const entry = table.get(key);
+    if (!entry) return null;
+    if (entry.expiresAt <= now()) {
+      table.delete(key);
+      return null;
+    }
+    return entry.ticket;
+  }
+
+  /** 用掉一张券：一次性券直接删除；可复用券不动它（到期由 prune 清）。 */
+  function consume(instanceId, ticketId) {
+    if (typeof ticketId !== 'string' || !ticketId) return;
+    const key = keyOf(instanceId, ticketId);
+    const entry = table.get(key);
+    if (entry && entry.reusable) return;
+    table.delete(key);
+  }
+
+  /** 清掉所有过期券；每次 mint / 可在别处定期调用。 */
+  function prune(at = now()) {
+    for (const [key, entry] of table) {
+      if (entry.expiresAt <= at) table.delete(key);
+    }
+  }
+
+  return { mint, resolve, consume, prune, size: () => table.size };
+}
+
+module.exports = { createTransferTickets, DEFAULT_TTL_MS, MAX_COUNT };

package/lib/mobile/wechat.js

@@ -426,6 +426,27 @@ function mediaTypeOf(name, bytes) {
   return 'image/png';
 }
 
+/**
+ * HTTP 那条路上，图片只留 `{name, base64}` 两个字段 —— `path`（以及任何路径形式的字段）一律剥掉。
+ *
+ * 为什么 HTTP 这条路不收 path：这个请求来自手机，手机口中的「本机路径」指的是手机上的文件；
+ * 宿主却跑在另一台电脑上，照着这个名字去读，读到的是电脑上同名的任意文件 —— 一次保存就顺走
+ * 了宿主机上任何一张图。工具那一侧不经过这里：模型自己有读盘权，给的路径本来就该能读，所以
+ * `writeArticle` / `mediaBytesOf` 的 path 能力原样保留。
+ *
+ * 只认 name 与 base64，别的字段（path、filePath、localPath、src……）自然全丢；`images` 不是
+ * 数组、项不是对象都按「没给」处理，不抛。name 合不合规矩交给 `writeArticle` 现有的拒绝逻辑。
+ */
+function httpImagesOnly(images) {
+  if (!Array.isArray(images)) return [];
+  const out = [];
+  for (const item of images) {
+    if (!isRecord(item)) continue;
+    out.push({ name: item.name, base64: item.base64 });
+  }
+  return out;
+}
+
 /**
  * `POST /wechat/article` —— 写一篇（App 侧目前不用，留给「在手机上删 / 改名」这类动作；
  * AI 那条路走的是工具，见 `tools.js`）。
@@ -433,8 +454,10 @@ function mediaTypeOf(name, bytes) {
 async function handleArticleWrite(_ctx, req, res) {
   const body = await readJsonBody(req, 8 * 1024 * 1024);
   if (!isRecord(body)) return fail(res, 400, 'bad-request', '请求体不是对象。');
+  // 只让 HTTP 入口不收 path：图片只留 {name, base64}（见 httpImagesOnly）。
+  const input = { ...body, images: httpImagesOnly(body.images) };
   try {
-    const { article } = await writeArticle(body);
+    const { article } = await writeArticle(input);
     sendJson(res, 200, {
       ok: true,
       id: article.id,
@@ -479,6 +502,8 @@ module.exports = {
   handleArticleDelete,
   // 工具那一侧直接用这几个（不经过 HTTP）
   writeArticle,
+  // 纯函数：HTTP 入口剥 path 用，单独导出便于直接测
+  httpImagesOnly,
   readArticle,
   listArticles,
   plainTextOf,

package/lib/p2p/rendezvous.cjs

@@ -0,0 +1,106 @@
+'use strict';
+
+/**
+ * 点对点隧道的**会合**：手机把自己的打洞候选报上来，电脑按它把自己那半边拉起来，
+ * 再把电脑自己的候选还回去。
+ *
+ * 为什么需要这一步：打洞的本质是「两端同时往对方的出口地址发包」。手机上知道自己的
+ * 出口（它自己问 STUN），电脑也知道自己的；但**彼此不知道对方的**。没有这一次交换，
+ * 两边都只能往空气里打 —— 这正是这条通道早先一次也连不上的原因。
+ *
+ * 为什么走这条路而不是另架一个会合服务：这一发就打在我们**已经有**的那条链路上（局域网 /
+ * 中转 / tailcat 隧道），只传几十个字节的地址。它不承载业务数据，也不新增任何部署物 ——
+ * 与「用户没有服务器、我们也不提供」是同一条原则。真正的数据面完全在两端之间。
+ *
+ * 端点本身是幂等的：手机每次心跳都可以带上当前候选再来一次，电脑发现「我已经按这份候选
+ * 起来过了」就直接复用，不重新打洞（重打会让已经打通的洞白丢一次）。
+ */
+
+const { sendJson } = require('../http/routing.js');
+const { readJsonBody } = require('../shared/http-util.js');
+
+/** 候选白名单：只收 `ip:port` 形状，长度也限住 —— 对端给的任何东西都当不可信数据。 */
+const CANDIDATE = /^[0-9a-fA-F.:[\]]{3,64}$/;
+
+/** 手机的公钥：只认 base64（44 字符）或 hex（64 字符）两种，长度不等就不是密钥。 */
+const PUBLIC_KEY = /^[A-Za-z0-9+/=]{43,44}$|^[0-9a-fA-F]{64}$/;
+
+function normalizePublicKey(value) {
+  if (typeof value !== 'string') return '';
+  const text = value.trim();
+  return PUBLIC_KEY.test(text) ? text : '';
+}
+
+function normalizeCandidates(list) {
+  if (!Array.isArray(list)) return [];
+  const out = [];
+  for (const item of list) {
+    if (typeof item !== 'string') continue;
+    const text = item.trim();
+    if (!text || text.length > 64 || !CANDIDATE.test(text)) continue;
+    if (!out.includes(text)) out.push(text);
+    // 上限 16 条：正常也就两三条，多出来的只可能是拼错的输入。
+    if (out.length >= 16) break;
+  }
+  return out;
+}
+
+/**
+ * @param {object} deps
+ * @param {object} deps.p2p 装配层交下来的 P2P 门面（`lib/p2p/wiring.cjs`）
+ * @param {() => number} [deps.lanPortInUse] 本机插件端口（隧道里那些连接最终转给它）
+ */
+function createP2PRendezvousHandler(deps) {
+  return async function handleRendezvous(_ctx, req, res) {
+    if (!deps.p2p || typeof deps.p2p.open !== 'function') {
+      // 这台电脑没装助手 / 没起这条通道：如实说，手机那边据此把这一条标成不可用，
+      // 而不是一直等一个永远不会来的回答。
+      sendJson(res, 200, { ok: true, available: false, reason: 'p2p-unavailable' });
+      return;
+    }
+
+    const body = await readJsonBody(req, 16 * 1024);
+    const candidates = normalizeCandidates(body && body.candidates);
+    const localCandidates = normalizeCandidates(body && body.localCandidates);
+    // 手机自己的公钥：电脑拉起隧道时要拿它对 WireGuard 握手。没有它，电脑配不出对端，
+    // 这条通道根本起不来（不是「打洞打不通」，是连设备都配不上）。
+    const phonePublicKey = normalizePublicKey(body && body.phonePublicKey);
+    // 手机候选为空也允许：电脑照样能「只听不打」地起来、把自己的候选报回去，等手机来打。
+    // 硬要它先有候选，等于把「谁先拨」的顺序焊死，第一发永远没有候选。
+
+    const opened = await deps.p2p.open({
+      // **不转 `body.peerKey`**：手机那一格装的是**我这台电脑的公钥**（它拿它确认「对面是那台
+      // 电脑」），不是它自己的。会话要的对端是手机那把，只有 `phonePublicKey` 一处。
+      // 早先把这一格直接当对端传下去，电脑于是拿自己的公钥配 WireGuard —— 洞能开、`path`
+      // 报 `direct`，但握手永远对不上，数据面一个包都过不去。
+      phonePublicKey,
+      candidates,
+      localCandidates,
+      targetPort: typeof deps.lanPortInUse === 'function' ? deps.lanPortInUse() : 0,
+    });
+    if (!opened || opened.ok === false) {
+      sendJson(res, 200, {
+        ok: true,
+        available: false,
+        reason: (opened && opened.code) || 'start-failed',
+      });
+      return;
+    }
+
+    // 回我自己的候选：手机拿到这份，才知道往哪打。
+    sendJson(res, 200, {
+      ok: true,
+      available: true,
+      // 隧道里那个固定端口（手机拨它）。
+      port: deps.p2p.constants ? deps.p2p.constants.P2P_PORT : undefined,
+      // **我这一把公钥**：手机要拿它确认「对面是那台电脑」并配 WireGuard 对端。二维码里
+      // 有这一份，但已经配过对、或换过电脑的老会话也得能自己拿到 —— 否则手机只能重新扫码。
+      publicKey: typeof opened.publicKey === 'string' ? opened.publicKey : '',
+      // 电脑的出口地址（STUN 那份 + 本机私网那份）。**这一份才是打洞的起点**。
+      candidates: normalizeCandidates(opened.candidates),
+      localCandidates: [],
+    });
+  };
+}
+
+module.exports = { createP2PRendezvousHandler, normalizeCandidates };