Make iframe previews local-first with an external-origin warning and allowlist

[nedtwigg]

Iframe previews are primarily for local development tools: dev servers, Storybook, and similar applications. External documentation is a useful convenience, but this renderer should not try to provide a full authenticated browser experience.

Follow-up to #571. Ship that PR as-is; this enhancement is separate. Keep its ambient Cookie/Set-Cookie stripping, with no cookie jar in this first iteration.

Proposed behavior

• Allow local loopback targets normally. Define local by the actual loopback destination; arbitrary private-network addresses or hostname string matches do not qualify automatically.
• Before opening a non-allowlisted external origin in the iframe renderer, show a prominent warning identifying the destination, with Open in browser, Allow this origin, and Cancel actions.
• Scope allowlist entries to an exact origin (scheme, hostname, and port). Make entries removable; decide persistence scope during implementation.
• Apply the policy to the initial URL and subsequent cross-origin navigation, including redirects, forms, and script-driven navigation. A click handler or a notification after navigation is not a sufficient gate. Establish what can be enforced in both VS Code and Tauri before choosing the mechanism.
• Approval permits a preview; it does not enable cookie authentication or expand supported URL schemes. The current proxy supports HTTP upstreams only. Unsupported targets should retain a clear way to open in another renderer/browser.

Suggested warning copy:

External website preview

Dormouse's iframe proxy changes website security protections to support local development. Do not sign in or enter sensitive information here.

Avoid claiming that every external page is necessarily vulnerable to XSS. The concrete concern is that proxy rewriting changes browser protections; allowing an origin does not make authenticated use safe.

Cookie support: defer until real tools require it

Do not add a cookie jar, cookie emulation, per-proxy IP allocation, or authenticated external browsing in this issue. Native JavaScript cookies on the shared loopback hostname remain a documented limitation; an allowlist is not cookie isolation.

As actual local tools fail, capture the tool/version, host/platform, reproduction, expected workflow, and the cookie behavior needed (server-managed session, JavaScript cookie access, CSRF, WebSockets, etc.). Use those stories to define a separate cookie enhancement and its compatibility tests.

A future jar must address caller authorization before attaching stored credentials. Restricting upstreams to localhost does not by itself prevent an unrelated caller from using a logged-in proxy session.

Implementation references

• docs/specs/dor-browser.md — iframe renderer and target policy
• docs/specs/security-local.md — browser-pane and loopback-listener boundaries
• lib/src/host/iframe-proxy.ts — target handling and redirects
• lib/src/host/iframe-proxy-rewrite.ts — injected navigation reporting

Update the owning specs when implementing the enhancement. Validate the warning/allowlist in both hosts, including initial navigation, cross-origin transitions, cancellation, and preserved local-tool behavior.

[dormouse-bot]

Two things worth settling before the mechanism choice, since both bear on "what can be enforced in both VS Code and Tauri."

The navigation gate already exists and is the same in both hosts. Each shipped webview CSP pins frame-src to loopback — webview-html.ts:76 and tauri.conf.json:26. A grant's origin is loopback, so an external origin is reachable only through a minted grant, and any navigation that would leave the proxy origin — redirect, form post, location.assign — is refused by the browser before the request. That is the non-click-handler gate the issue asks for, and it needs no new enforcement machinery; the policy reduces to deciding whether createIframeProxyUrl (iframe-proxy.ts:116) mints a grant at all. IframePanel re-calls it on every URL change including observed in-frame navigation (IframePanel.tsx:179), so that one chokepoint already sees the initial URL and every subsequent target, and IframeProxyResult is the natural carrier for a third ok: false variant.

One case escapes that chokepoint: a cross-origin redirect. sanitizeResponseHeaders rewrites Location onto the proxy origin only when it already starts with the grant's upstream origin (iframe-proxy.ts:355-357); a foreign Location is forwarded verbatim, the frame tries to navigate straight at it, and frame-src blocks it — so it fails closed, but as a blank pane with no explanation. The proxy is the only party that sees that hop, so the warning for it has to be served from the proxy origin, the way serveErrorPage already does, rather than surfaced through the panel. The existing coverage is the same-origin rewrite case only (iframe-proxy.test.ts:217).

"Local by the actual loopback destination" has no classifier yet. isBlockedAddress (iframe-proxy-rewrite.ts:257) only refuses link-local/metadata, and the one loopback helper in the tree — servesLoopback in lib/src/components/wall/port-url.ts — is exactly the hostname-string form this issue rules out. Resolving for real means a dns.lookup(..., { all: true }) requiring every result to be loopback, and pinning that address into the grant: handleRequest and handleUpgrade pass grant.upstream.hostname and re-resolve per request (:238, :382), so a name that resolves to 127.0.0.1 at classification time can resolve elsewhere at connect time. Host is already set to grant.upstream.host, so pinning to a resolved address doesn't break name-based vhosts upstream.

What I checked

Read at acc17ade: lib/src/host/iframe-proxy.ts, lib/src/host/iframe-proxy-rewrite.ts, lib/src/host/loopback-guard.ts, lib/src/lib/platform/iframe-proxy-types.ts, lib/src/components/wall/IframePanel.tsx, lib/src/components/wall/port-url.ts, vscode-ext/src/webview-html.ts, standalone/src-tauri/tauri.conf.json, plus docs/specs/dor-browser.md → "Iframe Renderer" / "Dev-Server Chip" and docs/specs/security-local.md → "Loopback Listeners".

No allowlist, approval prompt, or warning interstitial exists in the tree today. The frame-src claim is from both hosts' shipped CSP strings, not inferred from the specs — docs/specs/vscode.md:222-225 states the VS Code half and gives the blank-white-pane symptom, which is the same symptom the cross-origin redirect produces.

No PR opened: the persistence scope and the interstitial's placement are open design decisions in the issue body, and #571 is still in flight over these files.