httpcloak 1.5.1 → 1.5.2

package/README.md

@@ -99,13 +99,123 @@ session.postCb(
 );
 ```
 
-### With Proxy
+## Proxy Support
+
+HTTPCloak supports HTTP, SOCKS5, and HTTP/3 (MASQUE) proxies with full fingerprint preservation.
+
+### HTTP Proxy
 
 ```javascript
+const { Session } = require("httpcloak");
+
+// Basic HTTP proxy
 const session = new Session({
+  preset: "chrome-143",
+  proxy: "http://host:port",
+});
+
+// With authentication
+const sessionAuth = new Session({
   preset: "chrome-143",
   proxy: "http://user:pass@host:port",
 });
+
+// HTTPS proxy
+const sessionHttps = new Session({
+  preset: "chrome-143",
+  proxy: "https://user:pass@host:port",
+});
+```
+
+### SOCKS5 Proxy
+
+```javascript
+const { Session } = require("httpcloak");
+
+// SOCKS5 proxy (with DNS resolution on proxy)
+const session = new Session({
+  preset: "chrome-143",
+  proxy: "socks5h://host:port",
+});
+
+// With authentication
+const sessionAuth = new Session({
+  preset: "chrome-143",
+  proxy: "socks5h://user:pass@host:port",
+});
+
+const response = await session.get("https://www.cloudflare.com/cdn-cgi/trace");
+console.log(response.protocol); // h3 (HTTP/3 through SOCKS5!)
+```
+
+### HTTP/3 MASQUE Proxy
+
+MASQUE (RFC 9484) enables HTTP/3 connections through compatible proxies:
+
+```javascript
+const { Session } = require("httpcloak");
+
+// MASQUE proxy (auto-detected for known providers like Bright Data)
+const session = new Session({
+  preset: "chrome-143",
+  proxy: "https://user:pass@brd.superproxy.io:10001",
+});
+
+const response = await session.get("https://www.cloudflare.com/cdn-cgi/trace");
+console.log(response.protocol); // h3
+```
+
+## Advanced Features
+
+### Encrypted Client Hello (ECH)
+
+ECH encrypts the SNI (Server Name Indication) to prevent traffic analysis. Works with all Cloudflare domains:
+
+```javascript
+const { Session } = require("httpcloak");
+
+// Enable ECH for Cloudflare domains
+const session = new Session({
+  preset: "chrome-143",
+  echConfigDomain: "cloudflare-ech.com",
+});
+
+const response = await session.get("https://www.cloudflare.com/cdn-cgi/trace");
+console.log(response.text);
+// Output includes: sni=encrypted, http=http/3
+```
+
+### Domain Fronting (Connect-To)
+
+Connect to one server while requesting a different domain:
+
+```javascript
+const { Session } = require("httpcloak");
+
+// Connect to claude.ai's IP but request www.cloudflare.com
+const session = new Session({
+  preset: "chrome-143",
+  connectTo: { "www.cloudflare.com": "claude.ai" },
+});
+
+const response = await session.get("https://www.cloudflare.com/cdn-cgi/trace");
+```
+
+### Combined: SOCKS5 + ECH
+
+Get HTTP/3 with encrypted SNI through a SOCKS5 proxy:
+
+```javascript
+const { Session } = require("httpcloak");
+
+const session = new Session({
+  preset: "chrome-143",
+  proxy: "socks5h://user:pass@host:port",
+  echConfigDomain: "cloudflare-ech.com",
+});
+
+const response = await session.get("https://www.cloudflare.com/cdn-cgi/trace");
+// Response shows: http=http/3, sni=encrypted
 ```
 
 ## Cookie Management

package/lib/index.d.ts

@@ -6,6 +6,22 @@ export class HTTPCloakError extends Error {
   name: "HTTPCloakError";
 }
 
+export class Cookie {
+  /** Cookie name */
+  name: string;
+  /** Cookie value */
+  value: string;
+}
+
+export class RedirectInfo {
+  /** HTTP status code */
+  statusCode: number;
+  /** Request URL */
+  url: string;
+  /** Response headers */
+  headers: Record<string, string>;
+}
+
 export class Response {
   /** HTTP status code */
   statusCode: number;
@@ -13,21 +29,40 @@ export class Response {
   headers: Record<string, string>;
   /** Raw response body as Buffer */
   body: Buffer;
+  /** Response body as Buffer (alias for body) */
+  content: Buffer;
   /** Response body as string */
   text: string;
   /** Final URL after redirects */
   finalUrl: string;
+  /** Final URL after redirects (alias for finalUrl) */
+  url: string;
   /** Protocol used (http/1.1, h2, h3) */
   protocol: string;
+  /** Elapsed time in milliseconds */
+  elapsed: number;
+  /** Cookies set by this response */
+  cookies: Cookie[];
+  /** Redirect history */
+  history: RedirectInfo[];
+  /** True if status code < 400 */
+  ok: boolean;
+  /** HTTP status reason phrase (e.g., 'OK', 'Not Found') */
+  reason: string;
+  /** Response encoding from Content-Type header */
+  encoding: string | null;
 
   /** Parse response body as JSON */
   json<T = any>(): T;
+
+  /** Raise error if status >= 400 */
+  raiseForStatus(): void;
 }
 
 export interface SessionOptions {
   /** Browser preset to use (default: "chrome-143") */
   preset?: string;
-  /** Proxy URL (e.g., "http://user:pass@host:port") */
+  /** Proxy URL (e.g., "http://user:pass@host:port" or "socks5://host:port") */
   proxy?: string;
   /** Request timeout in seconds (default: 30) */
   timeout?: number;
@@ -43,17 +78,33 @@ export interface SessionOptions {
   retry?: number;
   /** Status codes to retry on (default: [429, 500, 502, 503, 504]) */
   retryOnStatus?: number[];
+  /** Prefer IPv4 addresses over IPv6 (default: false) */
+  preferIpv4?: boolean;
+  /** Default basic auth [username, password] */
+  auth?: [string, string];
+  /** Domain fronting map {requestHost: connectHost} - DNS resolves connectHost but SNI/Host uses requestHost */
+  connectTo?: Record<string, string>;
+  /** Domain to fetch ECH config from (e.g., "cloudflare-ech.com" for any Cloudflare domain) */
+  echConfigDomain?: string;
 }
 
 export interface RequestOptions {
-  /** HTTP method */
-  method: string;
-  /** Request URL */
-  url: string;
   /** Optional custom headers */
   headers?: Record<string, string>;
-  /** Optional request body */
+  /** Optional request body (for POST, PUT, PATCH) */
   body?: string | Buffer | Record<string, any>;
+  /** JSON body (will be serialized) */
+  json?: Record<string, any>;
+  /** Form data (will be URL encoded) */
+  data?: Record<string, any>;
+  /** Files to upload as multipart/form-data */
+  files?: Record<string, Buffer | { filename: string; content: Buffer; contentType?: string }>;
+  /** Query parameters */
+  params?: Record<string, string | number | boolean>;
+  /** Cookies to send with this request */
+  cookies?: Record<string, string>;
+  /** Basic auth [username, password] */
+  auth?: [string, string];
   /** Optional request timeout in seconds */
   timeout?: number;
 }
@@ -61,67 +112,66 @@ export interface RequestOptions {
 export class Session {
   constructor(options?: SessionOptions);
 
+  /** Default headers for all requests */
+  headers: Record<string, string>;
+
+  /** Default auth for all requests [username, password] */
+  auth: [string, string] | null;
+
   /** Close the session and release resources */
   close(): void;
 
   // Synchronous methods
   /** Perform a synchronous GET request */
-  getSync(url: string, headers?: Record<string, string>): Response;
+  getSync(url: string, options?: RequestOptions): Response;
 
   /** Perform a synchronous POST request */
-  postSync(
-    url: string,
-    body?: string | Buffer | Record<string, any>,
-    headers?: Record<string, string>
-  ): Response;
+  postSync(url: string, options?: RequestOptions): Response;
 
   /** Perform a synchronous custom HTTP request */
-  requestSync(options: RequestOptions): Response;
+  requestSync(method: string, url: string, options?: RequestOptions): Response;
 
   // Promise-based methods
   /** Perform an async GET request */
-  get(url: string, headers?: Record<string, string>): Promise<Response>;
+  get(url: string, options?: RequestOptions): Promise<Response>;
 
   /** Perform an async POST request */
-  post(
-    url: string,
-    body?: string | Buffer | Record<string, any>,
-    headers?: Record<string, string>
-  ): Promise<Response>;
+  post(url: string, options?: RequestOptions): Promise<Response>;
 
   /** Perform an async custom HTTP request */
-  request(options: RequestOptions): Promise<Response>;
+  request(method: string, url: string, options?: RequestOptions): Promise<Response>;
 
   /** Perform an async PUT request */
-  put(
-    url: string,
-    body?: string | Buffer | Record<string, any>,
-    headers?: Record<string, string>
-  ): Promise<Response>;
+  put(url: string, options?: RequestOptions): Promise<Response>;
 
   /** Perform an async DELETE request */
-  delete(url: string, headers?: Record<string, string>): Promise<Response>;
+  delete(url: string, options?: RequestOptions): Promise<Response>;
 
   /** Perform an async PATCH request */
-  patch(
-    url: string,
-    body?: string | Buffer | Record<string, any>,
-    headers?: Record<string, string>
-  ): Promise<Response>;
+  patch(url: string, options?: RequestOptions): Promise<Response>;
 
   /** Perform an async HEAD request */
-  head(url: string, headers?: Record<string, string>): Promise<Response>;
+  head(url: string, options?: RequestOptions): Promise<Response>;
 
   /** Perform an async OPTIONS request */
-  options(url: string, headers?: Record<string, string>): Promise<Response>;
+  options(url: string, options?: RequestOptions): Promise<Response>;
 
   // Cookie management
   /** Get all cookies from the session */
   getCookies(): Record<string, string>;
 
+  /** Get a specific cookie by name */
+  getCookie(name: string): string | null;
+
   /** Set a cookie in the session */
   setCookie(name: string, value: string): void;
 
+  /** Delete a specific cookie by name */
+  deleteCookie(name: string): void;
+
+  /** Clear all cookies from the session */
+  clearCookies(): void;
+
   /** Get cookies as a property */
   readonly cookies: Record<string, string>;
 }
@@ -162,7 +212,8 @@ export function patch(url: string, options?: RequestOptions): Promise<Response>;
 export function head(url: string, options?: RequestOptions): Promise<Response>;
 
 /** Perform an OPTIONS request */
-export function options(url: string, options?: RequestOptions): Promise<Response>;
+declare function opts(url: string, options?: RequestOptions): Promise<Response>;
+export { opts as options };
 
 /** Perform a custom HTTP request */
 export function request(method: string, url: string, options?: RequestOptions): Promise<Response>;

package/lib/index.js

@@ -674,7 +674,7 @@ class Session {
    * Create a new session
    * @param {Object} options - Session options
    * @param {string} [options.preset="chrome-143"] - Browser preset to use
-   * @param {string} [options.proxy] - Proxy URL (e.g., "http://user:pass@host:port")
+   * @param {string} [options.proxy] - Proxy URL (e.g., "http://user:pass@host:port" or "socks5://host:port")
    * @param {number} [options.timeout=30] - Request timeout in seconds
    * @param {string} [options.httpVersion="auto"] - HTTP version: "auto", "h1", "h2", "h3"
    * @param {boolean} [options.verify=true] - SSL certificate verification
@@ -683,6 +683,8 @@ class Session {
    * @param {number} [options.retry=3] - Number of retries on failure (set to 0 to disable)
    * @param {number[]} [options.retryOnStatus] - Status codes to retry on
    * @param {Array} [options.auth] - Default auth [username, password] for all requests
+   * @param {Object} [options.connectTo] - Domain fronting map {requestHost: connectHost}
+   * @param {string} [options.echConfigDomain] - Domain to fetch ECH config from (e.g., "cloudflare-ech.com")
    */
   constructor(options = {}) {
     const {
@@ -697,6 +699,8 @@ class Session {
       retryOnStatus = null,
       preferIpv4 = false,
       auth = null,
+      connectTo = null,
+      echConfigDomain = null,
     } = options;
 
     this._lib = getLib();
@@ -727,6 +731,12 @@ class Session {
     if (preferIpv4) {
       config.prefer_ipv4 = true;
     }
+    if (connectTo) {
+      config.connect_to = connectTo;
+    }
+    if (echConfigDomain) {
+      config.ech_config_domain = echConfigDomain;
+    }
 
     this._handle = this._lib.httpcloak_session_new(JSON.stringify(config));
 

package/npm/darwin-arm64/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@httpcloak/darwin-arm64",
-  "version": "1.5.1",
+  "version": "1.5.2",
   "description": "HTTPCloak native binary for darwin arm64",
   "os": [
     "darwin"

package/npm/darwin-x64/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@httpcloak/darwin-x64",
-  "version": "1.5.1",
+  "version": "1.5.2",
   "description": "HTTPCloak native binary for darwin x64",
   "os": [
     "darwin"

package/npm/linux-arm64/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@httpcloak/linux-arm64",
-  "version": "1.5.1",
+  "version": "1.5.2",
   "description": "HTTPCloak native binary for linux arm64",
   "os": [
     "linux"

package/npm/linux-x64/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@httpcloak/linux-x64",
-  "version": "1.5.1",
+  "version": "1.5.2",
   "description": "HTTPCloak native binary for linux x64",
   "os": [
     "linux"

package/npm/win32-arm64/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@httpcloak/win32-arm64",
-  "version": "1.5.1",
+  "version": "1.5.2",
   "description": "HTTPCloak native binary for win32 arm64",
   "os": [
     "win32"

package/npm/win32-x64/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@httpcloak/win32-x64",
-  "version": "1.5.1",
+  "version": "1.5.2",
   "description": "HTTPCloak native binary for win32 x64",
   "os": [
     "win32"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "httpcloak",
-  "version": "1.5.1",
+  "version": "1.5.2",
   "description": "Browser fingerprint emulation HTTP client with HTTP/1.1, HTTP/2, and HTTP/3 support",
   "main": "lib/index.js",
   "module": "lib/index.mjs",