httpcloak 1.5.9 → 1.6.0-beta.4

package/README.md

@@ -291,10 +291,10 @@ 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
+// Connect to example.com's IP but request www.cloudflare.com
 const session = new Session({
   preset: "chrome-143",
-  connectTo: { "www.cloudflare.com": "claude.ai" },
+  connectTo: { "www.cloudflare.com": "example.com" },
 });
 
 const response = await session.get("https://www.cloudflare.com/cdn-cgi/trace");
@@ -371,8 +371,8 @@ const session = new Session({
 const { availablePresets } = require("httpcloak");
 
 console.log(availablePresets());
-// ['chrome-143', 'chrome-143-windows', 'chrome-143-linux', 'chrome-143-macos',
-//  'chrome-131', 'firefox-133', 'safari-18', ...]
+// ['chrome-144', 'chrome-143', 'chrome-141', 'chrome-133',
+//  'firefox-133', 'safari-18', 'ios-chrome-144', ...]
 ```
 
 ## Response Object

package/lib/index.d.ts

@@ -11,6 +11,20 @@ export class Cookie {
   name: string;
   /** Cookie value */
   value: string;
+  /** Cookie domain */
+  domain: string;
+  /** Cookie path */
+  path: string;
+  /** Expiration date (RFC1123 format) */
+  expires: string;
+  /** Max age in seconds (0 means not set) */
+  maxAge: number;
+  /** Secure flag */
+  secure: boolean;
+  /** HttpOnly flag */
+  httpOnly: boolean;
+  /** SameSite attribute (Strict, Lax, None) */
+  sameSite: string;
 }
 
 export class RedirectInfo {
@@ -181,7 +195,7 @@ export class StreamResponse {
 }
 
 export interface SessionOptions {
-  /** Browser preset to use (default: "chrome-143") */
+  /** Browser preset to use (default: "chrome-144") */
   preset?: string;
   /** Proxy URL (e.g., "http://user:pass@host:port" or "socks5://host:port") */
   proxy?: string;
@@ -219,6 +233,10 @@ export interface SessionOptions {
   tlsOnly?: boolean;
   /** QUIC idle timeout in seconds (default: 30). Set higher for long-lived HTTP/3 connections. */
   quicIdleTimeout?: number;
+  /** Local IP address to bind outgoing connections (for IPv6 rotation with IP_FREEBIND on Linux) */
+  localAddress?: string;
+  /** Path to write TLS key log for Wireshark decryption (overrides SSLKEYLOGFILE env var) */
+  keyLogFile?: string;
 }
 
 export interface RequestOptions {
@@ -254,6 +272,12 @@ export class Session {
   /** Close the session and release resources */
   close(): void;
 
+  /** Refresh the session by closing all connections while keeping TLS session tickets.
+   * This simulates a browser page refresh - connections are severed but 0-RTT
+   * early data can be used on reconnection due to preserved session tickets.
+   */
+  refresh(): void;
+
   // Synchronous methods
   /** Perform a synchronous GET request */
   getSync(url: string, options?: RequestOptions): Response;
@@ -572,7 +596,7 @@ export class Session {
 export interface LocalProxyOptions {
   /** Port to listen on (default: 0 for auto-assign) */
   port?: number;
-  /** Browser preset to use (default: "chrome-143") */
+  /** Browser preset to use (default: "chrome-144") */
   preset?: string;
   /** Request timeout in seconds (default: 30) */
   timeout?: number;
@@ -599,6 +623,38 @@ export interface LocalProxyStats {
   bytesReceived: number;
 }
 
+/**
+ * Local HTTP proxy server that forwards requests through httpcloak with TLS fingerprinting.
+ * Use this to transparently apply fingerprinting to any HTTP client (e.g., Undici, fetch).
+ *
+ * Supports per-request proxy rotation via X-Upstream-Proxy header.
+ * Supports per-request session routing via X-HTTPCloak-Session header.
+ *
+ * IMPORTANT: For distributed session caching to work with X-HTTPCloak-Session header,
+ * you MUST register the session with the proxy using registerSession() first.
+ * Without registration, cache callbacks will not be triggered for that session.
+ *
+ * @example
+ * // Basic usage
+ * const proxy = new LocalProxy({ preset: "chrome-144", tlsOnly: true });
+ * console.log(`Proxy running on ${proxy.proxyUrl}`);
+ * // Use with any HTTP client pointing to the proxy
+ * proxy.close();
+ *
+ * @example
+ * // With distributed session cache
+ * const proxy = new LocalProxy({ port: 8888 });
+ * const session = new Session({ preset: 'chrome-144' });
+ *
+ * // Configure distributed cache
+ * httpcloak.configureSessionCache({
+ *   get: async (key) => await redis.get(key),
+ *   put: async (key, value, ttl) => { await redis.setex(key, ttl, value); return 0; },
+ * });
+ *
+ * // REQUIRED: Register session for cache callbacks to work
+ * proxy.registerSession('session-1', session);
+ */
 export class LocalProxy {
   /**
    * Create a new LocalProxy instance.
@@ -626,6 +682,9 @@ export class LocalProxy {
    * Register a session with an ID for use with X-HTTPCloak-Session header.
    * This allows per-request session routing through the proxy.
    *
+   * IMPORTANT: This is REQUIRED for distributed session caching to work.
+   * Without registration, cache callbacks will not be triggered for the session.
+   *
    * When a request is made through the proxy with the `X-HTTPCloak-Session: <sessionId>` header,
    * the proxy will use the registered session for that request, applying its TLS fingerprint
    * and cookies.
@@ -637,12 +696,13 @@ export class LocalProxy {
    * @example
    * ```typescript
    * const proxy = new LocalProxy({ port: 8888 });
-   * const session = new Session({ preset: 'chrome-143' });
+   * const session = new Session({ preset: 'chrome-144' });
    *
-   * // Register session with ID
+   * // Register session with ID (required for cache callbacks)
    * proxy.registerSession('user-1', session);
    *
    * // Now requests with X-HTTPCloak-Session: user-1 header will use this session
+   * // and trigger cache callbacks
    * ```
    */
   registerSession(sessionId: string, session: Session): void;
@@ -744,10 +804,13 @@ export const Preset: {
   CHROME_131_LINUX: string;
   CHROME_131_MACOS: string;
   IOS_CHROME_143: string;
+  IOS_CHROME_144: string;
   ANDROID_CHROME_143: string;
+  ANDROID_CHROME_144: string;
   FIREFOX_133: string;
   SAFARI_18: string;
   IOS_SAFARI_17: string;
+  IOS_SAFARI_18: string;
   all(): string[];
 };
 
@@ -759,42 +822,48 @@ export interface SessionCacheOptions {
   /**
    * Function to get session data from cache.
    * Returns JSON string with session data, or null if not found.
-   * Note: Must be synchronous - async callbacks are not supported.
+   * Supports both sync and async callbacks.
    */
-  get?: (key: string) => string | null;
+  get?: (key: string) => string | null | Promise<string | null>;
 
   /**
    * Function to store session data in cache.
    * Returns 0 on success, non-zero on error.
-   * Note: Must be synchronous - async callbacks are not supported.
+   * Supports both sync and async callbacks.
    */
-  put?: (key: string, value: string, ttlSeconds: number) => number;
+  put?: (key: string, value: string, ttlSeconds: number) => number | Promise<number>;
 
   /**
    * Function to delete session data from cache.
    * Returns 0 on success, non-zero on error.
-   * Note: Must be synchronous - async callbacks are not supported.
+   * Supports both sync and async callbacks.
    */
-  delete?: (key: string) => number;
+  delete?: (key: string) => number | Promise<number>;
 
   /**
    * Function to get ECH config from cache.
    * Returns base64-encoded config, or null if not found.
-   * Note: Must be synchronous - async callbacks are not supported.
+   * Supports both sync and async callbacks.
    */
-  getEch?: (key: string) => string | null;
+  getEch?: (key: string) => string | null | Promise<string | null>;
 
   /**
    * Function to store ECH config in cache.
    * Returns 0 on success, non-zero on error.
-   * Note: Must be synchronous - async callbacks are not supported.
+   * Supports both sync and async callbacks.
    */
-  putEch?: (key: string, value: string, ttlSeconds: number) => number;
+  putEch?: (key: string, value: string, ttlSeconds: number) => number | Promise<number>;
 
   /**
    * Error callback for cache operations.
    */
   onError?: (operation: string, key: string, error: string) => void;
+
+  /**
+   * Force async mode. If not specified, async mode is auto-detected
+   * based on whether any callback is an async function.
+   */
+  async?: boolean;
 }
 
 /**
@@ -803,13 +872,42 @@ export interface SessionCacheOptions {
  * Enables TLS session resumption across distributed httpcloak instances
  * by storing session tickets in an external cache like Redis or Memcached.
  *
+ * Supports both synchronous callbacks (for in-memory Map) and asynchronous
+ * callbacks (for Redis, database, etc.). Async mode is auto-detected when
+ * any callback is an async function.
+ *
  * Cache key formats:
  * - TLS sessions: httpcloak:sessions:{preset}:{protocol}:{host}:{port}
  * - ECH configs: httpcloak:ech:{preset}:{host}:{port}
+ *
+ * @example
+ * // Sync example with Map
+ * const cache = new Map();
+ * const backend = new SessionCacheBackend({
+ *   get: (key) => cache.get(key) || null,
+ *   put: (key, value, ttl) => { cache.set(key, value); return 0; },
+ *   delete: (key) => { cache.delete(key); return 0; },
+ * });
+ * backend.register();
+ *
+ * @example
+ * // Async example with Redis
+ * const redis = new Redis();
+ * const backend = new SessionCacheBackend({
+ *   get: async (key) => await redis.get(key),
+ *   put: async (key, value, ttl) => { await redis.setex(key, ttl, value); return 0; },
+ *   delete: async (key) => { await redis.del(key); return 0; },
+ * });
+ * backend.register();
  */
 export class SessionCacheBackend {
   constructor(options?: SessionCacheOptions);
 
+  /**
+   * Check if this backend is running in async mode.
+   */
+  readonly isAsync: boolean;
+
   /**
    * Register this cache backend globally.
    * After registration, all new Session and LocalProxy instances will use
@@ -827,8 +925,19 @@ export class SessionCacheBackend {
 /**
  * Configure a distributed session cache backend.
  *
+ * Supports both synchronous and asynchronous callbacks (auto-detected).
+ *
  * @param options Cache configuration
  * @returns The registered SessionCacheBackend instance
+ *
+ * @example
+ * // Using Redis with async callbacks
+ * const redis = new Redis();
+ * httpcloak.configureSessionCache({
+ *   get: async (key) => await redis.get(key),
+ *   put: async (key, value, ttl) => { await redis.setex(key, ttl, value); return 0; },
+ *   delete: async (key) => { await redis.del(key); return 0; },
+ * });
  */
 export function configureSessionCache(options: SessionCacheOptions): SessionCacheBackend;
 

package/lib/index.js

@@ -43,15 +43,11 @@ const Preset = {
   // Chrome 133
   CHROME_133: "chrome-133",
 
-  // Chrome 131
-  CHROME_131: "chrome-131",
-  CHROME_131_WINDOWS: "chrome-131-windows",
-  CHROME_131_LINUX: "chrome-131-linux",
-  CHROME_131_MACOS: "chrome-131-macos",
-
   // Mobile Chrome
   IOS_CHROME_143: "ios-chrome-143",
+  IOS_CHROME_144: "ios-chrome-144",
   ANDROID_CHROME_143: "android-chrome-143",
+  ANDROID_CHROME_144: "android-chrome-144",
 
   // Firefox
   FIREFOX_133: "firefox-133",
@@ -59,6 +55,7 @@ const Preset = {
   // Safari (desktop and mobile)
   SAFARI_18: "safari-18",
   IOS_SAFARI_17: "ios-safari-17",
+  IOS_SAFARI_18: "ios-safari-18",
 
   /**
    * Get all available preset names
@@ -66,11 +63,12 @@ const Preset = {
    */
   all() {
     return [
+      this.CHROME_144, this.CHROME_144_WINDOWS, this.CHROME_144_LINUX, this.CHROME_144_MACOS,
       this.CHROME_143, this.CHROME_143_WINDOWS, this.CHROME_143_LINUX, this.CHROME_143_MACOS,
-      this.CHROME_141, this.CHROME_133, this.CHROME_131,
-      this.IOS_CHROME_143, this.ANDROID_CHROME_143,
+      this.CHROME_141, this.CHROME_133,
+      this.IOS_CHROME_143, this.IOS_CHROME_144, this.ANDROID_CHROME_143, this.ANDROID_CHROME_144,
       this.FIREFOX_133,
-      this.SAFARI_18, this.IOS_SAFARI_17,
+      this.SAFARI_18, this.IOS_SAFARI_17, this.IOS_SAFARI_18,
     ];
   },
 };
@@ -105,16 +103,51 @@ const HTTP_STATUS_PHRASES = {
  */
 class Cookie {
   /**
-   * @param {string} name - Cookie name
-   * @param {string} value - Cookie value
-   */
-  constructor(name, value) {
-    this.name = name;
-    this.value = value;
+   * @param {Object} data - Cookie data from response
+   * @param {string} data.name - Cookie name
+   * @param {string} data.value - Cookie value
+   * @param {string} [data.domain] - Cookie domain
+   * @param {string} [data.path] - Cookie path
+   * @param {string} [data.expires] - Expiration date (RFC1123 format)
+   * @param {number} [data.max_age] - Max age in seconds
+   * @param {boolean} [data.secure] - Secure flag
+   * @param {boolean} [data.http_only] - HttpOnly flag
+   * @param {string} [data.same_site] - SameSite attribute (Strict, Lax, None)
+   */
+  constructor(data) {
+    if (typeof data === 'string') {
+      // Legacy: constructor(name, value)
+      this.name = data;
+      this.value = arguments[1] || "";
+      this.domain = "";
+      this.path = "";
+      this.expires = "";
+      this.maxAge = 0;
+      this.secure = false;
+      this.httpOnly = false;
+      this.sameSite = "";
+    } else {
+      this.name = data.name || "";
+      this.value = data.value || "";
+      this.domain = data.domain || "";
+      this.path = data.path || "";
+      this.expires = data.expires || "";
+      this.maxAge = data.max_age || 0;
+      this.secure = data.secure || false;
+      this.httpOnly = data.http_only || false;
+      this.sameSite = data.same_site || "";
+    }
   }
 
   toString() {
-    return `Cookie(name=${this.name}, value=${this.value})`;
+    let str = `Cookie(name=${this.name}, value=${this.value}`;
+    if (this.domain) str += `, domain=${this.domain}`;
+    if (this.path) str += `, path=${this.path}`;
+    if (this.secure) str += `, secure`;
+    if (this.httpOnly) str += `, httpOnly`;
+    if (this.sameSite) str += `, sameSite=${this.sameSite}`;
+    str += `)`;
+    return str;
   }
 }
 
@@ -156,7 +189,7 @@ class Response {
     this.elapsed = elapsed; // milliseconds
 
     // Parse cookies from response
-    this._cookies = (data.cookies || []).map(c => new Cookie(c.name || "", c.value || ""));
+    this._cookies = (data.cookies || []).map(c => new Cookie(c));
 
     // Parse redirect history
     this._history = (data.history || []).map(h => new RedirectInfo(
@@ -343,7 +376,7 @@ class FastResponse {
     this.elapsed = elapsed;
 
     // Parse cookies from response
-    this._cookies = (metadata.cookies || []).map(c => new Cookie(c.name || "", c.value || ""));
+    this._cookies = (metadata.cookies || []).map(c => new Cookie(c));
 
     // Parse redirect history
     this._history = (metadata.history || []).map(h => new RedirectInfo(
@@ -465,7 +498,7 @@ class StreamResponse {
     this.finalUrl = metadata.final_url || "";
     this.protocol = metadata.protocol || "";
     this.contentLength = metadata.content_length || -1;
-    this._cookies = (metadata.cookies || []).map(c => new Cookie(c.name || "", c.value || ""));
+    this._cookies = (metadata.cookies || []).map(c => new Cookie(c));
     this._closed = false;
   }
 
@@ -693,7 +726,7 @@ function getLibPath() {
 // Define callback proto globally for koffi (must be before getLib)
 const AsyncCallbackProto = koffi.proto("void AsyncCallback(int64 callbackId, str responseJson, str error)");
 
-// Session cache callback prototypes
+// Session cache callback prototypes (SYNC mode - for sync callbacks like Map)
 const SessionCacheGetProto = koffi.proto("str SessionCacheGet(str key)");
 const SessionCachePutProto = koffi.proto("int SessionCachePut(str key, str valueJson, int64 ttlSeconds)");
 const SessionCacheDeleteProto = koffi.proto("int SessionCacheDelete(str key)");
@@ -701,6 +734,13 @@ const SessionCacheErrorProto = koffi.proto("void SessionCacheError(str operation
 const EchCacheGetProto = koffi.proto("str EchCacheGet(str key)");
 const EchCachePutProto = koffi.proto("int EchCachePut(str key, str valueBase64, int64 ttlSeconds)");
 
+// Session cache callback prototypes (ASYNC mode - for async callbacks like Redis)
+const AsyncCacheGetProto = koffi.proto("void AsyncCacheGet(int64 requestId, str key)");
+const AsyncCachePutProto = koffi.proto("void AsyncCachePut(int64 requestId, str key, str valueJson, int64 ttlSeconds)");
+const AsyncCacheDeleteProto = koffi.proto("void AsyncCacheDelete(int64 requestId, str key)");
+const AsyncEchGetProto = koffi.proto("void AsyncEchGet(int64 requestId, str key)");
+const AsyncEchPutProto = koffi.proto("void AsyncEchPut(int64 requestId, str key, str valueBase64, int64 ttlSeconds)");
+
 // Load the native library
 let lib = null;
 let nativeLibHandle = null;
@@ -715,6 +755,8 @@ function getLib() {
     lib = {
       httpcloak_session_new: nativeLibHandle.func("httpcloak_session_new", "int64", ["str"]),
       httpcloak_session_free: nativeLibHandle.func("httpcloak_session_free", "void", ["int64"]),
+      httpcloak_session_refresh: nativeLibHandle.func("httpcloak_session_refresh", "void", ["int64"]),
+      httpcloak_session_refresh_protocol: nativeLibHandle.func("httpcloak_session_refresh_protocol", "str", ["int64", "str"]),
       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"]),
@@ -781,6 +823,18 @@ function getLib() {
         koffi.pointer(SessionCacheErrorProto),
       ]),
       httpcloak_clear_session_cache_callbacks: nativeLibHandle.func("httpcloak_clear_session_cache_callbacks", "void", []),
+      // Async session cache callbacks (for async backends like Redis)
+      httpcloak_set_async_session_cache_callbacks: nativeLibHandle.func("httpcloak_set_async_session_cache_callbacks", "void", [
+        koffi.pointer(AsyncCacheGetProto),
+        koffi.pointer(AsyncCachePutProto),
+        koffi.pointer(AsyncCacheDeleteProto),
+        koffi.pointer(AsyncEchGetProto),
+        koffi.pointer(AsyncEchPutProto),
+        koffi.pointer(SessionCacheErrorProto),
+      ]),
+      // Async cache result functions (called by JS to provide results to Go)
+      httpcloak_async_cache_get_result: nativeLibHandle.func("httpcloak_async_cache_get_result", "void", ["int64", "str"]),
+      httpcloak_async_cache_op_result: nativeLibHandle.func("httpcloak_async_cache_op_result", "void", ["int64", "int"]),
     };
   }
   return lib;
@@ -1078,7 +1132,9 @@ function version() {
 }
 
 /**
- * Get list of available browser presets
+ * Get available browser presets with their supported protocols.
+ * Returns an object mapping preset names to their info:
+ *   { "chrome-144": { protocols: ["h1", "h2", "h3"] }, ... }
  */
 function availablePresets() {
   const nativeLib = getLib();
@@ -1087,7 +1143,7 @@ function availablePresets() {
   if (result) {
     return JSON.parse(result);
   }
-  return [];
+  return {};
 }
 
 /**
@@ -1184,6 +1240,10 @@ class Session {
       echConfigDomain = null,
       tlsOnly = false,
       quicIdleTimeout = 0,
+      localAddress = null,
+      keyLogFile = null,
+      disableSpeculativeTls = false,
+      switchProtocol = null,
     } = options;
 
     this._lib = getLib();
@@ -1238,6 +1298,18 @@ class Session {
     if (quicIdleTimeout > 0) {
       config.quic_idle_timeout = quicIdleTimeout;
     }
+    if (localAddress) {
+      config.local_address = localAddress;
+    }
+    if (keyLogFile) {
+      config.key_log_file = keyLogFile;
+    }
+    if (disableSpeculativeTls) {
+      config.disable_speculative_tls = true;
+    }
+    if (switchProtocol) {
+      config.switch_protocol = switchProtocol;
+    }
 
     this._handle = this._lib.httpcloak_session_new(JSON.stringify(config));
 
@@ -1256,6 +1328,29 @@ class Session {
     }
   }
 
+  /**
+   * Refresh the session by closing all connections while keeping TLS session tickets.
+   * This simulates a browser page refresh - connections are severed but 0-RTT
+   * early data can be used on reconnection due to preserved session tickets.
+   * @param {string} [switchProtocol] - Optional protocol to switch to ("h1", "h2", "h3").
+   *   Overrides any switchProtocol set at construction time. Persists for future refresh() calls.
+   */
+  refresh(switchProtocol) {
+    if (this._handle) {
+      if (switchProtocol) {
+        const result = this._lib.httpcloak_session_refresh_protocol(this._handle, switchProtocol);
+        if (result) {
+          const data = JSON.parse(result);
+          if (data.error) {
+            throw new HTTPCloakError(data.error);
+          }
+        }
+      } else {
+        this._lib.httpcloak_session_refresh(this._handle);
+      }
+    }
+  }
+
   /**
    * Merge session headers with request headers
    */
@@ -2700,6 +2795,11 @@ function request(method, url, options = {}) {
  * Use this to transparently apply fingerprinting to any HTTP client (e.g., Undici, fetch).
  *
  * Supports per-request proxy rotation via X-Upstream-Proxy header.
+ * Supports per-request session routing via X-HTTPCloak-Session header.
+ *
+ * IMPORTANT: For distributed session caching to work with X-HTTPCloak-Session header,
+ * you MUST register the session with the proxy using registerSession() first.
+ * Without registration, cache callbacks will not be triggered for that session.
  *
  * @example
  * const proxy = new LocalProxy({ preset: "chrome-143", tlsOnly: true });
@@ -2709,6 +2809,22 @@ function request(method, url, options = {}) {
  * // Pass X-Upstream-Proxy header to rotate proxies per-request
  *
  * proxy.close();
+ *
+ * @example
+ * // Using with distributed session cache
+ * const proxy = new LocalProxy({ port: 8888 });
+ * const session = new Session({ preset: 'chrome-143' });
+ *
+ * // Configure distributed cache (e.g., Redis)
+ * httpcloak.configureSessionCache({
+ *   get: async (key) => await redis.get(key),
+ *   put: async (key, value, ttl) => { await redis.setex(key, ttl, value); return 0; },
+ * });
+ *
+ * // REQUIRED: Register session with proxy for cache callbacks to work
+ * proxy.registerSession('session-1', session);
+ *
+ * // Now requests with X-HTTPCloak-Session: session-1 will trigger cache callbacks
  */
 class LocalProxy {
   /**
@@ -2898,13 +3014,17 @@ class SessionCacheBackend {
   /**
    * Create a session cache backend.
    *
+   * Supports both synchronous and asynchronous callbacks. Async mode is automatically
+   * detected when any callback is an async function or returns a Promise.
+   *
    * @param {Object} options Cache configuration
-   * @param {Function} [options.get] Function to get session data: (key: string) => string|null|Promise<string|null>
-   * @param {Function} [options.put] Function to store session: (key: string, value: string, ttlSeconds: number) => number|Promise<number>
-   * @param {Function} [options.delete] Function to delete session: (key: string) => number|Promise<number>
-   * @param {Function} [options.getEch] Function to get ECH config: (key: string) => string|null|Promise<string|null>
-   * @param {Function} [options.putEch] Function to store ECH: (key: string, value: string, ttlSeconds: number) => number|Promise<number>
+   * @param {Function} [options.get] Get session data: (key: string) => string|null|Promise<string|null>
+   * @param {Function} [options.put] Store session: (key: string, value: string, ttlSeconds: number) => number|Promise<number>
+   * @param {Function} [options.delete] Delete session: (key: string) => number|Promise<number>
+   * @param {Function} [options.getEch] Get ECH config: (key: string) => string|null|Promise<string|null>
+   * @param {Function} [options.putEch] Store ECH: (key: string, value: string, ttlSeconds: number) => number|Promise<number>
    * @param {Function} [options.onError] Error callback: (operation: string, key: string, error: string) => void
+   * @param {boolean} [options.async] Force async mode (auto-detected if not specified)
    */
   constructor(options = {}) {
     this._get = options.get || null;
@@ -2914,6 +3034,23 @@ class SessionCacheBackend {
     this._putEch = options.putEch || null;
     this._onError = options.onError || null;
     this._registered = false;
+
+    // Auto-detect async mode based on function types
+    // AsyncFunction.constructor.name === 'AsyncFunction'
+    // Use !! to ensure boolean result (null && x returns null, not false)
+    const isAsyncFn = (fn) => !!(fn && (fn.constructor.name === 'AsyncFunction' || fn[Symbol.toStringTag] === 'AsyncFunction'));
+    this._asyncMode = options.async !== undefined ? options.async : (
+      isAsyncFn(this._get) || isAsyncFn(this._put) || isAsyncFn(this._delete) ||
+      isAsyncFn(this._getEch) || isAsyncFn(this._putEch)
+    );
+  }
+
+  /**
+   * Check if this backend is running in async mode.
+   * @returns {boolean}
+   */
+  get isAsync() {
+    return this._asyncMode;
   }
 
   /**
@@ -2926,17 +3063,42 @@ class SessionCacheBackend {
     const lib = getLib();
 
     // Create callback pointers (keep references to prevent GC)
-    // Use no-op callbacks for missing functions to avoid null pointer issues
     _sessionCacheCallbackPtrs = {};
 
-    // Create get callback (or no-op)
+    // Create error callback (shared between sync and async modes)
+    const errorFn = this._onError;
+    _sessionCacheCallbackPtrs.error = koffi.register((operation, key, error) => {
+      if (!errorFn) return;
+      try {
+        errorFn(operation, key, error);
+      } catch (e) {
+        // Ignore errors in error callback
+      }
+    }, koffi.pointer(SessionCacheErrorProto));
+
+    if (this._asyncMode) {
+      this._registerAsync(lib);
+    } else {
+      this._registerSync(lib);
+    }
+
+    _sessionCacheBackend = this;
+    this._registered = true;
+  }
+
+  /**
+   * Register synchronous callbacks (for in-memory Map, etc.)
+   * @private
+   */
+  _registerSync(lib) {
     const getFn = this._get;
     _sessionCacheCallbackPtrs.get = koffi.register((key) => {
       if (!getFn) return null;
       try {
         const result = getFn(key);
+        // If sync mode but user passed async function, warn and return null
         if (result && typeof result.then === 'function') {
-          console.warn('SessionCacheBackend: Async callbacks not fully supported, returning null');
+          console.warn('SessionCacheBackend: Detected async callback in sync mode. Use async: true option.');
           return null;
         }
         return result || null;
@@ -2945,13 +3107,13 @@ class SessionCacheBackend {
       }
     }, koffi.pointer(SessionCacheGetProto));
 
-    // Create put callback (or no-op)
     const putFn = this._put;
     _sessionCacheCallbackPtrs.put = koffi.register((key, value, ttlSeconds) => {
       if (!putFn) return 0;
       try {
         const result = putFn(key, value, Number(ttlSeconds));
         if (result && typeof result.then === 'function') {
+          console.warn('SessionCacheBackend: Detected async callback in sync mode. Use async: true option.');
           return 0;
         }
         return result || 0;
@@ -2960,13 +3122,13 @@ class SessionCacheBackend {
       }
     }, koffi.pointer(SessionCachePutProto));
 
-    // Create delete callback (or no-op)
     const deleteFn = this._delete;
     _sessionCacheCallbackPtrs.delete = koffi.register((key) => {
       if (!deleteFn) return 0;
       try {
         const result = deleteFn(key);
         if (result && typeof result.then === 'function') {
+          console.warn('SessionCacheBackend: Detected async callback in sync mode. Use async: true option.');
           return 0;
         }
         return result || 0;
@@ -2975,13 +3137,13 @@ class SessionCacheBackend {
       }
     }, koffi.pointer(SessionCacheDeleteProto));
 
-    // Create ECH get callback (or no-op)
     const getEchFn = this._getEch;
     _sessionCacheCallbackPtrs.getEch = koffi.register((key) => {
       if (!getEchFn) return null;
       try {
         const result = getEchFn(key);
         if (result && typeof result.then === 'function') {
+          console.warn('SessionCacheBackend: Detected async callback in sync mode. Use async: true option.');
           return null;
         }
         return result || null;
@@ -2990,13 +3152,13 @@ class SessionCacheBackend {
       }
     }, koffi.pointer(EchCacheGetProto));
 
-    // Create ECH put callback (or no-op)
     const putEchFn = this._putEch;
     _sessionCacheCallbackPtrs.putEch = koffi.register((key, value, ttlSeconds) => {
       if (!putEchFn) return 0;
       try {
         const result = putEchFn(key, value, Number(ttlSeconds));
         if (result && typeof result.then === 'function') {
+          console.warn('SessionCacheBackend: Detected async callback in sync mode. Use async: true option.');
           return 0;
         }
         return result || 0;
@@ -3005,18 +3167,6 @@ class SessionCacheBackend {
       }
     }, koffi.pointer(EchCachePutProto));
 
-    // Create error callback (or no-op)
-    const errorFn = this._onError;
-    _sessionCacheCallbackPtrs.error = koffi.register((operation, key, error) => {
-      if (!errorFn) return;
-      try {
-        errorFn(operation, key, error);
-      } catch (e) {
-        // Ignore errors in error callback
-      }
-    }, koffi.pointer(SessionCacheErrorProto));
-
-    // Register with library
     lib.httpcloak_set_session_cache_callbacks(
       _sessionCacheCallbackPtrs.get,
       _sessionCacheCallbackPtrs.put,
@@ -3025,9 +3175,104 @@ class SessionCacheBackend {
       _sessionCacheCallbackPtrs.putEch,
       _sessionCacheCallbackPtrs.error
     );
+  }
 
-    _sessionCacheBackend = this;
-    this._registered = true;
+  /**
+   * Register asynchronous callbacks (for Redis, database, etc.)
+   * Go will call our callback with a request ID, we process async,
+   * then call back into Go with the result.
+   * @private
+   */
+  _registerAsync(lib) {
+    const getFn = this._get;
+    _sessionCacheCallbackPtrs.get = koffi.register((requestId, key) => {
+      if (!getFn) {
+        lib.httpcloak_async_cache_get_result(requestId, null);
+        return;
+      }
+      // Process async and call back with result
+      Promise.resolve()
+        .then(() => getFn(key))
+        .then((result) => {
+          lib.httpcloak_async_cache_get_result(requestId, result || null);
+        })
+        .catch(() => {
+          lib.httpcloak_async_cache_get_result(requestId, null);
+        });
+    }, koffi.pointer(AsyncCacheGetProto));
+
+    const putFn = this._put;
+    _sessionCacheCallbackPtrs.put = koffi.register((requestId, key, value, ttlSeconds) => {
+      if (!putFn) {
+        lib.httpcloak_async_cache_op_result(requestId, 0);
+        return;
+      }
+      Promise.resolve()
+        .then(() => putFn(key, value, Number(ttlSeconds)))
+        .then((result) => {
+          lib.httpcloak_async_cache_op_result(requestId, result || 0);
+        })
+        .catch(() => {
+          lib.httpcloak_async_cache_op_result(requestId, -1);
+        });
+    }, koffi.pointer(AsyncCachePutProto));
+
+    const deleteFn = this._delete;
+    _sessionCacheCallbackPtrs.delete = koffi.register((requestId, key) => {
+      if (!deleteFn) {
+        lib.httpcloak_async_cache_op_result(requestId, 0);
+        return;
+      }
+      Promise.resolve()
+        .then(() => deleteFn(key))
+        .then((result) => {
+          lib.httpcloak_async_cache_op_result(requestId, result || 0);
+        })
+        .catch(() => {
+          lib.httpcloak_async_cache_op_result(requestId, -1);
+        });
+    }, koffi.pointer(AsyncCacheDeleteProto));
+
+    const getEchFn = this._getEch;
+    _sessionCacheCallbackPtrs.getEch = koffi.register((requestId, key) => {
+      if (!getEchFn) {
+        lib.httpcloak_async_cache_get_result(requestId, null);
+        return;
+      }
+      Promise.resolve()
+        .then(() => getEchFn(key))
+        .then((result) => {
+          lib.httpcloak_async_cache_get_result(requestId, result || null);
+        })
+        .catch(() => {
+          lib.httpcloak_async_cache_get_result(requestId, null);
+        });
+    }, koffi.pointer(AsyncEchGetProto));
+
+    const putEchFn = this._putEch;
+    _sessionCacheCallbackPtrs.putEch = koffi.register((requestId, key, value, ttlSeconds) => {
+      if (!putEchFn) {
+        lib.httpcloak_async_cache_op_result(requestId, 0);
+        return;
+      }
+      Promise.resolve()
+        .then(() => putEchFn(key, value, Number(ttlSeconds)))
+        .then((result) => {
+          lib.httpcloak_async_cache_op_result(requestId, result || 0);
+        })
+        .catch(() => {
+          lib.httpcloak_async_cache_op_result(requestId, -1);
+        });
+    }, koffi.pointer(AsyncEchPutProto));
+
+    lib.httpcloak_set_async_session_cache_callbacks(
+      _sessionCacheCallbackPtrs.get,
+      _sessionCacheCallbackPtrs.put,
+      _sessionCacheCallbackPtrs.delete,
+      _sessionCacheCallbackPtrs.getEch,
+      _sessionCacheCallbackPtrs.putEch,
+      _sessionCacheCallbackPtrs.error
+    );
   }
 
   /**
@@ -3053,11 +3298,25 @@ class SessionCacheBackend {
  * Configure a distributed session cache backend.
  *
  * This is a convenience function that creates and registers a SessionCacheBackend.
+ * Supports both synchronous and asynchronous callbacks (auto-detected).
  *
  * @param {Object} options Cache configuration (same as SessionCacheBackend constructor)
  * @returns {SessionCacheBackend} The registered backend
  *
- * Example:
+ * Example using in-memory Map (sync):
+ * ```javascript
+ * const httpcloak = require('httpcloak');
+ *
+ * const cache = new Map();
+ *
+ * httpcloak.configureSessionCache({
+ *   get: (key) => cache.get(key) || null,
+ *   put: (key, value, ttl) => { cache.set(key, value); return 0; },
+ *   delete: (key) => { cache.delete(key); return 0; },
+ * });
+ * ```
+ *
+ * Example using Redis (async):
  * ```javascript
  * const Redis = require('ioredis');
  * const httpcloak = require('httpcloak');
@@ -3065,12 +3324,12 @@ class SessionCacheBackend {
  * const redis = new Redis();
  *
  * httpcloak.configureSessionCache({
- *   get: (key) => redis.get(key),
- *   put: (key, value, ttl) => { redis.setex(key, ttl, value); return 0; },
- *   delete: (key) => { redis.del(key); return 0; },
+ *   get: async (key) => await redis.get(key),
+ *   put: async (key, value, ttl) => { await redis.setex(key, ttl, value); return 0; },
+ *   delete: async (key) => { await redis.del(key); return 0; },
  * });
  *
- * // Now all sessions will use Redis for TLS session storage
+ * // Async callbacks are automatically detected and handled properly
  * const session = new httpcloak.Session();
  * await session.get('https://example.com');
  * ```

package/lib/index.mjs

@@ -12,11 +12,26 @@ const require = createRequire(import.meta.url);
 const cjs = require("./index.js");
 
 // Re-export all named exports
+// Classes
 export const Session = cjs.Session;
+export const LocalProxy = cjs.LocalProxy;
 export const Response = cjs.Response;
+export const FastResponse = cjs.FastResponse;
+export const StreamResponse = cjs.StreamResponse;
+export const Cookie = cjs.Cookie;
+export const RedirectInfo = cjs.RedirectInfo;
 export const HTTPCloakError = cjs.HTTPCloakError;
+export const SessionCacheBackend = cjs.SessionCacheBackend;
+
+// Presets
 export const Preset = cjs.Preset;
+
+// Configuration
 export const configure = cjs.configure;
+export const configureSessionCache = cjs.configureSessionCache;
+export const clearSessionCache = cjs.clearSessionCache;
+
+// Module-level functions
 export const get = cjs.get;
 export const post = cjs.post;
 export const put = cjs.put;
@@ -24,9 +39,15 @@ export const patch = cjs.patch;
 export const head = cjs.head;
 export const options = cjs.options;
 export const request = cjs.request;
+
+// Utility
 export const version = cjs.version;
 export const availablePresets = cjs.availablePresets;
 
+// DNS configuration
+export const setEchDnsServers = cjs.setEchDnsServers;
+export const getEchDnsServers = cjs.getEchDnsServers;
+
 // 'delete' is a reserved word in ESM, so we export it specially
 const del = cjs.delete;
 export { del as delete };

package/npm/darwin-arm64/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@httpcloak/darwin-arm64",
-  "version": "1.5.9",
+  "version": "1.6.0-beta.4",
   "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.9",
+  "version": "1.6.0-beta.4",
   "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.9",
+  "version": "1.6.0-beta.4",
   "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.9",
+  "version": "1.6.0-beta.4",
   "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.9",
+  "version": "1.6.0-beta.4",
   "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.9",
+  "version": "1.6.0-beta.4",
   "description": "HTTPCloak native binary for win32 x64",
   "os": [
     "win32"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "httpcloak",
-  "version": "1.5.9",
+  "version": "1.6.0-beta.4",
   "description": "Browser fingerprint emulation HTTP client with HTTP/1.1, HTTP/2, and HTTP/3 support",
   "main": "lib/index.js",
   "module": "lib/index.mjs",
@@ -49,11 +49,15 @@
     "koffi": "^2.9.0"
   },
   "optionalDependencies": {
-    "@httpcloak/linux-x64": "1.5.9",
-    "@httpcloak/linux-arm64": "1.5.9",
-    "@httpcloak/darwin-x64": "1.5.9",
-    "@httpcloak/darwin-arm64": "1.5.9",
-    "@httpcloak/win32-x64": "1.5.9",
-    "@httpcloak/win32-arm64": "1.5.9"
+    "@httpcloak/darwin-arm64": "1.6.0-beta.4",
+    "@httpcloak/darwin-x64": "1.6.0-beta.4",
+    "@httpcloak/linux-arm64": "1.6.0-beta.4",
+    "@httpcloak/linux-x64": "1.6.0-beta.4",
+    "@httpcloak/win32-arm64": "1.6.0-beta.4",
+    "@httpcloak/win32-x64": "1.6.0-beta.4"
+  },
+  "devDependencies": {
+    "@types/node": "^25.1.0",
+    "typescript": "^5.9.3"
   }
 }