# 开发故事｜从原始字节到可复核结论

MoonPasskey Lab 的开发围绕一个具体目标推进：让开发者看清 Passkey 响应中有哪些数据、执行过哪些检查，以及一次失败发生在哪里。项目先建立 MoonBit 的 Base64URL、ByteReader 和有界 CBOR，再逐层加入协议结构、公钥参数、密码学与 RP 策略，最后通过 CLI、参考 RP 和 Dashboard 连接真实浏览器。

选择 MoonBit 对应两项工程目标。枚举和显式结果类型可以表达解析失败、未执行验证和验证成功的边界；同一份核心源码可以在 native、JavaScript、wasm 和 wasm-gc 上检查与测试。项目逐步把规则放入可复用包，再通过固定的 JSON 契约接入宿主，使 CLI 与网页能够共用实现。

## 先定义检查的边界

开发没有把所有成功都压成一个“已验证”。ClientDataJSON 解析保留输入原文与范围；ES256 参数检查仍明确标记公钥点检查尚未执行；点导入成功后才能取得验证后的公钥类型。Assertion 入口再组合 challenge、origin、RP ID、身份、flags、签名和计数器判断。

这一分层决定了报告的表达方式：结构可解析、签名有效、策略通过和 attestation 信任是不同结论。未实现或未执行的检查必须留在结果中，不能通过界面措辞补成成功。

## 一次需要维护者决定的标准取舍

早期任务要求 Assertion 接收 raw64，而 WebAuthn 的 ES256 wire 签名使用 ASN.1 DER。维护者明确选择按标准提供 DER Assertion 入口，同时保留通用 raw64 ECDSA 入口。适配层严格检查 DER 结构与标量范围，再调用固定 MoonCrypt 后端；回归测试覆盖截断、非最短编码、负数、冗余零、尾随内容和原始规范签名。

这项决定让浏览器返回的 DER 签名可以直接进入 Assertion 验证，也保留了两个入口各自的格式契约。[原始决策与验收](../../docs/DEVELOPMENT.md#项目集成与最终验收)

## AI 参与了什么，证据如何产生

AI 编码助手参与标准与本地 API 核验、后端候选比较、代码和测试编写、静态审阅以及文档整理。维护者提供阶段目标、授权边界和关键取舍，最终接受由维护者负责。AI 代理之间的审阅属于项目内部的自动化审阅，不能写作独立安全审计或人工审查记录。

几个实际修正说明了这条边界的必要性：

- 密码学依赖公开问题显示，部分非规范坐标可能被后端接受。项目保留导入前的严格坐标域范围检查，并加入 `x=p` 回归；没有宣称上游问题已被本项目修复。
- 集成审阅发现 CLI 文件解码可能损失原始字节，改为读取 Bytes 后严格 UTF-8 解码，并补充非法输入回归。
- 参考 RP 用实际编译 Core 和 SQLite 多连接测试挑战唯一提交、版本冲突后的重新验证及计数器策略；报告版本化后，历史文件缺失的事务字段继续记为未知。

测试采用项目合成样本及带来源、许可的 W3C、NIST、Wycheproof 数据，部分向量另经 OpenSSL 核对。原始向量、合成输入和真实设备报告分别记录。[完整开发记录](../../docs/DEVELOPMENT.md)

## 浏览器实验由人完成

2026-11-12，维护者选择 Safari 与 iCloud Keychain / 平台 Passkey，并亲自完成系统注册和认证。实际 Dashboard 脱敏导出显示 ES256/P-256、DER 签名和 Core 12 项检查通过。请求策略是 UV preferred，实际 UV=true，signCount 为 0→0。

这份记录证明该历史流程成功，不能用来推断 required 策略、iOS、Chrome 或计数器递增已经验收。Provider 标签来自维护者选择，未通过协议字段独立识别。原始脱敏文件保留不变，新报告格式通过 sidecar 说明来源。[真实设备与历史报告](../../docs/ASSERTION-INTEROP.md)

## 交付停在可复核的范围内

当前已有验收记录汇总为 631 个独立用例：原有 581 项与部署 50 个独立叶用例。四目标执行次数不增加独立用例数，部署 Node 输出的父测试也不重复计数。Ubuntu 22.04 隔离虚拟机完成了实际 Nginx 与合成 TLS 测试，真实服务器与公网 HTTPS 尚未部署验收。

本次提交整理采用功能冻结，只完善申报入口、说明与演示材料。下一步仍需维护者完成新设备流程和部署验证，并接受独立审查。项目可复用的成果，是 MoonBit 协议模块、共用分析接口、参考宿主和带来源的验证记录；后续能力按实际完成情况追加。[当前限制](LIMITATIONS.md) · [部署记录](../../deploy/ubuntu-nginx/VALIDATION.md)