HTTP protocol test 的驗證對象

Request 格式

Client 端發送的 request 是否符合 API 規格。Content-Type header、JSON body 的欄位名稱和型別、query parameter 的格式 — 這些在 mock client 中通常不被驗證（mock 接受任何 request），但真實 API 可能因為格式不符而拒絕。

Response 解析

Client 端能否正確解析真實 API 的 response。Mock response 通常是開發者手寫的 JSON，可能和真實 API 的 response 有微妙差異 — 欄位名稱大小寫、數值型別（integer vs float）、null vs 缺失欄位、巢狀結構。

Error response 處理

真實 API 的 error response 格式可能和 success response 不同。Mock client 通常只模擬 success case，偶爾模擬簡化的 error case。真實 API 的 400/401/403/404/500 各自可能有不同的 error body 結構。

認證流程

API 的認證流程（API key、OAuth token、session cookie）在 mock 中通常被跳過。真實 API 的認證包括 token 取得、token 過期、refresh flow — 每一步都可能失敗。

Test 結構

HTTP protocol test 的結構和 WebSocket protocol test 類似 — 對真實 API 發送真實 request、驗證真實 response。

 1test('POST /api/resource creates resource'):
 2  response = await httpClient.post(
 3    'http://localhost:8080/api/resource',
 4    body: jsonEncode({'name': 'test', 'type': 'A'}),
 5    headers: {'Content-Type': 'application/json', 'Authorization': 'Bearer ...'},
 6  )
 7  expect(response.statusCode, 201)
 8  body = jsonDecode(response.body)
 9  expect(body['id'], isNotNull)
10  expect(body['name'], 'test')
11
12test('POST /api/resource with invalid body returns 400'):
13  response = await httpClient.post(
14    'http://localhost:8080/api/resource',
15    body: jsonEncode({'invalid_field': 'value'}),
16    headers: {'Content-Type': 'application/json', 'Authorization': 'Bearer ...'},
17  )
18  expect(response.statusCode, 400)
19  body = jsonDecode(response.body)
20  expect(body['error'], isNotNull)  // 驗證 error body 結構

Consumer-driven contract test

當 client 和 server 由不同團隊開發時，consumer-driven contract test 是 protocol integration test 的延伸。Client 團隊定義「我期望的 request/response 格式」（contract），server 團隊驗證 server 實作是否符合 contract。

Consumer-driven contract test 的工具（Pact、Spring Cloud Contract）自動化了 contract 的定義、驗證和版本管理。適合 API 有多個 consumer 且需要獨立部署的場景。

自用工具或 client/server 同一人開發的場景不需要 contract test 工具 — 直接對真實 server 跑 protocol integration test 更簡單。

下一步路由

• CI 中如何管理 test 用的 server → CI 中的服務 fixture 管理
• WebSocket 的 protocol test → WebSocket 協議測試實作
• 什麼時候用 contract test 替代 protocol integration test → 成本判斷表
• Backend 的 contract testing 實務 → Backend 可靠性 contract testing

CLI 查詢：grep + jq

JSONL 格式的最大優勢是原生支援 Unix 文字處理工具。不需要額外的查詢語言、不需要客戶端工具、不需要連線到 database。

常見查詢模式

按事件類型過濾：

1grep '"type":"error"' events-2026-06-19.jsonl | jq .

按 namespace 過濾：

1grep '"name":"terminal.connect' events-2026-06-19.jsonl | jq .

按時間範圍過濾（跨檔案）：

1cat events-2026-06-1{8,9}.jsonl | jq 'select(.ts >= "2026-06-18T18:00:00")'

統計每種事件的數量：

1jq -r '.name' events-2026-06-19.jsonl | sort | uniq -c | sort -rn

grep 友好的 JSONL 設計

JSONL 的每行 JSON 結構影響 grep 的查詢效率和準確性。

把常用過濾欄位放在 JSON 的前面。grep 是字串匹配，把 type 和 name 放在行首讓 grep pattern 更簡單、誤匹配更少。

避免 JSON 值中包含雙引號。事件名稱和型別用簡單字串（不含特殊字元），讓 grep 的 pattern 不需要處理 escape。

每行 JSON 不換行。JSONL 的定義就是每行一個 JSON，但格式化工具可能自動加換行。寫入時用 json.Marshal（Go）或 JSON.stringify（JS）確保單行輸出。

HTTP 查詢 endpoint

HTTP 查詢 endpoint 讓非 CLI 使用者（dashboard、自動化腳本、其他服務）能查詢事件資料。

Endpoint 設計

1GET /v1/events?type=error&name=terminal.connect.*&from=2026-06-18T00:00:00Z&to=2026-06-19T00:00:00Z&limit=100

查詢參數：

回應格式

 1{
 2  "events": [
 3    {
 4      "v": 1,
 5      "type": "error",
 6      "timestamp": "2026-06-19T08:42:00Z",
 7      "source": { "sdk": "python", "platform": "macos", "app": "claude-hooks" },
 8      "name": "hook.failure",
 9      "level": "error",
10      "data": { "hook": "branch-status-reminder", "step": "validation" },
11      "error": { "message": "KeyError: 'status'", "stack": "Traceback...", "type": "KeyError" },
12      "context": { "session_id": "sess-abc-123" }
13    }
14  ],
15  "total": 42,
16  "limit": 100,
17  "offset": 0
18}

events 陣列按 timestamp 降序排列。total 是符合篩選條件的全量筆數（不受 limit 截斷），讓呼叫端計算分頁（total_pages = ceil(total / limit)）。分頁用 offset-based（offset=100 取第二頁），適合資料量在十萬筆以下的場景。資料量大到 offset 效能不足時，改用 cursor-based（after=<last_event_id>），但 cursor-based 是 PostgreSQL 層的演進，SQLite 層用 offset 足夠。

實作策略

HTTP 查詢 endpoint 的底層實作可以直接讀取 JSONL 檔案 — 根據 from/to 確定要讀哪些日期的檔案，逐行 parse 並過濾。這個實作在資料量小（單日萬筆以下）時足夠快。

當查詢效能成為問題時，在 JSONL 之上加一層索引（按 type/name 建立反向索引），或演進到 SQLite 儲存（見 規模演進）。

聚合查詢

逐筆查詢回答「發生了什麼」，聚合查詢回答「發生了多少」。Error 調查的第一步是定位最頻繁的 error — 「哪些 error 最多」需要按 name 分群計數的聚合結果，逐筆列表在這個階段資訊量太大。

Endpoint 設計

1GET /v1/events/summary?type=error&from=2026-06-18T00:00:00Z&to=2026-06-19T00:00:00Z&group_by=name

回傳按 name 分群的統計：

1{
2  "groups": [
3    { "name": "hook.failure", "count": 15, "last_seen": "2026-06-19T08:42:00Z" },
4    { "name": "terminal.connect.failed", "count": 3, "last_seen": "2026-06-19T07:10:00Z" }
5  ],
6  "total": 18,
7  "from": "2026-06-18T00:00:00Z",
8  "to": "2026-06-19T00:00:00Z"
9}

查詢參數和逐筆查詢共用（type、name、from、to），額外的 group_by 指定分群欄位（name 或 type）。

SQL 實作

SQLite backend 下直接用 GROUP BY：

1SELECT name, COUNT(*) as count, MAX(timestamp) as last_seen
2FROM events
3WHERE type = 'error' AND timestamp BETWEEN ? AND ?
4GROUP BY name
5ORDER BY count DESC
6LIMIT 100

有 type + timestamp 複合索引時，這個查詢在 10 萬筆資料內的效能和逐筆查詢相當 — GROUP BY 在索引掃描後做，不需要全表掃描。

和逐筆查詢的定位差異

兩者是互補的工作流 — 聚合查詢定位問題方向，逐筆查詢深入細節。Dashboard 的 Error 列表頁面直接消費聚合查詢的結果。

CLI vs HTTP 的定位

兩種介面共存 — CLI 用於開發者日常 debug，HTTP endpoint 用於自動化和遠端存取。兩者底層讀取同一份 JSONL 檔案，結果一致。

下一步路由

• JSONL 儲存的設計 → JSONL 儲存設計
• Rule engine 的自動化處理 → Rule engine 設計
• Collector 的完整架構 → Collector 架構

這個相容性決定了你的選擇空間。理解它的意義後，看到任何工具寫「支援 OpenAI 相容 API」時，你會知道這句話真正承諾的是什麼、不承諾的是什麼。

本章目標

讀完本章後，你應該能：

1. 看懂 apiBase: http://localhost:11434/v1 這類設定背後在做什麼。
2. 判斷一個介面層工具是否支援本地 LLM。
3. 知道「OpenAI 相容」承諾的範圍與邊界。
4. 用 curl 直接打本地 LLM 的 API 驗證它在跑。

API 形狀的核心：chat completions

OpenAI 在 2023 年定義的 chat completions API 核心是這個請求格式：

 1curl http://api.openai.com/v1/chat/completions \
 2  -H "Authorization: Bearer $OPENAI_API_KEY" \
 3  -H "Content-Type: application/json" \
 4  -d '{
 5    "model": "gpt-5",
 6    "messages": [
 7      {"role": "system", "content": "You are a helpful assistant."},
 8      {"role": "user", "content": "寫一個 Python function 計算費氏數列"}
 9    ],
10    "stream": true
11  }'

回應是一連串 server-sent events（SSE、伺服器把回應切成小封包陸續推給 client、而不是等整段算完才一次回）、每個 event 包含一個 token chunk。

本地推論伺服器實作同樣的 endpoint 形狀，只是 host 換成 localhost、API key 不檢查或檢查 dummy 值：

 1curl http://localhost:11434/v1/chat/completions \
 2  -H "Content-Type: application/json" \
 3  -d '{
 4    "model": "gemma4:31b-coding-mtp-bf16",
 5    "messages": [
 6      {"role": "system", "content": "You are a helpful assistant."},
 7      {"role": "user", "content": "寫一個 Python function 計算費氏數列"}
 8    ],
 9    "stream": true
10  }'

差別只有三點：

1. host：從 api.openai.com 換成 localhost:11434。
2. model：從 gpt-5 換成 gemma4:31b-coding-mtp-bf16。
3. Authorization：本地通常不檢查 API key，或接受任意值。

請求與回應的 JSON schema 完全一樣。這就是「OpenAI 相容」的字面意義。

為什麼這個相容性這麼重要

如果沒有 OpenAI 相容 API，每個介面層工具要支援新的伺服器就得寫專屬整合：Continue.dev 要為 Ollama 寫一份、為 LM Studio 寫一份、為 llama.cpp 寫一份、為雲端 OpenAI 寫一份、為 Anthropic 寫一份。每多一個工具就 N×M 的整合成本。

OpenAI 相容把這個成本拆成「介面層支援標準 API 一次 + 伺服器層實作標準 API 一次」、整合工作從 N×M 降到 N+M。後果是新伺服器（如 2024 年才出現的 oMLX）只要實作這份 API、馬上能被既有的所有介面層用上。

這也是為什麼幾乎所有 IDE plugin、CLI 工具、Web UI 都選擇 OpenAI 相容做 first-class citizen。Anthropic 自己的 API 形狀（messages、不同 streaming 格式）反而成為次要選項，介面層工具通常要為 Anthropic 寫額外的 adapter。

接本地 LLM 的最小設定

實際使用上，把任一個介面層工具切到本地 LLM 通常只要改三個欄位：

三個欄位的延伸判讀：API base 改成 localhost:11434 表示請求送到本機 11434 port、不走網路；API key 本地通常不檢查、但介面層工具可能仍要求填一個值才能初始化；Model name 要去伺服器看當前已下載的 model tag、Ollama 用 ollama list 查、LM Studio 在 Discover 分頁查。

接近真實的例子是 Continue.dev 的 config.json：

 1{
 2  "models": [
 3    {
 4      "title": "Gemma 4 31B (local)",
 5      "provider": "ollama",
 6      "model": "gemma4:31b-coding-mtp-bf16",
 7      "apiBase": "http://localhost:11434"
 8    }
 9  ]
10}

Continue.dev 內部會把 provider: ollama 翻成 OpenAI 相容請求送到 apiBase。如果你想用通用 OpenAI provider：

 1{
 2  "models": [
 3    {
 4      "title": "Local LLM (via OpenAI-compatible)",
 5      "provider": "openai",
 6      "model": "gemma4:31b-coding-mtp-bf16",
 7      "apiBase": "http://localhost:11434/v1",
 8      "apiKey": "not-needed"
 9    }
10  ]
11}

兩種寫法都會工作。provider: ollama 多一些 Ollama 特有功能（如 model auto-pull），provider: openai 比較通用、可以接任何 OpenAI 相容伺服器。

「OpenAI 相容」承諾什麼、不承諾什麼

相容承諾的是 API 形狀 —— request schema、response schema、streaming 格式、錯誤碼大致一致。不承諾的是：

1. 模型能力：本地 Gemma 4 31B 跟雲端 GPT-5 都能用同一套 API 呼叫，但回答品質天差地遠。
2. 效能特性：本地的 TTFT、生字速度跟雲端完全不同，介面層感覺不到差別不代表速度一樣。
3. 進階參數：OpenAI 自己的新功能（function calling 進階模式、structured output 強制 JSON 輸出、reasoning effort 控制推理深度等）不一定被本地伺服器完整支援。寫 code 場景常見問題是設定了 tools 參數但本地模型不會主動呼叫。模組四會展開這些進階特性、見 4.3 Tool use 原理。
4. 模型清單：呼叫 GET /v1/models 回的清單、本地是你已下載的模型、雲端是 OpenAI 提供的模型；介面層要把兩邊清單視為各自獨立的資料。

接近真實的意外事件：

• 設定 response_format: { type: "json_object" } 強制 JSON 輸出，本地某些舊模型不認，會直接回普通文字。
• 設定 tool_choice: "required" 強制使用工具，本地許多模型不支援，行為退化成普通對話。
• 設定 seed 想拿確定性輸出，本地伺服器多半實作了，但雲端 OpenAI 並不保證每個 model 都尊重。

陷阱是把「相容」當成「等價」。在依賴進階參數的場景下、寫程式時值得先假設本地伺服器可能不支援最新功能、預先準備降級處理（例如先試 tool_choice: "required"、伺服器忽略時 fallback 到 prompt-based 工具呼叫）。

用 curl 驗證本地 LLM 在跑

啟動 Ollama 並 pull 一個模型後，最快確認它在跑的方式是直接 curl：

1curl http://localhost:11434/v1/chat/completions \
2  -H "Content-Type: application/json" \
3  -d '{
4    "model": "gemma4:e4b",
5    "messages": [{"role": "user", "content": "Say hi in three languages."}],
6    "stream": false
7  }'

如果回的是 JSON 包含 choices[0].message.content，伺服器層正常。介面層連不上的時候，先用這個 curl 確認問題是介面層、伺服器層，還是模型本身。

需要驗證 streaming：

1curl http://localhost:11434/v1/chat/completions \
2  -H "Content-Type: application/json" \
3  -d '{
4    "model": "gemma4:e4b",
5    "messages": [{"role": "user", "content": "Count from 1 to 5."}],
6    "stream": true
7  }'

正常應該看到一連串 data: {...} 行，每行是一個 token chunk。

多伺服器並存：同時跑 Ollama 與 LM Studio

OpenAI 相容讓你可以同時在同一台 Mac 上跑多個伺服器，只要 port 不撞。常見配置：

Port 衝突的徵兆是啟動伺服器時報 address already in use。用 lsof -i :<port> 找佔用方、確認是舊版伺服器就 pkill -f 終止、或改用其他 port 啟動。詳細的 port 與 listen address 判讀見 Port 與 Localhost 卡片。

Continue.dev 的 config.json 可以同時列多個 model、每個 model 指向不同伺服器、UI 上下拉切換。這個能力讓「主力模型穩定跑、實驗模型隔離測試」變得直接。

不是 OpenAI 相容的本地工具

少數本地工具不走 OpenAI 相容，要特別注意：

1. MLX 原生 Python API：Apple 的 MLX framework 本身是 Python library、不是 HTTP server。需要自己 wrap 或用 mlx_lm.server（次要產品、功能不全）。完整的 MLX / MTP / oMLX 區別見 0.4 章節。
2. 早期 llama.cpp：在 OpenAI 相容前就存在，原生 API 形狀不同；新版加上 /v1/chat/completions 後跟主流相容。
3. 某些研究專案：直接 wrap PyTorch / Transformers，沒有 HTTP 層，要當 library 用。

遇到這類工具時、值得先評估「該不該為它寫 adapter」。判讀訊號：模型唯一性（這個工具是否提供其他伺服器拿不到的模型？）vs 整合成本（寫 adapter 與長期維護的時間投入）。模型唯一性高時值得投資、模型可在主流伺服器找到替代時、選 OpenAI 相容的主流伺服器（Ollama、LM Studio）能省下大量整合成本。

下一章

下一章：0.4 MLX / MTP / oMLX，澄清三個常被混為一談的術語，避開網路上最常見的本地 LLM 認知陷阱。

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）跟本文三層的對應關係。每個都值得獨立成篇、本文聚焦在「先把層數想清楚」這個前置問題。