Javascript SDK For Verifiable Credentials

At the moment, this library only contains a function to interact with an Identity Provider to get a credential presentation for a user.

The flow to request a credential is performed through a browser.

Installation

Install library

npm install @dfinity/verifiable-credentials

The bundle needs peer dependencies, be sure that following resources are available in your project as well.

npm install @dfinity/principal

Import per modules:

// import * from '@dfinity/verifiable-credentials'; // Error: use sub-imports, to ensure small app size
import { requestVerifiablePresentation } from "@dfinity/verifiable-credentials/request-verifiable-presentation";

Relying Party: Request Credentials

Use the function requestVerifiablePresentation to request credentials from an issuer.

Summary

The function performs the following steps:

• Open a new window or tab with the Identity Provider.
• Wait for a window post message from the Identity Provider.
• Send a request to the Identity Provider through the window post message.
• Wait for the response from the Identity Provider.
• Call onSuccess callback when the flow was successful. Not necessarily that the credential was received.
• Call onError callback when the flow has some technical error or the user closes the window.

More info in the Internet Identity Specification for Verifiable Credentials.

Usage

To start a flow, call the function with the expected parameters:

requestVerifiablePresentation({
  onSuccess: async (verifiablePresentation: VerifiablePresentationResponse) => {
    // Called when the flow finishes successfully.
  },
  onError() {
    // Called when there is a technical error.
  },
  issuerData: {
    origin: "<url of the origin>",
    canisterId: "<canister id>",
  },
  credentialData: {
    credentialSpec: {
      credentialType: '<credential type as expected by issuer>',
      arguments: {
        // Arguments to verify with the credential
      },
    },
    credentialSubject: "<user's principal>",
  },
  identityProvider: "<url identity provider>",
  derivationOrigin: "<[optional] origin for delegated identity>",
  windowOpenerFeatures: "<[optional] window opener config string>",
});

Paremeters

List of properties expected in the parameter when calling the function:

• onSuccess: Function that will be called when the flow finishes. Not necessarily with the credential. This is also called if the user doesn't have the credential.
• onError: Function that will be called when the flow failes due to a technical error. Also when the user interrupts the flow.
• issuerData: Object with the origin and canisterId of the issuer.
• credentialData: Object with the subbject and the credential requested.
• identityProvider: URL of the Identity Provider. Ex: new URL("https://identity.ic0.app/").
• derivationOrigin: Indicates an origin that should be used for principal derivation. It's the same value as the one used when logging in. More info.
• windowOpenerFeatures The flow will open a new window or tab. Pass here a configuration string to customize it.

Upcoming

Changes in the upcoming versions.

Breaking Changes

Improvements

release-2024-10-29

Breaking Changes

• New field derivationOrigin is required to match in the ID Alias credential in ic-verifiable-credentials.

Improvements

• Point identity.rs dependencies to crates.io instead of the repository.

release-2024-09-10

Breaking Changes

Improvements

• Update dependency versions.
• Fix importing js-library in Webpack projects.

release-2024-07-01

New projects

• Add ic-verifiable-credentials crate to the repository.

Improvements

• Add the credential arguments to the consent message of the dummy issuer.
• Add canister id input in the dummy relying party.
• Upgrade @dfinity/verifiable-credentials used in the dummy relying party to the latest published version.
• Port vc-util from II to this repository and rename it to ic-verifiable-credentials.
• Do not publish to NPM the JS library if there were no changes.
• Publish the dummy issuer and dummy relying party wasm modules and interface files as release artifacts so that they can be easily pulled into other projects.

2024.06.10

New projects

• Dummy relying party.
• Dummy issuer.

Breaking Changes

• Change the type of CredentialData.credentialSubject to Principal.
• Change the type of IssuerData.canisterId to Principal and make it mandatory.
• Change the type of identityProvider to URL.

Non-breaking Changes

• derivationOrigin field is now optional.

Installation

• List @dfinity/principal as a peer dependency.

2024.05.03

Release of the NPM library @dfinity/verifiable-credentials.

At the moment, this library only contains a function to interact with an Identity Provider to get a credential presentation for a user.