supython 0.1.6__tar.gz → 0.1.7__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: supython
-Version: 0.1.6
+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
@@ -418,6 +418,24 @@ 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
@@ -490,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.6 → supython-0.1.7}/README.md

@@ -360,6 +360,24 @@ 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
@@ -432,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.6 → supython-0.1.7}/pyproject.toml

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

{supython-0.1.6 → 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(
     *,