# 集中凭据协议 v2:阶段3接口指导 日期:2026-11-04。本文是已经完成本地开发测试的服务端接口契约,不表示现机已启用或新客户端已交付。产品经理决定权限集合;本文件不替产品选择具体业务或Scope。 ## 1. 启用与模式边界 Settings新增以下配置,环境变量均以`HN_`开头: | 配置 | 默认值/要求 | | --- | --- | | `CREDENTIAL_MODE` | 默认`legacy`;显式`broker`才启用新模式 | | `CREDENTIAL_KEYRING_FILE` | broker必须提供受控服务端密钥文件,格式见阶段1记录;无有效密钥启动失败,不回退 | | `CREDENTIAL_PERMISSION_PROFILES` | JSON对象:产品权限版本名映射Scope字符串数组;broker不可为空,不允许客户端传任意Scope | | `DATABASE_URL` | 生产broker必须使用PostgreSQL;SQLite仅用于本地开发和测试 | | 平台与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(原接口的新授权卡兼容) 文本/通知卡协议不变。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复测或客户端发布。完整解绑连接和任务补偿、旧绑定码作废、凭据拒绝自动失效上报、集中刷新后台调度、运维清理和正式Compose参数挂载为后续阶段。不要绕过新领取认证临时开放旧refresh接口。