WalletHandlers クラスは、DID Connect ワークフローを Express.js または同様のサーバーサイドフレームワークにシームレスに統合するために設計された高レベルのユーティリティです。指定されたアクションに必要なすべての API エンドポイントの設定を自動化し、アプリケーションとユーザーの DID ウォレット間の通信を処理します。
これは、メッセージの暗号署名と検証を管理する WalletAuthenticator と連携して動作します。WalletHandlers は Node.js の EventEmitter 上に構築されているため、トークンストレージのセッション状態が変化するにつれて、さまざまなライフサイクルイベントをリッスンできます。
コンストラクタ
DID Connect ハンドラのインスタンスを作成します。このインスタンスは、DID Connect プロセスの HTTP リクエストの処理を調整します。
DID Connect Handler Setup
const { WalletHandlers } = require('@did-connect/handler');
const { WalletAuthenticator } = require('@did-connect/authenticator');
const { FileStorage } = require('@did-connect/storage-file');
// 1. アプリのウォレットと情報でオーセンティケータを初期化
const authenticator = new WalletAuthenticator({ wallet, appInfo, chainInfo });
// 2. ストレージアダプタを初期化してセッション状態を管理
const tokenStorage = new FileStorage({ dbPath: './sessions.json' });
// 3. ハンドラインスタンスを作成
const handlers = new WalletHandlers({
authenticator,
tokenStorage,
});パラメータ
- config
object(required) — WalletHandlers インスタンスの設定オブジェクト。- authenticator
WalletAuthenticator(required) — 暗号操作を担当するWalletAuthenticatorのインスタンス。 - tokenStorage
object(required) — セッション状態を処理するトークンストレージインスタンス（例：FileStorage、MongoStorage）。 - pathTransformer
function— ウォレットコールバックの URL パス名を変換するためのオプションの関数。プロキシや複雑なルーティングシナリオで役立ちます。 - onConnect
function— ウォレットが QR コードをスキャンし、認証リクエストが送信される前に実行されるオプションのグローバルコールバック。グローバルな権限チェックに使用できます。プロセスを停止するにはエラーをスローします。 - options
object— ハンドラの動作をカスタマイズするためのオプションのオブジェクト。- prefix
string(default:/api/did) — 生成されるすべてのエンドポイントの URL プレフィックス。 - cleanupDelay
number(default:60000) — 完了したセッションをストレージからクリーンアップする前に待機する時間（ミリ秒）。 - tokenKey
string(default:_t_) — セッショントークンのクエリパラメータキー。 - encKey
string(default:_ek_) — 暗号化キーのクエリパラメータキー。 - versionKey
string(default:_v_) — プロトコルバージョンのクエリパラメータキー。
- prefix
- authenticator
メソッド
attach(config)
これは WalletHandlers クラスの主要なメソッドです。特定のユーザーアクション（例：「login」、「payment」）に必要な DID Connect ルートを Express アプリにアタッチします。このメソッドは、トークン生成からウォレットの応答処理まで、接続ライフサイクル全体を処理するための一連のエンドポイントを作成します。
アタッチされると、指定された action に対して以下のルートが作成されます：
GET {prefix}/{action}/token: 新しいセッショントークンを作成します。POST {prefix}/{action}/token: 新しいセッショントークンを作成します。GET {prefix}/{action}/status: セッショントークンのステータス（例：pending、scanned、approved）を確認します。GET {prefix}/{action}/timeout: セッショントークンを手動で期限切れにします。GET {prefix}/{action}/auth: ウォレットが認証要件を取得するためのエンドポイント。POST {prefix}/{action}/auth: ウォレットが署名付き応答を送信するためのエンドポイント。
パラメータ
- config
object(required) — ルートをアタッチするための設定オブジェクト。- app
object(required) — Express アプリのインスタンス。 - action
string(required) — このワークフローの一意の名前（例：「login」、「claim-asset」）。これは URL の一部になります。 - onAuth
function(required) — ユーザーがウォレットでのフローを正常に完了した後に実行されるコールバック。ここで検証済みデータを処理します。 - claims
object[]— ユーザーに要求するクレームのオプションの配列（例：profile、signature）。 - onStart
function— 新しいセッションが開始されたときに実行されるオプションのコールバック。 - onConnect
function— ウォレットがコードをスキャンしたときに実行されるオプションのコールバック。この特定のアクションに対してコンストラクタのonConnectをオーバーライドします。 - onDecline
function— ユーザーがウォレットでリクエストを拒否した場合に実行されるオプションのコールバック。 - onComplete
function— ワークフロー全体が終了し、セッショントークンが破棄された後に実行されるオプションのコールバック。 - onExpire
function— セッショントークンが期限切れになったときのオプションのコールバック。 - onError
function(default:console.error) — プロセス中に発生したエラーを処理するためのオプションのコールバック。 - authPrincipal
boolean | string(default:true) — ユーザーの DID を確立するために、最初にauthPrincipalクレームを要求するかどうか。 - persistentDynamicClaims
boolean(default:false) — 動的に生成されたクレームをセッションストレージに永続化するかどうか。
- app
例
Attach Login Handler
const express = require('express');
// ... コンストラクタの例からの authenticator と tokenStorage の設定
const app = express();
const handlers = new WalletHandlers({ authenticator, tokenStorage });
handlers.attach({
app,
action: 'login',
claims: [{ type: 'profile' }], // ユーザーのプロファイルを要求
onAuth: async ({ userDid, claims }) => {
// ログイン成功後のコアロジック。
// userDid を使用してデータベースでユーザーを検索または作成します。
const profile = claims.find(x => x.type === 'profile');
console.log(`User ${userDid} logged in with name: ${profile.fullName}.`);
// これで、ユーザーの Web セッションに Cookie または JWT を設定できます。
},
onComplete: ({ token }) => {
console.log(`Session ${token} completed and cleaned up.`);
},
onError: ({ error }) => {
console.error('An error occurred in the login flow:', error);
}
});
app.listen(3000, () => {
console.log('DID Connect server is running on port 3000');
});イベント
WalletHandlers は EventEmitter を拡張し、tokenStorage インスタンスをリッスンするため、イベントをサブスクライブしてセッションのライフサイクルを監視できます。これは、たとえば WebSocket を使用して QR コードがスキャンされたときに UI を更新するなど、ユーザーにリアルタイムのフィードバックを提供するのに特に役立ちます。
| Event | Payload | Description |
|---|---|---|
created | object | 新しいセッショントークンが作成されたときに発行されます。ペイロードにはトークンと初期セッションデータが含まれます。 |
updated | object | セッションが更新されたときに発行されます。ペイロードには更新されたセッションデータが含まれます。一般的な使用法は status: 'scanned' をチェックすることです。 |
deleted | object | セッショントークンが完了、期限切れ、または手動タイムアウトによって破棄されたときに発行されます。ペイロードには削除されたトークンが含まれます。 |
例
Listening to Session Events
// 'io' が Express アプリにアタッチされた Socket.IO サーバーインスタンスであると仮定
handlers.on('updated', (payload) => {
// 特定の Web クライアントに QR コードがスキャンされたことを通知
if (payload.status === 'scanned') {
console.log(`Wallet scanned token: ${payload.token}`);
// 'sid'（ソケット ID）はセッション作成時にセッションに保存する必要があります
if (payload.sid) {
io.to(payload.sid).emit('wallet_scanned');
}
}
});
handlers.on('deleted', ({ token }) => {
console.log(`Token ${token} was deleted from storage.`);
});