@sirosfoundation/dc-api

W3C Digital Credentials API utilities for OpenID4VP.

Zero-dependency, backend-agnostic library providing:

• Protocol constants — versioned OpenID4VP protocol identifiers per the W3C DC API spec
• Feature detection — check DC API availability and protocol support
• Native DC API invocation — call navigator.credentials.get() with proper parameters
• Error helpers — classify errors and generate user-friendly messages

Install

npm install @sirosfoundation/dc-api

A pre-built ESM bundle is also available at dist/dc-api.bundle.js for use in importmaps or environments without a bundler.

Usage

Requesting credentials

import {
  isDCAPIAvailable,
  getBestProtocol,
  requestCredential,
  isUserCancel,
} from '@sirosfoundation/dc-api';

// 1. Check if DC API + openid4vp is available
const protocol = getBestProtocol();

if (protocol) {
  try {
    // 2. Call the native DC API
    const result = await requestCredential(protocol, {
      request: signedJWT, // JAR for "openid4vp-v1-signed"
    });

    // 3. Submit result.data to your backend
    await submitToBackend(result.data);
  } catch (err) {
    if (isUserCancel(err)) {
      // User cancelled — show alternative flow
    } else {
      throw err;
    }
  }
} else {
  // No DC API support — use QR code / redirect fallback
  showQRCode();
}

Protocol constants

import { OID4VP_PROTOCOLS, isOID4VPProtocol } from '@sirosfoundation/dc-api';

// Use shared constants instead of hardcoding protocol strings
const supportedProtocols = [
  OID4VP_PROTOCOLS.UNSIGNED,
  OID4VP_PROTOCOLS.SIGNED,
  OID4VP_PROTOCOLS.MULTISIGNED,
];

// Type guard for filtering
const known = requests.filter(r => isOID4VPProtocol(r.protocol));

API

Protocol Constants

OID4VP_PROTOCOLS.UNSIGNED     // "openid4vp-v1-unsigned"
OID4VP_PROTOCOLS.SIGNED       // "openid4vp-v1-signed"
OID4VP_PROTOCOLS.MULTISIGNED  // "openid4vp-v1-multisigned"
OID4VP_PROTOCOLS.LEGACY       // "openid4vp"

OID4VP_SPEC_PROTOCOLS         // [UNSIGNED, SIGNED, MULTISIGNED]
OID4VP_ALL_PROTOCOLS          // [UNSIGNED, SIGNED, MULTISIGNED, LEGACY]
isOID4VPProtocol(value)       // Type guard — true for any known protocol

Detection

Function	Description
isDCAPIAvailable()	true when typeof DigitalCredential !== "undefined"
isProtocolAllowed(protocol)	Delegates to DigitalCredential.userAgentAllowsProtocol()
getBestProtocol(preference?)	Returns the first allowed protocol from a preference-ordered list (default: signed > multisigned > unsigned)

Request

Function	Description
requestCredential(protocol, data, options?)	Calls navigator.credentials.get({digital: {requests: [{protocol, data}]}}), returns { protocol, data }

options.signal accepts an AbortSignal for cancellation.

Error Helpers

Function	Description
getUserFriendlyErrorMessage(error)	Returns a human-readable message for DC API errors
isUserCancel(error)	true for NotAllowedError or AbortError
isProtocolUnsupported(error)	true for NotSupportedError
ERROR_MESSAGES	Map of DOMException names to user-facing strings

Design Principles

• Zero dependencies — no runtime dependencies
• Backend-agnostic — no knowledge of specific verifier or wallet endpoints
• Transport-agnostic — no QR codes, redirects, or SSE; those belong in the consumer
• Spec-aligned — uses the W3C DC API spec's detection and invocation patterns exactly

References

• W3C Digital Credentials API
• OpenID4VP (DC API profile)

License

BSD-2-Clause