@h-ai/crypto 0.1.0-alpha9 → 1.0.0-beta.1

package/dist/index.d.ts

@@ -1,6 +1,872 @@
 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 — 传输协议的字节预算与有界正文读取。
+ *
+ * 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，非字符串字符数限制。
+ *
+ * @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 的整数。
+ * @param options - 已启用模块所需的最小明文预算；只在宿主未显式设置上限时自动推导。
+ * @param options.requiredPlaintextBytes - 模块需要的最小 UTF-8 明文字节数，仍受 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, options?: {
+    requiredPlaintextBytes?: 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>;
+/**
+ * 为真实 HTTP 适配器分离业务与大附件容量；* 只匹配一个完整路径段。
+ * 单独声明且超过 1 MiB 的材料路由最多两个，普通业务最多十六个，租约须在响应完成或失败时释放。
+ * @param maxPlaintextBytes - 普通业务容量；省略使用 1 MiB。
+ * @param routes - 受信任的绝对路径到 UTF-8 容量映射，最多 100 条。
+ * @returns 协商最大容量及每请求的限额和可释放并发准入。
+ * @throws RangeError 配置路径、数量或容量无效。
+ * @example
+ * ```ts
+ * import { createTransportBodyPolicy } from '@h-ai/crypto'
+ * const policy = createTransportBodyPolicy(undefined, { '/api/files/*': 8 * 1024 * 1024 })
+ * const lease = policy.acquire('/api/files/attachment')
+ * try { if (lease) lease.limits.plaintextBytes }
+ * finally { lease?.release() }
+ * ```
+ */
+declare function createTransportBodyPolicy(maxPlaintextBytes?: number, routes?: Readonly<Record<string, number>>): {
+    maximum: TransportBodyLimits;
+    acquire(pathname: string): {
+        limits: TransportBodyLimits;
+        release(): void;
+    } | null;
+};
+
+/**
+ * 认证传输v2的头名、窗口与默认协商子路径；各HTTP适配器共用，不手写漂移常量。
+ *
+ * @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` 响应头的开启值。 */
+    readonly ENCRYPTED_HEADER_VALUE: "true";
+    /** 密钥协商端点的默认子路径（相对于挂载前缀）。 */
+    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适配器只用成功认证得到的上下文生成响应，不自行拼接示例密文。
+ *
+ * @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；结构类型不构成认证证明。
+ *
+ * @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;
+        encryptWithIV: (data: string, key: string) => HaiResult<{
+            ciphertext: string;
+            iv: string;
+        }>;
+        decryptWithIV: (ciphertext: string, key: string, iv: string) => HaiResult<string>;
+    };
+}
+/**
+ * 客户端公钥与nonce存储契约；生产显式共享Redis/数据库，真实共享与原子性由提供者保证。
+ * get的故障不能当未注册，claimRequest故障不能当成功；有效nonce不得在expiresAt前驱逐。
+ *
+ * @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 {
+    /** 公钥与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均必填，没有进程随机密钥回退。
+ *
+ * @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 {
+    /** 双向业务明文 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。
+ *
+ * @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>;
+    /**
+     * 按已认证请求上下文加密、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。
+ *
+ * @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;
@@ -14,56 +880,304 @@ 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;
+    readonly TRANSPORT_BUSY: _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';
-/** 对称加密选项 */
-interface SymmetricOptions {
-    /** 加密模式 */
+/**
+ * 结构化 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';
+/**
+ * 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;
-    /** IV 向量（CBC 模式必需，32 个十六进制字符） */
+    /** IV 向量（CBC 模式可选；未传时自动生成，32 个十六进制字符） */
     iv?: string;
-    /** 输入编码 */
-    inputEncoding?: 'utf8' | 'hex';
-    /** 输出格式 */
-    outputFormat?: 'hex' | 'base64';
+    /** 密文输出编码；默认 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;
+    /** 密文内容，编码由 encoding 字段说明 */
+    readonly ciphertext: string;
+    /** CBC 模式的 IV 向量；ECB 模式无该字段 */
+    readonly iv?: string;
+    /** ciphertext 字段的编码 */
+    readonly encoding: SymmetricCiphertextEncoding;
 }
-/** 带 IV 加密结果 */
-interface EncryptWithIVResult {
-    /** 密文 */
-    ciphertext: string;
-    /** IV 向量 */
-    iv: string;
+/**
+ * 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;
+/**
+ * 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;
@@ -71,15 +1185,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>;
     /**
@@ -89,6 +1235,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>;
     /**
@@ -100,6 +1261,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>;
     /**
@@ -109,6 +1287,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>;
     /**
@@ -119,25 +1312,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 {
     /**
@@ -146,6 +1398,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>;
     /**
@@ -157,6 +1421,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>;
     /**
@@ -167,78 +1444,230 @@ 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()`。
- * 支持 ECB/CBC 两种模式，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;
     /**
      * 对称加密
      *
+     * 默认 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
+     *
+     * @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?: 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
+     *
+     * @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: (ciphertext: string, key: string, options?: SymmetricOptions) => HaiResult<string>;
+    decrypt: (payload: SymmetricDecryptInput, key: string) => HaiResult<string>;
     /**
      * 带 IV 加密（CBC 模式，自动生成随机 IV）
      *
      * @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>;
     /**
-     * 从密码和盐值派生密钥
+     * 校验密钥格式是否合法（32 字符十六进制）
+     * @param key - 本次操作的密钥，不记录到日志。
+     * @returns 直接boolean，false表示不匹配/未就绪。
      *
-     * 内部使用哈希(password + salt) 取前 32 字符作为密钥。
-     * 注意：此为简单派生，不适用于高安全场景。
-     *
-     * @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 {
     /**
@@ -249,6 +1678,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>;
     /**
@@ -259,21 +1700,141 @@ 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` 服务对象的类型定义。使用前必须调用 `init()` 初始化。
+ * 认证传输工厂；需先初始化crypto，服务端显式受管密钥环+共享registry，客户端通过TLS协商公钥。
+ * 协议v2绑定方向、HTTP方法/路径/状态、密钥版本和nonce，验签/MAC成功后才解密；防重放不替代业务幂等。
  *
  * @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 TransportOperations {
+    /**
+     * 创建服务端传输加密管理器。
+     *
+     * 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>;
+    /**
+     * 创建客户端传输加密会话。
+     *
+     * options.keyExchangeUrl：密钥协商端点完整 URL。
+     * options.fetch：实际发送 HTTP 请求的 fetch（默认 `globalThis.fetch`）。
+     *
+     * @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;
+}
+/**
+ * 加密模块服务接口；init检查HaiResult，close返回void，调用不能把原语当作已认证HTTP协议。
  *
- * await crypto.init()
- * const hash = crypto.hash.hash('hello')
- * await crypto.close()
+ * @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 value = digest.data
+ * }
+ * finally { await crypto.close() }
  * ```
  */
 interface CryptoFunctions {
@@ -284,12 +1845,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>;
     /** 是否已初始化 */
@@ -302,6 +1881,8 @@ interface CryptoFunctions {
     readonly symmetric: SymmetricOperations;
     /** 密码哈希操作（未初始化时所有方法返回 NOT_INITIALIZED） */
     readonly password: PasswordOperations;
+    /** 传输加密操作（端到端混合加密；createServer 在未初始化时返回 NOT_INITIALIZED） */
+    readonly transport: TransportOperations;
 }
 
 /**
@@ -312,21 +1893,322 @@ 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;
 
-export { type AsymmetricEncryptOptions, type AsymmetricOperations, type CipherMode, type CryptoFunctions, type EncryptWithIVResult, HaiCryptoError, type HashOperations, type HashOptions, type KeyPair, type PasswordConfig, type PasswordOperations, type SignOptions, type SymmetricMode, type SymmetricOperations, type SymmetricOptions, crypto };
+/**
+ * @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>;
+
+/**
+ * 从实际HTTP请求提取可信方法/路径/查询/客户端ID并有界认证；成功后才执行业务。
+ * 拒绝缺少认证及头/正文重复承载，空请求也认证；不会由payload自证HTTP上下文。
+ * @param manager - 使用共享原子nonce registry的已创建管理器。
+ * @param request - 未消费正文的真实Request。
+ * @param limits - HTTP 路由容量；默认管理器协商容量。
+ * @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, limits?: TransportBodyLimits): Promise<HaiResult<{
+    plaintext: string;
+    context: TransportMessageContext;
+}>>;
+
+/**
+ * @h-ai/crypto — 传输加密内存 key store
+ *
+ * 提供显式开发/测试使用的进程内客户端公钥存储，生产使用共享 registry。
+ * @module crypto-transport-store-memory
+ */
+
+/**
+ * 显式创建开发/测试用进程内FIFO公钥registry；不跨进程、不持久化，生产共享状态守卫拒绝它。
+ * 有效nonce不会因公钥FIFO容量而提前逐出；过期nonce惰性清理。
+ * @param maxClients - 公钥容量，默认10000，超限淘汰最早公钥。
+ * @returns 本地registry；无效SM2公钥拒绝Promise。
+ *
+ * @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;
+
+/**
+ * @h-ai/crypto — 传输加密 Redis key store
+ *
+ * 通过 `@h-ai/cache` 持久化客户端公钥；通常应传入已初始化为 Redis 的 `cache` 实例。
+ * @module crypto-transport-store-redis
+ */
+
+/**
+ * 借用已初始化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（正整数秒，最大 2147483647）；未传则保持不过期。 */
+    readonly ttlSeconds?: number;
+}
+/**
+ * 创建借用cache的公钥/nonce registry；生产必须Redis共享provider，nonce用单key原子CAS。
+ * 公钥TTL省略则不过期，nonce有效期间禁止驱逐；容量由Redis部署预算管理，不提供DB maxClients。
+ * @param options - 已初始化cache与可选正整数TTL秒，最大2147483647。
+ * @returns registry；非法TTL同步TypeError，读写/公钥错误拒绝Promise，不关闭cache。
+ *
+ * @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;
+
+/**
+ * @h-ai/crypto — 传输加密关系数据库 key store
+ *
+ * 通过 `@h-ai/reldb` 保存客户端公钥，适用于需要跨节点共享状态的服务端部署。
+ * @module crypto-transport-store-reldb
+ */
+
+/**
+ * 借用已初始化数据库的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，正整数秒且最大 2147483647；省略则不过期。 */
+    readonly ttlSeconds?: number;
+    /** 所有节点共享的有效公钥容量，正安全整数，默认 10000；各节点必须一致。 */
+    readonly maxClients?: number;
+}
+/**
+ * 数据库registry及有界过期维护；注册自动维护，无流量时应用应定期调度pruneExpired。
+ * 不淘汰有效公钥/nonce，不创建后台计时器；维护失败拒绝并可重试。
+ *
+ * @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): ReldbTransportKeyStore;
+
+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, createTransportBodyPolicy, createTransportErrorResponse, crypto, isValidSM2PublicKey, parseTransportServerKeyRing, readTransportBody, resolveTransportBodyLimits };