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
@@ -0,0 +1,55 @@
1
+ /**
2
+ * Host single-instance guard shared by the plugin family. The family bundle
3
+ * (dsh-web-all / dsh-skins) namespaces every child row id (web-ui-*), so
4
+ * the loader accepts a standalone install of the same package side by side;
5
+ * without this guard the second instance would still re-register the same
6
+ * webserver routes, tools, settings namespaces, and system-prompt sections
7
+ * and fail the boot. mountOnce makes a mount of an already-mounted package a
8
+ * no-op for as long as the first instance lives (the browser half is already
9
+ * deduped by package name in the client module host).
10
+ *
11
+ * A no-op is only safe while the holder is ALIVE. The holder can be disposed
12
+ * long after the refused mount ran its course: the Host reloads a profile by
13
+ * creating the new loader entries before the old ones are torn down (a
14
+ * plugin-manager enable/disable/install write, a settings-driven row reload,
15
+ * HMR), so the new aggregate shell entry mounts its family plugin while the
16
+ * previous entry still owns the name. Dropping that refused mount lost the
17
+ * plugin for good - the previous entry then disposed its own mount, releasing
18
+ * the name with nobody left to take it, and the family row stayed listed as
19
+ * active while its host routes 404ed (the task-board panel showed
20
+ * "board.hostError.notMounted", no degraded record appeared, and only a Host
21
+ * restart recovered it).
22
+ *
23
+ * The refused mount is therefore QUEUED, not dropped, and replayed the moment
24
+ * the holder releases the name - if the waiting fiber is still alive then. The
25
+ * single-instance guarantee is unchanged: exactly one mount is live per
26
+ * package name, and the replay re-enters the guard so a later mount still
27
+ * dedupes against it.
28
+ *
29
+ * The registry rides a global symbol so two module instances of the same
30
+ * package (npm copy vs repository link) still share one verdict. That symbol
31
+ * is a CROSS-REPOSITORY contract, not this file's private state: the four
32
+ * satellite packages (dsh-skins / dsh-pet / dsh-presets /
33
+ * dsh-community-plugins) are separate repositories carrying their own copy of
34
+ * this guard, rebuilt on their own schedule, so the value under `MOUNTED`
35
+ * must keep the shape every published copy reads (a `Set` of package names
36
+ * with `has`/`add`/`delete`). The wait queues this guard added therefore live
37
+ * under their own additive key, and the registry reads back a `Set` even when
38
+ * some other build left a different value there. Changing `MOUNTED`'s shape
39
+ * in place broke that contract once: a satellite's legacy copy created a
40
+ * `Set`, the family's new copy read it as a `Map`, and every family row
41
+ * mounted after it failed with "claims.get is not a function".
42
+ *
43
+ * cordis `ctx.effect` runs its callback immediately and treats the callback's
44
+ * return value as the fiber disposer, so the unmarker is returned, not run.
45
+ */
46
+ /**
47
+ * Wrap a cordis plugin apply so the package runs at most once per process.
48
+ * The first mount registers normally and releases the name when its fiber
49
+ * disposes; a mount refused while that name is held waits for the release and
50
+ * then runs, unless its own fiber disposes first.
51
+ * @param packageName - npm package identity shared by every install source.
52
+ * @param fn - the original plugin apply.
53
+ * @returns an apply of the same shape.
54
+ */
55
+ export declare function mountOnce<T extends (...args: any[]) => unknown>(packageName: string, fn: T): T;
@@ -0,0 +1,524 @@
1
+ /**
2
+ * Wire contract between the host half (routes.ts) and the browser half
3
+ * (client/api.ts). Pure types only — imported by both halves, bundled into
4
+ * each, no runtime identity to share.
5
+ */
6
+ /**
7
+ * Authentication flavors a host entry may carry.
8
+ *
9
+ * `none` is a real OpenSSH method (`PreferredAuthentications none`): some
10
+ * sandboxes authenticate by username alone and reject any credential. Refusing
11
+ * to connect without a stored secret would make such a host permanently
12
+ * unreachable even though plain `ssh <alias>` works.
13
+ */
14
+ export type SshAuthKind = 'key' | 'password' | 'agent' | 'none';
15
+ /** One stored host entry (the $DSH_HOME/dsh-ssh.json store shape). */
16
+ export interface SshHostEntry {
17
+ /** Stable, user-chosen identifier used by every operation. */
18
+ alias: string;
19
+ /** Hostname or IP of the target. */
20
+ host: string;
21
+ /** SSH port (default 22). */
22
+ port: number;
23
+ /** Login user. */
24
+ user: string;
25
+ /** Authentication. */
26
+ auth: {
27
+ kind: SshAuthKind;
28
+ /** Absolute path to the private key for 'key' auth. */
29
+ keyPath?: string;
30
+ /**
31
+ * Every candidate key, in ssh_config order. OpenSSH tries each
32
+ * `IdentityFile` until one authenticates, so a host configured with two
33
+ * keys must not be reduced to the last one — that turns a working
34
+ * `ssh <alias>` into "All configured authentication methods failed".
35
+ * `keyPath` stays the primary (first) candidate for older readers.
36
+ */
37
+ keyPaths?: string[];
38
+ /** Passphrase for an encrypted key. */
39
+ passphrase?: string;
40
+ /** Password for 'password' auth. */
41
+ password?: string;
42
+ /**
43
+ * ssh-agent endpoint for 'agent' auth. A socket path, the special value
44
+ * 'pageant' (PuTTY Pageant on Windows), or undefined for auto-detect
45
+ * (SSH_AUTH_SOCK, then the native OpenSSH named pipe on Windows).
46
+ */
47
+ agentPath?: string;
48
+ };
49
+ /** Jump chain: local aliases connected through in order (ProxyJump). */
50
+ proxyJump: string[];
51
+ /**
52
+ * OpenSSH-compatible ProxyCommand: a shell command whose stdio becomes the
53
+ * connection transport. Tokens %h (host) / %p (port) / %r (user) / %n (alias)
54
+ * expand before exec and %% is a literal percent; an empty value or 'none'
55
+ * means "no proxy command". Mutually exclusive with a non-empty proxyJump.
56
+ */
57
+ proxyCommand?: string;
58
+ /** Free-form note. */
59
+ description?: string;
60
+ /** Deployment environment label (development / production / ...). */
61
+ environment?: string;
62
+ /** Free-form tags. */
63
+ tags: string[];
64
+ /** Physical location note. */
65
+ location?: string;
66
+ /**
67
+ * Opt-in ssh-agent forwarding (OpenSSH ForwardAgent / ssh -A): the host's
68
+ * sessions request agent forwarding so the remote can sign with this
69
+ * machine's agent. Default off; stored only when enabled.
70
+ */
71
+ forwardAgent?: boolean;
72
+ createdAt: number;
73
+ updatedAt: number;
74
+ }
75
+ /** Public (secret-free) projection of an entry, safe for the browser/agent. */
76
+ export interface SshHostSummary {
77
+ alias: string;
78
+ host: string;
79
+ port: number;
80
+ user: string;
81
+ auth: SshAuthKind;
82
+ /** Whether the key path exists on the host machine (key auth only). */
83
+ keyReady: boolean;
84
+ proxyJump: string[];
85
+ /** Configured ProxyCommand, echoed to the browser so the form can edit it. */
86
+ proxyCommand?: string;
87
+ description?: string;
88
+ environment?: string;
89
+ tags: string[];
90
+ location?: string;
91
+ /**
92
+ * Whether agent forwarding is enabled. Always projected as a definite
93
+ * boolean: the browser and the tool bridge need a value even for entries
94
+ * stored before the feature existed.
95
+ */
96
+ forwardAgent: boolean;
97
+ createdAt: number;
98
+ updatedAt: number;
99
+ }
100
+ /** Result of one non-interactive command execution. */
101
+ export interface ExecResult {
102
+ success: boolean;
103
+ /** Remote exit code, or null when the channel died without one. */
104
+ exitCode: number | null;
105
+ timedOut: boolean;
106
+ stdout: string;
107
+ stderr: string;
108
+ /** Wall-clock duration of the round trip in ms. */
109
+ durationMs: number;
110
+ /** Connection error message when the command never ran. */
111
+ error?: string;
112
+ }
113
+ /** One server entry in a cluster run. */
114
+ export interface ClusterResult {
115
+ alias: string;
116
+ ok: boolean;
117
+ exitCode?: number | null;
118
+ timedOut?: boolean;
119
+ stdout?: string;
120
+ stderr?: string;
121
+ durationMs?: number;
122
+ error?: string;
123
+ }
124
+ /** SFTP transfer progress frame (upload stream). */
125
+ export interface TransferProgress {
126
+ phase: 'connecting' | 'transferring' | 'done' | 'error';
127
+ file: string;
128
+ transferred: number;
129
+ total: number;
130
+ percent: number;
131
+ speedBps?: number;
132
+ error?: string;
133
+ }
134
+ /**
135
+ * One active local port-forward.
136
+ *
137
+ * `source` distinguishes a forward this plugin owns from one that already
138
+ * exists on the machine (`ssh -N -L …` started by hand or by another tool).
139
+ * Listing only our own forwards made a running tunnel look absent; the
140
+ * external row is read-only because the process is not ours to kill.
141
+ */
142
+ export interface TunnelInfo {
143
+ id: string;
144
+ alias: string;
145
+ localPort: number;
146
+ remoteHost: string;
147
+ remotePort: number;
148
+ state: 'forwarding' | 'connecting' | 'failed';
149
+ error?: string;
150
+ startedAt: number;
151
+ /** Who owns the listener. Absent means 'plugin' (older shape). */
152
+ source?: 'plugin' | 'external';
153
+ /** Owning OS process for an external forward. */
154
+ pid?: number;
155
+ /** True when the local port actually accepts connections right now. */
156
+ live?: boolean;
157
+ /** The ssh option that created it ('-L', '-R' or '-D'), external forwards only. */
158
+ kind?: 'local' | 'remote' | 'dynamic';
159
+ /** Project or service name (e.g. from forwards.conf or user remark). */
160
+ name?: string;
161
+ /** Remarks / note about what project or service this tunnel serves. */
162
+ description?: string;
163
+ /**
164
+ * True when the name/description came from a stored user remark rather than
165
+ * `~/.ssh/forwards.conf`. The panel marks these so a stale automatic name is
166
+ * not mistaken for one the operator typed.
167
+ */
168
+ customRemark?: boolean;
169
+ }
170
+ /**
171
+ * One ssh_config host that the store does not contain yet.
172
+ *
173
+ * The panel shows these so "import" is a decision about visible hosts rather
174
+ * than a button whose only feedback is a count.
175
+ */
176
+ export interface LocalConfigHost {
177
+ alias: string;
178
+ host: string;
179
+ port: number;
180
+ user: string;
181
+ /** What the store would use if this host were imported. */
182
+ auth: SshAuthKind;
183
+ /** True when the block cannot be imported as-is (wildcard / Match). */
184
+ skippedReason?: ImportSkipReason;
185
+ /** Host description (e.g. from comments preceding the Host block). */
186
+ description?: string;
187
+ }
188
+ /** One directory listing entry (remote file browser). */
189
+ export interface RemoteDirEntry {
190
+ name: string;
191
+ type: 'dir' | 'file' | 'other';
192
+ size: number;
193
+ mtimeMs: number;
194
+ mode?: number;
195
+ }
196
+ /** Test-connection outcome. */
197
+ export interface TestResult {
198
+ ok: boolean;
199
+ latencyMs?: number;
200
+ error?: string;
201
+ }
202
+ /** Host edit payload (create/update); 'alias' comes from the URL for updates. */
203
+ export interface HostPayload {
204
+ alias?: string;
205
+ host: string;
206
+ port?: number;
207
+ user: string;
208
+ /**
209
+ * Authentication. Required on create; on update an omitted auth keeps the
210
+ * stored secrets (the browser never receives them back).
211
+ */
212
+ auth?: SshHostEntry['auth'];
213
+ proxyJump?: string[];
214
+ /**
215
+ * ProxyCommand to store. An empty string or 'none' clears a stored value;
216
+ * omitting the key leaves it untouched (PATCH semantics).
217
+ */
218
+ proxyCommand?: string;
219
+ description?: string;
220
+ environment?: string;
221
+ tags?: string[];
222
+ location?: string;
223
+ /**
224
+ * Agent forwarding for this host. Omitted on update keeps the stored value;
225
+ * false clears it (PATCH semantics).
226
+ */
227
+ forwardAgent?: boolean;
228
+ }
229
+ /** Why one ssh_config Host block was not imported. */
230
+ export type ImportSkipReason = 'wildcard' | 'existing' | 'match' | 'invalid';
231
+ /** One skipped ssh_config block and the reason it could not be imported. */
232
+ export interface ImportSkipBlock {
233
+ /** Host pattern (or '`Match …`' label) that was skipped. */
234
+ name: string;
235
+ reason: ImportSkipReason;
236
+ }
237
+ /** Import outcome from ~/.ssh/config. */
238
+ export interface ImportResult {
239
+ parsed: number;
240
+ added: number;
241
+ /**
242
+ * Existing hosts whose stored shape was corrected from the config — a host
243
+ * that gained a second candidate key, or one switched to `none` auth. An
244
+ * "add-only" import cannot repair those, and reporting them as merely
245
+ * "existing" is what makes a broken host look already imported.
246
+ */
247
+ updated: number;
248
+ skipped: number;
249
+ /** Every skipped block with its reason, in scan order and deduplicated by name. */
250
+ skippedBlocks: ImportSkipBlock[];
251
+ }
252
+ /** JSON error body used by every route. */
253
+ export interface ApiErrorBody {
254
+ error: string;
255
+ }
256
+ /** WebSocket terminal protocol frames (host -> client and client -> host). */
257
+ export type TerminalServerFrame =
258
+ /** The shell is up; `sessionId` reattaches to it after a view detach. */
259
+ {
260
+ type: 'ready';
261
+ alias: string;
262
+ sessionId: string;
263
+ } | {
264
+ type: 'output';
265
+ data: string;
266
+ } | {
267
+ type: 'exit';
268
+ code: number | null;
269
+ error?: string;
270
+ } | {
271
+ type: 'auth_prompt';
272
+ name: string;
273
+ instructions: string;
274
+ prompts: Array<{
275
+ prompt: string;
276
+ echo: boolean;
277
+ }>;
278
+ };
279
+ export type TerminalClientFrame = {
280
+ type: 'input';
281
+ data: string;
282
+ } | {
283
+ type: 'resize';
284
+ cols: number;
285
+ rows: number;
286
+ } | {
287
+ type: 'auth_response';
288
+ responses: string[];
289
+ }
290
+ /** Leave the socket while the host keeps the shell alive for a reattach. */
291
+ | {
292
+ type: 'detach';
293
+ }
294
+ /** End the session outright (the view's disconnect control). */
295
+ | {
296
+ type: 'close';
297
+ };
298
+ /** One check result as the panel reads it. */
299
+ export interface CheckResultRow {
300
+ checkId: string;
301
+ alias: string;
302
+ value: number | boolean | string | null;
303
+ breached: boolean;
304
+ raw: string;
305
+ error?: string;
306
+ }
307
+ /** One retained inspection round. */
308
+ export interface InspectionRound {
309
+ startedAt: number;
310
+ durationMs: number;
311
+ targets: string[];
312
+ results: CheckResultRow[];
313
+ }
314
+ /** One host's change between the two most recent rounds. */
315
+ export interface HostChange {
316
+ alias: string;
317
+ checkId: string;
318
+ title: string;
319
+ before?: string;
320
+ after: string;
321
+ stateChange?: 'new-breach' | 'recovered';
322
+ }
323
+ /** The monitoring loop's health. */
324
+ export interface MonitorStatus {
325
+ enabled: boolean;
326
+ running: boolean;
327
+ intervalMs?: number;
328
+ hosts?: number;
329
+ lastRoundAt?: number;
330
+ nextTickAt?: number;
331
+ lastTick?: MonitorTickResult;
332
+ reason?: string;
333
+ }
334
+ /** One round's outcome as the loop recorded it. */
335
+ export interface MonitorTickResult {
336
+ at: number;
337
+ ran: boolean;
338
+ hosts: number;
339
+ breaches: number;
340
+ blind: number;
341
+ skippedBecause?: string;
342
+ }
343
+ /** One alert state row. */
344
+ export interface AlertStateRow {
345
+ ruleId: string;
346
+ alias: string;
347
+ state: 'ok' | 'pending' | 'firing' | 'frozen';
348
+ consecutiveBreaches?: number;
349
+ lastValue?: string;
350
+ lastFiredAt?: number;
351
+ }
352
+ /** One alert event. */
353
+ export interface AlertEventRow {
354
+ ruleId: string;
355
+ alias: string;
356
+ kind: 'trigger' | 'recover';
357
+ value: string;
358
+ at: number;
359
+ }
360
+ /** One aggregated metric bucket. */
361
+ export interface MetricBucketRow {
362
+ at: number;
363
+ metric: string;
364
+ value: number | null;
365
+ samples: number;
366
+ }
367
+ /** The live security posture. */
368
+ export interface SecurityStatus {
369
+ encryptConfigured: boolean;
370
+ secret: {
371
+ available: boolean;
372
+ source: 'env' | 'file' | 'none';
373
+ };
374
+ hostKeyPolicy?: string;
375
+ auditEnabled?: boolean;
376
+ /** Entries whose stored credentials are still readable without the key. */
377
+ plaintextAliases?: string[];
378
+ /** The key file the panel manages (shown so the operator can back it up). */
379
+ keyPath?: string;
380
+ }
381
+ /** One deployment step as the panel submits it. */
382
+ export interface DeployStepPayload {
383
+ name: string;
384
+ command: string;
385
+ /** Undo command. Required: a step without one cannot be rolled back. */
386
+ rollbackCommand: string;
387
+ }
388
+ /** A deployment plan as the panel submits it. */
389
+ export interface DeployPlanPayload {
390
+ id: string;
391
+ description?: string;
392
+ steps: DeployStepPayload[];
393
+ batchSize?: number;
394
+ timeoutMs?: number;
395
+ stopOnFailure?: boolean;
396
+ healthCheck?: {
397
+ command: string;
398
+ expectExitCode?: number;
399
+ settleMs?: number;
400
+ };
401
+ }
402
+ /** A log-search request as the panel submits it. */
403
+ export interface LogSearchPayload {
404
+ pattern: string;
405
+ source?: 'journal' | 'files';
406
+ directory?: string;
407
+ unit?: string;
408
+ sinceSeconds?: number;
409
+ maxLinesPerHost?: number;
410
+ }
411
+ /** One host's outcome inside a recorded deployment. */
412
+ export interface DeployHostRow {
413
+ alias: string;
414
+ ok: boolean;
415
+ /** Names of the steps that ran, in order (the orchestrator does not report them). */
416
+ steps: string[];
417
+ /** Health-check verdict, when the plan declared one. */
418
+ healthy?: boolean;
419
+ /** Whether a rollback was attempted for this host. */
420
+ rolledBack?: boolean;
421
+ /** The exit code of the last step. */
422
+ exitCode?: number | null;
423
+ error?: string;
424
+ }
425
+ /** One recorded deployment run, as the deploy tab reads it. */
426
+ export interface DeployRunRow {
427
+ id: string;
428
+ planId: string;
429
+ at: number;
430
+ finishedAt?: number;
431
+ /** The plan's batch size, so the UI can group hosts the way they ran. */
432
+ batchSize: number;
433
+ hostCount: number;
434
+ ok: boolean;
435
+ hosts: DeployHostRow[];
436
+ }
437
+ /** One host's slice of a cross-host log search. */
438
+ export interface LogHostRow {
439
+ alias: string;
440
+ ok: boolean;
441
+ lines: string[];
442
+ total: number;
443
+ truncated: boolean;
444
+ error?: string;
445
+ durationMs?: number;
446
+ }
447
+ /** One cross-host log search result, as the logs tab reads it. */
448
+ export interface LogSearchRow {
449
+ at: number;
450
+ pattern: string;
451
+ source: string;
452
+ /** 'all' or the selected aliases. */
453
+ targets: string[];
454
+ hosts: LogHostRow[];
455
+ }
456
+ /** Set or clear the master secret from the panel (interactive setup). */
457
+ export interface MasterSecretPayload {
458
+ /** New master secret. An empty string clears nothing; use action 'clear'. */
459
+ secret?: string;
460
+ /** 'set' stores/rotates the secret, 'clear' removes it. */
461
+ action: 'set' | 'clear';
462
+ /** For 'clear': re-encrypt existing plaintext first (refused when false). */
463
+ confirmPlaintext?: boolean;
464
+ }
465
+ /** Outcome of a master-secret change. */
466
+ export interface MasterSecretResult {
467
+ ok: boolean;
468
+ /** Where the secret now comes from. */
469
+ source: 'env' | 'file' | 'none';
470
+ /** Entries re-encrypted by this call. */
471
+ rotated: number;
472
+ /** Set when the change was refused or failed. */
473
+ error?: string;
474
+ }
475
+ /** Route paths the client calls (shared literals). */
476
+ export declare const SSH_API_BASE: "/api/dsh-ssh";
477
+ export declare const SSH_API: {
478
+ readonly hosts: string;
479
+ readonly importSshConfig: string;
480
+ /** ssh_config hosts the store does not contain yet (read-only preview). */
481
+ readonly localConfig: string;
482
+ readonly test: string;
483
+ readonly exec: string;
484
+ readonly cluster: string;
485
+ readonly upload: string;
486
+ readonly download: string;
487
+ readonly ls: string;
488
+ readonly tunnel: string;
489
+ readonly terminal: string;
490
+ /** The monitoring loop's health readout. */
491
+ readonly monitor: string;
492
+ /** Manual round trigger, the same path the timer takes. */
493
+ readonly monitorTick: string;
494
+ /** Retained inspection rounds. */
495
+ readonly inspection: string;
496
+ /** The change set between the two most recent rounds. */
497
+ readonly inspectionDiff: string;
498
+ /** Alert states and the recent event feed. */
499
+ readonly alerts: string;
500
+ /** Metric series for one host and tier. */
501
+ readonly metrics: string;
502
+ /** The live security posture. */
503
+ readonly security: string;
504
+ /** Recorded deployment runs, newest first. */
505
+ readonly deployHistory: string;
506
+ /** Run a deployment plan recorded into the history. */
507
+ readonly deploy: string;
508
+ /** Cross-host log search, recorded into the history. */
509
+ readonly logs: string;
510
+ /** Recent log-search results, newest first. */
511
+ readonly logsHistory: string;
512
+ /** Store or clear the master secret from the panel. */
513
+ readonly setSecret: string;
514
+ };
515
+ /** NDJSON transfer stream line shapes (upload). */
516
+ export type TransferStreamLine = {
517
+ type: 'progress';
518
+ progress: TransferProgress;
519
+ } | {
520
+ type: 'result';
521
+ ok: boolean;
522
+ transferredBytes?: number;
523
+ error?: string;
524
+ };
@@ -0,0 +1,82 @@
1
+ /**
2
+ * The /api/dsh-ssh route family: host CRUD, exec, cluster, SFTP transfer
3
+ * (NDJSON progress stream for uploads, binary stream for downloads), remote
4
+ * listing, tunnels, and the WebSocket PTY terminal upgrade. Every route
5
+ * carries a loopback-only trust fence (plus browser same-origin markers) —
6
+ * these endpoints execute commands on remote servers, so LAN-exposed dsh web
7
+ * deployments must not serve them.
8
+ */
9
+ import type { WebRoute, WebUpgradeRoute } from '@deepseek-ai/dsh-host-webserver';
10
+ import type { SshEngine } from './engine.ts';
11
+ import { TerminalSessionRegistry } from './engine/terminal-sessions.ts';
12
+ import type { DeployRunRow, LogSearchRow, MasterSecretPayload, MasterSecretResult } from './protocol.ts';
13
+ import type { ActivityHistory } from './activity/history.ts';
14
+ import type { HostStore } from './store.ts';
15
+ import type { Monitor } from './monitor/loop.ts';
16
+ import { type MetricStore } from './monitor/metrics.ts';
17
+ import type { Inspector } from './inspect/inspection.ts';
18
+ import type { AlertEngine } from './alerting/rules.ts';
19
+ import type { AlertEvent } from './alerting/tools.ts';
20
+ /** Route family dependencies. */
21
+ export interface SshRoutesDeps {
22
+ /** The host store (CRUD). */
23
+ store: HostStore;
24
+ /** The engine (ops). */
25
+ engine: SshEngine;
26
+ /** The monitoring loop (status readout). */
27
+ monitor?: Monitor;
28
+ /** The metric store (history readout). */
29
+ metrics?: MetricStore;
30
+ /** The inspection history (rounds and diff). */
31
+ inspector?: Inspector;
32
+ /** The alert engine (rule states). */
33
+ alerts?: AlertEngine;
34
+ /** The alert event feed. */
35
+ alertEvents?: AlertEvent[];
36
+ /**
37
+ * Report the live security posture (encryption configured vs active).
38
+ *
39
+ * A callback rather than a value so the route always reads the current
40
+ * config: toggling encryptCredentials in settings must be reflected on the
41
+ * next request, not after a remount.
42
+ */
43
+ security?: () => {
44
+ encryptConfigured: boolean;
45
+ secret: {
46
+ available: boolean;
47
+ source: 'env' | 'file' | 'none';
48
+ };
49
+ hostKeyPolicy: string;
50
+ auditEnabled: boolean;
51
+ };
52
+ /** Temp dir for upload/download staging (tests inject a sandbox). */
53
+ stagingDir?: string;
54
+ /** Upload byte cap override (tests); defaults to MAX_UPLOAD_BYTES. */
55
+ maxUploadBytes?: number;
56
+ /** The key file the panel manages (for the status report). */
57
+ keyPath?: string;
58
+ /** Aliases whose stored credentials are still plaintext. */
59
+ plaintext?: () => {
60
+ aliases: string[];
61
+ };
62
+ /**
63
+ * Store or clear the master secret. Mutating, so the route fences it
64
+ * exactly like any other write; the operation itself decides whether a
65
+ * rotation is required and refuses a change that would strand credentials.
66
+ */
67
+ setSecret?: (payload: MasterSecretPayload) => MasterSecretResult;
68
+ /** Deployment history (recorded runs, newest first). */
69
+ deployHistory?: ActivityHistory<DeployRunRow>;
70
+ /** Log-search history (recorded searches, newest first). */
71
+ logHistory?: ActivityHistory<LogSearchRow>;
72
+ }
73
+ /**
74
+ * Build every /api/dsh-ssh route (exact paths) plus the terminal upgrade.
75
+ * @param deps - store, engine, staging dir.
76
+ * @returns routes and the upgrade route.
77
+ */
78
+ export declare function makeRoutes(deps: SshRoutesDeps): {
79
+ routes: WebRoute[];
80
+ upgrade: WebUpgradeRoute;
81
+ terminalSessions: TerminalSessionRegistry;
82
+ };