Attestix离线验证器指南:6种语言验证AI Agent签名凭证,规范JSON加Ed25519一次讲透
Attestix离线验证器指南:6种语言验证AI Agent签名凭证,规范JSON加Ed25519一次讲透
Attestix离线验证器让"验证AI Agent签名凭证"不再依赖网络:签发方(issuer)的 Ed25519 公钥直接编码在凭证 JSON 的 did:key 里,验证方拿到一个纯文本 JSON 文件即可完成验签、查过期、查吊销。本指南面向新手,讲透 Attestix 的离线验证原理——规范 JSON(Canonical JSON)+ Ed25519 签名 + did:key 解码,以及 Python、JavaScript/TypeScript、Go、Rust、Java、R 六种语言验证器如何通过同一套公开一致性测试向量(conformance vectors)保证"同一份字节,同一份结论"。
🧭 Attestix离线验证器是什么
想象你是监管方,供应商发来一个 AI 系统的合规凭证(Verifiable Credential)。你想确认三件事:
- 凭证确实由声称的签发方签署;
- 签名内容未被篡改;
- 背后的审计链内部自洽。
传统做法要联网拉取 DID 文档、调用签发方接口。Attestix 的设计是零网络:签发方公钥不在外部目录里,而是内嵌在凭证自身的 issuer.id 字段中(形如 did:key:z6Mk...),解码后即得 32 字节 Ed25519 原始公钥。整个验证过程只读这一个 JSON 文件。
凭证 JSON ──▶ 剥离 proof/credentialStatus ──▶ 规范 JSON 序列化
│
did:key ──▶ base58 解码 ──▶ 32字节公钥 ◀───────────┤
▼
Ed25519 验签(RFC 8032)+ 过期/吊销检查
签发(issuance)保留在 Python 核心中单点实现;验证(verification)足够小——Ed25519 验签、规范序列化、did:key 解码、授权链衰减逻辑——因此被移植到了六种语言。一次签发,随处验证,离线可用。
📦 离线验证三支柱:Canonical JSON、Ed25519 与 did:key
1️⃣ 规范 JSON:验签的"字节级契约"
验签的前提是复现被签名的确切字节。Attestix 采用一套 JCS 风格(style)的规范序列化,注意:它不是严格 RFC 8785。规则(完整定义见 spec/verify/v1/README.md):
| 规则 | 说明 |
|---|---|
| 键排序 | 按 Unicode 码点升序,逐层递归 |
| 分隔符 | "," 与 ":",全串无空白 |
| 输出编码 | 原始 UTF-8,不做 \uXXXX 转义(é 是 2 字节,不是 6 字节) |
| 字符串归一 | 所有字符串与键都做 NFC 归一化(这是与严格 RFC 8785 的关键差异之一) |
| 浮点数 | 整数浮点折叠为整数:1.0 → 1;1.5 保持 1.5 |
| 大整数 | 超过 2^53 的整数原样序列化(JS 端需 BigInt) |
参考实现就在 attestix/auth/crypto.py 的 canonicalize_json 与 _normalize_for_signing 中。对 W3C VC 而言,被签名的字段是除 proof 与 credentialStatus 之外的全部顶层字段(见 attestix/services/credential_service.py 中的 MUTABLE_FIELDS)。任何一条规则做错,都会算出不同的字节,进而拒绝合法凭证——或更糟,接受被篡改的凭证。
2️⃣ Ed25519 签名与编码
- 签名算法:Ed25519(RFC 8032),作用于规范 JSON 的 UTF-8 字节;
- 签名编码:base64url 且带 padding——64 字节签名 → 88 字符、以
=结尾的字符串,存放在proof.proofValue。
3️⃣ did:key:公钥的自我编码
did:key:z6Mk... 的解码规则:去掉 did:key:z 前缀做 base58btc 解码,断言前两字节为 multicodec 前缀 0xed 0x01(ed25519-pub),剩余 32 字节即原始公钥。
一个常被忽略的安全细节:验证方只用 issuer.id 解码的公钥验签;若 proof.verificationMethod 指向另一个 DID,验证直接失败。这就堵死了"偷换签发方密钥"(key substitution)的攻击路径——实现见 attestix/services/credential_service.py 的 _verify_proof_bound。
最终结论是三个布尔值的 AND:
valid = signature_valid AND not_expired AND not_revoked
🌐 六种语言验证器 + 一份公开一致性向量
同一规范字节、六次独立实现。Attestix 0.4.0 提供六套验证器,全部对同一份公开向量断言:
| 语言 | 安装方式 | 说明 |
|---|---|---|
| Python | pip install attestix |
完整库:签发 + 验证 + 溯源 |
| JavaScript / TypeScript | npm install @vibetensor/attestix |
离线验证器 + 授权链辅助 |
| Go | go get 安装 attestix-go |
凭证验证 + 授权链 |
| Rust | cargo add attestix |
验证器 + 规范化检查 |
| Java | 按仓库构建说明安装 | 面向调用方锚定信任输入 |
| R | 按仓库安装说明安装 | 凭证 + 授权验证 |
📌 各语言验证器的信任输入与授权链检查边界并不完全相同,共享向量证明的是"密码学判词一致",安装前请阅读对应 README 并锁定已审查版本。
一致性契约是机器可读的 spec/verify/v1/vectors.json,由 spec/verify/v1/generate_vectors.py 用固定 Ed25519 种子 + 冻结时间戳从真实 0.4.0 密码学生成,共 7 条向量(见 spec/verify/v1/CONFORMANCE.md):
| 向量 ID | 检验内容 |
|---|---|
canon-001 |
规范化输出逐字节一致(NFC、码点排序、原始 UTF-8、大整数) |
didkey-001 |
0xed01 ‖ raw32 的 base58btc 公钥往返解码 |
vc-valid-001 |
合法 VC ⇒ 验证通过 |
vc-tampered-001 |
翻转一个声明字节 ⇒ 签名失效 |
vc-expired-001 |
过期凭证 ⇒ not_expired 为 false(签名本身仍有效) |
ucan-chain-valid-001 |
子授权是父授权子集 ⇒ 通过 |
ucan-chain-escalation-002 |
子级越权(admin 不在父级)⇒ 拒绝 |
对验证者最有价值的是 canon-001:如果你的规范化器连这个向量都过不了,后面一切签名验证都不会对;反之,过了它,字节就对上了。
⚡ 快速上手:三步完成离线验证
第一步:安装
pip install attestix
第二步:读取凭证 JSON
让供应商直接发给你一个 .json 文件即可——不需要密钥库、不需要目录服务。网站仓库里就有一份可直接验证的示例凭证:website/src/lib/samples/sample-valid-vc.json(另有一份被篡改的对照样本 sample-tampered-vc.json)。其结构骨架:
{
"id": "urn:uuid:fd2ab479-da9f-4cec-959e-c9a6c0e1f116",
"type": ["VerifiableCredential", "EUAIActComplianceCredential"],
"issuer": { "id": "did:key:z6Mkija7eQS9kNrvh1kAp7PJFgPEznFpBdDm825vugSQxdW7" },
"issuanceDate": "2026-05-30T02:58:42+00:00",
"expirationDate": "2027-05-30T02:58:42+00:00",
"credentialSubject": { "id": "attestix:9648678826a049b4", "risk_level": "high" },
"credentialStatus": { "type": "AttestixRevocationStatus", "revoked": false },
"proof": {
"type": "Ed25519Signature2020",
"proofValue": "AD7KznyeJv8xr9G9R4mKAyL0MZCkvM7wrghxP6yFxpyzvEUyRhh96jtDNFTzXjy8L1v4alN3GBk-5HJvytpuCw=="
}
}
第三步:调用外部验证接口
verify_credential_external 专为"凭证不在本地存储中"的外部验证者设计:
import json
from attestix.services.credential_service import CredentialService
with open("credential.json") as f:
vc = json.load(f)
result = CredentialService().verify_credential_external(vc)
print(result["valid"], result["checks"])
返回的 checks 包含 structure_valid、not_revoked、not_expired、signature_valid 四项。⚠️ 注意:本地没有吊销名单时,not_revoked 会被假设为 true——如果你的场景在乎吊销,需要另行确认吊销状态。
拿到 valid: True 意味着密码学意义上:签发方在签署时刻确实持有该私钥,且凭证未被改动。若供应商发来的是打包多张凭证的 Verifiable Presentation,则用 verify_presentation(attestix/services/credential_service.py)一次验完 VP 签名与内嵌每张凭证,并检查 holder 与各 credentialSubject 是否匹配。
CLI 场景可用 attestix credential --verify-cred <urn:uuid:xxx> --json,非法时退出码为 1,方便接入 CI/CD 门禁(见 attestix/cli.py)。不想写代码的话,也可以把 JSON 粘贴到官方浏览器验证页——验证完全在本地浏览器完成,凭证不上传服务器(实现见 website/src/app/(marketing)/verify/verify-client.tsx/verify/verify-client.tsx))。
⚠️ 新手最常踩的 5 个坑
- 套用严格的 RFC 8785 库:Attestix 做的是 NFC 归一化而 RFC 8785 不做;浮点格式化也不同。先跑
canon-001向量再谈其他。 - base64url 去掉 padding:VC 的
proofValue是带 padding 的 base64url;而 UCAN 授权 JWT 按 JWT 规范使用不带 padding 的 base64url。两者别混。 - 把
proof/credentialStatus也纳入签名域:这两个字段是刻意排除的可变字段,纳入就会验签失败。 - 信任
verificationMethod而非issuer.id:公钥必须从issuer.id(信任锚)解码,proof.verificationMethod只是声明字段,指向别处应判失败。 - 签名通过 ≠ 一切合规:离线验证无法确认实时吊销,也不等于对签发方身份与权限的背书;授权(delegation)链的越权检查是独立一环。
🔗 延伸:审计链与授权链的离线验证
- 审计链:Article 12 审计轨迹是 SHA-256 哈希链,每条记录链接上一条(规则:
SHA-256("{prev_hash}:{canonical_json}"),canonical_json 剔除prev_hash/chain_hash/signature字段)。篡改或重排任意一行,重算哈希都会指向第一处断裂的索引。完整可运行脚本见 website/content/docs/guides/offline-verify.mdx,审计事件定义见 attestix/audit/events.py。 - 授权链(UCAN):授权不是 JCS 签名,而是 EdDSA JWT;子级能力(
att)必须是父级的子集,越权即拒绝,循环jti会被识别。对应 attestix/services/delegation_service.py 与向量ucan-chain-escalation-002。 - MCP 工具:Agent 框架侧可用 attestix/tools/credential_tools.py 暴露的
verify_credential_external工具完成同样动作。
📚 参考资料
| 资料 | 路径 |
|---|---|
| 离线验证完整演练 | website/content/docs/guides/offline-verify.mdx |
| 规范化规范(字节级) | spec/verify/v1/README.md |
| 一致性向量与判词 | spec/verify/v1/CONFORMANCE.md |
| 向量数据(7 条) | spec/verify/v1/vectors.json |
| 密码学原语(Ed25519/did:key) | attestix/auth/crypto.py |
| 凭证验证服务 | attestix/services/credential_service.py |
| 示例凭证(合法/篡改) | website/src/lib/samples/sample-valid-vc.json / sample-tampered-vc.json |
记住核心心法:一次签发,随处验证——信任数学,而不是供应商。 当你需要为自家团队或 Agent 平台编写验证器时,先让规范化器通过 canon-001,其余步骤就是照着向量表逐项打勾而已。