bamboo-ssh 0.1.0__tar.gz

bamboo_ssh-0.1.0/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: bamboo-ssh
+Version: 0.1.0
+Summary: Reusable terminal session core with optional web terminal extras.
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Provides-Extra: web
+Requires-Dist: fastapi<1,>=0.136; extra == "web"
+Requires-Dist: uvicorn<1,>=0.44; extra == "web"
+Requires-Dist: websockets<17,>=13; extra == "web"
+Provides-Extra: full
+Requires-Dist: fastapi<1,>=0.136; extra == "full"
+Requires-Dist: uvicorn<1,>=0.44; extra == "full"
+Requires-Dist: websockets<17,>=13; extra == "full"
+Requires-Dist: argon2-cffi<24.0,>=23.1; extra == "full"
+Provides-Extra: dev
+Requires-Dist: pytest==9.0.3; extra == "dev"
+Requires-Dist: httpx==0.28.1; extra == "dev"
+
+# Bamboo SSH
+
+This project currently provides a reusable PTY-backed shell session core and an optional FastAPI web terminal adapter. It is designed for local or otherwise trusted environments.
+
+It is not an SSH transport layer yet. The current implementation launches a real shell on the host where the service runs.
+
+Requires Python 3.12 or newer.
+
+## Full Documentation
+
+See the documentation set in [`docs/`](./docs/README.md):
+
+- [Project Overview](./docs/project-overview.md)
+- [Architecture](./docs/architecture.md)
+- [Setup and Run](./docs/setup-and-run.md)
+- [Docker Support](./docs/docker.md)
+- [API and WebSocket Protocol](./docs/api-reference.md)
+- [File Reference](./docs/file-reference.md)
+- [Testing](./docs/testing.md)
+- [Security and Limitations](./docs/security-and-limitations.md)
+
+## Install Profiles
+
+The package supports three install modes:
+
+- `pip install bamboo-ssh` for the reusable core package
+- `pip install "bamboo-ssh[web]"` for the FastAPI web terminal adapter
+- `pip install "bamboo-ssh[full]"` for the web adapter plus built-in config-file auth helpers
+
+From this checkout, install the matching local package profile with:
+
+```bash
+python -m pip install .
+python -m pip install ".[web]"
+python -m pip install ".[full]"
+```
+
+Use `requirements.txt` for contributor setup. It installs the editable project with the `full` and `dev` extras.
+
+## Make Targets
+
+For local contributor and release helpers:
+
+- `make install` creates `.venv` and installs `requirements.txt`
+- `make clean` removes local build and test artifacts
+- `make build` creates a source distribution and wheel in `dist/`
+- `make deploy` builds and uploads `dist/*` to PyPI with `twine`
+
+For `make deploy`, authenticate with PyPI first, typically with a token in `TWINE_PASSWORD`.
+
+## Quick Start
+
+```bash
+python3 -m venv .venv
+. .venv/bin/activate
+python -m pip install ".[full]"
+bamboo-ssh auth init
+bamboo-ssh serve --host 127.0.0.1 --port 8765
+```
+
+Open `http://127.0.0.1:8765/`.
+
+If the default config file exists, `bamboo-ssh serve` loads it automatically. Use `--config /path/to/config.toml` to point at a different file.
+
+## Embedded Usage
+
+Other Python projects can import the package without using the built-in web auth flow.
+
+Use the core session API directly:
+
+```python
+from bamboo_ssh.core.session import TerminalSession
+
+session = TerminalSession.start(cols=80, rows=24)
+session.write("printf 'hello\\n'\n")
+session.close()
+```
+
+Or mount the web adapter inside another backend:
+
+```python
+from bamboo_ssh.adapters.fastapi_app import create_app
+
+terminal_app = create_app()
+protected_terminal_app = create_app(config_path="/etc/bamboo-ssh/config.toml")
+```
+
+## Built-In Auth
+
+The standalone auth mode is intentionally simple:
+
+- one admin username
+- password hash stored in a TOML config file
+- signed session cookie for the browser
+- no database
+
+Manage it with:
+
+```bash
+bamboo-ssh auth init
+bamboo-ssh auth set-password
+bamboo-ssh auth show-config-path
+```
+
+After login, the terminal page loads normally. `POST /logout` clears the session cookie and returns the browser to the login page.
+
+## Shell Startup Tuning
+
+Web terminal shell sessions export `WEB_TERMINAL=1`.
+
+If your shell startup files do expensive optional work such as loading large completion bundles, language managers, or interactive prompts, you can use that variable to skip them for browser terminal sessions while keeping a full login shell for normal terminal use.
+
+## Docker Quick Start
+
+```bash
+cp docker/.env.example docker/.env
+docker compose -f docker/compose.yml --env-file docker/.env up --build
+```
+
+This runs the terminal inside a Python 3.12 container. The browser terminal connects to the shell inside the container, not the host machine shell.

bamboo_ssh-0.1.0/README.md

@@ -0,0 +1,120 @@
+# Bamboo SSH
+
+This project currently provides a reusable PTY-backed shell session core and an optional FastAPI web terminal adapter. It is designed for local or otherwise trusted environments.
+
+It is not an SSH transport layer yet. The current implementation launches a real shell on the host where the service runs.
+
+Requires Python 3.12 or newer.
+
+## Full Documentation
+
+See the documentation set in [`docs/`](./docs/README.md):
+
+- [Project Overview](./docs/project-overview.md)
+- [Architecture](./docs/architecture.md)
+- [Setup and Run](./docs/setup-and-run.md)
+- [Docker Support](./docs/docker.md)
+- [API and WebSocket Protocol](./docs/api-reference.md)
+- [File Reference](./docs/file-reference.md)
+- [Testing](./docs/testing.md)
+- [Security and Limitations](./docs/security-and-limitations.md)
+
+## Install Profiles
+
+The package supports three install modes:
+
+- `pip install bamboo-ssh` for the reusable core package
+- `pip install "bamboo-ssh[web]"` for the FastAPI web terminal adapter
+- `pip install "bamboo-ssh[full]"` for the web adapter plus built-in config-file auth helpers
+
+From this checkout, install the matching local package profile with:
+
+```bash
+python -m pip install .
+python -m pip install ".[web]"
+python -m pip install ".[full]"
+```
+
+Use `requirements.txt` for contributor setup. It installs the editable project with the `full` and `dev` extras.
+
+## Make Targets
+
+For local contributor and release helpers:
+
+- `make install` creates `.venv` and installs `requirements.txt`
+- `make clean` removes local build and test artifacts
+- `make build` creates a source distribution and wheel in `dist/`
+- `make deploy` builds and uploads `dist/*` to PyPI with `twine`
+
+For `make deploy`, authenticate with PyPI first, typically with a token in `TWINE_PASSWORD`.
+
+## Quick Start
+
+```bash
+python3 -m venv .venv
+. .venv/bin/activate
+python -m pip install ".[full]"
+bamboo-ssh auth init
+bamboo-ssh serve --host 127.0.0.1 --port 8765
+```
+
+Open `http://127.0.0.1:8765/`.
+
+If the default config file exists, `bamboo-ssh serve` loads it automatically. Use `--config /path/to/config.toml` to point at a different file.
+
+## Embedded Usage
+
+Other Python projects can import the package without using the built-in web auth flow.
+
+Use the core session API directly:
+
+```python
+from bamboo_ssh.core.session import TerminalSession
+
+session = TerminalSession.start(cols=80, rows=24)
+session.write("printf 'hello\\n'\n")
+session.close()
+```
+
+Or mount the web adapter inside another backend:
+
+```python
+from bamboo_ssh.adapters.fastapi_app import create_app
+
+terminal_app = create_app()
+protected_terminal_app = create_app(config_path="/etc/bamboo-ssh/config.toml")
+```
+
+## Built-In Auth
+
+The standalone auth mode is intentionally simple:
+
+- one admin username
+- password hash stored in a TOML config file
+- signed session cookie for the browser
+- no database
+
+Manage it with:
+
+```bash
+bamboo-ssh auth init
+bamboo-ssh auth set-password
+bamboo-ssh auth show-config-path
+```
+
+After login, the terminal page loads normally. `POST /logout` clears the session cookie and returns the browser to the login page.
+
+## Shell Startup Tuning
+
+Web terminal shell sessions export `WEB_TERMINAL=1`.
+
+If your shell startup files do expensive optional work such as loading large completion bundles, language managers, or interactive prompts, you can use that variable to skip them for browser terminal sessions while keeping a full login shell for normal terminal use.
+
+## Docker Quick Start
+
+```bash
+cp docker/.env.example docker/.env
+docker compose -f docker/compose.yml --env-file docker/.env up --build
+```
+
+This runs the terminal inside a Python 3.12 container. The browser terminal connects to the shell inside the container, not the host machine shell.

bamboo_ssh-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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