create-caspian-app 0.2.0-beta.91 → 0.2.0-beta.93

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

@@ -69,8 +69,9 @@
 
 ### `main.py`
 
-- Treat `main.py` as the repo source of truth for FastAPI setup, static asset routes, auth bootstrap, middleware order, route registration, cache defaults, and error handlers.
-- Preserve the effective middleware execution order unless the task explicitly changes request semantics: `SessionMiddleware -> CSRFMiddleware -> AuthMiddleware -> RPCMiddleware`.
+- Treat `main.py` as the repo source of truth for FastAPI setup, auth bootstrap, middleware wiring, route registration, cache defaults, and error handlers.
+- When the app factors browser hardening or safe static-file behavior into app-owned helpers, treat `main.py` plus those imported helpers as the runtime source of truth together.
+- Preserve the effective middleware execution order unless the task explicitly changes request semantics: `SecurityHeadersMiddleware -> SessionMiddleware -> CSRFMiddleware -> AuthMiddleware -> RPCMiddleware`.
 - 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.
@@ -83,6 +84,7 @@
 - For file managers, keep shared storage, normalization, and Prisma-backed persistence helpers here while route-owned upload and delete `@rpc()` actions stay in `src/app/**/index.py`.
 - 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`.
+- Keep app-owned browser hardening, CSP defaults, safe static-file helpers, and production session-secret enforcement in `src/lib/security/runtime_security.py` when that module exists.
 
 ### `src/components/**/*.py`
 

package/dist/AGENTS.md

@@ -62,11 +62,11 @@ Use `.github/copilot-instructions.md` for the repo-wide implementation rules. Th
 
 - Local Caspian docs live under `node_modules/caspian-utils/dist/docs/`.
 - Workspace file instructions live under `.github/instructions/**/*.instructions.md` when the repo needs task- or library-specific AI guidance that should not be always-on.
-- Use `node_modules/caspian-utils/dist/docs/core-runtime-map.md` when a behavior is controlled by `main.py` or `.venv/Lib/site-packages/casp/**` and the owning file is not obvious yet.
+- Use `node_modules/caspian-utils/dist/docs/core-runtime-map.md` when a behavior is controlled by `main.py`, app-owned runtime helpers such as `src/lib/security/runtime_security.py`, or `.venv/Lib/site-packages/casp/**` and the owning file is not obvious yet.
 - Use `node_modules/caspian-utils/dist/docs/pulsepoint-runtime-map.md` when a behavior is controlled by the shipped PulsePoint browser runtime and the task names state, effects, refs, context, portals, directives, `pp.rpc`, uploads, streaming, SPA navigation, or scroll restoration.
 - Use `node_modules/caspian-utils/dist/docs/file-conventions.md` when the task asks what belongs in `index.html`, `index.py`, `layout.html`, `layout.py`, `loading.html`, `not-found.html`, or `error.html`.
 - 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, and `StateManager` persistence against the current `main.py` and installed `casp` package rather than copying older notes.
+- Before updating docs, verify runtime-specific claims such as middleware order, route param injection, `layout()` behavior, `StateManager` persistence, and browser security header or session-secret behavior against the current `main.py`, `src/lib/security/runtime_security.py`, and installed `casp` package rather than copying older notes.
 - When generating or reviewing `src/app/**/index.html`, `src/app/**/layout.html`, or component HTML templates, treat the single-root rule as a hard requirement: exactly one authored top-level parent element or one imported `x-*` root, with any owned `<script>` kept inside that same root. Do not allow sibling top-level tags, sibling scripts, or stray top-level text, because Caspian injects `pp-component` on that final root and errors if it cannot.
 
 ## Task Routing
@@ -78,13 +78,13 @@ If the task generates or edits route, layout, or component HTML templates, check
 - Project layout and file placement: read `node_modules/caspian-utils/dist/docs/index.md` and `node_modules/caspian-utils/dist/docs/project-structure.md`. Verify against the current workspace tree.
 - File conventions and special route files: read `node_modules/caspian-utils/dist/docs/file-conventions.md` and `node_modules/caspian-utils/dist/docs/routing.md`. Verify against `main.py`, `.venv/Lib/site-packages/casp/layout.py`, `.venv/Lib/site-packages/casp/loading.py`, and `.venv/Lib/site-packages/casp/caspian_config.py`.
 - Feature availability and tooling switches: read `caspian.config.json`. Verify against the current workspace tree, `main.py`, `prisma/**`, and `public/js/**`.
-- Framework internals and core-file lookup: read `node_modules/caspian-utils/dist/docs/core-runtime-map.md`. Verify against `main.py`, `.venv/Lib/site-packages/casp/**`, and the matching feature docs.
+- Framework internals and core-file lookup: read `node_modules/caspian-utils/dist/docs/core-runtime-map.md`. Verify against `main.py`, `src/lib/security/runtime_security.py`, `.venv/Lib/site-packages/casp/**`, and the matching feature docs.
 - PulsePoint browser runtime lookup: read `node_modules/caspian-utils/dist/docs/pulsepoint-runtime-map.md` and `node_modules/caspian-utils/dist/docs/pulsepoint.md`. Verify against `public/js/pp-reactive-v2.js`, `main.py`, `.venv/Lib/site-packages/casp/scripts_type.py`, and `.venv/Lib/site-packages/casp/components_compiler.py`.
 - Library-specific and task-specific rules: read the matching `.github/instructions/**/*.instructions.md` file. Verify against `caspian.config.json`, the current workspace tree, and the owning app and lib files.
 - MCP server layout and launch flow: read `node_modules/caspian-utils/dist/docs/mcp.md`. Verify against `settings/restart-mcp.ts`, `package.json`, and `src/lib/mcp/**`.
 - Routing, layouts, metadata: read `node_modules/caspian-utils/dist/docs/routing.md`. Verify against `main.py` and `.venv/Lib/site-packages/casp/layout.py`.
 - SPA navigation and scroll restoration: read `pulsepoint.md`, `routing.md`, and `core-runtime-map.md`. Verify against `public/js/pp-reactive-v2.js`, `src/app/**/layout.html`, and `main.py`.
-- Auth, sessions, RBAC, providers: read `node_modules/caspian-utils/dist/docs/auth.md`. Verify against `src/lib/auth/auth_config.py`, `main.py`, and `.venv/Lib/site-packages/casp/auth.py`.
+- Auth, sessions, RBAC, providers: read `node_modules/caspian-utils/dist/docs/auth.md`. Verify against `src/lib/auth/auth_config.py`, `main.py`, `src/lib/security/runtime_security.py`, and `.venv/Lib/site-packages/casp/auth.py`.
 - RPC, data loading, streaming, uploads: read `node_modules/caspian-utils/dist/docs/fetch-data.md` and `node_modules/caspian-utils/dist/docs/pulsepoint.md`. Verify against `.venv/Lib/site-packages/casp/rpc.py`, `public/js/pp-reactive-v2.js`, and `main.py`.
 - File uploads and managers: read `node_modules/caspian-utils/dist/docs/file-uploads.md` and `node_modules/caspian-utils/dist/docs/fetch-data.md`. Verify against `src/app/**`, `src/lib/**`, `prisma/**`, and `settings/bs-config.ts`.
 - Server state: read `node_modules/caspian-utils/dist/docs/state.md`. Verify against `.venv/Lib/site-packages/casp/state_manager.py` and `main.py`.

package/dist/main.py

@@ -3,7 +3,6 @@ from casp.scripts_type import transform_scripts
 import inspect
 import os
 import importlib.util
-import mimetypes
 import secrets
 import traceback
 import json
@@ -39,6 +38,12 @@ from casp.streaming import SSE
 from typing import Any, Optional, get_args, get_origin, Union
 from urllib.parse import urlparse
 from src.lib.auth.auth_config import build_auth_settings
+from src.lib.security.runtime_security import (
+    build_security_headers,
+    client_error_message,
+    get_session_secret,
+    public_file_response,
+)
 
 load_dotenv()
 cfg = get_config()
@@ -76,89 +81,18 @@ MAX_CONTENT_LENGTH_MB = int(os.getenv('MAX_CONTENT_LENGTH_MB', 16))
 IS_PRODUCTION = os.getenv('APP_ENV') == 'production'
 CACHE_ENABLED = os.getenv('CACHE_ENABLED', 'false').lower() == 'true'
 DEFAULT_TTL = int(os.getenv('CACHE_TTL', 600))
-INSECURE_SESSION_SECRET_VALUES = {"", "change-me", "changeme"}
-
-
-def _resolve_safe_public_path(base_dir: str | Path, relative_path: str) -> Optional[Path]:
-    base_path = Path(base_dir).resolve()
-    try:
-        candidate = (base_path / relative_path).resolve()
-        candidate.relative_to(base_path)
-    except (OSError, RuntimeError, ValueError):
-        return None
-
-    if not candidate.is_file():
-        return None
-
-    return candidate
-
-
-def _public_file_response(
-    base_dir: str | Path,
-    relative_path: str,
-    *,
-    media_type: Optional[str] = None,
-) -> Response:
-    file_path = _resolve_safe_public_path(base_dir, relative_path)
-    if file_path is None:
-        return Response(status_code=404)
-
-    resolved_media_type = media_type
-    if resolved_media_type is None:
-        resolved_media_type, _ = mimetypes.guess_type(str(file_path))
-
-    return FileResponse(
-        file_path,
-        media_type=resolved_media_type or 'application/octet-stream',
-    )
 
 
 def _client_error_message(exc: Exception) -> str:
-    return str(exc) if not IS_PRODUCTION else 'An unexpected error occurred.'
+    return client_error_message(exc, is_production=IS_PRODUCTION)
 
 
 def _get_session_secret() -> str:
-    session_secret = (os.getenv("AUTH_SECRET") or "").strip()
-    if session_secret and session_secret.lower() not in INSECURE_SESSION_SECRET_VALUES:
-        return session_secret
-
-    if not IS_PRODUCTION:
-        return "change-me"
-
-    raise RuntimeError(
-        "AUTH_SECRET must be set to a non-default value when APP_ENV=production."
-    )
-
-
-def _build_content_security_policy() -> str:
-    # PulsePoint currently relies on inline scripts/styles and runtime codegen,
-    # so this policy tightens source scope without breaking the app runtime.
-    directives = [
-        "default-src 'self'",
-        "base-uri 'self'",
-        "object-src 'none'",
-        "frame-ancestors 'self'",
-        "form-action 'self'",
-        "img-src 'self' data: blob:",
-        "font-src 'self' data:",
-        "connect-src 'self'",
-        "script-src 'self' 'unsafe-inline' 'unsafe-eval'",
-        "style-src 'self' 'unsafe-inline'",
-    ]
-    return "; ".join(directives)
+    return get_session_secret(is_production=IS_PRODUCTION)
 
 
 def _build_security_headers() -> dict[str, str]:
-    headers = {
-        "content-security-policy": _build_content_security_policy(),
-        "permissions-policy": "camera=(), geolocation=(), microphone=(), payment=(), usb=()",
-        "referrer-policy": "strict-origin-when-cross-origin",
-        "x-content-type-options": "nosniff",
-        "x-frame-options": "SAMEORIGIN",
-    }
-    if IS_PRODUCTION:
-        headers["strict-transport-security"] = "max-age=31536000; includeSubDomains"
-    return headers
+    return build_security_headers(is_production=IS_PRODUCTION)
 
 
 def _dev_cookie_scope() -> str:
@@ -204,12 +138,12 @@ SESSION_COOKIE_NAME = _scoped_cookie_name(
 
 @app.get('/css/{filename:path}')
 async def serve_css(filename: str):
-    return _public_file_response('public/css', filename, media_type='text/css')
+    return public_file_response('public/css', filename, media_type='text/css')
 
 
 @app.get('/js/{filename:path}')
 async def serve_js(filename: str):
-    return _public_file_response(
+    return public_file_response(
         'public/js',
         filename,
         media_type='application/javascript',
@@ -218,12 +152,12 @@ async def serve_js(filename: str):
 
 @app.get('/assets/{filename:path}')
 async def serve_assets(filename: str):
-    return _public_file_response('public/assets', filename)
+    return public_file_response('public/assets', filename)
 
 
 @app.get('/uploads/{filename:path}')
 async def serve_uploads(filename: str):
-    return _public_file_response('public/uploads', filename)
+    return public_file_response('public/uploads', filename)
 
 
 @app.get('/favicon.ico')

package/dist/src/lib/security/runtime_security.py

@@ -0,0 +1,164 @@
+import mimetypes
+import os
+from pathlib import Path
+from typing import Any, Optional
+
+from fastapi import Response
+from fastapi.responses import FileResponse
+
+INSECURE_SESSION_SECRET_VALUES = {"", "change-me", "changeme"}
+GOOGLE_FONTS_STYLES_ORIGIN = "https://fonts.googleapis.com"
+GOOGLE_FONTS_ASSETS_ORIGIN = "https://fonts.gstatic.com"
+GOOGLE_ACCOUNTS_ORIGIN = "https://accounts.google.com"
+GOOGLE_OAUTH_API_ORIGIN = "https://oauth2.googleapis.com"
+
+DEFAULT_CSP_DIRECTIVES: tuple[tuple[str, list[str]], ...] = (
+    ("default-src", ["'self'"]),
+    ("base-uri", ["'self'"]),
+    ("object-src", ["'none'"]),
+    ("frame-ancestors", ["'self'"]),
+    ("form-action", ["'self'"]),
+    ("img-src", ["'self'", "data:", "blob:", GOOGLE_ACCOUNTS_ORIGIN]),
+    ("font-src", ["'self'", "data:", GOOGLE_FONTS_ASSETS_ORIGIN]),
+    ("connect-src", ["'self'", GOOGLE_ACCOUNTS_ORIGIN,
+     GOOGLE_OAUTH_API_ORIGIN]),
+    ("frame-src", ["'self'", GOOGLE_ACCOUNTS_ORIGIN]),
+    ("script-src", ["'self'", "'unsafe-inline'", "'unsafe-eval'"]),
+    ("script-src-elem", ["'self'", "'unsafe-inline'", GOOGLE_ACCOUNTS_ORIGIN]),
+    ("style-src", ["'self'", "'unsafe-inline'", GOOGLE_FONTS_STYLES_ORIGIN]),
+    ("style-src-elem", ["'self'", "'unsafe-inline'",
+     GOOGLE_FONTS_STYLES_ORIGIN]),
+)
+
+# Add project-specific browser-side origins here only when the browser must
+# load a third-party resource that is not already covered by the defaults.
+# Example:
+# PROJECT_CSP_EXTRA_SOURCES = {
+#     "script-src-elem": ["https://cdn.jsdelivr.net"],
+#     "connect-src": ["https://api.example.com"],
+# }
+PROJECT_CSP_EXTRA_SOURCES: dict[str, Any] = {}
+
+
+def resolve_safe_public_path(base_dir: str | Path, relative_path: str) -> Optional[Path]:
+    base_path = Path(base_dir).resolve()
+    try:
+        candidate = (base_path / relative_path).resolve()
+        candidate.relative_to(base_path)
+    except (OSError, RuntimeError, ValueError):
+        return None
+
+    if not candidate.is_file():
+        return None
+
+    return candidate
+
+
+def public_file_response(
+    base_dir: str | Path,
+    relative_path: str,
+    *,
+    media_type: Optional[str] = None,
+) -> Response:
+    file_path = resolve_safe_public_path(base_dir, relative_path)
+    if file_path is None:
+        return Response(status_code=404)
+
+    resolved_media_type = media_type
+    if resolved_media_type is None:
+        resolved_media_type, _ = mimetypes.guess_type(str(file_path))
+
+    return FileResponse(
+        file_path,
+        media_type=resolved_media_type or "application/octet-stream",
+    )
+
+
+def client_error_message(exc: Exception, *, is_production: bool) -> str:
+    return str(exc) if not is_production else "An unexpected error occurred."
+
+
+def get_session_secret(*, is_production: bool) -> str:
+    session_secret = (os.getenv("AUTH_SECRET") or "").strip()
+    if session_secret and session_secret.lower() not in INSECURE_SESSION_SECRET_VALUES:
+        return session_secret
+
+    if not is_production:
+        return "change-me"
+
+    raise RuntimeError(
+        "AUTH_SECRET must be set to a non-default value when APP_ENV=production."
+    )
+
+
+def _normalize_csp_sources(value: Any) -> list[str]:
+    if isinstance(value, str):
+        return [token.strip() for token in value.replace(",", " ").split() if token.strip()]
+
+    if isinstance(value, (list, tuple, set)):
+        normalized: list[str] = []
+        for item in value:
+            normalized.extend(_normalize_csp_sources(item))
+        return normalized
+
+    return []
+
+
+def normalize_csp_extra_sources(parsed: Optional[dict[str, Any]]) -> dict[str, list[str]]:
+    if not isinstance(parsed, dict):
+        return {}
+
+    normalized: dict[str, list[str]] = {}
+    for directive, sources in parsed.items():
+        if not isinstance(directive, str):
+            continue
+
+        directive_sources = _normalize_csp_sources(sources)
+        if directive_sources:
+            normalized[directive.strip()] = directive_sources
+
+    return normalized
+
+
+def _merge_sources(*groups: list[str]) -> list[str]:
+    merged: list[str] = []
+    seen: set[str] = set()
+
+    for group in groups:
+        for source in group:
+            normalized = source.strip()
+            if not normalized or normalized in seen:
+                continue
+            merged.append(normalized)
+            seen.add(normalized)
+
+    return merged
+
+
+def build_content_security_policy() -> str:
+    # PulsePoint currently relies on inline scripts/styles and runtime codegen,
+    # so this policy narrows source scope without breaking the app runtime.
+    extra_sources = normalize_csp_extra_sources(PROJECT_CSP_EXTRA_SOURCES)
+    directives: list[str] = []
+
+    for name, defaults in DEFAULT_CSP_DIRECTIVES:
+        sources = _merge_sources(
+            defaults,
+            extra_sources.get(name, []),
+        )
+        directives.append(f"{name} {' '.join(sources)}")
+
+    return "; ".join(directives)
+
+
+def build_security_headers(*, is_production: bool) -> dict[str, str]:
+    headers = {
+        "content-security-policy": build_content_security_policy(),
+        "permissions-policy": "camera=(), geolocation=(), microphone=(), payment=(), usb=()",
+        "referrer-policy": "strict-origin-when-cross-origin",
+        "x-content-type-options": "nosniff",
+        "x-frame-options": "SAMEORIGIN",
+    }
+    if is_production:
+        headers["strict-transport-security"] = "max-age=31536000; includeSubDomains"
+    return headers

package/package.json

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