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,71 @@
1
+ /**
2
+ * Settings reader of the dsh-ssh browser half.
3
+ *
4
+ * The plugin's browser half owns one preference: the xterm `fontFamily` the
5
+ * panel applies to its terminals. Under the 0.1.7 settings model that field
6
+ * belongs to the plugin's own profile entry (its Cordis Config schema), and
7
+ * the browser surface addresses settings as one form per profile entry id — so
8
+ * the entry has to be resolved before its section can be read:
9
+ *
10
+ * - the family binder (`ctx.get('webUiSettings')`, published while
11
+ * dsh-web-settings is loaded) resolves the dsh-ssh namespace to its entry id
12
+ * through the Host bridge and hands back the native shared form;
13
+ * - without that group the shared configuration forms serve the form directly,
14
+ * and the entry is recognised by the one field this plugin's own schema
15
+ * declares: the entry whose resolved section carries `terminalFontFamily`.
16
+ */
17
+ import type { Context as ClientContext } from '@deepseek-ai/cordis';
18
+ import type { ConfigForm, ConfigFormSnapshot } from '@deepseek-ai/dsh-client-ui-settings/client';
19
+ /** Domain-owned description of one settings namespace a family surface binds. */
20
+ export interface ConfigFormSpec<T> {
21
+ /** Settings namespace the surface edits. */
22
+ namespace: string;
23
+ /**
24
+ * Narrow one wire section; undefined keeps the section the Host resolved.
25
+ * The shared form already validates against the namespace's serialized
26
+ * schema, so a decoder exists only to narrow beyond it.
27
+ */
28
+ decode?: (section: unknown) => T | undefined;
29
+ }
30
+ declare module '@deepseek-ai/cordis' {
31
+ interface Context {
32
+ /**
33
+ * Optional family settings binder provided by dsh-web-settings; absent when
34
+ * that group plugin is not installed, so callers fall back to the shared
35
+ * configuration forms service (`ctx.configForms`).
36
+ */
37
+ webUiSettings?: {
38
+ bind<S>(spec: ConfigFormSpec<S>): ConfigForm<S>;
39
+ };
40
+ }
41
+ }
42
+ /** The read face this plugin needs from its own settings entry. */
43
+ export interface SettingsReader<T> {
44
+ /** @returns the current snapshot (stable reference until the next change). */
45
+ getSnapshot(): ConfigFormSnapshot<T>;
46
+ /** Observe snapshot replacements. */
47
+ subscribe(listener: () => void): () => void;
48
+ }
49
+ /** A reader plus the release of every subscription it installed. */
50
+ export interface SettingsBinding<T> extends SettingsReader<T> {
51
+ /** Release the reader's subscriptions; later calls are no-ops. */
52
+ dispose(): void;
53
+ }
54
+ /**
55
+ * Bind this plugin's settings reader.
56
+ *
57
+ * `configForms` is deliberately read with `ctx.get` rather than declared in
58
+ * the client `inject` list. Declaring an optional service as a dependency
59
+ * makes the whole client fiber wait for it forever when the family does not
60
+ * ship it, and the panel then never mounts at all — a missing settings
61
+ * service would cost the entire panel, which is far too high a price for one
62
+ * terminal-font preference. Both paths below are optional by design: with
63
+ * neither present the reader reports `undefined`, and the panel uses its CSS
64
+ * font chain.
65
+ *
66
+ * @param ctx - client context carrying the family binder and/or the shared forms service.
67
+ * @param namespace - the family settings namespace this plugin owns.
68
+ * @param field - the field this plugin's own schema declares, used to recognise its entry when the family binder is absent.
69
+ * @returns the reader and the release of its subscriptions.
70
+ */
71
+ export declare function bindSettingsReader<T>(ctx: ClientContext, namespace: string, field: string): SettingsBinding<T>;
@@ -0,0 +1,158 @@
1
+ /**
2
+ * Deployment orchestration: roll a change out to a fleet in batches, check
3
+ * each batch, and roll back the batch that failed.
4
+ *
5
+ * The design constraint that shapes everything here: a rollout that cannot
6
+ * be undone is a deployment that only works on the happy path. So the
7
+ * orchestrator refuses to call a deployment successful unless it can also
8
+ * describe how to undo it, and it reports "cannot roll back" honestly when
9
+ * there is no previous version to roll back to — rather than pretending the
10
+ * batch is fine.
11
+ *
12
+ * A plan is:
13
+ * - a set of target hosts (selected like every other fleet operation)
14
+ * - the steps to run on each host (upload / exec)
15
+ * - a health probe run after the steps
16
+ * - a rollback command, run when the health probe fails
17
+ *
18
+ * Rollback is per BATCH, not per host: a batch that came up unhealthy is
19
+ * rolled back as a unit, because half a batch rolled back and half not is
20
+ * the worst possible state to hand an operator.
21
+ */
22
+ import type { SshEngine } from '../engine.ts';
23
+ /** One step of a deployment. */
24
+ export interface DeployStep {
25
+ /** A short name for the step (shown in the report). */
26
+ name: string;
27
+ /** The command to run on the remote host. */
28
+ command: string;
29
+ /**
30
+ * The command that undoes this step.
31
+ *
32
+ * Without it the step cannot be rolled back, and the orchestrator says so
33
+ * instead of silently leaving the host in the broken state.
34
+ */
35
+ rollbackCommand?: string;
36
+ }
37
+ /** A health probe run after the steps. */
38
+ export interface HealthCheck {
39
+ /** The command to run. */
40
+ command: string;
41
+ /** The expected exit code (default 0). */
42
+ expectExitCode?: number;
43
+ /** How long to wait for the service to come up before probing (ms). */
44
+ settleMs?: number;
45
+ }
46
+ /** A deployment plan. */
47
+ export interface DeployPlan {
48
+ /** A stable name for the plan. */
49
+ id: string;
50
+ /** A one-line description. */
51
+ description?: string;
52
+ /** The steps, in order. */
53
+ steps: DeployStep[];
54
+ /** The probe run after the steps. */
55
+ healthCheck?: HealthCheck;
56
+ /** How many hosts to deploy to at once. */
57
+ batchSize?: number;
58
+ /** Per-command timeout (ms). */
59
+ timeoutMs?: number;
60
+ /** Stop the rollout at the first failing batch. */
61
+ stopOnFailure?: boolean;
62
+ }
63
+ /** The outcome for one host. */
64
+ export interface DeployHostResult {
65
+ alias: string;
66
+ ok: boolean;
67
+ /** The exit code of the last step. */
68
+ exitCode?: number | null;
69
+ /** Whether the health probe passed. */
70
+ healthy?: boolean;
71
+ /** Whether a rollback was attempted. */
72
+ rolledBack?: boolean;
73
+ /** Whether the rollback succeeded. */
74
+ rollbackOk?: boolean;
75
+ /** The error message, when the host failed. */
76
+ error?: string;
77
+ /** The health probe output, for the operator to read. */
78
+ healthOutput?: string;
79
+ }
80
+ /** The outcome for one batch. */
81
+ export interface DeployBatchResult {
82
+ /** The batch index, starting at 1. */
83
+ index: number;
84
+ /** The hosts in this batch. */
85
+ aliases: string[];
86
+ /** The per-host results. */
87
+ results: DeployHostResult[];
88
+ /** Whether every host in the batch came up healthy. */
89
+ ok: boolean;
90
+ }
91
+ /** The outcome of a whole deployment. */
92
+ export interface DeployResult {
93
+ planId: string;
94
+ ok: boolean;
95
+ batches: DeployBatchResult[];
96
+ /** The hosts that were deployed to. */
97
+ targets: string[];
98
+ /** The hosts that were skipped because an earlier batch failed. */
99
+ skipped: string[];
100
+ /** How long the whole rollout took. */
101
+ durationMs: number;
102
+ /** Why the deployment failed, when it did. */
103
+ error?: string;
104
+ }
105
+ /** The default batch size when a plan does not set one. */
106
+ export declare const DEFAULT_BATCH_SIZE = 5;
107
+ /**
108
+ * Split a list into batches.
109
+ *
110
+ * @param items - the items to split.
111
+ * @param size - the batch size.
112
+ * @returns the batches.
113
+ */
114
+ export declare function chunk<T>(items: T[], size: number): T[][];
115
+ /**
116
+ * Run one deployment plan against the given hosts.
117
+ *
118
+ * @param engine - the SSH engine.
119
+ * @param plan - the plan.
120
+ * @param targets - the host aliases, in rollout order.
121
+ * @returns the deployment outcome.
122
+ */
123
+ export declare function deploy(engine: SshEngine, plan: DeployPlan, targets: string[]): Promise<DeployResult>;
124
+ /**
125
+ * Deploy to one host: run the steps, then the health probe, then roll back
126
+ * if the probe failed.
127
+ *
128
+ * @param engine - the SSH engine.
129
+ * @param plan - the plan.
130
+ * @param alias - the host alias.
131
+ * @param timeoutMs - the per-command timeout.
132
+ * @returns the per-host outcome.
133
+ */
134
+ export declare function deployHost(engine: SshEngine, plan: DeployPlan, alias: string, timeoutMs: number): Promise<DeployHostResult>;
135
+ /**
136
+ * Roll one host back to the previous version.
137
+ *
138
+ * A rollback is only possible when the plan declares a rollback command for
139
+ * every step. When it does not, the orchestrator says so plainly: the
140
+ * host is left in the failed state and the operator has to intervene.
141
+ *
142
+ * @param engine - the SSH engine.
143
+ * @param plan - the plan.
144
+ * @param alias - the host alias.
145
+ * @param timeoutMs - the per-command timeout.
146
+ * @returns whether a rollback was attempted and whether it worked.
147
+ */
148
+ export declare function rollbackHost(engine: SshEngine, plan: DeployPlan, alias: string, timeoutMs: number): Promise<{
149
+ attempted: boolean;
150
+ ok: boolean;
151
+ }>;
152
+ /**
153
+ * A human-readable rendering of a deployment outcome.
154
+ *
155
+ * @param result - the deployment outcome.
156
+ * @returns the report text.
157
+ */
158
+ export declare function renderDeploy(result: DeployResult): string;
@@ -0,0 +1,14 @@
1
+ /**
2
+ * Agent tool for deployment orchestration.
3
+ *
4
+ * The tool is deliberately plan-driven: the agent supplies the steps, the
5
+ * health probe and the rollback commands, and the orchestrator runs them in
6
+ * batches. A tool that invented a deployment shape would be a tool that
7
+ * deployed the wrong thing confidently.
8
+ */
9
+ import type { SshEngine } from '../engine.ts';
10
+ import { renderDeploy } from './orchestrator.ts';
11
+ import type { AuditRecorder } from '../audit/recorder.ts';
12
+ /** The deployment tool. */
13
+ export declare function hubDeployTool(engine: SshEngine, audit?: AuditRecorder): import("@deepseek-ai/dsh-tools").ToolDefinition;
14
+ export { renderDeploy };
@@ -0,0 +1,16 @@
1
+ /**
2
+ * DSH_HOME resolution shared by the plugin family's Host halves: the
3
+ * environment override wins, the platform home fallback follows. Mirrors
4
+ * what dsh-pet and dsh-liangshen each used to implement locally.
5
+ */
6
+ /** Expand a leading ~ (or ~user) in a path, platform-style. */
7
+ export declare function expandHome(path: string, home?: string): string;
8
+ /**
9
+ * Resolve the DSH home directory.
10
+ * @param env - process environment to read DSH_HOME from.
11
+ * @param home - platform home directory fallback (test seam).
12
+ * @returns the absolute DSH home path.
13
+ */
14
+ export declare function resolveDshHome(env?: NodeJS.ProcessEnv, home?: string): string;
15
+ /** Resolve the DSH home directory from the live environment. */
16
+ export declare function dshHome(): string;
@@ -0,0 +1,19 @@
1
+ /**
2
+ * Cluster execution: run one command concurrently across selected hosts; the
3
+ * caller must provide at least one non-empty aliases / environment / tags filter.
4
+ */
5
+ import type { ClusterResult } from '../protocol.ts';
6
+ import { type PoolEngine } from './connection-pool.ts';
7
+ interface ClusterOptions {
8
+ command: string;
9
+ aliases?: string[];
10
+ environment?: string;
11
+ tags?: string[];
12
+ timeoutMs?: number;
13
+ maxWorkers?: number;
14
+ /** Caller cancellation, forwarded to every host's command. */
15
+ signal?: AbortSignal;
16
+ }
17
+ /** Run one command against many hosts concurrently. */
18
+ export declare function cluster(engine: PoolEngine, options: ClusterOptions): Promise<ClusterResult[]>;
19
+ export {};
@@ -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
+ }