@deeeed/metamask-harness 0.70.1 → 0.71.0

package/adapters/terminal/lib/cdp-client.mjs

@@ -0,0 +1,84 @@
+// Minimal browser-level Chrome DevTools Protocol client with flattened target
+// sessions, for the long-running terminal wallet host. Page-level UI actions use
+// @farmslot/recipe-harness/runtime/cdp instead.
+
+import WebSocket from 'ws';
+
+export async function browserWebSocketUrl(port, timeoutMs = 15000) {
+  const deadline = Date.now() + timeoutMs;
+  let lastError;
+  while (Date.now() < deadline) {
+    try {
+      const response = await fetch(`http://127.0.0.1:${port}/json/version`);
+      if (response.ok) return (await response.json()).webSocketDebuggerUrl;
+    } catch (error) {
+      lastError = error;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 250));
+  }
+  throw new Error(`CDP on 127.0.0.1:${port} did not answer within ${timeoutMs}ms: ${lastError?.message ?? 'no response'}`);
+}
+
+export class CdpClient {
+  #ws;
+  #nextId = 1;
+  #pending = new Map();
+  #handlers = new Map();
+
+  static async connect(url) {
+    const client = new CdpClient();
+    client.#ws = new WebSocket(url, { perMessageDeflate: false, maxPayload: 256 * 1024 * 1024 });
+    await new Promise((resolve, reject) => {
+      client.#ws.once('open', resolve);
+      client.#ws.once('error', reject);
+    });
+    client.#ws.on('message', (data) => client.#dispatch(JSON.parse(String(data))));
+    client.#ws.on('close', () => {
+      for (const { reject } of client.#pending.values()) reject(new Error('CDP connection closed'));
+      client.#pending.clear();
+      client.#emit('close', {}, undefined);
+    });
+    return client;
+  }
+
+  #dispatch(message) {
+    if (message.id !== undefined) {
+      const pending = this.#pending.get(message.id);
+      if (!pending) return;
+      this.#pending.delete(message.id);
+      if (message.error) pending.reject(new Error(`${pending.method}: ${message.error.message}`));
+      else pending.resolve(message.result ?? {});
+      return;
+    }
+    this.#emit(message.method, message.params ?? {}, message.sessionId);
+  }
+
+  #emit(method, params, sessionId) {
+    for (const handler of this.#handlers.get(method) ?? []) {
+      try {
+        handler(params, sessionId);
+      } catch (error) {
+        process.stderr.write(`[cdp] handler for ${method} failed: ${error?.stack ?? error}\n`);
+      }
+    }
+  }
+
+  on(method, handler) {
+    if (!this.#handlers.has(method)) this.#handlers.set(method, new Set());
+    this.#handlers.get(method).add(handler);
+    return () => this.#handlers.get(method)?.delete(handler);
+  }
+
+  send(method, params = {}, sessionId = undefined) {
+    const id = this.#nextId++;
+    const payload = { id, method, params, ...(sessionId ? { sessionId } : {}) };
+    return new Promise((resolve, reject) => {
+      this.#pending.set(id, { resolve, reject, method });
+      this.#ws.send(JSON.stringify(payload));
+    });
+  }
+
+  close() {
+    this.#ws?.close();
+  }
+}

package/adapters/terminal/lib/display.mjs

@@ -0,0 +1,115 @@
+// How the slot browser is shown: headful (default) or headless, where its
+// window sits on screen, the page zoom that keeps the terminal's desktop layout
+// inside that window, and the optional slow-mo between UI actions.
+
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+
+const TRUE_VALUES = new Set(['1', 'true', 'yes', 'on']);
+const FALSE_VALUES = new Set(['0', 'false', 'no', 'off', '']);
+
+function envFlag(raw, label) {
+  if (raw == null) return undefined;
+  const value = String(raw).trim().toLowerCase();
+  if (TRUE_VALUES.has(value)) return true;
+  if (FALSE_VALUES.has(value)) return false;
+  throw new Error(`${label} must be 1/0 or true/false, got ${JSON.stringify(raw)}.`);
+}
+
+// Headless precedence: an explicit flag (--headless, or --headful as its
+// opposite) → the launch node (headless, or headful as its opposite) → env
+// TERMINAL_HEADLESS → headful.
+export function resolveHeadless({ headless, headful, nodeHeadless, nodeHeadful, env = process.env } = {}) {
+  if (headless === true && headful === true) throw new Error('--headless and --headful are mutually exclusive.');
+  if (headless === true) return true;
+  if (headful === true) return false;
+  if (typeof nodeHeadless === 'boolean') return nodeHeadless;
+  if (nodeHeadful === true) return false;
+  return envFlag(env.TERMINAL_HEADLESS, 'TERMINAL_HEADLESS') ?? false;
+}
+
+function slowMoValue(raw, label) {
+  if (raw == null || raw === '') return undefined;
+  const value = Number(raw);
+  if (!Number.isInteger(value) || value < 0 || value > 60000) {
+    throw new Error(`${label} must be whole milliseconds between 0 and 60000, got ${JSON.stringify(raw)}.`);
+  }
+  return value;
+}
+
+// Slow-mo precedence: --slow-mo → launch node slow_mo_ms → env TERMINAL_SLOW_MO → 0.
+export function resolveSlowMo({ flag, node, env = process.env } = {}) {
+  return slowMoValue(flag, '--slow-mo') ?? slowMoValue(node, 'slow_mo_ms') ?? slowMoValue(env.TERMINAL_SLOW_MO, 'TERMINAL_SLOW_MO') ?? 0;
+}
+
+// The order page switches layout at 800 and 1440 CSS px. Recipes were proven on
+// a 1600 CSS-px wide viewport, so a smaller window zooms out until the page
+// still lays out at least this wide.
+export const MIN_LAYOUT_WIDTH = 1460;
+export const MIN_ZOOM = 0.5;
+const FALLBACK_SCREEN = Object.freeze({ left: 0, top: 25, width: 1512, height: 920 });
+
+// The main screen's usable area in points (menu bar and Dock excluded).
+export function detectScreen(env = process.env) {
+  const explicit = /^(\d+)x(\d+)(?:\+(\d+)\+(\d+))?$/u.exec(String(env.TERMINAL_SCREEN ?? '').trim());
+  if (explicit) {
+    return { left: Number(explicit[3] ?? 0), top: Number(explicit[4] ?? 0), width: Number(explicit[1]), height: Number(explicit[2]), source: 'TERMINAL_SCREEN' };
+  }
+  if (process.platform === 'darwin') {
+    try {
+      const out = execFileSync('osascript', ['-l', 'JavaScript', '-e', [
+        'ObjC.import("AppKit");',
+        'const s = $.NSScreen.mainScreen; const f = s.frame; const v = s.visibleFrame;',
+        'JSON.stringify({ left: v.origin.x, top: f.size.height - v.origin.y - v.size.height, width: v.size.width, height: v.size.height })',
+      ].join(' ')], { encoding: 'utf8', timeout: 10000, stdio: ['ignore', 'pipe', 'ignore'] });
+      const screen = JSON.parse(out.trim());
+      if (screen.width > 0 && screen.height > 0) return { ...screen, source: 'main-screen' };
+    } catch {
+      // Fall through to a size that fits any current MacBook.
+    }
+  }
+  return { ...FALLBACK_SCREEN, source: 'fallback' };
+}
+
+// One window per slot, side by side: odd CDP ports (mmt-1: 9541) take the left
+// half of the main screen, even ports (mmt-2: 9542) the right half.
+// TERMINAL_WINDOW=x,y,width,height places the window explicitly.
+export function windowPlacement({ cdpPort, env = process.env, screen = null } = {}) {
+  const explicit = /^(-?\d+),(-?\d+),(\d+),(\d+)$/u.exec(String(env.TERMINAL_WINDOW ?? '').replace(/\s/gu, ''));
+  let bounds;
+  if (explicit) {
+    bounds = { x: Number(explicit[1]), y: Number(explicit[2]), width: Number(explicit[3]), height: Number(explicit[4]), source: 'TERMINAL_WINDOW' };
+  } else {
+    const area = screen ?? detectScreen(env);
+    const width = Math.floor(area.width / 2);
+    const column = Number(cdpPort) % 2 === 1 ? 0 : 1;
+    bounds = { x: Math.round(area.left) + column * width, y: Math.round(area.top), width, height: Math.floor(area.height), source: area.source ?? 'screen' };
+  }
+  const zoom = Math.max(MIN_ZOOM, Math.min(1, Math.floor((bounds.width / MIN_LAYOUT_WIDTH) * 100) / 100));
+  return { ...bounds, zoom };
+}
+
+// Chromium stores page zoom as a level: zoom = 1.2 ^ level. The profile's
+// default zoom applies to every page the slot browser opens.
+export function zoomLevel(zoom) {
+  return zoom === 1 ? 0 : Math.log(zoom) / Math.log(1.2);
+}
+
+export function writeProfileZoom(profile, zoom) {
+  const file = path.join(profile, 'Default', 'Preferences');
+  mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  const prefs = existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : {};
+  prefs.partition ??= {};
+  prefs.partition.default_zoom_level = { ...(prefs.partition.default_zoom_level ?? {}), x: zoomLevel(zoom) };
+  const temporary = `${file}.${process.pid}.tmp`;
+  writeFileSync(temporary, JSON.stringify(prefs), { mode: 0o600 });
+  renameSync(temporary, file);
+}
+
+// Headless keeps the tall viewport the recipes were first proven on; headful
+// opens a placed window instead.
+export function browserDisplayArgs({ headless, placement }) {
+  if (headless) return ['--headless=new', '--window-size=1600,2400'];
+  return [`--window-position=${placement.x},${placement.y}`, `--window-size=${placement.width},${placement.height}`];
+}

package/adapters/terminal/lib/hud.mjs

@@ -0,0 +1,148 @@
+// Recipe HUD for the terminal app tab: state handling and the page expression
+// that draws it.
+//
+// The overlay is an <mm-harness-hud> element under <html> (outside <body>) with
+// a closed shadow root, aria-hidden and pointer-events:none: page text, test-id
+// selectors, elementFromPoint clicks and the accessibility tree never see it.
+// It sits over the chart's top-left corner, below the chart toolbar, away from
+// the nav bar, the order form, the order rows and the bottom-left dev badge.
+// State lives in <runtime>/hud.json so the wallet host can redraw it after
+// every navigation; the expression only draws on the app origin, never inside
+// MetaMask's extension pages.
+
+import { readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+
+export const HUD_ELEMENT = 'mm-harness-hud';
+export const HUD_FILE = 'hud.json';
+const MAX_TEXT = 180;
+
+function text(value, max = MAX_TEXT) {
+  if (typeof value !== 'string' && typeof value !== 'number') return '';
+  const flat = String(value).replace(/\s+/gu, ' ').trim();
+  return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
+}
+
+function progressOf(raw) {
+  if (!raw || typeof raw !== 'object') return null;
+  const current = Number(raw.current);
+  const total = Number(raw.total);
+  if (!Number.isFinite(current) || !Number.isFinite(total) || total <= 0) return null;
+  return { current, total, complete: raw.complete === true };
+}
+
+// Fold one app.hud node into the previous state. A running node becomes the
+// current step; a pass/fail node also becomes the "last result" line, and the
+// recipe-complete node closes the run.
+export function nextHudState(prior, node = {}, nodeId = '') {
+  // A finished run's HUD stays up until the next run's first update replaces it.
+  const previous = prior?.finished ? { seq: prior.seq } : prior;
+  const status = ['running', 'pass', 'fail'].includes(node.status) ? node.status : 'running';
+  const progress = progressOf(node.progress);
+  const intent = text(node.intent ?? node.text ?? node.detail) || text(nodeId);
+  const id = text(node.node_id ?? node.nodeId ?? nodeId, 80);
+  const state = {
+    seq: (previous?.seq ?? 0) + 1,
+    title: text(node.title, 80) || previous?.title || 'Recipe run',
+    current: previous?.current ?? null,
+    last: previous?.last ?? null,
+    finished: null,
+  };
+  if (status === 'running') {
+    state.current = { nodeId: id, intent, progress: progress ?? previous?.current?.progress ?? null };
+    return state;
+  }
+  const error = status === 'fail' ? text(node.error) : '';
+  state.last = { nodeId: id, intent, status, ...(error ? { error } : {}) };
+  if (progress?.complete || id === 'recipe-complete') {
+    state.finished = status;
+    state.current = { nodeId: id, intent: status === 'pass' ? 'Recipe passed' : 'Recipe failed', progress };
+  } else if (progress) {
+    state.current = { ...(state.current ?? { nodeId: id, intent }), progress };
+  }
+  return state;
+}
+
+export function hudFile(runtimeDir) {
+  return path.join(runtimeDir, HUD_FILE);
+}
+
+export function readHudState(runtimeDir) {
+  try {
+    return JSON.parse(readFileSync(hudFile(runtimeDir), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+export function writeHudState(runtimeDir, state) {
+  const file = hudFile(runtimeDir);
+  const temporary = `${file}.${process.pid}.${Date.now()}.tmp`;
+  writeFileSync(temporary, `${JSON.stringify(state)}\n`, { mode: 0o600 });
+  renameSync(temporary, file);
+}
+
+export function clearHudState(runtimeDir) {
+  rmSync(hudFile(runtimeDir), { force: true });
+}
+
+const STYLE = `
+:host { all: initial; }
+.hud { position: fixed; top: 220px; left: 12px; z-index: 2147483647; width: 360px; max-width: calc(50vw - 24px);
+  box-sizing: border-box; padding: 8px 10px; border-radius: 8px; border: 1px solid rgba(255,255,255,.18);
+  background: rgba(16,18,24,.82); color: #f2f4f7; font: 12px/1.35 -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+  pointer-events: none; user-select: none; box-shadow: 0 4px 16px rgba(0,0,0,.35); }
+.row { display: flex; gap: 6px; align-items: baseline; }
+.title { font-weight: 600; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; flex: 1; }
+.step { color: #a9b1bd; font-variant-numeric: tabular-nums; }
+.intent { margin-top: 4px; }
+.badge { display: inline-block; padding: 0 5px; border-radius: 4px; font-size: 10px; font-weight: 700; letter-spacing: .03em; }
+.running { background: #2f6fed; color: #fff; }
+.pass { background: #1f9d55; color: #fff; }
+.fail { background: #d64545; color: #fff; }
+.last { margin-top: 4px; color: #c7cdd6; }
+.error { color: #ffb4b4; }
+`;
+
+// A self-contained page expression: draws (or clears, for null) the HUD when
+// the document is on the app origin, and skips the work when the same state
+// is already drawn.
+export function hudRenderExpression(state, appOrigin) {
+  return `(() => {
+    const state = ${JSON.stringify(state ?? null)};
+    if (location.origin !== ${JSON.stringify(String(appOrigin).replace(/\/$/u, ''))}) return { hud: false, reason: 'not-app-origin' };
+    const existing = document.documentElement.querySelector(':scope > ${HUD_ELEMENT}');
+    if (!state) { existing?.remove(); return { hud: false, cleared: true }; }
+    if (existing && existing.dataset.seq === String(state.seq)) return { hud: true, seq: state.seq, unchanged: true };
+    existing?.remove();
+    const host = document.createElement('${HUD_ELEMENT}');
+    host.dataset.seq = String(state.seq);
+    host.setAttribute('aria-hidden', 'true');
+    host.inert = true;
+    host.style.cssText = 'all: initial; position: fixed; inset: 0 auto auto 0; width: 0; height: 0; pointer-events: none; z-index: 2147483647;';
+    const root = host.attachShadow({ mode: 'closed' });
+    const el = (tag, cls, value) => { const node = document.createElement(tag); if (cls) node.className = cls; if (value != null) node.textContent = value; return node; };
+    const style = el('style', null, ${JSON.stringify(STYLE)});
+    const box = el('div', 'hud');
+    const head = el('div', 'row');
+    head.append(el('span', 'title', state.title));
+    const progress = state.current && state.current.progress;
+    if (progress) head.append(el('span', 'step', 'step ' + progress.current + '/' + progress.total));
+    box.append(head);
+    if (state.current) {
+      const line = el('div', 'intent');
+      const status = state.finished || 'running';
+      line.append(el('span', 'badge ' + status, status === 'running' ? 'RUN' : status.toUpperCase()), ' ', state.current.intent);
+      box.append(line);
+    }
+    if (state.last && !state.finished) {
+      const line = el('div', 'last');
+      line.append(el('span', 'badge ' + state.last.status, state.last.status.toUpperCase()), ' ', state.last.intent);
+      box.append(line);
+    }
+    if (state.last && state.last.error) box.append(el('div', 'last error', state.last.error));
+    root.append(style, box);
+    document.documentElement.append(host);
+    return { hud: true, seq: state.seq };
+  })()`;
+}

package/adapters/terminal/lib/mainnet-guard.mjs

@@ -0,0 +1,177 @@
+// Testnet enforcement for the terminal slot browser. In testnet mode nothing
+// the browser runs may reach a mainnet venue (Hyperliquid, or Lighter when the
+// controller carries it), whatever the dev server happens to serve:
+//   - the network layer: --host-resolver-rules makes every mainnet venue host
+//     unresolvable for the whole browser (pages, workers, WebSockets), and
+//     the wallet host fails and logs each attempt it sees (blocked-mainnet);
+//   - the wallet layer: a typed-data request for a mainnet action is refused
+//     before MetaMask or the injected signer sees it (refused-mainnet).
+// The venue hosts are the endpoints the venue SDK, the perps controller and
+// the app's source in the checkout connect to.
+
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+
+const SDK_PACKAGE = '@nktkas/hyperliquid';
+const CONTROLLER_PACKAGE = '@metamask/perps-controller';
+// Venue API hosts of the perps providers the terminal can configure: the
+// Hyperliquid API/RPC hosts and Lighter's zkLighter API.
+const VENUE_HOST = /^(?:[a-z0-9-]+\.)*(?:hyperliquid(?:-testnet)?\.xyz|zklighter\.elliot\.ai)$/u;
+// A URL in source text, any case; it is then parsed (canonicalUrl).
+const URL_CANDIDATE = /\b(?:https?|wss?):\/\/[^\s'"`<>(){}\\]+/giu;
+// Any mention of a venue host, URL or not: the cross-check of the SDK scan.
+const VENUE_HOST_MENTION = /(?<![\w.-])(?:[a-z0-9-]+\.)*(?:hyperliquid(?:-testnet)?\.xyz|zklighter\.elliot\.ai)(?![\w-])/giu;
+// Request paths of the venue APIs (info, exchange, WebSocket, EVM RPC,
+// Lighter's stream and REST API).
+const API_PATH = /^\/(?:ws|info|exchange|evm|stream|api)(?:\/|$)/u;
+const SOURCE_FILE = /\.(?:m?js|cjs|tsx?)$/u;
+// The venues' web hosts: the Hyperliquid app, which serves the coin icons the
+// terminal shows and the explorer pages it links to. Never an API endpoint,
+// on either network, so never blocked and never proof of the served network.
+export const LINK_HOSTS = new Set(['app.hyperliquid.xyz', 'app.hyperliquid-testnet.xyz']);
+
+function packageRoot(checkout, name) {
+  try {
+    const require = createRequire(path.join(checkout, 'package.json'));
+    return path.dirname(require.resolve(`${name}/package.json`));
+  } catch {
+    const direct = path.join(checkout, 'node_modules', name);
+    return existsSync(path.join(direct, 'package.json')) ? direct : null;
+  }
+}
+
+function* sourceFiles(dir, depth = 0) {
+  if (depth > 12) return;
+  for (const entry of readdirSync(dir)) {
+    if (entry === 'node_modules') continue;
+    const file = path.join(dir, entry);
+    const stat = statSync(file);
+    if (stat.isDirectory()) yield* sourceFiles(file, depth + 1);
+    else if (SOURCE_FILE.test(entry)) yield file;
+  }
+}
+
+export function isTestnetHost(host) {
+  return /(?:^|[.-])testnet(?:[.-]|$)/u.test(host);
+}
+
+// Venue URLs in source text, by kind: hosts used with an API path, hosts
+// used bare (a base URL whose paths are appended elsewhere), and hosts with
+// any other path (/rpc, /health, /coins/BTC.svg). Link hosts are left out,
+// except that a link host with an API path is reported (linkApi).
+export function venueUrlHosts(text) {
+  const found = { api: new Set(), bare: new Set(), other: new Set(), linkApi: new Set() };
+  for (const [candidate] of text.matchAll(URL_CANDIDATE)) {
+    const url = canonicalUrl(candidate);
+    if (!url || !VENUE_HOST.test(url.hostname)) continue;
+    const { hostname: host, pathname } = url;
+    // The path as a server reads it: decoded, any case.
+    const apiPath = API_PATH.test(safeDecode(pathname).toLowerCase());
+    if (LINK_HOSTS.has(host)) {
+      // A link host used as an API: the exemption would hide an endpoint.
+      if (apiPath) found.linkApi.add(`${host}${pathname}`);
+      continue;
+    }
+    if (apiPath) found.api.add(host);
+    else if (pathname === '/') found.bare.add(host);
+    else found.other.add(host);
+  }
+  return found;
+}
+
+
+// Endpoint hosts in one text: with anyPath (the venue SDK) every venue host;
+// otherwise API URLs and base URLs.
+export function venueEndpointHosts(text, { anyPath = false } = {}) {
+  const { api, bare, other } = venueUrlHosts(text);
+  return new Set([...api, ...bare, ...(anyPath ? other : [])]);
+}
+
+// The venue hosts the checkout can connect to. { mainnet: [...], testnet: [...] }
+//   - the venue SDK: every venue host, whatever the path;
+//   - the perps controller and the app's own source: API URLs and base URLs.
+// Link hosts (LINK_HOSTS) are never on either list, and a link host with an
+// API path in any scanned source fails the launch. Every mainnet host the SDK
+// mentions (as a URL or not) must be on the list, or the launch fails.
+export function venueHosts(checkout) {
+  const sdk = packageRoot(checkout, SDK_PACKAGE);
+  if (!sdk) throw new Error(`${SDK_PACKAGE} is not installed in ${checkout}; the mainnet block list comes from it.`);
+  const sources = [
+    { root: sdk, anyPath: true },
+    { root: packageRoot(checkout, CONTROLLER_PACKAGE), anyPath: false },
+    { root: path.join(checkout, 'src'), anyPath: false },
+  ].filter(({ root }) => root && existsSync(root));
+  const hosts = new Set();
+  const sdkMentions = new Set();
+  for (const { root, anyPath } of sources) {
+    for (const file of sourceFiles(root)) {
+      const text = readFileSync(file, 'utf8');
+      const { linkApi } = venueUrlHosts(text);
+      if (linkApi.size > 0) throw new Error(`${file} uses the venue web host as an API (${[...linkApi].join(', ')}); it is exempt from the mainnet block, so refusing to launch.`);
+      for (const host of venueEndpointHosts(text, { anyPath })) hosts.add(host);
+      if (anyPath) {
+        for (const [mention] of text.matchAll(VENUE_HOST_MENTION)) {
+          const host = mention.toLowerCase();
+          if (!LINK_HOSTS.has(host)) sdkMentions.add(host);
+        }
+      }
+    }
+  }
+  const mainnet = [...hosts].filter((host) => !isTestnetHost(host)).sort();
+  const testnet = [...hosts].filter((host) => isTestnetHost(host)).sort();
+  if (mainnet.length === 0) throw new Error(`no mainnet venue host found in ${SDK_PACKAGE} at ${sdk}; refusing to launch without a block list.`);
+  const missing = [...sdkMentions].filter((host) => !isTestnetHost(host) && !mainnet.includes(host));
+  if (missing.length > 0) throw new Error(`the mainnet block list misses ${missing.join(', ')}, which ${SDK_PACKAGE} names; refusing to launch.`);
+  return { mainnet, testnet };
+}
+
+export function mainnetVenueHosts(checkout) {
+  return venueHosts(checkout).mainnet;
+}
+
+export function hostResolverRules(hosts) {
+  // The host and its fully qualified form (trailing dot) alike.
+  return `--host-resolver-rules=${hosts.flatMap((host) => [`MAP ${host} ~NOTFOUND`, `MAP ${host}. ~NOTFOUND`]).join(', ')}`;
+}
+
+// A URL as the network sees it: new URL() lowercases the host, drops a
+// default port and resolves dot segments; a trailing dot names the same host.
+// { hostname, pathname }, or null.
+export function canonicalUrl(value) {
+  try {
+    const url = new URL(String(value));
+    return { hostname: url.hostname.toLowerCase().replace(/\.$/u, ''), pathname: url.pathname };
+  } catch {
+    return null;
+  }
+}
+
+function safeDecode(value) {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+}
+
+export function hostOf(url) {
+  return canonicalUrl(url)?.hostname ?? null;
+}
+
+export function isMainnetVenueUrl(url, hosts) {
+  const host = hostOf(url);
+  return host !== null && hosts.includes(host);
+}
+
+// A Hyperliquid action meant for mainnet: user-signed actions carry
+// hyperliquidChain "Mainnet"; L1 actions are signed as a phantom Agent whose
+// source is "a" on mainnet ("b" on testnet).
+export function mainnetTypedDataReason(data) {
+  const message = data?.message ?? {};
+  if (typeof message.hyperliquidChain === 'string' && message.hyperliquidChain.toLowerCase() === 'mainnet') {
+    return 'hyperliquidChain=Mainnet';
+  }
+  if (data?.primaryType === 'Agent' && message.source === 'a') return 'L1 Agent source=a';
+  return null;
+}

package/adapters/terminal/lib/origin.mjs

@@ -0,0 +1,30 @@
+// Exact app-origin checks for the terminal slot. A prefix match would let
+// http://localhost:30001 pass for http://localhost:3000, so every check parses
+// the URL and compares origins.
+
+export function originOf(url) {
+  try {
+    return new URL(String(url)).origin;
+  } catch {
+    return null;
+  }
+}
+
+export function isAppUrl(url, appOrigin) {
+  const origin = originOf(url);
+  return origin !== null && origin !== 'null' && origin === originOf(appOrigin);
+}
+
+// A wallet request (or log entry) is accepted only from the default execution
+// context of the tab's top frame, on the app origin, while that frame's
+// committed document is an app URL. The committed URL matters because an
+// about:blank document (a popup the app opened) inherits the app origin. For
+// a page target the main frame id equals the target id.
+export function isAppTopFrameContext(context, { targetId, appOrigin, committedUrl }) {
+  if (!context || !targetId) return false;
+  const aux = context.auxData ?? {};
+  return aux.isDefault === true &&
+    aux.frameId === targetId &&
+    isAppUrl(context.origin, appOrigin) &&
+    isAppUrl(committedUrl, appOrigin);
+}