# P3-WP04 边缘网关与数据不出域

## 结论

P3-WP04 已形成可测试的企业边缘工程基线，状态为
`ENGINEERING_COMPLETE_ENTERPRISE_EDGE_UAT_BLOCKED`。这不是生产就绪声明：
`enterprise_source_1`、`enterprise_source_2`、`network`、`security_legal`
仍为 `TBD_EXTERNAL`，真实来源、企业网络区、出站规则和安全法务签字尚未完成。

## 架构与信任边界

```text
平台人员 --RBAC--> 控制面/API/PostgreSQL(head 479)
                           | Ed25519签名任务/发布
                           v
企业边缘 --仅主动HTTPS+mTLS拉取--> 受信mTLS反向代理/控制面
   | SQLite离线队列、Runner、artifact/release本地存储
   +-- 企业来源采集/画像/质量/血缘/受控查询
   +-- 仅批准事件摘要出域；raw/recent_detail/restricted不出域
```

身份由 gateway ID、environment、network zone、generation、证书 SHA-256、
credential hash 和 policy digest 共同绑定。注册令牌一次性且只保存 hash；edge
credential 只返回一次，控制面只保存 hash；mTLS 终止只信任配置的代理地址及其
`SUCCESS` 证明，并从真实证书计算指纹。CRL、企业 CA 和出站防火墙属于外部网络门禁。

任务与发布由控制面 Ed25519 权威签名。签名材料在 PostgreSQL 中受 append-only、
generation、active-key 和数据库角色约束；生产禁止 inline private key。边缘验证
key-id、完整绑定、有效期、digest 和签名后才入队。服务端 signing key、edge 私钥、
credential 或 lease 均不得进入诊断、事件或 OpenAPI 普通响应正文。

## 功能闭环

1. 严格 Task/Event contract，未知字段拒绝；操作只允许 collect/profile/quality/lineage/controlled_query。
2. 默认拒绝的出站策略和数据分级：原始数据、近期明细与 restricted 留在边缘；仅脱敏元数据、统计、血缘、证据、健康/诊断摘要进入控制面。
3. SQLite durable queue 支持幂等、lease fencing、断网、重连、取消、重试、稳定 event ID 和 exact ACK replay。
4. PostgreSQL 控制面覆盖 enrollment、gateway、credential、task、event、release 和审计；迁移 head 479，应用角色最小权限。
5. pull-only agent 在企业内调用封闭 Runner adapter；任意 URL、SQL、命令、路径和未批准 node 均不能由控制面注入。
6. Nginx mTLS 契约验证可信代理、证书链、CRL、证书指纹及未认证拒绝；Compose 不暴露入站端口。
7. 安装/CSR/注册材料/轮换/撤销状态/签名发布验证/原子回滚工具实行绝对路径、符号链接拒绝、0600/0700、运行 UID/GID 绑定和有界备份；注册固定写入 `registration/registration.json`，且只含无秘密 digest/公钥/CA/CRL 绑定。
8. 可运行 Edge 镜像实际消费闭合 `edge.json`、credential 文件、client cert/key、CA、server CRL 和 task/release 公钥，执行无入站监听的 heartbeat/reconcile/pull 循环；内置 Runner 只接受签名的 `quality-evaluation` 工程自检并形成 `evidence` 事件，其他来源任务默认拒绝。server CRL 原子替换后会重建 TLS 连接池，过期、验签失败或命中已撤销服务端证书即 fail-stop；断网进入有界 degraded，SIGTERM 原子写 stopped health 后退出。企业来源 Runner handler 仍为 `TBD_EXTERNAL`。

## 数据和保留边界

| 分类 | 位置 | 控制面允许 | 保留边界 |
|---|---|---|---|
| raw/restricted | 边缘 artifact | 否 | 企业批准周期；到期可验证删除 |
| recent_detail | 边缘 artifact | 否 | 工程上限 365 天，企业可更短 |
| desensitized_metadata/statistics/lineage/evidence | 边缘 queue 与控制面 | 是，策略校验后 | 按批准的数据合同和审计周期 |
| health_summary/diagnostic_summary | 边缘 queue 与控制面 | 是，有界字段 | 按运维证据周期，禁止秘密/样本 |

## 运维、安全和迁移约束

- exact HTTPS control/proxy origins；企业侧以防火墙验证实际出站，应用策略不能替代网络控制。
- queue、artifact、release、secret/cert 分离；客户端 key 固定为 `secrets/client.key`，整个 secrets 与 cert/signing key mounts 只读，queue/artifact/release 可写；初始化 UID/GID 与 Compose runtime UID/GID 必须一致。
- 日志有界且脱敏；安全事故只记录 code、digest、计数、时间和版本。
- 证书轮换先 pending CSR、服务端批准再切换；撤销状态必须验证绑定 gateway/generation/cert/time/key-id 的 canonical Ed25519 envelope；撤销后本地停机且为终态，不允许本地解除。
- 发布检查将完整 Ed25519 manifest、artifact 和 bundle 记录原子归档到 `releases/verified/<manifest_digest>/`；回滚重新验签 current/target 及 artifact SHA-256，验证 deadline、版本、rollback binding、basename 后才原子提交 current 指针，使用 intent/history 识别 fsync 崩溃恢复。伪造 verified JSON、验后篡改、replay/降级/路径穿越均失败。
- v1→v2 queue 必须 drain gate、备份、副本迁移、兼容与恢复验证，不能在线原地强迁。
- 当前本地 queue schema 为 v2；只读 `status` 提供 task/event/outcome/artifact cleanup/release 水位、lease、schema 和 rollback intent 状态，不输出路径或秘密。retention 清理由 legal hold、delete receipt 和 ACK 约束。
- 数据库迁移由 migration owner 执行；应用 role 不得操作签名 authority 表和密钥轮换函数。

## 验收边界

本地工程验收覆盖恶意输入、重放、高敏出域、断网/重连、取消、发布/回滚、证书链/CRL、
真实 PostgreSQL、真实容器镜像配置和角色最小权限。未执行全量仓库回归，符合只验证受影响功能的约束。

企业 UAT 仍需：两个批准来源完成采集/质量/受控查询；批准网络区真实部署；抓包与网关审计证明未经批准原始数据出域为 0；网络和安全法务负责人签字；备份/恢复、证书轮换/撤销与升级/回滚在企业拓扑演练。完成前不得把本工作包标为生产就绪。

详细命令见 `docs/runbooks/EDGE_GATEWAY_OPERATIONS.md`，证据见
`docs/validation/P3_WP04_EDGE_GATEWAY_EVIDENCE.md`，故障注入台账见
`docs/validation/P3_WP04_FAILURE_INJECTION.json`。