> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zerone.run/llms.txt
> Use this file to discover all available pages before exploring further.

# 安全

> 保护 Agent Hub 凭据、角色与运行接口。

# 建立生产安全边界

Hub 同时持有模型凭据、部署配置和会话数据，应按控制平面保护。

## 必做项

* 只通过 HTTPS 暴露服务。
* 显式限制 CORS 来源。
* 使用高熵 JWT、Ops 和 Chat Push 密钥，并定期轮换。
* 数据库、对象存储与 Runtime 置于受控网络。
* 按最小权限分配 `admin`、`maintainer` 和 `member`。
* 不在日志、Issue 或 Agent prompt 中输出密钥。

`member` 对管理数据主要是只读；AIGC 密钥、Runtime 文件内容、写操作和部署控制仍由服务端拒绝。Casdoor 模式下，组织是租户边界，但 Hub 本地成员表才是角色真实来源。

<Warning>前端按钮是否显示不能替代服务端鉴权。任何新接口都必须在后端中间件中声明权限。</Warning>

## 当前版本的安全注意事项

1. **绝不把 `PROVIDER_ENCRYPTION_KEY` 提交到仓库**——一旦泄漏，所有 API key 都可能被解密。
2. **Provider API key 读取时掩码**——`GET /api/v1/providers` / `/:id` 与管理列表只返回掩码后的 key；明文仅能通过 `POST /api/v1/admin/providers/:id/reveal-key`（adminWrite 组 = admin/maintainer，按租户隔离）获取。请保留对 reveal 接口的审计；客户端不应需要明文 key。
3. **`OPS_API_KEY` 是高权限凭据**——它可以为任意组织登记任意 Casdoor OAuth client（`/api/v1/ops/tenant-clients`），即签发新的登录入口。一旦泄漏，攻击者可以把 Hub 登录导向他们控制的 Casdoor 应用。仅在接入新组织时配置，存入 secret manager，发现疑点立即轮换。请求需携带 `X-Ops-Key` 头；未配置时运维端点完全不挂载。
4. **`CHAT_PUSH_API_KEY` 是窄范围凭据**——它只授权通过 `POST /api/v1/chat/push`（请求头 `X-Chat-Push-Key`）写入聊天会话/消息。它不能读取任何数据、不能访问 `/api/v1/ops/*`、不授予任何用户身份。请与 `OPS_API_KEY` 保持独立，使任一泄漏互不影响；发现疑点即轮换。使用 ≥32 字节随机值生成。
5. **`tenant_oauth_clients.client_secret_enc` / `cert_enc` 静态加密**（AES-GCM，密钥为 `PROVIDER_ENCRYPTION_KEY`）；Ops API 响应从不返回 secret。
6. **CLI token 携带签发用户的完整权限**（`/api/v1/cli/*`，仅 admin/maintainer）——泄漏的 CLI token 在过期/吊销前等同于该用户的会话。token 以 SHA-256 哈希存储；发现疑点立即吊销。
7. **CORS 默认 AllowAll + AllowCredentials**——生产环境必须显式配置 allowlist。

## 已知限制

* **ServiceRouter 反向代理存在 SSRF 风险**——`EndpointURL` 缺少 scheme 与私网网段校验。
* **OAuth state 存于内存**——进程重启会丢失进行中的登录流程；建议迁移到 Redis。
* **Token Exchange 日志**——当前会打印包含 token 的响应体；生产环境应移除。

## 报告漏洞

如果你发现安全漏洞，请**不要**开公开 Issue。请直接邮件联系 **[zerone-agents@proton.me](mailto:zerone-agents@proton.me)**，我们会在 72 小时内响应。