@deeeed/metamask-harness 0.23.1 → 0.25.0

package/library/actions/shared/analytics/assert_events.mjs

@@ -0,0 +1,168 @@
+import { runAdapter } from './_adapter.mjs';
+import { readCollected } from './collector.mjs';
+
+const DEFAULT_TIMEOUT_MS = 15000;
+// Why a settle window exists at all: a duplicate emit arrives *after* the
+// expected one. If this returned the instant a count reached its target it
+// would pass on the first of two events and never see the second — which is
+// precisely the defect class this action was built to catch. So: wait until
+// satisfiable, then keep waiting, then judge.
+const DEFAULT_SETTLE_MS = 1500;
+
+function nonNegativeNumber(value, name, fallback) {
+  if (value === undefined) return fallback;
+  if (value === '') throw new Error(`${name} must not be blank.`);
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed < 0) {
+    throw new Error(`${name} must be a non-negative number, got ${JSON.stringify(value)}.`);
+  }
+  return parsed;
+}
+
+function nonNegativeInteger(value, name, fallback) {
+  const parsed = nonNegativeNumber(value, name, fallback);
+  if (!Number.isInteger(parsed)) {
+    throw new Error(`${name} must be an integer, got ${JSON.stringify(value)}.`);
+  }
+  return parsed;
+}
+
+function matchesProperties(actual, expected) {
+  return Object.entries(expected).every(([key, want]) => {
+    const got = actual?.[key];
+    if (want !== null && typeof want === 'object') {
+      return JSON.stringify(got) === JSON.stringify(want);
+    }
+    // Segment serialises numbers inconsistently across clients.
+    if (typeof want === 'number' && typeof got === 'string' && got.trim() !== '') {
+      return Number(got) === want;
+    }
+    if (typeof got === 'number' && typeof want === 'string' && want.trim() !== '') {
+      return got === Number(want);
+    }
+    return Object.is(got, want);
+  });
+}
+
+function selectFor(expectation, events) {
+  return events.filter(
+    (entry) =>
+      entry.event === expectation.event &&
+      (!expectation.properties || matchesProperties(entry.properties, expectation.properties)),
+  );
+}
+
+function expectationsFrom(input) {
+  const raw = input.node?.expect;
+  if (!Array.isArray(raw) || raw.length === 0) {
+    throw new Error('metamask.analytics.assert_events requires a non-empty expect array.');
+  }
+  return raw.map((entry) => {
+    if (typeof entry?.event !== 'string' || entry.event.length === 0) {
+      throw new Error('Each expect entry requires a non-empty event name.');
+    }
+    const hasCount = entry.count !== undefined;
+    const hasBounds = entry.min !== undefined || entry.max !== undefined;
+    if (hasCount && hasBounds) {
+      throw new Error(`expect entry for "${entry.event}" sets both count and min/max; pick one.`);
+    }
+    const expectation = {
+      event: entry.event,
+      properties: entry.properties ?? null,
+      count: hasCount ? nonNegativeInteger(entry.count, `count for "${entry.event}"`) : undefined,
+      min: entry.min !== undefined
+        ? nonNegativeInteger(entry.min, `min for "${entry.event}"`)
+        : hasCount
+          ? nonNegativeInteger(entry.count, `count for "${entry.event}"`)
+          : 1,
+      max: entry.max !== undefined
+        ? nonNegativeInteger(entry.max, `max for "${entry.event}"`)
+        : hasCount
+          ? nonNegativeInteger(entry.count, `count for "${entry.event}"`)
+          : undefined,
+    };
+    if (expectation.max !== undefined && expectation.min > expectation.max) {
+      throw new Error(
+        `expect entry for "${entry.event}" has min ${expectation.min} greater than max ${expectation.max}.`,
+      );
+    }
+    return expectation;
+  });
+}
+
+function describe(expectation) {
+  const bound =
+    expectation.count !== undefined
+      ? `exactly ${expectation.count}`
+      : `min ${expectation.min}${expectation.max === undefined ? '' : `, max ${expectation.max}`}`;
+  const props = expectation.properties ? ` matching ${JSON.stringify(expectation.properties)}` : '';
+  return `"${expectation.event}"${props} (${bound})`;
+}
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+runAdapter(async (input) => {
+  const since = nonNegativeNumber(input.node?.since, 'since', 0);
+  const timeoutMs = nonNegativeNumber(input.node?.timeout_ms, 'timeout_ms', DEFAULT_TIMEOUT_MS);
+  const settleMs = nonNegativeNumber(input.node?.settle_ms, 'settle_ms', DEFAULT_SETTLE_MS);
+  const exact = Boolean(input.node?.exact);
+  const expectations = expectationsFrom(input);
+
+  // Phase 1 — wait until every lower bound is reachable, or time out. Timing out
+  // is not itself a failure; the strict judgement below produces the message.
+  const deadline = Date.now() + timeoutMs;
+  let events = [];
+  for (;;) {
+    events = await readCollected(input, { since });
+    const allMet = expectations.every((e) => selectFor(e, events).length >= e.min);
+    if (allMet || Date.now() >= deadline) break;
+    await sleep(250);
+  }
+
+  // Phase 2 — settle, so a late duplicate lands before we judge.
+  await sleep(settleMs);
+  events = await readCollected(input, { since });
+
+  const failures = [];
+  const observed = [];
+  for (const expectation of expectations) {
+    const matched = selectFor(expectation, events);
+    observed.push({ event: expectation.event, matched: matched.length });
+    if (expectation.count !== undefined && matched.length !== expectation.count) {
+      failures.push(`expected ${describe(expectation)}, got ${matched.length}`);
+      continue;
+    }
+    if (matched.length < expectation.min) {
+      failures.push(`expected ${describe(expectation)}, got ${matched.length}`);
+      continue;
+    }
+    if (expectation.max !== undefined && matched.length > expectation.max) {
+      failures.push(`expected ${describe(expectation)}, got ${matched.length}`);
+    }
+  }
+
+  if (exact) {
+    const allowed = new Set(expectations.map((e) => e.event));
+    const unexpected = [...new Set(events.map((e) => e.event).filter((name) => name && !allowed.has(name)))];
+    if (unexpected.length) {
+      failures.push(`exact mode: unexpected event(s) ${unexpected.map((n) => `"${n}"`).join(', ')}`);
+    }
+  }
+
+  if (failures.length) {
+    const captured = events.map((e) => e.event).filter(Boolean);
+    throw new Error(
+      [
+        `metamask.analytics.assert_events failed:`,
+        ...failures.map((line) => `  - ${line}`),
+        `  captured since ${since}: ${captured.length ? captured.join(', ') : '(none)'}`,
+        // A missing-property failure here is most often a consent problem, not a
+        // client bug: platform-adapter strips utm_* unless BOTH
+        // participateInMetaMetrics and dataCollectionForMarketing are true.
+        `  if utm_* / marketing properties are missing, check MetaMetrics consent before suspecting the client.`,
+      ].join('\n'),
+    );
+  }
+
+  return { action: input.action, since, exact, observed, capturedCount: events.length };
+});

package/library/actions/shared/analytics/collector.mjs

@@ -0,0 +1,505 @@
+// Segment collector shared by every platform's analytics actions.
+//
+// Both clients already ship the mechanism to divert MetaMetrics to an arbitrary
+// host — the extension via SEGMENT_HOST, mobile via SEGMENT_PROXY_URL — and
+// neither validates the write key. Pointing either at this collector yields the
+// exact payloads Segment would have received.
+//
+// This lives in `shared/` because the payload shape is Segment's, not a
+// client's: `<root>/shared/<family>/<stem>.mjs` is the fallback the adapter
+// contract tries for every platform, so one implementation serves all.
+//
+// The server has to outlive the action process that starts it (each action is a
+// separate short-lived process), so `startCollector` spawns this same file
+// detached in `--serve` mode and records the pid. Events land in a JSONL file
+// that later actions read by cursor.
+
+import { randomUUID } from 'node:crypto';
+import { createServer } from 'node:http';
+import { execFile, spawn } from 'node:child_process';
+import { constants } from 'node:fs';
+import {
+  chmod,
+  lstat,
+  mkdir,
+  open,
+  rename,
+  unlink,
+} from 'node:fs/promises';
+import path from 'node:path';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+
+export function collectorPaths(projectRoot) {
+  const configuredRuntime = process.env.RECIPE_RUNTIME_DIR;
+  const runtimeRoot = configuredRuntime
+    ? path.resolve(projectRoot, configuredRuntime)
+    : path.join(projectRoot, 'temp/recipe/runtime');
+  const dir = path.join(runtimeRoot, 'analytics');
+  return {
+    dir,
+    eventsFile: path.join(dir, 'events.jsonl'),
+    stateFile: path.join(dir, 'collector.json'),
+  };
+}
+
+async function prepareCollectorStorage(projectRoot) {
+  const paths = collectorPaths(projectRoot);
+  const configuredRuntime = process.env.RECIPE_RUNTIME_DIR;
+  const boundary = configuredRuntime && path.isAbsolute(configuredRuntime)
+    ? path.resolve(configuredRuntime)
+    : path.resolve(projectRoot);
+  await ensureRealDirectoryChain(
+    boundary,
+    paths.dir,
+    Boolean(configuredRuntime && path.isAbsolute(configuredRuntime)),
+  );
+  await chmod(paths.dir, 0o700);
+  await ensurePrivateAppendFile(paths.eventsFile);
+  await secureExistingFile(paths.stateFile);
+  return paths;
+}
+
+async function ensureRealDirectoryChain(boundary, target, includeBoundary) {
+  const relative = path.relative(boundary, target);
+  if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+    throw new Error(`Analytics runtime path escapes its selected root: ${target}`);
+  }
+  if (includeBoundary) {
+    await mkdir(boundary, { recursive: true, mode: 0o700 });
+  }
+  let current = boundary;
+  const paths = includeBoundary ? [current] : [];
+  for (const segment of relative.split(path.sep).filter(Boolean)) {
+    current = path.join(current, segment);
+    paths.push(current);
+  }
+  for (const directory of paths) {
+    let info;
+    try {
+      info = await lstat(directory);
+    } catch (error) {
+      if (error?.code !== 'ENOENT') throw error;
+      await mkdir(directory, { mode: 0o700 });
+      info = await lstat(directory);
+    }
+    if (info.isSymbolicLink() || !info.isDirectory()) {
+      throw new Error(`Analytics runtime directory must be a real directory, not a symlink: ${directory}`);
+    }
+  }
+}
+
+async function secureExistingFile(filePath) {
+  try {
+    const info = await lstat(filePath);
+    if (info.isSymbolicLink() || !info.isFile()) {
+      throw new Error(`Analytics runtime file must be a real file, not a symlink: ${filePath}`);
+    }
+    await chmod(filePath, 0o600);
+    return true;
+  } catch (error) {
+    if (error?.code === 'ENOENT') return false;
+    throw error;
+  }
+}
+
+async function ensurePrivateAppendFile(filePath) {
+  await secureExistingFile(filePath);
+  const handle = await open(
+    filePath,
+    constants.O_WRONLY
+      | constants.O_APPEND
+      | constants.O_CREAT
+      | (constants.O_NOFOLLOW ?? 0),
+    0o600,
+  );
+  try {
+    const info = await handle.stat();
+    if (!info.isFile()) throw new Error(`Analytics events path is not a regular file: ${filePath}`);
+    await handle.chmod(0o600);
+  } finally {
+    await handle.close();
+  }
+}
+
+async function appendPrivateFile(filePath, value) {
+  const handle = await open(
+    filePath,
+    constants.O_WRONLY | constants.O_APPEND | (constants.O_NOFOLLOW ?? 0),
+  );
+  try {
+    const info = await handle.stat();
+    if (!info.isFile()) throw new Error(`Analytics events path is not a regular file: ${filePath}`);
+    await handle.writeFile(value);
+  } finally {
+    await handle.close();
+  }
+}
+
+async function readPrivateFile(filePath) {
+  const handle = await open(
+    filePath,
+    constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0),
+  );
+  try {
+    const info = await handle.stat();
+    if (!info.isFile()) throw new Error(`Analytics runtime path is not a regular file: ${filePath}`);
+    return await handle.readFile('utf8');
+  } finally {
+    await handle.close();
+  }
+}
+
+async function writePrivateState(stateFile, state) {
+  await secureExistingFile(stateFile);
+  const temporary = path.join(path.dirname(stateFile), `.collector-${randomUUID()}.json`);
+  let handle;
+  try {
+    handle = await open(
+      temporary,
+      constants.O_WRONLY
+        | constants.O_CREAT
+        | constants.O_EXCL
+        | (constants.O_NOFOLLOW ?? 0),
+      0o600,
+    );
+    await handle.writeFile(`${JSON.stringify(state)}\n`);
+    await handle.chmod(0o600);
+    await handle.close();
+    handle = undefined;
+    await rename(temporary, stateFile);
+    await chmod(stateFile, 0o600);
+  } catch (error) {
+    await handle?.close().catch(() => {});
+    await unlink(temporary).catch(() => {});
+    throw error;
+  }
+}
+
+/**
+ * Default port derives from the slot's CDP port so co-located slots do not
+ * collide. Mirrors farmslot's `SEGMENT_PORT="$(( CDP_PORT + 1000 ))"`.
+ */
+export function collectorPort(input) {
+  const explicit = input?.node?.port ?? process.env.SEGMENT_MOCK_PORT;
+  if (explicit !== undefined) return validPort(explicit, 'collector port');
+  const cdpRaw = input?.node?.cdp_port ?? process.env.CDP_PORT ?? process.env.RECIPE_CDP_PORT;
+  if (cdpRaw !== undefined) {
+    const cdp = validPort(cdpRaw, 'CDP port');
+    return validPort(cdp + 1000, 'collector port derived from CDP port');
+  }
+  return 9090;
+}
+
+function validPort(value, name) {
+  if (value === '') throw new Error(`Analytics ${name} must not be blank.`);
+  const port = Number(value);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new Error(`Analytics ${name} must be an integer from 1 to 65535, got ${JSON.stringify(value)}.`);
+  }
+  return port;
+}
+
+function projectRootOf(input) {
+  const root = input?.context?.projectRoot;
+  if (!root) throw new Error('Analytics actions require context.projectRoot.');
+  return root;
+}
+
+async function readState(stateFile) {
+  try {
+    return JSON.parse(await readPrivateFile(stateFile));
+  } catch {
+    return null;
+  }
+}
+
+function pidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    // Signal 0 tests for existence without delivering anything.
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function collectorHealth(port) {
+  try {
+    const response = await fetch(`http://127.0.0.1:${port}/__collector`, {
+      signal: AbortSignal.timeout(1000),
+    });
+    if (!response.ok) return null;
+    const body = await response.json();
+    return body?.collector === 'metamask-harness' && body?.port === port
+      ? body
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+async function stopCollector(state) {
+  if (
+    !state?.instanceId ||
+    !pidAlive(state.pid) ||
+    (await collectorHealth(state.port))?.instanceId !== state.instanceId
+  ) {
+    return false;
+  }
+  try {
+    process.kill(state.pid, 'SIGTERM');
+  } catch {
+    return true;
+  }
+  const deadline = Date.now() + 2000;
+  while (Date.now() < deadline && pidAlive(state.pid)) {
+    await new Promise((resolve) => setTimeout(resolve, 50));
+  }
+  if (pidAlive(state.pid)) {
+    try {
+      process.kill(state.pid, 'SIGKILL');
+    } catch {
+      // The process exited after the final liveness check.
+    }
+  }
+  return true;
+}
+
+async function stopSpawnedCollector(pid) {
+  if (!pidAlive(pid)) return;
+  try {
+    process.kill(pid, 'SIGTERM');
+  } catch {
+    return;
+  }
+  const deadline = Date.now() + 2000;
+  while (Date.now() < deadline && pidAlive(pid)) {
+    await new Promise((resolve) => setTimeout(resolve, 50));
+  }
+  if (pidAlive(pid)) {
+    try {
+      process.kill(pid, 'SIGKILL');
+    } catch {
+      // The process exited after the final liveness check.
+    }
+  }
+}
+
+async function prepareAndroidAccess(input, port) {
+  if (input?.platform !== 'mobile') return null;
+  const androidDevice =
+    input?.node?.android_device ??
+    process.env.ANDROID_DEVICE;
+  const adbSerial =
+    input?.node?.adb_serial ??
+    process.env.ADB_SERIAL ??
+    process.env.ANDROID_SERIAL ??
+    androidDevice;
+  const iosSimulator =
+    input?.node?.simulator ??
+    input?.node?.ios_simulator ??
+    process.env.IOS_SIMULATOR;
+  const explicitlyAndroid =
+    input?.node?.platform === 'android' ||
+    (adbSerial && String(androidDevice ?? '') === String(adbSerial));
+  if (!adbSerial || (iosSimulator && !explicitlyAndroid)) return null;
+  try {
+    await execFileAsync(
+      'adb',
+      ['-s', String(adbSerial), 'reverse', `tcp:${port}`, `tcp:${port}`],
+      { timeout: 5000 },
+    );
+  } catch (error) {
+    throw new Error(
+      `Analytics collector could not reverse port ${port} to Android device ${adbSerial}: ${error?.message ?? String(error)}`,
+    );
+  }
+  return String(adbSerial);
+}
+
+/**
+ * Idempotent: an already-running collector on the same port is reused, so a
+ * recipe may call start_capture in several nodes without stacking servers.
+ */
+export async function startCollector(input) {
+  const projectRoot = projectRootOf(input);
+  const port = collectorPort(input);
+  const { eventsFile, stateFile } = await prepareCollectorStorage(projectRoot);
+
+  const existing = await readState(stateFile);
+  const existingHealth = existing?.port ? await collectorHealth(existing.port) : null;
+  if (
+    existing?.port === port &&
+    existing?.instanceId &&
+    pidAlive(existing.pid) &&
+    existingHealth?.instanceId === existing.instanceId
+  ) {
+    const androidDevice = await prepareAndroidAccess(input, port);
+    return { port, pid: existing.pid, eventsFile, reused: true, androidDevice };
+  }
+  if (existing?.port && existing.port !== port) {
+    const stopped = await stopCollector(existing);
+    if (!stopped && pidAlive(existing.pid)) {
+      throw new Error(
+        `Refusing to replace unverified analytics collector process ${existing.pid} on port ${existing.port}.`,
+      );
+    }
+  }
+
+  const occupied = await collectorHealth(port);
+  if (occupied) {
+    throw new Error(
+      `Analytics collector port ${port} is owned by another instance. Choose another port or stop that collector.`,
+    );
+  }
+
+  const instanceId = randomUUID();
+  const child = spawn(
+    process.execPath,
+    [
+      '--input-type=module',
+      '--eval',
+      collectorServerSource(),
+      String(port),
+      eventsFile,
+      instanceId,
+    ],
+    {
+      detached: true,
+      stdio: 'ignore',
+    },
+  );
+  child.unref();
+
+  // The server binds asynchronously; fail loudly rather than let a later
+  // read_events return an empty list that looks like "no events emitted".
+  const deadline = Date.now() + 5000;
+  while (Date.now() < deadline) {
+    if ((await collectorHealth(port))?.instanceId === instanceId) {
+      try {
+        await writePrivateState(stateFile, { pid: child.pid, port, eventsFile, instanceId });
+        const androidDevice = await prepareAndroidAccess(input, port);
+        return {
+          port,
+          pid: child.pid,
+          eventsFile,
+          reused: false,
+          androidDevice,
+        };
+      } catch (error) {
+        await stopSpawnedCollector(child.pid);
+        throw error;
+      }
+    }
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+  await stopSpawnedCollector(child.pid);
+  throw new Error(`Segment collector failed to bind port ${port} within 5000ms.`);
+}
+
+export async function readCollected(input, { since = 0, event = null } = {}) {
+  const { eventsFile } = await prepareCollectorStorage(projectRootOf(input));
+  let raw = '';
+  try {
+    raw = await readPrivateFile(eventsFile);
+  } catch (error) {
+    if (error?.code === 'ENOENT') return [];
+    throw error;
+  }
+  const events = raw
+    .split('\n')
+    .filter(Boolean)
+    .map((line, index) => {
+      try {
+        return JSON.parse(line);
+      } catch (error) {
+        throw new Error(
+          `Analytics capture is corrupt at JSONL record ${index + 1}: ${error?.message ?? String(error)}`,
+        );
+      }
+    })
+    .filter((entry) => entry.ts >= since);
+  return event ? events.filter((entry) => entry.event === event) : events;
+}
+
+// --- server mode (spawned detached by startCollector) ---
+
+function eventsFromBody(body) {
+  // The Segment node SDK posts `{ batch: [...] }` to /v1/batch; the HTTP API
+  // also accepts a single event object on /v1/track.
+  const items = Array.isArray(body?.batch) ? body.batch : [body];
+  return items
+    .filter((item) => item && typeof item === 'object')
+    .map((item) => ({
+      type: item.type ?? null,
+      event: item.event ?? null,
+      properties: item.properties ?? {},
+      userId: item.userId ?? null,
+      anonymousId: item.anonymousId ?? null,
+      sentAt: item.timestamp ?? item.sentAt ?? null,
+      ts: Date.now(),
+    }));
+}
+
+function serve(port, eventsFile, instanceId) {
+  const server = createServer((request, response) => {
+    // The extension's Segment client runs in a page context, so preflight has
+    // to pass or nothing is ever delivered.
+    const cors = {
+      'Access-Control-Allow-Origin': '*',
+      'Access-Control-Allow-Methods': 'POST, GET, OPTIONS',
+      'Access-Control-Allow-Headers': '*',
+    };
+    if (request.method === 'OPTIONS') {
+      response.writeHead(204, cors);
+      response.end();
+      return;
+    }
+    if (request.method === 'GET') {
+      response.writeHead(200, { ...cors, 'Content-Type': 'application/json' });
+      response.end(JSON.stringify({
+        collector: 'metamask-harness',
+        port,
+        instanceId,
+      }));
+      return;
+    }
+
+    const chunks = [];
+    request.on('data', (chunk) => chunks.push(chunk));
+    request.on('end', async () => {
+      try {
+        const events = eventsFromBody(JSON.parse(Buffer.concat(chunks).toString('utf8')));
+        if (events.length) {
+          await appendPrivateFile(
+            eventsFile,
+            `${events.map((event) => JSON.stringify(event)).join('\n')}\n`,
+          );
+        }
+        // Segment clients retry on non-2xx, so acknowledge only after the
+        // payload is appended.
+        response.writeHead(200, { ...cors, 'Content-Type': 'application/json' });
+        response.end('{}');
+      } catch {
+        response.writeHead(500, { ...cors, 'Content-Type': 'application/json' });
+        response.end('{"error":"collector_write_failed"}');
+      }
+    });
+  });
+  server.listen(port, '127.0.0.1');
+}
+
+function collectorServerSource() {
+  return [
+    `import { createServer } from 'node:http';`,
+    `import { constants } from 'node:fs';`,
+    `import { open } from 'node:fs/promises';`,
+    `const appendPrivateFile = ${appendPrivateFile.toString()};`,
+    `const eventsFromBody = ${eventsFromBody.toString()};`,
+    `const serve = ${serve.toString()};`,
+    `serve(Number(process.argv[1]), process.argv[2], process.argv[3]);`,
+  ].join('\n');
+}

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

@@ -0,0 +1,14 @@
+export function consentParams(node) {
+  const optional = (value, fallback) =>
+    value === undefined || value === null || value === '' ? fallback : value;
+  const participate = Boolean(optional(node?.participate, true));
+  const marketing = Boolean(optional(node?.marketing, participate));
+  const timeoutMs = Number(optional(node?.timeout_ms, 15000));
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+    throw new Error('metamask.analytics.set_consent timeout_ms must be a positive number.');
+  }
+  if (marketing && !participate) {
+    throw new Error('metamask.analytics.set_consent cannot enable marketing collection while MetaMetrics participation is disabled.');
+  }
+  return { participate, marketing, timeoutMs };
+}