@juspay/shooter 1.18.0 → 1.20.0

package/src/lib/modules/server/terminal/pty-input.ts

@@ -0,0 +1,37 @@
+/**
+ * PTY input helpers.
+ *
+ * Submitting text to an interactive agent TUI (codex, claude, gemini, qwen, …)
+ * is not as simple as appending a newline. These TUIs read the PTY in raw mode:
+ *
+ *   - A bare LF (`\n`) is NOT the Enter key — it types a literal newline into
+ *     the prompt and never submits. (Verified: LF leaves codex sitting on its
+ *     prompt; the message just accumulates.)
+ *   - Even `"<text>\r"` written as a SINGLE chunk is treated as a bracketed
+ *     paste by the TUI, so the trailing CR is absorbed into the pasted body
+ *     instead of submitting. (Verified: codex types the text but does not run.)
+ *
+ * The reliable approach — the same bytes a real terminal emulator sends when a
+ * human pastes and presses Enter — is to wrap the body in an explicit bracketed
+ * paste (`ESC[200~` … `ESC[201~`) and then send a CR. The paste-end marker
+ * closes the paste unambiguously, so the following CR is a real Enter. This
+ * also preserves embedded newlines in multi-line messages (the whole point of
+ * bracketed paste) and submits correctly in modern interactive shells, where
+ * bracketed paste is enabled by default.
+ *
+ * Verified empirically against codex 0.136 and claude 2.1 — both receive the
+ * message and complete a turn.
+ */
+
+const PASTE_START = '\x1b[200~';
+const PASTE_END = '\x1b[201~';
+
+/**
+ * Build the PTY byte sequence that delivers `text` to an interactive terminal
+ * and submits it (presses Enter). Any trailing newline the caller added is
+ * stripped — the CR after the paste-end marker is what submits.
+ */
+export function ptySubmitSequence(text: string): string {
+  const body = text.replace(/[\r\n]+$/, '');
+  return `${PASTE_START}${body}${PASTE_END}\r`;
+}

package/src/lib/modules/server/terminal/pty-manager.ts

@@ -483,6 +483,12 @@ class PtyManager {
       terminal.pty.resize(cols, rows);
       terminal.cols = cols;
       terminal.rows = rows;
+      // Broadcast the new PTY size so attached clients (e.g. view-only
+      // guests) can follow the terminal dimensions.
+      const msg = JSON.stringify({ cols, rows, type: 'resize' });
+      for (const ws of terminal.clients) {
+        this.safeSend(ws, msg);
+      }
       return true;
     } catch {
       return false;

package/src/lib/modules/server/terminal/share-auth.ts

@@ -0,0 +1,37 @@
+// Resolves a terminal-scoped request to owner (API key) or guest (share token).
+// Kept separate from auth.ts so routes without share semantics don't pull in SQLite.
+
+import type { AccessContext } from '$lib/types';
+
+import { validateAuth } from '../auth';
+import { shareStore } from './share-store';
+
+/** Extract the Bearer token from a request, or null. */
+export function bearerToken(request: Request): null | string {
+  const auth = request.headers.get('Authorization') || request.headers.get('authorization');
+  if (!auth?.startsWith('Bearer ')) {
+    return null;
+  }
+  return auth.slice(7).trim();
+}
+
+/**
+ * Resolve access for a request targeting one terminal.
+ * Owner (valid API key) → { level: 'owner' }.
+ * Guest (valid share session for THIS terminal) → { level: 'guest', mode }.
+ * Anything else → null.
+ */
+export function resolveAccess(request: Request, terminalId: string): AccessContext | null {
+  if (validateAuth(request) === null) {
+    return { level: 'owner', mode: null };
+  }
+  const token = bearerToken(request);
+  if (!token) {
+    return null;
+  }
+  const session = shareStore.resolveToken(token);
+  if (session?.terminalId !== terminalId) {
+    return null;
+  }
+  return { level: 'guest', mode: session.mode };
+}

package/src/lib/modules/server/terminal/share-store.ts

@@ -0,0 +1,172 @@
+/**
+ * Share Store — SQLite persistence for terminal sharing.
+ *
+ * terminal_shares: one share per terminal (scrypt password hash + mode).
+ * share_sessions:  guest sessions keyed by sha256(token), 7-day TTL.
+ *
+ * Database location: ~/.shooter/shooter.db (same file as terminal-store).
+ */
+
+import type { ShareMode, TerminalShareRecord } from '$lib/types';
+
+import Database from 'better-sqlite3';
+import { createHash, randomBytes, scryptSync, timingSafeEqual } from 'crypto';
+import * as fs from 'fs';
+import * as path from 'path';
+
+const DB_DIR = path.join(process.env.HOME || '', '.shooter');
+const DB_PATH = path.join(DB_DIR, 'shooter.db');
+
+const SESSION_TTL_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
+
+// ── Password hashing (scrypt, per-share random salt) ─────────────────
+
+export class ShareStore {
+  private db: Database.Database;
+
+  constructor() {
+    fs.mkdirSync(DB_DIR, { recursive: true });
+    this.db = new Database(DB_PATH);
+    this.db.pragma('journal_mode = WAL');
+
+    this.db.exec(`
+			CREATE TABLE IF NOT EXISTS terminal_shares (
+				terminal_id   TEXT PRIMARY KEY,
+				password_hash TEXT NOT NULL,
+				mode          TEXT NOT NULL,
+				created_at    INTEGER NOT NULL,
+				updated_at    INTEGER NOT NULL
+			);
+			CREATE TABLE IF NOT EXISTS share_sessions (
+				token_hash  TEXT PRIMARY KEY,
+				terminal_id TEXT NOT NULL,
+				created_at  INTEGER NOT NULL,
+				expires_at  INTEGER NOT NULL
+			)
+		`);
+
+    this.cleanup();
+  }
+
+  /** Purge expired sessions and shares whose terminal no longer exists. */
+  cleanup(): void {
+    this.db.prepare('DELETE FROM share_sessions WHERE expires_at < ?').run(Date.now());
+    try {
+      this.db
+        .prepare('DELETE FROM terminal_shares WHERE terminal_id NOT IN (SELECT id FROM terminals)')
+        .run();
+      this.db
+        .prepare('DELETE FROM share_sessions WHERE terminal_id NOT IN (SELECT id FROM terminals)')
+        .run();
+    } catch {
+      // terminals table may not exist yet on a fresh database — skip orphan cleanup.
+    }
+  }
+
+  /** Issue a new guest session for a shared terminal. Returns the raw token (stored hashed). */
+  createSession(terminalId: string): { expiresAt: number; token: string } {
+    const token = randomBytes(32).toString('hex');
+    const now = Date.now();
+    const expiresAt = now + SESSION_TTL_MS;
+    this.db
+      .prepare(
+        'INSERT INTO share_sessions (token_hash, terminal_id, created_at, expires_at) VALUES (?, ?, ?, ?)'
+      )
+      .run(hashToken(token), terminalId, now, expiresAt);
+    return { expiresAt, token };
+  }
+
+  /** Delete all guest sessions for a terminal (password change / revoke). */
+  deleteSessions(terminalId: string): void {
+    this.db.prepare('DELETE FROM share_sessions WHERE terminal_id = ?').run(terminalId);
+  }
+
+  /** Revoke a share: delete the share row and every guest session for it. */
+  deleteShare(terminalId: string): void {
+    this.db.prepare('DELETE FROM terminal_shares WHERE terminal_id = ?').run(terminalId);
+    this.deleteSessions(terminalId);
+  }
+
+  getShare(terminalId: string): null | TerminalShareRecord {
+    const row = this.db
+      .prepare('SELECT * FROM terminal_shares WHERE terminal_id = ?')
+      .get(terminalId) as Record<string, unknown> | undefined;
+    return row ? rowToShare(row) : null;
+  }
+
+  /**
+   * Resolve a guest bearer token to its terminal + mode.
+   * Returns null if unknown, expired, or the share was revoked.
+   */
+  resolveToken(token: string): null | { mode: ShareMode; terminalId: string } {
+    if (!token) {
+      return null;
+    }
+    const row = this.db
+      .prepare(
+        `SELECT s.terminal_id, s.expires_at, sh.mode
+				 FROM share_sessions s
+				 JOIN terminal_shares sh ON sh.terminal_id = s.terminal_id
+				 WHERE s.token_hash = ?`
+      )
+      .get(hashToken(token)) as Record<string, unknown> | undefined;
+    if (!row) {
+      return null;
+    }
+    if ((row.expires_at as number) < Date.now()) {
+      this.db.prepare('DELETE FROM share_sessions WHERE token_hash = ?').run(hashToken(token));
+      return null;
+    }
+    return { mode: row.mode as ShareMode, terminalId: row.terminal_id as string };
+  }
+
+  /** Create or replace the share for a terminal. */
+  setShare(record: TerminalShareRecord): void {
+    this.db
+      .prepare(
+        `INSERT OR REPLACE INTO terminal_shares
+				 (terminal_id, password_hash, mode, created_at, updated_at)
+				 VALUES (?, ?, ?, ?, ?)`
+      )
+      .run(record.terminalId, record.passwordHash, record.mode, record.createdAt, record.updatedAt);
+  }
+}
+
+export function hashPassword(password: string): string {
+  const salt = randomBytes(16).toString('hex');
+  const hash = scryptSync(password, salt, 64).toString('hex');
+  return `scrypt:${salt}:${hash}`;
+}
+
+export function verifyPassword(password: string, stored: string): boolean {
+  const parts = stored.split(':');
+  if (parts.length !== 3 || parts[0] !== 'scrypt') {
+    return false;
+  }
+  const expected = Buffer.from(parts[2], 'hex');
+  const actual = scryptSync(password, parts[1], 64);
+  return expected.length === actual.length && timingSafeEqual(actual, expected);
+}
+
+// ── Row mapping ──────────────────────────────────────────────────────
+
+function hashToken(token: string): string {
+  return createHash('sha256').update(token).digest('hex');
+}
+
+function rowToShare(row: Record<string, unknown>): TerminalShareRecord {
+  return {
+    createdAt: row.created_at as number,
+    mode: row.mode as ShareMode,
+    passwordHash: row.password_hash as string,
+    terminalId: row.terminal_id as string,
+    updatedAt: row.updated_at as number,
+  };
+}
+
+// ── Singleton (globalThis bridges tsx server.ts + SvelteKit handler) ─
+
+const SS_GLOBAL_KEY = '__shooter_share_store';
+export const shareStore: ShareStore =
+  ((globalThis as Record<string, unknown>)[SS_GLOBAL_KEY] as ShareStore) || new ShareStore();
+(globalThis as Record<string, unknown>)[SS_GLOBAL_KEY] = shareStore;

package/src/lib/modules/server/ws/guest-registry.ts

@@ -0,0 +1,49 @@
+// Tracks WebSocket connections opened with a guest (scoped) ticket, per terminal,
+// so revoke / mode-change / password-change can force-close them immediately.
+// globalThis bridges the tsx server.ts and SvelteKit handler module scopes.
+
+import type { WebSocket } from 'ws';
+
+const GUESTS_KEY = '__shooter_ws_guest_conns';
+const guests: Map<string, Set<WebSocket>> = ((globalThis as Record<string, unknown>)[
+  GUESTS_KEY
+] as Map<string, Set<WebSocket>>) || new Map<string, Set<WebSocket>>();
+(globalThis as Record<string, unknown>)[GUESTS_KEY] = guests;
+
+/** Force-close every guest connection for a terminal. Returns the number closed. */
+export function closeGuests(terminalId: string): number {
+  const set = guests.get(terminalId);
+  if (!set) {
+    return 0;
+  }
+  let closed = 0;
+  for (const ws of set) {
+    try {
+      ws.close(4001, 'Share revoked');
+      closed++;
+    } catch {
+      // Already closing/closed.
+    }
+  }
+  guests.delete(terminalId);
+  return closed;
+}
+
+/** Register a guest connection; auto-removes itself on close. */
+export function registerGuest(terminalId: string, ws: WebSocket): void {
+  let set = guests.get(terminalId);
+  if (!set) {
+    set = new Set<WebSocket>();
+    guests.set(terminalId, set);
+  }
+  set.add(ws);
+  ws.on('close', () => {
+    const current = guests.get(terminalId);
+    if (current) {
+      current.delete(ws);
+      if (current.size === 0) {
+        guests.delete(terminalId);
+      }
+    }
+  });
+}

package/src/lib/modules/server/ws/server.ts

@@ -5,6 +5,7 @@
 //   /ws/session/:id   -> Live structured session stream
 //   /ws/events         -> Global event bus (broadcasts)
 
+import type { TicketScope } from '$lib/types';
 import type { IncomingMessage } from 'http';
 import type { Duplex } from 'stream';
 import type { WebSocket, WebSocketServer } from 'ws';
@@ -14,7 +15,9 @@ import {
   getEventsClientCount,
   handleEventsConnection,
 } from './events-handler.js';
+import { registerGuest } from './guest-registry.js';
 import { handleSessionConnection } from './session-handler.js';
+import { handleSuperSessionConnection } from './super-session-handler.js';
 import { handleTerminalConnection } from './terminal-handler.js';
 export type { WireShooterEvent as ShooterEvent } from '$lib/types';
 
@@ -48,7 +51,8 @@ export function setupWebSocketHandlers(
   wss: WebSocketServer,
   request: IncomingMessage,
   socket: Duplex,
-  head: Buffer
+  head: Buffer,
+  scope?: TicketScope
 ): void {
   const host = request.headers.host ?? 'localhost';
   let pathname: string;
@@ -61,17 +65,34 @@ export function setupWebSocketHandlers(
 
   // Route matching
   const terminalMatch = /^\/ws\/terminal\/(.+)$/.exec(pathname);
+  const superSessionMatch = /^\/ws\/super-session\/(.+)$/.exec(pathname);
   const sessionMatch = /^\/ws\/session\/(.+)$/.exec(pathname);
   const isEvents = pathname === '/ws/events';
 
-  if (!terminalMatch && !sessionMatch && !isEvents) {
+  if (!terminalMatch && !superSessionMatch && !sessionMatch && !isEvents) {
     socket.destroy();
     return;
   }
 
+  // Scoped (guest) tickets may only open the terminal/session channels of
+  // their own terminal. Events and super-session channels broadcast global
+  // data, so they are denied outright.
+  if (scope) {
+    const target = terminalMatch?.[1] ?? sessionMatch?.[1];
+    if (!target || superSessionMatch || target !== scope.terminalId) {
+      socket.write('HTTP/1.1 403 Forbidden\r\n\r\n');
+      socket.destroy();
+      return;
+    }
+  }
+
   wss.handleUpgrade(request, socket, head, (ws: WebSocket) => {
     allConnections.add(ws);
 
+    if (scope) {
+      registerGuest(scope.terminalId, ws);
+    }
+
     ws.on('close', () => {
       allConnections.delete(ws);
     });
@@ -82,10 +103,13 @@ export function setupWebSocketHandlers(
 
     if (terminalMatch) {
       const terminalId = terminalMatch[1];
-      handleTerminalConnection(ws, terminalId);
+      handleTerminalConnection(ws, terminalId, scope);
+    } else if (superSessionMatch) {
+      const superSessionId = superSessionMatch[1];
+      handleSuperSessionConnection(ws, superSessionId);
     } else if (sessionMatch) {
       const sessionId = sessionMatch[1];
-      handleSessionConnection(ws, sessionId);
+      handleSessionConnection(ws, sessionId, scope);
     } else if (isEvents) {
       handleEventsConnection(ws);
     }

package/src/lib/modules/server/ws/session-handler.ts

@@ -16,6 +16,7 @@ import type {
   WireSessionServerMessage as ServerMessage,
   SessionWatcherLike,
   TextContentBlock,
+  TicketScope,
 } from '$lib/types';
 import type { WebSocket } from 'ws';
 
@@ -23,6 +24,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 
 import { findCodexRolloutById } from '../sessions/codex-reader';
+import { ptySubmitSequence } from '../terminal/pty-input';
 
 // ── Module-level references ──────────────────────────────────────────
 
@@ -40,7 +42,7 @@ let _sessionWatcher: null | SessionWatcherLike = null;
  * 3. If still no terminal, treat as an external session — find the JSONL
  *    file directly and stream it via the session watcher.
  */
-export function handleSessionConnection(ws: WebSocket, id: string): void {
+export function handleSessionConnection(ws: WebSocket, id: string, scope?: TicketScope): void {
   const state: ConnectionState = {
     isExternalSession: false,
     retryInterval: null,
@@ -65,7 +67,7 @@ export function handleSessionConnection(ws: WebSocket, id: string): void {
   if (terminal) {
     state.terminalId = terminal.id;
     subscribeToSession(ws, state, terminal);
-    wireClientMessages(ws, state);
+    wireClientMessages(ws, state, scope);
     wireCleanup(ws, state);
     return;
   }
@@ -75,7 +77,7 @@ export function handleSessionConnection(ws: WebSocket, id: string): void {
   if (jsonlPath) {
     state.isExternalSession = true;
     subscribeToExternalSession(ws, state, jsonlPath);
-    wireClientMessages(ws, state);
+    wireClientMessages(ws, state, scope);
     wireCleanup(ws, state);
     return;
   }
@@ -506,7 +508,7 @@ function wireCleanup(ws: WebSocket, state: ConnectionState): void {
  * Extracted so both terminal-backed and external sessions share the same
  * message loop.
  */
-function wireClientMessages(ws: WebSocket, state: ConnectionState): void {
+function wireClientMessages(ws: WebSocket, state: ConnectionState, scope?: TicketScope): void {
   ws.on('message', (raw: Buffer | string) => {
     const data = typeof raw === 'string' ? raw : raw.toString('utf-8');
     const msg = parseClientMessage(data);
@@ -517,6 +519,10 @@ function wireClientMessages(ws: WebSocket, state: ConnectionState): void {
     try {
       switch (msg.type) {
         case 'cancel': {
+          if (scope?.readOnly) {
+            safeSend(ws, { message: 'This shared terminal is view-only.', type: 'error' });
+            return;
+          }
           if (state.isExternalSession) {
             safeSend(ws, {
               message: 'Cannot cancel — this is a read-only session. Connect to a terminal first.',
@@ -534,6 +540,10 @@ function wireClientMessages(ws: WebSocket, state: ConnectionState): void {
         }
 
         case 'send-input': {
+          if (scope?.readOnly) {
+            safeSend(ws, { message: 'This shared terminal is view-only.', type: 'error' });
+            return;
+          }
           if (state.isExternalSession) {
             safeSend(ws, {
               message:
@@ -547,11 +557,20 @@ function wireClientMessages(ws: WebSocket, state: ConnectionState): void {
             safeSend(ws, { message: 'Terminal has exited', type: 'error' });
             return;
           }
-          currentTerminal.pty.write(`${msg.text}\n`);
+          // Deliver + submit via a bracketed paste (see pty-input.ts): a bare
+          // LF never submits to an agent TUI and a trailing CR in the same
+          // write is absorbed as paste content. Bracketed paste closes the
+          // paste explicitly so the following CR is a real Enter.
+          currentTerminal.pty.write(ptySubmitSequence(msg.text));
           break;
         }
 
         case 'subscribe': {
+          // Scoped guests may only (re)subscribe to their own terminal's session.
+          if (scope && msg.sessionId !== scope.terminalId) {
+            safeSend(ws, { message: 'Not authorized for this session.', type: 'error' });
+            return;
+          }
           // (Re)subscribe to a different session. Clean up the old subscription.
           if (state.retryInterval) {
             clearInterval(state.retryInterval);

package/src/lib/modules/server/ws/super-session-handler.ts

@@ -0,0 +1,200 @@
+// WebSocket handler for /ws/super-session/:id — the merged Session-Over-Sessions
+// stream. On connect it replays the merged transcript (sos-history) and then
+// streams live tagged messages from every member. Accepts human-driven control
+// messages: relay-forward (inject into a member's terminal), member-add,
+// member-remove. Mirrors session-handler.ts in shape.
+
+import type { SessionSource, SosClientMessage, SosServerMessage } from '$lib/types';
+import type { WebSocket } from 'ws';
+
+import * as path from 'path';
+
+import { PROVIDERS } from '../sessions/registry';
+import { sosCoordinator } from '../sos/coordinator';
+
+const MAX_RELAY_TEXT = 10240; // 10 KB, same cap as /ws/session send-input
+// Stop streaming to a client whose outbound buffer exceeds this — bounds memory
+// growth when a slow consumer can't drain sos-history replay or a live burst.
+const MAX_WS_BUFFERED_BYTES = 1_000_000;
+const VALID_SOURCES = new Set<string>(PROVIDERS.map((p) => p.source));
+
+export function handleSuperSessionConnection(ws: WebSocket, id: string): void {
+  const session = sosCoordinator.getSuperSession(id);
+  if (!session) {
+    safeSend(ws, { message: `Super-session not found: ${id}`, type: 'sos-error' });
+    ws.close(1008, 'Super-session not found');
+    return;
+  }
+
+  // subscribe() replays the current transcript as an sos-history message, then
+  // streams live sos-message / sos-member-* events. If a send fails (socket
+  // closed or buffer over cap), stop feeding this client to bound memory.
+  let unsubscribe: (() => void) | null = null;
+  unsubscribe = sosCoordinator.subscribe(id, (msg) => {
+    if (!safeSend(ws, msg)) {
+      unsubscribe?.();
+      unsubscribe = null;
+    }
+  });
+
+  ws.on('message', (raw: Buffer | string) => {
+    const data = typeof raw === 'string' ? raw : raw.toString('utf-8');
+    const msg = parseClientMessage(data);
+    if (!msg) {
+      // Surface schema drift instead of silently dropping the frame — a dead
+      // control in the UI is much harder to debug than an explicit error.
+      safeSend(ws, { message: 'Invalid super-session control message', type: 'sos-error' });
+      return;
+    }
+    handleClientMessage(ws, id, msg);
+  });
+
+  ws.on('close', () => {
+    unsubscribe?.();
+  });
+  ws.on('error', () => {
+    // cleanup happens in 'close'
+  });
+}
+
+/** True when the string is a known provider source. */
+export function isValidProvider(value: string): value is SessionSource {
+  return VALID_SOURCES.has(value);
+}
+
+/** True for a bare session id (OpenCode) or an absolute path under HOME. */
+export function isValidSessionKey(key: string): boolean {
+  if (/^[A-Za-z0-9_-]+$/.test(key)) {
+    return true;
+  }
+  const home = process.env.HOME || '';
+  if (home === '' || !path.isAbsolute(key)) {
+    return false;
+  }
+  // Resolve before comparing so `..` segments cannot escape the HOME sandbox
+  // (e.g. /home/user/../etc/passwd passes a raw prefix check but not this).
+  const relative = path.relative(path.resolve(home), path.resolve(key));
+  return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+}
+
+function handleClientMessage(ws: WebSocket, superSessionId: string, msg: SosClientMessage): void {
+  switch (msg.type) {
+    case 'member-add': {
+      const member = sosCoordinator.addMember(superSessionId, {
+        capability: msg.capability,
+        provider: msg.provider,
+        sessionKey: msg.sessionKey,
+        terminalId: msg.terminalId ?? null,
+      });
+      if (!member) {
+        safeSend(ws, { message: 'Failed to add member', type: 'sos-error' });
+      }
+      break;
+    }
+    case 'member-remove': {
+      const ok = sosCoordinator.removeMember(superSessionId, msg.memberId);
+      if (!ok) {
+        safeSend(ws, { message: 'Member not found', type: 'sos-error' });
+      }
+      break;
+    }
+    case 'relay-approve': {
+      if (!sosCoordinator.approveRelay(superSessionId, msg.relayId)) {
+        safeSend(ws, { message: 'Pending relay not found', type: 'sos-error' });
+      }
+      break;
+    }
+    case 'relay-deny': {
+      if (!sosCoordinator.denyRelay(superSessionId, msg.relayId)) {
+        safeSend(ws, { message: 'Pending relay not found', type: 'sos-error' });
+      }
+      break;
+    }
+    case 'relay-forward': {
+      const error = sosCoordinator.relayForward(superSessionId, msg.toMemberId, msg.text);
+      if (error) {
+        safeSend(ws, { message: error, type: 'sos-error' });
+      }
+      break;
+    }
+  }
+}
+
+function parseClientMessage(raw: string): null | SosClientMessage {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (typeof parsed !== 'object' || parsed === null) {
+    return null;
+  }
+  const msg = parsed as Record<string, unknown>;
+
+  switch (msg.type) {
+    case 'member-add': {
+      if (
+        typeof msg.sessionKey !== 'string' ||
+        !isValidSessionKey(msg.sessionKey) ||
+        typeof msg.provider !== 'string' ||
+        !isValidProvider(msg.provider)
+      ) {
+        return null;
+      }
+      return {
+        capability: typeof msg.capability === 'string' ? msg.capability : undefined,
+        provider: msg.provider,
+        sessionKey: msg.sessionKey,
+        terminalId: typeof msg.terminalId === 'string' ? msg.terminalId : undefined,
+        type: 'member-add',
+      };
+    }
+    case 'member-remove': {
+      if (typeof msg.memberId !== 'string' || msg.memberId.length === 0) {
+        return null;
+      }
+      return { memberId: msg.memberId, type: 'member-remove' };
+    }
+    case 'relay-approve': {
+      if (typeof msg.relayId !== 'string' || msg.relayId.length === 0) {
+        return null;
+      }
+      return { relayId: msg.relayId, type: 'relay-approve' };
+    }
+    case 'relay-deny': {
+      if (typeof msg.relayId !== 'string' || msg.relayId.length === 0) {
+        return null;
+      }
+      return { relayId: msg.relayId, type: 'relay-deny' };
+    }
+    case 'relay-forward': {
+      if (
+        typeof msg.toMemberId !== 'string' ||
+        typeof msg.text !== 'string' ||
+        msg.text.length === 0 ||
+        msg.text.length > MAX_RELAY_TEXT
+      ) {
+        return null;
+      }
+      return { text: msg.text, toMemberId: msg.toMemberId, type: 'relay-forward' };
+    }
+    default:
+      return null;
+  }
+}
+
+function safeSend(ws: WebSocket, msg: SosServerMessage): boolean {
+  try {
+    if (ws.readyState !== 1 /* OPEN */) {
+      return false;
+    }
+    if (ws.bufferedAmount > MAX_WS_BUFFERED_BYTES) {
+      return false;
+    }
+    ws.send(JSON.stringify(msg));
+    return true;
+  } catch {
+    return false;
+  }
+}