@achamm/veilbrowser 0.3.0

package/dist/launcher.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Launches a REAL, unmodified Chrome. To a website, this process IS Chrome —
+ * identical TLS, identical JS engine, identical canvas/WebGL/font fingerprint —
+ * because it literally is the same binary a human runs.
+ *
+ * The whole stealth game at launch time is: don't add the switches that
+ * Puppeteer/Playwright add. Those tools flip on `--enable-automation` and a
+ * batch of `--disable-*` flags that change behaviour in fingerprintable ways.
+ * We launch with the flags a normal Chrome uses, minus the noise.
+ */
+import { type ChildProcess } from "node:child_process";
+export declare function findChrome(): string;
+export interface LaunchOptions {
+    headless?: boolean;
+    userDataDir?: string;
+    chromePath?: string;
+    windowSize?: {
+        width: number;
+        height: number;
+    };
+    /**
+     * Virtual-display (Xvfb) resolution — the `screen.*` a page sees. Defaults to a
+     * realistic desktop 1920x1080 so the Chrome window sits INSIDE the screen. A
+     * virtual display sized to the window (screen === window, window taller than
+     * screen) is a classic headless tell; a real monitor is bigger than the window.
+     * Only applies to veil's own auto-Xvfb, not an external DISPLAY.
+     */
+    screenSize?: {
+        width: number;
+        height: number;
+    };
+    proxy?: string;
+    /**
+     * Block visited sites from reaching loopback / private-network hosts (default
+     * true). Detectors port-scan 127.0.0.1 from JS to fingerprint the machine's
+     * other software; it also leaks your LAN to every page. The agent's own
+     * top-level navigation to a private host still works. Set false to allow a
+     * page to reach localhost (e.g. driving your own local app via subresources).
+     */
+    blockPrivateNetwork?: boolean;
+    /**
+     * WebGL backend:
+     *  - "hardware": use the real GPU via ANGLE/EGL → genuine, consistent vendor.
+     *    Works headless AND headful (no Xvfb needed). Best stealth — nothing spoofed.
+     *  - "software": SwiftShader + a spoofed Intel vendor. For GPU-less hosts only.
+     *  - "off": no GL flags.
+     *  - "auto" (default): "hardware" if a DRI render node is accessible, else "software".
+     */
+    gpu?: "hardware" | "software" | "off" | "auto";
+    /**
+     * Run headful on a virtual X display via Xvfb — "headful on a server". Headful
+     * Chrome scores far better against deep fingerprinters than headless (no
+     * headless render quirks, real screen size). Default "auto": on when headful is
+     * requested (headless:false) and there's no real DISPLAY. Requires Xvfb on PATH.
+     */
+    xvfb?: boolean;
+    extraArgs?: string[];
+}
+export interface LaunchResult {
+    webSocketDebuggerUrl: string;
+    process: ChildProcess;
+    userDataDir: string;
+    /** True only for SwiftShader (software) — the page layer should then mask the vendor. */
+    maskWebgl: boolean;
+    kill: () => void;
+}
+export declare function launchChrome(opts?: LaunchOptions): Promise<LaunchResult>;

package/dist/launcher.js

@@ -0,0 +1,272 @@
+/**
+ * Launches a REAL, unmodified Chrome. To a website, this process IS Chrome —
+ * identical TLS, identical JS engine, identical canvas/WebGL/font fingerprint —
+ * because it literally is the same binary a human runs.
+ *
+ * The whole stealth game at launch time is: don't add the switches that
+ * Puppeteer/Playwright add. Those tools flip on `--enable-automation` and a
+ * batch of `--disable-*` flags that change behaviour in fingerprintable ways.
+ * We launch with the flags a normal Chrome uses, minus the noise.
+ */
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, readlinkSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+const CANDIDATES = [
+    process.env.VEIL_CHROME,
+    "/opt/google/chrome/chrome",
+    "/usr/bin/google-chrome",
+    "/usr/bin/google-chrome-stable",
+    "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+    "/usr/bin/chromium",
+    "/usr/bin/chromium-browser",
+    "/snap/bin/chromium",
+].filter(Boolean);
+export function findChrome() {
+    for (const c of CANDIDATES)
+        if (existsSync(c))
+            return c;
+    throw new Error("No Chrome/Chromium found. Set VEIL_CHROME=/path/to/chrome");
+}
+const RENDER_NODE = "/dev/dri/renderD128";
+const wait = (ms) => new Promise((r) => setTimeout(r, ms));
+const LIVE = new Set();
+let reaperInstalled = false;
+function killGroup(proc) {
+    const pid = proc?.pid;
+    if (!pid)
+        return;
+    try {
+        process.kill(-pid, "SIGKILL"); // negative pid = the whole process group
+    }
+    catch {
+        try {
+            proc.kill("SIGKILL"); // group already gone → fall back to the single pid
+        }
+        catch { }
+    }
+}
+function reapAll() {
+    for (const b of LIVE) {
+        killGroup(b.child);
+        killGroup(b.xvfb);
+    }
+}
+const SIGNAL_EXIT = { SIGINT: 130, SIGTERM: 143, SIGHUP: 129 };
+function installReaper() {
+    if (reaperInstalled)
+        return;
+    reaperInstalled = true;
+    // 'exit' fires on a normal return AND during an uncaught-exception exit — sync
+    // context, exactly right for a group-kill.
+    process.on("exit", reapAll);
+    // Signals don't run 'exit' handlers on their own, so catch them, reap, and then
+    // leave with the conventional 128+signum code.
+    for (const sig of Object.keys(SIGNAL_EXIT)) {
+        process.on(sig, () => {
+            reapAll();
+            process.exit(SIGNAL_EXIT[sig]);
+        });
+    }
+}
+/** Start an Xvfb virtual display; resolves once it's ready, or null if unavailable. */
+async function startXvfb(width, height) {
+    let n = 99;
+    for (; n < 160; n++)
+        if (!existsSync(`/tmp/.X${n}-lock`))
+            break;
+    const display = `:${n}`;
+    let proc;
+    try {
+        proc = spawn("Xvfb", [display, "-screen", "0", `${width}x${height}x24`, "-nolisten", "tcp"], {
+            stdio: "ignore",
+        });
+    }
+    catch {
+        return null;
+    }
+    let exited = false;
+    proc.on("exit", () => (exited = true));
+    const start = Date.now();
+    while (!existsSync(`/tmp/.X${n}-lock`) && !exited && Date.now() - start < 5000)
+        await wait(50);
+    if (exited)
+        return null;
+    return { display, proc };
+}
+/** Resolve "auto" → real GPU if we can reach the render node, else SwiftShader. */
+function resolveGpu(mode) {
+    if (mode && mode !== "auto")
+        return mode;
+    try {
+        // accessSync would import fs; existsSync is already imported and the ACL
+        // grants read here. Presence of the node is a good-enough hardware signal.
+        return existsSync(RENDER_NODE) ? "hardware" : "software";
+    }
+    catch {
+        return "software";
+    }
+}
+export async function launchChrome(opts = {}) {
+    const chromePath = opts.chromePath ?? findChrome();
+    const ephemeral = !opts.userDataDir;
+    const userDataDir = opts.userDataDir ?? join(tmpdir(), `veil-${process.pid}-${Date.now()}`);
+    mkdirSync(userDataDir, { recursive: true });
+    // Reused profiles leave a stale DevToolsActivePort from the previous Chrome;
+    // waitForPort would read the OLD port and connect to a dead endpoint. Clear it
+    // so we wait for THIS launch's fresh port.
+    rmSync(join(userDataDir, "DevToolsActivePort"), { force: true });
+    // SingletonLock records who owns this profile — Chrome writes it as a symlink
+    // "<host>-<pid>". Only clear a STALE lock (its pid is dead). If a LIVE Chrome
+    // still owns the profile, REFUSE: two Chromes on one userDataDir silently
+    // corrupt it (this was the real cause of an "Initializing…" hang). Blindly
+    // removing the lock, as before, let that corruption happen.
+    const lockPath = join(userDataDir, "SingletonLock");
+    let ownerPid = -1; // -1 = no lock present
+    try {
+        ownerPid = parseInt(readlinkSync(lockPath).split("-").pop() || "", 10);
+    }
+    catch { }
+    if (ownerPid > 0) {
+        let alive = false;
+        try {
+            process.kill(ownerPid, 0);
+            alive = true;
+        }
+        catch (e) {
+            alive = e?.code === "EPERM";
+        }
+        if (alive) {
+            throw new Error(`Profile "${userDataDir}" is already in use by Chrome (pid ${ownerPid}). ` +
+                `Close it, or launch with a different userDataDir.`);
+        }
+    }
+    rmSync(lockPath, { force: true }); // absent or stale → safe to clear
+    rmSync(join(userDataDir, "SingletonCookie"), { force: true });
+    rmSync(join(userDataDir, "SingletonSocket"), { force: true });
+    // The screen (virtual display) is a realistic desktop; the window sits INSIDE it
+    // and is never larger than it, positioned like a real user's window so that
+    // screen.* > window.outer.*, availHeight leaves room for a taskbar, and
+    // screenX/screenY are non-zero — none of the "display sized to the window" tells.
+    const screen = opts.screenSize ?? { width: 1920, height: 1080 };
+    const win = opts.windowSize ?? { width: 1280, height: 800 };
+    const width = Math.min(win.width, screen.width);
+    const height = Math.min(win.height, screen.height);
+    const posX = Math.max(0, (screen.width - width) >> 1);
+    const posY = Math.max(0, (screen.height - height) >> 1);
+    // Port 0 => Chrome picks a free port and writes it to DevToolsActivePort.
+    const args = [
+        `--remote-debugging-port=0`,
+        `--user-data-dir=${userDataDir}`,
+        `--window-size=${width},${height}`,
+        `--window-position=${posX},${posY}`,
+        // Stealth: navigator.webdriver is gated behind this blink feature. Disabling
+        // the "AutomationControlled" feature makes navigator.webdriver === false,
+        // matching a normal browser. (Playwright historically left it true.)
+        `--disable-blink-features=AutomationControlled`,
+        // Quiet, non-suspicious startup — these match a fresh real profile, they are
+        // NOT the automation-only switches that change fingerprintable behaviour.
+        `--no-first-run`,
+        `--no-default-browser-check`,
+        `--disable-features=Translate,OptimizationHints`,
+        `--password-store=basic`,
+        `--homepage=about:blank`,
+        `about:blank`,
+    ];
+    if (opts.headless) {
+        // headless=new is the modern engine; still more detectable than headful,
+        // so it's opt-in. Default product mode is headful on a real display/Xvfb.
+        args.unshift("--headless=new");
+    }
+    // WebGL backend. Hardware (real GPU via ANGLE/EGL) is preferred — it gives an
+    // authentic, self-consistent fingerprint and works headless without Xvfb. We
+    // only fall back to SwiftShader (and then mask its vendor) when there's no GPU.
+    const gpu = resolveGpu(opts.gpu);
+    let maskWebgl = false;
+    if (gpu === "hardware") {
+        args.push("--use-gl=angle", "--use-angle=gl-egl");
+    }
+    else if (gpu === "software") {
+        args.push("--use-gl=angle", "--use-angle=swiftshader", "--enable-unsafe-swiftshader");
+        maskWebgl = true; // SwiftShader's vendor is a server tell — hide it.
+    }
+    if (opts.proxy)
+        args.push(`--proxy-server=${opts.proxy}`);
+    if (opts.extraArgs)
+        args.push(...opts.extraArgs);
+    // Headful on a server: bring up our own Xvfb display if there isn't a real one.
+    const childEnv = { ...process.env };
+    let xvfbProc = null;
+    const wantXvfb = opts.xvfb ?? (!opts.headless && !process.env.DISPLAY);
+    if (wantXvfb) {
+        const xvfb = await startXvfb(screen.width, screen.height);
+        if (xvfb) {
+            xvfbProc = xvfb.proc;
+            childEnv.DISPLAY = xvfb.display;
+        }
+        else if (!process.env.DISPLAY) {
+            // No virtual display available — degrade gracefully to headless rather than
+            // failing the whole launch. Still uses the real GPU; just a higher headless
+            // heuristic score. Better a working browser than none.
+            args.unshift("--headless=new");
+        }
+    }
+    // detached => Chrome leads its own process group, so killGroup() can take down
+    // the whole renderer/gpu/zygote tree in one shot instead of orphaning it.
+    const child = spawn(chromePath, args, { stdio: ["ignore", "ignore", "pipe"], env: childEnv, detached: true });
+    const live = { child, xvfb: xvfbProc, userDataDir, ephemeral };
+    LIVE.add(live);
+    installReaper();
+    // If Chrome dies on its own (crash, external kill), drop it from the reaper set,
+    // tear down its Xvfb, and clean an ephemeral profile — no leak, no stale dir.
+    child.on("exit", () => {
+        LIVE.delete(live);
+        killGroup(xvfbProc);
+        if (ephemeral) {
+            try {
+                rmSync(userDataDir, { recursive: true, force: true });
+            }
+            catch { }
+        }
+    });
+    const portFile = join(userDataDir, "DevToolsActivePort");
+    const wsPath = await waitForPort(portFile, child);
+    const port = wsPath.port;
+    // Fetch the browser-level WebSocket endpoint from Chrome's HTTP side.
+    const res = await fetch(`http://127.0.0.1:${port}/json/version`);
+    const info = (await res.json());
+    const kill = () => {
+        LIVE.delete(live);
+        killGroup(child); // whole process group, not just the main pid
+        killGroup(xvfbProc);
+        if (ephemeral) {
+            try {
+                rmSync(userDataDir, { recursive: true, force: true });
+            }
+            catch { }
+        }
+    };
+    return { webSocketDebuggerUrl: info.webSocketDebuggerUrl, process: child, userDataDir, maskWebgl, kill };
+}
+function waitForPort(portFile, child) {
+    return new Promise((resolve, reject) => {
+        let stderr = "";
+        child.stderr?.on("data", (d) => (stderr += d.toString()));
+        child.on("exit", (code) => reject(new Error(`Chrome exited early (code ${code}).\n${stderr.slice(-600)}`)));
+        const start = Date.now();
+        const tick = () => {
+            if (existsSync(portFile)) {
+                try {
+                    const port = parseInt(readFileSync(portFile, "utf8").split("\n")[0].trim(), 10);
+                    if (port > 0)
+                        return resolve({ port });
+                }
+                catch { }
+            }
+            if (Date.now() - start > 15000)
+                return reject(new Error("Chrome never opened a debug port"));
+            setTimeout(tick, 50);
+        };
+        tick();
+    });
+}

package/dist/mcp.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/mcp.js

@@ -0,0 +1,156 @@
+/**
+ * Veil MCP server (stdio, JSON-RPC 2.0, newline-delimited).
+ *
+ * Exposes the Veil browser as tools any MCP-speaking agent can drive — persoje,
+ * Claude Code, etc. Hand-rolled (no @modelcontextprotocol/sdk) to keep Veil's
+ * zero-dependency story intact. One browser + one active page per server process;
+ * extend to a page registry when you need parallel tabs.
+ *
+ *   bun run src/mcp.ts            # headful (stealthiest)
+ *   VEIL_HEADLESS=1 bun run src/mcp.ts
+ */
+import { createInterface } from "node:readline";
+import { Browser } from "./browser.js";
+let browser = null;
+let page = null;
+async function ensurePage() {
+    if (!browser)
+        browser = await Browser.launch({ headless: process.env.VEIL_HEADLESS === "1" });
+    if (!page)
+        page = await browser.newPage();
+    return page;
+}
+const TOOLS = [
+    { name: "veil_goto", description: "Navigate the browser to a URL (launches Chrome on first call).",
+        inputSchema: { type: "object", properties: { url: { type: "string" } }, required: ["url"] } },
+    { name: "veil_snapshot", description: "Return the page as a numbered list of interactive elements from the accessibility tree. Use the [ref] numbers with veil_click / veil_fill. No CSS selectors needed.",
+        inputSchema: { type: "object", properties: {} } },
+    { name: "veil_click", description: "Click an element by its snapshot ref (human-like mouse path).",
+        inputSchema: { type: "object", properties: { ref: { type: "number" } }, required: ["ref"] } },
+    { name: "veil_fill", description: "Click a field by ref and type text into it (human cadence).",
+        inputSchema: { type: "object", properties: { ref: { type: "number" }, text: { type: "string" } }, required: ["ref", "text"] } },
+    { name: "veil_type", description: "Type text into the currently focused element.",
+        inputSchema: { type: "object", properties: { text: { type: "string" } }, required: ["text"] } },
+    { name: "veil_screenshot", description: "Capture a PNG screenshot of the page (returned as an image for vision).",
+        inputSchema: { type: "object", properties: {} } },
+    { name: "veil_eval", description: "Evaluate a JS expression in the page and return the value.",
+        inputSchema: { type: "object", properties: { expression: { type: "string" } }, required: ["expression"] } },
+    { name: "veil_fedcm_enable", description: "Arm FedCM interception BEFORE navigating to a site that shows a Google/federated 'one-tap' sign-in on load. Order: veil_fedcm_enable -> veil_goto the sign-in page -> veil_fedcm_signin. (Skip this for an active 'Sign in with Google' button; veil_fedcm_signin arms itself when you pass a triggerRef.)",
+        inputSchema: { type: "object", properties: {} } },
+    { name: "veil_fedcm_signin", description: "Complete a federated ('Sign in with Google', FedCM) login that Chrome renders as a native chooser no click can reach: waits for the intercepted account chooser, selects an account, and returns it. Pass triggerRef to first click an active sign-in button; omit it for one-tap/passive flows (call veil_fedcm_enable before navigating). accountIndex defaults to 0.",
+        inputSchema: { type: "object", properties: { triggerRef: { type: "number" }, accountIndex: { type: "number" } } } },
+    { name: "veil_close", description: "Close the browser.", inputSchema: { type: "object", properties: {} } },
+];
+async function callTool(name, args) {
+    if (name === "veil_close") {
+        if (browser)
+            await browser.close();
+        browser = null;
+        page = null;
+        return { content: [{ type: "text", text: "closed" }] };
+    }
+    const p = await ensurePage();
+    switch (name) {
+        case "veil_goto":
+            await p.goto(args.url);
+            return text(`navigated to ${await p.url()}`);
+        case "veil_snapshot": {
+            const s = await p.snapshot();
+            return text(`# ${s.title}\n${s.url}\n\n${s.text || "(no interactive elements)"}`);
+        }
+        case "veil_click":
+            await p.click(args.ref);
+            return text(`clicked [${args.ref}]`);
+        case "veil_fill":
+            await p.fill(args.ref, args.text);
+            return text(`filled [${args.ref}]`);
+        case "veil_type":
+            await p.type(args.text);
+            return text(`typed ${args.text.length} chars`);
+        case "veil_screenshot": {
+            const png = await p.screenshot();
+            return { content: [{ type: "image", data: png.toString("base64"), mimeType: "image/png" }] };
+        }
+        case "veil_eval":
+            return text(JSON.stringify(await p.evaluate(args.expression)));
+        case "veil_fedcm_enable":
+            await p.enableFedCm({ autoSelectFirst: false });
+            return text("FedCM armed. Navigate to the sign-in page (one-tap fires on load), then call veil_fedcm_signin.");
+        case "veil_fedcm_signin": {
+            if (args.triggerRef != null) {
+                await p.enableFedCm({ autoSelectFirst: false });
+                await p.click(args.triggerRef);
+            }
+            const dialog = await p.waitForFedCmDialog({ timeout: args.timeout ?? 30000 });
+            const idx = args.accountIndex ?? 0;
+            const account = dialog.accounts[idx];
+            if (!account) {
+                await p.dismissFedCm();
+                throw new Error(`FedCM dialog had ${dialog.accounts.length} account(s); none at index ${idx}`);
+            }
+            await p.selectFedCmAccount(idx, dialog.dialogId);
+            await p.disableFedCm();
+            return text(`signed in via FedCM as ${account.email ?? account.name ?? account.accountId}`);
+        }
+        default:
+            throw new Error(`unknown tool: ${name}`);
+    }
+}
+const text = (t) => ({ content: [{ type: "text", text: t }] });
+// --- JSON-RPC stdio loop ---
+const send = (msg) => {
+    process.stdout.write(JSON.stringify(msg) + "\n");
+};
+async function handle(msg) {
+    const { id, method, params } = msg;
+    try {
+        if (method === "initialize") {
+            send({ jsonrpc: "2.0", id, result: {
+                    protocolVersion: "2024-11-05",
+                    capabilities: { tools: {} },
+                    serverInfo: { name: "veil", version: "0.3.0" },
+                } });
+            return;
+        }
+        if (method === "notifications/initialized")
+            return; // notification, no reply
+        if (method === "tools/list")
+            return send({ jsonrpc: "2.0", id, result: { tools: TOOLS } });
+        if (method === "tools/call") {
+            const result = await callTool(params.name, params.arguments ?? {});
+            return send({ jsonrpc: "2.0", id, result });
+        }
+        if (id !== undefined)
+            send({ jsonrpc: "2.0", id, error: { code: -32601, message: `method not found: ${method}` } });
+    }
+    catch (e) {
+        if (id !== undefined)
+            send({ jsonrpc: "2.0", id, error: { code: -32603, message: e?.message ?? String(e) } });
+    }
+}
+// Serialize handling: browser state is shared, and a fast request (close) must
+// never overtake a slow one (goto). Chain every message through one promise.
+let chain = Promise.resolve();
+const rl = createInterface({ input: process.stdin });
+rl.on("line", (line) => {
+    const t = line.trim();
+    if (!t)
+        return;
+    let msg;
+    try {
+        msg = JSON.parse(t);
+    }
+    catch {
+        return;
+    }
+    chain = chain.then(() => handle(msg)).catch(() => { });
+});
+const shutdown = async () => {
+    await chain.catch(() => { });
+    if (browser)
+        await browser.close().catch(() => { });
+    process.exit(0);
+};
+rl.on("close", shutdown); // stdin EOF (e.g. piped input)
+process.on("SIGINT", shutdown);
+process.on("SIGTERM", shutdown);