Add an internal CredentialBroker that serializes refresh and authorization by environment/app/user using renewable Redis leases. Re-read credentials under the lease and persist rotated pairs with expected-version CAS before returning an explicit access-only grant. Verify the actual platform user, remaining lifetime and scopes; never return refresh tokens from the broker. Persist source-version refresh attempts before platform calls. Timeouts, cancellation, lease loss, malformed responses and ambiguous database errors fence reuse of the old rotating refresh token, including after restart. A new authorization can establish a new version without stale overwrite. Add a strict, separate private Work v1 OIDC adapter while preserving legacy OAuth method behavior. Enable fakeredis Lua test support for Redis lease renewal tests. Document stage boundaries, recovery limitations and testing. Validation: 147 passed, 2 skipped (real PostgreSQL not configured), with 15 existing uvicorn/websockets deprecation warnings. New broker/adapter coverage: 45 tests. AST, runtime opt-in boundary and diff checks pass. An earlier Windows temp-file replace failure in a legacy client test passed both isolated rerun and the final full suite; no client code was changed. No public credential/OAuth routes are wired, no production database/key is initialized, and no real Work authorization, refresh or ECS deployment was performed. Authenticated access-token issuance, state transactions, binding checks and unbind integration remain subsequent stages.
10 KiB
集中凭据改造:分阶段交付记录
目标:ECS保存并刷新用户access/refresh token;客户端仅认证领取本人access token,MCP、Skill及业务接口在客户端执行并直连私有化Work。refresh token不下发客户端。
本文件描述开发阶段,不能作为当前现网已切换的证明。每阶段分别开发、测试、提交master并推送;实际ECS部署及客户端升级另有版本和现场验收。
阶段划分
| 阶段 | 范围 | 完成门槛 | 状态 |
|---|---|---|---|
| 1 | 服务端加密凭据存储基础 | 密文持久化、应用/用户/环境隔离、版本冲突、密钥轮换与篡改检测测试;不接入旧路由 | 已完成本地开发测试,提交71b9678 |
| 2 | 集中凭据Broker及刷新 | 应用/用户锁、持锁重读、版本CAS、响应校验、刷新unknown;新授权不受旧刷新覆盖 | 本次完成本地开发测试 |
| 3 | OAuth与认证领取 | 共享state事务、实际用户核验、绑定代次、只返回access的独立DTO及领取认证 | 待开发 |
| 4 | ECS权威解绑与消息任务关联 | 停发Token、失效事务/任务、连接和旧码联动,多实例/异常恢复 | 待开发 |
| 5 | 配置部署、迁移与旧接口退出 | 密钥挂载、产品权限配置、客户端对接、停用旧刷新/claim及代理、ARM64和真实平台验收 | 待开发 |
产品经理决定功能和Scope清单。阶段1不预设具体权限,不生成真实凭据、不读取现有设备、不调用平台。
阶段1:加密存储基础
新增relay/credential_store.py和测试,使用现有Store数据库连接,支持SQLite本地测试和PostgreSQL部署。只有显式构造CredentialStore时初始化新增表work_credentials_v2,当前connector不导入/启用该模块。
存储与加密
- 主键为environment/app_id/principal_id。access token、refresh token、实际Scope、到期时间一起作为AES-256-GCM密文保存;数据库元数据只有身份、凭据版本、key_id和更新时间。
- AAD绑定格式版本、身份三元组、凭据版本和key_id,防止跨用户/应用/环境调换密文。每次写入生成随机96位nonce。
- 调用方提交expected_version:0仅允许首次创建;后续更新必须匹配数据库版本。冲突抛固定异常,不自动覆盖、重试或刷新上游。
- keyring包含active_key_id及保留解密用的旧密钥。新写入采用当前密钥;旧记录必须先由有旧密钥的服务读取并以CAS重写后才可移除旧密钥。改active_key_id不表示全量密文已迁移。
- 存储对象仅供ECS内部使用,包含refresh token,绝不能直接序列化为客户端响应。后续阶段必须用独立字段白名单DTO,客户端只收到access token。
密钥管理
CredentialKeyring.from_file(Path(...))读取JSON文件,格式为active_key_id和keys映射,每项keys值为32字节随机密钥的标准Base64编码。当前不提供默认密钥、环境配置或自动启动接线,不能只上线此提交就开始存生产凭据。
部署阶段需由运维将密钥文件放在Git、镜像、数据库和普通备份之外的受控位置,以最小OS权限挂载,仅凭据服务可读;Windows文件ACL和Linux权限由部署检查落实,模块不声称已校验ACL。密钥与加密数据库备份分开保护。不要把真实密钥作为命令行参数、日志、工单或文档示例。
兼容与未完成边界
现有设备/绑定、数据库旧表、OAuth路由、通知和客户端协议均未修改;原始快照目录保留。阶段1没有发Token接口、后台刷新、绑定代次或解绑联动;旧实现仍可能把refresh下发PC,不能把本提交视为已经满足最终凭据边界。
版本CAS用于避免陈旧写入覆盖,并不能实现跨平台刷新exactly-once。AEAD用于检测密文篡改,不保证数据库整体历史回滚检测。PostgreSQL真实环境、密钥轮换运维和加密备份恢复必须另行验收。
复核命令
在仓库根设置PYTHONPATH=deployable后执行:
python -m pytest deployable/tests/test_credential_store.py -q
python -m pytest deployable/tests deployment-source/tests -q
真实PostgreSQL用例只有在测试环境设置HN_TEST_DATABASE_URL时执行;它创建并清理独立随机schema,不把测试指向业务库。未提供时明确skipped,不冒充实机通过。
本阶段验证记录(2026-11-04)
- Windows / Python 3.12.10,使用本机已有隔离测试依赖环境,
PYTHONPATH=deployable。 - 最后一轮完整本地回归:102 passed,2 skipped,15 warnings(42秒)。其中新增存储测试23项通过,新增真实PostgreSQL测试1项跳过;原有真实PostgreSQL测试也因未配置连接而跳过。
- warnings为现有uvicorn/websockets旧接口弃用提示,没有新增测试失败。新增模块AST语法与
git diff --check通过。 - 覆盖密文/WAL不含测试Token、重开连接持久性、环境/应用/用户密文调换拒绝、AAD/认证标签篡改、错误密钥、旧密钥移除、轮换重写、陈旧CAS和双连接并发写入、异常输入与固定错误信息。
- connector未引用新增模块,未新增公开路由,未生成真实密钥或初始化现有数据库。
测试只使用合成凭据、本地临时文件和平台桩,没有进行现网授权、刷新或消息推送。真实PostgreSQL、Docker/ARM64容器运行及现机业务验收尚未执行;不得将本地回归标为服务器上线完成。
阶段2:集中凭据Broker与刷新(2026-11-04)
本次改造
- 新增内部
CredentialBroker,按环境/应用/已核验owner读取加密凭据,保留原凭据实际剩余期限。AccessGrant只包含access token、到期时间、剩余秒数、版本和实际Scope,不含refresh token,repr也隐藏access token。 - 按环境/应用/owner取Redis可续期租约,刷新与新授权共用同一锁;持锁重读当前凭据,只在access即将过期时刷新。锁等待有上限,慢请求超过等待预算时其他调用返回busy,不自动并发刷新。
- 新增持久
work_refresh_attempts_v2,按源凭据版本唯一。上游调用前记录started;超时、取消、响应缺字段、身份不符、失锁或数据库失败后标为unknown;即使标记失败留下started,也阻止重复使用同一旧refresh。 - 新凭据经user_info核验实际用户后,以CAS原子保存access/refresh和版本,再返回access;后续领取不再触发同一版本刷新。重开数据库可保留刷新未知状态;重新授权写新版本后恢复。
- 新授权与刷新共享互斥与版本检查,拒绝旧结果覆盖外部已写入的新凭据。刷新Scope缺失仅继承原已核验Scope,不扩权;显式返回缩减Scope时保存新凭据但拒绝缺失能力。新授权必须返回实际Scope。
platform.py增加独立的credential_exchange/credential_refresh适配,使用现有私有化v1 OIDC端点。严格检查HTTP状态、顶层业务码和必要字段;不改变旧exchange/refresh/normalize调用契约,不直接复制agent-hub默认v3接口。- 新增平台调用超时、Redis失败、租约失效、身份与Scope核验,错误采用固定消息,不输出平台原始凭据或错误正文。
调用边界与后续集成要求
Broker仍是内部模块,未由connector实例化,没有新HTTP接口或后台调度。owner参数暂按应用范围内已核验的open_id使用,只能来自后续可信设备/授权事务映射;不得把此内部方法直接暴露给模型、客户端自选用户或无认证HTTP路由。阶段3仍需完成state、绑定代次、领取认证、产品权限配置及公开响应白名单。
此阶段不改变旧OAuth向PC交付refresh的行为,也不读取旧PC凭据。部署阶段必须关闭旧刷新并避免双主,不能仅发布此模块就宣称refresh只在ECS。
当前get_access连有效Token读取也经过短租约,便于与新授权/刷新串行;客户端将缓存access以降低领取压力。阶段3需在发放前复核绑定和代次,阶段4实现解绑联动。数据库失效状态、已发Bearer残余有效、Scope审批和平台撤权均不由本阶段替代。
已有Redis租约和CAS仍无法消除“平台已轮换、服务端未可靠保存”的故障窗口:持续未知时需重新授权,不自动重试旧refresh。数据库记录可恢复到新版本时后续领取复用,不因调用方未收到响应而再次刷新。记录清理必须保留当前源版本的重试屏障,后续运维策略另行定义,不能简单按短TTL删除started/unknown。
测试环境及结果
测试extra改为fakeredis[lua],在本机隔离测试环境安装Lua支持,用FakeRedis实际执行锁的Lua脚本及续租,不将Python本地锁冒充Redis分布式锁。Lua支持仅为测试依赖,生产使用Redis自身脚本,不增加生产Lupa依赖。离线测试环境需事先准备对应测试extra依赖。
最后一轮完整回归:147 passed,2 skipped,15 warnings(29.57秒)。新增Broker/平台适配测试45项通过;真实PostgreSQL的2个用例因未配置HN_TEST_DATABASE_URL而跳过,扩充的PostgreSQL用例含刷新记录唯一性和状态更新但尚未实测。
本地覆盖:多Broker实例与独立Redis客户端/数据库连接并发只刷新一次、续租覆盖慢平台调用、失败续租不发布结果、实际剩余期限、access-only对象、身份错误、授权/刷新串行、陈旧CAS、Scope减少、异常字段、进程取消、调用超时、崩溃started记录重开保留、刷新状态写失败、新凭据提交后确认丢失、Redis不可用及旧接口回归。
首轮完整回归有一条原有PC测试遇到Windows临时文件replace拒绝访问(WinError 5);该用例单独重跑和最后完整回归均通过,未修改该客户端实现,具体系统原因未确定。warnings仍为uvicorn/websockets旧API弃用提示。
未进行真实Redis多进程/多节点压测、真实PostgreSQL、Docker/ARM64、现机部署或真实授权/刷新。FakeRedis共享实例测试证明本地协议并发行为,不外推为生产集群验收。