httpcloak 1.5.7 → 1.5.9

package/README.md

@@ -334,8 +334,8 @@ console.log(cookies);
 // Access cookies as property
 console.log(session.cookies);
 
-// Clear a cookie
-session.clearCookie("session_id");
+// Delete a cookie
+session.deleteCookie("session_id");
 
 // Clear all cookies
 session.clearCookies();
@@ -506,6 +506,153 @@ async function downloadLargeFile(): Promise<void> {
 }
 ```
 
+## Local Proxy
+
+Use `LocalProxy` to apply TLS fingerprinting to any HTTP client (axios, node-fetch, etc.).
+
+### HTTPS with True Streaming (Recommended)
+
+For HTTPS requests with full fingerprinting AND true streaming (request/response bodies not materialized into memory), use the `X-HTTPCloak-Scheme` header:
+
+```javascript
+const { LocalProxy } = require("httpcloak");
+const axios = require("axios");
+
+// Start local proxy with Chrome fingerprint
+const proxy = new LocalProxy({ preset: "chrome-143" });
+console.log(`Proxy running on ${proxy.proxyUrl}`);
+
+// Use X-HTTPCloak-Scheme header for HTTPS with fingerprinting + streaming
+const response = await axios.get("http://example.com/api", {
+  // Note: http:// URL
+  proxy: {
+    host: "127.0.0.1",
+    port: proxy.port,
+  },
+  headers: {
+    "X-HTTPCloak-Scheme": "https", // Upgrades to HTTPS with fingerprinting
+  },
+});
+
+// This provides:
+// - Full TLS fingerprinting (Chrome/Firefox JA3/JA4)
+// - HTTP/3 support
+// - True streaming (request body NOT materialized into memory)
+// - Header modification capabilities
+
+proxy.close();
+```
+
+**Why use `X-HTTPCloak-Scheme`?**
+
+Standard HTTP proxy clients use CONNECT tunneling for HTTPS, which means the proxy can't inspect or modify the request. The `X-HTTPCloak-Scheme: https` header tells LocalProxy to:
+1. Accept the request as plain HTTP
+2. Upgrade it to HTTPS internally
+3. Apply full TLS fingerprinting
+4. Stream request/response bodies without memory materialization
+
+### Basic Usage
+
+```javascript
+const { LocalProxy } = require("httpcloak");
+const axios = require("axios");
+
+// Start local proxy with Chrome fingerprint
+const proxy = new LocalProxy({ preset: "chrome-143" });
+
+// Standard HTTPS (uses CONNECT tunnel - fingerprinting via upstream proxy only)
+const response = await axios.get("https://example.com", {
+  proxy: {
+    host: "127.0.0.1",
+    port: proxy.port,
+  },
+});
+
+// Per-request upstream proxy rotation
+const rotatedResponse = await axios.get("https://example.com", {
+  proxy: {
+    host: "127.0.0.1",
+    port: proxy.port,
+  },
+  headers: {
+    "X-Upstream-Proxy": "http://user:pass@rotating-proxy.com:8080",
+  },
+});
+
+proxy.close();
+```
+
+### TLS-Only Mode
+
+When your client already provides authentic browser headers, use TLS-only mode:
+
+```javascript
+const { LocalProxy } = require("httpcloak");
+
+// Only apply TLS fingerprint, pass headers through
+const proxy = new LocalProxy({ preset: "chrome-143", tlsOnly: true });
+
+// Your client's headers are preserved
+const response = await fetch("https://example.com", {
+  agent: new HttpsProxyAgent(proxy.proxyUrl),
+  headers: { "User-Agent": "My Custom UA" },
+});
+
+proxy.close();
+```
+
+### Session Registry
+
+Route different requests through different browser fingerprints:
+
+```javascript
+const { LocalProxy, Session } = require("httpcloak");
+
+const proxy = new LocalProxy({ preset: "chrome-143" });
+
+// Create sessions with different fingerprints
+const chromeSession = new Session({ preset: "chrome-143" });
+const firefoxSession = new Session({ preset: "firefox-133" });
+
+// Register sessions with the proxy
+proxy.registerSession("chrome-user", chromeSession);
+proxy.registerSession("firefox-user", firefoxSession);
+
+// Route requests using X-HTTPCloak-Session header
+const response = await axios.get("https://example.com", {
+  proxy: { host: "127.0.0.1", port: proxy.port },
+  headers: { "X-HTTPCloak-Session": "firefox-user" }, // Uses firefox fingerprint
+});
+
+// Unregister when done
+proxy.unregisterSession("chrome-user");
+proxy.unregisterSession("firefox-user");
+
+chromeSession.close();
+firefoxSession.close();
+proxy.close();
+```
+
+### LocalProxy Options
+
+```javascript
+const proxy = new LocalProxy({
+  port: 0,              // Port (0 = auto-select)
+  preset: "chrome-143", // Browser fingerprint
+  timeout: 30,          // Request timeout in seconds
+  maxConnections: 1000, // Max concurrent connections
+  tcpProxy: null,       // Default upstream TCP proxy
+  udpProxy: null,       // Default upstream UDP proxy
+  tlsOnly: false,       // TLS-only mode
+});
+
+proxy.port;           // Actual port number
+proxy.proxyUrl;       // Full proxy URL (http://127.0.0.1:port)
+proxy.isRunning;      // True if proxy is active
+proxy.getStats();     // Returns object with request/connection stats
+proxy.close();        // Stop the proxy
+```
+
 ## Platform Support
 
 - Linux (x64, arm64)