@hieutran094/camoufox-js 0.6.2

package/dist/data-files/warnings.yml

@@ -0,0 +1,51 @@
+navigator: >-
+    Manually setting navigator properties is not recommended.
+    Device information is automatically generated within Camoufox
+    based on the provided `os`.
+
+locale: >-
+    Use the `locale` parameter in Camoufox instead of setting the config manually.
+
+geolocation: >-
+    Please use the `geoip` parameter in Camoufox instead of setting your geolocation manually.
+    This can lead to detection if your target geolocation does not match your IP.
+    Pass `geoip=True` or a target IP (ex: geoip='123.45.67.89') to let Camoufox populate this data for you.
+
+header-ua: >-
+    Do not set the header.User-Agent manually. Camoufox will generate a User-Agent for you.
+
+viewport: >-
+    Manually setting screen & window properties is not recommended.
+    Screen dimensions are randomly generated within Camoufox
+    based on the provided screen constraints. See here:
+    https://github.com/daijro/camoufox/tree/main/pythonlib#browserforge-integration.
+
+custom_fingerprint: >-
+    Passing your own fingerprint is not recommended.
+    BrowserForge fingerprints are automatically generated within Camoufox
+    based on the provided `os` and `screen` constraints.
+
+proxy_without_geoip: >-
+    When using a proxy, it is heavily recommended that you pass `geoip=True`.
+
+ff_version: >-
+    Spoofing the Firefox version will likely lead to detection.
+    If rotating the Firefox version is absolutely necessary, it would be more advisable to
+    rotate between older versions of Camoufox instead.
+
+no_region: >-
+    Because you did not pass in a locale region, Camoufox will generate one for you.
+    This can cause suspicion if your IP does not match your locale region.
+
+block_webgl: >-
+    Disabling WebGL is not recommended. Many WAFs will check if WebGL is enabled.
+
+block_images: >-
+    Blocking image requests has been reported to cause detection issues on major WAFs.
+
+custom_fonts_only: >-
+    Disabling OS-specific fonts while spoofing your OS will make your browser fingerprint inconsistent.
+    WAFs can detect this mismatch between your claimed OS and available system fonts.
+
+disable_coop: >-
+    Disabling Cross-Origin-Opener-Policy (COOP) handling can potentially be detected by sophisticated WAFs.

package/dist/exceptions.d.ts

@@ -0,0 +1,76 @@
+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 CamoufoxNotInstalled extends Error {
+    constructor(message?: string);
+}
+export declare class FileNotFoundError extends Error {
+    constructor(message?: string);
+}

package/dist/exceptions.js

@@ -0,0 +1,153 @@
+export class UnsupportedVersion extends Error {
+    constructor(message) {
+        super(message ?? "The Camoufox 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 CamoufoxNotInstalled extends Error {
+    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 { Fingerprint, 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,84 @@
+import { join } from 'node:path';
+import { loadYaml } from './pkgman.js';
+import { FingerprintGenerator } from 'fingerprint-generator';
+export const SUPPORTED_OS = ['linux', 'macos', 'windows'];
+const BROWSERFORGE_DATA = loadYaml(join(import.meta.dirname, 'data-files', 'browserforge.yml'));
+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.replace(/(?<!\d)(1[0-9]{2})(\.0)(?!\d)/, `${ffVersion}$2`);
+        }
+        camoufoxData[typeKey] = data;
+    }
+}
+function handleScreenXY(camoufoxData, fpScreen) {
+    if ('window.screenY' in camoufoxData)
+        return;
+    let screenX = fpScreen.screenX;
+    if (!screenX) {
+        camoufoxData['window.screenX'] = 0;
+        camoufoxData['window.screenY'] = 0;
+        return;
+    }
+    if (screenX >= -50 && screenX <= 50) {
+        camoufoxData['window.screenY'] = screenX;
+        return;
+    }
+    let 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,3 @@
+export { Camoufox, NewBrowser } from './sync_api.js';
+export { type LaunchOptions, launchOptions } from './utils.js';
+export { launchServer } from './server.js';

package/dist/index.js

@@ -0,0 +1,3 @@
+export { Camoufox, NewBrowser } from './sync_api.js';
+export { launchOptions } from './utils.js';
+export { launchServer } from './server.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 class ProxyHelper {
+    static parseServer(server: string): {
+        schema: string;
+        url: string;
+        port?: string;
+    };
+    static asString(proxy: Proxy): string;
+    static 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 class ProxyHelper {
+    static 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]
+        };
+    }
+    static asString(proxy) {
+        const { schema, url, port } = this.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;
+    }
+    static 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.CAMOUFOX_DEBUG) {
+                console.warn(new InvalidProxy(`camoufox-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 {};