From fa9f15b3745b743d00d52bdf81f085f18dff68f6 Mon Sep 17 00:00:00 2001 From: Luxferre Date: Wed, 26 Aug 2026 08:24:40 +0300 Subject: [PATCH] working defaults --- README.md | 35 ++++++++++++++++++----------------- architecture.md | 35 +++++++++++++++-------------------- th3ist.go | 31 +++++++++++++++++++++++++------ 3 files changed, 58 insertions(+), 43 deletions(-) diff --git a/README.md b/README.md index 802627b..d9c2083 100644 --- a/README.md +++ b/README.md @@ -5,11 +5,14 @@ ## Features - **Standard OpenAI interface**: Serves `/v1/chat/completions` and `/v1/models` (with `/chat/completions` and `/models` aliases). -- **Dual-engine architecture**: - - **Browser bridge (`-auto-capture`)**: Routes upstream requests directly through a private, stealth headless Chromium session over CDP. This ensures a 100% genuine Chrome TLS handshake (JA3/JA4), completely bypassing Vercel Security Checkpoints and WAF blocks. - - **Direct HTTP client**: Fallback mode for high-throughput environments where valid Vercel clearance cookies and tokens are supplied directly. +- **Dual-engine architecture (Browser Bridge enabled by default)**: + - **Browser bridge (`-auto-capture`, default: true)**: Routes upstream requests directly through a private, stealth offscreen Chromium session over CDP with automatic virtual X server (`Xvfb`) isolation. This ensures a 100% genuine Chrome TLS handshake (JA3/JA4), completely bypassing Vercel Security Checkpoints and WAF blocks out of the box. + - **Direct HTTP client (`-direct` / `-no-bridge`)**: Fallback mode for high-throughput environments where valid Vercel clearance cookies and tokens are supplied directly. +- **Real-time per-token streaming**: Streams tokens in real time over CDP via `Runtime.addBinding` and `ReadableStreamDefaultReader`, passing token chunks immediately through stateful thinking and tool call filters without buffering. +- **Automated hardware fingerprint rotation & 429 auto-recovery**: Dynamically discovers FingerprintJS entropy modules (or generates high-entropy synthetic fallbacks) and auto-rotates visitor identities upon encountering `HTTP 429` / rate limits, retrying immediately (up to 4 attempts) without dropping client connections. - **Private & anti-fingerprinting stealth**: - **100% isolated session**: Launches in `--incognito` mode with a temporary ephemeral user profile and `--disable-extensions`, completely segregated from any existing Chromium/Chrome windows, history, extensions, or sessions. + - **Auto-managed virtual display (`-xvfb`, default: true)**: Spawns an isolated Xvfb display to completely isolate Chromium from tiling window managers (i3, bspwm, sway, dwm). - **Zero port collisions**: Binds to a dynamically allocated ephemeral loopback port for CDP commands. - **Stealth & anti-detection**: - Disables Blink automation features (`--disable-blink-features=AutomationControlled`). @@ -19,7 +22,6 @@ - Strips telemetry, domain reliability, crash reporting, and sync. - **Dynamic token ingestion API**: Provides `GET /v1/token` and `POST /v1/token` to inspect or hot-reload single-use hCaptcha tokens and cookies on the fly without restarting the server. - **Fast fail & clear error propagation**: Non-transient errors (such as `captcha_failed` or `invalid_params`) return immediately (<300ms) without wasting time in exponential backoff retry loops. -- **Streaming & non-streaming**: Full support for Server-Sent Events (`stream: true`) and standard JSON responses (`stream: false`). - **Reasoning content separation**: Parses `...` tags and upstream reasoning chunks into `reasoning_content` deltas / message fields. - **Function / tool calling translation**: Injects tool schemas into system instructions, maps multi-turn tool calling history, and parses model tool invocations into standard OpenAI `tool_calls`. - **Zero external dependencies**: Implemented using pure Go standard library. @@ -41,19 +43,24 @@ Binary will be produced at `bin/th3ist`. ## Running ```bash -# Run with Browser Bridge active (recommended for bypassing Vercel TLS checkpoint) -./bin/th3ist -auto-capture +# Run with default settings (Browser Bridge and isolated Xvfb active) +./bin/th3ist # Run on a custom port with static defaults ./bin/th3ist -port 9000 -default-model gemini-3.5-flash-lite + +# Run in direct HTTP client mode (bypasses browser bridge) +./bin/th3ist -direct ``` ### CLI flags | Flag | Description | Default | |------|-------------|---------| -| `-auto-capture` | Enable private browser bridge (bypasses Vercel TLS & mints fresh tokens) | `false` | -| `-xvfb` | Automatically spawn and manage an isolated virtual X server (`Xvfb`) for complete isolation from tiling window managers | `false` | +| `-auto-capture` | Enable private browser bridge (bypasses Vercel TLS & mints fresh tokens) | `true` | +| `-direct` / `-no-bridge` | Disable browser bridge and run in direct HTTP mode | `false` | +| `-xvfb` / `-Xvfb` | Automatically spawn and manage an isolated virtual X server (`Xvfb`) for complete isolation from tiling window managers | `true` | +| `-no-xvfb` | Disable automatic virtual X server (uses active `$DISPLAY`) | `false` | | `-display` | Custom X11 DISPLAY to attach Chromium to (e.g. `:99` for an existing Xvfb / Xephyr / Xnest session) | *(auto / `$DISPLAY`)* | | `-headless` | Force strict headless mode `--headless=new` (defaults to offscreen window when display is present) | `false` | | `-browser-bin` | Custom path to Chromium/Google Chrome binary | *(auto-detected)* | @@ -68,20 +75,14 @@ Binary will be produced at `bin/th3ist`. ### Tiled window managers & virtual display isolation -On tiling window managers (e.g., i3, bspwm, sway, dwm, awesome, hyprland, xmonad), any window created on the main `$DISPLAY` may be caught and tiled into the current workspace. +On tiling window managers (e.g., i3, bspwm, sway, dwm, awesome, hyprland, xmonad), `th3ist` defaults to managing an isolated virtual X server (`-xvfb`) so that no Chromium windows appear on your desktop workspace: -To prevent any windows from appearing on your desktop: - -1. **Option A: Auto-managed Xvfb (`-xvfb`)**: +1. **Option A: Auto-managed Xvfb (Default)**: Install `xorg-server-xvfb` (or `Xfbdev`): - **Void Linux**: `sudo xbps-install -S xorg-server-xvfb` - **Debian / Ubuntu**: `sudo apt install xvfb` - **Arch Linux**: `sudo pacman -S xorg-server-xvfb` - Then run `th3ist` with `-xvfb`: - ```bash - ./bin/th3ist -auto-capture -xvfb -port 9000 - ``` `th3ist` will automatically allocate an isolated virtual display (e.g. `:99`), launch `Xvfb`, attach Chromium to it, and cleanly terminate `Xvfb` on exit. 2. **Option B: Manual virtual X server (`Xvfb`, `Xephyr`, or `Xnest`)**: @@ -90,7 +91,7 @@ To prevent any windows from appearing on your desktop: Xvfb :99 -screen 0 1280x800x24 -ac & # Run th3ist attached to display :99 - ./bin/th3ist -auto-capture -display :99 -port 9000 + ./bin/th3ist -display :99 -port 9000 ``` 3. **Option C: Tiling window manager rules (`--class=th3ist_hidden`)**: diff --git a/architecture.md b/architecture.md index 75f5277..599031f 100644 --- a/architecture.md +++ b/architecture.md @@ -90,8 +90,8 @@ args := []string{ - **Offscreen positioning (`-3000, -3000`)**: Keeps the browser window completely off the visible desktop area without taking focus, stealing cursor input, or disrupting user workflow. - **Tiled window manager isolation (`-xvfb` / `-display`)**: - - Tiling window managers (i3, bspwm, sway, dwm) can capture offscreen windows on the main display. `th3ist` provides `-xvfb` to automatically launch and attach to a virtual X server (`Xvfb : -screen 0 1280x800x24`), ensuring 100% isolation from the desktop environment. - - Users can also supply a custom `-display :99` (for existing `Xvfb`, `Xephyr`, or `Xnest` sessions). + - Tiling window managers (i3, bspwm, sway, dwm, awesome, hyprland, xmonad) can capture offscreen windows on the main display. `th3ist` defaults to managing an isolated virtual X server (`-xvfb`, default: true) via `Xvfb : -screen 0 1280x800x24`, ensuring 100% isolation from the desktop environment out of the box. + - Users can also supply a custom `-display :99` (for existing `Xvfb`, `Xephyr`, or `Xnest` sessions) or pass `-no-xvfb` to attach to `$DISPLAY`. - Sets window class `--class=th3ist_hidden` and `--app=https://t3.chat` for easy floating/scratchpad filtering. - **Headless detection evasion**: Running in an active display context (real or virtual Xvfb) prevents hCaptcha Enterprise's client heuristics from detecting headless browser environments, ensuring automated invisible token generation succeeds. - **Strict headless fallback (`-headless`)**: When the `-headless` flag is passed or when `DISPLAY` is unset (e.g. Docker or server environments), it automatically uses `--headless=new`. @@ -173,7 +173,7 @@ Chromium ReadableStream (window.th3istStreamChunk) ├─► Emits structured OpenAI delta.tool_calls └─► Emits clean assistant text to delta.content in real time ``` -1. `Runtime.addBinding`: Exposes `window.th3istStreamChunk` to the browser context, relaying `ReadableStream` chunks over CDP in real time without buffering. +1. `Runtime.addBinding`: Exposes `window.th3istStreamChunk` to the browser context upon bridge startup, relaying in-page `ReadableStream` chunks over CDP in real time without buffering. 2. `StreamLineBuffer`: Reassembles partial TCP packets into complete protocol lines across chunk boundaries. 3. `StreamThinkingFilter`: Stateful filter intercepting `...` tags and routing to `reasoning_content`. 4. `StreamToolCallFilter`: Stateful filter intercepting `...` tags, preventing raw XML leaks in `content` and emitting OpenAI `delta.tool_calls`. @@ -214,7 +214,7 @@ To allow external token management or custom API keys: ### 3.6. Error handling & fast-fail semantics -- **Client errors (`400`, `401`, `403`)**: Non-transient errors (such as `captcha_failed` or `invalid_params`) bypass retry loops and return immediately in `<300ms` with original error bodies and HTTP status codes. +- **Client errors (`400`, `401`, `403`)**: Non-transient errors (such as `invalid_params`) bypass retry loops and return immediately in `<300ms` with original error bodies and HTTP status codes. - **Server errors (`5xx`)**: Direct HTTP fallback requests utilize `DoWithFibonacciRetry` with bounded Fibonacci delays (1s, 1s, 2s, 3s, 5s) before failing. --- @@ -234,18 +234,13 @@ Empirical testing confirmed that rate limiting on `t3.chat` is **tracked strictl #### 2. Automated hardware fingerprint mutation engine (`RotateIdentity`) Because `th3ist` controls Chromium via CDP, `BrowserBridge.RotateIdentity()` mutates client hardware entropy on demand: -- **Canvas entropy**: Injects pseudo-random variations into 2D canvas geometry hashing. +- **Dynamic module discovery & synthetic fallback**: Searches `document.scripts` and `performance.getEntriesByType('resource')` for active FingerprintJS modules before falling back to asset paths. If unavailable, synthesizes a complete set of high-entropy components. +- **Canvas entropy**: Injects pseudo-random variations into 2D canvas geometry & text hashing. - **Audio entropy**: Adds subtle jitter to `AudioContext` frequency responses. -- **Hardware concurrency & resolution**: Mutates CPU core counts (4, 6, 8, 12, 16) and screen resolutions. -- Submits the modified components to `/api/identity`, which returns: - ```json - { - "visitorId": "visitor_", - "requiresSignIn": false, - "confidence": 1 - } - ``` -- **Zero-downtime auto-recovery**: If `ExecuteFetch()` receives an `HTTP 429` or rate limit error, it immediately invokes `RotateIdentity()`, mints a fresh hCaptcha token, resets session IDs, and retries the completion request transparently (up to 4 attempts) without returning 429 errors to the client right away. +- **Hardware concurrency, resolution & memory**: Mutates CPU core counts (4, 6, 8, 12, 16, 24, 32), screen resolutions, and device memory values (4, 8, 16, 32 GB). +- **Storage reset**: Clears cached visitor markers from `localStorage` and `sessionStorage`. +- Submits the modified components to `/api/identity`, which returns a fresh signed `visitor_` and updates the browser cookie jar. +- **Zero-downtime multi-attempt auto-recovery**: When `ExecuteFetch()` or `ExecuteStreamFetch()` receives an `HTTP 429` or rate limit response, it immediately invokes `RotateIdentity()`, mints a fresh hCaptcha token, resets session IDs, and retries the request transparently (up to 4 attempts) without returning 429 errors to the client right away. #### 3. Bypassing guest limits via BYOK (bring your own key) `th3ist` also supports passing custom provider API keys directly in standard OpenAI format: @@ -262,11 +257,11 @@ curl http://localhost:8080/v1/chat/completions \ | File | Purpose | |------|---------| -| [`th3ist.go`](file:///home/lux/ditch/th3ist/th3ist.go) | Main server, BrowserBridge implementation, CDP protocol handler, stream parsers, tool calling converter, and HTTP handlers. | -| [`th3ist_test.go`](file:///home/lux/ditch/th3ist/th3ist_test.go) | Unit test suite covering message transforms, thinking tag filters, tool calling detection, mock upstream completions, and live bridge tests. | -| [`Makefile`](file:///home/lux/ditch/th3ist/Makefile) | Build, test, run, and cleanup targets. | -| [`README.md`](file:///home/lux/ditch/th3ist/README.md) | User documentation, quickstart guide, CLI flags, and API examples. | -| [`architecture.md`](file:///home/lux/ditch/th3ist/architecture.md) | In-depth architectural design, reverse engineering findings, and security mechanisms. | +| [`th3ist.go`](file:///home/lux/proj/th3ist/th3ist.go) | Main server, BrowserBridge implementation, CDP protocol handler, stream parsers, tool calling converter, and HTTP handlers. | +| [`th3ist_test.go`](file:///home/lux/proj/th3ist/th3ist_test.go) | Unit test suite covering message transforms, thinking tag filters, tool calling detection, mock upstream completions, and live bridge tests. | +| [`Makefile`](file:///home/lux/proj/th3ist/Makefile) | Build, test, run, and cleanup targets. | +| [`README.md`](file:///home/lux/proj/th3ist/README.md) | User documentation, quickstart guide, CLI flags, and API examples. | +| [`architecture.md`](file:///home/lux/proj/th3ist/architecture.md) | In-depth architectural design, reverse engineering findings, and security mechanisms. | --- diff --git a/th3ist.go b/th3ist.go index b4fa8fd..49e5e71 100644 --- a/th3ist.go +++ b/th3ist.go @@ -2940,10 +2940,15 @@ func main() { deploymentFlag := flag.String("deployment-id", DefaultDeploymentID, "x-deployment-id header value") clientContextFlag := flag.String("client-context", DefaultClientContext, "x-client-context header value") browserBinFlag := flag.String("browser-bin", "", "Custom path to Chromium/Chrome binary for auto-capture") - autoCaptureFlag := flag.Bool("auto-capture", false, "Automatically bridge requests and auto-generate fresh hCaptcha tokens via Chromium") + autoCaptureFlag := flag.Bool("auto-capture", true, "Automatically bridge requests and auto-generate fresh hCaptcha tokens via Chromium (default true)") + directFlag := flag.Bool("direct", false, "Disable browser bridge and run in direct HTTP client mode") + noBridgeFlag := flag.Bool("no-bridge", false, "Disable browser bridge (alias for -direct)") + noAutoCaptureFlag := flag.Bool("no-auto-capture", false, "Disable browser bridge (alias for -direct)") headlessFlag := flag.Bool("headless", false, "Force strict headless mode (defaults to offscreen window if display is available)") displayFlag := flag.String("display", "", "Custom X11 DISPLAY to run browser on (e.g. :99 for Xvfb / Xephyr / Xnest)") - xvfbFlag := flag.Bool("xvfb", false, "Automatically spawn and manage an isolated virtual X server (Xvfb) for headless tiling WM environments") + xvfbFlag := flag.Bool("xvfb", true, "Automatically spawn and manage an isolated virtual X server (Xvfb) for headless tiling WM environments (default true)") + xvfbUpperFlag := flag.Bool("Xvfb", false, "Alias for -xvfb") + noXvfbFlag := flag.Bool("no-xvfb", false, "Disable automatic virtual X server (use active DISPLAY)") uaFlag := flag.String("user-agent", DefaultUserAgent, "User-Agent header to send upstream") uaShortFlag := flag.String("ua", "", "Alias for -user-agent") flag.Parse() @@ -2954,6 +2959,19 @@ func main() { ConfiguredUserAgent = *uaFlag } + effectiveAutoCapture := *autoCaptureFlag + if *directFlag || *noBridgeFlag || *noAutoCaptureFlag { + effectiveAutoCapture = false + } + + effectiveXvfb := *xvfbFlag + if *xvfbUpperFlag { + effectiveXvfb = true + } + if *noXvfbFlag { + effectiveXvfb = false + } + gateway := NewT3Gateway( *targetURLFlag, *clientContextFlag, @@ -2962,13 +2980,13 @@ func main() { *hcaptchaFlag, *defaultModelFlag, *browserBinFlag, - *autoCaptureFlag, + effectiveAutoCapture, *headlessFlag, *displayFlag, - *xvfbFlag, + effectiveXvfb, ) - if *autoCaptureFlag { + if effectiveAutoCapture { fmt.Println("Initializing private browser bridge (TLS & dynamic hCaptcha generator)...") if err := gateway.bridge.Start(); err != nil { fmt.Fprintf(os.Stderr, "warning: browser bridge init failed: %v (falling back to direct client)\n", err) @@ -3008,7 +3026,8 @@ func main() { fmt.Printf("th3ist gateway starting on port %s...\n", *portFlag) fmt.Printf("Default Model: %s\n", *defaultModelFlag) fmt.Printf("Upstream: %s\n", *targetURLFlag) - fmt.Printf("Auto-Capture / Bridge: %t\n", *autoCaptureFlag) + fmt.Printf("Auto-Capture / Bridge: %t\n", effectiveAutoCapture) + fmt.Printf("Virtual X Display (Xvfb): %t\n", effectiveXvfb) fmt.Printf("Endpoints:\n") fmt.Printf(" GET http://localhost:%s/v1/models\n", *portFlag) fmt.Printf(" POST http://localhost:%s/v1/chat/completions\n", *portFlag)