dsh-ssh-workbench 0.0.0-stage → 1.6.4

package/lib/core/known-hosts.js

@@ -0,0 +1,74 @@
+/**
+ * Plugin-local known_hosts with strict-by-default trust.
+ *
+ * ssh2 verifies the host key with `hostHash: 'sha256'`; the verifier receives
+ * the hex digest, so this store keeps `<address> sha256:<hex>` lines. Unknown
+ * hosts are rejected unless the user explicitly trusts the fingerprint.
+ */
+import { knownHostsPath, readTextFile, writePrivateFile } from './paths.js'
+
+function addressOf(server) {
+  return `${server.host}:${server.port}`
+}
+
+function normalizeFingerprint(fingerprint) {
+  const value = String(fingerprint ?? '').trim().toLowerCase()
+  if (!value) return ''
+  return value.startsWith('sha256:') ? value : `sha256:${value}`
+}
+
+function parse(text) {
+  const map = new Map()
+  for (const rawLine of text.split(/\r?\n/)) {
+    const line = rawLine.trim()
+    if (!line || line.startsWith('#')) continue
+    const match = /^(\S+)\s+(sha256:[0-9a-f]+)$/i.exec(line)
+    if (match) map.set(match[1], match[2].toLowerCase())
+  }
+  return map
+}
+
+export function createKnownHosts({ file = knownHostsPath() } = {}) {
+  const load = () => parse(readTextFile(file))
+  const save = (map) => {
+    const lines = [...map.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([address, fp]) => `${address} ${fp}`)
+    writePrivateFile(file, `${lines.join('\n')}${lines.length ? '\n' : ''}`)
+  }
+  return {
+    addressOf,
+    /** `mode: 'strict'` rejects unknown hosts; `'accept-new'` records them (TOFU). */
+    verify(server, fingerprint, mode = 'strict') {
+      const address = addressOf(server)
+      const normalized = normalizeFingerprint(fingerprint)
+      if (!normalized) return false
+      const map = load()
+      const known = map.get(address)
+      if (known) return known === normalized
+      if (mode === 'accept-new') {
+        map.set(address, normalized)
+        save(map)
+        return true
+      }
+      return false
+    },
+    trust(server, fingerprint) {
+      const normalized = normalizeFingerprint(fingerprint)
+      if (!normalized) throw new Error('a fingerprint is required')
+      const map = load()
+      map.set(addressOf(server), normalized)
+      save(map)
+    },
+    revoke(server) {
+      const map = load()
+      const deleted = map.delete(addressOf(server))
+      save(map)
+      return deleted
+    },
+    list() {
+      return [...load().entries()].map(([address, fingerprint]) => ({ address, fingerprint }))
+    },
+    has(server) {
+      return load().has(addressOf(server))
+    },
+  }
+}

package/lib/core/local-file-api.js

@@ -0,0 +1,174 @@
+/**
+ * Local-filesystem implementation of the files-panel API.
+ *
+ * The workbench reuses the very same files component for remote SFTP and the
+ * local workspace. This adapter gives the local side the same method surface
+ * as the SSH runtime (`sftpHome`, `sftpList`, `sftpRead`, chunked open/read/
+ * write sessions, mkdir/remove/rename), so the panel and the file viewer stay
+ * provider-blind. Every path is resolved through the scoped local filesystem
+ * browser.
+ */
+import fsp from 'node:fs/promises'
+import { randomUUID } from 'node:crypto'
+
+export const LOCAL_FILE_REF = '__local__'
+
+const SYMLINK_WRITE_ERROR = 'refusing to write through a symlink'
+
+export function createLocalFileApi(localfs) {
+  const server = { id: LOCAL_FILE_REF, name: LOCAL_FILE_REF, platform: 'local' }
+  const sessions = new Map()
+
+  const sessionFor = (id, kind) => {
+    const session = sessions.get(id)
+    if (!session || session.kind !== kind) throw new Error('local transfer session not found')
+    return session
+  }
+
+  async function lstatOrNull(target) {
+    try {
+      return await fsp.lstat(target)
+    } catch (error) {
+      if (error && (error.code === 'ENOENT' || error.code === 'ENOTDIR')) return null
+      throw error
+    }
+  }
+
+  /**
+   * Open a local path for a transfer session.
+   *
+   * Write sessions resolve the path as a directory entry (parents followed and
+   * bounded by the root, final component not followed) and refuse to write
+   * through a final symlink, so an uploaded file cannot escape via a link.
+   * Read sessions keep follow semantics (a symlink inside the root is readable;
+   * one leaving the root is rejected by `localfs.resolve`).
+   */
+  async function openLocal(target, flags, { noFollowFinal = false } = {}) {
+    const resolved = noFollowFinal
+      ? await localfs.resolveEntry(target)
+      : await localfs.resolve(target)
+    if (noFollowFinal) {
+      const info = await lstatOrNull(resolved)
+      if (info && info.isSymbolicLink()) throw new Error(SYMLINK_WRITE_ERROR)
+    }
+    const handle = await fsp.open(resolved, flags)
+    return { resolved, handle }
+  }
+
+  /** Canonical local workspace root, mirroring the remote login home. */
+  async function sftpHome(_server) {
+    return await localfs.rootReal()
+  }
+
+  async function sftpList(_server, remotePath) {
+    const target = typeof remotePath === 'string' && remotePath.trim() ? remotePath : await localfs.rootReal()
+    const result = await localfs.list(target)
+    return result.entries
+  }
+
+  async function sftpRead(_server, remotePath, options = {}) {
+    const result = await localfs.read(remotePath, options.maxBytes)
+    const buffer = Buffer.from(result.base64, 'base64')
+    const binary = buffer.includes(0)
+    const formatted = {
+      path: result.path,
+      size: result.size,
+      bytesRead: buffer.length,
+      truncated: result.truncated,
+      binary,
+      content: binary ? undefined : buffer.toString('utf8'),
+    }
+    if (options.base64 === true) formatted.base64 = result.base64
+    return formatted
+  }
+
+  async function sftpOpenWrite(_server, remotePath, truncate = true) {
+    let opened
+    try {
+      opened = await openLocal(remotePath, truncate === false ? 'r+' : 'w', { noFollowFinal: true })
+    } catch (error) {
+      if (truncate === false && error && error.code === 'ENOENT') {
+        opened = await openLocal(remotePath, 'w', { noFollowFinal: true })
+      } else throw error
+    }
+    const id = `locw_${randomUUID()}`
+    sessions.set(id, { kind: 'write', path: opened.resolved, handle: opened.handle })
+    return { session: id, path: opened.resolved }
+  }
+
+  async function sftpWriteChunk(sessionId, offset, buffer) {
+    const session = sessionFor(sessionId, 'write')
+    await session.handle.write(buffer, 0, buffer.length, offset)
+    return { session: sessionId, bytes: buffer.length, offset }
+  }
+
+  async function sftpOpenRead(_server, remotePath) {
+    const opened = await openLocal(remotePath, 'r')
+    const info = await opened.handle.stat()
+    if (!info.isFile()) {
+      await opened.handle.close()
+      throw new Error('not a file')
+    }
+    const id = `locr_${randomUUID()}`
+    sessions.set(id, { kind: 'read', path: opened.resolved, handle: opened.handle, size: info.size })
+    return { session: id, path: opened.resolved, size: info.size }
+  }
+
+  async function sftpReadChunk(sessionId, offset, length) {
+    const session = sessionFor(sessionId, 'read')
+    const buffer = Buffer.alloc(length)
+    const { bytesRead } = await session.handle.read(buffer, 0, length, offset)
+    return { session: sessionId, bytesRead, base64: buffer.subarray(0, bytesRead).toString('base64') }
+  }
+
+  async function sftpCloseTransfer(sessionId) {
+    const session = sessions.get(sessionId)
+    // The server ref lets routes invalidate the local directory cache and log
+    // local activity under the right resource instead of "unknown" (B5/B8).
+    if (!session) return { session: sessionId, path: null, server: LOCAL_FILE_REF }
+    sessions.delete(sessionId)
+    let bytes
+    try {
+      if (session.kind === 'write') bytes = (await session.handle.stat()).size
+    } catch {
+      // A failed stat still closes the descriptor below.
+    }
+    await session.handle.close()
+    return { session: sessionId, path: session.path, bytes, server: LOCAL_FILE_REF }
+  }
+
+  async function sftpMkdir(_server, remotePath) {
+    return await localfs.mkdir(remotePath)
+  }
+
+  async function sftpRemove(_server, remotePath) {
+    return await localfs.remove(remotePath)
+  }
+
+  async function sftpRename(_server, fromPath, toPath) {
+    return await localfs.rename(fromPath, toPath)
+  }
+
+  async function dispose() {
+    for (const session of [...sessions.values()]) {
+      try { await session.handle.close() } catch { /* already closed */ }
+    }
+    sessions.clear()
+  }
+
+  return {
+    server,
+    sftpHome,
+    sftpList,
+    sftpRead,
+    sftpOpenWrite,
+    sftpWriteChunk,
+    sftpOpenRead,
+    sftpReadChunk,
+    sftpCloseTransfer,
+    sftpMkdir,
+    sftpRemove,
+    sftpRename,
+    dispose,
+  }
+}

package/lib/core/localfs.js

@@ -0,0 +1,381 @@
+/**
+ * Bounded local-filesystem browser for the workbench's local side.
+ *
+ * The workbench is a user-driven surface, not a model tool, but it still must
+ * not become a privilege escalation around the session sandbox. Every path is
+ * resolved inside one root (the Host's default working directory) and escapes
+ * (`..`, absolute paths outside the root, symlinks leaving it) are rejected
+ * before any filesystem call.
+ *
+ * Two different notions of "resolve" are needed:
+ *  - read/list follow the final component (`resolve`), because following a
+ *    symlink inside the root is legitimate for reading;
+ *  - remove/rename operate on the directory entry itself (`resolveEntry`), so
+ *    they never follow a final symlink (deleting or renaming the link must not
+ *    touch its target).
+ * Writes/mkdirs are the strictest case: an existing final symlink is refused
+ * outright and every existing path component must canonicalize inside the real
+ * root, including when the final component does not exist yet.
+ */
+import fsp from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+
+const MAX_READ_BYTES = 5 * 1024 * 1024
+const MAX_WRITE_BYTES = 20 * 1024 * 1024
+
+const OUTSIDE_ERROR = 'path is outside the local workspace root'
+const SYMLINK_WRITE_ERROR = 'refusing to write through a symlink'
+const ROOT_REMOVE_ERROR = 'refusing to remove the local workspace root'
+const ROOT_RENAME_ERROR = 'refusing to rename the local workspace root'
+
+const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']
+
+function isMissing(error) {
+  return Boolean(
+    error &&
+      typeof error === 'object' &&
+      (error.code === 'ENOENT' || error.code === 'ENOTDIR'),
+  )
+}
+
+/** Whether `target` is `root` itself or a path below it (handles root === '/'). */
+function withinRoot(target, root) {
+  if (target === root) return true
+  const prefix = root.endsWith(path.sep) ? root : root + path.sep
+  return target.startsWith(prefix)
+}
+
+/** Whether a canonical `real` path is the root itself or lives under it. */
+function isUnder(real, realRoot) {
+  // A root that does not exist yet has no canonical form; lexical containment
+  // (checked by the caller) is then the strongest guarantee available.
+  if (realRoot == null) return true
+  return withinRoot(real, realRoot)
+}
+
+function assertInside(real, realRoot) {
+  if (!isUnder(real, realRoot)) throw new Error(OUTSIDE_ERROR)
+}
+
+/** Render the permission bits of a lstat mode as `rwxrwxrwx`. */
+function permissionsOf(mode) {
+  const bits = []
+  for (let shift = 8; shift >= 0; shift -= 1) {
+    const bit = 1 << shift
+    bits.push(mode & bit ? 'rwx'[(8 - shift) % 3] : '-')
+  }
+  return bits.join('')
+}
+
+/**
+ * Synthesize an `ls -l`-style longname. The remote SFTP side gets this string
+ * from the server's readdir longname field; locally we build an equivalent so
+ * the shared files panel receives the same entry shape.
+ */
+function longnameOf(info, name) {
+  const type = info.isSymbolicLink() ? 'l' : info.isDirectory() ? 'd' : '-'
+  const when = new Date(info.mtimeMs)
+  const day = String(when.getDate()).padStart(2, ' ')
+  const hour = String(when.getHours()).padStart(2, '0')
+  const minute = String(when.getMinutes()).padStart(2, '0')
+  const stamp = `${MONTHS[when.getMonth()]} ${day} ${hour}:${minute}`
+  return `${type}${permissionsOf(info.mode)} ${info.nlink ?? 1} ${info.uid ?? 0} ${info.gid ?? 0} ${info.size} ${stamp} ${name}`
+}
+
+export function createLocalFs({ getRoot } = {}) {
+  /** Configured (lexical) root; kept synchronous for route/config callers. */
+  function rootPath() {
+    const value = typeof getRoot === 'function' ? getRoot() : undefined
+    return path.resolve(value || os.homedir())
+  }
+
+  /** Canonical root, or `null` when the configured root does not exist yet. */
+  async function rootRealOrNull() {
+    try {
+      return await fsp.realpath(rootPath())
+    } catch (error) {
+      if (isMissing(error)) return null
+      throw error
+    }
+  }
+
+  /** Canonical root (`realpath`); falls back to the lexical root if missing. */
+  async function rootReal() {
+    return (await rootRealOrNull()) ?? rootPath()
+  }
+
+  async function lstatOrNull(target) {
+    try {
+      return await fsp.lstat(target)
+    } catch (error) {
+      if (isMissing(error)) return null
+      throw error
+    }
+  }
+
+  /**
+   * Map a caller path onto an absolute lexical candidate.
+   *
+   * Both the configured root and its canonical realpath are accepted, so the
+   * canonical `entry.path` values returned by `list()` remain usable as
+   * navigation inputs when the configured root itself contains symlinked
+   * components (macOS `/tmp` -> `/private/tmp`, linked homes, etc.).
+   */
+  function candidateFor(input, realRoot) {
+    const lexicalRoot = rootPath()
+    const canonicalRoot = realRoot ?? lexicalRoot
+    const raw = typeof input === 'string' && input.trim() ? input.trim() : ''
+    const candidate =
+      raw === '' ? lexicalRoot : path.isAbsolute(raw) ? path.resolve(raw) : path.resolve(lexicalRoot, raw)
+    const insideLexical = withinRoot(candidate, lexicalRoot)
+    const insideReal = withinRoot(candidate, canonicalRoot)
+    if (!insideLexical && !insideReal) throw new Error(OUTSIDE_ERROR)
+    return candidate
+  }
+
+  /**
+   * Canonicalize a path that may not exist yet by walking up to the deepest
+   * existing ancestor. That ancestor must canonicalize inside the real root;
+   * the missing remainder cannot contain symlinks and is appended lexically.
+   *
+   * A dangling symlink anywhere in the chain is never silently followed:
+   * `dangling: 'propagate'` surfaces ENOENT (read/list semantics) and
+   * `dangling: 'reject'` refuses the operation (write/mkdir semantics).
+   */
+  async function canonicalizeMissing(candidate, realRoot, dangling) {
+    let cursor = candidate
+    const missing = []
+    for (;;) {
+      const info = await lstatOrNull(cursor)
+      if (info) {
+        if (info.isSymbolicLink()) {
+          let real
+          try {
+            real = await fsp.realpath(cursor)
+          } catch (error) {
+            if (isMissing(error)) {
+              if (dangling === 'reject') throw new Error(SYMLINK_WRITE_ERROR)
+              throw error
+            }
+            throw error
+          }
+          assertInside(real, realRoot)
+          return path.join(real, ...missing)
+        }
+        const real = await fsp.realpath(cursor)
+        assertInside(real, realRoot)
+        return path.join(real, ...missing)
+      }
+      const parent = path.dirname(cursor)
+      if (parent === cursor) throw new Error(OUTSIDE_ERROR)
+      missing.unshift(path.basename(cursor))
+      cursor = parent
+    }
+  }
+
+  /**
+   * Resolve a caller path for read/list: symlinks are followed and the result
+   * is the canonical real path. Non-existent final components are allowed
+   * through (the caller's fs call reports ENOENT) but their existing parent
+   * chain must still canonicalize inside the root.
+   */
+  async function resolveInside(input) {
+    const realRoot = await rootRealOrNull()
+    const candidate = candidateFor(input, realRoot)
+    try {
+      const real = await fsp.realpath(candidate)
+      assertInside(real, realRoot)
+      return real
+    } catch (error) {
+      if (isMissing(error)) return await canonicalizeMissing(candidate, realRoot, 'propagate')
+      throw error
+    }
+  }
+
+  /**
+   * Resolve a caller path as a *directory entry*: parents are followed and
+   * canonicalized inside the root, but the final component is not followed.
+   * Used by remove/rename so a symlink is operated on as a link, never as its
+   * target.
+   */
+  async function resolveEntry(input) {
+    const realRoot = await rootRealOrNull()
+    const lexicalRoot = rootPath()
+    const candidate = candidateFor(input, realRoot)
+    // The root itself has no directory-entry form; hand it back so remove/
+    // rename can reject it explicitly (B14) instead of recursing into it.
+    if (candidate === lexicalRoot || (realRoot != null && candidate === realRoot)) return candidate
+    const realParent = await fsp.realpath(path.dirname(candidate))
+    assertInside(realParent, realRoot)
+    return path.join(realParent, path.basename(candidate))
+  }
+
+  /**
+   * Resolve a write/mkdir target.
+   *
+   * - an existing final symlink is refused (`refusing to write through a
+   *   symlink`), even when it points inside the root;
+   * - parents are canonicalized through symlinks and must stay inside root;
+   * - non-existent targets validate their deepest existing ancestor, so a
+   *   symlinked parent plus a brand-new child name cannot escape (S1).
+   */
+  async function resolveCreateTarget(input) {
+    const realRoot = await rootRealOrNull()
+    const candidate = candidateFor(input, realRoot)
+    const direct = await lstatOrNull(candidate)
+    if (direct) {
+      if (direct.isSymbolicLink()) throw new Error(SYMLINK_WRITE_ERROR)
+      const real = await fsp.realpath(candidate)
+      assertInside(real, realRoot)
+      return real
+    }
+    return canonicalizeMissing(candidate, realRoot, 'reject')
+  }
+
+  async function list(input) {
+    const directory = await resolveInside(input)
+    const realRoot = await rootReal()
+    const stat = await fsp.stat(directory)
+    if (!stat.isDirectory()) throw new Error('not a directory')
+    const rows = await fsp.readdir(directory, { withFileTypes: true })
+    const entries = []
+    for (const row of rows) {
+      const full = path.join(directory, row.name)
+      // A file removed mid-listing (or an entry we cannot stat) still lists by
+      // name, as before; type detection prefers lstat because following a
+      // symlink mis-typed link-to-directory entries and enabled S2 data loss.
+      let info = null
+      try {
+        info = await fsp.lstat(full)
+      } catch {
+        info = null
+      }
+      const type = info
+        ? info.isSymbolicLink()
+          ? 'link'
+          : info.isDirectory()
+            ? 'dir'
+            : 'file'
+        : row.isSymbolicLink()
+          ? 'link'
+          : row.isDirectory()
+            ? 'dir'
+            : 'file'
+      entries.push({
+        name: row.name,
+        path: full,
+        type,
+        size: info ? (info.isDirectory() ? 0 : info.size) : 0,
+        mtime: info ? info.mtimeMs : null,
+        atime: info ? info.atimeMs : null,
+        mode: info ? info.mode : null,
+        uid: info ? info.uid : null,
+        gid: info ? info.gid : null,
+        longname: info ? longnameOf(info, row.name) : row.name,
+      })
+    }
+    entries.sort((left, right) => {
+      if (left.type !== right.type) {
+        if (left.type === 'dir') return -1
+        if (right.type === 'dir') return 1
+      }
+      return left.name.localeCompare(right.name)
+    })
+    return {
+      root: realRoot,
+      path: directory,
+      entries,
+      parent: directory === realRoot ? null : path.dirname(directory),
+    }
+  }
+
+  async function read(input, maxBytes = MAX_READ_BYTES) {
+    const file = await resolveInside(input)
+    const stat = await fsp.stat(file)
+    if (!stat.isFile()) throw new Error('not a file')
+    const size = stat.size
+    const limit = Math.min(Math.max(Number(maxBytes) || MAX_READ_BYTES, 1), MAX_READ_BYTES)
+    const handle = await fsp.open(file, 'r')
+    try {
+      const length = Math.min(size, limit)
+      const buffer = Buffer.alloc(length)
+      const { bytesRead } = await handle.read(buffer, 0, length, 0)
+      return {
+        path: file,
+        size,
+        mtime: stat.mtimeMs,
+        truncated: size > bytesRead,
+        base64: buffer.subarray(0, bytesRead).toString('base64'),
+      }
+    } finally {
+      await handle.close()
+    }
+  }
+
+  async function write(input, contentBase64) {
+    if (typeof contentBase64 !== 'string') throw new Error('contentBase64 is required')
+    const buffer = Buffer.from(contentBase64, 'base64')
+    if (buffer.length > MAX_WRITE_BYTES) throw new Error(`file exceeds ${MAX_WRITE_BYTES} bytes`)
+    const file = await resolveCreateTarget(input)
+    await fsp.mkdir(path.dirname(file), { recursive: true })
+    await fsp.writeFile(file, buffer)
+    return { path: file, size: buffer.length }
+  }
+
+  async function mkdir(input) {
+    const directory = await resolveCreateTarget(input)
+    await fsp.mkdir(directory, { recursive: true })
+    return { path: directory }
+  }
+
+  async function remove(input) {
+    const target = await resolveEntry(input)
+    const lexicalRoot = rootPath()
+    const realRoot = await rootReal()
+    // Empty input resolves to the root; deleting it must never be possible.
+    if (target === lexicalRoot || target === realRoot) throw new Error(ROOT_REMOVE_ERROR)
+    const info = await lstatOrNull(target)
+    if (!info) return { path: target, removed: false }
+    if (info.isSymbolicLink()) {
+      // Unlink the link itself; never follow it (a link can point outside the
+      // root and still be safely removable without touching its target, B7).
+      await fsp.unlink(target)
+    } else if (info.isDirectory()) {
+      await fsp.rm(target, { recursive: true, force: true })
+    } else {
+      await fsp.unlink(target)
+    }
+    return { path: target, removed: true }
+  }
+
+  async function rename(from, to) {
+    // Operate on directory entries: a symlink is moved as a link, not as its
+    // target (B4), and the destination's parents are canonicalized inside root.
+    const source = await resolveEntry(from)
+    const destination = await resolveEntry(to)
+    const lexicalRoot = rootPath()
+    const realRoot = await rootReal()
+    for (const target of [source, destination]) {
+      if (target === lexicalRoot || target === realRoot) throw new Error(ROOT_RENAME_ERROR)
+    }
+    // Match the remote SFTP semantics: rename must not silently overwrite.
+    const existing = await lstatOrNull(destination)
+    if (existing) throw new Error(`destination already exists: ${destination}`)
+    await fsp.rename(source, destination)
+    return { path: destination }
+  }
+
+  return {
+    root: rootPath,
+    rootReal,
+    resolve: resolveInside,
+    resolveEntry,
+    list,
+    read,
+    write,
+    mkdir,
+    remove,
+    rename,
+  }
+}