492f33a129
- DEFAULT_CHAIN_ADMISSION.md: reviewed and approved, real artifact refs added - DEFAULT_DATA_IDEMPOTENT_RELEASE_GATE.md: reviewed and approved - scripts/setup_default_data.sh: idempotent init with --dry-run/--apply/artifact - scripts/test/test_default_data.sh: 4 test cases all pass - scripts/acceptance/verify_user_key_self_service.sh: Phase 0 skeleton - .gitignore: add generated artifact directories
169 lines
3.7 KiB
Markdown
169 lines
3.7 KiB
Markdown
# Key Security Model
|
||
|
||
日期：2026-06-04
|
||
状态：待审核
|
||
适用版本：vNext.2
|
||
|
||
## 目的
|
||
|
||
为用户 key 自助申请、展示、重置、暂停、恢复建立生产级安全模型，避免 key 功能在设计层面留下对象级越权、明文泄露、审计缺失和资源滥用风险。
|
||
|
||
## 安全目标
|
||
|
||
1. 明文 key 仅在创建响应中返回一次
|
||
2. 本地状态库不保存可直接滥用的上游 secret 明文
|
||
3. 用户只能看到自己的 key 与自己的状态
|
||
4. 管理员动作必须可审计
|
||
5. key 的申请、重置、暂停、恢复、超限必须有明确权限边界
|
||
|
||
## 核心实体
|
||
|
||
### 1. key record
|
||
|
||
建议字段：
|
||
|
||
- key_id
|
||
- owner_subject_id
|
||
- key_fingerprint
|
||
- provider_scope / logical_group_scope
|
||
- display_name
|
||
- admin_status
|
||
- quota_status
|
||
- created_at
|
||
- rotated_at
|
||
- last_used_at
|
||
- last_four / masked_preview
|
||
|
||
### 2. audit event
|
||
|
||
建议字段：
|
||
|
||
- event_id
|
||
- actor_subject_id
|
||
- actor_role
|
||
- target_key_id
|
||
- action
|
||
- result
|
||
- reason
|
||
- ip / ua（如可得）
|
||
- created_at
|
||
|
||
## 明文与持久化规则
|
||
|
||
1. 明文 key 只在创建成功响应返回一次
|
||
2. 页面刷新后不再可恢复明文
|
||
3. 列表页只显示 masked preview
|
||
4. 本地状态库只保存：
|
||
- fingerprint
|
||
- masked preview
|
||
- metadata
|
||
5. 如需可恢复展示，必须使用明确加密材料与密钥管理，不得默认明文落库
|
||
|
||
当前默认建议：
|
||
|
||
- vNext.2 不支持“再次查看明文 key”
|
||
- 只支持“重置/重新生成”
|
||
|
||
## 授权模型
|
||
|
||
### 用户侧
|
||
|
||
用户仅允许：
|
||
|
||
- 查看自己的 key 列表
|
||
- 查看自己的 key 状态与模型范围
|
||
- 创建自己的 key
|
||
- 重置自己的 key
|
||
- 关闭/删除自己的 key（如产品允许）
|
||
|
||
用户禁止：
|
||
|
||
- 查看他人 key
|
||
- 查看他人 key 的明文/metadata
|
||
- 修改他人配额/状态
|
||
|
||
### 管理员侧
|
||
|
||
管理员允许：
|
||
|
||
- 查看 key 元数据
|
||
- 暂停/恢复 key
|
||
- 重置 key
|
||
- 查看 audit event
|
||
- 调整 quota
|
||
|
||
管理员默认禁止：
|
||
|
||
- 无审计地查看明文 key
|
||
|
||
## API 安全要求
|
||
|
||
所有 portal/self-service API 必须满足：
|
||
|
||
1. subject 绑定
|
||
- 列表接口必须按当前 subject 过滤
|
||
2. 对象级授权
|
||
- `GET /keys/:id`
|
||
- `POST /keys/:id/reset`
|
||
- `POST /keys/:id/pause`
|
||
- `POST /keys/:id/resume`
|
||
都必须校验 target key 属主或管理员权限
|
||
3. 功能级授权
|
||
- 管理员动作与普通用户动作分开
|
||
4. 资源消耗控制
|
||
- key 创建/重置需限频
|
||
5. 过度暴露防护
|
||
- 禁止在列表接口返回内部 route_id、shadow_group_id、host_account_id 等内部字段
|
||
|
||
## 状态机（与治理文档衔接）
|
||
|
||
在 key 视角，至少区分：
|
||
|
||
- `admin_status`: active / paused / disabled / retired
|
||
- `quota_status`: ok / exhausted / limited / unknown
|
||
|
||
用户看到的“不可用”必须能映射到明确原因：
|
||
|
||
- paused by admin
|
||
- quota exhausted
|
||
- route temporarily unavailable
|
||
- pending activation
|
||
|
||
## 审计要求
|
||
|
||
以下动作必须写 audit event：
|
||
|
||
- create
|
||
- rotate/reset
|
||
- pause
|
||
- resume
|
||
- delete/retire
|
||
- quota change
|
||
- owner transfer（如果未来支持）
|
||
- denied access
|
||
|
||
## 测试要求
|
||
|
||
至少需要以下测试：
|
||
|
||
1. 用户 A 不能读取用户 B 的 key 列表
|
||
2. 用户 A 不能重置用户 B 的 key
|
||
3. 创建后只返回一次明文 key
|
||
4. 列表接口永不返回明文 key
|
||
5. 管理员暂停后，用户调用结果与状态提示一致
|
||
6. 重置后旧 key 失效，新 key 生效
|
||
7. denied access 写入审计
|
||
8. key 创建/重置限频生效
|
||
|
||
## 验收要求
|
||
|
||
- 必须有越权访问测试
|
||
- 必须有明文一次性返回测试
|
||
- 必须有 audit event 验收
|
||
- 必须有首次 chat=200 用户闭环
|
||
|
||
## 与本轮范围关系
|
||
|
||
本文件属于 vNext.2 设计必备文档。
|
||
在 vNext.1 审核阶段，只允许作为设计产物存在，不进入实现。
|