Skip to content

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

fix: an off-allowlist click traps the tab in 403 idpi_domain_blocked with no hint that back recovers it (PIN-081)

Luigi Agosti5c4d1c5eb002
diff --git a/internal/cli/apiclient/apierror_idpi_test.go b/internal/cli/apiclient/apierror_idpi_test.go
new file mode 100644
index 00000000..d3427bac
--- /dev/null
+++ b/internal/cli/apiclient/apierror_idpi_test.go
@@ -0,0 +1,82 @@
+package apiclient
+
+import (
+ "context"
+ "net/http/httptest"
+ "strings"
+ "testing"
+ "time"
+
+ "github.com/pinchtab/pinchtab/internal/bridge"
+ "github.com/pinchtab/pinchtab/internal/config"
+ "github.com/pinchtab/pinchtab/internal/handlers"
+)
+
+// driftedTabBody is the REAL /url response for a tab that navigated off the
+// allowlist, produced by driving the handler rather than hand-written here: a
+// literal body would only prove this test's own fixture renders, which is the
+// mistake that let the missing hint ship in the first place.
+func driftedTabBody(t *testing.T) []byte {
+ t.Helper()
+ b := &driftedTabBridge{
+ state: bridge.TabPolicyState{
+ CurrentURL: "https://www.iana.org/help/example-domains",
+ Blocked: true,
+ Reason: `domain "www.iana.org" is not in the allowed list (security.allowedDomains)`,
+ UpdatedAt: time.Now(),
+ },
+ }
+ h := handlers.New(b, &config.RuntimeConfig{
+ ActionTimeout: time.Second,
+ AllowedDomains: []string{"example.com"},
+ IDPI: config.IDPIConfig{Enabled: true, StrictMode: true},
+ }, nil, nil, nil)
+
+ rec := httptest.NewRecorder()
+ h.HandleURL(rec, httptest.NewRequest("GET", "/url?tabId=tab1", nil))
+ if rec.Code != 403 {
+ t.Fatalf("expected the drifted tab to be blocked, got %d: %s", rec.Code, rec.Body.String())
+ }
+ return rec.Body.Bytes()
+}
+
+// The dead end this closes was a rendering outcome, not just a payload one: the
+// user saw a 403 naming a config key and nothing else. Both lines must reach the
+// terminal, the same way the navguard 409 already does.
+func TestRenderAPIErrorBodyShowsDriftedTabHintAndBackRemedy(t *testing.T) {
+ out := renderAPIErrorBody(403, driftedTabBody(t))
+
+ for _, want := range []string{
+ "Error 403: current tab blocked by IDPI",
+ "πŸ’‘ ",
+ "Remedy: pinchtab back",
+ } {
+ if !strings.Contains(out, want) {
+ t.Errorf("rendered error missing %q:\n%s", want, out)
+ }
+ }
+ // The recovery line must not send the user at the allowlist: that widens the
+ // isolation the operator set, and it does not unstick the tab either.
+ if strings.Contains(out, "config set security.allowedDomains") {
+ t.Errorf("a drifted tab must not be offered the allowlist widening:\n%s", out)
+ }
+}
+
+// driftedTabBridge answers only what the /url read path touches before the domain
+// policy refuses; everything else would be a bug in this test, not a real call.
+type driftedTabBridge struct {
+ bridge.BridgeAPI
+ state bridge.TabPolicyState
+}
+
+func (b *driftedTabBridge) EnsureBrowser(*config.RuntimeConfig) error { return nil }
+
+func (b *driftedTabBridge) TabContext(tabID string) (*bridge.TabHandle, string, error) {
+ return bridge.NewTabHandle(context.Background()), tabID, nil
+}
+
+func (b *driftedTabBridge) GetTabPolicyState(string) (bridge.TabPolicyState, bool) {
+ return b.state, true
+}
+
+func (b *driftedTabBridge) SetTabPolicyState(string, bridge.TabPolicyState) {}
diff --git a/internal/handlers/idpi_domain_block.go b/internal/handlers/idpi_domain_block.go
new file mode 100644
index 00000000..8ce4c2d3
--- /dev/null
+++ b/internal/handlers/idpi_domain_block.go
@@ -0,0 +1,75 @@
+package handlers
+
+import (
+ "fmt"
+ "net/http"
+ "strings"
+
+ "github.com/pinchtab/pinchtab/internal/httpx"
+ "github.com/pinchtab/pinchtab/internal/navguard"
+)
+
+// idpiDomainBlockedCode is the one code every IDPI domain block reports, so a
+// client can switch on it whether the tab drifted, a requested URL was refused,
+// or a navigation was blocked. The nav site used to answer with the generic
+// "error" code, which left the most common way to hit the allowlist as the one
+// case a consumer could not classify.
+const idpiDomainBlockedCode = "idpi_domain_blocked"
+
+// The drifted-tab block describes where the tab IS, not what the caller asked
+// for, so its remedy must not name the allowlist: widening it is precisely the
+// change the operator's allowlist exists to prevent, and an agent that follows
+// that lead erodes the posture instead of recovering. Going back does recover β€”
+// no navigation or history endpoint consults this guard, so `back` can always
+// reach a tab the read verbs have locked out.
+const idpiDriftedTabHint = "the tab navigated to a domain outside security.allowedDomains, so this page was never read β€” the block describes where the tab is, not what you asked for. Do not widen the allowlist to get past it."
+
+const idpiDriftedTabRemedy = "pinchtab back (returns the tab to the previous allowed page; use pinchtab nav <allowed-url> when there is no history entry, or close the tab)"
+
+// A refused target URL is the opposite case: nothing navigated, there is nothing
+// to recover from, and the allowlist genuinely is the only lever β€” so this is the
+// only remedy that names it, and the only place that guidance is rendered.
+const idpiRefusedURLHint = "the requested URL is outside security.allowedDomains, so the request was refused and nothing navigated. Allowing it widens what automation may reach β€” see docs/guides/security.md."
+
+// writeIDPIDomainBlocked is the single writer of an IDPI domain-block refusal, so
+// the status and code cannot differ between the three sites that produce one.
+func writeIDPIDomainBlocked(w http.ResponseWriter, message string, details map[string]any) {
+ httpx.ErrorCode(w, http.StatusForbidden, idpiDomainBlockedCode, message, false, details)
+}
+
+func idpiDriftedTabDetails(url string) map[string]any {
+ return idpiBlockDetails(url, idpiDriftedTabHint, idpiDriftedTabRemedy)
+}
+
+func idpiRefusedURLDetails(url string) map[string]any {
+ return idpiBlockDetails(url, idpiRefusedURLHint, idpiAllowlistRemedy(url))
+}
+
+func idpiBlockDetails(url, hint, remedy string) map[string]any {
+ details := map[string]any{
+ "hint": hint,
+ "url": url,
+ }
+ if remedy != "" {
+ details["remedy"] = remedy
+ }
+ // The domain is a discrete field as well as prose so MCP and dashboard
+ // consumers do not have to parse the sentence to learn what was blocked.
+ if host, ok := navguard.ExtractHost(url); ok && strings.TrimSpace(host) != "" {
+ details["domain"] = host
+ }
+ return details
+}
+
+// idpiAllowlistRemedy is the copy-pasteable widening of the allowlist, appending
+// to the current value rather than replacing it. A hostless target (about:blank)
+// cannot be allowlisted at all, so it gets no remedy instead of one that cannot
+// work.
+func idpiAllowlistRemedy(url string) string {
+ host, ok := navguard.ExtractHost(url)
+ if !ok || strings.TrimSpace(host) == "" {
+ return ""
+ }
+ return fmt.Sprintf("pinchtab config set security.allowedDomains "+
+ "\"$(pinchtab config get security.allowedDomains),%s\" then: pinchtab server restart", host)
+}
diff --git a/internal/handlers/idpi_domain_block_test.go b/internal/handlers/idpi_domain_block_test.go
new file mode 100644
index 00000000..6cd30bbc
--- /dev/null
+++ b/internal/handlers/idpi_domain_block_test.go
@@ -0,0 +1,174 @@
+package handlers
+
+import (
+ "encoding/json"
+ "net/http/httptest"
+ "strings"
+ "testing"
+ "time"
+
+ "github.com/pinchtab/pinchtab/internal/bridge"
+ "github.com/pinchtab/pinchtab/internal/config"
+)
+
+func idpiBlockingConfig() *config.RuntimeConfig {
+ return &config.RuntimeConfig{
+ ActionTimeout: time.Second,
+ AllowCookies: true,
+ AllowedDomains: []string{"example.com"},
+ IDPI: config.IDPIConfig{Enabled: true, StrictMode: true},
+ }
+}
+
+type blockedResponse struct {
+ Code string `json:"code"`
+ Error string `json:"error"`
+ Details map[string]any `json:"details"`
+}
+
+func decodeBlocked(t *testing.T, w *httptest.ResponseRecorder) blockedResponse {
+ t.Helper()
+ if w.Code != 403 {
+ t.Fatalf("status = %d, want 403: %s", w.Code, w.Body.String())
+ }
+ var resp blockedResponse
+ if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
+ t.Fatalf("decode response: %v (body %s)", err, w.Body.String())
+ }
+ if resp.Code != idpiDomainBlockedCode {
+ t.Errorf("code = %q, want %q β€” a consumer must be able to classify every IDPI domain block the same way", resp.Code, idpiDomainBlockedCode)
+ }
+ return resp
+}
+
+func detailString(t *testing.T, details map[string]any, key string) string {
+ t.Helper()
+ value, ok := details[key].(string)
+ if !ok || value == "" {
+ t.Fatalf("details.%s missing or empty; details = %v", key, details)
+ }
+ return value
+}
+
+// The reported dead end: every read verb answered 403 with no hint and no remedy,
+// and the only actionable string in the message was the allowlist config key β€”
+// the one change that must NOT be made to recover a tab that merely drifted.
+func TestDriftedTabBlockOffersBackNotTheAllowlist(t *testing.T) {
+ b := &policyMockBridge{
+ state: bridge.TabPolicyState{
+ CurrentURL: "https://www.iana.org/help/example-domains",
+ Blocked: true,
+ Reason: `domain "www.iana.org" is not in the allowed list (security.allowedDomains)`,
+ UpdatedAt: time.Now(),
+ },
+ hasState: true,
+ }
+ h := New(b, idpiBlockingConfig(), nil, nil, nil)
+
+ w := httptest.NewRecorder()
+ h.HandleURL(w, httptest.NewRequest("GET", "/url?tabId=tab1", nil))
+
+ resp := decodeBlocked(t, w)
+ remedy := detailString(t, resp.Details, "remedy")
+ if !strings.Contains(remedy, "pinchtab back") {
+ t.Errorf("remedy = %q, want the recovery that actually works (back)", remedy)
+ }
+ if strings.Contains(remedy, "security.allowedDomains") {
+ t.Errorf("remedy = %q must not point a drifted tab at the allowlist; widening it is the change the allowlist exists to prevent", remedy)
+ }
+ hint := detailString(t, resp.Details, "hint")
+ if !strings.Contains(strings.ToLower(hint), "never read") && !strings.Contains(strings.ToLower(hint), "was never") {
+ t.Errorf("hint = %q should say the page was never read", hint)
+ }
+ if got := detailString(t, resp.Details, "domain"); got != "www.iana.org" {
+ t.Errorf("details.domain = %q, want the blocked domain as a discrete field", got)
+ }
+ if got := detailString(t, resp.Details, "url"); got != "https://www.iana.org/help/example-domains" {
+ t.Errorf("details.url = %q", got)
+ }
+}
+
+// enforceURLDomainPolicy is reached only from the cookie endpoints, so it needs
+// its own case: a test against /navigate would leave this site untested.
+func TestRefusedCookieURLBlockNamesTheAllowlist(t *testing.T) {
+ // The current tab must be ON the allowlist, or the drifted-tab check refuses
+ // first and this test asserts on the wrong site's remedy.
+ b := &policyMockBridge{
+ state: bridge.TabPolicyState{
+ CurrentURL: "https://example.com/",
+ Blocked: false,
+ UpdatedAt: time.Now(),
+ },
+ hasState: true,
+ }
+ h := New(b, idpiBlockingConfig(), nil, nil, nil)
+
+ w := httptest.NewRecorder()
+ h.HandleGetCookies(w, httptest.NewRequest("GET", "/cookies?tabId=tab1&url=https://www.iana.org/help", nil))
+
+ resp := decodeBlocked(t, w)
+ remedy := detailString(t, resp.Details, "remedy")
+ if !strings.Contains(remedy, "security.allowedDomains") {
+ t.Errorf("remedy = %q; for a refused URL the allowlist genuinely is the only lever", remedy)
+ }
+ if strings.Contains(remedy, "pinchtab back") {
+ t.Errorf("remedy = %q; nothing navigated, so there is nothing to go back to", remedy)
+ }
+ if got := detailString(t, resp.Details, "domain"); got != "www.iana.org" {
+ t.Errorf("details.domain = %q", got)
+ }
+}
+
+// The nav site used to answer with the generic "error" code and append the
+// allowlist guidance to the MESSAGE. Both are now the shared shape.
+func TestBlockedNavigateCarriesTheSharedCodeAndRemedy(t *testing.T) {
+ h := New(&policyMockBridge{}, idpiBlockingConfig(), nil, nil, nil)
+
+ w := httptest.NewRecorder()
+ h.HandleNavigate(w, httptest.NewRequest("GET", "/navigate?url=https://www.iana.org/help", nil))
+
+ resp := decodeBlocked(t, w)
+ if !strings.Contains(resp.Error, "navigation blocked by IDPI") {
+ t.Errorf("error = %q, want the navigate-site wording", resp.Error)
+ }
+ if !strings.Contains(detailString(t, resp.Details, "remedy"), "security.allowedDomains") {
+ t.Errorf("details.remedy = %v", resp.Details["remedy"])
+ }
+}
+
+// A contains-check would pass happily on doubled guidance, which is exactly the
+// assertion that would let the duplication ship: the message must no longer carry
+// the allowlist instructions now that details.remedy does.
+func TestAllowlistGuidanceIsRenderedExactlyOnce(t *testing.T) {
+ h := New(&policyMockBridge{}, idpiBlockingConfig(), nil, nil, nil)
+
+ w := httptest.NewRecorder()
+ h.HandleNavigate(w, httptest.NewRequest("GET", "/navigate?url=https://www.iana.org/help", nil))
+ resp := decodeBlocked(t, w)
+
+ if got := strings.Count(resp.Error, "security.allowedDomains"); got > 1 {
+ t.Errorf("the error message names the allowlist %d times: %q", got, resp.Error)
+ }
+ if strings.Contains(resp.Error, "config set security.allowedDomains") {
+ t.Errorf("the message still carries the config-set guidance that details.remedy now renders: %q", resp.Error)
+ }
+
+ rendered := resp.Error + "\n" + detailString(t, resp.Details, "hint") + "\n" + detailString(t, resp.Details, "remedy")
+ if got := strings.Count(rendered, "config set security.allowedDomains"); got != 1 {
+ t.Errorf("the copy-pasteable allowlist command appears %d times in the rendered output, want exactly 1:\n%s", got, rendered)
+ }
+}
+
+// The two sites must not share one string, which is the whole reason the card
+// rejected a single shared remedy.
+func TestTheTwoBlockSitesGiveDifferentRemedies(t *testing.T) {
+ drifted := idpiDriftedTabDetails("https://www.iana.org/help")
+ refused := idpiRefusedURLDetails("https://www.iana.org/help")
+
+ if drifted["remedy"] == refused["remedy"] {
+ t.Fatalf("both sites render the same remedy %q; a drifted tab recovers with back, a refused URL does not", drifted["remedy"])
+ }
+ if drifted["hint"] == refused["hint"] {
+ t.Errorf("both sites render the same hint %q", drifted["hint"])
+ }
+}
diff --git a/internal/handlers/navigation.go b/internal/handlers/navigation.go
index 97a8e417..22703750 100644
--- a/internal/handlers/navigation.go
+++ b/internal/handlers/navigation.go
@@ -190,19 +190,6 @@ func (h *Handlers) resolveNavigateBrowser(w http.ResponseWriter, r *http.Request
return routing, true
}
-// idpiAllowlistHint appends a copy-pasteable remediation to an IDPI domain-block
-// error so the user isn't left knowing only the cause. Widening the allowlist
-// reduces isolation, so the hint says so and points at the security guide.
-func idpiAllowlistHint(url string) string {
- host, ok := navguard.ExtractHost(url)
- if !ok || strings.TrimSpace(host) == "" {
- return ""
- }
- return fmt.Sprintf(". To allow it, run: pinchtab config set security.allowedDomains "+
- "\"$(pinchtab config get security.allowedDomains),%s\" then: pinchtab server restart "+
- "(this widens what automation may reach β€” see docs/guides/security.md)", host)
-}
-
// idpiScannerHint appends remediation to an IDPI content-scanner block, which
// otherwise states only the cause. Unlike the domain allowlist, a scanner block
// can be a false positive on legitimate pages, so the fix is to relax strict mode
@@ -225,7 +212,9 @@ func (h *Handlers) validateNavigateTargets(w http.ResponseWriter, r *http.Reques
domainResult := h.IDPIGuard.CheckDomain(url)
if domainResult.Blocked {
h.recordNavigateRequest(r, tabID, url)
- httpx.Error(w, http.StatusForbidden, fmt.Errorf("navigation blocked by IDPI: %s%s", domainResult.Reason, idpiAllowlistHint(url)))
+ writeIDPIDomainBlocked(w,
+ fmt.Sprintf("navigation blocked by IDPI: %s", domainResult.Reason),
+ idpiRefusedURLDetails(url))
return navTargets{}, false
}
if domainResult.Threat {
diff --git a/internal/handlers/navigation_idpi_hint_test.go b/internal/handlers/navigation_idpi_hint_test.go
index 69c0aef0..4769eab0 100644
--- a/internal/handlers/navigation_idpi_hint_test.go
+++ b/internal/handlers/navigation_idpi_hint_test.go
@@ -5,29 +5,35 @@ import (
"testing"
)
-func TestIDPIAllowlistHint(t *testing.T) {
- hint := idpiAllowlistHint("https://example.com/some/path")
- if !strings.Contains(hint, "example.com") {
- t.Errorf("hint should name the blocked host; got %q", hint)
+// The allowlist guidance used to be appended to the error MESSAGE. It now lives
+// in details.remedy, which the CLI renders on its own line β€” but it has to keep
+// the properties that made it usable: name the host, append to the current value
+// instead of replacing it, and carry no placeholder a user would paste literally.
+func TestIDPIAllowlistRemedy(t *testing.T) {
+ remedy := idpiAllowlistRemedy("https://example.com/some/path")
+ if !strings.Contains(remedy, "example.com") {
+ t.Errorf("remedy should name the blocked host; got %q", remedy)
}
- if !strings.Contains(hint, "security.allowedDomains") {
- t.Errorf("hint should name the allowlist config key; got %q", hint)
+ if !strings.Contains(remedy, "security.allowedDomains") {
+ t.Errorf("remedy should name the allowlist config key; got %q", remedy)
}
- if !strings.Contains(hint, "server restart") {
- t.Errorf("hint should remind the user to restart; got %q", hint)
+ if !strings.Contains(remedy, "server restart") {
+ t.Errorf("remedy should remind the user to restart; got %q", remedy)
}
- // Must be copy-paste-safe: no "…" placeholder (which users paste literally),
- // and it should preserve existing domains via a `config get` append.
- if strings.ContainsRune(hint, '…') {
- t.Errorf("hint must not contain the … placeholder; got %q", hint)
+ if strings.ContainsRune(remedy, '…') {
+ t.Errorf("remedy must not contain the … placeholder; got %q", remedy)
}
- if !strings.Contains(hint, "config get security.allowedDomains") {
- t.Errorf("hint should append to existing domains via config get; got %q", hint)
+ if !strings.Contains(remedy, "config get security.allowedDomains") {
+ t.Errorf("remedy should append to existing domains via config get; got %q", remedy)
}
- // Hostless targets (e.g. about:blank) can't be allowlisted, so no hint.
- if got := idpiAllowlistHint("about:blank"); got != "" {
- t.Errorf("expected empty hint for hostless url; got %q", got)
+ // A hostless target cannot be allowlisted, so it gets no remedy rather than
+ // one that cannot work.
+ if got := idpiAllowlistRemedy("about:blank"); got != "" {
+ t.Errorf("expected no remedy for a hostless url; got %q", got)
+ }
+ if _, ok := idpiRefusedURLDetails("about:blank")["remedy"]; ok {
+ t.Error("a hostless refused URL must not carry a remedy")
}
}
diff --git a/internal/handlers/tab_policy.go b/internal/handlers/tab_policy.go
index eb8aebdf..28f24e87 100644
--- a/internal/handlers/tab_policy.go
+++ b/internal/handlers/tab_policy.go
@@ -82,10 +82,9 @@ func (h *Handlers) applyTabPolicyState(w http.ResponseWriter, state bridge.TabPo
w.Header().Set("X-IDPI-Warning", state.Reason)
}
if state.Blocked {
- httpx.ErrorCode(w, http.StatusForbidden, "idpi_domain_blocked",
- fmt.Sprintf("current tab blocked by IDPI: %s", state.Reason), false, map[string]any{
- "url": state.CurrentURL,
- })
+ writeIDPIDomainBlocked(w,
+ fmt.Sprintf("current tab blocked by IDPI: %s", state.Reason),
+ idpiDriftedTabDetails(state.CurrentURL))
return state.CurrentURL, false
}
return state.CurrentURL, true
@@ -101,10 +100,9 @@ func (h *Handlers) enforceURLDomainPolicy(w http.ResponseWriter, url string) boo
state := bridge.EvaluateTabPolicy(url, h.Config.IDPI, h.Config.AllowedDomains)
if state.Blocked {
- httpx.ErrorCode(w, http.StatusForbidden, "idpi_domain_blocked",
- fmt.Sprintf("url blocked by IDPI: %s", state.Reason), false, map[string]any{
- "url": url,
- })
+ writeIDPIDomainBlocked(w,
+ fmt.Sprintf("url blocked by IDPI: %s", state.Reason),
+ idpiRefusedURLDetails(url))
return false
}
return true