WebSSH2 Client - Web SSH Client

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.

Important Notice

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. This package is intended for advanced users who want to customize or integrate the client component independently.

Requirements

• Modern web browser with JavaScript enabled
• Compatible WebSSH2 server instance (v2.0.0 or compatible)
• Socket.IO v4.8.1 compatibility

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.

Server Requirements

The WebSSH2 client requires a compatible server that provides:

• 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.

Client Features

• 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

Host Key Verification

WebSSH2 Client supports client-side SSH host key verification using a Trust On First Use (TOFU) model. When enabled by the server, the client can independently verify host keys stored in the browser alongside any server-side verification, providing an additional layer of protection against man-in-the-middle attacks.

The server controls whether host key verification is active and whether the client-side store is available. When both are enabled, the client stores trusted host key fingerprints in localStorage and checks them on every connection.

Status Indicators

The status bar displays a shield icon when host key verification is active:

• ShieldCheck (green) — The host key is verified and matches a trusted key. The connection is authenticated.
• ShieldAlert (amber) — The host key is not yet stored or could not be verified against a trusted key.

Click the shield icon to open a popover with host key details including the host, port, algorithm, SHA-256 fingerprint, and where the key was verified (server store or client store).

Trust Prompt

When connecting to an unknown host (no stored key for that host:port and algorithm), a modal appears with:

• The host and port being connected to
• The key algorithm and SHA-256 fingerprint
• Accept / Reject buttons
• A "Remember this key (save to browser)" checkbox (only visible when the client store is enabled)

Accepting the key allows the connection to proceed. Checking the remember option saves the key to the browser so future connections are automatically verified. Rejecting the key closes the connection.

Mismatch Warning

If a host presents a key that does not match the previously stored fingerprint, a hard-block modal is displayed. The connection is always refused — there is no option to accept the mismatched key.

The modal shows both the expected and received fingerprints for comparison. Guidance is provided based on where the key was stored:

• Client store — Remove the old key from Trusted Host Keys in Settings, then reconnect.
• Server store — Contact your administrator to verify the server key has been intentionally changed.

Trusted Host Keys Settings

When the client-side store is enabled, a Trusted Host Keys section appears in the Settings modal (click the gear icon, then expand the "Trusted Host Keys" section).

Viewing stored keys

Each stored key is listed by host:port with its algorithm and computed SHA-256 fingerprint.

Deleting keys

Click the delete button next to any key entry to remove it. This is how you resolve mismatch warnings for keys stored in the client.

Adding keys manually

You can pre-trust a host key by entering:

• Host and Port of the SSH server
• Public key in OpenSSH format: algorithm base64key [comment]

Supported algorithms: ssh-ed25519, ssh-rsa, rsa-sha2-256, rsa-sha2-512, ecdsa-sha2-nistp256, ecdsa-sha2-nistp384, ecdsa-sha2-nistp521

Export and import

• Export downloads all trusted keys as a webssh2-hostkeys.json file.
• Import reads a JSON file and merges the keys into the existing store. Duplicate entries are overwritten by the imported data.

This is useful for sharing trusted keys across browsers or backing up your key store.

localStorage Format

Host keys are stored under the webssh2.hostkeys key in localStorage. The schema is:

{
  "version": 1,
  "keys": {
    "example.com:22": {
      "ssh-ed25519": {
        "key": "<base64-encoded public key>",
        "addedAt": "2026-01-15T10:30:00.000Z"
      }
    }
  }
}

• version — Schema version (currently 1).
• keys — A map keyed by host:port. Each value is a map of algorithm names to key entries.
• key — The base64-encoded public key data.
• addedAt — ISO 8601 timestamp of when the key was stored.

The export and import functions use this same format, so exported files can be imported into any other WebSSH2 Client instance.

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 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
• 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)

Advanced Header Styling

WebSSH2 Client supports comprehensive header styling through two approaches: enhanced headerStyle (recommended) and legacy headerBackground (maintained for backward compatibility).

Enhanced Header Styling (headerStyle)

The headerStyle parameter provides complete control over header appearance using Tailwind CSS classes or CSS properties:

Basic Examples:

# Enhanced background with custom height and text
?header=Production&headerStyle=bg-red-600%20h-10%20text-xl%20font-bold

# Gradient with custom styling
?header=Staging&headerStyle=bg-gradient-to-r%20from-blue-500%20to-purple-500%20h-8%20text-lg

# Custom text colors and shadows
?header=Development&headerStyle=bg-green-500%20text-black%20font-semibold%20shadow-lg

Advanced Styling Capabilities:

Backgrounds & Gradients:

# Multi-directional gradients
?headerStyle=bg-gradient-to-br%20from-purple-600%20via-pink-500%20to-yellow-400%20h-12

# Solid colors with transparency
?headerStyle=bg-blue-500%20h-8%20shadow-blue-500/50

# Complex gradient patterns
?headerStyle=bg-gradient-to-r%20from-red-500%20via-yellow-500%20to-green-500%20h-10

Typography & Layout:

# Large headers with custom fonts
?headerStyle=bg-slate-700%20h-16%20text-3xl%20font-black%20flex%20items-center%20justify-center

# Compact headers
?headerStyle=bg-indigo-600%20h-5%20text-xs%20font-medium

# Custom text alignment and colors
?headerStyle=bg-gradient-to-r%20from-cyan-400%20to-blue-500%20text-left%20text-yellow-100%20px-4

Borders & Effects:

# 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

Animations:

# Pulsing effect for alerts
?headerStyle=bg-red-600%20animate-pulse%20h-8%20font-bold

# Bouncing for urgent notifications
?headerStyle=bg-yellow-500%20animate-bounce%20h-10%20text-black%20font-semibold

Production Examples:

# 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

# Development environment
?header=🛠️%20Development%20Environment&headerStyle=bg-gradient-to-r%20from-green-400%20to-emerald-600%20h-8%20text-white%20font-medium

# 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

# Secure connection
?header=🔐%20Encrypted%20Connection&headerStyle=bg-gradient-to-r%20from-emerald-500%20to-teal-600%20h-8%20text-white%20shadow-md

Legacy Header Styling (headerBackground)

For backward compatibility, the original headerBackground parameter is still supported:

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:

?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:

// 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:

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.

Support

If you find this project helpful, consider supporting the developer:

License

This project is licensed under the MIT License - see the LICENSE.md file for details.

Acknowledgments

• Xterm.js for terminal emulation
• Socket.IO for WebSocket communication
• Vite for development and bundling
• ESLint + Prettier for code quality
• lucide-static for SVG icons