@deeeed/metamask-harness 0.70.1 → 0.71.0

package/library/actions/shared/console-collector.mjs

@@ -0,0 +1,230 @@
+// The console collector (adapters/extension/console-tail.mjs) behind run
+// diagnostics and assert_no_console_errors: how a collector is recognised as
+// this runtime's own, and the evidence that it is capturing. A process is
+// only ever signalled or trusted when its command line proves it is
+// console-tail.mjs writing this runtime's log with this runtime's owner marker.
+
+import { spawnSync } from 'node:child_process';
+import { createHash, randomUUID } from 'node:crypto';
+import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const COLLECTOR_SCRIPT_NAME = 'console-tail.mjs';
+// Logged in the app page to prove its console reaches the capture file.
+export const CAPTURE_CONTROL_MARK = '[mm-harness-capture-control]';
+
+// Same derivation as ownerMarker('console-collector', …) in
+// adapters/terminal/lib/processes.mjs, so the terminal stop path finds it.
+export function collectorOwnerMarker(runtimeDir) {
+  const id = createHash('sha256').update(path.resolve(runtimeDir)).digest('hex').slice(0, 32);
+  return `--mm-harness-owner=console-collector-${id}`;
+}
+
+export function processCommand(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return null;
+  try {
+    process.kill(pid, 0);
+  } catch {
+    return null;
+  }
+  const result = spawnSync('ps', ['-ww', '-p', String(pid), '-o', 'command='], { encoding: 'utf8' });
+  const command = result.status === 0 ? result.stdout.trim() : '';
+  return command || null;
+}
+
+export function readPid(pidFile) {
+  try {
+    const pid = Number.parseInt(readFileSync(pidFile, 'utf8').trim(), 10);
+    return Number.isInteger(pid) && pid > 0 ? pid : null;
+  } catch {
+    return null;
+  }
+}
+
+// This checkout's collector script: the only script a process may run to be
+// adopted as this runtime's collector.
+export const COLLECTOR_SCRIPT_PATH = fileURLToPath(new URL('../../../adapters/extension/console-tail.mjs', import.meta.url));
+
+// A process's command line and the script it runs (its argv[1]), or null.
+// Linux: /proc/<pid>/cmdline, exact. macOS: ps shows the arguments joined
+// with spaces (a path may contain spaces), so argv[1] is what follows
+// argv[0] (ps comm) up to " --cdp-port "; an argv[1] starting with "-" is a
+// node option (node -e …), never a script.
+export function processArgs(pid) {
+  const command = processCommand(pid);
+  if (!command) return null;
+  let script = null;
+  let args = null;
+  try {
+    const argv = readFileSync(`/proc/${pid}/cmdline`, 'utf8').split('\0').filter((arg, index, all) => index < all.length - 1 || arg);
+    script = argv[1] ?? null;
+    args = argv.slice(1).join(' ');
+  } catch {
+    const comm = spawnSync('ps', ['-ww', '-p', String(pid), '-o', 'comm='], { encoding: 'utf8' }).stdout?.trim();
+    if (comm && command.startsWith(`${comm} `)) {
+      args = command.slice(comm.length + 1);
+      const end = args.indexOf(' --cdp-port ');
+      script = end > 0 ? args.slice(0, end) : null;
+    }
+  }
+  // args: everything from argv[1] on, joined with spaces.
+  return script && !script.startsWith('-') ? { command, script, args } : { command, script: null, args: null };
+}
+
+function sameFile(a, b) {
+  try {
+    return realpathSync(a) === realpathSync(b);
+  } catch {
+    return false;
+  }
+}
+
+// The command line (ps joins the arguments with spaces and a path may
+// contain spaces, so it is never split on whitespace): each value is matched
+// together with the argument that follows it, in the order
+// ensureConsoleCollector starts the collector:
+//   <node> <dir>/console-tail.mjs --cdp-port <port> --extension-log <log>
+//     --dapp-log <log> <owner marker>
+const writesExtensionLog = (command, extensionLog) => command.includes(` --extension-log ${extensionLog} --dapp-log `);
+
+// This runtime's collector: running this checkout's console-tail.mjs (argv[1],
+// resolved), writing this extension log, with this runtime's owner marker.
+export function isOwnedCollector(proc, { extensionLog, marker, script = COLLECTOR_SCRIPT_PATH }) {
+  return Boolean(proc?.script) && sameFile(proc.script, script) && writesExtensionLog(proc.command, extensionLog) && proc.command.endsWith(` ${marker}`);
+}
+
+// A collector started before collectors carried owner markers, writing this
+// runtime's extension log (that path lies in this runtime's directory): its
+// argv[1] is a console-tail.mjs, from whichever harness started it.
+export function isLegacyCollector(proc, { extensionLog }) {
+  return Boolean(proc?.script) && path.basename(proc.script) === COLLECTOR_SCRIPT_NAME &&
+    writesExtensionLog(proc.command, extensionLog) && !proc.command.includes('--mm-harness-owner=');
+}
+
+const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
+
+// This runtime's collector started by another install of the harness (the
+// installed mm-harness and an MM_HARNESS_BIN checkout, say): argv[1] is a
+// console-tail.mjs other than this checkout's, and the rest of the arguments
+// are exactly the sequence a harness starts it with, for this runtime's
+// extension log and owner marker. It is retired before a replacement starts;
+// a process failing any of this (node -e, another runtime) is left alone.
+export function isPriorInstallCollector(proc, { extensionLog, marker, script = COLLECTOR_SCRIPT_PATH }) {
+  if (!proc?.script || !proc.args || path.basename(proc.script) !== COLLECTOR_SCRIPT_NAME || sameFile(proc.script, script)) return false;
+  return new RegExp(`^${escapeRegExp(proc.script)} --cdp-port \\d+ --extension-log ${escapeRegExp(extensionLog)} --dapp-log \\S(?:.*\\S)? ${escapeRegExp(marker)}$`, 'u').test(proc.args);
+}
+
+// ...on this CDP port and these logs: the whole argument list, exactly.
+export function collectorMatches(proc, { script = COLLECTOR_SCRIPT_PATH, cdpPort, extensionLog, pageLog, marker }) {
+  return isOwnedCollector(proc, { extensionLog, marker, script }) &&
+    proc.command.endsWith(` ${proc.script} --cdp-port ${cdpPort} --extension-log ${extensionLog} --dapp-log ${pageLog} ${marker}`);
+}
+
+// Is this runtime's collector running (on this CDP port)? { ok, pid, detail }
+export function collectorStatus({ pidFile, extensionLog, marker, cdpPort, script = COLLECTOR_SCRIPT_PATH }) {
+  const pid = readPid(pidFile);
+  if (!pid) return { ok: false, pid: null, detail: `no console collector pid in ${pidFile}` };
+  const proc = processArgs(pid);
+  if (!proc) return { ok: false, pid, detail: `console collector pid ${pid} is not running` };
+  if (!isOwnedCollector(proc, { extensionLog, marker, script })) return { ok: false, pid, detail: `pid ${pid} is not this runtime's console collector` };
+  if (cdpPort && !proc.command.includes(` --cdp-port ${cdpPort} --extension-log `)) {
+    return { ok: false, pid, detail: `console collector pid ${pid} watches another CDP port than ${cdpPort}` };
+  }
+  return { ok: true, pid, detail: `console collector pid ${pid} on CDP ${cdpPort ?? '?'}` };
+}
+
+function originOf(url) {
+  try {
+    return new URL(String(url)).origin;
+  } catch {
+    return null;
+  }
+}
+
+function fileSize(file) {
+  try {
+    return statSync(file).size;
+  } catch {
+    return 0;
+  }
+}
+
+function evaluateOnce(webSocketUrl, expression, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    const socket = new WebSocket(webSocketUrl);
+    const timer = setTimeout(() => {
+      try { socket.close(); } catch { /* closing */ }
+      reject(new Error('timed out'));
+    }, timeoutMs);
+    const done = (error) => {
+      clearTimeout(timer);
+      try { socket.close(); } catch { /* closing */ }
+      if (error) reject(error);
+      else resolve();
+    };
+    socket.addEventListener('open', () => socket.send(JSON.stringify({ id: 1, method: 'Runtime.evaluate', params: { expression } })));
+    socket.addEventListener('message', (event) => {
+      let message;
+      try {
+        message = JSON.parse(String(event.data));
+      } catch {
+        return;
+      }
+      if (message.id === 1) done(message.error ? new Error('the page refused the evaluation') : null);
+    });
+    socket.addEventListener('error', () => done(new Error('CDP connection failed')));
+  });
+}
+
+// The control check: log a marked line in a target the collector should be
+// attached to and wait for it in that target's capture file. Proves the
+// capture works now, for that file. { ok, detail }
+//   page       an http(s) page on appOrigin  -> the page log
+//   extension  MetaMask's service worker or one of its pages, by MetaMask's
+//              extension id (another extension, such as Chrome's own
+//              component extensions, proves nothing) -> the extension log
+// Details name only the expected target and log file, never values read from
+// the browser.
+export async function verifyCapture({ cdpPort, log, target: kind = 'page', appOrigin = null, extensionId = null, timeoutMs = 8000 }) {
+  const port = Number.parseInt(String(cdpPort), 10);
+  if (!(port > 0 && port < 65536)) return { ok: false, detail: `invalid CDP port ${JSON.stringify(cdpPort)}` };
+  if (kind === 'extension' && !/^[a-p]{32}$/u.test(String(extensionId ?? ''))) {
+    return { ok: false, detail: 'no MetaMask extension id is recorded for this slot (injected signer, or MetaMask was never launched)' };
+  }
+  const origin = kind === 'page' ? originOf(appOrigin) : null;
+  const label = kind === 'page' ? `${origin} page` : 'MetaMask extension';
+  let targets;
+  try {
+    const response = await fetch(`http://127.0.0.1:${port}/json/list`, { signal: AbortSignal.timeout(3000) });
+    targets = await response.json();
+  } catch (error) {
+    return { ok: false, detail: `CDP ${port} is not reachable to verify the ${label} console capture (${error.name})` };
+  }
+  const candidates = (Array.isArray(targets) ? targets : []).filter((target) => target.webSocketDebuggerUrl && (kind === 'page'
+    ? target.type === 'page' && originOf(target.url) === origin
+    : ['service_worker', 'page'].includes(target.type) && String(target.url).startsWith(`chrome-extension://${extensionId}/`)));
+  // The service worker first: it lives as long as the extension.
+  const chosen = candidates.find((target) => target.type === 'service_worker') ?? candidates[0];
+  if (!chosen) return { ok: false, detail: `no ${label} target is open to verify the console capture` };
+  const nonce = randomUUID();
+  const start = fileSize(log);
+  try {
+    await evaluateOnce(chosen.webSocketDebuggerUrl, `console.info(${JSON.stringify(`${CAPTURE_CONTROL_MARK} ${nonce}`)})`, 3000);
+  } catch (error) {
+    return { ok: false, detail: `could not log the capture control line in the ${label} (${error.message})` };
+  }
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (existsSync(log)) {
+      const text = readFileSync(log);
+      if (text.subarray(Math.min(start, text.length)).includes(nonce)) return { ok: true, detail: `control line from the ${label} reached ${path.basename(log)}` };
+    }
+    await new Promise((resolve) => setTimeout(resolve, 200));
+  }
+  return { ok: false, detail: `the capture control line logged in the ${label} did not reach ${log} within ${timeoutMs}ms` };
+}
+
+export function verifyPageCapture({ cdpPort, pageLog, appOrigin, timeoutMs }) {
+  return verifyCapture({ cdpPort, log: pageLog, target: 'page', appOrigin, timeoutMs });
+}