@imweapp/openclaw-imwe 2026.4.12-alpha.1

package/src/file-transfer/file-crypto.ts

@@ -0,0 +1,93 @@
+/**
+ * file-crypto.ts — AES-256-CTR 加解密模块
+ *
+ * 与 iOS FileCryptography 完全对齐的实现：
+ * - CTR 计数器规则：IV 前 12 字节固定，后 4 字节 big-endian 32-bit counter
+ * - counter = initialCounter + Math.floor(plaintextOffset / 16)
+ * - CTR 模式：输出长度 === 输入长度（无 padding）
+ */
+
+import crypto from 'node:crypto';
+import { FileEncryptionKey } from './types.js';
+
+/**
+ * 生成文件加密密钥对。
+ * - key: 32 字节随机（AES-256）
+ * - iv: 16 字节随机
+ */
+export function generateFileKey(): FileEncryptionKey {
+  return {
+    key: new Uint8Array(crypto.randomBytes(32)),
+    iv: new Uint8Array(crypto.randomBytes(16)),
+  };
+}
+
+/**
+ * AES-256-CTR XOR 操作（加密/解密共用，CTR 模式对称）。
+ * 支持从任意 offset 开始（分片 + 断点续传场景）。
+ *
+ * CTR 计数器规则（与 iOS 对齐）：
+ *   - IV 前 12 字节固定不变
+ *   - IV 后 4 字节作为 big-endian 32-bit counter
+ *   - blockIndex = Math.floor(plaintextOffset / 16)
+ *   - counter = initialCounter + blockIndex
+ *
+ * @param data             输入数据（明文或密文）
+ * @param key              AES-256 密钥（32 字节）
+ * @param iv               初始向量（16 字节）
+ * @param plaintextOffset  数据在完整文件中的字节偏移量
+ * @returns 输出数据（密文或明文）
+ */
+export function aesCtrXor(
+  data: Uint8Array,
+  key: Uint8Array,
+  iv: Uint8Array,
+  plaintextOffset: number,
+): Uint8Array {
+  if (key.length !== 32) {
+    throw new Error(`Invalid key length: expected 32 bytes, got ${key.length}`);
+  }
+  if (iv.length !== 16) {
+    throw new Error(`Invalid iv length: expected 16 bytes, got ${iv.length}`);
+  }
+
+  if (data.length === 0) {
+    return new Uint8Array(0);
+  }
+
+  // 计算起始 block 的 counter 值
+  const initialCounter = iv[12]! * 0x1000000 + iv[13]! * 0x10000 + iv[14]! * 0x100 + iv[15]!;
+  const blockIndex = Math.floor(plaintextOffset / 16);
+  const currentCounter = initialCounter + blockIndex;
+
+  // 构造调整后的 IV：前 12 字节不变，后 4 字节写入 currentCounter
+  const adjustedIv = Buffer.alloc(16);
+  iv.slice(0, 12).forEach((b, i) => (adjustedIv[i] = b));
+  adjustedIv.writeUInt32BE(currentCounter >>> 0, 12);
+
+  // 处理 offset 不在 block 边界的情况：需要跳过 block 内的前几个字节
+  const blockOffset = plaintextOffset % 16;
+
+  if (blockOffset === 0) {
+    // 对齐到 block 边界，直接加密
+    const cipher = crypto.createCipheriv('aes-256-ctr', key, adjustedIv);
+    const result = cipher.update(data);
+    cipher.final(); // CTR 模式 final 不产出额外数据
+    return new Uint8Array(result);
+  }
+
+  // 不在 block 边界：先填充 blockOffset 个零字节消耗 keystream，再处理实际数据
+  const padding = Buffer.alloc(blockOffset);
+  const cipher = crypto.createCipheriv('aes-256-ctr', key, adjustedIv);
+  cipher.update(padding); // 消耗前 blockOffset 字节的 keystream
+  const result = cipher.update(data);
+  cipher.final();
+  return new Uint8Array(result);
+}
+
+/**
+ * 计算数据的 SHA256 摘要（小写十六进制）。
+ */
+export function sha256Hex(data: Uint8Array): string {
+  return crypto.createHash('sha256').update(data).digest('hex');
+}

package/src/file-transfer/index.ts

@@ -0,0 +1,18 @@
+/**
+ * file-transfer/index.ts — 统一导出文件传输模块的公共接口
+ */
+
+export { generateFileKey, aesCtrXor, sha256Hex } from './file-crypto.js';
+export { uploadEncryptedFile } from './upload.js';
+export { downloadAndDecryptFile } from './download.js';
+export { runConcurrent } from './concurrency.js';
+export { resumePendingUploads, resumePendingDownloads } from './scheduler.js';
+export type {
+  FileEncryptionKey,
+  UploadResult,
+  UploadSendContext,
+  DownloadAndDecryptParams,
+  DownloadResult,
+  DownloadMessageContext,
+  FileTransferConfig,
+} from './types.js';

package/src/file-transfer/scheduler.ts

@@ -0,0 +1,185 @@
+/**
+ * scheduler.ts — 断点续传恢复调度器
+ *
+ * 在 gateway 启动时（startAccount）扫描 stateDir，
+ * 对未完成的上传/下载任务启动恢复，过期任务清理。
+ *
+ * 对齐 iOS 的 LargeAttachmentUploadScheduler：
+ *   - 启动时扫描未完成任务并恢复
+ *   - 异步执行（fire-and-forget），不阻塞轮询启动
+ *   - 单个任务失败不阻断其他任务
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { UploadState, UploadResult, DownloadState } from './types.js';
+import { uploadEncryptedFile } from './upload.js';
+import { downloadAndDecryptFile, clearDownloadState } from './download.js';
+
+// 过期阈值
+const UPLOAD_EXPIRY_MS = 24 * 60 * 60 * 1000; // 24 小时
+const DOWNLOAD_EXPIRY_MS = 7 * 24 * 60 * 60 * 1000; // 7 天
+
+/**
+ * 扫描并恢复未完成的上传任务。
+ * 异步执行不阻塞调用方。
+ *
+ * - 扫描 stateDir 中所有 upload-*.json
+ * - 超过 24 小时未更新的视为过期并清理
+ * - 未过期的启动恢复上传，完成后调用 onUploadComplete
+ * - 单个任务失败记录 WARN 日志，不阻断其他任务
+ */
+export async function resumePendingUploads(params: {
+  stateDir: string;
+  auth: { apiKey: string; apiSecret: string };
+  apiBaseUrl: string;
+  onUploadComplete: (state: UploadState, result: UploadResult) => Promise<void>;
+  log?: { info?: (...args: unknown[]) => void; warn?: (...args: unknown[]) => void };
+}): Promise<void> {
+  const { stateDir, auth, apiBaseUrl, onUploadComplete, log } = params;
+
+  if (!stateDir) return;
+
+  let files: string[];
+  try {
+    files = fs.readdirSync(stateDir).filter((f) => f.startsWith('upload-') && f.endsWith('.json'));
+  } catch {
+    // stateDir 不存在，无需恢复
+    return;
+  }
+
+  if (files.length === 0) return;
+
+  log?.info?.(`[scheduler] 发现 ${files.length} 个待恢复上传任务`);
+
+  const now = Date.now();
+  const tasks: Promise<void>[] = [];
+
+  for (const file of files) {
+    const filePath = path.join(stateDir, file);
+    let state: UploadState;
+    try {
+      const raw = fs.readFileSync(filePath, 'utf-8');
+      state = JSON.parse(raw) as UploadState;
+    } catch {
+      log?.warn?.(`[scheduler] 读取上传状态文件失败: ${file}`);
+      continue;
+    }
+
+    // 过期检查：超过 24 小时未更新则清理
+    if (now - state.updatedAt > UPLOAD_EXPIRY_MS) {
+      log?.info?.(`[scheduler] 上传状态已过期，清理: ${file}`);
+      try {
+        fs.unlinkSync(filePath);
+      } catch {
+        // 清理失败忽略
+      }
+      continue;
+    }
+
+    // 启动恢复任务
+    const task = (async () => {
+      try {
+        const result = await uploadEncryptedFile(state.mediaUrl, auth, apiBaseUrl, {
+          imMainAccId: state.imMainAccId,
+          config: { stateDir },
+          sendContext: state.sendContext,
+          log,
+        });
+        await onUploadComplete(state, result);
+        log?.info?.(`[scheduler] 上传恢复完成: ${state.mediaUrl}`);
+      } catch (err) {
+        log?.warn?.(`[scheduler] 上传恢复失败: ${state.mediaUrl}, ${String(err)}`);
+      }
+    })();
+
+    tasks.push(task);
+  }
+
+  // 并行执行所有恢复任务
+  await Promise.allSettled(tasks);
+}
+
+/**
+ * 扫描并恢复未完成的下载任务。
+ * 异步执行不阻塞调用方。
+ *
+ * - 扫描 stateDir 中所有 *.partial.meta 文件
+ * - 超过 7 天未更新的视为过期并清理（含 .partial 文件）
+ * - 未过期的启动恢复下载，完成后调用 onDownloadComplete
+ * - 单个任务失败记录 WARN 日志，不阻断其他任务
+ */
+export async function resumePendingDownloads(params: {
+  stateDir: string;
+  auth: { apiKey: string; apiSecret: string };
+  apiBaseUrl: string;
+  onDownloadComplete: (state: DownloadState, localPath: string) => Promise<void>;
+  log?: { info?: (...args: unknown[]) => void; warn?: (...args: unknown[]) => void };
+}): Promise<void> {
+  const { stateDir, auth, apiBaseUrl, onDownloadComplete, log } = params;
+
+  if (!stateDir) return;
+
+  let files: string[];
+  try {
+    files = fs.readdirSync(stateDir).filter((f) => f.endsWith('.partial.meta'));
+  } catch {
+    // stateDir 不存在，无需恢复
+    return;
+  }
+
+  if (files.length === 0) return;
+
+  log?.info?.(`[scheduler] 发现 ${files.length} 个待恢复下载任务`);
+
+  const now = Date.now();
+  const tasks: Promise<void>[] = [];
+
+  for (const file of files) {
+    const metaPath = path.join(stateDir, file);
+    let state: DownloadState;
+    try {
+      const raw = fs.readFileSync(metaPath, 'utf-8');
+      state = JSON.parse(raw) as DownloadState;
+    } catch {
+      log?.warn?.(`[scheduler] 读取下载状态文件失败: ${file}`);
+      continue;
+    }
+
+    // 过期检查：超过 7 天未更新则清理
+    if (now - state.updatedAt > DOWNLOAD_EXPIRY_MS) {
+      log?.info?.(`[scheduler] 下载状态已过期，清理: ${file}`);
+      // savePath = metaPath 去掉 .partial.meta 后缀
+      const savePath = metaPath.replace(/\.partial\.meta$/, '');
+      clearDownloadState(savePath);
+      continue;
+    }
+
+    // 需要 messageContext 才能恢复（否则无法分发）
+    if (!state.messageContext) {
+      log?.warn?.(`[scheduler] 下载状态缺少 messageContext，跳过: ${file}`);
+      continue;
+    }
+
+    // 启动恢复任务
+    const task = (async () => {
+      try {
+        // savePath = metaPath 去掉 .partial.meta 后缀
+        const savePath = metaPath.replace(/\.partial\.meta$/, '');
+
+        // 恢复下载需要原始参数，从 state 中无法完全恢复（缺少 key/iv/digest 等）
+        // 下载恢复依赖调用方再次调用 downloadAndDecryptFile 时自动检测 .partial.meta
+        // scheduler 层面仅通知调用方有待恢复的任务
+        await onDownloadComplete(state, savePath);
+        log?.info?.(`[scheduler] 下载恢复通知完成: ${file}`);
+      } catch (err) {
+        log?.warn?.(`[scheduler] 下载恢复失败: ${file}, ${String(err)}`);
+      }
+    })();
+
+    tasks.push(task);
+  }
+
+  // 并行执行所有恢复任务
+  await Promise.allSettled(tasks);
+}

package/src/file-transfer/types.ts

@@ -0,0 +1,195 @@
+/**
+ * types.ts — 文件传输模块的共享类型定义
+ *
+ * 定义加密密钥、分片计划、断点续传状态、上传/下载结果和配置等接口。
+ * 与 iOS 客户端的双层加密 + 分片传输架构对齐。
+ */
+
+/** 文件加密密钥对 */
+export interface FileEncryptionKey {
+  /** AES-256 密钥，32 字节 */
+  key: Uint8Array;
+  /** 初始向量，16 字节 */
+  iv: Uint8Array;
+}
+
+/** 分片计划 */
+export interface ChunkPlan {
+  /** 分片大小（字节），默认 2MB */
+  chunkSize: number;
+  /** 总分片数 */
+  totalChunks: number;
+  /** 文件总大小（字节） */
+  fileSize: number;
+}
+
+/** 单个分片的上传状态 */
+export interface ChunkStatus {
+  /** 分片索引（0-based） */
+  index: number;
+  /** 是否已上传完成 */
+  completed: boolean;
+  /** 上传成功后的 ETag */
+  etag?: string;
+}
+
+/** 消息发送上下文（断点续传恢复后需要） */
+export interface UploadSendContext {
+  /** 接收方 userId */
+  to: string;
+  /** 发送方 botAcctId */
+  fromId: string;
+  /** 媒体类型 */
+  mediaType: 'image' | 'video' | 'audio' | 'file';
+  /** 文字说明 */
+  caption?: string;
+  /** 文件名 */
+  fileName?: string;
+  /** MIME 类型 */
+  mimeType?: string;
+}
+
+/** 上传断点续传状态（持久化到 JSON 文件） */
+export interface UploadState {
+  /** 服务端返回的 fileId */
+  fileId: string;
+  /** 原始文件名（用于 initMultipartUpload 的 fileName 参数） */
+  fileName: string;
+  /** 原始媒体 URL 或路径（断点续传恢复时用于重新定位文件） */
+  mediaUrl: string;
+  /** IM 主账号 ID（API 接口必填参数） */
+  imMainAccId: string;
+  /** 明文文件大小 */
+  plaintextLength: number;
+  /** 分片大小 */
+  chunkSize: number;
+  /** 总分片数 */
+  totalChunks: number;
+  /** AES-256 密钥（hex 编码，持久化用） */
+  keyHex: string;
+  /** AES-CTR IV（hex 编码，持久化用） */
+  ivHex: string;
+  /** 各分片状态 */
+  chunks: ChunkStatus[];
+  /** 消息发送上下文（断点续传恢复后需要，用于上传完成后自动发送消息） */
+  sendContext: UploadSendContext;
+  /** 上传会话过期时间（毫秒时间戳，initMultipartUpload 返回，断点续传恢复后仍需） */
+  expireTime?: number;
+  /** 创建时间戳 */
+  createdAt: number;
+  /** 最后更新时间戳 */
+  updatedAt: number;
+}
+
+/** 消息分发上下文（断点续传恢复后需要） */
+export interface DownloadMessageContext {
+  /** 消息 ID */
+  msgId: string;
+  /** 发送者 ID */
+  senderId: string;
+  /** 消息内容（文本部分） */
+  content: string;
+  /** 消息时间戳 */
+  timestampMs: number;
+}
+
+/** 下载断点续传状态（持久化到 .partial.meta 文件） */
+export interface DownloadState {
+  /** 远程文件 ETag（用于检测文件变更） */
+  etag: string;
+  /** 分片大小 */
+  chunkSize: number;
+  /** 总分片数 */
+  totalChunks: number;
+  /** 文件总大小（密文） */
+  fileSize: number;
+  /** 已下载完成的分片索引集合 */
+  downloadedChunks: number[];
+  /** 消息分发上下文（断点续传恢复后需要，用于下载完成后分发给 AI agent） */
+  messageContext?: DownloadMessageContext;
+  /** 创建时间戳 */
+  createdAt: number;
+  /** 最后更新时间戳 */
+  updatedAt: number;
+}
+
+/** 上传结果 */
+export interface UploadResult {
+  /** 平台可访问的文件 URL（密文） */
+  url: string;
+  /** AES-256 加密密钥（32 字节） */
+  fileKey: Uint8Array;
+  /** AES-CTR 初始向量（16 字节） */
+  fileIv: Uint8Array;
+  /** SHA256(plaintext) 小写十六进制 */
+  fileDigest: string;
+  /** 明文长度（字节） */
+  plaintextLength: number;
+  /** 操作凭证（下载回调用） */
+  opCreds?: string;
+  /** 文件 MIME 类型 */
+  contentType?: string;
+  /** 图片 blurhash */
+  blurHash?: string;
+  /** 图片宽度 */
+  width?: number;
+  /** 图片高度 */
+  height?: number;
+  /** 上传会话过期时间（毫秒时间戳），用于填充 PbChatFileMeta.expireTime */
+  expireTime?: number;
+}
+
+/** 下载并解密的参数 */
+export interface DownloadAndDecryptParams {
+  /** 文件下载短链接 URL，格式：https://xxx/api/im/media/shortLink?shortCode=xxx */
+  url: string;
+  /** AES-256 密钥（32 字节） */
+  key: Uint8Array;
+  /** AES-CTR IV（16 字节） */
+  iv: Uint8Array;
+  /** 期望的 SHA256(plaintext) 摘要 */
+  digest: string;
+  /** 明文长度（字节） */
+  plaintextLength: number;
+  /** 操作凭证（下载完成回调用） */
+  opCreds?: string;
+  /** IM 主账号 ID（downloadCallback 必填） */
+  imMainAccId?: string;
+  /** 本地保存路径（不含扩展名，由调用方决定） */
+  savePath: string;
+  /** 并发数（默认 3） */
+  concurrency?: number;
+  /** 消息分发上下文（用于断点续传恢复后分发） */
+  messageContext?: DownloadMessageContext;
+}
+
+/** 下载结果 */
+export interface DownloadResult {
+  /** 解密后的本地文件路径 */
+  localPath: string;
+  /** 验证通过的 digest */
+  digest: string;
+}
+
+/** 文件传输配置 */
+export interface FileTransferConfig {
+  /** 分片大小（字节），默认 2MB */
+  chunkSize?: number;
+  /** 上传并发数，默认 3 */
+  uploadConcurrency?: number;
+  /** 下载并发数，默认 3 */
+  downloadConcurrency?: number;
+  /** 上传状态持久化目录（使用 botAcctId 作为路径标识，与 pullState 一致） */
+  stateDir?: string;
+  /** Stream 模式阈值（字节），默认 10MB，超过此大小使用 Stream 模式 */
+  streamThreshold?: number;
+}
+
+/** 默认配置 */
+export const DEFAULT_CONFIG: Required<FileTransferConfig> = {
+  chunkSize: 2 * 1024 * 1024, // 2MB
+  uploadConcurrency: 3,
+  downloadConcurrency: 3,
+  stateDir: '',
+  streamThreshold: 10 * 1024 * 1024, // 10MB
+};