@deeeed/metamask-harness 0.70.1 → 0.72.0

package/library/actions/shared/console-allowlist-add.mjs

@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+// Write console allowlist entries (schemaVersion 3) from a real capture, so
+// entries are copied from observed events instead of written by hand.
+//
+// Usage:
+//   node console-allowlist-add.mjs <run artifacts dir | capture log> [options]
+//     --allowlist <file>   the library's diagnostics/console-allowlist.json
+//                          (default: from RECIPE_LIBRARY_PATH, first library)
+//     --reason <text>      why these events are noise (required with --write)
+//     --link <url>         code or issue the reason points at
+//     --temporary          the entry goes once a known fix lands
+//     --pick <n,n,...>     the candidates to write (numbers from the listing)
+//     --write              append the picked candidates to the allowlist
+//                          (needs --pick: every entry is a deliberate choice)
+// A run artifacts dir is read through its diagnostics.json: the run's slice of
+// the raw slot capture (diagnostics-app-log.txt is redacted, so its query
+// strings would not match). Without --write it lists the candidates: every
+// warning, error or exception no entry matches yet, one per distinct event.
+
+import { closeSync, fstatSync, openSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import {
+  ALLOWLIST_RELATIVE_PATH,
+  allowlistEntryFor,
+  allowlistMatch,
+  classifyConsoleRecord,
+  consoleRecords,
+  libraryRootsFromEnv,
+  loadConsoleAllowlist,
+} from './console-findings.mjs';
+
+function parseArgs(argv) {
+  const options = { input: null, allowlist: null, reason: null, link: null, temporary: false, pick: null, write: false };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--allowlist') options.allowlist = argv[++index];
+    else if (arg === '--reason') options.reason = argv[++index];
+    else if (arg === '--link') options.link = argv[++index];
+    else if (arg === '--temporary') options.temporary = true;
+    else if (arg === '--pick') options.pick = String(argv[++index]).split(',').map(Number);
+    else if (arg === '--write') options.write = true;
+    else if (!options.input && !arg.startsWith('--')) options.input = arg;
+    else throw new Error(`unknown argument ${arg}`);
+  }
+  if (!options.input) throw new Error('usage: console-allowlist-add.mjs <run artifacts dir | capture log> [--allowlist <file>] [--reason <text>] [--link <url>] [--temporary] [--pick <n,...>] [--write]');
+  return options;
+}
+
+// The capture text a run diagnosed, or a whole log file.
+export function captureText(input) {
+  const run = readJsonOr(path.join(input, 'diagnostics.json'), null);
+  if (run) {
+    const { source } = run;
+    const fd = openSync(source.path, 'r');
+    try {
+      // The same file the run diagnosed: its inode, and long enough.
+      const stat = fstatSync(fd);
+      if ((source.inode !== undefined && source.inode !== stat.ino) || stat.size < source.endOffset) {
+        throw new Error(`${source.path} is not the capture the run diagnosed (it was rotated or replaced since)`);
+      }
+      return readFileSync(fd).subarray(source.startOffset, source.endOffset).toString('utf8');
+    } finally {
+      closeSync(fd);
+    }
+  }
+  return readFileSync(input, 'utf8');
+}
+
+// Distinct events no entry matches yet, as entries without a reason.
+export function allowlistCandidates(text, allowlist = { entries: [] }) {
+  const candidates = new Map();
+  for (const record of consoleRecords(text)) {
+    const finding = classifyConsoleRecord(record);
+    if (!finding || allowlistMatch(finding, allowlist)) continue;
+    const entry = allowlistEntryFor(finding);
+    const id = JSON.stringify(entry);
+    const known = candidates.get(id);
+    if (known) known.count += 1;
+    else candidates.set(id, { entry, level: finding.level, count: 1 });
+  }
+  return [...candidates.values()];
+}
+
+function readJsonOr(file, fallback) {
+  try {
+    return JSON.parse(readFileSync(file, 'utf8'));
+  } catch (error) {
+    if (error?.code === 'ENOENT' || error?.code === 'ENOTDIR') return fallback;
+    throw error;
+  }
+}
+
+export function appendEntries(file, entries) {
+  const document = readJsonOr(file, { schemaVersion: 3, entries: [] });
+  if (document.schemaVersion !== 3) throw new Error(`${file} is schemaVersion ${document.schemaVersion}; convert it to 3 first`);
+  document.entries.push(...entries);
+  writeFileSync(file, `${JSON.stringify(document, null, 2)}\n`);
+}
+
+function main(argv) {
+  const options = parseArgs(argv);
+  const roots = options.allowlist ? [] : libraryRootsFromEnv();
+  const file = options.allowlist ?? (roots[0] ? path.join(roots[0], ALLOWLIST_RELATIVE_PATH) : null);
+  const allowlist = file ? loadConsoleAllowlist([path.dirname(path.dirname(file))]) : { entries: [], problems: [] };
+  const candidates = allowlistCandidates(captureText(options.input), allowlist);
+  const picked = options.pick ? candidates.filter((_, index) => options.pick.includes(index + 1)) : candidates;
+  if (!options.write) {
+    candidates.forEach((candidate, index) => {
+      process.stdout.write(`${index + 1}. ${candidate.level} ×${candidate.count}\n${JSON.stringify(candidate.entry, null, 2)}\n`);
+    });
+    if (candidates.length === 0) process.stdout.write('every warning and error in this capture is already allowlisted\n');
+    return 0;
+  }
+  if (!file) throw new Error('--write needs --allowlist <file> (or RECIPE_LIBRARY_PATH)');
+  if (!options.reason?.trim()) throw new Error('--write needs --reason');
+  if (!options.pick?.length) throw new Error('--write needs --pick <n,...>: choose the candidates to allowlist from the listing');
+  const entries = picked.map(({ entry }) => ({
+    ...entry,
+    reason: options.reason.trim(),
+    ...(options.link ? { link: options.link } : {}),
+    ...(options.temporary ? { temporary: true } : {}),
+  }));
+  appendEntries(file, entries);
+  process.stdout.write(`appended ${entries.length} entr${entries.length === 1 ? 'y' : 'ies'} to ${file}\n`);
+  return 0;
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try {
+    process.exitCode = main(process.argv.slice(2));
+  } catch (error) {
+    process.stderr.write(`console-allowlist-add: ${error.message}\n`);
+    process.exitCode = 2;
+  }
+}

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 });
+}