chore: security updates and HTML error pages (#475)

* chore(security): update SECURITY.md and bump webssh2_client to 3.1.0

- Update supported version from 2.6.x to 3.1.x
- Add solid-js/seroval vulnerability assessment (CVE-2026-23737, CVE-2025-27109)
- Refresh Shai-hulud 2.0 IoC scan dates
- Bump webssh2_client dependency from ^3.0.0 to ^3.1.0

* feat(routes): add HTML error pages for browser clients

- Add content negotiation for error responses (HTML vs JSON)
- Create styled error page template with retry button for auth errors
- Update express-adapter to render HTML for browser requests
- Document error response format and content negotiation in ROUTES.md
- Update AUTHENTICATION.md with error handling details

Author: billchurch

DOCS/api/ROUTES.md

@@ -179,6 +179,53 @@ http://localhost:2222/ssh/host/example.com?port=2244&sshterm=xterm-256color&env=
 | 401 | Unauthorized (authentication required or failed) |
 | 404 | Not Found (invalid route) |
 | 500 | Internal Server Error |
+| 502 | Bad Gateway (SSH server unreachable) |
+| 504 | Gateway Timeout (SSH connection timed out) |
+
+## Error Response Format
+
+WebSSH2 uses content negotiation to return appropriate error responses based on the client type.
+
+### Browser Requests (Accept: text/html)
+
+When a browser requests a page and an SSH error occurs, WebSSH2 returns a styled HTML error page with:
+- Error title and description
+- Host and port details
+- "Try Again" button (for 401 authentication errors)
+
+This provides a user-friendly experience instead of raw JSON.
+
+### API Requests (Accept: application/json)
+
+API clients receive JSON error responses:
+
+```json
+{
+  "error": "Connection failed",
+  "message": "Handshake failed: no matching key exchange algorithm",
+  "host": "example.com",
+  "port": 22
+}
+```
+
+### Content Negotiation
+
+The response format is determined by the `Accept` header:
+- If `text/html` appears before `application/json` → HTML error page
+- Otherwise → JSON response
+
+**Examples:**
+
+```bash
+# Browser request - gets HTML error page
+curl -H "Accept: text/html" \
+  "http://localhost:2222/ssh/host/example.com"
+
+# API request - gets JSON response
+curl -H "Accept: application/json" \
+  -u "user:pass" \
+  "http://localhost:2222/ssh/host/example.com"
+```
 
 ## Migration Guide
 

DOCS/features/AUTHENTICATION.md

@@ -139,11 +139,33 @@ if (!validationResult.success) {
 
 This approach:
 - ✅ Prevents invalid credentials from reaching WebSocket layer
-- ✅ Provides immediate feedback on authentication failures  
+- ✅ Provides immediate feedback on authentication failures
 - ✅ Follows HTTP standards for proper status codes
 - ✅ Differentiates between auth failures and network issues
 - ✅ Prevents unnecessary re-authentication attempts for network problems
 
+#### Error Response Format
+
+WebSSH2 uses content negotiation to provide appropriate error responses:
+
+**Browser Requests** (`Accept: text/html`):
+- Returns a styled HTML error page
+- Shows error title, message, and connection details
+- Includes "Try Again" button for 401 errors
+
+**API Requests** (`Accept: application/json`):
+- Returns JSON with error details:
+  ```json
+  {
+    "error": "Authentication failed",
+    "message": "All configured authentication methods failed",
+    "host": "example.com",
+    "port": 22
+  }
+  ```
+
+This ensures browsers display user-friendly error pages while API clients receive machine-readable JSON.
+
 ## Migration Guide: Basic Auth → POST Auth
 
 ### Why Migrate?
@@ -299,7 +321,9 @@ curl -u "username:password" "http://localhost:2222/ssh/host/example.com"
 - **200 OK**: SSH credentials valid, terminal interface served
 - **401 Unauthorized**: SSH credentials invalid, includes `WWW-Authenticate` header
 - **400 Bad Request**: Malformed request or invalid parameters
-- **500 Internal Server Error**: Server-side issues (SSH connection problems, etc.)
+- **500 Internal Server Error**: Server-side issues
+- **502 Bad Gateway**: SSH server unreachable (network/DNS issues)
+- **504 Gateway Timeout**: SSH connection timed out
 
 ### Headers
 

SECURITY.md

@@ -6,8 +6,8 @@ We currently support only the latest released version of WebSSH2 with security u
 
 | Version | Supported          |
 | ------- | ------------------ |
-| 2.6.x   | :white_check_mark: |
-| < 2.6.0 | :x:                |
+| 3.1.x   | :white_check_mark: |
+| < 3.1.0 | :x:                |
 
 **We strongly recommend always using the latest release to ensure you have the most recent security patches and improvements.**
 
@@ -55,9 +55,43 @@ When deploying WebSSH2:
 
 Thank you for helping keep WebSSH2 and its users secure!
 
+## Solid-js and Seroval vulnerability assessment
+
+As of 2026-01-27, we evaluated the following vulnerabilities affecting our client dependencies:
+
+### CVE-2026-23737 (Seroval RCE)
+
+| Aspect | Status |
+|--------|--------|
+| Affected versions | seroval < 1.4.1 |
+| Our version | seroval@1.5.0 (transitive via solid-js) |
+| Status | **Not vulnerable** - already on patched version |
+
+This vulnerability affects the `fromJSON` and `fromCrossJSON` functions in client-to-server transmission scenarios, requiring Solid Start server functions to exploit.
+
+**Why we are not affected:**
+- webssh2_client is a plain Solid.js SPA, not a Solid Start application
+- No `"use server"` directives or server functions are used
+- All client-server communication uses Socket.IO's native JSON serialization
+- seroval is only a transitive dependency and is not directly imported or used
+
+### CVE-2025-27109 (Solid-js XSS)
+
+| Aspect | Status |
+|--------|--------|
+| Vulnerability type | Cross-site Scripting (XSS) |
+| Status | **Not vulnerable** - safe coding patterns used |
+
+**Why we are not affected:**
+- No `innerHTML` or `dangerouslySetInnerHTML` usage in the codebase
+- All JSX uses Solid.js safe text binding
+- Terminal output is rendered through xterm.js which safely handles escape sequences
+
+---
+
 ## Shai-hulud 2.0 supply chain risk
 
-As of 2025-12-03, automated checks for Shai-hulud 2.0 indicators of compromise (IoCs) found **no evidence of compromise** in this repository.
+As of 2026-01-27, automated checks for Shai-hulud 2.0 indicators of compromise (IoCs) found **no evidence of compromise** in this repository.
 
 The scanner performed the following checks:
 
@@ -85,6 +119,6 @@ For more information about detection logic or mitigations, contact the security
 
 ---
 
-**Last updated:** 2025-12-03
+**Last updated:** 2026-01-27
 
-**Next review:** 2026-01-03
+**Next review:** 2026-02-27

app/routes/adapters/express-adapter.ts

@@ -8,6 +8,7 @@ import type { AuthSession } from '../../auth/auth-utils.js'
 import { createNamespacedDebug } from '../../logger.js'
 import { HTTP } from '../../constants/index.js'
 import type { SshRouteResponse, SshRouteRequest } from '../handlers/ssh-handler.js'
+import { renderErrorPage } from '../templates/error-page.js'
 
 const debug = createNamespacedDebug('routes:adapter')
 
@@ -30,6 +31,43 @@ export const extractRouteRequest = (req: ExpressRequest): SshRouteRequest => {
   }
 }
 
+/**
+ * Check if an error response data object has the expected structure
+ */
+const isErrorResponseData = (
+  data: unknown
+): data is { error: string; message: string; host: string; port: number } => {
+  if (data === null || typeof data !== 'object') {
+    return false
+  }
+  const obj = data as Record<string, unknown>
+  return (
+    typeof obj['error'] === 'string' &&
+    typeof obj['message'] === 'string' &&
+    typeof obj['host'] === 'string' &&
+    typeof obj['port'] === 'number'
+  )
+}
+
+/**
+ * Check if request prefers HTML response based on Accept header
+ */
+const prefersHtml = (req: Request): boolean => {
+  const acceptHeader = req.get('accept') ?? ''
+  // Check if text/html appears before application/json in Accept header
+  // or if text/html is present and application/json is not
+  const htmlIndex = acceptHeader.indexOf('text/html')
+  const jsonIndex = acceptHeader.indexOf('application/json')
+
+  if (htmlIndex === -1) {
+    return false
+  }
+  if (jsonIndex === -1) {
+    return true
+  }
+  return htmlIndex < jsonIndex
+}
+
 /**
  * Apply route response to Express response
  */
@@ -53,8 +91,27 @@ export const applyRouteResponse = (
   // Send response
   res.status(response.status)
 
-  // For 502 Bad Gateway, send plain text for compatibility with tests
-  if (response.status === 502) {
+  // Check if this is an error response that should be rendered as HTML for browsers
+  const isErrorStatus = response.status >= 400
+  const req = res.req
+  const acceptsHtml = prefersHtml(req)
+
+  if (isErrorStatus && acceptsHtml && isErrorResponseData(response.data)) {
+    // Browser request with error - return HTML error page
+    const showRetry = response.status === HTTP.UNAUTHORIZED
+    const html = renderErrorPage({
+      title: response.data.error,
+      message: response.data.message,
+      host: response.data.host,
+      port: response.data.port,
+      showRetry
+    })
+    res.type('text/html').send(html)
+    return
+  }
+
+  // For 502 Bad Gateway without proper error data, send plain text for compatibility
+  if (response.status === HTTP.BAD_GATEWAY && !isErrorResponseData(response.data)) {
     res.send('Bad Gateway')
     return
   }