webssh 1.0.0

package/README.md

@@ -0,0 +1,48 @@
+# webssh
+
+Web-based SSH terminal server and client with xterm.js integration. Access remote shells through your browser or CLI.
+
+## Features
+
+- 🌐 **Browser-based terminal** – Full xterm.js integration with syntax highlighting and themes
+- 🔌 **WebSocket transport** – Real-time bidirectional communication
+- 🖥️ **CLI client** – Connect from command line with interactive prompt
+- 📏 **Auto-resize** – Terminal dimensions sync between client and server
+- 🔒 **Session management** – Unique session IDs with automatic cleanup
+- ⚡ **Lightweight** – Minimal dependencies, fast startup
+- 🚀 **Modern ES modules** – Native ESM with async/await support
+
+## Installation
+
+```bash
+npm install webssh
+
+
+#server mode
+
+import webssh from 'webssh';
+
+// Using async IIFE for top-level await
+const { serve } = webssh;
+
+const server = serve({
+  port: 3000,
+  host: 'localhost'
+});
+
+server.start(() => {
+  console.log('🚀 WebSSH server running at http://localhost:3000');
+});
+
+
+#client mode
+
+import webssh from 'webssh';
+
+const { connect } = webssh;
+
+// Connect with defaults (localhost:3000)
+await connect();
+
+// Or specify custom host/port
+await connect('remote.server.com', 8080);

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "webssh",
+  "version": "1.0.0",
+  "description": "Web-based SSH terminal server and client with xterm.js integration",
+  "type": "module",
+  "main": "webssh.js",
+  "exports": {
+    ".": "./webssh.js"
+  },
+  "files": [
+    "webssh.js",
+    "terminals.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node webssh.js",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "ssh",
+    "terminal",
+    "web-terminal",
+    "xterm",
+    "websocket",
+    "remote-shell",
+    "browser-terminal",
+    "pty",
+    "web-ssh"
+  ],
+  "author": "littlejustnode",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/littlejustnode/webssh.git"
+  },
+  "bugs": {
+    "url": "https://github.com/littlejustnode/webssh/issues"
+  },
+  "homepage": "https://github.com/littlejustnode/webssh#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "express": "^4.18.2",
+    "just-prompt": "^1.0.0",
+    "ws": "^8.14.2"
+  }
+}

package/terminals.js

@@ -0,0 +1,63 @@
+import * as os from 'node:os';
+import * as pty from 'node-pty';
+
+class TerminalManager {
+  constructor() {
+    this.sessions = new Map();
+  }
+
+  /**
+   * Creates a new terminal instance and stores it in the Map.
+   */
+  createSession(name, options = {}) {
+    const shell = os.platform() === 'win32' ? 'powershell.exe' : 'bash';
+    
+    const ptyProcess = pty.spawn(shell, [], {
+      name: 'xterm-color',
+      cols: options.cols || process.stdout.columns || 80,
+      rows: options.rows || process.stdout.rows || 24,
+      cwd: options.cwd || process.env.HOME || process.cwd(),
+      env: options.env || process.env
+    });
+
+    // Define the session object with the methods you requested
+    const session = {
+      id: name,
+      process: ptyProcess,
+      
+      // Listen for output
+      onOut: (callback) => {
+        ptyProcess.onData((data) => callback(data));
+      },
+
+      // Send commands (automatically adds newline if missing)
+      send: (data) => {
+        const command = data.endsWith('\r') || data.endsWith('\n') ? data : `${data}\r`;
+        ptyProcess.write(command);
+      },
+
+      // Kill this specific session and remove from memory
+      exit: () => {
+        ptyProcess.kill();
+        this.sessions.delete(name);
+      }
+    };
+
+    // Store it
+    this.sessions.set(name, session);
+    return session;
+  }
+
+  /**
+   * Terminates every session stored in memory.
+   */
+  close() {
+    this.sessions.forEach((session) => {
+      session.exit();
+    });
+    this.sessions.clear();
+  }
+}
+
+// Export a single instance to be used as 'terminals'
+export const terminals = new TerminalManager();

package/webssh.js

@@ -0,0 +1,276 @@
+
+import express from 'express';
+import { createServer } from 'node:http';
+import { WebSocketServer } from 'ws';
+import { terminals } from './terminals.js';
+import jp from 'just-prompt';
+
+
+// ────────────────────────────────────────────────
+//  SERVER BUILDER – returns chainable object
+// ────────────────────────────────────────────────
+
+function serve(options = {}) {
+  const config = {
+    port: 3000,
+    host: 'localhost',
+    path: '/terminal',
+    cors: false,
+    sessionPrefix: 'ws-',
+    ...options,
+  };
+
+  const app = express();
+  const httpServer = createServer(app);
+  const wss = new WebSocketServer({ server: httpServer, path: config.path });
+
+  if (config.cors) {
+    app.use((req, res, next) => {
+      res.setHeader('Access-Control-Allow-Origin', '*');
+      res.setHeader('Access-Control-Allow-Headers', '*');
+      next();
+    });
+  }
+
+  // Serve browser terminal
+  app.get('/', (req, res) => {
+    res.type('html').send(getBrowserHTML(config.path));
+  });
+
+  const clientToSessionId = new WeakMap();
+
+  wss.on('connection', (ws) => {
+    let session = null;
+    let sessionId = null;
+
+    ws.on('message', (raw) => {
+      try {
+        const data = raw.toString();
+
+        if (data.startsWith('{')) {
+          try {
+            const msg = JSON.parse(data);
+            if (msg.type === 'resize' && session) {
+              session.process.resize(msg.cols, msg.rows);
+            }
+          } catch {}
+          return;
+        }
+
+        if (!session) {
+          sessionId = `${config.sessionPrefix}${Date.now()}-${Math.random().toString(36).slice(2,8)}`;
+          session = terminals.createSession(sessionId, {
+            cols: 80,
+            rows: 24,
+          });
+
+          clientToSessionId.set(ws, sessionId);
+
+          session.onOut((chunk) => {
+            if (ws.readyState === WebSocket.OPEN) ws.send(chunk);
+          });
+
+          ws.send('\r\nWeb terminal ready.\r\n');
+        }
+
+        session.send(data);
+      } catch (err) {
+        console.error('WS message error:', err);
+      }
+    });
+
+    ws.on('close', () => {
+      if (sessionId) {
+        const sess = terminals.sessions.get(sessionId);
+        if (sess) {
+          sess.exit();
+          terminals.sessions.delete(sessionId);
+        }
+        clientToSessionId.delete(ws);
+      }
+    });
+
+    ws.on('error', (err) => console.error('WS error:', err));
+  });
+
+  // Chainable start method
+  function start(callback) {
+    httpServer.listen(config.port, config.host, () => {
+      const displayHost = config.host === '0.0.0.0' ? 'localhost' : config.host;
+      console.log(`Web terminal server listening at http://${displayHost}:${config.port}`);
+      console.log(`  → Browser:   http://${displayHost}:${config.port}/`);
+      console.log(`  → WS:        ws://${displayHost}:${config.port}${config.path}`);
+      if (callback) callback();
+    });
+  }
+
+  // Also expose close (optional)
+  function close() {
+    terminals.close();
+    httpServer.close();
+    wss.close();
+  }
+
+  return {
+    start,
+    close,
+    // for advanced usage if someone needs direct access
+    app,
+    httpServer,
+    wss,
+  };
+}
+
+// ────────────────────────────────────────────────
+//  CLIENT – single host string (unchanged)
+// ────────────────────────────────────────────────
+
+async function connect(host = 'localhost', port = 3000) {
+  const path = '/terminal';
+  const url = `ws://${host}:${port}${path}`;
+
+  const promptMessage = '→ ';
+  const exitCommand = 'exit';
+
+  const WebSocket = (await import('ws')).default;
+
+  return new Promise((resolve, reject) => {
+    console.log(`Connecting to ${url} ...`);
+
+    const socket = new WebSocket(url);
+
+    socket.on('open', () => {
+      console.clear();
+      console.log(`Connected to ${host}`);
+      console.log(`(type "${exitCommand}" to quit)\n`);
+
+      const prompt = jp.app(promptMessage, exitCommand, async (input) => {
+        if (socket.readyState === WebSocket.OPEN) {
+          socket.send(input + '\r');
+        }
+      });
+
+      prompt.onExit(() => {
+        socket.close();
+        resolve();
+      });
+
+      socket.on('message', (data) => {
+        process.stdout.write(data.toString());
+      });
+
+      socket.on('close', () => {
+        console.log(`\nDisconnected from ${host}.`);
+        prompt.stop();
+        resolve();
+      });
+
+      socket.on('error', (err) => {
+        console.error(`Connection error: ${err.message}`);
+        prompt.stop();
+        reject(err);
+      });
+
+      prompt.start().catch(reject);
+    });
+
+    socket.on('error', (err) => {
+      console.error(`Cannot connect to ${host}: ${err.message}`);
+      reject(err);
+    });
+  });
+}
+
+// ────────────────────────────────────────────────
+//  Browser HTML (unchanged)
+// ────────────────────────────────────────────────
+
+function getBrowserHTML(wsPath = '/terminal') {
+  return `
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8"/>
+  <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
+  <title>Web Terminal</title>
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@xterm/xterm@5.5.0/css/xterm.min.css"/>
+  <style>
+    body { margin:0; background:#000; height:100vh; overflow:hidden; }
+    #terminal { width:100%; height:100%; }
+  </style>
+</head>
+<body>
+  <div id="terminal"></div>
+
+  <script type="module">
+    import { Terminal } from 'https://cdn.jsdelivr.net/npm/@xterm/xterm@5.5.0/+esm';
+    import { FitAddon } from 'https://cdn.jsdelivr.net/npm/@xterm/addon-fit@0.10.0/+esm';
+
+    const term = new Terminal({
+      cursorBlink: true,
+      theme: { background: '#1e1e1e', foreground: '#e0e0e0' }
+    });
+
+    const fitAddon = new FitAddon();
+    term.loadAddon(fitAddon);
+    term.open(document.getElementById('terminal'));
+    fitAddon.fit();
+
+    const protocol = location.protocol === 'https:' ? 'wss:' : 'ws:';
+    const ws = new WebSocket(protocol + '//' + location.host + '${wsPath}');
+
+    let inputBuffer = "";
+
+    term.onData(data => {
+      switch (data) {
+        case '\\r':
+          if (ws.readyState === WebSocket.OPEN) ws.send(inputBuffer + '\\r');
+          inputBuffer = "";
+          term.write('\\r\\n');
+          break;
+        case '\\u007F':
+          if (inputBuffer.length > 0) {
+            inputBuffer = inputBuffer.slice(0, -1);
+            term.write('\\b \\b');
+          }
+          break;
+        default:
+          if (data >= ' ' && data <= '~') {
+            inputBuffer += data;
+            term.write(data);
+          }
+      }
+    });
+
+    ws.onmessage = e => term.write(e.data);
+
+    function sendResize() {
+      fitAddon.fit();
+      if (ws.readyState === WebSocket.OPEN) {
+        ws.send(JSON.stringify({
+          type: 'resize',
+          cols: term.cols,
+          rows: term.rows
+        }));
+      }
+    }
+
+    window.addEventListener('resize', sendResize);
+    ws.onopen = () => {
+      sendResize();
+      term.writeln('Connecting...');
+      term.focus();
+    };
+  </script>
+</body>
+</html>`;
+}
+
+// ────────────────────────────────────────────────
+//  Public API
+// ────────────────────────────────────────────────
+
+export default {
+  serve,     // ← new main server entry point
+  connect,   // simple client
+};