@deeeed/metamask-harness 0.28.0 → 0.29.1

package/dist/commands/launch/extension.js

@@ -1,13 +1,19 @@
 import { execFileSync } from "node:child_process";
 import http from "node:http";
 import fs from "node:fs";
+import { createRequire } from "node:module";
 import path from "node:path";
 import {
   depsCheck,
   recordDepsBaseline
 } from "@farmslot/recipe-harness/runtime/deps-readiness";
 import { colorHumanMessage } from "../../cli-color.js";
-import { recipeHarnessPath, recipeRuntimeDir, runnerDir } from "../../paths.js";
+import {
+  importRecipeHarnessRuntimeCdp,
+  recipeHarnessPath,
+  recipeRuntimeDir,
+  runnerDir
+} from "../../paths.js";
 import { extensionIdFromKey } from "../../adapters/extension/extension-id.js";
 import { extensionProductConfigBlock } from "../../adapters/extension/product-config.js";
 import { isExtensionDistStale } from "../../adapters/extension/runtime-decision.js";
@@ -15,6 +21,10 @@ import { checkExtensionRuntimeHealth } from "../../adapters/extension/runtime.js
 import { ensureHarnessFresh } from "../../adapters/harness-freshness.js";
 import { stopExtensionWatcher } from "../../adapters/slot-ports.js";
 import { EXIT, spawnScriptStreaming } from "../shared.js";
+const { CdpSession } = await importRecipeHarnessRuntimeCdp();
+const { RUNTIME_IDENTITY_FILENAME, RUNTIME_NONCE_PREFIX } = createRequire(import.meta.url)(
+  path.join(runnerDir, "adapters/extension/lib/chrome-args.cjs")
+);
 function extensionDepsBlock(target) {
   if (!fs.existsSync(path.join(target, "package.json"))) return null;
   const deps = depsCheck(target);
@@ -73,7 +83,8 @@ async function extensionRuntimeReusable(target) {
   if (isExtensionDistStale(target)) return false;
   for (let attempt = 0; attempt < 3; attempt += 1) {
     const reachable = await cdpVersionReachable(cdpPort);
-    const owned = reachable && cdpOwnedByExpectedRuntime(cdpPort, target);
+    const nonceOwned = reachable && await cdpOwnedByRuntimeNonce(cdpPort, target);
+    const owned = nonceOwned || reachable && cdpOwnedByExpectedRuntime(cdpPort, target);
     const targetPresent = owned && await cdpHasExpectedExtensionTarget(cdpPort, target);
     const healthy = targetPresent && await cdpRuntimeHealthy(cdpPort, target);
     if (healthy) return true;
@@ -88,17 +99,20 @@ function expectedChromeProfile(target) {
 function expectedRuntimeDist(target) {
   return path.resolve(path.join(target, recipeRuntimeDir(), process.env.RECIPE_RUNTIME_DIST_DIR || "runtime-dist"));
 }
-function cdpOwnedByExpectedRuntime(port, target) {
-  let pids = [];
-  try {
-    const out = execFileSync("lsof", ["-nP", `-iTCP:${port}`, "-sTCP:LISTEN", "-t"], {
-      encoding: "utf8",
-      stdio: ["ignore", "pipe", "ignore"]
-    });
-    pids = out.split(/\s+/u).filter((value) => /^\d+$/u.test(value));
-  } catch {
-    return false;
+function commandHasExactFlagValue(command, flag, value) {
+  const expected = `${flag}=${value}`;
+  let offset = command.indexOf(expected);
+  while (offset !== -1) {
+    const before = offset === 0 ? "" : command[offset - 1];
+    const afterOffset = offset + expected.length;
+    const after = afterOffset === command.length ? "" : command[afterOffset];
+    if ((!before || /\s/u.test(before)) && (!after || /\s/u.test(after))) return true;
+    offset = command.indexOf(expected, offset + 1);
   }
+  return false;
+}
+function cdpOwnedByExpectedRuntime(port, target) {
+  const pids = cdpListenerPids(port);
   const profile = expectedChromeProfile(target);
   const runtimeDist = expectedRuntimeDist(target);
   for (const pid of pids) {
@@ -107,7 +121,7 @@ function cdpOwnedByExpectedRuntime(port, target) {
         encoding: "utf8",
         stdio: ["ignore", "pipe", "ignore"]
       });
-      if (command.includes(`--user-data-dir=${profile}`) && (command.includes(`--load-extension=${runtimeDist}`) || command.includes(`--disable-extensions-except=${runtimeDist}`))) {
+      if (commandHasExactFlagValue(command, "--user-data-dir", profile) && (commandHasExactFlagValue(command, "--load-extension", runtimeDist) || commandHasExactFlagValue(command, "--disable-extensions-except", runtimeDist))) {
         return true;
       }
     } catch {
@@ -115,21 +129,118 @@ function cdpOwnedByExpectedRuntime(port, target) {
   }
   return false;
 }
-function cdpVersionReachable(port) {
+async function cdpOwnedByRuntimeNonce(port, target) {
+  const identity = readRuntimeIdentity(port, target);
+  if (!identity) return false;
+  const version = await cdpVersion(port);
+  const webSocketDebuggerUrl = version?.webSocketDebuggerUrl;
+  if (typeof webSocketDebuggerUrl !== "string" || !webSocketDebuggerUrl) return false;
+  let session;
+  try {
+    session = await CdpSession.connect(webSocketDebuggerUrl, { timeoutMs: 2e3 });
+    const result = await boundedBrowserCdpCall(
+      session,
+      "Browser.getBrowserCommandLine",
+      {},
+      2e3
+    );
+    if (!Array.isArray(result.arguments)) return false;
+    const nonceArgs = result.arguments.filter(
+      (argument) => typeof argument === "string" && argument.startsWith(RUNTIME_NONCE_PREFIX)
+    );
+    return nonceArgs.length === 1 && nonceArgs[0] === `${RUNTIME_NONCE_PREFIX}${identity.nonce}`;
+  } catch {
+    return false;
+  } finally {
+    session?.close();
+  }
+}
+async function boundedBrowserCdpCall(session, method, params, timeoutMs) {
+  let timer;
+  try {
+    return await Promise.race([
+      session.call(method, params),
+      new Promise((_resolve, reject) => {
+        timer = setTimeout(
+          () => reject(new Error(`${method} timed out after ${timeoutMs}ms.`)),
+          timeoutMs
+        );
+      })
+    ]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+function readRuntimeIdentity(port, target) {
+  const expectedPort = Number(port);
+  if (!Number.isInteger(expectedPort) || expectedPort <= 0 || expectedPort > 65535) return null;
+  const identityPath = path.join(target, recipeRuntimeDir(), RUNTIME_IDENTITY_FILENAME);
+  let descriptor;
+  try {
+    descriptor = fs.openSync(
+      identityPath,
+      fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW
+    );
+    const stat = fs.fstatSync(descriptor);
+    if (!stat.isFile() || stat.size <= 0 || stat.size > 4096 || (stat.mode & 63) !== 0) {
+      return null;
+    }
+    const parsed = JSON.parse(fs.readFileSync(descriptor, "utf8"));
+    if (parsed.port !== expectedPort || !Number.isInteger(parsed.pid) || Number(parsed.pid) <= 0 || !Number.isInteger(parsed.startedAt) || Number(parsed.startedAt) <= 0 || Number(parsed.startedAt) > Date.now() + 6e4 || typeof parsed.nonce !== "string" || !/^[a-f0-9]{64}$/u.test(parsed.nonce)) {
+      return null;
+    }
+    if (!cdpListenerPids(port).includes(String(parsed.pid))) return null;
+    return parsed;
+  } catch {
+    return null;
+  } finally {
+    if (descriptor !== void 0) fs.closeSync(descriptor);
+  }
+}
+function cdpListenerPids(port) {
+  try {
+    const out = execFileSync("lsof", ["-nP", `-iTCP:${port}`, "-sTCP:LISTEN", "-t"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"]
+    });
+    return out.split(/\s+/u).filter((value) => /^\d+$/u.test(value));
+  } catch {
+    return [];
+  }
+}
+async function cdpVersionReachable(port) {
+  return Boolean(await cdpVersion(port));
+}
+function cdpVersion(port) {
   return new Promise((resolve) => {
     const request = http.get(
       { host: "127.0.0.1", port: Number(port), path: "/json/version", timeout: 2e3 },
       (response) => {
-        response.resume();
-        const code = response.statusCode ?? 0;
-        resolve(code >= 200 && code < 300);
+        let body = "";
+        response.setEncoding("utf8");
+        response.on("data", (chunk) => {
+          body += chunk;
+        });
+        response.on("end", () => {
+          const code = response.statusCode ?? 0;
+          if (code < 200 || code >= 300) {
+            resolve(null);
+            return;
+          }
+          try {
+            const parsed = JSON.parse(body);
+            resolve(parsed && typeof parsed === "object" ? parsed : null);
+          } catch {
+            resolve(null);
+          }
+        });
       }
     );
     request.on("timeout", () => {
       request.destroy();
-      resolve(false);
+      resolve(null);
     });
-    request.on("error", () => resolve(false));
+    request.on("error", () => resolve(null));
   });
 }
 function expectedExtensionId(target) {

package/dist/commands/setup-base.js

@@ -0,0 +1,24 @@
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { runnerDir } from "../paths.js";
+function handleSetupBase(argv) {
+  const script = path.join(runnerDir, "adapters", "shared", "setup-base.sh");
+  const result = spawnSync("bash", [script, ...argv], {
+    cwd: process.cwd(),
+    env: { ...process.env, MM_HARNESS_NODE: process.execPath },
+    stdio: "inherit"
+  });
+  if (result.error) {
+    const code = result.error.code ?? "ESPAWN";
+    process.stderr.write(
+      `setup-base could not start (${code}).
+  Next: npm i -g @deeeed/metamask-harness@latest
+`
+    );
+    return 3;
+  }
+  return result.status ?? 1;
+}
+export {
+  handleSetupBase
+};

package/dist/mm-harness-cli.js

@@ -8,6 +8,7 @@ import { withCommandJournal } from "./command-journal.js";
 import { JsonStreamWriter } from "./json-stream.js";
 import { handleUpdate, maybeNudge } from "./commands/update.js";
 import { handleCallHelp } from "./commands/call.js";
+import { handleSetupBase } from "./commands/setup-base.js";
 import { getAdapterSurface } from "./adapters/surface.js";
 import { detectAdapter } from "./harness.js";
 import {
@@ -20,6 +21,28 @@ globalThis.__MM_HARNESS_WRAPPER__ = true;
 const { main: recipeMain } = await import("./cli.js");
 const rawArgv = process.argv.slice(2);
 const REAL = [
+  {
+    name: "setup-base",
+    summary: "Bootstrap numbered MetaMask product checkouts and install their dependencies.",
+    example: "mm-harness setup-base --only core --counts core=1",
+    helpText: `mm-harness setup-base [flags]
+
+  Bootstrap numbered MetaMask Extension, Mobile, and Core checkouts under one
+  base directory, then run each checkout's pinned dependency install.
+
+  --dir <base>                       Destination root
+  --counts <repo=n,...>              Copies per selected repository
+  --only <extension,mobile,core>     Repository subset
+  --dry-run                          Print the plan without changing anything
+  --force                            Override the free-space refusal
+  --json                             Machine-readable terminal summary
+  --show-config                      Print saved preferences and exit
+  --reset-config                     Remove saved preferences and exit
+  --skip-harness-update              Skip the installed-version notice
+
+Example:
+  mm-harness setup-base --only core --counts core=1`
+  },
   {
     name: "status",
     aliases: ["health", "home"],
@@ -603,7 +626,7 @@ const HELP_GROUPS = [
   {
     title: "MAINTAIN",
     blurb: "keep the installed harness current with the npm registry",
-    commands: ["update"]
+    commands: ["setup-base", "update"]
   }
 ];
 function commandMeta(name) {
@@ -732,7 +755,7 @@ program.command("completions").description("Install/print bundled shell tab-comp
   const result = spawnSync("bash", [script, ...rawArgv.slice(1)], { stdio: "inherit" });
   process.exit(result.status ?? 1);
 });
-const NUDGE_SKIP = ["update", "completions", "completion-candidates"];
+const NUDGE_SKIP = ["setup-base", "update", "completions", "completion-candidates"];
 if (rawArgv.length > 0 && !NUDGE_SKIP.includes(rawArgv[0])) {
   maybeNudge();
 }
@@ -794,6 +817,9 @@ if (rawArgv.length === 0) {
   process.stdout.write(groupedHelp());
   process.exit(0);
 }
+if (rawArgv[0] === "setup-base") {
+  process.exit(handleSetupBase(rawArgv.slice(1)));
+}
 const preflightBypass = /* @__PURE__ */ new Set([
   ...HIDDEN,
   "completions"

package/docs/RECIPES.md

@@ -64,8 +64,33 @@ Rules:
 - Use real product paths; never mutate hidden state to fabricate proof.
 - Prove preparation with an independent read/assert or visible UI postcondition.
 - Keep ticket-specific claims in task-local recipes.
-- Parameterize repeated behavior instead of multiplying names.
+- Compose, repair, or parameterize repeated behavior instead of multiplying names.
 - Keep secrets out of recipes, libraries, and evidence.
+- Limit claims to the boundary actually exercised. In-app navigation cannot
+  prove external ingress, and security-boundary proofs require accepted and
+  rejected cases.
+
+## Classify failures before changing either layer
+
+Recipes are maintained proof assets, not immutable descriptions of the app.
+Locators, labels, routes, and screen structure can legitimately change, so a
+failed recipe is not by itself evidence of either recipe drift or a product
+regression.
+
+1. Reproduce the failing node and compare it with authoritative acceptance
+   criteria, product contracts, or known-good evidence.
+2. Inspect the current product surface and resolved recipe source, then classify
+   the cause as product regression, recipe drift, fixture/runtime drift, or
+   harness defect.
+3. If an accepted product change establishes recipe drift, repair the smallest
+   shared action or recipe node that owns it. Otherwise preserve the failure
+   and fix or report the owning product, runtime, or harness layer.
+4. Rerun the repaired path and every shared recipe that composes it.
+5. Report the classification, owning source, change, and fresh evidence together.
+
+Do not duplicate a stale recipe to avoid maintaining it. Do not change product
+code merely to satisfy an obsolete proof path, or update a recipe merely to
+make a real regression pass.
 
 Keep responsibilities narrow:
 

package/docs/SECURITY.md

@@ -31,6 +31,37 @@ Fixture setup is allowed before the proof window when it is explicit in the
 trace. Mutating setup must finish with a real read/assert or visible UI
 postcondition.
 
+## Signed deeplink boundary
+
+Treat every raw or original URL parameter as attacker-controlled. Route handlers
+may receive only canonical parameters authorized by a valid signature and the
+link's `sig_params` list. Never add a handler fallback to original parameters,
+including for attribution or a destination considered read-only.
+
+Attribution fields such as `utm_*` may pass through only when they are inside
+the signed parameter set, explicitly allowlisted for the destination, and
+validated for bounded length and character format before use.
+
+A publishable signed-deeplink proof covers the whole ingress boundary:
+
+1. a valid, signed, destination-allowlisted, format-valid, within-limit
+   attribution value reaches the destination;
+2. an unsigned candidate parameter reaches neither handler nor destination;
+3. tampering with a signed value causes authorization failure or interstitial
+   demotion, and no candidate parameter reaches handler or destination;
+4. malformed `sig_params` and invalid signatures cause authorization failure or
+   interstitial demotion, and no candidate parameter reaches handler or
+   destination;
+5. a signed attribution key outside the destination allowlist does not reach
+   the destination or attribution context;
+6. signed attribution values with invalid characters or excessive length do
+   not reach the destination or attribution context;
+7. handler observations for accepted links contain canonical values only.
+
+Opening the same route from inside an already-running app proves downstream
+navigation or analytics consumption only. It is not evidence for external link
+parsing, signature verification, or canonicalization.
+
 ## Wallet fixtures
 
 Each checkout has one canonical fixture:

package/library/actions/extension/analytics/consent.mjs

@@ -0,0 +1,203 @@
+export function consentControllerExpression({
+  bridgeSymbol,
+  participate,
+  marketing,
+  timeoutMs,
+}) {
+  return `(async () => {
+    const submit = globalThis.stateHooks?.submitRequestToBackground;
+    const bridgeKey = Symbol.for(${JSON.stringify(bridgeSymbol)});
+    const capturedChrome = globalThis[bridgeKey];
+    let port;
+    let nextId = Date.now();
+    // Popup connections are ref-counted, so temporary ports cannot erase the
+    // live fullscreen or side-panel registration for the same tab.
+    const connectionName = 'popup';
+
+    const rawSubmit = (method, params) => new Promise((resolve, reject) => {
+      if (!port) {
+        if (typeof capturedChrome?.runtime?.connect !== 'function') {
+          reject(new Error('Extension consent setup could not reach the background controller.'));
+          return;
+        }
+        port = capturedChrome.runtime.connect({ name: connectionName });
+      }
+      const id = nextId++;
+      const timer = setTimeout(() => {
+        port.onMessage.removeListener(listener);
+        reject(new Error(method + ' timed out after ${Number(timeoutMs)}ms'));
+      }, ${Number(timeoutMs)});
+      const listener = (message) => {
+        const data = message?.name === 'controller' ? message.data : null;
+        if (data?.id !== id) return;
+        clearTimeout(timer);
+        port.onMessage.removeListener(listener);
+        if (data.error) reject(new Error(JSON.stringify(data.error)));
+        else resolve(data.result);
+      };
+      port.onMessage.addListener(listener);
+      try {
+        port.postMessage({
+          name: 'controller',
+          data: { jsonrpc: '2.0', id, method, params }
+        });
+      } catch (error) {
+        clearTimeout(timer);
+        port.onMessage.removeListener(listener);
+        reject(error);
+      }
+    });
+
+    const callController = typeof submit === 'function' ? submit : rawSubmit;
+    const readBackgroundState = () => new Promise((resolve, reject) => {
+      if (typeof capturedChrome?.runtime?.connect !== 'function') {
+        reject(new Error('Extension consent state is unavailable.'));
+        return;
+      }
+      const statePort = capturedChrome.runtime.connect({ name: connectionName });
+      const timer = setTimeout(() => {
+        statePort.onMessage.removeListener(listener);
+        statePort.disconnect();
+        reject(new Error('Extension consent state timed out after ${Number(timeoutMs)}ms.'));
+      }, ${Number(timeoutMs)});
+      const listener = (message) => {
+        const data = message?.name === 'controller' ? message.data : null;
+        if (data?.method !== 'START_UI_SYNC') return;
+        clearTimeout(timer);
+        statePort.onMessage.removeListener(listener);
+        statePort.disconnect();
+        resolve(data.params?.[0]);
+      };
+      statePort.onMessage.addListener(listener);
+    });
+    const readConsentState = async () => {
+      const hooks = globalThis.stateHooks || {};
+      const storeState = hooks.store?.getState?.();
+      const cleanState = typeof hooks.getCleanAppState === 'function'
+        ? await hooks.getCleanAppState()
+        : undefined;
+      const root = capturedChrome
+        ? await readBackgroundState()
+        : storeState ?? cleanState;
+      if (!root) {
+        throw new Error('Extension consent state is unavailable.');
+      }
+      const metamask = root?.metamask ?? root ?? {};
+      if (
+        typeof metamask.optedIn !== 'boolean' ||
+        typeof metamask.dataCollectionForMarketing !== 'boolean'
+      ) {
+        throw new Error('Extension consent state did not contain boolean consent fields.');
+      }
+      return {
+        state: {
+          optedIn: metamask.optedIn,
+          dataCollectionForMarketing: metamask.dataCollectionForMarketing,
+          analyticsId: metamask.analyticsId ? 'set' : null
+        },
+        source: capturedChrome
+          ? 'background-controller-flat-state'
+          : storeState
+            ? 'debug-page-store'
+            : 'debug-clean-app-state'
+      };
+    };
+    const waitForConsentState = async () => {
+      const expected = {
+        optedIn: ${JSON.stringify(participate)},
+        dataCollectionForMarketing: ${JSON.stringify(marketing)}
+      };
+      const deadline = Date.now() + ${Number(timeoutMs)};
+      let result;
+      do {
+        result = await readConsentState();
+        if (Object.entries(expected).every(([key, value]) => result.state[key] === value)) {
+          return result;
+        }
+        await new Promise((resolve) => setTimeout(resolve, 100));
+      } while (Date.now() < deadline);
+      throw new Error(
+        'Consent state did not settle to ' + JSON.stringify(expected) +
+        '; got ' + JSON.stringify(result?.state) + '.',
+      );
+    };
+    const setMarketing = async (value) => {
+      await callController('setDataCollectionForMarketing', [value]);
+    };
+
+    try {
+      if (!${JSON.stringify(participate)}) await setMarketing(false);
+      const analyticsId = await callController(
+        'setParticipateInMetaMetrics',
+        [${JSON.stringify(participate)}],
+      );
+      if (${JSON.stringify(participate)}) {
+        await setMarketing(${JSON.stringify(marketing)});
+      }
+      const settled = await waitForConsentState();
+      return {
+        analyticsId: analyticsId ? 'set' : null,
+        state: settled.state,
+        stateSource: settled.source
+      };
+    } finally {
+      port?.disconnect();
+      if (capturedChrome) delete globalThis[bridgeKey];
+    }
+  })()`;
+}
+
+export async function withConsentChromeBridge(page, {
+  bridgeSymbol,
+  timeoutMs,
+}, operation) {
+  const preload = await page.session.call('Page.addScriptToEvaluateOnNewDocument', {
+    source: `Object.defineProperty(
+      globalThis,
+      Symbol.for(${JSON.stringify(bridgeSymbol)}),
+      { value: globalThis.chrome, configurable: true }
+    );`,
+  });
+  if (!preload?.identifier) {
+    throw new Error('Extension consent setup could not register its temporary Chrome bridge.');
+  }
+
+  try {
+    let notifyLoaded;
+    const loaded = new Promise((resolve) => {
+      notifyLoaded = resolve;
+    });
+    const unsubscribe = page.session.on('Page.loadEventFired', () => notifyLoaded?.());
+    let reloadTimeout;
+    try {
+      await page.session.call('Page.reload', { ignoreCache: false });
+      await Promise.race([
+        loaded,
+        new Promise((_, reject) => {
+          reloadTimeout = setTimeout(
+            () => reject(new Error(`Extension consent reload timed out after ${timeoutMs}ms.`)),
+            timeoutMs,
+          );
+        }),
+      ]);
+    } finally {
+      clearTimeout(reloadTimeout);
+      unsubscribe();
+    }
+    await page.waitForExpression(
+      `typeof globalThis[Symbol.for(${JSON.stringify(bridgeSymbol)})]?.runtime?.connect === 'function'`,
+      { timeoutMs },
+    );
+    return await operation();
+  } finally {
+    try {
+      await page.session.call('Page.removeScriptToEvaluateOnNewDocument', {
+        identifier: preload.identifier,
+      });
+    } finally {
+      await page.evaluate(
+        `delete globalThis[Symbol.for(${JSON.stringify(bridgeSymbol)})]`,
+      );
+    }
+  }
+}