From 46ef24100ae80f5495b5ba47a967592c99727fea Mon Sep 17 00:00:00 2001
From: grypez <143971198+grypez@users.noreply.github.com>
Date: Fri, 13 Sep 2024 12:05:41 -0500
Subject: [PATCH 01/22] feat(extension): Add stream envelope handler.

---
 packages/extension/src/envelope.test.ts | 110 ++++++++++++++++
 packages/extension/src/envelope.ts      | 166 ++++++++++++++++++++++--
 packages/extension/src/message.ts       |   3 +
 3 files changed, 267 insertions(+), 12 deletions(-)
 create mode 100644 packages/extension/src/envelope.test.ts

diff --git a/packages/extension/src/envelope.test.ts b/packages/extension/src/envelope.test.ts
new file mode 100644
index 000000000..1422370e9
--- /dev/null
+++ b/packages/extension/src/envelope.test.ts
@@ -0,0 +1,110 @@
+import { describe, it, expect } from 'vitest';
+
+import {
+  capTpEnveloper,
+  commandEnveloper,
+  EnvelopeLabel,
+  isStreamEnvelope,
+  makeStreamEnvelopeHandler,
+} from './envelope.js';
+import { Command } from './message.js';
+
+const contentFixtures = {
+  command: { id: '1', message: { type: Command.Evaluate, data: '1 + 1' } },
+  capTp: { id: '4', message: { type: 'CTP_CALL', epoch: 0 } },
+};
+
+describe('envelope', () => {
+  describe('isStreamEnvelope', () => {
+    it('returns true for valid messages', () => {
+      expect(
+        isStreamEnvelope({
+          label: EnvelopeLabel.Command,
+          content: {
+            id: '1',
+            message: { type: 'evaluate', data: '1 + 1' },
+          },
+        }),
+      ).toBe(true);
+    });
+
+    it.each`
+      exportName            | enveloper           | content
+      ${'commandEnveloper'} | ${commandEnveloper} | ${contentFixtures.command}
+      ${'capTpEnveloper'}   | ${capTpEnveloper}   | ${contentFixtures.capTp}
+    `(
+      'returns true for valid contents wrapped by $enveloper.label',
+      ({ enveloper, content }) => {
+        expect(isStreamEnvelope(enveloper.wrap(content))).toBe(true);
+      },
+    );
+
+    it.each`
+      envelope
+      ${{}}
+      ${{ label: EnvelopeLabel.Command }}
+      ${{ label: EnvelopeLabel.CapTp }}
+      ${{ label: EnvelopeLabel.Command, content: contentFixtures.capTp }}
+      ${{ label: 'unknown', content: [] }}
+    `('returns false for invalid envelopes: $envelope', ({ envelope }) => {
+      expect(isStreamEnvelope(envelope)).toBe(false);
+    });
+  });
+
+  describe('StreamEnvelopeHandler', () => {
+    const testEnvelopeHandlers = {
+      command: async () => EnvelopeLabel.Command,
+      capTp: async () => EnvelopeLabel.CapTp,
+    };
+    const testErrorHandler = (problem: unknown): never => {
+      throw new Error(`TEST ${String(problem)}`);
+    };
+    const handler = makeStreamEnvelopeHandler(
+      testEnvelopeHandlers,
+      testErrorHandler,
+    );
+
+    it.each`
+      enveloper           | message
+      ${commandEnveloper} | ${contentFixtures.command}
+      ${capTpEnveloper}   | ${contentFixtures.capTp}
+    `('handles valid StreamEnvelopes', async ({ enveloper, message }) => {
+      expect(await handler(enveloper.wrap(message))).toStrictEqual(
+        enveloper.label,
+      );
+    });
+
+    it('routes invalid envelopes to supplied error handler', async () => {
+      await expect(handler({ label: 'unknown', content: [] })).rejects.toThrow(
+        /TEST Stream envelope handler received unexpected value/u,
+      );
+    });
+
+    it('routes valid stream envelopes with an unhandled label to the error handler', async () => {
+      const commandHandler = makeStreamEnvelopeHandler(
+        { command: testEnvelopeHandlers.command },
+        testErrorHandler,
+      );
+      await expect(
+        commandHandler(capTpEnveloper.wrap(contentFixtures.capTp)),
+      ).rejects.toThrow(
+        /TEST Stream envelope handler received an envelope with known but unexpected label/u,
+      );
+    });
+  });
+
+  describe('envelopeKit', () => {
+    it.each`
+      enveloper           | envelope
+      ${commandEnveloper} | ${contentFixtures.capTp}
+      ${capTpEnveloper}   | ${contentFixtures.command}
+    `(
+      'throws when unwrapping a malformed envelope',
+      ({ enveloper, envelope }) => {
+        expect(() => enveloper.unwrap(envelope)).toThrow(
+          /Expected envelope labelled/u,
+        );
+      },
+    );
+  });
+});
diff --git a/packages/extension/src/envelope.ts b/packages/extension/src/envelope.ts
index cc5e72e37..9951f2d27 100644
--- a/packages/extension/src/envelope.ts
+++ b/packages/extension/src/envelope.ts
@@ -1,22 +1,164 @@
 import { isObject } from '@metamask/utils';
 
-import type { WrappedIframeMessage } from './message.js';
-import { isWrappedIframeMessage } from './message.js';
+import type { CapTpMessage, WrappedIframeMessage } from './message.js';
+import { isCapTpMessage, isWrappedIframeMessage } from './message.js';
 
 export enum EnvelopeLabel {
   Command = 'command',
   CapTp = 'capTp',
 }
 
-export type StreamEnvelope =
-  | {
-      label: EnvelopeLabel.Command;
-      content: WrappedIframeMessage;
-    }
-  | { label: EnvelopeLabel.CapTp; content: unknown };
+type EnvelopeForm<Label extends EnvelopeLabel, Content> = {
+  label: Label;
+  content: Content;
+};
 
-export const isStreamEnvelope = (value: unknown): value is StreamEnvelope =>
+type LabelOf<Env> = Env extends EnvelopeForm<infer Label, unknown>
+  ? Label
+  : never;
+type LabeledWith<Label extends EnvelopeLabel> = {
+  label: Label;
+  [key: string]: unknown;
+};
+const isLabeled = <Label extends EnvelopeLabel>(
+  value: unknown,
+  label?: Label,
+): value is LabeledWith<Label> =>
   isObject(value) &&
-  (value.label === EnvelopeLabel.CapTp ||
-    (value.label === EnvelopeLabel.Command &&
-      isWrappedIframeMessage(value.content)));
+  typeof value.label !== 'undefined' &&
+  (label === undefined || value.label === label);
+
+type ContentOf<Env> = Env extends EnvelopeForm<EnvelopeLabel, infer Content>
+  ? Content
+  : never;
+type ContainerOf<Content> = {
+  content: Content;
+  [key: string]: unknown;
+};
+
+type GenericEnvelope<Env> = EnvelopeForm<LabelOf<Env>, ContentOf<Env>>;
+
+type EnvelopeKit<Env extends GenericEnvelope<Env>> = {
+  label: Env['label'];
+  sniff: (value: unknown) => value is LabeledWith<Env['label']>;
+  check: (value: unknown) => value is Env;
+  wrap: (content: Env['content']) => Env;
+  unwrap: (envelope: Env) => Env['content'];
+};
+
+const makeEnvelopeKit = <Env extends GenericEnvelope<Env>>(
+  label: Env['label'],
+  isContent: (value: unknown) => value is Env['content'],
+): EnvelopeKit<Env> => {
+  const hasLabel = (value: unknown): value is LabeledWith<Env['label']> =>
+    isLabeled(value, label);
+  const hasContent = (value: unknown): value is ContainerOf<ContentOf<Env>> =>
+    isObject(value) &&
+    typeof value.content !== 'undefined' &&
+    isContent(value.content);
+  return {
+    label,
+    sniff: hasLabel,
+    check: (value: unknown): value is Env =>
+      hasLabel(value) && hasContent(value),
+    wrap: (content: ContentOf<Env>) =>
+      ({
+        label,
+        content,
+      } as Env),
+    unwrap: (envelope: Env): Env['content'] => {
+      if (!hasLabel(envelope)) {
+        throw new Error(
+          // @ts-expect-error The type of `envelope` is `never`, but this could happen at runtime.
+          // eslint-disable-next-line @typescript-eslint/restrict-template-expressions
+          `Expected envelope labelled "${label}" but got "${envelope.label}".`,
+        );
+      }
+      return envelope.content;
+    },
+  };
+};
+
+type CommandEnvelope = EnvelopeForm<
+  EnvelopeLabel.Command,
+  WrappedIframeMessage
+>;
+type CapTpEnvelope = EnvelopeForm<EnvelopeLabel.CapTp, CapTpMessage>;
+
+export const commandEnveloper = makeEnvelopeKit<CommandEnvelope>(
+  EnvelopeLabel.Command,
+  isWrappedIframeMessage,
+);
+export const capTpEnveloper = makeEnvelopeKit<CapTpEnvelope>(
+  EnvelopeLabel.CapTp,
+  isCapTpMessage,
+);
+
+export const streamEnveloper = {
+  sniffCommand: commandEnveloper.sniff,
+  checkCommand: commandEnveloper.check,
+  wrapCommand: commandEnveloper.wrap,
+  unwrapCommand: commandEnveloper.unwrap,
+
+  sniffCapTp: capTpEnveloper.sniff,
+  checkCapTp: capTpEnveloper.check,
+  wrapCapTp: capTpEnveloper.wrap,
+  unwrapCapTp: capTpEnveloper.unwrap,
+};
+
+export type StreamEnvelope = CommandEnvelope | CapTpEnvelope;
+
+type StreamEnvelopeContent<Label extends LabelOf<StreamEnvelope>> =
+  Label extends EnvelopeLabel.Command
+    ? CommandEnvelope['content']
+    : Label extends EnvelopeLabel.CapTp
+    ? CapTpEnvelope['content']
+    : never;
+
+const envelopeKits: { [Label in EnvelopeLabel]: EnvelopeKit<StreamEnvelope> } =
+  Object.fromEntries([
+    [EnvelopeLabel.Command, commandEnveloper],
+    [EnvelopeLabel.CapTp, capTpEnveloper],
+  ]);
+
+export const isStreamEnvelope = (value: unknown): value is StreamEnvelope =>
+  isLabeled(value) &&
+  Object.values(envelopeKits).some((kit) => kit.check(value));
+
+type ContentHandler<Label extends LabelOf<StreamEnvelope>> = (
+  content: StreamEnvelopeContent<Label>,
+) => Promise<unknown>;
+
+type ErrorHandler = (...args: unknown[]) => never;
+
+type ContentHandlerBag = { [Label in EnvelopeLabel]?: ContentHandler<Label> };
+
+const defaultStreamEnvelopeErrorHandler = (problem: unknown): never => {
+  throw new Error(String(problem));
+};
+export const makeStreamEnvelopeHandler =
+  (
+    contentHandlers: ContentHandlerBag,
+    errorHandler: ErrorHandler = defaultStreamEnvelopeErrorHandler,
+  ) =>
+  async (value: unknown) => {
+    const envelope = isStreamEnvelope(value)
+      ? value
+      : errorHandler(
+          `Stream envelope handler received unexpected value ${JSON.stringify(
+            value,
+          )}`,
+        );
+    const kit =
+      /* v8 ignore next 4: Not known to be possible. */
+      envelopeKits[envelope.label] ??
+      errorHandler(
+        `Stream envelope handler received an envelope with unknown label "${envelope.label}"`,
+      );
+    const handler: ContentHandler<typeof envelope.label> =
+      contentHandlers[envelope.label] ??
+      errorHandler(
+        `Stream envelope handler received an envelope with known but unexpected label "${envelope.label}"`,
+      );
+    return handler(kit.unwrap(envelope));
+  };
diff --git a/packages/extension/src/message.ts b/packages/extension/src/message.ts
index c9e26b614..16682a62c 100644
--- a/packages/extension/src/message.ts
+++ b/packages/extension/src/message.ts
@@ -58,3 +58,6 @@ export const isWrappedIframeMessage = (
   isObject(value.message) &&
   typeof value.message.type === 'string' &&
   (typeof value.message.data === 'string' || value.message.data === null);
+
+export type CapTpMessage = unknown;
+export const isCapTpMessage = (value: unknown): value is CapTpMessage => true;

From 93d0787ba63db9e680aac5eaaa7b9d7cb8a5b0c9 Mon Sep 17 00:00:00 2001
From: grypez <143971198+grypez@users.noreply.github.com>
Date: Fri, 13 Sep 2024 13:46:25 -0500
Subject: [PATCH 02/22] feat(extension): Use stream envelope handler.

---
 packages/extension/src/envelope.ts            | 46 ++++++++++--------
 packages/extension/src/iframe-manager.test.ts |  3 +-
 packages/extension/src/iframe-manager.ts      | 48 +++++++------------
 packages/extension/src/iframe.ts              | 43 ++++++-----------
 4 files changed, 56 insertions(+), 84 deletions(-)

diff --git a/packages/extension/src/envelope.ts b/packages/extension/src/envelope.ts
index 9951f2d27..4f1413a11 100644
--- a/packages/extension/src/envelope.ts
+++ b/packages/extension/src/envelope.ts
@@ -129,36 +129,40 @@ type ContentHandler<Label extends LabelOf<StreamEnvelope>> = (
   content: StreamEnvelopeContent<Label>,
 ) => Promise<unknown>;
 
-type ErrorHandler = (...args: unknown[]) => never;
+type ErrorHandler = (reason: string) => unknown;
 
 type ContentHandlerBag = { [Label in EnvelopeLabel]?: ContentHandler<Label> };
-
-const defaultStreamEnvelopeErrorHandler = (problem: unknown): never => {
-  throw new Error(String(problem));
+const defaultErrorHandler: ErrorHandler = (reason) => {
+  throw new Error(reason);
 };
 export const makeStreamEnvelopeHandler =
   (
     contentHandlers: ContentHandlerBag,
-    errorHandler: ErrorHandler = defaultStreamEnvelopeErrorHandler,
+    errorHandler: ErrorHandler = defaultErrorHandler,
   ) =>
-  async (value: unknown) => {
-    const envelope = isStreamEnvelope(value)
-      ? value
-      : errorHandler(
-          `Stream envelope handler received unexpected value ${JSON.stringify(
-            value,
-          )}`,
-        );
-    const kit =
-      /* v8 ignore next 4: Not known to be possible. */
-      envelopeKits[envelope.label] ??
-      errorHandler(
+  async (value: unknown): Promise<unknown> => {
+    if (!isStreamEnvelope(value)) {
+      return errorHandler(
+        `Stream envelope handler received unexpected value ${JSON.stringify(
+          value,
+        )}`,
+      );
+    }
+    const envelope = value;
+    const kit = envelopeKits[envelope.label];
+    /* v8 ignore next 5: Not known to be possible. */
+    if (!kit) {
+      return errorHandler(
         `Stream envelope handler received an envelope with unknown label "${envelope.label}"`,
       );
-    const handler: ContentHandler<typeof envelope.label> =
-      contentHandlers[envelope.label] ??
-      errorHandler(
+    }
+    const handler = contentHandlers[envelope.label];
+    if (!handler) {
+      return errorHandler(
         `Stream envelope handler received an envelope with known but unexpected label "${envelope.label}"`,
       );
-    return handler(kit.unwrap(envelope));
+    }
+    return await (handler as ContentHandler<typeof envelope.label>)(
+      kit.unwrap(envelope),
+    );
   };
diff --git a/packages/extension/src/iframe-manager.test.ts b/packages/extension/src/iframe-manager.test.ts
index 146c45799..e38d8d24c 100644
--- a/packages/extension/src/iframe-manager.test.ts
+++ b/packages/extension/src/iframe-manager.test.ts
@@ -502,8 +502,7 @@ describe('IframeManager', () => {
       await delay(10);
 
       expect(warnSpy).toHaveBeenCalledWith(
-        'Offscreen received message with unexpected format',
-        'foo',
+        'Stream envelope handler received unexpected value "foo"',
       );
     });
 
diff --git a/packages/extension/src/iframe-manager.ts b/packages/extension/src/iframe-manager.ts
index 0adea2c18..add3d92a1 100644
--- a/packages/extension/src/iframe-manager.ts
+++ b/packages/extension/src/iframe-manager.ts
@@ -10,7 +10,7 @@ import {
 } from '@ocap/streams';
 
 import type { StreamEnvelope } from './envelope.js';
-import { EnvelopeLabel, isStreamEnvelope } from './envelope.js';
+import { EnvelopeLabel, makeStreamEnvelopeHandler } from './envelope.js';
 import type { CapTpPayload, IframeMessage, MessageId } from './message.js';
 import { Command } from './message.js';
 import { makeCounter, type VatId } from './shared.js';
@@ -169,31 +169,10 @@ export class IframeManager {
     reader: Reader<StreamEnvelope>,
   ): Promise<void> {
     const vat = this.#expectGetVat(vatId);
-    for await (const rawMessage of reader) {
-      console.debug('Offscreen received message', rawMessage);
 
-      if (!isStreamEnvelope(rawMessage)) {
-        console.warn(
-          'Offscreen received message with unexpected format',
-          rawMessage,
-        );
-        return;
-      }
-
-      switch (rawMessage.label) {
-        case EnvelopeLabel.CapTp: {
-          console.log(
-            'CapTP from vat',
-            JSON.stringify(rawMessage.content, null, 2),
-          );
-          const { capTp } = this.#expectGetVat(vatId);
-          if (capTp !== undefined) {
-            capTp.dispatch(rawMessage.content);
-          }
-          break;
-        }
-        case EnvelopeLabel.Command: {
-          const { id, message } = rawMessage.content;
+    const streamEnvelopeHandler = makeStreamEnvelopeHandler(
+      {
+        command: async ({ id, message }) => {
           const promiseCallbacks = vat.unresolvedMessages.get(id);
           if (promiseCallbacks === undefined) {
             console.error(`No unresolved message with id "${id}".`);
@@ -201,13 +180,18 @@ export class IframeManager {
             vat.unresolvedMessages.delete(id);
             promiseCallbacks.resolve(message.data);
           }
-          break;
-        }
-        /* v8 ignore next 3: Exhaustiveness check */
-        default:
-          // @ts-expect-error The type of `rawMessage` is `never`, but this could happen at runtime.
-          throw new Error(`Unexpected message label "${rawMessage.label}".`);
-      }
+        },
+        capTp: async (content) => {
+          console.log('CapTP from vat', JSON.stringify(content, null, 2));
+          vat.capTp?.dispatch(content);
+        },
+      },
+      console.warn,
+    );
+
+    for await (const rawMessage of reader) {
+      console.debug('Offscreen received message', rawMessage);
+      await streamEnvelopeHandler(rawMessage);
     }
   }
 
diff --git a/packages/extension/src/iframe.ts b/packages/extension/src/iframe.ts
index bcd25f1ef..8e43ae7f2 100644
--- a/packages/extension/src/iframe.ts
+++ b/packages/extension/src/iframe.ts
@@ -4,7 +4,7 @@ import { M } from '@endo/patterns';
 import { receiveMessagePort, makeMessagePortStreamPair } from '@ocap/streams';
 
 import type { StreamEnvelope } from './envelope.js';
-import { EnvelopeLabel, isStreamEnvelope } from './envelope.js';
+import { streamEnveloper, makeStreamEnvelopeHandler } from './envelope.js';
 import type { IframeMessage, WrappedIframeMessage } from './message.js';
 import { Command } from './message.js';
 
@@ -20,31 +20,19 @@ async function main(): Promise<void> {
   const streams = makeMessagePortStreamPair<StreamEnvelope>(port);
   let capTp: ReturnType<typeof makeCapTP> | undefined;
 
+  const streamEnvelopeHandler = makeStreamEnvelopeHandler(
+    {
+      command: handleMessage,
+      capTp: async (content) => capTp?.dispatch(content),
+    },
+    (problem: unknown) => {
+      throw new Error(`[vat IFRAME] ${String(problem)}`);
+    },
+  );
+
   for await (const rawMessage of streams.reader) {
     console.debug('iframe received message', rawMessage);
-
-    if (!isStreamEnvelope(rawMessage)) {
-      console.error(
-        'iframe received message with unexpected format',
-        rawMessage,
-      );
-      return;
-    }
-
-    switch (rawMessage.label) {
-      case EnvelopeLabel.CapTp:
-        if (capTp !== undefined) {
-          capTp.dispatch(rawMessage.content);
-        }
-        break;
-      case EnvelopeLabel.Command:
-        await handleMessage(rawMessage.content);
-        break;
-      /* v8 ignore next 3: Exhaustiveness check */
-      default:
-        // @ts-expect-error The type of `rawMessage` is `never`, but this could happen at runtime.
-        throw new Error(`Unexpected message label "${rawMessage.label}".`);
-    }
+    await streamEnvelopeHandler(rawMessage);
   }
 
   await streams.return();
@@ -88,7 +76,7 @@ async function main(): Promise<void> {
         capTp = makeCapTP(
           'iframe',
           async (content: unknown) =>
-            streams.writer.next({ label: EnvelopeLabel.CapTp, content }),
+            streams.writer.next(streamEnveloper.wrapCapTp(content)),
           bootstrap,
         );
         await replyToMessage(id, { type: Command.CapTpInit, data: null });
@@ -115,10 +103,7 @@ async function main(): Promise<void> {
     id: string,
     message: IframeMessage,
   ): Promise<void> {
-    await streams.writer.next({
-      label: EnvelopeLabel.Command,
-      content: { id, message },
-    });
+    await streams.writer.next(streamEnveloper.wrapCommand({ id, message }));
   }
 
   /**

From 0654b70922fe39c855e8a59f78df8d526e081442 Mon Sep 17 00:00:00 2001
From: grypez <143971198+grypez@users.noreply.github.com>
Date: Fri, 13 Sep 2024 14:05:40 -0500
Subject: [PATCH 03/22] test(extension): Cleanup envelope tests.

---
 packages/extension/src/envelope.test.ts | 37 ++++++++++++++-------
 packages/extension/src/envelope.ts      | 44 +++++++++++++++++++++----
 2 files changed, 62 insertions(+), 19 deletions(-)

diff --git a/packages/extension/src/envelope.test.ts b/packages/extension/src/envelope.test.ts
index 1422370e9..987537222 100644
--- a/packages/extension/src/envelope.test.ts
+++ b/packages/extension/src/envelope.test.ts
@@ -29,11 +29,11 @@ describe('envelope', () => {
     });
 
     it.each`
-      exportName            | enveloper           | content
-      ${'commandEnveloper'} | ${commandEnveloper} | ${contentFixtures.command}
-      ${'capTpEnveloper'}   | ${capTpEnveloper}   | ${contentFixtures.capTp}
+      enveloper           | content
+      ${commandEnveloper} | ${contentFixtures.command}
+      ${capTpEnveloper}   | ${contentFixtures.capTp}
     `(
-      'returns true for valid contents wrapped by $enveloper.label',
+      'returns true for valid contents wrapped by $enveloper.label enveloper',
       ({ enveloper, content }) => {
         expect(isStreamEnvelope(enveloper.wrap(content))).toBe(true);
       },
@@ -59,36 +59,49 @@ describe('envelope', () => {
     const testErrorHandler = (problem: unknown): never => {
       throw new Error(`TEST ${String(problem)}`);
     };
-    const handler = makeStreamEnvelopeHandler(
-      testEnvelopeHandlers,
-      testErrorHandler,
-    );
 
     it.each`
       enveloper           | message
       ${commandEnveloper} | ${contentFixtures.command}
       ${capTpEnveloper}   | ${contentFixtures.capTp}
     `('handles valid StreamEnvelopes', async ({ enveloper, message }) => {
+      const handler = makeStreamEnvelopeHandler(
+        testEnvelopeHandlers,
+        testErrorHandler,
+      );
       expect(await handler(enveloper.wrap(message))).toStrictEqual(
         enveloper.label,
       );
     });
 
+    it('routes invalid envelopes to default error handler', async () => {
+      const handler = makeStreamEnvelopeHandler(testEnvelopeHandlers);
+      // @ts-expect-error label is intentionally unknown
+      await expect(handler({ label: 'unknown', content: [] })).rejects.toThrow(
+        /^Stream envelope handler received unexpected value/u,
+      );
+    });
+
     it('routes invalid envelopes to supplied error handler', async () => {
+      const handler = makeStreamEnvelopeHandler(
+        testEnvelopeHandlers,
+        testErrorHandler,
+      );
+      // @ts-expect-error label is intentionally unknown
       await expect(handler({ label: 'unknown', content: [] })).rejects.toThrow(
-        /TEST Stream envelope handler received unexpected value/u,
+        /^TEST Stream envelope handler received unexpected value/u,
       );
     });
 
     it('routes valid stream envelopes with an unhandled label to the error handler', async () => {
-      const commandHandler = makeStreamEnvelopeHandler(
+      const handler = makeStreamEnvelopeHandler(
         { command: testEnvelopeHandlers.command },
         testErrorHandler,
       );
       await expect(
-        commandHandler(capTpEnveloper.wrap(contentFixtures.capTp)),
+        handler(capTpEnveloper.wrap(contentFixtures.capTp)),
       ).rejects.toThrow(
-        /TEST Stream envelope handler received an envelope with known but unexpected label/u,
+        /^TEST Stream envelope handler received an envelope with known but unexpected label/u,
       );
     });
   });
diff --git a/packages/extension/src/envelope.ts b/packages/extension/src/envelope.ts
index 4f1413a11..423cdb003 100644
--- a/packages/extension/src/envelope.ts
+++ b/packages/extension/src/envelope.ts
@@ -125,22 +125,52 @@ export const isStreamEnvelope = (value: unknown): value is StreamEnvelope =>
   isLabeled(value) &&
   Object.values(envelopeKits).some((kit) => kit.check(value));
 
+/**
+ * Sniffs envelope labels, applying the label's handler if known,
+ * and applying the error handler if the label is not handled or
+ * if the content did not meet the envelope's type guard.
+ */
+type StreamEnvelopeHandler = (envelope: StreamEnvelope) => Promise<unknown>;
+
+/**
+ * A handler for a specific stream envelope label.
+ * The stream envelope handler will return the returned value if applied to a
+ * well-formed envelope with the corresponding label.
+ */
 type ContentHandler<Label extends LabelOf<StreamEnvelope>> = (
   content: StreamEnvelopeContent<Label>,
 ) => Promise<unknown>;
 
+/**
+ * An object with {@link EnvelopeLabel} keys mapping to an appropriate {@link ContentHandler}.
+ * If the stream envelope handler encounters a well-formed stream envelope without a defined handler,
+ * the envelope will be passed to the {@link ErrorHandler}.
+ */
+type ContentHandlerBag = { [Label in EnvelopeLabel]?: ContentHandler<Label> };
+
+/**
+ * A handler for stream envelope parsing errors.
+ * If the stream envelope handler encounters a parsing error, it will
+ *  - throw the error handler's error if one is thrown
+ *  - return the error handler's returned value otherwise
+ */
 type ErrorHandler = (reason: string) => unknown;
 
-type ContentHandlerBag = { [Label in EnvelopeLabel]?: ContentHandler<Label> };
-const defaultErrorHandler: ErrorHandler = (reason) => {
-  throw new Error(reason);
-};
+/**
+ * Makes a {@link StreamEnvelopeHandler}.
+ *
+ * @param contentHandlers - A bag of async content handlers labeled with the envelope label they handle.
+ * @param errorHandler - An optional synchronous error handler, required to throw.
+ * @returns The stream envelope handler.
+ */
 export const makeStreamEnvelopeHandler =
   (
     contentHandlers: ContentHandlerBag,
-    errorHandler: ErrorHandler = defaultErrorHandler,
-  ) =>
-  async (value: unknown): Promise<unknown> => {
+    errorHandler: ErrorHandler = (reason) => {
+      throw new Error(reason);
+    },
+  ): StreamEnvelopeHandler =>
+  async (value: unknown) => {
     if (!isStreamEnvelope(value)) {
       return errorHandler(
         `Stream envelope handler received unexpected value ${JSON.stringify(

From b261307a7744e3e3a91d3bbe7f2afabf071b4604 Mon Sep 17 00:00:00 2001
From: grypez <143971198+grypez@users.noreply.github.com>
Date: Fri, 13 Sep 2024 23:30:08 -0500
Subject: [PATCH 04/22] Streamline handler logic.

---
 packages/extension/src/envelope.ts            | 41 ++++++++++++-------
 packages/extension/src/iframe-manager.test.ts |  3 +-
 2 files changed, 28 insertions(+), 16 deletions(-)

diff --git a/packages/extension/src/envelope.ts b/packages/extension/src/envelope.ts
index 423cdb003..9102e2696 100644
--- a/packages/extension/src/envelope.ts
+++ b/packages/extension/src/envelope.ts
@@ -150,46 +150,57 @@ type ContentHandlerBag = { [Label in EnvelopeLabel]?: ContentHandler<Label> };
 
 /**
  * A handler for stream envelope parsing errors.
- * If the stream envelope handler encounters a parsing error, it will
- *  - throw the error handler's error if one is thrown
- *  - return the error handler's returned value otherwise
+ * If the {@link StreamEnvelopeHandler} encounters an error while parsing the supplied value,
+ * it will pass the reason and value to the error handler.
  */
-type ErrorHandler = (reason: string) => unknown;
+type StreamEnvelopeErrorHandler = (reason: string, value: unknown) => unknown;
 
 /**
- * Makes a {@link StreamEnvelopeHandler}.
+ * Makes a {@link StreamEnvelopeHandler} which handles an unknown value.
+ * 
+ * If the supplied value is a valid envelope with a defined {@link StreamEnvelopeHandler},
+ * the stream envelope handler will return whatever the defined handler returns.
+ * 
+ * If the stream envelope handler is passed a well-formed stream envelope without a defined handler,
+ * an explanation and the envelope will be passed to the supplied {@link StreamEnvelopeErrorHandler}.
+ * 
+ * If the stream envelope handler encounters an error while parsing the supplied value,
+ * it will pass the reason and value to the supplied {@link StreamEnvelopeErrorHandler}.
+ * 
+ * If no error handler is supplied, the default error handling behavior is to throw.
  *
- * @param contentHandlers - A bag of async content handlers labeled with the envelope label they handle.
- * @param errorHandler - An optional synchronous error handler, required to throw.
+ * @param contentHandlers - A bag of async content handlers labeled with the {@link EnvelopeLabel} they handle.
+ * @param errorHandler - An optional synchronous error handler.
  * @returns The stream envelope handler.
  */
 export const makeStreamEnvelopeHandler =
   (
     contentHandlers: ContentHandlerBag,
-    errorHandler: ErrorHandler = (reason) => {
-      throw new Error(reason);
+    errorHandler: StreamEnvelopeErrorHandler = (reason, value) => {
+      throw new Error(`${reason} ${JSON.stringify(value, null, 2)}`);
     },
   ): StreamEnvelopeHandler =>
   async (value: unknown) => {
     if (!isStreamEnvelope(value)) {
       return errorHandler(
-        `Stream envelope handler received unexpected value ${JSON.stringify(
-          value,
-        )}`,
+        'Stream envelope handler received unexpected value',
+        value,
       );
     }
     const envelope = value;
     const kit = envelopeKits[envelope.label];
-    /* v8 ignore next 5: Not known to be possible. */
+    /* v8 ignore next 6: Not known to be possible. */
     if (!kit) {
       return errorHandler(
-        `Stream envelope handler received an envelope with unknown label "${envelope.label}"`,
+        'Stream envelope handler received an envelope with unknown label',
+        envelope,
       );
     }
     const handler = contentHandlers[envelope.label];
     if (!handler) {
       return errorHandler(
-        `Stream envelope handler received an envelope with known but unexpected label "${envelope.label}"`,
+        'Stream envelope handler received an envelope with known but unexpected label',
+        envelope,
       );
     }
     return await (handler as ContentHandler<typeof envelope.label>)(
diff --git a/packages/extension/src/iframe-manager.test.ts b/packages/extension/src/iframe-manager.test.ts
index e38d8d24c..312498a8b 100644
--- a/packages/extension/src/iframe-manager.test.ts
+++ b/packages/extension/src/iframe-manager.test.ts
@@ -502,7 +502,8 @@ describe('IframeManager', () => {
       await delay(10);
 
       expect(warnSpy).toHaveBeenCalledWith(
-        'Stream envelope handler received unexpected value "foo"',
+        'Stream envelope handler received unexpected value',
+        'foo',
       );
     });
 

From 652d036d03fa8ca65591e33f7b1e8db61c3588b9 Mon Sep 17 00:00:00 2001
From: grypez <143971198+grypez@users.noreply.github.com>
Date: Sat, 14 Sep 2024 01:29:01 -0500
Subject: [PATCH 05/22] feat(extension): Leverage envelope handling for
 uninitialized capTp behavior.

---
 packages/extension/src/envelope.test.ts       | 18 +++--
 packages/extension/src/envelope.ts            | 34 +++++----
 packages/extension/src/iframe-manager.test.ts | 34 ++++++++-
 packages/extension/src/iframe-manager.ts      | 74 +++++++++++--------
 packages/extension/src/iframe.ts              |  2 +-
 5 files changed, 106 insertions(+), 56 deletions(-)

diff --git a/packages/extension/src/envelope.test.ts b/packages/extension/src/envelope.test.ts
index 987537222..a22e0a21d 100644
--- a/packages/extension/src/envelope.test.ts
+++ b/packages/extension/src/envelope.test.ts
@@ -69,17 +69,17 @@ describe('envelope', () => {
         testEnvelopeHandlers,
         testErrorHandler,
       );
-      expect(await handler(enveloper.wrap(message))).toStrictEqual(
+      expect(await handler.handle(enveloper.wrap(message))).toStrictEqual(
         enveloper.label,
       );
     });
 
     it('routes invalid envelopes to default error handler', async () => {
       const handler = makeStreamEnvelopeHandler(testEnvelopeHandlers);
-      // @ts-expect-error label is intentionally unknown
-      await expect(handler({ label: 'unknown', content: [] })).rejects.toThrow(
-        /^Stream envelope handler received unexpected value/u,
-      );
+      await expect(
+        // @ts-expect-error label is intentionally unknown
+        handler.handle({ label: 'unknown', content: [] }),
+      ).rejects.toThrow(/^Stream envelope handler received unexpected value/u);
     });
 
     it('routes invalid envelopes to supplied error handler', async () => {
@@ -87,8 +87,10 @@ describe('envelope', () => {
         testEnvelopeHandlers,
         testErrorHandler,
       );
-      // @ts-expect-error label is intentionally unknown
-      await expect(handler({ label: 'unknown', content: [] })).rejects.toThrow(
+      await expect(
+        // @ts-expect-error label is intentionally unknown
+        handler.handle({ label: 'unknown', content: [] }),
+      ).rejects.toThrow(
         /^TEST Stream envelope handler received unexpected value/u,
       );
     });
@@ -99,7 +101,7 @@ describe('envelope', () => {
         testErrorHandler,
       );
       await expect(
-        handler(capTpEnveloper.wrap(contentFixtures.capTp)),
+        handler.handle(capTpEnveloper.wrap(contentFixtures.capTp)),
       ).rejects.toThrow(
         /^TEST Stream envelope handler received an envelope with known but unexpected label/u,
       );
diff --git a/packages/extension/src/envelope.ts b/packages/extension/src/envelope.ts
index 9102e2696..b536a27d4 100644
--- a/packages/extension/src/envelope.ts
+++ b/packages/extension/src/envelope.ts
@@ -130,7 +130,11 @@ export const isStreamEnvelope = (value: unknown): value is StreamEnvelope =>
  * and applying the error handler if the label is not handled or
  * if the content did not meet the envelope's type guard.
  */
-type StreamEnvelopeHandler = (envelope: StreamEnvelope) => Promise<unknown>;
+export type StreamEnvelopeHandler = {
+  handle: (envelope: StreamEnvelope) => Promise<unknown>;
+  contentHandlers: ContentHandlerBag;
+  errorHandler: StreamEnvelopeErrorHandler;
+};
 
 /**
  * A handler for a specific stream envelope label.
@@ -157,30 +161,29 @@ type StreamEnvelopeErrorHandler = (reason: string, value: unknown) => unknown;
 
 /**
  * Makes a {@link StreamEnvelopeHandler} which handles an unknown value.
- * 
+ *
  * If the supplied value is a valid envelope with a defined {@link StreamEnvelopeHandler},
  * the stream envelope handler will return whatever the defined handler returns.
- * 
+ *
  * If the stream envelope handler is passed a well-formed stream envelope without a defined handler,
  * an explanation and the envelope will be passed to the supplied {@link StreamEnvelopeErrorHandler}.
- * 
+ *
  * If the stream envelope handler encounters an error while parsing the supplied value,
  * it will pass the reason and value to the supplied {@link StreamEnvelopeErrorHandler}.
- * 
+ *
  * If no error handler is supplied, the default error handling behavior is to throw.
  *
  * @param contentHandlers - A bag of async content handlers labeled with the {@link EnvelopeLabel} they handle.
  * @param errorHandler - An optional synchronous error handler.
  * @returns The stream envelope handler.
  */
-export const makeStreamEnvelopeHandler =
-  (
-    contentHandlers: ContentHandlerBag,
-    errorHandler: StreamEnvelopeErrorHandler = (reason, value) => {
-      throw new Error(`${reason} ${JSON.stringify(value, null, 2)}`);
-    },
-  ): StreamEnvelopeHandler =>
-  async (value: unknown) => {
+export const makeStreamEnvelopeHandler = (
+  contentHandlers: ContentHandlerBag,
+  errorHandler: StreamEnvelopeErrorHandler = (reason, value) => {
+    throw new Error(`${reason} ${JSON.stringify(value, null, 2)}`);
+  },
+): StreamEnvelopeHandler => ({
+  handle: async (value: unknown) => {
     if (!isStreamEnvelope(value)) {
       return errorHandler(
         'Stream envelope handler received unexpected value',
@@ -206,4 +209,7 @@ export const makeStreamEnvelopeHandler =
     return await (handler as ContentHandler<typeof envelope.label>)(
       kit.unwrap(envelope),
     );
-  };
+  },
+  contentHandlers,
+  errorHandler,
+});
diff --git a/packages/extension/src/iframe-manager.test.ts b/packages/extension/src/iframe-manager.test.ts
index 312498a8b..43d173687 100644
--- a/packages/extension/src/iframe-manager.test.ts
+++ b/packages/extension/src/iframe-manager.test.ts
@@ -3,7 +3,7 @@ import * as snapsUtils from '@metamask/snaps-utils';
 import { delay, makePromiseKitMock } from '@ocap/test-utils';
 import { vi, describe, it, expect } from 'vitest';
 
-import { EnvelopeLabel } from './envelope.js';
+import { capTpEnveloper, EnvelopeLabel } from './envelope.js';
 import { IframeManager } from './iframe-manager.js';
 import type { IframeMessage } from './message.js';
 import { Command } from './message.js';
@@ -181,6 +181,38 @@ describe('IframeManager', () => {
   });
 
   describe('capTp', () => {
+    it('calls console.warn when receiving a capTp envelope before initialization', async () => {
+      const id = 'foo';
+
+      vi.mocked(snapsUtils.createWindow).mockImplementationOnce(vi.fn());
+      const warnSpy = vi.spyOn(console, 'warn');
+
+      const manager = new IframeManager();
+      vi.spyOn(manager, 'sendMessage').mockImplementationOnce(vi.fn());
+
+      const { port1, port2 } = new MessageChannel();
+
+      await manager.create({ id, getPort: makeGetPort(port1) });
+
+      const envelope = capTpEnveloper.wrap({
+        epoch: 0,
+        questionID: 'q-1',
+        type: 'CTP_BOOTSTRAP',
+      });
+
+      port2.postMessage({
+        done: false,
+        value: envelope,
+      });
+
+      await delay();
+
+      expect(warnSpy).toHaveBeenCalledWith(
+        'Stream envelope handler received an envelope with known but unexpected label',
+        envelope,
+      );
+    });
+
     it('throws if called before initialization', async () => {
       const mockWindow = {};
       vi.mocked(snapsUtils.createWindow).mockResolvedValueOnce(
diff --git a/packages/extension/src/iframe-manager.ts b/packages/extension/src/iframe-manager.ts
index add3d92a1..fd77b096c 100644
--- a/packages/extension/src/iframe-manager.ts
+++ b/packages/extension/src/iframe-manager.ts
@@ -9,7 +9,7 @@ import {
   makeMessagePortStreamPair,
 } from '@ocap/streams';
 
-import type { StreamEnvelope } from './envelope.js';
+import type { StreamEnvelope, StreamEnvelopeHandler } from './envelope.js';
 import { EnvelopeLabel, makeStreamEnvelopeHandler } from './envelope.js';
 import type { CapTpPayload, IframeMessage, MessageId } from './message.js';
 import { Command } from './message.js';
@@ -27,12 +27,15 @@ const getHtmlId = (id: VatId): string => `ocap-iframe-${id}`;
 
 type PromiseCallbacks = Omit<PromiseKit<unknown>, 'promise'>;
 
+type UnresolvedMessages = Map<MessageId, PromiseCallbacks>;
+
 type GetPort = (targetWindow: Window) => Promise<MessagePort>;
 
 type VatRecord = {
   streams: StreamPair<StreamEnvelope>;
   messageCounter: () => number;
-  unresolvedMessages: Map<MessageId, PromiseCallbacks>;
+  unresolvedMessages: UnresolvedMessages;
+  streamEnvelopeHandler: StreamEnvelopeHandler;
   capTp?: ReturnType<typeof makeCapTP>;
 };
 
@@ -63,26 +66,41 @@ export class IframeManager {
   async create(
     args: { id?: VatId; getPort?: GetPort } = {},
   ): Promise<readonly [Window, VatId]> {
-    const id = args.id ?? this.#nextVatId();
+    const vatId = args.id ?? this.#nextVatId();
     const getPort = args.getPort ?? initializeMessageChannel;
 
-    const newWindow = await createWindow(IFRAME_URI, getHtmlId(id));
+    const newWindow = await createWindow(IFRAME_URI, getHtmlId(vatId));
     const port = await getPort(newWindow);
     const streams = makeMessagePortStreamPair<StreamEnvelope>(port);
-    this.#vats.set(id, {
+    const unresolvedMessages = new Map();
+    this.#vats.set(vatId, {
       streams,
       messageCounter: makeCounter(),
-      unresolvedMessages: new Map(),
+      unresolvedMessages,
+      streamEnvelopeHandler: makeStreamEnvelopeHandler(
+        {
+          command: async ({ id, message }) => {
+            const promiseCallbacks = unresolvedMessages.get(id);
+            if (promiseCallbacks === undefined) {
+              console.error(`No unresolved message with id "${id}".`);
+            } else {
+              unresolvedMessages.delete(id);
+              promiseCallbacks.resolve(message.data);
+            }
+          },
+        },
+        console.warn,
+      ),
     });
     /* v8 ignore next 4: Not known to be possible. */
-    this.#receiveMessages(id, streams.reader).catch((error) => {
-      console.error(`Unexpected read error from vat "${id}"`, error);
-      this.delete(id).catch(() => undefined);
+    this.#receiveMessages(vatId, streams.reader).catch((error) => {
+      console.error(`Unexpected read error from vat "${vatId}"`, error);
+      this.delete(vatId).catch(() => undefined);
     });
 
-    await this.sendMessage(id, { type: Command.Ping, data: null });
-    console.debug(`Created vat with id "${id}"`);
-    return [newWindow, id] as const;
+    await this.sendMessage(vatId, { type: Command.Ping, data: null });
+    console.debug(`Created vat with id "${vatId}"`);
+    return [newWindow, vatId] as const;
   }
 
   /**
@@ -161,6 +179,17 @@ export class IframeManager {
     });
 
     vat.capTp = ctp;
+    vat.streamEnvelopeHandler = makeStreamEnvelopeHandler(
+      {
+        ...vat.streamEnvelopeHandler.contentHandlers,
+        capTp: async (content) => {
+          console.log('CapTP from vat', JSON.stringify(content, null, 2));
+          ctp.dispatch(content);
+        },
+      },
+      vat.streamEnvelopeHandler.errorHandler,
+    );
+
     return this.sendMessage(id, { type: Command.CapTpInit, data: null });
   }
 
@@ -170,28 +199,9 @@ export class IframeManager {
   ): Promise<void> {
     const vat = this.#expectGetVat(vatId);
 
-    const streamEnvelopeHandler = makeStreamEnvelopeHandler(
-      {
-        command: async ({ id, message }) => {
-          const promiseCallbacks = vat.unresolvedMessages.get(id);
-          if (promiseCallbacks === undefined) {
-            console.error(`No unresolved message with id "${id}".`);
-          } else {
-            vat.unresolvedMessages.delete(id);
-            promiseCallbacks.resolve(message.data);
-          }
-        },
-        capTp: async (content) => {
-          console.log('CapTP from vat', JSON.stringify(content, null, 2));
-          vat.capTp?.dispatch(content);
-        },
-      },
-      console.warn,
-    );
-
     for await (const rawMessage of reader) {
       console.debug('Offscreen received message', rawMessage);
-      await streamEnvelopeHandler(rawMessage);
+      await vat.streamEnvelopeHandler.handle(rawMessage);
     }
   }
 
diff --git a/packages/extension/src/iframe.ts b/packages/extension/src/iframe.ts
index 8e43ae7f2..c7c1f92d5 100644
--- a/packages/extension/src/iframe.ts
+++ b/packages/extension/src/iframe.ts
@@ -32,7 +32,7 @@ async function main(): Promise<void> {
 
   for await (const rawMessage of streams.reader) {
     console.debug('iframe received message', rawMessage);
-    await streamEnvelopeHandler(rawMessage);
+    await streamEnvelopeHandler.handle(rawMessage);
   }
 
   await streams.return();

From 1485080c1450fea0b2244ca363d512415d1250d6 Mon Sep 17 00:00:00 2001
From: grypez <143971198+grypez@users.noreply.github.com>
Date: Sat, 14 Sep 2024 02:15:23 -0500
Subject: [PATCH 06/22] Standardize errorHandler param names.

---
 packages/extension/src/iframe.ts | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/extension/src/iframe.ts b/packages/extension/src/iframe.ts
index c7c1f92d5..7e02471c1 100644
--- a/packages/extension/src/iframe.ts
+++ b/packages/extension/src/iframe.ts
@@ -25,8 +25,8 @@ async function main(): Promise<void> {
       command: handleMessage,
       capTp: async (content) => capTp?.dispatch(content),
     },
-    (problem: unknown) => {
-      throw new Error(`[vat IFRAME] ${String(problem)}`);
+    (reason, value) => {
+      throw new Error(`[vat IFRAME] ${reason} ${stringifyResult(value)}`);
     },
   );
 

From dc8db550779df3a8ffe508239974f6520aa72e34 Mon Sep 17 00:00:00 2001
From: grypez <143971198+grypez@users.noreply.github.com>
Date: Sat, 14 Sep 2024 02:17:11 -0500
Subject: [PATCH 07/22] Remove EnvelopeLabel dependence.

---
 packages/extension/src/envelope.ts            |   2 +-
 packages/extension/src/iframe-manager.test.ts | 190 +++++++-----------
 packages/extension/src/iframe-manager.ts      |  11 +-
 3 files changed, 83 insertions(+), 120 deletions(-)

diff --git a/packages/extension/src/envelope.ts b/packages/extension/src/envelope.ts
index b536a27d4..278c117ca 100644
--- a/packages/extension/src/envelope.ts
+++ b/packages/extension/src/envelope.ts
@@ -141,7 +141,7 @@ export type StreamEnvelopeHandler = {
  * The stream envelope handler will return the returned value if applied to a
  * well-formed envelope with the corresponding label.
  */
-type ContentHandler<Label extends LabelOf<StreamEnvelope>> = (
+type ContentHandler<Label extends EnvelopeLabel> = (
   content: StreamEnvelopeContent<Label>,
 ) => Promise<unknown>;
 
diff --git a/packages/extension/src/iframe-manager.test.ts b/packages/extension/src/iframe-manager.test.ts
index 43d173687..f23d6bd4e 100644
--- a/packages/extension/src/iframe-manager.test.ts
+++ b/packages/extension/src/iframe-manager.test.ts
@@ -3,7 +3,7 @@ import * as snapsUtils from '@metamask/snaps-utils';
 import { delay, makePromiseKitMock } from '@ocap/test-utils';
 import { vi, describe, it, expect } from 'vitest';
 
-import { capTpEnveloper, EnvelopeLabel } from './envelope.js';
+import { capTpEnveloper, streamEnveloper } from './envelope.js';
 import { IframeManager } from './iframe-manager.js';
 import type { IframeMessage } from './message.js';
 import { Command } from './message.js';
@@ -143,16 +143,13 @@ describe('IframeManager', () => {
       const postMessage = (i: number): void => {
         port2.postMessage({
           done: false,
-          value: {
-            label: EnvelopeLabel.Command,
-            content: {
-              id: `foo-${i + 1}`,
-              message: {
-                type: Command.Evaluate,
-                data: `${i + 1}`,
-              },
+          value: streamEnveloper.wrapCommand({
+            id: `foo-${i + 1}`,
+            message: {
+              type: Command.Evaluate,
+              data: `${i + 1}`,
             },
-          },
+          }),
         });
       };
 
@@ -235,26 +232,20 @@ describe('IframeManager', () => {
       const id = 'frangooly';
 
       const capTpInit = {
-        query: {
-          label: EnvelopeLabel.Command,
-          content: {
-            id: `${id}-1`,
-            message: {
-              data: null,
-              type: 'makeCapTp',
-            },
+        query: streamEnveloper.wrapCommand({
+          id: `${id}-1`,
+          message: {
+            data: null,
+            type: Command.CapTpInit,
           },
-        },
-        response: {
-          label: EnvelopeLabel.Command,
-          content: {
-            id: `${id}-1`,
-            message: {
-              type: 'makeCapTp',
-              data: null,
-            },
+        }),
+        response: streamEnveloper.wrapCommand({
+          id: `${id}-1`,
+          message: {
+            type: Command.CapTpInit,
+            data: null,
           },
-        },
+        }),
       };
 
       vi.mocked(snapsUtils.createWindow).mockImplementationOnce(vi.fn());
@@ -309,77 +300,59 @@ describe('IframeManager', () => {
       const id = 'frangooly';
 
       const capTpInit = {
-        query: {
-          label: EnvelopeLabel.Command,
-          content: {
-            id: `${id}-1`,
-            message: {
-              data: null,
-              type: 'makeCapTp',
-            },
+        query: streamEnveloper.wrapCommand({
+          id: `${id}-1`,
+          message: {
+            data: null,
+            type: Command.CapTpInit,
           },
-        },
-        response: {
-          label: EnvelopeLabel.Command,
-          content: {
-            id: `${id}-1`,
-            message: {
-              type: 'makeCapTp',
-              data: null,
-            },
+        }),
+        response: streamEnveloper.wrapCommand({
+          id: `${id}-1`,
+          message: {
+            type: Command.CapTpInit,
+            data: null,
           },
-        },
+        }),
       };
 
       const greatFrangoolyBootstrap = {
-        query: {
-          label: 'capTp',
-          content: {
-            epoch: 0,
-            questionID: 'q-1',
-            type: 'CTP_BOOTSTRAP',
-          },
-        },
-        response: {
-          label: 'capTp',
-          content: {
-            type: 'CTP_RETURN',
-            epoch: 0,
-            answerID: 'q-1',
-            result: {
-              body: '{"@qclass":"slot","iface":"Alleged: TheGreatFrangooly","index":0}',
-              slots: ['o+1'],
-            },
+        query: streamEnveloper.wrapCapTp({
+          epoch: 0,
+          questionID: 'q-1',
+          type: 'CTP_BOOTSTRAP',
+        }),
+        response: streamEnveloper.wrapCapTp({
+          type: 'CTP_RETURN',
+          epoch: 0,
+          answerID: 'q-1',
+          result: {
+            body: '{"@qclass":"slot","iface":"Alleged: TheGreatFrangooly","index":0}',
+            slots: ['o+1'],
           },
-        },
+        }),
       };
 
       const greatFrangoolyCall = {
-        query: {
-          label: 'capTp',
-          content: {
-            type: 'CTP_CALL',
-            epoch: 0,
-            method: {
-              body: '["whatIsTheGreatFrangooly",[]]',
-              slots: [],
-            },
-            questionID: 'q-2',
-            target: 'o-1',
+        query: streamEnveloper.wrapCapTp({
+          type: 'CTP_CALL',
+          epoch: 0,
+          method: {
+            body: '["whatIsTheGreatFrangooly",[]]',
+            slots: [],
           },
-        },
-        response: {
-          label: 'capTp',
-          content: {
-            type: 'CTP_RETURN',
-            epoch: 0,
-            answerID: 'q-2',
-            result: {
-              body: '"Crowned with Chaos"',
-              slots: [],
-            },
+          questionID: 'q-2',
+          target: 'o-1',
+        }),
+        response: streamEnveloper.wrapCapTp({
+          type: 'CTP_RETURN',
+          epoch: 0,
+          answerID: 'q-2',
+          result: {
+            body: '"Crowned with Chaos"',
+            slots: [],
           },
-        },
+        }),
       };
 
       vi.mocked(snapsUtils.createWindow).mockImplementationOnce(vi.fn());
@@ -471,22 +444,19 @@ describe('IframeManager', () => {
       const message: IframeMessage = { type: Command.Evaluate, data: '2+2' };
       const response: IframeMessage = { type: Command.Evaluate, data: '4' };
 
-      // sendMessage wraps the content in a EnvelopeLabel.Command envelope
+      // sendMessage wraps the content in a Command envelope
       const messagePromise = manager.sendMessage(id, message);
-      const messageId: string | undefined =
+      const messageId: string =
         portPostMessageSpy.mock.lastCall?.[0]?.value?.content?.id;
       expect(messageId).toBeTypeOf('string');
 
       // postMessage sends the json directly, so we have to wrap it in an envelope here
       port2.postMessage({
         done: false,
-        value: {
-          label: EnvelopeLabel.Command,
-          content: {
-            id: messageId,
-            message: response,
-          },
-        },
+        value: streamEnveloper.wrapCommand({
+          id: messageId,
+          message: response,
+        }),
       });
 
       // awaiting event loop should resolve the messagePromise
@@ -496,13 +466,10 @@ describe('IframeManager', () => {
       expect(portPostMessageSpy).toHaveBeenCalledOnce();
       expect(portPostMessageSpy).toHaveBeenCalledWith({
         done: false,
-        value: {
-          label: EnvelopeLabel.Command,
-          content: {
-            id: messageId,
-            message,
-          },
-        },
+        value: streamEnveloper.wrapCommand({
+          id: messageId,
+          message,
+        }),
       });
     });
 
@@ -553,16 +520,13 @@ describe('IframeManager', () => {
 
       port2.postMessage({
         done: false,
-        value: {
-          label: EnvelopeLabel.Command,
-          content: {
-            id: 'foo',
-            message: {
-              type: Command.Evaluate,
-              data: '"bar"',
-            },
+        value: streamEnveloper.wrapCommand({
+          id: 'foo',
+          message: {
+            type: Command.Evaluate,
+            data: '"bar"',
           },
-        },
+        }),
       });
       await delay(10);
 
diff --git a/packages/extension/src/iframe-manager.ts b/packages/extension/src/iframe-manager.ts
index fd77b096c..468701f2a 100644
--- a/packages/extension/src/iframe-manager.ts
+++ b/packages/extension/src/iframe-manager.ts
@@ -10,7 +10,7 @@ import {
 } from '@ocap/streams';
 
 import type { StreamEnvelope, StreamEnvelopeHandler } from './envelope.js';
-import { EnvelopeLabel, makeStreamEnvelopeHandler } from './envelope.js';
+import { makeStreamEnvelopeHandler, streamEnveloper } from './envelope.js';
 import type { CapTpPayload, IframeMessage, MessageId } from './message.js';
 import { Command } from './message.js';
 import { makeCounter, type VatId } from './shared.js';
@@ -148,10 +148,9 @@ export class IframeManager {
     const messageId = this.#nextMessageId(id);
 
     vat.unresolvedMessages.set(messageId, { reject, resolve });
-    await vat.streams.writer.next({
-      label: EnvelopeLabel.Command,
-      content: { id: messageId, message },
-    });
+    await vat.streams.writer.next(
+      streamEnveloper.wrapCommand({ id: messageId, message }),
+    );
     return promise;
   }
 
@@ -175,7 +174,7 @@ export class IframeManager {
     // eslint-disable-next-line @typescript-eslint/no-misused-promises
     const ctp = makeCapTP(id, async (content: unknown) => {
       console.log('CapTP to vat', JSON.stringify(content, null, 2));
-      await writer.next({ label: EnvelopeLabel.CapTp, content });
+      await writer.next(streamEnveloper.wrapCapTp(content));
     });
 
     vat.capTp = ctp;

From bc67061de2705bf435eaa4adac9a221025e86bbb Mon Sep 17 00:00:00 2001
From: grypez <143971198+grypez@users.noreply.github.com>
Date: Sat, 14 Sep 2024 03:37:58 -0500
Subject: [PATCH 08/22] Cleanup docs and type names.

---
 packages/extension/src/envelope.ts | 34 ++++++++++++++++--------------
 1 file changed, 18 insertions(+), 16 deletions(-)

diff --git a/packages/extension/src/envelope.ts b/packages/extension/src/envelope.ts
index 278c117ca..7611b27c3 100644
--- a/packages/extension/src/envelope.ts
+++ b/packages/extension/src/envelope.ts
@@ -52,7 +52,7 @@ const makeEnvelopeKit = <Env extends GenericEnvelope<Env>>(
 ): EnvelopeKit<Env> => {
   const hasLabel = (value: unknown): value is LabeledWith<Env['label']> =>
     isLabeled(value, label);
-  const hasContent = (value: unknown): value is ContainerOf<ContentOf<Env>> =>
+  const hasContent = (value: unknown): value is ContainerOf<Env['content']> =>
     isObject(value) &&
     typeof value.content !== 'undefined' &&
     isContent(value.content);
@@ -61,7 +61,7 @@ const makeEnvelopeKit = <Env extends GenericEnvelope<Env>>(
     sniff: hasLabel,
     check: (value: unknown): value is Env =>
       hasLabel(value) && hasContent(value),
-    wrap: (content: ContentOf<Env>) =>
+    wrap: (content: Env['content']) =>
       ({
         label,
         content,
@@ -108,7 +108,7 @@ export const streamEnveloper = {
 
 export type StreamEnvelope = CommandEnvelope | CapTpEnvelope;
 
-type StreamEnvelopeContent<Label extends LabelOf<StreamEnvelope>> =
+type StreamEnvelopeContent<Label extends StreamEnvelope['label']> =
   Label extends EnvelopeLabel.Command
     ? CommandEnvelope['content']
     : Label extends EnvelopeLabel.CapTp
@@ -126,31 +126,33 @@ export const isStreamEnvelope = (value: unknown): value is StreamEnvelope =>
   Object.values(envelopeKits).some((kit) => kit.check(value));
 
 /**
- * Sniffs envelope labels, applying the label's handler if known,
- * and applying the error handler if the label is not handled or
- * if the content did not meet the envelope's type guard.
+ * A handler for automatically unwrapping stream envelopes and handling their content.
+ *
+ * @property handle - Sniffs an unknown value for envelope labels, applying the label's handler if known, and applying the error handler if the label is not handled or if the content did not pass the envelope's type guard.
+ * @property contentHandlers - The bag of content candlers passed to the maker.
+ * @property errorHandler - The error handler passed to the maker.
  */
 export type StreamEnvelopeHandler = {
   handle: (envelope: StreamEnvelope) => Promise<unknown>;
-  contentHandlers: ContentHandlerBag;
+  contentHandlers: StreamEnvelopeContentHandlerBag;
   errorHandler: StreamEnvelopeErrorHandler;
 };
 
 /**
  * A handler for a specific stream envelope label.
- * The stream envelope handler will return the returned value if applied to a
- * well-formed envelope with the corresponding label.
  */
-type ContentHandler<Label extends EnvelopeLabel> = (
+type StreamEnvelopeContentHandler<Label extends EnvelopeLabel> = (
   content: StreamEnvelopeContent<Label>,
 ) => Promise<unknown>;
 
 /**
- * An object with {@link EnvelopeLabel} keys mapping to an appropriate {@link ContentHandler}.
+ * An object with {@link EnvelopeLabel} keys mapping to an appropriate {@link StreamEnvelopeContentHandler}.
  * If the stream envelope handler encounters a well-formed stream envelope without a defined handler,
  * the envelope will be passed to the {@link ErrorHandler}.
  */
-type ContentHandlerBag = { [Label in EnvelopeLabel]?: ContentHandler<Label> };
+type StreamEnvelopeContentHandlerBag = {
+  [Label in EnvelopeLabel]?: StreamEnvelopeContentHandler<Label>;
+};
 
 /**
  * A handler for stream envelope parsing errors.
@@ -178,7 +180,7 @@ type StreamEnvelopeErrorHandler = (reason: string, value: unknown) => unknown;
  * @returns The stream envelope handler.
  */
 export const makeStreamEnvelopeHandler = (
-  contentHandlers: ContentHandlerBag,
+  contentHandlers: StreamEnvelopeContentHandlerBag,
   errorHandler: StreamEnvelopeErrorHandler = (reason, value) => {
     throw new Error(`${reason} ${JSON.stringify(value, null, 2)}`);
   },
@@ -206,9 +208,9 @@ export const makeStreamEnvelopeHandler = (
         envelope,
       );
     }
-    return await (handler as ContentHandler<typeof envelope.label>)(
-      kit.unwrap(envelope),
-    );
+    return await (
+      handler as StreamEnvelopeContentHandler<typeof envelope.label>
+    )(kit.unwrap(envelope));
   },
   contentHandlers,
   errorHandler,

From 400548817e5af4a3fc097f1552d4ea24e653703e Mon Sep 17 00:00:00 2001
From: grypez <143971198+grypez@users.noreply.github.com>
Date: Sat, 14 Sep 2024 03:59:56 -0500
Subject: [PATCH 09/22] Make envelope kit test case name more descriptive.

---
 packages/extension/src/envelope.test.ts | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/packages/extension/src/envelope.test.ts b/packages/extension/src/envelope.test.ts
index a22e0a21d..19c288564 100644
--- a/packages/extension/src/envelope.test.ts
+++ b/packages/extension/src/envelope.test.ts
@@ -113,11 +113,12 @@ describe('envelope', () => {
       enveloper           | envelope
       ${commandEnveloper} | ${contentFixtures.capTp}
       ${capTpEnveloper}   | ${contentFixtures.command}
+      ${commandEnveloper} | ${capTpEnveloper.wrap(contentFixtures.command)}
     `(
-      'throws when unwrapping a malformed envelope',
+      'throws when $enveloper.label enveloper attempts to unwrap a malformed envelope $envelope',
       ({ enveloper, envelope }) => {
         expect(() => enveloper.unwrap(envelope)).toThrow(
-          /Expected envelope labelled/u,
+          /^Expected envelope labelled/u,
         );
       },
     );

From 8768114c96874f42c37b39e3b0809f372bd1962e Mon Sep 17 00:00:00 2001
From: grypez <143971198+grypez@users.noreply.github.com>
Date: Sat, 14 Sep 2024 11:58:01 -0400
Subject: [PATCH 10/22] Promote default errorHandler to constant.

Co-authored-by: Saleh Abdel Motaal <saleh@smotaal.io>
---
 packages/extension/src/envelope.ts | 17 ++++++++++++++---
 1 file changed, 14 insertions(+), 3 deletions(-)

diff --git a/packages/extension/src/envelope.ts b/packages/extension/src/envelope.ts
index 7611b27c3..dec1c7410 100644
--- a/packages/extension/src/envelope.ts
+++ b/packages/extension/src/envelope.ts
@@ -161,6 +161,19 @@ type StreamEnvelopeContentHandlerBag = {
  */
 type StreamEnvelopeErrorHandler = (reason: string, value: unknown) => unknown;
 
+/**
+ * The default handler for stream envelope parsing errors.
+ *
+ * @param reason - The reason for the error.
+ * @param value - The value that caused the error.
+ */
+const defaultStreamEnvelopeErrorHandler: StreamEnvelopeErrorHandler = (
+  reason,
+  value,
+) => {
+  throw new Error(`${reason} ${JSON.stringify(value, null, 2)}`);
+};
+
 /**
  * Makes a {@link StreamEnvelopeHandler} which handles an unknown value.
  *
@@ -181,9 +194,7 @@ type StreamEnvelopeErrorHandler = (reason: string, value: unknown) => unknown;
  */
 export const makeStreamEnvelopeHandler = (
   contentHandlers: StreamEnvelopeContentHandlerBag,
-  errorHandler: StreamEnvelopeErrorHandler = (reason, value) => {
-    throw new Error(`${reason} ${JSON.stringify(value, null, 2)}`);
-  },
+  errorHandler: StreamEnvelopeErrorHandler = defaultStreamEnvelopeErrorHandler,
 ): StreamEnvelopeHandler => ({
   handle: async (value: unknown) => {
     if (!isStreamEnvelope(value)) {

From 380aef1bb57249840b4d0bb696d60edaf83a74ab Mon Sep 17 00:00:00 2001
From: grypez <143971198+grypez@users.noreply.github.com>
Date: Sat, 14 Sep 2024 12:15:58 -0500
Subject: [PATCH 11/22] Rename types *Form -> *Like.

---
 packages/extension/src/envelope.ts | 52 +++++++++++++++++-------------
 packages/extension/src/message.ts  | 10 +++---
 2 files changed, 35 insertions(+), 27 deletions(-)

diff --git a/packages/extension/src/envelope.ts b/packages/extension/src/envelope.ts
index dec1c7410..24d320553 100644
--- a/packages/extension/src/envelope.ts
+++ b/packages/extension/src/envelope.ts
@@ -8,12 +8,12 @@ export enum EnvelopeLabel {
   CapTp = 'capTp',
 }
 
-type EnvelopeForm<Label extends EnvelopeLabel, Content> = {
+type EnvelopeLike<Label extends EnvelopeLabel, Content> = {
   label: Label;
   content: Content;
 };
 
-type LabelOf<Env> = Env extends EnvelopeForm<infer Label, unknown>
+type LabelOf<Envelope> = Envelope extends EnvelopeLike<infer Label, unknown>
   ? Label
   : never;
 type LabeledWith<Label extends EnvelopeLabel> = {
@@ -28,7 +28,10 @@ const isLabeled = <Label extends EnvelopeLabel>(
   typeof value.label !== 'undefined' &&
   (label === undefined || value.label === label);
 
-type ContentOf<Env> = Env extends EnvelopeForm<EnvelopeLabel, infer Content>
+type ContentOf<Envelope> = Envelope extends EnvelopeLike<
+  EnvelopeLabel,
+  infer Content
+>
   ? Content
   : never;
 type ContainerOf<Content> = {
@@ -36,37 +39,42 @@ type ContainerOf<Content> = {
   [key: string]: unknown;
 };
 
-type GenericEnvelope<Env> = EnvelopeForm<LabelOf<Env>, ContentOf<Env>>;
+type GenericEnvelope<Envelope> = EnvelopeLike<
+  LabelOf<Envelope>,
+  ContentOf<Envelope>
+>;
 
-type EnvelopeKit<Env extends GenericEnvelope<Env>> = {
-  label: Env['label'];
-  sniff: (value: unknown) => value is LabeledWith<Env['label']>;
-  check: (value: unknown) => value is Env;
-  wrap: (content: Env['content']) => Env;
-  unwrap: (envelope: Env) => Env['content'];
+type EnvelopeKit<Envelope extends GenericEnvelope<Envelope>> = {
+  label: Envelope['label'];
+  sniff: (value: unknown) => value is LabeledWith<Envelope['label']>;
+  check: (value: unknown) => value is Envelope;
+  wrap: (content: Envelope['content']) => Envelope;
+  unwrap: (envelope: Envelope) => Envelope['content'];
 };
 
-const makeEnvelopeKit = <Env extends GenericEnvelope<Env>>(
-  label: Env['label'],
-  isContent: (value: unknown) => value is Env['content'],
-): EnvelopeKit<Env> => {
-  const hasLabel = (value: unknown): value is LabeledWith<Env['label']> =>
+const makeEnvelopeKit = <Envelope extends GenericEnvelope<Envelope>>(
+  label: Envelope['label'],
+  isContent: (value: unknown) => value is Envelope['content'],
+): EnvelopeKit<Envelope> => {
+  const hasLabel = (value: unknown): value is LabeledWith<Envelope['label']> =>
     isLabeled(value, label);
-  const hasContent = (value: unknown): value is ContainerOf<Env['content']> =>
+  const hasContent = (
+    value: unknown,
+  ): value is ContainerOf<Envelope['content']> =>
     isObject(value) &&
     typeof value.content !== 'undefined' &&
     isContent(value.content);
   return {
     label,
     sniff: hasLabel,
-    check: (value: unknown): value is Env =>
+    check: (value: unknown): value is Envelope =>
       hasLabel(value) && hasContent(value),
-    wrap: (content: Env['content']) =>
+    wrap: (content: Envelope['content']) =>
       ({
         label,
         content,
-      } as Env),
-    unwrap: (envelope: Env): Env['content'] => {
+      } as Envelope),
+    unwrap: (envelope: Envelope): Envelope['content'] => {
       if (!hasLabel(envelope)) {
         throw new Error(
           // @ts-expect-error The type of `envelope` is `never`, but this could happen at runtime.
@@ -79,11 +87,11 @@ const makeEnvelopeKit = <Env extends GenericEnvelope<Env>>(
   };
 };
 
-type CommandEnvelope = EnvelopeForm<
+type CommandEnvelope = EnvelopeLike<
   EnvelopeLabel.Command,
   WrappedIframeMessage
 >;
-type CapTpEnvelope = EnvelopeForm<EnvelopeLabel.CapTp, CapTpMessage>;
+type CapTpEnvelope = EnvelopeLike<EnvelopeLabel.CapTp, CapTpMessage>;
 
 export const commandEnveloper = makeEnvelopeKit<CommandEnvelope>(
   EnvelopeLabel.Command,
diff --git a/packages/extension/src/message.ts b/packages/extension/src/message.ts
index 16682a62c..49b6f8bd5 100644
--- a/packages/extension/src/message.ts
+++ b/packages/extension/src/message.ts
@@ -14,7 +14,7 @@ export enum ExtensionMessageTarget {
   Offscreen = 'offscreen',
 }
 
-type CommandForm<
+type CommandLike<
   CommandType extends Command,
   Data extends DataObject,
   TargetType extends ExtensionMessageTarget,
@@ -37,10 +37,10 @@ export type CapTpPayload = {
 };
 
 type CommandMessage<TargetType extends ExtensionMessageTarget> =
-  | CommandForm<Command.Ping, null | 'pong', TargetType>
-  | CommandForm<Command.Evaluate, string, TargetType>
-  | CommandForm<Command.CapTpInit, null, TargetType>
-  | CommandForm<Command.CapTpCall, CapTpPayload, TargetType>;
+  | CommandLike<Command.Ping, null | 'pong', TargetType>
+  | CommandLike<Command.Evaluate, string, TargetType>
+  | CommandLike<Command.CapTpInit, null, TargetType>
+  | CommandLike<Command.CapTpCall, CapTpPayload, TargetType>;
 
 export type ExtensionMessage = CommandMessage<ExtensionMessageTarget>;
 export type IframeMessage = CommandMessage<never>;

From e17fc6e27ae1b6bce631ce7676dd4a9c136dac94 Mon Sep 17 00:00:00 2001
From: grypez <143971198+grypez@users.noreply.github.com>
Date: Sat, 14 Sep 2024 19:06:29 -0500
Subject: [PATCH 12/22] Narrow CapTpMessage type.

---
 packages/extension/src/envelope.test.ts  | 14 +++++++++++---
 packages/extension/src/iframe-manager.ts |  9 +++++++--
 packages/extension/src/iframe.ts         | 10 ++++++++--
 packages/extension/src/message.ts        | 13 +++++++++++--
 4 files changed, 37 insertions(+), 9 deletions(-)

diff --git a/packages/extension/src/envelope.test.ts b/packages/extension/src/envelope.test.ts
index 19c288564..a1c0605d0 100644
--- a/packages/extension/src/envelope.test.ts
+++ b/packages/extension/src/envelope.test.ts
@@ -7,11 +7,19 @@ import {
   isStreamEnvelope,
   makeStreamEnvelopeHandler,
 } from './envelope.js';
+import type { CapTpMessage, WrappedIframeMessage } from './message.js';
 import { Command } from './message.js';
 
 const contentFixtures = {
-  command: { id: '1', message: { type: Command.Evaluate, data: '1 + 1' } },
-  capTp: { id: '4', message: { type: 'CTP_CALL', epoch: 0 } },
+  command: {
+    id: '1',
+    message: { type: Command.Evaluate, data: '1 + 1' },
+  } as WrappedIframeMessage,
+  capTp: {
+    type: 'CTP_CALL',
+    epoch: 0,
+    unreliableKey: Symbol('unreliableValue'),
+  } as CapTpMessage,
 };
 
 describe('envelope', () => {
@@ -113,7 +121,7 @@ describe('envelope', () => {
       enveloper           | envelope
       ${commandEnveloper} | ${contentFixtures.capTp}
       ${capTpEnveloper}   | ${contentFixtures.command}
-      ${commandEnveloper} | ${capTpEnveloper.wrap(contentFixtures.command)}
+      ${commandEnveloper} | ${capTpEnveloper.wrap(contentFixtures.command as unknown as CapTpMessage)}
     `(
       'throws when $enveloper.label enveloper attempts to unwrap a malformed envelope $envelope',
       ({ enveloper, envelope }) => {
diff --git a/packages/extension/src/iframe-manager.ts b/packages/extension/src/iframe-manager.ts
index 468701f2a..3970a2706 100644
--- a/packages/extension/src/iframe-manager.ts
+++ b/packages/extension/src/iframe-manager.ts
@@ -11,7 +11,12 @@ import {
 
 import type { StreamEnvelope, StreamEnvelopeHandler } from './envelope.js';
 import { makeStreamEnvelopeHandler, streamEnveloper } from './envelope.js';
-import type { CapTpPayload, IframeMessage, MessageId } from './message.js';
+import type {
+  CapTpMessage,
+  CapTpPayload,
+  IframeMessage,
+  MessageId,
+} from './message.js';
 import { Command } from './message.js';
 import { makeCounter, type VatId } from './shared.js';
 
@@ -174,7 +179,7 @@ export class IframeManager {
     // eslint-disable-next-line @typescript-eslint/no-misused-promises
     const ctp = makeCapTP(id, async (content: unknown) => {
       console.log('CapTP to vat', JSON.stringify(content, null, 2));
-      await writer.next(streamEnveloper.wrapCapTp(content));
+      await writer.next(streamEnveloper.wrapCapTp(content as CapTpMessage));
     });
 
     vat.capTp = ctp;
diff --git a/packages/extension/src/iframe.ts b/packages/extension/src/iframe.ts
index 7e02471c1..5e58ab77a 100644
--- a/packages/extension/src/iframe.ts
+++ b/packages/extension/src/iframe.ts
@@ -5,7 +5,11 @@ import { receiveMessagePort, makeMessagePortStreamPair } from '@ocap/streams';
 
 import type { StreamEnvelope } from './envelope.js';
 import { streamEnveloper, makeStreamEnvelopeHandler } from './envelope.js';
-import type { IframeMessage, WrappedIframeMessage } from './message.js';
+import type {
+  CapTpMessage,
+  IframeMessage,
+  WrappedIframeMessage,
+} from './message.js';
 import { Command } from './message.js';
 
 const defaultCompartment = new Compartment({ URL });
@@ -76,7 +80,9 @@ async function main(): Promise<void> {
         capTp = makeCapTP(
           'iframe',
           async (content: unknown) =>
-            streams.writer.next(streamEnveloper.wrapCapTp(content)),
+            streams.writer.next(
+              streamEnveloper.wrapCapTp(content as CapTpMessage),
+            ),
           bootstrap,
         );
         await replyToMessage(id, { type: Command.CapTpInit, data: null });
diff --git a/packages/extension/src/message.ts b/packages/extension/src/message.ts
index 49b6f8bd5..3ec1eaeaf 100644
--- a/packages/extension/src/message.ts
+++ b/packages/extension/src/message.ts
@@ -59,5 +59,14 @@ export const isWrappedIframeMessage = (
   typeof value.message.type === 'string' &&
   (typeof value.message.data === 'string' || value.message.data === null);
 
-export type CapTpMessage = unknown;
-export const isCapTpMessage = (value: unknown): value is CapTpMessage => true;
+export type CapTpMessage<Type extends `CTP_${string}` = `CTP_${string}`> = {
+  type: Type;
+  epoch: number;
+  [key: string]: unknown;
+};
+
+export const isCapTpMessage = (value: unknown): value is CapTpMessage =>
+  isObject(value) &&
+  typeof value.type === 'string' &&
+  value.type.startsWith('CTP_') &&
+  typeof value.epoch === 'number';

From 92ac865fa49f60db3b63844e24612608af57af1f Mon Sep 17 00:00:00 2001
From: grypez <143971198+grypez@users.noreply.github.com>
Date: Sat, 14 Sep 2024 19:21:32 -0500
Subject: [PATCH 13/22] Narrow envelope interface.

---
 packages/extension/src/envelope.ts            | 15 ++---------
 packages/extension/src/iframe-manager.test.ts | 26 +++++++++----------
 packages/extension/src/iframe-manager.ts      | 12 +++++----
 packages/extension/src/iframe.ts              | 12 +++++----
 4 files changed, 29 insertions(+), 36 deletions(-)

diff --git a/packages/extension/src/envelope.ts b/packages/extension/src/envelope.ts
index 24d320553..e14883a40 100644
--- a/packages/extension/src/envelope.ts
+++ b/packages/extension/src/envelope.ts
@@ -46,7 +46,6 @@ type GenericEnvelope<Envelope> = EnvelopeLike<
 
 type EnvelopeKit<Envelope extends GenericEnvelope<Envelope>> = {
   label: Envelope['label'];
-  sniff: (value: unknown) => value is LabeledWith<Envelope['label']>;
   check: (value: unknown) => value is Envelope;
   wrap: (content: Envelope['content']) => Envelope;
   unwrap: (envelope: Envelope) => Envelope['content'];
@@ -66,7 +65,6 @@ const makeEnvelopeKit = <Envelope extends GenericEnvelope<Envelope>>(
     isContent(value.content);
   return {
     label,
-    sniff: hasLabel,
     check: (value: unknown): value is Envelope =>
       hasLabel(value) && hasContent(value),
     wrap: (content: Envelope['content']) =>
@@ -102,17 +100,8 @@ export const capTpEnveloper = makeEnvelopeKit<CapTpEnvelope>(
   isCapTpMessage,
 );
 
-export const streamEnveloper = {
-  sniffCommand: commandEnveloper.sniff,
-  checkCommand: commandEnveloper.check,
-  wrapCommand: commandEnveloper.wrap,
-  unwrapCommand: commandEnveloper.unwrap,
-
-  sniffCapTp: capTpEnveloper.sniff,
-  checkCapTp: capTpEnveloper.check,
-  wrapCapTp: capTpEnveloper.wrap,
-  unwrapCapTp: capTpEnveloper.unwrap,
-};
+export const wrapCommand = commandEnveloper.wrap;
+export const wrapCapTp = capTpEnveloper.wrap;
 
 export type StreamEnvelope = CommandEnvelope | CapTpEnvelope;
 
diff --git a/packages/extension/src/iframe-manager.test.ts b/packages/extension/src/iframe-manager.test.ts
index f23d6bd4e..221a9c029 100644
--- a/packages/extension/src/iframe-manager.test.ts
+++ b/packages/extension/src/iframe-manager.test.ts
@@ -3,7 +3,7 @@ import * as snapsUtils from '@metamask/snaps-utils';
 import { delay, makePromiseKitMock } from '@ocap/test-utils';
 import { vi, describe, it, expect } from 'vitest';
 
-import { capTpEnveloper, streamEnveloper } from './envelope.js';
+import { capTpEnveloper, wrapCommand, wrapCapTp } from './envelope.js';
 import { IframeManager } from './iframe-manager.js';
 import type { IframeMessage } from './message.js';
 import { Command } from './message.js';
@@ -143,7 +143,7 @@ describe('IframeManager', () => {
       const postMessage = (i: number): void => {
         port2.postMessage({
           done: false,
-          value: streamEnveloper.wrapCommand({
+          value: wrapCommand({
             id: `foo-${i + 1}`,
             message: {
               type: Command.Evaluate,
@@ -232,14 +232,14 @@ describe('IframeManager', () => {
       const id = 'frangooly';
 
       const capTpInit = {
-        query: streamEnveloper.wrapCommand({
+        query: wrapCommand({
           id: `${id}-1`,
           message: {
             data: null,
             type: Command.CapTpInit,
           },
         }),
-        response: streamEnveloper.wrapCommand({
+        response: wrapCommand({
           id: `${id}-1`,
           message: {
             type: Command.CapTpInit,
@@ -300,14 +300,14 @@ describe('IframeManager', () => {
       const id = 'frangooly';
 
       const capTpInit = {
-        query: streamEnveloper.wrapCommand({
+        query: wrapCommand({
           id: `${id}-1`,
           message: {
             data: null,
             type: Command.CapTpInit,
           },
         }),
-        response: streamEnveloper.wrapCommand({
+        response: wrapCommand({
           id: `${id}-1`,
           message: {
             type: Command.CapTpInit,
@@ -317,12 +317,12 @@ describe('IframeManager', () => {
       };
 
       const greatFrangoolyBootstrap = {
-        query: streamEnveloper.wrapCapTp({
+        query: wrapCapTp({
           epoch: 0,
           questionID: 'q-1',
           type: 'CTP_BOOTSTRAP',
         }),
-        response: streamEnveloper.wrapCapTp({
+        response: wrapCapTp({
           type: 'CTP_RETURN',
           epoch: 0,
           answerID: 'q-1',
@@ -334,7 +334,7 @@ describe('IframeManager', () => {
       };
 
       const greatFrangoolyCall = {
-        query: streamEnveloper.wrapCapTp({
+        query: wrapCapTp({
           type: 'CTP_CALL',
           epoch: 0,
           method: {
@@ -344,7 +344,7 @@ describe('IframeManager', () => {
           questionID: 'q-2',
           target: 'o-1',
         }),
-        response: streamEnveloper.wrapCapTp({
+        response: wrapCapTp({
           type: 'CTP_RETURN',
           epoch: 0,
           answerID: 'q-2',
@@ -453,7 +453,7 @@ describe('IframeManager', () => {
       // postMessage sends the json directly, so we have to wrap it in an envelope here
       port2.postMessage({
         done: false,
-        value: streamEnveloper.wrapCommand({
+        value: wrapCommand({
           id: messageId,
           message: response,
         }),
@@ -466,7 +466,7 @@ describe('IframeManager', () => {
       expect(portPostMessageSpy).toHaveBeenCalledOnce();
       expect(portPostMessageSpy).toHaveBeenCalledWith({
         done: false,
-        value: streamEnveloper.wrapCommand({
+        value: wrapCommand({
           id: messageId,
           message,
         }),
@@ -520,7 +520,7 @@ describe('IframeManager', () => {
 
       port2.postMessage({
         done: false,
-        value: streamEnveloper.wrapCommand({
+        value: wrapCommand({
           id: 'foo',
           message: {
             type: Command.Evaluate,
diff --git a/packages/extension/src/iframe-manager.ts b/packages/extension/src/iframe-manager.ts
index 3970a2706..bfcd9e6ef 100644
--- a/packages/extension/src/iframe-manager.ts
+++ b/packages/extension/src/iframe-manager.ts
@@ -10,7 +10,11 @@ import {
 } from '@ocap/streams';
 
 import type { StreamEnvelope, StreamEnvelopeHandler } from './envelope.js';
-import { makeStreamEnvelopeHandler, streamEnveloper } from './envelope.js';
+import {
+  makeStreamEnvelopeHandler,
+  wrapCapTp,
+  wrapCommand,
+} from './envelope.js';
 import type {
   CapTpMessage,
   CapTpPayload,
@@ -153,9 +157,7 @@ export class IframeManager {
     const messageId = this.#nextMessageId(id);
 
     vat.unresolvedMessages.set(messageId, { reject, resolve });
-    await vat.streams.writer.next(
-      streamEnveloper.wrapCommand({ id: messageId, message }),
-    );
+    await vat.streams.writer.next(wrapCommand({ id: messageId, message }));
     return promise;
   }
 
@@ -179,7 +181,7 @@ export class IframeManager {
     // eslint-disable-next-line @typescript-eslint/no-misused-promises
     const ctp = makeCapTP(id, async (content: unknown) => {
       console.log('CapTP to vat', JSON.stringify(content, null, 2));
-      await writer.next(streamEnveloper.wrapCapTp(content as CapTpMessage));
+      await writer.next(wrapCapTp(content as CapTpMessage));
     });
 
     vat.capTp = ctp;
diff --git a/packages/extension/src/iframe.ts b/packages/extension/src/iframe.ts
index 5e58ab77a..ed6ffc808 100644
--- a/packages/extension/src/iframe.ts
+++ b/packages/extension/src/iframe.ts
@@ -4,7 +4,11 @@ import { M } from '@endo/patterns';
 import { receiveMessagePort, makeMessagePortStreamPair } from '@ocap/streams';
 
 import type { StreamEnvelope } from './envelope.js';
-import { streamEnveloper, makeStreamEnvelopeHandler } from './envelope.js';
+import {
+  wrapCapTp,
+  wrapCommand,
+  makeStreamEnvelopeHandler,
+} from './envelope.js';
 import type {
   CapTpMessage,
   IframeMessage,
@@ -80,9 +84,7 @@ async function main(): Promise<void> {
         capTp = makeCapTP(
           'iframe',
           async (content: unknown) =>
-            streams.writer.next(
-              streamEnveloper.wrapCapTp(content as CapTpMessage),
-            ),
+            streams.writer.next(wrapCapTp(content as CapTpMessage)),
           bootstrap,
         );
         await replyToMessage(id, { type: Command.CapTpInit, data: null });
@@ -109,7 +111,7 @@ async function main(): Promise<void> {
     id: string,
     message: IframeMessage,
   ): Promise<void> {
-    await streams.writer.next(streamEnveloper.wrapCommand({ id, message }));
+    await streams.writer.next(wrapCommand({ id, message }));
   }
 
   /**

From 18a56abb0161d6405016a547118cf118f98dceb4 Mon Sep 17 00:00:00 2001
From: grypez <143971198+grypez@users.noreply.github.com>
Date: Sun, 15 Sep 2024 13:24:31 -0500
Subject: [PATCH 14/22] feat(streams): Add envelope kit.

---
 .../documents/make-stream-envelope-kit.md     |  83 +++++
 packages/streams/src/envelope-kit.test.ts     | 338 ++++++++++++++++++
 packages/streams/src/envelope-kit.ts          | 175 +++++++++
 packages/streams/src/index.ts                 |   1 +
 packages/streams/typedoc.json                 |   3 +-
 5 files changed, 599 insertions(+), 1 deletion(-)
 create mode 100644 packages/streams/documents/make-stream-envelope-kit.md
 create mode 100644 packages/streams/src/envelope-kit.test.ts
 create mode 100644 packages/streams/src/envelope-kit.ts

diff --git a/packages/streams/documents/make-stream-envelope-kit.md b/packages/streams/documents/make-stream-envelope-kit.md
new file mode 100644
index 000000000..63561b828
--- /dev/null
+++ b/packages/streams/documents/make-stream-envelope-kit.md
@@ -0,0 +1,83 @@
+---
+title: Making a StreamEnvelopeKit
+group: Documents
+category: Guides
+---
+
+# makeStreamEnvelopeKit
+
+### Template parameters must be explicitly declared
+
+To ensure proper typescript inference behavior, it is necessary to explicitly declare the template parameters when calling `makeStreamEnvelopeKit`. See the [example](#example) below for the recommended declaration pattern.
+
+### Passing an enum as a template parameter
+
+Due to a [typescript limitation](https://github.com/microsoft/TypeScript/issues/30611) it is not possible to specify an enum as the expected type of a template parameter. Therefore `makeStreamEnvelopeKit` will accept template parameters which are not within its intended bounds; improperly specified template parameters will result in improper typescript inference behavior. See the [example](#example) below for the recommended declaration pattern.
+
+### Example declaration
+
+```ts
+import { makeStreamEnvelopeKit } from '@ocap/streams';
+
+// Import or declare the content types.
+import type { FooContent } from './foo.js';
+/*
+type FooContent = {
+  a: number;
+  b: string;
+};
+*/
+type BarContent = {
+  c: boolean;
+};
+
+// Specify envelope labels in an enum.
+enum EnvelopeLabel {
+  Foo = 'foo',
+  Bar = 'bar',
+}
+
+// Create a string[] from the EnvelopeLabel enum.
+const labels = Object.values(EnvelopeLabel);
+
+// Make the StreamEnvelopeKit.
+export const myStreamEnvelopeKit = makeStreamEnvelopeKit<
+  // Pass the EnvelopeLabel enum as `typeof labels`.
+  typeof labels,
+  // Specify the content type for each content label.
+  {
+    // foo matches the value 'foo' of EnvelopeLabel.Foo
+    foo: FooContent;
+    bar: BarContent;
+  }
+>({
+  // Specify the type guards for each envelope label.
+  foo: (value: unknown): value is FooContent =>
+    isObject(value) &&
+    typeof value.a === 'number' &&
+    typeof value.b === 'string',
+
+  // bar matches the value 'bar' of EnvelopeLabel.Bar
+  bar: (value: unknown): value is BarContent =>
+    isObject(value) && typeof value.c === 'boolean',
+});
+```
+
+### Example use
+
+```ts
+// Destructure your new envelope kit.
+const { streamEnveloper, isStreamEnvelope } = myStreamEnvelopeKit;
+
+// Wrap some FooContent.
+const envelope = streamEnveloper.foo.wrap({
+  a: 1,
+  b: 'one',
+});
+
+// Protect your assumptions with the supplied type guard.
+if (isStreamEnvelope(envelope)) {
+  // ~~~ Unwrap your envelope right away! ~~~
+  const content = streamEnveloper[envelope.label].unwrap(envelope);
+}
+```
diff --git a/packages/streams/src/envelope-kit.test.ts b/packages/streams/src/envelope-kit.test.ts
new file mode 100644
index 000000000..0e0110f02
--- /dev/null
+++ b/packages/streams/src/envelope-kit.test.ts
@@ -0,0 +1,338 @@
+import { isObject } from '@metamask/utils';
+import { describe, expect, it } from 'vitest';
+
+import { makeStreamEnvelopeKit } from './envelope-kit.js';
+
+describe('makeStreamEnvelopeKit', () => {
+  type Foo = {
+    a: number;
+    b: string;
+  };
+  type Bar = {
+    c: boolean;
+  };
+  type ContentMap = {
+    foo: Foo;
+    bar: Bar;
+  };
+  enum Label {
+    Foo = 'foo',
+    Bar = 'bar',
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  const labels = Object.values(Label);
+
+  const { streamEnveloper, isStreamEnvelope } = makeStreamEnvelopeKit<
+    typeof labels,
+    ContentMap
+  >({
+    foo: (value: unknown): value is Foo =>
+      isObject(value) &&
+      typeof value.a === 'number' &&
+      typeof value.b === 'string',
+    bar: (value: unknown): value is Bar =>
+      isObject(value) && typeof value.c === 'boolean',
+  });
+
+  const fooContent: Foo = { a: 0, b: 's' };
+  const barContent: Bar = { c: false };
+
+  const inferNumber = (value: number): number => value;
+  const inferString = (value: string): string => value;
+  const inferBoolean = (value: boolean): boolean => value;
+
+  /* eslint-disable @typescript-eslint/no-unused-expressions */
+  // eslint-disable-next-line vitest/expect-expect
+  it('causes a typescript error when supplying typeguard keys not matching the label type', () => {
+    // @ts-expect-error the bar key is missing
+    makeStreamEnvelopeKit<typeof labels, ContentMap>({
+      foo: (value: unknown): value is Foo => true,
+    });
+    makeStreamEnvelopeKit<typeof labels, ContentMap>({
+      foo: (value: unknown): value is Foo => true,
+      bar: (value: unknown): value is Bar => true,
+      // @ts-expect-error the qux key is not included in labels
+      qux: (value: unknown): value is 'qux' => false,
+    });
+  });
+  /* eslint-enable @typescript-eslint/no-unused-expressions */
+
+  describe('enveloper', () => {
+    describe('check', () => {
+      it.each`
+        enveloper              | envelope
+        ${streamEnveloper.foo} | ${{ label: 'foo', content: fooContent }}
+        ${streamEnveloper.bar} | ${{ label: 'bar', content: barContent }}
+        ${streamEnveloper.bar} | ${{ label: 'bar', content: barContent, extra: 'value' }}
+      `(
+        'returns true for valid envelopes: $envelope',
+        ({ enveloper, envelope }) => {
+          expect(enveloper.check(envelope)).toBe(true);
+        },
+      );
+
+      it.each`
+        enveloper              | content
+        ${streamEnveloper.foo} | ${fooContent}
+        ${streamEnveloper.bar} | ${barContent}
+      `(
+        'returns true for content wrapped by its enveloper: $content',
+        ({ enveloper, content }) => {
+          expect(enveloper.check(enveloper.wrap(content))).toBe(true);
+        },
+      );
+
+      it.each`
+        enveloper              | value
+        ${streamEnveloper.foo} | ${null}
+        ${streamEnveloper.foo} | ${true}
+        ${streamEnveloper.foo} | ${[]}
+        ${streamEnveloper.foo} | ${{}}
+        ${streamEnveloper.foo} | ${fooContent}
+        ${streamEnveloper.foo} | ${{ id: '0xcafebeef' }}
+        ${streamEnveloper.foo} | ${{ label: 'foo', content: barContent }}
+        ${streamEnveloper.bar} | ${{ label: 'Bar', content: barContent }}
+      `(
+        'returns false for invalid envelopes: $value',
+        ({ enveloper, value }) => {
+          expect(enveloper.check(value)).toBe(false);
+        },
+      );
+
+      /* eslint-disable @typescript-eslint/no-unused-expressions */
+      // eslint-disable-next-line vitest/expect-expect
+      it.each`
+        envelope
+        ${null}
+      `('provides proper typescript inferences', ({ envelope }) => {
+        // eslint-disable-next-line vitest/no-conditional-in-test
+        if (streamEnveloper.foo.check(envelope)) {
+          inferNumber(envelope.content.a);
+          // @ts-expect-error a is not a string
+          inferString(envelope.content.a);
+          // @ts-expect-error b is not a number
+          inferNumber(envelope.content.b);
+          inferString(envelope.content.b);
+          // @ts-expect-error c is not defined
+          envelope.content.c;
+          switch (envelope.label) {
+            case Label.Foo:
+              expect(envelope.label).toMatch(Label.Foo);
+              break;
+            // @ts-expect-error label is Label.Foo
+            case Label.Bar: // unreachable
+              // @ts-expect-error label is inferred to be never
+              expect(envelope.label.concat('')).toMatch(
+                'This test line should be unreachable.',
+              );
+              break;
+            default: // unreachable
+              // @ts-expect-error label is inferred to be never
+              expect(envelope.label.concat('')).toMatch(
+                'This test line should be unreachable.',
+              );
+          }
+        }
+
+        // eslint-disable-next-line vitest/no-conditional-in-test
+        if (streamEnveloper.bar.check(envelope)) {
+          // @ts-expect-error a is not defined
+          envelope.content.a;
+          // @ts-expect-error b is not defined
+          envelope.content.b;
+          inferBoolean(envelope.content.c);
+          switch (envelope.label) {
+            // @ts-expect-error label is Label.Bar
+            case Label.Foo: // unreachable
+              // @ts-expect-error label is inferred to be never
+              expect(envelope.label.concat('')).toMatch(
+                'This test line should be unreachable.',
+              );
+              break;
+            case Label.Bar:
+              expect(envelope.label).toMatch(Label.Bar);
+              break;
+            default: // unreachable
+              // @ts-expect-error label is inferred to be never
+              expect(envelope.label.concat('')).toMatch(
+                'This test line should be unreachable.',
+              );
+          }
+        }
+      });
+      /* eslint-enable @typescript-eslint/no-unused-expressions */
+    });
+
+    describe('wrap', () => {
+      it.each`
+        enveloper              | content
+        ${streamEnveloper.foo} | ${fooContent}
+        ${streamEnveloper.bar} | ${barContent}
+      `(
+        'is inverse to unwrap from the same enveloper: $enveloper',
+        ({ enveloper, content }) => {
+          expect(enveloper.unwrap(enveloper.wrap(content))).toStrictEqual(
+            content,
+          );
+        },
+      );
+
+      // eslint-disable-next-line vitest/expect-expect
+      it('provides proper typescript inferences', () => {
+        streamEnveloper.foo.wrap(fooContent);
+        // @ts-expect-error foo rejects barContent
+        streamEnveloper.foo.wrap(barContent);
+        // @ts-expect-error bar rejects fooContent
+        streamEnveloper.bar.wrap(fooContent);
+        streamEnveloper.bar.wrap(barContent);
+      });
+    });
+
+    describe('unwrap', () => {
+      it.each`
+        enveloper              | envelope
+        ${streamEnveloper.foo} | ${{ content: fooContent }}
+        ${streamEnveloper.foo} | ${{ label: Label.Bar, content: fooContent }}
+      `(
+        'throws if passed an envelope with the wrong label: $envelope',
+        ({ enveloper, envelope }) => {
+          expect(() => enveloper.unwrap(envelope)).toThrow(
+            /^Expected envelope labelled "foo" but got /u,
+          );
+        },
+      );
+
+      /* eslint-disable @typescript-eslint/no-unused-expressions */
+      // eslint-disable-next-line vitest/expect-expect
+      it.each`
+        envelope
+        ${null}
+      `('provides proper typescript inferences', ({ envelope }) => {
+        try {
+          const content = streamEnveloper.foo.unwrap(envelope);
+
+          inferNumber(content.a);
+          // @ts-expect-error a is not a string
+          inferString(content.a);
+          // @ts-expect-error b is not a number
+          inferNumber(content.b);
+          inferString(content.b);
+          // @ts-expect-error c is undefined
+          content.c;
+        } catch {
+          undefined;
+        }
+
+        try {
+          // @ts-expect-error envelope was already inferred to be Envelope<Label.Foo, Foo>
+          content = streamEnveloper.bar.unwrap(envelope);
+        } catch {
+          undefined;
+        }
+      });
+      /* eslint-enable @typescript-eslint/no-unused-expressions */
+    });
+
+    describe('label', () => {
+      it.each`
+        enveloper              | label
+        ${streamEnveloper.foo} | ${Label.Foo}
+        ${streamEnveloper.bar} | ${Label.Bar}
+      `('has the right label: $label', ({ enveloper, label }) => {
+        expect(enveloper.label).toBe(label);
+      });
+
+      /* eslint-disable @typescript-eslint/no-unused-expressions */
+      // eslint-disable-next-line vitest/expect-expect
+      it.each`
+        fooEnveloper
+        ${streamEnveloper.foo}
+      `('provides proper typescript inferences', ({ fooEnveloper }) => {
+        const inferFooEnveloper = (
+          enveloper: typeof streamEnveloper.foo,
+        ): unknown => enveloper;
+        const inferBarEnveloper = (
+          enveloper: typeof streamEnveloper.bar,
+        ): unknown => enveloper;
+
+        type Enveloper = (typeof streamEnveloper)[keyof typeof streamEnveloper];
+        const ambiguousEnveloper = fooEnveloper as Enveloper;
+
+        switch (ambiguousEnveloper.label) {
+          case Label.Foo:
+            inferFooEnveloper(ambiguousEnveloper);
+            // @ts-expect-error label = Label.Foo implies ambiguousEnveloper is a FooEnveloper
+            inferBarEnveloper(ambiguousEnveloper);
+            break;
+          case Label.Bar:
+            // @ts-expect-error label = Label.Bar implies ambiguousEnveloper is a BarEnveloper
+            inferFooEnveloper(ambiguousEnveloper);
+            inferBarEnveloper(ambiguousEnveloper);
+            break;
+          default: // unreachable
+            // @ts-expect-error label options are exhausted
+            ambiguousEnveloper.label;
+        }
+      });
+      /* eslint-enable @typescript-eslint/no-unused-expressions */
+    });
+  });
+
+  describe('isStreamEnvelope', () => {
+    it.each`
+      value
+      ${streamEnveloper.foo.wrap(fooContent)}
+      ${streamEnveloper.bar.wrap(barContent)}
+    `('returns true for valid envelopes: $value', ({ value }) => {
+      expect(isStreamEnvelope(value)).toBe(true);
+    });
+
+    it.each`
+      value
+      ${null}
+      ${true}
+      ${[]}
+      ${{}}
+      ${fooContent}
+      ${{ id: '0x5012C312312' }}
+      ${streamEnveloper.foo.wrap(barContent as unknown as Foo)}
+    `('returns false for invalid values: $value', ({ value }) => {
+      expect(isStreamEnvelope(value)).toBe(false);
+    });
+
+    /* eslint-disable @typescript-eslint/no-unused-expressions */
+    // eslint-disable-next-line vitest/expect-expect
+    it.each`
+      value
+      ${null}
+    `('provides proper typescript inferences', ({ value }) => {
+      // eslint-disable-next-line vitest/no-conditional-in-test
+      if (isStreamEnvelope(value)) {
+        switch (value.label) {
+          case Label.Foo:
+            inferNumber(value.content.a);
+            // @ts-expect-error a is not a string
+            inferString(value.content.a);
+            // @ts-expect-error b is not a number
+            inferNumber(value.content.b);
+            inferString(value.content.b);
+            // @ts-expect-error c is undefined
+            value.content.c;
+            break;
+          case Label.Bar:
+            // @ts-expect-error a is undefined
+            value.content.a;
+            // @ts-expect-error a is undefined
+            value.content.b;
+            inferBoolean(value.content.c);
+            break;
+          default: // unreachable
+            // @ts-expect-error label options are exhausted
+            value.label;
+        }
+      }
+    });
+    /* eslint-enable @typescript-eslint/no-unused-expressions */
+  });
+});
diff --git a/packages/streams/src/envelope-kit.ts b/packages/streams/src/envelope-kit.ts
new file mode 100644
index 000000000..f9e8a0492
--- /dev/null
+++ b/packages/streams/src/envelope-kit.ts
@@ -0,0 +1,175 @@
+import { isObject } from '@metamask/utils';
+
+// Utilitous mapped types.
+
+/**
+ * An object type mapping keys to `ValueType`.
+ * A type which extends `TypeMap<SpecificKeys, unknown>` can map each key to a different type.
+ */
+type TypeMap<Keys extends string, ValueType = unknown> = {
+  [key in Keys]: ValueType;
+};
+
+/**
+ * Omit from `ObjectType` all keys without the specified `ValueType`.
+ */
+type PickByValue<ObjectType, ValueType> = Pick<
+  ObjectType,
+  {
+    [K in keyof ObjectType]: ObjectType[K] extends ValueType ? K : never;
+  }[keyof ObjectType]
+>;
+
+/**
+ * The result type of calling `Object.entries` on an object of type `ObjectType`.
+ *
+ * WARNING: If an object is typed as `ObjectType` but has excess properties,
+ * `Entries<typeof object>` will incorrectly omit the entries corresponding to the
+ * excess properties. Ensure your assumptions about the object align with typescript's.
+ * To be safe, use a type guard or only apply to objects you have declared.
+ *
+ * See https://www.typescriptlang.org/docs/handbook/2/objects.html#excess-property-checks
+ * for a description of excess properties.
+ */
+type Entries<ObjectType> = {
+  [K in keyof ObjectType]: [
+    keyof PickByValue<ObjectType, ObjectType[K]>,
+    ObjectType[K],
+  ];
+}[keyof ObjectType][];
+
+// Envelope types and type guards.
+
+type Envelope<Label extends string, Content> = {
+  label: Label;
+  content: Content;
+};
+
+type LabeledWith<Label extends string> = {
+  label: Label;
+  [key: string]: unknown;
+};
+
+const isLabeled = <Label extends string>(
+  value: unknown,
+  label?: Label,
+): value is LabeledWith<Label> =>
+  isObject(value) &&
+  typeof value.label !== 'undefined' &&
+  (label === undefined || value.label === label);
+
+type ContainerOf<Content> = {
+  content: Content;
+  [key: string]: unknown;
+};
+
+// Enveloper.
+
+type Enveloper<Label extends string, Content> = {
+  label: Label;
+  check: (value: unknown) => value is Envelope<Label, Content>;
+  wrap: (content: Content) => Envelope<Label, Content>;
+  unwrap: (envelope: Envelope<Label, Content>) => Content;
+};
+
+const makeEnveloper = <Label extends string, Content>(
+  label: Label,
+  isContent: (value: unknown) => value is Content,
+): Enveloper<Label, Content> => {
+  const hasLabel = (value: unknown): value is LabeledWith<Label> =>
+    isLabeled(value, label);
+  const hasContent = (value: unknown): value is ContainerOf<Content> =>
+    isObject(value) &&
+    typeof value.content !== 'undefined' &&
+    isContent(value.content);
+  return {
+    label,
+    check: (value: unknown): value is Envelope<Label, Content> =>
+      hasLabel(value) && hasContent(value),
+    wrap: (content: Content) =>
+      ({
+        label,
+        content,
+      } as Envelope<Label, Content>),
+    unwrap: (envelope: Envelope<Label, Content>): Content => {
+      if (!hasLabel(envelope)) {
+        throw new Error(
+          // @ts-expect-error The type of `envelope` is `never`, but this could happen at runtime.
+          // eslint-disable-next-line @typescript-eslint/restrict-template-expressions
+          `Expected envelope labelled "${label}" but got "${envelope.label}".`,
+        );
+      }
+      return envelope.content;
+    },
+  };
+};
+
+// Stream envelope kit.
+
+type StreamEnvelopeKitGuards<
+  Labels extends readonly string[],
+  ContentMap extends TypeMap<Labels[number]>,
+> = {
+  [K in Labels[number]]: (value: unknown) => value is ContentMap[K];
+};
+
+type StreamEnveloper<
+  Labels extends readonly string[],
+  ContentMap extends TypeMap<Labels[number]>,
+> = {
+  [K in Labels[number]]: Enveloper<K, ContentMap[K]>;
+};
+
+type StreamEnvelope<Label extends string, ContentMap extends TypeMap<Label>> = {
+  [K in Label]: Envelope<K, ContentMap[K]>;
+}[Label];
+
+type StreamEnvelopeKit<
+  Labels extends readonly string[],
+  ContentMap extends TypeMap<Labels[number]>,
+> = {
+  streamEnveloper: StreamEnveloper<Labels, ContentMap>;
+  isStreamEnvelope: (
+    value: unknown,
+  ) => value is StreamEnvelope<Labels[number], ContentMap>;
+};
+
+/**
+ * Make a {@link StreamEnvelopeKit}.
+ * The template parameters must be explicitly declared. See tutorial for suggested declaration pattern.
+ *
+ * @tutorial documents/make-stream-envelope-kit.md - An example showing how to specify the template parameters, including how to pass an enum type as a template parameter.
+ * @template Labels - An enum of envelope labels. WARNING: if specified improperly, typescript inference fails. See referenced tutorial.
+ * @template Content - An object type mapping the specified labels to the type of content they label.
+ * @param guards - An object mapping the specified envelope labels to a type guard of their contents.
+ * @returns The {@link StreamEnvelopeKit}.
+ */
+export const makeStreamEnvelopeKit = <
+  Labels extends string[],
+  ContentMap extends TypeMap<Labels[number]>,
+>(
+  guards: StreamEnvelopeKitGuards<Labels, ContentMap>,
+): StreamEnvelopeKit<Labels, ContentMap> => {
+  const entries = Object.entries(guards) as Entries<
+    StreamEnvelopeKitGuards<Labels, ContentMap>
+  >;
+  const streamEnveloper = Object.fromEntries(
+    entries.map(([label, isContent]) => [
+      label,
+      makeEnveloper(label, isContent),
+    ]),
+  );
+  return {
+    streamEnveloper: streamEnveloper as unknown as StreamEnveloper<
+      Labels,
+      ContentMap
+    >,
+    isStreamEnvelope: (
+      value: unknown,
+    ): value is StreamEnvelope<Labels[number], ContentMap> =>
+      isLabeled(value) &&
+      Object.values(streamEnveloper).some((enveloper) =>
+        enveloper.check(value),
+      ),
+  };
+};
diff --git a/packages/streams/src/index.ts b/packages/streams/src/index.ts
index aacd60335..22114e38e 100644
--- a/packages/streams/src/index.ts
+++ b/packages/streams/src/index.ts
@@ -8,3 +8,4 @@ export {
   MessagePortReader,
   MessagePortWriter,
 } from './streams.js';
+export { makeStreamEnvelopeKit } from './envelope-kit.js';
diff --git a/packages/streams/typedoc.json b/packages/streams/typedoc.json
index 3d60644d9..0b5039f22 100644
--- a/packages/streams/typedoc.json
+++ b/packages/streams/typedoc.json
@@ -3,5 +3,6 @@
   "excludePrivate": true,
   "hideGenerator": true,
   "out": "docs",
-  "tsconfig": "./tsconfig.build.json"
+  "tsconfig": "./tsconfig.build.json",
+  "projectDocuments": ["documents/*.md"]
 }

From 2278f7ea0678930c700e3e495b1aa91d5c333881 Mon Sep 17 00:00:00 2001
From: grypez <143971198+grypez@users.noreply.github.com>
Date: Sun, 15 Sep 2024 13:27:31 -0500
Subject: [PATCH 15/22] refactor(extension): Use @ocap/streams/envelope-kit.

---
 packages/extension/src/envelope.test.ts       | 134 -----------
 packages/extension/src/envelope.ts            | 225 ------------------
 packages/extension/src/iframe-manager.test.ts |  21 +-
 packages/extension/src/iframe-manager.ts      |  15 +-
 packages/extension/src/iframe.ts              |  12 +-
 .../extension/src/stream-envelope.test.ts     |  78 ++++++
 packages/extension/src/stream-envelope.ts     | 158 ++++++++++++
 7 files changed, 264 insertions(+), 379 deletions(-)
 delete mode 100644 packages/extension/src/envelope.test.ts
 delete mode 100644 packages/extension/src/envelope.ts
 create mode 100644 packages/extension/src/stream-envelope.test.ts
 create mode 100644 packages/extension/src/stream-envelope.ts

diff --git a/packages/extension/src/envelope.test.ts b/packages/extension/src/envelope.test.ts
deleted file mode 100644
index a1c0605d0..000000000
--- a/packages/extension/src/envelope.test.ts
+++ /dev/null
@@ -1,134 +0,0 @@
-import { describe, it, expect } from 'vitest';
-
-import {
-  capTpEnveloper,
-  commandEnveloper,
-  EnvelopeLabel,
-  isStreamEnvelope,
-  makeStreamEnvelopeHandler,
-} from './envelope.js';
-import type { CapTpMessage, WrappedIframeMessage } from './message.js';
-import { Command } from './message.js';
-
-const contentFixtures = {
-  command: {
-    id: '1',
-    message: { type: Command.Evaluate, data: '1 + 1' },
-  } as WrappedIframeMessage,
-  capTp: {
-    type: 'CTP_CALL',
-    epoch: 0,
-    unreliableKey: Symbol('unreliableValue'),
-  } as CapTpMessage,
-};
-
-describe('envelope', () => {
-  describe('isStreamEnvelope', () => {
-    it('returns true for valid messages', () => {
-      expect(
-        isStreamEnvelope({
-          label: EnvelopeLabel.Command,
-          content: {
-            id: '1',
-            message: { type: 'evaluate', data: '1 + 1' },
-          },
-        }),
-      ).toBe(true);
-    });
-
-    it.each`
-      enveloper           | content
-      ${commandEnveloper} | ${contentFixtures.command}
-      ${capTpEnveloper}   | ${contentFixtures.capTp}
-    `(
-      'returns true for valid contents wrapped by $enveloper.label enveloper',
-      ({ enveloper, content }) => {
-        expect(isStreamEnvelope(enveloper.wrap(content))).toBe(true);
-      },
-    );
-
-    it.each`
-      envelope
-      ${{}}
-      ${{ label: EnvelopeLabel.Command }}
-      ${{ label: EnvelopeLabel.CapTp }}
-      ${{ label: EnvelopeLabel.Command, content: contentFixtures.capTp }}
-      ${{ label: 'unknown', content: [] }}
-    `('returns false for invalid envelopes: $envelope', ({ envelope }) => {
-      expect(isStreamEnvelope(envelope)).toBe(false);
-    });
-  });
-
-  describe('StreamEnvelopeHandler', () => {
-    const testEnvelopeHandlers = {
-      command: async () => EnvelopeLabel.Command,
-      capTp: async () => EnvelopeLabel.CapTp,
-    };
-    const testErrorHandler = (problem: unknown): never => {
-      throw new Error(`TEST ${String(problem)}`);
-    };
-
-    it.each`
-      enveloper           | message
-      ${commandEnveloper} | ${contentFixtures.command}
-      ${capTpEnveloper}   | ${contentFixtures.capTp}
-    `('handles valid StreamEnvelopes', async ({ enveloper, message }) => {
-      const handler = makeStreamEnvelopeHandler(
-        testEnvelopeHandlers,
-        testErrorHandler,
-      );
-      expect(await handler.handle(enveloper.wrap(message))).toStrictEqual(
-        enveloper.label,
-      );
-    });
-
-    it('routes invalid envelopes to default error handler', async () => {
-      const handler = makeStreamEnvelopeHandler(testEnvelopeHandlers);
-      await expect(
-        // @ts-expect-error label is intentionally unknown
-        handler.handle({ label: 'unknown', content: [] }),
-      ).rejects.toThrow(/^Stream envelope handler received unexpected value/u);
-    });
-
-    it('routes invalid envelopes to supplied error handler', async () => {
-      const handler = makeStreamEnvelopeHandler(
-        testEnvelopeHandlers,
-        testErrorHandler,
-      );
-      await expect(
-        // @ts-expect-error label is intentionally unknown
-        handler.handle({ label: 'unknown', content: [] }),
-      ).rejects.toThrow(
-        /^TEST Stream envelope handler received unexpected value/u,
-      );
-    });
-
-    it('routes valid stream envelopes with an unhandled label to the error handler', async () => {
-      const handler = makeStreamEnvelopeHandler(
-        { command: testEnvelopeHandlers.command },
-        testErrorHandler,
-      );
-      await expect(
-        handler.handle(capTpEnveloper.wrap(contentFixtures.capTp)),
-      ).rejects.toThrow(
-        /^TEST Stream envelope handler received an envelope with known but unexpected label/u,
-      );
-    });
-  });
-
-  describe('envelopeKit', () => {
-    it.each`
-      enveloper           | envelope
-      ${commandEnveloper} | ${contentFixtures.capTp}
-      ${capTpEnveloper}   | ${contentFixtures.command}
-      ${commandEnveloper} | ${capTpEnveloper.wrap(contentFixtures.command as unknown as CapTpMessage)}
-    `(
-      'throws when $enveloper.label enveloper attempts to unwrap a malformed envelope $envelope',
-      ({ enveloper, envelope }) => {
-        expect(() => enveloper.unwrap(envelope)).toThrow(
-          /^Expected envelope labelled/u,
-        );
-      },
-    );
-  });
-});
diff --git a/packages/extension/src/envelope.ts b/packages/extension/src/envelope.ts
deleted file mode 100644
index e14883a40..000000000
--- a/packages/extension/src/envelope.ts
+++ /dev/null
@@ -1,225 +0,0 @@
-import { isObject } from '@metamask/utils';
-
-import type { CapTpMessage, WrappedIframeMessage } from './message.js';
-import { isCapTpMessage, isWrappedIframeMessage } from './message.js';
-
-export enum EnvelopeLabel {
-  Command = 'command',
-  CapTp = 'capTp',
-}
-
-type EnvelopeLike<Label extends EnvelopeLabel, Content> = {
-  label: Label;
-  content: Content;
-};
-
-type LabelOf<Envelope> = Envelope extends EnvelopeLike<infer Label, unknown>
-  ? Label
-  : never;
-type LabeledWith<Label extends EnvelopeLabel> = {
-  label: Label;
-  [key: string]: unknown;
-};
-const isLabeled = <Label extends EnvelopeLabel>(
-  value: unknown,
-  label?: Label,
-): value is LabeledWith<Label> =>
-  isObject(value) &&
-  typeof value.label !== 'undefined' &&
-  (label === undefined || value.label === label);
-
-type ContentOf<Envelope> = Envelope extends EnvelopeLike<
-  EnvelopeLabel,
-  infer Content
->
-  ? Content
-  : never;
-type ContainerOf<Content> = {
-  content: Content;
-  [key: string]: unknown;
-};
-
-type GenericEnvelope<Envelope> = EnvelopeLike<
-  LabelOf<Envelope>,
-  ContentOf<Envelope>
->;
-
-type EnvelopeKit<Envelope extends GenericEnvelope<Envelope>> = {
-  label: Envelope['label'];
-  check: (value: unknown) => value is Envelope;
-  wrap: (content: Envelope['content']) => Envelope;
-  unwrap: (envelope: Envelope) => Envelope['content'];
-};
-
-const makeEnvelopeKit = <Envelope extends GenericEnvelope<Envelope>>(
-  label: Envelope['label'],
-  isContent: (value: unknown) => value is Envelope['content'],
-): EnvelopeKit<Envelope> => {
-  const hasLabel = (value: unknown): value is LabeledWith<Envelope['label']> =>
-    isLabeled(value, label);
-  const hasContent = (
-    value: unknown,
-  ): value is ContainerOf<Envelope['content']> =>
-    isObject(value) &&
-    typeof value.content !== 'undefined' &&
-    isContent(value.content);
-  return {
-    label,
-    check: (value: unknown): value is Envelope =>
-      hasLabel(value) && hasContent(value),
-    wrap: (content: Envelope['content']) =>
-      ({
-        label,
-        content,
-      } as Envelope),
-    unwrap: (envelope: Envelope): Envelope['content'] => {
-      if (!hasLabel(envelope)) {
-        throw new Error(
-          // @ts-expect-error The type of `envelope` is `never`, but this could happen at runtime.
-          // eslint-disable-next-line @typescript-eslint/restrict-template-expressions
-          `Expected envelope labelled "${label}" but got "${envelope.label}".`,
-        );
-      }
-      return envelope.content;
-    },
-  };
-};
-
-type CommandEnvelope = EnvelopeLike<
-  EnvelopeLabel.Command,
-  WrappedIframeMessage
->;
-type CapTpEnvelope = EnvelopeLike<EnvelopeLabel.CapTp, CapTpMessage>;
-
-export const commandEnveloper = makeEnvelopeKit<CommandEnvelope>(
-  EnvelopeLabel.Command,
-  isWrappedIframeMessage,
-);
-export const capTpEnveloper = makeEnvelopeKit<CapTpEnvelope>(
-  EnvelopeLabel.CapTp,
-  isCapTpMessage,
-);
-
-export const wrapCommand = commandEnveloper.wrap;
-export const wrapCapTp = capTpEnveloper.wrap;
-
-export type StreamEnvelope = CommandEnvelope | CapTpEnvelope;
-
-type StreamEnvelopeContent<Label extends StreamEnvelope['label']> =
-  Label extends EnvelopeLabel.Command
-    ? CommandEnvelope['content']
-    : Label extends EnvelopeLabel.CapTp
-    ? CapTpEnvelope['content']
-    : never;
-
-const envelopeKits: { [Label in EnvelopeLabel]: EnvelopeKit<StreamEnvelope> } =
-  Object.fromEntries([
-    [EnvelopeLabel.Command, commandEnveloper],
-    [EnvelopeLabel.CapTp, capTpEnveloper],
-  ]);
-
-export const isStreamEnvelope = (value: unknown): value is StreamEnvelope =>
-  isLabeled(value) &&
-  Object.values(envelopeKits).some((kit) => kit.check(value));
-
-/**
- * A handler for automatically unwrapping stream envelopes and handling their content.
- *
- * @property handle - Sniffs an unknown value for envelope labels, applying the label's handler if known, and applying the error handler if the label is not handled or if the content did not pass the envelope's type guard.
- * @property contentHandlers - The bag of content candlers passed to the maker.
- * @property errorHandler - The error handler passed to the maker.
- */
-export type StreamEnvelopeHandler = {
-  handle: (envelope: StreamEnvelope) => Promise<unknown>;
-  contentHandlers: StreamEnvelopeContentHandlerBag;
-  errorHandler: StreamEnvelopeErrorHandler;
-};
-
-/**
- * A handler for a specific stream envelope label.
- */
-type StreamEnvelopeContentHandler<Label extends EnvelopeLabel> = (
-  content: StreamEnvelopeContent<Label>,
-) => Promise<unknown>;
-
-/**
- * An object with {@link EnvelopeLabel} keys mapping to an appropriate {@link StreamEnvelopeContentHandler}.
- * If the stream envelope handler encounters a well-formed stream envelope without a defined handler,
- * the envelope will be passed to the {@link ErrorHandler}.
- */
-type StreamEnvelopeContentHandlerBag = {
-  [Label in EnvelopeLabel]?: StreamEnvelopeContentHandler<Label>;
-};
-
-/**
- * A handler for stream envelope parsing errors.
- * If the {@link StreamEnvelopeHandler} encounters an error while parsing the supplied value,
- * it will pass the reason and value to the error handler.
- */
-type StreamEnvelopeErrorHandler = (reason: string, value: unknown) => unknown;
-
-/**
- * The default handler for stream envelope parsing errors.
- *
- * @param reason - The reason for the error.
- * @param value - The value that caused the error.
- */
-const defaultStreamEnvelopeErrorHandler: StreamEnvelopeErrorHandler = (
-  reason,
-  value,
-) => {
-  throw new Error(`${reason} ${JSON.stringify(value, null, 2)}`);
-};
-
-/**
- * Makes a {@link StreamEnvelopeHandler} which handles an unknown value.
- *
- * If the supplied value is a valid envelope with a defined {@link StreamEnvelopeHandler},
- * the stream envelope handler will return whatever the defined handler returns.
- *
- * If the stream envelope handler is passed a well-formed stream envelope without a defined handler,
- * an explanation and the envelope will be passed to the supplied {@link StreamEnvelopeErrorHandler}.
- *
- * If the stream envelope handler encounters an error while parsing the supplied value,
- * it will pass the reason and value to the supplied {@link StreamEnvelopeErrorHandler}.
- *
- * If no error handler is supplied, the default error handling behavior is to throw.
- *
- * @param contentHandlers - A bag of async content handlers labeled with the {@link EnvelopeLabel} they handle.
- * @param errorHandler - An optional synchronous error handler.
- * @returns The stream envelope handler.
- */
-export const makeStreamEnvelopeHandler = (
-  contentHandlers: StreamEnvelopeContentHandlerBag,
-  errorHandler: StreamEnvelopeErrorHandler = defaultStreamEnvelopeErrorHandler,
-): StreamEnvelopeHandler => ({
-  handle: async (value: unknown) => {
-    if (!isStreamEnvelope(value)) {
-      return errorHandler(
-        'Stream envelope handler received unexpected value',
-        value,
-      );
-    }
-    const envelope = value;
-    const kit = envelopeKits[envelope.label];
-    /* v8 ignore next 6: Not known to be possible. */
-    if (!kit) {
-      return errorHandler(
-        'Stream envelope handler received an envelope with unknown label',
-        envelope,
-      );
-    }
-    const handler = contentHandlers[envelope.label];
-    if (!handler) {
-      return errorHandler(
-        'Stream envelope handler received an envelope with known but unexpected label',
-        envelope,
-      );
-    }
-    return await (
-      handler as StreamEnvelopeContentHandler<typeof envelope.label>
-    )(kit.unwrap(envelope));
-  },
-  contentHandlers,
-  errorHandler,
-});
diff --git a/packages/extension/src/iframe-manager.test.ts b/packages/extension/src/iframe-manager.test.ts
index 221a9c029..d580f6b22 100644
--- a/packages/extension/src/iframe-manager.test.ts
+++ b/packages/extension/src/iframe-manager.test.ts
@@ -3,10 +3,10 @@ import * as snapsUtils from '@metamask/snaps-utils';
 import { delay, makePromiseKitMock } from '@ocap/test-utils';
 import { vi, describe, it, expect } from 'vitest';
 
-import { capTpEnveloper, wrapCommand, wrapCapTp } from './envelope.js';
 import { IframeManager } from './iframe-manager.js';
 import type { IframeMessage } from './message.js';
 import { Command } from './message.js';
+import { wrapCommand, wrapCapTp } from './stream-envelope.js';
 
 vi.mock('@endo/promise-kit', () => makePromiseKitMock());
 
@@ -68,12 +68,17 @@ describe('IframeManager', () => {
 
     it('creates a new iframe with the default getPort function', async () => {
       vi.resetModules();
-      vi.doMock('@ocap/streams', () => ({
-        initializeMessageChannel: vi.fn(),
-        makeMessagePortStreamPair: vi.fn(() => ({ reader: {}, writer: {} })),
-        MessagePortReader: class Mock1 {},
-        MessagePortWriter: class Mock2 {},
-      }));
+      vi.doMock('@ocap/streams', async (importOriginal) => {
+        // @ts-expect-error This import is known to exist, and the linter erases the appropriate assertion.
+        const { makeStreamEnvelopeKit } = await importOriginal();
+        return {
+          initializeMessageChannel: vi.fn(),
+          makeMessagePortStreamPair: vi.fn(() => ({ reader: {}, writer: {} })),
+          MessagePortReader: class Mock1 {},
+          MessagePortWriter: class Mock2 {},
+          makeStreamEnvelopeKit,
+        };
+      });
       const IframeManager2 = (await import('./iframe-manager.js'))
         .IframeManager;
 
@@ -191,7 +196,7 @@ describe('IframeManager', () => {
 
       await manager.create({ id, getPort: makeGetPort(port1) });
 
-      const envelope = capTpEnveloper.wrap({
+      const envelope = wrapCapTp({
         epoch: 0,
         questionID: 'q-1',
         type: 'CTP_BOOTSTRAP',
diff --git a/packages/extension/src/iframe-manager.ts b/packages/extension/src/iframe-manager.ts
index bfcd9e6ef..d1cd1b4e8 100644
--- a/packages/extension/src/iframe-manager.ts
+++ b/packages/extension/src/iframe-manager.ts
@@ -9,12 +9,6 @@ import {
   makeMessagePortStreamPair,
 } from '@ocap/streams';
 
-import type { StreamEnvelope, StreamEnvelopeHandler } from './envelope.js';
-import {
-  makeStreamEnvelopeHandler,
-  wrapCapTp,
-  wrapCommand,
-} from './envelope.js';
 import type {
   CapTpMessage,
   CapTpPayload,
@@ -23,6 +17,15 @@ import type {
 } from './message.js';
 import { Command } from './message.js';
 import { makeCounter, type VatId } from './shared.js';
+import {
+  makeStreamEnvelopeHandler,
+  wrapCapTp,
+  wrapCommand,
+} from './stream-envelope.js';
+import type {
+  StreamEnvelope,
+  StreamEnvelopeHandler,
+} from './stream-envelope.js';
 
 const IFRAME_URI = 'iframe.html';
 
diff --git a/packages/extension/src/iframe.ts b/packages/extension/src/iframe.ts
index ed6ffc808..294560d4a 100644
--- a/packages/extension/src/iframe.ts
+++ b/packages/extension/src/iframe.ts
@@ -3,18 +3,18 @@ import { makeExo } from '@endo/exo';
 import { M } from '@endo/patterns';
 import { receiveMessagePort, makeMessagePortStreamPair } from '@ocap/streams';
 
-import type { StreamEnvelope } from './envelope.js';
-import {
-  wrapCapTp,
-  wrapCommand,
-  makeStreamEnvelopeHandler,
-} from './envelope.js';
 import type {
   CapTpMessage,
   IframeMessage,
   WrappedIframeMessage,
 } from './message.js';
 import { Command } from './message.js';
+import type { StreamEnvelope } from './stream-envelope.js';
+import {
+  wrapCapTp,
+  wrapCommand,
+  makeStreamEnvelopeHandler,
+} from './stream-envelope.js';
 
 const defaultCompartment = new Compartment({ URL });
 
diff --git a/packages/extension/src/stream-envelope.test.ts b/packages/extension/src/stream-envelope.test.ts
new file mode 100644
index 000000000..94677e051
--- /dev/null
+++ b/packages/extension/src/stream-envelope.test.ts
@@ -0,0 +1,78 @@
+import '@ocap/shims/endoify';
+import { describe, it, expect } from 'vitest';
+
+import type { CapTpMessage, WrappedIframeMessage } from './message.js';
+import { Command } from './message.js';
+import {
+  wrapCapTp,
+  wrapCommand,
+  makeStreamEnvelopeHandler,
+} from './stream-envelope.js';
+
+describe('StreamEnvelopeHandler', () => {
+  const commandContent: WrappedIframeMessage = {
+    id: '1',
+    message: { type: Command.Evaluate, data: '1 + 1' },
+  };
+  const capTpContent: CapTpMessage = {
+    type: 'CTP_CALL',
+    epoch: 0,
+    // Our assumptions about the form of a CapTpMessage are weak.
+    unreliableKey: Symbol('unreliableValue'),
+  };
+
+  const commandLabel = wrapCommand(commandContent).label;
+  const capTpLabel = wrapCapTp(capTpContent).label;
+
+  const testEnvelopeHandlers = {
+    command: async () => commandLabel,
+    capTp: async () => capTpLabel,
+  };
+
+  const testErrorHandler = (problem: unknown): never => {
+    throw new Error(`TEST ${String(problem)}`);
+  };
+
+  it.each`
+    wrapper        | content           | label
+    ${wrapCommand} | ${commandContent} | ${commandLabel}
+    ${wrapCapTp}   | ${capTpContent}   | ${capTpLabel}
+  `('handles valid StreamEnvelopes', async ({ wrapper, content, label }) => {
+    const handler = makeStreamEnvelopeHandler(
+      testEnvelopeHandlers,
+      testErrorHandler,
+    );
+    expect(await handler.handle(wrapper(content))).toStrictEqual(label);
+  });
+
+  it('routes invalid envelopes to default error handler', async () => {
+    const handler = makeStreamEnvelopeHandler(testEnvelopeHandlers);
+    await expect(
+      // @ts-expect-error label is intentionally unknown
+      handler.handle({ label: 'unknown', content: [] }),
+    ).rejects.toThrow(/^Stream envelope handler received unexpected value/u);
+  });
+
+  it('routes invalid envelopes to supplied error handler', async () => {
+    const handler = makeStreamEnvelopeHandler(
+      testEnvelopeHandlers,
+      testErrorHandler,
+    );
+    await expect(
+      // @ts-expect-error label is intentionally unknown
+      handler.handle({ label: 'unknown', content: [] }),
+    ).rejects.toThrow(
+      /^TEST Stream envelope handler received unexpected value/u,
+    );
+  });
+
+  it('routes valid stream envelopes with an unhandled label to the error handler', async () => {
+    const handler = makeStreamEnvelopeHandler(
+      { command: testEnvelopeHandlers.command },
+      testErrorHandler,
+    );
+    await expect(handler.handle(wrapCapTp(capTpContent))).rejects.toThrow(
+      /^TEST Stream envelope handler received an envelope with known but unexpected label/u,
+    );
+  });
+});
diff --git a/packages/extension/src/stream-envelope.ts b/packages/extension/src/stream-envelope.ts
new file mode 100644
index 000000000..41ce35710
--- /dev/null
+++ b/packages/extension/src/stream-envelope.ts
@@ -0,0 +1,158 @@
+import { makeStreamEnvelopeKit } from '@ocap/streams';
+
+import type { CapTpMessage, WrappedIframeMessage } from './message.js';
+import { isCapTpMessage, isWrappedIframeMessage } from './message.js';
+
+// Utilitous mapped types.
+
+type GuardType<TypeGuard> = TypeGuard extends (
+  value: unknown,
+) => value is infer Type
+  ? Type
+  : never;
+
+// Declare and destructure the envelope kit.
+
+enum EnvelopeLabel {
+  Command = 'command',
+  CapTp = 'capTp',
+}
+
+type ContentMap = {
+  command: WrappedIframeMessage;
+  capTp: CapTpMessage;
+};
+
+// makeStreamEnvelopeKit requires an enum of labels but typescript
+// doesn't support enums as bounds on template parameters.
+//
+// See https://github.com/microsoft/TypeScript/issues/30611
+//
+// This workaround makes something equivalently type inferenceable.
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+const envelopeLabels = Object.values(EnvelopeLabel);
+
+const { streamEnveloper, isStreamEnvelope } = makeStreamEnvelopeKit<
+  typeof envelopeLabels,
+  ContentMap
+>({
+  command: isWrappedIframeMessage,
+  capTp: isCapTpMessage,
+});
+
+export const wrapCommand = streamEnveloper.command.wrap;
+export const wrapCapTp = streamEnveloper.capTp.wrap;
+
+// Stream envelope handler.
+
+export type StreamEnvelope = GuardType<typeof isStreamEnvelope>;
+
+/**
+ * A handler for automatically unwrapping stream envelopes and handling their content.
+ */
+export type StreamEnvelopeHandler = {
+  /**
+   * Sniffs an unknown value for envelope labels, applying the label's handler
+   * if known, and applying the error handler if the label is not handled or if
+   * the content did not pass the envelope's type guard.
+   *
+   * @template Envelope - The type of the envelope.
+   * @param envelope - The envelope to handle.
+   * @returns The result of the handler.
+   */
+  handle: <Envelope extends StreamEnvelope>(
+    envelope: Envelope,
+  ) => Promise<unknown>;
+  /**
+   * The bag of async content handlers labeled with the {@link EnvelopeLabel} they handle.
+   */
+  contentHandlers: StreamEnvelopeContentHandlerBag;
+  /**
+   * The error handler for the stream envelope handler.
+   */
+  errorHandler: StreamEnvelopeErrorHandler;
+};
+
+/**
+ * A handler for a specific stream envelope label.
+ */
+type StreamEnvelopeContentHandler<Label extends EnvelopeLabel> = (
+  content: ContentMap[Label],
+) => Promise<unknown>;
+
+/**
+ * An object with {@link EnvelopeLabel} keys mapping to an appropriate {@link StreamEnvelopeContentHandler}.
+ * If the stream envelope handler encounters a well-formed stream envelope without a defined handler,
+ * the envelope will be passed to the {@link ErrorHandler}.
+ */
+type StreamEnvelopeContentHandlerBag = {
+  [Label in EnvelopeLabel]?: (content: ContentMap[Label]) => Promise<unknown>;
+};
+
+/**
+ * A handler for stream envelope parsing errors.
+ * If the {@link StreamEnvelopeHandler} encounters an error while parsing the supplied value,
+ * it will pass the reason and value to the error handler.
+ */
+type StreamEnvelopeErrorHandler = (reason: string, value: unknown) => unknown;
+
+/**
+ * The default handler for stream envelope parsing errors.
+ *
+ * @param reason - The reason for the error.
+ * @param value - The value that caused the error.
+ */
+const defaultStreamEnvelopeErrorHandler: StreamEnvelopeErrorHandler = (
+  reason,
+  value,
+) => {
+  throw new Error(`${reason} ${JSON.stringify(value, null, 2)}`);
+};
+
+/**
+ * Makes a {@link StreamEnvelopeHandler} which handles an unknown value.
+ *
+ * If the supplied value is a valid envelope with a defined {@link StreamEnvelopeHandler},
+ * the stream envelope handler will return whatever the defined handler returns.
+ *
+ * If the stream envelope handler is passed a well-formed stream envelope without a defined handler,
+ * an explanation and the envelope will be passed to the supplied {@link StreamEnvelopeErrorHandler}.
+ *
+ * If the stream envelope handler encounters an error while parsing the supplied value,
+ * it will pass the reason and value to the supplied {@link StreamEnvelopeErrorHandler}.
+ *
+ * If no error handler is supplied, the default error handling behavior is to throw.
+ *
+ * @param contentHandlers - A bag of async content handlers labeled with the {@link EnvelopeLabel} they handle.
+ * @param errorHandler - An optional synchronous error handler.
+ * @returns The stream envelope handler.
+ */
+export const makeStreamEnvelopeHandler = (
+  contentHandlers: StreamEnvelopeContentHandlerBag,
+  errorHandler: StreamEnvelopeErrorHandler = defaultStreamEnvelopeErrorHandler,
+): StreamEnvelopeHandler => ({
+  handle: async (value: unknown) => {
+    if (!isStreamEnvelope(value)) {
+      return errorHandler(
+        'Stream envelope handler received unexpected value',
+        value,
+      );
+    }
+    const envelope = value;
+    const handler = contentHandlers[envelope.label] as
+      | StreamEnvelopeContentHandler<typeof envelope.label>
+      | undefined;
+    if (!handler) {
+      return errorHandler(
+        'Stream envelope handler received an envelope with known but unexpected label',
+        envelope,
+      );
+    }
+    const enveloper = streamEnveloper[envelope.label];
+    // The handler design makes typescript claustrophobic, but this is safe.
+    const content = enveloper.unwrap(envelope as never);
+    return await handler(content);
+  },
+  contentHandlers,
+  errorHandler,
+});

From 8bf3efe900d96b9ce47bdec726048e41180674cd Mon Sep 17 00:00:00 2001
From: grypez <143971198+grypez@users.noreply.github.com>
Date: Mon, 16 Sep 2024 10:26:07 -0500
Subject: [PATCH 16/22] test(streams): Remove it.each in type inference tests.

---
 packages/streams/src/envelope-kit.test.ts | 28 ++++++++++-------------
 1 file changed, 12 insertions(+), 16 deletions(-)

diff --git a/packages/streams/src/envelope-kit.test.ts b/packages/streams/src/envelope-kit.test.ts
index 0e0110f02..6bdcd6700 100644
--- a/packages/streams/src/envelope-kit.test.ts
+++ b/packages/streams/src/envelope-kit.test.ts
@@ -102,10 +102,9 @@ describe('makeStreamEnvelopeKit', () => {
 
       /* eslint-disable @typescript-eslint/no-unused-expressions */
       // eslint-disable-next-line vitest/expect-expect
-      it.each`
-        envelope
-        ${null}
-      `('provides proper typescript inferences', ({ envelope }) => {
+      it('provides proper typescript inferences', () => {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const envelope: any = null;
         // eslint-disable-next-line vitest/no-conditional-in-test
         if (streamEnveloper.foo.check(envelope)) {
           inferNumber(envelope.content.a);
@@ -205,10 +204,9 @@ describe('makeStreamEnvelopeKit', () => {
 
       /* eslint-disable @typescript-eslint/no-unused-expressions */
       // eslint-disable-next-line vitest/expect-expect
-      it.each`
-        envelope
-        ${null}
-      `('provides proper typescript inferences', ({ envelope }) => {
+      it('provides proper typescript inferences', () => {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const envelope: any = null;
         try {
           const content = streamEnveloper.foo.unwrap(envelope);
 
@@ -245,10 +243,9 @@ describe('makeStreamEnvelopeKit', () => {
 
       /* eslint-disable @typescript-eslint/no-unused-expressions */
       // eslint-disable-next-line vitest/expect-expect
-      it.each`
-        fooEnveloper
-        ${streamEnveloper.foo}
-      `('provides proper typescript inferences', ({ fooEnveloper }) => {
+      it('provides proper typescript inferences', () => {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const fooEnveloper: any = streamEnveloper.foo;
         const inferFooEnveloper = (
           enveloper: typeof streamEnveloper.foo,
         ): unknown => enveloper;
@@ -303,10 +300,9 @@ describe('makeStreamEnvelopeKit', () => {
 
     /* eslint-disable @typescript-eslint/no-unused-expressions */
     // eslint-disable-next-line vitest/expect-expect
-    it.each`
-      value
-      ${null}
-    `('provides proper typescript inferences', ({ value }) => {
+    it('provides proper typescript inferences', () => {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const value: any = null;
       // eslint-disable-next-line vitest/no-conditional-in-test
       if (isStreamEnvelope(value)) {
         switch (value.label) {

From 4fe70dea86dc35ff0a5813a675a6399240c265d9 Mon Sep 17 00:00:00 2001
From: grypez <143971198+grypez@users.noreply.github.com>
Date: Mon, 16 Sep 2024 17:32:50 -0500
Subject: [PATCH 17/22] refactor(extensions,streams): Move
 StreamEnvelopeHandler to streams package.

---
 packages/extension/src/stream-envelope.ts     | 136 +-------
 .../documents/make-stream-envelope-kit.md     |  45 ++-
 packages/streams/src/envelope-handler.test.ts |  77 ++++
 packages/streams/src/envelope-handler.ts      | 140 ++++++++
 packages/streams/src/envelope-kit.test.ts     | 329 ++----------------
 packages/streams/src/envelope-kit.ts          | 210 ++++-------
 .../streams/src/envelope-test-fixtures.ts     |  39 +++
 packages/streams/src/envelope.test.ts         |  69 ++++
 packages/streams/src/envelope.ts              |  35 ++
 packages/streams/src/enveloper.test.ts        | 226 ++++++++++++
 packages/streams/src/enveloper.ts             |  80 +++++
 packages/streams/src/generics.ts              |  37 ++
 packages/streams/src/index.ts                 |   9 +-
 13 files changed, 866 insertions(+), 566 deletions(-)
 create mode 100644 packages/streams/src/envelope-handler.test.ts
 create mode 100644 packages/streams/src/envelope-handler.ts
 create mode 100644 packages/streams/src/envelope-test-fixtures.ts
 create mode 100644 packages/streams/src/envelope.test.ts
 create mode 100644 packages/streams/src/envelope.ts
 create mode 100644 packages/streams/src/enveloper.test.ts
 create mode 100644 packages/streams/src/enveloper.ts
 create mode 100644 packages/streams/src/generics.ts

diff --git a/packages/extension/src/stream-envelope.ts b/packages/extension/src/stream-envelope.ts
index 41ce35710..f120cfd70 100644
--- a/packages/extension/src/stream-envelope.ts
+++ b/packages/extension/src/stream-envelope.ts
@@ -3,7 +3,7 @@ import { makeStreamEnvelopeKit } from '@ocap/streams';
 import type { CapTpMessage, WrappedIframeMessage } from './message.js';
 import { isCapTpMessage, isWrappedIframeMessage } from './message.js';
 
-// Utilitous mapped types.
+// Utilitous generic types.
 
 type GuardType<TypeGuard> = TypeGuard extends (
   value: unknown,
@@ -18,11 +18,6 @@ enum EnvelopeLabel {
   CapTp = 'capTp',
 }
 
-type ContentMap = {
-  command: WrappedIframeMessage;
-  capTp: CapTpMessage;
-};
-
 // makeStreamEnvelopeKit requires an enum of labels but typescript
 // doesn't support enums as bounds on template parameters.
 //
@@ -32,127 +27,24 @@ type ContentMap = {
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 const envelopeLabels = Object.values(EnvelopeLabel);
 
-const { streamEnveloper, isStreamEnvelope } = makeStreamEnvelopeKit<
+const envelopeKit = makeStreamEnvelopeKit<
   typeof envelopeLabels,
-  ContentMap
+  {
+    command: WrappedIframeMessage;
+    capTp: CapTpMessage;
+  }
 >({
   command: isWrappedIframeMessage,
   capTp: isCapTpMessage,
 });
 
-export const wrapCommand = streamEnveloper.command.wrap;
-export const wrapCapTp = streamEnveloper.capTp.wrap;
-
-// Stream envelope handler.
-
-export type StreamEnvelope = GuardType<typeof isStreamEnvelope>;
-
-/**
- * A handler for automatically unwrapping stream envelopes and handling their content.
- */
-export type StreamEnvelopeHandler = {
-  /**
-   * Sniffs an unknown value for envelope labels, applying the label's handler
-   * if known, and applying the error handler if the label is not handled or if
-   * the content did not pass the envelope's type guard.
-   *
-   * @template Envelope - The type of the envelope.
-   * @param envelope - The envelope to handle.
-   * @returns The result of the handler.
-   */
-  handle: <Envelope extends StreamEnvelope>(
-    envelope: Envelope,
-  ) => Promise<unknown>;
-  /**
-   * The bag of async content handlers labeled with the {@link EnvelopeLabel} they handle.
-   */
-  contentHandlers: StreamEnvelopeContentHandlerBag;
-  /**
-   * The error handler for the stream envelope handler.
-   */
-  errorHandler: StreamEnvelopeErrorHandler;
-};
+const { streamEnveloper, makeStreamEnvelopeHandler } = envelopeKit;
 
-/**
- * A handler for a specific stream envelope label.
- */
-type StreamEnvelopeContentHandler<Label extends EnvelopeLabel> = (
-  content: ContentMap[Label],
-) => Promise<unknown>;
+export type StreamEnvelope = GuardType<typeof envelopeKit.isStreamEnvelope>;
+export type StreamEnvelopeHandler = ReturnType<
+  typeof makeStreamEnvelopeHandler
+>;
 
-/**
- * An object with {@link EnvelopeLabel} keys mapping to an appropriate {@link StreamEnvelopeContentHandler}.
- * If the stream envelope handler encounters a well-formed stream envelope without a defined handler,
- * the envelope will be passed to the {@link ErrorHandler}.
- */
-type StreamEnvelopeContentHandlerBag = {
-  [Label in EnvelopeLabel]?: (content: ContentMap[Label]) => Promise<unknown>;
-};
-
-/**
- * A handler for stream envelope parsing errors.
- * If the {@link StreamEnvelopeHandler} encounters an error while parsing the supplied value,
- * it will pass the reason and value to the error handler.
- */
-type StreamEnvelopeErrorHandler = (reason: string, value: unknown) => unknown;
-
-/**
- * The default handler for stream envelope parsing errors.
- *
- * @param reason - The reason for the error.
- * @param value - The value that caused the error.
- */
-const defaultStreamEnvelopeErrorHandler: StreamEnvelopeErrorHandler = (
-  reason,
-  value,
-) => {
-  throw new Error(`${reason} ${JSON.stringify(value, null, 2)}`);
-};
-
-/**
- * Makes a {@link StreamEnvelopeHandler} which handles an unknown value.
- *
- * If the supplied value is a valid envelope with a defined {@link StreamEnvelopeHandler},
- * the stream envelope handler will return whatever the defined handler returns.
- *
- * If the stream envelope handler is passed a well-formed stream envelope without a defined handler,
- * an explanation and the envelope will be passed to the supplied {@link StreamEnvelopeErrorHandler}.
- *
- * If the stream envelope handler encounters an error while parsing the supplied value,
- * it will pass the reason and value to the supplied {@link StreamEnvelopeErrorHandler}.
- *
- * If no error handler is supplied, the default error handling behavior is to throw.
- *
- * @param contentHandlers - A bag of async content handlers labeled with the {@link EnvelopeLabel} they handle.
- * @param errorHandler - An optional synchronous error handler.
- * @returns The stream envelope handler.
- */
-export const makeStreamEnvelopeHandler = (
-  contentHandlers: StreamEnvelopeContentHandlerBag,
-  errorHandler: StreamEnvelopeErrorHandler = defaultStreamEnvelopeErrorHandler,
-): StreamEnvelopeHandler => ({
-  handle: async (value: unknown) => {
-    if (!isStreamEnvelope(value)) {
-      return errorHandler(
-        'Stream envelope handler received unexpected value',
-        value,
-      );
-    }
-    const envelope = value;
-    const handler = contentHandlers[envelope.label] as
-      | StreamEnvelopeContentHandler<typeof envelope.label>
-      | undefined;
-    if (!handler) {
-      return errorHandler(
-        'Stream envelope handler received an envelope with known but unexpected label',
-        envelope,
-      );
-    }
-    const enveloper = streamEnveloper[envelope.label];
-    // The handler design makes typescript claustrophobic, but this is safe.
-    const content = enveloper.unwrap(envelope as never);
-    return await handler(content);
-  },
-  contentHandlers,
-  errorHandler,
-});
+export const wrapCommand = streamEnveloper.command.wrap;
+export const wrapCapTp = streamEnveloper.capTp.wrap;
+export { makeStreamEnvelopeHandler };
diff --git a/packages/streams/documents/make-stream-envelope-kit.md b/packages/streams/documents/make-stream-envelope-kit.md
index 63561b828..16c8a79ed 100644
--- a/packages/streams/documents/make-stream-envelope-kit.md
+++ b/packages/streams/documents/make-stream-envelope-kit.md
@@ -63,7 +63,9 @@ export const myStreamEnvelopeKit = makeStreamEnvelopeKit<
 });
 ```
 
-### Example use
+### Enveloper use
+
+The low level enveloping functionality is available via the included `streamEnveloper` and `isStreamEnvelope`.
 
 ```ts
 // Destructure your new envelope kit.
@@ -81,3 +83,44 @@ if (isStreamEnvelope(envelope)) {
   const content = streamEnveloper[envelope.label].unwrap(envelope);
 }
 ```
+
+### Handler use
+
+If you know in advance how you plan to handle with your envelopes, you can let a `StreamEnvelopeHandler` do the checking and unwrapping for you.
+
+```ts
+// Destructure the maker from the kit.
+const { makeStreamEnvelopeHandler } = myStreamEnvelopeKit;
+
+// Declare how you want your envelope labels handled.
+const streamEnvelopeHandler = makeStreamEnvelopeHandler(
+  {
+    // The content type is automatically inferred in the declaration.
+    foo: async (content) => {
+      await delay(content.a);
+      return content.b;
+    },
+    bar: async (content) => (content.c ? 'yes' : 'no'),
+  },
+  // The optional errorHandler can throw or return.
+  // If unspecified, the default behavior is to throw.
+  (reason, value) => {
+    if (reason.match(/unexpected value/u)) {
+      throw new Error(`[myStreamError] ${reason}`);
+    }
+    return ['[myStreamWarning]', reason, value];
+  },
+);
+
+// Read messages from an @ocap/streams Reader.
+for await (const newMessage of myStreamReader) {
+  // And handle the message.
+  await streamEnvelopeHandler
+    .handle(newMessage)
+    // If the errorHandler throws, you can catch it here.
+    .catch(console.error)
+    // Otherwise, the promise resolves to the value returned by
+    // its appropriate content handler, or by the errorHandler.
+    .then(console.log);
+}
+```
diff --git a/packages/streams/src/envelope-handler.test.ts b/packages/streams/src/envelope-handler.test.ts
new file mode 100644
index 000000000..beb0b5468
--- /dev/null
+++ b/packages/streams/src/envelope-handler.test.ts
@@ -0,0 +1,77 @@
+import { describe, expect, it } from 'vitest';
+
+import { makeStreamEnvelopeHandler } from './envelope-handler.js';
+import {
+  barContent,
+  fooContent,
+  isStreamEnvelope,
+  Label,
+  streamEnveloper,
+} from './envelope-test-fixtures.js';
+
+describe('StreamEnvelopeHandler', () => {
+  const testEnvelopeHandlers = {
+    foo: async () => Label.Foo,
+    bar: async () => Label.Bar,
+  };
+
+  const testErrorHandler = (problem: unknown): never => {
+    throw new Error(`TEST ${String(problem)}`);
+  };
+
+  it.each`
+    wrapper                     | content       | label
+    ${streamEnveloper.foo.wrap} | ${fooContent} | ${Label.Foo}
+    ${streamEnveloper.bar.wrap} | ${barContent} | ${Label.Bar}
+  `('handles valid StreamEnvelopes', async ({ wrapper, content, label }) => {
+    const handler = makeStreamEnvelopeHandler(
+      streamEnveloper,
+      isStreamEnvelope,
+      testEnvelopeHandlers,
+      testErrorHandler,
+    );
+    console.debug(wrapper(content));
+    expect(await handler.handle(wrapper(content))).toStrictEqual(label);
+  });
+
+  it('routes invalid envelopes to default error handler', async () => {
+    const handler = makeStreamEnvelopeHandler(
+      streamEnveloper,
+      isStreamEnvelope,
+      testEnvelopeHandlers,
+    );
+    await expect(
+      // @ts-expect-error label is intentionally unknown
+      handler.handle({ label: 'unknown', content: [] }),
+    ).rejects.toThrow(/^Stream envelope handler received unexpected value/u);
+  });
+
+  it('routes invalid envelopes to supplied error handler', async () => {
+    const handler = makeStreamEnvelopeHandler(
+      streamEnveloper,
+      isStreamEnvelope,
+      testEnvelopeHandlers,
+      testErrorHandler,
+    );
+    await expect(
+      // @ts-expect-error label is intentionally unknown
+      handler.handle({ label: 'unknown', content: [] }),
+    ).rejects.toThrow(
+      /^TEST Stream envelope handler received unexpected value/u,
+    );
+  });
+
+  it('routes valid stream envelopes with an unhandled label to the error handler', async () => {
+    const handler = makeStreamEnvelopeHandler(
+      streamEnveloper,
+      isStreamEnvelope,
+      { foo: testEnvelopeHandlers.foo },
+      testErrorHandler,
+    );
+    await expect(
+      handler.handle(streamEnveloper.bar.wrap(barContent)),
+    ).rejects.toThrow(
+      /^TEST Stream envelope handler received an envelope with known but unexpected label/u,
+    );
+  });
+});
diff --git a/packages/streams/src/envelope-handler.ts b/packages/streams/src/envelope-handler.ts
new file mode 100644
index 000000000..d838aed01
--- /dev/null
+++ b/packages/streams/src/envelope-handler.ts
@@ -0,0 +1,140 @@
+import type { StreamEnvelope } from './envelope.js';
+import type { StreamEnveloper } from './enveloper.js';
+import type { TypeMap } from './generics.js';
+
+/**
+ * A handler for automatically unwrapping stream envelopes and handling their content.
+ */
+export type StreamEnvelopeHandler<
+  Labels extends readonly string[],
+  ContentMap extends TypeMap<Labels[number]>,
+> = {
+  /**
+   * Checks an unknown value for envelope labels, applying the label's handler
+   * if known, and applying the error handler if the label is not handled or if
+   * the content did not pass the envelope's type guard.
+   *
+   * @template Envelope - The type of the envelope.
+   * @param envelope - The envelope to handle.
+   * @returns The result of the handler.
+   */
+  handle: <Envelope extends StreamEnvelope<Labels[number], ContentMap>>(
+    envelope: Envelope,
+  ) => Promise<unknown>;
+  /**
+   * The bag of async content handlers labeled with the {@link EnvelopeLabel} they handle.
+   */
+  contentHandlers: StreamEnvelopeContentHandlerBag<Labels, ContentMap>;
+  /**
+   * The error handler for the stream envelope handler.
+   */
+  errorHandler: StreamEnvelopeErrorHandler;
+};
+
+/**
+ * A handler for a specific stream envelope label.
+ */
+type StreamEnvelopeContentHandler<
+  EnvelopeLabel extends string,
+  ContentMap extends TypeMap<EnvelopeLabel>,
+  Label extends EnvelopeLabel,
+> = (content: ContentMap[Label]) => Promise<unknown>;
+
+/**
+ * An object with {@link EnvelopeLabel} keys mapping to an appropriate {@link StreamEnvelopeContentHandler}.
+ * If the stream envelope handler encounters a well-formed stream envelope without a defined handler,
+ * the envelope will be passed to the {@link ErrorHandler}.
+ */
+export type StreamEnvelopeContentHandlerBag<
+  Labels extends readonly string[],
+  ContentMap extends TypeMap<Labels[number]>,
+> = {
+  [Label in Labels[number]]?: (content: ContentMap[Label]) => Promise<unknown>;
+};
+
+/**
+ * A handler for stream envelope parsing errors.
+ * If the {@link StreamEnvelopeHandler} encounters an error while parsing the supplied value,
+ * it will pass the reason and value to the error handler.
+ */
+export type StreamEnvelopeErrorHandler = (
+  reason: string,
+  value: unknown,
+) => unknown;
+
+/**
+ * The default handler for stream envelope parsing errors.
+ *
+ * @param reason - The reason for the error.
+ * @param value - The value that caused the error.
+ */
+const defaultStreamEnvelopeErrorHandler: StreamEnvelopeErrorHandler = (
+  reason,
+  value,
+) => {
+  throw new Error(`${reason} ${JSON.stringify(value, null, 2)}`);
+};
+
+/**
+ * Makes a {@link StreamEnvelopeHandler} which handles an unknown value.
+ *
+ * If the supplied value is a valid envelope with a defined {@link StreamEnvelopeHandler},
+ * the stream envelope handler will return whatever the defined handler returns.
+ *
+ * If the stream envelope handler is passed a well-formed stream envelope without a defined handler,
+ * an explanation and the envelope will be passed to the supplied {@link StreamEnvelopeErrorHandler}.
+ *
+ * If the stream envelope handler encounters an error while parsing the supplied value,
+ * it will pass the reason and value to the supplied {@link StreamEnvelopeErrorHandler}.
+ *
+ * If no error handler is supplied, the default error handling behavior is to throw.
+ *
+ * @param streamEnveloper - A {@link StreamEnveloper} made with the same Labels.
+ * @param isStreamEnvelope - A type guard which identifies stream envelopes.
+ * @param contentHandlers - A bag of async content handlers labeled with the {@link EnvelopeLabel} they handle.
+ * @param errorHandler - An optional synchronous error handler.
+ * @returns The stream envelope handler.
+ */
+export const makeStreamEnvelopeHandler = <
+  Labels extends readonly string[],
+  ContentMap extends TypeMap<Labels[number]>,
+>(
+  streamEnveloper: StreamEnveloper<Labels, ContentMap>,
+  isStreamEnvelope: (
+    value: unknown,
+  ) => value is StreamEnvelope<Labels[number], ContentMap>,
+  contentHandlers: StreamEnvelopeContentHandlerBag<Labels, ContentMap>,
+  errorHandler: StreamEnvelopeErrorHandler = defaultStreamEnvelopeErrorHandler,
+): StreamEnvelopeHandler<Labels, ContentMap> => {
+  return {
+    handle: async (value: unknown) => {
+      if (!isStreamEnvelope(value)) {
+        return errorHandler(
+          'Stream envelope handler received unexpected value',
+          value,
+        );
+      }
+      const envelope = value;
+      const handler = contentHandlers[envelope.label] as
+        | StreamEnvelopeContentHandler<
+            Labels[number],
+            ContentMap,
+            typeof envelope.label
+          >
+        | undefined;
+      const enveloper = streamEnveloper[envelope.label];
+      if (!handler || !enveloper) {
+        console.debug(`handler: ${JSON.stringify(handler)}`);
+        console.debug(`enveloper: ${JSON.stringify(enveloper)}`);
+        return errorHandler(
+          'Stream envelope handler received an envelope with known but unexpected label',
+          envelope,
+        );
+      }
+      const content = enveloper.unwrap(envelope);
+      return await handler(content);
+    },
+    contentHandlers,
+    errorHandler,
+  };
+};
diff --git a/packages/streams/src/envelope-kit.test.ts b/packages/streams/src/envelope-kit.test.ts
index 6bdcd6700..bdfa80777 100644
--- a/packages/streams/src/envelope-kit.test.ts
+++ b/packages/streams/src/envelope-kit.test.ts
@@ -1,47 +1,27 @@
-import { isObject } from '@metamask/utils';
 import { describe, expect, it } from 'vitest';
 
 import { makeStreamEnvelopeKit } from './envelope-kit.js';
+import type { Bar, ContentMap, Foo, labels } from './envelope-test-fixtures.js';
+import {
+  inferNumber,
+  inferString,
+  makeStreamEnvelopeHandler,
+} from './envelope-test-fixtures.js';
 
 describe('makeStreamEnvelopeKit', () => {
-  type Foo = {
-    a: number;
-    b: string;
-  };
-  type Bar = {
-    c: boolean;
-  };
-  type ContentMap = {
-    foo: Foo;
-    bar: Bar;
-  };
-  enum Label {
-    Foo = 'foo',
-    Bar = 'bar',
-  }
-
-  // eslint-disable-next-line @typescript-eslint/no-unused-vars
-  const labels = Object.values(Label);
-
-  const { streamEnveloper, isStreamEnvelope } = makeStreamEnvelopeKit<
-    typeof labels,
-    ContentMap
-  >({
-    foo: (value: unknown): value is Foo =>
-      isObject(value) &&
-      typeof value.a === 'number' &&
-      typeof value.b === 'string',
-    bar: (value: unknown): value is Bar =>
-      isObject(value) && typeof value.c === 'boolean',
+  it.each`
+    property
+    ${'streamEnveloper'}
+    ${'isStreamEnvelope'}
+    ${'makeStreamEnvelopeHandler'}
+  `('has the expected property: $property', ({ property }) => {
+    const streamEnvelopeKit = makeStreamEnvelopeKit<typeof labels, ContentMap>({
+      foo: (value: unknown): value is Foo => true,
+      bar: (value: unknown): value is Bar => true,
+    });
+    expect(streamEnvelopeKit).toHaveProperty(property);
   });
 
-  const fooContent: Foo = { a: 0, b: 's' };
-  const barContent: Bar = { c: false };
-
-  const inferNumber = (value: number): number => value;
-  const inferString = (value: string): string => value;
-  const inferBoolean = (value: boolean): boolean => value;
-
   /* eslint-disable @typescript-eslint/no-unused-expressions */
   // eslint-disable-next-line vitest/expect-expect
   it('causes a typescript error when supplying typeguard keys not matching the label type', () => {
@@ -58,158 +38,15 @@ describe('makeStreamEnvelopeKit', () => {
   });
   /* eslint-enable @typescript-eslint/no-unused-expressions */
 
-  describe('enveloper', () => {
-    describe('check', () => {
-      it.each`
-        enveloper              | envelope
-        ${streamEnveloper.foo} | ${{ label: 'foo', content: fooContent }}
-        ${streamEnveloper.bar} | ${{ label: 'bar', content: barContent }}
-        ${streamEnveloper.bar} | ${{ label: 'bar', content: barContent, extra: 'value' }}
-      `(
-        'returns true for valid envelopes: $envelope',
-        ({ enveloper, envelope }) => {
-          expect(enveloper.check(envelope)).toBe(true);
-        },
-      );
-
-      it.each`
-        enveloper              | content
-        ${streamEnveloper.foo} | ${fooContent}
-        ${streamEnveloper.bar} | ${barContent}
-      `(
-        'returns true for content wrapped by its enveloper: $content',
-        ({ enveloper, content }) => {
-          expect(enveloper.check(enveloper.wrap(content))).toBe(true);
-        },
-      );
-
-      it.each`
-        enveloper              | value
-        ${streamEnveloper.foo} | ${null}
-        ${streamEnveloper.foo} | ${true}
-        ${streamEnveloper.foo} | ${[]}
-        ${streamEnveloper.foo} | ${{}}
-        ${streamEnveloper.foo} | ${fooContent}
-        ${streamEnveloper.foo} | ${{ id: '0xcafebeef' }}
-        ${streamEnveloper.foo} | ${{ label: 'foo', content: barContent }}
-        ${streamEnveloper.bar} | ${{ label: 'Bar', content: barContent }}
-      `(
-        'returns false for invalid envelopes: $value',
-        ({ enveloper, value }) => {
-          expect(enveloper.check(value)).toBe(false);
-        },
-      );
-
-      /* eslint-disable @typescript-eslint/no-unused-expressions */
-      // eslint-disable-next-line vitest/expect-expect
-      it('provides proper typescript inferences', () => {
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        const envelope: any = null;
-        // eslint-disable-next-line vitest/no-conditional-in-test
-        if (streamEnveloper.foo.check(envelope)) {
-          inferNumber(envelope.content.a);
-          // @ts-expect-error a is not a string
-          inferString(envelope.content.a);
-          // @ts-expect-error b is not a number
-          inferNumber(envelope.content.b);
-          inferString(envelope.content.b);
-          // @ts-expect-error c is not defined
-          envelope.content.c;
-          switch (envelope.label) {
-            case Label.Foo:
-              expect(envelope.label).toMatch(Label.Foo);
-              break;
-            // @ts-expect-error label is Label.Foo
-            case Label.Bar: // unreachable
-              // @ts-expect-error label is inferred to be never
-              expect(envelope.label.concat('')).toMatch(
-                'This test line should be unreachable.',
-              );
-              break;
-            default: // unreachable
-              // @ts-expect-error label is inferred to be never
-              expect(envelope.label.concat('')).toMatch(
-                'This test line should be unreachable.',
-              );
-          }
-        }
-
-        // eslint-disable-next-line vitest/no-conditional-in-test
-        if (streamEnveloper.bar.check(envelope)) {
-          // @ts-expect-error a is not defined
-          envelope.content.a;
-          // @ts-expect-error b is not defined
-          envelope.content.b;
-          inferBoolean(envelope.content.c);
-          switch (envelope.label) {
-            // @ts-expect-error label is Label.Bar
-            case Label.Foo: // unreachable
-              // @ts-expect-error label is inferred to be never
-              expect(envelope.label.concat('')).toMatch(
-                'This test line should be unreachable.',
-              );
-              break;
-            case Label.Bar:
-              expect(envelope.label).toMatch(Label.Bar);
-              break;
-            default: // unreachable
-              // @ts-expect-error label is inferred to be never
-              expect(envelope.label.concat('')).toMatch(
-                'This test line should be unreachable.',
-              );
-          }
-        }
-      });
-      /* eslint-enable @typescript-eslint/no-unused-expressions */
-    });
-
-    describe('wrap', () => {
-      it.each`
-        enveloper              | content
-        ${streamEnveloper.foo} | ${fooContent}
-        ${streamEnveloper.bar} | ${barContent}
-      `(
-        'is inverse to unwrap from the same enveloper: $enveloper',
-        ({ enveloper, content }) => {
-          expect(enveloper.unwrap(enveloper.wrap(content))).toStrictEqual(
-            content,
-          );
-        },
-      );
-
-      // eslint-disable-next-line vitest/expect-expect
-      it('provides proper typescript inferences', () => {
-        streamEnveloper.foo.wrap(fooContent);
-        // @ts-expect-error foo rejects barContent
-        streamEnveloper.foo.wrap(barContent);
-        // @ts-expect-error bar rejects fooContent
-        streamEnveloper.bar.wrap(fooContent);
-        streamEnveloper.bar.wrap(barContent);
-      });
-    });
-
-    describe('unwrap', () => {
-      it.each`
-        enveloper              | envelope
-        ${streamEnveloper.foo} | ${{ content: fooContent }}
-        ${streamEnveloper.foo} | ${{ label: Label.Bar, content: fooContent }}
-      `(
-        'throws if passed an envelope with the wrong label: $envelope',
-        ({ enveloper, envelope }) => {
-          expect(() => enveloper.unwrap(envelope)).toThrow(
-            /^Expected envelope labelled "foo" but got /u,
-          );
-        },
-      );
-
-      /* eslint-disable @typescript-eslint/no-unused-expressions */
-      // eslint-disable-next-line vitest/expect-expect
-      it('provides proper typescript inferences', () => {
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        const envelope: any = null;
-        try {
-          const content = streamEnveloper.foo.unwrap(envelope);
-
+  describe('makeStreamEnvelopeHandler', () => {
+    /* eslint-disable @typescript-eslint/no-unused-expressions */
+    // eslint-disable-next-line vitest/expect-expect
+    it('provides proper typescript inferences', () => {
+      // all label arguments are optional
+      makeStreamEnvelopeHandler({});
+      // bar is optional
+      makeStreamEnvelopeHandler({
+        foo: async (content) => {
           inferNumber(content.a);
           // @ts-expect-error a is not a string
           inferString(content.a);
@@ -217,117 +54,15 @@ describe('makeStreamEnvelopeKit', () => {
           inferNumber(content.b);
           inferString(content.b);
           // @ts-expect-error c is undefined
-          content.c;
-        } catch {
-          undefined;
-        }
-
-        try {
-          // @ts-expect-error envelope was already inferred to be Envelope<Label.Foo, Foo>
-          content = streamEnveloper.bar.unwrap(envelope);
-        } catch {
-          undefined;
-        }
-      });
-      /* eslint-enable @typescript-eslint/no-unused-expressions */
-    });
-
-    describe('label', () => {
-      it.each`
-        enveloper              | label
-        ${streamEnveloper.foo} | ${Label.Foo}
-        ${streamEnveloper.bar} | ${Label.Bar}
-      `('has the right label: $label', ({ enveloper, label }) => {
-        expect(enveloper.label).toBe(label);
+          value.content.c;
+        },
       });
-
-      /* eslint-disable @typescript-eslint/no-unused-expressions */
-      // eslint-disable-next-line vitest/expect-expect
-      it('provides proper typescript inferences', () => {
+      // keys not included in labels are forbidden
+      makeStreamEnvelopeHandler({
+        // @ts-expect-error the qux key is not included in labels
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        const fooEnveloper: any = streamEnveloper.foo;
-        const inferFooEnveloper = (
-          enveloper: typeof streamEnveloper.foo,
-        ): unknown => enveloper;
-        const inferBarEnveloper = (
-          enveloper: typeof streamEnveloper.bar,
-        ): unknown => enveloper;
-
-        type Enveloper = (typeof streamEnveloper)[keyof typeof streamEnveloper];
-        const ambiguousEnveloper = fooEnveloper as Enveloper;
-
-        switch (ambiguousEnveloper.label) {
-          case Label.Foo:
-            inferFooEnveloper(ambiguousEnveloper);
-            // @ts-expect-error label = Label.Foo implies ambiguousEnveloper is a FooEnveloper
-            inferBarEnveloper(ambiguousEnveloper);
-            break;
-          case Label.Bar:
-            // @ts-expect-error label = Label.Bar implies ambiguousEnveloper is a BarEnveloper
-            inferFooEnveloper(ambiguousEnveloper);
-            inferBarEnveloper(ambiguousEnveloper);
-            break;
-          default: // unreachable
-            // @ts-expect-error label options are exhausted
-            ambiguousEnveloper.label;
-        }
+        qux: async (content: any) => content,
       });
-      /* eslint-enable @typescript-eslint/no-unused-expressions */
-    });
-  });
-
-  describe('isStreamEnvelope', () => {
-    it.each`
-      value
-      ${streamEnveloper.foo.wrap(fooContent)}
-      ${streamEnveloper.bar.wrap(barContent)}
-    `('returns true for valid envelopes: $value', ({ value }) => {
-      expect(isStreamEnvelope(value)).toBe(true);
-    });
-
-    it.each`
-      value
-      ${null}
-      ${true}
-      ${[]}
-      ${{}}
-      ${fooContent}
-      ${{ id: '0x5012C312312' }}
-      ${streamEnveloper.foo.wrap(barContent as unknown as Foo)}
-    `('returns false for invalid values: $value', ({ value }) => {
-      expect(isStreamEnvelope(value)).toBe(false);
-    });
-
-    /* eslint-disable @typescript-eslint/no-unused-expressions */
-    // eslint-disable-next-line vitest/expect-expect
-    it('provides proper typescript inferences', () => {
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      const value: any = null;
-      // eslint-disable-next-line vitest/no-conditional-in-test
-      if (isStreamEnvelope(value)) {
-        switch (value.label) {
-          case Label.Foo:
-            inferNumber(value.content.a);
-            // @ts-expect-error a is not a string
-            inferString(value.content.a);
-            // @ts-expect-error b is not a number
-            inferNumber(value.content.b);
-            inferString(value.content.b);
-            // @ts-expect-error c is undefined
-            value.content.c;
-            break;
-          case Label.Bar:
-            // @ts-expect-error a is undefined
-            value.content.a;
-            // @ts-expect-error a is undefined
-            value.content.b;
-            inferBoolean(value.content.c);
-            break;
-          default: // unreachable
-            // @ts-expect-error label options are exhausted
-            value.label;
-        }
-      }
     });
     /* eslint-enable @typescript-eslint/no-unused-expressions */
   });
diff --git a/packages/streams/src/envelope-kit.ts b/packages/streams/src/envelope-kit.ts
index f9e8a0492..53e3d5cdb 100644
--- a/packages/streams/src/envelope-kit.ts
+++ b/packages/streams/src/envelope-kit.ts
@@ -1,130 +1,28 @@
-import { isObject } from '@metamask/utils';
-
-// Utilitous mapped types.
-
-/**
- * An object type mapping keys to `ValueType`.
- * A type which extends `TypeMap<SpecificKeys, unknown>` can map each key to a different type.
- */
-type TypeMap<Keys extends string, ValueType = unknown> = {
-  [key in Keys]: ValueType;
-};
-
-/**
- * Omit from `ObjectType` all keys without the specified `ValueType`.
- */
-type PickByValue<ObjectType, ValueType> = Pick<
-  ObjectType,
-  {
-    [K in keyof ObjectType]: ObjectType[K] extends ValueType ? K : never;
-  }[keyof ObjectType]
->;
-
-/**
- * The result type of calling `Object.entries` on an object of type `ObjectType`.
- *
- * WARNING: If an object is typed as `ObjectType` but has excess properties,
- * `Entries<typeof object>` will incorrectly omit the entries corresponding to the
- * excess properties. Ensure your assumptions about the object align with typescript's.
- * To be safe, use a type guard or only apply to objects you have declared.
- *
- * See https://www.typescriptlang.org/docs/handbook/2/objects.html#excess-property-checks
- * for a description of excess properties.
- */
-type Entries<ObjectType> = {
-  [K in keyof ObjectType]: [
-    keyof PickByValue<ObjectType, ObjectType[K]>,
-    ObjectType[K],
-  ];
-}[keyof ObjectType][];
-
-// Envelope types and type guards.
-
-type Envelope<Label extends string, Content> = {
-  label: Label;
-  content: Content;
-};
-
-type LabeledWith<Label extends string> = {
-  label: Label;
-  [key: string]: unknown;
-};
-
-const isLabeled = <Label extends string>(
-  value: unknown,
-  label?: Label,
-): value is LabeledWith<Label> =>
-  isObject(value) &&
-  typeof value.label !== 'undefined' &&
-  (label === undefined || value.label === label);
-
-type ContainerOf<Content> = {
-  content: Content;
-  [key: string]: unknown;
-};
-
-// Enveloper.
-
-type Enveloper<Label extends string, Content> = {
-  label: Label;
-  check: (value: unknown) => value is Envelope<Label, Content>;
-  wrap: (content: Content) => Envelope<Label, Content>;
-  unwrap: (envelope: Envelope<Label, Content>) => Content;
-};
-
-const makeEnveloper = <Label extends string, Content>(
-  label: Label,
-  isContent: (value: unknown) => value is Content,
-): Enveloper<Label, Content> => {
-  const hasLabel = (value: unknown): value is LabeledWith<Label> =>
-    isLabeled(value, label);
-  const hasContent = (value: unknown): value is ContainerOf<Content> =>
-    isObject(value) &&
-    typeof value.content !== 'undefined' &&
-    isContent(value.content);
-  return {
-    label,
-    check: (value: unknown): value is Envelope<Label, Content> =>
-      hasLabel(value) && hasContent(value),
-    wrap: (content: Content) =>
-      ({
-        label,
-        content,
-      } as Envelope<Label, Content>),
-    unwrap: (envelope: Envelope<Label, Content>): Content => {
-      if (!hasLabel(envelope)) {
-        throw new Error(
-          // @ts-expect-error The type of `envelope` is `never`, but this could happen at runtime.
-          // eslint-disable-next-line @typescript-eslint/restrict-template-expressions
-          `Expected envelope labelled "${label}" but got "${envelope.label}".`,
-        );
-      }
-      return envelope.content;
-    },
-  };
-};
-
-// Stream envelope kit.
-
-type StreamEnvelopeKitGuards<
+import type {
+  StreamEnvelopeContentHandlerBag,
+  StreamEnvelopeErrorHandler,
+  StreamEnvelopeHandler,
+} from './envelope-handler.js';
+import { makeStreamEnvelopeHandler as makeHandler } from './envelope-handler.js';
+import type { StreamEnvelope } from './envelope.js';
+import { isLabeled } from './envelope.js';
+import type {
+  Enveloper,
+  StreamEnveloper,
+  StreamEnveloperGuards,
+} from './enveloper.js';
+import { makeStreamEnveloper } from './enveloper.js';
+import type { TypeMap } from './generics.js';
+
+export type MakeStreamEnvelopeHandler<
   Labels extends readonly string[],
   ContentMap extends TypeMap<Labels[number]>,
-> = {
-  [K in Labels[number]]: (value: unknown) => value is ContentMap[K];
-};
-
-type StreamEnveloper<
-  Labels extends readonly string[],
-  ContentMap extends TypeMap<Labels[number]>,
-> = {
-  [K in Labels[number]]: Enveloper<K, ContentMap[K]>;
-};
-
-type StreamEnvelope<Label extends string, ContentMap extends TypeMap<Label>> = {
-  [K in Label]: Envelope<K, ContentMap[K]>;
-}[Label];
+> = (
+  contentHandlers: StreamEnvelopeContentHandlerBag<Labels, ContentMap>,
+  errorHandler?: StreamEnvelopeErrorHandler,
+) => StreamEnvelopeHandler<Labels, ContentMap>;
 
-type StreamEnvelopeKit<
+export type StreamEnvelopeKit<
   Labels extends readonly string[],
   ContentMap extends TypeMap<Labels[number]>,
 > = {
@@ -132,6 +30,7 @@ type StreamEnvelopeKit<
   isStreamEnvelope: (
     value: unknown,
   ) => value is StreamEnvelope<Labels[number], ContentMap>;
+  makeStreamEnvelopeHandler: MakeStreamEnvelopeHandler<Labels, ContentMap>;
 };
 
 /**
@@ -148,28 +47,49 @@ export const makeStreamEnvelopeKit = <
   Labels extends string[],
   ContentMap extends TypeMap<Labels[number]>,
 >(
-  guards: StreamEnvelopeKitGuards<Labels, ContentMap>,
+  guards: StreamEnveloperGuards<Labels, ContentMap>,
 ): StreamEnvelopeKit<Labels, ContentMap> => {
-  const entries = Object.entries(guards) as Entries<
-    StreamEnvelopeKitGuards<Labels, ContentMap>
-  >;
-  const streamEnveloper = Object.fromEntries(
-    entries.map(([label, isContent]) => [
-      label,
-      makeEnveloper(label, isContent),
-    ]),
-  );
+  const streamEnveloper = makeStreamEnveloper(guards);
+  const isStreamEnvelope = (
+    value: unknown,
+  ): value is StreamEnvelope<Labels[number], ContentMap> =>
+    isLabeled(value) &&
+    (
+      Object.values(streamEnveloper) as Enveloper<Labels[number], unknown>[]
+    ).some((enveloper) => enveloper.check(value));
+
+  /**
+   * Makes a {@link StreamEnvelopeHandler} which handles an unknown value.
+   *
+   * If the supplied value is a valid envelope with a defined {@link StreamEnvelopeHandler},
+   * the stream envelope handler will return whatever the defined handler returns.
+   *
+   * If the stream envelope handler is passed a well-formed stream envelope without a defined handler,
+   * an explanation and the envelope will be passed to the supplied {@link StreamEnvelopeErrorHandler}.
+   *
+   * If the stream envelope handler encounters an error while parsing the supplied value,
+   * it will pass the reason and value to the supplied {@link StreamEnvelopeErrorHandler}.
+   *
+   * If no error handler is supplied, the default error handling behavior is to throw.
+   *
+   * @param contentHandlers - A bag of async content handlers labeled with the {@link EnvelopeLabel} they handle.
+   * @param errorHandler - An optional synchronous error handler.
+   * @returns The stream envelope handler.
+   */
+  const makeStreamEnvelopeHandler = (
+    contentHandlers: StreamEnvelopeContentHandlerBag<Labels, ContentMap>,
+    errorHandler?: StreamEnvelopeErrorHandler,
+  ): StreamEnvelopeHandler<Labels, ContentMap> =>
+    makeHandler(
+      streamEnveloper,
+      isStreamEnvelope,
+      contentHandlers,
+      errorHandler,
+    );
+
   return {
-    streamEnveloper: streamEnveloper as unknown as StreamEnveloper<
-      Labels,
-      ContentMap
-    >,
-    isStreamEnvelope: (
-      value: unknown,
-    ): value is StreamEnvelope<Labels[number], ContentMap> =>
-      isLabeled(value) &&
-      Object.values(streamEnveloper).some((enveloper) =>
-        enveloper.check(value),
-      ),
+    streamEnveloper,
+    isStreamEnvelope,
+    makeStreamEnvelopeHandler,
   };
 };
diff --git a/packages/streams/src/envelope-test-fixtures.ts b/packages/streams/src/envelope-test-fixtures.ts
new file mode 100644
index 000000000..1c08a0248
--- /dev/null
+++ b/packages/streams/src/envelope-test-fixtures.ts
@@ -0,0 +1,39 @@
+import { isObject } from '@metamask/utils';
+
+import { makeStreamEnvelopeKit } from './envelope-kit.js';
+
+export type Foo = {
+  a: number;
+  b: string;
+};
+export type Bar = {
+  c: boolean;
+};
+export type ContentMap = {
+  foo: Foo;
+  bar: Bar;
+};
+export enum Label {
+  Foo = 'foo',
+  Bar = 'bar',
+}
+
+export const labels = Object.values(Label);
+
+export const { streamEnveloper, isStreamEnvelope, makeStreamEnvelopeHandler } =
+  makeStreamEnvelopeKit<typeof labels, ContentMap>({
+    foo: (value: unknown): value is Foo =>
+      isObject(value) &&
+      typeof value.a === 'number' &&
+      typeof value.b === 'string',
+    bar: (value: unknown): value is Bar =>
+      isObject(value) && typeof value.c === 'boolean',
+  });
+
+export const fooContent: Foo = { a: 0, b: 's' };
+export const barContent: Bar = { c: false };
+
+/* v8 ignore next 3: These are type assertions used in other tests. */
+export const inferNumber = (value: number): number => value;
+export const inferString = (value: string): string => value;
+export const inferBoolean = (value: boolean): boolean => value;
diff --git a/packages/streams/src/envelope.test.ts b/packages/streams/src/envelope.test.ts
new file mode 100644
index 000000000..2cc00da6d
--- /dev/null
+++ b/packages/streams/src/envelope.test.ts
@@ -0,0 +1,69 @@
+import { describe, expect, it } from 'vitest';
+
+import type { Foo } from './envelope-test-fixtures.js';
+import {
+  barContent,
+  fooContent,
+  inferBoolean,
+  inferNumber,
+  inferString,
+  isStreamEnvelope,
+  Label,
+  streamEnveloper,
+} from './envelope-test-fixtures.js';
+
+describe('isStreamEnvelope', () => {
+  it.each`
+    value
+    ${streamEnveloper.foo.wrap(fooContent)}
+    ${streamEnveloper.bar.wrap(barContent)}
+  `('returns true for valid envelopes: $value', ({ value }) => {
+    expect(isStreamEnvelope(value)).toBe(true);
+  });
+
+  it.each`
+    value
+    ${null}
+    ${true}
+    ${[]}
+    ${{}}
+    ${fooContent}
+    ${{ id: '0x5012C312312' }}
+    ${streamEnveloper.foo.wrap(barContent as unknown as Foo)}
+  `('returns false for invalid values: $value', ({ value }) => {
+    expect(isStreamEnvelope(value)).toBe(false);
+  });
+
+  /* eslint-disable @typescript-eslint/no-unused-expressions */
+  // eslint-disable-next-line vitest/expect-expect
+  it('provides proper typescript inferences', () => {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const value: any = null;
+    // eslint-disable-next-line vitest/no-conditional-in-test
+    if (isStreamEnvelope(value)) {
+      switch (value.label) {
+        case Label.Foo:
+          inferNumber(value.content.a);
+          // @ts-expect-error a is not a string
+          inferString(value.content.a);
+          // @ts-expect-error b is not a number
+          inferNumber(value.content.b);
+          inferString(value.content.b);
+          // @ts-expect-error c is undefined
+          value.content.c;
+          break;
+        case Label.Bar:
+          // @ts-expect-error a is undefined
+          value.content.a;
+          // @ts-expect-error a is undefined
+          value.content.b;
+          inferBoolean(value.content.c);
+          break;
+        default: // unreachable
+          // @ts-expect-error label options are exhausted
+          value.label;
+      }
+    }
+  });
+  /* eslint-enable @typescript-eslint/no-unused-expressions */
+});
diff --git a/packages/streams/src/envelope.ts b/packages/streams/src/envelope.ts
new file mode 100644
index 000000000..fa393074c
--- /dev/null
+++ b/packages/streams/src/envelope.ts
@@ -0,0 +1,35 @@
+// Envelope types and type guards.
+
+import { isObject } from '@metamask/utils';
+
+import type { TypeMap } from './generics.js';
+
+export type Envelope<Label extends string, Content> = {
+  label: Label;
+  content: Content;
+};
+
+export type LabeledWith<Label extends string> = {
+  label: Label;
+  [key: string]: unknown;
+};
+
+export const isLabeled = <Label extends string>(
+  value: unknown,
+  label?: Label,
+): value is LabeledWith<Label> =>
+  isObject(value) &&
+  typeof value.label !== 'undefined' &&
+  (label === undefined || value.label === label);
+
+export type ContainerOf<Content> = {
+  content: Content;
+  [key: string]: unknown;
+};
+
+export type StreamEnvelope<
+  Label extends string,
+  ContentMap extends TypeMap<Label>,
+> = {
+  [K in Label]: Envelope<K, ContentMap[K]>;
+}[Label];
diff --git a/packages/streams/src/enveloper.test.ts b/packages/streams/src/enveloper.test.ts
new file mode 100644
index 000000000..5fb064d2d
--- /dev/null
+++ b/packages/streams/src/enveloper.test.ts
@@ -0,0 +1,226 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  barContent,
+  fooContent,
+  inferBoolean,
+  inferNumber,
+  inferString,
+  Label,
+  streamEnveloper,
+} from './envelope-test-fixtures.js';
+
+describe('StreamEnveloper', () => {
+  describe('check', () => {
+    it.each`
+      enveloper              | envelope
+      ${streamEnveloper.foo} | ${{ label: 'foo', content: fooContent }}
+      ${streamEnveloper.bar} | ${{ label: 'bar', content: barContent }}
+      ${streamEnveloper.bar} | ${{ label: 'bar', content: barContent, extra: 'value' }}
+    `(
+      'returns true for valid envelopes: $envelope',
+      ({ enveloper, envelope }) => {
+        expect(enveloper.check(envelope)).toBe(true);
+      },
+    );
+
+    it.each`
+      enveloper              | content
+      ${streamEnveloper.foo} | ${fooContent}
+      ${streamEnveloper.bar} | ${barContent}
+    `(
+      'returns true for content wrapped by its enveloper: $content',
+      ({ enveloper, content }) => {
+        expect(enveloper.check(enveloper.wrap(content))).toBe(true);
+      },
+    );
+
+    it.each`
+      enveloper              | value
+      ${streamEnveloper.foo} | ${null}
+      ${streamEnveloper.foo} | ${true}
+      ${streamEnveloper.foo} | ${[]}
+      ${streamEnveloper.foo} | ${{}}
+      ${streamEnveloper.foo} | ${fooContent}
+      ${streamEnveloper.foo} | ${{ id: '0xcafebeef' }}
+      ${streamEnveloper.foo} | ${{ label: 'foo', content: barContent }}
+      ${streamEnveloper.bar} | ${{ label: 'Bar', content: barContent }}
+    `('returns false for invalid envelopes: $value', ({ enveloper, value }) => {
+      expect(enveloper.check(value)).toBe(false);
+    });
+
+    /* eslint-disable @typescript-eslint/no-unused-expressions */
+    // eslint-disable-next-line vitest/expect-expect
+    it('provides proper typescript inferences', () => {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const envelope: any = null;
+      // eslint-disable-next-line vitest/no-conditional-in-test
+      if (streamEnveloper.foo.check(envelope)) {
+        inferNumber(envelope.content.a);
+        // @ts-expect-error a is not a string
+        inferString(envelope.content.a);
+        // @ts-expect-error b is not a number
+        inferNumber(envelope.content.b);
+        inferString(envelope.content.b);
+        // @ts-expect-error c is not defined
+        envelope.content.c;
+        switch (envelope.label) {
+          case Label.Foo:
+            expect(envelope.label).toMatch(Label.Foo);
+            break;
+          // @ts-expect-error label is Label.Foo
+          case Label.Bar: // unreachable
+            // @ts-expect-error label is inferred to be never
+            expect(envelope.label.concat('')).toMatch(
+              'This test line should be unreachable.',
+            );
+            break;
+          default: // unreachable
+            // @ts-expect-error label is inferred to be never
+            expect(envelope.label.concat('')).toMatch(
+              'This test line should be unreachable.',
+            );
+        }
+      }
+
+      // eslint-disable-next-line vitest/no-conditional-in-test
+      if (streamEnveloper.bar.check(envelope)) {
+        // @ts-expect-error a is not defined
+        envelope.content.a;
+        // @ts-expect-error b is not defined
+        envelope.content.b;
+        inferBoolean(envelope.content.c);
+        switch (envelope.label) {
+          // @ts-expect-error label is Label.Bar
+          case Label.Foo: // unreachable
+            // @ts-expect-error label is inferred to be never
+            expect(envelope.label.concat('')).toMatch(
+              'This test line should be unreachable.',
+            );
+            break;
+          case Label.Bar:
+            expect(envelope.label).toMatch(Label.Bar);
+            break;
+          default: // unreachable
+            // @ts-expect-error label is inferred to be never
+            expect(envelope.label.concat('')).toMatch(
+              'This test line should be unreachable.',
+            );
+        }
+      }
+    });
+    /* eslint-enable @typescript-eslint/no-unused-expressions */
+  });
+
+  describe('wrap', () => {
+    it.each`
+      enveloper              | content
+      ${streamEnveloper.foo} | ${fooContent}
+      ${streamEnveloper.bar} | ${barContent}
+    `(
+      'is inverse to unwrap from the same enveloper: $enveloper',
+      ({ enveloper, content }) => {
+        expect(enveloper.unwrap(enveloper.wrap(content))).toStrictEqual(
+          content,
+        );
+      },
+    );
+
+    // eslint-disable-next-line vitest/expect-expect
+    it('provides proper typescript inferences', () => {
+      streamEnveloper.foo.wrap(fooContent);
+      // @ts-expect-error foo rejects barContent
+      streamEnveloper.foo.wrap(barContent);
+      // @ts-expect-error bar rejects fooContent
+      streamEnveloper.bar.wrap(fooContent);
+      streamEnveloper.bar.wrap(barContent);
+    });
+  });
+
+  describe('unwrap', () => {
+    it.each`
+      enveloper              | envelope
+      ${streamEnveloper.foo} | ${{ content: fooContent }}
+      ${streamEnveloper.foo} | ${{ label: Label.Bar, content: fooContent }}
+    `(
+      'throws if passed an envelope with the wrong label: $envelope',
+      ({ enveloper, envelope }) => {
+        expect(() => enveloper.unwrap(envelope)).toThrow(
+          /^Expected envelope labelled "foo" but got /u,
+        );
+      },
+    );
+
+    /* eslint-disable @typescript-eslint/no-unused-expressions */
+    // eslint-disable-next-line vitest/expect-expect
+    it('provides proper typescript inferences', () => {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const envelope: any = null;
+      try {
+        const content = streamEnveloper.foo.unwrap(envelope);
+
+        inferNumber(content.a);
+        // @ts-expect-error a is not a string
+        inferString(content.a);
+        // @ts-expect-error b is not a number
+        inferNumber(content.b);
+        inferString(content.b);
+        // @ts-expect-error c is undefined
+        content.c;
+      } catch {
+        undefined;
+      }
+
+      try {
+        // @ts-expect-error envelope was already inferred to be Envelope<Label.Foo, Foo>
+        content = streamEnveloper.bar.unwrap(envelope);
+      } catch {
+        undefined;
+      }
+    });
+    /* eslint-enable @typescript-eslint/no-unused-expressions */
+  });
+
+  describe('label', () => {
+    it.each`
+      enveloper              | label
+      ${streamEnveloper.foo} | ${Label.Foo}
+      ${streamEnveloper.bar} | ${Label.Bar}
+    `('has the right label: $label', ({ enveloper, label }) => {
+      expect(enveloper.label).toBe(label);
+    });
+
+    /* eslint-disable @typescript-eslint/no-unused-expressions */
+    // eslint-disable-next-line vitest/expect-expect
+    it('provides proper typescript inferences', () => {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const fooEnveloper: any = streamEnveloper.foo;
+      const inferFooEnveloper = (
+        enveloper: typeof streamEnveloper.foo,
+      ): unknown => enveloper;
+      const inferBarEnveloper = (
+        enveloper: typeof streamEnveloper.bar,
+      ): unknown => enveloper;
+
+      type Enveloper = (typeof streamEnveloper)[keyof typeof streamEnveloper];
+      const ambiguousEnveloper = fooEnveloper as Enveloper;
+
+      switch (ambiguousEnveloper.label) {
+        case Label.Foo:
+          inferFooEnveloper(ambiguousEnveloper);
+          // @ts-expect-error label = Label.Foo implies ambiguousEnveloper is a FooEnveloper
+          inferBarEnveloper(ambiguousEnveloper);
+          break;
+        case Label.Bar:
+          // @ts-expect-error label = Label.Bar implies ambiguousEnveloper is a BarEnveloper
+          inferFooEnveloper(ambiguousEnveloper);
+          inferBarEnveloper(ambiguousEnveloper);
+          break;
+        default: // unreachable
+          // @ts-expect-error label options are exhausted
+          ambiguousEnveloper.label;
+      }
+    });
+    /* eslint-enable @typescript-eslint/no-unused-expressions */
+  });
+});
diff --git a/packages/streams/src/enveloper.ts b/packages/streams/src/enveloper.ts
new file mode 100644
index 000000000..6c86439f6
--- /dev/null
+++ b/packages/streams/src/enveloper.ts
@@ -0,0 +1,80 @@
+// Enveloper.
+
+import { isObject } from '@metamask/utils';
+
+import type { ContainerOf, Envelope, LabeledWith } from './envelope.js';
+import { isLabeled } from './envelope.js';
+import type { Entries, TypeMap } from './generics.js';
+
+export type Enveloper<Label extends string, Content> = {
+  label: Label;
+  check: (value: unknown) => value is Envelope<Label, Content>;
+  wrap: (content: Content) => Envelope<Label, Content>;
+  unwrap: (envelope: Envelope<Label, Content>) => Content;
+};
+
+const makeEnveloper = <Label extends string, Content>(
+  label: Label,
+  isContent: (value: unknown) => value is Content,
+): Enveloper<Label, Content> => {
+  const hasLabel = (value: unknown): value is LabeledWith<Label> =>
+    isLabeled(value, label);
+  const hasContent = (value: unknown): value is ContainerOf<Content> =>
+    isObject(value) &&
+    typeof value.content !== 'undefined' &&
+    isContent(value.content);
+  return {
+    label,
+    check: (value: unknown): value is Envelope<Label, Content> =>
+      hasLabel(value) && hasContent(value),
+    wrap: (content: Content) =>
+      ({
+        label,
+        content,
+      } as Envelope<Label, Content>),
+    unwrap: (envelope: Envelope<Label, Content>): Content => {
+      if (!hasLabel(envelope)) {
+        throw new Error(
+          // @ts-expect-error The type of `envelope` is `never`, but this could happen at runtime.
+          // eslint-disable-next-line @typescript-eslint/restrict-template-expressions
+          `Expected envelope labelled "${label}" but got "${envelope.label}".`,
+        );
+      }
+      return envelope.content;
+    },
+  };
+};
+
+// Stream envelope kit.
+
+export type StreamEnveloperGuards<
+  Labels extends readonly string[],
+  ContentMap extends TypeMap<Labels[number]>,
+> = {
+  [K in Labels[number]]: (value: unknown) => value is ContentMap[K];
+};
+
+export type StreamEnveloper<
+  Labels extends readonly string[],
+  ContentMap extends TypeMap<Labels[number]>,
+> = {
+  [K in Labels[number]]: Enveloper<K, ContentMap[K]>;
+};
+
+export const makeStreamEnveloper = <
+  Labels extends readonly string[],
+  ContentMap extends TypeMap<Labels[number]>,
+>(
+  guards: StreamEnveloperGuards<Labels, ContentMap>,
+): StreamEnveloper<Labels, ContentMap> => {
+  const entries = Object.entries(guards) as Entries<
+    StreamEnveloperGuards<Labels, ContentMap>
+  >;
+  const streamEnveloper = Object.fromEntries(
+    entries.map(([label, isContent]) => [
+      label,
+      makeEnveloper(label, isContent),
+    ]),
+  );
+  return streamEnveloper as unknown as StreamEnveloper<Labels, ContentMap>;
+};
diff --git a/packages/streams/src/generics.ts b/packages/streams/src/generics.ts
new file mode 100644
index 000000000..c4cfc1755
--- /dev/null
+++ b/packages/streams/src/generics.ts
@@ -0,0 +1,37 @@
+// Utilitous generic types.
+
+/**
+ * An object type mapping keys to `ValueType`.
+ * A type which extends `TypeMap<SpecificKeys, unknown>` can map each key to a different type.
+ */
+export type TypeMap<Keys extends string, ValueType = unknown> = {
+  [key in Keys]: ValueType;
+};
+
+/**
+ * Omit from `ObjectType` all keys without the specified `ValueType`.
+ */
+type PickByValue<ObjectType, ValueType> = Pick<
+  ObjectType,
+  {
+    [K in keyof ObjectType]: ObjectType[K] extends ValueType ? K : never;
+  }[keyof ObjectType]
+>;
+
+/**
+ * The result type of calling `Object.entries` on an object of type `ObjectType`.
+ *
+ * WARNING: If an object is typed as `ObjectType` but has excess properties,
+ * `Entries<typeof object>` will incorrectly omit the entries corresponding to the
+ * excess properties. Ensure your assumptions about the object align with typescript's.
+ * To be safe, use a type guard or only apply to objects you have declared.
+ *
+ * See https://www.typescriptlang.org/docs/handbook/2/objects.html#excess-property-checks
+ * for a description of excess properties.
+ */
+export type Entries<ObjectType> = {
+  [K in keyof ObjectType]: [
+    keyof PickByValue<ObjectType, ObjectType[K]>,
+    ObjectType[K],
+  ];
+}[keyof ObjectType][];
diff --git a/packages/streams/src/index.ts b/packages/streams/src/index.ts
index 22114e38e..7ddd045fa 100644
--- a/packages/streams/src/index.ts
+++ b/packages/streams/src/index.ts
@@ -8,4 +8,11 @@ export {
   MessagePortReader,
   MessagePortWriter,
 } from './streams.js';
-export { makeStreamEnvelopeKit } from './envelope-kit.js';
+export {
+  makeStreamEnvelopeKit,
+  type StreamEnvelopeKit,
+  type MakeStreamEnvelopeHandler,
+} from './envelope-kit.js';
+export type { StreamEnvelopeHandler } from './envelope-handler.js';
+export type { StreamEnveloper } from './enveloper.js';
+export type { Envelope, StreamEnvelope } from './envelope.js';

From 65e0d12a4124e9acf9f8c97c27dc1c7826254083 Mon Sep 17 00:00:00 2001
From: grypez <143971198+grypez@users.noreply.github.com>
Date: Tue, 17 Sep 2024 13:18:04 -0400
Subject: [PATCH 18/22] docs(streams): Reduce instruction details.

Co-authored-by: Erik Marks <25517051+rekmarks@users.noreply.github.com>
---
 packages/streams/documents/make-stream-envelope-kit.md | 6 ++----
 1 file changed, 2 insertions(+), 4 deletions(-)

diff --git a/packages/streams/documents/make-stream-envelope-kit.md b/packages/streams/documents/make-stream-envelope-kit.md
index 16c8a79ed..2fd579d73 100644
--- a/packages/streams/documents/make-stream-envelope-kit.md
+++ b/packages/streams/documents/make-stream-envelope-kit.md
@@ -19,14 +19,12 @@ Due to a [typescript limitation](https://github.com/microsoft/TypeScript/issues/
 ```ts
 import { makeStreamEnvelopeKit } from '@ocap/streams';
 
-// Import or declare the content types.
-import type { FooContent } from './foo.js';
-/*
+// Declare the content types.
 type FooContent = {
   a: number;
   b: string;
 };
-*/
+
 type BarContent = {
   c: boolean;
 };

From e95ae0020e22cb203aa398f115129d53705f644e Mon Sep 17 00:00:00 2001
From: grypez <143971198+grypez@users.noreply.github.com>
Date: Tue, 17 Sep 2024 13:19:04 -0400
Subject: [PATCH 19/22] refactor(extension): Assign capTp handler instead of
 remaking.

Co-authored-by: Erik Marks <25517051+rekmarks@users.noreply.github.com>
---
 packages/extension/src/iframe-manager.ts | 14 ++++----------
 1 file changed, 4 insertions(+), 10 deletions(-)

diff --git a/packages/extension/src/iframe-manager.ts b/packages/extension/src/iframe-manager.ts
index d1cd1b4e8..a61397fea 100644
--- a/packages/extension/src/iframe-manager.ts
+++ b/packages/extension/src/iframe-manager.ts
@@ -188,16 +188,10 @@ export class IframeManager {
     });
 
     vat.capTp = ctp;
-    vat.streamEnvelopeHandler = makeStreamEnvelopeHandler(
-      {
-        ...vat.streamEnvelopeHandler.contentHandlers,
-        capTp: async (content) => {
-          console.log('CapTP from vat', JSON.stringify(content, null, 2));
-          ctp.dispatch(content);
-        },
-      },
-      vat.streamEnvelopeHandler.errorHandler,
-    );
+    vat.streamEnvelopeHandler.contentHandlers.capTp = async (content) => {
+      console.log('CapTP from vat', JSON.stringify(content, null, 2));
+      ctp.dispatch(content);
+    };
 
     return this.sendMessage(id, { type: Command.CapTpInit, data: null });
   }

From cb925b89acf4b85211e2f4726a624eaf263732b1 Mon Sep 17 00:00:00 2001
From: grypez <143971198+grypez@users.noreply.github.com>
Date: Tue, 17 Sep 2024 12:59:58 -0500
Subject: [PATCH 20/22] refactor(streams): Move generics.ts into utils/.

---
 packages/streams/src/envelope-handler.ts     | 2 +-
 packages/streams/src/envelope-kit.ts         | 2 +-
 packages/streams/src/envelope.ts             | 2 +-
 packages/streams/src/enveloper.ts            | 2 +-
 packages/streams/src/{ => utils}/generics.ts | 0
 5 files changed, 4 insertions(+), 4 deletions(-)
 rename packages/streams/src/{ => utils}/generics.ts (100%)

diff --git a/packages/streams/src/envelope-handler.ts b/packages/streams/src/envelope-handler.ts
index d838aed01..b873b3a59 100644
--- a/packages/streams/src/envelope-handler.ts
+++ b/packages/streams/src/envelope-handler.ts
@@ -1,6 +1,6 @@
 import type { StreamEnvelope } from './envelope.js';
 import type { StreamEnveloper } from './enveloper.js';
-import type { TypeMap } from './generics.js';
+import type { TypeMap } from './utils/generics.js';
 
 /**
  * A handler for automatically unwrapping stream envelopes and handling their content.
diff --git a/packages/streams/src/envelope-kit.ts b/packages/streams/src/envelope-kit.ts
index 53e3d5cdb..ad6dc0d5a 100644
--- a/packages/streams/src/envelope-kit.ts
+++ b/packages/streams/src/envelope-kit.ts
@@ -12,7 +12,7 @@ import type {
   StreamEnveloperGuards,
 } from './enveloper.js';
 import { makeStreamEnveloper } from './enveloper.js';
-import type { TypeMap } from './generics.js';
+import type { TypeMap } from './utils/generics.js';
 
 export type MakeStreamEnvelopeHandler<
   Labels extends readonly string[],
diff --git a/packages/streams/src/envelope.ts b/packages/streams/src/envelope.ts
index fa393074c..5a53f4f2f 100644
--- a/packages/streams/src/envelope.ts
+++ b/packages/streams/src/envelope.ts
@@ -2,7 +2,7 @@
 
 import { isObject } from '@metamask/utils';
 
-import type { TypeMap } from './generics.js';
+import type { TypeMap } from './utils/generics.js';
 
 export type Envelope<Label extends string, Content> = {
   label: Label;
diff --git a/packages/streams/src/enveloper.ts b/packages/streams/src/enveloper.ts
index 6c86439f6..42c08b119 100644
--- a/packages/streams/src/enveloper.ts
+++ b/packages/streams/src/enveloper.ts
@@ -4,7 +4,7 @@ import { isObject } from '@metamask/utils';
 
 import type { ContainerOf, Envelope, LabeledWith } from './envelope.js';
 import { isLabeled } from './envelope.js';
-import type { Entries, TypeMap } from './generics.js';
+import type { Entries, TypeMap } from './utils/generics.js';
 
 export type Enveloper<Label extends string, Content> = {
   label: Label;
diff --git a/packages/streams/src/generics.ts b/packages/streams/src/utils/generics.ts
similarity index 100%
rename from packages/streams/src/generics.ts
rename to packages/streams/src/utils/generics.ts

From e2d44abe0d87b9774165d80e82a659a95331f97a Mon Sep 17 00:00:00 2001
From: grypez <143971198+grypez@users.noreply.github.com>
Date: Tue, 17 Sep 2024 13:04:51 -0500
Subject: [PATCH 21/22] tests(streams): Simplify never type assertions.

---
 packages/streams/src/enveloper.test.ts | 38 ++++++++------------------
 1 file changed, 12 insertions(+), 26 deletions(-)

diff --git a/packages/streams/src/enveloper.test.ts b/packages/streams/src/enveloper.test.ts
index 5fb064d2d..01f313981 100644
--- a/packages/streams/src/enveloper.test.ts
+++ b/packages/streams/src/enveloper.test.ts
@@ -1,14 +1,5 @@
 import { describe, expect, it } from 'vitest';
-
-import {
-  barContent,
-  fooContent,
-  inferBoolean,
-  inferNumber,
-  inferString,
-  Label,
-  streamEnveloper,
-} from './envelope-test-fixtures.js';
+import { barContent, fooContent, inferBoolean, inferNumber, inferString, Label, streamEnveloper } from './envelope-test-fixtures.js';
 
 describe('StreamEnveloper', () => {
   describe('check', () => {
@@ -45,9 +36,12 @@ describe('StreamEnveloper', () => {
       ${streamEnveloper.foo} | ${{ id: '0xcafebeef' }}
       ${streamEnveloper.foo} | ${{ label: 'foo', content: barContent }}
       ${streamEnveloper.bar} | ${{ label: 'Bar', content: barContent }}
-    `('returns false for invalid envelopes: $value', ({ enveloper, value }) => {
-      expect(enveloper.check(value)).toBe(false);
-    });
+    `(
+      'returns false for invalid envelopes: $value',
+      ({ enveloper, value }) => {
+        expect(enveloper.check(value)).toBe(false);
+      },
+    );
 
     /* eslint-disable @typescript-eslint/no-unused-expressions */
     // eslint-disable-next-line vitest/expect-expect
@@ -71,15 +65,11 @@ describe('StreamEnveloper', () => {
           // @ts-expect-error label is Label.Foo
           case Label.Bar: // unreachable
             // @ts-expect-error label is inferred to be never
-            expect(envelope.label.concat('')).toMatch(
-              'This test line should be unreachable.',
-            );
+            envelope.label.length;
             break;
           default: // unreachable
             // @ts-expect-error label is inferred to be never
-            expect(envelope.label.concat('')).toMatch(
-              'This test line should be unreachable.',
-            );
+            envelope.label.length;
         }
       }
 
@@ -94,18 +84,14 @@ describe('StreamEnveloper', () => {
           // @ts-expect-error label is Label.Bar
           case Label.Foo: // unreachable
             // @ts-expect-error label is inferred to be never
-            expect(envelope.label.concat('')).toMatch(
-              'This test line should be unreachable.',
-            );
+            envelope.label.length;
             break;
           case Label.Bar:
             expect(envelope.label).toMatch(Label.Bar);
             break;
           default: // unreachable
             // @ts-expect-error label is inferred to be never
-            expect(envelope.label.concat('')).toMatch(
-              'This test line should be unreachable.',
-            );
+            envelope.label.length;
         }
       }
     });
@@ -223,4 +209,4 @@ describe('StreamEnveloper', () => {
     });
     /* eslint-enable @typescript-eslint/no-unused-expressions */
   });
-});
+});
\ No newline at end of file

From 6f7c0dce8c6b204c8604eb193e6d83010375242b Mon Sep 17 00:00:00 2001
From: grypez <143971198+grypez@users.noreply.github.com>
Date: Tue, 17 Sep 2024 13:39:49 -0500
Subject: [PATCH 22/22] test(streams): Refactor type tests.

---
 .eslintrc.cjs                                 |  16 ++
 packages/streams/src/envelope-handler.test.ts |   2 +-
 packages/streams/src/envelope-kit.test.ts     |  57 +----
 .../streams/src/envelope-kit.types.test.ts    | 212 ++++++++++++++++++
 packages/streams/src/envelope.test.ts         |  41 +---
 packages/streams/src/enveloper.test.ts        | 143 +-----------
 .../envelope-kit-fixtures.ts}                 |   7 +-
 packages/streams/tsconfig.json                |   2 +-
 8 files changed, 249 insertions(+), 231 deletions(-)
 create mode 100644 packages/streams/src/envelope-kit.types.test.ts
 rename packages/streams/{src/envelope-test-fixtures.ts => test/envelope-kit-fixtures.ts} (70%)

diff --git a/.eslintrc.cjs b/.eslintrc.cjs
index 79a36054f..5f5e0b8aa 100644
--- a/.eslintrc.cjs
+++ b/.eslintrc.cjs
@@ -165,5 +165,21 @@ module.exports = {
         ],
       },
     },
+
+    {
+      // Rules for writing tests of typescript inference behavior.
+      // Mostly inherits rules for `files: ['**/*.test.{ts,js}']`.
+      files: ['**/*.types.test.ts'],
+      rules: {
+        // An explicit any type is useful for testing type narrowing.
+        '@typescript-eslint/no-explicit-any': 'off',
+        // Merely expressing an object is enough to invoke type inference.
+        '@typescript-eslint/no-unused-expressions': 'off',
+        // These sorts of tests don't generally need to run, only compile.
+        'vitest/expect-expect': 'off',
+        // Useful for `if (typeGuard(object))` statements.
+        'vitest/no-conditional-in-test': 'off',
+      },
+    },
   ],
 };
diff --git a/packages/streams/src/envelope-handler.test.ts b/packages/streams/src/envelope-handler.test.ts
index beb0b5468..2269153b4 100644
--- a/packages/streams/src/envelope-handler.test.ts
+++ b/packages/streams/src/envelope-handler.test.ts
@@ -7,7 +7,7 @@ import {
   isStreamEnvelope,
   Label,
   streamEnveloper,
-} from './envelope-test-fixtures.js';
+} from '../test/envelope-kit-fixtures.js';
 
 describe('StreamEnvelopeHandler', () => {
   const testEnvelopeHandlers = {
diff --git a/packages/streams/src/envelope-kit.test.ts b/packages/streams/src/envelope-kit.test.ts
index bdfa80777..f4eee1019 100644
--- a/packages/streams/src/envelope-kit.test.ts
+++ b/packages/streams/src/envelope-kit.test.ts
@@ -1,12 +1,12 @@
 import { describe, expect, it } from 'vitest';
 
 import { makeStreamEnvelopeKit } from './envelope-kit.js';
-import type { Bar, ContentMap, Foo, labels } from './envelope-test-fixtures.js';
-import {
-  inferNumber,
-  inferString,
-  makeStreamEnvelopeHandler,
-} from './envelope-test-fixtures.js';
+import type {
+  Bar,
+  ContentMap,
+  Foo,
+  labels,
+} from '../test/envelope-kit-fixtures.js';
 
 describe('makeStreamEnvelopeKit', () => {
   it.each`
@@ -21,49 +21,4 @@ describe('makeStreamEnvelopeKit', () => {
     });
     expect(streamEnvelopeKit).toHaveProperty(property);
   });
-
-  /* eslint-disable @typescript-eslint/no-unused-expressions */
-  // eslint-disable-next-line vitest/expect-expect
-  it('causes a typescript error when supplying typeguard keys not matching the label type', () => {
-    // @ts-expect-error the bar key is missing
-    makeStreamEnvelopeKit<typeof labels, ContentMap>({
-      foo: (value: unknown): value is Foo => true,
-    });
-    makeStreamEnvelopeKit<typeof labels, ContentMap>({
-      foo: (value: unknown): value is Foo => true,
-      bar: (value: unknown): value is Bar => true,
-      // @ts-expect-error the qux key is not included in labels
-      qux: (value: unknown): value is 'qux' => false,
-    });
-  });
-  /* eslint-enable @typescript-eslint/no-unused-expressions */
-
-  describe('makeStreamEnvelopeHandler', () => {
-    /* eslint-disable @typescript-eslint/no-unused-expressions */
-    // eslint-disable-next-line vitest/expect-expect
-    it('provides proper typescript inferences', () => {
-      // all label arguments are optional
-      makeStreamEnvelopeHandler({});
-      // bar is optional
-      makeStreamEnvelopeHandler({
-        foo: async (content) => {
-          inferNumber(content.a);
-          // @ts-expect-error a is not a string
-          inferString(content.a);
-          // @ts-expect-error b is not a number
-          inferNumber(content.b);
-          inferString(content.b);
-          // @ts-expect-error c is undefined
-          value.content.c;
-        },
-      });
-      // keys not included in labels are forbidden
-      makeStreamEnvelopeHandler({
-        // @ts-expect-error the qux key is not included in labels
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        qux: async (content: any) => content,
-      });
-    });
-    /* eslint-enable @typescript-eslint/no-unused-expressions */
-  });
 });
diff --git a/packages/streams/src/envelope-kit.types.test.ts b/packages/streams/src/envelope-kit.types.test.ts
new file mode 100644
index 000000000..9823ec9f2
--- /dev/null
+++ b/packages/streams/src/envelope-kit.types.test.ts
@@ -0,0 +1,212 @@
+import { describe, expect, it } from 'vitest';
+
+import { makeStreamEnvelopeKit } from './envelope-kit.js';
+import type {
+  Bar,
+  ContentMap,
+  Foo,
+  labels,
+} from '../test/envelope-kit-fixtures.js';
+import {
+  makeStreamEnvelopeHandler as kitMakeStreamEnvelopeHandler,
+  isStreamEnvelope,
+  Label,
+  streamEnveloper,
+  fooContent,
+  barContent,
+} from '../test/envelope-kit-fixtures.js';
+
+const inferNumber = (value: number): number => value;
+const inferString = (value: string): string => value;
+const inferBoolean = (value: boolean): boolean => value;
+
+describe('makeStreamEnvelopeKit', () => {
+  it('causes a typescript error when supplying typeguard keys not matching the label type', () => {
+    // @ts-expect-error the bar key is missing
+    makeStreamEnvelopeKit<typeof labels, ContentMap>({
+      foo: (value: unknown): value is Foo => true,
+    });
+    makeStreamEnvelopeKit<typeof labels, ContentMap>({
+      foo: (value: unknown): value is Foo => true,
+      bar: (value: unknown): value is Bar => true,
+      // @ts-expect-error the qux key is not included in labels
+      qux: (value: unknown): value is 'qux' => false,
+    });
+  });
+
+  describe('kitted makeStreamEnvelopeHandler', () => {
+    it('provides proper typescript inferences', () => {
+      // all label arguments are optional
+      kitMakeStreamEnvelopeHandler({});
+      // bar is optional
+      kitMakeStreamEnvelopeHandler({
+        foo: async (content) => {
+          inferNumber(content.a);
+          // @ts-expect-error a is not a string
+          inferString(content.a);
+          // @ts-expect-error b is not a number
+          inferNumber(content.b);
+          inferString(content.b);
+          // @ts-expect-error c is undefined
+          value.content.c;
+        },
+      });
+      // keys not included in labels are forbidden
+      kitMakeStreamEnvelopeHandler({
+        // @ts-expect-error the qux key is not included in labels
+        qux: async (content: any) => content,
+      });
+    });
+  });
+});
+
+describe('isStreamEnvelope', () => {
+  it('provides proper typescript inferences', () => {
+    const value: any = null;
+    if (isStreamEnvelope(value)) {
+      switch (value.label) {
+        case Label.Foo:
+          inferNumber(value.content.a);
+          // @ts-expect-error a is not a string
+          inferString(value.content.a);
+          // @ts-expect-error b is not a number
+          inferNumber(value.content.b);
+          inferString(value.content.b);
+          // @ts-expect-error c is undefined
+          value.content.c;
+          break;
+        case Label.Bar:
+          // @ts-expect-error a is undefined
+          value.content.a;
+          // @ts-expect-error a is undefined
+          value.content.b;
+          inferBoolean(value.content.c);
+          break;
+        default: // unreachable
+          // @ts-expect-error label options are exhausted
+          value.label;
+      }
+    }
+  });
+});
+
+describe('StreamEnveloper', () => {
+  describe('check', () => {
+    it('provides proper typescript inferences', () => {
+      const envelope: any = null;
+      if (streamEnveloper.foo.check(envelope)) {
+        inferNumber(envelope.content.a);
+        // @ts-expect-error a is not a string
+        inferString(envelope.content.a);
+        // @ts-expect-error b is not a number
+        inferNumber(envelope.content.b);
+        inferString(envelope.content.b);
+        // @ts-expect-error c is not defined
+        envelope.content.c;
+        switch (envelope.label) {
+          case Label.Foo:
+            expect(envelope.label).toMatch(Label.Foo);
+            break;
+          // @ts-expect-error label is Label.Foo
+          case Label.Bar: // unreachable
+            // @ts-expect-error label is inferred to be never
+            envelope.label.length;
+            break;
+          default: // unreachable
+            // @ts-expect-error label is inferred to be never
+            envelope.label.length;
+        }
+      }
+
+      if (streamEnveloper.bar.check(envelope)) {
+        // @ts-expect-error a is not defined
+        envelope.content.a;
+        // @ts-expect-error b is not defined
+        envelope.content.b;
+        inferBoolean(envelope.content.c);
+        switch (envelope.label) {
+          // @ts-expect-error label is Label.Bar
+          case Label.Foo: // unreachable
+            // @ts-expect-error label is inferred to be never
+            envelope.label.length;
+            break;
+          case Label.Bar:
+            expect(envelope.label).toMatch(Label.Bar);
+            break;
+          default: // unreachable
+            // @ts-expect-error label is inferred to be never
+            envelope.label.length;
+        }
+      }
+    });
+  });
+
+  describe('wrap', () => {
+    it('provides proper typescript inferences', () => {
+      streamEnveloper.foo.wrap(fooContent);
+      // @ts-expect-error foo rejects barContent
+      streamEnveloper.foo.wrap(barContent);
+      // @ts-expect-error bar rejects fooContent
+      streamEnveloper.bar.wrap(fooContent);
+      streamEnveloper.bar.wrap(barContent);
+    });
+  });
+
+  describe('unwrap', () => {
+    it('provides proper typescript inferences', () => {
+      const envelope: any = null;
+      try {
+        const content = streamEnveloper.foo.unwrap(envelope);
+
+        inferNumber(content.a);
+        // @ts-expect-error a is not a string
+        inferString(content.a);
+        // @ts-expect-error b is not a number
+        inferNumber(content.b);
+        inferString(content.b);
+        // @ts-expect-error c is undefined
+        content.c;
+      } catch {
+        undefined;
+      }
+
+      try {
+        // @ts-expect-error envelope was already inferred to be Envelope<Label.Foo, Foo>
+        content = streamEnveloper.bar.unwrap(envelope);
+      } catch {
+        undefined;
+      }
+    });
+  });
+
+  describe('label', () => {
+    it('provides proper typescript inferences', () => {
+      const fooEnveloper: any = streamEnveloper.foo;
+      const inferFooEnveloper = (
+        enveloper: typeof streamEnveloper.foo,
+      ): unknown => enveloper;
+      const inferBarEnveloper = (
+        enveloper: typeof streamEnveloper.bar,
+      ): unknown => enveloper;
+
+      type Enveloper = (typeof streamEnveloper)[keyof typeof streamEnveloper];
+      const ambiguousEnveloper = fooEnveloper as Enveloper;
+
+      switch (ambiguousEnveloper.label) {
+        case Label.Foo:
+          inferFooEnveloper(ambiguousEnveloper);
+          // @ts-expect-error label = Label.Foo implies ambiguousEnveloper is a FooEnveloper
+          inferBarEnveloper(ambiguousEnveloper);
+          break;
+        case Label.Bar:
+          // @ts-expect-error label = Label.Bar implies ambiguousEnveloper is a BarEnveloper
+          inferFooEnveloper(ambiguousEnveloper);
+          inferBarEnveloper(ambiguousEnveloper);
+          break;
+        default: // unreachable
+          // @ts-expect-error label options are exhausted
+          ambiguousEnveloper.label;
+      }
+    });
+  });
+});
diff --git a/packages/streams/src/envelope.test.ts b/packages/streams/src/envelope.test.ts
index 2cc00da6d..a7ef53db7 100644
--- a/packages/streams/src/envelope.test.ts
+++ b/packages/streams/src/envelope.test.ts
@@ -1,16 +1,12 @@
 import { describe, expect, it } from 'vitest';
 
-import type { Foo } from './envelope-test-fixtures.js';
+import type { Foo } from '../test/envelope-kit-fixtures.js';
 import {
   barContent,
   fooContent,
-  inferBoolean,
-  inferNumber,
-  inferString,
   isStreamEnvelope,
-  Label,
   streamEnveloper,
-} from './envelope-test-fixtures.js';
+} from '../test/envelope-kit-fixtures.js';
 
 describe('isStreamEnvelope', () => {
   it.each`
@@ -33,37 +29,4 @@ describe('isStreamEnvelope', () => {
   `('returns false for invalid values: $value', ({ value }) => {
     expect(isStreamEnvelope(value)).toBe(false);
   });
-
-  /* eslint-disable @typescript-eslint/no-unused-expressions */
-  // eslint-disable-next-line vitest/expect-expect
-  it('provides proper typescript inferences', () => {
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const value: any = null;
-    // eslint-disable-next-line vitest/no-conditional-in-test
-    if (isStreamEnvelope(value)) {
-      switch (value.label) {
-        case Label.Foo:
-          inferNumber(value.content.a);
-          // @ts-expect-error a is not a string
-          inferString(value.content.a);
-          // @ts-expect-error b is not a number
-          inferNumber(value.content.b);
-          inferString(value.content.b);
-          // @ts-expect-error c is undefined
-          value.content.c;
-          break;
-        case Label.Bar:
-          // @ts-expect-error a is undefined
-          value.content.a;
-          // @ts-expect-error a is undefined
-          value.content.b;
-          inferBoolean(value.content.c);
-          break;
-        default: // unreachable
-          // @ts-expect-error label options are exhausted
-          value.label;
-      }
-    }
-  });
-  /* eslint-enable @typescript-eslint/no-unused-expressions */
 });
diff --git a/packages/streams/src/enveloper.test.ts b/packages/streams/src/enveloper.test.ts
index 01f313981..e7aac5925 100644
--- a/packages/streams/src/enveloper.test.ts
+++ b/packages/streams/src/enveloper.test.ts
@@ -1,5 +1,11 @@
 import { describe, expect, it } from 'vitest';
-import { barContent, fooContent, inferBoolean, inferNumber, inferString, Label, streamEnveloper } from './envelope-test-fixtures.js';
+
+import {
+  barContent,
+  fooContent,
+  Label,
+  streamEnveloper,
+} from '../test/envelope-kit-fixtures.js';
 
 describe('StreamEnveloper', () => {
   describe('check', () => {
@@ -36,66 +42,9 @@ describe('StreamEnveloper', () => {
       ${streamEnveloper.foo} | ${{ id: '0xcafebeef' }}
       ${streamEnveloper.foo} | ${{ label: 'foo', content: barContent }}
       ${streamEnveloper.bar} | ${{ label: 'Bar', content: barContent }}
-    `(
-      'returns false for invalid envelopes: $value',
-      ({ enveloper, value }) => {
-        expect(enveloper.check(value)).toBe(false);
-      },
-    );
-
-    /* eslint-disable @typescript-eslint/no-unused-expressions */
-    // eslint-disable-next-line vitest/expect-expect
-    it('provides proper typescript inferences', () => {
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      const envelope: any = null;
-      // eslint-disable-next-line vitest/no-conditional-in-test
-      if (streamEnveloper.foo.check(envelope)) {
-        inferNumber(envelope.content.a);
-        // @ts-expect-error a is not a string
-        inferString(envelope.content.a);
-        // @ts-expect-error b is not a number
-        inferNumber(envelope.content.b);
-        inferString(envelope.content.b);
-        // @ts-expect-error c is not defined
-        envelope.content.c;
-        switch (envelope.label) {
-          case Label.Foo:
-            expect(envelope.label).toMatch(Label.Foo);
-            break;
-          // @ts-expect-error label is Label.Foo
-          case Label.Bar: // unreachable
-            // @ts-expect-error label is inferred to be never
-            envelope.label.length;
-            break;
-          default: // unreachable
-            // @ts-expect-error label is inferred to be never
-            envelope.label.length;
-        }
-      }
-
-      // eslint-disable-next-line vitest/no-conditional-in-test
-      if (streamEnveloper.bar.check(envelope)) {
-        // @ts-expect-error a is not defined
-        envelope.content.a;
-        // @ts-expect-error b is not defined
-        envelope.content.b;
-        inferBoolean(envelope.content.c);
-        switch (envelope.label) {
-          // @ts-expect-error label is Label.Bar
-          case Label.Foo: // unreachable
-            // @ts-expect-error label is inferred to be never
-            envelope.label.length;
-            break;
-          case Label.Bar:
-            expect(envelope.label).toMatch(Label.Bar);
-            break;
-          default: // unreachable
-            // @ts-expect-error label is inferred to be never
-            envelope.label.length;
-        }
-      }
+    `('returns false for invalid envelopes: $value', ({ enveloper, value }) => {
+      expect(enveloper.check(value)).toBe(false);
     });
-    /* eslint-enable @typescript-eslint/no-unused-expressions */
   });
 
   describe('wrap', () => {
@@ -111,16 +60,6 @@ describe('StreamEnveloper', () => {
         );
       },
     );
-
-    // eslint-disable-next-line vitest/expect-expect
-    it('provides proper typescript inferences', () => {
-      streamEnveloper.foo.wrap(fooContent);
-      // @ts-expect-error foo rejects barContent
-      streamEnveloper.foo.wrap(barContent);
-      // @ts-expect-error bar rejects fooContent
-      streamEnveloper.bar.wrap(fooContent);
-      streamEnveloper.bar.wrap(barContent);
-    });
   });
 
   describe('unwrap', () => {
@@ -136,35 +75,6 @@ describe('StreamEnveloper', () => {
         );
       },
     );
-
-    /* eslint-disable @typescript-eslint/no-unused-expressions */
-    // eslint-disable-next-line vitest/expect-expect
-    it('provides proper typescript inferences', () => {
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      const envelope: any = null;
-      try {
-        const content = streamEnveloper.foo.unwrap(envelope);
-
-        inferNumber(content.a);
-        // @ts-expect-error a is not a string
-        inferString(content.a);
-        // @ts-expect-error b is not a number
-        inferNumber(content.b);
-        inferString(content.b);
-        // @ts-expect-error c is undefined
-        content.c;
-      } catch {
-        undefined;
-      }
-
-      try {
-        // @ts-expect-error envelope was already inferred to be Envelope<Label.Foo, Foo>
-        content = streamEnveloper.bar.unwrap(envelope);
-      } catch {
-        undefined;
-      }
-    });
-    /* eslint-enable @typescript-eslint/no-unused-expressions */
   });
 
   describe('label', () => {
@@ -175,38 +85,5 @@ describe('StreamEnveloper', () => {
     `('has the right label: $label', ({ enveloper, label }) => {
       expect(enveloper.label).toBe(label);
     });
-
-    /* eslint-disable @typescript-eslint/no-unused-expressions */
-    // eslint-disable-next-line vitest/expect-expect
-    it('provides proper typescript inferences', () => {
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      const fooEnveloper: any = streamEnveloper.foo;
-      const inferFooEnveloper = (
-        enveloper: typeof streamEnveloper.foo,
-      ): unknown => enveloper;
-      const inferBarEnveloper = (
-        enveloper: typeof streamEnveloper.bar,
-      ): unknown => enveloper;
-
-      type Enveloper = (typeof streamEnveloper)[keyof typeof streamEnveloper];
-      const ambiguousEnveloper = fooEnveloper as Enveloper;
-
-      switch (ambiguousEnveloper.label) {
-        case Label.Foo:
-          inferFooEnveloper(ambiguousEnveloper);
-          // @ts-expect-error label = Label.Foo implies ambiguousEnveloper is a FooEnveloper
-          inferBarEnveloper(ambiguousEnveloper);
-          break;
-        case Label.Bar:
-          // @ts-expect-error label = Label.Bar implies ambiguousEnveloper is a BarEnveloper
-          inferFooEnveloper(ambiguousEnveloper);
-          inferBarEnveloper(ambiguousEnveloper);
-          break;
-        default: // unreachable
-          // @ts-expect-error label options are exhausted
-          ambiguousEnveloper.label;
-      }
-    });
-    /* eslint-enable @typescript-eslint/no-unused-expressions */
   });
-});
\ No newline at end of file
+});
diff --git a/packages/streams/src/envelope-test-fixtures.ts b/packages/streams/test/envelope-kit-fixtures.ts
similarity index 70%
rename from packages/streams/src/envelope-test-fixtures.ts
rename to packages/streams/test/envelope-kit-fixtures.ts
index 1c08a0248..0fb26d796 100644
--- a/packages/streams/src/envelope-test-fixtures.ts
+++ b/packages/streams/test/envelope-kit-fixtures.ts
@@ -1,6 +1,6 @@
 import { isObject } from '@metamask/utils';
 
-import { makeStreamEnvelopeKit } from './envelope-kit.js';
+import { makeStreamEnvelopeKit } from '../src/envelope-kit.js';
 
 export type Foo = {
   a: number;
@@ -32,8 +32,3 @@ export const { streamEnveloper, isStreamEnvelope, makeStreamEnvelopeHandler } =
 
 export const fooContent: Foo = { a: 0, b: 's' };
 export const barContent: Bar = { c: false };
-
-/* v8 ignore next 3: These are type assertions used in other tests. */
-export const inferNumber = (value: number): number => value;
-export const inferString = (value: string): string => value;
-export const inferBoolean = (value: boolean): boolean => value;
diff --git a/packages/streams/tsconfig.json b/packages/streams/tsconfig.json
index 85b667185..54f52c3be 100644
--- a/packages/streams/tsconfig.json
+++ b/packages/streams/tsconfig.json
@@ -6,5 +6,5 @@
     "types": ["ses", "vitest", "vitest/jsdom"]
   },
   "references": [{ "path": "../test-utils" }],
-  "include": ["./src"]
+  "include": ["./src", "test/envelope-kit-fixtures.ts"]
 }