@deeeed/metamask-harness 0.28.0 → 0.29.0

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 ## Unreleased
 
+## 0.29.0 - 2026-08-01
+
+### Added
+
+- Add `mm-harness setup-base` to bootstrap the shared default MetaMask checkout layout with interactive and scripted selection, persisted preferences, disk checks, dependency installation, and machine-readable summaries.
+- Ship a dependency-free getting-started site with an interactive walkthrough, platform-filterable command reference, architecture guide, tutorials, reviewer evidence guide, and automated browser acceptance and contrast checks.
+
+### Changed
+
+- Upgrade the Farmslot runtime dependencies to their structured suite-evidence releases and converge on protocol 0.15.0.
+
+### Fixed
+
+- Verify Extension MetaMetrics consent from the production background controller's flat state instead of relying on test-only page state hooks.
+- Resolve Extension Perps network state from both flattened and nested controller stores.
+- Update both supported `brace-expansion` lines to their patched releases for CVE-2026-14257.
+- Build the non-test Extension proof runtime with its webpack sources and supported debug hooks, then read wallet actions from clean app state and wait for account selection to converge.
+- Bind Extension runtime reuse to a per-launch nonce echoed by Chrome, with owner-only state, exact process-argument checks, and machine-global quarantine for unproven detached launches; keep validation launches on the invoking runner with checkout-contained runtime files; route Playwright-owned Extension injections through raw CDP; and require the hardened-page-safe recipe harness for page scrolling.
+
 ## 0.28.0 - 2026-07-31
 
 ### Added

package/README.md

@@ -10,6 +10,47 @@ and runtime paths are detected automatically.
 The generic graph engine and evidence schemas live in Farmslot packages.
 `mm-harness` owns MetaMask runtime control and domain capabilities.
 
+## Getting started from zero
+
+No checkouts yet? `mm-harness setup-base` clones the MetaMask product repos into one
+standard layout and runs each repo's own dependency install — no install of this
+package required to start:
+
+```bash
+npx -p @deeeed/metamask-harness mm-harness setup-base
+```
+
+It produces, under `~/dev/metamask` by default:
+
+```text
+metamask-extension-1..N   metamask-mobile-1..N   core-1..N
+```
+
+Run without flags in a terminal, it asks which projects you want and how many
+copies of each. Pass flags to skip the prompt entirely — which is how scripts,
+CI, and parent tools should invoke it:
+
+```bash
+mm-harness setup-base --only core --counts core=1
+mm-harness setup-base --dir ~/work/metamask --counts extension=3,mobile=1,core=2
+mm-harness setup-base --only mobile --dry-run        # plan only, changes nothing
+```
+
+The base directory resolves by precedence: `--dir`, then `$MM_HARNESS_BASE_DIR`,
+then saved preferences, then `~/dev/metamask`. A successful run saves the base
+directory and counts it used, so later runs adopt them — inspect with
+`--show-config`, clear with `--reset-config`. Re-running is safe: existing
+clones are fetched, never reset and never deleted.
+
+**Scope fence.** It clones and installs dependencies. Nothing else — no platform
+toolchains, no simulators, no `.env` files, no builds. Workflow onboarding is a
+prompt; environment readiness is `mm-harness doctor`, which is exactly where it
+points you next.
+
+`setup-base` is a normal command on the single `mm-harness` entrypoint. Its work
+stays in one readable shell leaf, and `npx -p` makes that same command available
+before a global install.
+
 ## Install
 
 ```bash

package/adapters/extension/build-lavamoat.sh

@@ -49,7 +49,8 @@ rm -f "$RUNTIME_DIR/webpack.log" "$RUNTIME_DIR/recipe-harness-webpack.log"
 
 echo "[recipe-harness] clean non-test LavaMoat build"
 rm -rf node_modules/.cache/webpack
-yarn webpack:lavamoat:build
+yarn webpack:tsc
+METAMASK_DEBUG=true yarn webpack:lavamoat:build
 test -f dist/chrome/manifest.json || {
   echo "build-lavamoat: build completed without dist/chrome/manifest.json" >&2
   exit 1

package/adapters/extension/ensure-browser.sh

@@ -200,6 +200,21 @@ kill_profile_processes() {
   fi
 }
 
+# Invalidate the old browser identity before signaling it. A concurrent quick
+# launch must fall through to process ownership while replacement is underway.
+node - "$SCRIPT_DIR/lib/chrome-args.cjs" "$AGENT_DIR" <<'NODE'
+const [modulePath, runtimeDir] = process.argv.slice(2);
+try {
+  require(modulePath).removeRuntimeIdentity(runtimeDir);
+} catch (error) {
+  const detail = error instanceof Error ? error.message : String(error);
+  throw new Error(
+    'Failed to invalidate Extension runtime identity under ' + runtimeDir + ': ' + detail +
+    '. Next: remove the invalid runtime identity and fix owner permissions, then rerun: mm-harness launch --adapter extension --build'
+  );
+}
+NODE
+
 # --- Kill existing browser (by PID only — don't touch other slots) ---
 PREV_PID=$(cat "${AGENT_DIR}/browser.pid" 2>/dev/null || true)
 if [ -n "$PREV_PID" ] && kill -0 "$PREV_PID" 2>/dev/null; then
@@ -275,12 +290,16 @@ exec node -e "
 const path = require('path');
 const fs = require('fs');
 const http = require('http');
-const { execSync, execFileSync } = require('child_process');
+const { execFileSync } = require('child_process');
 let chromium; try { chromium = require('@playwright/test').chromium; } catch { chromium = require('playwright').chromium; }
 const {
   automationRuntimeArgs,
+  createRuntimeIdentityNonce,
   isolatedProfileArgs,
   remoteDebuggingArgs,
+  removeRuntimeIdentity,
+  runtimeIdentityArgs,
+  writeRuntimeIdentity,
 } = require(path.join('${SCRIPT_DIR}', 'lib/chrome-args.cjs'));
 const { captureMacFrontmostProcess, restoreMacFrontmostProcess } = require(path.join('${SCRIPT_DIR}', 'lib/macos-focus.cjs'));
 
@@ -304,11 +323,14 @@ const resumeWebpack = () => {
 };
 
 (async () => {
+  const runtimeNonce = createRuntimeIdentityNonce();
+  const startedAt = Date.now();
   const args = [
     '--user-data-dir=' + PROFILE,
     '--disable-extensions-except=' + EXTENSION,
     '--load-extension=' + EXTENSION,
     ...automationRuntimeArgs(),
+    ...runtimeIdentityArgs(runtimeNonce),
     '--no-first-run',
     '--no-default-browser-check',
     ...isolatedProfileArgs(),
@@ -340,14 +362,63 @@ const resumeWebpack = () => {
   }
   const browser = await chromium.connectOverCDP('http://127.0.0.1:' + CDP_PORT);
   const ctx = browser.contexts()[0];
+  let listenerPids;
   try {
-    const browserPid = execSync('lsof -ti tcp:' + CDP_PORT + ' -sTCP:LISTEN | head -1', { timeout: 2000 }).toString().trim();
-    if (browserPid) {
-      fs.writeFileSync(path.join(AGENT_DIR, 'browser.pid'), browserPid);
-      fs.writeFileSync(path.join(AGENT_DIR, 'chromium.pid'), browserPid);
-      console.log('[reopen] Chromium PID ' + browserPid);
-    }
-  } catch {}
+    listenerPids = execFileSync(
+      'lsof',
+      ['-nP', '-iTCP:' + CDP_PORT, '-sTCP:LISTEN', '-t'],
+      { encoding: 'utf8', timeout: 10000 },
+    ).split(/\s+/).filter((value) => /^\d+$/.test(value));
+  } catch {
+    throw new Error(
+      'Reopened Chrome ownership could not be inspected with lsof. ' +
+      'Next: install or restore lsof, then rerun: mm-harness launch --adapter extension --build'
+    );
+  }
+  let browserPid = '';
+  for (const pid of listenerPids) {
+    try {
+      const command = execFileSync(
+        'ps',
+        ['-ww', '-o', 'command=', '-p', pid],
+        { encoding: 'utf8', timeout: 2000 },
+      );
+      if (
+        command.includes('--user-data-dir=' + PROFILE) &&
+        (
+          command.includes('--load-extension=' + EXTENSION) ||
+          command.includes('--disable-extensions-except=' + EXTENSION)
+        )
+      ) {
+        browserPid = pid;
+        break;
+      }
+    } catch {}
+  }
+  if (!browserPid) {
+    throw new Error(
+      'Reopened Chrome did not expose an owned CDP listener on port ' + CDP_PORT +
+      '. Next: inspect the slot browser process, then rerun: mm-harness launch --adapter extension --build'
+    );
+  }
+  fs.writeFileSync(path.join(AGENT_DIR, 'browser.pid'), browserPid);
+  fs.writeFileSync(path.join(AGENT_DIR, 'chromium.pid'), browserPid);
+  try {
+    writeRuntimeIdentity(AGENT_DIR, {
+      port: Number(CDP_PORT),
+      pid: Number(browserPid),
+      startedAt,
+      nonce: runtimeNonce,
+    });
+  } catch (error) {
+    try { process.kill(Number(browserPid), 'SIGTERM'); } catch {}
+    const detail = error && error.message ? error.message : String(error);
+    throw new Error(
+      'Failed to persist Extension runtime identity under ' + AGENT_DIR + ': ' + detail +
+      '. Next: fix owner write permissions for the runtime directory, then rerun: mm-harness launch --adapter extension --build'
+    );
+  }
+  console.log('[reopen] Chromium PID ' + browserPid);
 
   // Detect extension ID via the recipe-runner — the single source of truth.
   // Deterministic id from the loaded dist's manifest key; replaces a fragile
@@ -371,7 +442,8 @@ const resumeWebpack = () => {
 
   // Set window title to slot ID (persists across SPA navigations)
   const { applyPersistentSlotTitle } = require(path.join('${SCRIPT_DIR}', 'lib/slot-title.cjs'));
-  await page.evaluate(applyPersistentSlotTitle, SLOT_ID);
+  const { evaluatePageViaCdp } = require(path.join('${SCRIPT_DIR}', 'lib/playwright-cdp.cjs'));
+  await evaluatePageViaCdp(page, applyPersistentSlotTitle, SLOT_ID);
 
   // Wait for runtime state to settle, then unlock if needed.
   const unlockSelector = '[data-testid=\"unlock-password\"]';
@@ -438,6 +510,7 @@ const resumeWebpack = () => {
   process.exit(0);
 })().catch(e => {
   resumeWebpack();
+  try { removeRuntimeIdentity(AGENT_DIR); } catch {}
   try { fs.unlinkSync(path.join(AGENT_DIR, 'browser.pid')); } catch {}
   try { fs.unlinkSync(path.join(AGENT_DIR, 'chromium.pid')); } catch {}
   try { fs.unlinkSync(path.join(AGENT_DIR, 'extension.id')); } catch {}

package/adapters/extension/inject.mjs

@@ -126,6 +126,7 @@ copyFile(path.join(runnerDir, 'adapters/shared/tmux-session.sh'), path.join(harn
 copyFile(path.join(runnerDir, 'adapters/shared/tmux-viewer.sh'), path.join(harnessDir, 'scripts/lib/tmux-viewer.sh'));
 copyFile(path.join(runnerDir, 'adapters/shared/log-tui.mjs'), path.join(harnessDir, 'scripts/lib/log-tui.mjs'));
 copyFile(path.join(runnerDir, 'adapters/extension/lib/extension-id.cjs'), path.join(harnessDir, 'scripts/lib/extension-id.cjs'));
+copyFile(path.join(runnerDir, 'adapters/extension/lib/playwright-cdp.cjs'), path.join(harnessDir, 'scripts/lib/playwright-cdp.cjs'));
 copyFile(path.join(runnerDir, 'adapters/extension/lib/slot-title.cjs'), path.join(harnessDir, 'scripts/lib/slot-title.cjs'));
 copyFile(path.join(runnerDir, 'adapters/extension/lib/chrome-args.cjs'), path.join(harnessDir, 'scripts/lib/chrome-args.cjs'));
 copyFile(path.join(runnerDir, 'adapters/extension/lib/macos-focus.cjs'), path.join(harnessDir, 'scripts/lib/macos-focus.cjs'));

package/adapters/extension/launch-browser.cjs

@@ -26,8 +26,19 @@ const { execFileSync, spawn, spawnSync } = require('node:child_process');
 const { extensionIdFromExtensionDir } = require('./lib/extension-id.cjs');
 const {
   automationRuntimeArgs,
+  clearDetachedLaunchUnproven,
+  clearValidationPortQuarantine,
+  createRuntimeIdentityNonce,
+  hasDetachedLaunchUnproven,
   isolatedProfileArgs,
+  markDetachedLaunchUnproven,
+  markValidationPortLaunchUnproven,
   remoteDebuggingArgs,
+  removeRuntimeIdentity,
+  runtimeIdentityArgs,
+  readValidationPortQuarantine,
+  validationLaunchQuarantineError,
+  writeRuntimeIdentity,
 } = require('./lib/chrome-args.cjs');
 const { captureMacFrontmostProcess, restoreMacFrontmostProcess } = require('./lib/macos-focus.cjs');
 
@@ -46,6 +57,7 @@ if (!Number.isInteger(cdpPort) || cdpPort <= 0) {
 for (const key of ['chrome-bin', 'profile', 'extension-dir', 'chrome-log', 'chrome-pid']) {
   if (!args[key]) throw new Error(`Missing --${key}`);
 }
+const runtimeDir = path.dirname(path.resolve(args['extension-dir']));
 // --stop-only releases the profile before the dist snapshot exists on a first
 // run, so launch-input validation applies only to a real launch.
 if (args['stop-only'] === undefined) {
@@ -80,6 +92,15 @@ if (foreignPids.length > 0) {
 const ownedPids = new Set(listenerPids);
 const previousPid = readPidFile(args['chrome-pid']);
 if (previousPid !== null && processIsOwnedHarnessBrowser(previousPid, args.profile, args['extension-dir'])) ownedPids.add(previousPid);
+try {
+  removeRuntimeIdentity(runtimeDir);
+} catch (error) {
+  const detail = error instanceof Error ? error.message : String(error);
+  throw new Error(
+    `Failed to invalidate Extension runtime identity under ${runtimeDir}: ${detail}. ` +
+      'Next: remove the invalid runtime identity and fix owner permissions, then rerun: mm-harness launch --adapter extension --build',
+  );
+}
 terminatePids([...ownedPids]);
 if (args['reset-profile'] !== undefined) {
   fs.rmSync(args.profile, { recursive: true, force: true });
@@ -95,7 +116,25 @@ if (args['stop-only'] !== undefined) {
   process.exit(0);
 }
 
+const requestedProfileQuarantined = hasDetachedLaunchUnproven(args.profile);
+const portQuarantine = readValidationPortQuarantine(cdpPort);
+const validationPortLease = process.env.MM_HARNESS_VALIDATION_PORT_LEASE;
+const activeValidationLease = Boolean(
+  portQuarantine?.profile === path.resolve(args.profile) &&
+  portQuarantine.lease === validationPortLease &&
+  /^[a-f0-9]{64}$/u.test(validationPortLease || ''),
+);
+if (requestedProfileQuarantined || (portQuarantine && !activeValidationLease)) {
+  throw validationLaunchQuarantineError(
+    cdpPort,
+    portQuarantine?.profile || (requestedProfileQuarantined ? args.profile : undefined),
+    requestedProfileQuarantined ? args.profile : undefined,
+  );
+}
+
 const initialUrl = args['start-url'] || extensionHomeUrl(args['extension-dir']) || 'chrome://extensions/';
+const runtimeNonce = createRuntimeIdentityNonce();
+const startedAt = Date.now();
 const chromeArgs = [
   `--user-data-dir=${args.profile}`,
   // Debug-port trio (address + port + scoped allow-origins) from the shared module,
@@ -104,6 +143,7 @@ const chromeArgs = [
   '--no-first-run',
   '--disable-first-run-ui',
   ...automationRuntimeArgs(),
+  ...runtimeIdentityArgs(runtimeNonce),
   ...isolatedProfileArgs(),
   '--disable-default-apps',
   '--disable-popup-blocking',
@@ -123,6 +163,7 @@ let browserPid;
 try {
   const application = process.platform === 'darwin' ? macApplicationForExecutable(args['chrome-bin']) : null;
   if (application) {
+    beginDetachedLaunch(cdpPort, args.profile, activeValidationLease);
     execFileSync('open', ['-g', '-n', '-a', application, '--args', ...chromeArgs], {
       env: sanitizedChildEnv(),
       stdio: ['ignore', logFd, logFd],
@@ -132,18 +173,46 @@ try {
       throw new Error(`Chrome launched but did not expose CDP on 127.0.0.1:${cdpPort}`);
     }
   } else {
+    beginDetachedLaunch(cdpPort, args.profile, activeValidationLease);
     const child = spawn(args['chrome-bin'], chromeArgs, {
       detached: true,
       env: sanitizedChildEnv(),
       stdio: ['ignore', logFd, logFd],
     });
     child.unref();
-    browserPid = child.pid;
+    browserPid = waitForOwnedCdpPid(cdpPort, args.profile, args['extension-dir']);
+    if (browserPid === null) {
+      if (child.pid) terminatePids([child.pid]);
+      throw new Error(
+        `Chrome launched but did not expose an owned CDP listener on 127.0.0.1:${cdpPort}. ` +
+          `Next: inspect ${args['chrome-log']}, then rerun: mm-harness launch --adapter extension --build`,
+      );
+    }
   }
 } finally {
   fs.closeSync(logFd);
 }
 fs.writeFileSync(args['chrome-pid'], `${browserPid}\n`);
+try {
+  writeRuntimeIdentity(runtimeDir, {
+    port: cdpPort,
+    pid: browserPid,
+    startedAt,
+    nonce: runtimeNonce,
+  });
+  clearDetachedLaunchUnproven(args.profile);
+  if (!activeValidationLease) {
+    clearValidationPortQuarantine(cdpPort, args.profile);
+  }
+} catch (error) {
+  terminatePids([browserPid]);
+  fs.rmSync(args['chrome-pid'], { force: true });
+  const detail = error instanceof Error ? error.message : String(error);
+  throw new Error(
+    `Failed to persist Extension runtime identity under ${runtimeDir}: ${detail}. ` +
+      'Next: fix owner write permissions for the runtime directory, then rerun: mm-harness launch --adapter extension --build',
+  );
+}
 if (process.platform === 'darwin') {
   const wake = spawn('caffeinate', ['-dimsu', '-w', String(browserPid)], {
     detached: true,
@@ -167,6 +236,19 @@ function sanitizedChildEnv() {
   };
 }
 
+function beginDetachedLaunch(port, profile, activeLease) {
+  try {
+    if (!activeLease) markValidationPortLaunchUnproven(port, profile);
+    markDetachedLaunchUnproven(profile);
+  } catch (error) {
+    if (error.code === 'EEXIST') {
+      const quarantine = readValidationPortQuarantine(port);
+      throw validationLaunchQuarantineError(port, quarantine?.profile || profile);
+    }
+    throw error;
+  }
+}
+
 function macApplicationForExecutable(executable) {
   let current = path.resolve(executable);
   while (current !== path.dirname(current)) {