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,89 @@
1
+ /**
2
+ * Discovery of port forwards that already exist on this machine.
3
+ *
4
+ * The plugin can only list the tunnels it created itself, because they live in
5
+ * process memory. An operator's real fleet usually also has forwards started by
6
+ * hand (`ssh -N -L 8080:localhost:80 host`) or by another tool, and those were
7
+ * invisible in the tunnels tab even while they were serving traffic. This
8
+ * module reads the OS process table, parses the ssh forward options, and probes
9
+ * each local port so the panel can report what is actually listening.
10
+ *
11
+ * Everything here is best-effort: any failure (no process tool, a denied
12
+ * command, an unexpected line shape) yields "no external forwards" instead of
13
+ * an error, because a diagnostic aid must never break the tab it decorates.
14
+ */
15
+ import type { TunnelInfo } from '../protocol.ts';
16
+ /** One forward extracted from an ssh command line. */
17
+ export interface ParsedForward {
18
+ kind: 'local' | 'remote' | 'dynamic';
19
+ /** The port that listens on THIS machine (the local side of -L and -D). */
20
+ localPort: number;
21
+ /** Bind address for the local listener, when given. */
22
+ bindHost?: string;
23
+ remoteHost?: string;
24
+ remotePort?: number;
25
+ }
26
+ /** One ssh process and the forwards its command line declares. */
27
+ export interface ScannedProcess {
28
+ pid: number;
29
+ /** Destination alias/host: the last bare argument (OpenSSH's destination). */
30
+ destination: string;
31
+ forwards: ParsedForward[];
32
+ }
33
+ /**
34
+ * Split an ssh command line into arguments, tolerating both quoting styles a
35
+ * Windows process table can contain.
36
+ * @param commandLine - the raw command line.
37
+ * @returns the argument list (options keep their leading dash).
38
+ */
39
+ export declare function splitCommandLine(commandLine: string): string[];
40
+ /**
41
+ * Parse one `-L` / `-R` / `-D` specification.
42
+ *
43
+ * `-L` accepts `[bind_address:]port:host:hostport`; the bind part may itself be
44
+ * an IPv6 literal in brackets. `-D` accepts `[bind_address:]port`. `-R` mirrors
45
+ * `-L` but listens on the remote side, so it never owns a local port.
46
+ * @param kind - which option produced the spec.
47
+ * @param spec - the raw value after the option.
48
+ * @returns the parsed forward, or undefined when the spec is not understood.
49
+ */
50
+ export declare function parseForwardSpec(kind: 'local' | 'remote' | 'dynamic', spec: string): ParsedForward | undefined;
51
+ /**
52
+ * Extract the forward options and the destination from an ssh argument list.
53
+ * @param args - argv of one ssh invocation (program name included).
54
+ * @returns destination and forwards.
55
+ */
56
+ export declare function parseSshArguments(args: string[]): {
57
+ destination: string;
58
+ forwards: ParsedForward[];
59
+ };
60
+ /** Enumerate ssh processes with a forward on this machine (cached). */
61
+ export declare function scanSshProcesses(): Promise<ScannedProcess[]>;
62
+ /** Clear the process-scan cache (tests). */
63
+ export declare function resetTunnelScanCache(): void;
64
+ /** One record from ~/.ssh/forwards.conf. */
65
+ export interface ForwardConfEntry {
66
+ name: string;
67
+ localPort: number;
68
+ remoteTarget: string;
69
+ description: string;
70
+ }
71
+ /**
72
+ * Parse ~/.ssh/forwards.conf for project names and descriptions.
73
+ * The user's forwards.conf is the authoritative registry of tunnels on the machine.
74
+ */
75
+ export declare function readForwardsConf(overridePath?: string): Map<number, ForwardConfEntry>;
76
+ /**
77
+ * Port forwards that exist on this machine but are not owned by this plugin.
78
+ *
79
+ * A forward whose local port is dead is still reported (`live: false`) — it was
80
+ * declared by a running process, and hiding it would make a half-broken tunnel
81
+ * look absent rather than broken.
82
+ * @param owned - local ports the plugin already reports, to avoid duplicates.
83
+ * @param customRemarks - optional stored user remarks keyed by port or tunnel id.
84
+ * @returns external forwards in process order.
85
+ */
86
+ export declare function discoverExternalTunnels(owned: TunnelInfo[], customRemarks?: Record<string, {
87
+ name?: string;
88
+ description?: string;
89
+ }>): Promise<TunnelInfo[]>;
@@ -0,0 +1,49 @@
1
+ /**
2
+ * User remarks for port forwards this plugin does not own.
3
+ *
4
+ * An external forward's identity (`ext-<pid>-<index>`) changes every time the
5
+ * process behind it restarts, so a remark cannot hang off the tunnel id — it
6
+ * would evaporate on the next restart and the row would silently revert to an
7
+ * anonymous port. Remarks are therefore keyed by the local listening port,
8
+ * which is the one part of a forward that survives a restart.
9
+ *
10
+ * Precedence when both exist: a user remark wins over `~/.ssh/forwards.conf`,
11
+ * because the remark is the more recent, more specific statement of intent.
12
+ * Clearing the remark (saving both fields empty) deletes the entry, and the
13
+ * forwards.conf name shows through again — the file stays the user's, and this
14
+ * plugin never rewrites it.
15
+ */
16
+ /** A name/description pair the operator attached to one local port. */
17
+ export interface TunnelRemark {
18
+ name?: string;
19
+ description?: string;
20
+ }
21
+ /** Where remarks live. Separate from the host store: no secret ever lands here. */
22
+ export declare function tunnelRemarksPath(): string;
23
+ /**
24
+ * Read every stored remark, keyed by local port.
25
+ *
26
+ * A corrupt or hand-edited file yields an empty map rather than throwing: the
27
+ * tunnel list is the primary feature, and losing annotations must not take the
28
+ * whole tab down with an exception.
29
+ *
30
+ * @param path - override for tests.
31
+ * @returns remarks keyed by the local port as a string.
32
+ */
33
+ export declare function readTunnelRemarks(path?: string): Record<string, TunnelRemark>;
34
+ /** Replace the whole remarks file (atomic via a 0600 temp file + rename). */
35
+ export declare function writeTunnelRemarks(remarks: Record<string, TunnelRemark>, path?: string): void;
36
+ /**
37
+ * Replace the remark for one port.
38
+ *
39
+ * The pair is replaced wholesale rather than merged: the edit dialog shows both
40
+ * fields at once, so "empty" is an instruction to clear that field, not to keep
41
+ * the old value. When both end up empty the entry is removed entirely, which is
42
+ * how `~/.ssh/forwards.conf` becomes visible again.
43
+ *
44
+ * @param localPort - the listening port that identifies the forward.
45
+ * @param remark - the desired pair; absent fields mean cleared.
46
+ * @param path - override for tests.
47
+ * @returns the stored remark, or undefined when the entry was deleted.
48
+ */
49
+ export declare function setTunnelRemark(localPort: number, remark: TunnelRemark, path?: string): TunnelRemark | undefined;
@@ -0,0 +1,76 @@
1
+ /**
2
+ * Local port-forward tunnels: one loopback-only listener per tunnel, pinned
3
+ * to a pooled connection so an idle sweep never closes it, with per-tunnel
4
+ * socket tracking and stop (single / alias-scoped / all).
5
+ */
6
+ import { type Server as NetServer, type Socket } from 'node:net';
7
+ import type { TunnelInfo } from '../protocol.ts';
8
+ import { type PoolEngine, type PoolRecord } from './connection-pool.ts';
9
+ /** One active tunnel record (server + pinned connection + live sockets). */
10
+ export interface TunnelRecord {
11
+ info: TunnelInfo;
12
+ server: NetServer;
13
+ alias: string;
14
+ /** The pooled connection this tunnel pins; siblings on one alias may share it. */
15
+ record: PoolRecord;
16
+ sockets: Set<Socket>;
17
+ /** Detach the link-death hook startTunnel installs on the pooled client. */
18
+ detachLink?: () => void;
19
+ }
20
+ /** The engine slice the tunnel module needs (adds the tunnel registry). */
21
+ export interface TunnelEngine extends PoolEngine {
22
+ readonly tunnels: Map<string, TunnelRecord>;
23
+ nextTunnelId: number;
24
+ }
25
+ /** Start a local port-forward tunnel (listens on 127.0.0.1 only). */
26
+ export declare function startTunnel(engine: TunnelEngine, alias: string, options: {
27
+ remotePort: number;
28
+ remoteHost?: string;
29
+ localPort?: number;
30
+ name?: string;
31
+ description?: string;
32
+ }): Promise<TunnelInfo>;
33
+ /** All active tunnels. */
34
+ export declare function listTunnels(engine: TunnelEngine): TunnelInfo[];
35
+ /** Fields an editor may change on an existing tunnel. */
36
+ export interface TunnelUpdate {
37
+ /** New service name; an empty string (or null) clears it, letting forwards.conf show through. */
38
+ name?: string | null;
39
+ /** New remark; an empty string (or null) clears it. */
40
+ description?: string | null;
41
+ /** New remote target host. */
42
+ remoteHost?: string;
43
+ /** New remote target port. */
44
+ remotePort?: number;
45
+ /** New local listening port. */
46
+ localPort?: number;
47
+ }
48
+ /** What an edit did, so a caller can tell a rename from a rebuild. */
49
+ export interface TunnelUpdateResult {
50
+ tunnel: TunnelInfo;
51
+ /** True when the forward was torn down and rebuilt because its routing changed. */
52
+ restarted: boolean;
53
+ }
54
+ /**
55
+ * Edit an existing tunnel.
56
+ *
57
+ * A name or remark change is applied to the live record in place — renaming a
58
+ * forward costs nothing and must not interrupt traffic. A routing change cannot
59
+ * be done in place: the listener is bound to the old target, so the forward is
60
+ * stopped and rebuilt from the new parameters, and the caller is told
61
+ * (`restarted: true`) rather than left to guess whether connections dropped.
62
+ *
63
+ * When the rebuild fails the previous forward is already closed. That is
64
+ * reported explicitly instead of surfacing a bare "connect failed", which would
65
+ * read as if the old tunnel were still serving.
66
+ *
67
+ * @param engine - the tunnel engine.
68
+ * @param id - tunnel id to edit.
69
+ * @param patch - fields to change; omitted fields keep their current value.
70
+ * @returns the resulting tunnel and whether it was rebuilt.
71
+ */
72
+ export declare function updateTunnel(engine: TunnelEngine, id: string, patch: TunnelUpdate): Promise<TunnelUpdateResult>;
73
+ /** Stop one tunnel (closes the listener, live sockets, and the pinned connection). */
74
+ export declare function stopTunnel(engine: TunnelEngine, id: string): boolean;
75
+ /** Stop all tunnels (optionally for one alias). */
76
+ export declare function stopAllTunnels(engine: TunnelEngine, alias?: string): number;
@@ -0,0 +1,103 @@
1
+ /**
2
+ * The SSH engine facade: a per-alias persistent connection pool (ssh2) with
3
+ * multi-hop jump support, command execution, PTY shells, SFTP transfers,
4
+ * local port-forward tunnels and cluster execution. The heavy lifting lives
5
+ * in the engine/ modules (connection-pool, pty, sftp, tunnel, cluster); this
6
+ * class composes them behind one new SshEngine instance per plugin apply.
7
+ */
8
+ import type { ClusterResult, ExecResult, SshHostSummary, TestResult, TransferProgress, TunnelInfo } from './protocol.ts';
9
+ import type { HostStore } from './store.ts';
10
+ import { type EngineOptions, type KeyboardInteractiveHandler, type PoolRecord, type ResolvedEngineOptions } from './engine/connection-pool.ts';
11
+ import { type ShellSession } from './engine/pty.ts';
12
+ import { type TunnelRecord, type TunnelUpdate, type TunnelUpdateResult } from './engine/tunnel.ts';
13
+ export type { EngineOptions, KeyboardInteractiveHandler } from './engine/connection-pool.ts';
14
+ export type { ShellSession } from './engine/pty.ts';
15
+ export type { PoolRecord } from './engine/connection-pool.ts';
16
+ export type { TunnelRecord, TunnelUpdate, TunnelUpdateResult } from './engine/tunnel.ts';
17
+ /**
18
+ * The engine. Owns the pool, tunnels, and all operations. One instance per
19
+ * plugin apply; dispose() closes every connection.
20
+ */
21
+ export declare class SshEngine {
22
+ readonly store: HostStore;
23
+ readonly opts: ResolvedEngineOptions;
24
+ readonly pool: Map<string, PoolRecord>;
25
+ readonly acquireQueue: Map<string, Promise<PoolRecord>>;
26
+ readonly tunnels: Map<string, TunnelRecord>;
27
+ nextTunnelId: number;
28
+ private sweepTimer;
29
+ /**
30
+ * @param store - the host config store.
31
+ * @param options - engine knobs (defaults applied).
32
+ */
33
+ constructor(store: HostStore, options?: EngineOptions);
34
+ /**
35
+ * Change the pre-ready ceiling (TCP connect + key exchange + user
36
+ * authentication) for connections opened from now on. A pooled connection
37
+ * keeps serving until it reconnects, because the ceiling governs the
38
+ * connect path only.
39
+ */
40
+ setConnectTimeout(timeoutMs: number): void;
41
+ /** Secret-free host list (filtered by the optional query). */
42
+ list(query?: string): SshHostSummary[];
43
+ /** One host summary by alias. */
44
+ find(alias: string): SshHostSummary | undefined;
45
+ /** Run one command on `alias` (reusing the pooled connection). */
46
+ exec(alias: string, command: string, timeoutMs?: number, signal?: AbortSignal): Promise<ExecResult>;
47
+ /** Run one command against many hosts concurrently. */
48
+ cluster(options: {
49
+ command: string;
50
+ aliases?: string[];
51
+ environment?: string;
52
+ tags?: string[];
53
+ timeoutMs?: number;
54
+ maxWorkers?: number;
55
+ signal?: AbortSignal;
56
+ }): Promise<ClusterResult[]>;
57
+ /** Open a PTY shell session for the web terminal (standalone connection). */
58
+ openShell(alias: string, size: {
59
+ cols: number;
60
+ rows: number;
61
+ }, onKeyboardInteractive?: KeyboardInteractiveHandler): Promise<ShellSession>;
62
+ /** Upload one local file (or directory tree) to a remote path. */
63
+ upload(alias: string, localPath: string, remotePath: string, recursive: boolean, onProgress?: (progress: TransferProgress) => void): Promise<{
64
+ bytes: number;
65
+ files: number;
66
+ }>;
67
+ /** Download one remote file to a local path. */
68
+ download(alias: string, remotePath: string, localPath: string, onProgress?: (progress: TransferProgress) => void): Promise<{
69
+ bytes: number;
70
+ }>;
71
+ /** List a remote directory (file browser). */
72
+ ls(alias: string, path: string): Promise<import('./protocol.ts').RemoteDirEntry[]>;
73
+ /** Start a local port-forward tunnel (listens on 127.0.0.1 only). */
74
+ startTunnel(alias: string, options: {
75
+ remotePort: number;
76
+ remoteHost?: string;
77
+ localPort?: number;
78
+ name?: string;
79
+ description?: string;
80
+ }): Promise<TunnelInfo>;
81
+ /** All active tunnels. */
82
+ listTunnels(): TunnelInfo[];
83
+ /**
84
+ * Edit one tunnel. A name/remark change is applied in place; a routing change
85
+ * rebuilds the forward and reports `restarted: true`.
86
+ */
87
+ updateTunnel(id: string, patch: TunnelUpdate): Promise<TunnelUpdateResult>;
88
+ /** Stop one tunnel (closes the listener, live sockets, and the pinned connection). */
89
+ stopTunnel(id: string): boolean;
90
+ /** Stop all tunnels (optionally for one alias). */
91
+ stopAllTunnels(alias?: string): number;
92
+ /**
93
+ * Drop every live artifact bound to one alias: stop its tunnels and close
94
+ * the pooled connection. Host entries that are deleted or whose connection
95
+ * fields change must never keep serving a stale, previously authenticated
96
+ * connection — the next operation re-connects from the current config.
97
+ */
98
+ dropAlias(alias: string): void;
99
+ /** Probe connectivity with a cross-platform shell command. */
100
+ test(alias: string): Promise<TestResult>;
101
+ /** Close every pooled connection and tunnel. */
102
+ dispose(): void;
103
+ }
@@ -0,0 +1,59 @@
1
+ /**
2
+ * Shared JSON body/response helpers for the host route families: one strict
3
+ * bounded body reader, one lenient bounded body reader, one JSON object
4
+ * narrow, one JSON writer, and the outbound request-init helper that keeps a
5
+ * host fetch body decodable (withIdentityEncoding). Previously the readers
6
+ * were copy-pasted across the
7
+ * package route files (routes.ts, update-routes.ts, mobile-api.ts, and each
8
+ * family's route module) with drifting contracts: body caps ranging 4 KiB to
9
+ * 1 MiB and four distinct overflow behaviors (reject, undefined, null, throw).
10
+ *
11
+ * Packages receive this file as a generated copy via scripts/sync-shared.mjs;
12
+ * edit this shared source and re-run the sync instead of editing a copy.
13
+ * Consumer code is migrated onto it in follow-up waves; no call site changes
14
+ * belong in the same change as its introduction.
15
+ * @module dsh-web-shared/host/http
16
+ */
17
+ import type { IncomingMessage, OutgoingHttpHeaders, ServerResponse } from 'node:http';
18
+ /**
19
+ * Strict bounded body reader: parse a request body of at most maxBytes as
20
+ * JSON.
21
+ * @throws 'body too large' past the cap, or the JSON.parse error for an
22
+ * invalid or empty payload.
23
+ */
24
+ export declare function readBoundedJson(req: IncomingMessage, maxBytes: number): Promise<unknown>;
25
+ /**
26
+ * Lenient bounded body reader: parse a request body as JSON, or null on an
27
+ * empty body, invalid JSON, or a body past maxBytes (default 64 KiB).
28
+ * Overflow destroys the request instead of draining the remainder (no drain
29
+ * call, matching the current repo-wide behavior); callers must not keep
30
+ * reading the request afterwards. With objectOnly, non-JSON-object payloads
31
+ * also yield null.
32
+ */
33
+ export declare function readJsonBody(req: IncomingMessage, opts?: {
34
+ maxBytes?: number;
35
+ objectOnly?: boolean;
36
+ }): Promise<unknown | null>;
37
+ /** Narrow a value to a JSON object, or undefined when it is not one. */
38
+ export declare function asJsonObject(value: unknown): Record<string, unknown> | undefined;
39
+ /**
40
+ * Request init that asks a remote origin for an uncompressed body.
41
+ *
42
+ * The DSH host boots `@deepseek-ai/dsh-http-proxy`, whose top-level import of
43
+ * the npm `undici` copy replaces the legacy `undici.globalDispatcher.1` slot
44
+ * Node's built-in `fetch()` reads. That cross-major wrapper drops the
45
+ * `content-encoding` header and automatic decompression, so a plain fetch
46
+ * resolves to raw gzip/brotli/zstd bytes — compressed noise no JSON or text
47
+ * consumer can read. Every host fetch that parses a remote body must request
48
+ * identity encoding. Caller headers survive; `accept-encoding` is forced to
49
+ * `identity` because a caller value has no decoder behind it in this host.
50
+ * @param init - the caller's request init (signal, headers, method, ...).
51
+ * @returns a copy with `accept-encoding: identity` merged in.
52
+ */
53
+ export declare function withIdentityEncoding(init?: RequestInit): RequestInit;
54
+ /**
55
+ * Write one JSON response. Default headers are the family defaults
56
+ * (content-type and referrer-policy); caller headers are appended or
57
+ * override them.
58
+ */
59
+ export declare function writeJson(res: ServerResponse, status: number, body: unknown, headers?: OutgoingHttpHeaders): void;
@@ -0,0 +1,128 @@
1
+ /**
2
+ * dsh-ssh — host half. Mounts the SSH engine (persistent ssh2 connection
3
+ * pool, exec / PTY shell / SFTP / tunnels / cluster), the /api/dsh-ssh route
4
+ * family plus the terminal WebSocket upgrade, the agent tools (ssh_list,
5
+ * ssh_exec, ssh_upload, ssh_download, ssh_tunnel, ssh_cluster), and a
6
+ * system-prompt announcement. The browser half (./client) renders the host
7
+ * manager and web terminal. Everything rides official NPM SDK packages —
8
+ * no dsh source changes.
9
+ */
10
+ import type { Context } from '@deepseek-ai/cordis';
11
+ import z from '@deepseek-ai/schemastery';
12
+ /** Stable cordis plugin name. */
13
+ export declare const name = "ssh";
14
+ /**
15
+ * Services required before the SSH surfaces can mount.
16
+ *
17
+ * `timer` is required rather than optional: the monitoring loop is armed
18
+ * through it, and a plugin that silently fell back to a bare setInterval
19
+ * would leave a probe timer running after the plugin unloaded. Requiring it
20
+ * makes a profile without the timer service fail to activate this row
21
+ * instead of leaking timers.
22
+ */
23
+ export declare const inject: string[];
24
+ declare module '@deepseek-ai/cordis' {
25
+ interface Events {
26
+ /**
27
+ * Volatile config values were committed into the running instance without a
28
+ * remount (cordis-plugin-loader); dispatched to the owning fiber only.
29
+ * @param paths - the changed config paths, as key arrays.
30
+ * @mode emit
31
+ */
32
+ 'loader/volatile-update'(paths: readonly (readonly string[])[]): void;
33
+ }
34
+ }
35
+ /** Plugin config as a profile patch declares it, before schema resolution. */
36
+ export interface Config {
37
+ /**
38
+ * When true, a system-prompt section announces the SSH plugin to every agent
39
+ * (tools + host store). Off by default to keep prompts clean.
40
+ */
41
+ announceToAgent?: boolean;
42
+ /** Master switch for the plugin (routes, tools, prompt section). */
43
+ enabled?: boolean;
44
+ /**
45
+ * xterm `fontFamily` for the web terminal (issue #577). Empty (default)
46
+ * defers to the CSS chain: `--dsh-ssh-terminal-font`, then the official
47
+ * `--ds-font-family-code` token, then the built-in monospace stack. Set a
48
+ * Nerd Font stack here to render powerline/Nerd glyphs.
49
+ */
50
+ terminalFontFamily?: string;
51
+ /**
52
+ * Ceiling for the whole pre-ready SSH sequence in milliseconds: TCP
53
+ * connect, key exchange and user authentication (default 30000). Raise it
54
+ * for hosts whose password authentication is slow (for example PAM / LDAP
55
+ * behind a distant directory service).
56
+ */
57
+ connectTimeoutMs?: number;
58
+ }
59
+ /** The stable reference a `volatile()` config field resolves to; its owner updates it in place. */
60
+ interface ConfigRef<T> {
61
+ /** @returns the field's current value. */
62
+ get(): T;
63
+ }
64
+ /** One resolved config field: a live reference, or a plain value from a hand-built context. */
65
+ type ConfigField<T> = ConfigRef<T> | T;
66
+ /** The config the Host hands to {@link apply} — the runtime face of {@link Config}. */
67
+ export interface ResolvedConfig {
68
+ announceToAgent?: ConfigField<boolean>;
69
+ enabled?: ConfigField<boolean>;
70
+ terminalFontFamily?: ConfigField<string>;
71
+ connectTimeoutMs?: ConfigField<number>;
72
+ hostKeyPolicy?: ConfigField<'off' | 'tofu' | 'strict'>;
73
+ knownHostsPath?: ConfigField<string>;
74
+ encryptCredentials?: ConfigField<boolean>;
75
+ auditEnabled?: ConfigField<boolean>;
76
+ monitorEnabled?: ConfigField<boolean>;
77
+ monitorIntervalMs?: ConfigField<number>;
78
+ monitorChecks?: ConfigField<string>;
79
+ }
80
+ /**
81
+ * Plugin config schema. Under the 0.1.7 settings model this schema IS the
82
+ * entry's settings page: the Host derives one form per profile entry from it
83
+ * and serves it through the shared configuration forms. Every field is
84
+ * `volatile()`, which is what puts it on that page and what lets an edit reach
85
+ * a running instance without a remount: the loader commits the new value into
86
+ * the field's reference and announces `loader/volatile-update` on this fiber.
87
+ */
88
+ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
89
+ announceToAgent: z<boolean, boolean, "volatile-defined">;
90
+ enabled: z<boolean, boolean, "volatile-defined">;
91
+ terminalFontFamily: z<string, string, "volatile-defined">;
92
+ connectTimeoutMs: z<number, number, "volatile-defined">;
93
+ hostKeyPolicy: z<"off" | "tofu" | "strict", "off" | "tofu" | "strict", "volatile-defined">;
94
+ knownHostsPath: z<string, string, "volatile-defined">;
95
+ encryptCredentials: z<boolean, boolean, "volatile-defined">;
96
+ auditEnabled: z<boolean, boolean, "volatile-defined">;
97
+ monitorEnabled: z<boolean, boolean, "volatile-defined">;
98
+ monitorIntervalMs: z<number, number, "volatile-defined">;
99
+ monitorChecks: z<string, string, "volatile-defined">;
100
+ }>>, Schemastery.ObjectT<NoInfer<{
101
+ announceToAgent: z<boolean, boolean, "volatile-defined">;
102
+ enabled: z<boolean, boolean, "volatile-defined">;
103
+ terminalFontFamily: z<string, string, "volatile-defined">;
104
+ connectTimeoutMs: z<number, number, "volatile-defined">;
105
+ hostKeyPolicy: z<"off" | "tofu" | "strict", "off" | "tofu" | "strict", "volatile-defined">;
106
+ knownHostsPath: z<string, string, "volatile-defined">;
107
+ encryptCredentials: z<boolean, boolean, "volatile-defined">;
108
+ auditEnabled: z<boolean, boolean, "volatile-defined">;
109
+ monitorEnabled: z<boolean, boolean, "volatile-defined">;
110
+ monitorIntervalMs: z<number, number, "volatile-defined">;
111
+ monitorChecks: z<string, string, "volatile-defined">;
112
+ }>>, "plain">;
113
+ /** Model-facing announcement: plugin presence, capabilities, and limits. */
114
+ export declare const SSH_GUIDANCE: string;
115
+ /**
116
+ * Mount the SSH engine, routes, tools, and announcement.
117
+ *
118
+ * The mount guard keys on THIS package's identity, not the upstream one:
119
+ * both plugins register the same HTTP route prefix and the same sidebar
120
+ * row, so they must never share a mount slot — and if an operator has both
121
+ * installed, only one of them may own the routes.
122
+ *
123
+ * @param ctx - host plugin context carrying webServer/tools/systemPrompt.
124
+ * @param config - resolved plugin config (schema defaults applied by the loader).
125
+ */
126
+ export declare const apply: typeof applyImpl;
127
+ declare function applyImpl(ctx: Context, config?: ResolvedConfig): void;
128
+ export {};
@@ -0,0 +1,118 @@
1
+ /**
2
+ * Inspection checks: the vocabulary of what "inspect this fleet" means.
3
+ *
4
+ * The base plugin gives the agent a way to run a command on many hosts at
5
+ * once, but every run is improvised — nothing is defined, nothing is
6
+ * retained, nothing can be compared against last time. That is fine for
7
+ * "what is on this box" and useless for "is the fleet healthy".
8
+ *
9
+ * A check here is a named, typed probe with a command, a parser and a
10
+ * verdict rule. Checks are defined in code (they are part of the product,
11
+ * not user data), so their commands are known-good POSIX shell — the fleet
12
+ * is Linux-only by design, and the probes read only.
13
+ */
14
+ import type { ExecResult } from '../protocol.ts';
15
+ /** How a check's value is judged. */
16
+ export type CheckKind =
17
+ /** A percentage 0-100; the threshold is a watermark. */
18
+ 'percent'
19
+ /** A number compared against a threshold. */
20
+ | 'gauge'
21
+ /** A boolean: does the thing exist / is it running. */
22
+ | 'boolean'
23
+ /** A free-form text value (a version, a mount path). */
24
+ | 'text';
25
+ /** Which way a breach is judged. */
26
+ export type CheckDirection =
27
+ /** High values are bad (disk usage). */
28
+ 'above'
29
+ /** Low values are bad (free space, free memory). */
30
+ | 'below';
31
+ /** One inspection check. */
32
+ export interface Check {
33
+ /** Stable identifier, used in stored results. */
34
+ id: string;
35
+ /** What the check measures, in the operator's language. */
36
+ title: string;
37
+ /** How the value is judged. */
38
+ kind: CheckKind;
39
+ /** Which way a breach goes. */
40
+ direction: CheckDirection;
41
+ /**
42
+ * The breach threshold: a percentage for 'percent', a number for
43
+ * 'gauge', unused for the other kinds.
44
+ */
45
+ threshold?: number;
46
+ /** The read-only command that produces the value. */
47
+ command: string;
48
+ /** Parse the command output into a value. */
49
+ parse: (stdout: string) => number | boolean | string | null;
50
+ /** The unit shown in the panel. */
51
+ unit?: string;
52
+ }
53
+ /** The outcome of one check on one host. */
54
+ export interface CheckResult {
55
+ /** The check id. */
56
+ checkId: string;
57
+ /** The host alias. */
58
+ alias: string;
59
+ /** The parsed value, or null when the probe could not produce one. */
60
+ value: number | boolean | string | null;
61
+ /** Whether the value breaches the threshold. */
62
+ breached: boolean;
63
+ /** The raw output, trimmed, for the operator to read. */
64
+ raw: string;
65
+ /** The error when the command itself failed. */
66
+ error?: string;
67
+ }
68
+ /**
69
+ * The built-in check set.
70
+ *
71
+ * Every command is read-only and POSIX-shell compatible. Nothing installs
72
+ * anything on the remote host and nothing writes to it — an inspection
73
+ * that mutates the fleet is not an inspection.
74
+ */
75
+ export declare const BUILTIN_CHECKS: readonly Check[];
76
+ /**
77
+ * Parse a number out of command output.
78
+ *
79
+ * @param stdout - the raw output.
80
+ * @returns the first number found, or null.
81
+ */
82
+ export declare function parseNumber(stdout: string): number | null;
83
+ /**
84
+ * Find a check by id.
85
+ *
86
+ * @param id - the check id.
87
+ * @returns the check, or undefined.
88
+ */
89
+ export declare function findCheck(id: string): Check | undefined;
90
+ /**
91
+ * Judge one parsed value against a check's threshold.
92
+ *
93
+ * A `null` value never breaches: an unreadable probe is an unknown state,
94
+ * not a healthy one and not a breach either. The caller records the
95
+ * distinction — an unknown value must not be silently counted as healthy.
96
+ *
97
+ * @param check - the check.
98
+ * @param value - the parsed value.
99
+ * @returns whether the value breaches.
100
+ */
101
+ export declare function isBreached(check: Check, value: number | boolean | string | null): boolean;
102
+ /**
103
+ * Turn one exec result into a check result.
104
+ *
105
+ * @param check - the check that was run.
106
+ * @param alias - the host alias.
107
+ * @param result - the exec result.
108
+ * @returns the check result.
109
+ */
110
+ export declare function toCheckResult(check: Check, alias: string, result: ExecResult): CheckResult;
111
+ /**
112
+ * A human-readable rendering of one value.
113
+ *
114
+ * @param check - the check the value belongs to.
115
+ * @param value - the parsed value.
116
+ * @returns the display text.
117
+ */
118
+ export declare function formatValue(check: Check, value: number | boolean | string | null): string;