dsh-ssh-hub 0.0.0-stage → 0.1.9
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.
- package/LICENSE +202 -0
- package/README.md +255 -2
- package/cordis.patch.yml +16 -0
- package/icon.svg +3 -0
- package/lib/client.js +13766 -0
- package/lib/index.js +6727 -0
- package/lib/types/activity/history.d.ts +50 -0
- package/lib/types/alerting/notify.d.ts +89 -0
- package/lib/types/alerting/prompt-summary.d.ts +28 -0
- package/lib/types/alerting/rules.d.ts +135 -0
- package/lib/types/alerting/tools.d.ts +30 -0
- package/lib/types/audit/audit-log.d.ts +84 -0
- package/lib/types/audit/recorder.d.ts +50 -0
- package/lib/types/client/api.d.ts +199 -0
- package/lib/types/client/index.d.ts +45 -0
- package/lib/types/client/locales.d.ts +309 -0
- package/lib/types/client/native-panel.d.ts +70 -0
- package/lib/types/client/panel/ClusterTab.d.ts +7 -0
- package/lib/types/client/panel/DeployTab.d.ts +10 -0
- package/lib/types/client/panel/FleetTab.d.ts +10 -0
- package/lib/types/client/panel/HostFormDialog.d.ts +12 -0
- package/lib/types/client/panel/HostsTab.d.ts +25 -0
- package/lib/types/client/panel/LogsTab.d.ts +10 -0
- package/lib/types/client/panel/SshPanel.d.ts +14 -0
- package/lib/types/client/panel/TerminalTab.d.ts +27 -0
- package/lib/types/client/panel/TransferTab.d.ts +7 -0
- package/lib/types/client/panel/TunnelsTab.d.ts +27 -0
- package/lib/types/client/panel/controller.d.ts +253 -0
- package/lib/types/client/panel/helpers.d.ts +45 -0
- package/lib/types/client/panel/tabs.d.ts +62 -0
- package/lib/types/client/panel/xterm.css.d.ts +2 -0
- package/lib/types/client/settings-binding.d.ts +71 -0
- package/lib/types/deploy/orchestrator.d.ts +158 -0
- package/lib/types/deploy/tools.d.ts +14 -0
- package/lib/types/dsh-home.d.ts +16 -0
- package/lib/types/engine/cluster.d.ts +19 -0
- package/lib/types/engine/connection-pool.d.ts +183 -0
- package/lib/types/engine/proxy-command.d.ts +36 -0
- package/lib/types/engine/pty.d.ts +32 -0
- package/lib/types/engine/sftp.d.ts +20 -0
- package/lib/types/engine/terminal-sessions.d.ts +67 -0
- package/lib/types/engine/tunnel-discovery.d.ts +89 -0
- package/lib/types/engine/tunnel.d.ts +38 -0
- package/lib/types/engine.d.ts +98 -0
- package/lib/types/http.d.ts +59 -0
- package/lib/types/index.d.ts +128 -0
- package/lib/types/inspect/checks.d.ts +118 -0
- package/lib/types/inspect/inspection.d.ts +111 -0
- package/lib/types/inspect/tools.d.ts +50 -0
- package/lib/types/logs/search.d.ts +131 -0
- package/lib/types/logs/tools.d.ts +6 -0
- package/lib/types/loopback.d.ts +64 -0
- package/lib/types/monitor/loop.d.ts +133 -0
- package/lib/types/monitor/metrics.d.ts +151 -0
- package/lib/types/mount-once.d.ts +55 -0
- package/lib/types/protocol.d.ts +518 -0
- package/lib/types/routes.d.ts +82 -0
- package/lib/types/security/known-hosts.d.ts +153 -0
- package/lib/types/security/master-secret.d.ts +157 -0
- package/lib/types/security/redact.d.ts +44 -0
- package/lib/types/security/secrets.d.ts +70 -0
- package/lib/types/ssh-config.d.ts +42 -0
- package/lib/types/store.d.ts +183 -0
- package/lib/types/tool-surface.d.ts +72 -0
- package/lib/types/tools.d.ts +56 -0
- package/locale/en.json +6 -0
- package/locale/zh.json +6 -0
- package/package.json +126 -6
- package/src/activity/history.ts +117 -0
- package/src/alerting/notify.ts +212 -0
- package/src/alerting/prompt-summary.ts +71 -0
- package/src/alerting/rules.ts +281 -0
- package/src/alerting/tools.ts +263 -0
- package/src/audit/audit-log.ts +198 -0
- package/src/audit/recorder.ts +73 -0
- package/src/client/api.ts +752 -0
- package/src/client/css-modules.d.ts +5 -0
- package/src/client/index.ts +150 -0
- package/src/client/locales.ts +634 -0
- package/src/client/native-panel.tsx +141 -0
- package/src/client/panel/ClusterTab.tsx +141 -0
- package/src/client/panel/DeployTab.tsx +314 -0
- package/src/client/panel/FleetTab.tsx +494 -0
- package/src/client/panel/HostFormDialog.tsx +289 -0
- package/src/client/panel/HostsTab.tsx +395 -0
- package/src/client/panel/LogsTab.tsx +208 -0
- package/src/client/panel/SshPanel.tsx +105 -0
- package/src/client/panel/TerminalTab.tsx +550 -0
- package/src/client/panel/TransferTab.tsx +238 -0
- package/src/client/panel/TunnelsTab.tsx +306 -0
- package/src/client/panel/controller.ts +507 -0
- package/src/client/panel/helpers.ts +84 -0
- package/src/client/panel/panel.module.css +1712 -0
- package/src/client/panel/tabs.ts +52 -0
- package/src/client/panel/xterm.css.ts +2 -0
- package/src/client/settings-binding.ts +184 -0
- package/src/deploy/orchestrator.ts +326 -0
- package/src/deploy/tools.ts +225 -0
- package/src/dsh-home.ts +42 -0
- package/src/engine/cluster.ts +60 -0
- package/src/engine/connection-pool.ts +721 -0
- package/src/engine/proxy-command.ts +248 -0
- package/src/engine/pty.ts +78 -0
- package/src/engine/sftp.ts +229 -0
- package/src/engine/terminal-sessions.ts +280 -0
- package/src/engine/tunnel-discovery.ts +352 -0
- package/src/engine/tunnel.ts +205 -0
- package/src/engine.ts +187 -0
- package/src/http.ts +127 -0
- package/src/index.ts +690 -0
- package/src/inspect/checks.ts +251 -0
- package/src/inspect/inspection.ts +321 -0
- package/src/inspect/tools.ts +366 -0
- package/src/logs/search.ts +251 -0
- package/src/logs/tools.ts +160 -0
- package/src/loopback.ts +119 -0
- package/src/monitor/loop.ts +265 -0
- package/src/monitor/metrics.ts +333 -0
- package/src/mount-once.ts +142 -0
- package/src/protocol.ts +528 -0
- package/src/routes.ts +953 -0
- package/src/security/known-hosts.ts +342 -0
- package/src/security/master-secret.ts +334 -0
- package/src/security/redact.ts +119 -0
- package/src/security/secrets.ts +152 -0
- package/src/ssh-config.ts +182 -0
- package/src/store.ts +757 -0
- package/src/tool-surface.ts +96 -0
- package/src/tools.ts +517 -0
|
@@ -0,0 +1,183 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Connection pool: per-alias persistent ssh2 connections with multi-hop jump
|
|
3
|
+
* support, the acquire / dispose / sweep lifecycle, and the pooled exec path.
|
|
4
|
+
*/
|
|
5
|
+
import type { Client, ConnectConfig } from 'ssh2';
|
|
6
|
+
import type { ExecResult, SshHostEntry } from '../protocol.ts';
|
|
7
|
+
import { type HostStore } from '../store.ts';
|
|
8
|
+
import { type HostKeyPolicy } from '../security/known-hosts.ts';
|
|
9
|
+
/** Default engine knobs. */
|
|
10
|
+
export interface EngineOptions {
|
|
11
|
+
/** Connections idle longer than this are closed (ms). */
|
|
12
|
+
idleTimeoutMs?: number;
|
|
13
|
+
/**
|
|
14
|
+
* Ceiling for the whole pre-ready sequence (ms): TCP connect, SSH key
|
|
15
|
+
* exchange and user authentication. Passed to ssh2's `readyTimeout`.
|
|
16
|
+
*/
|
|
17
|
+
connectTimeoutMs?: number;
|
|
18
|
+
/** Keepalive ping interval (ms). */
|
|
19
|
+
keepaliveIntervalMs?: number;
|
|
20
|
+
/** Cap on captured stdout/stderr bytes per exec (ms). */
|
|
21
|
+
maxOutputBytes?: number;
|
|
22
|
+
/** Default exec timeout (ms). */
|
|
23
|
+
defaultExecTimeoutMs?: number;
|
|
24
|
+
/** Default cluster concurrency. */
|
|
25
|
+
defaultMaxWorkers?: number;
|
|
26
|
+
/** SFTP concurrent channel count for transfers. */
|
|
27
|
+
sftpConcurrency?: number;
|
|
28
|
+
/**
|
|
29
|
+
* Host-key verification policy. `off` keeps the base plugin's behaviour
|
|
30
|
+
* (no verification) so an upgrade never locks an existing user out;
|
|
31
|
+
* `tofu` records an unknown host and refuses a changed key; `strict`
|
|
32
|
+
* refuses anything not already in known_hosts.
|
|
33
|
+
*/
|
|
34
|
+
hostKeyPolicy?: HostKeyPolicy;
|
|
35
|
+
/** The known_hosts file consulted for verification. */
|
|
36
|
+
knownHostsPath?: string;
|
|
37
|
+
/** Called when TOFU records a newly trusted host key. */
|
|
38
|
+
onHostKeyRecord?: (host: string, port: number, keyType: string, key: string) => void;
|
|
39
|
+
}
|
|
40
|
+
/**
|
|
41
|
+
* Default ceiling for TCP connect, SSH key exchange and user authentication
|
|
42
|
+
* together (ms). Password authentication behind PAM / LDAP can outlast the
|
|
43
|
+
* previous 15 s ceiling while the server still eventually accepts it.
|
|
44
|
+
*/
|
|
45
|
+
export declare const DEFAULT_CONNECT_TIMEOUT_MS = 30000;
|
|
46
|
+
/**
|
|
47
|
+
* The engine knobs with every optional filled in.
|
|
48
|
+
*
|
|
49
|
+
* `onHostKeyRecord` is deliberately left optional even here: it is a
|
|
50
|
+
* callback, not a knob, and `Required<>` would force every construction
|
|
51
|
+
* site to spell out `undefined`.
|
|
52
|
+
*/
|
|
53
|
+
export type ResolvedEngineOptions = Required<Omit<EngineOptions, 'onHostKeyRecord'>> & Pick<EngineOptions, 'onHostKeyRecord'>;
|
|
54
|
+
/** Default engine knobs (applied when an option is omitted). */
|
|
55
|
+
export declare const DEFAULTS: ResolvedEngineOptions;
|
|
56
|
+
/** One pooled connection record. */
|
|
57
|
+
export interface PoolRecord {
|
|
58
|
+
client: Client;
|
|
59
|
+
/** Jump-chain clients kept alive under the target. */
|
|
60
|
+
hops: Client[];
|
|
61
|
+
idleAt: number;
|
|
62
|
+
/** Pinned connections (tunnels) are never swept. */
|
|
63
|
+
pinned: boolean;
|
|
64
|
+
broken: boolean;
|
|
65
|
+
/** Operations currently running on this connection (sweep guard). */
|
|
66
|
+
inFlight: number;
|
|
67
|
+
}
|
|
68
|
+
/**
|
|
69
|
+
* The slice of the engine the pool and exec paths need. The host class
|
|
70
|
+
* (engine.ts facade) satisfies this structurally.
|
|
71
|
+
*/
|
|
72
|
+
export interface PoolEngine {
|
|
73
|
+
readonly store: HostStore;
|
|
74
|
+
readonly opts: ResolvedEngineOptions;
|
|
75
|
+
readonly pool: Map<string, PoolRecord>;
|
|
76
|
+
readonly acquireQueue: Map<string, Promise<PoolRecord>>;
|
|
77
|
+
}
|
|
78
|
+
/** Build the ssh2 connect config for one entry (key read from disk). */
|
|
79
|
+
export declare function buildConnectConfig(entry: SshHostEntry, sock: ConnectConfig['sock'] | undefined, opts: ResolvedEngineOptions): ConnectConfig;
|
|
80
|
+
/**
|
|
81
|
+
* The default ssh-agent endpoint on Windows: the named pipe the native
|
|
82
|
+
* OpenSSH ssh-agent service listens on. ssh2 connects to a named pipe for any
|
|
83
|
+
* path matching its Windows pipe form, so the default is a real endpoint
|
|
84
|
+
* rather than a protocol name (#1910). PuTTY Pageant is still reachable — it
|
|
85
|
+
* is what the literal `pageant` agent path selects — but it is no longer the
|
|
86
|
+
* assumption.
|
|
87
|
+
*/
|
|
88
|
+
export declare const WINDOWS_AGENT_PIPE = "\\\\.\\pipe\\openssh-ssh-agent";
|
|
89
|
+
/** Resolve the ssh2 agent path for 'agent' auth. */
|
|
90
|
+
export declare function resolveAgentPath(agentPath?: string): string | undefined;
|
|
91
|
+
/**
|
|
92
|
+
* Resolve the ssh-agent endpoint that forwarding brokers signatures through:
|
|
93
|
+
* an explicitly configured agent path wins, then SSH_AUTH_SOCK, then the
|
|
94
|
+
* native OpenSSH named pipe on Windows. Undefined means no endpoint exists on
|
|
95
|
+
* this machine.
|
|
96
|
+
*
|
|
97
|
+
* Forwarding shares the auth resolution on purpose — the endpoint a host
|
|
98
|
+
* signs through is the same one it authenticates with — but it is a separate
|
|
99
|
+
* name so the forwarding path can evolve without touching auth.
|
|
100
|
+
*/
|
|
101
|
+
export declare function resolveForwardAgentPath(agentPath?: string): string | undefined;
|
|
102
|
+
/** Keyboard-interactive handler callback for 2FA / dynamic prompt flow. */
|
|
103
|
+
export type KeyboardInteractiveHandler = (name: string, instructions: string, instructionsLang: string, prompts: Array<{
|
|
104
|
+
prompt: string;
|
|
105
|
+
echo: boolean;
|
|
106
|
+
}>, finish: (responses: string[]) => void) => void;
|
|
107
|
+
/**
|
|
108
|
+
* Name the phase that actually stalled. ssh2 reports every pre-ready timeout
|
|
109
|
+
* as "Timed out while waiting for handshake", including one that expires
|
|
110
|
+
* during user authentication after a completed key exchange.
|
|
111
|
+
*
|
|
112
|
+
* @param timeoutMs - the configured `readyTimeout` (0 disables it).
|
|
113
|
+
* @param handshakeComplete - whether ssh2 completed the key exchange.
|
|
114
|
+
* @returns the operator-facing timeout message.
|
|
115
|
+
*/
|
|
116
|
+
export declare function readyTimeoutMessage(timeoutMs: number | undefined, handshakeComplete: boolean): string;
|
|
117
|
+
/**
|
|
118
|
+
* Whether ssh2 ended the attempt with its pre-ready timeout. The level is the
|
|
119
|
+
* stable discriminator; the message is reused for connect, key exchange and
|
|
120
|
+
* authentication alike.
|
|
121
|
+
*/
|
|
122
|
+
export declare function isReadyTimeout(error: Error): boolean;
|
|
123
|
+
/** Connect one ssh2 client (resolve on ready, reject on error/close). */
|
|
124
|
+
export declare function connectClient(config: ConnectConfig, onKeyboardInteractive?: KeyboardInteractiveHandler): Promise<Client>;
|
|
125
|
+
/** Cap captured output at the configured byte budget (marks truncation). */
|
|
126
|
+
export declare function appendOutput(target: {
|
|
127
|
+
text: string;
|
|
128
|
+
truncated: boolean;
|
|
129
|
+
}, chunk: Buffer, maxBytes: number): void;
|
|
130
|
+
/**
|
|
131
|
+
* Parse an OpenSSH jump hop written as an address: `[user@]host[:port]`
|
|
132
|
+
* (an IPv6 literal must be bracketed). Returns undefined when the value is not
|
|
133
|
+
* an address at all.
|
|
134
|
+
*/
|
|
135
|
+
export declare function parseJumpSpec(spec: string): {
|
|
136
|
+
host: string;
|
|
137
|
+
port?: number;
|
|
138
|
+
user?: string;
|
|
139
|
+
} | undefined;
|
|
140
|
+
/**
|
|
141
|
+
* Resolve one ProxyJump spec: an alias configured in this plugin wins, and any
|
|
142
|
+
* other value is read as an OpenSSH address whose credentials come from the
|
|
143
|
+
* target entry (an ad-hoc hop has no stored auth of its own).
|
|
144
|
+
*
|
|
145
|
+
* An address hop deliberately carries no forwardAgent flag: OpenSSH's
|
|
146
|
+
* ForwardAgent is a per-Host setting and an ad-hoc address was never
|
|
147
|
+
* configured, so it must never inherit the target's opt-in. A hop written as
|
|
148
|
+
* an alias uses that alias's own entry, which is how a user forwards on a
|
|
149
|
+
* bastion on purpose.
|
|
150
|
+
*/
|
|
151
|
+
export declare function resolveHop(engine: PoolEngine, entry: SshHostEntry, spec: string): SshHostEntry;
|
|
152
|
+
/**
|
|
153
|
+
* Build one full jump chain for an entry: hop clients connected through in
|
|
154
|
+
* order, each forwarding a stream to the next destination, ending with the
|
|
155
|
+
* target client. Shared by the pool and standalone shell sessions.
|
|
156
|
+
*
|
|
157
|
+
* A ProxyCommand is the transport that reaches its own host, so the entry's
|
|
158
|
+
* own command seeds the chain when there is no jump chain, and the first hop's
|
|
159
|
+
* command is used when the hop carries one.
|
|
160
|
+
*/
|
|
161
|
+
export declare function connectChain(engine: PoolEngine, entry: SshHostEntry, onKeyboardInteractive?: KeyboardInteractiveHandler): Promise<{
|
|
162
|
+
client: Client;
|
|
163
|
+
hops: Client[];
|
|
164
|
+
}>;
|
|
165
|
+
/** Connect (or reuse) the pooled chain for one alias; pins nothing. */
|
|
166
|
+
export declare function acquire(engine: PoolEngine, alias: string): Promise<PoolRecord>;
|
|
167
|
+
/**
|
|
168
|
+
* Tear down one alias's record. When `record` is given and no longer the
|
|
169
|
+
* pooled record for the alias (a concurrent acquire replaced it), nothing
|
|
170
|
+
* is torn down — the connection belongs to someone else now.
|
|
171
|
+
*/
|
|
172
|
+
export declare function disposeRecord(engine: PoolEngine, alias: string, record?: PoolRecord): void;
|
|
173
|
+
/** End one record's client and hop chain (best-effort, safe to repeat). */
|
|
174
|
+
export declare function endRecordChain(record: PoolRecord): void;
|
|
175
|
+
/** Close connections idle beyond the threshold (skips pinned and in-flight). */
|
|
176
|
+
export declare function sweepPool(engine: PoolEngine): void;
|
|
177
|
+
/**
|
|
178
|
+
* Run `fn` with a live client for `alias`, reconnecting (up to the
|
|
179
|
+
* attempt budget) when the connection broke mid-flight.
|
|
180
|
+
*/
|
|
181
|
+
export declare function withClient<T>(engine: PoolEngine, alias: string, fn: (client: Client) => Promise<T>, attempts?: number, signal?: AbortSignal): Promise<T>;
|
|
182
|
+
/** Run one command on `alias` (reusing the pooled connection). */
|
|
183
|
+
export declare function execCommand(engine: PoolEngine, alias: string, command: string, timeoutMs?: number, signal?: AbortSignal): Promise<ExecResult>;
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* OpenSSH-compatible ProxyCommand transport: run the command with the user's
|
|
3
|
+
* shell and expose its stdio as a Duplex that ssh2 accepts as `sock`.
|
|
4
|
+
*
|
|
5
|
+
* The command comes verbatim from the user's own 0600 store file and runs with
|
|
6
|
+
* the DSH host process's privileges — the same trust the `ssh(1)` client gives
|
|
7
|
+
* the identical line in `~/.ssh/config`.
|
|
8
|
+
*/
|
|
9
|
+
import { type ChildProcess } from 'node:child_process';
|
|
10
|
+
import { Duplex } from 'node:stream';
|
|
11
|
+
/** Token source for one host: the values %h / %p / %r / %n expand to. */
|
|
12
|
+
export interface ProxyTarget {
|
|
13
|
+
host: string;
|
|
14
|
+
port: number;
|
|
15
|
+
user: string;
|
|
16
|
+
/** The name the user addresses this host by (OpenSSH's %n). */
|
|
17
|
+
alias: string;
|
|
18
|
+
}
|
|
19
|
+
/** Expand the OpenSSH ProxyCommand tokens; unknown %X sequences stay verbatim. */
|
|
20
|
+
export declare function expandProxyTokens(command: string, target: ProxyTarget): string;
|
|
21
|
+
/** One running proxy command: its transport plus the process behind it. */
|
|
22
|
+
export interface ProxyCommandProcess {
|
|
23
|
+
/** The duplex transport handed to ssh2 as `sock`. */
|
|
24
|
+
stream: Duplex;
|
|
25
|
+
/** The spawned shell; killing the stream kills it (and its process group). */
|
|
26
|
+
child: ChildProcess;
|
|
27
|
+
}
|
|
28
|
+
/**
|
|
29
|
+
* Start one ProxyCommand and bridge its stdio into a Duplex.
|
|
30
|
+
*
|
|
31
|
+
* Failure modes are reported through the stream: a spawn error, or an exit
|
|
32
|
+
* before the SSH handshake finished, destroys it with the exit status and the
|
|
33
|
+
* tail of the command's stderr instead of letting ssh2 wait for its own
|
|
34
|
+
* `readyTimeout`.
|
|
35
|
+
*/
|
|
36
|
+
export declare function startProxyCommand(rawCommand: string, target: ProxyTarget): ProxyCommandProcess;
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* PTY shell sessions for the web terminal: a standalone (non-pooled)
|
|
3
|
+
* ssh2 connection with a long-lived shell channel, resize, and pausable
|
|
4
|
+
* output delivery.
|
|
5
|
+
*/
|
|
6
|
+
import { type KeyboardInteractiveHandler, type PoolEngine } from './connection-pool.ts';
|
|
7
|
+
/** A live PTY shell session. */
|
|
8
|
+
export interface ShellSession {
|
|
9
|
+
/** Assign to receive remote output. */
|
|
10
|
+
onData?: (data: Buffer) => void;
|
|
11
|
+
/** Assign to be notified when the channel closes. */
|
|
12
|
+
onExit?: (code: number | null, error?: string) => void;
|
|
13
|
+
/** Write raw input to the shell. */
|
|
14
|
+
send(data: string): void;
|
|
15
|
+
/** Resize the remote PTY. */
|
|
16
|
+
resize(cols: number, rows: number): void;
|
|
17
|
+
/** Close the session and its channel. */
|
|
18
|
+
close(): void;
|
|
19
|
+
/** Pause remote output delivery (transport backpressure). */
|
|
20
|
+
pause(): void;
|
|
21
|
+
/** Resume remote output delivery. */
|
|
22
|
+
resume(): void;
|
|
23
|
+
}
|
|
24
|
+
/**
|
|
25
|
+
* Open a PTY shell session for the web terminal (standalone connection).
|
|
26
|
+
* The shell is a long-lived exclusive stream: it uses its own connection so
|
|
27
|
+
* closing it can never tear down a pooled exec/tunnel sharing the alias.
|
|
28
|
+
*/
|
|
29
|
+
export declare function openShell(engine: PoolEngine, alias: string, size: {
|
|
30
|
+
cols: number;
|
|
31
|
+
rows: number;
|
|
32
|
+
}, onKeyboardInteractive?: KeyboardInteractiveHandler): Promise<ShellSession>;
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* SFTP transfers: upload (file or recursive tree), single-file download, and
|
|
3
|
+
* remote directory listing. Every channel is opened once per operation and
|
|
4
|
+
* released exactly once so sshd's MaxSessions cap is never exhausted.
|
|
5
|
+
*/
|
|
6
|
+
import type { RemoteDirEntry, TransferProgress } from '../protocol.ts';
|
|
7
|
+
import { type PoolEngine } from './connection-pool.ts';
|
|
8
|
+
/** Walk a local directory, collecting relative paths of every file. */
|
|
9
|
+
export declare function walkLocalDir(root: string): string[];
|
|
10
|
+
/** Upload one local file (or directory tree) to a remote path. */
|
|
11
|
+
export declare function upload(engine: PoolEngine, alias: string, localPath: string, remotePath: string, recursive: boolean, onProgress?: (progress: TransferProgress) => void): Promise<{
|
|
12
|
+
bytes: number;
|
|
13
|
+
files: number;
|
|
14
|
+
}>;
|
|
15
|
+
/** Download one remote file to a local path. */
|
|
16
|
+
export declare function download(engine: PoolEngine, alias: string, remotePath: string, localPath: string, onProgress?: (progress: TransferProgress) => void): Promise<{
|
|
17
|
+
bytes: number;
|
|
18
|
+
}>;
|
|
19
|
+
/** List a remote directory (file browser). */
|
|
20
|
+
export declare function ls(engine: PoolEngine, alias: string, path: string): Promise<RemoteDirEntry[]>;
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
import { WebSocket } from 'ws';
|
|
2
|
+
import type { KeyboardInteractiveHandler } from './connection-pool.ts';
|
|
3
|
+
import type { ShellSession } from './pty.ts';
|
|
4
|
+
/** What the registry needs from the engine (swappable in tests). */
|
|
5
|
+
export interface TerminalSessionDeps {
|
|
6
|
+
/** Open one PTY shell for the alias (engine.openShell). */
|
|
7
|
+
openShell(alias: string, size: {
|
|
8
|
+
cols: number;
|
|
9
|
+
rows: number;
|
|
10
|
+
}, onKeyboardInteractive?: KeyboardInteractiveHandler): Promise<ShellSession>;
|
|
11
|
+
/** @returns the current time (defaults to Date.now). */
|
|
12
|
+
now?: () => number;
|
|
13
|
+
/** Bounded scrollback per session. */
|
|
14
|
+
maxBufferBytes?: number;
|
|
15
|
+
/** Idle window before a detached session is reaped. */
|
|
16
|
+
idleMs?: number;
|
|
17
|
+
/** Grace window an exited session is kept for reattaching views. */
|
|
18
|
+
exitGraceMs?: number;
|
|
19
|
+
}
|
|
20
|
+
/**
|
|
21
|
+
* The host's terminal session table: open one session per connect, attach any
|
|
22
|
+
* number of sockets, and keep the shell alive across detach.
|
|
23
|
+
*/
|
|
24
|
+
export declare class TerminalSessionRegistry {
|
|
25
|
+
private readonly sessions;
|
|
26
|
+
private readonly deps;
|
|
27
|
+
private readonly maxBufferBytes;
|
|
28
|
+
private readonly idleMs;
|
|
29
|
+
private readonly exitGraceMs;
|
|
30
|
+
constructor(deps: TerminalSessionDeps);
|
|
31
|
+
/** Open a new session for the alias and attach the requesting socket to it. */
|
|
32
|
+
open(ws: WebSocket, alias: string, size: {
|
|
33
|
+
cols: number;
|
|
34
|
+
rows: number;
|
|
35
|
+
}): Promise<void>;
|
|
36
|
+
/**
|
|
37
|
+
* Attach a socket to an existing session, replaying its scrollback first.
|
|
38
|
+
* @returns false when the session is unknown (expired or already reaped).
|
|
39
|
+
*/
|
|
40
|
+
attach(ws: WebSocket, sessionId: string, size: {
|
|
41
|
+
cols: number;
|
|
42
|
+
rows: number;
|
|
43
|
+
}): boolean;
|
|
44
|
+
/** End every session (host teardown, plugin dispose). */
|
|
45
|
+
dispose(): void;
|
|
46
|
+
/** Number of live sessions (introspection for tests and diagnostics). */
|
|
47
|
+
size(): number;
|
|
48
|
+
/** Wire one socket's frames and lifecycle onto a session. */
|
|
49
|
+
private bind;
|
|
50
|
+
/** Remove a socket from its session, keeping the shell alive. */
|
|
51
|
+
private detach;
|
|
52
|
+
/** End the session a socket is attached to (explicit close from the view). */
|
|
53
|
+
private end;
|
|
54
|
+
/** Mark a session exited and keep it briefly so a reattaching view sees it. */
|
|
55
|
+
private finish;
|
|
56
|
+
/** Append output to the replay buffer, trimmed to the byte cap. */
|
|
57
|
+
private pushOutput;
|
|
58
|
+
/** Broadcast one frame to every attached socket, honoring backpressure. */
|
|
59
|
+
private send;
|
|
60
|
+
private sendTo;
|
|
61
|
+
/** Pause while any attached socket is backed up; resume once all drained. */
|
|
62
|
+
private applyBackpressure;
|
|
63
|
+
/** Answer a keyboard-interactive challenge through whoever is attached. */
|
|
64
|
+
private keyboardInteractive;
|
|
65
|
+
private scheduleReap;
|
|
66
|
+
private clearReap;
|
|
67
|
+
}
|
|
@@ -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,38 @@
|
|
|
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
|
+
/** Stop one tunnel (closes the listener, live sockets, and the pinned connection). */
|
|
36
|
+
export declare function stopTunnel(engine: TunnelEngine, id: string): boolean;
|
|
37
|
+
/** Stop all tunnels (optionally for one alias). */
|
|
38
|
+
export declare function stopAllTunnels(engine: TunnelEngine, alias?: string): number;
|
|
@@ -0,0 +1,98 @@
|
|
|
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 } 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 } 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
|
+
/** Stop one tunnel (closes the listener, live sockets, and the pinned connection). */
|
|
84
|
+
stopTunnel(id: string): boolean;
|
|
85
|
+
/** Stop all tunnels (optionally for one alias). */
|
|
86
|
+
stopAllTunnels(alias?: string): number;
|
|
87
|
+
/**
|
|
88
|
+
* Drop every live artifact bound to one alias: stop its tunnels and close
|
|
89
|
+
* the pooled connection. Host entries that are deleted or whose connection
|
|
90
|
+
* fields change must never keep serving a stale, previously authenticated
|
|
91
|
+
* connection — the next operation re-connects from the current config.
|
|
92
|
+
*/
|
|
93
|
+
dropAlias(alias: string): void;
|
|
94
|
+
/** Probe connectivity with a cross-platform shell command. */
|
|
95
|
+
test(alias: string): Promise<TestResult>;
|
|
96
|
+
/** Close every pooled connection and tunnel. */
|
|
97
|
+
dispose(): void;
|
|
98
|
+
}
|
|
@@ -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;
|