High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
chore: gate delete cookie operation
Luigi Agosti263ed42efe97
diff --git a/docs/architecture/mcp.md b/docs/architecture/mcp.mdindex afbe9e78..969c7e04 100644--- a/docs/architecture/mcp.md+++ b/docs/architecture/mcp.md@@ -115,7 +115,7 @@ URL validation lives in `handleNavigate` (`handlers_navigation.go`), which calls## Security Considerations- **`pinchtab_eval`** calls `/evaluate`, which requires `security.allowEvaluate: true` in the PinchTab config. It returns HTTP 403 by default. This is intentional — arbitrary JS execution is a separate opt-in from browser control.-- **`pinchtab_cookies`** calls `/cookies`, which requires `security.allowCookies: true` for read access. Cookie values can expose session credentials, so reads are disabled by default.+- **`pinchtab_cookies`** calls `/cookies`, which requires `security.allowCookies: true`. Cookie values can expose session credentials, so cookie operations are disabled by default.- **URL validation** — `pinchtab_navigate` rejects non-HTTP/HTTPS URLs to prevent SSRF via `file://`, `javascript:`, or custom schemes.- **Token forwarding** — the MCP client forwards the configured bearer token to PinchTab, so access control at the PinchTab layer applies to all tool calls.- **Wait caps** — `pinchtab_wait` and `pinchtab_wait_for_selector` enforce a 30-second maximum to prevent agent runaway.diff --git a/docs/endpoints.md b/docs/endpoints.mdindex fbad6e0c..ab55ee74 100644--- a/docs/endpoints.md+++ b/docs/endpoints.md@@ -306,7 +306,7 @@ GET /cache/statusNotes:- download and upload endpoints are gated by `security.allowDownload` and `security.allowUpload`-- cookie read/write endpoints (`GET/POST /cookies`, plus tab-scoped variants) are gated by `security.allowCookies`; `DELETE /cookies` and `DELETE /tabs/{id}/cookies` remain available so operators can remove session state+- cookie endpoints (`GET/POST/DELETE /cookies`, plus tab-scoped variants) are gated by `security.allowCookies`- download automatically decompresses `.gz` files and returns the decompressed content- `security.downloadAllowedDomains` can whitelist specific domains (bypasses SSRF checks for those domains). Setting `["*"]` matches every host and disables all private-IP protection on the download endpoint.- clipboard endpoints are gated by `security.allowClipboard`@@ -613,7 +613,7 @@ These gates are not ordinary feature toggles. Enabling them is a documented, non- `/evaluate` and `/tabs/{id}/evaluate` -> `security.allowEvaluate`- `/download` and `/tabs/{id}/download` -> `security.allowDownload`-- `GET/POST /cookies` and `GET/POST /tabs/{id}/cookies` -> `security.allowCookies`+- `GET/POST/DELETE /cookies` and `GET/POST/DELETE /tabs/{id}/cookies` -> `security.allowCookies`- `/upload` and `/tabs/{id}/upload` -> `security.allowUpload`- clipboard routes -> `security.allowClipboard`- attach routes -> `security.attach`diff --git a/docs/guides/security.md b/docs/guides/security.mdindex d99a34b3..fae9a79c 100644--- a/docs/guides/security.md+++ b/docs/guides/security.md@@ -198,7 +198,7 @@ Why they are considered dangerous:- `macro` can trigger higher-level automation flows- `screencast` can stream live page contents- `download` can fetch and persist remote content. When `security.downloadAllowedDomains` is set, listed domains bypass private-IP SSRF checks (intended for internal hosts such as Docker services). `["*"]` matches every host and disables all private-IP protection on the download endpoint.-- `cookies` can read or write browser session tokens for the current page+- `cookies` can read, write, or clear browser session tokens for the current page- `upload` can push local files into browser flowsThese are not the same as authentication.diff --git a/docs/reference/sessions.md b/docs/reference/sessions.mdindex 7a3a9058..799137df 100644--- a/docs/reference/sessions.md+++ b/docs/reference/sessions.md@@ -60,7 +60,7 @@ When a session record contains explicit `grants`, PinchTab enforces them in middThe built-in grant groups are: `browse`, `network`, `media`, `cookies`, `clipboard`, `evaluate`, `storage`, `console`, `solve`, `tasks`, and `activity`.-The `cookies` grant only authorizes session access to cookie routes; cookie reads and writes still require the server-level `security.allowCookies` gate.+The `cookies` grant only authorizes session access to cookie routes; cookie operations still require the server-level `security.allowCookies` gate.That default is a convenience for trusted automation, not a sandbox. If you need hard isolation between agents or tenants, use separate PinchTab instances.diff --git a/docs/reference/tabs.md b/docs/reference/tabs.mdindex d866943b..bf78087e 100644--- a/docs/reference/tabs.md+++ b/docs/reference/tabs.md@@ -252,7 +252,7 @@ A `pinchtab cookies` CLI command is available; today it exposes a single subcommpinchtab cookies clear # clear all cookies via CDP (affects all origins)```-Reading and writing cookie payloads is HTTP-only and requires `security.allowCookies=true`. Clearing cookies remains available through the CLI and HTTP API.+Reading, writing, and clearing cookies requires `security.allowCookies=true`.## Metricsdiff --git a/internal/handlers/cookies.go b/internal/handlers/cookies.goindex 56053d8d..26461b07 100644--- a/internal/handlers/cookies.go+++ b/internal/handlers/cookies.go@@ -146,6 +146,10 @@ type cookieSetRequest struct {//// @Endpoint DELETE /cookiesfunc (h *Handlers) HandleClearCookies(w http.ResponseWriter, r *http.Request) {+ if !h.ensureCookiesEnabled(w) {+ return+ }+if err := h.ensureChrome(); err != nil {httpx.Error(w, http.StatusServiceUnavailable, err)return@@ -175,6 +179,10 @@ func (h *Handlers) HandleTabClearCookies(w http.ResponseWriter, r *http.Request)return}+ if !h.ensureCookiesEnabled(w) {+ return+ }+// Verify tab exists before clearing.if _, _, err := h.tabContext(r, tabID); err != nil {WriteTabContextError(w, err, 404)diff --git a/internal/handlers/cookies_test.go b/internal/handlers/cookies_test.goindex eeffbfd0..12382da1 100644--- a/internal/handlers/cookies_test.go+++ b/internal/handlers/cookies_test.go@@ -53,6 +53,25 @@ func TestHandleSetCookies_DisabledByDefault(t *testing.T) {}}+func TestHandleClearCookies_DisabledByDefault(t *testing.T) {+ b := &cookieClearMockBridge{}+ h := New(b, &config.RuntimeConfig{}, nil, nil, nil)+ req := httptest.NewRequest("DELETE", "/cookies", nil)+ w := httptest.NewRecorder()++ h.HandleClearCookies(w, req)++ if w.Code != http.StatusForbidden {+ t.Fatalf("expected 403, got %d: %s", w.Code, w.Body.String())+ }+ if b.clearCookiesCalled {+ t.Fatal("expected ClearCookies not to be called")+ }+ if !bytes.Contains(w.Body.Bytes(), []byte("security.allowCookies")) {+ t.Fatalf("expected allowCookies hint, got %s", w.Body.String())+ }+}+func TestHandleSetCookies_NoTab(t *testing.T) {h := New(&failMockBridge{}, &config.RuntimeConfig{AllowCookies: true}, nil, nil, nil)body := `{"url":"https://pinchtab.com","cookies":[{"name":"a","value":"b"}],"tabId":"nonexistent"}`@@ -150,7 +169,7 @@ func (m *cookieClearMockBridge) ClearCookies(ctx context.Context) error {func TestHandleClearCookies_Success(t *testing.T) {b := &cookieClearMockBridge{}- h := New(b, &config.RuntimeConfig{}, nil, nil, nil)+ h := New(b, &config.RuntimeConfig{AllowCookies: true}, nil, nil, nil)req := httptest.NewRequest("DELETE", "/cookies", nil)w := httptest.NewRecorder()@@ -174,7 +193,7 @@ func TestHandleClearCookies_Success(t *testing.T) {func TestHandleTabClearCookies_Success(t *testing.T) {b := &cookieClearMockBridge{}- h := New(b, &config.RuntimeConfig{}, nil, nil, nil)+ h := New(b, &config.RuntimeConfig{AllowCookies: true}, nil, nil, nil)req := httptest.NewRequest("DELETE", "/tabs/tab1/cookies", nil)req.SetPathValue("id", "tab1")@@ -198,7 +217,7 @@ func TestHandleTabClearCookies_Success(t *testing.T) {}func TestHandleTabClearCookies_MissingTabID(t *testing.T) {- h := New(&cookieClearMockBridge{}, &config.RuntimeConfig{}, nil, nil, nil)+ h := New(&cookieClearMockBridge{}, &config.RuntimeConfig{AllowCookies: true}, nil, nil, nil)req := httptest.NewRequest("DELETE", "/tabs//cookies", nil)w := httptest.NewRecorder()@@ -209,10 +228,27 @@ func TestHandleTabClearCookies_MissingTabID(t *testing.T) {}}+func TestHandleTabClearCookies_DisabledByDefault(t *testing.T) {+ b := &cookieClearMockBridge{}+ h := New(b, &config.RuntimeConfig{}, nil, nil, nil)++ req := httptest.NewRequest("DELETE", "/tabs/tab1/cookies", nil)+ req.SetPathValue("id", "tab1")+ w := httptest.NewRecorder()+ h.HandleTabClearCookies(w, req)++ if w.Code != http.StatusForbidden {+ t.Fatalf("expected 403, got %d: %s", w.Code, w.Body.String())+ }+ if b.clearCookiesCalled {+ t.Fatal("expected ClearCookies not to be called")+ }+}+func TestHandleTabClearCookies_NoTab(t *testing.T) {b := &cookieClearMockBridge{}b.failTab = true- h := New(b, &config.RuntimeConfig{}, nil, nil, nil)+ h := New(b, &config.RuntimeConfig{AllowCookies: true}, nil, nil, nil)req := httptest.NewRequest("DELETE", "/tabs/nonexistent/cookies", nil)req.SetPathValue("id", "nonexistent")@@ -226,7 +262,7 @@ func TestHandleTabClearCookies_NoTab(t *testing.T) {func TestHandleClearCookies_RouteRegistration(t *testing.T) {b := &cookieClearMockBridge{}- h := New(b, &config.RuntimeConfig{}, nil, nil, nil)+ h := New(b, &config.RuntimeConfig{AllowCookies: true}, nil, nil, nil)mux := http.NewServeMux()h.RegisterRoutes(mux, nil)diff --git a/internal/handlers/security.go b/internal/handlers/security.goindex 619e48e0..3fc73abf 100644--- a/internal/handlers/security.go+++ b/internal/handlers/security.go@@ -63,7 +63,7 @@ func (h *Handlers) endpointSecurityStates() map[string]endpointSecurityState {Enabled: h.cookiesEnabled(),Setting: "security.allowCookies",Message: httpx.DisabledEndpointMessage("cookies", "security.allowCookies"),- Paths: []string{"GET /cookies", "POST /cookies", "GET /tabs/{id}/cookies", "POST /tabs/{id}/cookies"},+ Paths: []string{"GET /cookies", "POST /cookies", "DELETE /cookies", "GET /tabs/{id}/cookies", "POST /tabs/{id}/cookies", "DELETE /tabs/{id}/cookies"},},"upload": {Enabled: h.uploadEnabled(),diff --git a/internal/orchestrator/handlers.go b/internal/orchestrator/handlers.goindex 46edaaf9..edc112e7 100644--- a/internal/orchestrator/handlers.go+++ b/internal/orchestrator/handlers.go@@ -20,6 +20,8 @@ func (o *Orchestrator) Allows(cap routes.Capability) bool {return o.AllowsScreencast()case routes.CapDownload:return o.AllowsDownload()+ case routes.CapCookies:+ return o.AllowsCookies()case routes.CapUpload:return o.AllowsUpload()case routes.CapStateExport:@@ -97,6 +99,9 @@ func (o *Orchestrator) registerHandlers(mux *http.ServeMux, skipLaunch bool) {case routes.CapDownload:enabled = o.AllowsDownload()feature, setting, code = "download", "security.allowDownload", "download_disabled"+ case routes.CapCookies:+ enabled = o.AllowsCookies()+ feature, setting, code = "cookies", "security.allowCookies", "cookies_disabled"case routes.CapUpload:enabled = o.AllowsUpload()feature, setting, code = "upload", "security.allowUpload", "upload_disabled"diff --git a/internal/orchestrator/orchestrator.go b/internal/orchestrator/orchestrator.goindex 3f167cdf..ffbd63ec 100644--- a/internal/orchestrator/orchestrator.go+++ b/internal/orchestrator/orchestrator.go@@ -311,6 +311,10 @@ func (o *Orchestrator) AllowsDownload() bool {return o != nil && o.runtimeCfg != nil && o.runtimeCfg.AllowDownload}+func (o *Orchestrator) AllowsCookies() bool {+ return o != nil && o.runtimeCfg != nil && o.runtimeCfg.AllowCookies+}+func (o *Orchestrator) AllowsUpload() bool {return o != nil && o.runtimeCfg != nil && o.runtimeCfg.AllowUpload}diff --git a/internal/orchestrator/orchestrator_test.go b/internal/orchestrator/orchestrator_test.goindex 2196dc60..635722bd 100644--- a/internal/orchestrator/orchestrator_test.go+++ b/internal/orchestrator/orchestrator_test.go@@ -745,6 +745,8 @@ func TestOrchestrator_RegisterHandlers_LocksSensitiveRoutes(t *testing.T) {}{{method: "POST", path: "/tabs/tab1/evaluate", body: `{"expression":"1+1"}`, setting: "security.allowEvaluate"},{method: "GET", path: "/tabs/tab1/download", setting: "security.allowDownload"},+ {method: "GET", path: "/tabs/tab1/cookies", setting: "security.allowCookies"},+ {method: "DELETE", path: "/tabs/tab1/cookies", setting: "security.allowCookies"},{method: "POST", path: "/tabs/tab1/upload", body: `{}`, setting: "security.allowUpload"},{method: "GET", path: "/instances/inst1/screencast", setting: "security.allowScreencast"},}diff --git a/internal/routes/routes.go b/internal/routes/routes.goindex 6fd7e3ec..405b009d 100644--- a/internal/routes/routes.go+++ b/internal/routes/routes.go@@ -93,7 +93,7 @@ var coreEndpoints = []Endpoint{// Cookies{"GET", "/cookies", "Get cookies", CapCookies, true},{"POST", "/cookies", "Set cookies", CapCookies, true},- {"DELETE", "/cookies", "Clear all cookies", CapNone, true},+ {"DELETE", "/cookies", "Clear all cookies", CapCookies, true},// Metrics{"GET", "/metrics", "Runtime metrics", CapNone, true},diff --git a/internal/server/helpers.go b/internal/server/helpers.goindex 8aa212a9..a2094d5d 100644--- a/internal/server/helpers.go+++ b/internal/server/helpers.go@@ -41,7 +41,7 @@ func RegisterDefaultProxyRoutes(mux *http.ServeMux, orch *orchestrator.Orchestra"GET /snapshot", "GET /screenshot", "GET /text","POST /navigate", "POST /action", "POST /actions", "POST /evaluate","POST /tab", "POST /lock", "POST /unlock",- "GET /cookies", "POST /cookies",+ "GET /cookies", "POST /cookies", "DELETE /cookies","GET /download", "POST /upload","GET /stealth/status", "POST /fingerprint/rotate","GET /screencast", "GET /screencast/tabs",diff --git a/internal/strategy/routes.go b/internal/strategy/routes.goindex 81cdf07d..6e8d1074 100644--- a/internal/strategy/routes.go+++ b/internal/strategy/routes.go@@ -18,6 +18,8 @@ func capabilitySetting(cap routes.Capability) (feature, setting, code string) {return "screencast", "security.allowScreencast", "screencast_disabled"case routes.CapDownload:return "download", "security.allowDownload", "download_disabled"+ case routes.CapCookies:+ return "cookies", "security.allowCookies", "cookies_disabled"case routes.CapUpload:return "upload", "security.allowUpload", "upload_disabled"case routes.CapStateExport:diff --git a/internal/strategy/simple/simple_test.go b/internal/strategy/simple/simple_test.goindex 349016d5..d0a263c7 100644--- a/internal/strategy/simple/simple_test.go+++ b/internal/strategy/simple/simple_test.go@@ -118,15 +118,28 @@ func TestStrategy_RegisterRoutes_LocksSensitiveShorthandRoutes(t *testing.T) {mux := http.NewServeMux()s.RegisterRoutes(mux)- req := httptest.NewRequest("POST", "/evaluate", strings.NewReader(`{"expression":"1+1"}`))- rec := httptest.NewRecorder()- mux.ServeHTTP(rec, req)-- if rec.Code != 403 {- t.Fatalf("expected 403, got %d: %s", rec.Code, rec.Body.String())+ tests := []struct {+ method string+ path string+ body string+ setting string+ }{+ {method: "POST", path: "/evaluate", body: `{"expression":"1+1"}`, setting: "security.allowEvaluate"},+ {method: "GET", path: "/cookies", setting: "security.allowCookies"},+ {method: "DELETE", path: "/cookies", setting: "security.allowCookies"},}- if !strings.Contains(rec.Body.String(), "security.allowEvaluate") {- t.Fatalf("expected lock response to mention security.allowEvaluate, got %s", rec.Body.String())++ for _, tt := range tests {+ req := httptest.NewRequest(tt.method, tt.path, strings.NewReader(tt.body))+ rec := httptest.NewRecorder()+ mux.ServeHTTP(rec, req)++ if rec.Code != 403 {+ t.Fatalf("%s %s expected 403, got %d: %s", tt.method, tt.path, rec.Code, rec.Body.String())+ }+ if !strings.Contains(rec.Body.String(), tt.setting) {+ t.Fatalf("%s %s expected lock response to mention %s, got %s", tt.method, tt.path, tt.setting, rec.Body.String())+ }}}diff --git a/plugin/README.md b/plugin/README.mdindex 69dd40e4..3ee6f7a6 100644--- a/plugin/README.md+++ b/plugin/README.md@@ -228,7 +228,7 @@ pinchtab({ action: "wait", text: "Welcome back", timeout: 120000 })- **Server lifecycle**: the plugin does not start PinchTab — run `pinchtab server` separately. If the server isn't reachable, the plugin returns a clear error pointing at the configured `baseUrl`. Once the server is up, the plugin briefly waits for instance/profile readiness (handles the "still booting" / `503` window).- **`evaluate`** is blocked by default (`allowEvaluate: false`) — enable only for trusted agents- **`downloads`** and **`uploads`** are blocked by default — enable only when the task requires file transfer-- **Cookie access** exposes session credentials. Core cookie read/write endpoints are blocked unless `security.allowCookies=true`; do not log or expose cookie values to untrusted contexts+- **Cookie access** exposes session credentials. Core cookie endpoints are blocked unless `security.allowCookies=true`; do not log or expose cookie values to untrusted contexts- **Network exports** may contain private URLs and auth tokens — omit `--body` for sensitive sessions; delete exports after use- **Challenge solving** (`/solve`) requires explicit user approval — do not call speculatively- **Session reuse**: when agents reuse human-authenticated sessions, use dedicated low-privilege profiles and confirm before account-changing actionsdiff --git a/skills/pinchtab/SKILL.md b/skills/pinchtab/SKILL.mdindex f742f719..6b36e0d1 100644--- a/skills/pinchtab/SKILL.md+++ b/skills/pinchtab/SKILL.md@@ -60,7 +60,7 @@ Rules: only `nav <url>` auto-starts the default local server; `snap`, `text`, `h- Do not upload local files unless the user explicitly names the file and the destination flow requires it.- Do not save screenshots, PDFs, or downloads to arbitrary paths — use a user-specified path or a safe temporary/workspace directory.- Do not use PinchTab to inspect unrelated local files, browser secrets, stored credentials, or system configuration outside the task.-- Cookie read/write is disabled by default; do not inspect or expose cookies without explicit user approval.+- Cookie access is disabled by default; do not inspect, change, or clear cookies without explicit user approval.- Network exports (`pinchtab network-export`) may contain private URLs, auth tokens, and response bodies. Omit `--body` for sensitive sessions. Delete or redact export files after use.## Selectorsdiff --git a/skills/pinchtab/references/api.md b/skills/pinchtab/references/api.mdindex 91a8b55e..827dd91a 100644--- a/skills/pinchtab/references/api.md+++ b/skills/pinchtab/references/api.md@@ -303,7 +303,7 @@ curl "/screenshot?raw=true&format=png" -o screenshot.png## Evaluate JavaScriptUse this sparingly. Prefer `text`, `snapshot`, and normal actions first.-Default to read-only DOM inspection and avoid reading cookies, localStorage, or unrelated page secrets unless the user explicitly asks for that behavior. Cookie read/write is disabled by default and requires `security.allowCookies: true`.+Default to read-only DOM inspection and avoid reading cookies, localStorage, or unrelated page secrets unless the user explicitly asks for that behavior. Cookie access is disabled by default and requires `security.allowCookies: true`.```bash# CLI: pinchtab eval "document.title"@@ -407,7 +407,7 @@ Locked tabs show `owner` and `lockedUntil` in `/tabs`. Returns 409 on conflict.## Cookies-Cookie values are session credentials. Read/write endpoints are disabled by default (`security.allowCookies: false`); enable them only for an explicitly approved cookie-inspection or cookie-injection task. Do not log, copy, or send cookie values to untrusted contexts. Use cookie clearing after sensitive work when the user wants session state removed.+Cookie values are session credentials. Cookie endpoints are disabled by default (`security.allowCookies: false`); enable them only for an explicitly approved cookie-inspection, cookie-injection, or cookie-clearing task. Do not log, copy, or send cookie values to untrusted contexts.```bash# Get cookies for current page (requires security.allowCookies=true)@@ -416,6 +416,9 @@ curl /cookies# Set cookies (requires security.allowCookies=true)curl -X POST /cookies -H 'Content-Type: application/json' \-d '{"url":"https://pinchtab.com","cookies":[{"name":"session","value":"abc123"}]}'++# Clear cookies (requires security.allowCookies=true)+curl -X DELETE /cookies```## Solve challengesdiff --git a/tests/e2e/config/pinchtab-full-permissive.json b/tests/e2e/config/pinchtab-full-permissive.jsonindex 17e8021a..5fe9224b 100644--- a/tests/e2e/config/pinchtab-full-permissive.json+++ b/tests/e2e/config/pinchtab-full-permissive.json@@ -37,6 +37,7 @@"allowEvaluate": true,"allowDownload": true,"allowScreencast": true,+ "allowCookies": true,"allowUpload": true,"allowStateExport": true,"allowNetworkIntercept": true,diff --git a/tests/e2e/config/pinchtab-medium-permissive.json b/tests/e2e/config/pinchtab-medium-permissive.jsonindex 99d21c1a..edfa9818 100644--- a/tests/e2e/config/pinchtab-medium-permissive.json+++ b/tests/e2e/config/pinchtab-medium-permissive.json@@ -36,6 +36,7 @@"security": {"allowEvaluate": true,"allowDownload": true,+ "allowCookies": true,"allowUpload": true,"allowStateExport": true,"allowedDomains": [diff --git a/tests/e2e/config/pinchtab.json b/tests/e2e/config/pinchtab.jsonindex 494a24c8..faec556d 100644--- a/tests/e2e/config/pinchtab.json+++ b/tests/e2e/config/pinchtab.json@@ -39,6 +39,7 @@"security": {"allowEvaluate": true,"allowDownload": true,+ "allowCookies": true,"allowUpload": true,"allowClipboard": true,"allowStateExport": true,