# 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 审核阶段，只允许作为设计产物存在，不进入实现。