dsh-mobile-plugin 0.5.12 → 0.5.13

package/lib/mobile/uploads.js

@@ -17,6 +17,11 @@
  *
  * 顺序与幂等：chunk 只接受下一片，重复送达同一片按重传处理，跳号直接 409。
  *
+ * v3（`caps.wire === 'bin'`，见 docs/native-upload.md 的 v3 章）：请求体换成裸密文，一片
+ * 按**字节偏移**收、允许乱序，靠一个按偏移排序的待拼窗口把连续的部分落盘。协商进去的 job
+ * 走这条路；老客户端没有 `caps`，仍走上面那套按 index 的口径 —— 两条路靠 job 上记的 wire
+ * 分流，不做「猜」。
+ *
  * 图片走两段：先按上面那套把字节传完拿 uploadId，`session/send` 再把 uploadId 换回内联
  * base64 交给宿主 prompt。换的时候整份字节要读进内存 —— 宿主只认内联块，这条通道没有流式
  * 入口。也正因为如此，单张图片的大小上限由桌面端的附件限制定，这里不设体积门槛。
@@ -30,7 +35,9 @@ const os = require('node:os');
 const path = require('node:path');
 const crypto = require('node:crypto');
 
-const { sendJson, readJsonBody } = require('../shared/http-util');
+const { sendJson, readJsonBody, readRawBody } = require('../shared/http-util');
+// 头名的大小写不保证（中转会压成小写，Node 版本之间也有差异），复用信封那一份读法。
+const { headerOf } = require('../shared/e2ee-request');
 const { allowedRoots, inAllowedZone } = require('./allowed-zone.js');
 
 // 片大小的**起步值** 256KB（base64 后约 341KB）：客户端一次请求的硬预算是 8s
@@ -46,6 +53,24 @@ const CHUNK_MAX_BYTES = 2 * 1024 * 1024;
  * 放大到 11MB —— 按线上长度直接卡 8MB 等于悄悄砍掉四分之一的可用额度。
  */
 const CHUNK_MAX_BODY = Math.ceil(8 * 1024 * 1024 * 4 / 3);
+/**
+ * v3（二进制分片体）的片长：起步 4MB、天花板 6MB。
+ *
+ * 天花板的来历是**中转隧道单帧 8MB**：v3 一片的线上字节只是明文加 AEAD 的 12 字节 nonce
+ * 与 16 字节 tag（不 base64、不套 JSON），所以 6MB 明文装得进一帧还留出信封余量。v2 只能到
+ * 2MB 是因为同一份字节被 base64 了两遍（片一次、整条信封再一次），1.78 倍膨胀先把额度吃了。
+ */
+const BIN_CHUNK_BYTES = 4 * 1024 * 1024;
+const BIN_CHUNK_MAX_BYTES = 6 * 1024 * 1024;
+/** 同时在飞的片数缺省值：再小就藏不掉高延迟链路上的一片空等。 */
+const BIN_PIPELINE = 4;
+/**
+ * 客户端给的 pipeline 最多认到 8：它是内存与窗口的乘数，没有理由跟着请求往上翻。
+ *
+ * 窗口的字节上限由它乘出来（片数 × 片长）：窗口只需要装下「在飞的那几片」，再大等于给一个
+ * 发疯的客户端留一块几十 MB 的无主内存。乘出来的那个数就是 `begin` 回给客户端的那一格。
+ */
+const BIN_PIPELINE_MAX = 8;
 /** 文件名上限（按字符算，避开各文件系统的字节上限差异）。 */
 const NAME_MAX_CHARS = 120;
 /**
@@ -96,7 +121,13 @@ function resolveFinishedUpload(uploadId) {
   return { path: record.path, name: record.name, bytes: record.bytes };
 }
 
-/** 进行中的上传：uploadId → { name, stagingPath, received, bytes, expiresAt, expiryTimer }。 */
+/**
+ * 进行中的上传：uploadId → job。
+ *
+ * 两种 wire 共用这张表，靠 job 上的 `wire` 分流（`json` 是老行为，`bin` 是 v3）：
+ *  - json：`received` 是**片数**，chunk 只吃下一片。
+ *  - bin：`receivedBytes` 是**已连续落盘的字节数**，片按偏移收，乱序的先进 `window`。
+ */
 const uploads = new Map();
 
 function removeUpload(uploadId, job) {
@@ -104,6 +135,12 @@ function removeUpload(uploadId, job) {
   uploads.delete(uploadId);
   if (job.expiryTimer) clearTimeout(job.expiryTimer);
   job.expiryTimer = null;
+  // 待拼窗口是纯内存的片缓冲：job 从 Map 摘掉之后还可能被定时器闭包抓着，不清的话一次
+  // 中断的大文件能让几十 MB 多活到进程退出（`unlink` 只管暂存文件，管不到这些 Buffer）。
+  if (job.window) {
+    job.window.length = 0;
+    job.pendingWindowBytes = 0;
+  }
   return true;
 }
 
@@ -268,12 +305,46 @@ async function resolveDestDir(ctx, body) {
   return { dir };
 }
 
-/** POST /api/mobile/v1/upload/begin { name, destPath?, sessionId? } → { ok, uploadId, chunkSize }。 */
+/**
+ * begin 里的能力协商（v3）。
+ *
+ * **只有明确说了 `caps.wire === 'bin'` 才进 v3**：老 App 一个字段都不带，`caps` 为空，
+ * 于是它拿到的是和从前一模一样的响应，走的也是从前那条代码路径。
+ *
+ * v3 必须同时给出 `size`（总字节数）：收口时要靠它证明「字节齐了」，没有它就没法区分
+ * 「一次传完」和「少了一片但客户端以为传完了」。
+ *
+ * @returns {{ wire: 'json' } | { wire: 'bin', pipeline: number, windowBytes: number, windowPieces: number, total: number }
+ *          | { status: number, code: string, message: string }}
+ */
+function resolveCaps(body) {
+  const caps = body.caps && typeof body.caps === 'object' ? body.caps : null;
+  if (!caps || caps.wire !== 'bin') return { wire: 'json' };
+  // 只认真的数字：`null` 会被 Number() 悄悄变成 0，那等于把「没给」当成「传了个空文件」。
+  const size = body.size;
+  if (typeof size !== 'number' || !Number.isSafeInteger(size) || size < 0) {
+    return { status: 400, code: 'bad-request', message: '二进制分片需要 { size }（总字节数）' };
+  }
+  const asked = Number(caps.pipeline);
+  const pipeline = Number.isInteger(asked) && asked > 0 ? Math.min(asked, BIN_PIPELINE_MAX) : BIN_PIPELINE;
+  return {
+    wire: 'bin',
+    pipeline,
+    windowBytes: pipeline * BIN_CHUNK_MAX_BYTES,
+    // 与字节上限并行的第二道封顶：一片只有几字节时，光靠字节数能塞进几千片。
+    windowPieces: Math.max(4, pipeline * 2),
+    total: size,
+  };
+}
+
+/** POST /api/mobile/v1/upload/begin { name, size?, destPath?, sessionId?, caps? } → { ok, uploadId, chunkSize, maxChunkSize, … }。 */
 async function handleUploadBegin(ctx, req, res) {
   const body = await readJsonBody(req);
   if (!body || typeof body.name !== 'string' || !body.name.trim()) {
     return fail(res, 400, 'bad-request', '需要 { name }');
   }
+  const caps = resolveCaps(body);
+  if (caps.status) return fail(res, caps.status, caps.code, caps.message);
   // 落点先判：越界 / 不是目录在这一步就回，不先建暂存再报错 —— 残片要躺满 7 天才清。
   const destination = await resolveDestDir(ctx, body);
   if (destination.status) return fail(res, destination.status, destination.code, destination.message);
@@ -298,24 +369,158 @@ async function handleUploadBegin(ctx, req, res) {
     // 指定落点就记在这里，finish 才用得上（中途不再判一次范围：begin 已经认过）。
     destDir: destination.dir,
     stagingPath,
+    // 老路径（json）的两个计数器；v3 另起 `receivedBytes`，两者语义不同，不混用同一格。
     received: 0,
     bytes: 0,
+    wire: caps.wire,
+    // v3 才有意义：偏移收片的账、待拼窗口与它的两块封顶。
+    receivedBytes: 0,
+    total: caps.wire === 'bin' ? caps.total : 0,
+    pipeline: caps.wire === 'bin' ? caps.pipeline : 0,
+    windowBytes: caps.wire === 'bin' ? caps.windowBytes : 0,
+    windowPieces: caps.wire === 'bin' ? caps.windowPieces : 0,
+    window: [],
+    pendingWindowBytes: 0,
     expiresAt: Date.now() + STAGING_TTL_MS,
     expiryTimer: null,
   };
   uploads.set(uploadId, job);
   scheduleUploadExpiry(uploadId, job);
   // chunkSize 是起步值、maxChunkSize 是天花板：客户端从前者开始按实测周期往上爬。
+  //
+  // 老客户端（没协商 caps）拿到的是**和从前逐字节相同**的那五个字段：多一个 `wire` 都会
+  // 让「不带 caps 就走 v2」这条承诺落空，所以 v3 的字段只在真协商成功时追加。
+  if (caps.wire === 'bin') {
+    return sendJson(res, 200, {
+      ok: true,
+      uploadId,
+      chunkSize: BIN_CHUNK_BYTES,
+      maxChunkSize: BIN_CHUNK_MAX_BYTES,
+      wire: 'bin',
+      pipeline: job.pipeline,
+      windowBytes: job.windowBytes,
+    });
+  }
   sendJson(res, 200, { ok: true, uploadId, chunkSize: CHUNK_BYTES, maxChunkSize: CHUNK_MAX_BYTES });
 }
 
+/**
+ * 把一片按偏移接到暂存文件末尾，**只追加 `receivedBytes` 之后的那部分**。
+ *
+ * 「只追加尾巴」是为了容忍客户端切片的边界与上一片重叠：重叠字节已经在盘上了，再追加一遍
+ * 就把文件写坏（大文件里表现为某一段重复，且字节数悄悄变多）。返回写入字节数，0 表示这片
+ * 整段落在已收区间内。
+ */
+async function appendPiece(job, offset, data) {
+  const skip = job.receivedBytes - offset;
+  if (skip >= data.length) return 0;
+  const tail = skip > 0 ? data.subarray(skip) : data;
+  await fsp.appendFile(job.stagingPath, tail);
+  job.receivedBytes += tail.length;
+  // finish 落盘报的 `bytes` 与 json 分支同一个字段：两条 wire 的收口代码因此只差那一句判据。
+  job.bytes = job.receivedBytes;
+  return tail.length;
+}
+
+/** 顺着窗口把接得上的后续片一并落盘（它们的偏移正好从 `receivedBytes` 开始）。 */
+async function flushWindow(job) {
+  let wrote = false;
+  while (job.window.length) {
+    const next = job.window[0];
+    if (next.offset > job.receivedBytes) break;
+    job.window.shift();
+    job.pendingWindowBytes -= next.data.length;
+    if (await appendPiece(job, next.offset, next.data)) wrote = true;
+  }
+  return wrote;
+}
+
+/**
+ * v3 的一条二进制分片：`X-Dsh-Wire: bin` + `X-Dsh-Upload-Id` + `X-Dsh-Upload-Offset`，
+ * 请求体是这一片的裸密文（守卫已解成 `req.rawBody` 里的明文）。
+ *
+ * 偏移三分法（见 docs/native-upload.md 的「偏移与窗口」）：
+ *  - `offset < receivedBytes`：整片已收过 → 200 幂等；跨过边界 → 400 `bad-offset`。
+ *  - `offset === receivedBytes`：追加，并顺着窗口把接得上的后续片一起落盘。
+ *  - `offset > receivedBytes`：进窗口等前面补齐；窗口按字节数或积压片数封顶 → 409。
+ */
+async function handleBinChunk(req, res) {
+  const uploadId = headerOf(req, 'x-dsh-upload-id').trim();
+  const job = uploads.get(uploadId);
+  if (!job) return fail(res, 404, 'unknown-upload', '上传会话不存在或已结束');
+  // 同一 job 中途换 wire 一律拒：两种 wire 的 `received` 一个数片、一个数字节，混着收
+  // 会拼出一个对不上账的暂存文件，而客户端还以为自己在续传。
+  if (job.wire !== 'bin') {
+    return fail(res, 400, 'wire-mismatch', '这个上传是按 JSON 分片协商的，不能混发二进制分片');
+  }
+
+  const offsetText = headerOf(req, 'x-dsh-upload-offset').trim();
+  const offset = Number(offsetText);
+  if (!/^\d+$/.test(offsetText) || !Number.isSafeInteger(offset)) {
+    return fail(res, 400, 'bad-offset', 'X-Dsh-Upload-Offset 必须是非负整数');
+  }
+  const piece = await readRawBody(req, BIN_CHUNK_MAX_BYTES);
+  if (!piece) return fail(res, 413, 'too-large', '分片过大');
+  if (!piece.length) return fail(res, 400, 'bad-offset', '分片不能是空的');
+
+  const end = offset + piece.length;
+  if (offset < job.receivedBytes) {
+    if (end <= job.receivedBytes) return sendJson(res, 200, { ok: true, received: job.receivedBytes });
+    return fail(res, 400, 'bad-offset', `这一片跨过了已收边界（已收 ${job.receivedBytes} 字节）`);
+  }
+
+  if (offset === job.receivedBytes) {
+    try {
+      await appendPiece(job, offset, piece);
+      await flushWindow(job);
+    } catch (error) {
+      removeUpload(uploadId, job);
+      return fail(res, 500, 'inbox-unavailable', `写入暂存文件失败：${error.message}`);
+    }
+    job.expiresAt = Date.now() + STAGING_TTL_MS;
+    scheduleUploadExpiry(uploadId, job);
+    return sendJson(res, 200, { ok: true, received: job.receivedBytes });
+  }
+
+  // 到这里就是乱序：这一片比已连续落盘的字节跑得靠后，先攒着。
+  const existing = job.window.find((entry) => entry.offset === offset);
+  const added = existing ? piece.length - existing.data.length : piece.length;
+  if (
+    job.pendingWindowBytes + added > job.windowBytes
+    || (!existing && job.window.length >= job.windowPieces)
+  ) {
+    return fail(res, 409, 'window-exceeded', `乱序窗口已满（${job.windowPieces} 片 / ${job.windowBytes} 字节），请退避后重发这一片`);
+  }
+  if (existing) {
+    // 同一偏移重发：以新的字节为准（客户端重传的是同一片，内容应当一样），不重复计数。
+    existing.data = piece;
+  } else {
+    // 保持按偏移升序：flushWindow 只认队首，插错位置会让窗口永远不前进。
+    const at = job.window.findIndex((entry) => entry.offset > offset);
+    const entry = { offset, data: piece };
+    if (at < 0) job.window.push(entry);
+    else job.window.splice(at, 0, entry);
+  }
+  job.pendingWindowBytes += added;
+  job.expiresAt = Date.now() + STAGING_TTL_MS;
+  scheduleUploadExpiry(uploadId, job);
+  return sendJson(res, 200, { ok: true, received: job.receivedBytes });
+}
+
 /** POST /api/mobile/v1/upload/chunk { uploadId, index, data } → { ok, received }。 */
 async function handleUploadChunk(_ctx, req, res) {
+  // wire 在最前面分流：bin 的请求体是裸密文（守卫已解成 `req.rawBody`），拿它当 JSON 读
+  // 只会得到一个「畸形 JSON」的 413 —— 那是假象，不是真的太大。
+  if (headerOf(req, 'x-dsh-wire').trim().toLowerCase() === 'bin') return handleBinChunk(req, res);
+
   const body = await readJsonBody(req, CHUNK_MAX_BODY);
   if (!body) return fail(res, 413, 'too-large', '分片过大或不是合法 JSON');
 
   const job = uploads.get(String(body.uploadId == null ? '' : body.uploadId));
   if (!job) return fail(res, 404, 'unknown-upload', '上传会话不存在或已结束');
+  if (job.wire === 'bin') {
+    return fail(res, 400, 'wire-mismatch', '这个上传是按二进制分片协商的，不能混发 JSON 分片');
+  }
 
   const index = Number(body.index);
   if (!Number.isInteger(index) || index < 0) return fail(res, 400, 'bad-request', 'index 必须是非负整数');
@@ -358,6 +563,15 @@ async function handleUploadFinish(_ctx, req, res) {
     if (replay) return sendJson(res, 200, { ok: true, ...replay, uploadId });
     return fail(res, 404, 'unknown-upload', '上传会话不存在或已结束');
   }
+
+  // v3 的收口必须先证明字节齐了：分片可以乱序、可以重发，少一片时落盘出来的文件是残缺的，
+  // 而文件名照样对、客户端照样以为传完了。**job 不删** —— 客户端补上缺的那几片后还能再收一次口。
+  if (job.wire === 'bin' && job.receivedBytes !== job.total) {
+    return sendJson(res, 400, {
+      ok: false,
+      error: { code: 'incomplete', message: `上传还没收齐（已收 ${job.receivedBytes} / ${job.total} 字节）`, received: job.receivedBytes },
+    });
+  }
   removeUpload(uploadId, job);
 
   const dir = job.destDir || path.join(inboxRoot(), today());

package/lib/shared/e2ee-request.js

@@ -65,6 +65,17 @@ function signedPath(req) {
   return hit >= 0 ? pathname.slice(hit) : pathname;
 }
 
+/**
+ * v3 二进制分片的 AAD：`v2|up|METHOD|PATH|<uploadId>|<offset>`。
+ *
+ * 在 v2 的四段后面绑上这两格，是为了让「把一片搬到别的上传 / 搬到同一上传的别的偏移」
+ * 在 AEAD 这一层就不成立 —— 签名只覆盖路径与字节，绑不到上传身份上。
+ *
+ * 字符串口径写在 `docs/native-upload.md` 的 v3 章，与 App 侧下一阶段的实现对齐；这里只
+ * 负责把它拼出来，不额外规范化 offset（`"042"` 与 `"42"` 拼出来不同，客户端必须原样发）。
+ */
+const binChunkAad = (method, path, uploadId, offset) => `v2|up|${method}|${path}|${uploadId}|${offset}`;
+
 /** 查询串按线上原样（含 `?`），不排序：它必须与 App 真正发出去的那串一致。 */
 function signedQuery(req) {
   const raw = String(req?.url || '');
@@ -81,6 +92,8 @@ function signedQuery(req) {
  * @param {Buffer} [deps.rawBody] 已读到的请求体原文（没读过就给 undefined，这里会自己读）
  * @returns {{ ok: true, body: object|undefined, keys: object, device: object }
  *          | { ok: false, status: number, code: string, extra?: object }}
+ *
+ * 带 `X-Dsh-Wire: bin` 的请求没有 JSON body，解出来的明文放在 `req.rawBody`（Buffer）上。
  */
 function openRequest(req, deps, rawBody) {
   const keyId = headerOf(req, 'x-dsh-key-id').trim();
@@ -133,6 +146,32 @@ function openRequest(req, deps, rawBody) {
     nonces.set(keyId, table);
   }
 
+  // ── 二进制 wire（v3 的上行分片体，见 docs/native-upload.md 的 v3 章）──
+  //
+  // 只对**明确带头**的请求生效：老 App 不会发 `X-Dsh-Wire`，所以它走的仍是下面那条
+  // JSON 信封分支，一个字节都不变。反过来，带了 `bin` 就说明客户端知道自己在发裸密文，
+  // 这时候把它当 JSON 解只会得到一个「请求体不是合法 JSON」的 400。
+  if (headerOf(req, 'x-dsh-wire').trim().toLowerCase() === 'bin') {
+    const uploadId = headerOf(req, 'x-dsh-upload-id').trim();
+    const offsetText = headerOf(req, 'x-dsh-upload-offset').trim();
+    // 这两格既进 AAD 也进业务判据，缺一格就没法把「这一片」绑到「这个上传的这个偏移」上。
+    if (!uploadId || !/^\d+$/.test(offsetText)) {
+      return { ok: false, status: 400, code: 'e2ee-bad-envelope', extra: { reason: 'missing wire headers' } };
+    }
+    let plain;
+    try {
+      // AAD 比 v2 多两段：先把一片搬到别的上传、或搬到同一上传的别的偏移，认证就不过。
+      // 签名口径不变（签的仍是线上这串密文字节），所以上面那步验签一行没动。
+      plain = e2ee.open(keys.up, rawBody || Buffer.alloc(0), binChunkAad(method, signedPath(req), uploadId, offsetText));
+    } catch {
+      return { ok: false, status: 400, code: 'e2ee-decrypt-failed' };
+    }
+    // 业务 handler 拿不到 JSON（这一片本来就不是 JSON）：明文交给 `req.rawBody`，
+    // 上传 handler 用 `readRawBody` 取。响应仍由上面的守卫封成普通的 v2 JSON 信封。
+    req.rawBody = plain;
+    return { ok: true, body: undefined, keys, device: record, req: { ts, nonce } };
+  }
+
   // ── 解封请求体 ──
   let body;
   if (rawBody && rawBody.length > 0) {

package/lib/shared/http-util.js

@@ -137,4 +137,59 @@ function readJsonBody(req, maxBytes = JSON_MAX_BODY) {
   });
 }
 
-module.exports = { sendJson, sendHtml, readJsonBody, encodeJsonBody, wantsGzip, JSON_GZIP_MIN_BYTES, JSON_MAX_BODY };
+/**
+ * 读原始请求体，回 Buffer；超限 / 连接出错 → null。
+ *
+ * 与 `readJsonBody` 的分工：那条路交出去的是**解析好的 JSON**，这条路交出去的是**字节**。
+ * v3 的二进制分片（`X-Dsh-Wire: bin`）加密后就是裸字节，中间没有 JSON 这一层；handler 拿
+ * 到的明文片（守卫解封之后）同样是字节，所以两边都用这一条。
+ *
+ * `req.rawBody` 优先：信封守卫（`shared/e2ee-request.js`）已经把密文读走、解封完放在那里，
+ * 请求流早就见底了，再 `on('data')` 只会等来一个空 body —— 那会表现为「每片都解出 0 字节」，
+ * 而错误信息只会是「分片是空的」。
+ *
+ * @param {object} req         node:http IncomingMessage
+ * @param {number} [maxBytes]  请求体上限（字节），缺省按普通 JSON 那一档
+ * @returns {Promise<Buffer|null>}
+ */
+function readRawBody(req, maxBytes = JSON_MAX_BODY) {
+  const handed = req && req.rawBody;
+  if (Buffer.isBuffer(handed)) return Promise.resolve(handed.length > maxBytes ? null : handed);
+  return new Promise((resolve) => {
+    const chunks = [];
+    let total = 0;
+    let settled = false;
+    req.on('data', (chunk) => {
+      if (settled) return;
+      total += chunk.length;
+      if (total > maxBytes) {
+        settled = true;
+        req.destroy();
+        resolve(null);
+        return;
+      }
+      chunks.push(Buffer.from(chunk));
+    });
+    req.on('end', () => {
+      if (settled) return;
+      settled = true;
+      resolve(Buffer.concat(chunks));
+    });
+    req.on('error', () => {
+      if (settled) return;
+      settled = true;
+      resolve(null);
+    });
+  });
+}
+
+module.exports = {
+  sendJson,
+  sendHtml,
+  readJsonBody,
+  readRawBody,
+  encodeJsonBody,
+  wantsGzip,
+  JSON_GZIP_MIN_BYTES,
+  JSON_MAX_BODY,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-mobile-plugin",
-  "version": "0.5.12",
+  "version": "0.5.13",
   "description": "Mobile API (/api/mobile/v1) and relay client for the DSH mobile app — desktop profile build (dsh 0.2.x, peers resolved by the host)",
   "license": "MIT",
   "icon": "./icon.png",