@farmslot/adapter-web 0.5.0 → 0.6.0

package/src/web-dapp/lib/blocked-hosts.mjs

@@ -0,0 +1,24 @@
+// Testnet enforcement mechanics for the web-dapp slot browser: the hosts a
+// venue policy blocks become unresolvable for the whole browser (pages,
+// workers, WebSockets), and the wallet host fails and logs each request it
+// sees to one of them. Which hosts is the venue policy's (venueHosts).
+
+// A URL's host as the network sees it: lowercase, no trailing dot. null when
+// it does not parse.
+export function hostOf(url) {
+  try {
+    return new URL(String(url)).hostname.toLowerCase().replace(/\.$/u, '');
+  } catch {
+    return null;
+  }
+}
+
+export function isBlockedUrl(url, hosts) {
+  const host = hostOf(url);
+  return host !== null && hosts.includes(host);
+}
+
+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(', ')}`;
+}

package/src/web-dapp/lib/cdp-client.mjs

@@ -0,0 +1,86 @@
+// Minimal browser-level Chrome DevTools Protocol client with flattened target
+// sessions, for the long-running web-dapp wallet host. Page-level UI actions use
+// @farmslot/recipe-runner/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/src/web-dapp/lib/display.mjs

@@ -0,0 +1,169 @@
+// How the slot browser is shown: headful (default) or headless, where its
+// window sits on screen, the page zoom that keeps the app'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/src/web-dapp/lib/hud.mjs

@@ -0,0 +1,156 @@
+// Recipe HUD for the web-dapp 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/src/web-dapp/lib/paths.mjs

@@ -0,0 +1,55 @@
+// The checkout layout the web-dapp leaves share (`temp/recipe/runtime/<adapter>/`).
+// Local copies of the recipe-cli harness path helpers: adapter-web does not
+// depend on @farmslot/recipe-cli. The environment names and defaults match.
+
+import path from 'node:path';
+
+export const DEFAULT_RECIPE_RUNTIME_DIR = 'temp/recipe/runtime';
+export const DEFAULT_RECIPE_HARNESS_ROOT = 'temp/recipe/harness';
+
+export function validateRelativeRecipePath(name, value) {
+  if (!value || path.isAbsolute(value)) {
+    throw new Error(`${name} must be a non-empty relative path: ${value}`);
+  }
+  if (!/^[A-Za-z0-9._/-]+$/u.test(value)) {
+    throw new Error(`${name} contains unsupported characters: ${value}`);
+  }
+  for (const part of value.split('/')) {
+    if (!part || part === '.' || part === '..') {
+      throw new Error(`${name} contains unsafe path component: ${value}`);
+    }
+  }
+  return value;
+}
+
+/** The checkout-relative runtime directory: `RECIPE_RUNTIME_DIR`, else the default. */
+export function recipeRuntimeDir() {
+  return validateRelativeRecipePath(
+    'RECIPE_RUNTIME_DIR',
+    process.env.RECIPE_RUNTIME_DIR || DEFAULT_RECIPE_RUNTIME_DIR,
+  );
+}
+
+/** The checkout-relative overlay directory: `RECIPE_HARNESS_ROOT`, else the default. */
+export function recipeHarnessRoot() {
+  return validateRelativeRecipePath(
+    'RECIPE_HARNESS_ROOT',
+    process.env.RECIPE_HARNESS_ROOT || DEFAULT_RECIPE_HARNESS_ROOT,
+  );
+}
+
+export function recipeRuntimePath(projectRoot, ...segments) {
+  return path.join(projectRoot, recipeRuntimeDir(), ...segments);
+}
+
+export function recipeHarnessPath(projectRoot, ...segments) {
+  return path.join(projectRoot, recipeHarnessRoot(), ...segments);
+}
+
+export function walletFixturePath(projectRoot) {
+  return recipeRuntimePath(projectRoot, 'wallet-fixture.json');
+}
+
+export function shellQuote(value) {
+  return `'${value.replace(/'/gu, `'\\''`)}'`;
+}

package/src/web-dapp/lib/policy-fence.mjs

@@ -0,0 +1,128 @@
+// The venue policy module runs outside the plugin loader's import fence: the
+// host and every web-dapp leaf process require it by path. So mm-harness checks
+// it itself when it binds the adapter: the policy file and everything it
+// imports must be files the plugin digest covers (the loader's
+// libraryAdapterFiles, by real path), and imports must be literal relative
+// paths or node built-ins. The digest of those files goes in
+// RECIPE_WEB_DAPP_POLICY_DIGEST, and a process that loads the policy with it
+// set refuses files that changed since.
+
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import { isBuiltin } from 'node:module';
+import path from 'node:path';
+
+export const POLICY_DIGEST_ENV = 'RECIPE_WEB_DAPP_POLICY_DIGEST';
+
+export class PolicyFenceError extends Error {
+  constructor(message) {
+    super(message);
+    this.code = 'ADAPTER_PLUGIN_INVALID';
+    this.userAction =
+      "keep the venue policy and every file it imports in the plugin module's directory (or the library's actions/), importing node built-ins and literal relative paths only";
+  }
+}
+
+const STATIC_IMPORT = /(?:^|[\s;])(?:import|export)\b[^'"`;]*?\bfrom\s*(['"])([^'"]+)\1/gu;
+const BARE_IMPORT = /(?:^|[\s;])import\s*(['"])([^'"]+)\1/gu;
+const LITERAL_CALL = /(?<![.\w$])(?:import|require)\s*\(\s*(['"])([^'"]+)\1\s*\)/gu;
+const ANY_CALL = /(?<![.\w$])(?:import|require)\s*\(/gu;
+
+// Whole-line comments may mention imports and are dropped. Nothing else is: a
+// block or trailing comment that mentions an import is read as one and refused,
+// so the scan errs on the side of refusing, never of missing an import.
+function stripComments(source) {
+  return source.replace(/^\s*\/\/.*$/gmu, '');
+}
+
+function specifiers(source, file) {
+  const code = stripComments(source);
+  const found = [];
+  for (const pattern of [STATIC_IMPORT, BARE_IMPORT, LITERAL_CALL]) {
+    for (const match of code.matchAll(pattern)) found.push(match[2]);
+  }
+  const literalCalls = [...code.matchAll(LITERAL_CALL)].length;
+  if ([...code.matchAll(ANY_CALL)].length > literalCalls) {
+    throw new PolicyFenceError(
+      `web-dapp venue policy file ${file} imports or requires a computed specifier, which the host can't check.`,
+    );
+  }
+  return found;
+}
+
+function realFile(file) {
+  try {
+    const real = fs.realpathSync(file);
+    if (fs.statSync(real).isFile()) return real;
+  } catch {
+    // reported below
+  }
+  return undefined;
+}
+
+/**
+ * The real paths of the policy module and every file it imports, in import
+ * order. `allowed(real)` decides each file; relative specifiers resolve
+ * against the importer's real path, as Node does.
+ */
+function policyClosure(file, allowed) {
+  const start = realFile(path.resolve(file));
+  if (!start) throw new PolicyFenceError(`web-dapp venue policy file ${file} does not exist.`);
+  const seen = new Set();
+  const visit = (real) => {
+    if (seen.has(real)) return;
+    allowed(real);
+    seen.add(real);
+    for (const specifier of specifiers(fs.readFileSync(real, 'utf8'), real)) {
+      if (specifier.startsWith('node:') || isBuiltin(specifier)) continue;
+      if (!specifier.startsWith('./') && !specifier.startsWith('../')) {
+        throw new PolicyFenceError(
+          `web-dapp venue policy file ${real} imports '${specifier}', which is neither a node built-in nor a relative path the plugin digest covers.`,
+        );
+      }
+      const target = realFile(path.resolve(path.dirname(real), specifier));
+      if (!target)
+        throw new PolicyFenceError(
+          `web-dapp venue policy file ${real} imports '${specifier}', which does not resolve to a file.`,
+        );
+      visit(target);
+    }
+  };
+  visit(start);
+  return [...seen];
+}
+
+function digestFiles(files) {
+  const hash = createHash('sha256');
+  for (const file of [...files].sort()) {
+    hash.update(file).update('\0').update(fs.readFileSync(file)).update('\0');
+  }
+  return hash.digest('hex');
+}
+
+/**
+ * Check a policy module against `covered`, the real paths of the files the
+ * plugin digest covers, and return the digest of the policy's files. Throws
+ * PolicyFenceError when one of them is not covered.
+ */
+export function fencePolicy({ file, covered, scope }) {
+  const allowed = (real) => {
+    if (!covered.has(real)) {
+      throw new PolicyFenceError(
+        `web-dapp venue policy file ${real} is outside the files the plugin digest covers (${scope}).`,
+      );
+    }
+  };
+  return digestFiles(policyClosure(file, allowed));
+}
+
+/** Refuse a policy whose files changed since mm-harness bound it (`digest`). */
+export function assertPolicyDigest(file, digest) {
+  const now = digestFiles(policyClosure(file, () => {}));
+  if (now !== digest) {
+    throw new Error(
+      `web-dapp venue policy ${file} or a file it imports changed since the host bound it.\n` +
+        'Next: rerun the command, so it binds and checks the policy again.',
+    );
+  }
+}