secure-crypto-top-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Atengliyun
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,238 @@
+# 🔐 secure-crypto-top-sdk
+
+> **可插拔多算法 + 多协议(自定义 / TOP 风格)端到端加密 SDK**
+> AES-GCM/CBC · SM4 · SM3 · HMAC · RSA-OAEP 混合加密 · Fastify 集成
+
+[![npm version](https://img.shields.io/npm/v/secure-crypto-top-sdk.svg)](https://www.npmjs.com/package/secure-crypto-top-sdk)
+[![license](https://img.shields.io/npm/l/secure-crypto-top-sdk.svg)](./LICENSE)
+
+## ✨ 特性
+
+| 能力 | 说明 |
+|---|---|
+| **多算法可插拔** | `aes-256-gcm`、`aes-256-cbc`、`aes-128-cbc`、`sm4-cbc`、`rsa-oaep-aes-256-gcm` |
+| **多签名算法** | `hmac-sha256`、`hmac-sha512`、`md5`、`sha256`、`sm3` |
+| **多协议并存** | `custom`(自家信封) + `top`(TOP 风格,白名单排序 + biz_content 整体加密) |
+| **多 App 注册** | 一个服务端可托管多个 app,每个 app 独立密钥 / 独立算法白名单 |
+| **混合加密** | RSA-OAEP 包装 AES-256-GCM 临时密钥 → 前向安全 |
+| **Fastify 插件** | 一行 `app.register(...)` 启用端到端加密网关 |
+| **浏览器 SDK** | 同一份协议,浏览器 / Node / Fastify 互通 |
+| **零外部依赖** | 算法层全部纯 Node `crypto` / 纯 JS(SM3、SM4)实现,体积小 |
+
+## 📦 安装
+
+```bash
+npm install secure-crypto-top-sdk
+# 或
+pnpm add secure-crypto-top-sdk
+```
+
+## 🚀 快速开始
+
+### 1. Node.js 端:多协议 / 多算法(独立工具)
+
+```ts
+import { buildProtocolRequest, parseAndVerifyProtocol, buildProtocolResponse } from 'secure-crypto-top-sdk';
+
+const apps = [{ appKey: 'demo-app', appSecret: 'my-secret-1234567890' }];
+
+// 客户端构造请求(TOP 协议 + AES-256-GCM + HMAC-SHA256)
+const env = await buildProtocolRequest(
+  {
+    method: 'POST',
+    path: 'user.login',
+    biz: { username: 'alice', password: 'p@ss' },
+    cipher: 'aes-256-gcm',
+    digest: 'hmac-sha256',
+  },
+  {
+    appKey: 'demo-app',
+    appSecret: 'my-secret-1234567890',
+    encryptionKey: Buffer.alloc(32, 1),   // 32 字节对称密钥
+    hmacSecret: 'my-secret-1234567890',
+  }
+);
+
+// 服务端解析 + 验签
+const verified = await parseAndVerifyProtocol(env, { apps });
+console.log(verified.biz); // { username: 'alice', password: 'p@ss' }
+```
+
+切换到 **国密 SM4 + SM3**:
+
+```ts
+const env = await buildProtocolRequest(
+  { method: 'POST', path: 'user.pay', biz: { orderId: 'O1' }, cipher: 'sm4-cbc', digest: 'sm3' },
+  { appKey: 'demo-app', appSecret: 'my-secret', encryptionKey: Buffer.alloc(16, 1), hmacSecret: 'my-secret' }
+);
+```
+
+切换到 **custom 协议**(兼容老 secure-crypto-sdk):
+
+```ts
+const env = await buildProtocolRequest(
+  { method: 'POST', path: '/api/v1/echo', body: { foo: 'bar' }, protocol: 'custom' },
+  { appKey: 'demo-app', appSecret: 'my-secret', encryptionKey: Buffer.alloc(32, 1), hmacSecret: 'my-secret' }
+);
+```
+
+### 2. Fastify 网关(推荐)
+
+```ts
+import Fastify from 'fastify';
+import secureCryptoPlugin from 'secure-crypto-top-sdk/server';
+
+const app = Fastify({ logger: true });
+
+await app.register(secureCryptoPlugin, {
+  apps: [
+    {
+      appKey: 'demo-app',
+      appSecret: 'demo-secret-1234567890',
+      allowedCiphers: ['aes-256-gcm', 'sm4-cbc'],   // 限制可用加密算法
+      allowedDigests: ['hmac-sha256', 'sm3'],        // 限制可用签名算法
+    },
+    {
+      appKey: 'legacy',
+      appSecret: 'legacy-secret',
+      allowedCiphers: ['aes-256-cbc'],               // 老接口:仅 CBC
+      allowedDigests: ['md5'],
+    },
+  ],
+  defaultProtocol: 'top',
+  bypassPaths: ['/health', '/docs'],
+  // redis: redisClient,                            // 可选:nonce 防重放
+});
+
+app.post('/api/v1/top/login', async (req) => {
+  // 业务 handler 里直接读明文
+  const { username, password } = req.body as any;
+  // ...
+  return { success: true, userId: 1 };
+});
+```
+
+### 3. 浏览器端
+
+```ts
+import { SecureClient } from 'secure-crypto-top-sdk/client';
+
+const client = new SecureClient({
+  baseURL: 'https://api.example.com',
+  encryptionKey: 'a1b2c3...64字符hex',     // 32 字节 hex
+  hmacSecret: 'my-hmac-secret-1234567890', // >= 32 字符
+  appKey: 'demo-app',
+  protocol: 'top',                          // 默认 'top'
+  cipher: 'aes-256-gcm',
+  digest: 'hmac-sha256',
+});
+
+const data = await client.post('/api/v1/top/login', { username: 'alice', password: 'p@ss' });
+```
+
+## 🔄 协议格式
+
+### TOP 风格(默认)
+
+```jsonc
+{
+  "protocol": "top",
+  "method": "user.login",                // API 名
+  "app_key": "demo-app",
+  "timestamp": 1718000000000,
+  "v": "2.0",
+  "sign_method": "hmac-sha256",          // 或 sm3 / hmac-sha512
+  "cipher": "aes-256-gcm",                // 或 aes-256-cbc / sm4-cbc
+  "biz_content": "<base64密文>",          // 业务参数整体加密后 base64
+  "iv": "<base64>",
+  "authTag": "<base64>",                  // GCM 才有
+  "sign": "<hex 签名>"
+}
+```
+
+**签名拼接规则:**
+
+```
+signSource = sortedBizParams(biz + systemParams) + appSecret + biz_content
+sign       = digest(signSource, appSecret)
+```
+
+> 不同厂商的"加 secret"位置(头/尾/不参与)略有差异,可修改 `src/protocol/top/signer.ts` 适配。
+
+### Custom 风格(兼容旧 SDK)
+
+```jsonc
+{
+  "protocol": "custom",
+  "encryptedPayload": "<base64 整包密文>", // 加密 {path, method, body, query}
+  "iv": "<base64>",
+  "authTag": "<base64>",
+  "signature": "<hex>",
+  "timestamp": 1718000000000,
+  "nonce": "<uuid>"
+}
+```
+
+签名:`timestamp + nonce + encrypted + iv + authTag`
+
+## 🔌 扩展新算法
+
+```ts
+// 1. 实现 Cipher 接口
+import type { Cipher, CipherMeta } from 'secure-crypto-top-sdk';
+
+const meta: CipherMeta = { name: 'chacha20-poly1305', keyLength: 32, ivLength: 12, hasAuthTag: true, blockSize: 1 };
+const myCipher: Cipher = { name: 'chacha20-poly1305', meta, /* ... */ };
+
+// 2. 注册
+import { cipherRegistry } from 'secure-crypto-top-sdk';
+cipherRegistry.set('chacha20-poly1305', myCipher);
+```
+
+## 🧪 测试
+
+```bash
+pnpm test               # vitest
+pnpm demo:server        # 启动 demo 服务
+```
+
+## 📁 目录结构
+
+```
+secure-crypto-top-sdk/
+├── src/
+│   ├── algorithms/
+│   │   ├── cipher/          # AES-GCM/CBC、SM4、RSA-OAEP 混合
+│   │   ├── digest/          # HMAC、MD5/SHA、SM3
+│   │   ├── registry.ts      # 算法注册表
+│   │   └── types.ts
+│   ├── protocol/
+│   │   ├── custom/          # 自家协议
+│   │   ├── top/             # TOP 风格协议
+│   │   ├── base.ts          # ProtocolStrategy 接口
+│   │   └── registry.ts
+│   ├── config/              # AppRegistry / KeyStore
+│   ├── client/              # 浏览器 SecureClient
+│   ├── server/              # Fastify 插件 + 独立工具
+│   ├── types/
+│   ├── errors/
+│   └── index.ts
+├── demo/                    # demo-server.ts / demo-client.ts
+├── tests/                   # vitest
+├── package.json
+├── tsconfig.json
+└── tsup.config.ts
+```
+
+## 🔒 安全建议
+
+1. **生产环境**:`KeyStore.setHex` 显式注入密钥,**不要**用 `deriveFromApp`(它从 appSecret 派生对称密钥,弱于独立密钥)。
+2. **MD5 / SHA-256 摘要**:仅用于兼容老接口,默认应在 `allowedDigests` 中显式开启。
+3. **CBC 模式**:每次加密必须用新随机 IV(SDK 内已自动处理)。
+4. **混合加密**:用 `rsa-oaep-aes-256-gcm`,每次请求 AES key 临时生成,提供前向安全。
+5. **重放防护**:传 `redis` 给 Fastify 插件,启用 nonce 校验。
+6. **时间窗口**:默认 5 分钟,生产建议 ≤ 60 秒。
+
+## 📄 License
+
+MIT © 2026 Atengliyun

package/dist/base-v1-7dHNy.d.mts

@@ -0,0 +1,183 @@
+/**
+ * 算法可插拔层 - 公共类型定义
+ */
+/** 支持的加密算法(可按需扩展) */
+type CipherAlgorithm = 'aes-256-gcm' | 'aes-256-cbc' | 'aes-128-cbc' | 'sm4-cbc' | 'rsa-oaep-aes-256-gcm';
+/** 支持的摘要/签名算法 */
+type DigestAlgorithm = 'hmac-sha256' | 'hmac-sha512' | 'md5' | 'sha256' | 'sm3';
+/** 加密算法元信息 */
+interface CipherMeta {
+    name: CipherAlgorithm;
+    /** 密钥字节长度(对混合加密而言,指的是"对称密钥"长度) */
+    keyLength: number;
+    /** IV 字节长度,0 表示 IV 由算法内部生成/不需要 */
+    ivLength: number;
+    /** 是否有 authTag(GCM 模式) */
+    hasAuthTag: boolean;
+    /** 块大小(分组密码;流密码为 1) */
+    blockSize: number;
+}
+/** 摘要算法元信息 */
+interface DigestMeta {
+    name: DigestAlgorithm;
+    /** 输出字节长度 */
+    outputLength: number;
+    /** 是否需要密钥(hmac 系列) */
+    keyed: boolean;
+    /** 建议的最小密钥长度 */
+    minKeyLength: number;
+}
+interface EncryptResult {
+    /** 密文 */
+    data: Buffer;
+    /** IV(明文传输,可能由算法内部生成) */
+    iv: Buffer;
+    /** authTag(仅 GCM 等 AEAD 模式) */
+    tag?: Buffer;
+    /** 对于混合加密(rsa-oaep-aes-256-gcm),这里放加密后的对称密钥 */
+    encryptedKey?: Buffer;
+}
+interface EncryptParams {
+    /** 关联数据(AEAD) */
+    aad?: Buffer;
+    /** 调用方传入的对称密钥(必填,除非混合加密 + 走 RSA 派生) */
+    key?: Buffer;
+    /** 接收方 RSA 公钥(混合加密场景) */
+    rsaPublicKeyPem?: string;
+    /** 直接传入 IV(可选,默认内部随机生成) */
+    iv?: Buffer;
+}
+interface DecryptParams {
+    aad?: Buffer;
+    /** RSA 私钥 PEM(混合加密场景) */
+    rsaPrivateKeyPem?: string;
+    /** 对称密钥(必填,除非混合加密 + 走 RSA 私钥派生) */
+    key?: Buffer;
+    /** IV(必填) */
+    iv: Buffer;
+    /** GCM authTag */
+    tag?: Buffer;
+    /** 混合加密时,RSA 加密的对称密钥 */
+    encryptedKey?: Buffer;
+}
+/** 一个加密算法的统一接口 */
+interface Cipher {
+    readonly name: CipherAlgorithm;
+    readonly meta: CipherMeta;
+    /** 生成新的对称密钥(返回 Buffer) */
+    generateKey?(): Buffer;
+    /** 生成随机 IV */
+    generateIv(): Buffer;
+    encrypt(plain: Buffer, params?: EncryptParams): EncryptResult;
+    decrypt(cipher: Buffer, params: DecryptParams): Buffer;
+}
+interface Digest {
+    readonly name: DigestAlgorithm;
+    readonly meta: DigestMeta;
+    /** 计算摘要/签名,默认输出 hex */
+    sign(data: string | Buffer, key?: string | Buffer): string;
+    /** 校验摘要/签名 */
+    verify(sig: string, data: string | Buffer, key?: string | Buffer): boolean;
+}
+
+/**
+ * 全局类型定义:算法枚举、协议枚举、App 配置等
+ */
+
+/** 一个接入应用(app) 的服务端配置 */
+interface AppConfig {
+    /** 应用唯一标识 */
+    appKey: string;
+    /** 应用密钥(用于服务端校验签名 / 解密 biz_content) */
+    appSecret: string;
+    /** 是否启用 */
+    enabled?: boolean;
+    /** 允许的加密算法白名单,留空表示允许所有已注册算法 */
+    allowedCiphers?: CipherAlgorithm[];
+    /** 允许的摘要/签名算法白名单,留空表示允许所有 */
+    allowedDigests?: DigestAlgorithm[];
+    /** 允许的协议,留空表示所有已注册协议 */
+    allowedProtocols?: ProtocolKind[];
+    /** 自定义属性 */
+    metadata?: Record<string, unknown>;
+}
+/** ServerContext:服务端钩子里使用的上下文 */
+interface ServerContext {
+    app: AppConfig;
+    cipher: CipherAlgorithm;
+    digest: DigestAlgorithm;
+    protocol: ProtocolKind;
+}
+interface NonceStore {
+    set(key: string, value: string, ...args: any[]): Promise<any>;
+}
+
+type ProtocolKind = 'custom' | 'top';
+/** 协议策略的统一接口 */
+interface ProtocolStrategy {
+    readonly kind: ProtocolKind;
+    /**
+     * 客户端:组装请求信封
+     * @param input 业务参数 + 加密/签名算法
+     * @param ctx   客户端上下文(密钥等)
+     */
+    buildRequest(input: ProtocolRequestInput, ctx: ProtocolClientContext): Promise<Record<string, unknown>>;
+    /**
+     * 服务端:从原始 body 中解析、验签、解密
+     * 返回解出来的业务参数,挂到 req.secureRequest
+     */
+    parseAndVerify(raw: Record<string, unknown>, ctx: ProtocolServerContext): Promise<ProtocolVerifyResult>;
+    /**
+     * 服务端:把响应加密成信封
+     */
+    buildResponse(biz: unknown, ctx: ProtocolServerContext): Promise<Record<string, unknown>>;
+}
+interface ProtocolClientContext {
+    appKey: string;
+    appSecret: string;
+    /** 加密密钥 Buffer(对混合加密,rsaPublicKeyPem 走 params) */
+    encryptionKey: Buffer;
+    /** HMAC/签名密钥(hex 字符串) */
+    hmacSecret: string;
+    /** RSA 公钥 PEM(混合加密场景) */
+    rsaPublicKeyPem?: string;
+}
+interface ProtocolServerContext {
+    app: AppConfig;
+    encryptionKey: Buffer;
+    hmacSecret: string;
+    rsaPrivateKeyPem?: string;
+    nonceStore?: NonceStore;
+    requestWindowMs: number;
+}
+interface ProtocolRequestInput {
+    /** HTTP method */
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+    /** API 路径(/api/v1/...) */
+    path: string;
+    /** 业务参数(会被序列化到 envelope) */
+    biz: Record<string, unknown>;
+    /** 业务 body(可选) */
+    body?: unknown;
+    /** 用户 session(可选,TOP 协议需要) */
+    session?: string;
+    /** 业务 query */
+    query?: Record<string, string>;
+    /** 算法协商(可选,默认走客户端 / app 配置) */
+    cipher?: CipherAlgorithm;
+    digest?: DigestAlgorithm;
+    /** 协议类型(custom | top) */
+    protocol?: ProtocolKind;
+}
+interface ProtocolVerifyResult {
+    appKey: string;
+    method: string;
+    path: string;
+    body?: unknown;
+    query?: Record<string, string>;
+    session?: string;
+    /** 解析出来的子协议字段(TOP: biz_content 解密结果;custom: 整个载荷) */
+    biz: unknown;
+}
+
+export type { AppConfig as A, CipherAlgorithm as C, DigestAlgorithm as D, EncryptParams as E, NonceStore as N, ProtocolKind as P, ServerContext as S, Cipher as a, Digest as b, ProtocolStrategy as c, ProtocolRequestInput as d, ProtocolVerifyResult as e, CipherMeta as f, DecryptParams as g, DigestMeta as h, EncryptResult as i, ProtocolClientContext as j, ProtocolServerContext as k };

package/dist/base-v1-7dHNy.d.ts

@@ -0,0 +1,183 @@
+/**
+ * 算法可插拔层 - 公共类型定义
+ */
+/** 支持的加密算法(可按需扩展) */
+type CipherAlgorithm = 'aes-256-gcm' | 'aes-256-cbc' | 'aes-128-cbc' | 'sm4-cbc' | 'rsa-oaep-aes-256-gcm';
+/** 支持的摘要/签名算法 */
+type DigestAlgorithm = 'hmac-sha256' | 'hmac-sha512' | 'md5' | 'sha256' | 'sm3';
+/** 加密算法元信息 */
+interface CipherMeta {
+    name: CipherAlgorithm;
+    /** 密钥字节长度(对混合加密而言,指的是"对称密钥"长度) */
+    keyLength: number;
+    /** IV 字节长度,0 表示 IV 由算法内部生成/不需要 */
+    ivLength: number;
+    /** 是否有 authTag(GCM 模式) */
+    hasAuthTag: boolean;
+    /** 块大小(分组密码;流密码为 1) */
+    blockSize: number;
+}
+/** 摘要算法元信息 */
+interface DigestMeta {
+    name: DigestAlgorithm;
+    /** 输出字节长度 */
+    outputLength: number;
+    /** 是否需要密钥(hmac 系列) */
+    keyed: boolean;
+    /** 建议的最小密钥长度 */
+    minKeyLength: number;
+}
+interface EncryptResult {
+    /** 密文 */
+    data: Buffer;
+    /** IV(明文传输,可能由算法内部生成) */
+    iv: Buffer;
+    /** authTag(仅 GCM 等 AEAD 模式) */
+    tag?: Buffer;
+    /** 对于混合加密(rsa-oaep-aes-256-gcm),这里放加密后的对称密钥 */
+    encryptedKey?: Buffer;
+}
+interface EncryptParams {
+    /** 关联数据(AEAD) */
+    aad?: Buffer;
+    /** 调用方传入的对称密钥(必填,除非混合加密 + 走 RSA 派生) */
+    key?: Buffer;
+    /** 接收方 RSA 公钥(混合加密场景) */
+    rsaPublicKeyPem?: string;
+    /** 直接传入 IV(可选,默认内部随机生成) */
+    iv?: Buffer;
+}
+interface DecryptParams {
+    aad?: Buffer;
+    /** RSA 私钥 PEM(混合加密场景) */
+    rsaPrivateKeyPem?: string;
+    /** 对称密钥(必填,除非混合加密 + 走 RSA 私钥派生) */
+    key?: Buffer;
+    /** IV(必填) */
+    iv: Buffer;
+    /** GCM authTag */
+    tag?: Buffer;
+    /** 混合加密时,RSA 加密的对称密钥 */
+    encryptedKey?: Buffer;
+}
+/** 一个加密算法的统一接口 */
+interface Cipher {
+    readonly name: CipherAlgorithm;
+    readonly meta: CipherMeta;
+    /** 生成新的对称密钥(返回 Buffer) */
+    generateKey?(): Buffer;
+    /** 生成随机 IV */
+    generateIv(): Buffer;
+    encrypt(plain: Buffer, params?: EncryptParams): EncryptResult;
+    decrypt(cipher: Buffer, params: DecryptParams): Buffer;
+}
+interface Digest {
+    readonly name: DigestAlgorithm;
+    readonly meta: DigestMeta;
+    /** 计算摘要/签名,默认输出 hex */
+    sign(data: string | Buffer, key?: string | Buffer): string;
+    /** 校验摘要/签名 */
+    verify(sig: string, data: string | Buffer, key?: string | Buffer): boolean;
+}
+
+/**
+ * 全局类型定义:算法枚举、协议枚举、App 配置等
+ */
+
+/** 一个接入应用(app) 的服务端配置 */
+interface AppConfig {
+    /** 应用唯一标识 */
+    appKey: string;
+    /** 应用密钥(用于服务端校验签名 / 解密 biz_content) */
+    appSecret: string;
+    /** 是否启用 */
+    enabled?: boolean;
+    /** 允许的加密算法白名单,留空表示允许所有已注册算法 */
+    allowedCiphers?: CipherAlgorithm[];
+    /** 允许的摘要/签名算法白名单,留空表示允许所有 */
+    allowedDigests?: DigestAlgorithm[];
+    /** 允许的协议,留空表示所有已注册协议 */
+    allowedProtocols?: ProtocolKind[];
+    /** 自定义属性 */
+    metadata?: Record<string, unknown>;
+}
+/** ServerContext:服务端钩子里使用的上下文 */
+interface ServerContext {
+    app: AppConfig;
+    cipher: CipherAlgorithm;
+    digest: DigestAlgorithm;
+    protocol: ProtocolKind;
+}
+interface NonceStore {
+    set(key: string, value: string, ...args: any[]): Promise<any>;
+}
+
+type ProtocolKind = 'custom' | 'top';
+/** 协议策略的统一接口 */
+interface ProtocolStrategy {
+    readonly kind: ProtocolKind;
+    /**
+     * 客户端:组装请求信封
+     * @param input 业务参数 + 加密/签名算法
+     * @param ctx   客户端上下文(密钥等)
+     */
+    buildRequest(input: ProtocolRequestInput, ctx: ProtocolClientContext): Promise<Record<string, unknown>>;
+    /**
+     * 服务端:从原始 body 中解析、验签、解密
+     * 返回解出来的业务参数,挂到 req.secureRequest
+     */
+    parseAndVerify(raw: Record<string, unknown>, ctx: ProtocolServerContext): Promise<ProtocolVerifyResult>;
+    /**
+     * 服务端:把响应加密成信封
+     */
+    buildResponse(biz: unknown, ctx: ProtocolServerContext): Promise<Record<string, unknown>>;
+}
+interface ProtocolClientContext {
+    appKey: string;
+    appSecret: string;
+    /** 加密密钥 Buffer(对混合加密,rsaPublicKeyPem 走 params) */
+    encryptionKey: Buffer;
+    /** HMAC/签名密钥(hex 字符串) */
+    hmacSecret: string;
+    /** RSA 公钥 PEM(混合加密场景) */
+    rsaPublicKeyPem?: string;
+}
+interface ProtocolServerContext {
+    app: AppConfig;
+    encryptionKey: Buffer;
+    hmacSecret: string;
+    rsaPrivateKeyPem?: string;
+    nonceStore?: NonceStore;
+    requestWindowMs: number;
+}
+interface ProtocolRequestInput {
+    /** HTTP method */
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+    /** API 路径(/api/v1/...) */
+    path: string;
+    /** 业务参数(会被序列化到 envelope) */
+    biz: Record<string, unknown>;
+    /** 业务 body(可选) */
+    body?: unknown;
+    /** 用户 session(可选,TOP 协议需要) */
+    session?: string;
+    /** 业务 query */
+    query?: Record<string, string>;
+    /** 算法协商(可选,默认走客户端 / app 配置) */
+    cipher?: CipherAlgorithm;
+    digest?: DigestAlgorithm;
+    /** 协议类型(custom | top) */
+    protocol?: ProtocolKind;
+}
+interface ProtocolVerifyResult {
+    appKey: string;
+    method: string;
+    path: string;
+    body?: unknown;
+    query?: Record<string, string>;
+    session?: string;
+    /** 解析出来的子协议字段(TOP: biz_content 解密结果;custom: 整个载荷) */
+    biz: unknown;
+}
+
+export type { AppConfig as A, CipherAlgorithm as C, DigestAlgorithm as D, EncryptParams as E, NonceStore as N, ProtocolKind as P, ServerContext as S, Cipher as a, Digest as b, ProtocolStrategy as c, ProtocolRequestInput as d, ProtocolVerifyResult as e, CipherMeta as f, DecryptParams as g, DigestMeta as h, EncryptResult as i, ProtocolClientContext as j, ProtocolServerContext as k };

package/dist/client.d.mts

@@ -0,0 +1,72 @@
+import { P as ProtocolKind, C as CipherAlgorithm, D as DigestAlgorithm } from './base-v1-7dHNy.mjs';
+
+/**
+ * 浏览器端客户端公共类型
+ */
+
+interface BaseClientConfig {
+    baseURL: string;
+    /** 加密密钥 - 64 字符 hex(32 字节) */
+    encryptionKey: string;
+    /** 签名密钥(>= 32 字符) */
+    hmacSecret: string;
+    /** 应用标识(TOP 协议需要) */
+    appKey?: string;
+    /** 客户端默认协议 */
+    protocol?: ProtocolKind;
+    /** 默认加密算法 */
+    cipher?: CipherAlgorithm;
+    /** 默认签名算法 */
+    digest?: DigestAlgorithm;
+    defaultHeaders?: Record<string, string>;
+    requestWindowMs?: number;
+    /** RSA 公钥 PEM(混合加密场景) */
+    rsaPublicKeyPem?: string;
+    fetchImpl?: typeof fetch;
+}
+interface RequestOptions {
+    session?: string;
+    cipher?: CipherAlgorithm;
+    digest?: DigestAlgorithm;
+    protocol?: ProtocolKind;
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+}
+
+/**
+ * 浏览器端 / 通用 fetch 客户端
+ *
+ * 支持:
+ *   - 多种协议(protocol: 'custom' | 'top'),通过 envelope.protocol 字段协商
+ *   - 多种加密/签名算法(可按请求级别覆盖)
+ *   - 自动加密请求 + 解密响应 + 验签
+ */
+
+declare class SecureClient {
+    protected readonly baseURL: string;
+    protected readonly encryptionKey: Buffer;
+    protected readonly hmacSecret: string;
+    protected readonly appKey?: string;
+    protected readonly defaultProtocol: ProtocolKind;
+    protected readonly defaultCipher: BaseClientConfig['cipher'];
+    protected readonly defaultDigest: BaseClientConfig['digest'];
+    protected readonly defaultHeaders: Record<string, string>;
+    protected readonly requestWindowMs: number;
+    protected readonly rsaPublicKeyPem?: string;
+    protected readonly fetchImpl: typeof fetch;
+    constructor(config: BaseClientConfig);
+    /**
+     * 发起加密请求并解密响应
+     */
+    request<T = unknown>(method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH', path: string, options?: RequestOptions & {
+        body?: unknown;
+    }): Promise<T>;
+    protected decryptResponseOnly(envelope: any, protocolKind: ProtocolKind): Promise<unknown>;
+    get<T = unknown>(path: string, options?: RequestOptions): Promise<T>;
+    post<T = unknown>(path: string, body?: unknown, options?: RequestOptions): Promise<T>;
+    put<T = unknown>(path: string, body?: unknown, options?: RequestOptions): Promise<T>;
+    delete<T = unknown>(path: string, options?: RequestOptions): Promise<T>;
+    patch<T = unknown>(path: string, body?: unknown, options?: RequestOptions): Promise<T>;
+}
+
+export { type BaseClientConfig, type RequestOptions, SecureClient };