@juspay/shooter 1.19.0 → 1.20.0

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/terminal-client.ts

@@ -80,12 +80,24 @@ export interface QuickKeysProps {
 
 // --- keyboard-shortcuts types ---
 
-export interface ShortcutManagerOptions {
-  onHelp: () => void;
+export interface ShareGateProps {
+  /** Returns an error message to display, or null on success. */
+  onSubmit: (password: string) => Promise<null | string>;
 }
 
 // --- xterm-wrapper types ---
 
+export interface ShareSheetProps {
+  onClose: () => void;
+  open?: boolean;
+  shareUrl: string;
+  terminalId: string;
+}
+
+export interface ShortcutManagerOptions {
+  onHelp: () => void;
+}
+
 export interface ShortcutsHelpProps {
   onClose: () => void;
   open: boolean;
@@ -105,11 +117,14 @@ export interface TerminalOptions {
   container: HTMLElement;
   fontSize?: number;
   getTicket: () => Promise<string>;
+  initialCols?: number;
+  initialRows?: number;
   onActivity?: (active: boolean) => void;
   onCwd?: (path: string) => void;
   onDisconnect?: () => void;
   onExit?: (code: number) => void;
   onReconnect?: () => void;
+  readOnly?: boolean;
   terminalId?: string;
   wsUrl: string;
 }
@@ -126,7 +141,9 @@ export interface WsTerminalInboundMessage {
   active?: boolean;
   bytes?: number;
   code?: number;
+  cols?: number;
   data?: string;
   path?: string;
+  rows?: number;
   type: string;
 }

package/src/lib/types/ws.ts

@@ -146,6 +146,7 @@ export type WireTerminalServerMessage =
   | { bytes: number; type: 'output-dropped' }
   | { chunk: number; data: string; total: number; type: 'scrollback' }
   | { code: null | number; signal: null | string; type: 'exit' }
+  | { cols: number; rows: number; type: 'resize' }
   | { data: string; type: 'output' }
   | { message: string; type: 'error' };
 

package/src/routes/api/terminals/[id]/+server.ts

@@ -1,6 +1,9 @@
 import { validateAuth } from '$lib/modules/server/auth';
 import { ptyManager } from '$lib/modules/server/terminal/pty-manager.js';
+import { resolveAccess } from '$lib/modules/server/terminal/share-auth';
+import { shareStore } from '$lib/modules/server/terminal/share-store';
 import { toErrorMessage } from '$lib/modules/server/utils/error';
+import { closeGuests } from '$lib/modules/server/ws/guest-registry';
 import { json } from '@sveltejs/kit';
 
 import type { RequestHandler } from './$types';
@@ -21,10 +24,11 @@ function lastScrollbackLine(scrollback: string): null | string {
 }
 
 // GET /api/terminals/:id — Get terminal details by ID
+// Accepts the API key (owner) or a share session token scoped to this terminal.
 export const GET: RequestHandler = ({ params, request }) => {
-  const authError = validateAuth(request);
-  if (authError) {
-    return authError;
+  const access = resolveAccess(request, params.id);
+  if (!access) {
+    return json({ error: 'Unauthorized' }, { status: 401 });
   }
 
   try {
@@ -37,6 +41,7 @@ export const GET: RequestHandler = ({ params, request }) => {
     return json({
       args: terminal.args,
       clientCount: terminal.clients.size,
+      cols: terminal.cols,
       command: terminal.command,
       createdAt: terminal.createdAt.toISOString(),
       cwd: terminal.cwd,
@@ -45,10 +50,12 @@ export const GET: RequestHandler = ({ params, request }) => {
       id: terminal.id,
       lastOutput: lastScrollbackLine(terminal.scrollback),
       pid: terminal.pid,
+      rows: terminal.rows,
       sessionWs: `/ws/session/${terminal.id}`,
       status: terminal.status,
       timestamp: new Date().toISOString(),
       ws: `/ws/terminal/${terminal.id}`,
+      ...(access.level === 'guest' ? { shareMode: access.mode } : {}),
     });
   } catch (error) {
     console.error('[terminals] Failed to get terminal:', toErrorMessage(error));
@@ -72,6 +79,8 @@ export const DELETE: RequestHandler = ({ params, request }) => {
 
     if (terminal.status === 'exited') {
       ptyManager.remove(params.id);
+      shareStore.deleteShare(params.id);
+      closeGuests(params.id);
       console.log(`[terminals] Removed exited terminal ${params.id}`);
       return json({
         removed: true,
@@ -81,6 +90,8 @@ export const DELETE: RequestHandler = ({ params, request }) => {
     }
 
     ptyManager.kill(params.id);
+    shareStore.deleteShare(params.id);
+    closeGuests(params.id);
 
     console.log(`[terminals] Killed terminal ${params.id} (pid=${terminal.pid})`);
 

package/src/routes/api/terminals/[id]/paste-image/+server.ts

@@ -1,4 +1,4 @@
-import { validateAuth } from '$lib/modules/server/auth';
+import { resolveAccess } from '$lib/modules/server/terminal/share-auth';
 import { toErrorMessage } from '$lib/modules/server/utils/error';
 import { json } from '@sveltejs/kit';
 import { mkdirSync, writeFileSync } from 'fs';
@@ -6,10 +6,14 @@ import { mkdirSync, writeFileSync } from 'fs';
 import type { RequestHandler } from './$types';
 
 // POST /api/terminals/[id]/paste-image — Write clipboard image for a terminal
+// Accepts the API key (owner) or a control-mode share token for this terminal.
 export const POST: RequestHandler = async ({ params, request }) => {
-  const authError = validateAuth(request);
-  if (authError) {
-    return authError;
+  const access = resolveAccess(request, params.id);
+  if (!access) {
+    return json({ error: 'Unauthorized' }, { status: 401 });
+  }
+  if (access.level === 'guest' && access.mode !== 'control') {
+    return json({ error: 'View-only access' }, { status: 403 });
   }
 
   const terminalId = params.id;

package/src/routes/api/terminals/[id]/resize/+server.ts

@@ -1,15 +1,19 @@
-import { validateAuth } from '$lib/modules/server/auth';
 import { ptyManager } from '$lib/modules/server/terminal/pty-manager.js';
+import { resolveAccess } from '$lib/modules/server/terminal/share-auth';
 import { toErrorMessage } from '$lib/modules/server/utils/error';
 import { json } from '@sveltejs/kit';
 
 import type { RequestHandler } from './$types';
 
 // POST /api/terminals/:id/resize — Resize terminal
+// Accepts the API key (owner) or a control-mode share token for this terminal.
 export const POST: RequestHandler = async ({ params, request }) => {
-  const authError = validateAuth(request);
-  if (authError) {
-    return authError;
+  const access = resolveAccess(request, params.id);
+  if (!access) {
+    return json({ error: 'Unauthorized' }, { status: 401 });
+  }
+  if (access.level === 'guest' && access.mode !== 'control') {
+    return json({ error: 'View-only access' }, { status: 403 });
   }
 
   let body: { cols?: number; rows?: number };