heicode/docs/product-package/06-security-and-credential-management.md

06. 安全与凭证管理说明

核心原则

Heicode 是 SaaS 产品，不能把凭证管理转嫁给用户，也不能让密钥散落在 Git、Markdown、日志或子 Agnet 长期状态中。

安全目标：

1. 用户授权资源，平台托管凭证。
2. Heicode 服务端数据库只保存元数据和 secret_ref。
3. 长期密钥进入密钥保管器。
4. 子 Agnet 只拿短期、最小权限、可审计凭证。
5. 高危操作必须由客户端审批。

凭证分类

凭证	示例	存放位置
Git 凭证	GitHub token、SSH key	密钥保管器
云凭证	Azure、AWS、GCP access key	密钥保管器
数据库凭证	DB password、connection secret	密钥保管器
CodeGW 服务凭据	内部服务 token	服务环境或密钥保管器
短期凭证	临时云 token、临时 Git token	运行时注入，TTL 到期失效

密钥保管器

用户可见名称：密钥保管器。

技术实现：OpenBao，兼容 Vault API。

用户不需要直接登录 OpenBao，也不需要看到 OpenBao 控制台。

Secret Broker 流程

用户绑定资源
-> Heicode 接收授权结果
-> Heicode Secret Broker 写入 OpenBao
-> OpenBao 返回或形成 secret_ref
-> Heicode DB 保存 secret_ref
-> 前端只展示脱敏引用和状态

Heicode 接口不得返回明文密钥。日志、错误信息、审计摘要也不得包含明文密钥。

子 Agnet 访问凭证

子 Agnet 不保存长期密钥。

推荐流程：

Heicode 生成 Resource Grant
-> Agnet 平台部署子 Agnet
-> Agnet 平台绑定运行时身份
-> 子 Agnet 请求使用资源
-> 高危操作先走客户端审批
-> 审批通过后派生短期凭证
-> 短期凭证注入运行时
-> TTL 到期或任务结束后失效

高危操作

高危操作包括：

• 生产环境部署。
• 云资源创建、删除、扩缩容。
• 数据库迁移或写入。
• 访问生产密钥。
• 大额模型预算消耗。

审批必须记录：

• 审批人。
• 审批时间。
• 操作类型。
• 资源范围。
• 风险等级。
• TTL。
• 对应 deployment 或任务。

禁止事项

1. 禁止把 token 写入 Git。
2. 禁止把密钥写入 Markdown。
3. 禁止前端返回明文密钥。
4. 禁止在日志中打印密钥。
5. 禁止把长期云密钥注入子 Agnet。
6. 禁止把 OpenBao 暴露为普通公网入口。
7. 禁止把 CodeGW key 原文交给客户端长期保存。

用户侧解释

推荐文案：

Heicode 会把你的授权凭证存入密钥保管器。平台只在你授权的范围内，为对应任务和角色生成短期访问能力。密钥不会写入 Git、文档、日志或子 Agnet 长期状态。

验收标准

验收项	标准
数据库	只保存 secret_ref，不保存明文密钥
前端	不显示明文密钥
日志	不包含 token、password、private key、access key
子 Agnet	不保存长期凭证
高危操作	有客户端审批记录
OpenBao	不对普通公网暴露