103 lines
6.0 KiB
Markdown
103 lines
6.0 KiB
Markdown
# Telegram 通知出口 Owner Request 草稿
|
||
|
||
| 項目 | 內容 |
|
||
|------|------|
|
||
| 日期 | 2026-06-18 |
|
||
| 狀態 | `owner_request_draft_ready_no_dispatch_no_runtime_action` |
|
||
| 工具 | `scripts/security/telegram-notification-egress-owner-request-draft.py` |
|
||
| Snapshot | `docs/security/telegram-notification-egress-owner-request-draft.snapshot.json` |
|
||
| Source snapshot | `docs/security/telegram-notification-egress-inventory.snapshot.json` |
|
||
| 模式 | metadata-only；不送 request、不確認 recipient、不送 Telegram、不改 workflow / script |
|
||
| runtime gate | `0` |
|
||
|
||
## 1. 目的
|
||
|
||
`telegram_notification_egress_inventory_v1` 已確認 repo 內仍有 `18` 個 direct Bot API `sendMessage` call site，分散在 `11` 個檔案。這份 Owner Request 草稿把 call site 依檔案聚合成 `11` 份人工送件前草稿，要求 owner 判定每個通知出口要如何收斂：
|
||
|
||
- 改走 `TelegramGateway` final-exit formatter。
|
||
- 改走 AWOOI Alertmanager / webhook 入口，再由 TelegramGateway 發送。
|
||
- 保留為明確的 break-glass fallback，但必須有訊息形狀、redaction、delivery receipt 與 no-false-green gate。
|
||
|
||
本文件不是 request sent，也不是批准修改 workflow、script、API sender 或 Telegram route。
|
||
|
||
## 2. 固定數字
|
||
|
||
| 指標 | 數值 | 解讀 |
|
||
|------|------|------|
|
||
| `source_direct_bot_api_call_count` | `18` | 來源清冊中的 direct send call site |
|
||
| `source_direct_bot_api_file_count` | `11` | 來源清冊中的 direct send 檔案 |
|
||
| `request_draft_count` | `11` | 每個檔案一份 owner request 草稿 |
|
||
| `workflow_request_draft_count` | `6` | Gitea workflow 草稿 |
|
||
| `ops_script_request_draft_count` | `4` | ops script 草稿 |
|
||
| `api_direct_request_draft_count` | `1` | API direct sender 草稿 |
|
||
| `request_field_count` | `27` | 草稿 envelope 欄位 |
|
||
| `required_owner_field_count` | `19` | owner 必填欄位 |
|
||
| `preflight_check_count` | `16` | 送件前預檢 |
|
||
| `outcome_lane_count` | `9` | 收件結果分流 |
|
||
| `forbidden_payload_count` | `14` | 禁止提交的 payload 類型 |
|
||
| `blocked_action_count` | `26` | 草稿階段禁止動作 |
|
||
|
||
所有 request sent、recipient confirmed、audit event emitted、owner response received / accepted、formatter convergence accepted、delivery receipt accepted、break-glass fallback accepted、direct Bot API migration authorized、Telegram send、Bot API call、workflow / script modification、API sender refactor、secret collection、raw payload storage、production write、runtime gate 與 action button 都維持 `0 / false`。
|
||
|
||
## 3. Owner 必填欄位
|
||
|
||
每份草稿至少需要 owner 提供：
|
||
|
||
1. `owner_role_or_team`
|
||
2. `routing_purpose`
|
||
3. `current_sender`
|
||
4. `target_chat_route`
|
||
5. `message_shape_contract`
|
||
6. `redaction_contract`
|
||
7. `formatter_convergence_decision`
|
||
8. `gateway_or_alertmanager_target`
|
||
9. `break_glass_fallback_decision`
|
||
10. `delivery_receipt_ref`
|
||
11. `dedup_or_fingerprint_plan`
|
||
12. `fallback_or_degraded_mode`
|
||
13. `migration_or_exception_reason`
|
||
14. `maintenance_window`
|
||
15. `rollback_owner`
|
||
16. `postcheck_evidence_ref`
|
||
17. `no_secret_value_attestation`
|
||
18. `no_raw_payload_attestation`
|
||
19. `no_false_green_attestation`
|
||
|
||
Owner 回覆只能提供 metadata / ref，不得包含 Bot token、chat secret、secret hash、partial token、masked token、authorization header、raw message payload、raw workflow log、raw action log、未脫敏截圖、內部工作視窗逐字稿、private namespace、未脫敏內部路徑或內網 IP。
|
||
|
||
## 4. Preflight checks
|
||
|
||
送件前必須確認：
|
||
|
||
- source inventory 是目前版本，且 draft count 與 direct file count 一致。
|
||
- owner role、route purpose、message shape、redaction contract、formatter convergence decision 都存在。
|
||
- break-glass fallback 必須顯式標示；不能把 fallback 當主路徑偷渡。
|
||
- delivery receipt、dedup / fingerprint、maintenance window、rollback owner 與 post-check evidence 都已指定。
|
||
- no-secret-value、no-raw-payload、no-false-green attestation 都存在。
|
||
- runtime gate 維持 0；草稿不能送 Telegram、dispatch workflow、修改 script 或重構 API sender。
|
||
|
||
## 5. Outcome lanes
|
||
|
||
| Lane | 說明 |
|
||
|------|------|
|
||
| `draft_waiting_owner_dispatch` | 草稿待人工送件，request sent 仍為 0 |
|
||
| `request_owner_route_supplement` | 缺 owner、route、purpose |
|
||
| `request_formatter_convergence_supplement` | 缺 formatter convergence decision 或 target |
|
||
| `request_break_glass_fallback_supplement` | 缺 fallback decision 或 exception reason |
|
||
| `request_redaction_or_receipt_supplement` | 缺 redaction contract、receipt 或 dedup plan |
|
||
| `quarantine_secret_or_raw_payload` | 收到 secret / raw payload / raw log 時隔離 |
|
||
| `reject_false_green_claim` | 把 CD success、route 200、UI 可見或 Telegram 送達當驗收時拒收 |
|
||
| `ready_for_manual_dispatch` | 草稿 metadata 完整，可由人工送件 |
|
||
| `waiting_runtime_gate` | 即使回覆 accepted，runtime send / 修改仍需獨立批准 |
|
||
|
||
## 6. 禁止動作
|
||
|
||
此草稿階段禁止送 owner request、確認 recipient、emit audit event、送 Telegram、呼叫 Bot API、改 workflow、改 script、重構 API sender、改 chat route、改 Bot token、讀 secret store、收 secret value / hash / partial token / chat id secret、保存 raw message payload / 未脫敏 log、workflow dispatch、production deploy、把 CD success / route 200 / UI 可見當 delivery receipt、跳過 formatter convergence、跳過 redaction contract、開 runtime gate 或新增 action button。
|
||
|
||
## 7. 下一步
|
||
|
||
1. `docs/security/TELEGRAM-NOTIFICATION-EGRESS-MIGRATION-PLAN-DRAFT.md` 已把 11 份草稿排成三個遷移波次；migration authorized 仍為 `0`。
|
||
2. 人工確認送件對象與 route owner 後，才可把這 11 份草稿送出；送出本身需另有 audit event，不由本 snapshot 代替。
|
||
3. 收到 owner response 後，先做 intake preflight：欄位完整、無 secret value、無 raw payload、無 false-green claim。
|
||
4. 通過 reviewer 後，才可為每個 surface 進實作；workflow / script / API sender 修改仍需獨立維護窗口、rollback owner 與 production post-check。
|