@johnhenry/wsh 0.18.0 → 0.19.0

package/src/server/index.d.ts

@@ -20,6 +20,36 @@ export interface WshServerAuthOptions {
   authorizedKeys?: string | Uint8Array | Array<string | Uint8Array>;
   /** Extra policy, run after the signature verifies (and after the allowlist, when given). */
   authorize?: (who: WshServerPrincipal) => boolean | Promise<boolean>;
+  /**
+   * Enable password login: return `true` to admit. Sent in the clear inside the
+   * connection -- serve over `wss://` / a trusted link. Use a constant-time
+   * compare against hashes, never `===` on plaintext. Failures are throttled
+   * (see `rateLimit`); the callback is not consulted while a caller is locked out.
+   */
+  password?: (username: string, password: string) => boolean | Promise<boolean>;
+  /** Password-failure throttle. */
+  rateLimit?: {
+    /** Failures inside `windowMs` before lockout (default 5). */
+    maxFailures?: number;
+    /** Failure counting window (default 60000). */
+    windowMs?: number;
+    /** Lockout length once tripped (default 60000). */
+    lockoutMs?: number;
+    /** Pause before answering a failed attempt (default 250). */
+    failureDelayMs?: number;
+    /** Throttle bucket; default the peer address. Use this behind a proxy (e.g. read `x-forwarded-for` from `headers`). */
+    key?: (info: { address: string | undefined; headers: Record<string, string | string[] | undefined>; username: string }) => string;
+  };
+}
+
+/** The server's own identity, as advertised to clients. */
+export interface WshServerHostKey {
+  /** Hex SHA-256 of the raw key. */
+  fingerprint: string;
+  /** Raw 32-byte Ed25519 key. */
+  publicKey: Uint8Array;
+  /** `ssh-ed25519 AAAA...` */
+  openssh: string;
 }
 
 /** What a custom `exec` runner receives for one session. */
@@ -100,6 +130,12 @@ export interface WshServerOptions {
   exec?: true | WshServerExecOptions | WshExecRunner;
   /** Enable `pty` sessions by injecting a pty implementation. Off by default. */
   pty?: WshServerPtyOptions;
+  /**
+   * Advertise an Ed25519 host identity (with proof of possession) so clients can pin it.
+   * `{ file }` persists a PKCS#8 PEM (created 0600 on first start) -- the normal choice;
+   * `true` is a fresh key every start; or pass a `CryptoKeyPair`. Off by default.
+   */
+  hostKey?: true | { file: string } | CryptoKeyPair;
   /** Enable file ops and uploads/downloads under one directory. Off by default. */
   fs?: WshServerFsOptions;
   /** How long exec output waits for a client that has not yet opened its data stream (default 3000). */
@@ -119,6 +155,8 @@ export interface WshServer {
   close(): Promise<void>;
   /** The bound address, or `null` when not listening. */
   address(): WshServerAddress | null;
+  /** The advertised host identity; `null` before `listen()` resolves or without a `hostKey`. */
+  hostKey(): WshServerHostKey | null;
 }
 
 export function createWshServer(options?: WshServerOptions): WshServer;

package/src/server/index.mjs

@@ -8,7 +8,8 @@
  * refused.
  */
 
-import { buildAuthorizer, parseAuthorizedKeys } from './auth.mjs';
+import { buildAuthorizer, parseAuthorizedKeys, authMethods, FailureLimiter } from './auth.mjs';
+import { loadHostKey } from './host-key.mjs';
 import { spawnRunner } from './exec.mjs';
 import { normalizePty } from './pty.mjs';
 import { createFileAccess } from './fs.mjs';
@@ -25,12 +26,16 @@ export { parseAuthorizedKeys, STREAM_ANNOUNCE };
  *   `{ cwd, env, shell, timeoutMs, clientEnv }`, or a custom `run(command, io)` function.
  * @param {{ spawn: Function, shell?: string, cwd?: string, env?: object }} [options.pty]
  * @param {{ root: string, readOnly?: boolean, maxFileBytes?: number }} [options.fs]
+ * @param {true | { file: string } | CryptoKeyPair} [options.hostKey] - The server's own Ed25519
+ *   identity, advertised (with proof of possession) so clients can pin it. See `src/host-key.mjs`.
+ * @param {object} [options.auth.rateLimit] - Password-failure throttle: `{ maxFailures=5, windowMs=60000,
+ *   lockoutMs=60000, failureDelayMs=250, key(info) }` (`key` defaults to the peer address).
  * @param {number} [options.bindTimeoutMs=3000]
  * @param {(line: string) => void} [options.onLog]
  * @returns {{ listen(): Promise<{address: string, port: number}>, close(): Promise<void>, address(): ({address: string, port: number} | null) }}
  */
 export function createWshServer({
-  host = '127.0.0.1', port = 0, auth, exec, pty, fs, bindTimeoutMs = 3000, onLog = () => {},
+  host = '127.0.0.1', port = 0, auth, exec, pty, fs, hostKey, bindTimeoutMs = 3000, onLog = () => {},
 } = {}) {
   let wss = null;
   let bound = null;
@@ -45,6 +50,14 @@ export function createWshServer({
   }
   const ptyConfig = pty ? normalizePty(pty) : null;
   const files = fs ? createFileAccess(fs) : null;
+  const methods = authMethods(auth);
+  const rl = auth?.rateLimit ?? {};
+  const rateLimit = {
+    limiter: new FailureLimiter(rl),
+    key: typeof rl.key === 'function' ? rl.key : ({ address }) => String(address ?? 'unknown'),
+    failureDelayMs: rl.failureDelayMs ?? 250,
+  };
+  let host_ = null;
 
   return {
     async listen() {
@@ -56,13 +69,18 @@ export function createWshServer({
         throw new Error('@johnhenry/wsh/server needs the "ws" package: npm install ws', { cause: err });
       }
       const authorize = await buildAuthorizer(auth);
+      host_ = hostKey ? await loadHostKey(hostKey) : null;
       const attach = createConnectionFactory({
         authorize, execRunner, execOptions, pty: ptyConfig, files, bindTimeoutMs, log: onLog,
+        methods, hostKey: host_, rateLimit,
       });
 
       wss = new WebSocketServer({ host, port });
-      wss.on('connection', (ws) => {
-        const conn = attach({ send: (b) => { if (ws.readyState === 1) ws.send(b); } });
+      wss.on('connection', (ws, req) => {
+        const conn = attach({
+          send: (b) => { if (ws.readyState === 1) ws.send(b); },
+          remote: { address: req?.socket?.remoteAddress, headers: req?.headers ?? {} },
+        });
         ws.on('message', (d) => {
           const buf = Array.isArray(d) ? Buffer.concat(d) : Buffer.isBuffer(d) ? d : Buffer.from(d);
           conn.receive(new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength));
@@ -91,5 +109,10 @@ export function createWshServer({
     address() {
       return bound;
     },
+
+    /** The advertised host identity (`null` until `listen()` resolves, or with no `hostKey`). */
+    hostKey() {
+      return host_ ? { fingerprint: host_.fingerprint, publicKey: host_.publicKey, openssh: host_.openssh } : null;
+    },
   };
 }