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

package/dist/ukyc/deriveClientMaterial.d.mts

@@ -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.mts.map

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

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

package/dist/ukyc/deriveClientMaterial.mjs

@@ -0,0 +1,60 @@
+import { stringToBytes } from "@metamask/utils";
+import { ed25519 } from "@noble/curves/ed25519";
+import { hkdf } from "@noble/hashes/hkdf";
+import { sha256 } from "@noble/hashes/sha2";
+import { UKYC_DERIVED_KEY_SIZES, UKYC_KDF_INFO } from "./constants.mjs";
+import { toBase64Url } from "../encoding.mjs";
+/**
+ * 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 hkdf(sha256, localUserSecret, undefined, 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}.
+ */
+export function deriveClientMaterial(localUserSecret) {
+    const storageId = deriveLabeled(localUserSecret, UKYC_KDF_INFO.storageId, UKYC_DERIVED_KEY_SIZES.storageId);
+    const dataEncryptionKey = deriveLabeled(localUserSecret, UKYC_KDF_INFO.dataEncryptionKey, UKYC_DERIVED_KEY_SIZES.dataEncryptionKey);
+    const signingKey = deriveLabeled(localUserSecret, UKYC_KDF_INFO.signingKey, UKYC_DERIVED_KEY_SIZES.signingKey);
+    const relayTunnelKey = deriveLabeled(localUserSecret, UKYC_KDF_INFO.relayTunnelKey, UKYC_DERIVED_KEY_SIZES.relayTunnelKey);
+    const signingPublicKey = ed25519.getPublicKey(signingKey);
+    return {
+        storageId,
+        dataEncryptionKey,
+        signingKey,
+        signingPublicKey,
+        relayTunnelKey,
+    };
+}
+/**
+ * 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 function encodeClientMaterial(material) {
+    return {
+        storageId: toBase64Url(material.storageId),
+        signingPublicKey: toBase64Url(material.signingPublicKey),
+    };
+}
+//# sourceMappingURL=deriveClientMaterial.mjs.map

package/dist/ukyc/deriveClientMaterial.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"deriveClientMaterial.mjs","sourceRoot":"","sources":["../../src/ukyc/deriveClientMaterial.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,wBAAwB;AAChD,OAAO,EAAE,OAAO,EAAE,8BAA8B;AAChD,OAAO,EAAE,IAAI,EAAE,2BAA2B;AAC1C,OAAO,EAAE,MAAM,EAAE,2BAA2B;AAE5C,OAAO,EAAE,sBAAsB,EAAE,aAAa,EAAE,wBAAuB;AACvE,OAAO,EAAE,WAAW,EAAE,wBAAuB;AAsC7C;;;;;;;;;;;GAWG;AACH,SAAS,aAAa,CACpB,eAA2B,EAC3B,IAAY,EACZ,MAAc;IAEd,OAAO,IAAI,CAAC,MAAM,EAAE,eAAe,EAAE,SAAS,EAAE,aAAa,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,CAAC;AAC/E,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,oBAAoB,CAClC,eAA2B;IAE3B,MAAM,SAAS,GAAG,aAAa,CAC7B,eAAe,EACf,aAAa,CAAC,SAAS,EACvB,sBAAsB,CAAC,SAAS,CACjC,CAAC;IAEF,MAAM,iBAAiB,GAAG,aAAa,CACrC,eAAe,EACf,aAAa,CAAC,iBAAiB,EAC/B,sBAAsB,CAAC,iBAAiB,CACzC,CAAC;IAEF,MAAM,UAAU,GAAG,aAAa,CAC9B,eAAe,EACf,aAAa,CAAC,UAAU,EACxB,sBAAsB,CAAC,UAAU,CAClC,CAAC;IAEF,MAAM,cAAc,GAAG,aAAa,CAClC,eAAe,EACf,aAAa,CAAC,cAAc,EAC5B,sBAAsB,CAAC,cAAc,CACtC,CAAC;IAEF,MAAM,gBAAgB,GAAG,OAAO,CAAC,YAAY,CAAC,UAAU,CAAC,CAAC;IAE1D,OAAO;QACL,SAAS;QACT,iBAAiB;QACjB,UAAU;QACV,gBAAgB;QAChB,cAAc;KACf,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAClC,QAA4B;IAE5B,OAAO;QACL,SAAS,EAAE,WAAW,CAAC,QAAQ,CAAC,SAAS,CAAC;QAC1C,gBAAgB,EAAE,WAAW,CAAC,QAAQ,CAAC,gBAAgB,CAAC;KACzD,CAAC;AACJ,CAAC","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/jwtChain.cjs

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyJwtChain = void 0;
+const utils_1 = require("@metamask/utils");
+const ed25519_1 = require("@noble/curves/ed25519");
+const encoding_js_1 = require("../encoding.cjs");
+/**
+ * Decodes a base64url JWT segment into a parsed JSON object.
+ *
+ * @param segment - The base64url-encoded segment.
+ * @param label - Human-readable segment name for error messages.
+ * @returns The parsed JSON object.
+ */
+function decodeJsonSegment(segment, label) {
+    try {
+        return JSON.parse((0, utils_1.bytesToString)((0, encoding_js_1.base64UrlToBytes)(segment)));
+    }
+    catch (error) {
+        throw new Error(`UKYC: failed to decode jwtChain ${label}: ${String(error)}`);
+    }
+}
+/**
+ * Verifies `jwtChain` against `keys`: matches the JWT header `kid` to a
+ * published Ed25519 signing key and checks the EdDSA signature over the
+ * `header.payload` input. Returns the decoded, verified payload.
+ *
+ * @param keys - The JWKS keys published by the Fractal encryption service.
+ * @param jwtChain - The compact-serialized EdDSA JWT from `getWrappingKey`.
+ * @returns The verified JWT payload.
+ */
+function verifyJwtChain(keys, jwtChain) {
+    const [headerSegment, payloadSegment, signatureSegment] = jwtChain.split('.');
+    if (!headerSegment || !payloadSegment || !signatureSegment) {
+        throw new Error('UKYC: jwtChain is not a well-formed JWT (expected 3 segments).');
+    }
+    const header = decodeJsonSegment(headerSegment, 'header');
+    if (header.alg !== 'EdDSA') {
+        throw new Error(`UKYC: unsupported jwtChain alg "${String(header.alg)}" (expected EdDSA).`);
+    }
+    const jwk = keys.find((key) => key.kid === header.kid);
+    if (!jwk) {
+        throw new Error(`UKYC: no JWKS key matches jwtChain kid "${String(header.kid)}".`);
+    }
+    if (jwk.kty !== 'OKP' || jwk.crv !== 'Ed25519') {
+        throw new Error(`UKYC: JWKS key ${jwk.kid} is not an Ed25519 OKP key (kty=${jwk.kty}, crv=${jwk.crv}).`);
+    }
+    const isValid = ed25519_1.ed25519.verify((0, encoding_js_1.base64UrlToBytes)(signatureSegment), new TextEncoder().encode(`${headerSegment}.${payloadSegment}`), (0, encoding_js_1.base64UrlToBytes)(jwk.x));
+    if (!isValid) {
+        throw new Error('UKYC: jwtChain signature verification failed against JWKS.');
+    }
+    return decodeJsonSegment(payloadSegment, 'payload');
+}
+exports.verifyJwtChain = verifyJwtChain;
+//# sourceMappingURL=jwtChain.cjs.map

package/dist/ukyc/jwtChain.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"jwtChain.cjs","sourceRoot":"","sources":["../../src/ukyc/jwtChain.ts"],"names":[],"mappings":";;;AAAA,2CAAgD;AAChD,mDAAgD;AAEhD,iDAAkD;AA0ClD;;;;;;GAMG;AACH,SAAS,iBAAiB,CAAO,OAAe,EAAE,KAAa;IAC7D,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,IAAA,qBAAa,EAAC,IAAA,8BAAgB,EAAC,OAAO,CAAC,CAAC,CAAS,CAAC;IACtE,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CACb,mCAAmC,KAAK,KAAK,MAAM,CAAC,KAAK,CAAC,EAAE,CAC7D,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,SAAgB,cAAc,CAAC,IAAW,EAAE,QAAgB;IAC1D,MAAM,CAAC,aAAa,EAAE,cAAc,EAAE,gBAAgB,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC9E,IAAI,CAAC,aAAa,IAAI,CAAC,cAAc,IAAI,CAAC,gBAAgB,EAAE,CAAC;QAC3D,MAAM,IAAI,KAAK,CACb,gEAAgE,CACjE,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,iBAAiB,CAAY,aAAa,EAAE,QAAQ,CAAC,CAAC;IACrE,IAAI,MAAM,CAAC,GAAG,KAAK,OAAO,EAAE,CAAC;QAC3B,MAAM,IAAI,KAAK,CACb,mCAAmC,MAAM,CACvC,MAAM,CAAC,GAAG,CACX,qBAAqB,CACvB,CAAC;IACJ,CAAC;IAED,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,GAAG,KAAK,MAAM,CAAC,GAAG,CAAC,CAAC;IACvD,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,MAAM,IAAI,KAAK,CACb,2CAA2C,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAClE,CAAC;IACJ,CAAC;IACD,IAAI,GAAG,CAAC,GAAG,KAAK,KAAK,IAAI,GAAG,CAAC,GAAG,KAAK,SAAS,EAAE,CAAC;QAC/C,MAAM,IAAI,KAAK,CACb,kBAAkB,GAAG,CAAC,GAAG,mCAAmC,GAAG,CAAC,GAAG,SAAS,GAAG,CAAC,GAAG,IAAI,CACxF,CAAC;IACJ,CAAC;IAED,MAAM,OAAO,GAAG,iBAAO,CAAC,MAAM,CAC5B,IAAA,8BAAgB,EAAC,gBAAgB,CAAC,EAClC,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,GAAG,aAAa,IAAI,cAAc,EAAE,CAAC,EAC9D,IAAA,8BAAgB,EAAC,GAAG,CAAC,CAAC,CAAC,CACxB,CAAC;IACF,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CACb,4DAA4D,CAC7D,CAAC;IACJ,CAAC;IAED,OAAO,iBAAiB,CAAkB,cAAc,EAAE,SAAS,CAAC,CAAC;AACvE,CAAC;AAzCD,wCAyCC","sourcesContent":["import { bytesToString } from '@metamask/utils';\nimport { ed25519 } from '@noble/curves/ed25519';\n\nimport { base64UrlToBytes } from '../encoding.js';\n\n/**\n * Verifies the `jwtChain` returned by the Fractal encryption service against\n * its published JWKS.\n *\n * The signature check is done with `@noble/curves` (rather than WebCrypto\n * `subtle`) because not every MetaMask runtime exposes a `subtle`\n * implementation for Ed25519; JWT parsing is a plain base64url/JSON decode, so\n * no `jose` dependency is required.\n */\n\n/**\n * A single Ed25519 (OKP) JSON Web Key from the Fractal JWKS.\n */\nexport type Jwk = {\n  kty: string;\n  crv: string;\n  x: string;\n  kid: string;\n  use?: string;\n  alg?: string;\n};\n\n/**\n * The verified `jwtChain` payload. `sessionServerPublicKeyX` attests the\n * server's X25519 public key so the client can confirm the value returned\n * out-of-band by `getWrappingKey` was not tampered with.\n */\nexport type JwtChainPayload = {\n  sessionServerPublicKeyX: string;\n  nonce: string;\n};\n\n/**\n * The protected header of a compact JWT.\n */\ntype JwtHeader = {\n  alg?: string;\n  kid?: string;\n};\n\n/**\n * Decodes a base64url JWT segment into a parsed JSON object.\n *\n * @param segment - The base64url-encoded segment.\n * @param label - Human-readable segment name for error messages.\n * @returns The parsed JSON object.\n */\nfunction decodeJsonSegment<Type>(segment: string, label: string): Type {\n  try {\n    return JSON.parse(bytesToString(base64UrlToBytes(segment))) as Type;\n  } catch (error) {\n    throw new Error(\n      `UKYC: failed to decode jwtChain ${label}: ${String(error)}`,\n    );\n  }\n}\n\n/**\n * Verifies `jwtChain` against `keys`: matches the JWT header `kid` to a\n * published Ed25519 signing key and checks the EdDSA signature over the\n * `header.payload` input. Returns the decoded, verified payload.\n *\n * @param keys - The JWKS keys published by the Fractal encryption service.\n * @param jwtChain - The compact-serialized EdDSA JWT from `getWrappingKey`.\n * @returns The verified JWT payload.\n */\nexport function verifyJwtChain(keys: Jwk[], jwtChain: string): JwtChainPayload {\n  const [headerSegment, payloadSegment, signatureSegment] = jwtChain.split('.');\n  if (!headerSegment || !payloadSegment || !signatureSegment) {\n    throw new Error(\n      'UKYC: jwtChain is not a well-formed JWT (expected 3 segments).',\n    );\n  }\n\n  const header = decodeJsonSegment<JwtHeader>(headerSegment, 'header');\n  if (header.alg !== 'EdDSA') {\n    throw new Error(\n      `UKYC: unsupported jwtChain alg \"${String(\n        header.alg,\n      )}\" (expected EdDSA).`,\n    );\n  }\n\n  const jwk = keys.find((key) => key.kid === header.kid);\n  if (!jwk) {\n    throw new Error(\n      `UKYC: no JWKS key matches jwtChain kid \"${String(header.kid)}\".`,\n    );\n  }\n  if (jwk.kty !== 'OKP' || jwk.crv !== 'Ed25519') {\n    throw new Error(\n      `UKYC: JWKS key ${jwk.kid} is not an Ed25519 OKP key (kty=${jwk.kty}, crv=${jwk.crv}).`,\n    );\n  }\n\n  const isValid = ed25519.verify(\n    base64UrlToBytes(signatureSegment),\n    new TextEncoder().encode(`${headerSegment}.${payloadSegment}`),\n    base64UrlToBytes(jwk.x),\n  );\n  if (!isValid) {\n    throw new Error(\n      'UKYC: jwtChain signature verification failed against JWKS.',\n    );\n  }\n\n  return decodeJsonSegment<JwtChainPayload>(payloadSegment, 'payload');\n}\n"]}

package/dist/ukyc/jwtChain.d.cts

@@ -0,0 +1,40 @@
+/**
+ * Verifies the `jwtChain` returned by the Fractal encryption service against
+ * its published JWKS.
+ *
+ * The signature check is done with `@noble/curves` (rather than WebCrypto
+ * `subtle`) because not every MetaMask runtime exposes a `subtle`
+ * implementation for Ed25519; JWT parsing is a plain base64url/JSON decode, so
+ * no `jose` dependency is required.
+ */
+/**
+ * A single Ed25519 (OKP) JSON Web Key from the Fractal JWKS.
+ */
+export type Jwk = {
+    kty: string;
+    crv: string;
+    x: string;
+    kid: string;
+    use?: string;
+    alg?: string;
+};
+/**
+ * The verified `jwtChain` payload. `sessionServerPublicKeyX` attests the
+ * server's X25519 public key so the client can confirm the value returned
+ * out-of-band by `getWrappingKey` was not tampered with.
+ */
+export type JwtChainPayload = {
+    sessionServerPublicKeyX: string;
+    nonce: string;
+};
+/**
+ * Verifies `jwtChain` against `keys`: matches the JWT header `kid` to a
+ * published Ed25519 signing key and checks the EdDSA signature over the
+ * `header.payload` input. Returns the decoded, verified payload.
+ *
+ * @param keys - The JWKS keys published by the Fractal encryption service.
+ * @param jwtChain - The compact-serialized EdDSA JWT from `getWrappingKey`.
+ * @returns The verified JWT payload.
+ */
+export declare function verifyJwtChain(keys: Jwk[], jwtChain: string): JwtChainPayload;
+//# sourceMappingURL=jwtChain.d.cts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"jwtChain.d.cts","sourceRoot":"","sources":["../../src/ukyc/jwtChain.ts"],"names":[],"mappings":"AAKA;;;;;;;;GAQG;AAEH;;GAEG;AACH,MAAM,MAAM,GAAG,GAAG;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,CAAC,EAAE,MAAM,CAAC;IACV,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,uBAAuB,EAAE,MAAM,CAAC;IAChC,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AA2BF;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE,QAAQ,EAAE,MAAM,GAAG,eAAe,CAyC7E"}

package/dist/ukyc/jwtChain.d.mts

@@ -0,0 +1,40 @@
+/**
+ * Verifies the `jwtChain` returned by the Fractal encryption service against
+ * its published JWKS.
+ *
+ * The signature check is done with `@noble/curves` (rather than WebCrypto
+ * `subtle`) because not every MetaMask runtime exposes a `subtle`
+ * implementation for Ed25519; JWT parsing is a plain base64url/JSON decode, so
+ * no `jose` dependency is required.
+ */
+/**
+ * A single Ed25519 (OKP) JSON Web Key from the Fractal JWKS.
+ */
+export type Jwk = {
+    kty: string;
+    crv: string;
+    x: string;
+    kid: string;
+    use?: string;
+    alg?: string;
+};
+/**
+ * The verified `jwtChain` payload. `sessionServerPublicKeyX` attests the
+ * server's X25519 public key so the client can confirm the value returned
+ * out-of-band by `getWrappingKey` was not tampered with.
+ */
+export type JwtChainPayload = {
+    sessionServerPublicKeyX: string;
+    nonce: string;
+};
+/**
+ * Verifies `jwtChain` against `keys`: matches the JWT header `kid` to a
+ * published Ed25519 signing key and checks the EdDSA signature over the
+ * `header.payload` input. Returns the decoded, verified payload.
+ *
+ * @param keys - The JWKS keys published by the Fractal encryption service.
+ * @param jwtChain - The compact-serialized EdDSA JWT from `getWrappingKey`.
+ * @returns The verified JWT payload.
+ */
+export declare function verifyJwtChain(keys: Jwk[], jwtChain: string): JwtChainPayload;
+//# sourceMappingURL=jwtChain.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"jwtChain.d.mts","sourceRoot":"","sources":["../../src/ukyc/jwtChain.ts"],"names":[],"mappings":"AAKA;;;;;;;;GAQG;AAEH;;GAEG;AACH,MAAM,MAAM,GAAG,GAAG;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,CAAC,EAAE,MAAM,CAAC;IACV,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,uBAAuB,EAAE,MAAM,CAAC;IAChC,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AA2BF;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE,QAAQ,EAAE,MAAM,GAAG,eAAe,CAyC7E"}

package/dist/ukyc/jwtChain.mjs

@@ -0,0 +1,50 @@
+import { bytesToString } from "@metamask/utils";
+import { ed25519 } from "@noble/curves/ed25519";
+import { base64UrlToBytes } from "../encoding.mjs";
+/**
+ * Decodes a base64url JWT segment into a parsed JSON object.
+ *
+ * @param segment - The base64url-encoded segment.
+ * @param label - Human-readable segment name for error messages.
+ * @returns The parsed JSON object.
+ */
+function decodeJsonSegment(segment, label) {
+    try {
+        return JSON.parse(bytesToString(base64UrlToBytes(segment)));
+    }
+    catch (error) {
+        throw new Error(`UKYC: failed to decode jwtChain ${label}: ${String(error)}`);
+    }
+}
+/**
+ * Verifies `jwtChain` against `keys`: matches the JWT header `kid` to a
+ * published Ed25519 signing key and checks the EdDSA signature over the
+ * `header.payload` input. Returns the decoded, verified payload.
+ *
+ * @param keys - The JWKS keys published by the Fractal encryption service.
+ * @param jwtChain - The compact-serialized EdDSA JWT from `getWrappingKey`.
+ * @returns The verified JWT payload.
+ */
+export function verifyJwtChain(keys, jwtChain) {
+    const [headerSegment, payloadSegment, signatureSegment] = jwtChain.split('.');
+    if (!headerSegment || !payloadSegment || !signatureSegment) {
+        throw new Error('UKYC: jwtChain is not a well-formed JWT (expected 3 segments).');
+    }
+    const header = decodeJsonSegment(headerSegment, 'header');
+    if (header.alg !== 'EdDSA') {
+        throw new Error(`UKYC: unsupported jwtChain alg "${String(header.alg)}" (expected EdDSA).`);
+    }
+    const jwk = keys.find((key) => key.kid === header.kid);
+    if (!jwk) {
+        throw new Error(`UKYC: no JWKS key matches jwtChain kid "${String(header.kid)}".`);
+    }
+    if (jwk.kty !== 'OKP' || jwk.crv !== 'Ed25519') {
+        throw new Error(`UKYC: JWKS key ${jwk.kid} is not an Ed25519 OKP key (kty=${jwk.kty}, crv=${jwk.crv}).`);
+    }
+    const isValid = ed25519.verify(base64UrlToBytes(signatureSegment), new TextEncoder().encode(`${headerSegment}.${payloadSegment}`), base64UrlToBytes(jwk.x));
+    if (!isValid) {
+        throw new Error('UKYC: jwtChain signature verification failed against JWKS.');
+    }
+    return decodeJsonSegment(payloadSegment, 'payload');
+}
+//# sourceMappingURL=jwtChain.mjs.map

package/dist/ukyc/jwtChain.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"jwtChain.mjs","sourceRoot":"","sources":["../../src/ukyc/jwtChain.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,wBAAwB;AAChD,OAAO,EAAE,OAAO,EAAE,8BAA8B;AAEhD,OAAO,EAAE,gBAAgB,EAAE,wBAAuB;AA0ClD;;;;;;GAMG;AACH,SAAS,iBAAiB,CAAO,OAAe,EAAE,KAAa;IAC7D,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,aAAa,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC,CAAS,CAAC;IACtE,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CACb,mCAAmC,KAAK,KAAK,MAAM,CAAC,KAAK,CAAC,EAAE,CAC7D,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAAC,IAAW,EAAE,QAAgB;IAC1D,MAAM,CAAC,aAAa,EAAE,cAAc,EAAE,gBAAgB,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC9E,IAAI,CAAC,aAAa,IAAI,CAAC,cAAc,IAAI,CAAC,gBAAgB,EAAE,CAAC;QAC3D,MAAM,IAAI,KAAK,CACb,gEAAgE,CACjE,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,iBAAiB,CAAY,aAAa,EAAE,QAAQ,CAAC,CAAC;IACrE,IAAI,MAAM,CAAC,GAAG,KAAK,OAAO,EAAE,CAAC;QAC3B,MAAM,IAAI,KAAK,CACb,mCAAmC,MAAM,CACvC,MAAM,CAAC,GAAG,CACX,qBAAqB,CACvB,CAAC;IACJ,CAAC;IAED,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,GAAG,KAAK,MAAM,CAAC,GAAG,CAAC,CAAC;IACvD,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,MAAM,IAAI,KAAK,CACb,2CAA2C,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAClE,CAAC;IACJ,CAAC;IACD,IAAI,GAAG,CAAC,GAAG,KAAK,KAAK,IAAI,GAAG,CAAC,GAAG,KAAK,SAAS,EAAE,CAAC;QAC/C,MAAM,IAAI,KAAK,CACb,kBAAkB,GAAG,CAAC,GAAG,mCAAmC,GAAG,CAAC,GAAG,SAAS,GAAG,CAAC,GAAG,IAAI,CACxF,CAAC;IACJ,CAAC;IAED,MAAM,OAAO,GAAG,OAAO,CAAC,MAAM,CAC5B,gBAAgB,CAAC,gBAAgB,CAAC,EAClC,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,GAAG,aAAa,IAAI,cAAc,EAAE,CAAC,EAC9D,gBAAgB,CAAC,GAAG,CAAC,CAAC,CAAC,CACxB,CAAC;IACF,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CACb,4DAA4D,CAC7D,CAAC;IACJ,CAAC;IAED,OAAO,iBAAiB,CAAkB,cAAc,EAAE,SAAS,CAAC,CAAC;AACvE,CAAC","sourcesContent":["import { bytesToString } from '@metamask/utils';\nimport { ed25519 } from '@noble/curves/ed25519';\n\nimport { base64UrlToBytes } from '../encoding.js';\n\n/**\n * Verifies the `jwtChain` returned by the Fractal encryption service against\n * its published JWKS.\n *\n * The signature check is done with `@noble/curves` (rather than WebCrypto\n * `subtle`) because not every MetaMask runtime exposes a `subtle`\n * implementation for Ed25519; JWT parsing is a plain base64url/JSON decode, so\n * no `jose` dependency is required.\n */\n\n/**\n * A single Ed25519 (OKP) JSON Web Key from the Fractal JWKS.\n */\nexport type Jwk = {\n  kty: string;\n  crv: string;\n  x: string;\n  kid: string;\n  use?: string;\n  alg?: string;\n};\n\n/**\n * The verified `jwtChain` payload. `sessionServerPublicKeyX` attests the\n * server's X25519 public key so the client can confirm the value returned\n * out-of-band by `getWrappingKey` was not tampered with.\n */\nexport type JwtChainPayload = {\n  sessionServerPublicKeyX: string;\n  nonce: string;\n};\n\n/**\n * The protected header of a compact JWT.\n */\ntype JwtHeader = {\n  alg?: string;\n  kid?: string;\n};\n\n/**\n * Decodes a base64url JWT segment into a parsed JSON object.\n *\n * @param segment - The base64url-encoded segment.\n * @param label - Human-readable segment name for error messages.\n * @returns The parsed JSON object.\n */\nfunction decodeJsonSegment<Type>(segment: string, label: string): Type {\n  try {\n    return JSON.parse(bytesToString(base64UrlToBytes(segment))) as Type;\n  } catch (error) {\n    throw new Error(\n      `UKYC: failed to decode jwtChain ${label}: ${String(error)}`,\n    );\n  }\n}\n\n/**\n * Verifies `jwtChain` against `keys`: matches the JWT header `kid` to a\n * published Ed25519 signing key and checks the EdDSA signature over the\n * `header.payload` input. Returns the decoded, verified payload.\n *\n * @param keys - The JWKS keys published by the Fractal encryption service.\n * @param jwtChain - The compact-serialized EdDSA JWT from `getWrappingKey`.\n * @returns The verified JWT payload.\n */\nexport function verifyJwtChain(keys: Jwk[], jwtChain: string): JwtChainPayload {\n  const [headerSegment, payloadSegment, signatureSegment] = jwtChain.split('.');\n  if (!headerSegment || !payloadSegment || !signatureSegment) {\n    throw new Error(\n      'UKYC: jwtChain is not a well-formed JWT (expected 3 segments).',\n    );\n  }\n\n  const header = decodeJsonSegment<JwtHeader>(headerSegment, 'header');\n  if (header.alg !== 'EdDSA') {\n    throw new Error(\n      `UKYC: unsupported jwtChain alg \"${String(\n        header.alg,\n      )}\" (expected EdDSA).`,\n    );\n  }\n\n  const jwk = keys.find((key) => key.kid === header.kid);\n  if (!jwk) {\n    throw new Error(\n      `UKYC: no JWKS key matches jwtChain kid \"${String(header.kid)}\".`,\n    );\n  }\n  if (jwk.kty !== 'OKP' || jwk.crv !== 'Ed25519') {\n    throw new Error(\n      `UKYC: JWKS key ${jwk.kid} is not an Ed25519 OKP key (kty=${jwk.kty}, crv=${jwk.crv}).`,\n    );\n  }\n\n  const isValid = ed25519.verify(\n    base64UrlToBytes(signatureSegment),\n    new TextEncoder().encode(`${headerSegment}.${payloadSegment}`),\n    base64UrlToBytes(jwk.x),\n  );\n  if (!isValid) {\n    throw new Error(\n      'UKYC: jwtChain signature verification failed against JWKS.',\n    );\n  }\n\n  return decodeJsonSegment<JwtChainPayload>(payloadSegment, 'payload');\n}\n"]}

package/dist/ukyc/localUserSecret.cjs

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasLocalUserSecret = exports.getOrCreateLocalUserSecret = exports.loadLocalUserSecret = void 0;
+const utils_1 = require("@metamask/utils");
+const utils_2 = require("@noble/hashes/utils");
+const constants_js_1 = require("./constants.cjs");
+/**
+ * In-flight `getOrCreateLocalUserSecret` calls, keyed by entropy source.
+ * Deduplicates concurrent enrollments in a single client session so we never
+ * generate and persist two competing `local_user_secret`s for the same source.
+ */
+const inFlightCreations = new Map();
+/**
+ * Loads the persisted `local_user_secret` from Encrypted User Storage, if one
+ * exists.
+ *
+ * @param store - The Encrypted User Storage adapter.
+ * @param entropySourceId - Optional HD keyring entropy source id, used to scope
+ * the secret to a specific SRP in multi-SRP wallets. Defaults to the primary SRP.
+ * @returns The decoded `local_user_secret` bytes, or `null` if none has been
+ * enrolled.
+ */
+async function loadLocalUserSecret(store, entropySourceId) {
+    const stored = await store.get(constants_js_1.UKYC_LOCAL_USER_SECRET_PATH, entropySourceId);
+    if (!stored) {
+        return null;
+    }
+    const localUserSecret = (0, utils_1.base64ToBytes)(stored);
+    if (localUserSecret.length !== constants_js_1.UKYC_LOCAL_USER_SECRET_SIZE_BYTES) {
+        throw new Error(`UKYC: stored local_user_secret has unexpected length ${localUserSecret.length}, expected ${constants_js_1.UKYC_LOCAL_USER_SECRET_SIZE_BYTES}.`);
+    }
+    return localUserSecret;
+}
+exports.loadLocalUserSecret = loadLocalUserSecret;
+/**
+ * Persists a freshly generated `local_user_secret` to Encrypted User Storage.
+ *
+ * @param store - The Encrypted User Storage adapter.
+ * @param localUserSecret - The `local_user_secret` bytes to persist.
+ * @param entropySourceId - Optional HD keyring entropy source id.
+ */
+async function persistLocalUserSecret(store, localUserSecret, entropySourceId) {
+    await store.set(constants_js_1.UKYC_LOCAL_USER_SECRET_PATH, (0, utils_1.bytesToBase64)(localUserSecret), entropySourceId);
+}
+/**
+ * Creates the UKYC `local_user_secret` if it does not already exist, otherwise
+ * loads the existing one. This is the single entry point used on UKYC
+ * enrollment.
+ *
+ * The operation is idempotent and safe against concurrent callers in the same
+ * session: repeated or parallel calls resolve to the same `local_user_secret`
+ * and never generate more than one secret for a given entropy source.
+ *
+ * @param store - The Encrypted User Storage adapter.
+ * @param entropySourceId - Optional HD keyring entropy source id, used to scope
+ * the secret to a specific SRP in multi-SRP wallets. Defaults to the primary SRP.
+ * @returns The `local_user_secret` bytes (existing or newly created).
+ */
+async function getOrCreateLocalUserSecret(store, entropySourceId) {
+    const cacheKey = entropySourceId ?? '';
+    const pending = inFlightCreations.get(cacheKey);
+    if (pending) {
+        return pending;
+    }
+    const creation = (async () => {
+        const existing = await loadLocalUserSecret(store, entropySourceId);
+        if (existing) {
+            return existing;
+        }
+        const localUserSecret = (0, utils_2.randomBytes)(constants_js_1.UKYC_LOCAL_USER_SECRET_SIZE_BYTES);
+        await persistLocalUserSecret(store, localUserSecret, entropySourceId);
+        // Re-read after persisting so that all callers converge on whatever value
+        // actually landed in storage (defends against a competing write that may
+        // have won the race, e.g. from another device syncing the same feature).
+        return ((await loadLocalUserSecret(store, entropySourceId)) ?? localUserSecret);
+    })();
+    inFlightCreations.set(cacheKey, creation);
+    try {
+        return await creation;
+    }
+    finally {
+        inFlightCreations.delete(cacheKey);
+    }
+}
+exports.getOrCreateLocalUserSecret = getOrCreateLocalUserSecret;
+/**
+ * Whether a `local_user_secret` has already been enrolled for the given entropy
+ * source.
+ *
+ * @param store - The Encrypted User Storage adapter.
+ * @param entropySourceId - Optional HD keyring entropy source id.
+ * @returns `true` if a `local_user_secret` exists in Encrypted User Storage.
+ */
+async function hasLocalUserSecret(store, entropySourceId) {
+    return (await loadLocalUserSecret(store, entropySourceId)) !== null;
+}
+exports.hasLocalUserSecret = hasLocalUserSecret;
+//# sourceMappingURL=localUserSecret.cjs.map

package/dist/ukyc/localUserSecret.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"localUserSecret.cjs","sourceRoot":"","sources":["../../src/ukyc/localUserSecret.ts"],"names":[],"mappings":";;;AAAA,2CAA+D;AAC/D,+CAAkD;AAElD,kDAGwB;AAiCxB;;;;GAIG;AACH,MAAM,iBAAiB,GAAG,IAAI,GAAG,EAA+B,CAAC;AAEjE;;;;;;;;;GASG;AACI,KAAK,UAAU,mBAAmB,CACvC,KAA+B,EAC/B,eAAwB;IAExB,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,0CAA2B,EAAE,eAAe,CAAC,CAAC;IAE7E,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,eAAe,GAAG,IAAA,qBAAa,EAAC,MAAM,CAAC,CAAC;IAE9C,IAAI,eAAe,CAAC,MAAM,KAAK,gDAAiC,EAAE,CAAC;QACjE,MAAM,IAAI,KAAK,CACb,wDAAwD,eAAe,CAAC,MAAM,cAAc,gDAAiC,GAAG,CACjI,CAAC;IACJ,CAAC;IAED,OAAO,eAAe,CAAC;AACzB,CAAC;AAnBD,kDAmBC;AAED;;;;;;GAMG;AACH,KAAK,UAAU,sBAAsB,CACnC,KAA+B,EAC/B,eAA2B,EAC3B,eAAwB;IAExB,MAAM,KAAK,CAAC,GAAG,CACb,0CAA2B,EAC3B,IAAA,qBAAa,EAAC,eAAe,CAAC,EAC9B,eAAe,CAChB,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;GAaG;AACI,KAAK,UAAU,0BAA0B,CAC9C,KAA+B,EAC/B,eAAwB;IAExB,MAAM,QAAQ,GAAG,eAAe,IAAI,EAAE,CAAC;IAEvC,MAAM,OAAO,GAAG,iBAAiB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAChD,IAAI,OAAO,EAAE,CAAC;QACZ,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,MAAM,QAAQ,GAAG,CAAC,KAAK,IAAyB,EAAE;QAChD,MAAM,QAAQ,GAAG,MAAM,mBAAmB,CAAC,KAAK,EAAE,eAAe,CAAC,CAAC;QACnE,IAAI,QAAQ,EAAE,CAAC;YACb,OAAO,QAAQ,CAAC;QAClB,CAAC;QAED,MAAM,eAAe,GAAG,IAAA,mBAAW,EAAC,gDAAiC,CAAC,CAAC;QACvE,MAAM,sBAAsB,CAAC,KAAK,EAAE,eAAe,EAAE,eAAe,CAAC,CAAC;QAEtE,0EAA0E;QAC1E,yEAAyE;QACzE,yEAAyE;QACzE,OAAO,CACL,CAAC,MAAM,mBAAmB,CAAC,KAAK,EAAE,eAAe,CAAC,CAAC,IAAI,eAAe,CACvE,CAAC;IACJ,CAAC,CAAC,EAAE,CAAC;IAEL,iBAAiB,CAAC,GAAG,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IAE1C,IAAI,CAAC;QACH,OAAO,MAAM,QAAQ,CAAC;IACxB,CAAC;YAAS,CAAC;QACT,iBAAiB,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IACrC,CAAC;AACH,CAAC;AAnCD,gEAmCC;AAED;;;;;;;GAOG;AACI,KAAK,UAAU,kBAAkB,CACtC,KAA+B,EAC/B,eAAwB;IAExB,OAAO,CAAC,MAAM,mBAAmB,CAAC,KAAK,EAAE,eAAe,CAAC,CAAC,KAAK,IAAI,CAAC;AACtE,CAAC;AALD,gDAKC","sourcesContent":["import { base64ToBytes, bytesToBase64 } from '@metamask/utils';\nimport { randomBytes } from '@noble/hashes/utils';\n\nimport {\n  UKYC_LOCAL_USER_SECRET_PATH,\n  UKYC_LOCAL_USER_SECRET_SIZE_BYTES,\n} from './constants.js';\n\n/**\n * Orchestrates creation and loading of the UKYC `local_user_secret`.\n *\n * The `local_user_secret` is the root secret for all UKYC client-derived\n * material. It is generated once, on first enrollment, and persisted to\n * MetaMask Encrypted User Storage. It is never transmitted off the device, not\n * even to the idOS Relay. Every subsequent value (`storage_id`,\n * `data_encryption_key`, `signing_key`, `relay_tunnel_key`) is derived from it\n * via HKDF — see `deriveClientMaterial`.\n *\n * This module is platform-agnostic: the Encrypted User Storage backing is\n * injected as a {@link UkycLocalUserSecretStore} so the controller (which owns\n * the messenger) supplies the concrete `UserStorageController` calls.\n */\n\n/**\n * The Encrypted User Storage operations this module needs. On MetaMask clients\n * these are backed by `UserStorageController:performGetStorage` /\n * `performSetStorage`.\n */\nexport type UkycLocalUserSecretStore = {\n  /**\n   * Reads the base64 string stored at `path`, or `null` if none exists.\n   */\n  get: (path: string, entropySourceId?: string) => Promise<string | null>;\n  /**\n   * Writes the base64 string `value` at `path`.\n   */\n  set: (path: string, value: string, entropySourceId?: string) => Promise<void>;\n};\n\n/**\n * In-flight `getOrCreateLocalUserSecret` calls, keyed by entropy source.\n * Deduplicates concurrent enrollments in a single client session so we never\n * generate and persist two competing `local_user_secret`s for the same source.\n */\nconst inFlightCreations = new Map<string, Promise<Uint8Array>>();\n\n/**\n * Loads the persisted `local_user_secret` from Encrypted User Storage, if one\n * exists.\n *\n * @param store - The Encrypted User Storage adapter.\n * @param entropySourceId - Optional HD keyring entropy source id, used to scope\n * the secret to a specific SRP in multi-SRP wallets. Defaults to the primary SRP.\n * @returns The decoded `local_user_secret` bytes, or `null` if none has been\n * enrolled.\n */\nexport async function loadLocalUserSecret(\n  store: UkycLocalUserSecretStore,\n  entropySourceId?: string,\n): Promise<Uint8Array | null> {\n  const stored = await store.get(UKYC_LOCAL_USER_SECRET_PATH, entropySourceId);\n\n  if (!stored) {\n    return null;\n  }\n\n  const localUserSecret = base64ToBytes(stored);\n\n  if (localUserSecret.length !== UKYC_LOCAL_USER_SECRET_SIZE_BYTES) {\n    throw new Error(\n      `UKYC: stored local_user_secret has unexpected length ${localUserSecret.length}, expected ${UKYC_LOCAL_USER_SECRET_SIZE_BYTES}.`,\n    );\n  }\n\n  return localUserSecret;\n}\n\n/**\n * Persists a freshly generated `local_user_secret` to Encrypted User Storage.\n *\n * @param store - The Encrypted User Storage adapter.\n * @param localUserSecret - The `local_user_secret` bytes to persist.\n * @param entropySourceId - Optional HD keyring entropy source id.\n */\nasync function persistLocalUserSecret(\n  store: UkycLocalUserSecretStore,\n  localUserSecret: Uint8Array,\n  entropySourceId?: string,\n): Promise<void> {\n  await store.set(\n    UKYC_LOCAL_USER_SECRET_PATH,\n    bytesToBase64(localUserSecret),\n    entropySourceId,\n  );\n}\n\n/**\n * Creates the UKYC `local_user_secret` if it does not already exist, otherwise\n * loads the existing one. This is the single entry point used on UKYC\n * enrollment.\n *\n * The operation is idempotent and safe against concurrent callers in the same\n * session: repeated or parallel calls resolve to the same `local_user_secret`\n * and never generate more than one secret for a given entropy source.\n *\n * @param store - The Encrypted User Storage adapter.\n * @param entropySourceId - Optional HD keyring entropy source id, used to scope\n * the secret to a specific SRP in multi-SRP wallets. Defaults to the primary SRP.\n * @returns The `local_user_secret` bytes (existing or newly created).\n */\nexport async function getOrCreateLocalUserSecret(\n  store: UkycLocalUserSecretStore,\n  entropySourceId?: string,\n): Promise<Uint8Array> {\n  const cacheKey = entropySourceId ?? '';\n\n  const pending = inFlightCreations.get(cacheKey);\n  if (pending) {\n    return pending;\n  }\n\n  const creation = (async (): Promise<Uint8Array> => {\n    const existing = await loadLocalUserSecret(store, entropySourceId);\n    if (existing) {\n      return existing;\n    }\n\n    const localUserSecret = randomBytes(UKYC_LOCAL_USER_SECRET_SIZE_BYTES);\n    await persistLocalUserSecret(store, localUserSecret, entropySourceId);\n\n    // Re-read after persisting so that all callers converge on whatever value\n    // actually landed in storage (defends against a competing write that may\n    // have won the race, e.g. from another device syncing the same feature).\n    return (\n      (await loadLocalUserSecret(store, entropySourceId)) ?? localUserSecret\n    );\n  })();\n\n  inFlightCreations.set(cacheKey, creation);\n\n  try {\n    return await creation;\n  } finally {\n    inFlightCreations.delete(cacheKey);\n  }\n}\n\n/**\n * Whether a `local_user_secret` has already been enrolled for the given entropy\n * source.\n *\n * @param store - The Encrypted User Storage adapter.\n * @param entropySourceId - Optional HD keyring entropy source id.\n * @returns `true` if a `local_user_secret` exists in Encrypted User Storage.\n */\nexport async function hasLocalUserSecret(\n  store: UkycLocalUserSecretStore,\n  entropySourceId?: string,\n): Promise<boolean> {\n  return (await loadLocalUserSecret(store, entropySourceId)) !== null;\n}\n"]}

package/dist/ukyc/localUserSecret.d.cts

@@ -0,0 +1,65 @@
+/**
+ * Orchestrates creation and loading of the UKYC `local_user_secret`.
+ *
+ * The `local_user_secret` is the root secret for all UKYC client-derived
+ * material. It is generated once, on first enrollment, and persisted to
+ * MetaMask Encrypted User Storage. It is never transmitted off the device, not
+ * even to the idOS Relay. Every subsequent value (`storage_id`,
+ * `data_encryption_key`, `signing_key`, `relay_tunnel_key`) is derived from it
+ * via HKDF — see `deriveClientMaterial`.
+ *
+ * This module is platform-agnostic: the Encrypted User Storage backing is
+ * injected as a {@link UkycLocalUserSecretStore} so the controller (which owns
+ * the messenger) supplies the concrete `UserStorageController` calls.
+ */
+/**
+ * The Encrypted User Storage operations this module needs. On MetaMask clients
+ * these are backed by `UserStorageController:performGetStorage` /
+ * `performSetStorage`.
+ */
+export type UkycLocalUserSecretStore = {
+    /**
+     * Reads the base64 string stored at `path`, or `null` if none exists.
+     */
+    get: (path: string, entropySourceId?: string) => Promise<string | null>;
+    /**
+     * Writes the base64 string `value` at `path`.
+     */
+    set: (path: string, value: string, entropySourceId?: string) => Promise<void>;
+};
+/**
+ * Loads the persisted `local_user_secret` from Encrypted User Storage, if one
+ * exists.
+ *
+ * @param store - The Encrypted User Storage adapter.
+ * @param entropySourceId - Optional HD keyring entropy source id, used to scope
+ * the secret to a specific SRP in multi-SRP wallets. Defaults to the primary SRP.
+ * @returns The decoded `local_user_secret` bytes, or `null` if none has been
+ * enrolled.
+ */
+export declare function loadLocalUserSecret(store: UkycLocalUserSecretStore, entropySourceId?: string): Promise<Uint8Array | null>;
+/**
+ * Creates the UKYC `local_user_secret` if it does not already exist, otherwise
+ * loads the existing one. This is the single entry point used on UKYC
+ * enrollment.
+ *
+ * The operation is idempotent and safe against concurrent callers in the same
+ * session: repeated or parallel calls resolve to the same `local_user_secret`
+ * and never generate more than one secret for a given entropy source.
+ *
+ * @param store - The Encrypted User Storage adapter.
+ * @param entropySourceId - Optional HD keyring entropy source id, used to scope
+ * the secret to a specific SRP in multi-SRP wallets. Defaults to the primary SRP.
+ * @returns The `local_user_secret` bytes (existing or newly created).
+ */
+export declare function getOrCreateLocalUserSecret(store: UkycLocalUserSecretStore, entropySourceId?: string): Promise<Uint8Array>;
+/**
+ * Whether a `local_user_secret` has already been enrolled for the given entropy
+ * source.
+ *
+ * @param store - The Encrypted User Storage adapter.
+ * @param entropySourceId - Optional HD keyring entropy source id.
+ * @returns `true` if a `local_user_secret` exists in Encrypted User Storage.
+ */
+export declare function hasLocalUserSecret(store: UkycLocalUserSecretStore, entropySourceId?: string): Promise<boolean>;
+//# sourceMappingURL=localUserSecret.d.cts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"localUserSecret.d.cts","sourceRoot":"","sources":["../../src/ukyc/localUserSecret.ts"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;GAaG;AAEH;;;;GAIG;AACH,MAAM,MAAM,wBAAwB,GAAG;IACrC;;OAEG;IACH,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,eAAe,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACxE;;OAEG;IACH,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,eAAe,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/E,CAAC;AASF;;;;;;;;;GASG;AACH,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,wBAAwB,EAC/B,eAAe,CAAC,EAAE,MAAM,GACvB,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAgB5B;AAqBD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,0BAA0B,CAC9C,KAAK,EAAE,wBAAwB,EAC/B,eAAe,CAAC,EAAE,MAAM,GACvB,OAAO,CAAC,UAAU,CAAC,CAgCrB;AAED;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CACtC,KAAK,EAAE,wBAAwB,EAC/B,eAAe,CAAC,EAAE,MAAM,GACvB,OAAO,CAAC,OAAO,CAAC,CAElB"}

package/dist/ukyc/localUserSecret.d.mts

@@ -0,0 +1,65 @@
+/**
+ * Orchestrates creation and loading of the UKYC `local_user_secret`.
+ *
+ * The `local_user_secret` is the root secret for all UKYC client-derived
+ * material. It is generated once, on first enrollment, and persisted to
+ * MetaMask Encrypted User Storage. It is never transmitted off the device, not
+ * even to the idOS Relay. Every subsequent value (`storage_id`,
+ * `data_encryption_key`, `signing_key`, `relay_tunnel_key`) is derived from it
+ * via HKDF — see `deriveClientMaterial`.
+ *
+ * This module is platform-agnostic: the Encrypted User Storage backing is
+ * injected as a {@link UkycLocalUserSecretStore} so the controller (which owns
+ * the messenger) supplies the concrete `UserStorageController` calls.
+ */
+/**
+ * The Encrypted User Storage operations this module needs. On MetaMask clients
+ * these are backed by `UserStorageController:performGetStorage` /
+ * `performSetStorage`.
+ */
+export type UkycLocalUserSecretStore = {
+    /**
+     * Reads the base64 string stored at `path`, or `null` if none exists.
+     */
+    get: (path: string, entropySourceId?: string) => Promise<string | null>;
+    /**
+     * Writes the base64 string `value` at `path`.
+     */
+    set: (path: string, value: string, entropySourceId?: string) => Promise<void>;
+};
+/**
+ * Loads the persisted `local_user_secret` from Encrypted User Storage, if one
+ * exists.
+ *
+ * @param store - The Encrypted User Storage adapter.
+ * @param entropySourceId - Optional HD keyring entropy source id, used to scope
+ * the secret to a specific SRP in multi-SRP wallets. Defaults to the primary SRP.
+ * @returns The decoded `local_user_secret` bytes, or `null` if none has been
+ * enrolled.
+ */
+export declare function loadLocalUserSecret(store: UkycLocalUserSecretStore, entropySourceId?: string): Promise<Uint8Array | null>;
+/**
+ * Creates the UKYC `local_user_secret` if it does not already exist, otherwise
+ * loads the existing one. This is the single entry point used on UKYC
+ * enrollment.
+ *
+ * The operation is idempotent and safe against concurrent callers in the same
+ * session: repeated or parallel calls resolve to the same `local_user_secret`
+ * and never generate more than one secret for a given entropy source.
+ *
+ * @param store - The Encrypted User Storage adapter.
+ * @param entropySourceId - Optional HD keyring entropy source id, used to scope
+ * the secret to a specific SRP in multi-SRP wallets. Defaults to the primary SRP.
+ * @returns The `local_user_secret` bytes (existing or newly created).
+ */
+export declare function getOrCreateLocalUserSecret(store: UkycLocalUserSecretStore, entropySourceId?: string): Promise<Uint8Array>;
+/**
+ * Whether a `local_user_secret` has already been enrolled for the given entropy
+ * source.
+ *
+ * @param store - The Encrypted User Storage adapter.
+ * @param entropySourceId - Optional HD keyring entropy source id.
+ * @returns `true` if a `local_user_secret` exists in Encrypted User Storage.
+ */
+export declare function hasLocalUserSecret(store: UkycLocalUserSecretStore, entropySourceId?: string): Promise<boolean>;
+//# sourceMappingURL=localUserSecret.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"localUserSecret.d.mts","sourceRoot":"","sources":["../../src/ukyc/localUserSecret.ts"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;GAaG;AAEH;;;;GAIG;AACH,MAAM,MAAM,wBAAwB,GAAG;IACrC;;OAEG;IACH,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,eAAe,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACxE;;OAEG;IACH,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,eAAe,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/E,CAAC;AASF;;;;;;;;;GASG;AACH,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,wBAAwB,EAC/B,eAAe,CAAC,EAAE,MAAM,GACvB,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAgB5B;AAqBD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,0BAA0B,CAC9C,KAAK,EAAE,wBAAwB,EAC/B,eAAe,CAAC,EAAE,MAAM,GACvB,OAAO,CAAC,UAAU,CAAC,CAgCrB;AAED;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CACtC,KAAK,EAAE,wBAAwB,EAC/B,eAAe,CAAC,EAAE,MAAM,GACvB,OAAO,CAAC,OAAO,CAAC,CAElB"}