Documentation/Compared with ssh2

Compared with ssh2

@xec-sh/ssh derives its private wire implementation from ssh2 1.17.0. It combines that protocol lineage with the connection, trust, streaming and ownership mechanisms previously maintained inside Xec Core. The high-level client also retains the MIT attribution for its node-ssh lineage.

The comparison below concerns that pinned upstream release and Xec's developing 0.13.0 source. It does not assert that upstream is abandoned, that every later upstream commit has the same defects, or that Xec is a drop-in replacement. PROVENANCE.json records the source and reviewed patch lineage; upstream notices remain in the package.

Architectural differences

Concernssh2 1.17.0@xec-sh/ssh
ScopeClient, server and helper agentsClient connections, channels, SFTP, pooling and forwarding
Public APIEvent/callback transport API; external TypeScript declarationsESM, owned TypeScript contracts, Promise operations and typed streams
Host trustCaller supplies verification policyStrict known_hosts by default; explicit pin or custom verifier
ConnectionsCaller manages reuse and retirementLeases, capacity reservations, current trust and key identity
Remote effectsApplication interprets transport eventsExplicit unknown outcomes; no automatic command replay
Crypto distributionOptional native bindings and JavaScript pathsRuntime cryptography; owned OpenSSH key derivation; no addon or install build
AlgorithmsIncludes compatibility algorithms and compressionNarrow capability-checked policy; see negotiation
IntegrationConsumers construct their own ownership layerCore delegates SSH mechanics to the same standalone package

Upstream already provides real SSH multiplexing, PTYs, SFTP, forwarding and backpressure. Those capabilities are inherited and adapted, not inventions of this fork. The change is their ownership, supported policy, public contract and qualification. See upstream's API and cryptographic implementation.

Concrete fixes and checks

The following cases have specific regression oracles. An upstream report is context; a passing check must exercise the candidate's actual implementation.

BoundaryFailure being addressedRequired behavior
Channel openingZero packet size can prevent send progress (1504)Reject the peer's invalid channel parameters
Receive creditExcess data can drive a window negative (1505)Refuse excess bytes before delivery; preserve valid credit
Send creditWindow adjustment can overflow the protocol rangeReject overflow; do not inflate usable credit
Parked writesClosing a channel can leave a queued writer unresolved (1509)Settle owned writes on terminal closure
Packet encryptionNested writes can reuse mutable nonce state (1523)Reserve nonce/counter state before callbacks
SFTP closureServer-initiated close can lack acknowledgement (1522)Reply once and settle pending operations
SFTP streamsPending OPEN/CLOSE and cancellation can leave handles unresolvedPreserve acknowledgement and cleanup ownership
Host trustCached decisions, revoked entries and first-use racesObserve current revocation; serialize and confirm first-use writes
Host patternsBacktracking regular expressions can monopolize CPUBounded wildcard matching
Key decodingPEM-shaped text can be mistaken for a valid keyDecode and validate actual key material
Agent signingOversized frames or mismatched returned algorithmsBound input and validate the signature contract
DispatchLost completion can be mistaken for safe failureReport unknown outcome and prohibit blind replay

Not all rows are upstream defects. Host trust, connection leases, key-file access and outcome classification also correct or consolidate Xec's former wrapper. This distinction matters when assessing both provenance and impact.

Intentional compatibility changes

The package has no public Server, HTTPAgent, HTTPSAgent, Pageant bridge or Cygwin bridge. It does not retain old Node compatibility branches, PuTTY PPK, SHA1 signatures, DSA, CBC/RC4 or compression. There is no public import path into the wire engine.

Some upstream private protocol files remain JavaScript; public API declarations are maintained in TypeScript. The package is not described as a complete TypeScript rewrite. It has no external npm runtime dependencies. Native IEEE-P1363 signatures remove the ASN.1 dependency; the narrow, attributed OpenSSH bcrypt implementation uses native SHA512 instead of TweetNaCl. Inherited source remains documented in the license and provenance files.

A server that requires a removed algorithm fails negotiation. Fix that server's policy or select another explicitly approved client; there is no silent compatibility fallback.

Migrating an application

Previous useCurrent API
new ssh2.Client() and ready callbackawait new SSHClient().connect(config)
Xec NodeSSH from @xec-sh/core/sshSSHClient from @xec-sh/ssh
execCommand(command)exec(command, options)
Low-level cwd or argv concatenationCore $.ssh(target).cd(path) and tagged templates
Raw transport handleTyped channel/subsystem/forwarding methods
Per-application connection mapSSHConnectionPool and explicit leases
Root-only pnpm patchOwned source and the normal published SSH archive
Inferred success after disconnectInspect outcome, reconcile remote state, then decide

Custom host verifiers receive raw key bytes and return a boolean or Promise. Hash selection and transport callback overloads are removed. Do not port hostVerifier: () => true as a convenience: provision known hosts or an independently verified pin.

No throughput or startup superiority is asserted without comparable measurements. Fewer ownership layers and no native installation build are structural changes; actual latency depends on the runtime, server and workload.

Verification boundaries

The source includes native crypto/key/agent/protocol tests, an independent ssh2 server fixture, connection and cancellation regressions, and a packed-consumer gate. The latter must install the exact Core and SSH archives being released, rather than repack an unqualified variant.

Runtime interoperability checks and source tests do not replace Linux/Windows CI or installed-artifact acceptance. A successful release gate qualifies those exact bytes and scenarios, not every possible peer or a production fleet.

See also

MADE FOR BUILDERS.Static pages. Local search. Built with Lumen + Prism.