@mattrglobal/verifier-sdk-web 0.1.0

package/dist/typings/common/error.d.ts

@@ -0,0 +1,74 @@
+import { Result } from "neverthrow";
+/**
+ * Base error type used for all sdk error responses
+ * @typeParam T - the error type
+ */
+export declare type BaseError<T = string> = {
+    /**
+     * Error type
+     */
+    readonly type: T;
+    /**
+     * Message containing error description
+     */
+    readonly message: string;
+    /**
+     * Information about underlying root cause
+     */
+    readonly cause?: Error | unknown;
+    /**
+     * Additional details
+     */
+    readonly details?: unknown;
+};
+/**
+ * Instance of an exception
+ *
+ * @remarks
+ * Used to raise exception when something unexpeced occurs
+ *
+ * @example
+ * ```
+ * throw new Exception();
+ * throw new Exception(erorr);
+ * throw new Exception("Unexpected error occur signing", error);
+ * ```
+ */
+export declare class Exception extends Error {
+    readonly cause?: unknown;
+    constructor(message: string);
+    constructor(cause: unknown);
+    constructor(message: string | unknown, cause: unknown);
+}
+/**
+ * A utility function to get the value from a {@link Result} or throw if there was an error
+ *
+ * @remarks
+ * Allows you to get the value of a result directly or handle an error {@link Result} as an exception
+ *
+ * @param result - The {@link Result} to unwrap
+ * @param errMessage - Error message used when unwrap failed
+ * @typeParam T - the expected value of an ok result
+ */
+export declare const unwrap: <T = unknown>(result: Result<T, unknown>, errMessage?: string) => T;
+/**
+ * Used for exhaustive if/switch statements
+ * Example:
+ *
+ * ```ts
+ * enum Fruit {
+ *  orange = "orange",
+ *  apple = "apple",
+ * }
+ *
+ * const getFruitName = (fruit: Fruit): string => {
+ *  if (fruit === Fruit.orange) {
+ *    return "Orange";
+ *  }
+ *
+ *  // Should fail TS compilation as Fruit.apple is not being handled in the code above
+ *  return assertUnreachable(fruit);
+ * }
+ * ```
+ */
+export declare const assertUnreachable: (_: never) => never;

package/dist/typings/common/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./error";
+export * from "./validation";
+export * from "./safeFetch";

package/dist/typings/common/safeFetch.d.ts

@@ -0,0 +1,23 @@
+import { Result } from "neverthrow";
+import { BaseError } from "./error";
+export declare enum SafeFetchCommonRespondErrorType {
+    /**
+     * Unexpected response from the remote server
+     */
+    UnexpectedRespond = "UnexpectedRespond"
+}
+export declare enum SafeFetchErrorType {
+    /**
+     * Http error from the remote server with non 2XX response
+     */
+    HttpError = "HttpError",
+    /**
+     * Other uncategorised errors
+     */
+    UnknownError = "UnknownError"
+}
+export declare type SafeFetchValidateRespondError = BaseError<SafeFetchErrorType | SafeFetchCommonRespondErrorType.UnexpectedRespond>;
+/**
+ * Safe fetch function that wraps the fetch function and returns a Result type
+ */
+export declare const safeFetch: (input: RequestInfo, init?: RequestInit) => Promise<Result<Response, BaseError<SafeFetchErrorType>>>;

package/dist/typings/common/validation.d.ts

@@ -0,0 +1,11 @@
+import { ZodType } from "zod";
+/**
+ * Provide typeguards and boolean result of a zod validator
+ * @param validator
+ */
+export declare const isType: <T>(validator: ZodType<T, import("zod").ZodTypeDef, T>) => (value: unknown) => value is T;
+/**
+ * Asserts data against either internal Validator functions or Zod object schemas
+ * Throws CoreTypeError if assertion fails
+ */
+export declare const assertType: <T, InputData = T>(validator: ZodType<T, import("zod").ZodTypeDef, T>, message: string) => (data: InputData) => void;

package/dist/typings/index.d.ts

@@ -0,0 +1,11 @@
+import { initialise, requestCredentials, handleRedirectCallback } from "./verifier";
+import { HandleRedirectCallbackError, HandleRedirectCallbackErrorType } from "./verifier/handleRedirectCallback";
+import { RequestCredentialsError, RequestCredentialsErrorType } from "./verifier/requestCredentials";
+import { InitialiseOptions, RequestCredentialsOptions, CredentialQuery, OpenidPresentationCredentialProfileSupported, Mode, RequestCredentialsResponse, HandleRedirectCallbackResponse, ClaimType, PresentationSuccessResult, MobileCredentialPresentationCredential, ValidityInfoRequest, CredentialBranding, MobileCredentialResponseErrorCode, MobileCredentialVerificationResult, MobileCredentialVerificationReasonType, CredentialBrandingImageFormat } from "./verifier/types";
+export { Mode, OpenidPresentationCredentialProfileSupported, MobileCredentialVerificationReasonType, RequestCredentialsErrorType, HandleRedirectCallbackErrorType, CredentialBrandingImageFormat, ClaimType, };
+export type { InitialiseOptions, RequestCredentialsOptions, CredentialQuery, RequestCredentialsResponse, RequestCredentialsError, HandleRedirectCallbackResponse, PresentationSuccessResult, MobileCredentialPresentationCredential, ValidityInfoRequest, CredentialBranding, MobileCredentialResponseErrorCode, MobileCredentialVerificationResult, HandleRedirectCallbackError, };
+declare const utils: {
+    generateChallenge: () => string;
+    unwrap: <T = unknown>(result: import("neverthrow").Result<T, unknown>, errMessage?: string | undefined) => T;
+};
+export { initialise, requestCredentials, handleRedirectCallback, utils };

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

@@ -0,0 +1,14 @@
+import { Result } from "neverthrow";
+import { BaseError } from "../common";
+import { HandleRedirectCallbackResponse } from "./types";
+export declare enum HandleRedirectCallbackErrorType {
+    HandleRedirectCallbackFailed = "HandleRedirectCallbackFailed"
+}
+export declare enum HandleRedirectCallbackErrorMessage {
+    FailedToFindResponseCode = "Failed to find response code",
+    FailedToFindChallenge = "Failed to find challenge",
+    FailedToFindSessionId = "Failed to find sessionId",
+    FailedToGetSessionResult = "Failed to get session result"
+}
+export declare type HandleRedirectCallbackError = BaseError<HandleRedirectCallbackErrorType>;
+export declare const handleRedirectCallback: () => Promise<Result<HandleRedirectCallbackResponse, HandleRedirectCallbackError>>;

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

@@ -0,0 +1,5 @@
+export { initialise } from "./initialise";
+export { requestCredentials } from "./requestCredentials";
+export { handleRedirectCallback } from "./handleRedirectCallback";
+export * as types from "./types";
+export * as utils from "./utils";

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

@@ -0,0 +1,7 @@
+import { InitialiseOptions } from "./types";
+export declare enum InitialiseErrorMessage {
+    SdkNotInitialised = "SDK not initialised"
+}
+export declare const initialise: (options: InitialiseOptions) => void;
+export declare const getInitialiseOptions: () => InitialiseOptions | undefined;
+export declare const clearInitialiseOptions: () => void;

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

@@ -0,0 +1,12 @@
+import { Result } from "neverthrow";
+import { BaseError } from "../common";
+import { RequestCredentialsOptions, RequestCredentialsResponse } from "./types";
+export declare enum RequestCredentialsErrorType {
+    RequestCredentialsFailed = "RequestCredentialsFailed"
+}
+export declare enum RequestCredentialsErrorMessage {
+    FailedToStoreChallenge = "Failed to store challenge",
+    FailedToCreateSession = "Failed to create session"
+}
+export declare type RequestCredentialsError = BaseError<RequestCredentialsErrorType>;
+export declare const requestCredentials: (options: RequestCredentialsOptions) => Promise<Result<RequestCredentialsResponse, RequestCredentialsError>>;

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

@@ -0,0 +1,222 @@
+import { z } from "zod";
+/*** mobile-credential-framework https://github.com/mattrinternal/opencore/tree/master/packages/mobile-credential-framework/src/types ***/
+export declare enum MobileCredentialVerificationReasonType {
+    Expired = "expired",
+    Inactive = "inactive"
+}
+export declare enum ClaimType {
+    Boolean = "boolean",
+    Number = "number",
+    String = "string",
+    Binary = "binary",
+    Date = "date",
+    DateTime = "dateTime",
+    Array = "array",
+    Object = "object"
+}
+export declare enum CredentialBrandingImageFormat {
+    svg = "svg",
+    png = "png"
+}
+export declare enum MobileCredentialResponseErrorCode {
+    NotReturned = "notReturned"
+}
+export declare type MobileCredentialError = {
+    readonly docType: string;
+    readonly errorCode: MobileCredentialResponseErrorCode;
+};
+/*** mobile-credential-framework end ***/
+/*** credential-presentation https://github.com/mattrinternal/platform/tree/master/libraries/platform-api-types/src/api-types/credential-presentation ***/
+export declare enum OpenidPresentationCredentialProfileSupported {
+    MOBILE = "mobile"
+}
+export declare type CredentialQueryClaim = {
+    intentToRetain?: boolean;
+};
+/**
+ * {
+ *   "format":"mso_mdoc",
+ *   "docType":"org.iso.18013.5.1.mDL",
+ *   "nameSpaces":{
+ *     "org.iso.18013.5.1":{
+ *       "birthdate":{
+ *         "intentToRetain":true
+ *       },
+ *       "portrait":{
+ *         "intentToRetain":true
+ *       },
+ *       "resident_postal_code":{
+ *         "intentToRetain":true
+ *       }
+ *     },
+ *     "org.iso.18013.5.1.aamva":{
+ *       "DHS_compliance":{
+ *         "intentToRetain":true
+ *       }
+ *     }
+ *   }
+ * }
+ */
+export declare type CredentialQuery = {
+    profile: OpenidPresentationCredentialProfileSupported;
+    docType: string;
+    nameSpaces: {
+        [nameSpace: string]: {
+            [claim: string]: CredentialQueryClaim;
+        };
+    };
+};
+export declare const CredentialQueryValidator: z.ZodType<CredentialQuery>;
+/**
+ * List of error types for presentation failure result
+ */
+export declare enum PresentationErrorType {
+    /**
+     * User aborted the session explicitly before it timed-out
+     */
+    SessionAborted = "SessionAborted",
+    /**
+     * The submitted presentation response is invalid
+     * @category Verification Error
+     */
+    VerificationError = "VerificationError",
+    /**
+     * Received an error presentation response
+     */
+    ResponseError = "ResponseError",
+    /**
+     * Encountered an unknown error while processing a presentation response
+     */
+    Unknown = "Unknown"
+}
+/*** credential-presentation end ***/
+/*** mobile-credential https://github.com/mattrinternal/platform/tree/master/libraries/platform-api-types/src/api-types/mobile-credential ***/
+export declare type ValidityInfoRequest = {
+    signed: string;
+    validFrom: string;
+    validUntil: string;
+    expectedUpdate?: string;
+};
+export declare type CredentialBrandingImage = {
+    format: CredentialBrandingImageFormat;
+    data: string;
+};
+export declare type CredentialBranding = {
+    name?: string;
+    description?: string;
+    backgroundColor?: string;
+    watermarkImage?: CredentialBrandingImage;
+    issuerLogo?: CredentialBrandingImage;
+    issuerIcon?: CredentialBrandingImage;
+};
+export declare type MobileCredentialVerificationResult = {
+    readonly verified: true;
+} | {
+    readonly verified: false;
+    readonly reason: {
+        readonly type: MobileCredentialVerificationReasonType;
+        readonly message: string;
+    };
+};
+export declare type ClaimData = boolean | number | string | ClaimData[] | {
+    [key: string]: ClaimData;
+};
+export declare type DrivingPrivilegesClaim = {
+    vehicle_category_code: string;
+    issue_date: string;
+    expiry_date: string;
+}[];
+export declare type Claim = {
+    readonly type?: ClaimType.Boolean;
+    readonly value: boolean;
+} | {
+    readonly type?: ClaimType.Number;
+    readonly value: number;
+} | {
+    readonly type?: ClaimType.String;
+    readonly value: string;
+} | {
+    readonly type: ClaimType.Binary;
+    readonly value: string;
+} | {
+    readonly type: ClaimType.Date;
+    readonly value: string;
+} | {
+    readonly type: ClaimType.DateTime;
+    readonly value: string;
+} | {
+    readonly type: ClaimType.Object;
+    readonly value: Record<string, ClaimData>;
+} | {
+    readonly type: ClaimType.Array;
+    readonly value: Array<ClaimData>;
+};
+export declare type MobileCredentialPresentationCredential = {
+    docType: string;
+    validityInfo: ValidityInfoRequest;
+    branding?: CredentialBranding;
+    claims?: Record<string, Record<string, Claim>>;
+    claimErrors?: Record<string, Record<string, MobileCredentialResponseErrorCode>>;
+    verificationResult: MobileCredentialVerificationResult;
+    issuerInfo: {
+        commonName: string;
+        trustedIssuerId: string;
+    };
+};
+/*** mobile-credential end ***/
+/*** session result https://github.com/mattrinternal/platform/tree/master/libraries/platform-api-types/src/api-types/credential-presentation/sessionResult.ts ***/
+export declare type PresentationSuccessResult = {
+    sessionId: string;
+    challenge: string;
+    credentialQuery: CredentialQuery[];
+    credentials?: MobileCredentialPresentationCredential[];
+    credentialErrors?: MobileCredentialError[];
+};
+export declare type PresentationSuccessResultRelax = {
+    sessionId: string;
+    challenge: string;
+    credentialQuery?: unknown;
+    credentials?: unknown;
+    credentialErrors?: unknown;
+};
+export declare const PresentationSuccessResultRelaxValidator: z.ZodType<PresentationSuccessResultRelax>;
+export declare type PresentationFailureResult = {
+    sessionId: string;
+    challenge: string;
+    credentialQuery: CredentialQuery[];
+    error: {
+        type: PresentationErrorType;
+        message: string;
+    };
+};
+export declare type PresentationSessionResult = PresentationSuccessResult | PresentationFailureResult;
+export declare type ExchangeSessionResultParams = {
+    readonly sessionId: string;
+};
+export declare type ExchangeSessionResultRequest = {
+    readonly challenge: string;
+    readonly responseCode: string;
+};
+export declare type ExchangeSessionResultResponse = PresentationSessionResult;
+/*** session result end ***/
+/*** session https://github.com/mattrinternal/platform/tree/master/libraries/platform-api-types/src/api-types/credential-presentation/session.ts ***/
+export declare type CreateSessionRequest = z.infer<typeof CreateSessionRequestValidator>;
+export declare const CreateSessionRequestValidator: z.ZodObject<{
+    credentialQuery: z.ZodArray<z.ZodType<CredentialQuery, z.ZodTypeDef, CredentialQuery>, "many">;
+    challenge: z.ZodString;
+    redirectUri: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    challenge: string;
+    credentialQuery: CredentialQuery[];
+    redirectUri?: string | undefined;
+}, {
+    challenge: string;
+    credentialQuery: CredentialQuery[];
+    redirectUri?: string | undefined;
+}>;
+export declare type CreateSessionResponse = {
+    sessionId: string;
+    sessionUrl: string;
+};
+export declare const CreateSessionResponseValidator: z.ZodType<CreateSessionResponse>;
+/*** session end ***/

package/dist/typings/verifier/types/index.d.ts

@@ -0,0 +1,4 @@
+/*** required types from platform, import order is important! /***/
+export * from "./credential-presentation";
+/*** required types from platform ***/
+export * from "./verifier-web-sdk";

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

@@ -0,0 +1,29 @@
+import { z } from "zod";
+import { CredentialQuery, PresentationSuccessResult } from "./credential-presentation";
+export declare enum LocalStorageKey {
+    challenge = "mattr_chg",
+    sessionId = "mattr_sid"
+}
+export declare enum Mode {
+    sameDevice = "sameDevice",
+    crossDevice = "crossDevice"
+}
+export declare type SameDeviceRequestCredentialsOptions = {
+    credentialQuery: CredentialQuery[];
+    challenge?: string;
+    redirectUri: string;
+};
+export declare const SameDeviceRequestCredentialsOptionsValidator: z.ZodType<SameDeviceRequestCredentialsOptions>;
+export declare type RequestCredentialsOptions = SameDeviceRequestCredentialsOptions;
+export declare const RequestCredentialsOptionsValidator: z.ZodType<RequestCredentialsOptions>;
+export declare type SameDeviceRequestCredentialsResponse = {
+    sessionId: string;
+};
+export declare type RequestCredentialsResponse = SameDeviceRequestCredentialsResponse;
+export declare type HandleRedirectCallbackResponse = {
+    result: PresentationSuccessResult;
+};
+export declare type InitialiseOptions = {
+    apiBaseUrl: string;
+};
+export declare const InitialiseOptionsValidator: z.ZodType<InitialiseOptions>;

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

@@ -0,0 +1,23 @@
+import { Result } from "neverthrow";
+import { SafeFetchValidateRespondError } from "../common/safeFetch";
+import { CreateSessionRequest, CreateSessionResponse, PresentationSuccessResult } from "./types";
+export declare const generateChallenge: () => string;
+/**
+ * e.g. #response_code=456
+ * @param hash window.location.hash
+ * @param param
+ */
+export declare const getHashParamValue: (hash: string, param: string) => string | null;
+export declare const createSession: ({ credentialQuery, challenge, redirectUri, apiBaseUrl, }: {
+    credentialQuery: import("./types").CredentialQuery[];
+    challenge: string;
+    redirectUri?: string | undefined;
+} & {
+    apiBaseUrl: string;
+}) => Promise<Result<CreateSessionResponse, SafeFetchValidateRespondError>>;
+export declare const getSessionResult: ({ challenge, responseCode, sessionId, apiBaseUrl, }: {
+    challenge: string;
+    responseCode: string;
+    sessionId: string;
+    apiBaseUrl: string;
+}) => Promise<Result<PresentationSuccessResult, SafeFetchValidateRespondError>>;