@sirosfoundation/dc-api

W3C Digital Credentials API toolkit 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
• Protocol polyfill — shim OpenID4VP support in browsers lacking native protocol handling
• Web wallet support — enable web wallets to self-register without a browser extension

Modules

Import path	Description
@sirosfoundation/dc-api	Core: constants, detection, native invocation, errors
@sirosfoundation/dc-api/polyfill	Protocol polyfill: shims navigator.credentials.get() for OpenID4VP
@sirosfoundation/dc-api/web-wallets	Web wallet self-registration API (window.DigitalWallets)
@sirosfoundation/dc-api/bundle	Pre-built ESM bundle of core (for importmaps)
@sirosfoundation/dc-api/polyfill/bundle	Pre-built ESM bundle of polyfill
@sirosfoundation/dc-api/web-wallets/bundle	Pre-built ESM bundle of web-wallets

Install

npm install @sirosfoundation/dc-api

Usage

Core: Requesting credentials natively

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

const protocol = getBestProtocol(); // "openid4vp-v1-signed" (preferred)

if (protocol) {
  try {
    const result = await requestCredential(protocol, {
      request: signedJWT, // JAR for "openid4vp-v1-signed"
    });
    await submitToBackend(result.data);
  } catch (err) {
    if (isUserCancel(err)) {
      showAlternativeFlow();
    } else {
      throw err;
    }
  }
} else {
  showQRCode(); // No DC API support
}

Polyfill: OpenID4VP on browsers without native support

import { installPolyfill } from '@sirosfoundation/dc-api/polyfill';

// Shims navigator.credentials.get() for openid4vp-v1-signed
installPolyfill();

After installPolyfill(), the standard DC API surface works even when the browser lacks native OpenID4VP protocol support. The polyfill:

1. Delegates to native if the browser supports the requested protocol
2. Otherwise opens a registered wallet in a popup and relays the request via postMessage

Wallets are registered separately — either by the verifier (see below) or via enableWebWallets() for self-registration.

Web Wallets: Self-registration without an extension

import { installPolyfill } from '@sirosfoundation/dc-api/polyfill';
import { enableWebWallets } from '@sirosfoundation/dc-api/web-wallets';

installPolyfill();
enableWebWallets();

// Web wallets can now self-register:
window.DigitalWallets.register({
  id: 'my-wallet',
  name: 'My Wallet',
  url: 'https://wallet.example.com/dc-api',
  protocols: ['openid4vp-v1-signed'],
  icon: 'https://wallet.example.com/icon.svg',
});

If the wallet-companion browser extension is already installed, enableWebWallets() is a no-op.

API Reference

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

Detection

Function	Description
isDCAPIAvailable()	true when DigitalCredential is defined
isProtocolAllowed(protocol)	Delegates to DigitalCredential.userAgentAllowsProtocol()
getBestProtocol(preference?)	First allowed protocol (default: signed > multisigned > unsigned)

Request

Function	Description
requestCredential(protocol, data, options?)	Native DC API call, returns { protocol, data }

Error Helpers

Function	Description
getUserFriendlyErrorMessage(error)	Human-readable message for DC API errors
isUserCancel(error)	true for NotAllowedError / AbortError
isProtocolUnsupported(error)	true for NotSupportedError

Polyfill

Function	Description
installPolyfill(options?)	Override navigator.credentials.get() for OpenID4VP
uninstallPolyfill()	Restore original behavior
registerWallet(wallet)	Register a wallet endpoint
unregisterWallet(id)	Remove a registered wallet
getRegisteredWallets()	List registered wallets

Web Wallets

Function	Description
enableWebWallets(options?)	Expose window.DigitalWallets API
disableWebWallets()	Remove the API
selectWallet(wallets, protocol)	Show wallet selector (built-in or custom)

Design Principles

• Zero dependencies — no runtime dependencies
• Backend-agnostic — no knowledge of specific verifier or wallet endpoints
• Spec-aligned — uses the W3C DC API spec's detection and invocation patterns
• Progressive — core works standalone; polyfill and web-wallets are opt-in layers
• Extension-compatible — no-ops when wallet-companion handles the flow

Related

• wallet-companion — browser extension for DC API + web wallet routing
• WE BUILD CS-007 — conformance specification for DC API presentation

References

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

License

BSD-2-Clause