dsh-ssh-workbench 0.0.0-stage → 1.7.0

package/lib/core/dialect.js

@@ -0,0 +1,28 @@
+/**
+ * Target dialect helpers.
+ *
+ * A server record keeps a hand-maintained `platform` hint (`posix`/`windows`)
+ * for the UI and for pre-probe compatibility, but the only trustworthy source
+ * is a live probe. `facts.dialect` stores that probe result; every decision
+ * that changes the command syntax (which remote shell tool to use, how to
+ * wrap a timeout) reads it through `effectiveDialect()`.
+ */
+
+/** The dialect values this plugin understands. */
+const DIALECTS = Object.freeze({ POSIX: 'posix', WINDOWS: 'windows' })
+
+/** Normalize one raw dialect/platform value. */
+export function normalizeDialect(value) {
+  return value === DIALECTS.WINDOWS || value === 'win32' ? DIALECTS.WINDOWS : DIALECTS.POSIX
+}
+
+/**
+ * The dialect to build commands for.
+ * A probed value wins; the record's `platform` is only a fallback hint.
+ */
+export function effectiveDialect(server) {
+  const probed = server?.facts?.dialect
+  if (probed === DIALECTS.WINDOWS || probed === DIALECTS.POSIX) return probed
+  return normalizeDialect(server?.platform)
+}
+

package/lib/core/errors.js

@@ -0,0 +1,138 @@
+/**
+ * Shared SSH error taxonomy.
+ *
+ * Kept in its own module so the transport broker and the tool-facing runtime
+ * can share the same `SshError` class without an import cycle.
+ */
+
+export class SshError extends Error {
+  constructor(code, message, extra = {}) {
+    super(message)
+    this.name = 'SshError'
+    this.code = code
+    Object.assign(this, extra)
+  }
+}
+
+export function normalizeError(error, fingerprint) {
+  // Keep structured errors intact: a missing private key is an auth problem,
+  // not a generic execution failure.
+  if (error instanceof SshError) return error
+  const message = error instanceof Error ? error.message : String(error)
+  const code = error && typeof error === 'object' && 'code' in error ? String(error.code) : ''
+  if (/host key verification failed|host denied \(verification failed\)|hostVerifier/i.test(message)) {
+    return new SshError('HOST_KEY_UNKNOWN', message, { fingerprint })
+  }
+  if (/all configured authentication methods failed|authentication failed|permission denied/i.test(message)) {
+    return new SshError('AUTH_FAILED', message)
+  }
+  if (/timed out while waiting|connect timeout|timeout/i.test(message) && !/command/i.test(message)) {
+    return new SshError('CONNECT_TIMEOUT', message)
+  }
+  if (/econnrefused|ehostunreach|enotfound|getaddrinfo|network unreachable|econnreset/i.test(message) || /^(ECONN|ENOTFOUND|EHOST)/.test(code)) {
+    return new SshError('NETWORK', message)
+  }
+  return new SshError('EXEC_FAILED', message)
+}
+
+export function suggestedActionFor(code) {
+  switch (code) {
+    case 'AUTH_MISSING':
+      return 'Set the SSH password (or switch to key auth) in Settings → SSH Workbench → managed resources.'
+    case 'AUTH_FAILED':
+      return 'Check the username, private key path, or password for this resource.'
+    case 'HOST_KEY_UNKNOWN':
+      return 'Compare the shown fingerprint with the server operator, then trust it in Settings → SSH Workbench.'
+    case 'CONNECT_TIMEOUT':
+      return 'Check the host/port and network path; raise connectTimeoutMs if the host is slow.'
+    case 'NETWORK':
+      return 'The host is unreachable: check DNS, routing, VPN, or the SSH port.'
+    case 'TIMEOUT':
+      return 'The command exceeded its timeout. Narrow the command or raise timeoutMs.'
+    case 'CANCELLED':
+      return 'The operation was cancelled.'
+    case 'COMMAND_NOT_FOUND':
+      return 'The remote shell reported a missing command; check the remote PATH.'
+    case 'SFTP_FAILED':
+      return 'The SFTP operation failed; check the remote path, permissions, and the SSH server SFTP subsystem.'
+    case 'COMMAND_NOT_EXECUTABLE':
+      return 'The file exists but is not executable (exit 126); check the shebang and chmod +x.'
+    case 'PERMISSION_DENIED':
+      return 'Permission denied: check the remote user, file ownership/mode, or use a privileged account.'
+    case 'DISK_FULL':
+      return 'The remote filesystem is full or over quota; free space (df -h) and retry.'
+    case 'READ_ONLY_FS':
+      return 'The remote filesystem is read-only; remount it read-write or pick another path.'
+    case 'INTERRUPTED':
+      return 'The command was interrupted (exit 130 / SIGINT).'
+    case 'KILLED':
+      return 'The command was killed (exit 137 / SIGKILL); it may have hit the OOM killer or a manual kill.'
+    default:
+      return 'Inspect stderr for details, or run a smaller diagnostic command first.'
+  }
+}
+
+/**
+ * Classify a failed exec result into the most specific error code we can infer
+ * from the exit status and stderr. Used for both `errorCode` and the
+ * human-readable suggestion.
+ */
+export function classifyExecFailure({ exitCode, stderr, signal } = {}) {
+  const text = String(stderr ?? '')
+  if (/command not found/i.test(text)) return 'COMMAND_NOT_FOUND'
+  if (/permission denied/i.test(text)) return 'PERMISSION_DENIED'
+  if (/no space left on device|disk quota exceeded/i.test(text)) return 'DISK_FULL'
+  if (/read-only file system/i.test(text)) return 'READ_ONLY_FS'
+  if (signal) return 'KILLED'
+  switch (exitCode) {
+    case 126: return 'COMMAND_NOT_EXECUTABLE'
+    case 127: return 'COMMAND_NOT_FOUND'
+    case 130: return 'INTERRUPTED'
+    case 137: return 'KILLED'
+    default: return 'EXEC_FAILED'
+  }
+}
+
+export function errorResult(code, message, extra = {}) {
+  return {
+    outcome: code === 'CANCELLED' ? 'cancelled' : code === 'TIMEOUT' ? 'timeout' : 'failed',
+    exitCode: null,
+    signal: null,
+    stdout: '',
+    stderr: message,
+    durationMs: 0,
+    truncated: { stdout: false, stderr: false },
+    errorCode: code,
+    suggestedAction: suggestedActionFor(code),
+    ...extra,
+  }
+}
+
+/**
+ * `grep`/`diff`/`pgrep` exit 1 for "no match" / "files differ": that is a
+ * normal answer, not an execution failure. Reinterpret it only when the whole
+ * command was classified read-only and the remote wrote nothing to stderr —
+ * a read-only command that exits 1 with a silent stderr is almost certainly
+ * reporting content, not a broken execution.
+ */
+export function isBenignReadOnlyExit({ readOnly, exitCode, stderr, signal } = {}) {
+  return readOnly === true && exitCode === 1 && !signal && !String(stderr ?? '').trim()
+}
+
+/** Normalize any SFTP-layer error into a structured `SFTP_FAILED` SshError. */
+export function toSftpError(error) {
+  if (error instanceof SshError) {
+    return error.code === 'EXEC_FAILED' ? new SshError('SFTP_FAILED', error.message) : error
+  }
+  return new SshError('SFTP_FAILED', error instanceof Error ? error.message : String(error))
+}
+
+/** Connection-level failure detection (used to evict a dead pooled connection). */
+export function isConnectionLevelError(error) {
+  const message = error instanceof Error ? error.message : String(error ?? '')
+  const code = error && typeof error === 'object' && 'code' in error ? String(error.code) : ''
+  if (['ECONNRESET', 'ECONNREFUSED', 'EPIPE', 'ETIMEDOUT', 'EHOSTUNREACH', 'ENETUNREACH'].includes(code)) return true
+  return /not\s+connected|connection\s+(lost|reset|closed|force\s+closed)|socket\s+closed|force\s+closed|keepalive\s+timeout|read\s+ec\w+|broken\s+pipe|econn\w+|epipe|etimedout/i.test(
+    message,
+  )
+}

package/lib/core/execution-stats.js

@@ -0,0 +1,88 @@
+/**
+ * Per-session execution summary for the composer target dock.
+ *
+ * DSH owns conversation/model metrics (turns, TTFT, TPS); the plugin cannot
+ * read them. This module only summarizes the activity entries the plugin
+ * writes for remote executions, so the dock can show accurate SSH-side counts
+ * and latency without inventing values it does not own.
+ */
+
+function numericDuration(entry) {
+  return Number.isFinite(entry?.durationMs) && entry.durationMs >= 0 ? entry.durationMs : 0
+}
+
+function emptyBucket(name) {
+  return { name, count: 0, success: 0, failed: 0, durationMs: 0, averageMs: 0, lastAt: null }
+}
+
+function addToBucket(bucket, entry) {
+  bucket.count += 1
+  if (entry.outcome === 'success') bucket.success += 1
+  else bucket.failed += 1
+  bucket.durationMs += numericDuration(entry)
+  if (typeof entry.at === 'string' && (bucket.lastAt === null || entry.at > bucket.lastAt)) bucket.lastAt = entry.at
+}
+
+/**
+ * Summarize the plugin's remote execution activity for one Session.
+ *
+ * @param {object[]} entries newest-first activity entries
+ * @param {{ sessionId?: string, candidates?: string[] }} options
+ * @returns {{
+ *   sessionId: string|null,
+ *   count: number,
+ *   success: number,
+ *   failed: number,
+ *   durationMs: number,
+ *   averageMs: number,
+ *   lastAt: string|null,
+ *   servers: Array<{name:string,count:number,success:number,failed:number,durationMs:number,averageMs:number,lastAt:string|null}>
+ * }}
+ */
+export function summarizeExecution(entries, { sessionId, candidates = [] } = {}) {
+  const wanted = typeof sessionId === 'string' && sessionId.length > 0 ? sessionId : null
+  const byServer = new Map()
+  const summary = {
+    sessionId: wanted,
+    count: 0,
+    success: 0,
+    failed: 0,
+    durationMs: 0,
+    averageMs: 0,
+    lastAt: null,
+    servers: [],
+  }
+
+  if (wanted !== null) {
+    for (const entry of Array.isArray(entries) ? entries : []) {
+      if (!entry || entry.kind !== 'exec' || entry.sessionId !== wanted) continue
+      summary.count += 1
+      if (entry.outcome === 'success') summary.success += 1
+      else summary.failed += 1
+      summary.durationMs += numericDuration(entry)
+      if (typeof entry.at === 'string' && (summary.lastAt === null || entry.at > summary.lastAt)) summary.lastAt = entry.at
+      const name = typeof entry.server === 'string' && entry.server.length > 0 ? entry.server : null
+      if (name === null) continue
+      if (!byServer.has(name)) byServer.set(name, emptyBucket(name))
+      addToBucket(byServer.get(name), entry)
+    }
+  }
+
+  summary.averageMs = summary.count > 0 ? Math.round(summary.durationMs / summary.count) : 0
+
+  // Keep the mentioned resources in mention order, then append any target that
+  // ran from an explicit remote_exec task without being a session candidate.
+  const names = []
+  for (const name of Array.isArray(candidates) ? candidates : []) {
+    const value = String(name)
+    if (value && !names.includes(value)) names.push(value)
+  }
+  for (const name of [...byServer.keys()].sort()) {
+    if (!names.includes(name)) names.push(name)
+  }
+  summary.servers = names.map((name) => {
+    const bucket = byServer.get(name) ?? emptyBucket(name)
+    return { ...bucket, averageMs: bucket.count > 0 ? Math.round(bucket.durationMs / bucket.count) : 0 }
+  })
+  return summary
+}

package/lib/core/gate-pwsh.js

@@ -0,0 +1,88 @@
+/**
+ * PowerShell blacklist for the Windows remote shell.
+ *
+ * Same philosophy as the POSIX gate: this is a deterministic accident stop,
+ * not a permission boundary. It only catches machine-destroying commands a
+ * model might emit by mistake (disk/volume formatting, partition edits, boot
+ * configuration edits, whole-drive recursive deletes). Everything else is left
+ * to the DSH session approval preset.
+ */
+
+const RULES = [
+  {
+    ruleId: 'format-volume',
+    reason: 'formatting a volume (Format-Volume)',
+    pattern: /\bformat-volume\b/,
+  },
+  {
+    ruleId: 'disk-management',
+    reason: 'disk/partition management (Clear-Disk, Initialize-Disk, Remove-Partition)',
+    pattern: /\b(?:clear-disk|initialize-disk|remove-partition|resize-partition)\b/,
+  },
+  {
+    ruleId: 'diskpart',
+    reason: 'interactive disk partitioning (diskpart)',
+    pattern: /\bdiskpart(?:\.exe)?\b/,
+  },
+  {
+    ruleId: 'format-command',
+    reason: 'formatting a drive (format)',
+    pattern: /\bformat(?:\.com)?\s+[a-z]:/,
+  },
+  {
+    ruleId: 'boot-config',
+    reason: 'boot configuration edit (bcdedit)',
+    pattern: /\bbcdedit(?:\.exe)?\b/,
+  },
+  {
+    ruleId: 'wipe-free-space',
+    reason: 'wiping free space (cipher /w)',
+    pattern: /\bcipher(?:\.exe)?\s+\/w\b/,
+  },
+  {
+    ruleId: 'shadow-delete',
+    reason: 'deleting volume shadow copies (vssadmin/wbadmin)',
+    pattern: /\b(?:vssadmin|wbadmin)(?:\.exe)?\s+delete\b/,
+  },
+  {
+    ruleId: 'rm-root',
+    reason: 'recursive delete of a drive root or system directory',
+    pattern:
+      /\b(?:remove-item|rm|rd|rmdir|del)\b(?=[^|;]*(?:-recurse|-r\b|\/s)\b)[^|;]*?(?:[a-z]:[\\/]{1,2}(?:windows|users|programdata|program files)\b|[a-z]:[\\/]{0,2}(?:['"]|\s|$)|\$(?:env:)?systemdrive\b|%systemdrive%)/,
+  },
+  {
+    ruleId: 'remove-root-recursive',
+    reason: 'recursive delete of a whole drive',
+    pattern: /\b(?:remove-item|rm|rd|rmdir|del)\b[^|;]*?['"]?[a-z]:[\\/]?['"]?\s+(?:-recurse|-force|\/s|\/q)/,
+  },
+]
+
+/** Split one PowerShell command into independently-executed statements. */
+function powerShellStatements(command) {
+  return String(command ?? '')
+    .split(/[;\r\n]|\|\||&&|\|/)
+    .map((part) => part.trim())
+    .filter(Boolean)
+}
+
+/** Lowercase + collapse whitespace, without touching quoted content semantics. */
+function normalizeStatement(statement) {
+  return statement.toLowerCase().replace(/\s+/g, ' ').trim()
+}
+
+/**
+ * @param {string} command
+ * @returns {{decision: 'deny'|'allow', reason: string, ruleId: string}}
+ */
+export function classifyPowerShellCommand(command) {
+  if (!String(command ?? '').trim()) return { decision: 'allow', reason: 'empty command', ruleId: 'empty' }
+  for (const statement of powerShellStatements(command)) {
+    const text = normalizeStatement(statement)
+    for (const rule of RULES) {
+      if (rule.pattern.test(text)) {
+        return { decision: 'deny', reason: rule.reason, ruleId: rule.ruleId }
+      }
+    }
+  }
+  return { decision: 'allow', reason: 'not on the PowerShell machine-destruction blacklist', ruleId: 'allow' }
+}