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

package/dist/types.d.ts

@@ -0,0 +1,235 @@
+/**
+ * MFA recovery protocol types from the recovery ADR.
+ */
+export type Identifier = {
+    type: string;
+    namespace: string;
+    value: string;
+    verifier: unknown;
+};
+export type PoPChallenge = {
+    id: string;
+    escrowId: string;
+    /**
+     * Unix time in seconds.
+     */
+    expiresAt: number;
+};
+export type IdentifierAuthMode = 'key-bound';
+export type KeyBoundIdentifierToken = {
+    identifier: Identifier;
+    proofPublicKey: string;
+    requestHash: string;
+    providerAssertion: unknown;
+};
+export type ProofOfPossession = {
+    challengeId: string;
+    requestHash: string;
+    signature: string;
+};
+/**
+ * Identifier proof presented to an escrow. Only key-bound proofs are wired;
+ * escrow-challenge grants land with MFA-605 / MFA-606 / MFA-568.
+ */
+export type IdentifierAuthorization = {
+    kind: 'key-bound';
+    token: KeyBoundIdentifierToken;
+    proof: ProofOfPossession;
+};
+export type MutationOperation = 'register' | 'updateRecoverySecret' | 'updateIdentifiers';
+export type Mutation = {
+    id: string;
+    profileId: string;
+    operation: MutationOperation;
+    expectedVersion: number;
+    newVersion: number;
+    payloadHash: string;
+    audiences: string[];
+    requestHash: string;
+};
+export type AuthControllerToken = {
+    profileId: string;
+    requestHash: string;
+    twoFactor?: true;
+    identifiersHash?: string;
+    identifierOwnershipApproved?: true;
+    issuer: string;
+    /**
+     * Unix time in seconds.
+     */
+    expiresAt: number;
+    signature: string;
+};
+export type MutationReceipt = {
+    mutationId: string;
+    requestHash: string;
+    escrowId: string;
+    version: number;
+    /**
+     * SHA-256 of the uncompressed receipt public key, as `0x` hex.
+     */
+    receiptKeyId: string;
+    signature: string;
+};
+/**
+ * P-256 public JWK used as an ephemeral wrap key (`pkE`).
+ */
+export type EcPublicJwk = {
+    kty: 'EC';
+    crv: 'P-256';
+    x: string;
+    y: string;
+};
+/**
+ * Result of first-factor identifier authentication, consumed by
+ * `getRecoverySecret`.
+ *
+ * The private keys are ephemeral and must only be kept in memory.
+ */
+export type IdentifierSession = {
+    token: KeyBoundIdentifierToken;
+    proofPrivateKey: string;
+    requestId: string;
+    ephemeralPrivateKey: string;
+    pkE: EcPublicJwk;
+};
+/**
+ * Recovery secret wrapped to one escrow wrap key for transit.
+ * `ciphertext` is unprefixed hex of `nonce || ChaCha20-Poly1305(ciphertext+tag)`.
+ */
+export type WrappedSecret = {
+    pkE: EcPublicJwk;
+    ciphertext: string;
+};
+export type WrappedSecretOutput = {
+    ciphertext: string;
+};
+export type RegisterPayload = {
+    recoverySecret: WrappedSecret;
+    identifiers: Identifier[];
+};
+export type UpdateRecoverySecretPayload = Pick<RegisterPayload, 'recoverySecret'>;
+export type UpdateIdentifiersPayload = Pick<RegisterPayload, 'identifiers'>;
+/**
+ * Escrow `applyMutation` body. Recovery secrets are wrapped to that escrow's
+ * wrap key; do not confuse with {@link PendingMutationPayload}.
+ */
+export type MutationPayload = RegisterPayload | UpdateRecoverySecretPayload | UpdateIdentifiersPayload;
+/**
+ * 0x-hex of a plaintext recovery secret. Encrypted pending state stores this
+ * logical value; each escrow receives a {@link WrappedSecret} only at apply.
+ */
+export type PendingRecoverySecretHex = string;
+/**
+ * Logical register payload stored in encrypted pending state.
+ */
+export type PendingRegisterPayload = {
+    identifiers: Identifier[];
+    recoverySecret: PendingRecoverySecretHex;
+};
+/**
+ * Logical secret-update payload stored in encrypted pending state.
+ */
+export type PendingUpdateRecoverySecretPayload = Pick<PendingRegisterPayload, 'recoverySecret'>;
+/**
+ * Logical identifier-update payload stored in encrypted pending state.
+ */
+export type PendingUpdateIdentifiersPayload = Pick<PendingRegisterPayload, 'identifiers'>;
+/**
+ * Logical mutation payload persisted in encrypted pending state. Distinct from
+ * {@link MutationPayload}, which is the per-escrow apply body.
+ */
+export type PendingMutationPayload = PendingRegisterPayload | PendingUpdateRecoverySecretPayload | PendingUpdateIdentifiersPayload;
+type PendingOperationBase = {
+    mutation: Mutation;
+    identifier: Identifier | null;
+    payload: PendingMutationPayload;
+};
+export type AuthorizingPendingOperation = PendingOperationBase & {
+    phase: 'authorizing';
+};
+export type WritingPendingOperation = PendingOperationBase & {
+    phase: 'writing';
+    authControllerToken: AuthControllerToken;
+    receipts: MutationReceipt[];
+};
+export type PendingOperation = AuthorizingPendingOperation | WritingPendingOperation;
+export type RecoveryPhase = 'idle' | PendingOperation['phase'];
+/**
+ * Encoded ciphertext of {@link PendingOperation}. Wallet secure storage
+ * encrypts this blob (including any hex recovery secret). A raw recovery
+ * secret is never persisted in BaseController state.
+ *
+ * The recovery spec's pseudocode represents this as `Uint8Array`, but the
+ * controller stores the encoded ciphertext as a string so BaseController state
+ * persistence and serialization preserve it without binary coercion.
+ */
+export type EncryptedPendingOperation = string;
+export type GetRecoverySecretResponse = {
+    recoverySecret: WrappedSecretOutput;
+    version: number;
+    lastMutationId: string;
+    wrapKeyId: string;
+};
+/**
+ * Recovery secret plus the version to use as `epoch` on later mutations.
+ */
+export type RecoveredSecret = {
+    recoverySecret: Uint8Array;
+    epoch: number;
+};
+/**
+ * Authenticates the MetaMask profile and issues request-bound attestations.
+ */
+export type RecoveryAuthProvider = {
+    getAuthenticatedProfileId: () => Promise<string>;
+    authorizeRecoveryRequest: (params: {
+        requestHash: string;
+        requireTwoFactor?: boolean;
+        identifiers?: Identifier[];
+    }) => Promise<AuthControllerToken>;
+};
+/**
+ * Obtains a key-bound identifier assertion from an IdP (OIDC, Passkey, SIWE).
+ */
+export type RecoveryIdentifierAuthProvider = {
+    getKeyBoundIdentifierToken: (params: {
+        identifier: Identifier;
+        proofPublicKey: string;
+        requestHash: string;
+    }) => Promise<KeyBoundIdentifierToken>;
+};
+/**
+ * One recovery escrow replica. Implementations may talk to different backends.
+ */
+export type RecoveryEscrowProvider = {
+    readonly id: string;
+    /**
+     * P-256 wrap public JWK JSON. Mutation payloads are encrypted to this key;
+     * `getSecret` responses are encrypted to the request's ephemeral key using
+     * the corresponding wrap private key.
+     */
+    readonly wrapPublicKey: string;
+    isAvailable: () => Promise<boolean>;
+    generateChallenge: () => Promise<PoPChallenge>;
+    getSecret: (authorization: IdentifierAuthorization, requestId: string, pkE: EcPublicJwk) => Promise<GetRecoverySecretResponse>;
+    applyMutation: (mutation: Mutation, authControllerToken: AuthControllerToken, identifierAuthorization: IdentifierAuthorization | null, payload: MutationPayload) => Promise<MutationReceipt>;
+    /**
+     * Verifies a receipt cryptographically using the build-pinned receipt key
+     * and confirms it targets the expected escrow.
+     *
+     * @param receipt - Receipt returned by an escrow.
+     * @param mutation - Mutation acknowledged by the receipt.
+     * @param expectedEscrowId - Escrow identity expected by the caller.
+     */
+    verifyReceipt: (receipt: MutationReceipt, mutation: Mutation, expectedEscrowId: string) => boolean;
+};
+/**
+ * Encrypts pending mutation state using wallet secure storage.
+ */
+export type PendingOperationEncryptor = {
+    encrypt: (operation: PendingOperation) => Promise<EncryptedPendingOperation>;
+    decrypt: (ciphertext: EncryptedPendingOperation) => Promise<PendingOperation>;
+};
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,5 @@
+/**
+ * MFA recovery protocol types from the recovery ADR.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG","sourcesContent":["/**\n * MFA recovery protocol types from the recovery ADR.\n */\n\nexport type Identifier = {\n  type: string;\n  namespace: string;\n  value: string;\n  verifier: unknown;\n};\n\nexport type PoPChallenge = {\n  id: string;\n  escrowId: string;\n  /**\n   * Unix time in seconds.\n   */\n  expiresAt: number;\n};\n\nexport type IdentifierAuthMode = 'key-bound';\n\nexport type KeyBoundIdentifierToken = {\n  identifier: Identifier;\n  proofPublicKey: string;\n  requestHash: string;\n  providerAssertion: unknown;\n};\n\nexport type ProofOfPossession = {\n  challengeId: string;\n  requestHash: string;\n  signature: string;\n};\n\n/**\n * Identifier proof presented to an escrow. Only key-bound proofs are wired;\n * escrow-challenge grants land with MFA-605 / MFA-606 / MFA-568.\n */\nexport type IdentifierAuthorization = {\n  kind: 'key-bound';\n  token: KeyBoundIdentifierToken;\n  proof: ProofOfPossession;\n};\n\nexport type MutationOperation =\n  | 'register'\n  | 'updateRecoverySecret'\n  | 'updateIdentifiers';\n\nexport type Mutation = {\n  id: string;\n  profileId: string;\n  operation: MutationOperation;\n  expectedVersion: number;\n  newVersion: number;\n  payloadHash: string;\n  audiences: string[];\n  requestHash: string;\n};\n\nexport type AuthControllerToken = {\n  profileId: string;\n  requestHash: string;\n  twoFactor?: true;\n  identifiersHash?: string;\n  identifierOwnershipApproved?: true;\n  issuer: string;\n  /**\n   * Unix time in seconds.\n   */\n  expiresAt: number;\n  signature: string;\n};\n\nexport type MutationReceipt = {\n  mutationId: string;\n  requestHash: string;\n  escrowId: string;\n  version: number;\n  /**\n   * SHA-256 of the uncompressed receipt public key, as `0x` hex.\n   */\n  receiptKeyId: string;\n  signature: string;\n};\n\n/**\n * P-256 public JWK used as an ephemeral wrap key (`pkE`).\n */\nexport type EcPublicJwk = {\n  kty: 'EC';\n  crv: 'P-256';\n  x: string;\n  y: string;\n};\n\n/**\n * Result of first-factor identifier authentication, consumed by\n * `getRecoverySecret`.\n *\n * The private keys are ephemeral and must only be kept in memory.\n */\nexport type IdentifierSession = {\n  token: KeyBoundIdentifierToken;\n  proofPrivateKey: string;\n  requestId: string;\n  ephemeralPrivateKey: string;\n  pkE: EcPublicJwk;\n};\n\n/**\n * Recovery secret wrapped to one escrow wrap key for transit.\n * `ciphertext` is unprefixed hex of `nonce || ChaCha20-Poly1305(ciphertext+tag)`.\n */\nexport type WrappedSecret = {\n  pkE: EcPublicJwk;\n  ciphertext: string;\n};\n\nexport type WrappedSecretOutput = {\n  ciphertext: string;\n};\n\nexport type RegisterPayload = {\n  recoverySecret: WrappedSecret;\n  identifiers: Identifier[];\n};\n\nexport type UpdateRecoverySecretPayload = Pick<\n  RegisterPayload,\n  'recoverySecret'\n>;\n\nexport type UpdateIdentifiersPayload = Pick<RegisterPayload, 'identifiers'>;\n\n/**\n * Escrow `applyMutation` body. Recovery secrets are wrapped to that escrow's\n * wrap key; do not confuse with {@link PendingMutationPayload}.\n */\nexport type MutationPayload =\n  | RegisterPayload\n  | UpdateRecoverySecretPayload\n  | UpdateIdentifiersPayload;\n\n/**\n * 0x-hex of a plaintext recovery secret. Encrypted pending state stores this\n * logical value; each escrow receives a {@link WrappedSecret} only at apply.\n */\nexport type PendingRecoverySecretHex = string;\n\n/**\n * Logical register payload stored in encrypted pending state.\n */\nexport type PendingRegisterPayload = {\n  identifiers: Identifier[];\n  recoverySecret: PendingRecoverySecretHex;\n};\n\n/**\n * Logical secret-update payload stored in encrypted pending state.\n */\nexport type PendingUpdateRecoverySecretPayload = Pick<\n  PendingRegisterPayload,\n  'recoverySecret'\n>;\n\n/**\n * Logical identifier-update payload stored in encrypted pending state.\n */\nexport type PendingUpdateIdentifiersPayload = Pick<\n  PendingRegisterPayload,\n  'identifiers'\n>;\n\n/**\n * Logical mutation payload persisted in encrypted pending state. Distinct from\n * {@link MutationPayload}, which is the per-escrow apply body.\n */\nexport type PendingMutationPayload =\n  | PendingRegisterPayload\n  | PendingUpdateRecoverySecretPayload\n  | PendingUpdateIdentifiersPayload;\n\ntype PendingOperationBase = {\n  mutation: Mutation;\n  identifier: Identifier | null;\n  payload: PendingMutationPayload;\n};\n\nexport type AuthorizingPendingOperation = PendingOperationBase & {\n  phase: 'authorizing';\n};\n\nexport type WritingPendingOperation = PendingOperationBase & {\n  phase: 'writing';\n  authControllerToken: AuthControllerToken;\n  receipts: MutationReceipt[];\n};\n\nexport type PendingOperation =\n  | AuthorizingPendingOperation\n  | WritingPendingOperation;\n\nexport type RecoveryPhase = 'idle' | PendingOperation['phase'];\n\n/**\n * Encoded ciphertext of {@link PendingOperation}. Wallet secure storage\n * encrypts this blob (including any hex recovery secret). A raw recovery\n * secret is never persisted in BaseController state.\n *\n * The recovery spec's pseudocode represents this as `Uint8Array`, but the\n * controller stores the encoded ciphertext as a string so BaseController state\n * persistence and serialization preserve it without binary coercion.\n */\nexport type EncryptedPendingOperation = string;\n\nexport type GetRecoverySecretResponse = {\n  recoverySecret: WrappedSecretOutput;\n  version: number;\n  lastMutationId: string;\n  wrapKeyId: string;\n};\n\n/**\n * Recovery secret plus the version to use as `epoch` on later mutations.\n */\nexport type RecoveredSecret = {\n  recoverySecret: Uint8Array;\n  epoch: number;\n};\n\n/**\n * Authenticates the MetaMask profile and issues request-bound attestations.\n */\nexport type RecoveryAuthProvider = {\n  getAuthenticatedProfileId: () => Promise<string>;\n  authorizeRecoveryRequest: (params: {\n    requestHash: string;\n    requireTwoFactor?: boolean;\n    identifiers?: Identifier[];\n  }) => Promise<AuthControllerToken>;\n};\n\n/**\n * Obtains a key-bound identifier assertion from an IdP (OIDC, Passkey, SIWE).\n */\nexport type RecoveryIdentifierAuthProvider = {\n  getKeyBoundIdentifierToken: (params: {\n    identifier: Identifier;\n    proofPublicKey: string;\n    requestHash: string;\n  }) => Promise<KeyBoundIdentifierToken>;\n};\n\n/**\n * One recovery escrow replica. Implementations may talk to different backends.\n */\nexport type RecoveryEscrowProvider = {\n  readonly id: string;\n  /**\n   * P-256 wrap public JWK JSON. Mutation payloads are encrypted to this key;\n   * `getSecret` responses are encrypted to the request's ephemeral key using\n   * the corresponding wrap private key.\n   */\n  readonly wrapPublicKey: string;\n  isAvailable: () => Promise<boolean>;\n  generateChallenge: () => Promise<PoPChallenge>;\n  getSecret: (\n    authorization: IdentifierAuthorization,\n    requestId: string,\n    pkE: EcPublicJwk,\n  ) => Promise<GetRecoverySecretResponse>;\n  applyMutation: (\n    mutation: Mutation,\n    authControllerToken: AuthControllerToken,\n    identifierAuthorization: IdentifierAuthorization | null,\n    payload: MutationPayload,\n  ) => Promise<MutationReceipt>;\n  /**\n   * Verifies a receipt cryptographically using the build-pinned receipt key\n   * and confirms it targets the expected escrow.\n   *\n   * @param receipt - Receipt returned by an escrow.\n   * @param mutation - Mutation acknowledged by the receipt.\n   * @param expectedEscrowId - Escrow identity expected by the caller.\n   */\n  verifyReceipt: (\n    receipt: MutationReceipt,\n    mutation: Mutation,\n    expectedEscrowId: string,\n  ) => boolean;\n};\n\n/**\n * Encrypts pending mutation state using wallet secure storage.\n */\nexport type PendingOperationEncryptor = {\n  encrypt: (operation: PendingOperation) => Promise<EncryptedPendingOperation>;\n  decrypt: (ciphertext: EncryptedPendingOperation) => Promise<PendingOperation>;\n};\n"]}

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@metamask-previews/mfa-recovery-controller",
+  "version": "0.0.0-preview-a2f6118d2",
+  "description": "Manages MFA recovery flows across MetaMask clients",
+  "keywords": [
+    "Ethereum",
+    "MetaMask"
+  ],
+  "homepage": "https://github.com/MetaMask/core/tree/main/packages/mfa-recovery-controller#readme",
+  "bugs": {
+    "url": "https://github.com/MetaMask/core/issues"
+  },
+  "license": "(MIT OR Apache-2.0)",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MetaMask/core.git"
+  },
+  "files": [
+    "dist/"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json",
+    "build:all": "tsc --build tsconfig.build.json --verbose",
+    "build:clean": "yarn build:only-clean && yarn build",
+    "build:docs": "typedoc",
+    "build:only-clean": "rimraf './dist' './tsconfig.build.tsbuildinfo'",
+    "changelog:update": "../../scripts/update-changelog.sh @metamask/mfa-recovery-controller",
+    "changelog:validate": "../../scripts/validate-changelog.sh @metamask/mfa-recovery-controller",
+    "lint:tsconfigs": "tsx ../../scripts/lint-tsconfigs/lint-tsconfigs.mts",
+    "lint:tsconfigs:fix": "tsx ../../scripts/lint-tsconfigs/lint-tsconfigs.mts --fix",
+    "messenger-action-types:check": "tsx ../../packages/messenger-cli/src/cli.ts --formatter oxfmt --esm --check",
+    "messenger-action-types:generate": "tsx ../../packages/messenger-cli/src/cli.ts --formatter oxfmt --esm --generate",
+    "since-latest-release": "../../scripts/since-latest-release.sh",
+    "test": "NODE_OPTIONS=--experimental-vm-modules jest --reporters=jest-silent-reporter",
+    "test:clean": "NODE_OPTIONS=--experimental-vm-modules jest --clearCache",
+    "test:verbose": "NODE_OPTIONS=--experimental-vm-modules jest --verbose",
+    "test:watch": "NODE_OPTIONS=--experimental-vm-modules jest --watch"
+  },
+  "dependencies": {
+    "@metamask/base-controller": "^10.0.0",
+    "@metamask/messenger": "^3.0.0",
+    "@metamask/utils": "^12.0.0",
+    "@noble/ciphers": "^1.3.0",
+    "@noble/curves": "^1.9.2",
+    "@noble/hashes": "^1.8.0"
+  },
+  "devDependencies": {
+    "@metamask/auto-changelog": "^6.1.0",
+    "@types/jest": "^30.0.0",
+    "@typescript/native": "npm:typescript@^7.0.2",
+    "deepmerge": "^4.2.2",
+    "jest": "^30.4.2",
+    "rimraf": "^5.0.5",
+    "ts-jest": "^29.4.11",
+    "tsx": "^4.20.5",
+    "typedoc": "^0.25.13",
+    "typedoc-plugin-missing-exports": "^2.0.0",
+    "typescript": "npm:@typescript/typescript6@^6.0.2"
+  },
+  "engines": {
+    "node": "^22.14.0 || ^24"
+  }
+}