dsh-ssh-manage 0.3.5 → 0.3.6

package/README.en.md

@@ -24,6 +24,7 @@
 
 - **Host management** — scan the config, groups, tags, favorites, notes, latency and host inspection;
 - **Interactive terminal** — ssh2 allocates a PTY, xterm.js renders it, with colors, arrow keys, full-screen programs such as `vim`/`top`, and window resizing;
+- **Backup and migration** — export/import hosts, groups, tags, notes, favorites and passwords from Settings; exports are re-encrypted with a passphrase (scrypt + AES-256-GCM) and imports merge by alias;
 - **Day-to-day operations** — batch commands, SFTP browse/mkdir/rename/delete/upload/download, connection tests;
 - **Credentials** — one AES-256-GCM encrypted password per host, never written to `~/.ssh/config`; passwords are not returned to the browser by default, but Show password decrypts one on demand in the current page and auto-hides it after 30 seconds;
 - **Agent tool** — `ssh_manager` exposes the same capabilities to the model.
@@ -96,16 +97,16 @@ Creating a host requires alias, hostname and password. The password is not writt
 
 ### From npm (recommended)
 
-npm package: [`dsh-ssh-manage`](https://www.npmjs.com/package/dsh-ssh-manage) (current version `0.3.5`).
+npm package: [`dsh-ssh-manage`](https://www.npmjs.com/package/dsh-ssh-manage) (current version `0.3.6`).
 
 ```text
-plugin_manager action=install_bundle target=dsh-ssh-manage@0.3.5
+plugin_manager action=install_bundle target=dsh-ssh-manage@0.3.6
 ```
 
 Or with the DSH CLI:
 
 ```bash
-dsh plugin add dsh-ssh-manage@0.3.5
+dsh plugin add dsh-ssh-manage@0.3.6
 ```
 
 After installation, refresh the Web page; the sidebar shows an "SSH Hosts" entry with id `dsh-ssh-manage`.
@@ -221,6 +222,7 @@ The terminal uses vendored xterm.js 6.0.0 (MIT, see `assets/LICENSE.xterm`), @xt
 - **Config editing scope**: the editor only changes `Host`, `HostName`, `User`, `Port` and plugin metadata; maintain other SSH directives in `~/.ssh/config`.
 - **Batch commands** run one command; they are not an interactive terminal. Per-host output is capped at 1 MB and marked `truncated` when exceeded.
 - **File size**: SFTP files are capped at 10 MB.
+- **Export safety**: encrypted exports contain all passwords; a lost passphrase is unrecoverable. Import only merges and never deletes existing hosts or passwords.
 - **SFTP rename/delete**: rename refuses to overwrite an existing destination by default (`sftp_rename` can pass `overwrite: true` explicitly); deleting a directory requires it to be empty, and root paths, `.`/`..` and drive roots are refused; symlinks are removed as links, not followed.
 - **xterm assets**: the first terminal open loads about 500 KB of xterm.js basics; the search addon loads on demand, about 556 KiB total from the same origin (no CDN).
 

package/README.md

@@ -24,6 +24,7 @@
 
 - **主机管理**：扫描配置、分组、标签、收藏、备注、连接延迟、主机巡检；
 - **交互式终端**：ssh2 分配 PTY，xterm.js 渲染，支持彩色输出、方向键、`vim`/`top` 等全屏程序和窗口自适应；
+- **备份迁移**：设置页可导出/导入主机、分组、标签、备注、收藏和密码；导出文件用自定义口令二次加密（scrypt + AES-256-GCM），导入按别名合并；
 - **日常运维**：批量命令、SFTP 目录浏览 / 新建 / 重命名 / 删除 / 上传 / 下载、测试连接；
 - **凭据管理**：每台主机保存一份 AES-256-GCM 加密密码，不写进 `~/.ssh/config`；默认不返回浏览器，在主机详情点“显示密码”时才按需解密到当前页面，30 秒后自动隐藏；
 - **Agent 工具**：`ssh_manager` 把同一套能力开放给模型。
@@ -98,16 +99,16 @@
 
 ### 从 npm 安装（推荐）
 
-npm 包：[`dsh-ssh-manage`](https://www.npmjs.com/package/dsh-ssh-manage)（当前版本 `0.3.5`）。
+npm 包：[`dsh-ssh-manage`](https://www.npmjs.com/package/dsh-ssh-manage)（当前版本 `0.3.6`）。
 
 ```text
-plugin_manager action=install_bundle target=dsh-ssh-manage@0.3.5
+plugin_manager action=install_bundle target=dsh-ssh-manage@0.3.6
 ```
 
 或使用 DSH CLI：
 
 ```bash
-dsh plugin add dsh-ssh-manage@0.3.5
+dsh plugin add dsh-ssh-manage@0.3.6
 ```
 
 安装后刷新 Web 页面，左侧栏会出现「SSH 主机」入口，入口 id 为 `dsh-ssh-manage`。

package/client.js

@@ -261,6 +261,32 @@ window.__ModuleLoader__.load({
       'settings.stateDir': ['状态目录', 'State directory'],
       'settings.vault': ['凭据仓库', 'Credential vault'],
       'settings.vaultDesc': ['密码使用 AES-256-GCM 加密保存在本机状态目录，插件启动时自动解锁，不需要主密码。', 'Passwords are AES-256-GCM encrypted in the local state directory and unlocked automatically; no master password.'],
+      'settings.transfer': ['备份与迁移', 'Backup and migration'],
+      'settings.transferBadge': ['加密导出', 'Encrypted export'],
+      'settings.transferDesc': ['导出主机、分组、标签、备注、收藏和密码，密码用你设置的口令二次加密；导入时按别名合并，不会删除现有主机。', 'Export hosts, groups, tags, notes, favorites and passwords. Passwords are encrypted again with a passphrase you choose; import merges by alias and never deletes existing hosts.'],
+      'settings.export': ['导出', 'Export'],
+      'settings.import': ['导入', 'Import'],
+      'transfer.exportTitle': ['导出主机数据', 'Export host data'],
+      'transfer.importTitle': ['导入主机数据', 'Import host data'],
+      'transfer.exportDesc': ['将导出 {count} 台主机及其分组、标签、备注、收藏和全部密码。密码部分会用口令再次加密。', 'Exports {count} host(s) with groups, tags, notes, favorites and all passwords. Password data is encrypted again with a passphrase.'],
+      'transfer.importDesc': ['选择由 dsh-ssh-manage 导出的 JSON 文件，输入导出时设置的口令。按主机别名合并：相同别名更新，新别名创建，不删除现有主机。', 'Choose a JSON file exported by dsh-ssh-manage and enter its passphrase. Hosts merge by alias: existing aliases update, new ones are created, nothing is deleted.'],
+      'transfer.passphrase': ['导出/导入口令（至少 8 位）', 'Export/import passphrase (at least 8 characters)'],
+      'transfer.confirmPassphrase': ['再次输入口令', 'Repeat the passphrase'],
+      'transfer.passphraseHint': ['口令只用于加密导出文件，不会保存。忘记口令将无法恢复导出的密码。', 'The passphrase only encrypts the export file and is not stored. A lost passphrase cannot be recovered.'],
+      'transfer.chooseFile': ['选择导出 JSON 文件', 'Choose export JSON file'],
+      'transfer.fileReady': ['已选择：{count} 台主机', 'Selected: {count} host(s)'],
+      'transfer.fileTooLarge': ['文件超过 8 MB，拒绝读取。', 'File is larger than 8 MB and was rejected.'],
+      'transfer.invalidFile': ['不是有效的 dsh-ssh-manage 导出文件。', 'Not a valid dsh-ssh-manage export file.'],
+      'transfer.chooseFileFirst': ['请先选择导出文件。', 'Choose an export file first.'],
+      'transfer.passphraseShort': ['口令至少需要 8 位。', 'Passphrase must be at least 8 characters.'],
+      'transfer.passphraseMismatch': ['两次输入的口令不一致。', 'The passphrases do not match.'],
+      'transfer.exportWarning': ['导出文件包含加密后的密码，请妥善保管文件与口令，不要上传到公共位置。', 'The export contains encrypted passwords; keep both the file and passphrase safe and do not upload them publicly.'],
+      'transfer.importMergeNote': ['导入采用合并模式，不会删除现有主机或密码。', 'Import uses merge mode and never deletes existing hosts or passwords.'],
+      'transfer.doExport': ['加密导出', 'Export encrypted'],
+      'transfer.doImport': ['导入并合并', 'Import and merge'],
+      'transfer.exported': ['已导出 {count} 台主机', 'Exported {count} host(s)'],
+      'transfer.imported': ['导入完成：新建 {created}，更新 {updated}，恢复密码 {passwords}', 'Import complete: {created} created, {updated} updated, {passwords} password(s) restored'],
+      'transfer.importWarnings': ['{count} 条记录未能导入，请查看提示。', '{count} record(s) could not be imported.'],
       'settings.vaultCount': ['{count} 台主机已保存密码', '{count} hosts have a stored password'],
       'settings.vaultNone': ['还没有保存任何密码', 'No passwords stored yet'],
       'settings.appearance': ['外观', 'Appearance'],
@@ -479,6 +505,16 @@ window.__ModuleLoader__.load({
       setTimeout(() => URL.revokeObjectURL(url), 1500)
     }
 
+    function downloadTextFile(name, text, type = 'application/json') {
+      const blob = new Blob([text], { type })
+      const url = URL.createObjectURL(blob)
+      const anchor = document.createElement('a')
+      anchor.href = url
+      anchor.download = name || 'dsh-ssh-manage-export.json'
+      anchor.click()
+      setTimeout(() => URL.revokeObjectURL(url), 1500)
+    }
+
     function readFileBase64(file) {
       return new Promise((resolve, reject) => {
         const reader = new FileReader()
@@ -5287,8 +5323,201 @@ window.__ModuleLoader__.load({
       )
     }
 
+    function TransferDialog({ model, mode, onClose }) {
+      const { t, notify, load, hosts } = model
+      const [passphrase, setPassphrase] = React.useState('')
+      const [confirmation, setConfirmation] = React.useState('')
+      const [file, setFile] = React.useState(null)
+      const [reading, setReading] = React.useState(false)
+      const [busy, setBusy] = React.useState(false)
+      const [error, setError] = React.useState('')
+      const busyRef = React.useRef(false)
+      const fileRef = React.useRef(null)
+
+      React.useEffect(() => {
+        const onKey = (event) => {
+          if (event.key !== 'Escape' || busyRef.current) return
+          event.preventDefault()
+          event.stopPropagation()
+          onClose()
+        }
+        document.addEventListener('keydown', onKey, true)
+        return () => document.removeEventListener('keydown', onKey, true)
+      }, [onClose])
+
+      async function pickFile(event) {
+        const picked = event.target.files?.[0]
+        event.target.value = ''
+        if (!picked) return
+        if (picked.size > 8 * 1024 * 1024) {
+          setError(t('transfer.fileTooLarge'))
+          setFile(null)
+          return
+        }
+        setReading(true)
+        setError('')
+        try {
+          const text = typeof picked.text === 'function'
+            ? await picked.text()
+            : await new Promise((resolve, reject) => {
+                const reader = new FileReader()
+                reader.onload = () => resolve(String(reader.result ?? ''))
+                reader.onerror = () => reject(reader.error ?? new Error('Cannot read file'))
+                reader.readAsText(picked)
+              })
+          const parsed = JSON.parse(text)
+          if (!parsed || parsed.format !== 'dsh-ssh-manage-export' || !Array.isArray(parsed.hosts)) {
+            throw new Error(t('transfer.invalidFile'))
+          }
+          setFile({ name: picked.name, data: parsed })
+        } catch (failure) {
+          setFile(null)
+          setError(errorMessage(failure))
+        } finally {
+          setReading(false)
+        }
+      }
+
+      async function submit() {
+        if (busyRef.current) return
+        if (passphrase.length < 8) {
+          setError(t('transfer.passphraseShort'))
+          return
+        }
+        if (mode === 'export' && passphrase !== confirmation) {
+          setError(t('transfer.passphraseMismatch'))
+          return
+        }
+        if (mode === 'import' && !file) {
+          setError(t('transfer.chooseFileFirst'))
+          return
+        }
+        busyRef.current = true
+        setBusy(true)
+        setError('')
+        try {
+          if (mode === 'export') {
+            const value = await callAction('data/export', { passphrase })
+            const stamp = new Date().toISOString().replace(/[-:]/g, '').slice(0, 15)
+            downloadTextFile(`dsh-ssh-manage-export-${stamp}.json`, JSON.stringify(value, null, 2))
+            notify(t('transfer.exported', { count: value?.hosts?.length ?? hosts.length }), 'success')
+          } else {
+            const value = await callAction('data/import', { export: file.data, passphrase })
+            const summary = t('transfer.imported', {
+              created: value?.created ?? 0,
+              updated: value?.updated ?? 0,
+              passwords: value?.passwords ?? 0,
+            })
+            if (Array.isArray(value?.errors) && value.errors.length > 0) {
+              notify(`${summary}；${t('transfer.importWarnings', { count: value.errors.length })}`, 'error')
+            } else {
+              notify(summary, 'success')
+            }
+            await load({ quiet: true })
+          }
+          onClose()
+        } catch (failure) {
+          setError(errorMessage(failure))
+        } finally {
+          busyRef.current = false
+          setBusy(false)
+        }
+      }
+
+      return h(
+        'div',
+        {
+          className: 'ssh-fileDialogScrim',
+          onMouseDown: () => {
+            if (!busyRef.current) onClose()
+          },
+        },
+        h(
+          'div',
+          {
+            className: 'ssh-fileDialog ssh-transferDialog',
+            role: 'dialog',
+            'aria-modal': 'true',
+            'aria-label': mode === 'export' ? t('transfer.exportTitle') : t('transfer.importTitle'),
+            onMouseDown: (event) => event.stopPropagation(),
+          },
+          h('div', { className: 'ssh-fileDialogTitle' }, mode === 'export' ? t('transfer.exportTitle') : t('transfer.importTitle')),
+          h(
+            'div',
+            { className: 'ssh-fileDialogBody' },
+            mode === 'export'
+              ? t('transfer.exportDesc', { count: hosts.length })
+              : t('transfer.importDesc'),
+          ),
+          mode === 'import'
+            ? h(
+                'div',
+                { className: 'ssh-transferFile' },
+                h('input', {
+                  ref: fileRef,
+                  type: 'file',
+                  accept: '.json,application/json',
+                  className: 'ssh-srOnly',
+                  onChange: (event) => void pickFile(event),
+                }),
+                h(
+                  Button,
+                  { size: 'sm', variant: 'ghost', onClick: () => fileRef.current?.click(), disabled: reading || busy },
+                  reading ? h(Spinner, { size: 12 }) : h(IconUpload, { size: 13 }),
+                  file ? file.name : t('transfer.chooseFile'),
+                ),
+                file ? h(Badge, { tone: 'ok' }, t('transfer.fileReady', { count: file.data.hosts.length })) : null,
+              )
+            : null,
+          h(TextInput, {
+            type: 'password',
+            value: passphrase,
+            onChange: setPassphrase,
+            placeholder: t('transfer.passphrase'),
+            autoFocus: true,
+            disabled: busy,
+            onKeyDown: (event) => {
+              if (event.key === 'Enter') void submit()
+            },
+          }),
+          mode === 'export'
+            ? h(TextInput, {
+                type: 'password',
+                value: confirmation,
+                onChange: setConfirmation,
+                placeholder: t('transfer.confirmPassphrase'),
+                disabled: busy,
+                onKeyDown: (event) => {
+                  if (event.key === 'Enter') void submit()
+                },
+              })
+            : null,
+          h('div', { className: 'ssh-sectionHint' }, t('transfer.passphraseHint')),
+          error ? h('div', { className: 'ssh-formError' }, h(IconAlert, { size: 13 }), h('span', null, error)) : null,
+          h(
+            'div',
+            { className: 'ssh-sectionHint ssh-revealWarning' },
+            h(IconAlert, { size: 12 }),
+            h('span', null, mode === 'export' ? t('transfer.exportWarning') : t('transfer.importMergeNote')),
+          ),
+          h(
+            'div',
+            { className: 'ssh-fileDialogActions' },
+            h(Button, { variant: 'ghost', size: 'sm', onClick: onClose, disabled: busy }, t('common.cancel')),
+            h(
+              Button,
+              { variant: 'primary', size: 'sm', onClick: () => void submit(), disabled: busy || reading },
+              busy ? h(Spinner, { size: 12 }) : null,
+              mode === 'export' ? t('transfer.doExport') : t('transfer.doImport'),
+            ),
+          ),
+        ),
+      )
+    }
+
     function SettingsTab({ model }) {
       const { t, snapshot, hosts, columns, setColumns, copyValue, load, refreshing } = model
+      const [transferMode, setTransferMode] = React.useState(null)
       const passwordCount = hosts.filter((host) => host.passwordConfigured).length
       const exists = snapshot?.exists === true
       return h(
@@ -5359,6 +5588,33 @@ window.__ModuleLoader__.load({
               h('span', null, `${passwordCount} / ${hosts.length}`),
             ),
           ),
+          h(
+            'section',
+            { className: 'ssh-card' },
+            h(
+              'div',
+              { className: 'ssh-cardHead' },
+              h('h3', null, t('settings.transfer')),
+              h(Badge, { tone: 'muted' }, t('settings.transferBadge')),
+            ),
+            h('p', { className: 'ssh-cardDesc' }, t('settings.transferDesc')),
+            h(
+              'div',
+              { className: 'ssh-cardActions' },
+              h(
+                Button,
+                { size: 'sm', variant: 'ghost', onClick: () => setTransferMode('export') },
+                h(IconDownload, { size: 13 }),
+                t('settings.export'),
+              ),
+              h(
+                Button,
+                { size: 'sm', variant: 'ghost', onClick: () => setTransferMode('import') },
+                h(IconUpload, { size: 13 }),
+                t('settings.import'),
+              ),
+            ),
+          ),
           h(
             'section',
             { className: 'ssh-card' },
@@ -5408,6 +5664,13 @@ window.__ModuleLoader__.load({
               h('span', null, t('settings.aboutTag')),
             ),
           ),
+          transferMode
+            ? h(TransferDialog, {
+                model,
+                mode: transferMode,
+                onClose: () => setTransferMode(null),
+              })
+            : null,
         ),
       )
     }
@@ -5705,6 +5968,8 @@ body.ssh-col-resizing,body.ssh-col-resizing *{cursor:col-resize!important;user-s
 .ssh-fileRow{display:grid;grid-template-columns:22px minmax(0,1fr) 90px auto;align-items:center;gap:8px;padding:0 10px;height:34px;border-bottom:.5px solid var(--ssh-border);font-size:12px}
 .ssh-fileActions{display:flex;align-items:center;gap:2px}
 .ssh-fileDialogScrim{position:absolute;inset:0;z-index:20;display:flex;align-items:center;justify-content:center;padding:20px;background:var(--dsw-alias-bg-mask-1,color-mix(in srgb,var(--ssh-text) 18%,transparent))}
+.ssh-transferDialog{width:min(460px,100%)}
+.ssh-transferFile{display:flex;align-items:center;gap:6px;flex-wrap:wrap}
 .ssh-fileDialog{width:min(360px,100%);padding:14px;border:.5px solid var(--ssh-border-strong);border-radius:12px;background:var(--ssh-layer-1);box-shadow:var(--ssh-shadow);display:flex;flex-direction:column;gap:10px}
 .ssh-fileDialogTitle{font-size:13px;font-weight:600;color:var(--ssh-text)}
 .ssh-fileDialogBody{font-size:12px;line-height:1.5;color:var(--ssh-text-2)}

package/index.js

@@ -6,6 +6,7 @@ import { resolveSshPaths, listSshHosts, saveSshHost, deleteSshHost } from './lib
 import { deleteMetadata, loadMetadata, updateMetadata } from './lib/metadata.js'
 import { batchExec, deleteRemotePath, downloadFile, execCommand, inspectHost, listRemoteFiles, makeRemoteDirectory, openPty, renameRemotePath, testConnection, uploadFile } from './lib/ssh-client.js'
 import { storagePaths } from './lib/storage.js'
+import { createExport, importExport } from './lib/transfer.js'
 import { getPassword, listPasswordAliases, removePassword, setPassword } from './lib/vault.js'
 
 const STATE_ROUTE = '/dsh-ssh-manage/state'
@@ -173,6 +174,15 @@ export async function runAction(paths, action, params = {}) {
       if (!password) throw new Error('No password is stored for this host')
       return { password }
     }
+    case 'data/export': {
+      if (typeof params.passphrase !== 'string' || params.passphrase.length === 0) throw new Error('Passphrase is required')
+      return await createExport(paths, params.passphrase)
+    }
+    case 'data/import': {
+      if (typeof params.passphrase !== 'string' || params.passphrase.length === 0) throw new Error('Passphrase is required')
+      const result = await importExport(paths, params.export, params.passphrase)
+      return { ...result, state: await state(paths) }
+    }
     case 'host/metadata': {
       const alias = requireString(params, 'host')
       await findHost(paths, alias)

package/lib/transfer.js

@@ -0,0 +1,202 @@
+import { createCipheriv, createDecipheriv, randomBytes, scryptSync } from 'node:crypto'
+import { listSshHosts, saveSshHost } from './ssh-config.js'
+import { loadMetadata, updateMetadata } from './metadata.js'
+import { loadVault, saveVault } from './vault.js'
+
+const FORMAT = 'dsh-ssh-manage-export'
+const VERSION = 1
+const ALGORITHM = 'aes-256-gcm'
+const KDF = 'scrypt'
+const KDF_N = 16384
+const KDF_R = 8
+const KDF_P = 1
+const KEY_BYTES = 32
+const SALT_BYTES = 16
+const IV_BYTES = 12
+const MAX_HOSTS = 500
+const MAX_METADATA = 1000
+const MAX_PASSWORDS = 1000
+const ALIAS_RE = /^[A-Za-z0-9][A-Za-z0-9_.@-]{0,63}$/
+
+function assertPassphrase(passphrase) {
+  if (typeof passphrase !== 'string' || passphrase.length < 8) {
+    throw new Error('Passphrase must be at least 8 characters')
+  }
+}
+
+function deriveKey(passphrase, salt) {
+  return scryptSync(Buffer.from(passphrase, 'utf8'), salt, KEY_BYTES, {
+    N: KDF_N,
+    r: KDF_R,
+    p: KDF_P,
+    maxmem: 64 * 1024 * 1024,
+  })
+}
+
+function encryptSecrets(passwords, passphrase) {
+  const salt = randomBytes(SALT_BYTES)
+  const iv = randomBytes(IV_BYTES)
+  const key = deriveKey(passphrase, salt)
+  const cipher = createCipheriv(ALGORITHM, key, iv)
+  const ciphertext = Buffer.concat([
+    cipher.update(JSON.stringify({ passwords }), 'utf8'),
+    cipher.final(),
+  ])
+  return {
+    version: VERSION,
+    algorithm: ALGORITHM,
+    kdf: KDF,
+    kdfN: KDF_N,
+    kdfR: KDF_R,
+    kdfP: KDF_P,
+    salt: salt.toString('base64'),
+    iv: iv.toString('base64'),
+    tag: cipher.getAuthTag().toString('base64'),
+    ciphertext: ciphertext.toString('base64'),
+  }
+}
+
+function decryptSecrets(payload, passphrase) {
+  if (!payload || typeof payload !== 'object' || payload.algorithm !== ALGORITHM || payload.kdf !== KDF) {
+    throw new Error('Unsupported export secrets format')
+  }
+  const n = Number(payload.kdfN)
+  const r = Number(payload.kdfR)
+  const p = Number(payload.kdfP)
+  if (!Number.isInteger(n) || !Number.isInteger(r) || !Number.isInteger(p) || n < 1024 || n > 65536 || r < 1 || r > 16 || p < 1 || p > 8) {
+    throw new Error('Unsupported export KDF parameters')
+  }
+  try {
+    const salt = Buffer.from(String(payload.salt ?? ''), 'base64')
+    const iv = Buffer.from(String(payload.iv ?? ''), 'base64')
+    const tag = Buffer.from(String(payload.tag ?? ''), 'base64')
+    if (salt.length !== SALT_BYTES || iv.length !== IV_BYTES || tag.length === 0) throw new Error('bad envelope')
+    const key = scryptSync(Buffer.from(passphrase, 'utf8'), salt, KEY_BYTES, {
+      N: n,
+      r,
+      p,
+      maxmem: 64 * 1024 * 1024,
+    })
+    const decipher = createDecipheriv(ALGORITHM, key, iv)
+    decipher.setAuthTag(tag)
+    const plaintext = Buffer.concat([
+      decipher.update(Buffer.from(String(payload.ciphertext ?? ''), 'base64')),
+      decipher.final(),
+    ]).toString('utf8')
+    const parsed = JSON.parse(plaintext)
+    if (!parsed || typeof parsed !== 'object' || !parsed.passwords || typeof parsed.passwords !== 'object' || Array.isArray(parsed.passwords)) {
+      throw new Error('bad payload')
+    }
+    return parsed.passwords
+  } catch {
+    throw new Error('Cannot decrypt export: wrong passphrase or corrupted file')
+  }
+}
+
+function hostRecord(host) {
+  return {
+    host: String(host?.host ?? ''),
+    aliases: Array.isArray(host?.aliases) ? host.aliases.map(String) : [],
+    hostname: String(host?.hostname ?? ''),
+    user: String(host?.user ?? ''),
+    port: String(host?.port ?? ''),
+    identityFile: String(host?.identityFile ?? ''),
+    proxyJump: String(host?.proxyJump ?? ''),
+    forwardAgent: host?.forwardAgent === true,
+  }
+}
+
+export async function createExport(paths, passphrase) {
+  assertPassphrase(passphrase)
+  const { hosts } = await listSshHosts(paths)
+  const metadata = await loadMetadata(paths)
+  const vault = await loadVault(paths)
+  const passwords = {}
+  for (const [alias, password] of Object.entries(vault.records)) {
+    if (ALIAS_RE.test(alias) && typeof password === 'string' && password.length > 0) passwords[alias] = password
+  }
+  return {
+    format: FORMAT,
+    version: VERSION,
+    exportedAt: new Date().toISOString(),
+    hosts: hosts.map(hostRecord),
+    metadata: metadata.entries,
+    secrets: encryptSecrets(passwords, passphrase),
+  }
+}
+
+function validateEnvelope(exported) {
+  if (!exported || typeof exported !== 'object' || Array.isArray(exported)) throw new Error('Invalid export file')
+  if (exported.format !== FORMAT) throw new Error('Not a dsh-ssh-manage export file')
+  if (exported.version !== VERSION) throw new Error(`Unsupported export version: ${String(exported.version)}`)
+  if (!Array.isArray(exported.hosts) || exported.hosts.length > MAX_HOSTS) throw new Error('Invalid or too many hosts in export')
+  if (!exported.metadata || typeof exported.metadata !== 'object' || Array.isArray(exported.metadata) || Object.keys(exported.metadata).length > MAX_METADATA) {
+    throw new Error('Invalid metadata in export')
+  }
+  return {
+    hosts: exported.hosts,
+    metadata: exported.metadata,
+    secrets: exported.secrets,
+  }
+}
+
+function readableError(error) {
+  return error instanceof Error ? error.message : String(error)
+}
+
+/**
+ * Merge an export into the local config/metadata/vault. Existing hosts with the
+ * same alias are updated in place; nothing is deleted. Per-host failures are
+ * returned so a single malformed entry cannot abort the whole restore.
+ */
+export async function importExport(paths, exported, passphrase) {
+  assertPassphrase(passphrase)
+  const envelope = validateEnvelope(exported)
+  if (!envelope.secrets) throw new Error('This export does not contain encrypted passwords')
+  const passwords = decryptSecrets(envelope.secrets, passphrase)
+  if (Object.keys(passwords).length > MAX_PASSWORDS) throw new Error('Too many passwords in export')
+
+  const before = await listSshHosts(paths)
+  const existing = new Set(before.hosts.map((host) => host.host))
+  let created = 0
+  let updated = 0
+  const errors = []
+
+  for (const raw of envelope.hosts) {
+    try {
+      const host = hostRecord(raw)
+      if (!ALIAS_RE.test(host.host)) throw new Error('Invalid SSH host alias')
+      const exists = existing.has(host.host)
+      await saveSshHost({ paths, host, originalHost: exists ? host.host : null })
+      if (exists) updated += 1
+      else created += 1
+    } catch (error) {
+      errors.push(`${String(raw?.host ?? '?')}: ${readableError(error)}`)
+    }
+  }
+
+  let metadataCount = 0
+  for (const [alias, data] of Object.entries(envelope.metadata)) {
+    if (!ALIAS_RE.test(alias)) continue
+    try {
+      await updateMetadata(paths, alias, data)
+      metadataCount += 1
+    } catch (error) {
+      errors.push(`metadata ${alias}: ${readableError(error)}`)
+    }
+  }
+
+  let passwordCount = 0
+  const currentVault = await loadVault(paths)
+  const merged = { ...currentVault.records }
+  for (const [alias, password] of Object.entries(passwords)) {
+    if (!ALIAS_RE.test(alias) || typeof password !== 'string' || password.length === 0) continue
+    merged[alias] = password
+    passwordCount += 1
+  }
+  if (passwordCount > 0) await saveVault(paths, merged)
+
+  return { created, updated, metadata: metadataCount, passwords: passwordCount, errors }
+}
+
+export const __test = { encryptSecrets, decryptSecrets, hostRecord }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-ssh-manage",
-  "version": "0.3.5",
+  "version": "0.3.6",
   "description": "A DSH sidebar plugin for managing SSH host profiles with a real interactive PTY terminal.",
   "license": "MIT",
   "private": false,