fhEVM JS SDK 审查计划深度解析解密许可版本控制、阈值类型与 EIP-712 的正确性保障【免费下载链接】fhevmFHEVM, a full-stack framework for integrating Fully Homomorphic Encryption (FHE) with blockchain applications项目地址: https://gitcode.com/GitHub_Trending/fh/fhevmfhEVM 的 JavaScript SDKsdk/js-sdk负责在浏览器/Node 环境中完成加密、解密与 KMS 交互其中**解密许可Signed Decryption Permit**是用户向 KMS 网关授权解密的 EIP-712 签名凭证其版本、编码与校验直接决定解密流程能否在链上升级后保持正确。本文以仓库内审查文档 sdk/js-sdk/notes/SDK_REVIEW_PLAN.md 为主体系统解析其对 15 个审查点的 triage 结论并结合sdk/js-sdk/src、host-contracts、gateway-contracts的源码逐一印证读者可以从中掌握 permit 的 v1/v2 演进脉络、extraData 编码细节、阈值类型缺陷以及一套先证明不变量、再补测试的工程化审查方法。一、审查背景一份只读调查的代码审查计划该文档定位是一次read-only investigation只读调查未改动任何代码对sdk/js-sdk的 15 个审查点逐一给出四种判定之一confirmed bug已确认缺陷、decision needed需决策、additive work增量工作、verified-fine已验证无问题并附上证据。文档中的File:line引用以审查时点为准本文在引用时以文件路径为主并标注了与当前仓库代码的差异。1.1 关联的合约版本审查涉及三代 host 合约源码对应三档协议版本协议版本合约源码位置说明v12sdk/js-sdk/contracts/src/v0.12.0/host-contractsKMSVerifier 0.4.0extraData 最高 v1v13sdk/js-sdk/contracts/src/v0.13.0/host-contracts同上协议 API 走 v13 读取路径v14host-contracts/contractsKMSVerifier ≥ 0.4.0引入protocolConfigAddress与 epoch 概念SDK 侧对 KMSVerifier 版本与 extraData 上限的对应关系在 kmsExtraData-p.ts 的isKmsExtraDataCompatibleWithKmsVerifier中有精确注释 0.2.0→ 协议 v0.11.0 → extraData ≤ v00.2.0–0.3.x→ 协议 v0.12.0/v0.13.0 → extraData ≤ v10.4.0→ 协议 v0.14.0 → extraData ≤ v2 0.4.0v0.14.1则返回true不设上限理由是未来的合约版本接受范围无法预知若链上拒绝让 revert 本身成为事实来源。1.2 Triage 总览表#审查点判定1, 2threshold 是 uint256 而非 uint8Confirmed bug3getResolvedProtocolVersion可能为 undefinedVerified — 不是 bug4permit 中的零地址Decision可选加固前提已被修正5, 6decrypt v2/v3 路由潜在风险当前非活跃 bug9–15SDK 必须只产出 v1 permit / v0–v1 extraData已确认该不变量当前未被保证核心问题7parse/serialize permit 测试增量工作——当前覆盖为零8为 Ankur 提供 createEip712增量工作——当前不存在以下按优先级Workstream A → B → C → D → E展开。二、Workstream Av1-only 不变量最高优先级覆盖点 6/9/10/11/12/13/14/152.1 核心发现SDK 可能产出 v2 permit 与 v2 extraData审查的关键结论是当前 SDK 不存在任何experimental标志src中唯一的experimental命中是 isomorphicWorker.ts 里一处无关的 worker 注释因此存在两条相互独立的违规路径Path Av2 permit审查时点的signDecryptionPermit路由器在解析协议 ≥ 0.14.0 时派发到signDecryptionPermitV2而后者是公开可达的。Path Bv1 permit 内嵌入 v2 extraDatasignDecryptionPermitV1通过createUnsignedDecryptionPermitEip712V1调用的是通用的readCurrentKmsSignersContextreadKmsSignersContext-p.ts当链上 KMSVerifier ≥ 0.4.0 时会落入无门禁的_readCurrentKmsSignersContext_ProtocolApi_14_or_higher:177构造出带非零epochId的 v2 extraData随后kmsSignersContextToExtraDataKmsSignersContext-p.ts会根据epochId自动选择版本——不会封顶在 v1。也就是说一个v1 形状的 permit内部可能携带 v2 编码的 KMS 上下文链上/网关按 v1 解析时会产生语义漂移。2.2 当前仓库代码状态核对对照当前源码上述发现的部分落点已经演进需要在阅读时区分审查快照与当前实现路由器已固定 V1当前 SignedDecryptionPermit-p.ts 的signDecryptionPermit:153被刻意 pin 到 V1注释说明该公开 action 已废弃建议迁移到signLegacyDecryptionPermit/signUnifiedDecryptionPermit。而 signUnifiedDecryptionPermit.ts 直接调用SignedDecryptionPermitV2-p.ts的signDecryptionPermitV2——v2 签名能力仍然公开可达。Path B 的结构未变SignedDecryptionPermitV1-p.ts 的createUnsignedDecryptionPermitEip712V1:152仍在:167调用通用readCurrentKmsSignersContext再经kmsSignersContextToExtraData:173编码。只要链上 KMSVerifier 已升级到 ≥ 0.4.0v1 构建路径就可能产出 v2 extraData。extraData 版本自选择逻辑确认存在KmsSignersContext-p.ts 的kmsSignersContextToExtraData:153与 kmsExtraData-p.ts 的createKmsExtraData:286依据epochId是否为 0 自动选择 v0/v1/v2。2.3 三种 extraData 编码源码实证从 kmsExtraData-p.ts 可精确还原三种编码EXTRA_DATA_V0/V1/V2定义于:10-12版本字节结构十六进制长度约束v00x00单字节哨兵2contextId、epochId 必须为 0v11 字节版本 32 字节大端 contextId68contextId 非 0epochId 必须为 0v21 字节版本 32 字节 contextId 32 字节 epochId132contextId 与 epochId 均非 0另有一个易被忽略的细节toKmsSignedExtraDataBytesHex:228规定 KMS 签名时 v0 以空字节0x表示而非 SDK 内部的0x00——任何按内部编码重建签名消息的代码per-share 解密、公开解密证明等若漏掉这一转换v0 签名将无法验证。2.4 修复计划对应点 10–15在 runtime/client 上引入显式experimental模式标志当前不存在并贯穿到 KMS context 读取器。将_readCurrentKmsSignersContext_ProtocolApi_14_or_higher置于 experimental 门禁之后对应点 15。为signDecryptionPermitV1提供仅限 v1 的签名者上下文——专用的readCurrentKmsSignersContextV1或maxVersion1约束保证其永远拿不到 v2 上下文/非零 epoch对应点 10、14。将kmsSignersContextToExtraData封顶在 v1并在signDecryptionPermitV1内增加assert(extraData.version EXTRA_DATA_V1)让 Path B响亮地失败而不是静默产出 v2对应点 9、12。V2 签名路径已有镜像断言SignedDecryptionPermitV2-p.ts 的createUnsignedDecryptionPermitEip712V2中assert(kmsContextExtraData.ge(EXTRA_DATA_V2)):316-319。普通模式下禁止signDecryptionPermitV2——路由器在 ≥ 0.14.0 时抛错除非 experimental 开启对应点 11同时决策parse/serialize是否仍应接受v2 输入。加固路由对应点 5、6在解密路由处交叉校验signedPermit.version与协议推导的分支不一致即抛错而不是盲目转换。复查reconcileKmsSignersContext可被 relayer 输入的 v2 extraData 污染一并加门禁。待决策门禁模型——客户端单一布尔experimental还是完全以解析出的协议版本为键。点 14epochId 0与点 15experimental only暗示普通模式 永远 v1/epoch-0experimental 允许 0.14.0 的 v2/v3 路径。2.5 路由现状与潜在风险点 5、6审查指出路由并不以permit.version分支而是在单一0.14.0边界上按解析出的协议版本分支v2 路由/v3 路由对应 HTTP 端点v2/user-decrypt经fetchUserDecryptV1与v3/user-decrypt经fetchUserDecryptV2。点 5 的前提成立v1 抓取路由读取contractAddresses而 v2 permit 消息中缺少该字段v2 使用userAddressallowedContracts。当前源码的演进从当前 decryptValuesFromPairs.ts 看路由已改为按parameters.signedPermit.version分支:58-65注释明确写道permit 是自描述工件其 version 固定了 EIP-712 消息形状只有匹配的路由能读取它并命中对应 relayer 端点——这正对应审查建议 6 的硬化方向。同理 fetchUserDecrypt.ts 也按parameters.version 1分支。这说明审查建议的部分内容已在后续提交中落地但 Path B 的v1 permit 内嵌 v2 extraData与 experimental 门禁仍属开放项。三、Workstream Bthreshold 类型缺陷点 1、2已确认、自包含3.1 缺陷本质链上 uint256 与 TS Uint8Number 不一致链上与 SDK 自己的 ABI 片段都将 threshold 声明为uint256fragments.ts 以及 KMSVerifier.sol 的结构体uint256 threshold但 TS 类型层将其标注为Uint8Number并用isUint8校验uint.ts 的isUint8:143。于是readContract返回的bigint只要 255就会抛Invalid threshold.。涉及面包括KMSkmsSignersContext.tsthreshold: Uint8Number:56、KmsSignersContext-p.ts、getKmsContextSignersAndThresholdFromExtraData-p.ts、getKmsContextSignersAndThreshold-p.tsCoprocessorcoprocessor.ts、coprocessorSignersContext.ts、CoprocessorSignersContext-p.ts、getCoprocessorContextSignersAndThreshold-p.ts。3.2 修复方案将两类 threshold 统一重类型为 uint256/bigint用isUint256uint.ts 的isUint256:163校验去掉Number(...)收窄在 2^53 以上存在精度损失将recoveredAddresses.length threshold之类的比较改为BigInt(length) threshold。审查同时给出风险定性实践中阈值等于节点数量、通常远小于 256属于低频但真实的正确性上限例如 KmsSignersContext-p.ts 的createKmsSignersContext中kmsSignerThreshold: Number(kmsSignerThreshold) as Uint8Number的收窄。四、Workstream Cpermit 中的零地址点 4需决策且前提被修正4.1 前提修正仓库中不存在 RFC 12只有 notes/rfc/DRAFT_RFC_016.mdRFC 16。该草案将contractAddresses类型化为readonly string[]但未规定零地址、去重与最小数量。permit 的合约列表校验发生在gateway-contracts/contracts/Decryption.sol而非 host 侧KMSVerifier.sol后者只校验 KMS 响应签名。4.2 现状SDK 与合约都不拒绝零地址/重复项SDK 侧fetchKmsSigncryptedSharesV1-p.ts仅做成员资格校验空列表与最大 10 个的限制在MAX_USER_DECRYPT_CONTRACT_ADDRESSES 10SignedDecryptionPermitV1-p.ts 的_validateDecryptionPermitEip712V1:266只检查非空、≤10、duration 合法同样不检查零地址。合约侧Decryption.sol检查空列表、最大 10、user/delegator 不在列表中、ct-pair 在列表中同样没有零地址/重复项检查。SDK 与链上行为一致因此不存在SDK 与链分叉问题零地址在语义上只是无用的地址下游 ACLisAllowed会失败并非安全漏洞。4.3 决策(a) 保持现状与链一致或 (b) 在assertPermitV1IncludesContractAddresses与 permit 构建器中提前拒绝零地址与重复项。审查倾向 (b)——成本低、fail-fast——但属可选加固。五、Workstream D测试补齐与 createEip712点 7、8增量工作5.1 点 7permit 的 serialize/parse 当前零覆盖审查时点test/fheTest下唯一的 parse/serialize 相关代码是index.hello.test.ts中一段被注释掉的测试块。涉及函数serializeSignedDecryptionPermitToJSONSignedDecryptionPermit-p.ts:55内部有instanceof守卫:69并特意不在类上实现toJSON()防止JSON.stringify(permit)意外序列化敏感数据domain 的 bigintchainId会以十进制字符串输出保证JSON.stringify后仍可还原_toJsonSafeEip712:27。parseSignedDecryptionPermit:217无 version 时默认按 v1:232未知版本抛错:235-237v1/v2 分别派发:242-246并先经_normalizeSerializedPermitDomainChainId:179把字符串形式的chainId转回 bigint。公开包装actions/chain/serializeSignedDecryptionPermit.ts与actions/chain/parseSignedDecryptionPermit.ts。审查建议补充三类测试单元测试如src/core/kms/SignedDecryptionPermit-p.test.tsserialize 拒绝非 Impl 输入parse 的版本派发未知→抛错、缺省→v1畸形输入拒绝SignedDecryptionPermitV1-p.ts:277-306的校验publicKey 不匹配:289-294V1 的_validateDecryptionPermitEip712V1与 parse 路径。往返测试需链放在test/fheTest/**parse(serialize(permit))深比较覆盖 v1 自解密 v1 委托若保留 experimental再加 v2。接口一致性ParseSignedDecryptionPermitParametersactions/chain/parseSignedDecryptionPermit.ts字段名为serializedPermit且只接受对象违反命名规范应支持serialized: string | Record...——JSON 字符串目前会直接失败需要锁定或修复。5.2 点 8公开的 createEip712 不存在内部 builder 存在但未导出createKmsUserDecryptEip712V1createKmsUserDecryptEip712V1.ts、createKmsUserDecryptEip712V2、委托变体与 domain builder。而 notes/rfc/RFC003.md:256-257规定了公开 APIcreateUserDecryptEIP712/ createDelegatedUserDecryptEIP712语义是构造 EIP-712 typed data 但不签名。计划落点新增一个decrypt 层公开 actioncreateUserDecryptEip712(fhevm, params)含委托变体内部完成解析协议版本与链字段verifyingContractAddressDecryption、chainId、解析extraData链上抓取或接受入参、派发到内部 builder、返回未签名的 typed data。按 Workstream A普通模式下应构建V1typed data。命名须遵循createEip712/createUserDecryptEip712的大小写规范。值得注意的现状当前仓库已存在两个未签名 EIP-712公开 action——createUnsignedLegacyDecryptionPermitEip712.tsV1与createUnsignedUnifiedDecryptionPermitEip712.tsV2它们与 RFC003 的createUserDecryptEIP712理念一致但最终命名形态与委托变体仍需与 Ankur 确认。待决策RFC003 的签名形态是否满足需求extraData由调用方提供还是链上获取。六、Workstream E已验证、无需处理点 3getResolvedProtocolVersionCoreFhevm-p.ts 中声明为protocolVersion: ProtocolVersionResolution的类型是ProtocolVersionResolution | undefined全部 7 个调用点都处理了 undefined要么抛出明确错误要么在 ProtocolVersionResolver-p.ts 中回退测试也覆盖了 undefined 路径ProtocolVersionResolver-p.test.ts。结论无修复项。七、建议的实施顺序A 优先——正确性/安全性不变量若在 v0.13.0 版本中发出 v2 permit/extraData 会破坏解密且改动面最大其 experimental 标志决策会解锁 C/D 中的 v2 问题。B 并行——隔离、机械式的阈值类型修复。D 在 A 之后——测试需要编码 v1-only 不变量createEip712也要遵守它。C 最后——可选的零地址加固。八、实施前待决的两个开放问题Workstream A 的experimental 门禁模型单一布尔标志 vs. 完全依赖解析出的协议版本。createEip712是否遵循 RFC003 的签名形态、extraData由调用方提供还是链上获取。九、继续深入相关文件索引审查计划原文sdk/js-sdk/notes/SDK_REVIEW_PLAN.mdPermit 实现SignedDecryptionPermit-p.ts、SignedDecryptionPermitV1-p.ts、SignedDecryptionPermitV2-p.tsextraData 编码kmsExtraData-p.ts、KmsSignersContext-p.ts链上上下文读取readKmsSignersContext-p.ts、kmsSignersContext.ts数字校验基元uint.ts解密路由decryptValuesFromPairs.ts、fetchUserDecrypt.ts链上契约侧KMSVerifier.sol、Decryption.sol协议规范notes/rfc/RFC003.md、notes/rfc/DRAFT_RFC_016.md这份审查计划的真正价值在于它的方法论先把SDK 必须只产出 v1 permit这类不变量显式写出来再用源码证据逐条验证、按风险排序实施最后用测试把不变量固化下来——这正是多版本协议 SDK 演进时值得复用的工程范式。【免费下载链接】fhevmFHEVM, a full-stack framework for integrating Fully Homomorphic Encryption (FHE) with blockchain applications项目地址: https://gitcode.com/GitHub_Trending/fh/fhevm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
