WebCredential

CHAPI provides a single derived class, the WebCredential that forms the basis for any sort of credential data that is provided over the Web, i.e., via a "Credential Handler" that a origin has registered in the user's browser when the user visited that origin's website. Note that CHAPI provides an optional recommendedHandlerOrigins feature for any credential storage request to allow a Relying Party (aka issuer) to suggest one or more digital wallets to help the user store the credential. This is particularly helpful if the user has no wallet yet. The listed origins must have a `manifest.json` file with a valid `credential_handler` entry in order to be used by CHAPI.

// optionally include `recommendedHandlerOrigins` so the user can choose an
// applicable wallet if they don't have one yet:
const options = {
  recommendedHandlerOrigins: [
    'https://wallet.example'
  ]
};
const webCredential = new WebCredential('VerifiablePresentation', {
  '@context': 'https://www.w3.org/2018/credentials/v1',
  ...presentation,
  options
});
          

Requesting and Storing Credentials

Using CHAPI, a web application can get() and store() credentials without knowing anything about the user's wallet. This is intentional; for privacy reasons, the client app must not be able to query any information (without user consent) about which wallets or credential handlers a user may have installed (otherwise, fingerprinting and other attacks would be possible).

get()

A web app (a Relying Party or verifier) can request a credential using credentials.get() during a user gesture event, for example when the user pushes a button on a page that requires identity attributes or authentication. Note that CHAPI provides an optional recommendedHandlerOrigins feature for any credential request (not specific or restricted to VPR) to allow a Relying Party (aka verifier) to suggest one or more digital wallets to help the user complete the request. This is particularly helpful if the user has no wallet yet. The listed origins must have a `manifest.json` file with a valid `credential_handler` entry in order to be used by CHAPI.

const credentialQuery = {
  web: {
    VerifiablePresentation: {
      query: {
        type: 'QueryByExample',
        credentialQuery: {
          // an optional reason for requesting this credential that
          // may be shown to a user by their wallet software
          reason: 'We need you to prove your eligibility to work.',
          example: {
            '@context': [
              'https://www.w3.org/2018/credentials/v1',
              'https://w3id.org/citizenship/v1'
            ],
            type: 'PermanentResidentCard'
          }
        }
      },
      // a 128-bit randomly generated value encoded as a string (use a UUID);
      // it will be digitally signed in the authentication proof
      // that will be attached to the VerifiablePresentation response
      challenge: '3182bdea-63d9-11ea-b6de-3b7c1404d57f',
      // the domain that must be digitally signed in the authentication
      // proof that will be attached to the VerifiablePresentation
      // response, identifying the recipient
      domain: 'jobs.example.com'
    },
    // optionally include credential handler origins to recommend to
    // the user if they have no wallet or may want to choose one
    // the RP recommends; this is an optional CHAPI feature, it is not
    // specific to VPR
    recommendedHandlerOrigins: [
      'https://wallet.example'
    ]
  }
};
const webCredential = await navigator.credentials.get(credentialQuery);

if(!webCredential) {
  console.log('no presentation received');
}

// Response:

null // if the user cancels

// or a WebCredential with these attributes/values:
{
  "type": "web",
  "dataType": "VerifiablePresentation",
  "data": {
    // Verifiable Presentation goes here, containing the credentials
    // that the user agreed to share
  }
}

const {data: presentation} = webCredential;
// send `presentation` to server for forwarding to verifier API
          

// requesting DID Authentication that can be performed at the given `interact`
// service endpoint; the endpoint may respond to the DID Authentication
// response with another VPR or a VP with credentials
const credentialQuery = {
  web: {
    VerifiablePresentation: {
      query: {
        "type": "DIDAuthentication",
        "acceptedMethods": [{"method": "example"}]
      },
      challenge: '3182bdea-63d9-11ea-b6de-3b7c1404d57f',
      domain: 'jobs.example.com',
      interact: {
        service: [{
          type: "UnmediatedPresentationService2021",
          serviceEndpoint: "https://example.edu/exchangers/z238348134/exchanges/z872347234"
        }]
      }
    },
    // optionally include credential handler origins to recommend to
    // the user if they have no wallet or may want to choose one
    // the RP recommends; this is an optional CHAPI feature, it is not
    // specific to VPR
    recommendedHandlerOrigins: [
      'https://wallet.example'
    ]
  }
};
const webCredential = await navigator.credentials.get(credentialQuery);

if(!webCredential) {
  console.log('user canceled');
}

// Response:

null // if the user cancels

// or a WebCredential with these attributes/values:
{
  "type": "web",
  // wallet responded to the request out-of-band
  "dataType": "OutOfBand",
  "data": null
}
          

store()

A web app (for example, a credential issuer such as a university or institution) can ask to store a credential during a user gesture event, for example when the user pushes a button to receive a credential.

const result = await navigator.credentials.store(webCredential);
if(!result) {
  console.log('store credential operation canceled');
}

// Response:

null // if the user cancels

// or a WebCredential with these attributes/values:
{
  "type": "web",
  "dataType": "VerifiablePresentation",
  "data": {
    // Verifiable Presentation goes here, optionally containing the
    // credentials that the user agreed to store (can be an empty
    // presentation or `null`, but this does not indicate cancelation)
  }
}
          

Machine to Machine

These APIs do not require browser polyfills and can be used with or without channel authorization schemes such as access tokens provided by OAuth 2.0 Client Credentials.

{
  "query":
    [
      {
        "type": "RequestQueryByExample",
        "credentialQuery":
          [
            {
              "type":
                [
                    "VerifiableCredential",
                    "MillTestReportCertificate",
                ],
              "reason": "Acme Steel Inc. is ready to present certificate of origin for a steel import.",
            },
          ],
      },
    ],
}
            

  {
    "query": [
      {
        "type": "QueryByExample",
        "credentialQuery": {
          "example": {
            "@context": [
              "https://www.w3.org/2018/credentials/v1",
              "https://w3id.org/traceability/v1"
            ],
            "type": ["VerifiableCredential", "MillTestReportCertificate", "CommercialInvoiceCertificate", "BillOfLadingCertificate"]
          }
        }
      }
    ],
    "domain": "customs.example.gov",
    "challenge": "3182bdea-63d9-11ea-b6de-3b7c1404d57f"
  }

Step 3: Presentation Submission

A holder completes the workflow they initiated by submitting a Verifiable Presentation over the challenge and optionally the domain obtained from Step 2.

            {
              "@context": [
                "https://www.w3.org/2018/credentials/v1",
                "https://w3id.org/traceability/v1"
              ],
              "type": ["VerifiablePresentation"],
              "holder": "did:example:123",
              "verifiableCredential": [
                {
                  ...
                  "id": "https://example.com/credential/123",
                  "type": ["VerifiableCredential", "MillTestReportCertificate"],
                  ...
                },
                {
                  ...
                  "id": "https://example.com/credential/456",
                  "type": ["VerifiableCredential", "CommercialInvoiceCertificate"],
                  ...
                },
                {
                  ...
                  "id": "https://example.com/credential/789",
                  "type": ["VerifiableCredential", "BillOfLadingCertificate"],
                  ...
                }
              ],
              "proof": {
               ...
              }
            }
          

Step 4: Presentation Acknowledgement

A verifier acknowledges workflow they initiated by providing a response in Step 2.

            {
              "verified": true,
              ...
            }