qinglong/docs/adr/ADR-0035-approved-action-manual-recovery-authorization.md

# ADR-0035：Approved Action 人工恢复授权与强认证事实

- 状态：Proposed
- 日期：2026-07-19
- 关联：QL-RFC-0001、ADR-0028、ADR-0029、ADR-0030、ADR-0031、ADR-0033

## 上下文

ADR-0033 只允许人工把 post-start unknown action 显式终结为 succeeded、failed 或 blocked，禁止把旧 dispatch 重置后再次执行。这个操作会改变审计事实，也可能掩盖一个已经发生但无法验证的外部副作用，因此普通登录、可变 username、Agent 身份或仅在应用层判断一次角色都不足以授权。

人工服务先做 Policy 判断、随后 Repository 写终态时还存在撤权竞态：如果 owner/admin binding 或 Project version 在两步之间变化，旧的 allow 结果不能继续生效。授权记录若在终态提交之后另写，又会留下“动作已经被人裁决，但无法证明当时认证与授权上下文”的崩溃窗口。

因此人工恢复必须把稳定 User、近期强认证、Project Policy version fence 和低敏授权事实绑定到同一个终态事务。

## 决策

### 1. `approval.recover` 是独立的 Project permission

人工恢复只请求 `approval.recover`，不复用 `approval.decide`、`project.manage` 或通配 Tool 权限。固定角色矩阵为：

- owner、admin：允许；
- operator、viewer：拒绝；
- 未绑定、已撤销或 archived Project：默认拒绝。

首版继续使用静态 Policy Core；未来接 OPA 或自定义策略时也必须返回 Project/RoleBinding version fence，不能只返回一个布尔 allow。

### 2. 只接受仍有效的稳定 User principal

应用服务接收 ADR-0029 的 exact-shape `AuthenticatedPrincipal`，并在读取 recovery storage 前验证：

- `subject.type=user`；
- principal 在服务时钟上满足 `authenticatedAtMs <= now < expiresAtMs`；
- assurance 为 `multi_factor`、`hardware` 或 `local_console`；
- `now - authenticatedAtMs <= 5 分钟`。

`single_factor`、`service`、Agent、API App、MCP Client、Worker 和 System 均不能进行人工恢复。legacy `twoFactorActivated` 仍不是 MFA 事实；只有未来可信 authentication adapter 验证真实 ceremony 后才能产生上述 assurance。本 ADR 不定义 MFA 协议、恢复码或 local-console issuer。

### 3. Policy 判断必须携带可提交的 version fence

服务从 recovery snapshot 取得 immutable Project ID，以稳定 User 请求 `approval.recover`。只有 `allow` 且 Project version、当前 RoleBinding version 都存在时才构造授权事实。

SQLite Repository 在同一个 `BEGIN IMMEDIATE` 中重新读取最新 Project 与该 User 的 RoleBinding version：任一 version 不一致即以 fence rejection 失败，且在写 recovery resolution 或 execution 终态前退出。这样 revoke、role change、Project archive 或其他 version mutation 无法穿透已经计算出的 allow。

### 4. `0024` 授权事实与人工终态原子提交

`ApprovedActionRecoveryAuthorizationFacts` 与 human resolution 一对一，保存：

- dispatch、Project、manual mutation ID 和稳定 User ID；
- authentication ID、强 assurance、认证时间；
- Policy 判断使用的 Project/RoleBinding version；
- 授权时间；
- 对以上 canonical 字段计算的 SHA-256 fact digest。

表只允许 User 和三种强 assurance，要求正 version、认证时间不晚于授权时间且间隔不超过五分钟，并通过外键绑定 recovery resolution 与 Project。它不保存 cookie、JWT、MFA secret、recovery code、请求 header 或无界理由。

Repository 在一个事务内依次复验 execution/recovery fence、复验 Policy version、插入 human resolution、推进 execution/control 终态并插入授权事实。任一约束、trigger 或 commit 失败全部回滚，不能留下“有终态无授权事实”或“有授权事实无终态”。automatic evidence resolution 不创建人工授权事实。

### 5. 幂等重放必须包含相同授权事实

相同 manual mutation 只有在 decision、reason、evidence、User、时间和 authorization fact 全部精确一致时返回原结果。字段漂移、digest 不匹配或一条旧 human resolution 缺少 `0024` fact 时不补写、不重新解释，稳定返回 terminal/conflict 语义。

服务在重放前仍验证当前 principal 和当前 Policy；历史 allow 事实只用于审计与精确幂等，不成为永久授权 capability。

### 6. 当前保持 production unreachable

本切片已经实现 permission matrix、强认证应用服务、`0024` migration、SQLite 原子 Repository 和 contract tests，但没有注册到 app、loader、legacy service、API、CLI、MCP 或 UI。生产启用仍需要：

- 真实 MFA/hardware/local-console authentication adapter 与 credential 生命周期；
- 人工恢复列表、低敏证据预览、二次确认、rate limit 和审计 API/UI；
- 对外错误屏蔽，避免未授权调用者区分 dispatch 是否存在；
- profile-aware recovery lifecycle、指标、告警与积压门禁；
- PostgreSQL adapter 与多副本 revoke/resolve 竞争 contract；
- edge 设备和 cluster 节点上的故障注入与资源门禁。

## 影响

正面影响：

- 高风险 unknown 终结不能由 Agent、普通 session 或 operator 越权执行；
- 授权撤销竞态由数据库 version fence 关闭；
- 认证、授权与终态形成一个可验证、低敏、原子的审计事实；
- edge 只增加一次人工操作时的短事务和单行事实，不增加 watcher、timer 或常驻连接；
- cluster adapter 可以复用相同语义，通过 PostgreSQL row lock 实现多副本一致裁决。

代价与风险：

- 单用户部署若没有可信强认证入口，将不能使用人工恢复；这是安全门禁，不应降级为密码确认；
- 每条人工 resolution 增加一行保留事实和关联索引；
- authentication ID 虽非 Secret，仍属于安全审计标识，API 默认不得向普通读取者暴露；
- 当前只有 SQLite adapter，不能据此宣称 cluster-control 已可用。

## 未选择的方案

1. **owner/admin 登录即可恢复**：single-factor session 不足以授权未知副作用终结，拒绝。
2. **复用 `approval.decide`**：审批新动作与裁决已发生但未知的动作风险不同，拒绝。
3. **只在应用层检查 Policy**：检查与提交之间存在 revoke/archive 竞态，拒绝。
4. **终态提交后异步写审计日志**：崩溃会产生不可证明的人工裁决，拒绝。
5. **把完整 JWT/MFA 证明写数据库**：扩大 Secret 与隐私暴露面，拒绝。
6. **旧单用户环境自动提升为 local console**：UID、TTY 或私有文件本身不能证明可信 ceremony，拒绝。
7. **授权事实缺失时自动补写**：无法还原历史认证与 Policy snapshot，拒绝。

## 验证要求

- owner/admin 允许，operator/viewer/未绑定/revoked/archived 拒绝；
- 非 User、过期 principal、single-factor/service 或超过五分钟的强认证在 storage read 前拒绝；
- Project/RoleBinding 在 Policy allow 后变化时，Repository 在任何终态写入前 fence rejection；
- resolution、execution/control 终态与 authorization fact 同事务提交，fact 插入失败全部回滚；
- fact exact-shape、强 assurance、时间窗口、version、digest 或 identity 任一漂移均 fail closed；
- 精确 manual mutation 重放返回同一结果，变形重放不得覆盖原事实；
- automatic evidence resolution 不依赖或伪造人工授权事实；
- migration/schema ownership 覆盖表、索引、约束和外键；
- production reachability 搜索证明服务和 Repository 未被旧 app/loader/API/service 路径导入；
- Node 22 兼容门禁与固定 Node 24 目标门禁均通过。