@tiphareth/dsh-hardssh 0.1.2-alpha

package/src/ssh/exec/output.ts

@@ -0,0 +1,70 @@
+/**
+ * Incremental UTF-8 output collector with a strict BYTE budget.
+ *
+ * The previous implementation compared `text.length` (UTF-16 code units)
+ * against `chunk.length` (bytes) and decoded each chunk in isolation, so
+ * multi-byte characters split across chunks turned into U+FFFD and the
+ * budget was never truly enforced. This collector counts raw input bytes,
+ * decodes across chunk boundaries with StringDecoder, and truncates on a
+ * complete UTF-8 sequence boundary.
+ * @module dsh-ssh/exec/output
+ */
+
+import { StringDecoder } from 'node:string_decoder'
+
+/** Marker appended when the captured output hits the byte budget. */
+export const TRUNCATION_MARKER = '\n[output truncated]'
+
+/** One captured stream (stdout or stderr). */
+export class BoundedUtf8Output {
+  private readonly decoder = new StringDecoder('utf8')
+  private readonly parts: string[] = []
+  private _bytesAccepted = 0
+  private _truncated = false
+  private _ended = false
+
+  constructor(private readonly maxBytes: number) {}
+
+  /** Raw bytes accepted so far (before truncation). */
+  get bytesAccepted(): number {
+    return this._bytesAccepted
+  }
+
+  /** True once the byte budget was hit and output was cut. */
+  get truncated(): boolean {
+    return this._truncated
+  }
+
+  append(chunk: Buffer): void {
+    if (this._truncated || chunk.length === 0) return
+    const remaining = this.maxBytes - this._bytesAccepted
+    if (chunk.length <= remaining) {
+      this._bytesAccepted += chunk.length
+      this.parts.push(this.decoder.write(chunk))
+      return
+    }
+    // Budget exhausted mid-chunk: keep the longest prefix that ends on a
+    // complete UTF-8 sequence, then stop accepting input. Back off from a
+    // continuation byte (0b10xxxxxx) to the sequence lead, and drop the
+    // lead itself when its continuations were cut away.
+    let cut = remaining
+    while (cut > 0 && (chunk[cut] & 0xc0) === 0x80) cut -= 1
+    if (cut > 0 && (chunk[cut - 1] & 0xc0) === 0xc0) cut -= 1
+    const kept = chunk.subarray(0, cut)
+    this._bytesAccepted += kept.length
+    if (kept.length > 0) this.parts.push(this.decoder.write(kept))
+    this.parts.push(this.decoder.end())
+    this._ended = true
+    this._truncated = true
+  }
+
+  /** The captured text (truncation marker appended when cut). Idempotent. */
+  finish(): string {
+    if (!this._ended) {
+      this._ended = true
+      this.parts.push(this.decoder.end())
+    }
+    const text = this.parts.join('')
+    return this._truncated ? text + TRUNCATION_MARKER : text
+  }
+}

package/src/ssh/known-hosts.ts

@@ -0,0 +1,214 @@
+/**
+ * SSH host-key trust store (TOFU): first-connection trust-on-first-use.
+ *
+ * When enabled, the engine refuses to connect to a host whose public-key
+ * fingerprint has not been explicitly trusted: the first encounter records a
+ * `pending` entry and the connection is REJECTED (credentials are never sent
+ * to an unverified host), the operator confirms the fingerprint through the
+ * GUI, and every later connection re-checks the stored fingerprint with a
+ * constant-time comparison.
+ *
+ * The store is deliberately independent of the credentials vault: a
+ * fingerprint is not a secret, so verifying the host needs no unlock, and
+ * Host-Key protectio n can ship (and be tested) before the vault lands.
+ *
+ * @module dsh-hardssh/known-hosts
+ */
+
+import { createHash, timingSafeEqual } from 'node:crypto'
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+
+/** File format version. */
+const FORMAT_VERSION = 1
+
+/** One known-host record. */
+export interface KnownHostRecord {
+  alias: string
+  host: string
+  port: number
+  /** Server public-key algorithm (ssh-ed25519, ssh-rsa, …) for display. */
+  keyType: string
+  /** Canonical fingerprint: 'SHA256:' + base64 (no '=' padding). */
+  fingerprint: string
+  /** 'pending' = seen once, waiting for explicit trust; 'trusted' = confirmed. */
+  status: 'pending' | 'trusted'
+  firstSeenAt: number
+  confirmedAt: number | null
+}
+
+interface KnownHostsFile {
+  version: number
+  hosts: KnownHostRecord[]
+}
+
+/** Default file location: <home>/.dsh/ssh-known-hosts.json. */
+export function knownHostsPath(): string {
+  return join(homedir(), '.dsh', 'ssh-known-hosts.json')
+}
+
+/** Normalize a fingerprint to the canonical 'SHA256:<b64-no-padding>' form. */
+export function normalizeFingerprint(input: string): string {
+  const trimmed = input.trim().replace(/^SHA256:/iu, '')
+  return 'SHA256:' + trimmed.replace(/=+$/u, '')
+}
+
+/** Constant-time comparison of two fingerprints (canonical form, length-safe). */
+export function fingerprintsEqual(a: string, b: string): boolean {
+  const bufA = Buffer.from(normalizeFingerprint(a).slice('SHA256:'.length))
+  const bufB = Buffer.from(normalizeFingerprint(b).slice('SHA256:'.length))
+  return bufA.length === bufB.length && timingSafeEqual(bufA, bufB)
+}
+
+/** Compute the canonical OpenSSH-style fingerprint of a server key blob. */
+export function fingerprintOf(rawKey: Buffer): string {
+  const digest = createHash('sha256').update(rawKey).digest('base64').replace(/=+$/u, '')
+  return 'SHA256:' + digest
+}
+
+/** Host-key check outcome. */
+export type HostKeyCheck =
+  | { kind: 'trusted' }
+  | { kind: 'unknown'; fingerprintSha256: string }
+  | { kind: 'mismatch'; expected: string; actual: string }
+
+/** Persisted host-key trust store (atomic write, 0600). */
+export class KnownHostsStore {
+  private readonly path: string
+  private records = new Map<string, KnownHostRecord>()
+
+  constructor(filePath?: string) {
+    this.path = filePath ?? knownHostsPath()
+    this.load()
+  }
+
+  private load(): void {
+    if (!existsSync(this.path)) return
+    try {
+      const parsed = JSON.parse(readFileSync(this.path, 'utf8')) as KnownHostsFile
+      if (typeof parsed !== 'object' || parsed === null || !Array.isArray(parsed.hosts)) return
+      for (const record of parsed.hosts) {
+        if (isRecord(record)) this.records.set(record.alias, record)
+      }
+    } catch {
+      // Corrupt / unreadable trust file: fail open (treat as empty) rather
+      // than brick every SSH connection; the first connect re-records pending.
+    }
+  }
+
+  private save(): void {
+    const dir = dirname(this.path)
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true, mode: 0o700 })
+    const file: KnownHostsFile = { version: FORMAT_VERSION, hosts: [...this.records.values()] }
+    const tmp = this.path + '.tmp'
+    writeFileSync(tmp, JSON.stringify(file, null, 2) + '\n', { encoding: 'utf8', mode: 0o600 })
+    renameSync(tmp, this.path)
+  }
+
+  lookup(alias: string): KnownHostRecord | undefined {
+    return this.records.get(alias)
+  }
+
+  /** First encounter: record as pending (non-destructive re-observe keeps status). */
+  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
+    this.records.set(alias, {
+      alias,
+      host: meta.host,
+      port: meta.port,
+      keyType: meta.keyType,
+      fingerprint: meta.fingerprintSha256,
+      status: 'pending',
+      firstSeenAt: Date.now(),
+      confirmedAt: null,
+    })
+    this.save()
+  }
+
+  /** pending → trusted (must match the recorded fingerprint). */
+  trust(alias: string): void {
+    const record = this.records.get(alias)
+    if (record === undefined) throw new Error(`no host-key record for '${alias}'`)
+    record.status = 'trusted'
+    record.confirmedAt = Date.now()
+    this.save()
+  }
+
+  /** Forget a host (key rotation /误信 reset → next connect re-TOFU). */
+  forget(alias: string): void {
+    this.records.delete(alias)
+    this.save()
+  }
+
+  list(): KnownHostRecord[] {
+    return [...this.records.values()]
+  }
+}
+
+/** Per-alias host-key policy: check a server key against the store. */
+export class HostKeyPolicy {
+  constructor(private readonly knownHosts: KnownHostsStore) {}
+
+  /** Evaluate one server key: trusted / unknown (records pending) / mismatch. */
+  check(alias: string, rawKey: Buffer): 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,
+        keyType: keyTypeOf(rawKey),
+        fingerprintSha256: actual,
+      })
+      return { kind: 'unknown', fingerprintSha256: actual }
+    }
+    if (recorded.status !== 'trusted') 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'
+}
+
+function isRecord(value: unknown): value is KnownHostRecord {
+  if (typeof value !== 'object' || value === null) return false
+  const record = value as Record<string, unknown>
+  return typeof record.alias === 'string'
+    && typeof record.fingerprint === 'string'
+    && (record.status === 'pending' || record.status === 'trusted')
+}
+
+/** Error: the host key is not trusted yet (first encounter, awaiting confirm). */
+export class HostKeyUnknownError extends Error {
+  readonly fingerprintSha256: string
+  constructor(alias: string, fingerprintSha256: string) {
+    super(`host key for '${alias}' 尚未信任 — 请先确认 SHA256 指纹 ${fingerprintSha256}`)
+    this.name = 'HostKeyUnknownError'
+    this.fingerprintSha256 = fingerprintSha256
+  }
+}
+
+/** Error: the host key changed since it was trusted (possible MITM / key rotation). */
+export class HostKeyMismatchError extends Error {
+  readonly expected: string
+  readonly actual: string
+  constructor(alias: string, expected: string, actual: string) {
+    super(`host key for '${alias}' 已变化（期望 ${expected}，实际 ${actual}）—— 请先人工核验服务器后 forget 重置信任`)
+    this.name = 'HostKeyMismatchError'
+    this.expected = expected
+    this.actual = actual
+  }
+}

package/src/ssh/plugin.ts

@@ -0,0 +1,184 @@
+/**
+ * The SSH operations capability, now hosted inside dsh-hardssh (migrated
+ * from the legacy dsh-ssh package): host config store
+ * (~/.dsh/dsh-ssh.json), the shared ssh2 engine, /api/dsh-ssh routes, the
+ * six ssh_* agent tools, the `dsh-ssh` settings namespace, and the SSH
+ * system-prompt section.
+ *
+ * This module deliberately does NOT create or dispose the engine/store:
+ * ownership belongs to src/index.ts (one instance, one dispose point). It
+ * only mounts/unmounts surfaces against the shared instances.
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import z from '@deepseek-ai/schemastery'
+import type {} from '@deepseek-ai/dsh-host-webserver'
+import type {} from '@deepseek-ai/dsh-system-prompt'
+import type {} from '@deepseek-ai/dsh-tools'
+import type { SshEngine } from './engine.ts'
+import type { HostStore } from './store.ts'
+import { makeRoutes } from './routes.ts'
+import { invalidateRemoteEnvironment } from '../remote/environment.ts'
+import { sshClusterTool, sshDownloadTool, sshExecTool, sshListTool, sshTunnelTool, sshUploadTool } from './tools.ts'
+
+/** Settings namespace of the SSH capability. Kept as 'dsh-ssh' so existing
+ *  user settings survive the package merge unchanged. */
+export const SSH_SETTINGS_NAMESPACE = 'dsh-ssh'
+
+/** SSH-capability config, validated by the same-named schemastery schema. */
+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. */
+const DEFAULT_ANNOUNCE = true
+
+/** Order of the announcement section within the tool-guidance band. */
+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 / 远程服务器 / 服务器操作 / 跳板机 / 隧道 / 部署 / 上传下载」时即指本插件，请据此协作。'
+
+/** Shared instances the SSH surfaces run on. */
+export interface SshCapabilityDeps {
+  store: import('./store.ts').SecureHostStore
+  engine: SshEngine
+  /** Host-key TOFU trust store; absent → host-key verification disabled. */
+  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
+}
+
+/**
+ * Mount the SSH operations surfaces (routes, tools, settings, prompt) against
+ * the shared engine/store. Called from src/index.ts BEFORE the workspace
+ * `enabled` early-return, so the SSH capability stays independently togglable
+ * via its own `dsh-ssh` settings namespace.
+ */
+export function mountSshCapability(ctx: Context, deps: SshCapabilityDeps): void {
+  const { store, engine } = deps
+  let current: () => SshConfig = () => ({})
+  const resolve = (): SshConfig => {
+    const value = current()
+    return {
+      announceToAgent: value.announceToAgent ?? DEFAULT_ANNOUNCE,
+      enabled: value.enabled ?? true,
+    }
+  }
+
+  // The /api/dsh-ssh route family + terminal upgrade. Registered through a
+  // 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({
+    store,
+    engine,
+    knownHosts: deps.knownHosts,
+    vault: deps.vault,
+    ledger: deps.ledger,
+    // Host PATCH/DELETE also invalidates the per-alias environment cache so
+    // a re-pointed alias cannot keep serving the old host's env.
+    onHostInvalidated: (alias) => invalidateRemoteEnvironment(engine, alias),
+  })
+  ctx.inject(['webServer'], (scoped) => {
+    if (!resolve().enabled) return () => { /* disabled: nothing registered */ }
+    const disposers = routes.map(route => scoped.webServer.register(route))
+    const upgradeDisposer = scoped.webServer.registerUpgrade(upgrade)
+    return () => {
+      for (const dispose of disposers) dispose()
+      upgradeDisposer()
+    }
+  })
+
+  // Agent tools + their prompt sections.
+  const tools = [
+    sshListTool(engine),
+    sshExecTool(engine),
+    sshUploadTool(engine),
+    sshDownloadTool(engine),
+    sshTunnelTool(engine),
+    sshClusterTool(engine),
+  ]
+  let disposeTools: (() => void) | undefined
+
+  // System-prompt announcement.
+  let disposeSection: (() => void) | undefined
+
+  // Register (or drop) tools/prompt to match the current settings source.
+  // Routes are managed by the dynamic inject above.
+  const sync = (): void => {
+    const value = resolve()
+    if (disposeSection !== undefined) {
+      disposeSection()
+      disposeSection = undefined
+    }
+    if (disposeTools !== undefined) {
+      disposeTools()
+      disposeTools = undefined
+    }
+    if (!value.enabled) return
+    if (value.announceToAgent) {
+      disposeSection = ctx.systemPrompt.section({
+        name: 'plugin:dsh-ssh',
+        order: SECTION_ORDER,
+        text: SSH_GUIDANCE,
+      })
+    }
+    disposeTools = ctx.effect(
+      () => {
+        const disposers = tools.map(tool => ctx.tools.register(tool))
+        return () => { for (const dispose of disposers) dispose() }
+      },
+      'dsh-ssh: tools',
+    )
+  }
+
+  // Settings-backed configuration (dsh-settings service; optional in
+  // headless profiles). The service was rewritten in dsh 0.1.2: the old
+  // `installSettingsSection`/`settingsNamespace` exports are gone, replaced
+  // by ctx.settings.installSection(owner, ns, schema, entry, hooks). The
+  // default entry is the resolved config defaults; setSource/onChange keep
+  // the sync() wiring equivalent for both generations.
+  type SettingsService = {
+    installSection?(owner: Context, ns: string, schema: unknown, entry: unknown, hooks: {
+      setSource(current: () => SshConfig): void
+      onChange(): void
+    }): void
+  }
+  const settings = ctx.get('settings') as SettingsService | undefined
+  if (settings?.installSection !== undefined) {
+    settings.installSection(ctx, 'dsh-ssh', SshConfig, {}, {
+      setSource: (source) => {
+        current = source
+        sync()
+      },
+      onChange: sync,
+    })
+  }
+
+  // Initial registration (covers deployments with no settings service, whose
+  // installSection never fires its hooks).
+  sync()
+}

package/src/ssh/protocol.ts

@@ -0,0 +1,227 @@
+/**
+ * Wire contract between the host half (routes.ts) and the browser half
+ * (client/api.ts). Pure types only — imported by both halves, bundled into
+ * each, no runtime identity to share.
+ */
+
+/** Authentication flavors a host entry may carry. */
+export type SshAuthKind = 'key' | 'password'
+
+/** One stored host entry (the ~/.dsh/dsh-ssh.json store shape). */
+export interface SshHostEntry {
+  /** Stable, user-chosen identifier used by every operation. */
+  alias: string
+  /** Hostname or IP of the target. */
+  host: string
+  /** SSH port (default 22). */
+  port: number
+  /** Login user. */
+  user: string
+  /** Authentication. */
+  auth: {
+    kind: SshAuthKind
+    /** Absolute path to the private key for 'key' auth. */
+    keyPath?: string
+    /** Passphrase for an encrypted key. */
+    passphrase?: string
+    /** Password for 'password' auth. */
+    password?: string
+    /** Vault ref to the encrypted password/passphrase (v2 secure store). */
+    secretRef?: string
+  }
+  /** Jump chain: local aliases connected through in order (ProxyJump). */
+  proxyJump: string[]
+  /** Free-form note. */
+  description?: string
+  /** Deployment environment label (development / production / ...). */
+  environment?: string
+  /** Free-form tags. */
+  tags: string[]
+  /** Physical location note. */
+  location?: string
+  createdAt: number
+  updatedAt: number
+}
+
+/** Public (secret-free) projection of an entry, safe for the browser/agent. */
+export interface SshHostSummary {
+  alias: string
+  host: string
+  port: number
+  user: string
+  auth: SshAuthKind
+  /** Whether the key path exists on the host machine (key auth only). */
+  keyReady: boolean
+  proxyJump: string[]
+  description?: string
+  environment?: string
+  tags: string[]
+  location?: string
+  createdAt: number
+  updatedAt: number
+}
+
+/** Result of one non-interactive command execution. */
+export interface ExecResult {
+  success: boolean
+  /** Remote exit code, or null when the channel died without one. */
+  exitCode: number | null
+  timedOut: boolean
+  stdout: string
+  stderr: string
+  /** Wall-clock duration of the round trip in ms. */
+  durationMs: number
+  /** Connection error message when the command never ran. */
+  error?: string
+}
+
+/** One server entry in a cluster run. */
+export interface ClusterResult {
+  alias: string
+  ok: boolean
+  exitCode?: number | null
+  timedOut?: boolean
+  stdout?: string
+  stderr?: string
+  durationMs?: number
+  error?: string
+}
+
+/** SFTP transfer progress frame (upload stream). */
+export interface TransferProgress {
+  phase: 'connecting' | 'transferring' | 'done' | 'error'
+  file: string
+  transferred: number
+  total: number
+  percent: number
+  speedBps?: number
+  error?: string
+}
+
+/** One active local port-forward tunnel. */
+export interface TunnelInfo {
+  id: string
+  alias: string
+  localPort: number
+  remoteHost: string
+  remotePort: number
+  state: 'forwarding' | 'connecting' | 'failed'
+  error?: string
+  startedAt: number
+}
+
+/** One directory listing entry (remote file browser). */
+export interface RemoteDirEntry {
+  name: string
+  type: 'dir' | 'file' | 'other'
+  size: number
+  mtimeMs: number
+  mode?: number
+}
+
+/** Test-connection outcome. */
+export interface TestResult {
+  ok: boolean
+  latencyMs?: number
+  error?: string
+  /** Stable machine code for host-key routing (HOST_KEY_UNKNOWN / HOST_KEY_MISMATCH / NEEDS_PASSWORD). */
+  code?: string
+  /** Which secret a connection needs when code === 'NEEDS_PASSWORD'. */
+  secret?: 'password' | 'passphrase'
+  /** The pending/expected fingerprint when a host key was refused. */
+  hostKeyFingerprint?: string
+  /** Mismatch detail (expected vs actual) when the host key changed. */
+  hostKeyMismatch?: { expected: string; actual: string }
+}
+
+/** Host edit payload (create/update); 'alias' comes from the URL for updates. */
+export interface HostPayload {
+  alias?: string
+  host: string
+  port?: number
+  user: string
+  /**
+   * Authentication. Required on create; on update an omitted auth keeps the
+   * stored secrets (the browser never receives them back).
+   */
+  auth?: SshHostEntry['auth']
+  proxyJump?: string[]
+  description?: string
+  environment?: string
+  tags?: string[]
+  location?: string
+}
+
+/** Import outcome from ~/.ssh/config. */
+export interface ImportResult {
+  parsed: number
+  added: number
+  skipped: number
+  /** Aliases that failed to map (wildcard patterns, missing HostName, ...). */
+  skippedNames: string[]
+}
+
+/** JSON error body used by every route. */
+export interface ApiErrorBody {
+  error: string
+  /** Stable machine code (HOST_KEY_UNKNOWN / HOST_KEY_MISMATCH / HOST_IN_USE / ...). */
+  code?: string
+  /** Which secret a connection needs when code === 'NEEDS_PASSWORD'. */
+  secret?: 'password' | 'passphrase'
+  /** The fingerprint when a host key was refused. */
+  hostKeyFingerprint?: string
+  /** Mismatch detail (expected vs actual) when the host key changed. */
+  hostKeyMismatch?: { expected: string; actual: string }
+  /** Workspace titles referencing a host that cannot be deleted (HOST_IN_USE). */
+  workspaces?: Array<{ id: string; title: string }>
+}
+
+/** WebSocket terminal protocol frames (host -> client and client -> host). */
+export type TerminalServerFrame =
+  | { type: 'ready'; alias: string }
+  | { type: 'output'; data: string }
+  | { type: 'exit'; code: number | null; error?: string }
+
+export type TerminalClientFrame =
+  | { type: 'input'; data: string }
+  | { type: 'resize'; cols: number; rows: number }
+
+/** Route paths the client calls (shared literals). */
+export const SSH_API_BASE = '/api/dsh-ssh' as const
+
+export const SSH_API = {
+  hosts: SSH_API_BASE + '/hosts',
+  importSshConfig: SSH_API_BASE + '/hosts/import-ssh-config',
+  test: SSH_API_BASE + '/test',
+  exec: SSH_API_BASE + '/exec',
+  cluster: SSH_API_BASE + '/cluster',
+  upload: SSH_API_BASE + '/upload',
+  download: SSH_API_BASE + '/download',
+  ls: SSH_API_BASE + '/ls',
+  tunnel: SSH_API_BASE + '/tunnel',
+  terminal: SSH_API_BASE + '/terminal',
+  knownHosts: SSH_API_BASE + '/known-hosts',
+  vault: SSH_API_BASE + '/vault',
+  sessionSecret: SSH_API_BASE + '/session-secret',
+  connections: SSH_API_BASE + '/connections',
+} as const
+
+/** One known-host record as seen by the browser (no secrets). */
+export interface KnownHostView {
+  alias: string
+  host: string
+  port: number
+  keyType: string
+  fingerprint: string
+  status: 'pending' | 'trusted'
+  firstSeenAt: number
+  confirmedAt: number | null
+}
+
+/** Host-key trust actions the browser can perform. */
+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 }