supython 0.1.3__tar.gz → 0.1.4__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: supython
-Version: 0.1.3
+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)
@@ -418,7 +418,7 @@ 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
+### 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
@@ -449,6 +449,38 @@ Notes:
 - 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.3 → 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)
@@ -360,7 +360,7 @@ 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
+### 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
@@ -391,6 +391,38 @@ Notes:
 - 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.3 → supython-0.1.4}/pyproject.toml

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

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/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.3/src/supython/auth/__init__.py

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