跳到主要內容

驗證

@blocklet/server-js 函式庫提供兩種主要方法來驗證 API 請求：驗證權杖 (Auth Token) 和存取金鑰 (Access Key)。應根據應用程式的環境和安全需求選擇合適的方法。驗證權杖通常用於面向使用者的應用程式 (如瀏覽器)，而存取金鑰則設計用於安全的伺服器對伺服器通訊。

本節將說明如何實作這兩種驗證策略。

Authentication

使用驗證權杖

這是使用者主動登入的應用程式 (例如在瀏覽器中執行的 Web 應用程式) 最常見的驗證方法。驗證權杖通常從使用者的會話中取得，且在有限時間內有效。

若要使用此方法，請實例化用戶端，並使用 setAuthToken 方法提供權杖。

使用 setAuthToken

javascript
import BlockletServerClient from '@blocklet/server-js';

// 您的 Blocklet Server 端點
const endpoint = 'http://localhost:4000/api';
const client = new BlockletServerClient(endpoint);

// 使用者登入後從其會話中取得的權杖。
// 通常可以在您 Blocklet Server 網域的瀏覽器 localStorage 中，以 `__sst` 為鍵找到此權杖。
const userAuthToken = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0eXBlIjoidXNlciIsImRpZCI6Inoxbjd5TG5BRDV3VHJ5RjU2S0IzU3N0MVJlbVpVQTQ4OEhoIiwicm9sZSI6ImFkbWluIiwicHJvdmlkZXIiOiJ3YWxsZXQiLCJreWMiOjAsImVsZXZhdGVkIjpmYWxzZSwiZnVsbE5hbWUiOiJza3lwZXNreSIsImlhdCI6MTc2MTAzODQ1OSwiZXhwIjoxNzYxMDQyMDU5fQ.rLoDz0o2Jg83BP_IGF8bwhHT3Qnyhy8KfVQNzSa1ycY';

client.setAuthToken(userAuthToken);

// 所有後續的 API 呼叫都將自動進行驗證
async function fetchNodeInfo() {
  try {
    const response = await client.getNodeInfo();
    console.log('Node Info:', response.info.name);
  } catch (error) {
    console.error('Failed to fetch node info:', error);
  }
}

fetchNodeInfo();

設定權杖後，用戶端會在所有後續的 GraphQL 請求中自動包含一個 Authorization: Bearer <token> 標頭。

使用存取金鑰

存取金鑰適用於伺服器對伺服器通訊、背景服務或任何沒有使用者會話的非互動式環境。此方法提供了一種更安全、更持久的方式來授予程式化存取權限。

若要使用存取金鑰，您必須使用用戶端的原生版本，其中包含必要的密碼學函式庫。

匯入原生用戶端

javascript
import BlockletServerClient from '@blocklet/server-js/native';

然後，使用 setAuthAccessKey 方法設定用戶端。此方法接受一個包含以下欄位的物件：

  • accessKeyId string (required) — 金鑰的公開識別碼。這通常是關聯錢包的 DID 位址。
  • accessKeySecret string (required) — 用於簽署請求的密鑰 (或私鑰)。切勿在用戶端程式碼中洩漏此金鑰。
  • type any (required) — 簽署演算法或錢包類型。支援的值包含來自 @ocap/wallet 的錢包類型 (例如 eth、arc)，以及 'sha256' 和 'totp'。此類型必須與在 Blocklet Server 中設定存取金鑰的方式相符。

使用 setAuthAccessKey

javascript
import BlockletServerClient from '@blocklet/server-js/native';

const endpoint = 'http://localhost:4000/api';
const client = new BlockletServerClient(endpoint);

client.setAuthAccessKey({
  accessKeyId: 'zNKjw25A312AbC5A1234567890abcdefABCDEF', // 您的存取金鑰 ID
  accessKeySecret: 'sk_1234567890abcdefABCDEF1234567890abcdef', // 您的存取金鑰密鑰
  type: 'eth' // 與金鑰關聯的錢包類型
});

// 所有後續的 API 呼叫都將使用簽署的標頭進行驗證
async function fetchBlocklets() {
  try {
    const response = await client.getBlocklets();
    console.log(`Found ${response.blocklets.length} blocklets.`);
  } catch (error) {
    console.error('Failed to fetch blocklets:', error);
  }
}

fetchBlocklets();

使用存取金鑰時，用戶端會為每個請求產生一個唯一的簽章，並將其連同 x-access-key-id 和其他必要的驗證標頭一起在 x-access-signature 標頭中傳送。這確保了每個請求都能被安全地驗證，而不會洩漏密鑰。

現在您已了解如何驗證您的請求，可以繼續前往 API 參考 來探索可用的查詢和變更。