@sideband/secure-relay 0.1.0 → 0.2.1

package/src/frame.ts

@@ -0,0 +1,771 @@
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Binary wire format for Sideband Relay Protocol (SBRP).
+ *
+ * Frame structure (§13):
+ * ```
+ * ┌───────────┬──────────────┬────────────────┬─────────────────────┐
+ * │ Type (1B) │ Length (4B)  │ SessionID (8B) │ Payload (0..64KB)   │
+ * └───────────┴──────────────┴────────────────┴─────────────────────┘
+ * ```
+ *
+ * All multi-byte integers are big-endian.
+ */
+
+import {
+  FRAME_HEADER_SIZE,
+  HANDSHAKE_ACCEPT_PAYLOAD_SIZE,
+  HANDSHAKE_INIT_PAYLOAD_SIZE,
+  MAX_PAYLOAD_SIZE,
+  MAX_PING_PAYLOAD_SIZE,
+  MIN_CONTROL_PAYLOAD_SIZE,
+  MIN_ENCRYPTED_PAYLOAD_SIZE,
+  SIGNAL_PAYLOAD_SIZE,
+} from "./constants.js";
+import { extractSequence } from "./crypto.js";
+import type {
+  EncryptedMessage,
+  HandshakeAccept,
+  HandshakeInit,
+  SessionId,
+  SignalCode,
+  SignalReason,
+} from "./types.js";
+import { SbrpError, SbrpErrorCode } from "./types.js";
+
+/**
+ * Frame type discriminant (wire byte).
+ *
+ * Frame types are organized by authority:
+ * - Endpoint frames (0x01-0x03): Forwarded by relay, E2EE
+ * - Signal frame (0x04): Daemon → Relay only
+ * - Keepalive frames (0x10-0x11): Connection-scoped, never forwarded
+ * - Control frame (0x20): Relay → Endpoint only
+ */
+export const FrameType = {
+  // Endpoint frames (forwarded, E2EE)
+  HandshakeInit: 0x01,
+  HandshakeAccept: 0x02,
+  Data: 0x03, // Renamed from Encrypted for clarity
+
+  // Signal frame (daemon → relay)
+  Signal: 0x04,
+
+  // Keepalive frames (connection-scoped, never forwarded)
+  Ping: 0x10,
+  Pong: 0x11,
+
+  // Control frame (relay → endpoint)
+  Control: 0x20,
+} as const;
+
+export type FrameType = (typeof FrameType)[keyof typeof FrameType];
+
+/**
+ * Wire control codes (uint16, §14).
+ *
+ * Codes use ranges for categorization:
+ * - 0x01xx: Authentication (terminal)
+ * - 0x02xx: Routing (varies)
+ * - 0x03xx: Session (terminal)
+ * - 0x04xx: Wire format (terminal)
+ * - 0x09xx: Rate limiting (non-terminal)
+ * - 0x10xx: Session state (non-terminal)
+ */
+export const WireControlCode = {
+  // Authentication (0x01xx) - Terminal
+  Unauthorized: 0x0101,
+  Forbidden: 0x0102,
+
+  // Routing (0x02xx) - Varies
+  DaemonNotFound: 0x0201,
+  DaemonOffline: 0x0202, // Non-terminal
+
+  // Session (0x03xx) - Terminal
+  SessionNotFound: 0x0301,
+  SessionExpired: 0x0302,
+
+  // Wire Format (0x04xx) - Terminal
+  MalformedFrame: 0x0401,
+  PayloadTooLarge: 0x0402,
+  InvalidFrameType: 0x0403,
+  InvalidSessionId: 0x0404,
+  DisallowedSender: 0x0405,
+
+  // Internal (0x06xx) - Terminal
+  InternalError: 0x0601,
+
+  // Rate Limiting (0x09xx) - Non-terminal
+  RateLimited: 0x0901,
+
+  // Session State (0x10xx) - Non-terminal
+  SessionPaused: 0x1001,
+  SessionResumed: 0x1002,
+  SessionEnded: 0x1003,
+  SessionPending: 0x1004,
+} as const;
+
+export type WireControlCode =
+  (typeof WireControlCode)[keyof typeof WireControlCode];
+
+/** Check if a control code is terminal (closes connection) */
+export function isTerminalCode(code: WireControlCode): boolean {
+  // Non-terminal codes: daemon_offline (0x0202), rate_limited (0x09xx), session state (0x10xx)
+  return (
+    code !== WireControlCode.DaemonOffline &&
+    code !== WireControlCode.RateLimited &&
+    code < 0x1000
+  );
+}
+
+/** Decoded frame header */
+export interface FrameHeader {
+  type: FrameType;
+  length: number;
+  sessionId: SessionId;
+}
+
+/** Decoded frame (header + payload) */
+export interface Frame extends FrameHeader {
+  payload: Uint8Array;
+}
+
+/** Decoded Control frame payload */
+export interface ControlPayload {
+  code: WireControlCode;
+  message: string;
+}
+
+/** Decoded Signal frame payload */
+export interface SignalPayload {
+  signal: SignalCode;
+  reason: SignalReason;
+}
+
+// ============================================================================
+// Control code mapping
+// ============================================================================
+
+const sbrpToWire: Record<string, WireControlCode> = {
+  // Authentication
+  [SbrpErrorCode.Unauthorized]: WireControlCode.Unauthorized,
+  [SbrpErrorCode.Forbidden]: WireControlCode.Forbidden,
+
+  // Routing
+  [SbrpErrorCode.DaemonNotFound]: WireControlCode.DaemonNotFound,
+  [SbrpErrorCode.DaemonOffline]: WireControlCode.DaemonOffline,
+
+  // Session
+  [SbrpErrorCode.SessionNotFound]: WireControlCode.SessionNotFound,
+  [SbrpErrorCode.SessionExpired]: WireControlCode.SessionExpired,
+
+  // Wire Format
+  [SbrpErrorCode.MalformedFrame]: WireControlCode.MalformedFrame,
+  [SbrpErrorCode.PayloadTooLarge]: WireControlCode.PayloadTooLarge,
+  [SbrpErrorCode.InvalidFrameType]: WireControlCode.InvalidFrameType,
+  [SbrpErrorCode.InvalidSessionId]: WireControlCode.InvalidSessionId,
+  [SbrpErrorCode.DisallowedSender]: WireControlCode.DisallowedSender,
+
+  // Internal
+  [SbrpErrorCode.InternalError]: WireControlCode.InternalError,
+
+  // Rate Limiting
+  [SbrpErrorCode.RateLimited]: WireControlCode.RateLimited,
+
+  // Session State
+  [SbrpErrorCode.SessionPaused]: WireControlCode.SessionPaused,
+  [SbrpErrorCode.SessionResumed]: WireControlCode.SessionResumed,
+  [SbrpErrorCode.SessionEnded]: WireControlCode.SessionEnded,
+  [SbrpErrorCode.SessionPending]: WireControlCode.SessionPending,
+};
+
+const wireToSbrp: Record<number, SbrpErrorCode> = {
+  // Authentication
+  [WireControlCode.Unauthorized]: SbrpErrorCode.Unauthorized,
+  [WireControlCode.Forbidden]: SbrpErrorCode.Forbidden,
+
+  // Routing
+  [WireControlCode.DaemonNotFound]: SbrpErrorCode.DaemonNotFound,
+  [WireControlCode.DaemonOffline]: SbrpErrorCode.DaemonOffline,
+
+  // Session
+  [WireControlCode.SessionNotFound]: SbrpErrorCode.SessionNotFound,
+  [WireControlCode.SessionExpired]: SbrpErrorCode.SessionExpired,
+
+  // Wire Format
+  [WireControlCode.MalformedFrame]: SbrpErrorCode.MalformedFrame,
+  [WireControlCode.PayloadTooLarge]: SbrpErrorCode.PayloadTooLarge,
+  [WireControlCode.InvalidFrameType]: SbrpErrorCode.InvalidFrameType,
+  [WireControlCode.InvalidSessionId]: SbrpErrorCode.InvalidSessionId,
+  [WireControlCode.DisallowedSender]: SbrpErrorCode.DisallowedSender,
+
+  // Internal
+  [WireControlCode.InternalError]: SbrpErrorCode.InternalError,
+
+  // Rate Limiting
+  [WireControlCode.RateLimited]: SbrpErrorCode.RateLimited,
+
+  // Session State
+  [WireControlCode.SessionPaused]: SbrpErrorCode.SessionPaused,
+  [WireControlCode.SessionResumed]: SbrpErrorCode.SessionResumed,
+  [WireControlCode.SessionEnded]: SbrpErrorCode.SessionEnded,
+  [WireControlCode.SessionPending]: SbrpErrorCode.SessionPending,
+};
+
+/** Convert SbrpErrorCode to wire format (for relay-transmittable codes only) */
+export function toWireControlCode(code: SbrpErrorCode): WireControlCode {
+  const wire = sbrpToWire[code];
+  if (wire === undefined) {
+    throw new Error(`Unknown or non-wire SbrpErrorCode: ${code}`);
+  }
+  return wire;
+}
+
+/** Convert wire control code to SbrpErrorCode */
+export function fromWireControlCode(code: WireControlCode): SbrpErrorCode {
+  const sbrp = wireToSbrp[code];
+  if (sbrp === undefined) {
+    throw new Error(`Unknown WireControlCode: 0x${code.toString(16)}`);
+  }
+  return sbrp;
+}
+
+// ============================================================================
+// Validation helpers
+// ============================================================================
+
+const MAX_UINT64 = 0xffff_ffff_ffff_ffffn;
+
+/**
+ * Check if frame type requires non-zero sessionId (§13.2).
+ *
+ * Session-bound: HandshakeInit, HandshakeAccept, Data, Signal
+ * Connection-scoped (sessionId must be 0): Ping, Pong
+ * Variable (depends on content): Control
+ */
+function isSessionBound(type: FrameType): boolean {
+  return (
+    type === FrameType.HandshakeInit ||
+    type === FrameType.HandshakeAccept ||
+    type === FrameType.Data ||
+    type === FrameType.Signal
+  );
+}
+
+/** Check if frame type requires sessionId = 0 (connection-scoped) */
+function isConnectionScoped(type: FrameType): boolean {
+  return type === FrameType.Ping || type === FrameType.Pong;
+}
+
+function validateSessionId(sessionId: SessionId, type: FrameType): void {
+  if (sessionId < 0n || sessionId > MAX_UINT64) {
+    throw new SbrpError(
+      SbrpErrorCode.MalformedFrame,
+      `SessionId out of uint64 range: ${sessionId}`,
+    );
+  }
+  if (isSessionBound(type) && sessionId === 0n) {
+    throw new SbrpError(
+      SbrpErrorCode.MalformedFrame,
+      `Session-bound frame type 0x${type.toString(16).padStart(2, "0")} requires non-zero sessionId`,
+    );
+  }
+  if (isConnectionScoped(type) && sessionId !== 0n) {
+    throw new SbrpError(
+      SbrpErrorCode.MalformedFrame,
+      `Connection-scoped frame type 0x${type.toString(16).padStart(2, "0")} requires sessionId = 0`,
+    );
+  }
+}
+
+// ============================================================================
+// Low-level frame encoding/decoding
+// ============================================================================
+
+/**
+ * Encode a frame to binary wire format.
+ *
+ * @throws {SbrpError} if payload exceeds MAX_PAYLOAD_SIZE or sessionId is invalid
+ */
+export function encodeFrame(
+  type: FrameType,
+  sessionId: SessionId,
+  payload: Uint8Array,
+): Uint8Array {
+  validateSessionId(sessionId, type);
+
+  if (payload.length > MAX_PAYLOAD_SIZE) {
+    throw new SbrpError(
+      SbrpErrorCode.PayloadTooLarge,
+      `Payload size ${payload.length} exceeds maximum ${MAX_PAYLOAD_SIZE}`,
+    );
+  }
+
+  const frame = new Uint8Array(FRAME_HEADER_SIZE + payload.length);
+  const view = new DataView(frame.buffer);
+
+  frame[0] = type;
+  view.setUint32(1, payload.length, false);
+  view.setBigUint64(5, sessionId, false);
+  frame.set(payload, FRAME_HEADER_SIZE);
+
+  return frame;
+}
+
+/**
+ * Read frame header without decoding payload.
+ * Useful for routing decisions before full decode.
+ *
+ * Validates wire format constraints including non-zero sessionId
+ * for session-bound frames (§13.2).
+ *
+ * @throws {SbrpError} if buffer is too short, length exceeds max, or sessionId invalid
+ */
+export function readFrameHeader(data: Uint8Array): FrameHeader {
+  if (data.length < FRAME_HEADER_SIZE) {
+    throw new SbrpError(
+      SbrpErrorCode.MalformedFrame,
+      `Frame too short: ${data.length} < ${FRAME_HEADER_SIZE}`,
+    );
+  }
+
+  const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+  const type = data[0] as FrameType;
+  const length = view.getUint32(1, false);
+  const sessionId = view.getBigUint64(5, false);
+
+  if (length > MAX_PAYLOAD_SIZE) {
+    throw new SbrpError(
+      SbrpErrorCode.PayloadTooLarge,
+      `Payload length ${length} exceeds maximum ${MAX_PAYLOAD_SIZE}`,
+    );
+  }
+
+  // Wire format constraint: session-bound frames require non-zero sessionId
+  if (isSessionBound(type) && sessionId === 0n) {
+    throw new SbrpError(
+      SbrpErrorCode.MalformedFrame,
+      `Session-bound frame type 0x${type.toString(16).padStart(2, "0")} requires non-zero sessionId`,
+    );
+  }
+
+  // Wire format constraint: connection-scoped frames require sessionId = 0
+  if (isConnectionScoped(type) && sessionId !== 0n) {
+    throw new SbrpError(
+      SbrpErrorCode.MalformedFrame,
+      `Connection-scoped frame type 0x${type.toString(16).padStart(2, "0")} requires sessionId = 0`,
+    );
+  }
+
+  return { type, length, sessionId };
+}
+
+/**
+ * Decode a complete frame from binary data.
+ *
+ * Rejects trailing bytes to catch framing mistakes. Use `FrameDecoder`
+ * for streaming scenarios with multiple frames per buffer.
+ *
+ * @throws {SbrpError} if frame is malformed or has trailing bytes
+ */
+export function decodeFrame(data: Uint8Array): Frame {
+  const header = readFrameHeader(data);
+  const expectedSize = FRAME_HEADER_SIZE + header.length;
+
+  if (data.length < expectedSize) {
+    throw new SbrpError(
+      SbrpErrorCode.MalformedFrame,
+      `Frame truncated: got ${data.length}, expected ${expectedSize}`,
+    );
+  }
+
+  if (data.length > expectedSize) {
+    throw new SbrpError(
+      SbrpErrorCode.MalformedFrame,
+      `Frame has ${data.length - expectedSize} trailing bytes`,
+    );
+  }
+
+  const payload = data.subarray(FRAME_HEADER_SIZE, expectedSize);
+  return { ...header, payload };
+}
+
+/**
+ * Decode frame allowing trailing bytes (for streaming use).
+ * Returns the frame and number of bytes consumed.
+ */
+function decodeFrameFromBuffer(data: Uint8Array): {
+  frame: Frame;
+  bytesConsumed: number;
+} {
+  const header = readFrameHeader(data);
+  const frameSize = FRAME_HEADER_SIZE + header.length;
+
+  if (data.length < frameSize) {
+    throw new SbrpError(
+      SbrpErrorCode.MalformedFrame,
+      `Frame truncated: got ${data.length}, expected ${frameSize}`,
+    );
+  }
+
+  const payload = data.subarray(FRAME_HEADER_SIZE, frameSize);
+  return { frame: { ...header, payload }, bytesConsumed: frameSize };
+}
+
+// ============================================================================
+// High-level frame encoding (typed message → binary)
+// ============================================================================
+
+/**
+ * Encode HandshakeInit to wire frame.
+ *
+ * @throws {SbrpError} if initPublicKey is not exactly 32 bytes or sessionId is invalid
+ */
+export function encodeHandshakeInit(
+  sessionId: SessionId,
+  init: HandshakeInit,
+): Uint8Array {
+  if (init.initPublicKey.length !== HANDSHAKE_INIT_PAYLOAD_SIZE) {
+    throw new SbrpError(
+      SbrpErrorCode.MalformedFrame,
+      `initPublicKey must be ${HANDSHAKE_INIT_PAYLOAD_SIZE} bytes, got ${init.initPublicKey.length}`,
+    );
+  }
+  return encodeFrame(FrameType.HandshakeInit, sessionId, init.initPublicKey);
+}
+
+/**
+ * Encode HandshakeAccept to wire frame.
+ *
+ * @throws {SbrpError} if acceptPublicKey/signature have wrong sizes or sessionId is invalid
+ */
+export function encodeHandshakeAccept(
+  sessionId: SessionId,
+  accept: HandshakeAccept,
+): Uint8Array {
+  if (accept.acceptPublicKey.length !== 32) {
+    throw new SbrpError(
+      SbrpErrorCode.MalformedFrame,
+      `acceptPublicKey must be 32 bytes, got ${accept.acceptPublicKey.length}`,
+    );
+  }
+  if (accept.signature.length !== 64) {
+    throw new SbrpError(
+      SbrpErrorCode.MalformedFrame,
+      `signature must be 64 bytes, got ${accept.signature.length}`,
+    );
+  }
+  const payload = new Uint8Array(HANDSHAKE_ACCEPT_PAYLOAD_SIZE);
+  payload.set(accept.acceptPublicKey, 0);
+  payload.set(accept.signature, 32);
+  return encodeFrame(FrameType.HandshakeAccept, sessionId, payload);
+}
+
+/**
+ * Encode Data frame (encrypted message).
+ *
+ * @throws {SbrpError} if data is too short (< nonce + authTag) or sessionId is invalid
+ */
+export function encodeData(
+  sessionId: SessionId,
+  message: EncryptedMessage,
+): Uint8Array {
+  if (message.data.length < MIN_ENCRYPTED_PAYLOAD_SIZE) {
+    throw new SbrpError(
+      SbrpErrorCode.MalformedFrame,
+      `Data payload must be at least ${MIN_ENCRYPTED_PAYLOAD_SIZE} bytes, got ${message.data.length}`,
+    );
+  }
+  return encodeFrame(FrameType.Data, sessionId, message.data);
+}
+
+/**
+ * Encode Signal frame (daemon → relay).
+ *
+ * @param sessionId Session being signaled
+ * @param signal Signal code (ready or close)
+ * @param reason Reason code (for close signal)
+ */
+export function encodeSignal(
+  sessionId: SessionId,
+  signal: SignalCode,
+  reason: SignalReason = 0x00,
+): Uint8Array {
+  const payload = new Uint8Array(SIGNAL_PAYLOAD_SIZE);
+  payload[0] = signal;
+  payload[1] = reason;
+  return encodeFrame(FrameType.Signal, sessionId, payload);
+}
+
+/**
+ * Encode Ping frame (connection-scoped keepalive).
+ *
+ * @param payload Optional 0-8 byte payload for RTT measurement
+ */
+export function encodePing(
+  payload: Uint8Array = new Uint8Array(0),
+): Uint8Array {
+  if (payload.length > MAX_PING_PAYLOAD_SIZE) {
+    throw new SbrpError(
+      SbrpErrorCode.PayloadTooLarge,
+      `Ping payload must be 0-${MAX_PING_PAYLOAD_SIZE} bytes, got ${payload.length}`,
+    );
+  }
+  return encodeFrame(FrameType.Ping, 0n, payload);
+}
+
+/**
+ * Encode Pong frame (connection-scoped keepalive response).
+ *
+ * @param payload Payload from corresponding Ping (must be copied)
+ */
+export function encodePong(
+  payload: Uint8Array = new Uint8Array(0),
+): Uint8Array {
+  if (payload.length > MAX_PING_PAYLOAD_SIZE) {
+    throw new SbrpError(
+      SbrpErrorCode.PayloadTooLarge,
+      `Pong payload must be 0-${MAX_PING_PAYLOAD_SIZE} bytes, got ${payload.length}`,
+    );
+  }
+  return encodeFrame(FrameType.Pong, 0n, payload);
+}
+
+/**
+ * Encode Control frame (relay → endpoint).
+ *
+ * @param sessionId Session ID (non-zero for session events, 0 for connection errors)
+ * @param code Control code from WireControlCode
+ * @param message Optional diagnostic message (for errors only)
+ */
+export function encodeControl(
+  sessionId: SessionId,
+  code: WireControlCode,
+  message?: string,
+): Uint8Array {
+  const msgBytes = message ? new TextEncoder().encode(message) : null;
+  const payload = new Uint8Array(2 + (msgBytes?.length ?? 0));
+  new DataView(payload.buffer).setUint16(0, code, false);
+  if (msgBytes) payload.set(msgBytes, 2);
+  return encodeFrame(FrameType.Control, sessionId, payload);
+}
+
+// ============================================================================
+// High-level frame decoding (Frame → typed message)
+// ============================================================================
+
+/** Validate sessionId for session-bound frames on decode path */
+function validateSessionIdOnDecode(frame: Frame): void {
+  if (isSessionBound(frame.type) && frame.sessionId === 0n) {
+    throw new SbrpError(
+      SbrpErrorCode.MalformedFrame,
+      `Session-bound frame type 0x${frame.type.toString(16).padStart(2, "0")} requires non-zero sessionId`,
+    );
+  }
+  if (isConnectionScoped(frame.type) && frame.sessionId !== 0n) {
+    throw new SbrpError(
+      SbrpErrorCode.MalformedFrame,
+      `Connection-scoped frame type 0x${frame.type.toString(16).padStart(2, "0")} requires sessionId = 0`,
+    );
+  }
+}
+
+/**
+ * Decode HandshakeInit from frame.
+ *
+ * @throws {SbrpError} if frame type, payload size, or sessionId is invalid
+ */
+export function decodeHandshakeInit(frame: Frame): HandshakeInit {
+  if (frame.type !== FrameType.HandshakeInit) {
+    throw new SbrpError(
+      SbrpErrorCode.InvalidFrameType,
+      `Expected HandshakeInit (0x01), got 0x${frame.type.toString(16).padStart(2, "0")}`,
+    );
+  }
+  validateSessionIdOnDecode(frame);
+  if (frame.payload.length !== HANDSHAKE_INIT_PAYLOAD_SIZE) {
+    throw new SbrpError(
+      SbrpErrorCode.MalformedFrame,
+      `HandshakeInit payload must be ${HANDSHAKE_INIT_PAYLOAD_SIZE} bytes, got ${frame.payload.length}`,
+    );
+  }
+  return {
+    type: "handshake.init",
+    initPublicKey: frame.payload.slice(),
+  };
+}
+
+/**
+ * Decode HandshakeAccept from frame.
+ *
+ * @throws {SbrpError} if frame type, payload size, or sessionId is invalid
+ */
+export function decodeHandshakeAccept(frame: Frame): HandshakeAccept {
+  if (frame.type !== FrameType.HandshakeAccept) {
+    throw new SbrpError(
+      SbrpErrorCode.InvalidFrameType,
+      `Expected HandshakeAccept (0x02), got 0x${frame.type.toString(16).padStart(2, "0")}`,
+    );
+  }
+  validateSessionIdOnDecode(frame);
+  if (frame.payload.length !== HANDSHAKE_ACCEPT_PAYLOAD_SIZE) {
+    throw new SbrpError(
+      SbrpErrorCode.MalformedFrame,
+      `HandshakeAccept payload must be ${HANDSHAKE_ACCEPT_PAYLOAD_SIZE} bytes, got ${frame.payload.length}`,
+    );
+  }
+  return {
+    type: "handshake.accept",
+    acceptPublicKey: frame.payload.slice(0, 32),
+    signature: frame.payload.slice(32, 96),
+  };
+}
+
+/**
+ * Decode Data frame (encrypted message).
+ *
+ * @throws {SbrpError} if frame type, payload, or sessionId is invalid
+ */
+export function decodeData(frame: Frame): EncryptedMessage {
+  if (frame.type !== FrameType.Data) {
+    throw new SbrpError(
+      SbrpErrorCode.InvalidFrameType,
+      `Expected Data (0x03), got 0x${frame.type.toString(16).padStart(2, "0")}`,
+    );
+  }
+  validateSessionIdOnDecode(frame);
+  if (frame.payload.length < MIN_ENCRYPTED_PAYLOAD_SIZE) {
+    throw new SbrpError(
+      SbrpErrorCode.MalformedFrame,
+      `Data payload must be at least ${MIN_ENCRYPTED_PAYLOAD_SIZE} bytes, got ${frame.payload.length}`,
+    );
+  }
+  const seq = extractSequence(frame.payload);
+  return {
+    type: "encrypted",
+    seq,
+    data: frame.payload.slice(),
+  };
+}
+
+/**
+ * Decode Signal frame (daemon → relay).
+ *
+ * @throws {SbrpError} if frame type, payload size, or sessionId is invalid
+ */
+export function decodeSignal(frame: Frame): SignalPayload {
+  if (frame.type !== FrameType.Signal) {
+    throw new SbrpError(
+      SbrpErrorCode.InvalidFrameType,
+      `Expected Signal (0x04), got 0x${frame.type.toString(16).padStart(2, "0")}`,
+    );
+  }
+  validateSessionIdOnDecode(frame);
+  if (frame.payload.length !== SIGNAL_PAYLOAD_SIZE) {
+    throw new SbrpError(
+      SbrpErrorCode.MalformedFrame,
+      `Signal payload must be ${SIGNAL_PAYLOAD_SIZE} bytes, got ${frame.payload.length}`,
+    );
+  }
+  return {
+    signal: frame.payload[0] as SignalCode,
+    reason: frame.payload[1] as SignalReason,
+  };
+}
+
+/**
+ * Decode Control frame (relay → endpoint).
+ *
+ * Invalid UTF-8 sequences in message are replaced with U+FFFD.
+ *
+ * @throws {SbrpError} if frame type or payload is invalid
+ */
+export function decodeControl(frame: Frame): ControlPayload {
+  if (frame.type !== FrameType.Control) {
+    throw new SbrpError(
+      SbrpErrorCode.InvalidFrameType,
+      `Expected Control (0x20), got 0x${frame.type.toString(16).padStart(2, "0")}`,
+    );
+  }
+  if (frame.payload.length < MIN_CONTROL_PAYLOAD_SIZE) {
+    throw new SbrpError(
+      SbrpErrorCode.MalformedFrame,
+      `Control payload must be at least ${MIN_CONTROL_PAYLOAD_SIZE} bytes, got ${frame.payload.length}`,
+    );
+  }
+  const view = new DataView(
+    frame.payload.buffer,
+    frame.payload.byteOffset,
+    frame.payload.byteLength,
+  );
+  const code = view.getUint16(0, false) as WireControlCode;
+  // TextDecoder with fatal:false replaces invalid UTF-8 with U+FFFD
+  const message = new TextDecoder("utf-8", { fatal: false }).decode(
+    frame.payload.subarray(2),
+  );
+  return { code, message };
+}
+
+// ============================================================================
+// Streaming frame decoder
+// ============================================================================
+
+/**
+ * Streaming frame decoder for incremental parsing.
+ *
+ * Accumulates bytes and yields complete frames. Useful when frames
+ * may be fragmented across WebSocket messages or TCP reads.
+ *
+ * @example
+ * ```typescript
+ * const decoder = new FrameDecoder();
+ * ws.on("message", (data) => {
+ *   for (const frame of decoder.push(data)) {
+ *     handleFrame(frame);
+ *   }
+ * });
+ * ```
+ */
+export class FrameDecoder {
+  private buffer: Uint8Array = new Uint8Array(0);
+
+  /**
+   * Push data and yield any complete frames.
+   */
+  *push(data: Uint8Array): Generator<Frame> {
+    // Append to buffer
+    if (this.buffer.length === 0) {
+      this.buffer = data;
+    } else {
+      const combined = new Uint8Array(this.buffer.length + data.length);
+      combined.set(this.buffer, 0);
+      combined.set(data, this.buffer.length);
+      this.buffer = combined;
+    }
+
+    // Yield complete frames
+    while (this.buffer.length >= FRAME_HEADER_SIZE) {
+      const header = readFrameHeader(this.buffer);
+      const frameSize = FRAME_HEADER_SIZE + header.length;
+
+      if (this.buffer.length < frameSize) {
+        break; // Incomplete frame, wait for more data
+      }
+
+      const { frame, bytesConsumed } = decodeFrameFromBuffer(this.buffer);
+      yield frame;
+      this.buffer = this.buffer.subarray(bytesConsumed);
+    }
+  }
+
+  /** Reset decoder state, discarding any buffered data */
+  reset(): void {
+    this.buffer = new Uint8Array(0);
+  }
+
+  /** Number of bytes currently buffered */
+  get bufferedBytes(): number {
+    return this.buffer.length;
+  }
+}