Skip to content

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.md
index 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.md
index fbad6e0c..ab55ee74 100644
--- a/docs/endpoints.md
+++ b/docs/endpoints.md
@@ -306,7 +306,7 @@ GET /cache/status
Notes:
- 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.md
index 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 flows
These are not the same as authentication.
diff --git a/docs/reference/sessions.md b/docs/reference/sessions.md
index 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 midd
The 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.md
index 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 subcomm
pinchtab 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`.
## Metrics
diff --git a/internal/handlers/cookies.go b/internal/handlers/cookies.go
index 56053d8d..26461b07 100644
--- a/internal/handlers/cookies.go
+++ b/internal/handlers/cookies.go
@@ -146,6 +146,10 @@ type cookieSetRequest struct {
//
// @Endpoint DELETE /cookies
func (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.go
index 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.go
index 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.go
index 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.go
index 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.go
index 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.go
index 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.go
index 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.go
index 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.go
index 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.md
index 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 actions
diff --git a/skills/pinchtab/SKILL.md b/skills/pinchtab/SKILL.md
index 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.
## Selectors
diff --git a/skills/pinchtab/references/api.md b/skills/pinchtab/references/api.md
index 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 JavaScript
Use 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 challenges
diff --git a/tests/e2e/config/pinchtab-full-permissive.json b/tests/e2e/config/pinchtab-full-permissive.json
index 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.json
index 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.json
index 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,