# 安全模型

BinSchema 面向不可信二进制输入，但不是隔离恶意代码的沙箱。

## 已缓解的风险

- **越界读取**：所有读取在移动游标前检查剩余长度。
- **资源放大**：输入、输出、集合长度、嵌套深度和诊断轨迹数量均有可配置上限；长度/输出预算在大分配前检查。通用 `IncrementalDecoder` 仍属于 buffered/retry parser，小 chunk 高频 `poll()` 会重复解析，调用方应批量 `append()` 或收紧输入边界。
- **整数转换**：32 位无符号长度在转为运行时 `Int` 前验证范围。
- **截断与尾随数据**：分别产生 `UnexpectedEof` 与 `TrailingBytes`。
- **结构混淆**：magic、枚举值、条件字段和长度边界由 codec 验证。
- **完整性错误**：PNG 示例验证每个 chunk 的 CRC32。
- **日志放大**：字节字段的轨迹值只保留前 32 字节预览。
- **结构化对抗输入**：CI 会从有效 PNG/WAVE/PCAP/ISO BMFF/DNS 样本的字段轨迹出发，系统测试字段边界截断、长度字段膨胀、CRC 损坏与字段首字节翻转，要求所有后端只产生成功解析或结构化错误。
- **DNS 压缩指针**：pointer 只能指向当前报文区域内更早的 offset，跳转链受 `max_depth` 限制；section count、label 数量和展开域名长度都在循环/复制前检查。

## 默认限制

| 限制 | 默认值 |
|---|---:|
| 最大输入 | 64 MiB |
| 最大输出 | 64 MiB |
| 最大集合长度 | 1,000,000 |
| 最大嵌套深度 | 64 |
| 最大轨迹条目 | 100,000 |

调用方可通过 `Limits::new(...)` 与 `DecodeOptions` / `EncodeOptions` 收紧限制。轨迹条目达到上限时会返回 `LimitExceeded`，避免大量具名字段放大诊断内存。处理网络输入时，应根据实际协议设置远小于默认值的边界。

## 报告问题

请不要在公开 issue 中附带敏感数据或真实流量文件。提交最小化的合成样例，并说明 MoonBit 工具链版本、后端与期望行为。

## 结构化 mutation 测试

BinSchema 不依赖不可复现的纯随机测试来承担核心安全回归。仓库会先解析有效样本，利用 `TraceEntry` 的 `[start, end)` 字节范围和 Schema 约束生成确定性 mutation：在字段边界及字段内部截断输入、将分配相关长度字段扩张到极端值、破坏 PNG CRC，以及翻转每个具名字段的首字节。Wasm、Wasm-GC、JavaScript、Native 四后端运行同一组 mutation，用于验证边界检查、资源限制和错误路径不会因后端不同而失效。

这些测试不是完整的模糊测试替代品；它们提供稳定的安全回归基线。后续若接入持续 fuzzing，应保留这些确定性用例作为 CI 中可快速复现的最小集合。