supython 0.1.2__tar.gz → 0.1.3__tar.gz

{supython-0.1.2 → supython-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: supython
-Version: 0.1.2
+Version: 0.1.3
 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
+- **Generic hooks** — `@app.on_signup` / `@app.on_login` lifecycle hooks; `@app.claims_provider` for custom JWT claims
 - **`supython worker run`** — long-running worker with graceful SIGTERM drain
 
 **Operations & security**
@@ -418,6 +418,37 @@ SMTP_PASSWORD`.
 **OAuth** — add `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET` (and/or GitHub
 equivalents) to `.env`. Providers without credentials are silently disabled.
 
+### Custom JWT claims
+
+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.
+
+```python
+from supython.app import app
+
+@app.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
+    )
+    return {"org_id": str(org_id)} if org_id else {}
+```
+
+Notes:
+
+- Reserved JWT claims (`sub`, `email`, `role`, `aud`, `iat`, `exp`, `jti`)
+  cannot be overridden — they are filtered out automatically.
+- Providers run on the **service-role** connection used by the auth flow, so
+  they can read tables that RLS would block during issuance. Treat the
+  function as privileged code (same posture as a Postgres `security definer`
+  routine — sanitize any user-supplied input).
+- A provider that raises aborts issuance: a missing claim is a silent authz
+  bug, not a missing welcome email.
+- Refresh re-collects claims, so a token rotated via `/auth/v1/refresh`
+  reflects current state.
+
 ### Auth hardening settings (`.env`)
 
 | Variable | Default | Purpose |

{supython-0.1.2 → supython-0.1.3}/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
+- **Generic hooks** — `@app.on_signup` / `@app.on_login` lifecycle hooks; `@app.claims_provider` for custom JWT claims
 - **`supython worker run`** — long-running worker with graceful SIGTERM drain
 
 **Operations & security**
@@ -360,6 +360,37 @@ SMTP_PASSWORD`.
 **OAuth** — add `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET` (and/or GitHub
 equivalents) to `.env`. Providers without credentials are silently disabled.
 
+### Custom JWT claims
+
+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.
+
+```python
+from supython.app import app
+
+@app.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
+    )
+    return {"org_id": str(org_id)} if org_id else {}
+```
+
+Notes:
+
+- Reserved JWT claims (`sub`, `email`, `role`, `aud`, `iat`, `exp`, `jti`)
+  cannot be overridden — they are filtered out automatically.
+- Providers run on the **service-role** connection used by the auth flow, so
+  they can read tables that RLS would block during issuance. Treat the
+  function as privileged code (same posture as a Postgres `security definer`
+  routine — sanitize any user-supplied input).
+- A provider that raises aborts issuance: a missing claim is a silent authz
+  bug, not a missing welcome email.
+- Refresh re-collects claims, so a token rotated via `/auth/v1/refresh`
+  reflects current state.
+
 ### Auth hardening settings (`.env`)
 
 | Variable | Default | Purpose |

{supython-0.1.2 → supython-0.1.3}/pyproject.toml

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

{supython-0.1.2 → supython-0.1.3}/src/supython/app.py

@@ -11,6 +11,7 @@ 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
@@ -155,6 +156,7 @@ 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.3/src/supython/auth/claims.py

@@ -0,0 +1,72 @@
+"""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.
+
+Contract (intentionally narrower than ``hooks.fire``):
+
+- Providers run on the **service-role** connection used by the auth flow,
+  so they can read tables that RLS would block during issuance (e.g. a
+  ``user_roles`` lookup keyed by a brand-new user). Treat the function as
+  privileged — same posture as a Postgres ``security definer`` routine.
+- A provider raising propagates: a missing claim is a silent authz bug,
+  not a missing welcome email. ``hooks.fire`` swallows on purpose;
+  ``collect`` does not.
+- Reserved JWT claims (``sub``, ``email``, ``role``, ``aud``, ``iat``,
+  ``exp``, ``jti``) cannot be overridden — they are filtered out of every
+  provider's return value so a misbehaving provider can't mint a token
+  that contradicts its own header or expiry.
+"""
+
+import logging
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+import asyncpg
+
+from .schemas import UserResponse
+
+logger = logging.getLogger(__name__)
+
+ClaimsProvider = Callable[[UserResponse, asyncpg.Connection], Awaitable[dict[str, Any]]]
+
+_RESERVED: frozenset[str] = frozenset(
+    {"sub", "email", "role", "aud", "iat", "exp", "jti"}
+)
+
+_providers: list[ClaimsProvider] = []
+
+
+def register(fn: ClaimsProvider) -> ClaimsProvider:
+    """Register *fn* as a claims provider. Usable as a decorator."""
+    _providers.append(fn)
+    return fn
+
+
+async def collect(user: UserResponse, conn: asyncpg.Connection) -> dict[str, Any]:
+    """Run every registered provider and return the merged claim dict.
+
+    Providers run in registration order; later providers win on key
+    collisions. Reserved JWT claims are stripped from each return value
+    before merging.
+    """
+    merged: dict[str, Any] = {}
+    for fn in _providers:
+        out = await fn(user, conn)
+        if not out:
+            continue
+        for key in _RESERVED.intersection(out):
+            logger.warning(
+                "claims provider %r returned reserved claim %r; dropping",
+                getattr(fn, "__qualname__", fn),
+                key,
+            )
+        merged.update({k: v for k, v in out.items() if k not in _RESERVED})
+    return merged
+
+
+def reset() -> None:
+    """Clear all registered providers. Test-only."""
+    _providers.clear()

{supython-0.1.2 → supython-0.1.3}/src/supython/auth/service.py

@@ -14,6 +14,7 @@ from itsdangerous import BadSignature, URLSafeTimedSerializer
 from .. import mail, passwords, tokens
 from ..mailer import EmailMessage
 from ..settings import get_settings
+from . import claims
 from .schemas import UserResponse
 
 logger = logging.getLogger(__name__)
@@ -63,7 +64,10 @@ async def _audit_log(
 async def _issue_pair(
     conn: asyncpg.Connection, user: UserResponse
 ) -> tuple[str, str, int]:
-    access, ttl = tokens.issue_access_token(user.id, user.email)
+    extra = await claims.collect(user, conn)
+    access, ttl = tokens.issue_access_token(
+        user.id, user.email, extra_claims=extra or None
+    )
     refresh = tokens.issue_refresh_token()
     await conn.execute(
         "insert into auth.refresh_tokens (user_id, token) values ($1, $2)",
@@ -273,7 +277,10 @@ async def refresh_grant(
             new_refresh,
             refresh_token,
         )
-    access, ttl = tokens.issue_access_token(user.id, user.email)
+    extra = await claims.collect(user, conn)
+    access, ttl = tokens.issue_access_token(
+        user.id, user.email, extra_claims=extra or None
+    )
     return user, access, new_refresh, ttl