mirror of
https://github.com/garrytan/gstack.git
synced 2026-05-23 03:39:52 +02:00
v1.28.0.0 feat: browse --headed/--proxy/--navigate + gstack/llms.txt + webdriver-only stealth (#1363)
* feat(browse): SOCKS5 bridge with auth + cred redaction helper
Adds browse/src/socks-bridge.ts: a 127.0.0.1-only SOCKS5 listener that
accepts unauthenticated connections from Chromium and relays them through
an authenticated upstream proxy. Chromium does not prompt for SOCKS5 auth
at launch, so this bridge is the workaround for using auth-required
residential SOCKS5 upstreams.
- startSocksBridge({ upstream, port: 0 }) → ephemeral 127.0.0.1 listener
- testUpstream({ upstream, retries: 3, backoffMs: 500, budgetMs: 5000 })
pre-flight that connects to a known endpoint (default 1.1.1.1:443)
- Stream-error policy: kill affected client + upstream sockets on any
error mid-stream; no transport retries (a transport-layer retry can
corrupt browser traffic)
Adds browse/src/proxy-redact.ts: single source of truth for redacting
credentials in any logged proxy URL or upstream config. Every code path
that prints proxy config goes through this helper.
Adds the socks npm dep (~30KB) and 16 tests covering: 127.0.0.1-only
bind, byte-for-byte round trip through the bridge, auth rejection,
mid-stream upstream drop kills client conn, listener teardown,
testUpstream success + retry-exhaust paths, redaction of every
credential shape.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(browse): --proxy and --headed flags wire bridge into daemon
Adds the global --proxy <url> and --headed flags to the browse CLI.
Resolves cred policy and routes the daemon launch through the SOCKS5
bridge (or pass-through for HTTP/HTTPS) before chromium.launch().
CLI (cli.ts):
- extractGlobalFlags() strips --proxy/--headed from argv, parses URL via
Node URL class, validates D9 cred-mixing (env BROWSE_PROXY_USER/PASS
+ URL creds → exit 1 with hint), composes canonical proxy URL with
resolved creds, computes a stable configHash for daemon-mismatch
- ensureServer() now reads existing daemon's configHash from state file
and refuses (exit 1 with disconnect hint) if --proxy/--headed mismatch
the existing daemon. No silent restart that would drop tab state.
- All proxy-related stderr lines go through redactProxyUrl
proxy-config.ts (new):
- parseProxyConfig() — URL parser + D9 cred-mixing detector + scheme allowlist
- computeConfigHash() — stable hash of (proxy URL minus creds + headed flag)
- toUpstreamConfig() — map ParsedProxyConfig → socks-bridge.UpstreamConfig
Server (server.ts):
- Reads BROWSE_PROXY_URL at startup; for SOCKS5+auth, runs testUpstream
pre-flight (5s budget, 3 retries, 500ms backoff) and exits 1 on failure
with redacted error
- Spawns startSocksBridge() on 127.0.0.1:<ephemeral> and points
Chromium at it via socks5://127.0.0.1:<port>
- HTTP/HTTPS or unauth SOCKS5 → pass-through to chromium.launch
proxy.server (with username/password if present)
- State file gains optional configHash for daemon-mismatch check
- Bridge tears down via process.on('exit')
Browser manager (browser-manager.ts):
- New setProxyConfig({ server, username, password }) called by server.ts
before launch
- chromium.launch() and both launchPersistentContext sites pass the
proxy config through when set
Tests: 22 new across proxy-config (parse + cred-mixing + hash stability)
and extractGlobalFlags (flag stripping + cred-mixing rejection + cred
rotation hash stability + redaction).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(browse): Xvfb auto-spawn with PID + start-time validation
Adds browse/src/xvfb.ts: a Linux-only Xvfb auto-spawn module for
running headed Chromium in containers without DISPLAY. The module
walks a display range to pick a free one (never hardcodes :99) and
validates orphan PIDs by BOTH /proc/<pid>/cmdline matching 'Xvfb' AND
start-time matching the recorded value before sending any signal.
Defends against PID reuse — refuses to kill anything that doesn't
match both checks.
- shouldSpawnXvfb(env, platform) — pure decision: skip on macOS/Windows,
on Linux skip when DISPLAY or WAYLAND_DISPLAY is set (codex F2)
- pickFreeDisplay(99..120) — probes via xdpyinfo
- spawnXvfb(display) — returns { pid, startTime, display } handle
- isOurXvfb(pid, startTime) — both-checks validator
- cleanupXvfb(state) — best-effort, validates ownership before SIGTERM
Wired into server.ts startup: when shouldSpawnXvfb says yes, picks a
free display, spawns Xvfb, sets DISPLAY for chromium.launchHeaded, and
records xvfbPid/xvfbStartTime/xvfbDisplay in the state file. Cleanup
runs on process.on('exit'). The CLI's disconnect path also runs
cleanupXvfb() in the force-cleanup branch when the server is dead.
Disconnect now applies to any non-default daemon (headed mode OR
configHash-tagged daemon — i.e. one started with --proxy/--headed),
not just headed mode.
Adds xvfb + x11-utils to .github/docker/Dockerfile.ci so CI exercises
the Linux container --headed path on every run. Without it the most
common production path would go untested.
Tests: 17 new across decision logic, PID validation defenses
(cmdline mismatch, start-time mismatch), no-op safety on bad inputs,
and a Linux+Xvfb-installed gate for the spawn → validate → cleanup
round trip. Tests skip on macOS/Windows automatically.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(browse): webdriver-mask stealth + Chromium-through-bridge e2e
D7 (codex narrowing): mask navigator.webdriver only via addInitScript.
The wintermute approach (fake plugins=[1..5], fake languages=['en-US',
'en'], stub window.chrome) is intentionally NOT applied — modern
fingerprinters check consistency between plugins.length, languages,
userAgent, and platform, and synthesizing fixed values can flag MORE
bot-like, not less. The honest minimum is webdriver, which Chromium
exposes as a known automation tell.
Adds browse/src/stealth.ts: single source of truth for the stealth
init script and launch args. Both browser-manager.launch() (headless)
and launchHeaded() (persistent context with extension) call
applyStealth(context) and pass STEALTH_LAUNCH_ARGS into chromium.launch.
The pre-existing launchHeaded stealth that did fake plugins/languages
is removed for the same reason. The cdc_/__webdriver runtime cleanup
and Permissions API patch are kept — they remove automation-injected
artifacts, not synthesize fake natural-browser values.
Adds bridge-chromium-e2e.test.ts (codex F3): the test that proves the
FEATURE works. Real Chromium with proxy.server = 'socks5://127.0.0.1:
<bridgePort>' navigates to a local HTTP fixture; the auth upstream's
connect counter and the HTTP fixture's hit counter both increment,
proving traffic actually traversed bridge → auth-upstream → destination.
Without this test, we could ship a working byte-relay and a broken
Chromium integration and never know.
Adds bridge-port-restart.test.ts (codex F1, reframed): old test
assumed two daemons coexist, which contradicts D2 single-daemon model.
Reframed as restart-then-restart, asserting fresh ephemeral ports
(never the hardcoded 1090) on each spin-up.
Adds stealth-webdriver.test.ts: navigator.webdriver=false in both
fresh contexts and persistent contexts; navigator.plugins/languages
are NOT replaced with the wintermute fake list (D7 verification).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(gstack): generate llms.txt — single-file capability index for AI agents
Adds scripts/gen-llms-txt.ts: produces gstack/llms.txt at repo root,
indexing every skill (47), every browse command (75), and design
commands when the design CLI is present. Per the llmstxt.org
convention, agents can read one file to learn what gstack offers
instead of crawling 47 SKILL.md files.
Sources:
- skill SKILL.md.tmpl frontmatter (name + description block scalar)
- browse/src/commands.ts COMMAND_DESCRIPTIONS (sorted by category)
- design/src/commands.ts COMMAND_DESCRIPTIONS if present (best-effort)
Wired into scripts/gen-skill-docs.ts as a post-step so it regenerates
on every `bun run gen:skill-docs` (the same script that re-emits all
SKILL.md files). Failures are non-fatal warnings, not build breaks —
the generator never blocks SKILL.md regen.
Strict mode (--strict, also used by tests) throws when a skill is
missing name or description in its frontmatter, catching missing
metadata before it ships.
Tests: shape (top-level sections, sort order, single-line summary
discipline), every-skill-and-command-appears, strict-mode rejection of
incomplete frontmatter, and freshness check that the committed
gstack/llms.txt matches what the generator produces now.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(browse): --navigate flag on download for browser-triggered files
Adds the --navigate strategy from community PR #1355 (originally from
@garrytan-agents). When set, download navigates to the URL with
waitUntil:'commit' and captures the resulting browser download via
page.waitForEvent('download'), then saves via download.saveAs().
Handles URLs that trigger files via Content-Disposition headers,
multi-hop CDN redirects requiring browser cookies, or anti-bot CDN
chains where page.request.fetch() can't follow the auth/redirect
chain.
Defaults still use the existing direct-fetch strategy. --navigate is
opt-in.
Goes through the same validateNavigationUrl SSRF gate as goto, so
download --navigate cannot reach IPv4 metadata endpoints (AWS IMDSv1,
GCP/Azure equivalents) or arbitrary internal hosts.
Inferred content type from suggested filename for common extensions
(epub, pdf, zip, gz, mp3/mp4, jpg/jpeg/png, txt, html, json) — falls
back to application/octet-stream. Same 200MB cap as Strategy 1.
Frames the use case generically (anti-bot CDN, Content-Disposition,
redirect chains) rather than naming any specific site, per project
voice rules.
Co-Authored-By: @garrytan-agents
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs: v1.28.0.0 — browse SKILL section + VERSION + CHANGELOG
VERSION 1.27.1.0 → 1.28.0.0 (MINOR — substantial new capability:
five new flags/features, ~600 LOC added, new socks dep, multiple
new modules).
browse/SKILL.md.tmpl: new "Headed Mode + Proxy + Anti-Bot Sites"
section between User Handoff and Snapshot Flags. Documents
--headed (auto-Xvfb on Linux), --proxy (with embedded SOCKS5
bridge for auth), download --navigate, the cred-mixing policy,
daemon-discipline (refuse-on-mismatch), the narrowed
webdriver-only stealth, container support caveats, and the
fail-fast/no-retry failure modes.
CHANGELOG entry follows the release-summary format from CLAUDE.md:
two-line headline, lead paragraph, "The numbers that matter"
table tied to specific test files that prove each capability,
"What this means for AI agents" closing tied to a real workflow
shift, then itemized Added/Changed/Fixed/For-contributors
sections.
Browse SKILL.md regenerated via bun run gen:skill-docs.
gstack/llms.txt regenerated automatically from the same pipeline.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* test(browse): integration coverage for daemon mismatch + proxy fail-fast
Adds two integration tests that exercise the full process boundary,
not just the module-level wiring.
daemon-mismatch-refuse.test.ts (D2):
- Stubs a healthy state file with a fake configHash and a fake /health
HTTP server, runs the actual cli.ts binary with a mismatching
--proxy, asserts exit 1 + 'different config' / 'browse disconnect'
hint in stderr.
- Same shape with the plain-daemon-meets---headed case.
- Positive case: matching configHash → CLI does NOT emit the mismatch
hint (regardless of whether the actual command succeeds).
server-proxy-fail-fast.test.ts:
- Starts the rejecting SOCKS5 upstream, spawns server.ts with
BROWSE_PROXY_URL pointing at it, BROWSE_HEADLESS_SKIP=1 to skip
Chromium launch.
- Asserts exit 1, 'FAIL upstream' in stderr (testUpstream pre-flight
ran), no raw credential leakage in any output (redaction works on
the failure path), and exit within 30s upper bound.
Both tests use the existing spawn-bun-cli pattern from
commands.test.ts so they run on the same CI infrastructure as the
rest of the bun test suite.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix(gen-skill-docs): keep module sync so test require() still works
Two regressions caught by the full test suite after the v1.28.0.0
landing pass:
1) package.json version mismatch — VERSION was bumped to 1.28.0.0
but package.json still pinned to 1.27.1.0.
test/gen-skill-docs.test.ts asserts they match.
2) Top-level await in scripts/gen-llms-txt.ts (CLI entry block) and
scripts/gen-skill-docs.ts (post-step) made gen-skill-docs an
async module. test/gen-skill-docs.test.ts uses require() to pull
extractVoiceTriggers/processVoiceTriggers from gen-skill-docs,
which Bun rejects on async modules with:
"TypeError: require() async module ... unsupported.
use 'await import()' instead."
Fix: wrap the await blocks in void IIFEs so the modules remain sync
from a require() perspective.
After fix: all 379 gen-skill-docs tests pass, all 77 new feature
tests pass (3 skipped on macOS — Linux+Xvfb gates).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix(browse): apply codex adversarial findings on the new lifecycle
Codex outside-voice review caught five real production-failure modes in
the v1.28.0.0 proxy/headed lifecycle. Fixed:
1) `browse disconnect` skip-graceful for proxy-only daemons
(browse/src/cli.ts). The graceful /command POST went out with stray
`domains,` shorthand and (even fixed) the server's disconnect handler
only tears down headed mode — proxy-only daemons returned 200 "Not
in headed mode" while leaving the bridge running. Now disconnect
short-circuits to force-cleanup for non-headed daemons, which kicks
process.on('exit') in server.ts to close the bridge + Xvfb.
2) sendCommand crash retry preserves --proxy / --headed
(browse/src/cli.ts). The ECONNRESET retry path called startServer()
with no extraEnv, silently dropping the proxied flags. A daemon that
died mid-command would silently restart in default direct/headless
mode and bypass the SOCKS bridge. Now reapplies BROWSE_PROXY_URL,
BROWSE_HEADED, and BROWSE_CONFIG_HASH from the resolved global flags.
3) `connect` honors --proxy (browse/src/cli.ts). The headed-mode
`connect` command built its own serverEnv that didn't include
BROWSE_PROXY_URL, so `browse --proxy <url> connect` launched headed
Chromium without the proxy. Now threads proxyUrl + configHash into
the connect serverEnv.
4) SOCKS5 bridge handles fragmented TCP frames
(browse/src/socks-bridge.ts). Previously used once('data') and
parsed each chunk as a complete SOCKS5 frame — TCP doesn't preserve
message boundaries and split greetings/CONNECT requests caused
intermittent handshake failures. Replaced with a single state
machine that buffers chunks and uses size predicates on the SOCKS5
header to know when a complete frame has arrived. Pauses the client
socket during upstream connect and replays any remainder bytes
into the upstream on success.
5) Xvfb cleanup-then-state-delete ordering
(browse/src/server.ts). emergencyCleanup() previously deleted the
state file BEFORE any Xvfb cleanup could read it, orphaning Xvfb
on uncaughtException / unhandledRejection. Now reads the state
file first, calls cleanupXvfb() (which validates cmdline +
start-time before kill), then deletes the state file.
Adds a regression test for #4: writes the SOCKS5 greeting + CONNECT
one byte at a time with 5ms ticks, asserts a clean round trip after
the fragmented handshake.
Codex's sixth finding (bridge advertises NO_AUTH on 127.0.0.1, so any
co-located process can use the authenticated upstream) is documented
as a known limitation — gstack's threat model assumes single-user
hosts. Adding bridge-side auth is a separate change.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs: update BROWSER.md + TODOS.md for v1.28.0.0
BROWSER.md picks up a "Headed mode + proxy + browser-native downloads
(v1.28.0.0)" subsection inside Real-browser mode plus the new source-map
entries (socks-bridge.ts, proxy-config.ts, proxy-redact.ts, xvfb.ts,
stealth.ts). TODOS.md anti-bot-stealth item updated to reflect the v1.28
narrowing — the "fake plugins" line is no longer accurate.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
* fix(ci): include bun.lock in image build for deterministic install
CI evals all failed on PR #1363 with:
error: Could not resolve: "smart-buffer". Maybe you need to "bun install"?
error: Could not resolve: "ip-address". Maybe you need to "bun install"?
at /opt/node_modules_cache/socks/build/client/socksclient.js:15
The cached node_modules layer in the pre-baked Docker image had
`socks` (the new dep) but was missing its transitive deps (smart-buffer,
ip-address). The image build copied only package.json into the build
context — without bun.lock, `bun install` resolved a different tree
than local `bun install` did, dropping required transitive deps.
Reproduces locally as 229 packages (correct) when bun.lock is present
or absent. Why CI diverged isn't fully understood — possibly Docker
layer cache reuse across image rebuilds — but the deterministic fix is
to include the lockfile in the image build context and use
`--frozen-lockfile`, matching what every CI doc recommends.
Changes:
- .github/docker/Dockerfile.ci: COPY bun.lock alongside package.json,
switch `bun install` → `bun install --frozen-lockfile` so any future
lockfile drift fails loudly during image build instead of producing
a partially-installed cache that breaks downstream eval jobs.
- .github/workflows/evals.yml: include bun.lock in the image-tag hash
so adding/removing a dep invalidates the image, AND copy bun.lock
into the docker context alongside package.json.
- .github/workflows/evals-periodic.yml: same updates.
- .github/workflows/ci-image.yml: rebuild trigger now fires on bun.lock
changes too; build context includes bun.lock.
Image hash changes → fresh image gets built on next CI run → install
matches the lockfile exactly → no missing transitive deps.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix(ci): use hardlink copy instead of symlink for node_modules cache
After the bun.lock fix landed, the eval matrix STILL failed identically:
Could not resolve: "smart-buffer" / "ip-address"
at /opt/node_modules_cache/socks/build/client/socksclient.js
But the hash-tagged image actually contains smart-buffer + ip-address +
socks all flat in /opt/node_modules_cache (verified by pulling and
inspecting the image). 207 packages, all present.
Root cause: the workflow used `ln -s /opt/node_modules_cache node_modules`
to restore deps. Bun build (and Node module resolution generally) walks
a file's realpath to find sibling deps. From the symlinked
/workspace/node_modules/socks/build/client/socksclient.js, realpath
resolves to /opt/node_modules_cache/socks/build/client/socksclient.js,
and walking up to find a node_modules/smart-buffer dir fails — there's
no `node_modules` segment in the realpath.
Switch `ln -s` → `cp -al` (hardlink-copy). Each file in the cache becomes
a hardlink at /workspace/node_modules/<pkg>, sharing inodes (no data
copy). Realpath of /workspace/node_modules/socks/.../socksclient.js
stays inside /workspace/node_modules, so sibling deps resolve correctly.
Speed is comparable to symlink — `cp -al` on ~200 packages on tmpfs is
sub-second. Same caching story preserved.
Both evals.yml and evals-periodic.yml updated.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix(ci): cp -r instead of cp -al — /opt and /workspace are different filesystems
The hardlink-copy fix landed and immediately broke with:
cp: cannot create hard link 'node_modules/<file>' to
'/opt/node_modules_cache/<file>': Invalid cross-device link
GitHub Actions runners mount the workspace volume at /workspace
(overlay-fs layered onto the runner image), and /opt is the runner
image's own filesystem. Cross-filesystem hardlinks aren't supported.
Switch `cp -al` → `cp -r`. Cost: ~5s for ~200 packages of small JS
files vs ~0s for the broken symlink. Still cheaper than the ~15s
`bun install` fallback. Realpath of /workspace/node_modules/<pkg>/...
stays inside /workspace, so bun build's sibling-dep resolution works.
Both evals.yml and evals-periodic.yml updated.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Garry Tan
@@ -49,6 +49,11 @@ export interface BrowserState {
|
||||
export class BrowserManager {
|
||||
private browser: Browser | null = null;
|
||||
private context: BrowserContext | null = null;
|
||||
// Proxy config applied to chromium.launch() when set (D8). Set by server.ts
|
||||
// at startup based on BROWSE_PROXY_URL. For SOCKS5 with auth, server.ts
|
||||
// points this at the local bridge (socks5://127.0.0.1:<bridgePort>); for
|
||||
// HTTP/HTTPS or unauth SOCKS5, it's the upstream URL directly.
|
||||
private proxyConfig: { server: string; username?: string; password?: string } | null = null;
|
||||
private pages: Map<number, Page> = new Map();
|
||||
private tabSessions: Map<number, TabSession> = new Map();
|
||||
private activeTabId: number = 0;
|
||||
@@ -163,6 +168,15 @@ export class BrowserManager {
|
||||
return null;
|
||||
}
|
||||
|
||||
/**
|
||||
* Set the proxy config applied to chromium.launch() in launch() and
|
||||
* launchHeaded(). Called by server.ts at startup once the (optional) SOCKS5
|
||||
* bridge is up.
|
||||
*/
|
||||
setProxyConfig(cfg: { server: string; username?: string; password?: string } | null): void {
|
||||
this.proxyConfig = cfg;
|
||||
}
|
||||
|
||||
/**
|
||||
* Get the ref map for external consumers (e.g., /refs endpoint).
|
||||
*/
|
||||
@@ -179,7 +193,8 @@ export class BrowserManager {
|
||||
// BROWSE_EXTENSIONS_DIR points to an unpacked Chrome extension directory.
|
||||
// Extensions only work in headed mode, so we use an off-screen window.
|
||||
const extensionsDir = process.env.BROWSE_EXTENSIONS_DIR;
|
||||
const launchArgs: string[] = [];
|
||||
const { STEALTH_LAUNCH_ARGS } = await import('./stealth');
|
||||
const launchArgs: string[] = [...STEALTH_LAUNCH_ARGS];
|
||||
let useHeadless = true;
|
||||
|
||||
// Docker/CI: Chromium sandbox requires unprivileged user namespaces which
|
||||
@@ -207,6 +222,7 @@ export class BrowserManager {
|
||||
// browsing user-specified URLs has marginal sandbox benefit.
|
||||
chromiumSandbox: process.platform !== 'win32',
|
||||
...(launchArgs.length > 0 ? { args: launchArgs } : {}),
|
||||
...(this.proxyConfig ? { proxy: this.proxyConfig } : {}),
|
||||
});
|
||||
|
||||
// Chromium crash → exit with clear message
|
||||
@@ -229,6 +245,13 @@ export class BrowserManager {
|
||||
await this.context.setExtraHTTPHeaders(this.extraHeaders);
|
||||
}
|
||||
|
||||
// D7: mask navigator.webdriver only. The other 3 wintermute patches
|
||||
// (plugins, languages, chrome.runtime) are intentionally NOT applied —
|
||||
// faking them to fixed values can flag more bot-like to modern
|
||||
// fingerprinters, not less.
|
||||
const { applyStealth } = await import('./stealth');
|
||||
await applyStealth(this.context);
|
||||
|
||||
// Create first tab
|
||||
await this.newTab();
|
||||
}
|
||||
@@ -359,6 +382,7 @@ export class BrowserManager {
|
||||
viewport: null, // Use browser's default viewport (real window size)
|
||||
userAgent: this.customUserAgent || customUA,
|
||||
...(executablePath ? { executablePath } : {}),
|
||||
...(this.proxyConfig ? { proxy: this.proxyConfig } : {}),
|
||||
// Playwright adds flags that block extension loading
|
||||
ignoreDefaultArgs: [
|
||||
'--disable-extensions',
|
||||
@@ -369,33 +393,20 @@ export class BrowserManager {
|
||||
this.connectionMode = 'headed';
|
||||
this.intentionalDisconnect = false;
|
||||
|
||||
// ─── Anti-bot-detection stealth patches ───────────────────────
|
||||
// Playwright's Chromium is detected by sites like Google/NYTimes via:
|
||||
// 1. navigator.webdriver = true (handled by --disable-blink-features above)
|
||||
// 2. Missing plugins array (real Chrome has PDF viewer, etc.)
|
||||
// 3. Missing languages
|
||||
// 4. CDP runtime detection (window.cdc_* variables)
|
||||
// 5. Permissions API returning 'denied' for notifications
|
||||
// ─── Anti-bot-detection patches ───────────────────────────────
|
||||
// D7 (codex correction): mask navigator.webdriver only. We do NOT fake
|
||||
// plugins/languages — modern fingerprinters check consistency between
|
||||
// those and userAgent/platform, and synthesizing fixed values can flag
|
||||
// MORE bot-like, not less. Let Chromium's natural plugins and languages
|
||||
// surface unmodified.
|
||||
//
|
||||
// What we DO clean up are automation-specific runtime artifacts that
|
||||
// shouldn't exist in a real browser at all (Permissions API quirks,
|
||||
// ChromeDriver-injected window globals). Those aren't fingerprint
|
||||
// synthesis — they're removing leaked automation tells.
|
||||
const { applyStealth } = await import('./stealth');
|
||||
await applyStealth(this.context);
|
||||
await this.context.addInitScript(() => {
|
||||
// Fake plugins array (real Chrome has at least PDF Viewer)
|
||||
Object.defineProperty(navigator, 'plugins', {
|
||||
get: () => {
|
||||
const plugins = [
|
||||
{ name: 'PDF Viewer', filename: 'internal-pdf-viewer', description: 'Portable Document Format' },
|
||||
{ name: 'Chrome PDF Viewer', filename: 'internal-pdf-viewer', description: '' },
|
||||
{ name: 'Chromium PDF Viewer', filename: 'internal-pdf-viewer', description: '' },
|
||||
];
|
||||
(plugins as any).namedItem = (name: string) => plugins.find(p => p.name === name) || null;
|
||||
(plugins as any).refresh = () => {};
|
||||
return plugins;
|
||||
},
|
||||
});
|
||||
|
||||
// Fake languages (Playwright sometimes sends empty)
|
||||
Object.defineProperty(navigator, 'languages', {
|
||||
get: () => ['en-US', 'en'],
|
||||
});
|
||||
|
||||
// Remove CDP runtime artifacts that automation detectors look for
|
||||
// cdc_ prefixed vars are injected by ChromeDriver/CDP
|
||||
const cleanup = () => {
|
||||
@@ -1257,6 +1268,7 @@ export class BrowserManager {
|
||||
headless: false,
|
||||
args: launchArgs,
|
||||
viewport: null,
|
||||
...(this.proxyConfig ? { proxy: this.proxyConfig } : {}),
|
||||
ignoreDefaultArgs: [
|
||||
'--disable-extensions',
|
||||
'--disable-component-extensions-with-background-pages',
|
||||
|
||||
+198
-27
@@ -13,6 +13,8 @@ import * as fs from 'fs';
|
||||
import * as path from 'path';
|
||||
import { safeUnlink, safeUnlinkQuiet, safeKill, isProcessAlive } from './error-handling';
|
||||
import { resolveConfig, ensureStateDir, readVersionHash } from './config';
|
||||
import { parseProxyConfig, computeConfigHash, ProxyConfigError } from './proxy-config';
|
||||
import { redactProxyUrl } from './proxy-redact';
|
||||
|
||||
const config = resolveConfig();
|
||||
const IS_WINDOWS = process.platform === 'win32';
|
||||
@@ -92,6 +94,12 @@ interface ServerState {
|
||||
serverPath: string;
|
||||
binaryVersion?: string;
|
||||
mode?: 'launched' | 'headed';
|
||||
/** Hash of (proxyUrl + headed flag), used by D2 daemon-mismatch check. */
|
||||
configHash?: string;
|
||||
/** Xvfb child PID for cleanup on disconnect. */
|
||||
xvfbPid?: number;
|
||||
xvfbStartTime?: number;
|
||||
xvfbDisplay?: string;
|
||||
}
|
||||
|
||||
// ─── State File ────────────────────────────────────────────────
|
||||
@@ -305,19 +313,43 @@ function acquireServerLock(): (() => void) | null {
|
||||
}
|
||||
}
|
||||
|
||||
async function ensureServer(): Promise<ServerState> {
|
||||
async function ensureServer(flags?: GlobalFlags): Promise<ServerState> {
|
||||
const state = readState();
|
||||
const desiredHash = flags?.configHash;
|
||||
const extraEnv: Record<string, string> = {};
|
||||
if (flags?.proxyUrl) extraEnv.BROWSE_PROXY_URL = flags.proxyUrl;
|
||||
if (flags?.headed) extraEnv.BROWSE_HEADED = '1';
|
||||
if (desiredHash) extraEnv.BROWSE_CONFIG_HASH = desiredHash;
|
||||
|
||||
// Health-check-first: HTTP is definitive proof the server is alive and responsive.
|
||||
// This replaces the PID-gated approach which breaks on Windows (Bun's process.kill
|
||||
// always throws ESRCH for Windows PIDs in compiled binaries).
|
||||
if (state && await isServerHealthy(state.port)) {
|
||||
// D2 daemon-mismatch check: existing daemon's configHash must match the
|
||||
// CLI's resolved hash. If --proxy or --headed are passed and the existing
|
||||
// daemon was started with different config, refuse with a `disconnect`
|
||||
// hint. No silent restart — that would drop tab state, cookies, and
|
||||
// logged-in sessions without warning.
|
||||
if (desiredHash && state.configHash && state.configHash !== desiredHash) {
|
||||
console.error(`[browse] existing daemon has different config (proxy/headed mismatch).`);
|
||||
console.error(`[browse] run 'browse disconnect' first to apply --proxy/--headed.`);
|
||||
process.exit(1);
|
||||
}
|
||||
// Same path: existing daemon is plain (no flags) but caller passes
|
||||
// --proxy/--headed. Refuse for the same reason — apply explicitly via
|
||||
// disconnect+reconnect.
|
||||
if (desiredHash && !state.configHash && (flags?.proxyUrl || flags?.headed)) {
|
||||
console.error(`[browse] existing daemon was started without --proxy/--headed.`);
|
||||
console.error(`[browse] run 'browse disconnect' first to apply new flags.`);
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
// Check for binary version mismatch (auto-restart on update)
|
||||
const currentVersion = readVersionHash();
|
||||
if (currentVersion && state.binaryVersion && currentVersion !== state.binaryVersion) {
|
||||
console.error('[browse] Binary updated, restarting server...');
|
||||
await killServer(state.pid);
|
||||
return startServer();
|
||||
return startServer(extraEnv);
|
||||
}
|
||||
return state;
|
||||
}
|
||||
@@ -368,8 +400,14 @@ async function ensureServer(): Promise<ServerState> {
|
||||
if (state && state.pid) {
|
||||
await killServer(state.pid);
|
||||
}
|
||||
console.error('[browse] Starting server...');
|
||||
return await startServer();
|
||||
if (flags?.redactedProxyUrl && flags.redactedProxyUrl !== '<no proxy>') {
|
||||
console.error(`[browse] Starting server with proxy ${flags.redactedProxyUrl}${flags.headed ? ' (headed)' : ''}...`);
|
||||
} else if (flags?.headed) {
|
||||
console.error('[browse] Starting server in headed mode...');
|
||||
} else {
|
||||
console.error('[browse] Starting server...');
|
||||
}
|
||||
return await startServer(extraEnv);
|
||||
} finally {
|
||||
releaseLock();
|
||||
}
|
||||
@@ -459,13 +497,26 @@ async function sendCommand(state: ServerState, command: string, args: string[],
|
||||
if (oldState && oldState.pid) {
|
||||
await killServer(oldState.pid);
|
||||
}
|
||||
const newState = await startServer();
|
||||
// Reapply --proxy / --headed flags from this invocation when restarting
|
||||
// after a crash. Without this, a proxied daemon that dies mid-command
|
||||
// would silently restart in default direct/headless mode and bypass
|
||||
// the SOCKS bridge.
|
||||
const restartEnv: Record<string, string> = {};
|
||||
if (_globalFlags?.proxyUrl) restartEnv.BROWSE_PROXY_URL = _globalFlags.proxyUrl;
|
||||
if (_globalFlags?.headed) restartEnv.BROWSE_HEADED = '1';
|
||||
if (_globalFlags?.configHash) restartEnv.BROWSE_CONFIG_HASH = _globalFlags.configHash;
|
||||
const newState = await startServer(Object.keys(restartEnv).length ? restartEnv : undefined);
|
||||
return sendCommand(newState, command, args, retries + 1);
|
||||
}
|
||||
throw err;
|
||||
}
|
||||
}
|
||||
|
||||
// Module-level reference to the resolved global flags from main(). Used by
|
||||
// sendCommand's crash-retry path so a daemon restart after ECONNRESET doesn't
|
||||
// silently drop --proxy / --headed.
|
||||
let _globalFlags: GlobalFlags | null = null;
|
||||
|
||||
// ─── Ngrok Detection ───────────────────────────────────────────
|
||||
|
||||
/** Check if ngrok is installed and authenticated (native config or gstack env). */
|
||||
@@ -608,6 +659,78 @@ function hasFlag(args: string[], flag: string): boolean {
|
||||
return args.includes(flag);
|
||||
}
|
||||
|
||||
export interface GlobalFlags {
|
||||
/** Cleaned argv with --proxy/--headed stripped out. */
|
||||
args: string[];
|
||||
/** Resolved BROWSE_PROXY_URL (with creds embedded) or null. */
|
||||
proxyUrl: string | null;
|
||||
/** Whether --headed was passed. */
|
||||
headed: boolean;
|
||||
/** Hash of (proxy + headed) for daemon-mismatch check. */
|
||||
configHash: string;
|
||||
/** Redacted form of proxyUrl, safe for logs. */
|
||||
redactedProxyUrl: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* Strip the global --proxy and --headed flags from args, validate cred policy,
|
||||
* and return the resolved config. Exits 1 with a clear hint on policy
|
||||
* violations (D9 cred mixing, malformed URL, unsupported scheme).
|
||||
*
|
||||
* Exported for unit tests.
|
||||
*/
|
||||
export function extractGlobalFlags(rawArgs: string[], env: NodeJS.ProcessEnv): GlobalFlags {
|
||||
const out: string[] = [];
|
||||
let proxyUrl: string | null = null;
|
||||
let headed = false;
|
||||
|
||||
for (let i = 0; i < rawArgs.length; i++) {
|
||||
const arg = rawArgs[i];
|
||||
if (arg === '--proxy') {
|
||||
const value = rawArgs[i + 1];
|
||||
if (!value) {
|
||||
throw new ProxyConfigError(
|
||||
'usage: --proxy <scheme://[user:pass@]host:port>',
|
||||
'--proxy requires a URL value',
|
||||
);
|
||||
}
|
||||
proxyUrl = value;
|
||||
i++;
|
||||
continue;
|
||||
}
|
||||
if (arg.startsWith('--proxy=')) {
|
||||
proxyUrl = arg.slice('--proxy='.length);
|
||||
continue;
|
||||
}
|
||||
if (arg === '--headed') { headed = true; continue; }
|
||||
out.push(arg);
|
||||
}
|
||||
|
||||
// Compose the canonical proxyUrl with creds resolved from argv+env.
|
||||
let canonicalProxyUrl: string | null = null;
|
||||
if (proxyUrl) {
|
||||
const parsed = parseProxyConfig({
|
||||
proxyUrl,
|
||||
envUser: env.BROWSE_PROXY_USER,
|
||||
envPass: env.BROWSE_PROXY_PASS,
|
||||
});
|
||||
// Re-encode with resolved creds embedded (server reads BROWSE_PROXY_URL
|
||||
// from env — env passes to child process safely without ps-aux exposure).
|
||||
const rebuilt = new URL(proxyUrl);
|
||||
rebuilt.username = parsed.userId ? encodeURIComponent(parsed.userId) : '';
|
||||
rebuilt.password = parsed.password ? encodeURIComponent(parsed.password) : '';
|
||||
canonicalProxyUrl = rebuilt.toString();
|
||||
}
|
||||
|
||||
return {
|
||||
args: out,
|
||||
proxyUrl: canonicalProxyUrl,
|
||||
headed,
|
||||
configHash: computeConfigHash({ proxyUrl: canonicalProxyUrl, headed }),
|
||||
redactedProxyUrl: redactProxyUrl(canonicalProxyUrl),
|
||||
};
|
||||
}
|
||||
|
||||
async function handlePairAgent(state: ServerState, args: string[]): Promise<void> {
|
||||
const clientName = parseFlag(args, '--client') || `remote-${Date.now()}`;
|
||||
const domains = parseFlag(args, '--domain')?.split(',').map(d => d.trim());
|
||||
@@ -751,7 +874,24 @@ async function handlePairAgent(state: ServerState, args: string[]): Promise<void
|
||||
|
||||
// ─── Main ──────────────────────────────────────────────────────
|
||||
async function main() {
|
||||
const args = process.argv.slice(2);
|
||||
const rawArgs = process.argv.slice(2);
|
||||
|
||||
// ─── Global flags (--proxy, --headed) ───────────────────────
|
||||
// Extract before command dispatch so they apply to any command. Throws
|
||||
// ProxyConfigError on invalid URL or D9 cred-mixing violations.
|
||||
let globalFlags: GlobalFlags;
|
||||
try {
|
||||
globalFlags = extractGlobalFlags(rawArgs, process.env);
|
||||
} catch (err) {
|
||||
if (err instanceof ProxyConfigError) {
|
||||
console.error(`[browse] error: ${err.message}`);
|
||||
console.error(`[browse] hint: ${err.hint}`);
|
||||
process.exit(1);
|
||||
}
|
||||
throw err;
|
||||
}
|
||||
_globalFlags = globalFlags;
|
||||
const args = globalFlags.args;
|
||||
|
||||
if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
|
||||
console.log(`gstack browse — Fast headless browser for AI coding agents
|
||||
@@ -866,6 +1006,11 @@ Refs: After 'snapshot', use @e1, @e2... as selectors:
|
||||
// it would kill the server ~15s later. Cleanup happens via browser
|
||||
// disconnect event or $B disconnect.
|
||||
BROWSE_PARENT_PID: '0',
|
||||
// Apply --proxy from this invocation if present. Without this,
|
||||
// `browse --proxy <url> connect` would launch headed Chromium
|
||||
// bypassing the SOCKS bridge entirely.
|
||||
...(globalFlags.proxyUrl ? { BROWSE_PROXY_URL: globalFlags.proxyUrl } : {}),
|
||||
...(globalFlags.configHash ? { BROWSE_CONFIG_HASH: globalFlags.configHash } : {}),
|
||||
};
|
||||
const newState = await startServer(serverEnv);
|
||||
|
||||
@@ -930,29 +1075,39 @@ Refs: After 'snapshot', use @e1, @e2... as selectors:
|
||||
// guard blocks all commands when the server is unresponsive.
|
||||
if (command === 'disconnect') {
|
||||
const existingState = readState();
|
||||
if (!existingState || existingState.mode !== 'headed') {
|
||||
console.log('Not in headed mode — nothing to disconnect.');
|
||||
// disconnect applies when there's a non-default daemon — headed mode OR
|
||||
// any custom config (--proxy/--headed) recorded as configHash. Plain
|
||||
// headless daemons should use 'stop' instead.
|
||||
const hasCustomConfig = existingState && (existingState.mode === 'headed' || existingState.configHash);
|
||||
if (!existingState || !hasCustomConfig) {
|
||||
console.log('Not in headed/custom-config mode — nothing to disconnect.');
|
||||
process.exit(0);
|
||||
}
|
||||
// Try graceful shutdown via server
|
||||
try {
|
||||
const resp = await fetch(`http://127.0.0.1:${existingState.port}/command`, {
|
||||
method: 'POST',
|
||||
headers: {
|
||||
'Content-Type': 'application/json',
|
||||
'Authorization': `Bearer ${existingState.token}`,
|
||||
},
|
||||
body: JSON.stringify({
|
||||
domains,
|
||||
command: 'disconnect', args: [] }),
|
||||
signal: AbortSignal.timeout(3000),
|
||||
});
|
||||
if (resp.ok) {
|
||||
console.log('Disconnected from real browser.');
|
||||
process.exit(0);
|
||||
// For headed-mode daemons: try graceful shutdown via the server's
|
||||
// /command endpoint. For proxy-only / custom-config daemons (no headed
|
||||
// mode), the server's `disconnect` handler currently only tears down
|
||||
// headed state — it returns 200 "Not in headed mode" without cleaning
|
||||
// up the bridge or Xvfb. So we skip the graceful path for those and
|
||||
// jump straight to force-cleanup, which kills the daemon process and
|
||||
// lets process.on('exit') in server.ts close the bridge + Xvfb.
|
||||
if (existingState.mode === 'headed') {
|
||||
try {
|
||||
const resp = await fetch(`http://127.0.0.1:${existingState.port}/command`, {
|
||||
method: 'POST',
|
||||
headers: {
|
||||
'Content-Type': 'application/json',
|
||||
'Authorization': `Bearer ${existingState.token}`,
|
||||
},
|
||||
body: JSON.stringify({ command: 'disconnect', args: [] }),
|
||||
signal: AbortSignal.timeout(3000),
|
||||
});
|
||||
if (resp.ok) {
|
||||
console.log('Disconnected from real browser.');
|
||||
process.exit(0);
|
||||
}
|
||||
} catch {
|
||||
// Server not responding — fall through to force cleanup
|
||||
}
|
||||
} catch {
|
||||
// Server not responding — force cleanup
|
||||
}
|
||||
// Force kill + cleanup
|
||||
if (isProcessAlive(existingState.pid)) {
|
||||
@@ -967,6 +1122,22 @@ Refs: After 'snapshot', use @e1, @e2... as selectors:
|
||||
for (const lockFile of ['SingletonLock', 'SingletonSocket', 'SingletonCookie']) {
|
||||
safeUnlinkQuiet(path.join(profileDir, lockFile));
|
||||
}
|
||||
// Xvfb orphan cleanup: if the recorded PID still matches our Xvfb (by
|
||||
// cmdline AND start-time), kill it. PID-only would risk killing a
|
||||
// recycled PID belonging to an unrelated process.
|
||||
if (existingState.xvfbPid && existingState.xvfbStartTime) {
|
||||
try {
|
||||
const { cleanupXvfb } = await import('./xvfb');
|
||||
cleanupXvfb({
|
||||
pid: existingState.xvfbPid,
|
||||
startTime: existingState.xvfbStartTime,
|
||||
display: existingState.xvfbDisplay || ':99',
|
||||
});
|
||||
} catch {
|
||||
// Best effort — Linux-only module on a non-Linux disconnect may
|
||||
// not load; cleanup is best-effort anyway.
|
||||
}
|
||||
}
|
||||
safeUnlinkQuiet(config.stateFile);
|
||||
console.log('Disconnected (server was unresponsive — force cleaned).');
|
||||
process.exit(0);
|
||||
@@ -978,7 +1149,7 @@ Refs: After 'snapshot', use @e1, @e2... as selectors:
|
||||
commandArgs.push(stdin.trim());
|
||||
}
|
||||
|
||||
let state = await ensureServer();
|
||||
let state = await ensureServer(globalFlags);
|
||||
|
||||
// ─── Pair-Agent (post-server, pre-dispatch) ──────────────
|
||||
if (command === 'pair-agent') {
|
||||
|
||||
@@ -134,7 +134,7 @@ export const COMMAND_DESCRIPTIONS: Record<string, { category: string; descriptio
|
||||
'dialog-accept': { category: 'Interaction', description: 'Auto-accept next alert/confirm/prompt. Optional text is sent as the prompt response', usage: 'dialog-accept [text]' },
|
||||
'dialog-dismiss': { category: 'Interaction', description: 'Auto-dismiss next dialog' },
|
||||
// Data extraction
|
||||
'download': { category: 'Extraction', description: 'Download URL or media element to disk using browser cookies', usage: 'download <url|@ref> [path] [--base64]' },
|
||||
'download': { category: 'Extraction', description: 'Download URL or media element to disk using browser cookies. Use --navigate for URLs that trigger browser downloads (CDN redirects, Content-Disposition, anti-bot protected sites)', usage: 'download <url|@ref> [path] [--base64] [--navigate]' },
|
||||
'scrape': { category: 'Extraction', description: 'Bulk download all media from page. Writes manifest.json', usage: 'scrape <images|videos|media> [--selector sel] [--dir path] [--limit N]' },
|
||||
'archive': { category: 'Extraction', description: 'Save complete page as MHTML via CDP', usage: 'archive [path]' },
|
||||
// Visual
|
||||
|
||||
@@ -0,0 +1,155 @@
|
||||
/**
|
||||
* Parse + validate proxy config from CLI flags and environment.
|
||||
*
|
||||
* Used by:
|
||||
* cli.ts — to detect cred-mixing, daemon-mismatch, and forward to server
|
||||
* server.ts — to spawn the bridge and pass proxy to chromium.launch
|
||||
*
|
||||
* Cred policy (D9): if BOTH the URL embeds creds AND the env vars
|
||||
* BROWSE_PROXY_USER/PASS are set, refuse with a clear error. No silent
|
||||
* override — debugging confusion is worse than a one-time setup error.
|
||||
*/
|
||||
|
||||
import { createHash } from 'crypto';
|
||||
import type { UpstreamConfig } from './socks-bridge';
|
||||
|
||||
export interface ParsedProxyConfig {
|
||||
/** Original scheme: 'socks5' | 'http' | 'https' */
|
||||
scheme: 'socks5' | 'http' | 'https';
|
||||
host: string;
|
||||
port: number;
|
||||
userId?: string;
|
||||
password?: string;
|
||||
/** True if creds are present (from URL or env). */
|
||||
hasAuth: boolean;
|
||||
}
|
||||
|
||||
export class ProxyConfigError extends Error {
|
||||
constructor(public readonly hint: string, message: string) {
|
||||
super(message);
|
||||
this.name = 'ProxyConfigError';
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Parse the BROWSE_PROXY_URL string and merge env-supplied creds.
|
||||
*
|
||||
* @throws ProxyConfigError on malformed URL, unsupported scheme, or
|
||||
* ambiguous credentials (set in both URL and env).
|
||||
*/
|
||||
export function parseProxyConfig(opts: {
|
||||
proxyUrl: string;
|
||||
envUser?: string;
|
||||
envPass?: string;
|
||||
}): ParsedProxyConfig {
|
||||
let url: URL;
|
||||
try {
|
||||
url = new URL(opts.proxyUrl);
|
||||
} catch {
|
||||
throw new ProxyConfigError(
|
||||
'expected scheme://[user:pass@]host:port',
|
||||
`invalid proxy URL — could not parse`,
|
||||
);
|
||||
}
|
||||
|
||||
const scheme = url.protocol.replace(':', '');
|
||||
if (scheme !== 'socks5' && scheme !== 'http' && scheme !== 'https') {
|
||||
throw new ProxyConfigError(
|
||||
'use socks5://, http://, or https://',
|
||||
`unsupported proxy scheme '${scheme}'`,
|
||||
);
|
||||
}
|
||||
|
||||
if (!url.hostname) {
|
||||
throw new ProxyConfigError(
|
||||
'expected scheme://[user:pass@]host:port',
|
||||
`invalid proxy URL — missing host`,
|
||||
);
|
||||
}
|
||||
|
||||
const port = url.port
|
||||
? parseInt(url.port, 10)
|
||||
: (scheme === 'http' ? 80 : scheme === 'https' ? 443 : 1080);
|
||||
if (!Number.isInteger(port) || port <= 0 || port > 65535) {
|
||||
throw new ProxyConfigError(
|
||||
'expected scheme://[user:pass@]host:port',
|
||||
`invalid proxy URL — bad port`,
|
||||
);
|
||||
}
|
||||
|
||||
const urlHasUser = !!url.username;
|
||||
const urlHasPass = !!url.password;
|
||||
const envHasUser = !!opts.envUser;
|
||||
const envHasPass = !!opts.envPass;
|
||||
const urlHasCreds = urlHasUser || urlHasPass;
|
||||
const envHasCreds = envHasUser || envHasPass;
|
||||
|
||||
// D9 (codex correction): refuse on mixed sources. Silent override is a
|
||||
// debugging trap — when a stale BROWSE_PROXY_USER from a prior session
|
||||
// wins over a fresh --proxy URL, the user can't tell why.
|
||||
if (urlHasCreds && envHasCreds) {
|
||||
throw new ProxyConfigError(
|
||||
'unset BROWSE_PROXY_USER/PASS or remove user:pass@ from --proxy',
|
||||
`proxy creds set in both env (BROWSE_PROXY_USER) and URL — pick one source`,
|
||||
);
|
||||
}
|
||||
|
||||
let userId: string | undefined;
|
||||
let password: string | undefined;
|
||||
if (urlHasCreds) {
|
||||
userId = decodeURIComponent(url.username);
|
||||
password = url.password ? decodeURIComponent(url.password) : undefined;
|
||||
} else if (envHasCreds) {
|
||||
userId = opts.envUser;
|
||||
password = opts.envPass;
|
||||
}
|
||||
|
||||
return {
|
||||
scheme: scheme as 'socks5' | 'http' | 'https',
|
||||
host: url.hostname,
|
||||
port,
|
||||
...(userId ? { userId } : {}),
|
||||
...(password ? { password } : {}),
|
||||
hasAuth: !!(userId || password),
|
||||
};
|
||||
}
|
||||
|
||||
/** Convert a ParsedProxyConfig to the UpstreamConfig shape socks-bridge wants. */
|
||||
export function toUpstreamConfig(cfg: ParsedProxyConfig): UpstreamConfig {
|
||||
return {
|
||||
host: cfg.host,
|
||||
port: cfg.port,
|
||||
...(cfg.userId ? { userId: cfg.userId } : {}),
|
||||
...(cfg.password ? { password: cfg.password } : {}),
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Compute a stable hash of (proxyUrl + headed flag) for daemon-mismatch
|
||||
* detection (D2). The hash is deterministic across CLI invocations on the
|
||||
* same machine and survives daemon restarts via the state file.
|
||||
*
|
||||
* NEVER include resolved creds — the hash compares config intent, not
|
||||
* specific credential values, and we don't want creds in any persisted form.
|
||||
*/
|
||||
export function computeConfigHash(opts: {
|
||||
proxyUrl: string | null | undefined;
|
||||
headed: boolean;
|
||||
}): string {
|
||||
const proxyKey = canonicalizeProxyUrl(opts.proxyUrl);
|
||||
const input = JSON.stringify({ proxy: proxyKey, headed: opts.headed });
|
||||
return createHash('sha256').update(input).digest('hex').slice(0, 16);
|
||||
}
|
||||
|
||||
/** Strip creds from a proxy URL for hashing. Returns null for empty input. */
|
||||
function canonicalizeProxyUrl(input: string | null | undefined): string | null {
|
||||
if (!input) return null;
|
||||
try {
|
||||
const u = new URL(input);
|
||||
u.username = '';
|
||||
u.password = '';
|
||||
return `${u.protocol}//${u.host}`;
|
||||
} catch {
|
||||
return '<unparseable>';
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,46 @@
|
||||
/**
|
||||
* Single source of truth for redacting proxy credentials in log lines.
|
||||
*
|
||||
* Anywhere browse logs a proxy URL (startup banner, error messages, debug
|
||||
* output), it MUST go through redactProxyUrl first. Tests assert this for
|
||||
* every log path that prints proxy config.
|
||||
*/
|
||||
|
||||
const REDACTED = '***';
|
||||
|
||||
/**
|
||||
* Redact creds in a proxy URL string. Returns the URL with username and
|
||||
* password replaced by '***'. If the input isn't parseable as a URL, returns
|
||||
* a generic placeholder rather than echoing it back (input may be malformed
|
||||
* AND contain creds).
|
||||
*/
|
||||
export function redactProxyUrl(input: string | null | undefined): string {
|
||||
if (!input) return '<no proxy>';
|
||||
let url: URL;
|
||||
try {
|
||||
url = new URL(input);
|
||||
} catch {
|
||||
return '<malformed proxy url>';
|
||||
}
|
||||
if (url.username) url.username = REDACTED;
|
||||
if (url.password) url.password = REDACTED;
|
||||
return url.toString();
|
||||
}
|
||||
|
||||
/**
|
||||
* Redact creds in an upstream config object (host/port/userId/password).
|
||||
* Returns a plain object suitable for logging.
|
||||
*/
|
||||
export function redactUpstream(upstream: {
|
||||
host: string;
|
||||
port: number;
|
||||
userId?: string;
|
||||
password?: string;
|
||||
}): { host: string; port: number; userId?: string; password?: string } {
|
||||
return {
|
||||
host: upstream.host,
|
||||
port: upstream.port,
|
||||
...(upstream.userId ? { userId: REDACTED } : {}),
|
||||
...(upstream.password ? { password: REDACTED } : {}),
|
||||
};
|
||||
}
|
||||
@@ -41,6 +41,10 @@ import { inspectElement, modifyStyle, resetModifications, getModificationHistory
|
||||
// Bun.spawn used instead of child_process.spawn (compiled bun binaries
|
||||
// fail posix_spawn on all executables including /bin/bash)
|
||||
import { safeUnlink, safeUnlinkQuiet, safeKill } from './error-handling';
|
||||
import { startSocksBridge, testUpstream, type BridgeHandle } from './socks-bridge';
|
||||
import { parseProxyConfig, toUpstreamConfig, ProxyConfigError } from './proxy-config';
|
||||
import { redactProxyUrl } from './proxy-redact';
|
||||
import { shouldSpawnXvfb, pickFreeDisplay, spawnXvfb, xvfbInstallHint, type XvfbHandle } from './xvfb';
|
||||
import { logTunnelDenial } from './tunnel-denial-log';
|
||||
import {
|
||||
mintSseSessionToken, validateSseSessionToken, extractSseCookie,
|
||||
@@ -992,6 +996,31 @@ if (process.platform === 'win32') {
|
||||
function emergencyCleanup() {
|
||||
if (isShuttingDown) return;
|
||||
isShuttingDown = true;
|
||||
// Xvfb cleanup MUST happen before state-file deletion. spawnXvfb detaches
|
||||
// the child, so without this, an uncaught exception leaves the Xvfb
|
||||
// running with no PID record — orphan accumulates and eventually
|
||||
// exhausts the :99-:120 display range. Read the state file FIRST,
|
||||
// call cleanupXvfb (validates cmdline + start-time before kill), THEN
|
||||
// delete the state file.
|
||||
try {
|
||||
if (fs.existsSync(config.stateFile)) {
|
||||
const raw = fs.readFileSync(config.stateFile, 'utf-8');
|
||||
const state = JSON.parse(raw);
|
||||
if (state.xvfbPid && state.xvfbStartTime) {
|
||||
// Lazy import — emergencyCleanup may run on platforms where
|
||||
// ./xvfb's Linux-specific helpers fail to load. Best effort.
|
||||
try {
|
||||
const { cleanupXvfb } = require('./xvfb');
|
||||
cleanupXvfb({
|
||||
pid: state.xvfbPid,
|
||||
startTime: state.xvfbStartTime,
|
||||
display: state.xvfbDisplay || ':99',
|
||||
});
|
||||
} catch { /* best effort */ }
|
||||
}
|
||||
}
|
||||
} catch { /* state file unparseable — fall through to lock + state cleanup */ }
|
||||
|
||||
// Clean Chromium profile locks
|
||||
const profileDir = path.join(process.env.HOME || '/tmp', '.gstack', 'chromium-profile');
|
||||
for (const lockFile of ['SingletonLock', 'SingletonSocket', 'SingletonCookie']) {
|
||||
@@ -1020,6 +1049,97 @@ async function start() {
|
||||
const port = await findPort();
|
||||
LOCAL_LISTEN_PORT = port;
|
||||
|
||||
// ─── Proxy config (D8 + codex F5) ──────────────────────────────
|
||||
// BROWSE_PROXY_URL is set by the CLI when --proxy was passed. For SOCKS5
|
||||
// with auth, we run a local 127.0.0.1 bridge that relays to the
|
||||
// authenticated upstream (Chromium can't do SOCKS5 auth itself). For
|
||||
// HTTP/HTTPS or unauthenticated SOCKS5, we pass the URL directly to
|
||||
// Chromium's proxy.server option.
|
||||
let proxyBridge: BridgeHandle | null = null;
|
||||
const proxyUrl = process.env.BROWSE_PROXY_URL;
|
||||
if (proxyUrl) {
|
||||
let parsed;
|
||||
try {
|
||||
parsed = parseProxyConfig({
|
||||
proxyUrl,
|
||||
envUser: process.env.BROWSE_PROXY_USER,
|
||||
envPass: process.env.BROWSE_PROXY_PASS,
|
||||
});
|
||||
} catch (err) {
|
||||
if (err instanceof ProxyConfigError) {
|
||||
console.error(`[browse] error: ${err.message} (${err.hint})`);
|
||||
process.exit(1);
|
||||
}
|
||||
throw err;
|
||||
}
|
||||
|
||||
if (parsed.scheme === 'socks5' && parsed.hasAuth) {
|
||||
// Pre-flight: verify upstream accepts our creds before launching
|
||||
// Chromium. 5s budget, 3 retries with 500ms backoff (D4: handles VPN
|
||||
// warm-up race). On failure, exit with redacted error.
|
||||
console.log(`[browse] Testing SOCKS5 upstream ${redactProxyUrl(proxyUrl)}...`);
|
||||
try {
|
||||
const test = await testUpstream({
|
||||
upstream: toUpstreamConfig(parsed),
|
||||
budgetMs: 5000,
|
||||
retries: 3,
|
||||
backoffMs: 500,
|
||||
});
|
||||
console.log(`[browse] [proxy] upstream test ok in ${test.ms}ms (${test.attempts} attempt${test.attempts === 1 ? '' : 's'})`);
|
||||
} catch (err) {
|
||||
const msg = err instanceof Error ? err.message : String(err);
|
||||
console.error(`[browse] [proxy] FAIL upstream ${redactProxyUrl(proxyUrl)}: ${msg}`);
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
proxyBridge = await startSocksBridge({ upstream: toUpstreamConfig(parsed) });
|
||||
console.log(`[browse] [proxy] bridge listening on 127.0.0.1:${proxyBridge.port}`);
|
||||
browserManager.setProxyConfig({ server: `socks5://127.0.0.1:${proxyBridge.port}` });
|
||||
} else {
|
||||
// HTTP/HTTPS or unauth SOCKS5 — pass through to Chromium directly.
|
||||
browserManager.setProxyConfig({
|
||||
server: `${parsed.scheme}://${parsed.host}:${parsed.port}`,
|
||||
...(parsed.userId ? { username: parsed.userId } : {}),
|
||||
...(parsed.password ? { password: parsed.password } : {}),
|
||||
});
|
||||
console.log(`[browse] [proxy] using ${redactProxyUrl(proxyUrl)} (pass-through to Chromium)`);
|
||||
}
|
||||
|
||||
// Tear down bridge on shutdown.
|
||||
process.on('exit', () => {
|
||||
if (proxyBridge) {
|
||||
proxyBridge.close().catch(() => { /* shutting down anyway */ });
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
// ─── Xvfb auto-spawn (Linux + headed + no DISPLAY) ─────────────
|
||||
// codex F2: walk display range to pick a free one (never hardcode :99);
|
||||
// record start-time alongside PID so cleanup can validate ownership and
|
||||
// not kill a recycled PID.
|
||||
let xvfb: XvfbHandle | null = null;
|
||||
const xvfbDecision = shouldSpawnXvfb(process.env, process.platform);
|
||||
if (xvfbDecision.spawn) {
|
||||
const displayNum = pickFreeDisplay();
|
||||
if (displayNum == null) {
|
||||
console.error('[browse] no free X display in range :99-:120 — refusing to clobber existing X servers');
|
||||
process.exit(1);
|
||||
}
|
||||
try {
|
||||
xvfb = await spawnXvfb(displayNum);
|
||||
process.env.DISPLAY = xvfb.display;
|
||||
console.log(`[browse] [xvfb] spawned on ${xvfb.display} (pid ${xvfb.pid})`);
|
||||
} catch (err) {
|
||||
const msg = err instanceof Error ? err.message : String(err);
|
||||
console.error(`[browse] [xvfb] FAILED: ${msg}`);
|
||||
console.error(`[browse] [xvfb] hint: ${xvfbInstallHint()}`);
|
||||
process.exit(1);
|
||||
}
|
||||
process.on('exit', () => { try { xvfb?.close(); } catch { /* shutting down */ } });
|
||||
} else if (process.env.BROWSE_HEADED === '1') {
|
||||
console.log(`[browse] [xvfb] skipped: ${xvfbDecision.reason}`);
|
||||
}
|
||||
|
||||
// Launch browser (headless or headed with extension)
|
||||
// BROWSE_HEADLESS_SKIP=1 skips browser launch entirely (for HTTP-only testing)
|
||||
const skipBrowser = process.env.BROWSE_HEADLESS_SKIP === '1';
|
||||
@@ -1998,6 +2118,13 @@ async function start() {
|
||||
serverPath: path.resolve(import.meta.dir, 'server.ts'),
|
||||
binaryVersion: readVersionHash() || undefined,
|
||||
mode: browserManager.getConnectionMode(),
|
||||
// D2 daemon-mismatch detection: CLI computes the same hash from its
|
||||
// resolved flags and refuses if it differs from this stored value.
|
||||
...(process.env.BROWSE_CONFIG_HASH ? { configHash: process.env.BROWSE_CONFIG_HASH } : {}),
|
||||
// Xvfb child PID + start-time + display so disconnect (or a future
|
||||
// daemon launch on this state file) can validate-then-cleanup orphans
|
||||
// without clobbering a recycled PID.
|
||||
...(xvfb ? { xvfbPid: xvfb.pid, xvfbStartTime: xvfb.startTime, xvfbDisplay: xvfb.display } : {}),
|
||||
};
|
||||
const tmpFile = config.stateFile + '.tmp';
|
||||
fs.writeFileSync(tmpFile, JSON.stringify(state, null, 2), { mode: 0o600 });
|
||||
|
||||
@@ -0,0 +1,314 @@
|
||||
/**
|
||||
* Local SOCKS5 bridge — accepts unauthenticated connections on 127.0.0.1:<ephemeral>
|
||||
* and relays them through an authenticated upstream SOCKS5 proxy.
|
||||
*
|
||||
* Why this exists: Chromium does not prompt for SOCKS5 auth at launch. To use
|
||||
* an auth-required upstream (residential SOCKS5 from a VPN provider, for
|
||||
* example), we run a no-auth listener locally that the browser talks to, and
|
||||
* the bridge handles the auth handshake with upstream.
|
||||
*
|
||||
* Architecture:
|
||||
* Chromium → socks5://127.0.0.1:<ephemeral> (this bridge, no auth)
|
||||
* └→ authenticated SOCKS5 to upstream → destination
|
||||
*
|
||||
* Ported from wintermute's scripts/socks-bridge.mjs with TS types, ephemeral
|
||||
* port (no hardcoded 1090), 127.0.0.1-only bind, and a stream-error policy
|
||||
* that closes the affected client connection without transport retries (a
|
||||
* SOCKS bridge is transport, not request-aware — retries can corrupt browser
|
||||
* traffic mid-stream).
|
||||
*/
|
||||
|
||||
import * as net from 'net';
|
||||
import { SocksClient, type SocksProxy } from 'socks';
|
||||
|
||||
export interface UpstreamConfig {
|
||||
host: string;
|
||||
port: number;
|
||||
userId?: string;
|
||||
password?: string;
|
||||
}
|
||||
|
||||
export interface BridgeHandle {
|
||||
/** Local port the bridge is listening on (ephemeral). */
|
||||
port: number;
|
||||
/** Underlying server. Exposed for tests; production code uses close(). */
|
||||
server: net.Server;
|
||||
/** Close the listener and all in-flight client sockets. */
|
||||
close: () => Promise<void>;
|
||||
}
|
||||
|
||||
const SOCKS5_VERSION = 0x05;
|
||||
const NO_AUTH_METHOD = 0x00;
|
||||
const CMD_CONNECT = 0x01;
|
||||
const ATYP_IPV4 = 0x01;
|
||||
const ATYP_DOMAINNAME = 0x03;
|
||||
const ATYP_IPV6 = 0x04;
|
||||
const REPLY_SUCCESS = 0x00;
|
||||
const REPLY_GENERAL_FAILURE = 0x01;
|
||||
const REPLY_HOST_UNREACHABLE = 0x04;
|
||||
const UPSTREAM_CONNECT_TIMEOUT_MS = 15000;
|
||||
|
||||
function buildUpstream(upstream: UpstreamConfig): SocksProxy {
|
||||
return {
|
||||
host: upstream.host,
|
||||
port: upstream.port,
|
||||
type: 5,
|
||||
...(upstream.userId ? { userId: upstream.userId } : {}),
|
||||
...(upstream.password ? { password: upstream.password } : {}),
|
||||
};
|
||||
}
|
||||
|
||||
function parseConnectRequest(reqData: Buffer): { host: string; port: number } | null {
|
||||
if (reqData.length < 7 || reqData[0] !== SOCKS5_VERSION || reqData[1] !== CMD_CONNECT) {
|
||||
return null;
|
||||
}
|
||||
const atyp = reqData[3];
|
||||
if (atyp === ATYP_IPV4) {
|
||||
if (reqData.length < 10) return null;
|
||||
const host = `${reqData[4]}.${reqData[5]}.${reqData[6]}.${reqData[7]}`;
|
||||
const port = reqData.readUInt16BE(8);
|
||||
return { host, port };
|
||||
}
|
||||
if (atyp === ATYP_DOMAINNAME) {
|
||||
const len = reqData[4];
|
||||
if (reqData.length < 5 + len + 2) return null;
|
||||
const host = reqData.subarray(5, 5 + len).toString('utf8');
|
||||
const port = reqData.readUInt16BE(5 + len);
|
||||
return { host, port };
|
||||
}
|
||||
if (atyp === ATYP_IPV6) {
|
||||
if (reqData.length < 22) return null;
|
||||
const parts: string[] = [];
|
||||
for (let i = 4; i < 20; i += 2) parts.push(reqData.readUInt16BE(i).toString(16));
|
||||
const host = parts.join(':');
|
||||
const port = reqData.readUInt16BE(20);
|
||||
return { host, port };
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
function writeReply(sock: net.Socket, code: number): void {
|
||||
// SOCKS5 reply: VER REP RSV ATYP BND.ADDR(0.0.0.0) BND.PORT(0)
|
||||
const reply = Buffer.from([SOCKS5_VERSION, code, 0x00, ATYP_IPV4, 0, 0, 0, 0, 0, 0]);
|
||||
try { sock.write(reply); } catch { /* peer already gone */ }
|
||||
}
|
||||
|
||||
/**
|
||||
* Start a local SOCKS5 bridge that relays to an authenticated upstream.
|
||||
* Listens on 127.0.0.1 only (never 0.0.0.0). port: 0 picks an ephemeral port.
|
||||
*
|
||||
* Stream-error policy: on any error during a relayed connection, the affected
|
||||
* client socket and its upstream pair are destroyed. No transport retries.
|
||||
* Browser sees a proxy/connection error and surfaces it as such.
|
||||
*/
|
||||
export async function startSocksBridge(opts: {
|
||||
upstream: UpstreamConfig;
|
||||
port?: number;
|
||||
}): Promise<BridgeHandle> {
|
||||
const upstreamProxy = buildUpstream(opts.upstream);
|
||||
const requestedPort = opts.port ?? 0;
|
||||
const inFlight = new Set<net.Socket>();
|
||||
|
||||
// Frame-size predicates for the two SOCKS5 messages we read from the
|
||||
// client. Both return null when we don't yet have enough bytes to know
|
||||
// the frame size, or a positive integer when we do.
|
||||
function greetingSize(buf: Buffer): number | null {
|
||||
if (buf.length < 2) return null;
|
||||
return 2 + buf[1]; // VER NMETHODS + N method bytes
|
||||
}
|
||||
function connectSize(buf: Buffer): number | null {
|
||||
if (buf.length < 5) return null;
|
||||
const atyp = buf[3];
|
||||
if (atyp === ATYP_IPV4) return 10; // VER CMD RSV ATYP + 4 + 2
|
||||
if (atyp === ATYP_IPV6) return 22; // VER CMD RSV ATYP + 16 + 2
|
||||
if (atyp === ATYP_DOMAINNAME) return 7 + buf[4]; // VER CMD RSV ATYP LEN + N + 2
|
||||
return null;
|
||||
}
|
||||
|
||||
type State = 'greeting' | 'connect' | 'connecting' | 'piped' | 'closed';
|
||||
|
||||
const server = net.createServer((clientSocket) => {
|
||||
inFlight.add(clientSocket);
|
||||
clientSocket.once('close', () => inFlight.delete(clientSocket));
|
||||
|
||||
let state: State = 'greeting';
|
||||
let buf = Buffer.alloc(0);
|
||||
let upstreamSocket: net.Socket | null = null;
|
||||
|
||||
const killBoth = (reason?: string) => {
|
||||
void reason;
|
||||
state = 'closed';
|
||||
try { clientSocket.destroy(); } catch { /* already gone */ }
|
||||
if (upstreamSocket) {
|
||||
try { upstreamSocket.destroy(); } catch { /* already gone */ }
|
||||
}
|
||||
};
|
||||
|
||||
const handshakeTimeout = setTimeout(() => {
|
||||
if (state === 'greeting' || state === 'connect' || state === 'connecting') {
|
||||
killBoth('handshake timeout');
|
||||
}
|
||||
}, 30000);
|
||||
clientSocket.once('close', () => clearTimeout(handshakeTimeout));
|
||||
|
||||
const onData = (chunk: Buffer) => {
|
||||
if (state === 'closed' || state === 'piped') return;
|
||||
buf = buf.length === 0 ? chunk : Buffer.concat([buf, chunk]);
|
||||
|
||||
if (state === 'greeting') {
|
||||
const sz = greetingSize(buf);
|
||||
if (sz == null || buf.length < sz) return;
|
||||
const greeting = buf.subarray(0, sz);
|
||||
buf = buf.subarray(sz);
|
||||
if (greeting[0] !== SOCKS5_VERSION) { killBoth('bad version'); return; }
|
||||
try { clientSocket.write(Buffer.from([SOCKS5_VERSION, NO_AUTH_METHOD])); }
|
||||
catch { killBoth('write greeting reply failed'); return; }
|
||||
state = 'connect';
|
||||
// Fall through — buf may already contain CONNECT bytes (coalesced).
|
||||
}
|
||||
|
||||
if (state === 'connect') {
|
||||
const sz = connectSize(buf);
|
||||
if (sz == null || buf.length < sz) return;
|
||||
const reqData = buf.subarray(0, sz);
|
||||
const remainder = buf.subarray(sz);
|
||||
const dest = parseConnectRequest(reqData);
|
||||
if (!dest) {
|
||||
writeReply(clientSocket, REPLY_GENERAL_FAILURE);
|
||||
killBoth('bad connect request');
|
||||
return;
|
||||
}
|
||||
state = 'connecting';
|
||||
// Pause client reads so any post-handshake bytes don't get dropped.
|
||||
// We replay `remainder` after upstream is established.
|
||||
clientSocket.pause();
|
||||
SocksClient.createConnection({
|
||||
proxy: upstreamProxy,
|
||||
command: 'connect',
|
||||
destination: { host: dest.host, port: dest.port },
|
||||
timeout: UPSTREAM_CONNECT_TIMEOUT_MS,
|
||||
}).then((result) => {
|
||||
if (state === 'closed') {
|
||||
try { result.socket.destroy(); } catch { /* shutdown */ }
|
||||
return;
|
||||
}
|
||||
upstreamSocket = result.socket;
|
||||
writeReply(clientSocket, REPLY_SUCCESS);
|
||||
// Replay any pre-buffered post-handshake bytes BEFORE we pipe.
|
||||
if (remainder.length > 0) {
|
||||
try { upstreamSocket.write(remainder); } catch { killBoth('replay write failed'); return; }
|
||||
}
|
||||
// Wire the rest of the connection through the pipe.
|
||||
upstreamSocket.on('error', () => killBoth('upstream error'));
|
||||
upstreamSocket.on('close', () => { try { clientSocket.destroy(); } catch { /* already gone */ } });
|
||||
clientSocket.removeListener('data', onData);
|
||||
clientSocket.pipe(upstreamSocket);
|
||||
upstreamSocket.pipe(clientSocket);
|
||||
clientSocket.resume();
|
||||
state = 'piped';
|
||||
}).catch(() => {
|
||||
writeReply(clientSocket, REPLY_HOST_UNREACHABLE);
|
||||
killBoth('upstream connect failed');
|
||||
});
|
||||
return;
|
||||
}
|
||||
};
|
||||
|
||||
clientSocket.on('data', onData);
|
||||
clientSocket.on('error', () => killBoth('client error'));
|
||||
});
|
||||
|
||||
await new Promise<void>((resolve, reject) => {
|
||||
const onErr = (e: unknown) => { server.off('listening', onListen); reject(e); };
|
||||
const onListen = () => { server.off('error', onErr); resolve(); };
|
||||
server.once('error', onErr);
|
||||
server.once('listening', onListen);
|
||||
server.listen(requestedPort, '127.0.0.1');
|
||||
});
|
||||
|
||||
const address = server.address();
|
||||
if (!address || typeof address === 'string') {
|
||||
throw new Error('socks-bridge: unexpected listener address');
|
||||
}
|
||||
|
||||
return {
|
||||
port: address.port,
|
||||
server,
|
||||
close: async () => {
|
||||
for (const sock of inFlight) {
|
||||
try { sock.destroy(); } catch { /* already gone */ }
|
||||
}
|
||||
inFlight.clear();
|
||||
await new Promise<void>((resolve) => server.close(() => resolve()));
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
export interface UpstreamTestOpts {
|
||||
upstream: UpstreamConfig;
|
||||
/** Hostname to test connectivity to through the upstream. Default 1.1.1.1. */
|
||||
testHost?: string;
|
||||
/** Port. Default 443. */
|
||||
testPort?: number;
|
||||
/** Total time budget across all retries. Default 5000ms. */
|
||||
budgetMs?: number;
|
||||
/** Number of attempts. Default 3. */
|
||||
retries?: number;
|
||||
/** Backoff between attempts. Default 500ms. */
|
||||
backoffMs?: number;
|
||||
}
|
||||
|
||||
/**
|
||||
* Pre-flight: verify the upstream proxy actually accepts our credentials and
|
||||
* can reach a known endpoint. Called before chromium.launch so failures
|
||||
* surface as a clear startup error instead of a confusing 'connection
|
||||
* refused' on first navigation.
|
||||
*
|
||||
* Retries a few times with backoff because residential VPNs can take a
|
||||
* second to fully establish on first connect.
|
||||
*
|
||||
* Throws on final failure. Caller is responsible for redacting any error
|
||||
* that may leak credentials.
|
||||
*/
|
||||
export async function testUpstream(opts: UpstreamTestOpts): Promise<{ ok: true; attempts: number; ms: number }> {
|
||||
const upstreamProxy = buildUpstream(opts.upstream);
|
||||
const testHost = opts.testHost ?? '1.1.1.1';
|
||||
const testPort = opts.testPort ?? 443;
|
||||
const budgetMs = opts.budgetMs ?? 5000;
|
||||
const retries = opts.retries ?? 3;
|
||||
const backoffMs = opts.backoffMs ?? 500;
|
||||
|
||||
const start = Date.now();
|
||||
let lastErr: unknown;
|
||||
|
||||
for (let attempt = 1; attempt <= retries; attempt++) {
|
||||
const elapsed = Date.now() - start;
|
||||
const remaining = budgetMs - elapsed;
|
||||
if (remaining <= 0) break;
|
||||
const perAttempt = Math.min(remaining, Math.max(500, Math.floor(budgetMs / retries)));
|
||||
|
||||
try {
|
||||
const result = await SocksClient.createConnection({
|
||||
proxy: upstreamProxy,
|
||||
command: 'connect',
|
||||
destination: { host: testHost, port: testPort },
|
||||
timeout: perAttempt,
|
||||
});
|
||||
try { result.socket.destroy(); } catch { /* test connection done */ }
|
||||
return { ok: true, attempts: attempt, ms: Date.now() - start };
|
||||
} catch (err) {
|
||||
lastErr = err;
|
||||
if (attempt < retries) {
|
||||
const elapsedAfter = Date.now() - start;
|
||||
if (elapsedAfter + backoffMs >= budgetMs) break;
|
||||
await new Promise<void>((r) => setTimeout(r, backoffMs));
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
const reason = lastErr instanceof Error ? lastErr.message : String(lastErr);
|
||||
const err = new Error(`SOCKS5 upstream rejected or unreachable after ${retries} attempts (${Date.now() - start}ms): ${reason}`);
|
||||
(err as Error & { upstreamHost?: string; upstreamPort?: number }).upstreamHost = opts.upstream.host;
|
||||
(err as Error & { upstreamHost?: string; upstreamPort?: number }).upstreamPort = opts.upstream.port;
|
||||
throw err;
|
||||
}
|
||||
@@ -0,0 +1,39 @@
|
||||
/**
|
||||
* Stealth init script — webdriver-mask only (D7, codex narrowed).
|
||||
*
|
||||
* Modern anti-bot fingerprinters check consistency between navigator
|
||||
* properties (plugins.length, languages, userAgent, platform). Faking those
|
||||
* to fixed values (the wintermute approach) can flag MORE bot-like, not
|
||||
* less, and breaks legitimate sites that reflect on these properties.
|
||||
*
|
||||
* The honest minimum is masking navigator.webdriver, which Chromium exposes
|
||||
* as a known automation tell. Letting plugins/languages/chrome.runtime
|
||||
* surface their native Chromium values keeps the fingerprint internally
|
||||
* consistent.
|
||||
*/
|
||||
|
||||
import type { Browser, BrowserContext } from 'playwright';
|
||||
|
||||
/**
|
||||
* Init script applied to every page in a context. Runs in the page's main
|
||||
* world before any other scripts. Idempotent — defining the same property
|
||||
* twice in different contexts is fine.
|
||||
*/
|
||||
export const WEBDRIVER_MASK_SCRIPT = `Object.defineProperty(navigator, 'webdriver', { get: () => false });`;
|
||||
|
||||
/**
|
||||
* Apply stealth patches to a fresh BrowserContext (or persistent context).
|
||||
* Called by browser-manager.launch() and launchHeaded().
|
||||
*/
|
||||
export async function applyStealth(context: BrowserContext): Promise<void> {
|
||||
await context.addInitScript({ content: WEBDRIVER_MASK_SCRIPT });
|
||||
}
|
||||
|
||||
/**
|
||||
* Args added to chromium.launch's `args` to suppress the
|
||||
* AutomationControlled blink feature. This is independent of the init
|
||||
* script — it changes how Chromium identifies itself in the protocol layer.
|
||||
*/
|
||||
export const STEALTH_LAUNCH_ARGS = [
|
||||
'--disable-blink-features=AutomationControlled',
|
||||
];
|
||||
@@ -1137,9 +1137,10 @@ export async function handleWriteCommand(
|
||||
}
|
||||
|
||||
case 'download': {
|
||||
if (args.length === 0) throw new Error('Usage: download <url|@ref> [path] [--base64]');
|
||||
if (args.length === 0) throw new Error('Usage: download <url|@ref> [path] [--base64] [--navigate]');
|
||||
const isBase64 = args.includes('--base64');
|
||||
const filteredArgs = args.filter(a => a !== '--base64');
|
||||
const useNavigate = args.includes('--navigate');
|
||||
const filteredArgs = args.filter(a => a !== '--base64' && a !== '--navigate');
|
||||
let url = filteredArgs[0];
|
||||
const outputPath = filteredArgs[1];
|
||||
|
||||
@@ -1200,6 +1201,60 @@ export async function handleWriteCommand(
|
||||
if (!match) throw new Error('Failed to decode blob data');
|
||||
contentType = match[1];
|
||||
buffer = Buffer.from(match[2], 'base64');
|
||||
} else if (useNavigate) {
|
||||
// Strategy 2: Navigate to URL and capture browser-triggered download.
|
||||
// Handles URLs that trigger file downloads via redirects,
|
||||
// Content-Disposition headers, or anti-bot CDN chains where
|
||||
// page.request.fetch() can't follow the auth/redirect chain.
|
||||
await validateNavigationUrl(url);
|
||||
const downloadPromise = page.waitForEvent('download', { timeout: 60000 });
|
||||
// Use goto with 'commit' wait — the page may redirect to trigger
|
||||
// the download, so 'domcontentloaded' may never fire.
|
||||
page.goto(url, { waitUntil: 'commit', timeout: 30000 }).catch(() => {
|
||||
// Navigation may "fail" because the response is a download,
|
||||
// not a page. The download event handles it.
|
||||
});
|
||||
const download = await downloadPromise;
|
||||
const failure = await download.failure();
|
||||
if (failure) {
|
||||
throw new Error(`Download failed: ${failure}`);
|
||||
}
|
||||
// Save to temp location first, then read into buffer
|
||||
const tempPath = path.join(TEMP_DIR, `browse-nav-download-${Date.now()}`);
|
||||
await download.saveAs(tempPath);
|
||||
buffer = fs.readFileSync(tempPath);
|
||||
// Try to infer content type from suggested filename
|
||||
const suggested = download.suggestedFilename();
|
||||
if (suggested) {
|
||||
const extMatch = suggested.match(/\.([a-z0-9]+)$/i);
|
||||
if (extMatch) {
|
||||
const extLower = extMatch[1].toLowerCase();
|
||||
const mimeMap: Record<string, string> = {
|
||||
epub: 'application/epub+zip', pdf: 'application/pdf',
|
||||
zip: 'application/zip', gz: 'application/gzip',
|
||||
mp3: 'audio/mpeg', mp4: 'video/mp4',
|
||||
jpg: 'image/jpeg', jpeg: 'image/jpeg', png: 'image/png',
|
||||
txt: 'text/plain', html: 'text/html', json: 'application/json',
|
||||
};
|
||||
contentType = mimeMap[extLower] || 'application/octet-stream';
|
||||
}
|
||||
}
|
||||
// Clean up temp file if we're going to write elsewhere
|
||||
if (outputPath || isBase64) {
|
||||
try { fs.unlinkSync(tempPath); } catch { /* ignore */ }
|
||||
} else {
|
||||
// No explicit output path — rename temp file with inferred extension.
|
||||
const ext = contentType.split(';')[0].includes('/')
|
||||
? mimeToExt(contentType.split(';')[0].trim())
|
||||
: '.bin';
|
||||
const finalPath = path.join(TEMP_DIR, `browse-download-${Date.now()}${ext}`);
|
||||
fs.renameSync(tempPath, finalPath);
|
||||
const sizeKB = Math.round(buffer.length / 1024);
|
||||
return `Downloaded: ${finalPath} (${sizeKB}KB, ${contentType.split(';')[0].trim()})${suggested ? ` [${suggested}]` : ''}`;
|
||||
}
|
||||
if (buffer.length > 200 * 1024 * 1024) {
|
||||
throw new Error('File too large (>200MB).');
|
||||
}
|
||||
} else {
|
||||
// Strategy 1: Direct URL via page.request.fetch().
|
||||
// Gate the URL through the same validator `goto` uses. Without
|
||||
|
||||
@@ -0,0 +1,193 @@
|
||||
/**
|
||||
* Xvfb (X virtual framebuffer) auto-spawn for headed Chromium on Linux
|
||||
* containers without DISPLAY.
|
||||
*
|
||||
* The motivating use case: a headless container needs to run Chromium in
|
||||
* "headed" mode (visible window) — for example, to run with the
|
||||
* AutomationControlled flag off and pass anti-bot fingerprint checks. Xvfb
|
||||
* provides an off-screen X server that Chromium can render into.
|
||||
*
|
||||
* Design notes:
|
||||
* - Pick a free display dynamically (try :99, :100, :101...). NEVER unlink
|
||||
* /tmp/.X<n>-lock for displays we didn't create — that would steal an
|
||||
* active X server from another process or user.
|
||||
* - Validate orphan Xvfb processes by BOTH /proc/<pid>/cmdline matching
|
||||
* 'Xvfb' AND start-time matching the recorded value. PID reuse is real;
|
||||
* a one-field check would let us send SIGTERM to an unrelated process
|
||||
* that happened to inherit a recycled PID.
|
||||
* - Skip spawn entirely on macOS/Windows (native windowing) and on Linux
|
||||
* when DISPLAY or WAYLAND_DISPLAY is already set (codex F2).
|
||||
*/
|
||||
|
||||
import * as fs from 'fs';
|
||||
import * as path from 'path';
|
||||
import * as os from 'os';
|
||||
import { safeKill, isProcessAlive } from './error-handling';
|
||||
|
||||
export interface XvfbHandle {
|
||||
pid: number;
|
||||
startTime: string;
|
||||
display: string; // e.g. ":99"
|
||||
/** Best-effort cleanup. Validates ownership before kill. */
|
||||
close: () => void;
|
||||
}
|
||||
|
||||
export interface ShouldSpawnDecision {
|
||||
spawn: boolean;
|
||||
reason: string;
|
||||
}
|
||||
|
||||
const DISPLAY_RANGE_START = 99;
|
||||
const DISPLAY_RANGE_END = 120;
|
||||
|
||||
/**
|
||||
* Decide whether the daemon should auto-spawn an Xvfb. Pure: takes env +
|
||||
* platform and returns a decision. Easy to unit test.
|
||||
*/
|
||||
export function shouldSpawnXvfb(env: NodeJS.ProcessEnv, platform: NodeJS.Platform): ShouldSpawnDecision {
|
||||
if (env.BROWSE_HEADED !== '1') return { spawn: false, reason: 'not headed mode' };
|
||||
if (platform !== 'linux') return { spawn: false, reason: `platform ${platform} uses native windowing` };
|
||||
if (env.DISPLAY) return { spawn: false, reason: `DISPLAY=${env.DISPLAY} already set` };
|
||||
if (env.WAYLAND_DISPLAY) return { spawn: false, reason: `WAYLAND_DISPLAY=${env.WAYLAND_DISPLAY} set; Chromium uses Wayland natively` };
|
||||
return { spawn: true, reason: 'linux headed without DISPLAY/WAYLAND_DISPLAY' };
|
||||
}
|
||||
|
||||
/**
|
||||
* Probe a display number — return true if no X server is currently listening
|
||||
* on it (i.e., we can safely spawn a new Xvfb there).
|
||||
*/
|
||||
export function isDisplayFree(displayNum: number): boolean {
|
||||
// xdpyinfo exits 0 if a display is reachable. Exit non-zero means no
|
||||
// server, which is what we want.
|
||||
const result = Bun.spawnSync(['xdpyinfo', '-display', `:${displayNum}`], {
|
||||
stdout: 'ignore', stderr: 'ignore', timeout: 2000,
|
||||
});
|
||||
return result.exitCode !== 0;
|
||||
}
|
||||
|
||||
/**
|
||||
* Walk the display range and return the first free one, or null if all
|
||||
* displays in the range are taken.
|
||||
*/
|
||||
export function pickFreeDisplay(
|
||||
rangeStart: number = DISPLAY_RANGE_START,
|
||||
rangeEnd: number = DISPLAY_RANGE_END,
|
||||
): number | null {
|
||||
for (let n = rangeStart; n <= rangeEnd; n++) {
|
||||
if (isDisplayFree(n)) return n;
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
/**
|
||||
* Read the wall-clock start time of a PID via `ps -o lstart=`. Stable across
|
||||
* reads (unlike /proc/stat field 22 which reports jiffies since boot in a
|
||||
* format that's harder to compare). Returns an empty string if the process
|
||||
* is gone or ps fails.
|
||||
*/
|
||||
export function readPidStartTime(pid: number): string {
|
||||
if (!isProcessAlive(pid)) return '';
|
||||
const result = Bun.spawnSync(['ps', '-p', String(pid), '-o', 'lstart='], {
|
||||
stdout: 'pipe', stderr: 'pipe', timeout: 2000,
|
||||
});
|
||||
if (result.exitCode !== 0) return '';
|
||||
return result.stdout.toString().trim();
|
||||
}
|
||||
|
||||
/**
|
||||
* Read the cmdline of a PID via /proc/<pid>/cmdline. Returns empty string
|
||||
* if the process is gone or the cmdline isn't readable.
|
||||
*/
|
||||
export function readPidCmdline(pid: number): string {
|
||||
try {
|
||||
return fs.readFileSync(`/proc/${pid}/cmdline`, 'utf-8').replace(/\0/g, ' ').trim();
|
||||
} catch {
|
||||
return '';
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Validate that PID is still our Xvfb child. Both checks must pass:
|
||||
* 1. /proc/<pid>/cmdline contains 'Xvfb' (string match — Xvfb's argv[0] is
|
||||
* always 'Xvfb' or a full path ending in /Xvfb)
|
||||
* 2. Start time matches the recorded value (PID reuse defense)
|
||||
*/
|
||||
export function isOurXvfb(pid: number, recordedStartTime: string): boolean {
|
||||
if (!pid || !recordedStartTime) return false;
|
||||
const cmdline = readPidCmdline(pid);
|
||||
if (!cmdline.toLowerCase().includes('xvfb')) return false;
|
||||
const currentStart = readPidStartTime(pid);
|
||||
if (!currentStart) return false;
|
||||
return currentStart === recordedStartTime;
|
||||
}
|
||||
|
||||
/**
|
||||
* Spawn Xvfb on the given display. Returns a handle including the validated
|
||||
* start-time so future cleanup can confirm ownership.
|
||||
*
|
||||
* Throws if Xvfb isn't installed (caller should print a platform-specific
|
||||
* install hint).
|
||||
*/
|
||||
export async function spawnXvfb(displayNum: number): Promise<XvfbHandle> {
|
||||
const display = `:${displayNum}`;
|
||||
|
||||
// Spawn detached: Xvfb's lifetime is tied to whether we've explicitly
|
||||
// killed it via the handle's close() method, not to the parent process.
|
||||
const proc = Bun.spawn(['Xvfb', display, '-screen', '0', '1920x1080x24', '-ac'], {
|
||||
stdio: ['ignore', 'ignore', 'ignore'],
|
||||
});
|
||||
proc.unref();
|
||||
|
||||
// Wait for the X server to become reachable — Xvfb takes a few hundred ms
|
||||
// to bind. Probe via xdpyinfo with retries.
|
||||
const deadline = Date.now() + 3000;
|
||||
let ready = false;
|
||||
while (Date.now() < deadline) {
|
||||
await Bun.sleep(100);
|
||||
if (!isDisplayFree(displayNum)) { ready = true; break; }
|
||||
// If Xvfb crashed during startup, fail fast.
|
||||
if (proc.exitCode != null) {
|
||||
throw new Error(`Xvfb on ${display} exited during startup (code ${proc.exitCode}). Hint: install xvfb (apt-get install xvfb / yum install xorg-x11-server-Xvfb).`);
|
||||
}
|
||||
}
|
||||
if (!ready) {
|
||||
try { proc.kill('SIGKILL'); } catch { /* ignore */ }
|
||||
throw new Error(`Xvfb on ${display} never became reachable within 3s timeout`);
|
||||
}
|
||||
|
||||
const startTime = readPidStartTime(proc.pid);
|
||||
return {
|
||||
pid: proc.pid,
|
||||
startTime,
|
||||
display,
|
||||
close: () => cleanupXvfb({ pid: proc.pid, startTime, display }),
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Cleanup an Xvfb child if it's still ours. Validates ownership first; if
|
||||
* the PID has been recycled or the cmdline doesn't match, leave it alone.
|
||||
*
|
||||
* Best-effort: never throws.
|
||||
*/
|
||||
export function cleanupXvfb(state: { pid: number; startTime: string; display: string }): void {
|
||||
if (!state.pid) return;
|
||||
if (!isOurXvfb(state.pid, state.startTime)) return;
|
||||
try { safeKill(state.pid, 'SIGTERM'); } catch { /* swallow */ }
|
||||
// Wait briefly for Xvfb to exit, then SIGKILL if still alive.
|
||||
const deadline = Date.now() + 1000;
|
||||
while (Date.now() < deadline) {
|
||||
if (!isProcessAlive(state.pid)) break;
|
||||
}
|
||||
if (isProcessAlive(state.pid)) {
|
||||
try { safeKill(state.pid, 'SIGKILL'); } catch { /* swallow */ }
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Print a platform-specific install hint and return the message string.
|
||||
* Used by server.ts when Xvfb isn't installed.
|
||||
*/
|
||||
export function xvfbInstallHint(): string {
|
||||
return 'Xvfb not installed. apt-get install xvfb (Debian/Ubuntu) or yum install xorg-x11-server-Xvfb (RHEL/CentOS). Note: minimal containers (alpine, distroless) may also need fonts, dbus, gtk libs for headed Chromium to render.';
|
||||
}
|
||||
Reference in New Issue
Block a user