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

package/camofox.config.json

@@ -1,10 +1,10 @@
-{
-  "id": "camofox-browser",
-  "name": "Camofox Browser",
-  "version": "1.6.0",
-  "plugins": {
-    "youtube": { "enabled": true },
-    "persistence": { "enabled": true },
-    "vnc": { "resolution": "1920x1080" }
-  }
-}
+{
+  "id": "camofox-browser",
+  "name": "Camofox Browser",
+  "version": "1.6.0",
+  "plugins": {
+    "youtube": { "enabled": true },
+    "persistence": { "enabled": true },
+    "vnc": { "resolution": "1920x1080" }
+  }
+}

package/lib/auth.js

@@ -1,134 +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 };
+/**
+ * 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

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