@tiphareth/dsh-hardssh 0.1.2

package/src/ssh/routes.ts

@@ -0,0 +1,892 @@
+/**
+ * The /api/dsh-ssh route family: host CRUD, exec, cluster, SFTP transfer
+ * (NDJSON progress stream for uploads, binary stream for downloads), remote
+ * listing, tunnels, and the WebSocket PTY terminal upgrade. Every route
+ * carries a loopback-only trust fence (plus browser same-origin markers) —
+ * these endpoints execute commands on remote servers, so LAN-exposed dsh web
+ * deployments must not serve them.
+ */
+
+import { createReadStream, createWriteStream, mkdirSync } from 'node:fs'
+import { unlink } from 'node:fs/promises'
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import { basename, join } from 'node:path'
+import { tmpdir } from 'node:os'
+import { randomBytes } from 'node:crypto'
+import { WebSocket, WebSocketServer } from 'ws'
+import type { WebRoute, WebUpgradeRoute } from '@deepseek-ai/dsh-host-webserver'
+import type { SshEngine, ShellSession } from './engine.ts'
+import { SSH_API, type HostPayload, type ApiErrorBody, type TerminalClientFrame, type TerminalServerFrame } from './protocol.ts'
+import type { HostStore } from './store.ts'
+import { HostKeyMismatchError, HostKeyUnknownError, type KnownHostsStore } from './known-hosts.ts'
+import { NeedsPasswordError } from './engine.ts'
+
+/** Cap on JSON request bodies (host entries and exec payloads are small). */
+const MAX_JSON_BODY_BYTES = 64 * 1024
+
+/** Cap on declared upload bodies (staged to disk before SFTP). */
+export const DEFAULT_MAX_UPLOAD_BYTES = 4 * 1024 * 1024 * 1024
+
+/**
+ * One noServer WebSocket server for terminal upgrades: the browser half uses
+ * a standards-compliant WebSocket, so the host must speak real RFC 6455
+ * frames (the webserver hands us the raw upgraded socket).
+ */
+const terminalWss = new WebSocketServer({ noServer: true })
+
+/** Pause the shell when the socket's send buffer exceeds this… */
+const BACKPRESSURE_HIGH_WATER = 1024 * 1024
+
+/** …and resume once it drains below this. */
+const BACKPRESSURE_LOW_WATER = 512 * 1024
+
+/** Result of staging one upload body under a hard byte limit. */
+type StageUploadResult =
+  | { ok: true; receivedBytes: number }
+  | { ok: false; reason: 'too-large' | 'aborted' | 'request-error' | 'write-error'; receivedBytes: number; error: Error }
+
+function toError(error: unknown): Error {
+  return error instanceof Error ? error : new Error(String(error))
+}
+
+/** Idempotent staging-file cleanup (ENOENT is fine; other errors surface). */
+async function removeStagingFile(path: string): Promise<void> {
+  try {
+    await unlink(path)
+  } catch (error) {
+    if (typeof error === 'object' && error !== null && 'code' in error && error.code === 'ENOENT') return
+    throw error
+  }
+}
+
+/**
+ * Stage a request body to `tmpPath` while enforcing a hard cap on the bytes
+ * ACTUALLY received (`Content-Length` is only a fast-reject hint — chunked
+ * and under-declared bodies must be caught here). On every failure the sink
+ * is destroyed, its 'close' waited for (Windows needs the handle released
+ * before unlink), and the partial file removed. Resolves only after the
+ * write stream finished, so a success means the body is fully on disk.
+ */
+function stageUploadBody(req: IncomingMessage, tmpPath: string, limitBytes: number): Promise<StageUploadResult> {
+  return new Promise((resolve) => {
+    const sink = createWriteStream(tmpPath, { flags: 'wx' })
+
+    let receivedBytes = 0
+    let terminal = false
+    let result: StageUploadResult | undefined
+
+    const detachRequestListeners = (): void => {
+      req.off('data', onData)
+      req.off('end', onEnd)
+      req.off('aborted', onAborted)
+      req.off('error', onRequestError)
+    }
+
+    const resolveFailureAfterClose = (failure: Exclude<StageUploadResult, { ok: true }>): void => {
+      if (terminal) return
+      terminal = true
+      result = failure
+      detachRequestListeners()
+      // Stop consuming body bytes; the socket is torn down after the 413.
+      req.pause()
+      if (!sink.destroyed) sink.destroy()
+    }
+
+    const onData = (chunk: Buffer | string): void => {
+      if (terminal) return
+      const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)
+      receivedBytes += buffer.length
+      if (receivedBytes > limitBytes) {
+        // The over-limit chunk is NOT written, so the temp file never
+        // exceeds the cap.
+        resolveFailureAfterClose({ ok: false, reason: 'too-large', receivedBytes, error: new Error('upload body too large') })
+        return
+      }
+      // Respect filesystem backpressure instead of buffering unbounded data.
+      if (!sink.write(buffer)) {
+        req.pause()
+        sink.once('drain', () => { if (!terminal) req.resume() })
+      }
+    }
+
+    const onEnd = (): void => {
+      if (terminal) return
+      detachRequestListeners()
+      sink.end()
+    }
+
+    const onAborted = (): void => {
+      resolveFailureAfterClose({ ok: false, reason: 'aborted', receivedBytes, error: new Error('upload aborted by the client') })
+    }
+
+    const onRequestError = (error: Error): void => {
+      resolveFailureAfterClose({ ok: false, reason: 'request-error', receivedBytes, error: toError(error) })
+    }
+
+    sink.on('error', (error) => {
+      resolveFailureAfterClose({ ok: false, reason: 'write-error', receivedBytes, error: toError(error) })
+    })
+
+    sink.on('finish', () => {
+      if (terminal) return
+      terminal = true
+      detachRequestListeners()
+      resolve({ ok: true, receivedBytes })
+    })
+
+    sink.on('close', () => {
+      if (result === undefined) return
+      const failure = result
+      result = undefined
+      void removeStagingFile(tmpPath).catch(() => undefined).then(() => resolve(failure))
+    })
+
+    req.on('data', onData)
+    req.once('end', onEnd)
+    req.once('aborted', onAborted)
+    req.once('error', onRequestError)
+  })
+}
+
+/** 413 + connection: close so the sender cannot keep streaming into the socket. */
+function rejectUploadTooLarge(req: IncomingMessage, res: ServerResponse): void {
+  const payload = JSON.stringify({ error: 'upload body too large' })
+  res.writeHead(413, {
+    'content-type': 'application/json; charset=utf-8',
+    'content-length': String(Buffer.byteLength(payload)),
+    'connection': 'close',
+    'referrer-policy': 'no-referrer',
+  })
+  res.end(payload, () => {
+    if (!req.socket.destroyed) req.socket.destroy()
+  })
+}
+
+/** Loopback literal check plus browser same-origin markers (mirrors the pairing routes' fence). */
+function isLoopbackRequest(request: IncomingMessage): boolean {
+  const address = request.socket.remoteAddress
+  if (address !== '127.0.0.1' && address !== '::1' && address !== '::ffff:127.0.0.1') return false
+  const host = request.headers.host
+  if (typeof host !== 'string') return false
+  let hostUrl: URL
+  try {
+    hostUrl = new URL(`http://${host}`)
+  } catch {
+    return false
+  }
+  if (hostUrl.hostname !== '127.0.0.1' && hostUrl.hostname !== 'localhost' && hostUrl.hostname !== '[::1]') return false
+  if (request.headers['sec-fetch-site'] === 'cross-site') return false
+  const origin = request.headers.origin
+  if (origin === undefined) return true
+  try {
+    return new URL(origin).host === hostUrl.host
+  } catch {
+    return false
+  }
+}
+
+/** One JSON response. */
+function writeJson(res: ServerResponse, status: number, body: unknown): void {
+  const payload = JSON.stringify(body)
+  res.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'referrer-policy': 'no-referrer' })
+  res.end(payload)
+}
+
+/** Map a thrown error to a structured ApiErrorBody (host-key errors carry
+ *  machine codes + fingerprints for the GUI's confirm dialog). */
+function errorBody(error: unknown): ApiErrorBody {
+  if (error instanceof HostKeyUnknownError) {
+    return { error: error.message, code: 'HOST_KEY_UNKNOWN', hostKeyFingerprint: error.fingerprintSha256 }
+  }
+  if (error instanceof HostKeyMismatchError) {
+    return { error: error.message, code: 'HOST_KEY_MISMATCH', hostKeyFingerprint: error.actual, hostKeyMismatch: { expected: error.expected, actual: error.actual } }
+  }
+  if (error instanceof NeedsPasswordError) {
+    return { error: error.message, code: 'NEEDS_PASSWORD', secret: error.secret }
+  }
+  return { error: error instanceof Error ? error.message : String(error) }
+}
+
+/** Read a JSON request body (undefined when too large or unparseable). */
+async function readJsonBody(req: IncomingMessage): Promise<Record<string, unknown> | undefined> {
+  const chunks: Buffer[] = []
+  let size = 0
+  for await (const chunk of req) {
+    const buffer = chunk as Buffer
+    size += buffer.length
+    if (size > MAX_JSON_BODY_BYTES) return undefined
+    chunks.push(buffer)
+  }
+  try {
+    const parsed: unknown = JSON.parse(Buffer.concat(chunks).toString('utf8'))
+    return typeof parsed === 'object' && parsed !== null ? parsed as Record<string, unknown> : undefined
+  } catch {
+    return undefined
+  }
+}
+
+/** URL query helper (first value, decoded). */
+function queryParam(url: URL, name: string): string | undefined {
+  const value = url.searchParams.get(name)
+  return value === null ? undefined : value
+}
+
+/** Route family dependencies. */
+export interface SshRoutesDeps {
+  /** The host store (CRUD; vault-backed for secrets). */
+  store: import('./store.ts').SecureHostStore
+  /** The engine (ops). */
+  engine: SshEngine
+  /** Host-key trust store (TOFU); absent → host-key verification disabled. */
+  knownHosts?: KnownHostsStore
+  /** Credential vault (optional; enables /api/dsh-ssh/vault endpoints). */
+  vault?: import('./vault.ts').Vault
+  /** SSH-bound workspace ledger (host-delete reference check). */
+  ledger?: import('../ledger.ts').SshWorkspaceLedger
+  /** Temp dir for upload/download staging (tests inject a sandbox). */
+  stagingDir?: string
+  /** Hard cap on ACTUAL upload bytes accepted (chunked requests included).
+   *  Defaults to 4 GiB; tests inject a small value. */
+  uploadLimitBytes?: number
+  /** Called after a host PATCH/DELETE persisted, so derived caches (e.g. the
+   *  remote environment cache) can drop that alias. */
+  onHostInvalidated?: (alias: string) => void
+}
+
+/**
+ * Build every /api/dsh-ssh route (exact paths) plus the terminal upgrade.
+ * @param deps - store, engine, staging dir.
+ * @returns routes and the upgrade route.
+ */
+export function makeRoutes(deps: SshRoutesDeps): { routes: WebRoute[]; upgrade: WebUpgradeRoute } {
+  const { store, engine } = deps
+  const staging = deps.stagingDir ?? join(tmpdir(), 'dsh-ssh-uploads')
+  const uploadLimitBytes = deps.uploadLimitBytes ?? DEFAULT_MAX_UPLOAD_BYTES
+  if (!Number.isSafeInteger(uploadLimitBytes) || uploadLimitBytes < 0) {
+    throw new RangeError('uploadLimitBytes must be a non-negative safe integer')
+  }
+  // The upload route stages request bodies here; it must exist before the
+  // first request (a missing dir would hang the first upload forever).
+  mkdirSync(staging, { recursive: true })
+
+  /** Guard helper: fence + method check. */
+  const guard = (req: IncomingMessage, res: ServerResponse, method: string): boolean => {
+    if (!isLoopbackRequest(req)) {
+      writeJson(res, 403, { error: 'forbidden: loopback-only' })
+      return false
+    }
+    if (req.method !== method) {
+      writeJson(res, 405, { error: `method not allowed: ${req.method}` })
+      return false
+    }
+    return true
+  }
+
+  const routes: WebRoute[] = [
+    // ------------------------------------------------------------ hosts
+    {
+      kind: 'exact',
+      path: SSH_API.hosts,
+      handler: async (req, res) => {
+        // One handler per path (the webserver keyed route registry rejects
+        // duplicate (kind, path)); dispatch by HTTP method here.
+        const method = req.method ?? 'GET'
+        if (!isLoopbackRequest(req)) {
+          writeJson(res, 403, { error: 'forbidden: loopback-only' })
+          return
+        }
+        const url = new URL(req.url ?? '/', 'http://localhost')
+        if (method === 'GET') {
+          writeJson(res, 200, { hosts: engine.list(queryParam(url, 'query')) })
+          return
+        }
+        if (method === 'POST') {
+          const body = await readJsonBody(req)
+          if (body === undefined) {
+            writeJson(res, 400, { error: 'invalid JSON body' })
+            return
+          }
+          try {
+            const entry = await store.create(body as unknown as HostPayload)
+            writeJson(res, 201, { host: store.summarize(entry) })
+          } catch (error) {
+            writeJson(res, 400, { error: error instanceof Error ? error.message : String(error) })
+          }
+          return
+        }
+        if (method !== 'PATCH' && method !== 'DELETE') {
+          writeJson(res, 405, { error: `method not allowed: ${method}` })
+          return
+        }
+        const alias = queryParam(url, 'alias')
+        if (alias === undefined || alias === '') {
+          writeJson(res, 400, { error: 'alias query parameter is required' })
+          return
+        }
+        if (method === 'PATCH') {
+          const body = await readJsonBody(req)
+          if (body === undefined) {
+            writeJson(res, 400, { error: 'invalid JSON body' })
+            return
+          }
+          try {
+            const entry = await store.update(alias, body as unknown as Partial<HostPayload>)
+            // Persist first. A validation/save failure must leave all
+            // existing connections untouched. drain lets in-flight
+            // operations finish while generation invalidation guarantees
+            // subsequent acquisitions cannot reuse the old config's
+            // connection (or publish one built from it).
+            engine.invalidate(alias, { includeDependents: true, mode: 'drain' })
+            deps.onHostInvalidated?.(alias)
+            writeJson(res, 200, { host: store.summarize(entry) })
+          } catch (error) {
+            writeJson(res, 400, { error: error instanceof Error ? error.message : String(error) })
+          }
+          return
+        }
+        if (method === 'DELETE') {
+          // Reference guard: a host still backing SSH-bound workspaces must
+          // not be deleted (the workspaces would silently lose their
+          // transport). Return 409 with the referencing workspace titles.
+          if (deps.ledger !== undefined) {
+            const referenced = (await deps.ledger.list()).filter(record => record.alias === alias)
+            if (referenced.length > 0) {
+              writeJson(res, 409, {
+                error: `alias '${alias}' is still referenced by ${referenced.length} SSH workspace(s) (${referenced.map(r => r.title).join('、')}) — delete those workspaces first`,
+                code: 'HOST_IN_USE',
+                workspaces: referenced.map(record => ({ id: record.id, title: record.title })),
+              })
+              return
+            }
+          }
+          try {
+            // Delete first so a missing alias or failed store write does not
+            // disturb a live tunnel/connection.
+            await store.delete(alias)
+            // Tunnels own leases: release them before forcing the remaining
+            // pooled transport so records/sockets clean up normally.
+            engine.stopAllTunnels(alias)
+            engine.invalidate(alias, { mode: 'force' })
+            deps.onHostInvalidated?.(alias)
+            writeJson(res, 200, { ok: true })
+          } catch (error) {
+            writeJson(res, 400, { error: error instanceof Error ? error.message : String(error) })
+          }
+          return
+        }
+        writeJson(res, 405, { error: `method not allowed: ${method}` })
+      },
+    },
+    {
+      kind: 'exact',
+      path: SSH_API.importSshConfig,
+      handler: async (req, res) => {
+        if (!guard(req, res, 'POST')) return
+        try {
+          writeJson(res, 200, { result: store.importFromSshConfig() })
+        } catch (error) {
+          writeJson(res, 500, { error: error instanceof Error ? error.message : String(error) })
+        }
+      },
+    },
+    // -------------------------------------------------------- known-hosts
+    {
+      kind: 'exact',
+      path: SSH_API.knownHosts,
+      handler: async (req, res) => {
+        if (!isLoopbackRequest(req)) {
+          writeJson(res, 403, { error: 'forbidden: loopback-only' })
+          return
+        }
+        const method = req.method ?? 'GET'
+        const url = new URL(req.url ?? '/', 'http://localhost')
+        const knownHosts = deps.knownHosts
+        if (knownHosts === undefined) {
+          writeJson(res, 404, { error: 'host-key trust store is not enabled' })
+          return
+        }
+        if (method === 'GET') {
+          const alias = queryParam(url, 'alias')
+          const records = knownHosts.list()
+            .filter(record => alias === undefined || alias === '' || record.alias === alias)
+            .map(record => ({
+              alias: record.alias,
+              host: record.host,
+              port: record.port,
+              keyType: record.keyType,
+              fingerprint: record.fingerprint,
+              status: record.status,
+              firstSeenAt: record.firstSeenAt,
+              confirmedAt: record.confirmedAt,
+            } satisfies import('./protocol.ts').KnownHostView))
+          writeJson(res, 200, { records })
+          return
+        }
+        if (method !== 'POST') {
+          writeJson(res, 405, { error: `method not allowed: ${method}` })
+          return
+        }
+        const body = await readJsonBody(req)
+        const alias = typeof body?.alias === 'string' ? body.alias : ''
+        const action = typeof body?.action === 'string' ? body.action : ''
+        if (alias === '' || (action !== 'trust' && action !== 'forget')) {
+          writeJson(res, 400, { error: 'alias and action (trust|forget) are required' })
+          return
+        }
+        try {
+          if (action === 'trust') knownHosts.trust(alias)
+          else knownHosts.forget(alias)
+          writeJson(res, 200, { ok: true })
+        } catch (error) {
+          writeJson(res, 400, { error: error instanceof Error ? error.message : String(error) })
+        }
+      },
+    },
+    // ------------------------------------------------------------- vault
+    {
+      kind: 'exact',
+      path: SSH_API.vault,
+      handler: async (req, res) => {
+        if (!isLoopbackRequest(req)) {
+          writeJson(res, 403, { error: 'forbidden: loopback-only' })
+          return
+        }
+        const vault = deps.vault
+        if (vault === undefined) {
+          writeJson(res, 404, { error: 'credential vault is not enabled' })
+          return
+        }
+        const method = req.method ?? 'GET'
+        if (method === 'GET') {
+          writeJson(res, 200, { status: vault.status() })
+          return
+        }
+        if (method !== 'POST') {
+          writeJson(res, 405, { error: `method not allowed: ${method}` })
+          return
+        }
+        const body = await readJsonBody(req)
+        const action = typeof body?.action === 'string' ? body.action : ''
+        try {
+          if (action === 'status') {
+            writeJson(res, 200, { status: vault.status() })
+            return
+          }
+          if (action === 'unlock') {
+            const password = typeof body?.password === 'string' ? body.password : ''
+            await vault.unlock(password)
+            writeJson(res, 200, { ok: true, status: vault.status() })
+            return
+          }
+          if (action === 'rekey') {
+            const password = typeof body?.password === 'string' ? body.password : ''
+            await vault.rekey(password)
+            writeJson(res, 200, { ok: true, status: vault.status() })
+            return
+          }
+          writeJson(res, 400, { error: 'action must be status|unlock|rekey' })
+        } catch (error) {
+          // Vault errors carry stable codes (VAULT_LOCKED / VAULT_AUTH /
+          // VAULT_LOCKOUT) + retry info; surface the message + code.
+          const record = error as { code?: unknown }
+          writeJson(res, 401, {
+            error: error instanceof Error ? error.message : String(error),
+            code: typeof record.code === 'string' ? record.code : undefined,
+          })
+        }
+      },
+    },
+    // --------------------------------------------------- session-secret
+    {
+      kind: 'exact',
+      path: SSH_API.sessionSecret,
+      handler: async (req, res) => {
+        if (!isLoopbackRequest(req)) {
+          writeJson(res, 403, { error: 'forbidden: loopback-only' })
+          return
+        }
+        if ((req.method ?? '') !== 'POST') {
+          writeJson(res, 405, { error: `method not allowed: ${req.method}` })
+          return
+        }
+        const body = await readJsonBody(req)
+        const alias = typeof body?.alias === 'string' ? body.alias : ''
+        const password = typeof body?.password === 'string' ? body.password : undefined
+        const passphrase = typeof body?.passphrase === 'string' ? body.passphrase : undefined
+        if (alias === '' || (password === undefined && passphrase === undefined)) {
+          writeJson(res, 400, { error: 'alias and password|passphrase are required' })
+          return
+        }
+        // Memory-only: never persisted; consumed by connectChain for the
+        // pooled connection's lifetime (idle 30 min auto-disconnect).
+        engine.setSessionPassword(alias, { password, passphrase })
+        writeJson(res, 200, { ok: true })
+      },
+    },
+    // --------------------------------------------------- connections
+    {
+      kind: 'exact',
+      path: SSH_API.connections,
+      handler: async (req, res) => {
+        if (!isLoopbackRequest(req)) {
+          writeJson(res, 403, { error: 'forbidden: loopback-only' })
+          return
+        }
+        if ((req.method ?? '') !== 'GET') {
+          writeJson(res, 405, { error: `method not allowed: ${req.method}` })
+          return
+        }
+        writeJson(res, 200, { connected: engine.connectedAliases() })
+      },
+    },
+    // ------------------------------------------------------------ ops
+    {
+      kind: 'exact',
+      path: SSH_API.test,
+      handler: async (req, res) => {
+        if (!guard(req, res, 'POST')) return
+        const body = await readJsonBody(req)
+        const alias = typeof body?.alias === 'string' ? body.alias : ''
+        if (alias === '') {
+          writeJson(res, 400, { error: 'alias is required' })
+          return
+        }
+        try {
+          writeJson(res, 200, { result: await engine.test(alias) })
+        } catch (error) {
+          if (error instanceof NeedsPasswordError) {
+            // Not a failure: the connection needs a credential the user
+            // hasn't entered this session yet. Return a structured prompt
+            // (200) so the GUI can show the password dialog and retry.
+            writeJson(res, 200, {
+              result: { ok: false, error: error.message, code: 'NEEDS_PASSWORD', secret: error.secret },
+            })
+            return
+          }
+          writeJson(res, 500, errorBody(error))
+        }
+      },
+    },
+    {
+      kind: 'exact',
+      path: SSH_API.exec,
+      handler: async (req, res) => {
+        if (!guard(req, res, 'POST')) return
+        const body = await readJsonBody(req)
+        const alias = typeof body?.alias === 'string' ? body.alias : ''
+        const command = typeof body?.command === 'string' ? body.command : ''
+        if (alias === '' || command === '') {
+          writeJson(res, 400, { error: 'alias and command are required' })
+          return
+        }
+        const timeoutMs = typeof body?.timeoutMs === 'number' ? body.timeoutMs : undefined
+        try {
+          writeJson(res, 200, { result: await engine.exec(alias, command, timeoutMs) })
+        } catch (error) {
+          writeJson(res, 500, errorBody(error))
+        }
+      },
+    },
+    {
+      kind: 'exact',
+      path: SSH_API.cluster,
+      handler: async (req, res) => {
+        if (!guard(req, res, 'POST')) return
+        const body = await readJsonBody(req)
+        const command = typeof body?.command === 'string' ? body.command : ''
+        if (command === '') {
+          writeJson(res, 400, { error: 'command is required' })
+          return
+        }
+        const aliases = Array.isArray(body?.aliases) ? body.aliases.filter((x): x is string => typeof x === 'string') : undefined
+        const tags = Array.isArray(body?.tags) ? body.tags.filter((x): x is string => typeof x === 'string') : undefined
+        const environment = typeof body?.environment === 'string' ? body.environment : undefined
+        const timeoutMs = typeof body?.timeoutMs === 'number' ? body.timeoutMs : undefined
+        const maxWorkers = typeof body?.maxWorkers === 'number' ? body.maxWorkers : undefined
+        try {
+          writeJson(res, 200, { results: await engine.cluster({ command, aliases, environment, tags, timeoutMs, maxWorkers }) })
+        } catch (error) {
+          writeJson(res, 500, { error: error instanceof Error ? error.message : String(error) })
+        }
+      },
+    },
+    // ------------------------------------------------------------- ls
+    {
+      kind: 'exact',
+      path: SSH_API.ls,
+      handler: async (req, res) => {
+        if (!guard(req, res, 'GET')) return
+        const url = new URL(req.url ?? '/', 'http://localhost')
+        const alias = queryParam(url, 'alias')
+        const path = queryParam(url, 'path') ?? '/'
+        if (alias === undefined || alias === '') {
+          writeJson(res, 400, { error: 'alias query parameter is required' })
+          return
+        }
+        try {
+          writeJson(res, 200, { entries: await engine.ls(alias, path) })
+        } catch (error) {
+          writeJson(res, 400, { error: error instanceof Error ? error.message : String(error) })
+        }
+      },
+    },
+    // --------------------------------------------------------- tunnel
+    {
+      kind: 'exact',
+      path: SSH_API.tunnel,
+      handler: async (req, res) => {
+        if (!guard(req, res, 'POST')) return
+        const body = await readJsonBody(req)
+        const action = typeof body?.action === 'string' ? body.action : ''
+        if (action === 'list') {
+          writeJson(res, 200, { tunnels: engine.listTunnels() })
+          return
+        }
+        if (action === 'start') {
+          const alias = typeof body?.alias === 'string' ? body.alias : ''
+          const remotePort = typeof body?.remotePort === 'number' ? body.remotePort : undefined
+          if (alias === '' || remotePort === undefined) {
+            writeJson(res, 400, { error: 'alias and remotePort are required' })
+            return
+          }
+          try {
+            const tunnel = await engine.startTunnel(alias, {
+              remotePort,
+              remoteHost: typeof body?.remoteHost === 'string' && body.remoteHost !== '' ? body.remoteHost : undefined,
+              localPort: typeof body?.localPort === 'number' ? body.localPort : undefined,
+            })
+            writeJson(res, 200, { tunnel })
+          } catch (error) {
+            writeJson(res, 500, { error: error instanceof Error ? error.message : String(error) })
+          }
+          return
+        }
+        if (action === 'stop') {
+          const id = typeof body?.tunnelId === 'string' ? body.tunnelId : ''
+          if (id === '') {
+            writeJson(res, 400, { error: 'tunnelId is required' })
+            return
+          }
+          writeJson(res, 200, { ok: engine.stopTunnel(id) })
+          return
+        }
+        if (action === 'stop-all') {
+          const alias = typeof body?.alias === 'string' ? body.alias : undefined
+          writeJson(res, 200, { stopped: engine.stopAllTunnels(alias === '' ? undefined : alias) })
+          return
+        }
+        writeJson(res, 400, { error: `unknown action '${action}'` })
+      },
+    },
+    // --------------------------------------------------------- upload
+    {
+      kind: 'exact',
+      path: SSH_API.upload,
+      handler: async (req, res) => {
+        if (!guard(req, res, 'POST')) return
+        const url = new URL(req.url ?? '/', 'http://localhost')
+        const alias = queryParam(url, 'alias')
+        const remotePath = queryParam(url, 'remotePath')
+        if (alias === undefined || remotePath === undefined) {
+          writeJson(res, 400, { error: 'alias and remotePath query parameters are required' })
+          return
+        }
+
+        // Content-Length is only a fast-reject path; never trust it as proof
+        // the actual body is within the limit (chunked / under-declared).
+        const contentLengthHeader = req.headers['content-length']
+        const declaredBytes = typeof contentLengthHeader === 'string' ? Number(contentLengthHeader) : Number.NaN
+        if (Number.isFinite(declaredBytes) && declaredBytes > uploadLimitBytes) {
+          writeJson(res, 413, { error: 'upload body too large' })
+          return
+        }
+
+        const tmp = join(staging, `upload-${randomBytes(6).toString('hex')}`)
+
+        // Stage and validate the WHOLE body before starting the NDJSON 200 —
+        // over-limit bodies get a real HTTP 413, not a failure frame inside
+        // an already-started 200 stream.
+        const staged = await stageUploadBody(req, tmp, uploadLimitBytes)
+
+        if (!staged.ok) {
+          if (staged.reason === 'too-large') {
+            if (!res.headersSent) {
+              rejectUploadTooLarge(req, res)
+            } else {
+              res.destroy()
+            }
+            return
+          }
+          if (!res.headersSent) {
+            writeJson(res, staged.reason === 'aborted' ? 400 : 500, { error: staged.error.message })
+          } else {
+            res.destroy(staged.error)
+          }
+          return
+        }
+
+        res.writeHead(200, {
+          'content-type': 'application/x-ndjson; charset=utf-8',
+          'cache-control': 'no-cache',
+          'referrer-policy': 'no-referrer',
+        })
+
+        let responseClosed = false
+        const emit = (line: unknown): void => {
+          if (responseClosed || res.destroyed || res.writableEnded) return
+          try { res.write(`${JSON.stringify(line)}\n`) } catch { responseClosed = true }
+        }
+        const onResponseClose = (): void => { responseClosed = true }
+        res.once('close', onResponseClose)
+
+        try {
+          emit({ type: 'progress', progress: { phase: 'connecting', file: remotePath, transferred: 0, total: staged.receivedBytes, percent: 0 } })
+          const outcome = await engine.upload(alias, tmp, remotePath, false, progress => emit({ type: 'progress', progress }))
+          emit({ type: 'result', ok: true, transferredBytes: outcome.bytes })
+        } catch (error) {
+          emit({ type: 'result', ok: false, error: error instanceof Error ? error.message : String(error) })
+        } finally {
+          // engine.upload() has settled (read handle released) — safe to unlink.
+          await removeStagingFile(tmp).catch(() => undefined)
+          res.off('close', onResponseClose)
+          if (!responseClosed && !res.destroyed && !res.writableEnded) {
+            try { res.end() } catch { /* client gone */ }
+          }
+        }
+      },
+    },
+    // ------------------------------------------------------- download
+    {
+      kind: 'exact',
+      path: SSH_API.download,
+      handler: async (req, res) => {
+        if (!guard(req, res, 'GET')) return
+        const url = new URL(req.url ?? '/', 'http://localhost')
+        const alias = queryParam(url, 'alias')
+        const remotePath = queryParam(url, 'remotePath')
+        if (alias === undefined || remotePath === undefined) {
+          writeJson(res, 400, { error: 'alias and remotePath query parameters are required' })
+          return
+        }
+        const tmp = join(staging, `download-${randomBytes(6).toString('hex')}`)
+        try {
+          const outcome = await engine.download(alias, remotePath, tmp)
+          res.writeHead(200, {
+            'content-type': 'application/octet-stream',
+            'content-length': String(outcome.bytes),
+            'content-disposition': `attachment; filename="${basename(remotePath).replace(/"/g, '')}"`,
+            'referrer-policy': 'no-referrer',
+          })
+          await new Promise<void>((resolve, reject) => {
+            const source = createReadStream(tmp)
+            source.on('error', reject)
+            res.on('error', reject)
+            source.pipe(res)
+            source.on('end', resolve)
+          })
+        } catch (error) {
+          if (!res.headersSent) {
+            writeJson(res, 400, { error: error instanceof Error ? error.message : String(error) })
+          } else {
+            // Mid-stream failure after headers: destroy so the browser does
+            // not hang waiting for the promised content-length bytes.
+            res.destroy()
+          }
+        } finally {
+          await unlink(tmp).catch(() => undefined)
+        }
+      },
+    },
+  ]
+
+  // ---------------------------------------------- terminal (upgrade)
+  const upgrade: WebUpgradeRoute = {
+    path: SSH_API.terminal,
+    handler: (req, socket, head) => {
+      if (!isLoopbackRequest(req)) {
+        socket.write('HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n')
+        socket.destroy()
+        return
+      }
+      const url = new URL(req.url ?? '/', 'http://localhost')
+      const alias = queryParam(url, 'alias')
+      if (alias === undefined) {
+        socket.write('HTTP/1.1 400 Bad Request\r\nConnection: close\r\n\r\n')
+        socket.destroy()
+        return
+      }
+      const cols = Number.parseInt(queryParam(url, 'cols') ?? '80', 10)
+      const rows = Number.parseInt(queryParam(url, 'rows') ?? '24', 10)
+      terminalWss.handleUpgrade(req, socket, head, (ws) => {
+        let session: ShellSession | undefined
+        let closed = false
+        let paused = false
+        // Resume the shell once the socket's send buffer drains below the
+        // low-water mark (transport backpressure).
+        const resume = (): void => {
+          if (paused && ws.bufferedAmount < BACKPRESSURE_LOW_WATER) {
+            paused = false
+            session?.resume()
+          }
+        }
+        const sendFrame = (frame: TerminalServerFrame): void => {
+          if (closed || ws.readyState !== WebSocket.OPEN) return
+          ws.send(JSON.stringify(frame), resume)
+          if (!paused && ws.bufferedAmount > BACKPRESSURE_HIGH_WATER) {
+            paused = true
+            session?.pause()
+          }
+        }
+        const closeSession = (): void => {
+          const opened = session
+          session = undefined
+          if (opened !== undefined) opened.close()
+        }
+        engine.openShell(alias, {
+          cols: Number.isFinite(cols) ? cols : 80,
+          rows: Number.isFinite(rows) ? rows : 24,
+        }).then((opened) => {
+          if (ws.readyState !== WebSocket.OPEN) {
+            opened.close()
+            return
+          }
+          session = opened
+          sendFrame({ type: 'ready', alias })
+          opened.onData = (data) => sendFrame({ type: 'output', data: data.toString('utf8') })
+          opened.onExit = (code, error) => {
+            sendFrame({ type: 'exit', code, error })
+            closed = true
+            try { ws.close(1000) } catch { /* already closed */ }
+          }
+        }).catch((error) => {
+          sendFrame({ type: 'exit', code: null, error: error instanceof Error ? error.message : String(error) })
+          closed = true
+          try { ws.close(1000) } catch { /* already closed */ }
+        })
+        ws.on('message', (data) => {
+          let frame: TerminalClientFrame
+          try {
+            frame = JSON.parse(String(data)) as TerminalClientFrame
+          } catch {
+            return
+          }
+          if (frame.type === 'input') {
+            session?.send(frame.data)
+          } else if (frame.type === 'resize') {
+            session?.resize(Math.max(2, frame.cols), Math.max(1, frame.rows))
+          }
+        })
+        ws.on('close', () => {
+          closed = true
+          closeSession()
+        })
+        ws.on('error', () => {
+          closed = true
+          closeSession()
+        })
+      })
+    },
+  }
+
+  return { routes, upgrade }
+}