@diegosouzacdv/jev-browser-mcp 0.7.1 → 0.7.2

package/mcp_servers/jev-browser-npm/src/config.mjs

@@ -1,7 +1,8 @@
 import { readFileSync } from "node:fs";
-import { homedir } from "node:os";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
+import { homedir } from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { loadEnvironmentProfiles } from "./environment-profiles.mjs";
 
 const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../..");
 const CONFIG_PATH = path.join(PACKAGE_ROOT, "config", "ui-testing.json");
@@ -12,9 +13,10 @@ const CONFIG_KEYS = {
     "harness_browser",
     "computer_browser",
     "playwright_mcp_package",
-    "computer_user_data_dir",
-    "max_flow_steps",
-    "max_text_entry_chars",
+    "computer_user_data_dir",
+    "max_flow_steps",
+    "max_flow_steps_env",
+    "max_text_entry_chars",
   ],
   nodeBrowser: [
     "max_action_timeout_seconds",
@@ -42,15 +44,35 @@ const CONFIG_KEYS = {
     "record_video_width",
     "record_video_height",
     "max_upload_files",
-    "max_upload_path_chars",
-    "max_upload_file_bytes",
-    "max_upload_total_bytes",
+    "max_upload_path_chars",
+    "max_upload_file_bytes",
+    "max_upload_file_bytes_env",
+    "max_upload_total_bytes",
+    "max_upload_total_bytes_env",
+    "max_background_flow_runs",
+    "background_flow_result_ttl_seconds",
     "max_download_files",
     "max_download_file_bytes",
     "max_download_total_bytes",
-    "max_download_timeout_seconds",
-    "upload_root_env",
-    "artifact_directory",
+    "max_download_timeout_seconds",
+    "max_environment_profile_file_bytes",
+    "max_test_suite_file_bytes",
+    "max_test_suite_criteria",
+    "max_test_suite_report_bytes",
+    "max_database_query_chars",
+    "max_database_bind_values",
+    "max_external_extract_variables",
+    "max_hook_output_bytes",
+    "max_database_timeout_ms",
+    "max_database_rows",
+    "max_hook_timeout_ms",
+    "max_hook_argument_chars",
+    "max_smtp_captured_messages",
+    "upload_root_env",
+    "project_root_env",
+    "profiles_file_env",
+    "upload_staging_directory",
+    "artifact_directory",
     "artifact_directory_env",
     "max_frame_snapshots",
     "fast_path_single_plan_default",
@@ -110,13 +132,21 @@ function requireKeys(value, keys, scope) {
   }
 }
 
-function positiveNumber(value, name, integer = false) {
+function positiveNumber(value, name, integer = false) {
   const parsed = Number(value);
   if (!Number.isFinite(parsed) || parsed <= 0 || (integer && !Number.isInteger(parsed))) {
     throw new JevBrowserError(`config/ui-testing.json ${name} must be a positive ${integer ? "integer" : "number"}`);
   }
-  return parsed;
-}
+  return parsed;
+}
+
+function configurableLimit(configValue, env, envName, configPath) {
+  const variable = environmentName(envName, `${configPath}_env`);
+  const value = env[variable]?.trim();
+  if (value === undefined || value === "") return positiveNumber(configValue, configPath, true);
+  if (!/^\d+$/.test(value)) throw new JevBrowserError(`${variable} must be a positive integer`);
+  return positiveNumber(value, variable, true);
+}
 
 function expandHomeDirectory(value) {
   if (value.startsWith("~/") || value.startsWith("~\\")) return path.join(homedir(), value.slice(2));
@@ -131,12 +161,25 @@ function requireOutsidePackage(resolved, name) {
   return resolved;
 }
 
-function configuredDirectory(value, name) {
-  if (typeof value !== "string" || !value.trim()) throw new JevBrowserError(`config/ui-testing.json ${name} must be a directory path`);
-  const expanded = expandHomeDirectory(value.trim());
-  if (!path.isAbsolute(expanded)) throw new JevBrowserError(`config/ui-testing.json ${name} must be absolute or start with ~`);
-  return path.resolve(expanded);
-}
+function configuredDirectory(value, name) {
+  if (typeof value !== "string" || !value.trim()) throw new JevBrowserError(`config/ui-testing.json ${name} must be a directory path`);
+  const expanded = expandHomeDirectory(value.trim());
+  if (!path.isAbsolute(expanded)) throw new JevBrowserError(`config/ui-testing.json ${name} must be absolute or start with ~`);
+  return path.resolve(expanded);
+}
+
+function projectRelativeDirectory(projectRoot, value, name) {
+  if (typeof value !== "string" || !value.trim() || path.isAbsolute(value.trim())
+    || path.win32.isAbsolute(value.trim()) || value.trim().split(/[\\/]+/).includes("..")) {
+    throw new JevBrowserError(`config/ui-testing.json ${name} must be a relative directory inside the project`);
+  }
+  const resolved = path.resolve(projectRoot, value.trim());
+  const relative = path.relative(projectRoot, resolved);
+  if (!relative || relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+    throw new JevBrowserError(`config/ui-testing.json ${name} must stay inside the project directory`);
+  }
+  return resolved;
+}
 
 function environmentName(value, name) {
   if (typeof value !== "string" || !/^[A-Z][A-Z0-9_]*$/.test(value)) {
@@ -249,10 +292,38 @@ export function loadSettings({ env = process.env, configPath = CONFIG_PATH } = {
   ), "browser artifact directory");
   const uploadRootEnv = environmentName(browserOptions.upload_root_env, "jev_browser_mcp.browser.upload_root_env");
   const configuredUploadRoot = env[uploadRootEnv]?.trim();
-  const uploadRoot = configuredUploadRoot
-    ? configuredDirectory(configuredUploadRoot, `environment ${uploadRootEnv}`)
-    : null;
-  const snapshotScope = browserOptions.snapshot_scope_default;
+  const uploadRoot = configuredUploadRoot
+    ? configuredDirectory(configuredUploadRoot, `environment ${uploadRootEnv}`)
+    : null;
+  const projectRootEnv = environmentName(browserOptions.project_root_env, "jev_browser_mcp.browser.project_root_env");
+  const projectRoot = configuredDirectory(env[projectRootEnv]?.trim() || process.cwd(), `environment ${projectRootEnv}`);
+  const profilesFileEnv = environmentName(browserOptions.profiles_file_env, "jev_browser_mcp.browser.profiles_file_env");
+  const configuredProfilesFile = env[profilesFileEnv]?.trim() || path.join(projectRoot, ".jev-browser", "profiles.json");
+  const profilesFile = configuredDirectory(configuredProfilesFile, `environment ${profilesFileEnv}`);
+  let environmentProfiles;
+  try {
+    environmentProfiles = loadEnvironmentProfiles({
+      projectRoot,
+      filePath: profilesFile,
+      limits: {
+        maxFileBytes: positiveNumber(browserOptions.max_environment_profile_file_bytes, "jev_browser_mcp.browser.max_environment_profile_file_bytes", true),
+        maxDatabaseTimeoutMs: positiveNumber(browserOptions.max_database_timeout_ms, "jev_browser_mcp.browser.max_database_timeout_ms", true),
+        maxDatabaseRows: positiveNumber(browserOptions.max_database_rows, "jev_browser_mcp.browser.max_database_rows", true),
+        maxHookTimeoutMs: positiveNumber(browserOptions.max_hook_timeout_ms, "jev_browser_mcp.browser.max_hook_timeout_ms", true),
+        maxHookArgumentChars: positiveNumber(browserOptions.max_hook_argument_chars, "jev_browser_mcp.browser.max_hook_argument_chars", true),
+        maxSmtpCapturedMessages: positiveNumber(browserOptions.max_smtp_captured_messages, "jev_browser_mcp.browser.max_smtp_captured_messages", true),
+      },
+    });
+  } catch (error) {
+    throw new JevBrowserError(error?.message || "Jev Browser environment profile file is invalid");
+  }
+  const uploadStagingBaseDirectory = projectRelativeDirectory(
+    projectRoot,
+    browserOptions.upload_staging_directory,
+    "jev_browser_mcp.browser.upload_staging_directory",
+  );
+  const uploadStagingDirectory = path.join(uploadStagingBaseDirectory, `mcp-${process.pid}-${sessionId}`);
+  const snapshotScope = browserOptions.snapshot_scope_default;
   if (!new Set(["body", "main", "dialog"]).has(snapshotScope)) {
     throw new JevBrowserError("config/ui-testing.json jev_browser_mcp.browser.snapshot_scope_default must be body, main, or dialog");
   }
@@ -301,18 +372,25 @@ export function loadSettings({ env = process.env, configPath = CONFIG_PATH } = {
     browserOptions.post_step_ready_timeout_seconds_default,
     "jev_browser_mcp.browser.post_step_ready_timeout_seconds_default",
   );
-  if (postStepReadyTimeoutSeconds > maxReadyTimeoutSeconds) {
-    throw new JevBrowserError("config/ui-testing.json post-step readiness timeout exceeds its configured maximum");
-  }
-
-  return Object.freeze({
+  if (postStepReadyTimeoutSeconds > maxReadyTimeoutSeconds) {
+    throw new JevBrowserError("config/ui-testing.json post-step readiness timeout exceeds its configured maximum");
+  }
+  const maxFlowSteps = configurableLimit(document.browser.max_flow_steps, env, document.browser.max_flow_steps_env, "browser.max_flow_steps");
+  const maxUploadFileBytes = configurableLimit(browserOptions.max_upload_file_bytes, env, browserOptions.max_upload_file_bytes_env, "jev_browser_mcp.browser.max_upload_file_bytes");
+  const maxUploadTotalBytes = configurableLimit(browserOptions.max_upload_total_bytes, env, browserOptions.max_upload_total_bytes_env, "jev_browser_mcp.browser.max_upload_total_bytes");
+  if (maxUploadTotalBytes < maxUploadFileBytes) {
+    throw new JevBrowserError("JEV_BROWSER_MAX_UPLOAD_TOTAL_BYTES must be at least the per-file upload limit");
+  }
+
+  return Object.freeze({
     env,
     browser: Object.freeze({
       mode,
       channel,
       profileDir: profileDirectory(profileTemplate, channel, sessionId, env.JEV_BROWSER_PROFILE),
       sessionId,
-      maxFlowSteps: positiveNumber(document.browser.max_flow_steps, "browser.max_flow_steps", true),
+      maxFlowSteps,
+      maxFlowStepsEnv: environmentName(document.browser.max_flow_steps_env, "browser.max_flow_steps_env"),
       maxTextEntryChars: positiveNumber(document.browser.max_text_entry_chars, "browser.max_text_entry_chars", true),
       actionTimeoutMs: positiveNumber(browserOptions.max_action_timeout_seconds, "jev_browser_mcp.browser.max_action_timeout_seconds") * 1000,
       mutationConfirmationTtlMs: positiveNumber(browserOptions.mutation_confirmation_ttl_seconds, "jev_browser_mcp.browser.mutation_confirmation_ttl_seconds") * 1000,
@@ -322,7 +400,20 @@ export function loadSettings({ env = process.env, configPath = CONFIG_PATH } = {
       maxStepTimeoutSeconds: positiveNumber(browserOptions.max_step_timeout_seconds, "jev_browser_mcp.browser.max_step_timeout_seconds"),
       keyDelayMs: positiveNumber(browserOptions.key_delay_ms_default, "jev_browser_mcp.browser.key_delay_ms_default", true),
       visibilityPollMs: positiveNumber(browserOptions.visibility_poll_interval_ms_default, "jev_browser_mcp.browser.visibility_poll_interval_ms_default", true),
-      maxNetworkErrorBodyBytes: positiveNumber(browserOptions.max_network_error_body_bytes, "jev_browser_mcp.browser.max_network_error_body_bytes", true),
+      maxNetworkErrorBodyBytes: positiveNumber(browserOptions.max_network_error_body_bytes, "jev_browser_mcp.browser.max_network_error_body_bytes", true),
+      maxEnvironmentProfileFileBytes: positiveNumber(browserOptions.max_environment_profile_file_bytes, "jev_browser_mcp.browser.max_environment_profile_file_bytes", true),
+      maxTestSuiteFileBytes: positiveNumber(browserOptions.max_test_suite_file_bytes, "jev_browser_mcp.browser.max_test_suite_file_bytes", true),
+      maxTestSuiteCriteria: positiveNumber(browserOptions.max_test_suite_criteria, "jev_browser_mcp.browser.max_test_suite_criteria", true),
+      maxTestSuiteReportBytes: positiveNumber(browserOptions.max_test_suite_report_bytes, "jev_browser_mcp.browser.max_test_suite_report_bytes", true),
+      maxDatabaseQueryChars: positiveNumber(browserOptions.max_database_query_chars, "jev_browser_mcp.browser.max_database_query_chars", true),
+      maxDatabaseBindValues: positiveNumber(browserOptions.max_database_bind_values, "jev_browser_mcp.browser.max_database_bind_values", true),
+      maxExternalExtractVariables: positiveNumber(browserOptions.max_external_extract_variables, "jev_browser_mcp.browser.max_external_extract_variables", true),
+      maxHookOutputBytes: positiveNumber(browserOptions.max_hook_output_bytes, "jev_browser_mcp.browser.max_hook_output_bytes", true),
+      maxDatabaseTimeoutMs: positiveNumber(browserOptions.max_database_timeout_ms, "jev_browser_mcp.browser.max_database_timeout_ms", true),
+      maxDatabaseRows: positiveNumber(browserOptions.max_database_rows, "jev_browser_mcp.browser.max_database_rows", true),
+      maxHookTimeoutMs: positiveNumber(browserOptions.max_hook_timeout_ms, "jev_browser_mcp.browser.max_hook_timeout_ms", true),
+      maxHookArgumentChars: positiveNumber(browserOptions.max_hook_argument_chars, "jev_browser_mcp.browser.max_hook_argument_chars", true),
+      maxSmtpCapturedMessages: positiveNumber(browserOptions.max_smtp_captured_messages, "jev_browser_mcp.browser.max_smtp_captured_messages", true),
       maxNetworkErrorMessageChars: positiveNumber(browserOptions.max_network_error_message_chars, "jev_browser_mcp.browser.max_network_error_message_chars", true),
       maxNetworkHistoryEvents: positiveNumber(browserOptions.max_network_history_events, "jev_browser_mcp.browser.max_network_history_events", true),
       maxToolResponseBytes: positiveNumber(browserOptions.max_tool_response_bytes, "jev_browser_mcp.browser.max_tool_response_bytes", true),
@@ -335,14 +426,22 @@ export function loadSettings({ env = process.env, configPath = CONFIG_PATH } = {
       }),
       maxUploadFiles: positiveNumber(browserOptions.max_upload_files, "jev_browser_mcp.browser.max_upload_files", true),
       maxUploadPathChars: positiveNumber(browserOptions.max_upload_path_chars, "jev_browser_mcp.browser.max_upload_path_chars", true),
-      maxUploadFileBytes: positiveNumber(browserOptions.max_upload_file_bytes, "jev_browser_mcp.browser.max_upload_file_bytes", true),
-      maxUploadTotalBytes: positiveNumber(browserOptions.max_upload_total_bytes, "jev_browser_mcp.browser.max_upload_total_bytes", true),
+      maxUploadFileBytes,
+      maxUploadFileBytesEnv: environmentName(browserOptions.max_upload_file_bytes_env, "jev_browser_mcp.browser.max_upload_file_bytes_env"),
+      maxUploadTotalBytes,
+      maxUploadTotalBytesEnv: environmentName(browserOptions.max_upload_total_bytes_env, "jev_browser_mcp.browser.max_upload_total_bytes_env"),
+      maxBackgroundFlowRuns: positiveNumber(browserOptions.max_background_flow_runs, "jev_browser_mcp.browser.max_background_flow_runs", true),
+      backgroundFlowResultTtlMs: positiveNumber(browserOptions.background_flow_result_ttl_seconds, "jev_browser_mcp.browser.background_flow_result_ttl_seconds", true) * 1000,
       maxDownloadFiles: positiveNumber(browserOptions.max_download_files, "jev_browser_mcp.browser.max_download_files", true),
       maxDownloadFileBytes: positiveNumber(browserOptions.max_download_file_bytes, "jev_browser_mcp.browser.max_download_file_bytes", true),
       maxDownloadTotalBytes: positiveNumber(browserOptions.max_download_total_bytes, "jev_browser_mcp.browser.max_download_total_bytes", true),
-      downloadTimeoutMs: positiveNumber(browserOptions.max_download_timeout_seconds, "jev_browser_mcp.browser.max_download_timeout_seconds") * 1000,
-      uploadRoot,
-      artifactDirectory,
+      downloadTimeoutMs: positiveNumber(browserOptions.max_download_timeout_seconds, "jev_browser_mcp.browser.max_download_timeout_seconds") * 1000,
+      uploadRoot,
+      projectRoot,
+      environmentProfiles,
+      uploadStagingDirectory,
+      managedUploadStaging: true,
+      artifactDirectory,
       maxFrameSnapshots: positiveNumber(browserOptions.max_frame_snapshots, "jev_browser_mcp.browser.max_frame_snapshots", true),
       defaults: Object.freeze({
         fastPath: booleanValue(browserOptions.fast_path_single_plan_default, "jev_browser_mcp.browser.fast_path_single_plan_default"),

package/mcp_servers/jev-browser-npm/src/environment-profiles.mjs

@@ -0,0 +1,241 @@
+import { lstatSync, readFileSync, realpathSync, statSync } from "node:fs";
+import path from "node:path";
+
+const PROFILE_NAME = /^[A-Za-z][A-Za-z0-9_-]{0,47}$/;
+const ENV_NAME = /^[A-Z][A-Z0-9_]*$/;
+const HOOK_ARG_NAME = /^[A-Za-z][A-Za-z0-9_]{0,31}$/;
+
+function object(value, name) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${name} must be an object`);
+  return value;
+}
+
+function keys(value, required, optional, name) {
+  object(value, name);
+  const allowed = new Set([...required, ...optional]);
+  const missing = required.filter((key) => !Object.hasOwn(value, key));
+  const extra = Object.keys(value).filter((key) => !allowed.has(key));
+  if (missing.length || extra.length) {
+    throw new Error(`${name} has invalid fields${missing.length ? `; missing: ${missing.join(", ")}` : ""}${extra.length ? `; unsupported: ${extra.join(", ")}` : ""}`);
+  }
+}
+
+function envRef(value, name) {
+  if (typeof value !== "string" || !ENV_NAME.test(value)) throw new Error(`${name} must name an environment variable`);
+  return value;
+}
+
+function string(value, name, max = 512) {
+  if (typeof value !== "string" || !value.trim() || value.length > max || value.includes("\0")) throw new Error(`${name} must be a non-empty string of at most ${max} characters`);
+  return value.trim();
+}
+
+function positiveInteger(value, name, max) {
+  if (!Number.isSafeInteger(value) || value <= 0 || value > max) throw new Error(`${name} must be a positive integer no greater than ${max}`);
+  return value;
+}
+
+function projectPath(projectRoot, value, name, { absolute = false } = {}) {
+  const raw = string(value, name, 2048);
+  if (absolute && !path.isAbsolute(raw)) throw new Error(`${name} must be absolute`);
+  if (!absolute && (path.isAbsolute(raw) || path.win32.isAbsolute(raw) || raw.split(/[\\/]+/).includes(".."))) {
+    throw new Error(`${name} must be a safe relative path inside the project`);
+  }
+  const resolved = path.resolve(projectRoot, raw);
+  const relative = path.relative(projectRoot, resolved);
+  if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) throw new Error(`${name} must stay inside the project`);
+  return resolved;
+}
+
+function normalizeOrigins(value, name) {
+  if (!Array.isArray(value) || value.length > 32) throw new Error(`${name} must be an array with at most 32 origins`);
+  const origins = value.map((candidate) => {
+    let parsed;
+    try { parsed = new URL(string(candidate, name, 512)); } catch { throw new Error(`${name} contains an invalid origin`); }
+    if (!new Set(["http:", "https:"]).has(parsed.protocol) || parsed.username || parsed.password || parsed.pathname !== "/" || parsed.search || parsed.hash) {
+      throw new Error(`${name} entries must be bare http or https origins`);
+    }
+    return parsed.origin;
+  });
+  if (new Set(origins).size !== origins.length) throw new Error(`${name} must not repeat origins`);
+  return Object.freeze(origins);
+}
+
+function validateDatabase(value, name, limits) {
+  if (value === undefined) return undefined;
+  object(value, name);
+  if (value.engine === "postgresql") {
+    keys(value, ["engine", "connection_env", "timeout_ms", "max_rows"], [], name);
+    return Object.freeze({
+      engine: value.engine,
+      connectionEnv: envRef(value.connection_env, `${name}.connection_env`),
+      timeoutMs: positiveInteger(value.timeout_ms, `${name}.timeout_ms`, limits.maxDatabaseTimeoutMs),
+      maxRows: positiveInteger(value.max_rows, `${name}.max_rows`, limits.maxDatabaseRows),
+    });
+  }
+  if (value.engine === "oracle") {
+    keys(value, ["engine", "connect_env", "user_env", "password_env", "timeout_ms", "max_rows"], [], name);
+    return Object.freeze({
+      engine: value.engine,
+      connectEnv: envRef(value.connect_env, `${name}.connect_env`),
+      userEnv: envRef(value.user_env, `${name}.user_env`),
+      passwordEnv: envRef(value.password_env, `${name}.password_env`),
+      timeoutMs: positiveInteger(value.timeout_ms, `${name}.timeout_ms`, limits.maxDatabaseTimeoutMs),
+      maxRows: positiveInteger(value.max_rows, `${name}.max_rows`, limits.maxDatabaseRows),
+    });
+  }
+  throw new Error(`${name}.engine must be postgresql or oracle`);
+}
+
+function validateRemote(value, name) {
+  keys(value, ["protocol", "host", "username_env", "password_env", "root", "port"], ["host_fingerprint_env"], name);
+  const protocol = value.protocol;
+  if (!new Set(["ftp", "ftps", "sftp"]).has(protocol)) throw new Error(`${name}.protocol must be ftp, ftps, or sftp`);
+  const host = string(value.host, `${name}.host`, 253);
+  if (/[\s/@?#]/.test(host)) throw new Error(`${name}.host must be a hostname or IP address`);
+  const root = string(value.root, `${name}.root`, 1024);
+  if (/[\u0000-\u001f\u007f]/u.test(root) || !root.startsWith("/") || root.split("/").includes("..")) {
+    throw new Error(`${name}.root must be an absolute remote directory without traversal or control characters`);
+  }
+  const port = value.port;
+  positiveInteger(port, `${name}.port`, 65535);
+  const hostFingerprintEnv = value.host_fingerprint_env === undefined ? undefined : envRef(value.host_fingerprint_env, `${name}.host_fingerprint_env`);
+  if (protocol === "sftp" && !hostFingerprintEnv) throw new Error(`${name}.host_fingerprint_env is required for SFTP host verification`);
+  if (protocol !== "sftp" && hostFingerprintEnv) throw new Error(`${name}.host_fingerprint_env is only valid for SFTP`);
+  return Object.freeze({
+    protocol, host, port, root,
+    usernameEnv: envRef(value.username_env, `${name}.username_env`),
+    passwordEnv: envRef(value.password_env, `${name}.password_env`),
+    hostFingerprintEnv,
+  });
+}
+
+function validateHook(value, name, projectRoot, limits) {
+  keys(value, ["script", "arguments", "timeout_ms"], [], name);
+  if (!value.arguments || typeof value.arguments !== "object" || Array.isArray(value.arguments)) throw new Error(`${name}.arguments must be an object schema`);
+  const argumentsSchema = {};
+  for (const [argument, descriptor] of Object.entries(value.arguments)) {
+    if (!HOOK_ARG_NAME.test(argument)) throw new Error(`${name} contains an invalid hook argument name`);
+    keys(descriptor, ["type", "required", "max_length"], [], `${name}.arguments.${argument}`);
+    if (!new Set(["string", "integer", "boolean"]).has(descriptor.type)) throw new Error(`${name}.arguments.${argument}.type must be string, integer, or boolean`);
+    if (descriptor.required !== undefined && typeof descriptor.required !== "boolean") throw new Error(`${name}.arguments.${argument}.required must be a boolean`);
+    argumentsSchema[argument] = Object.freeze({
+      type: descriptor.type,
+      required: descriptor.required,
+      maxLength: positiveInteger(descriptor.max_length, `${name}.arguments.${argument}.max_length`, limits.maxHookArgumentChars),
+    });
+  }
+  return Object.freeze({
+    script: projectPath(projectRoot, value.script, `${name}.script`),
+    arguments: Object.freeze(argumentsSchema),
+    timeoutMs: positiveInteger(value.timeout_ms, `${name}.timeout_ms`, limits.maxHookTimeoutMs),
+  });
+}
+
+function validateProfile(profileId, raw, projectRoot, limits) {
+  keys(raw, ["environment"], ["application_origins", "database", "log_sources", "smtp_capture", "remotes", "hooks"], `profiles.${profileId}`);
+  if (!new Set(["dev", "hml", "prd"]).has(raw.environment)) throw new Error(`profiles.${profileId}.environment must be dev, hml, or prd`);
+  const applicationOrigins = normalizeOrigins(raw.application_origins ?? [], `profiles.${profileId}.application_origins`);
+  const database = validateDatabase(raw.database, `profiles.${profileId}.database`, limits);
+  const logSources = {};
+  const rawLogs = raw.log_sources ?? {};
+  object(rawLogs, `profiles.${profileId}.log_sources`);
+  for (const [source, file] of Object.entries(rawLogs)) {
+    if (!PROFILE_NAME.test(source)) throw new Error(`profiles.${profileId}.log_sources contains an invalid source name`);
+    const filePath = typeof file === "string" && path.isAbsolute(file)
+      ? path.resolve(file)
+      : projectPath(projectRoot, file, `profiles.${profileId}.log_sources.${source}`);
+    logSources[source] = filePath;
+  }
+  let smtpCapture;
+  if (raw.smtp_capture !== undefined) {
+    keys(raw.smtp_capture, ["port", "bind_address", "max_messages"], [], `profiles.${profileId}.smtp_capture`);
+    const bindAddress = raw.smtp_capture.bind_address;
+    if (!new Set(["127.0.0.1", "::1"]).has(bindAddress)) throw new Error(`profiles.${profileId}.smtp_capture.bind_address must be loopback`);
+    if (!Number.isSafeInteger(raw.smtp_capture.port) || raw.smtp_capture.port < 0 || raw.smtp_capture.port > 65535) {
+      throw new Error(`profiles.${profileId}.smtp_capture.port must be 0-65535`);
+    }
+    smtpCapture = Object.freeze({
+      bindAddress,
+      port: raw.smtp_capture.port,
+      maxMessages: positiveInteger(raw.smtp_capture.max_messages, `profiles.${profileId}.smtp_capture.max_messages`, limits.maxSmtpCapturedMessages),
+    });
+  }
+  const remotes = {};
+  const rawRemotes = raw.remotes ?? {};
+  object(rawRemotes, `profiles.${profileId}.remotes`);
+  for (const [remoteId, remote] of Object.entries(rawRemotes)) {
+    if (!PROFILE_NAME.test(remoteId)) throw new Error(`profiles.${profileId}.remotes contains an invalid remote name`);
+    remotes[remoteId] = validateRemote(remote, `profiles.${profileId}.remotes.${remoteId}`);
+  }
+  if (raw.environment === "prd" && Object.keys(raw.hooks ?? {}).length) throw new Error(`profiles.${profileId} cannot define hooks for PRD`);
+  const hooks = {};
+  const rawHooks = raw.hooks ?? {};
+  object(rawHooks, `profiles.${profileId}.hooks`);
+  for (const [hookId, hook] of Object.entries(rawHooks)) {
+    if (!PROFILE_NAME.test(hookId)) throw new Error(`profiles.${profileId}.hooks contains an invalid hook name`);
+    hooks[hookId] = validateHook(hook, `profiles.${profileId}.hooks.${hookId}`, projectRoot, limits);
+  }
+  return Object.freeze({
+    id: profileId,
+    environment: raw.environment,
+    applicationOrigins,
+    database,
+    logSources: Object.freeze(logSources),
+    smtpCapture,
+    remotes: Object.freeze(remotes),
+    hooks: Object.freeze(hooks),
+  });
+}
+
+export function loadEnvironmentProfiles({ projectRoot, filePath, limits }) {
+  const resolvedRoot = realpathSync(projectRoot);
+  const resolvedFile = path.resolve(filePath);
+  const relative = path.relative(resolvedRoot, resolvedFile);
+  if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+    throw new Error("JEV_BROWSER_PROFILES_FILE must stay inside the project directory");
+  }
+  let rawText;
+  try {
+    const info = lstatSync(resolvedFile);
+    if (info.isSymbolicLink() || !info.isFile() || info.size > limits.maxFileBytes) throw new Error("profile file is not a regular file within the configured size limit");
+    const realFile = realpathSync(resolvedFile);
+    if (realFile !== resolvedFile || !statSync(realFile).isFile()) throw new Error("profile file must not use symlinks");
+    rawText = readFileSync(realFile, "utf8");
+  } catch (error) {
+    if (error?.code === "ENOENT") return Object.freeze({ filePath: resolvedFile, profiles: Object.freeze({}) });
+    throw new Error("Jev Browser environment profile file is invalid or inaccessible");
+  }
+  let document;
+  try { document = JSON.parse(rawText); } catch { throw new Error("Jev Browser environment profile file must be valid JSON"); }
+  keys(document, ["version", "profiles"], [], "environment profiles root");
+  if (document.version !== 1) throw new Error("environment profiles version must be 1");
+  object(document.profiles, "environment profiles");
+  const profiles = {};
+  for (const [profileId, profile] of Object.entries(document.profiles)) {
+    if (!PROFILE_NAME.test(profileId)) throw new Error("environment profiles contains an invalid profile name");
+    profiles[profileId] = validateProfile(profileId, profile, resolvedRoot, limits);
+  }
+  return Object.freeze({ filePath: resolvedFile, profiles: Object.freeze(profiles) });
+}
+
+export function requireEnvironmentProfile(settings, profileId, purpose) {
+  if (typeof profileId !== "string" || !profileId) throw new Error(`${purpose} requires options.environment_profile`);
+  const profile = settings.browser.environmentProfiles.profiles[profileId];
+  if (!profile) throw new Error(`environment profile ${profileId} is not configured in ${settings.browser.environmentProfiles.filePath}`);
+  return profile;
+}
+
+export function isProfileOriginAllowed(profile, value) {
+  try { return profile.applicationOrigins.includes(new URL(value).origin); } catch { return false; }
+}
+
+export function resolveRemotePath(remote, requested) {
+  const value = string(requested, "remote path", 1024).replace(/\\/g, "/");
+  if (/[\u0000-\u001f\u007f]/u.test(value)) throw new Error("remote path must not contain control characters");
+  const normalized = path.posix.normalize(path.posix.join(remote.root, value.replace(/^\/+/, "")));
+  if (normalized !== remote.root && !normalized.startsWith(`${remote.root.replace(/\/$/, "")}/`)) {
+    throw new Error("remote path must stay inside the configured remote root");
+  }
+  return normalized;
+}