chromiumfish 0.1.3 → 0.1.4

package/README.md

@@ -12,7 +12,7 @@ npx chromiumfish fetch        # download + cache the browser build
 ```javascript
 import { ChromiumFish } from "chromiumfish";
 
-const browser = await ChromiumFish({ personaSeed: 27182, headless: true });
+const browser = await ChromiumFish({ personaSeed: "alpha-7", headless: true });
 const page = await browser.newPage();
 await page.goto("https://abrahamjuliot.github.io/creepjs/");
 await page.screenshot({ path: "fp.png" });
@@ -26,7 +26,7 @@ await browser.close();
 
 | Option | Default | Description |
 |--------|---------|-------------|
-| `personaSeed` | — | Integer seed for a stable, internally-consistent fingerprint persona. |
+| `personaSeed` | — | String id for a stable, internally-consistent fingerprint persona (any string; a number works too). |
 | `headless` | `true` | Run headless (SwiftShader). |
 | `proxy` | — | Playwright proxy object, e.g. `{ server, username, password }`. |
 | `windowSize` | `[1920, 1080]` | Window dimensions (`null` to omit). |

package/dist/fetch.js

@@ -11,7 +11,7 @@ import * as fs from "node:fs";
 import * as https from "node:https";
 import * as os from "node:os";
 import * as path from "node:path";
-import { browserVersion, releaseBaseUrl } from "./version.js";
+import { assertSafeVersion, browserVersion, releaseBaseUrl } from "./version.js";
 export function cacheRoot() {
     const env = process.env.CHROMIUMFISH_CACHE_DIR;
     if (env)
@@ -35,12 +35,13 @@ export function platformSlug() {
     throw new Error(`unsupported platform: ${process.platform}`);
 }
 function assetName(version) {
+    assertSafeVersion(version);
     const slug = platformSlug();
     const ext = slug.startsWith("win") ? "zip" : "tar.gz";
     return `chromiumfish-${version}-${slug}.${ext}`;
 }
 export function installDir(version = browserVersion()) {
-    return path.join(cacheRoot(), version, platformSlug());
+    return path.join(cacheRoot(), assertSafeVersion(version), platformSlug());
 }
 const BINARY_NAMES = ["chromiumfish", "chrome", "chromiumfish.exe", "chrome.exe", "ChromiumFish"];
 export function findBinary(root) {
@@ -48,8 +49,15 @@ export function findBinary(root) {
         return null;
     for (const name of BINARY_NAMES) {
         const direct = path.join(root, name);
-        if (fs.existsSync(direct) && fs.statSync(direct).isFile())
-            return direct;
+        // statSync can throw if the file is removed between existsSync and stat
+        // (TOCTOU); treat any stat failure as "not a usable binary here".
+        try {
+            if (fs.statSync(direct).isFile())
+                return direct;
+        }
+        catch {
+            /* keep looking */
+        }
     }
     const stack = [root];
     while (stack.length) {
@@ -64,11 +72,15 @@ export function findBinary(root) {
     }
     return null;
 }
+// Idle-timeout (ms) applied to every download/fetch socket. A stalled server
+// (no bytes for this long) aborts instead of hanging the launch forever.
+const DOWNLOAD_IDLE_TIMEOUT_MS = 60_000;
+const FETCH_IDLE_TIMEOUT_MS = 30_000;
 function download(url, dest) {
     fs.mkdirSync(path.dirname(dest), { recursive: true });
     return new Promise((resolve, reject) => {
         const get = (u) => {
-            https.get(u, (res) => {
+            const req = https.get(u, (res) => {
                 if (res.statusCode && res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
                     res.resume();
                     return get(res.headers.location);
@@ -80,15 +92,31 @@ function download(url, dest) {
                 const total = Number(res.headers["content-length"] || 0);
                 let read = 0;
                 const out = fs.createWriteStream(dest);
+                // On any failure: tear down both streams and remove the partial file
+                // so a later run doesn't trip over a truncated/corrupt download.
+                const fail = (err) => {
+                    res.destroy();
+                    out.destroy();
+                    try {
+                        fs.rmSync(dest, { force: true });
+                    }
+                    catch { /* best effort */ }
+                    reject(err);
+                };
                 res.on("data", (c) => {
                     read += c.length;
                     if (total)
                         process.stderr.write(`\r[chromiumfish] ${Math.floor((read / total) * 100)}%`);
                 });
+                res.on("error", fail);
                 res.pipe(out);
                 out.on("finish", () => { process.stderr.write("\n"); out.close(() => resolve()); });
-                out.on("error", reject);
-            }).on("error", reject);
+                out.on("error", fail);
+            });
+            req.on("error", reject);
+            req.setTimeout(DOWNLOAD_IDLE_TIMEOUT_MS, () => {
+                req.destroy(new Error(`download timed out (no data for ${DOWNLOAD_IDLE_TIMEOUT_MS}ms) for ${u}`));
+            });
         };
         process.stderr.write(`[chromiumfish] downloading ${url}\n`);
         get(url);
@@ -96,20 +124,27 @@ function download(url, dest) {
 }
 function fetchText(url) {
     return new Promise((resolve, reject) => {
-        const get = (u) => https.get(u, (res) => {
-            if (res.statusCode && res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
-                res.resume();
-                return get(res.headers.location);
-            }
-            if (res.statusCode !== 200) {
-                res.resume();
-                return reject(new Error(`HTTP ${res.statusCode}`));
-            }
-            let data = "";
-            res.setEncoding("utf8");
-            res.on("data", (c) => (data += c));
-            res.on("end", () => resolve(data));
-        }).on("error", reject);
+        const get = (u) => {
+            const req = https.get(u, (res) => {
+                if (res.statusCode && res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+                    res.resume();
+                    return get(res.headers.location);
+                }
+                if (res.statusCode !== 200) {
+                    res.resume();
+                    return reject(new Error(`HTTP ${res.statusCode}`));
+                }
+                let data = "";
+                res.setEncoding("utf8");
+                res.on("data", (c) => (data += c));
+                res.on("end", () => resolve(data));
+                res.on("error", reject);
+            });
+            req.on("error", reject);
+            req.setTimeout(FETCH_IDLE_TIMEOUT_MS, () => {
+                req.destroy(new Error(`request timed out for ${u}`));
+            });
+        };
         get(url);
     });
 }

package/dist/ip2tz.js

@@ -18,10 +18,12 @@
  */
 import { createHash } from "node:crypto";
 import * as fs from "node:fs";
+import * as http from "node:http";
 import * as https from "node:https";
 import * as path from "node:path";
+import * as tls from "node:tls";
 import { cacheRoot } from "./fetch.js";
-import { GEOIP_FALLBACK_VERSION, geoipBaseUrl, geoipLatestManifestUrl, geoipVersion } from "./version.js";
+import { assertSafeVersion, GEOIP_FALLBACK_VERSION, geoipBaseUrl, geoipLatestManifestUrl, geoipVersion, } from "./version.js";
 const MAGIC = Buffer.from("IP2TZ\x01", "latin1");
 const V4_REC = 6; // uint32 start + uint16 tz_idx
 const V6_REC = 18; // 16-byte start + uint16 tz_idx
@@ -89,33 +91,42 @@ export async function resolveVersion(version = geoipVersion(), download = true)
     return cached?.version || GEOIP_FALLBACK_VERSION;
 }
 export function assetName(version = geoipVersion()) {
-    return `ip2tz-${resolveVersionSync(version)}.bin`;
+    return `ip2tz-${assertSafeVersion(resolveVersionSync(version))}.bin`;
 }
 export function dbPath(version = geoipVersion()) {
-    return path.join(geoipDir(), `ip2tz-${resolveVersionSync(version)}.bin`);
+    return path.join(geoipDir(), `ip2tz-${assertSafeVersion(resolveVersionSync(version))}.bin`);
 }
+// Idle-timeout (ms) for the geoip manifest / DB / checksum fetches so a
+// stalled server can't hang resolution or download forever.
+const GET_IDLE_TIMEOUT_MS = 30_000;
 function get(url) {
     return new Promise((resolve, reject) => {
-        const go = (u) => https
-            .get(u, (res) => {
-            if (res.statusCode && res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
-                res.resume();
-                return go(res.headers.location);
-            }
-            if (res.statusCode !== 200) {
-                res.resume();
-                return reject(new Error(`HTTP ${res.statusCode}`));
-            }
-            const chunks = [];
-            res.on("data", (c) => chunks.push(c));
-            res.on("end", () => resolve(Buffer.concat(chunks)));
-        })
-            .on("error", reject);
+        const go = (u) => {
+            const req = https
+                .get(u, (res) => {
+                if (res.statusCode && res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+                    res.resume();
+                    return go(res.headers.location);
+                }
+                if (res.statusCode !== 200) {
+                    res.resume();
+                    return reject(new Error(`HTTP ${res.statusCode}`));
+                }
+                const chunks = [];
+                res.on("data", (c) => chunks.push(c));
+                res.on("end", () => resolve(Buffer.concat(chunks)));
+                res.on("error", reject);
+            })
+                .on("error", reject);
+            req.setTimeout(GET_IDLE_TIMEOUT_MS, () => {
+                req.destroy(new Error(`request timed out for ${u}`));
+            });
+        };
         go(url);
     });
 }
 export async function fetchDb(version = geoipVersion(), force = false) {
-    const v = await resolveVersion(version); // concrete, e.g. "2026.06"
+    const v = assertSafeVersion(await resolveVersion(version)); // concrete, e.g. "2026.06"
     const dest = path.join(geoipDir(), `ip2tz-${v}.bin`);
     if (fs.existsSync(dest) && !force)
         return dest;
@@ -256,28 +267,29 @@ function parseV6(ip) {
     }
     return b;
 }
-let cached = null;
+// Keyed by *resolved* concrete version so a later lookup with a different
+// version doesn't silently reuse the first DB loaded.
+const cache = new Map();
 async function getDb(version = geoipVersion(), download = true) {
-    if (cached)
-        return cached;
-    const v = await resolveVersion(version, download);
+    const v = assertSafeVersion(await resolveVersion(version, download));
+    const existing = cache.get(v);
+    if (existing)
+        return existing;
     let p = path.join(geoipDir(), `ip2tz-${v}.bin`);
     if (!fs.existsSync(p)) {
         if (!download)
             throw new Error("ip2tz DB not installed. Call fetchDb().");
         p = await fetchDb(v);
     }
-    cached = Ip2TzDB.load(p);
-    return cached;
+    const db = Ip2TzDB.load(p);
+    cache.set(v, db);
+    return db;
 }
 export async function lookupTimezone(ip, version = geoipVersion(), download = true) {
     return (await getDb(version, download)).lookup(ip);
 }
-export function egressIp(proxy, timeoutMs = 8000) {
-    // Note: proxy support for the probe would require an https-proxy agent; when
-    // a proxy is configured we currently probe direct and rely on the caller to
-    // pass an explicit IP if egress differs.
-    void proxy;
+/** Probe the egress IP directly (no proxy). */
+function egressDirect(timeoutMs) {
     return new Promise((resolve) => {
         const req = https.get(EGRESS_PROBE, { headers: { "User-Agent": "chromiumfish" } }, (res) => {
             let data = "";
@@ -299,6 +311,101 @@ export function egressIp(proxy, timeoutMs = 8000) {
         });
     });
 }
+/**
+ * Probe the egress IP *through an HTTP(S) proxy* by CONNECT-tunnelling to the
+ * probe host, so the resolved timezone matches the proxy's exit — the whole
+ * point of timezone:"auto". Mirrors what the Python SDK gets from urllib's
+ * ProxyHandler. Returns null on any failure (never falls back to a direct
+ * probe, which would report the machine's real-IP timezone).
+ */
+function egressViaProxy(proxy, timeoutMs) {
+    return new Promise((resolve) => {
+        let pu;
+        let tu;
+        try {
+            pu = new URL(proxy);
+            tu = new URL(EGRESS_PROBE);
+        }
+        catch {
+            return resolve(null);
+        }
+        let settled = false;
+        const done = (ip) => {
+            if (!settled) {
+                settled = true;
+                resolve(ip);
+            }
+        };
+        const headers = {};
+        if (pu.username) {
+            const creds = `${decodeURIComponent(pu.username)}:${decodeURIComponent(pu.password)}`;
+            headers["Proxy-Authorization"] = "Basic " + Buffer.from(creds).toString("base64");
+        }
+        const connectReq = http.request({
+            host: pu.hostname,
+            port: Number(pu.port) || (pu.protocol === "https:" ? 443 : 80),
+            method: "CONNECT",
+            path: `${tu.hostname}:443`,
+            headers,
+            timeout: timeoutMs,
+        });
+        connectReq.on("connect", (res, socket) => {
+            if (res.statusCode !== 200) {
+                socket.destroy();
+                return done(null);
+            }
+            const tlsSock = tls.connect({ socket, servername: tu.hostname }, () => {
+                // HTTP/1.0 so the response isn't chunk-encoded (simpler to parse).
+                tlsSock.write(`GET ${tu.pathname} HTTP/1.0\r\nHost: ${tu.hostname}\r\n` +
+                    `User-Agent: chromiumfish\r\nAccept: application/json\r\nConnection: close\r\n\r\n`);
+            });
+            let raw = "";
+            tlsSock.setEncoding("utf8");
+            tlsSock.setTimeout(timeoutMs, () => {
+                tlsSock.destroy();
+                done(null);
+            });
+            tlsSock.on("data", (d) => (raw += d));
+            tlsSock.on("end", () => {
+                const body = raw.split("\r\n\r\n").slice(1).join("\r\n\r\n");
+                const m = body.match(/\{[\s\S]*\}/);
+                try {
+                    done(m ? JSON.parse(m[0]).ip || null : null);
+                }
+                catch {
+                    done(null);
+                }
+            });
+            tlsSock.on("error", () => done(null));
+        });
+        connectReq.on("error", () => done(null));
+        connectReq.on("timeout", () => {
+            connectReq.destroy();
+            done(null);
+        });
+        connectReq.end();
+    });
+}
+export function egressIp(proxy, timeoutMs = 8000) {
+    if (proxy) {
+        let scheme = "";
+        try {
+            scheme = new URL(proxy).protocol;
+        }
+        catch {
+            /* invalid proxy URL */
+        }
+        if (scheme === "http:" || scheme === "https:")
+            return egressViaProxy(proxy, timeoutMs);
+        // SOCKS / unknown schemes aren't supported for the probe. Return null
+        // (leave the timezone unset) rather than probing the direct connection
+        // and reporting the machine's real-IP timezone — the incoherence we want
+        // to avoid.
+        process.stderr.write(`[chromiumfish] egress probe: unsupported proxy scheme '${scheme || proxy}'; skipping timezone resolution\n`);
+        return Promise.resolve(null);
+    }
+    return egressDirect(timeoutMs);
+}
 export async function resolveTimezone(opts = {}) {
     const { proxy, version = geoipVersion(), download = true } = opts;
     let ip = opts.ip;

package/dist/launcher.d.ts

@@ -6,8 +6,8 @@ import { type Browser, type LaunchOptions } from "playwright-core";
  */
 export declare const BASE_ARGS: string[];
 export interface ChromiumFishOptions extends Omit<LaunchOptions, "executablePath"> {
-    /** Integer seed for a stable, internally-consistent fingerprint persona. */
-    personaSeed?: number;
+    /** String id for a stable, internally-consistent fingerprint persona. */
+    personaSeed?: string;
     /** Run headless (SwiftShader). Defaults to true. */
     headless?: boolean;
     /** Window dimensions; defaults to [1920, 1080]. Pass null to omit. */
@@ -28,6 +28,6 @@ export declare function buildArgs(opts: ChromiumFishOptions): string[];
  * Launch ChromiumFish and return a standard Playwright `Browser`.
  *
  *   import { ChromiumFish } from "chromiumfish";
- *   const browser = await ChromiumFish({ personaSeed: 27182, headless: true });
+ *   const browser = await ChromiumFish({ personaSeed: "alpha-7", headless: true });
  */
 export declare function ChromiumFish(opts?: ChromiumFishOptions): Promise<Browser>;

package/dist/launcher.js

@@ -20,8 +20,12 @@ function proxyToUrl(proxy) {
         return undefined;
     const { server, username, password } = proxy;
     if (username && server.includes("://")) {
-        const [scheme, host] = server.split("://", 2);
-        return `${scheme}://${username}:${password ?? ""}@${host}`;
+        const idx = server.indexOf("://");
+        const scheme = server.slice(0, idx);
+        const host = server.slice(idx + 3);
+        // Percent-encode credentials so a password containing ':' / '@' / '/'
+        // can't corrupt the URL; the egress probe decodes them again.
+        return `${scheme}://${encodeURIComponent(username)}:${encodeURIComponent(password ?? "")}@${host}`;
     }
     return server;
 }
@@ -40,7 +44,7 @@ export function buildArgs(opts) {
  * Launch ChromiumFish and return a standard Playwright `Browser`.
  *
  *   import { ChromiumFish } from "chromiumfish";
- *   const browser = await ChromiumFish({ personaSeed: 27182, headless: true });
+ *   const browser = await ChromiumFish({ personaSeed: "alpha-7", headless: true });
  */
 export async function ChromiumFish(opts = {}) {
     const { personaSeed, headless = true, windowSize, version, download = true, timezone, args, ...launch } = opts;

package/dist/version.d.ts

@@ -6,7 +6,7 @@
  * SDK downloads by default; override it with `CHROMIUMFISH_VERSION`.
  */
 /** SDK package version (kept in sync with package.json). */
-export declare const SDK_VERSION = "0.1.3";
+export declare const SDK_VERSION = "0.1.4";
 /** Default ChromiumFish browser build to fetch. Matches src/chrome/VERSION. */
 export declare const DEFAULT_BROWSER_VERSION = "150.0.7844";
 /** Public repo hosting the release assets. */
@@ -26,6 +26,14 @@ export declare const DEFAULT_GEOIP_VERSION = "latest";
  * pointer). Bump occasionally so the offline floor stays recent.
  */
 export declare const GEOIP_FALLBACK_VERSION = "2026.06";
+/**
+ * Reject version strings that aren't a plain build tag. Versions are
+ * interpolated into filesystem cache paths and release URLs, so a crafted
+ * value like `../../../etc` would escape the cache dir (path traversal).
+ * Real tags are digits, dots, and hyphens (e.g. "150.0.7844", "2026.06",
+ * "latest").
+ */
+export declare function assertSafeVersion(version: string): string;
 export declare function browserVersion(): string;
 export declare function releaseBaseUrl(version?: string): string;
 export declare function geoipVersion(): string;

package/dist/version.js

@@ -6,7 +6,7 @@
  * SDK downloads by default; override it with `CHROMIUMFISH_VERSION`.
  */
 /** SDK package version (kept in sync with package.json). */
-export const SDK_VERSION = "0.1.3";
+export const SDK_VERSION = "0.1.4";
 /** Default ChromiumFish browser build to fetch. Matches src/chrome/VERSION. */
 export const DEFAULT_BROWSER_VERSION = "150.0.7844";
 /** Public repo hosting the release assets. */
@@ -26,14 +26,27 @@ export const DEFAULT_GEOIP_VERSION = "latest";
  * pointer). Bump occasionally so the offline floor stays recent.
  */
 export const GEOIP_FALLBACK_VERSION = "2026.06";
+/**
+ * Reject version strings that aren't a plain build tag. Versions are
+ * interpolated into filesystem cache paths and release URLs, so a crafted
+ * value like `../../../etc` would escape the cache dir (path traversal).
+ * Real tags are digits, dots, and hyphens (e.g. "150.0.7844", "2026.06",
+ * "latest").
+ */
+export function assertSafeVersion(version) {
+    if (!/^[A-Za-z0-9._-]+$/.test(version) || version === "." || version === "..") {
+        throw new Error(`invalid version string: ${JSON.stringify(version)}`);
+    }
+    return version;
+}
 export function browserVersion() {
-    return process.env.CHROMIUMFISH_VERSION || DEFAULT_BROWSER_VERSION;
+    return assertSafeVersion(process.env.CHROMIUMFISH_VERSION || DEFAULT_BROWSER_VERSION);
 }
 export function releaseBaseUrl(version = browserVersion()) {
     return `https://github.com/${RELEASE_REPO}/releases/download/v${version}`;
 }
 export function geoipVersion() {
-    return process.env.CHROMIUMFISH_GEOIP_VERSION || DEFAULT_GEOIP_VERSION;
+    return assertSafeVersion(process.env.CHROMIUMFISH_GEOIP_VERSION || DEFAULT_GEOIP_VERSION);
 }
 export function geoipBaseUrl(version = geoipVersion()) {
     return `https://github.com/${RELEASE_REPO}/releases/download/geoip-${version}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chromiumfish",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Stealth Chromium build with a drop-in Playwright harness — fetches and launches the ChromiumFish browser.",
   "type": "module",
   "main": "./dist/index.js",