@yeying-community/web3-bs 1.0.16 → 1.0.17

package/docs//345/212/240/350/247/243/345/257/206/346/234/215/345/212/241.md

@@ -0,0 +1,146 @@
+# 加解密服务
+
+本文档说明 `@yeying-community/web3-bs` 的加解密 SDK：3 个函数 + 4 个命名安全套件 + 调用模式与安全模型。
+
+## 1. 能力概述
+
+`encrypt` / `decrypt` / `getSupportedCipherSuites` 三个函数，调用钱包插件的 EIP-1193 自定义方法 `yeying_encrypt` / `yeying_decrypt` / `yeying_getCipherSuites`。
+
+调用模式与 UCAN 一致：
+- 站点必须已 `requestAccounts` 授权
+- 钱包必须已解锁（`unlockMethods` 集合自动覆盖）
+- **静默执行**——无审批弹窗
+
+**不暴露裸算法参数**（key size、iv 长度、kdf 迭代、mac 长度全部锁死）。DApp 只能选套件名 + 传数据密码 + 传明文/密文。安全默认在 SDK 内部强制，避免误用。
+
+## 2. 命名安全套件
+
+通过 `getSupportedCipherSuites()` 拿到最新列表（结构：`{name, description, mode}`）。当前 4 个：
+
+| name | mode | 用途 |
+| --- | --- | --- |
+| `aes-256-gcm` | symmetric | 国际默认（默认套件） |
+| `sm4-cbc-hmac-sm3` | symmetric | 国密对称（encrypt-then-MAC） |
+| `sha-256` | hash | 哈希 |
+| `sm3` | hash | 国密哈希 |
+
+每个套件**默认参数**：
+- AES-256-GCM：256-bit key、12-byte IV、PBKDF2-SHA256 210k 轮
+- SM4-CBC + HMAC-SM3：128-bit SM4 key + 256-bit MAC key（PBKDF2 派生后拆分）、16-byte IV、PKCS#7 padding
+- 哈希：32 字节输出
+
+## 3. 典型用法
+
+### 3.1 加密
+
+```ts
+import { encrypt, getSupportedCipherSuites } from '@yeying-community/web3-bs';
+
+const suites = await getSupportedCipherSuites();
+console.log(suites.map(s => `${s.name} (${s.mode})`).join(', '));
+// → aes-256-gcm (symmetric), sm4-cbc-hmac-sm3 (symmetric), sha-256 (hash), sm3 (hash)
+
+const ciphertext = await encrypt({
+  data: '夜莺钱包敏感数据 🔐',
+  password: 'app-specific-passphrase-2024',
+  // suite: 'aes-256-gcm' // 不传则用默认套件
+});
+// → v1:aes-256-gcm:<base64-salt>:<base64-iv>:<base64-ciphertext>
+```
+
+### 3.2 解密
+
+```ts
+import { decrypt } from '@yeying-community/web3-bs';
+
+const plaintextBytes = await decrypt({
+  ciphertext: 'v1:aes-256-gcm:...',
+  password: 'app-specific-passphrase-2024'
+});
+const text = new TextDecoder().decode(plaintextBytes);
+// → 夜莺钱包敏感数据 🔐
+```
+
+### 3.3 选国密套件
+
+```ts
+const ciphertext = await encrypt({
+  data: sensitiveString,
+  password: 'app-specific-passphrase-2024',
+  suite: 'sm4-cbc-hmac-sm3'
+});
+```
+
+## 4. 错误处理
+
+所有错误抛 `CipherError`（继承自 `Error`），并附带分类：
+
+```ts
+import { encrypt, CipherError, isUserRejectedWalletAction } from '@yeying-community/web3-bs';
+
+try {
+  const ct = await encrypt({ data, password, provider });
+} catch (err) {
+  if (err instanceof CipherError) {
+    if (err.type === 'userRejected') {
+      // 用户在钱包端点了取消
+    } else if (err.type === 'disconnected') {
+      // 钱包未连接站点 / 站点未授权 / 钱包未解锁
+    } else {
+      // 未知错误（密码错、密文坏、网络等）
+    }
+    if (isUserRejectedWalletAction(err)) {
+      // ...
+    }
+  }
+}
+```
+
+`CipherError.type` 取值：`'userRejected' | 'disconnected' | 'timeout' | 'notFound' | 'unknown'`，与 `classifyWalletError` 保持一致。
+
+## 5. 安全模型
+
+### 5.1 信任假设
+
+- **站点已授权 + 钱包已解锁** = 站点可在用户不知情下调用加解密（与 UCAN 同模型）
+- **站点被 XSS** = XSS 攻击者可在该站点 origin 下调用加解密——这是 DApp 自身的责任，UCAN 沿用同模型
+- **数据密码独立**——`password` 参数是 DApp 自己的密码，**与钱包解锁密码不同**；钱包解锁用 DApp 用户在钱包插件里输的密码，加解密用 DApp 在自己代码里持有的密码
+
+### 5.2 数据密码选择
+
+推荐做法：
+- **永远不要**用用户的钱包密码作为 `password`
+- **永远不要**用用户已知的其他密码（如邮箱密码、登录密码）
+- 推荐 DApp 在用户首次使用时**随机生成 32+ 字符的"应用密码"**，存到 `localStorage`（**加密形式**——DApp 自己的"数据密码"本身也要保护）或让用户保管
+
+### 5.3 DApp 端的安全实践
+
+- **不要**把密文/明文写到 `console.log` / `localStorage` 明文 / DOM
+- **不要**用加解密服务来保护**私钥/助记词**——那是 wallet 自己的职责；DApp 永远不该接触明文私钥
+- 解密后的 `Uint8Array` 用完即弃（不可显式 `secureWipe`，但应尽快失去引用）
+- 在 `password` 字段发生错误时，**不**把错误信息（如"wrong password"）显示给最终用户——防止攻击者用错误信息侧信道试密码
+
+## 6. 限制与陷阱
+
+- **不要**对相同 `(suite, password, plaintext)` 期待确定密文——salt + iv 每次随机
+- **不要**在 UCAN 过期 / 站点未连接钱包 / 钱包锁定 时调用——会抛 `CipherError type=disconnected`
+- 输出格式 `v1:...` 是 base64 字符串——**可粘贴到任何地方存储**（数据库、localStorage、剪贴板）
+- 哈希套件（`sha-256` / `sm3`）的输出**没有"解密"概念**——`decrypt` 对哈希套件会抛 `Suite xxx is a hash, cannot decrypt`（钱包侧）
+- 当前**不**支持 SM2 非对称加密（仅对称 + 哈希）——以后可能扩展
+
+## 7. 完整 API
+
+```ts
+// src/auth/encrypt.ts
+export interface CipherSuiteInfo { name: string; description: string; mode: 'hash' | 'symmetric'; }
+export interface EncryptOptions { data: string | Uint8Array; password: string; suite?: string; provider?: Eip1193Provider; }
+export interface DecryptOptions { ciphertext: string; password: string; provider?: Eip1193Provider; }
+export interface GetCipherSuitesOptions { provider?: Eip1193Provider; }
+
+export class CipherError extends Error { type; code; originalError; ... }
+
+export function encrypt(options: EncryptOptions): Promise<string>;
+export function decrypt(options: DecryptOptions): Promise<Uint8Array>;
+export function getSupportedCipherSuites(options?: GetCipherSuitesOptions): Promise<CipherSuiteInfo[]>;
+export function isUserRejectedWalletAction(error: unknown): boolean;
+```