supython 0.1.2__tar.gz → 0.1.4__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: supython
-Version: 0.1.2
+Version: 0.1.4
 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
@@ -58,7 +58,7 @@ Description-Content-Type: text/markdown
 
 # supython
 
-> A lightweight, Postgres-first BaaS framework for Python. **v0.1.2 release**
+> A lightweight, Postgres-first BaaS framework for Python. **v0.1.4 release**
 
 **the database owns the schema, Python owns the things SQL is bad at**. 
 It leans on [PostgREST](https://postgrest.org)
@@ -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,69 @@ 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 [shipped v0.1.3]
+
+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.
+
+### Reading the caller in your routes [shipped v0.1.4]
+
+Application code mounts its own routers alongside supython's. To gate an
+endpoint on a valid bearer token — or to read custom claims out of it —
+use the public dependencies re-exported from `supython.auth`:
+
+```python
+from typing import Annotated
+from uuid import UUID
+
+from fastapi import APIRouter, Depends
+from supython.auth import current_claims, current_user_id
+
+router = APIRouter(prefix="/api/v1")
+
+
+@router.get("/me")
+async def me(user_id: Annotated[UUID, Depends(current_user_id)]) -> dict:
+    return {"user_id": str(user_id)}
+
+
+@router.get("/whoami")
+async def whoami(claims: Annotated[dict, Depends(current_claims)]) -> dict:
+    # Read whatever your `claims_provider` injected — e.g. org_id.
+    return {"user_id": claims["sub"], "org_id": claims.get("org_id")}
+```
+
+Both dependencies raise `401 Unauthorized` when the `Authorization` header
+is missing, malformed, or carries an invalid/expired token. `current_user_id`
+is a thin convenience over `current_claims` — pick the dict version when you
+need any claim beyond the user UUID.
+
 ### Auth hardening settings (`.env`)
 
 | Variable | Default | Purpose |

{supython-0.1.2 → supython-0.1.4}/README.md

@@ -1,6 +1,6 @@
 # supython
 
-> A lightweight, Postgres-first BaaS framework for Python. **v0.1.2 release**
+> A lightweight, Postgres-first BaaS framework for Python. **v0.1.4 release**
 
 **the database owns the schema, Python owns the things SQL is bad at**. 
 It leans on [PostgREST](https://postgrest.org)
@@ -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,69 @@ 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 [shipped v0.1.3]
+
+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.
+
+### Reading the caller in your routes [shipped v0.1.4]
+
+Application code mounts its own routers alongside supython's. To gate an
+endpoint on a valid bearer token — or to read custom claims out of it —
+use the public dependencies re-exported from `supython.auth`:
+
+```python
+from typing import Annotated
+from uuid import UUID
+
+from fastapi import APIRouter, Depends
+from supython.auth import current_claims, current_user_id
+
+router = APIRouter(prefix="/api/v1")
+
+
+@router.get("/me")
+async def me(user_id: Annotated[UUID, Depends(current_user_id)]) -> dict:
+    return {"user_id": str(user_id)}
+
+
+@router.get("/whoami")
+async def whoami(claims: Annotated[dict, Depends(current_claims)]) -> dict:
+    # Read whatever your `claims_provider` injected — e.g. org_id.
+    return {"user_id": claims["sub"], "org_id": claims.get("org_id")}
+```
+
+Both dependencies raise `401 Unauthorized` when the `Authorization` header
+is missing, malformed, or carries an invalid/expired token. `current_user_id`
+is a thin convenience over `current_claims` — pick the dict version when you
+need any claim beyond the user UUID.
+
 ### Auth hardening settings (`.env`)
 
 | Variable | Default | Purpose |

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

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

{supython-0.1.2 → supython-0.1.4}/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.4/src/supython/auth/__init__.py

@@ -0,0 +1,4 @@
+from . import _email_job, router
+from .deps import current_claims, current_user_id
+
+__all__ = ["current_claims", "current_user_id", "router"]

supython-0.1.4/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.4/src/supython/auth/deps.py

@@ -0,0 +1,57 @@
+"""Public FastAPI dependencies for downstream apps.
+
+These are the supported way for application code to read the authenticated
+caller out of an incoming request — equivalent to the auth router's private
+``_current_user_id`` but stable, re-exported, and documented.
+
+Usage::
+
+    from typing import Annotated
+    from uuid import UUID
+
+    from fastapi import Depends
+    from supython.auth import current_user_id, current_claims
+
+    @router.get("/me")
+    async def me(user_id: Annotated[UUID, Depends(current_user_id)]):
+        ...
+
+    @router.get("/whoami")
+    async def whoami(claims: Annotated[dict, Depends(current_claims)]):
+        return {"org_id": claims.get("org_id")}
+"""
+
+from typing import Annotated, Any
+from uuid import UUID
+
+import jwt
+from fastapi import Depends, Header, HTTPException, status
+
+from .. import tokens
+
+
+async def current_claims(
+    authorization: Annotated[str | None, Header()] = None,
+) -> dict[str, Any]:
+    """Return the decoded JWT claims of the bearer token, or 401."""
+    if not authorization or not authorization.lower().startswith("bearer "):
+        raise HTTPException(status.HTTP_401_UNAUTHORIZED, "Missing bearer token")
+    token = authorization.split(" ", 1)[1]
+    try:
+        return tokens.decode_access_token(token)
+    except jwt.PyJWTError as exc:
+        raise HTTPException(
+            status.HTTP_401_UNAUTHORIZED, f"Invalid token: {exc}"
+        ) from exc
+
+
+async def current_user_id(
+    claims: Annotated[dict[str, Any], Depends(current_claims)],
+) -> UUID:
+    """Return the authenticated user's UUID from the bearer token, or 401."""
+    try:
+        return UUID(claims["sub"])
+    except (KeyError, ValueError) as exc:
+        raise HTTPException(
+            status.HTTP_401_UNAUTHORIZED, "Token missing valid sub claim"
+        ) from exc

{supython-0.1.2 → supython-0.1.4}/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
 
 

supython-0.1.2/src/supython/auth/__init__.py

@@ -1,3 +0,0 @@
-from . import _email_job, router
-
-__all__ = ["router"]