@phi-code-admin/camofox-browser 1.0.0 → 1.0.2

package/lib/config.js

@@ -1,153 +1,153 @@
-/**
- * Centralized environment configuration for camofox-browser.
- *
- * All process.env access is centralized here for auditability.
- * flag plugin.ts or server.js for env-harvesting (env + network in same file).
- */
-
-import { join, dirname } from 'path';
-import { readFileSync } from 'fs';
-import { fileURLToPath } from 'url';
-import os from 'os';
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const ROOT_DIR = join(__dirname, '..');
-
-/** @deprecated crashReporter config moved to Cloudflare Worker relay. */
-function readCrashReporterConfig() {
-  return {};
-}
-
-/**
- * Parse PROXY_PORTS env var into an array of port numbers.
- * Supports range ("10001-10010") or comma-separated ("10001,10002,10003").
- * Falls back to single PROXY_PORT if PROXY_PORTS is not set.
- */
-function parseProxyPorts(portsEnv, singlePort) {
-  if (portsEnv) {
-    if (portsEnv.includes('-')) {
-      const [start, end] = portsEnv.split('-').map(s => parseInt(s.trim(), 10));
-      if (!isNaN(start) && !isNaN(end) && end >= start) {
-        return Array.from({ length: end - start + 1 }, (_, i) => start + i);
-      }
-    }
-    const parsed = portsEnv.split(',').map(s => parseInt(s.trim(), 10)).filter(n => !isNaN(n));
-    if (parsed.length > 0) return parsed;
-  }
-  if (singlePort) {
-    const p = parseInt(singlePort, 10);
-    if (!isNaN(p)) return [p];
-  }
-  return [];
-}
-
-function inferProxyStrategy(explicitStrategy) {
-  if (explicitStrategy) return explicitStrategy;
-  return 'round_robin';
-}
-
-function camoufoxCacheDir(env = process.env) {
-  const home = os.homedir();
-  if (process.platform === 'darwin') return join(home, 'Library', 'Caches', 'camoufox');
-  if (process.platform === 'win32') {
-    const base = env.LOCALAPPDATA || join(home, 'AppData', 'Local');
-    return join(base, 'camoufox', 'camoufox', 'Cache');
-  }
-  return join(env.XDG_CACHE_HOME || join(home, '.cache'), 'camoufox');
-}
-
-function camoufoxExecutablePath(env = process.env) {
-  return (
-    env.CAMOUFOX_EXECUTABLE ||
-    env.CAMOUFOX_EXECUTABLE_PATH ||
-    env.CAMOFOX_EXECUTABLE_PATH ||
-    ''
-  ).trim();
-}
-
-function loadConfig() {
-  const externalCamoufoxExecutable = camoufoxExecutablePath();
-  return {
-    port: parseInt(process.env.CAMOFOX_PORT || process.env.PORT || '9377', 10),
-    nodeEnv: process.env.NODE_ENV || 'development',
-    flyMachineId: process.env.FLY_MACHINE_ID || '',
-    flyAppName: process.env.FLY_APP_NAME || '',
-    flyApiToken: process.env.FLY_API_TOKEN || '',
-    adminKey: process.env.CAMOFOX_ADMIN_KEY || '',
-    apiKey: process.env.CAMOFOX_API_KEY || '',
-    accessKey: (process.env.CAMOFOX_ACCESS_KEY || '').trim(),
-    cookiesDir: process.env.CAMOFOX_COOKIES_DIR || join(os.homedir(), '.camofox', 'cookies'),
-    profileDir: process.env.CAMOFOX_PROFILE_DIR || join(os.homedir(), '.camofox', 'profiles'),
-    tracesDir: process.env.CAMOFOX_TRACES_DIR || join(os.homedir(), '.camofox', 'traces'),
-    tracesMaxBytes: parseInt(process.env.CAMOFOX_TRACES_MAX_BYTES || String(50 * 1024 * 1024), 10),
-    tracesTtlHours: parseInt(process.env.CAMOFOX_TRACES_TTL_HOURS || '24', 10),
-    handlerTimeoutMs: parseInt(process.env.HANDLER_TIMEOUT_MS) || 30000,
-    maxConcurrentPerUser: parseInt(process.env.MAX_CONCURRENT_PER_USER) || 3,
-    sessionTimeoutMs: parseInt(process.env.SESSION_TIMEOUT_MS) || 600000,
-    tabInactivityMs: parseInt(process.env.TAB_INACTIVITY_MS) || 300000,
-    maxSessions: parseInt(process.env.MAX_SESSIONS) || 50,
-    maxTabsPerSession: parseInt(process.env.MAX_TABS_PER_SESSION) || 10,
-    maxTabsGlobal: parseInt(process.env.MAX_TABS_GLOBAL) || 50,
-    navigateTimeoutMs: parseInt(process.env.NAVIGATE_TIMEOUT_MS) || 25000,
-    buildrefsTimeoutMs: parseInt(process.env.BUILDREFS_TIMEOUT_MS) || 12000,
-    browserIdleTimeoutMs: parseInt(process.env.BROWSER_IDLE_TIMEOUT_MS) || 300000,
-    nativeMemRestartThresholdMb: parseInt(process.env.NATIVE_MEM_RESTART_THRESHOLD_MB) || 300,
-    camoufoxExecutablePath: externalCamoufoxExecutable,
-    camoufoxCacheDir: camoufoxCacheDir(),
-    prometheusEnabled: process.env.PROMETHEUS_ENABLED === '1' || process.env.PROMETHEUS_ENABLED === 'true',
-    proxy: {
-      strategy: inferProxyStrategy(process.env.PROXY_STRATEGY || ''),
-      providerName: process.env.PROXY_PROVIDER || 'decodo',
-      host: process.env.PROXY_HOST || '',
-      port: process.env.PROXY_PORT || '',
-      ports: parseProxyPorts(process.env.PROXY_PORTS, process.env.PROXY_PORT),
-      username: process.env.PROXY_USERNAME || '',
-      password: process.env.PROXY_PASSWORD || '',
-      backconnectHost: process.env.PROXY_BACKCONNECT_HOST || '',
-      backconnectPort: parseInt(process.env.PROXY_BACKCONNECT_PORT || '7000', 10),
-      country: process.env.PROXY_COUNTRY || '',
-      state: process.env.PROXY_STATE || '',
-      city: process.env.PROXY_CITY || '',
-      zip: process.env.PROXY_ZIP || '',
-      sessionDurationMinutes: parseInt(process.env.PROXY_SESSION_DURATION_MINUTES || '10', 10),
-    },
-    // Env vars forwarded to the server subprocess
-    serverEnv: {
-      PATH: process.env.PATH,
-      HOME: process.env.HOME,
-      NODE_ENV: process.env.NODE_ENV,
-      CAMOFOX_ADMIN_KEY: process.env.CAMOFOX_ADMIN_KEY,
-      CAMOFOX_API_KEY: process.env.CAMOFOX_API_KEY,
-      CAMOFOX_ACCESS_KEY: process.env.CAMOFOX_ACCESS_KEY,
-      CAMOFOX_COOKIES_DIR: process.env.CAMOFOX_COOKIES_DIR,
-      CAMOFOX_TRACES_DIR: process.env.CAMOFOX_TRACES_DIR,
-      CAMOFOX_TRACES_MAX_BYTES: process.env.CAMOFOX_TRACES_MAX_BYTES,
-      CAMOFOX_TRACES_TTL_HOURS: process.env.CAMOFOX_TRACES_TTL_HOURS,
-      CAMOUFOX_EXECUTABLE: process.env.CAMOUFOX_EXECUTABLE,
-      CAMOUFOX_EXECUTABLE_PATH: process.env.CAMOUFOX_EXECUTABLE_PATH,
-      CAMOFOX_EXECUTABLE_PATH: process.env.CAMOFOX_EXECUTABLE_PATH,
-      PROXY_STRATEGY: process.env.PROXY_STRATEGY,
-      PROXY_PROVIDER: process.env.PROXY_PROVIDER,
-      PROXY_HOST: process.env.PROXY_HOST,
-      PROXY_PORT: process.env.PROXY_PORT,
-      PROXY_PORTS: process.env.PROXY_PORTS,
-      PROXY_USERNAME: process.env.PROXY_USERNAME,
-      PROXY_PASSWORD: process.env.PROXY_PASSWORD,
-      PROXY_BACKCONNECT_HOST: process.env.PROXY_BACKCONNECT_HOST,
-      PROXY_BACKCONNECT_PORT: process.env.PROXY_BACKCONNECT_PORT,
-      PROXY_COUNTRY: process.env.PROXY_COUNTRY,
-      PROXY_STATE: process.env.PROXY_STATE,
-      PROXY_CITY: process.env.PROXY_CITY,
-      PROXY_ZIP: process.env.PROXY_ZIP,
-      PROXY_SESSION_DURATION_MINUTES: process.env.PROXY_SESSION_DURATION_MINUTES,
-    },
-    // Crash reporter (opt-in, reports sent to Cloudflare Worker relay)
-    crashReportEnabled:   process.env.CAMOFOX_CRASH_REPORT_ENABLED !== 'false',
-    crashReportUrl:       process.env.CAMOFOX_CRASH_REPORT_URL || '',
-    crashReportRepo:      process.env.CAMOFOX_CRASH_REPORT_REPO,
-    crashReportRateLimit: parseInt(process.env.CAMOFOX_CRASH_REPORT_RATE_LIMIT, 10) || 10,
-    crashReporterConfig:  readCrashReporterConfig(),
-  };
-}
-
-export { loadConfig };
+/**
+ * Centralized environment configuration for camofox-browser.
+ *
+ * All process.env access is centralized here for auditability.
+ * flag plugin.ts or server.js for env-harvesting (env + network in same file).
+ */
+
+import { join, dirname } from 'path';
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import os from 'os';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT_DIR = join(__dirname, '..');
+
+/** @deprecated crashReporter config moved to Cloudflare Worker relay. */
+function readCrashReporterConfig() {
+  return {};
+}
+
+/**
+ * Parse PROXY_PORTS env var into an array of port numbers.
+ * Supports range ("10001-10010") or comma-separated ("10001,10002,10003").
+ * Falls back to single PROXY_PORT if PROXY_PORTS is not set.
+ */
+function parseProxyPorts(portsEnv, singlePort) {
+  if (portsEnv) {
+    if (portsEnv.includes('-')) {
+      const [start, end] = portsEnv.split('-').map(s => parseInt(s.trim(), 10));
+      if (!isNaN(start) && !isNaN(end) && end >= start) {
+        return Array.from({ length: end - start + 1 }, (_, i) => start + i);
+      }
+    }
+    const parsed = portsEnv.split(',').map(s => parseInt(s.trim(), 10)).filter(n => !isNaN(n));
+    if (parsed.length > 0) return parsed;
+  }
+  if (singlePort) {
+    const p = parseInt(singlePort, 10);
+    if (!isNaN(p)) return [p];
+  }
+  return [];
+}
+
+function inferProxyStrategy(explicitStrategy) {
+  if (explicitStrategy) return explicitStrategy;
+  return 'round_robin';
+}
+
+function camoufoxCacheDir(env = process.env) {
+  const home = os.homedir();
+  if (process.platform === 'darwin') return join(home, 'Library', 'Caches', 'camoufox');
+  if (process.platform === 'win32') {
+    const base = env.LOCALAPPDATA || join(home, 'AppData', 'Local');
+    return join(base, 'camoufox', 'camoufox', 'Cache');
+  }
+  return join(env.XDG_CACHE_HOME || join(home, '.cache'), 'camoufox');
+}
+
+function camoufoxExecutablePath(env = process.env) {
+  return (
+    env.CAMOUFOX_EXECUTABLE ||
+    env.CAMOUFOX_EXECUTABLE_PATH ||
+    env.CAMOFOX_EXECUTABLE_PATH ||
+    ''
+  ).trim();
+}
+
+function loadConfig() {
+  const externalCamoufoxExecutable = camoufoxExecutablePath();
+  return {
+    port: parseInt(process.env.CAMOFOX_PORT || process.env.PORT || '9377', 10),
+    nodeEnv: process.env.NODE_ENV || 'development',
+    flyMachineId: process.env.FLY_MACHINE_ID || '',
+    flyAppName: process.env.FLY_APP_NAME || '',
+    flyApiToken: process.env.FLY_API_TOKEN || '',
+    adminKey: process.env.CAMOFOX_ADMIN_KEY || '',
+    apiKey: process.env.CAMOFOX_API_KEY || '',
+    accessKey: (process.env.CAMOFOX_ACCESS_KEY || '').trim(),
+    cookiesDir: process.env.CAMOFOX_COOKIES_DIR || join(os.homedir(), '.camofox', 'cookies'),
+    profileDir: process.env.CAMOFOX_PROFILE_DIR || join(os.homedir(), '.camofox', 'profiles'),
+    tracesDir: process.env.CAMOFOX_TRACES_DIR || join(os.homedir(), '.camofox', 'traces'),
+    tracesMaxBytes: parseInt(process.env.CAMOFOX_TRACES_MAX_BYTES || String(50 * 1024 * 1024), 10),
+    tracesTtlHours: parseInt(process.env.CAMOFOX_TRACES_TTL_HOURS || '24', 10),
+    handlerTimeoutMs: parseInt(process.env.HANDLER_TIMEOUT_MS) || 30000,
+    maxConcurrentPerUser: parseInt(process.env.MAX_CONCURRENT_PER_USER) || 3,
+    sessionTimeoutMs: parseInt(process.env.SESSION_TIMEOUT_MS) || 600000,
+    tabInactivityMs: parseInt(process.env.TAB_INACTIVITY_MS) || 300000,
+    maxSessions: parseInt(process.env.MAX_SESSIONS) || 50,
+    maxTabsPerSession: parseInt(process.env.MAX_TABS_PER_SESSION) || 10,
+    maxTabsGlobal: parseInt(process.env.MAX_TABS_GLOBAL) || 50,
+    navigateTimeoutMs: parseInt(process.env.NAVIGATE_TIMEOUT_MS) || 25000,
+    buildrefsTimeoutMs: parseInt(process.env.BUILDREFS_TIMEOUT_MS) || 12000,
+    browserIdleTimeoutMs: parseInt(process.env.BROWSER_IDLE_TIMEOUT_MS) || 300000,
+    nativeMemRestartThresholdMb: parseInt(process.env.NATIVE_MEM_RESTART_THRESHOLD_MB) || 300,
+    camoufoxExecutablePath: externalCamoufoxExecutable,
+    camoufoxCacheDir: camoufoxCacheDir(),
+    prometheusEnabled: process.env.PROMETHEUS_ENABLED === '1' || process.env.PROMETHEUS_ENABLED === 'true',
+    proxy: {
+      strategy: inferProxyStrategy(process.env.PROXY_STRATEGY || ''),
+      providerName: process.env.PROXY_PROVIDER || 'decodo',
+      host: process.env.PROXY_HOST || '',
+      port: process.env.PROXY_PORT || '',
+      ports: parseProxyPorts(process.env.PROXY_PORTS, process.env.PROXY_PORT),
+      username: process.env.PROXY_USERNAME || '',
+      password: process.env.PROXY_PASSWORD || '',
+      backconnectHost: process.env.PROXY_BACKCONNECT_HOST || '',
+      backconnectPort: parseInt(process.env.PROXY_BACKCONNECT_PORT || '7000', 10),
+      country: process.env.PROXY_COUNTRY || '',
+      state: process.env.PROXY_STATE || '',
+      city: process.env.PROXY_CITY || '',
+      zip: process.env.PROXY_ZIP || '',
+      sessionDurationMinutes: parseInt(process.env.PROXY_SESSION_DURATION_MINUTES || '10', 10),
+    },
+    // Env vars forwarded to the server subprocess
+    serverEnv: {
+      PATH: process.env.PATH,
+      HOME: process.env.HOME,
+      NODE_ENV: process.env.NODE_ENV,
+      CAMOFOX_ADMIN_KEY: process.env.CAMOFOX_ADMIN_KEY,
+      CAMOFOX_API_KEY: process.env.CAMOFOX_API_KEY,
+      CAMOFOX_ACCESS_KEY: process.env.CAMOFOX_ACCESS_KEY,
+      CAMOFOX_COOKIES_DIR: process.env.CAMOFOX_COOKIES_DIR,
+      CAMOFOX_TRACES_DIR: process.env.CAMOFOX_TRACES_DIR,
+      CAMOFOX_TRACES_MAX_BYTES: process.env.CAMOFOX_TRACES_MAX_BYTES,
+      CAMOFOX_TRACES_TTL_HOURS: process.env.CAMOFOX_TRACES_TTL_HOURS,
+      CAMOUFOX_EXECUTABLE: process.env.CAMOUFOX_EXECUTABLE,
+      CAMOUFOX_EXECUTABLE_PATH: process.env.CAMOUFOX_EXECUTABLE_PATH,
+      CAMOFOX_EXECUTABLE_PATH: process.env.CAMOFOX_EXECUTABLE_PATH,
+      PROXY_STRATEGY: process.env.PROXY_STRATEGY,
+      PROXY_PROVIDER: process.env.PROXY_PROVIDER,
+      PROXY_HOST: process.env.PROXY_HOST,
+      PROXY_PORT: process.env.PROXY_PORT,
+      PROXY_PORTS: process.env.PROXY_PORTS,
+      PROXY_USERNAME: process.env.PROXY_USERNAME,
+      PROXY_PASSWORD: process.env.PROXY_PASSWORD,
+      PROXY_BACKCONNECT_HOST: process.env.PROXY_BACKCONNECT_HOST,
+      PROXY_BACKCONNECT_PORT: process.env.PROXY_BACKCONNECT_PORT,
+      PROXY_COUNTRY: process.env.PROXY_COUNTRY,
+      PROXY_STATE: process.env.PROXY_STATE,
+      PROXY_CITY: process.env.PROXY_CITY,
+      PROXY_ZIP: process.env.PROXY_ZIP,
+      PROXY_SESSION_DURATION_MINUTES: process.env.PROXY_SESSION_DURATION_MINUTES,
+    },
+    // Crash reporter (opt-in, reports sent to Cloudflare Worker relay)
+    crashReportEnabled:   process.env.CAMOFOX_CRASH_REPORT_ENABLED !== 'false',
+    crashReportUrl:       process.env.CAMOFOX_CRASH_REPORT_URL || '',
+    crashReportRepo:      process.env.CAMOFOX_CRASH_REPORT_REPO,
+    crashReportRateLimit: parseInt(process.env.CAMOFOX_CRASH_REPORT_RATE_LIMIT, 10) || 10,
+    crashReporterConfig:  readCrashReporterConfig(),
+  };
+}
+
+export { loadConfig };

package/lib/cookies.js

@@ -1,119 +1,119 @@
-/**
- * Cookie file reading and parsing for camofox-browser.
- */
-
-import fs from 'fs/promises';
-import path from 'path';
-
-/**
- * Parse a Netscape-format cookie file into structured cookie objects.
- * @param {string} text - Raw cookie file content
- * @returns {Array<{name: string, value: string, domain: string, path: string, expires: number, httpOnly?: boolean, secure?: boolean}>}
- */
-function parseNetscapeCookieFile(text) {
-  const cookies = [];
-  const cleaned = text.replace(/^\uFEFF/, '');
-
-  for (const rawLine of cleaned.split(/\r?\n/)) {
-    const line = rawLine.trim();
-    if (!line) continue;
-    if (line.startsWith('#') && !line.startsWith('#HttpOnly_')) continue;
-
-    let httpOnly = false;
-    let working = line;
-    if (working.startsWith('#HttpOnly_')) {
-      httpOnly = true;
-      working = working.replace(/^#HttpOnly_/, '');
-    }
-
-    const parts = working.split('\t');
-    if (parts.length < 7) continue;
-
-    const domain = parts[0];
-    const cookiePath = parts[2];
-    const secure = parts[3].toUpperCase() === 'TRUE';
-    const expires = Number(parts[4]);
-    const name = parts[5];
-    const value = parts.slice(6).join('\t');
-
-    cookies.push({ name, value, domain, path: cookiePath, expires, httpOnly, secure });
-  }
-
-  return cookies;
-}
-
-/**
- * Read and parse cookies from a Netscape cookie file.
- * @param {object} opts
- * @param {string} opts.cookiesDir - Base directory for cookie files
- * @param {string} opts.cookiesPath - Relative path to the cookie file within cookiesDir
- * @param {string} [opts.domainSuffix] - Only include cookies whose domain ends with this suffix
- * @param {number} [opts.maxBytes=5242880] - Maximum file size in bytes
- * @returns {Promise<Array<{name: string, value: string, domain: string, path: string, expires: number, httpOnly: boolean, secure: boolean}>>}
- */
-async function readCookieFile({ cookiesDir, cookiesPath, domainSuffix, maxBytes = 5 * 1024 * 1024 }) {
-  const resolved = path.resolve(cookiesDir, cookiesPath);
-  if (!resolved.startsWith(cookiesDir + path.sep)) {
-    throw new Error('cookiesPath must be a relative path within the cookies directory');
-  }
-
-  const stat = await fs.stat(resolved);
-  if (stat.size > maxBytes) {
-    throw new Error('Cookie file too large (max 5MB)');
-  }
-
-  const text = await fs.readFile(resolved, 'utf8');
-  let cookies = parseNetscapeCookieFile(text);
-  if (domainSuffix) {
-    cookies = cookies.filter((c) => c.domain.endsWith(domainSuffix));
-  }
-
-  return cookies.map((c) => ({
-    name: c.name,
-    value: c.value,
-    domain: c.domain,
-    path: c.path,
-    expires: c.expires,
-    httpOnly: !!c.httpOnly,
-    secure: !!c.secure,
-  }));
-}
-
-/**
- * Import all cookies from the default bootstrap cookie file into a Playwright context.
- * Intended for first-run session seeding before any persistent storage state exists.
- * Missing file is treated as a no-op.
- * @param {object} opts
- * @param {string} opts.cookiesDir - Base directory for cookie files
- * @param {object} opts.context - Playwright BrowserContext
- * @param {string} [opts.cookiesPath='cookies.txt'] - Relative cookie file path within cookiesDir
- * @param {object} [opts.logger=console] - Logger with warn()
- * @returns {Promise<{imported: number, source: string|null}>}
- */
-async function importBootstrapCookies({ cookiesDir, context, cookiesPath = 'cookies.txt', logger = console }) {
-  if (!cookiesDir || !context) {
-    return { imported: 0, source: null };
-  }
-
-  const resolved = path.resolve(cookiesDir, cookiesPath);
-
-  try {
-    const cookies = await readCookieFile({ cookiesDir, cookiesPath });
-    if (cookies.length === 0) {
-      return { imported: 0, source: resolved };
-    }
-    await context.addCookies(cookies);
-    return { imported: cookies.length, source: resolved };
-  } catch (err) {
-    if (err?.code === 'ENOENT') {
-      return { imported: 0, source: null };
-    }
-    logger?.warn?.('failed to import bootstrap cookies', {
-      cookiesPath: resolved,
-      error: err?.message || String(err),
-    });
-    return { imported: 0, source: resolved };
-  }
-}
-
-export { parseNetscapeCookieFile, readCookieFile, importBootstrapCookies };
+/**
+ * Cookie file reading and parsing for camofox-browser.
+ */
+
+import fs from 'fs/promises';
+import path from 'path';
+
+/**
+ * Parse a Netscape-format cookie file into structured cookie objects.
+ * @param {string} text - Raw cookie file content
+ * @returns {Array<{name: string, value: string, domain: string, path: string, expires: number, httpOnly?: boolean, secure?: boolean}>}
+ */
+function parseNetscapeCookieFile(text) {
+  const cookies = [];
+  const cleaned = text.replace(/^\uFEFF/, '');
+
+  for (const rawLine of cleaned.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line) continue;
+    if (line.startsWith('#') && !line.startsWith('#HttpOnly_')) continue;
+
+    let httpOnly = false;
+    let working = line;
+    if (working.startsWith('#HttpOnly_')) {
+      httpOnly = true;
+      working = working.replace(/^#HttpOnly_/, '');
+    }
+
+    const parts = working.split('\t');
+    if (parts.length < 7) continue;
+
+    const domain = parts[0];
+    const cookiePath = parts[2];
+    const secure = parts[3].toUpperCase() === 'TRUE';
+    const expires = Number(parts[4]);
+    const name = parts[5];
+    const value = parts.slice(6).join('\t');
+
+    cookies.push({ name, value, domain, path: cookiePath, expires, httpOnly, secure });
+  }
+
+  return cookies;
+}
+
+/**
+ * Read and parse cookies from a Netscape cookie file.
+ * @param {object} opts
+ * @param {string} opts.cookiesDir - Base directory for cookie files
+ * @param {string} opts.cookiesPath - Relative path to the cookie file within cookiesDir
+ * @param {string} [opts.domainSuffix] - Only include cookies whose domain ends with this suffix
+ * @param {number} [opts.maxBytes=5242880] - Maximum file size in bytes
+ * @returns {Promise<Array<{name: string, value: string, domain: string, path: string, expires: number, httpOnly: boolean, secure: boolean}>>}
+ */
+async function readCookieFile({ cookiesDir, cookiesPath, domainSuffix, maxBytes = 5 * 1024 * 1024 }) {
+  const resolved = path.resolve(cookiesDir, cookiesPath);
+  if (!resolved.startsWith(cookiesDir + path.sep)) {
+    throw new Error('cookiesPath must be a relative path within the cookies directory');
+  }
+
+  const stat = await fs.stat(resolved);
+  if (stat.size > maxBytes) {
+    throw new Error('Cookie file too large (max 5MB)');
+  }
+
+  const text = await fs.readFile(resolved, 'utf8');
+  let cookies = parseNetscapeCookieFile(text);
+  if (domainSuffix) {
+    cookies = cookies.filter((c) => c.domain.endsWith(domainSuffix));
+  }
+
+  return cookies.map((c) => ({
+    name: c.name,
+    value: c.value,
+    domain: c.domain,
+    path: c.path,
+    expires: c.expires,
+    httpOnly: !!c.httpOnly,
+    secure: !!c.secure,
+  }));
+}
+
+/**
+ * Import all cookies from the default bootstrap cookie file into a Playwright context.
+ * Intended for first-run session seeding before any persistent storage state exists.
+ * Missing file is treated as a no-op.
+ * @param {object} opts
+ * @param {string} opts.cookiesDir - Base directory for cookie files
+ * @param {object} opts.context - Playwright BrowserContext
+ * @param {string} [opts.cookiesPath='cookies.txt'] - Relative cookie file path within cookiesDir
+ * @param {object} [opts.logger=console] - Logger with warn()
+ * @returns {Promise<{imported: number, source: string|null}>}
+ */
+async function importBootstrapCookies({ cookiesDir, context, cookiesPath = 'cookies.txt', logger = console }) {
+  if (!cookiesDir || !context) {
+    return { imported: 0, source: null };
+  }
+
+  const resolved = path.resolve(cookiesDir, cookiesPath);
+
+  try {
+    const cookies = await readCookieFile({ cookiesDir, cookiesPath });
+    if (cookies.length === 0) {
+      return { imported: 0, source: resolved };
+    }
+    await context.addCookies(cookies);
+    return { imported: cookies.length, source: resolved };
+  } catch (err) {
+    if (err?.code === 'ENOENT') {
+      return { imported: 0, source: null };
+    }
+    logger?.warn?.('failed to import bootstrap cookies', {
+      cookiesPath: resolved,
+      error: err?.message || String(err),
+    });
+    return { imported: 0, source: resolved };
+  }
+}
+
+export { parseNetscapeCookieFile, readCookieFile, importBootstrapCookies };