@imweapp/openclaw-imwe 2026.4.12-alpha.1

package/src/e2ee/store.ts

@@ -0,0 +1,174 @@
+/**
+ * store.ts — E2EE 本地状态文件（state.json）存储层
+ *
+ * 对应设计：design.md §2.3 / §3.2；requirements R9。
+ *
+ * 主要职责：
+ *   1. 目录路径拼接：`${stateDir}/channel-data/imwe/${botAcctId}/e2ee/state.json`
+ *   2. `createE2eeStore(opts)` 工厂 + `E2eeStore` 接口（`snapshot` / `update`）
+ *   3. 进程内 Promise 队列串行：所有 `update()` 共享同一 chain，保证先来先到
+ *   4. 跨进程 `proper-lockfile` 互斥 + 两阶段原子写（tmp + fsync + rename）
+ *
+ * 约束：
+ *   - `snapshot()` 不加锁、仅用于展示/日志；与并发 `update()` 存在天然读旧风险
+ *   - mutator 必须是纯函数，禁止在其内部发起网络请求
+ *   - `proper-lockfile` 要求被锁目标路径存在，因此 `update()` 进入锁临界区前
+ *     会先以 `wx` 独占标志兜底创建 state.json（已存在时忽略 EEXIST）
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import lockfile from 'proper-lockfile';
+
+import { DEFAULT_EMPTY_STATE, E2eeStateFileSchema, type E2eeStateFile } from './types.js';
+
+/**
+ * E2EE 状态文件存储接口。
+ *
+ * `update` 是变更 state.json 的**唯一入口**；`snapshot` 仅用于只读场景。
+ */
+export interface E2eeStore {
+  /**
+   * 加锁 + 读磁盘 + 跑 mutator + 两阶段写 + 释放锁。
+   *
+   * 实现要点：
+   *   - 进程内通过 Promise chain 串行化所有 `update`，保证 mutator 不交叉；
+   *   - 跨进程通过 `proper-lockfile.lock(state.json, { retries: 5, stale: 30_000 })`
+   *     兜底，避免两个 openclaw 进程同时写坏同一份 state.json；
+   *   - 写入走 tmp 文件 + fsync + rename，依赖 POSIX / NTFS 的 rename 原子性
+   *     保证崩溃场景下 state.json 要么是旧版本，要么是新版本，不会出现半行。
+   */
+  update<T>(mutator: (prev: E2eeStateFile) => { next: E2eeStateFile; result: T }): Promise<T>;
+
+  /**
+   * 只读快照（不加锁）。与 `update` 存在并发时可能读到较旧的数据，
+   * 仅用于展示/日志，不得作为写入前提。
+   */
+  snapshot(): Promise<E2eeStateFile>;
+}
+
+export function createE2eeStore(opts: {
+  accountId: string;
+  botAcctId: string;
+  stateDir: string;
+  log?: { warn?: (...args: unknown[]) => void };
+}): E2eeStore {
+  const { accountId, botAcctId, stateDir, log } = opts;
+
+  // state.json 目录与文件路径（使用 botAcctId 与 pullState 对齐，防止用户修改 accountId 但未改 appKey/appSecret）。
+  const stateFileDir = path.join(stateDir, 'channel-data', 'imwe', botAcctId, 'e2ee');
+  const stateFilePath = path.join(stateFileDir, 'state.json');
+  const stateFileTmpPath = `${stateFilePath}.tmp`;
+
+  /**
+   * 从磁盘加载 state.json：
+   *   - 目录不存在则 mkdir -p
+   *   - 文件不存在（ENOENT）→ 返回 DEFAULT_EMPTY_STATE
+   *   - JSON 解析或 zod schema 校验失败 → 自愈：重命名为 `state.json.corrupt-${ts}`
+   *     后回落 DEFAULT_EMPTY_STATE，并 WARN 日志（R9 第 6 条 / R15 第 5 条）
+   */
+  const load = (): E2eeStateFile => {
+    fs.mkdirSync(stateFileDir, { recursive: true });
+    let raw: string;
+    try {
+      raw = fs.readFileSync(stateFilePath, 'utf-8');
+    } catch (err) {
+      const errno = (err as NodeJS.ErrnoException).code;
+      if (errno === 'ENOENT') {
+        return DEFAULT_EMPTY_STATE({ accountId, botAcctId });
+      }
+      throw err;
+    }
+    try {
+      const parsed = JSON.parse(raw) as unknown;
+      return E2eeStateFileSchema.parse(parsed);
+    } catch {
+      const corruptPath = `${stateFilePath}.corrupt-${Date.now()}`;
+      try {
+        fs.renameSync(stateFilePath, corruptPath);
+      } catch {
+        // rename 失败也不阻断自愈：后续 ensureStateFileExists 会按 wx 兜底
+      }
+      log?.warn?.(`[e2ee][${accountId}] state.json 损坏已自愈 → ${corruptPath}`);
+      return DEFAULT_EMPTY_STATE({ accountId, botAcctId });
+    }
+  };
+
+  /**
+   * 确保 state.json 存在：`proper-lockfile` 以 `${file}.lock` 目录作为锁标记，
+   * 但仍要求被锁目标路径存在，否则 `realpath` 解析会抛 ENOENT。
+   *
+   * 使用 `wx` 独占标志：多进程竞态下仅首个创建者成功，其它进程遇到 EEXIST
+   * 会被忽略——初始内容相同，不影响正确性。
+   */
+  const ensureStateFileExists = (): void => {
+    fs.mkdirSync(stateFileDir, { recursive: true });
+    const init = DEFAULT_EMPTY_STATE({ accountId, botAcctId });
+    try {
+      fs.writeFileSync(stateFilePath, JSON.stringify(init), { encoding: 'utf-8', flag: 'wx' });
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== 'EEXIST') {
+        throw err;
+      }
+      // 已由其它进程/先前调用创建，OK。
+    }
+  };
+
+  /**
+   * 两阶段原子写：
+   *   1. open tmp 文件 → writeFile(JSON) → fsync → close
+   *   2. rename tmp → state.json（POSIX/NTFS 均为原子）
+   *
+   * fsync 保证 JSON bytes 落盘；rename 保证替换指针瞬间完成，
+   * 进程崩溃时 state.json 要么是旧版本完整副本，要么是新版本完整副本。
+   */
+  const writeAtomic = async (state: E2eeStateFile): Promise<void> => {
+    fs.mkdirSync(stateFileDir, { recursive: true });
+    const json = JSON.stringify(state);
+    const fh = await fs.promises.open(stateFileTmpPath, 'w');
+    try {
+      await fh.writeFile(json, 'utf-8');
+      await fh.sync();
+    } finally {
+      await fh.close();
+    }
+    await fs.promises.rename(stateFileTmpPath, stateFilePath);
+  };
+
+  /**
+   * 进程内 Promise 队列：通过单一 chain 保证所有 `update` 依序执行。
+   *
+   * 错误不传染下一次排队：每次 task 的 `.catch(() => undefined)` 只用来推进
+   * 队列指针，原始错误仍会以 `task` 的 rejection 抛回调用方。
+   */
+  let queue: Promise<unknown> = Promise.resolve();
+
+  const update = <T>(
+    mutator: (prev: E2eeStateFile) => { next: E2eeStateFile; result: T },
+  ): Promise<T> => {
+    const task = queue.then(async (): Promise<T> => {
+      // proper-lockfile 要求目标路径存在：先行确保 state.json 就位。
+      ensureStateFileExists();
+
+      const release = await lockfile.lock(stateFilePath, {
+        retries: 5,
+        stale: 30_000,
+      });
+      try {
+        const prev = load();
+        const { next, result } = mutator(prev);
+        await writeAtomic(next);
+        return result;
+      } finally {
+        await release();
+      }
+    });
+    queue = task.catch(() => undefined);
+    return task;
+  };
+
+  const snapshot = async (): Promise<E2eeStateFile> => load();
+
+  return { update, snapshot };
+}

package/src/e2ee/types.ts

@@ -0,0 +1,113 @@
+/**
+ * e2ee/types.ts — E2EE 本地状态文件（state.json）类型与 zod schema
+ *
+ * 字段与 design.md §2.3 的 `E2eeStateFile` 对齐。所有写入必须经 `E2eeStore.update`，
+ * 本文件只负责类型与 schema 定义，不包含落盘逻辑。
+ */
+
+import { z } from 'zod';
+
+/** 当前 state.json schema 版本；bump 时需同步迁移策略 */
+export const E2EE_STATE_FILE_VERSION = 1 as const;
+
+export const E2EE_DEVICE_STATUS = {
+  UNINITIALIZED: 'UNINITIALIZED',
+  NORMAL: 'NORMAL',
+  NEEDS_SUPPLEMENT: 'NEEDS_SUPPLEMENT',
+} as const;
+
+export type E2eeDeviceStatus = (typeof E2EE_DEVICE_STATUS)[keyof typeof E2EE_DEVICE_STATUS];
+
+/** 本地设备信息（bootstrap 完成后写入） */
+export const LocalDeviceSchema = z.object({
+  /** = Account.curve25519Key() 归一化后的稳定值 */
+  e2eeId: z.string(),
+  /** 冗余字段，= e2eeId，便于日志/调试 */
+  identityKey: z.string(),
+  /** pickleKey = sha256(e2eeId).prefix(32) */
+  accountPickle: z.string(),
+  createdAt: z.number(),
+  updatedAt: z.number(),
+});
+
+/** 对端 recipient（以 contactId = 对端 imAcctId 为 key） */
+export const RecipientSchema = z.object({
+  contactId: z.string(),
+  /** 对端 e2eeId 列表 */
+  deviceIds: z.array(z.string()),
+  unregisteredAt: z.number().optional(),
+  updatedAt: z.number(),
+});
+
+/** 单条 session（key = `${contactId}:${peerE2eeId}:${sessionId}`） */
+export const SessionSchema = z.object({
+  contactId: z.string(),
+  peerE2eeId: z.string(),
+  sessionId: z.string(),
+  /** pickleKey = sha256(sessionId).prefix(32) */
+  sessionPickle: z.string(),
+  isActive: z.boolean(),
+  createdAt: z.number(),
+  updatedAt: z.number(),
+  /** >0 表示不可用（staleTime 语义） */
+  staleAt: z.number().optional(),
+});
+
+/** PreKey 批次中的单个 key（OTK 或 FBK） */
+export const PreKeyEntrySchema = z.object({
+  keyType: z.enum(['otk', 'fallback']),
+  /** 来自 vodozemac OneTimeKeyInfo.keyId */
+  keyId: z.string(),
+  /** base64；用于隐式确认按 publicKey 匹配 */
+  publicKey: z.string(),
+});
+
+/** 单次 PreKey 上传批次（key = uploadId） */
+export const PreKeyBatchSchema = z.object({
+  uploadId: z.string(),
+  mode: z.enum(['create', 'replenish']),
+  state: z.enum(['pending', 'uploading', 'synced']),
+  keys: z.array(PreKeyEntrySchema),
+  retryCount: z.number(),
+  createdAt: z.number(),
+  updatedAt: z.number(),
+});
+
+/** E2EE 本地状态文件完整 schema */
+export const E2eeStateFileSchema = z.object({
+  version: z.literal(E2EE_STATE_FILE_VERSION),
+  accountId: z.string(),
+  /** 即 imAcctId */
+  botAcctId: z.string(),
+  local: LocalDeviceSchema.optional(),
+  recipients: z.record(z.string(), RecipientSchema),
+  sessions: z.record(z.string(), SessionSchema),
+  preKeyBatches: z.record(z.string(), PreKeyBatchSchema),
+});
+
+// ── 导出 TypeScript 类型（由 zod schema 推导，保持单一事实源） ──
+
+export type LocalDevice = z.infer<typeof LocalDeviceSchema>;
+export type Recipient = z.infer<typeof RecipientSchema>;
+export type Session = z.infer<typeof SessionSchema>;
+export type PreKeyEntry = z.infer<typeof PreKeyEntrySchema>;
+export type PreKeyBatch = z.infer<typeof PreKeyBatchSchema>;
+export type E2eeStateFile = z.infer<typeof E2eeStateFileSchema>;
+
+/**
+ * 空 state 工厂。首次启动或 state.json 损坏自愈后使用。
+ * 仅填必填字段，`local` 留空等待 bootstrap 写入。
+ */
+export function DEFAULT_EMPTY_STATE(params: {
+  accountId: string;
+  botAcctId: string;
+}): E2eeStateFile {
+  return {
+    version: E2EE_STATE_FILE_VERSION,
+    accountId: params.accountId,
+    botAcctId: params.botAcctId,
+    recipients: {},
+    sessions: {},
+    preKeyBatches: {},
+  };
+}

package/src/e2ee/vodozemac.ts

@@ -0,0 +1,373 @@
+/**
+ * e2ee/vodozemac.ts — vodozemac 薄封装（插件侧）
+ *
+ * 职责（对应 design.md §3.3 与 requirements R10）：
+ *   - 暴露 `pickleKey(input)` pickle 密钥派生（与 iOS `String.pickleKey` 对齐）。
+ *   - 暴露 `createVodozemacBinding()` 外壳：统一构造 Account / Session handle
+ *     的入口，并提供幂等的 `ready()` 懒加载钩子。
+ *   - 定义 `AccountHandle` / `SessionHandle` / `EncryptedBundle` 接口并通过
+ *     `wrapAccount` / `wrapSession` 复用实现；outbound / inbound / restore
+ *     路径共享同一套包装逻辑。
+ *
+ * 设计约束：
+ *   - 字节类型统一使用 `Uint8Array`，避免 base64 互转带来的歧义；
+ *   - 底层 vodozemac 实现严格从插件内嵌的 `../vodozemackit` 载入，
+ *     禁止旁路直接实例化 `WebAssembly.Module`（对应 requirement R12）；
+ *   - 本模块为纯 TypeScript 逻辑，不应被 codec 层顶层 import（requirement R12）。
+ */
+
+import { createHash } from 'node:crypto';
+
+import {
+  Account,
+  EncryptedMessage,
+  Session,
+  accountFromPickle,
+  sessionFromPickle,
+} from '../vodozemackit/index.js';
+import type { KeyMap, OneTimeKeyInfo } from '../vodozemackit/index.js';
+
+import { E2eeAccountNormalizeError } from './errors.js';
+
+// ─── 共享字节类型 ───────────────────────────────────────────────────────────
+
+/**
+ * vodozemac EncryptedMessage 的插件侧表示。
+ *
+ * `body` 对应 `PbSingleChatDeviceMsg.envelope` 字段,即 vodozemac
+ * `EncryptedMessage.body`(OlmMessage JSON 的 UTF-8 bytes)。
+ */
+export type EncryptedBundle = { body: Uint8Array };
+
+// ─── AccountHandle ──────────────────────────────────────────────────────────
+
+/**
+ * 单个本地 Account 的生命周期封装。
+ *
+ * 主要职责：
+ *   - 暴露稳定的 `e2eeId`（= `normalizeFreshAccount` 归一化后的 curve25519 公钥）
+ *   - 生成 OTK / FBK、标记已发布
+ *   - 构造 outbound / inbound session
+ *   - pickle / dispose 释放资源
+ */
+export interface AccountHandle {
+  /** = 归一化后的稳定 curve25519 公钥（base64） */
+  readonly e2eeId: string;
+
+  /** 返回 identity key（= `e2eeId`，便于调用侧语义区分） */
+  identityKey(): string;
+
+  /**
+   * 生成 `n` 个一次性密钥，返回新增列表与被挤出的 publicKey 列表。
+   * 行为对齐 `../vodozemackit` `Account.generateOneTimeKeysWithInfo`。
+   */
+  generateOneTimeKeysWithInfo(n: number): {
+    created: OneTimeKeyInfo[];
+    removed: string[];
+  };
+
+  /** 当前尚未发布的一次性密钥（含 keyId） */
+  oneTimeKeysWithInfo(): OneTimeKeyInfo[];
+
+  /** 尚未调用 `markKeysAsPublished` 的 OTK 数量 */
+  unpublishedOneTimeKeyCount(): number;
+
+  /** 生成一个兜底密钥（FBK），返回其 keyInfo */
+  generateFallbackKey(): OneTimeKeyInfo;
+
+  /** 标记当前所有已生成的 OTK / FBK 为已发布 */
+  markKeysAsPublished(): void;
+
+  /** 使用对端 identityKey + oneTimeKey 构造一个 outbound session */
+  createOutboundSession(peerIdentity: string, peerOneTimeKey: string): SessionHandle;
+
+  /**
+   * 接受对端发来的 PreKey 消息构造 inbound session，
+   * 返回 `{ session, plaintext, oneTimeKey(base64) }`。
+   * `oneTimeKey` 用于隐式确认对应 OTK 批次已送达。
+   */
+  createInboundSession(msg: EncryptedBundle): {
+    session: SessionHandle;
+    plaintext: Uint8Array;
+    oneTimeKey: string;
+  };
+
+  /** pickle 当前 Account 状态；内部使用 `pickleKey(e2eeId)` 派生密钥 */
+  pickle(): string;
+
+  /** 释放底层资源；调用后 handle 不可再用 */
+  dispose(): void;
+}
+
+// ─── SessionHandle ──────────────────────────────────────────────────────────
+
+/**
+ * 单条会话 session 的生命周期封装。
+ */
+export interface SessionHandle {
+  /** vodozemac session id */
+  readonly sessionId: string;
+
+  /** 对明文字节串加密，返回 EncryptedBundle */
+  encrypt(plainBytes: Uint8Array): EncryptedBundle;
+
+  /** 对密文 EncryptedBundle 解密，返回明文字节串 */
+  decrypt(msg: EncryptedBundle): Uint8Array;
+
+  /** 判断某条密文是否匹配当前 session */
+  matches(msg: EncryptedBundle): boolean;
+
+  /** pickle 当前 session 状态；内部使用 `pickleKey(sessionId)` 派生密钥 */
+  pickle(): string;
+
+  /** 释放底层资源；调用后 handle 不可再用 */
+  dispose(): void;
+}
+
+// ─── VodozemacBinding ───────────────────────────────────────────────────────
+
+/**
+ * vodozemac 绑定的顶层外壳。由 `createVodozemacBinding()` 创建；
+ * 在 `E2eeService` 构造时注入，所有 Account / Session 的生命周期由此入口管理。
+ */
+export interface VodozemacBinding {
+  /**
+   * 懒加载 WASM 的幂等入口。
+   *
+   * `../vodozemackit` 当前以 ESM 静态 import 形式加载 WASM；
+   * 此 `ready()` 保留为语义占位，便于未来切换到动态 import 时
+   * 在 `E2eeService.ensureLocalDevice` 内部以 `await binding.ready()` 统一阻塞。
+   * 多次调用必须幂等。
+   */
+  ready(): Promise<void>;
+
+  /**
+   * 新建 Account 并在内部完成 `normalizeFreshAccount` 归一化
+   * （≤4 轮 pickle/unpickle 直到 `curve25519Key()` 稳定）。
+   *
+   * 注：本 task 2.2 只返回 `curve25519Key()` 的直接取值作为 `e2eeId`；
+   * task 2.4 会在此处前置调用 `normalizeFreshAccount` 保证稳定性。
+   */
+  newAccount(): AccountHandle;
+
+  /** 从 pickle 字符串恢复 Account；pickle key = `pickleKey(e2eeId)` */
+  restoreAccount(e2eeId: string, pickle: string): AccountHandle;
+
+  /** 从 pickle 字符串恢复 Session；pickle key = `pickleKey(sessionId)` */
+  restoreSession(sessionId: string, pickle: string): SessionHandle;
+}
+
+/**
+ * `normalizeFreshAccount` — 自举 pickle/unpickle ≤4 轮直到 `curve25519Key()` 稳定。
+ *
+ * 对应 design.md §3.3.2 与 requirement R10：
+ * 新建 Account 在首次读取 curve25519Key() 后，再做一次 pickle→unpickle 有概率
+ * 返回与先前不同的 curve25519Key；iOS 通过"循环 pickle/unpickle 直到稳定"来收敛。
+ *
+ * 算法：
+ *   FOR round ∈ 1..4:
+ *     oldKey = account.curve25519Key()
+ *     pickle = account.pickle(pickleKey(oldKey))
+ *     account = accountFromPickle(pickle, pickleKey(oldKey))
+ *     newKey = account.curve25519Key()
+ *     if newKey == oldKey → return { account, stableE2eeId: newKey }
+ *   抛 E2eeAccountNormalizeError
+ *
+ * 前置条件：account 尚未 persist 过、尚未生成 OTK/FBK。
+ * 后置条件：返回的 account 满足 `pickle(pickleKey(e2eeId)) → unpickle → curve25519Key()` 与自身相等。
+ */
+export function normalizeFreshAccount(initial: Account): {
+  account: Account;
+  stableE2eeId: string;
+} {
+  let account = initial;
+  for (let round = 0; round < 4; round += 1) {
+    const oldKey = account.curve25519Key();
+    const pickle = account.pickle(pickleKey(oldKey));
+    account = accountFromPickle(pickle, pickleKey(oldKey));
+    const newKey = account.curve25519Key();
+    if (newKey === oldKey) {
+      return { account, stableE2eeId: newKey };
+    }
+  }
+  throw new E2eeAccountNormalizeError();
+}
+
+// ─── pickleKey 派生 ─────────────────────────────────────────────────────────
+
+/**
+ * pickle 密钥派生：`sha256(utf8(input))[0..32]`。
+ *
+ * - 与 iOS `String.pickleKey` 完全一致，确保跨端 pickle/unpickle 互通
+ *   （requirement R10.2）。
+ * - 返回的 Uint8Array 长度恒为 32（requirement R10.1）。
+ * - 相同 input 恒返回相同 key，调用之间无状态（requirement R10.2）。
+ *
+ * @param input 非空字符串，通常是 `e2eeId` 或 `sessionId`
+ * @returns 32 字节 Uint8Array
+ */
+export function pickleKey(input: string): Uint8Array {
+  const digest = createHash('sha256').update(input, 'utf8').digest();
+  // Node Buffer 继承自 Uint8Array，这里拷贝出独立的 Uint8Array 视图并截取前 32 字节，
+  // 避免消费侧意外写入共享 Buffer 造成状态污染。
+  const out = new Uint8Array(32);
+  out.set(digest.subarray(0, 32));
+  return out;
+}
+
+// ─── 内部：fallback key 解析 ────────────────────────────────────────────────
+
+/**
+ * 从 `Account.fallbackKey()` 返回的 KeyMap 中提取唯一一项 fallback 信息。
+ *
+ * vodozemac 底层 `generateFallbackKey()` 返回 void，需要再调 `fallbackKey()`
+ * 读取当前未发布的 fallback key（`{ keyId → publicKey }`）。
+ * 实际场景下 map 至多只有一条未发布的 fallback；取第一条即可。
+ */
+function extractFallbackKeyInfo(map: KeyMap): OneTimeKeyInfo {
+  const entries = Object.entries(map);
+  if (entries.length === 0) {
+    throw new Error('vodozemac: fallbackKey() 为空，generateFallbackKey 未生效');
+  }
+  const [keyId, publicKey] = entries[0]!;
+  return { keyId, publicKey };
+}
+
+// ─── 内部：wrapSession ──────────────────────────────────────────────────────
+
+/**
+ * 把底层 `Session` 包装成 `SessionHandle`。
+ *
+ * 被 outbound / inbound / restore 三路共享，保证加解密 I/O 类型一致。
+ */
+function wrapSession(inner: Session): SessionHandle {
+  // sessionId 在 session 生命周期内恒定，提前捕获避免每次 pickle 都回 WASM 查询。
+  const sessionId = inner.sessionId();
+
+  return {
+    get sessionId(): string {
+      return sessionId;
+    },
+
+    encrypt(plainBytes: Uint8Array): EncryptedBundle {
+      const em = inner.encrypt(plainBytes);
+      return { body: em.body };
+    },
+
+    decrypt(msg: EncryptedBundle): Uint8Array {
+      return inner.decrypt(new EncryptedMessage(msg.body));
+    },
+
+    matches(msg: EncryptedBundle): boolean {
+      return inner.sessionMatches(new EncryptedMessage(msg.body));
+    },
+
+    pickle(): string {
+      return inner.pickle(pickleKey(sessionId));
+    },
+
+    dispose(): void {
+      // 占位：底层 Session 由 JS GC 回收 wasm handle；后续若暴露显式 free 再补上。
+    },
+  };
+}
+
+// ─── 内部：wrapAccount ──────────────────────────────────────────────────────
+
+/**
+ * 把底层 `Account` 包装成 `AccountHandle`。
+ *
+ * `e2eeId` 由调用方传入（`newAccount` 来自 `curve25519Key()`，
+ * `restoreAccount` 来自 state.json 中的 `local.e2eeId`）；
+ * 后续 task 2.4 会在 `newAccount` 入口加上 `normalizeFreshAccount` 保证稳定。
+ */
+function wrapAccount(inner: Account, e2eeId: string): AccountHandle {
+  return {
+    get e2eeId(): string {
+      return e2eeId;
+    },
+
+    identityKey(): string {
+      // 对外暴露归一化后的稳定值，避免不同路径调用 `curve25519Key()` 出现瞬时差异。
+      return e2eeId;
+    },
+
+    generateOneTimeKeysWithInfo(n: number) {
+      return inner.generateOneTimeKeysWithInfo(n);
+    },
+
+    oneTimeKeysWithInfo(): OneTimeKeyInfo[] {
+      return inner.oneTimeKeysWithInfo();
+    },
+
+    unpublishedOneTimeKeyCount(): number {
+      return inner.unpublishedOneTimeKeyCount();
+    },
+
+    generateFallbackKey(): OneTimeKeyInfo {
+      inner.generateFallbackKey();
+      return extractFallbackKeyInfo(inner.fallbackKey());
+    },
+
+    markKeysAsPublished(): void {
+      inner.markKeysAsPublished();
+    },
+
+    createOutboundSession(peerIdentity: string, peerOneTimeKey: string): SessionHandle {
+      return wrapSession(inner.createOutboundSession(peerIdentity, peerOneTimeKey));
+    },
+
+    createInboundSession(msg: EncryptedBundle) {
+      const result = inner.createInboundSession(new EncryptedMessage(msg.body));
+      return {
+        session: wrapSession(result.session),
+        plaintext: result.plaintext,
+        oneTimeKey: result.oneTimeKey,
+      };
+    },
+
+    pickle(): string {
+      return inner.pickle(pickleKey(e2eeId));
+    },
+
+    dispose(): void {
+      // 占位：底层 Account 由 JS GC 回收 wasm handle；后续若暴露显式 free 再补上。
+    },
+  };
+}
+
+// ─── createVodozemacBinding ─────────────────────────────────────────────────
+
+/**
+ * 构造 VodozemacBinding 实例。
+ *
+ * `newAccount` 内部调用 `normalizeFreshAccount` 保证 `curve25519Key()` 收敛稳定
+ * （requirement R10），避免 state.json 写入非稳定值。
+ */
+export function createVodozemacBinding(): VodozemacBinding {
+  return {
+    async ready(): Promise<void> {
+      // vodozemackit 当前走静态 ESM import，WASM 在模块初始化时已就绪；
+      // 保留此方法以对齐 design.md §3.3 的契约，未来可替换为实际懒加载。
+      return;
+    },
+
+    newAccount(): AccountHandle {
+      const { account, stableE2eeId } = normalizeFreshAccount(new Account());
+      return wrapAccount(account, stableE2eeId);
+    },
+
+    restoreAccount(e2eeId: string, pickle: string): AccountHandle {
+      const inner = accountFromPickle(pickle, pickleKey(e2eeId));
+      return wrapAccount(inner, e2eeId);
+    },
+
+    restoreSession(sessionId: string, pickle: string): SessionHandle {
+      const inner = sessionFromPickle(pickle, pickleKey(sessionId));
+      // 包装后的 handle 会用 `inner.sessionId()` 作为 pickle key 来源；
+      // 此值与传入的 `sessionId` 一致，无需再校验。
+      void sessionId;
+      return wrapSession(inner);
+    },
+  };
+}