caspian-utils 0.0.32 → 0.0.33

package/dist/docs/auth.md

@@ -56,6 +56,7 @@ from casp.auth import (
 - Use `@rpc(require_auth=True, allowed_roles=[...])` for browser-triggered actions that need protection.
 - Use `StateManager` only for transient auth-adjacent request state; keep the authenticated session itself owned by `casp.auth`.
 - Keep secrets and provider credentials in `.env`; keep route visibility, redirects, and RBAC policy in `src/lib/auth/auth_config.py`.
+- Do not implement custom `next` parsing or post-login redirect selection inside sign-in UI flows when using the built-in Caspian auth stack. The runtime and centralized auth config already own guest redirects, auth-route redirects, and the default post-login target.
 - Validate login, signup, reset-password, and profile-mutation inputs before hitting the database or external providers.
 
 ## Framework Internals Note
@@ -122,6 +123,23 @@ Important behavior from the current implementation:
 - `role_identifier` defaults to `role`, and the current `auth.sign_in(...)` flow also normalizes `userRole` into `role` when possible.
 - `api_auth_prefix` defaults to `/api/auth` and should stay centralized here rather than being hard-coded across routes.
 
+## Redirect Ownership
+
+Treat redirect behavior as framework-owned plus config-owned, not sign-in-page-owned.
+
+- Keep the redirect policy in `src/lib/auth/auth_config.py`, especially `default_signin_redirect` and `default_signout_redirect`.
+- In the current runtime, unauthenticated requests to protected routes are redirected by middleware and decorators to `/signin?next=...`.
+- In the current runtime, authenticated users who hit an auth route such as `/signin` are redirected by the auth layer to `default_signin_redirect`, which defaults to `/dashboard`.
+- `guest_only()` also prefers a safe `next` query value for already-authenticated users and otherwise falls back to `default_signin_redirect`.
+- Because this behavior already exists in `main.py`, `.venv/Lib/site-packages/casp/auth.py`, and `src/lib/auth/auth_config.py`, sign-in implementations should not add their own redirect-decision layer, duplicate `next` handling, or hard-code a dashboard redirect inside the sign-in action.
+- When building sign-in flows, focus on credential validation, calling `auth.sign_in(...)` or the relevant provider flow, and rendering errors. Let Caspian decide where the user goes next.
+
+Use this rule of thumb for AI-generated sign-in work:
+
+- If the task is only to build or style the sign-in page, do not add redirect support.
+- If the task is to change where authenticated users land after sign-in, update `default_signin_redirect` in `src/lib/auth/auth_config.py` instead of editing the sign-in route logic.
+- If the task is to change how protected routes send guests to sign-in, inspect the installed auth runtime and middleware instead of adding local redirect code to the sign-in page.
+
 ## Choosing Public vs Private Route Mode
 
 Make this decision at app setup time in `src/lib/auth/auth_config.py`.
@@ -165,9 +183,9 @@ return AuthSettings(
 
 The installed auth code reads several values from `.env` when explicit values are not passed.
 
-- `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`.
+- `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.
@@ -225,29 +243,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, 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",
+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`. 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`.
+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
 
@@ -260,40 +278,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 apps where the request flow does not call `auth.refresh_session()`, `token_auto_refresh=True` still does nothing by itself.
+- 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, ...)
-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.
+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
 
@@ -765,7 +783,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 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.
+- 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.
 
@@ -808,7 +826,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` immediately inside any outer response-header wrapper 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`.
@@ -816,6 +834,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` plus `casp.runtime_security` when the task is about auth bootstrap, session middleware, safe public-file serving, response headers, 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/package.json

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