@assistkick/create 1.0.0

package/templates/product-system/packages/backend/src/services/pty_session_manager.ts

@@ -0,0 +1,279 @@
+/**
+ * PTY Session Manager — manages restricted command execution per user.
+ * Implements dec_029 (Command Prefix Whitelist) and dec_030 (Server-Side PTY Session Persistence).
+ *
+ * Architecture: No interactive shell is spawned. Instead, the server manages a
+ * command-line state machine that collects user input character-by-character,
+ * validates complete commands against the whitelist, then spawns only the
+ * validated command as a PTY process. While a command is running, raw input
+ * is forwarded to it. When the command exits, the session returns to idle.
+ */
+
+import type { IPty } from 'node-pty';
+
+const OUTPUT_BUFFER_MAX = 50_000;
+
+const ALLOWED_COMMAND_PREFIXES = [
+  'claude',
+] as const;
+
+const PROMPT = '\x1b[32m$\x1b[0m ';
+const WELCOME_MSG = `\x1b[90mRestricted terminal — allowed commands: ${ALLOWED_COMMAND_PREFIXES.join(', ')}\x1b[0m\r\n`;
+
+interface PtySessionManagerDeps {
+  spawn: (shell: string, args: string[], options: Record<string, unknown>) => IPty;
+  log: (tag: string, ...args: unknown[]) => void;
+  projectRoot: string;
+}
+
+interface PtySession {
+  userId: string;
+  pty: IPty | null;
+  state: 'idle' | 'running';
+  cols: number;
+  rows: number;
+  outputBuffer: string;
+  inputBuffer: string;
+  listeners: Set<(data: string) => void>;
+  createdAt: Date;
+}
+
+export class PtySessionManager {
+  private readonly sessions = new Map<string, PtySession>();
+  private readonly spawn: PtySessionManagerDeps['spawn'];
+  private readonly log: PtySessionManagerDeps['log'];
+  private readonly projectRoot: string;
+
+  constructor({ spawn, log, projectRoot }: PtySessionManagerDeps) {
+    this.spawn = spawn;
+    this.log = log;
+    this.projectRoot = projectRoot;
+  }
+
+  validateCommand = (input: string): { valid: boolean; error?: string } => {
+    const trimmed = input.trim();
+    if (!trimmed) {
+      return { valid: false, error: 'Empty command' };
+    }
+
+    const command = trimmed.split(/\s+/)[0];
+    const isAllowed = ALLOWED_COMMAND_PREFIXES.some(prefix => command === prefix);
+
+    if (!isAllowed) {
+      return {
+        valid: false,
+        error: `Command "${command}" is not allowed. Allowed commands: ${ALLOWED_COMMAND_PREFIXES.join(', ')}`,
+      };
+    }
+
+    return { valid: true };
+  };
+
+  getSession = (userId: string): PtySession | undefined => {
+    return this.sessions.get(userId);
+  };
+
+  createSession = (userId: string, cols: number, rows: number): PtySession => {
+    const existing = this.sessions.get(userId);
+    if (existing) {
+      this.log('PTY', `Reusing existing session for user ${userId}`);
+      return existing;
+    }
+
+    const session: PtySession = {
+      userId,
+      pty: null,
+      state: 'idle',
+      cols,
+      rows,
+      outputBuffer: '',
+      inputBuffer: '',
+      listeners: new Set(),
+      createdAt: new Date(),
+    };
+
+    this.sessions.set(userId, session);
+    this.log('PTY', `Created new session for user ${userId}`);
+
+    // Show welcome message and prompt
+    this.emitOutput(session, WELCOME_MSG);
+    this.emitOutput(session, PROMPT);
+
+    return session;
+  };
+
+  addListener = (userId: string, listener: (data: string) => void): void => {
+    const session = this.sessions.get(userId);
+    if (session) {
+      session.listeners.add(listener);
+    }
+  };
+
+  removeListener = (userId: string, listener: (data: string) => void): void => {
+    const session = this.sessions.get(userId);
+    if (session) {
+      session.listeners.delete(listener);
+    }
+  };
+
+  writeToSession = (userId: string, data: string): void => {
+    const session = this.sessions.get(userId);
+    if (!session) return;
+
+    if (session.state === 'running' && session.pty) {
+      // Forward raw input to the running command
+      session.pty.write(data);
+    } else if (session.state === 'idle') {
+      // Handle command-line input
+      this.handleIdleInput(session, data);
+    }
+  };
+
+  resizeSession = (userId: string, cols: number, rows: number): void => {
+    const session = this.sessions.get(userId);
+    if (session) {
+      session.cols = cols;
+      session.rows = rows;
+      if (session.pty) {
+        session.pty.resize(cols, rows);
+      }
+    }
+  };
+
+  destroySession = (userId: string): void => {
+    const session = this.sessions.get(userId);
+    if (session) {
+      if (session.pty) {
+        session.pty.kill();
+      }
+      this.sessions.delete(userId);
+      this.log('PTY', `Destroyed session for user ${userId}`);
+    }
+  };
+
+  destroyAll = (): void => {
+    for (const [userId] of this.sessions) {
+      this.destroySession(userId);
+    }
+  };
+
+  getBufferedOutput = (userId: string): string => {
+    const session = this.sessions.get(userId);
+    return session?.outputBuffer ?? '';
+  };
+
+  private handleIdleInput = (session: PtySession, data: string): void => {
+    for (const char of data) {
+      if (char === '\r' || char === '\n') {
+        // Enter pressed — validate and execute
+        this.emitOutput(session, '\r\n');
+        const command = session.inputBuffer.trim();
+        session.inputBuffer = '';
+
+        if (!command) {
+          this.emitOutput(session, PROMPT);
+          return;
+        }
+
+        const validation = this.validateCommand(command);
+        if (!validation.valid) {
+          this.emitOutput(session, `\x1b[31m${validation.error}\x1b[0m\r\n`);
+          this.emitOutput(session, PROMPT);
+          return;
+        }
+
+        this.spawnCommand(session, command);
+      } else if (char === '\x7f' || char === '\b') {
+        // Backspace
+        if (session.inputBuffer.length > 0) {
+          session.inputBuffer = session.inputBuffer.slice(0, -1);
+          this.emitOutput(session, '\b \b');
+        }
+      } else if (char === '\x03') {
+        // Ctrl+C — clear input
+        session.inputBuffer = '';
+        this.emitOutput(session, '^C\r\n');
+        this.emitOutput(session, PROMPT);
+      } else if (char >= ' ') {
+        // Printable character — echo and buffer
+        session.inputBuffer += char;
+        this.emitOutput(session, char);
+      }
+    }
+  };
+
+  private buildEnv = (): Record<string, string> => {
+    const env = { ...process.env } as Record<string, string>;
+    const home = env.HOME || '/root';
+    // Ensure common user-local binary directories are on PATH so that
+    // tools installed under the user profile (e.g. claude via npm -g)
+    // are found even when the server wasn't started from a login shell.
+    const extraPaths = [
+      `${home}/.local/bin`,
+      `${home}/.npm-global/bin`,
+      `${home}/.nvm/current/bin`,
+      '/usr/local/bin',
+      '/opt/homebrew/bin',
+    ];
+    const existing = env.PATH || '/usr/bin:/bin';
+    const missing = extraPaths.filter(p => !existing.split(':').includes(p));
+    if (missing.length) {
+      env.PATH = [...missing, existing].join(':');
+    }
+    return env;
+  };
+
+  private spawnCommand = (session: PtySession, command: string): void => {
+    const parts = command.trim().split(/\s+/);
+    const cmd = parts[0];
+    const args = parts.slice(1);
+
+    this.log('PTY', `Executing validated command "${command}" for user ${session.userId}`);
+
+    let spawnedPty: IPty;
+    try {
+      spawnedPty = this.spawn(cmd, args, {
+        name: 'xterm-256color',
+        cols: session.cols,
+        rows: session.rows,
+        cwd: this.projectRoot,
+        env: this.buildEnv(),
+      });
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      const env = this.buildEnv();
+      this.emitOutput(session, `\x1b[31mFailed to execute: ${msg}\x1b[0m\r\n`);
+      this.emitOutput(session, `\x1b[90mPATH: ${env.PATH}\x1b[0m\r\n`);
+      this.emitOutput(session, `\x1b[90mHOME: ${env.HOME || '(unset)'}\x1b[0m\r\n`);
+      this.emitOutput(session, `\x1b[90mSHELL: ${env.SHELL || '(unset)'}\x1b[0m\r\n`);
+      this.log('PTY', `Spawn failed for "${command}": ${msg} | PATH=${env.PATH}`);
+      this.emitOutput(session, PROMPT);
+      return;
+    }
+
+    session.pty = spawnedPty;
+    session.state = 'running';
+
+    spawnedPty.onData((data: string) => {
+      this.emitOutput(session, data);
+    });
+
+    spawnedPty.onExit(({ exitCode }) => {
+      this.log('PTY', `Command exited with code ${exitCode} for user ${session.userId}`);
+      session.pty = null;
+      session.state = 'idle';
+      this.emitOutput(session, '\r\n');
+      this.emitOutput(session, PROMPT);
+    });
+  };
+
+  private emitOutput = (session: PtySession, data: string): void => {
+    session.outputBuffer += data;
+    if (session.outputBuffer.length > OUTPUT_BUFFER_MAX) {
+      session.outputBuffer = session.outputBuffer.slice(-OUTPUT_BUFFER_MAX);
+    }
+    for (const listener of session.listeners) {
+      listener(data);
+    }
+  };
+}

package/templates/product-system/packages/backend/src/services/terminal_ws_handler.ts

@@ -0,0 +1,133 @@
+/**
+ * WebSocket handler for terminal connections.
+ * Authenticates via cookie, enforces admin-only access,
+ * and bridges WebSocket ↔ PTY session.
+ */
+
+import type { IncomingMessage } from 'node:http';
+import type { Duplex } from 'node:stream';
+import type { WebSocketServer, WebSocket } from 'ws';
+import type { AuthService } from './auth_service.js';
+import type { PtySessionManager } from './pty_session_manager.js';
+
+interface TerminalWsHandlerDeps {
+  wss: WebSocketServer;
+  authService: AuthService;
+  ptyManager: PtySessionManager;
+  log: (tag: string, ...args: unknown[]) => void;
+}
+
+interface TerminalMessage {
+  type: 'input' | 'resize';
+  data?: string;
+  cols?: number;
+  rows?: number;
+}
+
+const parseCookies = (cookieHeader: string | undefined): Record<string, string> => {
+  if (!cookieHeader) return {};
+  const cookies: Record<string, string> = {};
+  for (const pair of cookieHeader.split(';')) {
+    const [key, ...rest] = pair.trim().split('=');
+    if (key) {
+      cookies[key] = rest.join('=');
+    }
+  }
+  return cookies;
+};
+
+export class TerminalWsHandler {
+  private readonly wss: WebSocketServer;
+  private readonly authService: AuthService;
+  private readonly ptyManager: PtySessionManager;
+  private readonly log: TerminalWsHandlerDeps['log'];
+
+  constructor({ wss, authService, ptyManager, log }: TerminalWsHandlerDeps) {
+    this.wss = wss;
+    this.authService = authService;
+    this.ptyManager = ptyManager;
+    this.log = log;
+  }
+
+  handleUpgrade = (req: IncomingMessage, socket: Duplex, head: Buffer): void => {
+    if (req.url !== '/api/terminal') {
+      return;
+    }
+
+    this.wss.handleUpgrade(req, socket, head, (ws) => {
+      this.onConnection(ws, req);
+    });
+  };
+
+  private onConnection = async (ws: WebSocket, req: IncomingMessage): Promise<void> => {
+    const cookies = parseCookies(req.headers.cookie);
+    const token = cookies['access_token'];
+
+    if (!token) {
+      this.log('TERMINAL', 'Connection rejected — no access token');
+      ws.close(4001, 'Unauthorized');
+      return;
+    }
+
+    let payload: { sub: string; email?: string; role?: string };
+    try {
+      payload = await this.authService.verifyToken(token);
+    } catch {
+      this.log('TERMINAL', 'Connection rejected — invalid token');
+      ws.close(4001, 'Invalid token');
+      return;
+    }
+
+    if (payload.role !== 'admin') {
+      this.log('TERMINAL', `Connection rejected — user ${payload.sub} is not admin`);
+      ws.close(4003, 'Forbidden');
+      return;
+    }
+
+    const userId = payload.sub;
+    this.log('TERMINAL', `Admin ${payload.email} connected to terminal`);
+
+    // Get or create PTY session (default 80x24, client will send resize)
+    const session = this.ptyManager.createSession(userId, 80, 24);
+
+    // Send buffered output from previous session
+    const buffered = this.ptyManager.getBufferedOutput(userId);
+    if (buffered) {
+      ws.send(JSON.stringify({ type: 'output', data: buffered }));
+    }
+
+    // Bridge PTY output → WebSocket
+    const outputListener = (data: string) => {
+      if (ws.readyState === ws.OPEN) {
+        ws.send(JSON.stringify({ type: 'output', data }));
+      }
+    };
+    this.ptyManager.addListener(userId, outputListener);
+
+    ws.on('message', (raw: Buffer | string) => {
+      let msg: TerminalMessage;
+      try {
+        msg = JSON.parse(typeof raw === 'string' ? raw : raw.toString());
+      } catch {
+        return;
+      }
+
+      if (msg.type === 'input' && typeof msg.data === 'string') {
+        this.ptyManager.writeToSession(userId, msg.data);
+      } else if (msg.type === 'resize' && typeof msg.cols === 'number' && typeof msg.rows === 'number') {
+        this.ptyManager.resizeSession(userId, msg.cols, msg.rows);
+      }
+    });
+
+    ws.on('close', () => {
+      this.log('TERMINAL', `Admin ${payload.email} disconnected from terminal`);
+      this.ptyManager.removeListener(userId, outputListener);
+      // PTY session persists (dec_030) — not destroyed on disconnect
+    });
+
+    ws.on('error', (err) => {
+      this.log('TERMINAL', `WebSocket error: ${err.message}`);
+      this.ptyManager.removeListener(userId, outputListener);
+    });
+  };
+}

package/templates/product-system/packages/backend/src/services/user_management_service.test.ts

@@ -0,0 +1,158 @@
+import { describe, it, mock, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { UserManagementService } from './user_management_service.ts';
+
+const createMockDb = () => {
+  const state = {
+    deletedUsers: [] as string[],
+    deletedInvitations: [] as string[],
+    deletedRefreshTokens: [] as string[],
+  };
+
+  let selectResults: any[][] = [];
+  let selectCallIndex = 0;
+
+  const db = {
+    select: mock.fn(() => ({
+      from: mock.fn(() => ({
+        where: mock.fn(() => {
+          const result = selectResults[selectCallIndex] || [];
+          selectCallIndex++;
+          return result;
+        }),
+        orderBy: mock.fn(() => {
+          const result = selectResults[selectCallIndex] || [];
+          selectCallIndex++;
+          return result;
+        }),
+      })),
+    })),
+    delete: mock.fn(() => ({
+      where: mock.fn((condition: any) => {
+        // Track deletions
+      }),
+    })),
+    _state: state,
+    _setSelectResults: (results: any[][]) => {
+      selectResults = results;
+      selectCallIndex = 0;
+    },
+  };
+
+  return db;
+};
+
+const createService = (db: any) => {
+  return new UserManagementService({
+    getDb: () => db,
+    log: mock.fn(),
+  });
+};
+
+describe('UserManagementService', () => {
+  let db: ReturnType<typeof createMockDb>;
+  let service: UserManagementService;
+
+  beforeEach(() => {
+    db = createMockDb();
+    service = createService(db);
+  });
+
+  describe('listUsers', () => {
+    it('returns all users ordered by createdAt', async () => {
+      const mockUsers = [
+        { id: '1', email: 'admin@test.com', role: 'admin', createdAt: '2024-01-01T00:00:00Z' },
+        { id: '2', email: 'user@test.com', role: 'user', createdAt: '2024-01-02T00:00:00Z' },
+      ];
+      db._setSelectResults([mockUsers]);
+
+      const result = await service.listUsers();
+
+      assert.equal(result.length, 2);
+      assert.equal(result[0].email, 'admin@test.com');
+      assert.equal(result[1].role, 'user');
+    });
+
+    it('returns empty array when no users exist', async () => {
+      db._setSelectResults([[]]);
+
+      const result = await service.listUsers();
+
+      assert.equal(result.length, 0);
+    });
+  });
+
+  describe('deleteUser', () => {
+    it('throws when trying to delete own account', async () => {
+      await assert.rejects(
+        () => service.deleteUser('user-1', 'user-1'),
+        { message: 'Cannot delete your own account' },
+      );
+    });
+
+    it('throws when target user not found', async () => {
+      db._setSelectResults([[]]);
+
+      await assert.rejects(
+        () => service.deleteUser('nonexistent', 'admin-1'),
+        { message: 'User not found' },
+      );
+    });
+
+    it('deletes user and their refresh tokens', async () => {
+      db._setSelectResults([[{ id: 'user-2', email: 'user@test.com' }]]);
+
+      await service.deleteUser('user-2', 'admin-1');
+
+      // Verify delete was called twice (refresh tokens + user)
+      assert.equal(db.delete.mock.calls.length, 2);
+    });
+  });
+
+  describe('listInvitations', () => {
+    it('returns invitations with inviter emails resolved', async () => {
+      const mockInvitations = [
+        { id: 'inv-1', email: 'new@test.com', invitedBy: 'admin-1', createdAt: '2024-01-01', expiresAt: '2024-01-03', acceptedAt: null },
+      ];
+      const mockInviter = [{ email: 'admin@test.com' }];
+
+      db._setSelectResults([mockInvitations, mockInviter]);
+
+      const result = await service.listInvitations();
+
+      assert.equal(result.length, 1);
+      assert.equal(result[0].invitedByEmail, 'admin@test.com');
+    });
+
+    it('returns "unknown" when inviter not found', async () => {
+      const mockInvitations = [
+        { id: 'inv-1', email: 'new@test.com', invitedBy: 'deleted-user', createdAt: '2024-01-01', expiresAt: '2024-01-03', acceptedAt: null },
+      ];
+
+      db._setSelectResults([mockInvitations, []]);
+
+      const result = await service.listInvitations();
+
+      assert.equal(result[0].invitedByEmail, 'unknown');
+    });
+  });
+
+  describe('deleteInvitation', () => {
+    it('throws when invitation not found', async () => {
+      db._setSelectResults([[]]);
+
+      await assert.rejects(
+        () => service.deleteInvitation('nonexistent'),
+        { message: 'Invitation not found' },
+      );
+    });
+
+    it('deletes existing invitation', async () => {
+      db._setSelectResults([[{ id: 'inv-1', email: 'new@test.com' }]]);
+
+      await service.deleteInvitation('inv-1');
+
+      assert.equal(db.delete.mock.calls.length, 1);
+    });
+  });
+});

package/templates/product-system/packages/backend/src/services/user_management_service.ts

@@ -0,0 +1,128 @@
+/**
+ * User management service — admin-only operations for listing/deleting users and invitations.
+ */
+
+import { eq, ne } from 'drizzle-orm';
+import { users, invitations, refreshTokens } from '@interview-system/shared/db/schema.js';
+
+interface UserManagementServiceDeps {
+  getDb: () => any;
+  log: (tag: string, ...args: any[]) => void;
+}
+
+export interface UserRecord {
+  id: string;
+  email: string;
+  role: string;
+  createdAt: string;
+}
+
+export interface InvitationRecord {
+  id: string;
+  email: string;
+  invitedBy: string;
+  invitedByEmail: string;
+  createdAt: string;
+  expiresAt: string;
+  acceptedAt: string | null;
+}
+
+export class UserManagementService {
+  private readonly getDb: () => any;
+  private readonly log: (tag: string, ...args: any[]) => void;
+
+  constructor({ getDb, log }: UserManagementServiceDeps) {
+    this.getDb = getDb;
+    this.log = log;
+  }
+
+  listUsers = async (): Promise<UserRecord[]> => {
+    const db = this.getDb();
+    const rows = await db
+      .select({
+        id: users.id,
+        email: users.email,
+        role: users.role,
+        createdAt: users.createdAt,
+      })
+      .from(users)
+      .orderBy(users.createdAt);
+
+    return rows;
+  };
+
+  deleteUser = async (targetUserId: string, requesterId: string): Promise<void> => {
+    const db = this.getDb();
+
+    if (targetUserId === requesterId) {
+      throw new Error('Cannot delete your own account');
+    }
+
+    const [target] = await db
+      .select({ id: users.id, email: users.email })
+      .from(users)
+      .where(eq(users.id, targetUserId));
+
+    if (!target) {
+      throw new Error('User not found');
+    }
+
+    // Delete refresh tokens for the user
+    await db.delete(refreshTokens).where(eq(refreshTokens.userId, targetUserId));
+
+    // Delete the user
+    await db.delete(users).where(eq(users.id, targetUserId));
+
+    this.log('USERS', `User deleted: ${target.email} (by ${requesterId})`);
+  };
+
+  listInvitations = async (): Promise<InvitationRecord[]> => {
+    const db = this.getDb();
+    const rows = await db
+      .select({
+        id: invitations.id,
+        email: invitations.email,
+        invitedBy: invitations.invitedBy,
+        createdAt: invitations.createdAt,
+        expiresAt: invitations.expiresAt,
+        acceptedAt: invitations.acceptedAt,
+      })
+      .from(invitations)
+      .orderBy(invitations.createdAt);
+
+    // Resolve inviter emails
+    const inviterIds = [...new Set(rows.map((r: any) => r.invitedBy))];
+    const inviterMap = new Map<string, string>();
+    for (const inviterId of inviterIds) {
+      const [inviter] = await db
+        .select({ email: users.email })
+        .from(users)
+        .where(eq(users.id, inviterId as string));
+      if (inviter) {
+        inviterMap.set(inviterId as string, inviter.email);
+      }
+    }
+
+    return rows.map((r: any) => ({
+      ...r,
+      invitedByEmail: inviterMap.get(r.invitedBy) || 'unknown',
+    }));
+  };
+
+  deleteInvitation = async (invitationId: string): Promise<void> => {
+    const db = this.getDb();
+
+    const [invitation] = await db
+      .select({ id: invitations.id, email: invitations.email })
+      .from(invitations)
+      .where(eq(invitations.id, invitationId));
+
+    if (!invitation) {
+      throw new Error('Invitation not found');
+    }
+
+    await db.delete(invitations).where(eq(invitations.id, invitationId));
+
+    this.log('USERS', `Invitation deleted: ${invitation.email}`);
+  };
+}