@juspay/shooter 1.19.0 → 1.21.0

package/src/lib/modules/server/sessions/summary-store.ts

@@ -0,0 +1,111 @@
+/**
+ * Summary Store — SQLite persistence for session summary records.
+ *
+ * Persists SessionSummaryRecord rows written by the autopilot engine after
+ * each summarise+consensus pipeline run. Uses better-sqlite3 with WAL journal
+ * mode, mirroring the pattern from terminal-store.ts.
+ *
+ * Database location: ~/.shooter/shooter.db (shared with terminal-store)
+ */
+
+import type { SessionSummaryRecord } from '$lib/types';
+
+import Database from 'better-sqlite3';
+import * as fs from 'fs';
+import * as path from 'path';
+
+// ── Constants ────────────────────────────────────────────────────────
+
+const DB_DIR = path.join(process.env.HOME || '', '.shooter');
+const DB_PATH = path.join(DB_DIR, 'shooter.db');
+
+// ── Column list ──────────────────────────────────────────────────────
+
+const COLUMNS = [
+  'id',
+  'terminal_id',
+  'session_id',
+  'project_name',
+  'summary',
+  'next_steps',
+  'trigger',
+  'created_at',
+] as const;
+
+// ── Row ↔ Record conversion ──────────────────────────────────────────
+
+export class SummaryStore {
+  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 session_summaries (
+        id           TEXT PRIMARY KEY,
+        terminal_id  TEXT,
+        session_id   TEXT,
+        project_name TEXT,
+        summary      TEXT NOT NULL,
+        next_steps   TEXT NOT NULL DEFAULT '[]',
+        trigger      TEXT NOT NULL,
+        created_at   TEXT NOT NULL
+      )
+    `);
+  }
+
+  insert(record: SessionSummaryRecord): void {
+    const placeholders = COLUMNS.map(() => '?').join(', ');
+    this.db
+      .prepare(`INSERT INTO session_summaries (${COLUMNS.join(', ')}) VALUES (${placeholders})`)
+      .run(
+        record.id,
+        record.terminalId,
+        record.sessionId,
+        record.projectName,
+        record.summary,
+        record.nextSteps,
+        record.trigger,
+        record.createdAt
+      );
+  }
+
+  listRecent(limit: number, sessionId?: string): SessionSummaryRecord[] {
+    if (sessionId) {
+      const rows = this.db
+        .prepare(
+          'SELECT * FROM session_summaries WHERE session_id = ? ORDER BY created_at DESC LIMIT ?'
+        )
+        .all(sessionId, limit) as Record<string, unknown>[];
+      return rows.map(rowToRecord);
+    }
+    const rows = this.db
+      .prepare('SELECT * FROM session_summaries ORDER BY created_at DESC LIMIT ?')
+      .all(limit) as Record<string, unknown>[];
+    return rows.map(rowToRecord);
+  }
+}
+
+// ── SummaryStore ─────────────────────────────────────────────────────
+
+function rowToRecord(row: Record<string, unknown>): SessionSummaryRecord {
+  return {
+    createdAt: row.created_at as string,
+    id: row.id as string,
+    nextSteps: row.next_steps as string,
+    projectName: (row.project_name as string) ?? null,
+    sessionId: (row.session_id as string) ?? null,
+    summary: row.summary as string,
+    terminalId: (row.terminal_id as string) ?? null,
+    trigger: row.trigger as string,
+  };
+}
+
+// ── Singleton ────────────────────────────────────────────────────────
+// Shared instance across module loaders (same pattern as terminal-store).
+
+const SS_GLOBAL_KEY = '__shooter_summary_store';
+export const summaryStore: SummaryStore =
+  ((globalThis as Record<string, unknown>)[SS_GLOBAL_KEY] as SummaryStore) || new SummaryStore();
+(globalThis as Record<string, unknown>)[SS_GLOBAL_KEY] = summaryStore;

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/events-handler.ts

@@ -13,6 +13,18 @@ const eventsClients: Set<WebSocket> =
   ((globalThis as Record<string, unknown>)[EVENTS_KEY] as Set<WebSocket>) || new Set<WebSocket>();
 (globalThis as Record<string, unknown>)[EVENTS_KEY] = eventsClients;
 
+/**
+ * Server-side listeners (e.g. the always-on autopilot engine) that observe
+ * every broadcast event. Kept on globalThis so the listener registered from the
+ * server.ts module graph and the broadcaster called from the bundled SvelteKit
+ * handler graph share one set.
+ */
+const LISTENERS_KEY = '__shooter_ws_event_listeners';
+const eventListeners: Set<(event: ShooterEvent) => void> =
+  ((globalThis as Record<string, unknown>)[LISTENERS_KEY] as Set<(event: ShooterEvent) => void>) ||
+  new Set<(event: ShooterEvent) => void>();
+(globalThis as Record<string, unknown>)[LISTENERS_KEY] = eventListeners;
+
 // ── Handlers ────────────────────────────────────────────────────────
 
 /**
@@ -31,6 +43,15 @@ export function broadcastEvent(event: ShooterEvent): void {
       ws.send(data);
     }
   }
+
+  // Fan out to server-side listeners (autopilot engine, etc.).
+  for (const listener of eventListeners) {
+    try {
+      listener(event);
+    } catch {
+      // a faulty listener must never break the broadcast
+    }
+  }
 }
 
 /**
@@ -62,3 +83,14 @@ export function handleEventsConnection(ws: WebSocket): void {
     eventsClients.delete(ws);
   });
 }
+
+/**
+ * Register a server-side listener that receives every broadcast ShooterEvent.
+ * Returns an unsubscribe function. Used by the always-on autopilot engine.
+ */
+export function onShooterEvent(listener: (event: ShooterEvent) => void): () => void {
+  eventListeners.add(listener);
+  return (): void => {
+    eventListeners.delete(listener);
+  };
+}

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).