WebSSH2 Server API Documentation

Overview

The WebSSH2 server provides a WebSocket interface for establishing SSH connections. This API documentation outlines the events and data structures used for communication between the client and the server.

Currently this implementation requires Socket.IO v2.2.0 due to this instance targeting node 6.9.1 for a legacy project. Future releases will not have this limitation.

Connection

The server uses Socket.IO for real-time communication. Connect to the WebSocket server at the same host and port as the HTTP server, with the path /ssh/socket.io.

Events

Server to Client Events

1. authentication

   • Emitted to request authentication or provide authentication results.
   • Payload:

     {
       action: string, // "request_auth" or "auth_result"
       success?: boolean, // Only present for "auth_result"
       message?: string // Error message if authentication fails
     }
     

2. permissions

   • Emitted after successful authentication to provide allowed actions.
   • Payload:

     {
       autoLog: boolean,
       allowReplay: boolean,
       allowReconnect: boolean,
       allowReauth: boolean
     }
     

3. getTerminal

   • Emitted to request terminal specifications from the client.
   • Payload: true

4. data

   • Emitted when there's output from the SSH session.
   • Payload: string | Buffer
     • Shell data is emitted as a raw Buffer. Socket.IO 4.x automatically sends Buffers as WebSocket binary frames, avoiding the overhead of UTF-8 string conversion and JSON serialization. The client receives this as an ArrayBuffer.
     • Exec data (from the exec channel) is emitted as a string (UTF-8 encoded), since exec output is already a string from SSH2 and is not a high-throughput path.
   • Client handling: Convert ArrayBuffer to Uint8Array and pass directly to xterm.js Terminal.write(), which natively accepts Uint8Array. Only decode to string when text is needed (e.g., session logging).

5. ssherror

   • Emitted when an SSH-related error occurs.
   • Payload: string (Error message)

6. updateUI

   • Emitted to update specific UI elements.
   • Payload:

     {
       element: string, // UI element identifier
       value: any // New value for the element
     }
     

Client to Server Events

1. authenticate

   • Emit this event to provide authentication credentials.
   • Payload:

     {
       username: string,
       password: string,
       host: string,
       port: number,
       term?: string, // Optional terminal type
       cols?: number, // Optional terminal columns (added for early dimension setup)
       rows?: number, // Optional terminal rows (added for early dimension setup)
       forwardAllKeyboardInteractivePrompts?: boolean // When true, all keyboard-interactive prompts are forwarded to client
     }
     

   • The forwardAllKeyboardInteractivePrompts option bypasses the automatic password handling for keyboard-interactive auth. When set to true, all prompts (including password prompts) will be forwarded to the client for user input. This is useful for debugging or when explicit user interaction is required.

2. terminal

   • Emit this event to provide terminal dimensions.
   • Payload:

     {
       cols: number,
       rows: number
     }
     

   • Note: Terminal type (term) is managed server-side based on authentication parameters or server configuration.

3. data

   • Emit this event to send user input to the SSH session.
   • Payload: string (UTF-8 encoded user input)

4. resize

   • Emit this event when the terminal size changes.
   • Payload:

     {
       cols: number,
       rows: number
     }
     

5. control

   • Emit this event for special control commands.
   • Payload: string ("replayCredentials" or "reauth")

6. disconnect

   • Emit this event to close the connection.
   • No payload required

Authentication Flow

1. The server emits authentication with action: "request_auth".
2. The client emits authenticate with credentials.
3. For keyboard-interactive authentication, the server may emit multiple prompt events:
   • Each prompt contains fields for user input (password or text fields)
   • The client should display these prompts and collect user responses
   • The client responds via prompt-response with the user's answers
   • This loop continues until authentication completes
4. The server emits authentication with action: "auth_result" and success: true/false.

Keyboard-Interactive Behavior

By default:

• First round: If all prompts contain "password", the server auto-responds with the stored password
• Subsequent rounds: All prompts are forwarded to the client (e.g., 2FA verification codes)

This behavior can be overridden:

• Set forwardAllKeyboardInteractivePrompts: true in the authenticate payload to forward all prompts
• Or configure alwaysSendKeyboardInteractivePrompts: true on the server

Establishing SSH Session

1. After successful authentication, the server emits getTerminal.
2. The client emits terminal with terminal dimensions (cols/rows only).
3. The server uses terminal type from authentication parameters or server defaults.
4. The server establishes the SSH connection and starts emitting data events with terminal output.
5. The client can now send data events with user input.

Error Handling

• The client should listen for ssherror events and handle them appropriately (e.g., displaying error messages to the user).

UI Updates

• The client should listen for updateUI events and update the corresponding UI elements.

Best Practices

1. Handle connection errors and implement reconnection logic.
2. Implement proper error handling and user feedback.
3. Securely manage authentication credentials.
4. Handle terminal resizing appropriately.
5. Implement support for special control commands (replay credentials, reauthentication).