@metamask-previews/kyc-controller 0.0.0-preview-823dcff → 0.0.0-preview-e57e5c3dc

package/dist/types.d.mts

@@ -0,0 +1,124 @@
+/**
+ * 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 and card can share one controller.
+ */
+export type KycProduct = 'ramps' | 'card';
+/**
+ * Identity vendors supported behind the KYC surface.
+ */
+export type KycVendor = 'moonpay';
+/**
+ * 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.
+ * - `check` — running the invisible connection-check frame.
+ * - `auth` — running the visible authentication (OTP) frame.
+ * - `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`.
+ * - `submit` — submitting the KYC-required check.
+ * - `done` — flow complete; see `kycRequiredByProduct` / `sumsub`. 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 session is
+ * created.
+ */
+export type KycDisclaimer = {
+    id: string;
+    display_name: string;
+    url: string;
+};
+/**
+ * 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":"AAAA;;;;;;GAMG;AAEH;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,MAAM,CAAC;AAE1C;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,SAAS,CAAC;AAElC;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,QAAQ,GAChB,MAAM,GACN,OAAO,GACP,SAAS,GACT,OAAO,GACP,MAAM,GACN,MAAM,GACN,QAAQ,GACR,MAAM,GACN,OAAO,CAAC;AAEZ;;;;;;;;;;GAUG;AACH,MAAM,MAAM,eAAe,GACvB,MAAM,GACN,iBAAiB,GACjB,eAAe,GACf,WAAW,GACX,YAAY,GACZ,SAAS,GACT,UAAU,GACV,QAAQ,GACR,kBAAkB,CAAC;AAEvB;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B;;;;OAIG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB,6DAA6D;IAC7D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,wEAAwE;IACxE,cAAc,EAAE,MAAM,CAAC;IACvB,+BAA+B;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,oDAAoD;IACpD,MAAM,EAAE,MAAM,CAAC;IACf,kCAAkC;IAClC,YAAY,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,EAAE,EAAE,MAAM,CAAC;IAGX,YAAY,EAAE,MAAM,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;CACb,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC;;OAEG;IACH,oBAAoB,EAAE,MAAM,CAAC;IAE7B;;;OAGG;IACH,iBAAiB,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IAEzC;;OAEG;IACH,cAAc,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IAEjE;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B;;;OAGG;IACH,WAAW,IAAI,OAAO,CAAC;IAEvB;;OAEG;IACH,MAAM,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACzE,CAAC"}

package/dist/types.mjs

@@ -0,0 +1,9 @@
+/**
+ * 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.
+ */
+export {};
+//# 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 and card can share one controller.\n */\nexport type KycProduct = 'ramps' | 'card';\n\n/**\n * Identity vendors supported behind the KYC surface.\n */\nexport type KycVendor = 'moonpay';\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.\n * - `check` — running the invisible connection-check frame.\n * - `auth` — running the visible authentication (OTP) frame.\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`.\n * - `submit` — submitting the KYC-required check.\n * - `done` — flow complete; see `kycRequiredByProduct` / `sumsub`. When KYC is\n *   required, the document-verification sub-flow is 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 session is\n * created.\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 * 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.cts

@@ -0,0 +1,69 @@
+/**
+ * Constants for the UKYC client-derived key material and storage-authorization
+ * layer. See the architecture doc, section "Client-Derived Material".
+ */
+/**
+ * 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";
+/**
+ * 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.
+ */
+export declare const 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).
+ */
+export declare const UKYC_DERIVED_KEY_SIZES: {
+    readonly storageId: 32;
+    readonly dataEncryptionKey: 32;
+    readonly signingKey: 32;
+    readonly relayTunnelKey: 32;
+};
+/**
+ * HKDF `info` labels providing domain separation between the values derived
+ * 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";
+};
+/**
+ * Version bound into every `storage_access_token` payload.
+ */
+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";
+/**
+ * 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";
+/**
+ * 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.
+ */
+export declare const UKYC_STORAGE_ACCESS_TOKEN_AUDIENCES: readonly ["metamask:user-storage:ukyc", "idos:kwil"];
+/**
+ * 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.
+ */
+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.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"}

package/dist/ukyc/constants.d.mts

@@ -0,0 +1,69 @@
+/**
+ * Constants for the UKYC client-derived key material and storage-authorization
+ * layer. See the architecture doc, section "Client-Derived Material".
+ */
+/**
+ * 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";
+/**
+ * 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.
+ */
+export declare const 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).
+ */
+export declare const UKYC_DERIVED_KEY_SIZES: {
+    readonly storageId: 32;
+    readonly dataEncryptionKey: 32;
+    readonly signingKey: 32;
+    readonly relayTunnelKey: 32;
+};
+/**
+ * HKDF `info` labels providing domain separation between the values derived
+ * 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";
+};
+/**
+ * Version bound into every `storage_access_token` payload.
+ */
+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";
+/**
+ * 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";
+/**
+ * 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.
+ */
+export declare const UKYC_STORAGE_ACCESS_TOKEN_AUDIENCES: readonly ["metamask:user-storage:ukyc", "idos:kwil"];
+/**
+ * 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.
+ */
+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.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.mts","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"}

package/dist/ukyc/constants.mjs

@@ -0,0 +1,72 @@
+/**
+ * Constants for the UKYC client-derived key material and storage-authorization
+ * layer. See the architecture doc, section "Client-Derived Material".
+ */
+/**
+ * Fully-qualified key path for the `local_user_secret` in Encrypted User
+ * Storage.
+ */
+export 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
+ * below.
+ */
+export const 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).
+ */
+export const 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`.
+ */
+export const 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.
+ */
+export 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 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 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
+ * idOS Kwil can each find their own entry.
+ */
+export const UKYC_STORAGE_ACCESS_TOKEN_AUDIENCES = [
+    UKYC_STORAGE_ACCESS_TOKEN_AUDIENCE,
+    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.
+ */
+export 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 const UKYC_JWKS_PATH = '/.well-known/jwks.json';
+//# sourceMappingURL=constants.mjs.map

package/dist/ukyc/constants.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.mjs","sourceRoot":"","sources":["../../src/ukyc/constants.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,wBAAiC,CAAC;AAE7E;;;;GAIG;AACH,MAAM,CAAC,MAAM,iCAAiC,GAAG,EAAE,CAAC;AAEpD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG;IACpC,SAAS,EAAE,EAAE;IACb,iBAAiB,EAAE,EAAE;IACrB,UAAU,EAAE,EAAE;IACd,cAAc,EAAE,EAAE;CACV,CAAC;AAEX;;;GAGG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,SAAS,EAAE,qCAAqC;IAChD,iBAAiB,EAAE,8CAA8C;IACjE,UAAU,EAAE,sCAAsC;IAClD,cAAc,EAAE,2CAA2C;CACnD,CAAC;AAEX;;GAEG;AACH,MAAM,CAAC,MAAM,iCAAiC,GAAG,CAAC,CAAC;AAEnD;;;GAGG;AACH,MAAM,CAAC,MAAM,kCAAkC,GAC7C,4BAAqC,CAAC;AAExC;;;GAGG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,WAAoB,CAAC;AAEvD;;;;GAIG;AACH,MAAM,CAAC,MAAM,mCAAmC,GAAG;IACjD,kCAAkC;IAClC,kBAAkB;CACV,CAAC;AAEX;;;;GAIG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,aAAsB,CAAC;AAElE;;;GAGG;AACH,MAAM,CAAC,MAAM,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/deriveClientMaterial.cjs

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encodeClientMaterial = exports.deriveClientMaterial = void 0;
+const utils_1 = require("@metamask/utils");
+const ed25519_1 = require("@noble/curves/ed25519");
+const hkdf_1 = require("@noble/hashes/hkdf");
+const sha2_1 = require("@noble/hashes/sha2");
+const constants_js_1 = require("./constants.cjs");
+const encoding_js_1 = require("../encoding.cjs");
+/**
+ * Derives a single labeled value from `local_user_secret`.
+ *
+ * No salt is used: `local_user_secret` is already a high-entropy
+ * uniformly-random secret, so per-output domain separation comes entirely from
+ * the `info` label.
+ *
+ * @param localUserSecret - The root `local_user_secret` bytes.
+ * @param info - Domain-separation label for this output.
+ * @param length - Desired output length in bytes.
+ * @returns The derived bytes.
+ */
+function deriveLabeled(localUserSecret, info, length) {
+    return (0, hkdf_1.hkdf)(sha2_1.sha256, localUserSecret, undefined, (0, utils_1.stringToBytes)(info), length);
+}
+/**
+ * Derives all UKYC client material from the root `local_user_secret`.
+ *
+ * This is a pure function of `local_user_secret`: the same input always yields
+ * the same outputs, which is what makes `storage_id` and `signing_key` stable
+ * across sessions and devices.
+ *
+ * @param localUserSecret - The `local_user_secret` produced by
+ * `getOrCreateLocalUserSecret`.
+ * @returns The derived {@link UkycClientMaterial}.
+ */
+function deriveClientMaterial(localUserSecret) {
+    const storageId = deriveLabeled(localUserSecret, constants_js_1.UKYC_KDF_INFO.storageId, constants_js_1.UKYC_DERIVED_KEY_SIZES.storageId);
+    const dataEncryptionKey = deriveLabeled(localUserSecret, constants_js_1.UKYC_KDF_INFO.dataEncryptionKey, constants_js_1.UKYC_DERIVED_KEY_SIZES.dataEncryptionKey);
+    const signingKey = deriveLabeled(localUserSecret, constants_js_1.UKYC_KDF_INFO.signingKey, constants_js_1.UKYC_DERIVED_KEY_SIZES.signingKey);
+    const relayTunnelKey = deriveLabeled(localUserSecret, constants_js_1.UKYC_KDF_INFO.relayTunnelKey, constants_js_1.UKYC_DERIVED_KEY_SIZES.relayTunnelKey);
+    const signingPublicKey = ed25519_1.ed25519.getPublicKey(signingKey);
+    return {
+        storageId,
+        dataEncryptionKey,
+        signingKey,
+        signingPublicKey,
+        relayTunnelKey,
+    };
+}
+exports.deriveClientMaterial = deriveClientMaterial;
+/**
+ * Encodes the non-secret client material into the base64url wire shapes used by
+ * the UKYC storage API (`storage_id` and `signing_public_key`).
+ *
+ * @param material - The derived client material.
+ * @returns The base64url-encoded, non-secret fields.
+ */
+function encodeClientMaterial(material) {
+    return {
+        storageId: (0, encoding_js_1.toBase64Url)(material.storageId),
+        signingPublicKey: (0, encoding_js_1.toBase64Url)(material.signingPublicKey),
+    };
+}
+exports.encodeClientMaterial = encodeClientMaterial;
+//# sourceMappingURL=deriveClientMaterial.cjs.map

package/dist/ukyc/deriveClientMaterial.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"deriveClientMaterial.cjs","sourceRoot":"","sources":["../../src/ukyc/deriveClientMaterial.ts"],"names":[],"mappings":";;;AAAA,2CAAgD;AAChD,mDAAgD;AAChD,6CAA0C;AAC1C,6CAA4C;AAE5C,kDAAuE;AACvE,iDAA6C;AAsC7C;;;;;;;;;;;GAWG;AACH,SAAS,aAAa,CACpB,eAA2B,EAC3B,IAAY,EACZ,MAAc;IAEd,OAAO,IAAA,WAAI,EAAC,aAAM,EAAE,eAAe,EAAE,SAAS,EAAE,IAAA,qBAAa,EAAC,IAAI,CAAC,EAAE,MAAM,CAAC,CAAC;AAC/E,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAgB,oBAAoB,CAClC,eAA2B;IAE3B,MAAM,SAAS,GAAG,aAAa,CAC7B,eAAe,EACf,4BAAa,CAAC,SAAS,EACvB,qCAAsB,CAAC,SAAS,CACjC,CAAC;IAEF,MAAM,iBAAiB,GAAG,aAAa,CACrC,eAAe,EACf,4BAAa,CAAC,iBAAiB,EAC/B,qCAAsB,CAAC,iBAAiB,CACzC,CAAC;IAEF,MAAM,UAAU,GAAG,aAAa,CAC9B,eAAe,EACf,4BAAa,CAAC,UAAU,EACxB,qCAAsB,CAAC,UAAU,CAClC,CAAC;IAEF,MAAM,cAAc,GAAG,aAAa,CAClC,eAAe,EACf,4BAAa,CAAC,cAAc,EAC5B,qCAAsB,CAAC,cAAc,CACtC,CAAC;IAEF,MAAM,gBAAgB,GAAG,iBAAO,CAAC,YAAY,CAAC,UAAU,CAAC,CAAC;IAE1D,OAAO;QACL,SAAS;QACT,iBAAiB;QACjB,UAAU;QACV,gBAAgB;QAChB,cAAc;KACf,CAAC;AACJ,CAAC;AApCD,oDAoCC;AAED;;;;;;GAMG;AACH,SAAgB,oBAAoB,CAClC,QAA4B;IAE5B,OAAO;QACL,SAAS,EAAE,IAAA,yBAAW,EAAC,QAAQ,CAAC,SAAS,CAAC;QAC1C,gBAAgB,EAAE,IAAA,yBAAW,EAAC,QAAQ,CAAC,gBAAgB,CAAC;KACzD,CAAC;AACJ,CAAC;AAPD,oDAOC","sourcesContent":["import { stringToBytes } from '@metamask/utils';\nimport { ed25519 } from '@noble/curves/ed25519';\nimport { hkdf } from '@noble/hashes/hkdf';\nimport { sha256 } from '@noble/hashes/sha2';\n\nimport { UKYC_DERIVED_KEY_SIZES, UKYC_KDF_INFO } from './constants.js';\nimport { toBase64Url } from '../encoding.js';\n\n/**\n * Derives UKYC client material from the root `local_user_secret` using\n * HKDF-SHA256 with domain-separated `info` labels — see the architecture doc,\n * section \"Client-Derived Material\".\n */\n\n/**\n * The set of values derived from `local_user_secret`.\n */\nexport type UkycClientMaterial = {\n  /** Opaque lookup key for the encrypted KYC object. */\n  storageId: Uint8Array;\n  /** Symmetric key that encrypts `encrypted_kyc_data` (or wraps per-blob keys). */\n  dataEncryptionKey: Uint8Array;\n  /**\n   * Ed25519 private key used to sign `storage_access_token` capabilities. For\n   * Ed25519 the 32-byte HKDF output *is* the private key. The private half\n   * never leaves the device.\n   */\n  signingKey: Uint8Array;\n  /** Public half of `signingKey`, registered with the object on first write. */\n  signingPublicKey: Uint8Array;\n  /** Key for establishing/authenticating the encrypted tunnel to idOS, if needed. */\n  relayTunnelKey: Uint8Array;\n};\n\n/**\n * The same material with byte fields base64url-encoded, matching the wire\n * shapes in the architecture doc (`storage_id` as an opaque id, public key as a\n * \"base64url public key\"). Secret material is intentionally omitted.\n */\nexport type EncodedUkycClientMaterial = {\n  storageId: string;\n  signingPublicKey: string;\n};\n\n/**\n * Derives a single labeled value from `local_user_secret`.\n *\n * No salt is used: `local_user_secret` is already a high-entropy\n * uniformly-random secret, so per-output domain separation comes entirely from\n * the `info` label.\n *\n * @param localUserSecret - The root `local_user_secret` bytes.\n * @param info - Domain-separation label for this output.\n * @param length - Desired output length in bytes.\n * @returns The derived bytes.\n */\nfunction deriveLabeled(\n  localUserSecret: Uint8Array,\n  info: string,\n  length: number,\n): Uint8Array {\n  return hkdf(sha256, localUserSecret, undefined, stringToBytes(info), length);\n}\n\n/**\n * Derives all UKYC client material from the root `local_user_secret`.\n *\n * This is a pure function of `local_user_secret`: the same input always yields\n * the same outputs, which is what makes `storage_id` and `signing_key` stable\n * across sessions and devices.\n *\n * @param localUserSecret - The `local_user_secret` produced by\n * `getOrCreateLocalUserSecret`.\n * @returns The derived {@link UkycClientMaterial}.\n */\nexport function deriveClientMaterial(\n  localUserSecret: Uint8Array,\n): UkycClientMaterial {\n  const storageId = deriveLabeled(\n    localUserSecret,\n    UKYC_KDF_INFO.storageId,\n    UKYC_DERIVED_KEY_SIZES.storageId,\n  );\n\n  const dataEncryptionKey = deriveLabeled(\n    localUserSecret,\n    UKYC_KDF_INFO.dataEncryptionKey,\n    UKYC_DERIVED_KEY_SIZES.dataEncryptionKey,\n  );\n\n  const signingKey = deriveLabeled(\n    localUserSecret,\n    UKYC_KDF_INFO.signingKey,\n    UKYC_DERIVED_KEY_SIZES.signingKey,\n  );\n\n  const relayTunnelKey = deriveLabeled(\n    localUserSecret,\n    UKYC_KDF_INFO.relayTunnelKey,\n    UKYC_DERIVED_KEY_SIZES.relayTunnelKey,\n  );\n\n  const signingPublicKey = ed25519.getPublicKey(signingKey);\n\n  return {\n    storageId,\n    dataEncryptionKey,\n    signingKey,\n    signingPublicKey,\n    relayTunnelKey,\n  };\n}\n\n/**\n * Encodes the non-secret client material into the base64url wire shapes used by\n * the UKYC storage API (`storage_id` and `signing_public_key`).\n *\n * @param material - The derived client material.\n * @returns The base64url-encoded, non-secret fields.\n */\nexport function encodeClientMaterial(\n  material: UkycClientMaterial,\n): EncodedUkycClientMaterial {\n  return {\n    storageId: toBase64Url(material.storageId),\n    signingPublicKey: toBase64Url(material.signingPublicKey),\n  };\n}\n"]}

package/dist/ukyc/deriveClientMaterial.d.cts

@@ -0,0 +1,54 @@
+/**
+ * Derives UKYC client material from the root `local_user_secret` using
+ * HKDF-SHA256 with domain-separated `info` labels — see the architecture doc,
+ * section "Client-Derived Material".
+ */
+/**
+ * The set of values derived from `local_user_secret`.
+ */
+export type UkycClientMaterial = {
+    /** Opaque lookup key for the encrypted KYC object. */
+    storageId: Uint8Array;
+    /** Symmetric key that encrypts `encrypted_kyc_data` (or wraps per-blob keys). */
+    dataEncryptionKey: Uint8Array;
+    /**
+     * Ed25519 private key used to sign `storage_access_token` capabilities. For
+     * Ed25519 the 32-byte HKDF output *is* the private key. The private half
+     * never leaves the device.
+     */
+    signingKey: Uint8Array;
+    /** Public half of `signingKey`, registered with the object on first write. */
+    signingPublicKey: Uint8Array;
+    /** Key for establishing/authenticating the encrypted tunnel to idOS, if needed. */
+    relayTunnelKey: Uint8Array;
+};
+/**
+ * The same material with byte fields base64url-encoded, matching the wire
+ * shapes in the architecture doc (`storage_id` as an opaque id, public key as a
+ * "base64url public key"). Secret material is intentionally omitted.
+ */
+export type EncodedUkycClientMaterial = {
+    storageId: string;
+    signingPublicKey: string;
+};
+/**
+ * Derives all UKYC client material from the root `local_user_secret`.
+ *
+ * This is a pure function of `local_user_secret`: the same input always yields
+ * the same outputs, which is what makes `storage_id` and `signing_key` stable
+ * across sessions and devices.
+ *
+ * @param localUserSecret - The `local_user_secret` produced by
+ * `getOrCreateLocalUserSecret`.
+ * @returns The derived {@link UkycClientMaterial}.
+ */
+export declare function deriveClientMaterial(localUserSecret: Uint8Array): UkycClientMaterial;
+/**
+ * Encodes the non-secret client material into the base64url wire shapes used by
+ * the UKYC storage API (`storage_id` and `signing_public_key`).
+ *
+ * @param material - The derived client material.
+ * @returns The base64url-encoded, non-secret fields.
+ */
+export declare function encodeClientMaterial(material: UkycClientMaterial): EncodedUkycClientMaterial;
+//# sourceMappingURL=deriveClientMaterial.d.cts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"deriveClientMaterial.d.cts","sourceRoot":"","sources":["../../src/ukyc/deriveClientMaterial.ts"],"names":[],"mappings":"AAQA;;;;GAIG;AAEH;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,sDAAsD;IACtD,SAAS,EAAE,UAAU,CAAC;IACtB,iFAAiF;IACjF,iBAAiB,EAAE,UAAU,CAAC;IAC9B;;;;OAIG;IACH,UAAU,EAAE,UAAU,CAAC;IACvB,8EAA8E;IAC9E,gBAAgB,EAAE,UAAU,CAAC;IAC7B,mFAAmF;IACnF,cAAc,EAAE,UAAU,CAAC;CAC5B,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,yBAAyB,GAAG;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,EAAE,MAAM,CAAC;CAC1B,CAAC;AAsBF;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,eAAe,EAAE,UAAU,GAC1B,kBAAkB,CAkCpB;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,kBAAkB,GAC3B,yBAAyB,CAK3B"}