@h-ai/crypto 0.1.0-alpha.18 → 0.1.0-alpha.20

package/README.md

@@ -13,9 +13,9 @@
 
 ## 安全声明
 
-- **SM4 ECB 模式（当前默认值）不安全**：相同明文块产生相同密文块，会泄漏结构模式。**生产环境请勿使用** `crypto.symmetric.encrypt(data, key)` 默认模式，改用 `crypto.symmetric.encryptWithIV(data, key)`（自动生成随机 IV 的 CBC 模式）或显式传入 `{ mode: 'cbc', iv }`。
+- **SM4 默认加密返回结构化密文**：`crypto.symmetric.encrypt(data, key)` 默认使用 CBC + 随机 IV，返回 `{ mode, ciphertext, iv, encoding }`；解密时把该对象传给 `crypto.symmetric.decrypt(payload, key)`。
 - **SM4 `deriveKey(password, salt)` 不是 KDF**：仅为单次 SM3 哈希，不具备密码爆破抗性，**禁止用于密码存储**。如需密码哈希，使用 `crypto.password.hash(password)`；如需从密码派生密钥，请采用 PBKDF2 / scrypt / Argon2。
-- **IV 必须唯一**：相同密钥下禁止复用 IV；推荐使用 `encryptWithIV()` 每次自动生成。密文与 IV 需一同传输与存储（IV 可公开，不必保密）。
+- **IV 必须唯一**：相同密钥下禁止复用 IV；推荐使用默认 CBC 或 `encryptWithIV()` 每次自动生成。密文与 IV 需一同传输与存储（IV 可公开，不必保密）。
 
 ## 快速开始
 
@@ -81,33 +81,40 @@ if (hash.success) {
 }
 ```
 
-### 对称加密（ECB / CBC）
+### 对称加密（CBC 默认 / 结构化密文）
 
 ```ts
 // 生成随机密钥和 IV
 const key = crypto.symmetric.generateKey()
 const iv = crypto.symmetric.generateIV()
 
-// ECB 模式（默认，❌ 不安全，仅保留兼容性，请勿在生产使用）
-const ecbEnc = crypto.symmetric.encrypt('data', key)
-if (ecbEnc.success) {
-  const ecbDec = crypto.symmetric.decrypt(ecbEnc.data, key)
-  // ecbDec.data === 'data'
+// 默认：CBC + 自动随机 IV，返回结构化密文
+const safeEnc = crypto.symmetric.encrypt('data', key)
+if (safeEnc.success) {
+  // safeEnc.data: { mode: 'cbc', ciphertext, iv, encoding: 'hex' }
+  const safeDec = crypto.symmetric.decrypt(safeEnc.data, key)
+  // safeDec.data === 'data'
 }
 
-// CBC 模式（需指定 IV）
+// CBC 指定 IV（仍然返回结构化密文）
 const cbcEnc = crypto.symmetric.encrypt('data', key, { mode: 'cbc', iv })
 if (cbcEnc.success) {
-  const cbcDec = crypto.symmetric.decrypt(cbcEnc.data, key, { mode: 'cbc', iv })
+  const cbcDec = crypto.symmetric.decrypt(cbcEnc.data, key)
 }
 
-// 快捷方式：自动生成 IV 的 CBC 加解密
+// 结构化结果：自动生成 IV 的 CBC 加解密
 const withIV = crypto.symmetric.encryptWithIV('data', key)
 if (withIV.success) {
   const dec = crypto.symmetric.decryptWithIV(withIV.data.ciphertext, key, withIV.data.iv)
 }
 
-// 输出 base64 格式
+// ECB 模式（❌ 不安全；只有底层协议明确要求时才显式指定）
+const ecbEnc = crypto.symmetric.encrypt('data', key, { mode: 'ecb' })
+if (ecbEnc.success) {
+  const ecbDec = crypto.symmetric.decrypt(ecbEnc.data, key)
+}
+
+// 输出 base64 格式（ciphertext 字段为 base64，encoding 字段会标明）
 const b64Enc = crypto.symmetric.encrypt('data', key, { outputFormat: 'base64' })
 
 // ⚠️ 已弃用：从密码派生密钥（仅为单次 SM3 哈希，不是 KDF，禁止用于密码存储场景）
@@ -155,7 +162,7 @@ if (hashed.success) {
 #### 使用流程
 
 1. 先 `await crypto.init()`，确保 `crypto.asymmetric` 与 `crypto.symmetric` 已初始化。
-2. 服务端调用 `crypto.transport.createServer()` 创建 `manager`；它持有服务端密钥对，并负责保存客户端公钥。
+2. 服务端调用 `crypto.transport.createServer()` 创建 `manager`；它持有服务端密钥对，并负责保存客户端公钥。多节点部署时可注入共享 `keyStore`。
 3. 服务端提供一个 POST 密钥协商端点：接收 `{ clientPublicKey }`，调用 `manager.registerClientKey()` 注册客户端，再返回 `{ serverPublicKey: manager.getServerPublicKey(), clientId }`。
 4. 客户端调用 `crypto.transport.createClient({ keyExchangeUrl })` 创建会话；首次 `client.init()` 或 `client.encryptedFetch()` 会自动完成这次协商。
 5. 协商完成后，客户端请求会附带 `X-Client-Id`；若请求有 body，则 body 会被包装成 `{ encryptedKey, ciphertext, iv }`，并带上 `X-Encrypted: true`。无 body 的请求只附带 `X-Client-Id`，不会额外生成密文 body。
@@ -163,7 +170,13 @@ if (hashed.success) {
 7. 服务端返回 JSON 响应前，用 `manager.encryptResponse(clientId, data)` 重新加密，并设置 `X-Encrypted: true`；客户端收到后会自动解密。
 8. 客户端调用 `client.destroy()` 可清空当前会话；服务端调用 `manager.close()`，或在模块级调用 `await crypto.close()`，用于释放资源。
 
-> 默认 `keyStore` 是进程内内存实现。多节点部署时，需要会话粘性（sticky session），或改用共享的 `TransportKeyStore` 实现来保存客户端公钥。
+> 默认 `keyStore` 是进程内 FIFO 内存实现，超过 `maxClients` 会淘汰最早注册的客户端。多节点部署时，需要会话粘性（sticky session），或改用共享的 `TransportKeyStore` 实现来保存客户端公钥。
+
+共享存储可直接复用 `@h-ai/crypto` 根入口导出的 provider 工厂：
+
+- `createInMemoryKeyStore(maxClients)`：显式创建默认内存实现，常用于测试或自定义容量
+- `createRedisTransportKeyStore({ cache, ttlSeconds? })`：复用 `@h-ai/cache`，通常配合 Redis provider 获取跨节点共享
+- `createReldbTransportKeyStore({ reldb, ttlSeconds? })`：复用 `@h-ai/reldb`，自动建表 `hai_crypto_transport_client_keys`
 
 ```ts
 // 服务端：通常由 serv.createApp({ transport: { crypto } }) 或 kit.createHandle({ crypto }) 内部调用
@@ -182,6 +195,22 @@ const response = await client.encryptedFetch('https://api.example.com/api/v1/ech
 })
 ```
 
+```ts
+import { cache } from '@h-ai/cache'
+import { createRedisTransportKeyStore, crypto } from '@h-ai/crypto'
+
+await crypto.init()
+await cache.init({ type: 'redis', host: '127.0.0.1', port: 6379 })
+
+const server = crypto.transport.createServer({
+  keyStore: createRedisTransportKeyStore({ cache, ttlSeconds: 3600 }),
+})
+if (!server.success)
+  throw new Error(server.error.message)
+```
+
+`encryptedFetch()` 的语义与原生 `fetch` 一致：网络失败、密钥协商失败、请求加密失败或响应解密失败时会 reject；业务层应在调用处按 fetch 错误处理策略统一捕获。
+
 协议常量通过 `crypto.transport.protocol`（或 `TRANSPORT_PROTOCOL`）访问：`X-Client-Id`、`X-Encrypted`、默认 `/_hai/key-exchange`。
 
 ### 关闭模块

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 import * as _h_ai_core from '@h-ai/core';
 import { HaiResult } from '@h-ai/core';
+import { CacheFunctions } from '@h-ai/cache';
+import { ReldbFunctions } from '@h-ai/reldb';
 
 /**
  * @h-ai/crypto — 传输加密类型与协议常量
@@ -40,8 +42,8 @@ interface KeyExchangeResponse {
 }
 /** 非对称密钥对。 */
 interface TransportKeyPair {
-    publicKey: string;
-    privateKey: string;
+    readonly publicKey: string;
+    readonly privateKey: string;
 }
 /**
  * 端到端传输的加密载荷格式。
@@ -94,6 +96,18 @@ interface TransportKeyStore {
     /** 释放底层资源（关闭连接、清理定时器等）。 */
     close?: () => Promise<void>;
 }
+/**
+ * 创建服务端传输加密管理器的配置。
+ *
+ * `keyStore` 未传时，默认使用 {@link createInMemoryKeyStore}；此时可通过 `maxClients`
+ * 控制进程内 FIFO 容量。若传入共享 `keyStore`，则 `maxClients` 不再生效。
+ */
+interface TransportCreateServerOptions {
+    /** 客户端公钥存储；多节点部署时建议注入共享实现。 */
+    readonly keyStore?: TransportKeyStore;
+    /** 默认内存 keyStore 的最大容量（仅当 `keyStore` 未提供时生效）。 */
+    readonly maxClients?: number;
+}
 /**
  * 服务端传输加密管理器。
  *
@@ -139,7 +153,11 @@ interface TransportClient {
      * 通常无需手动调用：`encryptedFetch` 在首次请求前会自动 `init()`。
      */
     init: () => Promise<HaiResult<void>>;
-    /** 包装后的 fetch；签名与全局 `fetch` 一致，请求/响应自动加解密。 */
+    /**
+     * 包装后的 fetch；签名与全局 `fetch` 一致，请求/响应自动加解密。
+     *
+     * @throws 与原生 fetch 一样，网络错误、密钥协商失败、加密失败或解密失败会 reject。
+     */
     encryptedFetch: typeof fetch;
     /** 是否已完成密钥协商。 */
     ready: () => boolean;
@@ -191,24 +209,37 @@ interface HashOptions {
 }
 /** 对称加密模式 */
 type SymmetricMode = 'ecb' | 'cbc';
-/** 对称加密选项 */
-interface SymmetricOptions {
-    /** 加密模式 */
+/** 对称密文编码 */
+type SymmetricCiphertextEncoding = 'hex' | 'base64';
+/** 对称加密选项。默认 CBC，并自动生成随机 IV。 */
+interface SymmetricEncryptOptions {
+    /** 加密模式；默认 cbc */
     mode?: SymmetricMode;
-    /** IV 向量（CBC 模式必需，32 个十六进制字符） */
+    /** IV 向量（CBC 模式可选；未传时自动生成，32 个十六进制字符） */
     iv?: string;
-    /** 输入编码 */
-    inputEncoding?: 'utf8' | 'hex';
-    /** 输出格式 */
-    outputFormat?: 'hex' | 'base64';
+    /** 密文输出编码；默认 hex */
+    outputFormat?: SymmetricCiphertextEncoding;
+}
+/** 对称加密结构化结果。 */
+interface SymmetricEncryptedPayload {
+    /** 加密模式 */
+    readonly mode: SymmetricMode;
+    /** 密文内容，编码由 encoding 字段说明 */
+    readonly ciphertext: string;
+    /** CBC 模式的 IV 向量；ECB 模式无该字段 */
+    readonly iv?: string;
+    /** ciphertext 字段的编码 */
+    readonly encoding: SymmetricCiphertextEncoding;
 }
-/** 带 IV 加密结果 */
-interface EncryptWithIVResult {
-    /** 密文 */
-    ciphertext: string;
-    /** IV 向量 */
-    iv: string;
+/** CBC 模式结构化结果。 */
+interface SymmetricCbcEncryptedPayload extends SymmetricEncryptedPayload {
+    readonly mode: 'cbc';
+    readonly iv: string;
 }
+/** 对称解密输入。 */
+type SymmetricDecryptInput = SymmetricEncryptedPayload;
+/** 带 IV 加密结果。 */
+type EncryptWithIVResult = SymmetricCbcEncryptedPayload;
 /** 密码哈希配置 */
 interface PasswordConfig {
     /** 盐值长度（默认 16） */
@@ -320,7 +351,7 @@ interface HashOperations {
  * 对称加密操作接口
  *
  * 通过 `crypto.symmetric` 访问，需先调用 `crypto.init()`。
- * 支持 ECB/CBC 两种模式，CBC 模式需要提供 IV。
+ * 默认使用 CBC 并自动生成 IV；密文以结构化字段返回。
  */
 interface SymmetricOperations {
     /** 生成随机密钥（16 字节 = 32 个十六进制字符） */
@@ -330,23 +361,25 @@ interface SymmetricOperations {
     /**
      * 对称加密
      *
+     * 默认 CBC + 自动随机 IV，返回 `{ mode, ciphertext, iv, encoding }`。
+     * 显式 `{ mode: 'ecb' }` 可使用 ECB，但不推荐用于新数据。
+     *
      * @param data - 待加密明文
      * @param key - 密钥（32 字符十六进制）
      * @param options - 加密模式/IV/输出格式
-     * @returns 成功时返回密文；失败时返回 INVALID_KEY/INVALID_IV/ENCRYPTION_FAILED
+     * @returns 成功时返回结构化密文；失败时返回 INVALID_KEY/INVALID_IV/ENCRYPTION_FAILED
      */
-    encrypt: (data: string, key: string, options?: SymmetricOptions) => HaiResult<string>;
+    encrypt: (data: string, key: string, options?: SymmetricEncryptOptions) => HaiResult<SymmetricEncryptedPayload>;
     /**
      * 对称解密
      *
-     * 自动检测 base64 格式输入并转换为 hex。
+     * 解密 `encrypt()` 返回的结构化密文；不猜测字符串格式。
      *
-     * @param ciphertext - 密文（hex 或 base64）
+     * @param payload - 结构化密文（包含 mode/ciphertext/iv/encoding）
      * @param key - 密钥（32 字符十六进制）
-     * @param options - 解密模式/IV（需与加密时一致）
      * @returns 成功时返回明文；失败时返回 INVALID_KEY/INVALID_IV/DECRYPTION_FAILED
      */
-    decrypt: (ciphertext: string, key: string, options?: SymmetricOptions) => HaiResult<string>;
+    decrypt: (payload: SymmetricDecryptInput, key: string) => HaiResult<string>;
     /**
      * 带 IV 加密（CBC 模式，自动生成随机 IV）
      *
@@ -421,7 +454,7 @@ interface PasswordOperations {
  * 使用流程（直接使用底层 transport 工厂时）：
  *
  * 1. 先 `await crypto.init()`，确保 `crypto.asymmetric` / `crypto.symmetric` 已就绪。
- * 2. 服务端调用 `crypto.transport.createServer()` 创建 `TransportEncryptionManager`；该管理器负责持有服务端密钥对，并管理客户端公钥。
+ * 2. 服务端调用 `crypto.transport.createServer()` 创建 `TransportEncryptionManager`；该管理器负责持有服务端密钥对，并管理客户端公钥。多节点部署时可通过 `options.keyStore` 注入共享存储。
  * 3. 服务端暴露一个 POST 密钥协商端点：接收 `{ clientPublicKey }`，调用 `manager.registerClientKey()` 注册客户端公钥，再返回 `{ serverPublicKey: manager.getServerPublicKey(), clientId }`。
  * 4. 客户端调用 `crypto.transport.createClient({ keyExchangeUrl })` 创建会话；首次 `client.init()` 或 `client.encryptedFetch()` 会自动完成密钥协商。
  * 5. 协商完成后，客户端每次请求都会附带 `X-Client-Id`；若请求有 body，则 body 会被包装成 `{ encryptedKey, ciphertext, iv }`，并设置 `X-Encrypted: true`。
@@ -435,7 +468,9 @@ interface PasswordOperations {
  *
  * @example 服务端
  * ```ts
- * const result = crypto.transport.createServer()
+ * const result = crypto.transport.createServer({
+ *   keyStore: createRedisTransportKeyStore({ cache, ttlSeconds: 3600 }),
+ * })
  * if (!result.success) throw result.error
  * const manager = result.data
  * ```
@@ -454,15 +489,14 @@ interface TransportOperations {
     /**
      * 创建服务端传输加密管理器。
      *
-     * options.maxClients：默认内存 keyStore 的最大客户端数（默认 10000）。
+     * options.keyStore：注入共享客户端公钥存储。
+     * options.maxClients：默认内存 keyStore 的最大客户端数（默认 10000，仅在未传 keyStore 时生效）。
      * 成功返回 manager；密钥生成失败返回 `HaiCommonError.INTERNAL_ERROR`。
      *
      * @remarks
      * 通常在服务启动阶段创建一次，并交给 HTTP 中间件 / 路由处理器复用。
      */
-    createServer: (options?: {
-        maxClients?: number;
-    }) => HaiResult<TransportEncryptionManager>;
+    createServer: (options?: TransportCreateServerOptions) => HaiResult<TransportEncryptionManager>;
     /**
      * 创建客户端传输加密会话。
      *
@@ -549,4 +583,65 @@ interface CryptoFunctions {
  */
 declare const crypto: CryptoFunctions;
 
-export { type AsymmetricEncryptOptions, type AsymmetricOperations, type CipherMode, type CryptoFunctions, type EncryptWithIVResult, type EncryptedPayload, HaiCryptoError, type HashOperations, type HashOptions, type KeyExchangeRequest, type KeyExchangeResponse, type KeyPair, type PasswordConfig, type PasswordOperations, type SignOptions, type SymmetricMode, type SymmetricOperations, type SymmetricOptions, TRANSPORT_PROTOCOL, type TransportClient, type TransportCryptoServiceLike, type TransportEncryptionManager, type TransportKeyPair, type TransportKeyStore, type TransportOperations, crypto };
+/**
+ * @h-ai/crypto — 传输加密内存 key store
+ *
+ * 提供默认的进程内客户端公钥存储实现。
+ * @module crypto-transport-store-memory
+ */
+
+/**
+ * 创建进程内 FIFO 客户端密钥存储。
+ *
+ * ⚠️ 进程内实现：多节点部署时需让客户端首次请求后保持「会话粘性」（sticky session），
+ * 否则后续请求路由到其他节点会因找不到客户端公钥而失败。需要跨节点请改用
+ * Redis / 数据库实现 {@link TransportKeyStore}。
+ *
+ * @param maxClients - 最大客户端数（默认 10000），超过后按注册顺序淘汰最早条目。
+ */
+declare function createInMemoryKeyStore(maxClients?: number): TransportKeyStore;
+
+/**
+ * @h-ai/crypto — 传输加密 Redis key store
+ *
+ * 通过 `@h-ai/cache` 持久化客户端公钥；通常应传入已初始化为 Redis 的 `cache` 实例。
+ * @module crypto-transport-store-redis
+ */
+
+/** 创建 Redis 版传输 key store 的配置。 */
+interface CreateRedisTransportKeyStoreOptions {
+    /** 已初始化的 `@h-ai/cache` 实例；生产环境通常应使用 Redis provider。 */
+    readonly cache: CacheFunctions;
+    /** 客户端公钥的 TTL（秒）；未传则保持不过期。 */
+    readonly ttlSeconds?: number;
+}
+/**
+ * 创建基于 `@h-ai/cache` 的传输 key store。
+ *
+ * 说明：本实现依赖 cache 模块的 KV 语义；若要获得跨节点共享能力，应传入
+ * 已连接 Redis 的 `cache` 实例，而不是内存 provider。
+ */
+declare function createRedisTransportKeyStore(options: CreateRedisTransportKeyStoreOptions): TransportKeyStore;
+
+/**
+ * @h-ai/crypto — 传输加密关系数据库 key store
+ *
+ * 通过 `@h-ai/reldb` 保存客户端公钥，适用于需要跨节点共享状态的服务端部署。
+ * @module crypto-transport-store-reldb
+ */
+
+/** 创建关系数据库版传输 key store 的配置。 */
+interface CreateReldbTransportKeyStoreOptions {
+    /** 已初始化的 `@h-ai/reldb` 实例。 */
+    readonly reldb: ReldbFunctions;
+    /** 客户端公钥的 TTL（秒）；未传则保持不过期。 */
+    readonly ttlSeconds?: number;
+}
+/**
+ * 创建基于 `@h-ai/reldb` 的传输 key store。
+ *
+ * 首次读写时会自动创建 `hai_crypto_transport_client_keys` 表。
+ */
+declare function createReldbTransportKeyStore(options: CreateReldbTransportKeyStoreOptions): TransportKeyStore;
+
+export { type AsymmetricEncryptOptions, type AsymmetricOperations, type CipherMode, type CreateRedisTransportKeyStoreOptions, type CreateReldbTransportKeyStoreOptions, type CryptoFunctions, type EncryptWithIVResult, type EncryptedPayload, HaiCryptoError, type HashOperations, type HashOptions, type KeyExchangeRequest, type KeyExchangeResponse, type KeyPair, type PasswordConfig, type PasswordOperations, type SignOptions, type SymmetricCbcEncryptedPayload, type SymmetricCiphertextEncoding, type SymmetricDecryptInput, type SymmetricEncryptOptions, type SymmetricEncryptedPayload, type SymmetricMode, type SymmetricOperations, TRANSPORT_PROTOCOL, type TransportClient, type TransportCreateServerOptions, type TransportCryptoServiceLike, type TransportEncryptionManager, type TransportKeyPair, type TransportKeyStore, type TransportOperations, createInMemoryKeyStore, createRedisTransportKeyStore, createReldbTransportKeyStore, crypto };