# 安全模型

## 1. 信任边界

- Gateway、Distribution、Admin 和 Metrics 为四个独立监听边界。
- Provider API 和上游 Proxy 属于外部不可信网络。
- Worker 与 Controller 通道必须进行双向身份校验并绑定 cluster/worker。
- PostgreSQL 保存管理面持久状态；Redis 保存可重建的短效 Proxy 活动池与协调
  信息，Proxy 地址和凭据不写入 PostgreSQL。

## 2. 入口控制

- 严格模式下，非回环监听必须配置认证或 CIDR allowlist。
- 认证关闭不代表匿名状态消失：仍按可信代理链解析来源并形成 Client ID。
- Access、Auth、Rate Limit 和 Client Identification 相互独立。
- Admin 使用独立凭据，不能复用普通 Gateway 或 Distribution 凭据。
- `httpsecurity.Protection` 统一实现 Basic、API Key、Bearer、CIDR、可信代理链、
  Client ID 与入口准入；API 使用 401/`WWW-Authenticate`，Gateway 使用
  407/`Proxy-Authenticate`。
- Token Client ID 使用 SHA-256 的 128 位摘要前缀，不把 Token 本身写入领域、
  日志或审计键。

## 3. 目标地址策略

在解析和每次连接前同时检查：

- 私网、回环、链路本地、组播、保留地址和云元数据地址。
- 域名解析出的全部 A/AAAA 地址，而不是只检查原始 Host。
- 重定向或重试后的新目标，防止 DNS Rebinding 和策略绕过。
- CONNECT 的端口 allowlist 与规范化 host:port。

CONNECT 与绝对 URL 共用端口白名单；省略配置时仅允许 80/443。保留地址、
CGNAT、协议转换保留段和已知云元数据端点属于硬拒绝项。私网、回环或链路
本地的拒绝字段采用三态语义：省略等于拒绝，只有显式 `false` 才放行对应
类别，且不覆盖这些硬拒绝项。

## 4. Secret 处理

- 配置只保存环境变量或文件引用，不在日志中输出解析后的值。
- Proxy 唯一键包含 username 与 credentialVersion，不包含密码或 SecretRef 内容。
- Provider Parser 将静态/响应密码写入 `credentials.Store`，Proxy Snapshot 只携带
  SecretRef 与 credentialVersion；Gateway 通过统一 Resolver 按版本读取。
- 指标标签不得使用 token、Proxy URL、Client ID、session 或完整目标 URL。
- Provider 响应和模板错误只记录分类、Upstream 和 requestId。

## 5. Provider 模板

- 限制响应体大小、模板执行时间和输出候选数量。
- 模板函数采用白名单，禁止文件、网络、进程和环境变量访问。
- URL、Header、Query 和 Body 分别结构化编码，不拼接未转义字符串。
- 认证失败与限流响应分类处理，429 尊重有上限的 Retry-After。

## 6. 审计

Extraction 审计记录至少包含 requestId、Client、来源、Proxy ID、Upstream、
提取时间和到期时间。日志脱敏不影响审计关联，但审计接口自身必须受 Admin
权限保护并具备保留期限。

## 7. 优雅停机

- 先原子停止接收新请求，并关闭 HTTP 空闲连接。
- 已接收的 HTTP 请求和 CONNECT 隧道在 shutdown deadline 内继续排空。
- deadline 到期后强制关闭仍活跃的 Hijacked 隧道并返回超时结果。