feat(ux): client-side connection error modal with algorithm debugging (#476)

* feat(ux): client-side connection error modal with algorithm debugging

Replace server-side HTML error pages with rich client-side error modals.
When SSH connections fail, the client now receives structured error data
via the 'connection-error' WebSocket event and displays a helpful modal
with algorithm debugging information.

Changes:
- Add SSH algorithm capture from ssh2 debug logs during handshake
- Add algorithm analyzer to detect client/server mismatches and suggest fixes
- Add error normalizer for consistent, meaningful SSH error messages
- New 'connection-error' socket event with ConnectionErrorData payload
- Remove server-side HTML error page rendering (error-page.ts deleted)
- SSH validation moved from HTTP request to WebSocket connection
- Update webssh2_client to v3.2.0 (includes ConnectionErrorModal)

New files:
- app/services/ssh/algorithm-capture.ts - Captures algorithm negotiation
- app/services/ssh/algorithm-analyzer.ts - Analyzes compatibility issues
- app/services/ssh/error-normalizer.ts - Normalizes SSH2 error messages
- app/constants/algorithm-env-vars.ts - Environment variable mappings

BREAKING CHANGE: Error responses are now JSON-only. Clients must handle
the 'connection-error' event to display connection failures.

* test: update e2e tests for client-side error modal

Update authentication tests to work with the new ConnectionErrorModal:

- Tests now click "Try Again" button to dismiss error modal before
  checking for login form visibility
- Replace tests expecting HTTP 401/502 status codes with tests that
  verify error modal appears with appropriate messages
- Remove unused testBasicAuthErrorResponse import

The new behavior serves the client (200) for all Basic Auth requests
and displays connection errors via WebSocket 'connection-error' event.

* fix(lint): use export type...from syntax for re-exports

Replace import-then-export pattern with direct export type...from
syntax to fix SonarQube S7763 warnings in auth-utils.ts.

* refactor(test): extract shared algorithm test fixtures

Move duplicated AlgorithmSet builders from algorithm-analyzer and
algorithm-capture tests into shared fixtures file to reduce code
duplication flagged by SonarQube.

* fix(lint): remove deprecated eslint-env comments

ESLint flat config no longer recognizes /* eslint-env */ comments.
The existing /* global */ comments already declare the needed browser
globals, making eslint-env redundant.

* refactor(test): use credential builders and shared fixtures

- Use validCredentials(), invalidCredentials(), credentialsWithHost(),
  and credentialsWithPort() helpers in Playwright tests
- Extract shared algorithm test fixtures to reduce inline definitions
- Use it.each pattern for parametrized test cases

* fix(lint): resolve SonarQube warnings

- S7763: use export...from for type re-exports
- S6571: simplify Error | unknown to just unknown
- S4624: extract nested template literals to variables
- S4144: deduplicate identical createModernClientSet function

Author: billchurch

DOCS/api/ROUTES.md

@@ -20,10 +20,10 @@ WebSSH2 provides several HTTP routes for different authentication methods and ut
 **Screenshots:**
 
 Login Form:
-<img width="341" alt="Login Form" src="https://github.com/user-attachments/assets/829d1776-3bc5-4315-b0c6-9e96a648ce06">
+![Login Form](https://github.com/user-attachments/assets/829d1776-3bc5-4315-b0c6-9e96a648ce06)
 
 Terminal Configuration:
-<img width="341" alt="Terminal Configuration" src="https://github.com/user-attachments/assets/bf60f5ba-7221-4177-8d64-946907aed5ff">
+![Terminal Configuration](https://github.com/user-attachments/assets/bf60f5ba-7221-4177-8d64-946907aed5ff)
 
 ### 2. `/ssh/host/:host` - HTTP Basic Auth ⚠️ **DEPRECATED**
 
@@ -45,7 +45,7 @@ WebSSH2 validates SSH credentials immediately upon receiving HTTP Basic Auth cre
 **Expected Behavior:**
 
 1. **URL without embedded credentials:**
-   ```
+   ```text
    http://localhost:2222/ssh/host/example.com
    ```
    - Invalid credentials → 401 Unauthorized
@@ -54,7 +54,7 @@ WebSSH2 validates SSH credentials immediately upon receiving HTTP Basic Auth cre
    - Success
 
 2. **URL with embedded credentials:**
-   ```
+   ```text
    http://user:pass@localhost:2222/ssh/host/example.com
    ```
    - Browser always uses URL credentials
@@ -154,33 +154,33 @@ const response = await fetch('/ssh', {
 
 All routes support the following query parameters:
 
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `port` | integer | 22 | SSH port to connect to |
-| `sshterm` | string | xterm-color | Terminal type |
-| `header` | string | - | Header text override |
-| `headerBackground` | string | green | Header background color |
-| `headerStyle` | string | - | Additional inline styles (e.g., `color: red`) |
-| `env` | string | - | Comma-separated env pairs (e.g., `FOO:bar,BAR:baz`) |
+| Parameter          | Type    | Default     | Description                                           |
+| ------------------ | ------- | ----------- | ----------------------------------------------------- |
+| `port`             | integer | 22          | SSH port to connect to                                |
+| `sshterm`          | string  | xterm-color | Terminal type                                         |
+| `header`           | string  | -           | Header text override                                  |
+| `headerBackground` | string  | green       | Header background color                               |
+| `headerStyle`      | string  | -           | Additional inline styles (e.g., `color: red`)         |
+| `env`              | string  | -           | Comma-separated env pairs (e.g., `FOO:bar,BAR:baz`)   |
 
 ### Example with Query Parameters
 
-```
+```text
 http://localhost:2222/ssh/host/example.com?port=2244&sshterm=xterm-256color&env=DEBUG:true,NODE_ENV:production
 ```
 
 ## Response Codes
 
-| Code | Description |
-|------|-------------|
-| 200 | Success |
-| 302 | Redirect (for reauth) |
-| 400 | Bad Request (invalid parameters) |
-| 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) |
+| Code | Description                                       |
+| ---- | ------------------------------------------------- |
+| 200  | Success                                           |
+| 302  | Redirect (for reauth)                             |
+| 400  | Bad Request (invalid parameters)                  |
+| 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
 

DOCS/configuration/ENVIRONMENT-VARIABLES.md

@@ -387,7 +387,6 @@ See [CONFIG-JSON.md](./CONFIG-JSON.md) for `config.json` examples and additional
 
 | Variable | Type | Default | Description |
 |----------|------|---------|-------------|
-| `WEBSSH2_LOGGING_FORMAT` | string | `json` | Structured log output format (`json` only at present) |
 | `WEBSSH2_LOGGING_LEVEL` | string | `info` | Global minimum log level (`debug`, `info`, `warn`, `error`) |
 | `WEBSSH2_LOGGING_STDOUT_ENABLED` | boolean | `true` | Enables stdout transport when `true` |
 | `WEBSSH2_LOGGING_STDOUT_MIN_LEVEL` | string | `info` | Per-transport minimum level for stdout delivery |
@@ -469,6 +468,34 @@ docker run --name webssh2 --rm -it \
 | `WEBSSH2_SESSION_SECRET` | string | auto-generated | Session encryption secret |
 | `WEBSSH2_SESSION_NAME` | string | `webssh2.sid` | Session cookie name |
 
+### SSO Configuration (Single Sign-On)
+
+| Variable | Type | Default | Description |
+|----------|------|---------|-------------|
+| `WEBSSH2_SSO_ENABLED` | boolean | `false` | Enable SSO authentication via trusted headers |
+| `WEBSSH2_SSO_CSRF_PROTECTION` | boolean | `true` | Enable CSRF protection for SSO endpoints |
+| `WEBSSH2_SSO_TRUSTED_PROXIES` | array | `[]` | IP addresses/subnets of trusted reverse proxies (comma-separated or JSON) |
+| `WEBSSH2_SSO_HEADER_USERNAME` | string | `null` | HTTP header containing the username |
+| `WEBSSH2_SSO_HEADER_PASSWORD` | string | `null` | HTTP header containing the password |
+| `WEBSSH2_SSO_HEADER_SESSION` | string | `null` | HTTP header containing the session identifier |
+
+#### SSO Example
+
+```bash
+# Enable SSO with header-based authentication behind a reverse proxy
+WEBSSH2_SSO_ENABLED=true
+WEBSSH2_SSO_CSRF_PROTECTION=true
+WEBSSH2_SSO_TRUSTED_PROXIES="10.0.0.0/8,172.16.0.0/12"
+WEBSSH2_SSO_HEADER_USERNAME="X-Auth-Username"
+WEBSSH2_SSO_HEADER_PASSWORD="X-Auth-Password"
+```
+
+#### SSO Security Notes
+
+- **Trusted Proxies**: Only configure trusted proxy IPs/subnets. Requests from untrusted sources will have SSO headers ignored.
+- **CSRF Protection**: Keep enabled unless your reverse proxy handles CSRF protection.
+- **Header Security**: Ensure your reverse proxy strips incoming SSO headers from client requests to prevent header injection attacks.
+
 ## Data Type Formats
 
 ### Boolean Values

DOCS/features/AUTHENTICATION.md

@@ -52,6 +52,7 @@ POST authentication supports flexible parameter passing:
 - **Precedence:** Body parameters override query parameters
 
 This allows SSO systems to:
+
 1. Send credentials securely in POST body
 2. Specify target host via URL query parameters
 3. Mix and match based on security requirements
@@ -67,6 +68,7 @@ WebSSH2 validates SSH credentials **immediately** upon receiving HTTP Basic Auth
 **URL Format:** `http://localhost:2222/ssh/host/example.com`
 
 **Flow:**
+
 1. User navigates to URL
 2. Browser prompts for credentials (if not cached)
 3. WebSSH2 validates SSH credentials immediately
@@ -78,6 +80,7 @@ WebSSH2 validates SSH credentials **immediately** upon receiving HTTP Basic Auth
 **URL Format:** `http://user:pass@localhost:2222/ssh/host/example.com`
 
 **Flow:**
+
 1. Browser automatically uses embedded credentials
 2. WebSSH2 validates SSH credentials immediately
 3. **Invalid credentials** → 401 Unauthorized → **No re-authentication possible**
@@ -138,6 +141,7 @@ if (!validationResult.success) {
   - Re-authentication won't help
 
 This approach:
+
 - ✅ Prevents invalid credentials from reaching WebSocket layer
 - ✅ Provides immediate feedback on authentication failures
 - ✅ Follows HTTP standards for proper status codes
@@ -149,12 +153,15 @@ This approach:
 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",
@@ -178,6 +185,7 @@ This ensures browsers display user-friendly error pages while API clients receiv
 ### Migration Examples
 
 #### Before (Basic Auth - Deprecated)
+
 ```bash
 # Browser-based
 curl -u "username:password" "http://localhost:2222/ssh/host/example.com"
@@ -187,6 +195,7 @@ curl "http://username:password@localhost:2222/ssh/host/example.com"
 ```
 
 #### After (POST Auth - Recommended)
+
 ```bash
 # Standard POST request - all parameters in body
 curl -X POST "http://localhost:2222/ssh" \
@@ -265,13 +274,15 @@ async function authenticateWithSSO(ssoToken, targetHost, targetPort = 22) {
 ### For Users
 
 1. **For interactive re-authentication:** Use URLs without embedded credentials
-   ```
+
+   ```text
    ✅ Good: http://localhost:2222/ssh/host/example.com
    ❌ Problematic: http://user:pass@localhost:2222/ssh/host/example.com
    ```
 
 2. **For scripted/automated access:** Embed credentials in URL (no retry needed)
-   ```
+
+   ```text
    ✅ Good: http://validuser:validpass@localhost:2222/ssh/host/example.com
    ```
 
@@ -299,6 +310,7 @@ async function authenticateWithSSO(ssoToken, targetHost, targetPort = 22) {
 **Symptom:** 401 response but no authentication dialog appears
 
 **Causes & Solutions:**
+
 1. **Embedded credentials in URL** → Remove credentials from URL
 2. **Browser cached credentials** → Clear browser auth cache or use incognito mode
 3. **CORS issues** → Check server CORS configuration
@@ -310,6 +322,7 @@ async function authenticateWithSSO(ssoToken, targetHost, targetPort = 22) {
 **Solution:** Ensure scripts are properly encoding credentials and handling 401 responses
 
 **Example curl command:**
+
 ```bash
 curl -u "username:password" "http://localhost:2222/ssh/host/example.com"
 ```
@@ -328,7 +341,8 @@ curl -u "username:password" "http://localhost:2222/ssh/host/example.com"
 ### Headers
 
 **401 Response Headers:**
-```
+
+```http
 HTTP/1.1 401 Unauthorized
 WWW-Authenticate: Basic realm="WebSSH2"
 ```
@@ -342,6 +356,7 @@ DEBUG=webssh2:routes npm start
 ```
 
 Look for log entries like:
+
 - `Validating SSH credentials for user@host:port`
 - `SSH validation successful for user@host:port`
 - `SSH validation failed for user@host:port`
@@ -350,4 +365,4 @@ Look for log entries like:
 
 - [CONFIG.md](CONFIG.md) - Server configuration options
 - [SERVER_API.md](SERVER_API.md) - WebSocket API documentation
-- [DEVELOPMENT.md](DEVELOPMENT.md) - Development and testing guidelines
+- [DEVELOPMENT.md](DEVELOPMENT.md) - Development and testing guidelines