dsh-ssh-hub 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (133) hide show
  1. package/LICENSE +202 -0
  2. package/README.md +271 -2
  3. package/cordis.patch.yml +16 -0
  4. package/icon.svg +3 -0
  5. package/lib/client.js +13975 -0
  6. package/lib/index.js +6908 -0
  7. package/lib/types/activity/history.d.ts +50 -0
  8. package/lib/types/alerting/notify.d.ts +89 -0
  9. package/lib/types/alerting/prompt-summary.d.ts +28 -0
  10. package/lib/types/alerting/rules.d.ts +135 -0
  11. package/lib/types/alerting/tools.d.ts +30 -0
  12. package/lib/types/audit/audit-log.d.ts +84 -0
  13. package/lib/types/audit/recorder.d.ts +50 -0
  14. package/lib/types/client/api.d.ts +222 -0
  15. package/lib/types/client/index.d.ts +45 -0
  16. package/lib/types/client/locales.d.ts +319 -0
  17. package/lib/types/client/native-panel.d.ts +70 -0
  18. package/lib/types/client/panel/ClusterTab.d.ts +7 -0
  19. package/lib/types/client/panel/DeployTab.d.ts +10 -0
  20. package/lib/types/client/panel/FleetTab.d.ts +10 -0
  21. package/lib/types/client/panel/HostFormDialog.d.ts +12 -0
  22. package/lib/types/client/panel/HostsTab.d.ts +25 -0
  23. package/lib/types/client/panel/LogsTab.d.ts +10 -0
  24. package/lib/types/client/panel/SshPanel.d.ts +14 -0
  25. package/lib/types/client/panel/TerminalTab.d.ts +27 -0
  26. package/lib/types/client/panel/TransferTab.d.ts +7 -0
  27. package/lib/types/client/panel/TunnelEditDialog.d.ts +15 -0
  28. package/lib/types/client/panel/TunnelsTab.d.ts +27 -0
  29. package/lib/types/client/panel/controller.d.ts +253 -0
  30. package/lib/types/client/panel/helpers.d.ts +45 -0
  31. package/lib/types/client/panel/tabs.d.ts +62 -0
  32. package/lib/types/client/panel/xterm.css.d.ts +2 -0
  33. package/lib/types/client/settings-binding.d.ts +71 -0
  34. package/lib/types/deploy/orchestrator.d.ts +158 -0
  35. package/lib/types/deploy/tools.d.ts +14 -0
  36. package/lib/types/dsh-home.d.ts +16 -0
  37. package/lib/types/engine/cluster.d.ts +19 -0
  38. package/lib/types/engine/connection-pool.d.ts +183 -0
  39. package/lib/types/engine/proxy-command.d.ts +36 -0
  40. package/lib/types/engine/pty.d.ts +32 -0
  41. package/lib/types/engine/sftp.d.ts +20 -0
  42. package/lib/types/engine/terminal-sessions.d.ts +67 -0
  43. package/lib/types/engine/tunnel-discovery.d.ts +89 -0
  44. package/lib/types/engine/tunnel-remarks.d.ts +49 -0
  45. package/lib/types/engine/tunnel.d.ts +76 -0
  46. package/lib/types/engine.d.ts +103 -0
  47. package/lib/types/http.d.ts +59 -0
  48. package/lib/types/index.d.ts +128 -0
  49. package/lib/types/inspect/checks.d.ts +118 -0
  50. package/lib/types/inspect/inspection.d.ts +111 -0
  51. package/lib/types/inspect/tools.d.ts +50 -0
  52. package/lib/types/logs/search.d.ts +131 -0
  53. package/lib/types/logs/tools.d.ts +6 -0
  54. package/lib/types/loopback.d.ts +64 -0
  55. package/lib/types/monitor/loop.d.ts +133 -0
  56. package/lib/types/monitor/metrics.d.ts +151 -0
  57. package/lib/types/mount-once.d.ts +55 -0
  58. package/lib/types/protocol.d.ts +524 -0
  59. package/lib/types/routes.d.ts +82 -0
  60. package/lib/types/security/known-hosts.d.ts +153 -0
  61. package/lib/types/security/master-secret.d.ts +157 -0
  62. package/lib/types/security/redact.d.ts +44 -0
  63. package/lib/types/security/secrets.d.ts +70 -0
  64. package/lib/types/ssh-config.d.ts +42 -0
  65. package/lib/types/store.d.ts +183 -0
  66. package/lib/types/tool-surface.d.ts +72 -0
  67. package/lib/types/tools.d.ts +56 -0
  68. package/locale/en.json +6 -0
  69. package/locale/zh.json +6 -0
  70. package/package.json +126 -6
  71. package/src/activity/history.ts +117 -0
  72. package/src/alerting/notify.ts +212 -0
  73. package/src/alerting/prompt-summary.ts +71 -0
  74. package/src/alerting/rules.ts +281 -0
  75. package/src/alerting/tools.ts +263 -0
  76. package/src/audit/audit-log.ts +199 -0
  77. package/src/audit/recorder.ts +73 -0
  78. package/src/client/api.ts +782 -0
  79. package/src/client/css-modules.d.ts +5 -0
  80. package/src/client/index.ts +150 -0
  81. package/src/client/locales.ts +654 -0
  82. package/src/client/native-panel.tsx +141 -0
  83. package/src/client/panel/ClusterTab.tsx +141 -0
  84. package/src/client/panel/DeployTab.tsx +314 -0
  85. package/src/client/panel/FleetTab.tsx +494 -0
  86. package/src/client/panel/HostFormDialog.tsx +289 -0
  87. package/src/client/panel/HostsTab.tsx +395 -0
  88. package/src/client/panel/LogsTab.tsx +208 -0
  89. package/src/client/panel/SshPanel.tsx +105 -0
  90. package/src/client/panel/TerminalTab.tsx +550 -0
  91. package/src/client/panel/TransferTab.tsx +238 -0
  92. package/src/client/panel/TunnelEditDialog.tsx +174 -0
  93. package/src/client/panel/TunnelsTab.tsx +328 -0
  94. package/src/client/panel/controller.ts +507 -0
  95. package/src/client/panel/helpers.ts +84 -0
  96. package/src/client/panel/panel.module.css +1734 -0
  97. package/src/client/panel/tabs.ts +52 -0
  98. package/src/client/panel/xterm.css.ts +2 -0
  99. package/src/client/settings-binding.ts +184 -0
  100. package/src/deploy/orchestrator.ts +326 -0
  101. package/src/deploy/tools.ts +225 -0
  102. package/src/dsh-home.ts +42 -0
  103. package/src/engine/cluster.ts +60 -0
  104. package/src/engine/connection-pool.ts +721 -0
  105. package/src/engine/proxy-command.ts +248 -0
  106. package/src/engine/pty.ts +78 -0
  107. package/src/engine/sftp.ts +229 -0
  108. package/src/engine/terminal-sessions.ts +280 -0
  109. package/src/engine/tunnel-discovery.ts +353 -0
  110. package/src/engine/tunnel-remarks.ts +120 -0
  111. package/src/engine/tunnel.ts +300 -0
  112. package/src/engine.ts +195 -0
  113. package/src/http.ts +127 -0
  114. package/src/index.ts +690 -0
  115. package/src/inspect/checks.ts +251 -0
  116. package/src/inspect/inspection.ts +321 -0
  117. package/src/inspect/tools.ts +366 -0
  118. package/src/logs/search.ts +251 -0
  119. package/src/logs/tools.ts +160 -0
  120. package/src/loopback.ts +119 -0
  121. package/src/monitor/loop.ts +265 -0
  122. package/src/monitor/metrics.ts +333 -0
  123. package/src/mount-once.ts +142 -0
  124. package/src/protocol.ts +534 -0
  125. package/src/routes.ts +998 -0
  126. package/src/security/known-hosts.ts +342 -0
  127. package/src/security/master-secret.ts +334 -0
  128. package/src/security/redact.ts +119 -0
  129. package/src/security/secrets.ts +152 -0
  130. package/src/ssh-config.ts +182 -0
  131. package/src/store.ts +757 -0
  132. package/src/tool-surface.ts +96 -0
  133. package/src/tools.ts +550 -0
package/src/store.ts ADDED
@@ -0,0 +1,757 @@
1
+ /**
2
+ * Host config store: one JSON file (`$DSH_HOME/dsh-ssh.json`, defaulting
3
+ * to `~/.dsh`) holding every
4
+ * SSH host entry, written atomically (tmp + rename). Also parses the user's
5
+ * standard `~/.ssh/config` for one-shot import.
6
+ *
7
+ * Secrets (passwords, passphrases) are protected by a `SecretProtector`
8
+ * when one is configured: the stored value is then an encrypted envelope
9
+ * instead of plaintext. Without a protector the store keeps the base
10
+ * plugin's plaintext behaviour, so an existing installation is never
11
+ * locked out by enabling encryption.
12
+ */
13
+
14
+ import { existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs'
15
+ import { homedir } from 'node:os'
16
+ import { dirname, join, resolve } from 'node:path'
17
+ import { dshHome } from './dsh-home.ts'
18
+ import type { HostPayload, ImportResult, ImportSkipBlock, ImportSkipReason, LocalConfigHost, SshHostEntry, SshHostSummary } from './protocol.ts'
19
+ import { readSshConfigBlocks } from './ssh-config.ts'
20
+ import { isSealed } from './security/secrets.ts'
21
+
22
+ /**
23
+ * Encrypts and decrypts the secrets stored alongside a host entry.
24
+ *
25
+ * A protector is optional on purpose: with no master secret configured the
26
+ * store writes plaintext exactly as the base plugin did, so switching
27
+ * encryption on is a deliberate act by the operator.
28
+ */
29
+ export interface SecretProtector {
30
+ /** Encrypt one secret for storage. */
31
+ seal(plaintext: string): unknown
32
+ /** Decrypt a stored secret; returns undefined when it is not a sealed value. */
33
+ open(stored: unknown): string | undefined
34
+ }
35
+
36
+ /** File format version. */
37
+ const FORMAT_VERSION = 1
38
+
39
+ /** Store file location: $DSH_HOME/dsh-ssh.json (defaults to ~/.dsh). */
40
+ export function storePath(): string {
41
+ return join(dshHome(), 'dsh-ssh.json')
42
+ }
43
+
44
+ /** The user's standard OpenSSH config path. */
45
+ export function sshConfigPath(): string {
46
+ return join(homedir(), '.ssh', 'config')
47
+ }
48
+
49
+ interface StoreFile {
50
+ version: number
51
+ hosts: SshHostEntry[]
52
+ }
53
+
54
+ /** Validate the wire shape of a host payload; returns a message or undefined. */
55
+ export function validateHostPayload(payload: unknown): string | undefined {
56
+ if (typeof payload !== 'object' || payload === null) return 'body must be a JSON object'
57
+ const p = payload as Record<string, unknown>
58
+ if (typeof p.host !== 'string' || p.host.trim() === '') return 'host is required'
59
+ if (typeof p.user !== 'string' || p.user.trim() === '') return 'user is required'
60
+ const auth = p.auth as Record<string, unknown> | undefined
61
+ if (auth !== undefined) {
62
+ if (typeof auth !== 'object' || auth === null) return 'auth must be an object'
63
+ if (auth.kind !== 'key' && auth.kind !== 'password' && auth.kind !== 'agent' && auth.kind !== 'none') {
64
+ return 'auth.kind must be key, password, agent or none'
65
+ }
66
+ if (auth.keyPaths !== undefined
67
+ && (!Array.isArray(auth.keyPaths) || auth.keyPaths.some(entry => typeof entry !== 'string' || entry.trim() === ''))) {
68
+ return 'auth.keyPaths must be an array of non-empty strings'
69
+ }
70
+ if (auth.kind === 'key' && (typeof auth.keyPath !== 'string' || auth.keyPath.trim() === '')) {
71
+ return 'auth.keyPath is required for key auth'
72
+ }
73
+ if (auth.kind === 'password' && auth.password !== undefined && typeof auth.password !== 'string') {
74
+ return 'auth.password must be a string when provided'
75
+ }
76
+ if (auth.kind === 'agent' && auth.agentPath !== undefined && typeof auth.agentPath !== 'string') {
77
+ return 'auth.agentPath must be a string when provided'
78
+ }
79
+ }
80
+ if (p.port !== undefined && (typeof p.port !== 'number' || !Number.isInteger(p.port) || p.port < 1 || p.port > 65535)) {
81
+ return 'port must be an integer in 1..65535'
82
+ }
83
+ if (p.proxyJump !== undefined && (!Array.isArray(p.proxyJump) || p.proxyJump.some(x => typeof x !== 'string' || x === ''))) {
84
+ return 'proxyJump must be an array of alias strings'
85
+ }
86
+ if (p.proxyCommand !== undefined && typeof p.proxyCommand !== 'string') {
87
+ return 'proxyCommand must be a string when provided'
88
+ }
89
+ // OpenSSH resolves ProxyCommand and ProxyJump by "whichever appears first in
90
+ // the config"; a stored entry has no order, so the combination is rejected
91
+ // instead of silently picking one transport.
92
+ const proxyCommand = typeof p.proxyCommand === 'string' ? normalizeProxyCommand(p.proxyCommand) : undefined
93
+ const proxyJump = Array.isArray(p.proxyJump) ? p.proxyJump as string[] : []
94
+ if (proxyCommand !== undefined && proxyJump.length > 0) {
95
+ return 'proxyCommand and proxyJump cannot be combined — pick one transport per host'
96
+ }
97
+ if (p.tags !== undefined && (!Array.isArray(p.tags) || p.tags.some(x => typeof x !== 'string'))) {
98
+ return 'tags must be an array of strings'
99
+ }
100
+ if (p.forwardAgent !== undefined && typeof p.forwardAgent !== 'boolean') {
101
+ return 'forwardAgent must be a boolean'
102
+ }
103
+ return undefined
104
+ }
105
+
106
+ /** Alias grammar: letters/digits plus dots, hyphens, underscores (IP/domain aliases included). */
107
+ const ALIAS_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/
108
+
109
+ /** Validate an alias for creation. */
110
+ export function validateAlias(alias: string): string | undefined {
111
+ if (!ALIAS_RE.test(alias)) return 'alias must be letters, digits, dots, hyphens or underscores'
112
+ return undefined
113
+ }
114
+
115
+ /**
116
+ * The host store. Pure file I/O — no cordis dependency, unit-testable.
117
+ */
118
+ export class HostStore {
119
+ /** The JSON file path. */
120
+ readonly path: string
121
+ /** Optional override of the ~/.ssh/config path (tests). */
122
+ private readonly sshConfigOverride: string | undefined
123
+ /** Optional encryptor for the stored secrets. */
124
+ private readonly protector: SecretProtector | undefined
125
+
126
+ /**
127
+ * @param path - store file path (defaults to the standard location).
128
+ * @param sshConfigOverride - ssh config path override (tests only).
129
+ * @param protector - encryptor for stored secrets (tests / production).
130
+ */
131
+ constructor(path?: string, sshConfigOverride?: string, protector?: SecretProtector) {
132
+ this.path = resolve(path ?? storePath())
133
+ this.sshConfigOverride = sshConfigOverride
134
+ this.protector = protector
135
+ }
136
+
137
+ /** Load all entries (empty store when the file is absent). */
138
+ list(): SshHostEntry[] {
139
+ const file = this.load()
140
+ // The file holds the secrets as stored (sealed or plaintext); the
141
+ // in-memory shape always carries plaintext, because that is what the
142
+ // SSH layer needs.
143
+ return file.hosts.map(entry => this.decryptEntry(entry))
144
+ }
145
+
146
+ /** Find one entry by alias. */
147
+ find(alias: string): SshHostEntry | undefined {
148
+ return this.list().find(entry => entry.alias === alias)
149
+ }
150
+
151
+ /**
152
+ * Decrypt one stored entry's secrets.
153
+ *
154
+ * A value that is not a sealed envelope is passed through unchanged, so
155
+ * a store written before encryption was enabled keeps working.
156
+ *
157
+ * @param entry - the stored entry.
158
+ * @returns the entry with plaintext secrets.
159
+ */
160
+ private decryptEntry(entry: SshHostEntry): SshHostEntry {
161
+ if (this.protector === undefined) return entry
162
+ const password = this.protector.open(entry.auth.password)
163
+ const passphrase = this.protector.open(entry.auth.passphrase)
164
+ if (password === undefined && passphrase === undefined) {
165
+ // A sealed value the protector could not open means the master key is
166
+ // missing or wrong. Dropping it is the honest outcome: handing the
167
+ // envelope object to the SSH layer produces "no authentication methods"
168
+ // and hides the real cause, while keeping it would look like a password.
169
+ return {
170
+ ...entry,
171
+ auth: {
172
+ ...entry.auth,
173
+ password: isSealed(entry.auth.password) ? undefined : entry.auth.password,
174
+ passphrase: isSealed(entry.auth.passphrase) ? undefined : entry.auth.passphrase,
175
+ },
176
+ }
177
+ }
178
+ return {
179
+ ...entry,
180
+ auth: {
181
+ ...entry.auth,
182
+ ...(password !== undefined ? { password } : {}),
183
+ ...(passphrase !== undefined ? { passphrase } : {}),
184
+ },
185
+ }
186
+ }
187
+
188
+ /**
189
+ * Encrypt one entry's secrets for storage.
190
+ *
191
+ * @param entry - the entry with plaintext secrets.
192
+ * @returns the entry as it is written to disk.
193
+ */
194
+ private encryptEntry(entry: SshHostEntry): SshHostEntry {
195
+ if (this.protector === undefined) return entry
196
+ const password = entry.auth.password
197
+ const passphrase = entry.auth.passphrase
198
+ if (password === undefined && passphrase === undefined) return entry
199
+ return {
200
+ ...entry,
201
+ auth: {
202
+ ...entry.auth,
203
+ ...(password !== undefined ? { password: this.protector.seal(password) as string } : {}),
204
+ ...(passphrase !== undefined ? { passphrase: this.protector.seal(passphrase) as string } : {}),
205
+ },
206
+ }
207
+ }
208
+
209
+ /** Secret-free projection for the browser and agent surfaces. */
210
+ summarize(entry: SshHostEntry): SshHostSummary {
211
+ let keyReady = true
212
+ if (entry.auth.kind === 'key') {
213
+ // One usable candidate is enough: OpenSSH tries the list in order and
214
+ // stops at the first key that authenticates.
215
+ const candidates = keyCandidates(entry)
216
+ keyReady = candidates.some(path => existsSync(expandHome(path)))
217
+ } else if (entry.auth.kind === 'agent') {
218
+ keyReady = false
219
+ }
220
+ return {
221
+ alias: entry.alias,
222
+ host: entry.host,
223
+ port: entry.port,
224
+ user: entry.user,
225
+ auth: entry.auth.kind,
226
+ keyReady,
227
+ proxyJump: [...entry.proxyJump],
228
+ ...(entry.proxyCommand !== undefined ? { proxyCommand: entry.proxyCommand } : {}),
229
+ // Optional fields are spread conditionally: the tool bridge rejects
230
+ // undefined-valued properties as non-lossless JSON.
231
+ ...(entry.description !== undefined ? { description: entry.description } : {}),
232
+ ...(entry.environment !== undefined ? { environment: entry.environment } : {}),
233
+ tags: [...entry.tags],
234
+ ...(entry.location !== undefined ? { location: entry.location } : {}),
235
+ // Always a definite boolean, unlike the conditional optional fields:
236
+ // the tool bridge rejects undefined-valued JSON properties.
237
+ forwardAgent: entry.forwardAgent === true,
238
+ createdAt: entry.createdAt,
239
+ updatedAt: entry.updatedAt,
240
+ }
241
+ }
242
+
243
+ /** Create one entry. Throws on alias collision or invalid payload. */
244
+ create(payload: HostPayload): SshHostEntry {
245
+ const alias = payload.alias?.trim()
246
+ if (!alias) throw new Error('alias is required')
247
+ const aliasError = validateAlias(alias)
248
+ if (aliasError !== undefined) throw new Error(aliasError)
249
+ const bodyError = validateHostPayload(payload)
250
+ if (bodyError !== undefined) throw new Error(bodyError)
251
+ if (payload.auth === undefined) throw new Error('auth is required')
252
+ const file = this.load()
253
+ if (file.hosts.some(entry => entry.alias === alias)) throw new Error(`alias '${alias}' already exists`)
254
+ const now = Date.now()
255
+ const entry: SshHostEntry = {
256
+ alias,
257
+ host: payload.host.trim(),
258
+ port: payload.port ?? 22,
259
+ user: payload.user.trim(),
260
+ auth: {
261
+ kind: payload.auth.kind,
262
+ keyPath: payload.auth.kind === 'key' ? expandHome(payload.auth.keyPath?.trim() ?? '') : undefined,
263
+ keyPaths: payload.auth.kind === 'key' && payload.auth.keyPaths !== undefined
264
+ ? payload.auth.keyPaths.map(path => expandHome(path.trim())).filter(path => path !== '')
265
+ : undefined,
266
+ passphrase: payload.auth.kind === 'key' ? payload.auth.passphrase ?? undefined : undefined,
267
+ password: payload.auth.kind === 'password' ? payload.auth.password : undefined,
268
+ agentPath: payload.auth.kind === 'agent' ? normalizeAgentPath(payload.auth.agentPath) : undefined,
269
+ },
270
+ proxyJump: [...(payload.proxyJump ?? [])],
271
+ proxyCommand: normalizeProxyCommand(payload.proxyCommand),
272
+ description: payload.description?.trim() || undefined,
273
+ environment: payload.environment?.trim() || undefined,
274
+ tags: [...(payload.tags ?? [])].map(tag => tag.trim()).filter(tag => tag !== ''),
275
+ location: payload.location?.trim() || undefined,
276
+ // Stored only when enabled, so a store file written without agent
277
+ // forwarding stays byte-identical to the pre-feature format.
278
+ forwardAgent: payload.forwardAgent === true ? true : undefined,
279
+ createdAt: now,
280
+ updatedAt: now,
281
+ }
282
+ file.hosts.push(this.encryptEntry(entry))
283
+ this.save(file)
284
+ return entry
285
+ }
286
+
287
+ /** Update the fields present in `patch`; unknown aliases throw. */
288
+ update(alias: string, patch: Partial<HostPayload>): SshHostEntry {
289
+ const file = this.load()
290
+ const stored = file.hosts.find(candidate => candidate.alias === alias)
291
+ if (stored === undefined) throw new Error(`alias '${alias}' not found`)
292
+ // Patch a decrypted copy: the stored entry may hold sealed secrets, and
293
+ // mutating it in place would mix plaintext and ciphertext.
294
+ const entry = this.decryptEntry(stored)
295
+ // Partial-patch validation: only the present fields are checked (a
296
+ // caller may update just tags without resending host/user).
297
+ if (patch.host !== undefined && (typeof patch.host !== 'string' || patch.host.trim() === '')) {
298
+ throw new Error('host is required')
299
+ }
300
+ if (patch.user !== undefined && (typeof patch.user !== 'string' || patch.user.trim() === '')) {
301
+ throw new Error('user is required')
302
+ }
303
+ if (patch.port !== undefined && (typeof patch.port !== 'number' || !Number.isInteger(patch.port) || patch.port < 1 || patch.port > 65535)) {
304
+ throw new Error('port must be an integer in 1..65535')
305
+ }
306
+ if (patch.proxyJump !== undefined && (!Array.isArray(patch.proxyJump) || patch.proxyJump.some(x => typeof x !== 'string' || x === ''))) {
307
+ throw new Error('proxyJump must be an array of alias strings')
308
+ }
309
+ if (patch.proxyCommand !== undefined && typeof patch.proxyCommand !== 'string') {
310
+ throw new Error('proxyCommand must be a string when provided')
311
+ }
312
+ if (patch.forwardAgent !== undefined && typeof patch.forwardAgent !== 'boolean') {
313
+ throw new Error('forwardAgent must be a boolean')
314
+ }
315
+ // The mutual exclusion is checked on the MERGED view: a patch that only
316
+ // adds one transport must not slip past a stored value of the other.
317
+ const mergedProxyCommand = patch.proxyCommand !== undefined
318
+ ? normalizeProxyCommand(patch.proxyCommand)
319
+ : entry.proxyCommand
320
+ if (mergedProxyCommand !== undefined && (patch.proxyJump ?? entry.proxyJump).length > 0) {
321
+ throw new Error('proxyCommand and proxyJump cannot be combined — pick one transport per host')
322
+ }
323
+ if (patch.tags !== undefined && (!Array.isArray(patch.tags) || patch.tags.some(x => typeof x !== 'string'))) {
324
+ throw new Error('tags must be an array of strings')
325
+ }
326
+ if (patch.host !== undefined) entry.host = patch.host.trim()
327
+ if (patch.port !== undefined) entry.port = patch.port
328
+ if (patch.user !== undefined) entry.user = patch.user.trim()
329
+ if (patch.auth !== undefined) {
330
+ const auth = patch.auth
331
+ if (auth.kind !== 'key' && auth.kind !== 'password' && auth.kind !== 'agent' && auth.kind !== 'none') {
332
+ throw new Error('auth.kind must be key, password, agent or none')
333
+ }
334
+ if (auth.keyPaths !== undefined
335
+ && (!Array.isArray(auth.keyPaths) || auth.keyPaths.some(entry => typeof entry !== 'string' || entry.trim() === ''))) {
336
+ throw new Error('auth.keyPaths must be an array of non-empty strings')
337
+ }
338
+ if (auth.kind === 'key' && (typeof auth.keyPath !== 'string' || auth.keyPath.trim() === '')) {
339
+ throw new Error('auth.keyPath is required for key auth')
340
+ }
341
+ if (auth.kind === 'password' && auth.password !== undefined && typeof auth.password !== 'string') {
342
+ throw new Error('auth.password must be a string when provided')
343
+ }
344
+ if (auth.kind === 'agent' && auth.agentPath !== undefined && typeof auth.agentPath !== 'string') {
345
+ throw new Error('auth.agentPath must be a string when provided')
346
+ }
347
+ // A changed key path with no passphrase means the new key has none;
348
+ // only keep the old passphrase when the key path is unchanged.
349
+ const keyChanged = auth.kind === 'key'
350
+ && auth.keyPath !== undefined
351
+ && expandHome(auth.keyPath.trim()) !== entry.auth.keyPath
352
+ entry.auth = {
353
+ kind: auth.kind,
354
+ keyPath: auth.kind === 'key' ? expandHome(auth.keyPath?.trim() ?? '') : undefined,
355
+ keyPaths: auth.kind === 'key'
356
+ ? (auth.keyPaths !== undefined
357
+ ? auth.keyPaths.map(path => expandHome(path.trim())).filter(path => path !== '')
358
+ : (keyChanged ? undefined : entry.auth.keyPaths))
359
+ : undefined,
360
+ passphrase: auth.kind === 'key'
361
+ ? (auth.passphrase !== undefined ? auth.passphrase : (keyChanged ? undefined : entry.auth.passphrase))
362
+ : undefined,
363
+ password: auth.kind === 'password' ? auth.password : undefined,
364
+ agentPath: auth.kind === 'agent'
365
+ ? (auth.agentPath !== undefined ? normalizeAgentPath(auth.agentPath) : entry.auth.agentPath)
366
+ : undefined,
367
+ }
368
+ }
369
+ if (patch.proxyJump !== undefined) entry.proxyJump = [...patch.proxyJump]
370
+ if (patch.proxyCommand !== undefined) entry.proxyCommand = mergedProxyCommand
371
+ if (patch.description !== undefined) entry.description = patch.description.trim() || undefined
372
+ if (patch.environment !== undefined) entry.environment = patch.environment.trim() || undefined
373
+ if (patch.tags !== undefined) entry.tags = [...patch.tags].map(tag => tag.trim()).filter(tag => tag !== '')
374
+ if (patch.location !== undefined) entry.location = patch.location.trim() || undefined
375
+ // PATCH semantics: an omitted key keeps the stored value, false clears it.
376
+ if (patch.forwardAgent !== undefined) entry.forwardAgent = patch.forwardAgent === true ? true : undefined
377
+ entry.updatedAt = Date.now()
378
+ // Write the encrypted copy back over the stored one.
379
+ const index = file.hosts.findIndex(candidate => candidate.alias === alias)
380
+ file.hosts[index] = this.encryptEntry(entry)
381
+ this.save(file)
382
+ return entry
383
+ }
384
+
385
+ /** Remove one entry. */
386
+ delete(alias: string): void {
387
+ const file = this.load()
388
+ const index = file.hosts.findIndex(candidate => candidate.alias === alias)
389
+ if (index < 0) throw new Error(`alias '${alias}' not found`)
390
+ file.hosts.splice(index, 1)
391
+ this.save(file)
392
+ }
393
+
394
+ /**
395
+ * Import hosts from `~/.ssh/config`: Host blocks with a single non-wildcard
396
+ * pattern become entries (a missing HostName falls back to the pattern
397
+ * itself; key auth via IdentityFile; jump hosts via ProxyJump; ProxyCommand
398
+ * kept verbatim). `Include` files are expanded, and `Match` blocks,
399
+ * wildcard patterns, and aliases that already exist are skipped with a
400
+ * reason instead of silently disappearing.
401
+ * @returns import statistics.
402
+ */
403
+ importFromSshConfig(): ImportResult {
404
+ // Per-run statistics: a later import must not report earlier runs' skips.
405
+ this.skippedBlocks = []
406
+ const configPath = this.sshConfigOverride ?? sshConfigPath()
407
+ if (!existsSync(configPath)) return { parsed: 0, added: 0, updated: 0, skipped: 0, skippedBlocks: [] }
408
+ const { blocks, skipped } = readSshConfigBlocks(configPath)
409
+ this.skippedBlocks = [...skipped]
410
+ const skip = (name: string, reason: ImportSkipReason): void => {
411
+ if (name === '') return
412
+ if (this.skippedBlocks.some(block => block.name === name)) return
413
+ this.skippedBlocks.push({ name, reason })
414
+ }
415
+ let added = 0
416
+ let updated = 0
417
+ for (const block of blocks) {
418
+ const pattern = block.pattern.split(/\s+/)[0]
419
+ if (pattern.includes('*') || pattern.includes('?')) {
420
+ skip(pattern, 'wildcard')
421
+ continue
422
+ }
423
+ // A block without HostName is a usable OpenSSH entry: the Host pattern
424
+ // itself is the hostname.
425
+ const hostName = block.props.hostname !== undefined && block.props.hostname !== ''
426
+ ? block.props.hostname
427
+ : pattern
428
+ // OpenSSH tries every IdentityFile in order; collapsing the list to one
429
+ // key is what made a working `ssh <alias>` fail here.
430
+ const identityFiles = (block.repeated.identityfile ?? [])
431
+ .map(path => expandHome(path.trim()))
432
+ .filter(path => path !== '')
433
+ const agentValue = block.props.identityagent
434
+ const agentUsable = agentValue !== undefined && agentValue.toLowerCase() !== 'none'
435
+ // `PreferredAuthentications none` means the server authenticates on the
436
+ // username alone and every credential is rejected. Treating that as
437
+ // "password required" made the host permanently unconnectable.
438
+ const prefersNoneOnly = prefersNone(block.props.preferredauthentications)
439
+ const existing = this.list().find(entry => entry.alias === pattern)
440
+ if (existing !== undefined) {
441
+ // A host that is already stored can still be wrong: it may predate
442
+ // multi-key support (one key of two) or the `none` method. Add-only
443
+ // import called those "existing" and left them broken forever.
444
+ if (this.reconcileExisting(existing, identityFiles, prefersNoneOnly, block.props.description)) updated += 1
445
+ else skip(pattern, 'existing')
446
+ continue
447
+ }
448
+ const payload: HostPayload = {
449
+ alias: pattern,
450
+ host: hostName,
451
+ port: block.props.port !== undefined ? Number.parseInt(block.props.port, 10) : 22,
452
+ user: block.props.user ?? process.env.USER ?? 'root',
453
+ auth: {
454
+ kind: identityFiles.length > 0
455
+ ? 'key'
456
+ : agentUsable
457
+ ? 'agent'
458
+ : prefersNoneOnly
459
+ ? 'none'
460
+ : 'password',
461
+ keyPath: identityFiles[0],
462
+ keyPaths: identityFiles.length > 1 ? identityFiles : undefined,
463
+ password: block.props.password,
464
+ agentPath: agentUsable ? normalizeAgentPath(agentValue) : undefined,
465
+ },
466
+ proxyJump: block.props.proxyjump !== undefined
467
+ ? block.props.proxyjump.split(',').map(hop => hop.trim()).filter(hop => hop !== '')
468
+ : [],
469
+ proxyCommand: block.props.proxycommand,
470
+ description: block.props.description,
471
+ environment: block.props.environment,
472
+ tags: (block.props.tags ?? '').split(',').map(tag => tag.trim()).filter(tag => tag !== ''),
473
+ location: block.props.location,
474
+ forwardAgent: parseForwardAgentValue(block.props.forwardagent),
475
+ }
476
+ try {
477
+ this.create(payload)
478
+ added += 1
479
+ } catch {
480
+ // Unusable entry (bad alias grammar, conflicting transports, ...).
481
+ skip(pattern, 'invalid')
482
+ }
483
+ }
484
+ return {
485
+ parsed: blocks.length,
486
+ added,
487
+ updated,
488
+ skipped: this.skippedBlocks.length,
489
+ skippedBlocks: [...this.skippedBlocks],
490
+ }
491
+ }
492
+
493
+ /**
494
+ * ssh_config hosts that this store does not contain yet.
495
+ *
496
+ * The import button used to be the only signal that local config exists, and
497
+ * its only feedback was a count in a notice. Listing the candidates makes the
498
+ * gap visible before the click, which is the difference between "the panel
499
+ * cannot read my SSH config" and "these three hosts are waiting to be added".
500
+ * @returns unimported hosts in file order, with what the import would use.
501
+ */
502
+ listLocalConfigHosts(): LocalConfigHost[] {
503
+ const configPath = this.sshConfigOverride ?? sshConfigPath()
504
+ if (!existsSync(configPath)) return []
505
+ const { blocks } = readSshConfigBlocks(configPath)
506
+ const known = new Set(this.list().map(entry => entry.alias))
507
+ const out: LocalConfigHost[] = []
508
+ for (const block of blocks) {
509
+ const pattern = block.pattern.split(/\s+/)[0]
510
+ if (pattern === '') continue
511
+ if (pattern.includes('*') || pattern.includes('?')) {
512
+ out.push({ alias: pattern, host: block.props.hostname ?? pattern, port: 22, user: '', auth: 'key', skippedReason: 'wildcard' })
513
+ continue
514
+ }
515
+ if (known.has(pattern)) continue
516
+ const identityFiles = (block.repeated.identityfile ?? []).filter(path => path.trim() !== '')
517
+ const agentValue = block.props.identityagent
518
+ const agentUsable = agentValue !== undefined && agentValue.toLowerCase() !== 'none'
519
+ const port = block.props.port !== undefined ? Number.parseInt(block.props.port, 10) : 22
520
+ out.push({
521
+ alias: pattern,
522
+ host: block.props.hostname !== undefined && block.props.hostname !== '' ? block.props.hostname : pattern,
523
+ port: Number.isInteger(port) && port >= 1 && port <= 65535 ? port : 22,
524
+ user: block.props.user ?? '',
525
+ auth: identityFiles.length > 0
526
+ ? 'key'
527
+ : agentUsable
528
+ ? 'agent'
529
+ : prefersNone(block.props.preferredauthentications)
530
+ ? 'none'
531
+ : 'password',
532
+ description: block.props.description,
533
+ })
534
+ }
535
+ return out
536
+ }
537
+
538
+ /**
539
+ * Correct an already-stored host from its ssh_config block.
540
+ *
541
+ * Only the shapes that silently break a working `ssh <alias>` or strictly
542
+ * missing documentation are repaired, and only when the stored value is strictly
543
+ * missing information — never to undo a deliberate user edit:
544
+ * 1. a host with no description when the config provides one;
545
+ * 2. a key host that the config gives more candidate keys than it stores;
546
+ * 3. a host that stores `password` with no password while the config asks
547
+ * for the `none` method.
548
+ * @param existing - the stored entry.
549
+ * @param identityFiles - every IdentityFile from the block, in order.
550
+ * @param prefersNone - whether the block asks for the `none` method.
551
+ * @param description - optional description from the config block.
552
+ * @returns true when the entry was changed.
553
+ */
554
+ private reconcileExisting(
555
+ existing: SshHostEntry,
556
+ identityFiles: string[],
557
+ prefersNone: boolean,
558
+ description?: string,
559
+ ): boolean {
560
+ let changed = false
561
+ if ((existing.description === undefined || existing.description === '') && description !== undefined && description !== '') {
562
+ try {
563
+ this.update(existing.alias, { description })
564
+ changed = true
565
+ } catch {
566
+ // best effort
567
+ }
568
+ }
569
+ if (existing.auth.kind === 'password'
570
+ && prefersNone
571
+ && (existing.auth.password === undefined || existing.auth.password === '')) {
572
+ try {
573
+ this.update(existing.alias, { auth: { kind: 'none' } })
574
+ changed = true
575
+ } catch {
576
+ // best effort
577
+ }
578
+ }
579
+ if (existing.auth.kind === 'key' && identityFiles.length > 0) {
580
+ const stored = keyCandidates(existing)
581
+ const missing = identityFiles.filter(path => !stored.includes(path))
582
+ if (missing.length > 0) {
583
+ // Config order wins: OpenSSH tries the file list top-down.
584
+ const merged: string[] = []
585
+ for (const path of [...identityFiles, ...stored]) {
586
+ if (!merged.includes(path)) merged.push(path)
587
+ }
588
+ try {
589
+ this.update(existing.alias, {
590
+ auth: {
591
+ kind: 'key',
592
+ keyPath: merged[0],
593
+ keyPaths: merged,
594
+ passphrase: existing.auth.passphrase,
595
+ },
596
+ })
597
+ changed = true
598
+ } catch {
599
+ // best effort
600
+ }
601
+ }
602
+ }
603
+ return changed
604
+ }
605
+
606
+ private skippedBlocks: ImportSkipBlock[] = []
607
+
608
+ /**
609
+ * Last parsed store keyed by file identity. list/find ride every acquire
610
+ * and GUI refresh; re-reading and re-parsing the whole file each call is
611
+ * wasted work when the file has not changed. Any save invalidates.
612
+ */
613
+ private cache: { mtimeMs: number; size: number; file: StoreFile } | undefined
614
+
615
+ private load(): StoreFile {
616
+ let stats: { mtimeMs: number; size: number }
617
+ try {
618
+ stats = statSync(this.path)
619
+ } catch {
620
+ this.cache = undefined
621
+ return { version: FORMAT_VERSION, hosts: [] }
622
+ }
623
+ if (this.cache !== undefined && this.cache.mtimeMs === stats.mtimeMs && this.cache.size === stats.size) {
624
+ return this.cache.file
625
+ }
626
+ try {
627
+ const parsed = JSON.parse(readFileSync(this.path, 'utf8')) as StoreFile
628
+ if (typeof parsed !== 'object' || parsed === null || !Array.isArray(parsed.hosts)) {
629
+ throw new Error('store file shape invalid')
630
+ }
631
+ this.cache = { mtimeMs: stats.mtimeMs, size: stats.size, file: parsed }
632
+ return parsed
633
+ } catch {
634
+ // A corrupt store must not brick the plugin — and must not be silently
635
+ // overwritten by the next save: rename it aside for manual recovery
636
+ // (the plugin then starts from an empty list).
637
+ this.cache = undefined
638
+ try {
639
+ renameSync(this.path, `${this.path}.corrupt-${Date.now()}`)
640
+ } catch { /* best effort */ }
641
+ return { version: FORMAT_VERSION, hosts: [] }
642
+ }
643
+ }
644
+
645
+ private save(file: StoreFile): void {
646
+ const dir = dirname(this.path)
647
+ if (!existsSync(dir)) mkdirSync(dir, { recursive: true, mode: 0o700 })
648
+ const tmp = this.path + '.tmp'
649
+ // Secrets live in this file: keep it readable by the owner only. The
650
+ // tmp file carries the 0600 mode through the rename.
651
+ writeFileSync(tmp, JSON.stringify(file, null, 2) + '\n', { encoding: 'utf8', mode: 0o600 })
652
+ renameSync(tmp, this.path)
653
+ this.cache = undefined
654
+ }
655
+
656
+ /**
657
+ * Rewrite every entry's stored secrets under this store's protector.
658
+ *
659
+ * Rotation needs one write that changes the sealing key for the WHOLE file.
660
+ * Calling `update()` per entry cannot do that: `update` reads the stored
661
+ * file, decrypts it with the current protector, and re-seals with the same
662
+ * one — so it would rewrite each entry under the old key and the operator's
663
+ * new key would open nothing.
664
+ *
665
+ * This method takes the entries already decrypted (by `list()` under the
666
+ * previous protector) and re-seals them in a single `save()`, so there is no
667
+ * window where half the file is sealed with one key and half with another.
668
+ *
669
+ * @param entries - the entries with plaintext secrets.
670
+ */
671
+ resealAll(entries: SshHostEntry[]): void {
672
+ const file = this.load()
673
+ const next: StoreFile = {
674
+ ...file,
675
+ hosts: entries.map(entry => this.encryptEntry(entry)),
676
+ }
677
+ this.save(next)
678
+ }
679
+ }
680
+
681
+ /** Normalize an agent endpoint for storage: trim, expand `~`, and resolve the SSH_AUTH_SOCK token. */
682
+ export function normalizeAgentPath(agentPath: string | undefined): string | undefined {
683
+ const trimmed = agentPath?.trim()
684
+ if (trimmed === undefined || trimmed === '') return undefined
685
+ if (trimmed === 'SSH_AUTH_SOCK' || trimmed === '$SSH_AUTH_SOCK') {
686
+ const sock = process.env.SSH_AUTH_SOCK
687
+ return sock !== undefined && sock !== '' ? sock : undefined
688
+ }
689
+ return expandHome(trimmed)
690
+ }
691
+
692
+ /**
693
+ * Normalize a ProxyCommand for storage: trim, and treat an empty value or
694
+ * OpenSSH's `none` keyword as "no proxy command" (an explicit clear).
695
+ */
696
+ export function normalizeProxyCommand(raw: string | undefined): string | undefined {
697
+ const trimmed = raw?.trim()
698
+ if (trimmed === undefined || trimmed === '') return undefined
699
+ if (trimmed.toLowerCase() === 'none') return undefined
700
+ return trimmed
701
+ }
702
+
703
+ /**
704
+ * Read an ssh_config `ForwardAgent` value into the stored boolean flag. Only
705
+ * an explicit yes/true/on enables forwarding; an absent value, no/false/off,
706
+ * and anything unrecognized leave it off instead of failing the import — an
707
+ * unknown keyword must never cost the user the whole Host block.
708
+ */
709
+ export function parseForwardAgentValue(raw: string | undefined): boolean {
710
+ const value = raw?.trim().toLowerCase()
711
+ return value === 'yes' || value === 'true' || value === 'on'
712
+ }
713
+
714
+ /**
715
+ * Every private key this entry may authenticate with, in try order.
716
+ *
717
+ * `keyPaths` (the whole IdentityFile list) wins when present; older entries
718
+ * store only `keyPath`. Duplicates are dropped so a config that repeats the
719
+ * same path does not pay for a second handshake.
720
+ * @param entry - a stored host entry (secrets irrelevant).
721
+ * @returns candidate key paths, possibly empty.
722
+ */
723
+ export function keyCandidates(entry: { auth: { keyPath?: string; keyPaths?: string[] } }): string[] {
724
+ const list = entry.auth.keyPaths !== undefined && entry.auth.keyPaths.length > 0
725
+ ? entry.auth.keyPaths
726
+ : entry.auth.keyPath !== undefined
727
+ ? [entry.auth.keyPath]
728
+ : []
729
+ const unique: string[] = []
730
+ for (const path of list) {
731
+ const expanded = expandHome(path.trim())
732
+ if (expanded !== '' && !unique.includes(expanded)) unique.push(expanded)
733
+ }
734
+ return unique
735
+ }
736
+
737
+ /**
738
+ * Whether an ssh_config `PreferredAuthentications` list offers `none`.
739
+ *
740
+ * `none` is a real method: the client asks the server to accept the username
741
+ * with no credential, which some sandboxes do. An absent value means `none` was
742
+ * not requested, so callers must not infer it.
743
+ * @param raw - the raw option value, if any.
744
+ * @returns true when the method list contains `none`.
745
+ */
746
+ export function prefersNone(raw: string | undefined): boolean {
747
+ const value = raw?.trim().toLowerCase()
748
+ if (value === undefined || value === '') return false
749
+ return value.split(',').map(part => part.trim()).includes('none')
750
+ }
751
+
752
+ /** Expand a leading `~` in a filesystem path. */
753
+ export function expandHome(path: string): string {
754
+ if (path === '~') return homedir()
755
+ if (path.startsWith('~/')) return join(homedir(), path.slice(2))
756
+ return path
757
+ }