supython 0.1.6__tar.gz → 0.1.8__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: supython
-Version: 0.1.6
+Version: 0.1.8
 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.8}/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.8}/pyproject.toml

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

{supython-0.1.6 → supython-0.1.8}/src/supython/cli.py

@@ -1355,14 +1355,22 @@ def up(
     timeout: int = typer.Option(30, help="Seconds to wait for Postgres."),
     prod: bool = typer.Option(False, "--prod", help="Use docker-compose.prod.yml."),
     worker: bool = typer.Option(False, "--worker", help="Also start the worker (prod only)."),
+    profile: list[str] = typer.Option(
+        [],
+        "--profile",
+        help="Compose profile(s) to enable. Repeatable; user-defined extension services gated by a profile come up via a final sweep.",
+    ),
 ) -> None:
     """Start Postgres + PostgREST and apply migrations.
 
     Brings the DB up first, runs migrations (which create the roles
     PostgREST needs), rotates the authenticator password, then starts PostgREST.
+    Any user-added services gated behind a compose profile come up after the
+    core services when `--profile <name>` is passed.
     """
     compose_file = _resolve_compose_file(prod)
     is_prod = compose_file == "docker-compose.prod.yml"
+    user_profiles = tuple(profile)
     configure_logging("INFO", json_format=False)
     _compose_with(compose_file, "up", "-d", "db")
     typer.echo("waiting for Postgres ...")
@@ -1379,6 +1387,8 @@ def up(
         _compose_with(compose_file, "up", "-d", "postgrest", "supython")
         if worker:
             _compose_with(compose_file, "--profile", "worker", "up", "-d", "worker")
+        if user_profiles:
+            _compose_with(compose_file, "up", "-d", profiles=user_profiles)
         typer.echo("")
         typer.echo("ready.")
         typer.echo("  postgres   localhost:54322  (bind 127.0.0.1 only)")
@@ -1386,12 +1396,18 @@ def up(
         typer.echo("  supython   http://localhost:8000")
         if worker:
             typer.echo("  worker     running (profile=worker)")
+        for p in user_profiles:
+            typer.echo(f"  profile    {p}   # user-defined services")
     else:
         _compose_with(compose_file, "up", "-d", "postgrest")
+        if user_profiles:
+            _compose_with(compose_file, "up", "-d", profiles=user_profiles)
         typer.echo("")
         typer.echo("ready.")
         typer.echo("  postgres   localhost:54322  (user/db: supython)")
         typer.echo(f"  postgrest  {s.postgrest_url}")
+        for p in user_profiles:
+            typer.echo(f"  profile    {p}   # user-defined services")
         typer.echo("  next       supython dev   # start the auth/API service")
 
 
@@ -1610,11 +1626,15 @@ def _compose(*args: str) -> None:
     _compose_with(None, *args)
 
 
-def _compose_with(file: str | None, *args: str) -> None:
-    """Run `docker compose [-f <file>] <args...>`, surfacing common errors."""
+def _compose_with(
+    file: str | None, *args: str, profiles: tuple[str, ...] = ()
+) -> None:
+    """Run `docker compose [-f <file>] [--profile <p>]... <args...>`, surfacing common errors."""
     cmd = ["docker", "compose"]
     if file:
         cmd += ["-f", file]
+    for p in profiles:
+        cmd += ["--profile", p]
     cmd += list(args)
     try:
         subprocess.run(cmd, check=True)

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