proxy-pool/docs/security/security-model.md

安全模型

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 隧道并返回超时结果。