@mattrglobal/verifier-sdk-web 2.1.2-unstable.17 → 2.1.2-unstable.172

package/README.md

@@ -2,6 +2,8 @@
 
 # Table of Contents
 
+- [verifier-sdk-web](#verifier-sdk-web)
+- [Table of Contents](#table-of-contents)
 - [General](#general)
   - [Licensing](#licensing)
   - [Overview](#overview)
@@ -35,15 +37,21 @@ Request or download the
 
 ## Overview
 
-The Verifier Web SDK is a powerful tool for integrating online credential verification capabilities into your web applications. It enables secure and efficient verification of [mDocs](https://learn.mattr.global/docs/mdocs), supporting both [same-device](https://learn.mattr.global/docs/verification/online/mdocs/overview#same-device-verification-workflow) and [cross-device](https://learn.mattr.global/docs/verification/online/mdocs/overview#cross-device-verification-workflow) verification workflows. The SDK leverages the MATTR VII platform to handle credential presentation and verification processes.
+The Verifier Web SDK is a powerful tool for integrating online credential verification capabilities into your web
+applications. It enables secure and efficient verification of [mDocs](https://learn.mattr.global/docs/mdocs), supporting
+both [same-device](https://learn.mattr.global/docs/verification/online/mdocs/overview#same-device-verification-workflow)
+and
+[cross-device](https://learn.mattr.global/docs/verification/online/mdocs/overview#cross-device-verification-workflow)
+verification workflows. The SDK leverages the MATTR VII platform to handle credential presentation and verification
+processes.
 
 ## Features
 
-* Simple integration into web applications.
-* Supports both same-device and cross-device presentation flows.
-* Secure handling of mDocs requests and responses.
-* Compliant with [ISO/IEC DTS 18013-7](https://www.iso.org/standard/82772.html).
-* Offers [DC API](https://wicg.github.io/digital-credentials/) support as a **tech-preview**.
+- Simple integration into web applications.
+- Supports both same-device and cross-device presentation flows.
+- Secure handling of mDocs requests and responses.
+- Compliant with [ISO/IEC DTS 18013-7](https://www.iso.org/standard/82772.html).
+- Offers [DC API](https://wicg.github.io/digital-credentials/) support as a **tech-preview**.
 
 > In this SDK mDocs are referred to as Mobile Credentials.
 
@@ -51,8 +59,8 @@ 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/guides/get-started-pi) for step-by-step instructions to gain access
-to any of our SDKs.
+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.
 
@@ -82,25 +90,28 @@ MATTRVerifierSDK.initialize(...);
 <script src="https://cdn.mattr.global/js/verifier-sdk-web/{VERSION}/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).
+> 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.initialize(...);
-</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:
-* 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).
+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:
+
+- 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).
 
 ## Initialize the SDK
 
@@ -111,96 +122,137 @@ MATTRVerifierSDK.initialize({ apiBaseUrl, applicationId });
 ```
 
 - `apiBaseUrl` (required): URL of 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/Verifier-applications#operation/postVerifierApplication!c=201&path=0/id&t=response) parameter in the response returned when [creating a Verifier application](https://learn.mattr.global/api-reference/latest/tag/Verifier-applications#operation/postVerifierApplication) 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/Verifier-applications#operation/postVerifierApplication!c=201&path=0/id&t=response)
+  parameter in the response returned when
+  [creating a Verifier application](https://learn.mattr.global/api-reference/latest/tag/Verifier-applications#operation/postVerifierApplication)
+  on the MATTR VII verifier tenant.
 
 ## Prepare a credential query
 
-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: 
+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 = [
   {
-    "profile": "mobile",
-    "docType": "org.iso.18013.5.1.mDL",
-    "nameSpaces": {
+    profile: "mobile",
+    docType: "org.iso.18013.5.1.mDL",
+    nameSpaces: {
       "org.iso.18013.5.1": {
-        "given_name": {
-          "intentToRetain": false
+        given_name: {
+          intentToRetain: false,
+        },
+        family_name: {
+          intentToRetain: false,
         },
-        "family_name": {
-          "intentToRetain": false
+        birth_date: {
+          intentToRetain: false,
         },
-        "birth_date": {
-          "intentToRetain": false
+        portrait: {
+          intentToRetain: false,
         },
-        "portrait": {
-          "intentToRetain": false
+        resident_postal_code: {
+          intentToRetain: false,
         },
-        "resident_postal_code": {
-          "intentToRetain": false
-        }
       },
-    }
-  }
+    },
+  },
 ];
 ```
-* `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`.
+- `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.
 
-It also sets `intentToRetain` as `false` for all claims, indicating to the holder that the verifier will not retain any of these claims.
+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`.
 
-> 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.
+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:
-  * Generate this challenge by your backend and pass it to the SDK.
-  * Generate it using the SDK built-in method.
+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:
+
+- Generate this challenge by your backend and pass it to the SDK.
+- Generate it using the SDK built-in method.
 
-When the challenge is generated by your backend, you should use it to validate the verification results received from the MATTR VII verifier tenant.
+When the challenge is generated by your backend, you should use it to validate the verification results received from
+the MATTR VII verifier tenant.
 
 ## Determine supported presentation flows
 
-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.
+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.
+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.
 
 By default, the Verifier Web SDK automatically selects a flow based on the browser's user agent:
-* Same-device flows are used when the agent is a mobile device.
-* Cross-device flows are used in all other cases.
 
-This behavior can be explicitly overridden by specifying the desired mode in the SDK configuration, as shown in the [examples](#usage-examples) below.
+- Same-device flows are used when the agent is a mobile device.
+- Cross-device flows are used in all other cases.
+
+This behavior can be explicitly overridden by specifying the desired mode in the SDK configuration, as shown in the
+[examples](#request-credentials-examples) below.
 
 ## Define wallet identifiers
 
-You can define an identifier of a specific wallet you want to invoke with this verification request. The identifier defined by the SDK in the credential request must match one of the identifiers of a [wallet provider](https://learn.mattr.global/api-reference/latest/tag/Wallet-providers#operation/postWalletProvider!path=name&t=request) created on the MATTR VII verifier tenant.
-* If an identifier is provided and matches the `id` of one of the objects in the `walletProviders` array, the verifier tenant will invoke that specific wallet using its corresponding [`authorizationEndpoint`](https://learn.mattr.global/api-reference/latest/tag/Wallet-providers#operation/postWalletProvider!path=openid4vpConfiguration/authorizationEndpoint&t=request).
-* 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.
+You can define an identifier of a specific wallet you want to invoke with this verification request. The identifier
+defined by the SDK in the credential request must match one of the identifiers of a
+[wallet provider](https://learn.mattr.global/api-reference/latest/tag/Wallet-providers#operation/postWalletProvider!path=name&t=request)
+created on the MATTR VII verifier tenant.
+
+- If an identifier is provided and matches the `id` of one of the objects in the `walletProviders` array, the verifier
+  tenant will invoke that specific wallet using its corresponding
+  [`authorizationEndpoint`](https://learn.mattr.global/api-reference/latest/tag/Wallet-providers#operation/postWalletProvider!path=openid4vpConfiguration/authorizationEndpoint&t=request).
+- 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.
 
 ## 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/api-reference/latest/tag/Verifier-applications#operation/postVerifierApplication!path=0/openid4vpConfiguration/redirectUris&t=request) when creating a verifier application.
+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/Verifier-applications#operation/postVerifierApplication!path=0/openid4vpConfiguration/redirectUris&t=request)
+when creating a verifier application.
 
 ## Request credentials using the DC API
 
-> DC API support is currently offered as a **tech preview**. As such, functionality may be limited, may not work in all scenarios, and could change or break without prior notice.
+> DC API support is currently offered as a **tech preview**. As such, functionality may be limited, may not work in all
+> scenarios, and could change or break without prior notice.
 
-1. Add the `dcApiConfiguration` object to your MATTR VII [verifier application configuration](https://learn.mattr.global/docs/verification/remote-verification-api-reference/verifier-applications#update-a-verifier-application).
+1. Add the `dcApiConfiguration` object to your MATTR VII
+   [verifier application configuration](https://learn.mattr.global/docs/verification/remote-verification-api-reference/verifier-applications#update-a-verifier-application).
 
-2. Use the SDK's `isDigitalCredentialsApiSupported` method to determine if the user's browser supports the Digital Credentials API:
+2. Use the SDK's `isDigitalCredentialsApiSupported` method to determine if the user's browser supports the Digital
+   Credentials API:
 
 ```typescript
 import * as MattrVerifierSDK from "@mattrglobal/verifier-sdk-web";
@@ -243,9 +295,9 @@ const result = await MATTRVerifierSDK.requestCredentials({
   credentialQuery: credentialQuery, // Define what credential query to use
   challenge: MATTRVerifierSDK.utils.generateChallenge(), // Pass a unique challenge
   openid4vpConfiguration: {
-      walletProviderId, // Define the wallet identifier
-      redirectUri, // Define the redirect URI (not required for cross-device only requests)
-  }
+    walletProviderId, // Define the wallet identifier
+    redirectUri, // Define the redirect URI (not required for cross-device only requests)
+  },
 });
 
 if (result.isErr()) {
@@ -254,12 +306,21 @@ if (result.isErr()) {
   console.info("<<< MATTRVerifierSDK.requestCredentials succeed", result.value);
 }
 ```
-* `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 identifiers of a [wallet provider](https://learn.mattr.global/api-reference/latest/tag/Wallet-providers#operation/postWalletProvider!path=name&t=request) created on the MATTR VII verifier tenant..
-* `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/api-reference/latest/tag/Verifier-applications#operation/postVerifierApplication!path=0/openid4vpConfiguration/redirectUris&t=request) in the MATTR VII tenant's verifier application.
+
+- `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 identifiers of a
+  [wallet provider](https://learn.mattr.global/api-reference/latest/tag/Wallet-providers#operation/postWalletProvider!path=name&t=request)
+  created on the MATTR VII verifier tenant..
+- `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/api-reference/latest/tag/Verifier-applications#operation/postVerifierApplication!path=0/openid4vpConfiguration/redirectUris&t=request)
+  in the MATTR VII tenant's verifier application.
 
 ## Request credentials with explicit same-device flow
 
@@ -269,10 +330,10 @@ const result = await MATTRVerifierSDK.requestCredentials({
   credentialQuery: credentialQuery,
   challenge: MATTRVerifierSDK.utils.generateChallenge(),
   openid4vpConfiguration: {
-      redirectUri,
-      walletProviderId,
-      mode: "sameDevice",
-  }
+    redirectUri,
+    walletProviderId,
+    mode: "sameDevice",
+  },
 });
 
 // result can be retrieved on redirect uri page. for example
@@ -282,9 +343,9 @@ window.addEventListener("load", async () => {
 });
 ```
 
-* `mode`: When set to `sameDevice`, the SDK will only support same-device flow in this verification workflow.
-* Note that in this case you must define a `redirectUri`.
-* This example shows how you can redirect the user to page that will retrieve and display the verification results.
+- `mode`: When set to `sameDevice`, the SDK will only support same-device flow in this verification workflow.
+- Note that in this case you must define a `redirectUri`.
+- This example shows how you can redirect the user to page that will retrieve and display the verification results.
 
 ## Request credentials with explicit cross-device flow
 
@@ -294,9 +355,9 @@ const result = await MATTRVerifierSDK.requestCredentials({
   credentialQuery: credentialQuery,
   challenge: MATTRVerifierSDK.utils.generateChallenge(),
   openid4vpConfiguration: {
-      walletProviderId,
-      mode: "crossDevice",
-  }
+    walletProviderId,
+    mode: "crossDevice",
+  },
 });
 
 if (result.isErr()) {
@@ -306,8 +367,10 @@ if (result.isErr()) {
 }
 ```
 
-* `mode`: When set to `crossDevice`, the SDK will only support cross-device flow in this verification workflow.
-* Note that in this case you must define how to handle verification completion and failure.
+- `mode`: When set to `crossDevice`, the SDK will only support cross-device flow in this verification workflow.
+- Note that in this case you must define how to handle verification completion and failure.
 
 # Error Handling
-The SDK includes mechanisms for handling errors, such as invalid requests, session timeouts, and user aborts. Callbacks provide detailed error information to help diagnose and remedy issues.
+
+The SDK includes mechanisms for handling errors, such as invalid requests, session timeouts, and user aborts. Callbacks
+provide detailed error information to help diagnose and remedy issues.

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

@@ -7,7 +7,7 @@
  * Do Not Translate or Localize
  *
  * Bundle of @mattrglobal/verifier-sdk-web
- * Generated: 2026-02-16
+ * Generated: 2026-06-05
  * Version: 2.1.1
  * Dependencies:
  */
@@ -181,7 +181,8 @@ const PresentationResultRelaxValidator = v__namespace.object({
     credentialQuery: v__namespace.optional(v__namespace.unknown()),
     credentials: v__namespace.optional(v__namespace.unknown()),
     credentialErrors: v__namespace.optional(v__namespace.unknown()),
-    error: v__namespace.optional(v__namespace.unknown())
+    error: v__namespace.optional(v__namespace.unknown()),
+    state: v__namespace.optional(v__namespace.string())
 });
 
 exports.Mode = void 0;
@@ -203,7 +204,8 @@ v__namespace.object({
     challenge: v__namespace.string(),
     redirectUri: v__namespace.optional(v__namespace.string()),
     walletProviderId: v__namespace.optional(v__namespace.string()),
-    dcApiSupported: v__namespace.optional(v__namespace.boolean())
+    dcApiSupported: v__namespace.optional(v__namespace.boolean()),
+    state: v__namespace.optional(v__namespace.pipe(v__namespace.string(), v__namespace.minLength(1)))
 });
 
 const CreateSessionDigitalCredentialsValidator = v__namespace.object({
@@ -218,7 +220,8 @@ const CreateSessionOpenId4vpResponseValidator = v__namespace.object({
     type: v__namespace.optional(v__namespace.literal(SessionType.Openid4vp)),
     sessionId: v__namespace.string(),
     sessionKey: v__namespace.string(),
-    sessionUrl: v__namespace.string()
+    sessionUrl: v__namespace.string(),
+    state: v__namespace.optional(v__namespace.string())
 });
 
 const CreateSessionResponseValidator = v__namespace.union([ CreateSessionDigitalCredentialsValidator, CreateSessionOpenId4vpResponseValidator ]);
@@ -246,6 +249,7 @@ var LocalStorageKey;
 (function(LocalStorageKey) {
     LocalStorageKey["challenge"] = "mattr_chg";
     LocalStorageKey["sessionId"] = "mattr_sid";
+    LocalStorageKey["state"] = "mattr_st";
 })(LocalStorageKey || (LocalStorageKey = {}));
 
 const MATTR_SDK_VERSION_HEADER = "x-mattr-sdk-version";
@@ -280,7 +284,8 @@ const OpenId4vpConfigAutoDetectOptionsValidator = v__namespace.object({
 const RequestCredentialsOptionsValidator = v__namespace.object({
     credentialQuery: v__namespace.pipe(v__namespace.array(CredentialQueryValidator), v__namespace.nonEmpty()),
     challenge: v__namespace.optional(v__namespace.string()),
-    openid4vpConfiguration: v__namespace.optional(v__namespace.union([ OpenId4vpConfigSameDeviceOptionsValidator, OpenId4vpConfigCrossDeviceOptionsValidator, OpenId4vpConfigAutoDetectOptionsValidator ]))
+    openid4vpConfiguration: v__namespace.optional(v__namespace.union([ OpenId4vpConfigSameDeviceOptionsValidator, OpenId4vpConfigCrossDeviceOptionsValidator, OpenId4vpConfigAutoDetectOptionsValidator ])),
+    state: v__namespace.optional(v__namespace.pipe(v__namespace.string(), v__namespace.minLength(1, "state must not be empty")))
 });
 
 exports.RequestCredentialsErrorType = void 0;
@@ -303,6 +308,7 @@ var RequestCredentialsErrorMessage;
     RequestCredentialsErrorMessage["DcApiResponseParseError"] = "Failed to parse response from Digital Credentials API";
     RequestCredentialsErrorMessage["Abort"] = "User aborted the session";
     RequestCredentialsErrorMessage["Timeout"] = "User session timeout";
+    RequestCredentialsErrorMessage["StateMismatch"] = "State mismatch between requested session and back-channel result";
 })(RequestCredentialsErrorMessage || (RequestCredentialsErrorMessage = {}));
 
 exports.AbortSessionErrorType = void 0;
@@ -492,18 +498,20 @@ const getHashParamValue = (hash, param) => {
     return urlParams.get(param);
 };
 
-const createSession = async ({credentialQuery: credentialQuery, challenge: challenge, redirectUri: redirectUri, apiBaseUrl: apiBaseUrl, walletProviderId: walletProviderId, dcApiSupported: dcApiSupported, applicationId: applicationId}) => {
+const createSession = async ({credentialQuery: credentialQuery, challenge: challenge, redirectUri: redirectUri, apiBaseUrl: apiBaseUrl, walletProviderId: walletProviderId, dcApiSupported: dcApiSupported, applicationId: applicationId, state: state}) => {
     const openid4vpConfiguration = !!walletProviderId || !!redirectUri ? {
         redirectUri: redirectUri,
         walletProviderId: walletProviderId
     } : undefined;
-    const postData = {
+    const postData = Object.assign({
         credentialQuery: credentialQuery,
         challenge: challenge,
         applicationId: applicationId,
         dcApiSupported: dcApiSupported,
         openid4vpConfiguration: openid4vpConfiguration
-    };
+    }, state !== undefined ? {
+        state: state
+    } : {});
     const responseResult = await safeFetch(`${apiBaseUrl}/v2/presentations/web/sessions`, {
         method: "POST",
         headers: {
@@ -621,7 +629,7 @@ const closeCrossDeviceModal = options => {
 };
 
 const receiveMessageHandler = options => async event => {
-    const {onComplete: onComplete, onFailure: onFailure, container: container, sessionId: sessionId, apiBaseUrl: apiBaseUrl, challenge: challenge} = options;
+    const {onComplete: onComplete, onFailure: onFailure, container: container, sessionId: sessionId, apiBaseUrl: apiBaseUrl, challenge: challenge, state: state} = options;
     if (event.origin !== apiBaseUrl) {
         return;
     }
@@ -643,10 +651,22 @@ const receiveMessageHandler = options => async event => {
             });
             return;
         }
+        const resultState = "challenge" in result.value ? result.value.state : undefined;
+        if (state !== undefined && resultState !== undefined && state !== resultState) {
+            onFailure({
+                type: exports.RequestCredentialsErrorType.RequestCredentialsFailed,
+                message: RequestCredentialsErrorMessage.StateMismatch
+            });
+            closeCrossDeviceModal({
+                container: container
+            });
+            return;
+        }
         onComplete({
             result: "challenge" in result.value ? result.value : undefined,
             sessionId: result.value.sessionId,
-            sessionCompletedInRedirect: false
+            sessionCompletedInRedirect: false,
+            state: resultState !== null && resultState !== void 0 ? resultState : state
         });
         closeCrossDeviceModal({
             container: container
@@ -692,7 +712,7 @@ const openCrossDeviceModal = options => {
 };
 
 const requestCredentialsWithCrossDevice = async options => {
-    const {challenge: challenge, apiBaseUrl: apiBaseUrl, sessionUrl: sessionUrl, sessionId: sessionId, sessionKey: sessionKey} = options;
+    const {challenge: challenge, apiBaseUrl: apiBaseUrl, sessionUrl: sessionUrl, sessionId: sessionId, sessionKey: sessionKey, state: state} = options;
     const container = openCrossDeviceModal({
         sessionUrl: sessionUrl
     });
@@ -716,6 +736,7 @@ const requestCredentialsWithCrossDevice = async options => {
             sessionId: sessionId,
             apiBaseUrl: apiBaseUrl,
             challenge: challenge,
+            state: state,
             onComplete: data => resolve(neverthrow.ok(data)),
             onFailure: error => resolve(neverthrow.err(error))
         });
@@ -903,13 +924,18 @@ var SameDeviceRequestCredentialsErrorMessage;
 })(SameDeviceRequestCredentialsErrorMessage || (SameDeviceRequestCredentialsErrorMessage = {}));
 
 const requestCredentialsSameDevice = async options => {
-    const {challenge: challenge, apiBaseUrl: apiBaseUrl, applicationId: applicationId, sessionUrl: sessionUrl, sessionKey: sessionKey, sessionId: sessionId} = options;
+    const {challenge: challenge, apiBaseUrl: apiBaseUrl, applicationId: applicationId, sessionUrl: sessionUrl, sessionKey: sessionKey, sessionId: sessionId, state: state} = options;
     const abortController = setActiveSession({
         sessionId: sessionId,
         sessionKey: sessionKey
     });
     window.localStorage.setItem(LocalStorageKey.sessionId, sessionId);
     window.localStorage.setItem(LocalStorageKey.challenge, challenge);
+    if (state !== undefined) {
+        window.localStorage.setItem(LocalStorageKey.state, state);
+    } else {
+        window.localStorage.removeItem(LocalStorageKey.state);
+    }
     window.location.assign(sessionUrl);
     await sleep(SESSION_STATUS_POLLING_INITIAL_DELAY_MS);
     const checkResult = await withRetry((async () => {
@@ -960,7 +986,7 @@ const requestCredentials = async options => {
     }
     assertType(RequestCredentialsOptionsValidator, "Invalid request credential options")(options);
     const {apiBaseUrl: apiBaseUrl, applicationId: applicationId} = initializeOptions;
-    const {challenge: challenge = generateChallenge(), credentialQuery: credentialQuery, openid4vpConfiguration: openid4vpConfiguration} = options;
+    const {challenge: challenge = generateChallenge(), credentialQuery: credentialQuery, openid4vpConfiguration: openid4vpConfiguration, state: state} = options;
     const dcApiSupported = isDigitalCredentialsApiSupported();
     const openId4VpRedirectUri = deriveOpenId4vpRedirectUri(openid4vpConfiguration);
     const createSessionResult = await createSession({
@@ -970,7 +996,8 @@ const requestCredentials = async options => {
         walletProviderId: (_a = openid4vpConfiguration === null || openid4vpConfiguration === void 0 ? void 0 : openid4vpConfiguration.walletProviderId) !== null && _a !== void 0 ? _a : undefined,
         apiBaseUrl: apiBaseUrl,
         applicationId: applicationId,
-        dcApiSupported: dcApiSupported
+        dcApiSupported: dcApiSupported,
+        state: state
     });
     if (createSessionResult.isErr()) {
         return neverthrow.err({
@@ -1006,7 +1033,8 @@ const requestCredentials = async options => {
             applicationId: applicationId,
             sessionUrl: sessionUrl,
             sessionKey: sessionKey,
-            sessionId: sessionId
+            sessionId: sessionId,
+            state: state
         });
     }
     return await requestCredentialsWithCrossDevice({
@@ -1014,7 +1042,8 @@ const requestCredentials = async options => {
         apiBaseUrl: apiBaseUrl,
         sessionUrl: sessionUrl,
         sessionKey: sessionKey,
-        sessionId: sessionId
+        sessionId: sessionId,
+        state: state
     });
 };
 
@@ -1047,9 +1076,11 @@ var HandleRedirectCallbackErrorMessage;
     HandleRedirectCallbackErrorMessage["FailedToFindChallenge"] = "Failed to find challenge";
     HandleRedirectCallbackErrorMessage["FailedToFindActiveSession"] = "Failed to find active session";
     HandleRedirectCallbackErrorMessage["FailedToGetSessionResult"] = "Failed to get session result";
+    HandleRedirectCallbackErrorMessage["StateMismatch"] = "State mismatch between stored session and back-channel result";
 })(HandleRedirectCallbackErrorMessage || (HandleRedirectCallbackErrorMessage = {}));
 
 const handleRedirectCallback = async () => {
+    var _a;
     const initializeOptions = getInitializeOptions();
     if (!initializeOptions) {
         throw new Exception(InitializeErrorMessage.SdkNotInitialized);
@@ -1064,6 +1095,7 @@ const handleRedirectCallback = async () => {
     }
     const sessionId = window.localStorage.getItem(LocalStorageKey.sessionId);
     const challenge = window.localStorage.getItem(LocalStorageKey.challenge);
+    const storedState = (_a = window.localStorage.getItem(LocalStorageKey.state)) !== null && _a !== void 0 ? _a : undefined;
     if (!sessionId || !challenge) {
         return neverthrow.err({
             type: exports.HandleRedirectCallbackErrorType.HandleRedirectCallbackFailed,
@@ -1083,9 +1115,22 @@ const handleRedirectCallback = async () => {
             cause: result.error
         });
     }
+    const resultState = "challenge" in result.value ? result.value.state : undefined;
+    if (storedState !== undefined && resultState !== undefined && storedState !== resultState) {
+        window.localStorage.removeItem(LocalStorageKey.challenge);
+        window.localStorage.removeItem(LocalStorageKey.sessionId);
+        window.localStorage.removeItem(LocalStorageKey.state);
+        return neverthrow.err({
+            type: exports.HandleRedirectCallbackErrorType.HandleRedirectCallbackFailed,
+            message: HandleRedirectCallbackErrorMessage.StateMismatch
+        });
+    }
+    const state = resultState !== null && resultState !== void 0 ? resultState : storedState;
+    window.localStorage.removeItem(LocalStorageKey.state);
     return neverthrow.ok({
         result: "challenge" in result.value ? result.value : undefined,
-        sessionId: result.value.sessionId
+        sessionId: result.value.sessionId,
+        state: state
     });
 };