@juspay/shooter 1.0.0

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

@@ -0,0 +1,197 @@
+// WebSocket handler for /ws/terminal/:id — raw PTY I/O stream.
+// Relays terminal output to connected clients and routes client input
+// (keystrokes, resize, signals) back to the PTY.
+
+import type { WebSocket } from 'ws';
+
+// ── Types ────────────────────────────────────────────────────────────
+
+/** Inbound messages from the client. */
+type ClientMessage =
+  | { cols: number; rows: number; type: 'resize'; }
+  | { data: string; type: 'input'; }
+  | { signal: 'SIGINT' | 'SIGTERM' | 'SIGTSTP'; type: 'signal'; };
+
+/** Outbound messages to the client. */
+type ServerMessage =
+  | { bytes: number; type: 'output-dropped'; }
+  | { chunk: number; data: string; total: number; type: 'scrollback'; }
+  | { code: null | number; signal: null | string; type: 'exit'; }
+  | { data: string; type: 'output'; }
+  | { message: string; type: 'error'; };
+
+// ── Constants ────────────────────────────────────────────────────────
+
+/** Signal name → numeric code for process.kill(). */
+const SIGNAL_MAP: Record<string, NodeJS.Signals> = {
+  SIGINT: 'SIGINT',
+  SIGTERM: 'SIGTERM',
+  SIGTSTP: 'SIGTSTP',
+};
+
+// ── PTY Manager interface ────────────────────────────────────────────
+// Minimal duck-typed interface matching the real pty-manager singleton.
+
+interface ManagedTerminal {
+  clients: Set<WebSocket>;
+  exitCode: null | number;
+  id: string;
+  pty: {
+    kill: (signal: string) => void;
+    pid: number;
+    resize: (cols: number, rows: number) => void;
+    write: (data: string) => void;
+  };
+  status: 'exited' | 'running';
+}
+
+interface PtyManagerLike {
+  attach: (id: string, ws: WebSocket) => boolean;
+  detach: (id: string, ws: WebSocket) => boolean;
+  getTerminal: (id: string) => ManagedTerminal | undefined;
+}
+
+// Placeholder: will be replaced with the real ptyManager singleton import.
+// import { ptyManager } from '../terminal/pty-manager';
+let _ptyManager: null | PtyManagerLike = null;
+
+/**
+ * Handle a new WebSocket connection on the `/ws/terminal/:id` channel.
+ * Attaches the client to the terminal's viewer set, replays scrollback,
+ * and relays PTY I/O bidirectionally.
+ */
+export function handleTerminalConnection(ws: WebSocket, terminalId: string): void {
+  // ── 1. Look up the terminal ──────────────────────────────────────
+  if (!_ptyManager) {
+    safeSend(ws, { message: 'PTY manager not initialised', type: 'error' });
+    ws.close(1011, 'PTY manager not initialised');
+    return;
+  }
+
+  const terminal = _ptyManager.getTerminal(terminalId);
+  if (!terminal) {
+    safeSend(ws, { message: `Terminal not found: ${terminalId}`, type: 'error' });
+    ws.close(1008, 'Terminal not found');
+    return;
+  }
+
+  // ── 2. Attach via pty-manager (registers client + sends scrollback) ──
+  // The pty-manager's attach() adds ws to terminal.clients AND
+  // terminal.outputBuffers, then replays scrollback. Its broadcastOutput()
+  // loop delivers all PTY output — no per-client onData listener needed.
+  _ptyManager.attach(terminalId, ws);
+
+  // If the terminal already exited, tell the client immediately.
+  if (terminal.status === 'exited') {
+    safeSend(ws, { code: terminal.exitCode, signal: null, type: 'exit' });
+  }
+
+  // ── 3. Handle messages from the client ───────────────────────────
+  ws.on('message', (raw: Buffer | string) => {
+    const data = typeof raw === 'string' ? raw : raw.toString('utf-8');
+    const msg = parseClientMessage(data);
+    if (!msg) {
+      return; // Silently ignore malformed messages.
+    }
+
+    // Don't allow input to exited terminals.
+    if (terminal.status === 'exited') {
+      safeSend(ws, { message: 'Terminal has exited', type: 'error' });
+      return;
+    }
+
+    try {
+      switch (msg.type) {
+        case 'input':
+          terminal.pty.write(msg.data);
+          break;
+
+        case 'resize':
+          terminal.pty.resize(msg.cols, msg.rows);
+          break;
+
+        case 'signal': {
+          if (msg.signal === 'SIGINT') {
+            terminal.pty.write('\x03');
+          } else if (msg.signal === 'SIGTSTP') {
+            terminal.pty.write('\x1a');
+          } else if (msg.signal === 'SIGTERM') {
+            terminal.pty.kill('SIGTERM');
+          }
+          break;
+        }
+      }
+    } catch (err) {
+      const errMsg = err instanceof Error ? err.message : String(err);
+      console.error(`[ws/terminal] Error handling ${msg.type} for ${terminalId}:`, errMsg);
+      safeSend(ws, { message: `Failed to handle ${msg.type}: ${errMsg}`, type: 'error' });
+    }
+  });
+
+  // ── 4. Cleanup on disconnect ─────────────────────────────────────
+  ws.on('close', () => {
+    _ptyManager?.detach(terminalId, ws);
+  });
+
+  ws.on('error', () => {
+    // Errors are followed by 'close', which handles cleanup.
+    // This handler prevents unhandled error crashes.
+  });
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────
+
+/**
+ * Register the PTY manager instance. Called once during server bootstrap
+ * after the PTY manager is initialised.
+ */
+export function setPtyManager(manager: PtyManagerLike): void {
+  _ptyManager = manager;
+}
+
+/** Parse and validate an inbound client message. Returns null for invalid messages. */
+function parseClientMessage(raw: string): ClientMessage | null {
+  try {
+    const msg = JSON.parse(raw);
+    if (!msg || typeof msg !== 'object' || typeof msg.type !== 'string') {
+      return null;
+    }
+
+    switch (msg.type) {
+      case 'input':
+        if (typeof msg.data !== 'string') {return null;}
+        return { data: msg.data, type: 'input' };
+      case 'resize':
+        if (typeof msg.cols !== 'number' || typeof msg.rows !== 'number') {return null;}
+        if (msg.cols < 1 || msg.rows < 1 || msg.cols > 500 || msg.rows > 200) {return null;}
+        return { cols: Math.floor(msg.cols), rows: Math.floor(msg.rows), type: 'resize' };
+      case 'signal':
+        if (typeof msg.signal !== 'string' || !(msg.signal in SIGNAL_MAP)) {return null;}
+        return {
+          signal: msg.signal as ClientMessage & { type: 'signal' } extends { signal: infer S }
+            ? S
+            : never,
+          type: 'signal',
+        };
+      default:
+        return null;
+    }
+  } catch {
+    return null;
+  }
+}
+
+// ── Main handler ─────────────────────────────────────────────────────
+
+/** Safely send a JSON message over a WebSocket. */
+function safeSend(ws: WebSocket, msg: ServerMessage): boolean {
+  try {
+    if (ws.readyState !== 1 /* OPEN */) {
+      return false;
+    }
+    ws.send(JSON.stringify(msg));
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/lib/modules/server/ws/ticket-store.ts

@@ -0,0 +1,58 @@
+// WebSocket ticket store.
+// Generates short-lived, single-use tickets for authenticating WebSocket upgrades.
+// Tickets expire after 30 seconds and are cleaned up every 60 seconds.
+//
+// This avoids putting the long-lived API_KEY in WebSocket URL query parameters,
+// which would appear in proxy logs, Cloudflare access logs, and browser history.
+
+import { randomBytes } from 'crypto';
+
+interface Ticket {
+	createdAt: number;
+	used: boolean;
+}
+
+// Use globalThis to ensure a single shared Map across module instances.
+// server.ts (via tsx) and SvelteKit's build handler load this module separately,
+// creating two different module scopes. globalThis bridges them.
+const GLOBAL_KEY = '__shooter_ws_tickets';
+const tickets: Map<string, Ticket> =
+	(globalThis as Record<string, unknown>)[GLOBAL_KEY] as Map<string, Ticket> ||
+	new Map<string, Ticket>();
+(globalThis as Record<string, unknown>)[GLOBAL_KEY] = tickets;
+
+/**
+ * Generate a new single-use ticket (32-byte hex string).
+ * The ticket is valid for 30 seconds and can only be consumed once.
+ */
+export function generateTicket(): string {
+	const ticket = randomBytes(32).toString('hex');
+	tickets.set(ticket, { createdAt: Date.now(), used: false });
+	return ticket;
+}
+
+/**
+ * Validate and consume a ticket.
+ * Returns true if the ticket is valid, not yet used, and not expired.
+ * A valid ticket is marked as used (single-use) and cannot be reused.
+ */
+export function validateTicket(ticket: null | string): boolean {
+	if (!ticket) {return false;}
+	const entry = tickets.get(ticket);
+	if (!entry || entry.used) {return false;}
+	if (Date.now() - entry.createdAt > 30_000) {
+		tickets.delete(ticket);
+		return false;
+	}
+	entry.used = true;
+	return true;
+}
+
+// Cleanup expired tickets every 60 seconds.
+// .unref() ensures this timer does not prevent Node.js from exiting.
+setInterval(() => {
+	const now = Date.now();
+	for (const [key, val] of tickets) {
+		if (now - val.createdAt > 60_000) {tickets.delete(key);}
+	}
+}, 60_000).unref();