feat(extension): Add distributed object capability programming

packages/extension/package.json

@@ -31,7 +31,10 @@
     "test:watch": "vitest --config vitest.config.ts"
   },
   "dependencies": {
+    "@endo/captp": "^4.2.2",
     "@endo/eventual-send": "^1.2.4",
+    "@endo/exo": "^1.5.2",
+    "@endo/patterns": "^1.4.2",
     "@endo/promise-kit": "^1.1.4",
     "@metamask/snaps-utils": "^7.8.0",
     "@metamask/utils": "^9.1.0",

packages/extension/src/background-trusted-prelude.js

@@ -1,2 +1,2 @@
-import './dev-console.js';
 import './endoify.js';
+import './dev-console.js';

packages/extension/src/background.ts

@@ -1,19 +1,30 @@
+import type { Json } from '@metamask/utils';
+
 import './background-trusted-prelude.js';
-import type { ExtensionMessage } from './shared.js';
-import { Command, makeHandledCallback } from './shared.js';
+import type { ExtensionMessage } from './message.js';
+import { Command, ExtensionMessageTarget } from './message.js';
+import { makeHandledCallback } from './shared.js';
 
-// globalThis.kernel will exist due to dev-console.js
+// globalThis.kernel will exist due to dev-console.js in background-trusted-prelude.js
 Object.defineProperties(globalThis.kernel, {
-  sendMessage: {
-    value: sendMessage,
+  capTpCall: {
+    value: async (method: string, params: Json[]) =>
+      sendMessage(Command.CapTpCall, { method, params }),
+  },
+  capTpInit: {
+    value: async () => sendMessage(Command.CapTpInit),
   },
   evaluate: {
     value: async (source: string) => sendMessage(Command.Evaluate, source),
   },
   ping: {
     value: async () => sendMessage(Command.Ping),
   },
+  sendMessage: {
+    value: sendMessage,
+  },
 });
+harden(globalThis.kernel);
 
 const OFFSCREEN_DOCUMENT_PATH = '/offscreen.html';
 
@@ -29,12 +40,12 @@ chrome.action.onClicked.addListener(() => {
  * @param data - The message data.
  * @param data.name - The name to include in the message.
  */
-async function sendMessage(type: string, data?: string): Promise<void> {
+async function sendMessage(type: string, data?: Json): Promise<void> {
   await provideOffScreenDocument();
 
   await chrome.runtime.sendMessage({
     type,
-    target: 'offscreen',
+    target: ExtensionMessageTarget.Offscreen,
     data: data ?? null,
   });
 }
@@ -54,8 +65,8 @@ async function provideOffScreenDocument(): Promise<void> {
 
 // Handle replies from the offscreen document
 chrome.runtime.onMessage.addListener(
-  makeHandledCallback(async (message: ExtensionMessage<Command, string>) => {
-    if (message.target !== 'background') {
+  makeHandledCallback(async (message: ExtensionMessage) => {
+    if (message.target !== ExtensionMessageTarget.Background) {
       console.warn(
         `Background received message with unexpected target: "${message.target}"`,
       );
@@ -64,25 +75,17 @@ chrome.runtime.onMessage.addListener(
 
     switch (message.type) {
       case Command.Evaluate:
+      case Command.CapTpCall:
+      case Command.CapTpInit:
       case Command.Ping:
         console.log(message.data);
-        await closeOffscreenDocument();
         break;
       default:
         console.error(
+          // @ts-expect-error The type of `message` is `never`, but this could happen at runtime.
           // eslint-disable-next-line @typescript-eslint/restrict-template-expressions
           `Background received unexpected message type: "${message.type}"`,
         );
     }
   }),
 );
-
-/**
- * Close the offscreen document if it exists.
- */
-async function closeOffscreenDocument(): Promise<void> {
-  if (!(await chrome.offscreen.hasDocument())) {
-    return;
-  }
-  await chrome.offscreen.closeDocument();
-}

packages/extension/src/dev-console.test.ts

@@ -0,0 +1,21 @@
+import { describe, it, expect } from 'vitest';
+import '@ocap/shims/endoify';
+import './dev-console.js';
+
+describe('vat-console', () => {
+  describe('kernel', () => {
+    it('is available on globalThis', async () => {
+      expect(kernel).toBeDefined();
+    });
+
+    it('has expected property descriptors', async () => {
+      expect(
+        Object.getOwnPropertyDescriptor(globalThis, 'kernel'),
+      ).toMatchObject({
+        configurable: false,
+        enumerable: true,
+        writable: false,
+      });
+    });
+  });
+});

packages/extension/src/envelope.ts

@@ -0,0 +1,22 @@
+import { isObject } from '@metamask/utils';
+
+import type { WrappedIframeMessage } from './message.js';
+import { isWrappedIframeMessage } from './message.js';
+
+export enum EnvelopeLabel {
+  Command = 'command',
+  CapTp = 'capTp',
+}
+
+export type StreamEnvelope =
+  | {
+      label: EnvelopeLabel.Command;
+      content: WrappedIframeMessage;
+    }
+  | { label: EnvelopeLabel.CapTp; content: unknown };
+
+export const isStreamEnvelope = (value: unknown): value is StreamEnvelope =>
+  isObject(value) &&
+  (value.label === EnvelopeLabel.CapTp ||
+    (value.label === EnvelopeLabel.Command &&
+      isWrappedIframeMessage(value.content)));