Private State Tokens 開發人員指南

過去，第三方 Cookie 用於儲存及傳送使用者狀態的相關資訊，例如登入狀態、所用裝置的相關資訊，或是使用者是否為已知且受信任的對象。例如，使用者是否已透過單一登入登入、使用者是否擁有特定類型的相容裝置，或使用者是否為已知且值得信任的對象。隨著第三方 Cookie 支援功能淘汰，許多用途都需要以其他方式支援。

私密狀態權杖提供在網路上分享資訊的方式，但透過控管實際可分享的資料量，以保護隱私權的方式進行。

Private State Tokens (舊稱 Trust Tokens) 可在不同環境之間傳達使用者的真實性，同時協助網站防範詐欺及辨別機器人和真人，且不會進行被動追蹤。

本文將說明實作私密狀態權杖 (PST) 的技術細節。如需更概略的說明，請參閱「PST 總覽」。

Private State Tokens 的運作方式

在 PST 中，發行者和兌換者之間的關係是瞭解這項技術的關鍵。 發行者和兌換者可為同一家公司。

• 簽發者：這些實體會取得使用者的部分信號 (例如使用者是否為機器人)，並將信號嵌入儲存在使用者裝置上的權杖 (詳情請參閱下節)。
• 兌換者 - 這些實體可能沒有使用者的信號，但需要瞭解使用者的某些資訊 (例如使用者是否為機器人)，並要求從發行者兌換權杖，以瞭解使用者的可信度。

每次 PST 互動都需要發行者和兌換者共同作業，在網路上分享信號。這些信號是粗略值，不夠詳細，無法識別個人。

我適合使用私密狀態權杖嗎？

如果公司要做出信任決策，並希望在不同情境中都能取得相關資訊，或許可以考慮使用 PST。如要進一步瞭解 PST 的潛在用途，請參閱這篇說明文件。

發放及兌換權杖

PST 導入作業分為三個階段：

1. 核發權杖
2. 兌換權杖
3. 轉寄兌換記錄

在第一階段，權杖會發給瀏覽器 (通常是在某種驗證之後)。在第二階段，另一個實體會要求兌換已發行的權杖，以讀取該權杖中的值。在最後階段，兌換方會收到兌換記錄 (RR)，其中包含權杖中的值。兌換方隨後可將該記錄做為使用者認證，用於各種用途。

定義權杖策略

如要定義權杖策略，您需要瞭解 PST 的重要概念 (權杖和兌換記錄)、變數、行為和限制，才能思考這些概念在您應用情境中的潛在用途。

代幣和兌換記錄：兩者之間有何關係？

每個裝置最多可為每個頂層網站和發行者儲存 500 個權杖。此外，每個權杖都有中繼資料，說明簽發者用來簽發權杖的金鑰。您可以在兌換程序中，根據這項資訊決定是否要兌換權杖。瀏覽器會在使用者裝置上儲存 PST 資料，且只能透過 PST API 存取。

兌換權杖後，裝置會儲存兌換記錄 (RR)。 這個儲存空間會做為日後兌換的快取。每部裝置、每個頁面和每個發行者每 48 小時最多可兌換兩個權杖。新的兌換呼叫會盡可能使用快取的 RR，而不是向發行者提出要求。

1. 系統會核發新權杖 (每個發行者、網站和裝置最多 500 個)。
2. 所有權杖都會儲存在裝置上的權杖儲存空間 (類似於 Cookie 儲存空間)。
3. 如果找不到有效的 RR，則可在發行後產生新的 RR (每 48 小時最多 2 個)。
4. RR 在到期前都視為有效，並會做為本機快取使用。
5. 新的兌換呼叫會命中本機快取 (不會產生新的 RR)。

定義用途後，您必須仔細定義 RR 的生命週期，因為這會決定您在案件中可使用 RR 的次數。

定義策略前，請務必瞭解下列重要行為和變數：

範例情境

情境 1：RR 的生命週期少於 24 小時 (t=t)，且在 48 小時內兌換多次。

情境 2：RR 的生命週期為 24 小時，且在 48 小時內兌換多次。

情境 3：RR 的生命週期為 48 小時，且在 48 小時內多次兌換。

執行試用版

建議您先設定試用版，再採用 PST。

執行這項示範時，瀏覽器會使用示範發行者和兌換者伺服器提供及耗用權杖。

技術考量

如要讓試用版發揮最佳效能，請按照下列步驟操作：

• 請務必先停止所有 Chrome 執行個體，再使用旗標執行 Chrome。
• 如果您在 Windows 電腦上執行，請參閱 這份指南，瞭解如何將參數傳遞至 Chrome 可執行二進位檔。
• 使用示範應用程式時，開啟「應用程式」>「儲存空間」>「私人狀態權杖」下的 Chrome 開發人員工具，即可查看示範發行者發行或兌換的權杖。

設定採用目標

本節說明成為 PST 發行者或兌換者的資格條件。

成為核發單位

發卡機構在 PST 中扮演重要角色。並為權杖指派值，判斷使用者是否為機器人。如要以發行者身分開始使用 PST，請完成發行者註冊程序。

如要申請成為發行者，發行者網站的營運者必須使用「New PST Issuer」範本，在 GitHub 存放區上開啟新的問題。請按照存放區的指引填寫問題。 端點通過驗證後，就會併入這個存放區，Chrome 伺服器端基礎架構也會開始擷取這些金鑰。

簽發機構伺服器

核發者和兌換者是 PST 的主要參與者；伺服器和權杖是 PST 的主要工具。我們已在 GitHub 說明文件中提供權杖相關資訊，但仍想進一步說明 PST 伺服器。如要設定為 PST 發行者，請先設定發行伺服器。

部署環境：簽發機構伺服器

如要實作權杖簽發者伺服器，您必須建構自己的伺服器端應用程式，公開 HTTP 端點。

簽發機構元件由兩個主要模組組成：(1) 簽發機構伺服器和 (2) 權杖簽發機構。

與所有面向網路的應用程式一樣，建議您為發行者伺服器新增一層保護措施。

1. 簽發者伺服器：在我們的範例實作中，簽發伺服器是 Node.js 伺服器，使用 Express 架構代管簽發者 HTTP 端點。您可以查看 GitHub 上的程式碼範例。

2. 權杖簽發者：簽發者加密元件不需要任何特定語言，但由於這個元件有效能需求，我們提供 C 實作做為範例，其中使用 BoringSSL 程式庫管理權杖。您可以在 GitHub 上找到簽發者程式碼範例，以及安裝作業的相關資訊。

3. 金鑰：權杖發行者元件會使用自訂 EC 金鑰加密權杖。這些金鑰必須受到保護，並儲存在安全儲存空間。

發卡機構伺服器的技術規定

根據通訊協定，您需要在發行者伺服器中實作至少兩個 HTTP 端點：

• 金鑰承諾 (例如 /.well-known/private-state-token/key-commitment)： 瀏覽器可透過這個端點取得加密公開金鑰詳細資料，確認伺服器是否合法。
  • GitHub 上的程式碼範例
  • 觀看示範
• 核發權杖 (例如 /.well-known/private-state-token/issuance)： 所有權杖要求都會在這個權杖核發端點處理。這個端點將做為權杖簽發者元件的整合點。
  • GitHub 上的程式碼範例
  • 查看示範

如先前所述，由於這個伺服器預期會處理大量流量，因此建議您使用可擴充的基礎架構 (例如雲端環境) 部署伺服器，以便根據需求變化調整後端。

將呼叫傳送至發卡機構伺服器

在發卡機構堆疊中導入網站擷取呼叫，以便核發新權杖。

 // issuer request
    await fetch("/.well-known/private-state-token/issuance", {
      method: "POST",
      privateToken: {
        version: 1,
        operation: "token-request"
      }
    });

查看程式碼範例。

兌換伺服器

您必須自行建構伺服器端應用程式，才能實作權杖兌換服務。這樣您就能讀取簽發機構傳送的權杖。下列步驟說明如何兌換權杖，以及如何讀取與這些權杖相關聯的兌換記錄。

您可以選擇在同一部伺服器 (或伺服器群組) 中執行發行者和兌換者。

兌換伺服器的技術規定

根據通訊協定，您至少需要為兌換伺服器實作兩個 HTTP 端點：

• /.well-known/private-state-token/redemption：所有代幣兌換作業的處理端點。這個端點將整合權杖兌換元件。
  • GitHub 上的程式碼範例
  • 示範模式

將呼叫傳送至兌換伺服器

如要兌換權杖，您必須在兌換者堆疊中導入網站擷取呼叫，才能兌換先前發放的權杖。

    // redemption request
    await fetch("/.well-known/private-state-token/redemption", {
      method: "POST",
      privateToken: {
        version: 1,
        operation: "token-redemption",
        refreshPolicy: "none"
      }
    });

請參閱程式碼範例。

兌換權杖後，您可以透過另一個擷取呼叫傳送兌換記錄 (RR)：

    // attach redemption records from the issuers to the request
    await fetch("<DESTINATION_RESOURCE>", {
      method: "POST",
      privateToken: {
        version: 1,
        operation: "send-redemption-record",
        issuers: [<ISSUER_DOMAIN>]
      }
    });

請參閱程式碼範例。

部署實作項目

如要測試導入作業，請先前往發出呼叫的網頁，並確認權杖是按照您的邏輯建立。在後端確認呼叫是否符合規格。 接著，前往發出兌換呼叫的網頁，並確認已按照您的邏輯建立 RR。

實際部署

建議您選擇特定用途的目標網站：

• 每月造訪次數較少 (每月造訪次數約 <100 萬)：您應先將 API 部署給一小群目標對象
• 您擁有並掌控：如有需要，您可以快速停用實作項目，不必經過複雜的核准程序
• 最多只能有一個發行者：限制權杖數量，簡化測試。
• 最多兩名兌換者：如有問題，您需要簡化疑難排解程序。

權限政策

為確保 PST API 正常運作，頂層網頁和使用該 API 的任何子資源都必須能存取 PST API。

權杖要求作業是由 private-state-token-issuance 指令控制。token-redemption 和 send-redemption-record 作業是由 private-state-token-redemption 指令控管。在 Chrome 132 以上版本中，這些指令的許可清單預設為 * (所有來源)。也就是說，頂層網頁、同源 iframe 和跨源 iframe 都能使用這項功能，無須明確委派。

如要選擇不為網站上的特定網頁核發或兌換 PST 權杖，請在每個網頁的 Permissions-Policy 標頭中加入 private-state-token-issuance=() 和 private-state-token-redemption=()。

您也可以使用 Permissions-Policy 標頭，控管第三方對 PST 的存取權。將 self 和您要允許存取 API 的任何來源，做為標頭來源清單的參數。舉例來說，如要完全禁止在自有來源和 https://example.com 以外的所有瀏覽環境中使用 PST，請設定下列 HTTP 回應標頭：

Permissions-Policy:private-state-token-issuance=(self "https://example.com"),private-state-token-redemption=(self "https://example.com")

如要為所有跨來源資源啟用 API，請將來源清單設為 *。

瞭解如何使用權限政策控管 Privacy Sandbox 功能，或深入瞭解權限政策。

疑難排解

您可以透過 Chrome 開發人員工具的「網路」和「應用程式」分頁檢查 PST。

在「網路」分頁中：

在「應用程式」分頁中：

進一步瞭解這項開發人員工具整合。

用戶端最佳做法

如果網站的重要功能需要特定權杖核發者，請優先處理這些核發者。請先呼叫這些偏好發行者，再載入任何其他指令碼。hasPrivateToken(issuer)這對避免潛在兌換失敗至關重要。

每個頂層的發行者最多只能有兩名，第三方指令碼也可能會嘗試呼叫 hasPrivateToken(issuer)，優先處理自己偏好的發行者。因此，請預先保護重要發行者，確保網站正常運作。

  // Prioritize your critical token issuer.
  document.hasPrivateToken('https://critical-issuer.example')
    .then(hasToken => {
      if (hasToken) {
        // Use the token or perform actions based on its availability.
      } else {
        // Handle the case where the token is not available.
      }
    });

  // Load third-party scripts or secure another token issuer (up to two in total).

伺服器最佳做法和疑難排解

為確保發行者和兌換者伺服器能有效運作，建議您採用下列最佳做法，避免 PST 發生任何存取、安全性、記錄或流量問題。

• 端點必須使用 TLS 1.3 或 1.2，套用強效加密技術。
• 基礎架構必須能處理不同流量 (包括尖峰流量)。
• 請確保金鑰受到保護且安全無虞，並符合存取控制政策、金鑰管理策略和業務持續性計畫。
• 在堆疊中加入可觀測性指標，確保您在投入生產後，能瞭解使用情況、瓶頸和效能問題。

更多資訊

1. 請參閱開發人員說明文件：
   1. 首先請詳讀總覽，瞭解 PST 和相關功能。
   2. 觀看 PST 簡介影片。
   3. 試用 PST 示範模式。
   4. 此外，請參閱 API 說明，進一步瞭解相關詳細資訊。
   5. 進一步瞭解 API 的現行規格。
2. 使用 GitHub 問題或 W3C 通話參與討論。
3. 如要進一步瞭解任何術語，請參閱 Privacy Sandbox 詞彙表。
4. 如要進一步瞭解 Chrome 概念，例如「來源試用」或「Chrome 旗標」，請觀看 goo.gle/cc 提供的短片和文章。