provide-uterm-cloudflare 0.5.0__tar.gz

provide_uterm_cloudflare-0.5.0/PKG-INFO

@@ -0,0 +1,157 @@
+Metadata-Version: 2.4
+Name: provide-uterm-cloudflare
+Version: 0.5.0
+Summary: Cloudflare Workers runtime for provide-uterm control plane
+Author: provide.io llc
+License-Expression: AGPL-3.0-or-later
+Project-URL: Homepage, https://github.com/provide-io/provide-uterm
+Project-URL: Repository, https://github.com/provide-io/provide-uterm
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Classifier: Framework :: AsyncIO
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: pyjwt>=2.9
+Requires-Dist: provide-uterm>=0.5.0
+Requires-Dist: provide-uterm-server>=0.5.0
+Provides-Extra: dev
+Requires-Dist: pytest>=9.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=1.3; extra == "dev"
+Requires-Dist: pytest-cov>=7.0; extra == "dev"
+Requires-Dist: pytest-playwright>=0.7.2; extra == "dev"
+Requires-Dist: ruff>=0.15; extra == "dev"
+Requires-Dist: mypy>=1.19; extra == "dev"
+Requires-Dist: workers-py>=0.4.0; extra == "dev"
+Requires-Dist: websockets>=16.0; extra == "dev"
+Requires-Dist: cryptography>=44.0; extra == "dev"
+Requires-Dist: provide-uterm-server[annotation,server]>=0.5.0; extra == "dev"
+Requires-Dist: starlette>=0.40; extra == "dev"
+Requires-Dist: httpx2>=2.10; extra == "dev"
+
+# provide-uterm-cloudflare
+
+Cloudflare Workers companion package for [`provide-uterm`](../../README.md). Runs the provide-uterm control plane on Cloudflare Workers using Durable Objects, with a fleet-wide session registry backed by Workers KV.
+
+## What it does
+
+Each terminal session gets its own Durable Object (`SessionRuntime`). The DO arbitrates WebSocket traffic between the runtime worker connector and browser clients, stores hijack leases and snapshots in SQLite, and publishes events to all connected browsers. A fleet-wide session list is maintained in Workers KV.
+
+## Installation
+
+```bash
+pip install provide-uterm-cloudflare
+```
+
+Or install from the monorepo with `uv`:
+
+```bash
+uv pip install -e packages/provide-uterm-cloudflare
+```
+
+### Deploy
+
+The worker entrypoint is `src/worker_entry.py` (referenced by `main` in
+`wrangler.toml`). It lives at the package `src/` root on purpose: wrangler bundles
+the directory of the `main` file, so anchoring it there preserves the full
+`provide/uterm/cloudflare/` tree in the bundle and the worker's qualified imports
+resolve as-is.
+
+The Pyodide runtime also needs a flat vendor tree of the pure-Python deps the
+worker imports (`structlog`, `provide.telemetry`, and the `provide.uterm.*`
+modules). `pywrangler sync` produces a layout the worker can't import, so build it
+with the helper script, then deploy with `wrangler` directly (not `pywrangler
+deploy`, which would re-sync and overwrite the tree):
+
+```bash
+bash .ci/vendor_cf_worker.sh                          # build python_modules/
+cd packages/provide-uterm-cloudflare
+CLOUDFLARE_API_TOKEN=… npx wrangler deploy            # publish
+
+# Required secrets (AUTH_MODE is jwt-only; the worker 500s without these):
+npx wrangler secret put WORKER_BEARER_TOKEN           # >=32 high-entropy chars
+npx wrangler secret put WEBHOOK_SECRET_KEY            # base64 AES-256 key
+```
+
+## Key features
+
+- **Durable Object per session** — `SessionRuntime` DO holds all session state (leases, snapshots, event sequence) in SQLite.
+- **Fleet-wide session registry** — `SESSION_REGISTRY` Workers KV namespace; `GET /api/sessions` returns all active sessions across the fleet.
+- **CF Access JWT auth** — validates Cloudflare Access JWTs via JWKS; `JWT_DEFAULT_ROLE` env var assigns a role when the JWT carries no role claim.
+- **Hijack REST API** — `POST /hijack/{id}/acquire`, `POST /hijack/{id}/send`, `POST /hijack/{id}/release`, `GET /hijack/{id}/snapshot`.
+- **WebSocket proxy** — three WS endpoints per session:
+  - `/ws/worker/{worker_id}/term` — runtime worker protocol (JSON frames)
+  - `/ws/browser/{worker_id}/term` — browser/operator protocol (JSON frames)
+  - `/ws/raw/{worker_id}/term` — raw stream mode for `uterm listen` telnet/SSH gateways
+- **Hibernation-safe** — uses CF WebSocket Hibernation API; state survives DO sleep/wake cycles.
+- **WS session resumption** — browser reconnects reclaim their role and hijack ownership via one-time tokens stored in DO SQLite; see `docs/cf-do-architecture.md`.
+- **Quick-connect** — `POST /api/connect` creates sessions in KV; SPA serves the connect form at `/app/connect`. Supports shell, websocket, and ushell connector types.
+
+## Auth modes
+
+Set `AUTH_MODE` in `wrangler.toml` or `.dev.vars`. `jwt` is the **only**
+supported value — the worker is always internet-facing, so any other mode
+(`dev`/`none` are removed) raises a `ValueError` at config load.
+
+| Mode | Behavior |
+|---|---|
+| `jwt` | Validates CF Access JWT; role from claim or `JWT_DEFAULT_ROLE`. CF Access service-token JWTs (with a `common_name` claim and no human `email` claim) are accepted, but are only granted the admin role when `JWT_SERVICE_TOKEN_ADMIN=1` is set (defaults off); otherwise they get their roles from the normal claim/scope/default-role path. |
+
+`WORKER_BEARER_TOKEN` is also required and must clear a 32-character /
+non-placeholder entropy floor.
+
+## Current gaps
+
+- The quick-connect form creates sessions in KV but the CF worker cannot run
+  shell/SSH/telnet connectors itself — a worker process must bridge in via WS.
+- The hijack REST surface is intended to match the FastAPI contract, but there
+  are still backend-parity gaps; treat `docs/protocol-matrix.md` as the target
+  contract, not a guarantee that every edge case is identical today.
+
+## Commands
+
+```bash
+uv run pywrangler dev        # local dev server (sync deps + wrangler dev)
+uv run pywrangler deploy     # deploy to Cloudflare
+uterm-cf build               # build only
+uterm-cf deploy --env production
+```
+
+### Docker alternative
+
+```bash
+# Build and run from repo root
+docker build -f docker/Dockerfile.cf -t provide-uterm-cf .
+docker run --rm -p 27788:27788 provide-uterm-cf
+
+# JWT auth test
+docker run --rm -p 27788:27788 \
+  -e AUTH_MODE=jwt \
+  -e JWT_JWKS_URL=https://<team>.cloudflareaccess.com/cdn-cgi/access/certs \
+  -e JWT_ISSUER=https://<team>.cloudflareaccess.com \
+  -e JWT_AUDIENCE=<aud-tag> \
+  provide-uterm-cf
+```
+
+## Tests
+
+Unit tests (no network required):
+
+```bash
+uv run pytest tests/ -v
+```
+
+E2E tests against a local `wrangler dev` instance or the live worker:
+
+```bash
+E2E=1 uv run pytest -m e2e -v
+REAL_CF=1 REAL_CF_URL=https://provide-uterm-cloudflare.neurotic.workers.dev uv run pytest -m e2e -v
+```
+
+## Related
+
+- Main package: [`provide-uterm`](../../README.md)
+- Terraform for KV provisioning: `terraform/`

provide_uterm_cloudflare-0.5.0/README.md

@@ -0,0 +1,123 @@
+# provide-uterm-cloudflare
+
+Cloudflare Workers companion package for [`provide-uterm`](../../README.md). Runs the provide-uterm control plane on Cloudflare Workers using Durable Objects, with a fleet-wide session registry backed by Workers KV.
+
+## What it does
+
+Each terminal session gets its own Durable Object (`SessionRuntime`). The DO arbitrates WebSocket traffic between the runtime worker connector and browser clients, stores hijack leases and snapshots in SQLite, and publishes events to all connected browsers. A fleet-wide session list is maintained in Workers KV.
+
+## Installation
+
+```bash
+pip install provide-uterm-cloudflare
+```
+
+Or install from the monorepo with `uv`:
+
+```bash
+uv pip install -e packages/provide-uterm-cloudflare
+```
+
+### Deploy
+
+The worker entrypoint is `src/worker_entry.py` (referenced by `main` in
+`wrangler.toml`). It lives at the package `src/` root on purpose: wrangler bundles
+the directory of the `main` file, so anchoring it there preserves the full
+`provide/uterm/cloudflare/` tree in the bundle and the worker's qualified imports
+resolve as-is.
+
+The Pyodide runtime also needs a flat vendor tree of the pure-Python deps the
+worker imports (`structlog`, `provide.telemetry`, and the `provide.uterm.*`
+modules). `pywrangler sync` produces a layout the worker can't import, so build it
+with the helper script, then deploy with `wrangler` directly (not `pywrangler
+deploy`, which would re-sync and overwrite the tree):
+
+```bash
+bash .ci/vendor_cf_worker.sh                          # build python_modules/
+cd packages/provide-uterm-cloudflare
+CLOUDFLARE_API_TOKEN=… npx wrangler deploy            # publish
+
+# Required secrets (AUTH_MODE is jwt-only; the worker 500s without these):
+npx wrangler secret put WORKER_BEARER_TOKEN           # >=32 high-entropy chars
+npx wrangler secret put WEBHOOK_SECRET_KEY            # base64 AES-256 key
+```
+
+## Key features
+
+- **Durable Object per session** — `SessionRuntime` DO holds all session state (leases, snapshots, event sequence) in SQLite.
+- **Fleet-wide session registry** — `SESSION_REGISTRY` Workers KV namespace; `GET /api/sessions` returns all active sessions across the fleet.
+- **CF Access JWT auth** — validates Cloudflare Access JWTs via JWKS; `JWT_DEFAULT_ROLE` env var assigns a role when the JWT carries no role claim.
+- **Hijack REST API** — `POST /hijack/{id}/acquire`, `POST /hijack/{id}/send`, `POST /hijack/{id}/release`, `GET /hijack/{id}/snapshot`.
+- **WebSocket proxy** — three WS endpoints per session:
+  - `/ws/worker/{worker_id}/term` — runtime worker protocol (JSON frames)
+  - `/ws/browser/{worker_id}/term` — browser/operator protocol (JSON frames)
+  - `/ws/raw/{worker_id}/term` — raw stream mode for `uterm listen` telnet/SSH gateways
+- **Hibernation-safe** — uses CF WebSocket Hibernation API; state survives DO sleep/wake cycles.
+- **WS session resumption** — browser reconnects reclaim their role and hijack ownership via one-time tokens stored in DO SQLite; see `docs/cf-do-architecture.md`.
+- **Quick-connect** — `POST /api/connect` creates sessions in KV; SPA serves the connect form at `/app/connect`. Supports shell, websocket, and ushell connector types.
+
+## Auth modes
+
+Set `AUTH_MODE` in `wrangler.toml` or `.dev.vars`. `jwt` is the **only**
+supported value — the worker is always internet-facing, so any other mode
+(`dev`/`none` are removed) raises a `ValueError` at config load.
+
+| Mode | Behavior |
+|---|---|
+| `jwt` | Validates CF Access JWT; role from claim or `JWT_DEFAULT_ROLE`. CF Access service-token JWTs (with a `common_name` claim and no human `email` claim) are accepted, but are only granted the admin role when `JWT_SERVICE_TOKEN_ADMIN=1` is set (defaults off); otherwise they get their roles from the normal claim/scope/default-role path. |
+
+`WORKER_BEARER_TOKEN` is also required and must clear a 32-character /
+non-placeholder entropy floor.
+
+## Current gaps
+
+- The quick-connect form creates sessions in KV but the CF worker cannot run
+  shell/SSH/telnet connectors itself — a worker process must bridge in via WS.
+- The hijack REST surface is intended to match the FastAPI contract, but there
+  are still backend-parity gaps; treat `docs/protocol-matrix.md` as the target
+  contract, not a guarantee that every edge case is identical today.
+
+## Commands
+
+```bash
+uv run pywrangler dev        # local dev server (sync deps + wrangler dev)
+uv run pywrangler deploy     # deploy to Cloudflare
+uterm-cf build               # build only
+uterm-cf deploy --env production
+```
+
+### Docker alternative
+
+```bash
+# Build and run from repo root
+docker build -f docker/Dockerfile.cf -t provide-uterm-cf .
+docker run --rm -p 27788:27788 provide-uterm-cf
+
+# JWT auth test
+docker run --rm -p 27788:27788 \
+  -e AUTH_MODE=jwt \
+  -e JWT_JWKS_URL=https://<team>.cloudflareaccess.com/cdn-cgi/access/certs \
+  -e JWT_ISSUER=https://<team>.cloudflareaccess.com \
+  -e JWT_AUDIENCE=<aud-tag> \
+  provide-uterm-cf
+```
+
+## Tests
+
+Unit tests (no network required):
+
+```bash
+uv run pytest tests/ -v
+```
+
+E2E tests against a local `wrangler dev` instance or the live worker:
+
+```bash
+E2E=1 uv run pytest -m e2e -v
+REAL_CF=1 REAL_CF_URL=https://provide-uterm-cloudflare.neurotic.workers.dev uv run pytest -m e2e -v
+```
+
+## Related
+
+- Main package: [`provide-uterm`](../../README.md)
+- Terraform for KV provisioning: `terraform/`

provide_uterm_cloudflare-0.5.0/VERSION

@@ -0,0 +1 @@
+0.5.0

provide_uterm_cloudflare-0.5.0/pyproject.toml

@@ -0,0 +1,110 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "provide-uterm-cloudflare"
+dynamic = ["version"]
+description = "Cloudflare Workers runtime for provide-uterm control plane"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "AGPL-3.0-or-later"
+authors = [
+  {name = "provide.io llc"},
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Internet :: WWW/HTTP :: HTTP Servers",
+  "Framework :: AsyncIO",
+]
+dependencies = [
+  "pyjwt>=2.9",
+  "provide-uterm>=0.5.0",
+  "provide-uterm-server>=0.5.0",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=9.0",
+  "pytest-asyncio>=1.3",
+  "pytest-cov>=7.0",
+  "pytest-playwright>=0.7.2",
+  "ruff>=0.15",
+  "mypy>=1.19",
+  "workers-py>=0.4.0",
+  "websockets>=16.0",
+  "cryptography>=44.0",
+  # The cross-compat tests boot a real FastAPI server and compare it against
+  # the Worker, and that server refuses to build without annotation support.
+  # The Worker runtime itself does not need it, so it belongs here rather than
+  # in this package's runtime dependencies.
+  #
+  # [server] as well as [annotation]: fastapi/uvicorn live under provide-uterm-
+  # server's server/cli/tunnel extras, not [annotation], so app/factory_impl.py
+  # raised ModuleNotFoundError: No module named 'fastapi' the moment the
+  # isolated env stopped receiving it transitively — the same failure mode the
+  # starlette note below describes.
+  "provide-uterm-server[annotation,server]>=0.5.0",
+  # tests/conftest.py imports starlette.testclient directly, and TestClient
+  # needs httpx2 at import time. Neither is reachable through the line above:
+  # provide-uterm-server declares fastapi under its server/cli/tunnel extras,
+  # not under [annotation]. Both arrived transitively until 2026-08-06, when
+  # the same commit that passed on 08-05 began failing CI's isolated
+  # `uv run --package provide-uterm-cloudflare --extra dev` env with
+  # ModuleNotFoundError: No module named 'starlette'. A test's direct import
+  # belongs in its own package's dev extra rather than inherited by luck.
+  "starlette>=0.40",
+  "httpx2>=2.10",
+]
+
+[project.urls]
+Homepage = "https://github.com/provide-io/provide-uterm"
+Repository = "https://github.com/provide-io/provide-uterm"
+
+[project.scripts]
+uterm-cf = "provide.uterm.cloudflare.cli:main"
+
+[tool.setuptools.dynamic]
+version = {file = "VERSION"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+namespaces = true
+
+[tool.setuptools.package-data]
+"provide.uterm.cloudflare" = ["py.typed"]
+
+[tool.pytest.ini_options]
+consider_namespace_packages = true
+asyncio_mode = "auto"
+pythonpath = ["src"]
+markers = [
+    "e2e: end-to-end tests against a live pywrangler dev server (skipped by default; use -m e2e or E2E=1)",
+    "real_cf: requires real Cloudflare deployment with live KV + full WS support (skipped unless REAL_CF=1)",
+    "slow: slow tests (>10s); skipped unless SLOW=1 or REAL_CF=1",
+    "playwright: Playwright browser UI tests",
+]
+addopts = [
+    "--cov=provide.uterm.cloudflare",
+    "--cov-branch",
+    "--cov-report=term-missing",
+    "--cov-fail-under=100",
+]
+
+[tool.coverage.run]
+source = ["provide.uterm.cloudflare"]
+branch = true
+
+[tool.coverage.report]
+fail_under = 100
+show_missing = true
+skip_covered = false
+[tool.mutmut]
+source_paths = ["src/"]
+also_copy = ["wrangler.toml"]
+pytest_add_cli_args = ["-o", "addopts=", "--no-header", "-q"]
+pytest_add_cli_args_test_selection = ["tests/"]

provide_uterm_cloudflare-0.5.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

provide_uterm_cloudflare-0.5.0/src/provide/uterm/cloudflare/__init__.py

@@ -0,0 +1,10 @@
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("provide-uterm-cloudflare")
+except PackageNotFoundError:  # pragma: no cover
+    __version__ = "0.0.0"  # pragma: no cover
+
+from .config import CloudflareConfig
+
+__all__ = ["CloudflareConfig", "__version__"]

provide_uterm_cloudflare-0.5.0/src/provide/uterm/cloudflare/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())  # pragma: no cover

provide_uterm_cloudflare-0.5.0/src/provide/uterm/cloudflare/api/__init__.py

@@ -0,0 +1,10 @@
+__all__ = ["route_http"]
+
+
+def __getattr__(name: str) -> object:  # pragma: no cover
+    """Lazy import to avoid module loading issues during Pyodide validation."""
+    if name == "route_http":
+        from .http_routes import route_http
+
+        return route_http
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

provide_uterm_cloudflare-0.5.0/src/provide/uterm/cloudflare/api/_pam.py

@@ -0,0 +1,99 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 provide.io llc. All rights reserved.
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""
+POST /api/pam-events — accept PAM session notifications from a local bridge.
+
+The pam_uterm.so module writes to a Unix socket on the SSH host.  A local
+bridge (e.g. scripts/deckmux_demo_server.py or a dedicated forwarder) reads
+those events and POSTs them here so the operator dashboard can reflect
+live SSH sessions.
+
+Wire format (same JSON as pam_uterm.so):
+  {"event":"open",  "username":"alice","tty":"/dev/pts/3","pid":12345,"mode":"notify"}
+  {"event":"close", "username":"alice","tty":"/dev/pts/3","pid":12345}
+
+On "open" (notify mode), a read-only observer session entry is written to KV.
+On "close", the session is removed from KV.
+
+Capture mode (LD_PRELOAD) is a local-server-only capability — the CF edge
+cannot receive a Unix socket connection from the SSH host, so capture events
+are accepted but treated identically to notify events (session visible in
+dashboard but no live I/O).
+"""
+
+from __future__ import annotations
+
+import re
+import time
+from typing import TYPE_CHECKING, Any
+
+_TTY_SLUG_RE = re.compile(r"[^a-zA-Z0-9]+")
+
+
+def _tty_slug(tty: str) -> str:
+    """/dev/pts/3 → last component slug."""
+    basename = tty.split("/")[-1] if "/" in tty else tty
+    return _TTY_SLUG_RE.sub("-", basename).strip("-") or "tty"
+
+
+async def handle_pam_event(request: object, env: object) -> object:
+    """Handle POST /api/pam-events."""
+    if TYPE_CHECKING:
+        from provide.uterm.cloudflare.cf_types import json_response
+    else:
+        try:
+            from provide.uterm.cloudflare.cf_types import json_response
+        except ImportError:  # pragma: no cover
+            from cf_types import json_response  # type: ignore[import-not-found,no-redef]
+
+    method = str(getattr(request, "method", "GET")).upper()
+    if method != "POST":
+        return json_response({"error": "method_not_allowed"}, status=405)
+
+    try:
+        raw = await request.json()  # type: ignore[attr-defined]  # ty:ignore[unresolved-attribute]
+        body: dict[str, Any] = raw.to_py() if hasattr(raw, "to_py") else raw
+    except Exception:
+        return json_response({"error": "invalid_json"}, status=400)
+
+    event = str(body.get("event") or "")
+    if event not in ("open", "close"):
+        return json_response({"error": "unknown_event", "event": event}, status=422)
+
+    username = str(body.get("username") or "")
+    if not username:
+        return json_response({"error": "missing_username"}, status=422)
+
+    tty = str(body.get("tty") or "")
+    slug = _tty_slug(tty)
+    session_id = f"pam-{username}-{slug}"
+
+    kv = getattr(env, "SESSION_REGISTRY", None)
+
+    if event == "open":
+        entry: dict[str, Any] = {
+            "session_id": session_id,
+            "display_name": f"{username} ({tty or 'pam'})",
+            "created_at": time.time(),
+            "connector_type": "shell",
+            "lifecycle_state": "running",
+            "input_mode": "open",
+            "connected": True,
+            "auto_start": False,
+            "tags": ["pam", str(body.get("mode") or "notify"), username],
+            "recording_enabled": False,
+            "recording_available": False,
+            "owner": username,
+            "visibility": "operator",
+            "last_error": None,
+        }
+        if kv is not None:
+            import json as _json
+
+            await kv.put(f"session:{session_id}", _json.dumps({**entry, "hijacked": False}))
+        return json_response({"ok": True, "session_id": session_id, "action": "created"})
+
+    # event == "close"
+    if kv is not None:
+        await kv.delete(f"session:{session_id}")
+    return json_response({"ok": True, "session_id": session_id, "action": "deleted"})