安全模型¶

LedgerFlow 的安全模型建立在密码学绑定、类型化约束和时间绑定权限之上。 每个授权决策都是确定性的、无需网络调用即可验证， 并产生防篡改审计轨迹。

核心安全属性¶

重放保护¶

重放保护结合新鲜性和幂等性。

新鲜性¶

• created_at_ms 必须在 60 秒验证窗口内
• 窗口外 → 拒绝为过期或预设日期

基于 Nonce 的重放检测¶

验证器使用原子插入存储 challenge_id + nonce：

SET challenge_id:nonce 1 PX 300000 NX

键已存在 → 拒绝为重放。

幂等重试¶

相同 x402 请求使用相同支付标识符重试：

• 返回缓存的先前结果（成功或失败）
• 不重新验证或重新结算

相同 nonce 出现在不同 request_hash 或 accepted_hash 中：

• 立即拒绝为重放

签名验证¶

授权令签名¶

授权令签名覆盖授权令信封的规范签名字节：

ED25519_VERIFY(
    issuer.public_key,
    SHA256(canonical_warrant_bytes),
    warrant.signature
)

证明签名¶

证明签名覆盖证明原像：

ED25519_VERIFY(
    subject_signer.public_key,
    SHA256(CBOR(proof_preimage)),
    proof.signature
)

两者都必须通过。任一失败都会拒绝授权。

威胁模型¶

防护的威胁¶

超出范围¶

撤销¶

LedgerFlow v1 使用简单撤销模型：

• 短期授权令 — 默认 TTL 7 天、上限 90 天，PoP 新鲜性窗口仅 60 秒，缩小撤销窗口
• 授权令 ID 黑名单 — 发行者可以发布撤销的授权令 ID 列表
• 商户端缓存 — 商户可以本地检查撤销的授权令 ID

v1 没有实时撤销机制， 这是个已知限制。 发行者密钥泄露的话， 只能等授权令自然过期（最长 90 天）。

未来：一致性令牌¶

v2 可能引入受 Zanzibar Zookies 或 SpiceDB ZedTokens 启发的新鲜性令牌：

• 发行者发布带有一致性令牌的撤销快照
• 验证器在授权决策中包含令牌
• 保证跨分布式状态的新鲜性

这明确是 v2 扩展，不是 v1 要求。

密钥管理¶

签名密钥轮换¶

• 定期轮换签名密钥
• 旧授权令在过期前仍然有效（短期 TTL）
• 自然过期不需要撤销

发行者密钥安全¶

• 发行者密钥应存储在安全飞地或 HSM 中
• 永远不要把发行者密钥嵌入代理代码
• 不同委托级别用不同密钥

实现陷阱¶

应该做¶

• 使用确定性 CBOR 进行规范编码
• 验证证明绑定到 accepted_hash 和 request_hash
• 使用原子 nonce 插入（永远不要检查后设置）
• 签名链 + PoP + 无状态约束保持本地验证；撤销检查走在线 RevocationStore（生产持久化）
• 任何验证错误时关闭失败

不应该做¶

• 仅按签名者缓存（使用 warrant_digest）
• 接受 expires_at 超过 90 天的授权令
• 为"受信任"代理跳过重放保护
• 委托期间允许约束扩展
• 使用非规范序列化进行摘要计算

参见¶

• 协议 — 线路格式和证明模型
• 约束模型 — 约束如何执行权限边界
• 结算架构 — 结算验证