agora-workbench 0.1.1__tar.gz

agora_workbench-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+    MIT License
+
+    Copyright (c) Microsoft Corporation.
+
+    Permission is hereby granted, free of charge, to any person obtaining a copy
+    of this software and associated documentation files (the "Software"), to deal
+    in the Software without restriction, including without limitation the rights
+    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+    copies of the Software, and to permit persons to whom the Software is
+    furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included in all
+    copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+    SOFTWARE

agora_workbench-0.1.1/MANIFEST.in

@@ -0,0 +1,6 @@
+prune activity_ui/tests
+prune src/agora_workbench/code_execution/tests
+prune src/agora_workbench/connector/tests
+prune src/agora_workbench/deployment/tests
+global-exclude *.pyc
+global-exclude *.pyo

agora_workbench-0.1.1/PKG-INFO

@@ -0,0 +1,189 @@
+Metadata-Version: 2.4
+Name: agora-workbench
+Version: 0.1.1
+Summary: A toolkit for building MCP servers that provide sandboxed Python execution with domain-specific packages.
+License-Expression: MIT
+Project-URL: homepage, https://github.com/microsoft/agora-workbench
+Project-URL: documentation, https://microsoft.github.io/agora-workbench
+Project-URL: repository, https://github.com/microsoft/agora-workbench
+Project-URL: changelog, https://github.com/microsoft/agora-workbench/blob/main/CHANGELOG.md
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: azure-core>=1.38.0
+Requires-Dist: azure-data-tables>=12.7.0
+Requires-Dist: azure-identity>=1.25.0
+Requires-Dist: azure-search-documents>=11.4.0
+Requires-Dist: azure-storage-blob[aio]>=12.28.0
+Requires-Dist: fastapi>=0.115
+Requires-Dist: fastmcp>=2.14.2
+Requires-Dist: mcp>=1.28.1
+Requires-Dist: starlette>=1.3.1
+Requires-Dist: uvicorn>=0.34
+Requires-Dist: wsproto>=1.3.2
+Requires-Dist: cryptography>=48.0.1
+Requires-Dist: msal>=1.28.0
+Requires-Dist: pyjwt[crypto]>=2.8.0
+Requires-Dist: pandas>=2.3.3
+Requires-Dist: pyarrow>=22.0.0
+Requires-Dist: pydantic>=2.10.4
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: dill>=0.3.8
+Requires-Dist: ipykernel>=6.29.0
+Requires-Dist: jupyter-client>=8.6.0
+Requires-Dist: pyzmq>=26.0.0
+Requires-Dist: sqlite-vec>=0.1.9
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: sse-starlette>=3.3.0
+Requires-Dist: typeguard>=4.4.4
+Requires-Dist: typing-extensions>=4.12.0
+Provides-Extra: openai-agents
+Requires-Dist: openai-agents>=0.15.0; extra == "openai-agents"
+Provides-Extra: copilot-sdk
+Requires-Dist: github-copilot-sdk>=1.0.0; extra == "copilot-sdk"
+Requires-Dist: python-dotenv>=1.1.1; extra == "copilot-sdk"
+Provides-Extra: geo
+Requires-Dist: rasterio>=1.4.0; extra == "geo"
+Requires-Dist: titiler.core>=0.19.0; extra == "geo"
+Dynamic: license-file
+
+# Agora Workbench
+<p align="left">
+  <img src="logo.png" alt="Agora Workbench logo" width="250">
+</p>
+
+
+![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)
+[![MIT License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+A workbench for wrapping your tooling with MCP
+
+<h2><a href="https://microsoft.github.io/agora-workbench">Documentation</a></h2>
+
+> [!IMPORTANT]
+> **Research software and support**
+>
+> Agora Workbench is research software and is not an officially supported Microsoft product. It is provided
+> as-is and may change without notice. No support, service-level commitments, or compatibility guarantees are
+> provided. Issues and contributions are welcome, but responses, fixes, and continued maintenance are not
+> guaranteed.
+
+## Overview
+
+Agora Workbench is a toolkit for building MCP (Model Context Protocol) servers that provide sandboxed Python execution with domain-specific packages. It is agent-framework agnostic — any MCP-compatible client can take advantage of the servers created by Agora Workbench.
+
+Use Agora Workbench to:
+
+- **Wrap domain-specific Python tooling as MCP servers** — expose Python environments through isolated, session-aware execution environments that any MCP client can call
+- **Make tools discoverable** — register tools and skills in a searchable catalog so agents can find what they need by natural-language query
+- **Serve data alongside code** — attach a file catalog so agents can locate and load datasets without hardcoded paths
+- **Deploy to Azure Container Apps** — use the included Bicep templates and CLI to ship your servers with Entra ID auth and managed identity
+
+## Getting Started
+
+### Prerequisites
+
+- **Python 3.11+**
+- **Git**
+- **[uv](https://docs.astral.sh/uv/)** for dependency management
+- **Docker** (required for the bundled container examples and local Compose workflows)
+
+### Installation
+
+**With uv (recommended for development):**
+
+```bash
+git clone https://github.com/microsoft/agora-workbench.git
+cd agora-workbench
+uv sync --group dev  # install the project and dev tools
+```
+
+**With pip (for using as a library):**
+
+```bash
+pip install "agora-workbench==0.1.1"
+```
+
+The installed deployment CLI can also scaffold the standalone Activity UI:
+
+```bash
+agora-workbench-deploy init --target activity-ui
+```
+
+With uv, add the same release to your project with:
+
+```bash
+uv add "agora-workbench==0.1.1"
+```
+
+See the [changelog](https://github.com/microsoft/agora-workbench/blob/main/CHANGELOG.md) for release history and
+[release guide](https://github.com/microsoft/agora-workbench/blob/main/RELEASING.md) for the versioning policy.
+
+**Optional extras for examples** — the base package is all you need to build and run MCP servers. Extras pull in dependencies used by the example integrations:
+
+| Extra | Example integration |
+|-------|---------------------|
+| `openai-agents` | OpenAI Agents SDK adapter |
+| `copilot-sdk` | GitHub Copilot SDK adapter |
+| `geo` | Geospatial example server dependencies (rasterio, etc.) |
+
+Use the command for your installation method:
+
+```bash
+# uv (inside the cloned repo)
+uv sync --extra openai-agents
+
+# pip (consuming as a library)
+pip install "agora-workbench[openai-agents]==0.1.1"
+```
+
+### Configuration
+
+For local testing, no external credentials are required. Use the no-op auth config to skip authentication entirely:
+
+```python
+from agora_workbench.code_execution import CodeExecutionServer, ServerConfig
+from agora_workbench.code_execution.auth import create_noop_auth_config
+
+config = ServerConfig(
+    name="myserver",
+    description="My local test server",
+    type="uv",
+    dependency_file="numpy\npandas\n",
+)
+server = CodeExecutionServer(
+    server_config=config,
+    auth_config=create_noop_auth_config(),
+)
+```
+For Docker-based local deployment and Azure Container Apps, see the [deployment guide](https://microsoft.github.io/agora-workbench/guide/deploying/). For Entra ID authentication setup, see the [authentication guide](https://microsoft.github.io/agora-workbench/guide/authentication/).
+
+## Contributing
+
+This project welcomes contributions and suggestions. Most contributions require you to agree to a
+Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
+the rights to use your contribution. For details, visit [Contributor License Agreements](https://cla.opensource.microsoft.com).
+
+When you submit a pull request, a CLA bot will automatically determine whether you need to provide
+a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions
+provided by the bot. You will only need to do this once across all repos using our CLA.
+
+**Guidelines:**
+- For changes more complex than typos, please submit an issue first to discuss the proposed changes
+- Follow the development practices outlined in the project documentation
+
+### Contact
+
+For questions or feedback, please [open an issue](https://github.com/microsoft/agora-workbench/issues).
+
+This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
+For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
+contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
+
+## Trademarks
+
+This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft
+trademarks or logos is subject to and must follow
+[Microsoft's Trademark & Brand Guidelines](https://www.microsoft.com/legal/intellectualproperty/trademarks/usage/general).
+Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.
+Any use of third-party trademarks or logos are subject to those third-party's policies.

agora_workbench-0.1.1/README.md

@@ -0,0 +1,140 @@
+# Agora Workbench
+<p align="left">
+  <img src="logo.png" alt="Agora Workbench logo" width="250">
+</p>
+
+
+![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)
+[![MIT License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+A workbench for wrapping your tooling with MCP
+
+<h2><a href="https://microsoft.github.io/agora-workbench">Documentation</a></h2>
+
+> [!IMPORTANT]
+> **Research software and support**
+>
+> Agora Workbench is research software and is not an officially supported Microsoft product. It is provided
+> as-is and may change without notice. No support, service-level commitments, or compatibility guarantees are
+> provided. Issues and contributions are welcome, but responses, fixes, and continued maintenance are not
+> guaranteed.
+
+## Overview
+
+Agora Workbench is a toolkit for building MCP (Model Context Protocol) servers that provide sandboxed Python execution with domain-specific packages. It is agent-framework agnostic — any MCP-compatible client can take advantage of the servers created by Agora Workbench.
+
+Use Agora Workbench to:
+
+- **Wrap domain-specific Python tooling as MCP servers** — expose Python environments through isolated, session-aware execution environments that any MCP client can call
+- **Make tools discoverable** — register tools and skills in a searchable catalog so agents can find what they need by natural-language query
+- **Serve data alongside code** — attach a file catalog so agents can locate and load datasets without hardcoded paths
+- **Deploy to Azure Container Apps** — use the included Bicep templates and CLI to ship your servers with Entra ID auth and managed identity
+
+## Getting Started
+
+### Prerequisites
+
+- **Python 3.11+**
+- **Git**
+- **[uv](https://docs.astral.sh/uv/)** for dependency management
+- **Docker** (required for the bundled container examples and local Compose workflows)
+
+### Installation
+
+**With uv (recommended for development):**
+
+```bash
+git clone https://github.com/microsoft/agora-workbench.git
+cd agora-workbench
+uv sync --group dev  # install the project and dev tools
+```
+
+**With pip (for using as a library):**
+
+```bash
+pip install "agora-workbench==0.1.1"
+```
+
+The installed deployment CLI can also scaffold the standalone Activity UI:
+
+```bash
+agora-workbench-deploy init --target activity-ui
+```
+
+With uv, add the same release to your project with:
+
+```bash
+uv add "agora-workbench==0.1.1"
+```
+
+See the [changelog](https://github.com/microsoft/agora-workbench/blob/main/CHANGELOG.md) for release history and
+[release guide](https://github.com/microsoft/agora-workbench/blob/main/RELEASING.md) for the versioning policy.
+
+**Optional extras for examples** — the base package is all you need to build and run MCP servers. Extras pull in dependencies used by the example integrations:
+
+| Extra | Example integration |
+|-------|---------------------|
+| `openai-agents` | OpenAI Agents SDK adapter |
+| `copilot-sdk` | GitHub Copilot SDK adapter |
+| `geo` | Geospatial example server dependencies (rasterio, etc.) |
+
+Use the command for your installation method:
+
+```bash
+# uv (inside the cloned repo)
+uv sync --extra openai-agents
+
+# pip (consuming as a library)
+pip install "agora-workbench[openai-agents]==0.1.1"
+```
+
+### Configuration
+
+For local testing, no external credentials are required. Use the no-op auth config to skip authentication entirely:
+
+```python
+from agora_workbench.code_execution import CodeExecutionServer, ServerConfig
+from agora_workbench.code_execution.auth import create_noop_auth_config
+
+config = ServerConfig(
+    name="myserver",
+    description="My local test server",
+    type="uv",
+    dependency_file="numpy\npandas\n",
+)
+server = CodeExecutionServer(
+    server_config=config,
+    auth_config=create_noop_auth_config(),
+)
+```
+For Docker-based local deployment and Azure Container Apps, see the [deployment guide](https://microsoft.github.io/agora-workbench/guide/deploying/). For Entra ID authentication setup, see the [authentication guide](https://microsoft.github.io/agora-workbench/guide/authentication/).
+
+## Contributing
+
+This project welcomes contributions and suggestions. Most contributions require you to agree to a
+Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
+the rights to use your contribution. For details, visit [Contributor License Agreements](https://cla.opensource.microsoft.com).
+
+When you submit a pull request, a CLA bot will automatically determine whether you need to provide
+a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions
+provided by the bot. You will only need to do this once across all repos using our CLA.
+
+**Guidelines:**
+- For changes more complex than typos, please submit an issue first to discuss the proposed changes
+- Follow the development practices outlined in the project documentation
+
+### Contact
+
+For questions or feedback, please [open an issue](https://github.com/microsoft/agora-workbench/issues).
+
+This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
+For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
+contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
+
+## Trademarks
+
+This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft
+trademarks or logos is subject to and must follow
+[Microsoft's Trademark & Brand Guidelines](https://www.microsoft.com/legal/intellectualproperty/trademarks/usage/general).
+Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.
+Any use of third-party trademarks or logos are subject to those third-party's policies.

agora_workbench-0.1.1/activity_ui/Dockerfile

@@ -0,0 +1,21 @@
+# Activity UI sidecar — receives events from MCP servers and serves the UI.
+#
+# Build from the directory containing activity_ui/:
+#   docker build -f activity_ui/Dockerfile -t activity-ui:local .
+
+FROM mcr.microsoft.com/azurelinux/base/python:3.12
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1
+
+WORKDIR /app
+
+COPY activity_ui/requirements.txt /app/requirements.txt
+RUN pip3 install --no-input -r /app/requirements.txt
+
+COPY activity_ui /app/activity_ui
+
+EXPOSE 8030
+
+CMD ["python3", "-m", "activity_ui.server"]

agora_workbench-0.1.1/activity_ui/__init__.py

@@ -0,0 +1,5 @@
+"""Activity UI service — receives events from MCP servers and shows them to the user."""
+
+from .models import ActivityEvent
+
+__all__ = ["ActivityEvent"]

agora_workbench-0.1.1/activity_ui/auth.py

@@ -0,0 +1,298 @@
+"""App-layer authentication for Activity UI endpoints excluded from EasyAuth.
+
+Follows the same architecture as ``code_execution.auth``:
+
+- Abstract ``TokenValidator`` base class with async ``validate()`` method.
+- ``EntraTokenValidator`` for production (PyJWT + JWKS, RS256, issuer/audience).
+- ``NoOpTokenValidator`` for local development (accepts any token).
+
+POST /events is excluded from EasyAuth to allow managed-identity bearer tokens.
+The validator checks signature, issuer, audience, expiry, and the ``roles``
+claim containing ``ActivityEventWriter``.
+
+GET /stream and /events/recent use a short-lived stream token (HMAC-SHA256)
+delivered as an HttpOnly cookie. The token is minted by POST /stream-token,
+which is protected by EasyAuth (not in excludedPaths).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+import secrets
+import time
+from abc import ABC, abstractmethod
+from datetime import datetime, timezone
+
+import jwt
+from fastapi import HTTPException, Request, Response
+from jwt import PyJWKClient
+
+LOGGER = logging.getLogger(__name__)
+
+# Microsoft identity platform OIDC configuration
+_ENTRA_JWKS_URL_TEMPLATE = "https://login.microsoftonline.com/{tenant_id}/discovery/v2.0/keys"
+_ENTRA_ISSUER_TEMPLATES = [
+    "https://login.microsoftonline.com/{tenant_id}/v2.0",
+    "https://sts.windows.net/{tenant_id}/",
+]
+
+_REQUIRED_ROLE = "ActivityEventWriter"
+
+
+# ── Abstract base ────────────────────────────────────────────────────────────
+
+
+class TokenValidationError(Exception):
+    """Raised when token validation fails."""
+
+    def __init__(self, message: str, status_code: int = 401):
+        self.status_code = status_code
+        super().__init__(message)
+
+
+class TokenValidator(ABC):
+    """Validates bearer tokens from incoming requests."""
+
+    @abstractmethod
+    async def validate(self, token: str) -> dict:
+        """Validate a bearer token and return decoded claims.
+
+        Raises:
+            TokenValidationError: If the token is invalid.
+        """
+        raise NotImplementedError("Subclasses must implement validate().")
+
+
+# ── Entra ID implementation ──────────────────────────────────────────────────
+
+
+class EntraTokenValidator(TokenValidator):
+    """Validates JWTs issued by Microsoft Entra ID using PyJWT.
+
+    Fetches signing keys from the JWKS endpoint, verifies signature (RS256),
+    and validates standard claims (exp, aud, iss) plus the ``roles`` claim.
+    """
+
+    def __init__(self, client_id: str, tenant_id: str, audience: str = ""):
+        self._client_id = client_id
+        self._tenant_id = tenant_id
+        jwks_url = _ENTRA_JWKS_URL_TEMPLATE.format(tenant_id=tenant_id)
+        self._jwks_client = PyJWKClient(jwks_url, cache_keys=True)
+        # Accept multiple audience values (scoped URI, bare client ID, api:// prefix)
+        self._valid_audiences: list[str] = []
+        if audience:
+            self._valid_audiences.append(audience)
+        if client_id:
+            self._valid_audiences.append(client_id)
+            self._valid_audiences.append(f"api://{client_id}")
+        self._valid_issuers = [t.format(tenant_id=tenant_id) for t in _ENTRA_ISSUER_TEMPLATES]
+
+    async def validate(self, token: str) -> dict:
+        try:
+            signing_key = await asyncio.to_thread(self._jwks_client.get_signing_key_from_jwt, token)
+            payload = jwt.decode(
+                token,
+                signing_key.key,
+                algorithms=["RS256"],
+                audience=self._valid_audiences,
+                issuer=self._valid_issuers,
+                options={"verify_exp": True, "verify_aud": True, "verify_iss": True},
+            )
+        except jwt.ExpiredSignatureError:
+            raise TokenValidationError("Token is expired", status_code=401)
+        except jwt.InvalidAudienceError:
+            raise TokenValidationError("Token has invalid audience", status_code=401)
+        except jwt.InvalidIssuerError:
+            raise TokenValidationError("Token has invalid issuer", status_code=401)
+        except jwt.PyJWKClientError as exc:
+            LOGGER.error("JWKS key fetch failed: %s", exc)
+            raise TokenValidationError(f"Failed to fetch signing keys: {exc}", status_code=401)
+        except jwt.InvalidTokenError as exc:
+            LOGGER.warning("Token validation failed: %s", exc)
+            raise TokenValidationError(str(exc), status_code=401)
+
+        # Check roles claim (normalize to list in case of unexpected type)
+        roles = payload.get("roles", [])
+        if not isinstance(roles, list):
+            roles = [roles] if isinstance(roles, str) else []
+        if _REQUIRED_ROLE not in roles:
+            LOGGER.debug("Token missing required role %r, has: %s", _REQUIRED_ROLE, roles)
+            raise TokenValidationError(f"Missing required role: {_REQUIRED_ROLE}", status_code=403)
+
+        return payload
+
+
+# ── No-op implementation (local dev) ─────────────────────────────────────────
+
+
+class NoOpTokenValidator(TokenValidator):
+    """Accepts any bearer token without validation.
+
+    WARNING: Never use in production. Exists for local development only.
+    """
+
+    async def validate(self, token: str) -> dict:
+        LOGGER.warning("NoOpTokenValidator: accepting token without validation (development mode)")
+        # Try to decode payload for claims (no signature check)
+        try:
+            return jwt.decode(token, options={"verify_signature": False}) if token else {}
+        except jwt.PyJWTError:
+            return {}
+
+
+# ── Factory ──────────────────────────────────────────────────────────────────
+
+
+def create_token_validator() -> TokenValidator:
+    """Create the appropriate TokenValidator based on environment configuration.
+
+    Returns NoOpTokenValidator when ACTIVITY_UI_AUTH_DISABLED=true.
+    Returns EntraTokenValidator when the tenant and either the audience or
+    client ID are configured.
+    Raises RuntimeError if auth is enabled but config is incomplete.
+    """
+    if os.getenv("ACTIVITY_UI_AUTH_DISABLED", "").lower() == "true":
+        LOGGER.warning("Activity UI auth DISABLED — using NoOpTokenValidator")
+        return NoOpTokenValidator()
+
+    tenant_id = os.getenv("ENTRA_TENANT_ID", "")
+    audience = os.getenv("ACTIVITY_UI_AUDIENCE", "")
+    client_id = os.getenv("ACTIVITY_UI_CLIENT_ID", "")
+
+    if not tenant_id or not (audience or client_id):
+        raise RuntimeError(
+            "Activity UI auth is enabled but not configured. "
+            "Set ENTRA_TENANT_ID and ACTIVITY_UI_AUDIENCE/ACTIVITY_UI_CLIENT_ID, "
+            "or set ACTIVITY_UI_AUTH_DISABLED=true for local development."
+        )
+
+    return EntraTokenValidator(client_id=client_id, tenant_id=tenant_id, audience=audience)
+
+
+# ── FastAPI dependency ───────────────────────────────────────────────────────
+
+# Singleton validator created at import time. In production this fails fast
+# if auth config is missing; in local dev it returns NoOpTokenValidator.
+_validator: TokenValidator | None = None
+
+
+def _get_validator() -> TokenValidator:
+    global _validator
+    if _validator is None:
+        _validator = create_token_validator()
+    return _validator
+
+
+async def require_event_writer(request: Request) -> None:
+    """FastAPI dependency that validates bearer tokens on /events.
+
+    Raises HTTPException(401/403) on failure.
+    """
+    validator = _get_validator()
+
+    # Extract bearer token
+    auth_header = request.headers.get("Authorization", "")
+    if not auth_header.startswith("Bearer "):
+        if isinstance(validator, NoOpTokenValidator):
+            return
+        raise HTTPException(status_code=401, detail="Missing bearer token")
+
+    token = auth_header[7:]
+
+    try:
+        await validator.validate(token)
+    except TokenValidationError as exc:
+        raise HTTPException(status_code=exc.status_code, detail=str(exc))
+
+
+# ── Stream token (browser access to /stream and /events/recent) ──────────────
+
+# Server-generated secret for HMAC-signed stream tokens.
+# Rotates on restart — acceptable for short-lived tokens on single-replica.
+_STREAM_TOKEN_SECRET: str = os.getenv("ACTIVITY_UI_STREAM_SECRET", "") or secrets.token_hex(32)
+_STREAM_TOKEN_TTL_SECONDS = int(os.getenv("ACTIVITY_UI_STREAM_TOKEN_TTL", "300"))  # 5 min default
+_STREAM_TOKEN_COOKIE = "activity_stream_token"
+_STREAM_TOKEN_ALGORITHM = "HS256"
+
+
+def mint_stream_token(subject: str) -> str:
+    """Create a short-lived HMAC stream token for browser SSE access."""
+    now = time.time()
+    payload = {
+        "sub": subject,
+        "purpose": "stream",
+        "iat": int(now),
+        "exp": int(now) + _STREAM_TOKEN_TTL_SECONDS,
+    }
+    return jwt.encode(payload, _STREAM_TOKEN_SECRET, algorithm=_STREAM_TOKEN_ALGORITHM)
+
+
+def validate_stream_token(token: str) -> dict:
+    """Validate a stream token. Returns claims or raises TokenValidationError."""
+    try:
+        claims = jwt.decode(
+            token, _STREAM_TOKEN_SECRET, algorithms=[_STREAM_TOKEN_ALGORITHM], options={"require": ["exp", "iat"]}
+        )
+    except jwt.ExpiredSignatureError:
+        raise TokenValidationError("Stream token expired", status_code=401)
+    except jwt.MissingRequiredClaimError as exc:
+        raise TokenValidationError(f"Stream token missing required claim: {exc}", status_code=401)
+    except jwt.InvalidTokenError as exc:
+        raise TokenValidationError(f"Invalid stream token: {exc}", status_code=401)
+
+    if claims.get("purpose") != "stream":
+        raise TokenValidationError("Token not valid for stream access", status_code=403)
+
+    return claims
+
+
+def stream_token_expiry(token: str) -> datetime | None:
+    """Return the expiry time of a stream token (without full validation)."""
+    try:
+        claims = jwt.decode(
+            token, _STREAM_TOKEN_SECRET, algorithms=[_STREAM_TOKEN_ALGORITHM], options={"verify_exp": False}
+        )
+        exp = claims.get("exp")
+        return datetime.fromtimestamp(exp, tz=timezone.utc) if exp else None
+    except jwt.InvalidTokenError:
+        return None
+
+
+def set_stream_token_cookie(response: Response, token: str) -> None:
+    """Set the stream token as an HttpOnly, Secure, SameSite=Lax cookie."""
+    response.set_cookie(
+        key=_STREAM_TOKEN_COOKIE,
+        value=token,
+        httponly=True,
+        secure=True,
+        samesite="lax",
+        max_age=_STREAM_TOKEN_TTL_SECONDS,
+        path="/",
+    )
+
+
+async def require_stream_reader(request: Request) -> dict:
+    """FastAPI dependency that validates stream tokens on /stream and /events/recent.
+
+    Checks the stream token cookie (HttpOnly, set by POST /stream-token).
+    Falls back to query param for non-browser clients (e.g. curl for debugging).
+    Returns validated claims dict.
+
+    In NoOp mode (local dev), all requests are allowed.
+    """
+    validator = _get_validator()
+    if isinstance(validator, NoOpTokenValidator):
+        return {}
+
+    # Check cookie first, then query param fallback
+    token = request.cookies.get(_STREAM_TOKEN_COOKIE) or request.query_params.get("token")
+
+    if not token:
+        raise HTTPException(status_code=401, detail="Missing stream token")
+
+    try:
+        return validate_stream_token(token)
+    except TokenValidationError as exc:
+        raise HTTPException(status_code=exc.status_code, detail=str(exc))