supython 0.1.5__tar.gz → 0.1.7__tar.gz

{supython-0.1.5 → supython-0.1.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: supython
-Version: 0.1.5
+Version: 0.1.7
 Summary: A lightweight Postgres-first BaaS framework for Python
 Project-URL: Homepage, https://github.com/Tkeby/supython
 Project-URL: Repository, https://github.com/Tkeby/supython
@@ -95,7 +95,7 @@ Shipped [v0.1.2]:
 **Jobs & cron**
 - **Job queue** — Postgres-backed (`SELECT FOR UPDATE SKIP LOCKED`), idempotent enqueue, retry with backoff
 - **Cron scheduling** — `pg_cron` (primary) or in-process `croniter` fallback
-- **Generic hooks** — `@app.on_signup` / `@app.on_login` lifecycle hooks; `@app.claims_provider` for custom JWT claims
+- **Generic hooks** — `@app.on_signup` / `@app.on_login` lifecycle hooks; `@claims_provider` (from `supython.auth.claims`) for custom JWT claims
 - **`supython worker run`** — long-running worker with graceful SIGTERM drain
 
 **Operations & security**
@@ -418,17 +418,40 @@ SMTP_PASSWORD`.
 **OAuth** — add `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET` (and/or GitHub
 equivalents) to `.env`. Providers without credentials are silently disabled.
 
+**Logout semantics (stateless JWT)** — `/auth/v1/logout` revokes the
+**refresh** token; the access token remains valid until its `exp` claim. This
+is the standard stateless-JWT posture (same as Supabase Auth, Auth0, Cognito):
+both supython and PostgREST verify access tokens from the JWKS with **no
+per-request DB lookup**, so there is no place to consult a server-side
+denylist without breaking that contract. The mitigation is a **short
+`ACCESS_TOKEN_TTL`** plus refresh-token revocation:
+
+- Clients must drop *both* tokens locally on logout — the access token must
+  not be reused after the user signs out.
+- A stolen access token cannot be invalidated server-side mid-flight; it
+  stops being useful at `exp`. Pick a TTL that bounds your exposure.
+- Default `ACCESS_TOKEN_TTL=3600` (1 hour) is fine for development. For
+  production, set it to **300–900 seconds** so logout / role changes
+  propagate in minutes rather than an hour. Refresh tokens are still
+  long-lived (`REFRESH_TOKEN_TTL=30d`) so users don't get prompted to log
+  in every few minutes — clients refresh transparently.
+
 ### Custom JWT claims [shipped v0.1.3]
 
-Register a `claims_provider` to inject application-specific claims into every
+Register a claims provider to inject application-specific claims into every
 access token minted by the auth endpoints. Each provider is an async callable
 `(user, conn) -> dict` whose return value is merged into the token payload —
 on signup, password login, refresh, magic-link, OTP, and OAuth callbacks.
 
+Import `register` directly from `supython.auth.claims` (typically aliased to
+`claims_provider`). Don't reach for `supython.app.app` — extensions load
+*during* `create_app()`, before `app` is bound, so importing it from a
+user-side `EXTENSIONS` module is a circular import.
+
 ```python
-from supython.app import app
+from supython.auth.claims import register as claims_provider
 
-@app.claims_provider
+@claims_provider
 async def add_org(user, conn):
     org_id = await conn.fetchval(
         "select org_id from public.memberships where user_id = $1", user.id
@@ -472,7 +495,7 @@ async def me(user_id: Annotated[UUID, Depends(current_user_id)]) -> dict:
 
 @router.get("/whoami")
 async def whoami(claims: Annotated[dict, Depends(current_claims)]) -> dict:
-    # Read whatever your `claims_provider` injected — e.g. org_id.
+    # Read whatever your claims provider injected — e.g. org_id.
     return {"user_id": claims["sub"], "org_id": claims.get("org_id")}
 ```
 
@@ -485,6 +508,8 @@ need any claim beyond the user UUID.
 
 | Variable | Default | Purpose |
 |---|---|---|
+| `ACCESS_TOKEN_TTL` | `3600` | Access-token lifetime in seconds. Lower this (300–900) in production so logout / role changes propagate quickly — the access token is stateless and only stops working at `exp` |
+| `REFRESH_TOKEN_TTL` | `2592000` | Refresh-token lifetime in seconds (30 d). Refresh tokens *are* revocable via `/auth/v1/logout` |
 | `DB_STATEMENT_TIMEOUT_MS` | `30000` | Per-connection query timeout for the asyncpg pool (`0` disables) |
 | `DB_POOL_MIN_SIZE` | `1` | Minimum asyncpg pool size |
 | `DB_POOL_MAX_SIZE` | `10` | Maximum asyncpg pool size |

{supython-0.1.5 → supython-0.1.7}/README.md

@@ -37,7 +37,7 @@ Shipped [v0.1.2]:
 **Jobs & cron**
 - **Job queue** — Postgres-backed (`SELECT FOR UPDATE SKIP LOCKED`), idempotent enqueue, retry with backoff
 - **Cron scheduling** — `pg_cron` (primary) or in-process `croniter` fallback
-- **Generic hooks** — `@app.on_signup` / `@app.on_login` lifecycle hooks; `@app.claims_provider` for custom JWT claims
+- **Generic hooks** — `@app.on_signup` / `@app.on_login` lifecycle hooks; `@claims_provider` (from `supython.auth.claims`) for custom JWT claims
 - **`supython worker run`** — long-running worker with graceful SIGTERM drain
 
 **Operations & security**
@@ -360,17 +360,40 @@ SMTP_PASSWORD`.
 **OAuth** — add `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET` (and/or GitHub
 equivalents) to `.env`. Providers without credentials are silently disabled.
 
+**Logout semantics (stateless JWT)** — `/auth/v1/logout` revokes the
+**refresh** token; the access token remains valid until its `exp` claim. This
+is the standard stateless-JWT posture (same as Supabase Auth, Auth0, Cognito):
+both supython and PostgREST verify access tokens from the JWKS with **no
+per-request DB lookup**, so there is no place to consult a server-side
+denylist without breaking that contract. The mitigation is a **short
+`ACCESS_TOKEN_TTL`** plus refresh-token revocation:
+
+- Clients must drop *both* tokens locally on logout — the access token must
+  not be reused after the user signs out.
+- A stolen access token cannot be invalidated server-side mid-flight; it
+  stops being useful at `exp`. Pick a TTL that bounds your exposure.
+- Default `ACCESS_TOKEN_TTL=3600` (1 hour) is fine for development. For
+  production, set it to **300–900 seconds** so logout / role changes
+  propagate in minutes rather than an hour. Refresh tokens are still
+  long-lived (`REFRESH_TOKEN_TTL=30d`) so users don't get prompted to log
+  in every few minutes — clients refresh transparently.
+
 ### Custom JWT claims [shipped v0.1.3]
 
-Register a `claims_provider` to inject application-specific claims into every
+Register a claims provider to inject application-specific claims into every
 access token minted by the auth endpoints. Each provider is an async callable
 `(user, conn) -> dict` whose return value is merged into the token payload —
 on signup, password login, refresh, magic-link, OTP, and OAuth callbacks.
 
+Import `register` directly from `supython.auth.claims` (typically aliased to
+`claims_provider`). Don't reach for `supython.app.app` — extensions load
+*during* `create_app()`, before `app` is bound, so importing it from a
+user-side `EXTENSIONS` module is a circular import.
+
 ```python
-from supython.app import app
+from supython.auth.claims import register as claims_provider
 
-@app.claims_provider
+@claims_provider
 async def add_org(user, conn):
     org_id = await conn.fetchval(
         "select org_id from public.memberships where user_id = $1", user.id
@@ -414,7 +437,7 @@ async def me(user_id: Annotated[UUID, Depends(current_user_id)]) -> dict:
 
 @router.get("/whoami")
 async def whoami(claims: Annotated[dict, Depends(current_claims)]) -> dict:
-    # Read whatever your `claims_provider` injected — e.g. org_id.
+    # Read whatever your claims provider injected — e.g. org_id.
     return {"user_id": claims["sub"], "org_id": claims.get("org_id")}
 ```
 
@@ -427,6 +450,8 @@ need any claim beyond the user UUID.
 
 | Variable | Default | Purpose |
 |---|---|---|
+| `ACCESS_TOKEN_TTL` | `3600` | Access-token lifetime in seconds. Lower this (300–900) in production so logout / role changes propagate quickly — the access token is stateless and only stops working at `exp` |
+| `REFRESH_TOKEN_TTL` | `2592000` | Refresh-token lifetime in seconds (30 d). Refresh tokens *are* revocable via `/auth/v1/logout` |
 | `DB_STATEMENT_TIMEOUT_MS` | `30000` | Per-connection query timeout for the asyncpg pool (`0` disables) |
 | `DB_POOL_MIN_SIZE` | `1` | Minimum asyncpg pool size |
 | `DB_POOL_MAX_SIZE` | `10` | Maximum asyncpg pool size |

{supython-0.1.5 → supython-0.1.7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "supython"
-version = "0.1.5"
+version = "0.1.7"
 description = "A lightweight Postgres-first BaaS framework for Python"
 readme = "README.md"
 requires-python = ">=3.11"

{supython-0.1.5 → supython-0.1.7}/src/supython/app.py

@@ -11,7 +11,6 @@ from fastapi.middleware.cors import CORSMiddleware
 from . import __version__, db, jwks
 from .admin import router as admin_api_router
 from .admin import spa as admin_spa
-from .auth import claims as auth_claims
 from .auth.router import router as auth_router
 from .extensions import load_extensions
 from .settings_module import UserSettings, load_user_settings
@@ -156,7 +155,6 @@ def create_app() -> FastAPI:
     app.on_signup = _make_hook_decorator("signup")
     app.on_login = _make_hook_decorator("login")
     app.on_logout = _make_hook_decorator("logout")
-    app.claims_provider = auth_claims.register
 
     return app
 

{supython-0.1.5 → supython-0.1.7}/src/supython/auth/claims.py

@@ -1,9 +1,10 @@
 """Custom-claim providers for access-token issuance.
 
-Library users register an async callable via ``@app.claims_provider`` (or
-``claims.register``) and the auth service invokes it inside ``_issue_pair``
-just before minting the JWT. Each provider returns a ``dict`` that is
-merged into the access token's payload.
+Library users register an async callable via ``claims.register`` (typically
+imported as ``from supython.auth.claims import register as claims_provider``)
+and the auth service invokes it inside ``_issue_pair`` just before minting
+the JWT. Each provider returns a ``dict`` that is merged into the access
+token's payload.
 
 Contract (intentionally narrower than ``hooks.fire``):
 

{supython-0.1.5 → supython-0.1.7}/src/supython/functions/context.py

@@ -11,6 +11,7 @@ rule that applies elsewhere.
 from __future__ import annotations
 
 from collections.abc import AsyncIterator, Awaitable, Callable
+from contextlib import AbstractAsyncContextManager
 from dataclasses import dataclass, field
 from typing import TYPE_CHECKING, Any
 from uuid import UUID
@@ -18,6 +19,7 @@ from uuid import UUID
 import asyncpg
 import httpx
 
+from .. import db as _db
 from ..mailer import EmailBackend, EmailMessage, get_mailer
 from ..settings import Settings, get_settings
 from ..storage import service as storage_service
@@ -73,9 +75,7 @@ class StorageClient:
     ``backend`` by hand.
     """
 
-    def __init__(
-        self, conn: asyncpg.Connection, backend: StorageBackend
-    ) -> None:
+    def __init__(self, conn: asyncpg.Connection, backend: StorageBackend) -> None:
         self._conn = conn
         self._backend = backend
 
@@ -120,9 +120,7 @@ class StorageClient:
         )
 
     async def get_metadata(self, *, bucket: str, path: str) -> ObjectResponse:
-        return await storage_service.get_object_metadata(
-            self._conn, bucket, path
-        )
+        return await storage_service.get_object_metadata(self._conn, bucket, path)
 
     async def sign(
         self, *, bucket: str, path: str, expires_in: int | None = None
@@ -234,6 +232,30 @@ class Ctx:
     request: Request
     settings: Settings
 
+    def service_db(
+        self,
+        *,
+        with_user_claims: bool = True,
+    ) -> AbstractAsyncContextManager[asyncpg.Connection]:
+        """Yield a ``service_role`` connection for housekeeping inside a handler.
+
+        Convenience wrapper around :func:`supython.db.as_service_role` so user
+        code can write::
+
+            async with ctx.service_db() as conn:
+                await conn.execute("insert into audit.events ...")
+
+        instead of importing ``supython.db``. ``service_role`` bypasses RLS;
+        when the caller is authenticated the user's JWT claims are forwarded
+        to the session so helpers like ``auth.uid()`` still return the
+        caller's id inside the block. Pass ``with_user_claims=False`` to
+        suppress that and run truly impersonal admin work.
+        """
+        claims = (
+            self.user.claims if (with_user_claims and self.user is not None) else None
+        )
+        return _db.as_service_role(claims=claims)
+
 
 def build_ctx(
     *,