Skip to content

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

feat(handlers): declare each route's tab guard set in the catalog and verify it through the mux

Luigi Agosti9d89944a8894
diff --git a/internal/handlers/handlers.go b/internal/handlers/handlers.go
index b793d89c..ccb4cfe2 100644
--- a/internal/handlers/handlers.go
+++ b/internal/handlers/handlers.go
@@ -330,107 +330,108 @@ type routeBinding struct {
root http.HandlerFunc
tab http.HandlerFunc
tabOnly bool
+ guards tabGuards
}
// bridgeBindings is the authoritative bridge route catalog. It is realized as a
// method so the per-binding handlers can close over the receiver h.
func (h *Handlers) bridgeBindings() []routeBinding {
return []routeBinding{
- {pattern: "POST /navigate", root: h.HandleNavigate, tab: h.HandleTabNavigate},
- {pattern: "POST /back", root: h.HandleBack, tab: h.HandleTabBack},
- {pattern: "POST /forward", root: h.HandleForward, tab: h.HandleTabForward},
- {pattern: "POST /reload", root: h.HandleReload, tab: h.HandleTabReload},
- {pattern: "GET /snapshot", root: h.HandleSnapshot, tab: h.HandleTabSnapshot},
- {pattern: "GET /frame", root: h.HandleFrame, tab: h.HandleTabFrame},
- {pattern: "POST /frame", root: h.HandleFrame, tab: h.HandleTabFrame},
- {pattern: "GET /screenshot", root: h.HandleScreenshot, tab: h.HandleTabScreenshot},
- {pattern: "GET /annotate", root: h.HandleAnnotate, tab: h.HandleTabAnnotate},
- {pattern: "GET /capture", root: h.HandleCapture, tab: h.HandleTabCapture},
- {pattern: "GET /text", root: h.HandleText, tab: h.HandleTabText},
- {pattern: "GET /title", root: h.HandleTitle, tab: h.HandleTabTitle},
- {pattern: "GET /url", root: h.HandleURL, tab: h.HandleTabURL},
- {pattern: "GET /html", root: h.HandleHTML, tab: h.HandleTabHTML},
- {pattern: "GET /styles", root: h.HandleStyles, tab: h.HandleTabStyles},
- {pattern: "GET /value", root: h.HandleGetValue, tab: h.HandleTabGetValue},
- {pattern: "GET /attr", root: h.HandleGetAttr, tab: h.HandleTabGetAttr},
- {pattern: "GET /count", root: h.HandleCount, tab: h.HandleTabCount},
- {pattern: "GET /box", root: h.HandleGetBox, tab: h.HandleTabGetBox},
- {pattern: "GET /visible", root: h.HandleGetVisible, tab: h.HandleTabGetVisible},
- {pattern: "GET /enabled", root: h.HandleGetEnabled, tab: h.HandleTabGetEnabled},
- {pattern: "GET /checked", root: h.HandleGetChecked, tab: h.HandleTabGetChecked},
- {pattern: "GET /pdf", root: h.HandlePDF, tab: h.HandleTabPDF},
- {pattern: "POST /pdf", root: h.HandlePDF, tab: h.HandleTabPDF},
- {pattern: "POST /action", root: h.HandleAction, tab: h.HandleTabAction},
- {pattern: "POST /actions", root: h.HandleActions, tab: h.HandleTabActions},
- {pattern: "POST /dialog", root: h.HandleDialog, tab: h.HandleTabDialog},
- {pattern: "POST /wait", root: h.HandleWait, tab: h.HandleTabWait},
- {pattern: "POST /find", root: h.HandleFind, tab: h.HandleFind},
- {pattern: "POST /tab", root: h.HandleTab},
- {pattern: "POST /close", root: h.HandleClose, tab: h.HandleTabClose},
- {pattern: "POST /lock", root: h.HandleTabLock, tab: h.HandleTabLockByID},
- {pattern: "POST /unlock", root: h.HandleTabUnlock, tab: h.HandleTabUnlockByID},
- {pattern: "POST /handoff", tab: h.HandleTabHandoff, tabOnly: true},
- {pattern: "POST /resume", tab: h.HandleTabResume, tabOnly: true},
- {pattern: "GET /handoff", tab: h.HandleTabHandoffStatus, tabOnly: true},
- {pattern: "GET /cookies", root: h.HandleGetCookies, tab: h.HandleTabGetCookies},
- {pattern: "POST /cookies", root: h.HandleSetCookies, tab: h.HandleTabSetCookies},
- {pattern: "DELETE /cookies", root: h.HandleClearCookies, tab: h.HandleTabClearCookies},
- {pattern: "GET /metrics", root: h.HandleMetrics, tab: h.HandleTabMetrics},
- {pattern: "GET /timing", root: h.HandleTiming, tab: h.HandleTabTiming},
- {pattern: "GET /a11y/audit", root: h.HandleA11yAudit, tab: h.HandleTabA11yAudit},
- {pattern: "POST /audit/page", root: h.HandleAuditPage},
- {pattern: "POST /audit", root: h.HandleAudit},
- {pattern: "POST /scrape", root: h.HandleScrape},
- {pattern: "GET /network", root: h.HandleNetwork, tab: h.HandleTabNetwork},
- {pattern: "GET /network/stream", root: h.HandleNetworkStream, tab: h.HandleTabNetworkStream},
- {pattern: "GET /network/export", root: h.HandleNetworkExport, tab: h.HandleTabNetworkExport},
- {pattern: "GET /network/export/stream", root: h.HandleNetworkExportStream, tab: h.HandleTabNetworkExportStream},
- {pattern: "GET /network/{requestId}", root: h.HandleNetworkByID, tab: h.HandleTabNetworkByID},
- {pattern: "POST /network/clear", root: h.HandleNetworkClear},
- {pattern: "GET /network/route", root: h.HandleNetworkRouteList, tab: h.HandleTabNetworkRouteList},
- {pattern: "POST /network/route", root: h.HandleNetworkRoute, tab: h.HandleTabNetworkRoute},
- {pattern: "DELETE /network/route", root: h.HandleNetworkUnroute, tab: h.HandleTabNetworkUnroute},
- {pattern: "GET /console", root: h.HandleGetConsoleLogs},
- {pattern: "POST /console/clear", root: h.HandleClearConsoleLogs},
- {pattern: "GET /errors", root: h.HandleGetErrorLogs},
- {pattern: "POST /errors/clear", root: h.HandleClearErrorLogs},
- {pattern: "GET /clipboard/read", root: h.HandleClipboardRead},
- {pattern: "POST /clipboard/write", root: h.HandleClipboardWrite},
- {pattern: "POST /clipboard/copy", root: h.HandleClipboardCopy},
- {pattern: "GET /clipboard/paste", root: h.HandleClipboardPaste},
- {pattern: "GET /stealth/status", root: h.HandleStealthStatus},
- {pattern: "POST /fingerprint/rotate", root: h.HandleFingerprintRotate},
- {pattern: "GET /solvers", root: h.HandleListSolvers},
- {pattern: "GET /config/autosolver", root: h.HandleAutoSolverConfig},
- {pattern: "POST /solve", root: h.HandleSolve, tab: h.HandleTabSolve},
- {pattern: "POST /solve/{name}", root: h.HandleSolve, tab: h.HandleTabSolve},
- {pattern: "POST /emulation/viewport", root: h.HandleSetViewport, tab: h.HandleTabSetViewport},
- {pattern: "POST /emulation/geolocation", root: h.HandleSetGeolocation, tab: h.HandleTabSetGeolocation},
- {pattern: "POST /emulation/offline", root: h.HandleSetOffline, tab: h.HandleTabSetOffline},
- {pattern: "POST /emulation/headers", root: h.HandleSetHeaders, tab: h.HandleTabSetHeaders},
- {pattern: "POST /emulation/credentials", root: h.HandleSetCredentials, tab: h.HandleTabSetCredentials},
- {pattern: "POST /emulation/media", root: h.HandleSetMedia, tab: h.HandleTabSetMedia},
- {pattern: "POST /cache/clear", root: h.HandleCacheClear},
- {pattern: "GET /cache/status", root: h.HandleCacheStatus},
- {pattern: "POST /storage", root: h.HandleStorage, tab: h.HandleTabStorageSet},
- {pattern: "DELETE /storage", root: h.HandleStorage, tab: h.HandleTabStorageDelete},
- {pattern: "GET /storage", root: h.HandleStorage, tab: h.HandleTabStorageGet},
- {pattern: "GET /state", root: h.HandleStateCurrent},
- {pattern: "GET /state/list", root: h.HandleStateList},
- {pattern: "GET /state/show", root: h.HandleStateShow},
- {pattern: "POST /state/save", root: h.HandleStateSave},
- {pattern: "POST /state/load", root: h.HandleStateLoad},
- {pattern: "DELETE /state", root: h.HandleStateDelete},
- {pattern: "POST /state/clean", root: h.HandleStateClean},
- {pattern: "POST /evaluate", root: h.HandleEvaluate, tab: h.HandleTabEvaluate},
- {pattern: "POST /macro", root: h.HandleMacro},
- {pattern: "GET /download", root: h.HandleDownload, tab: h.HandleTabDownload},
- {pattern: "POST /upload", root: h.HandleUpload, tab: h.HandleTabUpload},
- {pattern: "GET /screencast", root: h.HandleScreencast},
- {pattern: "GET /screencast/tabs", root: h.HandleScreencastAll},
- {pattern: "POST /record/start", root: h.HandleRecordStart},
- {pattern: "POST /record/stop", root: h.HandleRecordStop},
- {pattern: "GET /record/status", root: h.HandleRecordStatus},
+ {pattern: "POST /navigate", root: h.HandleNavigate, tab: h.HandleTabNavigate, guards: guardHandoffPause},
+ {pattern: "POST /back", root: h.HandleBack, tab: h.HandleTabBack, guards: guardHandoffPause},
+ {pattern: "POST /forward", root: h.HandleForward, tab: h.HandleTabForward, guards: guardHandoffPause},
+ {pattern: "POST /reload", root: h.HandleReload, tab: h.HandleTabReload, guards: guardHandoffPause},
+ {pattern: "GET /snapshot", root: h.HandleSnapshot, tab: h.HandleTabSnapshot, guards: guardDialogBlocked | guardDomainPolicy},
+ {pattern: "GET /frame", root: h.HandleFrame, tab: h.HandleTabFrame, guards: guardNone},
+ {pattern: "POST /frame", root: h.HandleFrame, tab: h.HandleTabFrame, guards: guardNone},
+ {pattern: "GET /screenshot", root: h.HandleScreenshot, tab: h.HandleTabScreenshot, guards: guardDialogBlocked | guardDomainPolicy},
+ {pattern: "GET /annotate", root: h.HandleAnnotate, tab: h.HandleTabAnnotate, guards: guardDialogBlocked | guardDomainPolicy},
+ {pattern: "GET /capture", root: h.HandleCapture, tab: h.HandleTabCapture, guards: guardDialogBlocked | guardDomainPolicy},
+ {pattern: "GET /text", root: h.HandleText, tab: h.HandleTabText, guards: guardDialogBlocked | guardDomainPolicy},
+ {pattern: "GET /title", root: h.HandleTitle, tab: h.HandleTabTitle, guards: guardDialogBlocked | guardDomainPolicy},
+ {pattern: "GET /url", root: h.HandleURL, tab: h.HandleTabURL, guards: guardDialogBlocked | guardDomainPolicy},
+ {pattern: "GET /html", root: h.HandleHTML, tab: h.HandleTabHTML, guards: guardDialogBlocked | guardDomainPolicy},
+ {pattern: "GET /styles", root: h.HandleStyles, tab: h.HandleTabStyles, guards: guardDialogBlocked | guardDomainPolicy},
+ {pattern: "GET /value", root: h.HandleGetValue, tab: h.HandleTabGetValue, guards: guardDomainPolicy},
+ {pattern: "GET /attr", root: h.HandleGetAttr, tab: h.HandleTabGetAttr, guards: guardDomainPolicy},
+ {pattern: "GET /count", root: h.HandleCount, tab: h.HandleTabCount, guards: guardDomainPolicy},
+ {pattern: "GET /box", root: h.HandleGetBox, tab: h.HandleTabGetBox, guards: guardDomainPolicy},
+ {pattern: "GET /visible", root: h.HandleGetVisible, tab: h.HandleTabGetVisible, guards: guardDomainPolicy},
+ {pattern: "GET /enabled", root: h.HandleGetEnabled, tab: h.HandleTabGetEnabled, guards: guardDomainPolicy},
+ {pattern: "GET /checked", root: h.HandleGetChecked, tab: h.HandleTabGetChecked, guards: guardDomainPolicy},
+ {pattern: "GET /pdf", root: h.HandlePDF, tab: h.HandleTabPDF, guards: guardDialogBlocked | guardDomainPolicy},
+ {pattern: "POST /pdf", root: h.HandlePDF, tab: h.HandleTabPDF, guards: guardDialogBlocked | guardDomainPolicy},
+ {pattern: "POST /action", root: h.HandleAction, tab: h.HandleTabAction, guards: guardDialogBlocked | guardDomainPolicy | guardHandoffPause},
+ {pattern: "POST /actions", root: h.HandleActions, tab: h.HandleTabActions, guards: guardDomainPolicy},
+ {pattern: "POST /dialog", root: h.HandleDialog, tab: h.HandleTabDialog, guards: guardHandoffPause},
+ {pattern: "POST /wait", root: h.HandleWait, tab: h.HandleTabWait, guards: guardDomainPolicy},
+ {pattern: "POST /find", root: h.HandleFind, tab: h.HandleFind, guards: guardDomainPolicy},
+ {pattern: "POST /tab", root: h.HandleTab, guards: guardNone},
+ {pattern: "POST /close", root: h.HandleClose, tab: h.HandleTabClose, guards: guardNone},
+ {pattern: "POST /lock", root: h.HandleTabLock, tab: h.HandleTabLockByID, guards: guardNone},
+ {pattern: "POST /unlock", root: h.HandleTabUnlock, tab: h.HandleTabUnlockByID, guards: guardNone},
+ {pattern: "POST /handoff", tab: h.HandleTabHandoff, tabOnly: true, guards: guardDomainPolicy},
+ {pattern: "POST /resume", tab: h.HandleTabResume, tabOnly: true, guards: guardDomainPolicy},
+ {pattern: "GET /handoff", tab: h.HandleTabHandoffStatus, tabOnly: true, guards: guardNone},
+ {pattern: "GET /cookies", root: h.HandleGetCookies, tab: h.HandleTabGetCookies, guards: guardDomainPolicy},
+ {pattern: "POST /cookies", root: h.HandleSetCookies, tab: h.HandleTabSetCookies, guards: guardDomainPolicy},
+ {pattern: "DELETE /cookies", root: h.HandleClearCookies, tab: h.HandleTabClearCookies, guards: guardNone},
+ {pattern: "GET /metrics", root: h.HandleMetrics, tab: h.HandleTabMetrics, guards: guardNone},
+ {pattern: "GET /timing", root: h.HandleTiming, tab: h.HandleTabTiming, guards: guardDialogBlocked | guardDomainPolicy},
+ {pattern: "GET /a11y/audit", root: h.HandleA11yAudit, tab: h.HandleTabA11yAudit, guards: guardDialogBlocked | guardDomainPolicy},
+ {pattern: "POST /audit/page", root: h.HandleAuditPage, guards: guardNone},
+ {pattern: "POST /audit", root: h.HandleAudit, guards: guardNone},
+ {pattern: "POST /scrape", root: h.HandleScrape, guards: guardNone},
+ {pattern: "GET /network", root: h.HandleNetwork, tab: h.HandleTabNetwork, guards: guardDomainPolicy},
+ {pattern: "GET /network/stream", root: h.HandleNetworkStream, tab: h.HandleTabNetworkStream, guards: guardDomainPolicy},
+ {pattern: "GET /network/export", root: h.HandleNetworkExport, tab: h.HandleTabNetworkExport, guards: guardDomainPolicy},
+ {pattern: "GET /network/export/stream", root: h.HandleNetworkExportStream, tab: h.HandleTabNetworkExportStream, guards: guardDomainPolicy},
+ {pattern: "GET /network/{requestId}", root: h.HandleNetworkByID, tab: h.HandleTabNetworkByID, guards: guardDomainPolicy},
+ {pattern: "POST /network/clear", root: h.HandleNetworkClear, guards: guardNone},
+ {pattern: "GET /network/route", root: h.HandleNetworkRouteList, tab: h.HandleTabNetworkRouteList, guards: guardNone},
+ {pattern: "POST /network/route", root: h.HandleNetworkRoute, tab: h.HandleTabNetworkRoute, guards: guardDomainPolicy},
+ {pattern: "DELETE /network/route", root: h.HandleNetworkUnroute, tab: h.HandleTabNetworkUnroute, guards: guardDomainPolicy},
+ {pattern: "GET /console", root: h.HandleGetConsoleLogs, guards: guardDomainPolicy},
+ {pattern: "POST /console/clear", root: h.HandleClearConsoleLogs, guards: guardNone},
+ {pattern: "GET /errors", root: h.HandleGetErrorLogs, guards: guardDomainPolicy},
+ {pattern: "POST /errors/clear", root: h.HandleClearErrorLogs, guards: guardNone},
+ {pattern: "GET /clipboard/read", root: h.HandleClipboardRead, guards: guardNone},
+ {pattern: "POST /clipboard/write", root: h.HandleClipboardWrite, guards: guardNone},
+ {pattern: "POST /clipboard/copy", root: h.HandleClipboardCopy, guards: guardNone},
+ {pattern: "GET /clipboard/paste", root: h.HandleClipboardPaste, guards: guardNone},
+ {pattern: "GET /stealth/status", root: h.HandleStealthStatus, guards: guardNone},
+ {pattern: "POST /fingerprint/rotate", root: h.HandleFingerprintRotate, guards: guardDomainPolicy},
+ {pattern: "GET /solvers", root: h.HandleListSolvers, guards: guardNone},
+ {pattern: "GET /config/autosolver", root: h.HandleAutoSolverConfig, guards: guardNone},
+ {pattern: "POST /solve", root: h.HandleSolve, tab: h.HandleTabSolve, guards: guardDomainPolicy | guardHandoffPause},
+ {pattern: "POST /solve/{name}", root: h.HandleSolve, tab: h.HandleTabSolve, guards: guardDomainPolicy | guardHandoffPause},
+ {pattern: "POST /emulation/viewport", root: h.HandleSetViewport, tab: h.HandleTabSetViewport, guards: guardDomainPolicy},
+ {pattern: "POST /emulation/geolocation", root: h.HandleSetGeolocation, tab: h.HandleTabSetGeolocation, guards: guardDomainPolicy},
+ {pattern: "POST /emulation/offline", root: h.HandleSetOffline, tab: h.HandleTabSetOffline, guards: guardDomainPolicy},
+ {pattern: "POST /emulation/headers", root: h.HandleSetHeaders, tab: h.HandleTabSetHeaders, guards: guardDomainPolicy},
+ {pattern: "POST /emulation/credentials", root: h.HandleSetCredentials, tab: h.HandleTabSetCredentials, guards: guardDomainPolicy},
+ {pattern: "POST /emulation/media", root: h.HandleSetMedia, tab: h.HandleTabSetMedia, guards: guardDomainPolicy},
+ {pattern: "POST /cache/clear", root: h.HandleCacheClear, guards: guardNone},
+ {pattern: "GET /cache/status", root: h.HandleCacheStatus, guards: guardNone},
+ {pattern: "POST /storage", root: h.HandleStorage, tab: h.HandleTabStorageSet, guards: guardDomainPolicy},
+ {pattern: "DELETE /storage", root: h.HandleStorage, tab: h.HandleTabStorageDelete, guards: guardDomainPolicy},
+ {pattern: "GET /storage", root: h.HandleStorage, tab: h.HandleTabStorageGet, guards: guardDomainPolicy},
+ {pattern: "GET /state", root: h.HandleStateCurrent, guards: guardDomainPolicy},
+ {pattern: "GET /state/list", root: h.HandleStateList, guards: guardNone},
+ {pattern: "GET /state/show", root: h.HandleStateShow, guards: guardNone},
+ {pattern: "POST /state/save", root: h.HandleStateSave, guards: guardDomainPolicy},
+ {pattern: "POST /state/load", root: h.HandleStateLoad, guards: guardDomainPolicy},
+ {pattern: "DELETE /state", root: h.HandleStateDelete, guards: guardNone},
+ {pattern: "POST /state/clean", root: h.HandleStateClean, guards: guardNone},
+ {pattern: "POST /evaluate", root: h.HandleEvaluate, tab: h.HandleTabEvaluate, guards: guardDomainPolicy | guardHandoffPause},
+ {pattern: "POST /macro", root: h.HandleMacro, guards: guardDomainPolicy},
+ {pattern: "GET /download", root: h.HandleDownload, tab: h.HandleTabDownload, guards: guardDomainPolicy},
+ {pattern: "POST /upload", root: h.HandleUpload, tab: h.HandleTabUpload, guards: guardDomainPolicy | guardHandoffPause},
+ {pattern: "GET /screencast", root: h.HandleScreencast, guards: guardDomainPolicy},
+ {pattern: "GET /screencast/tabs", root: h.HandleScreencastAll, guards: guardNone},
+ {pattern: "POST /record/start", root: h.HandleRecordStart, guards: guardNone},
+ {pattern: "POST /record/stop", root: h.HandleRecordStop, guards: guardNone},
+ {pattern: "GET /record/status", root: h.HandleRecordStatus, guards: guardNone},
}
}
diff --git a/internal/handlers/tab_guards_test.go b/internal/handlers/tab_guards_test.go
new file mode 100644
index 00000000..c2a4c5cb
--- /dev/null
+++ b/internal/handlers/tab_guards_test.go
@@ -0,0 +1,301 @@
+package handlers
+
+import (
+ "context"
+ "encoding/json"
+ "net/http"
+ "net/http/httptest"
+ "os"
+ "path/filepath"
+ "strings"
+ "testing"
+ "time"
+
+ "github.com/pinchtab/pinchtab/internal/bridge"
+ "github.com/pinchtab/pinchtab/internal/config"
+ "github.com/pinchtab/pinchtab/internal/routes"
+ "github.com/pinchtab/pinchtab/internal/state"
+)
+
+// TestEveryBindingDeclaresItsGuardSet is the reason routeBinding carries guards
+// at all: an endpoint's tab policy has to be read off one catalog line, so the
+// no-guard case is written as guardNone rather than left to the zero value.
+func TestEveryBindingDeclaresItsGuardSet(t *testing.T) {
+ seen := 0
+ for _, b := range (*Handlers)(nil).bridgeBindings() {
+ seen++
+ if b.guards == 0 {
+ t.Errorf("%s declares no guard set; write guards: guardNone so the default is declared rather than inherited by omission", b.pattern)
+ continue
+ }
+ if b.guards&guardNone != 0 && b.guards != guardNone {
+ t.Errorf("%s combines guardNone with a real guard, so its line does not say what it enforces", b.pattern)
+ }
+ }
+ if seen == 0 {
+ t.Fatal("bridgeBindings() is empty, so this guard proves nothing")
+ }
+}
+
+// guardProbeBridge answers the two state lookups the guard chain consults —
+// handoff status and the tab's current URL — and nothing else, so a probe
+// observes the declared guard rather than whatever the handler does next.
+type guardProbeBridge struct {
+ mockBridge
+ paused bool
+ currentURL string
+}
+
+func (b *guardProbeBridge) SetTabHandoff(string, string, time.Duration) error { return nil }
+
+func (b *guardProbeBridge) ResumeTabHandoff(string) error { return nil }
+
+func (b *guardProbeBridge) TabHandoffState(string) (bridge.TabHandoffState, bool) {
+ if !b.paused {
+ return bridge.TabHandoffState{Status: "active"}, true
+ }
+ now := time.Now().UTC()
+ return bridge.TabHandoffState{
+ Status: "paused_handoff",
+ Reason: "manual_handoff",
+ PausedAt: now,
+ LastUpdatedAt: now,
+ }, true
+}
+
+func (b *guardProbeBridge) CurrentURL(context.Context) (string, error) { return b.currentURL, nil }
+
+// GetDialogManager is nil here so guardDialogBlocked resolves to "no dialog"
+// without CDP work: it runs first in the chain, and a probe that fails inside it
+// would never reach the guard under test.
+func (b *guardProbeBridge) GetDialogManager() *bridge.DialogManager { return nil }
+
+// guardProbe carries what a route needs to reach its guards. Guards run after
+// each handler's own validation, so a route that rejects {} never gets far
+// enough to refuse and its declaration would go unverified — the conformance
+// test fails naming the route until an entry lands here. wildcard fills path
+// wildcards other than {id}.
+type guardProbe struct {
+ body string
+ query string
+ wildcard string
+}
+
+var guardProbes = map[string]guardProbe{
+ "POST /navigate": {body: `{"url":"http://127.0.0.1:9/"}`},
+ "POST /tab": {body: `{"action":"new","url":"http://127.0.0.1:9/"}`},
+ "POST /action": {body: `{"kind":"click","selector":"#probe"}`},
+ "POST /actions": {body: `{"actions":[{"kind":"click","selector":"#probe"}]}`},
+ "POST /macro": {body: `{"steps":[{"kind":"click","selector":"#probe"}]}`},
+ "POST /dialog": {body: `{"action":"accept"}`},
+ "POST /wait": {body: `{"selector":"#probe"}`},
+ "POST /find": {body: `{"query":"probe"}`},
+ "POST /evaluate": {body: `{"expression":"1"}`},
+ "POST /upload": {body: `{"selector":"#probe","paths":["probe.txt"]}`},
+ "POST /solve/{name}": {wildcard: "cloudflare"},
+ "POST /cookies": {body: `{"cookies":[{"name":"probe","value":"1","domain":"127.0.0.1"}]}`},
+ "POST /emulation/viewport": {body: `{"width":800,"height":600}`},
+ "POST /emulation/headers": {body: `{"headers":{"X-Probe":"1"}}`},
+ "POST /emulation/credentials": {body: `{"username":"probe","password":"probe"}`},
+ "POST /emulation/media": {body: `{"feature":"prefers-color-scheme","value":"dark"}`},
+ "POST /storage": {body: `{"type":"local","key":"probe","value":"1"}`},
+ "POST /state/load": {body: `{"name":"probe"}`},
+ "GET /value": {query: "selector=%23probe"},
+ "GET /attr": {query: "selector=%23probe&name=id"},
+ "GET /count": {query: "selector=%23probe"},
+ "GET /box": {query: "selector=%23probe"},
+ "GET /visible": {query: "selector=%23probe"},
+ "GET /enabled": {query: "selector=%23probe"},
+ "GET /checked": {query: "selector=%23probe"},
+ "GET /download": {query: "url=http%3A%2F%2Fexample.com%2Ff.bin"},
+ "GET /network/export/stream": {query: "path=probe.har"},
+}
+
+// allCapabilities opens every capability gate: a 403 capability refusal answers
+// before the guard chain, which would make every gated route look unguarded.
+func allCapabilities(t *testing.T, tmpDir string) *config.RuntimeConfig {
+ t.Helper()
+ sandbox := filepath.Join(tmpDir, uploadSandboxDirName)
+ if err := os.MkdirAll(sandbox, 0o755); err != nil {
+ t.Fatalf("seed upload sandbox: %v", err)
+ }
+ if err := os.WriteFile(filepath.Join(sandbox, "probe.txt"), []byte("probe"), 0o644); err != nil {
+ t.Fatalf("seed upload probe file: %v", err)
+ }
+ sessions := state.SessionsDir(tmpDir)
+ if err := os.MkdirAll(sessions, 0o755); err != nil {
+ t.Fatalf("seed state sessions dir: %v", err)
+ }
+ if err := os.WriteFile(filepath.Join(sessions, "probe.json"), []byte("{}"), 0o644); err != nil {
+ t.Fatalf("seed state probe file: %v", err)
+ }
+ return &config.RuntimeConfig{
+ ActionTimeout: time.Second,
+ StateDir: tmpDir,
+ AllowEvaluate: true,
+ AllowMacro: true,
+ AllowScreencast: true,
+ AllowDownload: true,
+ AllowCookies: true,
+ AllowNetworkIntercept: true,
+ AllowUpload: true,
+ AllowStateExport: true,
+
+ DownloadAllowedDomains: []string{"example.com"},
+ }
+}
+
+// probeRoute drives one catalog endpoint through the real mux and reports the
+// refusal code it answered with. answered=false means the handler panicked on
+// the probe bridge, which is past the guard chain and so proves nothing either
+// way.
+func probeRoute(t *testing.T, b bridge.BridgeAPI, cfg *config.RuntimeConfig, ep routes.Endpoint) (code string, status int, answered bool) {
+ t.Helper()
+
+ h := New(b, cfg, nil, nil, nil)
+ mux := http.NewServeMux()
+ h.registerBridgeRoutes(mux)
+
+ route := ep.Route()
+ if ep.TabScoped {
+ route = ep.TabRoute()
+ }
+ probe := guardProbes[ep.Route()]
+ method, path, _ := strings.Cut(route, " ")
+ path = strings.ReplaceAll(path, "{id}", "tab1")
+ if probe.wildcard != "" {
+ path = strings.ReplaceAll(path, "{name}", probe.wildcard)
+ }
+ path = concreteRoutePath(path)
+ if probe.query != "" {
+ path += "?" + probe.query
+ }
+
+ w := httptest.NewRecorder()
+ answered = true
+ done := make(chan struct{})
+ go func() {
+ defer close(done)
+ defer func() {
+ if recover() != nil {
+ answered = false
+ }
+ }()
+ body := probe.body
+ if body == "" {
+ body = "{}"
+ }
+ req := httptest.NewRequest(method, path, strings.NewReader(body))
+ req.Header.Set("Content-Type", "application/json")
+ mux.ServeHTTP(w, req)
+ }()
+ select {
+ case <-done:
+ case <-time.After(10 * time.Second):
+ t.Fatalf("%s did not answer within the deadline", route)
+ }
+
+ var resp struct {
+ Code string `json:"code"`
+ }
+ _ = json.Unmarshal(w.Body.Bytes(), &resp)
+ return resp.Code, w.Code, answered
+}
+
+// guardedBindings pairs every catalog endpoint with the binding that declares
+// its guard set, so the conformance checks below walk the catalog rather than a
+// hand-kept list that could quietly stop covering a route.
+func guardedBindings(t *testing.T) []struct {
+ ep routes.Endpoint
+ b routeBinding
+} {
+ t.Helper()
+ bind := map[string]routeBinding{}
+ for _, b := range (*Handlers)(nil).bridgeBindings() {
+ bind[b.pattern] = b
+ }
+ var out []struct {
+ ep routes.Endpoint
+ b routeBinding
+ }
+ for _, ep := range routes.Core() {
+ b, ok := bind[ep.Route()]
+ if !ok {
+ t.Fatalf("catalog route %s has no binding", ep.Route())
+ }
+ out = append(out, struct {
+ ep routes.Endpoint
+ b routeBinding
+ }{ep, b})
+ }
+ if len(out) == 0 {
+ t.Fatal("the catalog is empty, so these conformance checks prove nothing")
+ }
+ return out
+}
+
+// TestDeclaredHandoffGuardMatchesTheRefusal is what stops the guards field being
+// decorative: every route that declares guardHandoffPause must actually refuse a
+// paused tab, and no route that omits it may. IDPI is off here so the domain
+// guard cannot answer first and mask the one under test.
+func TestDeclaredHandoffGuardMatchesTheRefusal(t *testing.T) {
+ checked, refusals := 0, 0
+ for _, row := range guardedBindings(t) {
+ t.Run(row.ep.Route(), func(t *testing.T) {
+ b := &guardProbeBridge{paused: true, currentURL: "https://allowed.example/"}
+ code, status, answered := probeRoute(t, b, allCapabilities(t, t.TempDir()), row.ep)
+ refused := code == handoffPausedCode
+ declared := row.b.guards&guardHandoffPause != 0
+
+ switch {
+ case declared && !refused:
+ t.Errorf("declares guardHandoffPause but a paused tab answered %d %q; either the declaration is wrong or the route needs a guardProbes entry that reaches its guards", status, code)
+ case !declared && refused && answered:
+ t.Errorf("refuses a paused tab without declaring guardHandoffPause, so its catalog line understates what it enforces")
+ }
+ checked++
+ if refused {
+ refusals++
+ }
+ })
+ }
+ if checked == 0 || refusals == 0 {
+ t.Fatalf("checked %d routes and saw %d handoff refusals; with none observed this test cannot tell a guard from its absence", checked, refusals)
+ }
+}
+
+// TestDeclaredDomainGuardMatchesTheRefusal is the same conformance check for the
+// IDPI current-tab domain policy, with the tab parked on a domain the allowlist
+// does not carry and handoff left active so it cannot answer instead.
+func TestDeclaredDomainGuardMatchesTheRefusal(t *testing.T) {
+ cfgFor := func(t *testing.T, tmpDir string) *config.RuntimeConfig {
+ cfg := allCapabilities(t, tmpDir)
+ cfg.IDPI = config.IDPIConfig{Enabled: true, StrictMode: true}
+ cfg.AllowedDomains = []string{"allowed.example", "127.0.0.1"}
+ return cfg
+ }
+
+ checked, refusals := 0, 0
+ for _, row := range guardedBindings(t) {
+ t.Run(row.ep.Route(), func(t *testing.T) {
+ b := &guardProbeBridge{currentURL: "https://blocked.example/page"}
+ code, status, answered := probeRoute(t, b, cfgFor(t, t.TempDir()), row.ep)
+ refused := code == idpiDomainBlockedCode
+ declared := row.b.guards&guardDomainPolicy != 0
+
+ switch {
+ case declared && !refused:
+ t.Errorf("declares guardDomainPolicy but an off-allowlist tab answered %d %q; either the declaration is wrong or the route needs a guardProbes entry that reaches its guards", status, code)
+ case !declared && refused && answered:
+ t.Errorf("blocks an off-allowlist tab without declaring guardDomainPolicy, so its catalog line understates what it enforces")
+ }
+ checked++
+ if refused {
+ refusals++
+ }
+ })
+ }
+ if checked == 0 || refusals == 0 {
+ t.Fatalf("checked %d routes and saw %d domain refusals; with none observed this test cannot tell a guard from its absence", checked, refusals)
+ }
+}