py-web-ssh 0.1.0__py3-none-any.whl

webssh/session.py

@@ -0,0 +1,345 @@
+from __future__ import annotations
+
+import asyncio
+import base64
+import threading
+import time
+import traceback
+import uuid
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from collections.abc import Callable
+from typing import Any, Literal
+
+import paramiko
+from starlette.websockets import WebSocket
+
+from .history import OutputChunk, OutputHistory
+from .models import ConnectRequest, LogEntry, SessionSummary
+from .ssh_client import ConnectedClient, connect_ssh
+
+
+SessionState = Literal["connecting", "connected", "closing", "closed", "error"]
+
+
+@dataclass(eq=False)
+class BrowserConnection:
+    loop: asyncio.AbstractEventLoop
+    queue: asyncio.Queue[dict[str, Any]]
+
+
+class TerminalSession:
+    def __init__(self, config: ConnectRequest, clock: Callable[[], float] = time.monotonic) -> None:
+        self.id = str(uuid.uuid4())
+        self.config = config
+        self._clock = clock
+        self.created_at = datetime.now(timezone.utc)
+        self.updated_at = self.created_at
+        self.state: SessionState = "connecting"
+        self.history = OutputHistory(config.scrollback_bytes)
+        self._logs: list[LogEntry] = []
+        self._clients: set[BrowserConnection] = set()
+        self._lock = threading.RLock()
+        self._channel_lock = threading.RLock()
+        self._stop = threading.Event()
+        self._thread = threading.Thread(target=self._run, name=f"ssh-session-{self.id}", daemon=True)
+        self._connected: ConnectedClient | None = None
+        self._channel: paramiko.Channel | None = None
+        self._snapshot: tuple[int, bytes, datetime] | None = None
+        self._last_client_detached_at: float | None = self._clock()
+        self._reaped = False
+
+    def start(self) -> None:
+        self._thread.start()
+
+    def attach(self, websocket: WebSocket) -> BrowserConnection:
+        connection = BrowserConnection(loop=asyncio.get_running_loop(), queue=asyncio.Queue(maxsize=512))
+        with self._lock:
+            if self._reaped:
+                raise RuntimeError("Session was cleaned up after being idle.")
+            self._clients.add(connection)
+            self._last_client_detached_at = None
+        return connection
+
+    def detach(self, connection: BrowserConnection) -> None:
+        with self._lock:
+            self._clients.discard(connection)
+            if not self._clients:
+                self._last_client_detached_at = self._clock()
+
+    def summary(self) -> SessionSummary:
+        with self._lock:
+            return SessionSummary(
+                session_id=self.id,
+                state=self.state,
+                created_at=self.created_at,
+                updated_at=self.updated_at,
+                config=self.config.sanitized(),
+                output_next_seq=self.history.next_seq,
+                output_earliest_seq=self.history.earliest_seq,
+                has_snapshot=self._snapshot is not None,
+                connected_clients=len(self._clients),
+            )
+
+    def logs(self) -> list[LogEntry]:
+        with self._lock:
+            return list(self._logs)
+
+    def log(self, level: str, message: str, details: str | None = None) -> None:
+        entry = LogEntry(level=level, message=message, details=details)
+        with self._lock:
+            self._logs.append(entry)
+            self.updated_at = entry.timestamp
+        self._broadcast(
+            {
+                "type": "log",
+                "entry": entry.model_dump(mode="json"),
+            }
+        )
+
+    def replay_payload(self) -> dict[str, Any]:
+        with self._lock:
+            snapshot_seq: int | None = None
+            snapshot_b64: str | None = None
+            warning: str | None = None
+            if self._snapshot is not None:
+                snapshot_seq, snapshot, _created_at = self._snapshot
+                snapshot_b64 = base64.b64encode(snapshot).decode("ascii")
+            elif self.history.earliest_seq > 0:
+                warning = (
+                    "The server trimmed early terminal bytes before any browser snapshot was saved. "
+                    "Replay may be incomplete; reconnect sooner or increase scrollback_bytes."
+                )
+
+            since_seq = snapshot_seq
+            if since_seq is not None and since_seq < self.history.earliest_seq:
+                warning = (
+                    "The server trimmed terminal bytes older than the latest browser snapshot. "
+                    "Replay may be incomplete; increase scrollback_bytes for longer disconnected runs."
+                )
+                chunks = self.history.since()
+            else:
+                chunks = self.history.since(since_seq)
+
+            return {
+                "type": "replay",
+                "state": self.state,
+                "snapshot_seq": snapshot_seq,
+                "snapshot": snapshot_b64,
+                "history_earliest_seq": self.history.earliest_seq,
+                "history_next_seq": self.history.next_seq,
+                "chunks": [self._chunk_payload(chunk) for chunk in chunks],
+                "logs": [entry.model_dump(mode="json") for entry in self._logs[-200:]],
+                "warning": warning,
+            }
+
+    def send_input(self, data: bytes) -> None:
+        with self._channel_lock:
+            if self._channel is None or self.state != "connected":
+                raise RuntimeError("SSH channel is not connected.")
+            self._channel.sendall(data)
+
+    def resize(self, cols: int, rows: int) -> None:
+        with self._channel_lock:
+            if self._channel is not None and self.state == "connected":
+                self._channel.resize_pty(width=cols, height=rows)
+
+    def save_snapshot(self, seq: int, snapshot: bytes) -> None:
+        with self._lock:
+            if seq <= self.history.next_seq:
+                self._snapshot = (seq, snapshot, datetime.now(timezone.utc))
+
+    def close(self, reason: str = "Client requested disconnect.") -> None:
+        self.log("info", reason, None)
+        self._set_state("closing")
+        self._stop.set()
+        with self._channel_lock:
+            if self._channel is not None:
+                self._channel.close()
+            if self._connected is not None:
+                self._connected.client.close()
+
+    def mark_reaped_if_idle(self, now: float, idle_timeout_seconds: float) -> bool:
+        with self._lock:
+            if self._clients or self._last_client_detached_at is None or self._reaped:
+                return False
+            if now - self._last_client_detached_at < idle_timeout_seconds:
+                return False
+            self._reaped = True
+            return True
+
+    @property
+    def ssh_client(self) -> paramiko.SSHClient:
+        if self._connected is None or self.state not in ("connected", "closing", "closed"):
+            raise RuntimeError("SSH connection is not ready.")
+        return self._connected.client
+
+    def _run(self) -> None:
+        try:
+            self.log("info", "Creating SSH connection.", None)
+            self._connected = connect_ssh(self.config, self.log)
+            channel = self._connected.transport.open_session()
+            channel.get_pty(
+                term=self.config.term,
+                width=self.config.size.cols,
+                height=self.config.size.rows,
+            )
+            channel.invoke_shell()
+            channel.settimeout(0.0)
+            with self._channel_lock:
+                self._channel = channel
+            self._set_state("connected")
+            self.log("info", "Interactive SSH terminal is ready.", None)
+
+            while not self._stop.is_set():
+                try:
+                    if channel.recv_ready():
+                        data = channel.recv(64 * 1024)
+                        if not data:
+                            break
+                        self._append_output(data)
+                    elif channel.exit_status_ready():
+                        break
+                    else:
+                        time.sleep(0.01)
+                except paramiko.ssh_exception.SSHException:
+                    raise
+                except Exception as exc:
+                    if self._stop.is_set():
+                        break
+                    if "timed out" not in str(exc).lower():
+                        raise
+
+            if self._stop.is_set():
+                self._set_state("closed")
+                self.log("info", "SSH terminal closed by request.", None)
+            else:
+                self._set_state("closed")
+                self.log("warning", "SSH terminal channel closed by the remote server.", None)
+        except Exception as exc:
+            self._set_state("error")
+            self.log("error", f"SSH session failed: {exc}", traceback.format_exc())
+            self._append_output(f"\r\n[py-web-ssh] SSH session failed: {exc}\r\n".encode("utf-8"))
+        finally:
+            with self._channel_lock:
+                try:
+                    if self._channel is not None:
+                        self._channel.close()
+                finally:
+                    self._channel = None
+                if self._connected is not None:
+                    self._connected.client.close()
+            if self.state not in ("error", "closed"):
+                self._set_state("closed")
+
+    def _append_output(self, data: bytes) -> None:
+        with self._lock:
+            chunk = self.history.append(data)
+            self.updated_at = datetime.now(timezone.utc)
+        self._broadcast(self._chunk_payload(chunk) | {"type": "output"})
+
+    def _chunk_payload(self, chunk: OutputChunk) -> dict[str, Any]:
+        return {
+            "seq": chunk.seq,
+            "data": base64.b64encode(chunk.data).decode("ascii"),
+        }
+
+    def _set_state(self, state: SessionState) -> None:
+        with self._lock:
+            self.state = state
+            self.updated_at = datetime.now(timezone.utc)
+        self._broadcast({"type": "status", "state": state})
+
+    def _broadcast(self, message: dict[str, Any]) -> None:
+        with self._lock:
+            clients = list(self._clients)
+        for client in clients:
+            try:
+                client.loop.call_soon_threadsafe(self._queue_message, client, message)
+            except RuntimeError:
+                self.detach(client)
+
+    def _queue_message(self, client: BrowserConnection, message: dict[str, Any]) -> None:
+        try:
+            client.queue.put_nowait(message)
+        except asyncio.QueueFull:
+            try:
+                client.queue.get_nowait()
+            except asyncio.QueueEmpty:
+                pass
+            client.queue.put_nowait(
+                {
+                    "type": "warning",
+                    "message": "Browser message queue overflowed; an output frame was dropped.",
+                }
+            )
+
+
+class SessionManager:
+    def __init__(
+        self,
+        idle_timeout_seconds: float = 300.0,
+        cleanup_interval_seconds: float = 30.0,
+        autostart_reaper: bool = True,
+        clock: Callable[[], float] = time.monotonic,
+    ) -> None:
+        self._sessions: dict[str, TerminalSession] = {}
+        self._lock = threading.RLock()
+        self._idle_timeout_seconds = idle_timeout_seconds
+        self._cleanup_interval_seconds = cleanup_interval_seconds
+        self._clock = clock
+        self._stop_reaper = threading.Event()
+        self._reaper_thread: threading.Thread | None = None
+        if autostart_reaper and idle_timeout_seconds > 0:
+            self._reaper_thread = threading.Thread(
+                target=self._run_reaper,
+                name="ssh-session-reaper",
+                daemon=True,
+            )
+            self._reaper_thread.start()
+
+    def create(self, config: ConnectRequest) -> TerminalSession:
+        session = TerminalSession(config, clock=self._clock)
+        with self._lock:
+            self._sessions[session.id] = session
+        session.start()
+        return session
+
+    def get(self, session_id: str) -> TerminalSession | None:
+        with self._lock:
+            return self._sessions.get(session_id)
+
+    def list(self) -> list[TerminalSession]:
+        with self._lock:
+            return list(self._sessions.values())
+
+    def close(self, session_id: str, reason: str = "Client requested disconnect.") -> bool:
+        session = self.get(session_id)
+        if session is None:
+            return False
+        session.close(reason)
+        return True
+
+    def cleanup_expired(self) -> list[str]:
+        now = self._clock()
+        expired: list[tuple[str, TerminalSession]] = []
+        with self._lock:
+            for session_id, session in list(self._sessions.items()):
+                if session.mark_reaped_if_idle(now, self._idle_timeout_seconds):
+                    expired.append((session_id, session))
+                    self._sessions.pop(session_id, None)
+
+        for session_id, session in expired:
+            session.close(
+                "No browser reconnected for 300 seconds; SSH session is being cleaned up."
+            )
+        return [session_id for session_id, _session in expired]
+
+    def stop_reaper(self) -> None:
+        self._stop_reaper.set()
+        if self._reaper_thread is not None:
+            self._reaper_thread.join(timeout=2.0)
+
+    def _run_reaper(self) -> None:
+        while not self._stop_reaper.wait(self._cleanup_interval_seconds):
+            self.cleanup_expired()

webssh/ssh_client.py

@@ -0,0 +1,288 @@
+from __future__ import annotations
+
+import io
+import socket
+import traceback
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Callable
+
+import paramiko
+
+from .models import ConnectRequest
+
+
+LogCallback = Callable[[str, str, str | None], None]
+
+
+@dataclass
+class ConnectedClient:
+    client: paramiko.SSHClient
+    transport: paramiko.Transport
+
+
+def connect_ssh(config: ConnectRequest, log: LogCallback) -> ConnectedClient:
+    """Open an SSH connection, including legacy algorithms Paramiko still supports."""
+
+    sock = socket.create_connection((config.host, config.port), timeout=config.timeout_seconds)
+    try:
+        transport = paramiko.Transport(sock, disabled_algorithms={})
+        if config.legacy_algorithms:
+            _enable_legacy_algorithms(transport, log)
+
+        log("info", f"Starting SSH handshake with {config.host}:{config.port}.", None)
+        transport.start_client(timeout=config.timeout_seconds)
+        if config.keepalive_seconds:
+            transport.set_keepalive(config.keepalive_seconds)
+
+        if config.strict_host_key:
+            _check_known_host(config, transport, log)
+        else:
+            log("warning", "Strict host key checking is disabled for this browser session.", None)
+
+        _authenticate(transport, config, log)
+
+        client = paramiko.SSHClient()
+        client._transport = transport  # Paramiko exposes no public constructor for this case.
+        log("info", "SSH authentication succeeded.", None)
+        return ConnectedClient(client=client, transport=transport)
+    except Exception:
+        sock.close()
+        raise
+
+
+def _enable_legacy_algorithms(transport: paramiko.Transport, log: LogCallback) -> None:
+    options = transport.get_security_options()
+    preferred = {
+        "kex": (
+            "curve25519-sha256@libssh.org",
+            "ecdh-sha2-nistp256",
+            "ecdh-sha2-nistp384",
+            "ecdh-sha2-nistp521",
+            "diffie-hellman-group16-sha512",
+            "diffie-hellman-group14-sha256",
+            "diffie-hellman-group-exchange-sha256",
+            "diffie-hellman-group14-sha1",
+            "diffie-hellman-group-exchange-sha1",
+            "diffie-hellman-group1-sha1",
+        ),
+        "ciphers": (
+            "aes128-ctr",
+            "aes192-ctr",
+            "aes256-ctr",
+            "aes128-gcm@openssh.com",
+            "aes256-gcm@openssh.com",
+            "aes128-cbc",
+            "aes192-cbc",
+            "aes256-cbc",
+            "3des-cbc",
+        ),
+        "digests": (
+            "hmac-sha2-256",
+            "hmac-sha2-512",
+            "hmac-sha1",
+            "hmac-sha1-96",
+            "hmac-md5",
+            "hmac-md5-96",
+        ),
+        "key_types": (
+            "ssh-ed25519",
+            "ecdsa-sha2-nistp256",
+            "ecdsa-sha2-nistp384",
+            "ecdsa-sha2-nistp521",
+            "rsa-sha2-512",
+            "rsa-sha2-256",
+            "ssh-rsa",
+            "ssh-dss",
+        ),
+        "pubkeys": (
+            "ssh-ed25519",
+            "ecdsa-sha2-nistp256",
+            "ecdsa-sha2-nistp384",
+            "ecdsa-sha2-nistp521",
+            "rsa-sha2-512",
+            "rsa-sha2-256",
+            "ssh-rsa",
+            "ssh-dss",
+        ),
+    }
+
+    changed: list[str] = []
+    unavailable: list[str] = []
+    for attr, wanted in preferred.items():
+        current = _current_algorithms(options, attr)
+        supported = _supported_algorithms(options, attr)
+        wanted_supported = [item for item in wanted if item in supported]
+        unavailable.extend(f"{attr}:{item}" for item in wanted if item not in supported)
+        merged = tuple(dict.fromkeys(wanted_supported + list(current)))
+        try:
+            _set_algorithms(options, attr, merged)
+            changed.append(f"{attr}={','.join(merged)}")
+        except Exception as exc:  # pragma: no cover - depends on Paramiko build/runtime.
+            log("warning", f"Could not set SSH {attr} algorithms: {exc}", None)
+
+    details = "\n".join(changed)
+    if unavailable:
+        details += "\n\nUnavailable in this Paramiko runtime:\n" + "\n".join(unavailable)
+    log("debug", "Paramiko security options prepared for broad legacy compatibility.", details)
+
+
+def _current_algorithms(options: paramiko.transport.SecurityOptions, attr: str) -> tuple[str, ...]:
+    if attr == "pubkeys":
+        return tuple(options._transport._preferred_pubkeys)
+    return tuple(getattr(options, attr))
+
+
+def _set_algorithms(
+    options: paramiko.transport.SecurityOptions,
+    attr: str,
+    algorithms: tuple[str, ...],
+) -> None:
+    if attr == "pubkeys":
+        options._transport._preferred_pubkeys = algorithms
+    else:
+        setattr(options, attr, algorithms)
+
+
+def _supported_algorithms(options: paramiko.transport.SecurityOptions, attr: str) -> set[str]:
+    if attr == "pubkeys":
+        return set(options._transport._key_info.keys())
+
+    transport = options._transport
+    info_attr = {
+        "kex": "_kex_info",
+        "ciphers": "_cipher_info",
+        "digests": "_mac_info",
+        "key_types": "_key_info",
+    }[attr]
+    return set(getattr(transport, info_attr).keys())
+
+
+def _check_known_host(config: ConnectRequest, transport: paramiko.Transport, log: LogCallback) -> None:
+    host_key = transport.get_remote_server_key()
+    known_hosts = paramiko.HostKeys()
+    paths = [
+        Path.home() / ".ssh" / "known_hosts",
+        Path.home() / ".ssh" / "known_hosts2",
+    ]
+    for path in paths:
+        if path.exists():
+            known_hosts.load(str(path))
+
+    candidates = [config.host, f"[{config.host}]:{config.port}"]
+    for candidate in candidates:
+        if known_hosts.check(candidate, host_key):
+            log("info", f"Host key verified for {candidate}.", None)
+            return
+
+    raise paramiko.SSHException(
+        "Strict host key checking failed. The remote host key is not present in "
+        "~/.ssh/known_hosts for this server and port."
+    )
+
+
+def _authenticate(transport: paramiko.Transport, config: ConnectRequest, log: LogCallback) -> None:
+    username = config.username
+    errors: list[str] = []
+
+    if config.private_key:
+        try:
+            pkey = _load_private_key(config.private_key, config.private_key_passphrase)
+            log("info", f"Trying private key authentication using {pkey.get_name()}.", None)
+            transport.auth_publickey(username, pkey)
+        except Exception as exc:
+            errors.append(f"private key: {exc}")
+            log("warning", f"Private key authentication failed: {exc}", traceback.format_exc())
+        if transport.is_authenticated():
+            return
+
+    if config.allow_agent:
+        try:
+            for key in paramiko.Agent().get_keys():
+                try:
+                    log("info", f"Trying SSH agent key {key.get_name()}.", None)
+                    transport.auth_publickey(username, key)
+                except Exception as exc:
+                    errors.append(f"agent key {key.get_name()}: {exc}")
+                    log("debug", f"SSH agent key failed: {exc}", None)
+                if transport.is_authenticated():
+                    return
+        except Exception as exc:
+            errors.append(f"agent: {exc}")
+            log("warning", f"SSH agent authentication failed: {exc}", traceback.format_exc())
+
+    if config.look_for_keys:
+        for key in _load_default_private_keys(config.private_key_passphrase, log):
+            try:
+                log("info", f"Trying local key file {key.get_name()}.", None)
+                transport.auth_publickey(username, key)
+            except Exception as exc:
+                errors.append(f"local key {key.get_name()}: {exc}")
+                log("debug", f"Local key failed: {exc}", None)
+            if transport.is_authenticated():
+                return
+
+    if config.password is not None:
+        try:
+            log("info", "Trying password authentication.", None)
+            transport.auth_password(username, config.password, fallback=True)
+        except Exception as exc:
+            errors.append(f"password: {exc}")
+            log("warning", f"Password authentication failed: {exc}", traceback.format_exc())
+        if transport.is_authenticated():
+            return
+
+        try:
+            log("info", "Trying keyboard-interactive authentication with the supplied password.", None)
+            transport.auth_interactive(username, lambda _title, _instructions, prompts: [config.password] * len(prompts))
+        except Exception as exc:
+            errors.append(f"keyboard-interactive: {exc}")
+            log("warning", f"Keyboard-interactive authentication failed: {exc}", traceback.format_exc())
+        if transport.is_authenticated():
+            return
+
+    try:
+        log("info", "Trying none authentication.", None)
+        transport.auth_none(username)
+    except Exception as exc:
+        errors.append(f"none: {exc}")
+        log("debug", f"None authentication failed: {exc}", None)
+    if transport.is_authenticated():
+        return
+
+    joined = "\n".join(errors) if errors else "No authentication method was accepted."
+    raise paramiko.AuthenticationException(f"SSH authentication failed:\n{joined}")
+
+
+def _load_private_key(text: str, passphrase: str | None) -> paramiko.PKey:
+    errors: list[str] = []
+    key_classes = [
+        paramiko.Ed25519Key,
+        paramiko.ECDSAKey,
+        paramiko.RSAKey,
+        paramiko.DSSKey,
+    ]
+    for key_class in key_classes:
+        try:
+            return key_class.from_private_key(io.StringIO(text), password=passphrase)
+        except Exception as exc:
+            errors.append(f"{key_class.__name__}: {exc}")
+    raise paramiko.SSHException("Could not parse private key. Tried: " + "; ".join(errors))
+
+
+def _load_default_private_keys(passphrase: str | None, log: LogCallback) -> list[paramiko.PKey]:
+    candidates = [
+        Path.home() / ".ssh" / "id_ed25519",
+        Path.home() / ".ssh" / "id_ecdsa",
+        Path.home() / ".ssh" / "id_rsa",
+        Path.home() / ".ssh" / "id_dsa",
+    ]
+    keys: list[paramiko.PKey] = []
+    for path in candidates:
+        if not path.exists():
+            continue
+        try:
+            keys.append(_load_private_key(path.read_text(encoding="utf-8"), passphrase))
+        except Exception as exc:
+            log("debug", f"Could not load local key {path}: {exc}", None)
+    return keys