OID4Client Library (@digitalbazaar/oid4-client)

A JavaScript library for working with the OpenID 4 Verifiable Credential Issuance (OID4VCI) protocol, offering functionality for requesting Verifiable Credentials.

Table of Contents

• Background
• Install
• Usage
• Testing
• Contribute
• Commercial Support
• License

Background

This library is a JavaScript (Node.js and browser) implementation of the OID4VCI v11 Protocol.

It allows you to perform the following operations:

1. Request a credential to be issued given a OID4VCI credential offer.
2. Request multiple credentials to be issued given a OID4VCI credential offer.
3. Authenticate using a DID if the offer requires it.

Install

npm install @digitalbazaar/oid4-client

Usage

Importing the Library

import { OID4Client } from "@digitalbazaar/oid4-client";

Creating a Client from a Credential Offer

const clientFromOffer = await OID4Client.fromCredentialOffer({
  offer: "YOUR_CREDENTIAL_OFFER",
});

Constructor

You can also instantiate the OID4Client directly using the following parameters:

• accessToken (Optional)
• issuerConfig
• metadata
• offer

Example:

const client = new OID4Client({
  accessToken: "YOUR_ACCESS_TOKEN",
  issuerConfig: "YOUR_ISSUER_CONFIG",
  metadata: "YOUR_METADATA",
  offer: "YOUR_OFFER",
});

Requesting a Credential

To request a single credential using the credential offer:

const credential = await client.requestCredential({
  did: "YOUR_DID",
  didProofSigner: "YOUR_DID_PROOF_SIGNER",
});

To request multiple credentials using the credential offer:

const credentials = await client.requestCredentials({
  did: "YOUR_DID",
  didProofSigner: "YOUR_DID_PROOF_SIGNER",
});

Requesting a Credential By Definition

To request a single credential using a specific credential definition:

const credential = await client.requestCredential({
  credentialDefinition: "YOUR_CREDENTIAL_DEFINITION",
  did: "YOUR_DID",
  didProofSigner: "YOUR_DID_PROOF_SIGNER",
});

To request multiple credentials using credential definition requests:

const credentials = await client.requestCredentials({
  requests: "YOUR_REQUESTS",
  did: "YOUR_DID",
  didProofSigner: "YOUR_DID_PROOF_SIGNER",
});

Testing

To run tests:

npm run test

Contribute

See the contribute file!

PRs accepted.

Note: If editing the Readme, please conform to the standard-readme specification.

Commercial Support

Commercial support for this library is available upon request from Digital Bazaar: support@digitalbazaar.com

License

New BSD License (3-clause) © Digital Bazaar

@digitalbazaar/oid4-client Changelog

4.3.0 - 2024-11-10

Added

• Add getNonce to client API for use with OID4VCI nonce_endpoint.
• Add option to pass nonce to requestCredential(s).

4.2.0 - 2024-10-15

Changed

• Update dependencies.

4.1.0 - 2024-10-01

Added

• Auto-detect whether to include vc in the JSON paths when computing presentation definition constraints from a VPR.

Fixed

• Ensure duplicate paths aren't used when generating a VPR from a presentation definition.

4.0.0 - 2024-09-20

Changed

• BREAKING: Use allOf instead of an invalid contains with an array value when generating presentation filters from a VPR.

3.8.0 - 2024-09-20

Added

• Accept allOf in combination with contains for array schemas.

3.7.0 - 2024-08-22

Added

• Add support for fetching credential offer from credential_offer_uri via getCredentialOffer().
• Improve automatic credential definition selection from a credential offer based on the specified format.

3.6.0 - 2024-08-22

Added

• Add support for issuer configuration URLs that do not match RFC 8414, but instead match the OID4VCI spec, i.e., <issuer>/.well-known/... will be accepted and not just <issuer origin>/.well-known/.../<issuer path>.
• Add support for parsing and using credential offers with credentials or credential_configuration_ids that include credential configuration IDs that are present in the issuer configuration.

3.5.0 - 2024-08-08

Added

• Allow vpToken param to be given when sending an authorization response. This param is optional and does not replace the verifiablePresentation parameter which is required to build the presentation submission. The vpToken param can be used if the format of the vp_token is not the plain JSON expression of the verifiablePresentation, but is instead some enveloping format that wraps the VP, such as a JWT (as in VC-JWT).

3.4.1 - 2024-07-29

Fixed

• Ensure presentation_required error is properly nested.

3.4.0 - 2024-07-15

Added

• Allow format to be passed when requesting credentials.

Changed

• Allow any format to be used in credential requests.

3.3.0 - 2024-01-24

Changed

• Update @digitalbazaar/http-client to 4.0.0.

3.2.0 - 2023-11-30

Changed

• Add prefixJwtVcPath option to add an additional JSON path that includes the JWT W3C VC 1.1 'vc' prefix to presentation definition constraints fields.

3.1.0 - 2023-10-25

Added

• Add basic OID4VP support. There are many differences in OID4VP implementations in the ecosystem today and OID4VP is still in draft form. This implementation supports a profile of draft 20 that uses LDP / Data Integrity secured VCs and provides utility functions for converting a subset of VPRs to authorization requests and vice versa. This OID4VP implementation should be considered experimental as the ecosystem matures and changes are made.

3.0.1 - 2023-08-09

Fixed

• Ensure authorization server metadata is retrieved along with credential issuer metadata. This information is combined to create the issuerConfig stored in the client. The client also stores metadata with the original metadata from each to allow differentiation as needed. A future version may remove issuerConfig to avoid any conflation that was the result of previous versions of the OID4VCI spec and implementations built off of this client.

3.0.0 - 2023-08-09

Changed

• BREAKING: The client now uses .well-known/openid-credential-issuer instead of .well-known/oauth-authorization-server to match the current version of the OID4VCI spec as of this date.

2.0.0 - 2023-06-01

Added

• Initial release, see individual commits for history. Notably, no version 1.x was released under this name, instead it was released as @digitalbazaar/oidc4vci-client.