WalletAuthenticator

WalletAuthenticatorは、DID Connectセッションにおけるサーバーサイドロジックのコアクラスです。認証リクエストの作成、レスポンスへの署名、ユーザーのウォレットから返されたデータの検証を担当します。特定のWebフレームワークから独立して動作し、すべての暗号化操作とJWT管理を処理します。

DID ConnectをExpress.jsアプリケーションに統合するには、WalletAuthenticatorを基盤とするWalletHandlersクラスを参照してください。

コンストラクタ

new WalletAuthenticator(config)

WalletAuthenticatorの新しいインスタンスを作成します。これは、アプリケーションのIDと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: '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。Webサーバーのコンテキストでは、リクエストオブジェクトから推測できることが多いです。
timeout number (default: 8000) — クレーム生成のタイムアウト（ミリ秒）。
tokenKey string (default: _t_) — セッショントークンに使用されるクエリパラメータキー。

メソッド

uri()

DID Walletがスキャンしてセッションを開始するためのQRコードとしてレンダリングできるディープリンクURLを生成します。

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形式のレスポンスには、アプリケーション情報、チェーン情報、およびユーザーに要求されている特定のクレームが含まれます。

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) — ユーザーのウォレットから要求される情報を定義するオブジェクト。詳細はクレームリファレンスを参照してください。
- pathname string — コールバックURLを組み立てるためのパス名。
- baseUrl string — コールバックのベースURL。
- challenge string — リプレイ攻撃を防ぐためのランダムなチャレンジ文字列。
- context object (required) — セッションコンテキストを含むオブジェクト。
  - token string (required) — セッショントークン。
  - userDid string — ユーザーのDID。
  - userPk string — ユーザーの公開鍵。
  - sharedKey string — 機密性の高いクレームのためにアプリとウォレット間で共有されるキー。
  - encryptionKey string — ウォレットからの暗号化キー。
- request object — Webサーバーからの元のリクエストオブジェクト（利用可能な場合）。

戻り値

**** Promise<object> — 署名された authInfo (JWT)、アプリケーションの公開鍵 appPk、および agentPk や sharedKey などの他の関連キーを含むオブジェクトに解決されるPromise。

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を開く前にクッキーとして設定されるキーと値のペア。
- storages object — nextUrlを開く前にlocalStorageとして設定されるキーと値のペア。

戻り値

**** Promise<object> — 署名された authInfo と appPk を含むオブジェクトに解決されるPromise。

verify()

DID Walletから送信されたレスポンスを検証します。ユーザーの公開鍵を使用して署名をチェックし、JWTをデコードしてクレームやその他のセッション情報を抽出します。

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('要求されたクレーム:', 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 — ユーザーによって満たされたクレームの配列。
- 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」などがあります。

認証ロジックの作成と管理方法を理解したところで、次のステップはそれをWebサーバーに統合することです。WalletHandlers APIリファレンスに進み、DID ConnectエンドポイントをExpress.jsアプリケーションにアタッチする方法を学んでください。