Merge pull request '#163' from docs/151-machine-identity-acceptance

docs: 同步 #151 机器身份与安全传输 v1
2026-08-31 11:24:10 +08:00
parent 06e0790f00 ae9bd015c2
commit cf00d73436
5 changed files with 86 additions and 10 deletions
@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Architecture-and-Code-Map
 wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Architecture-and-Code-Map.-
-wiki_revision: 812e822990d8c8e82445bd19ced67aca8c10aba4
-synchronized_at: 2026-08-31T01:58:55Z
+wiki_revision: 41c2193b2f1edb37abe1e8994d65d02207549039
+synchronized_at: 2026-08-31T03:18:12Z
 <!-- gitea-wiki-mirror:end -->

 # 架构与代码地图
@@ -344,3 +344,13 @@ Brain internal candidate / Sense local event

 Brain candidate、Sense candidate/Outbox 与 Bell Event/Receipt/Alert 继续是各自内部模型。当前没有新增可运行的跨端 ingress/relay，不能把冻结 Schema 解释为端到端链路已完成。
 <!-- standard-event-evidence-v1:end -->
+
+<!-- machine-identity-v1:start -->
+## 三项目机器身份与安全传输 v1
+
+工单 #151 已于 2026-08-31 验收并通过 PR #162 合入 `dev`。共享事实源为 `contracts/machine-identity/v1/**` 与 `contracts/transport/v1/**`；Sense、Brain、Bell 分别在自己的 `integration/machine_identity/` 中保留独立适配，不共享用户、JWT、Cookie、Casbin、数据库或业务实现。
+
+v1 使用 HTTPS 上的 Ed25519 短期请求绑定 JWS。每个部署实例拥有独立 principal、`kid` 和仓库外私钥；消费者使用本地外部公钥注册表，按精确 audience 与最小 scope 授权。令牌绑定 HTTP 方法、规范化路径和正文 SHA-256，有效期最多 300 秒、时钟偏差最多 30 秒，并以 `(principal,jti)` 原子防重放。TLS 最低 1.2，证书链与主机名验证不可关闭。
+
+Sense/Bell 使用 Go 标准库 Ed25519，Brain 冻结 `cryptography==50.0.1`。固定跨语言向量证明 Go/Python 可互相验签。#151 只提供身份、注册表、传输策略及可注入 replay 接口；#152/#153 才注册业务 endpoint，并必须使用各产品独立的持久原子 replay store验证重启，不能共享数据库。
+<!-- machine-identity-v1:end -->
@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Business-Rules-and-Glossary
 wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Business-Rules-and-Glossary.-
-wiki_revision: bc4a1a7be268028fa85717b71f48f7dd75cc7e52
-synchronized_at: 2026-08-31T01:59:04Z
+wiki_revision: 7a91edf3ca35ade3e254937c4a68b53d816a3eea
+synchronized_at: 2026-08-31T03:18:24Z
 <!-- gitea-wiki-mirror:end -->

 # 业务规则与术语
@@ -262,3 +262,15 @@ synchronized_at: 2026-08-31T01:59:04Z
 - **Bell 所有权**：Bell 独占内部 Event/Receipt、规则、Alert、ack、close、通知与用户审计；上游不得写入这些状态。
 - **兼容与回退**：未知主版本终止接收但保留已有事实；破坏性变化发布新主版本。回退停用新生产者版本，不删除 Outbox、Receipt、Event 或审计。
 <!-- standard-event-evidence-v1:end -->
+
+<!-- machine-identity-v1:start -->
+## 机器身份、权限和重放规则
+
+- 机器 principal 格式为 `yv:<sense|brain|bell>:<instance>`，每个产品实例独立；不得替代、携带或映射 Sense/Bell 用户身份。
+- v1 audience 只允许 `yovision-sense`、`yovision-brain`、`yovision-bell`；scope 只允许 `source-config:write`、`runtime-status:write`、`events:ingest`、`evidence:read`，没有通配符。
+- 机器令牌只能从 Authorization Bearer 读取，不接受管理员密码、浏览器 JWT/Cookie、query token、共享 secret 或其他产品用户身份。
+- 相同 `(principal,jti)` 只能成功一次；传输重试必须签发新令牌和 jti，但业务幂等键与载荷保持不变。
+- 私钥只存在于仓库外受操作系统保护的文件或秘密存储；运行配置只引用路径。公钥注册表属于各消费者本地配置，不是共享数据库。
+- 轮换先登记新 `kid`，最多并存 24 小时，切换后移除旧 key；禁用 principal 或吊销 `kid` 对每次请求即时生效。
+- 回退只能关闭 connector 并恢复三端独立运行，不得降级为明文、共享管理员身份、共享 JWT 或跳过签名/TLS 验证。
+<!-- machine-identity-v1:end -->
@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Local-Development-and-Verification
 wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Local-Development-and-Verification.-
-wiki_revision: d11757b202117e028878802e1e8a9ba9df1a8e89
-synchronized_at: 2026-08-31T01:59:13Z
+wiki_revision: 771fdd92eb03e9dff7d3ae20b7cb89f1ca288959
+synchronized_at: 2026-08-31T03:18:34Z
 <!-- gitea-wiki-mirror:end -->

 # 本地开发与验证
@@ -679,3 +679,30 @@ git diff --check

 这些测试只验证冻结契约，不验证 #153 产品 mapper/relay/ingress、#151 机器身份、实际证据存储/授权、网络断线补投或跨项目 E2E。
 <!-- standard-event-evidence-v1:end -->
+
+<!-- machine-identity-v1:start -->
+## 机器身份与安全传输 v1 验证
+
+从仓库根目录执行隔离契约测试：
+
+```powershell
+pwsh -NoProfile -File contracts/tests/machine-identity-v1/run.ps1
+```
+
+脚本在系统临时目录建立虚拟环境，按固定 `cryptography==50.0.1` 和 `jsonschema==4.25.1` 验证封闭 Schema、Go/Python 固定 Ed25519 向量、请求绑定、Bearer-only、错 audience/scope、过期、重放、轮换、吊销和 TLS policy，结束后删除所属临时目录。
+
+三端定向验证：
+
+```powershell
+cd Sense/server
+go test -race ./app/sense/integration/machine_identity
+
+cd ../../Bell/server
+go test -race ./app/bell/integration/machine_identity
+
+cd ../..
+Brain\.venv\Scripts\python.exe contracts\tests\machine-identity-v1\test_contract.py
+```
+
+这些测试只证明 #151 身份和传输基础。真实客户 PKI/网络、现场时钟漂移、业务 endpoint、断网补投以及持久 replay 重启恢复由 #152/#153/#155 验证；不得用进程内 replay store替代生产结论。
+<!-- machine-identity-v1:end -->
@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Troubleshooting
 wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Troubleshooting
-wiki_revision: 046624c1b2d7963ef733b4c9687d5dec14771388
-synchronized_at: 2026-08-27T09:05:32Z
+wiki_revision: 75bf70f375f58356e968b45139b54fcae391d1e8
+synchronized_at: 2026-08-31T03:18:53Z
 <!-- gitea-wiki-mirror:end -->

 # 故障排查
@@ -161,3 +161,18 @@ synchronized_at: 2026-08-27T09:05:32Z
 3. 若同步提示本地镜像有未提交修改，先核对改动归属并停止覆盖。
 4. Wiki 页面缺失、没有 revision、MCP/API 凭据不可用或映射准备删除/重命名时停止，由工单确认后处理。
 5. PowerShell 显示乱码时先区分文件编码和控制台输出编码，不默认另起 PowerShell 或使用 `-ExecutionPolicy Bypass`。
+
+<!-- machine-identity-v1:start -->
+## 机器身份 v1 排错
+
+| 现象/错误码 | 常见原因 | 检查 | 安全处理 |
+|---|---|---|---|
+| `machine_token_missing` | 未使用 Authorization Bearer 或格式错误 | 检查 connector 配置，不粘贴令牌 | 修复调用方；不改用 Cookie/query token |
+| `machine_token_invalid` | 签名、kid、请求方法/路径/正文摘要或封闭字段不匹配 | 核对版本、kid 和请求绑定 | 停止重试，修复配置/实现 |
+| `machine_token_expired` | 时钟偏差或令牌超过 5 分钟 | 检查双方 UTC 时钟 | 校时并签发新令牌，不延长长期 token |
+| `machine_audience_denied` / `machine_scope_denied` | 目标产品或最小权限不匹配 | 核对公钥注册表和调用方向 | 修正精确授权，不添加通配符 |
+| `machine_identity_revoked` | principal/key 已禁用或吊销 | 核对当前 kid 与轮换状态 | 切换已批准新 key；不得恢复旧 key绕过吊销 |
+| `machine_token_replayed` | 同一 jti 被再次使用 | 检查重试是否重新签名 | 新建 jti，保留业务幂等键 |
+
+排错日志只记录稳定错误码、已认证 principal/kid 和 correlation ID；不得记录令牌、签名、密钥、完整 Authorization header 或秘密路径。无法安全恢复时关闭 connector，三端保持独立运行。
+<!-- machine-identity-v1:end -->
@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Deployment-and-Operations
 wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Deployment-and-Operations.-
-wiki_revision: 0a772b0511044d98430ebd93304faa3dee57183d
-synchronized_at: 2026-08-31T01:39:35Z
+wiki_revision: 54d720aa07d2c40684da3fc04378393c7f318a04
+synchronized_at: 2026-08-31T03:20:15Z
 <!-- gitea-wiki-mirror:end -->

 # YoVision 部署与运维
@@ -142,3 +142,15 @@ Sense\start_sense.bat

 因此现阶段部署仍按 Sense、Brain 各自独立入口进行，不得手工共享数据库、用户 JWT/Cookie、摄像头凭据、文件目录或临时 JSON 字段来提前打通。需要停用或回退时保持两端独立运行，并保留上一已确认的配置与最后已知状态；未知协议主版本必须停止摄取而不是覆盖投影。
 <!-- sense-brain-contracts-v1:end -->
+
+<!-- machine-identity-v1:start -->
+## 机器身份部署与轮换边界
+
+#151 已冻结机器身份和传输基础，但 #152/#153 尚未注册业务 connector，因此当前不得手工拼接 endpoint 或临时共享凭据提前打通。
+
+部署时为每个调用实例独立生成 Ed25519 私钥，保存到仓库外受 ACL/秘密存储保护的位置；产品配置只记录私钥路径、principal、kid、目标 audience 和最小 scope。消费者从仓库外公钥注册表读取受信 principal/kid。不得把私钥、完整令牌、Authorization header、管理员密码、浏览器 JWT/Cookie 或 query token写入配置样例、日志、工单和备份。
+
+传输固定使用 HTTPS，TLS 最低 1.2并验证证书链与主机名。轮换按“先登记新公钥 → 调用方切换新 kid → 验证流量 → 24 小时内移除旧 key”执行；应急吊销直接禁用 principal 或 key，并同时停用相关 connector。回退保持 Sense、Brain、Bell 独立运行，保留 Outbox、Receipt、Event 和最后已知状态。
+
+#152/#153 必须为各产品注入自己的持久原子 `(principal,jti)` replay store并验证重启；内存 replay store 只用于适配测试或不重启的单进程原语。
+<!-- machine-identity-v1:end -->