140 lines
7.5 KiB
Markdown
140 lines
7.5 KiB
Markdown
# 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%` | 未授權，未執行 |
|