h2-fingerprint-client 1.0.0

package/README.md

@@ -0,0 +1,152 @@
+# h2-fingerprint-client
+
+> HTTP/2 fingerprint-aware request library for Node.js — mimics real browser SETTINGS frames, pseudo-header order, and header casing for research and educational purposes.
+
+---
+
+## Background
+
+Modern bot detection systems don't just inspect your IP or User-Agent. They fingerprint the structure of your HTTP/2 connection at the transport layer — analyzing:
+
+- **SETTINGS frames** — every browser sends unique `HEADER_TABLE_SIZE`, `INITIAL_WINDOW_SIZE`, `MAX_HEADER_LIST_SIZE` values on session open
+- **Pseudo-header order** — Chrome sends `:method :authority :scheme :path`, Firefox sends `:method :path :authority :scheme`
+- **Header casing and order** — real browsers send headers in a consistent, deterministic sequence
+- **WINDOW_UPDATE size** — the initial flow control window increment differs per browser
+
+A standard Node.js `http2` or `axios` request is immediately identifiable because it sends none of these signals correctly.
+
+This library lets you make HTTP/2 requests that structurally match a real browser's fingerprint.
+
+---
+
+## Install
+
+```bash
+npm install h2-fingerprint-client
+```
+
+---
+
+## Usage
+
+### Basic GET request
+
+```js
+const { get } = require("h2-fingerprint-client");
+
+const res = await get("https://example.com", {
+  profile: "chrome120", // chrome120 | firefox121 | safari17
+});
+
+console.log(res.status);   // 200
+console.log(res.body);     // HTML response
+console.log(res.timings);  // { connect: 120, total: 340 }
+console.log(res.profile);  // "Chrome 120 / Windows 11"
+```
+
+### POST request
+
+```js
+const { post } = require("h2-fingerprint-client");
+
+const res = await post("https://example.com/api/data", {
+  profile: "firefox121",
+  headers: { "content-type": "application/json" },
+  body: JSON.stringify({ key: "value" }),
+});
+```
+
+### Custom headers (merged with profile)
+
+```js
+const { request } = require("h2-fingerprint-client");
+
+const res = await request("https://example.com", {
+  profile: "safari17",
+  method: "GET",
+  headers: {
+    "accept-language": "fr-FR,fr;q=0.9",
+    "cookie": "session=abc123",
+  },
+  timeout: 10000,
+});
+```
+
+---
+
+## Profiles
+
+| Profile | Browser | OS | SETTINGS |
+|---|---|---|---|
+| `chrome120` | Chrome 120 | Windows 11 | `HEADER_TABLE_SIZE=65536, ENABLE_PUSH=0, INITIAL_WINDOW_SIZE=6291456, MAX_HEADER_LIST_SIZE=262144` |
+| `firefox121` | Firefox 121 | Windows 11 | `HEADER_TABLE_SIZE=65536, INITIAL_WINDOW_SIZE=131072, MAX_FRAME_SIZE=16384, ENABLE_PUSH=0` |
+| `safari17` | Safari 17 | macOS Sonoma | `HEADER_TABLE_SIZE=4096, ENABLE_PUSH=0, INITIAL_WINDOW_SIZE=4194304, MAX_FRAME_SIZE=16384` |
+
+---
+
+## Response Object
+
+```js
+{
+  status: 200,              // HTTP status code
+  headers: { ... },        // Response headers (pseudo-headers stripped)
+  body: "...",             // Response body as string
+  profile: "Chrome 120 / Windows 11",
+  timings: {
+    connect: 112,          // ms to establish HTTP/2 session
+    total: 348,            // ms total
+  }
+}
+```
+
+---
+
+## How It Works
+
+### 1. SETTINGS Frame
+On session open, Node.js's `http2.connect()` accepts a `settings` object. This library passes the exact settings values that each real browser sends, rather than the Node.js defaults.
+
+### 2. Pseudo-Header Order
+HTTP/2 uses pseudo-headers (`:method`, `:path`, `:authority`, `:scheme`) that must appear before regular headers. The **order** of these pseudo-headers differs between browsers and is a key fingerprinting signal. This library replicates the correct order per profile.
+
+### 3. Header Order
+Regular headers are ordered to match the real browser's typical output — not alphabetically or randomly as most HTTP clients do.
+
+### 4. Header Values
+Each profile ships with the correct `user-agent`, `accept`, `sec-ch-ua`, `sec-fetch-*` and other headers matching that browser version.
+
+---
+
+## Examples
+
+```bash
+# Basic request
+node examples/basic.js
+
+# Compare all profiles side by side
+node examples/compare-profiles.js
+```
+
+---
+
+## Limitations
+
+- HTTP/2 requires **HTTPS**. HTTP/1.1 sites are not supported.
+- TLS fingerprinting (JA3/JA4) is a separate layer — this library does not spoof TLS ClientHello. For that, look into solutions using BoringSSL or `curl-impersonate`.
+- WINDOW_UPDATE frame timing is not yet controllable.
+
+---
+
+## Research References
+
+- [RFC 7540 — HTTP/2](https://www.rfc-editor.org/rfc/rfc7540)
+- [RFC 7541 — HPACK Header Compression](https://www.rfc-editor.org/rfc/rfc7541)
+- [HTTP/2 Fingerprinting — BrowserLeaks](https://browserleaks.com/http2)
+- [TLS + HTTP/2 fingerprinting — tls.peet.ws](https://tls.peet.ws/)
+- [Akamai HTTP/2 fingerprinting research](https://www.blackhat.com/docs/eu-17/materials/eu-17-Shuster-Passive-Fingerprinting-Of-HTTP2-Clients-wp.pdf)
+
+---
+
+## License
+
+MIT — for research and educational use.

package/examples/basic.js

@@ -0,0 +1,16 @@
+const { get } = require("../src");
+
+(async () => {
+  try {
+    console.log("Testing Chrome 120 fingerprint...");
+    const res = await get("https://httpbin.org/headers", { profile: "chrome120" });
+    console.log("Status:", res.status);
+    console.log("Profile used:", res.profile);
+    console.log("Timings:", res.timings);
+    console.log("Response headers sent (as seen by server):");
+    const parsed = JSON.parse(res.body);
+    console.log(JSON.stringify(parsed.headers, null, 2));
+  } catch (err) {
+    console.error("Error:", err.message);
+  }
+})();

package/examples/compare-profiles.js

@@ -0,0 +1,23 @@
+/**
+ * Compare how different browser fingerprint profiles appear to a server.
+ * Run: node examples/compare-profiles.js
+ */
+const { get, PROFILES } = require("../src");
+
+(async () => {
+  const profileNames = Object.keys(PROFILES);
+  console.log(`Comparing ${profileNames.length} profiles against httpbin.org/headers\n`);
+
+  for (const profileName of profileNames) {
+    try {
+      console.log(`\n--- ${PROFILES[profileName].name} ---`);
+      const res = await get("https://httpbin.org/headers", { profile: profileName });
+      const parsed = JSON.parse(res.body);
+      console.log("Status:", res.status);
+      console.log("User-Agent:", parsed.headers["User-Agent"]);
+      console.log("Total time:", res.timings.total + "ms");
+    } catch (err) {
+      console.error(`  Error: ${err.message}`);
+    }
+  }
+})();

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "h2-fingerprint-client",
+  "version": "1.0.0",
+  "description": "HTTP/2 fingerprint-aware request library for Node.js — mimics real browser SETTINGS frames, pseudo-header order, and header ordering for research purposes.",
+  "main": "src/index.js",
+  "scripts": {
+    "example": "node examples/basic.js",
+    "compare": "node examples/compare-profiles.js"
+  },
+  "keywords": [
+    "http2",
+    "fingerprint",
+    "h2",
+    "browser",
+    "tls",
+    "anti-bot",
+    "scraping",
+    "research",
+    "settings-frame",
+    "header-order"
+  ],
+  "author": "Israze",
+  "license": "MIT",
+  "engines": {
+    "node": ">=14.0.0"
+  }
+}

package/src/client.js

@@ -0,0 +1,109 @@
+"use strict";
+
+const http2 = require("http2");
+const { PROFILES } = require("./profiles");
+
+function buildOrderedHeaders(profile, method, urlObj, extraHeaders = {}) {
+  const merged = { ...profile.headers, ...extraHeaders };
+  const ordered = {};
+
+  for (const pseudo of profile.pseudoHeaderOrder) {
+    if (pseudo === ":method") ordered[":method"] = method.toUpperCase();
+    if (pseudo === ":authority") ordered[":authority"] = urlObj.host;
+    if (pseudo === ":scheme") ordered[":scheme"] = urlObj.protocol.replace(":", "");
+    if (pseudo === ":path") ordered[":path"] = urlObj.pathname + urlObj.search;
+  }
+
+  for (const key of profile.headerOrder) {
+    if (merged[key] !== undefined) ordered[key] = merged[key];
+  }
+
+  for (const [key, value] of Object.entries(merged)) {
+    if (!ordered[key]) ordered[key] = value;
+  }
+
+  return ordered;
+}
+
+function request(url, options = {}) {
+  const {
+    profile: profileName = "chrome120",
+    method = "GET",
+    headers: extraHeaders = {},
+    body = null,
+    timeout = 15000,
+  } = options;
+
+  const profile = PROFILES[profileName];
+  if (!profile) {
+    return Promise.reject(
+      new Error(`Unknown profile "${profileName}". Available: ${Object.keys(PROFILES).join(", ")}`)
+    );
+  }
+
+  const urlObj = new URL(url);
+  if (urlObj.protocol !== "https:") {
+    return Promise.reject(new Error("HTTP/2 requires HTTPS. Use an https:// URL."));
+  }
+
+  return new Promise((resolve, reject) => {
+    const startTime = Date.now();
+    let connectTime = null;
+
+    const client = http2.connect(urlObj.origin, {
+      settings: profile.settings,
+      ALPNProtocols: ["h2"],
+    });
+
+    client.on("connect", () => { connectTime = Date.now() - startTime; });
+    client.on("error", (err) => { client.destroy(); reject(err); });
+
+    const orderedHeaders = buildOrderedHeaders(profile, method, urlObj, extraHeaders);
+    const req = client.request(orderedHeaders);
+
+    if (body) req.write(body);
+    req.end();
+
+    const timer = setTimeout(() => {
+      req.destroy();
+      client.destroy();
+      reject(new Error(`Request timed out after ${timeout}ms`));
+    }, timeout);
+
+    let responseHeaders = {};
+    let status = null;
+
+    req.on("response", (headers) => {
+      status = headers[":status"];
+      for (const [k, v] of Object.entries(headers)) {
+        if (!k.startsWith(":")) responseHeaders[k] = v;
+      }
+    });
+
+    const chunks = [];
+    req.on("data", (chunk) => chunks.push(chunk));
+
+    req.on("end", () => {
+      clearTimeout(timer);
+      client.close();
+      resolve({
+        status,
+        headers: responseHeaders,
+        body: Buffer.concat(chunks).toString("utf8"),
+        profile: profile.name,
+        timings: { connect: connectTime, total: Date.now() - startTime },
+      });
+    });
+
+    req.on("error", (err) => {
+      clearTimeout(timer);
+      client.destroy();
+      reject(err);
+    });
+  });
+}
+
+const get = (url, options = {}) => request(url, { ...options, method: "GET" });
+const post = (url, options = {}) => request(url, { ...options, method: "POST" });
+
+module.exports = { request, get, post, PROFILES };

package/src/fingerprints.js

@@ -0,0 +1,130 @@
+'use strict';
+
+/**
+ * HTTP/2 SETTINGS frame values and pseudo-header ordering
+ * based on real browser captures.
+ *
+ * References:
+ *  - https://www.rfc-editor.org/rfc/rfc7540
+ *  - https://browserleaks.com/http2
+ *  - https://tls.peet.ws/
+ */
+
+const FINGERPRINTS = {
+  chrome120: {
+    name: 'Chrome 120',
+    settings: {
+      HEADER_TABLE_SIZE: 65536,
+      ENABLE_PUSH: 0,
+      INITIAL_WINDOW_SIZE: 6291456,
+      MAX_HEADER_LIST_SIZE: 262144,
+    },
+    windowUpdate: 15663105,
+    pseudoHeaderOrder: [':method', ':authority', ':scheme', ':path'],
+    headerOrder: [
+      'cache-control',
+      'sec-ch-ua',
+      'sec-ch-ua-mobile',
+      'sec-ch-ua-platform',
+      'upgrade-insecure-requests',
+      'user-agent',
+      'accept',
+      'sec-fetch-site',
+      'sec-fetch-mode',
+      'sec-fetch-user',
+      'sec-fetch-dest',
+      'accept-encoding',
+      'accept-language',
+    ],
+    headers: {
+      'user-agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
+      'accept': 'text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8',
+      'accept-encoding': 'gzip, deflate, br',
+      'accept-language': 'en-US,en;q=0.9',
+      'cache-control': 'max-age=0',
+      'sec-ch-ua': '"Not_A Brand";v="8", "Chromium";v="120", "Google Chrome";v="120"',
+      'sec-ch-ua-mobile': '?0',
+      'sec-ch-ua-platform': '"Windows"',
+      'sec-fetch-dest': 'document',
+      'sec-fetch-mode': 'navigate',
+      'sec-fetch-site': 'none',
+      'sec-fetch-user': '?1',
+      'upgrade-insecure-requests': '1',
+    },
+    priority: {
+      exclusive: true,
+      streamDependency: 0,
+      weight: 255,
+    },
+  },
+
+  firefox121: {
+    name: 'Firefox 121',
+    settings: {
+      HEADER_TABLE_SIZE: 65536,
+      INITIAL_WINDOW_SIZE: 131072,
+      MAX_FRAME_SIZE: 16384,
+    },
+    windowUpdate: 12517377,
+    pseudoHeaderOrder: [':method', ':path', ':authority', ':scheme'],
+    headerOrder: [
+      'user-agent',
+      'accept',
+      'accept-language',
+      'accept-encoding',
+      'connection',
+    ],
+    headers: {
+      'user-agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:121.0) Gecko/20100101 Firefox/121.0',
+      'accept': 'text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,*/*;q=0.8',
+      'accept-encoding': 'gzip, deflate, br',
+      'accept-language': 'en-US,en;q=0.5',
+      'connection': 'keep-alive',
+      'upgrade-insecure-requests': '1',
+    },
+    priority: {
+      exclusive: false,
+      streamDependency: 0,
+      weight: 42,
+    },
+  },
+
+  safari17: {
+    name: 'Safari 17',
+    settings: {
+      INITIAL_WINDOW_SIZE: 4194304,
+      MAX_CONCURRENT_STREAMS: 100,
+    },
+    windowUpdate: 10485760,
+    pseudoHeaderOrder: [':method', ':scheme', ':path', ':authority'],
+    headerOrder: [
+      'user-agent',
+      'accept',
+      'accept-language',
+      'accept-encoding',
+    ],
+    headers: {
+      'user-agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 14_2) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.2 Safari/605.1.15',
+      'accept': 'text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8',
+      'accept-encoding': 'gzip, deflate, br',
+      'accept-language': 'en-US,en;q=0.9',
+    },
+    priority: null,
+  },
+};
+
+function getFingerprint(name) {
+  const fp = FINGERPRINTS[name];
+  if (!fp) {
+    throw new Error(
+      `Unknown fingerprint: "${name}". Available: ${Object.keys(FINGERPRINTS).join(', ')}`
+    );
+  }
+  return fp;
+}
+
+function listFingerprints() {
+  return Object.keys(FINGERPRINTS);
+}
+
+module.exports = { getFingerprint, listFingerprints, FINGERPRINTS };

package/src/index.js

@@ -0,0 +1,5 @@
+"use strict";
+
+const { request, get, post, PROFILES } = require("./client");
+
+module.exports = { request, get, post, PROFILES };

package/src/profiles.js

@@ -0,0 +1,111 @@
+/**
+ * Browser HTTP/2 fingerprint profiles
+ * Based on public research into browser HTTP/2 SETTINGS frames and header ordering.
+ *
+ * References:
+ * - https://www.rfc-editor.org/rfc/rfc7540 (HTTP/2 spec)
+ * - https://www.rfc-editor.org/rfc/rfc7541 (HPACK spec)
+ * - https://browserleaks.com/http2
+ * - https://tls.peet.ws/
+ */
+
+const PROFILES = {
+  chrome120: {
+    name: "Chrome 120 / Windows 11",
+    settings: {
+      HEADER_TABLE_SIZE: 65536,
+      ENABLE_PUSH: 0,
+      INITIAL_WINDOW_SIZE: 6291456,
+      MAX_HEADER_LIST_SIZE: 262144,
+    },
+    windowUpdate: 15663105,
+    pseudoHeaderOrder: [":method", ":authority", ":scheme", ":path"],
+    headerOrder: [
+      "cache-control",
+      "sec-ch-ua",
+      "sec-ch-ua-mobile",
+      "sec-ch-ua-platform",
+      "upgrade-insecure-requests",
+      "user-agent",
+      "accept",
+      "sec-fetch-site",
+      "sec-fetch-mode",
+      "sec-fetch-user",
+      "sec-fetch-dest",
+      "accept-encoding",
+      "accept-language",
+    ],
+    headers: {
+      "user-agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
+      accept: "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.7",
+      "accept-language": "en-US,en;q=0.9",
+      "accept-encoding": "gzip, deflate, br",
+      "cache-control": "max-age=0",
+      "sec-ch-ua": '"Not_A Brand";v="8", "Chromium";v="120", "Google Chrome";v="120"',
+      "sec-ch-ua-mobile": "?0",
+      "sec-ch-ua-platform": '"Windows"',
+      "sec-fetch-dest": "document",
+      "sec-fetch-mode": "navigate",
+      "sec-fetch-site": "none",
+      "sec-fetch-user": "?1",
+      "upgrade-insecure-requests": "1",
+    },
+  },
+
+  firefox121: {
+    name: "Firefox 121 / Windows 11",
+    settings: {
+      HEADER_TABLE_SIZE: 65536,
+      INITIAL_WINDOW_SIZE: 131072,
+      MAX_FRAME_SIZE: 16384,
+      ENABLE_PUSH: 0,
+    },
+    windowUpdate: 12517377,
+    pseudoHeaderOrder: [":method", ":path", ":authority", ":scheme"],
+    headerOrder: [
+      "user-agent",
+      "accept",
+      "accept-language",
+      "accept-encoding",
+      "upgrade-insecure-requests",
+    ],
+    headers: {
+      "user-agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:121.0) Gecko/20100101 Firefox/121.0",
+      accept: "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,*/*;q=0.8",
+      "accept-language": "en-US,en;q=0.5",
+      "accept-encoding": "gzip, deflate, br",
+      "upgrade-insecure-requests": "1",
+      "sec-fetch-dest": "document",
+      "sec-fetch-mode": "navigate",
+      "sec-fetch-site": "none",
+      "sec-fetch-user": "?1",
+    },
+  },
+
+  safari17: {
+    name: "Safari 17 / macOS Sonoma",
+    settings: {
+      HEADER_TABLE_SIZE: 4096,
+      ENABLE_PUSH: 0,
+      INITIAL_WINDOW_SIZE: 4194304,
+      MAX_FRAME_SIZE: 16384,
+      MAX_HEADER_LIST_SIZE: 16384,
+    },
+    windowUpdate: 10420225,
+    pseudoHeaderOrder: [":method", ":scheme", ":path", ":authority"],
+    headerOrder: [
+      "accept",
+      "user-agent",
+      "accept-language",
+      "accept-encoding",
+    ],
+    headers: {
+      "user-agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_2_1) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.2 Safari/605.1.15",
+      accept: "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
+      "accept-language": "en-US,en;q=0.9",
+      "accept-encoding": "gzip, deflate, br",
+    },
+  },
+};
+
+module.exports = { PROFILES };

package/src/session.js

@@ -0,0 +1,115 @@
+'use strict';
+
+const { request } = require('./client');
+const { getFingerprint, listFingerprints } = require('./fingerprints');
+
+/**
+ * H2Session - maintains a consistent fingerprint identity
+ * across multiple requests (same headers, same settings).
+ *
+ * Useful for multi-step scraping flows where consistency matters.
+ */
+class H2Session {
+  /**
+   * @param {object} options
+   * @param {string} [options.fingerprint='chrome120']
+   * @param {object} [options.headers={}] - extra headers applied to every request
+   * @param {number} [options.timeout=15000]
+   */
+  constructor(options = {}) {
+    this.fingerprint = options.fingerprint || 'chrome120';
+    this.baseHeaders = options.headers || {};
+    this.timeout = options.timeout || 15000;
+    this.cookieJar = {};
+
+    // Validate fingerprint exists on construction
+    getFingerprint(this.fingerprint);
+  }
+
+  /**
+   * Merges stored cookies into request headers.
+   * @param {string} host
+   * @returns {object}
+   */
+  _getCookieHeader(host) {
+    const cookies = this.cookieJar[host];
+    if (!cookies || Object.keys(cookies).length === 0) return {};
+    const cookieStr = Object.entries(cookies)
+      .map(([k, v]) => `${k}=${v}`)
+      .join('; ');
+    return { cookie: cookieStr };
+  }
+
+  /**
+   * Parses and stores set-cookie headers from a response.
+   * @param {string} host
+   * @param {object} responseHeaders
+   */
+  _storeCookies(host, responseHeaders) {
+    const raw = responseHeaders['set-cookie'];
+    if (!raw) return;
+    const list = Array.isArray(raw) ? raw : [raw];
+    if (!this.cookieJar[host]) this.cookieJar[host] = {};
+    for (const entry of list) {
+      const [pair] = entry.split(';');
+      const [name, ...rest] = pair.split('=');
+      if (name) this.cookieJar[host][name.trim()] = rest.join('=').trim();
+    }
+  }
+
+  /**
+   * Makes a request using this session's fingerprint + cookies.
+   * @param {string} url
+   * @param {object} [options]
+   * @returns {Promise<{ status, headers, body }>}
+   */
+  async request(url, options = {}) {
+    const parsed = new URL(url);
+    const cookieHeaders = this._getCookieHeader(parsed.host);
+
+    const res = await request(url, {
+      fingerprint: this.fingerprint,
+      timeout: this.timeout,
+      ...options,
+      headers: {
+        ...this.baseHeaders,
+        ...cookieHeaders,
+        ...(options.headers || {}),
+      },
+    });
+
+    this._storeCookies(parsed.host, res.headers);
+    return res;
+  }
+
+  get(url, options = {}) {
+    return this.session(url, { ...options, method: 'GET' });
+  }
+
+  post(url, options = {}) {
+    return this.request(url, { ...options, method: 'POST' });
+  }
+
+  /**
+   * Returns current fingerprint profile info.
+   */
+  inspect() {
+    const fp = getFingerprint(this.fingerprint);
+    return {
+      fingerprint: this.fingerprint,
+      name: fp.name,
+      settings: fp.settings,
+      pseudoHeaderOrder: fp.pseudoHeaderOrder,
+      cookieJar: this.cookieJar,
+    };
+  }
+
+  /**
+   * Clears stored cookies.
+   */
+  clearCookies() {
+    this.cookieJar = {};
+  }
+}
+
+module.exports = { H2Session };