dsh-remote-vs 0.0.0-stage → 0.8.3

package/src/store.ts

@@ -0,0 +1,364 @@
+/**
+ * Durable store for dsh-remote-vs: hosts + workspace bindings in
+ * $DSH_HOME/dsh-remote.json (0600, atomic tmp+rename writes).
+ */
+import { existsSync, statSync, openSync, readFileSync, renameSync, writeSync, closeSync } from 'node:fs'
+import { randomUUID } from 'node:crypto'
+import { join } from 'node:path'
+import { aliasRoot, keysDir, storePath } from './paths.ts'
+import type {
+  RemoteDeployState,
+  RemoteHostEntry,
+  RemoteHostSummary,
+  RemoteWorkspaceBinding,
+} from './protocol.ts'
+
+/** On-disk document shape. */
+interface StoreDoc {
+  version: 1
+  hosts: RemoteHostEntry[]
+  workspaces: RemoteWorkspaceBinding[]
+  /** Removed alias dirs (fail-closed tombstones; never auto-deleted). */
+  tombstones: string[]
+}
+
+/** Empty document. */
+function emptyDoc(): StoreDoc {
+  return { version: 1, hosts: [], workspaces: [], tombstones: [] }
+}
+
+/** Identity of the store file at one point in time; `null` = the file is absent. */
+type FileStamp = { mtimeMs: number; size: number } | null
+
+/** Same file identity (both absent counts as same). */
+function sameStamp(left: FileStamp, right: FileStamp): boolean {
+  if (left === null || right === null) return left === right
+  return left.mtimeMs === right.mtimeMs && left.size === right.size
+}
+
+/** Alias grammar: 1-64 chars of letters/digits/._- */
+const ALIAS_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/
+
+function assertAlias(alias: unknown): asserts alias is string {
+  if (typeof alias !== 'string' || !ALIAS_RE.test(alias)) {
+    throw new Error('alias must match [A-Za-z0-9._-]{1,64} and start with an alphanumeric')
+  }
+}
+
+/** Payload accepted by create/update (secrets included, host-side only). */
+export interface HostPayload {
+  alias: string
+  host: string
+  port?: number
+  user: string
+  auth: { kind: 'key' | 'password'; keyPath?: string; passphrase?: string; password?: string }
+  description?: string
+  tags?: string[]
+}
+
+export interface WorkspacePayload {
+  name: string
+  alias: string
+  remotePath: string
+}
+
+export class RemoteStore {
+  private readonly file: string
+  private doc: StoreDoc
+  /** File identity when `doc` was read from disk (undefined = `doc` is not known fresh). */
+  private stamp: FileStamp | undefined
+
+  constructor(file?: string) {
+    this.file = file ?? storePath()
+    // `doc` starts empty and `reload()` fills it: `stamp` is undefined, so the
+    // first read always takes the real path (missing file -> empty doc).
+    this.doc = emptyDoc()
+    this.reload()
+  }
+
+  /**
+   * Reload from disk (picks up external edits).
+   *
+   * Re-reading on every access is deliberate: the root fs router asks this store
+   * 2-4 times per routed file operation, and an edit made by another process
+   * must be visible without a restart. A stat is orders of magnitude cheaper
+   * than read + parse, so the file's identity (mtime + size) decides instead —
+   * unchanged means the cached doc is already the file's content. The stamp is
+   * taken BEFORE the read: a write landing in between leaves the older stamp
+   * behind, so the next access re-reads rather than trusting a stale doc. The
+   * one edit this cannot see is a same-length rewrite inside the filesystem's
+   * mtime granularity (sub-ms on NTFS/ext4).
+   */
+  reload(): void {
+    const stamp = this.stampOf()
+    if (stamp !== undefined && this.stamp !== undefined && sameStamp(stamp, this.stamp)) return
+    this.doc = this.loadDoc()
+    this.stamp = stamp
+  }
+
+  /**
+   * File identity right now: `null` when the file is absent, `undefined` when it
+   * cannot be statted at all. Both cases fall through to a full load, so the
+   * missing-file and unreadable-file paths behave exactly as they did before.
+   */
+  private stampOf(): FileStamp | undefined {
+    try {
+      const stat = statSync(this.file, { throwIfNoEntry: false })
+      return stat === undefined ? null : { mtimeMs: stat.mtimeMs, size: stat.size }
+    } catch {
+      return undefined
+    }
+  }
+
+  private loadDoc(): StoreDoc {
+    if (!existsSync(this.file)) return emptyDoc()
+    let parsed: unknown
+    try {
+      parsed = JSON.parse(readFileSync(this.file, 'utf8'))
+    } catch (error) {
+      throw new Error(`cannot parse ${this.file}: ${error instanceof Error ? error.message : String(error)}`)
+    }
+    if (typeof parsed !== 'object' || parsed === null) throw new Error(`${this.file}: root must be an object`)
+    const doc = parsed as Partial<StoreDoc>
+    if (doc.version !== 1) throw new Error(`${this.file}: unsupported version ${(doc as { version?: unknown }).version}`)
+    if (!Array.isArray(doc.hosts) || !Array.isArray(doc.workspaces)) {
+      throw new Error(`${this.file}: hosts/workspaces must be arrays`)
+    }
+    return {
+      version: 1,
+      hosts: doc.hosts,
+      workspaces: doc.workspaces,
+      tombstones: Array.isArray(doc.tombstones) ? doc.tombstones.filter(t => typeof t === 'string') : [],
+    }
+  }
+
+  private save(): void {
+    // The caller already mutated `doc`, so in-memory state is ahead of the file:
+    // invalidate the stamp. A failed write must not pin the dirty doc in place
+    // (the next read goes back to the file, as it always did), and a successful
+    // one is picked up by that same re-read, which re-arms the fast path.
+    this.stamp = undefined
+    const payload = JSON.stringify(this.doc, null, 2)
+    const tmp = `${this.file}.${process.pid}.tmp`
+    // 0600 from creation (Windows: best effort, mode is advisory there).
+    const fd = openSync(tmp, 'w', 0o600)
+    try {
+      writeSync(fd, payload)
+    } finally {
+      closeSync(fd)
+    }
+    renameSync(tmp, this.file)
+  }
+
+  // ------------------------------------------------------------- hosts
+  // NOTE: reads revalidate the file first (one stat; the file is tiny and a
+  // read + parse only happens when its identity changed), so routers + routes +
+  // GUI still see fresh state without a watcher.
+
+  list(): RemoteHostEntry[] {
+    this.reload()
+    return [...this.doc.hosts]
+  }
+
+  get(alias: string): RemoteHostEntry | undefined {
+    this.reload()
+    return this.doc.hosts.find(h => h.alias === alias)
+  }
+
+  require(alias: string): RemoteHostEntry {
+    const entry = this.get(alias)
+    if (entry === undefined) throw new Error(`unknown host alias: ${alias}`)
+    return entry
+  }
+
+  create(payload: HostPayload): RemoteHostEntry {
+    assertAlias(payload.alias)
+    if (this.get(payload.alias) !== undefined) throw new Error(`alias already exists: ${payload.alias}`)
+    const entry = this.normalize(payload, undefined)
+    this.doc.hosts.push(entry)
+    this.save()
+    return entry
+  }
+
+  update(alias: string, patch: Partial<Omit<HostPayload, 'alias'>>): RemoteHostEntry {
+    const current = this.require(alias)
+    // Empty auth materials mean "keep the stored one" (the browser never
+    // echoes secrets back, so an untouched field arrives empty/omitted).
+    let auth = patch.auth ?? current.auth
+    if (patch.auth !== undefined) {
+      if (patch.auth.kind === 'key') {
+        const keyPath = (patch.auth.keyPath ?? '').trim()
+        auth = {
+          kind: 'key',
+          keyPath: keyPath !== ''
+            ? keyPath
+            : current.auth.kind === 'key'
+              ? (current.auth.keyPath as string)
+              : '',
+          ...(patch.auth.passphrase !== undefined
+            ? { passphrase: patch.auth.passphrase }
+            : current.auth.kind === 'key' && current.auth.passphrase !== undefined
+              ? { passphrase: current.auth.passphrase }
+              : {}),
+        }
+      } else {
+        const password = patch.auth.password ?? ''
+        auth = {
+          kind: 'password',
+          password: password !== ''
+            ? password
+            : current.auth.kind === 'password'
+              ? (current.auth.password as string)
+              : '',
+        }
+      }
+    }
+    const merged: HostPayload = {
+      alias,
+      host: patch.host ?? current.host,
+      port: patch.port ?? current.port,
+      user: patch.user ?? current.user,
+      auth,
+      description: patch.description ?? current.description,
+      tags: patch.tags ?? current.tags,
+    }
+    const next = this.normalize(merged, current)
+    const index = this.doc.hosts.findIndex(h => h.alias === alias)
+    this.doc.hosts[index] = next
+    this.save()
+    return next
+  }
+
+  remove(alias: string): boolean {
+    const before = this.doc.hosts.length
+    this.doc.hosts = this.doc.hosts.filter(h => h.alias !== alias)
+    this.doc.workspaces = this.doc.workspaces.filter(w => w.alias !== alias)
+    if (this.doc.hosts.length === before) return false
+    this.save()
+    return true
+  }
+
+  private normalize(payload: HostPayload, current: RemoteHostEntry | undefined): RemoteHostEntry {
+    if (typeof payload.host !== 'string' || payload.host.trim() === '') throw new Error('host must be a non-empty string')
+    const port = payload.port ?? 22
+    if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error('port must be an integer 1-65535')
+    if (typeof payload.user !== 'string' || payload.user.trim() === '') throw new Error('user must be a non-empty string')
+    const auth = payload.auth
+    if (auth === undefined || (auth.kind !== 'key' && auth.kind !== 'password')) {
+      throw new Error('auth.kind must be key or password')
+    }
+    if (auth.kind === 'key') {
+      if (typeof auth.keyPath !== 'string' || auth.keyPath.trim() === '') throw new Error('auth.keyPath is required for key auth')
+      if (auth.passphrase !== undefined && typeof auth.passphrase !== 'string') throw new Error('auth.passphrase must be a string when provided')
+    } else {
+      if (typeof auth.password !== 'string' || auth.password === '') throw new Error('auth.password must be a non-empty string for password auth')
+    }
+    if (payload.description !== undefined && typeof payload.description !== 'string') throw new Error('description must be a string when provided')
+    if (payload.tags !== undefined && (!Array.isArray(payload.tags) || payload.tags.some(t => typeof t !== 'string'))) {
+      throw new Error('tags must be string[] when provided')
+    }
+    const now = Date.now()
+    return {
+      alias: payload.alias,
+      host: payload.host.trim(),
+      port,
+      user: payload.user.trim(),
+      auth: {
+        kind: auth.kind,
+        ...(auth.keyPath !== undefined ? { keyPath: auth.keyPath } : {}),
+        ...(auth.passphrase !== undefined ? { passphrase: auth.passphrase } : {}),
+        ...(auth.password !== undefined ? { password: auth.password } : {}),
+      },
+      ...(payload.description !== undefined ? { description: payload.description } : {}),
+      tags: payload.tags ?? [],
+      ...(current?.deploy !== undefined ? { deploy: current.deploy } : {}),
+      createdAt: current?.createdAt ?? now,
+      updatedAt: now,
+    }
+  }
+
+  /** Secret-free projection for browser/agent surfaces. */
+  summarize(entry: RemoteHostEntry): RemoteHostSummary {
+    let keyReady = false
+    if (entry.auth.kind === 'key' && entry.auth.keyPath !== undefined) {
+      try {
+        keyReady = existsSync(entry.auth.keyPath)
+      } catch {
+        keyReady = false
+      }
+    }
+    return {
+      alias: entry.alias,
+      host: entry.host,
+      port: entry.port,
+      user: entry.user,
+      auth: entry.auth.kind,
+      keyReady,
+      managedKey: entry.auth.kind === 'key'
+        && entry.auth.keyPath !== undefined
+        && entry.auth.keyPath.startsWith(keysDir() + (process.platform === 'win32' ? '\\' : '/')),
+      ...(entry.description !== undefined ? { description: entry.description } : {}),
+      tags: [...entry.tags],
+      ...(entry.deploy !== undefined ? { deploy: entry.deploy } : {}),
+      createdAt: entry.createdAt,
+      updatedAt: entry.updatedAt,
+    }
+  }
+
+  setDeploy(alias: string, state: RemoteDeployState): void {
+    const entry = this.require(alias)
+    entry.deploy = state
+    entry.updatedAt = Date.now()
+    this.save()
+  }
+
+  // -------------------------------------------------------- workspaces
+
+  listWorkspaces(): RemoteWorkspaceBinding[] {
+    this.reload()
+    return [...this.doc.workspaces]
+  }
+
+  createWorkspace(payload: WorkspacePayload): RemoteWorkspaceBinding {
+    if (typeof payload.name !== 'string' || payload.name.trim() === '') throw new Error('name must be a non-empty string')
+    this.require(payload.alias)
+    if (typeof payload.remotePath !== 'string' || !payload.remotePath.startsWith('/')) {
+      throw new Error('remotePath must be an absolute POSIX path')
+    }
+    const binding: RemoteWorkspaceBinding = {
+      id: randomUUID().slice(0, 8),
+      name: payload.name.trim(),
+      alias: payload.alias,
+      remotePath: payload.remotePath,
+      createdAt: Date.now(),
+    }
+    this.doc.workspaces.push(binding)
+    this.save()
+    return binding
+  }
+
+  removeWorkspace(id: string): boolean {
+    this.reload()
+    const victim = this.doc.workspaces.find(w => w.id === id)
+    if (victim === undefined) return false
+    // Tombstone the alias BEFORE dropping the binding (history stays readable,
+    // new tool calls fail closed instead of silently running locally).
+    this.addTombstone(join(aliasRoot(), id))
+    this.doc.workspaces = this.doc.workspaces.filter(w => w.id !== id)
+    this.save()
+    return true
+  }
+
+  /** Record a removed alias path (idempotent). */
+  addTombstone(aliasPath: string): void {
+    if (!this.doc.tombstones.includes(aliasPath)) {
+      this.doc.tombstones.push(aliasPath)
+      this.save()
+    }
+  }
+
+  listTombstones(): string[] {
+    this.reload()
+    return [...this.doc.tombstones]
+  }
+}

package/src/terminal.ts

@@ -0,0 +1,291 @@
+/**
+ * Remote PTY terminal sessions: one ssh2 shell per session, surviving socket
+ * detaches (reattach by id). Frames are JSON text (see protocol.ts).
+ */
+import { randomUUID } from 'node:crypto'
+import type { WebSocket } from 'ws'
+import type { ClientChannel } from 'ssh2'
+import type { RemotePool } from './pool.ts'
+import type { TerminalClientFrame, TerminalServerFrame } from './protocol.ts'
+
+interface Session {
+  id: string
+  alias: string
+  channel: ClientChannel
+  alive: boolean
+  exitCode: number | null
+  sockets: Set<WebSocket>
+  /** Bytes handed to sockets that have not flushed yet (see broadcast). */
+  pending: number
+  /** True while the channel is paused because a socket fell behind. */
+  paused: boolean
+  /** Fires once the last socket has been gone for EMPTY_SOCKET_TTL_MS. */
+  reap: ReturnType<typeof setTimeout> | undefined
+}
+
+/**
+ * A session with no attached socket is kept this long so that a page reload
+ * can reattach by id. Past it the session closes and the remote shell dies.
+ *
+ * Without this sweep nothing ever released the session: its `pool.hold` never
+ * returned to zero, so the connection could not idle out, and the remote sshd
+ * session slot stayed taken for the life of the host process. Ten minutes is
+ * far longer than a reload needs and far shorter than "until you restart DSH".
+ */
+const EMPTY_SOCKET_TTL_MS = 10 * 60_000
+
+/**
+ * Terminal output is a live stream with no natural end, so it needs a bound.
+ * When a socket falls this far behind, pause the channel — that pushes the
+ * brake all the way back to the remote command, instead of growing the host
+ * process. Resume once the socket has drained.
+ *
+ * The pause is real backpressure, not a local buffer: ssh2 only sends a window
+ * adjustment while the stream is flowing, so a paused channel lets the peer's
+ * send window drain to zero and the remote command blocks on its own write.
+ * The retained ceiling is therefore this mark plus ssh2's window (2 MiB) plus
+ * whatever is in flight — bounded, but not exactly 4 MiB.
+ *
+ * The counter is per session, not per socket: one lagging socket pauses the
+ * channel for every socket attached to that shell. That is deliberate — the
+ * alternative is letting the slowest consumer grow the host process.
+ */
+const OUT_HIGH_WATER = 4 * 1024 * 1024
+const OUT_LOW_WATER = 1 * 1024 * 1024
+
+/**
+ * The largest client frame accepted, in bytes.
+ *
+ * The only frame with a payload is `in` — keystrokes, and pastes, which the
+ * client chunks to stay under this. The upgrade server (`routes.ts`) passes
+ * this value as ws's `maxPayload`, so an oversized frame is refused before it
+ * is buffered at all; the check in `hookSocket` is the second layer, and it is
+ * what keeps such a frame from becoming a string plus an object graph in the
+ * process that also runs the agent.
+ */
+export const TERMINAL_MAX_FRAME_BYTES = 1024 * 1024
+
+export class TerminalSessionRegistry {
+  private readonly sessions = new Map<string, Session>()
+
+  constructor(private readonly pool: RemotePool) {}
+
+  /** Open a shell and attach the first socket. */
+  async open(ws: WebSocket, alias: string, cols: number, rows: number): Promise<string> {
+    const id = randomUUID().slice(0, 8)
+    let channel: ClientChannel
+    try {
+      channel = await this.pool.shell(alias, { cols, rows })
+    } catch (error) {
+      this.send(ws, { t: 'error', message: error instanceof Error ? error.message : String(error) })
+      try {
+        ws.close(1011)
+      } catch {
+        // Ignore.
+      }
+      throw error
+    }
+    const session: Session = {
+      id,
+      alias,
+      channel,
+      alive: true,
+      exitCode: null,
+      sockets: new Set(),
+      pending: 0,
+      paused: false,
+      reap: undefined,
+    }
+    this.sessions.set(id, session)
+    channel.on('data', (chunk: Buffer) => {
+      this.broadcast(session, { t: 'out', d: chunk.toString('utf8') })
+    })
+    channel.stderr.on('data', (chunk: Buffer) => {
+      this.broadcast(session, { t: 'out', d: chunk.toString('utf8') })
+    })
+    channel.on('close', (code: number | null) => {
+      session.alive = false
+      session.exitCode = code
+      this.broadcast(session, { t: 'exit', code })
+      for (const socket of session.sockets) {
+        try {
+          socket.close(1000)
+        } catch {
+          // Ignore.
+        }
+      }
+    })
+    this.hookSocket(session, ws)
+    this.send(ws, { t: 'ready', id })
+    return id
+  }
+
+  /**
+   * Attach another socket to a live session; false when unknown/dead.
+   *
+   * The size in the URL is deliberately NOT applied here. It is the same
+   * fixed 80x24 the view uses to open a shell, and re-applying it on every
+   * reattach — which is what a page reload does — SHRANK a running shell:
+   * SIGWINCH, and a full-screen program re-laying itself out at 80 columns,
+   * until that tab became visible and refit. The session already has a size.
+   * The socket sends a real `resize` frame as soon as it can measure itself
+   * (`XTerm.pushSize`), which is the only place that knows how wide it is.
+   *
+   * The parameters stay because the upgrade handler owns the URL and passes
+   * them on both paths; they matter to `open` (the PTY's initial size) only.
+   */
+  attach(ws: WebSocket, id: string, _cols: number, _rows: number): boolean {
+    const session = this.sessions.get(id)
+    if (session === undefined || !session.alive) return false
+    this.hookSocket(session, ws)
+    this.send(ws, { t: 'ready', id })
+    return true
+  }
+
+  /** Close one session (kills the remote shell). */
+  close(id: string): boolean {
+    const session = this.sessions.get(id)
+    if (session === undefined) return false
+    this.sessions.delete(id)
+    this.cancelReap(session)
+    try {
+      session.channel.close()
+    } catch {
+      // Ignore.
+    }
+    for (const socket of session.sockets) {
+      try {
+        socket.close(1000)
+      } catch {
+        // Ignore.
+      }
+    }
+    session.sockets.clear()
+    return true
+  }
+
+  /** Close every session (plugin unload). */
+  dispose(): void {
+    for (const id of [...this.sessions.keys()]) this.close(id)
+  }
+
+  list(): { id: string; alias: string; alive: boolean }[] {
+    return [...this.sessions.values()].map(s => ({ id: s.id, alias: s.alias, alive: s.alive }))
+  }
+
+  private hookSocket(session: Session, ws: WebSocket): void {
+    // A socket is back: the session is in use, so cancel any pending reap.
+    this.cancelReap(session)
+    session.sockets.add(ws)
+    ws.on('message', (raw) => {
+      // Refuse an oversized frame before parsing it — see
+      // TERMINAL_MAX_FRAME_BYTES. 1009 is the protocol's "message too big".
+      const bytes = Array.isArray(raw) ? raw.reduce((total, part) => total + part.byteLength, 0) : raw.byteLength
+      if (bytes > TERMINAL_MAX_FRAME_BYTES) {
+        try {
+          ws.close(1009)
+        } catch {
+          // Already gone.
+        }
+        return
+      }
+      let frame: TerminalClientFrame
+      try {
+        frame = JSON.parse(String(raw)) as TerminalClientFrame
+      } catch {
+        return
+      }
+      if (!session.alive) return
+      if (frame.t === 'in' && typeof frame.d === 'string') {
+        try {
+          session.channel.write(frame.d)
+        } catch {
+          // Ignore.
+        }
+      } else if (frame.t === 'resize' && Number.isFinite(frame.cols) && Number.isFinite(frame.rows)) {
+        try {
+          session.channel.setWindow(frame.rows, frame.cols, 0, 0)
+        } catch {
+          // Ignore.
+        }
+      }
+    })
+    const detach = (): void => {
+      session.sockets.delete(ws)
+      if (session.sockets.size > 0) return
+      // Nobody is watching any more. Release the brake first — a paused channel
+      // would otherwise stay paused with no socket left to resume it — then
+      // start the clock that ends the session (and with it the remote shell).
+      session.pending = 0
+      this.setPaused(session, false)
+      this.armReap(session)
+    }
+    ws.on('close', detach)
+    ws.on('error', detach)
+  }
+
+  /** Keep the shell for a while (reload can reattach), then close it for good. */
+  private armReap(session: Session): void {
+    this.cancelReap(session)
+    const timer = setTimeout(() => {
+      session.reap = undefined
+      // A late detach can arm a timer for a session that close() already
+      // removed; never act on an entry that is no longer the registered one.
+      if (this.sessions.get(session.id) !== session) return
+      if (session.sockets.size === 0) this.close(session.id)
+    }, EMPTY_SOCKET_TTL_MS)
+    timer.unref?.()
+    session.reap = timer
+  }
+
+  private cancelReap(session: Session): void {
+    if (session.reap === undefined) return
+    clearTimeout(session.reap)
+    session.reap = undefined
+  }
+
+  private setPaused(session: Session, paused: boolean): void {
+    if (session.paused === paused) return
+    session.paused = paused
+    try {
+      if (paused) session.channel.pause()
+      else session.channel.resume()
+    } catch {
+      // The channel may already be gone; the flag still records the intent.
+    }
+  }
+
+  private send(ws: WebSocket, frame: TerminalServerFrame): void {
+    try {
+      ws.send(JSON.stringify(frame))
+    } catch {
+      // Socket raced away.
+    }
+  }
+
+  private broadcast(session: Session, frame: TerminalServerFrame): void {
+    const text = JSON.stringify(frame)
+    // Bytes, not UTF-16 code units: CJK and emoji output would otherwise be
+    // undercounted by up to 3x and the brake would come on too late.
+    const size = Buffer.byteLength(text, 'utf8')
+    for (const socket of session.sockets) {
+      let settled = false
+      // The send callback fires once the frame is on the wire. It is the only
+      // public signal for "this socket has caught up", and it avoids relying on
+      // ws internals (bufferedAmount does not report the socket write queue).
+      const done = (): void => {
+        if (settled) return
+        settled = true
+        session.pending = Math.max(0, session.pending - size)
+        if (session.pending <= OUT_LOW_WATER) this.setPaused(session, false)
+      }
+      session.pending += size
+      try {
+        socket.send(text, done)
+      } catch {
+        done()
+      }
+    }
+    if (session.pending > OUT_HIGH_WATER) this.setPaused(session, true)
+  }
+}