@mindscraft/branch-video-agent-cli 0.5.0 → 0.5.2

package/README.md

@@ -252,61 +252,65 @@ AI Gateway Seed Audio 音频生成并等待示例：
 '@ | npm exec --yes --package=@mindscraft/branch-video-agent-cli branch-video-agent -- ai-gateway seed-audio-create -- --wait --raw
 ```
 
-`tts-create` / `tts-get` 是 Seed Audio 的历史兼容别名；新脚本优先使用 `seed-audio-create` / `seed-audio-get`。
-
-## RPG2 生产工作台
-
-工作台 CLI 只提交调用方显式登记的项目、产物和归档清单；它不会扫描 RPG 阶段目录，也不会根据文件名推断版本关系。认证仍使用 `AIHUB_AGENT_TOKEN` 与 `BRANCH_VIDEO_AGENT_BASE_URL`，不要在 JSON、命令行或日志中保存 token。
-
-项目、生产记录和外部 CDN 产物可使用 JSON 文件提交：
-
-```powershell
-branch-video-agent workbench project create --file .\project.json --raw
-branch-video-agent workbench record put --project wb_project_id --file .\record.json --raw
-branch-video-agent workbench submit --file .\artifact-external.json --raw
-branch-video-agent workbench annotation put --project wb_project_id --file .\annotation.json --raw
-```
-
-同一产物用稳定的 `artifactKey` 和由流程侧持久维护的递增 `sourceRevision`。`idempotencyKey` 由流程侧保存并在重试时复用。已有持久媒体使用 `content.type: "external"`；本地文档、脱敏 session 或其他需要长期保存的文件使用 `content.type: "local"` 与 `sourcePath`。CLI 会先计算 SHA-256、声明 blob，再以原始二进制流上传；服务端只收到 blob 描述，绝不会收到本地路径。单文件上限为 64 MiB。
-
-```json
-{
-  "schemaVersion": "workbench.artifact/1",
-  "projectId": "wb_project_id",
-  "artifactKey": "document:director-program",
-  "sourceRevision": 2,
-  "idempotencyKey": "persisted-event-uuid",
-  "kind": "markdown",
-  "stageKey": "04",
-  "title": "导演稿",
-  "content": {
-    "type": "local",
-    "sourcePath": "C:/production/canonical/director.md",
-    "mime": "text/markdown"
-  },
-  "source": {
-    "productionRecordId": "record_id",
-    "archiveGeneration": 0,
-    "sourceSchema": "director-program/4"
-  }
-}
-```
-
-上传响应在网络中丢失时，CLI 会先查询同一个已声明 blob；ready 状态不会重传，也不会重新登记业务版本。失败交给流程侧持久待传队列用相同事件重试。
-
-`sync` 只读取 `--manifest` 中显式的 `items`。每个 item 为 `type: "artifact"`（默认）或 `type: "annotation"`，可直接携带提交字段或放进 `submission`；不会递归任何工作目录。
-
-```powershell
-branch-video-agent workbench sync --manifest .\.workbench\pending-items.json --raw
-branch-video-agent workbench archive prepare --manifest .\.workbench\archive-wrapper.json --raw
-branch-video-agent workbench archive finalize --project wb_project_id --record record_id --revision 1 --manifest-hash <sha256> --raw
-branch-video-agent workbench archive status --project wb_project_id --record record_id --raw
-branch-video-agent workbench archive download --project wb_project_id --record record_id --revision 1 --file .\entry.json --output .\session.jsonl.zst --raw
-```
-
-`archive prepare` 的文件是调用方维护的 wrapper：`{ manifest, manifestHash, expectedPreviousRevision }`；CLI 原样提交规范化清单和 hash。`archive finalize` 只校验已经提交的清单，不补扫文件。下载的 `entry.json` 至少包含 `{ "entryId": "..." }`；受权限保护的字节写入 `--output`，stdout 仍只输出 JSON 回执。
-
-`record put` 的路径参数是稳定的流程 `recordKey`，返回对象的 `id` 才是后续 `end-intent`、`reopen` 和所有 `archive` 命令使用的 `productionRecordId`（也可传给 `--record`）。不要把 `recordKey` 当成归档路由 ID。
+`tts-create` / `tts-get` 是 Seed Audio 的历史兼容别名；新脚本优先使用 `seed-audio-create` / `seed-audio-get`。
+
+## RPG2 生产工作台
+
+工作台 CLI 只提交调用方显式登记的项目、产物和归档清单；它不会扫描 RPG 阶段目录，也不会根据文件名推断版本关系。认证仍使用 `AIHUB_AGENT_TOKEN` 与 `BRANCH_VIDEO_AGENT_BASE_URL`，不要在 JSON、命令行或日志中保存 token。
+
+项目、生产记录和外部 CDN 产物可使用 JSON 文件提交：
+
+```powershell
+branch-video-agent workbench project create --file .\project.json --raw
+branch-video-agent workbench record put --project wb_project_id --file .\record.json --raw
+branch-video-agent workbench submit --file .\artifact-external.json --raw
+branch-video-agent workbench annotation put --project wb_project_id --file .\annotation.json --raw
+```
+
+同一产物用稳定的 `artifactKey` 和由流程侧持久维护的递增 `sourceRevision`。`idempotencyKey` 由流程侧保存并在重试时复用。已有持久媒体使用 `content.type: "external"`；本地文档、脱敏 session 或其他需要长期保存的文件使用 `content.type: "local"` 与 `sourcePath`。CLI 先计算原文件 SHA-256、声明 blob。0.5.2 对尚未 ready 的 blob 要求服务端返回 `uploadTransport` 公钥配置；缺少配置时失败，不自动回退。文件先 gzip，再使用每次随机 AES-256-GCM 密钥加密，密钥以服务端 RSA3072 OAEP-SHA256 公钥封装。传输使用 `application/octet-stream`、`x-workbench-upload-format: gzip-aes256gcm-v1`，以及受限的 key-id/wrapped-key/nonce/auth-tag headers，不使用 Content-Encoding。服务端完整认证密文后才解压，校验原始大小和 SHA-256；下载返回原字节，版本和幂等键不变。相同字节复用首次声明的 MIME，CLI 使用该权威 MIME 构造 AAD 和提交描述；不会更改 blob 的 purpose 或脱敏证明。
+
+原文件上限 64 MiB，密文/压缩流上限 65 MiB。两端使用私有临时文件，成功、失败和取消时清理；下次上传只清理确定已退出 PID 的历史目录，保留活跃、无权探测及 PID 复用目录，因此不是总磁盘硬上限。TMPDIR 不得跨 PID namespace 共享（服务端 pod 私有 /tmp；CLI 宿主同 namespace）。异常强杀后恢复清理依赖下一次上传；仍需现有磁盘容量监控。
+
+公钥附加在已授权 blob 声明响应；私钥仅存服务端独立 Mongo 集合，所有 pod 读取同一权威记录。私钥不进入 Blob DTO、CLI、日志或镜像。此机制保护上传传输，不保护数据库泄露或能替换公钥的可信代理；网关不能检查加密后的文件正文，服务端仍执行鉴权、大小及完整性验证。部署先服务端后 CLI。服务端保留旧 raw/gzip 兼容；ready blob 直接复用，无需公钥或再传输。CLI 不发送本地文件路径。
+
+```json
+{
+  "schemaVersion": "workbench.artifact/1",
+  "projectId": "wb_project_id",
+  "artifactKey": "document:director-program",
+  "sourceRevision": 2,
+  "idempotencyKey": "persisted-event-uuid",
+  "kind": "markdown",
+  "stageKey": "04",
+  "title": "导演稿",
+  "content": {
+    "type": "local",
+    "sourcePath": "C:/production/canonical/director.md",
+    "mime": "text/markdown"
+  },
+  "source": {
+    "productionRecordId": "record_id",
+    "archiveGeneration": 0,
+    "sourceSchema": "director-program/4"
+  }
+}
+```
+
+上传响应在网络中丢失时，CLI 会先查询同一个已声明 blob；ready 状态不会重传，也不会重新登记业务版本。失败交给流程侧持久待传队列用相同事件重试。
+
+`sync` 只读取 `--manifest` 中显式的 `items`。每个 item 为 `type: "artifact"`（默认）或 `type: "annotation"`，可直接携带提交字段或放进 `submission`；不会递归任何工作目录。
+
+```powershell
+branch-video-agent workbench sync --manifest .\.workbench\pending-items.json --raw
+branch-video-agent workbench archive prepare --manifest .\.workbench\archive-wrapper.json --raw
+branch-video-agent workbench archive finalize --project wb_project_id --record record_id --revision 1 --manifest-hash <sha256> --raw
+branch-video-agent workbench archive status --project wb_project_id --record record_id --raw
+branch-video-agent workbench archive download --project wb_project_id --record record_id --revision 1 --file .\entry.json --output .\session.jsonl.zst --raw
+```
+
+`archive prepare` 的文件是调用方维护的 wrapper：`{ manifest, manifestHash, expectedPreviousRevision }`；CLI 原样提交规范化清单和 hash。`archive finalize` 只校验已经提交的清单，不补扫文件。下载的 `entry.json` 至少包含 `{ "entryId": "..." }`；受权限保护的字节写入 `--output`，stdout 仍只输出 JSON 回执。
+
+`record put` 的路径参数是稳定的流程 `recordKey`，返回对象的 `id` 才是后续 `end-intent`、`reopen` 和所有 `archive` 命令使用的 `productionRecordId`（也可传给 `--record`）。不要把 `recordKey` 当成归档路由 ID。
 
 ## 在仓库内构建发布包
 
@@ -314,16 +318,16 @@ branch-video-agent workbench archive download --project wb_project_id --record r
 
 ```powershell
 npm run agent:cli:package:build
-npm run agent:cli:package:smoke
-```
-
-需要运行会启动 standalone Mongo、真实 CLI HTTP 流、Python adapter 或 Chromium 的 Production Workbench 集成验收时，使用专用命令；常规 `npm test` 会排除这些外部运行时依赖。adapter E2E 需要相邻的 rpg2 adapter checkout，或显式设置 `RPG2_WORKBENCH_ADAPTER_ROOT`；缺失 checkout、`zstd` 或 Chromium 时命令应失败。
-
-```powershell
-npm run test:workbench-cli-integration
-npm run test:workbench-adapter-e2e
-npm run test:workbench-integration
-```
+npm run agent:cli:package:smoke
+```
+
+需要运行会启动 standalone Mongo、真实 CLI HTTP 流、Python adapter 或 Chromium 的 Production Workbench 集成验收时，使用专用命令；常规 `npm test` 会排除这些外部运行时依赖。adapter E2E 需要相邻的 rpg2 adapter checkout，或显式设置 `RPG2_WORKBENCH_ADAPTER_ROOT`；缺失 checkout、`zstd` 或 Chromium 时命令应失败。
+
+```powershell
+npm run test:workbench-cli-integration
+npm run test:workbench-adapter-e2e
+npm run test:workbench-integration
+```
 
 产物输出到：
 

package/dist/commands/workbench.js

@@ -1,3 +1,4 @@
+import { encryptUpload } from '../lib/uploadEncryption.js';
 import { createHash } from 'node:crypto';
 import { createReadStream } from 'node:fs';
 import { stat, writeFile } from 'node:fs/promises';
@@ -68,19 +69,30 @@ async function uploadLocalContent(context, sourcePath, content) {
         timeoutMs: context.flags.timeoutMs,
     });
     const blobId = getRequiredString(declared.data, 'id');
+    const declaredMime = declared.data.mime;
+    if (declared.data.sha256 !== sha256 || declared.data.size !== fileStat.size || typeof declaredMime !== 'string' || !/^[a-zA-Z0-9!#$&^_.+-]+\/[a-zA-Z0-9!#$&^_.+-]+$/.test(declaredMime) || declaredMime.length >= 200)
+        throw new CliCommandError('Blob declaration does not match the local file', 'BLOB_METADATA_MISMATCH');
     if (declared.data.state !== 'ready') {
         let uploadError;
+        const encrypted = await encryptUpload(sourcePath, projectId(context.payload, context.flags.project), declared.data);
+        const stream = createReadStream(encrypted.path);
         try {
             await context.client.requestStream(`${workbenchPath}/projects/${encodeURIComponent(projectId(context.payload, context.flags.project))}/blobs/${encodeURIComponent(blobId)}/content`, {
                 method: 'PUT',
-                body: Readable.toWeb(createReadStream(sourcePath)),
-                contentType: mime,
+                body: Readable.toWeb(stream),
+                contentType: 'application/octet-stream',
+                uploadFormat: 'gzip-aes256gcm-v1',
+                encryption: encrypted.headers,
                 timeoutMs: context.flags.timeoutMs,
             });
         }
         catch (error) {
             uploadError = error;
         }
+        finally {
+            stream.destroy();
+            await encrypted.cleanup();
+        }
         if (uploadError) {
             const status = await context.client.request(`${workbenchPath}/projects/${encodeURIComponent(projectId(context.payload, context.flags.project))}/blobs/${encodeURIComponent(blobId)}`, {
                 method: 'GET',
@@ -90,7 +102,7 @@ async function uploadLocalContent(context, sourcePath, content) {
                 throw uploadError;
         }
     }
-    return { type: 'blob', blobId, sha256, size: fileStat.size, mime };
+    return { type: 'blob', blobId, sha256, size: fileStat.size, mime: declaredMime };
 }
 function validateSubmission(payload) {
     if (payload.schemaVersion !== 'workbench.artifact/1') {

package/dist/lib/http.d.ts

@@ -13,6 +13,13 @@ type StreamRequestOptions = {
     method: string;
     body: ReadableStream<Uint8Array>;
     contentType: string;
+    uploadFormat?: 'gzip' | 'gzip-aes256gcm-v1';
+    encryption?: {
+        kid: string;
+        wrappedKey: string;
+        nonce: string;
+        tag: string;
+    };
     timeoutMs?: number;
 };
 type BinaryRequestResult = {

package/dist/lib/http.js

@@ -93,6 +93,8 @@ export class CliHttpClient {
                 headers: {
                     Authorization: `Bearer ${this.token}`,
                     'content-type': options.contentType,
+                    ...(options.encryption ? { 'x-workbench-key-id': options.encryption.kid, 'x-workbench-wrapped-key': options.encryption.wrappedKey, 'x-workbench-nonce': options.encryption.nonce, 'x-workbench-auth-tag': options.encryption.tag } : {}),
+                    ...(options.uploadFormat ? { 'x-workbench-upload-format': options.uploadFormat } : {}),
                 },
                 body: options.body,
                 duplex: 'half',

package/dist/lib/uploadEncryption.d.ts

@@ -0,0 +1,10 @@
+export declare function encryptUpload(sourcePath: string, projectId: string, blob: Record<string, unknown>): Promise<{
+    path: string;
+    headers: {
+        kid: string;
+        wrappedKey: string;
+        nonce: string;
+        tag: string;
+    };
+    cleanup: () => Promise<void>;
+}>;

package/dist/lib/uploadEncryption.js

@@ -0,0 +1,40 @@
+import { uploadTempDirectory } from './uploadTemp.js';
+import { constants, createCipheriv, createHash, createPublicKey, publicEncrypt, randomBytes } from 'node:crypto';
+import { createReadStream, createWriteStream } from 'node:fs';
+import { rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { Transform } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { createGzip } from 'node:zlib';
+import { CliCommandError } from './errors.js';
+export async function encryptUpload(sourcePath, projectId, blob) {
+    const config = blob.uploadTransport;
+    if (!config || config.format !== 'gzip-aes256gcm-v1' || config.keyAlgorithm !== 'RSA-OAEP-256' || config.contentAlgorithm !== 'A256GCM' || typeof config.kid !== 'string' || !/^[a-f0-9]{64}$/.test(config.kid) || typeof config.publicKeySpki !== 'string' || config.publicKeySpki.length > 1024)
+        throw new CliCommandError('Server does not offer the required encrypted upload protocol', 'UPLOAD_ENCRYPTION_REQUIRED');
+    let publicKey;
+    try {
+        const der = Buffer.from(config.publicKeySpki, 'base64');
+        publicKey = createPublicKey({ key: der, type: 'spki', format: 'der' });
+        if (publicKey.asymmetricKeyType !== 'rsa' || publicKey.asymmetricKeyDetails?.modulusLength !== 3072 || der.toString('base64') !== config.publicKeySpki || createHash('sha256').update(der).digest('hex') !== config.kid)
+            throw new Error();
+    }
+    catch {
+        throw new CliCommandError('Invalid upload public key', 'UPLOAD_ENCRYPTION_REQUIRED');
+    }
+    const key = randomBytes(32), nonce = randomBytes(12);
+    const cipher = createCipheriv('aes-256-gcm', key, nonce, { authTagLength: 16 });
+    cipher.setAAD(Buffer.from(JSON.stringify([config.format, config.kid, projectId, blob.id, blob.sha256, blob.size, blob.mime])));
+    const wrappedKey = publicEncrypt({ key: publicKey, padding: constants.RSA_PKCS1_OAEP_PADDING, oaepHash: 'sha256' }, key);
+    key.fill(0);
+    const directory = await uploadTempDirectory();
+    const path = join(directory, 'payload.enc');
+    const limit = (max) => { let size = 0; return new Transform({ transform(chunk, _encoding, done) { size += chunk.length; done(size > max ? new CliCommandError('Upload exceeds file size limit', 'FILE_TOO_LARGE') : null, chunk); } }); };
+    try {
+        await pipeline(createReadStream(sourcePath), limit(64 * 1024 * 1024), createGzip(), cipher, limit(65 * 1024 * 1024), createWriteStream(path, { flags: 'wx', mode: 0o600 }));
+        return { path, headers: { kid: config.kid, wrappedKey: wrappedKey.toString('base64url'), nonce: nonce.toString('base64url'), tag: cipher.getAuthTag().toString('base64url') }, cleanup: () => rm(directory, { recursive: true, force: true }) };
+    }
+    catch (error) {
+        await rm(directory, { recursive: true, force: true });
+        throw error;
+    }
+}

package/dist/lib/uploadTemp.d.ts

@@ -0,0 +1 @@
+export declare function uploadTempDirectory(): Promise<string>;

package/dist/lib/uploadTemp.js

@@ -0,0 +1,29 @@
+import { lstat, mkdir, mkdtemp, readdir, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+// This directory must belong to one host/container PID namespace. Never
+// share TMPDIR across PID namespaces. Cleanup runs only on the next upload;
+// it is not a hard total-disk cap, and reused PIDs are preserved.
+export async function uploadTempDirectory() {
+    const base = join(tmpdir(), 'workbench-upload-client');
+    await mkdir(base, { recursive: true, mode: 0o700 });
+    const info = await lstat(base);
+    if (!info.isDirectory() || info.isSymbolicLink() || (process.platform !== 'win32' && ((info.mode & 0o077) !== 0 || info.uid !== process.getuid?.())))
+        throw new Error('Unsafe upload temporary directory');
+    for (const entry of await readdir(base, { withFileTypes: true })) {
+        const match = /^([1-9][0-9]*)-[A-Za-z0-9]+$/.exec(entry.name);
+        if (!match || !entry.isDirectory() || entry.isSymbolicLink())
+            continue;
+        let dead = false;
+        try {
+            process.kill(Number(match[1]), 0);
+        }
+        catch (error) {
+            dead = error.code === 'ESRCH';
+        }
+        // EPERM and reused/live PIDs are conservatively preserved. No age heuristic.
+        if (dead)
+            await rm(join(base, entry.name), { recursive: true, force: true });
+    }
+    return mkdtemp(join(base, `${process.pid}-`));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mindscraft/branch-video-agent-cli",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "Published CLI for branch-video and AIHub agent APIs.",
   "type": "module",
   "bin": {