WeCipher

微信小程序加密工具库，基于 ECIES (ECDH + AES-GCM) 方案。

English | 中文

安装

npm install wecipher

主要 API

密钥生成

• generateP256KeyPair() - 生成 P-256 密钥对
• generateAES256Key() - 生成 AES-256 密钥

加密解密

• encryptAESGCM(plaintext, key, aad?) - AES-GCM 加密（返回 EncryptedData 对象）
• decryptAESGCM(encryptedData, key, aad?) - AES-GCM 解密（返回明文字符串）
• encryptWithAESGCM(plainText, aesKey, aad?) - AES-GCM 加密（返回 Base64 字符串）
• decryptWithAESGCM(cipherTextBase64, aesKey, aad?) - AES-GCM 解密（返回明文字符串）
• encryptAESKeyCompat(aesKey, serverPubKey) - ECIES 加密（兼容 Bouncy Castle）
• encryptAESKeyWithECCPublicKey(aesKey, eccPublicKey) - 使用 ECC 公钥进行 ECIES 加密

请求签名

• generateRequestSignature(signContent, aesKeyBytes) - 生成 x-signature 请求头（Base64(HmacSHA256(signContent, aesKeyBytes))）

密钥交换

• deriveSharedSecret(privateKey, publicKey) - 派生共享密钥
• deriveAESKey(sharedSecret) - 派生 AES 密钥

载荷加密

• clientEncryptField(plaintext, serverPublicKey, clientKeyPair, aad?) - 客户端加密
• clientDecryptField(encryptedData, serverPublicKey, clientPrivateKey, aad?) - 客户端解密（返回明文字符串）

工具函数

• bytesToBase64(bytes) / base64ToBytes(base64) - Base64 转换
• generateUUID(length?) - 默认生成标准 UUID v4；传入长度时生成指定长度随机十六进制字符串
• generateUUIDV4() - 生成标准 UUID v4 字符串
• jwkToPublicKey(jwk) - JWK 格式转换
• extractPublicKeyFromDERBase64(derBase64) - DER 格式解析

WMP 请求签名

generateRequestSignature 仅负责 HmacSHA256 与 Base64 编码；signContent 与 32 字节 AES 会话密钥由业务方传入。

按顺序用 \n 拼接：METHOD、PATH、SORTED_QUERY、BODY、X-NONCE。

• METHOD — 大写 HTTP 方法（如 POST）
• PATH — 不含域名与查询串的路径（如 /api/v1/orders）
• SORTED_QUERY — 查询参数按参数名升序排列，格式为 key1=val1&key2=val2，无参数时为空字符串
• BODY — 原始请求体字符串，无 body 时为空字符串
• X-NONCE — x-nonce 请求头的原始值

import { generateRequestSignature } from 'wecipher';

const signContent = [
  'POST',
  '/api-up-order/api/v1/orders',
  'page=1&type=vip',
  '{"memberId":"M001","amount":100}',
  '1713200000000',
].join('\n');

const xSignature = generateRequestSignature(signContent, aesKeyBytes);

可与 encryptAESKeyWithECCPublicKey（或 encryptAESKeyCompat）配合，通过 ECIES 协商每次请求的 AES 会话密钥并写入 x-encrypt-key 请求头。

AES-GCM AAD

aad 是可选参数，支持 string 或 Uint8Array。不传 AAD 的旧调用保持原有行为；加密时传入 AAD 后，解密时必须传入完全相同的 AAD。AAD 只参与认证，不会写入密文。

import { decryptAESGCM, encryptAESGCM, generateAES256Key } from 'wecipher';

const key = generateAES256Key();
const aad = 'request-id:123';

const encrypted = encryptAESGCM('hello', key, aad);
const plaintext = decryptAESGCM(encrypted, key, aad);

UUID

import { generateUUID, generateUUIDV4 } from 'wecipher';

generateUUID(); // 例如 "8ab9a533-2099-43a0-b48b-5fbb472d9343"
generateUUIDV4(); // 标准 UUID v4
generateUUID(16); // 指定长度随机十六进制字符串

微信小程序

• initWxSecureRandomCache(size?) - 初始化安全随机数缓存（必须先调用），默认128字节，可自定义大小
• setupWxPolyfills() - 设置微信小程序环境补丁，包括 TextEncoder/TextDecoder、crypto.getRandomValues、wx.getSecureRandomValuesSync（需先调用 initWxSecureRandomCache）
• generateAndCacheSecureRandomBytes(size?) - 生成并缓存安全随机数，默认128字节，使用 HKDF-SHA256 确保密码学安全性
• getSecureRandomValuesSync(length) - 同步获取指定长度的安全随机数
• wxGetSecureRandomValuesAsync(length) - 异步获取随机数
• isCacheInitialized() - 检查缓存是否已初始化
• resetSecureRandomCache() - 重置缓存（用于测试）

License

ISC