@webcrawl/curl-impersonate 0.0.0-stage → 1.3.1

package/README.md

@@ -1,3 +1,47 @@
-# Temporary Holding Version
+# @webcrawl/curl-impersonate
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Zero-dependency curl-impersonate fetch for Node.js.
+
+One GET hop through a pinned [lexiforest/curl-impersonate](https://github.com/lexiforest/curl-impersonate) binary with a **real-Chrome TLS/HTTP2 fingerprint** — the layer anti-bot WAFs (AWS WAF, Cloudflare Bot Management) judge before any HTML is served. Verified live against AWS-WAF-protected sites where Chrome-136-era fingerprints (`impit`, plain Node `fetch`) get 403/429.
+
+## Why
+
+Anti-bot WAFs fingerprint the TLS ClientHello (JA3/JA4) and HTTP/2 SETTINGS frame — Node's TLS stack matches none of them. curl-impersonate patches BoringSSL (Chrome's TLS library) so the handshake is byte-for-byte a real Chrome. We validated this against live AWS WAF targets: `chrome150` passes where `chrome136` is blocked.
+
+## Usage
+
+```ts
+import { impersonateFetch } from "@webcrawl/curl-impersonate";
+
+const res = await impersonateFetch("https://www.stubhub.com/concert-tickets/", {
+  profile: "chrome150", // default
+  timeoutMs: 12_000,
+});
+// { status: 200, headers, contentType: "text/html", body: Uint8Array }
+```
+
+Redirects are **manual** (not followed): one call = one hop, so you keep SSRF-guarding every redirect the way the webcrawl engine does.
+
+### Profiles
+
+| Profile | Notes |
+|---|---|
+| `chrome150` | default — newest profile verified to pass both stubhub + expedia AWS WAF |
+| `chrome142` | older fallback |
+| `chrome151_macos`, `chrome152` | newer presets from the binary |
+
+Headers (`User-Agent`, `sec-ch-ua`, `Sec-Fetch-*`, `Accept-Language`, `Priority`) are generated per-profile so they stay fingerprint-coherent — a Chrome 150 handshake never carries Chrome 136 client hints.
+
+## Binary acquisition (zero deps)
+
+The binary is downloaded on first use into `~/.cache/webcrawl-impersonate/v2.3.2/<platform>/` (or `os.tmpdir()` when HOME isn't writable — serverless):
+
+1. `WEBCRAWL_IMPERSONATE_BIN=/path/to/curl-impersonate` env override — checked first, skips download.
+2. Cached binary — no network.
+3. Pinned GitHub release asset (`lexiforest/curl-impersonate` v2.3.2), sha256-verified per asset before extraction. Downloads fail soft: the tier reports unavailable and callers fall back.
+
+macOS (arm64/x64), Linux (glibc/musl, arm64/x64). `ensureImpersonate()` pre-warms for CLI/MCP startup; `isImpersonateAvailable()` probes without network.
+
+## License
+
+MIT. The vendored binary is [curl-impersonate](https://github.com/lexiforest/curl-impersonate) (curl + BoringSSL under their own licenses).

package/dist/binary.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Binary acquisition for @webcrawl/curl-impersonate.
+ *
+ * Resolves a pinned lexiforest/curl-impersonate binary for the current
+ * platform, downloading it on first use into a cache dir. All failures
+ * degrade to `null` (tier unavailable, caller falls back) — never throw
+ * into the fetch path.
+ *
+ * Resolution order:
+ *   1. WEBCRAWL_IMPERSONATE_BIN env var (path to a curl-impersonate binary)
+ *   2. Cached binary under <cacheRoot>/webcrawl-impersonate/v2.3.2/<asset>/
+ *   3. First-use download from the pinned GitHub release asset (sha256-verified)
+ */
+export declare const IMPERSONATE_VERSION = "v2.3.2";
+/** Asset name (without `curl-impersonate-v2.3.2.` prefix) -> sha256. */
+export declare const ASSET_SHA256: Record<string, string>;
+/** Node platform/arch -> release asset name. Null when unsupported. */
+export declare function assetForPlatform(platform?: string, arch?: string): string | null;
+export declare function binaryCachePath(asset: string): string;
+/**
+ * Resolve the impersonate binary path, downloading on first use.
+ * Returns null when unavailable — never throws.
+ */
+export declare function ensureBinary(): Promise<string | null>;
+/** Synchronous availability probe (CLI startup, no network). */
+export declare function isBinaryCached(): boolean;
+/** Best-effort liveness check: binary runs and reports a version. */
+export declare function isBinaryHealthy(path: string): boolean;

package/dist/binary.js

@@ -0,0 +1,181 @@
+/**
+ * Binary acquisition for @webcrawl/curl-impersonate.
+ *
+ * Resolves a pinned lexiforest/curl-impersonate binary for the current
+ * platform, downloading it on first use into a cache dir. All failures
+ * degrade to `null` (tier unavailable, caller falls back) — never throw
+ * into the fetch path.
+ *
+ * Resolution order:
+ *   1. WEBCRAWL_IMPERSONATE_BIN env var (path to a curl-impersonate binary)
+ *   2. Cached binary under <cacheRoot>/webcrawl-impersonate/v2.3.2/<asset>/
+ *   3. First-use download from the pinned GitHub release asset (sha256-verified)
+ */
+import { createHash } from "node:crypto";
+import { execFileSync, spawn, spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, chmodSync, renameSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import * as https from "node:https";
+export const IMPERSONATE_VERSION = "v2.3.2";
+const RELEASE_BASE = `https://github.com/lexiforest/curl-impersonate/releases/download/${IMPERSONATE_VERSION}`;
+/** Asset name (without `curl-impersonate-v2.3.2.` prefix) -> sha256. */
+export const ASSET_SHA256 = {
+    "arm64-macos": "638ed43cc93cb5da91f794ff23fce1735fec3dc5c09ee87cc499d802c25d2d35",
+    "x86_64-macos": "4e9fe855a34d011de88bf216c196f6957624526678b99b4f2135acc9ffa8c156",
+    "x86_64-linux-gnu": "bc9bd2522fe1850dd54c0fff189c8dd606df3f222ab2a905f2dd255123c3f495",
+    "aarch64-linux-gnu": "35a351db883f5ce82945bd8280c727b08e27aa48594d4eb9e091d8c80e936d52",
+    "x86_64-linux-musl": "ce79849f3be2e15d06364f89aeebb901b6be7b48947e2af8dae0616bbc87731f",
+    "aarch64-linux-musl": "1519bcee11f9c93a7ed95026bd951d53e8c7cd093f3ac53651b143e5a1e2098f",
+};
+/** Node platform/arch -> release asset name. Null when unsupported. */
+export function assetForPlatform(platform = process.platform, arch = process.arch) {
+    if (platform === "darwin") {
+        if (arch === "arm64")
+            return "arm64-macos";
+        if (arch === "x64")
+            return "x86_64-macos";
+        return null;
+    }
+    if (platform === "linux") {
+        const isMusl = detectMusl();
+        if (arch === "arm64")
+            return isMusl ? "aarch64-linux-musl" : "aarch64-linux-gnu";
+        if (arch === "x64")
+            return isMusl ? "x86_64-linux-musl" : "x86_64-linux-gnu";
+        return null;
+    }
+    return null;
+}
+function detectMusl() {
+    // `ldd --version` prints "musl" on musl hosts; glibc prints "glibc"/"GNU".
+    // ldd missing or failing → assume glibc (the serverless default).
+    try {
+        const out = execFileSync("ldd", ["--version"], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+        return /musl/i.test(out);
+    }
+    catch {
+        return false;
+    }
+}
+function cacheRoot() {
+    const home = process.env.HOME || process.env.USERPROFILE || "";
+    const base = home ? join(home, ".cache") : tmpdir();
+    const root = join(base, "webcrawl-impersonate");
+    // Writable probe — HOME caches can be root-owned/EPERM (serverless, managed
+    // Macs); fall back to tmpdir() so the tier stays available.
+    try {
+        mkdirSync(root, { recursive: true });
+        return root;
+    }
+    catch {
+        return join(tmpdir(), "webcrawl-impersonate");
+    }
+}
+export function binaryCachePath(asset) {
+    return join(cacheRoot(), IMPERSONATE_VERSION, asset, "curl-impersonate");
+}
+function httpsGet(url, redirects = 0) {
+    return new Promise((resolve, reject) => {
+        if (redirects > 5) {
+            reject(new Error("too many redirects"));
+            return;
+        }
+        const req = https.get(url, (res) => {
+            const status = res.statusCode ?? 0;
+            const location = res.headers.location;
+            if (status >= 300 && status < 400 && location) {
+                res.resume();
+                resolve(httpsGet(new URL(location, url).href, redirects + 1));
+                return;
+            }
+            if (status !== 200) {
+                res.resume();
+                reject(new Error(`HTTP ${status} for ${url}`));
+                return;
+            }
+            const chunks = [];
+            res.on("data", (c) => chunks.push(c));
+            res.on("end", () => resolve(Buffer.concat(chunks)));
+            res.on("error", reject);
+        });
+        req.on("error", reject);
+    });
+}
+/**
+ * Resolve the impersonate binary path, downloading on first use.
+ * Returns null when unavailable — never throws.
+ */
+export async function ensureBinary() {
+    const override = process.env.WEBCRAWL_IMPERSONATE_BIN;
+    if (override) {
+        return existsSync(override) ? override : null;
+    }
+    const asset = assetForPlatform();
+    if (!asset)
+        return null;
+    const cached = binaryCachePath(asset);
+    if (existsSync(cached))
+        return cached;
+    try {
+        await downloadAndExtract(asset, cached);
+        return cached;
+    }
+    catch {
+        return null;
+    }
+}
+async function downloadAndExtract(asset, destPath) {
+    const url = `${RELEASE_BASE}/curl-impersonate-${IMPERSONATE_VERSION}.${asset}.tar.gz`;
+    const expected = ASSET_SHA256[asset];
+    if (!expected)
+        throw new Error(`no pinned sha256 for ${asset}`);
+    const tarball = await httpsGet(url);
+    const actual = createHash("sha256").update(tarball).digest("hex");
+    if (actual !== expected) {
+        throw new Error(`sha256 mismatch for ${asset}: ${actual}`);
+    }
+    const dir = dirname(destPath);
+    mkdirSync(dir, { recursive: true });
+    // Extract only the binary entry into a scratch dir, then move into place.
+    const scratch = join(dir, ".extract");
+    rmSync(scratch, { recursive: true, force: true });
+    mkdirSync(scratch, { recursive: true });
+    await new Promise((resolve, reject) => {
+        const tar = spawn("tar", ["-xzf", "-", "-C", scratch, "curl-impersonate"], {
+            stdio: ["pipe", "ignore", "pipe"],
+        });
+        tar.on("error", reject);
+        tar.on("close", (code) => code === 0 ? resolve() : reject(new Error(`tar exited ${code}`)));
+        tar.stdin.on("error", reject);
+        tar.stdin.end(tarball);
+        tar.stderr.on("data", () => { }); // drain
+    });
+    const extracted = join(scratch, "curl-impersonate");
+    chmodSync(extracted, 0o755);
+    renameSync(extracted, destPath);
+    rmSync(scratch, { recursive: true, force: true });
+}
+/** Synchronous availability probe (CLI startup, no network). */
+export function isBinaryCached() {
+    const override = process.env.WEBCRAWL_IMPERSONATE_BIN;
+    if (override)
+        return existsSync(override);
+    const asset = assetForPlatform();
+    if (!asset)
+        return false;
+    return existsSync(binaryCachePath(asset));
+}
+/** Best-effort liveness check: binary runs and reports a version. */
+export function isBinaryHealthy(path) {
+    try {
+        const r = spawnSync(path, ["--version"], { encoding: "utf8", timeout: 5000 });
+        return r.status === 0 && /curl/i.test(String(r.stdout));
+    }
+    catch {
+        return false;
+    }
+}

package/dist/fetch.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Spawn-based impersonate fetch: one GET hop through the pinned
+ * lexiforest curl-impersonate binary with a Chrome TLS/HTTP2 fingerprint.
+ *
+ * Redirects are NOT followed (-L off) so every hop goes through the
+ * caller's SSRF guard — same contract as `rawGet` in the engine fetcher.
+ */
+import { ImpersonateProfile } from "./profiles.js";
+export interface ImpersonateFetchResult {
+    status: number;
+    headers: Record<string, string>;
+    contentType: string;
+    /** Decompressed body bytes (the binary handles gzip/br/zstd itself). */
+    body: Uint8Array;
+}
+export declare class ResourceTooLargeError extends Error {
+    readonly bytes: number;
+    readonly maxBytes: number;
+    constructor(bytes: number, maxBytes: number);
+}
+export declare class ImpersonateUnavailableError extends Error {
+    constructor(message: string);
+}
+export declare class ImpersonateTimeoutError extends Error {
+    constructor(message: string);
+}
+export interface ImpersonateFetchOptions {
+    /** Impersonation preset (default chrome150). */
+    profile?: ImpersonateProfile;
+    /** Per-request headers merged over the profile navigation set. */
+    headers?: Record<string, string>;
+    /** Total timeout for the spawn (default 12s). */
+    timeoutMs?: number;
+    /** Declared-length guard before the body is accepted. */
+    maxBytes?: number;
+}
+/** Resolved binary path or null when the tier is unavailable. Memoized. */
+export declare function resolveBinary(): Promise<string | null>;
+/** Pre-warm the binary (download if missing) for CLI/MCP startup. */
+export declare function ensureImpersonate(): Promise<string | null>;
+/** True when the binary resolved (cached or downloaded). */
+export declare function isImpersonateAvailable(): Promise<boolean>;
+/** Parse a `-D` header dump (all blocks; the final block wins per header). */
+export declare function parseHeaderDump(dump: string): {
+    status: number;
+    headers: Record<string, string>;
+};
+/** One GET hop through curl-impersonate. Throws only on setup/size/timeout errors. */
+export declare function impersonateFetch(url: string, options?: ImpersonateFetchOptions): Promise<ImpersonateFetchResult>;

package/dist/fetch.js

@@ -0,0 +1,191 @@
+/**
+ * Spawn-based impersonate fetch: one GET hop through the pinned
+ * lexiforest curl-impersonate binary with a Chrome TLS/HTTP2 fingerprint.
+ *
+ * Redirects are NOT followed (-L off) so every hop goes through the
+ * caller's SSRF guard — same contract as `rawGet` in the engine fetcher.
+ */
+import { spawn } from "node:child_process";
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { DEFAULT_IMPERSONATE_PROFILE, profileHeaders, } from "./profiles.js";
+import { ensureBinary } from "./binary.js";
+export class ResourceTooLargeError extends Error {
+    bytes;
+    maxBytes;
+    constructor(bytes, maxBytes) {
+        super(`File is ${(bytes / 1e6).toFixed(1)} MB; the limit is ${(maxBytes / 1e6).toFixed(0)} MB`);
+        this.bytes = bytes;
+        this.maxBytes = maxBytes;
+        this.name = "ResourceTooLargeError";
+    }
+}
+export class ImpersonateUnavailableError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ImpersonateUnavailableError";
+    }
+}
+export class ImpersonateTimeoutError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ImpersonateTimeoutError";
+    }
+}
+let cachedBinary;
+let binaryProbe = null;
+/** Resolved binary path or null when the tier is unavailable. Memoized. */
+export async function resolveBinary() {
+    if (cachedBinary !== undefined)
+        return cachedBinary;
+    if (!binaryProbe) {
+        binaryProbe = ensureBinary().finally(() => {
+            binaryProbe = null;
+        });
+    }
+    return (cachedBinary = await binaryProbe);
+}
+/** Pre-warm the binary (download if missing) for CLI/MCP startup. */
+export async function ensureImpersonate() {
+    cachedBinary = undefined;
+    binaryProbe = null;
+    return resolveBinary();
+}
+/** True when the binary resolved (cached or downloaded). */
+export async function isImpersonateAvailable() {
+    return (await resolveBinary()) !== null;
+}
+/** Parse a `-D` header dump (all blocks; the final block wins per header). */
+export function parseHeaderDump(dump) {
+    const headers = {};
+    let status = 0;
+    const lines = String(dump ?? "").split(/\r?\n/);
+    for (const line of lines) {
+        const statusMatch = line.match(/^HTTP\/[\d.]+\s+(\d{3})/i);
+        if (statusMatch) {
+            status = Number(statusMatch[1]);
+            continue;
+        }
+        const idx = line.indexOf(":");
+        if (idx <= 0)
+            continue;
+        const key = line.slice(0, idx).trim().toLowerCase();
+        const val = line.slice(idx + 1).trim();
+        if (key === "set-cookie") {
+            // keep the first cookie of the final block; callers replay per-domain
+            if (!(key in headers))
+                headers[key] = val.split(";")[0];
+        }
+        else {
+            headers[key] = val;
+        }
+    }
+    return { status, headers };
+}
+/** One GET hop through curl-impersonate. Throws only on setup/size/timeout errors. */
+export async function impersonateFetch(url, options = {}) {
+    const bin = await resolveBinary();
+    if (!bin) {
+        throw new ImpersonateUnavailableError("curl-impersonate binary unavailable");
+    }
+    const { profile = DEFAULT_IMPERSONATE_PROFILE, headers = {}, timeoutMs = 12_000, maxBytes, } = options;
+    const navHeaders = profileHeaders(profile, headers);
+    const headerArgs = Object.entries(navHeaders).flatMap(([k, v]) => ["-H", `${k}: ${v}`]);
+    const dir = mkdtempSync(join(tmpdir(), "webcrawl-imp-"));
+    const headerFile = join(dir, "headers");
+    const bodyFile = join(dir, "body");
+    try {
+        const { exitCode, stdout, stderr } = await new Promise((resolve, reject) => {
+            const child = spawn(bin, [
+                "-sS",
+                "--compressed",
+                "--impersonate", profile,
+                "-m", String(Math.ceil(timeoutMs / 1000)),
+                "-D", headerFile,
+                "-o", bodyFile,
+                "-w", "%{http_code}",
+                url,
+                ...headerArgs,
+            ], { stdio: ["ignore", "pipe", "pipe"] });
+            let stdout = "";
+            let stderr = "";
+            let settled = false;
+            const timer = setTimeout(() => {
+                settled = true;
+                child.kill("SIGKILL");
+                reject(new ImpersonateTimeoutError(`timed out after ${timeoutMs}ms`));
+            }, timeoutMs + 2000);
+            child.stdout.on("data", (c) => (stdout += c.toString()));
+            child.stderr.on("data", (c) => (stderr += c.toString()));
+            child.on("error", (err) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                reject(err);
+            });
+            child.on("close", (code) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                // 0 = clean exit. Partial fetches (timeouts) still parse best-effort.
+                resolve({ exitCode: code ?? -1, stdout, stderr });
+            });
+        });
+        if (exitCode !== 0 && stderr.trim() && !existsFile(headerFile)) {
+            throw new Error(`curl-impersonate exited ${exitCode}: ${stderr.slice(0, 400)}`);
+        }
+        void stdout; // %{http_code} — kept for debugging; status comes from the dump
+        const { status: parsedStatus, headers: responseHeaders } = parseHeaderDump(safeRead(headerFile));
+        const status = parsedStatus || Number(stdout.trim()) || 0;
+        const body = safeReadBytes(bodyFile);
+        if (maxBytes !== undefined) {
+            const declared = Number(responseHeaders["content-length"]);
+            if (Number.isFinite(declared) && declared > maxBytes) {
+                throw new ResourceTooLargeError(declared, maxBytes);
+            }
+            if (body.byteLength > maxBytes) {
+                throw new ResourceTooLargeError(body.byteLength, maxBytes);
+            }
+        }
+        return {
+            status,
+            headers: responseHeaders,
+            contentType: (responseHeaders["content-type"] || "")
+                .split(";")[0]
+                .trim()
+                .toLowerCase(),
+            body,
+        };
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}
+function existsFile(path) {
+    try {
+        readFileSync(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function safeRead(path) {
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch {
+        return "";
+    }
+}
+function safeReadBytes(path) {
+    try {
+        return new Uint8Array(readFileSync(path));
+    }
+    catch {
+        return new Uint8Array(0);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @webcrawl/curl-impersonate — zero-dependency curl-impersonate fetch.
+ *
+ * One GET hop through a pinned lexiforest curl-impersonate binary with a
+ * Chrome TLS/HTTP2 fingerprint. Redirects are manual so callers keep
+ * SSRF-guarding each hop. Pairs with the engine fetch ladder as the tier
+ * between impit (Chrome 136) and browser/sandbox escalation.
+ */
+export { impersonateFetch, ensureImpersonate, isImpersonateAvailable, resolveBinary, parseHeaderDump, ImpersonateUnavailableError, ImpersonateTimeoutError, ResourceTooLargeError, } from "./fetch.js";
+export type { ImpersonateFetchOptions, ImpersonateFetchResult, } from "./fetch.js";
+export { DEFAULT_IMPERSONATE_PROFILE, profileHeaders, profileUserAgent, type ImpersonateProfile, } from "./profiles.js";
+export { ensureBinary, assetForPlatform, binaryCachePath, isBinaryCached, isBinaryHealthy, IMPERSONATE_VERSION, ASSET_SHA256, } from "./binary.js";

package/dist/index.js

@@ -0,0 +1,11 @@
+/**
+ * @webcrawl/curl-impersonate — zero-dependency curl-impersonate fetch.
+ *
+ * One GET hop through a pinned lexiforest curl-impersonate binary with a
+ * Chrome TLS/HTTP2 fingerprint. Redirects are manual so callers keep
+ * SSRF-guarding each hop. Pairs with the engine fetch ladder as the tier
+ * between impit (Chrome 136) and browser/sandbox escalation.
+ */
+export { impersonateFetch, ensureImpersonate, isImpersonateAvailable, resolveBinary, parseHeaderDump, ImpersonateUnavailableError, ImpersonateTimeoutError, ResourceTooLargeError, } from "./fetch.js";
+export { DEFAULT_IMPERSONATE_PROFILE, profileHeaders, profileUserAgent, } from "./profiles.js";
+export { ensureBinary, assetForPlatform, binaryCachePath, isBinaryCached, isBinaryHealthy, IMPERSONATE_VERSION, ASSET_SHA256, } from "./binary.js";

package/dist/profiles.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Browser impersonation profiles for the lexiforest curl-impersonate binary.
+ *
+ * The binary ships presets as `--impersonate <target>`; the target names here
+ * map 1:1 to the wrapper scripts in the release tarball (curl_chrome150 etc.).
+ * Presets bundle TLS ciphers/curves/extensions, HTTP/2 settings + pseudo-header
+ * order, and a default navigation header set — we override the UA/sec-ch-ua
+ * headers ourselves so they stay coherent with `sec-ch-ua-platform`.
+ */
+export type ImpersonateProfile = "chrome142" | "chrome150" | "chrome151_macos" | "chrome152";
+export declare const DEFAULT_IMPERSONATE_PROFILE: ImpersonateProfile;
+/**
+ * Fingerprint-coherent navigation headers for a profile: the UA, the
+ * client hints, and the Sec-Fetch navigation set a real Chrome tab sends.
+ * The binary replaces the TLS/HTTP2 layer; these headers keep the
+ * application layer consistent with it.
+ */
+export declare function profileHeaders(profile?: ImpersonateProfile, extra?: Record<string, string>): Record<string, string>;
+export declare function profileUserAgent(profile?: ImpersonateProfile): string;

package/dist/profiles.js

@@ -0,0 +1,46 @@
+/**
+ * Browser impersonation profiles for the lexiforest curl-impersonate binary.
+ *
+ * The binary ships presets as `--impersonate <target>`; the target names here
+ * map 1:1 to the wrapper scripts in the release tarball (curl_chrome150 etc.).
+ * Presets bundle TLS ciphers/curves/extensions, HTTP/2 settings + pseudo-header
+ * order, and a default navigation header set — we override the UA/sec-ch-ua
+ * headers ourselves so they stay coherent with `sec-ch-ua-platform`.
+ */
+export const DEFAULT_IMPERSONATE_PROFILE = "chrome150";
+const PROFILE_DEFS = {
+    chrome142: { chromeMajor: "142", platform: "macOS" },
+    chrome150: { chromeMajor: "150", platform: "macOS" },
+    chrome151_macos: { chromeMajor: "151", platform: "macOS" },
+    chrome152: { chromeMajor: "152", platform: "macOS" },
+};
+const MAC_UA = (v) => `Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/${v}.0.0.0 Safari/537.36`;
+const WIN_UA = (v) => `Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/${v}.0.0.0 Safari/537.36`;
+/**
+ * Fingerprint-coherent navigation headers for a profile: the UA, the
+ * client hints, and the Sec-Fetch navigation set a real Chrome tab sends.
+ * The binary replaces the TLS/HTTP2 layer; these headers keep the
+ * application layer consistent with it.
+ */
+export function profileHeaders(profile = DEFAULT_IMPERSONATE_PROFILE, extra) {
+    const def = PROFILE_DEFS[profile];
+    const v = def.chromeMajor;
+    return {
+        "User-Agent": def.platform === "macOS" ? MAC_UA(v) : WIN_UA(v),
+        "sec-ch-ua": `"Chromium";v="${v}", "Google Chrome";v="${v}", "Not.A/Brand";v="99"`,
+        "sec-ch-ua-mobile": "?0",
+        "sec-ch-ua-platform": `"${def.platform}"`,
+        "Upgrade-Insecure-Requests": "1",
+        Accept: "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8",
+        "Sec-Fetch-Site": "none",
+        "Sec-Fetch-Mode": "navigate",
+        "Sec-Fetch-User": "?1",
+        "Sec-Fetch-Dest": "document",
+        "Accept-Language": "en-US,en;q=0.9",
+        Priority: "u=0, i",
+        ...(extra ?? {}),
+    };
+}
+export function profileUserAgent(profile = DEFAULT_IMPERSONATE_PROFILE) {
+    return profileHeaders(profile)["User-Agent"];
+}

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "@webcrawl/curl-impersonate",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.3.1",
+  "description": "Zero-dependency curl-impersonate fetch for Node.js — pinned lexiforest binary, Chrome TLS/HTTP2 fingerprint impersonation (chrome150 default), automatic per-platform download with sha256 verification",
+  "type": "module",
+  "license": "MIT",
+  "author": "Brainfish AI <support@webcrawl.app> (https://webcrawl.app)",
+  "homepage": "https://webcrawl.app",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/brainfish-ai/webcrawl-anything.git",
+    "directory": "packages/curl-impersonate"
+  },
+  "bugs": {
+    "url": "https://github.com/brainfish-ai/webcrawl-anything/issues"
+  },
+  "keywords": [
+    "curl-impersonate",
+    "tls-fingerprint",
+    "ja3",
+    "ja4",
+    "http2-fingerprint",
+    "web-scraping",
+    "anti-bot",
+    "waf-bypass",
+    "webcrawl"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepack": "npm run build",
+    "test": "node --conditions=development --import tsx --test test/*.test.ts"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}