sub2api-cn-relay-manager/docs/2026-06-04-KEY_SECURITY_MODEL.md

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