headfox-js 0.1.1

package/dist/exceptions.d.ts

@@ -0,0 +1,82 @@
+export declare class UnsupportedVersion extends Error {
+    constructor(message?: string);
+}
+export declare class MissingRelease extends Error {
+    constructor(message?: string);
+}
+export declare class UnsupportedArchitecture extends Error {
+    constructor(message?: string);
+}
+export declare class UnsupportedOS extends Error {
+    constructor(message?: string);
+}
+export declare class UnknownProperty extends Error {
+    constructor(message?: string);
+}
+export declare class InvalidPropertyType extends Error {
+    constructor(message?: string);
+}
+export declare class InvalidAddonPath extends Error {
+    constructor(message?: string);
+}
+export declare class InvalidDebugPort extends Error {
+    constructor(message?: string);
+}
+export declare class MissingDebugPort extends Error {
+    constructor(message?: string);
+}
+export declare class LocaleError extends Error {
+    constructor(message: string);
+}
+export declare class InvalidIP extends Error {
+    constructor(message?: string);
+}
+export declare class InvalidProxy extends Error {
+    constructor(message?: string);
+}
+export declare class UnknownIPLocation extends LocaleError {
+    constructor(message?: string);
+}
+export declare class InvalidLocale extends LocaleError {
+    constructor(message?: string);
+    static invalidInput(locale: string): InvalidLocale;
+}
+export declare class UnknownTerritory extends InvalidLocale {
+    constructor(message?: string);
+}
+export declare class UnknownLanguage extends InvalidLocale {
+    constructor(message?: string);
+}
+export declare class NotInstalledGeoIPExtra extends Error {
+    constructor(message?: string);
+}
+export declare class NonFirefoxFingerprint extends Error {
+    constructor(message?: string);
+}
+export declare class InvalidOS extends Error {
+    constructor(message?: string);
+}
+export declare class VirtualDisplayError extends Error {
+    constructor(message?: string);
+}
+export declare class CannotFindXvfb extends VirtualDisplayError {
+    constructor(message?: string);
+}
+export declare class CannotExecuteXvfb extends VirtualDisplayError {
+    constructor(message?: string);
+}
+export declare class VirtualDisplayNotSupported extends VirtualDisplayError {
+    constructor(message?: string);
+}
+export declare class HeadfoxNotInstalled extends Error {
+    constructor(message?: string);
+}
+export declare class WebGLFingerprintUnavailable extends Error {
+    constructor(message?: string, options?: ErrorOptions);
+}
+export declare class CamoufoxNotInstalled extends HeadfoxNotInstalled {
+    constructor(message?: string);
+}
+export declare class FileNotFoundError extends Error {
+    constructor(message?: string);
+}

package/dist/exceptions.js

@@ -0,0 +1,165 @@
+export class UnsupportedVersion extends Error {
+    constructor(message) {
+        super(message ?? "The Headfox executable is outdated.");
+        this.name = "UnsupportedVersion";
+    }
+}
+export class MissingRelease extends Error {
+    constructor(message) {
+        super(message ?? "A required GitHub release asset is missing.");
+        this.name = "MissingRelease";
+    }
+}
+export class UnsupportedArchitecture extends Error {
+    constructor(message) {
+        super(message ?? "The architecture is not supported.");
+        this.name = "UnsupportedArchitecture";
+    }
+}
+export class UnsupportedOS extends Error {
+    constructor(message) {
+        super(message ?? "The OS is not supported.");
+        this.name = "UnsupportedOS";
+    }
+}
+export class UnknownProperty extends Error {
+    constructor(message) {
+        super(message ?? "The property is unknown.");
+        this.name = "UnknownProperty";
+    }
+}
+export class InvalidPropertyType extends Error {
+    constructor(message) {
+        super(message ?? "The property type is invalid.");
+        this.name = "InvalidPropertyType";
+    }
+}
+export class InvalidAddonPath extends Error {
+    constructor(message) {
+        super(message ?? "The addon path is invalid.");
+        this.name = "InvalidAddonPath";
+    }
+}
+export class InvalidDebugPort extends Error {
+    constructor(message) {
+        super(message ?? "The debug port is invalid.");
+        this.name = "InvalidDebugPort";
+    }
+}
+export class MissingDebugPort extends Error {
+    constructor(message) {
+        super(message ?? "The debug port is missing.");
+        this.name = "MissingDebugPort";
+    }
+}
+export class LocaleError extends Error {
+    constructor(message) {
+        super(message ?? "The locale is invalid.");
+        this.name = "LocaleError";
+    }
+}
+export class InvalidIP extends Error {
+    constructor(message) {
+        super(message ?? "An IP address is invalid.");
+        this.name = "InvalidIP";
+    }
+}
+export class InvalidProxy extends Error {
+    constructor(message) {
+        super(message ?? "A proxy is invalid.");
+        this.name = "InvalidProxy";
+    }
+}
+export class UnknownIPLocation extends LocaleError {
+    constructor(message) {
+        super(message ?? "The location of an IP is unknown.");
+        this.name = "UnknownIPLocation";
+    }
+}
+export class InvalidLocale extends LocaleError {
+    constructor(message) {
+        super(message ?? "The locale input is invalid.");
+        this.name = "InvalidLocale";
+    }
+    static invalidInput(locale) {
+        return new InvalidLocale(`Invalid locale: '${locale}'. Must be either a region, language, language-region, or language-script-region.`);
+    }
+}
+export class UnknownTerritory extends InvalidLocale {
+    constructor(message) {
+        super(message ?? "The territory is unknown.");
+        this.name = "UnknownTerritory";
+    }
+}
+export class UnknownLanguage extends InvalidLocale {
+    constructor(message) {
+        super(message ?? "The language is unknown.");
+        this.name = "UnknownLanguage";
+    }
+}
+export class NotInstalledGeoIPExtra extends Error {
+    constructor(message) {
+        super(message ?? "The geoip2 module is not installed.");
+        this.name = "NotInstalledGeoIPExtra";
+    }
+}
+export class NonFirefoxFingerprint extends Error {
+    constructor(message) {
+        super(message ?? "A passed Browserforge fingerprint is invalid.");
+        this.name = "NonFirefoxFingerprint";
+    }
+}
+export class InvalidOS extends Error {
+    constructor(message) {
+        super(message ?? "The target OS is invalid.");
+        this.name = "InvalidOS";
+    }
+}
+export class VirtualDisplayError extends Error {
+    constructor(message) {
+        super(message ?? "There is an error with the virtual display.");
+        this.name = "VirtualDisplayError";
+    }
+}
+export class CannotFindXvfb extends VirtualDisplayError {
+    constructor(message) {
+        super(message ?? "Xvfb cannot be found.");
+        this.name = "CannotFindXvfb";
+    }
+}
+export class CannotExecuteXvfb extends VirtualDisplayError {
+    constructor(message) {
+        super(message ?? "Xvfb cannot be executed.");
+        this.name = "CannotExecuteXvfb";
+    }
+}
+export class VirtualDisplayNotSupported extends VirtualDisplayError {
+    constructor(message) {
+        super(message ?? "The user tried to use a virtual display on a non-Linux OS.");
+        this.name = "VirtualDisplayNotSupported";
+    }
+}
+export class HeadfoxNotInstalled extends Error {
+    constructor(message) {
+        super(message ?? "Headfox is not installed.");
+        this.name = "HeadfoxNotInstalled";
+    }
+}
+export class WebGLFingerprintUnavailable extends Error {
+    constructor(message, options) {
+        super(message ?? "WebGL fingerprint sampling is unavailable in this runtime.", options);
+        this.name = "WebGLFingerprintUnavailable";
+    }
+}
+export class CamoufoxNotInstalled extends HeadfoxNotInstalled {
+    constructor(message) {
+        super(message ?? "Camoufox is not installed.");
+        this.name = "CamoufoxNotInstalled";
+    }
+}
+export class FileNotFoundError extends Error {
+    constructor(message) {
+        super(message ?? "File couldn't be found.");
+        this.name = "FileNotFoundError";
+    }
+}

package/dist/fingerprints.d.ts

@@ -0,0 +1,4 @@
+import { type Fingerprint, type FingerprintGeneratorOptions } from "fingerprint-generator";
+export declare const SUPPORTED_OS: readonly ["linux", "macos", "windows"];
+export declare function fromBrowserforge(fingerprint: Fingerprint, ffVersion?: string): Record<string, any>;
+export declare function generateFingerprint(window?: [number, number], config?: Partial<FingerprintGeneratorOptions>): Fingerprint;

package/dist/fingerprints.js

@@ -0,0 +1,82 @@
+import { FingerprintGenerator, } from "fingerprint-generator";
+import BROWSERFORGE_DATA from "./mappings/browserforge.config.js";
+export const SUPPORTED_OS = ["linux", "macos", "windows"];
+const FP_GENERATOR = new FingerprintGenerator({
+    browsers: ["firefox"],
+    operatingSystems: SUPPORTED_OS,
+});
+function randrange(min, max) {
+    return Math.floor(Math.random() * (max - min + 1)) + min;
+}
+function _castToProperties(camoufoxData, castEnum, bfDict, ffVersion) {
+    for (let [key, data] of Object.entries(bfDict)) {
+        if (!data)
+            continue;
+        const typeKey = castEnum[key];
+        if (!typeKey)
+            continue;
+        if (typeof data === "object" && !Array.isArray(data)) {
+            _castToProperties(camoufoxData, typeKey, data, ffVersion);
+            continue;
+        }
+        if (typeKey.startsWith("screen.") && typeof data === "number" && data < 0) {
+            data = 0;
+        }
+        if (ffVersion && typeof data === "string") {
+            data = data.replaceAll(/(?<!\d)(1[0-9]{2})(\.0)(?!\d)/gi, `${ffVersion}$2`);
+        }
+        camoufoxData[typeKey] = data;
+    }
+}
+function handleScreenXY(camoufoxData, fpScreen) {
+    if ("window.screenY" in camoufoxData)
+        return;
+    const screenX = fpScreen.screenX;
+    if (!screenX) {
+        camoufoxData["window.screenX"] = 0;
+        camoufoxData["window.screenY"] = 0;
+        return;
+    }
+    if (screenX >= -50 && screenX <= 50) {
+        camoufoxData["window.screenY"] = screenX;
+        return;
+    }
+    const screenY = fpScreen.availHeight - fpScreen.outerHeight;
+    if (screenY === 0) {
+        camoufoxData["window.screenY"] = 0;
+    }
+    else if (screenY > 0) {
+        camoufoxData["window.screenY"] = randrange(0, screenY);
+    }
+    else {
+        camoufoxData["window.screenY"] = randrange(screenY, 0);
+    }
+}
+export function fromBrowserforge(fingerprint, ffVersion) {
+    const camoufoxData = {};
+    _castToProperties(camoufoxData, BROWSERFORGE_DATA, { ...fingerprint }, ffVersion);
+    handleScreenXY(camoufoxData, fingerprint.screen);
+    return camoufoxData;
+}
+function handleWindowSize(fp, outerWidth, outerHeight) {
+    const sc = { ...fp.screen, screenY: undefined };
+    sc.screenX += Math.floor((sc.width - outerWidth) / 2);
+    sc.screenY = Math.floor((sc.height - outerHeight) / 2);
+    if (sc.innerWidth) {
+        sc.innerWidth = Math.max(outerWidth - sc.outerWidth + sc.innerWidth, 0);
+    }
+    if (sc.innerHeight) {
+        sc.innerHeight = Math.max(outerHeight - sc.outerHeight + sc.innerHeight, 0);
+    }
+    sc.outerWidth = outerWidth;
+    sc.outerHeight = outerHeight;
+    fp.screen = sc;
+}
+export function generateFingerprint(window, config) {
+    if (window) {
+        const { fingerprint } = FP_GENERATOR.getFingerprint(config);
+        handleWindowSize(fingerprint, window[0], window[1]);
+        return fingerprint;
+    }
+    return FP_GENERATOR.getFingerprint(config).fingerprint;
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { CamoufoxFetcher, camoufoxPath, ensureBrowserInstalled, getInstalledBrowserDir, HeadfoxFetcher, headfoxPath, installedVerStr, isBrowserInstalled, launchPath, } from "./pkgman.js";
+export { launchHeadfoxServer, launchServer } from "./server.js";
+export { Camoufox, Headfox, launchWithHeadfox, NewBrowser, } from "./sync_api.js";
+export { type LaunchOptions, launchOptions } from "./utils.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+export { CamoufoxFetcher, camoufoxPath, ensureBrowserInstalled, getInstalledBrowserDir, HeadfoxFetcher, headfoxPath, installedVerStr, isBrowserInstalled, launchPath, } from "./pkgman.js";
+export { launchHeadfoxServer, launchServer } from "./server.js";
+export { Camoufox, Headfox, launchWithHeadfox, NewBrowser, } from "./sync_api.js";
+export { launchOptions } from "./utils.js";

package/dist/ip.d.ts

@@ -0,0 +1,25 @@
+export declare class InvalidIP extends Error {
+}
+export declare class InvalidProxy extends Error {
+}
+export interface Proxy {
+    server: string;
+    username?: string;
+    password?: string;
+    bypass?: string;
+}
+export declare const ProxyHelper: {
+    readonly parseServer: (server: string) => {
+        schema: string;
+        url: string;
+        port?: string;
+    };
+    readonly asString: (proxy: Proxy) => string;
+    readonly asAxiosProxy: (proxyString: string) => {
+        [key: string]: string;
+    };
+};
+export declare function validIPv4(ip: string | false): boolean;
+export declare function validIPv6(ip: string | false): boolean;
+export declare function validateIP(ip: string): void;
+export declare function publicIP(proxy?: string): Promise<string>;

package/dist/ip.js

@@ -0,0 +1,90 @@
+import { Impit } from "impit";
+export class InvalidIP extends Error {
+}
+export class InvalidProxy extends Error {
+}
+export const ProxyHelper = {
+    parseServer(server) {
+        const proxyMatch = server.match(/^(?:(\w+):\/\/)?(.*?)(?::(\d+))?$/);
+        if (!proxyMatch) {
+            throw new InvalidProxy(`Invalid proxy server: ${server}`);
+        }
+        return {
+            schema: proxyMatch[1] || "http",
+            url: proxyMatch[2],
+            port: proxyMatch[3],
+        };
+    },
+    asString(proxy) {
+        const { schema, url, port } = ProxyHelper.parseServer(proxy.server);
+        let result = `${schema}://`;
+        if (proxy.username) {
+            result += proxy.username;
+            if (proxy.password) {
+                result += `:${proxy.password}`;
+            }
+            result += "@";
+        }
+        result += url;
+        if (port) {
+            result += `:${port}`;
+        }
+        return result;
+    },
+    asAxiosProxy(proxyString) {
+        return {
+            http: proxyString,
+            https: proxyString,
+        };
+    },
+};
+export function validIPv4(ip) {
+    if (!ip) {
+        return false;
+    }
+    return /^(?:[0-9]{1,3}\.){3}[0-9]{1,3}$/.test(ip);
+}
+export function validIPv6(ip) {
+    if (!ip) {
+        return false;
+    }
+    return /^(([0-9a-fA-F]{0,4}:){1,7}[0-9a-fA-F]{0,4})$/.test(ip);
+}
+export function validateIP(ip) {
+    if (!validIPv4(ip) && !validIPv6(ip)) {
+        throw new InvalidIP(`Invalid IP address: ${ip}`);
+    }
+}
+export async function publicIP(proxy) {
+    const URLS = [
+        "https://api.ipify.org",
+        "https://checkip.amazonaws.com",
+        "https://ipinfo.io/ip",
+        "https://icanhazip.com",
+        "https://ifconfig.co/ip",
+        "https://ipecho.net/plain",
+    ];
+    const errors = [];
+    for (const url of URLS) {
+        try {
+            const impit = new Impit({
+                proxyUrl: proxy,
+                timeout: 5000,
+            });
+            const response = await impit.fetch(url);
+            if (!response.ok) {
+                continue;
+            }
+            const ip = (await response.text()).trim();
+            validateIP(ip);
+            return ip;
+        }
+        catch (error) {
+            errors.push(error);
+            if (process.env.HEADFOX_DEBUG || process.env.CAMOUFOX_DEBUG) {
+                console.warn(new InvalidProxy(`headfox-js(warn): Failed to fetch public proxy IP from ${url}, retrying with another URL...`, { cause: error }));
+            }
+        }
+    }
+    throw new InvalidIP("Failed to get a public proxy IP address from any API endpoint.", { cause: errors });
+}

package/dist/locale.d.ts

@@ -0,0 +1,26 @@
+export declare const ALLOW_GEOIP = true;
+declare class Locale {
+    language: string;
+    region?: string | undefined;
+    script?: string | undefined;
+    constructor(language: string, region?: string | undefined, script?: string | undefined);
+    asString(): string;
+    asConfig(): Record<string, string>;
+}
+declare class Geolocation {
+    locale: Locale;
+    longitude: number;
+    latitude: number;
+    timezone: string;
+    accuracy?: number | undefined;
+    constructor(locale: Locale, longitude: number, latitude: number, timezone: string, accuracy?: number | undefined);
+    asConfig(): Record<string, any>;
+}
+export declare function normalizeLocale(locale: string): Locale;
+export declare function handleLocale(locale: string, ignoreRegion?: boolean): Locale;
+export declare function handleLocales(locales: string | string[], config: Record<string, any>): void;
+export declare function geoipAllowed(): void;
+export declare function downloadMMDB(): Promise<void>;
+export declare function removeMMDB(): void;
+export declare function getGeolocation(ip: string): Promise<Geolocation>;
+export {};