@achamm/veilbrowser 0.3.0

package/dist/page.js

@@ -0,0 +1,527 @@
+import { buildStealth } from "./stealth.js";
+import { Rng, mousePath, moveDelay, keyDelay, sleep } from "./human.js";
+const INTERESTING = new Set([
+    "button", "link", "textbox", "searchbox", "combobox", "checkbox", "radio",
+    "menuitem", "menuitemcheckbox", "tab", "switch", "slider", "option",
+    "listbox", "spinbutton", "textarea",
+]);
+/**
+ * True if `url` targets a loopback / private-network host. Fingerprinters
+ * (iphey, pixelscan, …) port-scan these from page JS to profile the machine's
+ * OTHER software — VNC on :5900, a local automation API on :3001, etc. — which
+ * also leaks your LAN to every site you visit. Exotic IP encodings (decimal,
+ * hex) are a known gap; real-world scanners use the canonical forms below.
+ */
+export function isPrivateHost(url) {
+    let host;
+    try {
+        host = new URL(url).hostname.toLowerCase();
+    }
+    catch {
+        return false;
+    }
+    host = host.replace(/^\[|\]$/g, ""); // strip IPv6 brackets
+    if (host === "localhost" || host.endsWith(".localhost"))
+        return true;
+    if (host === "::1" || host === "0.0.0.0")
+        return true;
+    const m = host.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.\d{1,3}$/);
+    if (!m)
+        return false;
+    const a = +m[1], b = +m[2];
+    return (a === 127 || // 127.0.0.0/8 loopback
+        a === 10 || // 10.0.0.0/8
+        a === 0 || // 0.0.0.0/8
+        (a === 192 && b === 168) || // 192.168.0.0/16
+        (a === 172 && b >= 16 && b <= 31) || // 172.16.0.0/12
+        (a === 169 && b === 254) // 169.254.0.0/16 link-local
+    );
+}
+// Only these (private) requests are intercepted, so normal browsing keeps its
+// exact timing — no global request pause. Globs over-capture slightly (e.g.
+// 172.1*); isPrivateHost() is the real gate in the handler. http/https only:
+// CDP's Fetch domain does not intercept WebSocket handshakes, so raw ws:// to a
+// private host falls back to Chrome's own Private Network Access (a timeout, not
+// a uniform block). Real port-scanners (and the :3001/:5900 probes) use HTTP.
+const PRIVATE_URL_PATTERNS = ["localhost", "127.", "0.0.0.0", "10.", "192.168.", "172.1", "172.2", "172.3", "169.254.", "[::1]"]
+    .flatMap((h) => ["http", "https"].map((s) => ({ urlPattern: `${s}://${h}*` })));
+export class Page {
+    cdp;
+    sessionId;
+    targetId;
+    rng = new Rng();
+    mouse = { x: 100, y: 100 };
+    refs = new Map();
+    closed = false;
+    // FedCM interception state (see enableFedCm).
+    fedcmOff;
+    fedcmQueue = [];
+    fedcmWaiters = [];
+    lastFedcmDialogId;
+    // Private-network block state (see blockPrivateNetwork).
+    blockPrivateOff;
+    mainFrameId;
+    topPrivate = false; // is the page's own top-level origin private?
+    constructor(cdp, sessionId, targetId) {
+        this.cdp = cdp;
+        this.sessionId = sessionId;
+        this.targetId = targetId;
+    }
+    /** Enable the domains we use and arm stealth injection on every document. */
+    async init(opts = {}) {
+        await this.send("Page.enable");
+        await this.send("DOM.enable");
+        await this.send("Accessibility.enable");
+        await this.normalizeUserAgent();
+        // Inject stealth before any page script runs, on every navigation/frame.
+        // Only mask WebGL on SwiftShader hosts; with a real GPU the authentic vendor
+        // is consistent and masking it would be a detectable lie.
+        const source = buildStealth({ maskWebgl: opts.maskWebgl ?? false });
+        await this.send("Page.addScriptToEvaluateOnNewDocument", { source });
+        if (opts.blockPrivateNetwork)
+            await this.blockPrivateNetwork();
+    }
+    /**
+     * Inject cookies before navigating — e.g. a logged-in session transferred
+     * from another browser. Each cookie is a CDP CookieParam ({name, value,
+     * domain, path, secure, httpOnly, expires?, sameSite?}). Lets the browser
+     * ride an existing session instead of re-doing a bot-walled login.
+     */
+    async setCookies(cookies) {
+        await this.send("Network.enable");
+        await this.send("Network.setCookies", { cookies });
+    }
+    /**
+     * Scrub the "HeadlessChrome" token from the UA and the matching client-hint
+     * brands. headless=new leaks it in both navigator.userAgent AND the Sec-CH-UA
+     * request headers; setUserAgentOverride with metadata fixes both at once. A
+     * no-op for headful Chrome, whose UA is already clean.
+     */
+    async normalizeUserAgent() {
+        const realUA = await this.evaluate("navigator.userAgent");
+        const cleanUA = realUA.replace("HeadlessChrome", "Chrome");
+        if (cleanUA === realUA)
+            return;
+        const major = (cleanUA.match(/Chrome\/(\d+)/)?.[1]) ?? "148";
+        await this.send("Emulation.setUserAgentOverride", {
+            userAgent: cleanUA,
+            acceptLanguage: "en-US,en;q=0.9",
+            platform: "Linux x86_64",
+            userAgentMetadata: {
+                brands: [
+                    { brand: "Chromium", version: major },
+                    { brand: "Google Chrome", version: major },
+                    { brand: "Not?A_Brand", version: "99" },
+                ],
+                fullVersion: `${major}.0.0.0`,
+                platform: "Linux",
+                platformVersion: "6.8.0",
+                architecture: "x86",
+                model: "",
+                mobile: false,
+            },
+        });
+    }
+    send(method, params = {}) {
+        return this.cdp.send(method, params, this.sessionId);
+    }
+    /** Navigate and wait for the load event. */
+    async goto(url, opts = {}) {
+        const loaded = this.cdp.once("Page.loadEventFired", {
+            sessionId: this.sessionId,
+            timeout: opts.timeout ?? 30000,
+        });
+        await this.send("Page.navigate", { url });
+        await loaded;
+        await sleep(this.rng.range(150, 400)); // settle, like a human reading
+    }
+    /** Evaluate JS in the page WITHOUT Runtime.enable (avoids the CDP tell). */
+    async evaluate(expression) {
+        const r = await this.send("Runtime.evaluate", {
+            expression,
+            returnByValue: true,
+            awaitPromise: true,
+        });
+        if (r.exceptionDetails)
+            throw new Error(`evaluate: ${r.exceptionDetails.text}`);
+        return r.result?.value;
+    }
+    async url() {
+        return this.evaluate("location.href");
+    }
+    /** Build the numbered element index from the accessibility tree. */
+    async snapshot() {
+        const { nodes } = await this.send("Accessibility.getFullAXTree");
+        this.refs.clear();
+        const elements = [];
+        let ref = 0;
+        for (const n of nodes) {
+            if (n.ignored)
+                continue;
+            const role = n.role?.value ?? "";
+            const name = (n.name?.value ?? "").trim();
+            if (!INTERESTING.has(role))
+                continue;
+            if (!name && role !== "textbox" && role !== "searchbox" && role !== "textarea")
+                continue;
+            const backendNodeId = n.backendDOMNodeId;
+            if (!backendNodeId)
+                continue;
+            const center = await this.boxCenter(backendNodeId);
+            if (!center)
+                continue; // not visible / no layout box
+            ref++;
+            const value = n.value?.value;
+            this.refs.set(ref, { backendNodeId, center });
+            elements.push({ ref, role, name, value, center });
+        }
+        const [url, title] = await Promise.all([
+            this.evaluate("location.href"),
+            this.evaluate("document.title"),
+        ]);
+        const text = elements
+            .map((e) => `[${e.ref}] ${e.role} ${JSON.stringify(e.name)}${e.value ? ` =${JSON.stringify(e.value)}` : ""}`)
+            .join("\n");
+        return { url, title, text, elements };
+    }
+    async boxCenter(backendNodeId) {
+        try {
+            const { model } = await this.send("DOM.getBoxModel", { backendNodeId });
+            const q = model.content; // [x1,y1, x2,y2, x3,y3, x4,y4]
+            const x = (q[0] + q[2] + q[4] + q[6]) / 4;
+            const y = (q[1] + q[3] + q[5] + q[7]) / 4;
+            if ((model.width ?? 0) <= 0 || (model.height ?? 0) <= 0)
+                return null;
+            return { x, y };
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Move the cursor along a human curve to a target point. */
+    async moveTo(target) {
+        const path = mousePath(this.mouse, target, this.rng);
+        for (const p of path) {
+            await this.send("Input.dispatchMouseEvent", {
+                type: "mouseMoved",
+                x: p.x,
+                y: p.y,
+                buttons: 0,
+            });
+            await sleep(moveDelay(this.rng));
+        }
+        this.mouse = target;
+    }
+    /** Click an element by its snapshot ref. */
+    async click(ref) {
+        const target = this.refs.get(ref);
+        if (!target)
+            throw new Error(`No element with ref ${ref}. Call snapshot() first.`);
+        await this.moveTo(target.center);
+        await sleep(this.rng.range(30, 90));
+        const common = { x: target.center.x, y: target.center.y, button: "left", clickCount: 1 };
+        await this.send("Input.dispatchMouseEvent", { type: "mousePressed", buttons: 1, ...common });
+        await sleep(this.rng.range(40, 110)); // press dwell
+        await this.send("Input.dispatchMouseEvent", { type: "mouseReleased", buttons: 0, ...common });
+    }
+    /** Bring this page's target to the foreground — CDP Input only routes to the active target. */
+    async bringToFront() {
+        await this.send("Page.bringToFront");
+    }
+    /** Trusted click at absolute viewport coords (when you can't resolve a snapshot ref). */
+    async clickAt(x, y) {
+        await this.moveTo({ x, y });
+        await sleep(this.rng.range(30, 90));
+        const common = { x, y, button: "left", clickCount: 1 };
+        await this.send("Input.dispatchMouseEvent", { type: "mousePressed", buttons: 1, ...common });
+        await sleep(this.rng.range(40, 110));
+        await this.send("Input.dispatchMouseEvent", { type: "mouseReleased", buttons: 0, ...common });
+    }
+    /** Type text into the focused element with human cadence. */
+    async type(text) {
+        for (const ch of text) {
+            await this.send("Input.dispatchKeyEvent", { type: "keyDown", text: ch });
+            await this.send("Input.dispatchKeyEvent", { type: "keyUp", text: ch });
+            await sleep(keyDelay(this.rng, ch));
+        }
+    }
+    /** Click a field then type into it. */
+    async fill(ref, text) {
+        await this.click(ref);
+        await sleep(this.rng.range(60, 160));
+        await this.type(text);
+    }
+    /** Capture a PNG screenshot (Buffer) — feed to a vision model. */
+    async screenshot(opts = {}) {
+        const params = { format: "png" };
+        if (opts.fullPage)
+            params.captureBeyondViewport = true;
+        const { data } = await this.send("Page.captureScreenshot", params);
+        return Buffer.from(data, "base64");
+    }
+    /** Poll an expression until truthy (replaces flaky fixed sleeps). */
+    async waitFor(expression, opts = {}) {
+        const timeout = opts.timeout ?? 10000;
+        const poll = opts.poll ?? 100;
+        const start = Date.now();
+        while (Date.now() - start < timeout) {
+            if (await this.evaluate(`!!(${expression})`))
+                return;
+            await sleep(poll);
+        }
+        throw new Error(`waitFor timed out: ${expression}`);
+    }
+    /**
+     * Attach local files to a file `<input>` — even a hidden one — without an OS
+     * file picker. Uses CDP DOM.setFileInputFiles (the same primitive Playwright
+     * uses under the hood), which sets `input.files` and fires `change` directly.
+     * `selector` defaults to the first file input; pass a more specific one if the
+     * page has several. Paths must be absolute.
+     */
+    async uploadFile(paths, selector = 'input[type="file"]') {
+        const { root } = await this.send("DOM.getDocument", { depth: 0 });
+        const { nodeId } = await this.send("DOM.querySelector", {
+            nodeId: root.nodeId,
+            selector,
+        });
+        if (!nodeId)
+            throw new Error(`uploadFile: no element matching ${selector}`);
+        await this.send("DOM.setFileInputFiles", { files: paths, nodeId });
+    }
+    /**
+     * Attach files through a control that opens a file picker (e.g. an "Upload
+     * files" menu item) WITHOUT an OS dialog. Intercepts the chooser via CDP,
+     * clicks the trigger, then feeds the paths to the input it opened for. This is
+     * the path for SPAs (like Gemini) that create the `<input>` lazily on click.
+     * Paths must be absolute.
+     */
+    async uploadViaPicker(triggerRef, paths, opts = {}) {
+        await this.send("Page.setInterceptFileChooserDialog", { enabled: true });
+        try {
+            // Listen on any session — the chooser event can arrive without our page
+            // sessionId attached, which silently filtered it out before.
+            const chooser = this.cdp.once("Page.fileChooserOpened", {
+                timeout: opts.timeout ?? 15000,
+            });
+            await this.click(triggerRef);
+            const ev = await chooser;
+            await this.send("DOM.setFileInputFiles", { files: paths, backendNodeId: ev.backendNodeId });
+        }
+        finally {
+            await this.send("Page.setInterceptFileChooserDialog", { enabled: false });
+        }
+    }
+    /** Read the page's visible text (for scraping a model response, etc.). */
+    async innerText() {
+        return this.evaluate("document.body ? document.body.innerText : ''");
+    }
+    /** Press a single named key on the focused element (Enter, Tab, Escape, arrows...). */
+    async press(key) {
+        const KEYS = {
+            Enter: { code: "Enter", vk: 13, text: "\r" },
+            Tab: { code: "Tab", vk: 9 },
+            Escape: { code: "Escape", vk: 27 },
+            Backspace: { code: "Backspace", vk: 8 },
+            ArrowDown: { code: "ArrowDown", vk: 40 },
+            ArrowUp: { code: "ArrowUp", vk: 38 },
+        };
+        const k = KEYS[key];
+        if (!k)
+            throw new Error(`press: unsupported key ${key}`);
+        const base = { key, code: k.code, windowsVirtualKeyCode: k.vk, nativeVirtualKeyCode: k.vk };
+        await this.send("Input.dispatchKeyEvent", { type: "rawKeyDown", ...base, ...(k.text ? { text: k.text } : {}) });
+        if (k.text)
+            await this.send("Input.dispatchKeyEvent", { type: "char", ...base, text: k.text });
+        await this.send("Input.dispatchKeyEvent", { type: "keyUp", ...base });
+    }
+    // --- FedCM: drive federated sign-in ("Sign in with Google" one-tap, etc.) ---
+    // Chrome renders FedCM account choosers as native browser UI that no synthetic
+    // mouse click can reach (the button is a cross-origin IdP iframe, and the
+    // chooser itself is browser chrome). FedCm.enable routes the dialog to us over
+    // CDP instead, so an agent can actually complete a federated login.
+    // End-to-end run: examples/fedcm.ts.
+    /**
+     * Start intercepting FedCM on this page. Call it ON DEMAND, right before the
+     * sign-in you're driving — never as blanket startup setup. Any page that
+     * silently probes FedCM at load (GoHighLevel, many SaaS logins) will HANG if
+     * interception is on and nothing resolves the probe, so keep it off until you
+     * need it and disableFedCm() afterwards.
+     *
+     * With {autoSelectFirst:true} (default) veil selects account 0 on every dialog
+     * automatically — the one-liner for "just sign me in". Pass false to inspect
+     * accounts via waitForFedCmDialog() and choose with selectFedCmAccount().
+     */
+    async enableFedCm(opts = {}) {
+        const autoSelect = opts.autoSelectFirst ?? true;
+        await this.send("FedCm.enable", { disableRejectionDelay: true });
+        // A prior dismissal drops the IdP into a cooldown where the dialog silently
+        // won't reappear; clear it so the next trigger actually shows.
+        try {
+            await this.send("FedCm.resetCooldown");
+        }
+        catch { }
+        if (this.fedcmOff)
+            return;
+        this.fedcmOff = this.cdp.on("FedCm.dialogShown", (p) => {
+            const dialog = {
+                dialogId: p.dialogId,
+                type: p.dialogType,
+                title: p.title,
+                subtitle: p.subtitle,
+                accounts: (p.accounts ?? []).map((a) => ({
+                    accountId: a.accountId,
+                    email: a.email,
+                    name: a.name,
+                    givenName: a.givenName,
+                    idpConfigUrl: a.idpConfigUrl,
+                })),
+            };
+            this.lastFedcmDialogId = dialog.dialogId;
+            // Bind selection to THIS session. CDP strips the sessionId off the event
+            // params, and selecting on the wrong target leaves the dialog — and the
+            // RP page's navigator.credentials.get() — hanging unresolved.
+            if (autoSelect && dialog.accounts.length) {
+                this.selectFedCmAccount(0, dialog.dialogId).catch(() => { });
+            }
+            const waiter = this.fedcmWaiters.shift();
+            if (waiter)
+                waiter(dialog);
+            else
+                this.fedcmQueue.push(dialog);
+        }, this.sessionId);
+    }
+    /** Resolve with the next FedCM dialog (or one already queued since enable). */
+    async waitForFedCmDialog(opts = {}) {
+        const queued = this.fedcmQueue.shift();
+        if (queued)
+            return queued;
+        return new Promise((resolve, reject) => {
+            const waiter = (d) => {
+                clearTimeout(timer);
+                resolve(d);
+            };
+            const timer = setTimeout(() => {
+                const i = this.fedcmWaiters.indexOf(waiter);
+                if (i >= 0)
+                    this.fedcmWaiters.splice(i, 1);
+                reject(new Error("waitForFedCmDialog: timed out (is FedCM enabled, and are you signed in to the IdP?)"));
+            }, opts.timeout ?? 30000);
+            this.fedcmWaiters.push(waiter);
+        });
+    }
+    /** Pick an account in the current FedCM dialog (index into dialog.accounts). */
+    async selectFedCmAccount(accountIndex = 0, dialogId = this.lastFedcmDialogId) {
+        if (!dialogId)
+            throw new Error("selectFedCmAccount: no FedCM dialog has appeared yet");
+        await this.send("FedCm.selectAccount", { dialogId, accountIndex });
+    }
+    /** Dismiss the current FedCM dialog (decline the sign-in). */
+    async dismissFedCm(dialogId = this.lastFedcmDialogId) {
+        if (!dialogId)
+            return;
+        await this.send("FedCm.dismissDialog", { dialogId, triggerCooldown: false });
+    }
+    /** Stop intercepting FedCM. Call after a sign-in so a later navigation that
+     *  probes FedCM isn't left hanging on us. */
+    async disableFedCm() {
+        this.fedcmOff?.();
+        this.fedcmOff = undefined;
+        this.fedcmQueue = [];
+        this.fedcmWaiters = [];
+        try {
+            await this.send("FedCm.disable");
+        }
+        catch { }
+    }
+    /**
+     * One call to complete an active federated sign-in: enables FedCM, clicks the
+     * "Sign in with Google" button (a snapshot ref), waits for the account
+     * chooser, selects an account, and returns it. For passive/one-tap flows that
+     * fire on page load, enableFedCm() BEFORE navigating, then
+     * waitForFedCmDialog() — the default autoSelectFirst signs you straight in.
+     */
+    async signInWithFedCm(opts = {}) {
+        await this.enableFedCm({ autoSelectFirst: false });
+        if (opts.triggerRef != null)
+            await this.click(opts.triggerRef);
+        const dialog = await this.waitForFedCmDialog({ timeout: opts.timeout });
+        const idx = opts.accountIndex ?? 0;
+        const account = dialog.accounts[idx];
+        if (!account)
+            throw new Error(`signInWithFedCm: no account at index ${idx} (dialog had ${dialog.accounts.length})`);
+        await this.selectFedCmAccount(idx, dialog.dialogId);
+        return account;
+    }
+    /**
+     * Stop the page — and any site it loads — from reaching loopback / private
+     * hosts. Detectors port-scan 127.0.0.1 from JS to fingerprint the machine's
+     * other software (and it leaks your LAN to every site). With this on, each
+     * such request is failed UNIFORMLY (same instant error, open port or closed),
+     * so the scan can't tell them apart and comes back empty. Only private-host
+     * requests are intercepted, so normal browsing keeps its exact timing.
+     *
+     * Still allowed: the agent's own top-level navigation to a private host
+     * (page.goto("http://localhost:3000")), and a localhost page loading its own
+     * localhost resources — only a PUBLIC page reaching a private host is blocked.
+     */
+    async blockPrivateNetwork() {
+        if (this.blockPrivateOff)
+            return;
+        // Learn the main frame so we can tell an agent nav from a page's own probe.
+        try {
+            const { frameTree } = await this.send("Page.getFrameTree");
+            this.mainFrameId = frameTree?.frame?.id;
+            this.topPrivate = isPrivateHost(frameTree?.frame?.url ?? "");
+        }
+        catch { }
+        const offNav = this.cdp.on("Page.frameNavigated", (p) => {
+            const f = p.frame;
+            if (f && !f.parentId) {
+                this.mainFrameId = f.id;
+                this.topPrivate = isPrivateHost(f.url ?? "");
+            }
+        }, this.sessionId);
+        await this.send("Fetch.enable", { patterns: PRIVATE_URL_PATTERNS });
+        const offFetch = this.cdp.on("Fetch.requestPaused", (p) => {
+            const url = p.request?.url ?? "";
+            // Allow: agent-driven top-level nav, and a private page's own resources.
+            // Block: any other private-host request from a public page (the scan).
+            const isMainNav = p.resourceType === "Document" && p.frameId === this.mainFrameId;
+            if (isPrivateHost(url) && !isMainNav && !this.topPrivate) {
+                this.send("Fetch.failRequest", { requestId: p.requestId, errorReason: "AccessDenied" }).catch(() => { });
+            }
+            else {
+                this.send("Fetch.continueRequest", { requestId: p.requestId }).catch(() => { });
+            }
+        }, this.sessionId);
+        this.blockPrivateOff = () => { offNav(); offFetch(); };
+    }
+    /** Lift the private-network block (re-allows localhost/LAN requests). */
+    async unblockPrivateNetwork() {
+        this.blockPrivateOff?.();
+        this.blockPrivateOff = undefined;
+        try {
+            await this.send("Fetch.disable");
+        }
+        catch { }
+    }
+    /** Close this page and detach its target from the browser. Idempotent. */
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.refs.clear();
+        if (this.targetId) {
+            try {
+                // Target.closeTarget closes the page/target and frees its resources.
+                // Send to browser context (no sessionId) since we're closing the target itself.
+                await this.cdp.send("Target.closeTarget", { targetId: this.targetId });
+            }
+            catch {
+                // Target already closed or doesn't exist; this is OK.
+            }
+        }
+        // Clean up any lingering event handlers for this session
+        this.cdp.clearHandlers(this.sessionId);
+    }
+}

package/dist/stealth.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The page-side stealth patch — minimal and SELF-GATING.
+ *
+ * Hard-won lesson: on a real, properly-launched Chrome, the "tells" stealth
+ * bundles fix don't exist. `--disable-blink-features=AutomationControlled`
+ * already yields `navigator.webdriver === false` (the correct *human* value —
+ * NOT `undefined`, which is itself anomalous). A real profile already has the
+ * `chrome` object, 5 plugins, and real `languages`. Blindly overriding those
+ * doesn't help — and the overrides themselves (a patched `permissions.query`,
+ * a faked `toString`) are the precise signatures deep fingerprinters score as
+ * "stealth detected".
+ *
+ * So every patch here is gated: it fires ONLY when the value is actually wrong
+ * (e.g. a stripped/headless environment leaked `webdriver === true` or 0 plugins).
+ * On a healthy real Chrome this injects a script that observably does nothing.
+ *
+ * The WebGL vendor override is the one opt-in (`maskWebgl`), used solely to hide
+ * SwiftShader on GPU-less hosts. With a real GPU it stays off — the authentic
+ * vendor is consistent with the rendered pixels, so masking would be a lie.
+ */
+export interface StealthOptions {
+    maskWebgl?: boolean;
+    webglVendor?: string;
+    webglRenderer?: string;
+}
+export declare function buildStealth(opts?: StealthOptions): string;
+/** Default stealth source: self-gating, no WebGL masking (authentic GPU fingerprint). */
+export declare const STEALTH_SOURCE: string;

package/dist/stealth.js

@@ -0,0 +1,74 @@
+export function buildStealth(opts = {}) {
+    const maskWebgl = opts.maskWebgl ?? false;
+    const vendor = opts.webglVendor ?? "Google Inc. (Intel)";
+    const renderer = opts.webglRenderer ?? "ANGLE (Intel, Mesa Intel(R) UHD Graphics)";
+    // Only emitted for SwiftShader hosts. When present it also needs the toString
+    // mask so the getParameter override can't be read back as non-native.
+    const webglBlock = maskWebgl
+        ? String.raw `
+  try {
+    const proto = WebGLRenderingContext && WebGLRenderingContext.prototype;
+    if (proto) {
+      const getParameter = proto.getParameter;
+      proto.getParameter = function (p) {
+        if (p === 37445) return ${JSON.stringify(vendor)};
+        if (p === 37446) return ${JSON.stringify(renderer)};
+        return getParameter.apply(this, arguments);
+      };
+      const native = Function.prototype.toString;
+      const masked = proto.getParameter;
+      Function.prototype.toString = function () {
+        if (this === masked || this === Function.prototype.toString) return 'function () { [native code] }';
+        return native.call(this);
+      };
+    }
+  } catch (e) {}`
+        : "";
+    return String.raw `
+(() => {
+  if (window.__veil) return;
+  Object.defineProperty(window, '__veil', { value: true, enumerable: false });
+
+  const patchGetter = (obj, prop, value) => {
+    try { Object.defineProperty(obj, prop, { get: () => value, configurable: true, enumerable: true }); } catch (e) {}
+  };
+
+  // webdriver: fix ONLY if automation leaked it as true. Real Chrome's false is correct.
+  try { if (navigator.webdriver === true) patchGetter(Object.getPrototypeOf(navigator), 'webdriver', false); } catch (e) {}
+
+  // chrome object: add only if a stripped build is missing it.
+  if (!window.chrome) window.chrome = { runtime: {} };
+
+  // plugins: backfill only if empty (real desktop reports the PDF viewers).
+  try {
+    if (navigator.plugins && navigator.plugins.length === 0) {
+      patchGetter(Object.getPrototypeOf(navigator), 'plugins', [
+        { name: 'PDF Viewer', filename: 'internal-pdf-viewer', description: 'Portable Document Format' },
+        { name: 'Chrome PDF Viewer', filename: 'internal-pdf-viewer', description: 'Portable Document Format' },
+      ]);
+    }
+  } catch (e) {}
+
+  // languages: backfill only if empty.
+  if (!navigator.languages || navigator.languages.length === 0) {
+    patchGetter(Object.getPrototypeOf(navigator), 'languages', ['en-US', 'en']);
+  }
+
+  // DELIBERATELY NOT PATCHED — deviceMemory and screen.availHeight.
+  // A tempting "fix" is to clamp deviceMemory to the spec max of 8, and to shave
+  // a taskbar inset off availHeight on a WM-less Xvfb (where availHeight === height).
+  // Both were tried and REMOVED: a JS getter override is itself the tell. A
+  // fingerprinter reading the property descriptor's getter sees "() => value"
+  // instead of "[native code]", or notices availHeight became an OWN property of
+  // the screen instance instead of being inherited from Screen.prototype. That is
+  // the exact "masking detected" signature veil exists to avoid — worse than the
+  // anomalous value it hid. On a real user's machine these values are already sane
+  // (Chrome caps deviceMemory at 8; a real desktop has a taskbar), so nothing needs
+  // patching. On a headless server box that leaks an out-of-spec deviceMemory, fix
+  // it at the source (the host), never with a getter a page can unmask.
+${webglBlock}
+})();
+`;
+}
+/** Default stealth source: self-gating, no WebGL masking (authentic GPU fingerprint). */
+export const STEALTH_SOURCE = buildStealth();

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@achamm/veilbrowser",
+  "version": "0.3.0",
+  "description": "Stealth browser automation for AI agents. Drives real Chrome over raw CDP—no Playwright, no Puppeteer, no WebDriver. Zero runtime dependencies. Passes bot.sannysoft.com 57/57; bypasses Cloudflare's JS challenge.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "selftest": "bun run examples/selftest.ts",
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "bun test tests/*.test.ts",
+    "prepublishOnly": "bun run build"
+  },
+  "keywords": [
+    "browser",
+    "automation",
+    "stealth",
+    "cdp",
+    "chrome",
+    "agent",
+    "ai",
+    "anti-bot",
+    "anti-detect",
+    "mcp",
+    "cloudflare",
+    "scraping"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/acunningham-ship-it/veilbrowser.git"
+  },
+  "homepage": "https://github.com/acunningham-ship-it/veilbrowser#readme",
+  "bugs": {
+    "url": "https://github.com/acunningham-ship-it/veilbrowser/issues"
+  },
+  "author": "Armani Cunningham <acunningham@crazeemedia.com>",
+  "engines": {
+    "node": ">=24.0.0",
+    "bun": ">=1.0.0"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^25.9.2",
+    "typescript": "^6.0.3"
+  }
+}