caspian-utils 0.1.6 → 0.1.8

package/dist/docs/auth.md

@@ -329,6 +329,8 @@ The pasted `main.py` auth middleware currently behaves like this:
 
 Because `AuthMiddleware` initializes `StateManager` on every request, auth flows can also use [state.md](./state.md) for transient request-scoped success or error state. Keep identity, session lifetime, and authorization decisions in `auth.sign_in(...)`, `auth.sign_out(...)`, and the auth decorators rather than moving them into the state manager.
 
+`AuthMiddleware` only runs on `scope["type"] == "http"`; it early-returns on WebSocket scopes. A private page route therefore does not protect a WebSocket. To keep socket auth aligned with page auth, reuse the same `Auth` instance inside the socket guard: bind the socket with `Auth.set_request(websocket)` (a `WebSocket` exposes `.session`, the one piece `Auth` reads) and call `auth.is_authenticated()`, `auth.get_payload()`, and `auth.check_role(...)`. See [websockets.md](./websockets.md) for the full guard pattern and the read-only-session caveat.
+
 ## The `auth` Object
 
 The global `auth` singleton owns the session lifecycle.

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

@@ -113,7 +113,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, session-middleware wiring, response-header middleware, and exception rendering |
-| `main.py` WebSockets | `cfg.websocket` route-registration gate, `@app.websocket(...)` paths, origin checks before `accept()`, auth/session extraction, message-size and idle-timeout handling, close codes, and connection cleanup |
+| `main.py` WebSockets | `cfg.websocket` route-registration gate, `@app.websocket(...)` paths, and the shared transport loop (message-size, idle-timeout, close codes, connection cleanup). Authorization is a single guard in `src/lib/websocket/websocket_security.py` (`authorize_websocket`) that runs the origin check before `accept()` and delegates auth to `Auth`. The HTTP middleware stack skips `scope["type"] == "websocket"`, so socket auth is enforced by that guard, not by `AuthMiddleware` |
 | `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/pulsepoint.md

@@ -346,11 +346,12 @@ Important:
 - The script lookup walks the current root and skips nested `pp-component` boundaries, so a parent does not consume a child component's script.
 - If multiple matching runtime scripts exist in the same root, the first matching owned script wins. Generate one script per root.
 - Authored route, layout, and component templates still need one top-level parent node so Caspian can inject the component boundary correctly after component expansion.
-- A scriptless component root still mounts and can receive props, refs, events, and nested children, but it has no local runtime scope beyond its props.
+- A scriptless component root still mounts and can receive props, refs, events, and nested children, but it does not create local bindings from those props on its own.
 - Component scripts are plain JavaScript executed with `new Function(...)`. Do not use `import`, `export`, or top-level `await` inside them.
 - The runtime auto-returns supported top-level bindings from the script. Do not rely on manual `return { ... }` objects.
-- `pp.props` contains the current prop bag for the component.
-- `pp.props.children` contains the root's initial inner HTML before the owned script is removed from the render template.
+- `pp.props` contains the current prop bag for the component.
+- `pp.props.children` contains the root's initial inner HTML before the owned script is removed from the render template.
+- Props are not auto-injected as standalone top-level template or handler variables. Read them through `pp.props` or explicitly destructure them in the component script.
 
 Bindings exported to the template:
 
@@ -569,12 +570,13 @@ When a child component needs the same token object, pass it from the provider sc
 
 - Child component props are derived from DOM attributes.
 - Attribute names are converted from kebab-case to camelCase for the prop bag.
-- Native `on*` attributes and `pp-component` are not included in props.
-- Empty attributes become boolean `true` props.
-- Pure prop expressions such as `title="{pageTitle}"` are evaluated in the parent scope.
-- Mixed strings such as `class="card {isActive ? 'active' : ''}"` are interpolated in the parent scope.
-- Non-expression attribute values are passed through as strings.
-- `children` is injected into props using the root's initial inner HTML.
+- Native `on*` attributes and `pp-component` are not included in props.
+- Empty attributes become boolean `true` props.
+- Pure prop expressions such as `title="{pageTitle}"` are evaluated in the parent scope.
+- Mixed strings such as `class="card {isActive ? 'active' : ''}"` are interpolated in the parent scope.
+- Non-expression attribute values are passed through as strings.
+- `children` is injected into props using the root's initial inner HTML.
+- Inside the child component, those values should be accessed through `pp.props` or a top-level destructure such as `const { title } = pp.props`; they are not implicitly available as bare identifiers.
 
 Nested components:
 

package/dist/docs/websockets.md

@@ -43,8 +43,9 @@ WEBSOCKET_PATH = "/ws/channel"
 
 @app.websocket(WEBSOCKET_PATH)
 async def websocket_live_endpoint(websocket: WebSocket):
-    if not is_origin_allowed(websocket):
-        await websocket.close(code=status.WS_1008_POLICY_VIOLATION)
+    # ONE guard authorizes the connection (origin + auth) and returns the
+    # identity, or None after closing. Pass require_auth / roles per channel.
+    if await authorize_websocket(websocket, require_auth=True) is None:
         return
 
     await manager.connect(websocket)
@@ -58,6 +59,8 @@ async def websocket_live_endpoint(websocket: WebSocket):
         manager.disconnect(websocket)
 ```
 
+Keep the authorization gate in one reusable helper rather than re-deriving auth in each endpoint. A public and a private channel should differ only by their `require_auth`/`roles` policy and their broadcast pool, not by a second copy of origin and session logic. Keep authenticated and guest traffic in separate connection managers so a private broadcast can never fan out to a guest connection.
+
 Keep reusable socket helpers in `src/lib/**` when they are shared by more than one endpoint or route. Good candidates include connection managers, session helpers, auth-payload extraction, payload normalization, and shared broadcast code.
 
 Keep route-specific browser UI in `src/app/**/index.html` and route-specific first-render values in the matching `index.py`. For example, an `index.py` can pass `websocket_path` and a development-only BrowserSync-aware `websocket_url` into the template with `render_page(__file__, {...})`.
@@ -108,11 +111,28 @@ This is one of the narrow cases where direct browser APIs and event listeners ar
 
 ## Auth And Sessions
 
-HTTP route privacy does not automatically make a WebSocket endpoint private. If a socket is authenticated, the endpoint must explicitly inspect the session or auth payload available on the WebSocket scope and close unauthenticated clients.
+HTTP route privacy does not automatically make a WebSocket endpoint private. The HTTP middleware stack (`AuthMiddleware`, `CSRFMiddleware`, `RPCMiddleware`, body-size, security-header, and diagnostics layers) early-returns on every non-`http` scope, so a WebSocket handshake (`scope["type"] == "websocket"`) is never seen by `AuthMiddleware`. The only middleware that runs on socket scopes is `SessionMiddleware`, which exposes `websocket.session`. Each authenticated socket endpoint must therefore authorize itself.
+
+Align that self-check with the rest of the app by delegating to Caspian's `Auth` instead of re-implementing session/`exp`/payload parsing. `Auth` methods read only `request.session`, and a `WebSocket` exposes `.session`, so binding the socket as the request context reuses the exact HTTP auth logic as a single source of truth:
+
+```python
+from casp.auth import Auth
+
+Auth.set_request(websocket)            # WebSocket exposes .session
+auth = Auth.get_instance()
+if auth.is_authenticated():
+    payload = auth.get_payload() or {}
+    if roles and not auth.check_role(payload, roles):
+        ...                            # forbidden -> close 1008
+else:
+    ...                                # unauthenticated -> close 1008 if required
+```
 
 Use close code `1008` for policy violations such as failed origin checks or missing authentication. If the endpoint accepts before rejecting, send a small JSON error payload first so the browser UI can show a useful message.
 
-If the app refreshes auth sessions, verify whether the WebSocket helper refreshes session expiry and whether that session mutation is persisted in the current middleware stack. Do not assume HTTP `AuthMiddleware` behavior applies to `scope["type"] == "websocket"`.
+Treat the socket auth check as read-only. `SessionMiddleware` only writes the session cookie on `http.response.start`, which never fires for a WebSocket, so session mutations made during a connection (including `refresh_session` / sliding `exp`) are not persisted back to the cookie. Do not rely on the socket to extend a session; verify identity and, if needed, drive session refresh from an HTTP request. Do not assume HTTP `AuthMiddleware` behavior applies to `scope["type"] == "websocket"`.
+
+Path-based `Auth` helpers (`is_private_route`, `get_required_roles`) read the HTTP route configuration and do not know about `/ws/*` paths. For socket RBAC, pass the required roles explicitly into the guard rather than asking `Auth` to classify the socket path.
 
 ## Origin And Proxy Checks
 

package/package.json

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