# IwoooS Public Gateway 變更前置 Gate 只讀清冊

| 項目 | 內容 |
|------|------|
| 日期 | 2026-06-12 |
| 狀態 | `repo_only_preflight_contract_ready` |
| 工具 | `scripts/security/public-gateway-preflight-inventory.py` |
| Snapshot | `docs/security/public-gateway-preflight-inventory.snapshot.json` |
| Schema | `docs/schemas/public_gateway_preflight_inventory_v1.schema.json` |
| runtime gate | `0` |

## 1. 目的

Public gateway 是所有產品、後台、API、callback、Webhook、ACME 與 WebSocket 的入口。Nginx 或 reverse proxy 若被手動修改，可能造成公開路由錯轉、管理後台暴露、憑證路徑錯置、ACME renew 失敗、WebSocket 中斷或 AI provider proxy 失效。

本清冊把 Nginx reload / public route change 前必備證據固定成只讀 Gate：誰負責、影響哪些 route、是否有 live conf evidence、是否有 rendered diff、是否有 `nginx -t`、是否有 route smoke、是否有 rollback owner。它不做任何 live 操作。

## 1.1 2026-06-14 Live Conf Export Request

已新增 `docs/security/PUBLIC-GATEWAY-LIVE-CONF-EXPORT-REQUEST.md` 與 `docs/security/public-gateway-live-conf-export-request.snapshot.json`，將三份 public gateway source config 轉成 owner-provided live conf 匯出請求草稿。

目前固定為 `export_request_count=3`、`c0_export_request_count=2`、`redaction_rule_count=8`、`redacted_export_received_count=0`、`raw_live_conf_stored_count=0`。此 artifact 只表示未來可向 owner 請求脫敏 export ref，不代表 request sent、live conf received、rendered diff ready、`nginx -t`、reload、route smoke、DNS / TLS probe、certbot renew、host write 或 production write。

## 1.2 2026-06-14 Redacted Export Intake Preflight

已新增 `docs/security/PUBLIC-GATEWAY-REDACTED-EXPORT-INTAKE-PREFLIGHT.md` 與 `docs/security/public-gateway-redacted-export-intake-preflight.snapshot.json`，將三份 live conf export request 轉成 redacted export 收件前預檢候選。

目前固定為 `intake_candidate_count=3`、`c0_intake_candidate_count=2`、`validation_check_count=10`、`rejection_guard_count=12`、`reviewer_intake_lane_count=5`、`redacted_export_received_count=0`、`accepted_redacted_export_count=0`。此 artifact 只表示未來收到 ref 時的補件、隔離、拒收與 rendered diff preflight 分流，不代表 request sent、recipient confirmed、live conf received / accepted、raw live conf stored、rendered diff ready、`nginx -t`、reload、route smoke、DNS / TLS probe、certbot renew、host write 或 production write。

## 1.3 2026-06-14 Rendered Diff Gate Draft

已新增 `docs/security/PUBLIC-GATEWAY-RENDERED-DIFF-GATE-DRAFT.md` 與 `docs/security/public-gateway-rendered-diff-gate-draft.snapshot.json`，將三份 redacted export intake candidate 轉成 rendered diff、`nginx -t`、reload、route smoke 與 rollback / post-check 的分階段 gate 草稿。

目前固定為 `diff_gate_candidate_count=3`、`c0_diff_gate_candidate_count=2`、`preflight_stage_count=7`、`blocked_action_count=14`、`redacted_export_accepted_count=0`、`rendered_diff_ready_count=0`、`nginx_test_executed_count=0`、`runtime_gate_count=0`。此 artifact 只表示下一層 gate 的 required shape，不代表 live conf accepted、rendered diff produced、`nginx -t`、reload、route smoke、DNS / TLS probe、certbot renew、host write 或 production write。

## 1.4 2026-06-14 DNS / TLS / certbot Owner Confirmation Request

已新增 `docs/security/DOMAIN-TLS-CERTBOT-OWNER-CONFIRMATION-REQUEST.md` 與 `docs/security/domain-tls-certbot-owner-confirmation-request.snapshot.json`，將 4 個 certificate path 需確認的 domain 轉成 owner confirmation request 草稿。

目前固定為 `owner_confirmation_request_count=4`、`c0_owner_confirmation_request_count=4`、`required_owner_field_count=9`、`confirmation_question_count=5`、`rejection_guard_count=12`、`owner_response_received_count=0`、`owner_response_accepted_count=0`、`runtime_gate_count=0`。此 artifact 只表示 DNS / TLS owner confirmation 的 required shape，不代表 request sent、owner response accepted、DNS query、live TLS probe、certbot renew、Nginx reload、route smoke、host write 或 production write。

## 2. repo-only 摘要

| 指標 | 值 |
|------|----|
| Nginx source config | `3` |
| C0 source config | `2` |
| route impact | `14` |
| unique upstream | `14` |
| TLS certificate path | `10` |
| certificate owner 確認缺口 | `4` |
| ACME challenge domain | `7` |
| admin route domain | `1` |
| WebSocket route domain | `6` |
| preflight gate | `12` |
| repo-only ready gate | `2` |
| owner acceptance required gate | `10` |
| owner response / accepted | `0 / 0` |
| live conf / rendered diff / nginx -t / route smoke | `0 / 0 / 0 / 0` |
| maintenance window / rollback owner | `0 / 0` |
| runtime gate / action button | `0 / 0` |

## 3. 已納入的 public gateway source

| config id | 主機 | 角色 | 等級 | source |
|-----------|------|------|------|--------|
| `host188_all_sites` | `192.168.0.188` | public gateway all sites | C0 | `infra/ansible/roles/nginx/templates/188-all-sites.conf.j2` |
| `host188_internal_tools_https` | `192.168.0.188` | internal tools HTTPS | C0 | `infra/ansible/roles/nginx/templates/188-internal-tools-https.conf.j2` |
| `host110_ollama_proxy` | `192.168.0.110` | Ollama proxy gateway | C1 | `infra/ansible/roles/nginx/templates/110-ollama-proxy.conf.j2` |

## 4. Reload / route change 前置 Gate

| Gate | 內容 | 目前狀態 |
|------|------|----------|
| PG1 | source-of-truth hash | repo-only ready |
| PG2 | affected route list | repo-only ready |
| PG3 | owner response | `0` |
| PG4 | owner-provided live config | `0` |
| PG5 | rendered diff | `0` |
| PG6 | `nginx -t` evidence | `0` |
| PG7 | public route smoke | `0` |
| PG8 | admin route smoke | `0` |
| PG9 | WebSocket / API smoke | `0` |
| PG10 | ACME / TLS owner check | `0` |
| PG11 | maintenance window | `0` |
| PG12 | rollback owner and ref | `0` |

## 5. owner response 欄位

任何 public gateway 變更、live drift 判讀或 reload 候選，都至少要具備：

1. `owner_role_or_team`
2. `decision`
3. `decision_reason`
4. `affected_scope`
5. `redacted_evidence_refs`
6. `followup_owner`
7. `rollback_owner`
8. `maintenance_window`
9. `validation_plan`
10. `nginx_test_evidence_ref`
11. `route_smoke_evidence_ref`

## 6. 指令

更新 snapshot：

```bash
python3 scripts/security/public-gateway-preflight-inventory.py \
  --root . \
  --generated-at 2026-06-12T10:30:00+08:00 \
  --output docs/security/public-gateway-preflight-inventory.snapshot.json
```

只輸出目前清冊：

```bash
python3 scripts/security/public-gateway-preflight-inventory.py --root .
```

## 7. 邊界

1. 本清冊不執行 SSH。
2. 本清冊不讀 live Nginx conf。
3. 本清冊不執行 `nginx -t`。
4. 本清冊不 reload / restart Nginx。
5. 本清冊不做 DNS query、TLS probe 或 certbot renew。
6. 本清冊不修改主機、不改 DNS、不改憑證、不讀 private key。
7. IwoooS UI 可顯示 preflight Gate，但不得把卡片可見視為 owner 已確認或 runtime 已授權。

## 8. 完成度

| 工作 | 完成度 | 說明 |
|------|--------|------|
| public gateway preflight 契約 | `100%` | 已固定 12 個 reload / route change 前置 Gate |
| source-of-truth hash / affected route list | `100%` | 由既有 Nginx / DNS-TLS snapshot 推導 |
| owner response / live conf / rendered diff | `0%` | 尚未收到，不能宣稱 live 無漂移 |
| `nginx -t` / route smoke / rollback owner | `0%` | 尚未批准且未執行 |
| runtime reload / host write | `0%` | 未授權，未執行 |