# 資安人工批准 Gate 契約

| 項目 | 內容 |
|------|------|
| 日期 | 2026-05-17 |
| 狀態 | 草案 |
| Schema | `docs/schemas/security_approval_gate_v1.schema.json` |
| Snapshot | `docs/security/security-approval-gate.snapshot.json` |
| 模式 | `approval_gate_only` |
| runtime 執行授權 | `false` |

## 0. 核心結論

`security_approval_gate_v1` 是 S3 的第一個框架契約。

它讓 AwoooP 能顯示、排序、記錄人工批准，但不讓批准自動變成執行。

批准後最多只能進入下一步設計、草案、只讀 inventory、低噪音 scope 或人工 exception；任何真正 runtime action 都還需要後續 runtime gate。

S3.1 開始，實際人工決策紀錄由 `security_approval_decision_record_v1` 保存。S3.2 開始，可用 `security_approval_review_packet_v1` 把 gate item 包成 review packet。S3.3 開始，決策後 next state 由 `security_approval_state_transition_v1` 定義。S3.4 開始，未來 runtime gate 的前置條件由 `security_followup_runtime_gate_v1` 顯示。Gate 定義可審項目與批准範圍；Review Packet 協助人工審查；Decision Record 保存決策結果與 audit evidence；State Transition 避免批准被誤解成執行；Follow-up Runtime Gate 避免批准後缺少 preflight 與 rollback 條件。

## 1. 目前 Gate 狀態

| 指標 | 數量 |
|------|------|
| Gate items | 8 |
| Pending human decision | 7 |
| Block candidate | 1 |
| Approved | 0 |
| Runtime actions authorized | `false` |
| Immediate execution after approval | `false` |
| Raw secret storage authorized | `false` |

## 2. 建議審查順序

| 順序 | Gate | 初期批准範圍 |
|------|------|--------------|
| 1 | Redacted finding ingestion | 只批准設計或 draft PR |
| 2 | Safe web crawl | 只批准低噪音 scope 定義 |
| 3 | Gitea owner attestation + read-only inventory | 先依 S4.9 驗收 S4.7 owner response，再只批准只讀 inventory 或 redacted admin export |
| 4 | GitHub target decisions | 只批准逐 repo S4.10 request packet / template status ledger / audit event templates / redaction examples / collection checks / intake preflight checks / response 與 S4.12 request packet / template status ledger / audit event templates / redaction examples / collection checks / intake preflight checks / workflow secret 名稱 response 驗收與決策草案 |
| 5 | Ref truth review | 只批准 S4.11 request packet / template status ledger / audit event templates / redaction examples / collection checks / intake preflight checks / owner response 驗收、人工分類與 reconcile 草案 |
| 6 | Credentialed scan | 只允許人工 exception 設計，仍需 runtime gate |
| 7 | Kali full-upgrade / reboot | 只允許維護窗口與 rollback 規劃 |
| 8 | Kali `/execute` | 預設維持 block candidate |

## 3. AwoooP 可做

1. 顯示 gate item、risk、required reviewers 與 evidence refs。
2. 記錄 approve / reject / defer / request more evidence / keep blocked。
3. 將人工決策寫入 Audit evidence。
4. 顯示批准範圍與仍然禁止事項。
5. 提醒哪些項目需要 follow-up runtime gate。
6. 將決策結果寫成 `security_approval_decision_record_v1`，但維持 `execution_authorized=false`。
7. 將 gate item 包成 `security_approval_review_packet_v1`，只顯示 review lane、required reviewers 與仍禁止事項。
8. 依 `security_approval_state_transition_v1` 顯示 next state；`approve_scope` 仍只進入 waiting runtime gate。
9. 依 `security_followup_runtime_gate_v1` 顯示 minimum evidence、preflight checks 與 rollback / disable requirement，但不啟用 runtime gate。

## 4. AwoooP 不可做

1. 不自動批准。
2. 不在批准後自動執行。
3. 不把 approval queue 接成 runner。
4. 不啟動 scan、credentialed scan 或 Kali `/execute`。
5. 不建立 GitHub repo、不改 visibility、不 sync refs、不切 GitHub primary。
6. 不保存 raw secret、token、cookie、private key 或 exploit payload。

## 5. 階段定位

S3.0 只讓人工批准有一致語言與可稽核格式。

它仍然不是 runtime enforcement，也不是一次把資安等級拉滿。低風險與中風險觀察仍以 observe / warn 為主；只有不可逆或高風險動作才進 gate。

2026-05-17 S4.8 追加：Gitea gate 的批准範圍已改為 owner attestation 先行。`approve_scope` 最多允許補 S4.7 owner coverage attestation、更新 matrix / decision table，並在後續 runtime gate 準備妥當後才可做一次 read-only inventory；仍不得保存 token value、寫 Gitea、建立 GitHub repo、sync refs 或切 primary。

2026-05-17 S4.9 追加，2026-05-18 補 request packet、template status ledger、audit event templates、redaction examples、display sections 與 collection checks：Gitea gate 現在要求 AwoooP 先顯示 S4.9 owner response request packet 與五個 template statuses，並用 audit event templates / redaction examples / display sections / collection checks 確認只記錄 metadata、request / received / accepted 分離；owner response 依 S4.9 收件包通過 intake preflight checks、outcome lanes 與基本驗收後，才可把 S4.7 coverage attestation 視為可審 evidence。此驗收仍只更新 read-only matrix / decision table / readiness gate，不授權 inventory runtime、repo migration 或 GitHub primary。