docs(ses): document Compartment availability and OOM limits (#2742)#3275
Open
kriskowal wants to merge 1 commit into
Open
docs(ses): document Compartment availability and OOM limits (#2742)#3275kriskowal wants to merge 1 commit into
kriskowal wants to merge 1 commit into
Conversation
|
Open
3 tasks
kriskowal
added a commit
to kriskowal/garden
that referenced
this pull request
May 21, 2026
…partment OOM docs, 4-of-5 squash with AGENTS.md exclusion)
|
Mirror of endojs/endo-but-for-bots#68 (head 4d8ed6b). |
kriskowal
force-pushed
the
kriskowal-compartment-oom-docs-2742
branch
from
4d8ed6b to
8a90ca3
Compare
Adds a Limitations section to docs/lockdown.md describing three classes of threat that a Compartment cannot mitigate, all intrinsic to running multiple compartments inside a single JavaScript agent. Availability: every compartment shares the agent's single thread, so a guest that enters a non-terminating synchronous computation (an infinite loop, runaway recursion, or any other unresponsive synchronous call, including via a property accessor, proxy trap, or synchronously-resolved `then` callback) denies progress to every sibling and to the start compartment until the engine intervenes. Host code that wants to remain available must interact with guest objects across an asynchronous boundary, or run the guest in a separate worker or process where it can be terminated. Memory exhaustion: the ECMAScript specification does not require an engine to abort the agent on OOM (see the TC39 OOM-fails-fast proposal), so a malicious compartment can intentionally exhaust memory and surface a `RangeError` or other allocation failure inside an unrelated synchronous call, including one into an object exported from another compartment. The victim is then left in a partially updated state, turning the availability concern into an integrity concern on otherwise trusted exports. Timing side-channels: the default Compartment deliberately excludes `Date`, `performance.now`, `setTimeout`, `setImmediate`, and every other host scheduling primitive, but any asynchronous boundary the guest can drive (another worker, another process, a network peer, a host-supplied promise resolved on a host-driven schedule) recovers wall-clock duration from the round-trip. Defeating timing side-channels therefore requires auditing every reachable async boundary, not just enumerating timer-like APIs; the host's mitigation menu includes running the suspect guest in a separate worker or process, throttling outbound message rate, and padding guest-visible message delivery so the round-trip distribution conveys less about host-internal events. For the broader threat catalog, the section cites Agoric's Taxonomy of Security Issues paper. The new section is cross-linked from packages/ses/README.md's Compartment section so readers reach it from the place Compartment is introduced. Fixes #2742
kriskowal
force-pushed
the
kriskowal-compartment-oom-docs-2742
branch
from
8a90ca3 to
debd645
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes: #2742
Description
Adds a Limitations section to
docs/lockdown.mdcovering three classes of threat aCompartmentcannot mitigate, all intrinsic to running multiple compartments inside a single JavaScript agent: availability (one compartment can deny synchronous progress to all siblings), memory exhaustion (an OOM in one compartment can surface as a partial-update integrity failure inside an unrelated synchronous call), and timing side-channels (any asynchronous boundary the guest can drive recovers wall-clock duration, regardless of the deliberate omission ofDate,performance.now, and host timers from the defaultCompartment).Each subsection states what the threat is, why a
Compartmentcannot address it, and what host-level remedies exist (chiefly, running the suspect guest in a separate worker or process, plus rate-throttling and timing-padding for the side-channel case). The timing section cites Agoric's Taxonomy of Security Issues for the broader catalog this section samples.The new section is cross-linked from
packages/ses/README.md's Compartment section so readers reach it from the placeCompartmentis introduced.Security Considerations
The change is documentation only; it introduces no new code, authority, or API surface. Its purpose is to make existing security properties of
Compartmentlegible to integrators, so hosts can make informed choices about when a single-agent compartment is sufficient and when a coarser boundary (separate worker or process) is required. The doc is careful to mark the timing-side-channel discussion as a sample of a broader threat space rather than a complete catalog.Scaling Considerations
None.
Documentation Considerations
The text lives in the existing
docs/lockdown.mdso downstream documentation toolchains pick it up without configuration changes. The README cross-link is a relative path within the same monorepo (../../docs/lockdown.md#limitations). No deployed-data migration.Testing Considerations
No code under test.
Compatibility Considerations
None; documentation only.
Upgrade Considerations
None.