hejunjie-encrypted-request

前端加密请求工具，与 hejunjie/encrypted-request PHP 包配套使用。将请求参数加密后，由调用方自行发起 HTTP 请求。

本项目已由 Zread 解析，可点击此处快速了解：了解本项目

特性

• 🔐 AES-256-GCM 加密业务数据，密钥每次随机生成，不存储
• 🔑 RSA-OAEP(SHA-1) 加密传递密钥材料，前端仅需配置 RSA 公钥
• ✍️ HMAC-SHA256 动态签名，防篡改、防重放
• 🪪 协议版本号，前后端通过版本号匹配加密协议，便于升级
• 📦 TypeScript 开发，类型完备
• 🚀 基于 Web Crypto API，零外部依赖

安装

npm install hejunjie-encrypted-request

快速开始

import { encryptRequest } from "hejunjie-encrypted-request";

const pubKey = `-----BEGIN PUBLIC KEY-----
您的 RSA 公钥
-----END PUBLIC KEY-----`;

const signSecret = "your-shared-secret";
const version = 1;

// 加密业务数据，version 为协议版本号，需与后端一致
const encrypted = await encryptRequest(
  {
    data: { message: "Hello World" },
    rsaPublicKey: pubKey,
    signSecret: signSecret,
  },
  version
);

// 使用加密结果发起请求
await fetch("/api/user/info", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(encrypted),
});

加密后的请求体结构：

{
  "en_data": "xK9mR3w...",
  "enc_payload": "Z7zoj/bF...",
  "timestamp": 1756367390,
  "sign": "a1b2c3..."
}

API 参考

encryptRequest(options, version)

对业务数据进行加密，返回可直接作为 HTTP body 的加密对象。

参数

| 参数 | 类型 | 必需 | 描述 | | ---- | ---- | ---- | ---- | | options | EncryptOptions | ✅ | 加密配置 | | version | number | ✅ | 协议版本号，需与后端匹配 |

返回

Promise<EncryptResult>

EncryptOptions

| 字段 | 类型 | 必需 | 描述 | | ---- | ---- | ---- | ---- | | data | Record<string, unknown> | ✅ | 要加密的业务数据 | | rsaPublicKey | string | ✅ | RSA 公钥（PEM 格式） | | signSecret | string | ✅ | HMAC 签名密钥，需与后端 SIGN_SECRET 一致 |

EncryptResult

| 字段 | 类型 | 描述 | | ---- | ---- | ---- | | en_data | string | AES-256-GCM 加密后的业务数据（Base64） | | enc_payload | string | RSA-OAEP 加密的密钥材料（Base64），包含 AES 密钥、IV、nonce 和协议版本号 | | timestamp | number | 秒级时间戳 | | sign | string | HMAC-SHA256 签名（64 字符 Hex） |

加密流程

1. 随机生成 AES-256 密钥（32 字节）、GCM IV（12 字节）、nonce（UUID 去横线）
2. 用 AES-256-GCM 加密 JSON 序列化后的业务数据 → en_data
3. 将密钥材料打包为 { v, aes_key, aes_iv, nonce }，用 RSA-OAEP(SHA-1) 公钥加密 → enc_payload
4. 对 en_data + enc_payload + timestamp 做 HMAC-SHA256 签名 → sign

[!NOTE] 每次调用 encryptRequest 都会重新生成 AES 密钥和 IV，因此相同数据每次加密结果不同。

注意事项

• 安全上下文：Web Crypto API 仅在 HTTPS 或 localhost 下可用，详见 MDN 文档
• RSA 公钥格式：需要 PEM 格式的 SPKI 公钥（-----BEGIN PUBLIC KEY-----）
• 签名密钥：signSecret 必须与后端 SIGN_SECRET 完全一致
• 协议版本号：version 参数需与后端约定一致，用于控制加密协议的兼容性

开发与构建

# 构建
npm run build

# 运行集成测试
npm test

TypeScript 源码位于 src/，构建输出到 dist/。编译目标为 ES2019，支持所有现代浏览器。

相关仓库

• PHP 解密端：hejunjie/encrypted-request