runspec-room 0.3.0__tar.gz

runspec_room-0.3.0/.gitignore

@@ -0,0 +1,6 @@
+*.db
+dist/
+build/
+*.egg-info/
+__pycache__/
+.pytest_cache/

runspec_room-0.3.0/CHANGELOG.md

@@ -0,0 +1,76 @@
+# Changelog
+
+All notable changes to `runspec-room` are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/), and this project adheres to
+semantic versioning.
+
+## [0.3.0]
+
+**S3: OIDC login + sessions + TLS.** The browser door is now authenticated.
+
+### Added
+- `console_room.web.auth` — OIDC config (`auth_from_env`, env-driven, secrets
+  never on the CLI) and pure identity helpers (`identity_from_userinfo`,
+  `session_user`, `AuthConfig.redirect_uri` / `.secure_cookies`).
+- OIDC login on the browser door (authlib): `/login` → your IdP, `/auth/callback`
+  → a signed-cookie session, `/logout`. The app shell (`/`) and the WebSocket are
+  gated on the session identity, so the browser no longer declares who it is —
+  and a spoofed `?user=` is ignored. A `/me` endpoint reports the logged-in user;
+  the frontend locks the name field and shows a sign-out link in auth mode.
+- TLS: `--tls-cert` / `--tls-key` (or `CONSOLE_ROOM_TLS_*`) make uvicorn serve
+  https/wss directly. uvicorn runs proxy-header-aware (`X-Forwarded-Proto`), so it
+  also works behind a TLS-terminating reverse proxy; session cookies are marked
+  `Secure` when the public URL is https.
+
+### Changed
+- Adds runtime dependencies `authlib` + `itsdangerous`. **Dev mode unchanged:**
+  with no `CONSOLE_ROOM_OIDC_*` config the browser door runs unauthenticated
+  (query-param identity), logging a warning — handy for local use, not for public
+  exposure. `--ndjson-only` still needs none of the web deps.
+- Static assets moved to `/static/`; the app shell is served from a gated `/`
+  route (was a root static mount).
+
+## [0.2.0]
+
+**S2: the browser front door.**
+
+### Added
+- `console_room.web.connection.BrowserConnection` — the browser counterpart of the
+  NDJSON console connection, satisfying the hub's `Participant` protocol with
+  `wants_backscroll = True` (people see recent history; consoles never do). Speaks
+  to a tiny `WebSocketLike` seam, so it's unit-tested with a fake socket.
+- `console_room.web.app.create_app` — the Starlette app: a `/ws` WebSocket door, a
+  `/healthz` check, and the static frontend served at `/`. When given an
+  `ndjson_addr`, its lifespan also runs the console NDJSON door on the same loop,
+  so one process serves both front doors.
+- A vanilla, no-build static frontend (`web/frontend/`): transcript + presence +
+  composer, with auto-reconnect. Browser identity comes from a `?user=&room=` join
+  form (a dev stand-in, replaced by the OIDC session in S3).
+- `server.py` now runs the **web server** by default (uvicorn + the app);
+  `--ndjson-only` keeps the stdlib console-door path for a minimal deploy.
+
+### Changed
+- Adds runtime dependencies `starlette` + `uvicorn[standard]` (the package is now a
+  web server). The `--ndjson-only` path imports neither — they're lazy — so a
+  console-only deploy can still run without them.
+
+## [0.1.0]
+
+Initial release — **S1: the console front door**.
+
+### Added
+- `console_room.hub.Hub` — the transport-agnostic room broker: join/leave with
+  live presence, message stamping (server-assigned `id`/`ts`/`sender`), persist,
+  and broadcast (sender included, so all views converge). Browser-only backscroll
+  asymmetry baked in via the participant's `wants_backscroll`.
+- `console_room.store.TranscriptStore` — durable SQLite transcript (`append` /
+  `recent`), stdlib-only, idempotent on message id.
+- `console_room.ndjson_server` — the NDJSON listener on localhost (the console
+  door): a `hello` handshake binds identity to the connection; `message` /
+  `presence` frames drive the hub; blank/malformed lines are skipped.
+- `console_room.models` — the wire schema: `Message`, frame builders, and
+  `hello` parsing/validation.
+- `console-room` CLI entry point (`--host` / `--port` / `--db`, env-overridable).
+
+Stdlib-only at this stage (no runtime dependencies). The browser door (S2) and
+OIDC + TLS (S3) follow. See `docs/design/console-room-server.md`.

runspec_room-0.3.0/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.4
+Name: runspec-room
+Version: 0.3.0
+Summary: The runspec console chat-room server — a dumb message pipe with presence: console SSH-tunnel door + OIDC-authenticated browser web door
+Author: runspec
+License-Expression: MIT
+Keywords: chat,console,room,runspec,ssh
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Communications :: Chat
+Requires-Python: >=3.10
+Requires-Dist: authlib>=1.3
+Requires-Dist: itsdangerous>=2.1
+Requires-Dist: starlette>=0.37
+Requires-Dist: uvicorn[standard]>=0.27
+Provides-Extra: dev
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# runspec-room
+
+The server behind the runspec-console **chat room** — a *dumb message pipe with
+presence*. It holds, per room, the connected participants, their live presence,
+and a durable transcript, and it does three things: accept connections, stamp +
+persist each inbound message, and broadcast every message / presence change to
+everyone else in the room. **All the intelligence stays in the consoles** — the
+server never runs anything.
+
+See `docs/design/console-room-server.md` for the full design and decisions.
+
+## Status — complete server (S1–S3)
+
+Two front doors, one process:
+
+- **Console door** — an NDJSON listener on **localhost**, which each
+  runspec-console reaches by opening a `direct-tcpip` channel over its existing
+  pooled SSH connection. A console's right to be in the room *is* its SSH access —
+  no new exposed port, no second credential.
+- **Browser door** — a WebSocket endpoint (`/ws`) plus a small vanilla static
+  frontend (transcript / composer / presence) with recent-history backscroll for
+  people. Authenticated via **OIDC** (no passwords stored); identity comes from
+  the signed-cookie session. TLS is self-terminated or left to a reverse proxy.
+
+## Run it
+
+```bash
+pip install -e .
+
+# Full server (browser + console doors):
+console-room --port 8080 --ndjson-port 8765 --db ./console_room.db
+
+# Console door only (no web deps needed):
+console-room --ndjson-only --ndjson-port 8765 --db ./console_room.db
+```
+
+The console door stays on localhost — consoles tunnel in. Open the browser door
+at the web port.
+
+### Enabling login (OIDC) + TLS
+
+Without OIDC config the browser door runs in **dev mode** — unauthenticated,
+identity from a `?user=` join form (a warning is logged; don't expose it). Set the
+OIDC env vars to require single sign-on:
+
+```bash
+export CONSOLE_ROOM_OIDC_ISSUER="https://login.microsoftonline.com/<tenant>/v2.0"
+# or CONSOLE_ROOM_OIDC_METADATA_URL=<discovery doc URL>
+export CONSOLE_ROOM_OIDC_CLIENT_ID="…"
+export CONSOLE_ROOM_OIDC_CLIENT_SECRET="…"
+export CONSOLE_ROOM_SESSION_SECRET="$(openssl rand -hex 32)"
+export CONSOLE_ROOM_PUBLIC_URL="https://room.example.com"   # for the redirect_uri
+# register  $CONSOLE_ROOM_PUBLIC_URL/auth/callback  as the redirect URI at your IdP
+
+console-room --host 0.0.0.0 --port 443 \
+  --tls-cert /etc/ssl/room.crt --tls-key /etc/ssl/room.key
+```
+
+uvicorn is proxy-header-aware (`X-Forwarded-Proto`), so you can drop `--tls-*` and
+let nginx/Caddy terminate TLS instead.
+
+## Wire protocol (NDJSON, one JSON object per line)
+
+Console → server:
+
+```json
+{"type":"hello",   "room":"ops", "user":"alice@web01"}
+{"type":"message", "room":"ops", "text":"rolling out"}
+{"type":"presence","room":"ops", "status":"available"}
+```
+
+The **first** frame must be `hello` — that's how a console declares its identity
+(the server can't see the OS user over the tunnel). The name is bound to the
+connection and stamped onto every later message; per-frame `user` fields are
+ignored, so a frame can't spoof a different sender.
+
+Server → client:
+
+```json
+{"type":"message", "room":"ops", "sender":"alice@web01", "text":"rolling out", "id":"…", "ts":0.0}
+{"type":"presence","room":"ops", "user":"alice@web01", "status":"available"}
+```
+
+The server echoes a sender's own message back (with the assigned `id`/`ts`); a
+console drops its own echo so it never re-reacts to its own messages.
+
+Browsers speak the **same `message` / `presence` schema** over the WebSocket — but
+their identity comes from the **connection** (the `?user=&room=` query in dev, the
+OIDC session in S3), so they send no `hello` frame.
+
+## Develop
+
+```bash
+pip install -e ".[dev]"
+pytest
+```

runspec_room-0.3.0/README.md

@@ -0,0 +1,96 @@
+# runspec-room
+
+The server behind the runspec-console **chat room** — a *dumb message pipe with
+presence*. It holds, per room, the connected participants, their live presence,
+and a durable transcript, and it does three things: accept connections, stamp +
+persist each inbound message, and broadcast every message / presence change to
+everyone else in the room. **All the intelligence stays in the consoles** — the
+server never runs anything.
+
+See `docs/design/console-room-server.md` for the full design and decisions.
+
+## Status — complete server (S1–S3)
+
+Two front doors, one process:
+
+- **Console door** — an NDJSON listener on **localhost**, which each
+  runspec-console reaches by opening a `direct-tcpip` channel over its existing
+  pooled SSH connection. A console's right to be in the room *is* its SSH access —
+  no new exposed port, no second credential.
+- **Browser door** — a WebSocket endpoint (`/ws`) plus a small vanilla static
+  frontend (transcript / composer / presence) with recent-history backscroll for
+  people. Authenticated via **OIDC** (no passwords stored); identity comes from
+  the signed-cookie session. TLS is self-terminated or left to a reverse proxy.
+
+## Run it
+
+```bash
+pip install -e .
+
+# Full server (browser + console doors):
+console-room --port 8080 --ndjson-port 8765 --db ./console_room.db
+
+# Console door only (no web deps needed):
+console-room --ndjson-only --ndjson-port 8765 --db ./console_room.db
+```
+
+The console door stays on localhost — consoles tunnel in. Open the browser door
+at the web port.
+
+### Enabling login (OIDC) + TLS
+
+Without OIDC config the browser door runs in **dev mode** — unauthenticated,
+identity from a `?user=` join form (a warning is logged; don't expose it). Set the
+OIDC env vars to require single sign-on:
+
+```bash
+export CONSOLE_ROOM_OIDC_ISSUER="https://login.microsoftonline.com/<tenant>/v2.0"
+# or CONSOLE_ROOM_OIDC_METADATA_URL=<discovery doc URL>
+export CONSOLE_ROOM_OIDC_CLIENT_ID="…"
+export CONSOLE_ROOM_OIDC_CLIENT_SECRET="…"
+export CONSOLE_ROOM_SESSION_SECRET="$(openssl rand -hex 32)"
+export CONSOLE_ROOM_PUBLIC_URL="https://room.example.com"   # for the redirect_uri
+# register  $CONSOLE_ROOM_PUBLIC_URL/auth/callback  as the redirect URI at your IdP
+
+console-room --host 0.0.0.0 --port 443 \
+  --tls-cert /etc/ssl/room.crt --tls-key /etc/ssl/room.key
+```
+
+uvicorn is proxy-header-aware (`X-Forwarded-Proto`), so you can drop `--tls-*` and
+let nginx/Caddy terminate TLS instead.
+
+## Wire protocol (NDJSON, one JSON object per line)
+
+Console → server:
+
+```json
+{"type":"hello",   "room":"ops", "user":"alice@web01"}
+{"type":"message", "room":"ops", "text":"rolling out"}
+{"type":"presence","room":"ops", "status":"available"}
+```
+
+The **first** frame must be `hello` — that's how a console declares its identity
+(the server can't see the OS user over the tunnel). The name is bound to the
+connection and stamped onto every later message; per-frame `user` fields are
+ignored, so a frame can't spoof a different sender.
+
+Server → client:
+
+```json
+{"type":"message", "room":"ops", "sender":"alice@web01", "text":"rolling out", "id":"…", "ts":0.0}
+{"type":"presence","room":"ops", "user":"alice@web01", "status":"available"}
+```
+
+The server echoes a sender's own message back (with the assigned `id`/`ts`); a
+console drops its own echo so it never re-reacts to its own messages.
+
+Browsers speak the **same `message` / `presence` schema** over the WebSocket — but
+their identity comes from the **connection** (the `?user=&room=` query in dev, the
+OIDC session in S3), so they send no `hello` frame.
+
+## Develop
+
+```bash
+pip install -e ".[dev]"
+pytest
+```

runspec_room-0.3.0/console_room/__init__.py

@@ -0,0 +1,28 @@
+"""
+console_room — the runspec chat-room server.
+
+A small "dumb message pipe with presence" the consoles connect to: it holds, per
+room, the connected participants, their live presence, and a durable transcript,
+and broadcasts every message / presence change. All intelligence stays in the
+consoles. See docs/design/console-room-server.md.
+
+S1 (this release) serves the console NDJSON-localhost door; the browser door and
+OIDC/TLS land in later slices.
+"""
+
+from __future__ import annotations
+
+from .hub import Hub, Participant
+from .models import Message, presence_frame
+from .store import TranscriptStore
+
+__version__ = "0.3.0"
+
+__all__ = [
+    "Hub",
+    "Participant",
+    "Message",
+    "TranscriptStore",
+    "presence_frame",
+    "__version__",
+]

runspec_room-0.3.0/console_room/hub.py

@@ -0,0 +1,130 @@
+"""
+hub.py — the in-process room broker (transport-agnostic).
+
+The hub owns rooms → participants and does the three jobs of the server: it lets
+participants join/leave, broadcasts every message and presence change, and
+persists messages to the transcript. It knows nothing about sockets: a
+*participant* is anything with ``.user`` / ``.room`` / ``.wants_backscroll`` and an
+async ``send(frame)``, so the NDJSON console connection (S1) and the WS browser
+connection (S2) plug into the same hub. See docs/design/console-room-server.md §4.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Any, Protocol, runtime_checkable
+
+from .models import Message, presence_frame
+
+logger = logging.getLogger("console_room.hub")
+
+
+@runtime_checkable
+class Participant(Protocol):
+    """A connected member of a room — the hub's view of any connection.
+
+    ``wants_backscroll`` is the load-bearing asymmetry: browsers want the recent
+    transcript on join, consoles must never get it (forward-only)."""
+
+    user: str
+    room: str
+    wants_backscroll: bool
+
+    async def send(self, frame: dict[str, Any]) -> None: ...
+
+
+@runtime_checkable
+class Store(Protocol):
+    """The slice of the transcript store the hub needs (synchronous; the hub
+    calls it via ``asyncio.to_thread``)."""
+
+    def append(self, msg: Message) -> None: ...
+    def recent(self, room: str, limit: int) -> list[Message]: ...
+
+
+async def _safe_send(p: Participant, frame: dict[str, Any]) -> None:
+    """Send to one participant, swallowing failures so a dead/slow connection
+    can't break a broadcast to the rest of the room."""
+    try:
+        await p.send(frame)
+    except Exception:
+        logger.warning("room: send to %r failed; dropping from this round", p.user)
+
+
+class Hub:
+    """Owns the live rooms and routes messages/presence between participants."""
+
+    def __init__(self, store: Store, *, backscroll_limit: int = 50) -> None:
+        self._store = store
+        self._backscroll = backscroll_limit
+        self._rooms: dict[str, set[Participant]] = {}
+        self._lock = asyncio.Lock()  # guards _rooms membership
+
+    async def join(self, p: Participant) -> None:
+        """Add ``p`` to its room: tell it who's already here, replay backscroll if
+        it wants it (browsers only), then announce it to the others."""
+        async with self._lock:
+            members = self._rooms.setdefault(p.room, set())
+            existing = list(members)
+            members.add(p)
+        # Catch the newcomer up on who is already present.
+        for other in existing:
+            await _safe_send(p, presence_frame(p.room, other.user, "available"))
+        # Backscroll: browsers see recent history; consoles never do.
+        if p.wants_backscroll:
+            for msg in await self._recent(p.room):
+                await _safe_send(p, msg.to_frame())
+        # Announce the newcomer to everyone already in the room.
+        await self._broadcast(
+            p.room, presence_frame(p.room, p.user, "available"), exclude=p
+        )
+
+    async def leave(self, p: Participant) -> None:
+        """Remove ``p`` and tell the room it's gone (best-effort; idempotent)."""
+        async with self._lock:
+            members = self._rooms.get(p.room)
+            present = bool(members and p in members)
+            if members and p in members:
+                members.remove(p)
+                if not members:
+                    self._rooms.pop(p.room, None)
+        if present:
+            await self._broadcast(
+                p.room, presence_frame(p.room, p.user, "away"), exclude=p
+            )
+
+    async def on_message(self, p: Participant, text: str) -> None:
+        """Stamp, persist, and broadcast a message — echoed to the sender too, so
+        every client (including the author's other views) converges on the same
+        server-assigned id/ts."""
+        msg = Message.new(p.room, p.user, text)
+        await asyncio.to_thread(self._store.append, msg)
+        await self._broadcast(p.room, msg.to_frame())
+
+    async def on_presence(self, p: Participant, status: str) -> None:
+        """Relay a participant's presence change (e.g. a console's rota flip) to
+        the rest of the room."""
+        await self._broadcast(p.room, presence_frame(p.room, p.user, status), exclude=p)
+
+    async def _recent(self, room: str) -> list[Message]:
+        return await asyncio.to_thread(self._store.recent, room, self._backscroll)
+
+    async def _broadcast(
+        self,
+        room: str,
+        frame: dict[str, Any],
+        *,
+        exclude: Participant | None = None,
+    ) -> None:
+        async with self._lock:
+            members = list(self._rooms.get(room, ()))
+        for m in members:
+            if m is exclude:
+                continue
+            await _safe_send(m, frame)
+
+    def room_size(self, room: str) -> int:
+        """Number of participants currently in ``room`` (for tests / a health
+        endpoint). Read-only snapshot."""
+        return len(self._rooms.get(room, ()))

runspec_room-0.3.0/console_room/models.py

@@ -0,0 +1,116 @@
+"""
+models.py — the room wire schema: a Message and the frame builders / validators.
+
+The server is the authority on a message's ``id`` / ``ts`` / ``sender`` — clients
+send only ``room`` + ``text`` and the server stamps the rest (see
+docs/design/console-room-server.md §3). These helpers are pure and have no I/O, so
+the framing rules are unit-tested on their own.
+"""
+
+from __future__ import annotations
+
+import time
+import uuid
+from dataclasses import dataclass
+from typing import Any
+
+# Cap a message body so a pathological post can't bloat the transcript / a frame,
+# mirroring the console source's _TEXT_CAP.
+TEXT_CAP = 20_000
+
+# Frame type tags.
+HELLO = "hello"
+MESSAGE = "message"
+PRESENCE = "presence"
+
+_VALID_STATUS = ("available", "away")
+
+
+def new_id() -> str:
+    """A fresh message id (server-assigned)."""
+    return uuid.uuid4().hex
+
+
+def now_ts() -> float:
+    """The current wall-clock timestamp (server-assigned)."""
+    return time.time()
+
+
+def _str(val: Any) -> str:
+    return "" if val is None else str(val)
+
+
+def _cap(text: str) -> str:
+    return text if len(text) <= TEXT_CAP else text[:TEXT_CAP] + "…"
+
+
+@dataclass(frozen=True)
+class Message:
+    """One sent message — the unit the transcript stores and broadcasts."""
+
+    room: str
+    sender: str
+    text: str
+    id: str
+    ts: float
+
+    @classmethod
+    def new(cls, room: str, sender: str, text: str) -> Message:
+        """Build a message, stamping a fresh ``id`` + ``ts`` (the server's job)."""
+        return cls(
+            room=_str(room),
+            sender=_str(sender),
+            text=_cap(_str(text)),
+            id=new_id(),
+            ts=now_ts(),
+        )
+
+    def to_frame(self) -> dict[str, Any]:
+        """The server → client ``message`` frame for this message."""
+        return {
+            "type": MESSAGE,
+            "room": self.room,
+            "sender": self.sender,
+            "text": self.text,
+            "id": self.id,
+            "ts": self.ts,
+        }
+
+
+def presence_frame(room: str, user: str, status: str) -> dict[str, Any]:
+    """A server → client ``presence`` frame. ``status`` is normalised to one of
+    ``available`` / ``away`` (anything not ``available`` becomes ``away``)."""
+    return {
+        "type": PRESENCE,
+        "room": _str(room),
+        "user": _str(user),
+        "status": normalize_status(status),
+    }
+
+
+def normalize_status(status: Any) -> str:
+    """Coerce a status to ``available`` / ``away`` (default ``away``)."""
+    return "available" if _str(status) == "available" else "away"
+
+
+@dataclass(frozen=True)
+class Hello:
+    """A parsed ``hello`` frame — a console declaring its identity on connect."""
+
+    user: str
+    room: str
+
+
+def parse_hello(obj: Any) -> Hello | None:
+    """Parse a ``hello`` frame, or ``None`` if it isn't a valid one.
+
+    A blank ``room`` is rejected (a console must say which room it's joining); a
+    blank ``user`` falls back to ``"unknown"`` so a mis-configured console is still
+    visibly present rather than silently dropped."""
+    if not isinstance(obj, dict) or _str(obj.get("type")) != HELLO:
+        return None
+    room = _str(obj.get("room")).strip()
+    if not room:
+        return None
+    user = _str(obj.get("user")).strip() or "unknown"
+    return Hello(user=user, room=room)