feat(ocap-kernel): Setup a general endowment pattern

Author: grypez

packages/ocap-kernel/src/VatSupervisor.ts

@@ -1,12 +1,8 @@
-import {
-  makeLiveSlots as localMakeLiveSlots,
-  makeMarshaller,
-} from '@agoric/swingset-liveslots';
+import { makeLiveSlots as localMakeLiveSlots } from '@agoric/swingset-liveslots';
 import type {
   VatDeliveryObject,
   VatSyscallResult,
 } from '@agoric/swingset-liveslots';
-import { Fail } from '@endo/errors';
 import { importBundle } from '@endo/import-bundle';
 import { makeMarshal } from '@endo/marshal';
 import type { CapData } from '@endo/marshal';
@@ -20,6 +16,7 @@ import { serializeError } from '@metamask/rpc-errors';
 import type { DuplexStream } from '@metamask/streams';
 import { isJsonRpcRequest, isJsonRpcResponse } from '@metamask/utils';
 
+import { makeEndowments } from './endowments/index.ts';
 import { vatSyscallMethodSpecs, vatHandlers } from './rpc/index.ts';
 import { makeGCAndFinalize } from './services/gc-finalize.ts';
 import { makeDummyMeterControl } from './services/meter-control.ts';
@@ -31,7 +28,6 @@ import type {
   VatDeliveryResult,
   VatId,
   VatSyscallObject,
-  VRef,
 } from './types.ts';
 import { isVatConfig, coerceVatSyscallObject } from './types.ts';
 
@@ -260,21 +256,10 @@ export class VatSupervisor {
       meterControl: makeDummyMeterControl(),
     });
 
-    const { m } = makeMarshaller(syscall, gcTools, this.id);
-    const toRef = (object: unknown): VRef =>
-      m.toCapData(object).slots[0] ?? Fail`cannot revoke object ${object}`;
-    const makeRevoker = (object: unknown): (() => void) => {
-      const ref = toRef(object);
-      return harden(() => {
-        syscall.revoke([ref]);
-      });
-    };
-    harden(makeRevoker);
-
     const workerEndowments = {
       console: this.#logger.subLogger({ tags: ['console'] }),
       assert: globalThis.assert,
-      makeRevoker,
+      ...makeEndowments(syscall, gcTools, this.id),
     };
 
     const { bundleSpec, parameters } = vatConfig;

packages/ocap-kernel/src/endowments/context.ts

@@ -0,0 +1,50 @@
+import { makeMarshaller } from '@agoric/swingset-liveslots';
+import { Fail } from '@endo/errors';
+
+// Used in the docs for a safe use of `toRef`.
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import type { factory as makeRevoker } from './factories/make-revoker.ts';
+import type { EndowmentContext, ToRef, Marshaller } from './types.ts';
+import type { GCTools, Syscall } from '../services/types.ts';
+import type { VatId } from '../types.ts';
+
+/**
+ * Make a function that converts an object to a vref.
+ *
+ * **ATTN**: Do not expose the return value of this function to user code.
+ *
+ * This is a hack that disrespects liveslots's encapsulation of the marshaller.
+ * If the user code gets a handle on `toRef` and a capability to send messages
+ * to the kernel, it can break vat containment by impersonating its supervisor.
+ *
+ * It is fine to expose a hardened function which passes an object to `toRef`,
+ * as long as the vref cannot escape the scope of that function.
+ *
+ * @see {@link makeRevoker} for an example of safe use of `toRef`.
+ *
+ * @param marshaller - The liveslots marshaller.
+ * @returns A function that converts an object to a vref.
+ */
+function makeToRef(marshaller: Marshaller): ToRef {
+  const toRef: ToRef = (object) =>
+    marshaller.toCapData(object).slots[0] ??
+    Fail`cannot make ocap url for object ${object}`;
+  return harden(toRef);
+}
+
+/**
+ * Make a context for an endowment.
+ *
+ * @param syscall - The syscall object.
+ * @param gcTools - The gc tools.
+ * @param vatId - The vat id.
+ * @returns A context for an endowment.
+ */
+export function makeEndowmentContext(
+  syscall: Syscall,
+  gcTools: GCTools,
+  vatId: VatId,
+): EndowmentContext {
+  const toRef = makeToRef(makeMarshaller(syscall, gcTools, vatId).m);
+  return { syscall, gcTools, vatId, toRef };
+}

packages/ocap-kernel/src/endowments/factories/index.ts

@@ -0,0 +1,16 @@
+import * as makeRevoker from './make-revoker.ts';
+import * as scry from './scry.ts';
+import type { EndowmentDefinition } from '../types.ts';
+
+const endowmentDefinitions = {
+  makeRevoker,
+  scry,
+} as const satisfies Record<string, EndowmentDefinition>;
+
+export type EndowmentName = keyof typeof endowmentDefinitions;
+
+export type Endowments = {
+  [K in EndowmentName]: ReturnType<(typeof endowmentDefinitions)[K]['factory']>;
+};
+
+export default endowmentDefinitions;

packages/ocap-kernel/src/endowments/factories/make-revoker.ts

@@ -0,0 +1,40 @@
+import type { VRef } from '../../types.ts';
+import type { EndowmentContext } from '../types.ts';
+
+/**
+ * A function that revokes a distributed object, making it impossible to call
+ * any methods on it.
+ */
+export type Revoker = () => void;
+
+/**
+ * A function that makes a revoker for a given object.
+ */
+export type MakeRevoker = (object: unknown) => Revoker;
+
+/**
+ * Make a function that makes a revoker for a given object. Intended to be used
+ * as a user code endowment.
+ *
+ * @param context - The context in which the endowment is created.
+ * @returns A function that makes a revoker for a given object.
+ */
+export function factory(context: EndowmentContext): MakeRevoker {
+  const { syscall, toRef } = context;
+  const revoke = (vref: VRef): void => {
+    syscall.revoke([vref]);
+  };
+  /**
+   * Make a revoker for a given object. A vat can only revoke its own objects,
+   * so revokable delegation is not possible. After the revoker is called, all
+   * eventual method calls from importers of the distributed object will fail.
+   *
+   * @param object - The object to revoke.
+   * @returns A function that revokes the object.
+   */
+  function makeRevoker(object: unknown): Revoker {
+    const ref = toRef(object);
+    return harden(() => revoke(ref));
+  }
+  return harden(makeRevoker);
+}

packages/ocap-kernel/src/endowments/factories/scry.ts

@@ -0,0 +1,21 @@
+import type { VRef } from '../../types.ts';
+import type { EndowmentContext } from '../types.ts';
+
+/**
+ * A function that scries a vref.
+ */
+export type Scry = (vref: VRef) => unknown;
+
+/**
+ * Make a function that scries a vref. It logs to the console, which in
+ * production is a no-op. In development, it can be used to inspect the
+ * contents of a vref.
+ *
+ * @param context - The context in which the endowment is created.
+ * @returns A function that scries a vref.
+ */
+export function factory(context: EndowmentContext): Scry {
+  const { toRef } = context;
+  const scry: Scry = (object: unknown) => console.log(`scry ${toRef(object)}`);
+  return harden(scry);
+}

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

@@ -0,0 +1,31 @@
+import type { GCTools, Syscall } from '../services/types.ts';
+import type { VatId } from '../types.ts';
+import { makeEndowmentContext } from './context.ts';
+import type { EndowmentName, Endowments } from './factories/index.ts';
+import endowmentDefinitions from './factories/index.ts';
+
+const allEndowmentNames = Object.keys(endowmentDefinitions) as EndowmentName[];
+
+/**
+ * Make a set of endowments for a vat.
+ *
+ * @param syscall - The syscall object.
+ * @param gcTools - The gc tools.
+ * @param vatId - The vat id.
+ * @param names - The names of the endowments to make. If not provided, all
+ *   endowments are made. XXX The default should be to make *no* endowments.
+ * @returns A set of endowments for a vat.
+ */
+export function makeEndowments(
+  syscall: Syscall,
+  gcTools: GCTools,
+  vatId: VatId,
+  names: EndowmentName[] = allEndowmentNames,
+): Endowments {
+  const context = makeEndowmentContext(syscall, gcTools, vatId);
+  return Object.fromEntries(
+    Object.entries(endowmentDefinitions)
+      .filter(([name]) => names.includes(name as EndowmentName))
+      .map(([name, definition]) => [name, definition.factory(context)]),
+  ) as Endowments;
+}

packages/ocap-kernel/src/endowments/types.ts

@@ -0,0 +1,25 @@
+import type { makeMarshaller } from '@agoric/swingset-liveslots';
+
+import type { GCTools, Syscall } from '../services/types.ts';
+import type { VRef, VatId } from '../types.ts';
+
+export type Marshaller = ReturnType<typeof makeMarshaller>['m'];
+
+/**
+ * A function that converts an object to a vref.
+ */
+export type ToRef = (object: unknown) => VRef;
+
+/**
+ * The context in which an endowment is created.
+ */
+export type EndowmentContext = {
+  syscall: Syscall;
+  gcTools: GCTools;
+  vatId: VatId;
+  toRef: ToRef;
+};
+
+export type EndowmentDefinition = {
+  factory: (context: EndowmentContext) => unknown;
+};