@deeeed/metamask-harness 0.24.0 → 0.25.0

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

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

@@ -0,0 +1,22 @@
+import { runAdapter } from './_adapter.mjs';
+import { readCollected } from './collector.mjs';
+
+runAdapter(async (input) => {
+  const since = input.node?.since === undefined ? 0 : Number(input.node.since);
+  if (input.node?.since === '' || !Number.isFinite(since) || since < 0) {
+    throw new Error(`metamask.analytics.read_events since must be a non-negative number, got ${JSON.stringify(input.node?.since)}.`);
+  }
+  const event = input.node?.event ?? null;
+  if (event !== null && (typeof event !== 'string' || event.length === 0)) {
+    throw new Error('metamask.analytics.read_events event must be a non-empty string when provided.');
+  }
+  const events = await readCollected(input, { since, event });
+  return {
+    action: input.action,
+    since,
+    count: events.length,
+    events,
+    // Names alone are usually what a human wants to eyeball in the artifact.
+    names: events.map((entry) => entry.event).filter(Boolean),
+  };
+});

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

@@ -0,0 +1,24 @@
+import { runAdapter } from './_adapter.mjs';
+import { startCollector } from './collector.mjs';
+
+// Returns a cursor so later reads can be bracketed to this flow. Without it,
+// repeated event names (`Perp Screen Viewed`) cross-match between flows.
+runAdapter(async (input) => {
+  const {
+    port,
+    pid,
+    eventsFile,
+    reused,
+    androidDevice,
+  } = await startCollector(input);
+  return {
+    action: input.action,
+    cursor: Date.now(),
+    port,
+    pid,
+    eventsFile,
+    reused,
+    androidDevice,
+    note: `Client must be built with its Segment host pointed at http://localhost:${port} (extension SEGMENT_HOST, mobile SEGMENT_PROXY_URL) and a non-empty write key.`,
+  };
+});