dsh-mobile-plugin 0.5.23 → 0.5.24

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 };