Skip to content

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

feat: add opt-in file:// navigation scheme gated by security.allowFileScheme

Bosch0d57b2751470
diff --git a/dashboard/src/pages/settings/settingsShared.ts b/dashboard/src/pages/settings/settingsShared.ts
index 84089d2b..e1febedf 100644
--- a/dashboard/src/pages/settings/settingsShared.ts
+++ b/dashboard/src/pages/settings/settingsShared.ts
@@ -109,6 +109,11 @@ export const securityEndpointRows = [
"Allow network interception",
"Lets agents install rules to abort or fulfill (mock) HTTP requests on a tab. When on, response forgery is FORBIDDEN on hosts in 'Allowed websites' below and PERMITTED elsewhere. Forging responses on hosts you've authorized the agent to use (e.g. your bank) is the highest-risk outcome — that's why allowlisted hosts are protected, not the reverse. OPTIONS preflights are skipped by default to avoid breaking CORS.",
],
+ [
+ "allowFileScheme",
+ "Allow file:// navigation",
+ "Lets agents open local file:// URLs. A file:// URL has no host, so it is NOT limited by 'Allowed websites' below and bypasses SSRF/private-IP protection — enabling it grants read access (via snapshot/screenshot/scrape) to any local file the server process can read. It stays blocked while a strict-mode allowlist is active. Enable only on trusted, single-tenant machines.",
+ ],
] as const satisfies ReadonlyArray<
| readonly [SecurityEndpointKey, string]
| readonly [SecurityEndpointKey, string, string]
diff --git a/dashboard/src/pages/settings/useSettingsController.ts b/dashboard/src/pages/settings/useSettingsController.ts
index dc1d78ed..162786ca 100644
--- a/dashboard/src/pages/settings/useSettingsController.ts
+++ b/dashboard/src/pages/settings/useSettingsController.ts
@@ -122,6 +122,7 @@ export function useSettingsController(): UseSettingsControllerResult {
backendConfig.security.allowDownload,
backendConfig.security.allowCookies,
backendConfig.security.allowUpload,
+ backendConfig.security.allowFileScheme,
].some(Boolean)
: false;
const apiTokenMissing = !backendState?.tokenConfigured;
diff --git a/dashboard/src/types/index.ts b/dashboard/src/types/index.ts
index d6f411f2..c1a9b898 100644
--- a/dashboard/src/types/index.ts
+++ b/dashboard/src/types/index.ts
@@ -151,6 +151,7 @@ export interface BackendSecurityConfig {
allowCookies: boolean;
allowUpload: boolean;
allowNetworkIntercept: boolean;
+ allowFileScheme: boolean;
allowedDomains: string[];
trustedProxyCIDRs: string[];
trustedResolveCIDRs: string[];
@@ -302,6 +303,7 @@ export const defaultBackendConfig: BackendConfig = {
allowCookies: false,
allowUpload: false,
allowNetworkIntercept: false,
+ allowFileScheme: false,
allowedDomains: ["127.0.0.1", "localhost", "::1"],
trustedProxyCIDRs: [],
trustedResolveCIDRs: [],
diff --git a/docs/guides/security.md b/docs/guides/security.md
index d1b79ea4..66b6ec67 100644
--- a/docs/guides/security.md
+++ b/docs/guides/security.md
@@ -194,6 +194,7 @@ Some endpoint families expose much more power than normal navigation and inspect
- `security.allowDownload`
- `security.allowCookies`
- `security.allowUpload`
+- `security.allowFileScheme`
Why they are considered dangerous:
@@ -203,6 +204,7 @@ Why they are considered dangerous:
- `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, write, or clear browser session tokens for the current page
- `upload` can push local files into browser flows
+- `allowFileScheme` permits navigation to `file://` URLs. Because a `file://` URL has no host, it is **not** subject to `allowedDomains` or the SSRF/private-IP guard, so enabling it grants read access (via snapshot/screenshot/scrape) to any local file the server process can read. It stays blocked when a strict-mode `allowedDomains` allowlist is active. Enable only on trusted, single-tenant hosts. `javascript:`, `chrome://`, and `data:` remain rejected regardless.
These are not the same as authentication.
diff --git a/docs/reference/config.md b/docs/reference/config.md
index cd54ec5b..bbb3a3b2 100644
--- a/docs/reference/config.md
+++ b/docs/reference/config.md
@@ -227,6 +227,7 @@ Current nested file-config shape:
"allowScreencast": false,
"allowDownload": false,
"allowCookies": false,
+ "allowFileScheme": false,
"allowedDomains": ["127.0.0.1", "localhost", "::1"],
"downloadAllowedDomains": [],
"downloadMaxBytes": 20971520,
diff --git a/internal/config/config_file_json.go b/internal/config/config_file_json.go
index 0e887965..8e78059f 100644
--- a/internal/config/config_file_json.go
+++ b/internal/config/config_file_json.go
@@ -84,6 +84,7 @@ type securityConfigJSON struct {
AllowDownload *bool `json:"allowDownload"`
AllowCookies *bool `json:"allowCookies"`
AllowNetworkIntercept *bool `json:"allowNetworkIntercept"`
+ AllowFileScheme *bool `json:"allowFileScheme"`
AllowedDomains []string `json:"allowedDomains"`
DownloadAllowedDomains []string `json:"downloadAllowedDomains"`
DownloadMaxBytes *int `json:"downloadMaxBytes"`
diff --git a/internal/config/config_file_marshal.go b/internal/config/config_file_marshal.go
index 37d2f9f1..a8b6bcda 100644
--- a/internal/config/config_file_marshal.go
+++ b/internal/config/config_file_marshal.go
@@ -211,6 +211,7 @@ func (fc FileConfig) MarshalJSON() ([]byte, error) {
AllowDownload: fc.Security.AllowDownload,
AllowCookies: fc.Security.AllowCookies,
AllowNetworkIntercept: fc.Security.AllowNetworkIntercept,
+ AllowFileScheme: fc.Security.AllowFileScheme,
AllowedDomains: effectiveSecurityAllowedDomains(fc.Security),
DownloadAllowedDomains: copyStringSlice(fc.Security.DownloadAllowedDomains),
DownloadMaxBytes: fc.Security.DownloadMaxBytes,
@@ -368,6 +369,7 @@ func FileConfigFromRuntime(cfg *RuntimeConfig) FileConfig {
allowDownload := cfg.AllowDownload
allowCookies := cfg.AllowCookies
allowNetworkIntercept := cfg.AllowNetworkIntercept
+ allowFileScheme := cfg.AllowFileScheme
downloadAllowedDomains := copyStringSlice(cfg.DownloadAllowedDomains)
downloadMaxBytes := cfg.EffectiveDownloadMaxBytes()
allowUpload := cfg.AllowUpload
@@ -489,6 +491,7 @@ func FileConfigFromRuntime(cfg *RuntimeConfig) FileConfig {
AllowDownload: &allowDownload,
AllowCookies: &allowCookies,
AllowNetworkIntercept: &allowNetworkIntercept,
+ AllowFileScheme: &allowFileScheme,
AllowedDomains: append([]string(nil), cfg.AllowedDomains...),
DownloadAllowedDomains: downloadAllowedDomains,
DownloadMaxBytes: &downloadMaxBytes,
diff --git a/internal/config/config_load.go b/internal/config/config_load.go
index 0aad6bd5..0109cbed 100644
--- a/internal/config/config_load.go
+++ b/internal/config/config_load.go
@@ -155,6 +155,7 @@ func LoadConfig() (*RuntimeConfig, []LoadDiagnostic, error) {
AllowDownload: false,
AllowCookies: false,
AllowNetworkIntercept: false,
+ AllowFileScheme: false,
RetainNetworkBodies: false,
RetainNetworkBodyMaxBytes: 256 * 1024,
AllowedDomains: append([]string(nil), defaultLocalAllowedDomains...),
@@ -385,6 +386,9 @@ func applyFileConfig(cfg *RuntimeConfig, fc *FileConfig) {
if fc.Security.AllowNetworkIntercept != nil {
cfg.AllowNetworkIntercept = *fc.Security.AllowNetworkIntercept
}
+ if fc.Security.AllowFileScheme != nil {
+ cfg.AllowFileScheme = *fc.Security.AllowFileScheme
+ }
cfg.DownloadAllowedDomains = append([]string(nil), fc.Security.DownloadAllowedDomains...)
if fc.Security.DownloadMaxBytes != nil {
cfg.DownloadMaxBytes = clampPositiveLimit(*fc.Security.DownloadMaxBytes, DefaultDownloadMaxBytes, MaxDownloadMaxBytes)
diff --git a/internal/config/config_types.go b/internal/config/config_types.go
index 817ea21f..3dbdcd3b 100644
--- a/internal/config/config_types.go
+++ b/internal/config/config_types.go
@@ -24,6 +24,7 @@ type RuntimeConfig struct {
AllowDownload bool
AllowCookies bool
AllowNetworkIntercept bool
+ AllowFileScheme bool
// AllowedDomains is the unified per-instance allowlist sourced from
// security.allowedDomains in the file config.
AllowedDomains []string
@@ -409,6 +410,7 @@ type SecurityConfig struct {
AllowDownload *bool `json:"allowDownload,omitempty"`
AllowCookies *bool `json:"allowCookies,omitempty"`
AllowNetworkIntercept *bool `json:"allowNetworkIntercept,omitempty"`
+ AllowFileScheme *bool `json:"allowFileScheme,omitempty"`
AllowedDomains []string `json:"allowedDomains,omitempty"`
DownloadAllowedDomains []string `json:"downloadAllowedDomains,omitempty"`
DownloadMaxBytes *int `json:"downloadMaxBytes,omitempty"`
diff --git a/internal/config/editor_get.go b/internal/config/editor_get.go
index 3b5dccf9..c552f3a0 100644
--- a/internal/config/editor_get.go
+++ b/internal/config/editor_get.go
@@ -330,6 +330,8 @@ func getSecurityField(s *SecurityConfig, field string) (string, error) {
return formatBoolPtr(s.AllowCookies), nil
case "allowNetworkIntercept":
return formatBoolPtr(s.AllowNetworkIntercept), nil
+ case "allowFileScheme":
+ return formatBoolPtr(s.AllowFileScheme), nil
case "allowedDomains":
return strings.Join(s.AllowedDomains, ","), nil
case "downloadAllowedDomains":
diff --git a/internal/config/editor_set.go b/internal/config/editor_set.go
index b68c573c..93ef0e6d 100644
--- a/internal/config/editor_set.go
+++ b/internal/config/editor_set.go
@@ -523,6 +523,8 @@ func setSecurityField(s *SecurityConfig, field, value string) error {
s.AllowUpload = &b
case "allowNetworkIntercept":
s.AllowNetworkIntercept = &b
+ case "allowFileScheme":
+ s.AllowFileScheme = &b
case "enableActionGuards":
s.EnableActionGuards = &b
case "trustLoopbackProxy":
diff --git a/internal/handlers/navigation.go b/internal/handlers/navigation.go
index b08ae533..4c85e76f 100644
--- a/internal/handlers/navigation.go
+++ b/internal/handlers/navigation.go
@@ -16,6 +16,7 @@ import (
"github.com/pinchtab/pinchtab/internal/browsers"
"github.com/pinchtab/pinchtab/internal/config"
"github.com/pinchtab/pinchtab/internal/httpx"
+ "github.com/pinchtab/pinchtab/internal/navguard"
)
// HandleNavigate navigates a tab to a URL or creates a new tab.
@@ -191,7 +192,8 @@ func (h *Handlers) resolveNavigateBrowser(w http.ResponseWriter, r *http.Request
// target resolution, recording the navigate request on both the blocked and
// accepted paths. On success it returns the resolved target and trusted-proxy CIDRs.
func (h *Handlers) validateNavigateTargets(w http.ResponseWriter, r *http.Request, tabID, url string, effectiveCfg *config.RuntimeConfig) (navTargets, bool) {
- if err := validateNavigateURL(url); err != nil {
+ allowFile := effectiveCfg != nil && effectiveCfg.AllowFileScheme
+ if err := validateNavigateURL(url, allowFile); err != nil {
httpx.Error(w, 400, err)
return navTargets{}, false
}
@@ -206,6 +208,14 @@ func (h *Handlers) validateNavigateTargets(w http.ResponseWriter, r *http.Reques
w.Header().Set("X-IDPI-Warning", domainResult.Reason)
}
+ // file:// has no network target, so SSRF/private-IP resolution does not apply.
+ // It has already passed the explicit-opt-in scheme gate and the IDPI domain
+ // guard above (strict-mode allowlists block it via the empty-host path).
+ if allowFile && navguard.IsFileURL(url) {
+ h.recordNavigateRequest(r, tabID, url)
+ return navTargets{target: &validatedNavigateTarget{AllowInternal: true}, trustedCIDRs: buildNavigateTrustedProxyCIDRs(effectiveCfg)}, true
+ }
+
trustedResolveCIDRs := parseCIDRs(effectiveCfg.TrustedResolveCIDRs)
target, err := validateNavigateTarget(url, h.IDPIGuard.DomainAllowed(url), trustedResolveCIDRs)
if err != nil {
diff --git a/internal/handlers/navigation_policy.go b/internal/handlers/navigation_policy.go
index 79c3a65a..c05b7603 100644
--- a/internal/handlers/navigation_policy.go
+++ b/internal/handlers/navigation_policy.go
@@ -84,8 +84,8 @@ func installNavigateRuntimeGuardWithBridge(b bridge.BridgeAPI, tCtx context.Cont
type validatedNavigateTarget = navguard.ValidatedTarget
-func validateNavigateURL(raw string) error {
- return navguard.ValidateURL(raw)
+func validateNavigateURL(raw string, allowFile bool) error {
+ return navguard.ValidateURLAllowingFile(raw, allowFile)
}
// Per-call Validator construction is intentional: trusted CIDRs come from the
diff --git a/internal/handlers/navigation_test.go b/internal/handlers/navigation_test.go
index a72d006d..ebae4987 100644
--- a/internal/handlers/navigation_test.go
+++ b/internal/handlers/navigation_test.go
@@ -85,12 +85,28 @@ func TestValidateNavigateURL_RejectsUnsupportedSchemes(t *testing.T) {
"chrome://settings",
"data:text/html,hello",
} {
- if err := validateNavigateURL(rawURL); err == nil {
+ if err := validateNavigateURL(rawURL, false); err == nil {
t.Fatalf("validateNavigateURL(%q) should reject unsupported schemes", rawURL)
}
}
}
+func TestValidateNavigateURL_GatesFileScheme(t *testing.T) {
+ const fileURL = "file:///tmp/pinchtab.html"
+ if err := validateNavigateURL(fileURL, false); err == nil {
+ t.Fatal("validateNavigateURL(file, false) should reject file:// when not opted in")
+ }
+ if err := validateNavigateURL(fileURL, true); err != nil {
+ t.Fatalf("validateNavigateURL(file, true) error = %v", err)
+ }
+ // The opt-in is scoped to file:// only; other schemes stay rejected.
+ for _, rawURL := range []string{"javascript:alert(1)", "chrome://settings", "data:text/html,hello"} {
+ if err := validateNavigateURL(rawURL, true); err == nil {
+ t.Fatalf("validateNavigateURL(%q, true) should still reject", rawURL)
+ }
+ }
+}
+
func TestValidateNavigateTarget_AllowsLocalHosts(t *testing.T) {
for _, rawURL := range []string{
"http://localhost:9867",
@@ -192,7 +208,7 @@ func TestValidateNavigateURL_AllowsHTTPHTTPSAndBareHostnames(t *testing.T) {
"pinchtab.com",
"about:blank",
} {
- if err := validateNavigateURL(rawURL); err != nil {
+ if err := validateNavigateURL(rawURL, false); err != nil {
t.Fatalf("validateNavigateURL(%q) error = %v", rawURL, err)
}
}
@@ -200,7 +216,7 @@ func TestValidateNavigateURL_AllowsHTTPHTTPSAndBareHostnames(t *testing.T) {
func TestValidateNavigateURL_RejectsOverlongURL(t *testing.T) {
rawURL := "https://pinchtab.com/" + strings.Repeat("a", navguard.MaxURLLen)
- if err := validateNavigateURL(rawURL); err == nil {
+ if err := validateNavigateURL(rawURL, false); err == nil {
t.Fatal("validateNavigateURL should reject overlong urls")
}
}
@@ -224,6 +240,56 @@ func TestHandleNavigate_RejectsUnsupportedSchemeBeforeCreateTab(t *testing.T) {
}
}
+func TestHandleNavigate_AllowsFileSchemeWhenEnabled(t *testing.T) {
+ m := &mockBridge{}
+ h := New(m, &config.RuntimeConfig{AllowFileScheme: true}, nil, nil, nil)
+
+ req := httptest.NewRequest("POST", "/navigate", bytes.NewReader([]byte(`{"url":"file:///tmp/pinchtab.html"}`)))
+ w := httptest.NewRecorder()
+ h.HandleNavigate(w, req)
+
+ if w.Code != 200 && w.Code != 500 {
+ t.Fatalf("expected file scheme navigate to proceed past validation, got %d: %s", w.Code, w.Body.String())
+ }
+ if len(m.createTabURLs) == 0 {
+ t.Fatal("expected CreateTab to be called for opted-in file scheme navigation")
+ }
+}
+
+func TestHandleTab_AllowsFileSchemeWhenEnabled(t *testing.T) {
+ m := &mockBridge{}
+ h := New(m, &config.RuntimeConfig{AllowFileScheme: true}, nil, nil, nil)
+
+ body := `{"action":"new","url":"file:///tmp/pinchtab.html"}`
+ req := httptest.NewRequest("POST", "/tab", bytes.NewReader([]byte(body)))
+ w := httptest.NewRecorder()
+ h.HandleTab(w, req)
+
+ if w.Code != 200 && w.Code != 500 {
+ t.Fatalf("expected file scheme tab creation to proceed, got %d: %s", w.Code, w.Body.String())
+ }
+ if len(m.createTabURLs) == 0 {
+ t.Fatal("expected CreateTab to be called for opted-in file scheme tab creation")
+ }
+}
+
+func TestHandleTab_RejectsFileSchemeWhenDisabled(t *testing.T) {
+ m := &mockBridge{}
+ h := New(m, &config.RuntimeConfig{}, nil, nil, nil)
+
+ body := `{"action":"new","url":"file:///etc/passwd"}`
+ req := httptest.NewRequest("POST", "/tab", bytes.NewReader([]byte(body)))
+ w := httptest.NewRecorder()
+ h.HandleTab(w, req)
+
+ if w.Code != 400 {
+ t.Fatalf("expected 400 for file scheme when AllowFileScheme is off, got %d: %s", w.Code, w.Body.String())
+ }
+ if len(m.createTabURLs) != 0 {
+ t.Fatalf("CreateTab should not be called for rejected file scheme, got %v", m.createTabURLs)
+ }
+}
+
func TestHandleNavigate_RejectsUnsupportedSchemeForExistingTab(t *testing.T) {
h := New(&mockBridge{}, &config.RuntimeConfig{}, nil, nil, nil)
diff --git a/internal/navguard/navguard_test.go b/internal/navguard/navguard_test.go
index de3a65af..3cebdd00 100644
--- a/internal/navguard/navguard_test.go
+++ b/internal/navguard/navguard_test.go
@@ -58,6 +58,46 @@ func TestValidateURL_RejectsEmpty(t *testing.T) {
}
}
+func TestValidateURLAllowingFile_GatesFileScheme(t *testing.T) {
+ const fileURL = "file:///tmp/pinchtab.html"
+
+ if err := ValidateURLAllowingFile(fileURL, false); err == nil {
+ t.Fatal("ValidateURLAllowingFile(file, false) should reject file:// scheme")
+ }
+ if err := ValidateURL(fileURL); err == nil {
+ t.Fatal("ValidateURL should reject file:// scheme by default")
+ }
+
+ if err := ValidateURLAllowingFile(fileURL, true); err != nil {
+ t.Fatalf("ValidateURLAllowingFile(file, true) error = %v", err)
+ }
+
+ for _, rawURL := range []string{"https://pinchtab.com", "http://pinchtab.test", "pinchtab.com", "about:blank"} {
+ if err := ValidateURLAllowingFile(rawURL, true); err != nil {
+ t.Fatalf("ValidateURLAllowingFile(%q, true) error = %v", rawURL, err)
+ }
+ }
+
+ for _, rawURL := range []string{"javascript:alert(1)", "chrome://settings", "data:text/html,hello"} {
+ if err := ValidateURLAllowingFile(rawURL, true); err == nil {
+ t.Fatalf("ValidateURLAllowingFile(%q, true) should still reject", rawURL)
+ }
+ }
+}
+
+func TestIsFileURL(t *testing.T) {
+ for _, rawURL := range []string{"file:///etc/passwd", "FILE:///tmp/x.html"} {
+ if !IsFileURL(rawURL) {
+ t.Fatalf("IsFileURL(%q) = false, want true", rawURL)
+ }
+ }
+ for _, rawURL := range []string{"https://pinchtab.com", "http://pinchtab.test", "about:blank", "pinchtab.com"} {
+ if IsFileURL(rawURL) {
+ t.Fatalf("IsFileURL(%q) = true, want false", rawURL)
+ }
+ }
+}
+
func TestValidateTarget_AllowsLocalHosts(t *testing.T) {
v := &Validator{}
for _, rawURL := range []string{
diff --git a/internal/navguard/url.go b/internal/navguard/url.go
index b15d5635..6bb78460 100644
--- a/internal/navguard/url.go
+++ b/internal/navguard/url.go
@@ -19,6 +19,10 @@ func (v *Validator) ValidateURL(raw string) error {
// ValidateURL is the standalone (non-method) URL validator, usable without a
// Validator instance.
func ValidateURL(raw string) error {
+ return ValidateURLAllowingFile(raw, false)
+}
+
+func ValidateURLAllowingFile(raw string, allowFile bool) error {
raw = strings.TrimSpace(raw)
if raw == "" {
return fmt.Errorf("url required")
@@ -41,11 +45,24 @@ func ValidateURL(raw string) error {
switch strings.ToLower(parsed.Scheme) {
case "http", "https":
return nil
+ case "file":
+ if allowFile {
+ return nil
+ }
+ return fmt.Errorf("invalid URL scheme: %s", parsed.Scheme)
default:
return fmt.Errorf("invalid URL scheme: %s", parsed.Scheme)
}
}
+func IsFileURL(raw string) bool {
+ parsed, err := url.Parse(strings.TrimSpace(raw))
+ if err != nil {
+ return false
+ }
+ return strings.EqualFold(parsed.Scheme, "file")
+}
+
// ExtractHost extracts the hostname from a raw URL string.
// Returns the lowercase, dot-trimmed host and true if found.
func ExtractHost(raw string) (string, bool) {
diff --git a/skills/pinchtab/SKILL.md b/skills/pinchtab/SKILL.md
index 03aabdd9..2bfcd612 100644
--- a/skills/pinchtab/SKILL.md
+++ b/skills/pinchtab/SKILL.md
@@ -105,6 +105,7 @@ Key settings agents may need to change:
- `security.allowEvaluate`: enable `eval` command (`true`/`false`)
- `security.allowScreencast`: enable `record` commands (`true`/`false`)
- `security.allowedDomains`: list of allowed hostnames (e.g. `["localhost", "127.0.0.1"]`)
+- `security.allowFileScheme`: allow `nav` to open `file://` local files (`true`/`false`, default `false`; grants local file read and is not constrained by `allowedDomains`)
- `instanceDefaults.mode`: `"headless"` or `"headed"` (string, not boolean)
After changing config with the server running, restart to apply: `pinchtab server restart`.
diff --git a/skills/pinchtab/TRUST.md b/skills/pinchtab/TRUST.md
index 5de29009..4ee53bd3 100644
--- a/skills/pinchtab/TRUST.md
+++ b/skills/pinchtab/TRUST.md
@@ -31,6 +31,7 @@ High-impact capabilities are **disabled by default** and require explicit config
| File downloads | **Disabled** | `security.allowDownloads` |
| File uploads | **Disabled** | `security.allowUploads` |
| Network interception | **Disabled** | `security.allowNetworkIntercept` |
+| `file://` navigation | **Disabled** | `security.allowFileScheme`; grants read access to local files the server can read, and `file://` has no host so it is **not** constrained by `allowedDomains` or the SSRF guard — enable only on trusted, single-tenant hosts |
| Challenge solving (autoSolver) | **Disabled** | `autoSolver.enabled`; requires explicit opt-in per deployment |
| Stealth level | **Light** (minimal) | `instanceDefaults.stealthLevel`; `light` applies only basic fingerprint normalization — anti-bot bypass requires `medium` or `full`, which must be set explicitly |
| Navigation domains | **Local-only allowlist** | `security.allowedDomains` (restrict or expand deliberately) |
@@ -95,7 +96,7 @@ For maximum confidence, use the npm package (`npm install -g pinchtab`) or Docke
PinchTab runs a separate Chrome process with:
- Isolated profile directory (default: `~/.pinchtab`)
-- No access to your user's home files (unless you explicitly navigate to `file://` URLs)
+- No access to your user's home files — `file://` navigation is rejected unless `security.allowFileScheme` is explicitly enabled
- Standard Chrome security model (site isolation, CSP, etc.)
Use `profiles.baseDir`, `profiles.defaultProfile`, or `PINCHTAB_CONFIG` if you need to control where PinchTab stores browser state.
diff --git a/skills/pinchtab/references/commands.md b/skills/pinchtab/references/commands.md
index dab48751..4013388b 100644
--- a/skills/pinchtab/references/commands.md
+++ b/skills/pinchtab/references/commands.md
@@ -63,6 +63,8 @@ pinchtab nav https://pinchtab.com --tab <tabId>
| `--block-ads` | Block ads for this navigation |
| `--print-tab-id` | Print only the tab ID |
+Only `http`/`https` URLs are accepted by default. `file://` (for opening a local HTML file) is rejected unless the server is started with `security.allowFileScheme` enabled — and even then it is blocked when a strict-mode domain allowlist is active, since `file://` has no host. `javascript:`, `chrome://`, and `data:` are always rejected.
+
### `pinchtab tab` (not `tabs`)
Manage browser tabs.