# MoonEvidence 安全说明

> 当前支持版本：v0.5.x
>
> 安全基线：2026-07-11 Asia/Shanghai

[架构文档](docs/ARCHITECTURE.md) · [证据包规范](docs/spec/EVIDENCE_PACK_SPEC.md) · [测试计划](docs/TEST_PLAN.md) · [侧信道审计](docs/CONST_TIME_AUDIT.md)

MoonEvidence 保护文件交付中的内容完整性、清单一致性和历史承诺。验证器把证据包视为不可信输入，重新计算文件摘要和 Merkle 根，并可对照独立保存的旧 manifest 摘要。密钥、外部锚点和运行环境由部署方管理。

## 安全模型

### 保护对象

| 对象 | 需要保持的性质 | 主要控制 |
| --- | --- | --- |
| 原始文件 | 验证时读取的字节与交付状态一致 | 逐文件摘要、只读快照 |
| `manifest.json` | 字段、顺序语义和摘要稳定 | 严格模型、RFC 8785 规范化 |
| Merkle 根 | 文件条目集合和顺序可复核 | 域分隔、奇数节点提升规则 |
| 历史 manifest 摘要 | 与当前证据包分开保存 | 归档系统、数据库或共享账本 |
| 验证报告 | 结论、错误码和路径不丢失 | 完备式检查、规范 JSON |
| Ed25519/HMAC 密钥 | 只由授权调用方持有 | 安全随机源、密钥托管、日志脱敏 |
| Fabric 锚点 | 首笔记录和提交状态可追溯 | v1 首笔保留规则、交易回执、跨组织查询 |

### 角色和输入

| 角色 | 控制的输入 | 信任级别 |
| --- | --- | --- |
| 证据提供方 | manifest、文件、证明、版本链 | 不可信 |
| 验证运行方 | 旧摘要、增量缓存、目录权限、资源限制 | 受控 |
| 密钥持有方 | Ed25519 seed、HMAC 密钥、公钥绑定 | 高信任 |
| Fabric 组织 | 身份证书、私钥、TLS 配置、背书和通道治理 | 高信任 |
| 发布维护方 | MoonBit、Node、Go 工具链和发布产物 | 受控 |

### 安全约束

1. manifest、文件、证明和版本链在进入业务结论前全部经过结构和语义检查。
2. 文件路径在文件读取前拒绝绝对路径、反斜杠、冒号、空段、`.` 和 `..`。
3. 完整验证从实际文件字节重算摘要，不接受 manifest 中的自述结果。
4. 外部旧摘要与证据包分开保存，并通过 `expected_manifest_digest` 显式回传。
5. 错误级发现决定拒绝，单个文件失败不会终止剩余检查。
6. 增量缓存只服务受控本机重复检查，正式交付执行完整验证。
7. Fabric 交易只携带规范 manifest 摘要，完整文件和本地凭据留在链下。
8. 网关同时校验 MoonBit 进程退出码和 JSON 结果，异常结果不会进入账本提交。
9. 密钥生命周期由调用环境管理，MoonEvidence 核心不持久化私钥。

完整信任边界图和组件责任位于[架构文档](docs/ARCHITECTURE.md#信任边界)。

## 支持范围

本策略覆盖 MoonBit 源码、CLI 和浏览器适配器、工具脚本、Showcase 以及 Fabric 集成。`examples/` 和 `tests/fixtures/` 保存测试与演示数据，运行时仍按不可信证据输入处理。

### 保障目标

| 目标 | MoonEvidence 提供的结果 | 配套控制 |
| --- | --- | --- |
| 内容完整性 | 定位缺失文件、字节变化和未登记文件 | 验证期间使用稳定文件快照 |
| 清单完整性 | 规范化 manifest 并重算 Merkle 根 | 固定证据包数据格式 |
| 历史一致性 | 当前 manifest 对照独立旧摘要 | 旧摘要由外部系统保护 |
| 签名验证 | Ed25519 对规范消息或审计条目验签 | 公钥身份由外部 PKI 或业务规则绑定 |
| 审计连续性 | 追加式哈希链和可选条目签名 | 操作授权和日志存储由业务系统控制 |
| 链上承诺 | Fabric 保存摘要、首笔交易 ID 和提交组织 | 联盟身份、背书、备份和监控 |
| 内容保密 | 文件和完整 manifest 保持链下 | 存储加密、传输加密和访问控制 |
| 提交顺序 | 回执记录区块和验证状态 | 法律时间由可信时钟和联盟治理提供 |
| 恶意内容治理 | 完整性结论保持可复核 | 文件类型检查、恶意代码扫描和沙箱 |

摘要适合作为公开承诺值。低熵或高度可预测的数据仍由加密和访问控制保护，避免第三方通过候选内容进行比对。

### 当前证据

| 验证层 | 当前证据 |
| --- | --- |
| 标准符合性 | RFC 8785、RFC 2104、RFC 8032、NIST SHA-256/SHA-512 样例 |
| 攻击输入 | Google Wycheproof Ed25519 150 条向量、异常 manifest 和路径矩阵 |
| 独立 oracle | 仓库维护的 Node.js 参考实现不调用 MoonBit 代码，对 Ed25519、SHA-2、HMAC、Merkle 和固定夹具执行差分检查 |
| 反向证明 | 16 个实现故障全部被现有测试捕获 |
| 多后端 | native、wasm、wasm-gc、js 使用同一核心并通过回归 |
| 进程和浏览器 | CLI 黑盒、浏览器接口冒烟、异常请求和行为性质检查 |
| 原生计时 | Windows/MSVC 三类 Ed25519 目标各 50,000 样本 |
| 真实协议 | Fabric 双组织提交、查询、重复和摘要回传实验 |

最新数字和命令记录位于 [RESULTS_LOG.md](docs/records/RESULTS_LOG.md)。标准向量、仓库内独立 oracle、随机差分、故障注入和多后端结果共同组成 v0.5.1 的工程保障基线；独立密码学审计属于高价值生产部署门禁。

### 密码学实现

- `digest` 提供纯 MoonBit SHA-256、SHA-512 和 HMAC-SHA256。
- `crypto` 实现 GF(2^255-19) 有限域、扩展坐标点运算和 RFC 8032 Ed25519。
- Ed25519 验签拒绝 `S >= l`、非规范点编码和低阶公钥。
- 标量乘使用固定 256 位迭代和条件选择，标量归约使用固定轮次的算术选择。
- 审计签名覆盖 RFC 8785 规范化后的完整条目。

[侧信道审计](docs/CONST_TIME_AUDIT.md)记录了秘密输入分类、源码分支检查和原生计时方法。当前计时结果绑定到记录中的 Windows/MSVC、CPU 和发布构建。高价值生产发布按目标工具链重新采样，并将最终机器码复核和独立密码学评审纳入认证门禁。

### 证据包和文件系统

模型层先校验清单路径，再由 CLI 组合包根目录读取文件。`moonbitlang/x/fs` 当前会跟随符号链接和 Windows 目录联接，适配层通过 32 层深度和 10,000 文件上限终止链接循环并限制遍历规模。

正式封装使用无符号链接、无目录联接的输入树，或在容器和受限文件系统根目录中运行。验证期间使用只读快照，避免文件在多次读取之间发生变化。

CLI 当前按文件完整读取字节。服务化部署在入口层限制 manifest 大小、文件数量、单文件大小、总字节数和执行时间。流式摘要接入后，这些策略继续由适配层执行。

增量验证信任上次成功结果的缓存。缓存目录使用仅当前用户可写权限，并与收到的证据包分开。外部交付、发布和上链前执行不带增量缓存的完整验证。

### 浏览器

浏览器工作台通过 Web Worker 调用发布版 MoonBit API。用户输入、签名 seed 和中间结果保留在当前页面会话中，工作台没有业务后端。

Showcase 和轻量演示使用 Web Crypto `getRandomValues` 生成 32 字节 seed。直接调用 `ed25519_keypair("{}")` 使用固定演示 seed，并在响应中返回 `demo seed used` 警告。正式调用始终显式传入安全随机 seed。

浏览器扩展、开发者工具和被注入的同源脚本可以读取页面内存。长期或高价值密钥进入外部密钥服务、硬件设备或短生命周期签名进程，网页工作台用于本地检查和交互演示。

### Fabric

Fabric 链码只接收规范 `sha256:` 或 `sha512:` manifest 摘要。业务参数和世界状态不包含文件、路径、逐文件摘要、Merkle 叶子、完整 manifest、本地证书路径、连接配置或私钥。Fabric 协议信封继续携带网络验证所需的提交者身份。

首笔锚点不可更新或删除。顺序重复返回原记录；并发首写只有在 Fabric 返回 MVCC code 11 且查询到相同锚点时才归一化。网关保存交易 ID、区块号、数值验证状态和成功标志。

Fabric 提议时间来自客户端事务头。可信时间、组织准入、CA enrollment、背书策略、ACL、节点可用性和账本备份由联盟部署策略提供。冻结合同见 [Fabric 规范](docs/spec/FABRIC_ANCHOR_SPEC.md)。

## 密钥职责

| 材料 | 责任方 | 使用规则 |
| --- | --- | --- |
| Ed25519 seed | 签名调用方 | 使用密码学安全随机源生成 32 字节，限制进程可见范围 |
| Ed25519 公钥 | 验证业务 | 通过 PKI、配置签名或受控登记绑定身份 |
| HMAC 密钥 | 消息认证调用方 | 与 Ed25519 seed 分离，独立轮换和授权 |
| Fabric 私钥和证书 | Fabric 组织 | 使用 CA、钱包或外部密钥系统托管 |
| TLS 根证书和连接配置 | Fabric 组织 | 校验服务器名称和证书链，限制文件权限 |
| 外部 manifest 摘要 | 归档或账本运营方 | 与证据包分开保存，读取过程可审计 |

密钥操作遵循以下规则：

1. 开发、测试和生产使用独立密钥域。
2. 私钥、seed、访问令牌和完整连接配置不进入 Git、证据包、链上参数或错误日志。
3. 签名输入先规范化，验签方使用相同数据格式和可信公钥。
4. 密钥轮换、撤销和身份恢复由外部 PKI 或业务登记系统完成。
5. 高价值密钥使用 KMS/HSM 或短生命周期适配器。MoonBit 和 JavaScript 托管内存不提供确定性清零保证。
6. 浏览器会话结束后丢弃临时密钥，不把演示 seed 用于长期签名。

Ed25519 签名证明持有对应 seed 的主体产生了签名。主体名称、组织身份和授权范围来自公钥登记和业务策略。

## 部署建议

### 交付级

适用于可复现归档、跨团队文件交付、CI 校验、教学研究和受控原型：

1. 从只读或冻结目录创建证据包。
2. 使用完整验证检查交付结果。
3. 把 manifest 摘要保存到独立归档位置。
4. 固定 MoonBit 版本和依赖锁文件。
5. 保留验证 JSON、命令版本和运行时间。

### 服务级

面向持续运行的内部服务增加：

1. 容器、低权限账户和专用工作目录。
2. 文件数、大小、总字节、运行时间和并发配额。
3. 无符号链接输入策略和稳定快照。
4. 密钥服务、日志脱敏、审计留存和告警。
5. 固定依赖、发布产物摘要和回滚流程。
6. 对异常输入、进程退出和 Fabric 提交失败建立监控。

### 生产认证

保护高价值资产的发布增加：

1. 独立密码学实现评审。
2. 目标 MoonBit 后端、C 编译器和机器码复核。
3. 按目标 CPU 运行原生计时实验。
4. KMS/HSM、密钥轮换和权限分离。
5. Fabric CA、ACL、背书、备份、容灾和可信时间治理。
6. 定期重跑标准向量、差分、故障注入、黑盒和真实协议实验。

发布门禁以 [CI 工作流](.github/workflows/ci.yml)、[测试治理](docs/TEST_GOVERNANCE.md)和[验收记录](docs/records/ACCEPTANCE_CHECKLIST.md)为准。

## 版本支持

| 版本 | 状态 | 安全处理 |
| --- | --- | --- |
| `main` | 开发分支 | 修复先进入评审分支并通过 required CI |
| `0.5.x` | 当前支持线 | 接收安全修复和部署建议 |
| `0.4.x` 及更早版本 | 历史版本 | 优先升级到当前支持线后复验 |

MoonEvidence 处于 1.0 前版本阶段。安全修复默认落在最新支持线，涉及证据包或进程合同变化时同步更新数据格式版本、`CHANGELOG.md` 和迁移说明。

所有版本的有效安全报告都会进入分流和影响评估。已发布修复通过 GitHub Security Advisory、Release 和 `CHANGELOG.md` 同步。

## 报告渠道

敏感安全问题通过 [GitHub Security Advisory](https://github.com/wenlittle/MoonEvidence/security/advisories/new) 私下提交。公开 Issue 只承载不含利用细节和敏感数据的问题。

报告内容建议包含：

- 受影响版本、后端和操作系统；
- 攻击者需要控制的输入；
- 最小复现步骤或测试；
- 实际结果和期望结果；
- 完整性、密钥、文件系统或账本影响；
- 已尝试的缓解方式。

处理目标：

| 阶段 | 目标 |
| --- | --- |
| 收到报告 | 7 天内确认 |
| 初步分流 | 14 天内给出影响范围和下一步 |
| 修复协作 | 与报告者约定测试、发布和披露时间 |
| 公开说明 | 修复发布后记录受影响版本、缓解措施和升级路径 |

优先级参考：

| 优先级 | 示例 |
| --- | --- |
| 紧急 | 完整验证接受被修改证据；私钥从默认交付流程泄露；路径逃逸导致任意文件读写 |
| 高 | 外部摘要对照可绕过；无效 Ed25519 签名被接受；异常 CLI 结果被网关提交 |
| 中 | 恶意本地证据包稳定耗尽资源；错误信息暴露超出预期的本地路径或元数据 |
| 低 | 不涉及敏感数据和安全结论的文档、演示或诊断呈现问题 |

收到确认前，请保留复现材料并避免在公开 Issue、讨论区或演示环境中披露利用细节。