@deeeed/metamask-harness 0.35.0 → 0.37.0

package/library/actions/shared/wallet/import-source.mjs

@@ -0,0 +1,101 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+
+import { mnemonicToAccount } from 'viem/accounts';
+
+import { walletFixturePath } from '../../harness-exports.mjs';
+
+const ENV_NAME = /^[A-Z_][A-Z0-9_]*$/u;
+
+function environmentValue(input, name) {
+  if (!ENV_NAME.test(name)) {
+    throw new Error(`Wallet import environment name is invalid: ${name}`);
+  }
+  return input.context?.env?.[name] ?? process.env[name];
+}
+
+async function optionalFixture(projectRoot) {
+  const absolutePath = walletFixturePath(projectRoot);
+  try {
+    return {
+      absolutePath,
+      relativePath: path.relative(projectRoot, absolutePath),
+      value: JSON.parse(await readFile(absolutePath, 'utf8')),
+    };
+  } catch (error) {
+    if (error?.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+export async function resolveWalletImportCredentials(input) {
+  const source = String(input.node?.credential_source ?? 'auto');
+  if (!['auto', 'environment', 'fixture'].includes(source)) {
+    throw new Error('metamask.wallet.import credential_source must be auto, environment, or fixture.');
+  }
+
+  const srpEnv = String(input.node?.srp_env ?? 'MM_HARNESS_WALLET_SRP');
+  const passwordEnv = String(input.node?.password_env ?? 'MM_HARNESS_WALLET_PASSWORD');
+  const environmentMnemonic = source === 'fixture'
+    ? undefined
+    : environmentValue(input, srpEnv)?.trim();
+  const environmentPassword = source === 'fixture'
+    ? undefined
+    : environmentValue(input, passwordEnv);
+  const fixture = source === 'environment' || (environmentMnemonic && environmentPassword)
+    ? null
+    : await optionalFixture(input.context.projectRoot);
+  const fixtureMnemonic = source === 'environment'
+    ? undefined
+    : fixture?.value?.accounts?.find((account) => account?.type === 'mnemonic')?.value?.trim();
+  const mnemonic = environmentMnemonic || fixtureMnemonic;
+  const password = environmentPassword ||
+    (source === 'environment' ? undefined : fixture?.value?.password);
+
+  if (!mnemonic) {
+    throw new Error(
+      `Wallet import requires ${srpEnv} or a mnemonic account in temp/recipe/runtime/wallet-fixture.json.\n` +
+        `  Next: export ${srpEnv}=<secret-recovery-phrase>`,
+    );
+  }
+  if (typeof password !== 'string' || password.length === 0) {
+    throw new Error(
+      `Wallet import requires ${passwordEnv} or password in temp/recipe/runtime/wallet-fixture.json.\n` +
+        `  Next: export ${passwordEnv}=<wallet-password>`,
+    );
+  }
+
+  let expectedAddress;
+  try {
+    expectedAddress = mnemonicToAccount(mnemonic).address.toLowerCase();
+  } catch {
+    throw new Error('Wallet import Secret Recovery Phrase is invalid.');
+  }
+
+  return {
+    mnemonic,
+    password,
+    expectedAddress,
+    source: environmentMnemonic ? 'environment' : 'fixture',
+    sourceName: environmentMnemonic ? srpEnv : fixture?.relativePath,
+  };
+}
+
+export function walletImportMethod(input) {
+  const method = String(input.node?.method ?? 'auto');
+  if (!['auto', 'profile', 'ui'].includes(method)) {
+    throw new Error('metamask.wallet.import method must be auto, profile, or ui.');
+  }
+  return method;
+}
+
+export function validateWalletImportOptions(platform, node) {
+  const interests = Array.isArray(node?.interests) ? node.interests : [];
+  const metametrics = node?.metametrics === true || node?.metametrics === 'true';
+  if (platform === 'extension' && interests.length > 0) {
+    throw new Error('Wallet import interests are supported only on Mobile.');
+  }
+  if (platform === 'mobile' && interests.length > 0 && !metametrics) {
+    throw new Error('Mobile onboarding interests require metametrics=true.');
+  }
+}

package/library/manifests/extension.action-manifest.json

@@ -1099,6 +1099,45 @@
       ],
       "execution_capabilities": []
     },
+    "metamask.wallet.validate_import": {
+      "description": "Validate wallet recovery credentials and derive the expected primary address without launching or mutating the app.",
+      "schema": {
+        "type": "object",
+        "properties": {
+          "credential_source": {
+            "type": "string",
+            "enum": ["auto", "environment", "fixture"]
+          },
+          "srp_env": {
+            "type": "string"
+          },
+          "password_env": {
+            "type": "string"
+          },
+          "metametrics": {
+            "type": "boolean"
+          },
+          "interests": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          }
+        },
+        "additionalProperties": false
+      },
+      "examples": [
+        {
+          "action": "metamask.wallet.validate_import",
+          "credential_source": "auto",
+          "intent": "Validate recovery credentials before resetting a wallet",
+          "next": "done"
+        }
+      ],
+      "execution_capabilities": [
+        "host-read-export"
+      ]
+    },
     "metamask.wallet.setup": {
       "description": "Import the wallet fixture accounts and password so the app starts from a known signed-in state.",
       "schema": {
@@ -1117,6 +1156,94 @@
         "app-mutation"
       ]
     },
+    "metamask.wallet.import": {
+      "description": "Make the wallet ready by reusing a fixture-backed profile or importing the primary mnemonic through visible onboarding UI.",
+      "schema": {
+        "type": "object",
+        "properties": {
+          "method": {
+            "type": "string",
+            "enum": ["auto", "profile", "ui"]
+          },
+          "credential_source": {
+            "type": "string",
+            "enum": ["auto", "environment", "fixture"]
+          },
+          "srp_env": {
+            "type": "string"
+          },
+          "password_env": {
+            "type": "string"
+          },
+          "metametrics": {
+            "type": "boolean",
+            "default": false,
+            "description": "Enable MetaMetrics during visible onboarding."
+          },
+          "biometrics": {
+            "type": "boolean",
+            "default": false,
+            "description": "Mobile-only biometric onboarding preference; ignored on Extension."
+          },
+          "notifications": {
+            "type": "boolean",
+            "default": false,
+            "description": "Mobile-only push notification onboarding preference; ignored on Extension."
+          },
+          "skip_wallet_tour": {
+            "type": "boolean",
+            "default": true,
+            "description": "Mobile-only wallet-home tour preference; ignored on Extension."
+          },
+          "interests": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "enum": ["swap_tokens", "trade_perpetuals", "prediction_markets", "send_receive_crypto", "earn_and_spend", "use_other_crypto_apps"]
+            },
+            "default": [],
+            "description": "Mobile-only onboarding interests; ignored when empty on Extension."
+          },
+          "timeout_ms": {
+            "type": "number"
+          }
+        },
+        "additionalProperties": false
+      },
+      "examples": [
+        {
+          "action": "metamask.wallet.import",
+          "method": "auto",
+          "intent": "Use an existing fixture profile or import through onboarding",
+          "next": "done"
+        }
+      ],
+      "execution_capabilities": [
+        "app-mutation"
+      ]
+    },
+    "metamask.wallet.reset": {
+      "description": "Delete the current wallet through the visible client reset flow and reach fresh onboarding.",
+      "schema": {
+        "type": "object",
+        "properties": {
+          "timeout_ms": {
+            "type": "number"
+          }
+        },
+        "additionalProperties": false
+      },
+      "examples": [
+        {
+          "action": "metamask.wallet.reset",
+          "intent": "Reset the wallet through visible UI before importing it again",
+          "next": "done"
+        }
+      ],
+      "execution_capabilities": [
+        "app-mutation"
+      ]
+    },
     "metamask.wallet.ensure_unlocked": {
       "description": "Unlock the wallet with the fixture password when it is currently locked.",
       "schema": {
@@ -1321,6 +1448,107 @@
       ],
       "execution_capabilities": []
     },
+    "metamask.perps.read_snapshot": {
+      "description": "Read a bounded, redacted snapshot of live Extension Perps state through product background APIs.",
+      "schema": {
+        "type": "object",
+        "properties": {
+          "include": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "enum": [
+                "account",
+                "markets",
+                "positions",
+                "orders",
+                "history",
+                "watchlist"
+              ]
+            },
+            "minItems": 1,
+            "default": [
+              "account",
+              "markets",
+              "positions",
+              "orders",
+              "history",
+              "watchlist"
+            ],
+            "description": "Sections to request. Every requested section must be available or the action fails."
+          },
+          "market": {
+            "type": "string",
+            "description": "Optional single market filter."
+          },
+          "markets": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "maxItems": 100,
+            "description": "Optional market filters applied to market-scoped sections."
+          },
+          "history": {
+            "type": "object",
+            "properties": {
+              "start_time_ms": {
+                "type": "integer",
+                "minimum": 0,
+                "description": "Inclusive history start time in Unix milliseconds. Defaults to 30 days before end_time_ms."
+              },
+              "end_time_ms": {
+                "type": "integer",
+                "minimum": 0,
+                "description": "Inclusive history end time in Unix milliseconds. Defaults to the current time."
+              },
+              "account_id": {
+                "type": "string",
+                "description": "Optional CAIP account ID passed to the product history API; the value is not returned."
+              },
+              "limit": {
+                "type": "integer",
+                "minimum": 1,
+                "default": 100,
+                "description": "Maximum history items returned after product filtering."
+              }
+            },
+            "additionalProperties": false
+          },
+          "max_items_per_section": {
+            "type": "integer",
+            "minimum": 1,
+            "default": 100,
+            "description": "Maximum normalized items returned for each requested list section."
+          },
+          "timeout_ms": {
+            "type": "integer",
+            "minimum": 1000,
+            "default": 20000,
+            "description": "Per-request background API timeout."
+          }
+        },
+        "additionalProperties": false
+      },
+      "examples": [
+        {
+          "action": "metamask.perps.read_snapshot",
+          "include": [
+            "account",
+            "markets",
+            "positions",
+            "orders"
+          ],
+          "markets": [
+            "BTC",
+            "ETH"
+          ],
+          "intent": "Read the bounded Perps state needed for release validation",
+          "next": "done"
+        }
+      ],
+      "execution_capabilities": []
+    },
     "metamask.perps.read_positions": {
       "description": "extension Read live Perps positions; without a selector, return all live positions.",
       "schema": {

package/library/manifests/mobile.action-manifest.json

@@ -1237,6 +1237,45 @@
       ],
       "execution_capabilities": []
     },
+    "metamask.wallet.validate_import": {
+      "description": "Validate wallet recovery credentials and derive the expected primary address without launching or mutating the app.",
+      "schema": {
+        "type": "object",
+        "properties": {
+          "credential_source": {
+            "type": "string",
+            "enum": ["auto", "environment", "fixture"]
+          },
+          "srp_env": {
+            "type": "string"
+          },
+          "password_env": {
+            "type": "string"
+          },
+          "metametrics": {
+            "type": "boolean"
+          },
+          "interests": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          }
+        },
+        "additionalProperties": false
+      },
+      "examples": [
+        {
+          "action": "metamask.wallet.validate_import",
+          "credential_source": "auto",
+          "intent": "Validate recovery credentials before resetting a wallet",
+          "next": "done"
+        }
+      ],
+      "execution_capabilities": [
+        "host-read-export"
+      ]
+    },
     "metamask.wallet.setup": {
       "description": "Import the wallet fixture accounts and password so the app starts from a known signed-in state.",
       "schema": {
@@ -1253,6 +1292,91 @@
       ],
       "execution_capabilities": ["app-mutation"]
     },
+    "metamask.wallet.import": {
+      "description": "Make the wallet ready by reusing a fixture-backed profile or importing the primary mnemonic through visible onboarding UI.",
+      "schema": {
+        "type": "object",
+        "properties": {
+          "method": {
+            "type": "string",
+            "enum": ["auto", "profile", "ui"]
+          },
+          "credential_source": {
+            "type": "string",
+            "enum": ["auto", "environment", "fixture"]
+          },
+          "srp_env": {
+            "type": "string"
+          },
+          "password_env": {
+            "type": "string"
+          },
+          "metametrics": {
+            "type": "boolean",
+            "default": false,
+            "description": "Enable MetaMetrics during visible onboarding."
+          },
+          "biometrics": {
+            "type": "boolean",
+            "enum": [false],
+            "default": false,
+            "description": "Biometric authentication is disabled because unattended recipes cannot satisfy the device prompt."
+          },
+          "notifications": {
+            "type": "boolean",
+            "default": false,
+            "description": "Enable push notifications during Mobile onboarding; defaults off."
+          },
+          "skip_wallet_tour": {
+            "type": "boolean",
+            "default": true,
+            "description": "Skip the Mobile wallet-home tour after onboarding; defaults on so recipes reach a usable wallet."
+          },
+          "interests": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "enum": ["swap_tokens", "trade_perpetuals", "prediction_markets", "send_receive_crypto", "earn_and_spend", "use_other_crypto_apps"]
+            },
+            "default": [],
+            "description": "Select optional onboarding interests; an empty list skips the questionnaire."
+          },
+          "timeout_ms": {
+            "type": "number"
+          }
+        },
+        "additionalProperties": false
+      },
+      "examples": [
+        {
+          "action": "metamask.wallet.import",
+          "method": "auto",
+          "intent": "Use an existing fixture profile or import through onboarding",
+          "next": "done"
+        }
+      ],
+      "execution_capabilities": ["app-mutation"]
+    },
+    "metamask.wallet.reset": {
+      "description": "Delete the current wallet through the visible client reset flow and reach fresh onboarding.",
+      "schema": {
+        "type": "object",
+        "properties": {
+          "timeout_ms": {
+            "type": "number"
+          }
+        },
+        "additionalProperties": false
+      },
+      "examples": [
+        {
+          "action": "metamask.wallet.reset",
+          "intent": "Reset the wallet through visible UI before importing it again",
+          "next": "done"
+        }
+      ],
+      "execution_capabilities": ["app-mutation"]
+    },
     "metamask.wallet.ensure_unlocked": {
       "description": "Unlock the wallet with the fixture password when it is currently locked.",
       "schema": {

package/library/recipes/extension/runner/action-validation.recipe.json

@@ -158,11 +158,22 @@
       },
       "perps-navigate-market": {
         "action": "ui.navigate",
-        "next": "start-state",
+        "next": "read-snapshot",
         "intent": "Show the ETH Perps market details",
         "page": "perps-market",
         "market": "ETH"
       },
+      "read-snapshot": {
+        "action": "metamask.perps.read_snapshot",
+        "include": [
+          "markets"
+        ],
+        "markets": [
+          "ETH"
+        ],
+        "next": "start-state",
+        "intent": "Read a bounded live Perps market snapshot"
+      },
       "ensure-clean": {
         "action": "metamask.perps.ensure_positions",
         "market": "ETH",

package/library/recipes/wallet/import.recipe.json

@@ -0,0 +1,102 @@
+{
+  "$schema": "https://farmslot.io/schemas/recipe-v1.schema.json",
+  "title": "Import or reuse a MetaMask wallet",
+  "description": "Make a Mobile or Extension wallet ready by reusing its fixture-backed profile or importing the primary mnemonic through visible onboarding UI.",
+  "paramsSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "method": {
+        "type": "string",
+        "enum": ["auto", "profile", "ui"],
+        "default": "auto",
+        "description": "Choose automatically from visible wallet state, require an existing profile, or require real-user onboarding UI."
+      },
+      "credential_source": {
+        "type": "string",
+        "enum": ["auto", "environment", "fixture"],
+        "default": "auto",
+        "description": "Read secrets from the named environment variables first, or require one source explicitly."
+      },
+      "srp_env": {
+        "type": "string",
+        "default": "MM_HARNESS_WALLET_SRP",
+        "description": "Environment variable containing the Secret Recovery Phrase; the value is never stored in the recipe or evidence."
+      },
+      "password_env": {
+        "type": "string",
+        "default": "MM_HARNESS_WALLET_PASSWORD",
+        "description": "Environment variable containing the wallet password; the value is never stored in the recipe or evidence."
+      },
+      "metametrics": {
+        "type": "boolean",
+        "default": false,
+        "description": "Enable MetaMetrics during visible onboarding; defaults off."
+      },
+      "biometrics": {
+        "type": "boolean",
+        "enum": [false],
+        "default": false,
+        "description": "Keep Mobile biometric authentication disabled for unattended validation."
+      },
+      "notifications": {
+        "type": "boolean",
+        "default": false,
+        "description": "Enable Mobile push notifications during onboarding; defaults off."
+      },
+      "skip_wallet_tour": {
+        "type": "boolean",
+        "default": true,
+        "description": "Skip the Mobile wallet-home tour so the recipe ends at a usable wallet."
+      },
+      "interests": {
+        "type": "array",
+        "items": {
+          "type": "string",
+          "enum": ["swap_tokens", "trade_perpetuals", "prediction_markets", "send_receive_crypto", "earn_and_spend", "use_other_crypto_apps"]
+        },
+        "default": [],
+        "description": "Mobile-only onboarding interests; an empty list skips the optional questionnaire."
+      },
+      "timeout_ms": {
+        "type": "number",
+        "default": 300000,
+        "description": "Maximum time for each onboarding transition and final wallet readiness."
+      }
+    }
+  },
+  "workflow": {
+    "entry": "fixture-status",
+    "nodes": {
+      "fixture-status": {
+        "action": "metamask.wallet.fixture_status",
+        "intent": "Record whether a canonical fixture is available without exposing its secrets",
+        "next": "import"
+      },
+      "import": {
+        "action": "metamask.wallet.import",
+        "method": "{{params.method}}",
+        "credential_source": "{{params.credential_source}}",
+        "srp_env": "{{params.srp_env}}",
+        "password_env": "{{params.password_env}}",
+        "metametrics": "{{params.metametrics}}",
+        "biometrics": "{{params.biometrics}}",
+        "notifications": "{{params.notifications}}",
+        "skip_wallet_tour": "{{params.skip_wallet_tour}}",
+        "interests": "{{params.interests}}",
+        "timeout_ms": "{{params.timeout_ms}}",
+        "intent": "Reuse the fixture-backed wallet or import it through the visible onboarding flow",
+        "next": "state"
+      },
+      "state": {
+        "action": "metamask.wallet.read_state",
+        "intent": "Prove the wallet has a selected account after setup",
+        "next": "done"
+      },
+      "done": {
+        "action": "end",
+        "status": "pass"
+      }
+    }
+  }
+}