Skip to content

High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.

security: gate state/storage endpoints, fix path traversal, namespace metadata

Yash Jadhavd4aa32eebafc
diff --git a/internal/handlers/openapi.go b/internal/handlers/openapi.go
index 103e03d6..00c52dbd 100644
--- a/internal/handlers/openapi.go
+++ b/internal/handlers/openapi.go
@@ -73,14 +73,16 @@ func (h *Handlers) HandleOpenAPI(w http.ResponseWriter, _ *http.Request) {
"x-pinchtab-enabled": security["screencast"].Enabled,
}},
"/storage": map[string]any{
- "get": map[string]any{"summary": "Get localStorage/sessionStorage items (current origin only)"},
"post": map[string]any{"summary": "Set a storage item"},
"delete": map[string]any{"summary": "Delete storage items or clear storage"},
},
- "/state/list": map[string]any{"get": map[string]any{"summary": "List saved state files"}},
- "/state/load": map[string]any{"post": map[string]any{"summary": "Load and restore browser state"}},
- "/state/clean": map[string]any{"post": map[string]any{"summary": "Clean old state files"}},
- "/state": map[string]any{"delete": map[string]any{"summary": "Delete a saved state file"}},
+ "/state/list": map[string]any{"get": map[string]any{"summary": "List saved state files"}},
+ // CapStateExport-gated endpoints
+ "/storage (GET)": map[string]any{"get": map[string]any{
+ "summary": "Get localStorage/sessionStorage items (current origin only)",
+ "description": security["stateExport"].Message,
+ "x-pinchtab-enabled": security["stateExport"].Enabled,
+ }},
"/state/show": map[string]any{"get": map[string]any{
"summary": "Show state file details",
"description": security["stateExport"].Message,
@@ -91,6 +93,21 @@ func (h *Handlers) HandleOpenAPI(w http.ResponseWriter, _ *http.Request) {
"description": security["stateExport"].Message,
"x-pinchtab-enabled": security["stateExport"].Enabled,
}},
+ "/state/load": map[string]any{"post": map[string]any{
+ "summary": "Load and restore browser state",
+ "description": security["stateExport"].Message,
+ "x-pinchtab-enabled": security["stateExport"].Enabled,
+ }},
+ "/state": map[string]any{"delete": map[string]any{
+ "summary": "Delete a saved state file",
+ "description": security["stateExport"].Message,
+ "x-pinchtab-enabled": security["stateExport"].Enabled,
+ }},
+ "/state/clean": map[string]any{"post": map[string]any{
+ "summary": "Clean old state files",
+ "description": security["stateExport"].Message,
+ "x-pinchtab-enabled": security["stateExport"].Enabled,
+ }},
},
})
}
diff --git a/internal/handlers/security.go b/internal/handlers/security.go
index ccfd3d5c..a439d205 100644
--- a/internal/handlers/security.go
+++ b/internal/handlers/security.go
@@ -67,7 +67,11 @@ func (h *Handlers) endpointSecurityStates() map[string]endpointSecurityState {
Enabled: h.stateExportEnabled(),
Setting: "security.allowStateExport",
Message: httpx.DisabledEndpointMessage("stateExport", "security.allowStateExport"),
- Paths: []string{"POST /state/save", "GET /state/show"},
+ Paths: []string{
+ "GET /storage", "GET /tabs/{id}/storage",
+ "GET /state/show", "POST /state/save",
+ "POST /state/load", "DELETE /state", "POST /state/clean",
+ },
},
}
}
diff --git a/internal/handlers/state.go b/internal/handlers/state.go
index a2a8d077..9d435dd0 100644
--- a/internal/handlers/state.go
+++ b/internal/handlers/state.go
@@ -206,9 +206,10 @@ func (h *Handlers) HandleStateSave(w http.ResponseWriter, r *http.Request) {
"origin": storageResult.Origin,
"userAgent": storageResult.UserAgent,
}
- // Merge user-provided metadata
- for k, v := range req.Metadata {
- metadata[k] = v
+ // Namespace user-provided metadata under "custom" to prevent overwriting
+ // browser-captured provenance fields (url, origin, userAgent).
+ if len(req.Metadata) > 0 {
+ metadata["custom"] = req.Metadata
}
sf := &state.StateFile{
@@ -250,10 +251,17 @@ func (h *Handlers) HandleStateSave(w http.ResponseWriter, r *http.Request) {
})
}
-// HandleStateLoad reads a state file and restores cookies and storage.
+// HandleStateLoad reads a state file and restores cookies and storage into the browser.
+// Gated behind CapStateExport: restoring cookies/storage is session injection.
//
// @Endpoint POST /state/load
func (h *Handlers) HandleStateLoad(w http.ResponseWriter, r *http.Request) {
+ if !h.stateExportEnabled() {
+ httpx.ErrorCode(w, 403, "state_export_disabled", httpx.DisabledEndpointMessage("stateExport", "security.allowStateExport"), false, map[string]any{
+ "setting": "security.allowStateExport",
+ })
+ return
+ }
var req struct {
Name string `json:"name"`
TabID string `json:"tabId"`
@@ -369,9 +377,16 @@ func (h *Handlers) HandleStateLoad(w http.ResponseWriter, r *http.Request) {
}
// HandleStateDelete removes a saved state file.
+// Gated behind CapStateExport: deletion is a destructive operation.
//
// @Endpoint DELETE /state
func (h *Handlers) HandleStateDelete(w http.ResponseWriter, r *http.Request) {
+ if !h.stateExportEnabled() {
+ httpx.ErrorCode(w, 403, "state_export_disabled", httpx.DisabledEndpointMessage("stateExport", "security.allowStateExport"), false, map[string]any{
+ "setting": "security.allowStateExport",
+ })
+ return
+ }
name := r.URL.Query().Get("name")
if name == "" {
httpx.Error(w, 400, fmt.Errorf("name query parameter is required"))
@@ -394,9 +409,16 @@ func (h *Handlers) HandleStateDelete(w http.ResponseWriter, r *http.Request) {
}
// HandleStateClean removes state files older than a given duration.
+// Gated behind CapStateExport: bulk deletion is a destructive operation.
//
// @Endpoint POST /state/clean
func (h *Handlers) HandleStateClean(w http.ResponseWriter, r *http.Request) {
+ if !h.stateExportEnabled() {
+ httpx.ErrorCode(w, 403, "state_export_disabled", httpx.DisabledEndpointMessage("stateExport", "security.allowStateExport"), false, map[string]any{
+ "setting": "security.allowStateExport",
+ })
+ return
+ }
var req struct {
OlderThanHours int `json:"olderThanHours"`
}
diff --git a/internal/handlers/storage.go b/internal/handlers/storage.go
index 55c7dbaa..8ea9612b 100644
--- a/internal/handlers/storage.go
+++ b/internal/handlers/storage.go
@@ -32,11 +32,18 @@ func (h *Handlers) HandleStorage(w http.ResponseWriter, r *http.Request) {
}
// handleStorageGet retrieves localStorage and/or sessionStorage items.
+// Gated behind CapStateExport: storage can contain auth tokens and session data.
//
// Query params:
// - type: "local", "session", or "" (both)
// - key: optional specific key to retrieve
func (h *Handlers) handleStorageGet(w http.ResponseWriter, r *http.Request) {
+ if !h.stateExportEnabled() {
+ httpx.ErrorCode(w, 403, "state_export_disabled", httpx.DisabledEndpointMessage("stateExport", "security.allowStateExport"), false, map[string]any{
+ "setting": "security.allowStateExport",
+ })
+ return
+ }
tabID := r.URL.Query().Get("tabId")
storageType := r.URL.Query().Get("type")
key := r.URL.Query().Get("key")
diff --git a/internal/routes/routes.go b/internal/routes/routes.go
index b2984c54..1bb21afa 100644
--- a/internal/routes/routes.go
+++ b/internal/routes/routes.go
@@ -109,16 +109,13 @@ var coreEndpoints = []Endpoint{
{"POST", "/cache/clear", "Clear browser cache", CapNone, false},
{"GET", "/cache/status", "Cache status", CapNone, false},
- // Storage (current origin only)
- {"GET", "/storage", "Get storage items", CapNone, true},
+ // Storage — GET reads sensitive client-side state and is gated alongside state export.
+ // POST/DELETE mutate state and are gated to prevent unauthorized writes.
{"POST", "/storage", "Set storage item", CapNone, true},
{"DELETE", "/storage", "Delete storage items", CapNone, true},
- // State management
+ // State management — list is read-only summary, ungated.
{"GET", "/state/list", "List saved states", CapNone, false},
- {"POST", "/state/load", "Load browser state", CapNone, false},
- {"DELETE", "/state", "Delete saved state", CapNone, false},
- {"POST", "/state/clean", "Clean old state files", CapNone, false},
// Capability-gated
{"POST", "/evaluate", "Run JavaScript in page", CapEvaluate, true},
@@ -127,8 +124,13 @@ var coreEndpoints = []Endpoint{
{"POST", "/upload", "Upload file to file input", CapUpload, true},
{"GET", "/screencast", "Live tab frame stream", CapScreencast, false},
{"GET", "/screencast/tabs", "List tabs available for screencast", CapScreencast, false},
- {"GET", "/state/show", "Show state details", CapStateExport, false},
+ // CapStateExport gates all sensitive state I/O: reading, writing, injection, and deletion.
+ {"GET", "/storage", "Get storage items (current origin)", CapStateExport, true},
+ {"GET", "/state/show", "Show state file details", CapStateExport, false},
{"POST", "/state/save", "Save browser state", CapStateExport, false},
+ {"POST", "/state/load", "Load and restore browser state", CapStateExport, false},
+ {"DELETE", "/state", "Delete saved state file", CapStateExport, false},
+ {"POST", "/state/clean", "Clean old state files", CapStateExport, false},
}
// Core returns a copy of the canonical endpoint list.
diff --git a/internal/state/state.go b/internal/state/state.go
index f7c10df9..41198e2d 100644
--- a/internal/state/state.go
+++ b/internal/state/state.go
@@ -345,9 +345,16 @@ func sanitizeFilename(name string) string {
return name
}
-// ResolvePath returns the full path for a named state file.
+// ResolvePath returns the full canonical path for a named state file.
+// Returns an empty string if the resolved path attempts to escape stateDir.
func ResolvePath(stateDir, name string) string {
dir := SessionsDir(stateDir)
filename := sanitizeFilename(name) + ".json"
- return filepath.Join(dir, filename)
+ resolved := filepath.Clean(filepath.Join(dir, filename))
+ // Belt-and-suspenders: reject if the canonical path escapes the sessions dir.
+ cleanDir := filepath.Clean(dir) + string(os.PathSeparator)
+ if !strings.HasPrefix(resolved, cleanDir) {
+ return ""
+ }
+ return resolved
}
diff --git a/internal/state/state_test.go b/internal/state/state_test.go
index 56f03c2a..32162fb9 100644
--- a/internal/state/state_test.go
+++ b/internal/state/state_test.go
@@ -314,3 +314,36 @@ func TestEmptyStorage(t *testing.T) {
t.Errorf("storage = %d, want 0", len(loaded.Storage))
}
}
+
+func TestResolvePathTraversal(t *testing.T) {
+ dir := t.TempDir()
+
+ // These names should all resolve safely within the sessions dir.
+ safe := []string{"simple", "with-dashes", "session_2024"}
+ for _, name := range safe {
+ p := ResolvePath(dir, name)
+ if p == "" {
+ t.Errorf("ResolvePath(%q) rejected a safe name", name)
+ }
+ }
+
+ // These names are path traversal attempts — must return "".
+ traversal := []string{
+ "../etc/passwd",
+ "..\\windows\\system32",
+ "../../secret",
+ "/etc/passwd",
+ }
+ for _, name := range traversal {
+ p := ResolvePath(dir, name)
+ if p == "" {
+ // Good: traversal rejected.
+ continue
+ }
+ // If non-empty, check it's actually inside the sessions dir.
+ sessDir := SessionsDir(dir)
+ if len(p) <= len(sessDir) {
+ t.Errorf("ResolvePath(%q) = %q escaped sessions dir %q", name, p, sessDir)
+ }
+ }
+}