@deeeed/metamask-harness 0.35.0 → 0.36.0

package/library/actions/mobile/wallet/import.mjs

@@ -0,0 +1,259 @@
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+import { resolveWalletImportCredentials, validateWalletImportOptions, walletImportMethod } from '../../shared/wallet/import-source.mjs';
+import {
+  bridgeCommand,
+  runAdapter,
+  selectBridgeStatusEntry,
+} from '../platform/bridge.mjs';
+import { setMobileConsent } from '../analytics/consent-settings.mjs';
+import { ensureUnlocked } from './ensure_unlocked.mjs';
+
+const TEST_IDS = {
+  existingWallet: 'wallet-setup-screen-have-an-existing-wallet-button-id',
+  importSeed: 'onboarding-sheet-import-seed-button-id',
+  srp: 'phrase-input-id',
+  continue: 'import-from-seed-screen-continue-button-id',
+  password: 'create-password-first-input-field',
+  confirmPassword: 'create-password-second-input-field',
+  passwordTerms: 'password-understand-box',
+  createPassword: 'submit-button',
+  metricsCheckbox: 'optin-metrics-metrics-checkbox',
+  metricsContinue: 'optin-metrics-continue-button-id',
+  interestSkip: 'onboarding-interest-skip-button',
+  interestContinue: 'onboarding-interest-continue-button',
+  successDone: 'onboarding-success-done-button',
+};
+
+const INTEREST_IDS = new Set([
+  'swap_tokens',
+  'trade_perpetuals',
+  'prediction_markets',
+  'send_receive_crypto',
+  'earn_and_spend',
+  'use_other_crypto_apps',
+]);
+
+function selectedEntry(status, input) {
+  return selectBridgeStatusEntry(status, input) ?? {};
+}
+
+function selectedAddress(status, input) {
+  return String(selectedEntry(status, input)?.account?.address ?? '').toLowerCase();
+}
+
+function walletReady(observed, input) {
+  const route = String(selectedEntry(observed, input)?.route?.name ?? '');
+  return Boolean(
+    selectedAddress(observed, input) &&
+    route &&
+    route !== 'Login' &&
+    route !== 'Onboarding' &&
+    route !== 'OptinMetrics' &&
+    route !== 'OnboardingInterestQuestionnaire'
+    && route !== 'OnboardingSuccess'
+  );
+}
+
+async function waitForPostPasswordScreen(input, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  let observed;
+  while (Date.now() <= deadline) {
+    observed = await status(input);
+    const route = String(selectedEntry(observed, input)?.route?.name ?? '');
+    if (
+      route === 'OptinMetrics' ||
+      route === 'OnboardingInterestQuestionnaire' ||
+      route === 'OnboardingSuccess' ||
+      walletReady(observed, input)
+    ) return { route, observed };
+    await new Promise((resolve) => setTimeout(resolve, 250));
+  }
+  const route = String(selectedEntry(observed, input)?.route?.name ?? 'unknown');
+  throw new Error(`Mobile onboarding did not advance after password creation from ${route}.`);
+}
+
+async function status(input) {
+  return bridgeCommand(input, ['status-selected']);
+}
+
+async function waitForCommand(input, args, timeoutMs, label) {
+  const deadline = Date.now() + timeoutMs;
+  let lastError;
+  while (Date.now() <= deadline) {
+    try {
+      const result = await bridgeCommand(input, args);
+      if (result?.ok !== false) return result;
+      lastError = result?.error;
+    } catch (error) {
+      lastError = error;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 250));
+  }
+  throw new Error(`${label} was not available before the wallet import timeout: ${String(lastError?.message ?? lastError ?? 'unknown')}`);
+}
+
+async function press(input, testId, timeoutMs) {
+  return waitForCommand(input, ['press-test-id', testId], timeoutMs, testId);
+}
+
+async function setSecretInput(input, testId, value, timeoutMs) {
+  const directory = await mkdtemp(path.join(os.tmpdir(), 'mm-harness-wallet-import-'));
+  const file = path.join(directory, 'value');
+  try {
+    await writeFile(file, value, { mode: 0o600 });
+    return await waitForCommand(
+      input,
+      ['set-input-file', testId, file],
+      timeoutMs,
+      testId,
+    );
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+}
+
+async function waitForInterestDecision(input, timeoutMs) {
+  const deadline = Date.now() + Math.min(timeoutMs, 10000);
+  let observed;
+  while (Date.now() <= deadline) {
+    observed = await status(input);
+    const route = String(selectedEntry(observed, input)?.route?.name ?? '');
+    if (route === 'OnboardingInterestQuestionnaire') return { available: true, observed };
+    if (route === 'OnboardingSuccess') return { available: false, observed };
+    if (walletReady(observed, input)) return { available: false, observed };
+    await new Promise((resolve) => setTimeout(resolve, 250));
+  }
+  const route = String(selectedEntry(observed, input)?.route?.name ?? 'unknown');
+  throw new Error(`Mobile onboarding did not reach the interests screen or wallet home from ${route}.`);
+}
+
+async function importThroughUi(input, timeoutMs) {
+  const credentials = await resolveWalletImportCredentials(input);
+  const metametricsEnabled = input.node?.metametrics === true || input.node?.metametrics === 'true';
+  const interests = Array.isArray(input.node?.interests)
+    ? input.node.interests.map((value) => String(value))
+    : [];
+  const invalidInterest = interests.find((value) => !INTEREST_IDS.has(value));
+  if (invalidInterest) throw new Error(`Unsupported Mobile onboarding interest: ${invalidInterest}.`);
+  await press(input, TEST_IDS.existingWallet, timeoutMs);
+  try {
+    await setSecretInput(input, TEST_IDS.srp, credentials.mnemonic, 3000);
+  } catch {
+    await press(input, TEST_IDS.importSeed, timeoutMs);
+    await setSecretInput(input, TEST_IDS.srp, credentials.mnemonic, timeoutMs);
+  }
+  await press(input, TEST_IDS.continue, timeoutMs);
+  await setSecretInput(input, TEST_IDS.password, credentials.password, timeoutMs);
+  await setSecretInput(input, TEST_IDS.confirmPassword, credentials.password, timeoutMs);
+  await press(input, TEST_IDS.passwordTerms, timeoutMs);
+  await press(input, TEST_IDS.createPassword, timeoutMs);
+
+  const postPassword = await waitForPostPasswordScreen(input, timeoutMs);
+  if (postPassword.route === 'OptinMetrics') {
+    if (!metametricsEnabled) await press(input, TEST_IDS.metricsCheckbox, timeoutMs);
+    await press(input, TEST_IDS.metricsContinue, timeoutMs);
+  }
+
+  const interestDecision = await waitForInterestDecision(input, timeoutMs);
+  if (!interestDecision.available && interests.length > 0) {
+    throw new Error('Mobile onboarding interests were requested, but the questionnaire is not enabled for this build.');
+  }
+  if (interestDecision.available && interests.length > 0) {
+    for (const interest of interests) {
+      await press(input, `onboarding-interest-option-${interest}`, timeoutMs);
+    }
+    await press(input, TEST_IDS.interestContinue, timeoutMs);
+  } else if (interestDecision.available) {
+    await press(input, TEST_IDS.interestSkip, timeoutMs);
+  }
+
+  const afterInterests = await status(input);
+  if (String(selectedEntry(afterInterests, input)?.route?.name ?? '') === 'OnboardingSuccess') {
+    await press(input, TEST_IDS.successDone, timeoutMs);
+  }
+
+  const deadline = Date.now() + timeoutMs;
+  let observed = await status(input);
+  while (Date.now() <= deadline) {
+    if (walletReady(observed, input)) break;
+    await new Promise((resolve) => setTimeout(resolve, 250));
+    observed = await status(input);
+  }
+  const actualAddress = selectedAddress(observed, input);
+  if (actualAddress !== credentials.expectedAddress) {
+    throw new Error(`Wallet import selected ${actualAddress || 'no address'}, expected ${credentials.expectedAddress}.`);
+  }
+  const { consent } = await setMobileConsent(
+    input,
+    metametricsEnabled,
+    false,
+    Math.min(timeoutMs, 30000),
+  );
+  const actualMetametricsEnabled = consent.optedIn === true;
+  await bridgeCommand(input, ['navigate', 'WalletView']);
+  observed = await status(input);
+  if (!walletReady(observed, input)) {
+    throw new Error('Mobile wallet import could not return to wallet home after applying MetaMetrics consent.');
+  }
+  return { credentials, observed, metametricsEnabled: actualMetametricsEnabled, interests };
+}
+
+runAdapter(async (input) => {
+  validateWalletImportOptions('mobile', input.node);
+  const method = walletImportMethod(input);
+  const timeoutMs = Number(input.node?.timeout_ms ?? 60000);
+  const before = await status(input);
+  const entry = selectedEntry(before, input);
+  const address = selectedAddress(before, input);
+  const route = String(entry?.route?.name ?? '');
+  const onboarding = route === 'Onboarding' || (!address && route !== 'Login');
+
+  if (method === 'ui' && !onboarding) {
+    throw new Error('metamask.wallet.import method=ui requires a fresh Mobile onboarding state.');
+  }
+  if (onboarding) {
+    if (method === 'profile') {
+      throw new Error('metamask.wallet.import method=profile found a fresh Mobile onboarding state.');
+    }
+    const imported = await importThroughUi(input, timeoutMs);
+    const importedEntry = selectedEntry(imported.observed, input);
+    return {
+      action: input.action,
+      method: 'ui-import',
+      credentialSource: imported.credentials.source,
+      credentialSourceName: imported.credentials.sourceName,
+      selectedAddress: importedEntry.account.address,
+      route: importedEntry.route ?? null,
+      metametricsEnabled: imported.metametricsEnabled,
+      interests: imported.interests,
+      redacted: true,
+      proofPath: 'mobile-visible-onboarding-import',
+    };
+  }
+
+  const credentials = await resolveWalletImportCredentials(input);
+  const unlocked = await ensureUnlocked({
+    ...input,
+    node: {
+      ...input.node,
+      ...(route === 'Login' ? { password: credentials.password } : {}),
+    },
+  });
+  const actualAddress = String(unlocked.account?.address ?? address).toLowerCase();
+  if (actualAddress !== credentials.expectedAddress) {
+    throw new Error(`Wallet profile selected ${actualAddress || 'no address'}, expected ${credentials.expectedAddress}.`);
+  }
+  return {
+    action: input.action,
+    method: 'profile',
+    credentialSource: credentials.source,
+    credentialSourceName: credentials.sourceName,
+    selectedAddress: unlocked.account?.address ?? address,
+    route: unlocked.route ?? entry.route ?? null,
+    redacted: true,
+    proofPath: 'mobile-fixture-profile',
+  };
+});

package/library/actions/mobile/wallet/reset-helper.mjs

@@ -0,0 +1,99 @@
+import {
+  bridgeCommand,
+  selectBridgeStatusEntry,
+} from '../platform/bridge.mjs';
+
+const TEST_IDS = {
+  existingWallet: 'wallet-setup-screen-have-an-existing-wallet-button-id',
+  forgotPassword: 'reset-wallet-button',
+  resetWallet: 'forgot-password-modal-reset-wallet-button',
+  confirmReset: 'forgot-password-modal-yes-reset-wallet-button',
+};
+
+function selectedEntry(status, input) {
+  return selectBridgeStatusEntry(status, input) ?? {};
+}
+
+function walletState(status, input) {
+  const entry = selectedEntry(status, input);
+  return {
+    address: String(entry?.account?.address ?? '').toLowerCase(),
+    route: String(entry?.route?.name ?? ''),
+  };
+}
+
+async function isFreshWallet(status, input) {
+  const state = walletState(status, input);
+  if (state.route !== 'Onboarding') return false;
+  return bridgeCommand(input, ['eval', `(() => {
+    const hook = globalThis.__REACT_DEVTOOLS_GLOBAL_HOOK__;
+    const rootsFor = hook?.getFiberRoots;
+    if (!hook?.renderers || typeof rootsFor !== 'function') return false;
+    const walk = (fiber) => {
+      if (!fiber) return false;
+      if (fiber.memoizedProps?.testID === ${JSON.stringify(TEST_IDS.existingWallet)}) return true;
+      return walk(fiber.child) || walk(fiber.sibling);
+    };
+    for (const [id] of hook.renderers) {
+      for (const root of rootsFor(id) ?? []) {
+        if (walk(root.current)) return true;
+      }
+    }
+    return false;
+  })()`]);
+}
+
+async function waitForCommand(input, args, timeoutMs, label) {
+  const deadline = Date.now() + timeoutMs;
+  let lastError;
+  while (Date.now() <= deadline) {
+    try {
+      const result = await bridgeCommand(input, args);
+      if (result?.ok !== false) return result;
+      lastError = result?.error;
+    } catch (error) {
+      lastError = error;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 250));
+  }
+  throw new Error(`${label} was not available before the wallet reset timeout: ${String(lastError?.message ?? lastError ?? 'unknown')}`);
+}
+
+async function waitForFreshWallet(input, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  let observed;
+  while (Date.now() <= deadline) {
+    observed = await bridgeCommand(input, ['status-selected']);
+    if (await isFreshWallet(observed, input)) return observed;
+    await new Promise((resolve) => setTimeout(resolve, 250));
+  }
+  const state = walletState(observed, input);
+  throw new Error(`Mobile wallet reset did not reach fresh onboarding; route=${state.route || 'unknown'} account=${state.address || 'none'}.`);
+}
+
+export async function resetMobileWalletThroughUi(input) {
+  const timeoutMs = Number(input.node?.timeout_ms ?? 60000);
+  const before = await bridgeCommand(input, ['status-selected']);
+  if (await isFreshWallet(before, input)) {
+    return {
+      alreadyFresh: true,
+      route: walletState(before, input).route,
+      redacted: true,
+      proofPath: 'mobile-visible-wallet-reset',
+    };
+  }
+
+  if (walletState(before, input).route !== 'Login') {
+    await bridgeCommand(input, ['navigate', 'Login']);
+  }
+  await waitForCommand(input, ['press-test-id', TEST_IDS.forgotPassword], timeoutMs, TEST_IDS.forgotPassword);
+  await waitForCommand(input, ['press-test-id', TEST_IDS.resetWallet], timeoutMs, TEST_IDS.resetWallet);
+  await waitForCommand(input, ['press-test-id', TEST_IDS.confirmReset], timeoutMs, TEST_IDS.confirmReset);
+  const after = await waitForFreshWallet(input, timeoutMs);
+  return {
+    alreadyFresh: false,
+    route: walletState(after, input).route,
+    redacted: true,
+    proofPath: 'mobile-visible-wallet-reset',
+  };
+}

package/library/actions/mobile/wallet/reset.mjs

@@ -0,0 +1,7 @@
+import { runAdapter } from '../platform/bridge.mjs';
+import { resetMobileWalletThroughUi } from './reset-helper.mjs';
+
+runAdapter(async (input) => ({
+  action: input.action,
+  ...(await resetMobileWalletThroughUi(input)),
+}));

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,79 @@
         "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."
+          },
+          "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": {