WalletAuthenticator

WalletAuthenticator 是 DID Connect 會話中伺服器端邏輯的核心類別。它負責建立驗證請求、簽署回應以及驗證從使用者錢包返回的資料。它獨立於任何特定的網頁框架運作，處理所有加密操作和 JWT 管理。

要將 DID Connect 整合到 Express.js 應用程式中，請參閱 WalletHandlers 類別，該類別建構於 WalletAuthenticator 之上。

建構函式

new WalletAuthenticator(config)

建立一個 WalletAuthenticator 的新實例。這是為 DID Connect 設定應用程式身份和配置的進入點。

Authenticator Setup

const { WalletAuthenticator } = require('@arcblock/did-connect');
const { fromRandom } = require('@ocap/wallet');

// 應用程式的錢包
const appWallet = fromRandom().toJSON();
const chainHost = 'https://beta.abtnetwork.io/api';
const chainId = 'beta';

const auth = new WalletAuthenticator({
  wallet: appWallet,
  baseUrl: 'https://example.com',
  appInfo: {
    name: 'DID Connect Demo',
    description: 'A demo application for DID Connect',
    icon: 'https://arcblock.oss-cn-beijing.aliyuncs.com/images/wallet-round.png',
    link: 'https://example.com'
  },
  chainInfo: {
    host: chainHost,
    id: chainId,
  },
});

參數

wallet WalletObject | Function (required) — 應用程式的錢包實例或一個返回錢包實例的函式。此錢包用於簽署與使用者錢包之間的所有通訊。
appInfo ApplicationInfo | Function (required) — 一個物件或函式，返回應用程式的基本資訊（名稱、描述、圖示等），這些資訊將顯示在使用者的錢包中。
chainInfo ChainInfo | Function — 應用程式所連接的區塊鏈資訊。可以是一個物件或一個返回物件的函式。預設為「none」鏈。
delegator WalletObject | Function — 授權 config.wallet 代表其行事的錢包。用於委派驗證流程。
delegation string | Function — 證明 delegator 和 wallet 之間委派關係的 JWT 權杖。
baseUrl string — 用於建構回呼 URL 的基礎 URL。通常可以從網頁伺服器上下文中的請求物件推斷出來。
timeout number (default: 8000) — 生成聲明（claims）的超時時間，單位為毫秒。
tokenKey string (default: _t_) — 用於會話權杖的查詢參數鍵。

方法

uri()

產生一個深層連結 URL，該 URL 可以被渲染為 QR code，供 DID Wallet 掃描以啟動會話。

Generating a Connect URL

const connectUrl = auth.uri({
  baseUrl: 'https://example.com',
  pathname: '/api/connect/relay/auth',
  token: 'some_session_token',
  query: { userAction: 'login' },
});

// connectUrl 將類似於：
// https://abtwallet.io/i/?action=requestAuth&url=https%3A%2F%2Fexample.com%2Fapi%2Fconnect%2Frelay%2Fauth%3FuserAction%3Dlogin%26_t_%3Dsome_session_token

參數

params object — 包含 URI 參數的物件。
- baseUrl string — 用於建構回呼 URL 的基礎 URL。
- pathname string — 錢包回呼端點的路徑。
- token string — 此驗證操作的唯一會話權杖。
- query object (default: {}) — 在回呼 URL 中保留的額外查詢參數物件。

返回值

**** string — 一個用於 DID Wallet 的深層連結 URL。

sign()

簽署一個要發送給錢包的驗證請求。這個 JWT 格式的回應包含了應用程式的資訊、鏈的資訊以及向使用者請求的特定聲明（claims）。

Signing an Auth Request

const authResponse = await auth.sign({
  claims: { profile: { items: ['fullName', 'email'] } }, // 請求使用者的姓名和電子郵件
  pathname: '/api/connect/relay/auth',
  baseUrl: 'https://example.com',
  challenge: 'random_challenge_string',
  context: { token: 'some_session_token' },
});

// authResponse 包含 { appPk, authInfo, ... }

參數

params object (required) — 用於簽署驗證請求的參數。
- claims object (required) — 一個定義需要從使用者錢包獲取資訊的物件。詳情請參閱 Claims 參考。
- pathname string — 用於組裝回呼 URL 的路徑名稱。
- baseUrl string — 回呼的基礎 URL。
- challenge string — 一個隨機的挑戰字串，以防止重放攻擊。
- context object (required) — 包含會話上下文的物件。
  - token string (required) — 會話權杖。
  - userDid string — 使用者的 DID。
  - userPk string — 使用者的公鑰。
  - sharedKey string — 應用程式和錢包之間用於敏感聲明（claims）的共享金鑰。
  - encryptionKey string — 來自錢包的加密金鑰。
- request object — 來自網頁伺服器的原始請求物件（如果有的話）。

返回值

**** Promise<object> — 一個解析為物件的 promise，該物件包含已簽署的 authInfo (JWT)、應用程式的公鑰 appPk，以及其他相關金鑰，如 agentPk 或 sharedKey。

signResponse()

簽署一個簡單的、最終的回應給錢包，通常在操作成功後或報告錯誤時使用。此回應可以選擇性地將使用者的錢包重新導向到一個新的 URL。

Signing a Success Response

const successResponse = await auth.signResponse({
  successMessage: 'Login successful!',
  nextUrl: 'https://example.com/dashboard',
}, 'https://example.com', requestContext);

// 此回應可以發送回錢包。

參數

params object (required) — 回應的參數。
- successMessage string — 成功時在錢包中顯示的訊息。
- errorMessage string — 錯誤時在錢包中顯示的訊息。
- nextUrl string — 訊息顯示後在錢包的 webview 中開啟的 URL。
- nextWorkflow string — 指向另一個 DID Connect 工作流程的 URL，用於將多個請求串聯在一起。
- response object — 任何要包含在回應中的額外 JSON 資料。
- cookies object — 在開啟 nextUrl 之前要設定為 cookie 的鍵值對。
- storages object — 在開啟 nextUrl 之前要設定為 localStorage 的鍵值對。

返回值

**** Promise<object> — 一個解析為物件的 promise，該物件包含已簽署的 authInfo 和 appPk。

verify()

驗證從 DID Wallet 發送的回應。它使用使用者的公鑰檢查簽名，並解碼 JWT 以提取聲明（claims）和其他會話資訊。

Verifying a Wallet Response

try {
  const walletResponse = {
    userPk: 'user_public_key_from_wallet',
    userInfo: 'jwt_token_from_wallet',
    token: 'the_original_session_token'
  };

  const verificationResult = await auth.verify(walletResponse);

  console.log('驗證成功！');
  console.log('使用者 DID：', verificationResult.userDid);
  console.log('請求的聲明 (Claims)：', verificationResult.claims);
} catch (error) {
  console.error('驗證失敗：', error.message);
}

參數

data object (required) — 一個包含來自錢包回應的 userPk 和 userInfo (JWT) 的物件。
locale string (default: en) — 錯誤訊息的地區設定。
enforceTimestamp boolean (default: true) — 是否強制執行 JWT 的時間戳有效性。設定為 false 以除錯時間同步問題。

返回值

**** Promise<object> — 一個解析為已解碼物件的 promise。
- token string — 原始的會話權杖。
- userDid string — 已驗證使用者的 DID。
- userPk string — 已驗證使用者的公鑰。
- claims array — 使用者履行的聲明 (claims) 陣列。
- challenge string — 原始的挑戰字串。
- timestamp number — JWT 的發行時間戳。

類型定義

ApplicationInfo

此物件定義了在連線會話期間向使用者在其 DID Wallet 中顯示的有關您應用程式的資訊。

name string (required) — 您的應用程式名稱。
description string (required) — 您的應用程式簡要描述。
icon string (required) — 您的應用程式標誌的 URL。
link string — 指向您應用程式首頁的連結，允許使用者從他們的錢包返回。
publisher string — 應用程式發行者的 DID。如果未提供，將自動設定為應用程式錢包的 DID。
path string (default: https://abtwallet.io/i/) — 錢包的深層連結 URL 前綴。

ChainInfo

此物件指定您的應用程式與之互動的區塊鏈。

id string (required) — 鏈的 ID（例如，「beta」、「main」）。對於 EVM 鏈，這是鏈 ID 號碼。
host string (required) — ArcBlock 鏈的 GraphQL 端點，或 EVM 鏈的 JSON-RPC 端點。
type string (default: arcblock) — 區塊鏈的類型。可以是「arcblock」、「ethereum」等。

現在您已經了解如何建立和管理驗證邏輯，下一步是將其整合到網頁伺服器中。請前往 WalletHandlers API 參考以學習如何將 DID Connect 端點附加到 Express.js 應用程式。