@h-ai/crypto 0.1.0-alpha.67 → 0.1.0-alpha.69

package/dist/index.d.ts

@@ -4,22 +4,144 @@ import { CacheFunctions } from '@h-ai/cache';
 import { ReldbFunctions } from '@h-ai/reldb';
 
 /**
- * @h-ai/crypto — 传输加密类型与协议常量
+ * @h-ai/crypto — 传输协议的字节预算与有界正文读取。
  *
- * 提供 SM2 + SM4（或等效非对称 + 对称）混合传输加密所需的接口与协议常量，
- * 由 kit / serv / api-client 共享，确保两端协议完全一致。
+ * serv/kit 共享相同预算，不依赖可省略或伪造的 Content-Length。
+ * @module crypto-transport-body
+ */
+/**
+ * 传输预算；业务预算由明文容量推导，安全字段保持独立。
+ * @example
+ * ```ts
+ * import { resolveTransportBodyLimits, type TransportBodyLimits } from '@h-ai/crypto'
+ * const limits: TransportBodyLimits = resolveTransportBodyLimits(8 * 1024 * 1024)
+ * const proxyBytes = limits.encryptedPayloadBytes
+ * ```
+ */
+interface TransportBodyLimits {
+    readonly keyExchangeBytes: number;
+    readonly envelopeHeaderBytes: number;
+    readonly publicKeyBytes: number;
+    readonly plaintextBytes: number;
+    readonly encryptedPayloadBytes: number;
+}
+/**
+ * 业务明文的有效 UTF-8 字节范围：1 KiB～64 MiB；不支持无限制。
+ * @example
+ * ```ts
+ * import { TRANSPORT_PLAINTEXT_RANGE } from '@h-ai/crypto'
+ * const maximumBytes = TRANSPORT_PLAINTEXT_RANGE.max
+ * ```
+ */
+declare const TRANSPORT_PLAINTEXT_RANGE: Readonly<{
+    min: 1024;
+    max: number;
+}>;
+/**
+ * 默认UTF-8字节预算；按实际流读取，不依赖Content-Length，非字符串字符数限制。
  *
- * @module crypto-transport-types
+ * @example
+ * ```ts
+ * import { readTransportBody, TRANSPORT_BODY_LIMITS } from '@h-ai/crypto'
+ * const request = new Request('https://api.example.com/api/v1/orders', { method: 'POST', body: JSON.stringify({ message: 'hello' }) })
+ * const text = await readTransportBody(request.body, { maxBytes: TRANSPORT_BODY_LIMITS.plaintextBytes, signal: request.signal })
+ * ```
+ */
+declare const TRANSPORT_BODY_LIMITS: TransportBodyLimits;
+/**
+ * 校验单一业务明文容量并推导双向密文预算；返回不可变快照。
+ * SM4-CBC 使用十六进制编码，预算为明文的两倍加 32 KiB（填充及认证封装）。
+ * @param maxPlaintextBytes - UTF-8 字节数，默认 1 MiB，有效范围 1 KiB～64 MiB 的整数。
+ * @returns 明文、密文及独立安全预算。
+ * @throws RangeError - 配置无效；不接受字符串、null、无限制或静默回退。
+ * @example
+ * ```ts
+ * import { resolveTransportBodyLimits } from '@h-ai/crypto'
+ * const limits = resolveTransportBodyLimits(8 * 1024 * 1024)
+ * const nginxLimit = limits.encryptedPayloadBytes
+ * ```
  */
+declare function resolveTransportBodyLimits(maxPlaintextBytes?: number): TransportBodyLimits;
+/**
+ * 可识别的容量错误；只包含方向、阶段和字节数，不包含报文内容。
+ * @example
+ * ```ts
+ * import { TransportBodyTooLargeError } from '@h-ai/crypto'
+ * const error = new TransportBodyTooLargeError(1024, 1025, { direction: 'request', stage: 'plaintext' })
+ * const diagnostic = { code: error.code, limitBytes: error.limitBytes, actualBytes: error.actualBytes }
+ * ```
+ */
+declare class TransportBodyTooLargeError extends RangeError {
+    readonly code: string | number;
+    readonly direction: 'request' | 'response';
+    readonly stage: 'plaintext' | 'encrypted' | 'header';
+    readonly limitBytes: number;
+    readonly actualBytes?: number;
+    constructor(limitBytes: number, actualBytes?: number, options?: {
+        direction?: 'request' | 'response';
+        stage?: 'plaintext' | 'encrypted' | 'header';
+    });
+}
+/**
+ * 有界原流读取选项；maxBytes是非负安全整数，signal取消等待和底层流。
+ *
+ * @example
+ * ```ts
+ * import { readTransportBody, type ReadTransportBodyOptions } from '@h-ai/crypto'
+ * const request = new Request('https://api.example.com/api/v1/orders', { method: 'POST', body: 'hello' })
+ * const options: ReadTransportBodyOptions = { maxBytes: 1024, signal: request.signal }
+ * const text = await readTransportBody(request.body, options)
+ * ```
+ */
+interface ReadTransportBodyOptions {
+    /** 允许读取的字节总数，必须为非负安全整数。 */
+    readonly maxBytes: number;
+    /** 请求取消时中止等待中的读取并取消底层流。 */
+    readonly signal?: AbortSignal;
+    /** 超限诊断方向；默认 request。 */
+    readonly direction?: 'request' | 'response';
+    /** 超限诊断阶段；默认 plaintext。 */
+    readonly stage?: 'plaintext' | 'encrypted' | 'header';
+}
+/**
+ * 逐块读取原始字节流并严格UTF-8解码；超限/取消后取消流并释放reader，清理失败不覆盖原异常。
+ * 不要传入clone/tee分支，否则另一分支仍可能保留数据。
+ * @param stream - 原始流；null返回空串但仍检查取消。
+ * @param options - 字节预算与取消信号。
+ * @returns 解码文本。
+ * @throws RangeError预算无效或超限；非法UTF-8、流异常和signal.reason继续抛出。
+ *
+ * @example
+ * ```ts
+ * import { readTransportBody } from '@h-ai/crypto'
+ * const request = new Request('https://api.example.com/api/v1/orders', { method: 'POST', body: 'hello' })
+ * const text = await readTransportBody(request.body, { maxBytes: 1024, signal: request.signal })
+ * ```
+ */
+declare function readTransportBody(stream: ReadableStream<Uint8Array> | null, options: ReadTransportBodyOptions): Promise<string>;
 
 /**
- * 传输加密协议常量。
+ * 认证传输v2的头名、窗口与默认协商子路径；各HTTP适配器共用，不手写漂移常量。
  *
- * 所有使用端必须复用这组常量，避免「header 名拼写漂移导致两端协议错配」。
+ * @example
+ * ```ts
+ * import { TRANSPORT_PROTOCOL } from '@h-ai/crypto'
+ * const headers = new Headers()
+ * headers.set(TRANSPORT_PROTOCOL.ENCRYPTED_HEADER, TRANSPORT_PROTOCOL.ENCRYPTED_HEADER_VALUE)
+ * const keyExchangePath = TRANSPORT_PROTOCOL.DEFAULT_KEY_EXCHANGE_PATH
+ * ```
  */
 declare const TRANSPORT_PROTOCOL: {
     /** 客户端 ID 请求头名。 */
     readonly CLIENT_ID_HEADER: "X-Client-Id";
+    /** GET/HEAD 等无正文请求的认证封装；禁止与正文封装同时出现。 */
+    readonly ENVELOPE_HEADER: "X-Hai-Transport";
+    /** 唯一支持的认证协议版本；旧未认证格式拒绝。 */
+    readonly VERSION: 2;
+    /** 请求允许的过去时间窗口（毫秒）。 */
+    readonly REQUEST_WINDOW_MS: 300000;
+    /** 节点时钟允许的最大未来偏差（毫秒）。 */
+    readonly CLOCK_SKEW_MS: 30000;
     /** 标识响应体已加密的响应头名。 */
     readonly ENCRYPTED_HEADER: "X-Encrypted";
     /** `X-Encrypted` 响应头的开启值。 */
@@ -28,45 +150,220 @@ declare const TRANSPORT_PROTOCOL: {
     readonly DEFAULT_KEY_EXCHANGE_PATH: "/_hai/key-exchange";
 };
 /**
- * 密钥协商请求体（客户端 → 服务端）。
+ * 密钥协商请求；只发送客户端公钥，私钥始终留在客户端，注册仍验证曲线点。
+ *
+ * @example
+ * ```ts
+ * import { crypto, type KeyExchangeRequest } from '@h-ai/crypto'
+ * const initialized = await crypto.init()
+ * if (!initialized.success) throw new Error(initialized.error.message)
+ * try {
+ *   const generated = crypto.asymmetric.generateKeyPair()
+ *   if (!generated.success) throw new Error(generated.error.message)
+ *   const pair = generated.data
+ *   const body: KeyExchangeRequest = { clientPublicKey: pair.publicKey }
+ *   const serialized = JSON.stringify(body)
+ * }
+ * finally { await crypto.close() }
+ * ```
  */
 interface KeyExchangeRequest {
     readonly clientPublicKey: string;
 }
 /**
- * 密钥协商响应体（服务端 → 客户端）。
+ * TLS协商响应，公开服务端版本、公钥和registry生成的clientId；不含服务端私钥。
+ *
+ * @example
+ * ```ts
+ * import type { KeyExchangeRequest, KeyExchangeResponse, TransportEncryptionManager } from '@h-ai/crypto'
+ * async function exchange(manager: TransportEncryptionManager, body: KeyExchangeRequest): Promise<KeyExchangeResponse> {
+ *   const clientId = await manager.registerClientKey(body.clientPublicKey)
+ *   return { clientId, serverKeyId: manager.getServerKeyId(), serverPublicKey: manager.getServerPublicKey() }
+ * }
+ * ```
  */
 interface KeyExchangeResponse {
+    /** 服务端业务明文 UTF-8 字节上限；缺省表示旧服务端的 1 MiB 默认值。 */
+    readonly maxPlaintextBytes?: number;
+    /** 服务端当前加密密钥版本；业务请求必须带回该值。 */
+    readonly serverKeyId: string;
     readonly serverPublicKey: string;
     readonly clientId: string;
 }
-/** 非对称密钥对。 */
+/**
+ * 传输使用的SM2公私钥对；服务端版本从私有Secret注入，客户端可本地生成独立会话密钥。
+ *
+ * @example
+ * ```ts
+ * import { crypto, type TransportKeyPair } from '@h-ai/crypto'
+ * const initialized = await crypto.init()
+ * if (!initialized.success) throw new Error(initialized.error.message)
+ * try {
+ *   const generated = crypto.asymmetric.generateKeyPair()
+ *   if (!generated.success) throw new Error(generated.error.message)
+ *   const pair = generated.data
+ *   const clientPair: TransportKeyPair = pair
+ *   const publicKey = clientPair.publicKey
+ * }
+ * finally { await crypto.close() }
+ * ```
+ */
 interface TransportKeyPair {
     readonly publicKey: string;
     readonly privateKey: string;
 }
 /**
- * 端到端传输的加密载荷格式。
+ * 完整v2认证封装；encryptedKey含独立SM4/HMAC密钥，signature覆盖认证字段和MAC。
+ * HTTP适配器只用成功认证得到的上下文生成响应，不自行拼接示例密文。
  *
- * `encryptedKey` 用对端非对称公钥加密的对称会话密钥；`ciphertext` + `iv`
- * 为该会话密钥加密的明文。两端必须使用同一份字段命名。
+ * @example
+ * ```ts
+ * import { authenticateTransportRequest, type EncryptedPayload, type TransportEncryptionManager } from '@h-ai/crypto'
+ * async function sealResponse(manager: TransportEncryptionManager, request: Request): Promise<EncryptedPayload> {
+ *   const verified = await authenticateTransportRequest(manager, request)
+ *   if (!verified.success) throw new Error(verified.error.message)
+ *   const encrypted = await manager.encryptResponse(verified.data.context, JSON.stringify({ accepted: true }), 200)
+ *   if (!encrypted.success) throw new Error(encrypted.error.message)
+ *   return encrypted.data
+ * }
+ * ```
  */
 interface EncryptedPayload {
+    /** 认证的请求上下文；响应必须原样关联同一个请求。 */
+    readonly context: TransportMessageContext;
+    /** 认证方向，防止把合法响应反射到请求入口。 */
+    readonly direction: 'request' | 'response';
+    /** 请求固定为 0；响应认证实际 HTTP 状态码。 */
+    readonly status: number;
+    /** SM2 封装的 JSON [SM4 密钥 hex, 独立 HMAC 密钥 hex]。 */
     readonly encryptedKey: string;
+    /** SM4-CBC 密文 hex；认证输入包含原始编码值。 */
     readonly ciphertext: string;
+    /** 随机 16 字节 CBC IV 的 hex 编码。 */
     readonly iv: string;
+    /** 独立随机密钥计算的 HMAC-SM3；先验证后解密 CBC。 */
+    readonly tag: string;
+    /** 对完整封装和 tag 的发送方 SM2 签名，防止公钥持有者伪造发送方。 */
+    readonly signature: string;
+}
+/**
+ * 认证的单次HTTP上下文；128位nonce、版本、客户端、时间、方法和实际路径SM3摘要共同绑定。
+ * 服务端共享registry只允许消费一次nonce；响应必须关联成功认证后的同一上下文。
+ *
+ * @example
+ * ```ts
+ * import { authenticateTransportRequest, type TransportEncryptionManager, type TransportMessageContext } from '@h-ai/crypto'
+ * async function contextOf(manager: TransportEncryptionManager, request: Request): Promise<TransportMessageContext> {
+ *   const verified = await authenticateTransportRequest(manager, request)
+ *   if (!verified.success) throw new Error(verified.error.message)
+ *   return verified.data.context
+ * }
+ * ```
+ */
+interface TransportMessageContext {
+    /** 唯一受支持的协议版本。 */
+    readonly version: 2;
+    /** 协商选择的受管服务端密钥版本。 */
+    readonly serverKeyId: string;
+    /** registry 注册的客户端 ID；发送方必须证明持有对应私钥。 */
+    readonly clientId: string;
+    /** 128 位随机十六进制 nonce，同时用于响应关联。 */
+    readonly requestId: string;
+    /** 请求创建时间，Unix 毫秒；允许过去 5 分钟、未来 30 秒。 */
+    readonly issuedAt: number;
+    /** 大写 HTTP 方法，必须与实际 Request 完全一致。 */
+    readonly method: string;
+    /** 实际 pathname + 原始 search 的 SM3 摘要，64 位小写 hex，避免在认证头中重复长 URL。 */
+    readonly pathHash: string;
+}
+/**
+ * 从实际HTTP Request提取的可信绑定输入；不能直接复制密文的自报方法、路径或客户端。
+ *
+ * @example
+ * ```ts
+ * import type { TransportRequestContext } from '@h-ai/crypto'
+ * function expectedContext(request: Request): TransportRequestContext {
+ *   const clientId = request.headers.get('X-Client-Id')
+ *   if (!clientId) throw new Error('Missing client ID')
+ *   const url = new URL(request.url)
+ *   return { clientId, method: request.method, path: url.pathname + url.search }
+ * }
+ * ```
+ */
+interface TransportRequestContext {
+    /** 实际 X-Client-Id 头，用于 registry 查询及发送方验签。 */
+    readonly clientId: string;
+    /** 实际 Request.method。 */
+    readonly method: string;
+    /** 实际 URL.pathname + URL.search，保留查询参数顺序及编码。 */
+    readonly path: string;
 }
 /**
- * 传输加密所需的非对称 + 对称能力子集。
+ * 客户端发出的完整请求封装，direction=request且status=0；结构类型不构成认证证明。
  *
- * 不直接依赖 `@h-ai/crypto` 的具体实现，便于测试时注入 mock；
- * 实际使用时 `crypto` 模块的实例本身即可结构兼容。
+ * @example
+ * ```ts
+ * import type { EncryptedRequestPayload, TransportEncryptionManager } from '@h-ai/crypto'
+ * async function decrypt(manager: TransportEncryptionManager, request: Request, payload: EncryptedRequestPayload): Promise<string> {
+ *   const clientId = request.headers.get('X-Client-Id')
+ *   if (!clientId) throw new Error('Missing client ID')
+ *   const url = new URL(request.url)
+ *   const result = await manager.decryptRequest(payload, { clientId, method: request.method, path: url.pathname + url.search })
+ *   if (!result.success) throw new Error(result.error.message)
+ *   return result.data
+ * }
+ * ```
+ */
+interface EncryptedRequestPayload extends EncryptedPayload {
+    readonly direction: 'request';
+    readonly status: 0;
+}
+/**
+ * 服务端受管版本密钥环；所有节点同版本对应同密钥，新协商选activeKeyId，旧版本保留到撤销。
+ * 先分发新旧版本再切活动ID；删除旧版本即撤销，私钥不进入PUBLIC_/VITE_/日志。
+ *
+ * @example
+ * ```ts
+ * import { parseTransportServerKeyRing, type TransportServerKeyRing } from '@h-ai/crypto'
+ * const parsed = parseTransportServerKeyRing(process.env.HAI_CRYPTO_TRANSPORT_SERVERKEYRING)
+ * if (!parsed.success) throw new Error(parsed.error.message)
+ * const ring: TransportServerKeyRing = parsed.data
+ * ```
+ */
+interface TransportServerKeyRing {
+    /** 新协商使用的版本；1–64 个字母、数字、下划线或连字符。 */
+    readonly activeKeyId: string;
+    /** ID 与密钥对；仅供服务端保管，所有节点必须分发相同版本的相同密钥。 */
+    readonly keys: Readonly<Record<string, TransportKeyPair>>;
+}
+/**
+ * 传输协议实际需要的SM2/SM3/HMAC/SM4能力；可结构化注入真实crypto，不仿造另一套算法。
+ *
+ * @example
+ * ```ts
+ * import { crypto, type TransportCryptoServiceLike } from '@h-ai/crypto'
+ * const initialized = await crypto.init()
+ * if (!initialized.success) throw new Error(initialized.error.message)
+ * try {
+ *   const service: TransportCryptoServiceLike = crypto
+ *   const digest = service.hash.hash('/api/v1/orders')
+ *   if (!digest.success) throw new Error(digest.error.message)
+ * }
+ * finally { await crypto.close() }
+ * ```
  */
 interface TransportCryptoServiceLike {
     asymmetric: {
         generateKeyPair: () => HaiResult<TransportKeyPair>;
         encrypt: (data: string, publicKey: string) => HaiResult<string>;
         decrypt: (ciphertext: string, privateKey: string) => HaiResult<string>;
+        sign: (data: string, privateKey: string) => HaiResult<string>;
+        verify: (data: string, signature: string, publicKey: string) => HaiResult<boolean>;
+    };
+    hash: {
+        /** SM3 摘要，用于实际请求路径绑定，不使用其它摘要算法替换。 */
+        hash: (data: string) => HaiResult<string>;
+        hmac: (data: string, key: string) => HaiResult<string>;
     };
     symmetric: {
         generateKey: () => string;
@@ -78,93 +375,471 @@ interface TransportCryptoServiceLike {
     };
 }
 /**
- * 客户端公钥存储抽象。
- *
- * 默认实现为进程内 Map（{@link createInMemoryKeyStore}），多节点部署时建议
- * 接入 Redis / 数据库实现以保证跨节点一致性。
+ * 客户端公钥与nonce存储契约；生产显式共享Redis/数据库，真实共享与原子性由提供者保证。
+ * get的故障不能当未注册，claimRequest故障不能当成功；有效nonce不得在expiresAt前驱逐。
  *
- * 设计原则：方法均为异步签名，避免后续替换为分布式实现时大改接口；
- * 内存实现以 `Promise.resolve` 包裹即可。
+ * @example
+ * ```ts
+ * import { crypto, createRedisTransportKeyStore, parseTransportServerKeyRing } from '@h-ai/crypto'
+ * import { cache } from '@h-ai/cache'
+ * const initialized = await crypto.init()
+ * if (!initialized.success) throw new Error(initialized.error.message)
+ * try {
+ *   const connected = await cache.init({ type: 'redis', host: 'cache', port: 6379, password: process.env.HAI_CACHE_PASSWORD })
+ *   if (!connected.success) throw new Error(connected.error.message)
+ *   try {
+ *     const registry = createRedisTransportKeyStore({ cache, ttlSeconds: 3600 })
+ *     const store: import('@h-ai/crypto').TransportKeyStore = registry
+ *     const scope = store.stateScope
+ *     // Redis部署须noeviction/可靠持久化，并同步各节点时钟。
+ *   }
+ *   finally { await cache.close() }
+ * }
+ * finally { await crypto.close() }
+ * ```
  */
 interface TransportKeyStore {
-    /** 注册新客户端，返回服务端生成的 `clientId`。 */
+    /** 公钥与nonce状态的真实共享能力；生产只接受shared。 */
+    readonly stateScope: 'local' | 'shared';
+    /**
+     * 注册有效 SM2 公钥，返回服务端生成的 clientId；格式/曲线点无效或存储故障必须 reject。
+     * 容量策略见具体工厂契约：数据库满容量拒绝，开发/测试内存实现允许 FIFO 淘汰公钥。
+     * @param publicKey - 实际调用输入，按该方法约束验证。
+     * @returns 异步操作结果；存储或网络故障按方法契约拒绝。
+     *
+     * @example
+     * ```ts
+     * import { crypto } from '@h-ai/crypto'
+     * const initialized = await crypto.init()
+     * if (!initialized.success) throw new Error(initialized.error.message)
+     * try {
+     *   const generated = crypto.asymmetric.generateKeyPair()
+     *   if (!generated.success) throw new Error(generated.error.message)
+     *   const pair = generated.data
+     *   const { createInMemoryKeyStore } = await import('@h-ai/crypto')
+     *   const registry = createInMemoryKeyStore(100)
+     *   try { const clientId = await registry.register(pair.publicKey) }
+     *   finally { await registry.close?.() }
+     *   // 本例仅开发/测试；生产替换为共享Redis/数据库registry。
+     * }
+     * finally { await crypto.close() }
+     * ```
+     */
     register: (publicKey: string) => Promise<string>;
-    /** 查询已注册客户端公钥。 */
+    /**
+     * 读取已注册有效公钥；缺失返回undefined，存储失败拒绝，不能伪装未注册。
+     * @param clientId - registry生成的客户端标识。
+     * @returns 异步操作结果；存储或网络故障按方法契约拒绝。
+     *
+     * @example
+     * ```ts
+     * import { crypto } from '@h-ai/crypto'
+     * const initialized = await crypto.init()
+     * if (!initialized.success) throw new Error(initialized.error.message)
+     * try {
+     *   const generated = crypto.asymmetric.generateKeyPair()
+     *   if (!generated.success) throw new Error(generated.error.message)
+     *   const pair = generated.data
+     *   const { createInMemoryKeyStore } = await import('@h-ai/crypto')
+     *   const registry = createInMemoryKeyStore(100)
+     *   try { const clientId = await registry.register(pair.publicKey); const publicKey = await registry.get(clientId) }
+     *   finally { await registry.close?.() }
+     * }
+     * finally { await crypto.close() }
+     * ```
+     */
     get: (clientId: string) => Promise<string | undefined>;
-    /** 主动删除（可选，便于客户端登出时清理）。 */
+    /**
+     * 原子消费客户端 requestId nonce；成功返回 true，重放返回 false。
+     * 必须跨节点共享且在 expiresAt（Unix 毫秒）前不驱逐；存储故障必须 reject，禁止当作成功。
+     * @param clientId - registry生成的客户端标识。
+     * @param requestId - 本次128位随机nonce。
+     * @param expiresAt - nonce至少保留到的Unix毫秒期限。
+     * @returns 异步操作结果；存储或网络故障按方法契约拒绝。
+     *
+     * @example
+     * ```ts
+     * import { crypto } from '@h-ai/crypto'
+     * const initialized = await crypto.init()
+     * if (!initialized.success) throw new Error(initialized.error.message)
+     * try {
+     *   const generated = crypto.asymmetric.generateKeyPair()
+     *   if (!generated.success) throw new Error(generated.error.message)
+     *   const pair = generated.data
+     *   const { createInMemoryKeyStore } = await import('@h-ai/crypto')
+     *   const registry = createInMemoryKeyStore(100)
+     *   try {
+     *     const clientId = await registry.register(pair.publicKey)
+     *     const requestId = globalThis.crypto.randomUUID().replaceAll('-', '')
+     *     const expiresAt = Date.now() + 360000
+     *     const first = await registry.claimRequest(clientId, requestId, expiresAt)
+     *     const replay = await registry.claimRequest(clientId, requestId, expiresAt)
+     *     // 单进程测试预期true/false；生产需要跨节点共享原子消费且有效期间不驱逐。
+     *   }
+     *   finally { await registry.close?.() }
+     * }
+     * finally { await crypto.close() }
+     * ```
+     */
+    claimRequest: (clientId: string, requestId: string, expiresAt: number) => Promise<boolean>;
+    /**
+     * 主动删除（可选，便于客户端登出时清理）。
+     * @param clientId - registry生成的客户端标识。
+     * @returns 异步操作结果；存储或网络故障按方法契约拒绝。
+     *
+     * @example
+     * ```ts
+     * import { crypto } from '@h-ai/crypto'
+     * const initialized = await crypto.init()
+     * if (!initialized.success) throw new Error(initialized.error.message)
+     * try {
+     *   const generated = crypto.asymmetric.generateKeyPair()
+     *   if (!generated.success) throw new Error(generated.error.message)
+     *   const pair = generated.data
+     *   const { createInMemoryKeyStore } = await import('@h-ai/crypto')
+     *   const registry = createInMemoryKeyStore(100)
+     *   try { const clientId = await registry.register(pair.publicKey); await registry.delete?.(clientId) }
+     *   finally { await registry.close?.() }
+     * }
+     * finally { await crypto.close() }
+     * ```
+     */
     delete?: (clientId: string) => Promise<void>;
-    /** 释放底层资源（关闭连接、清理定时器等）。 */
+    /**
+     * 可选释放registry自有资源；借用的cache/reldb不由registry关闭。
+     * @returns 异步操作结果；存储或网络故障按方法契约拒绝。
+     *
+     * @example
+     * ```ts
+     * import { createInMemoryKeyStore } from '@h-ai/crypto'
+     * const registry = createInMemoryKeyStore(100)
+     * await registry.close?.()
+     * // 共享registry借用的cache/reldb仍由应用反序关闭。
+     * ```
+     */
     close?: () => Promise<void>;
 }
 /**
- * 创建服务端传输加密管理器的配置。
+ * 服务端创建配置；受管密钥环和共享registry均必填，没有进程随机密钥回退。
  *
- * `keyStore` 未传时，默认使用 {@link createInMemoryKeyStore}；此时可通过 `maxClients`
- * 控制进程内 FIFO 容量。若传入共享 `keyStore`，则 `maxClients` 不再生效。
+ * @example
+ * ```ts
+ * import { crypto, createRedisTransportKeyStore, parseTransportServerKeyRing } from '@h-ai/crypto'
+ * import { cache } from '@h-ai/cache'
+ * const initialized = await crypto.init()
+ * if (!initialized.success) throw new Error(initialized.error.message)
+ * try {
+ *   const connected = await cache.init({ type: 'redis', host: 'cache', port: 6379, password: process.env.HAI_CACHE_PASSWORD })
+ *   if (!connected.success) throw new Error(connected.error.message)
+ *   try {
+ *     const registry = createRedisTransportKeyStore({ cache, ttlSeconds: 3600 })
+ *     const parsed = parseTransportServerKeyRing(process.env.HAI_CRYPTO_TRANSPORT_SERVERKEYRING)
+ *     if (!parsed.success) throw new Error(parsed.error.message)
+ *     const options: import('@h-ai/crypto').TransportCreateServerOptions = { serverKeyRing: parsed.data, keyStore: registry }
+ *     const created = crypto.transport.createServer(options)
+ *     if (!created.success) throw new Error(created.error.message)
+ *     await created.data.close()
+ *   }
+ *   finally { await cache.close() }
+ * }
+ * finally { await crypto.close() }
+ * ```
  */
 interface TransportCreateServerOptions {
-    /** 客户端公钥存储；多节点部署时建议注入共享实现。 */
-    readonly keyStore?: TransportKeyStore;
-    /** 默认内存 keyStore 的最大容量（仅当 `keyStore` 未提供时生效）。 */
-    readonly maxClients?: number;
+    /** 双向业务明文 UTF-8 字节上限；默认 1 MiB，整数范围 1 KiB～64 MiB。 */
+    readonly maxPlaintextBytes?: number;
+    /** 必填受管服务端密钥环；没有隐式随机生成或进程密钥回退。 */
+    readonly serverKeyRing: TransportServerKeyRing;
+    /** 客户端公钥存储；生产必须注入跨节点共享实现。 */
+    readonly keyStore: TransportKeyStore;
 }
 /**
- * 服务端传输加密管理器。
+ * 服务端认证传输管理器；注册公钥，按真实HTTP上下文验签/MAC/时效并消费nonce，随后才返回明文。
+ * 优先使用authenticateTransportRequest；响应只用已认证上下文。close释放registry自有资源，不关闭借用的cache/reldb。
  *
- * 由 {@link createTransportEncryption} 创建；负责服务端密钥对持有、客户端密钥
- * 注册与请求/响应的加解密。
- *
- * @remarks
- * 典型调用顺序：
- *
- * 1. `registerClientKey(clientPublicKey)`：在密钥协商端点中保存客户端公钥，并生成 `clientId`。
- * 2. `getServerPublicKey()`：把服务端公钥返回给客户端，供后续请求加密会话密钥。
- * 3. `decryptRequest(payload)`：普通业务请求进入业务逻辑前，先把密文请求体解成明文。
- * 4. `encryptResponse(clientId, data)`：业务处理完成后，按当前客户端公钥重新加密响应体。
- * 5. `close()`：服务关闭时释放底层 keyStore 资源。
+ * @example
+ * ```ts
+ * import { crypto, createRedisTransportKeyStore, parseTransportServerKeyRing } from '@h-ai/crypto'
+ * import { cache } from '@h-ai/cache'
+ * const initialized = await crypto.init()
+ * if (!initialized.success) throw new Error(initialized.error.message)
+ * try {
+ *   const connected = await cache.init({ type: 'redis', host: 'cache', port: 6379, password: process.env.HAI_CACHE_PASSWORD })
+ *   if (!connected.success) throw new Error(connected.error.message)
+ *   try {
+ *     const registry = createRedisTransportKeyStore({ cache, ttlSeconds: 3600 })
+ *     const ring = parseTransportServerKeyRing(process.env.HAI_CRYPTO_TRANSPORT_SERVERKEYRING)
+ *     if (!ring.success) throw new Error(ring.error.message)
+ *     const created = crypto.transport.createServer({ serverKeyRing: ring.data, keyStore: registry })
+ *     if (!created.success) throw new Error(created.error.message)
+ *     const manager = created.data
+ *     try {
+ *       const currentVersion = manager.getServerKeyId()
+ *       const publicKey = manager.getServerPublicKey()
+ *     }
+ *     finally { await manager.close() }
+ *   }
+ *   finally { await cache.close() }
+ * }
+ * finally { await crypto.close() }
+ * ```
  */
 interface TransportEncryptionManager {
+    /** 本管理器不可变的双向预算；由 maxPlaintextBytes 推导，安全预算独立。 */
+    readonly bodyLimits: TransportBodyLimits;
+    /**
+     * 当前新协商使用的服务端密钥 ID。
+     * @returns 直接返回值，使用前先初始化模块。
+     *
+     * @example
+     * ```ts
+     * import type { TransportEncryptionManager } from '@h-ai/crypto'
+     * function activeVersion(manager: TransportEncryptionManager): string { return manager.getServerKeyId() }
+     * ```
+     */
+    getServerKeyId: () => string;
+    /**
+     * 返回当前活动版本的公开公钥，只用于可信TLS协商，不含私钥。
+     * @returns 直接返回值，使用前先初始化模块。
+     *
+     * @example
+     * ```ts
+     * import type { TransportEncryptionManager } from '@h-ai/crypto'
+     * function activePublicKey(manager: TransportEncryptionManager): string { return manager.getServerPublicKey() }
+     * ```
+     */
     getServerPublicKey: () => string;
+    /**
+     * 验证 SM2 公钥编码和曲线点后向显式 registry 注册。
+     * @throws 公钥无效或 registry 写入失败；HTTP 协商适配器负责转换成失败响应。
+     * @param clientPublicKey - 实际调用输入，按该方法约束验证。
+     * @returns 异步操作结果；存储或网络故障按方法契约拒绝。
+     *
+     * @example
+     * ```ts
+     * import type { TransportEncryptionManager } from '@h-ai/crypto'
+     * async function register(manager: TransportEncryptionManager, clientPublicKey: string): Promise<string> {
+     *   // 方法校验编码/曲线点后写入共享registry；异常由HTTP协商适配器转成失败响应。
+     *   return manager.registerClientKey(clientPublicKey)
+     * }
+     * ```
+     */
     registerClientKey: (clientPublicKey: string) => Promise<string>;
+    /**
+     * 查询客户端公钥；registry 读取故障会 reject，不作为未注册处理。
+     * @param clientId - registry生成的客户端标识。
+     * @returns 异步操作结果；存储或网络故障按方法契约拒绝。
+     *
+     * @example
+     * ```ts
+     * import type { TransportEncryptionManager } from '@h-ai/crypto'
+     * async function lookup(manager: TransportEncryptionManager, clientId: string): Promise<string | undefined> {
+     *   return manager.getClientPublicKey(clientId)
+     * }
+     * ```
+     */
     getClientPublicKey: (clientId: string) => Promise<string | undefined>;
-    encryptResponse: (clientId: string, data: string) => Promise<HaiResult<EncryptedPayload>>;
-    decryptRequest: (payload: EncryptedPayload) => HaiResult<string>;
-    /** 关闭：释放 keyStore 资源。 */
+    /**
+     * 按已认证请求上下文加密、MAC 并签名响应，绑定实际 HTTP 状态。
+     * registry 及加密故障均返回失败 HaiResult；上下文只能来自成功的请求认证。
+     * @param request - 实际调用输入，按该方法约束验证。
+     * @param data - 实际调用输入，按该方法约束验证。
+     * @param status - 实际调用输入，按该方法约束验证。
+     * @returns HaiResult，先检查success再读取data。
+     *
+     * @example
+     * ```ts
+     * import { authenticateTransportRequest, type EncryptedPayload, type TransportEncryptionManager } from '@h-ai/crypto'
+     * async function sealResponse(manager: TransportEncryptionManager, request: Request): Promise<EncryptedPayload> {
+     *   const verified = await authenticateTransportRequest(manager, request)
+     *   if (!verified.success) throw new Error(verified.error.message)
+     *   const encrypted = await manager.encryptResponse(verified.data.context, JSON.stringify({ accepted: true }), 200)
+     *   if (!encrypted.success) throw new Error(encrypted.error.message)
+     *   return encrypted.data
+     * }
+     * ```
+     */
+    encryptResponse: (request: TransportMessageContext, data: string, status: number) => Promise<HaiResult<EncryptedPayload>>;
+    /**
+     * 验证发送方、MAC、HTTP 绑定和时效，原子消费 nonce 后才返回明文；错误不含密文或 Secret。
+     * expected 须从实际 Request 提取，不从 payload 复制。HTTP 优先用 authenticateTransportRequest。
+     * @param payload - 实际调用输入，按该方法约束验证。
+     * @param expected - 实际调用输入，按该方法约束验证。
+     * @returns HaiResult，先检查success再读取data。
+     *
+     * @example
+     * ```ts
+     * import type { EncryptedRequestPayload, TransportEncryptionManager } from '@h-ai/crypto'
+     * async function decrypt(manager: TransportEncryptionManager, request: Request, payload: EncryptedRequestPayload): Promise<string> {
+     *   const clientId = request.headers.get('X-Client-Id')
+     *   if (!clientId) throw new Error('Missing client ID')
+     *   const url = new URL(request.url)
+     *   const result = await manager.decryptRequest(payload, { clientId, method: request.method, path: url.pathname + url.search })
+     *   if (!result.success) throw new Error(result.error.message)
+     *   return result.data
+     * }
+     * ```
+     */
+    decryptRequest: (payload: EncryptedRequestPayload, expected: TransportRequestContext) => Promise<HaiResult<string>>;
+    /**
+     * 释放registry自有资源；应用仍负责借用cache/reldb的关闭。
+     * @returns 异步操作结果；存储或网络故障按方法契约拒绝。
+     *
+     * @example
+     * ```ts
+     * import { crypto, createRedisTransportKeyStore, parseTransportServerKeyRing } from '@h-ai/crypto'
+     * import { cache } from '@h-ai/cache'
+     * const initialized = await crypto.init()
+     * if (!initialized.success) throw new Error(initialized.error.message)
+     * try {
+     *   const connected = await cache.init({ type: 'redis', host: 'cache', port: 6379, password: process.env.HAI_CACHE_PASSWORD })
+     *   if (!connected.success) throw new Error(connected.error.message)
+     *   try {
+     *     const registry = createRedisTransportKeyStore({ cache, ttlSeconds: 3600 })
+     *     const ring = parseTransportServerKeyRing(process.env.HAI_CRYPTO_TRANSPORT_SERVERKEYRING)
+     *     if (!ring.success) throw new Error(ring.error.message)
+     *     const created = crypto.transport.createServer({ serverKeyRing: ring.data, keyStore: registry })
+     *     if (!created.success) throw new Error(created.error.message)
+     *     const manager = created.data
+     *     try {
+     *       const currentVersion = manager.getServerKeyId()
+     *       const publicKey = manager.getServerPublicKey()
+     *     }
+     *     finally { await manager.close() }
+     *   }
+     *   finally { await cache.close() }
+     * }
+     * finally { await crypto.close() }
+     * ```
+     */
     close: () => Promise<void>;
 }
 /**
- * 客户端传输加密会话。
+ * 客户端单会话；首次调用自动协商，后续请求生成随机nonce并认证响应关联/签名/MAC。
+ * init返回HaiResult；encryptedFetch按fetch契约reject；destroy清本地会话，不代表撤销服务端registry。
  *
- * 由 {@link createTransportClient} 创建；包装宿主 `fetch`，
- * 自动完成首次密钥协商并对后续请求自动加解密。
- *
- * @remarks
- * 典型调用顺序：
- *
- * 1. `init()`（可选）：预先完成一次密钥协商。
- * 2. `encryptedFetch()`：业务请求统一走这里；若当前会话尚未 ready，会先自动执行 `init()`。
- * 3. `ready()`：查看当前会话是否已经拿到 `clientId` 与服务端公钥。
- * 4. `destroy()`：登出、切租户或切环境时清空会话；下一次请求会重新协商。
+ * @example
+ * ```ts
+ * import { crypto } from '@h-ai/crypto'
+ * const initialized = await crypto.init()
+ * if (!initialized.success) throw new Error(initialized.error.message)
+ * try {
+ *   const client = crypto.transport.createClient({ keyExchangeUrl: 'https://api.example.com/api/v1/_hai/key-exchange' })
+ *   try {
+ *     const ready = await client.init()
+ *     if (!ready.success) throw new Error(ready.error.message)
+ *     const response = await client.encryptedFetch('https://api.example.com/api/v1/orders')
+ *     if (!response.ok) throw new Error('HTTP request failed')
+ *   }
+ *   finally { client.destroy() }
+ * }
+ * finally { await crypto.close() }
+ * ```
  */
 interface TransportClient {
     /**
      * 完成密钥协商；多次调用幂等（同一会话只协商一次）。
      *
      * 通常无需手动调用：`encryptedFetch` 在首次请求前会自动 `init()`。
+     * 协商在 30 秒内完成，握手 JSON 与单个公钥分别受 TRANSPORT_BODY_LIMITS 限制。
+     * @returns HaiResult，先检查success再读取data。
+     *
+     * @example
+     * ```ts
+     * import { crypto } from '@h-ai/crypto'
+     * const initialized = await crypto.init()
+     * if (!initialized.success) throw new Error(initialized.error.message)
+     * try {
+     *   const client = crypto.transport.createClient({ keyExchangeUrl: 'https://api.example.com/api/v1/_hai/key-exchange' })
+     *   try {
+     *     const ready = await client.init()
+     *     if (!ready.success) throw new Error(ready.error.message)
+     *     const response = await client.encryptedFetch('https://api.example.com/api/v1/orders')
+     *     if (!response.ok) throw new Error('HTTP request failed')
+     *   }
+     *   finally { client.destroy() }
+     * }
+     * finally { await crypto.close() }
+     * ```
      */
     init: () => Promise<HaiResult<void>>;
     /**
      * 包装后的 fetch；签名与全局 `fetch` 一致，请求/响应自动加解密。
+     * 明文/密文按 TRANSPORT_BODY_LIMITS 有界读取原流；超限或取消释放 reader，保留调用方 signal。
+     * 仅接受关联同一请求上下文与 HTTP status 的认证响应；缺标记也拒绝，不回退明文或密文。
      *
      * @throws 与原生 fetch 一样，网络错误、密钥协商失败、加密失败或解密失败会 reject。
+     *
+     * @example
+     * ```ts
+     * import { crypto } from '@h-ai/crypto'
+     * const initialized = await crypto.init()
+     * if (!initialized.success) throw new Error(initialized.error.message)
+     * try {
+     *   const client = crypto.transport.createClient({ keyExchangeUrl: 'https://api.example.com/api/v1/_hai/key-exchange' })
+     *   try {
+     *     const ready = await client.init()
+     *     if (!ready.success) throw new Error(ready.error.message)
+     *     const response = await client.encryptedFetch('https://api.example.com/api/v1/orders')
+     *     if (!response.ok) throw new Error('HTTP request failed')
+     *   }
+     *   finally { client.destroy() }
+     * }
+     * finally { await crypto.close() }
+     * ```
      */
     encryptedFetch: typeof fetch;
-    /** 是否已完成密钥协商。 */
+    /**
+     * 是否已完成密钥协商。
+     * @returns 直接boolean，false表示不匹配/未就绪。
+     *
+     * @example
+     * ```ts
+     * import { crypto } from '@h-ai/crypto'
+     * const initialized = await crypto.init()
+     * if (!initialized.success) throw new Error(initialized.error.message)
+     * try {
+     *   const client = crypto.transport.createClient({ keyExchangeUrl: 'https://api.example.com/api/v1/_hai/key-exchange' })
+     *   try { const ready = client.ready() }
+     *   finally { client.destroy() }
+     * }
+     * finally { await crypto.close() }
+     * ```
+     */
     ready: () => boolean;
-    /** 销毁会话（清空客户端密钥）。 */
+    /**
+     * 清空本地客户端密钥与协商状态；下次请求重新协商，不撤销服务端身份或业务效果。
+     * @returns 直接返回值，使用前先初始化模块。
+     *
+     * @example
+     * ```ts
+     * import { crypto } from '@h-ai/crypto'
+     * const initialized = await crypto.init()
+     * if (!initialized.success) throw new Error(initialized.error.message)
+     * try {
+     *   const client = crypto.transport.createClient({ keyExchangeUrl: 'https://api.example.com/api/v1/_hai/key-exchange' })
+     *   client.destroy()
+     *   // 只清本地会话；不撤销服务端registry或业务会话。
+     * }
+     * finally { await crypto.close() }
+     * ```
+     */
     destroy: () => void;
 }
 
+/**
+ * 加密领域标准错误集合；先判断 HaiResult.success，错误上下文不得附带明文或私钥。
+ *
+ * @example
+ * ```ts
+ * import { crypto, HaiCryptoError } from '@h-ai/crypto'
+ * const result = crypto.hash.hash('hello')
+ * if (!result.success && result.error.code === HaiCryptoError.NOT_INITIALIZED.code) {
+ *   // 尚未初始化时按生命周期处理，不忽略错误继续加密。
+ *   const message = result.error.message
+ * }
+ * ```
+ */
 declare const HaiCryptoError: {
     readonly INVALID_INPUT: _h_ai_core.HaiErrorDef;
     readonly INVALID_KEY: _h_ai_core.HaiErrorDef;
@@ -178,40 +853,185 @@ declare const HaiCryptoError: {
     readonly HASH_FAILED: _h_ai_core.HaiErrorDef;
     readonly HMAC_FAILED: _h_ai_core.HaiErrorDef;
     readonly INVALID_IV: _h_ai_core.HaiErrorDef;
+    readonly TRANSPORT_PAYLOAD_TOO_LARGE: _h_ai_core.HaiErrorDef;
+    readonly TRANSPORT_TIME_INVALID: _h_ai_core.HaiErrorDef;
 };
-/** 密文模式：0=C1C2C3（旧版），1=C1C3C2（国标） */
+/**
+ * SM2 密文排列：1为C1C3C2默认值，0为显式C1C2C3；解密必须匹配加密排列。
+ *
+ * @example
+ * ```ts
+ * import { crypto, type CipherMode } from '@h-ai/crypto'
+ * const initialized = await crypto.init()
+ * if (!initialized.success) throw new Error(initialized.error.message)
+ * try {
+ *   const generated = crypto.asymmetric.generateKeyPair()
+ *   if (!generated.success) throw new Error(generated.error.message)
+ *   const pair = generated.data
+ *   const mode: CipherMode = 1
+ *   const encrypted = crypto.asymmetric.encrypt('hello', pair.publicKey, { cipherMode: mode })
+ *   if (!encrypted.success) throw new Error(encrypted.error.message)
+ *   const decrypted = crypto.asymmetric.decrypt(encrypted.data, pair.privateKey, { cipherMode: mode })
+ *   if (!decrypted.success) throw new Error(decrypted.error.message)
+ * }
+ * finally { await crypto.close() }
+ * ```
+ */
 type CipherMode = 0 | 1;
-/** 非对称密钥对 */
+/**
+ * SM2 公私钥对；私钥必须保密，不写日志、公开配置或响应。
+ *
+ * @example
+ * ```ts
+ * import { crypto, type KeyPair } from '@h-ai/crypto'
+ * const initialized = await crypto.init()
+ * if (!initialized.success) throw new Error(initialized.error.message)
+ * try {
+ *   const generated = crypto.asymmetric.generateKeyPair()
+ *   if (!generated.success) throw new Error(generated.error.message)
+ *   const pair = generated.data
+ *   const keyPair: KeyPair = pair
+ *   const publicKey = keyPair.publicKey
+ * }
+ * finally { await crypto.close() }
+ * ```
+ */
 interface KeyPair {
     /** 公钥（十六进制字符串，包含 04 前缀为非压缩格式） */
     publicKey: string;
     /** 私钥（十六进制字符串，64 字符） */
     privateKey: string;
 }
-/** 非对称加密选项 */
+/**
+ * SM2 密文排列和输出编码；加解密 cipherMode 必须一致，解密可识别受支持的 base64 输出。
+ *
+ * @example
+ * ```ts
+ * import { crypto, type AsymmetricEncryptOptions } from '@h-ai/crypto'
+ * const initialized = await crypto.init()
+ * if (!initialized.success) throw new Error(initialized.error.message)
+ * try {
+ *   const generated = crypto.asymmetric.generateKeyPair()
+ *   if (!generated.success) throw new Error(generated.error.message)
+ *   const pair = generated.data
+ *   const options: AsymmetricEncryptOptions = { cipherMode: 1, outputFormat: 'base64' }
+ *   const encrypted = crypto.asymmetric.encrypt('hello', pair.publicKey, options)
+ *   if (!encrypted.success) throw new Error(encrypted.error.message)
+ *   const decrypted = crypto.asymmetric.decrypt(encrypted.data, pair.privateKey, options)
+ *   if (!decrypted.success) throw new Error(decrypted.error.message)
+ * }
+ * finally { await crypto.close() }
+ * ```
+ */
 interface AsymmetricEncryptOptions {
     /** 密文模式：0=C1C2C3（旧版），1=C1C3C2（国标，默认） */
     cipherMode?: CipherMode;
     /** 输出格式 */
     outputFormat?: 'hex' | 'base64';
 }
-/** 签名选项 */
+/**
+ * SM2 签名的哈希与用户标识参数；验签必须使用相同设置，默认启用哈希。
+ *
+ * @example
+ * ```ts
+ * import { crypto, type SignOptions } from '@h-ai/crypto'
+ * const initialized = await crypto.init()
+ * if (!initialized.success) throw new Error(initialized.error.message)
+ * try {
+ *   const generated = crypto.asymmetric.generateKeyPair()
+ *   if (!generated.success) throw new Error(generated.error.message)
+ *   const pair = generated.data
+ *   const options: SignOptions = { hash: true, userId: 'orders-service' }
+ *   const signature = crypto.asymmetric.sign('hello', pair.privateKey, options)
+ *   if (!signature.success) throw new Error(signature.error.message)
+ *   const verified = crypto.asymmetric.verify('hello', signature.data, pair.publicKey, options)
+ *   if (!verified.success) throw new Error(verified.error.message)
+ *   const accepted = verified.data
+ * }
+ * finally { await crypto.close() }
+ * ```
+ */
 interface SignOptions {
     /** 是否对数据进行哈希（默认 true） */
     hash?: boolean;
     /** 用户 ID（默认 "1234567812345678"） */
     userId?: string;
 }
-/** 哈希选项 */
+/**
+ * 字符串输入编码；hex 表示解码后的字节，Uint8Array 直接作为字节输入。
+ *
+ * @example
+ * ```ts
+ * import { crypto, type HashOptions } from '@h-ai/crypto'
+ * const initialized = await crypto.init()
+ * if (!initialized.success) throw new Error(initialized.error.message)
+ * try {
+ *   const options: HashOptions = { inputEncoding: 'hex' }
+ *   const digest = crypto.hash.hash('6869', options)
+ *   if (!digest.success) throw new Error(digest.error.message)
+ * }
+ * finally { await crypto.close() }
+ * ```
+ */
 interface HashOptions {
     /** 输入编码 */
     inputEncoding?: 'utf8' | 'hex';
 }
-/** 对称加密模式 */
+/**
+ * SM4 的 CBC/ECB 模式；新数据使用默认 CBC，ECB 会暴露相同明文块结构，两者都不提供 MAC。
+ *
+ * @example
+ * ```ts
+ * import { crypto, type SymmetricMode } from '@h-ai/crypto'
+ * const initialized = await crypto.init()
+ * if (!initialized.success) throw new Error(initialized.error.message)
+ * try {
+ *   const mode: SymmetricMode = 'cbc'
+ *   const key = crypto.symmetric.generateKey()
+ *   const encrypted = crypto.symmetric.encrypt('hello', key, { mode })
+ *   if (!encrypted.success) throw new Error(encrypted.error.message)
+ * }
+ * finally { await crypto.close() }
+ * ```
+ */
 type SymmetricMode = 'ecb' | 'cbc';
-/** 对称密文编码 */
+/**
+ * 结构化 SM4 ciphertext 的 hex/base64 编码标识，解密必须保留。
+ *
+ * @example
+ * ```ts
+ * import { crypto, type SymmetricCiphertextEncoding } from '@h-ai/crypto'
+ * const initialized = await crypto.init()
+ * if (!initialized.success) throw new Error(initialized.error.message)
+ * try {
+ *   const outputFormat: SymmetricCiphertextEncoding = 'base64'
+ *   const key = crypto.symmetric.generateKey()
+ *   const encrypted = crypto.symmetric.encrypt('hello', key, { outputFormat })
+ *   if (!encrypted.success) throw new Error(encrypted.error.message)
+ *   const decrypted = crypto.symmetric.decrypt(encrypted.data, key)
+ *   if (!decrypted.success) throw new Error(decrypted.error.message)
+ * }
+ * finally { await crypto.close() }
+ * ```
+ */
 type SymmetricCiphertextEncoding = 'hex' | 'base64';
-/** 对称加密选项。默认 CBC，并自动生成随机 IV。 */
+/**
+ * SM4 模式、IV 与编码；CBC 未提供 IV 时随机生成，手动 IV 必须每次独立随机。
+ *
+ * @example
+ * ```ts
+ * import { crypto, type SymmetricEncryptOptions } from '@h-ai/crypto'
+ * const initialized = await crypto.init()
+ * if (!initialized.success) throw new Error(initialized.error.message)
+ * try {
+ *   const options: SymmetricEncryptOptions = { mode: 'cbc', outputFormat: 'base64' }
+ *   const key = crypto.symmetric.generateKey()
+ *   const encrypted = crypto.symmetric.encrypt('hello', key, options)
+ *   if (!encrypted.success) throw new Error(encrypted.error.message)
+ * }
+ * finally { await crypto.close() }
+ * ```
+ */
 interface SymmetricEncryptOptions {
     /** 加密模式；默认 cbc */
     mode?: SymmetricMode;
@@ -220,7 +1040,25 @@ interface SymmetricEncryptOptions {
     /** 密文输出编码；默认 hex */
     outputFormat?: SymmetricCiphertextEncoding;
 }
-/** 对称加密结构化结果。 */
+/**
+ * SM4 密文及 mode/encoding/可选 IV；保留全部字段才能正确解密，不含消息认证能力。
+ *
+ * @example
+ * ```ts
+ * import { crypto, type SymmetricEncryptedPayload } from '@h-ai/crypto'
+ * const initialized = await crypto.init()
+ * if (!initialized.success) throw new Error(initialized.error.message)
+ * try {
+ *   const key = crypto.symmetric.generateKey()
+ *   const encrypted = crypto.symmetric.encrypt('hello', key)
+ *   if (!encrypted.success) throw new Error(encrypted.error.message)
+ *   const payload: SymmetricEncryptedPayload = encrypted.data
+ *   const decrypted = crypto.symmetric.decrypt(payload, key)
+ *   if (!decrypted.success) throw new Error(decrypted.error.message)
+ * }
+ * finally { await crypto.close() }
+ * ```
+ */
 interface SymmetricEncryptedPayload {
     /** 加密模式 */
     readonly mode: SymmetricMode;
@@ -231,16 +1069,87 @@ interface SymmetricEncryptedPayload {
     /** ciphertext 字段的编码 */
     readonly encoding: SymmetricCiphertextEncoding;
 }
-/** CBC 模式结构化结果。 */
+/**
+ * CBC 结构化密文，mode固定cbc且IV必填；仍需上层消息认证。
+ *
+ * @example
+ * ```ts
+ * import { crypto, type SymmetricCbcEncryptedPayload } from '@h-ai/crypto'
+ * const initialized = await crypto.init()
+ * if (!initialized.success) throw new Error(initialized.error.message)
+ * try {
+ *   const key = crypto.symmetric.generateKey()
+ *   const encrypted = crypto.symmetric.encryptWithIV('hello', key)
+ *   if (!encrypted.success) throw new Error(encrypted.error.message)
+ *   const payload: SymmetricCbcEncryptedPayload = encrypted.data
+ *   const decrypted = crypto.symmetric.decrypt(payload, key)
+ *   if (!decrypted.success) throw new Error(decrypted.error.message)
+ * }
+ * finally { await crypto.close() }
+ * ```
+ */
 interface SymmetricCbcEncryptedPayload extends SymmetricEncryptedPayload {
     readonly mode: 'cbc';
     readonly iv: string;
 }
-/** 对称解密输入。 */
+/**
+ * SM4 解密输入别名；传入加密返回的完整结构，不能用裸密文猜测IV或编码。
+ *
+ * @example
+ * ```ts
+ * import { crypto, type SymmetricDecryptInput } from '@h-ai/crypto'
+ * const initialized = await crypto.init()
+ * if (!initialized.success) throw new Error(initialized.error.message)
+ * try {
+ *   const key = crypto.symmetric.generateKey()
+ *   const encrypted = crypto.symmetric.encrypt('hello', key)
+ *   if (!encrypted.success) throw new Error(encrypted.error.message)
+ *   const payload: SymmetricDecryptInput = encrypted.data
+ *   const decrypted = crypto.symmetric.decrypt(payload, key)
+ *   if (!decrypted.success) throw new Error(decrypted.error.message)
+ * }
+ * finally { await crypto.close() }
+ * ```
+ */
 type SymmetricDecryptInput = SymmetricEncryptedPayload;
-/** 带 IV 加密结果。 */
+/**
+ * encryptWithIV 的CBC结构化结果别名；含 mode、ciphertext、iv 与 encoding。
+ *
+ * @example
+ * ```ts
+ * import { crypto, type EncryptWithIVResult } from '@h-ai/crypto'
+ * const initialized = await crypto.init()
+ * if (!initialized.success) throw new Error(initialized.error.message)
+ * try {
+ *   const key = crypto.symmetric.generateKey()
+ *   const encrypted = crypto.symmetric.encryptWithIV('hello', key)
+ *   if (!encrypted.success) throw new Error(encrypted.error.message)
+ *   const payload: EncryptWithIVResult = encrypted.data
+ *   const decrypted = crypto.symmetric.decrypt(payload, key)
+ *   if (!decrypted.success) throw new Error(decrypted.error.message)
+ * }
+ * finally { await crypto.close() }
+ * ```
+ */
 type EncryptWithIVResult = SymmetricCbcEncryptedPayload;
-/** 密码哈希配置 */
+/**
+ * 迭代SM3密码参数；默认盐长16、迭代10000，合法范围以实现校验为准，已有哈希自行携带参数。
+ *
+ * @example
+ * ```ts
+ * import { crypto, type PasswordConfig } from '@h-ai/crypto'
+ * const initialized = await crypto.init()
+ * if (!initialized.success) throw new Error(initialized.error.message)
+ * try {
+ *   const config: PasswordConfig = { saltLength: 16, iterations: 10000 }
+ *   const hashed = crypto.password.hash('test-password', config)
+ *   if (!hashed.success) throw new Error(hashed.error.message)
+ *   const verified = crypto.password.verify('test-password', hashed.data)
+ *   if (!verified.success) throw new Error(verified.error.message)
+ * }
+ * finally { await crypto.close() }
+ * ```
+ */
 interface PasswordConfig {
     /** 盐值长度（默认 16） */
     saltLength?: number;
@@ -248,15 +1157,47 @@ interface PasswordConfig {
     iterations?: number;
 }
 /**
- * 非对称加密操作接口
+ * SM2 操作域；先初始化，所有 HaiResult 先检查 success，boolean 校验器按直接返回值使用。
+ * 公钥曲线点有效不等于对端身份可信；可信公钥分发仍由TLS/受管信任链保证。
  *
- * 通过 `crypto.asymmetric` 访问，需先调用 `crypto.init()`。
+ * @example
+ * ```ts
+ * import { crypto, type AsymmetricOperations } from '@h-ai/crypto'
+ * const initialized = await crypto.init()
+ * if (!initialized.success) throw new Error(initialized.error.message)
+ * try {
+ *   const generated = crypto.asymmetric.generateKeyPair()
+ *   if (!generated.success) throw new Error(generated.error.message)
+ *   const pair = generated.data
+ *   const operations: AsymmetricOperations = crypto.asymmetric
+ *   const signature = operations.sign('hello', pair.privateKey)
+ *   if (!signature.success) throw new Error(signature.error.message)
+ *   const verified = operations.verify('hello', signature.data, pair.publicKey)
+ *   if (!verified.success) throw new Error(verified.error.message)
+ *   const matches = verified.data
+ * }
+ * finally { await crypto.close() }
+ * ```
  */
 interface AsymmetricOperations {
     /**
      * 生成密钥对
      *
      * @returns 成功时包含公私钥对；失败时返回 KEY_GENERATION_FAILED
+     *
+     * @example
+     * ```ts
+     * import { crypto } from '@h-ai/crypto'
+     * const initialized = await crypto.init()
+     * if (!initialized.success) throw new Error(initialized.error.message)
+     * try {
+     *   const generated = crypto.asymmetric.generateKeyPair()
+     *   if (!generated.success) throw new Error(generated.error.message)
+     *   const pair = generated.data
+     *   const publicKey = pair.publicKey
+     * }
+     * finally { await crypto.close() }
+     * ```
      */
     generateKeyPair: () => HaiResult<KeyPair>;
     /**
@@ -266,6 +1207,21 @@ interface AsymmetricOperations {
      * @param publicKey - 公钥（十六进制，支持带/不带 04 前缀）
      * @param options - 加密选项（密文模式、输出格式）
      * @returns 成功时返回密文字符串；失败时返回 INVALID_KEY 或 ENCRYPTION_FAILED
+     *
+     * @example
+     * ```ts
+     * import { crypto } from '@h-ai/crypto'
+     * const initialized = await crypto.init()
+     * if (!initialized.success) throw new Error(initialized.error.message)
+     * try {
+     *   const generated = crypto.asymmetric.generateKeyPair()
+     *   if (!generated.success) throw new Error(generated.error.message)
+     *   const pair = generated.data
+     *   const encrypted = crypto.asymmetric.encrypt('hello', pair.publicKey, { cipherMode: 1, outputFormat: 'hex' })
+     *   if (!encrypted.success) throw new Error(encrypted.error.message)
+     * }
+     * finally { await crypto.close() }
+     * ```
      */
     encrypt: (data: string, publicKey: string, options?: AsymmetricEncryptOptions) => HaiResult<string>;
     /**
@@ -277,6 +1233,23 @@ interface AsymmetricOperations {
      * @param privateKey - 私钥（64 字符十六进制）
      * @param options - 解密选项（密文模式需与加密时一致）
      * @returns 成功时返回明文；失败时返回 INVALID_KEY 或 DECRYPTION_FAILED
+     *
+     * @example
+     * ```ts
+     * import { crypto } from '@h-ai/crypto'
+     * const initialized = await crypto.init()
+     * if (!initialized.success) throw new Error(initialized.error.message)
+     * try {
+     *   const generated = crypto.asymmetric.generateKeyPair()
+     *   if (!generated.success) throw new Error(generated.error.message)
+     *   const pair = generated.data
+     *   const encrypted = crypto.asymmetric.encrypt('hello', pair.publicKey)
+     *   if (!encrypted.success) throw new Error(encrypted.error.message)
+     *   const decrypted = crypto.asymmetric.decrypt(encrypted.data, pair.privateKey)
+     *   if (!decrypted.success) throw new Error(decrypted.error.message)
+     * }
+     * finally { await crypto.close() }
+     * ```
      */
     decrypt: (ciphertext: string, privateKey: string, options?: AsymmetricEncryptOptions) => HaiResult<string>;
     /**
@@ -286,6 +1259,21 @@ interface AsymmetricOperations {
      * @param privateKey - 私钥（64 字符十六进制）
      * @param options - 签名选项（hash 开关、userId）
      * @returns 成功时返回签名字符串；失败时返回 INVALID_KEY 或 SIGN_FAILED
+     *
+     * @example
+     * ```ts
+     * import { crypto } from '@h-ai/crypto'
+     * const initialized = await crypto.init()
+     * if (!initialized.success) throw new Error(initialized.error.message)
+     * try {
+     *   const generated = crypto.asymmetric.generateKeyPair()
+     *   if (!generated.success) throw new Error(generated.error.message)
+     *   const pair = generated.data
+     *   const signature = crypto.asymmetric.sign('hello', pair.privateKey)
+     *   if (!signature.success) throw new Error(signature.error.message)
+     * }
+     * finally { await crypto.close() }
+     * ```
      */
     sign: (data: string, privateKey: string, options?: SignOptions) => HaiResult<string>;
     /**
@@ -296,25 +1284,84 @@ interface AsymmetricOperations {
      * @param publicKey - 公钥（支持带/不带 04 前缀）
      * @param options - 验签选项
      * @returns 成功时返回 boolean；失败时返回 INVALID_KEY 或 VERIFY_FAILED
+     *
+     * @example
+     * ```ts
+     * import { crypto } from '@h-ai/crypto'
+     * const initialized = await crypto.init()
+     * if (!initialized.success) throw new Error(initialized.error.message)
+     * try {
+     *   const generated = crypto.asymmetric.generateKeyPair()
+     *   if (!generated.success) throw new Error(generated.error.message)
+     *   const pair = generated.data
+     *   const signature = crypto.asymmetric.sign('hello', pair.privateKey)
+     *   if (!signature.success) throw new Error(signature.error.message)
+     *   const verified = crypto.asymmetric.verify('hello', signature.data, pair.publicKey)
+     *   if (!verified.success) throw new Error(verified.error.message)
+     *   const accepted = verified.data
+     * }
+     * finally { await crypto.close() }
+     * ```
      */
     verify: (data: string, signature: string, publicKey: string, options?: SignOptions) => HaiResult<boolean>;
     /**
-     * 校验公钥格式是否合法
+     * 校验128/130字符SM2非压缩公钥编码及曲线点；有效不代表对端持有私钥。
+     * @param key - 本次操作的密钥，不记录到日志。
+     * @returns 直接boolean，false表示不匹配/未就绪。
      *
-     * 合法格式：128 字符十六进制（无前缀）或 130 字符（含 04 前缀）。
+     * @example
+     * ```ts
+     * import { crypto } from '@h-ai/crypto'
+     * const initialized = await crypto.init()
+     * if (!initialized.success) throw new Error(initialized.error.message)
+     * try {
+     *   const generated = crypto.asymmetric.generateKeyPair()
+     *   if (!generated.success) throw new Error(generated.error.message)
+     *   const pair = generated.data
+     *   const valid = crypto.asymmetric.isValidPublicKey(pair.publicKey)
+     * }
+     * finally { await crypto.close() }
+     * ```
      */
     isValidPublicKey: (key: string) => boolean;
     /**
-     * 校验私钥格式是否合法
+     * 校验64字符十六进制私钥格式；这是格式检查，不是密钥配对证明。
+     * @param key - 本次操作的密钥，不记录到日志。
+     * @returns 直接boolean，false表示不匹配/未就绪。
      *
-     * 合法格式：64 字符十六进制。
+     * @example
+     * ```ts
+     * import { crypto } from '@h-ai/crypto'
+     * const initialized = await crypto.init()
+     * if (!initialized.success) throw new Error(initialized.error.message)
+     * try {
+     *   const generated = crypto.asymmetric.generateKeyPair()
+     *   if (!generated.success) throw new Error(generated.error.message)
+     *   const pair = generated.data
+     *   const valid = crypto.asymmetric.isValidPrivateKey(pair.privateKey)
+     * }
+     * finally { await crypto.close() }
+     * ```
      */
     isValidPrivateKey: (key: string) => boolean;
 }
 /**
- * 哈希操作接口
+ * SM3 摘要、HMAC-SM3 与常量时间摘要匹配操作；摘要不是加密，HMAC密钥不能公开。
  *
- * 通过 `crypto.hash` 访问，需先调用 `crypto.init()`。
+ * @example
+ * ```ts
+ * import { crypto, type HashOperations } from '@h-ai/crypto'
+ * const initialized = await crypto.init()
+ * if (!initialized.success) throw new Error(initialized.error.message)
+ * try {
+ *   const operations: HashOperations = crypto.hash
+ *   const digest = operations.hash('hello')
+ *   if (!digest.success) throw new Error(digest.error.message)
+ *   const verified = operations.verify('hello', digest.data)
+ *   if (!verified.success) throw new Error(verified.error.message)
+ * }
+ * finally { await crypto.close() }
+ * ```
  */
 interface HashOperations {
     /**
@@ -323,6 +1370,18 @@ interface HashOperations {
      * @param data - 待哈希数据（字符串或 Uint8Array）
      * @param options - 输入编码选项
      * @returns 成功时返回 64 字符十六进制哈希值；失败时返回 HASH_FAILED
+     *
+     * @example
+     * ```ts
+     * import { crypto } from '@h-ai/crypto'
+     * const initialized = await crypto.init()
+     * if (!initialized.success) throw new Error(initialized.error.message)
+     * try {
+     *   const digest = crypto.hash.hash('6869', { inputEncoding: 'hex' })
+     *   if (!digest.success) throw new Error(digest.error.message)
+     * }
+     * finally { await crypto.close() }
+     * ```
      */
     hash: (data: string | Uint8Array, options?: HashOptions) => HaiResult<string>;
     /**
@@ -334,6 +1393,19 @@ interface HashOperations {
      * @param data - 待计算数据
      * @param key - HMAC 密钥
      * @returns 成功时返回 64 字符十六进制 HMAC 值；失败时返回 HMAC_FAILED
+     *
+     * @example
+     * ```ts
+     * import { crypto } from '@h-ai/crypto'
+     * const initialized = await crypto.init()
+     * if (!initialized.success) throw new Error(initialized.error.message)
+     * try {
+     *   const key = crypto.symmetric.generateKey()
+     *   const tag = crypto.hash.hmac('hello', key)
+     *   if (!tag.success) throw new Error(tag.error.message)
+     * }
+     * finally { await crypto.close() }
+     * ```
      */
     hmac: (data: string, key: string) => HaiResult<string>;
     /**
@@ -344,19 +1416,77 @@ interface HashOperations {
      * @param data - 原始数据
      * @param expectedHash - 期望的哈希值
      * @returns 成功时返回 boolean；失败时返回 HASH_FAILED
+     *
+     * @example
+     * ```ts
+     * import { crypto } from '@h-ai/crypto'
+     * const initialized = await crypto.init()
+     * if (!initialized.success) throw new Error(initialized.error.message)
+     * try {
+     *   const digest = crypto.hash.hash('hello')
+     *   if (!digest.success) throw new Error(digest.error.message)
+     *   const verified = crypto.hash.verify('hello', digest.data)
+     *   if (!verified.success) throw new Error(verified.error.message)
+     *   const matches = verified.data
+     * }
+     * finally { await crypto.close() }
+     * ```
      */
     verify: (data: string, expectedHash: string) => HaiResult<boolean>;
 }
 /**
- * 对称加密操作接口
+ * SM4 同步操作域；默认CBC与随机IV，返回完整结构化密文；CBC原语不提供完整性认证。
  *
- * 通过 `crypto.symmetric` 访问，需先调用 `crypto.init()`。
- * 默认使用 CBC 并自动生成 IV；密文以结构化字段返回。
+ * @example
+ * ```ts
+ * import { crypto, type SymmetricOperations } from '@h-ai/crypto'
+ * const initialized = await crypto.init()
+ * if (!initialized.success) throw new Error(initialized.error.message)
+ * try {
+ *   const operations: SymmetricOperations = crypto.symmetric
+ *   const key = operations.generateKey()
+ *   const encrypted = operations.encrypt('hello', key)
+ *   if (!encrypted.success) throw new Error(encrypted.error.message)
+ *   const decrypted = operations.decrypt(encrypted.data, key)
+ *   if (!decrypted.success) throw new Error(decrypted.error.message)
+ * }
+ * finally { await crypto.close() }
+ * ```
  */
 interface SymmetricOperations {
-    /** 生成随机密钥（16 字节 = 32 个十六进制字符） */
+    /**
+     * 生成随机密钥（16 字节 = 32 个十六进制字符）
+     * @returns 直接返回值，使用前先初始化模块。
+     *
+     * @example
+     * ```ts
+     * import { crypto } from '@h-ai/crypto'
+     * const initialized = await crypto.init()
+     * if (!initialized.success) throw new Error(initialized.error.message)
+     * try {
+     *   const key = crypto.symmetric.generateKey()
+     *   const valid = crypto.symmetric.isValidKey(key)
+     * }
+     * finally { await crypto.close() }
+     * ```
+     */
     generateKey: () => string;
-    /** 生成随机 IV（16 字节 = 32 个十六进制字符） */
+    /**
+     * 生成随机 IV（16 字节 = 32 个十六进制字符）
+     * @returns 直接返回值，使用前先初始化模块。
+     *
+     * @example
+     * ```ts
+     * import { crypto } from '@h-ai/crypto'
+     * const initialized = await crypto.init()
+     * if (!initialized.success) throw new Error(initialized.error.message)
+     * try {
+     *   const iv = crypto.symmetric.generateIV()
+     *   const valid = crypto.symmetric.isValidIV(iv)
+     * }
+     * finally { await crypto.close() }
+     * ```
+     */
     generateIV: () => string;
     /**
      * 对称加密
@@ -368,6 +1498,19 @@ interface SymmetricOperations {
      * @param key - 密钥（32 字符十六进制）
      * @param options - 加密模式/IV/输出格式
      * @returns 成功时返回结构化密文；失败时返回 INVALID_KEY/INVALID_IV/ENCRYPTION_FAILED
+     *
+     * @example
+     * ```ts
+     * import { crypto } from '@h-ai/crypto'
+     * const initialized = await crypto.init()
+     * if (!initialized.success) throw new Error(initialized.error.message)
+     * try {
+     *   const key = crypto.symmetric.generateKey()
+     *   const encrypted = crypto.symmetric.encrypt('hello', key)
+     *   if (!encrypted.success) throw new Error(encrypted.error.message)
+     * }
+     * finally { await crypto.close() }
+     * ```
      */
     encrypt: (data: string, key: string, options?: SymmetricEncryptOptions) => HaiResult<SymmetricEncryptedPayload>;
     /**
@@ -378,6 +1521,21 @@ interface SymmetricOperations {
      * @param payload - 结构化密文（包含 mode/ciphertext/iv/encoding）
      * @param key - 密钥（32 字符十六进制）
      * @returns 成功时返回明文；失败时返回 INVALID_KEY/INVALID_IV/DECRYPTION_FAILED
+     *
+     * @example
+     * ```ts
+     * import { crypto } from '@h-ai/crypto'
+     * const initialized = await crypto.init()
+     * if (!initialized.success) throw new Error(initialized.error.message)
+     * try {
+     *   const key = crypto.symmetric.generateKey()
+     *   const encrypted = crypto.symmetric.encrypt('hello', key)
+     *   if (!encrypted.success) throw new Error(encrypted.error.message)
+     *   const decrypted = crypto.symmetric.decrypt(encrypted.data, key)
+     *   if (!decrypted.success) throw new Error(decrypted.error.message)
+     * }
+     * finally { await crypto.close() }
+     * ```
      */
     decrypt: (payload: SymmetricDecryptInput, key: string) => HaiResult<string>;
     /**
@@ -385,43 +1543,103 @@ interface SymmetricOperations {
      *
      * @param data - 待加密明文
      * @param key - 密钥（32 字符十六进制）
-     * @returns 成功时返回 { ciphertext, iv }；失败时同 encrypt
+     * @returns 成功时返回完整 { mode, ciphertext, iv, encoding }；失败时同 encrypt
+     *
+     * @example
+     * ```ts
+     * import { crypto } from '@h-ai/crypto'
+     * const initialized = await crypto.init()
+     * if (!initialized.success) throw new Error(initialized.error.message)
+     * try {
+     *   const key = crypto.symmetric.generateKey()
+     *   const encrypted = crypto.symmetric.encryptWithIV('hello', key)
+     *   if (!encrypted.success) throw new Error(encrypted.error.message)
+     * }
+     * finally { await crypto.close() }
+     * ```
      */
     encryptWithIV: (data: string, key: string) => HaiResult<EncryptWithIVResult>;
     /**
      * 带 IV 解密（CBC 模式）
      *
+     * 不提供完整性认证。传输场景必须用 transport 先验签和验证 MAC，禁止直接对 HTTP 密文调用此 primitive。
+     *
      * @param ciphertext - 密文
      * @param key - 密钥
      * @param iv - 加密时使用的 IV
      * @returns 成功时返回明文；失败时同 decrypt
+     *
+     * @example
+     * ```ts
+     * import { crypto } from '@h-ai/crypto'
+     * const initialized = await crypto.init()
+     * if (!initialized.success) throw new Error(initialized.error.message)
+     * try {
+     *   const key = crypto.symmetric.generateKey()
+     *   const encrypted = crypto.symmetric.encryptWithIV('hello', key)
+     *   if (!encrypted.success) throw new Error(encrypted.error.message)
+     *   const decrypted = crypto.symmetric.decryptWithIV(encrypted.data.ciphertext, key, encrypted.data.iv)
+     *   if (!decrypted.success) throw new Error(decrypted.error.message)
+     * }
+     * finally { await crypto.close() }
+     * ```
      */
     decryptWithIV: (ciphertext: string, key: string, iv: string) => HaiResult<string>;
     /**
-     * 从密码和盐值派生密钥
-     *
-     * 内部仅执行单次哈希(password + salt) 取前 32 字符作为密钥。
-     *
-     * ⚠️ 安全警告：**此实现不是标准 KDF**，不具备密码爆破抗性。
-     * - 禁止用于密码存储（请用 `crypto.password.hash`）。
-     * - 禁止用于高价值密钥派生（请在应用层采用 PBKDF2 / scrypt / Argon2）。
+     * 校验密钥格式是否合法（32 字符十六进制）
+     * @param key - 本次操作的密钥，不记录到日志。
+     * @returns 直接boolean，false表示不匹配/未就绪。
      *
-     * @deprecated 未来版本可能移除。详见模块 README 安全声明。
-     * @param password - 密码
-     * @param salt - 盐值
-     * @returns 32 字符十六进制密钥
+     * @example
+     * ```ts
+     * import { crypto } from '@h-ai/crypto'
+     * const initialized = await crypto.init()
+     * if (!initialized.success) throw new Error(initialized.error.message)
+     * try {
+     *   const key = crypto.symmetric.generateKey()
+     *   const valid = crypto.symmetric.isValidKey(key)
+     * }
+     * finally { await crypto.close() }
+     * ```
      */
-    deriveKey: (password: string, salt: string) => string;
-    /** 校验密钥格式是否合法（32 字符十六进制） */
     isValidKey: (key: string) => boolean;
-    /** 校验 IV 格式是否合法（32 字符十六进制） */
+    /**
+     * 校验 IV 格式是否合法（32 字符十六进制）
+     * @param iv - 实际调用输入，按该方法约束验证。
+     * @returns 直接boolean，false表示不匹配/未就绪。
+     *
+     * @example
+     * ```ts
+     * import { crypto } from '@h-ai/crypto'
+     * const initialized = await crypto.init()
+     * if (!initialized.success) throw new Error(initialized.error.message)
+     * try {
+     *   const iv = crypto.symmetric.generateIV()
+     *   const valid = crypto.symmetric.isValidIV(iv)
+     * }
+     * finally { await crypto.close() }
+     * ```
+     */
     isValidIV: (iv: string) => boolean;
 }
 /**
- * 密码哈希操作接口
+ * 迭代加盐SM3密码存储操作；验证从 $hai$ 格式读取参数，返回成功false表示密码不匹配。
  *
- * 通过 `crypto.password` 访问，需先调用 `crypto.init()`。
- * 使用迭代加盐的方式生成密码哈希。
+ * @example
+ * ```ts
+ * import { crypto, type PasswordOperations } from '@h-ai/crypto'
+ * const initialized = await crypto.init()
+ * if (!initialized.success) throw new Error(initialized.error.message)
+ * try {
+ *   const operations: PasswordOperations = crypto.password
+ *   const hashed = operations.hash('test-password')
+ *   if (!hashed.success) throw new Error(hashed.error.message)
+ *   const verified = operations.verify('test-password', hashed.data)
+ *   if (!verified.success) throw new Error(verified.error.message)
+ *   const matches = verified.data
+ * }
+ * finally { await crypto.close() }
+ * ```
  */
 interface PasswordOperations {
     /**
@@ -432,6 +1650,18 @@ interface PasswordOperations {
      * @param password - 明文密码（不能为空）
      * @param config - 可选配置（盐值长度、迭代次数）
      * @returns 成功时返回格式化的哈希字符串；失败时返回 INVALID_INPUT 或 HASH_FAILED
+     *
+     * @example
+     * ```ts
+     * import { crypto } from '@h-ai/crypto'
+     * const initialized = await crypto.init()
+     * if (!initialized.success) throw new Error(initialized.error.message)
+     * try {
+     *   const hashed = crypto.password.hash('test-password', { iterations: 10000, saltLength: 16 })
+     *   if (!hashed.success) throw new Error(hashed.error.message)
+     * }
+     * finally { await crypto.close() }
+     * ```
      */
     hash: (password: string, config?: PasswordConfig) => HaiResult<string>;
     /**
@@ -442,61 +1672,86 @@ interface PasswordOperations {
      * @param password - 待验证的明文密码
      * @param hash - 存储的哈希值（格式: `$hai$<iterations>$<salt>$<hash>`）
      * @returns 成功时返回 boolean；失败时返回 INVALID_INPUT 或 VERIFY_FAILED
+     *
+     * @example
+     * ```ts
+     * import { crypto } from '@h-ai/crypto'
+     * const initialized = await crypto.init()
+     * if (!initialized.success) throw new Error(initialized.error.message)
+     * try {
+     *   const hashed = crypto.password.hash('test-password')
+     *   if (!hashed.success) throw new Error(hashed.error.message)
+     *   const verified = crypto.password.verify('test-password', hashed.data)
+     *   if (!verified.success) throw new Error(verified.error.message)
+     *   const matches = verified.data
+     * }
+     * finally { await crypto.close() }
+     * ```
      */
     verify: (password: string, hash: string) => HaiResult<boolean>;
 }
 /**
- * 传输加密操作接口（端到端混合加密）。
+ * 认证传输工厂；需先初始化crypto，服务端显式受管密钥环+共享registry，客户端通过TLS协商公钥。
+ * 协议v2绑定方向、HTTP方法/路径/状态、密钥版本和nonce，验签/MAC成功后才解密；防重放不替代业务幂等。
  *
- * 通过 `crypto.transport` 访问，需先调用 `crypto.init()`。
- *
- * @remarks
- * 使用流程（直接使用底层 transport 工厂时）：
- *
- * 1. 先 `await crypto.init()`，确保 `crypto.asymmetric` / `crypto.symmetric` 已就绪。
- * 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`。
- * 6. 服务端在业务逻辑前调用 `manager.decryptRequest()` 解密请求体，在返回前调用 `manager.encryptResponse(clientId, data)` 为当前客户端重新加密响应。
- * 7. 客户端收到 `X-Encrypted: true` 的响应后会自动解密；调用 `client.destroy()` 可清空当前会话，下次请求会重新协商。
- *
- * 常规应用优先使用上层封装，而不是手写 HTTP 协商细节：
- * - `serv.createApp({ transport: { crypto } })`
- * - `kit.createHandle({ crypto: { crypto, transport: true } })`
- * - `apiClient.init({ transport: { crypto } })`
- *
- * @example 服务端
- * ```ts
- * const result = crypto.transport.createServer({
- *   keyStore: createRedisTransportKeyStore({ cache, ttlSeconds: 3600 }),
- * })
- * if (!result.success) throw result.error
- * const manager = result.data
- * ```
- *
- * @example 客户端
+ * @example
  * ```ts
- * const client = crypto.transport.createClient({
- *   keyExchangeUrl: 'https://api.example.com/api/v1/_hai/key-exchange',
- * })
- * const resp = await client.encryptedFetch('https://api.example.com/api/v1/echo', {
- *   method: 'POST', body: JSON.stringify({ hello: 'world' }),
- * })
+ * import { crypto } from '@h-ai/crypto'
+ * const initialized = await crypto.init()
+ * if (!initialized.success) throw new Error(initialized.error.message)
+ * try {
+ *   const client = crypto.transport.createClient({ keyExchangeUrl: 'https://api.example.com/api/v1/_hai/key-exchange' })
+ *   try {
+ *     const ready = await client.init()
+ *     if (!ready.success) throw new Error(ready.error.message)
+ *     const response = await client.encryptedFetch('https://api.example.com/api/v1/orders')
+ *     if (!response.ok) throw new Error('HTTP request failed')
+ *   }
+ *   finally { client.destroy() }
+ * }
+ * finally { await crypto.close() }
  * ```
  */
 interface TransportOperations {
     /**
      * 创建服务端传输加密管理器。
      *
-     * options.keyStore：注入共享客户端公钥存储。
-     * options.maxClients：默认内存 keyStore 的最大客户端数（默认 10000，仅在未传 keyStore 时生效）。
-     * 成功返回 manager；密钥生成失败返回 `HaiCommonError.INTERNAL_ERROR`。
+     * serverKeyRing/keyStore 均必填；生产使用相同受管密钥环与共享 registry。
+     * 成功返回 manager；缺失、格式错误或公私钥错配返回脱敏 HaiResult 错误。
      *
      * @remarks
      * 通常在服务启动阶段创建一次，并交给 HTTP 中间件 / 路由处理器复用。
+     * @param options - 实际调用输入，按该方法约束验证。
+     * @returns HaiResult，先检查success再读取data。
+     *
+     * @example
+     * ```ts
+     * import { crypto, createRedisTransportKeyStore, parseTransportServerKeyRing } from '@h-ai/crypto'
+     * import { cache } from '@h-ai/cache'
+     * const initialized = await crypto.init()
+     * if (!initialized.success) throw new Error(initialized.error.message)
+     * try {
+     *   const connected = await cache.init({ type: 'redis', host: 'cache', port: 6379, password: process.env.HAI_CACHE_PASSWORD })
+     *   if (!connected.success) throw new Error(connected.error.message)
+     *   try {
+     *     const registry = createRedisTransportKeyStore({ cache, ttlSeconds: 3600 })
+     *     const ring = parseTransportServerKeyRing(process.env.HAI_CRYPTO_TRANSPORT_SERVERKEYRING)
+     *     if (!ring.success) throw new Error(ring.error.message)
+     *     const created = crypto.transport.createServer({ serverKeyRing: ring.data, keyStore: registry })
+     *     if (!created.success) throw new Error(created.error.message)
+     *     const manager = created.data
+     *     try {
+     *       const currentVersion = manager.getServerKeyId()
+     *       const publicKey = manager.getServerPublicKey()
+     *     }
+     *     finally { await manager.close() }
+     *   }
+     *   finally { await cache.close() }
+     * }
+     * finally { await crypto.close() }
+     * ```
      */
-    createServer: (options?: TransportCreateServerOptions) => HaiResult<TransportEncryptionManager>;
+    createServer: (options: TransportCreateServerOptions) => HaiResult<TransportEncryptionManager>;
     /**
      * 创建客户端传输加密会话。
      *
@@ -506,26 +1761,52 @@ interface TransportOperations {
      * @remarks
      * 返回的是“单会话”客户端：同一个实例会复用已协商得到的 `clientId` 与服务端公钥；
      * 调用 `destroy()` 后会回到未协商状态。
+     * @param options - 实际调用输入，按该方法约束验证。
+     * @param options.keyExchangeUrl - 密钥协商端点完整 URL。
+     * @param options.fetch - 实际发送 HTTP 请求的 fetch，默认 `globalThis.fetch`。
+     * @param options.maxPlaintextBytes - 可选本地明文 UTF-8 字节上限，默认跟随服务端。
+     * @returns 直接返回值，使用前先初始化模块。
+     *
+     * @example
+     * ```ts
+     * import { crypto } from '@h-ai/crypto'
+     * const initialized = await crypto.init()
+     * if (!initialized.success) throw new Error(initialized.error.message)
+     * try {
+     *   const client = crypto.transport.createClient({ keyExchangeUrl: 'https://api.example.com/api/v1/_hai/key-exchange' })
+     *   try {
+     *     const ready = await client.init()
+     *     if (!ready.success) throw new Error(ready.error.message)
+     *     const response = await client.encryptedFetch('https://api.example.com/api/v1/orders')
+     *     if (!response.ok) throw new Error('HTTP request failed')
+     *   }
+     *   finally { client.destroy() }
+     * }
+     * finally { await crypto.close() }
+     * ```
      */
     createClient: (options: {
         keyExchangeUrl: string;
         fetch?: typeof fetch;
+        maxPlaintextBytes?: number;
     }) => TransportClient;
     /** 协议常量（headers、密钥协商默认路径）。 */
     readonly protocol: typeof TRANSPORT_PROTOCOL;
 }
 /**
- * 加密模块函数接口
- *
- * `crypto` 服务对象的类型定义。使用前必须调用 `init()` 初始化。
+ * 加密模块服务接口；init检查HaiResult，close返回void，调用不能把原语当作已认证HTTP协议。
  *
  * @example
  * ```ts
  * import { crypto } from '@h-ai/crypto'
- *
- * await crypto.init()
- * const hash = crypto.hash.hash('hello')
- * await crypto.close()
+ * const initialized = await crypto.init()
+ * if (!initialized.success) throw new Error(initialized.error.message)
+ * try {
+ *   const digest = crypto.hash.hash('hello')
+ *   if (!digest.success) throw new Error(digest.error.message)
+ *   const value = digest.data
+ * }
+ * finally { await crypto.close() }
  * ```
  */
 interface CryptoFunctions {
@@ -536,12 +1817,30 @@ interface CryptoFunctions {
      * 重复调用会先关闭再重新初始化。
      *
      * @returns 成功时返回 ok(undefined)；失败时返回 INIT_FAILED
+     *
+     * @example
+     * ```ts
+     * import { crypto } from '@h-ai/crypto'
+     * const initialized = await crypto.init()
+     * if (!initialized.success) throw new Error(initialized.error.message)
+     * await crypto.close()
+     * ```
      */
     init: () => Promise<HaiResult<void>>;
     /**
      * 关闭加密模块，释放内部状态
      *
      * 关闭后再访问 asymmetric/hash/symmetric/password 会返回 NOT_INITIALIZED 错误。
+     * @returns 异步操作结果；存储或网络故障按方法契约拒绝。
+     *
+     * @example
+     * ```ts
+     * import { crypto } from '@h-ai/crypto'
+     * const initialized = await crypto.init()
+     * if (!initialized.success) throw new Error(initialized.error.message)
+     * await crypto.close()
+     * const ready = crypto.isInitialized
+     * ```
      */
     close: () => Promise<void>;
     /** 是否已初始化 */
@@ -566,38 +1865,169 @@ interface CryptoFunctions {
  */
 
 /**
- * 加密模块服务对象（统一入口）
- *
- * 使用前必须调用 `crypto.init()` 进行初始化。
- * 未初始化时访问 asymmetric/hash/symmetric/password 的任何方法均返回 NOT_INITIALIZED 错误。
+ * 加密模块公开服务对象；先检查 init 的 HaiResult，再使用各操作域，最后 close。
+ * SM2/SM3/SM4 原语不等于认证传输；HTTP 使用 transport 的签名、MAC、上下文和共享 nonce 校验。
  *
  * @example
  * ```ts
  * import { crypto } from '@h-ai/crypto'
- *
- * await crypto.init()
- * const hash = crypto.hash.hash('hello')
- * const keyPair = crypto.asymmetric.generateKeyPair()
- * await crypto.close()
+ * const initialized = await crypto.init()
+ * if (!initialized.success) throw new Error(initialized.error.message)
+ * try {
+ *   const generated = crypto.asymmetric.generateKeyPair()
+ *   if (!generated.success) throw new Error(generated.error.message)
+ *   const pair = generated.data
+ *   const digest = crypto.hash.hash('hello')
+ *   if (!digest.success) throw new Error(digest.error.message)
+ *   const publicKeyValid = crypto.asymmetric.isValidPublicKey(pair.publicKey)
+ * }
+ * finally { await crypto.close() }
  * ```
  */
 declare const crypto: CryptoFunctions;
 
+/**
+ * @h-ai/crypto — SM2 公钥输入校验。
+ * @module crypto-public-key
+ */
+/**
+ * 纯函数校验 SM2 公钥的编码及曲线点，不初始化模块或访问 registry。
+ * 仅接受128字符无前缀或130字符04前缀的十六进制非压缩点；拒绝曲线外点及其它编码。
+ * @param publicKey - 不可信的输入。
+ * @returns 有效字符串时为 true，并收窄类型；不证明密钥所有权，注册后仍须验签。
+ *
+ * @example
+ * ```ts
+ * import { crypto, isValidSM2PublicKey } from '@h-ai/crypto'
+ * const initialized = await crypto.init()
+ * if (!initialized.success) throw new Error(initialized.error.message)
+ * try {
+ *   const generated = crypto.asymmetric.generateKeyPair()
+ *   if (!generated.success) throw new Error(generated.error.message)
+ *   const pair = generated.data
+ *   const valid = isValidSM2PublicKey(pair.publicKey)
+ *   const invalid = isValidSM2PublicKey('not-a-public-key')
+ * }
+ * finally { await crypto.close() }
+ * ```
+ */
+declare function isValidSM2PublicKey(publicKey: unknown): publicKey is string;
+
+/** @h-ai/crypto — serv/kit 共用的安全传输错误响应。 */
+
+/**
+ * 已认证请求的时间窗口错误；只提供校时建议，不调整时钟或放宽防重放窗口。
+ * @example
+ * ```ts
+ * import { TransportTimeError } from '@h-ai/crypto'
+ * const error = new TransportTimeError()
+ * // 展示 error.message；同步设备/服务器时间后由用户刷新重试。
+ * ```
+ */
+declare class TransportTimeError extends Error {
+    readonly context?: TransportMessageContext | undefined;
+    readonly code: string | number;
+    constructor(context?: TransportMessageContext | undefined);
+}
+/**
+ * 创建脱敏传输错误；已验证绑定、签名和 MAC 的时间/响应容量错误继续加密，请求读取超限返回 HTTP 413。
+ * @param error - 容量或时间错误，不包含业务报文。
+ * @param authenticated - 仅在请求绑定、签名和 MAC 已验证后提供管理器和上下文。
+ * @param authenticated.manager - 使用原服务端预算的管理器。
+ * @param authenticated.context - 已验证请求绑定、签名和 MAC 的上下文；时间拒绝不会放行业务。
+ * @returns 可诊断的失败响应；加密失败仍只返回错误，不发送原业务响应。
+ * @example
+ * ```ts
+ * import { createTransportErrorResponse, TransportBodyTooLargeError } from '@h-ai/crypto'
+ * const response = await createTransportErrorResponse(new TransportBodyTooLargeError(1024, 1025))
+ * const status = response.status // 413
+ * ```
+ */
+declare function createTransportErrorResponse(error: TransportBodyTooLargeError | TransportTimeError, authenticated?: {
+    manager: TransportEncryptionManager;
+    context: TransportMessageContext;
+}): Promise<Response>;
+
+/**
+ * @h-ai/crypto — 服务端受管传输密钥环的安全解析。
+ * @module crypto-transport-keyring
+ */
+
+/**
+ * 解析服务端私有JSON或受管对象，不读取环境或初始化模块；实际密钥配对由createServer验证。
+ * @param serialized - Secret Manager提供的JSON字符串或对象。
+ * @returns 结构有效的密钥环或脱敏INVALID_KEY，不回显私钥/原始输入。
+ *
+ * @example
+ * ```ts
+ * import { parseTransportServerKeyRing, type TransportServerKeyRing } from '@h-ai/crypto'
+ * const parsed = parseTransportServerKeyRing(process.env.HAI_CRYPTO_TRANSPORT_SERVERKEYRING)
+ * if (!parsed.success) throw new Error(parsed.error.message)
+ * const ring: TransportServerKeyRing = parsed.data
+ * // 仅服务端使用；createServer还会校验每个版本的公私钥配对。
+ * ```
+ */
+declare function parseTransportServerKeyRing(serialized: unknown): HaiResult<TransportServerKeyRing>;
+
+/**
+ * @h-ai/crypto — serv/kit 共用的实际 HTTP 请求认证入口。
+ * @module crypto-transport-request
+ */
+
+/**
+ * 从实际HTTP请求提取可信方法/路径/查询/客户端ID并有界认证；成功后才执行业务。
+ * 拒绝缺少认证及头/正文重复承载，空请求也认证；不会由payload自证HTTP上下文。
+ * @param manager - 使用共享原子nonce registry的已创建管理器。
+ * @param request - 未消费正文的真实Request。
+ * @returns 明文和响应关联上下文；认证失败无明文。
+ * @throws RangeError超限；流读取/取消沿用原异常，HTTP适配器负责转响应。
+ *
+ * @example
+ * ```ts
+ * import { authenticateTransportRequest, TRANSPORT_PROTOCOL, type TransportEncryptionManager } from '@h-ai/crypto'
+ * async function handle(manager: TransportEncryptionManager, request: Request): Promise<Response> {
+ *   const verified = await authenticateTransportRequest(manager, request)
+ *   if (!verified.success) return new Response(null, { status: 400 })
+ *   const encrypted = await manager.encryptResponse(verified.data.context, JSON.stringify({ accepted: true }), 200)
+ *   if (!encrypted.success) return new Response(null, { status: 500 })
+ *   return Response.json(encrypted.data, { headers: { [TRANSPORT_PROTOCOL.ENCRYPTED_HEADER]: TRANSPORT_PROTOCOL.ENCRYPTED_HEADER_VALUE } })
+ * }
+ * ```
+ */
+declare function authenticateTransportRequest(manager: TransportEncryptionManager, request: Request): Promise<HaiResult<{
+    plaintext: string;
+    context: TransportMessageContext;
+}>>;
+
 /**
  * @h-ai/crypto — 传输加密内存 key store
  *
- * 提供默认的进程内客户端公钥存储实现。
+ * 提供显式开发/测试使用的进程内客户端公钥存储，生产使用共享 registry。
  * @module crypto-transport-store-memory
  */
 
 /**
- * 创建进程内 FIFO 客户端密钥存储。
- *
- * ⚠️ 进程内实现：多节点部署时需让客户端首次请求后保持「会话粘性」（sticky session），
- * 否则后续请求路由到其他节点会因找不到客户端公钥而失败。需要跨节点请改用
- * Redis / 数据库实现 {@link TransportKeyStore}。
+ * 显式创建开发/测试用进程内FIFO公钥registry；不跨进程、不持久化，生产共享状态守卫拒绝它。
+ * 有效nonce不会因公钥FIFO容量而提前逐出；过期nonce惰性清理。
+ * @param maxClients - 公钥容量，默认10000，超限淘汰最早公钥。
+ * @returns 本地registry；无效SM2公钥拒绝Promise。
  *
- * @param maxClients - 最大客户端数（默认 10000），超过后按注册顺序淘汰最早条目。
+ * @example
+ * ```ts
+ * import { crypto, createInMemoryKeyStore } from '@h-ai/crypto'
+ * const initialized = await crypto.init()
+ * if (!initialized.success) throw new Error(initialized.error.message)
+ * try {
+ *   const generated = crypto.asymmetric.generateKeyPair()
+ *   if (!generated.success) throw new Error(generated.error.message)
+ *   const pair = generated.data
+ *   const registry = createInMemoryKeyStore(100)
+ *   const clientId = await registry.register(pair.publicKey)
+ *   const saved = await registry.get(clientId)
+ *   await registry.delete?.(clientId)
+ * }
+ * finally { await crypto.close() }
+ * ```
  */
 declare function createInMemoryKeyStore(maxClients?: number): TransportKeyStore;
 
@@ -608,18 +2038,59 @@ declare function createInMemoryKeyStore(maxClients?: number): TransportKeyStore;
  * @module crypto-transport-store-redis
  */
 
-/** 创建 Redis 版传输 key store 的配置。 */
+/**
+ * 借用已初始化cache的registry配置；只有Redis provider报告shared，内存cache不能满足生产。
+ * TTL是客户端公钥寿命，nonce另按认证窗口持有；连接由应用关闭。
+ *
+ * @example
+ * ```ts
+ * import { crypto, createRedisTransportKeyStore, parseTransportServerKeyRing } from '@h-ai/crypto'
+ * import { cache } from '@h-ai/cache'
+ * const initialized = await crypto.init()
+ * if (!initialized.success) throw new Error(initialized.error.message)
+ * try {
+ *   const connected = await cache.init({ type: 'redis', host: 'cache', port: 6379, password: process.env.HAI_CACHE_PASSWORD })
+ *   if (!connected.success) throw new Error(connected.error.message)
+ *   try {
+ *     const registry = createRedisTransportKeyStore({ cache, ttlSeconds: 3600 })
+ *     const options: import('@h-ai/crypto').CreateRedisTransportKeyStoreOptions = { cache, ttlSeconds: 3600 }
+ *     const secondView = createRedisTransportKeyStore(options)
+ *     const scope = secondView.stateScope
+ *   }
+ *   finally { await cache.close() }
+ * }
+ * finally { await crypto.close() }
+ * ```
+ */
 interface CreateRedisTransportKeyStoreOptions {
     /** 已初始化的 `@h-ai/cache` 实例；生产环境通常应使用 Redis provider。 */
     readonly cache: CacheFunctions;
-    /** 客户端公钥的 TTL（秒）；未传则保持不过期。 */
+    /** 客户端公钥的 TTL（正整数秒，最大 2147483647）；未传则保持不过期。 */
     readonly ttlSeconds?: number;
 }
 /**
- * 创建基于 `@h-ai/cache` 的传输 key store。
+ * 创建借用cache的公钥/nonce registry；生产必须Redis共享provider，nonce用单key原子CAS。
+ * 公钥TTL省略则不过期，nonce有效期间禁止驱逐；容量由Redis部署预算管理，不提供DB maxClients。
+ * @param options - 已初始化cache与可选正整数TTL秒，最大2147483647。
+ * @returns registry；非法TTL同步TypeError，读写/公钥错误拒绝Promise，不关闭cache。
  *
- * 说明：本实现依赖 cache 模块的 KV 语义；若要获得跨节点共享能力，应传入
- * 已连接 Redis 的 `cache` 实例，而不是内存 provider。
+ * @example
+ * ```ts
+ * import { crypto, createRedisTransportKeyStore, parseTransportServerKeyRing } from '@h-ai/crypto'
+ * import { cache } from '@h-ai/cache'
+ * const initialized = await crypto.init()
+ * if (!initialized.success) throw new Error(initialized.error.message)
+ * try {
+ *   const connected = await cache.init({ type: 'redis', host: 'cache', port: 6379, password: process.env.HAI_CACHE_PASSWORD })
+ *   if (!connected.success) throw new Error(connected.error.message)
+ *   try {
+ *     const registry = createRedisTransportKeyStore({ cache, ttlSeconds: 3600 })
+ *     const scope = registry.stateScope
+ *   }
+ *   finally { await cache.close() }
+ * }
+ * finally { await crypto.close() }
+ * ```
  */
 declare function createRedisTransportKeyStore(options: CreateRedisTransportKeyStoreOptions): TransportKeyStore;
 
@@ -630,18 +2101,90 @@ declare function createRedisTransportKeyStore(options: CreateRedisTransportKeySt
  * @module crypto-transport-store-reldb
  */
 
-/** 创建关系数据库版传输 key store 的配置。 */
+/**
+ * 借用已初始化数据库的registry配置；TTL与共享maxClients各节点必须一致。
+ * 生产使用PostgreSQL/MySQL，DB时钟维护期限；连接由应用关闭。
+ *
+ * @example
+ * ```ts
+ * import { createReldbTransportKeyStore } from '@h-ai/crypto'
+ * import { reldb } from '@h-ai/reldb'
+ * const connected = await reldb.init({ type: 'postgresql', host: 'db', port: 5432, database: 'hai', user: 'postgres', password: process.env.HAI_DB_PASSWORD })
+ * if (!connected.success) throw new Error(connected.error.message)
+ * try {
+ *   const registry = createReldbTransportKeyStore({ reldb, ttlSeconds: 3600, maxClients: 10000 })
+ *   const options: import('@h-ai/crypto').CreateReldbTransportKeyStoreOptions = { reldb, ttlSeconds: 3600, maxClients: 10000 }
+ *   const secondView = createReldbTransportKeyStore(options)
+ *   const removed = await secondView.pruneExpired()
+ * }
+ * finally { await reldb.close() }
+ * ```
+ */
 interface CreateReldbTransportKeyStoreOptions {
     /** 已初始化的 `@h-ai/reldb` 实例。 */
     readonly reldb: ReldbFunctions;
-    /** 客户端公钥的 TTL（秒）；未传则保持不过期。 */
+    /** 公钥 TTL，正整数秒且最大 2147483647；省略则不过期。 */
     readonly ttlSeconds?: number;
+    /** 所有节点共享的有效公钥容量，正安全整数，默认 10000；各节点必须一致。 */
+    readonly maxClients?: number;
 }
 /**
- * 创建基于 `@h-ai/reldb` 的传输 key store。
+ * 数据库registry及有界过期维护；注册自动维护，无流量时应用应定期调度pruneExpired。
+ * 不淘汰有效公钥/nonce，不创建后台计时器；维护失败拒绝并可重试。
  *
- * 首次读写时会自动创建 `hai_crypto_transport_client_keys` 表。
+ * @example
+ * ```ts
+ * import { createReldbTransportKeyStore } from '@h-ai/crypto'
+ * import { reldb } from '@h-ai/reldb'
+ * const connected = await reldb.init({ type: 'postgresql', host: 'db', port: 5432, database: 'hai', user: 'postgres', password: process.env.HAI_DB_PASSWORD })
+ * if (!connected.success) throw new Error(connected.error.message)
+ * try {
+ *   const registry = createReldbTransportKeyStore({ reldb, ttlSeconds: 3600, maxClients: 10000 })
+ *   const removed = await registry.pruneExpired()
+ * }
+ * finally { await reldb.close() }
+ * ```
+ */
+interface ReldbTransportKeyStore extends TransportKeyStore {
+    /**
+     * 按数据库时钟最多删除 100 条过期公钥和 100 条过期 nonce，返回实际删除总数。
+     * 不驱逐有效记录；建表或维护故障会 reject，之后允许重新调用。应用可以定期调度本方法。
+     * @returns 异步操作结果；存储或网络故障按方法契约拒绝。
+     *
+     * @example
+     * ```ts
+     * import { createReldbTransportKeyStore } from '@h-ai/crypto'
+     * import { reldb } from '@h-ai/reldb'
+     * const connected = await reldb.init({ type: 'postgresql', host: 'db', port: 5432, database: 'hai', user: 'postgres', password: process.env.HAI_DB_PASSWORD })
+     * if (!connected.success) throw new Error(connected.error.message)
+     * try {
+     *   const registry = createReldbTransportKeyStore({ reldb, ttlSeconds: 3600, maxClients: 10000 })
+     *   const removed = await registry.pruneExpired()
+     * }
+     * finally { await reldb.close() }
+     * ```
+     */
+    pruneExpired: () => Promise<number>;
+}
+/**
+ * 创建共享数据库registry；首次操作惰性建表，失败可重试，事务锁住持久容量行后注册。
+ * 每次注册有界维护；公钥TTL与过期维护使用数据库epoch毫秒，传输窗口仍要求节点时钟同步，不能提前删除有效nonce。
+ * @param options - 已初始化数据库、公钥TTL和各节点一致的正安全整数maxClients，默认10000。
+ * @returns registry；非法配置同步TypeError，操作故障拒绝Promise；不关闭借用数据库。
+ *
+ * @example
+ * ```ts
+ * import { createReldbTransportKeyStore } from '@h-ai/crypto'
+ * import { reldb } from '@h-ai/reldb'
+ * const connected = await reldb.init({ type: 'postgresql', host: 'db', port: 5432, database: 'hai', user: 'postgres', password: process.env.HAI_DB_PASSWORD })
+ * if (!connected.success) throw new Error(connected.error.message)
+ * try {
+ *   const registry = createReldbTransportKeyStore({ reldb, ttlSeconds: 3600, maxClients: 10000 })
+ *   const removed = await registry.pruneExpired()
+ * }
+ * finally { await reldb.close() }
+ * ```
  */
-declare function createReldbTransportKeyStore(options: CreateReldbTransportKeyStoreOptions): TransportKeyStore;
+declare function createReldbTransportKeyStore(options: CreateReldbTransportKeyStoreOptions): ReldbTransportKeyStore;
 
-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 };
+export { type AsymmetricEncryptOptions, type AsymmetricOperations, type CipherMode, type CreateRedisTransportKeyStoreOptions, type CreateReldbTransportKeyStoreOptions, type CryptoFunctions, type EncryptWithIVResult, type EncryptedPayload, type EncryptedRequestPayload, HaiCryptoError, type HashOperations, type HashOptions, type KeyExchangeRequest, type KeyExchangeResponse, type KeyPair, type PasswordConfig, type PasswordOperations, type ReadTransportBodyOptions, type ReldbTransportKeyStore, type SignOptions, type SymmetricCbcEncryptedPayload, type SymmetricCiphertextEncoding, type SymmetricDecryptInput, type SymmetricEncryptOptions, type SymmetricEncryptedPayload, type SymmetricMode, type SymmetricOperations, TRANSPORT_BODY_LIMITS, TRANSPORT_PLAINTEXT_RANGE, TRANSPORT_PROTOCOL, type TransportBodyLimits, TransportBodyTooLargeError, type TransportClient, type TransportCreateServerOptions, type TransportCryptoServiceLike, type TransportEncryptionManager, type TransportKeyPair, type TransportKeyStore, type TransportMessageContext, type TransportOperations, type TransportRequestContext, type TransportServerKeyRing, TransportTimeError, authenticateTransportRequest, createInMemoryKeyStore, createRedisTransportKeyStore, createReldbTransportKeyStore, createTransportErrorResponse, crypto, isValidSM2PublicKey, parseTransportServerKeyRing, readTransportBody, resolveTransportBodyLimits };