webssh2_client 1.0.0 → 2.0.0-alpha.10

package/README.md

@@ -1,223 +1,469 @@
 # WebSSH2 Client - Web SSH Client
 
+[![CI](https://github.com/billchurch/webssh2_client/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/billchurch/webssh2_client/actions/workflows/ci.yml)
+[![Release](https://github.com/billchurch/webssh2_client/actions/workflows/release.yml/badge.svg?branch=main)](https://github.com/billchurch/webssh2_client/actions/workflows/release.yml)
+
 ![Orthrus Mascot](images/orthrus.png)
 
-WebSSH2 Client is an HTML5 web-based terminal emulator and SSH client. It uses WebSockets to communicate with a WebSSH2 server, which in turn uses SSH2 to connect to SSH servers.
+WebSSH2 Client is an HTML5 web-based terminal emulator and SSH client component. It uses WebSockets to communicate with a WebSSH2 server, which in turn uses SSH2 to connect to SSH servers.
 
 ![WebSSH2 demo](https://user-images.githubusercontent.com/1668075/182425293-acc8741e-cc92-4105-afdc-9538e1685d4b.gif)
 
-# EXPERIMENTAL
-The current status is experimental, and this first version is a refactor of webssh2 v0.2.x to be compatible with a refactor of the same version of webssh2 as a stand-alone server-side component  running Node.js v6.9.1.
-
-The intention is to harmonize the latest release of webssh2 by splitting out the client and server as separate repos (webssh2-client and webssh2-server) but joining them both together as modules in a parent webssh2 in an attempt to provide backward compatibility.
+# Important Notice
 
-The main idea behind bifurcating the client/server is to make it easier to customize the client to work in other frameworks and use cases.
+This package contains only the browser-side client component of WebSSH2. It requires a compatible WebSSH2 server to function. The server component is available at [webssh2 server](https://github.com/billchurch/webssh2/tree/bigip-server). This package is intended for advanced users who want to customize or integrate the client component independently.
 
-## Table of Contents
+# Status
 
-- [Requirements](#requirements)
-- [Installation](#installation)
-- [Usage](#usage)
-- [Configuration](#configuration)
-- [Features](#features)
-- [Routes](#routes)
-- [Development](#development)
-- [Advanced Configuration](#advanced-configuration)
-- [Support](#support)
-- [License](#license)
-- [Acknowledgments](#acknowledgments)
+This is an experimental refactor of the WebSSH2 v0.2.x client to function as a standalone component. It has been separated from the server-side code to facilitate customization and integration with different frameworks.
 
 ## Requirements
 
 - Modern web browser with JavaScript enabled
-- WebSSH2 server (see server README for setup instructions)
+- Compatible WebSSH2 server instance (v0.2.x or compatible)
+- Socket.IO v2.2.0 compatibility (due to server requirements)
 
 ## Installation
 
 1. Clone the repository:
+
    ```
    git clone https://github.com/billchurch/webssh2_client.git
    cd webssh2_client
    ```
 
 2. Install dependencies:
+
    ```
    npm install
    ```
 
 3. Build the client:
+
    ```
    npm run build
    ```
 
 4. The built client files will be in the `client/public` directory.
 
-## Usage
+## Server Requirements
 
-1. Set up and start the WebSSH2 server (see server README for instructions).
+The WebSSH2 client requires a compatible server that provides:
 
-2. Access the web client by navigating to the server's URL, typically:
-   ```
-   http://localhost:2222/ssh
-   ```
+- WebSocket endpoint for SSH communication
+- Authentication handling
+- SSH connection management
+- Socket.IO v2.2.0 compatibility
+
+For server setup instructions, refer to the [WebSSH2 server documentation](https://github.com/billchurch/webssh2/tree/bigip-server).
+
+## Client Features
 
-3. You'll be prompted for host details and SSH credentials.
+- Web-based SSH client with xterm.js terminal emulation
+- **Terminal Search Functionality:**
+  - Real-time search with live match highlighting
+  - Case-sensitive and regex search options
+  - Whole word matching
+  - Match counter (current/total)
+  - OS-aware keyboard shortcuts (Ctrl+F on Windows/Linux, ⌘F on macOS)
+  - Navigation with Enter/Shift+Enter or arrow buttons
+  - F3/Shift+F3 for quick match navigation
+- **Advanced Clipboard Integration:**
+  - Auto-copy on selection (similar to terminals like tmux or PuTTY, configurable)
+  - Middle-click paste support (configurable)
+  - Keyboard shortcuts: Ctrl+Shift+C/V (Windows/Linux) or Cmd+Shift+C/V (macOS)
+  - Browser compatibility detection with fallback mechanisms
+  - Visual feedback with toast notifications
+  - All features can be toggled in Terminal Settings
+- Customizable terminal settings:
+  - Font size and family
+  - Color schemes
+  - Cursor behavior
+  - Scrollback buffer size
+  - Clipboard behavior controls
+- Session logging with download capability
+- Copy and paste functionality
+- Terminal mouse support
+- Keyboard shortcuts
+- Responsive design
+- Multi-factor authentication support (when supported by server)
+- Support for credential replay and reauthentication
+
+## Security and Lint Rules
+
+- No innerHTML: The client never uses `innerHTML` for user content. All text uses `textContent` and safe DOM building helpers.
+- CSP: Strict `script-src 'self'` (no inline scripts). Inline styles allowed for xterm DOM renderer and safe color updates.
+- ESLint guardrails:
+  - `no-unsanitized` plugin blocks unsanitized DOM sinks (`innerHTML`, `outerHTML`, `insertAdjacentHTML`, `document.write`).
+  - Additional bans via `no-restricted-properties` for those sinks, and `no-restricted-syntax` for string-based timers and `new Function`.
+- Xterm integration: Terminal output is rendered with `xterm.write()`; no HTML rendering of remote data.
 
 ## Configuration
 
-The client can be configured using URL parameters or through the config file on the server. Some configurable options include:
+The client can be configured through:
+
+1. URL parameters
+2. Configuration object
+3. User interface settings
 
+### URL Parameters
+
+Supported URL parameters include:
+
+- `host` - SSH server hostname
 - `port` - SSH server port (default: 22)
 - `header` - Optional header text
-- `headerBackground` - Optional header background color
-- `sshterm` - Terminal type for pty (default: xterm-color)
+- `headerStyle` - Complete header styling with Tailwind CSS classes or CSS (recommended)
+- `headerBackground` - Header background styling only (legacy, see Advanced Header Styling below)
+- `sshterm` - Terminal type (default: xterm-color)
 
-For a full list of configuration options, refer to the server README.
+#### Advanced Header Styling
 
-## Features
+WebSSH2 Client supports comprehensive header styling through two approaches: **enhanced headerStyle** (recommended) and **legacy headerBackground** (maintained for backward compatibility).
 
-- Web-based SSH client with xterm.js terminal emulation
-- Supports various SSH authentication methods (password and keyboard-interactive)
-- Customizable terminal settings (font size, font family, colors, etc.)
-- Session logging with download option
-- Support for reauthentication and credential replay
-- Responsive design for various screen sizes
-- Keyboard shortcuts support
-- Terminal Mouse support
-- Copy and paste functionality
-- Multi-factor authentication support
-- CORS support for flexible server setups
+##### Enhanced Header Styling (headerStyle)
 
-## Routes
+The `headerStyle` parameter provides complete control over header appearance using Tailwind CSS classes or CSS properties:
 
-The WebSSH2 Server (not provided by this package) provides two main routes:
+**Basic Examples:**
 
-### 1. `/ssh`
+```
+# Enhanced background with custom height and text
+?header=Production&headerStyle=bg-red-600%20h-10%20text-xl%20font-bold
 
-- Interactive login form
-- Terminal configuration options
+# Gradient with custom styling
+?header=Staging&headerStyle=bg-gradient-to-r%20from-blue-500%20to-purple-500%20h-8%20text-lg
 
-### 2. `/ssh/host/:host`
+# Custom text colors and shadows
+?header=Development&headerStyle=bg-green-500%20text-black%20font-semibold%20shadow-lg
+```
 
-- Quick connections to specific hosts
-- Optional `port` parameter (e.g., `?port=2222`)
-- HTTP Basic Authentication for credentials
+**Advanced Styling Capabilities:**
 
-## Development
+**Backgrounds & Gradients:**
 
-- To add custom JavaScript, modify `./src/client.htm`, `./src/index.js`, or add your file to `webpack.*.js`.
-- For security, use HTTPS when transmitting credentials via HTTP Basic Auth.
-- Terminal settings can be customized after login via `Menu | Settings` and persist across sessions.
-- Debug mode can be enabled by setting the `DEBUG` environment variable.
+```
+# Multi-directional gradients
+?headerStyle=bg-gradient-to-br%20from-purple-600%20via-pink-500%20to-yellow-400%20h-12
 
-## Advanced Configuration 
+# Solid colors with transparency
+?headerStyle=bg-blue-500%20h-8%20shadow-blue-500/50
 
-In the client HTML file, you'll find this script tag:
+# Complex gradient patterns
+?headerStyle=bg-gradient-to-r%20from-red-500%20via-yellow-500%20to-green-500%20h-10
+```
+
+**Typography & Layout:**
 
-```html
-<script>
-window.webssh2Config = null;
-</script>
 ```
+# Large headers with custom fonts
+?headerStyle=bg-slate-700%20h-16%20text-3xl%20font-black%20flex%20items-center%20justify-center
 
-The WebSSH2 server replaces this null value with a configuration object. However, you can also set this manually to override server-provided settings or to configure the client when using it standalone.
+# Compact headers
+?headerStyle=bg-indigo-600%20h-5%20text-xs%20font-medium
 
-### Configuration Options
+# Custom text alignment and colors
+?headerStyle=bg-gradient-to-r%20from-cyan-400%20to-blue-500%20text-left%20text-yellow-100%20px-4
+```
 
-Here's a comprehensive list of parameters that can be injected using `window.webssh2Config`:
+**Borders & Effects:**
 
-```javascript
-window.webssh2Config = {
-  socket: {
-    url: null,  // WebSocket URL. If null, it will be automatically determined
-    path: '/ssh/socket.io',  // Socket.IO path
-  },
-  ssh: {
-    host: null,  // SSH server hostname (required for autoConnect)
-    port: 22,  // SSH server port
-    username: null,  // SSH username (required for autoConnect)
-    password: null,  // SSH password (required for autoConnect)
-    sshterm: 'xterm-color',  // Terminal type
-    readyTimeout: 20000,  // SSH connection timeout (ms)
-  },
-  header: {
-    text: null,  // Custom header text
-    background: 'green',  // Header background color
-  },
-  autoConnect: false  // Whether to connect automatically
-};
+```
+# Styled borders
+?headerStyle=bg-purple-500%20border-2%20border-white%20border-dashed%20h-8
+
+# Shadow effects
+?headerStyle=bg-green-500%20shadow-xl%20shadow-green-500/50%20rounded-lg%20h-10
+
+# Rounded corners
+?headerStyle=bg-gradient-to-r%20from-pink-400%20to-rose-500%20rounded-xl%20h-12%20mx-2
 ```
 
-### Auto-Connect Functionality
+**Animations:**
 
-The `autoConnect` option is used to create pre-configured connections:
+```
+# Pulsing effect for alerts
+?headerStyle=bg-red-600%20animate-pulse%20h-8%20font-bold
 
-- When set to `true`, the client will attempt to connect immediately using the provided SSH configuration, bypassing the login form.
-- For `autoConnect` to work, you must provide at least the `host` in the SSH configuration.
-- `autoConnect` requires a username and password. If these are not provided, the server may use other methods (like basic auth or session data) to authenticate the connection.
-- If the host is missing when `autoConnect` is `true,` the login form will be shown instead.
+# Bouncing for urgent notifications
+?headerStyle=bg-yellow-500%20animate-bounce%20h-10%20text-black%20font-semibold
+```
 
-Example usage:
+**Production Examples:**
 
-```javascript
-window.webssh2Config = {
-  ssh: {
-    host: 'example.com',
-    port: 22,
-    username: 'user',  // Optional
-    password: 'password'  // Optional
-  },
-  autoConnect: true
-};
 ```
+# Critical system warning
+?header=🚨%20PRODUCTION%20-%20CRITICAL%20🚨&headerStyle=bg-gradient-to-r%20from-red-600%20to-red-700%20h-12%20text-2xl%20font-bold%20animate-pulse%20shadow-lg
 
-This configuration will attempt to connect to `example.com` as soon as the page loads, using any provided credentials or relying on server-side authentication methods.
+# Development environment
+?header=🛠️%20Development%20Environment&headerStyle=bg-gradient-to-r%20from-green-400%20to-emerald-600%20h-8%20text-white%20font-medium
 
-### Security Considerations
+# Staging deployment
+?header=🚀%20Staging%20Deployment&headerStyle=bg-gradient-to-r%20from-yellow-400%20to-orange-500%20h-10%20text-black%20font-semibold%20border-b-2%20border-orange-600
 
-The `autoConnect` feature only requires the host to be specified. The server handles authentication, which may use various methods, including basic auth or session data.
-- If you do include a username and password in the client-side configuration, be cautious, as this may pose security risks, especially in production environments.
-- For production use, consider using secure server-side authentication methods rather than including credentials in the client-side configuration.
-When `autoConnect` is not used, ensure your server is configured to prompt for or securely handle credentials as needed.
+# Secure connection
+?header=🔐%20Encrypted%20Connection&headerStyle=bg-gradient-to-r%20from-emerald-500%20to-teal-600%20h-8%20text-white%20shadow-md
+```
 
-### Customization Examples
+##### Legacy Header Styling (headerBackground)
 
-1. Setting a custom header:
-   ```javascript
-   window.webssh2Config = {
-     header: {
-       text: 'My Custom SSH Client',
-       background: '#007acc'
-     }
-   };
-   ```
+For backward compatibility, the original `headerBackground` parameter is still supported:
 
-2. Configuring for a specific SSH server with auto-connect:
-   ```javascript
-   window.webssh2Config = {
-     ssh: {
-       host: 'myserver.example.com',
-       port: 2222
-     },
-     autoConnect: true
-   };
-   ```
+**Basic Colors:**
+
+```
+?header=Production&headerBackground=red
+?header=Custom&headerBackground=%23ff6b35
+```
+
+**Tailwind Classes:**
+
+```
+?header=Server%20Alpha&headerBackground=bg-blue-500
+?header=Critical%20System&headerBackground=bg-red-600
+```
+
+**Simple Gradients:**
 
-By leveraging these configuration options, you can customize the WebSSH2 client to suit your needs or integrate it seamlessly into your existing systems. Remember that the server handles authentication, providing flexibility in managing and securing credentials.
+```
+?header=Gradient%20Demo&headerBackground=bg-gradient-to-r%20from-blue-500%20to-purple-500
+```
+
+##### Header Styling Reference
+
+**Essential Styling Categories:**
+
+**🎨 Background Colors & Gradients**
+
+```
+# Solid Colors
+bg-red-500, bg-red-600, bg-blue-500, bg-blue-600, bg-green-500, bg-yellow-500
+bg-purple-500, bg-pink-500, bg-indigo-500, bg-cyan-500, bg-emerald-500, bg-slate-700
+
+# Gradients (All 8 Directions Available)
+bg-gradient-to-r, bg-gradient-to-l, bg-gradient-to-t, bg-gradient-to-b
+bg-gradient-to-tr, bg-gradient-to-tl, bg-gradient-to-br, bg-gradient-to-bl
+
+# Color Ranges (from/to/via)
+from-red-500 to from-red-700, from-blue-500 to from-blue-700
+from-green-500 to from-green-700, from-yellow-400 to from-yellow-500
+from-orange-400 to from-orange-500, from-purple-500 to from-purple-600
+from-indigo-500 to from-indigo-600, from-pink-500 to from-pink-600
+from-cyan-400 to from-cyan-500, from-emerald-500, from-teal-500, from-slate-700
+via-yellow-500, via-pink-500, via-purple-500, via-blue-500
+```
+
+**📝 Text Styling**
+
+```
+# Sizes: text-xs, text-sm, text-base, text-lg, text-xl, text-2xl, text-3xl, text-4xl
+# Weights: font-normal, font-medium, font-semibold, font-bold, font-black
+# Colors: text-white, text-black, text-yellow-100, text-blue-100, text-red-100, text-green-100, text-gray-100
+# Alignment: text-center, text-left
+
+# Examples
+text-2xl font-bold text-white
+text-sm font-medium text-black
+text-4xl font-black text-yellow-100
+```
+
+**📏 Header Heights**
+
+```
+# Available: h-4, h-5, h-6, h-7, h-8, h-10, h-12, h-14, h-16
+# Default was h-6 (24px), now customizable
+
+h-5     # Very compact header
+h-8     # Compact header
+h-12    # Standard header
+h-16    # Prominent header
+```
+
+**✨ Visual Effects**
+
+```
+# Animations
+animate-pulse    # Pulsing effect for alerts
+animate-bounce   # Bouncing for urgent notifications
+
+# Shadows
+shadow, shadow-md, shadow-lg, shadow-xl
+
+# Borders
+border, border-2, border-4
+border-red-500, border-blue-500, border-white
+border-dashed, border-solid
+
+# Border Radius
+rounded, rounded-lg, rounded-xl
+```
+
+**📍 Layout & Positioning**
+
+```
+# Text Alignment
+text-left, text-center
+
+# Spacing (Padding)
+px-2, px-4, px-6 (horizontal padding)
+py-1, py-2, py-3 (vertical padding)
+
+# Flexbox (for complex layouts)
+flex items-center justify-center
+```
+
+**Common Use Cases:**
+
+**🚨 Production/Critical Systems:**
+
+```
+# Red gradient with large text and pulsing animation
+bg-gradient-to-r from-red-600 to-red-700 h-12 text-2xl font-bold animate-pulse
+
+# Solid red with white border
+bg-red-600 border-2 border-white h-10 text-xl font-bold
+```
+
+**🚀 Staging/Development:**
+
+```
+# Yellow-orange gradient for staging
+bg-gradient-to-r from-yellow-400 to-orange-500 h-10 text-black font-semibold
+
+# Green for development
+bg-gradient-to-r from-green-400 to-emerald-600 h-8 text-white font-medium
+```
+
+**🔒 Secure/Special Connections:**
+
+```
+# Blue gradient with shadow
+bg-gradient-to-r from-blue-500 to-cyan-500 h-8 shadow-lg
+
+# Purple with rounded corners
+bg-purple-600 rounded-lg h-10 font-semibold
+```
+
+**⚡ Quick Reference:**
+
+- **Solid Colors**: red-500/600, blue-500/600, green-500, yellow-500, purple-500, pink-500, indigo-500, cyan-500, emerald-500, slate-700
+- **Gradient Colors**: Full range 400-700 for red/blue/green, 400-500 for yellow/orange, 500-600 for purple/indigo/pink, etc.
+- **Text sizes**: xs, sm, base, lg, xl, 2xl, 3xl, 4xl
+- **Heights**: 4, 5, 6, 7, 8, 10, 12, 14, 16 (h-4 = 16px, h-16 = 64px)
+- **Combine freely**: `bg-blue-500 h-12 text-xl font-bold animate-pulse shadow-lg`
+
+##### Styling System Features
+
+**Automatic Detection:**
+The system automatically detects whether you're using:
+
+- Tailwind CSS classes (applied as CSS classes)
+- CSS color values (applied as inline styles)
+
+**Complete Tailwind Support:**
+
+- **Backgrounds:** Solid colors, gradients, transparency
+- **Typography:** Font sizes, weights, colors, alignment
+- **Layout:** Heights, padding, margins, flexbox
+- **Borders:** Styles, colors, radius
+- **Effects:** Shadows, animations
+- **Bundle Optimized:** Curated safelist keeps CSS file size reasonable (~33KB)
+
+**Backward Compatibility:**
+
+- Existing `headerBackground` URLs continue to work
+- Mixed usage supported (header + headerBackground or headerStyle)
+- Graceful fallback to CSS for non-Tailwind values
+
+### Clipboard Settings
+
+The WebSSH2 client includes comprehensive clipboard integration. All clipboard features can be configured through the Terminal Settings modal (accessible from the menu) or via localStorage:
+
+#### Features
+
+1. **Auto-copy on Selection**: Automatically copies selected text to the system clipboard when you select text with your mouse (similar to tmux or PuTTY)
+2. **Middle-click Paste**: Paste clipboard contents by middle-clicking in the terminal
+3. **Keyboard Shortcuts**: Use Ctrl+Shift+C to copy and Ctrl+Shift+V to paste (Cmd+Shift+C/V on macOS)
+
+#### Configuration
+
+Clipboard settings are stored in localStorage under `webssh2.settings.global` and can be toggled via the Terminal Settings modal:
+
+- `clipboardAutoSelectToCopy` (default: `true`) - Enable/disable auto-copy on selection
+- `clipboardEnableMiddleClickPaste` (default: `true`) - Enable/disable middle-click paste
+- `clipboardEnableKeyboardShortcuts` (default: `true`) - Enable/disable keyboard shortcuts
+
+#### Browser Compatibility
+
+The clipboard integration includes:
+
+- Automatic detection of browser clipboard API support
+- Fallback mechanisms for older browsers
+- Security context validation (HTTPS/localhost required)
+- Browser-specific warnings and guidance
+- Visual feedback via toast notifications for clipboard operations
+
+#### Programmatic Configuration
+
+You can also configure clipboard settings programmatically:
+
+```javascript
+// Read current settings
+const settings = JSON.parse(
+  localStorage.getItem('webssh2.settings.global') || '{}'
+)
+
+// Update clipboard settings
+settings.clipboardAutoSelectToCopy = false // Disable auto-copy
+settings.clipboardEnableMiddleClickPaste = true // Enable middle-click
+settings.clipboardEnableKeyboardShortcuts = true // Enable shortcuts
+
+// Save settings
+localStorage.setItem('webssh2.settings.global', JSON.stringify(settings))
+```
+
+### Configuration Object
+
+You can configure the client by setting `window.webssh2Config`:
+
+```javascript
+window.webssh2Config = {
+  socket: {
+    url: null, // WebSocket URL (auto-detected if null)
+    path: '/ssh/socket.io' // Socket.IO path
+  },
+  ssh: {
+    host: null, // SSH server hostname
+    port: 22, // SSH server port
+    username: null,
+    sshterm: 'xterm-color'
+  },
+  header: {
+    text: null,
+    background: 'green'
+  },
+  autoConnect: false
+}
+```
+
+## Development
+
+See [DEVELOPMENT.md](./DEVELOPMENT.md).
 
 ## Support
 
-If you find this project helpful, you can support the developer:
+If you find this project helpful, consider supporting the developer:
 
 [![Buy Me A Coffee](https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png)](https://www.buymeacoffee.com/billchurch)
 
-
 ## License
 
 This project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details.
 
 ## Acknowledgments
 
-- [Xterm.js](https://xtermjs.org/) for providing the terminal emulator
-- [Socket.IO](https://socket.io/) for real-time, bidirectional communication
-- [Webpack](https://webpack.js.org/) for module bundling
+- [Xterm.js](https://xtermjs.org/) for terminal emulation
+- [Socket.IO](https://socket.io/) for WebSocket communication
+- [Vite](https://vitejs.dev/) for development and bundling
+- [ESLint](https://eslint.org/) + [Prettier](https://prettier.io/) for code quality
+- [lucide-static](https://github.com/lucide-icons/lucide) for SVG icons

package/client/index.js

@@ -1,8 +1,14 @@
 // client
-// client/index.js
-const path = require('path');
-
-module.exports = {
+// client/index.ts
+import path from 'path'
+import { readFileSync } from 'fs'
+import { fileURLToPath } from 'url'
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+const packageJson = JSON.parse(
+  readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8')
+)
+export default {
   getPublicPath: () => path.join(__dirname, 'public'),
-  version: require('../package.json').version
-};
+  version: packageJson.version
+}