fix: Improve public endowment API based on review

- Narrow console/network factory types to require their options at
  compile time (sourceLabel and notify respectively)
- Add descriptive assert messages for runtime safety (JS consumers)
- Remove CommonEndowmentSpecification from public exports (internal detail)
- Add SES lockdown() prerequisite to module JSDoc
- Fix stale Snap-specific language in comments and JSDoc
- Fix "Create a a" typo in console.ts
- Update changelog to list all exported modules and types
- Add barrel smoke test verifying all re-exports
- Add tests for non-Snap labels and missing sourceLabel

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

Author: sirtimid

packages/snaps-execution-environments/CHANGELOG.md

@@ -10,7 +10,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - Export endowment factories via `@metamask/snaps-execution-environments/endowments` sub-path ([#3957](https://github.com/MetaMask/snaps/pull/3957))
-  - Exports endowment factory modules: `timeout`, `interval`, `date`, `textEncoder`, `textDecoder`, `crypto`, `math`
+  - Exports endowment factory modules: `timeout`, `interval`, `date`, `textEncoder`, `textDecoder`, `crypto`, `math`, `consoleEndowment`, `network`
+  - Exports `buildCommonEndowments` and types: `EndowmentFactory`, `EndowmentFactoryOptions`, `EndowmentFactoryResult`, `NotifyFunction`
 
 ## [11.0.2]
 

packages/snaps-execution-environments/src/common/endowments/commonEndowmentFactory.ts

@@ -24,9 +24,9 @@ export type NotifyFunction = (
  */
 export type EndowmentFactoryOptions = {
   /**
-   * A label identifying the source of endowment interactions (e.g., console
-   * output). The caller controls the format — Snaps passes `Snap: ${snapId}`,
-   * but external consumers may use any label.
+   * A label identifying the source of endowment interactions, used as a
+   * prefix in console output. For example, passing `"MyApp"` causes console
+   * messages to be prefixed with `[MyApp]`.
    */
   sourceLabel?: string;
 
@@ -44,9 +44,10 @@ export type EndowmentFactoryOptions = {
  */
 export type EndowmentFactoryResult = {
   /**
-   * An optional function that performs cleanup when the execution environment
-   * becomes idle. Must not render endowments unusable — only restore them to
-   * their initial state, since they may be reused without reconstruction.
+   * An optional function that performs cleanup when active resources (e.g.,
+   * pending timers or open network connections) should be released. Must not
+   * render endowments unusable — only restore them to their initial state,
+   * since they may be reused without reconstruction.
    */
   teardownFunction?: () => Promise<void> | void;
   [key: string]: unknown;
@@ -106,16 +107,18 @@ const commonEndowments: CommonEndowmentSpecification[] = [
  * @returns An object with common endowments.
  */
 const buildCommonEndowments = (): EndowmentFactory[] => {
+  // Console and network have narrower option types for their public API,
+  // but are widened here for internal dispatch via EndowmentFactory[].
   const endowmentFactories: EndowmentFactory[] = [
     crypto,
     interval,
     math,
-    network,
+    network as EndowmentFactory,
     timeout,
     textDecoder,
     textEncoder,
     date,
-    consoleEndowment,
+    consoleEndowment as EndowmentFactory,
   ];
 
   commonEndowments.forEach((endowmentSpecification) => {

packages/snaps-execution-environments/src/common/endowments/console.test.ts

@@ -39,7 +39,7 @@ describe('Console endowment', () => {
       expect(console.log).not.toStrictEqual(rootRealmGlobal.console.log);
     });
 
-    it('will log a message identifying the source of the call (snap id)', () => {
+    it('prefixes output with the source label', () => {
       const { console } = consoleEndowment.factory({
         sourceLabel: `Snap: ${MOCK_SNAP_ID}`,
       });
@@ -78,7 +78,7 @@ describe('Console endowment', () => {
       expect(console.error).not.toStrictEqual(rootRealmGlobal.console.error);
     });
 
-    it('will log a message identifying the source of the call (snap id)', () => {
+    it('prefixes output with the source label', () => {
       const { console } = consoleEndowment.factory({
         sourceLabel: `Snap: ${MOCK_SNAP_ID}`,
       });
@@ -99,7 +99,7 @@ describe('Console endowment', () => {
       expect(console.assert).not.toStrictEqual(rootRealmGlobal.console.assert);
     });
 
-    it('will log a message identifying the source of the call (snap id)', () => {
+    it('prefixes output with the source label', () => {
       const { console } = consoleEndowment.factory({
         sourceLabel: `Snap: ${MOCK_SNAP_ID}`,
       });
@@ -121,7 +121,7 @@ describe('Console endowment', () => {
       expect(console.debug).not.toStrictEqual(rootRealmGlobal.console.debug);
     });
 
-    it('will log a message identifying the source of the call (snap id)', () => {
+    it('prefixes output with the source label', () => {
       const { console } = consoleEndowment.factory({
         sourceLabel: `Snap: ${MOCK_SNAP_ID}`,
       });
@@ -142,7 +142,7 @@ describe('Console endowment', () => {
       expect(console.info).not.toStrictEqual(rootRealmGlobal.console.info);
     });
 
-    it('will log a message identifying the source of the call (snap id)', () => {
+    it('prefixes output with the source label', () => {
       const { console } = consoleEndowment.factory({
         sourceLabel: `Snap: ${MOCK_SNAP_ID}`,
       });
@@ -163,7 +163,7 @@ describe('Console endowment', () => {
       expect(console.warn).not.toStrictEqual(rootRealmGlobal.console.warn);
     });
 
-    it('will log a message identifying the source of the call (snap id)', () => {
+    it('prefixes output with the source label', () => {
       const { console } = consoleEndowment.factory({
         sourceLabel: `Snap: ${MOCK_SNAP_ID}`,
       });
@@ -175,4 +175,20 @@ describe('Console endowment', () => {
       );
     });
   });
+
+  it('throws when sourceLabel is not provided', () => {
+    // @ts-expect-error: Testing runtime guard for missing required option.
+    expect(() => consoleEndowment.factory({})).toThrow(
+      'The "sourceLabel" option is required by the console endowment factory.',
+    );
+  });
+
+  it('supports arbitrary source labels for non-Snap consumers', () => {
+    const { console } = consoleEndowment.factory({
+      sourceLabel: 'ocap-kernel: vat-42',
+    });
+    const logSpy = jest.spyOn(rootRealmGlobal.console, 'log');
+    console.log('test message');
+    expect(logSpy).toHaveBeenCalledWith('[ocap-kernel: vat-42] test message');
+  });
 });

packages/snaps-execution-environments/src/common/endowments/console.ts

@@ -3,6 +3,10 @@ import { assert } from '@metamask/utils';
 import type { EndowmentFactoryOptions } from './commonEndowmentFactory';
 import { rootRealmGlobal } from '../globalObject';
 
+type ConsoleEndowmentOptions = Required<
+  Pick<EndowmentFactoryOptions, 'sourceLabel'>
+>;
+
 export const consoleAttenuatedMethods = new Set([
   'log',
   'assert',
@@ -13,8 +17,9 @@ export const consoleAttenuatedMethods = new Set([
 ]);
 
 /**
- * A set of all the `console` values that will be passed to the snap. This has
- * all the values that are available in both the browser and Node.js.
+ * A set of all the `console` method names that will be included in the
+ * attenuated console object. Covers values available in both browser and
+ * Node.js.
  */
 export const consoleMethods = new Set([
   'debug',
@@ -72,15 +77,18 @@ function getMessage(sourceLabel: string, message: unknown, ...args: unknown[]) {
 }
 
 /**
- * Create a a {@link console} object, with the same properties as the global
+ * Create a {@link console} object, with the same properties as the global
  * {@link console} object, but with some methods replaced.
  *
  * @param options - Factory options used in construction of the endowment.
  * @param options.sourceLabel - Label identifying the source of the console call.
  * @returns The {@link console} object with the replaced methods.
  */
-function createConsole({ sourceLabel }: EndowmentFactoryOptions = {}) {
-  assert(sourceLabel !== undefined);
+function createConsole({ sourceLabel }: ConsoleEndowmentOptions) {
+  assert(
+    sourceLabel !== undefined,
+    'The "sourceLabel" option is required by the console endowment factory.',
+  );
   const keys = Object.getOwnPropertyNames(
     rootRealmGlobal.console,
   ) as (keyof typeof console)[];

packages/snaps-execution-environments/src/common/endowments/network.ts

@@ -3,6 +3,10 @@ import { assert } from '@metamask/utils';
 import type { EndowmentFactoryOptions } from './commonEndowmentFactory';
 import { withTeardown } from '../utils';
 
+type NetworkEndowmentOptions = Required<
+  Pick<EndowmentFactoryOptions, 'notify'>
+>;
+
 /**
  * This class wraps a Response object.
  * That way, a teardown process can stop any processes left.
@@ -157,20 +161,24 @@ class AlteredResponse extends Response {
 /**
  * Create a network endowment, consisting of a `fetch` function.
  * This allows us to provide a teardown function, so that we can cancel
- * any pending requests, connections, streams, etc. that may be open when a snap
- * is terminated.
+ * any pending requests, connections, streams, etc. that may be open when the
+ * execution context is torn down.
  *
  * This wraps the original implementation of `fetch`,
  * to ensure that a bad actor cannot get access to the original function, thus
  * potentially preventing the network requests from being torn down.
  *
  * @param options - An options bag.
- * @param options.notify - A reference to the notify function of the snap executor.
+ * @param options.notify - A notification callback for outbound request
+ * lifecycle events.
  * @returns An object containing a wrapped `fetch`
  * function, as well as a teardown function.
  */
-const createNetwork = ({ notify }: EndowmentFactoryOptions = {}) => {
-  assert(notify, 'Notify must be passed to network endowment factory');
+const createNetwork = ({ notify }: NetworkEndowmentOptions) => {
+  assert(
+    notify,
+    'The "notify" callback is required by the network endowment factory.',
+  );
   // Open fetch calls or open body streams
   const openConnections = new Set<{ cancel: () => Promise<void> }>();
   // Track last teardown count

packages/snaps-execution-environments/src/endowments.test.ts

@@ -0,0 +1,46 @@
+import {
+  timeout,
+  interval,
+  date,
+  textEncoder,
+  textDecoder,
+  crypto,
+  math,
+  consoleEndowment,
+  network,
+  buildCommonEndowments,
+} from './endowments';
+
+describe('endowments barrel', () => {
+  it.each([
+    { name: 'timeout', module: timeout, expectedName: 'setTimeout' },
+    { name: 'interval', module: interval, expectedName: 'setInterval' },
+    { name: 'date', module: date, expectedName: 'Date' },
+    { name: 'textEncoder', module: textEncoder, expectedName: 'TextEncoder' },
+    { name: 'textDecoder', module: textDecoder, expectedName: 'TextDecoder' },
+    { name: 'crypto', module: crypto, expectedName: 'crypto' },
+    { name: 'math', module: math, expectedName: 'Math' },
+    {
+      name: 'consoleEndowment',
+      module: consoleEndowment,
+      expectedName: 'console',
+    },
+    { name: 'network', module: network, expectedName: 'fetch' },
+  ])('exports $name with names and factory', ({ module, expectedName }) => {
+    expect(module).toHaveProperty('names');
+    expect(module).toHaveProperty('factory');
+    expect(module.names).toContain(expectedName);
+    expect(typeof module.factory).toBe('function');
+  });
+
+  it('exports buildCommonEndowments', () => {
+    expect(typeof buildCommonEndowments).toBe('function');
+    const factories = buildCommonEndowments();
+    expect(Array.isArray(factories)).toBe(true);
+    expect(factories.length).toBeGreaterThan(0);
+    factories.forEach((factory) => {
+      expect(factory).toHaveProperty('names');
+      expect(factory).toHaveProperty('factory');
+    });
+  });
+});

packages/snaps-execution-environments/src/endowments.ts

@@ -1,9 +1,13 @@
 /**
  * Public endowment factory exports for use outside the Snaps ecosystem.
  *
+ * **Prerequisite**: These factories call the SES `harden()` global internally.
+ * The consuming environment must have loaded SES and called `lockdown()` before
+ * invoking any factory function.
+ *
  * Each module provides a `names` array and a `factory` function. Call
  * `factory()` to obtain hardened endowment values (and an optional
- * `teardownFunction` for timer-based endowments).
+ * `teardownFunction` for stateful endowments that manage resources).
  *
  * @example
  * ```ts
@@ -13,7 +17,7 @@
  * // { setTimeout, clearTimeout, teardownFunction }
  *
  * const dateEndowment = date.factory();
- * // { Date } (with noise-added Date.now)
+ * // { Date } (with attenuated Date.now)
  * ```
  *
  * @module endowments
@@ -37,5 +41,4 @@ export type {
   EndowmentFactoryOptions,
   EndowmentFactoryResult,
   EndowmentFactory,
-  CommonEndowmentSpecification,
 } from './common/endowments/commonEndowmentFactory';