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/.github/workflows/live.yml b/.github/workflows/live.yml new file mode 100644 index 0000000..e4d24f7 --- /dev/null +++ b/.github/workflows/live.yml @@ -0,0 +1,109 @@ +name: Live tests + +on: + workflow_call: + inputs: + ref: + description: Git ref to test + required: false + type: string + push: + branches: + - master + pull_request: + workflow_dispatch: + schedule: + - cron: '17 3 * * *' + +permissions: + contents: read + +concurrency: + group: live-${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +jobs: + live: + name: Live suite + runs-on: ubuntu-latest + timeout-minutes: 30 + + steps: + - name: Check out + uses: actions/checkout@v4 + with: + ref: ${{ inputs.ref || github.ref }} + + - name: Set up Node + uses: actions/setup-node@v4 + with: + node-version: 24.x + cache: npm + + - name: Install + run: npm ci + + # The private key is gitignored, so each run gets a throwaway pair. The + # setup script installs the public half for the test users. + - name: Generate throwaway SSH key + run: ssh-keygen -q -t ed25519 -N "" -C ssh2shell-ci -f "$RUNNER_TEMP/test_ed25519" + + - name: Start test hosts + run: sudo bash test/ci/setup-live-hosts.sh "$RUNNER_TEMP/test_ed25519.pub" + + # The runner image runs its own sshd on 0.0.0.0:22, so the test hosts use + # 2222 (the setup script's default). Keep these in sync with + # test/ci/setup-live-hosts.sh if LIVE_SSH_PORT is changed. + - name: Run live suite + env: + SSH2SHELL_MODULE: src + HOST: 127.0.0.10 + PORT: '2222' + USER_NAME: tester + PASSWORD: password + PRIVATE_KEY_PATH: ${{ runner.temp }}/test_ed25519 + KEY_PASSPHRASE: '' + EXPECTED_HOST_HASH: '' + SECOND_USER: suuser + SECOND_USER_PASSWORD: secondpassword + NOPASSWD_USER: nopasswd + NOPASSWD_PASSWORD: nopasswdpassword + KBD_USER: kbduser + KBD_PASSWORD: kbdpassword + KBD_HOST: 127.0.0.10 + KBD_PORT: '2222' + SERVER1_HOST: 127.0.0.10 + SERVER1_PORT: '2222' + SERVER1_USER_NAME: tester + SERVER1_PASSWORD: password + SERVER2_HOST: 127.0.0.11 + SERVER2_PORT: '2222' + SERVER2_USER_NAME: tester + SERVER2_PASSWORD: password + SERVER3_HOST: 127.0.0.12 + SERVER3_PORT: '2222' + SERVER3_USER_NAME: tester + SERVER3_PASSWORD: password + run: npm run test:live:all + + # sshd logs are root-owned, and upload-artifact runs as the runner user. + # Copy them into the workspace so the artifact has one readable root. + - name: Collect live logs + if: always() + run: | + mkdir -p test/logs/sshd + sudo cp /var/log/ssh2shell/*.log test/logs/sshd/ 2>/dev/null || true + sudo chown -R "$(id -u):$(id -g)" test/logs + + - name: Upload live logs + if: always() + uses: actions/upload-artifact@v4 + with: + name: live-logs + path: test/logs + if-no-files-found: ignore + retention-days: 7 + + - name: Stop test hosts + if: always() + run: sudo bash test/ci/stop-live-hosts.sh diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index 19cc04b..4153e40 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -19,8 +19,15 @@ concurrency: cancel-in-progress: false jobs: + live: + name: Live suite + uses: ./.github/workflows/live.yml + with: + ref: ${{ inputs.ref || github.ref }} + publish: name: Publish ${{ inputs.ref || github.ref_name }} + needs: live runs-on: ubuntu-latest steps: - name: Check out diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..02b6e34 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,76 @@ +# Changelog + +All notable changes to this project are recorded here. The format follows +[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses +[semantic versioning](https://semver.org/spec/v2.0.0.html). + +Releases before `4.0.0` are recorded as git tags and GitHub Releases. + +## [Unreleased] + +## [4.0.0] - 2026-11-15 + +### Breaking changes + +- **Host hops use `ssh2` `forwardOut` channels.** The nested `ssh` command path + is gone, so a jump host no longer needs an `ssh` client, a shell, or a copy of + your key. `server.ssh` and its options are removed: use `ssh2` connection + options instead (`algorithms` replaces `cipherSpec` / `macSpec`, and + `forceIPv4` / `forceIPv6` replace `forceAddressType`). `exitCommands` is + removed with the command path. +- **`host.msg` is renamed to `host.onMsg`.** The Hubot-era `msg: { send: fn }` + shape is no longer mapped. +- **`server.hashMethod` is removed.** Use `hostHash` or `hostVerifier`. +- **`sshObj.stop` is removed.** Use `abort`. +- **Host `idleTime` and `dataIdleTime` are removed.** Use `idleTimeOut` and + `dataIdleTimeOut`. The instance-level `SSH.idleTime` and `SSH.dataIdleTime` + remain. +- **`commandStartTimeout` and `details.noOutput` are removed.** The command idle + timer is always armed when a command is written, so a silent command times + out. A command that returns to a prompt without output is a normal + completion. +- **`passphrasePrompt` is removed.** Only `passwordPrompt` remains. +- **An empty host list throws.** `new SSH2Shell([])`, `null`, and `undefined` + throw a `TypeError` instead of starting a run with no hosts. +- **Host objects are mutated during a run.** `commands` is consumed, + `sessionText` accumulates, and flags such as `pwSent` and `sudoFailed` are + updated. Create a fresh object, or clone it, before reusing it with another + instance. + +### Added + +- Depth-first hop traversal with sibling hosts. Each hop is a real `ssh2` + connection opened through the parent's `forwardOut` channel, and it is + verified with the same `hostHash` / `hostVerifier` contract as a primary. +- Contained hop failures. A failed hop emits `error` with type `Hop`, skips its + commands and unstarted descendants, and the parent continues with its + remaining hosts. A failed primary is finalized and the next primary runs. +- Per-hop `connectedMessage`, `readyMessage`, and `closedMessage`. +- Provisioning `--print-config` and environment-source logging (development + tooling). + +### Changed + +- The command idle timer is armed when a command is written, not after the + first output, so a command that never produces output still times out. +- Responses are sliced after the last echoed command, which removes earlier + session noise and the garbled-buffer workaround. +- `command` and `_buffer` are record-scoped and restored when backing out of a + hop, so the parent resumes its own command state. +- Host config no longer receives library state: default handlers are resolved + per record instead of being written into the host object, and + `applyHostDefaults` no longer writes `server.hashKey`. + +### Development + +- Added `test/live/host_traversal.js` and `test/live/host_faults.js` as the + acceptance tests for hop traversal and fault containment. +- Added `SSH2SHELL_MODULE` (`src`, `lib`, `baseline`, or a repository-relative + path) to select the build under test for live tests and provisioning. +- Rewrote the provisioning script around the current host API and a documented + `PROVISION_*` environment contract. Re-provisioning removes the 3.x + `~/.ssh/id_ed25519` copies that were only needed by nested `ssh -i` hops. +- `ssh2Client` is now `_ssh2Client` and is documented as an internal test seam. + +[Unreleased]: https://github.com/cmp-202/ssh2shell/compare/v4.0.0...HEAD +[4.0.0]: https://github.com/cmp-202/ssh2shell/compare/v3.3.0...v4.0.0 diff --git a/README.md b/README.md index b31a138..47e9569 100644 --- a/README.md +++ b/README.md @@ -58,6 +58,7 @@ one command to decide what to do next. - [Troubleshooting](#troubleshooting) - [Security](#security) - [Development](#development) +- [Changelog](#changelog) - [License](#license) ## Why ssh2shell @@ -82,6 +83,11 @@ npm install ssh2shell Requires Node.js 18 or newer. +**Upgrading from 3.x:** 4.0.0 is a breaking release. Host hops now use `ssh2` +`forwardOut` connections, `server.ssh` and `exitCommands` are removed, and +several host options were renamed. Read the [4.0.0 changes](./CHANGELOG.md) +before upgrading. + ## Quick start ```javascript @@ -143,7 +149,7 @@ When all hosts finish, `connect(callback)` passes the combined text. | --- | --- | --- | --- | | Single host | `new SSH2Shell(host)` | One `ssh2` connection | You have one server | | Multiple primary hosts | `new SSH2Shell([host1, host2])` | A new `ssh2` connection per host, one after another | You have several independent servers | -| Tunnelling | `host1.hosts = [host2]` | An `ssh` command run inside the current session | You must reach a host through a jump host | +| Tunnelling | `host1.hosts = [host2]` | A new `ssh2` connection through the parent connection's `forwardOut` channel | You must reach a host through a jump host | **Notifications.** `commands` entries can emit a `msg` or add text to `sessionText` without sending anything to the host. See @@ -154,6 +160,12 @@ When all hosts finish, `connect(callback)` passes the combined text. The defaults below are the values used when a property is omitted. Optional properties never need to be included just to keep a default. +`ssh2shell` fills defaults into the host object and keeps runtime state there: +`commands` is consumed as it runs, `sessionText` accumulates output, and +per-host flags such as `pwSent` and `sudoFailed` are updated. Treat a host +config as belonging to one run. Create a fresh object, or clone it, before +reusing it with another instance. + ### `server` `server` is passed to `ssh2.Client.connect()`, so any option that ssh2 accepts @@ -164,18 +176,15 @@ directly. | --- | --- | --- | --- | | `host` | string | — | **Required.** Host name or IP address. | | `port` | number \| string | `22` | SSH port. | -| `userName` | string | — | **Required.** Login name. `username` is accepted as an alias. | +| `userName` | string | — | **Required.** Login name. ssh2's native `username` also works. | | `password` | string | — | Password authentication. | | `privateKey` | Buffer \| string | — | Private key contents, usually from `fs.readFileSync()`. | -| `passPhrase` | string | — | Private-key passphrase. `passphrase` is accepted as an alias. | +| `passPhrase` | string | — | Private-key passphrase. ssh2's native `passphrase` also works. | | `tryKeyboard` | boolean | `false` | Enable keyboard-interactive authentication. | | `hostHash` | string | — | Hash algorithm used to verify the server key. Any algorithm from `crypto.getHashes()` works. `sha256` is a good choice. | | `hostVerifier` | function | — | `(hashedKey, verify) => boolean`. Called with the hashed key when `hostHash` is set. | | `algorithms` | object | — | ssh2 cipher, compression, hmac, kex, and server host key settings. | -`hashMethod` is accepted as a legacy alias for `hostHash`. It is copied to -`hostHash` before the connection is opened. - `hashKey` is **not** used by `ssh2shell` or `ssh2`. Do not set it. ### Commands and notifications @@ -217,8 +226,7 @@ before it is matched and stored. | `standardPrompt` | string | `">$%#"` | Characters that identify a command prompt. Compiled to a regex matching one of these at the end of a line. | | `standardPromptRegex` | string \| RegExp | — | Opt-in full prompt regex. Replaces `standardPrompt` for prompt detection. Anchored to the end; `g`, `y`, and `m` flags are ignored. | | `passwordPrompt` | string | `":"` | Text that identifies a password prompt. | -| `passphrasePrompt` | string | `":"` | Text that identifies a passphrase prompt. | -| `passPromptText` | string | `"Password"` | Text that must appear before the password/passphrase prompt. Shared by both prompt types. | +| `passPromptText` | string | `"Password"` | Text that must appear before the password prompt. | | `commandResponse` | `"raw"` \| `"handled"` | `"raw"` | Shape of the `commandComplete` response. `handled` removes the echoed command and trailing prompt and trims; `details.rawResponse` keeps the raw buffer. `sessionText` stays raw. | | `captureStderr` | boolean | `false` | Merge captured stderr into the `commandComplete` response and `sessionText`. `details.stderr` carries the captured text. `stderrData` still fires. | | `asciiFilter` | string | `"[^\r\n\x20-\x7e]"` | Regex that removes non-standard ASCII. Complete terminal escape sequences are removed first. Tabs are preserved by the compiled default. | @@ -233,7 +241,7 @@ still works, but a prompt ending in `:` will not. If the trailing-character match is too loose, set `standardPromptRegex` to the full prompt, for example `'tester@host:~\\$\\s?$'`. It is anchored to the end automatically and used everywhere `standardPrompt` is: normal command -completion, `sudo`, and nested `ssh` prompts. An invalid pattern falls back to +completion and `sudo` prompts. An invalid pattern falls back to `standardPrompt` and logs a debug message. Treat it as trusted configuration; a pathological pattern can be expensive to evaluate. @@ -264,18 +272,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,18 +301,20 @@ 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 -value overrides the instance value for that host. +`SSH.idleTime` and `SSH.dataIdleTime` can be set on the instance before +`connect()`; a host `idleTimeOut` or `dataIdleTimeOut` overrides the instance +value for that host. ### Messages and debug output @@ -314,7 +323,6 @@ value overrides the instance value for that host. | `connectedMessage` | string | `"Connected"` | Emitted as a `msg` when the connection opens. | | `readyMessage` | string | `"Ready"` | Emitted as a `msg` when the shell is ready. | | `closedMessage` | string | `"Closed"` | Emitted as a `msg` when the connection closes. | -| `msg` | function \| `{ send }` | `console.log` | Receives every `msg` event. The legacy `{ send: fn }` shape is accepted. | | `verbose` | boolean | `false` | Emit process details, including the loaded host config and intermediate values useful for troubleshooting. | | `debug` | boolean | `false` | Emit internal process steps. | | `progress` | boolean | `true` | Write a stderr liveness indicator while a command is in flight. Set to `false` to disable. TTY-only; never affects `sessionText`. | @@ -333,14 +341,19 @@ stream handler, and `onError` runs before the default error handler so it can observe the error before the connection closes. Handlers added to the instance with `SSH.on(...)` run for every host, in parallel with any host handler. +Handlers are called with `this` set to the `SSH2Shell` instance, so +`this.sshObj`, `this.emit()`, `this.close()`, and `this.stop()` are available. +Use a normal `function` when you need `this`; an arrow function captures the +surrounding scope instead. + | Handler | Arguments | Runs when | | --- | --- | --- | -| `msg` | `message` | A message is emitted. | +| `onMsg` | `message` | A message is emitted. Replaces the default `console.log` sink for that host. | | `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 +366,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. @@ -567,10 +580,9 @@ const host = { }; ``` -Fingerprint validation applies to the **primary** connection only. Nested -connections are made by running `ssh` on the primary host, so their host-key -handling belongs to that host's `known_hosts` configuration and to the -`server.ssh` options. See [Security](#security). +Fingerprint validation applies to every connection. A nested host sets its own +`hostHash` / `hostVerifier` on its `server` object, and the hop is verified the +same way as a primary connection. See [Security](#security). See [`test/live/fingerprint.js`](./test/live/fingerprint.js) for a runnable example. @@ -684,7 +696,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. @@ -727,14 +739,6 @@ const host = { }; ``` -If you see garbled text before the real response, save the partial response and -clear the buffer before writing: - -```javascript -this.sshObj.sessionText += response; -this._buffer = ''; -``` - To change timeout handling for every host, leave `onCommandTimeout` out of the host object and listen on the instance: @@ -781,36 +785,39 @@ SSH.connect((allSessionText) => { Each host is independent. Shared functions can be assigned to multiple host objects, and shared handlers can be added to the instance instead. +Pass either a single host object or a non-empty array. An empty array, `null`, +or `undefined` throws a `TypeError` at construction. The array is copied, so it +can be reused across runs. + +If a primary host fails to connect, the run does not end: that host is finalized +and the next primary is attempted. Each primary is tried once, in order. This is +separate from hop containment, where a failed nested host only skips its own +subtree. + See -[`test/live/multiple_primary_hosts.js`](./test/live/multiple_primary_hosts.js). +[`test/live/multiple_primary_hosts.js`](./test/live/multiple_primary_hosts.js) +and [`test/live/host_faults.js`](./test/live/host_faults.js). ### Tunnelling through a jump host Set `hosts` on a host object to connect to further hosts **through** it. Each -nested connection is an `ssh` command run inside the current session, so it uses -the shell of the host you are already on. +nested host is a real `ssh2` connection opened through the parent connection +with `forwardOut`, so the jump host only forwards TCP. It does not need an `ssh` +client, a shell, or a copy of your key. ```javascript const fs = require('fs'); +// Hops authenticate from this process, so the key stays local. +const privateKey = fs.readFileSync(process.env.PRIVATE_KEY_PATH); + const jump = { - server: { - host: '10.0.0.10', - userName: 'deploy', - privateKey: fs.readFileSync(process.env.PRIVATE_KEY_PATH), - }, + server: { host: '10.0.0.10', userName: 'deploy', privateKey }, commands: ['hostname'], }; const target = { - server: { - host: '192.168.1.20', - userName: 'deploy', - ssh: { - // Key as it exists on the jump host, used by the nested `ssh -i`. - identityFile: process.env.HOP_KEY_PATH || '/home/deploy/.ssh/id_ed25519', - }, - }, + server: { host: '192.168.1.20', userName: 'deploy', privateKey }, commands: ['hostname', 'uptime'], }; @@ -820,95 +827,59 @@ const SSH = new SSH2Shell(jump); SSH.connect((sessionText) => console.log(sessionText)); ``` -`identityFile` must be an absolute path on the jump host; the value is -single-quoted, so `~` is not expanded. For multi-hop chains, use -`HOP_KEY_PATH` for the first hop and `HOP2_KEY_PATH` for the second (see -[`test/live/chaining.js`](./test/live/chaining.js)). +`server.host` and `server.port` are the destination the **jump host** connects +to, so names resolve from the jump host's network. Every other connection +setting (`userName`, `password`, `privateKey`, `passPhrase`, `agent`, +`tryKeyboard`, `hostHash` / `hostVerifier`, `algorithms`, `readyTimeout`, +`keepaliveInterval`, and so on) applies to the `ssh2` login for that host and +uses local values. A hop does not inherit the parent's credentials; set them on +each host object. + +There is no `server.ssh` block. Options that used to map to `ssh` flags map to +`ssh2` connection options instead: `algorithms` replaces `cipherSpec` and +`macSpec`, and `forceIPv4` / `forceIPv6` replace `forceAddressType`. See +[Host-to-host connections](./docs/NEXT-HOST-CONNECTION.md) for the full mapping. Nested hosts can be chained to any depth: ```javascript jump.hosts = [bastion]; bastion.hosts = [target]; -target.hosts = []; ``` The process is: 1. Connect to the primary host and run its commands. -2. For each entry in its `hosts` array, save the current host and load the - nested host. -3. Run `ssh` on the current host to reach the nested host. -4. Run the nested host's commands, then process its own `hosts` array. -5. Restore the previous host and continue with its remaining `hosts` entries. -6. Close all sessions and pass the combined text to the callback. - -A nested host object must be defined before it is added to another `hosts` -array. - -**`server.ssh` options.** These options apply only to nested `ssh` connections. -The primary connection uses ssh2 directly. - -```javascript -const host = { - server: { - // ...connection settings - ssh: { - forceProtocolVersion: 2, // 1 or 2; true selects 2 - forceAddressType: 4, // 4 or 6; true selects 4 - disablePseudoTTY: false, // true adds -T - forcePseudoTTY: false, // true adds -t - verbose: false, // true adds -v - cipherSpec: '', // -c - escape: '', // -e - logFile: '', // -E - configFile: '', // -F - identityFile: '', // -i - loginName: '', // -l - macSpec: '', // -m - options: {}, // -o key=value for each entry - }, - }, - commands: ['hostname'], -}; -``` - -| Property | Maps to | Notes | -| --- | --- | --- | -| `forceProtocolVersion` | `-1` / `-2` | `1`, `2`, or `true` (selects `-2`). Any other value raises a Security Alert error. | -| `forceAddressType` | `-4` / `-6` | `4`, `6`, or `true` (selects `-4`). Any other value raises a Security Alert error. | -| `disablePseudoTTY` | `-T` | Disables pseudo-terminal allocation. | -| `forcePseudoTTY` | `-t` | Forces pseudo-terminal allocation. | -| `verbose` | `-v` | Verbose ssh output. | -| `cipherSpec` | `-c` | Cipher specification. | -| `escape` | `-e` | Escape character. | -| `logFile` | `-E` | Log file path. | -| `configFile` | `-F` | Config file path. | -| `identityFile` | `-i` | Identity file path. | -| `loginName` | `-l` | Login name. | -| `macSpec` | `-m` | MAC specification. | -| `options` | `-o key=value` | Each own enumerable entry. Keys are reduced to `[a-zA-Z0-9]`; values are shell-quoted. | - -The nested command is always built as: - -```text -ssh -x -o "StrictHostKeyChecking=no" -p ''@'' -``` - -`userName` and `host` are shell-quoted, and `port` is reduced to digits. -`options` keys and values containing shell control characters are rejected with -a `Security Alert` error. +2. For each entry in its `hosts` array, open a `forwardOut` channel through the + current connection and log in to the nested host over that channel. +3. Run the nested host's commands, then process its own `hosts` array. +4. Close the nested connection, restore the parent, and continue with its + remaining `hosts` entries. +5. Close all connections and pass the combined text to the callback. + +The `hosts` array is copied for the run, so it is not consumed and can be reused +across runs. + +Each hop uses the same host-key contract as the primary: `ssh2` accepts the key +unless `hostHash` / `hostVerifier` is set, and the library never injects +`StrictHostKeyChecking=no`. Set a verifier on a nested host object to pin its +key. + +Connection-level features such as keyboard-interactive work per connection, not +just the primary. Each nested host uses its own `connectedMessage`, +`readyMessage`, and `closedMessage`. -> **Note:** `StrictHostKeyChecking=no` is added to every nested connection. If -> that is not acceptable, enforce host-key policy in the primary host's -> `~/.ssh/config` or `known_hosts`, or avoid tunnelling for those hosts. +`sessionText` stays per host. A nested host's text is merged into its immediate +parent, so the primary ends up with the whole subtree in traversal order. -Connection-level features such as keyboard-interactive apply to the primary -connection only. Each nested host uses its own `connectedMessage`, -`readyMessage`, and `closedMessage`. +If a nested host fails to connect, the failure is contained: the `error` event +fires with type `Hop`, that host's remaining commands and unstarted descendants +are skipped, and the parent continues with its remaining hosts. Other primary +hosts still run. -See [`test/live/tunnel.js`](./test/live/tunnel.js) and -[`test/live/chaining.js`](./test/live/chaining.js). +See [`test/live/tunnel.js`](./test/live/tunnel.js), +[`test/live/tunnel_3_hop.js`](./test/live/tunnel_3_hop.js), and +[`test/live/host_traversal.js`](./test/live/host_traversal.js). ## Events and the API @@ -937,9 +908,9 @@ 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. | +| `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`. A failed host hop uses type `Hop`; the hop is contained and the parent continues. `close` requests a connection close; `callback(err, type)` runs before closing. | | `keyboard-interactive` | `name, instructions, instructionsLang, prompts, finish` | The server requested keyboard-interactive authentication. | `commandComplete` receives the response after the command has been removed from @@ -961,11 +932,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 +1029,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** @@ -1076,7 +1046,7 @@ onCommandProcessing(command, response, sshObj, stream) { closes the shell, then the connection. - Prefer clearing the queues while the shell is usable. Close when the prompt is not recognised and Ctrl-C does not recover, or the connection is compromised. -- Do not call `this.connection.end()` from a handler. Use `close()` so the final +- Do not end the connection directly from a handler. Use `close()` so the final session text is preserved. The full behavior matrix and internal details are in @@ -1086,7 +1056,7 @@ The full behavior matrix and internal details are in ### Log to a file -Set `msg` on the host to send status messages to a file instead of the console, +Set `onMsg` on the host to send status messages to a file instead of the console, and append the final transcript in the callback: ```javascript @@ -1095,7 +1065,7 @@ const log = (text) => fs.appendFileSync('ssh2shell.log', `${text}\n`); const host = { // ... - msg: log, + onMsg: log, }; const SSH = new SSH2Shell(host); @@ -1105,7 +1075,7 @@ SSH.connect((sessionText) => { }); ``` -`msg` receives every message emitted by `ssh2shell`, including the connection +`onMsg` receives every message emitted by `ssh2shell`, including the connection messages and any `msg:` notifications. The callback's `sessionText` is the complete transcript. For live per-command output as the run progresses, enable `verbose`. @@ -1213,24 +1183,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 @@ -1260,8 +1231,8 @@ chunk, so existing stderr handlers keep working. configured password and passphrase replaced with `[REDACTED]`, and object dumps mask `password` and `passphrase` keys. - Credentials are only redacted from `ssh2shell`'s own debug and verbose output. - Your own `msg`, `data`, and `commandComplete` handlers receive raw text and - must redact it if you log it. + Your own `onMsg`, `onData`, and `onCommandComplete` handlers receive raw text + and must redact it if you log it. - Prefer environment variables or a secrets manager over hard-coded passwords in source files. @@ -1283,10 +1254,12 @@ normal `msg` and sets `sshObj.sudoFailed = true`, so it is visible without `sshObj.sudoFailed` in `onCommandComplete`, or set `abortOnSudoFailure: true` to stop the run. -**A nested host fails to authenticate.** Nested connections use the `ssh` -command on the primary host. Confirm that the primary host can reach the target -and that the supplied `userName`, `password`, `passPhrase`, or `identityFile` -works from that host. +**A nested host fails to authenticate.** Each hop is an `ssh2` login made from +this process through the parent connection. Confirm that the jump host can reach +the target address and port, and that the nested host object has working +credentials (`userName`, `password`, `privateKey`, `passPhrase`, or `agent`). +Hops use local credentials, not the parent's. The failure arrives as an `error` +event with type `Hop`, and the parent continues with its remaining hosts. **The output contains escape codes or control characters.** Adjust `disableColorFilter`, `disableASCIIFilter`, `textColorFilter`, or `asciiFilter`. @@ -1296,26 +1269,30 @@ See [Prompts and response filters](#prompts-and-response-filters). Common causes are a wrong host or port, a rejected key, or an invalid `standardPrompt`. +**You need lower-level connection state.** Members whose names begin with `_` +are internal and may change between releases. `connection` and `_stream` are +diagnostic handles for the active host; use the documented methods rather than +driving them directly. + ## Security -Keep `ssh2shell` and its dependencies up to date. The library validates and -quotes values that are interpolated into the nested `ssh` command, but the +Keep `ssh2shell` and its dependencies up to date. Host values are passed to +`ssh2` as data, so there is no nested command string to quote or validate. The application is still responsible for validating untrusted input before it -reaches `server` or `server.ssh`. +reaches `server`. - Allow-list `host`, `userName`, and `port` at the application boundary. -- Treat `server.ssh` values (`identityFile`, `cipherSpec`, `escape`, `logFile`, - `configFile`, `loginName`, `macSpec`, and `options`) as configuration, not - user input. -- Nested connections add `StrictHostKeyChecking=no`. If that is not acceptable, - enforce host-key policy on the primary host or avoid tunnelling. +- Treat `privateKey`, `passPhrase`, and `agent` as configuration, not user input. +- Set `hostHash` / `hostVerifier` on primaries and hops where host identity + matters. `ssh2` accepts any host key by default; the library never injects + `StrictHostKeyChecking=no`. - Keep `exposeCredentials` at its default (`false`) in production. -- Use fingerprint validation on primary connections where host identity matters. **Advisory:** [GHSA-4j47-m47f-3jp8](https://github.com/cmp-202/ssh2shell/security/advisories/GHSA-4j47-m47f-3jp8) covers argument injection and shell breakout through unquoted `server.ssh` -parameters and the `host`/`userName`/`port` fields. It is fixed in `2.0.13`, -`2.0.14`, and `3.0.0`. Users of `2.0.12` and earlier should upgrade. +parameters and the `host`/`userName`/`port` fields in releases before the +`ssh2` hop transport. It is fixed in `2.0.13`, `2.0.14`, and `3.0.0`. Users of +`2.0.12` and earlier should upgrade. ## Development @@ -1327,9 +1304,16 @@ npm test ``` `npm test` checks that `lib/` matches `src/`, runs the offline unit tests, and -runs the level-aware baseline tests. The live tests need real hosts. See -[`test/README.md`](./test/README.md) for the test layout, live runner, -environment variables, keys, and VM provisioning. +runs the level-aware baseline tests. The live tests need SSH hosts; CI starts +three throwaway `sshd` instances on the runner, and the same suite can run +against the provisioning VMs locally. See [`test/README.md`](./test/README.md) +for the test layout, live runner, environment variables, keys, CI hosts, and VM +provisioning. + +## Changelog + +See [CHANGELOG.md](./CHANGELOG.md) for user-facing changes by release, +including the breaking changes in the current major version. ## License diff --git a/REFACTORING.md b/REFACTORING.md index 34ce668..9024340 100644 --- a/REFACTORING.md +++ b/REFACTORING.md @@ -46,15 +46,18 @@ Two host layers exist and must stay distinct: - **Primary hosts** live in `_hosts` and are opened with a new `ssh2.Client` connection. `_nextPrimaryHost` iterates this array. -- **Secondary (nested) hosts** live in the current host's `hosts` array and are - opened by typing an `ssh ...` command into the current shell (`_sshConnect`). - `_nextHost` iterates this array. Several secondary hosts may be chained. - -`_runExit` is the "finish this host" routine. It runs queued exit commands, then -opens the next secondary host if one remains, otherwise backs out through -`_connections` via `_previousHost`, and finally closes. Backing out to a previous -host re-runs `_runExit`, so that host's remaining `hosts` entries are resumed -rather than discarded. See `docs/API-BASELINE.md` for the exact order. +- **Secondary (nested) hosts** live in the current host's `hosts` array. Since + L7.24 a hop opens an `ssh2` `forwardOut` channel through the active record and + logs in over it, instead of typing an `ssh ...` command into the shell. The + active records form an ancestor stack in `_connections`; `_nextHost` + iterates the nested array. Several secondary hosts may be chained. + +`_runExit` is the "finish this host" routine. It opens the next secondary host +if one remains, otherwise backs out through `_connections` via `_previousHost`, +and finally closes. The literal `exit` branch remains for `su` / `sudo -i` and +the final primary shell; a hop is left by closing its connection. Backing out to +a previous host re-runs `_runExit`, so that host's remaining `hosts` entries are +resumed rather than discarded. See `docs/API-BASELINE.md` for the exact order. ## Branch and tag policy @@ -105,6 +108,7 @@ The release tags give a stable coarse boundary for the untagged levels: | `refactor/L7.6..v3.1.0` | `v3.1.0` | L7.7-L7.17 plus follow-up commits (16 commits) | | `v3.1.0..v3.2.0` | `v3.2.0` | L7.18 (post-3.1.0 shutdown work) | | `v3.2.0..v3.3.0` | `v3.3.0` | L7.19-L7.23 (opt-in prompt/response/timeout/silent-command/stderr features) | +| `v3.3.0..v4.0.0` | `v4.0.0` | L7.24-L7.25 (`ssh2` `forwardOut` hops, always-on command idle timeout, surface cleanup) | ```bash # Inspect everything after the last tagged level @@ -119,14 +123,18 @@ git diff v3.1.0..v3.2.0 git log --oneline v3.2.0..v3.3.0 git diff v3.2.0..v3.3.0 -# Revert the post-3.2.0 work as one commit (keeps history) -git revert --no-commit v3.2.0..v3.3.0 -git commit -m "revert post-3.2.0 work" +# Inspect the post-3.3.0 work +git log --oneline v3.3.0..v4.0.0 +git diff v3.3.0..v4.0.0 + +# Revert the post-3.3.0 work as one commit (keeps history) +git revert --no-commit v3.3.0..v4.0.0 +git commit -m "revert post-3.3.0 work" ``` -`v2.0.14`, `v2.1.0`, `v3.0.0`, `v3.1.0`, `v3.2.0`, and `v3.3.0` are the -release boundaries. The release process, tag convention, and `gitHead` check -are in [docs/PUBLISHING.md](docs/PUBLISHING.md). +`v2.0.14`, `v2.1.0`, `v3.0.0`, `v3.1.0`, `v3.2.0`, `v3.3.0`, and `v4.0.0` +are the release boundaries. The release process, tag convention, and `gitHead` +check are in [docs/PUBLISHING.md](docs/PUBLISHING.md). ## Level completion checklist @@ -217,6 +225,8 @@ must be recorded here. | L7.21 | — (ledger-only) | — | Done (v3.3.0) | Opt-in `commandTimeoutRetries` with library-owned attempts | New suite covers the single-timeout default, re-arm, handler answer, stop, opt-out, final-only close, and reset points; `npm test` 169/169 unit and 169/169 baseline; live `timeout` passes | No level tag; released in `v3.3.0`; see [L7.21 deliverables](#l721-deliverables-command-timeout-retries) | | L7.22 | — (ledger-only) | — | Done (v3.3.0) | Opt-in `commandStartTimeout` for silent commands and `details.noOutput` | New suite covers the default no-timer behavior, start-timer arming, `noOutput` true/false, and the per-command reset; `npm test` 179/179 unit and 179/179 baseline | No level tag; released in `v3.3.0`; see [L7.22 deliverables](#l722-deliverables-silent-command-timeout) | | L7.23 | — (ledger-only) | — | Done (v3.3.0) | Opt-in stderr capture in the command response (`captureStderr`) | New suite covers the default, raw merge, handled merge, escape filtering, and per-command reset; `npm test` 179/179 unit and 179/179 baseline | No level tag; released in `v3.3.0`; see [L7.23 deliverables](#l723-deliverables-stderr-capture) | +| L7.24 | — (ledger-only) | — | Done (v4.0.0) | `ssh2` `forwardOut` host hops and an always-on command idle timeout | `npm run test:src` 163/163; `npm test` 155 pass with 8 baseline-skipped; full live suite 28/28 on `src` twice; clean-VM provisioning reports `sudoers: OK`, `sshd: OK`, `network: OK` | No level tag; released in `v4.0.0`; see [L7.24 deliverables](#l724-deliverables-ssh2-forwardout-hops-and-always-on-command-idle-timeout) | +| L7.25 | — (ledger-only) | — | Done (v4.0.0) | Pre-release instance and host-config surface cleanup; removes legacy aliases and renames `host.msg` to `host.onMsg` | `npm run test:src` 166/166; `npm run test:baseline` 158 pass with 8 baseline-skipped | No level tag; released in `v4.0.0`; see [L7.25 deliverables](#l725-deliverables-pre-release-surface-cleanup) | Commit SHAs are deliberately omitted from this table: a commit cannot contain its own hash. Where a tag exists, it is the stable rollback reference; use @@ -1017,6 +1027,12 @@ Signed-off-by: user request for the silent-command and "no output yet" distincti Released in `v3.3.0`. +> **Superseded in 4.0.0.** 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. @@ -1055,6 +1071,90 @@ Released in `v3.3.0`. - `npm test` — 179/179 unit and 179/179 baseline. - `stderrData` still fires in every case; the default payload is unchanged. +### L7.24 deliverables (`ssh2` `forwardOut` hops and always-on command idle timeout) + +Signed-off-by: user request to replace nested `ssh` host hops and to make silent +commands time out. + +Released in `v4.0.0`. + +- `src/ssh2shell.js` — `_connect(parent = null)` owns primary and hop + connections; a hop opens a `forwardOut` channel and logs in over it. Records + form an ancestor stack with per-record listeners and timers. `_failContext()` + contains hop failures, `_endPrimary()` advances past a failed primary, and + `_closeContext()` is the only record teardown. `_sanitizeResponse()` slices + after the last echoed command. The command idle timer is armed when a command + is written, reset by `_onData`, and cancelled by prompt detection. +- `src/ssh2shell/defaults.js` — `commandStartTimeout` is gone and + `passphrasePrompt` is no longer defaulted. +- Removed `src/ssh2shell/ssh-command.js`, `buildSshCommand()`, `shellQuote()`, + `shellControlChars`, `_sshConnect()`, `_processSSHPrompt()`, + `sshAuth` / `sshToNextHost`, `exitCommands`, and the `Security Alert` path. +- `test/unit/host-hop.test.js` — record stack, hop transport, containment, + primary advance, and host-list validation. +- `test/unit/command-start-timeout.test.js` — always-on timeout, a silent + command returning to a prompt, and prompt-race cancellation. +- `test/live/host_traversal.js` and `test/live/host_faults.js` — depth-first + traversal and contained-fault acceptance tests. +- `test/utils/module-target.js` and `test/utils/module.js` — `SSH2SHELL_MODULE` + selection for `src`, `lib`, `baseline`, or a repo-relative path. +- `docs/NEXT-HOST-CONNECTION.md` — design and implementation record. + +#### Verification + +- `npm run test:src` — 163/163. +- `npm test` — 155 pass, 8 baseline-skipped. +- Live suite against `src` — 28/28, run twice. +- Clean-VM provisioning (`SSH2SHELL_MODULE=src`) — `sudoers: OK`, `sshd: OK`, + `network: OK`. + +### L7.25 deliverables (pre-release surface cleanup) + +Pre-release cleanup of the instance and host-config surface. Released in +`v4.0.0` on `next-host-connection`. + +**Breaking changes** + +- `host.msg` is renamed to `host.onMsg`. The Hubot-era `msg: { send: fn }` + shape is removed. +- `server.hashMethod` is removed; use `hostHash`. +- `sshObj.stop` is removed; use `abort`. +- Host `idleTime` and `dataIdleTime` are removed; use `idleTimeOut` and + `dataIdleTimeOut`. Instance-level `SSH.idleTime` / `SSH.dataIdleTime` remain. + +**Host config no longer gains library state** + +- `_loadDefaults` resolves default command handlers per record instead of + writing instance-capturing closures into the host object. +- The `{ send }` message shape is no longer rewritten into `host.msg`. +- `applyHostDefaults` no longer writes `server.hashKey`. + +**Instance surface** + +- CoffeeScript-era prototype defaults moved into the constructor; the prototype + default block is deleted. +- Constructor binds reduced to the public entry points, `_connect` / + `_connectHop`, and the three default command handlers. +- Dead `_boundListener`, `_detachListener`, `_boundListeners`, and prototype + no-op handlers removed. +- `ssh2Client` is now `_ssh2Client`, marked as an internal test seam. +- `command` and `_buffer` are saved on the record and restored by + `_restoreContext()`, so backing out of a hop resumes the parent's command + state. + +**Docs** + +- README: `onMsg` replaces `msg`; removed aliases deleted; active-host mirrors + and internal members reduced to one Troubleshooting note; host-config + mutation and handler `this` documented; garbled-buffer workaround removed. +- `docs/API-BASELINE.md`, `docs/CLOSE-SEMANTICS.md`, and + `docs/NEXT-HOST-CONNECTION.md` updated for the removed aliases. + +#### Verification + +- `npm run test:src` — 166/166. +- `npm run test:baseline` — 158 pass, 8 baseline-skipped. + ## Backlog and future work Items explicitly deferred until after the mechanical refactor. Each one changes @@ -1072,13 +1172,14 @@ observable behavior or security posture and needs its own level and sign-off. `test/unit/api-baseline.test.js`. It kept and modernized `lots_of_commands.js`, `pipe.js`, `ssh_user_command.js`, `sudo_no_pass.js`, and `timeout.js` as manual live-host checks. -- **Replace the nested-host `ssh ...` command string with chained `ssh2` - connections.** Today `_sshConnect` builds a shell command (`ssh -x ...`) and - types it into the current shell. Chaining `ssh2.Client` objects would avoid - shell quoting, remove the dependency on a remote `ssh` binary, and make - authentication/fingerprint handling consistent for nested hosts. This is the - largest planned behavioral change and should be its own level with dedicated - tests. +- **Done at L7.24 (signed off, superseded by + [L7.24 deliverables](#l724-deliverables-ssh2-forwardout-hops-and-always-on-command-idle-timeout)): + replace the nested-host `ssh ...` command string with chained `ssh2` + connections.** The hop now opens an `ssh2` `forwardOut` channel and logs in + over it, so there is no shell quoting, no remote `ssh` binary, and hop + authentication uses the runner's local credentials. Nested hosts run on the + normal `onData` / `commandComplete` path. The old `_sshConnect` / + `buildSshCommand()` path and `src/ssh2shell/ssh-command.js` are removed. - **Done post-L5 (signed off):** map the documented `dataIdleTimeOut` to the internal `dataIdleTime` timer (default 500 ms). `dataIdleTimeOut` wins; the undocumented `dataIdleTime` remains as a fallback. @@ -1198,12 +1299,11 @@ behavior. the handled response and keep the raw buffer only as an optional extra. `commandProcessing` receives chunks before filtering, so handlers can see ANSI, partial prompts, and the same prompt more than once. -- `commandComplete` does not fire for `exit`, empty commands, or the nested - `ssh` command, and the timeout itself does not emit `commandComplete` (a - subsequent answered `onData` can). The nested-`ssh` gap is a stage-engine - difference, not a missing event. Replacing the nested - `ssh ...` command string with chained `ssh2` connections removes that stage - and puts nested hosts back on the normal `onData` / `commandComplete` path. +- `commandComplete` does not fire for `exit` or empty commands, and the timeout + itself does not emit `commandComplete` (a subsequent answered `onData` can). + The old nested-`ssh` gap was a stage-engine difference, not a missing event; + L7.24 removed that stage, so nested hosts now use the normal `onData` / + `commandComplete` path. - A command that restarts networking or `sshd` in the foreground can drop the session or exceed `idleTimeOut`; the current workaround is `nohup ... &` plus polling. @@ -1218,16 +1318,20 @@ behavior. **Candidate improvements (behavior changes; implemented items are marked)** -- Pass the handled response to `commandComplete`: remove the echoed command, - trailing prompt, ANSI, and wrap artifacts. The handler already receives - `command`, so this avoids redundant parsing. Keep the raw buffer as an - optional extra for callers that need it. -- Keep the default standard-prompt set small (the most-used prompts) and add an - opt-in full regular expression (or `standardPromptRegex`) for callers that - need to anchor to `user@host:~$ `. -- Treat `commandTimeout` as a first-class retry path: document that answering a - prompt from the timeout handler can resume normal completion, and consider a - built-in attempt counter instead of per-host `FirstPass` flags. +- **Implemented:** pass the handled response to `commandComplete`: remove the + echoed command, trailing prompt, ANSI, and wrap artifacts. The handler already + receives `command`, so this avoids redundant parsing. The opt-in + `commandResponse: 'handled'` keeps the raw buffer as `details.rawResponse`. + See [L7.20 deliverables](#l720-deliverables-handled-commandcomplete-payload). +- **Implemented:** keep the default standard-prompt set small (the most-used + prompts) and add an opt-in full regular expression (`standardPromptRegex`) for + callers that need to anchor to `user@host:~$ `. See + [L7.19 deliverables](#l719-deliverables-standardpromptregex). +- **Implemented:** treat `commandTimeout` as a first-class retry path: answering + a prompt from the timeout handler can resume normal completion, and + `commandTimeoutRetries` gives the library an attempt counter instead of + per-host `FirstPass` flags. See + [L7.21 deliverables](#l721-deliverables-command-timeout-retries). - **Implemented:** define and test the queue-mutation contract: `sshObj.commands` push/unshift/splice from `commandComplete`, plus explicit skip/stop flags (`skipCommands`, `skipHosts`, `skipPrimaryHosts`, `abort`/`stop`) checked by @@ -1240,7 +1344,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 4.0.0: 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..4324332 100644 --- a/docs/API-BASELINE.md +++ b/docs/API-BASELINE.md @@ -1,14 +1,25 @@ # API baseline and README reconciliation - **Baseline:** `refactor/L0-baseline` (`v2.0.14`) -- **Source of truth:** `src/ssh2shell.js`, a 1:1 port of the baseline - `src/ssh2shell.coffee`; `lib/ssh2shell.js` is its published copy. +- **Characterized build:** the frozen baseline in + `test/fixtures/baseline-ssh2shell.js`, a 1:1 port of the baseline + `src/ssh2shell.coffee`. - **Method:** read the implementation, exercise it with the offline harness in `test/unit/`, and compare every documented claim in `README.md` against the actual code. - **Status:** L1 baseline characterization, preserved through L4; L5, L6, and L6.1 record the signed-off behavior changes separately. +> **Superseded in 4.0.0.** The current `src/ssh2shell.js` replaced the +> nested `ssh` command with `ssh2` `forwardOut` hops. `server.ssh`, the +> jump-host credential model, `exitCommands`, `passphrasePrompt`, +> `commandStartTimeout`, and `details.noOutput` no longer exist. The host +> message handler is now `onMsg`; `server.hashMethod`, `sshObj.stop`, the host +> `idleTime` / `dataIdleTime` aliases, and the `msg: { send }` shape are also +> removed. The sections below describe the frozen baseline and remain useful +> for comparison only. See [NEXT-HOST-CONNECTION.md](NEXT-HOST-CONNECTION.md) +> and the README for current behavior. + The README is treated as *documented intent*. Where it disagrees with the code, the code is recorded as the current behavior and the mismatch is listed below. Nothing here is fixed during L1 except the documentation-only corrections @@ -75,23 +86,27 @@ until `_connections` is empty and `close()` runs. | `pipe(destination)` | Inherited | Legacy `Stream.prototype.pipe`; works by listening to `data`/`end`. | | `unpipe(destination)` | **Missing** | `Stream.prototype.unpipe` is undefined. The README no longer documents it; `pipe`/`unpipe` are stream-level operations on the instance, not host config. | -### Public properties - -| Property | Meaning | -| --- | --- | -| `sshObj` | Current host object plus runtime state. | -| `command` | Command currently being run (`""` between commands). | -| `connection` | Current `ssh2.Client` instance. | -| `_hosts` | Remaining **primary** hosts (each connected with `ssh2`). | -| `_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. | -| `standardPrompt`, `passwordPrompt`, `passphrasePrompt` | Compiled `RegExp` prompt detectors. `standardPrompt` is compiled from `standardPromptRegex` when that opt-in is set, otherwise from the `standardPrompt` character set. | -| `asciiFilter`, `textColorFilter` | Compiled `RegExp` response filters. | +### Instance properties observed at baseline + +This table records the instance properties the baseline exposed, not a +supported API. In the current major, members beginning with `_` are internal. +`sshObj`, `command`, `idleTime`, and `dataIdleTime` are documented in the +README; the rest are diagnostics or implementation state. + +| Property | Status | Meaning | +| --- | --- | --- | +| `sshObj` | Public | Current host object plus runtime state. | +| `command` | Public | Command currently being run (`""` between commands). | +| `connection` | Diagnostic | Active host's `ssh2.Client` instance. | +| `_hosts` | Internal | Remaining **primary** hosts (each connected with `ssh2`). | +| `_connections` | Internal | Stack of previous hosts used to back out through secondary/nested connections. | +| `_stream` | Diagnostic | Active shell stream. | +| `_buffer` | Internal | Raw response buffer for the current command. | +| `_stderrBuffer` | Internal | Captured stderr for the current command when `captureStderr` is enabled. | +| `idleTime` | Public | Command timeout in ms (`idleTimeOut`, default 5000). | +| `dataIdleTime` | Public | Response-settling delay in ms (`dataIdleTimeOut`, default 500). | +| `standardPrompt`, `passwordPrompt`, `passphrasePrompt` | Diagnostic | Compiled `RegExp` prompt detectors. `standardPrompt` is compiled from `standardPromptRegex` when that opt-in is set, otherwise from the `standardPrompt` character set. | +| `asciiFilter`, `textColorFilter` | Diagnostic | Compiled `RegExp` response filters. | ### Events emitted by the code @@ -104,7 +119,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 +130,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`, @@ -129,14 +144,20 @@ undocumented `dataIdleTime`), `commandResponse`, `commandStartTimeout`, `onCommandTimeout`, `onKeyboardInteractive`, `onData`, `onStderrData`, `onError`, `onEnd`. -**Nested SSH command options (`server.ssh`):** `forceProtocolVersion`, +**Nested SSH command options (`server.ssh`, baseline only):** `forceProtocolVersion`, `forceAddressType`, `disablePseudoTTY`, `forcePseudoTTY`, `verbose`, `cipherSpec`, `escape`, `logFile`, `configFile`, `identityFile`, `loginName`, `macSpec`, `options`. **Removed legacy aliases:** the misspelled `passwordPromt` and -`passphrasePromt` fallbacks were removed post-L7. Only `passwordPrompt` and -`passphrasePrompt` are read. The frozen baseline still honours the aliases. +`passphrasePromt` fallbacks were removed post-L7. The baseline reads +`passwordPrompt` and `passphrasePrompt`; the current build reads only +`passwordPrompt` (for `sudo`). The frozen baseline still honours the aliases. + +The current major also removed the host `msg` handler (replaced by `onMsg`), +the `msg: { send }` shape, `server.hashMethod` (use `hostHash`), `sshObj.stop` +(use `abort`), and the host `idleTime` / `dataIdleTime` keys (use +`idleTimeOut` / `dataIdleTimeOut`). The frozen baseline still accepts them. ## README claims that are confirmed by the code @@ -149,9 +170,10 @@ undocumented `dataIdleTime`), `commandResponse`, `commandStartTimeout`, - `onCommandProcessing`, `onCommandComplete`, `onCommandTimeout`, `onKeyboardInteractive`, `onData`, `onStderrData`, `onError`, and `onEnd` are registered per host. -- Multiple primary hosts, nested `hosts` arrays, notifications, sudo/su prompt - handling, and `server.ssh` option construction are implemented. -- Fingerprint validation is delegated to `ssh2` through `server.hashMethod` and +- Multiple primary hosts, nested `hosts` arrays, notifications, and sudo/su prompt + handling are implemented. The baseline also implements `server.ssh` option + construction; the current build does not. +- Fingerprint validation is delegated to `ssh2` through `server.hostHash` and `server.hostVerifier`. ## L1 README corrections @@ -286,21 +308,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/CLOSE-SEMANTICS.md b/docs/CLOSE-SEMANTICS.md index ea078b4..ad1821a 100644 --- a/docs/CLOSE-SEMANTICS.md +++ b/docs/CLOSE-SEMANTICS.md @@ -34,17 +34,16 @@ command completes -> commandComplete event -> _applyHandlerFlags(): consume abort/stop/skip* flags set by the handler -> _nextCommand(): shift the next command, or _runExit() - -> _runExit(): queued exitCommands - -> sshObj.hosts (nested hosts) + -> _runExit(): sshObj.hosts (nested hosts) -> _connections (back out to the previous host) -> literal 'exit' -> close() - -> close(): _finalizeHost() then _stream.close() - -> stream 'finish': _finalizeHost() - -> stream 'close': connection.end() - -> connection 'close': clear timers; _finalizeRun(); - closedMessage or error; - final callback or the next primary host + -> close(): _closeContext() removes that record's listeners, finalizes the host, + closes the stream, then ends the connection + -> connection 'close': _appendPartial(); _failContext() -> _endPrimary() + finalize the visited hosts; + closedMessage or error; + final callback or the next primary host ``` `_commandComplete()` appends the response **before** it emits @@ -56,16 +55,15 @@ The shutdown paths are: ```text stop(reason) -> clear every command queue, every nested hosts queue, and _hosts - -> keep sshObj.exitCommands -> if a command is in flight: Ctrl-C, wait for prompt or idleTimeOut - -> run queued exit commands (bounded by idleTimeOut) + -> close the active record and every ancestor -> _finalizeRun(): one `end` per visited host, nested text merged -> close once; callback once; `Stop requested: ` close() / close({ graceful: true }) -> finalize the current host and ancestors -> continue with remaining primary hosts (compatibility) - -> graceful: clear queues, run exit commands, back out of nested shells + -> graceful: back out of nested shells before closing ``` ## Current outcomes (implemented) @@ -76,10 +74,10 @@ close() / close({ graceful: true }) | `sshObj.commands.length = 0` or `sshObj.skipCommands = true` in `onCommandComplete` | current host stops | that host's nested hosts still run; remaining primary hosts still run | response already added; `end` once per visited host | normal close | progress ends; normal close message | | also `sshObj.hosts.length = 0` or `sshObj.skipHosts = true` | current host stops | that host's own nested hosts are skipped; sibling nested hosts queued on a parent still run; remaining primary hosts still run | response already added; `end` once per visited host | normal close | progress ends; normal close message | | `sshObj.skipPrimaryHosts = true` | current host stops | no further primary hosts | response already added; `end` once per visited host | normal close | progress ends; normal close message | -| `sshObj.abort = true` / `sshObj.stop = true` / `this.stop(reason)` | all queues cleared | no nested or primary hosts run | current response and nested text merged; `end` once per visited host; callback once | one close; queued exit commands run first | progress ends; `Stop requested: `; `closedMessage` on clean close | +| `sshObj.abort = true` / `this.stop(reason)` | all queues cleared | no nested or primary hosts run | current response and nested text merged; `end` once per visited host; callback once | one close of the active record and its ancestors | progress ends; `Stop requested: `; `closedMessage` on clean close | | `this.close()` in a handler | no further writes | current connection ends; remaining primary hosts still connect; current host's nested children are skipped | current host finalized; `end` once per visited host | stream closes, then `connection.end()` | progress ends; `closedMessage` | -| `this.close({ graceful: true })` | no further commands | runs queued exit commands and backs out of nested shells; remaining primary hosts still run | complete for every visited host | one close | progress ends; normal close message | -| `this.connection.end()` | same as `close()` | same as `close()`, but bypasses exit commands and host back-out | text may be missing because finalization is skipped | connection ends directly | progress ends | +| `this.close({ graceful: true })` | no further commands | backs out of nested shells; remaining primary hosts still run | complete for every visited host | one close | progress ends; normal close message | +| `this.connection.end()` | same as `close()` | same as `close()`, but bypasses host back-out | text may be missing because finalization is skipped | connection ends directly | progress ends | | `stream.write('\x03')` (Ctrl-C) | unchanged | unchanged | partial output stays in the buffer | stays open | unchanged | | Default `onCommandTimeout` | current command ends | remaining primary hosts still connect | the default handler adds the partial buffer to `sessionText` | emits a closing error; stream closes, then the connection | progress ends; error `msg` | @@ -107,7 +105,7 @@ Notes: | ID | Gap | Status | | --- | --- | --- | | G1 | `close()` cannot stop a whole run: the next primary host still connects. | **Resolved by `stop()`.** `close()` keeps the compatibility behavior. | -| G2 | `close()` bypasses `_runExit()`, so queued exit commands and the nested-host text merge do not run. | **Resolved.** `close({ graceful: true })` runs exit commands and backs out; plain `close()` finalizes the current host. | +| G2 | `close()` bypasses `_runExit()`, so the nested-host back-out does not run. | **Resolved.** `close({ graceful: true })` backs out of nested shells; plain `close()` finalizes the current host. | | G3 | `close()` from `onCommandComplete` does not stop `_nextCommand()`, so the queue is still walked. | **Resolved.** The command loop checks `_closing`/`_runComplete`. | | G4 | Clearing `sshObj.commands` stops only the current host; nested and primary hosts continue. | **By design.** `stop()` aborts the whole run; `skipPrimaryHosts` skips primaries only. | | G5 | There is no public way to skip the remaining primary hosts (`_hosts` is private). | **Resolved** by `sshObj.skipPrimaryHosts = true`. | @@ -147,9 +145,9 @@ With the implemented changes: | `sshObj.commands.length = 0` / `sshObj.skipCommands = true` | Stop the current host after this command. Let the normal back-out run. | | `sshObj.hosts.length = 0` / `sshObj.skipHosts = true` | Skip the current host's own nested hosts. The current host continues its commands unless `skipCommands` is also set; sibling nested hosts queued on a parent still run; primary hosts continue. | | `sshObj.skipPrimaryHosts = true` | Do not connect the remaining primary hosts. The current host finishes its commands unless `skipCommands` is also set. | -| `SSH.stop(reason)` / `sshObj.abort = true` / `sshObj.stop = true` | Stop the whole run: no more commands, no more nested or primary hosts. | +| `SSH.stop(reason)` / `sshObj.abort = true` | Stop the whole run: no more commands, no more nested or primary hosts. | | `SSH.close()` | Immediate close of the current shell connection. Remaining primary hosts still run. | -| `SSH.close({ graceful: true })` | Run queued exit commands and back out of nested shells before closing. | +| `SSH.close({ graceful: true })` | Back out of nested shells before closing. | Implemented matrix: @@ -158,9 +156,9 @@ Implemented matrix: | Clear `commands` / `skipCommands` | current host stops | children and primary hosts continue | complete; `end` once per host | normal close | progress ends; normal close | | Clear `hosts` / `skipHosts` | current host continues unless `skipCommands` is also set | current host's children skipped; sibling nested hosts queued on a parent continue; primary hosts continue | complete; `end` once per host | normal close | progress ends; normal close | | `skipPrimaryHosts` | current host continues unless `skipCommands` is also set | no further primary hosts | complete; `end` once per host | normal close | progress ends; normal close | -| `stop(reason)` | all queues cleared | all remaining hosts skipped | current response and nested text merged; `end` once per visited host; callback once | one close; exit commands run first | progress ends; `Stop requested: `; `closedMessage` on clean close | +| `stop(reason)` | all queues cleared | all remaining hosts skipped | current response and nested text merged; `end` once per visited host; callback once | one close of the active record and its ancestors | progress ends; `Stop requested: `; `closedMessage` on clean close | | `close()` | no further writes | current connection ends; primary hosts continue (compat) | current host finalized; `end` once per visited host | one close | progress ends; `closedMessage` | -| `close({ graceful: true })` | no further commands | exit commands and back-out run; primary hosts continue | complete; `end` once per visited host | one close | progress ends; normal close | +| `close({ graceful: true })` | no further commands | back-out runs; primary hosts continue | complete; `end` once per visited host | one close | progress ends; normal close | | `stream.write('\x03')` | unchanged | unchanged | partial buffer retained | stays open | unchanged | | Timeout | current command ends | policy from `onCommandTimeout` | partial buffer saved before close | close by default | progress ends; error `msg` | @@ -193,10 +191,10 @@ R1–R8 were signed off and implemented. private primary-host queue. - If a command is in flight, writes Ctrl-C and waits for the prompt or the idle timeout before closing. -- Runs the library's queued `exitCommands` (the `exit` it adds when a nested - `ssh` shell opens) when the shell is still healthy. Explicit `exit` entries in - `commands` are cleared with the rest of the queue; closing the connection still - ends any `sudo -i` or `su` shell. +- Closes the active record and every ancestor. Leaving a nested shell is a + connection close, not an `exit` command; closing the connection still ends any + `sudo -i` or `su` shell. Explicit `exit` entries in `commands` are cleared with + the rest of the queue. - Closes once and calls the final callback with the complete `sessionText`. - Records the reason as `sshObj.stopReason` and emits `Stop requested: `. - Is a no-op before `connect()` and after the run has finished. @@ -208,8 +206,8 @@ R1–R8 were signed off and implemented. snapshotted and its `end` is emitted exactly once. - Keeps the existing "continue with the next primary host" behavior for compatibility; `stop()` is the whole-run abort. -- `close({ graceful: true })` runs queued exit commands and backs out of nested - shells before the stream closes. +- `close({ graceful: true })` backs out of nested shells before the stream + closes. ### R3. The command loop is guarded @@ -220,7 +218,7 @@ R1–R8 were signed off and implemented. ### R4. Handler stop flags -- `sshObj.abort` or `sshObj.stop` calls `stop()` after the handler returns. +- `sshObj.abort` calls `stop()` after the handler returns. - `sshObj.skipCommands` clears the current host's `commands` array. - `sshObj.skipHosts` clears the current host's `hosts` array. It does **not** clear a parent's queue: sibling nested hosts queued on a parent still run, by @@ -230,8 +228,8 @@ R1–R8 were signed off and implemented. ### R5. Centralized host finalization -- `_finalizeHost()` is used by `_runExit()`, `_previousHost()`, - `_nextPrimaryHost()`, `close()`, `stop()`, and the connection `close` handler. +- `_finalizeHost()` is used by `_closeContext()`, `_previousHost()`, + `_nextPrimaryHost()`, `_finalizeRun()`, and the stream `finish` handler. - `_finalizeRun()` finalizes the current host and every ancestor, deepest first. - Nested text is merged into the parent exactly once via `_mergedHosts`; `_primaryhostSessionText` and `_allSessions` are appended exactly once via @@ -316,7 +314,9 @@ onError(err, type, close) { 1. ~~Should `close()` continue with remaining primary hosts (compatibility) or abort the run?~~ **Signed off:** continue; use `stop()` to abort. 2. ~~Should `stop()` run queued exit commands by default?~~ **Signed off:** yes, - bounded by the idle timeout; `close()` remains the immediate path. + bounded by the idle timeout; `close()` remains the immediate path. **Superseded:** + the `ssh2` hop transport removed the `exitCommands` queue. `stop()` closes the + active record and its ancestors instead. 3. ~~Should a rejected sudo password abort by default?~~ **Signed off:** no, emit a visible message and offer `abortOnSudoFailure`. 4. ~~Should handlers use `sshObj` flags or return values?~~ **Signed off:** flags, diff --git a/docs/ERROR-HANDLING.md b/docs/ERROR-HANDLING.md index 8cbc03a..a30defe 100644 --- a/docs/ERROR-HANDLING.md +++ b/docs/ERROR-HANDLING.md @@ -53,15 +53,15 @@ call to `close()`. | # | Source | Trigger | Emitted payload `(err, type, close, callback)` | Close | Flow immediately after emit | Effect on session | | --- | --- | --- | --- | --- | --- | --- | | 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. | -| 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. | -| 8 | `_connect` connection `error` | The `ssh2.Client` emits `error` | `(err, "Connection", )` | `true` only once a shell stream exists | None | Before the shell opens this is a notification (`close=false`) and the guarded listener does not throw. Once a stream exists it closes and ends the connection. Baseline: always reports without closing. | -| 9 | `_connect` connection `close` | `ssh2` reports `had_error` truthy | `(Error("Connection closed with error"), "Connection close")` with `err.level = "Connection close"` and `err.hadError = had_error` | `false` | Clear timers, `_finalizeRun()`, then call `_callback(_allSessions)` or start the next primary host | Non-fatal. The readable error is reported, every visited host is finalized, and the session still finishes or advances. | -| 10 | `_connect` connect `try` | `connection.connect` throws synchronously | `(e + " " + e.stack, "Connection.connect", )` | `true` only once a shell stream exists | None | Before the shell opens this is a notification and the guarded listener does not throw. `_stream` is reset per primary host, so a stale stream is never closed. | +| 2 | `_connect` hop `forwardOut` | The parent connection's `forwardOut` callback returns an `Error` | `(err, "Hop", false, null, context)` | `false` | `_hopFailed()` -> `_failContext()`: close descendants deepest-first, close the hop, restore the parent, then `_runExit()` on it | Contained. The hop and its unstarted subtree are skipped; the parent continues with its remaining hosts. | +| 3 | `_bindConnection` hop `error` | The hop's `ssh2.Client` emits `error` (login or transport failure) | `(err, "Hop", false, null, context)` | `false` | `_hopFailed()` -> `_failContext()` | Contained. The hop and its subtree are skipped; the parent continues. No retry. | +| 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 | `_openShell` 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 | `_bindStream` 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 | `_bindStream` 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. | +| 8 | `_bindConnection` connection `error` | The `ssh2.Client` emits `error` | `(err, "Connection", )` for a primary; `(err, "Hop", false, null, context)` for a hop | `true` only once a shell stream exists | None | Before the shell opens a primary error is a notification (`close=false`) and the guarded listener does not throw. Once a stream exists it closes and ends the connection. A hop error is contained by `_hopFailed()`. Baseline: always reports without closing. | +| 9 | `_bindConnection` connection `close` | `ssh2` reports `had_error` truthy | `(Error("Connection closed with error"), "Connection close")` with `err.level = "Connection close"` and `err.hadError = had_error` | `false` | `_appendPartial()`, then emit the close message or error, then `_failContext()` -> `_endPrimary()` | Non-fatal. The readable error is reported, every visited host is finalized, and the run advances to the next primary or calls the callback. | +| 10 | `_openClient` connect `try` | `connection.connect` throws synchronously | `(e + " " + e.stack, "Connection.connect", )` for a primary; `(err, "Hop", false, null, context)` for a hop | `true` only once a shell stream exists | None | Before the shell opens a primary throw is a notification and the guarded listener does not throw. A hop throw is contained by `_hopFailed()`. `_stream` is reset per primary host, so a stale stream is never closed. | | 11 | `_connect` missing parameters | No `sshObj.server` or no `sshObj.commands` | `("Missing connection parameters", "Parameters", false, callback)` | `false` | None | No close. The default listener now runs the diagnostic callback, which prints `server` and `commands`; the session still neither starts nor ends. | ## Notification vs terminator @@ -70,9 +70,9 @@ Not every failure should be an `error` event. The current classification is: | Class | Emit sites | Meaning | | --- | --- | --- | -| **Terminator** (`close=true`) | Security Alert, Command Timeout, Stream, Stream.read error, and Shell/Connection/Connection.connect **once a live shell stream exists** | The current connection cannot continue; closing the stream is the intended way to end it. | +| **Terminator** (`close=true`) | Command Timeout, Stream, Stream.read error, and Shell/Connection/Connection.connect **once a live shell stream exists** | The current connection cannot continue; closing the stream is the intended way to end it. | | **Notification** (`close=false`) | Pre-shell Shell/Connection/Connection.connect errors, missing connection parameters, sudo password rejection | The error is reported but nothing is closed. Sudo rejection emits a normal `msg` (and sets `sudoFailed`) instead of an `error`. | -| **Flow control** (`close=false`) | Nested SSH authentication failure, Connection close (`had_error`) | The error is reported, but the existing back-out/advance logic decides what happens next. Connection close finalizes the visited hosts first. | +| **Flow control** (`close=false`) | Hop failure (`forwardOut` or hop connection error), Connection close (`had_error`) | The error is reported, but the existing back-out/advance logic decides what happens next. A hop failure is contained to its subtree; Connection close finalizes the visited hosts first. | The rule: only emit a closing `error` when a live connection must end. Before a shell stream exists there is nothing to close, so Shell, Connection, and @@ -137,7 +137,7 @@ Consequences: ```js // NoReady fake client: connect() never emits ready, so no shell stream exists. const ssh = new SSH2Shell(host); -ssh.ssh2Client = NoReady; +ssh._ssh2Client = NoReady; ssh.on('error', () => { /* never runs on current L5 */ }); ssh.connect(); ssh.connection.emit('error', new Error('boom')); @@ -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 @@ -211,6 +211,10 @@ ssh._loadDefaults(); // baseline: 1; fixed current: 1 (no duplicate) ### L6.1 follow-ups (signed off) +> **Superseded in 4.0.0:** the nested-`ssh` transport was removed, so +> `_processSSHPrompt` and the post-auth nested-shell timeout no longer exist. +> Hop failures are contained by `_hopFailed()`. + - **Post-auth nested-SSH timeout.** `_processSSHPrompt` re-arms the idle timer when authenticated output matches no prompt, instead of returning with no timer. A silent nested shell now times out rather than hanging. diff --git a/docs/NEXT-HOST-CONNECTION.md b/docs/NEXT-HOST-CONNECTION.md new file mode 100644 index 0000000..f9af150 --- /dev/null +++ b/docs/NEXT-HOST-CONNECTION.md @@ -0,0 +1,1761 @@ +# Host-to-host connections: ssh2 hop design + +- **Status:** released in 4.0.0. 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` (merged for 4.0.0). +- **Release:** `4.0.0`. 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, map `userName` / `passPhrase` to ssh2's `username` / `passphrase`, 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`. | +| 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*` 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` | `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`, `onMsg`, `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. | +| `onMsg` | 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 landed on `next-host-connection` and shipped in `v4.0.0`. +- `v4.0.0` is the stable boundary; `v3.3.0` is the last 3.x release. +- The range is recorded in [REFACTORING.md](../REFACTORING.md) as the rollback + boundary. diff --git a/docs/PUBLISHING.md b/docs/PUBLISHING.md index 9884c79..95a7ea1 100644 --- a/docs/PUBLISHING.md +++ b/docs/PUBLISHING.md @@ -47,16 +47,17 @@ For a new version: ```bash npm version --no-git-tag-version -# update REFACTORING.md / docs as needed -git add package.json package-lock.json REFACTORING.md docs +# update REFACTORING.md, CHANGELOG.md, and docs as needed +git add package.json package-lock.json REFACTORING.md CHANGELOG.md docs git commit -m "chore: release X.Y.Z" git tag -a vX.Y.Z -m "X.Y.Z" git push origin master git push origin vX.Y.Z ``` -The tag push triggers `.github/workflows/publish.yml`, which runs the full suite -and publishes with provenance. +The tag push triggers `.github/workflows/publish.yml`, which runs the live suite +(`live.yml`), the offline suite, and publishes with provenance. The publish job +does not start unless the live suite passes. To publish an existing tag manually, open **Actions → Publish to npm → Run workflow**, choose `master`, and enter the tag (for example `v3.0.0`). @@ -83,18 +84,19 @@ left to memory. - [ ] Decide the semver level from the commits since the last tag. - [ ] `npm version --no-git-tag-version`. -- [ ] Update `REFACTORING.md` and any docs affected by the release. +- [ ] Update `REFACTORING.md`, `CHANGELOG.md`, and any docs affected by the + release. - [ ] `npm test` passes (`check:build`, unit, baseline). +- [ ] Run the live suite locally when the change touches connection or command + flow: `npm run test:live:all`. - [ ] Commit `chore: release X.Y.Z`, tag `vX.Y.Z`, push `master` and the tag. +- [ ] The **Live tests** workflow passes. - [ ] The **Publish to npm** workflow succeeds. - [ ] `npm view ssh2shell version` and the `gitHead` check above pass. - [ ] Create a GitHub Release for `vX.Y.Z` with notes for the new features and fixes. -- [ ] Add or update `CHANGELOG.md` for the version. - [ ] Check the workflow actions for deprecated runtimes (for example `actions/checkout` and `actions/setup-node` on Node 20) and bump them. -- [ ] Run the live suite when the change touches connection or command flow: - `npm run test:live:all`. ## Stopgap: granular access token with bypass 2FA diff --git a/lib/ssh2shell.js b/lib/ssh2shell.js index 0c38cc6..7d536c3 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, @@ -69,62 +69,46 @@ class SSH2Shell extends Stream { constructor(hosts) { super(hosts); - // Methods that were CoffeeScript fat-arrows are bound in the constructor. - // Keep the same list and order so callbacks and event listeners keep - // their `this`. - this._connect = this._connect.bind(this); + // Public entry points keep own bound copies so they can be detached and + // passed around. `_connect` and `_connectHop` are passed as bare callbacks + // to the host queue. Default event handlers are bound so the emitter can + // invoke them with this instance. this.connect = this.connect.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); - this._runCommand = this._runCommand.bind(this); - this._checkCommand = this._checkCommand.bind(this); - this._nextCommand = this._nextCommand.bind(this); - this._commandComplete = this._commandComplete.bind(this); - this._finalizeHost = this._finalizeHost.bind(this); - this._finalizeRun = this._finalizeRun.bind(this); - this._mergeNestedText = this._mergeNestedText.bind(this); - this._applyHandlerFlags = this._applyHandlerFlags.bind(this); - this._resetRunState = this._resetRunState.bind(this); - this._callFinalCallback = this._callFinalCallback.bind(this); - this._beginStopExit = this._beginStopExit.bind(this); - this._finishStop = this._finishStop.bind(this); - this._forceStop = this._forceStop.bind(this); - this._clearStopTimer = this._clearStopTimer.bind(this); - this._armStopTimer = this._armStopTimer.bind(this); - this._prepareGracefulClose = this._prepareGracefulClose.bind(this); - this._clearCloseTimer = this._clearCloseTimer.bind(this); - this._armCloseTimer = this._armCloseTimer.bind(this); - 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); - this._onData = this._onData.bind(this); - this._callback = this._callback.bind(this); - 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.ssh2Client = require('ssh2').Client; - this._hosts = typeIsArray(hosts) && hosts.length > 0 ? hosts : [hosts]; + this._connect = this._connect.bind(this); + this._connectHop = this._connectHop.bind(this); + this._defaultOnCommandProcessing = this._defaultOnCommandProcessing.bind(this); + this._defaultOnCommandComplete = this._defaultOnCommandComplete.bind(this); + this._defaultOnCommandTimeout = this._defaultOnCommandTimeout.bind(this); + // Internal test seam. Not part of the public API. + this._ssh2Client = require('ssh2').Client; + + // 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 +128,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; @@ -156,6 +139,22 @@ class SSH2Shell extends Stream { // merging are idempotent across the normal path and an abrupt close. this._finalizedHosts = new Set(); this._mergedHosts = new Set(); + // Instance defaults are own properties from construction. CoffeeScript + // class-body values used to be shared through the prototype until the first + // host load, which aliased `_stream` between instances. + this._callback = null; + this.command = ''; + this._primaryhostSessionText = ''; + this._stream = {}; + this._buffer = ''; + this.idleTime = 5000; + this.dataIdleTime = 500; + this.idleTimer = null; + this.dataReceivedTimer = null; + this.asciiFilter = ''; + this.textColorFilter = ''; + this.passwordPrompt = ''; + this.standardPrompt = ''; this._loadDefaultListeners(); } @@ -165,9 +164,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 +187,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,91 +220,408 @@ 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; } - _boundListener ( eventName, listener, prepend = false ) { - if ( typeof listener === `function` ){ - // Avoid attaching the same handler twice when _loadDefaults runs again. - if (this._boundListeners[eventName] === listener) { - return; + // A real shell stream exists only after `connection.shell` succeeds. Before + // that, the active stream is the `{}` placeholder. + _hasLiveStream() { + 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; } - this._boundListeners[eventName] = listener; - if (prepend) { + 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); } } - - return; } - // A real shell stream exists only after `connection.shell` succeeds. Before - // that, `_stream` is the prototype `{}` placeholder. - _hasLiveStream() { - return Boolean(this._stream && typeof this._stream.close === 'function'); + // 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; } - - // Helper to safely detach listeners using cached references - _detachListener(eventName, currentKey) { - const cachedHandler = this._boundListeners[eventName]; - const hostHandler = this.sshObj ? this.sshObj[currentKey] : undefined; - let removed = false; - - if (typeof cachedHandler === 'function') { - this.removeListener(eventName, cachedHandler); - delete this._boundListeners[eventName]; // clear cache item - removed = true; - } - if (typeof hostHandler === 'function' && hostHandler !== cachedHandler) { - this.removeListener(eventName, hostHandler); - removed = true; - } - - return removed; - }; - + + _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`; `userName` / `passPhrase` are the public names. + _normalizeServer(server) { + const options = Object.assign({}, server || {}); + delete options.ssh; + if (!options.username) { + options.username = options.userName; + } + 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) { + // `command` and `_buffer` are instance aliases for the active host. Save + // the ancestor's values before the child replaces them so restoring the + // parent after a hop resumes its own command state. + parent.command = this.command; + parent.buffer = this._buffer; + 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, + command: '', + buffer: '', + 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; + this.command = typeof context.command === 'string' ? context.command : ''; + this._buffer = typeof context.buffer === 'string' ? context.buffer : ''; + + // 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; + } + // Host prefixes disambiguate messages when the session can span more than // one host. A single host reads better without repeating its address on // every line. Nested hosts keep the prefix, including after their queue has @@ -439,25 +767,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 +801,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 +816,11 @@ class SSH2Shell extends Stream { } }, this.idleTime); - return this.idleTimer; + if (context) { + context.idleTimer = timer; + } + this.idleTimer = timer; + return timer; } _onData(data) { @@ -492,15 +831,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 +847,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 +857,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 +916,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 +936,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 +1094,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 +1204,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; } @@ -1020,15 +1221,9 @@ class SSH2Shell extends Stream { sshObj.skipPrimaryHosts = false; } - if (sshObj.abort || sshObj.stop) { - const reason = - typeof sshObj.abort === 'string' - ? sshObj.abort - : typeof sshObj.stop === 'string' - ? sshObj.stop - : 'command-failed'; + if (sshObj.abort) { + const reason = typeof sshObj.abort === 'string' ? sshObj.abort : 'command-failed'; sshObj.abort = false; - sshObj.stop = false; this.stop(reason); } } @@ -1103,7 +1298,6 @@ class SSH2Shell extends Stream { if (isCommandWrite) { this.sshObj.commandTimeoutAttempt = 0; this.sshObj.retryCommandTimeout = undefined; - this._commandSawData = false; this._stderrBuffer = ''; } @@ -1114,13 +1308,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 +1329,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 +1342,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 +1384,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 +1417,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 +1443,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 +1478,68 @@ 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.command = ''; + 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 +1553,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 +1611,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 +1643,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 +1667,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 +1687,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 +1722,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 +1783,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 +1856,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 +1864,63 @@ 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.command = ''; + 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 +1928,6 @@ class SSH2Shell extends Stream { return; } - this._loadDefaults(); - if (typeof action === 'function') { return action(); } @@ -1708,182 +1948,239 @@ 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() { - // `idleTimeOut` is the documented key; `idleTime` is a legacy alias. - const idleTimeOut = - toPositiveNumber(this.sshObj.idleTimeOut) || - toPositiveNumber(this.sshObj.idleTime); + _applyHostTimerValues(host = this.sshObj) { + const idleTimeOut = toPositiveNumber(host.idleTimeOut); if (idleTimeOut > 0) { this.idleTime = idleTimeOut; } - // 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); + const dataIdleTimeOut = toPositiveNumber(host.dataIdleTimeOut); if (dataIdleTimeOut > 0) { this.dataIdleTime = dataIdleTimeOut; } } - _loadDefaults() { + // Default command handlers. They live on the prototype and are bound in the + // constructor; a host overrides them per record without mutating the config. + _defaultOnCommandProcessing() {} + + _defaultOnCommandComplete() { + this._systemMsg('debug', `onCommandComplete:`); + } + + _defaultOnCommandTimeout(command, response, stream, connection, details) { + // With `commandTimeoutRetries` configured, only the final attempt closes + // the run. The library re-arms the timer for earlier attempts. + if (details && details.final === false) { + this._systemMsg( + 'debug', + `loadDefaults: Class.commandTimeout retry ${details.attempt}/${details.maxRetries}` + ); + return; + } + + response = response.replace(this.command, ''); + this._systemMsg('debug', `loadDefaults: Class.commandTimeout`); + + this._systemMsg( + 'verbose', + `loadDefaults: Timeout command: ${command} response: ${response}` + ); + + this.emit( + 'error', + `${this.host}: Command timed out after ${this.idleTime / 1000} seconds`, + 'Command Timeout', + true, + (err, type) => { + this.sshObj.sessionText += this._buffer; + this._buffer = ''; + } + ); + } + + // 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; + // A host `onMsg` handler replaces the instance fallback while the record is + // active. `_removeListeners` restores the fallback when the record leaves. + const onMsg = typeof host.onMsg === 'function' ? host.onMsg : null; + const previousMsg = record.listeners.msg; + if (previousMsg && previousMsg !== onMsg) { + this.removeListener('msg', previousMsg); + delete record.listeners.msg; } - - 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); + if (onMsg) { + if (this.listeners('msg').includes(this.msg)) { + this.removeListener('msg', this.msg); + } + this._bindHostListener(record, 'msg', onMsg); + } 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}` ); } - // Listener defaults for command processing. - this.sshObj.onCommandProcessing = - this.sshObj.onCommandProcessing ?? - ((command, response, sshObj, stream) => {}); - - this.sshObj.onCommandComplete = - this.sshObj.onCommandComplete ?? - ((command, response, sshObj) => { - this._systemMsg('debug', `onCommandComplete:`); - }); - - this.sshObj.onCommandTimeout = - this.sshObj.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. - if (details && details.final === false) { - this._systemMsg( - 'debug', - `loadDefaults: Class.commandTimeout retry ${details.attempt}/${details.maxRetries}` - ); - return; - } - - response = response.replace(this.command, ''); - this._systemMsg('debug', `loadDefaults: Class.commandTimeout`); - - this._systemMsg('verbose',`loadDefaults: Timeout command: ${command} response: ${response}`); - - this.emit( - 'error', - `${this.host}: Command timed out after ${this.idleTime / 1000} seconds`, - 'Command Timeout', - true, - (err, type) => { - this.sshObj.sessionText += this._buffer; - this._buffer = ''; - } - ); - }); - - // Explicitly cache references right before binding them to the event emitter - if (typeof this.sshObj.onKeyboardInteractive === 'function') { - this._boundListener('keyboard-interactive', this.sshObj.onKeyboardInteractive); - } - if (typeof this.sshObj.onError === 'function') { + // 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; + + // Resolve the command handlers for this record. Defaults are not written + // back to the host config, so reusing a host object with another instance + // does not retain the first instance's closures. + const onCommandProcessing = + typeof host.onCommandProcessing === 'function' + ? host.onCommandProcessing + : this._defaultOnCommandProcessing; + const onCommandComplete = + typeof host.onCommandComplete === 'function' + ? host.onCommandComplete + : this._defaultOnCommandComplete; + const onCommandTimeout = + typeof host.onCommandTimeout === 'function' + ? host.onCommandTimeout + : this._defaultOnCommandTimeout; + + // 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 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', onCommandProcessing); + this._bindHostListener(record, 'commandComplete', onCommandComplete); + this._bindHostListener(record, 'commandTimeout', 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 +2194,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; + } + + 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; + } + + 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; + } - this.connection = new this.ssh2Client(); + // 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; - this.connection.on( + 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,201 +2343,224 @@ 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. + } + } + }); + }); } } -// Class-body properties in the CoffeeScript source become prototype -// properties. They are intentionally shared until an instance assigns an own -// value, matching the baseline (and its known prototype-state quirk). -SSH2Shell.prototype.sshObj = {}; -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 () {}; -SSH2Shell.prototype.onCommandComplete = function () {}; -SSH2Shell.prototype.onCommandTimeout = function () {}; -SSH2Shell.prototype.onEnd = function () {}; - module.exports = SSH2Shell; diff --git a/lib/ssh2shell/defaults.js b/lib/ssh2shell/defaults.js index e67860b..3b54087 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,9 +79,6 @@ function applyHostDefaults(sshObj) { if (typeof sshObj.sudoFailed !== 'boolean') { sshObj.sudoFailed = false; } - if (sshObj.server.hashKey == null) { - sshObj.server.hashKey = ''; - } if (!sshObj.sessionText) { 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/package-lock.json b/package-lock.json index 7b8cf96..726dc72 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "ssh2shell", - "version": "3.3.0", + "version": "4.0.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "ssh2shell", - "version": "3.3.0", + "version": "4.0.0", "license": "ISC", "dependencies": { "ssh2": "^1.4.0" diff --git a/package.json b/package.json index 9b9107c..ab43467 100644 --- a/package.json +++ b/package.json @@ -1,11 +1,12 @@ { "name": "ssh2shell", - "version": "3.3.0", + "version": "4.0.0", "author": "cmp-202", "description": "A wrapper class for ssh2 to run multiple sequential commands in an SSH shell session, handle command responses, and tunnel through to other hosts using nested host objects", "main": "./lib/ssh2shell.js", "files": [ - "lib" + "lib", + "CHANGELOG.md" ], "engines": { "node": ">=18.0.0" 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..7d536c3 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, @@ -69,62 +69,46 @@ class SSH2Shell extends Stream { constructor(hosts) { super(hosts); - // Methods that were CoffeeScript fat-arrows are bound in the constructor. - // Keep the same list and order so callbacks and event listeners keep - // their `this`. - this._connect = this._connect.bind(this); + // Public entry points keep own bound copies so they can be detached and + // passed around. `_connect` and `_connectHop` are passed as bare callbacks + // to the host queue. Default event handlers are bound so the emitter can + // invoke them with this instance. this.connect = this.connect.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); - this._runCommand = this._runCommand.bind(this); - this._checkCommand = this._checkCommand.bind(this); - this._nextCommand = this._nextCommand.bind(this); - this._commandComplete = this._commandComplete.bind(this); - this._finalizeHost = this._finalizeHost.bind(this); - this._finalizeRun = this._finalizeRun.bind(this); - this._mergeNestedText = this._mergeNestedText.bind(this); - this._applyHandlerFlags = this._applyHandlerFlags.bind(this); - this._resetRunState = this._resetRunState.bind(this); - this._callFinalCallback = this._callFinalCallback.bind(this); - this._beginStopExit = this._beginStopExit.bind(this); - this._finishStop = this._finishStop.bind(this); - this._forceStop = this._forceStop.bind(this); - this._clearStopTimer = this._clearStopTimer.bind(this); - this._armStopTimer = this._armStopTimer.bind(this); - this._prepareGracefulClose = this._prepareGracefulClose.bind(this); - this._clearCloseTimer = this._clearCloseTimer.bind(this); - this._armCloseTimer = this._armCloseTimer.bind(this); - 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); - this._onData = this._onData.bind(this); - this._callback = this._callback.bind(this); - 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.ssh2Client = require('ssh2').Client; - this._hosts = typeIsArray(hosts) && hosts.length > 0 ? hosts : [hosts]; + this._connect = this._connect.bind(this); + this._connectHop = this._connectHop.bind(this); + this._defaultOnCommandProcessing = this._defaultOnCommandProcessing.bind(this); + this._defaultOnCommandComplete = this._defaultOnCommandComplete.bind(this); + this._defaultOnCommandTimeout = this._defaultOnCommandTimeout.bind(this); + // Internal test seam. Not part of the public API. + this._ssh2Client = require('ssh2').Client; + + // 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 +128,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; @@ -156,6 +139,22 @@ class SSH2Shell extends Stream { // merging are idempotent across the normal path and an abrupt close. this._finalizedHosts = new Set(); this._mergedHosts = new Set(); + // Instance defaults are own properties from construction. CoffeeScript + // class-body values used to be shared through the prototype until the first + // host load, which aliased `_stream` between instances. + this._callback = null; + this.command = ''; + this._primaryhostSessionText = ''; + this._stream = {}; + this._buffer = ''; + this.idleTime = 5000; + this.dataIdleTime = 500; + this.idleTimer = null; + this.dataReceivedTimer = null; + this.asciiFilter = ''; + this.textColorFilter = ''; + this.passwordPrompt = ''; + this.standardPrompt = ''; this._loadDefaultListeners(); } @@ -165,9 +164,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 +187,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,91 +220,408 @@ 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; } - _boundListener ( eventName, listener, prepend = false ) { - if ( typeof listener === `function` ){ - // Avoid attaching the same handler twice when _loadDefaults runs again. - if (this._boundListeners[eventName] === listener) { - return; + // A real shell stream exists only after `connection.shell` succeeds. Before + // that, the active stream is the `{}` placeholder. + _hasLiveStream() { + 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; } - this._boundListeners[eventName] = listener; - if (prepend) { + 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); } } - - return; } - // A real shell stream exists only after `connection.shell` succeeds. Before - // that, `_stream` is the prototype `{}` placeholder. - _hasLiveStream() { - return Boolean(this._stream && typeof this._stream.close === 'function'); + // 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; } - - // Helper to safely detach listeners using cached references - _detachListener(eventName, currentKey) { - const cachedHandler = this._boundListeners[eventName]; - const hostHandler = this.sshObj ? this.sshObj[currentKey] : undefined; - let removed = false; - - if (typeof cachedHandler === 'function') { - this.removeListener(eventName, cachedHandler); - delete this._boundListeners[eventName]; // clear cache item - removed = true; - } - if (typeof hostHandler === 'function' && hostHandler !== cachedHandler) { - this.removeListener(eventName, hostHandler); - removed = true; - } - - return removed; - }; - + + _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`; `userName` / `passPhrase` are the public names. + _normalizeServer(server) { + const options = Object.assign({}, server || {}); + delete options.ssh; + if (!options.username) { + options.username = options.userName; + } + 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) { + // `command` and `_buffer` are instance aliases for the active host. Save + // the ancestor's values before the child replaces them so restoring the + // parent after a hop resumes its own command state. + parent.command = this.command; + parent.buffer = this._buffer; + 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, + command: '', + buffer: '', + 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; + this.command = typeof context.command === 'string' ? context.command : ''; + this._buffer = typeof context.buffer === 'string' ? context.buffer : ''; + + // 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; + } + // Host prefixes disambiguate messages when the session can span more than // one host. A single host reads better without repeating its address on // every line. Nested hosts keep the prefix, including after their queue has @@ -439,25 +767,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 +801,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 +816,11 @@ class SSH2Shell extends Stream { } }, this.idleTime); - return this.idleTimer; + if (context) { + context.idleTimer = timer; + } + this.idleTimer = timer; + return timer; } _onData(data) { @@ -492,15 +831,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 +847,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 +857,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 +916,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 +936,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 +1094,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 +1204,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; } @@ -1020,15 +1221,9 @@ class SSH2Shell extends Stream { sshObj.skipPrimaryHosts = false; } - if (sshObj.abort || sshObj.stop) { - const reason = - typeof sshObj.abort === 'string' - ? sshObj.abort - : typeof sshObj.stop === 'string' - ? sshObj.stop - : 'command-failed'; + if (sshObj.abort) { + const reason = typeof sshObj.abort === 'string' ? sshObj.abort : 'command-failed'; sshObj.abort = false; - sshObj.stop = false; this.stop(reason); } } @@ -1103,7 +1298,6 @@ class SSH2Shell extends Stream { if (isCommandWrite) { this.sshObj.commandTimeoutAttempt = 0; this.sshObj.retryCommandTimeout = undefined; - this._commandSawData = false; this._stderrBuffer = ''; } @@ -1114,13 +1308,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 +1329,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 +1342,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 +1384,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 +1417,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 +1443,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 +1478,68 @@ 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.command = ''; + 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 +1553,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 +1611,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 +1643,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 +1667,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 +1687,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 +1722,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 +1783,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 +1856,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 +1864,63 @@ 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.command = ''; + 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 +1928,6 @@ class SSH2Shell extends Stream { return; } - this._loadDefaults(); - if (typeof action === 'function') { return action(); } @@ -1708,182 +1948,239 @@ 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() { - // `idleTimeOut` is the documented key; `idleTime` is a legacy alias. - const idleTimeOut = - toPositiveNumber(this.sshObj.idleTimeOut) || - toPositiveNumber(this.sshObj.idleTime); + _applyHostTimerValues(host = this.sshObj) { + const idleTimeOut = toPositiveNumber(host.idleTimeOut); if (idleTimeOut > 0) { this.idleTime = idleTimeOut; } - // 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); + const dataIdleTimeOut = toPositiveNumber(host.dataIdleTimeOut); if (dataIdleTimeOut > 0) { this.dataIdleTime = dataIdleTimeOut; } } - _loadDefaults() { + // Default command handlers. They live on the prototype and are bound in the + // constructor; a host overrides them per record without mutating the config. + _defaultOnCommandProcessing() {} + + _defaultOnCommandComplete() { + this._systemMsg('debug', `onCommandComplete:`); + } + + _defaultOnCommandTimeout(command, response, stream, connection, details) { + // With `commandTimeoutRetries` configured, only the final attempt closes + // the run. The library re-arms the timer for earlier attempts. + if (details && details.final === false) { + this._systemMsg( + 'debug', + `loadDefaults: Class.commandTimeout retry ${details.attempt}/${details.maxRetries}` + ); + return; + } + + response = response.replace(this.command, ''); + this._systemMsg('debug', `loadDefaults: Class.commandTimeout`); + + this._systemMsg( + 'verbose', + `loadDefaults: Timeout command: ${command} response: ${response}` + ); + + this.emit( + 'error', + `${this.host}: Command timed out after ${this.idleTime / 1000} seconds`, + 'Command Timeout', + true, + (err, type) => { + this.sshObj.sessionText += this._buffer; + this._buffer = ''; + } + ); + } + + // 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; + // A host `onMsg` handler replaces the instance fallback while the record is + // active. `_removeListeners` restores the fallback when the record leaves. + const onMsg = typeof host.onMsg === 'function' ? host.onMsg : null; + const previousMsg = record.listeners.msg; + if (previousMsg && previousMsg !== onMsg) { + this.removeListener('msg', previousMsg); + delete record.listeners.msg; } - - 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); + if (onMsg) { + if (this.listeners('msg').includes(this.msg)) { + this.removeListener('msg', this.msg); + } + this._bindHostListener(record, 'msg', onMsg); + } 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}` ); } - // Listener defaults for command processing. - this.sshObj.onCommandProcessing = - this.sshObj.onCommandProcessing ?? - ((command, response, sshObj, stream) => {}); - - this.sshObj.onCommandComplete = - this.sshObj.onCommandComplete ?? - ((command, response, sshObj) => { - this._systemMsg('debug', `onCommandComplete:`); - }); - - this.sshObj.onCommandTimeout = - this.sshObj.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. - if (details && details.final === false) { - this._systemMsg( - 'debug', - `loadDefaults: Class.commandTimeout retry ${details.attempt}/${details.maxRetries}` - ); - return; - } - - response = response.replace(this.command, ''); - this._systemMsg('debug', `loadDefaults: Class.commandTimeout`); - - this._systemMsg('verbose',`loadDefaults: Timeout command: ${command} response: ${response}`); - - this.emit( - 'error', - `${this.host}: Command timed out after ${this.idleTime / 1000} seconds`, - 'Command Timeout', - true, - (err, type) => { - this.sshObj.sessionText += this._buffer; - this._buffer = ''; - } - ); - }); - - // Explicitly cache references right before binding them to the event emitter - if (typeof this.sshObj.onKeyboardInteractive === 'function') { - this._boundListener('keyboard-interactive', this.sshObj.onKeyboardInteractive); - } - if (typeof this.sshObj.onError === 'function') { + // 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; + + // Resolve the command handlers for this record. Defaults are not written + // back to the host config, so reusing a host object with another instance + // does not retain the first instance's closures. + const onCommandProcessing = + typeof host.onCommandProcessing === 'function' + ? host.onCommandProcessing + : this._defaultOnCommandProcessing; + const onCommandComplete = + typeof host.onCommandComplete === 'function' + ? host.onCommandComplete + : this._defaultOnCommandComplete; + const onCommandTimeout = + typeof host.onCommandTimeout === 'function' + ? host.onCommandTimeout + : this._defaultOnCommandTimeout; + + // 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 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', onCommandProcessing); + this._bindHostListener(record, 'commandComplete', onCommandComplete); + this._bindHostListener(record, 'commandTimeout', 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 +2194,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; + } + + 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; + } + + 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; + } - this.connection = new this.ssh2Client(); + // 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; - this.connection.on( + 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,201 +2343,224 @@ 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. + } + } + }); + }); } } -// Class-body properties in the CoffeeScript source become prototype -// properties. They are intentionally shared until an instance assigns an own -// value, matching the baseline (and its known prototype-state quirk). -SSH2Shell.prototype.sshObj = {}; -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 () {}; -SSH2Shell.prototype.onCommandComplete = function () {}; -SSH2Shell.prototype.onCommandTimeout = function () {}; -SSH2Shell.prototype.onEnd = function () {}; - module.exports = SSH2Shell; diff --git a/src/ssh2shell/defaults.js b/src/ssh2shell/defaults.js index e67860b..3b54087 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,9 +79,6 @@ function applyHostDefaults(sshObj) { if (typeof sshObj.sudoFailed !== 'boolean') { sshObj.sudoFailed = false; } - if (sshObj.server.hashKey == null) { - sshObj.server.hashKey = ''; - } if (!sshObj.sessionText) { 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..575eed6 100644 --- a/test/README.md +++ b/test/README.md @@ -1,8 +1,9 @@ # Testing ssh2shell -This folder holds the offline test suites and the local environment used for -live tests against real VMs. The main [README](../README.md) covers the library -API; start here when you need to run, rebuild, or extend the tests. +This folder holds the offline test suites and the environment used for live +tests. Locally they run against the provisioning VMs; CI starts throwaway `sshd` +hosts on the runner. The main [README](../README.md) covers the library API; +start here when you need to run, rebuild, or extend the tests. ## Layout @@ -38,10 +39,28 @@ 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. +## Test workflow + +Use the fastest suite that covers the change, and save the slow checks for +boundaries: + +1. **Every small block:** run the full offline suite (`npm run test:src`). It is + fast and catches regressions in unrelated areas. +2. **End of a change:** run only the live tests that exercise the changed path, + for example `node scripts/run-live.js timeout timeout_retries command_timeout` + for timeout work. +3. **Commit, release, or moving to another development area:** run the full live + suite (`node scripts/run-live.js --all`), plus provisioning when the change + affects connection setup or the provisioned environment. + +The live suite grows over time, so a full run at the end of every block is mostly +waiting. Targeted runs keep the feedback loop short; the full run at boundaries +keeps the release honest. + ## Live tests The live suite logs in to the three test VMs and exercises real prompts, sudo, @@ -54,8 +73,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 +97,80 @@ 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: