bamboo-ssh 0.1.0__py3-none-any.whl

bamboo_ssh/__init__.py

@@ -0,0 +1,5 @@
+"""Bamboo SSH package."""
+
+from .core import TerminalSession, stream_terminal_output
+
+__all__ = ["TerminalSession", "stream_terminal_output"]

bamboo_ssh/adapters/__init__.py

@@ -0,0 +1,6 @@
+"""FastAPI adapter exports."""
+
+from .fastapi_app import app, build_arg_parser, main
+
+__all__ = ["app", "build_arg_parser", "main"]
+

bamboo_ssh/adapters/fastapi_app.py

@@ -0,0 +1,236 @@
+from __future__ import annotations
+
+import argparse
+import asyncio
+import contextlib
+from html import escape
+from pathlib import Path
+from typing import Any
+from urllib.parse import parse_qs
+
+import uvicorn
+from fastapi import FastAPI, Request, WebSocket, WebSocketDisconnect, status
+from fastapi.responses import FileResponse, HTMLResponse, RedirectResponse, Response
+from fastapi.staticfiles import StaticFiles
+
+from bamboo_ssh.core.session import TerminalSession, stream_terminal_output
+
+
+SESSION_COOKIE_NAME = "bamboo_ssh_session"
+
+
+def _resolve_static_dir(
+    package_static_dir: Path | None = None,
+    checkout_static_dir: Path | None = None,
+) -> Path:
+    package_root = Path(__file__).resolve().parents[1]
+    candidates = (
+        package_static_dir or package_root / "static",
+        checkout_static_dir or package_root.parent / "static",
+    )
+    for candidate in candidates:
+        if candidate.is_dir():
+            return candidate
+    raise FileNotFoundError(f"Could not find static assets in: {', '.join(str(path) for path in candidates)}")
+
+
+def _resolve_login_template(package_template_path: Path | None = None) -> Path:
+    package_root = Path(__file__).resolve().parents[1]
+    candidate = package_template_path or package_root / "ui" / "templates" / "login.html"
+    if candidate.is_file():
+        return candidate
+    raise FileNotFoundError(f"Could not find login template: {candidate}")
+
+
+def _load_auth_settings(config: Any | None, config_path: str | Path | None) -> Any | None:
+    if config is not None:
+        auth_settings = getattr(config, "auth", None)
+        return auth_settings if auth_settings is not None and getattr(auth_settings, "enabled", False) else None
+
+    if config_path is None:
+        return None
+
+    resolved_config_path = Path(config_path).expanduser().resolve()
+    if not resolved_config_path.exists():
+        raise FileNotFoundError(f"Config file not found: {resolved_config_path}")
+
+    from bamboo_ssh.auth.config import load_config
+
+    auth_settings = load_config(resolved_config_path).auth
+    return auth_settings if auth_settings is not None and auth_settings.enabled else None
+
+
+def _read_login_template(template_path: Path, error_message: str | None = None) -> str:
+    template = template_path.read_text(encoding="utf-8")
+    error_html = ""
+    if error_message:
+        error_html = f'<p class="login-error" role="alert">{escape(error_message)}</p>'
+    return template.replace("{{ERROR_BLOCK}}", error_html)
+
+
+def _parse_form_body(body: bytes) -> dict[str, str]:
+    try:
+        parsed = parse_qs(body.decode("utf-8"), keep_blank_values=True)
+    except UnicodeDecodeError:
+        return {}
+
+    return {key: values[-1] if values else "" for key, values in parsed.items()}
+
+
+def _validate_session_token(token: str | None, auth_settings: Any | None) -> bool:
+    if auth_settings is None or not token:
+        return False
+
+    from bamboo_ssh.auth.sessions import validate_session_token
+
+    return validate_session_token(token, auth_settings) is not None
+
+
+def _is_authenticated(cookies: dict[str, str], auth_settings: Any | None) -> bool:
+    if auth_settings is None:
+        return True
+    return _validate_session_token(cookies.get(SESSION_COOKIE_NAME), auth_settings)
+
+
+def _redirect(location: str) -> RedirectResponse:
+    return RedirectResponse(location, status_code=status.HTTP_303_SEE_OTHER)
+
+
+def _render_login_page(template_path: Path, error_message: str | None = None, status_code: int = 200) -> HTMLResponse:
+    return HTMLResponse(_read_login_template(template_path, error_message), status_code=status_code)
+
+
+def _parse_positive_int(value: str | None, default: int) -> int:
+    try:
+        parsed = int(value or "")
+    except ValueError:
+        return default
+    return parsed if parsed > 0 else default
+
+
+def create_app(
+    *,
+    config: Any | None = None,
+    config_path: str | Path | None = None,
+    package_static_dir: Path | None = None,
+    checkout_static_dir: Path | None = None,
+    login_template_path: Path | None = None,
+) -> FastAPI:
+    static_dir = _resolve_static_dir(package_static_dir, checkout_static_dir)
+    template_path = _resolve_login_template(login_template_path)
+    auth_settings = _load_auth_settings(config, config_path)
+
+    app = FastAPI(title="Python Web Terminal")
+    app.mount("/static", StaticFiles(directory=static_dir), name="static")
+
+    @app.get("/")
+    async def index(request: Request) -> Response:
+        if not _is_authenticated(request.cookies, auth_settings):
+            return _redirect("/login")
+        return FileResponse(static_dir / "index.html")
+
+    @app.get("/login")
+    async def login_page(request: Request) -> Response:
+        if auth_settings is None or _is_authenticated(request.cookies, auth_settings):
+            return _redirect("/")
+        return _render_login_page(template_path)
+
+    @app.post("/login")
+    async def login(request: Request) -> Response:
+        if auth_settings is None:
+            return _redirect("/")
+
+        form_data = _parse_form_body(await request.body())
+        username = form_data.get("username", "")
+        password = form_data.get("password", "")
+
+        from bamboo_ssh.auth.passwords import verify_password
+        from bamboo_ssh.auth.sessions import issue_session_token
+
+        if username != auth_settings.username or not verify_password(password, auth_settings.password_hash):
+            return _render_login_page(template_path, "Invalid username or password.", status.HTTP_401_UNAUTHORIZED)
+
+        response = _redirect("/")
+        response.set_cookie(
+            SESSION_COOKIE_NAME,
+            issue_session_token(auth_settings),
+            httponly=True,
+            max_age=auth_settings.session_ttl_seconds,
+            path="/",
+            samesite="lax",
+            secure=request.url.scheme == "https",
+        )
+        return response
+
+    @app.post("/logout")
+    async def logout() -> RedirectResponse:
+        response = _redirect("/login" if auth_settings is not None else "/")
+        response.delete_cookie(SESSION_COOKIE_NAME, path="/")
+        return response
+
+    @app.websocket("/ws/terminal")
+    async def terminal_socket(websocket: WebSocket) -> None:
+        if not _is_authenticated(websocket.cookies, auth_settings):
+            await websocket.close(code=status.WS_1008_POLICY_VIOLATION)
+            return
+
+        await websocket.accept()
+
+        cols = _parse_positive_int(websocket.query_params.get("cols"), 80)
+        rows = _parse_positive_int(websocket.query_params.get("rows"), 24)
+        command = websocket.query_params.get("command", "")
+
+        session = TerminalSession.start(cols=cols, rows=rows, command=command)
+        send_lock = asyncio.Lock()
+
+        async def send_json(payload: dict) -> None:
+            async with send_lock:
+                await websocket.send_json(payload)
+
+        reader_task = asyncio.create_task(stream_terminal_output(session, send_json))
+
+        try:
+            while True:
+                payload = await websocket.receive_json()
+                msg_type = payload.get("type")
+
+                if msg_type == "cmd":
+                    data = payload.get("data", "")
+                    if isinstance(data, str) and data:
+                        session.write(data)
+                elif msg_type == "resize":
+                    next_cols = _parse_positive_int(str(payload.get("cols", "")), cols)
+                    next_rows = _parse_positive_int(str(payload.get("rows", "")), rows)
+                    session.resize(next_cols, next_rows)
+                    cols, rows = next_cols, next_rows
+                elif msg_type == "heartbeat":
+                    await send_json({"type": "heartbeat", "timestamp": payload.get("timestamp")})
+                else:
+                    await send_json({"type": "error", "data": f"unsupported message type: {msg_type}"})
+        except WebSocketDisconnect:
+            pass
+        finally:
+            session.close()
+            reader_task.cancel()
+            with contextlib.suppress(asyncio.CancelledError):
+                await reader_task
+
+    return app
+
+
+STATIC_DIR = _resolve_static_dir()
+LOGIN_TEMPLATE = _resolve_login_template()
+app = create_app()
+
+
+def build_arg_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Run the Python web terminal server.")
+    parser.add_argument("--host", default="127.0.0.1", help="Host interface to bind")
+    parser.add_argument("--port", type=int, default=8765, help="Port to listen on")
+    parser.add_argument("--config", help="Path to the Bamboo SSH config file.")
+    return parser
+
+
+def main() -> None:
+    args = build_arg_parser().parse_args()
+    uvicorn.run(create_app(config_path=args.config), host=args.host, port=args.port)

bamboo_ssh/auth/__init__.py

@@ -0,0 +1,14 @@
+"""Standalone authentication helpers for Bamboo SSH."""
+
+from .config import AuthSettings, BambooSSHConfig, ServerSettings, load_config, save_config
+from .passwords import hash_password, verify_password
+
+__all__ = [
+    "AuthSettings",
+    "BambooSSHConfig",
+    "ServerSettings",
+    "hash_password",
+    "load_config",
+    "save_config",
+    "verify_password",
+]

bamboo_ssh/auth/cli.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+import argparse
+from dataclasses import replace
+import getpass
+import os
+from pathlib import Path
+import secrets
+
+from .config import AuthSettings, BambooSSHConfig, load_config, save_config
+
+
+def resolve_config_path(config_path: str | None) -> Path:
+    if config_path:
+        return Path(config_path).expanduser().resolve()
+
+    config_home = os.environ.get("XDG_CONFIG_HOME")
+    if config_home:
+        base_directory = Path(config_home)
+    else:
+        base_directory = Path.home() / ".config"
+
+    return (base_directory / "bamboo-ssh" / "config.toml").expanduser().resolve()
+
+
+def run_init(args: argparse.Namespace) -> int:
+    from .passwords import hash_password
+
+    config_path = resolve_config_path(args.config)
+    password = _prompt_password()
+    existing_config = load_config(config_path) if config_path.exists() else BambooSSHConfig()
+    existing_auth = existing_config.auth
+
+    auth_settings = AuthSettings(
+        enabled=True if existing_auth is None else existing_auth.enabled,
+        username=args.username,
+        password_hash=hash_password(password),
+        session_secret=secrets.token_urlsafe(32),
+        session_ttl_seconds=43200 if existing_auth is None else existing_auth.session_ttl_seconds,
+    )
+    save_config(config_path, BambooSSHConfig(server=existing_config.server, auth=auth_settings))
+    print(config_path)
+    return 0
+
+
+def run_set_password(args: argparse.Namespace) -> int:
+    from .passwords import hash_password
+
+    config_path = resolve_config_path(args.config)
+    if not config_path.exists():
+        raise SystemExit(f"Config file not found: {config_path}")
+
+    config = load_config(config_path)
+    if config.auth is None:
+        raise SystemExit(f"Config file does not contain an [auth] section: {config_path}")
+    if args.username is not None and args.username != config.auth.username:
+        raise SystemExit(
+            f"Configured username is {config.auth.username!r}, not {args.username!r}."
+        )
+
+    password = _prompt_password()
+    updated_auth = replace(config.auth, password_hash=hash_password(password))
+    save_config(config_path, BambooSSHConfig(server=config.server, auth=updated_auth))
+    print(config_path)
+    return 0
+
+
+def run_show_config_path(args: argparse.Namespace) -> int:
+    print(resolve_config_path(args.config))
+    return 0
+
+
+def _prompt_password() -> str:
+    try:
+        password = getpass.getpass("Password: ")
+        confirmation = getpass.getpass("Confirm password: ")
+    except (EOFError, KeyboardInterrupt) as exc:
+        raise SystemExit("Password prompt aborted.") from exc
+
+    if not password:
+        raise SystemExit("Password must not be empty.")
+    if password != confirmation:
+        raise SystemExit("Passwords did not match.")
+
+    return password

bamboo_ssh/auth/config.py

@@ -0,0 +1,205 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+import json
+import os
+from pathlib import Path
+import tempfile
+import tomllib
+from typing import Any, Mapping
+
+
+@dataclass(frozen=True, slots=True)
+class ServerSettings:
+    host: str = "127.0.0.1"
+    port: int = 8765
+
+    def __post_init__(self) -> None:
+        _require_string("server.host", self.host)
+        _require_tcp_port("server.port", self.port)
+
+    @classmethod
+    def from_mapping(cls, data: Mapping[str, Any] | None) -> "ServerSettings":
+        section = data or {}
+        host = section.get("host", "127.0.0.1")
+        port = section.get("port", 8765)
+
+        return cls(host=host, port=port)
+
+    def to_mapping(self) -> dict[str, Any]:
+        return {"host": self.host, "port": self.port}
+
+
+@dataclass(frozen=True, slots=True)
+class AuthSettings:
+    username: str
+    password_hash: str
+    session_secret: str
+    enabled: bool = True
+    session_ttl_seconds: int = 43200
+
+    def __post_init__(self) -> None:
+        _require_bool("auth.enabled", self.enabled)
+        _require_non_empty_string("auth.username", self.username)
+        _require_non_empty_string("auth.password_hash", self.password_hash)
+        _require_non_empty_string("auth.session_secret", self.session_secret)
+        _require_positive_integer("auth.session_ttl_seconds", self.session_ttl_seconds)
+
+    @classmethod
+    def from_mapping(cls, data: Mapping[str, Any]) -> "AuthSettings":
+        enabled = data.get("enabled", True)
+        username = data.get("username")
+        password_hash = data.get("password_hash")
+        session_secret = data.get("session_secret")
+        session_ttl_seconds = data.get("session_ttl_seconds", 43200)
+
+        return cls(
+            enabled=enabled,
+            username=username,
+            password_hash=password_hash,
+            session_secret=session_secret,
+            session_ttl_seconds=session_ttl_seconds,
+        )
+
+    def to_mapping(self) -> dict[str, Any]:
+        return {
+            "enabled": self.enabled,
+            "username": self.username,
+            "password_hash": self.password_hash,
+            "session_secret": self.session_secret,
+            "session_ttl_seconds": self.session_ttl_seconds,
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class BambooSSHConfig:
+    server: ServerSettings = field(default_factory=ServerSettings)
+    auth: AuthSettings | None = None
+
+
+def load_config(path: str | Path) -> BambooSSHConfig:
+    config_path = Path(path)
+    data = tomllib.loads(config_path.read_text(encoding="utf-8"))
+
+    server_data = data.get("server")
+    if server_data is not None and not isinstance(server_data, dict):
+        raise ValueError("server section must be a table")
+
+    auth_data = data.get("auth")
+    if auth_data is not None and not isinstance(auth_data, dict):
+        raise ValueError("auth section must be a table")
+
+    return BambooSSHConfig(
+        server=ServerSettings.from_mapping(server_data),
+        auth=AuthSettings.from_mapping(auth_data) if auth_data is not None else None,
+    )
+
+
+def save_config(path: str | Path, config: BambooSSHConfig) -> None:
+    config_path = Path(path)
+    config_path.parent.mkdir(parents=True, exist_ok=True)
+    serialized = _serialize_config(config)
+
+    tmp_file = tempfile.NamedTemporaryFile(
+        mode="w",
+        encoding="utf-8",
+        dir=config_path.parent,
+        prefix=f".{config_path.name}.",
+        suffix=".tmp",
+        delete=False,
+    )
+    tmp_path = Path(tmp_file.name)
+
+    try:
+        if os.name != "nt":
+            os.chmod(tmp_path, 0o600)
+
+        with tmp_file:
+            tmp_file.write(serialized)
+            tmp_file.flush()
+            os.fsync(tmp_file.fileno())
+
+        os.replace(tmp_path, config_path)
+        _fsync_parent_directory(config_path.parent)
+    except Exception:
+        if tmp_path.exists():
+            tmp_path.unlink()
+        raise
+
+
+def _serialize_config(config: BambooSSHConfig) -> str:
+    sections: list[tuple[str, dict[str, Any]]] = [("server", config.server.to_mapping())]
+    if config.auth is not None:
+        sections.append(("auth", config.auth.to_mapping()))
+
+    lines: list[str] = []
+    for index, (name, values) in enumerate(sections):
+        if index:
+            lines.append("")
+        lines.append(f"[{name}]")
+        for key, value in values.items():
+            lines.append(f"{key} = {_format_toml_value(value)}")
+
+    lines.append("")
+    return "\n".join(lines)
+
+
+def _format_toml_value(value: Any) -> str:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, int):
+        return str(value)
+    if isinstance(value, str):
+        return json.dumps(value)
+    raise TypeError(f"unsupported TOML value: {value!r}")
+
+
+def _require_bool(field_name: str, value: Any) -> bool:
+    if not isinstance(value, bool):
+        raise ValueError(f"{field_name} must be a boolean")
+    return value
+
+
+def _require_string(field_name: str, value: Any) -> str:
+    if not isinstance(value, str):
+        raise ValueError(f"{field_name} must be a string")
+    return value
+
+
+def _require_non_empty_string(field_name: str, value: Any) -> str:
+    text = _require_string(field_name, value)
+    if not text:
+        raise ValueError(f"{field_name} must not be empty")
+    return text
+
+
+def _require_integer(field_name: str, value: Any) -> int:
+    if type(value) is not int:
+        raise ValueError(f"{field_name} must be an integer")
+    return value
+
+
+def _require_positive_integer(field_name: str, value: Any) -> int:
+    integer = _require_integer(field_name, value)
+    if integer <= 0:
+        raise ValueError(f"{field_name} must be positive")
+    return integer
+
+
+def _require_tcp_port(field_name: str, value: Any) -> int:
+    port = _require_integer(field_name, value)
+    if not 1 <= port <= 65535:
+        raise ValueError(f"{field_name} must be between 1 and 65535")
+    return port
+
+
+def _fsync_parent_directory(path: Path) -> None:
+    if os.name != "posix":
+        return
+
+    flags = getattr(os, "O_RDONLY", 0) | getattr(os, "O_DIRECTORY", 0)
+    directory_fd = os.open(path, flags)
+    try:
+        os.fsync(directory_fd)
+    finally:
+        os.close(directory_fd)

bamboo_ssh/auth/passwords.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from argon2 import PasswordHasher
+from argon2.exceptions import InvalidHash, VerificationError, VerifyMismatchError
+
+
+_PASSWORD_HASHER = PasswordHasher()
+
+
+def hash_password(password: str) -> str:
+    return _PASSWORD_HASHER.hash(password)
+
+
+def verify_password(password: str, password_hash: str) -> bool:
+    try:
+        return _PASSWORD_HASHER.verify(password_hash, password)
+    except (InvalidHash, VerificationError, VerifyMismatchError):
+        return False

bamboo_ssh/auth/sessions.py

@@ -0,0 +1,114 @@
+from __future__ import annotations
+
+import base64
+import binascii
+from dataclasses import dataclass
+import hashlib
+import hmac
+import json
+import math
+import time
+
+from .config import AuthSettings
+
+
+@dataclass(frozen=True, slots=True)
+class SessionClaims:
+    username: str
+    issued_at: int
+    expires_at: int
+
+
+def issue_session_token(settings: AuthSettings, *, now: int | float | None = None) -> str:
+    issued_at = _current_timestamp(now)
+    expires_at = issued_at + settings.session_ttl_seconds
+    payload = {
+        "username": settings.username,
+        "iat": issued_at,
+        "exp": expires_at,
+    }
+    payload_bytes = json.dumps(payload, separators=(",", ":"), sort_keys=True).encode("utf-8")
+    signature = _sign_payload(payload_bytes, settings.session_secret)
+    return f"{_urlsafe_b64encode(payload_bytes)}.{_urlsafe_b64encode(signature)}"
+
+
+def validate_session_token(
+    token: str,
+    settings: AuthSettings,
+    *,
+    now: int | float | None = None,
+) -> SessionClaims | None:
+    try:
+        payload_segment, signature_segment = token.split(".", maxsplit=1)
+    except ValueError:
+        return None
+
+    try:
+        payload_bytes = _urlsafe_b64decode(payload_segment)
+        signature = _urlsafe_b64decode(signature_segment)
+    except (ValueError, binascii.Error):
+        return None
+
+    expected_signature = _sign_payload(payload_bytes, settings.session_secret)
+    if not hmac.compare_digest(signature, expected_signature):
+        return None
+
+    claims = _parse_claims(payload_bytes)
+    if claims is None:
+        return None
+
+    current_time = _current_timestamp(now)
+    if claims.username != settings.username:
+        return None
+    if claims.issued_at > current_time:
+        return None
+    if claims.expires_at <= current_time:
+        return None
+
+    return claims
+
+
+def _parse_claims(payload_bytes: bytes) -> SessionClaims | None:
+    try:
+        payload = json.loads(payload_bytes)
+    except (json.JSONDecodeError, UnicodeDecodeError):
+        return None
+
+    if not isinstance(payload, dict):
+        return None
+    if set(payload) != {"username", "iat", "exp"}:
+        return None
+
+    username = payload["username"]
+    issued_at = payload["iat"]
+    expires_at = payload["exp"]
+
+    if not isinstance(username, str) or not username:
+        return None
+    if type(issued_at) is not int or type(expires_at) is not int:
+        return None
+    if expires_at <= issued_at:
+        return None
+
+    return SessionClaims(username=username, issued_at=issued_at, expires_at=expires_at)
+
+
+def _current_timestamp(now: int | float | None) -> int:
+    if now is None:
+        return int(time.time())
+    if isinstance(now, float) and not math.isfinite(now):
+        raise ValueError("now must be a finite timestamp")
+    return int(now)
+
+
+def _sign_payload(payload_bytes: bytes, session_secret: str) -> bytes:
+    return hmac.new(session_secret.encode("utf-8"), payload_bytes, hashlib.sha256).digest()
+
+
+def _urlsafe_b64encode(data: bytes) -> str:
+    return base64.urlsafe_b64encode(data).rstrip(b"=").decode("ascii")
+
+
+def _urlsafe_b64decode(data: str) -> bytes:
+    padding = "=" * (-len(data) % 4)
+    return base64.b64decode(data + padding, altchars=b"-_", validate=True)