Enforce secure nested-document lifecycle for Code OSS webviews

[wieslawsoltes]

Current nested-lifecycle checkpoint — 19 September 2026

Main is 2b64b08965aeba5ecbd33fcc0bd1beaaceaf6243. The audit found a real missing lifecycle contract after merged Permissions Policy, script-CSP, generation and pagehide work.

Active branch feature/iframe-beforeunload-lifecycle-267 in /Users/wieslawsoltes/GitHub/.worktrees/WebScene-beforeunload-267, exact base 2b64b089, implements synchronous cancelable nested beforeunload before authored iframe navigation/document replacement. A veto must preserve the current realm, document generation and pending tasks; reentrant self-navigation is blocked without blocking sibling document work. No commit exists yet.

Only git diff --check runs. WPT-derived regression, unchanged Markdown Preview and the full nested-consumer matrix remain authored/scheduled but unexecuted.

Parent epic: #264. Top-level release epic: #227.

Proven gap

After service-worker readiness, unchanged browser/pre/index.html creates a nested iframe, sets a sandbox and Permissions Policy, navigates it to fake.html, reads contentWindow/contentDocument, then calls document.open(), write(), and close() with extension HTML. Updates replace the active frame. The prelude observes DOMContentLoaded/load/beforeunload, posts messages across the frame, uses ResizeObserver, preserves scroll, and removes stale frames.

WebScene's capability record at b81f594c explicitly limits iframe support to an initial same-origin document and leaves navigated src/srcdoc, history, sandboxing, origin transitions, cross-origin access control, complete load/error order, repeated-navigation teardown, and arbitrary iframe rendering outside the claim. No CSP enforcement implementation was found in the audited runtime. #253 owns the sandbox DOMTokenList and token semantics; this issue owns the resulting browsing-context, document, origin, CSP, Permissions Policy, navigation, and replacement behavior.

Dependencies and boundaries

• Depends on Expose HTMLIFrameElement.sandbox for Code OSS webviews and Markdown Preview #253 and the service-worker/resource issues.
• Uses Provide crypto.subtle through a vetted cross-platform provider #102 for the already-implemented parent-origin SHA-256 and Implement Worker, transferable MessagePort, and iframe contexts for Code OSS #81 for MessagePort/postMessage.
• Coordinates with AppScene#31 and [GPU 19/20] Qualify WebGPU/WebGL conformance, resilience and support claims #41. The secure boundary belongs in reusable WebScene document contexts.
• The audited product endpoint is an origin-partitioned https://{{uuid}}.vscode-cdn.net/... URL and the outer workbench CSP permits https://*.vscode-cdn.net frames. Native acceptance must preserve equivalent origin separation even when packaged transport is not HTTP.
• Establish Chromium/AppScene visual and geometry regression gates for unchanged Code OSS #259 owns the shared visual oracle, Qualify Code OSS accessibility semantics, keyboard navigation, and native exposure #262 release-wide accessibility, and Publish a Code OSS Web API capability ledger and expand WPT coverage #263 the API/WPT ledger; this issue supplies their nested-document evidence.

Acceptance

• Selected HTML iframe/navigation, WindowProxy, origin, CSP, sandbox, Permissions Policy, DOM parsing/writing, and lifecycle WPTs pass with checked-in Chromium results and explicit exclusions.
• Native top-level + nested fixtures cover src, srcdoc, fake.html, base URL, initial about:blank, realm/constructor identity, contentWindow/contentDocument, parent/top/frameElement, same-origin access, opaque sandbox origins, cross-origin denial, postMessage target/origin, CSP nonces/sources, permissions, and links/download/navigation admission.
• open/write/close, update replacement, reload, detach during load, error, beforeunload/pagehide, observer disconnect, and shutdown produce browser-order events and reject callbacks from stale generations.
• 100 create/load/write/replace/reload/detach cycles leave zero old realms, WindowProxy targets, documents, observers, ports, fetches, and scene nodes. A 1 MiB HTML update reaches load and first stable scene at p95 <= 250 ms; retained growth after warm-up <= 8 MiB.
• Markdown CSP blocks disallowed scripts/resources while permitting its nonce, styles, images, and local-resource origins; sandbox flags never silently broaden access.
• The same contracts cover notebook output, custom editor, webview view/panel, release notes, chat/MCP, Mermaid, and Simple Browser documents.

Proposed PR stack

1. navigation and WindowProxy/realm identity;
2. document open/write/close and replacement lifecycle;
3. origin/CSP/Permissions Policy enforcement;
4. teardown/performance/WPT and unchanged webview acceptance.

[wieslawsoltes]

Added native child #399 for the first reproduced unchanged-Code blocker after #392: preserve the same-origin iframe WindowProxy and pre-navigation DOMContentLoaded subscription through fake.html navigation, then allow the navigated Document's open/write/close replacement. Chrome 153 passes the focused sequence; exact main 93780758 times out before the lifecycle callback. Scope excludes #393 CSS paths and all cross-origin/CSP/admission/traversal expansion.

[wieslawsoltes]

#399 is complete via #402, merged at 51f71381bda9015b64cf0566534e209f8bfa9986.

The unchanged Code OSS Markdown iframe bootstrap now keeps a stable same-origin WindowProxy across navigation and document.open/write/close, delivers the navigated document lifecycle, and cleans retained listeners across 100 teardown cycles. Chrome 153 passed 6/6; the focused native gate passed with p95 3.176 ms, flat measured heap (1,359,228 bytes), and bounded RSS (40.9 -> 89.9 MiB). Opaque/cross-origin frames remain fail-closed. Linux, macOS, portable V8, native-document, and NativeAOT 11/12 checks passed on exact PR head 400316f638e4e031cab2378722c421863d9a6032; unrelated NuGet packaging was canceled.

[wieslawsoltes]

Current-main audit after the implementation-only #268 slices: #267 remains open and unchanged at cumulative main 4ea2feebd0dd7f2f08dfa1a8bfbbe1ca5f3d6c3b.

The merged Select All and command-capability work does not widen iframe origin, sandbox, CSP, Permissions Policy, navigation, or resource admission. Remaining #267 implementation still includes CSP nonce/source enforcement for Markdown, Permissions Policy, broader same-origin/opaque/cross-origin navigation behavior, reload/error/beforeunload/pagehide ordering, stale-generation rejection, and repeated replacement/detach teardown. Its required WPT/Chromium/native/security/performance and exact unchanged-product evidence remains outstanding.

[wieslawsoltes]

#448 is complete via #450, merged as aa276b17c42eee22dd067f6872afc4b2d02f4034 from the current-main baseline a263f4e.

The reusable nested-document policy path now reflects HTMLIFrameElement.allow and enforces inherited iframe Permissions Policy admission for the two unchanged VS Code OSS clipboard features, clipboard-read and clipboard-write. The parser covers default same-origin behavior, bare/source-origin delegation, self, src, *, none, and explicit origins. Denied calls reject with NotAllowedError before native host handoff; existing user-activation, MIME, quota, and host-request checks remain in force.

This closes the smallest proven Permissions Policy gap used by webviewElement.ts and browser/pre/index.html. CSP enforcement, response-header policy, other policy-controlled features, cross-origin WindowProxy work, and the broader navigation/teardown matrix remain open in #267.

Validation debt is deliberate under the implementation-only directive: no focused tests, benchmarks, broad native build, package qualification, or CI wait was run. The generated WebIDL binding was regenerated and git diff --check passed after rebasing; cumulative validation remains assigned to #264/#267.

[wieslawsoltes]

#454 is complete via #455, merged as a2f873e822fd83af9a41013989aabbf94b520bf3 after rebasing onto current main 580f177c18b067bd6b11aef9d7b2b2e400804a0d.

Nested iframe hydration now reads the first effective meta Content Security Policy in parser order and applies script-src-elem, script-src, or default-src fallback before speculative fetch and evaluation. This preserves the prelude-injected API script that precedes the meta policy, admits unchanged Markdown's nonce-bearing scripts, handles bounded unsafe-inline, self, scheme, explicit-origin, and wildcard-host sources, and reflects the active script nonce.

The focused boundary does not claim response-header CSP, style/image/font/media/connect/frame/worker directives, violation events/reporting, hash sources, dynamic insertion, or multiple-policy intersection; those remain in #267.

Validation debt is deliberate under the implementation-only directive: no focused tests, benchmarks, broad native build, package qualification, or CI wait was run. git diff --check passed before the required rebase; cumulative security and unchanged-product validation remains assigned to #264/#267.

[wieslawsoltes]

#460 is complete via #461, merged as c19fbc36ddd36d23eb9116b354295acf05ee9e58 after rebasing onto current main 1d663aeb825fd12ac1f9c3822a65a4c53fd07b1f.

Each authored iframe src navigation and document.open() replacement now advances a per-frame generation. Navigation clears stale response bytes, retires an earlier preparation future without blocking the new one, deduplicates queued hydration, and binds async preparation plus cooperative script/DOMContentLoaded/load continuation to the captured generation. Detach and top-level teardown retire the generation state. This closes the same-URL/source-race path where older work was previously identified only by frame ID and source text.

Full location.reload(), history traversal, beforeunload/pagehide, cross-origin WindowProxy behavior, error-event ordering, and performance qualification remain in #267.

Validation debt is deliberate under the implementation-only directive: no focused tests, benchmarks, broad native build, package qualification, or CI wait was run. git diff --check passed before the required rebase; cumulative lifecycle and unchanged-product validation remains assigned to #264/#267.

[wieslawsoltes]

#466 is complete via #467, merged as 6363114a6b75c6d5905adabd491820194ed4e174 after rebasing onto current main b383afc181e4794ef7b7f5266cb8f5d51c6c41b1.

The outgoing nested Window now receives one non-bubbling, non-cancelable pagehide with persisted === false before navigation generation advances or iframe detach cancels realm tasks. The one-shot guard resets when a replacement realm becomes active and is cleared on teardown. This covers unchanged VS Code's oldActiveFrame.remove() replacement and Markdown Editor's pagehide scroll-state persistence hook.

beforeunload cancellation, visibility transitions, unload, explicit reload/history, cross-origin proxies, and broad event-order validation remain in #267. This is the final implementation slice in the current wave.

Validation debt is deliberate under the implementation-only directive: no focused tests, benchmarks, broad native build, package qualification, or CI wait was run. git diff --check passed before the required rebase; cumulative lifecycle and unchanged-product validation remains assigned to #264/#267.