@tiphareth/dsh-hardssh 0.1.2 → 0.2.3

package/src/ssh/known-hosts.ts

@@ -110,10 +110,18 @@ export class KnownHostsStore {
     return this.records.get(alias)
   }
 
-  /** First encounter: record as pending (non-destructive re-observe keeps status). */
+  /** First encounter: record as pending. Re-observing keeps the recorded
+   *  status/fingerprint but backfills a previously empty host/port. */
   observe(alias: string, meta: { host: string; port: number; keyType: string; fingerprintSha256: string }): void {
     const existing = this.records.get(alias)
-    if (existing !== undefined) return // keep pending/trusted as-is
+    if (existing !== undefined) {
+      let changed = false
+      if (existing.host === '' && meta.host !== '') { existing.host = meta.host; changed = true }
+      if (existing.port === 0 && meta.port > 0) { existing.port = meta.port; changed = true }
+      if (existing.keyType === 'ssh-unknown' && meta.keyType !== 'ssh-unknown') { existing.keyType = meta.keyType; changed = true }
+      if (changed) this.save()
+      return
+    }
     this.records.set(alias, {
       alias,
       host: meta.host,
@@ -127,10 +135,13 @@ export class KnownHostsStore {
     this.save()
   }
 
-  /** pending → trusted (must match the recorded fingerprint). */
-  trust(alias: string): void {
+  /** pending → trusted (must match the recorded fingerprint). Optional
+   *  host/port backfill completes a record whose first observe had no target. */
+  trust(alias: string, target?: { host?: string; port?: number }): void {
     const record = this.records.get(alias)
     if (record === undefined) throw new Error(`no host-key record for '${alias}'`)
+    if (record.host === '' && target?.host !== undefined && target.host !== '') record.host = target.host
+    if (record.port === 0 && target?.port !== undefined && target.port > 0) record.port = target.port
     record.status = 'trusted'
     record.confirmedAt = Date.now()
     this.save()
@@ -151,36 +162,49 @@ export class KnownHostsStore {
 export class HostKeyPolicy {
   constructor(private readonly knownHosts: KnownHostsStore) {}
 
-  /** Evaluate one server key: trusted / unknown (records pending) / mismatch. */
-  check(alias: string, rawKey: Buffer): HostKeyCheck {
+  /** Evaluate one server key: trusted / unknown (records pending) / mismatch.
+   *  `target` supplies the host/port the engine is actually connecting to so
+   *  the audit record is complete instead of `''`/0. */
+  check(alias: string, rawKey: Buffer, target?: { host?: string; port?: number }): HostKeyCheck {
     const recorded = this.knownHosts.lookup(alias)
     const actual = fingerprintOf(rawKey)
     if (recorded === undefined) {
       // First encounter: remember as pending, but NOT trusted — the caller
       // must refuse the connection until the operator confirms.
       this.knownHosts.observe(alias, {
-        host: '', // host/port are filled by the engine's richer record on confirm
-        port: 0,
+        host: target?.host ?? '',
+        port: target?.port ?? 0,
         keyType: keyTypeOf(rawKey),
         fingerprintSha256: actual,
       })
       return { kind: 'unknown', fingerprintSha256: actual }
     }
-    if (recorded.status !== 'trusted') return { kind: 'unknown', fingerprintSha256: recorded.fingerprint }
+    if (recorded.status !== 'trusted') {
+      this.knownHosts.observe(alias, {
+        host: target?.host ?? '',
+        port: target?.port ?? 0,
+        keyType: keyTypeOf(rawKey),
+        fingerprintSha256: recorded.fingerprint,
+      })
+      return { kind: 'unknown', fingerprintSha256: recorded.fingerprint }
+    }
     if (fingerprintsEqual(recorded.fingerprint, actual)) return { kind: 'trusted' }
     return { kind: 'mismatch', expected: recorded.fingerprint, actual }
   }
 }
 
-/** Best-effort key type label from the raw blob's base64 header. */
-function keyTypeOf(rawKey: Buffer): string {
-  try {
-    const base64 = rawKey.toString('base64')
-    const decoded = Buffer.from(base64, 'base64').toString('utf8')
-    const end = decoded.indexOf(' ')
-    if (end > 0) return decoded.slice(0, end)
-  } catch { /* fall through */ }
-  return 'ssh-unknown'
+/**
+ * Parse the key type out of a real SSH wire public-key blob. The blob is
+ * `string algorithm, byte[] key` where every string is a 4-byte big-endian
+ * length followed by raw bytes — NOT the `ssh-ed25519 AAAA…` authorized_keys
+ * text form, so a text-oriented decode would always yield 'ssh-unknown'.
+ */
+export function keyTypeOf(rawKey: Buffer): string {
+  if (rawKey.length < 4) return 'ssh-unknown'
+  const length = rawKey.readUInt32BE(0)
+  if (length === 0 || length > 64 || 4 + length > rawKey.length) return 'ssh-unknown'
+  const algorithm = rawKey.subarray(4, 4 + length).toString('latin1')
+  return /^[a-z0-9@.\-]+$/u.test(algorithm) ? algorithm : 'ssh-unknown'
 }
 
 function isRecord(value: unknown): value is KnownHostRecord {

package/src/ssh/local-transfer-policy.ts

@@ -0,0 +1,83 @@
+/**
+ * Host-side path policy for ssh_upload / ssh_download.
+ *
+ * These tools bridge remote I/O to the DSH host, so accepting an arbitrary
+ * absolute local path would bypass the normal FileSystem sandbox. The only
+ * trusted per-call root available to a tool body is the validated absolute cwd
+ * stored on the invoking Agent's immutable SessionHeader.
+ */
+
+import { existsSync, realpathSync, statSync } from 'node:fs'
+import { basename, dirname, isAbsolute, relative, resolve } from 'node:path'
+import type { ToolRunContext } from '@deepseek-ai/dsh-tools'
+
+export type LocalTransferDirection = 'upload-source' | 'download-destination'
+
+function outside(root: string, candidate: string): boolean {
+  const rel = relative(root, candidate)
+  return rel === '..' || rel.startsWith(`..${process.platform === 'win32' ? '\\' : '/'}`) || isAbsolute(rel)
+}
+
+function fail(path: string, root: string): never {
+  throw new Error(`local transfer path '${path}' is outside the invoking session workspace '${root}'`)
+}
+
+/** Canonicalize a not-yet-existing destination through its nearest existing
+ * ancestor, preserving the suffix beneath that canonical ancestor. */
+function canonicalFuturePath(path: string): string {
+  const suffix: string[] = [basename(path)]
+  let cursor = dirname(path)
+  for (;;) {
+    if (existsSync(cursor)) {
+      return resolve(realpathSync.native(cursor), ...suffix)
+    }
+    const parent = dirname(cursor)
+    if (parent === cursor) throw new Error(`cannot resolve an existing parent for local destination '${path}'`)
+    suffix.unshift(basename(cursor))
+    cursor = parent
+  }
+}
+
+/**
+ * Validate and canonicalize one local transfer path.
+ *
+ * Uploads must name an existing regular file. Downloads may create the final
+ * file and missing parent directories, but their nearest existing ancestor is
+ * canonicalized so an in-workspace symlink/junction cannot redirect the write
+ * outside the session root.
+ */
+export function secureLocalTransferPath(
+  exec: ToolRunContext,
+  localPath: string,
+  direction: LocalTransferDirection,
+): string {
+  const cwd = exec.agent?.session.header.cwd
+  if (cwd === undefined) {
+    throw new Error('local transfer denied: the tool call has no invoking session workspace')
+  }
+  if (!isAbsolute(cwd)) throw new Error('local transfer denied: invoking session cwd is not absolute')
+  if (!isAbsolute(localPath)) throw new Error('local transfer path must be absolute')
+
+  let root: string
+  try {
+    root = realpathSync.native(cwd)
+  } catch {
+    throw new Error(`local transfer denied: invoking session workspace '${cwd}' is unavailable`)
+  }
+
+  const requested = resolve(localPath)
+  let canonical: string
+  if (direction === 'upload-source') {
+    try {
+      canonical = realpathSync.native(requested)
+    } catch {
+      throw new Error(`local upload source '${localPath}' does not exist`)
+    }
+    if (!statSync(canonical).isFile()) throw new Error(`local upload source '${localPath}' is not a regular file`)
+  } else {
+    canonical = existsSync(requested) ? realpathSync.native(requested) : canonicalFuturePath(requested)
+  }
+
+  if (outside(root, canonical)) fail(localPath, root)
+  return canonical
+}

package/src/ssh/plugin.ts

@@ -25,29 +25,21 @@ import { sshClusterTool, sshDownloadTool, sshExecTool, sshListTool, sshTunnelToo
  *  user settings survive the package merge unchanged. */
 export const SSH_SETTINGS_NAMESPACE = 'dsh-ssh'
 
-/** SSH-capability config, validated by the same-named schemastery schema. */
+/** SSH-capability config, validated by the same-named schemastery schema.
+ *  `secretStorage` is deliberately NOT a key here: the mode decides which
+ *  objects are constructed at plugin load, so it is a single source in the
+ *  top-level plugin config (`Config.secretStorage`). A value left in this
+ *  namespace by hand is reported as drift by src/index.ts, never applied. */
 export interface SshConfig {
   /** When true (default), a system-prompt section announces the SSH capability. */
   announceToAgent?: boolean
   /** Master switch for the SSH surfaces (routes, tools, prompt section). */
   enabled?: boolean
-  /**
-   * Secret storage mode:
-   * - 'none' (default): passwords/passphrases are NEVER persisted; each
-   *   session's first connection prompts for them (VSCode Remote-SSH style)
-   *   and they live in memory (session password table) for the connection
-   *   pool lifetime (idle 30 min auto-disconnect; new terminals reuse it).
-   * - 'vault': store secrets encrypted at rest (AES-256-GCM) under a master
-   *   password / DSH_CREDENTIAL_PASSWORD; for headless agents that must run
-   *   password hosts unattended.
-   */
-  secretStorage?: 'none' | 'vault'
 }
 
 export const SshConfig: z<SshConfig> = z.object({
   announceToAgent: z.boolean().default(true),
   enabled: z.boolean().default(true),
-  secretStorage: z.union([z.const('none'), z.const('vault')]).default('none'),
 })
 
 /** Schema default, re-read for hand-built test contexts. */
@@ -57,7 +49,7 @@ const DEFAULT_ANNOUNCE = true
 const SECTION_ORDER = 150
 
 /** Model-facing announcement: SSH operations capability, capabilities, limits. */
-export const SSH_GUIDANCE = '本机已安装 dsh-hardssh 插件（内建 DSH 远程 SSH 运维）：侧边栏「SSH」入口；SSH 运维与 SSH 工作区在 dsh-hardssh 中统一维护。能力：主机配置存 ~/.dsh/dsh-ssh.json（可从 ~/.ssh/config 导入）；持久连接池复用长连接（空闲 30 分钟自动断开）；ssh_list 列出主机、ssh_exec 执行远程命令、ssh_upload/ssh_download 传输文件、ssh_tunnel 本地端口转发（访问远程数据库/内网服务）、ssh_cluster 集群并发执行；支持密钥/密码认证、passphrase 密钥与 ProxyJump 跳板机；Web 终端走 WebSocket。限制：主机操作由用户在 GUI 中配置后 agent 方可使用；密码以明文存在用户主目录私有文件（权限 0600）；命令输出原样返回、可能含敏感信息；连接建立失败会自动重连，但命令或文件操作一旦提交就不会自动重试——结果不明确时应先核实远端状态，再决定是否人工重试；传输/执行消耗真实远程资源，先确认再操作。用户提到「SSH / 远程服务器 / 服务器操作 / 跳板机 / 隧道 / 部署 / 上传下载」时即指本插件，请据此协作。'
+export const SSH_GUIDANCE = '本机已安装 dsh-hardssh 插件（内建 DSH 远程 SSH 运维）：侧边栏「SSH」入口；SSH 运维与 SSH 工作区在 dsh-hardssh 中统一维护。能力：主机配置存 ~/.dsh/dsh-ssh.json（可从 ~/.ssh/config 导入）；持久连接池复用长连接（空闲 30 分钟自动断开）；ssh_list 列出主机、ssh_exec 执行远程命令、ssh_upload/ssh_download 传输文件、ssh_tunnel 本地端口转发（访问远程数据库/内网服务）、ssh_cluster 集群并发执行；支持密钥/密码认证、passphrase 密钥与 ProxyJump 跳板机；Web 终端走 WebSocket。限制：主机操作由用户在 GUI 中配置后 agent 方可使用；凭据默认不落盘（secretStorage=none 时仅存于本进程内存，按连接存活期复用、连接池回收即失效；secretStorage=vault 时以 AES-256-GCM 加密存于本机 vault 文件，`DSH_CREDENTIAL_PASSWORD` 自动解锁默认关闭，需 vaultAutoUnlock: env 显式开启）；命令输出与错误经过凭据脱敏（已揭示/会话内的密码会被替换），但仍可能含其它敏感信息；连接建立失败会自动重连，但命令或文件操作一旦提交就不会自动重试——结果不明确时应先核实远端状态，再决定是否人工重试；传输/执行消耗真实远程资源，先确认再操作。用户提到「SSH / 远程服务器 / 服务器操作 / 跳板机 / 隧道 / 部署 / 上传下载」时即指本插件，请据此协作。'
 
 /** Shared instances the SSH surfaces run on. */
 export interface SshCapabilityDeps {
@@ -67,8 +59,10 @@ export interface SshCapabilityDeps {
   knownHosts?: import('./known-hosts.ts').KnownHostsStore
   /** Credential vault; absent → vault endpoints disabled. */
   vault?: import('./vault.ts').Vault
-  /** SSH-bound workspace ledger (host-delete reference guard). */
-  ledger?: import('../ledger.ts').SshWorkspaceLedger
+  /** SSH-bound workspace record source (host-delete reference guard). The
+   *  legacy ledger in legacy mode, the generic WorkspaceCore-backed projection
+   *  store in the default generic mode. */
+  ledger?: import('../backend.ts').WorkspaceStoreView
 }
 
 /**
@@ -92,7 +86,7 @@ export function mountSshCapability(ctx: Context, deps: SshCapabilityDeps): void
   // dynamic webServer inject (headless profiles lack the service — mirroring
   // the workspace routes in src/index.ts). The enabled switch is honored at
   // registration time; toggling it later takes effect on reload.
-  const { routes, upgrade } = makeRoutes({
+  const { routes, upgrade, dispose: disposeRoutes } = makeRoutes({
     store,
     engine,
     knownHosts: deps.knownHosts,
@@ -103,12 +97,19 @@ export function mountSshCapability(ctx: Context, deps: SshCapabilityDeps): void
     onHostInvalidated: (alias) => invalidateRemoteEnvironment(engine, alias),
   })
   ctx.inject(['webServer'], (scoped) => {
-    if (!resolve().enabled) return () => { /* disabled: nothing registered */ }
+    // Tear down the terminal server (live PTYs, SSH shells, WebSocketServer)
+    // on unload/HMR even when the switch is off or nothing was registered.
+    const dispose = (): void => { void disposeRoutes() }
+    if (!resolve().enabled) return dispose
     const disposers = routes.map(route => scoped.webServer.register(route))
     const upgradeDisposer = scoped.webServer.registerUpgrade(upgrade)
     return () => {
-      for (const dispose of disposers) dispose()
+      for (const routeDisposer of disposers) routeDisposer()
+      // Unregistering the upgrade route does not release its terminals: close
+      // every live PTY/SSH shell and the instance's WebSocketServer so unload
+      // and HMR leave nothing running (A-06). Idempotent.
       upgradeDisposer()
+      dispose()
     }
   })
 

package/src/ssh/protocol.ts

@@ -85,6 +85,16 @@ export interface ClusterResult {
   stderr?: string
   durationMs?: number
   error?: string
+  /** Stable machine code for a per-host failure (B-14) — lets callers retry
+   *  on an auth/TOFU gate instead of parsing the human message. */
+  code?: 'NEEDS_PASSWORD' | 'HOST_KEY_UNKNOWN' | 'HOST_KEY_MISMATCH' | 'ALIAS_NOT_FOUND' | 'ABORTED' | 'TIMEOUT' | 'ERROR'
+  /** Which secret the host needs when `code` is NEEDS_PASSWORD. */
+  secret?: 'password' | 'passphrase'
+  /** Server-key fingerprint for HOST_KEY_UNKNOWN / HOST_KEY_MISMATCH. */
+  hostKeyFingerprint?: string
+  /** Expected/actual fingerprints for HOST_KEY_MISMATCH. */
+  expected?: string
+  actual?: string
 }
 
 /** SFTP transfer progress frame (upload stream). */
@@ -224,4 +234,15 @@ export type KnownHostAction = 'trust' | 'forget'
 /** NDJSON transfer stream line shapes (upload). */
 export type TransferStreamLine =
   | { type: 'progress'; progress: TransferProgress }
-  | { type: 'result'; ok: boolean; transferredBytes?: number; error?: string }
+  /** The final remote rename is about to start; loss after this point means
+   *  the target's result is unknown until inspected. */
+  | { type: 'commit' }
+  | {
+    type: 'result'
+    ok: boolean
+    transferredBytes?: number
+    error?: string
+    code?: string
+    secret?: 'password' | 'passphrase'
+    hostKeyFingerprint?: string
+  }