@mattrglobal/verifier-sdk-web 2.1.2-unstable.98 → 2.2.0

package/dist/typings/verifier/handleRedirectCallback.d.ts

@@ -11,7 +11,8 @@ export declare enum HandleRedirectCallbackErrorMessage {
     FailedToFindResponseCode = "Failed to find response code",
     FailedToFindChallenge = "Failed to find challenge",
     FailedToFindActiveSession = "Failed to find active session",
-    FailedToGetSessionResult = "Failed to get session result"
+    FailedToGetSessionResult = "Failed to get session result",
+    StateMismatch = "State mismatch between stored session and back-channel result"
 }
 export type HandleRedirectCallbackError = BaseError<HandleRedirectCallbackErrorType>;
 /**

package/dist/typings/verifier/requestCredentials.d.ts

@@ -3,6 +3,14 @@ import { RequestCredentialsError, RequestCredentialsOptions, RequestCredentialsR
 /**
  * Requests credentials based on the provided options.
  *
+ * An optional `state` correlation reference can be supplied via {@link RequestCredentialsOptions} to link the session to a
+ * record in your own system. When provided it must be a non-empty string, and is carried through the presentation session
+ * and echoed back on the result: on {@link RequestCredentialsResponse} for cross-device flows, and via
+ * `handleRedirectCallback()` for same-device flows. Because `state` is transmitted in plain text on the wallet-facing
+ * request URI and stored in session records, it must not contain personally identifiable information (PII), credentials, or
+ * other sensitive data. When omitted, the OpenID4VP `state` claim falls back to the internal `sessionId` and no `state` is
+ * returned.
+ *
  * @param options - The options to request credentials with {@link RequestCredentialsOptions}.
  * @returns A promise that resolves to a result containing either the {@link RequestCredentialsResponse | requested credentials} or an {@link RequestCredentialsError | error}.
  */

package/dist/typings/verifier/types/credential-presentation.d.ts

@@ -249,6 +249,7 @@ export type PresentationSuccessResult = {
     credentialQuery: CredentialQuery[];
     credentials?: MobileCredentialPresentationCredential[];
     credentialErrors?: MobileCredentialError[];
+    state?: string;
 };
 export type PresentationResultRelax = {
     sessionId: string;
@@ -257,6 +258,7 @@ export type PresentationResultRelax = {
     credentials?: unknown;
     credentialErrors?: unknown;
     error?: unknown;
+    state?: string;
 };
 export declare const PresentationResultRelaxValidator: v.ObjectSchema<{
     readonly sessionId: v.StringSchema<undefined>;
@@ -266,6 +268,7 @@ export declare const PresentationResultRelaxValidator: v.ObjectSchema<{
     readonly credentials: v.OptionalSchema<v.UnknownSchema, undefined>;
     readonly credentialErrors: v.OptionalSchema<v.UnknownSchema, undefined>;
     readonly error: v.OptionalSchema<v.UnknownSchema, undefined>;
+    readonly state: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
 }, undefined>;
 export type PresentationFailureResult = {
     sessionId: string;
@@ -275,6 +278,7 @@ export type PresentationFailureResult = {
         type: PresentationErrorType;
         message: string;
     };
+    state?: string;
 };
 /**
  * The result of a hidden credential presentation request, retured when `resultAvailableInFrontChannel` is set to false in verifier's configuration
@@ -338,6 +342,7 @@ export declare const CreateSessionRequestValidator: v.ObjectSchema<{
     readonly redirectUri: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
     readonly walletProviderId: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
     readonly dcApiSupported: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
+    readonly state: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>, undefined>;
 }, undefined>;
 export type CreateSessionResponse = v.InferOutput<typeof CreateSessionResponseValidator>;
 export declare const CreateSessionResponseValidator: v.UnionSchema<[v.ObjectSchema<{
@@ -351,6 +356,7 @@ export declare const CreateSessionResponseValidator: v.UnionSchema<[v.ObjectSche
     readonly sessionId: v.StringSchema<undefined>;
     readonly sessionKey: v.StringSchema<undefined>;
     readonly sessionUrl: v.StringSchema<undefined>;
+    readonly state: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
 }, undefined>], undefined>;
 export type AbortSessionRequest = v.InferOutput<typeof AbortSessionRequestValidator>;
 export declare const AbortSessionRequestValidator: v.ObjectSchema<{

package/dist/typings/verifier/types/verifier-web-sdk.d.ts

@@ -3,10 +3,11 @@ import { BaseError } from "../../common";
 import { CredentialQuery, Mode, PresentationSessionResult } from "./credential-presentation";
 export declare enum LocalStorageKey {
     challenge = "mattr_chg",
-    sessionId = "mattr_sid"
+    sessionId = "mattr_sid",
+    state = "mattr_st"
 }
 export declare const MATTR_SDK_VERSION_HEADER = "x-mattr-sdk-version";
-export declare const MATTR_SDK_VERSION_VALUE = "2.1.1";
+export declare const MATTR_SDK_VERSION_VALUE = "2.2.0";
 export declare enum MessageEventDataType {
     PresentationCompleted = "PresentationCompleted",// { type: "PresentationCompleted", responseCode, sessionId }
     PresentationTimeout = "PresentationTimeout",// { type: "PresentationTimeout", sessionId }
@@ -19,6 +20,7 @@ export type SameDeviceRequestCredentialsOptions = {
     sessionUrl: string;
     sessionKey: string;
     sessionId: string;
+    state?: string;
 };
 export type CrossDeviceRequestCredentialsOptions = {
     challenge: string;
@@ -26,6 +28,7 @@ export type CrossDeviceRequestCredentialsOptions = {
     sessionUrl: string;
     sessionKey: string;
     sessionId: string;
+    state?: string;
 };
 /**
  * Options for openid4vpConfiguration to request credentials via a same-device flow.
@@ -123,6 +126,12 @@ export type RequestCredentialsOptions = {
      * Optional configuration for openid4vp presentation flow
      */
     openid4vpConfiguration?: OpenIdvpConfiguration;
+    /**
+     * An optional customer-supplied correlation reference attached to the presentation session.
+     * When provided, replaces the internal sessionId as the OpenID4VP `state` claim and is
+     * appended as a plain query parameter to the auth request URI.
+     */
+    state?: string;
 };
 export declare const RequestCredentialsOptionsValidator: v.ObjectSchema<{
     readonly credentialQuery: v.SchemaWithPipe<readonly [v.ArraySchema<v.ObjectSchema<{
@@ -155,6 +164,7 @@ export declare const RequestCredentialsOptionsValidator: v.ObjectSchema<{
         readonly redirectUri: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.NonEmptyAction<string, "Must not be empty">, v.UrlAction<string, undefined>]>;
         readonly mode: v.OptionalSchema<v.PicklistSchema<[Mode.CrossDevice, Mode.SameDevice], undefined>, undefined>;
     }, undefined>], undefined>, undefined>;
+    readonly state: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, "state must not be empty">]>, undefined>;
 }, undefined>;
 export type MessageEvent = {
     data: {
@@ -181,6 +191,12 @@ export type RequestCredentialsResponse = {
      *  Indicates that session is completed and the flow will continue on the redirected page
      */
     sessionCompletedInRedirect?: boolean;
+    /**
+     * The customer-supplied correlation reference echoed back from the session.
+     * Present only when `state` was provided to `requestCredentials()`.
+     * For same-device flows, surfaced via `handleRedirectCallback()` instead.
+     */
+    state?: string;
 };
 /**
  * The error type for the requestCredentials function
@@ -199,7 +215,8 @@ export declare enum RequestCredentialsErrorMessage {
     DcApiError = "Failed to request credentials with Digital Credentials API",
     DcApiResponseParseError = "Failed to parse response from Digital Credentials API",
     Abort = "User aborted the session",
-    Timeout = "User session timeout"
+    Timeout = "User session timeout",
+    StateMismatch = "State mismatch between requested session and back-channel result"
 }
 /**
  * The error type for the `abortCredentialRequest` function
@@ -230,6 +247,12 @@ export type HandleRedirectCallbackResponse = {
      * Session identifier which can be used to fetch a presentation result via a back channel.
      */
     sessionId: string;
+    /**
+     * The customer-supplied correlation reference.
+     * Prefers the back-channel `result.state` value when available; falls back to the
+     * value stored in `localStorage` before the wallet redirect.
+     */
+    state?: string;
 };
 /**
  * Options for the initialize function

package/dist/typings/verifier/utils.d.ts

@@ -26,7 +26,7 @@ export declare const getHashParamValue: (hash: string, param: string) => string
  * @param walletProviderId - optional, The ID of the wallet provider, if not provided the default wallet provider will be used.
  * @returns A promise that resolves to a result containing either the created session response or an error.
  */
-export declare const createSession: ({ credentialQuery, challenge, redirectUri, apiBaseUrl, walletProviderId, dcApiSupported, applicationId, }: CreateSessionRequest & InitializeOptions) => Promise<Result<CreateSessionResponse, SafeFetchValidateResponseError>>;
+export declare const createSession: ({ credentialQuery, challenge, redirectUri, apiBaseUrl, walletProviderId, dcApiSupported, applicationId, state, }: CreateSessionRequest & InitializeOptions) => Promise<Result<CreateSessionResponse, SafeFetchValidateResponseError>>;
 /**
  * Abort a session with the provided parameters.
  *

package/dist/verifier-js.development.js

@@ -7,8 +7,8 @@
  * Do Not Translate or Localize
  *
  * Bundle of @mattrglobal/verifier-sdk-web
- * Generated: 2026-03-17
- * Version: 2.1.1
+ * Generated: 2026-06-08
+ * Version: 2.2.0
  * Dependencies:
  *
  * neverthrow -- 4.3.0
@@ -624,6 +624,23 @@
         if (list.length > 1) return "(".concat(list.join(" ".concat(separator, " ")), ")");
         return (_list$ = list[0]) !== null && _list$ !== void 0 ? _list$ : "never";
     }
+    function minLength(requirement, message$1) {
+        return {
+            kind: "validation",
+            type: "min_length",
+            reference: minLength,
+            async: false,
+            expects: ">=".concat(requirement),
+            requirement: requirement,
+            message: message$1,
+            "~run": function run(dataset, config$1) {
+                if (dataset.typed && dataset.value.length < this.requirement) _addIssue(this, "length", dataset, config$1, {
+                    received: "".concat(dataset.value.length)
+                });
+                return dataset;
+            }
+        };
+    }
     function nonEmpty(message$1) {
         return {
             kind: "validation",
@@ -1320,7 +1337,8 @@
         credentialQuery: optional(unknown()),
         credentials: optional(unknown()),
         credentialErrors: optional(unknown()),
-        error: optional(unknown())
+        error: optional(unknown()),
+        state: optional(string())
     });
     exports.Mode = void 0;
     (function(Mode) {
@@ -1337,7 +1355,8 @@
         challenge: string(),
         redirectUri: optional(string()),
         walletProviderId: optional(string()),
-        dcApiSupported: optional(_boolean())
+        dcApiSupported: optional(_boolean()),
+        state: optional(pipe(string(), minLength(1)))
     });
     const CreateSessionDigitalCredentialsValidator = object({
         type: literal(SessionType.DigitalCredentialsApi),
@@ -1350,7 +1369,8 @@
         type: optional(literal(SessionType.Openid4vp)),
         sessionId: string(),
         sessionKey: string(),
-        sessionUrl: string()
+        sessionUrl: string(),
+        state: optional(string())
     });
     const CreateSessionResponseValidator = union([ CreateSessionDigitalCredentialsValidator, CreateSessionOpenId4vpResponseValidator ]);
     const GetSessionStatusResponseValidator = union([ object({
@@ -1363,9 +1383,10 @@
     (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";
-    const MATTR_SDK_VERSION_VALUE = "2.1.1";
+    const MATTR_SDK_VERSION_VALUE = "2.2.0";
     var MessageEventDataType;
     (function(MessageEventDataType) {
         MessageEventDataType["PresentationCompleted"] = "PresentationCompleted";
@@ -1389,7 +1410,8 @@
     const RequestCredentialsOptionsValidator = object({
         credentialQuery: pipe(array(CredentialQueryValidator), nonEmpty()),
         challenge: optional(string()),
-        openid4vpConfiguration: optional(union([ OpenId4vpConfigSameDeviceOptionsValidator, OpenId4vpConfigCrossDeviceOptionsValidator, OpenId4vpConfigAutoDetectOptionsValidator ]))
+        openid4vpConfiguration: optional(union([ OpenId4vpConfigSameDeviceOptionsValidator, OpenId4vpConfigCrossDeviceOptionsValidator, OpenId4vpConfigAutoDetectOptionsValidator ])),
+        state: optional(pipe(string(), minLength(1, "state must not be empty")))
     });
     exports.RequestCredentialsErrorType = void 0;
     (function(RequestCredentialsErrorType) {
@@ -1408,6 +1430,7 @@
         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;
     (function(AbortSessionErrorType) {
@@ -1590,18 +1613,20 @@
         const urlParams = new URLSearchParams(hash.split("#")[1]);
         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: {
@@ -1708,7 +1733,7 @@
         removeWindowMessageEventListener();
     };
     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;
         }
@@ -1730,10 +1755,22 @@
                 });
                 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
@@ -1777,7 +1814,7 @@
         return modalContainer;
     };
     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
         });
@@ -1801,6 +1838,7 @@
                 sessionId: sessionId,
                 apiBaseUrl: apiBaseUrl,
                 challenge: challenge,
+                state: state,
                 onComplete: data => resolve(ok(data)),
                 onFailure: error => resolve(err(error))
             });
@@ -1975,13 +2013,18 @@
         SameDeviceRequestCredentialsErrorMessage["FailedToCreateSession"] = "Failed to create session";
     })(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 () => {
@@ -2031,7 +2074,7 @@
         }
         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({
@@ -2041,7 +2084,8 @@
             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 err({
@@ -2077,7 +2121,8 @@
                 applicationId: applicationId,
                 sessionUrl: sessionUrl,
                 sessionKey: sessionKey,
-                sessionId: sessionId
+                sessionId: sessionId,
+                state: state
             });
         }
         return await requestCredentialsWithCrossDevice({
@@ -2085,7 +2130,8 @@
             apiBaseUrl: apiBaseUrl,
             sessionUrl: sessionUrl,
             sessionKey: sessionKey,
-            sessionId: sessionId
+            sessionId: sessionId,
+            state: state
         });
     };
     const deriveOpenId4vpRedirectUri = openid4vpConfiguration => {
@@ -2113,8 +2159,10 @@
         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);
@@ -2129,6 +2177,7 @@
         }
         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 err({
                 type: exports.HandleRedirectCallbackErrorType.HandleRedirectCallbackFailed,
@@ -2148,9 +2197,22 @@
                 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 err({
+                type: exports.HandleRedirectCallbackErrorType.HandleRedirectCallbackFailed,
+                message: HandleRedirectCallbackErrorMessage.StateMismatch
+            });
+        }
+        const state = resultState !== null && resultState !== void 0 ? resultState : storedState;
+        window.localStorage.removeItem(LocalStorageKey.state);
         return ok({
             result: "challenge" in result.value ? result.value : undefined,
-            sessionId: result.value.sessionId
+            sessionId: result.value.sessionId,
+            state: state
         });
     };
     const utils = {