Skip to content

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.tsx
index 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 (
<SectionCard
title="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."
>
<input
value={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>
+ </>
+ )}
<SettingRow
label="Extra flags"
description="Additional Chrome flags appended when launching managed instances."
diff --git a/dashboard/src/types/index.ts b/dashboard/src/types/index.ts
index 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/dev
index 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 ]; then
fi
run_e2e_runner "${@:2}"
;;
+ smoke)
+ if [ $# -gt 1 ]; then
+ run_command "smoke ${*:2}"
+ else
+ run_command "smoke"
+ fi
+ ;;
binary)
if [ $# -gt 1 ]; then
run_command "binary $2"
diff --git a/docs/architecture/browser-targets.md b/docs/architecture/browser-targets.md
new file mode 100644
index 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.md
index 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
```mermaid
diff --git a/docs/guides/cloakbrowser.md b/docs/guides/cloakbrowser.md
new file mode 100644
index 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.md
index 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.json
index 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.md
index 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 and
shows the active config file path. Provider keys remain managed directly in the
config 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.go
index 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.go
index 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.ChromeBinary
if 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.Runti
chromeBinary = 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.Runti
browserCtx, 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.Bundle
bundle = 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.Bundle
return 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.go
index 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.go
index 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.go
new file mode 100644
index 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.go
index 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.go
index 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.go
index 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.go
index 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.go
index 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 only
ChromeExtraFlags: "",
+ 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.go
index 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: &quota,
+ 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 := true
diff --git a/internal/config/config_types.go b/internal/config/config_types.go
index 5ee27a67..95481afd 100644
--- a/internal/config/config_types.go
+++ b/internal/config/config_types.go
@@ -60,6 +60,7 @@ type RuntimeConfig struct {
BlockAds bool
MaxTabs int
MaxParallelTabs int // 0 = auto-detect from runtime.NumCPU
+ BrowserProvider string
ChromeBinary string
ChromeDebugPort int
ChromeExtraFlags 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 CloakBrowserRuntimeConfig
ExtensionPaths []string
UserAgent string
NoAnimations 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.go
index 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, nil
case "version":
return b.ChromeVersion, nil
case "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.go
index 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.go
index 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 = value
case "version":
b.ChromeVersion = value
case "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.go
index 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) bool
wantErr 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.go
index 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.go
index 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: &quota,
+ },
+ },
+ }
+ 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.json
index 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.go
index 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.BrowserProviderChrome
if cfg != nil {
levelName = cfg.StealthLevel
headless = 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 Laun
return 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.go
index 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.go
index 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 := false
diff --git a/scripts/README.md b/scripts/README.md
index 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.sh
new file mode 100755
index 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.md
index 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 basic
go run ./tests/tools/runner e2e --suite extended
go run ./tests/tools/runner e2e --suite smoke
-go run ./tests/tools/runner e2e --suite smoke-docker
go 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 Scenario
1. 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.sh
index 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 /snapshot
assert_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_test
start_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')
fi
if [ -n "$PASS_REF" ] && [ "$PASS_REF" != "null" ]; then
diff --git a/tests/tools/docker/cloakbrowser-smoke.Dockerfile b/tests/tools/docker/cloakbrowser-smoke.Dockerfile
new file mode 100644
index 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.pl
new file mode 100644
index 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.go
index 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, nil
case "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, nil
default:
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.go
index 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.Buffer
if 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.go
index 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)