terp-cap-realtime 0.1.0__tar.gz

terp_cap_realtime-0.1.0/.gitignore

@@ -0,0 +1,47 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+.venv-*/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# uv
+uv.lock
+
+# Node
+node_modules/
+.pnpm-store/
+*.tsbuildinfo
+
+# Playwright (conformance e2e) artifacts
+test-results/
+playwright-report/
+blob-report/
+playwright/.cache/
+.last-run.json
+
+# Local frontend template render checks
+apps/example/_frontend_tpl_check/
+
+# Editor / OS
+.DS_Store
+.idea/
+*.local
+
+# Local environment overrides — never commit (a real .env may hold SECRET_KEY).
+# The tracked template is `.env.example`.
+.env
+.env.*
+!.env.example
+!.env.example.jinja
+# Rendered app-declared variables (environment.schema.json) — may hold secrets.
+.app.env

terp_cap_realtime-0.1.0/PKG-INFO

@@ -0,0 +1,7 @@
+Metadata-Version: 2.4
+Name: terp-cap-realtime
+Version: 0.1.0
+Summary: Terp realtime capability — typed, policy-gated SSE and WebSocket channels with one-use connection tickets.
+License-Expression: Apache-2.0
+Requires-Python: >=3.13
+Requires-Dist: terp-core==0.1.0

terp_cap_realtime-0.1.0/README.md

@@ -0,0 +1,66 @@
+# terp-cap-realtime
+
+The opt-in, sanctioned realtime surface for Terp apps: typed SSE and WebSocket
+channels behind one generated-client handshake.
+
+## Backend
+
+Declare and register a channel once:
+
+```python
+from pydantic import BaseModel
+from terp.capabilities.realtime import RealtimeChannel, register_channel
+
+class Notice(BaseModel):
+    sequence: int
+    text: str
+
+NOTICES = register_channel(RealtimeChannel("system.notices", Notice))
+```
+
+The default audience is the authenticated principal. Publish to that explicit
+audience (a tenant resolver can return a tenant id instead; use
+`global_audience` only for intentionally global broadcasts):
+
+```python
+await publish(NOTICES, Notice(sequence=1, text="Ready"), audience=str(user_id))
+```
+
+A bidirectional WebSocket channel adds an inbound Pydantic model + handler. Its
+subscription requirement defaults to VIEWER; its inbound requirement defaults
+to EDITOR, and both can be typed `Role`/`Permission` objects. The handler receives
+the authenticated principal and a validated model, never an untyped frame. Each
+frame runs in a fresh session that closes when its sync or async handler returns;
+apps with a custom session seam pass it as `message_session_provider` to
+`configure_realtime`.
+
+The self-registering `ModuleSpec` mounts:
+
+- `POST /api/v1/realtime/tickets` — authenticated by the app's normal principal
+  provider; applies channel authority; returns a 30-second opaque ticket.
+- `GET /api/v1/realtime/sse/{channel}` — redeems an SSE ticket once.
+- `WS /api/v1/realtime/ws/{channel}` — redeems a WebSocket ticket once.
+
+The bearer token stays server-side; it never appears in the URL. Configure
+`principal_validator` to recheck expiry/revocation during long-lived connections.
+Single-process apps use bounded in-memory broker/ticket stores. Multi-replica
+apps wire a shared broker and `RedisConnectionTicketStore` (atomic GET+DEL),
+shipped behind the `terp-cap-redis[realtime]` extra
+(`terp.capabilities.redis.realtime`).
+
+## Frontend
+
+App modules use the package-root hook, never raw transports:
+
+```tsx
+const notices = useRealtimeChannel({
+  channel: "system.notices",
+  validate: isNotice,
+});
+```
+
+The hook mints its ticket through the generated authenticated client, opens the
+native transport internally, and validates every JSON payload with the supplied
+type guard before exposing it. A transient disconnect closes the consumed-ticket
+transport and remints with bounded exponential backoff; `close()` cancels both a
+pending mint and scheduled reconnects.

terp_cap_realtime-0.1.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "terp-cap-realtime"
+version = "0.1.0"
+description = "Terp realtime capability — typed, policy-gated SSE and WebSocket channels with one-use connection tickets."
+requires-python = ">=3.13"
+license = "Apache-2.0"
+dependencies = [
+    "terp-core==0.1.0",
+]
+
+# Self-registering: the kernel mounts the authenticated ticket + transport
+# router at /api/v1/realtime behind Policy.default(). App code declares typed
+# channels and publishes through the capability's public registry/broker seam.
+[project.entry-points."terp.capabilities"]
+realtime = "terp.capabilities.realtime:module"
+
+# PEP 420 namespace package: this distribution owns only
+# `terp.capabilities.realtime`.
+[tool.hatch.build.targets.wheel]
+sources = ["src"]
+only-include = ["src/terp/capabilities/realtime"]

terp_cap_realtime-0.1.0/src/terp/capabilities/realtime/__init__.py

@@ -0,0 +1,101 @@
+"""terp.capabilities.realtime — sanctioned typed SSE + WebSocket channels.
+
+App modules never touch raw transports. They declare a :class:`RealtimeChannel`,
+register it, and publish Pydantic messages through :func:`publish`; the
+self-registering capability exposes the authenticated ticket + transport
+router. Browser code subscribes through ``@terp/react-core``'s
+``useRealtimeChannel`` hook, which mints its one-use ticket with the generated
+client before opening EventSource/WebSocket.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+from terp.capabilities.realtime.broker import (
+    BackpressureError,
+    InMemoryRealtimeBroker,
+    RealtimeBroker,
+    audience_topic,
+    configure_broker,
+    get_broker,
+)
+from terp.capabilities.realtime.channel import (
+    AudienceResolver,
+    InboundHandler,
+    RealtimeAuthzRef,
+    RealtimeChannel,
+    clear_channels,
+    global_audience,
+    get_channel,
+    register_channel,
+    registered_channels,
+    principal_audience,
+)
+from terp.capabilities.realtime.router import (
+    HEARTBEAT_SECONDS,
+    MAX_INBOUND_BYTES,
+    TICKET_TTL_SECONDS,
+    MessageSessionProvider,
+    PrincipalValidator,
+    configure_realtime,
+    module,
+    reset_realtime_configuration,
+    router,
+)
+from terp.capabilities.realtime.tickets import (
+    ConnectionTicket,
+    ConnectionTicketStore,
+    InMemoryConnectionTicketStore,
+    configure_ticket_store,
+    get_ticket_store,
+)
+
+
+async def publish(
+    channel: RealtimeChannel, message: BaseModel, *, audience: str
+) -> None:
+    """Validate and publish *message* to one explicit channel *audience*."""
+    if get_channel(channel.name) != channel:
+        raise ValueError(
+            f"realtime channel {channel.name!r} is not registered with this declaration"
+        )
+    validated = channel.outbound_model.model_validate(message)
+    await get_broker().publish(
+        audience_topic(channel.name, audience), validated.model_dump_json()
+    )
+
+
+__all__ = [
+    "AudienceResolver",
+    "BackpressureError",
+    "ConnectionTicket",
+    "ConnectionTicketStore",
+    "HEARTBEAT_SECONDS",
+    "InboundHandler",
+    "InMemoryConnectionTicketStore",
+    "InMemoryRealtimeBroker",
+    "MAX_INBOUND_BYTES",
+    "MessageSessionProvider",
+    "PrincipalValidator",
+    "RealtimeBroker",
+    "RealtimeChannel",
+    "RealtimeAuthzRef",
+    "TICKET_TTL_SECONDS",
+    "clear_channels",
+    "audience_topic",
+    "configure_broker",
+    "configure_realtime",
+    "configure_ticket_store",
+    "get_broker",
+    "get_channel",
+    "get_ticket_store",
+    "global_audience",
+    "module",
+    "publish",
+    "principal_audience",
+    "register_channel",
+    "registered_channels",
+    "reset_realtime_configuration",
+    "router",
+]

terp_cap_realtime-0.1.0/src/terp/capabilities/realtime/broker.py

@@ -0,0 +1,151 @@
+"""Realtime broker port + bounded in-process implementation.
+
+The broker is the fan-out seam: publishers submit already-validated JSON and
+each subscriber gets a bounded queue. A slow consumer is disconnected instead
+of growing memory without bound; its transport observes ``BackpressureError``
+and closes. Multi-replica deployments replace this per-process adapter with a
+shared broker (Redis/pubsub, managed messaging) through ``configure_broker``.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from abc import ABC, abstractmethod
+from collections.abc import AsyncIterator
+from dataclasses import dataclass
+from threading import RLock
+
+
+class BackpressureError(RuntimeError):
+    """A subscriber fell behind its bounded queue and must reconnect."""
+
+
+def audience_topic(channel: str, audience: str) -> str:
+    """Opaque broker topic for one declared channel + authorized audience."""
+    normalized = audience.strip()
+    if not normalized or len(normalized) > 500 or "\x00" in normalized:
+        raise ValueError("realtime audience must be a non-empty string (max 500 chars)")
+    return f"{channel}\x00{normalized}"
+
+
+@dataclass(frozen=True)
+class _Overflow:
+    pass
+
+
+_OVERFLOW = _Overflow()
+
+
+class RealtimeBroker(ABC):
+    """Publish validated JSON and subscribe to one declared channel name."""
+
+    @abstractmethod
+    async def publish(self, channel: str, payload: str) -> None: ...
+
+    @abstractmethod
+    def stream(self, channel: str) -> AsyncIterator[str]: ...
+
+
+@dataclass(eq=False)
+class _Subscriber:
+    loop: asyncio.AbstractEventLoop
+    queue: asyncio.Queue[str | _Overflow]
+
+
+class InMemoryRealtimeBroker(RealtimeBroker):
+    """Thread-safe, per-process fan-out with bounded queues.
+
+    ``publish`` may run on an event loop different from a subscriber's (or be
+    invoked via ``asyncio.run`` from a sync service hook), so delivery uses
+    ``call_soon_threadsafe`` into the queue owner's loop. Queue overflow posts
+    one terminal marker and unregisters the subscriber.
+    """
+
+    def __init__(self, *, queue_size: int = 100) -> None:
+        if queue_size <= 0:
+            raise ValueError("realtime queue_size must be positive")
+        self._queue_size = queue_size
+        self._lock = RLock()
+        self._subscribers: dict[str, set[_Subscriber]] = {}
+
+    async def publish(self, channel: str, payload: str) -> None:
+        with self._lock:
+            subscribers = tuple(self._subscribers.get(channel, ()))
+        for subscriber in subscribers:
+            subscriber.loop.call_soon_threadsafe(
+                self._deliver, channel, subscriber, payload
+            )
+
+    def stream(self, channel: str) -> AsyncIterator[str]:
+        return self._subscription(channel)
+
+    async def _subscription(self, channel: str) -> AsyncIterator[str]:
+        subscriber = _Subscriber(
+            loop=asyncio.get_running_loop(),
+            queue=asyncio.Queue(maxsize=self._queue_size),
+        )
+        with self._lock:
+            self._subscribers.setdefault(channel, set()).add(subscriber)
+        try:
+            while True:
+                item = await subscriber.queue.get()
+                if item is _OVERFLOW:
+                    raise BackpressureError(
+                        f"realtime subscriber for {channel!r} exceeded its queue"
+                    )
+                yield item
+        finally:
+            self._discard(channel, subscriber)
+
+    def _deliver(self, channel: str, subscriber: _Subscriber, payload: str) -> None:
+        try:
+            subscriber.queue.put_nowait(payload)
+        except asyncio.QueueFull:
+            self._discard(channel, subscriber)
+            while not subscriber.queue.empty():
+                subscriber.queue.get_nowait()
+            subscriber.queue.put_nowait(_OVERFLOW)
+
+    def _discard(self, channel: str, subscriber: _Subscriber) -> None:
+        with self._lock:
+            subscribers = self._subscribers.get(channel)
+            if subscribers is None:
+                return
+            subscribers.discard(subscriber)
+            if not subscribers:
+                self._subscribers.pop(channel, None)
+
+    def reset(self) -> None:
+        """Drop every subscriber (test-isolation seam)."""
+        with self._lock:
+            self._subscribers.clear()
+
+
+_configured_broker: RealtimeBroker | None = None
+_configuration_lock = RLock()
+
+
+def configure_broker(broker: RealtimeBroker | None) -> None:
+    """Install *broker* process-wide (``None`` resets to the lazy default)."""
+    global _configured_broker
+    with _configuration_lock:
+        _configured_broker = broker
+
+
+def get_broker() -> RealtimeBroker:
+    """The configured broker, creating the bounded in-memory default lazily."""
+    global _configured_broker
+    with _configuration_lock:
+        if _configured_broker is None:
+            _configured_broker = InMemoryRealtimeBroker()
+        return _configured_broker
+
+
+__all__ = [
+    "BackpressureError",
+    "InMemoryRealtimeBroker",
+    "RealtimeBroker",
+    "audience_topic",
+    "configure_broker",
+    "get_broker",
+]

terp_cap_realtime-0.1.0/src/terp/capabilities/realtime/channel.py

@@ -0,0 +1,171 @@
+"""Typed realtime channel declarations + the process registry.
+
+A channel is the realtime analogue of ``EventDefinition``: app code names it
+once and binds its wire payload to Pydantic models. The transport never accepts
+an untyped dict. ``mode='sse'`` is server-push only; ``mode='websocket'`` may
+add an inbound model + handler for bidirectional messages.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from threading import RLock
+from typing import Literal
+
+from pydantic import BaseModel
+from sqlmodel import Session
+
+from terp.core import (
+    AuthorizationRequirement,
+    Permission,
+    Principal,
+    Role,
+    Roles,
+    as_role,
+)
+
+_CHANNEL_RE = re.compile(r"^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$")
+
+InboundHandler = Callable[[Session, Principal, BaseModel], None | Awaitable[None]]
+AudienceResolver = Callable[[Session, Principal], str]
+
+
+def principal_audience(_session: Session, principal: Principal) -> str:
+    """Default audience: only connections minted for this principal."""
+    return str(principal.id)
+
+
+def global_audience(_session: Session, _principal: Principal) -> str:
+    """Explicit opt-in audience for a channel intentionally shared by all subscribers."""
+    return "global"
+
+
+RealtimeAuthzRef = AuthorizationRequirement | Permission | Role | Roles
+
+
+def _requirement(value: RealtimeAuthzRef) -> AuthorizationRequirement:
+    if isinstance(value, AuthorizationRequirement):
+        return value
+    if isinstance(value, Permission):
+        return AuthorizationRequirement.from_permission(value)
+    return AuthorizationRequirement.from_role(as_role(value))
+
+
+@dataclass(frozen=True, init=False)
+class RealtimeChannel:
+    """One typed, authorized realtime stream.
+
+    ``requirement`` is the read authority for minting a ticket. Role floors and
+    permissions use the same normalized objects as ``Policy``; a permission is
+    denied fail-closed unless the realtime capability is configured with a
+    permission enforcer. Each ``on_message`` call receives a fresh per-frame
+    session that closes when the handler completes. ``inbound_model`` /
+    ``on_message`` are both required or both absent, and only WebSocket channels
+    may declare them.
+    """
+
+    name: str
+    outbound_model: type[BaseModel]
+    mode: Literal["sse", "websocket"] = "sse"
+    requirement: AuthorizationRequirement
+    inbound_requirement: AuthorizationRequirement
+    inbound_model: type[BaseModel] | None = None
+    on_message: InboundHandler | None = None
+    audience: AudienceResolver
+
+    def __init__(
+        self,
+        name: str,
+        outbound_model: type[BaseModel],
+        *,
+        mode: Literal["sse", "websocket"] = "sse",
+        requirement: RealtimeAuthzRef = Roles.VIEWER,
+        inbound_requirement: RealtimeAuthzRef = Roles.EDITOR,
+        inbound_model: type[BaseModel] | None = None,
+        on_message: InboundHandler | None = None,
+        audience: AudienceResolver = principal_audience,
+    ) -> None:
+        if _CHANNEL_RE.fullmatch(name) is None:
+            raise ValueError(
+                "RealtimeChannel.name must be a lowercase dotted/dashed token, "
+                f"got {name!r}"
+            )
+        if not isinstance(outbound_model, type) or not issubclass(
+            outbound_model, BaseModel
+        ):
+            raise TypeError("RealtimeChannel.outbound_model must be a Pydantic model")
+        if mode not in {"sse", "websocket"}:
+            raise ValueError("RealtimeChannel.mode must be 'sse' or 'websocket'")
+        has_model = inbound_model is not None
+        has_handler = on_message is not None
+        if has_model != has_handler:
+            raise ValueError(
+                "RealtimeChannel.inbound_model and on_message must be declared together"
+            )
+        if has_model and mode != "websocket":
+            raise ValueError("only WebSocket channels can receive inbound messages")
+        if has_model and (
+            not isinstance(inbound_model, type)
+            or not issubclass(inbound_model, BaseModel)
+        ):
+            raise TypeError("RealtimeChannel.inbound_model must be a Pydantic model")
+        if not callable(audience):
+            raise TypeError("RealtimeChannel.audience must be callable")
+        object.__setattr__(self, "name", name)
+        object.__setattr__(self, "outbound_model", outbound_model)
+        object.__setattr__(self, "mode", mode)
+        object.__setattr__(self, "requirement", _requirement(requirement))
+        object.__setattr__(
+            self, "inbound_requirement", _requirement(inbound_requirement)
+        )
+        object.__setattr__(self, "inbound_model", inbound_model)
+        object.__setattr__(self, "on_message", on_message)
+        object.__setattr__(self, "audience", audience)
+
+
+_lock = RLock()
+_channels: dict[str, RealtimeChannel] = {}
+
+
+def register_channel(channel: RealtimeChannel) -> RealtimeChannel:
+    """Register *channel* exactly once (idempotent for the same declaration)."""
+    with _lock:
+        existing = _channels.get(channel.name)
+        if existing is not None and existing != channel:
+            raise ValueError(f"duplicate realtime channel declaration: {channel.name!r}")
+        _channels[channel.name] = channel
+    return channel
+
+
+def get_channel(name: str) -> RealtimeChannel | None:
+    """The declared channel named *name*, or ``None`` (never a dynamic topic)."""
+    with _lock:
+        return _channels.get(name)
+
+
+def registered_channels() -> tuple[RealtimeChannel, ...]:
+    """All declarations, sorted for deterministic introspection/tests."""
+    with _lock:
+        return tuple(_channels[name] for name in sorted(_channels))
+
+
+def clear_channels() -> None:
+    """Drop the registry (test-isolation seam; declarations are import-time)."""
+    with _lock:
+        _channels.clear()
+
+
+__all__ = [
+    "AudienceResolver",
+    "InboundHandler",
+    "RealtimeAuthzRef",
+    "RealtimeChannel",
+    "clear_channels",
+    "get_channel",
+    "global_audience",
+    "principal_audience",
+    "register_channel",
+    "registered_channels",
+]

terp_cap_realtime-0.1.0/src/terp/capabilities/realtime/router.py

@@ -0,0 +1,458 @@
+"""Authenticated ticket mint + SSE/WebSocket transport endpoints.
+
+The HTTP mint endpoint runs behind the capability's normal deny-by-default
+``Policy`` and receives the live principal from the app's configured auth seam.
+It applies the channel's typed authority requirement, then captures that
+principal in a 30-second, single-use ticket. Browser-native transports redeem
+the opaque ticket at handshake; the bearer token never enters a URL.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from collections.abc import AsyncIterator, Callable, Iterator
+from contextlib import contextmanager
+from inspect import isawaitable, iscoroutinefunction
+from typing import Annotated, Literal
+
+from fastapi import APIRouter, Depends, Query, Request, WebSocket, WebSocketDisconnect
+from pydantic import BaseModel, Field, ValidationError
+from sqlmodel import Session
+from starlette.responses import StreamingResponse
+
+from terp.core import (
+    AuthorizationRequirement,
+    ModuleSpec,
+    PermissionDeniedError,
+    PermissionEnforcer,
+    Policy,
+    Principal,
+    SessionDep,
+    bind_audit_actor,
+    get_principal,
+    get_session,
+)
+
+from terp.capabilities.realtime.broker import (
+    BackpressureError,
+    audience_topic,
+    get_broker,
+)
+from terp.capabilities.realtime.channel import RealtimeChannel, get_channel
+from terp.capabilities.realtime.tickets import ConnectionTicket, get_ticket_store
+
+TICKET_TTL_SECONDS = 30
+HEARTBEAT_SECONDS = 15.0
+MAX_INBOUND_BYTES = 64 * 1024
+
+PrincipalValidator = Callable[[Principal, str], bool]
+MessageSessionProvider = Callable[[], Iterator[Session]]
+
+_permission_enforcer: PermissionEnforcer | None = None
+_principal_validator: PrincipalValidator | None = None
+_message_session_provider: MessageSessionProvider | None = None
+
+
+class TicketRequest(BaseModel):
+    channel: str = Field(min_length=1, max_length=200)
+    transport: Literal["sse", "websocket"]
+
+
+class TicketResponse(BaseModel):
+    ticket: str = Field(min_length=1, max_length=200)
+    expires_in: int = Field(gt=0)
+    channel: str = Field(min_length=1, max_length=200)
+    transport: Literal["sse", "websocket"]
+
+
+def configure_realtime(
+    *,
+    permission_enforcer: PermissionEnforcer | None = None,
+    principal_validator: PrincipalValidator | None = None,
+    message_session_provider: MessageSessionProvider | None = None,
+) -> None:
+    """Wire optional authorization/revocation seams at composition time.
+
+    A channel whose requirement is a Permission denies fail-closed unless
+    ``permission_enforcer`` is present. ``principal_validator`` may revalidate
+    long-lived connections at handshake/heartbeat/frame boundaries; without it,
+    authority is the live principal captured by the 30-second ticket mint.
+    ``message_session_provider`` supplies one fresh session per inbound frame;
+    the core request-session provider is the default.
+    """
+    global _permission_enforcer, _principal_validator, _message_session_provider
+    _permission_enforcer = permission_enforcer
+    _principal_validator = principal_validator
+    _message_session_provider = message_session_provider
+
+
+def reset_realtime_configuration() -> None:
+    """Restore optional seam defaults (test isolation)."""
+    configure_realtime()
+
+
+def _authorize_requirement(
+    requirement: AuthorizationRequirement,
+    principal: Principal,
+    session: Session,
+) -> None:
+    if principal.role.rank < requirement.min_rank:
+        raise PermissionDeniedError()
+    if requirement.kind == "permission" and (
+        _permission_enforcer is None
+        or not _permission_enforcer(session, principal.id, requirement.name)
+    ):
+        raise PermissionDeniedError()
+
+
+def _authorize(channel: RealtimeChannel, principal: Principal, session: Session) -> None:
+    _authorize_requirement(channel.requirement, principal, session)
+    if channel.inbound_model is not None:
+        _authorize_requirement(channel.inbound_requirement, principal, session)
+
+
+def _validate_live(ticket: ConnectionTicket) -> bool:
+    return _principal_validator is None or _principal_validator(
+        ticket.principal, ticket.credential
+    )
+
+
+async def _validate_live_async(ticket: ConnectionTicket) -> bool:
+    validator = _principal_validator
+    if validator is None:
+        return True
+    return await asyncio.to_thread(
+        validator, ticket.principal, ticket.credential
+    )
+
+
+@contextmanager
+def _message_session() -> Iterator[Session]:
+    sessions = (_message_session_provider or get_session)()
+    try:
+        session = next(sessions)
+    except StopIteration as exc:
+        raise RuntimeError("realtime message session provider yielded no session") from exc
+    try:
+        yield session
+    finally:
+        close = getattr(sessions, "close", None)
+        if close is not None:
+            close()
+
+
+def _handler_is_async(handler: Callable[..., object]) -> bool:
+    return iscoroutinefunction(handler) or iscoroutinefunction(
+        getattr(handler, "__call__", None)
+    )
+
+
+def _run_sync_handler(
+    handler: Callable[..., object],
+    ticket: ConnectionTicket,
+    message: BaseModel,
+) -> None:
+    with _message_session() as session, bind_audit_actor(ticket.principal.id):
+        result = handler(session, ticket.principal, message)
+        if isawaitable(result):
+            close = getattr(result, "close", None)
+            if close is not None:
+                close()
+            raise TypeError(
+                "realtime sync handler returned an awaitable; declare it with async def"
+            )
+
+
+async def _run_inbound_handler(
+    handler: Callable[..., object],
+    ticket: ConnectionTicket,
+    message: BaseModel,
+) -> None:
+    if not _handler_is_async(handler):
+        await asyncio.to_thread(_run_sync_handler, handler, ticket, message)
+        return
+    with _message_session() as session, bind_audit_actor(ticket.principal.id):
+        result = handler(session, ticket.principal, message)
+        if not isawaitable(result):
+            raise TypeError("realtime async handler returned a non-awaitable")
+        await result
+
+
+def _bearer_credential(request: Request) -> str:
+    header = request.headers.get("Authorization", "")
+    if not header.lower().startswith("bearer "):
+        return ""
+    return header[7:].strip()
+
+
+router = APIRouter(tags=["realtime"])
+
+
+@router.post("/tickets", response_model=TicketResponse, status_code=201)
+def mint_ticket(
+    payload: TicketRequest,
+    request: Request,
+    session: SessionDep,
+    principal: Principal | None = Depends(get_principal),
+) -> TicketResponse:
+    if principal is None:
+        # Defensive: the module guard already rejects this endpoint, but the
+        # handler remains fail-closed when called directly in tests.
+        from terp.core import AuthenticationError
+
+        raise AuthenticationError()
+    channel = get_channel(payload.channel)
+    if channel is None or channel.mode != payload.transport:
+        # Do not reveal whether a guessed channel exists under another mode.
+        raise PermissionDeniedError()
+    _authorize(channel, principal, session)
+    connection_ticket = ConnectionTicket(
+            principal=principal,
+            channel=channel.name,
+            transport=payload.transport,
+            credential=_bearer_credential(request),
+            audience=channel.audience(session, principal),
+        )
+    if not _validate_live(connection_ticket):
+        from terp.core import AuthenticationError
+
+        raise AuthenticationError()
+    ticket = get_ticket_store().issue(
+        connection_ticket,
+        ttl_seconds=TICKET_TTL_SECONDS,
+    )
+    return TicketResponse(
+        ticket=ticket,
+        expires_in=TICKET_TTL_SECONDS,
+        channel=channel.name,
+        transport=payload.transport,
+    )
+
+
+def _consume_ticket(
+    token: str, *, channel_name: str, transport: str
+) -> ConnectionTicket | None:
+    return get_ticket_store().consume(
+        token, channel=channel_name, transport=transport
+    )
+
+
+def _sse_data(payload: str) -> bytes:
+    # The broker accepts only Pydantic-produced compact JSON; replace CR/LF as
+    # defense in depth so one payload can never inject an SSE field/event.
+    safe = payload.replace("\r", "").replace("\n", "")
+    return f"data: {safe}\n\n".encode("utf-8")
+
+
+async def _sse_stream(
+    channel: RealtimeChannel,
+    ticket: ConnectionTicket,
+    *,
+    heartbeat_seconds: float = HEARTBEAT_SECONDS,
+) -> AsyncIterator[bytes]:
+    iterator = get_broker().stream(
+        audience_topic(channel.name, ticket.audience)
+    ).__aiter__()
+    pending = asyncio.create_task(anext(iterator))
+    try:
+        while True:
+            done, _ = await asyncio.wait(
+                {pending}, timeout=heartbeat_seconds
+            )
+            if not done:
+                if not await _validate_live_async(ticket):
+                    return
+                yield b": keepalive\n\n"
+                continue
+            try:
+                payload = pending.result()
+            except (StopAsyncIteration, BackpressureError):
+                return
+            if not await _validate_live_async(ticket):
+                return
+            yield _sse_data(payload)
+            pending = asyncio.create_task(anext(iterator))
+    finally:
+        pending.cancel()
+        # asyncio.wait, never gather — see _settle_websocket_tasks.
+        await asyncio.wait({pending})
+        await iterator.aclose()
+
+
+@router.get(
+    "/sse/{channel_name}",
+    response_model=None,
+    response_class=StreamingResponse,
+)
+def subscribe_sse(
+    channel_name: str,
+    ticket: Annotated[str, Query(min_length=1, max_length=200)],
+) -> StreamingResponse:
+    channel = get_channel(channel_name)
+    redeemed = _consume_ticket(ticket, channel_name=channel_name, transport="sse")
+    if channel is None or channel.mode != "sse" or redeemed is None:
+        from terp.core import AuthenticationError
+
+        raise AuthenticationError()
+    if not _validate_live(redeemed):
+        from terp.core import AuthenticationError
+
+        raise AuthenticationError()
+    return StreamingResponse(
+        _sse_stream(channel, redeemed),
+        media_type="text/event-stream",
+        headers={
+            "Cache-Control": "no-cache, no-store",
+            "X-Accel-Buffering": "no",
+        },
+    )
+
+
+async def _websocket_outbound(
+    websocket: WebSocket, channel: RealtimeChannel, ticket: ConnectionTicket
+) -> None:
+    async for payload in get_broker().stream(
+        audience_topic(channel.name, ticket.audience)
+    ):
+        if not await _validate_live_async(ticket):
+            await websocket.close(code=1008, reason="session no longer valid")
+            return
+        await websocket.send_text(payload)
+
+
+async def _websocket_liveness(
+    websocket: WebSocket,
+    ticket: ConnectionTicket,
+    *,
+    interval_seconds: float = HEARTBEAT_SECONDS,
+) -> None:
+    while True:
+        await asyncio.sleep(interval_seconds)
+        if not await _validate_live_async(ticket):
+            await websocket.close(code=1008, reason="session no longer valid")
+            return
+
+
+async def _websocket_inbound(
+    websocket: WebSocket,
+    channel: RealtimeChannel,
+    ticket: ConnectionTicket,
+) -> None:
+    while True:
+        text = await websocket.receive_text()
+        if len(text.encode("utf-8")) > MAX_INBOUND_BYTES:
+            await websocket.close(code=1009, reason="message too large")
+            return
+        if not await _validate_live_async(ticket):
+            await websocket.close(code=1008, reason="session no longer valid")
+            return
+        if channel.inbound_model is None or channel.on_message is None:
+            await websocket.close(code=1008, reason="channel is server-push only")
+            return
+        try:
+            message = channel.inbound_model.model_validate_json(text)
+        except ValidationError:
+            await websocket.send_text(
+                json.dumps(
+                    {"type": "error", "code": "invalid_message"}, separators=(",", ":")
+                )
+            )
+            continue
+        await _run_inbound_handler(channel.on_message, ticket, message)
+
+
+def _raise_unexpected_task_results(results: list[object]) -> None:
+    for result in results:
+        if isinstance(result, BaseException) and not isinstance(
+            result,
+            (WebSocketDisconnect, BackpressureError, asyncio.CancelledError),
+        ):
+            raise result
+
+
+async def _settle_websocket_tasks(*tasks: asyncio.Task[None]) -> None:
+    """Run until the first task settles, then cancel and drain the rest.
+
+    The drain awaits ``asyncio.wait`` — never ``asyncio.gather``: when the
+    host task is cancelled mid-drain (server shutdown, test-portal teardown),
+    a cancelled gather re-raises the *last child's* CancelledError instead of
+    the host's own. The child's copy carries no cancel-scope message, so the
+    surrounding anyio cancel scope refuses to absorb it and the teardown
+    crashes the connection task.
+    """
+    _done, pending = await asyncio.wait(tasks, return_when=asyncio.FIRST_COMPLETED)
+    for task in pending:
+        task.cancel()
+    await asyncio.wait(tasks)
+    results: list[object] = []
+    for task in tasks:
+        if task.cancelled():
+            continue
+        exc = task.exception()
+        results.append(exc if exc is not None else task.result())
+    _raise_unexpected_task_results(results)
+
+
+@router.websocket("/ws/{channel_name}")
+async def subscribe_websocket(
+    websocket: WebSocket,
+    channel_name: str,
+    ticket: Annotated[str, Query(min_length=1, max_length=200)],
+    handshake_session: SessionDep,
+) -> None:
+    channel = get_channel(channel_name)
+    redeemed = _consume_ticket(
+        ticket, channel_name=channel_name, transport="websocket"
+    )
+    if (
+        channel is None
+        or channel.mode != "websocket"
+        or redeemed is None
+        or not await _validate_live_async(redeemed)
+    ):
+        await websocket.close(code=1008, reason="invalid connection ticket")
+        return
+    # Global guard/audit dependencies resolve one request session even for this
+    # ticket-authenticated public route. Release it before the long-lived socket;
+    # each inbound frame gets a fresh, bounded message unit of work instead.
+    handshake_session.close()
+    await websocket.accept()
+    outbound = asyncio.create_task(
+        _websocket_outbound(websocket, channel, redeemed)
+    )
+    inbound = asyncio.create_task(
+        _websocket_inbound(websocket, channel, redeemed)
+    )
+    liveness = asyncio.create_task(_websocket_liveness(websocket, redeemed))
+    await _settle_websocket_tasks(outbound, inbound, liveness)
+
+
+module = ModuleSpec(
+    name="realtime",
+    router=router,
+    # Native EventSource/WebSocket constructors cannot attach the in-memory
+    # bearer header, so the transport handshake is public at the HTTP layer
+    # and authenticates by a 30-second, single-use ticket instead. The mint
+    # endpoint self-authenticates with Depends(get_principal), then enforces
+    # the channel's typed authority. The stronger public-write declaration
+    # makes this exceptional route posture explicit and runtime-validated.
+    policy=Policy.public_write(
+        reason="realtime handshakes redeem one-use authenticated connection tickets"
+    ),
+)
+
+
+__all__ = [
+    "HEARTBEAT_SECONDS",
+    "MAX_INBOUND_BYTES",
+    "MessageSessionProvider",
+    "TICKET_TTL_SECONDS",
+    "PrincipalValidator",
+    "TicketRequest",
+    "TicketResponse",
+    "configure_realtime",
+    "module",
+    "reset_realtime_configuration",
+    "router",
+]

terp_cap_realtime-0.1.0/src/terp/capabilities/realtime/tickets.py

@@ -0,0 +1,117 @@
+"""Single-use, TTL-bounded connection tickets for browser-native transports.
+
+The Terp access token lives in React memory. Native ``EventSource`` and
+``WebSocket`` constructors cannot attach its Authorization header, and putting
+the bearer token in a URL would leak it into logs/history. The sanctioned flow
+therefore mints a short-lived opaque ticket over the generated authenticated
+client, then redeems it exactly once at the transport handshake.
+"""
+
+from __future__ import annotations
+
+import secrets
+import time
+from abc import ABC, abstractmethod
+from collections.abc import Callable
+from dataclasses import dataclass
+from threading import Lock
+
+from terp.core import Principal
+
+
+@dataclass(frozen=True)
+class ConnectionTicket:
+    """The authority captured at mint for one channel + transport handshake."""
+
+    principal: Principal
+    channel: str
+    transport: str
+    credential: str = ""
+    audience: str = ""
+
+
+class ConnectionTicketStore(ABC):
+    """Atomic issue/consume port for opaque one-use tickets."""
+
+    @abstractmethod
+    def issue(self, ticket: ConnectionTicket, *, ttl_seconds: int) -> str: ...
+
+    @abstractmethod
+    def consume(
+        self, token: str, *, channel: str, transport: str
+    ) -> ConnectionTicket | None:
+        """Atomically remove and return a live exact-match ticket, else None."""
+
+
+class InMemoryConnectionTicketStore(ConnectionTicketStore):
+    """Thread-safe per-process ticket store, TTL-expired on issue/consume."""
+
+    def __init__(self, *, clock: Callable[[], float] = time.monotonic) -> None:
+        self._clock = clock
+        self._lock = Lock()
+        self._entries: dict[str, tuple[float, ConnectionTicket]] = {}
+
+    def issue(self, ticket: ConnectionTicket, *, ttl_seconds: int) -> str:
+        if ttl_seconds <= 0:
+            raise ValueError("connection ticket ttl_seconds must be positive")
+        token = secrets.token_urlsafe(32)
+        now = self._clock()
+        with self._lock:
+            self._sweep(now)
+            self._entries[token] = (now + ttl_seconds, ticket)
+        return token
+
+    def consume(
+        self, token: str, *, channel: str, transport: str
+    ) -> ConnectionTicket | None:
+        now = self._clock()
+        with self._lock:
+            entry = self._entries.pop(token, None)
+            if entry is None:
+                return None
+            expires_at, ticket = entry
+            if expires_at <= now:
+                return None
+            # Consume even on a mismatch: a leaked ticket cannot be probed
+            # against channel names/transports and then reused correctly.
+            if ticket.channel != channel or ticket.transport != transport:
+                return None
+            return ticket
+
+    def _sweep(self, now: float) -> None:
+        expired = [key for key, (expires_at, _) in self._entries.items() if expires_at <= now]
+        for key in expired:
+            del self._entries[key]
+
+    def reset(self) -> None:
+        with self._lock:
+            self._entries.clear()
+
+
+_configured_store: ConnectionTicketStore | None = None
+_configuration_lock = Lock()
+
+
+def configure_ticket_store(store: ConnectionTicketStore | None) -> None:
+    """Install *store* process-wide (``None`` resets to the lazy default)."""
+    global _configured_store
+    with _configuration_lock:
+        _configured_store = store
+
+
+def get_ticket_store() -> ConnectionTicketStore:
+    """The configured store, creating the in-memory default lazily."""
+    global _configured_store
+    with _configuration_lock:
+        if _configured_store is None:
+            _configured_store = InMemoryConnectionTicketStore()
+        return _configured_store
+
+
+__all__ = [
+    "ConnectionTicket",
+    "ConnectionTicketStore",
+    "InMemoryConnectionTicketStore",
+    "configure_ticket_store",
+    "get_ticket_store",
+]