Skip to content

armgit / mso

Public Imported from GitHub
0

Browser-based graphical shell and control plane for a Linux server you own — real terminal, file manager, live metrics and BYOK AI in one mobile-first workspace. Next.js 16 · React 19 · node-pty · Tailwind v4 · shadcn/ui. Public alpha, self-hosted.

8.2 KB
Raw Blame
// SERVER-ONLY. Interactive PTY session manager behind /api/v1/term/*. Spawns
// the owner's login shell on the host and streams raw bytes both ways (vim,
// top, ssh, tab-completion — anything a real terminal does).
//
// SECURITY: this is an interactive OWNER shell — the destructive-command regex
// in exec.ts CANNOT apply here. A pty carries raw keystrokes with no command
// boundary to inspect, and an interactive shell composes commands from
// fragments (history, completion, editors) anyway. The gate is the same as
// every /api/v1 route: signed session cookie + approved device. Session
// open/close are audited (term.open / term.close). The browser terminal does
// not audit keystrokes (high-volume, and the owner has a full shell by design),
// but the AGENT-side pty_session tool does: it logs term.write per call, because
// "opened a shell" and "typed a command into a shell" are different acts and
// collapsing them would hide the second one from forensics.
import { spawn } from "node-pty";
import type { IPty } from "node-pty";
import { createHash, randomBytes } from "crypto";
import { HostError } from "./host-error";
import { resolveCwd } from "./exec";
import { childEnv } from "./child-env";

const MAX_SESSIONS = 8; // concurrent live shells
const BUFFER_CAP = 256 * 1024; // chars of replay buffer per session
const IDLE_REAP_MS = 30 * 60_000; // no attached client for 30 min → kill
// Hard browser/process exits cannot reliably send /term/close. If all eight slots are
// occupied, a shell that has had NO stream listener for this long is safe to reclaim
// under capacity pressure. The grace is deliberately longer than EventSource's normal
// reconnect window, and attached shells are never candidates.
const CAPACITY_RECLAIM_GRACE_MS = 10_000;
const DEAD_LINGER_MS = 60_000; // exited sessions linger so streams deliver `exit`
const REAP_TICK_MS = 60_000;

export type PtyListener = {
  /** `offset` = absolute stream position AFTER the chunk. Used as the SSE
   * event id so a Last-Event-ID reconnect resumes exactly where it left off. */
  onData: (chunk: string, offset: number) => void;
  onExit: (code: number) => void;
};

type Session = {
  id: string;
  ownerHash: string;
  pty: IPty;
  /** Replay ring: recent output chunks with absolute start offsets. */
  chunks: { off: number; data: string }[];
  buffered: number;
  offset: number; // total chars ever emitted
  listeners: Set<PtyListener>;
  dead: boolean;
  exitCode: number;
  idleSince: number; // last moment with zero listeners (or exit time)
};

// globalThis stash so dev-mode HMR module reloads don't orphan live shells.
// A full server restart still drops every session (clients see the stream die
// and get a Restart button) — sessions are processes, not persistable state.
const g = globalThis as {
  __osPtySessions?: Map<string, Session>;
  __osPtyReaper?: ReturnType<typeof setInterval>;
};
const sessions = (g.__osPtySessions ??= new Map<string, Session>());

function ensureReaper(): void {
  if (g.__osPtyReaper) return;
  g.__osPtyReaper = setInterval(() => {
    const now = Date.now();
    for (const s of sessions.values()) {
      if (!s.dead && s.listeners.size === 0 && now - s.idleSince > IDLE_REAP_MS)
        s.pty.kill(); // onExit marks it dead; lingers below until cleaned
      if (s.dead && s.listeners.size === 0 && now - s.idleSince > DEAD_LINGER_MS)
        sessions.delete(s.id);
    }
  }, REAP_TICK_MS);
  g.__osPtyReaper.unref?.();
}

function ownerHash(owner: string): string {
  if (!owner || owner.length > 512) throw new HostError("Unknown terminal session");
  return createHash("sha256").update(owner).digest("hex");
}

function get(id: string, owner: string): Session {
  const s = sessions.get(id);
  if (!s || s.ownerHash !== ownerHash(owner)) throw new HostError("Unknown terminal session");
  return s;
}

function clampDim(n: number): number {
  return Math.max(2, Math.min(500, Math.round(n)));
}

function reclaimDetachedSlot(now = Date.now()): boolean {
  let candidate: Session | null = null;
  for (const session of sessions.values()) {
    if (session.dead || session.listeners.size > 0) continue;
    if (now - session.idleSince < CAPACITY_RECLAIM_GRACE_MS) continue;
    if (!candidate || session.idleSince < candidate.idleSince) candidate = session;
  }
  if (!candidate) return false;

  // Delete first so the slot is immediately available even though node-pty emits its
  // exit callback asynchronously. A late reconnect to the reclaimed id correctly gets
  // “Unknown terminal session” and the client can Restart instead of reviving a shell
  // we deliberately evicted under capacity pressure.
  sessions.delete(candidate.id);
  candidate.pty.kill();
  return true;
}

export async function openPty(opts: {
  cols: number;
  rows: number;
  cwd?: string;
  owner: string;
}): Promise<{ id: string; cwd: string }> {
  let live = 0;
  for (const s of sessions.values()) if (!s.dead) live++;
  if (live >= MAX_SESSIONS && !reclaimDetachedSlot())
    throw new HostError(`Too many terminal sessions (max ${MAX_SESSIONS}) — close one first`);

  const cwd = await resolveCwd(opts.cwd); // write-root bounded; explicit invalid paths fail
  const isWindows = process.platform === "win32";
  const shell = isWindows
    ? process.env.POWERSHELL_EXE || "powershell.exe"
    : process.env.SHELL || "/bin/bash";
  const env = childEnv(); // process.env minus the app's own secrets
  env.TERM = "xterm-256color";
  env.COLORTERM = "truecolor";

  const pty = spawn(shell, isWindows ? ["-NoLogo"] : ["-l"], {
    name: "xterm-256color",
    cols: clampDim(opts.cols),
    rows: clampDim(opts.rows),
    cwd,
    env,
  });
  const s: Session = {
    id: randomBytes(16).toString("hex"),
    ownerHash: ownerHash(opts.owner),
    pty,
    chunks: [],
    buffered: 0,
    offset: 0,
    listeners: new Set(),
    dead: false,
    exitCode: 0,
    idleSince: Date.now(),
  };
  pty.onData((data) => {
    s.chunks.push({ off: s.offset, data });
    s.offset += data.length;
    s.buffered += data.length;
    while (s.buffered > BUFFER_CAP && s.chunks.length > 1) {
      const drop = s.chunks.shift();
      if (drop) s.buffered -= drop.data.length;
    }
    for (const l of s.listeners) l.onData(data, s.offset);
  });
  pty.onExit(({ exitCode }) => {
    s.dead = true;
    s.exitCode = exitCode;
    s.idleSince = Date.now();
    for (const l of s.listeners) l.onExit(exitCode);
  });
  sessions.set(s.id, s);
  ensureReaper();
  return { id: s.id, cwd };
}

/** True when the session id exists (live or recently exited). */
export function hasPty(id: string, owner: string): boolean {
  const session = sessions.get(id);
  return Boolean(session && session.ownerHash === ownerHash(owner));
}

// Attach a stream: replay buffered output past `fromOffset` synchronously,
// then live events. A dead session replays + fires onExit immediately.
// Returns the detach fn (idle-reap clock starts when the last client leaves).
export function attachPty(id: string, owner: string, fromOffset: number, l: PtyListener): () => void {
  const s = get(id, owner);
  const from = Math.max(0, Math.min(fromOffset, s.offset));
  for (const c of s.chunks) {
    const end = c.off + c.data.length;
    if (end <= from) continue;
    l.onData(c.off >= from ? c.data : c.data.slice(from - c.off), end);
  }
  if (s.dead) {
    l.onExit(s.exitCode);
    return () => {};
  }
  s.listeners.add(l);
  return () => {
    s.listeners.delete(l);
    if (s.listeners.size === 0) s.idleSince = Date.now();
  };
}

export function writePty(id: string, owner: string, data: string): void {
  const s = get(id, owner);
  if (s.dead) throw new HostError("Terminal session has exited");
  s.pty.write(data);
}

export function resizePty(id: string, owner: string, cols: number, rows: number): void {
  const s = get(id, owner);
  if (s.dead) throw new HostError("Terminal session has exited");
  s.pty.resize(clampDim(cols), clampDim(rows));
}

// Idempotent close: the client fires close-on-unmount even after the shell
// already exited. Returns whether a live shell was actually killed (audit
// only logs a real kill).
export function closePty(id: string, owner: string): boolean {
  const s = sessions.get(id);
  if (!s || s.ownerHash !== ownerHash(owner) || s.dead) return false;
  s.pty.kill();
  return true;
}