@juspay/shooter 1.19.0 → 1.20.0

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,6 +15,7 @@ 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';
@@ -49,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;
@@ -71,9 +74,25 @@ export function setupWebSocketHandlers(
     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);
     });
@@ -84,13 +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';
 
@@ -41,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,
@@ -66,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;
   }
@@ -76,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;
   }
@@ -507,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);
@@ -518,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.',
@@ -535,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:
@@ -557,6 +566,11 @@ function wireClientMessages(ws: WebSocket, state: ConnectionState): void {
         }
 
         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/terminal-handler.ts

@@ -7,6 +7,7 @@ import type {
   TerminalPtyManagerLike as PtyManagerLike,
   WireTerminalServerMessage as ServerMessage,
   TerminalSignal,
+  TicketScope,
 } from '$lib/types';
 import type { WebSocket } from 'ws';
 
@@ -28,7 +29,11 @@ let _ptyManager: null | PtyManagerLike = null;
  * 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 {
+export function handleTerminalConnection(
+  ws: WebSocket,
+  terminalId: string,
+  scope?: TicketScope
+): void {
   // ── 1. Look up the terminal ──────────────────────────────────────
   if (!_ptyManager) {
     safeSend(ws, { message: 'PTY manager not initialised', type: 'error' });
@@ -62,6 +67,11 @@ export function handleTerminalConnection(ws: WebSocket, terminalId: string): voi
       return; // Silently ignore malformed messages.
     }
 
+    // View-only guests: every inbound frame type mutates the PTY — drop them all.
+    if (scope?.readOnly) {
+      return;
+    }
+
     // Don't allow input to exited terminals.
     if (terminal.status === 'exited') {
       safeSend(ws, { message: 'Terminal has exited', type: 'error' });
@@ -74,9 +84,18 @@ export function handleTerminalConnection(ws: WebSocket, terminalId: string): voi
           terminal.pty.write(msg.data);
           break;
 
-        case 'resize':
+        case 'resize': {
           terminal.pty.resize(msg.cols, msg.rows);
+          // Broadcast the new PTY size to the other attached clients so
+          // view-only guests can follow the owner's terminal dimensions.
+          const resizeMsg: ServerMessage = { cols: msg.cols, rows: msg.rows, type: 'resize' };
+          for (const client of terminal.clients) {
+            if (client !== ws) {
+              safeSend(client, resizeMsg);
+            }
+          }
           break;
+        }
 
         case 'signal': {
           if (msg.signal === 'SIGINT') {

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

@@ -5,7 +5,7 @@
 // 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 type { Ticket } from '$lib/types';
+import type { Ticket, TicketScope } from '$lib/types';
 
 import { randomBytes } from 'crypto';
 
@@ -21,32 +21,40 @@ const tickets: Map<string, Ticket> =
 /**
  * Generate a new single-use ticket (32-byte hex string).
  * The ticket is valid for 30 seconds and can only be consumed once.
+ * An optional scope restricts the ticket to one terminal's channels
+ * (and optionally to read-only access).
  */
-export function generateTicket(): string {
+export function generateTicket(scope?: TicketScope): string {
   const ticket = randomBytes(32).toString('hex');
-  tickets.set(ticket, { createdAt: Date.now(), used: false });
+  tickets.set(ticket, {
+    createdAt: Date.now(),
+    readOnly: scope?.readOnly ?? null,
+    terminalId: scope?.terminalId ?? null,
+    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.
+ * Returns the consumed Ticket (including any scope) if it is valid, not yet
+ * used, and not expired; otherwise null. A valid ticket is marked as used
+ * (single-use) and cannot be reused.
  */
-export function validateTicket(ticket: null | string): boolean {
+export function validateTicket(ticket: null | string): null | Ticket {
   if (!ticket) {
-    return false;
+    return null;
   }
   const entry = tickets.get(ticket);
   if (!entry || entry.used) {
-    return false;
+    return null;
   }
   if (Date.now() - entry.createdAt > 30_000) {
     tickets.delete(ticket);
-    return false;
+    return null;
   }
   entry.used = true;
-  return true;
+  return entry;
 }
 
 // Cleanup expired tickets every 30 seconds (matches ticket lifetime).

package/src/lib/types/generated/Client.ts

@@ -1,4 +1,4 @@
-import { type SessionSource, decodeSessionSource } from './index';
+import { type ShareMode, decodeShareMode, type SessionSource, decodeSessionSource } from './index';
 import {
   isJSON,
   decodeString,
@@ -307,6 +307,24 @@ export type TerminalDetailView = {
    * @memberof TerminalDetailView
    */
   sessionWs: string;
+  /**
+   * @description Current PTY width in columns (for fixed-size guest rendering)
+   * @type { number }
+   * @memberof TerminalDetailView
+   */
+  cols: number | null;
+  /**
+   * @description Current PTY height in rows (for fixed-size guest rendering)
+   * @type { number }
+   * @memberof TerminalDetailView
+   */
+  rows: number | null;
+  /**
+   * @description Present when fetched with a guest share token — the guest's access mode
+   * @type { ShareMode }
+   * @memberof TerminalDetailView
+   */
+  shareMode: ShareMode | null;
 };
 
 export function decodeTerminalDetailView(rawInput: unknown): TerminalDetailView | null {
@@ -325,6 +343,9 @@ export function decodeTerminalDetailView(rawInput: unknown): TerminalDetailView
     const decodedTimestamp = decodeString(rawInput['timestamp']);
     const decodedWs = decodeString(rawInput['ws']);
     const decodedSessionWs = decodeString(rawInput['sessionWs']);
+    const decodedCols = decodeNumber(rawInput['cols']);
+    const decodedRows = decodeNumber(rawInput['rows']);
+    const decodedShareMode = decodeShareMode(rawInput['shareMode']);
 
     if (
       decodedId === null ||
@@ -355,6 +376,9 @@ export function decodeTerminalDetailView(rawInput: unknown): TerminalDetailView
       timestamp: decodedTimestamp,
       ws: decodedWs,
       sessionWs: decodedSessionWs,
+      cols: decodedCols,
+      rows: decodedRows,
+      shareMode: decodedShareMode,
     };
   }
   return null;