httpcloak 1.5.0 → 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

@@ -69,17 +69,105 @@ const Preset = {
   },
 };
 
+/**
+ * HTTP status reason phrases
+ */
+const HTTP_STATUS_PHRASES = {
+  100: "Continue", 101: "Switching Protocols", 102: "Processing",
+  200: "OK", 201: "Created", 202: "Accepted", 203: "Non-Authoritative Information",
+  204: "No Content", 205: "Reset Content", 206: "Partial Content", 207: "Multi-Status",
+  300: "Multiple Choices", 301: "Moved Permanently", 302: "Found", 303: "See Other",
+  304: "Not Modified", 305: "Use Proxy", 307: "Temporary Redirect", 308: "Permanent Redirect",
+  400: "Bad Request", 401: "Unauthorized", 402: "Payment Required", 403: "Forbidden",
+  404: "Not Found", 405: "Method Not Allowed", 406: "Not Acceptable",
+  407: "Proxy Authentication Required", 408: "Request Timeout", 409: "Conflict",
+  410: "Gone", 411: "Length Required", 412: "Precondition Failed",
+  413: "Payload Too Large", 414: "URI Too Long", 415: "Unsupported Media Type",
+  416: "Range Not Satisfiable", 417: "Expectation Failed", 418: "I'm a teapot",
+  421: "Misdirected Request", 422: "Unprocessable Entity", 423: "Locked",
+  424: "Failed Dependency", 425: "Too Early", 426: "Upgrade Required",
+  428: "Precondition Required", 429: "Too Many Requests",
+  431: "Request Header Fields Too Large", 451: "Unavailable For Legal Reasons",
+  500: "Internal Server Error", 501: "Not Implemented", 502: "Bad Gateway",
+  503: "Service Unavailable", 504: "Gateway Timeout", 505: "HTTP Version Not Supported",
+  506: "Variant Also Negotiates", 507: "Insufficient Storage", 508: "Loop Detected",
+  510: "Not Extended", 511: "Network Authentication Required",
+};
+
+/**
+ * Cookie object from Set-Cookie header
+ */
+class Cookie {
+  /**
+   * @param {string} name - Cookie name
+   * @param {string} value - Cookie value
+   */
+  constructor(name, value) {
+    this.name = name;
+    this.value = value;
+  }
+
+  toString() {
+    return `Cookie(name=${this.name}, value=${this.value})`;
+  }
+}
+
+/**
+ * Redirect info from history
+ */
+class RedirectInfo {
+  /**
+   * @param {number} statusCode - HTTP status code
+   * @param {string} url - Request URL
+   * @param {Object} headers - Response headers
+   */
+  constructor(statusCode, url, headers) {
+    this.statusCode = statusCode;
+    this.url = url;
+    this.headers = headers || {};
+  }
+
+  toString() {
+    return `RedirectInfo(statusCode=${this.statusCode}, url=${this.url})`;
+  }
+}
+
 /**
  * Response object returned from HTTP requests
  */
 class Response {
-  constructor(data) {
+  /**
+   * @param {Object} data - Response data from native library
+   * @param {number} [elapsed=0] - Elapsed time in milliseconds
+   */
+  constructor(data, elapsed = 0) {
     this.statusCode = data.status_code || 0;
     this.headers = data.headers || {};
     this._body = Buffer.from(data.body || "", "utf8");
     this._text = data.body || "";
     this.finalUrl = data.final_url || "";
     this.protocol = data.protocol || "";
+    this.elapsed = elapsed; // milliseconds
+
+    // Parse cookies from response
+    this._cookies = (data.cookies || []).map(c => new Cookie(c.name || "", c.value || ""));
+
+    // Parse redirect history
+    this._history = (data.history || []).map(h => new RedirectInfo(
+      h.status_code || 0,
+      h.url || "",
+      h.headers || {}
+    ));
+  }
+
+  /** Cookies set by this response */
+  get cookies() {
+    return this._cookies;
+  }
+
+  /** Redirect history (list of RedirectInfo objects) */
+  get history() {
+    return this._history;
   }
 
   /** Response body as string */
@@ -107,6 +195,29 @@ class Response {
     return this.statusCode < 400;
   }
 
+  /** HTTP status reason phrase (e.g., 'OK', 'Not Found') */
+  get reason() {
+    return HTTP_STATUS_PHRASES[this.statusCode] || "Unknown";
+  }
+
+  /**
+   * Response encoding from Content-Type header.
+   * Returns null if not specified.
+   */
+  get encoding() {
+    let contentType = this.headers["content-type"] || this.headers["Content-Type"] || "";
+    if (contentType.includes("charset=")) {
+      const parts = contentType.split(";");
+      for (const part of parts) {
+        const trimmed = part.trim();
+        if (trimmed.toLowerCase().startsWith("charset=")) {
+          return trimmed.split("=")[1].trim().replace(/['"]/g, "");
+        }
+      }
+    }
+    return null;
+  }
+
   /**
    * Parse response body as JSON
    */
@@ -119,7 +230,7 @@ class Response {
    */
   raiseForStatus() {
     if (!this.ok) {
-      throw new HTTPCloakError(`HTTP ${this.statusCode}`);
+      throw new HTTPCloakError(`HTTP ${this.statusCode}: ${this.reason}`);
     }
   }
 }
@@ -215,32 +326,158 @@ function getLibPath() {
   );
 }
 
+// Define callback proto globally for koffi (must be before getLib)
+const AsyncCallbackProto = koffi.proto("void AsyncCallback(int64 callbackId, str responseJson, str error)");
+
 // Load the native library
 let lib = null;
+let nativeLibHandle = null;
 
 function getLib() {
   if (lib === null) {
     const libPath = getLibPath();
-    const nativeLib = koffi.load(libPath);
+    nativeLibHandle = koffi.load(libPath);
 
     // Use str for string returns - koffi handles the string copy automatically
     // Note: The C strings allocated by Go are not freed, but Go's GC handles them
     lib = {
-      httpcloak_session_new: nativeLib.func("httpcloak_session_new", "int64", ["str"]),
-      httpcloak_session_free: nativeLib.func("httpcloak_session_free", "void", ["int64"]),
-      httpcloak_get: nativeLib.func("httpcloak_get", "str", ["int64", "str", "str"]),
-      httpcloak_post: nativeLib.func("httpcloak_post", "str", ["int64", "str", "str", "str"]),
-      httpcloak_request: nativeLib.func("httpcloak_request", "str", ["int64", "str"]),
-      httpcloak_get_cookies: nativeLib.func("httpcloak_get_cookies", "str", ["int64"]),
-      httpcloak_set_cookie: nativeLib.func("httpcloak_set_cookie", "void", ["int64", "str", "str"]),
-      httpcloak_free_string: nativeLib.func("httpcloak_free_string", "void", ["void*"]),
-      httpcloak_version: nativeLib.func("httpcloak_version", "str", []),
-      httpcloak_available_presets: nativeLib.func("httpcloak_available_presets", "str", []),
+      httpcloak_session_new: nativeLibHandle.func("httpcloak_session_new", "int64", ["str"]),
+      httpcloak_session_free: nativeLibHandle.func("httpcloak_session_free", "void", ["int64"]),
+      httpcloak_get: nativeLibHandle.func("httpcloak_get", "str", ["int64", "str", "str"]),
+      httpcloak_post: nativeLibHandle.func("httpcloak_post", "str", ["int64", "str", "str", "str"]),
+      httpcloak_request: nativeLibHandle.func("httpcloak_request", "str", ["int64", "str"]),
+      httpcloak_get_cookies: nativeLibHandle.func("httpcloak_get_cookies", "str", ["int64"]),
+      httpcloak_set_cookie: nativeLibHandle.func("httpcloak_set_cookie", "void", ["int64", "str", "str"]),
+      httpcloak_free_string: nativeLibHandle.func("httpcloak_free_string", "void", ["void*"]),
+      httpcloak_version: nativeLibHandle.func("httpcloak_version", "str", []),
+      httpcloak_available_presets: nativeLibHandle.func("httpcloak_available_presets", "str", []),
+      // Async functions
+      httpcloak_register_callback: nativeLibHandle.func("httpcloak_register_callback", "int64", [koffi.pointer(AsyncCallbackProto)]),
+      httpcloak_unregister_callback: nativeLibHandle.func("httpcloak_unregister_callback", "void", ["int64"]),
+      httpcloak_get_async: nativeLibHandle.func("httpcloak_get_async", "void", ["int64", "str", "str", "int64"]),
+      httpcloak_post_async: nativeLibHandle.func("httpcloak_post_async", "void", ["int64", "str", "str", "str", "int64"]),
+      httpcloak_request_async: nativeLibHandle.func("httpcloak_request_async", "void", ["int64", "str", "int64"]),
     };
   }
   return lib;
 }
 
+/**
+ * Async callback manager for native Go goroutine-based async
+ *
+ * Each async request registers a callback with Go and receives a unique ID.
+ * When Go completes the request, it invokes the callback with that ID.
+ */
+class AsyncCallbackManager {
+  constructor() {
+    // callbackId -> { resolve, reject, startTime }
+    this._pendingRequests = new Map();
+    this._callbackPtr = null;
+    this._refTimer = null; // Timer to keep event loop alive
+  }
+
+  /**
+   * Ref the event loop to prevent Node.js from exiting while requests are pending
+   */
+  _ref() {
+    if (this._refTimer === null) {
+      // Create a timer that keeps the event loop alive
+      this._refTimer = setInterval(() => {}, 2147483647); // Max interval
+    }
+  }
+
+  /**
+   * Unref the event loop when no more pending requests
+   */
+  _unref() {
+    if (this._pendingRequests.size === 0 && this._refTimer !== null) {
+      clearInterval(this._refTimer);
+      this._refTimer = null;
+    }
+  }
+
+  /**
+   * Ensure the callback is set up with koffi
+   */
+  _ensureCallback() {
+    if (this._callbackPtr !== null) {
+      return;
+    }
+
+    // Create callback function that will be invoked by Go
+    // koffi.register expects koffi.pointer(proto) as the type
+    this._callbackPtr = koffi.register((callbackId, responseJson, error) => {
+      const pending = this._pendingRequests.get(Number(callbackId));
+      if (!pending) {
+        return;
+      }
+      this._pendingRequests.delete(Number(callbackId));
+      this._unref(); // Check if we can release the event loop
+
+      const { resolve, reject, startTime } = pending;
+      const elapsed = Date.now() - startTime;
+
+      if (error && error !== "") {
+        let errMsg = error;
+        try {
+          const errData = JSON.parse(error);
+          errMsg = errData.error || error;
+        } catch (e) {
+          // Use raw error string
+        }
+        reject(new HTTPCloakError(errMsg));
+      } else if (responseJson) {
+        try {
+          const data = JSON.parse(responseJson);
+          if (data.error) {
+            reject(new HTTPCloakError(data.error));
+          } else {
+            resolve(new Response(data, elapsed));
+          }
+        } catch (e) {
+          reject(new HTTPCloakError(`Failed to parse response: ${e.message}`));
+        }
+      } else {
+        reject(new HTTPCloakError("No response received"));
+      }
+    }, koffi.pointer(AsyncCallbackProto));
+  }
+
+  /**
+   * Register a new async request
+   * @returns {{ callbackId: number, promise: Promise<Response> }}
+   */
+  registerRequest(nativeLib) {
+    this._ensureCallback();
+
+    // Register callback with Go (each request gets unique ID)
+    const callbackId = nativeLib.httpcloak_register_callback(this._callbackPtr);
+
+    // Create promise for this request with start time
+    let resolve, reject;
+    const promise = new Promise((res, rej) => {
+      resolve = res;
+      reject = rej;
+    });
+    const startTime = Date.now();
+
+    this._pendingRequests.set(Number(callbackId), { resolve, reject, startTime });
+    this._ref(); // Keep event loop alive
+
+    return { callbackId, promise };
+  }
+}
+
+// Global async callback manager
+let asyncManager = null;
+
+function getAsyncManager() {
+  if (asyncManager === null) {
+    asyncManager = new AsyncCallbackManager();
+  }
+  return asyncManager;
+}
+
 /**
  * Convert result to string (handles both direct strings and null)
  * With "str" return type, koffi automatically handles the conversion
@@ -254,8 +491,11 @@ function resultToString(result) {
 
 /**
  * Parse response from the native library
+ * @param {string} resultPtr - Result pointer from native function
+ * @param {number} [elapsed=0] - Elapsed time in milliseconds
+ * @returns {Response}
  */
-function parseResponse(resultPtr) {
+function parseResponse(resultPtr, elapsed = 0) {
   const result = resultToString(resultPtr);
   if (!result) {
     throw new HTTPCloakError("No response received");
@@ -267,7 +507,7 @@ function parseResponse(resultPtr) {
     throw new HTTPCloakError(data.error);
   }
 
-  return new Response(data);
+  return new Response(data, elapsed);
 }
 
 /**
@@ -434,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
@@ -442,6 +682,9 @@ class Session {
    * @param {number} [options.maxRedirects=10] - Maximum number of redirects to follow
    * @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 {
@@ -455,10 +698,14 @@ class Session {
       retry = 3,
       retryOnStatus = null,
       preferIpv4 = false,
+      auth = null,
+      connectTo = null,
+      echConfigDomain = null,
     } = options;
 
     this._lib = getLib();
     this.headers = {}; // Default headers
+    this.auth = auth; // Default auth for all requests
 
     const config = {
       preset,
@@ -484,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));
 
@@ -512,6 +765,31 @@ class Session {
     return { ...this.headers, ...headers };
   }
 
+  /**
+   * Apply cookies to headers
+   * @param {Object} headers - Existing headers
+   * @param {Object} cookies - Cookies to apply as key-value pairs
+   * @returns {Object} Headers with cookies applied
+   */
+  _applyCookies(headers, cookies) {
+    if (!cookies || Object.keys(cookies).length === 0) {
+      return headers;
+    }
+
+    const cookieStr = Object.entries(cookies)
+      .map(([k, v]) => `${k}=${v}`)
+      .join("; ");
+
+    headers = headers ? { ...headers } : {};
+    const existing = headers["Cookie"] || "";
+    if (existing) {
+      headers["Cookie"] = `${existing}; ${cookieStr}`;
+    } else {
+      headers["Cookie"] = cookieStr;
+    }
+    return headers;
+  }
+
   // ===========================================================================
   // Synchronous Methods
   // ===========================================================================
@@ -522,19 +800,25 @@ class Session {
    * @param {Object} [options] - Request options
    * @param {Object} [options.headers] - Custom headers
    * @param {Object} [options.params] - Query parameters
+   * @param {Object} [options.cookies] - Cookies to send with this request
    * @param {Array} [options.auth] - Basic auth [username, password]
    * @returns {Response} Response object
    */
   getSync(url, options = {}) {
-    const { headers = null, params = null, auth = null } = options;
+    const { headers = null, params = null, cookies = null, auth = null } = options;
 
     url = addParamsToUrl(url, params);
     let mergedHeaders = this._mergeHeaders(headers);
-    mergedHeaders = applyAuth(mergedHeaders, auth);
+    // Use request auth if provided, otherwise fall back to session auth
+    const effectiveAuth = auth !== null ? auth : this.auth;
+    mergedHeaders = applyAuth(mergedHeaders, effectiveAuth);
+    mergedHeaders = this._applyCookies(mergedHeaders, cookies);
 
     const headersJson = mergedHeaders ? JSON.stringify(mergedHeaders) : null;
+    const startTime = Date.now();
     const result = this._lib.httpcloak_get(this._handle, url, headersJson);
-    return parseResponse(result);
+    const elapsed = Date.now() - startTime;
+    return parseResponse(result, elapsed);
   }
 
   /**
@@ -550,11 +834,12 @@ class Session {
    *   - { filename, content, contentType? }: file with metadata
    * @param {Object} [options.headers] - Custom headers
    * @param {Object} [options.params] - Query parameters
+   * @param {Object} [options.cookies] - Cookies to send with this request
    * @param {Array} [options.auth] - Basic auth [username, password]
    * @returns {Response} Response object
    */
   postSync(url, options = {}) {
-    let { body = null, json = null, data = null, files = null, headers = null, params = null, auth = null } = options;
+    let { body = null, json = null, data = null, files = null, headers = null, params = null, cookies = null, auth = null } = options;
 
     url = addParamsToUrl(url, params);
     let mergedHeaders = this._mergeHeaders(headers);
@@ -588,11 +873,16 @@ class Session {
       body = body.toString("utf8");
     }
 
-    mergedHeaders = applyAuth(mergedHeaders, auth);
+    // Use request auth if provided, otherwise fall back to session auth
+    const effectiveAuth = auth !== null ? auth : this.auth;
+    mergedHeaders = applyAuth(mergedHeaders, effectiveAuth);
+    mergedHeaders = this._applyCookies(mergedHeaders, cookies);
 
     const headersJson = mergedHeaders ? JSON.stringify(mergedHeaders) : null;
+    const startTime = Date.now();
     const result = this._lib.httpcloak_post(this._handle, url, body, headersJson);
-    return parseResponse(result);
+    const elapsed = Date.now() - startTime;
+    return parseResponse(result, elapsed);
   }
 
   /**
@@ -600,11 +890,12 @@ class Session {
    * @param {string} method - HTTP method
    * @param {string} url - Request URL
    * @param {Object} [options] - Request options
+   * @param {Object} [options.cookies] - Cookies to send with this request
    * @param {Object} [options.files] - Files to upload as multipart/form-data
    * @returns {Response} Response object
    */
   requestSync(method, url, options = {}) {
-    let { body = null, json = null, data = null, files = null, headers = null, params = null, auth = null, timeout = null } = options;
+    let { body = null, json = null, data = null, files = null, headers = null, params = null, cookies = null, auth = null, timeout = null } = options;
 
     url = addParamsToUrl(url, params);
     let mergedHeaders = this._mergeHeaders(headers);
@@ -638,7 +929,10 @@ class Session {
       body = body.toString("utf8");
     }
 
-    mergedHeaders = applyAuth(mergedHeaders, auth);
+    // Use request auth if provided, otherwise fall back to session auth
+    const effectiveAuth = auth !== null ? auth : this.auth;
+    mergedHeaders = applyAuth(mergedHeaders, effectiveAuth);
+    mergedHeaders = this._applyCookies(mergedHeaders, cookies);
 
     const requestConfig = {
       method: method.toUpperCase(),
@@ -648,70 +942,171 @@ class Session {
     if (body) requestConfig.body = body;
     if (timeout) requestConfig.timeout = timeout;
 
+    const startTime = Date.now();
     const result = this._lib.httpcloak_request(
       this._handle,
       JSON.stringify(requestConfig)
     );
-    return parseResponse(result);
+    const elapsed = Date.now() - startTime;
+    return parseResponse(result, elapsed);
   }
 
   // ===========================================================================
-  // Promise-based Methods
+  // Promise-based Methods (Native async using Go goroutines)
   // ===========================================================================
 
   /**
-   * Perform an async GET request
+   * Perform an async GET request using native Go goroutines
    * @param {string} url - Request URL
    * @param {Object} [options] - Request options
+   * @param {Object} [options.cookies] - Cookies to send with this request
    * @returns {Promise<Response>} Response object
    */
   get(url, options = {}) {
-    return new Promise((resolve, reject) => {
-      setImmediate(() => {
-        try {
-          resolve(this.getSync(url, options));
-        } catch (err) {
-          reject(err);
-        }
-      });
-    });
+    const { headers = null, params = null, cookies = null, auth = null } = options;
+
+    url = addParamsToUrl(url, params);
+    let mergedHeaders = this._mergeHeaders(headers);
+    // Use request auth if provided, otherwise fall back to session auth
+    const effectiveAuth = auth !== null ? auth : this.auth;
+    mergedHeaders = applyAuth(mergedHeaders, effectiveAuth);
+    mergedHeaders = this._applyCookies(mergedHeaders, cookies);
+
+    const headersJson = mergedHeaders ? JSON.stringify(mergedHeaders) : null;
+
+    // Register async request with callback manager
+    const manager = getAsyncManager();
+    const { callbackId, promise } = manager.registerRequest(this._lib);
+
+    // Start async request
+    this._lib.httpcloak_get_async(this._handle, url, headersJson, callbackId);
+
+    return promise;
   }
 
   /**
-   * Perform an async POST request
+   * Perform an async POST request using native Go goroutines
    * @param {string} url - Request URL
    * @param {Object} [options] - Request options
+   * @param {Object} [options.cookies] - Cookies to send with this request
    * @returns {Promise<Response>} Response object
    */
   post(url, options = {}) {
-    return new Promise((resolve, reject) => {
-      setImmediate(() => {
-        try {
-          resolve(this.postSync(url, options));
-        } catch (err) {
-          reject(err);
-        }
-      });
-    });
+    let { body = null, json = null, data = null, files = null, headers = null, params = null, cookies = null, auth = null } = options;
+
+    url = addParamsToUrl(url, params);
+    let mergedHeaders = this._mergeHeaders(headers);
+
+    // Handle multipart file upload
+    if (files !== null) {
+      const formData = (data !== null && typeof data === "object") ? data : null;
+      const multipart = encodeMultipart(formData, files);
+      body = multipart.body.toString("latin1");
+      mergedHeaders = mergedHeaders || {};
+      mergedHeaders["Content-Type"] = multipart.contentType;
+    }
+    // Handle JSON body
+    else if (json !== null) {
+      body = JSON.stringify(json);
+      mergedHeaders = mergedHeaders || {};
+      if (!mergedHeaders["Content-Type"]) {
+        mergedHeaders["Content-Type"] = "application/json";
+      }
+    }
+    // Handle form data
+    else if (data !== null && typeof data === "object") {
+      body = new URLSearchParams(data).toString();
+      mergedHeaders = mergedHeaders || {};
+      if (!mergedHeaders["Content-Type"]) {
+        mergedHeaders["Content-Type"] = "application/x-www-form-urlencoded";
+      }
+    }
+    // Handle Buffer body
+    else if (Buffer.isBuffer(body)) {
+      body = body.toString("utf8");
+    }
+
+    // Use request auth if provided, otherwise fall back to session auth
+    const effectiveAuth = auth !== null ? auth : this.auth;
+    mergedHeaders = applyAuth(mergedHeaders, effectiveAuth);
+    mergedHeaders = this._applyCookies(mergedHeaders, cookies);
+
+    const headersJson = mergedHeaders ? JSON.stringify(mergedHeaders) : null;
+
+    // Register async request with callback manager
+    const manager = getAsyncManager();
+    const { callbackId, promise } = manager.registerRequest(this._lib);
+
+    // Start async request
+    this._lib.httpcloak_post_async(this._handle, url, body, headersJson, callbackId);
+
+    return promise;
   }
 
   /**
-   * Perform an async custom HTTP request
+   * Perform an async custom HTTP request using native Go goroutines
    * @param {string} method - HTTP method
    * @param {string} url - Request URL
    * @param {Object} [options] - Request options
+   * @param {Object} [options.cookies] - Cookies to send with this request
    * @returns {Promise<Response>} Response object
    */
   request(method, url, options = {}) {
-    return new Promise((resolve, reject) => {
-      setImmediate(() => {
-        try {
-          resolve(this.requestSync(method, url, options));
-        } catch (err) {
-          reject(err);
-        }
-      });
-    });
+    let { body = null, json = null, data = null, files = null, headers = null, params = null, cookies = null, auth = null, timeout = null } = options;
+
+    url = addParamsToUrl(url, params);
+    let mergedHeaders = this._mergeHeaders(headers);
+
+    // Handle multipart file upload
+    if (files !== null) {
+      const formData = (data !== null && typeof data === "object") ? data : null;
+      const multipart = encodeMultipart(formData, files);
+      body = multipart.body.toString("latin1");
+      mergedHeaders = mergedHeaders || {};
+      mergedHeaders["Content-Type"] = multipart.contentType;
+    }
+    // Handle JSON body
+    else if (json !== null) {
+      body = JSON.stringify(json);
+      mergedHeaders = mergedHeaders || {};
+      if (!mergedHeaders["Content-Type"]) {
+        mergedHeaders["Content-Type"] = "application/json";
+      }
+    }
+    // Handle form data
+    else if (data !== null && typeof data === "object") {
+      body = new URLSearchParams(data).toString();
+      mergedHeaders = mergedHeaders || {};
+      if (!mergedHeaders["Content-Type"]) {
+        mergedHeaders["Content-Type"] = "application/x-www-form-urlencoded";
+      }
+    }
+    // Handle Buffer body
+    else if (Buffer.isBuffer(body)) {
+      body = body.toString("utf8");
+    }
+
+    // Use request auth if provided, otherwise fall back to session auth
+    const effectiveAuth = auth !== null ? auth : this.auth;
+    mergedHeaders = applyAuth(mergedHeaders, effectiveAuth);
+    mergedHeaders = this._applyCookies(mergedHeaders, cookies);
+
+    const requestConfig = {
+      method: method.toUpperCase(),
+      url,
+    };
+    if (mergedHeaders) requestConfig.headers = mergedHeaders;
+    if (body) requestConfig.body = body;
+    if (timeout) requestConfig.timeout = timeout;
+
+    // Register async request with callback manager
+    const manager = getAsyncManager();
+    const { callbackId, promise } = manager.registerRequest(this._lib);
+
+    // Start async request
+    this._lib.httpcloak_request_async(this._handle, JSON.stringify(requestConfig), callbackId);
+
+    return promise;
   }
 
   /**
@@ -766,6 +1161,16 @@ class Session {
     return {};
   }
 
+  /**
+   * Get a specific cookie by name
+   * @param {string} name - Cookie name
+   * @returns {string|null} Cookie value or null if not found
+   */
+  getCookie(name) {
+    const cookies = this.getCookies();
+    return cookies[name] || null;
+  }
+
   /**
    * Set a cookie in the session
    * @param {string} name - Cookie name
@@ -775,6 +1180,25 @@ class Session {
     this._lib.httpcloak_set_cookie(this._handle, name, value);
   }
 
+  /**
+   * Delete a specific cookie by name
+   * @param {string} name - Cookie name to delete
+   */
+  deleteCookie(name) {
+    // Set cookie to empty value - effectively deletes it
+    this._lib.httpcloak_set_cookie(this._handle, name, "");
+  }
+
+  /**
+   * Clear all cookies from the session
+   */
+  clearCookies() {
+    const cookies = this.getCookies();
+    for (const name of Object.keys(cookies)) {
+      this.deleteCookie(name);
+    }
+  }
+
   /**
    * Get cookies as a property
    */
@@ -960,6 +1384,8 @@ module.exports = {
   // Classes
   Session,
   Response,
+  Cookie,
+  RedirectInfo,
   HTTPCloakError,
   // Presets
   Preset,

package/lib/index.mjs

@@ -0,0 +1,35 @@
+/**
+ * HTTPCloak Node.js Client - ESM Module
+ *
+ * A fetch/axios-compatible HTTP client with browser fingerprint emulation.
+ * Provides TLS fingerprinting for HTTP requests.
+ */
+
+import { createRequire } from "module";
+const require = createRequire(import.meta.url);
+
+// Import the CommonJS module
+const cjs = require("./index.js");
+
+// Re-export all named exports
+export const Session = cjs.Session;
+export const Response = cjs.Response;
+export const HTTPCloakError = cjs.HTTPCloakError;
+export const Preset = cjs.Preset;
+export const configure = cjs.configure;
+export const get = cjs.get;
+export const post = cjs.post;
+export const put = cjs.put;
+export const patch = cjs.patch;
+export const head = cjs.head;
+export const options = cjs.options;
+export const request = cjs.request;
+export const version = cjs.version;
+export const availablePresets = cjs.availablePresets;
+
+// 'delete' is a reserved word in ESM, so we export it specially
+const del = cjs.delete;
+export { del as delete };
+
+// Default export (the entire module)
+export default cjs;

package/npm/darwin-arm64/lib.mjs

@@ -0,0 +1,6 @@
+// Auto-generated - exports path to native library (ESM)
+import { fileURLToPath } from "url";
+import { dirname, join } from "path";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+export default join(__dirname, "libhttpcloak-darwin-arm64.dylib");

package/npm/darwin-arm64/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@httpcloak/darwin-arm64",
-  "version": "1.5.0",
+  "version": "1.5.2",
   "description": "HTTPCloak native binary for darwin arm64",
   "os": [
     "darwin"
@@ -9,6 +9,13 @@
     "arm64"
   ],
   "main": "lib.js",
+  "module": "lib.mjs",
+  "exports": {
+    ".": {
+      "import": "./lib.mjs",
+      "require": "./lib.js"
+    }
+  },
   "license": "MIT",
   "repository": {
     "type": "git",

package/npm/darwin-x64/lib.mjs

@@ -0,0 +1,6 @@
+// Auto-generated - exports path to native library (ESM)
+import { fileURLToPath } from "url";
+import { dirname, join } from "path";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+export default join(__dirname, "libhttpcloak-darwin-amd64.dylib");

package/npm/darwin-x64/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@httpcloak/darwin-x64",
-  "version": "1.5.0",
+  "version": "1.5.2",
   "description": "HTTPCloak native binary for darwin x64",
   "os": [
     "darwin"
@@ -9,6 +9,13 @@
     "x64"
   ],
   "main": "lib.js",
+  "module": "lib.mjs",
+  "exports": {
+    ".": {
+      "import": "./lib.mjs",
+      "require": "./lib.js"
+    }
+  },
   "license": "MIT",
   "repository": {
     "type": "git",

package/npm/linux-arm64/lib.mjs

@@ -0,0 +1,6 @@
+// Auto-generated - exports path to native library (ESM)
+import { fileURLToPath } from "url";
+import { dirname, join } from "path";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+export default join(__dirname, "libhttpcloak-linux-arm64.so");

package/npm/linux-arm64/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@httpcloak/linux-arm64",
-  "version": "1.5.0",
+  "version": "1.5.2",
   "description": "HTTPCloak native binary for linux arm64",
   "os": [
     "linux"
@@ -9,6 +9,13 @@
     "arm64"
   ],
   "main": "lib.js",
+  "module": "lib.mjs",
+  "exports": {
+    ".": {
+      "import": "./lib.mjs",
+      "require": "./lib.js"
+    }
+  },
   "license": "MIT",
   "repository": {
     "type": "git",

package/npm/linux-x64/lib.mjs

@@ -0,0 +1,6 @@
+// Auto-generated - exports path to native library (ESM)
+import { fileURLToPath } from "url";
+import { dirname, join } from "path";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+export default join(__dirname, "libhttpcloak-linux-amd64.so");

package/npm/linux-x64/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@httpcloak/linux-x64",
-  "version": "1.5.0",
+  "version": "1.5.2",
   "description": "HTTPCloak native binary for linux x64",
   "os": [
     "linux"
@@ -9,6 +9,13 @@
     "x64"
   ],
   "main": "lib.js",
+  "module": "lib.mjs",
+  "exports": {
+    ".": {
+      "import": "./lib.mjs",
+      "require": "./lib.js"
+    }
+  },
   "license": "MIT",
   "repository": {
     "type": "git",

package/npm/win32-arm64/lib.mjs

@@ -0,0 +1,6 @@
+// Auto-generated - exports path to native library (ESM)
+import { fileURLToPath } from "url";
+import { dirname, join } from "path";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+export default join(__dirname, "libhttpcloak-windows-arm64.dll");

package/npm/win32-arm64/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@httpcloak/win32-arm64",
-  "version": "1.5.0",
+  "version": "1.5.2",
   "description": "HTTPCloak native binary for win32 arm64",
   "os": [
     "win32"
@@ -9,6 +9,13 @@
     "arm64"
   ],
   "main": "lib.js",
+  "module": "lib.mjs",
+  "exports": {
+    ".": {
+      "import": "./lib.mjs",
+      "require": "./lib.js"
+    }
+  },
   "license": "MIT",
   "repository": {
     "type": "git",

package/npm/win32-x64/lib.mjs

@@ -0,0 +1,6 @@
+// Auto-generated - exports path to native library (ESM)
+import { fileURLToPath } from "url";
+import { dirname, join } from "path";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+export default join(__dirname, "libhttpcloak-windows-amd64.dll");

package/npm/win32-x64/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@httpcloak/win32-x64",
-  "version": "1.5.0",
+  "version": "1.5.2",
   "description": "HTTPCloak native binary for win32 x64",
   "os": [
     "win32"
@@ -9,6 +9,13 @@
     "x64"
   ],
   "main": "lib.js",
+  "module": "lib.mjs",
+  "exports": {
+    ".": {
+      "import": "./lib.mjs",
+      "require": "./lib.js"
+    }
+  },
   "license": "MIT",
   "repository": {
     "type": "git",

package/package.json

@@ -1,11 +1,25 @@
 {
   "name": "httpcloak",
-  "version": "1.5.0",
+  "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",
   "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./lib/index.d.ts",
+        "default": "./lib/index.mjs"
+      },
+      "require": {
+        "types": "./lib/index.d.ts",
+        "default": "./lib/index.js"
+      }
+    }
+  },
   "scripts": {
     "test": "node test.js",
+    "test:esm": "node test.mjs",
     "setup-packages": "node scripts/setup-npm-packages.js"
   },
   "keywords": [
@@ -35,11 +49,11 @@
     "koffi": "^2.9.0"
   },
   "optionalDependencies": {
-    "@httpcloak/linux-x64": "1.5.0",
-    "@httpcloak/linux-arm64": "1.5.0",
-    "@httpcloak/darwin-x64": "1.5.0",
-    "@httpcloak/darwin-arm64": "1.5.0",
-    "@httpcloak/win32-x64": "1.5.0",
-    "@httpcloak/win32-arm64": "1.5.0"
+    "@httpcloak/linux-x64": "1.5.1",
+    "@httpcloak/linux-arm64": "1.5.1",
+    "@httpcloak/darwin-x64": "1.5.1",
+    "@httpcloak/darwin-arm64": "1.5.1",
+    "@httpcloak/win32-x64": "1.5.1",
+    "@httpcloak/win32-arm64": "1.5.1"
   }
 }