签名与载荷怎么防伪?manufacturing-wechat-miniapp-starter canonicalJson与SHA-256哈希原理剖析
签名与载荷怎么防伪?manufacturing-wechat-miniapp-starter canonicalJson与SHA-256哈希原理剖析
manufacturing-wechat-miniapp-starter 是一个面向制造业的微信小程序 starter 项目,把员工熟悉的微信端变成一线报工、考勤、工资确认的低门槛数据入口,并通过可审计的方式与 MES(制造执行系统)集成。它最值得关注的设计之一,就是用 canonicalJson(规范 JSON)+ SHA-256 哈希 给数据和电子签名"上锁",防止篡改与抵赖。这篇文章带你用最少代码看懂它的防伪原理。
先想清楚:为什么要"防伪"?
想象这样一个场景:员工在小程序里提交了一条"工单完成"记录,数据要回传给 MES。那么系统怎么回答下面两个问题?
- 数据有没有被改过? 如果传输中途数量从 100 件变成 90 件,系统能不能发现?
- 员工签过字吗? 工资单上的电子签名,将来能否作为"本人确认过"的证据?
manufacturing-wechat-miniapp-starter 的答案是:不要靠"信任",要靠可验证的指纹。核心工具只有两样:
| 工具 | 作用 | 一句话理解 |
|---|---|---|
| canonicalJson | 把 JSON 变成唯一的标准写法 | 先"排版统一",再谈指纹 |
| SHA-256 | 算出数据的 64 位十六进制指纹 | 内容变 1 个字节,指纹全变 |
canonicalJson:先让 JSON 有一个"固定长相"
🔑 这是新手最容易忽略的一步。直接用 JSON.stringify 算哈希有个大坑:字段顺序不同,字符串就不同。
看两个内容完全一样、只是字段顺序不同的对象:
{ "hours": 8, "workDate": "2030-01-15" }
{ "workDate": "2030-01-15", "hours": 8 }
如果用普通序列化算哈希,两条数据的"指纹"完全不同——MES 会误以为这是两条不同的记录。
所以项目先做了一步"规范化"。src/crypto.js 中的 canonicalJson 做了三件事:
- 对象键按字母序排序:
Object.keys(value).sort()保证任何对象无论原本顺序如何,序列化出来都长一个样; - 递归处理嵌套结构:数组里的对象、对象里的数组,全部套同一套规则;
- 紧凑输出、不带多余空格:输出里没有格式化换行,只保留纯内容。
打个比方:canonicalJson 就像先把文件按公文格式统一排版,再送去盖章指纹——只有排版一致,指纹才有可比性。
SHA-256 哈希:给数据盖一个"指纹章"
规范化之后,项目用 Node.js 内置的 node:crypto 计算 SHA-256(见 src/crypto.js 的 sha256 函数),它有三个关键特性:
- 确定性:同样的输入永远得到同样的 64 位十六进制字符串(所以 tests/connector.test.js 里可以直接断言
receipt.payloadHash.length等于 64); - 不可逆:从指纹推不回原始内容,知道哈希也无法还原出原始 JSON;
- 雪崩效应:输入哪怕只改 1 个字节,输出的 64 位指纹几乎全部重排。
这三条合起来,就构成了"防伪"的数学基础:想偷偷改数据,就必须能找到一个不同内容却产生相同指纹的"撞指纹",而这对 SHA-256 来说在现实中不可行。
实战一:MES 导出的载荷防伪 + 幂等重试
这套机制在 src/connector.js 的 MES 导出流程中体现得最完整,整个链路是:
- 出口算指纹:
payloadHash = sha256(input.payload),随载荷一起发给 MES; - 幂等键防重复:每条导出带一个稳定
idempotencyKey,同一键 + 同一载荷再次调用,直接返回原回执(replayed: true),不会重复写 MES; - 改内容就报错:同一幂等键但载荷变了(比如工时从 8 改成 9),哈希必然不同,系统抛出
IDEMPOTENCY_CONFLICT; - 回执也要验:MES 返回的回执如果带了
payloadHash且与本地不一致,直接判定MES_RECEIPT_HASH_MISMATCH。
这套"载荷哈希 + 幂等键 + 回执校验"的组合拳,对应 README 里描述的 idempotent MES exports with payload hashes and receipts。相关失败路径都被测试覆盖了:
- 相同键 + 相同载荷 → 本地回放,只调一次传输层;
- 相同键 + 变更载荷 → 拒绝;
- 回执哈希不匹配 → 拒绝;
- 审计日志只记回执身份,不含载荷正文(隐私设计)。
实战二:工资签名只存哈希,不留原文
另一个很实用的场景是月度工资单的电子签名,实现在 src/payroll.js 的 acknowledgePayroll:
- 月度工资单确认时,
signature至少 12 个字符,否则报SIGNATURE_REQUIRED——防止"随手一点"式的无意识确认; - 签名原文经过
sha256后以signatureHash形式落库,原始签名内容不存储。
tests/payroll.test.js 中有一个很有说服力的测试:断言数据库行的 JSON 里完全搜不到签名原文,只存在 64 位哈希。这对隐私友好——系统能证明"该员工确实签过且没改过",却不需要在库里留一份敏感的笔迹/签名数据。
新手如何本地验证这些原理?
项目零依赖(Node.js 20+),两条命令即可体验:
npm test
npm run demo
npm run demo 会跑一遍完整的合成流程:员工打考勤 → 导出 MES → 打印回执 ID 和载荷哈希,对应 examples/demo.js。你可以试着修改 demo 里的 payload(比如把 status 改一个字),再跑一次,观察 64 位 payloadHash 如何整体重排——这就是雪崩效应的现场演示。
小结
- canonicalJson 解决"同一内容多种写法"的问题,让哈希可比;
- SHA-256 生成不可逆、抗碰撞的数据指纹;
- 两者组合后,MES 导出的载荷可验真、可幂等重试,工资签名只存指纹、不留原文;
- 核心实现集中在 src/crypto.js,应用点见 src/connector.js 与 src/payroll.js,测试保障在 tests/ 目录。
对新手来说,这套"先规范化、再算指纹、最后逐点校验"的模式,是理解一切签名防伪系统(从 HTTPS 证书到区块链)的通用骨架。