[Stage 3] Web APIs to be exposed to ShadowRealms #393
Description
Back in September 2023, TC39 agreed to move this proposal to Stage 2 setting a missing requirement for Stage 3 to provide a list of suitable APIs to be exposed to ShadowRealms, along with sufficient tests to ensure correct behaviour in implementations.
Salesforce is currently working with Igalia to organize this work. Igalia produced the following list mapping all the names below:
Web APIs exposed in ShadowRealm
Defined in WebIDL as of whatwg/html#9893.
Checklist indicates which APIs are already covered in WPT.
(Checklist updated by @ptomato)
- AbortController
- AbortSignal (except AbortSignal.timeout)
- addEventListener
- atob
- btoa
- ByteLengthQueuingStrategy
- CompressionStream
- console
- CountQueuingStrategy
- crypto - pending agreement by webcrypto spec
- CustomEvent
- DataCloneError
- DOMException
- PR merged Enable ShadowRealm testing for DOMException web-platform-tests/wpt#49159
- Also used extensively throughout other tests covered here.
- DecompressionStream
- dispatchEvent
- ErrorEvent
- This requires converting the existing test from an HTML file to a JavaScript file with
// META: global=window,worker,shadowrealmheader
- This requires converting the existing test from an HTML file to a JavaScript file with
- Event
- EventTarget
- Observable
- PromiseRejectionEvent
- This requires converting the existing test from an HTML file to a JavaScript file with
// META: global=window,worker,shadowrealmheader
- This requires converting the existing test from an HTML file to a JavaScript file with
- queueMicrotask
- ReadableByteStreamController
- ReadableStream
- ReadableStreamBYOBReader
- ReadableStreamBYOBRequest
- ReadableStreamDefaultController
- ReadableStreamDefaultReader
- removeEventListener
- self
- structuredClone
- Subscriber
- TextDecoder
- TextDecoderStream
- TextEncoder
- TextEncoderStream
- TransformStream
- TransformStreamDefaultController
- This is barely covered by wpt. IDL tests in Enable shadowrealm testing for streams api (tests with dependencies) web-platform-tests/wpt#42005
- URL
- URLPattern - pending agreement by urlpattern spec
- URLSearchParams
- WebAssembly (except WebAssembly.compileStreaming and WebAssembly.instantiateStreaming)
- WritableStream
- WritableStreamDefaultController
- WritableStreamDefaultWriter
In Progress
Additional names being added within specs PRs and WPT coverage:
- atob
- btoa
- crypto.getRandomValues
- structuredClone (would bring in DataCloneError)
- URLPattern - note Chromium-only for now, but standards positions from WebKit and Mozilla are positive
Additional rationale regarding Workers
With rationale for not exposing in ShadowRealm:
- browser state: ShadowRealm code shouldn't be able to access any information about the browser or its global state.
- canvas: Without the ability to pass objects into a ShadowRealm it doesn't make much sense to include HTML canvas APIs with no way to display the canvas.
- host access: ShadowRealm code shouldn't be able to access information about or resources on the host.
- multimedia: ShadowRealm code doesn't need to do anything with multimedia APIs, since there's no way to display multimedia.
- network access: ShadowRealm code shouldn't be able to access the network.
- secure context: ShadowRealm isn't a secure context, so APIs annotated with
[SecureContext]aren't exposed. - timers: ShadowRealm code shouldn't be able to access timing information other than through
DateandTemporal.Now. - workers: ShadowRealm can't launch workers.
-
- communication channels: ShadowRealm doesn't include communication channels such as web sockets, postMessage, etc. This is a level of I/O that is more broad than ShadowRealm should have by default.
Inclusion criteria from specs that are at least Candidate Recommendation, omitting any W3C Working Drafts, API drafts from WICG, etc. Also omitting worker-specific APIs only exposed in workers and not also in window.
- AbortSignal.timeout - timers
- BroadcastChannel - communication channels
- CacheStorage - secure context, workers
- caches - secure context, workers
- Cache - secure context, workers
- cancelAnimationFrame - timers
- CanvasGradient - canvas
- CanvasPattern - canvas
- clearInterval - timers
- clearTimeout - timers
- CloseEvent - network access
- createImageBitmap - canvas
- crossOriginIsolated - network access
- CryptoKey - secure context
- Crypto (except for getRandomValues) - secure context
- DOMStringList - legacy and tightly linked to the DOM
- EventSource - network access
- fetch - network access
- FileSystemDirectoryHandle - secure context, host access
- FileSystemFileHandle - secure context, host access
- FileSystemHandle - secure context, host access
- FileSystemSyncAccessHandle - secure context, host access
- FileSystemWritableFileStream - secure context, host access
- FormData - network access
- Headers - network access
- IDBCursorWithValue - browser state
- IDBCursor - browser state
- IDBDatabase - browser state
- IDBFactory - browser state
- IDBIndex - browser state
- IDBKeyRange - browser state
- IDBObjectStore - browser state
- IDBOpenDBRequest - browser state
- IDBRequest - browser state
- IDBTransaction - browser state
- IDBVersionChangeEvent - browser state
- ImageBitmapRenderingContext - canvas
- ImageBitmap - canvas
- ImageData - canvas
- indexedDB - browser state
- isSecureContext - network access
- MLActivation - secure context
- MLCommandEncoder - secure context
- MLContext - secure context
- MLGraphBuilder - secure context
- MLGraph - secure context
- MLOperand - secure context
- ML - secure context
- MediaSourceHandle - multimedia
- MediaSource - multimedia
- MessageChannel - communication channels
- MessageEvent - communication channels
- MessagePort - communication channels
- NavigationPreloadManager - secure context, workers
- navigator - browser state (some properties of navigator might be OK though)
- Notification - host access
- OffscreenCanvasRenderingContext2D - canvas
- OffscreenCanvas - canvas
- origin - network access
- Path2D - canvas
- PerformanceEntry - host access
- PerformanceMark - host access
- PerformanceMeasure - host access
- PerformanceObserverEntryList - host access
- PerformanceObserver - host access
- PerformanceResourceTiming - host access, timers
- Performance - timers, host access
- performance - timers, host access
- ProgressEvent - network access
- queueMicrotask - timers
- reportError - probably redundant
- requestAnimationFrame - timers
- Request - network access
- Response - network access
- SecurityPolicyViolationEvent - network access
- ServiceWorkerContainer - secure context, workers
- ServiceWorkerRegistration - secure context, workers
- ServiceWorker - secure context, workers
- setInterval - timers
- setTimeout - timers
- SourceBufferList - multimedia
- SourceBuffer - multimedia
- StorageManager - browser state
- SubtleCrypto - secure context
- TestUtils - not exposed to end users anyway
- TextMetrics - canvas
- WebAssembly.compileStreaming - network access
- WebAssembly.instantiateStreaming - network access
- WebGLActiveInfo - canvas
- WebGLBuffer - canvas
- WebGLContextEvent - canvas
- WebGLFrameBuffer - canvas
- WebGLObject - canvas
- WebGLProgram - canvas
- WebGLRenderBuffer - canvas
- WebGLRenderingContext - canvas
- WebGLShaderPrecisionFormat - canvas
- WebGLShader - canvas
- WebGLTexture - canvas
- WebGLUniformLocation - canvas
- WebSocket - network access
- Worker - workers
- XMLHttpRequestEventTarget - network access
- XMLHttpRequest - network access
Blob and related APIs (currently W3C Working Draft) could arguably be included but initially we decided not to expose them because they are somewhat tied to fetch and file APIs. The HTML spec references Blob, but only in APIs that are not available in ShadowRealm.