@diegosouzacdv/jev-browser-mcp 0.7.1 → 0.7.2

package/mcp_servers/jev-browser-npm/src/test-integrations.mjs

@@ -0,0 +1,655 @@
+import { createHash, timingSafeEqual } from "node:crypto";
+import { spawn } from "node:child_process";
+import { lstat, open, realpath, stat } from "node:fs/promises";
+import path from "node:path";
+import { PassThrough } from "node:stream";
+import { setTimeout as delay } from "node:timers/promises";
+import { JevBrowserError } from "./config.mjs";
+import { isProfileOriginAllowed, requireEnvironmentProfile, resolveRemotePath } from "./environment-profiles.mjs";
+
+const SENSITIVE_KEY = /(?:pass(?:word)?|secret|token|authorization|cookie|credential|api[_-]?key|private[_-]?key|email|cpf|cnpj|matricula|identity|phone|telefone|address|endereco|user(?:name)?|usuario)/i;
+const SECRET_VALUE = /(?:Bearer\s+\S+|(?:password|token|secret|api[_-]?key)\s*[:=]\s*[^\s,;]+)/ig;
+const SAFE_RESPONSE_HEADERS = new Set(["cache-control", "content-length", "content-type", "date", "etag", "last-modified", "retry-after", "vary"]);
+
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function redactValue(value, depth = 0) {
+  if (depth > 8) return "[omitted]";
+  if (Array.isArray(value)) return value.slice(0, 100).map((item) => redactValue(item, depth + 1));
+  if (!isRecord(value)) return typeof value === "string" ? value.replace(SECRET_VALUE, "[redacted]").slice(0, 4000) : value;
+  return Object.fromEntries(Object.entries(value).slice(0, 100).map(([key, item]) => [key, SENSITIVE_KEY.test(key) ? "[redacted]" : redactValue(item, depth + 1)]));
+}
+
+function envValue(settings, name) {
+  const value = settings.env[name];
+  if (typeof value !== "string" || !value.trim()) throw new JevBrowserError(`required environment variable ${name} is not configured`);
+  return value;
+}
+
+function safeFilename(value, maxChars) {
+  if (typeof value !== "string" || !value.trim() || value.length > maxChars || value.includes("\0")
+    || value === "." || value === ".." || /[\\/<>:"|?*\u0000-\u001f\u007f]/u.test(value)) {
+    throw new JevBrowserError("fixture file_name must be a safe filename without path separators");
+  }
+  return value.normalize("NFC");
+}
+
+function mimeType(filename) {
+  const extension = path.extname(filename).toLowerCase();
+  return new Map([
+    [".pdf", "application/pdf"], [".txt", "text/plain"], [".csv", "text/csv"],
+    [".json", "application/json"], [".png", "image/png"], [".jpg", "image/jpeg"],
+  ]).get(extension) || "application/octet-stream";
+}
+
+function makePdf(text) {
+  const escaped = text.replace(/[^\x20-\x7e]/g, "?").replace(/[\\()]/g, "\\$&");
+  const objects = [
+    "<< /Type /Catalog /Pages 2 0 R >>",
+    "<< /Type /Pages /Kids [3 0 R] /Count 1 >>",
+    "<< /Type /Page /Parent 2 0 R /MediaBox [0 0 612 792] /Resources << /Font << /F1 4 0 R >> >> /Contents 5 0 R >>",
+    "<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica >>",
+    `<< /Length ${Buffer.byteLength(`BT /F1 12 Tf 72 720 Td (${escaped}) Tj ET\n`, "ascii")} >>\nstream\nBT /F1 12 Tf 72 720 Td (${escaped}) Tj ET\nendstream`,
+  ];
+  let document = "%PDF-1.4\n";
+  const offsets = [0];
+  for (let index = 0; index < objects.length; index += 1) {
+    offsets.push(Buffer.byteLength(document, "ascii"));
+    document += `${index + 1} 0 obj\n${objects[index]}\nendobj\n`;
+  }
+  const xrefOffset = Buffer.byteLength(document, "ascii");
+  document += `xref\n0 ${objects.length + 1}\n0000000000 65535 f \n`;
+  for (const offset of offsets.slice(1)) document += `${String(offset).padStart(10, "0")} 00000 n \n`;
+  document += `trailer\n<< /Size ${objects.length + 1} /Root 1 0 R >>\nstartxref\n${xrefOffset}\n%%EOF\n`;
+  return Buffer.from(document, "ascii");
+}
+
+function deterministicBytes(size) {
+  const output = Buffer.alloc(size);
+  let offset = 0;
+  let counter = 0;
+  while (offset < size) {
+    const block = createHash("sha256").update(`jev-browser-fixture:${counter}`).digest();
+    block.copy(output, offset, 0, Math.min(block.length, size - offset));
+    offset += block.length;
+    counter += 1;
+  }
+  return output;
+}
+
+async function verifyManagedFile(filePath, settings) {
+  const roots = [settings.browser.uploadStagingDirectory, settings.browser.uploadRoot].filter(Boolean).map((root) => path.resolve(root));
+  const resolved = await realpath(filePath).catch(() => { throw new JevBrowserError("fixture file could not be read from a permitted upload directory"); });
+  const allowed = roots.some((root) => {
+    const relative = path.relative(root, resolved);
+    return relative !== "" && relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+  });
+  const info = await stat(resolved);
+  if (!allowed || !info.isFile() || info.size > settings.browser.maxUploadFileBytes) {
+    throw new JevBrowserError("file path must resolve to a regular file within the configured upload root and size limit");
+  }
+  const handle = await open(resolved, "r");
+  try { return { path: resolved, info, buffer: await handle.readFile() }; }
+  finally { await handle.close(); }
+}
+
+function jsonPathValue(value, jsonPath) {
+  const parts = jsonPath.split(".");
+  let current = value;
+  for (const part of parts) {
+    if (!part || part === "__proto__" || part === "constructor" || part === "prototype") return undefined;
+    if (Array.isArray(current) && /^\d+$/.test(part)) current = current[Number(part)];
+    else if (isRecord(current) && Object.hasOwn(current, part)) current = current[part];
+    else return undefined;
+  }
+  return current;
+}
+
+function normalizedComparable(value) {
+  if (Array.isArray(value)) return value.map(normalizedComparable);
+  if (isRecord(value)) return Object.fromEntries(Object.keys(value).sort().map((key) => [key, normalizedComparable(value[key])]));
+  return value;
+}
+
+function matchesExpected(actual, expected) {
+  return Object.entries(expected).every(([key, value]) => JSON.stringify(normalizedComparable(actual?.[key])) === JSON.stringify(normalizedComparable(value)));
+}
+
+export function assertReadOnlySql(sql, maxQueryChars) {
+  if (!Number.isSafeInteger(maxQueryChars) || maxQueryChars <= 0 || typeof sql !== "string" || sql.length > maxQueryChars || !/^\s*select\b/i.test(sql)
+    || sql.includes(";") || /\b(?:insert|update|delete|merge|alter|drop|truncate|create|grant|revoke|commit|rollback|execute|call|begin|declare)\b/i.test(sql)) {
+    throw new JevBrowserError("assert_db accepts one read-only SELECT statement without PL/SQL or additional statements");
+  }
+}
+
+function variableMap(step) {
+  return isRecord(step.binds) ? step.binds : {};
+}
+
+async function assertDatabase(step, settings, profile, variables, secrets, adapters = {}) {
+  if (!profile.database) throw new JevBrowserError(`environment profile ${profile.id} has no read-only database configuration`);
+  assertReadOnlySql(step.sql, settings.browser.maxDatabaseQueryChars);
+  const binds = variableMap(step);
+  let rows;
+  if (profile.database.engine === "postgresql") {
+    const Pool = adapters.pgPool || (await import("pg")).Pool;
+    const pool = new Pool({
+      connectionString: envValue(settings, profile.database.connectionEnv),
+      max: 1,
+      connectionTimeoutMillis: profile.database.timeoutMs,
+      statement_timeout: profile.database.timeoutMs,
+      query_timeout: profile.database.timeoutMs,
+      allowExitOnIdle: true,
+    });
+    let client;
+    try {
+      client = await pool.connect();
+      await client.query("BEGIN READ ONLY");
+      await client.query("SELECT set_config('statement_timeout', $1, true)", [`${profile.database.timeoutMs}ms`]);
+      const boundedSql = `SELECT * FROM (${step.sql}) AS jev_browser_bounded_result LIMIT ${profile.database.maxRows + 1}`;
+      const reply = await client.query({ text: boundedSql, values: Object.values(binds), rowMode: "array" });
+      rows = reply.rows.slice(0, profile.database.maxRows).map((values) => Object.fromEntries(reply.fields.map((field, index) => [field.name, values[index]])));
+      if (reply.rowCount > profile.database.maxRows) throw new JevBrowserError("assert_db result exceeded the configured row limit");
+      await client.query("ROLLBACK");
+    } catch (error) {
+      await client?.query("ROLLBACK").catch(() => {});
+      if (error instanceof JevBrowserError) throw error;
+      throw new JevBrowserError(`assert_db PostgreSQL query failed (${error?.code || "database error"})`);
+    } finally {
+      client?.release();
+      await pool.end();
+    }
+  } else {
+    const oracledb = adapters.oracledb || (await import("oracledb")).default;
+    const connection = await oracledb.getConnection({
+      connectString: envValue(settings, profile.database.connectEnv),
+      user: envValue(settings, profile.database.userEnv),
+      password: envValue(settings, profile.database.passwordEnv),
+    });
+    connection.callTimeout = profile.database.timeoutMs;
+    try {
+      await connection.execute("SET TRANSACTION READ ONLY");
+      const reply = await connection.execute(step.sql, binds, {
+        outFormat: oracledb.OUT_FORMAT_OBJECT,
+        maxRows: profile.database.maxRows + 1,
+        fetchArraySize: Math.min(100, profile.database.maxRows),
+      });
+      rows = (reply.rows || []).slice(0, profile.database.maxRows);
+      if ((reply.rows || []).length > profile.database.maxRows) throw new JevBrowserError("assert_db result exceeded the configured row limit");
+      await connection.rollback();
+    } catch (error) {
+      await connection.rollback().catch(() => {});
+      if (error instanceof JevBrowserError) throw error;
+      throw new JevBrowserError(`assert_db Oracle query failed (${error?.errorNum || "database error"})`);
+    } finally {
+      await connection.close();
+    }
+  }
+  const expected = step.expected;
+  const countMatched = expected.row_count === undefined || rows.length === expected.row_count;
+  const firstRowMatched = expected.first_row === undefined || matchesExpected(rows[0], expected.first_row);
+  const allRowsMatched = expected.rows === undefined || JSON.stringify(normalizedComparable(rows)) === JSON.stringify(normalizedComparable(expected.rows));
+  const matched = countMatched && firstRowMatched && allRowsMatched;
+  if (!matched) throw new JevBrowserError(`assert_db failed for profile ${profile.id}: expected result did not match (${rows.length} row(s))`);
+  for (const [as, extraction] of Object.entries(step.extract || {})) {
+    const extracted = jsonPathValue(rows[extraction.row ?? 0], extraction.column);
+    if (extracted === undefined) throw new JevBrowserError(`assert_db extract ${as} did not resolve to a selected column`);
+    variables[as] = String(extracted);
+    if (SENSITIVE_KEY.test(extraction.column) && String(extracted) && !secrets.includes(String(extracted))) secrets.push(String(extracted));
+  }
+  return { action: step.action, asserted: true, engine: profile.database.engine, row_count: rows.length };
+}
+
+async function readLogSince(session, source, since, maxBytes) {
+  const configuredPath = session.profile.logSources[source];
+  if (!configuredPath) throw new JevBrowserError(`log source ${source} is not allow-listed in environment profile ${session.profile.id}`);
+  const info = await lstat(configuredPath).catch(() => { throw new JevBrowserError(`configured log source ${source} is unavailable`); });
+  if (info.isSymbolicLink() || !info.isFile()) throw new JevBrowserError(`configured log source ${source} must be a regular non-symlink file`);
+  const realFile = await realpath(configuredPath);
+  if (realFile !== path.resolve(configuredPath)) throw new JevBrowserError(`configured log source ${source} must not use symlinks`);
+  const currentSize = (await stat(realFile)).size;
+  const initial = session.logFlowOffsets[source] ?? 0;
+  const fromStep = session.logStepOffsets.get(Number(String(since).slice(5)))?.[source];
+  const offset = since === "flow" ? initial : fromStep;
+  if (offset === undefined) throw new JevBrowserError("assert_log since must be flow or a previously executed step:N");
+  const start = Math.max(offset, currentSize - maxBytes);
+  const length = Math.max(0, currentSize - start);
+  const handle = await open(realFile, "r");
+  try {
+    const buffer = Buffer.alloc(length);
+    if (length) await handle.read(buffer, 0, length, start);
+    return { text: buffer.toString("utf8"), truncated: start > offset };
+  } finally { await handle.close(); }
+}
+
+async function startMailbox(session, settings) {
+  if (session.smtpServer) return session.smtpAddress;
+  const smtp = session.profile.smtpCapture;
+  if (!smtp) throw new JevBrowserError(`environment profile ${session.profile.id} has no smtp_capture configuration`);
+  const [{ SMTPServer }, { simpleParser }] = await Promise.all([import("smtp-server"), import("mailparser")]);
+  session.mailParser = simpleParser;
+  const maxBytes = settings.browser.maxNetworkErrorBodyBytes;
+  session.smtpServer = new SMTPServer({
+    disabledCommands: ["AUTH", "STARTTLS"],
+    authOptional: true,
+    size: maxBytes,
+    onData(stream, _session, callback) {
+      const chunks = [];
+      let total = 0;
+      let overflow = false;
+      stream.on("data", (chunk) => {
+        total += chunk.length;
+        if (total <= maxBytes) chunks.push(chunk);
+        else overflow = true;
+      });
+      stream.on("error", (error) => callback(error));
+      stream.on("end", async () => {
+        if (overflow) return callback(new Error("message exceeds configured SMTP capture limit"));
+        try {
+          const parsed = await session.mailParser(Buffer.concat(chunks, total));
+          if (session.mailbox.length >= smtp.maxMessages) return callback(new Error("SMTP capture mailbox is full"));
+          session.mailbox.push({
+            from: String(parsed.from?.text || "").slice(0, 512),
+            to: (parsed.to?.value || []).map(({ address }) => String(address || "").slice(0, 254)).slice(0, 50),
+            subject: String(parsed.subject || "").slice(0, 1000),
+            text: String(parsed.text || "").slice(0, maxBytes),
+            html: String(parsed.html || "").slice(0, maxBytes),
+            received_at: new Date().toISOString(),
+          });
+          callback(null, "message captured by jev-browser test mailbox");
+        } catch {
+          callback(new Error("SMTP message could not be parsed"));
+        }
+      });
+    },
+  });
+  await new Promise((resolve, reject) => {
+    const fail = (error) => reject(error);
+    session.smtpServer.once("error", fail);
+    session.smtpServer.listen(smtp.port, smtp.bindAddress, () => {
+      session.smtpServer.removeListener("error", fail);
+      resolve();
+    });
+  }).catch((error) => {
+    session.smtpServer = undefined;
+    throw new JevBrowserError(`test SMTP capture could not bind to ${smtp.bindAddress}:${smtp.port} (${error?.code || "bind error"})`);
+  });
+  const address = session.smtpServer.server.address();
+  session.smtpAddress = { host: smtp.bindAddress, port: address.port };
+  return session.smtpAddress;
+}
+
+async function assertEmail(step, session, settings) {
+  if (!session.profile.smtpCapture) throw new JevBrowserError("assert_email needs an environment profile with smtp_capture configured");
+  if (!session.smtpServer) throw new JevBrowserError("assert_email requires start_email_capture before the application sends its message");
+  const timeoutMs = step.timeoutMs ?? settings.browser.actionTimeoutMs;
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() <= deadline) {
+    const message = session.mailbox.find((item) => (!step.to || item.to.some((to) => to.toLowerCase() === step.to.toLowerCase()))
+      && (!step.subjectContains || item.subject.toLowerCase().includes(step.subjectContains.toLowerCase()))
+      && (!step.bodyContains || `${item.text}\n${item.html}`.toLowerCase().includes(step.bodyContains.toLowerCase())));
+    if (message) return { action: step.action, asserted: true, recipient_matched: Boolean(step.to), subject_matched: Boolean(step.subjectContains), body_matched: Boolean(step.bodyContains), received_at: message.received_at };
+    await delay(Math.min(100, Math.max(1, deadline - Date.now())));
+  }
+  throw new JevBrowserError(`assert_email did not observe a matching message within ${timeoutMs}ms`);
+}
+
+function requiredRemoteCredentials(remote, settings) {
+  return {
+    user: envValue(settings, remote.usernameEnv),
+    password: envValue(settings, remote.passwordEnv),
+  };
+}
+
+function verifiedHostFingerprint(value) {
+  return String(value || "").replace(/^SHA256:/i, "").replace(/=+$/, "");
+}
+
+async function withRemote(remoteId, profile, settings, operation) {
+  const remote = profile.remotes[remoteId];
+  if (!remote) throw new JevBrowserError(`remote server ${remoteId} is not configured in environment profile ${profile.id}`);
+  const credentials = requiredRemoteCredentials(remote, settings);
+  if (remote.protocol === "sftp") {
+    const module = await import("ssh2-sftp-client");
+    const Client = module.default;
+    const client = new Client("jev-browser-test");
+    const expected = verifiedHostFingerprint(envValue(settings, remote.hostFingerprintEnv));
+    if (!expected) throw new JevBrowserError("SFTP host fingerprint is empty");
+    await client.connect({
+      host: remote.host,
+      port: remote.port,
+      username: credentials.user,
+      password: credentials.password,
+      hostHash: "sha256",
+      hostVerifier: (hash) => {
+        const actual = verifiedHostFingerprint(Buffer.isBuffer(hash) ? hash.toString("base64") : hash);
+        const actualBytes = Buffer.from(actual);
+        const expectedBytes = Buffer.from(expected);
+        return actualBytes.length === expectedBytes.length && timingSafeEqual(actualBytes, expectedBytes);
+      },
+      readyTimeout: settings.browser.actionTimeoutMs,
+    });
+    try { return await operation(client, remote); } finally { await client.end().catch(() => {}); }
+  }
+  const module = await import("basic-ftp");
+  const client = new module.Client(settings.browser.actionTimeoutMs);
+  try {
+    await client.access({
+      host: remote.host,
+      port: remote.port,
+      user: credentials.user,
+      password: credentials.password,
+      secure: remote.protocol === "ftps",
+    });
+    return await operation(client, remote);
+  } finally { client.close(); }
+}
+
+async function assertRemoteFile(step, profile, settings) {
+  return withRemote(step.server, profile, settings, async (client, remote) => {
+    const remotePath = resolveRemotePath(remote, step.path);
+    let size;
+    try {
+      if (remote.protocol === "sftp") {
+        const exists = await client.exists(remotePath);
+        if (exists === false) {
+          if (step.exists) throw new JevBrowserError("assert_remote_file expected the remote file to exist");
+          return { action: step.action, asserted: true, exists: false };
+        }
+        const info = await client.stat(remotePath);
+        if (!info.isFile) throw new JevBrowserError("assert_remote_file target is not a regular file");
+        size = info.size;
+        if (step.sha256) {
+          if (size > settings.browser.maxDownloadFileBytes) throw new JevBrowserError("remote file exceeds the configured verification size limit");
+          const bytes = await client.get(remotePath);
+          const actual = createHash("sha256").update(bytes).digest("hex");
+          if (actual !== step.sha256) throw new JevBrowserError("assert_remote_file SHA-256 did not match");
+        }
+      } else {
+        const parent = path.posix.dirname(remotePath);
+        const name = path.posix.basename(remotePath);
+        const entry = (await client.list(parent)).find((candidate) => candidate.name === name);
+        if (!entry || entry.type !== 1) {
+          if (step.exists) throw new JevBrowserError("assert_remote_file expected the remote file to exist");
+          return { action: step.action, asserted: true, exists: false };
+        }
+        size = entry.size;
+        if (step.sha256) {
+          if (size > settings.browser.maxDownloadFileBytes) throw new JevBrowserError("remote file exceeds the configured verification size limit");
+          const chunks = [];
+          const output = new PassThrough();
+          output.on("data", (chunk) => chunks.push(chunk));
+          await client.downloadTo(output, remotePath);
+          const actual = createHash("sha256").update(Buffer.concat(chunks)).digest("hex");
+          if (actual !== step.sha256) throw new JevBrowserError("assert_remote_file SHA-256 did not match");
+        }
+      }
+      if (step.sizeBytes !== undefined && size !== step.sizeBytes) throw new JevBrowserError("assert_remote_file size did not match");
+      return { action: step.action, asserted: true, exists: true, size_bytes: size, ...(step.sha256 ? { sha256_matched: true } : {}) };
+    } catch (error) {
+      if (error instanceof JevBrowserError) throw error;
+      throw new JevBrowserError(`assert_remote_file failed for ${step.server} (${error?.code || "remote file error"})`);
+    }
+  });
+}
+
+async function deleteRemoteFile(step, profile, settings, allowMutations) {
+  if (profile.environment !== "dev") throw new JevBrowserError("delete_remote_file is restricted to DEV profiles");
+  if (!allowMutations) throw new JevBrowserError("delete_remote_file requires explicit allow_mutations authorization");
+  return withRemote(step.server, profile, settings, async (client, remote) => {
+    const remotePath = resolveRemotePath(remote, step.path);
+    try {
+      if (remote.protocol === "sftp") await client.delete(remotePath);
+      else await client.remove(remotePath);
+      return { action: step.action, deleted: true, server: step.server };
+    } catch (error) {
+      throw new JevBrowserError(`delete_remote_file failed for ${step.server} (${error?.code || "remote delete error"})`);
+    }
+  });
+}
+
+function safeHookArguments(hook, provided) {
+  if (!isRecord(provided)) throw new JevBrowserError("run_hook args must be an object");
+  const unknown = Object.keys(provided).filter((key) => !Object.hasOwn(hook.arguments, key));
+  const missing = Object.entries(hook.arguments).filter(([key, descriptor]) => descriptor.required && !Object.hasOwn(provided, key)).map(([key]) => key);
+  if (unknown.length || missing.length) throw new JevBrowserError(`run_hook arguments invalid${unknown.length ? `; unsupported: ${unknown.join(", ")}` : ""}${missing.length ? `; missing: ${missing.join(", ")}` : ""}`);
+  const args = [];
+  for (const [key, value] of Object.entries(provided)) {
+    const schema = hook.arguments[key];
+    if (schema.type === "string") {
+      if (typeof value !== "string" || value.length > schema.maxLength || /[\0\r\n]/.test(value)) throw new JevBrowserError(`run_hook argument ${key} must be a string within its configured limit`);
+      args.push(`--${key}`, value);
+    } else if (schema.type === "integer") {
+      if (!Number.isSafeInteger(value)) throw new JevBrowserError(`run_hook argument ${key} must be an integer`);
+      args.push(`--${key}`, String(value));
+    } else {
+      if (typeof value !== "boolean") throw new JevBrowserError(`run_hook argument ${key} must be a boolean`);
+      args.push(`--${key}`, String(value));
+    }
+  }
+  return args;
+}
+
+async function runAllowlistedHook(step, settings, profile, allowMutations) {
+  if (profile.environment !== "dev") throw new JevBrowserError("run_hook is restricted to DEV profiles");
+  if (!allowMutations) throw new JevBrowserError("run_hook requires explicit allow_mutations authorization");
+  const hook = profile.hooks[step.hook];
+  if (!hook) throw new JevBrowserError(`hook ${step.hook} is not allow-listed in environment profile ${profile.id}`);
+  const target = await realpath(hook.script).catch(() => { throw new JevBrowserError(`allow-listed hook ${step.hook} is unavailable`); });
+  const info = await lstat(hook.script);
+  if (info.isSymbolicLink() || !info.isFile() || target !== path.resolve(hook.script)) throw new JevBrowserError(`allow-listed hook ${step.hook} must be a regular non-symlink file`);
+  const args = safeHookArguments(hook, step.args);
+  const timeoutMs = Math.min(step.timeoutMs, hook.timeoutMs);
+  const outcome = await new Promise((resolve) => {
+    const child = spawn(process.execPath, [target, ...args], {
+      cwd: settings.browser.projectRoot,
+      shell: false,
+      windowsHide: true,
+      stdio: ["ignore", "pipe", "pipe"],
+      env: {
+        PATH: process.env.PATH || "",
+        ...(process.env.SystemRoot ? { SystemRoot: process.env.SystemRoot } : {}),
+      },
+    });
+    let outputBytes = 0;
+    let timedOut = false;
+    child.stdout.on("data", (chunk) => { outputBytes += chunk.length; });
+    child.stderr.on("data", (chunk) => { outputBytes += chunk.length; });
+    const timer = setTimeout(() => { timedOut = true; child.kill(); }, timeoutMs);
+    child.once("error", () => { clearTimeout(timer); resolve({ code: null, timedOut, outputBytes }); });
+    child.once("close", (code) => { clearTimeout(timer); resolve({ code, timedOut, outputBytes }); });
+  });
+  if (outcome.timedOut) throw new JevBrowserError(`allow-listed hook ${step.hook} exceeded its timeout`);
+  const passed = outcome.code === step.expectedExitCode;
+  if (!passed) throw new JevBrowserError(`allow-listed hook ${step.hook} exited with code ${outcome.code ?? "unknown"}; expected ${step.expectedExitCode}`);
+  return { action: step.action, asserted: true, hook: step.hook, exit_code: outcome.code, output_bytes: Math.min(outcome.outputBytes, settings.browser.maxHookOutputBytes) };
+}
+
+export function createIntegrationSession(settings, profileId) {
+  const profile = profileId ? requireEnvironmentProfile(settings, profileId, "integrated test actions") : undefined;
+  const session = {
+    settings,
+    profile,
+    mailbox: [],
+    smtpServer: undefined,
+    smtpAddress: undefined,
+    mailParser: undefined,
+    logFlowOffsets: {},
+    logStepOffsets: new Map(),
+    async markFlowStart() {
+      if (!profile) return;
+      for (const [name, filePath] of Object.entries(profile.logSources)) {
+        this.logFlowOffsets[name] = await stat(filePath).then(({ size }) => size).catch(() => 0);
+      }
+    },
+    async markStep(stepIndex) {
+      if (!profile) return;
+      const offsets = {};
+      for (const [name, filePath] of Object.entries(profile.logSources)) offsets[name] = await stat(filePath).then(({ size }) => size).catch(() => 0);
+      this.logStepOffsets.set(stepIndex, offsets);
+    },
+    async close() {
+      if (this.smtpServer) await new Promise((resolve) => this.smtpServer.close(() => resolve())).catch(() => {});
+      this.smtpServer = undefined;
+      this.mailbox.length = 0;
+    },
+  };
+  return session;
+}
+
+export async function executeIntegrationStep(step, context) {
+  const { settings, profile, session, variables, page, execution, secrets, adapters } = context;
+  if (step.action === "generate_fixture") {
+    const filename = safeFilename(step.fileName, settings.browser.maxUploadPathChars);
+    let buffer;
+    if (step.kind === "text") buffer = Buffer.from(step.content ?? "Jev Browser test fixture\n", "utf8");
+    else if (step.kind === "pdf") buffer = makePdf(step.content ?? "Jev Browser test fixture");
+    else buffer = deterministicBytes(step.sizeBytes);
+    if (buffer.length > settings.browser.maxUploadFileBytes) throw new JevBrowserError("generate_fixture exceeds the configured per-file upload limit; Jev also imposes a 47 MiB provider limit");
+    const { prepareUploadStagingDirectory } = await import("./upload-staging.mjs");
+    const directory = await prepareUploadStagingDirectory(settings);
+    if (!directory) throw new JevBrowserError("project-local fixture staging is unavailable");
+    const filePath = path.join(directory, filename);
+    const { writeFile } = await import("node:fs/promises");
+    await writeFile(filePath, buffer, { flag: "wx", mode: 0o600 });
+    variables[step.as] = filePath;
+    return {
+      action: step.action,
+      fixture: step.as,
+      file_name: filename,
+      size_bytes: buffer.length,
+      sha256: createHash("sha256").update(buffer).digest("hex"),
+      mime_type: mimeType(filename),
+    };
+  }
+  if (step.action === "assert_download") {
+    const source = await verifyManagedFile(step.filePath, settings);
+    const downloaded = execution.downloadLedger.files.at(-1);
+    if (!downloaded) throw new JevBrowserError("assert_download needs a completed download earlier in the same flow");
+    const downloadedHandle = await open(downloaded.path, "r");
+    let bytes;
+    try { bytes = await downloadedHandle.readFile(); }
+    finally { await downloadedHandle.close(); }
+    const sourceHash = createHash("sha256").update(source.buffer).digest("hex");
+    const downloadedHash = createHash("sha256").update(bytes).digest("hex");
+    const sourceMime = mimeType(path.basename(source.path));
+    const downloadMime = downloaded.mimeType || mimeType(downloaded.name);
+    const matches = source.info.size === downloaded.sizeBytes && sourceHash === downloadedHash && sourceMime === downloadMime
+      && (!step.mimeType || step.mimeType === downloadMime);
+    if (!matches) throw new JevBrowserError("assert_download file integrity, size, or MIME type did not match the fixture");
+    return { action: step.action, asserted: true, sha256: downloadedHash, size_bytes: bytes.length, mime_type: downloadMime };
+  }
+  if (step.action === "http_request") {
+    const pageUrl = new URL(page.url());
+    const target = new URL(step.url, pageUrl);
+    const timeoutMs = step.timeoutMs ?? settings.browser.actionTimeoutMs;
+    if (target.origin !== pageUrl.origin) throw new JevBrowserError("http_request must stay on the current application origin");
+    if (profile ? !isProfileOriginAllowed(profile, target.toString()) : (!execution.localOnly || !/^https?:\/\/(?:localhost|127\.0\.0\.1|\[::1\])(?::\d+)?(?:\/|$)/i.test(target.toString()))) {
+      throw new JevBrowserError("http_request origin is not allowed by local_only or the selected environment profile");
+    }
+    if (step.method !== "GET" && (!execution.allowMutations || !profile || profile.environment === "prd")) {
+      throw new JevBrowserError("mutating http_request requires allow_mutations and an explicit DEV or HML profile");
+    }
+    const multipart = [];
+    for (const field of step.multipart || []) {
+      if (Object.hasOwn(field, "filePath")) {
+        const file = await verifyManagedFile(field.filePath, settings);
+        multipart.push({ name: field.name, fileName: field.fileName || path.basename(file.path), mimeType: mimeType(field.fileName || file.path), base64: file.buffer.toString("base64") });
+      } else multipart.push({ name: field.name, value: String(field.value ?? "") });
+    }
+    const reply = await page.evaluate(async ({ url, method, json, multipart: fields, includeBody, maxBytes, timeoutMs: requestTimeoutMs }) => {
+      const controller = new AbortController();
+      const timeout = setTimeout(() => controller.abort(), requestTimeoutMs);
+      try {
+        const options = { method, credentials: "same-origin", redirect: "error", cache: "no-store", signal: controller.signal };
+        if (json !== undefined) {
+          options.headers = { "content-type": "application/json" };
+          options.body = JSON.stringify(json);
+        } else if (fields.length) {
+          const form = new FormData();
+          for (const field of fields) {
+            if (field.base64 !== undefined) {
+              const binary = atob(field.base64);
+              const bytes = Uint8Array.from(binary, (character) => character.charCodeAt(0));
+              form.append(field.name, new File([bytes], field.fileName, { type: field.mimeType }));
+            } else form.append(field.name, field.value);
+          }
+          options.body = form;
+        }
+        const response = await fetch(url, options);
+        const headers = {};
+        for (const name of ["cache-control", "content-length", "content-type", "date", "etag", "last-modified", "retry-after", "vary"]) {
+          const value = response.headers.get(name);
+          if (value !== null) headers[name] = value.slice(0, 256);
+        }
+        const reader = response.body?.getReader();
+        const chunks = [];
+        let size = 0;
+        let truncated = false;
+        if (reader) {
+          while (size <= maxBytes) {
+            const { done, value } = await reader.read();
+            if (done) break;
+            const chunk = value.slice(0, Math.max(0, maxBytes + 1 - size));
+            chunks.push(chunk);
+            size += chunk.length;
+            if (size > maxBytes || chunk.length < value.length) { truncated = true; await reader.cancel(); break; }
+          }
+        }
+        const bytes = new Uint8Array(Math.min(size, maxBytes));
+        let offset = 0;
+        for (const chunk of chunks) { const accepted = chunk.subarray(0, Math.max(0, bytes.length - offset)); bytes.set(accepted, offset); offset += accepted.length; }
+        const body = new TextDecoder().decode(bytes);
+        let parsed;
+        try { parsed = JSON.parse(body); } catch { parsed = body; }
+        return { status: response.status, ok: response.ok, headers, body: includeBody ? parsed : undefined, body_truncated: truncated };
+      } finally {
+        clearTimeout(timeout);
+      }
+    }, {
+      url: target.toString(), method: step.method, json: step.json, multipart,
+      includeBody: step.includeBody || Object.keys(step.extract || {}).length > 0,
+      maxBytes: settings.browser.maxNetworkErrorBodyBytes,
+      timeoutMs,
+    });
+    if (Object.keys(step.extract || {}).length && (reply.body === undefined || typeof reply.body === "string" || reply.body_truncated)) {
+      throw new JevBrowserError("http_request extract requires a complete JSON response body");
+    }
+    for (const [as, extraction] of Object.entries(step.extract || {})) {
+      const value = jsonPathValue(reply.body, extraction.jsonPath);
+      if (value === undefined || isRecord(value) || Array.isArray(value)) throw new JevBrowserError(`http_request extract ${as} did not resolve to a scalar JSON value`);
+      variables[as] = String(value);
+      if (SENSITIVE_KEY.test(extraction.jsonPath.split(".").at(-1)) && String(value) && !secrets.includes(String(value))) secrets.push(String(value));
+    }
+    if (step.expectedStatus !== undefined && reply.status !== step.expectedStatus) throw new JevBrowserError(`http_request expected status ${step.expectedStatus}, received ${reply.status}`);
+    const safeBody = step.includeBody ? redactValue(reply.body) : undefined;
+    return {
+      action: step.action,
+      method: step.method,
+      url: target.origin + target.pathname,
+      status: reply.status,
+      ok: reply.ok,
+      response_headers: reply.headers,
+      ...(step.includeBody ? { response_body: safeBody, body_truncated: reply.body_truncated } : {}),
+      ...(Object.keys(step.extract || {}).length ? { extracted_fields: Object.keys(step.extract) } : {}),
+    };
+  }
+  if (step.action === "assert_db") return assertDatabase(step, settings, profile, variables, secrets, adapters);
+  if (step.action === "assert_log") {
+    const { text, truncated } = await readLogSince(session, step.source, step.since, settings.browser.maxNetworkErrorBodyBytes);
+    const passed = text.includes(step.contains) && (!step.notContains || !text.includes(step.notContains));
+    if (!passed) throw new JevBrowserError(`assert_log did not find the expected log condition in source ${step.source}${truncated ? " (bounded tail scanned)" : ""}`);
+    return { action: step.action, asserted: true, source: step.source, since: step.since, scanned_bytes: Buffer.byteLength(text), truncated };
+  }
+  if (step.action === "start_email_capture") {
+    const address = await startMailbox(session, settings);
+    return { action: step.action, host: address.host, port: address.port, mailbox: "in-memory; cleared when the flow ends" };
+  }
+  if (step.action === "assert_email") return assertEmail(step, session, settings);
+  if (step.action === "assert_remote_file") return assertRemoteFile(step, profile, settings);
+  if (step.action === "delete_remote_file") return deleteRemoteFile(step, profile, settings, execution.allowMutations);
+  if (step.action === "run_hook") return runAllowlistedHook(step, settings, profile, execution.allowMutations);
+  throw new JevBrowserError(`unsupported integrated test action ${step.action}`);
+}