Skip to content

feat: Export endowment factories via sub-path#3957

Draft
sirtimid wants to merge 3 commits intomainfrom
sirtimid/export-endowment-factories
Draft

feat: Export endowment factories via sub-path#3957
sirtimid wants to merge 3 commits intomainfrom
sirtimid/export-endowment-factories

Conversation

@sirtimid
Copy link
Copy Markdown
Contributor

@sirtimid sirtimid commented Apr 14, 2026

Summary

  • Adds @metamask/snaps-execution-environments/endowments sub-path export exposing generic endowment factory modules: timeout, interval, date, textEncoder, textDecoder, crypto, math
  • These factories are fully generic (no Snaps-specific coupling) and can be reused by other SES-based projects like ocap-kernel
  • Snaps-specific factories (console, network) and types referencing internal Snaps modules are intentionally excluded to keep the public API clean

Note

Medium Risk
Adds a new public entrypoint via package exports, which can affect downstream bundling/type resolution even though underlying runtime logic is unchanged.

Overview
Introduces a new public subpath export, @metamask/snaps-execution-environments/endowments, to expose the generic endowment factory modules (timeout, interval, date, textEncoder, textDecoder, crypto, math).

Updates packaging and tooling to support this new entrypoint by adding ./endowments to package.json exports, documenting it in the changelog, and excluding src/endowments.ts from Jest/Vitest coverage reporting.

Reviewed by Cursor Bugbot for commit bf365e7. Bugbot is set up for automated code reviews on this repo. Configure here.

@sirtimid sirtimid requested a review from a team as a code owner April 14, 2026 15:02
sirtimid added a commit that referenced this pull request Apr 14, 2026
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@sirtimid sirtimid requested a review from rekmarks April 14, 2026 15:03
sirtimid added a commit that referenced this pull request Apr 14, 2026
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@sirtimid sirtimid force-pushed the sirtimid/export-endowment-factories branch from 5ed70c1 to f4b1edc Compare April 14, 2026 15:04
sirtimid and others added 3 commits April 14, 2026 18:54
Add `@metamask/snaps-execution-environments/endowments` sub-path export
that exposes generic endowment factory modules (timeout, interval, date,
textEncoder, textDecoder, crypto, math) for reuse in other SES-based
projects like ocap-kernel.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The endowments.ts barrel file is a pure re-export module with no
logic to test, matching the existing exclusion pattern for index.ts.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@sirtimid sirtimid force-pushed the sirtimid/export-endowment-factories branch from f9b9a7d to bf365e7 Compare April 14, 2026 16:59
@codecov
Copy link
Copy Markdown

codecov bot commented Apr 14, 2026

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.56%. Comparing base (22f8da9) to head (bf365e7).

Additional details and impacted files
@@           Coverage Diff           @@
##             main    #3957   +/-   ##
=======================================
  Coverage   98.56%   98.56%           
=======================================
  Files         428      428           
  Lines       12347    12347           
  Branches     1940     1940           
=======================================
  Hits        12170    12170           
  Misses        177      177           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@sirtimid sirtimid marked this pull request as draft April 14, 2026 17:38
github-merge-queue bot pushed a commit to MetaMask/ocap-kernel that referenced this pull request Apr 14, 2026
## Summary

This is **Part 1** of the vat endowments overhaul (closes #813). Part 2
will integrate attenuated endowment factories from
`@metamask/snaps-execution-environments` once
[MetaMask/snaps#3957](MetaMask/snaps#3957) is
merged and released — adding timer teardown on vat termination,
anti-timing-attack `Date`, and crypto-backed `Math.random`.

The hardcoded `allowedGlobals` in `VatSupervisor` is extracted into a
dedicated `endowments.ts` module and made configurable:

- **New `DEFAULT_ALLOWED_GLOBALS` constant** — a hardened record of
host/Web API endowments that SES Compartments do not provide by default.
JS intrinsics (`ArrayBuffer`, `BigInt`, typed arrays, `Intl`, etc.) are
excluded since they are already available in every Compartment.
- **Expanded endowment set** — adds `URL`, `URLSearchParams`, `atob`,
`btoa`, `AbortController`, `AbortSignal` alongside the existing
`TextEncoder`, `TextDecoder`, `setTimeout`, `clearTimeout`, `Date`.
- **Configurable `allowedGlobals` on `VatSupervisor`** — optional
constructor parameter defaulting to `DEFAULT_ALLOWED_GLOBALS`. Custom
maps are hardened on assignment.
- **Warning on unknown globals** — when a vat requests a global not in
the allowlist, a warning is logged instead of silently ignoring it.

## Testing

Unit tests in `endowments.test.ts` verify the constant's shape and
frozen state. `VatSupervisor.test.ts` tests the configurable parameter,
the warning behavior (both positive and negative paths via `initVat`
RPC). E2e tests in `kernel-test` exercise each endowment inside a real
SES Compartment and verify that all host APIs are genuinely absent when
not endowed, including that the tamed `Date.now` throws in secure mode
without the `Date` endowment.

🤖 Generated with [Claude Code](https://claude.com/claude-code)


<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Changes vat endowment/SES-global handling by expanding and
centralizing the allowlist and adding kernel-controlled restrictions,
which can affect vat initialization and security boundaries if
misconfigured.
> 
> **Overview**
> Adds a hardened `DEFAULT_ALLOWED_GLOBALS` export and expands the
default endowment set (e.g. `URL`, `URLSearchParams`, `atob`/`btoa`,
`AbortController`/`AbortSignal`) used to explicitly provide host/Web
globals to vats.
> 
> Introduces a kernel-level `allowedGlobalNames` option that is
propagated through `VatManager`/`VatHandle` to the `initVat` RPC and
enforced in `VatSupervisor` by filtering the allowlist; vats now fail
initialization when requesting a global outside the effective allowlist.
> 
> Adds unit + integration tests (including a new kernel-test vat) to
verify each endowment works when granted, is absent when not endowed,
and that kernel restrictions reject disallowed globals; updates public
exports and changelog accordingly.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
a105504. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant