headfox-js 0.1.1

package/dist/virtdisplay.js

@@ -0,0 +1,123 @@
+import { execFileSync, spawn } from "node:child_process";
+import { randomInt } from "node:crypto";
+import { existsSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { globSync } from "glob";
+import { CannotExecuteXvfb, CannotFindXvfb, VirtualDisplayNotSupported, } from "./exceptions.js";
+import { OS_NAME } from "./pkgman.js";
+export class VirtualDisplay {
+    debug;
+    proc = null;
+    _display = null;
+    // private _lock = new Lock();
+    constructor(debug = false) {
+        this.debug = debug;
+    }
+    get xvfb_args() {
+        return [
+            "-screen",
+            "0",
+            "1x1x24",
+            "-ac",
+            "-nolisten",
+            "tcp",
+            "-extension",
+            "RENDER",
+            "+extension",
+            "GLX",
+            "-extension",
+            "COMPOSITE",
+            "-extension",
+            "XVideo",
+            "-extension",
+            "XVideo-MotionCompensation",
+            "-extension",
+            "XINERAMA",
+            "-shmem",
+            "-fp",
+            "built-ins",
+            "-nocursor",
+            "-br",
+        ];
+    }
+    get xvfb_path() {
+        const path = execFileSync("which", ["Xvfb"]).toString().trim();
+        if (!path) {
+            throw new CannotFindXvfb("Please install Xvfb to use headless mode.");
+        }
+        if (!existsSync(path) || !execFileSync("test", ["-x", path])) {
+            throw new CannotExecuteXvfb(`I do not have permission to execute Xvfb: ${path}`);
+        }
+        return path;
+    }
+    get xvfb_cmd() {
+        return [this.xvfb_path, `:${this.display}`, ...this.xvfb_args];
+    }
+    execute_xvfb() {
+        if (this.debug) {
+            console.log("Starting virtual display:", this.xvfb_cmd.join(" "));
+        }
+        this.proc = spawn(this.xvfb_cmd[0], this.xvfb_cmd.slice(1), {
+            stdio: this.debug ? "inherit" : "ignore",
+            detached: true,
+        });
+    }
+    get() {
+        VirtualDisplay.assert_linux();
+        // this._lock.runExclusive(() => {
+        if (!this.proc) {
+            this.execute_xvfb();
+        }
+        else if (this.debug) {
+            console.log(`Using virtual display: ${this.display}`);
+        }
+        // });
+        return `:${this.display}`;
+    }
+    kill() {
+        // this._lock.runExclusive(() => {
+        if (this.proc && !this.proc.killed) {
+            if (this.debug) {
+                console.log("Terminating virtual display:", this.display);
+            }
+            this.proc.kill();
+        }
+        // });
+    }
+    /**
+     * Get list of lock files in /tmp
+     * @returns List of lock file paths
+     */
+    static _get_lock_files() {
+        const tmpd = process.env.TMPDIR || tmpdir();
+        try {
+            return globSync(path.join(tmpd, ".X*-lock")).filter((p) => {
+                try {
+                    return statSync(p).isFile();
+                }
+                catch {
+                    return false;
+                }
+            });
+        }
+        catch {
+            return [];
+        }
+    }
+    static _free_display() {
+        const ls = VirtualDisplay._get_lock_files().map((x) => parseInt(x.split("X")[1].split("-")[0], 10));
+        return ls.length ? Math.max(99, Math.max(...ls) + randomInt(3, 20)) : 99;
+    }
+    get display() {
+        if (this._display === null) {
+            this._display = VirtualDisplay._free_display();
+        }
+        return this._display;
+    }
+    static assert_linux() {
+        if (OS_NAME !== "lin") {
+            throw new VirtualDisplayNotSupported("Virtual display is only supported on Linux.");
+        }
+    }
+}

package/dist/warnings.d.ts

@@ -0,0 +1,4 @@
+export declare class LeakWarning extends Error {
+    constructor(message: string);
+    static warn(warningKey: string, iKnowWhatImDoing?: boolean): void;
+}

package/dist/warnings.js

@@ -0,0 +1,33 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import WARNINGS_DATA from "./mappings/warnings.config.js";
+const currentDir = import.meta.dirname ?? path.dirname(fileURLToPath(import.meta.url));
+export class LeakWarning extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "LeakWarning";
+    }
+    static warn(warningKey, iKnowWhatImDoing) {
+        let warning = WARNINGS_DATA[warningKey];
+        if (iKnowWhatImDoing) {
+            return;
+        }
+        if (iKnowWhatImDoing !== undefined) {
+            warning += "\nIf this is intentional, pass `iKnowWhatImDoing=true`.";
+        }
+        const currentModule = currentDir;
+        const originalStackTrace = Error.prepareStackTrace;
+        Error.prepareStackTrace = (_, stack) => stack;
+        const err = new Error();
+        const stack = err.stack;
+        Error.prepareStackTrace = originalStackTrace;
+        for (const frame of stack) {
+            const frameFileName = frame.getFileName();
+            if (frameFileName && !frameFileName.startsWith(currentModule)) {
+                console.warn(`${warning} at ${frameFileName}:${frame.getLineNumber()}`);
+                return;
+            }
+        }
+        console.warn(warning);
+    }
+}

package/dist/webgl/sample.d.ts

@@ -0,0 +1,19 @@
+interface WebGLData {
+    vendor: string;
+    renderer: string;
+    data: string;
+    win: number;
+    mac: number;
+    lin: number;
+    webGl2Enabled: boolean;
+}
+export declare function sampleWebGL(os: "win" | "mac" | "lin", vendor?: string, renderer?: string): Promise<WebGLData>;
+interface VendorRenderer {
+    vendor: string;
+    renderer: string;
+}
+interface PossiblePairs {
+    [key: string]: Array<VendorRenderer>;
+}
+export declare function getPossiblePairs(): Promise<PossiblePairs>;
+export {};

package/dist/webgl/sample.js

@@ -0,0 +1,121 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { WebGLFingerprintUnavailable } from "../exceptions.js";
+import { OS_ARCH_MATRIX } from "../pkgman.js";
+// Cached Database constructor - loaded lazily on first use
+let DatabaseConstructor = null;
+/**
+ * Opens a SQLite database using the appropriate driver for the runtime.
+ * Uses bun:sqlite in Bun, better-sqlite3 in Node.js.
+ * The Database constructor is cached after first load.
+ */
+async function openDatabase(pathName) {
+    try {
+        if (!DatabaseConstructor) {
+            if (typeof Bun !== "undefined") {
+                // @ts-expect-error - bun:sqlite only exists in Bun runtime
+                const { Database: BunDatabase } = await import("bun:sqlite");
+                DatabaseConstructor = BunDatabase;
+            }
+            else {
+                const { default: NodeDatabase } = await import("better-sqlite3");
+                DatabaseConstructor = NodeDatabase;
+            }
+        }
+        if (!DatabaseConstructor) {
+            throw new Error("No SQLite database constructor is available.");
+        }
+        return new DatabaseConstructor(pathName);
+    }
+    catch (error) {
+        throw new WebGLFingerprintUnavailable("WebGL fingerprint sampling data could not be loaded. Install optional SQLite support or continue with WebGL disabled.", { cause: error });
+    }
+}
+// Get database path relative to this file
+const currentDir = import.meta.dirname ?? path.dirname(fileURLToPath(import.meta.url));
+const DB_PATH = path.join(currentDir, "..", "data-files", "webgl_data.db");
+export async function sampleWebGL(os, vendor, renderer) {
+    if (!OS_ARCH_MATRIX[os]) {
+        throw new Error(`Invalid OS: ${os}. Must be one of: win, mac, lin`);
+    }
+    const db = await openDatabase(DB_PATH);
+    let query = "";
+    let params = [];
+    if (vendor && renderer) {
+        query = `SELECT vendor, renderer, data, ${os} FROM webgl_fingerprints WHERE vendor = ? AND renderer = ?`;
+        params = [vendor, renderer];
+    }
+    else {
+        query = `SELECT vendor, renderer, data, ${os} FROM webgl_fingerprints WHERE ${os} > 0`;
+    }
+    return new Promise((resolve, reject) => {
+        try {
+            const rows = db.prepare(query).all(...params);
+            if (rows.length === 0) {
+                reject(new Error(`No WebGL data found for OS: ${os}`));
+                return;
+            }
+            if (vendor && renderer) {
+                const result = rows[0];
+                if (!result) {
+                    reject(new Error(`No WebGL data found for OS: ${os}`));
+                    return;
+                }
+                const osWeight = result[os];
+                if (osWeight === undefined || osWeight <= 0) {
+                    const pairs = db
+                        .prepare(`SELECT DISTINCT vendor, renderer FROM webgl_fingerprints WHERE ${os} > 0`)
+                        .all();
+                    reject(new Error(`Vendor "${vendor}" and renderer "${renderer}" combination not valid for ${os}. Possible pairs: ${pairs.map((pair) => `${pair.vendor}, ${pair.renderer}`).join(", ")}`));
+                    return;
+                }
+                resolve(JSON.parse(result.data));
+            }
+            else {
+                const dataStrs = rows.map((row) => row.data);
+                const probs = rows.map((row) => row[os]);
+                const probsArray = probs.map((p) => p / probs.reduce((a, b) => a + b, 0));
+                function weightedRandomChoice(weights) {
+                    const sum = weights.reduce((acc, weight) => acc + weight, 0);
+                    const threshold = Math.random() * sum;
+                    let cumulativeSum = 0;
+                    for (let i = 0; i < weights.length; i++) {
+                        cumulativeSum += weights[i];
+                        if (cumulativeSum >= threshold) {
+                            return i;
+                        }
+                    }
+                    return weights.length - 1; // Fallback in case of rounding errors
+                }
+                const idx = weightedRandomChoice(probsArray);
+                resolve(JSON.parse(dataStrs[idx]));
+            }
+        }
+        catch (err) {
+            reject(err);
+        }
+    }).finally(() => {
+        db.close();
+    });
+}
+export async function getPossiblePairs() {
+    const db = await openDatabase(DB_PATH);
+    const result = {};
+    return new Promise((resolve, reject) => {
+        try {
+            const osTypes = Object.keys(OS_ARCH_MATRIX);
+            osTypes.forEach((os_type) => {
+                const rows = db
+                    .prepare(`SELECT DISTINCT vendor, renderer FROM webgl_fingerprints WHERE ${os_type} > 0 ORDER BY ${os_type} DESC`)
+                    .all();
+                result[os_type] = rows;
+            });
+            resolve(result);
+        }
+        catch (err) {
+            reject(err);
+        }
+    }).finally(() => {
+        db.close();
+    });
+}

package/package.json

@@ -0,0 +1,94 @@
+{
+	"name": "headfox-js",
+	"version": "0.1.1",
+	"description": "TypeScript launcher and Playwright tooling for Headfox, currently powered by Camoufox-compatible browser bundles.",
+	"license": "MPL-2.0",
+	"type": "module",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		},
+		"./package.json": "./package.json"
+	},
+	"bin": {
+		"headfox-js": "./bin/headfox-js.mjs",
+		"camoufox-js": "./bin/headfox-js.mjs"
+	},
+	"files": [
+		"dist",
+		"bin",
+		"README.md",
+		"LICENSE.md"
+	],
+	"keywords": [
+		"headfox",
+		"firefox",
+		"camoufox",
+		"camoufox-js",
+		"playwright",
+		"fingerprinting",
+		"browser-automation",
+		"headlessx"
+	],
+	"author": "saifyxpro (https://saify.me)",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/saifyxpro/HeadlessX.git",
+		"directory": "packages/headfox-js"
+	},
+	"bugs": {
+		"url": "https://github.com/saifyxpro/HeadlessX/issues"
+	},
+	"homepage": "https://github.com/saifyxpro/HeadlessX/tree/develop/packages/headfox-js",
+	"engines": {
+		"node": ">=20"
+	},
+	"packageManager": "pnpm@10.32.1",
+	"publishConfig": {
+		"access": "public"
+	},
+	"scripts": {
+		"clean": "rimraf dist",
+		"copy-files": "node ./copy-data-files.mjs",
+		"build": "pnpm run clean && tsc -p tsconfig.json && pnpm run copy-files",
+		"check": "biome check .",
+		"prepack": "pnpm run build",
+		"typecheck": "tsc -p tsconfig.json --noEmit",
+		"test": "vitest"
+	},
+	"dependencies": {
+		"adm-zip": "^0.5.16",
+		"cli-progress": "^3.12.0",
+		"commander": "^14.0.0",
+		"fingerprint-generator": "^2.1.66",
+		"glob": "^13.0.0",
+		"impit": "^0.11.0",
+		"language-tags": "^2.0.1",
+		"maxmind": "^5.0.0",
+		"pretty-bytes": "^7.1.0",
+		"ua-parser-js": "^2.0.2",
+		"xml2js": "^0.6.2"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "2.4.7",
+		"@types/adm-zip": "^0.5.7",
+		"@types/better-sqlite3": "^7.6.13",
+		"@types/cli-progress": "^3.11.6",
+		"@types/language-tags": "^1.0.4",
+		"@types/node": "^24.0.0",
+		"@types/xml2js": "^0.4.14",
+		"playwright-core": "^1.58.2",
+		"rimraf": "^6.0.1",
+		"typescript": "^5.8.3",
+		"vitest": "^4.0.0"
+	},
+	"optionalDependencies": {
+		"better-sqlite3": "^12.2.0"
+	},
+	"peerDependencies": {
+		"playwright-core": ">=1.53.0"
+	}
+}