@mattrglobal/verifier-sdk-web 2.0.0-preview-digital-credential-api.4 → 2.0.0

package/README.md

@@ -12,8 +12,7 @@
     - [Web project with an existing bundler set up](#web-project-with-an-existing-bundler-set-up)
     - [Loading directly from script tag](#loading-directly-from-script-tag)
 - [Usage](#usage)
-  - [Support for Digital Credential API (Tech Preview)](#support-for-digital-credential-api-tech-preview)
-  - [Initialise the SDK](#initialise-the-sdk)
+  - [Initialize the SDK](#initialize-the-sdk)
   - [Prepare a credential query](#prepare-a-credential-query)
   - [Generate challenge](#generate-challenge)
   - [Determine supported presentation flows](#determine-supported-presentation-flows)
@@ -30,7 +29,7 @@
 ## Licensing
 
 Request or download the
-[MATTR Pi SDK Trial Licence Agreement](https://learn.mattr.global/docs/terms/mattr-pi-sdk-licence-agreement) and the
+[MATTR Pi SDK Trial License Agreement](https://learn.mattr.global/docs/terms/mattr-pi-sdk-licence-agreement) and the
 [MATTR Customer Agreement](https://learn.mattr.global/docs/terms/customer-agreement) and review these terms carefully.
 
 ## Overview
@@ -50,7 +49,7 @@ The Verifier Web SDK is a powerful tool for integrating online credential verifi
 
 ## How to get access to the MATTR Pi Verifier Web SDK
 
-Refer to our [SDK Docs landing page](https://learn.mattr.global/references#mattr-pi-sdk-docs) for step-by-step instructions to gain access
+Refer to our [SDK Docs landing page](https://learn.mattr.global/guides/get-started-pi) for step-by-step instructions to gain access
 to any of our SDKs.
 
 > Please [reach out](mailto:dev-support@mattr.global) if you need any assistance.
@@ -62,7 +61,7 @@ to any of our SDKs.
 1. Install dependencies via yarn:
 
 ```bash
-yarn add @mattrglobal/verifier-sdk-web@2.0.0-preview-digital-credential-api.2
+yarn add @mattrglobal/verifier-sdk-web
 ```
 
 2. Import the sdk module in your code:
@@ -70,7 +69,7 @@ yarn add @mattrglobal/verifier-sdk-web@2.0.0-preview-digital-credential-api.2
 ```javascript
 import * as MATTRVerifierSDK from "@mattrglobal/verifier-sdk-web";
 
-MATTRVerifierSDK.initialise(...);
+MATTRVerifierSDK.initialize(...);
 ```
 
 ### Loading directly from script tag
@@ -78,55 +77,43 @@ MATTRVerifierSDK.initialise(...);
 1. Load the following script tag from your web page:
 
 ```html
-<script src="https://cdn.mattr.global/js/verifier-sdk-web/2.0.0-preview-digital-credential-api.2/verifier-js.production.js"></script>
+<script src="https://cdn.mattr.global/js/verifier-sdk-web/1.0/verifier-js.production.js"></script>
 ```
 
+> This script will automatically pick up any SDK patch updates. You can lock your implementation to a specific patch version by replacing 1.0 with the specific version (e.g. https://cdn.mattr.global/js/verifier-sdk-web/1.0.1/verifier-js.production.js).
+
 2. Access SDK functions via global `MATTRVerifierSDK` object.
 
 ```javascript
-<script>
-   MATTRVerifierSDK.initialise(...);
-</script>
+<script> 
+   MATTRVerifierSDK.initialize(...);
+</script> 
 ```
 
 # Usage
 
 The SDK can make a request to create a presentation session with a configured MATTR VII verifier tenant. This requires the following configurations and settings:
-* Initialise the SDK with the URL of the MATTR VII tenant that will handle the verification request.
+* Initialize the SDK with the URL of the MATTR VII tenant that will handle the verification request.
 * Prepare a credential query that defines what claims are required for verification.
 * Generate a unique challenge for the presentation session.
 * Determine what presentation flows are supported in the session.
 * Define what wallets can be used to respond to the verification request.
 * Configure the URI the user will be redirected to when the verification workflow is completed (only required for same-device flows).
 
-## Support for Digital Credential API (Tech Preview)
-
-This SDK supports the experimental Web Platform Digital Credential API and will automatically attempt to use the Digital Credential API (ahead of executing the request based on OpenID4VP as per ISO 18013-7) when the following conditions are met:
-- The SDK detects the Digital Credential API is available in the current web browser.
-- The feature has been enabled when the SDK was [initialised]((#initialise-the-sdk).
-
-## Initialise the SDK
+## Initialize the SDK
 
-You must initialise the SDK before you can use any of its functions and methods:
+You must initialize the SDK before you can use any of its functions and methods:
 
 ```javascript
-MATTRVerifierSDK.initialise({
-  apiBaseUrl: "{tenant_url}",
-  applicationId: "{applicationId}",
-  /**
-   * Configurations when Digital Credential Api is available
-   **/
-  enableDigitalCredentialsApiSameDeviceFlow: true, // indicate if SDK will request credential via Digital Credential Api in a same device flow
-  enableDigitalCredentialsApiCrossDeviceFlow: false, // indicate if SDK request credential via Digital Credential Api in a cross device flow
-});
+MATTRVerifierSDK.initialize({ apiBaseUrl, applicationId });
 ```
 
 - `apiBaseUrl` (required): URL of the MATTR VII verifier tenant.
-- `applicationId` (optional): Unique identifier of the verifier application. This must match the [`name`](https://learn.mattr.global/api-reference/latest/tag/mDocs-verification#operation/postVerifierApplication!path=name&t=request) parameter defined as part of a Verifier application created on the MATTR VII verifier tenant.
+- `applicationId` (required): Unique identifier of the verifier application. This must match the [`id`](https://learn.mattr.global/api-reference/latest/tag/mDocs-verification#operation/postVerifierApplication!c=200&path=id&t=response) parameter in the response returned when [creating a Verifier application configuration](https://learn.mattr.global/api-reference/latest/tag/mDocs-verification#operation/postVerifierApplication) on the MATTR VII verifier tenant.
 
 ## Prepare a credential query
 
-The following example credential query will request the `birthdate` and `portrait` claims from a `mobile` credential `profile` with `org.iso.18013.5.1.mDL` as a `docType`:
+The following example credential query will request the `given_name`, `family_name`, `birth_date` and `portrait` claims from a `mobile` credential profile with `org.iso.18013.5.1.mDL` as a docType: 
 
 ```javascript
 const credentialQuery = [
@@ -135,7 +122,13 @@ const credentialQuery = [
     "docType": "org.iso.18013.5.1.mDL",
     "nameSpaces": {
       "org.iso.18013.5.1": {
-        "birthdate": {
+        "given_name": {
+          "intentToRetain": false
+        },
+        "family_name": {
+          "intentToRetain": false
+        },
+        "birth_date": {
           "intentToRetain": false
         },
         "portrait": {
@@ -149,9 +142,23 @@ const credentialQuery = [
   }
 ];
 ```
-
+* `profile`: Credential format of the credential that will be verified. Currently only mobile (mDocs) is supported.
+* `docType`: the mDL’s type. Confirm with the certificate issuer for what docType they are issuing. Some common examples include:
+  * Mobile Driver License (`org.iso.18013.5.1.mDL`).
+  * PhotoID (`org.iso.23220.photoid.1`).
+  * Mobile Vehicle Registration Card (`org.iso.7367.1.mVRC`).
+  * Health certificate (`org.micov.vtr.1`).
+* `nameSpaces`: Each namespace corresponds to a group of claims included in the credential. These can be claims that are part of a specific standard, jurisdiction or any other reference. The namespace would usually correspond to the requested `docType`.
+  * `intentToRetain` (Optional): When set to `true`, the holder will be indicated that the verifier intends to retain this claim beyond the verification workflow. Defaults to `false` when not specified.
+  
 > The API supports including multiple query objects in the `credentialQuery` array in a single request. For simplicity, this example only includes a single query object.
 
+In this example the `credentialQuery` query will request for the `birthdate`, `portrait` and `resident_postal_code` claims from any credentials whose `profile` is `mobile` and `docType` is `org.iso.18013.5.1.mDL`.
+
+It also sets `intentToRetain` as `false` for all claims, indicating to the holder that the verifier will not retain any of these claims.
+
+> While `intentToRetain` defaults to false, it is explicitly set to `false` in the example above for clarity purposes. If there is no intention to retain a claim, it is sufficient to simply exclude `intentToRetain` from the query.
+
 ## Generate challenge
 
 The Verifier Web SDK passes a unique challenge to the MATTR VII verifier tenant with every request to create a new presentation session. The purpose of the challenge is to ensure the security and integrity of the credential verification process by preventing replay attacks and verifying the authenticity of each request and response. You can either:
@@ -164,7 +171,7 @@ When the challenge is generated by your backend, you should use it to validate t
 
 The **same-device flow** involves the user completing all steps on a single device, such as their smartphone. They initiate the credential request on the verifier's web app, are redirected to their wallet app to consent and present credentials, and then return to the verifier's web app with the results.
 
-In contrast, the **cross-device flow** starts on one device, like a laptop. When the user initiates the request, the web app responds by displaying a QR code. The user then scans this QR code with their smartphone, use their wallet app to present matching credentials, and the results are sent back to the verifier's web app.
+In contrast, the **cross-device flow** starts on one device, like a laptop. When the user initiates the request, the web app responds by displaying a QR code. The user then scans this QR code with their smartphone, use their wallet app to present matching credentials, and the results are sent back to the verifier's web app. 
 
 The main difference is that the same-device flow uses only one device for the entire process, while the cross-device flow uses two devices for added flexibility.
 
@@ -181,72 +188,55 @@ You can define an identifier of a specific wallet you want to invoke with this v
 * If an identifier is provided and does not match the `id` of any of the objects in the `walletProviders array`, the request will fail.
 * If an identifier is not provided, the verifier tenant will use `mdoc-openid4vp://` (default OID4VP scheme) to invoke any wallet.
 
-**Note** that if the SDK request credentials via the Digital Credential API, the mobile operating system will prompt the user to make a selection of which credential from which wallet it would like to respond to the request with.
-
 ## Configure redirectUri
 
-When using the same-device presentation flow with OpenID4VP (ISO 18013-7) e.g instead of using the Digital Credential API, the SDK must define what URI to redirect the user to once they complete the verification workflow in their wallet app. This can be any URI (including custom URI schemes), and must match one of the values defined in the [`redirectUris` array](https://learn.mattr.global/latest/tag/mDocs-verification#operation/putVerifierConfiguration!path=redirectUris&t=request) in the MATTR VII tenant's verifier configuration.
+When using the same-device presentation flow, the SDK must define what URI to redirect the user to once they complete the verification workflow in their wallet app. This can be any URI (including custom URI schemes), and must match one of the values defined in the [`redirectUris` array](https://learn.mattr.global/api-reference/latest/tag/mDocs-verification#operation/postVerifierApplication!path=openid4vpConfiguration/redirectUris&t=request) in the MATTR VII tenant's verifier configuration.
 
 # Request credentials examples
 
 ## Request credentials with automatic flow selection
 
 ```javascript
-MATTRVerifierSDK.initialise({ apiBaseUrl, applicationId }); // Initialise the SDK
+MATTRVerifierSDK.initialize({ apiBaseUrl, applicationId }); // Initialize the SDK
 const result = await MATTRVerifierSDK.requestCredentials({
   credentialQuery: [credentialQuery], // Define what credential query to use
   challenge: MATTRVerifierSDK.utils.generateChallenge(), // Pass a unique challenge
-  walletProviderId, // Define the wallet identifier
-  redirectUri, // Define the redirect URI (not required for cross-device only requests)
-  crossDeviceCallback: { // Define how to handle completion/failure of cross-device flows (not required for same-device only requests)
-    onComplete: (result) => {
-      console.info("<<< MATTRVerifierSDK.requestCredentials crossDeviceCallback.onComplete", result);
-    },
-    onFailure: (error) => {
-      console.info("<<< MATTRVerifierSDK.requestCredentials crossDeviceCallback.onFailure", error);
-    },
-  },
+  openid4vpConfiguration: {
+      walletProviderId, // Define the wallet identifier
+      redirectUri, // Define the redirect URI (not required for cross-device only requests)
+  }
 });
 
-// Check result when it's available in the return value
-if (requestCredentialsResult.isOk() && "result" in requestCredentialsResult.value) {
-  console.info("<<< MATTRVerifierSDK.requestCredentials result",result.value.result);
+if (result.isErr()) {
+  console.info("<<< MATTRVerifierSDK.requestCredentials succeed", result.error);
+} else {
+  console.info("<<< MATTRVerifierSDK.requestCredentials failure", result.value);
 }
-
-// Check result also in your page of redirect_uri
-window.addEventListener("load", async () => {
-  MATTRVerifierSDK.initialise({ apiBaseUrl });
-  const result = await MATTRVerifierSDK.handleRedirectCallback();
-});
 ```
-* `apiBaseUrl` : Replace with the [`tenant_url`](https://learn.mattr.global/docs/security/authentication) of your MATTR VII verifier tenant.
+* `apiBaseUrl` : Replace with the [`tenant_url`](https://learn.mattr.global/docs/platform-management/authentication) of your MATTR VII verifier tenant.
 * `credentialQuery`: The credential query to be used in the request.
 * `challenge`: The challenge that will be passed to the MATTR VII tenant with the request to create a presentation session. This example uses the SDK built-in method to generate the challenge, but you can replace it with a challenge generated by your backend system.
 * `walletProviderId`: Replace with a wallet identifier that matches one of the values in the [`walletProviders` array](https://learn.mattr.global/api-reference/latest/tag/mDocs-verification#operation/putVerifierConfiguration!path=walletProviders/id&t=request) of the MATTR VII tenant's verifier configuration.
 * `mode`: When omitted, the SDK defaults to automatically selecting a flow based on the browser's user agent (set to `undefined` in the example for clarity).
-* `redirectUri` Replace with a URI that matches one of the values in the [`redirectUris` array](https://learn.mattr.global/latest/tag/mDocs-verification#operation/putVerifierConfiguration!path=redirectUris&t=request) in the MATTR VII tenant's verifier configuration.
-* `crossDeviceCallback`: Defines how to handle completion (`onComplete`) or failure (`onFailure`) of the verification workflow.
+* `redirectUri` Replace with a URI that matches one of the values in the [`redirectUris` array](https://learn.mattr.global/api-reference/latest/tag/mDocs-verification#operation/postVerifierApplication!path=openid4vpConfiguration/redirectUris&t=request) in the MATTR VII tenant's verifier application configuration.
 
 ## Request credentials with explicit same-device flow
 
 ```javascript
-MATTRVerifierSDK.initialise({ apiBaseUrl, applicationId });
-const requestCredentialsResult = await MATTRVerifierSDK.requestCredentials({
+MATTRVerifierSDK.initialize({ apiBaseUrl, applicationId });
+const result = await MATTRVerifierSDK.requestCredentials({
   credentialQuery: [credentialQuery],
   challenge: MATTRVerifierSDK.utils.generateChallenge(),
-  redirectUri,
-  walletProviderId,
-  mode: "sameDevice",
+  openid4vpConfiguration: {
+      redirectUri,
+      walletProviderId,
+      mode: "sameDevice",
+  }
 });
 
-// Check result when it's available in the return value
-if (requestCredentialsResult.isOk() && "result" in requestCredentialsResult.value) {
-  console.info("<<< MATTRVerifierSDK.requestCredentials result",result.value.result);
-}
-
-// Check result also in your page of redirect_uri
+// result can be retrieved on redirect uri page. for example
 window.addEventListener("load", async () => {
-  MATTRVerifierSDK.initialise({ apiBaseUrl, applicationId });
+  MATTRVerifierSDK.initialize({ apiBaseUrl, applicationId });
   const result = await MATTRVerifierSDK.handleRedirectCallback();
 });
 ```
@@ -258,25 +248,20 @@ window.addEventListener("load", async () => {
 ## Request credentials with explicit cross-device flow
 
 ```javascript
-MATTRVerifierSDK.initialise({ apiBaseUrl, applicationId });
-const requestCredentialsResult = await MATTRVerifierSDK.requestCredentials({
+MATTRVerifierSDK.initialize({ apiBaseUrl, applicationId });
+const result = await MATTRVerifierSDK.requestCredentials({
   credentialQuery: [credentialQuery],
   challenge: MATTRVerifierSDK.utils.generateChallenge(),
-  walletProviderId,
-  mode: "crossDevice",
-  crossDeviceCallback: {
-    onComplete: (result) => {
-      console.info("<<< MATTRVerifierSDK.requestCredentials crossDeviceCallback.onComplete", result);
-    },
-    onFailure: (error) => {
-      console.info("<<< MATTRVerifierSDK.requestCredentials crossDeviceCallback.onFailure", error);
-    },
-  },
+  openid4vpConfiguration: {
+      walletProviderId,
+      mode: "crossDevice",
+  }
 });
 
-// Check result when it's available in the return value
-if (requestCredentialsResult.isOk() && "result" in requestCredentialsResult.value) {
-  console.info("<<< MATTRVerifierSDK.requestCredentials result",result.value.result);
+if (result.isErr()) {
+  console.info("<<< MATTRVerifierSDK.requestCredentials succeed", result.error);
+} else {
+  console.info("<<< MATTRVerifierSDK.requestCredentials failure", result.value);
 }
 ```