dsh-ssh-tunnel 1.0.0 → 1.0.2

package/lib/shared/args.js

@@ -0,0 +1,23 @@
+/**
+ * Strict argument coercion for API/tool entry points.
+ *
+ * `String(x || fallback)` turns a missing argument into the literal string
+ * "undefined" (or the fallback), which then flows into path operations and
+ * silently creates files or remote paths named "undefined". These helpers
+ * throw instead, so the caller sees which argument is missing.
+ */
+
+export function requireString(value, label) {
+  if (value == null) throw new Error(label + ' required')
+  const s = String(value).trim()
+  if (!s) throw new Error(label + ' required')
+  return s
+}
+
+/** Like requireString, but an empty value resolves to the fallback. */
+export function stringOrDefault(value, fallback, label) {
+  if (value == null) return requireString(fallback, label)
+  const s = String(value).trim()
+  if (!s) return requireString(fallback, label)
+  return s
+}

package/lib/shared/host-key.js

@@ -1,32 +1,32 @@
-import { createHash } from 'node:crypto'
-
-/** True when stored value is a sha256 hex digest (not legacy raw-key String(Buffer)). */
-export function isUsableHostFingerprint(fp) {
-  return typeof fp === 'string' && /^[0-9a-f]{64}$/.test(fp.trim().toLowerCase())
-}
-
-/**
- * Normalize ssh2 hostVerifier input to a stable sha256 hex fingerprint.
- * - With connect option hostHash:'sha256', key is already a hex string.
- * - Raw Buffer (no hostHash) is hashed here as a safe fallback.
- */
-export function fingerprintFromHostKey(key) {
-  if (key == null) return ''
-  if (typeof key === 'string') {
-    const s = key.trim().toLowerCase()
-    if (/^[0-9a-f]{64}$/.test(s)) return s
-    if (/^[0-9a-f]+$/.test(s) && s.length >= 32) return createHash('sha256').update(Buffer.from(s, 'hex')).digest('hex')
-    return createHash('sha256').update(Buffer.from(key, 'utf8')).digest('hex')
-  }
-  if (typeof Buffer !== 'undefined' && Buffer.isBuffer(key)) {
-    return createHash('sha256').update(key).digest('hex')
-  }
-  return createHash('sha256').update(Buffer.from(String(key))).digest('hex')
-}
-
-/** Human-facing label for trust prompts / logs. */
-export function formatHostFingerprint(fp, algo = 'SHA256') {
-  if (!fp) return ''
-  const hex = String(fp).trim().toLowerCase()
-  return `${algo}:${hex}`
-}
+import { createHash } from 'node:crypto'
+
+/** True when stored value is a sha256 hex digest (not legacy raw-key String(Buffer)). */
+export function isUsableHostFingerprint(fp) {
+  return typeof fp === 'string' && /^[0-9a-f]{64}$/.test(fp.trim().toLowerCase())
+}
+
+/**
+ * Normalize ssh2 hostVerifier input to a stable sha256 hex fingerprint.
+ * - With connect option hostHash:'sha256', key is already a hex string.
+ * - Raw Buffer (no hostHash) is hashed here as a safe fallback.
+ */
+export function fingerprintFromHostKey(key) {
+  if (key == null) return ''
+  if (typeof key === 'string') {
+    const s = key.trim().toLowerCase()
+    if (/^[0-9a-f]{64}$/.test(s)) return s
+    if (/^[0-9a-f]+$/.test(s) && s.length >= 32) return createHash('sha256').update(Buffer.from(s, 'hex')).digest('hex')
+    return createHash('sha256').update(Buffer.from(key, 'utf8')).digest('hex')
+  }
+  if (typeof Buffer !== 'undefined' && Buffer.isBuffer(key)) {
+    return createHash('sha256').update(key).digest('hex')
+  }
+  return createHash('sha256').update(Buffer.from(String(key))).digest('hex')
+}
+
+/** Human-facing label for trust prompts / logs. */
+export function formatHostFingerprint(fp, algo = 'SHA256') {
+  if (!fp) return ''
+  const hex = String(fp).trim().toLowerCase()
+  return `${algo}:${hex}`
+}

package/lib/shared/host-summary.js

@@ -1,75 +1,75 @@
-/** Credential presence without exposing secret material. */
-export function hostCredentialConfigured(host, secrets) {
-  if (!host) return false
-  if (host.authType === 'keyboardInteractive') return false
-  const sec = (secrets && secrets.byHostId && secrets.byHostId[host.id]) || {}
-  if (host.authType === 'privateKey') {
-    return !!(host.privateKeyPath || sec.privateKeyPem)
-  }
-  return !!sec.password
-}
-
-/** UI-safe host record (never includes password/PEM). */
-export function publicHost(host, secrets) {
-  const configured = hostCredentialConfigured(host, secrets)
-  const sec = (secrets && secrets.byHostId && secrets.byHostId[host.id]) || {}
-  return {
-    id: host.id,
-    name: host.name,
-    host: host.host,
-    port: host.port || 22,
-    username: host.username,
-    authType: host.authType || 'privateKey',
-    privateKeyPath: host.privateKeyPath || '',
-    source: host.source || 'manual',
-    updatedAt: host.updatedAt || 0,
-    credentialConfigured: configured,
-    credentialStatus:
-      host.authType === 'keyboardInteractive'
-        ? 'unsupported'
-        : configured
-          ? 'saved'
-          : 'missing',
-    passwordConfigured: !!sec.password,
-    privateKeyConfigured: !!(host.privateKeyPath || sec.privateKeyPem),
-  }
-}
-
-/** Model-facing summary: no paths to key files beyond endpoint metadata. */
-export function modelHostSummary(host, secrets) {
-  const p = publicHost(host, secrets)
-  return {
-    host_id: p.id,
-    name: p.name,
-    endpoint: `${p.username}@${p.host}:${p.port}`,
-    username: p.username,
-    host: p.host,
-    port: p.port,
-    authType: p.authType,
-    credentialConfigured: p.credentialConfigured,
-    credentialStatus: p.credentialStatus,
-  }
-}
-
-/** Fail if object looks like it still carries raw secrets (for tests / asserts). */
-export function assertNoSecretFields(obj, label = 'object') {
-  const banned = ['password', 'privateKeyPem', 'privateKey', 'passphrase', 'secret']
-  const stack = [{ value: obj, path: label }]
-  while (stack.length) {
-    const { value, path } = stack.pop()
-    if (!value || typeof value !== 'object') continue
-    if (Array.isArray(value)) {
-      value.forEach((v, i) => stack.push({ value: v, path: `${path}[${i}]` }))
-      continue
-    }
-    for (const [k, v] of Object.entries(value)) {
-      const key = k.toLowerCase()
-      if (banned.includes(key) && v) {
-        throw new Error(`${path}.${k} must not carry secret material`)
-      }
-      // allow *Configured boolean flags
-      if (typeof v === 'object' && v) stack.push({ value: v, path: `${path}.${k}` })
-    }
-  }
-  return true
-}
+/** Credential presence without exposing secret material. */
+export function hostCredentialConfigured(host, secrets) {
+  if (!host) return false
+  if (host.authType === 'keyboardInteractive') return false
+  const sec = (secrets && secrets.byHostId && secrets.byHostId[host.id]) || {}
+  if (host.authType === 'privateKey') {
+    return !!(host.privateKeyPath || sec.privateKeyPem)
+  }
+  return !!sec.password
+}
+
+/** UI-safe host record (never includes password/PEM). */
+export function publicHost(host, secrets) {
+  const configured = hostCredentialConfigured(host, secrets)
+  const sec = (secrets && secrets.byHostId && secrets.byHostId[host.id]) || {}
+  return {
+    id: host.id,
+    name: host.name,
+    host: host.host,
+    port: host.port || 22,
+    username: host.username,
+    authType: host.authType || 'privateKey',
+    privateKeyPath: host.privateKeyPath || '',
+    source: host.source || 'manual',
+    updatedAt: host.updatedAt || 0,
+    credentialConfigured: configured,
+    credentialStatus:
+      host.authType === 'keyboardInteractive'
+        ? 'unsupported'
+        : configured
+          ? 'saved'
+          : 'missing',
+    passwordConfigured: !!sec.password,
+    privateKeyConfigured: !!(host.privateKeyPath || sec.privateKeyPem),
+  }
+}
+
+/** Model-facing summary: no paths to key files beyond endpoint metadata. */
+export function modelHostSummary(host, secrets) {
+  const p = publicHost(host, secrets)
+  return {
+    host_id: p.id,
+    name: p.name,
+    endpoint: `${p.username}@${p.host}:${p.port}`,
+    username: p.username,
+    host: p.host,
+    port: p.port,
+    authType: p.authType,
+    credentialConfigured: p.credentialConfigured,
+    credentialStatus: p.credentialStatus,
+  }
+}
+
+/** Fail if object looks like it still carries raw secrets (for tests / asserts). */
+export function assertNoSecretFields(obj, label = 'object') {
+  const banned = ['password', 'privateKeyPem', 'privateKey', 'passphrase', 'secret']
+  const stack = [{ value: obj, path: label }]
+  while (stack.length) {
+    const { value, path } = stack.pop()
+    if (!value || typeof value !== 'object') continue
+    if (Array.isArray(value)) {
+      value.forEach((v, i) => stack.push({ value: v, path: `${path}[${i}]` }))
+      continue
+    }
+    for (const [k, v] of Object.entries(value)) {
+      const key = k.toLowerCase()
+      if (banned.includes(key) && v) {
+        throw new Error(`${path}.${k} must not carry secret material`)
+      }
+      // allow *Configured boolean flags
+      if (typeof v === 'object' && v) stack.push({ value: v, path: `${path}.${k}` })
+    }
+  }
+  return true
+}

package/lib/shared/http-trust.js

@@ -1,59 +1,59 @@
-/**
- * Loopback / Origin checks for the local HTTP API.
- * 0.0.0.0 is NOT loopback (it is a bind-all address).
- */
-
-export function isLoopbackHostname(hostname) {
-  const h = String(hostname || '').replace(/^\[|\]$/g, '').toLowerCase()
-  return h === 'localhost' || h === '127.0.0.1' || h === '::1'
-}
-
-function originHostPort(originHeader) {
-  try {
-    const u = new URL(String(originHeader))
-    const host = u.hostname.replace(/^\[|\]$/g, '').toLowerCase()
-    const port = u.port || (u.protocol === 'https:' ? '443' : u.protocol === 'http:' ? '80' : '')
-    return { host, port, hostHeaderLike: port ? `${host}:${port}` : host }
-  } catch {
-    return null
-  }
-}
-
-/**
- * @param {object} req Node HTTP request
- * @param {string[]} trustedHosts
- */
-export function isTrustedRequest(req, trustedHosts) {
-  try {
-    const hostHeader = req.headers?.host || req.headers?.Host
-    if (!hostHeader) return false
-    const url = new URL('http://' + hostHeader)
-    const reqHost = url.hostname.replace(/^\[|\]$/g, '').toLowerCase()
-    const list = Array.isArray(trustedHosts) ? trustedHosts : []
-    const hostOk =
-      isLoopbackHostname(reqHost) ||
-      list.some((entry) => {
-        const e = String(entry)
-        return e === hostHeader || e === url.hostname || e === url.host
-      })
-    if (!hostOk) return false
-
-    const origin = req.headers?.origin || req.headers?.Origin
-    if (!origin) return true
-    const parsed = originHostPort(origin)
-    if (!parsed) return false
-    if (isLoopbackHostname(parsed.host) && isLoopbackHostname(reqHost)) {
-      const reqPort = url.port || '80'
-      if (parsed.port && parsed.port !== reqPort) return false
-      return true
-    }
-    return list.some((entry) => {
-      const e = String(entry)
-      return e === parsed.hostHeaderLike || e === parsed.host || e === origin
-    })
-  } catch {
-    return false
-  }
-}
-
-export const MAX_JSON_BODY_BYTES = 2 * 1024 * 1024
+/**
+ * Loopback / Origin checks for the local HTTP API.
+ * 0.0.0.0 is NOT loopback (it is a bind-all address).
+ */
+
+export function isLoopbackHostname(hostname) {
+  const h = String(hostname || '').replace(/^\[|\]$/g, '').toLowerCase()
+  return h === 'localhost' || h === '127.0.0.1' || h === '::1'
+}
+
+function originHostPort(originHeader) {
+  try {
+    const u = new URL(String(originHeader))
+    const host = u.hostname.replace(/^\[|\]$/g, '').toLowerCase()
+    const port = u.port || (u.protocol === 'https:' ? '443' : u.protocol === 'http:' ? '80' : '')
+    return { host, port, hostHeaderLike: port ? `${host}:${port}` : host }
+  } catch {
+    return null
+  }
+}
+
+/**
+ * @param {object} req Node HTTP request
+ * @param {string[]} trustedHosts
+ */
+export function isTrustedRequest(req, trustedHosts) {
+  try {
+    const hostHeader = req.headers?.host || req.headers?.Host
+    if (!hostHeader) return false
+    const url = new URL('http://' + hostHeader)
+    const reqHost = url.hostname.replace(/^\[|\]$/g, '').toLowerCase()
+    const list = Array.isArray(trustedHosts) ? trustedHosts : []
+    const hostOk =
+      isLoopbackHostname(reqHost) ||
+      list.some((entry) => {
+        const e = String(entry)
+        return e === hostHeader || e === url.hostname || e === url.host
+      })
+    if (!hostOk) return false
+
+    const origin = req.headers?.origin || req.headers?.Origin
+    if (!origin) return true
+    const parsed = originHostPort(origin)
+    if (!parsed) return false
+    if (isLoopbackHostname(parsed.host) && isLoopbackHostname(reqHost)) {
+      const reqPort = url.port || '80'
+      if (parsed.port && parsed.port !== reqPort) return false
+      return true
+    }
+    return list.some((entry) => {
+      const e = String(entry)
+      return e === parsed.hostHeaderLike || e === parsed.host || e === origin
+    })
+  } catch {
+    return false
+  }
+}
+
+export const MAX_JSON_BODY_BYTES = 2 * 1024 * 1024

package/lib/shared/path.js

@@ -1,8 +1,6 @@
 import { lstatSync, realpathSync } from 'node:fs'
 import { dirname, isAbsolute, join, normalize, resolve as pathResolve } from 'node:path'
 
-export const WORKSPACE_ROOT = '/workspace'
-
 /**
  * Local roots the path guard accepts, most specific first.
  *
@@ -11,8 +9,11 @@ export const WORKSPACE_ROOT = '/workspace'
  * `/workspace` at all, and a fixed root rejects every real local path — which
  * breaks SFTP upload/download and the sidebar file browser. Relative local
  * paths resolve against the first root, so an explicit project root wins over
- * the `DSH_SSH_TUNNEL_WORKSPACE_ROOT` operator override and over the
- * `/workspace` fallback.
+ * the `DSH_SSH_TUNNEL_WORKSPACE_ROOT` operator override.
+ *
+ * There is deliberately no implicit fallback root: guessing a root (e.g. the
+ * host process cwd plus `/workspace`) silently widens the trust boundary.
+ * Callers that cannot name a project workspace must fail loudly instead.
  *
  * Read at call time so hosts and tests can set them after module load.
  */
@@ -21,7 +22,6 @@ export function workspaceRoots(explicitRoot = '') {
   if (explicitRoot && String(explicitRoot).trim()) raw.push(String(explicitRoot).trim())
   const env = process.env.DSH_SSH_TUNNEL_WORKSPACE_ROOT
   if (env && String(env).trim()) raw.push(String(env).trim())
-  if (!raw.length) raw.push(WORKSPACE_ROOT)
   const roots = []
   for (const r of raw) {
     const key = normalizeProjectKey(r)
@@ -90,11 +90,11 @@ function realExisting(abs) {
   let probe = abs
   while (true) {
     try {
-      return realpathSync(probe)
+      return { path: realpathSync(probe), probe }
     } catch (e) {
       if (e && e.code === 'ENOENT') {
         const parent = dirname(probe)
-        if (!parent || parent === probe) return ''
+        if (!parent || parent === probe) return null
         probe = parent
         continue
       }
@@ -118,6 +118,11 @@ export function constrainToWorkspace(inputPath, { forUnlink = false, root = '' }
     throw new Error('local path required')
   }
   const roots = workspaceRoots(root)
+  if (!roots.length) {
+    throw new Error(
+      'no local workspace root configured (open a project workspace or set DSH_SSH_TUNNEL_WORKSPACE_ROOT)',
+    )
+  }
   let abs = String(inputPath)
   if (!isAbsolute(abs)) abs = join(roots[0], abs)
   abs = pathResolve(abs)
@@ -134,23 +139,17 @@ export function constrainToWorkspace(inputPath, { forUnlink = false, root = '' }
       if (!(e && e.code === 'ENOENT')) throw e
     }
   }
-  const real = realExisting(abs)
-  if (real && !isPathInsideRoots(real, roots)) {
-    throw new Error('local path escapes ' + roots.join(' or ') + ' via symlink')
+  const found = realExisting(abs)
+  if (found && found.path && !isPathInsideRoots(found.path, roots)) {
+    // A link was traversed only if the nearest existing ancestor resolves to a
+    // path other than its own lexical form; a missing leaf must not be
+    // reported as a symlink escape.
+    if (comparablePath(found.path) !== comparablePath(found.probe)) {
+      throw new Error('local path escapes ' + roots.join(' or ') + ' via symlink')
+    }
+    throw new Error('local path must be under ' + roots.join(' or '))
   }
   return abs
 }
 
-export function joinUnderRoot(root, relOrAbs) {
-  const roots = workspaceRoots()
-  const r = normalizeProjectKey(root) || roots[0]
-  let abs = String(relOrAbs || r)
-  if (!isAbsolute(abs)) abs = join(r, abs)
-  abs = pathResolve(abs)
-  if (!isPathInsideRoots(abs, [...roots, r])) {
-    throw new Error('path outside allowed roots')
-  }
-  return constrainToWorkspace(abs)
-}
-
 export { isAbsolute, join, normalize, pathResolve }

package/lib/shared/persist.js

@@ -1,41 +1,41 @@
-import { chmodSync, existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
-import { dirname, join } from 'node:path'
-
-/**
- * Missing file → fallback. Corrupt JSON → throw (never treat as empty store).
- */
-export function readJsonFile(path, fallback) {
-  if (!existsSync(path)) return fallback
-  let raw
-  try {
-    raw = readFileSync(path, 'utf8')
-  } catch (e) {
-    throw new Error('cannot read ' + path + ': ' + (e && e.message ? e.message : e))
-  }
-  try {
-    return JSON.parse(raw)
-  } catch {
-    throw new Error('corrupt json: ' + path)
-  }
-}
-
-export function writeJsonAtomic(path, data, mode = 0o600) {
-  const tmp = path + '.tmp'
-  writeFileSync(tmp, JSON.stringify(data, null, 2) + '\n', { mode })
-  try { chmodSync(tmp, mode) } catch {}
-  renameSync(tmp, path)
-  try { chmodSync(path, mode) } catch {}
-}
-
-export function migrateMarkerPath(dataDir) {
-  return join(dataDir, '.migrated-draft')
-}
-
-export function hostEndpointKey(host, port, username) {
-  return `${String(username || '').trim()}@${String(host || '').trim()}:${Number(port) || 22}`
-}
-
-export function findExistingHostByEndpoint(hosts, host, port, username) {
-  const key = hostEndpointKey(host, port, username)
-  return (hosts || []).find((h) => hostEndpointKey(h.host, h.port, h.username) === key)
-}
+import { chmodSync, existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+/**
+ * Missing file → fallback. Corrupt JSON → throw (never treat as empty store).
+ */
+export function readJsonFile(path, fallback) {
+  if (!existsSync(path)) return fallback
+  let raw
+  try {
+    raw = readFileSync(path, 'utf8')
+  } catch (e) {
+    throw new Error('cannot read ' + path + ': ' + (e && e.message ? e.message : e))
+  }
+  try {
+    return JSON.parse(raw)
+  } catch {
+    throw new Error('corrupt json: ' + path)
+  }
+}
+
+export function writeJsonAtomic(path, data, mode = 0o600) {
+  const tmp = path + '.tmp'
+  writeFileSync(tmp, JSON.stringify(data, null, 2) + '\n', { mode })
+  try { chmodSync(tmp, mode) } catch {}
+  renameSync(tmp, path)
+  try { chmodSync(path, mode) } catch {}
+}
+
+export function migrateMarkerPath(dataDir) {
+  return join(dataDir, '.migrated-draft')
+}
+
+export function hostEndpointKey(host, port, username) {
+  return `${String(username || '').trim()}@${String(host || '').trim()}:${Number(port) || 22}`
+}
+
+export function findExistingHostByEndpoint(hosts, host, port, username) {
+  const key = hostEndpointKey(host, port, username)
+  return (hosts || []).find((h) => hostEndpointKey(h.host, h.port, h.username) === key)
+}

package/lib/shared/session-auth.js

@@ -1,39 +1,47 @@
-/**
- * Result-delivery authorization gates for SSH session operations (security).
- * Pure helpers kept in shared/ so they are testable without an ssh2 install.
- *
- * Background (v0.4.3): a host grant can be revoked while an SSHManager
- * operation is already in flight. Closing the session stops the transport,
- * but a command can complete and a file can be pulled in the same tick as the
- * revocation. These gates are the *second* boundary: even if the transport
- * work finished, nothing from the revoked host may be delivered to the agent
- * (and no downloaded file may remain on disk).
- *
- * v0.4.4: missing predicate is fail-closed (never a silent no-op). HTTP and
- * write actions re-check the same gate.
- */
-import { unlinkSync } from 'node:fs'
-
-export function assertSessionStillAuthorized(session, isHostAuthorized) {
-  if (!session) throw new Error('SSH session missing')
-  if (typeof isHostAuthorized !== 'function') {
-    throw new Error('SSH authorization predicate required')
-  }
-  if (session.projectPathKey && !isHostAuthorized(session.projectPathKey, session.hostId)) {
-    throw new Error('SSH session host is not authorized for the current project.')
-  }
-}
-
-export function discardRevokedLocalFile(session, localPath, isHostAuthorized) {
-  if (!session) return false
-  if (typeof isHostAuthorized !== 'function') {
-    throw new Error('SSH authorization predicate required')
-  }
-  if (session.projectPathKey && !isHostAuthorized(session.projectPathKey, session.hostId)) {
-    try {
-      unlinkSync(localPath)
-    } catch {}
-    return true
-  }
-  return false
-}
+/**
+ * Result-delivery authorization gates for SSH session operations (security).
+ * Pure helpers kept in shared/ so they are testable without an ssh2 install.
+ *
+ * Background (v0.4.3): a host grant can be revoked while an SSHManager
+ * operation is already in flight. Closing the session stops the transport,
+ * but a command can complete and a file can be pulled in the same tick as the
+ * revocation. These gates are the *second* boundary: even if the transport
+ * work finished, nothing from the revoked host may be delivered to the agent
+ * (and no downloaded file may remain on disk).
+ *
+ * v0.4.4: missing predicate is fail-closed (never a silent no-op). HTTP and
+ * write actions re-check the same gate.
+ *
+ * A session without a project binding is also denied: every creation path
+ * normalizes projectPathKey, so an empty binding means corrupted state, and
+ * skipping the comparison would silently authorize it.
+ */
+import { unlinkSync } from 'node:fs'
+
+export function assertSessionStillAuthorized(session, isHostAuthorized, deniedMessage) {
+  if (!session) throw new Error('SSH session missing')
+  if (typeof isHostAuthorized !== 'function') {
+    throw new Error('SSH authorization predicate required')
+  }
+  if (!isHostAuthorized(session.projectPathKey, session.hostId)) {
+    throw new Error(
+      typeof deniedMessage === 'string' && deniedMessage
+        ? deniedMessage
+        : 'SSH session host is not authorized for the current project.',
+    )
+  }
+}
+
+export function discardRevokedLocalFile(session, localPath, isHostAuthorized) {
+  if (!session) return false
+  if (typeof isHostAuthorized !== 'function') {
+    throw new Error('SSH authorization predicate required')
+  }
+  if (!isHostAuthorized(session.projectPathKey, session.hostId)) {
+    try {
+      unlinkSync(localPath)
+    } catch {}
+    return true
+  }
+  return false
+}