SuperAPI AI 工具集

encryption

安全与审计

查看项目

更新于 10-16 05:07

技能介绍

用途:为 Epicenter 提供加密模式与实现参考,覆盖密钥派生、对称加密、密钥层级、密钥轮换和 EncryptedBlob 格式,适用于需要“加密此数据”、密钥管理或加密原语的场景。

主要能力:使用 HKDF-SHA256 做密钥派生,info 字符串作为域分隔标签(如 user:{userId}、workspace:{wsId}),空 salt;对称加密采用 XChaCha20-Poly1305(@noble/ciphers),24 字节随机 nonce;密钥层级为根密钥→每用户密钥→每工作区密钥;密钥版本嵌入密文 blob[1],支持惰性重加密与轮换。

使用方式:通过环境变量 ENCRYPTION_SECRETS 配置,格式为逗号分隔的 version:secret 对,最高版本为当前加密密钥,例如 ENCRYPTION_SECRETS="1:base64encodedSecret",轮换后 ENCRYPTION_SECRETS="2:newBase64Secret,1:oldBase64Secret"。生成密钥可用 openssl rand -base64 32。EncryptedBlob 为 Uint8Array,blob[0] 为格式版本(当前 1),blob[1] 为密钥版本,blob[2..25] 为 nonce,blob[26..] 为密文与认证标签。可用 isEncryptedBlob、getKeyVersion、getFormatVersion 检测与读取。

适用场景:CRDT 热路径中的同步加解密、工作区值加密、密钥轮换与离线设备兼容、密文自描述版本管理。

限制:AES-256-GCM 经 WebCrypto 更快但为异步,本方案需同步加解密;HKDF info 字符串应视为协议字符串保持稳定;轮换时旧密钥建议保留至少 90 天;格式版本升级仅用于算法或二进制布局变更;服务端可见性、测试向量与批量轮换校验需按资料另行定义。