Introduce an opt-in AES-256-GCM credential store keyed by environment, application and principal. Bind ciphertext to identity, version and key ID with authenticated data; support retained decryption keys and active-key rotation. Use expected-version CAS to reject duplicate or stale writers. Keep token values and scopes encrypted at rest, hide token fields from object repr, and use fixed errors without credential contents. Add tests for identity substitution, authenticated tampering, wrong keys, rotation, persistence, concurrent writers and malformed inputs. Include an opt-in PostgreSQL test using an isolated schema. Validation: 102 passed, 2 skipped (no real PostgreSQL URL), 15 existing uvicorn/websockets deprecation warnings. Python AST and diff checks pass. This is stage 1 only: no public routes or existing OAuth/refresh behavior are changed, no production key/database is initialized, and no ECS runtime deployment or real platform requests were performed. Broker, centralized refresh, access-token-only issuance and unbind lifecycle integration remain subsequent stages. See deployable/CREDENTIAL_MIGRATION.md.
63 lines
5.4 KiB
Markdown
63 lines
5.4 KiB
Markdown
# 集中凭据改造:分阶段交付记录
|
||
|
||
目标:ECS保存并刷新用户access/refresh token;客户端仅认证领取本人access token,MCP、Skill及业务接口在客户端执行并直连私有化Work。refresh token不下发客户端。
|
||
|
||
本文件描述开发阶段,不能作为当前现网已切换的证明。每阶段分别开发、测试、提交master并推送;实际ECS部署及客户端升级另有版本和现场验收。
|
||
|
||
## 阶段划分
|
||
|
||
| 阶段 | 范围 | 完成门槛 | 状态 |
|
||
| --- | --- | --- | --- |
|
||
| 1 | 服务端加密凭据存储基础 | 密文持久化、应用/用户/环境隔离、版本冲突、密钥轮换与篡改检测测试;不接入旧路由 | 本次交付 |
|
||
| 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`后执行:
|
||
|
||
```text
|
||
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容器运行及现机业务验收尚未执行;不得将本地回归标为服务器上线完成。
|