# 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 操作。

## 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%` | 未授權，未執行 |
