ssh2web 1.0.0

package/README.md

@@ -0,0 +1,122 @@
+# SSH Client
+
+![Demo](static/img/demo.png)
+
+SSH-2 client library for the browser (or any environment with Web Crypto and WebSockets). Connects over a WebSocket transport, performs key exchange, public-key auth, and exposes a session API for reading/writing and PTY control. This was built for [Agentripper.com](https://agentripper.com) because other solutions did not satisfy our requirements.
+
+**Install:** `npm install ssh2web`  
+**Use in another project:** Point your bundler at the package or copy this directory; the package builds with `npm run build` (output in `dist/`).
+
+## Public API
+
+```typescript
+import { connectSSH } from "lib/sshClient"; // or your path to the lib
+
+const conn = await connectSSH(
+  ws,                                    // WebSocket (binary)
+  { username, certificate, privateKey },  // credentials
+  onError,                                // (err: string) => void
+  { cols, rows, onPtyDenied }            // optional: terminal size, pty callback
+);
+
+conn.onData(data => { /* handle server output */ });
+conn.write(userInput);
+conn.resize(cols, rows);
+conn.close();
+```
+
+Types: `SSHConnection`, `ConnectSSHOptions`, `SSHCredentials`. Errors: `SSHError`, `KEXError`, `AuthenticationError`, `MacVerificationError`, `ProtocolError`, `ChannelError`, `ParseError` (exported from the same module).
+
+## Architecture
+
+| Layer | Purpose |
+|-------|---------|
+| **domain/** | Models, constants, errors |
+| **crypto/** | Digest, cipher, MAC, DH/X25519, key derivation |
+| **protocol/** | Packet codec, serialization, deserialization |
+| **transport/** | AES-CTR + HMAC, sequence numbers |
+| **kex/** | KEXINIT builder, KEX state |
+| **auth/** | Auth state, cert parsing, PEM + Ed25519 sign |
+| **channel/** | Channel state |
+| **connection/** | Orchestrator and public types |
+
+## Directory layout
+
+```
+sshClient/
+  index.ts                   (public API)
+  ARCHITECTURE.md
+  REFACTORING.md
+  domain/                    constants, errors, models
+  crypto/                    digest, cipher, mac, arithmetic, keyexchange, keys (+ *.test.ts)
+  protocol/                  serialization, deserialization, codec, messages (+ *.test.ts)
+  transport/                  transportcipher (+ *.test.ts)
+  kex/                       kexstate, builder (+ *.test.ts)
+  auth/                      authstate, certparser, keys (+ *.test.ts)
+  channel/                   channelstate (+ *.test.ts)
+  connection/                connectSSH, connectionstate, types
+```
+
+## Testing
+
+From the repo root that contains this lib (e.g. `website/`):
+
+```bash
+npm run test
+```
+
+With coverage:
+
+```bash
+npm run test -- --coverage
+```
+
+### Coverage (Vitest, v8)
+
+Latest run (82 tests, 19 files):
+
+| Metric     | Coverage |
+|-----------|----------|
+| Statements| 43.1%    |
+| Branches  | 27.6%    |
+| Functions | 54.1%    |
+| Lines     | 43.4%    |
+
+| Area       | Stmts | Lines |
+|------------|-------|-------|
+| auth       | 90.5  | 88.2  |
+| crypto     | 100   | 100   |
+| domain     | 76.8  | 84.1  |
+| kex        | 82.4  | 78.6  |
+| protocol   | 73.9  | 78.3  |
+| transport  | 84.4  | 89.2  |
+| channel    | 50    | 50    |
+| connection | 1.0   | 1.1   (orchestrator largely integration) |
+
+Unit tests are colocated (`*.test.ts`). The connection orchestrator is exercised by end-to-end use; crypto, protocol, transport, auth, and state layers are unit-tested.
+
+## Design principles
+
+- **KISS** – Simple, direct implementations  
+- **Single responsibility** – One concern per module  
+- **Layered** – Domain to crypto to protocol to transport to connection  
+- **Test-friendly** – Layers testable in isolation  
+
+## Data flow
+
+```
+Caller
+  |
+  connectSSH(ws, creds) -> connection/connectSSH
+    - Version exchange (client/server ident)
+    - KEX (KEXINIT, KEXDH/KEX_ECDH, NEWKEYS)
+    - Key derivation, transport cipher
+    - Service request (ssh-userauth)
+    - USERAUTH (publickey, cert + signature)
+    - CHANNEL_OPEN session, pty-req, shell
+    - Returns SSHConnection
+         - write(data)
+         - onData(cb)
+         - resize(cols, rows)
+         - close()
+```

package/dist/auth/authstate.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Authentication state machine.
+ * Manages auth flow: service request → userauth → success/failure.
+ */
+export type AuthPhase = "init" | "service_requested" | "awaiting_pk_ok" | "signed" | "complete" | "failed";
+export interface AuthState {
+    phase: AuthPhase;
+    receivedPKOk: boolean;
+    error: string | null;
+}
+export declare function createAuthState(): AuthState;
+export declare function transitionAuthPhase(current: AuthPhase): AuthPhase;
+export declare function setAuthFailed(state: AuthState, error: string): AuthState;
+//# sourceMappingURL=authstate.d.ts.map

package/dist/auth/authstate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authstate.d.ts","sourceRoot":"","sources":["../../auth/authstate.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,mBAAmB,GAAG,gBAAgB,GAAG,QAAQ,GAAG,UAAU,GAAG,QAAQ,CAAC;AAE3G,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,SAAS,CAAC;IACjB,YAAY,EAAE,OAAO,CAAC;IACtB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED,wBAAgB,eAAe,IAAI,SAAS,CAM3C;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,SAAS,GAAG,SAAS,CAUjE;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,CAExE"}

package/dist/auth/authstate.js

@@ -0,0 +1,25 @@
+/**
+ * Authentication state machine.
+ * Manages auth flow: service request → userauth → success/failure.
+ */
+export function createAuthState() {
+    return {
+        phase: "init",
+        receivedPKOk: false,
+        error: null,
+    };
+}
+export function transitionAuthPhase(current) {
+    const transitions = {
+        "init": "service_requested",
+        "service_requested": "awaiting_pk_ok",
+        "awaiting_pk_ok": "signed",
+        "signed": "complete",
+        "complete": "complete",
+        "failed": "failed",
+    };
+    return transitions[current];
+}
+export function setAuthFailed(state, error) {
+    return { ...state, phase: "failed", error };
+}

package/dist/auth/certparser.d.ts

@@ -0,0 +1,9 @@
+/**
+ * SSH certificate parsing.
+ * Extracts key type and certificate blob from base64-encoded format.
+ */
+export declare function parseCertBase64(cert: string): {
+    keyType: string;
+    certBlob: Uint8Array;
+};
+//# sourceMappingURL=certparser.d.ts.map

package/dist/auth/certparser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"certparser.d.ts","sourceRoot":"","sources":["../../auth/certparser.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,UAAU,CAAA;CAAE,CAOvF"}

package/dist/auth/certparser.js

@@ -0,0 +1,13 @@
+/**
+ * SSH certificate parsing.
+ * Extracts key type and certificate blob from base64-encoded format.
+ */
+export function parseCertBase64(cert) {
+    const parts = cert.trim().replace(/\s+/g, " ").split(" ");
+    if (parts.length < 2)
+        throw new Error("Invalid certificate format");
+    const keyType = parts[0];
+    const b64 = parts[1].replace(/\s/g, "");
+    const certBlob = Uint8Array.from(atob(b64), (c) => c.charCodeAt(0));
+    return { keyType, certBlob };
+}

package/dist/auth/keys.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Certificate and private key parsing.
+ * Extracts key material from PEM and base64-encoded SSH certs.
+ */
+export declare function parsePemPrivateKey(pem: string): Promise<CryptoKey>;
+export declare function ed25519Sign(privateKey: CryptoKey, data: Uint8Array): Promise<Uint8Array>;
+//# sourceMappingURL=keys.d.ts.map

package/dist/auth/keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.d.ts","sourceRoot":"","sources":["../../auth/keys.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAMxE;AAED,wBAAsB,WAAW,CAAC,UAAU,EAAE,SAAS,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAK9F"}

package/dist/auth/keys.js

@@ -0,0 +1,18 @@
+/**
+ * Certificate and private key parsing.
+ * Extracts key material from PEM and base64-encoded SSH certs.
+ */
+export async function parsePemPrivateKey(pem) {
+    const m = pem.match(/-----BEGIN PRIVATE KEY-----([\s\S]*?)-----END PRIVATE KEY-----/);
+    if (!m)
+        throw new Error("Invalid PEM format");
+    const b64 = m[1].replace(/\s/g, "");
+    const der = Uint8Array.from(atob(b64), (c) => c.charCodeAt(0));
+    return crypto.subtle.importKey("pkcs8", der, { name: "Ed25519" }, false, ["sign"]);
+}
+export async function ed25519Sign(privateKey, data) {
+    const buffer = data.byteOffset === 0 && data.byteLength === data.buffer.byteLength
+        ? data.buffer
+        : data.slice().buffer;
+    return new Uint8Array(await crypto.subtle.sign({ name: "Ed25519" }, privateKey, buffer));
+}

package/dist/channel/channelstate.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Channel management state machine.
+ * Tracks channel lifecycle: open → pty_request → shell → data_exchange.
+ */
+export type ChannelPhase = "init" | "opening" | "open" | "pty_requested" | "shell_requested" | "active" | "closed";
+export interface ChannelState {
+    phase: ChannelPhase;
+    clientChannelId: number;
+    serverChannelId: number;
+    windowSizeLocal: number;
+    windowSizeRemote: number;
+    ptySent: boolean;
+    shellSent: boolean;
+}
+export declare function createChannelState(defaultWindowSize: number): ChannelState;
+export declare function transitionChannelPhase(current: ChannelPhase): ChannelPhase;
+export declare function adjustWindowSize(state: ChannelState, consumed: number): ChannelState;
+//# sourceMappingURL=channelstate.d.ts.map

package/dist/channel/channelstate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channelstate.d.ts","sourceRoot":"","sources":["../../channel/channelstate.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,eAAe,GAAG,iBAAiB,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAEnH,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,YAAY,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,gBAAgB,EAAE,MAAM,CAAC;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,wBAAgB,kBAAkB,CAAC,iBAAiB,EAAE,MAAM,GAAG,YAAY,CAU1E;AAED,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,YAAY,GAAG,YAAY,CAW1E;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,GAAG,YAAY,CAEpF"}

package/dist/channel/channelstate.js

@@ -0,0 +1,30 @@
+/**
+ * Channel management state machine.
+ * Tracks channel lifecycle: open → pty_request → shell → data_exchange.
+ */
+export function createChannelState(defaultWindowSize) {
+    return {
+        phase: "init",
+        clientChannelId: 0,
+        serverChannelId: 0,
+        windowSizeLocal: defaultWindowSize,
+        windowSizeRemote: defaultWindowSize,
+        ptySent: false,
+        shellSent: false,
+    };
+}
+export function transitionChannelPhase(current) {
+    const transitions = {
+        "init": "opening",
+        "opening": "open",
+        "open": "pty_requested",
+        "pty_requested": "shell_requested",
+        "shell_requested": "active",
+        "active": "active",
+        "closed": "closed",
+    };
+    return transitions[current];
+}
+export function adjustWindowSize(state, consumed) {
+    return { ...state, windowSizeLocal: state.windowSizeLocal - consumed };
+}

package/dist/connection/connectSSH.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Main SSH connection orchestrator.
+ * Entry point that coordinates all layers: domain, crypto, protocol, transport, state machines.
+ */
+import type { SSHConnection, ConnectSSHOptions } from "./types";
+import type { Credentials as SSHCredentials } from "../domain/models";
+export declare function connectSSH(ws: WebSocket, creds: SSHCredentials, onError?: (err: string) => void, options?: ConnectSSHOptions): Promise<SSHConnection>;
+//# sourceMappingURL=connectSSH.d.ts.map

package/dist/connection/connectSSH.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connectSSH.d.ts","sourceRoot":"","sources":["../../connection/connectSSH.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAChE,OAAO,KAAK,EAAE,WAAW,IAAI,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAoDtE,wBAAsB,UAAU,CAC9B,EAAE,EAAE,SAAS,EACb,KAAK,EAAE,cAAc,EACrB,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,EAC/B,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,aAAa,CAAC,CAkBxB"}