@metamask-previews/mfa-recovery-controller 0.0.0-preview-a2f6118d2

package/dist/crypto.js

@@ -0,0 +1,268 @@
+import { base64ToBytes, bytesToBase64, bytesToHex, concatBytes, hexToBytes, stringToBytes, } from '@metamask/utils';
+import { chacha20poly1305 } from '@noble/ciphers/chacha';
+import { p256 } from '@noble/curves/nist';
+import { hkdf } from '@noble/hashes/hkdf';
+import { sha256 as sha256Sync } from '@noble/hashes/sha2';
+const WRAP_INFO = new TextEncoder().encode('escrow-wrap-v1');
+const CHACHA_KEY_LEN = 32;
+const CHACHA_NONCE_LEN = 12;
+/**
+ * Recursively sorts object keys so hashes are independent of property order.
+ *
+ * @param value - JSON-compatible value.
+ * @returns A canonical JSON string.
+ */
+export function canonicalize(value) {
+    return JSON.stringify(sortKeys(value));
+}
+/**
+ * SHA-256 of the canonical JSON form of `value`, as a 0x-prefixed hex string.
+ *
+ * @param value - Value to hash.
+ * @returns Hex digest.
+ */
+export function hash(value) {
+    return bytesToHex(sha256Sync(stringToBytes(canonicalize(value))));
+}
+/**
+ * Canonical identifier list bound into AuthController `identifiersHash`.
+ *
+ * @param identifiers - Identifier set.
+ * @returns Sorted identifier records including verifier material.
+ */
+export function canonicalizeIdentifiers(identifiers) {
+    return [...identifiers]
+        .map((identifier) => ({
+        namespace: identifier.namespace,
+        type: identifier.type,
+        value: identifier.value,
+        verifier: identifier.verifier,
+    }))
+        .sort((left, right) => canonicalize(left).localeCompare(canonicalize(right)));
+}
+/**
+ * @returns A random 0x-prefixed id.
+ */
+export function randomId() {
+    return bytesToHex(randomBytes(16));
+}
+/**
+ * Unix time in seconds. AuthController tokens and PoP challenges use this unit.
+ *
+ * @returns Seconds since the Unix epoch.
+ */
+export function unixNow() {
+    return Math.floor(Date.now() / 1000);
+}
+/**
+ * Generates an ephemeral ECDSA P-256 proof key pair for key-bound identifier PoP.
+ *
+ * @returns JWK-encoded public and private keys.
+ */
+export function generateSigningKey() {
+    const privateKeyBytes = p256.utils.randomSecretKey();
+    const publicKeyBytes = p256.getPublicKey(privateKeyBytes, false);
+    const publicJwk = {
+        kty: 'EC',
+        crv: 'P-256',
+        x: toBase64Url(publicKeyBytes.slice(1, 33)),
+        y: toBase64Url(publicKeyBytes.slice(33, 65)),
+    };
+    return {
+        publicKey: JSON.stringify(publicJwk),
+        privateKey: JSON.stringify({
+            ...publicJwk,
+            d: toBase64Url(privateKeyBytes),
+        }),
+    };
+}
+/**
+ * Signs a message with the ephemeral proof private key.
+ *
+ * @param privateKey - JWK JSON private key.
+ * @param message - Message string; hashed with SHA-256 before ECDSA.
+ * @returns Compact IEEE P1363 hex signature (`r‖s`).
+ */
+export function sign(privateKey, message) {
+    const jwk = JSON.parse(privateKey);
+    if (typeof jwk.d !== 'string') {
+        throw new Error('Invalid P-256 private JWK');
+    }
+    return bytesToHex(p256
+        .sign(sha256Sync(stringToBytes(message)), fromBase64Url(jwk.d))
+        .toBytes('compact'));
+}
+/**
+ * Verifies a P-256 signature against a public key.
+ *
+ * @param publicKey - JWK JSON public key.
+ * @param signature - Compact IEEE P1363 hex signature.
+ * @param message - Message string; hashed with SHA-256 before ECDSA.
+ * @returns Whether the signature is valid.
+ */
+export function verifySignature(publicKey, signature, message) {
+    const jwk = JSON.parse(publicKey);
+    if (typeof jwk.x !== 'string' || typeof jwk.y !== 'string') {
+        return false;
+    }
+    try {
+        return p256.verify(hexToBytes(signature), sha256Sync(stringToBytes(message)), concatBytes([
+            new Uint8Array([0x04]),
+            fromBase64Url(jwk.x),
+            fromBase64Url(jwk.y),
+        ]));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Unsigned mutation-receipt digest. SHA-256 of canonical JSON of the receipt
+ * fields excluding `signature`.
+ *
+ * @param receipt - Receipt fields covered by the signature.
+ * @param receipt.escrowId - Escrow that issued the receipt.
+ * @param receipt.mutationId - Mutation id.
+ * @param receipt.receiptKeyId - SHA-256 of the uncompressed receipt public key.
+ * @param receipt.requestHash - Mutation request hash.
+ * @param receipt.version - Applied version.
+ * @returns Hex digest.
+ */
+export function hashMutationReceipt(receipt) {
+    return hash({
+        escrowId: receipt.escrowId,
+        mutationId: receipt.mutationId,
+        receiptKeyId: receipt.receiptKeyId,
+        requestHash: receipt.requestHash,
+        version: receipt.version,
+    });
+}
+/**
+ * Decodes hex that may or may not have a `0x` prefix.
+ *
+ * @param hexString - Hex string.
+ * @returns Raw bytes.
+ */
+export function decodeHex(hexString) {
+    return hexToBytes((hexString.startsWith('0x') ? hexString : `0x${hexString}`));
+}
+/**
+ * SHA-256 of the uncompressed P-256 wrap public key, as `0x` hex.
+ *
+ * @param wrapPublicKey - Wrap public JWK JSON.
+ * @returns Key id matching cubist `wrapKeyId`.
+ */
+export function wrapKeyId(wrapPublicKey) {
+    return bytesToHex(sha256Sync(publicKeyBytesFromJwk(wrapPublicKey)));
+}
+/**
+ * Encrypts plaintext to a P-256 public key using escrow-wrap-v1.
+ *
+ * @param privateKey - Sender P-256 private JWK JSON.
+ * @param publicKey - Recipient P-256 public JWK JSON.
+ * @param plaintext - Bytes to encrypt.
+ * @returns Unprefixed hex of `nonce || ciphertext+tag`.
+ */
+export function encryptToPublic(privateKey, publicKey, plaintext) {
+    const key = deriveTransportKey(privateKey, publicKey);
+    const nonce = randomBytes(CHACHA_NONCE_LEN);
+    const ciphertext = chacha20poly1305(key, nonce).encrypt(plaintext);
+    return bytesToHex(concatBytes([nonce, ciphertext])).slice(2);
+}
+/**
+ * Decrypts escrow-wrap-v1 ciphertext produced by {@link encryptToPublic}.
+ *
+ * @param privateKey - Recipient P-256 private JWK JSON.
+ * @param publicKey - Sender P-256 public JWK JSON.
+ * @param ciphertextHex - Unprefixed or `0x` hex of `nonce || ciphertext+tag`.
+ * @returns Plaintext bytes.
+ */
+export function decryptFromPublic(privateKey, publicKey, ciphertextHex) {
+    const key = deriveTransportKey(privateKey, publicKey);
+    const blob = decodeHex(ciphertextHex);
+    if (blob.length < CHACHA_NONCE_LEN) {
+        throw new Error('Wrapped secret is truncated');
+    }
+    return chacha20poly1305(key, blob.subarray(0, CHACHA_NONCE_LEN)).decrypt(blob.subarray(CHACHA_NONCE_LEN));
+}
+function deriveTransportKey(privateKey, publicKey) {
+    const privateBytes = privateKeyBytesFromJwk(privateKey);
+    const publicBytes = publicKeyBytesFromJwk(publicKey);
+    const shared = p256.getSharedSecret(privateBytes, publicBytes);
+    // noble returns a compressed point (33 bytes). Cubist uses the 32-byte x-coordinate.
+    const ikm = shared.slice(1, 33);
+    return hkdf(sha256Sync, ikm, undefined, WRAP_INFO, CHACHA_KEY_LEN);
+}
+function privateKeyBytesFromJwk(privateKey) {
+    const jwk = JSON.parse(privateKey);
+    if (typeof jwk.d !== 'string') {
+        throw new Error('Invalid P-256 private JWK');
+    }
+    return fromBase64Url(jwk.d);
+}
+function publicKeyBytesFromJwk(publicKey) {
+    const jwk = JSON.parse(publicKey);
+    if (jwk.kty !== 'EC' ||
+        jwk.crv !== 'P-256' ||
+        typeof jwk.x !== 'string' ||
+        typeof jwk.y !== 'string') {
+        throw new Error('Invalid P-256 public JWK');
+    }
+    return concatBytes([
+        new Uint8Array([0x04]),
+        fromBase64Url(jwk.x),
+        fromBase64Url(jwk.y),
+    ]);
+}
+/**
+ * Encodes bytes as unpadded base64url (JWK coordinate format).
+ *
+ * @param bytes - Raw coordinate or scalar.
+ * @returns Base64url string.
+ */
+function toBase64Url(bytes) {
+    return bytesToBase64(bytes)
+        .replace(/\+/gu, '-')
+        .replace(/\//gu, '_')
+        .replace(/[=]+$/u, '');
+}
+/**
+ * @param length - Number of bytes to generate.
+ * @returns CSPRNG bytes.
+ */
+function randomBytes(length) {
+    return globalThis.crypto.getRandomValues(new Uint8Array(length));
+}
+/**
+ * Decodes unpadded base64url JWK coordinates.
+ *
+ * @param value - Base64url string.
+ * @returns Raw bytes.
+ */
+function fromBase64Url(value) {
+    return base64ToBytes(value
+        .replace(/-/gu, '+')
+        .replace(/_/gu, '/')
+        .padEnd(value.length + ((4 - (value.length % 4)) % 4), '='));
+}
+/**
+ * Recursively sorts keys and encodes Uint8Array as hex.
+ *
+ * @param value - Value to normalize.
+ * @returns JSON-safe canonical form.
+ */
+function sortKeys(value) {
+    if (value instanceof Uint8Array) {
+        return bytesToHex(value);
+    }
+    if (Array.isArray(value)) {
+        return value.map(sortKeys);
+    }
+    if (value !== null && typeof value === 'object') {
+        return Object.fromEntries(Object.keys(value)
+            .sort()
+            .map((key) => [key, sortKeys(value[key])]));
+    }
+    return value;
+}
+//# sourceMappingURL=crypto.js.map

package/dist/crypto.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"crypto.js","sourceRoot":"","sources":["../src/crypto.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  base64ToBytes,\n  bytesToBase64,\n  bytesToHex,\n  concatBytes,\n  hexToBytes,\n  stringToBytes,\n} from '@metamask/utils';\nimport type { Hex } from '@metamask/utils';\nimport { chacha20poly1305 } from '@noble/ciphers/chacha';\nimport { p256 } from '@noble/curves/nist';\nimport { hkdf } from '@noble/hashes/hkdf';\nimport { sha256 as sha256Sync } from '@noble/hashes/sha2';\n\nimport type { EcPublicJwk, Identifier } from './types.js';\n\nconst WRAP_INFO = new TextEncoder().encode('escrow-wrap-v1');\nconst CHACHA_KEY_LEN = 32;\nconst CHACHA_NONCE_LEN = 12;\n\n/**\n * Recursively sorts object keys so hashes are independent of property order.\n *\n * @param value - JSON-compatible value.\n * @returns A canonical JSON string.\n */\nexport function canonicalize(value: unknown): string {\n  return JSON.stringify(sortKeys(value));\n}\n\n/**\n * SHA-256 of the canonical JSON form of `value`, as a 0x-prefixed hex string.\n *\n * @param value - Value to hash.\n * @returns Hex digest.\n */\nexport function hash(value: unknown): Hex {\n  return bytesToHex(sha256Sync(stringToBytes(canonicalize(value))));\n}\n\n/**\n * Canonical identifier list bound into AuthController `identifiersHash`.\n *\n * @param identifiers - Identifier set.\n * @returns Sorted identifier records including verifier material.\n */\nexport function canonicalizeIdentifiers(identifiers: Identifier[]): unknown {\n  return [...identifiers]\n    .map((identifier) => ({\n      namespace: identifier.namespace,\n      type: identifier.type,\n      value: identifier.value,\n      verifier: identifier.verifier,\n    }))\n    .sort((left, right) =>\n      canonicalize(left).localeCompare(canonicalize(right)),\n    );\n}\n\n/**\n * @returns A random 0x-prefixed id.\n */\nexport function randomId(): Hex {\n  return bytesToHex(randomBytes(16));\n}\n\n/**\n * Unix time in seconds. AuthController tokens and PoP challenges use this unit.\n *\n * @returns Seconds since the Unix epoch.\n */\nexport function unixNow(): number {\n  return Math.floor(Date.now() / 1000);\n}\n\n/**\n * Generates an ephemeral ECDSA P-256 proof key pair for key-bound identifier PoP.\n *\n * @returns JWK-encoded public and private keys.\n */\nexport function generateSigningKey(): {\n  publicKey: string;\n  privateKey: string;\n} {\n  const privateKeyBytes = p256.utils.randomSecretKey();\n  const publicKeyBytes = p256.getPublicKey(privateKeyBytes, false);\n  const publicJwk = {\n    kty: 'EC',\n    crv: 'P-256',\n    x: toBase64Url(publicKeyBytes.slice(1, 33)),\n    y: toBase64Url(publicKeyBytes.slice(33, 65)),\n  };\n  return {\n    publicKey: JSON.stringify(publicJwk),\n    privateKey: JSON.stringify({\n      ...publicJwk,\n      d: toBase64Url(privateKeyBytes),\n    }),\n  };\n}\n\n/**\n * Signs a message with the ephemeral proof private key.\n *\n * @param privateKey - JWK JSON private key.\n * @param message - Message string; hashed with SHA-256 before ECDSA.\n * @returns Compact IEEE P1363 hex signature (`r‖s`).\n */\nexport function sign(privateKey: string, message: string): Hex {\n  const jwk = JSON.parse(privateKey) as { d?: string };\n  if (typeof jwk.d !== 'string') {\n    throw new Error('Invalid P-256 private JWK');\n  }\n  return bytesToHex(\n    p256\n      .sign(sha256Sync(stringToBytes(message)), fromBase64Url(jwk.d))\n      .toBytes('compact'),\n  );\n}\n\n/**\n * Verifies a P-256 signature against a public key.\n *\n * @param publicKey - JWK JSON public key.\n * @param signature - Compact IEEE P1363 hex signature.\n * @param message - Message string; hashed with SHA-256 before ECDSA.\n * @returns Whether the signature is valid.\n */\nexport function verifySignature(\n  publicKey: string,\n  signature: string,\n  message: string,\n): boolean {\n  const jwk = JSON.parse(publicKey) as { x?: string; y?: string };\n  if (typeof jwk.x !== 'string' || typeof jwk.y !== 'string') {\n    return false;\n  }\n  try {\n    return p256.verify(\n      hexToBytes(signature as Hex),\n      sha256Sync(stringToBytes(message)),\n      concatBytes([\n        new Uint8Array([0x04]),\n        fromBase64Url(jwk.x),\n        fromBase64Url(jwk.y),\n      ]),\n    );\n  } catch {\n    return false;\n  }\n}\n\n/**\n * Unsigned mutation-receipt digest. SHA-256 of canonical JSON of the receipt\n * fields excluding `signature`.\n *\n * @param receipt - Receipt fields covered by the signature.\n * @param receipt.escrowId - Escrow that issued the receipt.\n * @param receipt.mutationId - Mutation id.\n * @param receipt.receiptKeyId - SHA-256 of the uncompressed receipt public key.\n * @param receipt.requestHash - Mutation request hash.\n * @param receipt.version - Applied version.\n * @returns Hex digest.\n */\nexport function hashMutationReceipt(receipt: {\n  escrowId: string;\n  mutationId: string;\n  receiptKeyId: string;\n  requestHash: string;\n  version: number;\n}): Hex {\n  return hash({\n    escrowId: receipt.escrowId,\n    mutationId: receipt.mutationId,\n    receiptKeyId: receipt.receiptKeyId,\n    requestHash: receipt.requestHash,\n    version: receipt.version,\n  });\n}\n\n/**\n * Decodes hex that may or may not have a `0x` prefix.\n *\n * @param hexString - Hex string.\n * @returns Raw bytes.\n */\nexport function decodeHex(hexString: string): Uint8Array {\n  return hexToBytes(\n    (hexString.startsWith('0x') ? hexString : `0x${hexString}`) as Hex,\n  );\n}\n\n/**\n * SHA-256 of the uncompressed P-256 wrap public key, as `0x` hex.\n *\n * @param wrapPublicKey - Wrap public JWK JSON.\n * @returns Key id matching cubist `wrapKeyId`.\n */\nexport function wrapKeyId(wrapPublicKey: string): Hex {\n  return bytesToHex(sha256Sync(publicKeyBytesFromJwk(wrapPublicKey)));\n}\n\n/**\n * Encrypts plaintext to a P-256 public key using escrow-wrap-v1.\n *\n * @param privateKey - Sender P-256 private JWK JSON.\n * @param publicKey - Recipient P-256 public JWK JSON.\n * @param plaintext - Bytes to encrypt.\n * @returns Unprefixed hex of `nonce || ciphertext+tag`.\n */\nexport function encryptToPublic(\n  privateKey: string,\n  publicKey: string,\n  plaintext: Uint8Array,\n): string {\n  const key = deriveTransportKey(privateKey, publicKey);\n  const nonce = randomBytes(CHACHA_NONCE_LEN);\n  const ciphertext = chacha20poly1305(key, nonce).encrypt(plaintext);\n  return bytesToHex(concatBytes([nonce, ciphertext])).slice(2);\n}\n\n/**\n * Decrypts escrow-wrap-v1 ciphertext produced by {@link encryptToPublic}.\n *\n * @param privateKey - Recipient P-256 private JWK JSON.\n * @param publicKey - Sender P-256 public JWK JSON.\n * @param ciphertextHex - Unprefixed or `0x` hex of `nonce || ciphertext+tag`.\n * @returns Plaintext bytes.\n */\nexport function decryptFromPublic(\n  privateKey: string,\n  publicKey: string,\n  ciphertextHex: string,\n): Uint8Array {\n  const key = deriveTransportKey(privateKey, publicKey);\n  const blob = decodeHex(ciphertextHex);\n  if (blob.length < CHACHA_NONCE_LEN) {\n    throw new Error('Wrapped secret is truncated');\n  }\n  return chacha20poly1305(key, blob.subarray(0, CHACHA_NONCE_LEN)).decrypt(\n    blob.subarray(CHACHA_NONCE_LEN),\n  );\n}\n\nfunction deriveTransportKey(privateKey: string, publicKey: string): Uint8Array {\n  const privateBytes = privateKeyBytesFromJwk(privateKey);\n  const publicBytes = publicKeyBytesFromJwk(publicKey);\n  const shared = p256.getSharedSecret(privateBytes, publicBytes);\n  // noble returns a compressed point (33 bytes). Cubist uses the 32-byte x-coordinate.\n  const ikm = shared.slice(1, 33);\n  return hkdf(sha256Sync, ikm, undefined, WRAP_INFO, CHACHA_KEY_LEN);\n}\n\nfunction privateKeyBytesFromJwk(privateKey: string): Uint8Array {\n  const jwk = JSON.parse(privateKey) as { d?: string };\n  if (typeof jwk.d !== 'string') {\n    throw new Error('Invalid P-256 private JWK');\n  }\n  return fromBase64Url(jwk.d);\n}\n\nfunction publicKeyBytesFromJwk(publicKey: string): Uint8Array {\n  const jwk = JSON.parse(publicKey) as EcPublicJwk;\n  if (\n    jwk.kty !== 'EC' ||\n    jwk.crv !== 'P-256' ||\n    typeof jwk.x !== 'string' ||\n    typeof jwk.y !== 'string'\n  ) {\n    throw new Error('Invalid P-256 public JWK');\n  }\n  return concatBytes([\n    new Uint8Array([0x04]),\n    fromBase64Url(jwk.x),\n    fromBase64Url(jwk.y),\n  ]);\n}\n\n/**\n * Encodes bytes as unpadded base64url (JWK coordinate format).\n *\n * @param bytes - Raw coordinate or scalar.\n * @returns Base64url string.\n */\nfunction toBase64Url(bytes: Uint8Array): string {\n  return bytesToBase64(bytes)\n    .replace(/\\+/gu, '-')\n    .replace(/\\//gu, '_')\n    .replace(/[=]+$/u, '');\n}\n\n/**\n * @param length - Number of bytes to generate.\n * @returns CSPRNG bytes.\n */\nfunction randomBytes(length: number): Uint8Array {\n  return globalThis.crypto.getRandomValues(new Uint8Array(length));\n}\n\n/**\n * Decodes unpadded base64url JWK coordinates.\n *\n * @param value - Base64url string.\n * @returns Raw bytes.\n */\nfunction fromBase64Url(value: string): Uint8Array {\n  return base64ToBytes(\n    value\n      .replace(/-/gu, '+')\n      .replace(/_/gu, '/')\n      .padEnd(value.length + ((4 - (value.length % 4)) % 4), '='),\n  );\n}\n\n/**\n * Recursively sorts keys and encodes Uint8Array as hex.\n *\n * @param value - Value to normalize.\n * @returns JSON-safe canonical form.\n */\nfunction sortKeys(value: unknown): unknown {\n  if (value instanceof Uint8Array) {\n    return bytesToHex(value);\n  }\n  if (Array.isArray(value)) {\n    return value.map(sortKeys);\n  }\n  if (value !== null && typeof value === 'object') {\n    return Object.fromEntries(\n      Object.keys(value as Record<string, unknown>)\n        .sort()\n        .map((key) => [key, sortKeys((value as Record<string, unknown>)[key])]),\n    );\n  }\n  return value;\n}\n"]}

package/dist/errors.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Errors thrown by `MfaRecoveryController`.
+ */
+export declare class MfaRecoveryError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+/**
+ * Thrown when a mutation is not acknowledged by every configured escrow.
+ * Call `MfaRecoveryController.resume()` to retry the same mutation.
+ */
+export declare class IncompleteMutationError extends MfaRecoveryError {
+    readonly mutationId: string;
+    constructor(mutationId: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,YAAY,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAKxC;CACF;AAED;;;GAGG;AACH,qBAAa,uBAAwB,SAAQ,gBAAgB;IAC3D,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B,YAAY,UAAU,EAAE,MAAM,EAO7B;CACF"}

package/dist/errors.js

@@ -0,0 +1,25 @@
+/**
+ * Errors thrown by `MfaRecoveryController`.
+ */
+export class MfaRecoveryError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.name = 'MfaRecoveryError';
+        this.code = code;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/**
+ * Thrown when a mutation is not acknowledged by every configured escrow.
+ * Call `MfaRecoveryController.resume()` to retry the same mutation.
+ */
+export class IncompleteMutationError extends MfaRecoveryError {
+    mutationId;
+    constructor(mutationId) {
+        super(`Mutation ${mutationId} is not acknowledged by every escrow`, 'incomplete_mutation');
+        this.name = 'IncompleteMutationError';
+        this.mutationId = mutationId;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IAChC,IAAI,CAAS;IAEtB,YAAY,OAAe,EAAE,IAAY;QACvC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;QAC/B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,IAAI,MAAM,CAAC,SAAS,CAAC,CAAC;IACpD,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,uBAAwB,SAAQ,gBAAgB;IAClD,UAAU,CAAS;IAE5B,YAAY,UAAkB;QAC5B,KAAK,CACH,YAAY,UAAU,sCAAsC,EAC5D,qBAAqB,CACtB,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;QACtC,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;CACF","sourcesContent":["/**\n * Errors thrown by `MfaRecoveryController`.\n */\nexport class MfaRecoveryError extends Error {\n  readonly code: string;\n\n  constructor(message: string, code: string) {\n    super(message);\n    this.name = 'MfaRecoveryError';\n    this.code = code;\n    Object.setPrototypeOf(this, new.target.prototype);\n  }\n}\n\n/**\n * Thrown when a mutation is not acknowledged by every configured escrow.\n * Call `MfaRecoveryController.resume()` to retry the same mutation.\n */\nexport class IncompleteMutationError extends MfaRecoveryError {\n  readonly mutationId: string;\n\n  constructor(mutationId: string) {\n    super(\n      `Mutation ${mutationId} is not acknowledged by every escrow`,\n      'incomplete_mutation',\n    );\n    this.name = 'IncompleteMutationError';\n    this.mutationId = mutationId;\n  }\n}\n"]}

package/dist/escrow-utils.d.ts

@@ -0,0 +1,42 @@
+import type { Mutation, MutationReceipt, RecoveryEscrowProvider } from './types.js';
+export type RecoverySecretResult = {
+    escrowId: string;
+    recoverySecret: Uint8Array;
+    version: number;
+    lastMutationId: string;
+};
+/**
+ * Identifies a fulfilled promise result for TypeScript narrowing.
+ *
+ * @param result - Settled promise result.
+ * @returns Whether the result is fulfilled.
+ */
+export declare function isFulfilledResult<Result>(result: PromiseSettledResult<Result>): result is PromiseFulfilledResult<Result>;
+/**
+ * Checks the serialized shape of a mutation receipt.
+ *
+ * @param value - Decrypted or provider-returned value.
+ * @returns Whether the value has a mutation receipt shape.
+ */
+export declare function isMutationReceipt(value: unknown): value is MutationReceipt;
+/**
+ * Verifies a receipt against its expected target escrow.
+ *
+ * The provider checks the ECDSA receipt signature with its build-pinned
+ * receipt key; the target identity check is performed here as well.
+ *
+ * @param receipt - Receipt returned by an escrow.
+ * @param mutation - Mutation the receipt must acknowledge.
+ * @param escrow - Expected target escrow provider.
+ * @returns Whether the receipt is valid for the target.
+ */
+export declare function verifyMutationReceipt(receipt: MutationReceipt, mutation: Mutation, escrow: RecoveryEscrowProvider): boolean;
+/**
+ * Selects the highest consistent successful recovery-secret response.
+ *
+ * @param results - Settled escrow read results.
+ * @returns The selected recovery-secret response.
+ * @throws If no response succeeds or matching highest versions disagree.
+ */
+export declare function selectHighestConsistentVersion(results: PromiseSettledResult<RecoverySecretResult>[]): Omit<RecoverySecretResult, 'escrowId'>;
+//# sourceMappingURL=escrow-utils.d.ts.map

package/dist/escrow-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"escrow-utils.d.ts","sourceRoot":"","sources":["../src/escrow-utils.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,QAAQ,EACR,eAAe,EACf,sBAAsB,EACvB,MAAM,YAAY,CAAC;AAEpB,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,UAAU,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EACtC,MAAM,EAAE,oBAAoB,CAAC,MAAM,CAAC,GACnC,MAAM,IAAI,sBAAsB,CAAC,MAAM,CAAC,CAE1C;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,eAAe,CAY1E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,eAAe,EACxB,QAAQ,EAAE,QAAQ,EAClB,MAAM,EAAE,sBAAsB,GAC7B,OAAO,CAST;AAED;;;;;;GAMG;AACH,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,oBAAoB,CAAC,oBAAoB,CAAC,EAAE,GACpD,IAAI,CAAC,oBAAoB,EAAE,UAAU,CAAC,CA2BxC"}

package/dist/escrow-utils.js

@@ -0,0 +1,77 @@
+import { areUint8ArraysEqual } from '@metamask/utils';
+import { MfaRecoveryError } from './errors.js';
+/**
+ * Identifies a fulfilled promise result for TypeScript narrowing.
+ *
+ * @param result - Settled promise result.
+ * @returns Whether the result is fulfilled.
+ */
+export function isFulfilledResult(result) {
+    return result.status === 'fulfilled';
+}
+/**
+ * Checks the serialized shape of a mutation receipt.
+ *
+ * @param value - Decrypted or provider-returned value.
+ * @returns Whether the value has a mutation receipt shape.
+ */
+export function isMutationReceipt(value) {
+    return (isRecord(value) &&
+        typeof value.mutationId === 'string' &&
+        typeof value.requestHash === 'string' &&
+        typeof value.escrowId === 'string' &&
+        typeof value.version === 'number' &&
+        Number.isInteger(value.version) &&
+        value.version >= 0 &&
+        typeof value.receiptKeyId === 'string' &&
+        typeof value.signature === 'string');
+}
+/**
+ * Verifies a receipt against its expected target escrow.
+ *
+ * The provider checks the ECDSA receipt signature with its build-pinned
+ * receipt key; the target identity check is performed here as well.
+ *
+ * @param receipt - Receipt returned by an escrow.
+ * @param mutation - Mutation the receipt must acknowledge.
+ * @param escrow - Expected target escrow provider.
+ * @returns Whether the receipt is valid for the target.
+ */
+export function verifyMutationReceipt(receipt, mutation, escrow) {
+    if (receipt.escrowId !== escrow.id) {
+        return false;
+    }
+    try {
+        return escrow.verifyReceipt(receipt, mutation, escrow.id);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Selects the highest consistent successful recovery-secret response.
+ *
+ * @param results - Settled escrow read results.
+ * @returns The selected recovery-secret response.
+ * @throws If no response succeeds or matching highest versions disagree.
+ */
+export function selectHighestConsistentVersion(results) {
+    const responses = results
+        .filter(isFulfilledResult)
+        .map((result) => result.value);
+    if (responses.length === 0) {
+        throw new MfaRecoveryError('No escrow returned a recovery secret', 'read_failed');
+    }
+    const highestVersion = Math.max(...responses.map((response) => response.version));
+    const highest = responses.filter((response) => response.version === highestVersion);
+    const selected = highest[0];
+    if (!highest.every((response) => response.lastMutationId === selected.lastMutationId &&
+        areUint8ArraysEqual(response.recoverySecret, selected.recoverySecret))) {
+        throw new MfaRecoveryError('Replica corruption', 'replica_corruption');
+    }
+    return selected;
+}
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+//# sourceMappingURL=escrow-utils.js.map

package/dist/escrow-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"escrow-utils.js","sourceRoot":"","sources":["../src/escrow-utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAEtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAc/C;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAC/B,MAAoC;IAEpC,OAAO,MAAM,CAAC,MAAM,KAAK,WAAW,CAAC;AACvC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAc;IAC9C,OAAO,CACL,QAAQ,CAAC,KAAK,CAAC;QACf,OAAO,KAAK,CAAC,UAAU,KAAK,QAAQ;QACpC,OAAO,KAAK,CAAC,WAAW,KAAK,QAAQ;QACrC,OAAO,KAAK,CAAC,QAAQ,KAAK,QAAQ;QAClC,OAAO,KAAK,CAAC,OAAO,KAAK,QAAQ;QACjC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,OAAO,CAAC;QAC/B,KAAK,CAAC,OAAO,IAAI,CAAC;QAClB,OAAO,KAAK,CAAC,YAAY,KAAK,QAAQ;QACtC,OAAO,KAAK,CAAC,SAAS,KAAK,QAAQ,CACpC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,qBAAqB,CACnC,OAAwB,EACxB,QAAkB,EAClB,MAA8B;IAE9B,IAAI,OAAO,CAAC,QAAQ,KAAK,MAAM,CAAC,EAAE,EAAE,CAAC;QACnC,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,CAAC;QACH,OAAO,MAAM,CAAC,aAAa,CAAC,OAAO,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;IAC5D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,8BAA8B,CAC5C,OAAqD;IAErD,MAAM,SAAS,GAAG,OAAO;SACtB,MAAM,CAAC,iBAAiB,CAAC;SACzB,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACjC,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC3B,MAAM,IAAI,gBAAgB,CACxB,sCAAsC,EACtC,aAAa,CACd,CAAC;IACJ,CAAC;IACD,MAAM,cAAc,GAAG,IAAI,CAAC,GAAG,CAC7B,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,CAAC,OAAO,CAAC,CACjD,CAAC;IACF,MAAM,OAAO,GAAG,SAAS,CAAC,MAAM,CAC9B,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,CAAC,OAAO,KAAK,cAAc,CAClD,CAAC;IACF,MAAM,QAAQ,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAC5B,IACE,CAAC,OAAO,CAAC,KAAK,CACZ,CAAC,QAAQ,EAAE,EAAE,CACX,QAAQ,CAAC,cAAc,KAAK,QAAQ,CAAC,cAAc;QACnD,mBAAmB,CAAC,QAAQ,CAAC,cAAc,EAAE,QAAQ,CAAC,cAAc,CAAC,CACxE,EACD,CAAC;QACD,MAAM,IAAI,gBAAgB,CAAC,oBAAoB,EAAE,oBAAoB,CAAC,CAAC;IACzE,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC","sourcesContent":["import { areUint8ArraysEqual } from '@metamask/utils';\n\nimport { MfaRecoveryError } from './errors.js';\nimport type {\n  Mutation,\n  MutationReceipt,\n  RecoveryEscrowProvider,\n} from './types.js';\n\nexport type RecoverySecretResult = {\n  escrowId: string;\n  recoverySecret: Uint8Array;\n  version: number;\n  lastMutationId: string;\n};\n\n/**\n * Identifies a fulfilled promise result for TypeScript narrowing.\n *\n * @param result - Settled promise result.\n * @returns Whether the result is fulfilled.\n */\nexport function isFulfilledResult<Result>(\n  result: PromiseSettledResult<Result>,\n): result is PromiseFulfilledResult<Result> {\n  return result.status === 'fulfilled';\n}\n\n/**\n * Checks the serialized shape of a mutation receipt.\n *\n * @param value - Decrypted or provider-returned value.\n * @returns Whether the value has a mutation receipt shape.\n */\nexport function isMutationReceipt(value: unknown): value is MutationReceipt {\n  return (\n    isRecord(value) &&\n    typeof value.mutationId === 'string' &&\n    typeof value.requestHash === 'string' &&\n    typeof value.escrowId === 'string' &&\n    typeof value.version === 'number' &&\n    Number.isInteger(value.version) &&\n    value.version >= 0 &&\n    typeof value.receiptKeyId === 'string' &&\n    typeof value.signature === 'string'\n  );\n}\n\n/**\n * Verifies a receipt against its expected target escrow.\n *\n * The provider checks the ECDSA receipt signature with its build-pinned\n * receipt key; the target identity check is performed here as well.\n *\n * @param receipt - Receipt returned by an escrow.\n * @param mutation - Mutation the receipt must acknowledge.\n * @param escrow - Expected target escrow provider.\n * @returns Whether the receipt is valid for the target.\n */\nexport function verifyMutationReceipt(\n  receipt: MutationReceipt,\n  mutation: Mutation,\n  escrow: RecoveryEscrowProvider,\n): boolean {\n  if (receipt.escrowId !== escrow.id) {\n    return false;\n  }\n  try {\n    return escrow.verifyReceipt(receipt, mutation, escrow.id);\n  } catch {\n    return false;\n  }\n}\n\n/**\n * Selects the highest consistent successful recovery-secret response.\n *\n * @param results - Settled escrow read results.\n * @returns The selected recovery-secret response.\n * @throws If no response succeeds or matching highest versions disagree.\n */\nexport function selectHighestConsistentVersion(\n  results: PromiseSettledResult<RecoverySecretResult>[],\n): Omit<RecoverySecretResult, 'escrowId'> {\n  const responses = results\n    .filter(isFulfilledResult)\n    .map((result) => result.value);\n  if (responses.length === 0) {\n    throw new MfaRecoveryError(\n      'No escrow returned a recovery secret',\n      'read_failed',\n    );\n  }\n  const highestVersion = Math.max(\n    ...responses.map((response) => response.version),\n  );\n  const highest = responses.filter(\n    (response) => response.version === highestVersion,\n  );\n  const selected = highest[0];\n  if (\n    !highest.every(\n      (response) =>\n        response.lastMutationId === selected.lastMutationId &&\n        areUint8ArraysEqual(response.recoverySecret, selected.recoverySecret),\n    )\n  ) {\n    throw new MfaRecoveryError('Replica corruption', 'replica_corruption');\n  }\n  return selected;\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return value !== null && typeof value === 'object' && !Array.isArray(value);\n}\n"]}

package/dist/identifier-auth.d.ts

@@ -0,0 +1,83 @@
+import type { Identifier, IdentifierAuthMode, IdentifierAuthorization, KeyBoundIdentifierToken, RecoveryEscrowProvider, RecoveryIdentifierAuthProvider } from './types.js';
+/**
+ * Minimum identifier count for register and updateIdentifiers.
+ */
+export declare const MIN_IDENTIFIERS = 2;
+/**
+ * Distinct identifier identities (`type` + `namespace` + `value`).
+ *
+ * @param identifiers - Identifier list.
+ * @returns Distinct identity count.
+ */
+export declare function countDistinctIdentifiers(identifiers: Identifier[]): number;
+/**
+ * Trusted identifier-type registry. Escrows and the controller derive the
+ * authentication mode from this table, never from a client-selected flag.
+ *
+ * TODO: MFA-605 / MFA-606 / MFA-568 — add `emailOtp` / `smsOtp` as
+ * `escrow-challenge` once escrow OTP commands exist.
+ */
+export declare const IDENTIFIER_AUTH_MODES: Record<string, IdentifierAuthMode>;
+export type AuthorizedEscrow = {
+    escrow: RecoveryEscrowProvider;
+    authorization: IdentifierAuthorization;
+};
+/**
+ * Requests a key-bound identifier token and returns the private key used to
+ * prove possession of it.
+ *
+ * @param params - Identifier authorization parameters.
+ * @param params.identifier - Identifier to authenticate.
+ * @param params.requestHash - Request hash bound to the authorization.
+ * @param params.identifierAuthProvider - Provider for key-bound assertions.
+ * @returns Key-bound identifier token and its proof private key.
+ */
+export declare function requestKeyBoundIdentifierToken({ identifier, requestHash, identifierAuthProvider, }: {
+    identifier: Identifier;
+    requestHash: string;
+    identifierAuthProvider: RecoveryIdentifierAuthProvider;
+}): Promise<{
+    token: KeyBoundIdentifierToken;
+    proofPrivateKey: string;
+}>;
+/**
+ * Authorizes a key-bound identifier with each escrow that successfully
+ * provides a challenge.
+ *
+ * @param params - Key-bound authorization parameters.
+ * @param params.escrows - Escrows to authorize.
+ * @param params.token - Key-bound identifier token.
+ * @param params.proofPrivateKey - Private key for proving token possession.
+ * @returns Successful escrow authorizations.
+ */
+export declare function authorizeWithKeyBoundToken({ escrows, token, proofPrivateKey, }: {
+    escrows: RecoveryEscrowProvider[];
+    token: KeyBoundIdentifierToken;
+    proofPrivateKey: string;
+}): Promise<AuthorizedEscrow[]>;
+/**
+ * Requests and authorizes a key-bound identifier with each escrow that
+ * successfully provides a challenge.
+ *
+ * @param params - Identifier authorization parameters.
+ * @param params.escrows - Escrows to authorize.
+ * @param params.identifier - Identifier to authorize.
+ * @param params.requestHash - Request hash bound to the authorization.
+ * @param params.identifierAuthProvider - Provider for key-bound assertions.
+ * @returns Successful escrow authorizations.
+ */
+export declare function authorizeKeyBoundIdentifier({ escrows, identifier, requestHash, identifierAuthProvider, }: {
+    escrows: RecoveryEscrowProvider[];
+    identifier: Identifier;
+    requestHash: string;
+    identifierAuthProvider: RecoveryIdentifierAuthProvider;
+}): Promise<AuthorizedEscrow[]>;
+/**
+ * Returns the auth mode for an identifier type.
+ *
+ * @param type - Identifier type.
+ * @returns Auth mode.
+ * @throws If the type is not in the trusted registry.
+ */
+export declare function getIdentifierAuthMode(type: string): IdentifierAuthMode;
+//# sourceMappingURL=identifier-auth.d.ts.map

package/dist/identifier-auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identifier-auth.d.ts","sourceRoot":"","sources":["../src/identifier-auth.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,UAAU,EACV,kBAAkB,EAClB,uBAAuB,EACvB,uBAAuB,EACvB,sBAAsB,EACtB,8BAA8B,EAC/B,MAAM,YAAY,CAAC;AAEpB;;GAEG;AACH,eAAO,MAAM,eAAe,IAAI,CAAC;AAEjC;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,WAAW,EAAE,UAAU,EAAE,GAAG,MAAM,CAM1E;AAED;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAIpE,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,MAAM,EAAE,sBAAsB,CAAC;IAC/B,aAAa,EAAE,uBAAuB,CAAC;CACxC,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAsB,8BAA8B,CAAC,EACnD,UAAU,EACV,WAAW,EACX,sBAAsB,GACvB,EAAE;IACD,UAAU,EAAE,UAAU,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,sBAAsB,EAAE,8BAA8B,CAAC;CACxD,GAAG,OAAO,CAAC;IAAE,KAAK,EAAE,uBAAuB,CAAC;IAAC,eAAe,EAAE,MAAM,CAAA;CAAE,CAAC,CAQvE;AAED;;;;;;;;;GASG;AACH,wBAAsB,0BAA0B,CAAC,EAC/C,OAAO,EACP,KAAK,EACL,eAAe,GAChB,EAAE;IACD,OAAO,EAAE,sBAAsB,EAAE,CAAC;IAClC,KAAK,EAAE,uBAAuB,CAAC;IAC/B,eAAe,EAAE,MAAM,CAAC;CACzB,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC,CA6B9B;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,2BAA2B,CAAC,EAChD,OAAO,EACP,UAAU,EACV,WAAW,EACX,sBAAsB,GACvB,EAAE;IACD,OAAO,EAAE,sBAAsB,EAAE,CAAC;IAClC,UAAU,EAAE,UAAU,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,sBAAsB,EAAE,8BAA8B,CAAC;CACxD,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAW9B;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,CAStE"}