@robota-sdk/agent-transport-ws 3.0.0-beta.100

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);
+      },
+    };
+  }
+}

package/src/ws-connection-guards.ts

@@ -0,0 +1,104 @@
+/**
+ * Connection-admission guards for the WS transport (SEC-001 / GUI-002).
+ *
+ * Pure, socket-free predicates over the HTTP upgrade request — token minting/comparison plus the
+ * `Host` and `Origin` allow-lists. Split out of `ws-transport-configurable.ts` so the transport file
+ * carries lifecycle and frame routing only; the admission policy is independently readable and the
+ * transport module stays within the file-size ratchet.
+ */
+
+import { timingSafeEqual } from 'node:crypto';
+
+import { resolveAdmission } from '@robota-sdk/agent-transport/node';
+
+import type { ITransportAdmission } from '@robota-sdk/agent-interface-transport';
+import type { IncomingMessage } from 'node:http';
+
+/**
+ * Host names that are always loopback (port stripped by the caller). IPv4 bind only, so `[::1]`
+ * inbound is moot, but accepting it is harmless.
+ */
+const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '::1', '[::1]']);
+
+/** Strip the `:port` suffix from a Host/authority (port-agnostic — `bindWithRetry` can walk the port). */
+function hostname(hostHeader: string | undefined): string | null {
+  if (!hostHeader) return null;
+  if (hostHeader.startsWith('[')) return hostHeader.slice(0, hostHeader.indexOf(']') + 1) || null;
+  const colon = hostHeader.lastIndexOf(':');
+  return colon === -1 ? hostHeader : hostHeader.slice(0, colon);
+}
+
+/**
+ * The upgrade `Host` must be a loopback name (port-agnostic) or an explicitly allowed host — closes
+ * DNS rebinding. A missing `Host` is rejected (a well-formed HTTP/1.1 client always sends one).
+ */
+export function hostAllowed(req: IncomingMessage, allowedHosts: ReadonlySet<string>): boolean {
+  const host = hostname(req.headers.host);
+  if (host === null) return false;
+  return LOOPBACK_HOSTS.has(host) || allowedHosts.has(host);
+}
+
+/**
+ * A browser sends an unforgeable `Origin`; require it to be loopback or explicitly allowed. A
+ * non-browser client omits `Origin` (allowed here — the token is its gate). Closes the browser
+ * drive-by hole.
+ */
+export function originAllowed(req: IncomingMessage, allowedOrigins: ReadonlySet<string>): boolean {
+  const origin = req.headers.origin;
+  if (origin === undefined) return true; // non-browser client; token still required
+  if (allowedOrigins.has(origin)) return true;
+  try {
+    return LOOPBACK_HOSTS.has(new URL(origin).hostname);
+  } catch {
+    return false; // malformed Origin → reject
+  }
+}
+
+/**
+ * Constant-time token comparison. Returns false on any length mismatch (never throws), so an
+ * absent/short/long presented token is a plain reject, not an error.
+ */
+export function tokenMatches(expected: string, presented: string | null | undefined): boolean {
+  if (!presented) return false;
+  const a = Buffer.from(expected);
+  const b = Buffer.from(presented);
+  if (a.length !== b.length) return false;
+  return timingSafeEqual(a, b);
+}
+
+/** Read the presented token from the upgrade request: `?token=` query param, else the WS subprotocol. */
+export function presentedToken(req: IncomingMessage): string | null {
+  try {
+    const url = new URL(req.url ?? '', 'ws://127.0.0.1');
+    const q = url.searchParams.get('token');
+    if (q) return q;
+  } catch {
+    // malformed URL → fall through to the subprotocol header
+  }
+  const proto = req.headers['sec-websocket-protocol'];
+  return typeof proto === 'string' ? proto.split(',')[0]?.trim() || null : null;
+}
+
+/**
+ * This transport's admission decision, asked of the shared seam.
+ *
+ * Lives here rather than in the transport file because this module already owns the admission
+ * policy — token comparison and the Host/Origin allow-lists — and the transport file carries
+ * lifecycle and frame routing. The split is also what keeps that file inside its size ratchet.
+ */
+export function resolveWsAdmission(config: {
+  token?: string;
+  open?: boolean;
+  openReason?: string;
+}): ITransportAdmission {
+  // No fabricated reason. The first version filled one in for any caller that omitted it, 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. The whole point of requiring it is that nobody can produce one by
+  // accident, so the seam is asked the question exactly as it was given.
+  return resolveAdmission({
+    ...(config.token !== undefined ? { token: config.token } : {}),
+    ...(config.open === true ? { open: true } : {}),
+    ...(config.openReason !== undefined ? { openReason: config.openReason } : {}),
+  });
+}

package/src/ws-message-data.ts

@@ -0,0 +1,8 @@
+import type { RawData } from 'ws';
+
+/** Normalize the `ws` inbound payload variants to one binary view. */
+export function toBytes(data: RawData): Uint8Array {
+  if (Array.isArray(data)) return new Uint8Array(Buffer.concat(data));
+  if (data instanceof ArrayBuffer) return new Uint8Array(data);
+  return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+}

package/src/ws-session-delivery.ts

@@ -0,0 +1,109 @@
+import {
+  createOutboundDelivery,
+  createPendingStallClock,
+  DEFAULT_MAX_PENDING_BYTES,
+  isOverPendingBudget,
+} from '@robota-sdk/agent-transport';
+import { WebSocket } from 'ws';
+
+import type {
+  IPendingStallClock,
+  TOutboundDeliver,
+  TServerMessage,
+} from '@robota-sdk/agent-transport';
+
+/**
+ * Connection-scoped session delivery lifecycle shared by sync and async WebSocket failures.
+ *
+ * ARCH-030: {@link deliver} is the ONLY way out of this class. The raw sink — the `readyState` check
+ * plus `socket.send` — is private, so no caller can put a frame on this socket outside the connection's
+ * one outbound boundary. That is not stylistic: the previous shape exposed a public `send` that threw
+ * on a closed socket, and every reply the protocol handler produced went through it unguarded.
+ */
+export class WsSessionDelivery {
+  private cleanupProtocol = (): void => undefined;
+  private detachSink = (): void => undefined;
+  private closed = false;
+  /**
+   * Issue #2306: ONE drain clock for the socket. `bufferedAmount` does not distinguish text from
+   * binary, so both halves observe the same clock — a slow reader of payload frames is caught when a
+   * JSON reply is attempted, and the reverse.
+   */
+  private readonly stallClock: IPendingStallClock = createPendingStallClock();
+
+  /**
+   * The connection's outbound boundary. Built here, from this class's own sink and its own `close`
+   * policy, and passed DOWN into `createSessionMessageHandler` — the carrier owns both halves, so it builds the
+   * boundary rather than handing the protocol layer a raw sink to wrap.
+   */
+  readonly deliver: TOutboundDeliver;
+
+  constructor(private readonly socket: WebSocket) {
+    this.deliver = createOutboundDelivery(
+      (message) => this.rawSend(message),
+      () => this.close(),
+      // ARCH-030 / issue #1734: the socket's own count of what it has accepted and not yet written.
+      // Read at call time — it changes underneath.
+      () => this.socket.bufferedAmount,
+      DEFAULT_MAX_PENDING_BYTES,
+      this.stallClock,
+    );
+  }
+
+  /**
+   * Put a TRANS-001 payload frame on this socket, under the SAME budget and the same close policy as
+   * the text protocol (ARCH-030 / issue #1734).
+   *
+   * A WebSocket carries two kinds of outbound frame over one socket, and until this existed the
+   * binary half went straight to `socket.send` — outside the boundary, with no budget, and with a
+   * failure that could only surface as a throw inside a listener. `bufferedAmount` does not
+   * distinguish the two, so a non-reading peer accumulating payload frames was invisible to a budget
+   * that only guarded the other half.
+   *
+   * It is not `deliver`: that boundary is typed for `TServerMessage` and its brand is what makes a
+   * raw send unusable where a protocol frame is required. Widening it to accept bytes would remove
+   * the property the brand exists for.
+   */
+  readonly deliverBinary = (frame: Uint8Array): void => {
+    if (this.closed) return;
+    if (this.socket.readyState !== WebSocket.OPEN) return;
+    if (
+      isOverPendingBudget(this.socket.bufferedAmount) ||
+      this.stallClock.observe(this.socket.bufferedAmount) !== undefined
+    ) {
+      this.close();
+      return;
+    }
+    this.socket.send(frame, { binary: true }, (error) => {
+      if (error) this.close();
+    });
+  };
+
+  private rawSend(message: TServerMessage): void {
+    if (this.socket.readyState !== WebSocket.OPEN) throw new Error('WebSocket is not open');
+    this.socket.send(JSON.stringify(message), (error) => {
+      if (error) this.close();
+    });
+  }
+
+  bindProtocolCleanup(cleanup: () => void): void {
+    this.cleanupProtocol = cleanup;
+  }
+
+  bindSinkDetach(detach: () => void): void {
+    this.detachSink = detach;
+  }
+
+  readonly close = (): void => {
+    if (this.closed) return;
+    this.closed = true;
+    this.detachSink();
+    this.cleanupProtocol();
+    if (
+      this.socket.readyState === WebSocket.OPEN ||
+      this.socket.readyState === WebSocket.CONNECTING
+    ) {
+      this.socket.close(1011, 'session event delivery failed');
+    }
+  };
+}

package/src/ws-transport-config.ts

@@ -0,0 +1,133 @@
+/**
+ * The construction contract for `WsTransport` — what a caller decides before the server exists.
+ *
+ * Split from `ws-transport-configurable.ts` under the file-size ceiling, and the seam is the
+ * honest one: everything here is a decision the CALLER makes (port, retries, admission — SEC-008's
+ * `token`/`open`/`openReason` contract lives in these doc comments), while the class next door is
+ * what the transport DOES with those decisions.
+ */
+
+import type { TUsageSurface } from '@robota-sdk/agent-interface-analytics';
+import type { ISessionBinder, TDriverId } from '@robota-sdk/agent-interface-session';
+import type { ITransportLifecycleError } from '@robota-sdk/agent-interface-transport';
+import type { IProtocolSession, ISessionMessageHandlerOptions } from '@robota-sdk/agent-transport';
+
+export const DEFAULT_PORT = 7070;
+export const DEFAULT_MAX_RETRIES = 20;
+
+export interface IWsTransportConfig {
+  /** Trusted server-assigned identity for turns submitted over this product surface. */
+  driverId?: TDriverId;
+  /** Trusted product surface, independent from the connection's driver identity. */
+  surface?: TUsageSurface;
+  /** Host-owned cross-session usage read model, forwarded unchanged to the protocol handler. */
+  personalUsageReporter?: ISessionMessageHandlerOptions['personalUsageReporter'];
+  /** Host-owned current-session trace/cost producer, forwarded unchanged to the protocol handler. */
+  usageReporter?: ISessionMessageHandlerOptions['usageReporter'];
+  /** Host-owned stored-session trace/cost producer for personal-usage drill-down. */
+  storedSessionUsageReporter?: ISessionMessageHandlerOptions['storedSessionUsageReporter'];
+  /** Host-owned session directory (#3189): lets every connection list, start and switch sessions. */
+  sessionDirectory?: ISessionMessageHandlerOptions['sessionDirectory'];
+  /** #3282 §4a: host-owned read/write for the GUI Settings screen, forwarded unchanged. */
+  settingsReporter?: ISessionMessageHandlerOptions['settingsReporter'];
+  /**
+   * #3189: gives each connection a binding of its own — its own session and its own directory view —
+   * so one connection's switch moves only that connection. Released when the connection closes. When
+   * set, a connection uses its binding's session and directory instead of the attached session and
+   * `sessionDirectory`; without it every connection shares the attached session.
+   */
+  sessionBinder?: ISessionBinder<IProtocolSession>;
+  port?: number;
+  maxRetries?: number;
+  /**
+   * OPTIONAL explicit loopback auth token. When set, every connection MUST present a matching token
+   * (query param `?token=` or the `Sec-WebSocket-Protocol` subprotocol) or the socket is closed BEFORE any
+   * session data is emitted (GUI-002; the host sidecar supplies its configured token). SEC-001: when this is unset
+   * AND `open` is not `true`, the transport AUTO-MINTS a random per-launch token (secure by default) —
+   * `resolvedToken` exposes it so the surface can deliver it to the co-located client (a `0600` connection
+   * file / the served monitor's injected `ws-url`). An explicit token here wins over the auto-mint — but NOT
+   * over `open`: SEC-008 makes a token together with `open: true` a contradiction that throws, rather
+   * than a precedence one side quietly wins.
+   */
+  token?: string;
+  /**
+   * SEC-001 discouraged opt-out: when `true`, run WITHOUT auth (no token, no auto-mint) — the pre-SEC-001
+   * open loopback behavior. NOT RECOMMENDED (any local process or browser page can then drive+authorize the
+   * session); mirrors Jupyter's `c.ServerApp.token = ''`.
+   *
+   * SEC-008: `open: true` together with a non-empty `token` is REJECTED, not resolved by precedence. The
+   * two ask for opposite things, and picking a winner silently is how a caller ends up with the admission
+   * it did not choose. `resolveAdmission` decides that for every transport, so they cannot differ.
+   */
+  open?: boolean;
+  /** SEC-008: why running with no credential is correct here. Required when `open` is true. */
+  openReason?: string;
+  /**
+   * SEC-001 defense-in-depth: extra host names (beyond `localhost`/`127.0.0.1`/`::1`) accepted in the
+   * upgrade `Host` header. The `Host` allow-list closes DNS-rebinding independently of the token.
+   */
+  allowedHosts?: readonly string[];
+  /**
+   * SEC-001 defense-in-depth: extra browser `Origin`s (beyond loopback) accepted on the upgrade — e.g. the
+   * `apps/agent-web` app origin. A browser sends an unforgeable `Origin`; a non-browser client omits it (and
+   * is gated by the token instead). Closes the "any web page in any browser" hole before history is emitted.
+   */
+  allowedOrigins?: readonly string[];
+}
+
+type TUsageReporters = Pick<
+  ISessionMessageHandlerOptions,
+  'personalUsageReporter' | 'usageReporter' | 'storedSessionUsageReporter'
+>;
+
+/** Remove absent reporters so exact-optional handler options remain truthful. */
+function configuredUsageReporters(config: IWsTransportConfig): TUsageReporters {
+  return {
+    ...(config.personalUsageReporter
+      ? { personalUsageReporter: config.personalUsageReporter }
+      : {}),
+    ...(config.usageReporter ? { usageReporter: config.usageReporter } : {}),
+    ...(config.storedSessionUsageReporter
+      ? { storedSessionUsageReporter: config.storedSessionUsageReporter }
+      : {}),
+  };
+}
+
+type TConfiguredHandlerOptions = Pick<
+  ISessionMessageHandlerOptions,
+  | 'driverId'
+  | 'surface'
+  | 'personalUsageReporter'
+  | 'usageReporter'
+  | 'storedSessionUsageReporter'
+  | 'sessionDirectory'
+  | 'settingsReporter'
+>;
+
+/** Project immutable transport attribution/reporters into each protocol handler. */
+export function configuredWsHandlerOptions(config: IWsTransportConfig): TConfiguredHandlerOptions {
+  return {
+    ...(config.driverId ? { driverId: config.driverId } : {}),
+    ...(config.surface ? { surface: config.surface } : {}),
+    ...configuredUsageReporters(config),
+    ...(config.sessionDirectory ? { sessionDirectory: config.sessionDirectory } : {}),
+    ...(config.settingsReporter ? { settingsReporter: config.settingsReporter } : {}),
+  };
+}
+
+export function validTransportOptions(options: Readonly<Record<string, unknown>>): boolean {
+  const { port, maxRetries } = options;
+  if (port !== undefined && (typeof port !== 'number' || port < 1 || port > 65535)) return false;
+  return maxRetries === undefined || (typeof maxRetries === 'number' && maxRetries >= 0);
+}
+
+export function transportLifecycleError(
+  transportName: string,
+  code: ITransportLifecycleError['code'],
+): ITransportLifecycleError {
+  return Object.assign(new Error(`${transportName} ${code}.`), {
+    name: 'TransportLifecycleError' as const,
+    code,
+    transportName,
+  });
+}