webssh2/SERVER_API.md

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 (UTF-8 encoded terminal output)

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
     }
     

2. terminal

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

     {
       term: string, // e.g., "xterm-256color"
       cols: number,
       rows: number
     }
     

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. The server may emit authentication with action: "keyboard-interactive" for additional authentication steps.
4. The server emits authentication with action: "auth_result" and success: true/false.

Establishing SSH Session

1. After successful authentication, the server emits getTerminal.
2. The client emits terminal with terminal specifications.
3. The server establishes the SSH connection and starts emitting data events with terminal output.
4. 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).