# Telegram 通知出口 No-New-Bypass Guard

| 項目 | 內容 |
|------|------|
| 日期 | 2026-06-19 |
| 狀態 | `pass_no_new_bypass` |
| 工具 | `scripts/security/telegram-notification-egress-no-new-bypass-guard.py` |
| Snapshot | `docs/security/telegram-notification-egress-no-new-bypass-guard.snapshot.json` |
| Source snapshot | `docs/security/telegram-notification-egress-inventory.snapshot.json` |
| 模式 | repo source scan；不讀 secret、不送 Telegram、不修改 workflow / script / API sender |
| runtime gate | `0` |

## 1. 目的

`telegram_notification_egress_no_new_bypass_guard_v1` 用 committed inventory 當 baseline，掃描 repo source 是否新增未登記的 Telegram Bot API direct endpoint。目前 committed inventory 已讀回 `0` 個 direct `sendMessage` call site；本 guard 的目的改為維持 `0` 旁路，防止新 direct Bot API 在治理收斂後重新出現。

## 2. 掃描範圍

| 範圍 | 說明 |
|------|------|
| `.gitea/workflows` | Gitea Actions workflow 中的 direct Bot API |
| `scripts/ops` | 主機 / 備份 / DR 類 ops script |
| `scripts/ci` | CI helper script |
| `apps/api/src` | API sender 與 notification 相關 source |

Guard 目前保護的方法包含 `sendMessage`、`sendDocument`、`sendPhoto`、`sendMediaGroup`、`editMessageText`、`sendAnimation`、`sendVideo`、`sendAudio`、`sendVoice`。

## 3. 固定數字

| 指標 | 數值 | 解讀 |
|------|------|------|
| `source_direct_bot_api_call_count` | `0` | committed inventory 的 direct call baseline |
| `source_direct_bot_api_file_count` | `0` | committed inventory 的 direct file baseline |
| `baseline_signature_count` | `0` | baseline signature 數 |
| `current_direct_bot_api_call_count` | `0` | 目前掃描到的 direct call 數 |
| `current_direct_bot_api_file_count` | `0` | 目前掃描到的 direct file 數 |
| `guarded_method_count` | `9` | 受保護 Bot API method 數 |
| `sendMessage_call_count` | `0` | 目前沒有 direct `sendMessage` |
| `sendDocument_call_count` | `0` | 不允許新增附件型 direct send |
| `sendPhoto_call_count` | `0` | 不允許新增圖片型 direct send |
| `sendMediaGroup_call_count` | `0` | 不允許新增 media group direct send |
| `editMessageText_call_count` | `0` | 不允許新增 edit direct call |
| `new_bypass_count` | `0` | 新增未登記旁路必須維持 0 |
| `removed_baseline_call_count` | `0` | baseline 移除需另外走 migration evidence |
| `runtime_gate_count` | `0` | 不提供 runtime 執行授權 |

## 4. 判讀規則

- `new_bypass_count=0` 才代表沒有新增未登記 direct Bot API 旁路。
- 既有 direct `sendMessage` 已收斂到 `0`；任何新增 direct endpoint 都必須視為 regression。
- 若新增 `sendDocument`、`sendPhoto`、`sendMediaGroup` 等附件型出口，guard 會阻擋，必須先進 inventory、owner request、migration plan 與 acceptance ledger。
- 若未來出現 removed / added baseline 差異，不能只靠 guard 結果宣稱完成；仍需 migration evidence、delivery receipt 與 postcheck。

## 5. 禁止事項

本 guard 不得被解讀成以下授權：

- 送 Telegram 或呼叫 Bot API。
- 修改 workflow、ops script、API sender、chat route 或 Bot token。
- 讀 secret store、收 secret value / hash / partial token。
- 保存 raw payload、raw log 或未脫敏截圖。
- 開 runtime gate 或新增 action button。

## 6. 驗證指令

```bash
python3 scripts/security/telegram-notification-egress-no-new-bypass-guard.py --root .
python3 -m json.tool docs/security/telegram-notification-egress-no-new-bypass-guard.snapshot.json >/dev/null
python3 -m py_compile scripts/security/telegram-notification-egress-no-new-bypass-guard.py
python3 scripts/security/security-mirror-progress-guard.py --root .
```

## 7. 完成度

| 項目 | 完成度 | 邊界 |
|------|--------|------|
| No-new-bypass source guard | `100%` | 目前 `new_bypass_count=0` |
| Existing direct Bot API convergence | `100%` | repo source 已讀回 direct send `0` |
| Runtime execution | `0%` | 不送 Telegram、不呼叫 Bot API、不改 live route |