101 lines
4.6 KiB
Markdown
101 lines
4.6 KiB
Markdown
# bare-ssh2
|
||
|
||
This is a **Bare-native port** of the excellent [ssh2](https://github.com/mscdex/ssh2) library by Brian White (mscdex). It exposes the same public API (`Client`, `Server`, agents, `utils`, SFTP helpers, etc.) so code written for `ssh2` can switch the import to `bare-ssh2` and run on the [Bare](https://github.com/holepunchto/bare) / Pear runtime.
|
||
|
||
On **Node.js**, builtin modules are still used (via the `default` branch of this package’s `imports` map), so the same package can be tried on Node for comparison; primary support targets **Bare**.
|
||
|
||
## Installation
|
||
|
||
```bash
|
||
npm install bare-ssh2
|
||
```
|
||
|
||
## Drop-in usage
|
||
|
||
Replace `ssh2` with `bare-ssh2`:
|
||
|
||
```js
|
||
const { readFileSync } = require('fs')
|
||
const { Client } = require('bare-ssh2')
|
||
|
||
const conn = new Client()
|
||
conn
|
||
.on('ready', () => {
|
||
conn.exec('uptime', (err, stream) => {
|
||
if (err) throw err
|
||
stream
|
||
.on('close', (code, signal) => {
|
||
console.log('close', code, signal)
|
||
conn.end()
|
||
})
|
||
.on('data', (data) => console.log('STDOUT:', data.toString()))
|
||
stream.stderr.on('data', (data) => console.log('STDERR:', data.toString()))
|
||
})
|
||
})
|
||
.connect({
|
||
host: 'example.com',
|
||
port: 22,
|
||
username: 'you',
|
||
privateKey: readFileSync('/path/to/key')
|
||
})
|
||
```
|
||
|
||
ESM interop follows your bundler/runtime rules for loading this **CommonJS** package.
|
||
|
||
## How it maps Node builtins on Bare
|
||
|
||
Inside this package, `require('net')`, `require('dns')`, and other Node core names are resolved using `package.json` **`imports`** with the **`bare`** condition to [bare-node-\*](https://github.com/holepunchto/bare-node) wrappers. You do not need to change those specifiers in application code that only imports `bare-ssh2`.
|
||
|
||
**`crypto`:** Bare’s module resolver does not apply this package’s `imports` map to dependencies such as `tweetnacl` (used by `bcrypt-pbkdf`). This package therefore depends on a small local **[`shims/crypto`](shims/crypto/)** package (published as the `crypto` dependency) built on **`bare-crypto`**, with **`getCiphers()`** / **`getHashes()`** lists implemented in [`shims/crypto/lists.js`](shims/crypto/lists.js). The **`bare`** `imports` entry for `crypto` points at the same shim so library code and transitive deps share one implementation.
|
||
|
||
**`assert` / `buffer`:** Declared as **`npm:bare-node-*`** aliases so `asn1` and `safer-buffer` resolve them on Bare.
|
||
|
||
**Buffer:** [`lib/buffer-polyfill.js`](lib/buffer-polyfill.js) adds Node’s `utf8Write` / `latin1Write` / `*Slice` helpers when missing (loaded from `lib/index.js`, `client.js`, `server.js`, `keygen.js`, and `protocol/keyParser.js`).
|
||
|
||
The optional **ssh2** native crypto binding and **`cpu-features`** optional dependency from upstream are **not** used here. For **ChaCha20** packet encryption without OpenSSL, the **`chacha20`** npm package is used when `createCipheriv('chacha20', …)` is unsupported.
|
||
|
||
## API documentation
|
||
|
||
See the upstream [ssh2 README](https://github.com/mscdex/ssh2/blob/master/README.md) for the full API (client/server events, SFTP, forwarding, HTTP(S) agents, key utilities).
|
||
|
||
## Testing
|
||
|
||
From this package directory after `npm install`:
|
||
|
||
```bash
|
||
npm test
|
||
```
|
||
|
||
This runs **Prettier**, then **`bare test/test-protocol-crypto.js`**, then **`node test/test-protocol-keyparser.js`** (key parser sign/verify checks currently match Node’s OpenSSL more closely than Bare’s crypto for some ECDSA/OpenSSH fixtures).
|
||
|
||
Other useful commands:
|
||
|
||
```bash
|
||
bare test/test-protocol-crypto.js
|
||
npm run test:all
|
||
```
|
||
|
||
`npm run test:all` runs Prettier and **`bare test/test.js`**, which spawns every `test-*.js` (needs OpenSSH, keys, etc. where applicable).
|
||
|
||
```bash
|
||
npm run test:node
|
||
```
|
||
|
||
runs the same driver under Node.
|
||
|
||
### Known gaps on Bare
|
||
|
||
- **RC4 (`arcfour`)** and some legacy ciphers are not implemented in **bare-crypto**; they are omitted from negotiation when unsupported.
|
||
- **ECDSA signing** for some OpenSSH private key paths may differ between Bare and Node; report issues with minimal key fixtures if you hit this in production.
|
||
- Tests that shell out to **OpenSSH** or need a full **worker_threads** stack may fail unless the matching **bare-node-\*** test dependencies are installed.
|
||
- Default cipher/MAC lists follow **`getCiphers()`** / **`getHashes()`** from the crypto shim (subset of OpenSSL’s names).
|
||
- **SSH agent** helpers that use **`child_process`** depend on **bare-subprocess**; Windows-specific paths (Pageant, Cygwin) may differ from Node.
|
||
|
||
## TypeScript
|
||
|
||
Upstream `ssh2` does not ship types. You can use **`@types/ssh2`** for typings against this API.
|
||
|
||
## License
|
||
|
||
**MIT** — same as the original ssh2 code. See [LICENSE](LICENSE) and [NOTICE](NOTICE).
|