dsh-remote 0.8.13 → 0.8.15

package/lib/client.js

@@ -6,7 +6,7 @@
 //
 // A unified workspace directory picker fills ui-workspace's two directory-flow
 // holes (sidebar + conversation hero):
-//   • 本机 tab → opens the NATIVE OS folder chooser (ctx.workspaces.pickDirectory)
+//   • 本机 tab → opens the NATIVE OS folder chooser (/dsh-remote/local-pick)
 //     and returns the picked local path (works with local workspaces).
 //   • 远程 tab → pick a machine (dropdown), list its directories over
 //     /dsh-remote/ls, choose or type a remote path → /dsh-remote/mirror builds a
@@ -109,6 +109,7 @@ window.__ModuleLoader__.load({
         'settings.deleted': '已删除',
         'settings.saved': '已保存更新',
         'settings.added': '已添加 — 可设为当前',
+        'settings.secretStoreFailed': '密码未能写入系统密钥库（{msg}），已回退为明文保存在 machines.json，连接仍可用。',
         'settings.switched': '已切换为当前远程机',
         'settings.cleared': '已取消当前远程机 — 本地会话不再自动使用远程上下文',
         'settings.filledSsh': '已从 ~/.ssh/config 填入（仅引用私钥路径，不读取内容）',
@@ -308,6 +309,7 @@ window.__ModuleLoader__.load({
         'settings.deleted': 'Deleted',
         'settings.saved': 'Saved',
         'settings.added': 'Added — you can set it as current',
+        'settings.secretStoreFailed': 'The OS keychain refused the password ({msg}); it was saved as plaintext in machines.json and the machine still connects.',
         'settings.switched': 'Switched to current remote machine',
         'settings.cleared': 'Cleared current remote — local sessions no longer use remote context automatically',
         'settings.filledSsh': 'Filled from ~/.ssh/config (only references the private key path, never reads its content)',
@@ -598,8 +600,7 @@ window.__ModuleLoader__.load({
       }
     }
 
-    let WORKSPACES = null // ctx.get('workspaces'), set in apply()
-    let SESSIONS = null // ctx.get('sessions'), set in apply()
+    let SESSIONS = null // optional sessions service, tracked by ctx.inject in apply()
 
     // ── Settings → 远程工作区 (machine registry + forwards + audit) ──────────
     function RemoteWorkspacePage() {
@@ -716,7 +717,13 @@ window.__ModuleLoader__.load({
           workspace: form.workspace, hostKeyMode: form.hostKeyMode, useAgent: form.useAgent, keyboardInteractive: form.keyboardInteractive,
           encryptPassword: form.encryptPassword,
           proxy: form.proxyHost ? { host: form.proxyHost, port: Number(form.proxyPort) || 22, username: form.proxyUser || '', password: form.proxyPassword || '', privateKeyPath: form.proxyKey || '' } : undefined,
-        }).then((r) => { refresh(); clearForm(); setMsg(form.id ? tr('settings.saved') : tr('settings.added')) }).catch((e) => setErr(String((e && e.message) || e))).finally(() => setBusy(false))
+        }).then((r) => {
+          refresh(); clearForm()
+          // Issue #30: "加密保存密码"失败时服务端回退明文并带警告 —— 不能再静默
+          // 保存一台没有凭据的机器（那会让之后每次连接都失败且没有原因）。
+          if (r && r.warning === 'secret-store-failed') setErr(tr('settings.secretStoreFailed', { msg: r.warningDetail || 'unknown' }))
+          else setMsg(form.id ? tr('settings.saved') : tr('settings.added'))
+        }).catch((e) => setErr(String((e && e.message) || e))).finally(() => setBusy(false))
       }
       const useNow = (id) => { setBusy(true); api('POST', '/dsh-remote/current', { id }).then((r) => { setCurrentId(r.currentId); setMsg(tr('settings.switched')) }).catch((e) => setErr(String((e && e.message) || e))).finally(() => setBusy(false)) }
       // Issue #13: "active remote = none" — saved machines stay, but no machine
@@ -1955,36 +1962,31 @@ window.__ModuleLoader__.load({
 
     function apply(ctx) {
       const slots = ctx.get('slots')
-      if (slots === undefined) return
       wireLocale(ctx)
-      // Issue #26: on dsh 0.1.2-rc.1+ the cordis ctx proxy throws
-      // "cannot get property \"workspaces\" without inject" on ANY bare property
-      // read of an undeclared/unavailable service. ctx.get(name) stays an
-      // optional lookup that returns undefined instead of throwing, so never
-      // fall back to ctx.<name> property access — keep it purely optional.
-      WORKSPACES = (ctx && ctx.get && ctx.get('workspaces')) || null
-      SESSIONS = (ctx && ctx.get && ctx.get('sessions')) || null
+      // Optional integrations must not gate the settings page. In particular,
+      // replacement sidebars may disable the native ui-workspace package.
+      ctx.inject(['sessions'], (inner) => {
+        const sessions = inner.get('sessions')
+        SESSIONS = sessions
+        inner.effect(() => () => {
+          if (SESSIONS === sessions) SESSIONS = null
+        }, 'dsh-remote.sessions')
+      })
       slots.inject('settings.section', () =>
-        slots.register({ name: 'settings.section', id: 'dsh-remote', priority: 40, label: () => tr('settings.title') }, () => React.createElement(RemoteWorkspacePage, null)),
-      )
-      slots.inject(
-        'conversation.hero.workspace.directoryFlow',
-        () => slots.inject('sidebar.workspaces.directoryFlow',
-          function* () {
-            yield slots.register({ name: 'conversation.hero.workspace.directoryFlow', id: 'dsh-remote', priority: -100 }, DirPicker)
-            yield slots.register({ name: 'sidebar.workspaces.directoryFlow', id: 'dsh-remote', priority: -100 }, DirPicker)
-          },
-        ),
+        slots.register({ name: 'settings.section', id: 'dsh-remote', order: 40, label: () => tr('settings.title') }, () => React.createElement(RemoteWorkspacePage, null)),
       )
+      for (const slot of ['conversation.hero.workspace.directoryFlow', 'sidebar.workspaces.directoryFlow']) {
+        slots.inject(slot, () =>
+          slots.register({ name: slot, id: 'dsh-remote', priority: -100 }, DirPicker),
+        )
+      }
       ctx.inject(['betterSidebar'], (inner) => {
-        const bsDispose = registerSidebarIntegration(inner)
-        if (bsDispose) {
-          inner.effect(() => bsDispose, 'dsh-remote.betterSidebar')
-        }
+        inner.effect(() => registerSidebarIntegration(inner), 'dsh-remote.betterSidebar')
       })
     }
 
     exports.name = name
+    exports.inject = ['slots', 'locale']
     exports.apply = apply
     return module.exports
   },

package/lib/credential.js

@@ -1,107 +1,177 @@
-// dsh-remote — optional OS-keychain password storage.
-// Machines keep their password in the OS credential store instead of the
-// plaintext machines.json when the user enables "加密保存密码" per machine.
-// Every backend is best-effort: any failure resolves to {ok:false} and the
-// caller falls back to plaintext (the feature must never block connecting).
-//
-// Backends:
-//   darwin  → `security` (login keychain, generic password)
-//   win32   → DPAPI via PowerShell (CurrentUser scope), files under
-//             $DSH_HOME/remote-workspaces/.secrets/
-//   linux   → `secret-tool` (libsecret / gnome-keyring), optional
-//   else    → unsupported (plain)
-import { execFile } from 'node:child_process'
-import { mkdirSync, writeFileSync, readFileSync, unlinkSync } from 'node:fs'
-import { join as joinPath } from 'node:path'
-
-const SERVICE = 'dsh-remote'
-const TIMEOUT = 8000
-
-function run(bin, args, input) {
-  return new Promise((resolve, reject) => {
-    execFile(bin, args, { timeout: TIMEOUT, maxBuffer: 1 << 20, ...(input != null ? { input } : {}) }, (err, stdout, stderr) => {
-      if (err) return reject(err)
-      resolve(String(stdout || '').trim())
-    })
-  })
-}
-
-export function platformBackend() {
-  if (process.platform === 'darwin') return 'keychain'
-  if (process.platform === 'win32') return 'windows'
-  return 'secret' // linux (secret-tool may be absent → falls back)
-}
-
-function account(machineId) {
-  // Only machine ids are stored; sanitize just in case.
-  return String(machineId || '').replace(/[^a-zA-Z0-9._-]/g, '_')
-}
-
-/** Save a password to the OS store. Resolves {ok, backend} — ok:false on any
- * failure (caller falls back to plaintext). */
-export async function saveSecret(machineId, password, secretsDir) {
-  const acc = account(machineId)
-  try {
-    if (process.platform === 'darwin') {
-      await run('security', ['add-generic-password', '-U', '-s', SERVICE, '-a', acc, '-w', String(password)])
-      return { ok: true, backend: 'keychain' }
-    }
-    if (process.platform === 'win32') {
-      // DPAPI-encrypt and store under the harness home.
-      const script =
-        `$p='${String(password).replace(/'/g, "''")}';` +
-        `$s=[System.Security.Cryptography.ProtectedData]::Protect([Text.Encoding]::UTF8.GetBytes($p),$null,[System.Security.Cryptography.DataProtectionScope]::CurrentUser);` +
-        `[Convert]::ToBase64String($s)`
-      const b64 = await run('powershell', ['-NoProfile', '-STA', '-Command', script])
-      if (!b64) return { ok: false, backend: 'windows' }
-      mkdirSync(secretsDir || '.', { recursive: true })
-      writeFileSync(joinPath(secretsDir || '.', acc + '.bin'), b64, 'utf8')
-      return { ok: true, backend: 'windows' }
-    }
-    if (process.platform === 'linux') {
-      await run('secret-tool', ['store', '--label=' + SERVICE, 'service', SERVICE, 'account', acc], String(password) + '\n')
-      return { ok: true, backend: 'secret' }
-    }
-  } catch { /* fall through */ }
-  return { ok: false, backend: platformBackend() }
-}
-
-/** Fetch a stored password. Resolves string|null. */
-export async function getSecret(machineId, secretsDir) {
-  const acc = account(machineId)
-  try {
-    if (process.platform === 'darwin') {
-      return await run('security', ['find-generic-password', '-s', SERVICE, '-a', acc, '-w'])
-    }
-    if (process.platform === 'win32') {
-      const b64 = readFileSync(joinPath(secretsDir || '.', acc + '.bin'), 'utf8').trim()
-      if (!b64) return null
-      const script =
-        `$s=[Convert]::FromBase64String('${b64}');` +
-        `[Text.Encoding]::UTF8.GetString([System.Security.Cryptography.ProtectedData]::Unprotect($s,$null,[System.Security.Cryptography.DataProtectionScope]::CurrentUser))`
-      return await run('powershell', ['-NoProfile', '-STA', '-Command', script])
-    }
-    if (process.platform === 'linux') {
-      return await run('secret-tool', ['lookup', 'service', SERVICE, 'account', acc])
-    }
-  } catch { /* fall through */ }
-  return null
-}
-
-/** Delete a stored password (idempotent). */
-export async function deleteSecret(machineId, secretsDir) {
-  const acc = account(machineId)
-  try {
-    if (process.platform === 'darwin') {
-      await run('security', ['delete-generic-password', '-s', SERVICE, '-a', acc]).catch(() => {})
-      return
-    }
-    if (process.platform === 'win32') {
-      try { unlinkSync(joinPath(secretsDir || '.', acc + '.bin')) } catch { /* absent */ }
-      return
-    }
-    if (process.platform === 'linux') {
-      await run('secret-tool', ['clear', 'service', SERVICE, 'account', acc]).catch(() => {})
-    }
-  } catch { /* best effort */ }
-}
+// dsh-remote — optional OS-keychain password storage.
+// Machines keep their password in the OS credential store instead of the
+// plaintext machines.json when the user enables "加密保存密码" per machine.
+// Every backend is best-effort: any failure resolves to {ok:false} and the
+// caller (persistPassword) falls back to plaintext + a user-visible warning
+// (the feature must never block connecting, and must never silently drop the
+// credential — issue #30).
+//
+// Backends:
+//   darwin  → `security` (login keychain, generic password)
+//   win32   → DPAPI via PowerShell (CurrentUser scope), files under
+//             $DSH_HOME/remote-workspaces/.secrets/
+//   linux   → `secret-tool` (libsecret / gnome-keyring), optional
+//   else    → unsupported (plain)
+import { execFile } from 'node:child_process'
+import { mkdirSync, writeFileSync, readFileSync, unlinkSync } from 'node:fs'
+import { join as joinPath } from 'node:path'
+
+const SERVICE = 'dsh-remote'
+const TIMEOUT = 8000
+
+// Windows PowerShell 5.1 does not preload System.Security, so
+// [System.Security.Cryptography.ProtectedData] is "not found" until the assembly
+// is added (issue #30: without this the whole DPAPI call failed and the caller
+// silently lost the password). `-ErrorAction SilentlyContinue` keeps the line
+// harmless on PowerShell 7, where the type is already available.
+const PS_SECURITY_ASSEMBLY = 'Add-Type -AssemblyName System.Security -ErrorAction SilentlyContinue;'
+
+function run(bin, args, input) {
+  return new Promise((resolve, reject) => {
+    execFile(bin, args, { timeout: TIMEOUT, maxBuffer: 1 << 20, ...(input != null ? { input } : {}) }, (err, stdout, stderr) => {
+      if (err) return reject(err)
+      resolve(String(stdout || '').trim())
+    })
+  })
+}
+
+export function platformBackend() {
+  if (process.platform === 'darwin') return 'keychain'
+  if (process.platform === 'win32') return 'windows'
+  return 'secret' // linux (secret-tool may be absent → falls back)
+}
+
+function account(machineId) {
+  // Only machine ids are stored; sanitize just in case.
+  return String(machineId || '').replace(/[^a-zA-Z0-9._-]/g, '_')
+}
+
+/** Redact a failed command's diagnostics: execFile puts the FULL command line
+ * (which carries the password as an argv) into `err.message`, and this string is
+ * shown in the settings UI — so the secret must never survive it. */
+function safeReason(err, password) {
+  const raw = [err && err.stderr, err && err.message, err && err.code]
+    .filter(Boolean).map(String).join(' ')
+  const secret = String(password == null ? '' : password)
+  const scrubbed = secret ? raw.split(secret).join('***') : raw
+  return scrubbed.replace(/\s+/g, ' ').trim().slice(0, 300)
+}
+
+/** PowerShell one-liner that DPAPI-protects a password (CurrentUser scope).
+ *  Exported because the issue #30 fix (the mandatory Add-Type preamble) is only
+ *  observable here — a Windows host cannot be exercised from the test suite. */
+export function dpapiProtectScript(password) {
+  return PS_SECURITY_ASSEMBLY +
+    `$p='${String(password).replace(/'/g, "''")}';` +
+    `$s=[System.Security.Cryptography.ProtectedData]::Protect([Text.Encoding]::UTF8.GetBytes($p),$null,[System.Security.Cryptography.DataProtectionScope]::CurrentUser);` +
+    `[Convert]::ToBase64String($s)`
+}
+
+/** PowerShell one-liner that reverses dpapiProtectScript(). */
+export function dpapiUnprotectScript(b64) {
+  return PS_SECURITY_ASSEMBLY +
+    `$s=[Convert]::FromBase64String('${String(b64).replace(/'/g, "''")}');` +
+    `[Text.Encoding]::UTF8.GetString([System.Security.Cryptography.ProtectedData]::Unprotect($s,$null,[System.Security.Cryptography.DataProtectionScope]::CurrentUser))`
+}
+
+/** Save a password to the OS store. Resolves {ok, backend, error} — ok:false on
+ * any failure (caller falls back to plaintext). `error` is a password-free
+ * diagnostic for the UI. */
+export async function saveSecret(machineId, password, secretsDir) {
+  const acc = account(machineId)
+  try {
+    if (process.platform === 'darwin') {
+      await run('security', ['add-generic-password', '-U', '-s', SERVICE, '-a', acc, '-w', String(password)])
+      return { ok: true, backend: 'keychain', error: '' }
+    }
+    if (process.platform === 'win32') {
+      // DPAPI-encrypt and store under the harness home.
+      const script = dpapiProtectScript(password)
+      const b64 = await run('powershell', ['-NoProfile', '-STA', '-Command', script])
+      if (!b64) return { ok: false, backend: 'windows', error: 'DPAPI returned no ciphertext' }
+      mkdirSync(secretsDir || '.', { recursive: true })
+      writeFileSync(joinPath(secretsDir || '.', acc + '.bin'), b64, 'utf8')
+      return { ok: true, backend: 'windows', error: '' }
+    }
+    if (process.platform === 'linux') {
+      await run('secret-tool', ['store', '--label=' + SERVICE, 'service', SERVICE, 'account', acc], String(password) + '\n')
+      return { ok: true, backend: 'secret', error: '' }
+    }
+  } catch (err) {
+    return { ok: false, backend: platformBackend(), error: safeReason(err, password) || 'secret store write failed' }
+  }
+  return { ok: false, backend: platformBackend(), error: `unsupported platform: ${process.platform}` }
+}
+
+/** Decide where a machine password is persisted (issue #30).
+ *
+ * The contract the settings UI relies on: a password is NEVER dropped. When the
+ * requested OS store fails (missing DPAPI assembly, locked keychain, absent
+ * secret-tool), this falls back to plaintext in machines.json and reports
+ * `warning: 'secret-store-failed'` so the caller can tell the user instead of
+ * silently saving a credential-less machine.
+ *
+ * `save` is injectable so the fallback is unit-testable on any platform.
+ *
+ * @returns {Promise<{stored:'secret'|'plain'|'none', credentialBackend:string, password:string, warning:string, error:string}>}
+ */
+export async function persistPassword({ backend, machineId, password, secretsDir, save = saveSecret }) {
+  const pw = password == null ? '' : String(password)
+  const want = backend && backend !== 'plain' ? backend : 'plain'
+  if (!pw) return { stored: 'none', credentialBackend: want, password: '', warning: '', error: '' }
+  if (want === 'plain') return { stored: 'plain', credentialBackend: 'plain', password: pw, warning: '', error: '' }
+  let res
+  try {
+    res = await save(machineId, pw, secretsDir)
+  } catch (err) {
+    res = { ok: false, error: safeReason(err, pw) }
+  }
+  if (res && res.ok) {
+    return { stored: 'secret', credentialBackend: res.backend || want, password: '', warning: '', error: '' }
+  }
+  return {
+    stored: 'plain',
+    credentialBackend: 'plain',
+    password: pw,
+    warning: 'secret-store-failed',
+    error: String((res && res.error) || '') || 'secret store write failed',
+  }
+}
+
+/** Fetch a stored password. Resolves string|null. */
+export async function getSecret(machineId, secretsDir) {
+  const acc = account(machineId)
+  try {
+    if (process.platform === 'darwin') {
+      return await run('security', ['find-generic-password', '-s', SERVICE, '-a', acc, '-w'])
+    }
+    if (process.platform === 'win32') {
+      const b64 = readFileSync(joinPath(secretsDir || '.', acc + '.bin'), 'utf8').trim()
+      if (!b64) return null
+      const script = dpapiUnprotectScript(b64)
+      return await run('powershell', ['-NoProfile', '-STA', '-Command', script])
+    }
+    if (process.platform === 'linux') {
+      return await run('secret-tool', ['lookup', 'service', SERVICE, 'account', acc])
+    }
+  } catch { /* fall through */ }
+  return null
+}
+
+/** Delete a stored password (idempotent). */
+export async function deleteSecret(machineId, secretsDir) {
+  const acc = account(machineId)
+  try {
+    if (process.platform === 'darwin') {
+      await run('security', ['delete-generic-password', '-s', SERVICE, '-a', acc]).catch(() => {})
+      return
+    }
+    if (process.platform === 'win32') {
+      try { unlinkSync(joinPath(secretsDir || '.', acc + '.bin')) } catch { /* absent */ }
+      return
+    }
+    if (process.platform === 'linux') {
+      await run('secret-tool', ['clear', 'service', SERVICE, 'account', acc]).catch(() => {})
+    }
+  } catch { /* best effort */ }
+}

package/lib/errors.js

@@ -1,78 +1,78 @@
-// dsh-remote — SSH/SFTP error classification → actionable hints.
-// Pure function so it is unit-testable and reused by tools, slash commands,
-// the test-connect route and the settings UI.
-
-/** Classify an error thrown by the ssh pool / sftp wrapper.
- * @returns {{ category: 'auth'|'network'|'hostkey'|'timeout'|'sftp'|'credentials'|'other', hint: string, raw: string }}
- */
-export function classifyError(err, opts = {}) {
-  const msg = String((err && err.message) || err || '')
-  const { host, port } = opts
-  const where = host ? ` (${host}:${port || 22})` : ''
-
-  if (/host key/i.test(msg) && /(change|mismatch|fingerprint|verify|unknown host)/i.test(msg)) {
-    return {
-      category: 'hostkey',
-      hint: `主机指纹校验失败${where}：可能遭遇中间人攻击，或该主机重装/更换过密钥。确认无异常后执行 /remote-forget-key 重新信任。`,
-      raw: msg,
-    }
-  }
-  if (/permission denied|all configured authentication methods failed|authentication failed/i.test(msg)) {
-    return {
-      category: 'auth',
-      hint: `认证失败${where}：检查用户名/密码/私钥路径，私钥是否设了 passphrase；若公司机器要求 OTP/动态码，请确认机器配置了 keyboard-interactive 或对应密码。`,
-      raw: msg,
-    }
-  }
-  if (/no credentials/i.test(msg)) {
-    return {
-      category: 'credentials',
-      hint: `缺少凭据：请设置 password 或 privateKeyPath（私钥只在显式提供时使用），或为该机器启用 SSH agent。`,
-      raw: msg,
-    }
-  }
-  if (/ENOTFOUND|EAI_AGAIN|getaddrinfo/i.test(msg)) {
-    return {
-      category: 'network',
-      hint: `主机不可达${where}：检查 host 拼写 / IP / DNS；内网机器可能需要走跳板机（配置 proxy）或 VPN。`,
-      raw: msg,
-    }
-  }
-  if (/ECONNREFUSED|connection refused/i.test(msg)) {
-    return {
-      category: 'network',
-      hint: `连接被拒绝${where}：确认端口 ${port || 22} 正确、远端 sshd 在监听；检查防火墙/安全组是否放行。`,
-      raw: msg,
-    }
-  }
-  if (/sftp operation timed out|sftp failed|readdir|writeFile|fastGet|fastPut/i.test(msg)) {
-    return {
-      category: 'sftp',
-      hint: `SFTP 操作失败：可能是远端磁盘/权限问题或服务器卡死（已自动超时保护）。检查目标路径权限。`,
-      raw: msg,
-    }
-  }
-  if (/ETIMEDOUT|timed out|timeout/i.test(msg)) {
-    return {
-      category: 'timeout',
-      hint: `连接/操作超时${where}：检查端口、防火墙、路由；或调大 connectTimeoutMs / commandTimeoutMs。`,
-      raw: msg,
-    }
-  }
-  if (/cannot read private key/i.test(msg)) {
-    return {
-      category: 'credentials',
-      hint: `无法读取私钥文件：检查 privateKeyPath 是否存在、当前用户是否有读取权限。`,
-      raw: msg,
-    }
-  }
-  return { category: 'other', hint: msg, raw: msg }
-}
-
-/** One-line friendly message: hint (+ raw when it adds information). */
-export function friendlyMessage(err, opts = {}) {
-  const c = classifyError(err, opts)
-  if (c.category === 'other') return c.raw
-  if (c.raw && c.raw !== c.hint) return `${c.hint}（原始错误：${c.raw}）`
-  return c.hint
-}
+// dsh-remote — SSH/SFTP error classification → actionable hints.
+// Pure function so it is unit-testable and reused by tools, slash commands,
+// the test-connect route and the settings UI.
+
+/** Classify an error thrown by the ssh pool / sftp wrapper.
+ * @returns {{ category: 'auth'|'network'|'hostkey'|'timeout'|'sftp'|'credentials'|'other', hint: string, raw: string }}
+ */
+export function classifyError(err, opts = {}) {
+  const msg = String((err && err.message) || err || '')
+  const { host, port } = opts
+  const where = host ? ` (${host}:${port || 22})` : ''
+
+  if (/host key/i.test(msg) && /(change|mismatch|fingerprint|verify|unknown host)/i.test(msg)) {
+    return {
+      category: 'hostkey',
+      hint: `主机指纹校验失败${where}：可能遭遇中间人攻击，或该主机重装/更换过密钥。确认无异常后执行 /remote-forget-key 重新信任。`,
+      raw: msg,
+    }
+  }
+  if (/permission denied|all configured authentication methods failed|authentication failed/i.test(msg)) {
+    return {
+      category: 'auth',
+      hint: `认证失败${where}：检查用户名/密码/私钥路径，私钥是否设了 passphrase；若公司机器要求 OTP/动态码，请确认机器配置了 keyboard-interactive 或对应密码。`,
+      raw: msg,
+    }
+  }
+  if (/no credentials/i.test(msg)) {
+    return {
+      category: 'credentials',
+      hint: `缺少凭据：请设置 password 或 privateKeyPath（私钥只在显式提供时使用），或为该机器启用 SSH agent。`,
+      raw: msg,
+    }
+  }
+  if (/ENOTFOUND|EAI_AGAIN|getaddrinfo/i.test(msg)) {
+    return {
+      category: 'network',
+      hint: `主机不可达${where}：检查 host 拼写 / IP / DNS；内网机器可能需要走跳板机（配置 proxy）或 VPN。`,
+      raw: msg,
+    }
+  }
+  if (/ECONNREFUSED|connection refused/i.test(msg)) {
+    return {
+      category: 'network',
+      hint: `连接被拒绝${where}：确认端口 ${port || 22} 正确、远端 sshd 在监听；检查防火墙/安全组是否放行。`,
+      raw: msg,
+    }
+  }
+  if (/sftp operation timed out|sftp failed|readdir|writeFile|fastGet|fastPut/i.test(msg)) {
+    return {
+      category: 'sftp',
+      hint: `SFTP 操作失败：可能是远端磁盘/权限问题或服务器卡死（已自动超时保护）。检查目标路径权限。`,
+      raw: msg,
+    }
+  }
+  if (/ETIMEDOUT|timed out|timeout/i.test(msg)) {
+    return {
+      category: 'timeout',
+      hint: `连接/操作超时${where}：检查端口、防火墙、路由；或调大 connectTimeoutMs / commandTimeoutMs。`,
+      raw: msg,
+    }
+  }
+  if (/cannot read private key/i.test(msg)) {
+    return {
+      category: 'credentials',
+      hint: `无法读取私钥文件：检查 privateKeyPath 是否存在、当前用户是否有读取权限。`,
+      raw: msg,
+    }
+  }
+  return { category: 'other', hint: msg, raw: msg }
+}
+
+/** One-line friendly message: hint (+ raw when it adds information). */
+export function friendlyMessage(err, opts = {}) {
+  const c = classifyError(err, opts)
+  if (c.category === 'other') return c.raw
+  if (c.raw && c.raw !== c.hint) return `${c.hint}（原始错误：${c.raw}）`
+  return c.hint
+}