chromiumfish 0.1.0

package/LICENSE

@@ -0,0 +1,30 @@
+MIT License
+
+Copyright (c) 2026 Arman Hossain
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+This package distributes builds of the Chromium project, which is licensed
+under the BSD 3-Clause License and includes third-party components under their
+respective licenses. The full Chromium license text and credits are bundled
+with each browser release. "Chromium" and "Google Chrome" are trademarks of
+Google LLC. ChromiumFish is an independent fork and is not affiliated with,
+sponsored by, or endorsed by Google LLC.

package/README.md

@@ -0,0 +1,52 @@
+# chromiumfish (Node)
+
+Stealth Chromium with a drop-in [Playwright](https://playwright.dev) harness.
+
+```bash
+npm install chromiumfish playwright-core
+npx chromiumfish fetch        # download + cache the browser build
+```
+
+## Usage
+
+```javascript
+import { ChromiumFish } from "chromiumfish";
+
+const browser = await ChromiumFish({ personaSeed: 27182, headless: true });
+const page = await browser.newPage();
+await page.goto("https://abrahamjuliot.github.io/creepjs/");
+await page.screenshot({ path: "fp.png" });
+await browser.close();
+```
+
+`ChromiumFish()` returns a standard Playwright `Browser`, so `newContext`,
+`newPage`, routing, tracing, etc. all work as usual.
+
+## Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `personaSeed` | — | Integer seed for a stable, internally-consistent fingerprint persona. |
+| `headless` | `true` | Run headless (SwiftShader). |
+| `proxy` | — | Playwright proxy object, e.g. `{ server, username, password }`. |
+| `windowSize` | `[1920, 1080]` | Window dimensions (`null` to omit). |
+| `version` | pinned | Override the browser build version. |
+| `download` | `true` | Auto-download the build if missing. |
+| `args` | — | Extra Chromium flags. |
+| _...rest_ | — | Forwarded to `chromium.launch()`. |
+
+## CLI
+
+```bash
+npx chromiumfish fetch [--browser-version X] [--force]   # download + cache
+npx chromiumfish path                                     # print binary path
+npx chromiumfish clear                                    # wipe the cache
+npx chromiumfish --version
+```
+
+Builds are cached under `~/.cache/chromiumfish/<version>/` (override with
+`CHROMIUMFISH_CACHE_DIR`). Pin a build with `CHROMIUMFISH_VERSION`.
+
+## License
+
+MIT © Arman Hossain. See the [repository](https://github.com/arman-bd/chromiumfish).

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+import * as fs from "node:fs";
+import { binaryPath, cacheRoot, fetchBrowser } from "./fetch.js";
+import { SDK_VERSION, browserVersion } from "./version.js";
+async function main(argv) {
+    const cmd = argv[2];
+    switch (cmd) {
+        case "fetch": {
+            const force = argv.includes("--force");
+            const vIdx = argv.indexOf("--browser-version");
+            const version = vIdx >= 0 ? argv[vIdx + 1] : undefined;
+            console.log(await fetchBrowser(version, force));
+            return 0;
+        }
+        case "path":
+            console.log(await binaryPath());
+            return 0;
+        case "clear": {
+            const root = cacheRoot();
+            if (fs.existsSync(root)) {
+                fs.rmSync(root, { recursive: true, force: true });
+                console.log(`removed ${root}`);
+            }
+            else {
+                console.log("nothing to remove");
+            }
+            return 0;
+        }
+        case "--version":
+        case "-V":
+            console.log(`chromiumfish ${SDK_VERSION} (browser ${browserVersion()})`);
+            return 0;
+        default:
+            console.log([
+                "chromiumfish — fetch and manage the ChromiumFish browser build",
+                "",
+                "Usage:",
+                "  chromiumfish fetch [--browser-version X] [--force]   download + cache",
+                "  chromiumfish path                                    print binary path",
+                "  chromiumfish clear                                   wipe the cache",
+                "  chromiumfish --version",
+            ].join("\n"));
+            return cmd ? 0 : 1;
+    }
+}
+main(process.argv)
+    .then((code) => process.exit(code))
+    .catch((err) => {
+    console.error(err?.message || err);
+    process.exit(1);
+});

package/dist/fetch.d.ts

@@ -0,0 +1,6 @@
+export declare function cacheRoot(): string;
+export declare function platformSlug(): string;
+export declare function installDir(version?: string): string;
+export declare function findBinary(root: string): string | null;
+export declare function fetchBrowser(version?: string, force?: boolean): Promise<string>;
+export declare function binaryPath(version?: string, download?: boolean): Promise<string>;

package/dist/fetch.js

@@ -0,0 +1,187 @@
+/**
+ * Download, verify, and cache the ChromiumFish browser build.
+ *
+ * Resolves `version × platform` to a GitHub Release asset, verifies its
+ * SHA-256, extracts it to a per-version cache dir, and returns the path to the
+ * launchable binary.
+ */
+import { createHash } from "node:crypto";
+import { spawnSync } from "node:child_process";
+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";
+export function cacheRoot() {
+    const env = process.env.CHROMIUMFISH_CACHE_DIR;
+    if (env)
+        return env;
+    if (process.platform === "darwin")
+        return path.join(os.homedir(), "Library", "Caches", "chromiumfish");
+    if (process.platform === "win32")
+        return path.join(process.env.LOCALAPPDATA || path.join(os.homedir(), "AppData", "Local"), "chromiumfish");
+    return path.join(process.env.XDG_CACHE_HOME || path.join(os.homedir(), ".cache"), "chromiumfish");
+}
+export function platformSlug() {
+    const arch = { x64: "x64", arm64: "arm64" }[process.arch];
+    if (!arch)
+        throw new Error(`unsupported architecture: ${process.arch}`);
+    if (process.platform === "linux")
+        return `linux-${arch}`;
+    if (process.platform === "darwin")
+        return `mac-${arch}`;
+    if (process.platform === "win32")
+        return `win-${arch}`;
+    throw new Error(`unsupported platform: ${process.platform}`);
+}
+function assetName(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());
+}
+const BINARY_NAMES = ["chromiumfish", "chrome", "chromiumfish.exe", "chrome.exe", "ChromiumFish"];
+export function findBinary(root) {
+    if (!fs.existsSync(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;
+    }
+    const stack = [root];
+    while (stack.length) {
+        const dir = stack.pop();
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory())
+                stack.push(full);
+            else if (BINARY_NAMES.includes(entry.name))
+                return full;
+        }
+    }
+    return null;
+}
+function download(url, dest) {
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    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(`download failed (${res.statusCode}) for ${u}`));
+                }
+                const total = Number(res.headers["content-length"] || 0);
+                let read = 0;
+                const out = fs.createWriteStream(dest);
+                res.on("data", (c) => {
+                    read += c.length;
+                    if (total)
+                        process.stderr.write(`\r[chromiumfish] ${Math.floor((read / total) * 100)}%`);
+                });
+                res.pipe(out);
+                out.on("finish", () => { process.stderr.write("\n"); out.close(() => resolve()); });
+                out.on("error", reject);
+            }).on("error", reject);
+        };
+        process.stderr.write(`[chromiumfish] downloading ${url}\n`);
+        get(url);
+    });
+}
+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);
+        get(url);
+    });
+}
+function sha256(file) {
+    return createHash("sha256").update(fs.readFileSync(file)).digest("hex");
+}
+function extract(archive, dest) {
+    fs.mkdirSync(dest, { recursive: true });
+    // Modern tar (incl. Windows 10+ bsdtar) extracts both .tar.gz and .zip.
+    const r = spawnSync("tar", ["-xf", archive, "-C", dest], { stdio: "inherit" });
+    if (r.status !== 0)
+        throw new Error(`extraction failed for ${archive}`);
+}
+export async function fetchBrowser(version = browserVersion(), force = false) {
+    const target = installDir(version);
+    if (force && fs.existsSync(target))
+        fs.rmSync(target, { recursive: true, force: true });
+    const cached = findBinary(target);
+    if (cached)
+        return cached;
+    const base = releaseBaseUrl(version);
+    const asset = assetName(version);
+    const archive = path.join(cacheRoot(), version, asset);
+    await download(`${base}/${asset}`, archive);
+    try {
+        const expected = (await fetchText(`${base}/${asset}.sha256`)).trim().split(/\s+/)[0];
+        const actual = sha256(archive);
+        if (actual !== expected) {
+            fs.rmSync(archive, { force: true });
+            throw new Error(`checksum mismatch for ${asset}: ${actual} !== ${expected}`);
+        }
+    }
+    catch (e) {
+        if (String(e?.message || e).includes("HTTP"))
+            process.stderr.write("[chromiumfish] warning: no .sha256 published, skipping verification\n");
+        else
+            throw e;
+    }
+    extract(archive, target);
+    fs.rmSync(archive, { force: true });
+    macosPrepare(target);
+    const bin = findBinary(target);
+    if (!bin)
+        throw new Error(`no browser binary found in extracted build at ${target}`);
+    if (process.platform !== "win32")
+        fs.chmodSync(bin, 0o755);
+    process.stderr.write(`[chromiumfish] ready: ${bin}\n`);
+    return bin;
+}
+/**
+ * Identity-clean macOS prep: strip the download
+ * quarantine flag, and ensure an ad-hoc signature so Apple Silicon will run the
+ * binary — no certificate, name, or identity attached. Release builds ship
+ * ad-hoc signed; this is a defensive fallback.
+ */
+function macosPrepare(target) {
+    if (process.platform !== "darwin")
+        return;
+    spawnSync("xattr", ["-dr", "com.apple.quarantine", target], { stdio: "ignore" });
+    const app = fs.readdirSync(target).find((n) => n.endsWith(".app"));
+    const signTarget = app ? path.join(target, app) : findBinary(target);
+    if (signTarget) {
+        const valid = spawnSync("codesign", ["--verify", "--quiet", signTarget]).status === 0;
+        if (!valid)
+            spawnSync("codesign", ["--force", "--deep", "--sign", "-", signTarget], { stdio: "ignore" });
+    }
+}
+export async function binaryPath(version = browserVersion(), download = true) {
+    const existing = findBinary(installDir(version));
+    if (existing)
+        return existing;
+    if (!download)
+        throw new Error(`ChromiumFish ${version} not installed. Run \`npx chromiumfish fetch\`.`);
+    return fetchBrowser(version);
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { ChromiumFish, buildArgs, BASE_ARGS } from "./launcher.js";
+export type { ChromiumFishOptions } from "./launcher.js";
+export { fetchBrowser, binaryPath, installDir, cacheRoot, platformSlug, findBinary } from "./fetch.js";
+export { SDK_VERSION, DEFAULT_BROWSER_VERSION, RELEASE_REPO, browserVersion, releaseBaseUrl, } from "./version.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { ChromiumFish, buildArgs, BASE_ARGS } from "./launcher.js";
+export { fetchBrowser, binaryPath, installDir, cacheRoot, platformSlug, findBinary } from "./fetch.js";
+export { SDK_VERSION, DEFAULT_BROWSER_VERSION, RELEASE_REPO, browserVersion, releaseBaseUrl, } from "./version.js";

package/dist/launcher.d.ts

@@ -0,0 +1,27 @@
+import { type Browser, type LaunchOptions } from "playwright-core";
+/**
+ * Flags that keep the GPU-less / SwiftShader path working and the persona
+ * engine happy. Mirrors the production launch_lean.sh defaults (minus anything
+ * baked into the build / bundled addon).
+ */
+export declare const BASE_ARGS: string[];
+export interface ChromiumFishOptions extends Omit<LaunchOptions, "executablePath"> {
+    /** Integer seed for a stable, internally-consistent fingerprint persona. */
+    personaSeed?: number;
+    /** Run headless (SwiftShader). Defaults to true. */
+    headless?: boolean;
+    /** Window dimensions; defaults to [1920, 1080]. Pass null to omit. */
+    windowSize?: [number, number] | null;
+    /** Override the browser build version. */
+    version?: string;
+    /** Auto-download the build if missing. Defaults to true. */
+    download?: boolean;
+}
+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 });
+ */
+export declare function ChromiumFish(opts?: ChromiumFishOptions): Promise<Browser>;

package/dist/launcher.js

@@ -0,0 +1,42 @@
+import { chromium } from "playwright-core";
+import { binaryPath } from "./fetch.js";
+/**
+ * Flags that keep the GPU-less / SwiftShader path working and the persona
+ * engine happy. Mirrors the production launch_lean.sh defaults (minus anything
+ * baked into the build / bundled addon).
+ */
+export const BASE_ARGS = [
+    "--no-sandbox",
+    "--no-zygote",
+    "--disable-dev-shm-usage",
+    "--use-gl=angle",
+    "--use-angle=swiftshader",
+    "--enable-unsafe-swiftshader",
+];
+export function buildArgs(opts) {
+    const args = [...BASE_ARGS];
+    if (opts.personaSeed !== undefined)
+        args.push(`--persona-seed=${opts.personaSeed}`);
+    const ws = opts.windowSize === undefined ? [1920, 1080] : opts.windowSize;
+    if (ws)
+        args.push(`--window-size=${ws[0]},${ws[1]}`);
+    if (opts.args)
+        args.push(...opts.args);
+    return args;
+}
+/**
+ * Launch ChromiumFish and return a standard Playwright `Browser`.
+ *
+ *   import { ChromiumFish } from "chromiumfish";
+ *   const browser = await ChromiumFish({ personaSeed: 27182, headless: true });
+ */
+export async function ChromiumFish(opts = {}) {
+    const { personaSeed, headless = true, windowSize, version, download = true, args, ...launch } = opts;
+    const executablePath = await binaryPath(version, download);
+    return chromium.launch({
+        executablePath,
+        headless,
+        args: buildArgs({ personaSeed, windowSize, args }),
+        ...launch,
+    });
+}

package/dist/version.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Pinned browser build + release coordinates.
+ *
+ * The browser is built privately and published to this repo's GitHub Releases.
+ * `DEFAULT_BROWSER_VERSION` is the release tag (without the leading `v`) the
+ * 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.0";
+/** 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. */
+export declare const RELEASE_REPO = "arman-bd/chromiumfish";
+export declare function browserVersion(): string;
+export declare function releaseBaseUrl(version?: string): string;

package/dist/version.js

@@ -0,0 +1,19 @@
+/**
+ * Pinned browser build + release coordinates.
+ *
+ * The browser is built privately and published to this repo's GitHub Releases.
+ * `DEFAULT_BROWSER_VERSION` is the release tag (without the leading `v`) the
+ * SDK downloads by default; override it with `CHROMIUMFISH_VERSION`.
+ */
+/** SDK package version (kept in sync with package.json). */
+export const SDK_VERSION = "0.1.0";
+/** Default ChromiumFish browser build to fetch. Matches src/chrome/VERSION. */
+export const DEFAULT_BROWSER_VERSION = "150.0.7844";
+/** Public repo hosting the release assets. */
+export const RELEASE_REPO = "arman-bd/chromiumfish";
+export function browserVersion() {
+    return process.env.CHROMIUMFISH_VERSION || DEFAULT_BROWSER_VERSION;
+}
+export function releaseBaseUrl(version = browserVersion()) {
+    return `https://github.com/${RELEASE_REPO}/releases/download/v${version}`;
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "chromiumfish",
+  "version": "0.1.0",
+  "description": "Stealth Chromium build with a drop-in Playwright harness — fetches and launches the ChromiumFish browser.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "chromiumfish": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "playwright",
+    "chromium",
+    "stealth",
+    "fingerprint",
+    "automation",
+    "anti-detect"
+  ],
+  "author": "Arman Hossain",
+  "license": "MIT",
+  "homepage": "https://chromiumfish.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/arman-bd/chromiumfish.git"
+  },
+  "bugs": {
+    "url": "https://github.com/arman-bd/chromiumfish/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "peerDependencies": {
+    "playwright-core": ">=1.40"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.4.0"
+  }
+}