WalletAuthenticator

The WalletAuthenticator is the core class for server-side logic in a DID Connect session. It is responsible for creating authentication requests, signing responses, and verifying the data returned from the user's wallet. It operates independently of any specific web framework, handling all the cryptographic operations and JWT management.

For integrating DID Connect into an Express.js application, see the WalletHandlers class, which builds upon WalletAuthenticator.

Constructor

new WalletAuthenticator(config)

Creates a new instance of the WalletAuthenticator. This is the entry point for setting up your application's identity and configuration for DID Connect.

Authenticator Setup

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

// The application's 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,
  },
});

Parameters

wallet WalletObject | Function (required) — The application's wallet instance or a function that returns one. This wallet is used to sign all communications with the user's wallet.
appInfo ApplicationInfo | Function (required) — An object or function that returns the application's basic information (name, description, icon, etc.) to be displayed in the user's wallet.
chainInfo ChainInfo | Function — Information about the blockchain the application is connected to. Can be an object or a function that returns one. Defaults to a 'none' chain.
delegator WalletObject | Function — The wallet that authorizes config.wallet to act on its behalf. Used for delegated authentication flows.
delegation string | Function — The JWT token that proves the delegation relationship between delegator and wallet.
baseUrl string — The base URL for constructing callback URLs. Can often be inferred from the request object in a web server context.
timeout number (default: 8000) — Timeout in milliseconds for generating claims.
tokenKey string (default: _t_) — The query parameter key used for the session token.

Methods

uri()

Generates a deep link URL that can be rendered as a QR code for the DID Wallet to scan and initiate a session.

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 will be similar to:
// https://abtwallet.io/i/?action=requestAuth&url=https%3A%2F%2Fexample.com%2Fapi%2Fconnect%2Frelay%2Fauth%3FuserAction%3Dlogin%26_t_%3Dsome_session_token

Parameters

params object — An object containing the parameters for the URI.
- baseUrl string — The base URL from which the callback URL will be constructed.
- pathname string — The path for the wallet callback endpoint.
- token string — The unique session token for this authentication action.
- query object (default: {}) — An object of additional query parameters to persist in the callback URL.

Returns

**** string — A deep link URL for DID Wallet.

sign()

Signs an authentication request to be sent to the wallet. This JWT-formatted response contains the application's info, chain info, and the specific claims being requested from the user.

Signing an Auth Request

const authResponse = await auth.sign({
  claims: { profile: { items: ['fullName', 'email'] } }, // Requesting user's name and email
  pathname: '/api/connect/relay/auth',
  baseUrl: 'https://example.com',
  challenge: 'random_challenge_string',
  context: { token: 'some_session_token' },
});

// authResponse contains { appPk, authInfo, ... }

Parameters

params object (required) — Parameters for signing the authentication request.
- claims object (required) — An object defining the information required from the user's wallet. See Claims Reference for details.
- pathname string — The pathname to assemble the callback URL.
- baseUrl string — The base URL for the callback.
- challenge string — A random challenge string to prevent replay attacks.
- context object (required) — An object containing session context.
  - token string (required) — The session token.
  - userDid string — The user's DID.
  - userPk string — The user's public key.
  - sharedKey string — Shared key between app and wallet for sensitive claims.
  - encryptionKey string — Encryption key from the wallet.
- request object — The original request object from the web server, if available.

Returns

**** Promise<object> — A promise that resolves to an object containing the signed authInfo (JWT), the application's public key appPk, and other relevant keys like agentPk or sharedKey.

signResponse()

Signs a simple, final response to the wallet, typically used after a successful operation or to report an error. This response can optionally redirect the user's wallet to a new URL.

Signing a Success Response

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

// This response can be sent back to the wallet.

Parameters

params object (required) — Parameters for the response.
- successMessage string — A message to display in the wallet on success.
- errorMessage string — A message to display in the wallet on error.
- nextUrl string — A URL to open in the wallet's webview after the message is displayed.
- nextWorkflow string — A URL to another DID Connect workflow to chain multiple requests together.
- response object — Any additional JSON data to be included in the response.
- cookies object — Key-value pairs to be set as cookies before opening nextUrl.
- storages object — Key-value pairs to be set as localStorage before opening nextUrl.

Returns

**** Promise<object> — A promise that resolves to an object containing the signed authInfo and appPk.

verify()

Verifies a response sent from the DID Wallet. It checks the signature using the user's public key and decodes the JWT to extract the claims and other session information.

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('Verification successful!');
  console.log('User DID:', verificationResult.userDid);
  console.log('Requested Claims:', verificationResult.claims);
} catch (error) {
  console.error('Verification failed:', error.message);
}

Parameters

data object (required) — An object containing the userPk and userInfo (the JWT) from the wallet's response.
locale string (default: en) — The locale for error messages.
enforceTimestamp boolean (default: true) — Whether to enforce the JWT's timestamp validity. Set to false to debug time-sync issues.

Returns

**** Promise<object> — A promise that resolves to a decoded object.
- token string — The original session token.
- userDid string — The DID of the authenticated user.
- userPk string — The public key of the authenticated user.
- claims array — An array of claims fulfilled by the user.
- challenge string — The original challenge string.
- timestamp number — The issuance timestamp of the JWT.

Type Definitions

ApplicationInfo

This object defines the information about your application that is displayed to the user in their DID Wallet during a connect session.

name string (required) — The name of your application.
description string (required) — A brief description of your application.
icon string (required) — A URL to your application's logo.
link string — A link to your application's home page, allowing the user to return from their wallet.
publisher string — The DID of the application publisher. Automatically set to the application wallet's DID if not provided.
path string (default: https://abtwallet.io/i/) — The deep link URL prefix for the wallet.

ChainInfo

This object specifies the blockchain that your application interacts with.

id string (required) — The ID of the chain (e.g., 'beta', 'main'). For EVM chains, this is the Chain ID number.
host string (required) — The GraphQL endpoint for ArcBlock chains, or a JSON-RPC endpoint for EVM chains.
type string (default: arcblock) — The type of blockchain. Can be 'arcblock', 'ethereum', etc.

Now that you understand how to create and manage authentication logic, the next step is to integrate it into a web server. Proceed to the WalletHandlers API Reference to learn how to attach DID Connect endpoints to an Express.js application.