@deeeed/metamask-harness 0.28.0 → 0.29.0

package/adapters/extension/lib/chrome-args.cjs

@@ -1,4 +1,11 @@
 'use strict';
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const RUNTIME_IDENTITY_FILENAME = 'extension-runtime-identity.json';
+const RUNTIME_NONCE_PREFIX = '--mm-harness-runtime-nonce=';
+const DETACHED_LAUNCH_UNPROVEN_FILENAME = '.mm-harness-detached-launch-unproven';
 // chrome-args.cjs — single source of truth for the remote-debugging launch flags
 // shared by BOTH extension launchers: the fresh spawn (launch-browser.cjs) and the
 // reopen path (ensure-browser.sh → reopen-browser.sh). Keeping the debug-port trio
@@ -38,4 +45,321 @@ function automationRuntimeArgs() {
   ];
 }
 
-module.exports = { automationRuntimeArgs, isolatedProfileArgs, remoteDebuggingArgs };
+function createRuntimeIdentityNonce() {
+  return crypto.randomBytes(32).toString('hex');
+}
+
+function runtimeIdentityArgs(nonce) {
+  if (!/^[a-f0-9]{64}$/u.test(nonce)) {
+    throw new Error('runtimeIdentityArgs: nonce must be 32 bytes encoded as lowercase hex');
+  }
+  return ['--enable-automation', `${RUNTIME_NONCE_PREFIX}${nonce}`];
+}
+
+function runtimeIdentityPath(runtimeDir) {
+  return path.join(path.resolve(runtimeDir), RUNTIME_IDENTITY_FILENAME);
+}
+
+function detachedLaunchUnprovenPath(profile) {
+  return path.join(path.resolve(profile), DETACHED_LAUNCH_UNPROVEN_FILENAME);
+}
+
+function validationPortQuarantineRoot() {
+  if (typeof process.getuid !== 'function') {
+    throw new Error('Extension validation port quarantine requires a POSIX user identity.');
+  }
+  const uid = process.getuid();
+  const root = path.join(fs.realpathSync('/tmp'), `mm-harness-extension-validation-${uid}`);
+  try {
+    fs.mkdirSync(root, { mode: 0o700 });
+  } catch (error) {
+    if (error.code !== 'EEXIST') throw error;
+  }
+  const stat = fs.lstatSync(root);
+  if (
+    stat.isSymbolicLink() ||
+    !stat.isDirectory() ||
+    stat.uid !== uid ||
+    (stat.mode & 0o777) !== 0o700
+  ) {
+    throw new Error(`Extension validation quarantine root is not an owner-only directory: ${root}`);
+  }
+  return root;
+}
+
+function validationPortQuarantinePath(port) {
+  const numericPort = Number(port);
+  if (!Number.isInteger(numericPort) || numericPort <= 0 || numericPort > 65535) {
+    throw new Error(`validationPortQuarantinePath: invalid cdp port: ${port}`);
+  }
+  return path.join(validationPortQuarantineRoot(), `port-${numericPort}.json`);
+}
+
+function readValidationPortQuarantine(port) {
+  const destination = validationPortQuarantinePath(port);
+  let descriptor;
+  try {
+    descriptor = fs.openSync(destination, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+    const stat = fs.fstatSync(descriptor);
+    if (
+      !stat.isFile() ||
+      stat.uid !== process.getuid() ||
+      stat.size <= 0 ||
+      stat.size > 4_096 ||
+      (stat.mode & 0o777) !== 0o600
+    ) {
+      return { path: destination };
+    }
+    const value = JSON.parse(fs.readFileSync(descriptor, 'utf8'));
+    if (
+      value.schemaVersion !== 1 ||
+      value.port !== Number(port) ||
+      typeof value.profile !== 'string' ||
+      (value.lease !== undefined && !/^[a-f0-9]{64}$/u.test(value.lease))
+    ) {
+      return { path: destination };
+    }
+    return {
+      path: destination,
+      profile: value.profile,
+      ...(value.lease === undefined ? {} : { lease: value.lease }),
+    };
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    return { path: destination };
+  } finally {
+    if (descriptor !== undefined) fs.closeSync(descriptor);
+  }
+}
+
+function writeValidationPortQuarantine(port, profile, reason, allowExisting, lease) {
+  const destination = validationPortQuarantinePath(port);
+  const pending = path.join(
+    path.dirname(destination),
+    `.port-${Number(port)}.${process.pid}.${crypto.randomBytes(16).toString('hex')}.pending`,
+  );
+  let descriptor;
+  try {
+    descriptor = fs.openSync(
+      pending,
+      fs.constants.O_WRONLY |
+        fs.constants.O_CREAT |
+        fs.constants.O_EXCL |
+        fs.constants.O_NOFOLLOW,
+      0o600,
+    );
+    fs.fchmodSync(descriptor, 0o600);
+    fs.writeFileSync(descriptor, `${JSON.stringify({
+      schemaVersion: 1,
+      port: Number(port),
+      profile: path.resolve(profile),
+      reason: String(reason).slice(0, 1_024),
+      ...(lease === undefined ? {} : { lease }),
+    })}\n`, 'utf8');
+    fs.fsyncSync(descriptor);
+    fs.closeSync(descriptor);
+    descriptor = undefined;
+    fs.linkSync(pending, destination);
+    return destination;
+  } catch (error) {
+    if (allowExisting && error.code === 'EEXIST') return destination;
+    throw error;
+  } finally {
+    if (descriptor !== undefined) {
+      try {
+        fs.closeSync(descriptor);
+      } catch {}
+    }
+    try {
+      fs.unlinkSync(pending);
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+    }
+  }
+}
+
+function markValidationPortLaunchUnproven(port, profile, lease) {
+  if (lease !== undefined && !/^[a-f0-9]{64}$/u.test(lease)) {
+    throw new Error('markValidationPortLaunchUnproven: invalid lease');
+  }
+  return writeValidationPortQuarantine(
+    port,
+    profile,
+    'A detached browser launch was submitted but ownership was not proven.',
+    false,
+    lease,
+  );
+}
+
+function quarantineValidationPort(port, profile, reason) {
+  return writeValidationPortQuarantine(port, profile, reason, true, undefined);
+}
+
+function clearValidationPortQuarantine(port, profile, lease) {
+  const quarantine = readValidationPortQuarantine(port);
+  if (!quarantine) return;
+  if (
+    quarantine.profile !== path.resolve(profile) ||
+    (quarantine.lease !== undefined && quarantine.lease !== lease)
+  ) {
+    throw new Error(`Extension validation port ${port} is quarantined for another or invalid profile.`);
+  }
+  fs.unlinkSync(quarantine.path);
+}
+
+function shellQuote(value) {
+  return `'${String(value).replaceAll("'", `'"'"'`)}'`;
+}
+
+function validationLaunchQuarantineError(port, ownerProfile, requestedProfile) {
+  const portMarker = validationPortQuarantinePath(port);
+  const profiles = [...new Set([ownerProfile, requestedProfile]
+    .filter((profile) => typeof profile === 'string')
+    .map((profile) => path.resolve(profile)))];
+  const markers = [
+    ...profiles.map(detachedLaunchUnprovenPath),
+    portMarker,
+  ];
+  const profileText = profiles.length > 0 ? ` or profile ${profiles.join(' or ')}` : '';
+  return new Error(
+    `Refusing to launch on CDP port ${port} because its detached browser state is quarantined. ` +
+      `Next: confirm no browser uses port ${port}${profileText}, then run: rm -- ${markers.map(shellQuote).join(' ')}`,
+  );
+}
+
+function writeDetachedLaunchMarker(profile, reason, allowExisting) {
+  const destination = detachedLaunchUnprovenPath(profile);
+  fs.mkdirSync(path.dirname(destination), { recursive: true });
+  let descriptor;
+  try {
+    descriptor = fs.openSync(
+      destination,
+      fs.constants.O_WRONLY |
+        fs.constants.O_CREAT |
+        fs.constants.O_EXCL |
+        fs.constants.O_NOFOLLOW,
+      0o600,
+    );
+    fs.fchmodSync(descriptor, 0o600);
+    fs.writeFileSync(descriptor, `${reason}\n`, 'utf8');
+    fs.fsyncSync(descriptor);
+    fs.closeSync(descriptor);
+    return destination;
+  } catch (error) {
+    if (descriptor !== undefined) {
+      try {
+        fs.closeSync(descriptor);
+      } catch {}
+    }
+    if (allowExisting && error.code === 'EEXIST') return destination;
+    throw error;
+  }
+}
+
+function markDetachedLaunchUnproven(profile) {
+  return writeDetachedLaunchMarker(
+    profile,
+    'A detached browser launch was submitted but ownership was not proven.',
+    false,
+  );
+}
+
+function quarantineDetachedLaunch(profile, reason) {
+  return writeDetachedLaunchMarker(profile, reason, true);
+}
+
+function hasDetachedLaunchUnproven(profile) {
+  return fs.lstatSync(detachedLaunchUnprovenPath(profile), { throwIfNoEntry: false }) !== undefined;
+}
+
+function clearDetachedLaunchUnproven(profile) {
+  const destination = detachedLaunchUnprovenPath(profile);
+  const stat = fs.lstatSync(destination, { throwIfNoEntry: false });
+  if (!stat) return;
+  if (stat.isSymbolicLink() || !stat.isFile()) {
+    throw new Error(`Detached launch marker is not a regular file: ${destination}`);
+  }
+  fs.unlinkSync(destination);
+}
+
+function removeRuntimeIdentity(runtimeDir) {
+  fs.rmSync(runtimeIdentityPath(runtimeDir), { force: true });
+}
+
+function writeRuntimeIdentity(runtimeDir, identity) {
+  assertRuntimeIdentity(identity);
+  const destination = runtimeIdentityPath(runtimeDir);
+  const directory = path.dirname(destination);
+  fs.mkdirSync(directory, { recursive: true });
+  const temporary = path.join(
+    directory,
+    `.${RUNTIME_IDENTITY_FILENAME}.${process.pid}.${crypto.randomBytes(8).toString('hex')}.tmp`,
+  );
+  let descriptor;
+  try {
+    descriptor = fs.openSync(
+      temporary,
+      fs.constants.O_WRONLY |
+        fs.constants.O_CREAT |
+        fs.constants.O_EXCL |
+        fs.constants.O_NOFOLLOW,
+      0o600,
+    );
+    fs.fchmodSync(descriptor, 0o600);
+    fs.writeFileSync(descriptor, `${JSON.stringify(identity)}\n`, 'utf8');
+    fs.fsyncSync(descriptor);
+    fs.closeSync(descriptor);
+    descriptor = undefined;
+    fs.renameSync(temporary, destination);
+  } catch (error) {
+    if (descriptor !== undefined) {
+      try {
+        fs.closeSync(descriptor);
+      } catch {}
+    }
+    fs.rmSync(temporary, { force: true });
+    throw error;
+  }
+}
+
+function assertRuntimeIdentity(identity) {
+  if (
+    !identity ||
+    !Number.isInteger(identity.port) ||
+    identity.port <= 0 ||
+    identity.port > 65535 ||
+    !Number.isInteger(identity.pid) ||
+    identity.pid <= 0 ||
+    !Number.isInteger(identity.startedAt) ||
+    identity.startedAt <= 0 ||
+    !/^[a-f0-9]{64}$/u.test(identity.nonce)
+  ) {
+    throw new Error('writeRuntimeIdentity: invalid runtime identity');
+  }
+}
+
+module.exports = {
+  DETACHED_LAUNCH_UNPROVEN_FILENAME,
+  RUNTIME_IDENTITY_FILENAME,
+  RUNTIME_NONCE_PREFIX,
+  automationRuntimeArgs,
+  clearDetachedLaunchUnproven,
+  clearValidationPortQuarantine,
+  createRuntimeIdentityNonce,
+  detachedLaunchUnprovenPath,
+  hasDetachedLaunchUnproven,
+  isolatedProfileArgs,
+  markDetachedLaunchUnproven,
+  markValidationPortLaunchUnproven,
+  quarantineDetachedLaunch,
+  quarantineValidationPort,
+  readValidationPortQuarantine,
+  remoteDebuggingArgs,
+  removeRuntimeIdentity,
+  runtimeIdentityArgs,
+  runtimeIdentityPath,
+  shellQuote,
+  validationLaunchQuarantineError,
+  validationPortQuarantinePath,
+  writeRuntimeIdentity,
+};

package/adapters/extension/lib/playwright-cdp.cjs

@@ -0,0 +1,34 @@
+'use strict';
+
+function buildEvaluationExpression(callbackOrExpression, argument) {
+  if (typeof callbackOrExpression === 'string') return callbackOrExpression;
+  if (typeof callbackOrExpression !== 'function') {
+    throw new TypeError('CDP evaluation requires a function or expression string.');
+  }
+  return argument === undefined
+    ? `(${callbackOrExpression.toString()})()`
+    : `(${callbackOrExpression.toString()})(${JSON.stringify(argument)})`;
+}
+
+async function evaluatePageViaCdp(page, callbackOrExpression, argument) {
+  const session = await page.context().newCDPSession(page);
+  try {
+    const response = await session.send('Runtime.evaluate', {
+      expression: buildEvaluationExpression(callbackOrExpression, argument),
+      awaitPromise: true,
+      returnByValue: true,
+    });
+    if (response.exceptionDetails) {
+      const detail =
+        response.exceptionDetails.exception?.description ??
+        response.exceptionDetails.text ??
+        'unknown evaluation failure';
+      throw new Error(`CDP evaluation failed: ${detail}`);
+    }
+    return response.result?.value;
+  } finally {
+    await session.detach().catch(() => {});
+  }
+}
+
+module.exports = { buildEvaluationExpression, evaluatePageViaCdp };

package/adapters/extension/lib/slot-title.cjs

@@ -39,12 +39,10 @@ function readSlotId(target, runtimeDir) {
 }
 
 /**
- * Playwright page.evaluate callback. Must stay a plain function (no closure)
- * so Playwright can serialize it into the page.
+ * Serialized page-evaluation callback. Must stay a plain function (no closure).
  */
 function applyPersistentSlotTitle(slot) {
-  // Inline sanitize — this function is serialized into the page for Playwright
-  // and CDP, so it cannot call Node helpers.
+  // Inline sanitize because the serialized function cannot call Node helpers.
   const id =
     typeof slot === 'string' && /^[A-Za-z0-9._:-]{1,64}$/u.test(slot.trim())
       ? slot.trim()

package/adapters/extension/lib/validation-launch-supervisor.cjs

@@ -0,0 +1,292 @@
+#!/usr/bin/env node
+'use strict';
+
+const dgram = require('node:dgram');
+const { execFileSync, spawn } = require('node:child_process');
+const {
+  clearValidationPortQuarantine,
+  createRuntimeIdentityNonce,
+  hasDetachedLaunchUnproven,
+  markValidationPortLaunchUnproven,
+  quarantineDetachedLaunch,
+  quarantineValidationPort,
+  readValidationPortQuarantine,
+  validationLaunchQuarantineError,
+} = require('./chrome-args.cjs');
+const { stopProfileProcesses } = require('./validation-process-ownership.cjs');
+
+const port = Number(process.argv[2]);
+if (!Number.isInteger(port) || port <= 0 || port > 65535 || typeof process.send !== 'function') {
+  process.exit(2);
+}
+
+const socket = dgram.createSocket('udp4');
+let launchChild;
+let launchLease;
+let ownsPortLease = false;
+let launchRequest;
+let launchFinished = false;
+let finishStarted = false;
+let finalizing = false;
+let releaseRequest;
+let profileCleaned = false;
+
+process.stdout.on('error', () => {});
+process.stderr.on('error', () => {});
+
+function send(message, callback = () => {}) {
+  if (!process.connected) {
+    callback();
+    return;
+  }
+  process.send(message, callback);
+}
+
+function signalLaunchTree(signal) {
+  if (!launchChild?.pid) return;
+  if (process.platform === 'win32') launchChild.kill(signal);
+  else signalPids(launchTreePids(), signal);
+}
+
+function launchTreeExists() {
+  if (!launchChild?.pid) return false;
+  if (process.platform !== 'win32') return launchTreePids().length > 0;
+  try {
+    process.kill(launchChild.pid, 0);
+    return true;
+  } catch (error) {
+    return error.code !== 'ESRCH';
+  }
+}
+
+function launchTreePids() {
+  const output = execFileSync('ps', ['-axo', 'pid=,pgid='], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'ignore'],
+  });
+  const pids = [];
+  for (const line of output.split('\n')) {
+    const match = line.match(/^\s*(\d+)\s+(\d+)\s*$/u);
+    if (match && Number(match[2]) === launchChild.pid) pids.push(Number(match[1]));
+  }
+  return pids.filter((pid) => pid !== process.pid);
+}
+
+function delay(milliseconds) {
+  return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+
+async function stopRemainingLaunchTree() {
+  if (!launchTreeExists()) return;
+  signalLaunchTree('SIGTERM');
+  const termDeadline = Date.now() + 1_000;
+  while (launchTreeExists() && Date.now() < termDeadline) await delay(50);
+  if (!launchTreeExists()) return;
+  signalLaunchTree('SIGKILL');
+  const killDeadline = Date.now() + 1_000;
+  while (launchTreeExists() && Date.now() < killDeadline) await delay(50);
+  if (launchTreeExists()) throw new Error(`Extension validation launcher process group ${launchChild.pid} survived SIGKILL.`);
+}
+
+function signalPids(pids, signal) {
+  for (const pid of pids) {
+    try {
+      process.kill(pid, signal);
+    } catch (error) {
+      if (error.code !== 'ESRCH') throw error;
+    }
+  }
+}
+
+function closeSocket() {
+  return new Promise((resolve) => socket.close(resolve));
+}
+
+async function cleanProfile(quietMs) {
+  await stopProfileProcesses(launchRequest.profile, { quietMs });
+  profileCleaned = true;
+}
+
+function quarantineProfile(error) {
+  let quarantineError;
+  try {
+    quarantineDetachedLaunch(launchRequest.profile, error.message);
+  } catch (markerError) {
+    quarantineError = markerError;
+  }
+  try {
+    quarantineValidationPort(port, launchRequest.profile, error.message);
+  } catch (markerError) {
+    quarantineError ||= markerError;
+  }
+  return quarantineError
+    ? new Error(`${error.message} Extension validation could not persist quarantine: ${quarantineError.message}`)
+    : error;
+}
+
+async function finalize(preserveProfileOwner) {
+  if (finalizing) return;
+  finalizing = true;
+  let finalError;
+  if (launchRequest && !preserveProfileOwner && !profileCleaned) {
+    try {
+      await cleanProfile(2_000);
+    } catch (error) {
+      finalError = quarantineProfile(error);
+    }
+  }
+  if (launchRequest && ownsPortLease && !finalError) {
+    try {
+      const detachedLaunchUnproven = hasDetachedLaunchUnproven(launchRequest.profile);
+      if (preserveProfileOwner && detachedLaunchUnproven) {
+        throw new Error('Extension validation cannot release an unproven detached browser launch.');
+      }
+      if (!detachedLaunchUnproven) {
+        clearValidationPortQuarantine(port, launchRequest.profile, launchLease);
+        ownsPortLease = false;
+      }
+    } catch (error) {
+      finalError = quarantineProfile(error);
+    }
+  }
+  await closeSocket();
+  if (finalError) send({ type: 'release-error', message: finalError.message }, () => process.exit(1));
+  else process.exit(0);
+}
+
+async function finish(result) {
+  if (finishStarted) return;
+  finishStarted = true;
+  let finalResult = result;
+  let launchTreeError;
+  try {
+    await stopRemainingLaunchTree();
+  } catch (error) {
+    launchTreeError = quarantineProfile(error);
+  }
+  if (launchRequest && (launchTreeError || result.exitCode !== 0 || result.timedOut || result.error)) {
+    let detachedLaunchUnproven = false;
+    try {
+      detachedLaunchUnproven = hasDetachedLaunchUnproven(launchRequest.profile);
+    } catch (error) {
+      launchTreeError ||= quarantineProfile(error);
+    }
+    try {
+      await cleanProfile(detachedLaunchUnproven || result.timedOut || result.error || launchTreeError ? 2_000 : 0);
+    } catch (error) {
+      launchTreeError ||= quarantineProfile(error);
+    }
+  }
+  if (launchTreeError) {
+    finalResult = { type: 'result', exitCode: null, timedOut: result.timedOut, error: launchTreeError.message };
+  }
+  launchFinished = true;
+  send(finalResult);
+  if (releaseRequest !== undefined || !process.connected) void finalize(releaseRequest === true);
+}
+
+function startLaunch(message) {
+  if (
+    launchChild ||
+    !message ||
+    typeof message.command !== 'string' ||
+    !Array.isArray(message.args) ||
+    typeof message.profile !== 'string'
+  ) {
+    send({ type: 'error', message: 'Invalid extension validation supervisor launch request.' }, () => process.exit(2));
+    return;
+  }
+  const timeoutMs = Number(message.timeoutMs);
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+    send({ type: 'error', message: 'Invalid extension validation supervisor timeout.' }, () => process.exit(2));
+    return;
+  }
+  launchRequest = message;
+  const lease = createRuntimeIdentityNonce();
+  launchLease = lease;
+  try {
+    markValidationPortLaunchUnproven(port, message.profile, lease);
+    ownsPortLease = true;
+  } catch (error) {
+    void finish({ type: 'result', exitCode: null, timedOut: false, error: error.message });
+    return;
+  }
+  launchChild = spawn(message.command, message.args, {
+    cwd: message.cwd,
+    env: {
+      ...message.env,
+      MM_HARNESS_VALIDATION_PORT_LEASE: lease,
+    },
+    detached: process.platform !== 'win32',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  launchChild.stdout.pipe(process.stdout);
+  launchChild.stderr.pipe(process.stderr);
+  let timedOut = false;
+  let killTimer;
+  const timeout = setTimeout(() => {
+    timedOut = true;
+    try {
+      signalLaunchTree('SIGTERM');
+    } catch (error) {
+      void finish({ type: 'result', exitCode: null, timedOut, error: error.message });
+      return;
+    }
+    killTimer = setTimeout(() => {
+      try {
+        signalLaunchTree('SIGKILL');
+      } catch (error) {
+        void finish({ type: 'result', exitCode: null, timedOut, error: error.message });
+      }
+    }, 1_000);
+    killTimer.unref();
+  }, timeoutMs);
+  launchChild.once('error', (error) => {
+    clearTimeout(timeout);
+    if (killTimer) clearTimeout(killTimer);
+    void finish({ type: 'result', exitCode: null, timedOut, error: error.message });
+  });
+  launchChild.once('close', (exitCode) => {
+    clearTimeout(timeout);
+    if (killTimer) clearTimeout(killTimer);
+    void finish({ type: 'result', exitCode, timedOut });
+  });
+}
+
+process.on('message', (message) => {
+  if (message?.type === 'run') startLaunch(message);
+  if (message?.type === 'release') {
+    releaseRequest = message.preserveProfileOwner === true;
+    if (launchFinished) void finalize(releaseRequest);
+  }
+  if (message?.type === 'cancel' && !launchChild) {
+    releaseRequest = false;
+    void finish({ type: 'cancelled', timedOut: false });
+  }
+});
+
+process.on('disconnect', () => {
+  releaseRequest = false;
+  if (!launchChild) {
+    void finish({ type: 'cancelled', timedOut: false });
+    return;
+  }
+  launchChild.stdout.unpipe(process.stdout);
+  launchChild.stderr.unpipe(process.stderr);
+  launchChild.stdout.resume();
+  launchChild.stderr.resume();
+  if (launchFinished) void finalize(false);
+});
+
+socket.once('error', (error) => {
+  const message = error.code === 'EADDRINUSE'
+    ? `Extension validation runtime is already preparing on port ${port}.`
+    : error.message;
+  send({ type: 'error', message }, () => process.exit(1));
+});
+const existingQuarantine = readValidationPortQuarantine(port);
+if (existingQuarantine) {
+  send({ type: 'error', message: validationLaunchQuarantineError(port, existingQuarantine.profile).message }, () => process.exit(1));
+} else {
+  socket.bind({ address: '127.0.0.1', port, exclusive: true }, () => send({ type: 'ready' }));
+}