@phi-code-admin/camofox-browser 1.0.0

package/lib/auth.js

@@ -0,0 +1,134 @@
+/**
+ * Shared auth middleware for camofox-browser.
+ *
+ * Extracts the duplicated auth pattern from cookie/storage_state endpoints
+ * into a reusable Express middleware factory.
+ *
+ * Policy (requireAuth / per-route):
+ *   - If CAMOFOX_API_KEY is set, require Bearer token match (timing-safe).
+ *   - If CAMOFOX_ACCESS_KEY is set, also accept it as an alternative (superkey).
+ *   - If neither key set and NODE_ENV !== production, allow loopback (127.0.0.1 / ::1).
+ *   - Otherwise, reject.
+ *
+ * Policy (accessKeyMiddleware / global):
+ *   - If CAMOFOX_ACCESS_KEY is set, require Bearer match on all routes except
+ *     /health, cookie import (when CAMOFOX_API_KEY set), and /stop (when CAMOFOX_ADMIN_KEY set).
+ *   - If not set, pass through (backward-compatible).
+ */
+
+import crypto from 'crypto';
+
+/**
+ * Timing-safe string comparison.
+ */
+function timingSafeCompare(a, b) {
+  if (typeof a !== 'string' || typeof b !== 'string') return false;
+  const bufA = Buffer.from(a);
+  const bufB = Buffer.from(b);
+  if (bufA.length !== bufB.length) {
+    // Compare against self to burn constant time, then return false
+    crypto.timingSafeEqual(bufA, bufA);
+    return false;
+  }
+  return crypto.timingSafeEqual(bufA, bufB);
+}
+
+/**
+ * Check if an address is loopback.
+ */
+function isLoopbackAddress(address) {
+  if (!address) return false;
+  return address === '127.0.0.1' || address === '::1' || address === '::ffff:127.0.0.1';
+}
+
+/**
+ * Create an Express middleware that enforces API key auth.
+ *
+ * Accepts CAMOFOX_API_KEY as primary token. When CAMOFOX_ACCESS_KEY is also
+ * configured, it is accepted as an alternative ("superkey") so that routes
+ * gated by both the global access-key middleware AND this per-route middleware
+ * don't require two different tokens in a single Authorization header.
+ *
+ * @param {object} config - Must have { apiKey, nodeEnv }; optionally { accessKey }
+ * @param {object} [options]
+ * @param {string} [options.errorMessage] - Custom error message when rejecting unauthenticated requests
+ * @returns {function} Express middleware (req, res, next)
+ */
+export function requireAuth(config, options = {}) {
+  const errorMessage = options.errorMessage ||
+    'This endpoint requires CAMOFOX_API_KEY except for loopback requests in non-production environments.';
+
+  return function requireAuthCheck(req, res, next) {
+    const auth = String(req.headers['authorization'] || '');
+    const match = auth.match(/^Bearer\s+(.+)$/i);
+    const token = match ? match[1]?.trim() : null;
+
+    // Accept API key
+    if (config.apiKey && token && timingSafeCompare(token, config.apiKey)) {
+      return next();
+    }
+
+    // Accept access key as alternative (superkey)
+    if (config.accessKey && token && timingSafeCompare(token, config.accessKey)) {
+      return next();
+    }
+
+    // If any key is configured, a valid token was required -- reject
+    if (config.apiKey || config.accessKey) {
+      return res.status(403).json({ error: 'Forbidden' });
+    }
+
+    // No keys configured -- allow loopback in non-production
+    const remoteAddress = req.socket?.remoteAddress || '';
+    const allowUnauthedLocal = config.nodeEnv !== 'production' && isLoopbackAddress(remoteAddress);
+    if (!allowUnauthedLocal) {
+      return res.status(403).json({ error: errorMessage });
+    }
+
+    next();
+  };
+}
+
+/**
+ * Global access-key middleware factory.
+ *
+ * When CAMOFOX_ACCESS_KEY is set, requires `Authorization: Bearer <key>` on
+ * every route except:
+ *   - GET /health (Docker/Fly healthcheck)
+ *   - POST /sessions/:userId/cookies (only when CAMOFOX_API_KEY is also set -- has its own gate)
+ *   - POST /stop (only when CAMOFOX_ADMIN_KEY is also set -- has its own gate)
+ *
+ * When a route's dedicated key is NOT configured, the access-key middleware
+ * does NOT exempt it -- defense-in-depth prevents unprotected endpoints.
+ *
+ * When CAMOFOX_ACCESS_KEY is not set, passes through (backward-compatible).
+ *
+ * @param {object} config - Must have { accessKey }; optionally { apiKey, adminKey }
+ * @returns {function} Express middleware (req, res, next)
+ */
+export function accessKeyMiddleware(config) {
+  return function accessKeyCheck(req, res, next) {
+    if (!config.accessKey) return next();
+
+    // Exempt healthcheck
+    if (req.path === '/health') return next();
+
+    // Exempt routes with their own dedicated auth -- but only when their key is configured.
+    // If the dedicated key is NOT set, the access key gates the route (defense-in-depth).
+    if (config.apiKey && req.method === 'POST' && /^\/sessions\/[^/]+\/cookies$/.test(req.path)) return next();
+    if (config.adminKey && req.method === 'POST' && req.path === '/stop') return next();
+
+    const auth = String(req.headers['authorization'] || '');
+    const match = auth.match(/^Bearer\s+(.+)$/i);
+    const token = match ? match[1]?.trim() : null;
+    if (!token || !timingSafeCompare(token, config.accessKey)) {
+      return res.status(401)
+        .set('WWW-Authenticate', 'Bearer realm="camofox"')
+        .json({ error: 'Unauthorized' });
+    }
+    next();
+  };
+}
+
+// Re-export utilities so server.js can still use them directly
+export { timingSafeCompare, isLoopbackAddress };

package/lib/camoufox-executable.js

@@ -0,0 +1,189 @@
+import crypto from 'crypto';
+import {
+  accessSync,
+  constants,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  realpathSync,
+  rmSync,
+  statSync,
+  symlinkSync,
+  writeFileSync,
+} from 'fs';
+import { dirname, join, resolve } from 'path';
+import { platform, tmpdir } from 'os';
+
+function assertExecutable(path) {
+  const stat = statSync(path);
+  if (!stat.isFile() && !stat.isSymbolicLink()) {
+    throw new Error(`Camoufox executable is not a file: ${path}`);
+  }
+  if (platform() !== 'win32') accessSync(path, constants.X_OK);
+}
+
+function nixStoreRoot(path) {
+  const match = path.match(/^\/nix\/store\/[^/]+/);
+  return match?.[0] || null;
+}
+
+function collectDirs(root, maxDepth = 4) {
+  const dirs = [];
+  const queue = [{ dir: root, depth: 0 }];
+  const seen = new Set();
+
+  while (queue.length > 0) {
+    const { dir, depth } = queue.shift();
+    if (seen.has(dir)) continue;
+    seen.add(dir);
+    dirs.push(dir);
+    if (depth >= maxDepth) continue;
+
+    let entries = [];
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;
+      queue.push({ dir: join(dir, entry.name), depth: depth + 1 });
+    }
+  }
+
+  return dirs;
+}
+
+function findResourceDir(executablePath) {
+  const resolvedPath = realpathSync(executablePath);
+  const directDirs = [
+    dirname(executablePath),
+    dirname(resolvedPath),
+  ];
+
+  const storeRoot = nixStoreRoot(resolvedPath) || nixStoreRoot(executablePath);
+  const likelyDirs = storeRoot
+    ? [
+        storeRoot,
+        join(storeRoot, 'lib', 'camoufox'),
+        join(storeRoot, 'libexec', 'camoufox'),
+        join(storeRoot, 'share', 'camoufox'),
+        join(storeRoot, 'opt', 'camoufox'),
+      ]
+    : [];
+
+  const allCandidates = [...directDirs, ...likelyDirs];
+  for (const dir of allCandidates) {
+    if (existsSync(join(dir, 'properties.json'))) return dir;
+  }
+
+  if (storeRoot) {
+    for (const dir of collectDirs(storeRoot)) {
+      if (existsSync(join(dir, 'properties.json'))) return dir;
+    }
+  }
+
+  return null;
+}
+
+function ensureSymlink(target, linkPath, type = 'file') {
+  rmSync(linkPath, { force: true, recursive: true });
+  symlinkSync(target, linkPath, platform() === 'win32' && type === 'dir' ? 'junction' : type);
+}
+
+function shimRootFor(executablePath, resourceDir) {
+  const key = crypto
+    .createHash('sha256')
+    .update(`${realpathSync(executablePath)}\n${realpathSync(resourceDir)}`)
+    .digest('hex')
+    .slice(0, 16);
+  return join(tmpdir(), 'camofox-browser-external-camoufox', key);
+}
+
+function ensureLaunchShim(executablePath, resourceDir) {
+  const shimRoot = shimRootFor(executablePath, resourceDir);
+  mkdirSync(shimRoot, { recursive: true });
+
+  const shimExecutable = join(shimRoot, platform() === 'win32' ? 'camoufox.exe' : 'camoufox-bin');
+  ensureSymlink(realpathSync(executablePath), shimExecutable);
+
+  for (const name of ['properties.json', 'version.json']) {
+    const target = join(resourceDir, name);
+    if (existsSync(target)) ensureSymlink(realpathSync(target), join(shimRoot, name));
+  }
+
+  const fontconfig = join(resourceDir, 'fontconfig');
+  if (existsSync(fontconfig)) ensureSymlink(realpathSync(fontconfig), join(shimRoot, 'fontconfig'), 'dir');
+
+  return shimExecutable;
+}
+
+function camoufoxLaunchFileName() {
+  if (platform() === 'win32') return 'camoufox.exe';
+  if (platform() === 'darwin') return join('Camoufox.app', 'Contents', 'MacOS', 'camoufox');
+  return 'camoufox-bin';
+}
+
+function ensureCamoufoxJsCache(resourceDir, cacheDir, executablePath) {
+  const cacheVersion = join(cacheDir, 'version.json');
+  const cacheFontconfig = join(cacheDir, 'fontconfig');
+  const cacheProperties = join(cacheDir, 'properties.json');
+  const cacheExecutable = join(cacheDir, camoufoxLaunchFileName());
+
+  if (
+    existsSync(cacheVersion) &&
+    existsSync(cacheFontconfig) &&
+    existsSync(cacheProperties) &&
+    existsSync(cacheExecutable)
+  ) {
+    return;
+  }
+
+  const versionFile = join(resourceDir, 'version.json');
+  const propertiesFile = join(resourceDir, 'properties.json');
+  const fontconfig = join(resourceDir, 'fontconfig');
+  if (!existsSync(versionFile) || !existsSync(propertiesFile) || !existsSync(fontconfig)) {
+    throw new Error(
+      `External Camoufox bundle at ${resourceDir} must include properties.json, version.json, and fontconfig/ for camoufox-js compatibility`
+    );
+  }
+
+  mkdirSync(cacheDir, { recursive: true });
+  if (!existsSync(cacheVersion)) {
+    writeFileSync(cacheVersion, readFileSync(versionFile));
+  }
+  if (!existsSync(cacheProperties)) {
+    ensureSymlink(realpathSync(propertiesFile), cacheProperties);
+  }
+  if (!existsSync(cacheFontconfig)) {
+    ensureSymlink(realpathSync(fontconfig), cacheFontconfig, 'dir');
+  }
+  if (!existsSync(cacheExecutable)) {
+    mkdirSync(dirname(cacheExecutable), { recursive: true });
+    ensureSymlink(realpathSync(executablePath), cacheExecutable);
+  }
+}
+
+export function prepareExternalCamoufoxExecutable(executablePath, { cacheDir } = {}) {
+  if (!executablePath) return null;
+  if (!cacheDir) throw new Error('cacheDir is required for external Camoufox executable preparation');
+
+  const resolvedExecutable = resolve(executablePath);
+  assertExecutable(resolvedExecutable);
+
+  const resourceDir = findResourceDir(resolvedExecutable);
+  if (!resourceDir) {
+    throw new Error(
+      `Could not find Camoufox resources for ${resolvedExecutable}. ` +
+      'Point the executable override at a Camoufox bundle that includes properties.json.'
+    );
+  }
+
+  ensureCamoufoxJsCache(resourceDir, cacheDir, resolvedExecutable);
+
+  return {
+    executablePath: ensureLaunchShim(resolvedExecutable, resourceDir),
+    resourceDir,
+  };
+}

package/lib/config.js

@@ -0,0 +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 };

package/lib/cookies.js

@@ -0,0 +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 };