create-caspian-app 0.4.0-rc.0 → 0.4.0-rc.2

package/dist/.github/copilot-instructions.md

@@ -101,7 +101,8 @@ This is the top architectural requirement for this workspace. Treat it as a hard
 - Do not move normal file upload or file-manager behavior into `main.py`; keep those actions in the owning route `index.py` and shared helpers in `src/lib/**`.
 - Document route param behavior exactly as implemented here.
 - Do not use `main.py` alone to infer whether optional features are enabled; confirm that in `caspian.config.json` first.
-- Before changing WebSocket behavior, verify `cfg.websocket`, the app's endpoint registration, origin allow-list logic, session/auth checks, idle timeout, maximum message size, close codes, and connection cleanup. HTTP-only middleware does not automatically protect `scope["type"] == "websocket"` connections.
+- Before changing WebSocket behavior, verify `cfg.websocket`, the app's endpoint registration, the `authorize_websocket(...)` guard in `src/lib/websocket/websocket_security.py`, idle timeout, maximum message size, close codes, and connection cleanup. HTTP-only middleware does not automatically protect `scope["type"] == "websocket"` connections, so socket auth lives in that guard, not `AuthMiddleware`.
+- Authorize sockets with the single `authorize_websocket(...)` guard, which runs the origin check then delegates to Caspian `Auth` (`Auth.set_request(websocket)` + `is_authenticated`/`get_payload`/`check_role`). Add channels by calling that guard with `require_auth=`/`roles=`; do not re-implement session/`exp`/payload parsing per endpoint. Keep authenticated and guest broadcast pools separate, and treat the socket session as read-only.
 
 ### `src/lib/**/*.py`
 
@@ -112,7 +113,7 @@ This is the top architectural requirement for this workspace. Treat it as a hard
 - When `caspian.config.json` has `mcp: true`, keep app-owned MCP tools in `src/lib/mcp/mcp_server.py` and keep the default FastMCP config in `src/lib/mcp/fastmcp.json`. If those locations change, update `settings/restart-mcp.ts` and the MCP docs together.
 - Keep auth policy in `src/lib/auth/auth_config.py`. Keep auth bootstrap and middleware order changes in `main.py`.
 - Do not recreate or customize `src/lib/security/runtime_security.py` for normal application work. Runtime security helpers are package-owned in `casp.runtime_security`; app-specific policy should live in app-owned config or route/helper code instead.
-- Keep reusable WebSocket helpers under `src/lib/websocket/**` when they are shared across socket endpoints or route clients. Common shared helpers include session extraction, authenticated payload checks, origin utilities, connection managers, payload normalization, and broadcast fan-out.
+- Keep reusable WebSocket helpers under `src/lib/websocket/**` when they are shared across socket endpoints or route clients. Common shared helpers include the `authorize_websocket(...)` guard (origin + `Auth`-delegated auth), origin utilities, connection managers, payload normalization, and broadcast fan-out.
 
 ### `src/components/**/*.py`
 

package/dist/AGENTS.md

@@ -74,7 +74,8 @@ Use `.github/copilot-instructions.md` for the repo-wide implementation rules. Th
 - When `caspian.config.json` has `websocket: true`, WebSocket behavior is app-owned in `main.py`. Do not assume fixed route names or endpoint paths across Caspian projects; define project-specific socket paths in the app, keep shared socket helpers in `src/lib/websocket/**` when needed, and let each route that needs a socket client pass its own `websocket_path` or `websocket_url` into its template.
 - WebSocket pages may be public, authenticated, role-gated, or mixed depending on the app. Keep route-specific browser UI in that route's `src/app/**/index.html`, keep first-render socket URL/path values in the matching `index.py`, and keep reusable session/auth/connection/broadcast helpers out of route files only when they are shared.
 - For WebSocket clients, use PulsePoint for component state and lifecycle but native `new WebSocket(...)` for the transport. Keep the socket in `pp.ref(...)`, close it in a cleanup effect, and keep direct socket event listeners inside the owning route template script.
-- Before changing socket security, verify the app's origin allow-list logic, session extraction, authenticated payload checks, idle timeout, message-size limits, and close codes in the running code. HTTP route privacy and `AuthMiddleware` do not by themselves protect WebSocket scopes.
+- Before changing socket security, verify the app's origin allow-list logic, auth check, idle timeout, message-size limits, and close codes in the running code. HTTP route privacy and `AuthMiddleware` do not by themselves protect WebSocket scopes: the HTTP middleware stack early-returns on `scope["type"] == "websocket"`, so only `SessionMiddleware` runs and each socket endpoint must authorize itself.
+- Socket authorization in this workspace is a single guard, `authorize_websocket(...)` in `src/lib/websocket/websocket_security.py`, that runs the origin check then delegates auth to Caspian's `Auth` (`Auth.set_request(websocket)` plus `is_authenticated`/`get_payload`/`check_role`). Reuse that guard for new channels and gate them with `require_auth=` / `roles=`; do not re-implement session/`exp`/payload parsing per endpoint. Keep authenticated and guest traffic in separate broadcast pools, and treat the socket session as read-only (mutations are not persisted to the cookie over a WebSocket).
 - Keep route-specific backend logic in that route's `src/app/**/index.py`, including first-render data loading, route-owned `@rpc()` actions, auth checks, redirects, and validation. Move logic to `src/lib/**` only when it is shared by more than one route, feature, component, or integration.
 - For grouped-subtree SPA navigation UX, the current browser runtime keeps unmarked shell scrollers stable and uses `pp-reset-scroll="true"` on the content pane that should reset. Check `pulsepoint.md`, `routing.md`, and `public/js/pp-reactive-v2.js` before changing that behavior.
 - Before updating docs, verify runtime-specific claims such as middleware order, route param injection, `layout()` behavior, `StateManager` persistence, safe public-file serving, response header, or session-secret behavior against the current `main.py` and installed `casp` package, especially `.venv/Lib/site-packages/casp/runtime_security.py`, rather than copying older notes.

package/dist/main.py

@@ -19,6 +19,8 @@ from fastapi import (
 )
 from fastapi.responses import RedirectResponse, FileResponse, HTMLResponse
 from starlette.datastructures import MutableHeaders
+from starlette.middleware import Middleware
+from starlette.middleware.cors import CORSMiddleware
 from starlette.middleware.sessions import SessionMiddleware
 from starlette.types import ASGIApp, Receive, Scope, Send
 from starlette.exceptions import HTTPException as StarletteHTTPException
@@ -57,6 +59,78 @@ from casp.runtime_security import (
 load_dotenv()
 cfg = get_config()
 
+# ====
+# CORS configuration (shared .env convention, mirrors casp.rpc origin checks)
+# ====
+
+
+def _csv_env(name: str) -> list[str]:
+    return [item.strip() for item in os.getenv(name, "").split(",") if item.strip()]
+
+
+def _bool_env(name: str, default: bool = False) -> bool:
+    raw = os.getenv(name)
+    if raw is None:
+        return default
+    return raw.strip().lower() in {"1", "true", "yes", "on"}
+
+
+def _configured_cors_origins() -> list[str]:
+    """Browser origins allowed to call the app, per the .env convention."""
+    origins: list[str] = []
+    for raw in (*_csv_env("CORS_ALLOWED_ORIGINS"), os.getenv("APP_BASE_URL", "")):
+        value = (raw or "").strip().rstrip("/")
+        if value and value not in origins:
+            origins.append(value)
+    return origins
+
+
+def _build_mcp_cors_middleware() -> "Middleware":
+    """Build the MCP CORS layer from .env, adding MCP-required headers.
+
+    Browser MCP clients (e.g. MCP Inspector "Direct") send an OPTIONS preflight
+    and rely on the mcp-session-id / mcp-protocol-version headers, which are not
+    in the generic CORS_ALLOWED_HEADERS list, so they are merged in here.
+    """
+    origins = _configured_cors_origins()
+    allow_credentials = _bool_env("CORS_ALLOW_CREDENTIALS")
+
+    if not origins:
+        # The CORS spec forbids "*" together with credentials, so when no
+        # explicit origin is configured fall back to open + no credentials.
+        origins = ["*"]
+        allow_credentials = False
+
+    methods = _csv_env("CORS_ALLOWED_METHODS") or [
+        "GET", "POST", "DELETE", "OPTIONS"]
+
+    headers = _csv_env("CORS_ALLOWED_HEADERS")
+    for required in ("Content-Type", "Accept", "Authorization",
+                     "mcp-session-id", "mcp-protocol-version"):
+        if required.lower() not in {h.lower() for h in headers}:
+            headers.append(required)
+
+    expose = _csv_env("CORS_EXPOSE_HEADERS")
+    for required in ("mcp-session-id", "mcp-protocol-version"):
+        if required.lower() not in {h.lower() for h in expose}:
+            expose.append(required)
+
+    try:
+        max_age = int(os.getenv("CORS_MAX_AGE", "600"))
+    except ValueError:
+        max_age = 600
+
+    return Middleware(
+        CORSMiddleware,
+        allow_origins=origins,
+        allow_credentials=allow_credentials,
+        allow_methods=methods,
+        allow_headers=headers,
+        expose_headers=expose,
+        max_age=max_age,
+    )
+
+
 # ====
 # MCP SERVER (mounted into this app so one deploy serves web + MCP)
 # ====
@@ -66,7 +140,7 @@ if cfg.mcp:
     # caspian.config.json, so suppress the static "module not found" check.
     from src.lib.mcp.mcp_server import mcp  # type: ignore[import-not-found]
     # Inner path "/" so the mount prefix below is the full endpoint path.
-    mcp_app = mcp.http_app(path="/")
+    mcp_app = mcp.http_app(path="/", middleware=[_build_mcp_cors_middleware()])
 
 # ====
 # AUTH CONFIGURATION (App behavior - customize here)
@@ -108,6 +182,11 @@ REQUEST_TIMEOUT_SECONDS = max(
     1.0,
     float(os.getenv('CASPIAN_REQUEST_TIMEOUT_SECONDS', 20)),
 )
+# Path prefixes that serve long-lived streaming responses (SSE, etc.) and must
+# not be subject to the per-request timeout. The MCP streamable-HTTP transport
+# keeps GET /mcp/ open indefinitely; wrapping it in asyncio.wait_for cancels the
+# stream mid-response and corrupts the ASGI message sequence.
+STREAMING_PATH_PREFIXES = ('/mcp',)
 MAX_CONTENT_LENGTH_BYTES = max(1, MAX_CONTENT_LENGTH_MB) * 1024 * 1024
 
 
@@ -412,6 +491,12 @@ class RequestDiagnosticsMiddleware:
         if should_log and not IS_PRODUCTION:
             print(f"[request:start] {method} {path}", flush=True)
 
+        # Long-lived streaming endpoints (MCP SSE) must bypass the timeout, or
+        # asyncio.wait_for cancels the stream and the ASGI send sequence breaks.
+        if path.startswith(STREAMING_PATH_PREFIXES):
+            await self.app(scope, receive, send)
+            return
+
         try:
             await asyncio.wait_for(
                 self.app(scope, receive, send),
@@ -462,48 +547,6 @@ MAX_WEBSOCKET_MESSAGE_BYTES = max(
 )
 
 
-def _normalized_origin(value: str) -> str:
-    return (value or "").strip().rstrip("/")
-
-
-def _configured_websocket_origins() -> set[str]:
-    raw_values = []
-    for env_name in (
-        "WEBSOCKET_ALLOWED_ORIGINS",
-        "CORS_ALLOWED_ORIGINS",
-        "APP_BASE_URL",
-    ):
-        raw_values.extend(os.getenv(env_name, "").split(","))
-
-    return {
-        _normalized_origin(origin)
-        for origin in raw_values
-        if _normalized_origin(origin)
-    }
-
-
-def _websocket_same_origin(websocket: WebSocket) -> str:
-    scheme = "https" if websocket.url.scheme == "wss" else "http"
-    return _normalized_origin(f"{scheme}://{websocket.url.netloc}")
-
-
-def _is_websocket_origin_allowed(websocket: WebSocket) -> bool:
-    origin = _normalized_origin(websocket.headers.get("origin", ""))
-    if not origin:
-        return not IS_PRODUCTION
-
-    parsed_origin = urlparse(origin)
-    if not parsed_origin.scheme or not parsed_origin.netloc:
-        return False
-
-    if not IS_PRODUCTION and parsed_origin.hostname in {"localhost", "127.0.0.1"}:
-        return parsed_origin.scheme == "http"
-
-    allowed_origins = _configured_websocket_origins()
-    allowed_origins.add(_websocket_same_origin(websocket))
-    return origin in allowed_origins
-
-
 async def _run_websocket_channel(
     websocket: WebSocket,
     manager: Any,
@@ -581,30 +624,20 @@ if cfg.websocket:
     # Optional, feature-gated module: only generated when websocket is enabled
     # in caspian.config.json, so suppress the static "module not found" check.
     from src.lib.websocket.websocket_security import (  # type: ignore[import-not-found]
-        get_authenticated_payload_from_session,
-        get_websocket_session,
+        authorize_websocket,
         public_websocket_connections,
         websocket_connections,
     )
 
+    # Both endpoints share ONE guard (`authorize_websocket`) that delegates to
+    # Caspian's `Auth`, and ONE transport loop (`_run_websocket_channel`). They
+    # differ only by auth policy and broadcast pool. To role-gate a channel,
+    # pass `roles=[...]`; to add another channel, add an endpoint that calls the
+    # same guard.
+
     @app.websocket(WEBSOCKET_PATH)
     async def websocket_live_endpoint(websocket: WebSocket):
-        if not _is_websocket_origin_allowed(websocket):
-            await websocket.close(code=status.WS_1008_POLICY_VIOLATION)
-            return
-
-        session = get_websocket_session(websocket)
-        user_payload = get_authenticated_payload_from_session(
-            session,
-            Auth.get_instance(),
-        )
-        if user_payload is None:
-            await websocket.accept()
-            await websocket.send_json({
-                "type": "error",
-                "message": "Authentication required.",
-            })
-            await websocket.close(code=status.WS_1008_POLICY_VIOLATION)
+        if await authorize_websocket(websocket, require_auth=True) is None:
             return
 
         await _run_websocket_channel(
@@ -616,8 +649,7 @@ if cfg.websocket:
 
     @app.websocket(PUBLIC_WEBSOCKET_PATH)
     async def websocket_public_endpoint(websocket: WebSocket):
-        if not _is_websocket_origin_allowed(websocket):
-            await websocket.close(code=status.WS_1008_POLICY_VIOLATION)
+        if await authorize_websocket(websocket, require_auth=False) is None:
             return
 
         await _run_websocket_channel(

package/dist/src/lib/mcp/mcp_server.py

@@ -14,13 +14,13 @@ FILES_LIST_PATH = PROJECT_ROOT / "settings" / "files-list.json"
 COMPONENT_MAP_PATH = PROJECT_ROOT / "settings" / "component-map.json"
 
 
-mcp = FastMCP(
-    name="Caspian MCP",
-    instructions=(
-        "Read-only workspace metadata for the Caspian application. "
-        "Use these tools for project configuration, generated file inventory, and component discovery."
-    ),
-)
+mcp = FastMCP(
+    name="Caspian MCP",
+    instructions=(
+        "Read-only workspace metadata for the Caspian application. "
+        "Use these tools for project configuration, generated file inventory, and component discovery."
+    ),
+)
 
 
 def _load_json(path: Path, fallback: Any) -> Any:
@@ -88,4 +88,4 @@ def component_inventory() -> dict[str, Any]:
     return {
         "count": len(components),
         "components": components,
-    }
+    }

package/dist/src/lib/websocket/websocket_security.py

@@ -1,60 +1,130 @@
 from __future__ import annotations
 
-from collections.abc import MutableMapping
-from datetime import datetime, timezone
+import os
 from typing import Any
+from urllib.parse import urlparse
 
-from fastapi import WebSocket
+from fastapi import WebSocket, status
 
+from casp.auth import Auth
 
-def get_websocket_session(websocket: WebSocket) -> MutableMapping[str, Any]:
-    session = getattr(websocket, "session", None)
-    if isinstance(session, MutableMapping):
-        return session
+# ====
+# WebSocket security: ONE guard that reuses Caspian's `Auth` as the source of
+# truth, so socket auth lines up with HTTP route auth instead of duplicating it.
+#
+# Why this lives here and not in `AuthMiddleware`:
+# HTTP middleware in `main.py` early-returns on every non-`http` scope, so a
+# WebSocket handshake (`scope["type"] == "websocket"`) is never seen by
+# `AuthMiddleware`. Each socket endpoint must therefore authorize itself. We do
+# that by delegating to the same `Auth` instance that powers page privacy.
+# ====
 
-    scope_session = websocket.scope.get("session")
-    if isinstance(scope_session, MutableMapping):
-        return scope_session
 
-    return {}
+def _is_production() -> bool:
+    return os.getenv("APP_ENV") == "production"
 
 
-def get_authenticated_payload_from_session(
-    session: MutableMapping[str, Any],
-    auth_instance: Any,
-) -> dict[str, Any] | None:
-    payload_key = getattr(auth_instance, "PAYLOAD_SESSION_KEY", "")
-    payload_name = getattr(auth_instance, "PAYLOAD_NAME", "")
+def _normalized_origin(value: str) -> str:
+    return (value or "").strip().rstrip("/")
+
+
+def _configured_websocket_origins() -> set[str]:
+    raw_values: list[str] = []
+    for env_name in (
+        "WEBSOCKET_ALLOWED_ORIGINS",
+        "CORS_ALLOWED_ORIGINS",
+        "APP_BASE_URL",
+    ):
+        raw_values.extend(os.getenv(env_name, "").split(","))
+
+    return {
+        _normalized_origin(origin)
+        for origin in raw_values
+        if _normalized_origin(origin)
+    }
+
+
+def _websocket_same_origin(websocket: WebSocket) -> str:
+    scheme = "https" if websocket.url.scheme == "wss" else "http"
+    return _normalized_origin(f"{scheme}://{websocket.url.netloc}")
+
+
+def is_websocket_origin_allowed(websocket: WebSocket) -> bool:
+    """Anti-CSWSH origin check. NOT authentication.
+
+    A browser cannot forge the `Origin` header, so this blocks cross-site
+    script-driven handshakes. A raw client (wscat, python websockets) can send
+    any origin, which is exactly why authentication is a separate gate.
+    """
+    origin = _normalized_origin(websocket.headers.get("origin", ""))
+    if not origin:
+        # No Origin header: tolerate local tooling in dev, reject in production.
+        return not _is_production()
 
-    payload_wrapper = session.get(payload_key)
-    if not isinstance(payload_wrapper, dict):
+    parsed_origin = urlparse(origin)
+    if not parsed_origin.scheme or not parsed_origin.netloc:
+        return False
+
+    if not _is_production() and parsed_origin.hostname in {"localhost", "127.0.0.1"}:
+        return parsed_origin.scheme == "http"
+
+    allowed_origins = _configured_websocket_origins()
+    allowed_origins.add(_websocket_same_origin(websocket))
+    return origin in allowed_origins
+
+
+async def authorize_websocket(
+    websocket: WebSocket,
+    *,
+    require_auth: bool,
+    roles: list[str] | None = None,
+) -> dict[str, Any] | None:
+    """Single entry point for socket authorization.
+
+    Returns the connecting identity on success, or `None` after closing the
+    socket on failure. The return value gates the connection only; do not echo
+    it to other clients (it may contain the authenticated user's payload).
+
+    - `require_auth=True`  -> authenticated session required, else close 1008.
+    - `require_auth=False` -> guests allowed; authenticated users keep identity.
+    - `roles`              -> RBAC via `Auth.check_role`, same rule as HTTP routes.
+
+    Auth is read from the session cookie that `SessionMiddleware` (the one
+    middleware that runs on websocket scopes) exposes as `websocket.session`.
+    Treat this as read-only: session writes are not persisted back to the cookie
+    over a WebSocket, so this guard must not rely on `refresh_session`.
+    """
+    # 1. Origin / CSWSH check runs before accept so rejected handshakes never
+    #    upgrade.
+    if not is_websocket_origin_allowed(websocket):
+        await websocket.close(code=status.WS_1008_POLICY_VIOLATION)
         return None
 
-    exp = payload_wrapper.get("exp")
-    if exp is not None:
-        try:
-            if float(exp) < datetime.now(timezone.utc).timestamp():
-                session.pop(payload_key, None)
-                return None
-        except Exception:
-            session.pop(payload_key, None)
+    # 2. Reuse Caspian `Auth` as the single source of truth. `Auth` only reads
+    #    `request.session`, and a WebSocket exposes `.session`, so binding the
+    #    socket as the request context lets us reuse the exact HTTP auth logic.
+    Auth.set_request(websocket)  # type: ignore[arg-type]
+    auth = Auth.get_instance()
+
+    if auth.is_authenticated():
+        payload = auth.get_payload() or {}
+        if roles and not auth.check_role(payload, roles):
+            await _reject(websocket, "Forbidden.")
             return None
+        return payload
 
-    payload = payload_wrapper.get(payload_name)
-    if payload is None:
-        session.pop(payload_key, None)
+    if require_auth:
+        await _reject(websocket, "Authentication required.")
         return None
 
-    if isinstance(payload, dict):
-        if getattr(getattr(auth_instance, "settings", None), "token_auto_refresh", False):
-            refreshed_wrapper = dict(payload_wrapper)
-            refreshed_wrapper["exp"] = auth_instance._calculate_expiration(
-                auth_instance.settings.default_token_validity
-            )
-            session[payload_key] = refreshed_wrapper
-        return payload
+    return {"guest": True, "scope": "public"}
+
 
-    return {"value": payload}
+async def _reject(websocket: WebSocket, message: str) -> None:
+    """Accept, surface a JSON error so the browser UI can react, then close."""
+    await websocket.accept()
+    await websocket.send_json({"type": "error", "message": message})
+    await websocket.close(code=status.WS_1008_POLICY_VIOLATION)
 
 
 class WebSocketConnectionManager:
@@ -80,5 +150,7 @@ class WebSocketConnectionManager:
             self.disconnect(websocket)
 
 
-websocket_connections = WebSocketConnectionManager()
-public_websocket_connections = WebSocketConnectionManager()
+# Separate pools keep authenticated traffic isolated from guest traffic, so a
+# private broadcast can never fan out to a public (guest) connection.
+websocket_connections = WebSocketConnectionManager()
+public_websocket_connections = WebSocketConnectionManager()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-caspian-app",
-  "version": "0.4.0-rc.0",
+  "version": "0.4.0-rc.2",
   "description": "Scaffold a new Caspian project (FastAPI-powered reactive Python framework).",
   "main": "dist/index.js",
   "type": "module",