@metamask-previews/kyc-controller 0.0.0-preview-4f4c98e → 0.0.0-preview-eb263b0ee

package/dist/index.mjs

@@ -0,0 +1,12 @@
+export { KycController, getDefaultKycControllerState, controllerName } from "./KycController.mjs";
+export { KycService, serviceName } from "./KycService.mjs";
+export { selectIsKycRequiredForProduct, selectKycPhase, selectKycSumSub } from "./selectors.mjs";
+export { alpha2ToAlpha3, ALPHA2_TO_ALPHA3 } from "./countryCodes.mjs";
+export { decryptCredentials, generateKeyPair } from "./crypto.mjs";
+// UKYC storage-access-token utilities. Exported so a signed capability token can
+// be minted for testing UKYC Storage (see `mintUkycTestToken`).
+export { UKYC_CAPABILITY_AUTH_SCHEME, UKYC_KWIL_AUDIENCE, UKYC_STORAGE_ACCESS_TOKEN_AUDIENCE, UKYC_STORAGE_ACCESS_TOKEN_AUDIENCES, UKYC_STORAGE_ACCESS_TOKEN_VERSION } from "./ukyc/constants.mjs";
+export { deriveClientMaterial, encodeClientMaterial } from "./ukyc/deriveClientMaterial.mjs";
+export { encodeStorageAccessTokenForHeader, signStorageAccessToken } from "./ukyc/storageAccessToken.mjs";
+export { mintUkycTestToken } from "./ukyc/testToken.mjs";
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,EACb,4BAA4B,EAC5B,cAAc,EACf,4BAA2B;AA+B5B,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,yBAAwB;AA0C1D,OAAO,EACL,6BAA6B,EAC7B,cAAc,EACd,eAAe,EAChB,wBAAuB;AAExB,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,2BAA0B;AACrE,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,qBAAoB;AA0BlE,iFAAiF;AACjF,gEAAgE;AAChE,OAAO,EACL,2BAA2B,EAC3B,kBAAkB,EAClB,kCAAkC,EAClC,mCAAmC,EACnC,iCAAiC,EAClC,6BAA4B;AAC7B,OAAO,EACL,oBAAoB,EACpB,oBAAoB,EACrB,wCAAuC;AAKxC,OAAO,EACL,iCAAiC,EACjC,sBAAsB,EACvB,sCAAqC;AAQtC,OAAO,EAAE,iBAAiB,EAAE,6BAA4B","sourcesContent":["export {\n  KycController,\n  getDefaultKycControllerState,\n  controllerName,\n} from './KycController.js';\nexport type {\n  KycControllerActions,\n  KycControllerEvents,\n  KycControllerGetStateAction,\n  KycControllerMessenger,\n  KycControllerOptions,\n  KycControllerState,\n  KycControllerStateChangeEvent,\n  KycControllerStatusChangedEvent,\n} from './KycController.js';\nexport type {\n  KycControllerAcceptTermsAndStartSessionAction,\n  KycControllerBuildAuthFrameUrlAction,\n  KycControllerBuildCheckFrameUrlAction,\n  KycControllerBuildResetFrameUrlAction,\n  KycControllerCheckKycRequiredAction,\n  KycControllerClearSavedTermsAction,\n  KycControllerClearStateAction,\n  KycControllerCreateVendorCustomerAction,\n  KycControllerGetCustomerIdentityAction,\n  KycControllerGetKycStatusAction,\n  KycControllerGetSessionStatusAction,\n  KycControllerHandleFrameMessageAction,\n  KycControllerInitializeAction,\n  KycControllerLoadDisclaimersAction,\n  KycControllerRefreshKycStatusAction,\n  KycControllerResetAction,\n  KycControllerStartSumSubAction,\n} from './KycController-method-action-types.js';\n\nexport { KycService, serviceName } from './KycService.js';\nexport type {\n  ApplicantAccessTokenResponse,\n  CapabilityAuthorization,\n  CheckKycRequiredParams,\n  CreateVendorCustomerParams,\n  CreateSessionParams,\n  CreateUkycSessionParams,\n  EncryptionSchema,\n  FetchSessionDisclaimersParams,\n  GetSessionStatusParams,\n  VendorCustomerResponse,\n  JwksResponse,\n  KycServiceActions,\n  KycServiceCacheUpdatedEvent,\n  KycServiceEvents,\n  KycServiceGranularCacheUpdatedEvent,\n  KycServiceInvalidateQueriesAction,\n  KycServiceMessenger,\n  KycServiceOptions,\n  SetAuthorizationsParams,\n  SubmitSessionDisclaimersParams,\n  SubmitVendorDisclaimersParams,\n  UkycSessionResponse,\n} from './KycService.js';\nexport type {\n  KycServiceCheckKycRequiredAction,\n  KycServiceCreateVendorCustomerAction,\n  KycServiceCreateJourneyAction,\n  KycServiceCreateSessionAction,\n  KycServiceCreateUkycSessionAction,\n  KycServiceFetchDisclaimersAction,\n  KycServiceFetchJwksAction,\n  KycServiceFetchKycStatusAction,\n  KycServiceFetchSessionDisclaimersAction,\n  KycServiceGetGeoCountryAction,\n  KycServiceGetSessionStatusAction,\n  KycServiceSetAuthorizationsAction,\n  KycServiceSubmitSessionDisclaimersAction,\n  KycServiceSubmitVendorDisclaimersAction,\n} from './KycService-method-action-types.js';\n\nexport {\n  selectIsKycRequiredForProduct,\n  selectKycPhase,\n  selectKycSumSub,\n} from './selectors.js';\n\nexport { alpha2ToAlpha3, ALPHA2_TO_ALPHA3 } from './countryCodes.js';\nexport { decryptCredentials, generateKeyPair } from './crypto.js';\nexport type {\n  DecryptedCredentials,\n  DecryptResult,\n  EncryptedCredentialsEnvelope,\n  X25519KeyPair,\n} from './crypto.js';\n\nexport type {\n  KycConsentDocument,\n  KycConsentRecord,\n  KycCustomerIdentity,\n  KycDisclaimer,\n  KycPhase,\n  KycProduct,\n  KycSessionDisclaimers,\n  KycSessionStatus,\n  KycSumSubLaunchParams,\n  KycSumSubLauncher,\n  KycSumSubStatus,\n  KycUserStatus,\n  KycUserStatusResponse,\n  KycVendor,\n  KycVendorSigning,\n} from './types.js';\n\n// UKYC storage-access-token utilities. Exported so a signed capability token can\n// be minted for testing UKYC Storage (see `mintUkycTestToken`).\nexport {\n  UKYC_CAPABILITY_AUTH_SCHEME,\n  UKYC_KWIL_AUDIENCE,\n  UKYC_STORAGE_ACCESS_TOKEN_AUDIENCE,\n  UKYC_STORAGE_ACCESS_TOKEN_AUDIENCES,\n  UKYC_STORAGE_ACCESS_TOKEN_VERSION,\n} from './ukyc/constants.js';\nexport {\n  deriveClientMaterial,\n  encodeClientMaterial,\n} from './ukyc/deriveClientMaterial.js';\nexport type {\n  EncodedUkycClientMaterial,\n  UkycClientMaterial,\n} from './ukyc/deriveClientMaterial.js';\nexport {\n  encodeStorageAccessTokenForHeader,\n  signStorageAccessToken,\n} from './ukyc/storageAccessToken.js';\nexport type {\n  SignStorageAccessTokenParams,\n  UkycStorageAccessToken,\n  UkycStorageAccessTokenPayload,\n  UkycStorageOperation,\n  UkycTokenPresenter,\n} from './ukyc/storageAccessToken.js';\nexport { mintUkycTestToken } from './ukyc/testToken.js';\nexport type {\n  MintedUkycTestToken,\n  MintUkycTestTokenParams,\n} from './ukyc/testToken.js';\n"]}

package/dist/selectors.cjs

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.selectIsKycRequiredForProduct = exports.selectKycSumSub = exports.selectKycPhase = void 0;
+const reselect_1 = require("reselect");
+const selectKycRequiredByProduct = (state) => state.kycRequiredByProduct;
+/**
+ * Selects the current flow phase.
+ *
+ * @param state - The KycController state.
+ * @returns The current phase.
+ */
+const selectKycPhase = (state) => state.phase;
+exports.selectKycPhase = selectKycPhase;
+/**
+ * Selects the SumSub sub-flow state.
+ *
+ * @param state - The KycController state.
+ * @returns The SumSub state.
+ */
+const selectKycSumSub = (state) => state.sumsub;
+exports.selectKycSumSub = selectKycSumSub;
+/**
+ * Creates a selector that returns whether KYC is required for a product.
+ *
+ * @param product - The consuming feature.
+ * @returns A selector returning the cached requirement, or `undefined`.
+ */
+const selectIsKycRequiredForProduct = (product) => (0, reselect_1.createSelector)([selectKycRequiredByProduct], (map) => map[product]);
+exports.selectIsKycRequiredForProduct = selectIsKycRequiredForProduct;
+//# sourceMappingURL=selectors.cjs.map

package/dist/selectors.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"selectors.cjs","sourceRoot":"","sources":["../src/selectors.ts"],"names":[],"mappings":";;;AAAA,uCAA0C;AAK1C,MAAM,0BAA0B,GAAG,CACjC,KAAyB,EACmB,EAAE,CAAC,KAAK,CAAC,oBAAoB,CAAC;AAE5E;;;;;GAKG;AACI,MAAM,cAAc,GAAG,CAC5B,KAAyB,EACI,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC;AAFjC,QAAA,cAAc,kBAEmB;AAE9C;;;;;GAKG;AACI,MAAM,eAAe,GAAG,CAC7B,KAAyB,EACK,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC;AAFnC,QAAA,eAAe,mBAEoB;AAEhD;;;;;GAKG;AACI,MAAM,6BAA6B,GAAG,CAC3C,OAAmB,EACmC,EAAE,CACxD,IAAA,yBAAc,EACZ,CAAC,0BAA0B,CAAC,EAC5B,CAAC,GAAG,EAAuB,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,CAC3C,CAAC;AANS,QAAA,6BAA6B,iCAMtC","sourcesContent":["import { createSelector } from 'reselect';\n\nimport type { KycControllerState } from './KycController.js';\nimport type { KycProduct } from './types.js';\n\nconst selectKycRequiredByProduct = (\n  state: KycControllerState,\n): KycControllerState['kycRequiredByProduct'] => state.kycRequiredByProduct;\n\n/**\n * Selects the current flow phase.\n *\n * @param state - The KycController state.\n * @returns The current phase.\n */\nexport const selectKycPhase = (\n  state: KycControllerState,\n): KycControllerState['phase'] => state.phase;\n\n/**\n * Selects the SumSub sub-flow state.\n *\n * @param state - The KycController state.\n * @returns The SumSub state.\n */\nexport const selectKycSumSub = (\n  state: KycControllerState,\n): KycControllerState['sumsub'] => state.sumsub;\n\n/**\n * Creates a selector that returns whether KYC is required for a product.\n *\n * @param product - The consuming feature.\n * @returns A selector returning the cached requirement, or `undefined`.\n */\nexport const selectIsKycRequiredForProduct = (\n  product: KycProduct,\n): ((state: KycControllerState) => boolean | undefined) =>\n  createSelector(\n    [selectKycRequiredByProduct],\n    (map): boolean | undefined => map[product],\n  );\n"]}

package/dist/{selectors.d.ts → selectors.d.cts}

@@ -1,5 +1,5 @@
-import type { KycControllerState } from './KycController.js';
-import type { KycProduct } from './types.js';
+import type { KycControllerState } from "./KycController.cjs";
+import type { KycProduct } from "./types.cjs";
 /**
  * Selects the current flow phase.
  *
@@ -20,5 +20,5 @@ export declare const selectKycSumSub: (state: KycControllerState) => KycControll
  * @param product - The consuming feature.
  * @returns A selector returning the cached requirement, or `undefined`.
  */
-export declare const selectIsKycRequiredForProduct: (product: KycProduct) => ((state: KycControllerState) => boolean | undefined);
-//# sourceMappingURL=selectors.d.ts.map
+export declare const selectIsKycRequiredForProduct: (product: KycProduct) => (state: KycControllerState) => boolean | undefined;
+//# sourceMappingURL=selectors.d.cts.map

package/dist/selectors.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"selectors.d.cts","sourceRoot":"","sources":["../src/selectors.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAE,4BAA2B;AAC7D,OAAO,KAAK,EAAE,UAAU,EAAE,oBAAmB;AAM7C;;;;;GAKG;AACH,eAAO,MAAM,cAAc,UAClB,kBAAkB,KACxB,kBAAkB,CAAC,OAAO,CAAgB,CAAC;AAE9C;;;;;GAKG;AACH,eAAO,MAAM,eAAe,UACnB,kBAAkB,KACxB,kBAAkB,CAAC,QAAQ,CAAiB,CAAC;AAEhD;;;;;GAKG;AACH,eAAO,MAAM,6BAA6B,YAC/B,UAAU,aACT,kBAAkB,KAAK,OAAO,GAAG,SAI1C,CAAC"}

package/dist/selectors.d.mts

@@ -0,0 +1,24 @@
+import type { KycControllerState } from "./KycController.mjs";
+import type { KycProduct } from "./types.mjs";
+/**
+ * Selects the current flow phase.
+ *
+ * @param state - The KycController state.
+ * @returns The current phase.
+ */
+export declare const selectKycPhase: (state: KycControllerState) => KycControllerState['phase'];
+/**
+ * Selects the SumSub sub-flow state.
+ *
+ * @param state - The KycController state.
+ * @returns The SumSub state.
+ */
+export declare const selectKycSumSub: (state: KycControllerState) => KycControllerState['sumsub'];
+/**
+ * Creates a selector that returns whether KYC is required for a product.
+ *
+ * @param product - The consuming feature.
+ * @returns A selector returning the cached requirement, or `undefined`.
+ */
+export declare const selectIsKycRequiredForProduct: (product: KycProduct) => (state: KycControllerState) => boolean | undefined;
+//# sourceMappingURL=selectors.d.mts.map

package/dist/selectors.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"selectors.d.mts","sourceRoot":"","sources":["../src/selectors.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAE,4BAA2B;AAC7D,OAAO,KAAK,EAAE,UAAU,EAAE,oBAAmB;AAM7C;;;;;GAKG;AACH,eAAO,MAAM,cAAc,UAClB,kBAAkB,KACxB,kBAAkB,CAAC,OAAO,CAAgB,CAAC;AAE9C;;;;;GAKG;AACH,eAAO,MAAM,eAAe,UACnB,kBAAkB,KACxB,kBAAkB,CAAC,QAAQ,CAAiB,CAAC;AAEhD;;;;;GAKG;AACH,eAAO,MAAM,6BAA6B,YAC/B,UAAU,aACT,kBAAkB,KAAK,OAAO,GAAG,SAI1C,CAAC"}

package/dist/{selectors.js → selectors.mjs}

@@ -1,4 +1,4 @@
-import { createSelector } from 'reselect';
+import { createSelector } from "reselect";
 const selectKycRequiredByProduct = (state) => state.kycRequiredByProduct;
 /**
  * Selects the current flow phase.
@@ -21,4 +21,4 @@ export const selectKycSumSub = (state) => state.sumsub;
  * @returns A selector returning the cached requirement, or `undefined`.
  */
 export const selectIsKycRequiredForProduct = (product) => createSelector([selectKycRequiredByProduct], (map) => map[product]);
-//# sourceMappingURL=selectors.js.map
+//# sourceMappingURL=selectors.mjs.map

package/dist/selectors.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"selectors.mjs","sourceRoot":"","sources":["../src/selectors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,iBAAiB;AAK1C,MAAM,0BAA0B,GAAG,CACjC,KAAyB,EACmB,EAAE,CAAC,KAAK,CAAC,oBAAoB,CAAC;AAE5E;;;;;GAKG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAC5B,KAAyB,EACI,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC;AAE9C;;;;;GAKG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAC7B,KAAyB,EACK,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC;AAEhD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG,CAC3C,OAAmB,EACmC,EAAE,CACxD,cAAc,CACZ,CAAC,0BAA0B,CAAC,EAC5B,CAAC,GAAG,EAAuB,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,CAC3C,CAAC","sourcesContent":["import { createSelector } from 'reselect';\n\nimport type { KycControllerState } from './KycController.js';\nimport type { KycProduct } from './types.js';\n\nconst selectKycRequiredByProduct = (\n  state: KycControllerState,\n): KycControllerState['kycRequiredByProduct'] => state.kycRequiredByProduct;\n\n/**\n * Selects the current flow phase.\n *\n * @param state - The KycController state.\n * @returns The current phase.\n */\nexport const selectKycPhase = (\n  state: KycControllerState,\n): KycControllerState['phase'] => state.phase;\n\n/**\n * Selects the SumSub sub-flow state.\n *\n * @param state - The KycController state.\n * @returns The SumSub state.\n */\nexport const selectKycSumSub = (\n  state: KycControllerState,\n): KycControllerState['sumsub'] => state.sumsub;\n\n/**\n * Creates a selector that returns whether KYC is required for a product.\n *\n * @param product - The consuming feature.\n * @returns A selector returning the cached requirement, or `undefined`.\n */\nexport const selectIsKycRequiredForProduct = (\n  product: KycProduct,\n): ((state: KycControllerState) => boolean | undefined) =>\n  createSelector(\n    [selectKycRequiredByProduct],\n    (map): boolean | undefined => map[product],\n  );\n"]}

package/dist/types.cjs

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * Shared types for the KYC controller and service.
+ *
+ * The KYC flow is vendor-backed (currently MoonPay for identity + SumSub for
+ * document verification) but the surface exposed to consumers (ramps, card) is
+ * intentionally vendor-neutral so a future vendor swap does not ripple out.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.cjs.map

package/dist/types.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.cjs","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG","sourcesContent":["/**\n * Shared types for the KYC controller and service.\n *\n * The KYC flow is vendor-backed (currently MoonPay for identity + SumSub for\n * document verification) but the surface exposed to consumers (ramps, card) is\n * intentionally vendor-neutral so a future vendor swap does not ripple out.\n */\n\n/**\n * A MetaMask feature that consumes KYC. Used to key the per-product\n * \"is KYC required\" cache so ramps, card, and money can share one controller.\n */\nexport type KycProduct = 'ramps' | 'card' | 'money';\n\n/**\n * Identity vendors supported behind the KYC surface.\n *\n * - `moonpay` — MoonPay Check/Auth frames + SumSub documents.\n * - `iron` — Iron-only Money/VBA path: empty-shell customer → consents →\n *   SumSub, with no MoonPay Check/Auth frames.\n */\nexport type KycVendor = 'moonpay' | 'iron';\n\n/**\n * Vendor-scoped identity for the currently authenticated KYC customer.\n *\n * Exposed to consumers (e.g. ramps) that must attach the vendor customer id to\n * downstream provider calls without reading the full KYC state, which also\n * holds session/access tokens. The identifier is session-scoped: it is only\n * available once the customer has authenticated through the current flow and\n * is cleared on `reset()`.\n */\nexport type KycCustomerIdentity = {\n  /** The identity vendor that issued {@link KycCustomerIdentity.id}. */\n  vendor: KycVendor;\n  /** The vendor customer id (e.g. MoonPay customer UUID). */\n  id: string;\n};\n\n/**\n * User-keyed KYC status returned by `GET /kyc/status` and stored for toast /\n * banner rendering. Collapses vendor + SumSub / relay state into the offsite\n * contract.\n */\nexport type KycUserStatus =\n  | 'not-started'\n  | 'pending'\n  | 'need-more-information'\n  | 'terminal-failure'\n  | 'completed';\n\n/**\n * Payload from `GET /kyc/status`, including optional fields that power the\n * 3-state error contract (retryable SumSub vs terminal vs EDD).\n */\nexport type KycUserStatusResponse = {\n  status: KycUserStatus;\n  /** Present when the user can reopen a SumSub session (retryable path). */\n  sumsubSessionId?: string;\n  /** Machine-readable error code for terminal / EDD UX. */\n  errorCode?: string;\n};\n\n/**\n * Phases of the end-to-end identity flow.\n *\n * - `idle` — nothing started.\n * - `terms` — waiting for the customer to accept the vendor terms.\n * - `session` — creating the vendor session (MoonPay) or creating the UKYC\n *   session and recording session-scoped disclaimers (non-MoonPay vendors).\n * - `check` — running the invisible connection-check frame (MoonPay only).\n * - `auth` — running the visible authentication (OTP) frame (MoonPay only).\n * - `form` — authenticated. When the flow is scoped to a product, the\n *   KYC-required check runs automatically from here; otherwise the consumer\n *   drives it manually via `checkKycRequired`. Consents-path vendors skip\n *   this phase.\n * - `submit` — submitting the KYC-required check / launching SumSub.\n * - `done` — flow complete; see `kycRequiredByProduct` / `sumsub` /\n *   `userStatus`. When KYC is required, the document-verification sub-flow is\n *   launched automatically.\n * - `error` — flow halted; see `error`.\n */\nexport type KycPhase =\n  | 'idle'\n  | 'terms'\n  | 'session'\n  | 'check'\n  | 'auth'\n  | 'form'\n  | 'submit'\n  | 'done'\n  | 'error';\n\n/**\n * Progress of the SumSub document-verification sub-flow.\n *\n * - `polling` — the SDK finished and the controller is polling the UKYC\n *   backend for the session's final decision (see `KycSessionStatus`). The\n *   sub-flow resolves to `complete` or `failed` once a terminal status arrives.\n * - `vendorProcessing` — session creation reported that the applicant is\n *   already approved on the relay (`kycStatus`) while the vendor is still\n *   finalizing its own decision (`finalStatus`). There is nothing left for the\n *   applicant to do, so the SDK is not launched; see `statusMessage`.\n */\nexport type KycSumSubStatus =\n  | 'idle'\n  | 'creatingSession'\n  | 'fetchingToken'\n  | 'launching'\n  | 'inProgress'\n  | 'polling'\n  | 'complete'\n  | 'failed'\n  | 'vendorProcessing';\n\n/**\n * The status of a UKYC session, returned by the `GET /sessions/{id}/status`\n * endpoint and polled after the SumSub SDK completes to determine the final\n * verification decision.\n */\nexport type KycSessionStatus = {\n  /**\n   * The overall status of the session. Terminal values (e.g. `approved`,\n   * `completed`, `rejected`, `failed`, `blocked`) end polling; any other value\n   * keeps polling.\n   */\n  finalStatus: string;\n  /** Optional human-readable message describing the status. */\n  statusMessage?: string;\n  /** The vendor-agnostic external user id associated with the session. */\n  externalUserId: string;\n  /** The KYC decision status. */\n  kycStatus: string;\n  /** The identity vendor that handled the session. */\n  vendor: string;\n  /** The vendor-specific status. */\n  vendorStatus: string;\n};\n\n/**\n * A single disclaimer/term the customer must accept before a vendor session is\n * created (`GET /vendors/{vendor}/disclaimers`).\n */\nexport type KycDisclaimer = {\n  id: string;\n  // Mirrors the vendor API response field, which is snake_case.\n  // eslint-disable-next-line @typescript-eslint/naming-convention\n  display_name: string;\n  url: string;\n};\n\n/**\n * A vendor T&C signing returned by `POST /vendors/{vendor}/disclaimers`.\n */\nexport type KycVendorSigning = {\n  /** Iron signing id. */\n  id: string;\n  // Mirrors the vendor API response field, which is snake_case.\n  // eslint-disable-next-line @typescript-eslint/naming-convention\n  customer_id: string;\n  // Mirrors the vendor API response field, which is snake_case.\n  // eslint-disable-next-line @typescript-eslint/naming-convention\n  content_id?: string;\n};\n\n/**\n * A legal document in the session-scoped idOS / KYC-provider catalog\n * (`GET`/`POST /sessions/{sessionId}/disclaimers`).\n */\nexport type KycConsentDocument = {\n  /** Stable identifier of the legal document. */\n  key: string;\n  /** Version of the document currently in force. */\n  version: string;\n  /** Human-readable document title. */\n  title: string;\n  /** URL the document body is hosted at. */\n  url: string;\n  /** Whether this session already consented to this document version. */\n  consented: boolean;\n};\n\n/**\n * A consent record posted for a catalog document. `key` and `version` must\n * match the current session catalog.\n */\nexport type KycConsentRecord = {\n  key: string;\n  version: string;\n};\n\n/**\n * Session-scoped disclaimer catalog returned by\n * `GET`/`POST /sessions/{sessionId}/disclaimers`.\n */\nexport type KycSessionDisclaimers = {\n  /** idOS legal documents. */\n  idOS: KycConsentDocument[];\n  /** KYC provider (SumSub) legal documents. */\n  kycProvider: KycConsentDocument[];\n  /** Whether the user consented to reuse existing idOS credentials. */\n  credentialReusabilityConsentGiven: boolean;\n};\n\n/**\n * Parameters passed to a platform SumSub launcher.\n */\nexport type KycSumSubLaunchParams = {\n  /**\n   * The applicant access token used to initialize the SumSub SDK.\n   */\n  applicantAccessToken: string;\n\n  /**\n   * Called by the SDK when the access token expires; must resolve with a fresh\n   * applicant access token.\n   */\n  onTokenExpiration: () => Promise<string>;\n\n  /**\n   * Called when the SDK reports a status transition.\n   */\n  onStatusChange?: (prevStatus: string, newStatus: string) => void;\n\n  /**\n   * BCP-47 locale for the SDK UI.\n   */\n  locale?: string;\n\n  /**\n   * Enables SDK debug logging.\n   */\n  debug?: boolean;\n};\n\n/**\n * Platform adapter that launches the native/web SumSub SDK.\n *\n * The KYC controller is platform-agnostic and does not import any SDK; each\n * client (mobile / extension / web) injects an implementation of this\n * interface. The controller owns all orchestration (session creation, token\n * exchange, token refresh, state) and only delegates the actual SDK\n * presentation to `launch`.\n */\nexport type KycSumSubLauncher = {\n  /**\n   * Whether the underlying SDK is available in the current runtime (e.g. the\n   * native module is linked). When `false`, `startSumSub` fails fast.\n   */\n  isAvailable(): boolean;\n\n  /**\n   * Presents the SumSub verification flow and resolves with the SDK result.\n   */\n  launch(params: KycSumSubLaunchParams): Promise<Record<string, unknown>>;\n};\n"]}

package/dist/{types.d.ts → types.d.cts}

@@ -205,4 +205,4 @@ export type KycSumSubLauncher = {
      */
     launch(params: KycSumSubLaunchParams): Promise<Record<string, unknown>>;
 };
-//# sourceMappingURL=types.d.ts.map
+//# sourceMappingURL=types.d.cts.map

package/dist/types.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.cts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.d.mts

@@ -0,0 +1,208 @@
+/**
+ * Shared types for the KYC controller and service.
+ *
+ * The KYC flow is vendor-backed (currently MoonPay for identity + SumSub for
+ * document verification) but the surface exposed to consumers (ramps, card) is
+ * intentionally vendor-neutral so a future vendor swap does not ripple out.
+ */
+/**
+ * A MetaMask feature that consumes KYC. Used to key the per-product
+ * "is KYC required" cache so ramps, card, and money can share one controller.
+ */
+export type KycProduct = 'ramps' | 'card' | 'money';
+/**
+ * Identity vendors supported behind the KYC surface.
+ *
+ * - `moonpay` — MoonPay Check/Auth frames + SumSub documents.
+ * - `iron` — Iron-only Money/VBA path: empty-shell customer → consents →
+ *   SumSub, with no MoonPay Check/Auth frames.
+ */
+export type KycVendor = 'moonpay' | 'iron';
+/**
+ * Vendor-scoped identity for the currently authenticated KYC customer.
+ *
+ * Exposed to consumers (e.g. ramps) that must attach the vendor customer id to
+ * downstream provider calls without reading the full KYC state, which also
+ * holds session/access tokens. The identifier is session-scoped: it is only
+ * available once the customer has authenticated through the current flow and
+ * is cleared on `reset()`.
+ */
+export type KycCustomerIdentity = {
+    /** The identity vendor that issued {@link KycCustomerIdentity.id}. */
+    vendor: KycVendor;
+    /** The vendor customer id (e.g. MoonPay customer UUID). */
+    id: string;
+};
+/**
+ * User-keyed KYC status returned by `GET /kyc/status` and stored for toast /
+ * banner rendering. Collapses vendor + SumSub / relay state into the offsite
+ * contract.
+ */
+export type KycUserStatus = 'not-started' | 'pending' | 'need-more-information' | 'terminal-failure' | 'completed';
+/**
+ * Payload from `GET /kyc/status`, including optional fields that power the
+ * 3-state error contract (retryable SumSub vs terminal vs EDD).
+ */
+export type KycUserStatusResponse = {
+    status: KycUserStatus;
+    /** Present when the user can reopen a SumSub session (retryable path). */
+    sumsubSessionId?: string;
+    /** Machine-readable error code for terminal / EDD UX. */
+    errorCode?: string;
+};
+/**
+ * Phases of the end-to-end identity flow.
+ *
+ * - `idle` — nothing started.
+ * - `terms` — waiting for the customer to accept the vendor terms.
+ * - `session` — creating the vendor session (MoonPay) or creating the UKYC
+ *   session and recording session-scoped disclaimers (non-MoonPay vendors).
+ * - `check` — running the invisible connection-check frame (MoonPay only).
+ * - `auth` — running the visible authentication (OTP) frame (MoonPay only).
+ * - `form` — authenticated. When the flow is scoped to a product, the
+ *   KYC-required check runs automatically from here; otherwise the consumer
+ *   drives it manually via `checkKycRequired`. Consents-path vendors skip
+ *   this phase.
+ * - `submit` — submitting the KYC-required check / launching SumSub.
+ * - `done` — flow complete; see `kycRequiredByProduct` / `sumsub` /
+ *   `userStatus`. When KYC is required, the document-verification sub-flow is
+ *   launched automatically.
+ * - `error` — flow halted; see `error`.
+ */
+export type KycPhase = 'idle' | 'terms' | 'session' | 'check' | 'auth' | 'form' | 'submit' | 'done' | 'error';
+/**
+ * Progress of the SumSub document-verification sub-flow.
+ *
+ * - `polling` — the SDK finished and the controller is polling the UKYC
+ *   backend for the session's final decision (see `KycSessionStatus`). The
+ *   sub-flow resolves to `complete` or `failed` once a terminal status arrives.
+ * - `vendorProcessing` — session creation reported that the applicant is
+ *   already approved on the relay (`kycStatus`) while the vendor is still
+ *   finalizing its own decision (`finalStatus`). There is nothing left for the
+ *   applicant to do, so the SDK is not launched; see `statusMessage`.
+ */
+export type KycSumSubStatus = 'idle' | 'creatingSession' | 'fetchingToken' | 'launching' | 'inProgress' | 'polling' | 'complete' | 'failed' | 'vendorProcessing';
+/**
+ * The status of a UKYC session, returned by the `GET /sessions/{id}/status`
+ * endpoint and polled after the SumSub SDK completes to determine the final
+ * verification decision.
+ */
+export type KycSessionStatus = {
+    /**
+     * The overall status of the session. Terminal values (e.g. `approved`,
+     * `completed`, `rejected`, `failed`, `blocked`) end polling; any other value
+     * keeps polling.
+     */
+    finalStatus: string;
+    /** Optional human-readable message describing the status. */
+    statusMessage?: string;
+    /** The vendor-agnostic external user id associated with the session. */
+    externalUserId: string;
+    /** The KYC decision status. */
+    kycStatus: string;
+    /** The identity vendor that handled the session. */
+    vendor: string;
+    /** The vendor-specific status. */
+    vendorStatus: string;
+};
+/**
+ * A single disclaimer/term the customer must accept before a vendor session is
+ * created (`GET /vendors/{vendor}/disclaimers`).
+ */
+export type KycDisclaimer = {
+    id: string;
+    display_name: string;
+    url: string;
+};
+/**
+ * A vendor T&C signing returned by `POST /vendors/{vendor}/disclaimers`.
+ */
+export type KycVendorSigning = {
+    /** Iron signing id. */
+    id: string;
+    customer_id: string;
+    content_id?: string;
+};
+/**
+ * A legal document in the session-scoped idOS / KYC-provider catalog
+ * (`GET`/`POST /sessions/{sessionId}/disclaimers`).
+ */
+export type KycConsentDocument = {
+    /** Stable identifier of the legal document. */
+    key: string;
+    /** Version of the document currently in force. */
+    version: string;
+    /** Human-readable document title. */
+    title: string;
+    /** URL the document body is hosted at. */
+    url: string;
+    /** Whether this session already consented to this document version. */
+    consented: boolean;
+};
+/**
+ * A consent record posted for a catalog document. `key` and `version` must
+ * match the current session catalog.
+ */
+export type KycConsentRecord = {
+    key: string;
+    version: string;
+};
+/**
+ * Session-scoped disclaimer catalog returned by
+ * `GET`/`POST /sessions/{sessionId}/disclaimers`.
+ */
+export type KycSessionDisclaimers = {
+    /** idOS legal documents. */
+    idOS: KycConsentDocument[];
+    /** KYC provider (SumSub) legal documents. */
+    kycProvider: KycConsentDocument[];
+    /** Whether the user consented to reuse existing idOS credentials. */
+    credentialReusabilityConsentGiven: boolean;
+};
+/**
+ * Parameters passed to a platform SumSub launcher.
+ */
+export type KycSumSubLaunchParams = {
+    /**
+     * The applicant access token used to initialize the SumSub SDK.
+     */
+    applicantAccessToken: string;
+    /**
+     * Called by the SDK when the access token expires; must resolve with a fresh
+     * applicant access token.
+     */
+    onTokenExpiration: () => Promise<string>;
+    /**
+     * Called when the SDK reports a status transition.
+     */
+    onStatusChange?: (prevStatus: string, newStatus: string) => void;
+    /**
+     * BCP-47 locale for the SDK UI.
+     */
+    locale?: string;
+    /**
+     * Enables SDK debug logging.
+     */
+    debug?: boolean;
+};
+/**
+ * Platform adapter that launches the native/web SumSub SDK.
+ *
+ * The KYC controller is platform-agnostic and does not import any SDK; each
+ * client (mobile / extension / web) injects an implementation of this
+ * interface. The controller owns all orchestration (session creation, token
+ * exchange, token refresh, state) and only delegates the actual SDK
+ * presentation to `launch`.
+ */
+export type KycSumSubLauncher = {
+    /**
+     * Whether the underlying SDK is available in the current runtime (e.g. the
+     * native module is linked). When `false`, `startSumSub` fails fast.
+     */
+    isAvailable(): boolean;
+    /**
+     * Presents the SumSub verification flow and resolves with the SDK result.
+     */
+    launch(params: KycSumSubLaunchParams): Promise<Record<string, unknown>>;
+};
+//# sourceMappingURL=types.d.mts.map

package/dist/types.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.mts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/{types.js → types.mjs}

@@ -6,4 +6,4 @@
  * intentionally vendor-neutral so a future vendor swap does not ripple out.
  */
 export {};
-//# sourceMappingURL=types.js.map
+//# sourceMappingURL=types.mjs.map

package/dist/types.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.mjs","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG","sourcesContent":["/**\n * Shared types for the KYC controller and service.\n *\n * The KYC flow is vendor-backed (currently MoonPay for identity + SumSub for\n * document verification) but the surface exposed to consumers (ramps, card) is\n * intentionally vendor-neutral so a future vendor swap does not ripple out.\n */\n\n/**\n * A MetaMask feature that consumes KYC. Used to key the per-product\n * \"is KYC required\" cache so ramps, card, and money can share one controller.\n */\nexport type KycProduct = 'ramps' | 'card' | 'money';\n\n/**\n * Identity vendors supported behind the KYC surface.\n *\n * - `moonpay` — MoonPay Check/Auth frames + SumSub documents.\n * - `iron` — Iron-only Money/VBA path: empty-shell customer → consents →\n *   SumSub, with no MoonPay Check/Auth frames.\n */\nexport type KycVendor = 'moonpay' | 'iron';\n\n/**\n * Vendor-scoped identity for the currently authenticated KYC customer.\n *\n * Exposed to consumers (e.g. ramps) that must attach the vendor customer id to\n * downstream provider calls without reading the full KYC state, which also\n * holds session/access tokens. The identifier is session-scoped: it is only\n * available once the customer has authenticated through the current flow and\n * is cleared on `reset()`.\n */\nexport type KycCustomerIdentity = {\n  /** The identity vendor that issued {@link KycCustomerIdentity.id}. */\n  vendor: KycVendor;\n  /** The vendor customer id (e.g. MoonPay customer UUID). */\n  id: string;\n};\n\n/**\n * User-keyed KYC status returned by `GET /kyc/status` and stored for toast /\n * banner rendering. Collapses vendor + SumSub / relay state into the offsite\n * contract.\n */\nexport type KycUserStatus =\n  | 'not-started'\n  | 'pending'\n  | 'need-more-information'\n  | 'terminal-failure'\n  | 'completed';\n\n/**\n * Payload from `GET /kyc/status`, including optional fields that power the\n * 3-state error contract (retryable SumSub vs terminal vs EDD).\n */\nexport type KycUserStatusResponse = {\n  status: KycUserStatus;\n  /** Present when the user can reopen a SumSub session (retryable path). */\n  sumsubSessionId?: string;\n  /** Machine-readable error code for terminal / EDD UX. */\n  errorCode?: string;\n};\n\n/**\n * Phases of the end-to-end identity flow.\n *\n * - `idle` — nothing started.\n * - `terms` — waiting for the customer to accept the vendor terms.\n * - `session` — creating the vendor session (MoonPay) or creating the UKYC\n *   session and recording session-scoped disclaimers (non-MoonPay vendors).\n * - `check` — running the invisible connection-check frame (MoonPay only).\n * - `auth` — running the visible authentication (OTP) frame (MoonPay only).\n * - `form` — authenticated. When the flow is scoped to a product, the\n *   KYC-required check runs automatically from here; otherwise the consumer\n *   drives it manually via `checkKycRequired`. Consents-path vendors skip\n *   this phase.\n * - `submit` — submitting the KYC-required check / launching SumSub.\n * - `done` — flow complete; see `kycRequiredByProduct` / `sumsub` /\n *   `userStatus`. When KYC is required, the document-verification sub-flow is\n *   launched automatically.\n * - `error` — flow halted; see `error`.\n */\nexport type KycPhase =\n  | 'idle'\n  | 'terms'\n  | 'session'\n  | 'check'\n  | 'auth'\n  | 'form'\n  | 'submit'\n  | 'done'\n  | 'error';\n\n/**\n * Progress of the SumSub document-verification sub-flow.\n *\n * - `polling` — the SDK finished and the controller is polling the UKYC\n *   backend for the session's final decision (see `KycSessionStatus`). The\n *   sub-flow resolves to `complete` or `failed` once a terminal status arrives.\n * - `vendorProcessing` — session creation reported that the applicant is\n *   already approved on the relay (`kycStatus`) while the vendor is still\n *   finalizing its own decision (`finalStatus`). There is nothing left for the\n *   applicant to do, so the SDK is not launched; see `statusMessage`.\n */\nexport type KycSumSubStatus =\n  | 'idle'\n  | 'creatingSession'\n  | 'fetchingToken'\n  | 'launching'\n  | 'inProgress'\n  | 'polling'\n  | 'complete'\n  | 'failed'\n  | 'vendorProcessing';\n\n/**\n * The status of a UKYC session, returned by the `GET /sessions/{id}/status`\n * endpoint and polled after the SumSub SDK completes to determine the final\n * verification decision.\n */\nexport type KycSessionStatus = {\n  /**\n   * The overall status of the session. Terminal values (e.g. `approved`,\n   * `completed`, `rejected`, `failed`, `blocked`) end polling; any other value\n   * keeps polling.\n   */\n  finalStatus: string;\n  /** Optional human-readable message describing the status. */\n  statusMessage?: string;\n  /** The vendor-agnostic external user id associated with the session. */\n  externalUserId: string;\n  /** The KYC decision status. */\n  kycStatus: string;\n  /** The identity vendor that handled the session. */\n  vendor: string;\n  /** The vendor-specific status. */\n  vendorStatus: string;\n};\n\n/**\n * A single disclaimer/term the customer must accept before a vendor session is\n * created (`GET /vendors/{vendor}/disclaimers`).\n */\nexport type KycDisclaimer = {\n  id: string;\n  // Mirrors the vendor API response field, which is snake_case.\n  // eslint-disable-next-line @typescript-eslint/naming-convention\n  display_name: string;\n  url: string;\n};\n\n/**\n * A vendor T&C signing returned by `POST /vendors/{vendor}/disclaimers`.\n */\nexport type KycVendorSigning = {\n  /** Iron signing id. */\n  id: string;\n  // Mirrors the vendor API response field, which is snake_case.\n  // eslint-disable-next-line @typescript-eslint/naming-convention\n  customer_id: string;\n  // Mirrors the vendor API response field, which is snake_case.\n  // eslint-disable-next-line @typescript-eslint/naming-convention\n  content_id?: string;\n};\n\n/**\n * A legal document in the session-scoped idOS / KYC-provider catalog\n * (`GET`/`POST /sessions/{sessionId}/disclaimers`).\n */\nexport type KycConsentDocument = {\n  /** Stable identifier of the legal document. */\n  key: string;\n  /** Version of the document currently in force. */\n  version: string;\n  /** Human-readable document title. */\n  title: string;\n  /** URL the document body is hosted at. */\n  url: string;\n  /** Whether this session already consented to this document version. */\n  consented: boolean;\n};\n\n/**\n * A consent record posted for a catalog document. `key` and `version` must\n * match the current session catalog.\n */\nexport type KycConsentRecord = {\n  key: string;\n  version: string;\n};\n\n/**\n * Session-scoped disclaimer catalog returned by\n * `GET`/`POST /sessions/{sessionId}/disclaimers`.\n */\nexport type KycSessionDisclaimers = {\n  /** idOS legal documents. */\n  idOS: KycConsentDocument[];\n  /** KYC provider (SumSub) legal documents. */\n  kycProvider: KycConsentDocument[];\n  /** Whether the user consented to reuse existing idOS credentials. */\n  credentialReusabilityConsentGiven: boolean;\n};\n\n/**\n * Parameters passed to a platform SumSub launcher.\n */\nexport type KycSumSubLaunchParams = {\n  /**\n   * The applicant access token used to initialize the SumSub SDK.\n   */\n  applicantAccessToken: string;\n\n  /**\n   * Called by the SDK when the access token expires; must resolve with a fresh\n   * applicant access token.\n   */\n  onTokenExpiration: () => Promise<string>;\n\n  /**\n   * Called when the SDK reports a status transition.\n   */\n  onStatusChange?: (prevStatus: string, newStatus: string) => void;\n\n  /**\n   * BCP-47 locale for the SDK UI.\n   */\n  locale?: string;\n\n  /**\n   * Enables SDK debug logging.\n   */\n  debug?: boolean;\n};\n\n/**\n * Platform adapter that launches the native/web SumSub SDK.\n *\n * The KYC controller is platform-agnostic and does not import any SDK; each\n * client (mobile / extension / web) injects an implementation of this\n * interface. The controller owns all orchestration (session creation, token\n * exchange, token refresh, state) and only delegates the actual SDK\n * presentation to `launch`.\n */\nexport type KycSumSubLauncher = {\n  /**\n   * Whether the underlying SDK is available in the current runtime (e.g. the\n   * native module is linked). When `false`, `startSumSub` fails fast.\n   */\n  isAvailable(): boolean;\n\n  /**\n   * Presents the SumSub verification flow and resolves with the SDK result.\n   */\n  launch(params: KycSumSubLaunchParams): Promise<Record<string, unknown>>;\n};\n"]}

package/dist/ukyc/constants.cjs

@@ -0,0 +1,75 @@
+"use strict";
+/**
+ * Constants for the UKYC client-derived key material and storage-authorization
+ * layer. See the architecture doc, section "Client-Derived Material".
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UKYC_JWKS_PATH = exports.UKYC_CAPABILITY_AUTH_SCHEME = exports.UKYC_STORAGE_ACCESS_TOKEN_AUDIENCES = exports.UKYC_KWIL_AUDIENCE = exports.UKYC_STORAGE_ACCESS_TOKEN_AUDIENCE = exports.UKYC_STORAGE_ACCESS_TOKEN_VERSION = exports.UKYC_KDF_INFO = exports.UKYC_DERIVED_KEY_SIZES = exports.UKYC_LOCAL_USER_SECRET_SIZE_BYTES = exports.UKYC_LOCAL_USER_SECRET_PATH = void 0;
+/**
+ * Fully-qualified key path for the `local_user_secret` in Encrypted User
+ * Storage.
+ */
+exports.UKYC_LOCAL_USER_SECRET_PATH = `ukyc.local_user_secret`;
+/**
+ * Size of the `local_user_secret` in bytes. 32 bytes (256 bits) provides high
+ * entropy and matches the input length expected by the HKDF-SHA256 derivations
+ * below.
+ */
+exports.UKYC_LOCAL_USER_SECRET_SIZE_BYTES = 32;
+/**
+ * Byte length of each value derived from `local_user_secret`.
+ *
+ * `signingKey` is 32 bytes because it is used directly as the Ed25519
+ * private key (for Ed25519 the 32-byte seed *is* the private key).
+ */
+exports.UKYC_DERIVED_KEY_SIZES = {
+    storageId: 32,
+    dataEncryptionKey: 32,
+    signingKey: 32,
+    relayTunnelKey: 32,
+};
+/**
+ * HKDF `info` labels providing domain separation between the values derived
+ * from `local_user_secret`.
+ */
+exports.UKYC_KDF_INFO = {
+    storageId: 'metamask.ukyc.storage.v1.storage_id',
+    dataEncryptionKey: 'metamask.ukyc.storage.v1.data_encryption_key',
+    signingKey: 'metamask.ukyc.storage.v1.signing_key',
+    relayTunnelKey: 'metamask.ukyc.storage.v1.relay_tunnel_key',
+};
+/**
+ * Version bound into every `storage_access_token` payload.
+ */
+exports.UKYC_STORAGE_ACCESS_TOKEN_VERSION = 1;
+/**
+ * Audience identifying the UKYC user-storage service. Required by UKYC Storage
+ * when it verifies a `storage_access_token`.
+ */
+exports.UKYC_STORAGE_ACCESS_TOKEN_AUDIENCE = 'metamask:user-storage:ukyc';
+/**
+ * Audience identifying the idOS Kwil credential-registry nodes. Required by
+ * idOS Kwil when it verifies a `storage_access_token`.
+ */
+exports.UKYC_KWIL_AUDIENCE = 'idos:kwil';
+/**
+ * Full audience list bound into every `storage_access_token` payload. `aud`
+ * lists every verifier that may accept the token, so both UKYC Storage and
+ * idOS Kwil can each find their own entry.
+ */
+exports.UKYC_STORAGE_ACCESS_TOKEN_AUDIENCES = [
+    exports.UKYC_STORAGE_ACCESS_TOKEN_AUDIENCE,
+    exports.UKYC_KWIL_AUDIENCE,
+];
+/**
+ * Authorization scheme under which a signed `storage_access_token` envelope is
+ * carried to UKYC Storage: `Authorization: AccessToken <base64url(envelope)>`.
+ * The credentials portion is what `encodeStorageAccessTokenForHeader` returns.
+ */
+exports.UKYC_CAPABILITY_AUTH_SCHEME = 'AccessToken';
+/**
+ * Standard well-known path where the Fractal encryption service publishes its
+ * JWKS (the Ed25519 public keys used to sign the `jwtChain`).
+ */
+exports.UKYC_JWKS_PATH = '/.well-known/jwks.json';
+//# sourceMappingURL=constants.cjs.map

package/dist/ukyc/constants.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.cjs","sourceRoot":"","sources":["../../src/ukyc/constants.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH;;;GAGG;AACU,QAAA,2BAA2B,GAAG,wBAAiC,CAAC;AAE7E;;;;GAIG;AACU,QAAA,iCAAiC,GAAG,EAAE,CAAC;AAEpD;;;;;GAKG;AACU,QAAA,sBAAsB,GAAG;IACpC,SAAS,EAAE,EAAE;IACb,iBAAiB,EAAE,EAAE;IACrB,UAAU,EAAE,EAAE;IACd,cAAc,EAAE,EAAE;CACV,CAAC;AAEX;;;GAGG;AACU,QAAA,aAAa,GAAG;IAC3B,SAAS,EAAE,qCAAqC;IAChD,iBAAiB,EAAE,8CAA8C;IACjE,UAAU,EAAE,sCAAsC;IAClD,cAAc,EAAE,2CAA2C;CACnD,CAAC;AAEX;;GAEG;AACU,QAAA,iCAAiC,GAAG,CAAC,CAAC;AAEnD;;;GAGG;AACU,QAAA,kCAAkC,GAC7C,4BAAqC,CAAC;AAExC;;;GAGG;AACU,QAAA,kBAAkB,GAAG,WAAoB,CAAC;AAEvD;;;;GAIG;AACU,QAAA,mCAAmC,GAAG;IACjD,0CAAkC;IAClC,0BAAkB;CACV,CAAC;AAEX;;;;GAIG;AACU,QAAA,2BAA2B,GAAG,aAAsB,CAAC;AAElE;;;GAGG;AACU,QAAA,cAAc,GAAG,wBAAwB,CAAC","sourcesContent":["/**\n * Constants for the UKYC client-derived key material and storage-authorization\n * layer. See the architecture doc, section \"Client-Derived Material\".\n */\n\n/**\n * Fully-qualified key path for the `local_user_secret` in Encrypted User\n * Storage.\n */\nexport const UKYC_LOCAL_USER_SECRET_PATH = `ukyc.local_user_secret` as const;\n\n/**\n * Size of the `local_user_secret` in bytes. 32 bytes (256 bits) provides high\n * entropy and matches the input length expected by the HKDF-SHA256 derivations\n * below.\n */\nexport const UKYC_LOCAL_USER_SECRET_SIZE_BYTES = 32;\n\n/**\n * Byte length of each value derived from `local_user_secret`.\n *\n * `signingKey` is 32 bytes because it is used directly as the Ed25519\n * private key (for Ed25519 the 32-byte seed *is* the private key).\n */\nexport const UKYC_DERIVED_KEY_SIZES = {\n  storageId: 32,\n  dataEncryptionKey: 32,\n  signingKey: 32,\n  relayTunnelKey: 32,\n} as const;\n\n/**\n * HKDF `info` labels providing domain separation between the values derived\n * from `local_user_secret`.\n */\nexport const UKYC_KDF_INFO = {\n  storageId: 'metamask.ukyc.storage.v1.storage_id',\n  dataEncryptionKey: 'metamask.ukyc.storage.v1.data_encryption_key',\n  signingKey: 'metamask.ukyc.storage.v1.signing_key',\n  relayTunnelKey: 'metamask.ukyc.storage.v1.relay_tunnel_key',\n} as const;\n\n/**\n * Version bound into every `storage_access_token` payload.\n */\nexport const UKYC_STORAGE_ACCESS_TOKEN_VERSION = 1;\n\n/**\n * Audience identifying the UKYC user-storage service. Required by UKYC Storage\n * when it verifies a `storage_access_token`.\n */\nexport const UKYC_STORAGE_ACCESS_TOKEN_AUDIENCE =\n  'metamask:user-storage:ukyc' as const;\n\n/**\n * Audience identifying the idOS Kwil credential-registry nodes. Required by\n * idOS Kwil when it verifies a `storage_access_token`.\n */\nexport const UKYC_KWIL_AUDIENCE = 'idos:kwil' as const;\n\n/**\n * Full audience list bound into every `storage_access_token` payload. `aud`\n * lists every verifier that may accept the token, so both UKYC Storage and\n * idOS Kwil can each find their own entry.\n */\nexport const UKYC_STORAGE_ACCESS_TOKEN_AUDIENCES = [\n  UKYC_STORAGE_ACCESS_TOKEN_AUDIENCE,\n  UKYC_KWIL_AUDIENCE,\n] as const;\n\n/**\n * Authorization scheme under which a signed `storage_access_token` envelope is\n * carried to UKYC Storage: `Authorization: AccessToken <base64url(envelope)>`.\n * The credentials portion is what `encodeStorageAccessTokenForHeader` returns.\n */\nexport const UKYC_CAPABILITY_AUTH_SCHEME = 'AccessToken' as const;\n\n/**\n * Standard well-known path where the Fractal encryption service publishes its\n * JWKS (the Ed25519 public keys used to sign the `jwtChain`).\n */\nexport const UKYC_JWKS_PATH = '/.well-known/jwks.json';\n"]}

package/dist/ukyc/{constants.d.ts → constants.d.cts}

@@ -6,7 +6,7 @@
  * Fully-qualified key path for the `local_user_secret` in Encrypted User
  * Storage.
  */
-export declare const UKYC_LOCAL_USER_SECRET_PATH: `ukyc.local_user_secret`;
+export declare const UKYC_LOCAL_USER_SECRET_PATH: "ukyc.local_user_secret";
 /**
  * Size of the `local_user_secret` in bytes. 32 bytes (256 bits) provides high
  * entropy and matches the input length expected by the HKDF-SHA256 derivations
@@ -30,10 +30,10 @@ export declare const UKYC_DERIVED_KEY_SIZES: {
  * from `local_user_secret`.
  */
 export declare const UKYC_KDF_INFO: {
-    readonly storageId: 'metamask.ukyc.storage.v1.storage_id';
-    readonly dataEncryptionKey: 'metamask.ukyc.storage.v1.data_encryption_key';
-    readonly signingKey: 'metamask.ukyc.storage.v1.signing_key';
-    readonly relayTunnelKey: 'metamask.ukyc.storage.v1.relay_tunnel_key';
+    readonly storageId: "metamask.ukyc.storage.v1.storage_id";
+    readonly dataEncryptionKey: "metamask.ukyc.storage.v1.data_encryption_key";
+    readonly signingKey: "metamask.ukyc.storage.v1.signing_key";
+    readonly relayTunnelKey: "metamask.ukyc.storage.v1.relay_tunnel_key";
 };
 /**
  * Version bound into every `storage_access_token` payload.
@@ -43,12 +43,12 @@ export declare const UKYC_STORAGE_ACCESS_TOKEN_VERSION = 1;
  * Audience identifying the UKYC user-storage service. Required by UKYC Storage
  * when it verifies a `storage_access_token`.
  */
-export declare const UKYC_STORAGE_ACCESS_TOKEN_AUDIENCE: 'metamask:user-storage:ukyc';
+export declare const UKYC_STORAGE_ACCESS_TOKEN_AUDIENCE: "metamask:user-storage:ukyc";
 /**
  * Audience identifying the idOS Kwil credential-registry nodes. Required by
  * idOS Kwil when it verifies a `storage_access_token`.
  */
-export declare const UKYC_KWIL_AUDIENCE: 'idos:kwil';
+export declare const UKYC_KWIL_AUDIENCE: "idos:kwil";
 /**
  * Full audience list bound into every `storage_access_token` payload. `aud`
  * lists every verifier that may accept the token, so both UKYC Storage and
@@ -60,10 +60,10 @@ export declare const UKYC_STORAGE_ACCESS_TOKEN_AUDIENCES: readonly ["metamask:us
  * carried to UKYC Storage: `Authorization: AccessToken <base64url(envelope)>`.
  * The credentials portion is what `encodeStorageAccessTokenForHeader` returns.
  */
-export declare const UKYC_CAPABILITY_AUTH_SCHEME: 'AccessToken';
+export declare const UKYC_CAPABILITY_AUTH_SCHEME: "AccessToken";
 /**
  * Standard well-known path where the Fractal encryption service publishes its
  * JWKS (the Ed25519 public keys used to sign the `jwtChain`).
  */
 export declare const UKYC_JWKS_PATH = "/.well-known/jwks.json";
-//# sourceMappingURL=constants.d.ts.map
+//# sourceMappingURL=constants.d.cts.map

package/dist/ukyc/constants.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.cts","sourceRoot":"","sources":["../../src/ukyc/constants.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;GAGG;AACH,eAAO,MAAM,2BAA2B,0BAAoC,CAAC;AAE7E;;;;GAIG;AACH,eAAO,MAAM,iCAAiC,KAAK,CAAC;AAEpD;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB;;;;;CAKzB,CAAC;AAEX;;;GAGG;AACH,eAAO,MAAM,aAAa;;;;;CAKhB,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,iCAAiC,IAAI,CAAC;AAEnD;;;GAGG;AACH,eAAO,MAAM,kCAAkC,8BACR,CAAC;AAExC;;;GAGG;AACH,eAAO,MAAM,kBAAkB,aAAuB,CAAC;AAEvD;;;;GAIG;AACH,eAAO,MAAM,mCAAmC,sDAGtC,CAAC;AAEX;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,eAAyB,CAAC;AAElE;;;GAGG;AACH,eAAO,MAAM,cAAc,2BAA2B,CAAC"}