@robota-sdk/agent-transport-ws 3.0.0-beta.78 → 3.0.0-beta.81

package/src/__tests__/ws-transport-auth.test.ts

@@ -0,0 +1,220 @@
+import { createTestInteractiveSession } from '@robota-sdk/agent-interface-session/testing';
+
+import { WebSocket } from 'ws';
+import { describe, it, expect, vi, afterEach } from 'vitest';
+
+import { WsTransport } from '../ws-transport-configurable.js';
+
+import type { IInteractiveSession } from '@robota-sdk/agent-interface-session';
+
+/**
+ * GUI-002 TC-03 — required loopback auth token. A configured token MUST be presented (query param or
+ * `Sec-WebSocket-Protocol` subprotocol) or the socket is closed BEFORE any session data.
+ *
+ * SEC-001 — secure by default: when NO token is configured, the transport AUTO-MINTS one (`resolvedToken`),
+ * so an unauthenticated connection is rejected; `{ open: true }` is the discouraged opt-out. Plus
+ * defense-in-depth: the WS upgrade rejects a non-loopback `Host` (DNS rebinding) and a non-allowed browser
+ * `Origin` at the handshake.
+ */
+
+function mockSession(): IInteractiveSession {
+  return Object.assign(createTestInteractiveSession(), {
+    getMessages: vi.fn().mockReturnValue([{ role: 'user', content: 'hi' }]),
+    getExecutionWorkspaceSnapshot: vi.fn().mockReturnValue({ entries: [] }),
+    on: vi.fn(),
+    off: vi.fn(),
+    submit: vi.fn(),
+    abort: vi.fn(),
+    cancelQueue: vi.fn(),
+    executeCommand: vi.fn(),
+    resolvePermission: vi.fn(),
+    resolveAsk: vi.fn(),
+  });
+}
+
+const started: WsTransport[] = [];
+
+interface IStartConfig {
+  token?: string;
+  open?: boolean;
+  /** SEC-008: required alongside `open` — the transport refuses an opt-out nobody explained. */
+  openReason?: string;
+  allowedHosts?: readonly string[];
+  allowedOrigins?: readonly string[];
+}
+
+/** Start a transport and return its port + the resolved token (auto-minted when none was configured). */
+async function startOn(config: IStartConfig = {}): Promise<{ port: number; token?: string }> {
+  // Use a high, unlikely-occupied base port; retry covers rare collisions.
+  const port = 17000 + Math.floor((started.length + 1) * 7);
+  const t = new WsTransport({ port, maxRetries: 30, ...config });
+  t.attach(mockSession());
+  await t.start();
+  started.push(t);
+  return { port, token: t.resolvedToken };
+}
+
+afterEach(async () => {
+  while (started.length) await started.pop()!.stop();
+});
+
+/**
+ * Connect and resolve with the outcome: `'messages'` if a `messages` frame arrives first, or `'closed'`
+ * with the close code if the socket closes before any frame. 1.5s guard so a hang fails loudly.
+ */
+function probe(
+  port: number,
+  opts: { token?: string; subprotocol?: string; headers?: Record<string, string> } = {},
+): Promise<string> {
+  const url = `ws://127.0.0.1:${port}${opts.token ? `?token=${encodeURIComponent(opts.token)}` : ''}`;
+  const wsOpts = opts.headers ? { headers: opts.headers } : {};
+  const ws = opts.subprotocol
+    ? new WebSocket(url, opts.subprotocol, wsOpts)
+    : new WebSocket(url, wsOpts);
+  return new Promise<string>((resolve) => {
+    const done = (v: string): void => {
+      try {
+        ws.close();
+      } catch {
+        /* already closing */
+      }
+      resolve(v);
+    };
+    const timer = setTimeout(() => done('timeout'), 1500);
+    ws.on('message', (data) => {
+      const msg = JSON.parse(String(data)) as { type: string };
+      if (msg.type === 'messages') {
+        clearTimeout(timer);
+        done('messages');
+      }
+    });
+    ws.on('close', (code) => {
+      clearTimeout(timer);
+      done(`closed:${code}`);
+    });
+    ws.on('error', () => {
+      clearTimeout(timer);
+      done('closed:error');
+    });
+  });
+}
+
+describe('WsTransport loopback auth (GUI-002 TC-03)', () => {
+  it('attributes submissions with the trusted server-side surface driver id', async () => {
+    const port = 17650;
+    const submit = vi.fn().mockResolvedValue(undefined);
+    const session = Object.assign(mockSession(), { submit });
+    const transport = new WsTransport({
+      port,
+      maxRetries: 30,
+      open: true,
+      openReason: 'surface-attribution regression test',
+      driverId: 'app',
+      surface: 'desktop-app',
+    });
+    transport.attach(session);
+    await transport.start();
+    started.push(transport);
+    const ws = new WebSocket(`ws://127.0.0.1:${transport.boundPort}`);
+    await new Promise<void>((resolve, reject) => {
+      ws.on('open', resolve);
+      ws.on('error', reject);
+    });
+
+    ws.send(JSON.stringify({ type: 'submit', prompt: 'attribute me' }));
+    await vi.waitFor(() => expect(submit).toHaveBeenCalled());
+
+    expect(submit).toHaveBeenCalledWith('attribute me', undefined, undefined, {
+      driverId: 'app',
+      surface: 'desktop-app',
+    });
+    const closed = new Promise<void>((resolve) => ws.once('close', () => resolve()));
+    ws.close();
+    await closed;
+  });
+
+  it('accepts a connection presenting the correct token via query param', async () => {
+    const { port } = await startOn({ token: 'secret-nonce' });
+    expect(await probe(port, { token: 'secret-nonce' })).toBe('messages');
+  });
+
+  it('accepts the correct token via Sec-WebSocket-Protocol subprotocol', async () => {
+    const { port } = await startOn({ token: 'secret-nonce' });
+    expect(await probe(port, { subprotocol: 'secret-nonce' })).toBe('messages');
+  });
+
+  it('rejects a MISSING token before any session data is emitted', async () => {
+    const { port } = await startOn({ token: 'secret-nonce' });
+    expect(await probe(port)).toBe('closed:1008'); // never 'messages'
+  });
+
+  it('rejects a WRONG token before any session data is emitted', async () => {
+    const { port } = await startOn({ token: 'secret-nonce' });
+    expect(await probe(port, { token: 'not-the-nonce' })).toBe('closed:1008');
+  });
+
+  // ── SEC-001 ────────────────────────────────────────────────────────────────
+  it('TC-01: NO token configured AUTO-MINTS one — unauthenticated rejected, minted token works', async () => {
+    const { port, token } = await startOn({}); // secure by default
+    expect(token).toBeTruthy();
+    expect(await probe(port)).toBe('closed:1008');
+    expect(await probe(port, { token })).toBe('messages');
+  });
+
+  it('TC-05: the discouraged `open` opt-out restores unauthenticated behavior', async () => {
+    const { port, token } = await startOn({
+      open: true,
+      openReason: 'SEC-008: the discouraged opt-out is the SUBJECT of this case',
+    });
+    expect(token).toBeUndefined();
+    expect(await probe(port)).toBe('messages');
+  });
+
+  it('TC-02: rejects a non-loopback Host at the upgrade (DNS-rebinding defense)', async () => {
+    const { port, token } = await startOn({ token: 'secret-nonce' });
+    expect(await probe(port, { token, headers: { host: 'evil.example.com' } })).not.toBe(
+      'messages',
+    );
+  });
+
+  it('TC-02: accepts a loopback Host on a port-agnostic match', async () => {
+    const { port, token } = await startOn({ token: 'secret-nonce' });
+    expect(await probe(port, { token, headers: { host: `localhost:${port}` } })).toBe('messages');
+  });
+
+  it('TC-03: rejects a non-allowed browser Origin at the upgrade', async () => {
+    const { port, token } = await startOn({ token: 'secret-nonce' });
+    expect(await probe(port, { token, headers: { origin: 'https://evil.example.com' } })).not.toBe(
+      'messages',
+    );
+  });
+
+  it('TC-03: accepts a configured app Origin', async () => {
+    const { port, token } = await startOn({
+      token: 'secret-nonce',
+      allowedOrigins: ['https://app.example.com'],
+    });
+    expect(await probe(port, { token, headers: { origin: 'https://app.example.com' } })).toBe(
+      'messages',
+    );
+  });
+});
+
+describe('SEC-008: `open` takes a written reason here too', () => {
+  // The first version filled a reason in for any caller that omitted one, which made WS the ONE
+  // transport where `{ open: true }` alone was accepted — HTTP and WebRTC both refuse it. Review
+  // found that: a reason invented on the caller's behalf reads, to the next person, as a decision
+  // somebody made, and the whole point of requiring it is that nobody can produce one by accident.
+  it('refuses an opt-out with no reason', () => {
+    expect(() => new WsTransport({ port: 17999, open: true })).toThrow(/openReason/);
+  });
+
+  it('accepts one that says why', () => {
+    // Without this the fix would be "refuse every open transport", which is not the decision — an
+    // open transport is legitimate, it just has to be chosen out loud.
+    expect(
+      () =>
+        new WsTransport({ port: 17999, open: true, openReason: 'loopback only — no remote peer' }),
+    ).not.toThrow();
+  });
+});

package/src/__tests__/ws-transport-lifecycle.test.ts

@@ -0,0 +1,135 @@
+import { createServer } from 'node:net';
+
+import { runTransportLifecycleConformance } from '@robota-sdk/agent-interface-transport/testing';
+import { createTestInteractiveSession } from '@robota-sdk/agent-interface-session/testing';
+
+import { WebSocket } from 'ws';
+import { describe, it, expect, expectTypeOf, vi, afterEach } from 'vitest';
+
+import { WsTransport } from '../ws-transport-configurable.js';
+
+import type { IConfigurableTransport } from '@robota-sdk/agent-interface-transport';
+import type { IInteractiveSession } from '@robota-sdk/agent-interface-session';
+import type { IProtocolSession } from '@robota-sdk/agent-transport';
+
+/**
+ * ARCH-004 RUNTIME-13 — `stop()` must resolve even with a client still connected.
+ *
+ * Before the fix, `stop()` did `wss.close(cb)`, whose callback fires only after every client socket is gone,
+ * so a live client made `stop()` hang forever. The fix sends a close frame to each client and terminates any
+ * survivor at a 5s deadline, so the server-close callback always resolves.
+ */
+
+function mockSession(): IInteractiveSession {
+  return Object.assign(createTestInteractiveSession(), {
+    getMessages: vi.fn().mockReturnValue([]),
+    getExecutionWorkspaceSnapshot: vi.fn().mockReturnValue({ entries: [] }),
+    on: vi.fn(),
+    off: vi.fn(),
+    submit: vi.fn(),
+    abort: vi.fn(),
+    cancelQueue: vi.fn(),
+  });
+}
+
+const started: WsTransport[] = [];
+afterEach(async () => {
+  while (started.length) await started.pop()!.stop();
+});
+
+describe('WsTransport lifecycle (ARCH-004 RUNTIME-13)', () => {
+  it('accepts only the protocol session roles required by the carrier', () => {
+    const transport = new WsTransport({
+      open: true,
+      openReason: 'type compatibility test',
+    });
+    expectTypeOf(transport).toMatchTypeOf<IConfigurableTransport<IProtocolSession>>();
+    expectTypeOf(transport.attach).toEqualTypeOf<(session: IProtocolSession) => void>();
+  });
+
+  it('stop() resolves promptly with a client still connected (previously hung forever)', async () => {
+    const t = new WsTransport({
+      port: 17800,
+      maxRetries: 40,
+      open: true,
+      openReason: 'SEC-008: this case is about the stop() lifecycle, not admission',
+    });
+    t.attach(mockSession());
+    await t.start();
+    started.push(t);
+    const port = t.boundPort;
+
+    const ws = new WebSocket(`ws://127.0.0.1:${port}`);
+    await new Promise<void>((resolve, reject) => {
+      ws.on('open', () => resolve());
+      ws.on('error', reject);
+    });
+
+    const startedAt = Date.now();
+    await t.stop(); // must not hang — the whole test would time out if it did
+    const elapsed = Date.now() - startedAt;
+
+    // A well-behaved client closes on the 1001 frame, so stop() resolves well under the 5s terminate deadline.
+    expect(elapsed).toBeLessThan(4500);
+    started.pop(); // already stopped
+    try {
+      ws.terminate();
+    } catch {
+      /* already closed */
+    }
+  });
+
+  it('can retry start after a bind failure without an intervening stop', async () => {
+    const blocker = createServer();
+    await new Promise<void>((resolve, reject) => {
+      blocker.once('error', reject);
+      blocker.listen(0, '127.0.0.1', resolve);
+    });
+    const address = blocker.address();
+    if (!address || typeof address === 'string') throw new Error('Expected a TCP address.');
+
+    const transport = new WsTransport({
+      port: address.port,
+      maxRetries: 0,
+      open: true,
+      openReason: 'bind failure lifecycle regression',
+    });
+    transport.attach(mockSession());
+    let blockerOpen = true;
+    try {
+      await expect(transport.start()).rejects.toMatchObject({ code: 'EADDRINUSE' });
+      await new Promise<void>((resolve, reject) =>
+        blocker.close((error) => (error ? reject(error) : resolve())),
+      );
+      blockerOpen = false;
+
+      await expect(transport.start()).resolves.toBeUndefined();
+      started.push(transport);
+      expect(transport.boundPort).toBe(address.port);
+    } finally {
+      if (blockerOpen) {
+        await new Promise<void>((resolve) => blocker.close(() => resolve()));
+      }
+    }
+  });
+
+  it('invokes the shared lifecycle conformance suite', async () => {
+    await runTransportLifecycleConformance({
+      subjectId: '@robota-sdk/agent-transport-ws#WsTransport',
+      kind: 'service',
+      createAdapter: () =>
+        new WsTransport({
+          port: 0,
+          open: true,
+          openReason: 'ARCH-011 lifecycle conformance',
+        }),
+      createSession: mockSession,
+      assertReady: (transport) => {
+        if (transport.boundPort === undefined) throw new Error('WS endpoint not bound');
+      },
+      assertStopped: (transport) => {
+        if (transport.boundPort !== undefined) throw new Error('WS endpoint still bound');
+      },
+    });
+  });
+});

package/src/__tests__/ws-transport.test.ts

@@ -1,9 +1,14 @@
-import { describe, it, expect, vi } from 'vitest';
+import { runTransportLifecycleConformance } from '@robota-sdk/agent-interface-transport/testing';
+import { createTestInteractiveSession } from '@robota-sdk/agent-interface-session/testing';
+
+import { describe, it, expect, expectTypeOf, vi } from 'vitest';
 import { createWsTransport } from '../ws-transport.js';
-import type { IInteractiveSession } from '@robota-sdk/agent-interface-transport';
+import type { ITransportAdapter } from '@robota-sdk/agent-interface-transport';
+import type { IInteractiveSession } from '@robota-sdk/agent-interface-session';
+import type { IProtocolSession } from '@robota-sdk/agent-transport';
 
 function createMockSession(): IInteractiveSession {
-  return {
+  return Object.assign(createTestInteractiveSession(), {
     submit: vi.fn(),
     abort: vi.fn(),
     cancelQueue: vi.fn(),
@@ -17,10 +22,16 @@ function createMockSession(): IInteractiveSession {
     listCommands: vi.fn().mockReturnValue([]),
     on: vi.fn(),
     off: vi.fn(),
-  } as unknown as IInteractiveSession;
+  });
 }
 
 describe('createWsTransport', () => {
+  it('accepts only the protocol session roles required by the carrier', () => {
+    const transport = createWsTransport({ send: vi.fn() });
+    expectTypeOf(transport).toMatchTypeOf<ITransportAdapter<IProtocolSession>>();
+    expectTypeOf(transport.attach).toEqualTypeOf<(session: IProtocolSession) => void>();
+  });
+
   it('returns an adapter with name "ws"', () => {
     const transport = createWsTransport({ send: vi.fn() });
     expect(transport.name).toBe('ws');
@@ -28,7 +39,10 @@ describe('createWsTransport', () => {
 
   it('throws if start() is called without attach()', async () => {
     const transport = createWsTransport({ send: vi.fn() });
-    await expect(transport.start()).rejects.toThrow('No session attached');
+    await expect(transport.start()).rejects.toMatchObject({
+      name: 'TransportLifecycleError',
+      code: 'not-attached',
+    });
   });
 
   it('onMessage is null before start()', () => {
@@ -50,4 +64,54 @@ describe('createWsTransport', () => {
     await transport.stop();
     expect(transport.onMessage).toBeNull();
   });
+
+  it('isolates an outbound failure, cleans subscriptions, and reports to the carrier owner', async () => {
+    const handlers = new Map<string, (value: unknown) => void>();
+    const session = createTestInteractiveSession({
+      on: ((event: string, handler: (value: unknown) => void) => {
+        handlers.set(event, handler);
+      }) as IInteractiveSession['on'],
+      off: ((event: string) => {
+        handlers.delete(event);
+      }) as IInteractiveSession['off'],
+    });
+    const onDeliveryError = vi.fn();
+    const transport = createWsTransport({
+      send: () => {
+        throw new Error('functional adapter socket closed');
+      },
+      onDeliveryError,
+    });
+    transport.attach(session);
+    await transport.start();
+
+    expect(() =>
+      handlers.get('branch_event')?.({
+        kind: 'checkpoint_created',
+        checkpointId: 'turn-0001',
+        branchId: 'main',
+      }),
+    ).not.toThrow();
+    expect(onDeliveryError).toHaveBeenCalledWith(
+      expect.objectContaining({ message: 'functional adapter socket closed' }),
+      'branch_event',
+    );
+    expect(handlers.size).toBe(0);
+    expect(transport.onMessage).toBeNull();
+  });
+
+  it('invokes the shared lifecycle conformance suite', async () => {
+    await runTransportLifecycleConformance({
+      subjectId: '@robota-sdk/agent-transport-ws#createWsTransport',
+      kind: 'service',
+      createAdapter: () => createWsTransport({ send: vi.fn() }),
+      createSession: createMockSession,
+      assertReady: (transport) => {
+        if (typeof transport.onMessage !== 'function') throw new Error('WS handler not ready');
+      },
+      assertStopped: (transport) => {
+        if (transport.onMessage !== null) throw new Error('WS handler still ready');
+      },
+    });
+  });
 });

package/src/index.ts

@@ -1,7 +1,7 @@
-export { createWsHandler } from './ws-handler.js';
-export type { IWsHandlerOptions } from './ws-handler.js';
-export type { TClientMessage, TServerMessage } from './ws-protocol.js';
 export { createWsTransport } from './ws-transport.js';
-export type { IWsTransportOptions } from './ws-transport.js';
+export type { IWsTransport, IWsTransportOptions } from './ws-transport.js';
 export { WsTransport } from './ws-transport-configurable.js';
-export type { IWsTransportConfig } from './ws-transport-configurable.js';
+export type { IWsTransportConfig } from './ws-transport-config.js';
+// TRANS-001 — payload-agnostic channel multiplexing (also usable standalone by another carrier).
+export { PayloadChannelRegistry } from './payload-channels.js';
+export type { TChannelSink } from './payload-channels.js';

package/src/payload-channels.ts

@@ -0,0 +1,204 @@
+/**
+ * Payload-agnostic channel registry (TRANS-001) — the transport-side half of
+ * {@link IPayloadChannelHost}.
+ *
+ * Owns the multiplexing the carrier needs and nothing else: which channels exist, what each one
+ * declared, per-channel outbound `seq`, the attached connection sinks, and inbound routing. It is
+ * completely blind to payload semantics — a channel carrying audio, a file, or app events is the
+ * same object to this class.
+ *
+ * Every rejection is EXPLICIT: an undeclared event, binary traffic on a text-only channel, or a
+ * frame for an unregistered channel comes back as a stated error the carrier reports to the peer.
+ * Nothing is silently dropped or defaulted.
+ */
+
+import {
+  decodeChannelFrame,
+  encodeBinaryFrame,
+  encodeChannelEventFrame,
+} from '@robota-sdk/agent-transport';
+
+import type {
+  IBinaryFrame,
+  IChannelDescriptor,
+  IChannelEventFrame,
+  IPayloadChannel,
+  IPayloadChannelHost,
+  TChannelEventMap,
+  TChannelReceiveResult,
+} from '@robota-sdk/agent-interface-transport';
+
+/** Delivers an encoded frame to one attached connection. */
+export type TChannelSink = (frame: Uint8Array) => void;
+
+type TBinaryHandler = (frame: IBinaryFrame) => void;
+/**
+ * Storage type for a consumer's event handler. `never` parameters make every concrete
+ * `(payload: TEvents[K], frame: IChannelEventFrame<TEvents[K]>) => void` assignable to it, so the
+ * per-channel handler sets stay heterogeneous without an `unknown` double-cast. The declared-event
+ * check at both `onEvent` and `receive` is what keeps the erased types honest at runtime.
+ */
+type TEventHandler = (payload: never, frame: never) => void;
+
+/** Per-channel mutable state. Kept private to the registry — consumers only see `IPayloadChannel`. */
+interface IChannelState {
+  readonly descriptor: IChannelDescriptor;
+  readonly declaredEvents: ReadonlySet<string>;
+  readonly eventHandlers: Map<string, Set<TEventHandler>>;
+  readonly binaryHandlers: Set<TBinaryHandler>;
+  seq: number;
+  open: boolean;
+}
+
+export class PayloadChannelRegistry implements IPayloadChannelHost {
+  private readonly channels = new Map<string, IChannelState>();
+  private readonly sinks = new Set<TChannelSink>();
+
+  /**
+   * Attach a connection. Every frame a channel sends is fanned out to all attached sinks; the
+   * returned function detaches (call it on socket close).
+   */
+  addSink(sink: TChannelSink): () => void {
+    this.sinks.add(sink);
+    return (): void => {
+      this.sinks.delete(sink);
+    };
+  }
+
+  registerChannel<TEvents extends TChannelEventMap>(
+    descriptor: IChannelDescriptor<TEvents>,
+  ): IPayloadChannel<TEvents> {
+    if (this.channels.has(descriptor.name)) {
+      throw new Error(`Channel "${descriptor.name}" is already registered on this transport`);
+    }
+    const state: IChannelState = {
+      descriptor: descriptor as IChannelDescriptor,
+      declaredEvents: new Set<string>(descriptor.events),
+      eventHandlers: new Map(),
+      binaryHandlers: new Set(),
+      seq: 0,
+      open: true,
+    };
+    this.channels.set(descriptor.name, state);
+    return this.createHandle<TEvents>(descriptor, state);
+  }
+
+  /**
+   * Route one inbound encoded frame to its channel's handlers. The result states exactly what
+   * happened so the carrier can answer the peer (a `protocol_error`) instead of dropping it.
+   */
+  receive(bytes: Uint8Array): TChannelReceiveResult {
+    const decoded = decodeChannelFrame(bytes);
+    if (!decoded.ok) return decoded;
+
+    const { frame } = decoded;
+    const state = this.channels.get(frame.channel);
+    if (!state || !state.open) {
+      return { ok: false, error: `No channel registered for "${frame.channel}"` };
+    }
+
+    if (frame.kind === 'binary') {
+      if (state.descriptor.binary !== true) {
+        return {
+          ok: false,
+          error: `Channel "${frame.channel}" did not declare binary payload support`,
+        };
+      }
+      for (const handler of [...state.binaryHandlers]) handler(frame);
+      return { ok: true, frame };
+    }
+
+    if (!state.declaredEvents.has(frame.event)) {
+      return {
+        ok: false,
+        error: `Channel "${frame.channel}" did not declare event "${frame.event}"`,
+      };
+    }
+    const handlers = state.eventHandlers.get(frame.event);
+    if (handlers) {
+      for (const handler of [...handlers]) handler(frame.payload as never, frame as never);
+    }
+    return { ok: true, frame };
+  }
+
+  /** Fan one encoded frame out to every attached connection. */
+  private broadcast(frame: Uint8Array): void {
+    for (const sink of [...this.sinks]) sink(frame);
+  }
+
+  /** Assert the channel is still open before any send/subscribe. */
+  private static assertOpen(state: IChannelState): void {
+    if (!state.open) throw new Error(`Channel "${state.descriptor.name}" is closed`);
+  }
+
+  private createHandle<TEvents extends TChannelEventMap>(
+    descriptor: IChannelDescriptor<TEvents>,
+    state: IChannelState,
+  ): IPayloadChannel<TEvents> {
+    return {
+      descriptor,
+
+      sendEvent: <K extends keyof TEvents & string>(event: K, payload: TEvents[K]): void => {
+        PayloadChannelRegistry.assertOpen(state);
+        if (!state.declaredEvents.has(event)) {
+          throw new Error(`Channel "${descriptor.name}" did not declare event "${event}"`);
+        }
+        const seq = state.seq;
+        state.seq += 1;
+        this.broadcast(
+          encodeChannelEventFrame({
+            kind: 'event',
+            channel: descriptor.name,
+            seq,
+            event,
+            payload,
+          }),
+        );
+      },
+
+      sendBinary: (payload: Uint8Array): void => {
+        PayloadChannelRegistry.assertOpen(state);
+        if (descriptor.binary !== true) {
+          throw new Error(`Channel "${descriptor.name}" did not declare binary payload support`);
+        }
+        const seq = state.seq;
+        state.seq += 1;
+        this.broadcast(
+          encodeBinaryFrame({ kind: 'binary', channel: descriptor.name, seq, payload }),
+        );
+      },
+
+      onEvent: <K extends keyof TEvents & string>(
+        event: K,
+        handler: (payload: TEvents[K], frame: IChannelEventFrame<TEvents[K]>) => void,
+      ): (() => void) => {
+        PayloadChannelRegistry.assertOpen(state);
+        if (!state.declaredEvents.has(event)) {
+          throw new Error(`Channel "${descriptor.name}" did not declare event "${event}"`);
+        }
+        const set = state.eventHandlers.get(event) ?? new Set<TEventHandler>();
+        const typed: TEventHandler = handler;
+        set.add(typed);
+        state.eventHandlers.set(event, set);
+        return (): void => {
+          set.delete(typed);
+        };
+      },
+
+      onBinary: (handler: (frame: IBinaryFrame) => void): (() => void) => {
+        PayloadChannelRegistry.assertOpen(state);
+        state.binaryHandlers.add(handler);
+        return (): void => {
+          state.binaryHandlers.delete(handler);
+        };
+      },
+
+      close: (): void => {
+        state.open = false;
+        state.eventHandlers.clear();
+        state.binaryHandlers.clear();
+        this.channels.delete(descriptor.name);
+      },
+    };
+  }
+}