三問設計法

每個 gate 設計時回答三個問題：

成功時做什麼

Gate 通過後使用者進入下一步。這是最直覺的設計 — 認證成功進入主畫面、網路連線成功開始載入資料、權限授予後啟用功能。

成功路徑通常是設計時最先考慮的，也是最不容易遺漏的。

失敗時做什麼

Gate 未通過時使用者的替代路徑。替代路徑可以是：降級功能（部分功能可用）、替代驗證方式（密碼代替 Face ID）、手動重試（重試按鈕）、放棄操作（返回上一頁）。

失敗路徑是最容易遺漏的。app_tunnel 的 biometric gate 設定 biometricOnly: true，Face ID 不可用時使用者直接被擋住，沒有密碼 fallback、沒有跳過選項、沒有返回路徑（U.C2）。修復只改一個 boolean — biometricOnly: false — 讓系統自動提示輸入裝置密碼。但這個決策應該在企劃階段做，而非實機測試時才發現。

使用者不知道發生什麼時做什麼

Gate 處理中（loading）或結果不確定（timeout）時使用者看到什麼、能做什麼。

使用者不知道發生什麼的情境包括：認證彈窗尚未出現（系統延遲）、網路請求已發但未回應（loading）、權限對話框被系統遮擋（多個 dialog 堆疊）。

在這個狀態下使用者需要的是：知道系統在做什麼（loading 指示）、可以取消等待（取消按鈕）、超過合理時間後有提示（timeout 訊息 + 重試選項）。

Gate 的四種常見類型

認證 Gate

使用者必須驗證身份才能使用功能。生物辨識、密碼、PIN 碼、OAuth 登入。

認證 gate 的 fallback 設計取決於安全需求和使用場景。銀行 app 可能要求生物辨識 + PIN 碼雙重驗證，沒有更低層級的 fallback。自用工具可以接受密碼 fallback，因為使用者本身就是 owner — 可用性優先於認證強度（U.C2）。

網路 Gate

功能需要網路連線才能運作。連線存在但不穩定的場景比完全離線更難處理 — 請求可能成功、可能逾時、可能部分成功。

權限 Gate

App 需要系統權限（相機、位置、通知）才能使用特定功能。

權限 gate 的特殊性在於使用者可以永久拒絕。拒絕後再次請求不會彈出系統對話框 — 必須引導使用者到系統設定手動開啟。

環境 Gate

特定的硬體或軟體條件必須滿足。最低 OS 版本、特定感測器（NFC、深度相機）、特定連接（藍牙已開啟）。

環境 gate 的 fallback 通常有限 — 硬體不存在時無法用軟體模擬。但至少應該告知使用者為什麼功能不可用，而非靜默禁用。

其他常見 Gate

商業 app 還有兩種 gate 在本系列涵蓋範圍之外但實務常見：

付費 Gate（paywall）：功能需要付費才能使用。付費 gate 的 fallback 設計和上述四種不同 — 「失敗」路徑的目標是引導使用者付費而非提供替代功能。試用期、降級功能、付費引導 vs 付費強制的取捨依賴商業模式決策。

版本相容性 Gate：API 版本過舊需要升級 app。Fallback 是提示使用者更新，但強制更新會阻擋無法更新的使用者（舊 OS 版本不支援新版 app）。

Gate 設計表

把三問設計法應用到每個 gate，產出一張設計表：

失敗欄和不確定欄為空的 gate 就是 UX 死胡同的候選 — 和畫面狀態矩陣的退出路徑檢查同樣的邏輯。

三問設計法的具體應用在 Biometric fallback 完整設計中以生物辨識 gate 為例展開。Gate 在開發環境的行為可能和真機不同，開發環境 vs 真機的 gate 行為差異表列出每個 gate 在模擬器和真機上的差異。Gate 設計表的「失敗」欄和畫面狀態矩陣的「退出路徑」欄是同一個問題在不同層級的表達。

生物辨識失敗的情境

生物辨識失敗有多種原因，每種原因對使用者的影響和合理的 fallback 不同。

暫時性失敗

Face ID 因光線不足辨識失敗、指紋因手指潮濕讀取失敗。使用者的生物特徵正常，只是當次辨識條件不佳。重試可能成功。

持續性失敗

使用者戴口罩讓 Face ID 無法辨識（較舊的 iOS 版本）、手指受傷影響指紋辨識。生物特徵暫時改變，短期內重試都不會成功。需要替代認證方式。

硬體不可用

裝置沒有 Face ID / Touch ID 模組（較舊機型）、模擬器不支援生物辨識、生物辨識功能被裝置管理策略（MDM）禁用。需要替代認證方式。

使用者未設定

裝置有硬體但使用者沒有設定 Face ID 或指紋。系統的 canCheckBiometrics 回傳 true（硬體存在）但實際認證會失敗。需要引導使用者設定或提供替代認證。

iOS 和 Android 的行為差異

iOS（LocalAuthentication）

iOS 的 LAContext.evaluatePolicy 有兩個 policy：

• deviceOwnerAuthenticationWithBiometrics：只接受生物辨識，失敗後不自動提示密碼
• deviceOwnerAuthentication：先嘗試生物辨識，失敗後系統自動彈出裝置密碼輸入

Flutter 的 local_auth 套件的 biometricOnly 參數對應這兩個 policy。biometricOnly: true 用前者，biometricOnly: false 用後者。

iOS 的行為特點：系統控制認證 UI（不是 app 自行繪製），認證失敗次數過多會自動鎖定（需要輸入密碼解鎖），Face ID 多次失敗後系統會自動提供密碼選項（即使 app 要求 biometricOnly）。

Android（BiometricPrompt）

Android 的 BiometricPrompt 分成三個 class：

• BIOMETRIC_STRONG：只接受 Class 3 生物辨識（經過硬體安全模組驗證的指紋/面部）
• BIOMETRIC_WEAK：接受 Class 2 和 Class 3 生物辨識
• DEVICE_CREDENTIAL：接受裝置 PIN/圖形/密碼

三個 class 可以用 | 組合。BIOMETRIC_STRONG | DEVICE_CREDENTIAL 表示先嘗試強生物辨識，失敗後 fallback 到裝置密碼。

Android 的行為特點：不同廠商的生物辨識品質差異大（Samsung 的面部辨識和 Pixel 的面部辨識安全等級不同）、部分裝置的指紋感測器在螢幕下方（使用者可能不知道在哪裡觸碰）。

安全 vs 可用性的顯式取捨

biometricOnly 的決策涉及安全和可用性的取捨。這個取捨應該在功能規格中顯式記錄，讓後續的 code review 和維護者能理解決策的背景。

記錄格式建議：

1Gate: biometric authentication
2Decision: biometricOnly = false (allow device credential fallback)
3Security trade-off: device credential (PIN/password) is weaker than biometric
4Rationale: self-hosted tool, user = owner, availability > auth strength
5Risk accepted: someone with device PIN can access the app

app_tunnel 選擇 biometricOnly: true 的原始意圖是「安全性更高」，但沒有顯式記錄取捨，也沒有評估「Face ID 不可用時使用者完全無法使用 app」的代價。自用工具的使用者就是 owner，密碼 fallback 的安全風險遠低於完全無法使用的可用性風險（U.C2）。

下一步路由

• Gate 設計的通用方法論 → Gate 分類與三問設計法
• 開發環境遮蔽 gate 問題 → 開發環境 vs 真機的 gate 行為差異表
• 安全 vs 可用性在 monitoring 中的對應 → monitoring 模組七 資安

概念位置

UX 語境的 gate 聚焦在使用者體驗層 — 關注的是「使用者被擋住時看到什麼、能做什麼」。和 backend 語境的 gate decision 不同，後者關注的是部署流程中的品質關卡。Gate 的失敗路徑和不確定路徑應該反映在畫面狀態矩陣的退出路徑欄中。

可觀察訊號與例子

需要 gate 設計的訊號是使用者在某個功能前被阻擋且沒有替代路徑。常見情境：biometric 認證失敗後使用者無法進入 app、網路斷線後使用者被困在 loading 畫面、權限被拒後功能靜默消失但使用者不知道為什麼。

設計責任

Gate 的設計責任是確保每條路徑都有明確的使用者體驗。成功路徑通常最先被設計；失敗路徑需要提供 UX fallback（替代驗證、降級功能、返回上一頁）；不確定路徑需要 loading 指示和取消操作。開發環境可能遮蔽 gate 問題 — 模擬器跳過認證、debug build 自動授權 — 差異表讓開發者在上機前知道哪些 gate 還沒被真實驗證。

觀察

ttyd WebSocket 協議要求連線建立後發送一個 JSON frame 包含 base64 編碼的帳密（{"AuthToken":"base64(user:pass)"}），ttyd 驗證通過後才開始推送 terminal output。app_tunnel 的 ConnectionManager 建立 WS 連線後直接開始監聽 stream，沒有發送 auth token。

判讀

1. Mock 的 happy path 比真實服務寬鬆。FakeWebSocketChannel 的 ready 是 Future.value()（立即完成），stream 是開發者手動控制的 StreamController。真實 ttyd 的行為是：ready 完成代表 TCP+WS 握手成功，但 stream 要等 auth token 驗證後才有資料。Mock 把兩步合成一步。

2. Integration test 名為整合實為 fake。connection_flow_test.dart 標題是「端對端整合測試」，但內部使用 FakeWebSocketChannel + FakeBiometricService + InMemoryCredentialRepository — 三個核心依賴全是 fake。這個 test 驗證的是「假設所有外部服務都正常，內部狀態機是否正確」，不是「真實服務互動是否正確」。

3. 功能缺失比功能錯誤更難被 test 抓到。功能錯誤（T.C1 text vs binary）至少有一個實作可以斷言；功能缺失意味著沒有程式碼可以 test。只有 protocol integration test（對真實服務跑）才能暴露「應該有但沒有」的行為。

策略

1. Protocol integration test 必須涵蓋 auth handshake：連線 → 發送正確 auth token → 斷言收到 output；連線 → 不發送 auth token → 斷言 timeout 或斷線。
2. 在企劃階段列出協議握手步驟：ttyd WS 協議的 auth handshake 應該在 spec 文件中明確列出，不依賴開發者記得實作。
3. 區分「名義 integration」和「真實 integration」：test 名稱含 integration 但全用 fake，應標明 fake-integration 或改名 connection-state-machine-test。

下一步路由

• 想區分 mock 層級 → 模組一：測試策略分層
• 想建 protocol integration test → 模組三：協議整合測試
• 想設計 auth 機制的 UX fallback → U.C2 biometricOnly 無 fallback

觀察

app_tunnel 使用 local_auth 套件進行生物辨識認證。AuthenticationOptions 設定 biometricOnly: true，表示只接受生物辨識（Face ID / 指紋），不接受裝置密碼作為 fallback。

 1// 修復前
 2options: const AuthenticationOptions(
 3  stickyAuth: true,
 4  biometricOnly: true,  // Face ID 不可用 → 認證直接失敗
 5),
 6
 7// 修復後
 8options: const AuthenticationOptions(
 9  stickyAuth: true,
10  biometricOnly: false, // Face ID 不可用 → 系統自動提示輸入裝置密碼
11),

判讀

1. Gate fallback 是設計問題，不是實作問題。biometricOnly 的預設值是 false（允許密碼 fallback），開發時特意改成 true 是因為認為「安全性更高」。但這個判斷沒有考慮 fallback 缺失時的 UX 代價 — 使用者完全無法進入 app。

2. 開發環境遮蔽了問題。iOS 模擬器預設不支援 Face ID，但 isAvailable() 的實作會檢查 isDeviceSupported() + getAvailableBiometrics().isNotEmpty。模擬器回傳 isDeviceSupported() = true 但 getAvailableBiometrics() = []，所以在模擬器上 isAvailable() 回傳 false，直接跳過認證走預設路徑。真實裝置上 isAvailable() = true 但 Face ID 可能失敗，這時沒有 fallback。

3. 安全性 vs 可用性的取捨需要顯式記錄。biometricOnly: true 的安全收益是「確保只有生物特徵擁有者能操作」；代價是「任何生物辨識失敗場景都阻擋使用」。自用工具的使用者就是 owner，密碼 fallback 的安全風險遠低於「完全無法使用」的可用性風險。

策略

1. 每個 gate 設計時列三問：成功時做什麼？失敗時做什麼？使用者不知道發生什麼時做什麼？
2. 在狀態矩陣標注 gate fallback：biometric / network / auth 每個 gate 旁邊標注替代路徑，空白 = 使用者被擋住。
3. 安全 vs 可用性取捨顯式記錄：在 spec 文件記錄「biometricOnly: false — 接受密碼 fallback，因為自用工具可用性優先於生物辨識強制」。

下一步路由

• 想設計 Gate fallback 體系 → Gate 分類與三問設計法
• 想了解 biometric 在不同平台的行為差異 → 待補：iOS/Android biometric API 行為對照
• 類似案例（導航死胡同）→ U.C1 五個狀態零個退出

對應 findings

待寫章節

• Gate 分類與三問設計法（成功 / 失敗 / 使用者不知道發生什麼）
• Biometric fallback 完整設計（iOS/Android 差異）
• 網路斷線 UX 模式（offline-first / retry / degraded mode）
• Permission 請求時機與措辭
• 開發環境 vs 真機的 gate 行為差異表

跨分類引用

• → testing 模組一 測試策略：gate fallback 的 mock vs 真機行為差異需要 protocol test
• → monitoring 模組七 資安：biometric fallback 的安全 vs 可用性取捨

認證：來源是誰

認證驗證送出資料的 client 是否合法。未認證的 request 應該被拒絕，避免任意來源向 collector 寫入資料。

API Key 認證

每個合法的 SDK client 有一個 API key。Collector 檢查 request header 中的 API key 是否在合法清單中。

 1func authMiddleware(next http.Handler) http.Handler {
 2    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 3        key := r.Header.Get("X-API-Key")
 4        if !isValidKey(key) {
 5            http.Error(w, "unauthorized", http.StatusUnauthorized)
 6            return
 7        }
 8        next.ServeHTTP(w, r)
 9    })
10}

自用工具場景下，一個 API key 對應一個 client 通常就足夠。多個 client（例如同一個 app 的 iOS 和 Android 版本）可以用同一個 key，或每個平台一個 key 以便在 access log 中區分來源。

mTLS（Mutual TLS）

Client 和 server 互相驗證對方的憑證。安全性比 API key 高 — 攻擊者即使取得 API key，沒有 client 憑證也無法連線。

mTLS 的設定成本較高（每個 client 需要產生和管理憑證），適合對安全性要求較高的環境。自用工具通常不需要 mTLS。

授權：允許做什麼

授權控制已認證的 client 可以執行哪些操作。Collector 的操作通常分為兩類：寫入事件和查詢事件。

角色分離

最簡單的授權模型是兩個角色：

• Writer：只能寫入事件（POST /events）。SDK client 使用這個角色。
• Reader：只能查詢事件（GET /events、GET /query）。開發者的 CLI 工具使用這個角色。

角色分離的價值在於限制洩漏的影響範圍。如果 SDK 的 API key 被洩漏，攻擊者只能寫入（產生垃圾事件），不能讀取（看到歷史事件中的敏感資訊）。

寫入限制

即使認證通過、角色正確，collector 也可以對寫入加上限制：

• Rate limit：每個 API key 每分鐘最多 N 個 request。防止 client 端 bug 導致事件風暴。
• Payload size limit：每個事件最大 M KB。防止異常大的 event data 消耗儲存。
• Schema validation：事件必須符合定義的 JSON schema。格式不正確的事件拒絕存入。

Access Log：誰做了什麼

Access log 記錄每個到達 collector 的 request — 來源 IP、API key（或 key 的 hash）、操作類型、時間戳、response status。

Access log 的用途：

安全審計：發現異常行為 — 未知 IP 的大量寫入、非工作時間的讀取、連續的認證失敗。

問題排查：SDK 說事件送出成功但 collector 沒有收到 — access log 可以確認 request 是否到達、response 是什麼。

用量統計：每個 client 送了多少事件、佔多少儲存。

Access log 本身也是監控資料，但和業務事件分開儲存。Access log 存在 collector 本機的 log 檔中，用系統的 logrotate 管理輪替。

12026-06-19T10:30:00Z POST /events key=sk_mon_ab...cd ip=192.168.1.50 status=200 size=1234
22026-06-19T10:30:01Z POST /events key=INVALID ip=10.0.0.99 status=401 size=0
32026-06-19T10:31:00Z GET /query key=sk_read_ef...gh ip=192.168.1.1 status=200 size=8901

下一步路由

• SDK 端的 redaction → SDK Redaction API 設計
• Transport 層的加密 → Transport 安全
• 資料儲存後的去識別化 → 去識別化策略
• Client-side credential 暴露的根本限制 → Client-side SDK 認證

這個限制來自 architecture，和 implementation 無關。混淆 JS、ProGuard 混淆 APK、編譯 Python 成 .pyc，都只增加提取成本，不改變「credential 在 client 端」的事實。

Collector Access Control 討論了 API key 和 mTLS 的認證機制，Transport 安全 討論了傳輸層加密。兩者的前提是 credential 被妥善保管。本章處理的是那個前提不成立時 — credential 已被提取或必然可被提取 — 的緩解策略。

商業方案的處理方式

所有主流的 client-side telemetry 方案都面對同樣的限制。它們的共同策略是：承認 client credential 會暴露，把防線從「保護 credential」轉移到「限制 credential 被濫用的影響」。

Google Analytics 4：Measurement ID（G-XXXXXXXXXX）直接寫在網頁的 JS snippet 中，任何人檢視網頁原始碼都能取得。GA4 的防護在 server-side — Google 用 domain 白名單過濾來源，加上自動的 bot traffic 偵測剔除機器流量。Measurement Protocol（server-to-server）需要額外的 API secret，但 client-side 的 gtag.js 不需要。

Sentry：DSN（Data Source Name）包含 project ID 和 public key，直接嵌在 SDK init 的程式碼中。Sentry 官方文件明確標示 DSN 是 public 的 — 攻擊者取得 DSN 只能送事件，不能讀取已收集的資料。防護靠 rate limit（每個 project 的 events/sec 上限）、allowed domains（只接受來自白名單 domain 的事件）、和 server-side 的 event 去重。

Firebase：整個 google-services.json / GoogleService-Info.plist 的內容 — 包含 apiKey、projectId、appId — 都視為公開資訊。Firebase 的安全模型不依賴這些 key 的保密性；它們的功能是識別（identify）而非授權（authorize）。需要保護的資源靠 Firebase Security Rules 和 App Check（device attestation）處理。

Datadog RUM：Client token 是獨立於 API key 的 credential。API key 可以讀寫所有 Datadog 資料，必須保護在 server-side；client token 只能寫入 RUM 事件，設計上可以暴露在 client 端。Datadog 建議搭配 intake proxy（collector 前面加一層自己的 server），讓 client token 不直接出現在瀏覽器中。

這些方案的共同模式：client-side credential 的角色是「識別來源」而非「授權存取」。即使被提取，攻擊者能做的事被限縮在「寫入事件」— 影響可控。

認證天花板：識別 vs 授權

Collector Access Control 的 API key 同時承擔識別和授權 — 有 key 就能寫入，沒 key 就被拒絕。在 server-side 場景下這沒有問題，因為 key 不會暴露。

Client-side 場景需要拆開這兩個功能：

識別（identification）：這個 request 來自哪個 app、哪個 SDK、哪個部署版本。識別資訊可以公開 — 它的價值是讓 collector 知道事件來自哪裡，用於 access log、per-app rate limit、和事件標記。

授權（authorization）：這個 request 有沒有權限執行寫入操作。授權依賴 credential 的保密性 — 在 client-side 場景下，credential 保密性的天花板很低。

接受這個區分後，client-side SDK 的 API key 更接近「識別 token」。它的洩漏不是安全事件（像 server-side API key 洩漏那樣），而是預期中的狀態。防護的重點從「防止 key 洩漏」轉移到「限制 key 被濫用時的影響」。

多層緩解策略

以下各層按實作成本遞增排列。前面的層在多數場景下足夠，後面的層在 endpoint 暴露在公開網路且面對主動攻擊時才需要。

第一層：寫入限制（collector 已有）

Collector Access Control 的寫入限制 — rate limit、payload size limit、schema validation — 是第一層防護。這些機制不區分「合法 SDK」和「偽造 client」，對所有寫入請求一視同仁地施加約束。

Rate limit 限制每個 API key 的事件速率。Schema validation 拒絕不符合 event.schema.json 結構的 payload。兩者合起來把偽造流量的影響限制在「每秒 N 筆符合 schema 的事件」— 這個量級的資料汙染對 error tracking 的影響有限（error 事件靠 stack trace fingerprint 去重），對 funnel 分析的影響較大（行為事件的計數會被灌水）。

第二層：Origin 驗證

Web SDK 的 HTTP request 帶有瀏覽器自動附加的 Origin header。Collector 可以檢查 Origin 是否在白名單中。

 1func originCheck(next http.Handler, allowed []string) http.Handler {
 2    allowedSet := make(map[string]bool)
 3    for _, o := range allowed {
 4        allowedSet[o] = true
 5    }
 6    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 7        origin := r.Header.Get("Origin")
 8        if origin != "" && !allowedSet[origin] {
 9            http.Error(w, "forbidden origin", http.StatusForbidden)
10            return
11        }
12        next.ServeHTTP(w, r)
13    })
14}

Origin 驗證擋住的是「從瀏覽器中跨域呼叫」的場景 — 攻擊者在自己的網站用 JS 向你的 collector 發 request，瀏覽器會帶上攻擊者網站的 Origin，被 collector 拒絕。

天花板：Origin header 只有瀏覽器會自動附加。用 curl、Postman、或任何非瀏覽器 HTTP client 發 request 時，可以自行設定任意 Origin 值。Origin 驗證擋得住瀏覽器中的跨域呼叫，擋不住直接用 HTTP client 偽造的 request。

Mobile SDK（Flutter / native app）的 request 不帶 Origin header。Origin 驗證只對 Web SDK 有效。

第三層：Request signing

SDK 用 HMAC 對每個 request 簽章，collector 驗證簽章有效性。簽章的輸入包含 timestamp 和 payload hash，防止 replay attack 和 payload 竄改。

1X-Signature: a3f8c2e1b7d94f06...  (HMAC-SHA256 結果的 hex 編碼)
2X-Timestamp: 1719216000

SDK 計算方式：HMAC-SHA256(secret, timestamp + "." + SHA256(body))，結果轉 hex 字串放入 X-Signature header。

Collector 端的驗證邏輯：

 1func verifySignature(r *http.Request, secret string) bool {
 2    ts := r.Header.Get("X-Timestamp")
 3    sig := r.Header.Get("X-Signature")
 4
 5    // 拒絕超過 5 分鐘的 request timestamp（防 replay）
 6    // 5 分鐘容忍 client-server 時鐘漂移和網路延遲；行動裝置偏差大的環境可放寬到 10 分鐘
 7    // 此處的 timestamp 是 HTTP request 發出時間，和事件的 timestamp 欄位（事件產生時間）無關
 8    tsInt, err := strconv.ParseInt(ts, 10, 64)
 9    if err != nil || abs(time.Now().Unix()-tsInt) > 300 {
10        return false
11    }
12
13    body, _ := io.ReadAll(r.Body)
14    bodyHash := sha256.Sum256(body)
15    expected := hmac.New(sha256.New, []byte(secret))
16    expected.Write([]byte(ts + "." + hex.EncodeToString(bodyHash[:])))
17
18    sigBytes, err := hex.DecodeString(sig)
19    if err != nil {
20        return false
21    }
22    return hmac.Equal(sigBytes, expected.Sum(nil))
23}

Request signing 增加偽造成本 — 攻擊者需要提取 HMAC secret 並實作簽章邏輯，而非直接複製一個 API key 貼到 curl 指令。

HMAC secret 和 API key 一樣嵌在 client 端程式碼中，反編譯 APK 或閱讀 JS bundle 可以提取。Signing 增加的是攻擊者的工程投入（需要理解簽章算法並正確實作），而非理論上的安全性。對 casual attacker（看到 API key 就想試試的人）有效，對 motivated attacker（願意花時間逆向工程的人）無效。

第四層：行為分析異常偵測

Collector 端統計每個 API key（或 source.app）的事件模式，建立 baseline 後偵測偏離。

正常 SDK 的行為有可預測的特徵：

Collector 可以用 rule engine 偵測異常模式：

• 單一 API key 的事件量在 10 分鐘內超過過去 24 小時平均值的 10 倍
• 連續 N 個 request 的事件全是同一個 type
• source.sdk 欄位的值不在已知的 SDK 版本清單中

偵測到異常後的處理方式是標記而非丟棄 — 在事件中加入 _flags.suspicious = true flag，讓 dashboard 和分析查詢可以過濾。直接丟棄有誤殺正常流量的風險（例如行銷活動導致的真實流量暴增）。

攻擊者如果研究過正常 SDK 的行為模式（事件類型分布、送出間隔、payload 結構），可以模擬出相似的流量。行為分析依賴「偽造流量和正常流量有可偵測的差異」這個前提 — 對低投入的攻擊者成立，對高投入的攻擊者不一定。

第五層：Device attestation

由作業系統或平台層驗證 client 的合法性，提供 SDK 自身無法產生的證明。

Firebase App Check：整合 DeviceCheck（iOS）、Play Integrity（Android）、reCAPTCHA Enterprise（Web），由裝置平台出具 attestation token。Collector 向 Firebase 驗證 token 的有效性。

Apple DeviceCheck / App Attest：iOS 裝置向 Apple server 請求 attestation，證明 request 來自一台真實的、未被篡改的 iOS 裝置上的合法 app。

Google Play Integrity：驗證 request 來自 Google Play 安裝的 app、在未 root 的裝置上、由合法使用者操作。

Device attestation 提供的保證比前四層都強 — 它依賴裝置硬體和平台服務（難以偽造），而非 SDK 嵌入的 secret（可提取）。

天花板：

• 平台綁定 — 每個平台（iOS / Android / Web）需要各自整合不同的 attestation 服務，跨平台 SDK 的實作成本高
• Root / 越獄裝置上 attestation 可能失敗或被繞過
• Web 端的 reCAPTCHA 驗證依賴 Google 服務，有隱私和可用性的考量
• 自架 collector 需要額外整合 Firebase Admin SDK 或各平台的驗證 API

Device attestation 適合商業產品級的 mobile app，對自架監控工具而言實作成本通常超出收益。

自架方案的規模對應

不同部署規模下，需要做到哪一層取決於 endpoint 的暴露程度和偽造流量的影響大小。

Intake proxy 架構：在公開 endpoint 和商業產品場景下，可以在 collector 前面加一層自己的 server（proxy），SDK 送事件到 proxy，proxy 用 server-side API key 轉發到 collector。Client 端的 credential 只指向 proxy，proxy 的 API key 指向 collector — credential 分層，client 端的 key 洩漏不影響 collector 的認證。

1SDK ──(client token)──→ Intake Proxy ──(server API key)──→ Collector

Proxy 的額外成本是多一個 server 和網路跳躍。自用場景下不需要；endpoint 公開時值得考慮。

偽造流量的影響分析

偽造流量進入 collector 後，對不同類型的分析影響不同。

Error tracking 影響較低：error 事件的價值在 stack trace 和 error message。偽造的 error 事件缺少真實的 stack trace — 即使格式正確，內容是編造的。Error 去重靠 fingerprint（error type + message + stack trace top frame），偽造事件產生的 fingerprint 不會和真實 error 碰撞，在 dashboard 上是獨立的 error group，容易識別和過濾。

行為分析影響較高：funnel 和 cohort 分析依賴事件計數的準確性。偽造的 page.view 和 button.click 事件直接灌水計數，導致轉換率失真。偽造事件越接近真實事件的結構（正確的 event name、合理的 timestamp），影響越大。

資源消耗是固定成本：無論事件內容是否真實，每筆事件都消耗 collector 的寫入 I/O、儲存空間、和查詢時間。Rate limit 把這個成本限制在可控範圍 — 每秒 N 筆是上限，無論來源是否合法。

事後標記策略

偵測到可疑流量後，collector 在事件中加入標記欄位而非直接丟棄。丟棄有誤殺風險 — 行銷活動的流量暴增、SDK 版本升級改變了事件模式、新平台的 SDK 上線 — 這些正常場景可能觸發異常偵測。

標記方式是在 collector 寫入時，對符合異常條件的事件附加 metadata：

1{
2  "v": 1,
3  "type": "event",
4  "name": "button.click",
5  "source": { "sdk": "js", "platform": "web", "app": "main-site" },
6  "_flags": { "suspicious": true, "reason": "rate_anomaly" }
7}

Dashboard 查詢預設排除 _flags.suspicious = true 的事件。需要調查時可以包含 — 看可疑事件的模式有助於判斷是攻擊還是誤判。

下一步路由

• Collector 端的認證和授權機制 → Collector Access Control 實作
• Transport 層的加密保護 → Transport 安全
• Endpoint 濫用的威脅分析 → 監控資料洩漏的 Threat Model
• SDK 端的寫入速率控制 → Ingestion Scaling
• 行為分析和 rule engine → Rule Engine 設計
• 偽造流量對資料完整性的影響 → 端到端資料完整性
• Error fingerprint 讓偽造 error 容易辨識 → Error Fingerprint 與去重分群

概念位置

Authentication 是 authorization 的前置條件。系統先確認身份，再判斷該身份能否操作某個資源。身份確認失敗時，後續權限判斷缺少可靠基礎。

可觀察訊號與例子

系統需要 authentication 設計的訊號是服務需要區分使用者、管理員、service account 或第三方系統。Webhook 進站可以用 signature 驗證來源；service-to-service 可以用 mTLS 或 workload identity。

設計責任

Authentication 要處理 credential 保存、過期、撤銷、輪替、錯誤回應、登入風險與 audit log。安全事件後要能追查是哪個身份與 credential 被使用。

API 認證的核心是「身分維度的分離」 — 一個 request 同時牽涉「人」「呼叫的系統」「另一個系統有沒有對應身分」三個獨立問題，每個問題的 secret 機制不同、洩漏後果不同、撤銷方式不同。混用一個機制回答全部問題，等於用同一把鑰匙開家、車、保險箱。

看似一個 API request，其實同時要回答：

• 發起這個 request 的「人」是誰？（identity）
• 把這個 request 傳過來的「系統」是誰？（caller）
• 這個人在「另一個系統」有沒有對應身分？（cross-system mapping）

每個問題都需要不同的 secret 機制來回答。設計時先拆身分維度，再選 token、shared secret、mTLS 或 provisioning workflow，才有辦法讓洩漏範圍、撤銷粒度與排障路由各自清楚。

這篇整理兩層信任邊界（Layer 1 使用者、Layer 2 系統）跟一個跨系統 workflow（Layer 3 Provisioning），以及它們各自對應的 secret 機制。每層的實作細節都另有獨立文章深入、本文聚焦「為什麼要分」「各層解什麼問題」的心智模型。

前提假設：以下所有機制都假設 transport 走 HTTPS / TLS。Token 與 secret 需要在加密通道內傳輸，否則中間人可直接取得 credential。HTTPS 是所有層共同依賴的 transport 前提。

本文 token 範圍：本文討論「opaque token」（隨機字串、server 端 lookup），不涵蓋 JWT（self-contained token、簽章驗證）。兩者安全模型不同，比較見 Layer 1 段落。

Layer 1：使用者層（Bearer Token）

使用者層負責把 request 綁到已登入的人類或帳號主體。它回答的問題是：「這個 request 是哪個使用者發的？」

Bearer Token 是 capability credential（持有即授權）、不是 identity credential（身分證明）。差別在於：身分證遺失可以掛失補辦、別人撿到也無法直接領錢；Bearer Token 一旦被取得、攻擊者就能即時用該使用者身分發 request、沒有第二道關卡。這個本質決定了 token 的儲存、傳輸、撤銷機制都必須以「持有即危險」為前提設計。

「Bearer Token」是 RFC 6750 定義的 HTTP authentication scheme（Authorization: Bearer <token>）、屬於通用概念 — GitHub PAT、Stripe API Key、OAuth access token、Laravel Sanctum 的 PAT、JWT 都是 Bearer Token 的不同實作。

Opaque Token vs JWT：兩種根本不同的設計

「Bearer Token」是上位概念、實作上有兩條主線、安全模型完全不同：

兩者各有適合情境：opaque token 撤銷快、適合「使用者主動登出 / 帳號被盜要立即停權」；JWT 不需 DB lookup、適合「跨多個 microservice、想避免每次都查中央 DB」。下面 Layer 1 的內容只聚焦 opaque token — JWT 的設計細節（簽章演算法選擇、alg: none 攻擊、key rotation）是獨立議題、不在本篇範圍。

Opaque Token 的格式設計

Opaque token 是隨機字串、但實際 format 在不同產品有兩條主流分流：

兩種設計沒有絕對優劣、取決於 token 的傳播範圍：純內部使用、Sanctum 設計簡潔且足夠；對外開放、容易散落公開 repo、prefix 設計能讓 GitHub Secret Scanning / Stripe webhook 等工具自動偵測洩漏。

Sanctum 的 {PK}|{secret} 設計常被誤解為「業界標準」 — 其實是 Laravel 生態的特定選擇。具體機制、跟 GitHub / Stripe 設計的比較、各語言實作範例見 Laravel Sanctum 的 Bearer Token 設計剖析。

Token 在 DB 的儲存原則（簡述）

無論用哪種 format、有三條跨設計通用的儲存原則：

1. DB 只存 hash、不存原文 — token 是高熵隨機字串、SHA-256 即可、不需 bcrypt
2. 比對必須是 constant-time — 用各語言提供的 hash_equals / compare_digest / ConstantTimeCompare、不用 ==
3. Lookup 用穩定字段、機密比對放應用層 — DB 引擎不保證 constant-time 比對、把機密比對搬離 DB

這三條的詳細推導、各語言 constant-time 函式對照、非 Laravel 環境的實作範例見 Laravel Sanctum 的 Bearer Token 設計剖析。

Token 的生命週期

1   Login                  Use                  Expire/Revoke
2─────────  ───────────────────────────  ─────────────────
3issued → DB 存 hash  →  Bearer 驗證    →   row deleted
4                            ↓
5                       set request.user

• expires_at（例如 7 天、30 天）— 限制洩漏 token 的暴露窗
• abilities / scopes — 限縮權限粒度（「只能讀」「只能存取某 resource」），降低單一 token 洩漏的破壞範圍
• 登出即刪 row — opaque token 的撤銷成本低，這是它相對 JWT 的關鍵優勢
• rate limit / brute force 防護 — token 是隨機字串、攻擊者可暴力試。應用層要對「token 驗證失敗」加 rate limit、避免被掃出有效 token
• 長期 access 用 refresh token pattern — access token 短 TTL（小時級）、refresh token 長 TTL（月級）。Access token 洩漏只影響短窗、refresh token 撤銷後新的 access token 也無法發放

信任邊界

1[ 使用者 ] ─────────▶ [ API server ]
2              token        ↑
3                           知道「你是誰」
4                           但不會自動跨到其他系統

Bearer Token 是 capability credential — 任何持有它的 client 都能以該使用者身分發 request。這也是為什麼 token 一旦離開原本的 API server，就會引發下一層問題：B 系統收到 A 系統的 token、根本不知道該怎麼驗證、也不該驗證。

Layer 2：系統層（System-to-system credential）

系統層負責驗證呼叫方服務本身的身分。它回答的問題是：「這個 request 是哪個系統發的？」

當系統 A 需要呼叫系統 B 的 API 時，Layer 1 的使用者 token 只代表「使用者」的身分。系統 B 仍需要獨立驗證「這個 request 來自合法的合作系統 A」，這個判斷要由系統層 credential 承擔。

為什麼分得這麼清楚

想像系統 B 收到一個請求：

1B 收到請求「給我會員 X 的資料」
2   ↓
3B 自問：這請求來自...
4   ├─ 我的合作夥伴系統 A？  → 可進入授權判斷
5   ├─ 未註冊的外部 caller？ → 回 401 / 403
6   └─ 偽裝成 A 的 caller？  → 回 401 / 403 並記錄告警

純粹靠 Layer 1 的使用者 token 只能證明「這位 user 的身分」，無法證明「系統 A 的身分」。這個分工讓帳號被盜與合作系統被冒用分別走不同監控與撤銷流程。

「Shared Secret」與「API Key」的關係

兩者常被混用、實際上是同一個機制（一邊發、一邊存的對稱字串）的不同部署方式：

下面討論的「Shared Secret」泛指這個 pattern；要做 per-client identity 與 revoke 時、改成 API Key 結構即可。

常見方案的取捨

選擇預設值的判斷：純內部固定夥伴可從 Shared Secret 起步；對外或多 client 直接上 API Key；公網跨組織 + 需要短期撤銷上 OAuth Client Credentials；合規或高威脅環境用 mTLS。

mTLS 的 CA 階層、憑證生命週期、撤銷機制、nginx / service mesh 整合見 mTLS 實際怎麼設定與運維。

Shared Secret 的隱形成本

Shared Secret 部署簡單、但維運上有幾個固定痛點：

• 無法 per-caller 撤銷 — 一旦洩漏，所有用這把 secret 的 client 都得換
• 輪替需要兩邊同步 — 任何一邊忘了更新就斷線、需要「雙密過渡期」讓兩邊有時間切換。具體實作見 Shared Secret 安全輪替設計
• 常被放進 query param — 為了簡便、會留在 nginx access log、CDN log、瀏覽器 history 裡。應放在 request header（例如 X-System-Secret: xxx）或走 HMAC / OAuth

信任邊界

1[ 系統 A ] ═════════▶ [ 系統 B ]
2       shared secret
3       (server-to-server, server-only credential)

Layer 2 secret 的安全邊界是 server-side runtime。一旦進入瀏覽器或行動 app，攻擊者就能透過反編譯、JS source map、devtools network panel 等管道取得；取得後即可假冒系統 A 呼叫系統 B。Mobile app 的反編譯工具（jadx、Hopper、Ghidra 等）讓這個攻擊成本極低，obfuscation 只能增加時間成本。

如果 client 端需要呼叫 B，安全路由是讓 client 先呼叫 A，由 A 在 server 端用 Layer 2 secret 呼叫 B（A 當 proxy / BFF）；另一條路是用 OAuth 把 short-lived token 發給 client，long-lived secret 留在 server。

Layer 3：跨系統 Provisioning（身分對應 workflow、不是新的信任邊界）

回答的問題：「系統 A 的使用者 X、在系統 B 對應到哪個身分？」

Layer 3 跟 Layer 1 / 2 在概念上不對等 — Layer 1 / 2 是「驗證某個身分」的信任邊界、各自需要獨立的 secret 機制；Layer 3 不引入新的 secret、是「讓兩個系統的使用者身分對應上」的 workflow。它建立在 Layer 1（A 已驗證使用者）跟 Layer 2（A 已被授權呼叫 B）之上、不取代任何一層。

之所以仍放進「層」的編號系統、是因為實際 API 串接時、開發者會把它跟前兩層一起遇到、必須在同一個心智模型裡處理。但設計時要清楚意識到：Layer 3 的失敗模式是「身分對不上」、不是「身分被偽造」、跟 Layer 1 / 2 的安全失敗模式不同。

為什麼需要 provisioning

當 A 跟 B 是兩個獨立 service 時，「A 的使用者 X」跟「B 的使用者 X」未必是同一筆資料。可能：

• B 從來沒見過 X 這個人
• B 有自己對 X 的 record、但跟 A 不同 schema
• B 看過 X、但兩邊的 user_id 還沒對應上

需要一個機制把兩邊綁定 — 這個動作叫 provisioning。

Eager vs Lazy 兩種策略

Provisioning 策略的判斷核心是「何時承擔跨系統建檔成本」。Eager 把成本前移到註冊流程，Lazy 把成本延後到第一次使用；兩者差異不只是效能，而是資料膨脹、首用體驗與文件契約的取捨。

1EAGER (註冊時就跨系統建檔)
2────────────────────────────
3使用者註冊系統 A
4   ↓
5   A 新增會員 row
6   ↓
7   A ──同步呼叫──▶ B.createUser()  ← 即使他可能永遠不用 B
8   ↓
9   兩邊都有資料、可以立刻呼叫 B 的 API

Eager 適合大多數使用者都會用到 B 功能、且首用延遲成本高的服務。主要風險是 B 會累積大量低活躍 user，schema migration、備份與隱私刪除流程都會被放大。

 1LAZY (第一次需要時才建)
 2────────────────────────────
 3使用者註冊系統 A
 4   ↓
 5   A 新增會員 row              ← 只有 A 這邊
 6   ↓
 7   ...日後可能很久才用到 B...
 8   ↓
 9使用者第一次需要 B 的功能
10   ↓
11   呼叫 A 的「provision」endpoint
12   ↓
13   A ──呼叫──▶ B.findOrCreateUser()  ← 這時候才建
14   ↓
15   之後就跟 eager 一樣

Lazy 適合只有一部分使用者會用到 B 功能、且第一次使用可以接受一次 provisioning 延遲的服務。主要風險是「第一次使用」這個時機需要被寫進文件、SDK 或錯誤碼，否則接手者會把 B 的 404 誤判成 request 格式或權限問題。

Lazy 的「隱性 API 依賴順序」

Lazy provisioning 的最大成本是隱性依賴順序造成的認知負擔：

• 文件若沒有寫清楚「呼叫 B 前先呼叫 A 的 provision endpoint」，接手者會在「B 回 404 找不到 user」的訊號上花大量時間排查
• 用 SDK 包裝可以把 provision 自動處理、對外只暴露單一 API
• 不用 SDK 時，文件需要在快速上手與錯誤碼段落顯眼註明這個依賴順序

折衷做法：B 的 API 在第一次發現 user 不存在時、主動回一個 PROVISIONING_REQUIRED 錯誤碼、client 看到就知道要去呼叫 A 的 provision endpoint。比起靜默 500 或單純 404 更能引導 client 走到正確流程。

信任邊界示意

1[ 使用者 ] ──Layer 1──▶ [ 系統 A ] ══Layer 2══▶ [ 系統 B ]
2                            │  Layer 3 workflow：
3                            └─ 觸發後在 B 建立對應身分

Layer 3 不引入新的 secret、是「建立兩邊身分關聯」的 lifecycle 動作。它依賴 Layer 1（確認使用者身分）跟 Layer 2（A 被授權對 B 發指令）。沒有 Layer 1 / 2 的話、provisioning 自己無法獨立成立。

三層怎麼組合

把三層擺在一起的典型 request 流程：

 1        ┌─────────────┐                       ┌──────────────┐
 2        │  使用者      │                       │   系統 A     │
 3        │  (Browser/  │ ──── Layer 1 ──────▶ │              │
 4        │   App)      │      Bearer token     │              │
 5        └─────────────┘                       └──────┬───────┘
 6                                                     │
 7                                            Layer 3  │ Provision
 8                                                     │ (第一次)
 9                                                     ▼
10                                              ┌──────────────┐
11                                              │   系統 B     │
12                                              └──────────────┘
13                                                     ▲
14                                                     │
15                                            Layer 2  │ Shared secret
16                                                     │ (server-to-server)

每一條線都是一層信任邊界，各自需要不同 secret 機制保護。

設計時最常見的三個失效模式

失效模式一：讓使用者 token 也能驗 Layer 2

責任分工：「使用者身分」跟「呼叫系統身分」是兩個獨立維度、各自需要獨立 credential。系統 B 對「來自 A」的信任應綁定在系統層 credential，而不是任何單一使用者帳號上。

常見誤用：B 接受「只要 request 帶有任一合法使用者 token 就放行」。

風險判讀：這會把系統信任降階為使用者信任。任一帳號被盜（釣魚、密碼洩漏、token 外流）時，攻擊者就能用該使用者身分對 B 發 request，執行 B 開放給 A 的系統操作。

操作路由：使用者層用 Layer 1 token，系統層用 Layer 2 credential，兩層都通過才放行。

失效模式二：把 Layer 2 secret 放進 client

責任分工：Layer 2 secret 是「server 代表系統 A 對外的證明」，應留在 server 端的受信任執行環境。

常見誤用：把 shared secret 寫進前端 JS、行動 app 編譯時、甚至 git public repo。

風險判讀：client 環境（瀏覽器、mobile app）不在受控範圍。JS source 可在 devtools 直接看，mobile binary 可被反編譯出字串。Obfuscation 提高的是時間成本，沒有改變 secret 已散佈到不受信任環境的事實。

操作路由：client 需要 B 的功能時，走「client → A → B」，由 A 在 server 端用 Layer 2 secret 呼叫 B；或用 OAuth 把 short-lived token 發給 client，long-lived secret 留在 server。

失效模式三：Layer 3 依賴順序沒文件化

責任分工：跨系統依賴順序是 API 契約的一部分，屬 publisher 的責任，需要在文件、SDK 或錯誤訊號中顯式表達。

常見誤用：「呼叫 B 之前要先呼叫 A 的某個 endpoint」這個前置條件只存在於原始設計者的記憶中、文件沒寫、SDK 沒包、B 失敗時也只回 generic error。

風險判讀：接手者看到「呼叫 B 失敗」時，會優先檢查 B 的文件、request 格式與 network 層。若真正根因是尚未呼叫 A 的 provision endpoint，偵錯路徑會被導到錯誤層級。

操作路由（任選其一、優先序由上而下）：

1. SDK 包裝、自動處理 provision、對外只暴露單一 API
2. B 主動回 PROVISIONING_REQUIRED error code、引導 client 補上前置呼叫
3. 文件在「快速上手」段顯眼處註明依賴順序

何時可以簡化三層

三層框架的設計重點是「跨系統身分與 credential 分工」。當某一層回答的問題在架構裡不存在，設計可以縮小到實際存在的身分問題。

簡化的判準是「該層回答的問題是否真實存在於這個架構」。單體 application 沒有跨系統呼叫時，Layer 2 的 caller 驗證可以省略；兩個系統共用同一份 user DB 時，Layer 3 的身分對應 workflow 可以省略。

簡化不等於降低基礎安全前提。HTTPS / TLS 與 token 儲存原則（hash + constant-time）是任何 Layer 1 的最低要求，跟「層」的數量無關。

收尾

兩層信任邊界 + 一個身分對應 workflow：

• Layer 1（使用者）：解決「你是誰」 — 用 Bearer Token、注意 capability credential 的暴露成本
• Layer 2（系統）：解決「哪個系統呼叫的」 — 用 Shared Secret / API Key / OAuth / mTLS、secret 不離 server
• Layer 3（Provisioning workflow）：解決「兩邊身分怎麼對上」 — 不是新的 secret、是 lifecycle 動作

設計後端 API 時，先把這三個問題分開，secret 機制的選擇會變清楚。若排障訊號是「這個 token 在那邊不能用」，下一步是先判斷它卡在使用者層、系統層，還是 provisioning workflow。

各層的深入文章

本文聚焦「為什麼要分層」的心智模型、各層的具體實作細節都另有獨立文章：

• Layer 1（使用者） → Laravel Sanctum 的 Bearer Token 設計剖析：{PK}|{secret} format 為什麼這樣設計、DB 儲存三原則、各語言 constant-time 函式對照、跟 GitHub / Stripe 的設計比較
• Layer 2（系統）→ Shared Secret 維運 → Shared Secret 安全輪替設計：雙密過渡期、自動化 rotation 工具（AWS Secrets Manager / Vault / GCP）、緊急 vs 定期流程、多 client 同步難題
• Layer 2（系統）→ mTLS 部署 → mTLS 實際怎麼設定與運維：CA 階層、憑證生命週期、撤銷機制（CRL / OCSP / short-lived）、nginx / Envoy / service mesh 整合

沒展開的延伸議題

JWT 的簽章演算法選擇、alg: none 攻擊、token rotation 的具體實作、零信任網路下的 service-to-service 認證、OAuth flow 的完整 lifecycle、SSO（SAML / OIDC）跟本文三層的對應關係。每個都值得獨立成篇、本文聚焦在「先把層數想清楚」這個前置問題。

Sanctum PAT 的核心設計是把「找 row」與「比對 secret」拆成兩個責任。Laravel Sanctum 的 Personal Access Token（簡稱 PAT）長這樣：

11|abc123def456ghi789jkl012mno345pqr678stu
2↑           ↑
3DB 主鍵     真正的祕密

豎線前的數字是 personal_access_tokens 資料表的 primary key、豎線後是高熵隨機字串。這個設計在 Laravel 生態裡很常見、但常被誤解為「業界標準 token 格式」 — 實際上是 Sanctum 特定的設計選擇、跟 GitHub PAT（ghp_...）、Stripe API Key（sk_live_...）的設計取捨完全不同。

本文拆解 Sanctum PAT 三個關鍵設計決策：

1. 為什麼把 PK 公開放進 token
2. DB 為什麼只存 hash 不存原文
3. constant-time 比對為什麼放在應用層、不放在 DB

讀完後，你可以用 token 的傳播範圍、撤銷需求與洩漏偵測需求，判斷自己的 application 適合 Sanctum 風格還是其他 token format，並把 hash 儲存與 constant-time 比對原則套用到非 Laravel 環境。

本文位置：本文是 API 認證的三層信任邊界 Layer 1 的深入篇。主文聚焦「為什麼要分層」的心智模型、本文聚焦「Sanctum 這個特定實作怎麼設計、為什麼」。

Sanctum 在 Laravel 認證生態的位置

Laravel 官方提供三套認證套件、各自解的問題不同：

Sanctum 的設計目標是「比 Passport 簡單、比手刻 token 嚴謹」 — 不引入 OAuth 的完整 flow，但解決 token issue、storage、revoke 的常見坑。{PK}|{secret} 是這個設計目標下的具體 trade-off。

設計決策一：為什麼把 PK 公開放進 token

驗證 token 的兩個責任

Server 收到 client 傳來的 token、要做兩件事：

1. 找到 DB 裡對應的 row（這個 token 是哪個 user 的）
2. 比對 確認 token 沒被偽造

如果 token 只是純隨機字串（沒有 PK 前綴），validation 的 SQL 常會被設計成：

1SELECT * FROM personal_access_tokens WHERE token = ?

這要求 token 欄位有 index，且 server 要讓 DB 同時負責 lookup 與 secret 比對。效能通常不是瓶頸，真正的設計問題是 secret 比對落在應用層控制範圍之外。

DB 比對的 timing 不可控

DB 查詢適合處理索引搜尋，不適合承擔機密字串的 timing-safe 比對。當 WHERE token = ? 在 DB 執行時，執行時間可能洩漏：

• B-tree index 的查找路徑長度（同 prefix 的 row 多時、走的 page 不同）
• 字串比對的短路行為（多數 DB 引擎不保證 constant-time 比對）
• Buffer pool hit / miss 造成的時間差

攻擊者透過大量探測，可能推斷出有效 token 的部分結構。雖然實務上利用這個 leak 攻擊成本很高，但更穩健的設計原則是：安全機制應放在 application 能明確控制的比對函式，而不是依賴 DB 引擎的實作細節。

Sanctum 的解法：用 PK 收斂搜尋、把比對搬到應用層

{PK}|{secret} 的設計把驗證拆成兩步：

 1client 傳來: "1|abc123..."
 2       ↓
 3   server 拆解
 4       ↓
 5   ┌──────────────┐
 6   │ PK = 1       │ ──→ SELECT * FROM tokens WHERE id = 1
 7   │ secret = abc │      （O(log N)、行為穩定）
 8   └──────────────┘
 9       ↓
10   拿到該 row 的 hash
11       ↓
12   hash_equals(stored_hash, sha256(secret))
13       ↓
14   constant-time 比對、不洩漏 timing

關鍵在於 DB 只負責「找到單一 row」、不負責「比對機密」：

常見誤解：「PK 讓查詢變 O(1)」

PK 前綴的主要價值是安全責任切分，不是把查詢從慢變快。很多 Sanctum 教學文章寫「PK 把查詢變 O(1)、避免 full scan」，這個說法忽略了 hash 欄位也能被索引：

• hash 欄位也能 index — WHERE token_hash = ? 用 B-tree index 是 O(log N)、不是 full scan
• 兩條路都是 B-tree index lookup — token 規模下都不會是效能瓶頸；clustered（PK）跟 secondary（hash）的 IO cost 微差在多數場景可忽略

PK 設計的主要價值在安全可預測性、效能差距在多數場景可忽略：把比對機密的責任明確劃在「應用層 constant-time 函式」、不依賴 DB 引擎不保證的 timing 行為。

效能差異反而出現在「hash 欄位是否要 index」 — 如果用 hash lookup、token_hash 欄位需要 unique index、寫入成本變高；用 PK lookup、token_hash 不需要 index、寫入更輕量。但這在 token 規模通常不是 bottleneck。

設計決策二：DB 只存 hash 的威脅模型

威脅模型：DB 被攻陷

Token 是 capability credential — 持有即授權。如果 DB 直接存 plaintext token、任何能讀取 DB 的人（SQL injection、備份外流、運維 dump 不小心 push 到 GitHub）都能直接拿 token 假冒使用者發 request。

Sanctum 的做法：

1// 發放 token
2$plaintext = Str::random(40);  // Sanctum 預設 40 char、base62 字元集
3$hash = hash('sha256', $plaintext);
4DB::table('personal_access_tokens')->insert([
5    'token' => $hash,           // DB 只存 hash
6    'tokenable_id' => $userId,
7]);
8return $tokenId . '|' . $plaintext;  // 只此一次回給 client、之後再也拿不到

意義：DB 被 dump 時，攻擊者拿到的是不可直接使用的 hash。攻擊者要還原 plaintext 需要對 SHA-256 做 preimage attack；對 40 字元高熵隨機字串而言，計算成本實務上不可行。

SHA-256 與 bcrypt 的適用差異

密碼儲存用 bcrypt / Argon2 是因為密碼通常熵低（人類記得住的東西、entropy 通常 < 40 bit）、要刻意慢、抵抗 offline brute-force。

Token 是高熵隨機字串（40 char base62 ≈ 238 bit entropy、比一般人類記得住的 password 高約 6 個數量級的熵）— 攻擊者就算拿到 hash、暴力枚舉 plaintext 的搜尋空間是 62^40 ≈ 10^71、宇宙年齡內試不完。在這個前提下：

在高熵 token 的前提下，SHA-256 的速度是優點，因為每次 API request 都需要驗證 token。bcrypt 的慢速設計主要服務低熵 password，套到高熵 token 會增加延遲而沒有對應的安全收益。

Salt 的適用邊界

bcrypt 用 salt 是為了防 rainbow table 攻擊（預算好常見密碼的 hash、查表）。Rainbow table 對「人類選的密碼」有效、對「40 char 高熵 token」無效（搜尋空間太大、預算表的成本超過直接 brute-force）。

所以 Sanctum 對 token 用 unsalted SHA-256，是符合「高熵隨機 token」威脅模型的選擇。若 credential 來源改成人類可記憶密碼，威脅模型就會改變，儲存策略也要回到 password hashing。

設計決策三：constant-time 比對放在應用層

Constant-time 比對在解什麼

== 或 strcmp 比對字串時、會「短路」 — 一發現不同就回傳 false：

1// 偽程式碼：strcmp 的典型實作
2for (i = 0; i < len; i++) {
3    if (a[i] != b[i]) return false;  // ← 在這裡 return、不跑完
4}
5return true;

攻擊者可量測「server 從收到 request 到回 401」的時間、推斷「前幾個 byte 是對的」：

實務上單次 request 的網路抖動遠大於這幾 μs、但攻擊者可重複幾百萬次取平均、把雜訊濾掉、最終推出整個 hash。這就是 timing attack。

Constant-time 函式的實作策略

Constant-time 比對的核心是「不論輸入長什麼樣、都跑完整個比對長度」：

1// 偽程式碼：constant-time 比對
2result = 0;
3for (i = 0; i < len; i++) {
4    result |= a[i] ^ b[i];  // 用 XOR 累積差異、不 return
5}
6return result == 0;

每次呼叫都跑完整個 loop、結果用 bitwise OR 累積、最後一次性比對。執行時間不依輸入內容變化。

各語言的 constant-time 比對函式

失效模式：用 ==、===、strcmp、String.equals 比對 hash，會讓執行時間受到第一個不同 byte 的位置影響。判讀訊號是驗證邏輯直接使用語言的一般字串相等運算；下一步路由是改用標準庫或框架提供的 constant-time 函式。

為什麼不放在 DB 層

DB 引擎大多不保證 constant-time 比對。MySQL、PostgreSQL 的字串比對為了效能，底層仍可能走短路邏輯；因此「WHERE hash = ?」即使加 index，也不適合被當成 timing-safe 的安全邊界。

Sanctum 的設計把 secret 比對完全搬到應用層用 hash_equals — DB 只負責「用 PK 找到單一 row」、應用層負責「比對 hash」。職責清楚、安全可預測。

Sanctum vs GitHub PAT vs Stripe API Key

三者都是 opaque token（隨機字串、server lookup）、但 format 設計取捨完全不同：

各自的設計動機

Sanctum：使用情境是「單一 Laravel application 自己發、自己驗」。Token 不會散落在公開 repo（除非開發者犯錯）、洩漏偵測不是首要需求。把 PK 直接放進 token、換 timing 安全與設計簡潔。

GitHub PAT：使用情境是「使用者把 token 寫進 CI config、push 到 public repo」。GitHub 把 ghp_ 前綴標準化、自家服務（Push Protection、Secret Scanning）會主動 scan 公開 repo、發現 ghp_... pattern 就通知 user 並 revoke。Token 的可辨識性是洩漏偵測 infrastructure 的一環、不是浪費字元。

Stripe API Key：使用情境跨 live 跟 test 環境、且有 public / secret 兩種 key。前綴設計：

• sk_live_ — secret key、live 環境（會收真錢）
• sk_test_ — secret key、test 環境
• pk_live_ — publishable key、live 環境（可放 client）
• pk_test_ — publishable key、test 環境

工程師看一眼就知道「這把 key 能幹嘛」、避免把 live key 寫進 test config。

怎麼選

表格的判準是 token 會不會離開受控環境。單一 Laravel app 內部使用時，Sanctum 的 PK 前綴足以支撐 lookup 與撤銷；對外 API、第三方整合或多環境部署時，prefix 可提供洩漏掃描與人工辨識訊號。也可以混用成 {prefix}|{PK}|{secret}，同時保留 lookup 收斂與語意辨識。

在非 Laravel 環境怎麼套用

Sanctum 的三個原則跨語言通用：

1. DB 只存 hash — 用任何語言的 SHA-256 / SHA-512 即可。Python: hashlib.sha256、Go: crypto/sha256、Node: crypto.createHash('sha256')
2. Lookup 用穩定字段 — 把「找到 row」跟「比對機密」分開、WHERE id = ? 是穩定的、WHERE hash = ? 在 timing 上不可控
3. 應用層 constant-time 比對 — 用本文上面表格列的函式、絕不用 ==

非 Laravel 框架的等效實作：

 1# Python + SQLAlchemy 範例
 2import secrets, hashlib, hmac
 3
 4def issue_token(user_id):
 5    plaintext = secrets.token_urlsafe(32)
 6    hash_value = hashlib.sha256(plaintext.encode()).hexdigest()
 7    token = PersonalAccessToken(user_id=user_id, hash=hash_value)
 8    db.session.add(token)
 9    db.session.commit()
10    return f"{token.id}|{plaintext}"  # 只此一次回給 client
11
12def verify_token(raw_token):
13    # production 範例需多一層 try-except 涵蓋 int() 轉型與 DB 例外
14    try:
15        token_id, plaintext = raw_token.split('|', 1)
16        token = PersonalAccessToken.query.get(int(token_id))
17    except (ValueError, TypeError):
18        return None
19    if not token:
20        return None
21    expected_hash = hashlib.sha256(plaintext.encode()).hexdigest()
22    if not hmac.compare_digest(token.hash, expected_hash):
23        return None
24    return token.user

 1// Go + sqlx 範例
 2func IssueToken(ctx context.Context, userID int64) (string, error) {
 3    plaintext := generateRandomString(40)
 4    hash := sha256.Sum256([]byte(plaintext))
 5    var tokenID int64
 6    err := db.QueryRowContext(ctx,
 7        "INSERT INTO personal_access_tokens (user_id, hash) VALUES ($1, $2) RETURNING id",
 8        userID, hex.EncodeToString(hash[:]),
 9    ).Scan(&tokenID)
10    if err != nil {
11        return "", err
12    }
13    return fmt.Sprintf("%d|%s", tokenID, plaintext), nil
14}
15
16func VerifyToken(ctx context.Context, raw string) (*Token, error) {
17    parts := strings.SplitN(raw, "|", 2)
18    if len(parts) != 2 {
19        return nil, ErrInvalidFormat
20    }
21    tokenID, err := strconv.ParseInt(parts[0], 10, 64)
22    if err != nil {
23        return nil, ErrInvalidFormat
24    }
25    var token Token
26    err = db.GetContext(ctx, &token, "SELECT * FROM personal_access_tokens WHERE id = $1", tokenID)
27    if err != nil {
28        return nil, err
29    }
30    expectedHash := sha256.Sum256([]byte(parts[1]))
31    storedHash, _ := hex.DecodeString(token.Hash)
32    if subtle.ConstantTimeCompare(storedHash, expectedHash[:]) != 1 {
33        return nil, ErrInvalidToken
34    }
35    return &token, nil
36}

兩者的關鍵都是：SELECT WHERE id = ? + 應用層 compare_digest / ConstantTimeCompare、不依賴 DB 比對 hash。

收尾

Sanctum 的 {PK}|{secret} 是一個特定情境下的設計取捨，不是業界通用標準：

• 它假設 token 不會散落到公開環境、所以不需要 prefix-based 洩漏偵測
• 它把比對機密的責任明確劃在應用層、不依賴 DB 引擎的 timing 行為
• 它用 SHA-256 + 不加 salt、因為 token 高熵時這個選擇符合威脅模型

如果你的場景符合這些假設，Sanctum 的設計可以直接使用。若場景是對外 API、需要洩漏偵測、多環境或多 token type，prefix-based format 會提供更好的操作訊號；儲存原則（hash + constant-time）則跨設計通用。

延伸閱讀：

• API 認證的三層信任邊界 — 本文的主篇、Sanctum 在「Layer 1 使用者層」的位置
• Shared Secret 安全輪替設計 — Layer 2 系統間 secret 的輪替議題
• mTLS 實際怎麼設定與運維 — Layer 2 進階方案的部署細節