refactor(ocap-kernel): type vat-endowments allowlist as literal union#941
Merged
refactor(ocap-kernel): type vat-endowments allowlist as literal union#941
Conversation
Replace `string[]` with a `AllowedGlobalName` literal-union type at every propagation site for the vat-endowments allowlist so typos surface at compile time, and enforce the same invariant at the initVat RPC boundary via `AllowedGlobalNameStruct` (a superstruct `enums()` derived from the same source-of-truth tuple as the type). - `AllowedGlobalName`, `AllowedGlobalNameStruct`, `MakeAllowedGlobals`, and `VatEndowmentsStruct` are now exported from `endowments.ts` and re-exported from the package index. - `VatSupervisor` asserts `VatEndowmentsStruct` against the `makeAllowedGlobals()` return value in the constructor so a malformed custom factory fails fast at construction rather than during teardown. - `VatConfig.globals`, `Kernel.make`, `VatManager`, `VatHandle`, and the `initVat` RPC spec all carry `AllowedGlobalName[]`. Follow-up to #937. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Contributor
Coverage Report
File Coverage
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
rekmarks
approved these changes
Apr 21, 2026
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.
Summary
Follow-up to #937 tightening the type surface of the vat-endowments allowlist.
AllowedGlobalNameliteral-union type (and pairedAllowedGlobalNameStructsuperstruct) derived from a singlereadonlytuple inendowments.ts. Typos are now caught at compile time at every propagation site and rejected at theinitVatRPC boundary.string[]→AllowedGlobalName[]at 5 sites:Kernel.makeoptions,VatManager,VatHandle,initVatRPC spec +InitVatfunction type, andVatConfig.globals.VatSupervisorconstructor nowassert()s themakeAllowedGlobals()return value againstVatEndowmentsStruct, so a malformed custom factory fails fast at construction instead of during termination.MakeAllowedGlobalsfactory type alias,AllowedGlobalNameStruct, andVatEndowmentsStructare exported from the package index for symmetry with the existing struct exports.The previously-silent "drops unknown names" path is no longer reachable through the typed API; the equivalent integration test now asserts the RPC-layer rejection (
Invalid params).Test plan
yarn build— 24/24 tasks cleanyarn lintcleanyarn test:dev:quiet— 45/45 turbo tasks, 2279 tests in@metamask/ocap-kernel, full@ocap/kernel-testsuite green (incl. updatedendowment-globals.test.ts > rejects unknown names in allowedGlobalNames at the RPC boundary)🤖 Generated with Claude Code
Note
Medium Risk
This is a breaking API-surface change that tightens types and adds runtime validation at the
initVatRPC boundary; risk is mainly client compatibility and potential new rejections for previously-accepted inputs.Overview
Tightens vat endowment allowlists from
string[]to a literal union. IntroducesAllowedGlobalName+AllowedGlobalNameStructderived from a single allowlist tuple, and propagates the type change throughVatConfig.globals,Kernel.make({ allowedGlobalNames }),VatManager/VatHandle, and theinitVatRPC params so unknown names are rejected as Invalid params at the RPC boundary.Hardens extension points and exports. Adds
VatEndowmentsStruct+MakeAllowedGlobalsand asserts custommakeAllowedGlobals()return values inVatSupervisorto fail fast on malformed factories; re-exports the new types/structs fromindex.tsand updates tests and changelog accordingly.Reviewed by Cursor Bugbot for commit 5ae29fa. Bugbot is set up for automated code reviews on this repo. Configure here.