arn-browser 0.0.2 → 0.0.3

package/dist/mappings/warnings.config.d.ts

@@ -0,0 +1,16 @@
+declare const _default: {
+    navigator: string;
+    locale: string;
+    geolocation: string;
+    "header-ua": string;
+    viewport: string;
+    custom_fingerprint: string;
+    proxy_without_geoip: string;
+    ff_version: string;
+    no_region: string;
+    block_webgl: string;
+    block_images: string;
+    custom_fonts_only: string;
+    disable_coop: string;
+};
+export default _default;

package/dist/mappings/warnings.config.js

@@ -0,0 +1,28 @@
+export default {
+    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/pkgman.d.ts

@@ -0,0 +1,62 @@
+import type { PathLike } from "node:fs";
+import type { Writable } from "node:stream";
+export declare const OS_NAME: "mac" | "win" | "lin";
+export declare const INSTALL_DIR: PathLike;
+export declare const LOCAL_DATA: PathLike;
+export declare const OS_ARCH_MATRIX: {
+    [key: string]: string[];
+};
+declare class Version {
+    release: string;
+    version?: string;
+    sorted_rel: number[];
+    constructor(release: string, version?: string);
+    private buildSortedRel;
+    get fullString(): string;
+    equals(other: Version): boolean;
+    lessThan(other: Version): boolean;
+    isSupported(): boolean;
+    static fromPath(filePath?: PathLike): Version;
+    static isSupportedPath(path: PathLike): boolean;
+    static buildMinMax(): [Version, Version];
+}
+export declare class GitHubDownloader {
+    githubRepo: string;
+    apiUrl: string;
+    constructor(githubRepo: string);
+    checkAsset(asset: any): any;
+    missingAssetError(): void;
+    getAsset({ retries }?: {
+        retries: number;
+    }): Promise<any>;
+}
+export declare class CamoufoxFetcher extends GitHubDownloader {
+    arch: string;
+    _version_obj?: Version;
+    pattern: RegExp;
+    _url?: string;
+    constructor();
+    init(): Promise<void>;
+    checkAsset(asset: any): [Version, string] | null;
+    missingAssetError(): void;
+    static getPlatformArch(): string;
+    fetchLatest(): Promise<void>;
+    static downloadFile(url: string): Promise<Buffer>;
+    extractZip(zipFile: string | Buffer): Promise<void>;
+    static cleanup(): boolean;
+    setVersion(): void;
+    install(): Promise<void>;
+    get url(): string;
+    get version(): string;
+    get release(): string;
+    get verstr(): string;
+}
+export declare function installedVerStr(): string;
+export declare function camoufoxPath(downloadIfMissing?: boolean): PathLike;
+export declare function getPath(file: string): string;
+export declare function launchPath(): string;
+export declare function webdl(url: string, desc?: string, bar?: boolean, buffer?: Writable | null, { retries }?: {
+    retries: number;
+}): Promise<Buffer>;
+export declare function unzip(zipFile: Buffer, extractPath: string, desc?: string, bar?: boolean): Promise<void>;
+export {};

package/dist/pkgman.js

@@ -0,0 +1,347 @@
+import { execSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { setTimeout } from "node:timers/promises";
+import AdmZip from "adm-zip";
+import ProgressBar from "progress";
+import { CONSTRAINTS } from "./__version__.js";
+import { CamoufoxNotInstalled, FileNotFoundError, MissingRelease, UnsupportedArchitecture, UnsupportedOS, UnsupportedVersion, } from "./exceptions.js";
+const ARCH_MAP = {
+    x64: "x86_64",
+    ia32: "i686",
+    arm64: "arm64",
+    arm: "arm64",
+};
+const OS_MAP = {
+    darwin: "mac",
+    linux: "lin",
+    win32: "win",
+};
+if (!(process.platform in OS_MAP)) {
+    throw new UnsupportedOS(`OS ${process.platform} is not supported`);
+}
+export const OS_NAME = OS_MAP[process.platform];
+export const INSTALL_DIR = userCacheDir("camoufox");
+export const LOCAL_DATA = path.join(import.meta.dirname, "data-files");
+export const OS_ARCH_MATRIX = {
+    win: ["x86_64", "i686"],
+    mac: ["x86_64", "arm64"],
+    lin: ["x86_64", "arm64", "i686"],
+};
+const LAUNCH_FILE = {
+    win: "camoufox.exe",
+    mac: "../MacOS/camoufox",
+    lin: "camoufox-bin",
+};
+class Version {
+    release;
+    version;
+    sorted_rel;
+    constructor(release, version) {
+        this.release = release;
+        this.version = version;
+        this.sorted_rel = this.buildSortedRel();
+    }
+    buildSortedRel() {
+        const parts = this.release
+            .split(".")
+            .map((x) => Number.isNaN(Number(x)) ? x.charCodeAt(0) - 1024 : Number(x));
+        while (parts.length < 5) {
+            parts.push(0);
+        }
+        return parts;
+    }
+    get fullString() {
+        return `${this.version}-${this.release}`;
+    }
+    equals(other) {
+        return this.sorted_rel.join(".") === other.sorted_rel.join(".");
+    }
+    lessThan(other) {
+        for (let i = 0; i < this.sorted_rel.length; i++) {
+            if (this.sorted_rel[i] < other.sorted_rel[i])
+                return true;
+            if (this.sorted_rel[i] > other.sorted_rel[i])
+                return false;
+        }
+        return false;
+    }
+    isSupported() {
+        return VERSION_MIN.lessThan(this) && this.lessThan(VERSION_MAX);
+    }
+    static fromPath(filePath = INSTALL_DIR) {
+        const versionPath = path.join(filePath.toString(), "version.json");
+        if (!fs.existsSync(versionPath)) {
+            throw new FileNotFoundError(`Version information not found at ${versionPath}. Please run \`camoufox fetch\` to install.`);
+        }
+        const versionData = JSON.parse(fs.readFileSync(versionPath, "utf-8"));
+        return new Version(versionData.release, versionData.version);
+    }
+    static isSupportedPath(path) {
+        return Version.fromPath(path).isSupported();
+    }
+    static buildMinMax() {
+        return [
+            new Version(CONSTRAINTS.MIN_VERSION),
+            new Version(CONSTRAINTS.MAX_VERSION),
+        ];
+    }
+}
+const [VERSION_MIN, VERSION_MAX] = Version.buildMinMax();
+export class GitHubDownloader {
+    githubRepo;
+    apiUrl;
+    constructor(githubRepo) {
+        this.githubRepo = githubRepo;
+        this.apiUrl = `https://api.github.com/repos/${githubRepo}/releases`;
+    }
+    checkAsset(asset) {
+        return asset.browser_download_url;
+    }
+    missingAssetError() {
+        throw new MissingRelease(`Could not find a release asset in ${this.githubRepo}.`);
+    }
+    async getAsset({ retries } = { retries: 5 }) {
+        let attempts = 0;
+        let response;
+        while (attempts < retries) {
+            try {
+                response = await fetch(this.apiUrl);
+                if (response.ok)
+                    break;
+            }
+            catch (e) {
+                console.error(e, `retrying (${attempts + 1}/${retries})...`);
+                await setTimeout(5e3);
+            }
+            attempts++;
+        }
+        if (!response || !response.ok) {
+            throw new Error(`Failed to fetch releases from ${this.apiUrl} after ${retries} attempts`);
+        }
+        const releases = await response.json();
+        for (const release of releases) {
+            for (const asset of release.assets) {
+                const data = this.checkAsset(asset);
+                if (data) {
+                    return data;
+                }
+            }
+        }
+        this.missingAssetError();
+    }
+}
+export class CamoufoxFetcher extends GitHubDownloader {
+    arch;
+    _version_obj;
+    pattern;
+    _url;
+    constructor() {
+        super("daijro/camoufox");
+        this.arch = CamoufoxFetcher.getPlatformArch();
+        this.pattern = new RegExp(`camoufox-(.+)-(.+)-${OS_NAME}\\.${this.arch}\\.zip`);
+    }
+    async init() {
+        await this.fetchLatest();
+    }
+    checkAsset(asset) {
+        const match = asset.name.match(this.pattern);
+        if (!match)
+            return null;
+        const version = new Version(match[2], match[1]);
+        if (!version.isSupported())
+            return null;
+        return [version, asset.browser_download_url];
+    }
+    missingAssetError() {
+        throw new MissingRelease(`No matching release found for ${OS_NAME} ${this.arch} in the supported range: (${CONSTRAINTS.asRange()}). Please update the library.`);
+    }
+    static getPlatformArch() {
+        const platArch = os.arch().toLowerCase();
+        if (!(platArch in ARCH_MAP)) {
+            throw new UnsupportedArchitecture(`Architecture ${platArch} is not supported`);
+        }
+        const arch = ARCH_MAP[platArch];
+        if (!OS_ARCH_MATRIX[OS_NAME].includes(arch)) {
+            throw new UnsupportedArchitecture(`Architecture ${arch} is not supported for ${OS_NAME}`);
+        }
+        return arch;
+    }
+    async fetchLatest() {
+        if (this._version_obj)
+            return;
+        const releaseData = await this.getAsset();
+        this._version_obj = releaseData[0];
+        this._url = releaseData[1];
+    }
+    static async downloadFile(url) {
+        const response = await fetch(url);
+        return Buffer.from(await response.arrayBuffer());
+    }
+    async extractZip(zipFile) {
+        const zip = new AdmZip(zipFile);
+        zip.extractAllTo(INSTALL_DIR.toString(), true);
+    }
+    static cleanup() {
+        if (fs.existsSync(INSTALL_DIR)) {
+            fs.rmSync(INSTALL_DIR, { recursive: true });
+            return true;
+        }
+        return false;
+    }
+    setVersion() {
+        fs.writeFileSync(path.join(INSTALL_DIR.toString(), "version.json"), JSON.stringify({ version: this.version, release: this.release }));
+    }
+    async install() {
+        await this.init();
+        await CamoufoxFetcher.cleanup();
+        try {
+            fs.mkdirSync(INSTALL_DIR, { recursive: true });
+            const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "camoufox-"));
+            const tempFilePath = path.join(tempDir, "camoufox.zip");
+            const tempFileStream = fs.createWriteStream(tempFilePath);
+            await webdl(this.url, "Downloading Camoufox...", true, tempFileStream);
+            await new Promise((r) => tempFileStream.close(r));
+            await this.extractZip(tempFilePath);
+            this.setVersion();
+            if (OS_NAME !== "win") {
+                execSync(`chmod -R 755 ${INSTALL_DIR}`);
+            }
+            console.log("Camoufox successfully installed.");
+        }
+        catch (e) {
+            console.error(`Error installing Camoufox: ${e}`);
+            await CamoufoxFetcher.cleanup();
+            throw e;
+        }
+    }
+    get url() {
+        if (!this._url) {
+            throw new Error("Url is not available. Make sure to run fetchLatest first.");
+        }
+        return this._url;
+    }
+    get version() {
+        if (!this._version_obj || !this._version_obj.version) {
+            throw new Error("Version is not available. Make sure to run fetchLatest first.");
+        }
+        return this._version_obj.version;
+    }
+    get release() {
+        if (!this._version_obj) {
+            throw new Error("Release information is not available. Make sure to run the installation first.");
+        }
+        return this._version_obj.release;
+    }
+    get verstr() {
+        if (!this._version_obj) {
+            throw new Error("Version is not available. Make sure to run the installation first.");
+        }
+        return this._version_obj.fullString;
+    }
+}
+function userCacheDir(appName) {
+    if (OS_NAME === "win") {
+        return path.join(os.homedir(), "AppData", "Local", appName, appName, "Cache");
+    }
+    else if (OS_NAME === "mac") {
+        return path.join(os.homedir(), "Library", "Caches", appName);
+    }
+    else {
+        return path.join(os.homedir(), ".cache", appName);
+    }
+}
+export function installedVerStr() {
+    return Version.fromPath().fullString;
+}
+export function camoufoxPath(downloadIfMissing = true) {
+    // Ensure the directory exists and is not empty
+    if (!fs.existsSync(INSTALL_DIR) || fs.readdirSync(INSTALL_DIR).length === 0) {
+        if (!downloadIfMissing) {
+            throw new Error(`Camoufox executable not found at ${INSTALL_DIR}`);
+        }
+    }
+    else if (fs.existsSync(INSTALL_DIR) &&
+        Version.isSupportedPath(INSTALL_DIR)) {
+        return INSTALL_DIR;
+    }
+    else {
+        if (!downloadIfMissing) {
+            throw new UnsupportedVersion("Camoufox executable is outdated.");
+        }
+    }
+    // Install and recheck
+    const fetcher = new CamoufoxFetcher();
+    fetcher.install().then(() => camoufoxPath());
+    return INSTALL_DIR;
+}
+export function getPath(file) {
+    if (OS_NAME === "mac") {
+        return path.resolve(camoufoxPath().toString(), "Camoufox.app", "Contents", "Resources", file);
+    }
+    return path.join(camoufoxPath().toString(), file);
+}
+export function launchPath() {
+    const launchPath = getPath(LAUNCH_FILE[OS_NAME]);
+    if (!fs.existsSync(launchPath)) {
+        throw new CamoufoxNotInstalled(`Camoufox is not installed at ${camoufoxPath()}. Please run \`camoufox fetch\` to install.`);
+    }
+    return launchPath;
+}
+export async function webdl(url, desc = "", bar = true, buffer = null, { retries } = { retries: 5 }) {
+    let attempts = 0;
+    let response;
+    while (attempts < retries) {
+        try {
+            response = await fetch(url);
+            if (response.ok)
+                break;
+        }
+        catch (e) {
+            console.error(e, `retrying (${attempts + 1}/${retries})...`);
+            await setTimeout(5e3);
+        }
+        attempts++;
+    }
+    if (!response || !response.ok) {
+        throw new Error(`Failed to download from ${url} after ${retries} attempts`);
+    }
+    const totalSize = parseInt(response.headers.get("content-length") || "0", 10);
+    const progressBar = bar
+        ? new ProgressBar(`${desc} [:bar] :percent :etas`, {
+            total: totalSize,
+            width: 40,
+        })
+        : null;
+    const chunks = [];
+    for await (const chunk of response.body) {
+        if (buffer) {
+            buffer.write(chunk);
+        }
+        else {
+            chunks.push(chunk);
+        }
+        if (progressBar) {
+            progressBar.tick(chunk.length, "X");
+        }
+    }
+    const fileBuffer = Buffer.concat(chunks);
+    return fileBuffer;
+}
+export async function unzip(zipFile, extractPath, desc, bar = true) {
+    const zip = new AdmZip(zipFile);
+    const zipEntries = zip.getEntries();
+    if (bar) {
+        console.log(desc || "Extracting files...");
+    }
+    for (const entry of zipEntries) {
+        if (bar) {
+            console.log(`Extracting ${entry.entryName}`);
+        }
+        zip.extractEntryTo(entry, extractPath, false, true);
+    }
+    if (bar) {
+        console.log("Extraction complete.");
+    }
+}

package/dist/server.d.ts

@@ -0,0 +1,6 @@
+import { type BrowserServer } from "playwright-core";
+import { type LaunchOptions } from "./utils.js";
+export declare function launchServer({ port, ws_path, ...options }: LaunchOptions | {
+    port?: number;
+    ws_path?: string;
+}): Promise<BrowserServer>;

package/dist/server.js

@@ -0,0 +1,9 @@
+import { firefox } from "playwright-core";
+import { launchOptions } from "./utils.js";
+export async function launchServer({ port, ws_path, ...options }) {
+    return firefox.launchServer({
+        ...(await launchOptions(options)),
+        port,
+        wsPath: ws_path,
+    });
+}

package/dist/sync_api.d.ts

@@ -0,0 +1,7 @@
+import { type Browser, type BrowserContext, type BrowserType } from "playwright-core";
+import { type LaunchOptions } from "./utils.js";
+export declare function Camoufox<UserDataDir extends string | undefined = undefined, ReturnType = UserDataDir extends string ? BrowserContext : Browser>(launch_options?: LaunchOptions | {
+    headless?: boolean | "virtual";
+    user_data_dir: UserDataDir;
+}): Promise<ReturnType>;
+export declare function NewBrowser<UserDataDir extends string | false = false, ReturnType = UserDataDir extends string ? BrowserContext : Browser>(playwright: BrowserType<Browser>, headless?: boolean | "virtual", fromOptions?: Record<string, any>, userDataDir?: UserDataDir, debug?: boolean, launch_options?: LaunchOptions): Promise<ReturnType>;

package/dist/sync_api.js

@@ -0,0 +1,27 @@
+import { firefox, } from "playwright-core";
+import { launchOptions, syncAttachVD } from "./utils.js";
+import { VirtualDisplay } from "./virtdisplay.js";
+export async function Camoufox(launch_options = {}) {
+    const { headless, user_data_dir, ...launchOptions } = launch_options;
+    return NewBrowser(firefox, headless, {}, user_data_dir ?? false, false, launchOptions);
+}
+export async function NewBrowser(playwright, headless = false, fromOptions = {}, userDataDir = false, debug = false, launch_options = {}) {
+    let virtualDisplay = null;
+    if (headless === "virtual") {
+        virtualDisplay = new VirtualDisplay(debug);
+        launch_options.virtual_display = virtualDisplay.get();
+        launch_options.headless = false;
+    }
+    else {
+        launch_options.headless ||= headless;
+    }
+    if (!fromOptions || Object.keys(fromOptions).length === 0) {
+        fromOptions = await launchOptions({ debug, ...launch_options });
+    }
+    if (typeof userDataDir === "string") {
+        const context = await playwright.launchPersistentContext(userDataDir, fromOptions);
+        return syncAttachVD(context, virtualDisplay);
+    }
+    const browser = await playwright.launch(fromOptions);
+    return syncAttachVD(browser, virtualDisplay);
+}

package/dist/utils.d.ts

@@ -0,0 +1,88 @@
+import { type PathLike } from "node:fs";
+import type { Fingerprint, FingerprintGeneratorOptions } from "fingerprint-generator";
+import type { LaunchOptions as PlaywrightLaunchOptions } from "playwright-core";
+import { type DefaultAddons } from "./addons.js";
+import { SUPPORTED_OS } from "./fingerprints.js";
+import type { VirtualDisplay } from "./virtdisplay.js";
+type Screen = FingerprintGeneratorOptions["screen"];
+export declare function getAsBooleanFromENV(name: string, defaultValue?: boolean | undefined): boolean;
+export declare function syncAttachVD(browser: any, virtualDisplay?: VirtualDisplay | null): any;
+export interface LaunchOptions {
+    /** Operating system to use for the fingerprint generation.
+     * Can be "windows", "macos", "linux", or a list to randomly choose from.
+     * Default: ["windows", "macos", "linux"]
+     */
+    os?: (typeof SUPPORTED_OS)[number] | (typeof SUPPORTED_OS)[number][];
+    /** Whether to block all images. */
+    block_images?: boolean;
+    /** Whether to block WebRTC entirely. */
+    block_webrtc?: boolean;
+    /** Whether to block WebGL. To prevent leaks, only use this for special cases. */
+    block_webgl?: boolean;
+    /** Disables the Cross-Origin-Opener-Policy, allowing elements in cross-origin iframes to be clicked. */
+    disable_coop?: boolean;
+    /** Calculate longitude, latitude, timezone, country, & locale based on the IP address.
+     * Pass the target IP address to use, or `true` to find the IP address automatically.
+     */
+    geoip?: string | boolean;
+    /** Humanize the cursor movement.
+     * Takes either `true`, or the MAX duration in seconds of the cursor movement.
+     * The cursor typically takes up to 1.5 seconds to move across the window.
+     */
+    humanize?: boolean | number;
+    /** Locale(s) to use. The first listed locale will be used for the Intl API. */
+    locale?: string | string[];
+    /** List of Firefox addons to use. */
+    addons?: string[];
+    /** Fonts to load into the browser (in addition to the default fonts for the target `os`).
+     * Takes a list of font family names that are installed on the system.
+     */
+    fonts?: string[];
+    /** If enabled, OS-specific system fonts will not be passed to the browser. */
+    custom_fonts_only?: boolean;
+    /** Default addons to exclude. Passed as a list of `DefaultAddons` enums. */
+    exclude_addons?: (keyof typeof DefaultAddons)[];
+    /** Constrains the screen dimensions of the generated fingerprint. */
+    screen?: Screen;
+    /** Set a fixed window size instead of generating a random one. */
+    window?: [number, number];
+    /** Use a custom BrowserForge fingerprint. If not provided, a random fingerprint will be generated
+     * based on the provided `os` & `screen` constraints.
+     */
+    fingerprint?: Fingerprint;
+    /** Firefox version to use. Defaults to the current Camoufox version.
+     * To prevent leaks, only use this for special cases.
+     */
+    ff_version?: number;
+    /** Whether to run the browser in headless mode. Defaults to `false`.
+     */
+    headless?: boolean;
+    /** Whether to enable running scripts in the main world.
+     * To use this, prepend "mw:" to the script: `page.evaluate("mw:" + script)`.
+     */
+    main_world_eval?: boolean;
+    /** Custom browser executable path. */
+    executable_path?: string | PathLike;
+    /** Firefox user preferences to set. */
+    firefox_user_prefs?: Record<string, any>;
+    /** Proxy to use for the browser.
+     * Note: If `geoip` is `true`, a request will be sent through this proxy to find the target IP.
+     */
+    proxy?: string | PlaywrightLaunchOptions["proxy"];
+    /** Cache previous pages, requests, etc. (uses more memory). */
+    enable_cache?: boolean;
+    /** Arguments to pass to the browser. */
+    args?: string[];
+    /** Environment variables to set. */
+    env?: Record<string, string | number | boolean>;
+    /** Prints the config being sent to Camoufox. */
+    debug?: boolean;
+    /** Virtual display number. Example: `":99"`. This is handled by Camoufox & AsyncCamoufox. */
+    virtual_display?: string;
+    /** Use a specific WebGL vendor/renderer pair. Passed as a tuple of `[vendor, renderer]`. */
+    webgl_config?: [string, string];
+    /** Additional Firefox launch options. */
+    [key: string]: any;
+}
+export declare function launchOptions({ config, os, block_images, block_webrtc, block_webgl, disable_coop, webgl_config, geoip, humanize, locale, addons, fonts, custom_fonts_only, exclude_addons, screen, window, fingerprint, ff_version, headless, main_world_eval, executable_path, firefox_user_prefs, proxy, enable_cache, args, env, i_know_what_im_doing, debug, virtual_display, ...launch_options }: LaunchOptions): Promise<Record<string, any>>;
+export {};