awoooi/docs/security/PUBLIC-GATEWAY-PREFLIGHT-INVENTORY.md

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：

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

只輸出目前清冊：

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