zevairouter 1.0.61 → 1.0.65

package/cli/app/cli/hooks/postinstall.js

@@ -148,12 +148,12 @@ try {
   warn(`Camoufox skipped: ${e.message}`);
 }
 
-// 5) CloakBrowser (Grok Turnstile / xAI email bulk)
+// 5) CloakBrowser + mmdb-lib (Grok Turnstile / proxy geoip)
 try {
-  log("… CloakBrowser (Grok bulk / Turnstile)");
+  log("… CloakBrowser + mmdb-lib (Grok bulk / geoip)");
   const cloak = warmCloakbrowser();
   if (cloak.ok) {
-    log("✓ CloakBrowser ready");
+    log("✓ CloakBrowser + mmdb-lib ready");
   } else {
     warn(`CloakBrowser skipped: ${cloak.error?.message || "unknown"} — install on first Grok bulk if needed`);
   }

package/cli/app/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zevairouter",
-  "version": "1.0.61",
+  "version": "1.0.65",
   "description": "Self-hosted AI router: many providers, one OpenAI-compatible /v1 endpoint and dashboard",
   "bin": {
     "zevai": "./cli/cli.js"

package/cli/app/src/lib/oauth/services/displayEnv.js

@@ -0,0 +1,134 @@
+/**
+ * Headed browsers need a display. On bare Linux VPS there is no $DISPLAY.
+ * We try to start Xvfb automatically so CloakBrowser / Turnstile can run.
+ */
+import { spawn, execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+
+const g = globalThis.__zevaiXvfb ??= {
+  proc: null,
+  display: null,
+};
+
+function which(bin) {
+  try {
+    return execFileSync("which", [bin], { encoding: "utf8" }).trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+export function hasUsableDisplay() {
+  // Desktop OS: headed Chromium/Playwright works without $DISPLAY
+  // (macOS GUI session / Windows). Only bare Linux servers need Xvfb.
+  if (process.platform === "darwin" || process.platform === "win32") {
+    return true;
+  }
+
+  const d = process.env.DISPLAY;
+  if (!d || !String(d).trim()) return false;
+
+  // On Linux, verify something is listening if xdpyinfo exists
+  if (which("xdpyinfo")) {
+    try {
+      execFileSync("xdpyinfo", ["-display", d], {
+        stdio: "ignore",
+        timeout: 2000,
+      });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  return true;
+}
+
+function findFreeDisplayNumber() {
+  for (let n = 99; n <= 119; n += 1) {
+    const lock = path.join("/tmp", `.X${n}-lock`);
+    if (!fs.existsSync(lock)) return n;
+  }
+  return 99;
+}
+
+/**
+ * Ensure process.env.DISPLAY is set for headed launches.
+ * @returns {{ ok: boolean, display?: string, managed?: boolean, error?: Error }}
+ */
+export function ensureDisplayForHeadedBrowser() {
+  if (hasUsableDisplay()) {
+    return {
+      ok: true,
+      display: process.env.DISPLAY || (process.platform === "darwin" ? "aqua" : ""),
+      managed: false,
+    };
+  }
+
+  // Only Linux VPS needs a virtual framebuffer
+  if (process.platform !== "linux") {
+    // Should not reach here (hasUsableDisplay is true on darwin/win32)
+    return { ok: true, display: process.env.DISPLAY || "", managed: false };
+  }
+
+  if (g.display && g.proc && !g.proc.killed) {
+    process.env.DISPLAY = g.display;
+    return { ok: true, display: g.display, managed: true };
+  }
+
+  const xvfb = which("Xvfb");
+  if (!xvfb) {
+    const err = new Error(
+      "This VPS has no graphical display ($DISPLAY). Grok/CloakBrowser needs a virtual screen.\n" +
+        "Fix (Ubuntu/Debian as root):\n" +
+        "  apt-get update && apt-get install -y xvfb\n" +
+        "Then restart zevai / zevairouter and retry bulk import.\n" +
+        "ZevaiRouter will auto-start Xvfb when it is installed."
+    );
+    err.code = "XVFB_MISSING";
+    return { ok: false, error: err };
+  }
+
+  const num = findFreeDisplayNumber();
+  const display = `:${num}`;
+  try {
+    const proc = spawn(
+      xvfb,
+      [display, "-screen", "0", "1280x900x24", "-ac", "-nolisten", "tcp"],
+      {
+        stdio: "ignore",
+        detached: true,
+      }
+    );
+    proc.unref();
+    g.proc = proc;
+    g.display = display;
+    process.env.DISPLAY = display;
+
+    // Brief settle so clients don't connect before X is up
+    const start = Date.now();
+    while (Date.now() - start < 800) {
+      /* spin */
+    }
+    if (which("xdpyinfo")) {
+      try {
+        execFileSync("xdpyinfo", ["-display", display], {
+          stdio: "ignore",
+          timeout: 2000,
+        });
+      } catch {
+        // still proceed — some images lack xdpyinfo
+      }
+    }
+
+    console.log(`[display] Started Xvfb on ${display} for headed browser automation`);
+    return { ok: true, display, managed: true };
+  } catch (error) {
+    const err = new Error(
+      `Failed to start Xvfb: ${error?.message || error}. Install with: apt-get install -y xvfb`
+    );
+    err.code = "XVFB_START_FAILED";
+    err.cause = error;
+    return { ok: false, error: err };
+  }
+}

package/cli/hooks/camoufoxRuntime.js

@@ -1,9 +1,16 @@
 // Ensure camoufox-js (optional stealth Firefox engine) is installed AND its
-// browser binary is downloaded. The package is in optionalDependencies, so
-// `npm install -g zevairouter` may legitimately ship without it (e.g. when npm
-// skipped optional install on a constrained network). When the user picks
-// Camoufox in the bulk-import modal we install lazily \u2014 same shape as the
-// sqlite/playwright runtime helpers \u2014 instead of failing the worker.
+// browser binary is downloaded + kept in sync with the JS package.
+//
+// Failure mode we fix for end users (Mac + Ubuntu/Linux + Windows):
+//   camoufox-js emits fingerprint keys (e.g. audio:seed) that an *old* cached
+//   Camoufox binary rejects → "Unknown property audio:seed in config".
+//
+// Strategy:
+//   1) Install camoufox-js into ~/.zevai/runtime when missing
+//   2) On every process first-use: if binary missing OR package version changed
+//      OR no zevai stamp, run `camoufox-js fetch` (no-op when already current)
+//   3) Export force-refresh so launch can recover after Unknown-property errors
+//   4) Linux: best-effort install of GUI libs via playwright install-deps
 const { spawnSync } = require("child_process");
 const { createRequire } = require("module");
 const fs = require("fs");
@@ -14,6 +21,9 @@ const { runNpmInstall, getRuntimeDir, getRuntimeNodeModules } = require("./sqlit
 
 const CAMOUFOX_PACKAGE = "camoufox-js";
 const CAMOUFOX_VERSION = "^0.11.0";
+// Bump when we need every install to re-check binary even if package version
+// string is unchanged (e.g. known bad binary fingerprints).
+const BINARY_POLICY = "v2-audio-seed";
 
 // This helper is reached through webpack-bundled server code, which rewrites
 // bare `require(...)` into its own module registry — so `require("camoufox-js")`
@@ -37,6 +47,7 @@ function getRuntimeRequire() {
 }
 
 let cachedReady = null;
+let binaryCheckedThisProcess = false;
 
 function tryRequireCamoufox() {
   // 1) Direct absolute-path resolution via a runtime-anchored createRequire —
@@ -62,6 +73,34 @@ function tryRequireCamoufox() {
   return null;
 }
 
+function findCamoufoxPackageDir() {
+  try {
+    const rreq = getRuntimeRequire();
+    const candidate = path.join(getRuntimeNodeModules(), CAMOUFOX_PACKAGE);
+    if (fs.existsSync(path.join(candidate, "package.json"))) return candidate;
+    if (rreq) {
+      try {
+        return path.dirname(rreq.resolve(`${CAMOUFOX_PACKAGE}/package.json`));
+      } catch {}
+    }
+  } catch {}
+  try {
+    return path.dirname(nodeRequire.resolve(`${CAMOUFOX_PACKAGE}/package.json`));
+  } catch {}
+  return null;
+}
+
+function getCamoufoxJsPackageVersion() {
+  try {
+    const dir = findCamoufoxPackageDir();
+    if (!dir) return null;
+    const pkg = JSON.parse(fs.readFileSync(path.join(dir, "package.json"), "utf8"));
+    return String(pkg.version || "").trim() || null;
+  } catch {
+    return null;
+  }
+}
+
 function findCamoufoxCli() {
   const candidates = [];
   // camoufox-js ships its CLI entry as dist/__main__.js (there is no cli.js).
@@ -73,6 +112,8 @@ function findCamoufoxCli() {
   try {
     candidates.push(path.join(getRuntimeNodeModules(), CAMOUFOX_PACKAGE, ...rel));
   } catch {}
+  const pkgDir = findCamoufoxPackageDir();
+  if (pkgDir) candidates.push(path.join(pkgDir, ...rel));
   for (const candidate of candidates) {
     if (candidate && fs.existsSync(candidate)) return candidate;
   }
@@ -92,6 +133,10 @@ function getCamoufoxBinaryDir() {
   return path.join(homeDir, ".cache", "camoufox");
 }
 
+function getStampPath() {
+  return path.join(getCamoufoxBinaryDir(), ".zevai-binary-stamp.json");
+}
+
 // The launch binary camoufox-js resolves per OS (dist/pkgman.js LAUNCH_FILE),
 // relative to the install dir. Linux is the primary target (Ubuntu VPS).
 function getCamoufoxLaunchBinary() {
@@ -109,6 +154,70 @@ function isCamoufoxBinaryAvailable() {
   }
 }
 
+function getInstalledBinaryVersion() {
+  try {
+    const versionPath = path.join(getCamoufoxBinaryDir(), "version.json");
+    if (!fs.existsSync(versionPath)) return null;
+    const data = JSON.parse(fs.readFileSync(versionPath, "utf8"));
+    if (!data?.version) return null;
+    return `${data.version}${data.release ? `-${data.release}` : ""}`;
+  } catch {
+    return null;
+  }
+}
+
+function readBinaryStamp() {
+  try {
+    const p = getStampPath();
+    if (!fs.existsSync(p)) return null;
+    return JSON.parse(fs.readFileSync(p, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function writeBinaryStamp({ packageVersion, binaryVersion } = {}) {
+  try {
+    const dir = getCamoufoxBinaryDir();
+    fs.mkdirSync(dir, { recursive: true });
+    const stamp = {
+      policy: BINARY_POLICY,
+      packageVersion: packageVersion || getCamoufoxJsPackageVersion(),
+      binaryVersion: binaryVersion || getInstalledBinaryVersion(),
+      platform: process.platform,
+      arch: process.arch,
+      fetchedAt: new Date().toISOString(),
+    };
+    fs.writeFileSync(getStampPath(), JSON.stringify(stamp, null, 2));
+    return stamp;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Decide whether we should run `camoufox-js fetch`.
+ * - Missing binary → yes
+ * - No stamp (legacy installs, Mac beta.24 era) → yes (fetch is no-op if current)
+ * - Package version or policy changed → yes
+ * - force → yes
+ */
+function shouldFetchCamoufoxBinary({ force = false } = {}) {
+  if (force) return true;
+  if (process.env.ZEVAI_CAMOUFOX_SKIP_FETCH === "1") return false;
+  if (!isCamoufoxBinaryAvailable()) return true;
+  if (!getInstalledBinaryVersion()) return true;
+
+  const stamp = readBinaryStamp();
+  if (!stamp) return true;
+
+  const pkgVer = getCamoufoxJsPackageVersion();
+  if (pkgVer && stamp.packageVersion && stamp.packageVersion !== pkgVer) return true;
+  if (stamp.policy !== BINARY_POLICY) return true;
+
+  return false;
+}
+
 function ensureCamoufoxPackage({ silent = false } = {}) {
   const mod = tryRequireCamoufox();
   if (mod) return { ok: true, module: mod };
@@ -140,15 +249,30 @@ function fetchCamoufoxBinary({ silent = false, timeout = 600_000 } = {}) {
   if (!cliPath) {
     return { ok: false, reason: "camoufox-js cli script not found after install" };
   }
-  if (!silent) console.log("\u23f3 Downloading Camoufox browser binary (first run, ~150MB)...");
+  if (!silent) {
+    console.log(
+      isCamoufoxBinaryAvailable()
+        ? "\u23f3 Checking/updating Camoufox browser binary (keeps fingerprint config compatible)..."
+        : "\u23f3 Downloading Camoufox browser binary (first run, ~150–300MB)..."
+    );
+  }
   const res = spawnSync(process.execPath, [cliPath, "fetch"], {
     stdio: silent ? ["ignore", "pipe", "pipe"] : "inherit",
     timeout,
     encoding: "utf8",
+    env: {
+      ...process.env,
+      // Never skip: users hit audio:seed / unknown property when binary lags.
+      PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD: undefined,
+    },
   });
   if (res.status === 0) {
+    writeBinaryStamp({
+      packageVersion: getCamoufoxJsPackageVersion(),
+      binaryVersion: getInstalledBinaryVersion(),
+    });
     if (!silent) console.log("\u2705 Camoufox browser ready");
-    return { ok: true };
+    return { ok: true, binaryVersion: getInstalledBinaryVersion() };
   }
   const stderr = String(res.stderr || "");
   let reason = "unknown error";
@@ -159,6 +283,66 @@ function fetchCamoufoxBinary({ silent = false, timeout = 600_000 } = {}) {
   return { ok: false, reason };
 }
 
+/**
+ * Ensure binary exists and matches current camoufox-js expectations.
+ * Safe to call often: after the first successful check this process, subsequent
+ * calls are free unless force=true.
+ */
+function ensureCamoufoxBinary({ silent = false, force = false } = {}) {
+  if (!force && binaryCheckedThisProcess && isCamoufoxBinaryAvailable()) {
+    return { ok: true, skipped: "already-checked", binaryVersion: getInstalledBinaryVersion() };
+  }
+
+  if (!shouldFetchCamoufoxBinary({ force })) {
+    // Stamp already valid — still write stamp if somehow missing binary version field
+    if (!readBinaryStamp()) {
+      writeBinaryStamp();
+    }
+    binaryCheckedThisProcess = true;
+    return { ok: true, skipped: "up-to-date", binaryVersion: getInstalledBinaryVersion() };
+  }
+
+  const fetched = fetchCamoufoxBinary({ silent });
+  if (!fetched.ok) {
+    // If we already have *some* binary, degrade gracefully — launch path will
+    // sanitize unsupported fingerprint keys. Only hard-fail when missing entirely.
+    if (isCamoufoxBinaryAvailable()) {
+      if (!silent) {
+        console.log(
+          `\u26a0 Camoufox binary update failed (${fetched.reason}); using existing binary with config sanitization.`
+        );
+      }
+      binaryCheckedThisProcess = true;
+      return {
+        ok: true,
+        degraded: true,
+        reason: fetched.reason,
+        binaryVersion: getInstalledBinaryVersion(),
+      };
+    }
+    return fetched;
+  }
+
+  binaryCheckedThisProcess = true;
+  return fetched;
+}
+
+/**
+ * Force re-download after launch errors like "Unknown property audio:seed".
+ * Clears process cache so the next ensure re-checks.
+ */
+function refreshCamoufoxBinary({ silent = false } = {}) {
+  binaryCheckedThisProcess = false;
+  cachedReady = null;
+  try {
+    const stamp = getStampPath();
+    if (fs.existsSync(stamp)) fs.unlinkSync(stamp);
+  } catch {
+    // ignore
+  }
+  return ensureCamoufoxBinary({ silent, force: true });
+}
+
 function findPlaywrightCli() {
   const candidates = [];
   for (const pkg of ["playwright", "playwright-core"]) {
@@ -184,7 +368,11 @@ function findPlaywrightCli() {
 function ensureLinuxBrowserDeps({ silent = false } = {}) {
   if (process.platform !== "linux") return { ok: true, skipped: "not-linux" };
   if (typeof process.getuid === "function" && process.getuid() !== 0) {
-    if (!silent) console.log("\u2139 Skipping auto-install of Camoufox system libs (not root). If Camoufox fails to launch, run: npx playwright install-deps firefox");
+    if (!silent) {
+      console.log(
+        "\u2139 Skipping auto-install of Camoufox system libs (not root). If Camoufox fails to launch, run: npx playwright install-deps firefox"
+      );
+    }
     return { ok: true, skipped: "not-root" };
   }
   const cliPath = findPlaywrightCli();
@@ -199,37 +387,41 @@ function ensureLinuxBrowserDeps({ silent = false } = {}) {
     if (!silent) console.log("\u2705 Camoufox system libraries ready");
     return { ok: true };
   }
-  if (!silent) console.log("\u26a0 Could not auto-install system libs; if Camoufox fails to launch run: npx playwright install-deps firefox");
+  if (!silent) {
+    console.log(
+      "\u26a0 Could not auto-install system libs; if Camoufox fails to launch run: npx playwright install-deps firefox"
+    );
+  }
   return { ok: false, reason: String(res.stderr || "").trim().split(/\r?\n/).pop()?.slice(0, 200) };
 }
 
-function ensureCamoufoxRuntime({ silent = false } = {}) {
-  if (cachedReady === true) return { ok: true };
+function ensureCamoufoxRuntime({ silent = false, forceBinaryRefresh = false } = {}) {
+  if (cachedReady === true && !forceBinaryRefresh) {
+    return { ok: true, module: tryRequireCamoufox() };
+  }
 
   const pkg = ensureCamoufoxPackage({ silent });
   if (!pkg.ok) {
     cachedReady = false;
     const error = new Error(
       `Camoufox engine not available. ${pkg.reason}. ` +
-      `Install manually with "npm install -g camoufox-js && npx camoufox-js fetch", then retry. ` +
-      `You can also switch back to the Chromium engine in the bulk-import modal.`
+        `Install manually with "npm install -g camoufox-js && npx camoufox-js fetch", then retry. ` +
+        `You can also switch back to the Chromium engine in the bulk-import modal.`
     );
     error.code = "CAMOUFOX_PACKAGE_MISSING";
     return { ok: false, error };
   }
 
-  if (!isCamoufoxBinaryAvailable()) {
-    const fetched = fetchCamoufoxBinary({ silent });
-    if (!fetched.ok) {
-      cachedReady = false;
-      const error = new Error(
-        `Camoufox browser binary not downloaded. ${fetched.reason}. ` +
+  const binary = ensureCamoufoxBinary({ silent, force: forceBinaryRefresh });
+  if (!binary.ok) {
+    cachedReady = false;
+    const error = new Error(
+      `Camoufox browser binary not downloaded. ${binary.reason}. ` +
         `Run "npx camoufox-js fetch" manually, then retry. ` +
         `You can also switch back to the Chromium engine in the bulk-import modal.`
-      );
-      error.code = "CAMOUFOX_BINARY_MISSING";
-      return { ok: false, error };
-    }
+    );
+    error.code = "CAMOUFOX_BINARY_MISSING";
+    return { ok: false, error };
   }
 
   // Ensure Linux GUI libraries are present (idempotent). Runs even when the
@@ -238,7 +430,12 @@ function ensureCamoufoxRuntime({ silent = false } = {}) {
   ensureLinuxBrowserDeps({ silent });
 
   cachedReady = true;
-  return { ok: true, module: pkg.module };
+  return {
+    ok: true,
+    module: pkg.module,
+    binaryVersion: binary.binaryVersion || getInstalledBinaryVersion(),
+    binaryDegraded: Boolean(binary.degraded),
+  };
 }
 
 function loadCamoufoxModule() {
@@ -247,11 +444,17 @@ function loadCamoufoxModule() {
 
 function resetCache() {
   cachedReady = null;
+  binaryCheckedThisProcess = false;
 }
 
 module.exports = {
   ensureCamoufoxRuntime,
+  ensureCamoufoxBinary,
+  refreshCamoufoxBinary,
   loadCamoufoxModule,
   isCamoufoxBinaryAvailable,
+  getInstalledBinaryVersion,
+  getCamoufoxJsPackageVersion,
+  getCamoufoxBinaryDir,
   resetCache,
 };

package/cli/hooks/cloakbrowserRuntime.js

@@ -1,14 +1,22 @@
 // Lazy-install helper for cloakbrowser (stealth Chromium that can pass Turnstile).
 // Same shape as camoufoxRuntime / playwrightRuntime — optional package, install on demand.
+// Also installs mmdb-lib (required by cloakbrowser when geoip: true for proxy timezone match).
 const { createRequire } = require("module");
 const fs = require("fs");
 const path = require("path");
 
-const { runNpmInstall, getRuntimeDir, getRuntimeNodeModules, summarizeNpmError } = require("./sqliteRuntime");
+const {
+  runNpmInstall,
+  getRuntimeDir,
+  getRuntimeNodeModules,
+  summarizeNpmError,
+  buildEnvWithRuntime,
+} = require("./sqliteRuntime");
 
 const CLOAKBROWSER_PACKAGE = "cloakbrowser";
-// Keep in sync with package.json optionalDependencies
 const CLOAKBROWSER_VERSION = "^0.3.32";
+const MMDB_PACKAGE = "mmdb-lib";
+const MMDB_VERSION = "^3.0.2";
 
 const nodeRequire =
   typeof __non_webpack_require__ === "function" ? __non_webpack_require__ : require;
@@ -24,6 +32,10 @@ function getRuntimeRequire() {
 
 let cachedReady = null;
 
+function hasPackage(name) {
+  return fs.existsSync(path.join(getRuntimeNodeModules(), name, "package.json"));
+}
+
 function tryRequireCloakbrowser() {
   try {
     const rreq = getRuntimeRequire();
@@ -41,14 +53,20 @@ function tryRequireCloakbrowser() {
       return nodeRequire(candidate);
     }
   } catch {}
-  // Dev / user global installs
+  return null;
+}
+
+function tryRequireMmdb() {
   try {
-    const home = process.env.HOME || process.env.USERPROFILE || "";
-    const aurix = path.join(home, ".aurix/agent/node_modules", CLOAKBROWSER_PACKAGE);
-    if (fs.existsSync(path.join(aurix, "package.json"))) {
-      return nodeRequire(aurix);
+    const rreq = getRuntimeRequire();
+    const candidate = path.join(getRuntimeNodeModules(), MMDB_PACKAGE);
+    if (rreq && fs.existsSync(path.join(candidate, "package.json"))) {
+      return rreq(candidate);
     }
   } catch {}
+  try {
+    return nodeRequire(MMDB_PACKAGE);
+  } catch {}
   return null;
 }
 
@@ -56,45 +74,75 @@ function loadCloakbrowserModule() {
   return tryRequireCloakbrowser();
 }
 
+/**
+ * Ensure cloakbrowser + mmdb-lib are available under ~/.zevai/runtime.
+ * mmdb-lib is required when launching with geoip: true (proxy timezone/locale).
+ */
 function ensureCloakbrowserRuntime({ silent = false } = {}) {
-  if (cachedReady?.ok && cachedReady.module) {
+  if (cachedReady?.ok && cachedReady.module && tryRequireMmdb()) {
     return cachedReady;
   }
 
-  let mod = tryRequireCloakbrowser();
-  if (mod?.launch) {
-    cachedReady = { ok: true, module: mod };
-    return cachedReady;
+  // Inject runtime node_modules into resolution for cloakbrowser's require("mmdb-lib")
+  try {
+    const env = buildEnvWithRuntime(process.env);
+    if (env.NODE_PATH && !process.env.NODE_PATH?.includes(getRuntimeNodeModules())) {
+      process.env.NODE_PATH = env.NODE_PATH;
+      // Re-init module paths for already-running process
+      try {
+        // eslint-disable-next-line no-underscore-dangle
+        require("module").Module._initPaths();
+      } catch {
+        /* ignore */
+      }
+    }
+  } catch {
+    /* ignore */
   }
 
-  if (!silent) {
-    console.log(`[cloakbrowser] Installing ${CLOAKBROWSER_PACKAGE}@${CLOAKBROWSER_VERSION} into runtime…`);
+  let mod = tryRequireCloakbrowser();
+  const needCloak = !mod?.launch;
+  const needMmdb = !tryRequireMmdb() && !hasPackage(MMDB_PACKAGE);
+
+  if (needCloak || needMmdb) {
+    const pkgs = [];
+    if (needCloak) pkgs.push(`${CLOAKBROWSER_PACKAGE}@${CLOAKBROWSER_VERSION}`);
+    if (needMmdb) pkgs.push(`${MMDB_PACKAGE}@${MMDB_VERSION}`);
+
+    if (!silent) {
+      console.log(`[cloakbrowser] Installing ${pkgs.join(", ")} into runtime…`);
+    }
+
+    const installRes = runNpmInstall({
+      cwd: getRuntimeDir(),
+      pkgs,
+      timeout: 300_000,
+    });
+
+    if (!installRes.ok) {
+      const reason = summarizeNpmError(installRes.stderr || installRes.stdout || "");
+      const err = new Error(
+        `Failed to install ${pkgs.join(", ")}. On the host run: cd "${getRuntimeDir()}" && npm install ${pkgs.join(" ")} — ${reason}`
+      );
+      err.code = "CLOAKBROWSER_INSTALL_FAILED";
+      return { ok: false, error: err };
+    }
   }
 
-  // runNpmInstall expects a single options object: { cwd, pkgs, extraArgs, timeout }
-  // (NOT positional args). Wrong call shape caused: "pkgs is not iterable" / toast
-  // "Failed to install cloakbrowser … b is not iterable" on first Grok bulk use.
-  const installRes = runNpmInstall({
-    cwd: getRuntimeDir(),
-    pkgs: [`${CLOAKBROWSER_PACKAGE}@${CLOAKBROWSER_VERSION}`],
-    timeout: 300_000,
-  });
-
-  if (!installRes.ok) {
-    const reason = summarizeNpmError(installRes.stderr || installRes.stdout || "");
+  mod = tryRequireCloakbrowser();
+  if (!mod?.launch) {
     const err = new Error(
-      `Failed to install cloakbrowser. On the host run: cd "${getRuntimeDir()}" && npm install ${CLOAKBROWSER_PACKAGE}@${CLOAKBROWSER_VERSION} — ${reason}`
+      `cloakbrowser installed but launch() is missing. Reinstall: cd "${getRuntimeDir()}" && npm install ${CLOAKBROWSER_PACKAGE}@${CLOAKBROWSER_VERSION} ${MMDB_PACKAGE}@${MMDB_VERSION}`
     );
-    err.code = "CLOAKBROWSER_INSTALL_FAILED";
+    err.code = "CLOAKBROWSER_API_MISMATCH";
     return { ok: false, error: err };
   }
 
-  mod = tryRequireCloakbrowser();
-  if (!mod?.launch) {
+  if (!tryRequireMmdb() && !hasPackage(MMDB_PACKAGE)) {
     const err = new Error(
-      `cloakbrowser installed but launch() is missing. Reinstall: cd "${getRuntimeDir()}" && npm install ${CLOAKBROWSER_PACKAGE}@${CLOAKBROWSER_VERSION}`
+      `mmdb-lib is required for geoip: true. Install: cd "${getRuntimeDir()}" && npm install ${MMDB_PACKAGE}@${MMDB_VERSION}`
     );
-    err.code = "CLOAKBROWSER_API_MISMATCH";
+    err.code = "MMDB_MISSING";
     return { ok: false, error: err };
   }
 
@@ -107,4 +155,6 @@ module.exports = {
   loadCloakbrowserModule,
   CLOAKBROWSER_PACKAGE,
   CLOAKBROWSER_VERSION,
+  MMDB_PACKAGE,
+  MMDB_VERSION,
 };