caspian-utils 0.0.30 → 0.0.31

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 src.lib.security.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`. If the app uses an app-owned security helper for session-secret enforcement, safe public-file serving, or browser security headers, keep that helper in `src/lib/**` and 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 browser security headers such as CSP, `X-Content-Type-Options`, framing policy, and HSTS while preserving any headers already set by the response.
+- `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 any app-owned runtime security helper when the task is about auth bootstrap, session middleware, browser security 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 any imported app-owned runtime helpers | [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. App-owned helper modules imported by `main.py` may own safe static-file serving, browser security headers, CSP defaults, 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 may be factored into an app-owned runtime module and should reject `..` traversal before serving from `public/**`.
+- Session middleware secrets may be resolved through an app-owned helper so production can fail fast when `AUTH_SECRET` is missing or still on a default placeholder.
+- Browser security headers and CSP defaults may be built in an app-owned helper and attached through `SecurityHeadersMiddleware`.
+- 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) |
+| Browser security headers, CSP defaults, and safe public-file serving | app-owned helpers imported by `main.py` | app-owned runtime modules | [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) |
@@ -106,7 +110,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, browser security headers, 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

@@ -185,16 +185,27 @@ 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 security 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.
+
+### `src/lib/security/runtime_security.py`
+
+When the app factors request hardening into an app-owned helper module, keep browser security headers, CSP defaults, safe public-file helpers, and production session-secret enforcement there instead of bloating `main.py`.
+
+Use this module when the task is about:
+
+- safe serving of files from `public/**`
+- browser security headers or content-security-policy defaults
+- production session-secret enforcement
+- user-facing vs production-safe exception messaging helpers
 
 ### `caspian.config.json`
 

package/package.json

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