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 解密（接收 EncryptedData 对象）
• encryptWithAESGCM(plainText, aesKey, aad?) - AES-GCM 加密（返回 Base64 字符串）
• decryptWithAESGCM(cipherTextBase64, aesKey, aad?) - AES-GCM 解密（接收 Base64 字符串）
• encryptAESKeyCompat(aesKey, serverPubKey) - ECIES 加密（兼容 Bouncy Castle）

密钥交换

• 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 格式解析

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