Files
ecs-relay-service/deployable/CREDENTIAL_PROTOCOL_V2.md
ex_tianzy d1ab834ecb 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.
2026-11-04 11:43:53 +08:00

104 lines
9.6 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 集中凭据协议 v2:阶段3接口指导
日期:2026-11-04。本文是已经完成本地开发测试的服务端接口契约,不表示现机已启用或新客户端已交付。产品经理决定权限集合;本文件不替产品选择具体业务或Scope。阶段4的解绑、内部准入和WSS扩展见[连接与任务生命周期](BINDING_TASK_LIFECYCLE.md)。
## 1. 启用与模式边界
Settings新增以下配置,环境变量均以`HN_`开头:
| 配置 | 默认值/要求 |
| --- | --- |
| `CREDENTIAL_MODE` | 默认`legacy`;显式`broker`才启用新模式 |
| `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回调精确登记 |
密钥不在本文或客户端配置中生成/分发。当前Compose及初始化工具尚未完成这些新参数、密钥挂载和权限集合的正式部署接线(阶段5)。不能仅在旧settings.env中增加变量就认定容器已经启用broker,也不要自行在生产切换。
私有化平台端点按历史实测和现场配置复核:`/open-apis/authen/v1/index`曾成功授权,v1 OIDC曾成功换码/刷新;不要默认沿用公网域名或自动切换agent-hub的v3协议。
| 模式 | OAuth与凭据接口 | 旧业务代理 |
| --- | --- | --- |
| legacy | 继续原OAuth start/claim/refresh行为,v2路由不存在 | 保留`/work/api` |
| broker | 注册本文v2路由和新`/oauth/cb`;旧`/oauth/start`、`claim`、`pending`、`refresh`不注册 | 不注册`/work/api` |
现有消息接收、回复、通知和设备注册/绑定仍保留。旧客户端不能在broker模式继续使用原凭据协议,切换需要协调升级与新授权;不会按某次请求失败自动退回旧刷新。
## 2. 设备证明与绑定版本
所有`/work/v2/*`接口均为POST,JSON禁止额外字段。基础字段:
| 字段 | 要求 |
| --- | --- |
| `host_id` | 当前注册设备,32位小写十六进制 |
| `binding_owner` | 本机绑定回执中的用户声明,必须与ECS当前绑定一致;不是可自选收件人或凭据用户 |
| `binding_generation` | 当前绑定版本,非负整数,禁止字符串、bool;只有status可显式为null引导同步 |
| `request_id` | 8–100字符,字母数字下划线短横线;授权发起可用稳定ID重取同一事务 |
| `proof` | 以下内容的设备私钥签名信封,签名编码沿用现有`crypto.sign`协议 |
proof正文包含`version=2`(严格整数)、`environment`、`app_id`、`host_id`、`purpose="work-v2"`、`method="POST"`、实际`path`、`ts`、32位十六进制`nonce`、`payload_hash`。environment和app_id必须匹配目标ECS部署,后续客户端公开发布配置提供这两项,不能在多个环境盲目复用签名。payload_hash为去掉顶层proof之后,**完整模型字段**经过现有`crypto.canonical`规范化后的SHA256,包括owner、generation、request_id及接口附加字段。status的generation使用null时也必须纳入签名正文。
规范化沿用现有UTF-8 JSON:键排序、紧凑分隔符、不做ASCII转义。时间窗口90秒,nonce一次性记录180秒;重发HTTP使用新nonce,业务request_id可保持。path被签名,因此不能把一个接口的证明转用到另一个接口。
服务端依次核对当前绑定/吊销、设备证书/签名、时间和nonce、请求路径与摘要;Redis等待后再次核对绑定。IP和设备有独立限流。请求/校验错误不回显输入值,Token响应及普通错误响应均禁止缓存。
`Store`增加`binding_generation`,原数据迁移默认0,保留设备证书、私钥、公钥和owner;新bind、unbind使版本递增,首次revoke递增。绑定回执新增该字段;已有安装可通过认证status读取当前版本,不需为此重新生成身份或重绑。
## 3. 接口
### POST /work/v2/status
仅基础字段;首次同步可令generation为null,但仍要用设备私钥证明正确binding_owner。返回当前绑定版本、协议/模式、产品权限版本名和凭据状态;不返回access/refresh。owner不符、未绑定或吊销仍拒绝。
### POST /work/v2/authorizations
增加`permission_profile`,只能使用服务器配置的产品权限版本。返回`transaction_id`、status、expires_at;waiting时返回authorization_url。事务ID格式`oauth2_`加32位十六进制,期限600秒。同request_id同请求返回同事务且不延长期限;同ID改内容拒绝。
一个应用/用户只保留一个当前待授权意图,新请求会使之前waiting/exchanging事务变为superseded;重复同ID不作此操作。数据库设备行锁串行化跨worker新授权,回调提交前重查事务,防止较早授权覆盖较新的权限意图。已存在有效凭据不会因发起新授权直接删除。
服务端保存state摘要及加密state,不保存code;Scope快照和身份/设备/版本与事务绑定。Scope由产品权限配置决定,不接受请求中的scope/open_id/refresh_token等额外参数。
### GET /oauth/cb
平台跳转带code/state或取消结果,不要求设备签名。服务端验证随机state、到期时间、密文绑定、当前设备代次和产品权限版本,并原子将waiting变为exchanging/cancelled。重复/过期回调不再次换码。
Broker换码后调用user_info核验实际授权人与原绑定一致,回写前再次验证事务/绑定;加密保存access/refresh,仅返回通用完成提示。错人、缺字段、绑定变化或事务被新请求取代时不提交旧授权。回调成功不等于产品业务已执行。
阶段3数据库共享事务允许其他connector接续未消费回调。若进程在平台换码中崩溃,exchanging不能自动重放一次性code,期限后需重新授权;不宣称平台调用exactly-once。事务容量有全局配置及用户频率限制,过期记录清理/归档在部署运维阶段完善。
### POST /work/v2/authorizations/status
增加transaction_id,必须属于当前用户/设备/绑定版本。返回waiting/exchanging/authorized/failed/cancelled/superseded/expired;成功但实际Scope不足产品集合时返回permission_update_required。状态查询不返回Token。已完成授权的终态不因等待期限过去而改称expired;过期的waiting/exchanging按expired返回。
### POST /work/v2/credentials/access-token
增加permission_profile。owner来自已验证绑定,Broker按用户加锁读取/刷新,权限不足不靠刷新补齐;绑定变化拒绝发放。
响应采用固定字段白名单:`access_token`、`token_type="Bearer"`、`expires_at`、`expires_in`、`server_time`、`credential_version`、`granted_scopes`、`app_id`。expires_in是返回时的剩余秒数,不保证每次都得到完整两小时。**任何响应均不包含refresh token、其密文或应用凭据。**
客户端默认只在内存缓存access。未来本机CredentialProvider请求本接口,不能把它注册为模型可调用的get_token工具。业务SDK拿到access后直接请求固定的私有化飞书域名,refresh留在ECS。
如果刷新时解绑,平台已经轮换的凭据仍需保存,避免丢失最新refresh;发放前重新校验绑定,拒绝把access交给已解绑设备。ECS数据库状态提交与HTTP发出之间仍存在不可消除的竞争边界,已发Bearer的即时失效仍依赖平台撤权。
### POST /device/notifications(原接口的新授权卡兼容)
legacy文本/通知卡协议不变;broker模式从阶段4起必须传当前`binding_generation`并纳入work-notify-v1签名payload。broker模式的`kind=authorization`将原`oauth_state`字段用作**transaction_id引用**,不是原始state或任意URL;ECS验证事务归属、当前绑定版本和waiting状态后从服务器生成链接。发送前再校验,不能把其他设备事务发给本人或用旧代次链接继续授权。
本人通知收件人与路由继续由ECS确定,应用Token不下发。阶段4已补当前绑定版本与旧绑定码失效、路由准入及持久补偿;客户端侧对应升级和真实部署仍需后续验证。
## 4. 错误与审计
- 401:authorization_required;403:设备/绑定/证明错误、产品权限未批准或permission_update_required。
- 409:请求nonce重放、稳定ID改内容、refresh_unknown、权限版本变化。
- 410:授权事务过期;429:限流;503:凭据/状态不可用、等待租约或容量超限。
- 回调换码/核验失败返回固定502,不回显code、state、平台错误正文或Token。
成功授权和Token发放写原有审计表,仅记录用户、设备/事务引用、凭据版本和结果。不得记录Token正文、完整授权URL或请求头。
## 5. 本阶段尚未完成
无实际服务器部署、真实PostgreSQL/多节点Redis验收、真实Work OAuth复测或客户端发布。阶段4新增的解绑/任务/旧绑定码补偿以对应文档和本地测试为准;凭据拒绝自动失效上报、集中刷新后台调度、运维清理和正式Compose参数挂载仍为后续工作。不要绕过新领取认证临时开放旧refresh接口。