Prepare WebSSH for self-hosted deployment

2026-06-13 12:11:36 +08:00
parent aaac2afe2a
commit 845c3dece3
20 changed files with 1628 additions and 183 deletions
@@ -0,0 +1,61 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+WebSSH is a web-based SSH client. A Tornado async server handles HTTP/WebSocket connections and tunnels terminal I/O to remote SSH servers via Paramiko. The browser renders the terminal using xterm.js.
+
+## Development Commands
+
+```bash
+# Install
+pip install -r requirements.txt
+pip install -e .            # editable install (provides `wssh` CLI entry point)
+
+# Run
+python run.py               # starts on default port 8888
+python run.py --port=8888 --debug=True --data-dir=./data
+
+# Lint
+ruff check .                # or: flake8 . (max-line-length=79, see setup.cfg)
+
+# Test
+pytest                      # all tests
+pytest --cov=webssh         # with coverage
+pytest tests/test_app.py    # single file
+```
+
+## Architecture
+
+```
+Browser (xterm.js + WebSocket) <--> Tornado (WsockHandler) <--> Paramiko SSH channel <--> Remote SSH server
+```
+
+**Backend (`webssh/`)**
+- `main.py` — entry point; wires routes, parses CLI options, starts Tornado IOLoop.
+- `handler.py` — all Tornado request handlers. `MixinHandler` is the base mixin providing IP filtering, XSRF, origin checks, and session auth. Key handlers: `IndexHandler` (serves UI on GET, initiates SSH on POST), `WsockHandler` (WebSocket relay), `LoginHandler`/`LogoutHandler`, `ConnectionsHandler`/`ConnectionHandler`.
+- `worker.py` — `Worker` class manages the Paramiko SSH channel lifecycle and registers its socket fd on Tornado's IOLoop for async read/write.
+- `settings.py` — CLI option definitions (Tornado `define()`), host key loading, SSL context setup, font defaults.
+- `auth.py` — admin user setup and password verification using PBKDF2-SHA256.
+- `storage.py` — persistent saved-connections store (`connections.json`) with file locking.
+- `policy.py` — thread-safe `AutoAddPolicy` wrapper for Paramiko host key validation.
+- `utils.py` — input parsing/validation helpers (`to_str`, `to_bytes`, `to_int`, `to_ip_address`, hostname/port validators).
+
+**Frontend (`webssh/static/js/main.js`, `webssh/templates/`)**
+- jQuery 3 + Bootstrap 4 UI, xterm.js terminal, WebSocket bridge.
+- `index.html` — terminal page; `login.html` — auth page.
+
+**Data directory** (`~/.webssh` or `--data-dir`): stores `auth.json`, `connections.json`, cookie secret.
+
+## Key Design Constraints
+
+- **Async safety**: Paramiko SSH connections are blocking. Always run them via `IndexHandler.executor` (ThreadPoolExecutor) to avoid blocking the Tornado IOLoop.
+- **Thread safety**: File writes to `auth.json`/`connections.json` and Paramiko host-key mutations must use `threading.Lock`.
+- **New endpoints**: Subclass `MixinHandler`. Use `@tornado.web.authenticated` for protected routes.
+- **Python 3.10+** required (see setup.py classifiers).
+- **File permissions**: Database files (`auth.json`, `connections.json`) are created with mode `0o600`.
+
+## Testing
+
+Tests use pytest. `tests/sshserver.py` spins up a local mock SSH server (Paramiko-based) for integration testing of handler connections, password auth, key auth, and 2FA.