Proof Digital Credentials

A digital passport. Verified once, usable everywhere.

Read our documentation or try it!

Table of Contents

• Packages
• Installation
• Getting Started
  • Client Side
  • Response Modes
• Verifiable Credential Presentation
  • Credential Type
  • Request
    • Scopes
• Documentation
• Contributing

Packages

| Package | Runtime | Usage | Runtime deps | | ------------------------------------------------------------------------------------------------------ | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ----------------- | | @proof.com/proof-vc-common | browser or Node | Request a Verifiable Presentation | 0 ✅ | | @proof.com/proof-vc-server | Node | proof-vc-common plus Presentation Verification, Secured Authorization Requests, Transaction Templates and Verifier Enrollment | sd-jwt, owf, jose |

Installation

Browser / Node:

npm install @proof.com/proof-vc-common

Node:

npm install @proof.com/proof-vc-server

Proof implements the OpenID for Verifiable Presentations 1.0 specification. Setup an OAuth Application in your Proof account to get your client_id.

Getting Started

Client Side

You can request a Verifiable Presentation in the browser by using createClient and authorizationUrl to craft an Authorization Request URL. Either fragment or direct_post Response Mode are supported (defaults to fragment).

• if using fragment, at the callback URI, use parseAuthorizationResponse to extract the vp_token from it and send it to your verification endpoint
• if using direct_post, the vp_token is sent directly to your verification endpoint

import {
  createClient,
  parseAuthorizationResponse,
} from "@proof.com/proof-vc-common";

const proof = createClient({
  environment: "sandbox",
  clientId: "verifier-demo",
  callbackUri: "https://example.com/callback",
});

button.onclick = () => {
  window.location.href = proof.authorizationUrl({
    nonce: "3e8e4918-e9fb-453a-a538-81152be15c1b",
    scope: "urn:proof:params:scope:verifiable-credentials:basic",
  });
};

// at https://example.com/callback
const response = parseAuthorizationResponse(); // reads window.location.hash
if (response?.type === "success") {
  fetch("/verify_vp_token", {
    method: "POST",
    body: new URLSearchParams({ vp_token: response.vpToken }),
  });
} else if (response?.type === "error") {
  console.error(response.error, response.errorDescription);
}

parseAuthorizationResponse returns { type: "success", vpToken, state? }, { type: "error", error, errorDescription?, errorUri?, state? } when the authorization server answered with an OAuth 2.0 error response, or null when neither is present.

You can also use buildAuthorizationUrl to provide all the Authorization Request parameters at once:

import { buildAuthorizationUrl } from "@proof.com/proof-vc-common";

window.location.href = buildAuthorizationUrl({
  environment: "sandbox",
  clientId: "verifier-demo",
  callbackUri: "https://example.com/callback",
  nonce: "3e8e4918-e9fb-453a-a538-81152be15c1b",
  scope: "urn:proof:params:scope:verifiable-credentials:basic",
});

Response Modes

Proof supports fragment and direct_post response modes (default fragment).

fragment

Using fragment the vp_token is returned as a fragment of the callbackUri when the user is 302 redirected from Proof to your website. Use parseAuthorizationResponse() in the browser to read it.

GET https://example.com/verify_vp_token#vp_token=eyJwcm9vZl9pZF9...

direct_post

Using direct_post the vp_token and state (optional) are returned in the application/x-www-form-urlencoded body of a POST request to the callbackUri from Proof to your server. Pass the vp_token value as received to verifyVPToken. See the OID4VP specification for more details.

POST https://example.com/verify_vp_token
Content-Type: application/x-www-form-urlencoded

vp_token=eyJwcm9vZl9pZF9...&state=6A2B4CD830

Verifiable Credential Presentation

Credential Type

Proof issues Verifiable Credentials according to the SD-JWT-VC specification and publishes its OID4VCI Credential Issuer Metadata at https://api.proof.com/.well-known/openid-credential-issuer.

ProofCredentialV1

| claim | accessor | type | description | | -------------------- | -------------- | ------- | ------------------------------------------------------------------ | | given_name | givenName | string | user's given name as it appears on the verified identity document | | family_name | familyName | string | user's family name as it appears on the verified identity document | | birth_date | birthDate | string | user's date of birth in ISO 8601 format (YYYY-MM-DD) | | age_equal_or_over.18 | isOver18 | boolean | boolean confirming the user is 18 or older | | age_equal_or_over.21 | isOver21 | boolean | boolean confirming the user is 21 or older | | age_equal_or_over.65 | isOver65 | boolean | boolean confirming the user is 65 or older | | is_national.us | isNationalUS | boolean | boolean confirming US nationality (nationality:us scope) |

All attributes are selectively disclosable and will return undefined if the claim wasn't disclosed. getClaims() returns the disclosed claims as issued and toJSON() the accessors above. A credential with a vct unknown to this SDK is returned as a DefaultProofCredential with a one-time ProofVCWarning.

Request

Request a Verifiable Credential Presentation with an OAuth 2.0 Authorization Request. See Client Side and Server Side above for the two entry points. Exactly one of scope or dcqlQuery must be given.

Scopes

Proof supports the scope parameter of the OID4VP specification. Each scope maps to a pre-defined DCQL query and returns a specific Credential Type.

Supported scope and their associated Credential Type:

| scope | Credential Type | claims | Key Binding JWT | | -------------------------------------------------------------- | ------------------- | --------------------------------------------------- | --------------- | | urn:proof:params:scope:verifiable-credentials:basic | ProofCredentialV1 | given_name, family_name, age_equal_or_over.18 | yes | | urn:proof:params:scope:verifiable-credentials:nationality:us | ProofCredentialV1 | age_equal_or_over.18, is_national.us | yes |

A scope unknown to this SDK is accepted and emits a one-time ProofVCWarning.

Documentation

Digital Credentials guides https://dev.proof.com/docs/digital-credentials-overview
API Documentation https://dev.proof.com/reference/authorizeverifiablecredentialpresentation

Contributing

Contribution guidelines for this project