代理憑證編碼驗證：避免 407 錯誤與密鑰外洩

同一組代理帳號密碼在一個工具中成功，換到另一個工具卻回傳 407，原因往往不是帳號失效，而是憑證穿越了不同的解析邊界。獨立的使用者名稱欄位可能需要原始值，URL 中的使用者資訊卻可能需要百分比編碼；Shell、CI 或設定檔還可能在客戶端收到參數前再次處理特殊字元。

本指南提供一套受控驗收方法，適用於取得授權的資料蒐集、瀏覽器測試、廣告驗證與市場研究。目標不是尋找一條「所有工具通用」的編碼規則，而是證明每個設定入口實際接收什麼，同時讓正式密鑰遠離原始碼、日誌與測試證據。

最常見的三個故障邊界

設定邊界：客戶端可能提供獨立的 server、username、password 欄位，也可能只接受組合憑證或完整代理 URL。這些入口的解碼規則未必相同。

序列化邊界：冒號、@、百分比符號、空格、反斜線與非 ASCII 字元在 URL 中可能具有結構意義。該編碼時不編碼會失敗，重複編碼同樣會失敗。

執行邊界：互動式 Shell、CI 變數、YAML、JSON 與命令包裝器可能先修改引號、跳脫或換行。

必須分別測試這三層。只憑 407 無法判斷是哪一層改變了憑證。

優先使用結構化憑證欄位

客戶端若支援獨立欄位，應優先使用。Playwright 的代理設定可將伺服器、使用者名稱和密碼分開提供，避免把秘密放入 URL，也明確了責任邊界：應用程式傳入邏輯值，客戶端負責協定序列化。

const browser = await chromium.launch({
  proxy: {
    server: process.env.PROXY_SERVER!,
    username: process.env.PROXY_USERNAME!,
    password: process.env.PROXY_PASSWORD!,
  },
});

環境變數應來自獲准的密鑰儲存，不要列印整個設定物件。獨立欄位仍需驗證，但不應在文件沒有要求時自行預先編碼密碼。

識別客戶端明確規定的解碼行為

curl 對代理憑證有明確規則：代理憑證字串中的使用者名稱和密碼在使用前會進行 URL 解碼，因此可以用編碼形式表達 @ 等分隔字元，使用者名稱中的冒號也必須避免被當成帳號與密碼的分隔符。這個規則只代表 curl 的契約，不能機械套用到所有 SDK。

curl --proxy "$PROXY_SERVER" \
  --proxy-user "$PROXY_USERPASS" \
  --fail-with-body "$AUTHORIZED_TEST_URL"

組合值應在受保護的設定層中產生，不要把真實密碼貼到命令歷史、工單或範例。若 API 已提供獨立欄位，除非文件明確要求，否則不要先編碼密碼。

建立一次性字元矩陣

請供應商或憑證管理員在隔離帳戶中建立短期測試憑證。每次只改變一類字元，不要一次混入所有複雜字元。

只使用合成值，在證據中保存案例編號與單向指紋，不保存測試密鑰本身。

七步驗收流程

1. 先證明乾淨基線

用簡單的一次性憑證，透過供應商支援的客戶端請求獲准測試位址，記錄代理路由、預期區域、目標狀態和去識別化出口指紋。基線失敗時先停止，繼續做編碼實驗無法隔離問題。

2. 固定其他變數

保持端點、協定、認證方式、目標、區域與請求完全不變，每次只測試一種字元類別。

3. 先測結構化設定

把原始邏輯值傳入獨立欄位。成功結果可作為該客戶端的參考；失敗時先檢查設定載入與密鑰注入，不要立即增加編碼。

4. 僅在必要時測試序列化形式

代理 URL 或文件規定的組合欄位，只編碼對應的 URL 元件，不要編碼整條 URL，也不要把已編碼值重用到原始密碼欄位。

5. 對比本機與 CI

用參數陣列在本機執行同一案例，再在 CI 中執行。若只有 CI 失敗，檢查 YAML 引號、變數插值、尾隨換行和密鑰遮罩。正式流程應避免依賴互動式命令列。

6. 為故障正確分層

• 設定解析錯誤：尚未連線客戶端就拒絕值；
• 解析或連線錯誤：代理端點沒有被存取；
• 通道或 TLS 錯誤：認證可能成功，但下一跳失敗；
• HTTP 407：代理沒有接受收到的認證；
• 目標回應：代理鏈路完成，目標網站已回應。

在歸因到帳戶權限前，先確認供應商是否觀察到本次嘗試。可結合代理認證 407 疑難排解指南逐層檢查。

7. 固化已驗證契約

記錄設定入口、輸入屬於邏輯值或序列化值、唯一編碼責任方、已測執行階段版本與去識別化規則。將一次性憑證字元矩陣加入持續整合。

不洩密地識別重複編碼

不要記錄認證標頭或完整代理 URL。分別計算邏輯測試值和應用程式序列化結果的單向指紋，並記錄長度、字元類別案例和負責的程式碼路徑。

若百分比符號先被編碼，隨後又被第二層編碼，接收端只解碼一次就可能得到錯誤密碼。正確修復方式是明確唯一的序列化責任方，而不是隨意再增加一次解碼。

建議證據欄位

test_case_id
client_name
client_version
configuration_surface
runner_type
logical_value_fingerprint
serialized_value_fingerprint
expected_proxy_route
provider_attempt_observed
result_class
http_status
exit_fingerprint
redaction_check
timestamp

記錄中不得出現代理密碼、完整使用者名稱、認證標頭、Cookie 或完整代理 URL。參考代理 HAR 憑證去識別化指南控制證據；如果密鑰意外進入日誌，應立即執行代理憑證輪替流程。

發布檢查清單

• [ ] 憑證為短期、限權、可丟棄的測試憑證。
• [ ] 特殊字元測試前，簡單基線已經成功。
• [ ] 端點、路由、協定和目標保持固定。
• [ ] 優先使用獨立帳號密碼欄位。
• [ ] 只對文件指定的元件編碼。
• [ ] 只有一個層負責序列化。
• [ ] 本機與 CI 執行路徑分別驗證。
• [ ] 命令歷史與程序輸出不含秘密。
• [ ] 日誌已去識別化代理 URL 和認證材料。
• [ ] 先為故障分層，再決定是否輪替憑證。
• [ ] 強制代理失敗時關閉，不得靜默直連。
• [ ] 供應商與目標允許本次測試流量。

常見問題

所有特殊字元都應百分比編碼嗎？

不應該。是否編碼取決於設定入口。URL 元件可能需要編碼，而獨立密碼欄位通常需要原始邏輯值。必須遵循具體客戶端契約並實測。

HTTP 407 一定代表密碼錯誤嗎？

不一定。它表示代理沒有接受提交的認證，但解析、編碼、認證方案、帳戶政策或密鑰注入都可能改變實際提交值。

可以擷取送出的認證標頭嗎？

應避免擷取真實認證材料。使用一次性憑證、能去識別化的客戶端診斷與供應商端嘗試確認。任何意外擷取都應按憑證外洩處理。

為什麼本機命令成功，CI 卻失敗？

Shell、YAML 解析器、變數儲存或包裝器可能以不同方式處理特殊字元和尾隨換行。應比較指紋與設定邊界，而不是列印秘密。

合規說明

代理只能用於合法且取得授權的測試與蒐集。遵守目標服務條款、robots 指令、隱私和資料保護要求、速率限制與供應商政策。憑證驗證必須使用獲准帳戶和一次性密鑰，不得用於猜測密碼、繞過存取控制、隱藏違規活動或未經許可取得資料。