@ewqwe/digital-identity

npm-compatible JavaScript/TypeScript library for EU Digital Identity (OpenID4VP, DCQL, mDoc, SD-JWT VC).

Part of the ewQwe TypeScript workspace. When used inside the workspace the library is resolved via pnpm's workspace:* protocol. Published to npm for external consumers.

Installation

As an npm dependency (external consumer)

npm install @ewqwe/digital-identity

Inside the pnpm workspace

# From typescript/ root — build the library
pnpm --filter @ewqwe/digital-identity build

The library is linked into consumers via workspace:* in the workspace root.

Usage

CommonJS

const { buildAgeVerificationQuery, generateNonce } = require('@ewqwe/digital-identity');

const query = buildAgeVerificationQuery(18);
const nonce = generateNonce();

ES Modules

import { buildAgeVerificationQuery, generateNonce } from '@ewqwe/digital-identity';

const query = buildAgeVerificationQuery(18);
const nonce = generateNonce();

Features

• DCQL Query Builders: Build Digital Credentials Query Language queries for OpenID4VP.
• Credential Types: Pre-configured credential types (mDL, PID, Proof of Age, etc.) with associated claims.
• Protocol Profiles: HAIP and Annex A profile support.
• Attestation Verification: JWT signature verification using the Web Crypto API in browsers and Node.js.
• Type Definitions: Full TypeScript support with comprehensive type safety.

Quick Start

Generate an age verification query

import { buildAgeVerificationQuery } from '@ewqwe/digital-identity';

// Generate query for age 18+
const query = buildAgeVerificationQuery(18);
console.log(JSON.stringify(query, null, 2));

// Generate query for age 21+
const query21 = buildAgeVerificationQuery(21);

Build an Init Transaction Request

import { buildInitTransactionRequest } from '@ewqwe/digital-identity';

const request = buildInitTransactionRequest(
  'https://example.com',
  'mdl',
  ['given_name', 'family_name', 'birth_date']
);

Generate a Cryptographic Nonce

import { generateNonce } from '@ewqwe/digital-identity';

const nonce = generateNonce();
// Returns a base64url-encoded 32-byte random value

Validate a DCQL Query

import { isValidDCQLQuery, buildAgeVerificationQuery } from '@ewqwe/digital-identity';

const query = buildAgeVerificationQuery(18);
const validation = isValidDCQLQuery(query);

if (validation.valid) {
  console.log('Valid DCQL query');
} else {
  console.error('Invalid:', validation.error);
}

API Reference

DCQL Query Functions

| Function | Description | |----------|-------------| | buildAgeVerificationQuery(ageThreshold) | Build minimal age verification query | | buildAgeVerificationQueryWithFallback(ageThreshold) | Build query with mDL fallback | | buildInitTransactionRequest(publicUrl, credentialType, claims) | Build init transaction request | | getDefaultAgeVerificationDCQL() | Get default age verification query | | determineProfile(credentialType, explicitProfile) | Determine protocol profile | | generateNonce() | Generate cryptographic nonce | | isValidDCQLQuery(query) | Validate DCQL query structure | | parseDCQLQuery(queryString) | Parse DCQL from JSON string | | extractAgeThreshold(query) | Extract age threshold from query |

Credential Types

import { CREDENTIAL_TYPES, getClaimsForType } from '@ewqwe/digital-identity';

// Get all credential types
const types = Object.keys(CREDENTIAL_TYPES);

// Get claims for a specific type
const mdlClaims = getClaimsForType('mdl');

Protocol Profiles

import { PROTOCOL_PROFILES, determineProfile } from '@ewqwe/digital-identity';

// Get HAIP profile
const haip = PROTOCOL_PROFILES.haip;

// Determine profile for credential type
const profile = determineProfile('mdl'); // 'haip'

Attestation Verification

import { parseAttestation, verifyAttestation } from '@ewqwe/digital-identity';

// Parse and verify attestation from backend response
const attestation = await parseAttestation(jwtToken, '/ewqwe_api/jwks');

// Or verify with pre-imported public key
const publicKey = await importVerifierPublicKey(pemOrSpki);
const claims = await verifyAttestation(jwtToken, publicKey);

API Client

@ewqwe/digital-identity exports EwqweApiClient for server-side and browser client code, with a pluggable fetch implementation.

import { EwqweApiClient } from '@ewqwe/digital-identity';

const apiClient = new EwqweApiClient({
  baseUrl: 'https://localhost:5175',
  fetch: window.fetch,
});

const tx = await apiClient.initOpenID4VPTransaction({
  public_url: 'https://localhost:5174',
  credential_type: 'proof-of-age',
});

const status = await apiClient.getOpenID4VPTransactionStatus(tx.transaction_id);
const verify = await apiClient.verifyPresentation({
  vp_token: '<vp_token>',
  presentation_submission: null,
});

API client methods

• initOpenID4VPTransaction(request: InitTransactionRequest): Promise<InitTransactionResponse>
• getOpenID4VPTransactionStatus(transactionId: string): Promise<TransactionStatusResult>
• getOpenID4VPAuthorizationRequest(transactionId: string): Promise<OpenID4VPRequest>
• postOpenID4VPAuthorizationRequest(transactionId: string, response: OpenID4VPResponse): Promise<void>
• postOpenID4VPDirectPost(response: OpenID4VPResponse): Promise<void>
• getOpenID4VPJwks(): Promise<{ keys: unknown[] }>
• verifyPresentation(args): Promise<VerifyResponse>

License

MIT