From 848f928f24cdeb1e23979907b0ce6b72a62ec751 Mon Sep 17 00:00:00 2001 From: cmp-202 Date: Sun, 15 Nov 2026 15:15:59 +1300 Subject: [PATCH 01/13] feat!: ssh2 forwardOut host hops and always-on command timeout - Replace the nested ssh command with real ssh2 connections opened through the parent connection's forwardOut channel. Remove server.ssh, the jump-host credential copy, and the nested prompt/command helpers. - Track hosts as an ancestor record stack with per-record listeners and timers. Contain hop failures, advance past failed primaries, and finalize each visited host once. - Arm the command idle timeout when a command is written, reset it on data, and cancel it when a prompt is detected. Remove the commandStartTimeout option and details.noOutput. - Fix _sanitizeResponse for long commands whose PTY redraw places a prompt before the echoed command. - Add host traversal and fault live tests, module target selection for src/lib/baseline, and update the README and design docs. --- .env-example | 17 +- README.md | 81 +- REFACTORING.md | 10 +- docs/API-BASELINE.md | 33 +- docs/ERROR-HANDLING.md | 12 +- docs/NEXT-HOST-CONNECTION.md | 1761 ++++++++++++++++++++ lib/ssh2shell.js | 2026 ++++++++++++++--------- lib/ssh2shell/defaults.js | 15 +- lib/ssh2shell/ssh-command.js | 124 -- lib/ssh2shell/util.js | 12 - scripts/run-live.js | 63 +- src/ssh2shell.js | 2026 ++++++++++++++--------- src/ssh2shell/defaults.js | 15 +- src/ssh2shell/ssh-command.js | 124 -- src/ssh2shell/util.js | 12 - test/README.md | 79 +- test/certs/README.md | 9 +- test/live/bash_script.js | 22 +- test/live/chaining.js | 27 +- test/live/close_from_handler.js | 2 +- test/live/command_timeout.js | 2 +- test/live/fingerprint.js | 2 +- test/live/graceful_close.js | 14 +- test/live/host_faults.js | 202 +++ test/live/host_traversal.js | 217 +++ test/live/keyboard-interactive.js | 2 +- test/live/lots_of_commands.js | 2 +- test/live/multiple_primary_hosts.js | 2 +- test/live/notifications.js | 2 +- test/live/pipe.js | 2 +- test/live/private_key.js | 2 +- test/live/progress.js | 2 +- test/live/prompt_response.js | 2 +- test/live/simple.js | 2 +- test/live/ssh_user_command.js | 2 +- test/live/stop_multiple_hosts.js | 2 +- test/live/stop_on_failure.js | 2 +- test/live/sudo_no_pass.js | 2 +- test/live/sudo_rejected.js | 2 +- test/live/sudo_su.js | 2 +- test/live/timeout.js | 2 +- test/live/timeout_retries.js | 2 +- test/live/transport_drop.js | 2 +- test/live/tunnel.js | 18 +- test/live/tunnel_3_hop.js | 25 +- test/provision/README.md | 7 +- test/provision/provision.js | 31 +- test/unit/api-baseline.test.js | 42 +- test/unit/command-flow.test.js | 30 +- test/unit/command-response.test.js | 40 + test/unit/command-start-timeout.test.js | 143 +- test/unit/error-handling.test.js | 45 +- test/unit/errors.test.js | 10 +- test/unit/helpers/fake-ssh2.js | 58 + test/unit/host-hop.test.js | 250 +++ test/unit/hosts.test.js | 128 +- test/unit/port-semantics.test.js | 9 - test/unit/prompt-regex.test.js | 16 - test/unit/prompts.test.js | 108 -- test/unit/shutdown.test.js | 56 +- test/unit/ssh-connect.test.js | 316 ---- test/unit/timeout-retries.test.js | 1 - test/unit/timers.test.js | 24 +- test/utils/module-target.js | 28 + test/utils/module.js | 13 + 65 files changed, 5705 insertions(+), 2636 deletions(-) create mode 100644 docs/NEXT-HOST-CONNECTION.md delete mode 100644 lib/ssh2shell/ssh-command.js delete mode 100644 src/ssh2shell/ssh-command.js create mode 100644 test/live/host_faults.js create mode 100644 test/live/host_traversal.js create mode 100644 test/unit/host-hop.test.js delete mode 100644 test/unit/ssh-connect.test.js create mode 100644 test/utils/module-target.js create mode 100644 test/utils/module.js diff --git a/.env-example b/.env-example index 90067e2..7259f25 100644 --- a/.env-example +++ b/.env-example @@ -1,19 +1,18 @@ +# Live tests and provisioning target: src (development), lib (release build), +# baseline (regression fixture), or a path relative to the repository root. +SSH2SHELL_MODULE=src + # Primary host (server1) HOST=192.168.44.10 PORT=22 USER_NAME=tester PASSWORD=password -# Private key authentication (test/live/private_key.js) and hop auth +# Private key authentication (test/live/private_key.js) and `forwardOut` hops. +# Hops use the runner's local key, so this is the only key path the tests need. PRIVATE_KEY_PATH=test/certs/test_ed25519 KEY_PASSPHRASE= -# Path to the private key as it exists on the jump host(s), used by nested -# `ssh -i` hops. Override these when the key is installed elsewhere or under a -# different name. They must be absolute paths on the jump host. -HOP_KEY_PATH=/home/tester/.ssh/id_ed25519 -HOP2_KEY_PATH=/home/tester/.ssh/id_ed25519 - # Host fingerprint verification (test/live/fingerprint.js) # Leave empty to print the hash and accept the first connection, then pin it. EXPECTED_HOST_HASH= @@ -33,8 +32,8 @@ NOPASSWD_USER=nopasswd NOPASSWD_PASSWORD=nopasswdpassword # Nested, tunnelled, and chained hosts -# The test key authenticates these hosts. The *_PASSWORD values are only -# needed if you switch a test back to password authentication. +# The local test key authenticates these hosts through `forwardOut`. The +# *_PASSWORD values are only needed if you switch a test to password auth. SERVER2_HOST=192.168.44.11 SERVER2_PORT=22 SERVER2_USER_NAME=tester diff --git a/README.md b/README.md index b31a138..ed89635 100644 --- a/README.md +++ b/README.md @@ -264,18 +264,17 @@ payload would remain in the response. Set `disableASCIIFilter` to keep them. | Property | Type | Default | Description | | --- | --- | --- | --- | -| `idleTimeOut` | number | `5000` | Milliseconds of silence before the command is treated as timed out. Every `onData` event resets the timer. | -| `dataIdleTimeOut` | number | `500` | Milliseconds of silence used to decide that a response burst has ended. | -| `commandStartTimeout` | boolean | `false` | Arm `idleTimeOut` as soon as a command is written, so a command that never produces output still times out. | +| `idleTimeOut` | number | `5000` | Milliseconds of silence before the command is treated as timed out. The timer starts when a command is written, resets on every `onData` event, and is cancelled by prompt detection. | +| `dataIdleTimeOut` | number | `500` | Milliseconds of silence used to decide that a response burst has ended. Keep it below `idleTimeOut`. | | `commandTimeoutRetries` | number | `0` | Number of times to re-arm `commandTimeout` after a non-final attempt. `0` preserves the single-timeout behavior. | `idleTimeOut` is an inactivity timeout, not a limit on how long a command may -run. Every `onData` event resets the timer, so a command that keeps producing -output stays alive. When no data has arrived for `idleTimeOut` milliseconds, the -`commandTimeout` event fires with a fifth `details` argument: -`{ attempt, maxRetries, final, noOutput }`. `noOutput` is `true` when the command -has not produced any data yet, which distinguishes a silent command from a -missed prompt. +run. The timer starts when the command is written, so a command that never +produces output still times out. Every `onData` event resets the timer, so a +command that keeps producing output stays alive. A detected prompt cancels the +timer, and the command completes normally. When no prompt has been detected for +`idleTimeOut` milliseconds, the `commandTimeout` event fires with a fifth +`details` argument: `{ attempt, maxRetries, final }`. The library owns the attempt count. With `commandTimeoutRetries` set, it re-arms the timer after each non-final attempt; the handler only reacts. The @@ -294,14 +293,16 @@ onCommandTimeout(command, response, stream, connection, details) { } ``` -The idle timer is armed by incoming data. A command that produces no output at -all is not covered by `commandTimeout` unless you opt in with -`commandStartTimeout: true`, which arms the timer when the command is written. -The timeout details then report `noOutput: true`. Without the option, use a -server keepalive or an external timeout for completely silent commands. +The idle timer is armed when the command is written, so a command that produces +no output still times out like any other command that never returns to the +prompt. A command that returns to the prompt without output is a normal +completion, not a timeout. The timeout does not distinguish the two cases in its +payload; inspect `response` if a handler needs to. `dataIdleTimeOut` is the response-settling delay. It groups stream chunks into -one response before prompt matching. It is not the command timeout. +one response before prompt matching. It is not the command timeout. Keep it +below `idleTimeOut`; prompt detection cancels the idle timer, but the settle +delay must run first. `idleTime` is accepted as a legacy alias for `idleTimeOut`. You can also set `SSH.idleTime` or `SSH.dataIdleTime` on the instance before `connect()`; a host @@ -339,8 +340,8 @@ with `SSH.on(...)` run for every host, in parallel with any host handler. | `onData` | `data` | Raw data arrives from the stream. | | `onStderrData` | `data` | Data arrives on stderr. | | `onCommandProcessing` | `command, response, sshObj, stream` | Output arrives before the prompt is detected. | -| `onCommandComplete` | `command, response, sshObj, details` | A command returns to the prompt. Use it to inspect the response, queue follow-up commands, or stop the current host. | -| `onCommandTimeout` | `command, response, stream, connection, details` | No data arrives for `idleTimeOut` milliseconds. | +| `onCommandComplete` | `command, response, sshObj, details` | When the prompt is detected after a command is run. | +| `onCommandTimeout` | `command, response, stream, connection, details` | Catches when a command hangs or is waiting for input. | | `onEnd` | `sessionText, sshObj` | The host session finishes. | | `onError` | `err, type, close, callback` | An error is raised. | | `onKeyboardInteractive` | `name, instructions, instructionsLang, prompts, finish` | Keyboard-interactive authentication is requested. | @@ -353,11 +354,11 @@ progress. can answer a prompt with `stream.write('y\n')`. See [Respond to a prompt mid-command](#respond-to-a-prompt-mid-command). -`onCommandTimeout` receives `details` as -`{ attempt, maxRetries, final, noOutput }`. With `commandTimeoutRetries` set, the -library re-arms the timer for non-final attempts; the handler does not need to -count. Set `this.sshObj.retryCommandTimeout = false` to stop retrying for the -current command. +`onCommandTimeout` receives `details` as `{ attempt, maxRetries, final }`. With +`commandTimeoutRetries` set, the library re-arms the timer for non-final +attempts; the handler does not need to count. Set +`this.sshObj.retryCommandTimeout = false` to stop retrying for the current +command. `onCommandComplete` receives `details.rawResponse` and, when `captureStderr` is enabled, `details.stderr` with the captured stderr text. @@ -684,7 +685,7 @@ SSH.on('commandProcessing', function (command, response, sshObj, stream) { Do not define the same handler in both places. It will run twice. If no prompt is detected and no answer is sent, `commandTimeout` fires after -`idleTimeOut` milliseconds with no data. +`idleTimeOut` milliseconds without a prompt. See [`test/live/prompt_response.js`](./test/live/prompt_response.js) for a runnable example. @@ -937,7 +938,7 @@ SSH.on('keyboard-interactive', (name, instructions, instructionsLang, prompts, f | `stderrData` | `data` | Data from stderr. Defaults to `console.error`. | | `commandProcessing` | `command, response, sshObj, stream` | Output received before the prompt is detected. | | `commandComplete` | `command, response, sshObj, details` | A command returned to the prompt. `response` is raw by default; `commandResponse: 'handled'` removes the echoed command and trailing prompt. `details.rawResponse` is always the raw buffer; `details.stderr` carries captured stderr when `captureStderr` is enabled. The handler can modify `sshObj.commands` to queue follow-up work. | -| `commandTimeout` | `command, response, stream, connection, details` | No data arrived for `idleTimeOut` milliseconds, or `commandStartTimeout` armed the timer at command start. `details` is `{ attempt, maxRetries, final, noOutput }`. | +| `commandTimeout` | `command, response, stream, connection, details` | No prompt was detected for `idleTimeOut` milliseconds after the command was written or the last data event. `details` is `{ attempt, maxRetries, final }`. | | `end` | `sessionText, sshObj` | A host session finished. On the final host, `sessionText` is the combined text. | | `error` | `err, type, close, callback` | An error occurred. A dropped transport uses type `Connection close` and passes an `Error` with `level = 'Connection close'` and `hadError`. `close` requests a connection close; `callback(err, type)` runs before closing. | | `keyboard-interactive` | `name, instructions, instructionsLang, prompts, finish` | The server requested keyboard-interactive authentication. | @@ -961,11 +962,11 @@ part of the public API. | Member | Description | | --- | --- | | `connect(callback)` | Start the session. `callback(sessionText)` is optional and receives the combined text when all hosts finish. | -| `stop(reason)` | Abort the whole run. Clears every command and host queue, sends Ctrl-C if a command is in flight, runs the library's queued `exitCommands` (bounded by `idleTimeOut`), closes once, and calls the callback once. A no-op before `connect()` or after the run finishes. | +| `stop(reason)` | Abort the whole run. Clears every command and host queue, sends Ctrl-C if a command is in flight, closes the active connection and its ancestors, and calls the callback once. A no-op before `connect()` or after the run finishes. | | `close()` | Close the current shell stream. A no-op if the shell has not opened yet. Remaining primary hosts still run; use `stop()` to abandon them. | -| `close({ graceful: true })` | Run queued exit commands and back out of nested shells before closing. Remaining primary hosts still run. | +| `close({ graceful: true })` | Back out of nested shells before closing. Remaining primary hosts still run. | | `emit(name, ...args)` | Raise an event. Inherited from `EventEmitter`. | -| `sshObj` | The current host object, including runtime state such as `sessionText`, `commands`, `hosts`, `exitCommands`, `pwSent`, `sudoFailed`, `stopReason`, and the `skipCommands` / `skipHosts` / `skipPrimaryHosts` / `abort` flags. | +| `sshObj` | The current host object, including runtime state such as `sessionText`, `commands`, `hosts`, `pwSent`, `sudoFailed`, `stopReason`, and the `skipCommands` / `skipHosts` / `skipPrimaryHosts` / `abort` flags. | | `command` | The command currently being processed. | | `idleTime` | The active command timeout in milliseconds. | | `dataIdleTime` | The active response-settling delay in milliseconds. | @@ -1058,13 +1059,12 @@ onCommandProcessing(command, response, sshObj, stream) { `skipCommands` if the current host should stop now; otherwise its remaining commands still run. - `stop(reason)` clears every queue. If a command is still running it sends - Ctrl-C first, then runs the library's queued `exitCommands` (bounded by - `idleTimeOut`), closes once, and calls the callback once. The reason appears - as `Stop requested: ` and in `sshObj.stopReason`. + Ctrl-C first, then closes the active connection and its ancestors, and calls + the callback once. The reason appears as `Stop requested: ` and in + `sshObj.stopReason`. - `close()` closes the current connection but still runs the remaining primary hosts, matching earlier releases. Use `stop()` to abandon them. -- `close({ graceful: true })` runs the queued exit commands and backs out of - nested shells before closing. +- `close({ graceful: true })` backs out of nested shells before closing. **Notes** @@ -1213,24 +1213,25 @@ silent commands; it produces nothing when stderr is redirected to a file. ### Silent commands -A command that never writes anything does not arm the data-driven idle timer. -Opt in with `commandStartTimeout: true` to arm it when the command is written: +The idle timer starts when a command is written, so a command that writes +nothing still times out if it never returns to the prompt. A silent command that +does return to the prompt completes normally. + +Give a legitimately long silent command a larger `idleTimeOut`: ```javascript const host = { // ... - commandStartTimeout: true, idleTimeOut: 30000, onCommandTimeout(command, response, stream, connection, details) { - if (details.noOutput) { - this.emit('msg', `${command} produced no output`); - } + this.emit('msg', `${command} did not return to a prompt`); }, }; ``` -The timeout details still report `{ attempt, maxRetries, final, noOutput }`, so -the same handler works with `commandTimeoutRetries`. +The timeout details report `{ attempt, maxRetries, final }`, so the same handler +works with `commandTimeoutRetries`. To distinguish a silent command from one that +wrote output but missed the prompt, inspect `response`. ### Capturing stderr diff --git a/REFACTORING.md b/REFACTORING.md index 34ce668..2bdd116 100644 --- a/REFACTORING.md +++ b/REFACTORING.md @@ -1017,6 +1017,12 @@ Signed-off-by: user request for the silent-command and "no output yet" distincti Released in `v3.3.0`. +> **Superseded in the next major.** The idle timer is now always armed when a +> command is written, so a silent command times out without an opt-in. The +> `commandStartTimeout` option and `details.noOutput` were removed. A detected +> prompt cancels the timer, so a silent command that returns to the prompt still +> completes normally. See `test/unit/command-start-timeout.test.js`. + - `src/ssh2shell.js` — `_runCommand` arms the idle timer when `commandStartTimeout` is `true` and resets `_commandSawData` for the new command. `_onData` marks data as seen once a command is in flight. @@ -1240,7 +1246,9 @@ behavior. - **Implemented:** handle silent long-running commands. `commandStartTimeout` arms the idle timer when the command is written, and `details.noOutput` distinguishes "no output yet" from "prompt missed". See - [L7.22 deliverables](#l722-deliverables-silent-command-timeout). + [L7.22 deliverables](#l722-deliverables-silent-command-timeout). This was + superseded in the next major: the timer is always armed at command start and + both `commandStartTimeout` and `details.noOutput` are removed. - **Implemented:** opt-in stderr capture in the command response with `captureStderr` and `details.stderr`; `onStderrData` remains the always-on event. See [L7.23 deliverables](#l723-deliverables-stderr-capture). diff --git a/docs/API-BASELINE.md b/docs/API-BASELINE.md index 09b18e0..73d1f62 100644 --- a/docs/API-BASELINE.md +++ b/docs/API-BASELINE.md @@ -86,7 +86,6 @@ until `_connections` is empty and `close()` runs. | `_connections` | Stack of previous hosts used to back out through secondary/nested connections. | | `_stream` | Current shell stream. | | `_buffer` | Raw response buffer for the current command. | -| `_commandSawData` | Internal: whether the current command has produced data (drives `details.noOutput`). | | `_stderrBuffer` | Internal: captured stderr for the current command when `captureStderr` is enabled. | | `idleTime` | Command timeout in ms (`idleTimeOut`, default 5000). | | `dataIdleTime` | Internal data-settle timer in ms; intended public key is `dataIdleTimeOut`, default 500. | @@ -104,7 +103,7 @@ until `_connections` is empty and `close()` runs. | `end` | `(sessionText, sshObj)` | Stream `finish`, `_previousHost`, `_nextPrimaryHost`. | | `commandProcessing` | `(command, response, sshObj, stream)` | `_onData` while a command is still producing output. | | `commandComplete` | `(command, response, sshObj, details)` | `_commandComplete` after a prompt is detected. `response` is the raw buffer by default; `commandResponse: 'handled'` removes the echoed command and trailing prompt. `details.rawResponse` is always the raw buffer; `details.stderr` carries captured stderr when `captureStderr` is enabled. | -| `commandTimeout` | `(command, response, stream, connection, details)` | `_scheduleIdleTimeout`, armed by `_onData` or by `_runCommand` when `commandStartTimeout` is set. `details` is `{ attempt, maxRetries, final, noOutput }`. | +| `commandTimeout` | `(command, response, stream, connection, details)` | `_scheduleIdleTimeout`, armed when `_runCommand` writes a command and reset by `_onData`. A detected prompt cancels the timer. `details` is `{ attempt, maxRetries, final }`. | | `keyboard-interactive` | `(name, instructions, lang, prompts, finish)` | Re-emitted from the `ssh2.Client`. | | `newPrimaryHost` | value returned by `_nextPrimaryHost`, which is `_initiate`'s return value: at `connect()` time this is `_stream` (the prototype placeholder `{}` until the shell opens) | `connect` and connection `close`. | | `pipe` / `Unpipe` | — | Not emitted by the class. These are stream-level concepts; the README no longer lists them. | @@ -115,7 +114,7 @@ until `_connections` is empty and `close()` runs. `connectedMessage`, `readyMessage`, `closedMessage`, `showBanner`, `verbose`, `debug`, `progress`, `exposeCredentials`, `enter`, `streamEncoding`, `window`, `pty`, `idleTimeOut`, `dataIdleTimeOut` (public timer key; falls back to the -undocumented `dataIdleTime`), `commandResponse`, `commandStartTimeout`, +undocumented `dataIdleTime`), `commandResponse`, `captureStderr`, `commandTimeoutRetries`, `sessionText`, `exitCommands`. **Prompts and filters:** `standardPrompt`, `standardPromptRegex`, @@ -286,21 +285,19 @@ run against both the current build and the frozen baseline, guarded by `test/unit/command-response.test.js`. - **`commandTimeoutRetries`.** A non-negative integer, default `0`. The library owns the attempt count and re-arms the idle timer for each non-final attempt; - the handler only reacts to - `details = { attempt, maxRetries, final, noOutput }`. The default handler - closes only on the final attempt, so `0` preserves the single-timeout - behavior. A handler can set `this.sshObj.retryCommandTimeout = false` to stop - retrying for the current command. The attempt count resets when the same - command is written and when a command completes, not for internal - password/exit writes. Test: `test/unit/timeout-retries.test.js`; live checks: - `test/live/timeout.js` (handler-managed) and `test/live/timeout_retries.js` - (opt-in retries). -- **`commandStartTimeout`.** A boolean, default `false`. When `true`, the idle - timer is armed as soon as the command is written, so a command that never - produces output still reaches `commandTimeout`. The library tracks - `_commandSawData` per command and reports `details.noOutput`: `true` means no - data has arrived for the command, `false` means output arrived but no prompt - was detected. Incoming data still clears and re-arms the timer normally. Test: + the handler only reacts to `details = { attempt, maxRetries, final }`. The + default handler closes only on the final attempt, so `0` preserves the + single-timeout behavior. A handler can set + `this.sshObj.retryCommandTimeout = false` to stop retrying for the current + command. The attempt count resets when the same command is written and when a + command completes, not for internal password/exit writes. Test: + `test/unit/timeout-retries.test.js`; live checks: `test/live/timeout.js` + (handler-managed) and `test/live/timeout_retries.js` (opt-in retries). +- **Command idle timeout.** The idle timer is armed when a command is written, so + a command that never produces output still reaches `commandTimeout`. Incoming + data resets the timer, and a detected prompt cancels it. A silent command that + returns to the prompt completes normally. The literal `exit` command and + internal password writes do not arm the timer. Test: `test/unit/command-start-timeout.test.js`. - **`captureStderr`.** A boolean, default `false`. When `true`, stderr chunks are filtered with the same colour and ASCII filters as stdout, buffered in diff --git a/docs/ERROR-HANDLING.md b/docs/ERROR-HANDLING.md index 8cbc03a..05d448a 100644 --- a/docs/ERROR-HANDLING.md +++ b/docs/ERROR-HANDLING.md @@ -55,7 +55,7 @@ call to `close()`. | 1 | `_processSudoPrompt` | Sudo password rejected (`pwSent` true) or no password configured | **No `error` event** (current). Baseline emitted `(": Sudo password was incorrect...", "Sudo authentication")` when `debug` was on. | n/a | Set `sshObj.sudoFailed = true`, emit a normal `msg`, then `_resetFromSudoError()`: append buffer to `sessionText`, clear buffer/command, write `Ctrl-C`. With `abortOnSudoFailure: true`, `stop('sudo-failed')`. | Notification only by default. Connection stays open; the sudo command is cancelled and the session continues. | | 2 | `_sshConnect` | `buildSshCommand` returns an error (security alert) | `(result.error, "Security Alert", true)` | `true` | `return` | Closes the current shell stream, which ends the connection. Remaining secondary hosts are not resumed. | | 3 | `_processSSHPrompt` | Nested SSH authentication fails after the password/passphrase was sent | `(": SSH authentication failed for @", "SSH multi host authentication failure")` | `false` | `_previousHost()` if `_connections` is non-empty, otherwise `_runExit()` | No direct close. The back-out/exit path eventually closes or resumes the previous host. | -| 4 | `_loadDefaults` default `onCommandTimeout` | Command idle timer fires on the final attempt | `(": Command timed out after seconds", "Command Timeout", true, callback)` | `true` | None | With `commandTimeoutRetries` set, non-final attempts return without closing and the library re-arms; only the final attempt closes. The default listener now runs the callback (saving `_buffer` to `sessionText` and clearing it) before closing the stream. With `commandStartTimeout: true`, the timer is armed when the command is written, so a silent command also reaches this path; `details.noOutput` is `true` when no data arrived for the command. | +| 4 | `_loadDefaults` default `onCommandTimeout` | Command idle timer fires on the final attempt | `(": Command timed out after seconds", "Command Timeout", true, callback)` | `true` | None | With `commandTimeoutRetries` set, non-final attempts return without closing and the library re-arms; only the final attempt closes. The default listener now runs the callback (saving `_buffer` to `sessionText` and clearing it) before closing the stream. The timer is armed when the command is written, so a silent command also reaches this path; a prompt cancels the timer before it fires. | | 5 | `_connect` shell callback | `connection.shell` returns an `Error` | `(err, "Shell", )` | `true` only when a stream was supplied | `return` | Closes the supplied stream. With no stream the error is reported without a close, and the guarded default listener cannot throw. | | 6 | `_connect` stream `error` | The shell stream emits `error` | `(err, "Stream", true)` | `true` (baseline: no close) | None | Current: closes the stream, ends the connection. Baseline: leaves the stream/connection open. | | 7 | `_connect` stream `data` handler | A `data` listener throws | `(err, "Stream.read error", true)` with `err.level = "Data handling"` | `true` | None | Closes the stream, ends the connection. | @@ -197,11 +197,11 @@ ssh._loadDefaults(); // baseline: 1; fixed current: 1 (no duplicate) `error`. The first timeout is still final when the option is `0`, so the default behavior is unchanged. Test: `test/unit/timeout-retries.test.js`. -13. **Silent commands can time out on opt-in.** `commandStartTimeout: true` - arms the idle timer when a command is written, instead of waiting for the - first data event. `details.noOutput` distinguishes a command with no output - from one whose prompt was missed. The default is `false`, so existing - sessions keep the data-driven timer. Test: +13. **Silent commands time out by default.** The idle timer is armed when a + command is written instead of waiting for the first data event. A command + that never returns to a prompt reaches `commandTimeout`, whether or not it + wrote output. A detected prompt cancels the timer, so a silent command that + returns to the prompt completes normally. Test: `test/unit/command-start-timeout.test.js`. 14. **Stderr can be captured on opt-in.** `captureStderr: true` filters stderr with the response filters, merges it into `commandComplete` and diff --git a/docs/NEXT-HOST-CONNECTION.md b/docs/NEXT-HOST-CONNECTION.md new file mode 100644 index 0000000..6d3f36b --- /dev/null +++ b/docs/NEXT-HOST-CONNECTION.md @@ -0,0 +1,1761 @@ +# Host-to-host connections: ssh2 hop design + +- **Status:** implemented on this branch. The record stack, `forwardOut` hop + transport, failure containment, and the `_sanitizeResponse` long-command fix + are in `src/ssh2shell.js`; the nested `ssh` command path is removed. Both live + acceptance tests (`test/live/host_traversal.js` and + `test/live/host_faults.js`) pass against `src`, including on a freshly + provisioned VM. +- **Branch:** `next-host-connection`. +- **Release:** next major. The `server.ssh` removal and the jump-host + credential change are breaking, so this does not ship as a 3.x minor. +- **Target:** replace the nested `ssh` command with a real `ssh2` connection + hop, then remove the command-based path. +- **Source of truth:** `src/ssh2shell.js` (current build). `lib/ssh2shell.js` is + its published copy. +- **Related docs:** [CLOSE-SEMANTICS.md](CLOSE-SEMANTICS.md), + [API-BASELINE.md](API-BASELINE.md), [ERROR-HANDLING.md](ERROR-HANDLING.md). + +The primary connection is already a clear state engine: `_connect` opens an +`ssh2.Client`, `ready` opens a shell, the stream feeds `_onData`, and +`_commandComplete` / `_nextCommand` / `_runExit` drive the command loop. This +design reuses that engine for host-to-host hops. The old nested `ssh` command +path is not a comparison baseline; it is removed. + +## Decision + +Nested hosts keep the same public host objects, `hosts` arrays, command queues, +handlers, `sessionText`, and traversal order. The transport changes: + +| | Current | New | +| --- | --- | --- | +| Nested transport | `ssh ...` written to the parent shell | `ssh2.Client` connected through the parent connection | +| Authentication | Parsed password/passphrase prompts | `ssh2` authentication on the new client | +| Host key | `StrictHostKeyChecking=no` in the command | `ssh2` `hostHash` / `hostVerifier` | +| Exit | Queued `exit` command | Child connection is closed | +| Security hardening | `Security Alert` on shell metacharacters; `shellQuote` | Removed; values go to `ssh2` as data | +| `server.ssh` options | Mapped to `ssh` command-line flags | Removed; use `ssh2` connection options | + +This is a breaking change. It removes `server.ssh`, the nested `ssh` command, +the jump-host credential model, the queued `exit` command, and the +shell-metacharacter hardening layer. Plan it for a major release, not a 3.x +minor. + +### Decisions locked from design review + +| Topic | Decision | +| --- | --- | +| Nested host reuse | `_pushContext()` copies `host.hosts` into `context.pendingHosts`; `_nextHost()` shifts that copy. The caller's nested arrays are never consumed. | +| Active aliases during a hop | `_pushContext()` sets `this.connection = null` and `this._stream = {}` for the child. `_openClient()` / `_openShell()` fill them. `_hasLiveStream()` is false while `forwardOut` is pending. | +| Primary close reporting | The primary `connection.on('close')` handler emits the `Connection close` error or `closedMessage`; `_endPrimary()` only finalizes and advances. The synchronous-throw path reports before calling `_failContext()`. | +| `_removeListeners(context)` | Pure listener/timer cleanup. It does not call `_progressEnd()` and does not reset instance `idleTime` / `dataIdleTime`. Progress ends on the active-record switch. | +| Record timers | `idleTime` and `dataIdleTime` are stored on the record by `_loadDefaults(context)` and reapplied by `_restoreContext()`. | +| Close-event guards | Handlers return when `context.closed` or `context.failing` is set. The hop close handler also returns when `_closing`, `_stopping`, or `_runComplete` is set, so a plain `close()` does not navigate back to the parent. | +| Missing hop parent | `_connectHop()` without a parent routes to `_failContext()` (or `_callFinalCallback()`), so the run terminates. | +| Pending `forwardOut` | A stop/close during `forwardOut` closes the channel and the pending child record, then restores the parent. | +| Expected-drop reconnect | Out of scope. This change adds `_appendPartial()` for unexpected drops only. `breaksConnection`, `expectedClose`, the partial `commandComplete`, and the retry loop stay in the follow-up. | +| Keyboard-interactive | The fallback responder is bound into `context.listeners` when the host sets `tryKeyboard`; instance re-emits are guarded by `context === _activeContext()`. | +| Hop host keys | Same as the primary: `ssh2` accepts unless `hostHash` / `hostVerifier` is set. Documented, no warning. | +| Compatibility switch | Rejected. The nested `ssh` path is removed; this is a major release. | +| `newPrimaryHost` | Emitted only when a primary actually starts, with that host config. | +| Failed host `end` | The failed record is finalized and emits `end`; unstarted descendants do not. | + + +## Why replace the command path + +- **No shell prompt parsing for authentication.** `_processSSHPrompt` and the + `sshAuth` / `sshToNextHost` flags exist only because `ssh` asks for + credentials in the parent shell. `ssh2` reports authentication directly. +- **No command building or shell hardening.** `buildSshCommand`, + `shellQuote`, `shellControlChars`, and the `Security Alert` path exist to make + a command string safe. The hop passes values to `ssh2` as data. +- **No command injection surface.** Nothing is interpolated into a remote shell. +- **No dependency on the remote `ssh` binary or its configuration.** The hop + works when the jump host has no `ssh` client, a restricted shell, or a + `~/.ssh/config` that changes behaviour. +- **Real host-key verification.** The command path injects + `StrictHostKeyChecking=no`. The hop can use the same `hostHash` / + `hostVerifier` contract as the primary connection. +- **One connection lifecycle.** Connection, shell, data, timeout, error, and + close handling become the same code for primary and nested hosts. +- **Per-hop failure isolation.** A dropped target connection is a distinct event + from a dropped jump host. The connection model can report which hop failed and + leave the parent shell intact; this is also the foundation for a future + reconnect/retry policy. +- **Less state to keep consistent.** No `exitCommands` queue, no + `sshToNextHost` guard in `_commandComplete`, no SSH case in `_onData`, and no + exit-command branch in `_runExit`. + +The cost is a state change: the library must hold more than one live +connection. The rest of this document maps that change. + +## New method + +### One `_connect`, two transports + +`_connect()` is the right place for both connection kinds. Once a transport +exists, primary and hop connections are identical: create an `ssh2.Client`, bind +the connection handlers, wait for `ready`, open a shell, and feed the same data +engine. The only difference is where the socket comes from. + +- **Primary:** `client.connect(server)` opens a TCP socket. +- **Hop:** `parent.connection.forwardOut(...)` opens a direct-tcpip channel, then + `client.connect({ ...server, sock: channel })` uses that channel as its + transport. + +`this.connection` is an `ssh2.Client` in both cases. A hop does **not** use a +different connection type; `sock` is an `ssh2` channel, not a client. That is why +one method can own both paths without branching in the command engine, the +handlers, or the close code. + +`_connect(parent = null)` takes the parent context. `null` means a primary host; +a context means a hop. + +```js +_connect(parent = null) { + if (this._stopping || this._runComplete) { + return; + } + + const context = this._pushContext(this.sshObj, parent); + const server = this._normalizeServer(this.sshObj.server); + // Defaults now belong to the record, so they are loaded after the record + // exists and before the client is opened. + this._loadDefaults(context); + + if (context.isPrimary) { + return this._openClient(context, server); + } + + parent.connection.forwardOut( + '127.0.0.1', + 0, + server.host, + Number(server.port) || 22, + (err, channel) => { + if (err) { + return this._hopFailed(context, err); + } + if (this._stopping || this._runComplete || this._closing) { + channel.close(); + // The child record is already active. Close it and restore the parent + // so a stop/close during forwardOut does not leave a half-open stack. + return this._failContext(context, new Error('Connection cancelled'), 'cancelled'); + } + return this._openClient( + context, + Object.assign({}, server, { sock: channel }) + ); + } + ); +} + +// Readability alias used by _nextHost(). The transport branch is in _connect(). +_connectHop() { + const parent = this._activeContext(); + if (!parent || !parent.connection) { + this.emit('error', 'No parent connection for host hop', 'Hop', false); + return; + } + return this._connect(parent); +} +``` + +`_openClient()` is the shared tail for both paths: + +```js +_openClient(context, options) { + context.connection = new this.ssh2Client(); + this._bindConnection(context); + try { + context.connection.connect(options); + } catch (err) { + if (context.isPrimary) { + this.emit( + 'error', + `${err} ${err.stack}`, + 'Connection.connect', + this._hasLiveStream() + ); + return this._failContext(context, err, 'connect-throw'); + } + return this._hopFailed(context, err); + } +} +``` + +`_nextHost()` only changes the method it initiates: + +```js +_nextHost() { + if (this._stopping || this._runComplete) { + return; + } + + // The outgoing record is still active; remove its handlers before the child + // config replaces the aliases. `pendingHosts` is the record's copy, so the + // caller's nested array is never consumed. + const parent = this._activeContext(); + this._removeListeners(parent); + const nextHost = parent.pendingHosts.shift(); + this._systemMsg('debug', `nextHost: hop to ${nextHost.server.host}`); + + this.sshObj = nextHost; + this.host = nextHost.server.host; + + return this._initiate(this._connectHop); +} +``` + +`_connectHop()` has no logic of its own; it exists so `_nextHost()` reads as a +host switch. If preferred, `_nextHost()` can call +`_initiate(() => this._connect(parent))` and the alias can be deleted. + +Because `_loadDefaults` is now record-scoped, it moves out of `_initiate()` and +into `_connect()` after `_pushContext()`. `_initiate(action)` keeps only its stop +guard and the `action()` call: + +```js +_initiate(action) { + if (this._stopping || this._runComplete) { + return; + } + return action(); +} +``` + +That keeps one ordering rule: a record exists before its defaults are loaded, and +the client is opened after both. `_loadDefaults(context)` reads `context.host` +instead of `this.sshObj` and stores its timers on the record. + +### Shared helpers extracted from `_connect` + +`_connect` keeps its shape but delegates event wiring and shell setup to +context-aware helpers. Each handler closes over `context`, not `this.sshObj`, so +a late event from a parent connection cannot act on the active child. + +| Helper | Responsibility | +| --- | --- | +| `_normalizeServer(server)` | Copy the server object, apply `username` / `hostHash` / `passphrase` aliases, strip `ssh`, and leave the host object untouched. | +| `_pushContext(host, parent)` | When `parent` is set, push that parent record onto `_connections`; then create `{ host, parent, connection: null, stream: null, isPrimary: parent === null, closed: false, failing: false, listeners: {}, idleTimer: null, dataReceivedTimer: null, expectedClose: false, idleTime, dataIdleTime, pendingHosts }`, make it `_active`, set `this.sshObj` / `this.host` / `this.connection = null` / `this._stream = {}`, and return it. A primary starts with `_connections = []`. | +| `_activeContext()` | Return `this._active`, or `null`. | +| `_bindConnection(context)` | Attach `keyboard-interactive`, `connect`, `ready`, `error`, and `close` handlers. Each handler closes over `context`. | +| `_openShell(context)` | Call `context.connection.shell(...)`, set the encoding, and attach `data`, `stderr`, `error`, `finish`, and `close` handlers that ignore events when the context is no longer active. | +| `_openClient(context, options)` | Create the client, bind the handlers, and connect. A synchronous `connect()` throw is routed to `_failContext`. | +| `_restoreContext(context)` | Set `this.connection` / `this._stream` / `this.sshObj` / `this.host` back to a context after a child closes, and reapply the context's `idleTime` / `dataIdleTime` values. | +| `_popContext()` | Pop the top ancestor from `_connections`, make it active, restore the aliases, and reapply its timer values. Used by `_previousHost()`. | +| `_popTo(context)` | Drop `context` and every record above it from `_connections` until `context.parent` is on top, then pop it to make the parent active. Used by `_failContext()`. | +| `_descendantsOf(context)` | Return the active record plus every record deeper than `context` (`_connections.slice(indexOf(context) + 1)` reversed), deepest-first, excluding `context`. Used for teardown. | +| `_closeContext(context, reason)` | The only record teardown point: remove `context.listeners`, close the stream and connection, and finalize the host. Idempotent through `context.closed`. | +| `_closeAllContexts(reason)` | Close the active record and every ancestor, deepest-first, through `_closeContext()`. Used by `_nextPrimaryHost()`, `close()`, and `stop()`. | +| `_failContext(context, err, reason)` | The only record failure entry point: tear down descendants, close the record, then `_endPrimary` for a primary or `_popTo()` + `_runExit()` for a hop. | +| `_endPrimary(reason)` | Exactly-once primary advance: finalize the run, then start the next primary or call the callback. Used by `connection.on('close')`, the synchronous connect throw, and `_failContext`. | +| `_hopFailed(context, err)` | Emit the record's `error`, then delegate to `_failContext(context, err, 'hop-failed')`. | +| `_removeListeners(context)` | Remove only the handlers in `context.listeners` and clear that record's timers; never read `this.sshObj` or the instance `_boundListeners` cache. Pure cleanup: no `_progressEnd()`, no instance timer reset. | +| `_loadDefaults(context)` | Bind host handlers into `context.listeners` and apply record-scoped timers. Instance defaults stay on the instance. | + +The primary path through `_connect()` is then just: + +```js +const context = this._pushContext(this.sshObj, null); +this._loadDefaults(context); +return this._openClient(context, this._normalizeServer(this.sshObj.server)); +``` + +The hop path adds one asynchronous transport step before the same +`_openClient()`. There is no second connection implementation to keep in sync. + +### Where connection objects live + +**Decision: one regressive stack. `_connections` holds the ancestors of the +active host; the active host is a separate record.** + +```js +// Active host: hostaaa +this._active = { + host: hostaaa, parent: hostaa, connection: aaaaClient, + stream: aaaaStream, isPrimary: false, closed: false, + listeners: {}, idleTimer: null, dataReceivedTimer: null, expectedClose: false, +}; +this._connections = [ + { host: host1, parent: null, connection: host1Client, stream: host1Stream, isPrimary: true, closed: false, listeners: {}, idleTimer: null, dataReceivedTimer: null, expectedClose: false }, + { host: hosta, parent: host1, connection: hostaClient, stream: hostaStream, isPrimary: false, closed: false, listeners: {}, idleTimer: null, dataReceivedTimer: null, expectedClose: false }, + { host: hostaa, parent: hosta, connection: hostaaClient, stream: hostaaStream, isPrimary: false, closed: false, listeners: {}, idleTimer: null, dataReceivedTimer: null, expectedClose: false }, +]; +``` + +Every record has the same shape. `_pushContext()` creates all fields, including +`listeners`, the two record-scoped timers, `expectedClose`, and the `failing` +re-entry guard used by `_failContext()`. It also stores `idleTime`, +`dataIdleTime`, and `pendingHosts` (a copy of `host.hosts`) on the record so a +parent can be restored without reading the active aliases and so a host's +nested array is never consumed. + +This answers "should connection objects be added to the connections with the +configs?" **Yes, but as a record around the config, not as properties on the +config.** + +The stack is a single regressive path, not a tree. `_connections` holds only the +hosts above the active one; the active host is not in the array. Forward paths +wait in `host.hosts`. A host with several nested hosts runs them one at a time: +push the active record, make child A active, finish A (pop), make the parent +active, push it again for child B, and so on. When the primary finishes, +`_nextPrimaryHost()` closes and resets the stack, then the next primary becomes +active with `_connections = []` and its own `hosts` are traversed the same way. + +- `_connections[0]` is the primary record while a hop is active. At a primary, + `_connections` is empty. +- `_active` is the active record; `this.connection`, `this._stream`, `this.sshObj`, + and `this.host` are aliases for it. +- `parent` points at the record that supplied the `forwardOut` channel, so a + three-hop chain closes and restores in order. +- `closed` makes teardown idempotent when the normal exit path and a connection + event race. + +#### Why not attach `connection` / `stream` to the host config + +The host object is user configuration, not lifecycle state. Attaching live +handles to it would: + +- put sockets and channels into the `verbose` config dump and the credential + redaction walk; +- make a host object single-use, so the same config could not appear in + `_hosts` or be reused across runs; +- leak connection state into `_loadDefaults`, which mutates the host config; +- change the documented host shape for no user benefit. + +#### Why not a separate parallel stack + +A second array (`_contexts`) would have to stay in lockstep with `_connections` +at every push, pop, close, and finalize point. One array of records removes that +class of bug and answers the close question directly: to close a hop, close the +record you already have. + +#### Why not bind `sshObj` to the connection + +The reverse binding — `connection.sshObj = host`, or making the connection the +context — is tempting because a connection event handler could recover the host +without a closure. It is not the right owner: + +- **The connection is ephemeral; the host is not.** A reconnect replaces the + client. `expectedClose`, the retry count, and the timer belong to the host + context and must survive the swap. If the connection owns them, reconnect has + to rebuild the context and transfer the state. +- **The host exists before the connection.** `_nextHost()` sets `this.sshObj` + and `_connect()` runs `_loadDefaults(context)` before `_openClient()` creates + the client. There is a real window where the host has no connection to bind to. +- **`ssh2.Client` is not ours.** Adding `sshObj`, `stream`, `parent`, and + `closed` to a third-party object couples us to its extensibility and leaks + library state through the documented `this.connection`. +- **Teardown is array-shaped.** `stop()`, `close()`, and `_finalizeRun()` walk + records deepest-first. A linked list via `connection.parent` needs a second + child link or an array anyway. +- **The stream is separate from the client.** `ready` creates the stream after + the connection, so the context has to hold both. The connection cannot be the + single container without more mutation. + +If a back-reference is useful for handlers or debugging, make it +non-authoritative: + +```js +context.connection.context = context; // or a WeakMap +``` + +The stack stays the source of truth; the connection just points back at its +record. Event handlers already close over `context` in `_bindConnection()` and +`_openShell()`, so this is a convenience, not a dependency. + +#### How `_connect` interacts with the stack + +| Step | Stack effect | +| --- | --- | +| `connect()` -> `_connect(null)` | Create the primary as the active record. `_connections` stays `[]`. | +| `_nextHost()` -> `_connectHop()` -> `_connect(parent)` | `parent = _activeContext()`. Push the parent record onto `_connections`, then make the child active. | +| `forwardOut` | Reads `parent.connection`; no stack change. | +| `_openClient(child)` | Fills `child.connection`; `_openShell` fills `child.stream`. | +| Commands | Active aliases point at the child record. | +| `_runExit()` -> `_previousHost()` | Close the active child, pop its parent, make the parent active again. | +| Next sibling or `close()` | Uses the restored parent record; a sibling pushes it again. | +| `_nextPrimaryHost()` | Close the active record and every ancestor, reset `_connections` to `[]`, then `_connect(null)` makes the next primary active. | + +#### Checks that keep their meaning + +Because the active host is outside `_connections`, `_connections.length > 0` +still means "we are inside a nested host". The checks do not flip; only the +record shape changes from a host config to `record.host`: + +| Location | Current check | New check | +| --- | --- | --- | +| `_processNotifications()` | `_connections.length > 0` prefixes the host on session notes | Unchanged | +| `_runExit()` | `_connections.length > 0` means "return to the previous host" | Unchanged | +| `_finalizeHost()` | primary when `_connections.length === 0` or `host === _connections[0]` | `host === _connections[0].host`, with the empty-stack fallback kept | +| `_mergeNestedText()` | root is `_connections[0]` | parent is the record below the host, or the last ancestor | +| `_finalizeRun()` | current host plus `_connections` in reverse | active host plus `_connections` records in reverse | +| `stop()` / `_prepareGracefulClose()` | `clearQueues(host)` over `_connections` | `clearQueues(record.host)` for the active record and each ancestor | +| `_nextPrimaryHost()` | `_connections = []` | close the active record and every ancestor, then reset | +| `_nextHost()` | `_connections.push(this.sshObj)` | `_connect` pushes the parent record before the child becomes active | + +## Primary connection vs host hop + +| Concern | Primary (`_connect(null)`) | Hop (`_connect(parent)`) | Shared | +| --- | --- | --- | --- | +| Entry point | `connect()` -> `_nextPrimaryHost(this._connect)` | `_runExit()` -> `_nextHost()` -> `_connectHop()` -> `_connect(parent)` | `_initiate` loads defaults and binds host handlers. | +| Stack | Creates the active record; `_connections` is `[]` | Pushes the parent record onto `_connections`, then makes the child active | One record shape for both. | +| Client | `new ssh2.Client()` | `new ssh2.Client()` | Same client type. | +| Transport | `client.connect(server)` | `parent.connection.forwardOut(...)` then `client.connect({ ...server, sock: channel })` | `_normalizeServer` and `_openClient`. | +| Credentials | Local process: `password`, `privateKey`, `passPhrase`, `agent` | Local process, same fields | Same `ssh2` authentication. | +| Host key | `hostHash` / `hostVerifier` on `server` | Same fields passed to the child client | `_normalizeServer` applies `hostHash`/`hashMethod`. | +| Auth prompts | `ssh2` handles them; `keyboard-interactive` is re-emitted | Same | `_bindConnection` installs the same handler. | +| Shell | `context.connection.shell(window, { pty })` | Same | `_openShell`. | +| Stream encoding | `streamEncoding`, default `utf8` | Same | `_openShell`. | +| Data routing | Active stream only | Active stream only; inactive parent streams are ignored | Stream handler compares `context` with `_activeContext()`. | +| Host defaults | `_loadDefaults` | `_loadDefaults` | Same host object contract. | +| Command loop | `_nextCommand` / `_checkCommand` / `_runCommand` | Same | No change. | +| Timeout | `_scheduleIdleTimeout` | Same | The idle timer is armed per command and retries work per command. | +| Session text | `_finalizeHost` / `_finalizeRun` | Same, with the record stack | `_mergeNestedText` merges one level at a time into the immediate parent, so the primary still receives the whole subtree. | +| Close | Active primary close ends the primary | Active child close returns to the parent record | `_closeContext` and `_finalizeRun`. | +| Next step | Next primary host, or final callback | Parent `_runExit()` | Same order, no exit commands. | + +### Deviation register + +Logging is not a deviation. `_systemMsg`, `debug`, `verbose`, `msg` prefixes, +progress, sudo prompts, command-response handling, `captureStderr`, and the +default error listener all read the active aliases and keep their current +behaviour. Only the following need code changes. + +| ID | Deviation | Impact | Resolution | +| --- | --- | --- | --- | +| D1 | More than one live connection | `this.connection` / `this._stream` are aliases, not the whole session | `_connections` records plus active aliases. | +| D2 | Parent stream stays open during a hop | Late parent data could enter the child buffer | Stream handlers check `context === _activeContext()` before emitting `data` / `stderrData`. | +| D3 | Child connection has its own `close` | A child close must not advance the primary-host queue | Close handler branches on `context.isPrimary`; child close -> `_previousHost()`. | +| D4 | No `exit` command leaves a hop | The old `exitCommands` queue has no producer | Remove the queue and its drains; leaving a hop closes its connection. | +| D5 | Credentials are local to the runner | Keys and agents on the jump host no longer work | Migration to a local `privateKey` or local `agent`. | +| D6 | Host-key policy changes | `StrictHostKeyChecking=no` is gone | `ssh2` defaults; opt in with `hostHash` / `hostVerifier`. | +| D7 | `server.ssh` has no equivalent | Flags such as `logFile`, `configFile`, `escape` disappear | Remove in the major release; map supported fields in the migration table. | +| D8 | `forwardOut` can fail before a child client exists | No child connection to close | `_hopFailed` pops the record, restores the parent, emits `error`, and resumes the parent path. | +| D9 | An inactive ancestor can emit `close` / `error` | The active child is not the failed connection | Close/error handlers act on the event's context; an ancestor failure tears down its descendants first. | +| D10 | A close can be expected | A reboot or network command closes the connection on purpose | Record `expectedClose` from the command; the transport change still follows the normal close path, and the reconnect policy uses the flag later. | + +`keyboard-interactive` is also unchanged in contract: `_bindConnection` already +installs it per client, and the instance event carries that client's `finish`. +Inactive-parent timers are cleared by `_removeListeners(context)` on every host +switch; `_hopFailed` must do the same through `_closeContext`. + +## Properties + +### Host properties: unchanged + +These stay on the host object and apply to the active context exactly as they do +for a primary host: + +`commands`, `hosts`, `sessionText`, `connectedMessage`, +`readyMessage`, `closedMessage`, `showBanner`, `verbose`, `debug`, `progress`, +`exposeCredentials`, `commandResponse`, `captureStderr`, +`commandTimeoutRetries`, `abortOnSudoFailure`, `pty`, `window`, +`streamEncoding`, `standardPrompt`, `standardPromptRegex`, `passwordPrompt`, +`passPromptText`, `textColorFilter`, `asciiFilter`, +`disableColorFilter`, `disableASCIIFilter`, `enter`, `idleTimeOut`, +`dataIdleTimeOut`, and the `on*` / `msg` handlers. + +`passwordPrompt` and `passPromptText` stay because `sudo` still detects +password prompts. `passphrasePrompt` and `exitCommands` are removed with the +command path. + +`sessionText` remains per host. `_mergeNestedText` prefixes a nested host's +text with `\n: ` and merges it into its **immediate parent**, not the +primary. A child finalizes before its parent, so the deepest text travels up one +level at a time and lands in traversal order. The primary ends up carrying the +whole subtree, and a three-level run reads +`host1,hosta,hostaa,hostaaa` rather than `host1,hostaaa,hostaa,hosta`. + +### Server properties: same contract, different source + +| Property | Primary | Hop | Notes | +| --- | --- | --- | --- | +| `host` | `ssh2` connect | `forwardOut` destination | The jump host resolves the name. | +| `port` | `ssh2` connect | `forwardOut` destination port | Defaults to `22`. | +| `userName` | `ssh2` connect | `ssh2` connect | `username` alias applied by `_normalizeServer`. | +| `password` | `ssh2` connect | `ssh2` connect | Used for the hop login, not the parent shell. | +| `privateKey` | `ssh2` connect | `ssh2` connect | Must be readable by the **local** process. | +| `passPhrase` | `ssh2` connect | `ssh2` connect | `passphrase` alias applied. | +| `agent` | `ssh2` connect | `ssh2` connect | Local agent, not the jump host's agent. | +| `tryKeyboard` | `ssh2` connect | `ssh2` connect | Same event path. | +| `hostHash` / `hashMethod` | `ssh2` connect | `ssh2` connect | Same verifier contract. | +| `hostVerifier` | `ssh2` connect | `ssh2` connect | Recommended for hops. | +| `algorithms` | `ssh2` connect | `ssh2` connect | Replaces `server.ssh.cipherSpec` / `macSpec`. | +| `readyTimeout` | `ssh2` connect | `ssh2` connect | Applies to the child login. | +| `keepaliveInterval` / `keepaliveCountMax` | `ssh2` connect | `ssh2` connect | Applies per connection. | +| `forceIPv4` / `forceIPv6` | `ssh2` connect | `ssh2` connect | Replaces `server.ssh.forceAddressType`. | +| `sock` | not used | set by the hop | Do not set it on the host object. | +| `ssh` | not used | **removed** | See the migration table. | + +### Removed internals + +| Item | Reason | +| --- | --- | +| `src/ssh2shell/ssh-command.js` and `buildSshCommand()` | No command line to build. | +| `shellQuote()` and `shellControlChars` in `util.js` | Only used to build and validate the nested `ssh` command. | +| The `Security Alert` error path | There is no shell string to validate. | +| `_sshConnect()` | Replaced by the hop branch of `_connect(parent)` (via `_connectHop()`). | +| `_processSSHPrompt()` | `ssh2` owns authentication. | +| The `sshToNextHost` case in `_onData()` | There is no `ssh` command in the parent shell. | +| The `sshToNextHost !== true` guard in `_commandComplete()` | There is no nested-command output to suppress. | +| `sshObj.sshAuth` and `sshObj.sshToNextHost` | No prompt state to track. | +| The `exitCommands` queue, `exitCommands.push('exit')`, the `_runExit()` drain, and the `_beginStopExit()` drain | There is no nested shell to leave; leaving a hop closes its connection. | +| `passphrasePrompt` | Only used by `_processSSHPrompt()`. `passwordPrompt` stays for `sudo`. | +| `server.ssh.*` and the forced `StrictHostKeyChecking=no` | There are no command-line flags to map. | + +## Methods + +| Method | Change | +| --- | --- | +| `connect()` | Unchanged; still starts the primary host. | +| `_connect(parent = null)` | **Shared.** Makes a context record active, then either connects directly (`parent === null`) or pushes the parent and connects via `parent.connection.forwardOut` (`parent` set). All wiring goes through `_openClient`. | +| `_connectHop()` | **New, thin adapter.** `_connect(_activeContext())`. Holds no logic. | +| `_openClient(context, options)` | **New.** Creates the client, binds context-scoped handlers, and connects. | +| `_nextHost()` | Switches the host and calls `_initiate(this._connectHop)` instead of `_sshConnect`. Queues no exit command. | +| `_previousHost()` | Closes the active child through `_closeContext` (listeners, stream, connection, finalize), pops the parent record, makes the parent active again, then calls `_runExit()` on it. | +| `_nextPrimaryHost()` | Finalizes the current primary, closes the active record and every ancestor, clears the stack, resets `_stream` / `connection`, then starts the next primary. | +| `_runExit()` | Simplified. `hosts` -> `_nextHost()`; `_connections.length > 0` -> `_previousHost()`; literal `exit` -> run it; else `close()`. No `exitCommands` drain. | +| `_finalizeHost()` | Primary detection uses `host === _connections[0].host`. | +| `_finalizeRun()` | Iterates the record stack deepest-first. | +| `_mergeNestedText()` | Merges into the immediate parent record; falls back to the last ancestor for legacy bare-host stacks. | +| `_onData()` | The SSH prompt case is removed. Sudo, normal prompt, first prompt, and timeout handling are unchanged. | +| `_commandComplete()` | The `sshToNextHost` guard is removed. Response handling, `commandResponse`, `captureStderr`, and handler flags are unchanged. | +| `_processSudoPrompt()` | Unchanged. `passwordPrompt` is still used for `sudo`. | +| `stop()` | Clears queues as today, sends Ctrl-C if a command is in flight, then closes the active record and every ancestor. No exit commands. | +| `_beginStopExit()` | Waits for the prompt or `_finishStop()`. No exit-command drain. | +| `_finishStop()` | Closes the active stream and every ancestor connection, then finalizes. | +| `close()` / `_closeStreamNow()` | Closes the active record and its ancestors, then follows the primary-host contract. | +| `_hasLiveStream()` | Checks the active record's stream. | +| `_removeListeners(context)` | **Signature change.** Removes only the handlers in `context.listeners` and clears that record's timers. Never reads `this.sshObj`; does not call `_progressEnd()` or reset instance timer values. | +| `_loadDefaults(context)` | **Signature change.** Binds host handlers into `context.listeners`, stores the record's `idleTime` / `dataIdleTime`, and resets per-command state. No longer resets `sshAuth` / `sshToNextHost`. | +| `_closeContext(context, reason)` | **New.** The only record teardown: remove listeners, close stream and connection, finalize the host. Idempotent. | +| `_failContext(context, err, reason)` | **New.** The only record failure entry: descendants deepest-first, close the record, then `_endPrimary` (primary) or `_popTo()` + `_runExit()` (hop). | +| `_popTo(context)` | **New.** Drop the failed record and its descendants, then restore the parent. Used only by `_failContext`. | +| `_endPrimary(reason)` | **New.** Exactly-once primary advance; shared by the primary `connection.on('close')` handler, the synchronous connect throw, and `_failContext`. The public `close()` / `stop()` still go straight to the callback. | +| `_hopFailed(context, err)` | **New.** Emits the record's `error`, then calls `_failContext`. | +| `_descendantsOf(context)` | **New.** Active record and records above `context`, deepest-first, excluding `context`, for teardown. | +| `_runCommand()`, `_nextCommand()`, `_checkCommand()`, `_processNotifications()`, `_scheduleIdleTimeout()`, `_applyHandlerFlags()` | Reused unchanged, against the active record. | +| `_captureStderr()`, `_mergeStderr()`, `_handleCommandResponse()` | Reused unchanged. | +| `_progressStart()` / `_progressEnd()` / `_progressBreak()` | Reused unchanged; one heartbeat for the active command. | +| `_sanitizeResponse()` | **Changed.** Slices after the **last** echoed command instead of the first. A long command makes the PTY redraw, and the redraw can place the previous prompt before the echoed command; that prompt must not complete the new command. When the full echo is not in the buffer yet, the old partial-echo removal still applies. | + +### Long-command redraw fix + +The clean-VM provisioning run exposed a prompt-detection bug that the existing +live suite did not hit. The network command in `test/provision/provision.js` is +about 2,900 characters. The PTY redraws it with `\u001b[H\u001b[J`, NUL bytes, +and an OSC title update. The redraw can put a prompt **before** the echoed +command. `_sanitizeResponse()` removed the command from the middle and left that +prompt at the end of the buffer, so the end-anchored `standardPrompt` matched and +the command was treated as complete before its output arrived. The session then +closed and `network: OK` never appeared. + +`_sanitizeResponse()` now finds `lastIndexOf(command)` and tests only the text +after it. A prompt that belongs to the previous command is outside the slice; the +prompt that follows the real output still matches. The fallback keeps the +partial-echo behavior for a buffer that contains only the start of the echoed +command. `commandResponse: 'handled'` is unaffected because it strips the echo +through `stripEchoedCommand()` in `_handleCommandResponse()`. + +Regression tests live in `test/unit/command-response.test.js`: one for a prompt +before the echo, and one for command text repeated in the output. + +## Close handling + +### Record teardown + +Add one helper that is the only way a connection is closed: + +```js +_closeContext(context, reason) { + if (!context || context.closed) { + return; + } + context.closed = true; + + // Remove this record's host handlers before the connection closes. The + // active aliases may already point at a parent or child when a late close + // event arrives, so the record must carry the config that bound them. + this._removeListeners(context); + + if (context.stream && typeof context.stream.close === 'function') { + context.stream.close(); + } + if (context.connection && typeof context.connection.end === 'function') { + context.connection.end(); + } + + this._finalizeHost(context.host, reason); +} +``` + +`_closeStreamNow()`, `_finishStop()`, `_previousHost()`, `_failContext()`, +`_closeAllContexts()`, and `_nextPrimaryHost()` all use it. Closing a record is +idempotent, and `context.closed` is what stops the resulting `stream` / +`connection` events from re-entering the close path. Popping the record is the +caller's job: `_previousHost()` closes the active child and pops its parent; +`_nextPrimaryHost()` closes the active record and clears the stack. + +### Listener ownership + +Host handlers are bound by `_loadDefaults()` and must be removed using the config +that supplied them. Today `_removeListeners()` reads `this.sshObj`, which is +correct only while one host is active. A hop breaks that assumption: a close or +error for an ancestor can arrive after the active aliases point at a child, and +the child's `sshObj` does not have the ancestor's handlers. + +Give each record its own listener set: + +```js +context.listeners = { + data: fn, + stderrData: fn, + commandProcessing: fn, + commandComplete: fn, + commandTimeout: fn, + end: fn, + error: fn, + msg: fn, + 'keyboard-interactive': fn, +}; +``` + +`_loadDefaults(context)` binds into `context.listeners`; +`_removeListeners(context)` iterates that map and calls +`this.removeListener(eventName, listener)`. It never reads `this.sshObj`. The +instance defaults (`_onData`, the default `error` listener, the progress +listener, the fallback `msg`) stay on the instance and are never removed by a +host switch. + +Timers follow the same rule: `idleTimer` and `dataReceivedTimer` become +record-scoped (`context.idleTimer`, `context.dataReceivedTimer`) so an ancestor +close cannot cancel the active child's timeout. `_stopTimer` and `_closeTimer` +remain run-level. + +Removal points: + +| Moment | Records whose listeners are removed | +| --- | --- | +| Hop completes (`_previousHost`) | The hop | +| Hop fails (`_hopFailed`) | The hop | +| Hop's descendants are torn down | Each descendant, deepest-first | +| Primary completes and a next primary exists (`_nextPrimaryHost`) | The primary | +| Primary fails and a next primary exists (`_endPrimary`) | The primary | +| `close()` / `stop()` / `_finishStop()` | Active record and ancestors, deepest-first | +| Final primary close, no next primary | Same `_closeContext` path, so teardown is uniform | +| Any host switch | Only the outgoing record; never the incoming one | + +`_closeContext(context, reason)` is the single place that closes a record, so it +is also the right place to remove that record's listeners, before closing the +stream and connection. That keeps the rule true for normal completion, failure, +and run-ending teardown. + +The current code removed `_removeListeners()` from the connection `close` +handler because the run terminates there. That is still true for the final +primary, but not for a hop: a hop close returns to a live parent, so its +handlers must be removed or they keep firing against the parent's events. + +### `stop()` + +The queue clearing and Ctrl-C behaviour is unchanged. The difference is the +final teardown: + +1. Clear every `commands` and `hosts` queue, plus `_hosts`. +2. If a command is in flight, write `Ctrl-C` to the active stream and wait for + the prompt or `idleTimeOut`. +3. `_finalizeRun()` deepest-first: one `end` per visited host. +4. Close the active record, then each ancestor, deepest-first. Do not send + `exit` to a hop. +5. Call the final callback once. + +There is no `exitCommands` step: the child connection is the exit. + +`_forceStop()` uses the same teardown, so a stuck hop cannot leave a parent +connection open. If a hop is still waiting on `forwardOut`, `_hopFailed` sees +`_stopping` and closes the parent record instead of restoring it as active. + +### `close()` and `close({ graceful: true })` + +- **Plain `close()`** closes the active record and its ancestors, finalizes + them, and then follows the existing primary-host contract. If the active + record is a hop, the parent is closed too; the run does not continue on a + half-closed stack. +- **Graceful `close()`** keeps the existing intent: finish the current command + path, back out of nested hosts, then close. `_runExit()` walks `hosts` and + `_previousHost()` closes each child connection. No `exit` command is needed + for a hop. +- Remaining primary hosts still run after either close, matching the current + compatibility contract. + +### Connection and stream events + +Every handler returns immediately when `context.closed` or `context.failing` is +set, so a close that races the normal teardown cannot navigate twice. The hop +`connection.on('close')` handler also returns when `_closing`, `_stopping`, or +`_runComplete` is set: a plain `close()` tears the stack down itself and must not +restore the parent. + +| Event | Primary record | Hop record | +| --- | --- | --- | +| `stream.on('finish')` | `_finalizeHost(context.host, 'stream-finish')` | Same. | +| `stream.on('close')` | `context.connection.end()` | Same. | +| `connection.on('close')` | Finalize, emit `closedMessage`, then next primary or callback | Finalize child, restore parent, `_previousHost()` / `_runExit()`. | +| `connection.on('error')` | Existing `error` contract | Existing `error` contract; do not close the parent unless the error is terminal for the child. | +| `forwardOut` error | n/a | Emit `error`, make the parent active again, continue the parent path. | + +A hop `connection.on('close')` must never call `_nextPrimaryHost`. The +`context.isPrimary` flag is the guard. If an ancestor closes or errors while a +child is active, tear down the descendants first, then let the ancestor event +follow the primary contract. + +### Finalization + +`_finalizeRun()` currently collects the current host and `_connections` in +reverse. It becomes: + +```js +const hosts = []; +if (this._active && this._active.host) { + hosts.push(this._active.host); +} +for (let index = this._connections.length - 1; index >= 0; index -= 1) { + const host = this._connections[index].host; + if (host && host.server) { + hosts.push(host); + } +} +for (const host of hosts) { + this._finalizeHost(host, reason); +} +``` + +The active host is not in `_connections`, so it is added first and the ancestors +follow in reverse. Keep a fallback that adds `this.sshObj` when there is no +active record (before `_connect` or after a reset). `_finalizedHosts` and +`_mergedHosts` keep finalization and text merging idempotent across the normal +path and an abrupt drop. + +A failed record is finalized like any other record, so it emits `end` with the +text it produced. Only descendants that never started are skipped: they are not +active and not in `_connections`, so they are never finalized. This is why +`test/live/host_faults.js` expects `bad-deep` and `bad-primary` in `end-order` +but not `bad-deep-child`. + +## Primary failure policy + +**Decision: a failed primary does not end the run. Each remaining primary is +attempted once, in order.** This is the current `connection.on('close')` +behaviour; the change makes it explicit and covers the paths that bypass it. + +| Outcome | Action | +| --- | --- | +| Primary connects and finishes | Finalize, next primary or callback (unchanged) | +| Primary connect/auth/stream fails | Emit `error` for that primary, finalize it, advance to the next primary | +| Synchronous throw from `connection.connect()` | Same as a connect failure; do not rely on a `close` event | +| `stop()` / `abort` | No advance; finalize the run and call the callback once | +| `close()` | No advance; close and call the callback once | +| `skipPrimaryHosts` | `_hosts` cleared; callback after the current primary | +| No primaries left | `_callFinalCallback()` with `_allSessions` | + +“Keep trying” means the next primary, not the same one. Retrying the same +primary is reconnect, and stays out of scope. + +Exactly-once advance: route both `connection.on('close')` and the synchronous +throw catch through one method: + +```js +_endPrimary(reason) { + // Navigation only. The caller reports first: the close handler emits the + // `Connection close` error or `closedMessage`; the synchronous-throw path + // emits its error before calling _failContext(). + if (this._primaryEnded || this._runComplete) { + return; + } + this._primaryEnded = true; + this._finalizeRun(reason); + + if (this._stopping || this._closing) { + return this._callFinalCallback(); + } + if (this._hosts.length > 0) { + return this._nextPrimaryHost(this._connect); + } + return this._callFinalCallback(); +} +``` + +`_nextPrimaryHost()` resets `_primaryEnded = false` when it starts the next +primary, so a late `close` from the previous client hits the guard instead of +starting a second primary. + +Nested failures do **not** advance primaries. A hop failure is terminal for that +host and its subtree because the path to it is gone: + +- `_hopFailed(context, err)` emits `error`, finalizes the failed host, restores + the parent, then runs `_runExit()` on the parent. +- The parent's remaining `hosts` (siblings) still run. +- The failed host's own `hosts` (descendants that have not started) never run and + get no `end`. Descendants that were already active are finalized deepest-first + before the failed host is closed. +- The failed hop is not retried. Reconnect, if ever added, starts from the + nearest live ancestor, not from the failed record. + +With `host1.hosts = [hosta, hostb]` and `hostb.hosts = [hostbb]`: + +| Failure | What runs next | +| --- | --- | +| `hosta` fails | `hostb` (sibling) still runs | +| `hostb` fails | `hostbb` does not run (its parent never connected); the run backs out to `host1`, then to the next primary | + +A nested failure therefore costs one subtree, not the primary and not the run. +A primary failure costs that primary only; later primaries still run. + +### What counts as a failure + +“Failure” is not one thing, and the current code treats these differently: + +| Failure | Current code | New model | +| --- | --- | --- | +| Primary connect/auth fails | `error` + `close` -> next primary (verified: the next primary is attempted) | Same, via `_endPrimary()` | +| Hop connect/auth fails | Inferred from shell text in `_processSSHPrompt()`, then `_previousHost()`; siblings continue | `_hopFailed()`; siblings continue | +| Command timeout on a hop | The nested shell shares the primary stream, so the default handler closes the primary stream and the primary ends | Closes only that hop's stream/connection; siblings continue | +| Stream error on a hop | Same: the primary stream is closed | Scoped to the hop | + +The last two are a real improvement, not just tidying. Today a single nested +command that never returns a prompt takes down the whole primary. With one +stream per record, a hop failure costs only that hop and its descendants. + +The verified primary behaviour is worth recording because it is easy to assume +otherwise: + +```text +CONNECT 1 one.test +ERR ECONNREFUSED | Connection +END one.test +CONNECT 2 two.test +CALLBACK "one.test: \ntwo.test: ..." +``` + +The first primary fails before `ready`, `close` fires, and `_nextPrimaryHost()` +starts the second. The gap is only the synchronous `connection.connect()` throw, +which has no `close` event to trigger that advance. + +## Host navigation on failure + +Error handling answers "what is reported". Host navigation answers "what runs +next". They are separate decisions, and a command failure that changes connection +state takes the same navigation path as a connection failure. + +### Failure classes + +| Class | Examples | Navigation | +| --- | --- | --- | +| Fatal to the run | `stop()`, `abort`, `close()`, `close({ graceful: true })` | No navigation. Tear down the active record and ancestors deepest-first, finalize, call the callback once. | +| Fatal to a record | connect/auth/`forwardOut` error, connection `close`, stream `error`, command timeout that closes the stream | Contained by position: a primary goes to `_endPrimary`, a hop goes to `_hopFailed`. | +| Expected drop | A command marked `breaksConnection` or matching `connectionBreakingCommands` | Same navigation as a fatal record failure in this change. `expectedClose` only changes reporting and the future reconnect decision. | +| Command failure that keeps the connection | Non-zero exit, missing command, handled error text | Not a failure for navigation. `commandComplete` runs and `_nextCommand()` continues. | + +The single entry point for a record failure: + +```js +_failContext(context, err, reason) { + if (!context || context.closed || context.failing) { + return; + } + context.failing = true; + + // Descendants ride on this record's transport. Tear them down deepest-first + // before the record itself, so each is finalized once with its own text. + for (const descendant of this._descendantsOf(context)) { + this._closeContext(descendant, 'ancestor-failed'); + } + this._closeContext(context, reason); + + if (context.isPrimary) { + return this._endPrimary(reason); + } + this._popTo(context); // drop the failed record and its descendants + return this._runExit(); // parent siblings, then up +} +``` + +`_endPrimary` finalizes and either starts the next primary or calls the callback. +`_hopFailed(context, err)` is the hop wrapper: it emits the record's `error`, then +calls `_failContext(context, err, 'hop-failed')`. The connection handlers, the +`forwardOut` error, the stream `error`, and a connection-breaking command timeout +all call `_failContext`, so there is one navigation rule rather than one per +source. The `failing` flag makes a close that arrives while descendants are being +torn down a no-op instead of a second unwind. + +`_popTo(context)` drops the failed record and its descendants from +`_connections` until `context.parent` is on top, then pops it to make the parent +active. `_popContext()` alone is not enough: the stack above a failed ancestor +still holds the descendants that were just closed. + +Because `_popTo()` restores the parent and `_runExit()` re-evaluates the parent's +`hosts` and `_connections`, a contained failure needs no special sibling logic. +The parent simply continues its normal path. + +### Navigation matrix + +Using the confirmed configuration: + +```text +host1.hosts = [hosta] hosta.hosts = [hostaa] hostaa.hosts = [hostaaa] +host2.hosts = [hostb,hostc] hostb.hosts = [hostbb] hostc.hosts = [hostcc] +host3.hosts = [hostd,hoste,hostf] +primary list = [host1, host2, host3] +``` + +| Failure at | Descendants torn down | Runs next | Eventually | +| --- | --- | --- | --- | +| `hosta` connect/auth | none started | `hostb` (host1's next sibling) | host1 completes, then host2 | +| `hosta` after `hostaa` is active | `hostaaa` if active, then `hostaa`, deepest-first | `hostb` | host1 completes, then host2 | +| `hostaa` | its active descendants only | `hosta`'s remaining siblings (none), then `host1`'s remaining siblings (`hostb`) | host2 | +| `host2` connect/auth | none | `host3` | callback after host3 | +| `host2` after `hostbb` is active | `hostbb` | `host3` (host2 has no parent) | callback | +| `hostb` command timeout | none beyond the record | `hostc` (sibling) | host2 completes, then host3 | +| `host3` (last primary) | active hop, if any | callback | run ends | +| Any record during `stop()` / `close()` | all active records | callback | run ends | + +The rows encode four rules: + +- **A hop failure never skips its siblings** and never advances the primary + queue. The parent is restored and `_runExit()` continues. +- **A primary failure never resumes inside that primary**, because there is no + parent. It advances to the next primary. Active descendants are finalized + before the advance. +- **Descendants that never connected get no `end`.** Descendants that were + active are finalized with their own session text, deepest-first, because they + did run. +- **No retry.** Each record is attempted once. A failed hop is not re-opened and a + failed primary is not retried. Reconnect is the separate follow-up. + +### Interaction with the traversal loop + +`_failContext` only chooses the failure branch. It does not duplicate the normal +loop: + +```text +failure on a record + -> _failContext(record) + -> tear down active descendants (deepest-first) + -> close and finalize the record + -> primary: _endPrimary() -> next primary or callback + -> hop: _popTo(record) -> _runExit() on the parent + -> parent.hosts (siblings) + -> _connections (keep backing out) + -> primary 'exit' (unchanged) + -> close() +``` + +This is why a command failure that affects connection state needs no separate +navigation: it calls `_failContext` at the same level a connection failure does. +A command that only fails, without touching the transport, never enters this +path. + +## Connection loss and reconnection + +The transport swap does not add automatic reconnection. It makes connection loss +observable per hop, which the command path cannot do: a nested `ssh` drop is only +inferred from shell text, and the parent shell is the only connection the library +owns. + +| Failure | Records affected | This change | Possible follow-up | +| --- | --- | --- | --- | +| Target (leaf) connection drops | Leaf record and its descendants | Emit `error` / `close` for that record, finalize it, restore the parent, continue the parent path | Re-open the leaf with `forwardOut` and retry, subject to an idempotency policy | +| Expected drop after a breaking command | The record that ran the command | Same as an unexpected drop for now | Record `expectedClose`, then reconnect with `reconnectRetries` / `reconnectDelay`; emit `reconnect` with `expected: true` and resume at the next command. Only exhaustion emits an `error`. | +| Jump host connection drops | That record and every descendant | Tear down the descendants, then follow the primary close contract | Reconnect from the nearest live ancestor, or fail the run | +| Primary connection drops | The whole stack | Existing behavior: finalize, next primary or callback | Optional reconnect before advancing | + +Design constraints for a future reconnect policy: + +- **Command replay is not automatically safe.** A command may have partially + executed before the drop. Retry must be opt-in per host and documented. +- **Reconnect from a live ancestor.** Use `forwardOut` from the nearest record + that is still connected, not from the failed record. +- **Keep the pre-drop text.** `sessionText` must retain what ran and mark the + boundary, so callers can tell what was lost. +- **Do not resurrect finalized hosts.** A reconnect must respect `stop()`, + `close()`, and `_finalizedHosts`. + +### Expected drops: reconnect after a known breaking command + +A close event on its own is not a reconnect signal. An unexpected drop is a +failure, but a drop caused by a command the run just issued (`reboot`, +`shutdown -r`, `systemctl restart sshd`, a network reconfiguration) is expected. +Treating both the same either retries on a real failure or gives up on a planned +restart. + +Mark the intent at the command level: + +- A command can opt in with `breaksConnection: true`, or a host can list + `connectionBreakingCommands` as regular expressions. Before the command is + written, the active record gets `expectedClose = true`. +- If the command completes normally, clear `expectedClose`; the connection + stayed up and nothing special happened. +- On `close`, if `record.expectedClose` is set, do not run the failure path. + Mark the record `reconnecting`, keep it on the stack, and schedule a + reconnect. Otherwise follow the normal finalize path. + +Reconnect uses the same transport as the original connection: + +| Record | Reconnect | +| --- | --- | +| Primary | `client.connect(server)` | +| Hop | `parent.connection.forwardOut(...)` then `client.connect({ ...server, sock })` | + +The retry budget mirrors `commandTimeoutRetries`: + +```js +sshObj.reconnectRetries = 3; // attempts after the first drop +sshObj.reconnectDelay = 5000; // ms between attempts +``` + +- Each attempt waits `reconnectDelay`, reconnects, waits for `ready`, and opens + a new shell. +- The record's timer is tracked and cleared by `stop()`, `close()`, and + `_finalizeRun()`. +- On success, the record resumes at the next command. The command that broke + the connection is treated as complete; see + [The breaking command's completion](#the-breaking-commands-completion). +- On exhaustion, emit `error` with the attempt count and fall back to today's + close semantics: finalize the record, restore the parent, and continue the + parent path. + +### The breaking command's completion + +The command that broke the connection still completes from the caller's point of +view: it ran, and the connection ended before a prompt. Fire the handler with +whatever output arrived: + +- `commandComplete` fires with the buffer captured before the close and + `details = { rawResponse, connectionClosed: true, expectedClose: true, reason }`. +- `details.rawResponse` is the partial buffer. `commandResponse: 'handled'` and + `captureStderr` apply as usual, so `payload` and `details.stderr` behave the + same as a normal completion. +- `sessionText` keeps the partial response and gets a boundary marker recording + that the command did not return a prompt. +- Handler flags (`abort`, `skipCommands`, `skipHosts`, `skipPrimaryHosts`) are + applied before the reconnect is scheduled, so a handler can still cancel the + run. +- The handler does not advance the queue. `_nextCommand()` runs after the + reconnect succeeds, so the next command is not written to a dead shell. + +Guard the emission with the existing `_commandInFlight` flag. If the prompt +already completed the command before the close arrived, the handler has already +fired and the close only handles the reconnect. + +An unexpected drop does not fire `commandComplete`: the command did not +complete, and the existing `Connection close` error is the signal. The partial +buffer still has to reach `sessionText`, because `_finalizeHost` only reads +`sessionText` and never looks at `_buffer`. + +Add one helper for the partial-buffer append: + +```js +_appendPartial(reason) { + if (!this._buffer) { + return ''; + } + const partial = this._buffer; + this._buffer = ''; + this.sshObj.sessionText += partial; + this.sshObj.sessionText += `\n[connection closed${reason ? `: ${reason}` : ''}]\n`; + return partial; +} +``` + +- **Expected drop:** the completion path appends the partial response and the + boundary marker, then clears `_buffer` before scheduling the reconnect. The + close path then sees an empty buffer and adds nothing, so the text is not + duplicated. +- **Unexpected drop:** no `commandComplete`; `_appendPartial('connection-close')` + runs before `_finalizeRun()`, so `end` and the callback see the partial text. +- **No command in flight:** the same helper preserves banner or prompt text that + arrived before the close. +- Clearing `_buffer` in both paths is what stops a later stream `finish` from + appending the same text twice. + +### Reporting an expected drop + +A planned reboot should not look like a failure, and a failed reconnect should +not look like the original drop. Report both through one event: + +| Event | Payload | When | +| --- | --- | --- | +| `reconnect` | `(sshObj, details)` | When a reconnect is scheduled, before each attempt, and once on success | +| `error` | `(err, 'Reconnect', false)` | Only when the last reconnect attempt fails; an unexpected drop still emits the existing `Connection close` error | + +`details` is `{ phase, attempt, maxRetries, delay, expected, reason }`: + +- `phase` is `'scheduled'`, `'attempt'`, or `'success'`. +- `reason` is the matched command (`'reboot'`, `'systemctl restart sshd'`) for + an expected drop. `'connection-lost'` is reserved for a future opt-in to + retry unexpected drops. +- `expected` is `true` for a planned drop. + +The initial close is reported as: + +- **Expected drop:** `msg` plus a `reconnect` event with `expected: true`. No + `error`; a reboot is not a fault. +- **Unexpected drop:** the existing `Connection close` error and no retry. + +On exhaustion, the error carries the same details: + +```js +const err = new Error(`Reconnect failed after ${details.maxRetries} attempts`); +err.level = 'Reconnect'; +err.reconnect = details; +this.emit('error', err, 'Reconnect', false); +``` + +That keeps a reboot out of the error stream while still surfacing a real +reconnect failure, and lets a handler log "host rebooted" from the `reconnect` +event without treating it as a fault. Wire it like the other handlers: a host +`onReconnect(sshObj, details)` receives the same payload, and the event is a +no-op when no handler is set. + +Rules: + +- **Only the record whose connection closed reconnects.** A jump-host drop + cannot be repaired from below. Reconnect the jump host from its own parent, + then re-establish its descendants; until that is implemented, a jump-host drop + tears down the descendants and follows the close contract. +- **Only expected closes reconnect.** An unmarked drop is a failure. Do not + silently retry it; command replay is unsafe. +- **Respect stop and close.** A scheduled reconnect is cancelled by `stop()` and + `close()`, and never resurrects a finalized host. +- **Keep the text boundary.** `sessionText` keeps the pre-drop output and gets a + marker, so the caller can tell the command was cut short. +- **Do not replay the breaking command.** The restart is the point of the + command; rerunning it would restart the host again. Replay, if ever needed, is + a separate per-command option. + +This stays out of the transport change. The initial implementation preserves +today's close semantics: a hop drop finalizes that host, returns to the parent, +and lets the normal traversal decide what runs next. The reconnect policy above +is the designed follow-up, because the transport change is what makes the close +event trustworthy enough to act on. + +## Host config traversal + +### Current code order + +This is the order the code actually runs, verified against `src/ssh2shell.js`. +It is a loop, not a single pass: `_nextPrimaryHost()` is both the start and the +continuation after each primary closes. + +| Step | Entry | What happens | +| --- | --- | --- | +| 1. Normalize the host list | `constructor()` | `typeIsArray(hosts) && hosts.length > 0 ? hosts : [hosts]`; `_primaryHostCount` and `_multipleHosts` are fixed here. | +| 2. Start / next primary | `connect()` -> `_nextPrimaryHost(this._connect)` | If `_hosts` has an entry: finalize the current primary, `_removeListeners()`, reset `_stream` and `_connections`, shift the next primary, reset `_primaryhostSessionText`, then `_initiate()`. | +| 3. Load defaults | `_initiate(action)` | `_loadDefaults()` first, then the action. Defaults, prompts, filters, timers, and host handlers are per host. | +| 4. Connect | `_connect()` | Bind client events, open the shell on `ready`, bind stream events, then `connection.connect(server)`. | +| 5. First command | `_onData()` | The first `standardPrompt` with `command === ''` calls `_nextCommand()`, which shifts `sshObj.commands` into `this.command`. | +| 6. Run commands | `_runCommand()` / `_commandComplete()` | A prompt with a command calls `_commandComplete()`, then `_nextCommand()` for the next one. | +| 7. No commands, nested hosts | `_nextCommand()` -> `_runExit()` -> `_nextHost()` | `_removeListeners()`, shift the child, push the current `sshObj` onto `_connections`, assign the child, `_initiate(_sshConnect)`. | +| 8. No nested host, ancestors | `_runExit()` -> `_previousHost()` | Finalize the child, `_removeListeners()`, pop the parent, reapply its timers, `_runExit()` on the parent. The parent has no commands left, so it goes to its remaining `hosts` or backs out again. | +| 9. Drained | `_runExit()` -> `close()` | `_closeStreamNow()` -> `_finalizeRun('close')` -> stream/connection close -> `connection.on('close')` -> `_callFinalCallback(_allSessions)`. | +| 10. Next primary | `connection.on('close')` | If `_hosts` still has entries, `_nextPrimaryHost(this._connect)`; otherwise the callback. | + +Notes that matter for the transport change: + +- **Nested text is merged one level at a time.** `_finalizeHost(nested)` calls + `_mergeNestedText()` into its immediate parent's `sessionText`. Because a + child finalizes before its parent, the parent then carries the child's text + when it merges upward. `_finalizeHost(primary)` appends + `_primaryhostSessionText` to `_allSessions`, so the callback sees one string + per primary with the whole subtree in traversal order. +- **The parent never re-runs commands.** Its queue was consumed before it + nested; on return `_runExit()` only looks at `hosts`, then `_connections`. +- **`_finalizeRun()` is the safety net.** It finalizes the active host plus + `_connections` in reverse, so a transport drop still yields complete text. +- **The final close does not call `_removeListeners()`.** Host handlers are + detached on a switch only; the final close relies on `_closing` / + `_runComplete` and the `close` event. +- **Connection failure has no direct branch in `_connect()`.** It relies on + `connection.on('error')` + `connection.on('close')` -> `_nextPrimaryHost`. + A synchronous throw from `connection.connect()` only emits `error`, and there + is no guaranteed `close`, so that case can stall. A nested failure is inferred + from shell text in `_processSSHPrompt()` and backs out with `_previousHost()` / + `_runExit()`. The hop path replaces both with `_hopFailed`. + +#### The current nested topology is flat, not chained + +This is the most important behaviour the transport change fixes, and it is easy +to miss because the traversal order looks correct. + +`_processSSHPrompt()` pushes `exit` onto `sshObj.exitCommands` when the nested +shell reports a standard prompt. `_runExit()` drains `exitCommands` before it +looks at `sshObj.hosts`, so a nested host leaves its `ssh` shell before it runs +its own nested hosts. The next host is then connected from whatever shell is +active, which is the primary, not the host that just finished: + +```text +host1 -> ssh hosta (from host1's shell) +hosta commands +hosta _runExit: exit (leaves hosta, back on host1's shell) +hosta _runExit: hosts (ssh hostaa from host1's shell, not from hosta) +``` + +So with `host1.hosts = [hosta]`, `hosta.hosts = [hostaa]`, +`hostaa.hosts = [hostaaa]`, the real transport is: + +```text +host1 -> hosta +host1 -> hostaa +host1 -> hostaaa +``` + +not `host1 -> hosta -> hostaa -> hostaaa`. The `_connections` config stack still +records `[host1, hosta, hostaa]`, but only one nested shell is open at a time and +it is always opened from the primary. `tunnel`, `chaining`, and +`tunnel_3_hop` pass today only because every test VM can reach every other test +VM directly. They do not prove a chain. + +This also explains the fault result: a failed `ssh` command returns the parent +prompt, which `_processSSHPrompt()` accepts as success when `sshAuth` is already +true, so the failed host's commands run on the parent shell instead of being +reported as a connection failure. `test/live/host_faults.js` records that +behaviour and is the acceptance test for the new per-hop transport. + +The new model opens a child client through `forwardOut` from its immediate +parent record and keeps every ancestor connection open until the child is closed, +so the topology becomes the real chain and a failed hop is a connection event +rather than shell text. + + +Two edge cases are worth fixing before changing step 1: + +- `hosts = []` becomes `[[]]`, not an empty run; `_loadDefaults()` then reads + `sshObj.server.host` and throws. +- `_nextPrimaryHost()` has no `else`, so it relies on the constructor + guaranteeing at least one entry. `connect()` would emit `newPrimaryHost` with + `undefined` otherwise. + +### Host list normalization + +The constructor should produce a well-defined list, and `connect()` should always +terminate: + +```js +// constructor +const list = typeIsArray(hosts) ? hosts : [hosts]; +if (list.length === 0 || list.some((host) => !host || typeof host !== 'object')) { + throw new TypeError( + 'ssh2shell: a host config object or a non-empty array of host configs is required' + ); +} +this._hosts = list.slice(); // do not consume the caller's array +this._primaryHostCount = this._hosts.length; +this._multipleHosts = this._primaryHostCount > 1; +``` + +- A single host object stays supported. +- An empty array, `null`, or `undefined` fails at construction with a clear + `TypeError`, instead of throwing later inside `_loadDefaults()`. +- `slice()` keeps `shift()` from mutating the caller's array. Today the same + array passed to two runs is drained by the first. +- Nested `hosts` arrays stay lazy; only the primary list is validated. + +`_nextPrimaryHost()` must always finish: + +```js +_nextPrimaryHost(connect) { + if (this._stopping || this._runComplete) { + return this._callFinalCallback(); + } + if (this._hosts.length === 0) { + return this._callFinalCallback(); + } + // ... existing body +} +``` + +`connect()` then always reaches either a primary or the callback. +`_callFinalCallback()` is already idempotent through `_callbackCalled`, so the +extra exit cannot double-call it. + +The traversal contract is unchanged except that there is no exit command to +queue: + +```text +command completes + -> _commandComplete() + -> _nextCommand(): next command, or _runExit() + -> sshObj.hosts (hop to the next nested host) + -> _connections parent (close the child record, return to the parent) + -> literal 'exit' (primary shell) + -> close() +``` + +The confirmed walk, using the full test configuration: + +```text +host1.hosts = [hosta] hosta.hosts = [hostaa] hostaa.hosts = [hostaaa] +host2.hosts = [hostb,hostc] hostb.hosts = [hostbb] hostc.hosts = [hostcc] +host3.hosts = [hostd,hoste,hostf] +primary list = [host1, host2, host3] +``` + +| Step | Active | `_connections` | +| --- | --- | --- | +| 1 | host1 | `[]` | +| 2 | hosta | `[host1]` | +| 3 | hostaa | `[host1, hosta]` | +| 4 | hostaaa | `[host1, hosta, hostaa]` | +| 5 | hostaa | `[host1, hosta]` | +| 6 | hosta | `[host1]` | +| 7 | host1 | `[]` | +| 8 | host2 | `[]` | +| 9 | hostb | `[host2]` | +| 10 | hostbb | `[host2, hostb]` | +| 11 | hostb | `[host2]` | +| 12 | host2 | `[]` | +| 13 | hostc | `[host2]` | +| 14 | hostcc | `[host2, hostc]` | +| 15 | hostc | `[host2]` | +| 16 | host2 | `[]` | +| 17 | host3 | `[]` | +| 18 | hostd | `[host3]` | +| 19 | host3 | `[]` | +| 20 | hoste | `[host3]` | +| 21 | host3 | `[]` | +| 22 | hostf | `[host3]` | +| 23 | host3 | `[]` | +| 24 | close() | n/a | + +The pattern is the same at every depth: going down pushes the active record, +finishing a child pops its parent back to active, and siblings push that same +parent again. The primary never sits in `_connections` while it is active, and +`_nextPrimaryHost()` starts the next primary with an empty stack. + +`_runExit()` becomes: + +```js +_runExit() { + if (this._runComplete) { + return; + } + + this._progressEnd(); + + if (this._stopping) { + return this._beginStopExit(); + } + + if (!this._gracefulClosing && this.sshObj.hosts && this.sshObj.hosts.length > 0) { + return this._nextHost(); + } + + if (this._connections && this._connections.length > 0) { + this.emit('msg', `${this._hostPrefix()}${this.sshObj.closedMessage}`); + return this._previousHost(); + } + + if (!this._gracefulClosing && this.command === 'exit') { + return this._runCommand('exit'); + } + + return this.close(); +} +``` + +The literal `'exit'` branch stays for a user command or the primary shell. The +only remaining use is the user-issued `exit` that leaves `su` / `sudo -i` and +the final primary shell; it is not how a hop is left. `_previousHost()` closes +the child connection. + +`exitCommands` is removed because its only producer was `_processSSHPrompt()` +pushing `exit` for a nested `ssh` shell. The `su` test in +`test/live/sudo_su.js` already uses a normal command entry, so it is unaffected. +Remove the stale "sudo su has been authenticated and add an extra exit command" +comment in `_commandComplete()` with the `sshToNextHost` guard. + +### Stack operations + +`_nextHost()` no longer pushes the parent config. It hands the child to +`_connectHop()`, and `_connect(parent)` pushes the parent record before the child +becomes active: + +```js +_nextHost() { + if (this._stopping || this._runComplete) { + return; + } + // The outgoing record is still active here; its handlers must go before the + // child's config replaces the aliases. + this._removeListeners(this._activeContext()); + const nextHost = this.sshObj.hosts.shift(); + this.sshObj = nextHost; + this.host = nextHost.server.host; + return this._initiate(this._connectHop); +} +``` + +`_nextHost()` sets `this.sshObj` to the child before `_connectHop()` runs, so +`_pushContext()` must push the `parent` argument it is given, not `this.sshObj`. +The parent record is already authoritative in `this._active`. + +`_previousHost()` closes the active child record, pops its parent, makes the +parent active, and lets `_runExit()` decide what runs next: + +```js +_previousHost() { + if (this._stopping || this._runComplete) { + return; + } + const child = this._activeContext(); + this._closeContext(child, 'previous-host'); // removes listeners + finalizes + this._popContext(); // pops the parent, makes it active, restores the aliases + return this._runExit(); +} +``` + +`_nextPrimaryHost()` closes the active record and every ancestor before it resets +the stack, so a new primary never inherits a hop's socket: + +```js +_nextPrimaryHost(connect) { + // ... + this._closeAllContexts('next-primary-host'); + this._connections = []; + this._stream = {}; + this.sshObj = this._hosts.shift(); + // ... + return this._initiate(connect); // _connect(null) makes the new primary active +} +``` + +`_closeContext()` is idempotent through `context.closed`; `_popContext()` pops +the parent, makes it active, and re-points `this.connection`, `this._stream`, +`this.sshObj`, and `this.host` at it. That is the whole array contract: push the +parent in `_connect` when `parent` is set, close and pop in `_previousHost` / +`_closeAllContexts`, restore aliases on every change. + +What changes is the stack: + +| Current | New | +| --- | --- | +| `_connections` holds parent host configs | `_connections` holds ancestor records: host config **plus** connection, stream, parent, and flags | +| `_connections[0]` is the first ancestor, not the primary | `_connections[0]` is the primary record while a hop is active; at a primary the stack is empty | +| `_nextHost()` pushes the current host | `_connect(parent)` pushes the current active record, then makes the child active | +| `_previousHost()` pops a host | `_previousHost()` closes the active child, then pops its parent | +| `_nextPrimaryHost()` resets `_connections` | `_nextPrimaryHost()` closes the active record and every ancestor, then resets the stack | + +Because the active host is outside the stack, "is there a parent to return to?" +stays `_connections.length > 0`. The traversal order itself does not change: +nested `hosts`, then the parent record, then the primary `exit`, then `close()`. + +Nested host objects are still consumed from `sshObj.hosts` with `shift()`, so +`skipHosts`, `skipPrimaryHosts`, `skipCommands`, `abort`, and `stop` keep their +documented behavior. `_multipleHosts` and the `[host]` message prefix are +unchanged. + +`_loadDefaults` still runs on every host switch, so prompt/filter compilation, +timer overrides, and handler binding follow the active host. `_removeListeners` +still detaches the outgoing host's handlers before the next context becomes +active, but it now takes that host's record so it cannot remove a parent's or a +child's handlers by mistake. `_restoreContext()` reapplies the parent's timer +values, so the instance-level `idleTime` / `dataIdleTime` match the active host +after backing out of a hop. + +## Reuse of standard handlers + +The handlers are reused as they are. `debug`, `verbose`, `msg`, `progress`, +sudo prompts, command responses, stderr capture, and the default error listener +all read the active host and active aliases, which is still the child while the +child is active. No handler needs to know whether the host is primary or nested. + +| Handler / event | Behaviour on a hop | +| --- | --- | +| `onCommandProcessing` | Fires for the active child command, same as a primary command. | +| `onCommandComplete` | Receives the child host's `sshObj` and the same `details` (`rawResponse`, optional `stderr`). | +| `onCommandTimeout` | Same `details` (`attempt`, `maxRetries`, `final`). The idle timer and retries work per command. | +| `onData` | Fires for active child data. Inactive parent stream data is dropped before it reaches `_onData`. | +| `onStderrData` | Fires for the active child stream. `captureStderr` still merges into the child response. | +| `onEnd` | Fires once per visited host, child before parent. | +| `onError` | Host handler runs for the event's record; the default listener keeps its existing close semantics for the active record. | +| `msg` | Same `_systemMsg` path and `[host]` prefix rules. | +| `onKeyboardInteractive` | Bound per connection; the instance event fires with that connection's `finish`. | +| `reconnect` | Follow-up only. Fires with the record's `sshObj` and `{ phase, attempt, maxRetries, delay, expected, reason }`; a reboot reports `expected: true`, a real failure is an `error` with `level: 'Reconnect'`. | +| `progress` | One heartbeat for the active command; `_progressEnd()` runs before a host switch. | + +The one implementation rule is for library code, not users: an event handler +must act on the record it was bound to, not on `this.connection` / +`this._stream`. Those aliases always mean "active record", and a late parent +event is not the active record. + +## `server.ssh` migration + +`server.ssh` is removed with the command path. This table is the user-facing +replacement: + +| `server.ssh` | Replacement | +| --- | --- | +| `identityFile` | Local `privateKey` (contents) or a local `agent`. A path on the jump host no longer works. | +| `forceAddressType` | `forceIPv4: true` or `forceIPv6: true`. | +| `forceProtocolVersion` | Not supported; `ssh2` speaks SSH-2 only. | +| `disablePseudoTTY` | `pty: false` on the host. | +| `forcePseudoTTY` | `pty: true` on the host. | +| `verbose` | `debug: true` on the host, or `ssh2` debug output. | +| `cipherSpec` | `algorithms: { cipher: [...] }`. | +| `macSpec` | `algorithms: { mac: [...] }`. | +| `loginName` | `userName` on `server`. | +| `options` | The equivalent `ssh2` connect option. | +| `escape`, `logFile`, `configFile` | No equivalent; use local `ssh2` options or the local SSH configuration. | +| `StrictHostKeyChecking=no` (implicit) | `ssh2` accepts the key when no verifier is set; set `hostHash` / `hostVerifier` to verify. | + +## Risks and open questions + +1. **Credential location is a breaking change.** The current nested path uses + keys and agents on the jump host. The hop uses the local process. This must + be called out in the release notes and migration guide. +2. **Host-key policy.** The current path disables strict checking. The hop + inherits `ssh2` defaults, which accept any key unless `hostVerifier` is set. + Decision: match the primary contract and stay silent; document that a hop + should set `hostHash` / `hostVerifier` when verification is required. +3. **`forwardOut` restrictions.** A jump host can deny direct-tcpip channels. + The error must be visible and must not leave the parent record inactive. +4. **Source address for `forwardOut`.** Use `127.0.0.1:0` unless a server + rejects it. Make the source values internal constants, not host properties. +5. **Name resolution.** `forwardOut` sends the destination to the jump host, so + names resolve there. Document this; it matches the current `ssh` command + behaviour. +6. **Inactive parent data.** A parent shell can emit a late prompt or keepalive + output while the child runs. Drop it before it reaches the child's `_buffer`. +7. **`keyboard-interactive` on a child.** Already bound per client by + `_bindConnection`; keep the `finish` callback with that connection. No + contract change. +8. **`exitCommands` is removed.** There is no nested shell to leave. Stop and + close now close connections directly. If a caller relied on the runtime + array, call that out in the migration notes. +9. **Versioning.** Removing `server.ssh` and the command path is a major + change. A temporary `hostHop: 'ssh2' | 'ssh'` compatibility switch was + considered and rejected: the requirement is to remove the nested `ssh` path, + not keep it as a baseline. Ship the removal in the major release. +10. **`this.connection` / `this._stream` aliases.** They remain for + compatibility, but they now mean "active record". Document that they are + not stable across a host hop. +11. **Active host outside the stack.** `_connections` holds only ancestors, so + `length > 0` keeps meaning "nested" and `_connections[0]` is the primary only + while nested. The record-shape changes at the sites listed in + [Checks that keep their meaning](#checks-that-keep-their-meaning) must land + before the command path is removed. +12. **Pending `forwardOut` during stop/close.** There is no child stream yet + while the channel is being opened. `_hopFailed` and the stop path must + close the parent record, not assume an active child. +13. **`Security Alert` removal.** There is no shell string to validate, so the + `Security Alert` error type and `shellQuote` / `shellControlChars` are gone. + Host-key acceptance becomes an `ssh2` policy (`hostHash` / `hostVerifier`) + instead of a forced `StrictHostKeyChecking=no`. +14. **Reconnection is out of scope.** The per-hop model makes it possible, but + command replay is unsafe by default. Do not bundle it with the transport + change; see + [Connection loss and reconnection](#connection-loss-and-reconnection). The + intended follow-up is an expected-drop reconnect: a command marked + `breaksConnection` records `expectedClose`, and a bounded + `reconnectRetries` / `reconnectDelay` timer reconnects that record and + resumes at the next command. +15. **Listener ownership is part of the transport change, not cleanup.** A hop + close returns to a live parent, so the hop's handlers must be removed before + the parent's aliases are restored. `_removeListeners(context)` must use the + config that bound the handlers, not `this.sshObj`, or a late ancestor event + removes the wrong host's handlers. Land record-scoped `listeners` and timers + before the first hop is enabled. +16. **Navigation policy must be one rule.** Primary failure advances; hop failure + is contained. Connection failures, `forwardOut` errors, stream errors, and + connection-breaking command timeouts all enter `_failContext`; do not add a + second failure branch in a handler. The navigation matrix in + [Host navigation on failure](#host-navigation-on-failure) is the acceptance + test for that rule. + +## Test plan + +### Unit + +- Replace `test/unit/ssh-connect.test.js` with a hop suite: + - `_connect(null)` makes the primary active with `_connections = []`. + - `_connect(parent)` pushes the active parent record and calls + `parent.connection.forwardOut` with the child host and port. + - The child client receives `sock`. + - A `forwardOut` error emits `error`, leaves the parent active, and continues + the parent path. + - `_nextHost` switches to `_connectHop` and does not queue `exit`. + - `_previousHost` closes the child stream and connection, pops the parent, and + restores the parent aliases. + - A leaf `connection.on('close')` finalizes only the leaf record and restores + the parent. + - An ancestor `connection.on('close')` tears down its descendants first. + - Child `close` does not advance the primary-host queue. + - A primary connect failure advances to the next primary (verified today); a + synchronous `connect()` throw does the same through `_endPrimary`. + - A failed hop does not run its own descendants and does not skip its siblings. + - A connection-breaking command timeout on a hop closes only that hop; the + parent's remaining siblings still run. + - `_failContext` is re-entrant-safe: a close that arrives during descendant + teardown does not unwind twice. + - `_removeListeners(context)` removes only that record's handlers; a parent's + handler still fires after a child is closed, and a child's handler does not + fire against the parent. + - `stop()` closes the active record and its ancestors deepest-first and + finalizes each host once. + - `_finalizeRun` emits one `end` per visited host. + - Inactive parent stream data is dropped. +- Update traversal tests in `test/unit/hosts.test.js` to build records instead + of bare host configs in `_connections`. +- Remove the nested-prompt cases from `test/unit/prompts.test.js` and + `test/unit/prompt-regex.test.js`; keep the primary prompt and sudo cases. +- Remove the command-building and `Security Alert` cases with + `test/unit/ssh-connect.test.js`. +- Update `test/unit/error-handling.test.js` for hop connection errors and for + the active record living outside `_connections`. +- Update `test/unit/api-baseline.test.js` and `test/unit/credentials.test.js` + for the removed `sshAuth` / `sshToNextHost` fields. +- Guard new hop tests with `if (isBaseline()) return;`; the frozen baseline + still has the command path and cannot run them. + +### Reconnect follow-up + +- A command marked `breaksConnection` sets `expectedClose`; a normal completion + clears it. +- Expected close fires `commandComplete` with the partial buffer, + `details.connectionClosed = true`, and no `error`. +- `reconnect` fires with `scheduled`, `attempt`, and `success` phases; the next + command runs only after success. +- Exhaustion emits `error` with `level: 'Reconnect'` and falls back to the close + path. +- `stop()` and `close()` cancel a pending reconnect timer. + +### Live + +Run in this order. The existing suite is the regression gate; a new hop test is +not trusted until the existing tests still pass. + +Live tests and `provision.js` load their build through +`test/utils/module.js`, so the same suite can run against `src` (the default +development target), `lib` (the release build), `baseline` (the frozen +regression fixture), or a repo-relative path: + +```bash +SSH2SHELL_MODULE=src node scripts/run-live.js --all +SSH2SHELL_MODULE=lib node scripts/run-live.js --all +SSH2SHELL_MODULE=baseline node scripts/run-live.js --all +``` + +`scripts/run-live.js` resolves the target once and passes an absolute +`SSH2SHELL_LIVE_MODULE` to the instrumentation preload and the test process, so +both use the same module instance. The runner prints the selected module. + +1. **Existing live suite, unchanged.** Run every test that exercises the + current nested path: + + - `tunnel` + - `chaining` + - `tunnel_3_hop` + - `multiple_primary_hosts` + - `stop_multiple_hosts` + - `graceful_close` + - `transport_drop` + + `tunnel`, `chaining`, and `tunnel_3_hop` are the hop tests: as part of the + change they stop using `server.ssh.identityFile` on the jump host and use the + runner's local `privateKey` for every host. That is the migration proof. + +2. **New hop tests.** Extend `transport_drop` for a leaf hop drop (parent path + continues) and a jump-host drop (descendants tear down). Add a case for a + jump host that denies `forwardOut`, if the test VMs can be configured that + way. + + Two tests already cover the host-array shape: + + - `test/live/host_traversal.js` walks three primaries with nested hosts at + three depths and sibling branches. It asserts the depth-first marker order + and logs `end-order`. It passes on both transports. + - `test/live/host_faults.js` fails a nested leaf, a descendant that never + starts, and a primary. It asserts the containment contract: + + ```text + fault-order:primary1,good-hop,good-sibling,primary2 + error-count:2 + end-order:bad-deep,good-hop,good-sibling,primary1,bad-primary,primary2 + ``` + + The current nested-`ssh` path fails it: `bad-deep` runs on the parent + shell, `good-sibling` is skipped, and only the primary error is reported. + Treat a green `host_faults` run as the acceptance check for + `_failContext` and the primary/hop navigation split. + + Run them through the runner, which allows the expected `ECONNREFUSED` + marker: + + ```bash + node scripts/run-live.js host_traversal host_faults --timeout 180 + ``` + +3. **Clean-VM provisioning.** After the suite is green, rebuild a VM with + `test/provision/provision.js` and rerun the hop tests against it. A fresh VM + has no cached keys, no `~/.ssh/id_ed25519` on the test users, and default + `sshd` settings, so it catches assumptions the existing VMs hide. + + - Remove the `hopKeyUsers` private-key copy from provisioning. It exists only + for the nested `ssh -i` model; `forwardOut` uses the runner's local key. + - Keep the public key in every test user's `authorized_keys`. + - Run `npm run provision -- server1`, then `tunnel`, `chaining`, and + `tunnel_3_hop` with server1 as the jump host. + - Confirm the hop works with no private key on server1 or server2. That is + the real-world proof that credentials are local to the runner. + +### Verification + +- `npm test` — unit and frozen baseline. +- `node scripts/run-live.js --all` — existing suite first. +- Re-run the hop tests after a clean provisioning. +- `git diff --check`. + +## Implementation order + +1. Normalize the host list in the constructor and make `_nextPrimaryHost()` + terminate: validate a single object or non-empty array, `slice()` the caller's + array, and fall back to `_callFinalCallback()` when the queue is empty or the + run is stopping. +2. Turn `_connections` into the ancestor stack: `_pushContext()`, + `_activeContext()`, `_popContext()`, `_popTo()`, `_restoreContext()`, + `_descendantsOf()`, and `_closeContext()`. `_connect(null)` makes the primary + active with an empty stack. `_closeContext` calls `_removeListeners(context)`. +3. Move listener and timer ownership onto the record: `_loadDefaults(context)` + binds into `context.listeners`, `_removeListeners(context)` removes only that + map, and `idleTimer` / `dataReceivedTimer` become record-scoped. Remove the + instance `_boundListeners` dependency for host handlers. +4. Extract `_normalizeServer()`, `_bindConnection()`, `_openShell()`, and + `_openClient()` from `_connect()`; keep the primary path green. +5. Add the hop branch to `_connect(parent)`, add the `_connectHop()` adapter, and + switch `_nextHost()` to it. +6. Add `_failContext()`, `_endPrimary()`, `_hopFailed()`, and `_popTo()`, and route + `connection.on('close')`, the synchronous `connect()` throw, `forwardOut` + errors, stream errors, and connection-breaking command timeouts through them. + Verify the primary-advance and hop-contained cases from the navigation matrix. +7. Update `_previousHost()`, `_nextPrimaryHost()`, `_finalizeHost()`, + `_finalizeRun()`, `_mergeNestedText()`, `_processNotifications()`, and + `_runExit()` for the record stack. The `length > 0` checks keep their meaning. +8. Update `stop()`, `_beginStopExit()`, `_finishStop()`, `close()`, and + `_closeStreamNow()` to close the active record and its ancestors without an + exit-command drain. +9. Remove `_sshConnect()`, `_processSSHPrompt()`, the SSH case in `_onData()`, + the `sshToNextHost` guard in `_commandComplete()`, `sshAuth`, + `sshToNextHost`, `passphrasePrompt`, `exitCommands`, `buildSshCommand()`, + `ssh-command.js`, `shellQuote`, `shellControlChars`, the `Security Alert` + path, and `server.ssh` handling. +10. Update the README, `docs/API-BASELINE.md`, `docs/CLOSE-SEMANTICS.md`, and + `docs/ERROR-HANDLING.md`. +11. Replace the unit suites and run the live suite. + +## Rollback + +- The work is isolated on `next-host-connection`. +- Until the branch merges, `v3.3.0` is the stable boundary. +- If the change ships, tag the major release and record it in + [REFACTORING.md](../REFACTORING.md) as the rollback boundary. diff --git a/lib/ssh2shell.js b/lib/ssh2shell.js index 0c38cc6..caa1b1a 100644 --- a/lib/ssh2shell.js +++ b/lib/ssh2shell.js @@ -4,12 +4,12 @@ // nested host objects. // // The class is the public facade. Pure default application, prompt/filter -// compilation, and nested-SSH command construction live in ./ssh2shell/*. -// Behavior matches the baseline except for the signed-off L5/L6/L6.1 fixes. +// compilation, and credential redaction live in ./ssh2shell/*. Host hops are +// real ssh2 connections opened through the parent connection's forwardOut +// channel; there is no nested `ssh` command. const Stream = require('node:stream'); -const { buildSshCommand } = require('./ssh2shell/ssh-command'); const { applyHostDefaults } = require('./ssh2shell/defaults'); const { compileAsciiFilter, @@ -74,13 +74,13 @@ class SSH2Shell extends Stream { // their `this`. this._connect = this._connect.bind(this); this.connect = this.connect.bind(this); + this._connectHop = this._connectHop.bind(this); this._loadDefaults = this._loadDefaults.bind(this); this._initiate = this._initiate.bind(this); this._removeListeners = this._removeListeners.bind(this); this.close = this.close.bind(this); this.stop = this.stop.bind(this); this._runExit = this._runExit.bind(this); - this._sshConnect = this._sshConnect.bind(this); this._nextPrimaryHost = this._nextPrimaryHost.bind(this); this._nextHost = this._nextHost.bind(this); this._previousHost = this._previousHost.bind(this); @@ -105,7 +105,6 @@ class SSH2Shell extends Stream { this._forceClose = this._forceClose.bind(this); this._closeStreamNow = this._closeStreamNow.bind(this); this._processNotifications = this._processNotifications.bind(this); - this._processSSHPrompt = this._processSSHPrompt.bind(this); this._resetFromSudoError = this._resetFromSudoError.bind(this); this._processSudoPrompt = this._processSudoPrompt.bind(this); this._sanitizeResponse = this._sanitizeResponse.bind(this); @@ -114,17 +113,57 @@ class SSH2Shell extends Stream { this._systemMsg = this._systemMsg.bind(this); this._detachListener = this._detachListener.bind(this); this._boundListener = this._boundListener.bind(this); - this._loadDefaultListeners = this._loadDefaultListeners.bind(this); + this._loadDefaultListeners = this._loadDefaultListeners.bind(this); + this._normalizeServer = this._normalizeServer.bind(this); + this._bindConnection = this._bindConnection.bind(this); + this._openShell = this._openShell.bind(this); + this._openClient = this._openClient.bind(this); + this._pushContext = this._pushContext.bind(this); + this._activeContext = this._activeContext.bind(this); + this._popContext = this._popContext.bind(this); + this._popTo = this._popTo.bind(this); + this._restoreContext = this._restoreContext.bind(this); + this._attachContextListeners = this._attachContextListeners.bind(this); + this._descendantsOf = this._descendantsOf.bind(this); + this._closeContext = this._closeContext.bind(this); + this._closeAllContexts = this._closeAllContexts.bind(this); + this._failContext = this._failContext.bind(this); + this._hopFailed = this._hopFailed.bind(this); + this._endPrimary = this._endPrimary.bind(this); + this._pendingHosts = this._pendingHosts.bind(this); + this._appendPartial = this._appendPartial.bind(this); + this._reportMissingParameters = this._reportMissingParameters.bind(this); + this._bindHostListener = this._bindHostListener.bind(this); + this._streamFor = this._streamFor.bind(this); + this._hasLiveStreamFor = this._hasLiveStreamFor.bind(this); this.ssh2Client = require('ssh2').Client; - this._hosts = typeIsArray(hosts) && hosts.length > 0 ? hosts : [hosts]; + + // A single host config or a non-empty array of host configs. The caller's + // array is copied so shift() cannot drain a config reused by another run. + const list = typeIsArray(hosts) ? hosts : [hosts]; + if ( + list.length === 0 || + list.some((host) => !host || typeof host !== 'object') + ) { + throw new TypeError( + 'ssh2shell: a host config object or a non-empty array of host configs is required' + ); + } + this._hosts = list.slice(); this._primaryHostCount = this._hosts.length; this._multipleHosts = this._primaryHostCount > 1; this._boundListeners = {}; - this.sshObj = {}; + this.sshObj = {}; + // `_connections` holds the ancestors of the active record; `_active` is the + // active record itself. A primary host has an empty stack. this._connections = []; + this._active = null; + this._primaryEnded = false; this.host = "No host"; this._allSessions = ''; this._defaultErrorListener = null; + this._defaultDataListener = null; + this._defaultStderrListener = null; // Progress output is on by default and written to stderr so it never // touches sessionText. The stream and interval are instance state so a test // or a consumer can substitute a TTY-like sink without changing the host @@ -144,7 +183,6 @@ class SSH2Shell extends Stream { this._stopReason = null; this._stopTimer = null; this._commandInFlight = false; - this._commandSawData = false; this._stderrBuffer = ''; this._inCommandComplete = false; this._started = false; @@ -165,9 +203,21 @@ class SSH2Shell extends Stream { console.log(message); }; } - if(!this._boundListeners['msg']){ - this._boundListener('msg', this.msg); - } + // Keep the instance fallback available between hosts. A host-specific `msg` + // handler replaces it while that record is active; _removeListeners + // restores it when the record is left. Check whether the host handler is + // actually attached, not just present in the record: a switch detaches it + // before the child is created. + const active = this._activeContext(); + const hostMsgAttached = Boolean( + active && + active.listeners && + typeof active.listeners.msg === 'function' && + this.listeners('msg').includes(active.listeners.msg) + ); + if (!hostMsgAttached && !this.listeners('msg').includes(this.msg)) { + this.on('msg', this.msg); + } // Break the progress line before any msg listener runs, including a // caller-supplied handler. This keeps a heartbeat from prefixing a message. if (!this._progressMsgListener) { @@ -176,23 +226,23 @@ class SSH2Shell extends Stream { }; this.prependListener('msg', this._progressMsgListener); } - if(!this._boundListeners['data']){ - const data = (data) => { - this._onData(data); - }; - this._boundListener ( 'data', data); + if (!this._defaultDataListener) { + this._defaultDataListener = (data) => { + this._onData(data); + }; + this.on('data', this._defaultDataListener); } - if(!this._boundListeners['stderrData']){ - const stderrData = (data) => { - console.error(data); - }; - this._boundListener ( 'stderrData', stderrData); + if (!this._defaultStderrListener) { + this._defaultStderrListener = (data) => { + console.error(data); + }; + this.on('stderrData', this._defaultStderrListener); } // Track the default error listener separately from host `onError` handlers. // The host cache entry is cleared when a host handler is detached, which // used to make the next host install a second default listener. if (!this._defaultErrorListener) { - this._defaultErrorListener = (err, type, close = false, callback) => { + this._defaultErrorListener = (err, type, close = false, callback, context) => { this._progressEnd(); this._systemMsg('debug', `Class.error: ${err}, ${type}`); @@ -209,46 +259,22 @@ class SSH2Shell extends Stream { callback.call(this, err, type, close); } - // Only close a real shell stream. Before the shell opens, `_stream` is - // the prototype `{}` placeholder, which has no close method. - if (close && this._hasLiveStream()) { - this._stream.close(); + // Only close a real shell stream. Before the shell opens, the active + // stream is the `{}` placeholder, which has no close method. The + // optional context lets an ancestor error close its own stream instead + // of the active child's. + if (close) { + const target = context || this._activeContext(); + const stream = target && target.stream ? target.stream : this._stream; + if (stream && typeof stream.close === 'function') { + stream.close(); + } } }; } if (!this.listeners('error').includes(this._defaultErrorListener)) { this.on('error', this._defaultErrorListener); } - if(!this._boundListeners['keyboard-interactive']){ - // Only install the fallback when the caller has not supplied a handler. - // Two handlers would both call finish(), resetting the handshake. - const hasUserHandler = - this.listeners('keyboard-interactive').length > 0 || - typeof this.sshObj?.onKeyboardInteractive === 'function'; - if ( - this.sshObj && - this.sshObj.server && - this.sshObj.server.tryKeyboard && - !hasUserHandler - ) { - const keyboardInteractive = (name, instructions, instructionsLang, prompts, finish) => { - this._systemMsg('debug',`keyboard-interactive:`); - - this._systemMsg('verbose',`name: ${name}`); - this._systemMsg('verbose',`instructions: ${instructions}`); - - const responses = prompts.map(p => { - this._systemMsg('verbose',`prompts: ${p.prompt}`); - return ''; // Baseline fallback response - }); - this._systemMsg('verbose',`Prompts object: ${responses}`); - // The handshake stalls unless finish() receives the responses as an - // array of strings. - finish(responses); - }; - this._boundListener ( 'keyboard-interactive', keyboardInteractive); - } - } return; } @@ -270,11 +296,382 @@ class SSH2Shell extends Stream { } // A real shell stream exists only after `connection.shell` succeeds. Before - // that, `_stream` is the prototype `{}` placeholder. + // that, the active stream is the `{}` placeholder. _hasLiveStream() { - return Boolean(this._stream && typeof this._stream.close === 'function'); + const context = this._activeContext(); + const stream = context && context.stream ? context.stream : this._stream; + return Boolean(stream && typeof stream.close === 'function'); } - + + // Bind a host handler to this instance and remember it on the record so the + // exact function can be removed when the record is left. Replacing a handler + // for the same event removes the previous record handler first. + _bindHostListener(context, eventName, listener, prepend = false) { + if (!context || typeof listener !== 'function') { + return; + } + + const previous = context.listeners[eventName]; + if (previous === listener && this.listeners(eventName).includes(listener)) { + return; + } + if (typeof previous === 'function' && previous !== listener) { + this.removeListener(eventName, previous); + } + + context.listeners[eventName] = listener; + if (prepend) { + this.prependListener(eventName, listener); + } else { + this.on(eventName, listener); + } + } + + // Re-attaches the handlers a record bound before it was left for a child. + // Host handlers are detached on every switch, so restoring an ancestor has + // to put its own handlers back before it can finish (for example `onEnd`). + _attachContextListeners(context) { + if (!context || !context.listeners) { + return; + } + + for (const [eventName, listener] of Object.entries(context.listeners)) { + if (typeof listener !== 'function') { + continue; + } + if (this.listeners(eventName).includes(listener)) { + continue; + } + if (eventName === 'msg' && this.listeners('msg').includes(this.msg)) { + this.removeListener('msg', this.msg); + } + if (eventName === 'error') { + this.prependListener(eventName, listener); + } else { + this.on(eventName, listener); + } + } + } + + // Returns the stream that belongs to a record. Tests and embedders can set + // `_stream` directly without going through `_openShell`, so the active record + // falls back to the instance alias. + _streamFor(context) { + if (!context) { + return null; + } + if (context.stream) { + return context.stream; + } + return context === this._activeContext() ? this._stream : null; + } + + _hasLiveStreamFor(context) { + const stream = this._streamFor(context); + return Boolean(stream && typeof stream.close === 'function'); + } + + // Copy the server options so the host config is not mutated. `ssh2` uses + // `username` / `passphrase`; the public API keeps the legacy aliases. + _normalizeServer(server) { + const options = Object.assign({}, server || {}); + delete options.ssh; + if (!options.username) { + options.username = options.userName; + } + if (!options.hostHash) { + options.hostHash = options.hashMethod; + } + if (!options.passphrase) { + options.passphrase = options.passPhrase; + } + return options; + } + + // Creates the record for the active host. `parent === null` is a primary; + // otherwise the parent record is pushed onto the ancestor stack first. + _pushContext(host, parent) { + if (parent) { + this._connections.push(parent); + } + + const record = { + host, + parent: parent || null, + connection: null, + stream: null, + isPrimary: !parent, + closed: false, + failing: false, + listeners: {}, + idleTimer: null, + dataReceivedTimer: null, + expectedClose: false, + idleTime: this.idleTime, + dataIdleTime: this.dataIdleTime, + pendingHosts: null, + reportedError: false, + }; + + this._active = record; + this.sshObj = host; + this.host = host.server ? host.server.host : 'No host'; + this.connection = null; + this._stream = {}; + this.idleTimer = null; + this.dataReceivedTimer = null; + return record; + } + + _activeContext() { + return this._active || null; + } + + // Makes a record the active host again and re-points the compatibility + // aliases at it. + _restoreContext(context) { + if (!context) { + return null; + } + this._active = context; + this.connection = context.connection; + this._stream = context.stream || {}; + this.sshObj = context.host; + this.host = context.host && context.host.server + ? context.host.server.host + : this.host; + this.idleTime = context.idleTime; + this.dataIdleTime = context.dataIdleTime; + this.idleTimer = context.idleTimer || null; + this.dataReceivedTimer = context.dataReceivedTimer || null; + + // Compiled prompts/filters and logging flags belong to the active record. + // Parents are restored after a child closes, so put theirs back too. + if (context.standardPrompt) { + this.standardPrompt = context.standardPrompt; + } + if (context.passwordPrompt) { + this.passwordPrompt = context.passwordPrompt; + } + if (context.asciiFilter) { + this.asciiFilter = context.asciiFilter; + } + if (context.textColorFilter) { + this.textColorFilter = context.textColorFilter; + } + if (typeof context.debug === 'boolean') { + this.debug = context.debug; + } + if (typeof context.verbose === 'boolean') { + this.verbose = context.verbose; + } + if (typeof context.progress === 'boolean') { + this.progress = context.progress; + } + if (typeof context.exposeCredentials === 'boolean') { + this.exposeCredentials = context.exposeCredentials; + } + + this._attachContextListeners(context); + return context; + } + + // Pops the top ancestor and makes it active. Used when a hop completes. + _popContext() { + const parent = this._connections.pop(); + if (!parent) { + return null; + } + return this._restoreContext(parent); + } + + // Drops a failed record and everything above it, then restores its parent. + _popTo(context) { + if (!context) { + return null; + } + + const index = this._connections.indexOf(context); + if (index >= 0) { + // Remove the record and its descendants from the stack. + this._connections.length = index; + } + + const parent = this._connections.pop() || context.parent || null; + if (parent) { + return this._restoreContext(parent); + } + this._active = null; + return null; + } + + // Active record plus every record deeper than `context`, deepest-first. + // `context` itself is excluded; callers close it separately. + _descendantsOf(context) { + if (!context) { + return []; + } + + const result = []; + const active = this._activeContext(); + if (active && active !== context && !active.closed) { + result.push(active); + } + + const index = this._connections.indexOf(context); + if (index >= 0) { + for (let position = this._connections.length - 1; position > index; position -= 1) { + const record = this._connections[position]; + if (record && record !== context && !record.closed) { + result.push(record); + } + } + } + return result; + } + + // The only record teardown point. Idempotent through `context.closed`. + _closeContext(context, reason) { + if (!context || context.closed) { + return false; + } + + context.closed = true; + + // Finalize while the record's own handlers are still attached so a host + // `onEnd` observes its `end`. `closed` already makes transport events + // no-ops, so the close below cannot re-enter this path. + this._finalizeHost(context.host, reason); + this._removeListeners(context); + + const stream = this._streamFor(context); + if (stream && typeof stream.close === 'function') { + try { + stream.close(); + } catch (e) { + // The transport may already be gone; teardown continues. + } + } + if (context.connection && typeof context.connection.end === 'function') { + try { + context.connection.end(); + } catch (e) { + // The transport may already be gone; teardown continues. + } + } + + return true; + } + + // Closes the active record and every ancestor, deepest-first. + _closeAllContexts(reason) { + const active = this._activeContext(); + if (active) { + this._closeContext(active, reason); + } + for (let index = this._connections.length - 1; index >= 0; index -= 1) { + this._closeContext(this._connections[index], reason); + } + } + + // The only record failure entry point. Descendants are torn down first, then + // the record itself, and navigation follows the primary/hop split. + _failContext(context, err, reason) { + if (!context || context.closed || context.failing) { + return; + } + context.failing = true; + + for (const descendant of this._descendantsOf(context)) { + this._closeContext(descendant, 'ancestor-failed'); + } + this._closeContext(context, reason); + + if (context.isPrimary) { + return this._endPrimary(reason); + } + + this._popTo(context); + return this._runExit(); + } + + _hopFailed(context, err) { + if (!context || context.closed || context.failing) { + return; + } + context.reportedError = true; + this.emit('error', err, 'Hop', false, null, context); + return this._failContext(context, err, 'hop-failed'); + } + + // Exactly-once primary advance. Callers report the close before calling this; + // `_endPrimary` only navigates. + _endPrimary(reason) { + if (this._primaryEnded || this._runComplete) { + return; + } + this._primaryEnded = true; + this._finalizeRun(reason); + + if (this._stopping || this._closing) { + return this._callFinalCallback(); + } + if (this._hosts.length > 0) { + return this._nextPrimaryHost(this._connect); + } + return this._callFinalCallback(); + } + + // Nested host queues are copied lazily so a config can be reused across runs + // without `shift()` draining the caller's array. + _pendingHosts(context = this._activeContext()) { + const host = context ? context.host : this.sshObj; + if (context && context.pendingHosts) { + return context.pendingHosts; + } + + const list = host && Array.isArray(host.hosts) ? host.hosts : []; + if (!context) { + return list; + } + context.pendingHosts = list.slice(); + return context.pendingHosts; + } + + // Preserves the partial response of a command that never returned a prompt, + // so `end` and the final callback see it even though `_finalizeHost` only + // reads `sessionText`. + _appendPartial(reason, host = this.sshObj) { + if (!this._buffer) { + return ''; + } + const partial = this._buffer; + this._buffer = ''; + if (host) { + host.sessionText += partial; + host.sessionText += `\n[connection closed${reason ? `: ${reason}` : ''}]\n`; + } + return partial; + } + + _reportMissingParameters() { + this.emit( + 'error', + 'Missing connection parameters', + 'Parameters', + false, + function (err, type, close) { + const expose = this.exposeCredentials === true; + this.emit( + 'msg', + expose ? this.sshObj.server : redactCredentials(this.sshObj.server) + ); + this.emit('msg', this.sshObj.commands); + } + ); + return this._stream; + } + // Helper to safely detach listeners using cached references _detachListener(eventName, currentKey) { const cachedHandler = this._boundListeners[eventName]; @@ -439,25 +836,32 @@ class SSH2Shell extends Stream { return null; } - this.idleTimer = setTimeout(() => { + const context = this._activeContext(); + const timer = setTimeout(() => { + // A timer left over from an inactive or closed record must not fire + // against the active host. + if (context && (context.closed || context !== this._activeContext())) { + return; + } + // This timer has fired. Clearing the reference lets the re-arm check // below detect whether _onData already scheduled the next one. - this.idleTimer = null; + if (context) { + context.idleTimer = null; + } + if (this.idleTimer === timer) { + this.idleTimer = null; + } this._progressEnd(); const attempt = (this.sshObj.commandTimeoutAttempt || 0) + 1; this.sshObj.commandTimeoutAttempt = attempt; const maxRetries = toNonNegativeInteger(this.sshObj.commandTimeoutRetries); const final = attempt > maxRetries; - // Distinguish a command that has not produced anything yet from one - // whose output arrived but never returned to a prompt. With no command - // in flight this is not a command-output distinction. - const noOutput = - this.command.length > 0 && this._commandSawData !== true; this._systemMsg( 'debug', - `commandTimeout: ${noOutput ? 'no output received' : 'no prompt detected'} (${attempt}/${maxRetries})` + `commandTimeout: no prompt detected (${attempt}/${maxRetries})` ); this.emit( @@ -466,7 +870,7 @@ class SSH2Shell extends Stream { response, this._stream, this.connection, - { attempt, maxRetries, final, noOutput } + { attempt, maxRetries, final } ); // Re-arm for the next attempt unless this was the last one, the handler @@ -481,7 +885,11 @@ class SSH2Shell extends Stream { } }, this.idleTime); - return this.idleTimer; + if (context) { + context.idleTimer = timer; + } + this.idleTimer = timer; + return timer; } _onData(data) { @@ -492,15 +900,11 @@ class SSH2Shell extends Stream { } this._buffer += data; - // Any data for a command means the timeout is a missed prompt rather than - // a completely silent command. The start timer uses this for `noOutput`. - if (this.command.length > 0) { - this._commandSawData = true; - } - if ( - this.command.length > 0 && - !this.standardPrompt.test(this._sanitizeResponse()) - ) { + const hasCommand = this.command.length > 0; + const promptDetected = + hasCommand && this.standardPrompt.test(this._sanitizeResponse()); + + if (hasCommand && !promptDetected) { this.emit( 'commandProcessing', this.command, @@ -512,10 +916,7 @@ class SSH2Shell extends Stream { clearTimeout(this.idleTimer); } this._scheduleIdleTimeout(this._buffer); - } else if ( - this.command.length < 1 && - !this.standardPrompt.test(this._buffer) - ) { + } else if (!hasCommand && !this.standardPrompt.test(this._buffer)) { this.emit( 'commandProcessing', this.command, @@ -525,12 +926,41 @@ class SSH2Shell extends Stream { ); } + // A detected prompt means the command returned to the shell, so the idle + // timeout no longer applies. Clearing it here (rather than only in the + // settle callback) keeps a short `idleTimeOut` from firing before a longer + // `dataIdleTimeOut` has grouped the response. + if (promptDetected && this.idleTimer) { + clearTimeout(this.idleTimer); + this.idleTimer = null; + const active = this._activeContext(); + if (active) { + active.idleTimer = null; + } + } + // Set a timer to fire when no more data events are received and then // process the buffer based on command and prompt combinations. + const context = this._activeContext(); + if (context && context.dataReceivedTimer) { + clearTimeout(context.dataReceivedTimer); + } if (this.dataReceivedTimer) { clearTimeout(this.dataReceivedTimer); } - return (this.dataReceivedTimer = setTimeout(() => { + const timer = setTimeout(() => { + // A timer left over from an inactive or closed record must not process + // the active host's buffer. + if (context && (context.closed || context !== this._activeContext())) { + return; + } + if (context) { + context.dataReceivedTimer = null; + } + if (this.dataReceivedTimer === timer) { + this.dataReceivedTimer = null; + } + // Clear the command and SSH timeout timer. if (this.idleTimer) { clearTimeout(this.idleTimer); @@ -555,13 +985,6 @@ class SSH2Shell extends Stream { this._systemMsg('debug', `onData: Sudo command data`); return this._processSudoPrompt(); - // Check if ssh authentication needs to be handled. - case this.sshObj.sshToNextHost && - this.command.length > 0 && - this.command.indexOf('ssh ') === 0: - this._systemMsg('debug', `onData: SSH command data`); - - return this._processSSHPrompt(); // Check for standard prompt from a command. case this.command.length > 0 && this.standardPrompt.test(this._sanitizeResponse()): @@ -582,14 +1005,32 @@ class SSH2Shell extends Stream { return this._scheduleIdleTimeout(this._buffer); } - }, this.dataIdleTime)); + }, this.dataIdleTime); + if (context) { + context.dataReceivedTimer = timer; + } + this.dataReceivedTimer = timer; + return timer; } _sanitizeResponse() { - return this._buffer.replace( - this.command.slice(0, this._buffer.length), - '' - ); + const command = this.command; + if (!command) { + return this._buffer; + } + + // The shell echoes the command before running it. A long line can make the + // terminal redraw, and that redraw may put a prompt or control text before + // the final echo. Slice after the last echo so only what the command + // produced is tested for a prompt; a prompt that appears before the echo + // belongs to the previous command and must not complete this one. + const index = this._buffer.lastIndexOf(command); + if (index >= 0) { + return this._buffer.slice(index + command.length); + } + + // The buffer may still hold only part of the echoed command. + return this._buffer.replace(command.slice(0, this._buffer.length), ''); } // Opt-in `commandResponse: 'handled'` payload: the echoed command and the @@ -722,240 +1163,64 @@ class SSH2Shell extends Stream { return result; } - _sshConnect() { - if (this._stopping || this._runComplete) { - return; + _processNotifications() { + // An empty command has nothing to run or report, so skip it and continue + // with the queue instead of leaving the state machine idle. + if (!this.command) { + this._systemMsg('debug', `processNotifications: Empty command, skip`); + return this._nextCommand(); } - const result = buildSshCommand(this.sshObj); - if (result.error) { - this.emit('error', result.error, 'Security Alert', true); - return; + // This is a message for the sessionText like an echo command in bash. + const sessionNote = this.command.match(/^`(.*)`$/); + if (sessionNote) { + this._systemMsg('debug', `processNotifications: sessionText output`); + + if (this._connections.length > 0) { + this.sshObj.sessionText += `${this.host}: Note: ${sessionNote[1]}${this.sshObj.enter}`; + } else { + this.sshObj.sessionText += `Note: ${sessionNote[1]}${this.sshObj.enter}`; + } + this._systemMsg('verbose', sessionNote[1]); + + return this._nextCommand(); } - // A nested connection that authenticates with a key has no prompt to - // answer. Mark it authenticated up front so the first remote shell prompt - // is treated as success instead of a failed connection. Password and - // passphrase auth still start unauthenticated so the first prompt can be - // answered. - const server = this.sshObj.server; - this.sshObj.sshAuth = !server.password && !server.passPhrase; - this.sshObj.sshToNextHost = true; + // This is a message to output in process. + const msgNote = this.command.match(/^msg:(.*)$/); + if (msgNote) { + this._systemMsg('debug', `processNotifications: msg to output`); + + this.emit('msg', `${this._hostPrefix()}Note: ${msgNote[1]}`); + return this._nextCommand(); + } - // Perfectly combined secure connection command string. - this.command = result.command; - this._systemMsg('debug',`SSH command: connect`); - this._progressStart(); + this._systemMsg('debug', `processNotifications: Normal Command to run`); - return this._runCommand(this.command); + return this._checkCommand(); } - - _processSSHPrompt() { - // Not authenticated yet so detect prompts. - const response = this._sanitizeResponse().trim(); - if (this.idleTimer) { - clearTimeout(this.idleTimer); - } - const passwordPrompt = - this.passwordPrompt.test(response) && - !this.sshObj.server.hasOwnProperty('passPhrase'); - const passphrasePrompt = - this.passphrasePrompt.test(response) && - this.sshObj.server.hasOwnProperty('passPhrase'); - const standardPrompt = this.standardPrompt.test(response); - - this._systemMsg('debug', `processSSHPrompt: SSH password handling`); - - this._systemMsg( - 'verbose', - `processSSHPrompt: Password prompt: ${passwordPrompt}, Passphase prompt: ${passphrasePrompt}, Standard prompt: ${standardPrompt}, Password previously sent: ${this.sshObj.sshAuth}` - ); - if (!this.sshObj.sshAuth) { - this._systemMsg( - 'debug', - `processSSHPrompt: First prompt detection` - ); + _commandComplete() { + this._progressEnd(); + this._commandInFlight = false; + const rawResponse = this._buffer; + const response = rawResponse.trim(); + // Captured stderr is consumed once per command. It is empty unless the + // host opts in with `captureStderr: true`. + const capturedStderr = + this.sshObj.captureStderr === true + ? (this._stderrBuffer || '').trim() + : ''; + // `exit` is reported by the shell, not as a command response. It is the + // literal command that leaves `su` / `sudo -i` or the primary shell. + if (this.command !== '' && this.command !== 'exit') { + this._systemMsg('debug',`commandComplete: Raising commandComplete event`); - // Provide password. - if (passwordPrompt) { - this._systemMsg('debug', `processSSHPrompt: send password`); - - this.sshObj.sshAuth = true; - this._buffer = ''; - - return this._runCommand(`${this.sshObj.server.password}`); - } else if (passphrasePrompt) { - this._systemMsg('debug', `processSSHPrompt: send passphrase`); - - this.sshObj.sshAuth = true; - this._buffer = ''; - return this._runCommand(`${this.sshObj.server.passPhrase}`); - } else if (standardPrompt) { - this._systemMsg('debug', `processSSHPrompt: standard prompt: connection failed`); - - this._systemMsg('verbose',`processSSHPrompt: SSH failed: Response: ${response}`); - - this._commandInFlight = false; - this.sshObj.sessionText += `${this.host}: SSH failed: Response: ${response}`; - return this._runExit(); - } else { - this._systemMsg('debug', `processSSHPrompt: No prompt detected`); - - this._systemMsg('verbose',`processSSHPrompt: Response: ${response}`); - - if (this.verbose){ - if (!this.sshObj.server.hasOwnProperty('password')) - { - this._systemMsg( - 'verbose', - `processSSHPrompt: SSH password prompt: ${this.sshObj.passwordPrompt}` - ); - } - if (this.sshObj.server.hasOwnProperty('passPhrase')) - { - this._systemMsg( - 'verbose', - `processSSHPrompt: SSH passphrase prompt: ${this.sshObj.passphrasePrompt}` - ); - } - this._systemMsg( - 'verbose', - `processSSHPrompt: SSH standard prompt: ${this.sshObj.standardPrompt}` - ); - } - - this._commandInFlight = false; - return this._runExit(); - } - } else { - this._systemMsg( - 'debug', - `processSSHPrompt: Post authentication prompt detection` - ); - - if (standardPrompt) { - this._systemMsg('debug', `processSSHPrompt: SSH complete: normal prompt`); - - if (this.sshObj.showBanner) { - this.sshObj.sessionText += `\n ${response}`; - } - this._commandInFlight = false; - this.sshObj.exitCommands.push('exit'); - this.emit('msg', `${this.sshObj.connectedMessage}`); - this.emit('msg', `${this.sshObj.readyMessage}`); - this._systemMsg('debug', `processSSHPrompt: next command`); - - this.sshObj.sshToNextHost = false; - return this._nextCommand(); - } else if (passwordPrompt || passphrasePrompt) { - // Password or passphrase detected a second time after authentication - // indicates failure. - this.emit( - 'msg', - `SSH authentication failed` - ); - this._systemMsg('debug', `processSSHPrompt: Authentication failed`); - - this._systemMsg('verbose',`processSSHPrompt: failed response: ${response}`); - - this._commandInFlight = false; - this.sshObj.sshAuth = false; - let using; - switch (true) { - case passwordPrompt: - using = `SSH password: ${this.sshObj.server.password}`; - break; - case passphrasePrompt: - using = `SSH passphrase: ${this.sshObj.server.passPhrase}`; - break; - } - this.emit( - 'error', - `${this.host}: SSH authentication failed for ${this.sshObj.server.userName}@${this.host}`, - 'SSH multi host authentication failure' - ); - - // No connection so drop back to first host settings if there was one. - if (this._connections.length > 0) { - return this._previousHost(); - } - - return this._runExit(); - } - - // Authenticated, but the response is neither a prompt nor a repeated - // credential prompt. Re-arm the idle timer so a silent nested shell - // cannot leave the session with no timer at all. - this._systemMsg( - 'debug', - `processSSHPrompt: No prompt after authentication, reset timeout` - ); - return this._scheduleIdleTimeout(response); - } - } - - _processNotifications() { - // An empty command has nothing to run or report, so skip it and continue - // with the queue instead of leaving the state machine idle. - if (!this.command) { - this._systemMsg('debug', `processNotifications: Empty command, skip`); - return this._nextCommand(); - } - - // This is a message for the sessionText like an echo command in bash. - const sessionNote = this.command.match(/^`(.*)`$/); - if (sessionNote) { - this._systemMsg('debug', `processNotifications: sessionText output`); - - if (this._connections.length > 0) { - this.sshObj.sessionText += `${this.host}: Note: ${sessionNote[1]}${this.sshObj.enter}`; - } else { - this.sshObj.sessionText += `Note: ${sessionNote[1]}${this.sshObj.enter}`; - } - this._systemMsg('verbose', sessionNote[1]); - - return this._nextCommand(); - } - - // This is a message to output in process. - const msgNote = this.command.match(/^msg:(.*)$/); - if (msgNote) { - this._systemMsg('debug', `processNotifications: msg to output`); - - this.emit('msg', `${this._hostPrefix()}Note: ${msgNote[1]}`); - return this._nextCommand(); - } - - this._systemMsg('debug', `processNotifications: Normal Command to run`); - - return this._checkCommand(); - } - - _commandComplete() { - this._progressEnd(); - this._commandInFlight = false; - const rawResponse = this._buffer; - const response = rawResponse.trim(); - // Captured stderr is consumed once per command. It is empty unless the - // host opts in with `captureStderr: true`. - const capturedStderr = - this.sshObj.captureStderr === true - ? (this._stderrBuffer || '').trim() - : ''; - // Check sudo su has been authenticated and add an extra exit command. - if ( - this.command !== '' && - this.command !== 'exit' && - this.sshObj.sshToNextHost !== true - ) { - this._systemMsg('debug',`commandComplete: Raising commandComplete event`); - - this._systemMsg( - 'verbose', - `commandComplete:\nCommand:\n ${this.command}\nResponse: ${response}` - ); - this.sshObj.sessionText += this._mergeStderr(response, capturedStderr); + this._systemMsg( + 'verbose', + `commandComplete:\nCommand:\n ${this.command}\nResponse: ${response}` + ); + this.sshObj.sessionText += this._mergeStderr(response, capturedStderr); // `commandResponse: 'handled'` opts into a response without the echoed // command or trailing prompt. The raw buffer stays available to handlers @@ -1008,10 +1273,15 @@ class SSH2Shell extends Stream { if (sshObj.skipHosts) { // By design: this clears only the current host's own nested queue. // Sibling nested hosts queued on a parent still run, matching the - // documented skipHosts behavior. + // documented skipHosts behavior. The record's lazy copy is the queue + // `_nextHost()` reads, so clear it too. if (Array.isArray(sshObj.hosts)) { sshObj.hosts.length = 0; } + const active = this._activeContext(); + if (active && Array.isArray(active.pendingHosts)) { + active.pendingHosts.length = 0; + } sshObj.skipHosts = false; } @@ -1103,7 +1373,6 @@ class SSH2Shell extends Stream { if (isCommandWrite) { this.sshObj.commandTimeoutAttempt = 0; this.sshObj.retryCommandTimeout = undefined; - this._commandSawData = false; this._stderrBuffer = ''; } @@ -1114,13 +1383,17 @@ class SSH2Shell extends Stream { this._commandInFlight = Boolean(command); const written = this._stream.write(`${command}${this.sshObj.enter}`); - // Opt-in `commandStartTimeout`: arm the idle timer as soon as the command - // is written so a completely silent command still times out. Incoming data - // clears and re-arms it through the normal `_onData` path. + // Arm the idle timer as soon as a command is written. Incoming data resets + // it through `_onData`, and a detected prompt cancels it. This makes a + // silent command time out like any other command that never returns to the + // prompt. The literal `exit` closes the shell, so it has no prompt to wait + // for, and a graceful close is already bounded by the stop/close timer. if ( written !== false && isCommandWrite && - this.sshObj.commandStartTimeout === true + command.length > 0 && + command !== 'exit' && + !this._gracefulClosing ) { if (this.idleTimer) { clearTimeout(this.idleTimer); @@ -1131,9 +1404,11 @@ class SSH2Shell extends Stream { return written; } - // Merge a nested host's text into the primary host's sessionText exactly - // once. Called before exit commands so the text survives even if leaving the - // nested shell times out. + // Merge a nested host's text into its immediate parent's sessionText exactly + // once. Merging one level at a time keeps the text in traversal order: a + // child finalizes before its parent, so the deepest text travels up the + // chain and lands after the parent's own output. The primary host then + // carries the whole subtree. _mergeNestedText(host = this.sshObj) { if (!host || !host.server || !this._connections || this._connections.length === 0) { return false; @@ -1142,13 +1417,34 @@ class SSH2Shell extends Stream { return false; } - const root = this._connections[0]; - if (!root || root === host) { + const active = this._activeContext(); + let parentRecord = null; + + if (active && active.host === host) { + // The active host sits outside the stack; its parent is the last record. + parentRecord = this._connections[this._connections.length - 1]; + } else { + // A host being finalized from the stack has its parent one level up. + const index = this._connections.findIndex( + (record) => (record && record.host ? record.host : record) === host + ); + if (index > 0) { + parentRecord = this._connections[index - 1]; + } else if (index === -1) { + // Legacy callers can put bare host configs on the stack without a + // record for the active host. The last ancestor is still the parent. + parentRecord = this._connections[this._connections.length - 1]; + } + } + + const parent = + parentRecord && parentRecord.host ? parentRecord.host : parentRecord; + if (!parent || parent === host) { return false; } this._mergedHosts.add(host); - root.sessionText += `\n${host.server.host}: ${host.sessionText || ''}`; + parent.sessionText += `\n${host.server.host}: ${host.sessionText || ''}`; return true; } @@ -1163,10 +1459,12 @@ class SSH2Shell extends Stream { } this._finalizedHosts.add(host); - const isPrimary = - !this._connections || - this._connections.length === 0 || - host === this._connections[0]; + // The active host is outside the stack, so the primary is the first + // ancestor's host (or the active host when the stack is empty). Records + // built by older tests may still hold a bare host config. + const rootRecord = this._connections ? this._connections[0] : null; + const root = rootRecord && rootRecord.host ? rootRecord.host : rootRecord; + const isPrimary = !root || host === root; if (!isPrimary) { this._mergeNestedText(host); @@ -1194,12 +1492,16 @@ class SSH2Shell extends Stream { // complete session text. _finalizeRun(reason = null) { const hosts = []; - if (this.sshObj && this.sshObj.server) { + const active = this._activeContext(); + if (active && active.host && active.host.server) { + hosts.push(active.host); + } else if (this.sshObj && this.sshObj.server) { hosts.push(this.sshObj); } if (this._connections) { for (let index = this._connections.length - 1; index >= 0; index -= 1) { - const host = this._connections[index]; + const record = this._connections[index]; + const host = record && record.host ? record.host : record; if (host && host.server) { hosts.push(host); } @@ -1216,27 +1518,31 @@ class SSH2Shell extends Stream { return; } - this._systemMsg('debug',`previousHost: raise end event on current connection: ${this.host}`); - - this._finalizeHost(this.sshObj, 'previous-host'); + const child = this._activeContext(); this._systemMsg( - 'debug', - `previousHost: Check for previous connections and reload its configuration if one exists` + 'debug', + `previousHost: close child connection: ${this.host}` ); - // Remove the outgoing host's handlers before restoring the previous host. - // Without this, a stale commandComplete (or similar) handler keeps firing - // against the new current host and duplicates session text. - this._removeListeners(); - - if (this._connections.length > 0) { - this.sshObj = this._connections.pop(); - this.host = this.sshObj.server.host; - // Reapply the previous host's timer config over the base restored by - // _removeListeners. - this._applyHostTimerValues(); - this._systemMsg('debug',`previousHost: previous host loaded: ${this.host} `); - + if (child) { + // Closing the child removes its handlers and finalizes it exactly once. + this._closeContext(child, 'previous-host'); + this._popContext(); + this._systemMsg('debug', `previousHost: previous host loaded: ${this.host}`); + } else if (this._connections.length > 0) { + // Fallback for callers that built the stack manually. The record form is + // the supported one. + this._finalizeHost(this.sshObj, 'previous-host'); + this._removeListeners(); + const parent = this._connections.pop(); + const parentHost = parent && parent.host ? parent.host : parent; + if (parent && parent.host) { + this._restoreContext(parent); + } else if (parentHost) { + this.sshObj = parentHost; + this.host = parentHost.server.host; + } + this._systemMsg('debug', `previousHost: previous host loaded: ${this.host}`); } return this._runExit(); @@ -1247,52 +1553,67 @@ class SSH2Shell extends Stream { return; } - this._removeListeners(); - const nextHost = this.sshObj.hosts.shift(); + // The outgoing record is still active; its handlers must go before the + // child's config replaces the aliases. `pendingHosts` is the record's own + // copy, so the caller's nested array is never consumed. + const parent = this._activeContext(); + if (!parent) { + // Without an active record there is no connection to hop from. Terminate + // instead of recursing through `_runExit()`. + return this._callFinalCallback(); + } + + this._removeListeners(parent); + const pending = this._pendingHosts(parent); + const nextHost = pending.shift(); + if (!nextHost) { + return this._runExit(); + } + this._systemMsg( - 'debug', - `nextHost: load ${nextHost.server.host} config, prepare and start SSH connection` + 'debug', + `nextHost: hop to ${nextHost.server.host} through ${this.host}` ); - this._connections.push(this.sshObj); this.sshObj = nextHost; this.host = nextHost.server.host; - return this._initiate(this._sshConnect); + return this._initiate(this._connectHop); } _nextPrimaryHost(connect) { if (this._stopping || this._runComplete) { - return; + return this._callFinalCallback(); + } + if (this._hosts.length === 0) { + return this._callFinalCallback(); } - if (this._hosts.length > 0) { - this._systemMsg('debug', `nextPrimaryHost: load next host for ssh2 connection`); - - // Check this is not loading the first primary host before removing - // listeners. - if (this.sshObj.server) { - this._systemMsg('debug', `nextPrimaryHost: end current host ${this.host}`); - - this._finalizeHost(this.sshObj, 'next-primary-host'); - } - - this._systemMsg('debug',`nextPrimaryHost: Load next primary host: ${this.host}`); - - this._removeListeners(); - // A new primary host gets a new connection, so drop the previous host's - // stream reference and nested stack. Otherwise an early error could close - // the old stream or the new host could be mistaken for a nested one. - this._stream = {}; - this._connections = []; - this.sshObj = this._hosts.shift(); - this.host = this.sshObj.server.host; - this._primaryhostSessionText = `${this.host}: `; - this._closing = false; - this._gracefulClosing = false; - this._commandInFlight = false; - return this._initiate(connect); + this._systemMsg('debug', `nextPrimaryHost: load next host for ssh2 connection`); + + // Close the current primary and every active hop before resetting the + // stack, so a new primary never inherits a hop's socket. + if (this._activeContext()) { + this._closeAllContexts('next-primary-host'); + } else if (this.sshObj && this.sshObj.server) { + this._finalizeHost(this.sshObj, 'next-primary-host'); } + + this._progressEnd(); + this._stream = {}; + this.connection = null; + this._connections = []; + this._active = null; + this._primaryEnded = false; + this._buffer = ''; + this._stderrBuffer = ''; + this.sshObj = this._hosts.shift(); + this.host = this.sshObj.server.host; + this._primaryhostSessionText = `${this.host}: `; + this._closing = false; + this._gracefulClosing = false; + this._commandInFlight = false; + return this._initiate(connect); } _runExit() { @@ -1306,37 +1627,37 @@ class SSH2Shell extends Stream { if (this._stopping) { return this._beginStopExit(); } - - // Run the exit commands loaded when a nested ssh shell opens. Merge the - // nested text first so it is captured even if the exit command times out. - if (this.sshObj.exitCommands && this.sshObj.exitCommands.length > 0) { - this._systemMsg( - 'verbose', - `runExit: Queued exit commands: ${this.sshObj.exitCommands.length}` - ); - - this._mergeNestedText(); - this.command = this.sshObj.exitCommands.pop(); - return this._runCommand(this.command); - } else if (!this._gracefulClosing && this.sshObj.hosts && this.sshObj.hosts.length > 0) { - // More hosts to connect to so process the next one. + + // Nested hosts only exist on an active record. A bare `sshObj.hosts` array + // without a record has no connection to hop from, so it must not drive + // navigation here. + const active = this._activeContext(); + const pending = active ? this._pendingHosts(active) : []; + + if (!this._gracefulClosing && pending.length > 0) { + // More nested hosts to connect to so process the next one. this._systemMsg('debug',`runExit: Load next host`); - + return this._nextHost(); - } else if (this._connections && this._connections.length > 0) { + } + + if (this._connections && this._connections.length > 0) { // Leaving last host so load previous host. this._systemMsg('debug',`runExit: load previous host`); - + this.emit('msg', `${this._hostPrefix()}${this.sshObj.closedMessage}`); return this._previousHost(); - } else if (!this._gracefulClosing && this.command === 'exit') { + } + + if (!this._gracefulClosing && this.command === 'exit') { + // The literal `exit` leaves `su` / `sudo -i` or the primary shell. A hop + // is left by closing its connection, not by an exit command. this._systemMsg('debug',`runExit: run exit command`); - + return this._runCommand('exit'); - // Nothing more to do so end the stream with last exit. - } else { - return this.close(); } + + return this.close(); } // --------------------------------------------------------------------------- @@ -1364,23 +1685,29 @@ class SSH2Shell extends Stream { } // Clear every command and host queue, including the private primary-host - // queue and nested queues queued on parents. The library's exit commands are - // deliberately kept so a nested shell can be left cleanly. - const clearQueues = (host) => { - if (!host) { + // queue and the nested queues held by the active record and its ancestors. + const clearRecord = (record) => { + if (!record) { return; } + const host = record.host || record; if (Array.isArray(host.commands)) { host.commands.length = 0; } if (Array.isArray(host.hosts)) { host.hosts.length = 0; } + if (Array.isArray(record.pendingHosts)) { + record.pendingHosts.length = 0; + } }; - clearQueues(this.sshObj); + clearRecord(this._activeContext()); + if (!this._activeContext() && this.sshObj) { + clearRecord({ host: this.sshObj }); + } if (Array.isArray(this._connections)) { - for (const host of this._connections) { - clearQueues(host); + for (const record of this._connections) { + clearRecord(record); } } this._hosts.length = 0; @@ -1390,7 +1717,7 @@ class SSH2Shell extends Stream { if (this._commandInFlight) { // Interrupt the running command and wait for the prompt or the idle - // timeout before running the exit commands. + // timeout before closing the records. this._armStopTimer(); if (this._hasLiveStream()) { this._stream.write('\x03'); @@ -1414,23 +1741,11 @@ class SSH2Shell extends Stream { return; } - if (!this._hasLiveStream()) { - return this._finishStop(); - } - - const exitCommands = this.sshObj && Array.isArray(this.sshObj.exitCommands) - ? this.sshObj.exitCommands - : []; - - if (exitCommands.length > 0) { + // A command that is still in flight gets the stop timer and the Ctrl-C + // already sent by stop(). The prompt (or the timer) reaches _finishStop(). + if (this._commandInFlight && this._hasLiveStream()) { this._armStopTimer(); - this.command = exitCommands.pop(); - this._systemMsg('debug', `stop: run queued exit command`); - const written = this._runCommand(this.command); - if (written === false) { - return this._finishStop(); - } - return written; + return; } return this._finishStop(); @@ -1446,17 +1761,13 @@ class SSH2Shell extends Stream { this._commandInFlight = false; this._closing = true; this._runComplete = true; - this._finalizeRun(this._stopReason || 'stop'); - - if (this._hasLiveStream()) { - this._stream.close(); - return this._allSessions; - } - if (this.connection && typeof this.connection.end === 'function') { - this.connection.end(); - return this._allSessions; - } + // Closing every record finalizes each host once, deepest-first. + this._closeAllContexts(this._stopReason || 'stop'); + this._active = null; + this._connections = []; + this._stream = {}; + this.connection = null; return this._callFinalCallback(); } @@ -1485,25 +1796,32 @@ class SSH2Shell extends Stream { } } - // Graceful close runs queued exit commands and backs out of nested shells - // before closing. Remaining primary hosts still run, matching close()'s - // compatibility contract. + // Graceful close drops queued commands and nested hosts, then backs out of + // the active records before closing. Remaining primary hosts still run, + // matching close()'s compatibility contract. _prepareGracefulClose() { - const clearQueues = (host) => { - if (!host) { + const clearRecord = (record) => { + if (!record) { return; } + const host = record.host || record; if (Array.isArray(host.commands)) { host.commands.length = 0; } if (Array.isArray(host.hosts)) { host.hosts.length = 0; } + if (Array.isArray(record.pendingHosts)) { + record.pendingHosts.length = 0; + } }; - clearQueues(this.sshObj); + clearRecord(this._activeContext()); + if (!this._activeContext() && this.sshObj) { + clearRecord({ host: this.sshObj }); + } if (Array.isArray(this._connections)) { - for (const host of this._connections) { - clearQueues(host); + for (const record of this._connections) { + clearRecord(record); } } } @@ -1539,20 +1857,25 @@ class SSH2Shell extends Stream { this._closing = true; this._progressEnd(); this._systemMsg('debug',`Stream: close`); - this._finalizeRun('close'); - if (this._hasLiveStream()) { - const result = this._stream.close(); - // Unit tests and embedders can supply a stream without a client. Without - // a connection no `close` event will arrive, so finish here. - if (!this.connection) { - this._callFinalCallback(); - } - return result; - } - if (this.connection && typeof this.connection.end === 'function') { - return this.connection.end(); + // Close the active record and every ancestor. `_closeContext` finalizes + // each host once and closes its stream/connection. + this._closeAllContexts('close'); + this._active = null; + this._connections = []; + this._stream = {}; + this.connection = null; + + // A plain close() still honours the primary-host contract: remaining + // primaries run. Advance directly because the records are already closed + // and their close events are suppressed. + if (!this._stopping && !this._runComplete && this._hosts.length > 0) { + this._closing = false; + this._primaryEnded = false; + return this.emit('newPrimaryHost', this._nextPrimaryHost(this._connect)); } + + this._runComplete = true; return this._callFinalCallback(); } @@ -1607,7 +1930,6 @@ class SSH2Shell extends Stream { this._stopping = false; this._stopReason = null; this._commandInFlight = false; - this._commandSawData = false; this._stderrBuffer = ''; this._inCommandComplete = false; this._runComplete = false; @@ -1616,69 +1938,62 @@ class SSH2Shell extends Stream { this._finalizedHosts = new Set(); this._mergedHosts = new Set(); this._connections = []; + this._active = null; + this._primaryEnded = false; this._stream = {}; + this.connection = null; + this.sshObj = {}; + this.host = 'No host'; + this._buffer = ''; this._allSessions = ''; this._primaryhostSessionText = ''; } - _removeListeners() { - this._progressEnd(); - this._systemMsg('debug',`removeListeners: removing event listeners linked to the host`); - - if ( - typeof this.sshObj.onKeyboardInteractive === 'function' || - typeof this._boundListeners['keyboard-interactive'] === 'function' - ){ - this._detachListener('keyboard-interactive', 'onKeyboardInteractive'); - } - if (typeof this.sshObj.onStderrData === 'function'){ - this._detachListener('stderrData', 'onStderrData'); - } - if (typeof this.sshObj.onData === 'function'){ - this._detachListener('data', 'onData'); - } - if (typeof this.sshObj.onEnd === 'function'){ - this._detachListener('end', 'onEnd'); - } - if (typeof this.sshObj.onCommandProcessing === 'function'){ - this._detachListener('commandProcessing', 'onCommandProcessing'); - } - if (typeof this.sshObj.onCommandComplete === 'function'){ - this._detachListener('commandComplete', 'onCommandComplete'); + // Removes only the handlers a record bound, plus that record's timers. Host + // handlers are owned by the record, never by `this.sshObj`: an ancestor event + // can arrive while a child is active. Instance defaults stay attached. + _removeListeners(context = this._activeContext()) { + if (!context) { + return; } - if (typeof this.sshObj.onCommandTimeout === 'function'){ - this._detachListener('commandTimeout', 'onCommandTimeout'); + + this._systemMsg( + 'debug', + `removeListeners: removing event listeners linked to ${context.host ? context.host.server.host : 'host'}` + ); + + if (context.listeners) { + // Keep the map: restoring an ancestor after a hop needs the exact + // handlers that host bound. Only the emitter attachment is removed. + for (const [eventName, listener] of Object.entries(context.listeners)) { + if (typeof listener === 'function') { + this.removeListener(eventName, listener); + } + } } - if (typeof this.sshObj.onError === 'function'){ - this._detachListener('error', 'onError'); + + if (context.idleTimer) { + clearTimeout(context.idleTimer); + context.idleTimer = null; } - if ( - typeof this.sshObj.msg === 'function' || - typeof this._boundListeners['msg'] === 'function' - ){ - this._detachListener('msg', 'msg'); - } - // Keep a message sink for _systemMsg between leaving this host and loading - // the next one. _loadDefaults swaps in a host handler when one exists. - this._boundListener('msg', this.msg); - - if (this.idleTimer) { - clearTimeout(this.idleTimer); + if (context.dataReceivedTimer) { + clearTimeout(context.dataReceivedTimer); + context.dataReceivedTimer = null; } - if (this.dataReceivedTimer) { - clearTimeout(this.dataReceivedTimer); + if (context === this._activeContext()) { + if (this.idleTimer) { + clearTimeout(this.idleTimer); + this.idleTimer = null; + } + if (this.dataReceivedTimer) { + clearTimeout(this.dataReceivedTimer); + this.dataReceivedTimer = null; + } } - // Roll timer values back to the instance base so one host's override does - // not leak into the next host. - if (this._baseIdleTime !== undefined) { - this.idleTime = this._baseIdleTime; - } - if (this._baseDataIdleTime !== undefined) { - this.dataIdleTime = this._baseDataIdleTime; - } - - return; + // Keep a message sink available between hosts. `_loadDefaultListeners` + // restores the fallback only when the active record has no host `msg`. + this._loadDefaultListeners(); } _initiate(action) { @@ -1686,8 +2001,6 @@ class SSH2Shell extends Stream { return; } - this._loadDefaults(); - if (typeof action === 'function') { return action(); } @@ -1708,11 +2021,11 @@ class SSH2Shell extends Stream { // Applies a host's timer config only when it supplies a valid value, so an // instance value is not overwritten by the defaults. - _applyHostTimerValues() { + _applyHostTimerValues(host = this.sshObj) { // `idleTimeOut` is the documented key; `idleTime` is a legacy alias. const idleTimeOut = - toPositiveNumber(this.sshObj.idleTimeOut) || - toPositiveNumber(this.sshObj.idleTime); + toPositiveNumber(host.idleTimeOut) || + toPositiveNumber(host.idleTime); if (idleTimeOut > 0) { this.idleTime = idleTimeOut; } @@ -1720,112 +2033,135 @@ class SSH2Shell extends Stream { // Public key is `dataIdleTimeOut` (README). Keep the undocumented // `dataIdleTime` as a fallback for existing callers. const dataIdleTimeOut = - toPositiveNumber(this.sshObj.dataIdleTimeOut) || - toPositiveNumber(this.sshObj.dataIdleTime); + toPositiveNumber(host.dataIdleTimeOut) || + toPositiveNumber(host.dataIdleTime); if (dataIdleTimeOut > 0) { this.dataIdleTime = dataIdleTimeOut; } } - _loadDefaults() { + // Loads a host's defaults and binds its handlers to the record that owns + // them. When no record is supplied, the active one is used; direct calls + // before a connection (unit tests and embedders) create the primary record. + _loadDefaults(context = null) { + let record = context || this._activeContext(); + // A direct call (tests and embedders) can set `sshObj` without creating a + // record. Treat that as a new primary config rather than reusing the + // previous record's host. + if (!record || (!context && record.host !== this.sshObj)) { + record = this._pushContext(this.sshObj, null); + } + + const host = record.host || this.sshObj; + this.sshObj = host; + this.host = host.server ? host.server.host : 'No host'; + this._progressEnd(); this.command = ''; this._buffer = ''; - this._commandSawData = false; this._stderrBuffer = ''; - this.debug = this.sshObj.debug ?? false; - this.verbose = this.sshObj.verbose ?? false; - this.progress = this.sshObj.progress !== false; - this.exposeCredentials = this.sshObj.exposeCredentials ?? false; - this.host = this.sshObj.server.host; + this.debug = host.debug ?? false; + this.verbose = host.verbose ?? false; + this.progress = host.progress !== false; + this.exposeCredentials = host.exposeCredentials ?? false; // Remember that this session uses nested hosts even after the queue has // been consumed, so message prefixes stay consistent. - if (Array.isArray(this.sshObj.hosts) && this.sshObj.hosts.length > 0) { + if (Array.isArray(host.hosts) && host.hosts.length > 0) { this._multipleHosts = true; } // Support the legacy { send: fn } message handler shape. - if ( - this.sshObj.msg && - this.sshObj.msg.send && - typeof this.sshObj.msg.send === 'function' - ) { - this.sshObj.msg = this.sshObj.msg.send; + if (host.msg && host.msg.send && typeof host.msg.send === 'function') { + host.msg = host.msg.send; } - if (typeof this._boundListeners['msg'] === 'function') { - this._detachListener('msg', 'msg'); - } - if (typeof this.sshObj.msg === 'function') { - this._boundListener('msg', this.sshObj.msg); - } else { - this._boundListener('msg', this.msg); + // A host `msg` handler replaces the instance fallback while the record is + // active. `_removeListeners` restores the fallback when the record leaves. + const previousMsg = record.listeners.msg; + if (previousMsg && previousMsg !== host.msg) { + this.removeListener('msg', previousMsg); + delete record.listeners.msg; + } + if (typeof host.msg === 'function') { + if (this.listeners('msg').includes(this.msg)) { + this.removeListener('msg', this.msg); + } + this._bindHostListener(record, 'msg', host.msg); + } else if (!this.listeners('msg').includes(this.msg)) { + this.on('msg', this.msg); } this._systemMsg('debug',`Load Defaults`); - - applyHostDefaults(this.sshObj); - this._captureBaseTimerValues(); - this._applyHostTimerValues(); + applyHostDefaults(host); - // Keep the instance base when no host value was supplied; only repair an - // invalid current value. - if (!(toPositiveNumber(this.idleTime) > 0)) { - this.idleTime = this._baseIdleTime; - } - if (!(toPositiveNumber(this.dataIdleTime) > 0)) { - this.dataIdleTime = this._baseDataIdleTime; - } + this._captureBaseTimerValues(); + // Every host starts from the instance base; only a valid host value + // overrides it. This keeps one host's timers from leaking into the next. + this.idleTime = this._baseIdleTime; + this.dataIdleTime = this._baseDataIdleTime; + this._applyHostTimerValues(host); + record.idleTime = this.idleTime; + record.dataIdleTime = this.dataIdleTime; // Compile ASCII Filter with Safe Fallback. These compiled regexes are // internal state, not public config: recompile from the current host on // every load so a later host with different filters/prompts is honoured. - const ascii = compileAsciiFilter(this.sshObj.asciiFilter); + const ascii = compileAsciiFilter(host.asciiFilter); this.asciiFilter = ascii.filter; if (ascii.usedFallback && this.debug) { this._systemMsg( 'debug', - `loadDefaults: AsciiFilter: incorrect regular expression reverting to default: ${this.sshObj.asciiFilter}` + `loadDefaults: AsciiFilter: incorrect regular expression reverting to default: ${host.asciiFilter}` ); } // Compile Text Color Filter with Safe Fallback. - const color = compileTextColorFilter(this.sshObj.textColorFilter); + const color = compileTextColorFilter(host.textColorFilter); this.textColorFilter = color.filter; if (color.usedFallback && this.debug) { this._systemMsg( 'debug', - `loadDefaults: TextColorFilter: incorrect regular expression reverting to default: ${this.sshObj.textColorFilter}` + `loadDefaults: TextColorFilter: incorrect regular expression reverting to default: ${host.textColorFilter}` ); } // Prompts: fully sanitized at runtime via escapeRegex (never need // fallbacks because they are cast as pure literals). - const prompts = compilePrompts(this.sshObj); + const prompts = compilePrompts(host); this.passwordPrompt = prompts.passwordPrompt; - this.passphrasePrompt = prompts.passphrasePrompt; this.standardPrompt = prompts.standardPrompt; if (prompts.standardPromptFallback) { this._systemMsg( 'debug', - `loadDefaults: StandardPromptRegex: incorrect regular expression reverting to standardPrompt: ${this.sshObj.standardPromptRegex}` + `loadDefaults: StandardPromptRegex: incorrect regular expression reverting to standardPrompt: ${host.standardPromptRegex}` ); } + // Store the compiled state on the record so restoring an ancestor after a + // child closes does not keep the child's prompts or filters. + record.standardPrompt = this.standardPrompt; + record.passwordPrompt = this.passwordPrompt; + record.asciiFilter = this.asciiFilter; + record.textColorFilter = this.textColorFilter; + record.debug = this.debug; + record.verbose = this.verbose; + record.progress = this.progress; + record.exposeCredentials = this.exposeCredentials; + // Listener defaults for command processing. - this.sshObj.onCommandProcessing = - this.sshObj.onCommandProcessing ?? + host.onCommandProcessing = + host.onCommandProcessing ?? ((command, response, sshObj, stream) => {}); - - this.sshObj.onCommandComplete = - this.sshObj.onCommandComplete ?? + + host.onCommandComplete = + host.onCommandComplete ?? ((command, response, sshObj) => { this._systemMsg('debug', `onCommandComplete:`); }); - this.sshObj.onCommandTimeout = - this.sshObj.onCommandTimeout ?? + host.onCommandTimeout = + host.onCommandTimeout ?? ((command, response, stream, connection, details) => { // With `commandTimeoutRetries` configured, only the final attempt // closes the run. The library re-arms the timer for earlier attempts. @@ -1839,7 +2175,7 @@ class SSH2Shell extends Stream { response = response.replace(this.command, ''); this._systemMsg('debug', `loadDefaults: Class.commandTimeout`); - + this._systemMsg('verbose',`loadDefaults: Timeout command: ${command} response: ${response}`); this.emit( @@ -1854,36 +2190,67 @@ class SSH2Shell extends Stream { ); }); - // Explicitly cache references right before binding them to the event emitter - if (typeof this.sshObj.onKeyboardInteractive === 'function') { - this._boundListener('keyboard-interactive', this.sshObj.onKeyboardInteractive); + // Bind the host handlers into the record. They are removed with the same + // record on a host switch, failure, or teardown. + if (typeof host.onKeyboardInteractive === 'function') { + this._bindHostListener(record, 'keyboard-interactive', host.onKeyboardInteractive); } - if (typeof this.sshObj.onError === 'function') { + if (typeof host.onError === 'function') { // Host handlers run before the default listener so they can observe the // error before the default listener closes the stream. - this._boundListener('error', this.sshObj.onError, true); + this._bindHostListener(record, 'error', host.onError, true); } - if (typeof this.sshObj.onData === 'function') { - this._boundListener('data', this.sshObj.onData); + if (typeof host.onData === 'function') { + this._bindHostListener(record, 'data', host.onData); } - if (typeof this.sshObj.onStderrData === 'function') { - this._boundListener('stderrData', this.sshObj.onStderrData); + if (typeof host.onStderrData === 'function') { + this._bindHostListener(record, 'stderrData', host.onStderrData); } - if (typeof this.sshObj.onEnd === 'function') { - this._boundListener('end', this.sshObj.onEnd); + if (typeof host.onEnd === 'function') { + this._bindHostListener(record, 'end', host.onEnd); } - - this._boundListener('commandProcessing', this.sshObj.onCommandProcessing); - this._boundListener('commandComplete', this.sshObj.onCommandComplete); + this._bindHostListener(record, 'commandProcessing', host.onCommandProcessing); + this._bindHostListener(record, 'commandComplete', host.onCommandComplete); + this._bindHostListener(record, 'commandTimeout', host.onCommandTimeout); - this._boundListener('commandTimeout', this.sshObj.onCommandTimeout); + // The tryKeyboard fallback belongs to the record that set it. It is only + // installed when no host or instance handler exists, because two handlers + // would both call finish() and reset the handshake. + if ( + host.server && + host.server.tryKeyboard && + typeof host.onKeyboardInteractive !== 'function' && + this.listeners('keyboard-interactive').length === 0 + ) { + const keyboardInteractive = ( + name, + instructions, + instructionsLang, + prompts, + finish + ) => { + this._systemMsg('debug', `keyboard-interactive:`); + + this._systemMsg('verbose', `name: ${name}`); + this._systemMsg('verbose', `instructions: ${instructions}`); + + const responses = prompts.map((prompt) => { + this._systemMsg('verbose', `prompts: ${prompt.prompt}`); + return ''; // Baseline fallback response + }); + this._systemMsg('verbose', `Prompts object: ${responses}`); + // The handshake stalls unless finish() receives an array of strings. + finish(responses); + }; + this._bindHostListener(record, 'keyboard-interactive', keyboardInteractive); + } this._loadDefaultListeners(); this._systemMsg('debug',`loadDefaults: Host loaded`); - - this._systemMsg('verbose', 'loadDefaults: Config:', this.sshObj); + + this._systemMsg('verbose', 'loadDefaults: Config:', host); } connect(callback) { @@ -1897,18 +2264,144 @@ class SSH2Shell extends Stream { return this.emit('newPrimaryHost', this._nextPrimaryHost(this._connect)); } - _connect() { + // The only connection method. `parent === null` opens a primary host; a + // parent record opens a hop through `parent.connection.forwardOut`. Both + // paths share `_openClient()` and `_openShell()`, so there is one command + // engine, one set of handlers, and one close policy. + _connect(parent = null) { if (this._stopping || this._runComplete) { - return; + return this._stream; } - this.connection = new this.ssh2Client(); + const host = this.sshObj; + const context = this._pushContext(host, parent || null); + const server = this._normalizeServer(host.server); + // Defaults belong to the record, so they are loaded after the record + // exists and before the client is opened. + this._loadDefaults(context); + + if (!host.server) { + if (context.isPrimary) { + return this._reportMissingParameters(); + } + this._hopFailed(context, new Error('Missing connection parameters')); + return this._stream; + } - this.connection.on( + if (context.isPrimary) { + this._systemMsg('debug', `Connect: primary`); + return this._openClient(context, server); + } + + const parentConnection = parent && parent.connection; + if (!parentConnection || typeof parentConnection.forwardOut !== 'function') { + this._hopFailed(context, new Error('No parent connection for host hop')); + return this._stream; + } + this._systemMsg('debug', `Connect: forwardOut`); + parentConnection.forwardOut( + '127.0.0.1', + 0, + server.host, + Number(server.port) || 22, + (err, channel) => { + if (context.closed || context.failing) { + if (channel && typeof channel.close === 'function') { + try { + channel.close(); + } catch (e) { + // The channel may already be gone. + } + } + return; + } + + if (err) { + return this._hopFailed(context, err); + } + + if (this._stopping || this._runComplete || this._closing) { + if (channel && typeof channel.close === 'function') { + try { + channel.close(); + } catch (e) { + // The channel may already be gone. + } + } + // The child record is already active. Close it and restore the + // parent so a stop/close during forwardOut does not leave a + // half-open stack. + return this._failContext( + context, + new Error('Connection cancelled'), + 'cancelled' + ); + } + + return this._openClient( + context, + Object.assign({}, server, { sock: channel }) + ); + } + ); + + return this._stream; + } + + // Readability alias used by `_nextHost()`. The transport branch lives in + // `_connect()`. + _connectHop() { + const parent = this._activeContext(); + if (!parent || !parent.connection) { + this.emit('error', 'No parent connection for host hop', 'Hop', false); + return this._callFinalCallback(); + } + return this._connect(parent); + } + + // Shared tail for primary connections and hops. The only difference is the + // `sock` option a hop supplies. + _openClient(context, options) { + context.connection = new this.ssh2Client(); + this.connection = context.connection; + this._bindConnection(context); + + try { + context.connection.connect(options); + } catch (err) { + if (context.isPrimary) { + // A synchronous throw has no guaranteed `close` event, so report it + // and advance the primary here. + this.emit( + 'error', + `${err} ${err.stack}`, + 'Connection.connect', + this._hasLiveStreamFor(context), + null, + context + ); + return this._failContext(context, err, 'connect-throw'); + } + return this._hopFailed(context, err); + } + + return this._stream; + } + + // Attaches the transport handlers to one record. Every handler closes over + // `context`, so a late event from an ancestor cannot act on the active + // child. + _bindConnection(context) { + const connection = context.connection; + + connection.on( 'keyboard-interactive', (name, instructions, instructionsLang, prompts, finish) => { + if (context.closed || context !== this._activeContext()) { + return; + } this._systemMsg('debug', `Connection.keyboard-interactive`); - + this.emit( 'keyboard-interactive', name, @@ -1920,171 +2413,223 @@ class SSH2Shell extends Stream { } ); - this.connection.on('connect', () => { - this._systemMsg('debug',`connect: Connection.connect`); - - this.emit('msg', this.sshObj.connectedMessage); + connection.on('connect', () => { + if (context.closed) { + return; + } + this._systemMsg('debug', `connect: Connection.connect`); + this.emit('msg', context.host.connectedMessage); }); - this.connection.on('ready', () => { - this._systemMsg('debug',`connect: Connection.ready`); - - this.emit('msg', this.sshObj.readyMessage); - - // Open a shell. - this.connection.shell( - this.sshObj.window, - { pty: this.sshObj.pty }, - (err, stream) => { - this._stream = stream; - if (err instanceof Error) { - this.emit('error', err, 'Shell', this._hasLiveStream()); - return; - } - this._systemMsg('debug', `connect: Connection.shell`); - - this._stream.setEncoding(this.sshObj.streamEncoding); - - this._stream.on('error', (err) => { - this._systemMsg('debug', `connect: Stream.error`); - - this.emit('error', err, 'Stream', true); - }); - - this._stream.stderr.on('data', (data) => { - this._systemMsg('debug', `connect: Stream.stderr.data`); - - // Opt-in capture happens before the event so a handler can rely on - // the buffer being current. The event still fires either way. - this._captureStderr(data); - this.emit('stderrData', data); - }); - - this._stream.on('data', (data) => { - try { - this.emit('data', data); - } catch (e) { - const err = new Error(`${e} ${e.stack}`); - err.level = 'Data handling'; - this.emit('error', err, 'Stream.read error', true); - } - }); - - this._stream.on('finish', () => { - this._progressEnd(); - this._systemMsg('debug', `connect: Stream.finish`); - - // Finalize through the same path as close/connection close so the - // text is appended and `end` fires exactly once per host. - this._finalizeHost(this.sshObj, 'stream-finish'); - }); - - this._stream.on('close', (code, signal) => { - this._progressEnd(); - this._systemMsg('debug', `connect: Stream.close`); - - if (this.connection && typeof this.connection.end === 'function') { - this.connection.end(); - } - }); - } - ); + connection.on('ready', () => { + if (context.closed || context.failing) { + return; + } + this._systemMsg('debug', `connect: Connection.ready`); + this.emit('msg', context.host.readyMessage); + return this._openShell(context); }); - this.connection.on('error', (err) => { - this._systemMsg('debug',`connect: Connection.error`); - - // Before the shell opens there is no live stream to close, so report the - // error without terminating. Once a shell exists, the connection error - // is a terminator. - this.emit('error', err, 'Connection', this._hasLiveStream()); + connection.on('error', (err) => { + if (context.closed || context.failing) { + return; + } + this._systemMsg('debug', `connect: Connection.error`); + + if (context.isPrimary) { + // Before the shell opens there is no live stream to close, so report + // the error without terminating. ssh2 follows a connection error with + // `close`, which advances the primary. + this.emit( + 'error', + err, + 'Connection', + this._hasLiveStreamFor(context), + null, + context + ); + return; + } + + // A failed hop connection is contained to that host and its subtree. + return this._hopFailed(context, err); }); - this.connection.on('close', (had_error) => { + connection.on('close', (had_error) => { this._progressEnd(); - this._systemMsg('debug',`connect: Connection.close`); - - if (this.idleTimer) { - clearTimeout(this.idleTimer); - } - if (this.dataReceivedTimer) { - clearTimeout(this.dataReceivedTimer); + this._systemMsg('debug', `connect: Connection.close`); + + if (context.closed || context.failing) { + return; } - // A transport drop may skip stream `finish`, so finalize the current - // host and any ancestors before reporting the close. This keeps the - // callback text complete even when the last command never returned. - this._finalizeRun( - this._stopping ? this._stopReason : 'connection-close' - ); + if (context.isPrimary) { + // Preserve any partial command output before the host is finalized. + this._appendPartial('connection-close', context.host); - if (had_error) { - const err = new Error('Connection closed with error'); - err.level = 'Connection close'; - err.hadError = had_error; - this.emit('error', err, 'Connection close'); - } else { - const closedMessage = - this.sshObj && this.sshObj.closedMessage - ? this.sshObj.closedMessage - : 'Closed'; - this.emit('msg', closedMessage); - } + if (had_error) { + const err = new Error('Connection closed with error'); + err.level = 'Connection close'; + err.hadError = had_error; + this.emit('error', err, 'Connection close', null, null, context); + } else { + const closedMessage = + context.host && context.host.closedMessage + ? context.host.closedMessage + : 'Closed'; + this.emit('msg', closedMessage); + } - if (this._stopping || this._runComplete) { - return this._callFinalCallback(); + return this._failContext( + context, + had_error ? new Error('Connection closed with error') : null, + this._stopping ? this._stopReason : 'connection-close' + ); } - if (this._hosts.length > 0) { - this._closing = false; - this._gracefulClosing = false; - return this.emit( - 'newPrimaryHost', - this._nextPrimaryHost(this._connect) - ); + // A plain close/stop tears the stack down itself; the child close event + // must not navigate back to the parent. + if (this._closing || this._stopping || this._runComplete) { + return; } - return this._callFinalCallback(); + // An unplanned hop close is a record failure. It is contained: the + // parent's remaining hosts still run. + this._appendPartial('connection-close', context.host); + return this._hopFailed(context, new Error('Connection closed')); }); + } - if (this.sshObj.server && this.sshObj.commands) { - try { - if (!this.sshObj.server.username) { - this.sshObj.server.username = this.sshObj.server.userName; - } - if (!this.sshObj.server.hostHash) { - this.sshObj.server.hostHash = this.sshObj.server.hashMethod; - } - if (!this.sshObj.server.passphrase) { - this.sshObj.server.passphrase = this.sshObj.server.passPhrase; + // Opens the shell for a record and routes its stream events. Inactive + // ancestor streams are ignored so only the active host drives the command + // engine. + _openShell(context) { + const connection = context.connection; + const host = context.host; + + connection.shell(host.window, { pty: host.pty }, (err, stream) => { + if (context.closed || context.failing) { + if (stream && typeof stream.close === 'function') { + try { + stream.close(); + } catch (e) { + // The stream may already be gone. + } } - - this.connection.connect(this.sshObj.server); - } catch (e) { - this.emit( - 'error', - `${e} ${e.stack}`, - 'Connection.connect', - this._hasLiveStream() - ); + return; } - } else { - this.emit( - 'error', - 'Missing connection parameters', - 'Parameters', - false, - function (err, type, close) { - const expose = this.exposeCredentials === true; + + if (err instanceof Error) { + this._systemMsg('debug', `connect: Connection.shell`); + + // ssh2 can hand back a stream alongside the error. Store it on the + // record so teardown closes it instead of leaking the shell. + if (stream) { + context.stream = stream; + if (context === this._activeContext()) { + this._stream = stream; + } + } + + if (context.isPrimary) { this.emit( - 'msg', - expose ? this.sshObj.server : redactCredentials(this.sshObj.server) + 'error', + err, + 'Shell', + this._hasLiveStreamFor(context), + null, + context ); - this.emit('msg', this.sshObj.commands); + return this._failContext(context, err, 'shell'); } - ); - } - return this._stream; + return this._hopFailed(context, err); + } + + context.stream = stream; + if (context === this._activeContext()) { + this._stream = stream; + } + this._systemMsg('debug', `connect: Connection.shell`); + + stream.setEncoding(host.streamEncoding); + + stream.on('error', (err) => { + if (context.closed || context.failing) { + return; + } + this._systemMsg('debug', `connect: Stream.error`); + + if (context.isPrimary) { + this.emit('error', err, 'Stream', true, null, context); + return; + } + return this._hopFailed(context, err); + }); + + stream.stderr.on('data', (data) => { + if (context.closed || context !== this._activeContext()) { + return; + } + this._systemMsg('debug', `connect: Stream.stderr.data`); + + // Opt-in capture happens before the event so a handler can rely on + // the buffer being current. The event still fires either way. + this._captureStderr(data); + this.emit('stderrData', data); + }); + + stream.on('data', (data) => { + if (context.closed || context !== this._activeContext()) { + return; + } + try { + this.emit('data', data); + } catch (e) { + const readError = new Error(`${e} ${e.stack}`); + readError.level = 'Data handling'; + if (context.isPrimary) { + this.emit( + 'error', + readError, + 'Stream.read error', + true, + null, + context + ); + return; + } + return this._hopFailed(context, readError); + } + }); + + stream.on('finish', () => { + if (context.closed) { + return; + } + this._progressEnd(); + this._systemMsg('debug', `connect: Stream.finish`); + + // Finalize through the same path as close/connection close so the + // text is appended and `end` fires exactly once per host. + this._finalizeHost(context.host, 'stream-finish'); + }); + + stream.on('close', (code, signal) => { + this._progressEnd(); + this._systemMsg('debug', `connect: Stream.close`); + + if (context.closed || context.failing) { + return; + } + if (context.connection && typeof context.connection.end === 'function') { + try { + context.connection.end(); + } catch (e) { + // The transport may already be gone. + } + } + }); + }); } } @@ -2096,20 +2641,17 @@ SSH2Shell.prototype.command = ''; SSH2Shell.prototype._hosts = []; SSH2Shell.prototype._primaryHostCount = 1; SSH2Shell.prototype._multipleHosts = false; -SSH2Shell.prototype._sshToNextHost = false; SSH2Shell.prototype._primaryhostSessionText = ''; SSH2Shell.prototype._allSessions = ''; SSH2Shell.prototype._connections = []; SSH2Shell.prototype._stream = {}; SSH2Shell.prototype._buffer = ''; -SSH2Shell.prototype._commandSawData = false; SSH2Shell.prototype._stderrBuffer = ''; SSH2Shell.prototype._boundListeners = {}; SSH2Shell.prototype.idleTime = 5000; SSH2Shell.prototype.asciiFilter = ''; SSH2Shell.prototype.textColorFilter = ''; SSH2Shell.prototype.passwordPrompt = ''; -SSH2Shell.prototype.passphrasePrompt = ''; SSH2Shell.prototype.standardPrompt = ''; SSH2Shell.prototype._callback = function () {}; SSH2Shell.prototype.onCommandProcessing = function () {}; diff --git a/lib/ssh2shell/defaults.js b/lib/ssh2shell/defaults.js index e67860b..d913bcc 100644 --- a/lib/ssh2shell/defaults.js +++ b/lib/ssh2shell/defaults.js @@ -3,7 +3,6 @@ // Applies the baseline host defaults in place. This mutates only the host // object; instance-level values (command, buffer, timers) stay in the class. function applyHostDefaults(sshObj) { - sshObj.sshToNextHost = false; if (!sshObj.connectedMessage) { sshObj.connectedMessage = 'Connected'; } @@ -32,11 +31,6 @@ function applyHostDefaults(sshObj) { // changes the second `commandComplete` argument. sshObj.commandResponse = sshObj.commandResponse === 'handled' ? 'handled' : 'raw'; - // Opt-in: arm the command idle timer when the command is written. Without - // this, a command that never produces any output never arms the timer. - if (sshObj.commandStartTimeout !== true) { - sshObj.commandStartTimeout = false; - } // Opt-in: merge stderr into the command response and sessionText. The // `stderrData` event still fires either way. if (sshObj.captureStderr !== true) { @@ -54,9 +48,6 @@ function applyHostDefaults(sshObj) { if (!sshObj.passwordPrompt) { sshObj.passwordPrompt = ':'; } - if (!sshObj.passphrasePrompt) { - sshObj.passphrasePrompt = ':'; - } if (!sshObj.passPromptText) { sshObj.passPromptText = 'Password'; } @@ -73,11 +64,7 @@ function applyHostDefaults(sshObj) { if (sshObj.disableASCIIFilter !== true) { sshObj.disableASCIIFilter = false; } - if (!sshObj.exitCommands) { - sshObj.exitCommands = []; - } sshObj.pwSent = false; - sshObj.sshAuth = false; // Retry budget for command idle timeouts. The library owns the attempt count; // a handler only reacts to the `details` argument. const retries = Number(sshObj.commandTimeoutRetries); @@ -92,7 +79,7 @@ function applyHostDefaults(sshObj) { if (typeof sshObj.sudoFailed !== 'boolean') { sshObj.sudoFailed = false; } - if (sshObj.server.hashKey == null) { + if (sshObj.server && sshObj.server.hashKey == null) { sshObj.server.hashKey = ''; } if (!sshObj.sessionText) { diff --git a/lib/ssh2shell/ssh-command.js b/lib/ssh2shell/ssh-command.js deleted file mode 100644 index 7b5430b..0000000 --- a/lib/ssh2shell/ssh-command.js +++ /dev/null @@ -1,124 +0,0 @@ -'use strict'; - -const { shellControlChars, shellQuote } = require('./util'); - -// Maps a boolean-or-value SSH option to an allow-listed command-line flag. -// `true` selects the documented default; `false`/null/undefined disable it. -function mapSshFlag(value, allowed, defaultValue, name) { - const selected = value === true ? defaultValue : String(value); - if (!allowed.includes(selected)) { - return { error: `Invalid ${name}: ${value}` }; - } - return { flag: ` -${selected}` }; -} - -// Appends one `- ` option after checking for shell control -// characters. Returns an error object instead of throwing so the caller can -// emit a Security Alert without interrupting the connection flow. -function appendSshOption(parts, flag, value, label) { - if (!value) { - return null; - } - if (shellControlChars.test(value)) { - return { error: `Malicious characters detected in SSH ${label}.` }; - } - parts.push(` -${flag} ${shellQuote(value)}`); - return null; -} - -// Builds the `ssh ...` command used to connect to a secondary/nested host. -// Returns `{ error }` for an injection guard, or `{ command }` on success. -function buildSshCommand(sshObj) { - // Add ssh commandline options from host.server.ssh. - let sshFlags = '-x'; - const sshOptions = []; - - if (sshObj.server.ssh) { - // Map protocol/address options to valid ssh flags. `true` keeps the old - // boolean intent by selecting the modern default (IPv4 / protocol 2). - if (sshObj.server.ssh.forceProtocolVersion) { - const protocol = mapSshFlag( - sshObj.server.ssh.forceProtocolVersion, - ['1', '2'], - '2', - 'forceProtocolVersion' - ); - if (protocol.error) { - return protocol; - } - sshFlags += protocol.flag; - } - if (sshObj.server.ssh.forceAddressType) { - const address = mapSshFlag( - sshObj.server.ssh.forceAddressType, - ['4', '6'], - '4', - 'forceAddressType' - ); - if (address.error) { - return address; - } - sshFlags += address.flag; - } - if (sshObj.server.ssh.disablePseudoTTY) { - sshFlags += 'T'; - } - if (sshObj.server.ssh.forcePseudoTTY) { - sshFlags += 't'; - } - if (sshObj.server.ssh.verbose) { - sshFlags += 'v'; - } - - // Intercept and safely escape single-parameter properties. The label is - // used verbatim in the Security Alert message. - const optionSpecs = [ - ['c', 'cipherSpec', 'cipherSpec'], - ['e', 'escape', 'escape sequence'], - ['E', 'logFile', 'logFile path'], - ['F', 'configFile', 'configFile path'], - ['i', 'identityFile', 'identityFile path'], - ['l', 'loginName', 'loginName'], - ['m', 'macSpec', 'macSpec'], - ]; - for (const [flag, key, label] of optionSpecs) { - const failure = appendSshOption( - sshOptions, - flag, - sshObj.server.ssh[key], - label - ); - if (failure) { - return failure; - } - } - - // Validate custom option blocks safely. Only own enumerable properties are - // included, so inherited values cannot leak into the command line. - const options = sshObj.server.ssh.options || {}; - for (const [option, value] of Object.entries(options)) { - if (shellControlChars.test(option) || shellControlChars.test(value)) { - return { error: 'Malicious characters detected in SSH options.' }; - } - const safeOption = String(option).replace(/[^a-zA-Z0-9]/g, ''); - const safeValue = shellQuote(value); - sshOptions.push(` -o ${safeOption}=${safeValue}`); - } - } - - // Wrap target dynamic properties to ensure security boundaries hold up. - sshOptions.push(' -o "StrictHostKeyChecking=no"'); - - // Sanitize user context fields going straight into the string command. - const safePort = String(sshObj.server.port || 22).replace(/[^0-9]/g, ''); - sshOptions.push(` -p ${safePort}`); - - const safeUser = shellQuote(sshObj.server.userName); - const safeHost = shellQuote(sshObj.server.host); - - return { - command: `ssh ${sshFlags} ${sshOptions.join('')} ${safeUser}@${safeHost}`, - }; -} - -module.exports = { buildSshCommand }; diff --git a/lib/ssh2shell/util.js b/lib/ssh2shell/util.js index 3ceba4c..48278a2 100644 --- a/lib/ssh2shell/util.js +++ b/lib/ssh2shell/util.js @@ -6,12 +6,6 @@ function escapeRegex(str) { return String(str).replace(/[|\\{}()[\]^$+*?.]/g, '\\$&'); } -function shellQuote(value) { - return "'" + String(value).replace(/'/g, "'\\''") + "'"; -} - -const shellControlChars = /[;&|`$\n\r]/; - // Terminal escape sequences arrive as complete CSI or OSC strings. The ASCII // filter only removes the ESC byte, which leaves the printable payload (for // example `[?2004l` and `]3008;...`) in the response. Remove the whole @@ -88,10 +82,6 @@ function compilePrompts(sshObj) { `${cleanText}[^\\n]*${escapeRegex(sshObj.passwordPrompt || ':')}\\s?$`, 'i' ), - passphrasePrompt: new RegExp( - `${cleanText}[^\\n]*${escapeRegex(sshObj.passphrasePrompt || ':')}\\s?$`, - 'i' - ), standardPrompt: custom.regex || new RegExp(`[${escapeRegex(sshObj.standardPrompt || '>$%#')}]\\s?$`), @@ -169,8 +159,6 @@ module.exports = { escapeRegex, redactCredentials, redactString, - shellControlChars, - shellQuote, stripTerminalEscapes, typeIsArray, }; diff --git a/scripts/run-live.js b/scripts/run-live.js index f9c122a..c530876 100644 --- a/scripts/run-live.js +++ b/scripts/run-live.js @@ -18,7 +18,12 @@ const repoRoot = path.join(__dirname, '..'); const testDir = path.join(repoRoot, 'test', 'live'); const logDir = path.join(repoRoot, 'test', 'logs'); const instrumentPath = path.join(__dirname, 'live-instrument.js'); -const modulePath = path.join(repoRoot, 'src', 'ssh2shell.js'); +const { resolveTarget } = require(path.join( + repoRoot, + 'test', + 'utils', + 'module-target.js' +)); const resultPath = path.join(logDir, '.live-result.json'); // Load .env so the runner can build the same expectations the tests see. @@ -28,6 +33,12 @@ try { // .env is optional; tests that need it report their own missing values. } +// `SSH2SHELL_MODULE` selects src (default), lib, baseline, or a path. The +// absolute path is passed to both the instrumentation preload and the tests. +const modulePath = resolveTarget( + process.env.SSH2SHELL_MODULE || process.env.SSH2SHELL_LIVE_MODULE +); + const env = process.env; const user = env.USER_NAME || 'tester'; const secondUser = env.SECOND_USER || 'suuser'; @@ -80,7 +91,9 @@ const fatalLogMarkers = [ // Per-test success checks. `contains`/`excludes` inspect the callback session // text; `logContains`/`logExcludes` inspect the test log; `files` inspect the -// extra output files some tests write. +// extra output files some tests write. `allowErrors` lists expected error event +// types and `allowFatalMarkers` lists expected connection markers for fault +// tests. const checks = { simple: { contains: ['Filesystem', 'Mem:'], @@ -142,6 +155,45 @@ const checks = { contains: [server1, server2].filter(Boolean), excludes: ['SSH failed'], }, + // Full host-array walk: three primaries, nested hosts at three depths, and + // siblings. The order is depth-first and is asserted inside the test too. + host_traversal: { + contains: [ + 'traversal:host1', + 'traversal:hosta', + 'traversal:hostaa', + 'traversal:hostaaa', + 'traversal:host2', + 'traversal:hostb', + 'traversal:hostbb', + 'traversal:hostc', + 'traversal:hostcc', + 'traversal:host3', + 'traversal:hostd', + 'traversal:hoste', + 'traversal:hostf', + ], + logContains: [ + 'traversal-order:host1,hosta,hostaa,hostaaa,host2,hostb,hostbb,hostc,hostcc,host3,hostd,hoste,hostf', + ], + excludes: ['SSH failed'], + }, + // Fault containment: a failed hop must not skip its sibling, and a failed + // primary must not stop the next primary. The failed hosts and the + // never-started descendant must not run. This is the acceptance test for the + // next-host-connection transport; the nested-ssh path fails it because the + // failed hop's command runs on the parent shell and the sibling is skipped. + host_faults: { + contains: ['fault:primary1', 'fault:good-hop', 'fault:good-sibling', 'fault:primary2'], + excludes: ['fault:bad-deep', 'fault:bad-deep-child', 'fault:bad-primary'], + logContains: [ + 'fault-order:primary1,good-hop,good-sibling,primary2', + 'error-count:2', + 'end-order:bad-deep,good-hop,good-sibling,primary1,bad-primary,primary2', + ], + allowErrors: ['Connection', 'Hop'], + allowFatalMarkers: ['ECONNREFUSED'], + }, progress: { contains: ['progress-demo-', server1, server2].filter(Boolean), }, @@ -154,7 +206,7 @@ const checks = { logContains: ['Note: Starting deployment'], }, bash_script: { - contains: ['./myscript.sh', 'rm myscript.sh'], + contains: [': printf'], excludes: ['No such file or directory', 'command not found', 'syntax error'], }, lots_of_commands: { @@ -292,7 +344,11 @@ function evaluate(name, result, logText) { } } + const allowedMarkers = new Set(check.allowFatalMarkers || []); for (const marker of fatalLogMarkers) { + if (allowedMarkers.has(marker)) { + continue; + } if (normalizedLog.includes(marker)) { failures.push(`fatal log marker: ${marker}`); } @@ -510,6 +566,7 @@ async function main() { console.log( `Running ${selected.length} live test(s), timeout ${options.timeoutMs / 1000}s` ); + console.log(`Module: ${path.relative(repoRoot, modulePath)}`); console.log(''); const results = []; diff --git a/src/ssh2shell.js b/src/ssh2shell.js index 0c38cc6..caa1b1a 100644 --- a/src/ssh2shell.js +++ b/src/ssh2shell.js @@ -4,12 +4,12 @@ // nested host objects. // // The class is the public facade. Pure default application, prompt/filter -// compilation, and nested-SSH command construction live in ./ssh2shell/*. -// Behavior matches the baseline except for the signed-off L5/L6/L6.1 fixes. +// compilation, and credential redaction live in ./ssh2shell/*. Host hops are +// real ssh2 connections opened through the parent connection's forwardOut +// channel; there is no nested `ssh` command. const Stream = require('node:stream'); -const { buildSshCommand } = require('./ssh2shell/ssh-command'); const { applyHostDefaults } = require('./ssh2shell/defaults'); const { compileAsciiFilter, @@ -74,13 +74,13 @@ class SSH2Shell extends Stream { // their `this`. this._connect = this._connect.bind(this); this.connect = this.connect.bind(this); + this._connectHop = this._connectHop.bind(this); this._loadDefaults = this._loadDefaults.bind(this); this._initiate = this._initiate.bind(this); this._removeListeners = this._removeListeners.bind(this); this.close = this.close.bind(this); this.stop = this.stop.bind(this); this._runExit = this._runExit.bind(this); - this._sshConnect = this._sshConnect.bind(this); this._nextPrimaryHost = this._nextPrimaryHost.bind(this); this._nextHost = this._nextHost.bind(this); this._previousHost = this._previousHost.bind(this); @@ -105,7 +105,6 @@ class SSH2Shell extends Stream { this._forceClose = this._forceClose.bind(this); this._closeStreamNow = this._closeStreamNow.bind(this); this._processNotifications = this._processNotifications.bind(this); - this._processSSHPrompt = this._processSSHPrompt.bind(this); this._resetFromSudoError = this._resetFromSudoError.bind(this); this._processSudoPrompt = this._processSudoPrompt.bind(this); this._sanitizeResponse = this._sanitizeResponse.bind(this); @@ -114,17 +113,57 @@ class SSH2Shell extends Stream { this._systemMsg = this._systemMsg.bind(this); this._detachListener = this._detachListener.bind(this); this._boundListener = this._boundListener.bind(this); - this._loadDefaultListeners = this._loadDefaultListeners.bind(this); + this._loadDefaultListeners = this._loadDefaultListeners.bind(this); + this._normalizeServer = this._normalizeServer.bind(this); + this._bindConnection = this._bindConnection.bind(this); + this._openShell = this._openShell.bind(this); + this._openClient = this._openClient.bind(this); + this._pushContext = this._pushContext.bind(this); + this._activeContext = this._activeContext.bind(this); + this._popContext = this._popContext.bind(this); + this._popTo = this._popTo.bind(this); + this._restoreContext = this._restoreContext.bind(this); + this._attachContextListeners = this._attachContextListeners.bind(this); + this._descendantsOf = this._descendantsOf.bind(this); + this._closeContext = this._closeContext.bind(this); + this._closeAllContexts = this._closeAllContexts.bind(this); + this._failContext = this._failContext.bind(this); + this._hopFailed = this._hopFailed.bind(this); + this._endPrimary = this._endPrimary.bind(this); + this._pendingHosts = this._pendingHosts.bind(this); + this._appendPartial = this._appendPartial.bind(this); + this._reportMissingParameters = this._reportMissingParameters.bind(this); + this._bindHostListener = this._bindHostListener.bind(this); + this._streamFor = this._streamFor.bind(this); + this._hasLiveStreamFor = this._hasLiveStreamFor.bind(this); this.ssh2Client = require('ssh2').Client; - this._hosts = typeIsArray(hosts) && hosts.length > 0 ? hosts : [hosts]; + + // A single host config or a non-empty array of host configs. The caller's + // array is copied so shift() cannot drain a config reused by another run. + const list = typeIsArray(hosts) ? hosts : [hosts]; + if ( + list.length === 0 || + list.some((host) => !host || typeof host !== 'object') + ) { + throw new TypeError( + 'ssh2shell: a host config object or a non-empty array of host configs is required' + ); + } + this._hosts = list.slice(); this._primaryHostCount = this._hosts.length; this._multipleHosts = this._primaryHostCount > 1; this._boundListeners = {}; - this.sshObj = {}; + this.sshObj = {}; + // `_connections` holds the ancestors of the active record; `_active` is the + // active record itself. A primary host has an empty stack. this._connections = []; + this._active = null; + this._primaryEnded = false; this.host = "No host"; this._allSessions = ''; this._defaultErrorListener = null; + this._defaultDataListener = null; + this._defaultStderrListener = null; // Progress output is on by default and written to stderr so it never // touches sessionText. The stream and interval are instance state so a test // or a consumer can substitute a TTY-like sink without changing the host @@ -144,7 +183,6 @@ class SSH2Shell extends Stream { this._stopReason = null; this._stopTimer = null; this._commandInFlight = false; - this._commandSawData = false; this._stderrBuffer = ''; this._inCommandComplete = false; this._started = false; @@ -165,9 +203,21 @@ class SSH2Shell extends Stream { console.log(message); }; } - if(!this._boundListeners['msg']){ - this._boundListener('msg', this.msg); - } + // Keep the instance fallback available between hosts. A host-specific `msg` + // handler replaces it while that record is active; _removeListeners + // restores it when the record is left. Check whether the host handler is + // actually attached, not just present in the record: a switch detaches it + // before the child is created. + const active = this._activeContext(); + const hostMsgAttached = Boolean( + active && + active.listeners && + typeof active.listeners.msg === 'function' && + this.listeners('msg').includes(active.listeners.msg) + ); + if (!hostMsgAttached && !this.listeners('msg').includes(this.msg)) { + this.on('msg', this.msg); + } // Break the progress line before any msg listener runs, including a // caller-supplied handler. This keeps a heartbeat from prefixing a message. if (!this._progressMsgListener) { @@ -176,23 +226,23 @@ class SSH2Shell extends Stream { }; this.prependListener('msg', this._progressMsgListener); } - if(!this._boundListeners['data']){ - const data = (data) => { - this._onData(data); - }; - this._boundListener ( 'data', data); + if (!this._defaultDataListener) { + this._defaultDataListener = (data) => { + this._onData(data); + }; + this.on('data', this._defaultDataListener); } - if(!this._boundListeners['stderrData']){ - const stderrData = (data) => { - console.error(data); - }; - this._boundListener ( 'stderrData', stderrData); + if (!this._defaultStderrListener) { + this._defaultStderrListener = (data) => { + console.error(data); + }; + this.on('stderrData', this._defaultStderrListener); } // Track the default error listener separately from host `onError` handlers. // The host cache entry is cleared when a host handler is detached, which // used to make the next host install a second default listener. if (!this._defaultErrorListener) { - this._defaultErrorListener = (err, type, close = false, callback) => { + this._defaultErrorListener = (err, type, close = false, callback, context) => { this._progressEnd(); this._systemMsg('debug', `Class.error: ${err}, ${type}`); @@ -209,46 +259,22 @@ class SSH2Shell extends Stream { callback.call(this, err, type, close); } - // Only close a real shell stream. Before the shell opens, `_stream` is - // the prototype `{}` placeholder, which has no close method. - if (close && this._hasLiveStream()) { - this._stream.close(); + // Only close a real shell stream. Before the shell opens, the active + // stream is the `{}` placeholder, which has no close method. The + // optional context lets an ancestor error close its own stream instead + // of the active child's. + if (close) { + const target = context || this._activeContext(); + const stream = target && target.stream ? target.stream : this._stream; + if (stream && typeof stream.close === 'function') { + stream.close(); + } } }; } if (!this.listeners('error').includes(this._defaultErrorListener)) { this.on('error', this._defaultErrorListener); } - if(!this._boundListeners['keyboard-interactive']){ - // Only install the fallback when the caller has not supplied a handler. - // Two handlers would both call finish(), resetting the handshake. - const hasUserHandler = - this.listeners('keyboard-interactive').length > 0 || - typeof this.sshObj?.onKeyboardInteractive === 'function'; - if ( - this.sshObj && - this.sshObj.server && - this.sshObj.server.tryKeyboard && - !hasUserHandler - ) { - const keyboardInteractive = (name, instructions, instructionsLang, prompts, finish) => { - this._systemMsg('debug',`keyboard-interactive:`); - - this._systemMsg('verbose',`name: ${name}`); - this._systemMsg('verbose',`instructions: ${instructions}`); - - const responses = prompts.map(p => { - this._systemMsg('verbose',`prompts: ${p.prompt}`); - return ''; // Baseline fallback response - }); - this._systemMsg('verbose',`Prompts object: ${responses}`); - // The handshake stalls unless finish() receives the responses as an - // array of strings. - finish(responses); - }; - this._boundListener ( 'keyboard-interactive', keyboardInteractive); - } - } return; } @@ -270,11 +296,382 @@ class SSH2Shell extends Stream { } // A real shell stream exists only after `connection.shell` succeeds. Before - // that, `_stream` is the prototype `{}` placeholder. + // that, the active stream is the `{}` placeholder. _hasLiveStream() { - return Boolean(this._stream && typeof this._stream.close === 'function'); + const context = this._activeContext(); + const stream = context && context.stream ? context.stream : this._stream; + return Boolean(stream && typeof stream.close === 'function'); } - + + // Bind a host handler to this instance and remember it on the record so the + // exact function can be removed when the record is left. Replacing a handler + // for the same event removes the previous record handler first. + _bindHostListener(context, eventName, listener, prepend = false) { + if (!context || typeof listener !== 'function') { + return; + } + + const previous = context.listeners[eventName]; + if (previous === listener && this.listeners(eventName).includes(listener)) { + return; + } + if (typeof previous === 'function' && previous !== listener) { + this.removeListener(eventName, previous); + } + + context.listeners[eventName] = listener; + if (prepend) { + this.prependListener(eventName, listener); + } else { + this.on(eventName, listener); + } + } + + // Re-attaches the handlers a record bound before it was left for a child. + // Host handlers are detached on every switch, so restoring an ancestor has + // to put its own handlers back before it can finish (for example `onEnd`). + _attachContextListeners(context) { + if (!context || !context.listeners) { + return; + } + + for (const [eventName, listener] of Object.entries(context.listeners)) { + if (typeof listener !== 'function') { + continue; + } + if (this.listeners(eventName).includes(listener)) { + continue; + } + if (eventName === 'msg' && this.listeners('msg').includes(this.msg)) { + this.removeListener('msg', this.msg); + } + if (eventName === 'error') { + this.prependListener(eventName, listener); + } else { + this.on(eventName, listener); + } + } + } + + // Returns the stream that belongs to a record. Tests and embedders can set + // `_stream` directly without going through `_openShell`, so the active record + // falls back to the instance alias. + _streamFor(context) { + if (!context) { + return null; + } + if (context.stream) { + return context.stream; + } + return context === this._activeContext() ? this._stream : null; + } + + _hasLiveStreamFor(context) { + const stream = this._streamFor(context); + return Boolean(stream && typeof stream.close === 'function'); + } + + // Copy the server options so the host config is not mutated. `ssh2` uses + // `username` / `passphrase`; the public API keeps the legacy aliases. + _normalizeServer(server) { + const options = Object.assign({}, server || {}); + delete options.ssh; + if (!options.username) { + options.username = options.userName; + } + if (!options.hostHash) { + options.hostHash = options.hashMethod; + } + if (!options.passphrase) { + options.passphrase = options.passPhrase; + } + return options; + } + + // Creates the record for the active host. `parent === null` is a primary; + // otherwise the parent record is pushed onto the ancestor stack first. + _pushContext(host, parent) { + if (parent) { + this._connections.push(parent); + } + + const record = { + host, + parent: parent || null, + connection: null, + stream: null, + isPrimary: !parent, + closed: false, + failing: false, + listeners: {}, + idleTimer: null, + dataReceivedTimer: null, + expectedClose: false, + idleTime: this.idleTime, + dataIdleTime: this.dataIdleTime, + pendingHosts: null, + reportedError: false, + }; + + this._active = record; + this.sshObj = host; + this.host = host.server ? host.server.host : 'No host'; + this.connection = null; + this._stream = {}; + this.idleTimer = null; + this.dataReceivedTimer = null; + return record; + } + + _activeContext() { + return this._active || null; + } + + // Makes a record the active host again and re-points the compatibility + // aliases at it. + _restoreContext(context) { + if (!context) { + return null; + } + this._active = context; + this.connection = context.connection; + this._stream = context.stream || {}; + this.sshObj = context.host; + this.host = context.host && context.host.server + ? context.host.server.host + : this.host; + this.idleTime = context.idleTime; + this.dataIdleTime = context.dataIdleTime; + this.idleTimer = context.idleTimer || null; + this.dataReceivedTimer = context.dataReceivedTimer || null; + + // Compiled prompts/filters and logging flags belong to the active record. + // Parents are restored after a child closes, so put theirs back too. + if (context.standardPrompt) { + this.standardPrompt = context.standardPrompt; + } + if (context.passwordPrompt) { + this.passwordPrompt = context.passwordPrompt; + } + if (context.asciiFilter) { + this.asciiFilter = context.asciiFilter; + } + if (context.textColorFilter) { + this.textColorFilter = context.textColorFilter; + } + if (typeof context.debug === 'boolean') { + this.debug = context.debug; + } + if (typeof context.verbose === 'boolean') { + this.verbose = context.verbose; + } + if (typeof context.progress === 'boolean') { + this.progress = context.progress; + } + if (typeof context.exposeCredentials === 'boolean') { + this.exposeCredentials = context.exposeCredentials; + } + + this._attachContextListeners(context); + return context; + } + + // Pops the top ancestor and makes it active. Used when a hop completes. + _popContext() { + const parent = this._connections.pop(); + if (!parent) { + return null; + } + return this._restoreContext(parent); + } + + // Drops a failed record and everything above it, then restores its parent. + _popTo(context) { + if (!context) { + return null; + } + + const index = this._connections.indexOf(context); + if (index >= 0) { + // Remove the record and its descendants from the stack. + this._connections.length = index; + } + + const parent = this._connections.pop() || context.parent || null; + if (parent) { + return this._restoreContext(parent); + } + this._active = null; + return null; + } + + // Active record plus every record deeper than `context`, deepest-first. + // `context` itself is excluded; callers close it separately. + _descendantsOf(context) { + if (!context) { + return []; + } + + const result = []; + const active = this._activeContext(); + if (active && active !== context && !active.closed) { + result.push(active); + } + + const index = this._connections.indexOf(context); + if (index >= 0) { + for (let position = this._connections.length - 1; position > index; position -= 1) { + const record = this._connections[position]; + if (record && record !== context && !record.closed) { + result.push(record); + } + } + } + return result; + } + + // The only record teardown point. Idempotent through `context.closed`. + _closeContext(context, reason) { + if (!context || context.closed) { + return false; + } + + context.closed = true; + + // Finalize while the record's own handlers are still attached so a host + // `onEnd` observes its `end`. `closed` already makes transport events + // no-ops, so the close below cannot re-enter this path. + this._finalizeHost(context.host, reason); + this._removeListeners(context); + + const stream = this._streamFor(context); + if (stream && typeof stream.close === 'function') { + try { + stream.close(); + } catch (e) { + // The transport may already be gone; teardown continues. + } + } + if (context.connection && typeof context.connection.end === 'function') { + try { + context.connection.end(); + } catch (e) { + // The transport may already be gone; teardown continues. + } + } + + return true; + } + + // Closes the active record and every ancestor, deepest-first. + _closeAllContexts(reason) { + const active = this._activeContext(); + if (active) { + this._closeContext(active, reason); + } + for (let index = this._connections.length - 1; index >= 0; index -= 1) { + this._closeContext(this._connections[index], reason); + } + } + + // The only record failure entry point. Descendants are torn down first, then + // the record itself, and navigation follows the primary/hop split. + _failContext(context, err, reason) { + if (!context || context.closed || context.failing) { + return; + } + context.failing = true; + + for (const descendant of this._descendantsOf(context)) { + this._closeContext(descendant, 'ancestor-failed'); + } + this._closeContext(context, reason); + + if (context.isPrimary) { + return this._endPrimary(reason); + } + + this._popTo(context); + return this._runExit(); + } + + _hopFailed(context, err) { + if (!context || context.closed || context.failing) { + return; + } + context.reportedError = true; + this.emit('error', err, 'Hop', false, null, context); + return this._failContext(context, err, 'hop-failed'); + } + + // Exactly-once primary advance. Callers report the close before calling this; + // `_endPrimary` only navigates. + _endPrimary(reason) { + if (this._primaryEnded || this._runComplete) { + return; + } + this._primaryEnded = true; + this._finalizeRun(reason); + + if (this._stopping || this._closing) { + return this._callFinalCallback(); + } + if (this._hosts.length > 0) { + return this._nextPrimaryHost(this._connect); + } + return this._callFinalCallback(); + } + + // Nested host queues are copied lazily so a config can be reused across runs + // without `shift()` draining the caller's array. + _pendingHosts(context = this._activeContext()) { + const host = context ? context.host : this.sshObj; + if (context && context.pendingHosts) { + return context.pendingHosts; + } + + const list = host && Array.isArray(host.hosts) ? host.hosts : []; + if (!context) { + return list; + } + context.pendingHosts = list.slice(); + return context.pendingHosts; + } + + // Preserves the partial response of a command that never returned a prompt, + // so `end` and the final callback see it even though `_finalizeHost` only + // reads `sessionText`. + _appendPartial(reason, host = this.sshObj) { + if (!this._buffer) { + return ''; + } + const partial = this._buffer; + this._buffer = ''; + if (host) { + host.sessionText += partial; + host.sessionText += `\n[connection closed${reason ? `: ${reason}` : ''}]\n`; + } + return partial; + } + + _reportMissingParameters() { + this.emit( + 'error', + 'Missing connection parameters', + 'Parameters', + false, + function (err, type, close) { + const expose = this.exposeCredentials === true; + this.emit( + 'msg', + expose ? this.sshObj.server : redactCredentials(this.sshObj.server) + ); + this.emit('msg', this.sshObj.commands); + } + ); + return this._stream; + } + // Helper to safely detach listeners using cached references _detachListener(eventName, currentKey) { const cachedHandler = this._boundListeners[eventName]; @@ -439,25 +836,32 @@ class SSH2Shell extends Stream { return null; } - this.idleTimer = setTimeout(() => { + const context = this._activeContext(); + const timer = setTimeout(() => { + // A timer left over from an inactive or closed record must not fire + // against the active host. + if (context && (context.closed || context !== this._activeContext())) { + return; + } + // This timer has fired. Clearing the reference lets the re-arm check // below detect whether _onData already scheduled the next one. - this.idleTimer = null; + if (context) { + context.idleTimer = null; + } + if (this.idleTimer === timer) { + this.idleTimer = null; + } this._progressEnd(); const attempt = (this.sshObj.commandTimeoutAttempt || 0) + 1; this.sshObj.commandTimeoutAttempt = attempt; const maxRetries = toNonNegativeInteger(this.sshObj.commandTimeoutRetries); const final = attempt > maxRetries; - // Distinguish a command that has not produced anything yet from one - // whose output arrived but never returned to a prompt. With no command - // in flight this is not a command-output distinction. - const noOutput = - this.command.length > 0 && this._commandSawData !== true; this._systemMsg( 'debug', - `commandTimeout: ${noOutput ? 'no output received' : 'no prompt detected'} (${attempt}/${maxRetries})` + `commandTimeout: no prompt detected (${attempt}/${maxRetries})` ); this.emit( @@ -466,7 +870,7 @@ class SSH2Shell extends Stream { response, this._stream, this.connection, - { attempt, maxRetries, final, noOutput } + { attempt, maxRetries, final } ); // Re-arm for the next attempt unless this was the last one, the handler @@ -481,7 +885,11 @@ class SSH2Shell extends Stream { } }, this.idleTime); - return this.idleTimer; + if (context) { + context.idleTimer = timer; + } + this.idleTimer = timer; + return timer; } _onData(data) { @@ -492,15 +900,11 @@ class SSH2Shell extends Stream { } this._buffer += data; - // Any data for a command means the timeout is a missed prompt rather than - // a completely silent command. The start timer uses this for `noOutput`. - if (this.command.length > 0) { - this._commandSawData = true; - } - if ( - this.command.length > 0 && - !this.standardPrompt.test(this._sanitizeResponse()) - ) { + const hasCommand = this.command.length > 0; + const promptDetected = + hasCommand && this.standardPrompt.test(this._sanitizeResponse()); + + if (hasCommand && !promptDetected) { this.emit( 'commandProcessing', this.command, @@ -512,10 +916,7 @@ class SSH2Shell extends Stream { clearTimeout(this.idleTimer); } this._scheduleIdleTimeout(this._buffer); - } else if ( - this.command.length < 1 && - !this.standardPrompt.test(this._buffer) - ) { + } else if (!hasCommand && !this.standardPrompt.test(this._buffer)) { this.emit( 'commandProcessing', this.command, @@ -525,12 +926,41 @@ class SSH2Shell extends Stream { ); } + // A detected prompt means the command returned to the shell, so the idle + // timeout no longer applies. Clearing it here (rather than only in the + // settle callback) keeps a short `idleTimeOut` from firing before a longer + // `dataIdleTimeOut` has grouped the response. + if (promptDetected && this.idleTimer) { + clearTimeout(this.idleTimer); + this.idleTimer = null; + const active = this._activeContext(); + if (active) { + active.idleTimer = null; + } + } + // Set a timer to fire when no more data events are received and then // process the buffer based on command and prompt combinations. + const context = this._activeContext(); + if (context && context.dataReceivedTimer) { + clearTimeout(context.dataReceivedTimer); + } if (this.dataReceivedTimer) { clearTimeout(this.dataReceivedTimer); } - return (this.dataReceivedTimer = setTimeout(() => { + const timer = setTimeout(() => { + // A timer left over from an inactive or closed record must not process + // the active host's buffer. + if (context && (context.closed || context !== this._activeContext())) { + return; + } + if (context) { + context.dataReceivedTimer = null; + } + if (this.dataReceivedTimer === timer) { + this.dataReceivedTimer = null; + } + // Clear the command and SSH timeout timer. if (this.idleTimer) { clearTimeout(this.idleTimer); @@ -555,13 +985,6 @@ class SSH2Shell extends Stream { this._systemMsg('debug', `onData: Sudo command data`); return this._processSudoPrompt(); - // Check if ssh authentication needs to be handled. - case this.sshObj.sshToNextHost && - this.command.length > 0 && - this.command.indexOf('ssh ') === 0: - this._systemMsg('debug', `onData: SSH command data`); - - return this._processSSHPrompt(); // Check for standard prompt from a command. case this.command.length > 0 && this.standardPrompt.test(this._sanitizeResponse()): @@ -582,14 +1005,32 @@ class SSH2Shell extends Stream { return this._scheduleIdleTimeout(this._buffer); } - }, this.dataIdleTime)); + }, this.dataIdleTime); + if (context) { + context.dataReceivedTimer = timer; + } + this.dataReceivedTimer = timer; + return timer; } _sanitizeResponse() { - return this._buffer.replace( - this.command.slice(0, this._buffer.length), - '' - ); + const command = this.command; + if (!command) { + return this._buffer; + } + + // The shell echoes the command before running it. A long line can make the + // terminal redraw, and that redraw may put a prompt or control text before + // the final echo. Slice after the last echo so only what the command + // produced is tested for a prompt; a prompt that appears before the echo + // belongs to the previous command and must not complete this one. + const index = this._buffer.lastIndexOf(command); + if (index >= 0) { + return this._buffer.slice(index + command.length); + } + + // The buffer may still hold only part of the echoed command. + return this._buffer.replace(command.slice(0, this._buffer.length), ''); } // Opt-in `commandResponse: 'handled'` payload: the echoed command and the @@ -722,240 +1163,64 @@ class SSH2Shell extends Stream { return result; } - _sshConnect() { - if (this._stopping || this._runComplete) { - return; + _processNotifications() { + // An empty command has nothing to run or report, so skip it and continue + // with the queue instead of leaving the state machine idle. + if (!this.command) { + this._systemMsg('debug', `processNotifications: Empty command, skip`); + return this._nextCommand(); } - const result = buildSshCommand(this.sshObj); - if (result.error) { - this.emit('error', result.error, 'Security Alert', true); - return; + // This is a message for the sessionText like an echo command in bash. + const sessionNote = this.command.match(/^`(.*)`$/); + if (sessionNote) { + this._systemMsg('debug', `processNotifications: sessionText output`); + + if (this._connections.length > 0) { + this.sshObj.sessionText += `${this.host}: Note: ${sessionNote[1]}${this.sshObj.enter}`; + } else { + this.sshObj.sessionText += `Note: ${sessionNote[1]}${this.sshObj.enter}`; + } + this._systemMsg('verbose', sessionNote[1]); + + return this._nextCommand(); } - // A nested connection that authenticates with a key has no prompt to - // answer. Mark it authenticated up front so the first remote shell prompt - // is treated as success instead of a failed connection. Password and - // passphrase auth still start unauthenticated so the first prompt can be - // answered. - const server = this.sshObj.server; - this.sshObj.sshAuth = !server.password && !server.passPhrase; - this.sshObj.sshToNextHost = true; + // This is a message to output in process. + const msgNote = this.command.match(/^msg:(.*)$/); + if (msgNote) { + this._systemMsg('debug', `processNotifications: msg to output`); + + this.emit('msg', `${this._hostPrefix()}Note: ${msgNote[1]}`); + return this._nextCommand(); + } - // Perfectly combined secure connection command string. - this.command = result.command; - this._systemMsg('debug',`SSH command: connect`); - this._progressStart(); + this._systemMsg('debug', `processNotifications: Normal Command to run`); - return this._runCommand(this.command); + return this._checkCommand(); } - - _processSSHPrompt() { - // Not authenticated yet so detect prompts. - const response = this._sanitizeResponse().trim(); - if (this.idleTimer) { - clearTimeout(this.idleTimer); - } - const passwordPrompt = - this.passwordPrompt.test(response) && - !this.sshObj.server.hasOwnProperty('passPhrase'); - const passphrasePrompt = - this.passphrasePrompt.test(response) && - this.sshObj.server.hasOwnProperty('passPhrase'); - const standardPrompt = this.standardPrompt.test(response); - - this._systemMsg('debug', `processSSHPrompt: SSH password handling`); - - this._systemMsg( - 'verbose', - `processSSHPrompt: Password prompt: ${passwordPrompt}, Passphase prompt: ${passphrasePrompt}, Standard prompt: ${standardPrompt}, Password previously sent: ${this.sshObj.sshAuth}` - ); - if (!this.sshObj.sshAuth) { - this._systemMsg( - 'debug', - `processSSHPrompt: First prompt detection` - ); + _commandComplete() { + this._progressEnd(); + this._commandInFlight = false; + const rawResponse = this._buffer; + const response = rawResponse.trim(); + // Captured stderr is consumed once per command. It is empty unless the + // host opts in with `captureStderr: true`. + const capturedStderr = + this.sshObj.captureStderr === true + ? (this._stderrBuffer || '').trim() + : ''; + // `exit` is reported by the shell, not as a command response. It is the + // literal command that leaves `su` / `sudo -i` or the primary shell. + if (this.command !== '' && this.command !== 'exit') { + this._systemMsg('debug',`commandComplete: Raising commandComplete event`); - // Provide password. - if (passwordPrompt) { - this._systemMsg('debug', `processSSHPrompt: send password`); - - this.sshObj.sshAuth = true; - this._buffer = ''; - - return this._runCommand(`${this.sshObj.server.password}`); - } else if (passphrasePrompt) { - this._systemMsg('debug', `processSSHPrompt: send passphrase`); - - this.sshObj.sshAuth = true; - this._buffer = ''; - return this._runCommand(`${this.sshObj.server.passPhrase}`); - } else if (standardPrompt) { - this._systemMsg('debug', `processSSHPrompt: standard prompt: connection failed`); - - this._systemMsg('verbose',`processSSHPrompt: SSH failed: Response: ${response}`); - - this._commandInFlight = false; - this.sshObj.sessionText += `${this.host}: SSH failed: Response: ${response}`; - return this._runExit(); - } else { - this._systemMsg('debug', `processSSHPrompt: No prompt detected`); - - this._systemMsg('verbose',`processSSHPrompt: Response: ${response}`); - - if (this.verbose){ - if (!this.sshObj.server.hasOwnProperty('password')) - { - this._systemMsg( - 'verbose', - `processSSHPrompt: SSH password prompt: ${this.sshObj.passwordPrompt}` - ); - } - if (this.sshObj.server.hasOwnProperty('passPhrase')) - { - this._systemMsg( - 'verbose', - `processSSHPrompt: SSH passphrase prompt: ${this.sshObj.passphrasePrompt}` - ); - } - this._systemMsg( - 'verbose', - `processSSHPrompt: SSH standard prompt: ${this.sshObj.standardPrompt}` - ); - } - - this._commandInFlight = false; - return this._runExit(); - } - } else { - this._systemMsg( - 'debug', - `processSSHPrompt: Post authentication prompt detection` - ); - - if (standardPrompt) { - this._systemMsg('debug', `processSSHPrompt: SSH complete: normal prompt`); - - if (this.sshObj.showBanner) { - this.sshObj.sessionText += `\n ${response}`; - } - this._commandInFlight = false; - this.sshObj.exitCommands.push('exit'); - this.emit('msg', `${this.sshObj.connectedMessage}`); - this.emit('msg', `${this.sshObj.readyMessage}`); - this._systemMsg('debug', `processSSHPrompt: next command`); - - this.sshObj.sshToNextHost = false; - return this._nextCommand(); - } else if (passwordPrompt || passphrasePrompt) { - // Password or passphrase detected a second time after authentication - // indicates failure. - this.emit( - 'msg', - `SSH authentication failed` - ); - this._systemMsg('debug', `processSSHPrompt: Authentication failed`); - - this._systemMsg('verbose',`processSSHPrompt: failed response: ${response}`); - - this._commandInFlight = false; - this.sshObj.sshAuth = false; - let using; - switch (true) { - case passwordPrompt: - using = `SSH password: ${this.sshObj.server.password}`; - break; - case passphrasePrompt: - using = `SSH passphrase: ${this.sshObj.server.passPhrase}`; - break; - } - this.emit( - 'error', - `${this.host}: SSH authentication failed for ${this.sshObj.server.userName}@${this.host}`, - 'SSH multi host authentication failure' - ); - - // No connection so drop back to first host settings if there was one. - if (this._connections.length > 0) { - return this._previousHost(); - } - - return this._runExit(); - } - - // Authenticated, but the response is neither a prompt nor a repeated - // credential prompt. Re-arm the idle timer so a silent nested shell - // cannot leave the session with no timer at all. - this._systemMsg( - 'debug', - `processSSHPrompt: No prompt after authentication, reset timeout` - ); - return this._scheduleIdleTimeout(response); - } - } - - _processNotifications() { - // An empty command has nothing to run or report, so skip it and continue - // with the queue instead of leaving the state machine idle. - if (!this.command) { - this._systemMsg('debug', `processNotifications: Empty command, skip`); - return this._nextCommand(); - } - - // This is a message for the sessionText like an echo command in bash. - const sessionNote = this.command.match(/^`(.*)`$/); - if (sessionNote) { - this._systemMsg('debug', `processNotifications: sessionText output`); - - if (this._connections.length > 0) { - this.sshObj.sessionText += `${this.host}: Note: ${sessionNote[1]}${this.sshObj.enter}`; - } else { - this.sshObj.sessionText += `Note: ${sessionNote[1]}${this.sshObj.enter}`; - } - this._systemMsg('verbose', sessionNote[1]); - - return this._nextCommand(); - } - - // This is a message to output in process. - const msgNote = this.command.match(/^msg:(.*)$/); - if (msgNote) { - this._systemMsg('debug', `processNotifications: msg to output`); - - this.emit('msg', `${this._hostPrefix()}Note: ${msgNote[1]}`); - return this._nextCommand(); - } - - this._systemMsg('debug', `processNotifications: Normal Command to run`); - - return this._checkCommand(); - } - - _commandComplete() { - this._progressEnd(); - this._commandInFlight = false; - const rawResponse = this._buffer; - const response = rawResponse.trim(); - // Captured stderr is consumed once per command. It is empty unless the - // host opts in with `captureStderr: true`. - const capturedStderr = - this.sshObj.captureStderr === true - ? (this._stderrBuffer || '').trim() - : ''; - // Check sudo su has been authenticated and add an extra exit command. - if ( - this.command !== '' && - this.command !== 'exit' && - this.sshObj.sshToNextHost !== true - ) { - this._systemMsg('debug',`commandComplete: Raising commandComplete event`); - - this._systemMsg( - 'verbose', - `commandComplete:\nCommand:\n ${this.command}\nResponse: ${response}` - ); - this.sshObj.sessionText += this._mergeStderr(response, capturedStderr); + this._systemMsg( + 'verbose', + `commandComplete:\nCommand:\n ${this.command}\nResponse: ${response}` + ); + this.sshObj.sessionText += this._mergeStderr(response, capturedStderr); // `commandResponse: 'handled'` opts into a response without the echoed // command or trailing prompt. The raw buffer stays available to handlers @@ -1008,10 +1273,15 @@ class SSH2Shell extends Stream { if (sshObj.skipHosts) { // By design: this clears only the current host's own nested queue. // Sibling nested hosts queued on a parent still run, matching the - // documented skipHosts behavior. + // documented skipHosts behavior. The record's lazy copy is the queue + // `_nextHost()` reads, so clear it too. if (Array.isArray(sshObj.hosts)) { sshObj.hosts.length = 0; } + const active = this._activeContext(); + if (active && Array.isArray(active.pendingHosts)) { + active.pendingHosts.length = 0; + } sshObj.skipHosts = false; } @@ -1103,7 +1373,6 @@ class SSH2Shell extends Stream { if (isCommandWrite) { this.sshObj.commandTimeoutAttempt = 0; this.sshObj.retryCommandTimeout = undefined; - this._commandSawData = false; this._stderrBuffer = ''; } @@ -1114,13 +1383,17 @@ class SSH2Shell extends Stream { this._commandInFlight = Boolean(command); const written = this._stream.write(`${command}${this.sshObj.enter}`); - // Opt-in `commandStartTimeout`: arm the idle timer as soon as the command - // is written so a completely silent command still times out. Incoming data - // clears and re-arms it through the normal `_onData` path. + // Arm the idle timer as soon as a command is written. Incoming data resets + // it through `_onData`, and a detected prompt cancels it. This makes a + // silent command time out like any other command that never returns to the + // prompt. The literal `exit` closes the shell, so it has no prompt to wait + // for, and a graceful close is already bounded by the stop/close timer. if ( written !== false && isCommandWrite && - this.sshObj.commandStartTimeout === true + command.length > 0 && + command !== 'exit' && + !this._gracefulClosing ) { if (this.idleTimer) { clearTimeout(this.idleTimer); @@ -1131,9 +1404,11 @@ class SSH2Shell extends Stream { return written; } - // Merge a nested host's text into the primary host's sessionText exactly - // once. Called before exit commands so the text survives even if leaving the - // nested shell times out. + // Merge a nested host's text into its immediate parent's sessionText exactly + // once. Merging one level at a time keeps the text in traversal order: a + // child finalizes before its parent, so the deepest text travels up the + // chain and lands after the parent's own output. The primary host then + // carries the whole subtree. _mergeNestedText(host = this.sshObj) { if (!host || !host.server || !this._connections || this._connections.length === 0) { return false; @@ -1142,13 +1417,34 @@ class SSH2Shell extends Stream { return false; } - const root = this._connections[0]; - if (!root || root === host) { + const active = this._activeContext(); + let parentRecord = null; + + if (active && active.host === host) { + // The active host sits outside the stack; its parent is the last record. + parentRecord = this._connections[this._connections.length - 1]; + } else { + // A host being finalized from the stack has its parent one level up. + const index = this._connections.findIndex( + (record) => (record && record.host ? record.host : record) === host + ); + if (index > 0) { + parentRecord = this._connections[index - 1]; + } else if (index === -1) { + // Legacy callers can put bare host configs on the stack without a + // record for the active host. The last ancestor is still the parent. + parentRecord = this._connections[this._connections.length - 1]; + } + } + + const parent = + parentRecord && parentRecord.host ? parentRecord.host : parentRecord; + if (!parent || parent === host) { return false; } this._mergedHosts.add(host); - root.sessionText += `\n${host.server.host}: ${host.sessionText || ''}`; + parent.sessionText += `\n${host.server.host}: ${host.sessionText || ''}`; return true; } @@ -1163,10 +1459,12 @@ class SSH2Shell extends Stream { } this._finalizedHosts.add(host); - const isPrimary = - !this._connections || - this._connections.length === 0 || - host === this._connections[0]; + // The active host is outside the stack, so the primary is the first + // ancestor's host (or the active host when the stack is empty). Records + // built by older tests may still hold a bare host config. + const rootRecord = this._connections ? this._connections[0] : null; + const root = rootRecord && rootRecord.host ? rootRecord.host : rootRecord; + const isPrimary = !root || host === root; if (!isPrimary) { this._mergeNestedText(host); @@ -1194,12 +1492,16 @@ class SSH2Shell extends Stream { // complete session text. _finalizeRun(reason = null) { const hosts = []; - if (this.sshObj && this.sshObj.server) { + const active = this._activeContext(); + if (active && active.host && active.host.server) { + hosts.push(active.host); + } else if (this.sshObj && this.sshObj.server) { hosts.push(this.sshObj); } if (this._connections) { for (let index = this._connections.length - 1; index >= 0; index -= 1) { - const host = this._connections[index]; + const record = this._connections[index]; + const host = record && record.host ? record.host : record; if (host && host.server) { hosts.push(host); } @@ -1216,27 +1518,31 @@ class SSH2Shell extends Stream { return; } - this._systemMsg('debug',`previousHost: raise end event on current connection: ${this.host}`); - - this._finalizeHost(this.sshObj, 'previous-host'); + const child = this._activeContext(); this._systemMsg( - 'debug', - `previousHost: Check for previous connections and reload its configuration if one exists` + 'debug', + `previousHost: close child connection: ${this.host}` ); - // Remove the outgoing host's handlers before restoring the previous host. - // Without this, a stale commandComplete (or similar) handler keeps firing - // against the new current host and duplicates session text. - this._removeListeners(); - - if (this._connections.length > 0) { - this.sshObj = this._connections.pop(); - this.host = this.sshObj.server.host; - // Reapply the previous host's timer config over the base restored by - // _removeListeners. - this._applyHostTimerValues(); - this._systemMsg('debug',`previousHost: previous host loaded: ${this.host} `); - + if (child) { + // Closing the child removes its handlers and finalizes it exactly once. + this._closeContext(child, 'previous-host'); + this._popContext(); + this._systemMsg('debug', `previousHost: previous host loaded: ${this.host}`); + } else if (this._connections.length > 0) { + // Fallback for callers that built the stack manually. The record form is + // the supported one. + this._finalizeHost(this.sshObj, 'previous-host'); + this._removeListeners(); + const parent = this._connections.pop(); + const parentHost = parent && parent.host ? parent.host : parent; + if (parent && parent.host) { + this._restoreContext(parent); + } else if (parentHost) { + this.sshObj = parentHost; + this.host = parentHost.server.host; + } + this._systemMsg('debug', `previousHost: previous host loaded: ${this.host}`); } return this._runExit(); @@ -1247,52 +1553,67 @@ class SSH2Shell extends Stream { return; } - this._removeListeners(); - const nextHost = this.sshObj.hosts.shift(); + // The outgoing record is still active; its handlers must go before the + // child's config replaces the aliases. `pendingHosts` is the record's own + // copy, so the caller's nested array is never consumed. + const parent = this._activeContext(); + if (!parent) { + // Without an active record there is no connection to hop from. Terminate + // instead of recursing through `_runExit()`. + return this._callFinalCallback(); + } + + this._removeListeners(parent); + const pending = this._pendingHosts(parent); + const nextHost = pending.shift(); + if (!nextHost) { + return this._runExit(); + } + this._systemMsg( - 'debug', - `nextHost: load ${nextHost.server.host} config, prepare and start SSH connection` + 'debug', + `nextHost: hop to ${nextHost.server.host} through ${this.host}` ); - this._connections.push(this.sshObj); this.sshObj = nextHost; this.host = nextHost.server.host; - return this._initiate(this._sshConnect); + return this._initiate(this._connectHop); } _nextPrimaryHost(connect) { if (this._stopping || this._runComplete) { - return; + return this._callFinalCallback(); + } + if (this._hosts.length === 0) { + return this._callFinalCallback(); } - if (this._hosts.length > 0) { - this._systemMsg('debug', `nextPrimaryHost: load next host for ssh2 connection`); - - // Check this is not loading the first primary host before removing - // listeners. - if (this.sshObj.server) { - this._systemMsg('debug', `nextPrimaryHost: end current host ${this.host}`); - - this._finalizeHost(this.sshObj, 'next-primary-host'); - } - - this._systemMsg('debug',`nextPrimaryHost: Load next primary host: ${this.host}`); - - this._removeListeners(); - // A new primary host gets a new connection, so drop the previous host's - // stream reference and nested stack. Otherwise an early error could close - // the old stream or the new host could be mistaken for a nested one. - this._stream = {}; - this._connections = []; - this.sshObj = this._hosts.shift(); - this.host = this.sshObj.server.host; - this._primaryhostSessionText = `${this.host}: `; - this._closing = false; - this._gracefulClosing = false; - this._commandInFlight = false; - return this._initiate(connect); + this._systemMsg('debug', `nextPrimaryHost: load next host for ssh2 connection`); + + // Close the current primary and every active hop before resetting the + // stack, so a new primary never inherits a hop's socket. + if (this._activeContext()) { + this._closeAllContexts('next-primary-host'); + } else if (this.sshObj && this.sshObj.server) { + this._finalizeHost(this.sshObj, 'next-primary-host'); } + + this._progressEnd(); + this._stream = {}; + this.connection = null; + this._connections = []; + this._active = null; + this._primaryEnded = false; + this._buffer = ''; + this._stderrBuffer = ''; + this.sshObj = this._hosts.shift(); + this.host = this.sshObj.server.host; + this._primaryhostSessionText = `${this.host}: `; + this._closing = false; + this._gracefulClosing = false; + this._commandInFlight = false; + return this._initiate(connect); } _runExit() { @@ -1306,37 +1627,37 @@ class SSH2Shell extends Stream { if (this._stopping) { return this._beginStopExit(); } - - // Run the exit commands loaded when a nested ssh shell opens. Merge the - // nested text first so it is captured even if the exit command times out. - if (this.sshObj.exitCommands && this.sshObj.exitCommands.length > 0) { - this._systemMsg( - 'verbose', - `runExit: Queued exit commands: ${this.sshObj.exitCommands.length}` - ); - - this._mergeNestedText(); - this.command = this.sshObj.exitCommands.pop(); - return this._runCommand(this.command); - } else if (!this._gracefulClosing && this.sshObj.hosts && this.sshObj.hosts.length > 0) { - // More hosts to connect to so process the next one. + + // Nested hosts only exist on an active record. A bare `sshObj.hosts` array + // without a record has no connection to hop from, so it must not drive + // navigation here. + const active = this._activeContext(); + const pending = active ? this._pendingHosts(active) : []; + + if (!this._gracefulClosing && pending.length > 0) { + // More nested hosts to connect to so process the next one. this._systemMsg('debug',`runExit: Load next host`); - + return this._nextHost(); - } else if (this._connections && this._connections.length > 0) { + } + + if (this._connections && this._connections.length > 0) { // Leaving last host so load previous host. this._systemMsg('debug',`runExit: load previous host`); - + this.emit('msg', `${this._hostPrefix()}${this.sshObj.closedMessage}`); return this._previousHost(); - } else if (!this._gracefulClosing && this.command === 'exit') { + } + + if (!this._gracefulClosing && this.command === 'exit') { + // The literal `exit` leaves `su` / `sudo -i` or the primary shell. A hop + // is left by closing its connection, not by an exit command. this._systemMsg('debug',`runExit: run exit command`); - + return this._runCommand('exit'); - // Nothing more to do so end the stream with last exit. - } else { - return this.close(); } + + return this.close(); } // --------------------------------------------------------------------------- @@ -1364,23 +1685,29 @@ class SSH2Shell extends Stream { } // Clear every command and host queue, including the private primary-host - // queue and nested queues queued on parents. The library's exit commands are - // deliberately kept so a nested shell can be left cleanly. - const clearQueues = (host) => { - if (!host) { + // queue and the nested queues held by the active record and its ancestors. + const clearRecord = (record) => { + if (!record) { return; } + const host = record.host || record; if (Array.isArray(host.commands)) { host.commands.length = 0; } if (Array.isArray(host.hosts)) { host.hosts.length = 0; } + if (Array.isArray(record.pendingHosts)) { + record.pendingHosts.length = 0; + } }; - clearQueues(this.sshObj); + clearRecord(this._activeContext()); + if (!this._activeContext() && this.sshObj) { + clearRecord({ host: this.sshObj }); + } if (Array.isArray(this._connections)) { - for (const host of this._connections) { - clearQueues(host); + for (const record of this._connections) { + clearRecord(record); } } this._hosts.length = 0; @@ -1390,7 +1717,7 @@ class SSH2Shell extends Stream { if (this._commandInFlight) { // Interrupt the running command and wait for the prompt or the idle - // timeout before running the exit commands. + // timeout before closing the records. this._armStopTimer(); if (this._hasLiveStream()) { this._stream.write('\x03'); @@ -1414,23 +1741,11 @@ class SSH2Shell extends Stream { return; } - if (!this._hasLiveStream()) { - return this._finishStop(); - } - - const exitCommands = this.sshObj && Array.isArray(this.sshObj.exitCommands) - ? this.sshObj.exitCommands - : []; - - if (exitCommands.length > 0) { + // A command that is still in flight gets the stop timer and the Ctrl-C + // already sent by stop(). The prompt (or the timer) reaches _finishStop(). + if (this._commandInFlight && this._hasLiveStream()) { this._armStopTimer(); - this.command = exitCommands.pop(); - this._systemMsg('debug', `stop: run queued exit command`); - const written = this._runCommand(this.command); - if (written === false) { - return this._finishStop(); - } - return written; + return; } return this._finishStop(); @@ -1446,17 +1761,13 @@ class SSH2Shell extends Stream { this._commandInFlight = false; this._closing = true; this._runComplete = true; - this._finalizeRun(this._stopReason || 'stop'); - - if (this._hasLiveStream()) { - this._stream.close(); - return this._allSessions; - } - if (this.connection && typeof this.connection.end === 'function') { - this.connection.end(); - return this._allSessions; - } + // Closing every record finalizes each host once, deepest-first. + this._closeAllContexts(this._stopReason || 'stop'); + this._active = null; + this._connections = []; + this._stream = {}; + this.connection = null; return this._callFinalCallback(); } @@ -1485,25 +1796,32 @@ class SSH2Shell extends Stream { } } - // Graceful close runs queued exit commands and backs out of nested shells - // before closing. Remaining primary hosts still run, matching close()'s - // compatibility contract. + // Graceful close drops queued commands and nested hosts, then backs out of + // the active records before closing. Remaining primary hosts still run, + // matching close()'s compatibility contract. _prepareGracefulClose() { - const clearQueues = (host) => { - if (!host) { + const clearRecord = (record) => { + if (!record) { return; } + const host = record.host || record; if (Array.isArray(host.commands)) { host.commands.length = 0; } if (Array.isArray(host.hosts)) { host.hosts.length = 0; } + if (Array.isArray(record.pendingHosts)) { + record.pendingHosts.length = 0; + } }; - clearQueues(this.sshObj); + clearRecord(this._activeContext()); + if (!this._activeContext() && this.sshObj) { + clearRecord({ host: this.sshObj }); + } if (Array.isArray(this._connections)) { - for (const host of this._connections) { - clearQueues(host); + for (const record of this._connections) { + clearRecord(record); } } } @@ -1539,20 +1857,25 @@ class SSH2Shell extends Stream { this._closing = true; this._progressEnd(); this._systemMsg('debug',`Stream: close`); - this._finalizeRun('close'); - if (this._hasLiveStream()) { - const result = this._stream.close(); - // Unit tests and embedders can supply a stream without a client. Without - // a connection no `close` event will arrive, so finish here. - if (!this.connection) { - this._callFinalCallback(); - } - return result; - } - if (this.connection && typeof this.connection.end === 'function') { - return this.connection.end(); + // Close the active record and every ancestor. `_closeContext` finalizes + // each host once and closes its stream/connection. + this._closeAllContexts('close'); + this._active = null; + this._connections = []; + this._stream = {}; + this.connection = null; + + // A plain close() still honours the primary-host contract: remaining + // primaries run. Advance directly because the records are already closed + // and their close events are suppressed. + if (!this._stopping && !this._runComplete && this._hosts.length > 0) { + this._closing = false; + this._primaryEnded = false; + return this.emit('newPrimaryHost', this._nextPrimaryHost(this._connect)); } + + this._runComplete = true; return this._callFinalCallback(); } @@ -1607,7 +1930,6 @@ class SSH2Shell extends Stream { this._stopping = false; this._stopReason = null; this._commandInFlight = false; - this._commandSawData = false; this._stderrBuffer = ''; this._inCommandComplete = false; this._runComplete = false; @@ -1616,69 +1938,62 @@ class SSH2Shell extends Stream { this._finalizedHosts = new Set(); this._mergedHosts = new Set(); this._connections = []; + this._active = null; + this._primaryEnded = false; this._stream = {}; + this.connection = null; + this.sshObj = {}; + this.host = 'No host'; + this._buffer = ''; this._allSessions = ''; this._primaryhostSessionText = ''; } - _removeListeners() { - this._progressEnd(); - this._systemMsg('debug',`removeListeners: removing event listeners linked to the host`); - - if ( - typeof this.sshObj.onKeyboardInteractive === 'function' || - typeof this._boundListeners['keyboard-interactive'] === 'function' - ){ - this._detachListener('keyboard-interactive', 'onKeyboardInteractive'); - } - if (typeof this.sshObj.onStderrData === 'function'){ - this._detachListener('stderrData', 'onStderrData'); - } - if (typeof this.sshObj.onData === 'function'){ - this._detachListener('data', 'onData'); - } - if (typeof this.sshObj.onEnd === 'function'){ - this._detachListener('end', 'onEnd'); - } - if (typeof this.sshObj.onCommandProcessing === 'function'){ - this._detachListener('commandProcessing', 'onCommandProcessing'); - } - if (typeof this.sshObj.onCommandComplete === 'function'){ - this._detachListener('commandComplete', 'onCommandComplete'); + // Removes only the handlers a record bound, plus that record's timers. Host + // handlers are owned by the record, never by `this.sshObj`: an ancestor event + // can arrive while a child is active. Instance defaults stay attached. + _removeListeners(context = this._activeContext()) { + if (!context) { + return; } - if (typeof this.sshObj.onCommandTimeout === 'function'){ - this._detachListener('commandTimeout', 'onCommandTimeout'); + + this._systemMsg( + 'debug', + `removeListeners: removing event listeners linked to ${context.host ? context.host.server.host : 'host'}` + ); + + if (context.listeners) { + // Keep the map: restoring an ancestor after a hop needs the exact + // handlers that host bound. Only the emitter attachment is removed. + for (const [eventName, listener] of Object.entries(context.listeners)) { + if (typeof listener === 'function') { + this.removeListener(eventName, listener); + } + } } - if (typeof this.sshObj.onError === 'function'){ - this._detachListener('error', 'onError'); + + if (context.idleTimer) { + clearTimeout(context.idleTimer); + context.idleTimer = null; } - if ( - typeof this.sshObj.msg === 'function' || - typeof this._boundListeners['msg'] === 'function' - ){ - this._detachListener('msg', 'msg'); - } - // Keep a message sink for _systemMsg between leaving this host and loading - // the next one. _loadDefaults swaps in a host handler when one exists. - this._boundListener('msg', this.msg); - - if (this.idleTimer) { - clearTimeout(this.idleTimer); + if (context.dataReceivedTimer) { + clearTimeout(context.dataReceivedTimer); + context.dataReceivedTimer = null; } - if (this.dataReceivedTimer) { - clearTimeout(this.dataReceivedTimer); + if (context === this._activeContext()) { + if (this.idleTimer) { + clearTimeout(this.idleTimer); + this.idleTimer = null; + } + if (this.dataReceivedTimer) { + clearTimeout(this.dataReceivedTimer); + this.dataReceivedTimer = null; + } } - // Roll timer values back to the instance base so one host's override does - // not leak into the next host. - if (this._baseIdleTime !== undefined) { - this.idleTime = this._baseIdleTime; - } - if (this._baseDataIdleTime !== undefined) { - this.dataIdleTime = this._baseDataIdleTime; - } - - return; + // Keep a message sink available between hosts. `_loadDefaultListeners` + // restores the fallback only when the active record has no host `msg`. + this._loadDefaultListeners(); } _initiate(action) { @@ -1686,8 +2001,6 @@ class SSH2Shell extends Stream { return; } - this._loadDefaults(); - if (typeof action === 'function') { return action(); } @@ -1708,11 +2021,11 @@ class SSH2Shell extends Stream { // Applies a host's timer config only when it supplies a valid value, so an // instance value is not overwritten by the defaults. - _applyHostTimerValues() { + _applyHostTimerValues(host = this.sshObj) { // `idleTimeOut` is the documented key; `idleTime` is a legacy alias. const idleTimeOut = - toPositiveNumber(this.sshObj.idleTimeOut) || - toPositiveNumber(this.sshObj.idleTime); + toPositiveNumber(host.idleTimeOut) || + toPositiveNumber(host.idleTime); if (idleTimeOut > 0) { this.idleTime = idleTimeOut; } @@ -1720,112 +2033,135 @@ class SSH2Shell extends Stream { // Public key is `dataIdleTimeOut` (README). Keep the undocumented // `dataIdleTime` as a fallback for existing callers. const dataIdleTimeOut = - toPositiveNumber(this.sshObj.dataIdleTimeOut) || - toPositiveNumber(this.sshObj.dataIdleTime); + toPositiveNumber(host.dataIdleTimeOut) || + toPositiveNumber(host.dataIdleTime); if (dataIdleTimeOut > 0) { this.dataIdleTime = dataIdleTimeOut; } } - _loadDefaults() { + // Loads a host's defaults and binds its handlers to the record that owns + // them. When no record is supplied, the active one is used; direct calls + // before a connection (unit tests and embedders) create the primary record. + _loadDefaults(context = null) { + let record = context || this._activeContext(); + // A direct call (tests and embedders) can set `sshObj` without creating a + // record. Treat that as a new primary config rather than reusing the + // previous record's host. + if (!record || (!context && record.host !== this.sshObj)) { + record = this._pushContext(this.sshObj, null); + } + + const host = record.host || this.sshObj; + this.sshObj = host; + this.host = host.server ? host.server.host : 'No host'; + this._progressEnd(); this.command = ''; this._buffer = ''; - this._commandSawData = false; this._stderrBuffer = ''; - this.debug = this.sshObj.debug ?? false; - this.verbose = this.sshObj.verbose ?? false; - this.progress = this.sshObj.progress !== false; - this.exposeCredentials = this.sshObj.exposeCredentials ?? false; - this.host = this.sshObj.server.host; + this.debug = host.debug ?? false; + this.verbose = host.verbose ?? false; + this.progress = host.progress !== false; + this.exposeCredentials = host.exposeCredentials ?? false; // Remember that this session uses nested hosts even after the queue has // been consumed, so message prefixes stay consistent. - if (Array.isArray(this.sshObj.hosts) && this.sshObj.hosts.length > 0) { + if (Array.isArray(host.hosts) && host.hosts.length > 0) { this._multipleHosts = true; } // Support the legacy { send: fn } message handler shape. - if ( - this.sshObj.msg && - this.sshObj.msg.send && - typeof this.sshObj.msg.send === 'function' - ) { - this.sshObj.msg = this.sshObj.msg.send; + if (host.msg && host.msg.send && typeof host.msg.send === 'function') { + host.msg = host.msg.send; } - if (typeof this._boundListeners['msg'] === 'function') { - this._detachListener('msg', 'msg'); - } - if (typeof this.sshObj.msg === 'function') { - this._boundListener('msg', this.sshObj.msg); - } else { - this._boundListener('msg', this.msg); + // A host `msg` handler replaces the instance fallback while the record is + // active. `_removeListeners` restores the fallback when the record leaves. + const previousMsg = record.listeners.msg; + if (previousMsg && previousMsg !== host.msg) { + this.removeListener('msg', previousMsg); + delete record.listeners.msg; + } + if (typeof host.msg === 'function') { + if (this.listeners('msg').includes(this.msg)) { + this.removeListener('msg', this.msg); + } + this._bindHostListener(record, 'msg', host.msg); + } else if (!this.listeners('msg').includes(this.msg)) { + this.on('msg', this.msg); } this._systemMsg('debug',`Load Defaults`); - - applyHostDefaults(this.sshObj); - this._captureBaseTimerValues(); - this._applyHostTimerValues(); + applyHostDefaults(host); - // Keep the instance base when no host value was supplied; only repair an - // invalid current value. - if (!(toPositiveNumber(this.idleTime) > 0)) { - this.idleTime = this._baseIdleTime; - } - if (!(toPositiveNumber(this.dataIdleTime) > 0)) { - this.dataIdleTime = this._baseDataIdleTime; - } + this._captureBaseTimerValues(); + // Every host starts from the instance base; only a valid host value + // overrides it. This keeps one host's timers from leaking into the next. + this.idleTime = this._baseIdleTime; + this.dataIdleTime = this._baseDataIdleTime; + this._applyHostTimerValues(host); + record.idleTime = this.idleTime; + record.dataIdleTime = this.dataIdleTime; // Compile ASCII Filter with Safe Fallback. These compiled regexes are // internal state, not public config: recompile from the current host on // every load so a later host with different filters/prompts is honoured. - const ascii = compileAsciiFilter(this.sshObj.asciiFilter); + const ascii = compileAsciiFilter(host.asciiFilter); this.asciiFilter = ascii.filter; if (ascii.usedFallback && this.debug) { this._systemMsg( 'debug', - `loadDefaults: AsciiFilter: incorrect regular expression reverting to default: ${this.sshObj.asciiFilter}` + `loadDefaults: AsciiFilter: incorrect regular expression reverting to default: ${host.asciiFilter}` ); } // Compile Text Color Filter with Safe Fallback. - const color = compileTextColorFilter(this.sshObj.textColorFilter); + const color = compileTextColorFilter(host.textColorFilter); this.textColorFilter = color.filter; if (color.usedFallback && this.debug) { this._systemMsg( 'debug', - `loadDefaults: TextColorFilter: incorrect regular expression reverting to default: ${this.sshObj.textColorFilter}` + `loadDefaults: TextColorFilter: incorrect regular expression reverting to default: ${host.textColorFilter}` ); } // Prompts: fully sanitized at runtime via escapeRegex (never need // fallbacks because they are cast as pure literals). - const prompts = compilePrompts(this.sshObj); + const prompts = compilePrompts(host); this.passwordPrompt = prompts.passwordPrompt; - this.passphrasePrompt = prompts.passphrasePrompt; this.standardPrompt = prompts.standardPrompt; if (prompts.standardPromptFallback) { this._systemMsg( 'debug', - `loadDefaults: StandardPromptRegex: incorrect regular expression reverting to standardPrompt: ${this.sshObj.standardPromptRegex}` + `loadDefaults: StandardPromptRegex: incorrect regular expression reverting to standardPrompt: ${host.standardPromptRegex}` ); } + // Store the compiled state on the record so restoring an ancestor after a + // child closes does not keep the child's prompts or filters. + record.standardPrompt = this.standardPrompt; + record.passwordPrompt = this.passwordPrompt; + record.asciiFilter = this.asciiFilter; + record.textColorFilter = this.textColorFilter; + record.debug = this.debug; + record.verbose = this.verbose; + record.progress = this.progress; + record.exposeCredentials = this.exposeCredentials; + // Listener defaults for command processing. - this.sshObj.onCommandProcessing = - this.sshObj.onCommandProcessing ?? + host.onCommandProcessing = + host.onCommandProcessing ?? ((command, response, sshObj, stream) => {}); - - this.sshObj.onCommandComplete = - this.sshObj.onCommandComplete ?? + + host.onCommandComplete = + host.onCommandComplete ?? ((command, response, sshObj) => { this._systemMsg('debug', `onCommandComplete:`); }); - this.sshObj.onCommandTimeout = - this.sshObj.onCommandTimeout ?? + host.onCommandTimeout = + host.onCommandTimeout ?? ((command, response, stream, connection, details) => { // With `commandTimeoutRetries` configured, only the final attempt // closes the run. The library re-arms the timer for earlier attempts. @@ -1839,7 +2175,7 @@ class SSH2Shell extends Stream { response = response.replace(this.command, ''); this._systemMsg('debug', `loadDefaults: Class.commandTimeout`); - + this._systemMsg('verbose',`loadDefaults: Timeout command: ${command} response: ${response}`); this.emit( @@ -1854,36 +2190,67 @@ class SSH2Shell extends Stream { ); }); - // Explicitly cache references right before binding them to the event emitter - if (typeof this.sshObj.onKeyboardInteractive === 'function') { - this._boundListener('keyboard-interactive', this.sshObj.onKeyboardInteractive); + // Bind the host handlers into the record. They are removed with the same + // record on a host switch, failure, or teardown. + if (typeof host.onKeyboardInteractive === 'function') { + this._bindHostListener(record, 'keyboard-interactive', host.onKeyboardInteractive); } - if (typeof this.sshObj.onError === 'function') { + if (typeof host.onError === 'function') { // Host handlers run before the default listener so they can observe the // error before the default listener closes the stream. - this._boundListener('error', this.sshObj.onError, true); + this._bindHostListener(record, 'error', host.onError, true); } - if (typeof this.sshObj.onData === 'function') { - this._boundListener('data', this.sshObj.onData); + if (typeof host.onData === 'function') { + this._bindHostListener(record, 'data', host.onData); } - if (typeof this.sshObj.onStderrData === 'function') { - this._boundListener('stderrData', this.sshObj.onStderrData); + if (typeof host.onStderrData === 'function') { + this._bindHostListener(record, 'stderrData', host.onStderrData); } - if (typeof this.sshObj.onEnd === 'function') { - this._boundListener('end', this.sshObj.onEnd); + if (typeof host.onEnd === 'function') { + this._bindHostListener(record, 'end', host.onEnd); } - - this._boundListener('commandProcessing', this.sshObj.onCommandProcessing); - this._boundListener('commandComplete', this.sshObj.onCommandComplete); + this._bindHostListener(record, 'commandProcessing', host.onCommandProcessing); + this._bindHostListener(record, 'commandComplete', host.onCommandComplete); + this._bindHostListener(record, 'commandTimeout', host.onCommandTimeout); - this._boundListener('commandTimeout', this.sshObj.onCommandTimeout); + // The tryKeyboard fallback belongs to the record that set it. It is only + // installed when no host or instance handler exists, because two handlers + // would both call finish() and reset the handshake. + if ( + host.server && + host.server.tryKeyboard && + typeof host.onKeyboardInteractive !== 'function' && + this.listeners('keyboard-interactive').length === 0 + ) { + const keyboardInteractive = ( + name, + instructions, + instructionsLang, + prompts, + finish + ) => { + this._systemMsg('debug', `keyboard-interactive:`); + + this._systemMsg('verbose', `name: ${name}`); + this._systemMsg('verbose', `instructions: ${instructions}`); + + const responses = prompts.map((prompt) => { + this._systemMsg('verbose', `prompts: ${prompt.prompt}`); + return ''; // Baseline fallback response + }); + this._systemMsg('verbose', `Prompts object: ${responses}`); + // The handshake stalls unless finish() receives an array of strings. + finish(responses); + }; + this._bindHostListener(record, 'keyboard-interactive', keyboardInteractive); + } this._loadDefaultListeners(); this._systemMsg('debug',`loadDefaults: Host loaded`); - - this._systemMsg('verbose', 'loadDefaults: Config:', this.sshObj); + + this._systemMsg('verbose', 'loadDefaults: Config:', host); } connect(callback) { @@ -1897,18 +2264,144 @@ class SSH2Shell extends Stream { return this.emit('newPrimaryHost', this._nextPrimaryHost(this._connect)); } - _connect() { + // The only connection method. `parent === null` opens a primary host; a + // parent record opens a hop through `parent.connection.forwardOut`. Both + // paths share `_openClient()` and `_openShell()`, so there is one command + // engine, one set of handlers, and one close policy. + _connect(parent = null) { if (this._stopping || this._runComplete) { - return; + return this._stream; } - this.connection = new this.ssh2Client(); + const host = this.sshObj; + const context = this._pushContext(host, parent || null); + const server = this._normalizeServer(host.server); + // Defaults belong to the record, so they are loaded after the record + // exists and before the client is opened. + this._loadDefaults(context); + + if (!host.server) { + if (context.isPrimary) { + return this._reportMissingParameters(); + } + this._hopFailed(context, new Error('Missing connection parameters')); + return this._stream; + } - this.connection.on( + if (context.isPrimary) { + this._systemMsg('debug', `Connect: primary`); + return this._openClient(context, server); + } + + const parentConnection = parent && parent.connection; + if (!parentConnection || typeof parentConnection.forwardOut !== 'function') { + this._hopFailed(context, new Error('No parent connection for host hop')); + return this._stream; + } + this._systemMsg('debug', `Connect: forwardOut`); + parentConnection.forwardOut( + '127.0.0.1', + 0, + server.host, + Number(server.port) || 22, + (err, channel) => { + if (context.closed || context.failing) { + if (channel && typeof channel.close === 'function') { + try { + channel.close(); + } catch (e) { + // The channel may already be gone. + } + } + return; + } + + if (err) { + return this._hopFailed(context, err); + } + + if (this._stopping || this._runComplete || this._closing) { + if (channel && typeof channel.close === 'function') { + try { + channel.close(); + } catch (e) { + // The channel may already be gone. + } + } + // The child record is already active. Close it and restore the + // parent so a stop/close during forwardOut does not leave a + // half-open stack. + return this._failContext( + context, + new Error('Connection cancelled'), + 'cancelled' + ); + } + + return this._openClient( + context, + Object.assign({}, server, { sock: channel }) + ); + } + ); + + return this._stream; + } + + // Readability alias used by `_nextHost()`. The transport branch lives in + // `_connect()`. + _connectHop() { + const parent = this._activeContext(); + if (!parent || !parent.connection) { + this.emit('error', 'No parent connection for host hop', 'Hop', false); + return this._callFinalCallback(); + } + return this._connect(parent); + } + + // Shared tail for primary connections and hops. The only difference is the + // `sock` option a hop supplies. + _openClient(context, options) { + context.connection = new this.ssh2Client(); + this.connection = context.connection; + this._bindConnection(context); + + try { + context.connection.connect(options); + } catch (err) { + if (context.isPrimary) { + // A synchronous throw has no guaranteed `close` event, so report it + // and advance the primary here. + this.emit( + 'error', + `${err} ${err.stack}`, + 'Connection.connect', + this._hasLiveStreamFor(context), + null, + context + ); + return this._failContext(context, err, 'connect-throw'); + } + return this._hopFailed(context, err); + } + + return this._stream; + } + + // Attaches the transport handlers to one record. Every handler closes over + // `context`, so a late event from an ancestor cannot act on the active + // child. + _bindConnection(context) { + const connection = context.connection; + + connection.on( 'keyboard-interactive', (name, instructions, instructionsLang, prompts, finish) => { + if (context.closed || context !== this._activeContext()) { + return; + } this._systemMsg('debug', `Connection.keyboard-interactive`); - + this.emit( 'keyboard-interactive', name, @@ -1920,171 +2413,223 @@ class SSH2Shell extends Stream { } ); - this.connection.on('connect', () => { - this._systemMsg('debug',`connect: Connection.connect`); - - this.emit('msg', this.sshObj.connectedMessage); + connection.on('connect', () => { + if (context.closed) { + return; + } + this._systemMsg('debug', `connect: Connection.connect`); + this.emit('msg', context.host.connectedMessage); }); - this.connection.on('ready', () => { - this._systemMsg('debug',`connect: Connection.ready`); - - this.emit('msg', this.sshObj.readyMessage); - - // Open a shell. - this.connection.shell( - this.sshObj.window, - { pty: this.sshObj.pty }, - (err, stream) => { - this._stream = stream; - if (err instanceof Error) { - this.emit('error', err, 'Shell', this._hasLiveStream()); - return; - } - this._systemMsg('debug', `connect: Connection.shell`); - - this._stream.setEncoding(this.sshObj.streamEncoding); - - this._stream.on('error', (err) => { - this._systemMsg('debug', `connect: Stream.error`); - - this.emit('error', err, 'Stream', true); - }); - - this._stream.stderr.on('data', (data) => { - this._systemMsg('debug', `connect: Stream.stderr.data`); - - // Opt-in capture happens before the event so a handler can rely on - // the buffer being current. The event still fires either way. - this._captureStderr(data); - this.emit('stderrData', data); - }); - - this._stream.on('data', (data) => { - try { - this.emit('data', data); - } catch (e) { - const err = new Error(`${e} ${e.stack}`); - err.level = 'Data handling'; - this.emit('error', err, 'Stream.read error', true); - } - }); - - this._stream.on('finish', () => { - this._progressEnd(); - this._systemMsg('debug', `connect: Stream.finish`); - - // Finalize through the same path as close/connection close so the - // text is appended and `end` fires exactly once per host. - this._finalizeHost(this.sshObj, 'stream-finish'); - }); - - this._stream.on('close', (code, signal) => { - this._progressEnd(); - this._systemMsg('debug', `connect: Stream.close`); - - if (this.connection && typeof this.connection.end === 'function') { - this.connection.end(); - } - }); - } - ); + connection.on('ready', () => { + if (context.closed || context.failing) { + return; + } + this._systemMsg('debug', `connect: Connection.ready`); + this.emit('msg', context.host.readyMessage); + return this._openShell(context); }); - this.connection.on('error', (err) => { - this._systemMsg('debug',`connect: Connection.error`); - - // Before the shell opens there is no live stream to close, so report the - // error without terminating. Once a shell exists, the connection error - // is a terminator. - this.emit('error', err, 'Connection', this._hasLiveStream()); + connection.on('error', (err) => { + if (context.closed || context.failing) { + return; + } + this._systemMsg('debug', `connect: Connection.error`); + + if (context.isPrimary) { + // Before the shell opens there is no live stream to close, so report + // the error without terminating. ssh2 follows a connection error with + // `close`, which advances the primary. + this.emit( + 'error', + err, + 'Connection', + this._hasLiveStreamFor(context), + null, + context + ); + return; + } + + // A failed hop connection is contained to that host and its subtree. + return this._hopFailed(context, err); }); - this.connection.on('close', (had_error) => { + connection.on('close', (had_error) => { this._progressEnd(); - this._systemMsg('debug',`connect: Connection.close`); - - if (this.idleTimer) { - clearTimeout(this.idleTimer); - } - if (this.dataReceivedTimer) { - clearTimeout(this.dataReceivedTimer); + this._systemMsg('debug', `connect: Connection.close`); + + if (context.closed || context.failing) { + return; } - // A transport drop may skip stream `finish`, so finalize the current - // host and any ancestors before reporting the close. This keeps the - // callback text complete even when the last command never returned. - this._finalizeRun( - this._stopping ? this._stopReason : 'connection-close' - ); + if (context.isPrimary) { + // Preserve any partial command output before the host is finalized. + this._appendPartial('connection-close', context.host); - if (had_error) { - const err = new Error('Connection closed with error'); - err.level = 'Connection close'; - err.hadError = had_error; - this.emit('error', err, 'Connection close'); - } else { - const closedMessage = - this.sshObj && this.sshObj.closedMessage - ? this.sshObj.closedMessage - : 'Closed'; - this.emit('msg', closedMessage); - } + if (had_error) { + const err = new Error('Connection closed with error'); + err.level = 'Connection close'; + err.hadError = had_error; + this.emit('error', err, 'Connection close', null, null, context); + } else { + const closedMessage = + context.host && context.host.closedMessage + ? context.host.closedMessage + : 'Closed'; + this.emit('msg', closedMessage); + } - if (this._stopping || this._runComplete) { - return this._callFinalCallback(); + return this._failContext( + context, + had_error ? new Error('Connection closed with error') : null, + this._stopping ? this._stopReason : 'connection-close' + ); } - if (this._hosts.length > 0) { - this._closing = false; - this._gracefulClosing = false; - return this.emit( - 'newPrimaryHost', - this._nextPrimaryHost(this._connect) - ); + // A plain close/stop tears the stack down itself; the child close event + // must not navigate back to the parent. + if (this._closing || this._stopping || this._runComplete) { + return; } - return this._callFinalCallback(); + // An unplanned hop close is a record failure. It is contained: the + // parent's remaining hosts still run. + this._appendPartial('connection-close', context.host); + return this._hopFailed(context, new Error('Connection closed')); }); + } - if (this.sshObj.server && this.sshObj.commands) { - try { - if (!this.sshObj.server.username) { - this.sshObj.server.username = this.sshObj.server.userName; - } - if (!this.sshObj.server.hostHash) { - this.sshObj.server.hostHash = this.sshObj.server.hashMethod; - } - if (!this.sshObj.server.passphrase) { - this.sshObj.server.passphrase = this.sshObj.server.passPhrase; + // Opens the shell for a record and routes its stream events. Inactive + // ancestor streams are ignored so only the active host drives the command + // engine. + _openShell(context) { + const connection = context.connection; + const host = context.host; + + connection.shell(host.window, { pty: host.pty }, (err, stream) => { + if (context.closed || context.failing) { + if (stream && typeof stream.close === 'function') { + try { + stream.close(); + } catch (e) { + // The stream may already be gone. + } } - - this.connection.connect(this.sshObj.server); - } catch (e) { - this.emit( - 'error', - `${e} ${e.stack}`, - 'Connection.connect', - this._hasLiveStream() - ); + return; } - } else { - this.emit( - 'error', - 'Missing connection parameters', - 'Parameters', - false, - function (err, type, close) { - const expose = this.exposeCredentials === true; + + if (err instanceof Error) { + this._systemMsg('debug', `connect: Connection.shell`); + + // ssh2 can hand back a stream alongside the error. Store it on the + // record so teardown closes it instead of leaking the shell. + if (stream) { + context.stream = stream; + if (context === this._activeContext()) { + this._stream = stream; + } + } + + if (context.isPrimary) { this.emit( - 'msg', - expose ? this.sshObj.server : redactCredentials(this.sshObj.server) + 'error', + err, + 'Shell', + this._hasLiveStreamFor(context), + null, + context ); - this.emit('msg', this.sshObj.commands); + return this._failContext(context, err, 'shell'); } - ); - } - return this._stream; + return this._hopFailed(context, err); + } + + context.stream = stream; + if (context === this._activeContext()) { + this._stream = stream; + } + this._systemMsg('debug', `connect: Connection.shell`); + + stream.setEncoding(host.streamEncoding); + + stream.on('error', (err) => { + if (context.closed || context.failing) { + return; + } + this._systemMsg('debug', `connect: Stream.error`); + + if (context.isPrimary) { + this.emit('error', err, 'Stream', true, null, context); + return; + } + return this._hopFailed(context, err); + }); + + stream.stderr.on('data', (data) => { + if (context.closed || context !== this._activeContext()) { + return; + } + this._systemMsg('debug', `connect: Stream.stderr.data`); + + // Opt-in capture happens before the event so a handler can rely on + // the buffer being current. The event still fires either way. + this._captureStderr(data); + this.emit('stderrData', data); + }); + + stream.on('data', (data) => { + if (context.closed || context !== this._activeContext()) { + return; + } + try { + this.emit('data', data); + } catch (e) { + const readError = new Error(`${e} ${e.stack}`); + readError.level = 'Data handling'; + if (context.isPrimary) { + this.emit( + 'error', + readError, + 'Stream.read error', + true, + null, + context + ); + return; + } + return this._hopFailed(context, readError); + } + }); + + stream.on('finish', () => { + if (context.closed) { + return; + } + this._progressEnd(); + this._systemMsg('debug', `connect: Stream.finish`); + + // Finalize through the same path as close/connection close so the + // text is appended and `end` fires exactly once per host. + this._finalizeHost(context.host, 'stream-finish'); + }); + + stream.on('close', (code, signal) => { + this._progressEnd(); + this._systemMsg('debug', `connect: Stream.close`); + + if (context.closed || context.failing) { + return; + } + if (context.connection && typeof context.connection.end === 'function') { + try { + context.connection.end(); + } catch (e) { + // The transport may already be gone. + } + } + }); + }); } } @@ -2096,20 +2641,17 @@ SSH2Shell.prototype.command = ''; SSH2Shell.prototype._hosts = []; SSH2Shell.prototype._primaryHostCount = 1; SSH2Shell.prototype._multipleHosts = false; -SSH2Shell.prototype._sshToNextHost = false; SSH2Shell.prototype._primaryhostSessionText = ''; SSH2Shell.prototype._allSessions = ''; SSH2Shell.prototype._connections = []; SSH2Shell.prototype._stream = {}; SSH2Shell.prototype._buffer = ''; -SSH2Shell.prototype._commandSawData = false; SSH2Shell.prototype._stderrBuffer = ''; SSH2Shell.prototype._boundListeners = {}; SSH2Shell.prototype.idleTime = 5000; SSH2Shell.prototype.asciiFilter = ''; SSH2Shell.prototype.textColorFilter = ''; SSH2Shell.prototype.passwordPrompt = ''; -SSH2Shell.prototype.passphrasePrompt = ''; SSH2Shell.prototype.standardPrompt = ''; SSH2Shell.prototype._callback = function () {}; SSH2Shell.prototype.onCommandProcessing = function () {}; diff --git a/src/ssh2shell/defaults.js b/src/ssh2shell/defaults.js index e67860b..d913bcc 100644 --- a/src/ssh2shell/defaults.js +++ b/src/ssh2shell/defaults.js @@ -3,7 +3,6 @@ // Applies the baseline host defaults in place. This mutates only the host // object; instance-level values (command, buffer, timers) stay in the class. function applyHostDefaults(sshObj) { - sshObj.sshToNextHost = false; if (!sshObj.connectedMessage) { sshObj.connectedMessage = 'Connected'; } @@ -32,11 +31,6 @@ function applyHostDefaults(sshObj) { // changes the second `commandComplete` argument. sshObj.commandResponse = sshObj.commandResponse === 'handled' ? 'handled' : 'raw'; - // Opt-in: arm the command idle timer when the command is written. Without - // this, a command that never produces any output never arms the timer. - if (sshObj.commandStartTimeout !== true) { - sshObj.commandStartTimeout = false; - } // Opt-in: merge stderr into the command response and sessionText. The // `stderrData` event still fires either way. if (sshObj.captureStderr !== true) { @@ -54,9 +48,6 @@ function applyHostDefaults(sshObj) { if (!sshObj.passwordPrompt) { sshObj.passwordPrompt = ':'; } - if (!sshObj.passphrasePrompt) { - sshObj.passphrasePrompt = ':'; - } if (!sshObj.passPromptText) { sshObj.passPromptText = 'Password'; } @@ -73,11 +64,7 @@ function applyHostDefaults(sshObj) { if (sshObj.disableASCIIFilter !== true) { sshObj.disableASCIIFilter = false; } - if (!sshObj.exitCommands) { - sshObj.exitCommands = []; - } sshObj.pwSent = false; - sshObj.sshAuth = false; // Retry budget for command idle timeouts. The library owns the attempt count; // a handler only reacts to the `details` argument. const retries = Number(sshObj.commandTimeoutRetries); @@ -92,7 +79,7 @@ function applyHostDefaults(sshObj) { if (typeof sshObj.sudoFailed !== 'boolean') { sshObj.sudoFailed = false; } - if (sshObj.server.hashKey == null) { + if (sshObj.server && sshObj.server.hashKey == null) { sshObj.server.hashKey = ''; } if (!sshObj.sessionText) { diff --git a/src/ssh2shell/ssh-command.js b/src/ssh2shell/ssh-command.js deleted file mode 100644 index 7b5430b..0000000 --- a/src/ssh2shell/ssh-command.js +++ /dev/null @@ -1,124 +0,0 @@ -'use strict'; - -const { shellControlChars, shellQuote } = require('./util'); - -// Maps a boolean-or-value SSH option to an allow-listed command-line flag. -// `true` selects the documented default; `false`/null/undefined disable it. -function mapSshFlag(value, allowed, defaultValue, name) { - const selected = value === true ? defaultValue : String(value); - if (!allowed.includes(selected)) { - return { error: `Invalid ${name}: ${value}` }; - } - return { flag: ` -${selected}` }; -} - -// Appends one `- ` option after checking for shell control -// characters. Returns an error object instead of throwing so the caller can -// emit a Security Alert without interrupting the connection flow. -function appendSshOption(parts, flag, value, label) { - if (!value) { - return null; - } - if (shellControlChars.test(value)) { - return { error: `Malicious characters detected in SSH ${label}.` }; - } - parts.push(` -${flag} ${shellQuote(value)}`); - return null; -} - -// Builds the `ssh ...` command used to connect to a secondary/nested host. -// Returns `{ error }` for an injection guard, or `{ command }` on success. -function buildSshCommand(sshObj) { - // Add ssh commandline options from host.server.ssh. - let sshFlags = '-x'; - const sshOptions = []; - - if (sshObj.server.ssh) { - // Map protocol/address options to valid ssh flags. `true` keeps the old - // boolean intent by selecting the modern default (IPv4 / protocol 2). - if (sshObj.server.ssh.forceProtocolVersion) { - const protocol = mapSshFlag( - sshObj.server.ssh.forceProtocolVersion, - ['1', '2'], - '2', - 'forceProtocolVersion' - ); - if (protocol.error) { - return protocol; - } - sshFlags += protocol.flag; - } - if (sshObj.server.ssh.forceAddressType) { - const address = mapSshFlag( - sshObj.server.ssh.forceAddressType, - ['4', '6'], - '4', - 'forceAddressType' - ); - if (address.error) { - return address; - } - sshFlags += address.flag; - } - if (sshObj.server.ssh.disablePseudoTTY) { - sshFlags += 'T'; - } - if (sshObj.server.ssh.forcePseudoTTY) { - sshFlags += 't'; - } - if (sshObj.server.ssh.verbose) { - sshFlags += 'v'; - } - - // Intercept and safely escape single-parameter properties. The label is - // used verbatim in the Security Alert message. - const optionSpecs = [ - ['c', 'cipherSpec', 'cipherSpec'], - ['e', 'escape', 'escape sequence'], - ['E', 'logFile', 'logFile path'], - ['F', 'configFile', 'configFile path'], - ['i', 'identityFile', 'identityFile path'], - ['l', 'loginName', 'loginName'], - ['m', 'macSpec', 'macSpec'], - ]; - for (const [flag, key, label] of optionSpecs) { - const failure = appendSshOption( - sshOptions, - flag, - sshObj.server.ssh[key], - label - ); - if (failure) { - return failure; - } - } - - // Validate custom option blocks safely. Only own enumerable properties are - // included, so inherited values cannot leak into the command line. - const options = sshObj.server.ssh.options || {}; - for (const [option, value] of Object.entries(options)) { - if (shellControlChars.test(option) || shellControlChars.test(value)) { - return { error: 'Malicious characters detected in SSH options.' }; - } - const safeOption = String(option).replace(/[^a-zA-Z0-9]/g, ''); - const safeValue = shellQuote(value); - sshOptions.push(` -o ${safeOption}=${safeValue}`); - } - } - - // Wrap target dynamic properties to ensure security boundaries hold up. - sshOptions.push(' -o "StrictHostKeyChecking=no"'); - - // Sanitize user context fields going straight into the string command. - const safePort = String(sshObj.server.port || 22).replace(/[^0-9]/g, ''); - sshOptions.push(` -p ${safePort}`); - - const safeUser = shellQuote(sshObj.server.userName); - const safeHost = shellQuote(sshObj.server.host); - - return { - command: `ssh ${sshFlags} ${sshOptions.join('')} ${safeUser}@${safeHost}`, - }; -} - -module.exports = { buildSshCommand }; diff --git a/src/ssh2shell/util.js b/src/ssh2shell/util.js index 3ceba4c..48278a2 100644 --- a/src/ssh2shell/util.js +++ b/src/ssh2shell/util.js @@ -6,12 +6,6 @@ function escapeRegex(str) { return String(str).replace(/[|\\{}()[\]^$+*?.]/g, '\\$&'); } -function shellQuote(value) { - return "'" + String(value).replace(/'/g, "'\\''") + "'"; -} - -const shellControlChars = /[;&|`$\n\r]/; - // Terminal escape sequences arrive as complete CSI or OSC strings. The ASCII // filter only removes the ESC byte, which leaves the printable payload (for // example `[?2004l` and `]3008;...`) in the response. Remove the whole @@ -88,10 +82,6 @@ function compilePrompts(sshObj) { `${cleanText}[^\\n]*${escapeRegex(sshObj.passwordPrompt || ':')}\\s?$`, 'i' ), - passphrasePrompt: new RegExp( - `${cleanText}[^\\n]*${escapeRegex(sshObj.passphrasePrompt || ':')}\\s?$`, - 'i' - ), standardPrompt: custom.regex || new RegExp(`[${escapeRegex(sshObj.standardPrompt || '>$%#')}]\\s?$`), @@ -169,8 +159,6 @@ module.exports = { escapeRegex, redactCredentials, redactString, - shellControlChars, - shellQuote, stripTerminalEscapes, typeIsArray, }; diff --git a/test/README.md b/test/README.md index a819c37..1e29672 100644 --- a/test/README.md +++ b/test/README.md @@ -38,7 +38,7 @@ Feature-specific suites include `test/unit/prompt-regex.test.js` (`standardPromptRegex`), `test/unit/command-response.test.js` (`commandResponse: 'handled'`), `test/unit/timeout-retries.test.js` (`commandTimeoutRetries`), `test/unit/command-start-timeout.test.js` -(`commandStartTimeout` and `details.noOutput`), and +(always-on command idle timeout), and `test/unit/stderr-capture.test.js` (`captureStderr` and `details.stderr`). Opt-in cases are guarded by `isBaseline()` so the frozen artifact still passes. @@ -54,8 +54,9 @@ cp .env-example .env Most tests authenticate with the key at `PRIVATE_KEY_PATH`. Passwords are used only where the protocol requires them: `sudo`, `su`, and keyboard-interactive. -Nested hops use `HOP_KEY_PATH` and `HOP2_KEY_PATH`, which are paths on the jump -host rather than on your workstation. +Nested hosts are reached with `forwardOut` from the parent connection, so hops +authenticate with the same local `PRIVATE_KEY_PATH`; no key needs to be copied +to the jump host. Run the curated batch after a change: @@ -77,10 +78,77 @@ node scripts/run-live.js simple tunnel chaining node scripts/run-live.js --all --timeout 300 ``` +Live tests and `provision.js` load the build selected by `SSH2SHELL_MODULE`: +`src` (default for development), `lib` (the release build), `baseline` (the +frozen regression fixture), or a path relative to the repository root. For +example: + +```bash +SSH2SHELL_MODULE=lib npm run test:live +SSH2SHELL_MODULE=baseline npm run test:live +``` + `timeout.js` keeps the handler-managed `FirstPass` approach. `timeout_retries.js` uses `commandTimeoutRetries` and `details.final`, so the library owns the attempt count and re-arms the timer. +### Host traversal and fault tests + +Two live tests exercise the host-array shape directly. They are not in the +curated batch because they are the acceptance tests for the +[next-host-connection](../docs/NEXT-HOST-CONNECTION.md) transport change. + +- `host_traversal.js` builds three primaries and reuses the VMs at three depths: + + ```text + host1.hosts = [hosta] hosta.hosts = [hostaa] hostaa.hosts = [hostaaa] + host2.hosts = [hostb,hostc] hostb.hosts = [hostbb] hostc.hosts = [hostcc] + host3.hosts = [hostd,hoste,hostf] + primary list = [host1, host2, host3] + ``` + + Each host writes a unique `traversal: