# 資安人工審查封包契約

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

## 0. 核心結論

`security_approval_review_packet_v1` 是 S3.2 的人工審查封包格式。

它把 `security_approval_queue_v1` 與 `security_approval_gate_v1` 的 8 個審查項目整理成 AwoooP 可以顯示的 review packet，讓 Operator 看得懂「現在要審什麼、由誰審、可以做哪些決策、仍然禁止哪些動作」。

它不是批准結果，也不是執行授權。真正的人工決策仍必須另外寫入 `security_approval_decision_record_v1`，而且每筆紀錄都必須維持 `execution_authorized=false`。

S3.3 開始，決策後的 next state 由 `security_approval_state_transition_v1` 定義。這讓 AwoooP 能顯示 `approve_scope` 後仍在等待 runtime gate，而不是直接執行。

S3.4 開始，等待 runtime gate 時要看哪些前置條件，由 `security_followup_runtime_gate_v1` 顯示。這仍只是準備模板，不會啟用 runtime gate。

## 1. 目前狀態

| 指標 | 數量 |
|------|------|
| Review packets | 8 |
| Ready for human review | 7 |
| Block candidate | 1 |
| Decision records created | 0 |
| Runtime actions authorized | `false` |
| Action buttons allowed | `false` |

## 2. Review Packet 順序

| 順序 | Packet | Review lane | 初期定位 |
|------|--------|-------------|----------|
| 1 | Redacted finding ingestion | `design_or_draft_review` | 只審是否可設計或建立 draft PR |
| 2 | Safe web crawl | `low_noise_scan_scope_review` | 只審低噪音 scope 定義 |
| 3 | Gitea owner attestation + read-only inventory | `read_only_inventory_review` | 先依 S4.9 審 S4.7 owner response，再審只讀 token 或 redacted export |
| 4 | GitHub target decisions | `design_or_draft_review` | 先審 S4.10 owner response request packet / template status ledger / audit event templates / redaction examples / collection checks / intake preflight checks / response 與 S4.12 workflow / secret 名稱 request packet / template status ledger / audit event templates / redaction examples / collection checks / intake preflight checks / response，再審 owner / visibility / canonical 草案 |
| 5 | Ref truth review | `design_or_draft_review` | 先審 S4.11 request packet / template status ledger / audit event templates / redaction examples / collection checks / intake preflight checks / owner response 驗收，再審人工分類與 reconcile 草案 |
| 6 | Credentialed scan | `manual_exception_review` | 只審 exception 設計 |
| 7 | Kali full-upgrade / reboot | `manual_exception_review` | 只審維護窗口與 rollback 計畫 |
| 8 | Kali `/execute` | `blocked_by_default_review` | 預設維持 block candidate |

## 3. AwoooP 可做

1. 顯示 review packet、review order、risk、review lane 與 required reviewers。
2. 顯示 requested decision、decision options、evidence refs 與 still forbidden。
3. 讓人工 reviewer 選擇 approve / reject / defer / request more evidence / keep blocked。
4. 將實際決策另寫成 `security_approval_decision_record_v1`。
5. 依 `security_approval_state_transition_v1` 顯示決策後 next state。
6. 依 `security_followup_runtime_gate_v1` 顯示後續 runtime gate 準備條件。
7. 將 packet 作為 Operator Console / Audit evidence，不新增執行按鈕。

## 4. AwoooP 不可做

1. 不把 review packet 視為批准。
2. 不把 review packet 視為 runtime authorization。
3. 不因為 packet 存在就啟動 scan、credentialed scan 或 Kali `/execute`。
4. 不建立 GitHub repo、不改 visibility、不 sync refs、不切 GitHub primary。
5. 不保存 raw secret、token、cookie、private key、credential value 或 exploit payload。

## 5. 階段定位

S3.2 只補上「讓人好審」的封包，不提高資安阻力。

低風險與中風險仍以 observe / warn / draft review 為主；只有不可逆或高風險動作才持續留在 approval gate，且批准後仍必須再過 runtime gate。

2026-05-17 S4.8 追加：Gitea review packet 會顯示 S4.7 的 5 個 owner attestation items、`received_attestation_count=0` 與 `accepted_attestation_count=0`。這讓 reviewer 先判斷 coverage gap 與 scope decision，不會把 read-only inventory approval 誤解成 repo migration 或 GitHub primary approval。

2026-05-17 S4.9 追加，2026-05-18 補 request packet、template status ledger、audit event templates、redaction examples、display sections 與 collection checks：Gitea review packet 會顯示 S4.9 的 1 個 owner response request packet、5 個 template statuses、3 個 audit event templates、5 個 redaction examples、8 個 display sections、6 個 collection checks、5 個 owner response templates、6 個 intake preflight checks、5 個 outcome lanes、`received_response_count=0`、8 個 acceptance checks 與 10 個 rejection rules。reviewer 應先確認 request packet 只要求脫敏回覆，template statuses 仍逐項 waiting，audit event templates 仍為 template-only 且不保存 raw payload，redaction examples 只是填寫範例，display sections 只是只讀 UI 順序，collection checks 沒有把 request sent 誤判成 received / accepted，再看 response 是否可審、需補證、需隔離、需拒收或仍需等待，最後才看 read-only inventory gate；review packet 仍不代表批准，也不授權執行。