High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
feat: cloakbrowser support basics
Luigi Agostief899469b98d
diff --git a/dashboard/src/pages/settings/BrowserSettingsSection.tsx b/dashboard/src/pages/settings/BrowserSettingsSection.tsxindex c0054d71..d6a7d134 100644--- a/dashboard/src/pages/settings/BrowserSettingsSection.tsx+++ b/dashboard/src/pages/settings/BrowserSettingsSection.tsx@@ -1,4 +1,4 @@-import type { BackendConfig } from "../../types";+import type { BackendCloakBrowserConfig, BackendConfig } from "../../types";import type { UpdateBackendSection } from "./settingsShared";import { csvToList, fieldClass, listToCsv } from "./settingsShared";import { SectionCard, SettingRow } from "./SettingsSharedComponents";@@ -12,13 +12,39 @@ export function BrowserSettingsSection({backendConfig,updateBackendSection,}: BrowserSettingsSectionProps) {+ const cloak = backendConfig.browser.cloak;+ const updateCloak = (patch: Partial<BackendCloakBrowserConfig>) =>+ updateBackendSection("browser", {+ cloak: {+ ...cloak,+ ...patch,+ },+ });+return (<SectionCardtitle="Browser Runtime"description="These settings are written into the generated child config for new managed instances."><SettingRow- label="Chrome version"+ label="Provider"+ description="Browser backend used for new managed instances."+ >+ <select+ value={backendConfig.browser.provider}+ onChange={(e) =>+ updateBackendSection("browser", {+ provider: e.target.value === "cloak" ? "cloak" : "chrome",+ })+ }+ className={fieldClass}+ >+ <option value="chrome">Chrome</option>+ <option value="cloak">CloakBrowser</option>+ </select>+ </SettingRow>+ <SettingRow+ label="Browser version"description="Version string used in generated UA/fingerprint defaults."><input@@ -32,8 +58,8 @@ export function BrowserSettingsSection({/></SettingRow><SettingRow- label="Chrome binary"- description="Optional path override for the Chrome executable."+ label="Browser binary"+ description="Optional path override for the Chrome or CloakBrowser executable."><inputvalue={backendConfig.browser.binary}@@ -45,6 +71,115 @@ export function BrowserSettingsSection({className={fieldClass}/></SettingRow>+ {backendConfig.browser.provider === "cloak" && (+ <>+ <SettingRow+ label="Fingerprint seed"+ description="Deterministic CloakBrowser identity seed. Leave blank for a fresh identity per launch."+ >+ <input+ value={cloak.fingerprintSeed}+ onChange={(e) => updateCloak({ fingerprintSeed: e.target.value })}+ className={fieldClass}+ />+ </SettingRow>+ <SettingRow+ label="Fingerprint platform"+ description="Native platform fingerprint reported by CloakBrowser."+ >+ <select+ value={cloak.platform}+ onChange={(e) =>+ updateCloak({+ platform: e.target+ .value as BackendCloakBrowserConfig["platform"],+ })+ }+ className={fieldClass}+ >+ <option value="">Auto</option>+ <option value="windows">Windows</option>+ <option value="macos">macOS</option>+ <option value="linux">Linux</option>+ </select>+ </SettingRow>+ <SettingRow+ label="Cloak locale"+ description="Locale passed as --fingerprint-locale."+ >+ <input+ value={cloak.locale}+ onChange={(e) => updateCloak({ locale: e.target.value })}+ className={fieldClass}+ />+ </SettingRow>+ <SettingRow+ label="Cloak timezone"+ description="Timezone passed as --fingerprint-timezone."+ >+ <input+ value={cloak.timezone}+ onChange={(e) => updateCloak({ timezone: e.target.value })}+ className={fieldClass}+ />+ </SettingRow>+ <SettingRow+ label="WebRTC IP"+ description="Explicit replacement IP or auto for CloakBrowser proxy exit-IP resolution."+ >+ <input+ value={cloak.webrtcIP}+ onChange={(e) => updateCloak({ webrtcIP: e.target.value })}+ className={fieldClass}+ />+ </SettingRow>+ <SettingRow+ label="Fonts directory"+ description="Directory containing target-platform fonts for CloakBrowser."+ >+ <input+ value={cloak.fontsDir}+ onChange={(e) => updateCloak({ fontsDir: e.target.value })}+ className={fieldClass}+ />+ </SettingRow>+ <SettingRow+ label="Storage quota"+ description="Storage quota in MB passed as --fingerprint-storage-quota."+ >+ <input+ type="number"+ min={0}+ value={cloak.storageQuotaMB ?? ""}+ onChange={(e) =>+ updateCloak({+ storageQuotaMB:+ e.target.value === "" ? undefined : Number(e.target.value),+ })+ }+ className={fieldClass}+ />+ </SettingRow>+ <SettingRow+ label="Native stealth only"+ description="Disable PinchTab JS stealth overlays and automation-hiding launch flags."+ >+ <label className="flex items-center gap-2 text-sm text-text-primary">+ <input+ type="checkbox"+ checked={cloak.disableDefaultStealthArgs ?? true}+ onChange={(e) =>+ updateCloak({+ disableDefaultStealthArgs: e.target.checked,+ })+ }+ className="h-4 w-4 accent-primary"+ />+ Use CloakBrowser native patches+ </label>+ </SettingRow>+ </>+ )}<SettingRowlabel="Extra flags"description="Additional Chrome flags appended when launching managed instances."diff --git a/dashboard/src/types/index.ts b/dashboard/src/types/index.tsindex 5a0950d2..96e956d3 100644--- a/dashboard/src/types/index.ts+++ b/dashboard/src/types/index.ts@@ -97,10 +97,26 @@ export interface BackendObservabilityConfig {activity: BackendActivityConfig;}+export type BackendBrowserProvider = "chrome" | "cloak";++export interface BackendCloakBrowserConfig {+ fingerprintSeed: string;+ platform: "" | "windows" | "macos" | "linux";+ locale: string;+ timezone: string;+ webrtcIP: string;+ fontsDir: string;+ storageQuotaMB?: number;+ disableDefaultStealthArgs?: boolean;+}+export interface BackendBrowserConfig {+ provider: BackendBrowserProvider;version: string;binary: string;+ remoteDebuggingPort?: number;extraFlags: string;+ cloak: BackendCloakBrowserConfig;extensionPaths: string[];}@@ -233,9 +249,21 @@ export const defaultBackendConfig: BackendConfig = {cookieSecure: undefined,},browser: {+ provider: "chrome",version: "144.0.7559.133",binary: "",+ remoteDebuggingPort: undefined,extraFlags: "",+ cloak: {+ fingerprintSeed: "",+ platform: "",+ locale: "",+ timezone: "",+ webrtcIP: "",+ fontsDir: "",+ storageQuotaMB: undefined,+ disableDefaultStealthArgs: true,+ },extensionPaths: [],},instanceDefaults: {@@ -356,6 +384,11 @@ export function normalizeBackendConfig(browser: {...defaultBackendConfig.browser,...(input?.browser ?? {}),+ provider: input?.browser?.provider === "cloak" ? "cloak" : "chrome",+ cloak: {+ ...defaultBackendConfig.browser.cloak,+ ...(input?.browser?.cloak ?? {}),+ },extensionPaths:input?.browser?.extensionPaths ??defaultBackendConfig.browser.extensionPaths,diff --git a/dev b/devindex 448e5ceb..cc154e0f 100755--- a/dev+++ b/dev@@ -29,8 +29,7 @@ COMMANDS=("e2e:π³:E2E suites"" basic:π³:Basic suite (api + cli + infra)"" extended:π³:Extended suite (all extended)"- " smoke:π³:Smoke suite"- " smoke-docker:π³:Host Docker smoke checks only"+ " smoke:π³:Smoke suite with Docker checks"" smoke-plugin:π³:OpenClaw plugin Docker smoke"" api:π³:API basic tests"" cli:π³:CLI basic tests"@@ -40,6 +39,8 @@ COMMANDS=(" cli-extended:π³:CLI extended tests"" infra-extended:π³:Infra extended (multi-instance)"" test <name>:π³:Run a single E2E test by start_test name"+ "smoke:π¨:Manual smoke checks"+ " cloakbrowser:π¨:CloakBrowser Docker image smoke""opt:β‘:Optimization baseline"" baseline:β‘:Run optimization baseline lane""bench:π:Benchmark lanes"@@ -258,6 +259,24 @@ run_command() {local bench_args="${target#bench }"exec bash scripts/dev-bench.sh ${bench_args};;+ "smoke")+ echo " ${ACCENT}${BOLD}π¨ Manual smoke checks${NC}"+ echo ""+ echo " Usage:"+ echo " ./dev smoke cloakbrowser [pinchtab-image]"+ echo ""+ echo " ${MUTED}CloakBrowser smoke checks are opt-in and Docker-backed. By default this builds pinchtab-cloakbrowser:test from tests/tools/docker/cloakbrowser-smoke.Dockerfile.${NC}"+ exit 1+ ;;+ "smoke cloakbrowser"|"smoke cloakbrowser "*)+ echo " ${ACCENT}${BOLD}π¨ CloakBrowser Docker smoke${NC}"+ echo ""+ local -a smoke_args=()+ if [ "$target" != "smoke cloakbrowser" ]; then+ read -r -a smoke_args <<< "${target#smoke cloakbrowser }"+ fi+ exec bash scripts/docker-cloakbrowser-smoke.sh "${smoke_args[@]}"+ ;;"e2e test")echo " ${ERROR}Missing test name. Usage: dev e2e test \"<name substring>\"${NC}"exit 1@@ -456,6 +475,13 @@ if [ $# -gt 0 ]; thenfirun_e2e_runner "${@:2}";;+ smoke)+ if [ $# -gt 1 ]; then+ run_command "smoke ${*:2}"+ else+ run_command "smoke"+ fi+ ;;binary)if [ $# -gt 1 ]; thenrun_command "binary $2"diff --git a/docs/architecture/browser-targets.md b/docs/architecture/browser-targets.mdnew file mode 100644index 00000000..91d9521d--- /dev/null+++ b/docs/architecture/browser-targets.md@@ -0,0 +1,345 @@+# Browser Targets++PinchTab currently treats the browser backend as a single global provider:+`browser.provider=chrome|cloak`. That works for first-class CloakBrowser support,+but it makes browser type mutually exclusive. The next architecture should let+one PinchTab server know about multiple browser targets and select one per+request, per instance, or by fallback policy.++This spec uses "browser target" to mean a named runnable browser backend such as+`chrome-local`, `cloak-us`, or `lightpanda-fast`. A target has a provider type,+launch or attach settings, profile storage, capabilities, and health state.++## Goals++- Configure multiple browser targets in one PinchTab config.+- Keep a default browser target for existing clients.+- Let requests select a target explicitly when they need one.+- Let PinchTab fall back to another configured target when startup or+ acquisition fails.+- Support multiple targets of the same provider type.+- Support future provider types with different capability surfaces, including+ lightweight browsers such as Lightpanda-style runtimes.+- Preserve the current Chrome behavior when no multi-target config is present.++## Non-Goals++- Do not make PinchTab download third-party browser binaries at runtime.+- Do not silently move an existing tab from one browser target to another.+- Do not fallback after a request has already performed page side effects unless+ the request explicitly opts into retry semantics.+- Do not require every browser provider to support every endpoint.++## Configuration++Introduce named targets under `browser.targets`. Keep current single-provider+fields as a compatibility shorthand that migrates to a target named `default`.++Example:++```json+{+ "browser": {+ "defaultTarget": "chrome-local",+ "fallbackOrder": ["cloak-primary", "chrome-local"],+ "targets": {+ "chrome-local": {+ "provider": "chrome",+ "binary": "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",+ "modes": ["headless", "headed"]+ },+ "cloak-primary": {+ "provider": "cloak",+ "binary": "/opt/cloakbrowser/chrome",+ "modes": ["headless"],+ "cloak": {+ "fingerprintSeed": "42069",+ "platform": "linux",+ "locale": "en-US",+ "timezone": "UTC",+ "disableDefaultStealthArgs": true+ }+ },+ "lightpanda-fast": {+ "provider": "lightpanda",+ "binary": "/usr/local/bin/lightpanda",+ "modes": ["headless"],+ "capabilityOverrides": {+ "extensions": false,+ "pdf": false+ }+ }+ }+ }+}+```++Rules:++- `browser.defaultTarget` is required once `browser.targets` is present.+- Target names are stable API identifiers. They must be lowercase, URL-safe,+ and not derived from binary paths.+- `browser.fallbackOrder` is optional. If absent, fallback is disabled unless a+ request supplies an explicit fallback list.+- Current `browser.provider`, `browser.binary`, `browser.extraFlags`, and+ `browser.cloak` remain valid and are interpreted as `browser.targets.default`+ during config load.+- Provider-specific blocks live inside each target, not globally.+- Profile directories are target-scoped:+ `profiles.baseDir/<target-name>/<profile-name>`.++## Request Selection++Add a canonical request option named `browserTarget`.++Examples:++```http+POST /navigate+{+ "url": "https://example.com",+ "browserTarget": "cloak-primary"+}+```++```http+POST /instances/start+{+ "browserTarget": "lightpanda-fast",+ "mode": "headless"+}+```++Selection order:++1. If a request references an existing `tabId` or `instanceId`, the existing+ instance's browser target wins. A conflicting `browserTarget` is a `409`.+2. If `browserTarget` is present, resolve that named target.+3. If a request supplies a provider type such as `browserProvider=cloak`, resolve+ the configured default target for that provider only when unambiguous.+4. Otherwise use `browser.defaultTarget`.+5. If acquisition fails and fallback is enabled, walk the request fallback list+ first, then `browser.fallbackOrder`.++Surfaces:++- HTTP JSON bodies use `browserTarget`.+- HTTP query params may use `browserTarget` for GET-style endpoints.+- CLI can expose `--browser <target>` as the user-facing alias.+- MCP tools should expose `browserTarget` for explicitness.+- `/instances/start` should accept `browserTarget` because instances are the+ natural browser ownership boundary.++## Fallback++Fallback is only safe before a browser instance has performed request side+effects.++Fallback is allowed for:++- binary missing or not executable+- startup timeout+- CDP connect failure+- browser process exits during startup+- target unhealthy or in cooldown+- target lacks a required capability and the request allows capability fallback++Fallback is not allowed for:++- security policy denials+- IDPI or allowed-domain blocks+- auth/session failures+- existing `tabId` or `instanceId` requests+- action/navigation after the target page has already changed state, unless a+ future endpoint explicitly declares idempotent retry behavior++Request-level controls:++```json+{+ "url": "https://example.com",+ "browserTarget": "cloak-primary",+ "fallbackTargets": ["chrome-local"],+ "allowBrowserFallback": true+}+```++Response metadata should expose the actual target:++```json+{+ "tabId": "...",+ "url": "https://example.com",+ "browserTarget": "chrome-local",+ "browserProvider": "chrome",+ "fallbackFrom": "cloak-primary",+ "fallbackReason": "startup_timeout"+}+```++If fallback is disabled or exhausted, return a structured error:++```json+{+ "code": "browser_target_unavailable",+ "error": "browser target cloak-primary failed to start",+ "details": {+ "browserTarget": "cloak-primary",+ "browserProvider": "cloak",+ "reason": "startup_timeout",+ "fallbackTried": ["chrome-local"]+ }+}+```++## Capabilities++Each provider adapter declares a capability set. PinchTab uses capabilities to+route requests, decide fallback, and return clear unsupported-operation errors.++Initial capability names:++- `cdp`+- `headless`+- `headed`+- `persistentProfiles`+- `extensions`+- `domSnapshot`+- `actions`+- `evaluate`+- `cookies`+- `screenshots`+- `pdf`+- `upload`+- `download`+- `networkIntercept`+- `emulation`+- `nativeStealth`+- `remoteAttach`++Capability resolution:++- Provider adapters expose default capabilities.+- Runtime probes can downgrade capabilities when a binary is missing a feature.+- `capabilityOverrides` can disable capabilities for a target.+- Endpoint handlers declare required capabilities.+- If the selected target lacks a required capability, return `409+ browser_capability_unsupported` unless fallback is enabled and another target+ can satisfy the request.++This is what makes Lightpanda-style providers viable. A lightweight provider can+be configured beside Chrome and CloakBrowser, but only endpoints backed by its+declared capabilities are routed to it. Missing features should be explicit,+not discovered as late CDP errors.++## Provider Adapter Contract++Introduce a provider registry instead of hard-coding `chrome|cloak` in launch+paths.++Adapter responsibilities:++- validate target config+- resolve binary or remote endpoint+- report capabilities+- build launch args or remote attach config+- probe runtime health+- redact provider-specific secrets+- map provider-specific launch errors to normalized failure reasons++Sketch:++```go+type BrowserProvider interface {+ Type() string+ ValidateTarget(target BrowserTargetConfig) []error+ Capabilities(target BrowserTargetConfig) CapabilitySet+ BuildLaunchPlan(target BrowserTargetConfig, runtime RuntimeOptions) (LaunchPlan, error)+ Probe(ctx context.Context, target BrowserTargetConfig) (ProbeResult, error)+}+```++The first implementation can keep Chrome and CloakBrowser on the existing+chromedp allocator path. Future non-Chromium providers can either implement a+CDP-compatible adapter or force a larger engine abstraction when CDP is not+enough.++## Instance Model++Instances become target-bound:++- Every instance records `browserTarget` and `browserProvider`.+- `/instances` includes those fields.+- `/health` includes default target health and degraded target summaries.+- `/stealth/status` continues to report provider information for the active+ instance, and should add `browserTarget`.+- Tab lifecycle, leases, locks, handoff, and active-tab routing remain+ instance-scoped.++Auto-start behavior:++- `simple` strategy starts or reuses an instance for the selected target.+- `always-on` starts one default instance per configured always-on target.+- Allocation policy must never hand a request to an instance from a different+ target than the resolver selected.++## Security++Browser target selection is not a security bypass.++- Existing auth, sessions, IDPI, allowed domains, and endpoint capability gates+ still run after target selection.+- Fallback must not bypass a security block. A blocked navigation should stay+ blocked on every target.+- Agent/session policy can later restrict allowed targets per token or agent.+- Browser target names should be logged in activity and audit trails.+- Provider-specific secrets, especially proxy credentials, must be redacted.+- Hosted third-party browser targets require separate licensing and trust review+ before being documented as supported.++## Migration++Phase 1 keeps behavior identical:++- Existing config without `browser.targets` produces one target named `default`.+- Existing `browser.provider=chrome` remains the default.+- Existing tests for Chrome launch args stay unchanged.++Phase 2 adds named target config and request selection:++- Add config structs, validation, JSON schema, editor get/set, and dashboard UI.+- Add `browserTarget` request parsing to `/navigate`, `/instances/start`, and+ routes that can auto-acquire an instance.+- Add target fields to instance metadata and health output.++Phase 3 adds fallback:++- Add startup failure classification.+- Add target health/cooldown state.+- Add global and request-level fallback order.+- Add response metadata for fallback selection.++Phase 4 adds capability routing:++- Add provider capability declarations.+- Gate endpoint acquisition by required capabilities.+- Convert unsupported-provider failures into structured `409` responses.++Phase 5 adds future providers:++- Remote CDP-backed targets.+- Lightpanda-style lightweight targets with explicit partial capability support.+- Provider-specific E2E smoke lanes selected by capability rather than provider+ name.++## Open Questions++- Should `browserProvider=cloak` be accepted on requests, or should all requests+ use only target names to avoid ambiguity?+- Should fallback be opt-in per request, globally configured, or both?+- Should target-level security policy exist, or should security stay purely+ instance/request scoped?+- Should CLI defaults be `--browser <target>` only, or should commands also+ expose `--browser-provider <provider>`?+- How should target health be surfaced in dashboard without encouraging users to+ run every target all the time?diff --git a/docs/architecture/index.md b/docs/architecture/index.mdindex e4750fef..1c7bcd11 100644--- a/docs/architecture/index.md+++ b/docs/architecture/index.md@@ -22,6 +22,11 @@ PinchTab also supports an advanced attach path:The current managed implementation is bridge-backed. Any direct-CDP-only managed model is architectural discussion elsewhere, not the default runtime path in this codebase.+Related architecture specs:++- [Browser Targets](./browser-targets.md): proposed multi-browser target model for+ selecting Chrome, CloakBrowser, and future providers per request.+## System Overview```mermaiddiff --git a/docs/guides/cloakbrowser.md b/docs/guides/cloakbrowser.mdnew file mode 100644index 00000000..13d5389b--- /dev/null+++ b/docs/guides/cloakbrowser.md@@ -0,0 +1,296 @@+# CloakBrowser++Use this guide to run PinchTab with a CloakBrowser Chromium binary. PinchTab+stays the API and automation control plane. CloakBrowser supplies the browser+executable and native fingerprint patches.++```text+agent -> PinchTab API -> PinchTab bridge -> CloakBrowser Chromium+```++## What PinchTab Supports++PinchTab can launch a user-installed CloakBrowser binary with:++- `browser.provider=cloak`+- `browser.binary=/absolute/path/to/cloakbrowser/chrome`+- structured fingerprint settings under `browser.cloak`+- PinchTab profile directories, tab lifecycle, screenshots, snapshots, actions,+ downloads, uploads, clipboard, and evaluate endpoints+- `/stealth/status` reporting for the active provider, native Cloak mode, and+ PinchTab overlay status++When CloakBrowser native stealth is enabled, PinchTab disables overlapping+PinchTab JavaScript stealth overlays and automation-hiding launch flags by+default. PinchTab still controls browser lifecycle, user data directories,+headless/headed mode, remote debugging, tab limits, and action humanization.++PinchTab does not bundle CloakBrowser in release binaries, npm packages,+Homebrew formulae, or the default published Docker image.++## Licensing++CloakBrowser has two relevant pieces:++- wrapper packages and source code+- the compiled CloakBrowser Chromium binary++The wrapper source is MIT licensed. The compiled Chromium binary has a separate+license. Do not vendor, copy, or redistribute that binary in PinchTab release+artifacts or public Docker images unless the license explicitly permits that+use.++The safe default is: install or download CloakBrowser yourself, then point+PinchTab at that local binary path.++Review:++- [CloakBrowser repository](https://github.com/CloakHQ/CloakBrowser)+- [CloakBrowser binary license](https://github.com/CloakHQ/CloakBrowser/blob/main/BINARY-LICENSE.md)++## Install CloakBrowser++Install CloakBrowser through one of its official package paths, then use the+reported Chromium binary path as PinchTab's `browser.binary`.++Python:++```bash+pip install cloakbrowser+python -m cloakbrowser install+python -m cloakbrowser info+```++JavaScript:++```bash+npm install cloakbrowser playwright-core+node -e "import('cloakbrowser').then(async m => { await m.ensureBinary(); console.log(m.binaryInfo()); })"+```++Use an absolute path to the `chrome` executable reported by the installer.++## Configure PinchTab++Create or update your PinchTab config:++```bash+pinchtab config init+pinchtab config set browser.provider cloak+pinchtab config set browser.binary /absolute/path/to/cloakbrowser/chrome+pinchtab config set browser.cloak.fingerprintSeed 42069+pinchtab config set browser.cloak.platform windows+pinchtab config set browser.cloak.timezone Europe/London+pinchtab config set browser.cloak.locale en-GB+```++Example config fragment:++```json+{+ "browser": {+ "provider": "cloak",+ "binary": "/absolute/path/to/cloakbrowser/chrome",+ "cloak": {+ "fingerprintSeed": "42069",+ "platform": "windows",+ "timezone": "Europe/London",+ "locale": "en-GB",+ "webrtcIP": "auto",+ "disableDefaultStealthArgs": true+ }+ },+ "instanceDefaults": {+ "mode": "headless",+ "humanize": true+ }+}+```++Use a fixed `browser.cloak.fingerprintSeed` when revisiting the same site from+the same profile. Keep `browser.cloak.disableDefaultStealthArgs` set to `true`+unless you intentionally want to layer PinchTab's legacy stealth behavior over+CloakBrowser's native patches.++## Cloak Options++PinchTab maps these `browser.cloak` fields to CloakBrowser launch flags:++| Config field | Launch flag |+| --- | --- |+| `fingerprintSeed` | `--fingerprint=<seed>` |+| `platform` | `--fingerprint-platform=<windows|macos|linux>` |+| `timezone` | `--fingerprint-timezone=<iana timezone>` |+| `locale` | `--fingerprint-locale=<locale>` |+| `webrtcIP` | `--fingerprint-webrtc-ip=<ip|auto>` |+| `fontsDir` | `--fingerprint-fonts-dir=<path>` |+| `storageQuotaMB` | `--fingerprint-storage-quota=<mb>` |++Use `browser.extraFlags` only for advanced CloakBrowser flags that do not have a+structured PinchTab field.++```json+{+ "browser": {+ "provider": "cloak",+ "binary": "/absolute/path/to/cloakbrowser/chrome",+ "cloak": {+ "fingerprintSeed": "42069",+ "timezone": "Europe/London",+ "locale": "en-GB"+ },+ "extraFlags": "--fingerprint-brand=Chrome"+ }+}+```++Be conservative with raw flags. PinchTab owns lifecycle flags such as remote+debugging port, user data dir, headless mode, window size, extension paths, and+user agent.++## Start PinchTab++Start the server:++```bash+pinchtab server+```++In another shell, check that the server is healthy and can drive a page:++```bash+pinchtab health+pinchtab nav https://example.com --snap+```++If your security policy blocks public navigation, add the exact host to+`security.allowedDomains` before using a public URL.++## Verify CloakBrowser Is Active++Check `/stealth/status` after the managed browser instance starts:++```bash+TOKEN="$(pinchtab config get server.token)"+curl -sS -H "Authorization: Bearer ${TOKEN}" \+ http://127.0.0.1:9867/stealth/status+```++Look for these fields:++```json+{+ "provider": "cloak",+ "native": true,+ "pinchtabOverlaysDisabled": true,+ "fingerprintSeed": "42069"+}+```++If launch fails, inspect the instance:++```bash+pinchtab instances+pinchtab instance logs <instance-id>+```++Common causes:++- the configured binary path does not exist+- the binary is not executable+- the CloakBrowser binary was downloaded for a different operating system+- the profile directory is locked by another browser process+- a raw extra flag conflicts with PinchTab-owned lifecycle behavior++## Docker++The published `pinchtab/pinchtab` and `ghcr.io/pinchtab/pinchtab` images include+Alpine Chromium. They do not include CloakBrowser.++For local Docker use with CloakBrowser, build the dedicated local image:++```bash+docker build \+ -f tests/tools/docker/cloakbrowser-smoke.Dockerfile \+ -t pinchtab-cloakbrowser:local \+ .+```++Create a config that points PinchTab at the CloakBrowser binary inside that+image:++```json+{+ "server": {+ "bind": "0.0.0.0",+ "port": "9867",+ "token": "replace-me",+ "stateDir": "/data"+ },+ "browser": {+ "provider": "cloak",+ "binary": "/opt/cloakbrowser/chrome",+ "cloak": {+ "fingerprintSeed": "42069",+ "platform": "linux",+ "timezone": "UTC",+ "locale": "en-US",+ "disableDefaultStealthArgs": true+ }+ },+ "instanceDefaults": {+ "mode": "headless",+ "humanize": true+ },+ "profiles": {+ "baseDir": "/data/profiles",+ "defaultProfile": "default"+ }+}+```++Run the container with the config mounted read-only:++```bash+docker run -d \+ --name pinchtab-cloak \+ -p 127.0.0.1:9867:9867 \+ --shm-size=2g \+ -v pinchtab-cloak-data:/data \+ -v "$PWD/pinchtab-cloak.json":/config/pinchtab.json:ro \+ -e PINCHTAB_CONFIG=/config/pinchtab.json \+ pinchtab-cloakbrowser:local+```++Do not publish or push a CloakBrowser-bundled image unless the CloakBrowser+binary license explicitly permits redistribution for your use case.++## Maintainer Validation++Project maintainers can validate the Docker integration with:++```bash+./dev smoke cloakbrowser+```++That command builds the same dedicated local image, starts PinchTab with+`browser.provider=cloak`, verifies `/stealth/status`, and runs the+Cloak-compatible API scenario set against the container.++## Security++CloakBrowser changes browser fingerprint behavior. It does not change PinchTab's+security model.++Keep these rules:++- leave PinchTab bound to localhost unless you intentionally operate a secured+ remote deployment+- keep `server.token` set when reachable outside localhost+- keep `security.allowedDomains` narrow+- do not expose CDP endpoints publicly+- do not use automation against systems you do not own or have authorization to+ test++If a target site blocks automation, treat that as a policy and reliability+signal, not just a technical obstacle.diff --git a/docs/guides/contributing.md b/docs/guides/contributing.mdindex 561b5872..79580b8e 100644--- a/docs/guides/contributing.md+++ b/docs/guides/contributing.md@@ -253,7 +253,7 @@ go tool cover -html=coverage.out # View coverage./dev e2e # Run the default extended E2E suite./dev e2e basic # Run API + CLI + Infra basic tests./dev e2e smoke # Run smoke scenarios + host Docker smoke checks-./dev e2e smoke-docker # Run host Docker smoke checks only+./dev smoke cloakbrowser # Run opt-in CloakBrowser Docker smoke image./dev e2e api # Run API basic tests./dev e2e cli # Run CLI basic tests./dev e2e infra # Run Infra basic tests@@ -291,7 +291,7 @@ All dev scripts are accessible through `./dev`:| `e2e` | Run the default extended E2E suite || `e2e basic` | Run the PR E2E suite (`api` + `cli` + `infra` basic tests) || `e2e smoke` | Run smoke scenarios plus host Docker smoke checks |-| `e2e smoke-docker` | Run only host Docker smoke checks |+| `smoke cloakbrowser` | Run opt-in CloakBrowser Docker smoke using `tests/tools/docker/cloakbrowser-smoke.Dockerfile` || `e2e api` | Run API basic tests || `e2e cli` | Run CLI basic tests || `e2e infra` | Run Infra basic tests |diff --git a/docs/index.json b/docs/index.jsonindex 13dbf555..7304309d 100644--- a/docs/index.json+++ b/docs/index.json@@ -13,6 +13,7 @@"guides/contributing.md","guides/security.md","guides/mcp-agents.md",+ "guides/cloakbrowser.md","guides/attach-chrome.md","guides/remote-bridge-orchestrator.md","guides/tailscale-bridge-orchestrator.md",diff --git a/docs/reference/config.md b/docs/reference/config.mdindex dc2eb90c..3da172d6 100644--- a/docs/reference/config.md+++ b/docs/reference/config.md@@ -181,9 +181,21 @@ Current nested file-config shape:"cookieSecure": null},"browser": {+ "provider": "chrome","version": "144.0.7559.133","binary": "/path/to/chrome",+ "remoteDebuggingPort": null,"extraFlags": "--disable-gpu",+ "cloak": {+ "fingerprintSeed": "42069",+ "platform": "windows",+ "locale": "en-GB",+ "timezone": "Europe/London",+ "webrtcIP": "auto",+ "fontsDir": "/path/to/fonts",+ "storageQuotaMB": 2048,+ "disableDefaultStealthArgs": true+ },"extensionPaths": ["/path/to/pinchtab/extensions"]},"instanceDefaults": {@@ -342,6 +354,38 @@ The dashboard Settings page exposes the non-secret AutoSolver settings andshows the active config file path. Provider keys remain managed directly in theconfig file.+### Browser Provider++`browser.provider` selects the local browser backend:++- `chrome` is the default and uses the normal Chrome/Chromium launch path.+- `cloak` uses a user-installed CloakBrowser Chromium binary from `browser.binary`.++When `browser.provider` is `cloak`, `browser.binary` must point at the local+CloakBrowser Chromium executable. PinchTab does not download, bundle, or+redistribute the CloakBrowser binary.++`browser.cloak` maps supported CloakBrowser fingerprint settings to native launch+flags:++- `fingerprintSeed` -> `--fingerprint`+- `platform` -> `--fingerprint-platform`+- `locale` -> `--fingerprint-locale`+- `timezone` -> `--fingerprint-timezone`+- `webrtcIP` -> `--fingerprint-webrtc-ip`+- `fontsDir` -> `--fingerprint-fonts-dir`+- `storageQuotaMB` -> `--fingerprint-storage-quota`++`disableDefaultStealthArgs` defaults to true for native Cloak mode. In that mode,+PinchTab keeps its process, profile, tab, extension, and action-control behavior,+but does not add its own JS stealth overlays or automation-hiding launch flags on+top of CloakBrowser's native patches.++Advanced CloakBrowser flags can still go through `browser.extraFlags` when they+are not PinchTab-owned lifecycle flags.++### Browser Extra Flags+`browser.extraFlags` is validated and sanitized. It is only for user-safe Chrome flags that do not weaken browser security and do not override PinchTab-owned launch behavior.Rejected examples include:diff --git a/internal/bridge/bridge_lifecycle.go b/internal/bridge/bridge_lifecycle.goindex 7e980a1a..78b9e3b0 100644--- a/internal/bridge/bridge_lifecycle.go+++ b/internal/bridge/bridge_lifecycle.go@@ -55,6 +55,9 @@ func (b *Bridge) applyTargetStealth(ctx context.Context) {if b == nil || b.Config == nil {return}+ if config.NativeCloakStealthEnabled(b.Config) {+ return+ }ua := ""if b.StealthBundle != nil {@@ -69,8 +72,10 @@ func (b *Bridge) applyTargetStealth(ctx context.Context) {}func (b *Bridge) tabSetup(ctx context.Context) {- b.applyTargetStealth(ctx)- b.installWorkerStealthParity(ctx)+ if !config.NativeCloakStealthEnabled(b.Config) {+ b.applyTargetStealth(ctx)+ b.installWorkerStealthParity(ctx)+ }b.injectStealth(ctx)if b.Config.NoAnimations {if err := b.InjectNoAnimations(ctx); err != nil {diff --git a/internal/bridge/runtime/init.go b/internal/bridge/runtime/init.goindex d6e6329f..e1d6bbf7 100644--- a/internal/bridge/runtime/init.go+++ b/internal/bridge/runtime/init.go@@ -49,6 +49,9 @@ func InitChrome(cfg *config.RuntimeConfig, bundle *stealth.Bundle, hooks Hooks)}slog.Info("starting chrome initialization", "headless", cfg.Headless, "profile", cfg.ProfileDir, "binary", cfg.ChromeBinary)+ if config.IsCloakBrowserProvider(cfg.BrowserProvider) && strings.TrimSpace(cfg.ChromeBinary) == "" {+ return nil, nil, nil, nil, stealth.LaunchModeUninitialized, missingBrowserBinaryError(cfg)+ }bundle = ensureStealthBundle(cfg, bundle)allocCtx, allocCancel, opts, debugPort := setupAllocator(cfg, bundle, hooks)@@ -152,6 +155,7 @@ func setupAllocator(cfg *config.RuntimeConfig, bundle *stealth.Bundle, hooks Hoo}opts = appendExecAllocatorFlags(opts, BaseChromeFlagArgs())opts = appendExecAllocatorFlags(opts, bundle.Launch.Args)+ opts = appendExecAllocatorFlags(opts, cloakBrowserFlagArgs(cfg))chromeBinary := cfg.ChromeBinaryif chromeBinary == "" {@@ -289,10 +293,7 @@ func startChromeWithRecovery(parentCtx context.Context, cfg *config.RuntimeConfi}if err := chromedp.Run(browserCtx, chromedp.ActionFunc(func(ctx context.Context) error {- if err := stealth.ApplyTargetEmulation(ctx, cfg, bundle.LaunchUserAgent()); err != nil {- return err- }- return injectedScript(ctx, bundle.Script)+ return applyStartupStealth(ctx, cfg, bundle, bundle.Script)})); err != nil {browserCancel()allocCancel()@@ -332,7 +333,7 @@ func startChromeWithRemoteAllocator(parentCtx context.Context, cfg *config.RuntichromeBinary = findChromeBinary()}if chromeBinary == "" {- return nil, nil, stealth.LaunchModeUninitialized, fmt.Errorf("chrome/chromium not found: please install chrome or chromium, or set 'binary' in config.json")+ return nil, nil, stealth.LaunchModeUninitialized, missingBrowserBinaryError(cfg)}args := buildChromeArgsWithBundle(cfg, bundle, debugPort)@@ -366,10 +367,7 @@ func startChromeWithRemoteAllocator(parentCtx context.Context, cfg *config.RuntibrowserCtx, browserCancel := chromedp.NewContext(remoteAllocCtx)if err := chromedp.Run(browserCtx, chromedp.ActionFunc(func(ctx context.Context) error {- if err := stealth.ApplyTargetEmulation(ctx, cfg, bundle.LaunchUserAgent()); err != nil {- return err- }- return injectedScript(ctx, injectedStealthScript)+ return applyStartupStealth(ctx, cfg, bundle, injectedStealthScript)})); err != nil {browserCancel()remoteAllocCancel()@@ -486,6 +484,7 @@ func buildChromeArgsWithBundle(cfg *config.RuntimeConfig, bundle *stealth.Bundlebundle = ensureStealthBundle(cfg, bundle)args := append([]string{fmt.Sprintf("--remote-debugging-port=%d", port)}, BaseChromeFlagArgs()...)args = append(args, bundle.Launch.Args...)+ args = append(args, cloakBrowserFlagArgs(cfg)...)if validPaths := existingExtensionPaths(cfg.ExtensionPaths); len(validPaths) > 0 {joined := strings.Join(validPaths, ",")@@ -520,6 +519,53 @@ func buildChromeArgsWithBundle(cfg *config.RuntimeConfig, bundle *stealth.Bundlereturn appendChromeCompatibilityFlags(args)}+func cloakBrowserFlagArgs(cfg *config.RuntimeConfig) []string {+ if cfg == nil || !config.IsCloakBrowserProvider(cfg.BrowserProvider) {+ return nil+ }+ cloak := cfg.Cloak+ args := []string{}+ add := func(name, value string) {+ value = strings.TrimSpace(value)+ if value != "" {+ args = append(args, name+"="+value)+ }+ }+ add("--fingerprint", cloak.FingerprintSeed)+ add("--fingerprint-platform", cloak.Platform)+ add("--fingerprint-locale", cloak.Locale)+ add("--fingerprint-timezone", cloak.Timezone)+ add("--fingerprint-webrtc-ip", cloak.WebRTCIP)+ add("--fingerprint-fonts-dir", cloak.FontsDir)+ if cloak.StorageQuotaMB > 0 {+ args = append(args, "--fingerprint-storage-quota="+strconv.Itoa(cloak.StorageQuotaMB))+ }+ return args+}++func applyStartupStealth(ctx context.Context, cfg *config.RuntimeConfig, bundle *stealth.Bundle, script string) error {+ if !config.NativeCloakStealthEnabled(cfg) {+ ua := ""+ if bundle != nil {+ ua = bundle.LaunchUserAgent()+ }+ if err := stealth.ApplyTargetEmulation(ctx, cfg, ua); err != nil {+ return err+ }+ }+ if strings.TrimSpace(script) == "" {+ return nil+ }+ return injectedScript(ctx, script)+}++func missingBrowserBinaryError(cfg *config.RuntimeConfig) error {+ if cfg != nil && config.IsCloakBrowserProvider(cfg.BrowserProvider) {+ return fmt.Errorf("cloakbrowser binary not found: set browser.binary to the CloakBrowser Chromium binary when browser.provider is cloak")+ }+ return fmt.Errorf("chrome/chromium not found: please install chrome or chromium, or set 'binary' in config.json")+}+func injectedScript(ctx context.Context, script string) error {return chromedp.FromContext(ctx).Target.Execute(ctx,"Page.addScriptToEvaluateOnNewDocument",diff --git a/internal/bridge/runtime/init_test.go b/internal/bridge/runtime/init_test.goindex 0bd9105d..fc9c6652 100644--- a/internal/bridge/runtime/init_test.go+++ b/internal/bridge/runtime/init_test.go@@ -6,6 +6,9 @@ import ("fmt""os""testing"++ "github.com/pinchtab/pinchtab/internal/config"+ "github.com/pinchtab/pinchtab/internal/stealth")func TestChromeNeedsNoSandbox(t *testing.T) {@@ -97,3 +100,87 @@ func TestShouldRetryChromeStartupWithDirectLaunch(t *testing.T) {})}}++func TestBuildChromeArgs_CloakProviderUsesNativeFingerprintFlags(t *testing.T) {+ cfg := &config.RuntimeConfig{+ BrowserProvider: config.BrowserProviderCloak,+ Cloak: config.CloakBrowserRuntimeConfig{+ FingerprintSeed: "42069",+ Platform: "windows",+ Locale: "en-GB",+ Timezone: "Europe/London",+ WebRTCIP: "auto",+ FontsDir: "/opt/fonts",+ StorageQuotaMB: 2048,+ DisableDefaultStealthArgs: true,+ },+ }++ args := BuildChromeArgs(cfg, 9222)+ for _, want := range []string{+ "--fingerprint=42069",+ "--fingerprint-platform=windows",+ "--fingerprint-locale=en-GB",+ "--fingerprint-timezone=Europe/London",+ "--fingerprint-webrtc-ip=auto",+ "--fingerprint-fonts-dir=/opt/fonts",+ "--fingerprint-storage-quota=2048",+ } {+ if !stealth.HasLaunchArg(args, want) {+ t.Fatalf("BuildChromeArgs() missing %q in %v", want, args)+ }+ }+ for _, blocked := range []string{+ "--disable-automation",+ "--enable-automation=false",+ "--disable-blink-features=AutomationControlled",+ "--enable-network-information-downlink-max",+ } {+ if stealth.HasLaunchArg(args, blocked) {+ t.Fatalf("BuildChromeArgs() included PinchTab stealth arg %q in native Cloak mode: %v", blocked, args)+ }+ }+ if stealth.HasLaunchArgPrefix(args, "--user-agent=") {+ t.Fatalf("BuildChromeArgs() included PinchTab user-agent override in native Cloak mode: %v", args)+ }+}++func TestBuildChromeArgs_DefaultChromeProviderKeepsChromeLaunchContract(t *testing.T) {+ cfg := &config.RuntimeConfig{+ BrowserProvider: config.BrowserProviderChrome,+ ChromeVersion: "144.0.0.0",+ ExtensionPaths: []string{},+ }++ args := BuildChromeArgs(cfg, 9222)+ for _, want := range []string{+ "--remote-debugging-port=9222",+ "--disable-background-networking",+ "--disable-automation",+ "--enable-automation=false",+ "--disable-blink-features=AutomationControlled",+ "--enable-network-information-downlink-max",+ "--lang=en-US",+ "--disable-extensions",+ } {+ if !stealth.HasLaunchArg(args, want) {+ t.Fatalf("BuildChromeArgs() missing Chrome provider arg %q in %v", want, args)+ }+ }+ if !stealth.HasLaunchArgPrefix(args, "--user-agent=Mozilla/5.0") {+ t.Fatalf("BuildChromeArgs() missing Chrome provider user-agent in %v", args)+ }+ for _, blockedPrefix := range []string{+ "--fingerprint=",+ "--fingerprint-platform=",+ "--fingerprint-locale=",+ "--fingerprint-timezone=",+ "--fingerprint-webrtc-ip=",+ "--fingerprint-fonts-dir=",+ "--fingerprint-storage-quota=",+ } {+ if stealth.HasLaunchArgPrefix(args, blockedPrefix) {+ t.Fatalf("BuildChromeArgs() included Cloak flag prefix %q in Chrome provider mode: %v", blockedPrefix, args)+ }+ }+}diff --git a/internal/bridge/worker_stealth.go b/internal/bridge/worker_stealth.goindex 74e686f4..817824c1 100644--- a/internal/bridge/worker_stealth.go+++ b/internal/bridge/worker_stealth.go@@ -10,6 +10,7 @@ import ("github.com/chromedp/cdproto/target""github.com/chromedp/chromedp"+ "github.com/pinchtab/pinchtab/internal/config""github.com/pinchtab/pinchtab/internal/stealth")@@ -17,6 +18,9 @@ func (b *Bridge) installWorkerStealthParity(ctx context.Context) {if b == nil || b.Config == nil {return}+ if config.NativeCloakStealthEnabled(b.Config) {+ return+ }chromedp.ListenTarget(ctx, func(ev any) {attached, ok := ev.(*target.EventAttachedToTarget)@@ -34,6 +38,10 @@ func (b *Bridge) installWorkerStealthParity(ctx context.Context) {}func (b *Bridge) applyWorkerStealth(parent context.Context, targetID target.ID, targetType string) {+ if b == nil || config.NativeCloakStealthEnabled(b.Config) {+ return+ }+workerCtx, cancel := chromedp.NewContext(parent, chromedp.WithTargetID(targetID))defer cancel()diff --git a/internal/config/browser_provider.go b/internal/config/browser_provider.gonew file mode 100644index 00000000..bca2b11e--- /dev/null+++ b/internal/config/browser_provider.go@@ -0,0 +1,38 @@+package config++import "strings"++const (+ BrowserProviderChrome = "chrome"+ BrowserProviderCloak = "cloak"+)++func NormalizeBrowserProvider(provider string) string {+ switch strings.ToLower(strings.TrimSpace(provider)) {+ case BrowserProviderCloak:+ return BrowserProviderCloak+ default:+ return BrowserProviderChrome+ }+}++func IsCloakBrowserProvider(provider string) bool {+ return NormalizeBrowserProvider(provider) == BrowserProviderCloak+}++func NativeCloakStealthEnabled(cfg *RuntimeConfig) bool {+ return cfg != nil &&+ IsCloakBrowserProvider(cfg.BrowserProvider) &&+ cfg.Cloak.DisableDefaultStealthArgs+}++func hasCloakBrowserConfig(c CloakBrowserConfig) bool {+ return c.FingerprintSeed != "" ||+ c.Platform != "" ||+ c.Locale != "" ||+ c.Timezone != "" ||+ c.WebRTCIP != "" ||+ c.FontsDir != "" ||+ c.StorageQuotaMB != nil ||+ c.DisableDefaultStealthArgs != nil+}diff --git a/internal/config/config_file.go b/internal/config/config_file.goindex 20cbd0d4..89c111b9 100644--- a/internal/config/config_file.go+++ b/internal/config/config_file.go@@ -169,6 +169,7 @@ func DefaultFileConfig() FileConfig {StateDir: userConfigDir(),},Browser: BrowserConfig{+ Provider: BrowserProviderChrome,ChromeVersion: "144.0.7559.133",ExtensionPaths: []string{defaultExtensionsDir(userConfigDir())},},diff --git a/internal/config/config_file_json.go b/internal/config/config_file_json.goindex 34afe3ca..857e7457 100644--- a/internal/config/config_file_json.go+++ b/internal/config/config_file_json.go@@ -30,11 +30,24 @@ type serverConfigJSON struct {}type browserConfigJSON struct {- ChromeVersion string `json:"version"`- ChromeBinary string `json:"binary"`- ChromeDebugPort *int `json:"remoteDebuggingPort,omitempty"`- ChromeExtraFlags string `json:"extraFlags"`- ExtensionPaths []string `json:"extensionPaths"`+ Provider string `json:"provider"`+ ChromeVersion string `json:"version"`+ ChromeBinary string `json:"binary"`+ ChromeDebugPort *int `json:"remoteDebuggingPort,omitempty"`+ ChromeExtraFlags string `json:"extraFlags"`+ Cloak *cloakBrowserConfigJSON `json:"cloak,omitempty"`+ ExtensionPaths []string `json:"extensionPaths"`+}++type cloakBrowserConfigJSON struct {+ FingerprintSeed string `json:"fingerprintSeed,omitempty"`+ Platform string `json:"platform,omitempty"`+ Locale string `json:"locale,omitempty"`+ Timezone string `json:"timezone,omitempty"`+ WebRTCIP string `json:"webrtcIP,omitempty"`+ FontsDir string `json:"fontsDir,omitempty"`+ StorageQuotaMB *int `json:"storageQuotaMB,omitempty"`+ DisableDefaultStealthArgs *bool `json:"disableDefaultStealthArgs,omitempty"`}type instanceDefaultsConfigJSON struct {diff --git a/internal/config/config_file_marshal.go b/internal/config/config_file_marshal.goindex f9958a0a..f1fb2f02 100644--- a/internal/config/config_file_marshal.go+++ b/internal/config/config_file_marshal.go@@ -23,6 +23,82 @@ func intPtrIfPositive(v int) *int {return &n}+func intPtrIfNonNegative(v int) *int {+ if v < 0 {+ return nil+ }+ n := v+ return &n+}++func boolPtrValue(v bool) *bool {+ b := v+ return &b+}++func browserProviderForFile(provider string) string {+ if provider == "" {+ return BrowserProviderChrome+ }+ return provider+}++func cloakBrowserConfigJSONFromFile(provider string, c CloakBrowserConfig) *cloakBrowserConfigJSON {+ if !hasCloakBrowserConfig(c) {+ return nil+ }+ if !IsCloakBrowserProvider(provider) &&+ c.FingerprintSeed == "" &&+ c.Platform == "" &&+ c.Locale == "" &&+ c.Timezone == "" &&+ c.WebRTCIP == "" &&+ c.FontsDir == "" &&+ c.StorageQuotaMB == nil {+ return nil+ }+ return &cloakBrowserConfigJSON{+ FingerprintSeed: c.FingerprintSeed,+ Platform: c.Platform,+ Locale: c.Locale,+ Timezone: c.Timezone,+ WebRTCIP: c.WebRTCIP,+ FontsDir: c.FontsDir,+ StorageQuotaMB: c.StorageQuotaMB,+ DisableDefaultStealthArgs: c.DisableDefaultStealthArgs,+ }+}++func cloakBrowserConfigFromRuntime(cfg *RuntimeConfig) CloakBrowserConfig {+ if cfg == nil {+ return CloakBrowserConfig{}+ }+ c := cfg.Cloak+ hasRuntimeCloak := IsCloakBrowserProvider(cfg.BrowserProvider) ||+ c.FingerprintSeed != "" ||+ c.Platform != "" ||+ c.Locale != "" ||+ c.Timezone != "" ||+ c.WebRTCIP != "" ||+ c.FontsDir != "" ||+ c.StorageQuotaMB > 0+ out := CloakBrowserConfig{+ FingerprintSeed: c.FingerprintSeed,+ Platform: c.Platform,+ Locale: c.Locale,+ Timezone: c.Timezone,+ WebRTCIP: c.WebRTCIP,+ FontsDir: c.FontsDir,+ }+ if c.StorageQuotaMB > 0 {+ out.StorageQuotaMB = intPtrIfNonNegative(c.StorageQuotaMB)+ }+ if hasRuntimeCloak {+ out.DisableDefaultStealthArgs = boolPtrValue(c.DisableDefaultStealthArgs)+ }+ return out+}+// tabPolicyDefaultsFromRuntime emits a TabPolicyDefaults block when the runtime// config carries any non-default tab-policy setting (lifecycle, close delay, or// restore). Returns nil for a fully vanilla config so round-tripping doesn't@@ -69,10 +145,12 @@ func (fc FileConfig) MarshalJSON() ([]byte, error) {CookieSecure: fc.Server.CookieSecure,},Browser: browserConfigJSON{+ Provider: browserProviderForFile(fc.Browser.Provider),ChromeVersion: fc.Browser.ChromeVersion,ChromeBinary: fc.Browser.ChromeBinary,ChromeDebugPort: fc.Browser.ChromeDebugPort,ChromeExtraFlags: fc.Browser.ChromeExtraFlags,+ Cloak: cloakBrowserConfigJSONFromFile(fc.Browser.Provider, fc.Browser.Cloak),ExtensionPaths: copyStringSlice(fc.Browser.ExtensionPaths),},InstanceDefaults: instanceDefaultsConfigJSON{@@ -329,10 +407,12 @@ func FileConfigFromRuntime(cfg *RuntimeConfig) FileConfig {CookieSecure: cfg.CookieSecure,},Browser: BrowserConfig{+ Provider: NormalizeBrowserProvider(cfg.BrowserProvider),ChromeVersion: cfg.ChromeVersion,ChromeBinary: cfg.ChromeBinary,ChromeDebugPort: intPtrIfPositive(cfg.ChromeDebugPort),ChromeExtraFlags: cfg.ChromeExtraFlags,+ Cloak: cloakBrowserConfigFromRuntime(cfg),ExtensionPaths: append([]string(nil), cfg.ExtensionPaths...),},InstanceDefaults: InstanceDefaultsConfig{diff --git a/internal/config/config_file_test.go b/internal/config/config_file_test.goindex 42195532..1298988e 100644--- a/internal/config/config_file_test.go+++ b/internal/config/config_file_test.go@@ -21,6 +21,9 @@ func TestDefaultFileConfig(t *testing.T) {if fc.Server.CookieSecure != nil {t.Errorf("DefaultFileConfig.Server.CookieSecure = %v, want nil for auto-detect", formatBoolPtr(fc.Server.CookieSecure))}+ if fc.Browser.Provider != BrowserProviderChrome {+ t.Errorf("DefaultFileConfig.Browser.Provider = %v, want %s", fc.Browser.Provider, BrowserProviderChrome)+ }if fc.InstanceDefaults.Mode != "headless" {t.Errorf("DefaultFileConfig.InstanceDefaults.Mode = %v, want headless", fc.InstanceDefaults.Mode)}@@ -432,6 +435,12 @@ func TestFileConfigJSONPreservesExplicitZeroValues(t *testing.T) {}browser := raw["browser"].(map[string]any)+ if provider, ok := browser["provider"]; !ok || provider != BrowserProviderChrome {+ t.Fatalf("browser.provider = %#v, want chrome", provider)+ }+ if _, ok := browser["cloak"]; ok {+ t.Fatal("browser.cloak should not be emitted for default chrome provider")+ }if ext, ok := browser["extensionPaths"]; !ok {t.Fatal("browser.extensionPaths missing from JSON")} else if items, ok := ext.([]any); !ok || len(items) != 0 {@@ -476,6 +485,39 @@ func TestFileConfigJSONPreservesExplicitZeroValues(t *testing.T) {}}+func TestFileConfigJSONEmitsCloakBrowserConfig(t *testing.T) {+ disableDefaultStealthArgs := true+ fc := DefaultFileConfig()+ fc.Browser.Provider = BrowserProviderCloak+ fc.Browser.ChromeBinary = "/opt/cloakbrowser/chrome"+ fc.Browser.Cloak = CloakBrowserConfig{+ FingerprintSeed: "42069",+ Platform: "windows",+ DisableDefaultStealthArgs: &disableDefaultStealthArgs,+ }++ data, err := json.Marshal(fc)+ if err != nil {+ t.Fatalf("json.Marshal(FileConfig) error = %v", err)+ }++ var raw map[string]any+ if err := json.Unmarshal(data, &raw); err != nil {+ t.Fatalf("json.Unmarshal(FileConfig JSON) error = %v", err)+ }+ browser := raw["browser"].(map[string]any)+ cloak, ok := browser["cloak"].(map[string]any)+ if !ok {+ t.Fatal("browser.cloak missing from JSON")+ }+ if cloak["fingerprintSeed"] != "42069" {+ t.Fatalf("browser.cloak.fingerprintSeed = %#v, want 42069", cloak["fingerprintSeed"])+ }+ if cloak["platform"] != "windows" {+ t.Fatalf("browser.cloak.platform = %#v, want windows", cloak["platform"])+ }+}+func boolPtr(b bool) *bool {return &b}diff --git a/internal/config/config_load.go b/internal/config/config_load.goindex dc3d312b..1dd7f6db 100644--- a/internal/config/config_load.go+++ b/internal/config/config_load.go@@ -82,8 +82,10 @@ func Load() *RuntimeConfig {BlockAds: false,MaxTabs: 20,MaxParallelTabs: 0,+ BrowserProvider: BrowserProviderChrome,ChromeBinary: "", // Set via config.json onlyChromeExtraFlags: "",+ Cloak: CloakBrowserRuntimeConfig{DisableDefaultStealthArgs: true},ExtensionPaths: []string{defaultExtensionsDir(userConfigDir())},UserAgent: "",NoAnimations: false,@@ -405,6 +407,12 @@ func applyFileConfig(cfg *RuntimeConfig, fc *FileConfig) {}// Browser+ if fc.Browser.Provider != "" {+ cfg.BrowserProvider = NormalizeBrowserProvider(fc.Browser.Provider)+ if IsCloakBrowserProvider(cfg.BrowserProvider) && fc.Browser.Cloak.DisableDefaultStealthArgs == nil {+ cfg.Cloak.DisableDefaultStealthArgs = true+ }+ }if fc.Browser.ChromeVersion != "" {cfg.ChromeVersion = fc.Browser.ChromeVersion}@@ -417,6 +425,7 @@ func applyFileConfig(cfg *RuntimeConfig, fc *FileConfig) {if fc.Browser.ChromeExtraFlags != "" {cfg.ChromeExtraFlags = SanitizeChromeExtraFlags(fc.Browser.ChromeExtraFlags)}+ applyCloakBrowserConfigToRuntime(cfg, fc.Browser.Cloak)if fc.Browser.ExtensionPaths != nil {cfg.ExtensionPaths = append([]string(nil), fc.Browser.ExtensionPaths...)}@@ -642,3 +651,33 @@ func ApplyFileConfigToRuntime(cfg *RuntimeConfig, fc *FileConfig) {applyFileConfig(cfg, fc)finalizeProfileConfig(cfg)}++func applyCloakBrowserConfigToRuntime(cfg *RuntimeConfig, cloak CloakBrowserConfig) {+ if cfg == nil {+ return+ }+ if cloak.FingerprintSeed != "" {+ cfg.Cloak.FingerprintSeed = cloak.FingerprintSeed+ }+ if cloak.Platform != "" {+ cfg.Cloak.Platform = cloak.Platform+ }+ if cloak.Locale != "" {+ cfg.Cloak.Locale = cloak.Locale+ }+ if cloak.Timezone != "" {+ cfg.Cloak.Timezone = cloak.Timezone+ }+ if cloak.WebRTCIP != "" {+ cfg.Cloak.WebRTCIP = cloak.WebRTCIP+ }+ if cloak.FontsDir != "" {+ cfg.Cloak.FontsDir = cloak.FontsDir+ }+ if cloak.StorageQuotaMB != nil {+ cfg.Cloak.StorageQuotaMB = *cloak.StorageQuotaMB+ }+ if cloak.DisableDefaultStealthArgs != nil {+ cfg.Cloak.DisableDefaultStealthArgs = *cloak.DisableDefaultStealthArgs+ }+}diff --git a/internal/config/config_load_test.go b/internal/config/config_load_test.goindex 54d9cb74..9d9defb6 100644--- a/internal/config/config_load_test.go+++ b/internal/config/config_load_test.go@@ -53,6 +53,12 @@ func TestLoadConfigDefaults(t *testing.T) {if cfg.CookieSecure != nil {t.Errorf("default CookieSecure = %v, want nil for auto-detect", *cfg.CookieSecure)}+ if cfg.BrowserProvider != BrowserProviderChrome {+ t.Errorf("default BrowserProvider = %v, want %s", cfg.BrowserProvider, BrowserProviderChrome)+ }+ if !cfg.Cloak.DisableDefaultStealthArgs {+ t.Errorf("default Cloak.DisableDefaultStealthArgs = false, want true")+ }wantExtensionsDir := defaultExtensionsDir(userConfigDir())if len(cfg.ExtensionPaths) != 1 || cfg.ExtensionPaths[0] != wantExtensionsDir {t.Errorf("default ExtensionPaths = %v, want [%q]", cfg.ExtensionPaths, wantExtensionsDir)@@ -692,6 +698,58 @@ func TestApplyFileConfigToRuntime_SanitizesChromeExtraFlags(t *testing.T) {}}+func TestApplyFileConfigToRuntime_CloakBrowserSettings(t *testing.T) {+ quota := 2048+ disableDefaultStealthArgs := false+ cfg := &RuntimeConfig{Cloak: CloakBrowserRuntimeConfig{DisableDefaultStealthArgs: true}}+ fc := &FileConfig{+ Browser: BrowserConfig{+ Provider: BrowserProviderCloak,+ ChromeBinary: "/opt/cloakbrowser/chrome",+ Cloak: CloakBrowserConfig{+ FingerprintSeed: "42069",+ Platform: "windows",+ Locale: "en-GB",+ Timezone: "Europe/London",+ WebRTCIP: "auto",+ FontsDir: "/opt/fonts",+ StorageQuotaMB: "a,+ DisableDefaultStealthArgs: &disableDefaultStealthArgs,+ },+ },+ }++ ApplyFileConfigToRuntime(cfg, fc)++ if cfg.BrowserProvider != BrowserProviderCloak {+ t.Fatalf("BrowserProvider = %q, want %q", cfg.BrowserProvider, BrowserProviderCloak)+ }+ if cfg.ChromeBinary != "/opt/cloakbrowser/chrome" {+ t.Fatalf("ChromeBinary = %q, want configured binary", cfg.ChromeBinary)+ }+ if cfg.Cloak.FingerprintSeed != "42069" ||+ cfg.Cloak.Platform != "windows" ||+ cfg.Cloak.Locale != "en-GB" ||+ cfg.Cloak.Timezone != "Europe/London" ||+ cfg.Cloak.WebRTCIP != "auto" ||+ cfg.Cloak.FontsDir != "/opt/fonts" ||+ cfg.Cloak.StorageQuotaMB != quota ||+ cfg.Cloak.DisableDefaultStealthArgs {+ t.Fatalf("Cloak settings not applied: %+v", cfg.Cloak)+ }++ defaultCfg := &RuntimeConfig{}+ ApplyFileConfigToRuntime(defaultCfg, &FileConfig{+ Browser: BrowserConfig{+ Provider: BrowserProviderCloak,+ ChromeBinary: "/opt/cloakbrowser/chrome",+ },+ })+ if !defaultCfg.Cloak.DisableDefaultStealthArgs {+ t.Fatal("Cloak.DisableDefaultStealthArgs = false for cloak provider with no override, want true")+ }+}+func TestApplyFileConfigToRuntime_AutoSolverSettings(t *testing.T) {cfg := &RuntimeConfig{}enabled := truediff --git a/internal/config/config_types.go b/internal/config/config_types.goindex 5ee27a67..95481afd 100644--- a/internal/config/config_types.go+++ b/internal/config/config_types.go@@ -60,6 +60,7 @@ type RuntimeConfig struct {BlockAds boolMaxTabs intMaxParallelTabs int // 0 = auto-detect from runtime.NumCPU+ BrowserProvider stringChromeBinary stringChromeDebugPort intChromeExtraFlags string@@ -71,6 +72,7 @@ type RuntimeConfig struct {// state) rather than a fresh isolated profile. Cleanup never kills the// external Chrome β pinchtab only owns the CDP connection.CDPAttachURL string+ Cloak CloakBrowserRuntimeConfigExtensionPaths []stringUserAgent stringNoAnimations bool@@ -293,11 +295,35 @@ type DashboardSessionFileConfig struct {}type BrowserConfig struct {- ChromeVersion string `json:"version,omitempty"`- ChromeBinary string `json:"binary,omitempty"`- ChromeDebugPort *int `json:"remoteDebuggingPort,omitempty"`- ChromeExtraFlags string `json:"extraFlags,omitempty"`- ExtensionPaths []string `json:"extensionPaths,omitempty"`+ Provider string `json:"provider,omitempty"`+ ChromeVersion string `json:"version,omitempty"`+ ChromeBinary string `json:"binary,omitempty"`+ ChromeDebugPort *int `json:"remoteDebuggingPort,omitempty"`+ ChromeExtraFlags string `json:"extraFlags,omitempty"`+ Cloak CloakBrowserConfig `json:"cloak,omitempty"`+ ExtensionPaths []string `json:"extensionPaths,omitempty"`+}++type CloakBrowserConfig struct {+ FingerprintSeed string `json:"fingerprintSeed,omitempty"`+ Platform string `json:"platform,omitempty"`+ Locale string `json:"locale,omitempty"`+ Timezone string `json:"timezone,omitempty"`+ WebRTCIP string `json:"webrtcIP,omitempty"`+ FontsDir string `json:"fontsDir,omitempty"`+ StorageQuotaMB *int `json:"storageQuotaMB,omitempty"`+ DisableDefaultStealthArgs *bool `json:"disableDefaultStealthArgs,omitempty"`+}++type CloakBrowserRuntimeConfig struct {+ FingerprintSeed string+ Platform string+ Locale string+ Timezone string+ WebRTCIP string+ FontsDir string+ StorageQuotaMB int+ DisableDefaultStealthArgs bool}type InstanceDefaultsConfig struct {diff --git a/internal/config/editor_get.go b/internal/config/editor_get.goindex 1ca2fa2c..c2a8d5e1 100644--- a/internal/config/editor_get.go+++ b/internal/config/editor_get.go@@ -60,7 +60,12 @@ func getServerField(s *ServerConfig, field string) (string, error) {}func getBrowserField(b *BrowserConfig, field string) (string, error) {+ if strings.HasPrefix(field, "cloak.") {+ return getCloakBrowserField(&b.Cloak, strings.TrimPrefix(field, "cloak."))+ }switch field {+ case "provider":+ return b.Provider, nilcase "version":return b.ChromeVersion, nilcase "binary":@@ -72,6 +77,29 @@ func getBrowserField(b *BrowserConfig, field string) (string, error) {}}+func getCloakBrowserField(c *CloakBrowserConfig, field string) (string, error) {+ switch field {+ case "fingerprintSeed":+ return c.FingerprintSeed, nil+ case "platform":+ return c.Platform, nil+ case "locale":+ return c.Locale, nil+ case "timezone":+ return c.Timezone, nil+ case "webrtcIP":+ return c.WebRTCIP, nil+ case "fontsDir":+ return c.FontsDir, nil+ case "storageQuotaMB":+ return formatIntPtr(c.StorageQuotaMB), nil+ case "disableDefaultStealthArgs":+ return formatBoolPtr(c.DisableDefaultStealthArgs), nil+ default:+ return "", fmt.Errorf("unknown field browser.cloak.%s", field)+ }+}+func getObservabilityField(o *ObservabilityFileConfig, field string) (string, error) {if strings.HasPrefix(field, "activity.") {return getActivityField(&o.Activity, strings.TrimPrefix(field, "activity."))diff --git a/internal/config/editor_get_test.go b/internal/config/editor_get_test.goindex 956d5265..b1e7a208 100644--- a/internal/config/editor_get_test.go+++ b/internal/config/editor_get_test.go@@ -21,8 +21,17 @@ func TestGetConfigValue_RoundTrip(t *testing.T) {{"observability.activity.retentionDays", "14", "14"},{"observability.activity.events.dashboard", "true", "true"},{"observability.activity.events.mcp", "false", "false"},+ {"browser.provider", "cloak", "cloak"},{"browser.version", "120.0", "120.0"},{"browser.binary", "/usr/bin/chrome", "/usr/bin/chrome"},+ {"browser.cloak.fingerprintSeed", "42069", "42069"},+ {"browser.cloak.platform", "windows", "windows"},+ {"browser.cloak.locale", "en-GB", "en-GB"},+ {"browser.cloak.timezone", "Europe/London", "Europe/London"},+ {"browser.cloak.webrtcIP", "auto", "auto"},+ {"browser.cloak.fontsDir", "/opt/fonts", "/opt/fonts"},+ {"browser.cloak.storageQuotaMB", "2048", "2048"},+ {"browser.cloak.disableDefaultStealthArgs", "false", "false"},{"instanceDefaults.mode", "headed", "headed"},{"instanceDefaults.noRestore", "true", "true"},{"instanceDefaults.blockImages", "false", "false"},diff --git a/internal/config/editor_set.go b/internal/config/editor_set.goindex 8de3622c..32f0682d 100644--- a/internal/config/editor_set.go+++ b/internal/config/editor_set.go@@ -74,7 +74,12 @@ func setServerField(s *ServerConfig, field, value string) error {}func setBrowserField(b *BrowserConfig, field, value string) error {+ if strings.HasPrefix(field, "cloak.") {+ return setCloakBrowserField(&b.Cloak, strings.TrimPrefix(field, "cloak."), value)+ }switch field {+ case "provider":+ b.Provider = valuecase "version":b.ChromeVersion = valuecase "binary":@@ -87,6 +92,38 @@ func setBrowserField(b *BrowserConfig, field, value string) error {return nil}+func setCloakBrowserField(c *CloakBrowserConfig, field, value string) error {+ switch field {+ case "fingerprintSeed":+ c.FingerprintSeed = value+ case "platform":+ c.Platform = value+ case "locale":+ c.Locale = value+ case "timezone":+ c.Timezone = value+ case "webrtcIP":+ c.WebRTCIP = value+ case "fontsDir":+ c.FontsDir = value+ case "storageQuotaMB":+ n, err := strconv.Atoi(value)+ if err != nil {+ return fmt.Errorf("browser.cloak.storageQuotaMB must be a number: %w", err)+ }+ c.StorageQuotaMB = &n+ case "disableDefaultStealthArgs":+ b, err := parseBool(value)+ if err != nil {+ return fmt.Errorf("browser.cloak.disableDefaultStealthArgs must be true or false: %w", err)+ }+ c.DisableDefaultStealthArgs = &b+ default:+ return fmt.Errorf("unknown field browser.cloak.%s", field)+ }+ return nil+}+func setObservabilityField(o *ObservabilityFileConfig, field, value string) error {if strings.HasPrefix(field, "activity.") {return setActivityField(&o.Activity, strings.TrimPrefix(field, "activity."), value)diff --git a/internal/config/editor_set_test.go b/internal/config/editor_set_test.goindex 3e5851d6..1be502d3 100644--- a/internal/config/editor_set_test.go+++ b/internal/config/editor_set_test.go@@ -51,8 +51,16 @@ func TestSetConfigValue_BrowserAndInstanceDefaultsFields(t *testing.T) {check func(*FileConfig) boolwantErr bool}{+ {"browser.provider", "cloak", func(fc *FileConfig) bool { return fc.Browser.Provider == BrowserProviderCloak }, false},{"browser.version", "144.0.7559.133", func(fc *FileConfig) bool { return fc.Browser.ChromeVersion == "144.0.7559.133" }, false},{"browser.binary", "/tmp/chrome", func(fc *FileConfig) bool { return fc.Browser.ChromeBinary == "/tmp/chrome" }, false},+ {"browser.cloak.fingerprintSeed", "42069", func(fc *FileConfig) bool { return fc.Browser.Cloak.FingerprintSeed == "42069" }, false},+ {"browser.cloak.storageQuotaMB", "2048", func(fc *FileConfig) bool { return *fc.Browser.Cloak.StorageQuotaMB == 2048 }, false},+ {"browser.cloak.disableDefaultStealthArgs", "false", func(fc *FileConfig) bool {+ return fc.Browser.Cloak.DisableDefaultStealthArgs != nil && !*fc.Browser.Cloak.DisableDefaultStealthArgs+ }, false},+ {"browser.cloak.storageQuotaMB", "large", nil, true},+ {"browser.cloak.disableDefaultStealthArgs", "maybe", nil, true},{"instanceDefaults.mode", "headed", func(fc *FileConfig) bool { return fc.InstanceDefaults.Mode == "headed" }, false},{"instanceDefaults.maxTabs", "50", func(fc *FileConfig) bool { return *fc.InstanceDefaults.MaxTabs == 50 }, false},{"instanceDefaults.stealthLevel", "full", func(fc *FileConfig) bool { return fc.InstanceDefaults.StealthLevel == "full" }, false},diff --git a/internal/config/validate.go b/internal/config/validate.goindex 406456be..9f9b06fe 100644--- a/internal/config/validate.go+++ b/internal/config/validate.go@@ -48,6 +48,21 @@ func ValidateFileConfig(fc *FileConfig) []error {})}}++ if fc.Browser.Provider != "" && !isValidBrowserProvider(fc.Browser.Provider) {+ errs = append(errs, ValidationError{+ Field: "browser.provider",+ Message: fmt.Sprintf("invalid value %q (must be chrome or cloak)", fc.Browser.Provider),+ })+ }+ if IsCloakBrowserProvider(fc.Browser.Provider) && strings.TrimSpace(fc.Browser.ChromeBinary) == "" {+ errs = append(errs, ValidationError{+ Field: "browser.binary",+ Message: "must be set when browser.provider is cloak",+ })+ }+ errs = append(errs, validateCloakBrowserConfig(fc.Browser.Cloak)...)+if fc.MultiInstance.InstancePortStart != nil && fc.MultiInstance.InstancePortEnd != nil {if *fc.MultiInstance.InstancePortStart > *fc.MultiInstance.InstancePortEnd {errs = append(errs, ValidationError{@@ -346,6 +361,54 @@ func validateBind(bind string, field string) error {return nil}+func isValidBrowserProvider(provider string) bool {+ switch strings.ToLower(strings.TrimSpace(provider)) {+ case BrowserProviderChrome, BrowserProviderCloak:+ return true+ default:+ return false+ }+}++func validateCloakBrowserConfig(cloak CloakBrowserConfig) []error {+ var errs []error+ if cloak.Platform != "" && !isValidCloakPlatform(cloak.Platform) {+ errs = append(errs, ValidationError{+ Field: "browser.cloak.platform",+ Message: fmt.Sprintf("invalid value %q (must be windows, macos, or linux)", cloak.Platform),+ })+ }+ if cloak.StorageQuotaMB != nil && *cloak.StorageQuotaMB < 0 {+ errs = append(errs, ValidationError{+ Field: "browser.cloak.storageQuotaMB",+ Message: fmt.Sprintf("must be >= 0 (got %d)", *cloak.StorageQuotaMB),+ })+ }+ for field, value := range map[string]string{+ "browser.cloak.fingerprintSeed": cloak.FingerprintSeed,+ "browser.cloak.locale": cloak.Locale,+ "browser.cloak.timezone": cloak.Timezone,+ "browser.cloak.webrtcIP": cloak.WebRTCIP,+ } {+ if strings.ContainsAny(strings.TrimSpace(value), " \t\n\r") {+ errs = append(errs, ValidationError{+ Field: field,+ Message: "must not contain whitespace",+ })+ }+ }+ return errs+}++func isValidCloakPlatform(platform string) bool {+ switch strings.ToLower(strings.TrimSpace(platform)) {+ case "windows", "macos", "linux":+ return true+ default:+ return false+ }+}+func isValidStealthLevel(level string) bool {switch level {case "light", "medium", "full":diff --git a/internal/config/validate_test.go b/internal/config/validate_test.goindex de2257cd..4b1f4715 100644--- a/internal/config/validate_test.go+++ b/internal/config/validate_test.go@@ -470,6 +470,91 @@ func TestValidateFileConfig_ChromeExtraFlags(t *testing.T) {}}+func TestValidateFileConfig_CloakBrowser(t *testing.T) {+ quota := 2048+ valid := &FileConfig{+ Browser: BrowserConfig{+ Provider: BrowserProviderCloak,+ ChromeBinary: "/opt/cloakbrowser/chrome",+ Cloak: CloakBrowserConfig{+ FingerprintSeed: "42069",+ Platform: "windows",+ Locale: "en-GB",+ Timezone: "Europe/London",+ WebRTCIP: "auto",+ StorageQuotaMB: "a,+ },+ },+ }+ if errs := ValidateFileConfig(valid); len(errs) != 0 {+ t.Fatalf("ValidateFileConfig(valid cloak config) errors = %v, want none", errs)+ }++ negativeQuota := -1+ tests := []struct {+ name string+ fc *FileConfig+ want string+ }{+ {+ name: "invalid provider",+ fc: &FileConfig{Browser: BrowserConfig{Provider: "firefox"}},+ want: "browser.provider",+ },+ {+ name: "cloak requires binary",+ fc: &FileConfig{Browser: BrowserConfig{Provider: BrowserProviderCloak}},+ want: "browser.binary",+ },+ {+ name: "invalid platform",+ fc: &FileConfig{Browser: BrowserConfig{+ Provider: BrowserProviderCloak,+ ChromeBinary: "/opt/cloakbrowser/chrome",+ Cloak: CloakBrowserConfig{Platform: "ios"},+ }},+ want: "browser.cloak.platform",+ },+ {+ name: "negative storage quota",+ fc: &FileConfig{Browser: BrowserConfig{+ Provider: BrowserProviderCloak,+ ChromeBinary: "/opt/cloakbrowser/chrome",+ Cloak: CloakBrowserConfig{StorageQuotaMB: &negativeQuota},+ }},+ want: "browser.cloak.storageQuotaMB",+ },+ {+ name: "fingerprint seed whitespace",+ fc: &FileConfig{Browser: BrowserConfig{+ Provider: BrowserProviderCloak,+ ChromeBinary: "/opt/cloakbrowser/chrome",+ Cloak: CloakBrowserConfig{FingerprintSeed: "42 069"},+ }},+ want: "browser.cloak.fingerprintSeed",+ },+ }++ for _, tt := range tests {+ t.Run(tt.name, func(t *testing.T) {+ errs := ValidateFileConfig(tt.fc)+ if len(errs) == 0 {+ t.Fatalf("ValidateFileConfig() returned no errors, want %s", tt.want)+ }+ found := false+ for _, err := range errs {+ if strings.Contains(err.Error(), tt.want) {+ found = true+ break+ }+ }+ if !found {+ t.Fatalf("ValidateFileConfig() errors = %v, want field %s", errs, tt.want)+ }+ })+ }+}+func TestValidationError_Error(t *testing.T) {err := ValidationError{Field: "server.port",diff --git a/internal/schema/config.json b/internal/schema/config.jsonindex ed203501..a194ed99 100644--- a/internal/schema/config.json+++ b/internal/schema/config.json@@ -64,6 +64,17 @@"null"]},+ "nullableNonNegativeInteger": {+ "anyOf": [+ {+ "type": "integer",+ "minimum": 0+ },+ {+ "type": "null"+ }+ ]+ },"nullableString": {"type": ["string",@@ -204,6 +215,15 @@"type": "object","additionalProperties": false,"properties": {+ "provider": {+ "type": "string",+ "enum": [+ "",+ "chrome",+ "cloak"+ ],+ "default": "chrome"+ },"version": {"type": "string","default": "144.0.7559.133"@@ -217,11 +237,57 @@"extraFlags": {"type": "string"},+ "cloak": {+ "$ref": "#/definitions/cloakBrowser"+ },"extensionPaths": {"$ref": "#/definitions/stringArray"}}},+ "cloakBrowser": {+ "type": "object",+ "additionalProperties": false,+ "properties": {+ "fingerprintSeed": {+ "type": "string",+ "pattern": "^\\S*$",+ "description": "Deterministic CloakBrowser fingerprint seed. Empty lets CloakBrowser generate a fresh identity."+ },+ "platform": {+ "type": "string",+ "enum": [+ "",+ "windows",+ "macos",+ "linux"+ ]+ },+ "locale": {+ "type": "string",+ "pattern": "^\\S*$"+ },+ "timezone": {+ "type": "string",+ "pattern": "^\\S*$"+ },+ "webrtcIP": {+ "type": "string",+ "pattern": "^\\S*$",+ "description": "Explicit WebRTC replacement IP, or auto when CloakBrowser should resolve the proxy exit IP."+ },+ "fontsDir": {+ "type": "string"+ },+ "storageQuotaMB": {+ "$ref": "#/definitions/nullableNonNegativeInteger"+ },+ "disableDefaultStealthArgs": {+ "$ref": "#/definitions/nullableBoolean",+ "description": "When true, PinchTab does not add its JS stealth overlays or automation-hiding launch flags for CloakBrowser."+ }+ }+ },"instanceDefaults": {"type": "object","additionalProperties": false,diff --git a/internal/stealth/bundle.go b/internal/stealth/bundle.goindex bd1e58d7..144a7534 100644--- a/internal/stealth/bundle.go+++ b/internal/stealth/bundle.go@@ -35,6 +35,8 @@ const (type Bundle struct {Level Level `json:"level"`+ Provider string `json:"provider"`+ Native bool `json:"native"`Seed int64 `json:"seed"`Script string `json:"-"`ScriptHash string `json:"scriptHash"`@@ -46,27 +48,34 @@ type Bundle struct {}type Status struct {- Level Level `json:"level"`- Headless bool `json:"headless"`- LaunchMode LaunchMode `json:"launchMode"`- ScriptHash string `json:"scriptHash"`- UserAgent string `json:"userAgent,omitempty"`- WebdriverMode WebdriverMode `json:"webdriverMode"`- PatchIDs []string `json:"patchIds"`- Flags map[string]bool `json:"flags"`- Capabilities map[string]bool `json:"capabilities"`- Tradeoffs []string `json:"tradeoffs,omitempty"`- TabOverrides map[string]bool `json:"tabOverrides"`+ Level Level `json:"level"`+ Provider string `json:"provider"`+ Native bool `json:"native"`+ Headless bool `json:"headless"`+ LaunchMode LaunchMode `json:"launchMode"`+ ScriptHash string `json:"scriptHash"`+ UserAgent string `json:"userAgent,omitempty"`+ FingerprintSeed string `json:"fingerprintSeed,omitempty"`+ WebdriverMode WebdriverMode `json:"webdriverMode"`+ PinchTabOverlaysDisabled bool `json:"pinchtabOverlaysDisabled"`+ PatchIDs []string `json:"patchIds"`+ Flags map[string]bool `json:"flags"`+ Capabilities map[string]bool `json:"capabilities"`+ Tradeoffs []string `json:"tradeoffs,omitempty"`+ TabOverrides map[string]bool `json:"tabOverrides"`}func NewBundle(cfg *config.RuntimeConfig, seed int64) *Bundle {levelName := ""headless := false+ provider := config.BrowserProviderChromeif cfg != nil {levelName = cfg.StealthLevelheadless = cfg.Headless+ provider = config.NormalizeBrowserProvider(cfg.BrowserProvider)}level := NormalizeLevel(levelName)+ nativeCloak := config.NativeCloakStealthEnabled(cfg)personaJSON := "{}"if cfg != nil {if encoded, err := json.Marshal(BuildPersona(cfg.UserAgent, cfg.ChromeVersion)); err == nil {@@ -74,18 +83,31 @@ func NewBundle(cfg *config.RuntimeConfig, seed int64) *Bundle {}}script := renderBundleScript(level, personaJSON, seed, headless)+ hashSource := renderBundleScript(level, personaJSON, 0, headless)+ patchIDs := patchIDsForLevel(level, headless)+ capabilities := capabilityMap(level, headless)+ tradeoffIDs := tradeoffs(level)+ if nativeCloak {+ script = renderNativeCloakScript()+ hashSource = script+ patchIDs = nativeCloakPatchIDs()+ capabilities = nativeCloakCapabilityMap()+ tradeoffIDs = nil+ }return &Bundle{- Level: level,- Seed: seed,- Script: script,+ Level: level,+ Provider: provider,+ Native: nativeCloak,+ Seed: seed,+ Script: script,// Keep the status hash stable across identical configs even when the// per-process seed changes. The seed is runtime entropy, not contract.- ScriptHash: hashScript(renderBundleScript(level, personaJSON, 0, headless)),+ ScriptHash: hashScript(hashSource),Launch: BuildLaunchContract(cfg, level),- PatchIDs: patchIDsForLevel(level, headless),- Capabilities: capabilityMap(level, headless),- Tradeoffs: tradeoffs(level),+ PatchIDs: patchIDs,+ Capabilities: capabilities,+ Tradeoffs: tradeoffIDs,Webdriver: WebdriverModeNativeBaseline,}}@@ -102,6 +124,10 @@ func renderBundleScript(level Level, personaJSON string, seed int64, headless bo)}+func renderNativeCloakScript() string {+ return PopupGuardInitScript+}+func NormalizeLevel(level string) Level {switch strings.ToLower(strings.TrimSpace(level)) {case string(LevelMedium):@@ -119,16 +145,20 @@ func StatusFromBundle(bundle *Bundle, cfg *config.RuntimeConfig, launchMode Laun}status := &Status{- Level: bundle.Level,- Headless: cfg != nil && cfg.Headless,- LaunchMode: launchMode,- ScriptHash: bundle.ScriptHash,- UserAgent: bundle.LaunchUserAgent(),- WebdriverMode: bundle.Webdriver,- PatchIDs: append([]string(nil), bundle.PatchIDs...),- Flags: statusFlags(bundle, cfg),- Capabilities: cloneBoolMap(bundle.Capabilities),- Tradeoffs: append([]string(nil), bundle.Tradeoffs...),+ Level: bundle.Level,+ Provider: bundle.Provider,+ Native: bundle.Native,+ Headless: cfg != nil && cfg.Headless,+ LaunchMode: launchMode,+ ScriptHash: bundle.ScriptHash,+ UserAgent: bundle.LaunchUserAgent(),+ FingerprintSeed: statusFingerprintSeed(cfg),+ WebdriverMode: bundle.Webdriver,+ PinchTabOverlaysDisabled: bundle.Native,+ PatchIDs: append([]string(nil), bundle.PatchIDs...),+ Flags: statusFlags(bundle, cfg),+ Capabilities: cloneBoolMap(bundle.Capabilities),+ Tradeoffs: append([]string(nil), bundle.Tradeoffs...),TabOverrides: map[string]bool{"fingerprintRotateActive": false,},@@ -139,6 +169,13 @@ func StatusFromBundle(bundle *Bundle, cfg *config.RuntimeConfig, launchMode Launreturn status}+func statusFingerprintSeed(cfg *config.RuntimeConfig) string {+ if cfg == nil || !config.IsCloakBrowserProvider(cfg.BrowserProvider) {+ return ""+ }+ return cfg.Cloak.FingerprintSeed+}+func hashScript(script string) string {sum := sha256.Sum256([]byte(script))return fmt.Sprintf("sha256:%x", sum)@@ -264,6 +301,25 @@ func patchIDsForLevel(level Level, headless bool) []string {return patches}+func nativeCloakPatchIDs() []string {+ return []string{+ "native-cloakbrowser",+ "popup-guard",+ }+}++func nativeCloakCapabilityMap() map[string]bool {+ caps := capabilityMap(LevelLight, false)+ caps["nativeCloakBrowser"] = true+ caps["sourceLevelFingerprinting"] = true+ caps["pinchtabJSOverlays"] = false+ caps["canvasNoise"] = true+ caps["audioNoise"] = true+ caps["webglSpoofing"] = true+ caps["webrtcMitigation"] = true+ return caps+}+func tradeoffs(level Level) []string {switch level {case LevelMedium:diff --git a/internal/stealth/bundle_test.go b/internal/stealth/bundle_test.goindex a911a56e..658ff5c5 100644--- a/internal/stealth/bundle_test.go+++ b/internal/stealth/bundle_test.go@@ -149,3 +149,46 @@ func TestBuildLaunchContractOwnsStealthLaunchFlags(t *testing.T) {t.Fatalf("expected an explicit custom UA to pin --user-agent, got %v", custom.Args)}}++func TestNewBundleNativeCloakDisablesPinchTabStealthOverlays(t *testing.T) {+ cfg := &config.RuntimeConfig{+ BrowserProvider: config.BrowserProviderCloak,+ Cloak: config.CloakBrowserRuntimeConfig{+ FingerprintSeed: "42069",+ DisableDefaultStealthArgs: true,+ },+ StealthLevel: "full",+ Headless: true,+ }++ bundle := NewBundle(cfg, 1234)+ if bundle.Provider != config.BrowserProviderCloak {+ t.Fatalf("Provider = %q, want %q", bundle.Provider, config.BrowserProviderCloak)+ }+ if !bundle.Native {+ t.Fatal("expected native Cloak bundle")+ }+ if strings.Contains(bundle.Script, "__pinchtab_stealth_level") {+ t.Fatalf("native Cloak script should not include PinchTab JS stealth overlay")+ }+ if !strings.Contains(bundle.Script, "window.open") {+ t.Fatalf("native Cloak script should retain popup guard")+ }+ if len(bundle.Launch.Args) != 0 {+ t.Fatalf("native Cloak launch args = %v, want none", bundle.Launch.Args)+ }+ if !bundle.Launch.Flags["pinchtabStealthArgsDisabled"] {+ t.Fatalf("native Cloak launch flags = %v, want pinchtabStealthArgsDisabled", bundle.Launch.Flags)+ }++ status := StatusFromBundle(bundle, cfg, LaunchModeAllocator)+ if status.Provider != config.BrowserProviderCloak || !status.Native || !status.PinchTabOverlaysDisabled {+ t.Fatalf("status = %+v, want native cloak provider with overlays disabled", status)+ }+ if status.FingerprintSeed != "42069" {+ t.Fatalf("status FingerprintSeed = %q, want 42069", status.FingerprintSeed)+ }+ if !status.Capabilities["sourceLevelFingerprinting"] {+ t.Fatalf("status capabilities = %v, want sourceLevelFingerprinting", status.Capabilities)+ }+}diff --git a/internal/stealth/launch.go b/internal/stealth/launch.goindex b9db8af9..945c0d99 100644--- a/internal/stealth/launch.go+++ b/internal/stealth/launch.go@@ -12,6 +12,15 @@ type LaunchContract struct {}func BuildLaunchContract(cfg *config.RuntimeConfig, level Level) LaunchContract {+ if config.NativeCloakStealthEnabled(cfg) {+ return LaunchContract{+ Flags: map[string]bool{+ "nativeCloakBrowser": true,+ "pinchtabStealthArgsDisabled": true,+ },+ }+ }+persona := BrowserPersona{}customUA := ""headless := falsediff --git a/scripts/README.md b/scripts/README.mdindex 97183d17..a1cfe5f0 100644--- a/scripts/README.md+++ b/scripts/README.md@@ -27,6 +27,7 @@ Development and CI scripts for PinchTab.| `autosolver-realworld-smoke.sh` | Smoke-test real-world autosolver flow against an external detection page || `dev.sh` | Full build (dashboard + Go) and run || `dev-e2e.sh` | Lookup wrapper for `./dev e2e test`; delegates execution to the Go E2E runner |+| `docker-cloakbrowser-smoke.sh` | Docker CloakBrowser smoke using the dedicated local-only `tests/tools/docker/cloakbrowser-smoke.Dockerfile` image || `docker-smoke.sh` | Host Docker smoke helper invoked by the Go E2E runner || `npm-dev-binary.sh` | Build the canonical `./pinchtab-dev` binary for source-checkout npm-package testing || `run.sh` | Run the existing `./pinchtab` binary |@@ -48,5 +49,5 @@ Development and CI scripts for PinchTab.## `./dev` shortcuts- `./dev e2e smoke` runs the smoke tier through the Go e2e runner, including host Docker smoke checks.-- `./dev e2e smoke-docker` runs only the host Docker smoke suite through the Go e2e runner.-- `PINCHTAB_DOCKER_SMOKE_RELEASE_IMAGE=<image> ./dev e2e smoke-docker --filter release` skips the release-image build and runs the release-image Docker smoke checks against the specified image tag.+- `PINCHTAB_DOCKER_SMOKE_RELEASE_IMAGE=<image> ./dev e2e smoke --filter release` skips the release-image build and runs the matching Docker smoke checks against the specified image tag.+- `./dev smoke cloakbrowser [image]` runs the manual Docker CloakBrowser smoke. By default it builds `pinchtab-cloakbrowser:test` from `tests/tools/docker/cloakbrowser-smoke.Dockerfile`, which installs the CloakBrowser binary into that local image. The smoke mounts `/data` and `/tmp` as tmpfs for Chromium profile and socket paths, serves `tests/e2e/fixtures`, checks a representative endpoint subset, and runs the Cloak-compatible API basic E2E scenario files in the API runner container attached to the Cloak container's network namespace. Set `SKIP_BUILD=1` to require a prebuilt image, or set `PINCHTAB_CLOAKBROWSER_E2E_SCENARIOS` to override the scenario list.diff --git a/scripts/docker-cloakbrowser-smoke.sh b/scripts/docker-cloakbrowser-smoke.shnew file mode 100755index 00000000..1043b5ef--- /dev/null+++ b/scripts/docker-cloakbrowser-smoke.sh@@ -0,0 +1,439 @@+#!/usr/bin/env bash+set -euo pipefail++IMAGE="${1:-pinchtab-cloakbrowser:test}"+RUNNER_IMAGE="${PINCHTAB_CLOAKBROWSER_RUNNER_IMAGE:-pinchtab-e2e-runner-api:cloak-smoke}"+CLOAK_CONTAINER_BIN="/opt/cloakbrowser/chrome"+TOKEN="pinchtab-docker-cloak-smoke-${RANDOM}${RANDOM}"+NAME="pinchtab-docker-cloak-smoke-${RANDOM}${RANDOM}"+TMP_DIR="$(mktemp -d "${TMPDIR:-/tmp}/pinchtab-docker-cloak.XXXXXX")"+FIXTURES_PORT="${PINCHTAB_CLOAKBROWSER_FIXTURES_PORT:-}"+FIXTURES_HOST="${PINCHTAB_CLOAKBROWSER_FIXTURES_HOST:-cloak-fixtures.local}"+HOST_FIXTURES_URL=""+FIXTURES_URL=""+FAILED=0+CONTAINER_STARTED=0+FIXTURES_STARTED=0+HOST_PORT=""+API_RESULT=""+API_STATUS=""+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"+ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"+CLOAK_DOCKERFILE="${PINCHTAB_CLOAKBROWSER_DOCKERFILE:-tests/tools/docker/cloakbrowser-smoke.Dockerfile}"+RUNNER_DOCKERFILE="${PINCHTAB_CLOAKBROWSER_RUNNER_DOCKERFILE:-tests/e2e/runner-api/Dockerfile}"++cleanup() {+ set +e+ if [ "$CONTAINER_STARTED" -eq 1 ] && docker ps -a --format '{{.Names}}' | grep -Fxq "$NAME"; then+ if [ "$FAILED" -ne 0 ]; then+ echo ""+ echo "Container logs:"+ docker logs "$NAME" || true+ echo ""+ echo "Process list:"+ docker exec "$NAME" ps -eo pid,user,args || true+ if [ "$FIXTURES_STARTED" -eq 1 ]; then+ echo ""+ echo "Fixture server log:"+ docker exec "$NAME" sh -lc 'cat /tmp/pinchtab-fixtures.log 2>/dev/null || true' || true+ fi+ mkdir -p "$TMP_DIR/data"+ docker cp "$NAME:/data/." "$TMP_DIR/data/" >/dev/null 2>&1 || true+ if [ -n "${HOST_PORT:-}" ]; then+ echo ""+ echo "HTTP diagnostics:"+ echo "/autorestart/status:"+ curl -sS -H "Authorization: Bearer ${TOKEN}" "http://127.0.0.1:${HOST_PORT}/autorestart/status" || true+ echo ""+ echo "/instances:"+ instances_diag="$(curl -sS -H "Authorization: Bearer ${TOKEN}" "http://127.0.0.1:${HOST_PORT}/instances" || true)"+ echo "$instances_diag"+ echo "$instances_diag" | jq -r '.[].id? // empty' 2>/dev/null | while read -r inst_id; do+ [ -n "$inst_id" ] || continue+ echo ""+ echo "/instances/${inst_id}/logs:"+ curl -sS -H "Authorization: Bearer ${TOKEN}" "http://127.0.0.1:${HOST_PORT}/instances/${inst_id}/logs" || true+ echo ""+ done+ fi+ fi+ docker rm -f "$NAME" >/dev/null 2>&1 || true+ fi+ if [ "$FAILED" -ne 0 ]; then+ echo "Artifacts kept at: $TMP_DIR"+ else+ rm -rf "$TMP_DIR"+ fi+}+trap cleanup EXIT++skip() {+ echo "SKIP: $*"+ exit 77+}++fail() {+ FAILED=1+ echo "FAIL: $*" >&2+ exit 1+}++api_request() {+ local method="$1"+ local path="$2"+ local body="${3:-}"+ local url="http://127.0.0.1:${HOST_PORT}${path}"+ local -a args=(+ -sS+ -w $'\n%{http_code}'+ -X "$method"+ -H "Authorization: Bearer ${TOKEN}"+ )+ if [ "$method" = "POST" ]; then+ args+=(-H "Content-Type: application/json" -d "$body")+ fi++ local response+ if ! response="$(curl "${args[@]}" "$url" 2>&1)"; then+ fail "$method $path failed: $response"+ fi+ API_STATUS="${response##*$'\n'}"+ API_RESULT="${response%$'\n'*}"+ if [ "$API_STATUS" -lt 200 ] || [ "$API_STATUS" -ge 300 ]; then+ fail "$method $path failed with HTTP $API_STATUS: $API_RESULT"+ fi+}++api_get() {+ api_request GET "$1"+}++api_post() {+ api_request POST "$1" "$2"+}++assert_api_jq() {+ local expr="$1"+ local label="$2"+ echo "$API_RESULT" | jq -e "$expr" >/dev/null || fail "$label failed: $API_RESULT"+}++assert_file_min_bytes() {+ local path="$1"+ local min_bytes="$2"+ local label="$3"+ local bytes+ bytes="$(wc -c < "$path" | tr -d '[:space:]')"+ if [ "${bytes:-0}" -lt "$min_bytes" ]; then+ fail "$label too small: ${bytes:-0} bytes"+ fi+}++assert_screenshot_png() {+ local path="$1"+ local out="$TMP_DIR/screenshot.png"+ local headers="$TMP_DIR/screenshot.headers"+ curl -fsS \+ -D "$headers" \+ -o "$out" \+ -H "Authorization: Bearer ${TOKEN}" \+ "http://127.0.0.1:${HOST_PORT}${path}" || fail "GET $path failed"+ grep -qi '^content-type: image/png' "$headers" || fail "GET $path did not return image/png"+ assert_file_min_bytes "$out" 500 "screenshot"+}++choose_free_port() {+ python3 - <<'PY'+import socket++sock = socket.socket()+sock.bind(("127.0.0.1", 0))+print(sock.getsockname()[1])+sock.close()+PY+}++run_fixture_endpoint_smoke() {+ echo "Running fixture-backed CloakBrowser endpoint smoke..."++ api_post /navigate "{\"url\":\"${FIXTURES_URL}/index.html\",\"waitFor\":\"selector\",\"waitSelector\":\"#welcome\"}"+ assert_api_jq '.title | contains("Home")' "fixture home navigation title"+ assert_api_jq '.url | contains("index.html")' "fixture home navigation URL"+ local tab_id+ tab_id="$(echo "$API_RESULT" | jq -r '.tabId // empty')"+ [ -n "$tab_id" ] || fail "navigate response did not include tabId: $API_RESULT"++ api_get /tabs+ echo "$API_RESULT" | jq -e --arg tab "$tab_id" '.tabs | map(.id) | index($tab) != null' >/dev/null \+ || fail "tabs includes fixture tab failed: $API_RESULT"++ api_get "/snapshot?tabId=${tab_id}&filter=interactive"+ assert_api_jq '.nodes | length > 0' "snapshot returns nodes"++ api_get "/tabs/${tab_id}/text"+ assert_api_jq '.text | contains("Welcome to the E2E test fixtures")' "tab text includes fixture content"++ api_get "/tabs/${tab_id}/html?selector=%23welcome"+ assert_api_jq '.html | contains("Welcome to the E2E test fixtures")' "selected html includes fixture content"++ api_get "/tabs/${tab_id}/styles?selector=%23welcome&prop=display"+ assert_api_jq '.styles.display == "block"' "selected styles include display"++ assert_screenshot_png "/tabs/${tab_id}/screenshot?format=png&raw=true"++ api_post "/tabs/${tab_id}/navigate" "{\"url\":\"${FIXTURES_URL}/buttons.html\",\"waitFor\":\"selector\",\"waitSelector\":\"#increment\"}"+ assert_api_jq '.title | contains("Buttons")' "buttons navigation title"++ api_post "/tabs/${tab_id}/action" '{"kind":"click","selector":"#increment"}'+ assert_api_jq '.success == true' "click action succeeded"++ api_post "/tabs/${tab_id}/evaluate" '{"expression":"document.querySelector(\"#count\").textContent"}'+ assert_api_jq '.result == "1"' "evaluate sees click result"++ api_post "/tabs/${tab_id}/navigate" "{\"url\":\"${FIXTURES_URL}/form.html\",\"waitFor\":\"selector\",\"waitSelector\":\"#username\"}"+ assert_api_jq '.title | contains("Form")' "form navigation title"++ api_post "/tabs/${tab_id}/actions" '{"stopOnError":true,"actions":[{"kind":"fill","selector":"#username","text":"cloak_user"},{"kind":"check","selector":"#terms"}]}'+ assert_api_jq '.successful == 2 and .failed == 0' "batch actions succeeded"++ api_post "/tabs/${tab_id}/evaluate" '{"expression":"({username: document.querySelector(\"#username\").value, terms: document.querySelector(\"#terms\").checked})"}'+ assert_api_jq '.result.username == "cloak_user" and .result.terms == true' "evaluate sees batch action results"+}++run_e2e_scenarios() {+ local -a default_scenarios=(+ "actions-basic.sh"+ "browser-basic.sh"+ "clipboard-basic.sh"+ "console-basic.sh"+ "emulation-basic.sh"+ "files-basic.sh"+ "inspect-basic.sh"+ "tabs-basic.sh"+ )+ local -a scenarios=()+ local -a scenario_args=()++ if [ -n "${PINCHTAB_CLOAKBROWSER_E2E_SCENARIOS:-}" ]; then+ read -r -a scenarios <<< "${PINCHTAB_CLOAKBROWSER_E2E_SCENARIOS}"+ else+ scenarios=("${default_scenarios[@]}")+ fi++ for scenario in "${scenarios[@]}"; do+ [ -n "$scenario" ] || continue+ scenario_args+=("scenario=$scenario")+ done++ if [ "${#scenario_args[@]}" -eq 0 ]; then+ echo "Skipping API E2E scenarios because PINCHTAB_CLOAKBROWSER_E2E_SCENARIOS is empty."+ return+ fi++ echo "Running API E2E scenarios against CloakBrowser in Docker:"+ printf ' - %s\n' "${scenarios[@]}"++ docker run --rm \+ --network "container:${NAME}" \+ -v "$ROOT/tests/e2e":/e2e:ro \+ -e "FIXTURES_HOST=${FIXTURES_HOST}" \+ -e "E2E_SERVER=http://127.0.0.1:9867" \+ -e "E2E_SERVER_TOKEN=${TOKEN}" \+ -e "FIXTURES_URL=${FIXTURES_URL}" \+ -e "E2E_HELPER=api" \+ -e "E2E_SCENARIO_DIR=scenarios/api" \+ -e "E2E_REQUIRED_COMMANDS=curl jq" \+ -e "E2E_READY_TARGETS=E2E_SERVER|60|E2E_SERVER_TOKEN" \+ -e "E2E_SUMMARY_TITLE=CloakBrowser API E2E scenarios" \+ "$RUNNER_IMAGE" \+ /bin/sh -lc 'printf "127.0.0.1 %s\n" "$FIXTURES_HOST" >> /etc/hosts; exec /bin/bash /e2e/run.sh "$@"' \+ _ "${scenario_args[@]}" \+ || fail "API E2E scenarios failed"+}++command -v docker >/dev/null 2>&1 || skip "docker is not installed"+command -v python3 >/dev/null 2>&1 || fail "python3 is required to write the smoke config"+command -v jq >/dev/null 2>&1 || fail "jq is required to validate smoke responses"+command -v curl >/dev/null 2>&1 || fail "curl is required to run smoke requests"++if [ -z "$FIXTURES_PORT" ]; then+ FIXTURES_PORT="$(choose_free_port)"+fi+HOST_FIXTURES_URL="http://127.0.0.1:${FIXTURES_PORT}"+FIXTURES_URL="http://${FIXTURES_HOST}:${FIXTURES_PORT}"++if [ "${SKIP_BUILD:-}" = "1" ]; then+ if docker image inspect "$IMAGE" >/dev/null 2>&1; then+ echo "Using existing Docker image: $IMAGE (SKIP_BUILD=1)"+ else+ skip "Docker image $IMAGE not found and SKIP_BUILD=1 is set"+ fi+else+ echo "Building PinchTab CloakBrowser Docker image: $IMAGE"+ docker build -f "$ROOT/$CLOAK_DOCKERFILE" -t "$IMAGE" "$ROOT"+fi++if [ "${SKIP_RUNNER_BUILD:-}" = "1" ]; then+ if docker image inspect "$RUNNER_IMAGE" >/dev/null 2>&1; then+ echo "Using existing E2E runner image: $RUNNER_IMAGE (SKIP_RUNNER_BUILD=1)"+ else+ skip "E2E runner image $RUNNER_IMAGE not found and SKIP_RUNNER_BUILD=1 is set"+ fi+else+ echo "Building API E2E runner image: $RUNNER_IMAGE"+ docker build -f "$ROOT/$RUNNER_DOCKERFILE" -t "$RUNNER_IMAGE" "$ROOT/tests/e2e/runner-api"+fi++docker run --rm --entrypoint /bin/sh "$IMAGE" -lc "test -x '$CLOAK_CONTAINER_BIN'" \+ || fail "CloakBrowser binary not found in image at $CLOAK_CONTAINER_BIN; rebuild the dedicated CloakBrowser smoke image"++CONFIG_PATH="$TMP_DIR/pinchtab-cloak.json"+python3 - "$CONFIG_PATH" "$TOKEN" "$CLOAK_CONTAINER_BIN" "$FIXTURES_HOST" <<'PY'+import json+import sys++path, token, cloak_binary, fixtures_host = sys.argv[1:]+cfg = {+ "server": {+ "bind": "0.0.0.0",+ "port": "9867",+ "token": token,+ "stateDir": "/data",+ },+ "browser": {+ "provider": "cloak",+ "binary": cloak_binary,+ "extensionPaths": [],+ "cloak": {+ "fingerprintSeed": "42069",+ "platform": "linux",+ "locale": "en-US",+ "timezone": "UTC",+ "disableDefaultStealthArgs": True,+ },+ },+ "instanceDefaults": {+ "mode": "headless",+ "humanize": True,+ "maxTabs": 10,+ },+ "security": {+ "allowEvaluate": True,+ "allowDownload": True,+ "allowCookies": True,+ "allowUpload": True,+ "allowClipboard": True,+ "allowStateExport": True,+ "allowedDomains": [fixtures_host, "127.0.0.1", "localhost", "::1"],+ "downloadAllowedDomains": [fixtures_host],+ "trustedResolveCIDRs": ["127.0.0.1/32"],+ },+ "profiles": {+ "baseDir": "/data/profiles",+ "defaultProfile": "cloak-docker-smoke",+ },+}+with open(path, "w", encoding="utf-8") as fh:+ json.dump(cfg, fh, indent=2)+PY++docker run -d \+ --name "$NAME" \+ --user 1000:1000 \+ --shm-size=2g \+ --tmpfs /data:rw,size=1024m,uid=1000,gid=1000,mode=0755 \+ --tmpfs /tmp:rw,size=512m,mode=1777 \+ --add-host "${FIXTURES_HOST}:127.0.0.1" \+ -e PINCHTAB_CONFIG=/config/pinchtab-cloak.json \+ -v "$CONFIG_PATH":/config/pinchtab-cloak.json:ro \+ -v "$ROOT/tests/e2e/fixtures":/fixtures:ro \+ -v "$ROOT/tests/tools/fixtures/static-server.pl":/usr/local/bin/fixture-server.pl:ro \+ --publish 127.0.0.1::9867 \+ --publish "127.0.0.1:${FIXTURES_PORT}:${FIXTURES_PORT}" \+ "$IMAGE" >/dev/null+CONTAINER_STARTED=1++HOST_PORT="$(docker port "$NAME" 9867/tcp 2>/dev/null | head -1 | awk -F: '{print $NF}' || true)"+if [ -z "$HOST_PORT" ]; then+ HOST_PORT="$(docker inspect -f '{{with index .NetworkSettings.Ports "9867/tcp"}}{{(index . 0).HostPort}}{{end}}' "$NAME" 2>/dev/null || true)"+fi+if [ -z "$HOST_PORT" ]; then+ fail "failed to determine published host port"+fi++echo "Waiting for PinchTab+CloakBrowser container on port $HOST_PORT..."+docker exec "$NAME" sh -lc "FIXTURES_ROOT=/fixtures FIXTURES_PORT=${FIXTURES_PORT} /usr/bin/perl /usr/local/bin/fixture-server.pl >/tmp/pinchtab-fixtures.log 2>&1 &"+FIXTURES_STARTED=1++fixtures_ready=0+for _ in $(seq 1 30); do+ if curl -fsS "${HOST_FIXTURES_URL}/index.html" >/dev/null 2>&1 &&+ docker exec "$NAME" curl -fsS "${FIXTURES_URL}/index.html" >/dev/null 2>&1; then+ fixtures_ready=1+ break+ fi+ sleep 1+done+if [ "$fixtures_ready" -ne 1 ]; then+ fail "fixture server was not reachable from the PinchTab container at ${FIXTURES_URL}"+fi++health_ready=0+for _ in $(seq 1 90); do+ if curl -fsS -H "Authorization: Bearer ${TOKEN}" "http://127.0.0.1:${HOST_PORT}/health" >/dev/null 2>&1; then+ health_ready=1+ break+ fi+ sleep 1+done+if [ "$health_ready" -ne 1 ]; then+ health_body="$(curl -sS -H "Authorization: Bearer ${TOKEN}" "http://127.0.0.1:${HOST_PORT}/health" 2>&1 || true)"+ fail "health check did not pass: $health_body"+fi++uid="$(docker exec "$NAME" id -u | tr -d '\r')"+if [ "$uid" = "0" ]; then+ fail "container is running as root; expected non-root user"+fi++shm_mb="$(docker exec "$NAME" sh -lc "df -Pm /dev/shm | awk 'NR==2 {print \$2}'" | tr -d '\r')"+if [ "${shm_mb:-0}" -lt 1024 ]; then+ fail "/dev/shm is too small: ${shm_mb:-unknown} MB"+fi++docker exec "$NAME" sh -lc 'if command -v fc-list >/dev/null 2>&1; then fc-list | grep -q .; else find /usr/share/fonts -type f 2>/dev/null | head -1 | grep -q .; fi' || fail "no fonts found in container"++echo "Waiting for managed CloakBrowser instance..."+instance_ready=0+instances_body="[]"+autorestart_body="{}"+for _ in $(seq 1 120); do+ instances_body="$(curl -fsS -H "Authorization: Bearer ${TOKEN}" "http://127.0.0.1:${HOST_PORT}/instances" 2>/dev/null || echo "[]")"+ if echo "$instances_body" | jq -e '.[]? | select(.status == "running")' >/dev/null; then+ instance_ready=1+ break+ fi+ autorestart_body="$(curl -fsS -H "Authorization: Bearer ${TOKEN}" "http://127.0.0.1:${HOST_PORT}/autorestart/status" 2>/dev/null || echo "{}")"+ if echo "$autorestart_body" | jq -e '.status == "crashed"' >/dev/null 2>&1; then+ break+ fi+ sleep 1+done+if [ "$instance_ready" -ne 1 ]; then+ fail "managed CloakBrowser instance did not become running: instances=$instances_body autorestart=$autorestart_body"+fi++if ! status="$(curl -fsS -H "Authorization: Bearer ${TOKEN}" "http://127.0.0.1:${HOST_PORT}/stealth/status" 2>&1)"; then+ fail "stealth status request failed: $status"+fi+echo "$status" | jq -e '+ .provider == "cloak" and+ .native == true and+ .pinchtabOverlaysDisabled == true and+ .fingerprintSeed == "42069"+' >/dev/null || fail "unexpected stealth status: $status"++run_fixture_endpoint_smoke+run_e2e_scenarios++echo "Docker CloakBrowser smoke passed."diff --git a/tests/e2e/README.md b/tests/e2e/README.mdindex f5b2cc24..6afc318f 100644--- a/tests/e2e/README.md+++ b/tests/e2e/README.md@@ -11,7 +11,7 @@ End-to-end tests for PinchTab that exercise the full stack including browser aut./dev e2e basic # Run the basic suite (api + cli + infra basic tests)./dev e2e extended # Run the extended suite./dev e2e smoke # Run smoke scenarios plus host Docker smoke checks-./dev e2e smoke-docker # Run host Docker smoke checks only+./dev smoke cloakbrowser # Run opt-in CloakBrowser Docker smoke image./dev e2e api # Run API basic tests./dev e2e cli # Run CLI basic tests./dev e2e infra # Run infra basic tests@@ -26,7 +26,6 @@ Or directly through the Go runner:go run ./tests/tools/runner e2e --suite basicgo run ./tests/tools/runner e2e --suite extendedgo run ./tests/tools/runner e2e --suite smoke-go run ./tests/tools/runner e2e --suite smoke-dockergo run ./tests/tools/runner e2e --suite infra-extended --filter orchestrator```@@ -66,6 +65,19 @@ By default, tier comes from the filename suffix: `*-basic.sh` is `basic`, `*-smo- `extended` is deeper coverage: edge cases, detailed interaction checks, and tests that are useful before release. Extended suites include the matching `basic` scenarios plus `extended` scenarios for that group.- `smoke` is independent high-setup coverage: lifecycle, multi-instance, host Docker, and production-like checks that do not belong in PR flow. `./dev e2e smoke` runs only `*-smoke.sh` scenarios plus host Docker smoke checks; it does not include `basic` or `extended`.+CloakBrowser smoke checks need a Linux CloakBrowser binary and a compatible+PinchTab image, so they are exposed as the manual Docker smoke command+`./dev smoke cloakbrowser` instead of being included in the CI-backed+`./dev e2e smoke` suite. By default, the command builds+`tests/tools/docker/cloakbrowser-smoke.Dockerfile` into+`pinchtab-cloakbrowser:test` and uses tmpfs mounts for browser profile and+socket paths. The smoke reuses `tests/e2e/fixtures`, checks a representative+endpoint subset, and then invokes the existing E2E scenario executor in the API+runner container attached to the Cloak-backed container's network namespace for+the Cloak-compatible API basic scenario set. This uses the same+`tests/e2e/run.sh` API helper and assertion base as the normal Chrome API+suite, while keeping CloakBrowser out of CI by default.+### Adding A Scenario1. Add or update a grouped entrypoint under `tests/e2e/scenarios/api/`, `tests/e2e/scenarios/cli/`, `tests/e2e/scenarios/infra/`, or `tests/e2e/scenarios/plugin/`.diff --git a/tests/e2e/scenarios/api/inspect-basic.sh b/tests/e2e/scenarios/api/inspect-basic.shindex 2c326675..8bb7a5e0 100755--- a/tests/e2e/scenarios/api/inspect-basic.sh+++ b/tests/e2e/scenarios/api/inspect-basic.sh@@ -10,6 +10,7 @@ assert_ok "navigate to form.html"pt_get /snapshotassert_ok "snapshot to populate ref cache"+FORM_SNAPSHOT="$RESULT"# Extract refs for various elements we will inspect.# form.html has: textbox (username), textbox (email), textbox (password),@@ -135,9 +136,9 @@ end_teststart_test "inspect: password field values redacted in snapshot"# Type a value into the password field so there's something to redact.-PASS_REF=$(find_ref_by_role_and_name "textbox" "Password:" "$RESULT")+PASS_REF=$(find_ref_by_role_and_name "textbox" "Password:" "$FORM_SNAPSHOT")if [ -z "$PASS_REF" ] || [ "$PASS_REF" = "null" ]; then- PASS_REF=$(echo "$RESULT" | jq -r '[.nodes[] | select(.name | test("password";"i")) | .ref] | first // empty')+ PASS_REF=$(echo "$FORM_SNAPSHOT" | jq -r '[.nodes[] | select(.name | test("password";"i")) | .ref] | first // empty')fiif [ -n "$PASS_REF" ] && [ "$PASS_REF" != "null" ]; thendiff --git a/tests/tools/docker/cloakbrowser-smoke.Dockerfile b/tests/tools/docker/cloakbrowser-smoke.Dockerfilenew file mode 100644index 00000000..b425a2b2--- /dev/null+++ b/tests/tools/docker/cloakbrowser-smoke.Dockerfile@@ -0,0 +1,92 @@+# Local-only CloakBrowser smoke image.+#+# This Dockerfile intentionally lives outside the default Dockerfile so the main+# PinchTab image stays small and does not include the CloakBrowser binary.+# Do not publish images built from this Dockerfile unless the CloakBrowser+# binary license explicitly permits redistribution for your use case.++# Stage 1: Build the React dashboard with Bun.+FROM oven/bun:1 AS dashboard+WORKDIR /build+COPY dashboard/package.json dashboard/bun.lock ./+RUN bun install --frozen-lockfile+COPY dashboard/ .+RUN bun run build++# Stage 2: Compile the Go binary.+FROM golang:1.26-alpine AS builder+RUN apk add --no-cache git+WORKDIR /build+COPY go.mod go.sum ./+RUN go mod download+COPY . .+COPY --from=dashboard /build/dist/ internal/dashboard/dashboard/+RUN mv internal/dashboard/dashboard/index.html internal/dashboard/dashboard/dashboard.html+RUN go build -ldflags="-s -w" -o pinchtab ./cmd/pinchtab++# Stage 3: Download CloakBrowser through its official Python package.+FROM python:3.12-slim AS cloakbrowser-binary+ENV CLOAKBROWSER_CACHE_DIR=/cloak-cache \+ CLOAKBROWSER_AUTO_UPDATE=false \+ PYTHONUNBUFFERED=1+RUN python -m pip install --disable-pip-version-check --root-user-action=ignore --no-cache-dir cloakbrowser && \+ python - <<'PY'+import logging+from pathlib import Path+from shutil import copytree, rmtree+from cloakbrowser.download import ensure_binary++logging.basicConfig(level=logging.INFO, format="cloakbrowser: %(message)s")+print("Installing CloakBrowser Chromium binary into the local smoke image...", flush=True)+src = Path(ensure_binary()).parent+dst = Path("/opt/cloakbrowser")+if dst.exists():+ rmtree(dst)+copytree(src, dst, symlinks=True)+print(f"CloakBrowser Chromium binary ready at {dst / 'chrome'}", flush=True)+PY++# Stage 4: Runtime image with GNU/Linux userspace for CloakBrowser.+FROM debian:bookworm-slim++LABEL org.opencontainers.image.source="https://github.com/pinchtab/pinchtab"+LABEL org.opencontainers.image.description="PinchTab with local-only CloakBrowser runtime for smoke testing"++# Debian's glibc userspace lets the CloakBrowser Linux binary run; Alpine reports+# that binary as "not found" because the GNU dynamic loader is absent.+RUN apt-get update && apt-get install -y --no-install-recommends \+ ca-certificates \+ chromium \+ curl \+ dumb-init \+ fontconfig \+ fonts-liberation \+ fonts-noto-color-emoji \+ procps \+ && rm -rf /var/lib/apt/lists/*++# Non-root user; /data is the persistent volume mount point.+RUN groupadd --gid 1000 pinchtab && \+ useradd --uid 1000 --gid 1000 --home-dir /data --create-home --shell /usr/sbin/nologin pinchtab && \+ mkdir -p /data && \+ chown pinchtab:pinchtab /data++COPY --from=builder /build/pinchtab /usr/local/bin/pinchtab+COPY --from=cloakbrowser-binary /opt/cloakbrowser /opt/cloakbrowser+COPY --chmod=0755 docker-entrypoint.sh /usr/local/bin/docker-entrypoint.sh++USER pinchtab+WORKDIR /data++# HOME and XDG_CONFIG_HOME point into the persistent volume so config+# and Chrome profiles survive container restarts.+ENV HOME=/data \+ XDG_CONFIG_HOME=/data/.config++EXPOSE 9867++HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \+ CMD /bin/sh -lc 'pinchtab health >/dev/null' || exit 1++ENTRYPOINT ["/usr/bin/dumb-init", "--"]+CMD ["/usr/local/bin/docker-entrypoint.sh", "pinchtab", "server"]diff --git a/tests/tools/fixtures/static-server.pl b/tests/tools/fixtures/static-server.plnew file mode 100644index 00000000..3f1115c1--- /dev/null+++ b/tests/tools/fixtures/static-server.pl@@ -0,0 +1,102 @@+#!/usr/bin/env perl+use strict;+use warnings;+use IO::Socket::INET;++my $root = $ENV{FIXTURES_ROOT} || '/fixtures';+my $port = $ENV{FIXTURES_PORT} || 8080;++my $server = IO::Socket::INET->new(+ LocalAddr => '0.0.0.0',+ LocalPort => $port,+ Listen => 20,+ ReuseAddr => 1,+) or die "listen on $port: $!";++$| = 1;+print "fixture server listening on $port\n";++while (my $client = $server->accept) {+ $client->autoflush(1);+ my $request = <$client> || '';+ while (my $header = <$client>) {+ last if $header =~ /^\r?\n$/;+ }++ if ($request !~ m{^GET\s+([^ ]+)\s+HTTP/}i) {+ respond($client, 405, 'text/plain; charset=utf-8', 'method not allowed');+ next;+ }++ my $path = $1;+ $path =~ s/\?.*\z//;+ $path =~ s/%([0-9A-Fa-f]{2})/chr(hex($1))/eg;+ $path = '/index.html' if $path eq '/';++ if ($path eq '/redirect-to-internal') {+ redirect($client, 'http://127.0.0.1:9999/health');+ next;+ }++ if ($path =~ /\0/ || $path =~ m{(^|/)\.\.(/|\z)}) {+ respond($client, 403, 'text/plain; charset=utf-8', 'forbidden');+ next;+ }++ $path =~ s{^/+}{};+ my $file = "$root/$path";+ if (!-f $file) {+ respond($client, 404, 'text/plain; charset=utf-8', 'not found');+ next;+ }++ my $fh;+ if (!open $fh, '<:raw', $file) {+ respond($client, 500, 'text/plain; charset=utf-8', 'open failed');+ next;+ }+ local $/;+ my $body = <$fh>;+ close $fh;++ respond($client, 200, content_type($file), $body);+}++sub content_type {+ my ($file) = @_;+ return 'text/html; charset=utf-8' if $file =~ /\.html\z/;+ return 'text/plain; charset=utf-8' if $file =~ /\.txt\z/;+ return 'application/javascript; charset=utf-8' if $file =~ /\.js\z/;+ return 'text/css; charset=utf-8' if $file =~ /\.css\z/;+ return 'application/xml' if $file =~ /\.xml\z/;+ return 'application/gzip' if $file =~ /\.gz\z/;+ return 'application/octet-stream';+}++sub respond {+ my ($client, $status, $content_type, $body) = @_;+ my %reason = (+ 200 => 'OK',+ 302 => 'Found',+ 403 => 'Forbidden',+ 404 => 'Not Found',+ 405 => 'Method Not Allowed',+ 500 => 'Internal Server Error',+ );+ $body = '' if !defined $body;+ print {$client} "HTTP/1.1 $status " . ($reason{$status} || 'OK') . "\r\n";+ print {$client} "Content-Type: $content_type\r\n";+ print {$client} "Content-Length: " . length($body) . "\r\n";+ print {$client} "Connection: close\r\n\r\n";+ print {$client} $body;+ close $client;+}++sub redirect {+ my ($client, $location) = @_;+ print {$client} "HTTP/1.1 302 Found\r\n";+ print {$client} "Location: $location\r\n";+ print {$client} "Content-Length: 0\r\n";+ print {$client} "Connection: close\r\n\r\n";+ close $client;+}diff --git a/tests/tools/runner/internal/e2e/e2e.go b/tests/tools/runner/internal/e2e/e2e.goindex c8f4aca4..af88f5a3 100644--- a/tests/tools/runner/internal/e2e/e2e.go+++ b/tests/tools/runner/internal/e2e/e2e.go@@ -28,7 +28,7 @@ const usageText = `Usage:Options:--suite basic|extended|smoke|api|cli|infra|plugin|api-extended|cli-extended|infra-extended- smoke-orchestrator|smoke-security|smoke-lifecycle|smoke-docker+ smoke-orchestrator|smoke-security|smoke-lifecycle--filter TEXT Filter scenario file names, groups, tiers, helpers, or tags--test TEXT Run one start_test block by name--extra FILES Add extra scenario files, space-separated@@ -130,7 +130,7 @@ func normalizeSuite(raw string) (string, error) {return raw, nilcase "api", "cli", "infra", "plugin","api-extended", "cli-extended", "infra-extended",- "smoke", "smoke-orchestrator", "smoke-security", "smoke-lifecycle", "smoke-docker":+ "smoke", "smoke-orchestrator", "smoke-security", "smoke-lifecycle":return raw, nildefault:return "", fmt.Errorf("unknown suite %q", raw)diff --git a/tests/tools/runner/internal/e2e/e2e_test.go b/tests/tools/runner/internal/e2e/e2e_test.goindex e1804cba..dfe08c56 100644--- a/tests/tools/runner/internal/e2e/e2e_test.go+++ b/tests/tools/runner/internal/e2e/e2e_test.go@@ -609,7 +609,7 @@ func TestStructuredEventTeeFiltersHumanOutputOnly(t *testing.T) {func TestRejectsRemovedLegacyAliases(t *testing.T) {t.Setenv("E2E_LOGS", "")- for _, suite := range []string{"pr", "release", "all"} {+ for _, suite := range []string{"pr", "release", "all", "smoke-docker"} {var stdout, stderr bytes.Bufferif code := Run([]string{"--suite", suite, "--dry-run"}, &stdout, &stderr); code == 0 {t.Fatalf("Run should reject legacy alias %q, stdout: %s", suite, stdout.String())@@ -676,16 +676,17 @@ func TestDryRunSmokePlan(t *testing.T) {}}-func TestDryRunSmokeDockerPlan(t *testing.T) {+func TestDryRunSmokeFilterDockerPlan(t *testing.T) {t.Setenv("E2E_LOGS", "")var stdout, stderr bytes.Buffer- if code := Run([]string{"--suite", "smoke-docker", "--dry-run"}, &stdout, &stderr); code != 0 {+ if code := Run([]string{"--suite", "smoke", "--filter", "docker", "--dry-run"}, &stdout, &stderr); code != 0 {t.Fatalf("Run returned %d, stderr: %s", code, stderr.String())}out := stdout.String()for _, want := range []string{- "suite: smoke-docker",+ "suite: smoke",+ "filter: docker","== E2E Docker Smoke tests (host) ==","docker build --load -t pinchtab-release-smoke:dry-run .","docker build --load --platform linux/amd64 -f tests/tools/docker/chrome-cft-smoke.Dockerfile -t pinchtab-chrome-cft-smoke:dry-run .",@@ -699,15 +700,15 @@ func TestDryRunSmokeDockerPlan(t *testing.T) {}}if strings.Contains(out, "docker compose -f tests/e2e/docker-compose-multi.yml up") {- t.Fatalf("smoke-docker should not start the compose stack:\n%s", out)+ t.Fatalf("smoke --filter docker should not start the compose stack:\n%s", out)}}-func TestDryRunSmokeDockerFilterAddsImageBuildDependency(t *testing.T) {+func TestDryRunSmokeFilterMCPAddsImageBuildDependency(t *testing.T) {t.Setenv("E2E_LOGS", "")var stdout, stderr bytes.Buffer- if code := Run([]string{"--suite", "smoke-docker", "--filter", "mcp", "--dry-run"}, &stdout, &stderr); code != 0 {+ if code := Run([]string{"--suite", "smoke", "--filter", "mcp", "--dry-run"}, &stdout, &stderr); code != 0 {t.Fatalf("Run returned %d, stderr: %s", code, stderr.String())}out := stdout.String()diff --git a/tests/tools/runner/internal/e2e/runner.go b/tests/tools/runner/internal/e2e/runner.goindex 70d59e40..ad574e80 100644--- a/tests/tools/runner/internal/e2e/runner.go+++ b/tests/tools/runner/internal/e2e/runner.go@@ -144,8 +144,6 @@ func (r *Runner) run() int {return r.runSmokeFiltered("security")case "smoke-lifecycle":return r.runSmokeFiltered("lifecycle")- case "smoke-docker":- return r.runDockerSmoke()case "api":return r.runSingle(apiSuite())case "cli":@@ -328,19 +326,6 @@ func (r *Runner) runSmoke() int {return 0}-func (r *Runner) runDockerSmoke() int {- steps := r.selectedDockerSmokeSteps()- if len(steps) == 0 {- _, _ = fmt.Fprintf(r.stderr, "e2e: no docker smoke steps matched filter %q\n", r.args.Filter)- return 1- }- code := r.runDockerSmokeSteps(steps)- if code == 0 && !r.args.DryRun {- _, _ = fmt.Fprintln(r.stdout, "E2E docker smoke suite passed")- }- return code-}-func (r *Runner) runDockerSmokeSteps(steps []dockerSmokeStep) int {def := dockerSmokeSuite()r.printSuiteStart(def)