@mattrglobal/verifier-sdk-web 1.0.2-unstable.99 → 2.0.0-preview-digital-credential-api.2

package/README.md

@@ -12,6 +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)
   - [Prepare a credential query](#prepare-a-credential-query)
   - [Generate challenge](#generate-challenge)
@@ -61,7 +62,7 @@ to any of our SDKs.
 1. Install dependencies via yarn:
 
 ```bash
-yarn add @mattrglobal/verifier-sdk-web
+yarn add @mattrglobal/verifier-sdk-web@2.0.0-preview-digital-credential-api.2
 ```
 
 2. Import the sdk module in your code:
@@ -77,11 +78,9 @@ MATTRVerifierSDK.initialise(...);
 1. Load the following script tag from your web page:
 
 ```html
-<script src="https://cdn.mattr.global/js/verifier-sdk-web/1.0/verifier-js.production.js"></script>
+<script src="https://cdn.mattr.global/js/verifier-sdk-web/2.0.0-preview-digital-credential-api.2/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
@@ -100,11 +99,24 @@ The SDK can make a request to create a presentation session with a configured MA
 * 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 also SDK supports the experimental Web Platform Digital Credential API. If the SDK detects the Digital Credential API is available in the current web browser and the feature has been enabled via parameters passed to the initialise function, it will attempt to use it ahead of executing the request based on OpenID4VP (ISO 18013-7).
+
 ## Initialise the SDK
 
 You must initialise the SDK before you can use any of its functions and methods.
 
-When initialising the SDK, you must provide the URL of the MATTR VII verifier tenant.
+```javascript
+MATTRVerifierSDK.initialise({
+  apiBaseUrl: "{tenant_url}", // provide the URL of the MATTR VII verifier tenant.
+  /** 
+   * 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
+});
+```
 
 ## Prepare a credential query
 
@@ -159,9 +171,11 @@ 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, 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 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.
 
 # Request credentials examples
 
@@ -169,7 +183,7 @@ When using the same-device presentation flow, the SDK must define what URI to re
 
 ```javascript
 MATTRVerifierSDK.initialise({ apiBaseUrl }); // Initialise the SDK
-const result = await MATTRVerifierSDK.requestCredentials({
+const requestCredentialsResult = await MATTRVerifierSDK.requestCredentials({
   credentialQuery: [credentialQuery], // Define what credential query to use
   challenge: MATTRVerifierSDK.utils.generateChallenge(), // Pass a unique challenge
   walletProviderId, // Define the wallet identifier
@@ -183,6 +197,17 @@ const result = await MATTRVerifierSDK.requestCredentials({
     },
   },
 });
+
+// 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
+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.
 * `credentialQuery`: The credential query to be used in the request.
@@ -196,7 +221,7 @@ const result = await MATTRVerifierSDK.requestCredentials({
 
 ```javascript
 MATTRVerifierSDK.initialise({ apiBaseUrl });
-const result = await MATTRVerifierSDK.requestCredentials({
+const requestCredentialsResult = await MATTRVerifierSDK.requestCredentials({
   credentialQuery: [credentialQuery],
   challenge: MATTRVerifierSDK.utils.generateChallenge(),
   redirectUri,
@@ -204,7 +229,12 @@ const result = await MATTRVerifierSDK.requestCredentials({
   mode: "sameDevice",
 });
 
-// result can be retrieved on redirect uri page. for example
+// 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
 window.addEventListener("load", async () => {
   MATTRVerifierSDK.initialise({ apiBaseUrl });
   const result = await MATTRVerifierSDK.handleRedirectCallback();
@@ -219,7 +249,7 @@ window.addEventListener("load", async () => {
 
 ```javascript
 MATTRVerifierSDK.initialise({ apiBaseUrl });
-const result = await MATTRVerifierSDK.requestCredentials({
+const requestCredentialsResult = await MATTRVerifierSDK.requestCredentials({
   credentialQuery: [credentialQuery],
   challenge: MATTRVerifierSDK.utils.generateChallenge(),
   walletProviderId,
@@ -233,6 +263,11 @@ const result = await MATTRVerifierSDK.requestCredentials({
     },
   },
 });
+
+// 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);
+}
 ```
 
 * `mode`: When set to `crossDevice`, the SDK will only support cross-device flow in this verification workflow.

package/dist/lib/verifier-js-no-deps.cjs.js

@@ -7,8 +7,8 @@
  * Do Not Translate or Localize
  *
  * Bundle of @mattrglobal/verifier-sdk-web
- * Generated: 2024-10-20
- * Version: 1.0.1
+ * Generated: 2024-10-21
+ * Version: 2.0.0-preview-digital-credential-api.2
  * Dependencies:
  */
 
@@ -200,6 +200,11 @@ const CreateSessionResponseValidator = v__namespace.object({
     sessionUrl: v__namespace.string()
 });
 
+const CreateDigitalCredentialsApiSessionResponseValidator = v__namespace.object({
+    sessionId: v__namespace.string(),
+    request: v__namespace.object({})
+});
+
 var LocalStorageKey;
 
 (function(LocalStorageKey) {
@@ -262,7 +267,9 @@ exports.RequestCredentialsErrorType = void 0;
 })(exports.RequestCredentialsErrorType || (exports.RequestCredentialsErrorType = {}));
 
 const InitialiseOptionsValidator = v__namespace.object({
-    apiBaseUrl: v__namespace.string()
+    apiBaseUrl: v__namespace.string(),
+    enableDigitalCredentialsApiSameDeviceFlow: v__namespace.optional(v__namespace.boolean()),
+    enableDigitalCredentialsApiCrossDeviceFlow: v__namespace.optional(v__namespace.boolean())
 });
 
 let initialiseOptions = undefined;
@@ -378,6 +385,64 @@ const isMobileDetect = userAgent => isMobile.isMobile({
     tablet: false
 });
 
+const isDigitalCredentialsApiSupported = () => {
+    var _a;
+    try {
+        return typeof ((_a = navigator === null || navigator === void 0 ? void 0 : navigator.identity) === null || _a === void 0 ? void 0 : _a.get) === "function";
+    } catch (error) {
+        return false;
+    }
+};
+
+const createDigitalCredentialsApiSession = async ({credentialQuery: credentialQuery, challenge: challenge, apiBaseUrl: apiBaseUrl}) => {
+    const postData = {
+        credentialQuery: credentialQuery,
+        challenge: challenge
+    };
+    const responseResult = await safeFetch(`${apiBaseUrl}/v2/presentations/sessions/browserApi/request`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json"
+        },
+        body: JSON.stringify(postData)
+    });
+    if (responseResult.isErr()) {
+        return neverthrow.err(responseResult.error);
+    }
+    const data = await responseResult.value.json();
+    if (!isType(CreateDigitalCredentialsApiSessionResponseValidator)(data)) {
+        return neverthrow.err({
+            type: SafeFetchCommonRespondErrorType.UnexpectedRespond,
+            message: "Create digital credentials api session return unsupported response"
+        });
+    }
+    return neverthrow.ok(data);
+};
+
+const getDigitalCredentialsApiSessionResult = async ({challenge: challenge, sessionId: sessionId, response: response, apiBaseUrl: apiBaseUrl}) => {
+    const postData = {
+        challenge: challenge,
+        sessionId: sessionId,
+        response: response
+    };
+    const fetchResultFn = async () => await safeFetch(`${apiBaseUrl}/v2/presentations/sessions/browserApi/response`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json"
+        },
+        body: JSON.stringify(postData)
+    });
+    const responseResult = await withRetrySafeFetch(fetchResultFn, {
+        retries: 2,
+        retryHttpStatus: 404
+    });
+    if (responseResult.isErr()) {
+        return neverthrow.err(responseResult.error);
+    }
+    const data = await responseResult.value.json();
+    return neverthrow.ok(data);
+};
+
 exports.CrossDeviceCallbackErrorType = void 0;
 
 (function(CrossDeviceCallbackErrorType) {
@@ -519,12 +584,12 @@ const requestCredentialsCrossDevice = async options => {
     });
 };
 
-var SameDeviceRequestCredentialsErrorMessage;
+var SameDeviceRequestCredentialsErrorMessage$1;
 
 (function(SameDeviceRequestCredentialsErrorMessage) {
     SameDeviceRequestCredentialsErrorMessage["FailedToStoreChallenge"] = "Failed to store challenge";
     SameDeviceRequestCredentialsErrorMessage["FailedToCreateSession"] = "Failed to create session";
-})(SameDeviceRequestCredentialsErrorMessage || (SameDeviceRequestCredentialsErrorMessage = {}));
+})(SameDeviceRequestCredentialsErrorMessage$1 || (SameDeviceRequestCredentialsErrorMessage$1 = {}));
 
 const requestCredentialsSameDevice = async options => {
     const {challenge: challenge, credentialQuery: credentialQuery, redirectUri: redirectUri, walletProviderId: walletProviderId, initialiseOptions: initialiseOptions} = options;
@@ -534,7 +599,7 @@ const requestCredentialsSameDevice = async options => {
     if (!storedChallenge) {
         return neverthrow.err({
             type: exports.RequestCredentialsErrorType.RequestCredentialsFailed,
-            message: SameDeviceRequestCredentialsErrorMessage.FailedToStoreChallenge
+            message: SameDeviceRequestCredentialsErrorMessage$1.FailedToStoreChallenge
         });
     }
     const createSessionResult = await createSession({
@@ -547,7 +612,7 @@ const requestCredentialsSameDevice = async options => {
     if (createSessionResult.isErr()) {
         return neverthrow.err({
             type: exports.RequestCredentialsErrorType.RequestCredentialsFailed,
-            message: SameDeviceRequestCredentialsErrorMessage.FailedToCreateSession,
+            message: SameDeviceRequestCredentialsErrorMessage$1.FailedToCreateSession,
             cause: createSessionResult.error
         });
     }
@@ -559,6 +624,71 @@ const requestCredentialsSameDevice = async options => {
     });
 };
 
+var SameDeviceRequestCredentialsErrorMessage;
+
+(function(SameDeviceRequestCredentialsErrorMessage) {
+    SameDeviceRequestCredentialsErrorMessage["FailedToStoreChallenge"] = "Failed to store challenge";
+    SameDeviceRequestCredentialsErrorMessage["FailedToCreateSession"] = "Failed to create session";
+})(SameDeviceRequestCredentialsErrorMessage || (SameDeviceRequestCredentialsErrorMessage = {}));
+
+const requestCredentialsDigitalCredentialsApi = async options => {
+    const {challenge: challenge, credentialQuery: credentialQuery, initialiseOptions: initialiseOptions} = options;
+    const {apiBaseUrl: apiBaseUrl} = initialiseOptions;
+    window.localStorage.setItem(LocalStorageKey.challenge, challenge);
+    const storedChallenge = window.localStorage.getItem(LocalStorageKey.challenge);
+    if (!storedChallenge) {
+        return neverthrow.err({
+            type: exports.RequestCredentialsErrorType.RequestCredentialsFailed,
+            message: SameDeviceRequestCredentialsErrorMessage.FailedToStoreChallenge
+        });
+    }
+    const createSessionResult = await createDigitalCredentialsApiSession({
+        credentialQuery: credentialQuery,
+        challenge: storedChallenge,
+        apiBaseUrl: apiBaseUrl
+    });
+    if (createSessionResult.isErr()) {
+        return neverthrow.err({
+            type: exports.RequestCredentialsErrorType.RequestCredentialsFailed,
+            message: SameDeviceRequestCredentialsErrorMessage.FailedToCreateSession,
+            cause: createSessionResult.error
+        });
+    }
+    const {request: request, sessionId: sessionId} = createSessionResult.value;
+    window.localStorage.setItem(LocalStorageKey.sessionId, sessionId);
+    let rawResponse;
+    try {
+        rawResponse = await navigator.identity.get(request);
+    } catch (_a) {
+        return neverthrow.err({
+            type: exports.RequestCredentialsErrorType.RequestCredentialsFailed,
+            message: "Failed call to digital credentials api"
+        });
+    }
+    let response;
+    try {
+        response = JSON.parse(rawResponse.data);
+    } catch (_b) {
+        response = rawResponse.data;
+    }
+    const result = await getDigitalCredentialsApiSessionResult({
+        challenge: challenge,
+        sessionId: sessionId,
+        response: response,
+        apiBaseUrl: apiBaseUrl
+    });
+    if (result.isOk()) {
+        return neverthrow.ok({
+            sessionId: sessionId,
+            result: result.value
+        });
+    }
+    return neverthrow.err({
+        type: exports.RequestCredentialsErrorType.RequestCredentialsFailed,
+        message: "Invalid response from digital credentials api"
+    });
+};
+
 const requestCredentials = async options => {
     var _a;
     const initialiseOptions = getInitialiseOptions();
@@ -568,6 +698,24 @@ const requestCredentials = async options => {
     assertType(RequestCredentialsOptionsValidator, "Invalid request credential options")(options);
     const {challenge: challenge = generateChallenge()} = options;
     const mode = (_a = options.mode) !== null && _a !== void 0 ? _a : isMobileDetect(navigator.userAgent) ? exports.Mode.sameDevice : exports.Mode.crossDevice;
+    if (initialiseOptions.enableDigitalCredentialsApiCrossDeviceFlow && isDigitalCredentialsApiSupported() && mode === exports.Mode.crossDevice) {
+        console.log("Digital Credentials API support found, proceeding with request using API in cross device flow");
+        return await requestCredentialsDigitalCredentialsApi(Object.assign(Object.assign({}, options), {
+            initialiseOptions: initialiseOptions,
+            challenge: challenge
+        }));
+    } else if (initialiseOptions.enableDigitalCredentialsApiCrossDeviceFlow) {
+        console.log("Digital Credentials API support not found, falling back to OpenID4VP");
+    }
+    if (initialiseOptions.enableDigitalCredentialsApiSameDeviceFlow && isDigitalCredentialsApiSupported() && mode === exports.Mode.sameDevice) {
+        console.log("Digital Credentials API support found, proceeding with request using API in same device flow");
+        return await requestCredentialsDigitalCredentialsApi(Object.assign(Object.assign({}, options), {
+            initialiseOptions: initialiseOptions,
+            challenge: challenge
+        }));
+    } else if (initialiseOptions.enableDigitalCredentialsApiSameDeviceFlow) {
+        console.log("Digital Credentials API support not found, falling back to OpenID4VP");
+    }
     if (mode === exports.Mode.sameDevice && "redirectUri" in options) {
         return await requestCredentialsSameDevice(Object.assign(Object.assign({}, options), {
             initialiseOptions: initialiseOptions,
@@ -650,7 +798,8 @@ const handleRedirectCallback = async () => {
 
 const utils = {
     generateChallenge: generateChallenge,
-    unwrap: unwrap
+    unwrap: unwrap,
+    isDigitalCredentialsApiSupported: isDigitalCredentialsApiSupported
 };
 
 exports.handleRedirectCallback = handleRedirectCallback;