@juspay/shooter 1.18.0 → 1.20.0

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;

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

@@ -0,0 +1,404 @@
+import {
+  isJSON,
+  decodeString,
+  _decodeString,
+  decodeNumber,
+  _decodeNumber,
+  decodeBoolean,
+  _decodeBoolean,
+} from 'type-decoder';
+
+/**
+ * @type { ShareMode }
+ * @description What a share guest may do — watch only, or full input control
+ */
+export type ShareMode = 'view' | 'control';
+
+export function decodeShareMode(rawInput: unknown): ShareMode | null {
+  switch (rawInput) {
+    case 'view':
+    case 'control':
+      return rawInput;
+  }
+  return null;
+}
+
+export function _decodeShareMode(rawInput: unknown): ShareMode | undefined {
+  switch (rawInput) {
+    case 'view':
+    case 'control':
+      return rawInput;
+  }
+  return;
+}
+
+/**
+ * @type { AccessLevel }
+ * @description Authorization level resolved for a terminal-scoped request
+ */
+export type AccessLevel = 'owner' | 'guest';
+
+export function decodeAccessLevel(rawInput: unknown): AccessLevel | null {
+  switch (rawInput) {
+    case 'owner':
+    case 'guest':
+      return rawInput;
+  }
+  return null;
+}
+
+export function _decodeAccessLevel(rawInput: unknown): AccessLevel | undefined {
+  switch (rawInput) {
+    case 'owner':
+    case 'guest':
+      return rawInput;
+  }
+  return;
+}
+
+/**
+ * @type { AccessContext }
+ * @description Resolved authorization for a terminal-scoped API request
+ */
+export type AccessContext = {
+  /**
+   * @description owner (API key) or guest (share session token)
+   * @type { AccessLevel }
+   * @memberof AccessContext
+   */
+  level: AccessLevel;
+  /**
+   * @description Guest access mode (present only when level is guest)
+   * @type { ShareMode }
+   * @memberof AccessContext
+   */
+  mode: ShareMode | null;
+};
+
+export function decodeAccessContext(rawInput: unknown): AccessContext | null {
+  if (isJSON(rawInput)) {
+    const decodedLevel = decodeAccessLevel(rawInput['level']);
+    const decodedMode = decodeShareMode(rawInput['mode']);
+
+    if (decodedLevel === null) {
+      return null;
+    }
+
+    return {
+      level: decodedLevel,
+      mode: decodedMode,
+    };
+  }
+  return null;
+}
+
+/**
+ * @type { TerminalShareRecord }
+ * @description Persisted share configuration for one terminal (terminal_shares table)
+ */
+export type TerminalShareRecord = {
+  /**
+   * @description Terminal this share belongs to (primary key)
+   * @type { string }
+   * @memberof TerminalShareRecord
+   */
+  terminalId: string;
+  /**
+   * @description scrypt:<salt-hex>:<hash-hex> password hash
+   * @type { string }
+   * @memberof TerminalShareRecord
+   */
+  passwordHash: string;
+  /**
+   * @description Access mode granted to guests
+   * @type { ShareMode }
+   * @memberof TerminalShareRecord
+   */
+  mode: ShareMode;
+  /**
+   * @description Unix timestamp (ms) when the share was created
+   * @type { number }
+   * @memberof TerminalShareRecord
+   */
+  createdAt: number;
+  /**
+   * @description Unix timestamp (ms) when the share was last updated
+   * @type { number }
+   * @memberof TerminalShareRecord
+   */
+  updatedAt: number;
+};
+
+export function decodeTerminalShareRecord(rawInput: unknown): TerminalShareRecord | null {
+  if (isJSON(rawInput)) {
+    const decodedTerminalId = decodeString(rawInput['terminalId']);
+    const decodedPasswordHash = decodeString(rawInput['passwordHash']);
+    const decodedMode = decodeShareMode(rawInput['mode']);
+    const decodedCreatedAt = decodeNumber(rawInput['createdAt']);
+    const decodedUpdatedAt = decodeNumber(rawInput['updatedAt']);
+
+    if (
+      decodedTerminalId === null ||
+      decodedPasswordHash === null ||
+      decodedMode === null ||
+      decodedCreatedAt === null ||
+      decodedUpdatedAt === null
+    ) {
+      return null;
+    }
+
+    return {
+      terminalId: decodedTerminalId,
+      passwordHash: decodedPasswordHash,
+      mode: decodedMode,
+      createdAt: decodedCreatedAt,
+      updatedAt: decodedUpdatedAt,
+    };
+  }
+  return null;
+}
+
+/**
+ * @type { ShareSessionRecord }
+ * @description Persisted guest session (share_sessions table); token stored as sha256 hash
+ */
+export type ShareSessionRecord = {
+  /**
+   * @description sha256 hex of the guest bearer token (primary key)
+   * @type { string }
+   * @memberof ShareSessionRecord
+   */
+  tokenHash: string;
+  /**
+   * @description Terminal the session grants access to
+   * @type { string }
+   * @memberof ShareSessionRecord
+   */
+  terminalId: string;
+  /**
+   * @description Unix timestamp (ms) when the session was created
+   * @type { number }
+   * @memberof ShareSessionRecord
+   */
+  createdAt: number;
+  /**
+   * @description Unix timestamp (ms) when the session expires (created + 7 days)
+   * @type { number }
+   * @memberof ShareSessionRecord
+   */
+  expiresAt: number;
+};
+
+export function decodeShareSessionRecord(rawInput: unknown): ShareSessionRecord | null {
+  if (isJSON(rawInput)) {
+    const decodedTokenHash = decodeString(rawInput['tokenHash']);
+    const decodedTerminalId = decodeString(rawInput['terminalId']);
+    const decodedCreatedAt = decodeNumber(rawInput['createdAt']);
+    const decodedExpiresAt = decodeNumber(rawInput['expiresAt']);
+
+    if (
+      decodedTokenHash === null ||
+      decodedTerminalId === null ||
+      decodedCreatedAt === null ||
+      decodedExpiresAt === null
+    ) {
+      return null;
+    }
+
+    return {
+      tokenHash: decodedTokenHash,
+      terminalId: decodedTerminalId,
+      createdAt: decodedCreatedAt,
+      expiresAt: decodedExpiresAt,
+    };
+  }
+  return null;
+}
+
+/**
+ * @type { ShareInfoResponse }
+ * @description Owner view of a terminal's share state (GET /api/terminals/[id]/share)
+ */
+export type ShareInfoResponse = {
+  /**
+   * @description Whether sharing is currently enabled for this terminal
+   * @type { boolean }
+   * @memberof ShareInfoResponse
+   */
+  active: boolean;
+  /**
+   * @description Current access mode (present when active)
+   * @type { ShareMode }
+   * @memberof ShareInfoResponse
+   */
+  mode: ShareMode | null;
+  /**
+   * @description Unix timestamp (ms) when the share was created (present when active)
+   * @type { number }
+   * @memberof ShareInfoResponse
+   */
+  createdAt: number | null;
+  /**
+   * @description Unix timestamp (ms) when the share was last updated (present when active)
+   * @type { number }
+   * @memberof ShareInfoResponse
+   */
+  updatedAt: number | null;
+};
+
+export function decodeShareInfoResponse(rawInput: unknown): ShareInfoResponse | null {
+  if (isJSON(rawInput)) {
+    const decodedActive = decodeBoolean(rawInput['active']);
+    const decodedMode = decodeShareMode(rawInput['mode']);
+    const decodedCreatedAt = decodeNumber(rawInput['createdAt']);
+    const decodedUpdatedAt = decodeNumber(rawInput['updatedAt']);
+
+    if (decodedActive === null) {
+      return null;
+    }
+
+    return {
+      active: decodedActive,
+      mode: decodedMode,
+      createdAt: decodedCreatedAt,
+      updatedAt: decodedUpdatedAt,
+    };
+  }
+  return null;
+}
+
+/**
+ * @type { ShareStatusResponse }
+ * @description Public probe response (GET /api/terminals/[id]/share/status)
+ */
+export type ShareStatusResponse = {
+  /**
+   * @description Whether a share exists for this terminal
+   * @type { boolean }
+   * @memberof ShareStatusResponse
+   */
+  shared: boolean;
+};
+
+export function decodeShareStatusResponse(rawInput: unknown): ShareStatusResponse | null {
+  if (isJSON(rawInput)) {
+    const decodedShared = decodeBoolean(rawInput['shared']);
+
+    if (decodedShared === null) {
+      return null;
+    }
+
+    return {
+      shared: decodedShared,
+    };
+  }
+  return null;
+}
+
+/**
+ * @type { ShareAuthRequest }
+ * @description Guest password exchange request (POST /api/terminals/[id]/share/auth)
+ */
+export type ShareAuthRequest = {
+  /**
+   * @description The share password
+   * @type { string }
+   * @memberof ShareAuthRequest
+   */
+  password: string;
+};
+
+export function decodeShareAuthRequest(rawInput: unknown): ShareAuthRequest | null {
+  if (isJSON(rawInput)) {
+    const decodedPassword = decodeString(rawInput['password']);
+
+    if (decodedPassword === null) {
+      return null;
+    }
+
+    return {
+      password: decodedPassword,
+    };
+  }
+  return null;
+}
+
+/**
+ * @type { ShareAuthResponse }
+ * @description Guest session issued after successful password exchange
+ */
+export type ShareAuthResponse = {
+  /**
+   * @description Guest bearer token (64-char hex, shown once)
+   * @type { string }
+   * @memberof ShareAuthResponse
+   */
+  token: string;
+  /**
+   * @description Access mode granted by this session
+   * @type { ShareMode }
+   * @memberof ShareAuthResponse
+   */
+  mode: ShareMode;
+  /**
+   * @description Unix timestamp (ms) when this session expires
+   * @type { number }
+   * @memberof ShareAuthResponse
+   */
+  expiresAt: number;
+};
+
+export function decodeShareAuthResponse(rawInput: unknown): ShareAuthResponse | null {
+  if (isJSON(rawInput)) {
+    const decodedToken = decodeString(rawInput['token']);
+    const decodedMode = decodeShareMode(rawInput['mode']);
+    const decodedExpiresAt = decodeNumber(rawInput['expiresAt']);
+
+    if (decodedToken === null || decodedMode === null || decodedExpiresAt === null) {
+      return null;
+    }
+
+    return {
+      token: decodedToken,
+      mode: decodedMode,
+      expiresAt: decodedExpiresAt,
+    };
+  }
+  return null;
+}
+
+/**
+ * @type { ShareConfigRequest }
+ * @description Owner create/update share request (PUT /api/terminals/[id]/share)
+ */
+export type ShareConfigRequest = {
+  /**
+   * @description New share password (min 6 chars; required on create, optional on update)
+   * @type { string }
+   * @memberof ShareConfigRequest
+   */
+  password: string | null;
+  /**
+   * @description Access mode to grant guests
+   * @type { ShareMode }
+   * @memberof ShareConfigRequest
+   */
+  mode: ShareMode;
+};
+
+export function decodeShareConfigRequest(rawInput: unknown): ShareConfigRequest | null {
+  if (isJSON(rawInput)) {
+    const decodedPassword = decodeString(rawInput['password']);
+    const decodedMode = decodeShareMode(rawInput['mode']);
+
+    if (decodedMode === null) {
+      return null;
+    }
+
+    return {
+      password: decodedPassword,
+      mode: decodedMode,
+    };
+  }
+  return null;
+}

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

@@ -435,7 +435,8 @@ export type TerminalServerMessage =
   | CTerminalServerMessageTerminalOutputDroppedMessage
   | CTerminalServerMessageTerminalScrollbackMessage
   | CTerminalServerMessageTerminalExitMessage
-  | CTerminalServerMessageTerminalErrorMessage;
+  | CTerminalServerMessageTerminalErrorMessage
+  | CTerminalServerMessageTerminalResizeMessage;
 
 export function decodeTerminalServerMessage(rawInput: unknown): TerminalServerMessage | null {
   const result: TerminalServerMessage | null =
@@ -443,7 +444,8 @@ export function decodeTerminalServerMessage(rawInput: unknown): TerminalServerMe
     decodeCTerminalServerMessageTerminalOutputDroppedMessage(rawInput) ??
     decodeCTerminalServerMessageTerminalScrollbackMessage(rawInput) ??
     decodeCTerminalServerMessageTerminalExitMessage(rawInput) ??
-    decodeCTerminalServerMessageTerminalErrorMessage(rawInput);
+    decodeCTerminalServerMessageTerminalErrorMessage(rawInput) ??
+    decodeCTerminalServerMessageTerminalResizeMessage(rawInput);
 
   return result;
 }
@@ -533,6 +535,23 @@ export function decodeCTerminalServerMessageTerminalErrorMessage(
   return new CTerminalServerMessageTerminalErrorMessage(result);
 }
 
+export class CTerminalServerMessageTerminalResizeMessage {
+  data: TerminalResizeMessage;
+  constructor(data: TerminalResizeMessage) {
+    this.data = data;
+  }
+}
+
+export function decodeCTerminalServerMessageTerminalResizeMessage(
+  rawInput: unknown
+): CTerminalServerMessageTerminalResizeMessage | null {
+  const result = decodeTerminalResizeMessage(rawInput);
+  if (result === null) {
+    return null;
+  }
+  return new CTerminalServerMessageTerminalResizeMessage(result);
+}
+
 /**
  * @type { TextContentBlock }
  * @description Content block in the live 'message' payload
@@ -2326,12 +2345,26 @@ export type Ticket = {
    * @memberof Ticket
    */
   used: boolean;
+  /**
+   * @description When set, the ticket may only open WS channels for this terminal
+   * @type { string }
+   * @memberof Ticket
+   */
+  terminalId: string | null;
+  /**
+   * @description When true, input/resize/signal/send-input/cancel frames are dropped
+   * @type { boolean }
+   * @memberof Ticket
+   */
+  readOnly: boolean | null;
 };
 
 export function decodeTicket(rawInput: unknown): Ticket | null {
   if (isJSON(rawInput)) {
     const decodedCreatedAt = decodeNumber(rawInput['createdAt']);
     const decodedUsed = decodeBoolean(rawInput['used']);
+    const decodedTerminalId = decodeString(rawInput['terminalId']);
+    const decodedReadOnly = decodeBoolean(rawInput['readOnly']);
 
     if (decodedCreatedAt === null || decodedUsed === null) {
       return null;
@@ -2340,6 +2373,44 @@ export function decodeTicket(rawInput: unknown): Ticket | null {
     return {
       createdAt: decodedCreatedAt,
       used: decodedUsed,
+      terminalId: decodedTerminalId,
+      readOnly: decodedReadOnly,
+    };
+  }
+  return null;
+}
+
+/**
+ * @type { TicketScope }
+ * @description Scope restriction carried by a guest WebSocket ticket
+ */
+export type TicketScope = {
+  /**
+   * @description Only WS channels for this terminal may be opened
+   * @type { string }
+   * @memberof TicketScope
+   */
+  terminalId: string;
+  /**
+   * @description Whether the connection is view-only (input frames dropped)
+   * @type { boolean }
+   * @memberof TicketScope
+   */
+  readOnly: boolean;
+};
+
+export function decodeTicketScope(rawInput: unknown): TicketScope | null {
+  if (isJSON(rawInput)) {
+    const decodedTerminalId = decodeString(rawInput['terminalId']);
+    const decodedReadOnly = decodeBoolean(rawInput['readOnly']);
+
+    if (decodedTerminalId === null || decodedReadOnly === null) {
+      return null;
+    }
+
+    return {
+      terminalId: decodedTerminalId,
+      readOnly: decodedReadOnly,
     };
   }
   return null;

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

@@ -10,3 +10,4 @@ export * from './OpenCode';
 export * from './Notification';
 export * from './Client';
 export * from './Config';
+export * from './Share';

package/src/lib/types/index.ts

@@ -12,8 +12,8 @@ export type * from './gemini';
 export * from './generated';
 export type * from './neurolink';
 export type * from './server';
-
 export type * from './sessions';
+
 // Explicit re-exports to resolve conflicts between generated types and the
 // hand-written sessions.ts versions. The generated Sessions module exports
 // wrapper-class variants (CMessagePartTextPart, etc.) with `type: string`
@@ -27,5 +27,6 @@ export type {
   ToolResultPart,
   ToolUsePart,
 } from './sessions';
+export type * from './sos';
 export type * from './terminal-client';
 export type * from './ws';