feat(lifecycle): add stage 4 authoritative unbind and durable task routing

Unify broker-mode binding changes in database transactions: advance device
generation, invalidate pending authorizations/tasks and prior pairing-code
epochs, and persist audit plus invalidation outbox. Add authenticated device
unbind alongside robot/admin paths. Pairing codes are hashed, generation-
fenced and consumed atomically with binding.

Replay Redis invalidation effects without undoing committed unbind. Guard
online cleanup and delayed kill events by generation. Introduce a separate
router admission credential with no platform-event injection authority.
Router verifies signed nonce-bound internal admission on handshake, task
traffic and periodic checks; reject stale sessions and control-plane outages.

Persist task owner/device/generation/session/worker and original message
mapping. Sign routing metadata, verify late results, claim replies once and
mark ambiguous/crashed tasks unknown instead of replaying writes. Fence
notifications across same-user rebind. Release in-memory slots/waiters even
when database or Redis cleanup fails.

Validation: 213 passed, 3 skipped (real PostgreSQL not configured), 30 existing
uvicorn/websockets deprecation warnings. New lifecycle coverage: 28 tests,
including real loopback WebSocket isolation, reverse completion, missed kill,
periodic unbind checks, outbox recovery, transaction rollback and cleanup
failures. Syntax, docs and staged diff checks pass.

Default legacy mode remains unchanged. Broker mode now requires coordinated
router admission configuration and a v2 client handshake. No production ECS
configuration, real credentials or client installer was changed. PostgreSQL,
real Redis multi-node, ARM64 and actual Work/client rollout remain stage 5.
This commit is contained in:
ex_tianzy
2026-11-04 11:43:53 +08:00
parent 93bfbca83a
commit d1ab834ecb
13 changed files with 1128 additions and 29 deletions
+5 -4
View File
@@ -1,6 +1,6 @@
# 集中凭据协议 v2:阶段3接口指导
日期:2026-11-04。本文是已经完成本地开发测试的服务端接口契约,不表示现机已启用或新客户端已交付。产品经理决定权限集合;本文件不替产品选择具体业务或Scope。
日期:2026-11-04。本文是已经完成本地开发测试的服务端接口契约,不表示现机已启用或新客户端已交付。产品经理决定权限集合;本文件不替产品选择具体业务或Scope。阶段4的解绑、内部准入和WSS扩展见[连接与任务生命周期](BINDING_TASK_LIFECYCLE.md)。
## 1. 启用与模式边界
@@ -12,6 +12,7 @@ Settings新增以下配置,环境变量均以`HN_`开头:
| `CREDENTIAL_KEYRING_FILE` | broker必须提供受控服务端密钥文件,格式见阶段1记录;无有效密钥启动失败,不回退 |
| `CREDENTIAL_PERMISSION_PROFILES` | JSON对象:产品权限版本名映射Scope字符串数组;broker不可为空,不允许客户端传任意Scope |
| `DATABASE_URL` | 生产broker必须使用PostgreSQL;SQLite仅用于本地开发和测试 |
| `ROUTER_ADMISSION_SECRET` | 阶段4新增:connector与router共用的独立内部准入凭据,不能复用事件/管理/应用Secret;需受控挂载 |
| 平台与OAuth | broker要求`FEISHU_ENABLED`和`OAUTH_ENABLED`为true,应用凭据仍只在ECS |
| 授权入口与公开URL | 固定HTTPS授权端点,不能含预设query/fragment或用户名密码;公开HTTPS回调精确登记 |
@@ -84,9 +85,9 @@ Broker换码后调用user_info核验实际授权人与原绑定一致,回写
### POST /device/notifications(原接口的新授权卡兼容)
文本/通知卡协议不变。broker模式的`kind=authorization`将原`oauth_state`字段用作**transaction_id引用**,不是原始state或任意URL;ECS验证事务归属、当前绑定版本和waiting状态后从服务器生成链接。发送前再校验,不能把其他设备事务发给本人或用旧代次链接继续授权。
legacy文本/通知卡协议不变;broker模式从阶段4起必须传当前`binding_generation`并纳入work-notify-v1签名payload。broker模式的`kind=authorization`将原`oauth_state`字段用作**transaction_id引用**,不是原始state或任意URL;ECS验证事务归属、当前绑定版本和waiting状态后从服务器生成链接。发送前再校验,不能把其他设备事务发给本人或用旧代次链接继续授权。
本人通知收件人与路由继续由ECS确定,应用Token不下发。完整通知、路由和旧绑定码失效补偿在阶段4继续完善。
本人通知收件人与路由继续由ECS确定,应用Token不下发。阶段4已补当前绑定版本与旧绑定码失效、路由准入及持久补偿;客户端侧对应升级和真实部署仍需后续验证。
## 4. 错误与审计
@@ -99,4 +100,4 @@ Broker换码后调用user_info核验实际授权人与原绑定一致,回写
## 5. 本阶段尚未完成
无实际服务器部署、真实PostgreSQL/多节点Redis验收、真实Work OAuth复测或客户端发布。完整解绑连接和任务补偿、旧绑定码作废、凭据拒绝自动失效上报、集中刷新后台调度、运维清理和正式Compose参数挂载为后续阶段。不要绕过新领取认证临时开放旧refresh接口。
无实际服务器部署、真实PostgreSQL/多节点Redis验收、真实Work OAuth复测或客户端发布。阶段4新增的解绑/任务/旧绑定码补偿以对应文档和本地测试为准;凭据拒绝自动失效上报、集中刷新后台调度、运维清理和正式Compose参数挂载仍为后续工作。不要绕过新领取认证临时开放旧refresh接口。