@imweapp/openclaw-imwe 2026.4.12-alpha.1

package/src/e2ee/api.ts

@@ -0,0 +1,261 @@
+/**
+ * e2ee/api.ts — E2EE HTTP API（首期：payload 构造工厂）
+ *
+ * 对应设计：docs/07-E2EE单聊实现设计.md §2.5 / §3.4；requirements R3、R11。
+ *
+ * 本文件首期仅承载 `buildE2eeDeviceUploadPayload`，用于 `/e2eeDevice/create`
+ * 与 `/e2eeDevice/replenish` 请求体中的 `uploadId / md5Sum / e2eeDeviceJson`
+ * 三个字段构造。与 iOS `EncryptionKeysPerIMAccount.toRequestParams` 对齐：
+ *
+ *   encryptionKeysPerIMAccount = {
+ *     imAcctId,
+ *     e2eeId,
+ *     identityKey,
+ *     oneTimeKeys: string[],   // base64
+ *     fallbackKeys: string[],  // base64
+ *   }
+ *
+ *   md5Sum        = hex(md5(sortedJson([encryptionKeysPerIMAccount])))
+ *   e2eeDeviceJson = sortedJson([encryptionKeysPerIMAccount])
+ *
+ * 使用 `./canonical.ts` 的 `sortedJsonStringify` / `buildMd5Sum` 保证两个字段
+ * 基于同一份规范化字节串产出；相同输入必得相同 md5Sum / e2eeDeviceJson。
+ *
+ * HTTP 端点封装对齐 open-bot E2EE 接口：create / replenish /
+ * querySupplement / getPreKeyBundle。
+ */
+
+import { randomUUID } from 'node:crypto';
+
+import { postJson } from '../api-client.js';
+import { buildMd5Sum, sortedJsonStringify } from './canonical.js';
+import { NoPeerDeviceError } from './errors.js';
+import type { E2eeDeviceStatus } from './types.js';
+
+/** `/e2eeDevice/create` 与 `/replenish` 请求体中的上传 payload 输入 */
+export interface BuildE2eeDeviceUploadPayloadParams {
+  imAcctId: string;
+  e2eeId: string;
+  identityKey: string;
+  /** base64 编码的 OTK 公钥列表 */
+  oneTimeKeys: string[];
+  /** base64 编码的 FBK 公钥列表 */
+  fallbackKeys: string[];
+}
+
+/** 构造出的上传三元组 */
+export interface E2eeDeviceUploadPayload {
+  /** 32 字符 UUID hex；幂等键 */
+  uploadId: string;
+  /** 小写十六进制 MD5（对 [encryptionKeysPerIMAccount] 的 sortedJson 字节串取摘要） */
+  md5Sum: string;
+  /** 规范化 JSON 字符串；与计算 md5Sum 的字节串完全一致 */
+  e2eeDeviceJson: string;
+}
+
+/**
+ * 构造 `/e2eeDevice/create` 与 `/replenish` 的上传 payload。
+ *
+ * - `uploadId` 使用 32 字符 UUID hex；每次调用独立生成，用于服务端幂等键。
+ * - `md5Sum` = `buildMd5Sum([encryptionKeysPerIMAccount])`，对**数组**做 sortedJson
+ *   后取 MD5 小写 hex，与 iOS 保持逐字节一致。
+ * - `e2eeDeviceJson` = `sortedJsonStringify([encryptionKeysPerIMAccount])`，
+ *   复用同一规范化路径，保证服务端拿到的 JSON 字节与 md5Sum 输入严格对应。
+ *
+ * 纯函数（除 UUID 随机性外无 I/O）；相同输入参数产出确定性 md5Sum / e2eeDeviceJson。
+ */
+export function buildE2eeDeviceUploadPayload(
+  params: BuildE2eeDeviceUploadPayloadParams,
+): E2eeDeviceUploadPayload {
+  const encryptionKeysPerIMAccount = {
+    imAcctId: params.imAcctId,
+    e2eeId: params.e2eeId,
+    identityKey: params.identityKey,
+    oneTimeKeys: [...params.oneTimeKeys],
+    fallbackKeys: [...params.fallbackKeys],
+  };
+  const payloads = [encryptionKeysPerIMAccount];
+
+  return {
+    uploadId: randomUUID().replaceAll('-', ''),
+    md5Sum: buildMd5Sum(payloads),
+    e2eeDeviceJson: sortedJsonStringify(payloads),
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// open-bot E2EE HTTP 端点封装（docs/02-OpenAPI接口设计.md §九~十二）
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** `/e2eeDevice/create` 与 `/replenish` 请求体（对齐 iOS `EncryptionKeysPerIMAccount.toRequestParams`） */
+export interface CreateDeviceRequest {
+  imAcctId: string;
+  e2eeId: string;
+  identityKey: string;
+  oneTimeKeys: string[];
+  fallbackKeys: string[];
+}
+
+/** getPreKeyBundle 返回的 PreKeyBundle（oneTimeKey 可能承载 OTK 或 fallback key） */
+export interface PreKeyBundle {
+  acctId: string;
+  e2eeId: string;
+  identityKey: string;
+  signedPreKey?: string;
+  signedPreKeySignature?: string;
+  oneTimeKey: string;
+}
+
+/** `/e2eeDevice/querySupplement` 响应 */
+export interface QuerySupplementResponse {
+  e2eeId: string;
+  status: E2eeDeviceStatus;
+  identityKey?: string;
+  oneTimeKeyCount?: number;
+  fallbackKeyCount?: number;
+  oneTimeKeyRequireNum?: number;
+  fallbackKeyRequireNum?: number;
+  needsSupplement?: boolean;
+}
+
+/** E2EE HTTP API 对外契约 */
+export interface E2eeApi {
+  /** 新建 / 替换本设备。`uploadId` / `md5Sum` / `e2eeDeviceJson` 由内部 `buildE2eeDeviceUploadPayload` 生成。 */
+  createDevice(params: CreateDeviceRequest): Promise<void>;
+
+  /** 补充 OTK / FBK。请求体与 `createDevice` 完全同构，仅路径不同。 */
+  replenish(params: CreateDeviceRequest): Promise<void>;
+
+  /** 查询本机设备密钥状态。 */
+  querySupplement(e2eeId: string): Promise<QuerySupplementResponse>;
+
+  /** 单目标 PreKeyBundle 申请（单聊主路径）。 */
+  getPreKeyBundle(params: {
+    otherImAcctId: string;
+    /** 指定目标设备；为空字符串时由服务端按账号选择。 */
+    otherE2eeId: string;
+  }): Promise<PreKeyBundle>;
+}
+
+/**
+ * 构造 E2EE HTTP API 客户端。
+ *
+ * - 所有端点经 `postJson`（api-client.ts）发出，复用既有 HMAC-SHA256 签名链路。
+ * - 错误语义：`postJson` 对非 2xx 已经抛错；本层只额外处理 PreKeyBundle 字段不全。
+ */
+export function createE2eeApi(opts: {
+  apiBaseUrl: string;
+  auth: { apiKey: string; apiSecret: string };
+}): E2eeApi {
+  const { apiBaseUrl, auth } = opts;
+
+  // 构造 create / replenish 的请求体
+  const toUploadBody = (
+    processType: 'CREATE' | 'REPLENISH',
+    params: CreateDeviceRequest,
+  ): Record<string, unknown> => {
+    const payload = buildE2eeDeviceUploadPayload(params);
+    console.log(
+      'Create JSON ',
+      JSON.stringify({
+        processType,
+        deviceType: 'BOT',
+        uploadId: payload.uploadId,
+        batchCount: 1,
+        batchNo: 1,
+        md5Sum: payload.md5Sum,
+        e2eeDeviceJson: payload.e2eeDeviceJson,
+      }),
+    );
+    return {
+      processType,
+      deviceType: 'BOT',
+      uploadId: payload.uploadId,
+      batchCount: 1,
+      batchNo: 1,
+      md5Sum: payload.md5Sum,
+      e2eeDeviceJson: payload.e2eeDeviceJson,
+    };
+  };
+
+  return {
+    async createDevice(params) {
+      await postJson<unknown>(
+        apiBaseUrl,
+        '/api/im/open/bot/e2eeDevice/create',
+        toUploadBody('CREATE', params),
+        auth,
+      );
+    },
+
+    async replenish(params) {
+      await postJson<unknown>(
+        apiBaseUrl,
+        '/api/im/open/bot/e2eeDevice/replenish',
+        toUploadBody('REPLENISH', params),
+        auth,
+      );
+    },
+
+    async querySupplement(e2eeId) {
+      return postJson<QuerySupplementResponse>(
+        apiBaseUrl,
+        '/api/im/open/bot/e2eeDevice/querySupplement',
+        { e2eeId },
+        auth,
+      );
+    },
+
+    async getPreKeyBundle(params) {
+      const raw = await postJson<unknown>(
+        apiBaseUrl,
+        '/api/im/open/bot/e2eeDevice/getPreKeyBundle',
+        { otherImAcctId: params.otherImAcctId, otherE2eeId: params.otherE2eeId },
+        auth,
+      );
+      return parsePreKeyBundle(raw, params.otherImAcctId, params.otherE2eeId);
+    },
+  };
+}
+
+/** 解析 getPreKeyBundle 响应，并把字段不全统一映射为 NoPeerDeviceError。 */
+function parsePreKeyBundle(raw: unknown, otherImAcctId: string, otherE2eeId: string): PreKeyBundle {
+  if (raw === null || typeof raw !== 'object') {
+    throw new NoPeerDeviceError('getPreKeyBundle 响应不是对象', otherImAcctId);
+  }
+  const obj = raw as Record<string, unknown>;
+  const acctId = pickString(obj, ['acctId', 'imAcctId']);
+  const e2eeId = pickString(obj, ['e2eeId']);
+  const identityKey = pickString(obj, ['identityKey']);
+  const oneTimeKey = pickString(obj, ['oneTimeKey']);
+
+  if (!acctId || !e2eeId || !identityKey || !oneTimeKey) {
+    throw new NoPeerDeviceError(
+      `getPreKeyBundle 响应字段不全 (acctId=${!!acctId}, e2eeId=${!!e2eeId}, identityKey=${!!identityKey}, oneTimeKey=${!!oneTimeKey})`,
+      otherImAcctId,
+    );
+  }
+  if (otherE2eeId && e2eeId !== otherE2eeId) {
+    throw new NoPeerDeviceError('getPreKeyBundle 返回的 e2eeId 与目标设备不匹配', otherImAcctId);
+  }
+
+  return {
+    acctId,
+    e2eeId,
+    identityKey,
+    signedPreKey: pickString(obj, ['signedPreKey']) || undefined,
+    signedPreKeySignature: pickString(obj, ['signedPreKeySignature']) || undefined,
+    oneTimeKey,
+  };
+}
+
+/** 从对象里按 key 优先级取第一个非空字符串，全部缺失时返回空串。 */
+function pickString(obj: Record<string, unknown>, keys: readonly string[]): string {
+  for (const key of keys) {
+    const value = obj[key];
+    if (typeof value === 'string' && value.length > 0) {
+      return value;
+    }
+  }
+  return '';
+}

package/src/e2ee/canonical.ts

@@ -0,0 +1,59 @@
+/**
+ * canonical.ts — E2EE 规范化序列化与 md5Sum
+ *
+ * 对应设计：docs/07-E2EE单聊实现设计.md §2.5；requirements R11
+ *
+ * 为对齐 iOS `JSONSerialization.data(options:.sortedKeys)` + `Data.md5()`，本模块提供：
+ *   - sortedJsonStringify(value): 递归按 key 字典序排序对象字段，再 UTF-8 JSON 序列化；
+ *     对 undefined 字段按 JSON.stringify 原始行为忽略；数组元素保持原顺序（仅递归元素内部）。
+ *   - buildMd5Sum(payloads): 对数组做 sortedJsonStringify → Node 'md5' 摘要 → 小写 hex。
+ *
+ * 设计约束：
+ *   - 使用 MD5（**不是** SHA-256），仅用于上传完整性校验，不承担密码学安全。
+ *   - 纯函数，无 I/O，无副作用；相同输入必得相同输出。
+ */
+
+import { createHash } from 'node:crypto';
+
+/**
+ * 递归规范化：对 object 字段按 key 字典序重排，对 array 保持顺序仅递归元素，
+ * 对 null / primitives 原样返回；undefined 字段由下游 JSON.stringify 自然忽略。
+ */
+function canonicalize(value: unknown): unknown {
+  if (value === null || typeof value !== 'object') {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return value.map(canonicalize);
+  }
+  const entries = value as Record<string, unknown>;
+  const sortedKeys = Object.keys(entries).sort();
+  const result: Record<string, unknown> = {};
+  for (const key of sortedKeys) {
+    const child = entries[key];
+    if (child === undefined) continue; // 与 JSON.stringify 一致，忽略 undefined 字段
+    result[key] = canonicalize(child);
+  }
+  return result;
+}
+
+/**
+ * 对输入递归按 key 字典序排序后 UTF-8 JSON 序列化。
+ *
+ * - 数组保持原顺序（只对元素递归）
+ * - undefined 字段被忽略（与 JSON.stringify 一致）
+ * - 跨调用确定性：相同 value 返回相同字符串
+ */
+export function sortedJsonStringify(value: unknown): string {
+  return JSON.stringify(canonicalize(value));
+}
+
+/**
+ * 计算 md5Sum：对 payloads 数组先 sortedJsonStringify，再取 MD5 小写 hex。
+ *
+ * 对齐 iOS `hex(md5(sortedJson([encryptionKeysPerIMAccount])))`。
+ */
+export function buildMd5Sum(payloads: unknown[]): string {
+  const canonicalJson = sortedJsonStringify(payloads);
+  return createHash('md5').update(canonicalJson, 'utf8').digest('hex');
+}

package/src/e2ee/errors.ts

@@ -0,0 +1,103 @@
+/**
+ * e2ee/errors.ts — E2EE 子系统错误类型
+ *
+ * 对应设计：design.md §3 + requirements R4 / R7 / R10。
+ *
+ * 分类原则：
+ *   - NoPeerDeviceError：对端未启用 E2EE / apply 响应缺字段 / e2eeId 不匹配 →
+ *     视作 ACCOUNT_E2EE_NOT_EXISTS；上层必须"失败不降级"，不得以明文发送兜底。
+ *   - DeviceNotMatchError：服务端识别本端持有的对端设备集合与实际不一致，
+ *     附带 device 级（单聊）或账号级（群聊）的差异列表。
+ *   - E2eeApiError：HTTP 4xx/5xx 的通用兜底。
+ *   - E2eeAccountNormalizeError：normalizeFreshAccount 超过 4 轮仍未收敛。
+ *   - SingleNoAvailableRecipientOrSession：encryptSingle peer-must-exist 校验失败。
+ *   - E2eeEncryptFailedError：所有活跃 session encrypt 全部失败。
+ */
+
+/** `ACCOUNT_E2EE_NOT_EXISTS` 语义：对端未启用 E2EE / apply 响应无效。 */
+export class NoPeerDeviceError extends Error {
+  readonly code = 'ACCOUNT_E2EE_NOT_EXISTS';
+
+  constructor(
+    message: string,
+    public readonly peerImAcctId: string,
+  ) {
+    super(message);
+    this.name = 'NoPeerDeviceError';
+  }
+}
+
+/** DEVICE_NOT_MATCH：服务端返回的本端对端设备集合与实际不一致。 */
+export class DeviceNotMatchError extends Error {
+  readonly code = 'E2EE_DEVICE_NOT_MATCH';
+
+  constructor(
+    message: string,
+    public readonly data: {
+      extraDevices?: Array<{ imAcctId: string; e2eeId: string }>;
+      missDevices?: Array<{ imAcctId: string; e2eeId: string }>;
+      extraImAcctIds?: string[];
+      missImAcctIds?: string[];
+    },
+  ) {
+    super(message);
+    this.name = 'DeviceNotMatchError';
+  }
+}
+
+/** E2EE HTTP 通用错误（4xx / 5xx / 网络异常）。 */
+export class E2eeApiError extends Error {
+  readonly code = 'E2EE_API_ERROR';
+
+  constructor(
+    message: string,
+    public readonly statusCode?: number,
+    public readonly responseBody?: string,
+  ) {
+    super(message);
+    this.name = 'E2eeApiError';
+  }
+}
+
+/**
+ * normalizeFreshAccount 自举 pickle/unpickle >4 轮仍未收敛时抛出。
+ * 永远不应把该 Account 的 pickle / curve25519Key 写入 state.json。
+ */
+export class E2eeAccountNormalizeError extends Error {
+  readonly code = 'E2EE_ACCOUNT_NORMALIZE_FAILED';
+
+  constructor(message = 'vodozemac Account 归一化失败：curve25519Key 连续 4 轮未收敛') {
+    super(message);
+    this.name = 'E2eeAccountNormalizeError';
+  }
+}
+
+/**
+ * encryptSingle 的 peer-must-exist 校验失败：
+ *   完成 getPreKeyBundle 协商后 `sessions[to]` 仍无任何活跃 session，
+ *   立即同步抛错，不得触发 `session.encrypt` 或额外 I/O（R6）。
+ */
+export class SingleNoAvailableRecipientOrSession extends Error {
+  readonly code = 'SINGLE_NO_AVAILABLE_RECIPIENT_OR_SESSION';
+
+  constructor(
+    message: string,
+    public readonly peerImAcctId: string,
+  ) {
+    super(message);
+    this.name = 'SingleNoAvailableRecipientOrSession';
+  }
+}
+
+/** 所有活跃 session 的 encrypt 都抛错时兜底抛出。 */
+export class E2eeEncryptFailedError extends Error {
+  readonly code = 'E2EE_ENCRYPT_FAILED';
+
+  constructor(
+    message: string,
+    public readonly peerImAcctId: string,
+  ) {
+    super(message);
+    this.name = 'E2eeEncryptFailedError';
+  }
+}

package/src/e2ee/index.ts

@@ -0,0 +1,8 @@
+/**
+ * e2ee/index.ts — E2EE 子系统公共接口聚合导出
+ */
+
+export { createE2eeService } from './service.js';
+export type { E2eeService, BotInfo } from './service.js';
+export { E2EE_DEVICE_STATUS } from './types.js';
+export type { E2eeDeviceStatus } from './types.js';

package/src/e2ee/proper-lockfile.d.ts

@@ -0,0 +1,61 @@
+/**
+ * 最小 ambient 声明：`proper-lockfile` 不提供官方 `@types` 包，
+ * 这里仅补齐本项目实际使用到的 `lock` / `unlock` / `check` 三个函数签名。
+ *
+ * 参考：https://github.com/moxystudio/node-proper-lockfile#api
+ */
+
+declare module 'proper-lockfile' {
+  /** `lockfile.lock` 的 retries 选项：数字或 `node-retry` 配置对象。 */
+  export interface LockRetryOptions {
+    retries?: number;
+    factor?: number;
+    minTimeout?: number;
+    maxTimeout?: number;
+    randomize?: boolean;
+  }
+
+  export interface LockOptions {
+    /** 重试次数，或完整的 retry 配置对象 */
+    retries?: number | LockRetryOptions;
+    /** 认为锁已陈旧（被 crash 的持有者遗留）的毫秒阈值，默认 10_000 */
+    stale?: number;
+    /** 锁心跳更新间隔（ms） */
+    update?: number;
+    /** 显式指定 lockfile 路径，默认 `${file}.lock` */
+    lockfilePath?: string;
+    /** 是否通过 `fs.realpath` 解析符号链接，默认 true */
+    realpath?: boolean;
+    /** 可选注入的 fs 实现（用于测试） */
+    fs?: unknown;
+    /** 进程退出时的兜底策略，默认 true */
+    onCompromised?: (err: Error) => void;
+  }
+
+  export interface UnlockOptions {
+    lockfilePath?: string;
+    realpath?: boolean;
+    fs?: unknown;
+  }
+
+  export interface CheckOptions extends UnlockOptions {
+    stale?: number;
+  }
+
+  /** 释放锁的 callback，多次调用仅首次生效。 */
+  export type ReleaseLock = () => Promise<void>;
+
+  /** 异步加锁。返回 release 函数。 */
+  export function lock(file: string, options?: LockOptions): Promise<ReleaseLock>;
+  /** 异步释放锁。 */
+  export function unlock(file: string, options?: UnlockOptions): Promise<void>;
+  /** 检查指定路径是否已被加锁。 */
+  export function check(file: string, options?: CheckOptions): Promise<boolean>;
+
+  const _default: typeof lock & {
+    lock: typeof lock;
+    unlock: typeof unlock;
+    check: typeof check;
+  };
+  export default _default;
+}