SSH Helper

What it is

SSH Helper is a Node.js application that exposes a browser-based terminal interface using xterm.js. It bridges the gap between web browsers and server shells by spawning PTY (pseudo-terminal) sessions via WebSockets. Designed for secure deployment, it offloads authentication to an Nginx/OAuth2 proxy layer (e.g., AWS Cognito) and supports optional IP whitelisting for additional network-level security.

Features

• Full xterm.js terminal emulation with color and responsive design
• WebSocket-based real-time I/O for low-latency shell interaction
• Optional IP whitelisting for network-level access control
• Seamless integration with Nginx and OAuth2 proxies for authentication
• Automated deployment via bootstrap script for systemd and Nginx

Quickstart

git clone https://github.com/davidbmar/ssh-helper
cd ssh-helper
npm install
cp config.json config.local.json
npm run dev

Architecture

flowchart TD
    User[User Browser] -->|HTTPS| Nginx[Nginx Reverse Proxy]
    Nginx -->|Auth Request| OAuth2[OAuth2 Proxy / Cognito]
    OAuth2 -->|Authenticated Headers| Nginx
    Nginx -->|Proxy Pass| App[SSH Helper Node.js]
    App -->|Spawn PTY| Shell[Bash/Sh Shell]
    App -->|WebSocket| User

How it's built

The backend is built with Express.js and the 'ws' library for WebSocket handling, using 'node-pty' to spawn real shell processes (bash/sh). The frontend uses xterm.js for terminal emulation, connecting to the backend via WebSocket. Configuration is managed via a JSON file, and deployment is streamlined using a bash bootstrap script that configures systemd services and modular Nginx includes.

How it runs

sequenceDiagram
    participant U as User
    participant N as Nginx
    participant O as OAuth2 Proxy
    participant S as SSH Helper
    participant P as PTY Process

    U->>N: GET /ssh
    N->>O: /oauth2/auth
    O-->>N: 200 OK + User Headers
    N->>S: Proxy Request + X-User-Email
    S-->>N: HTTP 101 Switching Protocols
    N-->>U: WebSocket Connection Established
    U->>S: Terminal Input (WS)
    S->>P: Write to PTY
    P-->>S: Shell Output
    S-->>U: Terminal Output (WS)

How to apply & reuse

Deploy this tool when you need secure, browser-accessible shell access to development or production servers without exposing raw SSH ports. It is ideal for environments already using Nginx as a reverse proxy with OAuth2/OIDC authentication (like Cognito or Auth0), allowing you to grant terminal access based on user identity rather than just SSH keys.

At a glance