docs(compartment-mapper): add ARCHITECTURE.md #3049
Conversation
boneskull
force-pushed
the
boneskull/compartment-mapper-architecture
branch
from
f95cad8 to
297fa12
Compare
I am iterating on this, but Claude has already made some things more clear.
boneskull
force-pushed
the
boneskull/compartment-mapper-architecture
branch
from
297fa12 to
c5883fe
Compare
kriskowal
left a comment
kriskowal
left a comment
There was a problem hiding this comment.
Only had a moment to look and leave some comments. Thanks for sharing the draft.
| @@ -0,0 +1,1365 @@ | |||
| # Compartment Mapper Architecture | |||
|
|
|||
| This document provides a comprehensive technical analysis of `@endo/compartment-mapper`, a package that enables secure, sandboxed execution of Node.js-style applications using the SES (Secure ECMAScript) `Compartment` abstraction. | |||
| 3. **Links** compartments together, allowing controlled module sharing | ||
| 4. **Executes** or **archives** applications in a sandboxed environment | ||
|
|
||
| This enables the _Principle of Least Authority (POLA)_: each package runs with only the capabilities explicitly granted to it, mitigating prototype pollution and supply chain attacks. |
There was a problem hiding this comment.
In combination with a trust-on-first-use policy,
Otherwise, it simply enables us to bundle node_modules applications deterministically such that they can collectively run in a guest sandbox with packages in separate compartments.
It will eventually allow us to bundle applications as a ZIP of original sources, eschewing source modification entirely, improving the debugging experience of sandboxed applications anywhere.
|
|
||
| ### What is a Compartment? | ||
|
|
||
| A **Compartment** (from the SES proposal) is an isolated JavaScript execution environment with: |
There was a problem hiding this comment.
From the compartments proposal, https://github.com/endojs/proposal-compartments
|
|
||
| This enables the _Principle of Least Authority (POLA)_: each package runs with only the capabilities explicitly granted to it, mitigating prototype pollution and supply chain attacks. | ||
|
|
||
| ### What is a Compartment? |
There was a problem hiding this comment.
Might be good to move this into its own related document since some of this detail exceeds the needs of the context but would be useful nonetheless. In particular, a rigorous account of the SES frozen intrinsics would be good to have somewhere.
| sequenceDiagram | ||
| participant User | ||
| participant Archive as archive.js | ||
| participant NodeModules as node-modules.js | ||
| participant ArchiveLite as archive-lite.js | ||
| participant Linker as link.js | ||
| participant Zip as @endo/zip | ||
|
|
||
| Note over User,Zip: Archive Creation |
There was a problem hiding this comment.
I’m adding a note to CONTRIBUTING.md that should convince folks to use 2 space indents in these Mermaid diagrams consistently.
| @@ -0,0 +1,1365 @@ | |||
| # Compartment Mapper Architecture | |||
|
|
|||
| This document provides a comprehensive technical analysis of `@endo/compartment-mapper`, a package that enables secure, sandboxed execution of Node.js-style applications using the SES (Secure ECMAScript) `Compartment` abstraction. | |||
There was a problem hiding this comment.
Please ensure that this uses the voice of authority on the architecture rather than a post-hoc analysis before it lands.
I am iterating on this, but Claude has already made some things more clear.