qinglong/docs/adr/ADR-0046-cluster-two-phase-security-admission.md

# ADR-0046: Cluster 两阶段安全 Admission

- 状态：Proposed
- 日期：2026-07-19
- 关联 RFC：QL-RFC-0001 D-04、D-08、D-13、D-27 至 D-32、D-43、D-44

## 上下文

ADR-0045 建立了有界 HTTP surface，并保证 `/api/v3` 在 readiness 与 recovery 完成前不可达。但如果 Authentication 和 Policy 只是普通业务 handler 中的 middleware，HTTP adapter 仍会先读取、缓存并解析整个 JSON body。匿名或已撤权请求因此可以在拒绝前消耗内存和 CPU；新增 route 也可能因漏装 middleware 绕过统一 Policy/Approval/Audit。

cluster-control 还不能复用 legacy Express Controller 作为安全入口：它会把 2.x session、Sequelize、route scope 和控制面装配重新耦合到 cluster artifact，并破坏 edge/cluster 的 Profile 隔离。

## 决策

### 1. 共享安全契约属于 runtime-core

`@qinglong/runtime-core/security` 只定义并严格规范化：

- `SecuritySubject` 与 active `SecurityPrincipal`；
- authentication assurance；
- `allow | deny | require_approval` Policy decision；
- 可选 Project/RoleBinding version fence；
- 有界、低敏 reason code。

该入口没有数据库 driver、JWT library、HTTP framework 或 legacy 依赖。adapter 返回过期、未来时间、扩展 shape、非法 identifier、空 reason 或无效 fence 时视为安全依赖故障并 fail closed。

### 2. HTTP admission 固定为两个阶段

第一阶段 `prepare(metadata)` 只接收 method、path、query、有界 headers、request ID 和 AbortSignal，固定执行：

1. route resolver 产生稳定 operation、permission、Project scope 和 handler；
2. authenticator 产生 active Principal；
3. Policy authorizer 返回 decision/fence；
4. security audit sink 记录低敏 decision fact。

只有全部成功且 decision 为 `allow` 时，pipeline 才返回 `PreparedAdmission`。HTTP adapter 随后才读取有界 JSON body，并调用 prepared operation。`deny` 与 `require_approval` 均不会读取 body 或调用业务 handler。

### 3. 安全依赖与审计 fail closed

- 无 credential 返回 `401 authentication_required`；
- Policy deny 返回 `403 forbidden`；
- 需要审批返回 `403 approval_required`；
- route/authentication/authorization/audit 不可用返回各自稳定的 `503` code；
- adapter 原始错误、credential、Principal、内部 Policy reason 和 stack 不进入 wire response；
- `allowed` decision 必须先完成安全审计，审计失败不得继续 handler。

HTTP 的通用 `onError` 仍只用于技术诊断，不能替代安全 decision fact。

### 4. 当前 pipeline 不是生产身份实现

本 ADR 只建立不可绕过的顺序与端口。生产启用仍需要：

- 真实 credential authenticator（panel/API App/mTLS 等必须分别建模）；
- PostgreSQL Project/RoleBinding Policy adapter 与 version fence；
- 经过评审的 route registry 和领域 handler；
- 有界、持久化、可告警的安全审计 sink；
- ApprovalRequest/dispatch 对 `require_approval` 的产品入口。

禁止用 allow-all authenticator、固定 owner Principal 或无操作 audit sink 把当前 generic host 宣布为 production-ready。

## 被否决的替代方案

### 在每个 Controller 内手写鉴权

拒绝。无法证明所有 route 都经过相同顺序，且默认发生在 body 解析之后。

### 只依赖反向代理完成认证授权

拒绝。代理身份可以作为 credential transport，但领域 permission、Project fence、Approval 与审计仍必须由 QingLong 裁决。

### 认证成功后立即读取 body，再执行 Policy

拒绝。已认证不等于对目标 Project/operation 有权，撤权或 Agent approval 仍会让大 body 成为无意义资源消耗。

### 审计失败时继续业务请求

拒绝。允许动作却没有对应安全 decision fact 会破坏可追责性，并使安全存储故障静默降级。

## 影响

### 正向

- 未认证、撤权和需审批请求在 body 读取前被拒绝，保护低资源设备与 cluster gateway；
- route 新增时必须显式提供 operation/permission/scope，不存在可选安全 middleware；
- Principal/Policy contract 可被 edge、standalone、cluster-control 和 worker 复用；
- wire error 保持低敏、稳定且不绑定具体认证/数据库实现。

### 代价

- route resolver 必须能仅凭 method/path/query/headers 确定 permission 与 Project scope；依赖 body 才能授权的动作必须先重构为 path identity 或单独的受限 preview/admission 协议；
- 安全审计成为 availability dependency，需要有界队列、持久化和告警设计；
- 两阶段 handler contract 比普通 `(request) => response` 多一个 prepared operation。

## 验证

1. runtime-core contract test 拒绝过期/未来 Principal、widened shape、非法 reason 与 fence。
2. admission pipeline test 固定 route→authenticate→authorize→audit→handler 顺序。
3. authentication reject、Policy deny、approval required、adapter failure 和 audit failure 都证明 handler 未执行。
4. 真实 Node HTTP 测试只发送声明的 `Content-Length` 而不发送 body，仍必须立即得到认证拒绝，证明 preflight 不等待 body。
5. 公开 admission/config/application import closure 不得加载 legacy `back/**`、PostgreSQL migration DDL 或 Drizzle schema。
6. Node 24、依赖审计和 GitNexus impact/detect-changes 作为合并门禁。