評估：圖片上傳遷移至 Cloudflare R2

[abc873693]

背景

目前 ap_common_announcement_ui 的圖片上傳由 ImgbbHelper / ImgurHelper 實作（位於 packages/ap_common_announcement_ui/lib/src/api/），兩者皆以硬編碼的匿名 client key 直接從 Flutter client 上傳。

延續 #139 的方向，評估進一步遷移至 Cloudflare R2 以降低對第三方免費圖床的依賴。

現況

• ImgbbHelper.uploadImage(XFile) 為 edit_page.dart 唯一使用的上傳器（按鈕文案仍為 pickAndUploadToImgur，實際呼叫 Imgbb）
• 兩個 helper 沒有共同 abstract interface，為 duck-typed（皆回傳 Future<ApiResult<String>>）
• API key 硬編碼在 class 中，無 runtime 注入機制
• 無檔案大小 / 格式預檢，僅靠 HTTP 400 回報 notSupportImageType

R2 的核心限制

R2 使用 S3 相容簽章認證，不能把 Access Key 放進 client app，必須搭配後端或 presigned URL。與 Imgur/Imgbb 的 anonymous upload 模式根本不同。

候選方案

方案	說明	成本	複雜度
A	Cloudflare Worker 產生 presigned PUT URL，client 直接 PUT	Worker 免費額度內 + R2 儲存費	中
B	Worker 作為 upload proxy，client 傳給 Worker，Worker 寫 R2	Worker CPU time 較貴	低
C	放棄 R2，沿用有 anonymous upload 的第三方服務	—	—

優缺點

優勢

• 無 egress 費用、可綁自訂 domain、保留政策可控
• 不再依賴第三方免費方案（Imgur 曾封鎖台灣 IP，見 Move from Imgur other service #139）
• 消除硬編碼 public key 的長期風險

成本 / 劣勢

• 需新增維運一個 Cloudflare Worker（目前 ap_common 生態無自有 backend）
• 多下游 App（NKUST / NSYSU / WTUC…）需設計共用或各自 bucket（多租戶）
• Abuse 防護需自行處理（rate limit、referer、檔案大小/類型驗證）

認證策略（若採用 Worker + R2）

前提：Mobile App 是可反編譯的 binary，無法 100% 證明「請求來自官方 App」。目標是疊加多層防線把 abuse 成本拉高。

候選機制

機制	強度	成本	備註
Shared header / API key	★	幾乎零	只擋懶鬼 bot，與現況同風險
Cloudflare Turnstile	★★	免費、有 mobile SDK	隱形 CAPTCHA
Play Integrity API (Android)	★★★★	Google 免費額度內	驗證 Play Store 版本、未 root
App Attest (iOS)	★★★★	Apple 免費	驗證 bundle ID + 裝置
綁定既有登入（推薦）	★★★★★	幾乎零（重用現有 auth）	見下方

推薦流程：登入綁定 + 短期 presigned URL

edit_page.dart 是公告編輯頁，照理只有管理員/登入使用者會用：

1. Worker 只接受帶有 ap_common App 登入 token 的請求
2. Worker 驗證 token → 簽發短期 presigned R2 URL（例如 5 分鐘有效）
3. 搭配 IP + 帳號雙層 rate limit（純 IP 會因 CGNAT / 校園網路誤殺）

Platform Attestation（Play Integrity / App Attest）作為 optional 加強層。

Rate limit 實作備選

• Workers Rate Limiting API（binding，GA、免費方案可用）— 最簡單
• Durable Objects — 需滑動視窗或跨區強一致時使用
• WAF Rate Limiting Rules — Dashboard 設定，進階規則需 Pro+

取 client IP 一律用 CF-Connecting-IP（邊緣注入、無法偽造），不要用 X-Forwarded-For。

建議的前置工作（不論是否採用 R2）

• 抽出 ImageUploader abstract interface，讓下游 App 可注入自訂實作
• 移除 edit_page.dart 中對 ImgbbHelper 的硬依賴
• 修正按鈕文案 pickAndUploadToImgur（與實際行為不符）

待決議

1. 是否值得為了圖片上傳新增 Worker 維運負擔？
2. 若採用 R2，多 App 共用 bucket vs. 各自 bucket？
3. 認證策略：是否能重用下游 App 的既有登入 token？各 App 的 auth 機制是否一致？
4. 短期替代方案：是否先完成 ImageUploader 抽象，把選擇權交給下游？

Related: #139

[abc873693]

Worker 實作 checklist

在 workers/upload-worker/ 放了 TypeScript 骨架（proxy 模式：client 傳 bytes → Worker 驗證 → 寫 R2 → 回傳公開 URL），以下是後續要釐清 / 補完的項目。

Endpoint 設計

• POST /upload（proxy 模式，直接收 body 寫 R2）
• 評估是否改 presigned PUT（減少 Worker CPU time，但 R2 presigned 需 SigV4，複雜度較高）
• 決定 R2 key 命名規則（目前：{YYYY/MM/DD}/{uuid}.{ext}）
• 成功回傳格式（目前：{ url: string }，與 Imgbb/Imgur 對齊）

認證

• 目前用 Authorization: Bearer <APP_SHARED_SECRET>（shared secret，與現況 Imgbb key 同等風險，TODO 標註）
• 評估升級為「綁定 ap_common 登入 token」— 需各下游 App auth 機制盤點
• 需要 Platform Attestation 嗎？（Play Integrity / App Attest）

Rate limit

• Workers Rate Limiting binding（10 次 / 60 秒 / IP）
• 補第二層（帳號 / token），避免 CGNAT 誤殺
• 決定超額懲罰策略（429 就退、還是遞增延遲？）

R2 bucket 配置

• 多下游 App 共用一個 bucket，或各自一個？
• 自訂網域（cdn.ap-common.dev 之類）
• 生命週期規則（過期自動清除？）
• 是否需備援（e.g. object replication）

CORS

• 目前允許 *（為 Flutter web 保留）
• 評估是否收斂到 ap_common App 白名單

輸入驗證

• Content-Type 白名單（jpg/png/webp/gif）
• Content-Length 上限（預設 10 MiB，可由 MAX_UPLOAD_BYTES 調整）
• Magic bytes 驗證（防 Content-Type 被偽造）— 進階，非必需

部署

• 建立 R2 bucket：wrangler r2 bucket create ap-common-images
• 建立 rate limit namespace 並更新 wrangler.toml 的 namespace_id
• wrangler secret put APP_SHARED_SECRET
• 設定 PUBLIC_URL_BASE 為實際的自訂網域
• wrangler deploy
• 新增 CI workflow（lint TypeScript、驗證 wrangler deploy dry-run）

Flutter 端（後續 PR）

• CloudflareR2Helper implements ImageUploader（目前 abstraction 在 評估：圖片上傳遷移至 Cloudflare R2 #183 的 PR 中）
• 在 edit_page.dart 注入為預設 uploader
• 下游 App（NKUST / NSYSU / WTUC）逐一更新

[abc873693]

⚠️ 開源前置：Worker 實作的安全評估

本 repo 為 MIT 開源，Worker 程式碼 / config / endpoint 結構全部公開。威脅模型要從「對手看不到程式碼」改為「對手連 config 都逐行讀過」。下面按風險優先序整理。

🔴 Critical：Shared Secret 認證在開源下形同無防護

目前 skeleton 用 Authorization: Bearer <APP_SHARED_SECRET>（wrangler secret put 存在 Cloudflare 側，不進 repo）。但 secret 必須打包進 Flutter App 才能使用，而：

• App binary 是公開下載的 APK/IPA，可反編譯
• App 原始碼就在本 repo，看 ImageUploader 實作即可抄出

結果：任何人都能 POST 到 Worker，用 R2 當免費圖床，帳單寄給維護者。這是開源 + 自有後端最大的差異 —— 現況 Imgur/Imgbb 沒這問題是因為成本在第三方。

解法候選（強度由低到高）：

• Platform Attestation：Play Integrity（Android）+ App Attest（iOS）— 驗證「Play Store 安裝、未 root」
• 登入綁定：Worker 驗證下游 App 既有校務登入 token 再發上傳權限
• 放棄自建：繼續用 Imgbb 或改用 Cloudflare Images（有內建 moderation）

🔴 Critical：成本暴露直接進維護者帳單

• R2 儲存：$0.015 / GB / 月
• Workers：免費 100k req/day，之後 $5 / 10M
• 攻擊者可用多 IP 輪替繞過 rate limit（目前 10/60s/IP）

必做：Cloudflare 端設 billing alert 與 spending cap。

🟠 High：wrangler.toml 內容即將公開

目前有 bucket_name、namespace_id、PUBLIC_URL_BASE 等。雖非「機密」，但：

• bucket_name 公開 → 若未設訪問控制可被 enumerate
• 多下游 App（NKUST / NSYSU / WTUC）各自部署需不同值

建議：改為 wrangler.toml.example，實際 wrangler.toml 進 .gitignore；或用 [env.production] 多環境切分。

🟠 High：任意內容上傳 → 法律責任

Content-Type 白名單只擋 header，不驗內容。攻擊者可：

• 上傳違法內容（兒少、版權侵害）→ bucket 持有者要處理 DMCA / 執法調閱
• 改 Content-Type 混淆（目前沒驗 magic bytes）

該做的：

• Magic bytes 驗證（讀 header bytes 比對 JPEG/PNG/WEBP/GIF signature）
• 公開 abuse report / takedown 流程
• 評估用 Cloudflare Images 取代（內建 moderation）

🟡 Medium：CI/CD 部署鏈的 supply-chain 風險

若後續加 GitHub Actions 自動部署：

• CF API token 在 GitHub Secrets
• 惡意 PR 合併即自動部署惡意 Worker（可轉發上傳內容、讀取 R2）

建議：部署只限 tag 或手動觸發，加 environment: production protection rule，不跟 PR merge 連動。

🟡 Medium：手寫的 RateLimit TS 介面脆弱

@cloudflare/workers-types 不一定含 Rate Limiting binding 型別（視版本），我自己寫了 local interface。升級 wrangler 時容易漂移。

建議：pin wrangler 版本，升級時跑 wrangler types 重產。

🟡 Medium：bucket 公開 URL 可被 leech

URL 採 UUID 命名（不可猜），但任何發出的圖片 URL 等於永久公開。公告配圖場景 OK，若之後有私有內容就不適用。

🟢 Low / Tech-debt

• 未 strip EXIF（可能洩漏使用者 GPS / 裝置）
• 無稽核 log（事後追查哪個 IP/token 上傳過 key X 會很痛）
• 10 MiB 上限只擋 Content-Length，沒擋 chunked upload 繞過

---

前置門檻（建議 Worker 合併前要過）

• 認證模型拍板：Platform Attestation / 登入綁定 / 放棄自建，三擇一
• wrangler.toml → wrangler.toml.example，實際 config 不進 repo
• 加 magic bytes 驗證
• README 明示「當前認證等同無保護，不得用於生產」直到上一項完成
• Cloudflare 端 billing alert / spending cap
• 部署 workflow 的觸發條件（tag / 手動 only，不跟 PR merge 綁定）

目前進度與分支

• 分支 feature/183-image-upload-refactor 的工作已 stash 保留，尚未 commit
• stash 內容：
  • Flutter 端 ImageUploader abstraction + i18n 去 Imgur 綁定
  • Worker skeleton（workers/upload-worker/，當前狀態僅可作為設計參考、不可部署）
• Flutter abstraction PR 可獨立先走（與 Worker 認證決策解耦）；Worker 部分等認證策略拍板後再出