luxferre/th3ist
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

working defaults

Browse Source
This commit is contained in:
Luxferre
2026-08-26 08:24:40 +03:00
parent 5f23e9b61c
commit fa9f15b374
3 changed files with 58 additions and 43 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+18 -17
View File
@@ -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 `<think>...</think>` 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`)**:
architecture.md
+15 -20
View File
@@ -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 :<free_display> -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 :<free_display> -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 `<think>...</think>` tags and routing to `reasoning_content`.
4. `StreamToolCallFilter`: Stateful filter intercepting `<tool_call>...</tool_call>` 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_<fresh_hash>",
"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_<hash>` 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. |
---
th3ist.go
+25 -6
View File
@@ -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)