Ver.iD Node.js Client

A powerful TypeScript SDK for integrating Ver.iD decentralized identity authentication and disclosure flows into your Node.js server applications. This package enables server-side OAuth 2.1 flows with secure client authentication using client secrets.

Getting Started

Installation

Using npm in your project directory run the following command:

npm install @ver-id/node-client

Using yarn in your project directory run the following command:

yarn add @ver-id/node-client

Using pnpm in your project directory run the following command:

pnpm add @ver-id/node-client

Authentication

Decentralized identity apps redefine the authentication experience, shifting from traditional, password-based methods to a secure, password-less system utilizing QR codes. This modern approach enhances security, simplifies the login process, and significantly improves user experience by leveraging user-controlled, decentralized authentication.

You can quickly create an authentication flow using Ver.iD Studio and execute the flow using authentication client:

import { VeridAuthenticationClient } from '@ver-id/node-client';

// Create authentication client
const authenticationClient = new VeridAuthenticationClient({
  issuerUri: '<VERID_OAUTH_ISSUER_URI>', // Ver.iD OAuth Issuer URI
  client_id: '<VERID_AUTHENTICATION_FLOW_ID>', // Authentication flow id registered in Ver.iD Studio
  redirectUri: 'REGISTERED_REDIRECT_URI', // One of the registered redirect uri in the flow
});

// Generate authentication url
const { authenticationUrl, state } =
  await authenticationClient.generateAuthenticationUrl({
    scope: '<SCOPES_TO_REQUEST>',
  });

// Redirect the user to the Ver.iD authentication flow (or return URL to frontend)
// After user completes authentication, Ver.iD redirects to your redirectUri with code and state

// Finalize the flow to exchange authorization code for tokens
const authenticationResponse = await authenticationClient.finalize({
  clientAuth: {
    client_secret: '<YOUR_CLIENT_SECRET>', // Client secret from Ver.iD Studio
  },
  callbackParams: callbackUrl, // The complete callback URL with code and state
});

// Decode the ID token
const authenticationDecodedToken = await authenticationClient.decode(
  authenticationResponse
);

Note: Unlike browser clients, the Node.js client requires explicit clientAuth with a client_secret during the finalize step. This enables secure server-side authentication flows where the client secret is never exposed to the frontend.

For other comprehensive configurations and examples, see the AUTHENTICATION.md document.

Verification

Decentralized identity apps transform Know-Your-Customer (KYC) and Know-Your-Business (KYB) procedures used by large online platforms to verify their platform users or companies, effectively replacing tedious manual document verification with a swift, secure exchange of verified digital credentials. This process leverages decentralized identity apps that not only provide essential credentials like passports and ID cards but also enable direct integration with governmental identity databases globally. With regulations such as eIDAS 2.0 and DMA on the horizon, our solution is poised to meet official credential requirements, offering a future-proof method for identity verification.

You can quickly create a disclosure flow using Ver.iD Studio and execute the flow using disclosure client:

import { VeridDisclosureClient } from '@ver-id/node-client';

// Create disclosure client
const disclosureClient = new VeridDisclosureClient({
  issuerUri: '<VERID_OAUTH_ISSUER_URI>', // Ver.iD OAuth Issuer URI
  client_id: '<VERID_DISCLOSURE_FLOW_ID>', // Disclosure flow id registered in Ver.iD Studio
  redirectUri: 'REGISTERED_REDIRECT_URI', // One of the registered redirect uri in the flow
});

// Generate disclosure url
const { disclosureUrl, state } = await disclosureClient.generateDisclosureUrl();

// Redirect the user to the Ver.iD disclosure flow (or return URL to frontend)
// After user completes disclosure, Ver.iD redirects to your redirectUri with code and state

// Finalize the flow to exchange authorization code for tokens
const disclosureResponse = await disclosureClient.finalize({
  clientAuth: {
    client_secret: '<YOUR_CLIENT_SECRET>', // Client secret from Ver.iD Studio
  },
  callbackParams: callbackUrl, // The complete callback URL with code and state
});

// Decode the token
const disclosureDecodedToken = await disclosureClient.decode(
  disclosureResponse
);

Note: Unlike browser clients, the Node.js client requires explicit clientAuth with a client_secret during the finalize step. This enables secure server-side disclosure flows where the client secret is never exposed to the frontend.

For other comprehensive configurations and examples, see the VERIFICATION.md document.

Issuance

Issuance flows enable you to issue verified credentials to users that they can store in their decentralized identity wallets. This allows users to prove attributes about themselves without repeatedly going through verification processes. Issued credentials can include digital IDs, certificates, licenses, or any verified information.

You can quickly create an issuance flow using Ver.iD Studio and execute the flow using issuance client:

import { VeridIssuanceClient } from '@ver-id/node-client';

// Create issuance client
const issuanceClient = new VeridIssuanceClient({
  issuerUri: '<VERID_OAUTH_ISSUER_URI>', // Ver.iD OAuth Issuer URI
  client_id: '<VERID_ISSUANCE_FLOW_ID>', // Issuance flow id registered in Ver.iD Studio
  redirectUri: 'REGISTERED_REDIRECT_URI', // One of the registered redirect uri in the flow
});

// Step 1: Generate code challenge
const { codeChallenge, state } = await issuanceClient.generateCodeChallenge();

// Step 2: Create issuance intent (required for issuance flows)
// Only pass either payload.mapping or payload.data
const intentId = await issuanceClient.createIssuanceIntent(
  {
    payload: {
      mapping: { name: 'fullName', email: 'emailAddress' },
      data: {
        attributeUuid: '<ATTRIBUTE_UUID>',
        value: 'John Doe',
      },
    },
  },
  codeChallenge,
  { client_secret: '<YOUR_CLIENT_SECRET>' } // Client authentication required for Node.js
);

// Step 3: Generate issuance url with intent
const { issuanceUrl, state: finalState } =
  await issuanceClient.generateIssuanceUrl({
    intent_id: intentId,
    state, // Use the state from Step 1
    codeChallenge, // Use the code challenge from Step 1
  });

// Redirect the user to the Ver.iD issuance flow (or return URL to frontend)
// After user completes issuance, Ver.iD redirects to your redirectUri with code and state

// Finalize the flow to exchange authorization code for tokens
const issuanceResponse = await issuanceClient.finalize({
  clientAuth: {
    client_secret: '<YOUR_CLIENT_SECRET>', // Client secret from Ver.iD Studio
  },
  callbackParams: callbackUrl, // The complete callback URL with code and state
});

// Decode the token
const issuanceDecodedToken = await issuanceClient.decode(issuanceResponse);

Note: Unlike authentication and disclosure, issuance flows require intent creation with a credential payload before generating the issuance URL. The Node.js client requires clientAuth with a client_secret for both intent creation and the finalize step for secure server-side flows.

For other comprehensive configurations and examples, see the ISSUANCE.md document.

Examples

See the apps/sample-node-server directory for a complete Express.js server implementation demonstrating authentication and verification flows.

Cache Stores

All SDK flow clients use a cache manager to persist temporary OAuth state (PKCE verifiers, nonces). By default, FileStorageCacheManager is used. You can swap it for any built-in store — or provide your own ICacheManager implementation.

File Storage (default)

Persists cache to a JSON file on disk. Suitable for single-process servers and local development.

import { FileStorageCacheManager } from '@ver-id/node-client';

// Uses default directory: ~/.verid-cache/cache.json
const cacheManager = new FileStorageCacheManager();

// Or specify a custom directory
const cacheManager = new FileStorageCacheManager('/tmp/my-app-cache');

Memory Storage

In-memory Map-based store. Fastest option but data is lost on process restart and not shared across instances.

import { MemoryStorageCacheManager } from '@ver-id/node-client';

const cacheManager = new MemoryStorageCacheManager();

Redis

Shared cache for distributed / multi-instance deployments. Works with both redis (node-redis) and ioredis.

Install one of the Redis client libraries:

yarn add redis
# or
yarn add ioredis

Using redis (node-redis):

import { createClient } from 'redis';
import { RedisCacheManager } from '@ver-id/node-client';

const redisClient = createClient({ url: 'redis://localhost:6379' });
await redisClient.connect();

const cacheManager = new RedisCacheManager({
  client: redisClient,
  options: {
    prefix: 'myapp:', // optional, default: 'verid:'
    ttlSeconds: 600, // optional, auto-expire after 10 minutes
  },
});

Using ioredis:

import Redis from 'ioredis';
import { RedisCacheManager } from '@ver-id/node-client';

const redisClient = new Redis();

const cacheManager = new RedisCacheManager({ client: redisClient });

AWS DynamoDB

Serverless cache for AWS-native environments. Ideal for Lambda deployments where Redis isn't available.

Install the AWS SDK packages:

yarn add @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb

DynamoDB table requirements:

• Partition key: pk (String)
• Optional TTL attribute: ttl (Number) — enable DynamoDB TTL on this attribute

import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
import { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';
import { DynamoDBCacheManager } from '@ver-id/node-client';

const dynamoClient = DynamoDBDocumentClient.from(
  new DynamoDBClient({ region: 'us-east-1' })
);

const cacheManager = new DynamoDBCacheManager({
  client: dynamoClient,
  tableName: 'verid-cache',
  options: {
    prefix: 'myapp:', // optional, default: 'verid:'
    ttlSeconds: 600, // optional, requires DynamoDB TTL enabled on `ttl` attribute
  },
});

Using a cache store with any flow client

Pass the cache manager via the options.cacheManager property:

const authClient = new VeridAuthenticationClient({
  issuerUri: '<VERID_OAUTH_ISSUER_URI>',
  client_id: '<VERID_AUTHENTICATION_FLOW_ID>',
  redirectUri: 'REGISTERED_REDIRECT_URI',
  options: {
    cacheManager: new RedisCacheManager({ client: redisClient }),
  },
});

This works identically for VeridDisclosureClient and VeridIssuanceClient.

Troubleshooting

| Problem | Fix | | --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | ENOENT: no such file or directory, open '...cache.json' | The default FileStorageCacheManager writes to ~/.verid-cache/. Ensure the process has write permission, or switch to MemoryStorageCacheManager. | | State mismatch on finalize | The callbackParams URL must contain the same state parameter that was generated. Ensure you're forwarding the full callback URL. | | OperationFailedError: Failed to discover issuer | Verify issuerUri is correct and reachable from the server. | | TokenGrantError during finalize | Double-check client_secret and ensure the redirect URI matches exactly. | | Redis / DynamoDB connection errors | Ensure the cache client is connected before passing it to the cache manager constructor. |

Acknowledgments

• Built with TypeScript
• Powered by oauth4webapi
• Uses jose for JWT handling

License

MIT