feat(ocap-kernel): integrate Snaps attenuated endowment factories

Replaces raw vat-global endowments with attenuated factories from
`@metamask/snaps-execution-environments/endowments`:

- Adds `setInterval`, `clearInterval`, `crypto`, `SubtleCrypto`, and
  `Math` (with `crypto.getRandomValues`-sourced `Math.random`) to the
  default allowlist.
- Replaces the raw `setTimeout`/`clearTimeout` and `Date` with the
  monotonic, attenuated Snaps factories.
- Wires each factory's `teardownFunction` into `VatSupervisor.terminate`
  via an aggregate teardown built on `Promise.allSettled`, so pending
  timers and open resources are released even if one teardown rejects.
- Replaces the `DEFAULT_ALLOWED_GLOBALS` constant + `allowedGlobals`
  constructor parameter with `createDefaultEndowments()` factory and
  `makeAllowedGlobals` parameter; the factory is invoked once per
  supervisor so state is isolated per vat.

NOTE: this change depends on the `/endowments` subpath export landing
in `@metamask/snaps-execution-environments` (MetaMask/snaps#3957).
The PR stays in draft until that is released; the `^11.1.0` version
pin is a placeholder and will be updated when the release ships.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: sirtimid

packages/kernel-test/src/endowment-globals.test.ts

@@ -113,6 +113,18 @@ describe('global endowments', () => {
     expect(logs).toContain('timer: fired');
   });
 
+  it('can use setInterval and clearInterval', async () => {
+    const { kernel, entries } = await setup({
+      globals: ['setInterval', 'clearInterval'],
+    });
+
+    await kernel.queueMessage(v1Root, 'testInterval', []);
+    await waitUntilQuiescent();
+
+    const logs = extractTestLogs(entries, vatId);
+    expect(logs).toContain('interval: ticks=2');
+  });
+
   it('can use real Date (not tamed)', async () => {
     const { kernel, entries } = await setup({ globals: ['Date'] });
 
@@ -123,6 +135,28 @@ describe('global endowments', () => {
     expect(logs).toContain('date: isReal=true');
   });
 
+  it('can use crypto.getRandomValues', async () => {
+    const { kernel, entries } = await setup({
+      globals: ['crypto', 'SubtleCrypto'],
+    });
+
+    await kernel.queueMessage(v1Root, 'testCrypto', []);
+    await waitUntilQuiescent();
+
+    const logs = extractTestLogs(entries, vatId);
+    expect(logs).toContain('crypto: hasRandomBytes=true');
+  });
+
+  it('can use Math.random sourced from crypto.getRandomValues', async () => {
+    const { kernel, entries } = await setup({ globals: ['Math'] });
+
+    await kernel.queueMessage(v1Root, 'testMath', []);
+    await waitUntilQuiescent();
+
+    const logs = extractTestLogs(entries, vatId);
+    expect(logs).toContain('math: inRange=true');
+  });
+
   describe('host APIs are absent when not endowed', () => {
     // These are Web/host APIs that are NOT JS intrinsics — they should
     // be genuinely absent from a SES compartment unless explicitly endowed.
@@ -137,6 +171,10 @@ describe('global endowments', () => {
       'AbortSignal',
       'setTimeout',
       'clearTimeout',
+      'setInterval',
+      'clearInterval',
+      'crypto',
+      'SubtleCrypto',
     ])('does not have %s without endowing it', async (name) => {
       // Launch with no globals at all
       const { kernel, entries } = await setup({ globals: [] });
@@ -155,6 +193,14 @@ describe('global endowments', () => {
         'secure mode',
       );
     });
+
+    it('throws when calling tamed Math.random without endowing Math', async () => {
+      const { kernel } = await setup({ globals: [] });
+
+      await expect(kernel.queueMessage(v1Root, 'testMath', [])).rejects.toThrow(
+        'secure mode',
+      );
+    });
   });
 
   describe('kernel-level allowedGlobalNames restriction', () => {

packages/kernel-test/src/vats/endowment-globals.ts

@@ -62,13 +62,45 @@ export function buildRootObject(vatPowers: TestPowers) {
       });
     },
 
+    testInterval: async () => {
+      return new Promise((resolve) => {
+        let tickCount = 0;
+        const handle = setInterval(() => {
+          tickCount += 1;
+          if (tickCount >= 2) {
+            clearInterval(handle);
+            tlog(`interval: ticks=${tickCount}`);
+            resolve(tickCount);
+          }
+        }, 10);
+      });
+    },
+
     testDate: () => {
       const now = Date.now();
       const isReal = !Number.isNaN(now) && now > 0;
       tlog(`date: isReal=${String(isReal)}`);
       return isReal;
     },
 
+    testCrypto: () => {
+      // A 16-byte buffer makes the all-zero coincidence vanishingly small
+      // (2^-128); a 4-byte buffer has a ~1-in-4-billion false-negative rate.
+      const buffer = new Uint8Array(16);
+      // eslint-disable-next-line n/no-unsupported-features/node-builtins -- `crypto` here is the vat endowment, not the Node global; the rule's engines check does not apply inside a SES Compartment.
+      crypto.getRandomValues(buffer);
+      const hasRandomBytes = buffer.some((byte) => byte !== 0);
+      tlog(`crypto: hasRandomBytes=${String(hasRandomBytes)}`);
+      return hasRandomBytes;
+    },
+
+    testMath: () => {
+      const value = Math.random();
+      const inRange = value >= 0 && value < 1;
+      tlog(`math: inRange=${String(inRange)}`);
+      return inRange;
+    },
+
     checkGlobal: (name: string) => {
       // In a SES compartment, globalThis points to the compartment's own
       // global object, so this correctly detects whether an endowment was

packages/ocap-kernel/CHANGELOG.md

@@ -9,6 +9,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- Integrate Snaps attenuated endowment factories into vat globals ([#935](https://github.com/MetaMask/ocap-kernel/pull/935))
+  - Add `setInterval`, `clearInterval`, `crypto`, `SubtleCrypto`, and `Math` (crypto-backed `Math.random`) to the default vat endowments
+  - Swap raw `setTimeout`/`clearTimeout` and `Date` for attenuated versions from `@metamask/snaps-execution-environments`
+  - Wire factory `teardownFunction`s into `VatSupervisor.terminate()` so pending timers and other resources are released on vat termination
+  - Replace exported `DEFAULT_ALLOWED_GLOBALS` constant with `createDefaultEndowments()` factory and `VatEndowments` type; `VatSupervisor` now accepts `makeAllowedGlobals` in place of `allowedGlobals`
 - Make vat global allowlist configurable and expand available endowments ([#933](https://github.com/MetaMask/ocap-kernel/pull/933))
   - Export `DEFAULT_ALLOWED_GLOBALS` with `URL`, `URLSearchParams`, `atob`, `btoa`, `AbortController`, and `AbortSignal` in addition to the existing globals
   - Accept optional `allowedGlobals` on `VatSupervisor` for custom allowlists

packages/ocap-kernel/package.json

@@ -94,6 +94,7 @@
     "@metamask/kernel-utils": "workspace:^",
     "@metamask/logger": "workspace:^",
     "@metamask/rpc-errors": "^7.0.3",
+    "@metamask/snaps-execution-environments": "^11.1.0",
     "@metamask/streams": "workspace:^",
     "@metamask/superstruct": "^3.2.1",
     "@metamask/utils": "^11.9.0",

packages/ocap-kernel/src/Kernel.ts

@@ -232,7 +232,7 @@ export class Kernel {
    * @param options.mnemonic - Optional BIP39 mnemonic for deriving the kernel identity.
    * @param options.ioChannelFactory - Optional factory for creating IO channels.
    * @param options.systemSubclusters - Optional array of system subcluster configurations.
-   * @param options.allowedGlobalNames - Optional list of allowed global names for vat endowments. When set, only these names from DEFAULT_ALLOWED_GLOBALS are available to vats.
+   * @param options.allowedGlobalNames - Optional list of allowed global names for vat endowments. When set, only these names from the `VatSupervisor`'s configured endowments (see `createDefaultEndowments`) are available to vats.
    * @returns A promise for the new kernel instance.
    */
   static async make(

packages/ocap-kernel/src/index.test.ts

@@ -7,14 +7,14 @@ describe('index', () => {
     expect(Object.keys(indexModule).sort()).toStrictEqual([
       'CapDataStruct',
       'ClusterConfigStruct',
-      'DEFAULT_ALLOWED_GLOBALS',
       'Kernel',
       'KernelStatusStruct',
       'SubclusterStruct',
       'VatConfigStruct',
       'VatHandle',
       'VatIdStruct',
       'VatSupervisor',
+      'createDefaultEndowments',
       'generateMnemonic',
       'initTransport',
       'insistKRef',

packages/ocap-kernel/src/index.ts

@@ -1,7 +1,8 @@
 export { Kernel } from './Kernel.ts';
 export { VatHandle } from './vats/VatHandle.ts';
 export { VatSupervisor } from './vats/VatSupervisor.ts';
-export { DEFAULT_ALLOWED_GLOBALS } from './vats/endowments.ts';
+export { createDefaultEndowments } from './vats/endowments.ts';
+export type { VatEndowments } from './vats/endowments.ts';
 export { initTransport } from './remotes/platform/transport.ts';
 export type { IOChannel, IOChannelFactory } from './io/types.ts';
 export type {

packages/ocap-kernel/src/vats/VatSupervisor.test.ts

@@ -6,6 +6,7 @@ import { rpcErrors } from '@metamask/rpc-errors';
 import { TestDuplexStream } from '@ocap/repo-tools/test-utils/streams';
 import { describe, it, expect, vi } from 'vitest';
 
+import type { VatEndowments } from './endowments.ts';
 import { VatSupervisor } from './VatSupervisor.ts';
 import type { FetchBlob } from './VatSupervisor.ts';
 
@@ -23,21 +24,29 @@ vi.mock('@agoric/swingset-liveslots', () => ({
   })),
 }));
 
+const makeVatEndowments = (
+  globals: Record<string, unknown>,
+  teardown: () => Promise<void> = async () => undefined,
+): VatEndowments => ({
+  globals: harden({ ...globals }),
+  teardown,
+});
+
 const makeVatSupervisor = async ({
   dispatch,
   logger,
   vatPowers,
   makePlatform,
   platformOptions,
-  allowedGlobals,
+  makeAllowedGlobals,
   fetchBlob,
 }: {
   dispatch?: (input: unknown) => void | Promise<void>;
   logger?: Logger;
   vatPowers?: Record<string, unknown>;
   makePlatform?: PlatformFactory;
   platformOptions?: Record<string, unknown>;
-  allowedGlobals?: Record<string, unknown>;
+  makeAllowedGlobals?: () => VatEndowments;
   fetchBlob?: FetchBlob;
 } = {}): Promise<{
   supervisor: VatSupervisor;
@@ -59,7 +68,7 @@ const makeVatSupervisor = async ({
       vatPowers: vatPowers ?? {},
       makePlatform: makePlatform ?? defaultMakePlatform,
       platformOptions: platformOptions ?? {},
-      allowedGlobals,
+      makeAllowedGlobals,
       fetchBlob,
     }),
     stream: kernelStream,
@@ -143,6 +152,59 @@ describe('VatSupervisor', () => {
         value: undefined,
       });
     });
+
+    it('calls the endowments teardown before closing the stream', async () => {
+      const teardown = vi.fn().mockResolvedValue(undefined);
+      const { supervisor, stream } = await makeVatSupervisor({
+        makeAllowedGlobals: () => makeVatEndowments({}, teardown),
+      });
+      const endSpy = vi.spyOn(stream, 'end');
+
+      await supervisor.terminate();
+
+      expect(teardown).toHaveBeenCalledTimes(1);
+      expect(endSpy).toHaveBeenCalledTimes(1);
+      expect(teardown.mock.invocationCallOrder[0]).toBeLessThan(
+        endSpy.mock.invocationCallOrder[0] as number,
+      );
+    });
+
+    it('closes the stream and logs when teardown rejects', async () => {
+      const logger = {
+        error: vi.fn(),
+        subLogger: vi.fn(() => logger),
+      } as unknown as Logger;
+      const teardownError = new Error('boom');
+      const { supervisor, stream } = await makeVatSupervisor({
+        logger,
+        makeAllowedGlobals: () =>
+          makeVatEndowments({}, async () => {
+            throw teardownError;
+          }),
+      });
+
+      await supervisor.terminate();
+
+      expect(logger.error).toHaveBeenCalledWith(
+        expect.stringContaining('Endowment teardown failed'),
+        teardownError,
+      );
+      expect(await stream.next()).toStrictEqual({
+        done: true,
+        value: undefined,
+      });
+    });
+
+    it('is safe to call twice', async () => {
+      const teardown = vi.fn().mockResolvedValue(undefined);
+      const { supervisor } = await makeVatSupervisor({
+        makeAllowedGlobals: () => makeVatEndowments({}, teardown),
+      });
+
+      await supervisor.terminate();
+      expect(await supervisor.terminate()).toBeUndefined();
+      expect(teardown).toHaveBeenCalledTimes(2);
+    });
   });
 
   describe('platform configuration', () => {
@@ -171,12 +233,16 @@ describe('VatSupervisor', () => {
     });
   });
 
-  describe('allowedGlobals configuration', () => {
-    it('accepts a custom allowedGlobals parameter', async () => {
+  describe('makeAllowedGlobals configuration', () => {
+    it('invokes the factory exactly once at construction', async () => {
+      const factory = vi.fn(() =>
+        makeVatEndowments({ CustomGlobal: 'custom-value' }),
+      );
       const { supervisor } = await makeVatSupervisor({
-        allowedGlobals: { CustomGlobal: 'custom-value' },
+        makeAllowedGlobals: factory,
       });
       expect(supervisor).toBeInstanceOf(VatSupervisor);
+      expect(factory).toHaveBeenCalledTimes(1);
     });
 
     it('throws when a vat requests an unknown global', async () => {
@@ -189,7 +255,7 @@ describe('VatSupervisor', () => {
 
       const { stream } = await makeVatSupervisor({
         dispatch,
-        allowedGlobals: { Date: globalThis.Date },
+        makeAllowedGlobals: () => makeVatEndowments({ Date: globalThis.Date }),
         fetchBlob: mockFetchBlob,
       });
 

packages/ocap-kernel/src/vats/VatSupervisor.ts

@@ -28,7 +28,8 @@ import {
 } from '@metamask/utils';
 
 import { loadBundle } from './bundle-loader.ts';
-import { DEFAULT_ALLOWED_GLOBALS } from './endowments.ts';
+import { createDefaultEndowments } from './endowments.ts';
+import type { VatEndowments } from './endowments.ts';
 import { makeGCAndFinalize } from '../garbage-collection/gc-finalize.ts';
 import { makeDummyMeterControl } from '../liveslots/meter-control.ts';
 import { makeSupervisorSyscall } from '../liveslots/syscall.ts';
@@ -59,7 +60,7 @@ type SupervisorConstructorProps = {
   platformOptions?: Record<string, unknown>;
   vatPowers?: Record<string, unknown> | undefined;
   fetchBlob?: FetchBlob;
-  allowedGlobals?: Record<string, unknown>;
+  makeAllowedGlobals?: () => VatEndowments;
 };
 
 const marshal = makeMarshal(undefined, undefined, {
@@ -109,6 +110,13 @@ export class VatSupervisor {
   /** The set of globals that vats are allowed to request. */
   readonly #allowedGlobals: Record<string, unknown>;
 
+  /**
+   * Releases resources held by the endowment factories (e.g. pending timers,
+   * open network connections). Invoked from {@link terminate} before closing
+   * the kernel stream; failures are logged but do not prevent stream closure.
+   */
+  readonly #endowmentsTeardown: () => Promise<void>;
+
   /**
    * Construct a new VatSupervisor instance.
    *
@@ -120,7 +128,9 @@ export class VatSupervisor {
    * @param params.fetchBlob - Function to fetch the user code bundle for this vat.
    * @param params.makePlatform - Function to create the platform for this vat.
    * @param params.platformOptions - Options to pass to the makePlatform function.
-   * @param params.allowedGlobals - Map of allowed globals. Defaults to {@link DEFAULT_ALLOWED_GLOBALS}.
+   * @param params.makeAllowedGlobals - Factory invoked exactly once at
+   * construction to produce this vat's isolated endowments and an aggregate
+   * teardown function. Defaults to {@link createDefaultEndowments}.
    */
   constructor({
     id,
@@ -132,7 +142,7 @@ export class VatSupervisor {
     },
     platformOptions,
     fetchBlob,
-    allowedGlobals = DEFAULT_ALLOWED_GLOBALS,
+    makeAllowedGlobals = createDefaultEndowments,
   }: SupervisorConstructorProps) {
     this.id = id;
     this.#kernelStream = kernelStream;
@@ -144,7 +154,9 @@ export class VatSupervisor {
     this.#fetchBlob = fetchBlob ?? defaultFetchBlob;
     this.#platformOptions = platformOptions ?? {};
     this.#makePlatform = makePlatform;
-    this.#allowedGlobals = harden(allowedGlobals);
+    const { globals, teardown } = makeAllowedGlobals();
+    this.#allowedGlobals = globals;
+    this.#endowmentsTeardown = teardown;
 
     this.#rpcClient = new RpcClient(
       vatSyscallMethodSpecs,
@@ -174,9 +186,22 @@ export class VatSupervisor {
   /**
    * Terminate the VatSupervisor.
    *
+   * Endowment teardown runs first so pending timers and other resources are
+   * released before the kernel stream closes. Teardown failures are logged
+   * but never block stream closure — the original `error` (if any) must
+   * always reach the kernel.
+   *
    * @param error - The error to terminate the VatSupervisor with.
    */
   async terminate(error?: Error): Promise<void> {
+    try {
+      await this.#endowmentsTeardown();
+    } catch (teardownError) {
+      this.#logger.error(
+        `Endowment teardown failed during terminate of vat "${this.id}"`,
+        teardownError,
+      );
+    }
     await this.#kernelStream.end(error);
   }