ssh_tunnel_proxy 2.1.3 → 3.0.0

package/README.md

@@ -1,267 +1,415 @@
 # ssh_tunnel_proxy
-Initiate a ssh reverse tunnel proxy with forwarding ports
 
-ssh_tunnel_proxy is a wrapper to ssh2 that provides async functionality as well as an extension to the api to include methods to setup a list of proxy forwards, exec a list of commands or startup a terminal shell. To setup a ssh tunnel, parameters are suppled for host, port, authentication and a list of proxy ports or commands to invoke. If a ngrok api key is provided the host and port of the ngrok tunnel are obtained. If the connection is interrupted or connection errors occur, attempts are made re-establish the tunnel.
+SSH port forwarding for Node.js. You give it an SSH listener that already exists
+at `host:port`. It keeps local (`ssh -L`) and reverse (`ssh -R`) forwards up over
+that connection.
 
-In addition to the node api, a command line function called ssh-node2 is included to start ssh sessions in a manner similar to the ssh command line utility.
+```text
+  browser ──▶ 127.0.0.1:8280 ──▶ [ SSH ] ──▶ 127.0.0.1:8123 on the far side
+```
 
-### Command line examples
+The only runtime dependency is [`ssh2`](https://github.com/mscdex/ssh2).
 
-Initialize ssh2 command:
-```
-npm i ssh_tunnel_proxy -g
-```
-Connect to remote host and establish local forwards:
+## Why not `ssh -L`?
+
+OpenSSH already does the same forwarding. Use it when a single hop stays up and
+you are fine supervising the process yourself.
+
+This package is for the hop that does not stay up — a phone, a NAT mapping, a
+zrok or ngrok TCP share — and for code that has to *do something* when it drops.
 
+| `ssh -L` / `ssh -R` | `ssh_tunnel_proxy` |
+| --- | --- |
+| A process you start and hope stays running | An object with `connect()`, `close()`, and events |
+| Local port vanishes on drop (`ECONNREFUSED`, then a race to bind it again) | Listener stays bound in `degraded`; new clients fail fast; same port comes back |
+| `ServerAliveInterval` or a restart loop in a shell | Bounded reconnect with backoff, or a hard stop at `maxAttempts` |
+| stderr and exit codes | `TunnelError` with a stable `code` (`AUTH_FAILED`, `TARGET_UNREACHABLE`, …) |
+| One shared stream per reverse forward in naive wrappers | One SSH channel and one TCP socket per connection |
+| No picture of what is open | `getStatus()`, `listConnections()`, byte counts |
+
+It does not replace `sshd`, generate keys, or create the relay. It is the layer
+on top of an SSH listener that keeps forwards honest when the path is flaky.
+
+## Install
+
+```bash
+npm install ssh_tunnel_proxy
 ```
-ssh2-node -i ~/.ssh/<private_key> -L 8180:192.168.1.1:80 <username>@<hostname>
+
+The package includes `examples/tunnel-cli.js`. After `npm run build` (or from a
+clone), you can bring forwards up with no application code.
+
+## Quick start: the CLI
+
+Copy `examples/config.example.json`, point each `transport.endpoint` at a host
+that already speaks SSH, and give every service its own loopback listen port.
+
+```json
+[
+  {
+    "name": "pi-living",
+    "transport": {
+      "endpoint": { "host": "192.168.1.21", "port": 22 },
+      "username": "user",
+      "privateKey": { "source": "file", "value": "~/.ssh/id_ed25519" }
+    },
+    "localForwards": [
+      { "id": "ha", "listen": { "host": "127.0.0.1", "port": 8123 }, "target": { "host": "127.0.0.1", "port": 8123 } }
+    ]
+  },
+  {
+    "name": "pi-garage",
+    "transport": {
+      "endpoint": { "host": "192.168.1.22", "port": 22 },
+      "username": "user",
+      "privateKey": { "source": "file", "value": "~/.ssh/id_ed25519" }
+    },
+    "localForwards": [
+      { "id": "cameras", "listen": { "host": "127.0.0.1", "port": 8080 }, "target": { "host": "127.0.0.1", "port": 8080 } }
+    ],
+    "disabled": false
+  }
+]
 ```
 
-Connect to host with parameters stored in ~/.config/ssh_tunnel_proxy/config.json:
+The example CLI starts one `worker_threads` Worker per config entry, so
+each session has its own event loop. A blocked tick or a drop on one
+board does not stall the others, and a local port stays bound while that
+hop reconnects.
 
+```bash
+node examples/tunnel-cli.js --list -F ./config.json
+node examples/tunnel-cli.js all    -F ./config.json
 ```
-ssh2-node rh2
+
+`all` starts every entry that is not `"disabled": true`. Open
+`http://127.0.0.1:8123` and `http://127.0.0.1:8080` in a browser on this
+machine. Ctrl-C closes the lot.
+
+A single host, or an override without editing the file:
+
+```bash
+node examples/tunnel-cli.js pi-living -F ./config.json
+node examples/tunnel-cli.js pi-living -F ./config.json -L 9090:127.0.0.1:3000
+node examples/tunnel-cli.js user@192.168.1.21 -i ~/.ssh/id_ed25519 \
+    -L 8123:127.0.0.1:8123
 ```
 
-default config file, located at:
-~/.config/ssh_tunnel_proxy/config.json
+Config path: `-F` / `--config`, else `$SSH_TUNNEL_PROXY_CONFIG`, else
+`~/.config/ssh_tunnel_proxy/config.json`. v1 and v2 entry shapes are both
+accepted. The CLI is an example on purpose — the library itself still takes a
+`TunnelConfig` object and does not read a file.
+
+Two config entries are two SSH sessions — and two Workers — even if they
+point at the same host. That is how you isolate a filesystem mount from
+a database on one VPS. Give each entry its own listen ports.
+
 ```json
-[{
-  "hostname":"rh2",
-  "username": "<username>",
-  "proxy_ports": [
-    "8280:127.0.0.1:80",
-    "9000:127.0.0.1:9000",
-    "8122:192.168.2.1:22"
-  ],
-  "private_key_filename":"~/.ssh/<private key>",
-  "ngrok_api": "<ngrok api key>"
-}]
+[
+  {
+    "name": "vps-fs",
+    "transport": {
+      "endpoint": { "host": "host.example.net", "port": 22 },
+      "username": "user",
+      "privateKey": { "source": "file", "value": "~/.ssh/id_ed25519" }
+    },
+    "localForwards": [
+      { "id": "sshd", "listen": { "host": "127.0.0.1", "port": 2222 }, "target": { "host": "127.0.0.1", "port": 22 } }
+    ],
+    "portPolicy": { "allowedPrivilegedPorts": [22], "allowedRemoteHosts": ["127.0.0.1"] }
+  },
+  {
+    "name": "vps-mariadb",
+    "transport": {
+      "endpoint": { "host": "host.example.net", "port": 22 },
+      "username": "user",
+      "privateKey": { "source": "file", "value": "~/.ssh/id_ed25519" }
+    },
+    "localForwards": [
+      { "id": "mariadb", "listen": { "host": "127.0.0.1", "port": 13306 }, "target": { "host": "127.0.0.1", "port": 3306 } }
+    ]
+  }
+]
 ```
 
-Execute command on remote host
+```bash
+node examples/tunnel-cli.js all -F ./config.json
+sshfs -p 2222 user@127.0.0.1:/var/www ~/mnt/vps -o reconnect
+# MariaDB clients: 127.0.0.1:13306
 ```
-ssh2-node rh2 "ls -all"
+
+A flap on the SFTP hop does not take the database session with it.
+
+### Do not block the event loop
+
+`ssh2` and this library run on Node’s single JS thread. A synchronous
+`JSON.parse` of a large file, a tight CPU loop, or a giant
+`readFileSync` in the **same process** pauses *every* tunnel in that
+process: accepts, channel data, keepalives, and reconnect timers.
+
+The example CLI is safe because it only reads a small config and then
+moves bytes. If you embed `SSHTunnel` in an app that also parses,
+indexes, or transforms large payloads:
+
+- Prefer `worker_threads` (or a child process) for that work.
+- Keep the process that calls `connect()` dedicated to SSH and local
+  sockets.
+- Do not `JSON.parse` multi‑megabyte buffers on the tunnel tick.
+
+The example CLI already puts each session on its own Worker. If you
+embed `SSHTunnel` in a larger app, do the same — or use `worker_threads`
+for parse/CPU and keep one dedicated Worker (or process) per transport.
+
+## Quick start: the library
+
+Same forwards from your own process, for example Home Assistant at
+`127.0.0.1:8123`:
+
+```ts
+import { SSHTunnel, credential } from 'ssh_tunnel_proxy';
+
+const tunnel = new SSHTunnel({
+  transport: {
+    endpoint: { host: '127.0.0.1', port: 9191 },
+    username: 'user',
+    privateKey: credential.file('~/.ssh/id_ed25519'),
+  },
+  localForwards: [
+    {
+      id: 'home-assistant',
+      listen: { host: '127.0.0.1', port: 8123 },
+      target: { host: '127.0.0.1', port: 8123 },
+    },
+  ],
+});
+
+tunnel.on('error', (err) => console.error(err.code, err.message));
+await tunnel.connect();
+
+const { endpoint } = tunnel.resolveEndpoint('home-assistant');
+console.log(`open http://${endpoint.host}:${endpoint.port}`);
+
+await tunnel.close();
 ```
 
-### List of command-line options (compatible with original ssh2 command):
+`9191` is whatever local port your relay (zrok, ngrok, Tailscale, or a LAN
+address) already bound. This package does not create that listener.
+
+### Reverse forward
+
+Expose a process on this machine to the peer (`ssh -R`):
+
+```ts
+const status = await tunnel.addRemoteForward({
+  id: 'dev-server',
+  bind: { host: '127.0.0.1', port: 0 }, // 0 = peer chooses the port
+  target: { host: '127.0.0.1', port: 3000 },
+});
+
+console.log('peer is listening on', status.assignedPort);
 ```
-Usage: ssh2-node [options] [userhost] [exec...]
-
-Nodejs ssh2 command line client
-
-Arguments:
-  userhost                                          Connect to hostname in config.
-  exec                                              Command to exec on remote host (must be in quotes)
-
-Options:
-  -V, --version                                     output the version number
-  -2 --protocolv2 [protocolv2]                      Forces ssh to try protocol version 2 only.
-  -4 --ipv4only [ipv4only]                          Forces ssh to use IPv4 addresses only.
-  -6 --ipv6only [ipv6only]                          Forces ssh to use IPv6 addresses only.
-  -A --forward_enable [forward_enable]              Enables forwarding of the authentication agent
-                                                    connection.
-  -a --forward_disable [forward_disable]            Disables forwarding of the authentication agent
-                                                    connection.
-  -b --bind [bind]                                  bind_address
-  -C --compress [compress]                          Requests compression of all data
-  -c --cipher [cipher]                              cipher_spec
-  -D --dynamic_forward [dynamic_forward]             Specifies a local 'dynamic' application-level
-                                                    port forwarding.
-  -e --escape [escape]                              escape_char Sets the escape character for
-                                                    sessions with a pty.
-  -F --config [config]                              configfile
-  -f --background [background]                      Requests ssh to go to background just before
-                                                    command execution.
-  -g --local_forward_remote [local_forward_remote]  Allows remote hosts to connect to local forwarded
-                                                    ports.
-  -I --smartcard [smartcard]                        smartcard_device Specify the device ssh.
-  -i --identity [identity]                          Private key filename.
-  -K --gssapi_auth [gssapi_auth]                    Enables GSSAPI-based authentication and
-                                                    forwarding (delegation) of GSSAPI credentials to
-                                                    the server.
-  -k --gssapi_disable [gssapi_disable]              Disables forwarding (delegation) of GSSAPI
-                                                    credentials to the server.
-  -L --local_forward_out [local_forward_out...]     bind_address:port:host:hostport
-  -l --login_name [login_name]                      login_name
-  -M --master_mode [master_mode]                    Places the ssh client into 'master' mode for
-                                                    connection sharing. Multiple -M options
-  -m --mac_spec [mac_spec]                          mac_spec
-  -N --no_exec [no_exec]                            Do not execute a remote command.
-  -n --redirect_stdin [redirect_stdin]              Redirects stdin from /dev/null
-  -O --ctl_cmd [ctl_cmd]                            ctl_cmd
-  -o --option [option]                              option
-  -p --port [port]                                  port Port to connect to on the remote host.
-  -q --quiet [quiet]                                Quiet mode. Causes most warning and diagnostic
-                                                    messages to be suppressed.
-  -R --local_forward_in [local_forward_in...]       bind_address:port:host:hostport
-  -S --ctl_path [ctl_path]                          ctl_path Specifies the location of a control
-                                                    socket for connection sharing.
-  -s --subsystem [subsystem]                        May be used to request invocation of a subsystem
-                                                    on the remote system.
-  -T --disable_tty [disable_tty]                    Disable pseudo-tty allocation.
-  -t --force_tty [force_tty]                        Force pseudo-tty allocation.
-  -V --version [version]                            Display the version number and exit.
-  -v --verbose [verbose]                            Verbose mode. Causes ssh to print debugging
-                                                    messages about its progress.
-  -W --forward_stdin_stdout [forward_stdin_stdout]  host:port Requests that standard input and output
-                                                    on the client be forwarded to host on port ver
-                                                    the secure channel.
-  -w --tunnel [tunnel]                              Requests tunnel device forwarding with the
-                                                    specified tun(4) devices between the client
-                                                    (local_tun) and the server (remote_tun).
-  -X --x11 [x11]                                    Enables X11 forwarding.
-  -x --x11_disable [x11_disable]                    Disables X11 forwarding.
-  -Y --x11_trusted [x11_trusted]                    Enables trusted X11 forwarding.
-  -y --log [log]                                    Send log information using the syslog(3)
-  -H --ngrok [ngrok]                                Obtain connectiion hostport from ngrok
-  -J --keychain_service [keychain_service]          Service name to obtain private key from system
-                                                    keychain.
-  -j --keychain_account [keychain_account]          Account name to obtain private key from system
-                                                    keychain.
-  -h, --help                                        display help for command
+
+Each inbound connection gets its own SSH channel and its own TCP socket.
+
+### Several services on one transport
+
+```ts
+localForwards: [
+  { id: 'home-assistant', listen: { host: '127.0.0.1', port: 8123 }, target: { host: '127.0.0.1', port: 8123 } },
+  { id: 'cameras',        listen: { host: '127.0.0.1', port: 8080 }, target: { host: '127.0.0.1', port: 8080 } },
+]
 ```
-### Api examples
 
-Exec remote commands using async await and processing result through streams.
+Open `http://127.0.0.1:8123` and `http://127.0.0.1:8080` in a browser on this
+machine. Listeners bind loopback only.
 
-```js
-// send result of cmd through pipeline, generating a stream of json objects
-function lsTest(cmdProxy, cmd, destination) {
+## What this package does not do
 
-    return new Promise( (resolveCmd) => {
+See [MIGRATION.md](./MIGRATION.md) for the v1 mapping.
 
-             // set input of pipeline to split data into lines (npm i split)
-            const tunnel = split();
+| Out of scope | Do this instead |
+| --- | --- |
+| Key generation and keychains | `credential.file`, `credential.env`, `credential.agent`, or `credential.callback` |
+| Creating a zrok / ngrok / Tailscale share | Start the relay yourself, then pass `host:port` |
+| Interactive shells | Use `ssh`, or `tunnel.exec()` for one command |
+| Reading `~/.config/ssh_tunnel_proxy/config.json` | Pass a `TunnelConfig` object |
 
-            // when pipeline is ready exec shell cmd
-            const pipelineReady = (socket) => {
+## Using a TCP relay (zrok, ngrok, …)
 
-                return new Promise((resolve) => {
+1. On the host that runs `sshd` and the private apps, share the SSH port. With zrok:
 
-                  // invoke command on remote host and send results to pipeline
-                  cmdProxy.execCmd(cmd, tunnel)
+   ```bash
+   zrok share private --backend-mode tcpTunnel 127.0.0.1:22
+   ```
 
-                        // stream processing complete, cleanup pipeline and exit
-                        .then(() => {
-                            //self.cleanupPipeline(socket);
-                            resolveCmd();
-                        });
-                    resolve();
-                })
-            }
+2. On the machine that will run this library, bind that share locally and check
+   that it really is SSH:
 
-            // pipe shell cmd result through json parser pipeline to destination
-            pipeline(tunnel,
-                self.parse(),
-                self.toJSONString(),
-                destination,
-                pipelineReady
-            );
-    })
-}
+   ```bash
+   zrok access private --bind 127.0.0.1:9191 <share-token>
+   nc 127.0.0.1 9191    # must print SSH-2.0-...
+   ```
 
-async function runCmd() {
+3. Point `transport.endpoint` at `127.0.0.1:9191`.
 
-  const opts = {
-    "hostname":"rh2",
-    "username": "<username>",
-    "private_key_filename":"~/.ssh/<private key>",
-    "ngrok_api": "<ngrok api key>"
-  }
+A longer copy of this pattern is in `examples/zrok-termux.ts`.
+
+## API
+
+### `new SSHTunnel(config, options?)`
+
+`TunnelConfig` matches `proto/sshtunnel/v1/tunnel.proto`.
+
+| Method | Returns | Notes |
+| --- | --- | --- |
+| `connect()` | `Promise<TunnelStatus>` | Idempotent; concurrent calls share one attempt. |
+| `close()` | `Promise<TunnelStatus>` | Idempotent. Stops reconnect and closes everything. |
+| `addLocalForward(spec \| string)` | `Promise<ForwardStatus>` | Object or `"8280:127.0.0.1:8080"`. |
+| `addLocalForwards(specs[])` | `Promise<ForwardStatus[]>` | Atomic: one bind failure rolls all of them back. |
+| `addRemoteForward(spec \| string)` | `Promise<ForwardStatus>` | `bind.port: 0` → read `assignedPort`. |
+| `addRemoteForwards(specs[])` | `Promise<ForwardStatus[]>` | Atomic, as above. |
+| `removeForward(id)` | `Promise<ForwardStatus>` | Unbinds the listener and closes its connections. |
+| `resolveEndpoint(id)` | `{ endpoint, state }` | Where to connect, including a peer-assigned port. |
+| `getStatus()` | `TunnelStatus` | Tunnel + every forward. |
+| `getForwardStatus(id)` | `ForwardStatus` | One forward. |
+| `listConnections()` | `ConnectionStatus[]` | Live proxied connections and byte counts. |
+| `getState()` / `isReady()` | `TunnelState` / `boolean` | |
+| `exec(command, streams?)` | `Promise<{ code, stdout, stderr }>` | One command. No TTY. |
+
+### Events
+
+| Event | Payload | When |
+| --- | --- | --- |
+| `state` | `{ previous, current, reason? }` | Tunnel state change. |
+| `ready` | `TunnelStatus` | Transport up and forwards open. Also after a successful reconnect. |
+| `forward` | `{ status, previous }` | A forward changes state. |
+| `connection` | `{ status, previous }` | One proxied connection changes state. |
+| `reconnect` | `{ attempt, delayMs, cause? }` | A retry is scheduled. |
+| `error` | `TunnelError` | Always has a `code`. |
+| `close` | `TunnelStatus` | Reached `closed`. |
+| `debug` | `(message, ...args)` | Tracing. `options.debugSsh` enables ssh2 protocol logs. |
+
+### States
+
+```text
+tunnel      idle → connecting → ready ⇄ reconnecting → closing → closed
+                              ↘ failed
+
+forward     pending → opening → active ⇄ degraded → closing → closed
+                              ↘ failed
+
+connection  accepted → opening → piped → half_closed → closed
+                              ↘ failed
+```
 
-  const sshTunnelProxy = new SSHTunnelProxy();
+`degraded`: the local listener stays bound while SSH is down. New clients fail
+fast instead of getting `ECONNREFUSED` and racing to rebind. When SSH returns the
+same forward becomes `active` again.
 
-  // connect to remote host
-  await sshTunnelProxy.connectSSH(opts);
+### Errors
 
-  // invoke ls -all on remote host and parse result to json object string
-  await lsTest(sshTunnelProxy, 'ls -all', process.stdout);
+Branch on `err.code`, not on the message:
+
+```ts
+import { isTunnelError } from 'ssh_tunnel_proxy';
+
+try {
+  await tunnel.addLocalForward('80:127.0.0.1:8080');
+} catch (err) {
+  if (isTunnelError(err) && err.code === 'PORT_NOT_PERMITTED') {
+    // privileged listen port was not allowlisted
+  }
 }
+```
+
+`INVALID_FORWARD_SPEC`, `PORT_NOT_PERMITTED`, `HOST_NOT_PERMITTED`,
+`TRANSPORT_NOT_READY`, `AUTH_FAILED`, `LISTEN_FAILED`, `REMOTE_BIND_FAILED`,
+`CHANNEL_OPEN_FAILED`, `TARGET_UNREACHABLE`, `DUPLICATE_FORWARD_ID`,
+`UNKNOWN_FORWARD`, `CONNECTION_LIMIT`, `RECONNECT_EXHAUSTED`,
+`CREDENTIAL_UNRESOLVED`.
 
-runCmd();
+## Credentials
+
+The library only resolves a reference. It never writes a secret.
+
+```ts
+credential.file('~/.ssh/id_ed25519')
+credential.env('SSH_PRIVATE_KEY')
+credential.inline(pem)
+credential.agent()
+credential.callback('vault://key')   // needs options.credentialResolver
 ```
 
-Example of use of the api with electronjs.
+Optional host-key check:
 
-main.js:
-```js
+```ts
+transport: {
+  // ...
+  hostKeyFingerprints: ['sha256:47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU'],
+}
+```
 
-async function init_sshTunnelProxy(win) {
+Omit fingerprints only on a path that is already authenticated (a private share).
 
-  const { SSHTunnelProxy } = require('ssh_tunnel_proxy');
-  const sshTunnelProxy = new SSHTunnelProxy();
-  
-  ipcMain.on('connect_ssh_sync', async function(event,opts) {
-    // only allow connection on remote server to system ports http,https,ssh and user ports >1023
-    const portWhitelist = {
-      80:true,
-      443:true,
-      22:true
-    }
-    await sshTunnelProxy.connectSSH(opts, portWhitelist);
-    event.returnValue = 'connected';
-  });
+## Port policy
 
-  ipcMain.on('generate_keypair', async (event, ...args) => await sshTunnelProxy.generateAndStoreKeypair(...args));
+Local listen ports and remote target ports are separate decisions. Local listeners
+must be loopback (`127.0.0.1` or `::1`).
 
-  ipcMain.on('get_public_key', async (event, ...args) => await sshTunnelProxy.getPublicKey(...args));
+```ts
+portPolicy: {
+  allowedPrivilegedPorts: [22, 80, 443],
+  allowedLocalListenPorts: [8123, 8080],
+  allowedRemoteTargetPorts: [8123, 8080, 22],
+  allowedRemoteHosts: ['127.0.0.1', '192.168.1.1'],
+}
+```
+
+Order: valid TCP port (remote bind may be `0`); ports below 1024 need
+`allowedPrivilegedPorts`; a non-empty role list must include the port. No policy
+means any unprivileged port, no privileged port.
 
-  ipcMain.on('network_online', (event, ...args) => sshTunnelProxy.onNetworkOnline(...args));
+## Data model
 
-  ipcMain.on('network_offline', (event, ...args) => sshTunnelProxy.onNetworkOffline(...args));
+`proto/sshtunnel/v1/tunnel.proto` is the cross-language source of truth.
+`src/model.ts` is a hand-written TypeScript projection; a unit test fails if they
+drift. The runtime does not depend on protobuf.
 
-  sshTunnelProxy.on('ready',(...args) => win.webContents.send('ready',...args));
+## Migrating from v1
 
-  sshTunnelProxy.on('debug',(...args) => win.webContents.send('debug',...args));
+`SSHTunnelProxy` still exists:
 
-  sshTunnelProxy.on('error',(...args) => win.webContents.send('error',...args));
+```ts
+import { SSHTunnelProxy } from 'ssh_tunnel_proxy';
 
-};
+const proxy = new SSHTunnelProxy();
+proxy.on('ssh_tunnel_ready', () => console.log('up'));
+await proxy.connectSSH(
+  {
+    username: 'user',
+    host: '127.0.0.1',
+    port: '9191',
+    private_key_filename: '~/.ssh/id_ed25519',
+    proxy_ports: ['8123:127.0.0.1:8123'],
+  },
+  { 22: true, 80: true, 443: true },
+);
 ```
 
-preload.js:
-```js
-const { contextBridge, ipcRenderer } = require('electron')
-
-contextBridge.exposeInMainWorld('sshModule', {
-    connect_ssh_sync: opts => ipcRenderer.sendSync('connect_ssh_sync', opts),
-    generate_keypair: (...args) => ipcRenderer.sendSync("generate_keypair", ...args),
-    get_public_key: (...args) => ipcRenderer.sendSync("get_public_key", ...args),
-    network_online: (...args) => ipcRenderer.send("network_online", ...args),
-    network_offline: (...args) => ipcRenderer.send("network_offline", ...args),
-    ready: (callback) => ipcRenderer.on('ready', callback),
-    debug: (callback) => ipcRenderer.on('debug', callback),
-    error: (callback) => ipcRenderer.on('error', callback)
-});
+`ngrok_api`, `service_name`, and `shell` throw. Details in
+[MIGRATION.md](./MIGRATION.md).
+
+## Development
+
+```bash
+npm install
+npm run build
+npm test
 ```
 
-// render process
-```js
-// initialize ssh message handlers
-sshModule.ready((event, data) => {
-});
-sshModule.debug((event,msg)=>{
-})
-sshModule.error((event,err)=>{
-});
+Integration tests run an in-process `ssh2.Server`. No external `sshd` or network
+is required.
 
-// options for connect_ssh_sync
-var sshParams = {
-  "username": "<username>",
-  "password": "",
-  "host": "",
-  "port": "",
-  "proxy_ports": [
-    "8280:127.0.0.1:80",
-    "9000:127.0.0.1:9000",
-    "8122:192.168.2.1:22"
-  ],
-  "service_name": "service",
-  "server_name": "server",
-  "ngrok_api": "<ngrok_api_key>"
-};
-
-// initate ssh tunnel
-sshModule.connect_ssh_sync(sshParams);
-```
+## License
+
+MIT. See [LICENSE](./LICENSE).

package/build/bridge.d.ts

@@ -0,0 +1,14 @@
+import type { Client } from 'ssh2';
+import type { TunnelError } from './errors';
+import type { ConnectionState, ConnectionStatus, ForwardState, ForwardStatus } from './model';
+export interface TransportBridge {
+    /** The live SSH client, or throw TRANSPORT_NOT_READY. */
+    requireClient(forwardId: string): Client;
+    /** The live SSH client, or undefined when the transport is down. */
+    peekClient(): Client | undefined;
+    onConnectionChanged(status: ConnectionStatus, previous: ConnectionState): void;
+    onForwardChanged(status: ForwardStatus, previous: ForwardState): void;
+    onError(error: TunnelError): void;
+    debug(message: string, ...args: unknown[]): void;
+}
+//# sourceMappingURL=bridge.d.ts.map

package/build/bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge.d.ts","sourceRoot":"","sources":["../src/bridge.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAEnC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAC5C,OAAO,KAAK,EACV,eAAe,EACf,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACd,MAAM,SAAS,CAAC;AAEjB,MAAM,WAAW,eAAe;IAC9B,yDAAyD;IACzD,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;IACzC,oEAAoE;IACpE,UAAU,IAAI,MAAM,GAAG,SAAS,CAAC;IACjC,mBAAmB,CAAC,MAAM,EAAE,gBAAgB,EAAE,QAAQ,EAAE,eAAe,GAAG,IAAI,CAAC;IAC/E,gBAAgB,CAAC,MAAM,EAAE,aAAa,EAAE,QAAQ,EAAE,YAAY,GAAG,IAAI,CAAC;IACtE,OAAO,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,CAAC;IAClC,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;CAClD"}

package/build/bridge.js

@@ -0,0 +1,12 @@
+"use strict";
+/*
+ * bridge.ts — the narrow surface a forward handle needs from its tunnel.
+ *
+ * Forward handles never reach into the tunnel, and the tunnel never reaches into
+ * a handle's sockets. Everything crosses this interface, which keeps the forward
+ * logic unit-testable against a fake transport.
+ *
+ * License: MIT
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=bridge.js.map

package/build/bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge.js","sourceRoot":"","sources":["../src/bridge.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG"}