Codex
123 lines
6.6 KiB
Markdown
123 lines
6.6 KiB
Markdown
# PJ2026-010502 APIKey
|
|
|
|
## 修改历史
|
|
|
|
| 版本 | 对应 commit id | 更新日期 | 变更说明 |
|
|
| --- | --- | --- | --- |
|
|
|
|
当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 `待提交` 版本。
|
|
|
|
## 正文
|
|
|
|
## PJ2026-010502 APIKey 需求规格
|
|
|
|
## 1. 文档控制
|
|
|
|
| 字段 | 内容 |
|
|
| --- | --- |
|
|
| 编号 | PJ2026-010502 |
|
|
| 短名 | APIKey |
|
|
| 层级 | L2 课题 |
|
|
| 状态 | 已生效 |
|
|
| 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) |
|
|
| 上级规格 | [PJ2026-0105 用户管理](PJ2026-0105-user-management.md) |
|
|
| 规格治理索引 | [规格治理](spec-governance.md) |
|
|
|
|
本文采用 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 账号会话](PJ2026-010501-account-session.md)。
|
|
- quota、plan、entitlement 的业务解释归 [PJ2026-010503 权限配额](PJ2026-010503-access-quota.md)。
|
|
- usage、ledger 和费用扣减归 [PJ2026-010504 计量账本](PJ2026-010504-metering-ledger.md)。
|
|
- CLI 参数和输出格式归 [客户端](PJ2026-0104-client.md)。
|
|
|
|
## 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生命周期 | [客户端](PJ2026-0104-client.md)、[账号会话](PJ2026-010501-account-session.md) |
|
|
|
|
APIKey 应提供用户自服务的 key 创建、列表、重命名、撤销和轮换能力，并保证完整 secret 只在创建或轮换时返回一次。
|
|
|
|
长期展示和日志中只能使用 prefix、状态、scope、last used 和 redacted 摘要。客户端负责呈现这些摘要，不得保存或重新展示完整 secret。
|
|
|
|
### 6.2 USER-KEY-REQ-002 Key 策略
|
|
|
|
| 编号 | 短名 | 主责模块 | 关联模块 |
|
|
| --- | --- | --- | --- |
|
|
| USER-KEY-REQ-002 | Key策略 | PJ2026-01050202 Key策略 | [权限配额](PJ2026-010503-access-quota.md)、[平台运维](PJ2026-0106-platform-ops.md) |
|
|
|
|
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编排](PJ2026-0102-agent-orchestration.md)、[计量账本](PJ2026-010504-metering-ledger.md) |
|
|
|
|
APIKey 应提供服务端 introspection，使受保护 API 能把调用凭据解析为用户 principal、scope、状态和策略判断结果。
|
|
|
|
撤销 key、过期 key、禁用用户和不满足 scope 的调用必须在进入 Agent 执行、硬件资源占用或计费记录前被拒绝，并返回可被客户端一致呈现的错误。
|
|
|
|
### 6.4 USER-KEY-REQ-004 Key 审计
|
|
|
|
| 编号 | 短名 | 主责模块 | 关联模块 |
|
|
| --- | --- | --- | --- |
|
|
| USER-KEY-REQ-004 | Key审计 | PJ2026-01050204 Key审计 | [账单后台](PJ2026-010505-billing-admin.md)、[租户隔离](PJ2026-010506-tenant-isolation.md) |
|
|
|
|
APIKey 应记录 key 使用摘要、last used、拒绝原因和策略命中信息，使用户和管理员可以排查自动化调用而不暴露完整 secret。
|
|
|
|
审计输出必须脱敏，并与 usage、ledger 和租户隔离判断保持一致。任何 issue、日志、导出和页面都不得打印完整 API key。
|