Codex
6.6 KiB
PJ2026-010502 APIKey
修改历史
| 版本 | 对应 commit id | 更新日期 | 变更说明 |
|---|
当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 待提交 版本。
正文
PJ2026-010502 APIKey 需求规格
1. 文档控制
| 字段 | 内容 |
|---|---|
| 编号 | PJ2026-010502 |
| 短名 | APIKey |
| 层级 | L2 课题 |
| 状态 | 已生效 |
| 需求规格模板 | ISO/IEC/IEEE 29148 需求规格模板 |
| 上级规格 | PJ2026-0105 用户管理 |
| 规格治理索引 | 规格治理 |
本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版：正文只保留 APIKey 的稳定使命、范围、术语、系统边界、内部分工和原子需求。
2. 目的和范围
2.1 目的
APIKey 负责 HWLAB 自动化调用凭据的生命周期和调用身份绑定，使用户脚本、CLI、Agent 入口和内部 API 能以可撤销、可审计、可限额的方式代表用户发起请求。
D601 v0.3 当前已具备用户自服务 API key 创建、列表、重命名、撤销、prefix 展示和创建时一次性 secret 返回；本课题在该基线上定义 expiry、quota、IP/rate 策略、轮换和调用审计的目标能力。
2.2 范围内
- API key 创建、一次性 secret 返回、prefix 脱敏展示、列表、重命名、撤销和轮换。
- key 与用户、scope、状态、过期时间、quota、rate limit、IP 策略和调用身份的绑定。
- API key introspection、preflight principal 生成和受保护 API 调用鉴权。
- key 使用记录、last used、拒绝原因和审计摘要。
2.3 范围外
- 用户注册登录和 Web session 归 PJ2026-010501 账号会话。
- quota、plan、entitlement 的业务解释归 PJ2026-010503 权限配额。
- usage、ledger 和费用扣减归 PJ2026-010504 计量账本。
- CLI 参数和输出格式归 客户端。
3. 术语表
| 术语 | 定义 |
|---|---|
| API key secret | 创建时一次性返回给用户的完整调用凭据。 |
| key prefix | 可长期展示和搜索的非敏感 key 摘要。 |
| scope | API key 可访问能力集合的声明。 |
| introspection | 服务端根据 API key 解析用户、状态、scope 和策略的过程。 |
| key 策略 | 绑定在 API key 上的过期、quota、IP、rate limit 或状态约束。 |
4. 系统边界和接口
本规格把 APIKey 作为用户管理的自动化凭据层看待；本章只描述输入、输出和责任边界。
| 边界项 | 内容 |
|---|---|
| 外部使用者 | 普通用户、自动化脚本、CLI、Cloud API、Agent编排、平台管理员。 |
| 外部输入 | 创建 key 请求、重命名请求、撤销请求、轮换请求、API key 调用凭据、scope 和策略配置。 |
| 受控资源 | API key 记录、secret hash、prefix、scope、状态、过期时间、quota/rate/IP 策略和 last used 摘要。 |
| 外部输出 | 创建结果、一次性 secret、脱敏 key 列表、introspection principal、拒绝错误和审计摘要。 |
| 用户接口 | Cloud Web API key 页面、HTTP API、hwlab-cli API key 命令和受保护业务 API。 |
| 系统边界 | APIKey 负责调用凭据和用户身份绑定；不定义用户登录、计费扣减、客户端布局或 Agent 执行事实。 |
5. 内部分工与规格索引
| 编号 | 模块或课题 | 规格文档 | 主责边界 | 上游依赖 | 下游支撑 |
|---|---|---|---|---|---|
| PJ2026-01050201 | Key生命周期 | 本规格 6.1 | 创建、展示、重命名、撤销和轮换 | 账号会话 | Web、CLI |
| PJ2026-01050202 | Key策略 | 本规格 6.2 | scope、expiry、quota、IP 和 rate limit 绑定 | 权限配额、平台配置 | 受保护 API |
| PJ2026-01050203 | Key校验 | 本规格 6.3 | introspection 和 principal 输出 | 账号状态、key 策略 | Agent编排、Cloud API |
| PJ2026-01050204 | Key审计 | 本规格 6.4 | last used、拒绝原因和脱敏审计 | key 校验、计量账本 | admin、运营分析 |
6. 原子需求
6.1 USER-KEY-REQ-001 Key 生命周期
| 编号 | 短名 | 主责模块 | 关联模块 |
|---|---|---|---|
| USER-KEY-REQ-001 | Key生命周期 | PJ2026-01050201 Key生命周期 | 客户端、账号会话 |
APIKey 应提供用户自服务的 key 创建、列表、重命名、撤销和轮换能力，并保证完整 secret 只在创建或轮换时返回一次。
长期展示和日志中只能使用 prefix、状态、scope、last used 和 redacted 摘要。客户端负责呈现这些摘要，不得保存或重新展示完整 secret。
6.2 USER-KEY-REQ-002 Key 策略
| 编号 | 短名 | 主责模块 | 关联模块 |
|---|---|---|---|
| USER-KEY-REQ-002 | Key策略 | PJ2026-01050202 Key策略 | 权限配额、平台运维 |
APIKey 应支持把 scope、过期时间、quota、IP 约束和 rate limit 策略绑定到 key，使自动化调用可以被按用户和凭据级别限制。
key 策略只表达调用凭据约束。plan、entitlement 和资源可消费性由权限配额解释；平台运维只提供配置和运行支撑，不定义用户策略。
6.3 USER-KEY-REQ-003 Key 校验
| 编号 | 短名 | 主责模块 | 关联模块 |
|---|---|---|---|
| USER-KEY-REQ-003 | Key校验 | PJ2026-01050203 Key校验 | Agent编排、计量账本 |
APIKey 应提供服务端 introspection，使受保护 API 能把调用凭据解析为用户 principal、scope、状态和策略判断结果。
撤销 key、过期 key、禁用用户和不满足 scope 的调用必须在进入 Agent 执行、硬件资源占用或计费记录前被拒绝，并返回可被客户端一致呈现的错误。
6.4 USER-KEY-REQ-004 Key 审计
| 编号 | 短名 | 主责模块 | 关联模块 |
|---|---|---|---|
| USER-KEY-REQ-004 | Key审计 | PJ2026-01050204 Key审计 | 账单后台、租户隔离 |
APIKey 应记录 key 使用摘要、last used、拒绝原因和策略命中信息，使用户和管理员可以排查自动化调用而不暴露完整 secret。
审计输出必须脱敏，并与 usage、ledger 和租户隔离判断保持一致。任何 issue、日志、导出和页面都不得打印完整 API key。