caspian-utils 0.0.30 → 0.0.32

package/dist/docs/auth.md

@@ -165,8 +165,9 @@ return AuthSettings(
 
 The installed auth code reads several values from `.env` when explicit values are not passed.
 
-- `AUTH_SECRET` backs `AuthSettings.secret_key`.
-- `AUTH_COOKIE_NAME` backs `AuthSettings.cookie_name`.
+- `AUTH_SECRET` backs `AuthSettings.secret_key`.
+- App-owned startup helpers may also validate `AUTH_SECRET` and refuse production startup when the value is missing or still on a default placeholder.
+- `AUTH_COOKIE_NAME` backs `AuthSettings.cookie_name`.
 - `SESSION_LIFETIME_HOURS` controls `SessionMiddleware.max_age` in the current `main.py` bootstrap.
 - `APP_ENV=production` enables secure session cookies and the `Secure` flag on the current CSRF cookie.
 - `CASPIAN_BROWSER_SYNC_PORT` can override the development cookie scope suffix used by the current `main.py` bootstrap.
@@ -224,28 +225,29 @@ This does two things:
 - applies the centralized settings once at startup
 - registers OAuth providers once so `AuthMiddleware` can delegate signin and callback paths through `auth.auth_providers(...)`
 
-The current `main.py` also wires the session middleware directly:
-
-```python
-from starlette.middleware.sessions import SessionMiddleware
-
-
-SESSION_LIFETIME_HOURS = int(os.getenv("SESSION_LIFETIME_HOURS", 7))
-IS_PRODUCTION = os.getenv("APP_ENV") == "production"
-
-
-app.add_middleware(
-    SessionMiddleware,
-    secret_key=os.getenv("AUTH_SECRET", "change-me"),
-    session_cookie=os.getenv("AUTH_COOKIE_NAME", "session"),
-    max_age=SESSION_LIFETIME_HOURS * 3600,
-    same_site="lax",
+The current `main.py` also wires the session middleware directly, and some apps delegate the secret lookup to an app-owned helper:
+
+```python
+from starlette.middleware.sessions import SessionMiddleware
+from casp.runtime_security import get_session_secret
+
+
+SESSION_LIFETIME_HOURS = int(os.getenv("SESSION_LIFETIME_HOURS", 7))
+IS_PRODUCTION = os.getenv("APP_ENV") == "production"
+
+
+app.add_middleware(
+    SessionMiddleware,
+    secret_key=get_session_secret(is_production=IS_PRODUCTION),
+    session_cookie=os.getenv("AUTH_COOKIE_NAME", "session"),
+    max_age=SESSION_LIFETIME_HOURS * 3600,
+    same_site="lax",
     https_only=IS_PRODUCTION,
     path="/",
 )
 ```
 
-Keep this wiring in `main.py`. Keep only the policy values in `src/lib/auth/auth_config.py`.
+Keep this wiring in `main.py`. Keep only the policy values in `src/lib/auth/auth_config.py`. Runtime security helpers for session-secret enforcement, safe public-file serving, production-safe error messages, and baseline response headers are package-owned by `casp.runtime_security`; keep the middleware attachment itself in `main.py`.
 
 ## Session Lifetime Rules
 
@@ -258,37 +260,40 @@ The effective authenticated session lasts only while both are valid.
 
 - If the session cookie expires first, the session disappears even if the auth payload expiration was longer.
 - If the auth payload expires first, `auth.is_authenticated()` clears it even if the session cookie still exists.
-- In the pasted `main.py`, `token_auto_refresh=True` still does nothing by itself because the request flow does not call `auth.refresh_session()`.
+- In apps where the request flow does not call `auth.refresh_session()`, `token_auto_refresh=True` still does nothing by itself.
 
 Keep `SESSION_LIFETIME_HOURS` and `default_token_validity` aligned unless you intentionally want one boundary to end earlier than the other.
 
 ## Middleware Order
 
-The current `main.py` adds middleware in this source order:
-
-```python
-app.add_middleware(RPCMiddleware)
-app.add_middleware(AuthMiddleware)
-app.add_middleware(CSRFMiddleware)
-app.add_middleware(SessionMiddleware, ...)
-```
-
-Because Starlette runs the last-added middleware first, the effective request order is:
-
-1. `SessionMiddleware`
-2. `CSRFMiddleware`
-3. `AuthMiddleware`
-4. `RPCMiddleware`
-5. route handler or RPC endpoint
-
-Current behavior by layer:
-
-- `SessionMiddleware` provides `request.session` for the rest of the stack.
-- `CSRFMiddleware` ensures `request.session["csrf_token"]` exists and emits a scoped CSRF cookie based on `pp_csrf`, for example `pp_csrf_5091` in development or plain `pp_csrf` when no dev scope is active.
-- `AuthMiddleware` sets request context with `Auth.set_request(request)`, initializes `StateManager`, runs provider callbacks, skips configured static asset paths, and enforces public, auth, private, and role-based route redirects.
-- `RPCMiddleware` handles `POST` requests with `X-PP-RPC: true` and forwards them to Caspian's RPC handler after auth and session setup are already available.
-
-Keep `SessionMiddleware` outermost. If CSRF, auth, or RPC handling runs before it, `request.session` will not be available.
+The current `main.py` adds middleware in this source order:
+
+```python
+app.add_middleware(RPCMiddleware)
+app.add_middleware(AuthMiddleware)
+app.add_middleware(CSRFMiddleware)
+app.add_middleware(SessionMiddleware, ...)
+app.add_middleware(SecurityHeadersMiddleware)
+```
+
+Because Starlette runs the last-added middleware first, the effective request order is:
+
+1. `SecurityHeadersMiddleware`
+2. `SessionMiddleware`
+3. `CSRFMiddleware`
+4. `AuthMiddleware`
+5. `RPCMiddleware`
+6. route handler or RPC endpoint
+
+Current behavior by layer:
+
+- `SecurityHeadersMiddleware` can attach baseline response headers from `casp.runtime_security`, such as `X-Content-Type-Options`, framing policy, referrer policy, permissions policy, and production HSTS, while preserving any headers already set by the response. Do not assume this layer emits CSP or owns third-party browser resource allowlists; verify the installed package helper first.
+- `SessionMiddleware` provides `request.session` for the rest of the stack.
+- `CSRFMiddleware` ensures `request.session["csrf_token"]` exists and emits a scoped CSRF cookie based on `pp_csrf`, for example `pp_csrf_5091` in development or plain `pp_csrf` when no dev scope is active.
+- `AuthMiddleware` sets request context with `Auth.set_request(request)`, initializes `StateManager`, runs provider callbacks, skips configured static asset paths, and enforces public, auth, private, and role-based route redirects.
+- `RPCMiddleware` handles `POST` requests with `X-PP-RPC: true` and forwards them to Caspian's RPC handler after auth and session setup are already available.
+
+Keep `SessionMiddleware` immediately inside any outer response-header wrapper such as `SecurityHeadersMiddleware`. If CSRF, auth, or RPC handling runs before the session layer, `request.session` will not be available.
 
 ## Current `AuthMiddleware` Flow
 
@@ -760,7 +765,7 @@ Prefer `AuthSettings`, `configure_auth(...)`, and `auth.settings` in new code.
 - Expired or malformed payloads are removed during `auth.is_authenticated()` checks.
 - `auth.get_payload()` returns `None` for missing payloads, a dict for dict payloads, and `{"value": ...}` for non-dict payloads.
 - OAuth callback helpers return `None` on failure, so calling routes should be prepared for a normal page render or explicit error state when provider login fails.
-- The current app bootstrap adds `SessionMiddleware`, `CSRFMiddleware`, `AuthMiddleware`, and `RPCMiddleware`; auth-aware code depends on that ordering so sessions and CSRF state exist before route checks or RPC handling.
+- The current app bootstrap may wrap auth and session handling in an outer `SecurityHeadersMiddleware`; auth-aware code still depends on `SessionMiddleware`, `CSRFMiddleware`, `AuthMiddleware`, and `RPCMiddleware` staying in the correct relative order so sessions and CSRF state exist before route checks or RPC handling.
 - Password reset, email verification, and other account-recovery workflows are application responsibilities layered on top of `casp.auth`, not built-in auth runtime features.
 - Route lists and RBAC maps are exact-path checks, not wildcard or prefix rules.
 
@@ -803,7 +808,7 @@ If an AI agent is deciding how to handle auth in Caspian, apply these rules firs
 - Do not treat `token_auto_refresh` as a route-privacy switch. In the current app it only affects sliding-session refresh if `auth.refresh_session()` is called.
 - Use `@require_auth`, `@require_role`, and `@guest_only` for page-level access rules.
 - Use `@rpc(require_auth=True, allowed_roles=[...])` for protected browser-triggered actions.
-- Keep `SessionMiddleware` outermost so auth, CSRF, and RPC handlers can read `request.session`.
+- Keep `SessionMiddleware` immediately inside any outer response-header wrapper so auth, CSRF, and RPC handlers can read `request.session`.
 - Use [state.md](./state.md) only for transient auth-adjacent request state, not as the auth session store.
 - Align `SESSION_LIFETIME_HOURS` with `default_token_validity` unless you intentionally want different cookie and auth-payload expiry windows.
 - Prefer exact route strings in `public_routes`, `auth_routes`, `private_routes`, and `role_based_routes`.
@@ -811,6 +816,6 @@ If an AI agent is deciding how to handle auth in Caspian, apply these rules firs
 - Keep auth secrets and OAuth provider credentials in `.env`.
 - Set `AUTH_COOKIE_NAME` explicitly so the session middleware cookie name and auth settings stay aligned.
 - Use `.venv/Lib/site-packages/casp/auth.py` only when the task is about framework auth internals or debugging installed behavior.
-- Use `main.py` when the task is about auth bootstrap, session middleware, or middleware execution order.
+- Use `main.py` plus `casp.runtime_security` when the task is about auth bootstrap, session middleware, safe public-file serving, response headers, or middleware execution order.
 - Pair auth work with `fetch-data.md` for RPC forms and `validation.md` for credential validation.
 - Check `routing.md` and `project-structure.md` before creating new auth routes or shared auth helpers.

package/dist/docs/core-runtime-map.md

@@ -29,16 +29,19 @@ Use it when you already know a behavior is controlled by `main.py` or `.venv/Lib
 
 | Concern | Core file | Read first | Why it matters |
 | --- | --- | --- | --- |
-| App bootstrap and request flow | [main.py](../../../../main.py) | [project-structure.md](./project-structure.md), [routing.md](./routing.md), [auth.md](./auth.md) | FastAPI app creation, static asset routes, middleware order, route registration, cache check and save, exception handlers, and final HTML transforms all live here. |
+| App bootstrap and request flow | [main.py](../../../../main.py) plus imported runtime helpers such as `casp.runtime_security` | [project-structure.md](./project-structure.md), [routing.md](./routing.md), [auth.md](./auth.md) | FastAPI app creation, middleware wiring, route registration, cache check and save, exception handlers, and final HTML transforms live here. Package-owned helpers imported by `main.py` may own safe public-file serving, baseline non-CSP response headers, production-safe error messages, or production session-secret enforcement. |
 | Browser runtime, SPA navigation, and scroll restoration | [public/js/pp-reactive-v2.js](../../../../public/js/pp-reactive-v2.js) | [pulsepoint.md](./pulsepoint.md), [fetch-data.md](./fetch-data.md) | The shipped `pp` runtime, same-origin SPA interception, per-history-entry scroll state, `pp-reset-scroll` behavior, and browser RPC helpers live here. |
 
 Important current `main.py` behaviors AI should keep in mind:
 
-- In development, `_scoped_cookie_name(...)` appends the active BrowserSync or dev port to both the session cookie name and the CSRF cookie name. The scope is resolved from `CASPIAN_BROWSER_SYNC_PORT`, then `settings/bs-config.json`, then `PORT`.
-- `register_single_route(...)` passes path params to `page()` as one positional dict, injects matching query params by name, and injects `request` by keyword when declared.
-- The render pipeline is `transform_components(...)`, then `render_with_nested_layouts(...)`, then `transform_scripts(...)`.
-- Route-level generators returned from `page()` are wrapped in `SSE(...)` before the response is sent.
-- Middleware is added in source order as `RPCMiddleware`, `AuthMiddleware`, `CSRFMiddleware`, `SessionMiddleware`, so the effective request order is reversed at runtime.
+- In development, `_scoped_cookie_name(...)` appends the active BrowserSync or dev port to both the session cookie name and the CSRF cookie name. The scope is resolved from `CASPIAN_BROWSER_SYNC_PORT`, then `settings/bs-config.json`, then `PORT`.
+- `register_single_route(...)` passes path params to `page()` as one positional dict, injects matching query params by name, and injects `request` by keyword when declared.
+- The render pipeline is `transform_components(...)`, then `render_with_nested_layouts(...)`, then `transform_scripts(...)`.
+- Route-level generators returned from `page()` are wrapped in `SSE(...)` before the response is sent.
+- Safe public-file helpers live in `casp.runtime_security` and should reject `..` traversal before serving from `public/**`.
+- Session middleware secrets may be resolved through `casp.runtime_security` so production can fail fast when `AUTH_SECRET` is missing or still on a default placeholder.
+- Baseline non-CSP response headers may be built by `casp.runtime_security` and attached through `SecurityHeadersMiddleware`. Do not assume that helper is a third-party browser resource or domain registry; check the current helper before adding CSP behavior.
+- Middleware is added in source order as `RPCMiddleware`, `AuthMiddleware`, `CSRFMiddleware`, `SessionMiddleware`, `SecurityHeadersMiddleware`, so the effective request order is reversed at runtime.
 - `public/js/pp-reactive-v2.js` saves scroll positions per history entry, resets window scroll on push navigation, and uses `pp-reset-scroll="true"` to opt specific containers or the whole body into reset behavior.
 
 ## Caspian Core Feature Map
@@ -53,6 +56,7 @@ Use this table when the task names a framework feature but the owning file is no
 | Metadata | route or layout `metadata`, runtime metadata helpers | `casp.layout`, `main.py` | [metadata.md](./metadata.md), [routing.md](./routing.md) |
 | Component imports and `x-*` tags | `src/components/**`, `src/app/**/*.html` | `casp.components_compiler`, `casp.component_decorator` | [components.md](./components.md), [routing.md](./routing.md) |
 | Auth and route protection | `src/lib/auth/auth_config.py`, `main.py`, route decorators | `casp.auth`, `main.py` middleware | [auth.md](./auth.md) |
+| Baseline response headers and safe public-file serving | `main.py` imports from `casp.runtime_security` | `.venv/Lib/site-packages/casp/runtime_security.py` | [auth.md](./auth.md), [project-structure.md](./project-structure.md) |
 | RPC and server actions | route or component Python modules with `@rpc()` | `casp.rpc`, `main.py` middleware | [fetch-data.md](./fetch-data.md), [file-uploads.md](./file-uploads.md) |
 | Streaming | route `page()` generators, RPC generators | `casp.streaming`, `casp.rpc`, `main.py` | [fetch-data.md](./fetch-data.md) |
 | Server state | request handlers and RPC actions | `casp.state_manager`, `main.py` middleware | [state.md](./state.md) |
@@ -85,8 +89,9 @@ Interactive CRUD page:
 | Runtime file | Primary responsibility | Read these docs |
 | --- | --- | --- |
 | [.venv/Lib/site-packages/casp/layout.py](../../../../.venv/Lib/site-packages/casp/layout.py) | `render_page(...)`, `render_layout(...)`, nested layout discovery, metadata merge, and the synchronous `layout()` contract | [routing.md](./routing.md), [metadata.md](./metadata.md) |
-| [.venv/Lib/site-packages/casp/auth.py](../../../../.venv/Lib/site-packages/casp/auth.py) | `AuthSettings`, route privacy checks, session payloads, OAuth providers, CSRF helper behavior, and redirect logic | [auth.md](./auth.md) |
-| [.venv/Lib/site-packages/casp/rpc.py](../../../../.venv/Lib/site-packages/casp/rpc.py) | `@rpc()` registration, rate limits, request handling, auth-aware action checks, and streamed RPC responses | [fetch-data.md](./fetch-data.md) |
+| [.venv/Lib/site-packages/casp/auth.py](../../../../.venv/Lib/site-packages/casp/auth.py) | `AuthSettings`, route privacy checks, session payloads, OAuth providers, CSRF helper behavior, and redirect logic | [auth.md](./auth.md) |
+| [.venv/Lib/site-packages/casp/runtime_security.py](../../../../.venv/Lib/site-packages/casp/runtime_security.py) | safe public-file serving, baseline non-CSP response headers, production-safe error messages, and production session-secret enforcement used by `main.py` | [project-structure.md](./project-structure.md), [auth.md](./auth.md) |
+| [.venv/Lib/site-packages/casp/rpc.py](../../../../.venv/Lib/site-packages/casp/rpc.py) | `@rpc()` registration, rate limits, request handling, auth-aware action checks, and streamed RPC responses | [fetch-data.md](./fetch-data.md) |
 | [.venv/Lib/site-packages/casp/streaming.py](../../../../.venv/Lib/site-packages/casp/streaming.py) | `SSE`, `ServerSentEvent`, and generator-to-event-stream wrapping | [fetch-data.md](./fetch-data.md) |
 | [.venv/Lib/site-packages/casp/state_manager.py](../../../../.venv/Lib/site-packages/casp/state_manager.py) | request-scoped state, session bucket persistence, listener lifecycle, and wire-request reset behavior | [state.md](./state.md) |
 | [.venv/Lib/site-packages/casp/cache_handler.py](../../../../.venv/Lib/site-packages/casp/cache_handler.py) | `Cache`, cache manifest handling, filename generation, disk-backed HTML storage, and invalidation | [cache.md](./cache.md) |
@@ -106,7 +111,7 @@ Use these behavior checkpoints when AI needs the fastest verification path for a
 
 | Runtime area | Verify these behaviors |
 | --- | --- |
-| `main.py` routing and request flow | route registration, path and query injection, static asset handling, and exception rendering |
+| `main.py` routing and request flow | route registration, path and query injection, static asset handling, session-middleware wiring, response-header middleware, and exception rendering |
 | `public/js/pp-reactive-v2.js` browser runtime | SPA interception, history-vs-push scroll behavior, `pp-reset-scroll` semantics, and browser-side `pp.rpc()` behavior |
 | `casp.auth` | auth settings, signin and signout flow, provider wiring, and page protection behavior |
 | `casp.rpc` and streamed RPC responses | middleware interception, CSRF and session expectations, registry behavior, and helper-level RPC contracts |

package/dist/docs/project-structure.md

@@ -80,10 +80,10 @@ my-app/
       mcp/
         fastmcp.json
         mcp_server.py
-      prisma/
-        __init__.py
-        db.py
-        models.py
+      prisma/
+        __init__.py
+        db.py
+        models.py
   .venv/
     Lib/
       site-packages/
@@ -130,7 +130,7 @@ For component HTML files, follow the component authoring rules in [components.md
 
 The directories listed in `componentScanDirs` determine where component tooling scans. When that list includes `src/`, `src/components/` is a conventionally clean location, not a hard-coded runtime requirement.
 
-### `src/lib/`
+### `src/lib/`
 
 Use this folder for shared helpers, reusable validators, RPC-facing service wrappers, data-access helpers, formatting utilities, and other app-level support code that is not itself a reusable rendered component.
 
@@ -140,7 +140,9 @@ For file upload and manager flows, keep route-owned `@rpc()` actions in `src/app
 
 When a project includes an app-owned Python database layer under `src/lib/prisma/`, reuse that package for Python-side data access and keep any additional shared database helpers in `src/lib/`.
 
-When MCP is enabled for the project, this folder also contains the app-owned FastMCP server under `src/lib/mcp/`.
+When MCP is enabled for the project, this folder also contains the app-owned FastMCP server under `src/lib/mcp/`.
+
+Do not add `src/lib/security/runtime_security.py` for normal app work. Runtime security helpers for safe public-file serving, production session-secret enforcement, production-safe error messages, and baseline non-CSP response headers are package-owned by `casp.runtime_security`.
 
 ### Shared Database Helpers
 
@@ -185,16 +187,31 @@ If the local BrowserSync stack is running, keep that upload directory in `settin
 
 The application entry point for the project.
 
-In the current Caspian app shape, this file is where startup wiring happens:
-
-- load environment variables
-- call `configure_auth(build_auth_settings())`
-- register OAuth providers with `Auth.set_providers(...)`
-- create the FastAPI app
-- register routes and RPC handlers
-- add `SessionMiddleware`, CSRF middleware, auth middleware, and RPC middleware
-
-Use `main.py` for auth bootstrap and middleware-order changes. Use `src/lib/auth/auth_config.py` for auth policy values such as public routes, redirects, and RBAC maps.
+In the current Caspian app shape, this file is where startup wiring happens:
+
+- load environment variables
+- call `configure_auth(build_auth_settings())`
+- register OAuth providers with `Auth.set_providers(...)`
+- create the FastAPI app
+- register routes and RPC handlers
+- add response headers middleware, `SessionMiddleware`, CSRF middleware, auth middleware, and RPC middleware
+
+Use `main.py` for auth bootstrap and middleware-order changes. Use `src/lib/auth/auth_config.py` for auth policy values such as public routes, redirects, and RBAC maps.
+
+### `.venv/Lib/site-packages/casp/runtime_security.py`
+
+The installed Caspian package owns runtime security helpers that `main.py` can import as `casp.runtime_security`. Keep this file in the package instead of copying it into `src/lib/`, because normal app users should not need to edit it.
+
+This helper is not a registry for third-party browser resources. Do not add Google, YouTube, CDN, image-host, API, or iframe origins here just because the browser or server uses them. If an app later chooses to enforce a Content Security Policy, document and implement that as an explicit project policy rather than assuming `runtime_security.py` owns a domain allowlist.
+
+Use this package module when the task is about:
+
+- safe serving of files from `public/**`
+- production session-secret enforcement
+- user-facing vs production-safe exception messaging helpers
+- baseline response headers such as permissions, referrer, MIME sniffing, framing, or HSTS behavior
+
+Because this file is framework-owned, edit it only for Caspian runtime work or when documentation must match the installed package. App-specific auth policy still belongs in `src/lib/auth/auth_config.py`, and app-specific upload or storage behavior should live in route-owned code or other `src/lib/**` helpers.
 
 ### `caspian.config.json`
 

package/dist/docs/pulsepoint.md

@@ -7,9 +7,9 @@ related:
   links:
     - /docs/components
     - /docs/routing
-    - /docs/fetch-data
-    - /docs/pulsepoint-runtime-map
-    - /docs/core-runtime-map
+    - /docs/fetch-data
+    - /docs/pulsepoint-runtime-map
+    - /docs/core-runtime-map
     - /docs/project-structure
     - /docs/index
 ---
@@ -44,9 +44,9 @@ Important current facts:
 
 If docs, generated examples, or older notes disagree with `public/js/pp-reactive-v2.js` plus `main.py`, follow the code that actually runs.
 
-Use [core-runtime-map.md](./core-runtime-map.md) when the controlling runtime file is not obvious yet.
-
-Use [pulsepoint-runtime-map.md](./pulsepoint-runtime-map.md) when the task names a specific PulsePoint feature or directive and you need a quick feature-to-runtime lookup before reading the full guide.
+Use [core-runtime-map.md](./core-runtime-map.md) when the controlling runtime file is not obvious yet.
+
+Use [pulsepoint-runtime-map.md](./pulsepoint-runtime-map.md) when the task names a specific PulsePoint feature or directive and you need a quick feature-to-runtime lookup before reading the full guide.
 
 ## Default Frontend Rule
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "caspian-utils",
-  "version": "0.0.30",
+  "version": "0.0.32",
   "description": "Caspian tooling",
   "main": "index.js",
   "scripts": {