Cookie 轉 JSON 轉換器會接收嚴格的 HTTP Cookie 請求標頭(例如 SID=abc; lang=en-US),將其轉成扁平的 JSON 物件,物件的鍵是 cookie 名稱、值是字串,然後再把這個對映反轉回序列化的 Cookie 欄位。一個可運作的 Cookie 轉換器範例,輸入 SID=abc; lang=en-US; cart=abc== 會產生一個包含三個字串成員的 JSON 物件,逐字保留每一個字元,而不會進行 URL 解碼百分號序列,也不會正規化分隔符號的空白。反向範例則把一個檢視過的 JSON 物件(例如 {"preference":"dark","SID":"abc","cart":"abc=="})轉回精確的欄位值 preference=dark; SID=abc; cart=abc==,透過詞法掃描保留 JSON 成員的順序,並把多出來的等號當作值資料保留。嚴格序列化設定檔正是讓這個範例可以重現的原因:每一組都必須是 name=value,多組之間必須剛好用分號加一個 ASCII 空格連接,並且會自動修剪貼上內容外圍的 ASCII 空格。名稱遵循 RFC token 設定檔且區分大小寫,所以 SID 與 sid 是兩個不同的鍵。值遵循 RFC cookie-value 設定檔,可是不加引號的合法 cookie 八位元組,或是用雙引號包起來的相同序列;像 %2F 這樣的百分號序列會保留為 percent、2、F 三個字元。Set-Cookie 回應標頭帶有 Domain、Path、Expires、Secure、HttpOnly、SameSite 等屬性,明確不在處理範圍內,會產生明確的錯誤,而不是產生誤導的 JSON。請透過 Cookie 轉 JSON 轉換器 試試您自己的輸入。
Cookie 轉換器範例會產生什麼
兩個方向的範例涵蓋了這個關鍵字背後的實際需求。Cookie 轉 JSON 方向把序列化的請求標頭變成扁平的 JSON 物件,讓每個名稱與值都能被檢視、排序,或搬移到其他工具。JSON 轉 Cookie 方向則接收一個檢視過的字串對映,產生一個可放進 HTTP 請求或測試 fixture 的請求標頭值。兩個方向都會在唯讀區域中回傳純文字,並且完全在目前分頁中執行,不會把貼上的內容送到伺服器;當 cookie 字串含有即時工作階段祕密時,這一點很重要。
輸出版面與最常見的除錯工作流程形狀相同:範例一邊是 JSON 物件,另一邊是來源或目的地的欄位。輸入上限是 100,000 個 UTF-16 程式碼單位,輸出上限是 200,000 個程式碼單位,兩者都是精確值,所以超出任一邊界後的第一個程式碼單位會被拒絕。轉換絕不會切割、上限、取樣、略過或部分回傳輸入,這代表成功的範例就是完整的輸入,不多也不少。
Cookie 轉 JSON 範例逐步解說
請把以下原始值貼到 Cookie 轉 JSON 模式:
SID=abc; lang=en-US; cart=abc==
共有三組。每一組中的第一個等號是結構分隔符,而第三組的 abc== 會把結尾的等號當作值資料保留,這正符合簽章 token、查詢字串以及 Base64 填補的樣貌。轉換後,唯讀輸出區域會顯示:
{ "SID": "abc", "lang": "en-US", "cart": "abc==" }組數為三,每個值都是 JSON 字串,縮排為兩個空格,因為內部正向對映會透過 JSON.stringify 以兩格縮排序列化。內部對映使用 null 原型建立,因此結果是純物件,而不是 Object.prototype 的實例,而保留名稱 __proto__、prototype 與 constructor 在兩個方向上都會被擋下,作為縱深防禦的界線。
允許加上精確的欄位名稱前綴。貼上 Cookie: SID=abc; lang=en-US 會產生相同的 JSON 物件,因為嚴格設定檔接受緊接在值前面的選擇性 Cookie: 前綴。COOKIE: 也可以,因為欄位名稱比對不區分大小寫。Cookie : 則不行,因為單字與冒號之間的空白格式錯誤。
JSON 轉 Cookie 範例逐步解說
切換到 JSON 轉 Cookie 模式並貼上:
{"preference":"dark","SID":"abc","cart":"abc=="}
詞法掃描會讀取一個非空物件,其解碼後的鍵是 RFC token,解碼後的值是 cookie-octet 字串。成員順序會被保留以方便輸出,不過 Cookie 語意不應依賴序列化順序。輸出結果為:
preference=dark; SID=abc; cart=abc==
組與組之間的分隔符剛好是一個分號加一個 ASCII 空格。不會加入任何百分號編碼、不會增刪引號,也不會執行任何排序。組數為三,而結尾的 == 會被保留,因為每一組中只有第一個等號具有結構意義。反向會把解碼後的鍵驗證為 RFC token、把解碼後的值驗證為可接受的 cookie-value,因此逸出字元會在檢查前解碼;所以逸出的換行字元會失敗,因為其解碼後的控制字元不屬於 cookie-value 資料。
在本機執行 Cookie 轉換器範例
- 開啟 Cookie 轉 JSON 轉換器,選擇 Cookie 轉 JSON 方向。
- 貼上像 SID=abc; lang=en-US; cart=abc== 這樣的原始嚴格值,或若您是從請求擷取中複製欄位,也可以加上精確的 Cookie: 前綴。只有在您想驗證前綴解析器是否接受時,才加上欄位名稱。
- 點擊 convert 並檢視唯讀輸出、組數以及任何錯誤訊息。編輯輸入或切換方向會清除先前的輸出、組數、剪貼簿狀態與剪貼簿計時器,因此顯示的結果永遠反映目前的文字。
- 對於 JSON 轉 Cookie,請貼上一個非空 JSON 物件,其解碼後的鍵通過 token 檢查、解碼後的值為可接受的 cookie 字串,然後點擊 convert。輸出結果是單一 Cookie 欄位值,可直接貼到 HTTP 用戶端或測試 fixture。
- 使用複製按鈕複製完整輸出。剪貼簿寫入是非同步的,並使用一個世代識別碼,因此較舊的「已複製」狀態在編輯、重試、切換方向或卸載後絕不會還原。若瀏覽器拒絕剪貼簿權限,完整輸出仍會保持可見以供手動選取。
會讓 Cookie 轉換器範例失敗的輸入
接受與拒絕的情境並排比較比用文字條列更容易,因此下表把具代表性的輸入與嚴格設定檔下的結果配對。每一個接受的列都會乾淨地對應到 Cookie 轉 JSON 輸出或 JSON 轉 Cookie 輸出,而每一個被拒絕的列會呈現清楚的錯誤,而不是被正規化的結果。
| 情境 | 範例輸入 | 結果 |
|---|---|---|
| 原始嚴格標頭 | SID=abc; lang=en-US | 接受,產生扁平 JSON 物件 |
| 選擇性前綴 | Cookie: SID=abc; lang=en-US | 接受,前綴比對不區分大小寫 |
| 等號周圍有空白 | SID = abc; lang=en-US | 拒絕,嚴格設定檔禁止邊界空白 |
| 缺少分隔空白 | SID=abc;lang=en-US | 拒絕,要求剛好是 ; |
| 結尾分號 | SID=abc; lang=en-US; | 拒絕,不允許結尾分號 |
| 重複名稱 | SID=abc; SID=def | 拒絕,沒有先到先贏或後到後贏行為 |
| 原型風險名稱 | __proto__=x; a=1 | 拒絕,縱深防禦擋下 |
| Set-Cookie 前綴 | Set-Cookie: SID=abc; Path=/ | 拒絕,屬於回應屬性範圍 |
| 含數字值的 JSON | {"n":1} | 拒絕,只允許字串值 |
| 解碼後重複的 JSON 鍵 | {"a":"1","\u0061":"2"} | 拒絕,詞法掃描偵測到重複 |
採取嚴格拒絕而非默默正規化,正是這個範例在每次執行時行為都一致的原因。一個容忍格式錯誤輸入的除錯工作流程,反而會掩蓋當初引發問題的那份歧義。
範例的限制、範圍與安全性注意事項
範例在兩端都有邊界。輸入必須是 100,000 個 UTF-16 程式碼單位以內,完整輸出必須是 200,000 個程式碼單位以內,而零或無效的輸出長度會被拒絕。介面絕不使用 maxLength 來默默限制輸入長度,因此整份輸入都會送到解析器,整份被接受的結果都會送到輸出區域。
範例絕不會讀取 document.cookie,絕不會修改瀏覽器的 cookie 儲存區,也絕不會發出 HTTP 請求。Cookie 標頭經常帶有即時工作階段祕密,因此請把這個範例當作處理任何含有憑證的文字一樣:保持貼上內容的私密性,並輪替任何已在受信賴環境外暴露的工作階段 token。如需更深入的規則細節,Cookie 轉換器速查表:嚴格 RFC 6265 配對 會逐步走過完整設定檔。
本範例不處理的範圍:Set-Cookie 回應標頭及其屬性、任何序列的百分號解碼、自動加上或移除引號、排序、像 Domain 或 Path 的屬性推斷,以及任何關於某個 cookie 是否安全的宣稱。此處描述的行為奠基於 RFC 6265,轉換器不會在該設定檔之外憑空創造行為。對於一般的 JSON 工作(例如格式化或驗證無關文字),JSON 格式化工具 或 JSON 驗證工具 會更合適,因為這些工具完全不會套用 Cookie 設定檔。
如需更深入的檢視,請參閱 Cron 解析速查表:範圍、步進與範例。