Files
ecs-relay-service/deployable/CREDENTIAL_MIGRATION.md
T
ex_tianzy 02d433250f feat(credentials): add stage 2 centralized broker and refresh fencing
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.
2026-11-04 10:30:27 +08:00

10 KiB
Raw Blame History

集中凭据改造:分阶段交付记录

目标: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共享实例测试证明本地协议并发行为,不外推为生产集群验收。