@tracer-kit/encrypted-storage

npm install @tracer-kit/encrypted-storage

提供分离的加密 Writer 与 Reader。Writer 运行时配置只接受 RSA 公钥，Reader 只接受 RSA 私钥；私钥不应进入业务页面。

flowchart LR
  Value[业务值] --> Writer[Encrypted Writer]
  Public[RSA 公钥] --> Writer
  Writer --> DB[(Core Storage 密文)]
  DB --> Source[EncryptedRecordSource]
  Source --> Reader[Encrypted Reader]
  Private[RSA 私钥] --> Reader
  Reader --> Result[逐条解密结果]

Writer

import { createEncryptedStorageWriter } from '@tracer-kit/encrypted-storage';

// Writer 只接收公钥，适合业务页面写入加密数据。
const writer = await createEncryptedStorageWriter({ publicKey, databaseName: 'my-logs' });
await writer.add({ message: 'hello' });

// 页面或测试生命周期结束时释放 IndexedDB 与通知通道。
writer.close();

Writer 先确定记录 ID 和发生时间，再把二者作为 AES-GCM AAD 编码到 v2 EncryptedEnvelope，最后交给 Core Storage 持久化。因此 IndexedDB 中不包含明文值，记录元数据被修改后 Reader 也会返回认证失败。

Reader

import { createEncryptedStorageReader } from '@tracer-kit/encrypted-storage';

// 普通同源页面可让 Reader 直接打开对应数据库。
const reader = await createEncryptedStorageReader<{ message: string }>({ privateKey, databaseName: 'my-logs' });
const page = await reader.query({ limit: 100 });
for (const record of page.records) {
  // 单条损坏只返回 failed，不会让整页查询失败。
  if (record.status === 'decrypted') console.log(record.value);
}
reader.close();

Reader 也接受 bridge 等外部来源：{ privateKey, source }。来源只需实现 query()，不会创建 IndexedDB；单条密文解密失败会返回 status: 'failed'，不影响同页其他记录。

// DevTools 中 source 通过 MAIN-world bridge 查询页面 Origin 的密文。
const bridgeReader = await createEncryptedStorageReader({
  privateKey,
  source: {
    query: (query) => bridge.queryEncryptedRecords(query),
  },
});

Reader 使用 ENVELOPE_FORMAT_INVALID、AUTHENTICATION_FAILED 和 DECRYPT_FAILED 稳定区分记录级失败，不返回原始异常或密文内容。

测试与维护

• test/writer.test.ts：公钥加密写入和生命周期。
• test/reader.test.ts：直接/bridge source、逐条失败分类与遍历。

修改 Writer/Reader 契约或错误码时，必须同步本 README、相关测试、Codec README 和 DevTools 文档。