fastapi-startkit-auth 0.3.0__py3-none-any.whl

fastapi_startkit_auth/routes.py

@@ -0,0 +1,362 @@
+from __future__ import annotations
+
+import base64
+import binascii
+from typing import Any
+from urllib.parse import urlencode
+
+from fastapi import APIRouter, Depends, Form, Request, Response
+from pydantic import BaseModel
+
+from .clients.models import Client
+from .dependencies import current_user, get_auth_manager
+from .exceptions import (
+    InvalidClient,
+    InvalidGrant,
+    InvalidRequest,
+    ThrottleException,
+    UnauthorizedClient,
+    UnsupportedGrantType,
+)
+from .manager import AuthManager
+
+
+# --- request bodies ------------------------------------------------------
+class ClientCreate(BaseModel):
+    name: str
+    redirect_uris: list[str] = []
+    confidential: bool = True
+    grant_types: list[str] = []
+
+
+class AuthorizeRequest(BaseModel):
+    client_id: str
+    redirect_uri: str | None = None
+    scope: str = ""
+    state: str | None = None
+    code_challenge: str | None = None
+    code_challenge_method: str | None = "S256"
+
+
+class PersonalAccessTokenCreate(BaseModel):
+    name: str
+    scopes: list[str] = []
+
+
+class ForgotPasswordRequest(BaseModel):
+    email: str
+
+
+class ResetPasswordRequest(BaseModel):
+    email: str
+    token: str
+    password: str
+
+
+def _scopes(raw: str | None) -> list[str]:
+    return [s for s in (raw or "").split() if s]
+
+
+def _client_credentials_from_request(
+    request: Request, client_id: str | None, client_secret: str | None
+) -> tuple[str | None, str | None]:
+    """Prefer HTTP Basic auth for client credentials, falling back to form fields."""
+    header = request.headers.get("authorization", "")
+    if header.lower().startswith("basic "):
+        try:
+            decoded = base64.b64decode(header[6:]).decode("utf-8")
+            cid, _, secret = decoded.partition(":")
+            return cid, secret
+        except (binascii.Error, UnicodeDecodeError):
+            raise InvalidClient("Malformed Basic authorization header.")
+    return client_id, client_secret
+
+
+def _authenticate_client(manager: AuthManager, client_id: str, secret: str | None, grant: str) -> Client:
+    client = manager.client_repository.authenticate(client_id, secret)
+    if client is None:
+        raise InvalidClient("Client authentication failed.")
+    if not client.allows_grant(grant):
+        raise UnauthorizedClient(f"Client is not authorized for the {grant} grant.")
+    return client
+
+
+def _require_authenticated_client(
+    manager: AuthManager, request: Request, client_id: str | None, client_secret: str | None
+) -> Client:
+    """Authenticate the calling client for the introspection/revocation endpoints."""
+    client_id, client_secret = _client_credentials_from_request(request, client_id, client_secret)
+    if not client_id:
+        raise InvalidClient("Client authentication is required.")
+    client = manager.client_repository.authenticate(client_id, client_secret)
+    if client is None:
+        raise InvalidClient("Client authentication failed.")
+    return client
+
+
+def build_router(prefix: str = "") -> APIRouter:
+    """Build the OAuth2/Passport router. Mounted onto the app by AuthProvider."""
+    router = APIRouter(prefix=prefix)
+
+    # --- unified token endpoint (RFC 6749 §3.2) -----------------------
+    @router.post("/oauth/token")
+    async def token(
+        request: Request,
+        grant_type: str = Form(...),
+        username: str | None = Form(None),
+        password: str | None = Form(None),
+        scope: str | None = Form(None),
+        refresh_token: str | None = Form(None),
+        code: str | None = Form(None),
+        redirect_uri: str | None = Form(None),
+        code_verifier: str | None = Form(None),
+        client_id: str | None = Form(None),
+        client_secret: str | None = Form(None),
+        manager: AuthManager = Depends(get_auth_manager),
+    ) -> dict[str, Any]:
+        client_id, client_secret = _client_credentials_from_request(request, client_id, client_secret)
+        scopes = _scopes(scope)
+
+        if grant_type == "password":
+            if client_id:
+                _authenticate_client(manager, client_id, client_secret, "password")
+            issued = manager.password_grant().handle(
+                username=username or "", password=password or "", scopes=scopes, client_id=client_id
+            )
+            return issued.to_response()
+
+        if grant_type == "client_credentials":
+            if not client_id:
+                raise InvalidClient("client_id is required for the client_credentials grant.")
+            client = _authenticate_client(manager, client_id, client_secret, "client_credentials")
+            return manager.client_credentials_grant().handle(client=client, scopes=scopes).to_response()
+
+        if grant_type == "refresh_token":
+            if not refresh_token:
+                raise InvalidRequest("refresh_token is required.")
+            if client_id:
+                _authenticate_client(manager, client_id, client_secret, "refresh_token")
+            return manager.refresh_grant().handle(
+                refresh_token=refresh_token, scopes=scopes or None
+            ).to_response()
+
+        if grant_type == "authorization_code":
+            if not code:
+                raise InvalidRequest("code is required.")
+            if not client_id:
+                raise InvalidClient("client_id is required for the authorization_code grant.")
+            client = manager.client_repository.find(client_id)
+            if client is None:
+                raise InvalidClient("Unknown client.")
+            client_authenticated = False
+            if client.confidential:
+                _authenticate_client(manager, client_id, client_secret, "authorization_code")
+                client_authenticated = True
+            issued = manager.authorization_code_grant().handle(
+                client=client,
+                code=code,
+                redirect_uri=redirect_uri,
+                code_verifier=code_verifier,
+                client_authenticated=client_authenticated,
+            )
+            return issued.to_response()
+
+        raise UnsupportedGrantType(f"Unsupported grant_type: {grant_type!r}")
+
+    # --- simple password endpoint (FastAPI tutorial style) ------------
+    @router.post("/token")
+    async def simple_token(
+        username: str = Form(...),
+        password: str = Form(...),
+        scope: str | None = Form(None),
+        manager: AuthManager = Depends(get_auth_manager),
+    ) -> dict[str, Any]:
+        issued = manager.password_grant().handle(
+            username=username, password=password, scopes=_scopes(scope), client_id=None
+        )
+        return issued.to_response()
+
+    # --- authorization endpoint (code + PKCE) -------------------------
+    @router.post("/oauth/authorize")
+    async def authorize(
+        body: AuthorizeRequest,
+        user=Depends(current_user),
+        manager: AuthManager = Depends(get_auth_manager),
+    ) -> dict[str, Any]:
+        client = manager.client_repository.find(body.client_id)
+        if client is None:
+            raise InvalidClient("Unknown client.")
+        if body.redirect_uri is not None and not client.allows_redirect(body.redirect_uri):
+            raise InvalidRequest("redirect_uri is not registered for this client.")
+        user_id = manager.guard().provider.get_identifier(user)
+        code = manager.authorization_code_grant().issue_code(
+            client=client,
+            user_id=user_id,
+            scopes=_scopes(body.scope),
+            redirect_uri=body.redirect_uri,
+            code_challenge=body.code_challenge,
+            code_challenge_method=body.code_challenge_method,
+        )
+        result: dict[str, Any] = {"code": code, "state": body.state}
+        if body.redirect_uri:
+            sep = "&" if "?" in body.redirect_uri else "?"
+            params = {"code": code}
+            if body.state is not None:
+                params["state"] = body.state
+            result["redirect_to"] = f"{body.redirect_uri}{sep}{urlencode(params)}"
+        return result
+
+    # --- introspection (RFC 7662) -------------------------------------
+    @router.post("/oauth/introspect")
+    async def introspect(
+        request: Request,
+        token: str = Form(...),
+        client_id: str | None = Form(None),
+        client_secret: str | None = Form(None),
+        manager: AuthManager = Depends(get_auth_manager),
+    ) -> dict[str, Any]:
+        _require_authenticated_client(manager, request, client_id, client_secret)
+        return manager.token_service.introspect(token)
+
+    # --- revocation (RFC 7009) ----------------------------------------
+    @router.post("/oauth/revoke")
+    async def revoke(
+        request: Request,
+        token: str = Form(...),
+        token_type_hint: str | None = Form(None),
+        client_id: str | None = Form(None),
+        client_secret: str | None = Form(None),
+        manager: AuthManager = Depends(get_auth_manager),
+    ) -> dict[str, Any]:
+        _require_authenticated_client(manager, request, client_id, client_secret)
+        svc = manager.token_service
+        # Try refresh first when hinted; otherwise decode as an access token.
+        if token_type_hint == "refresh_token":
+            svc.revoke_refresh(token)
+            return {"revoked": True}
+        try:
+            claims = svc.encoder.decode(token, verify_exp=False)
+            svc.revoke_access(claims.get("jti", ""))
+        except Exception:
+            svc.revoke_refresh(token)
+        return {"revoked": True}
+
+    # --- client management --------------------------------------------
+    @router.post("/oauth/clients", status_code=201)
+    async def create_client(
+        body: ClientCreate,
+        manager: AuthManager = Depends(get_auth_manager),
+    ) -> dict[str, Any]:
+        client, secret = manager.client_repository.register(
+            name=body.name,
+            redirect_uris=body.redirect_uris,
+            confidential=body.confidential,
+            grant_types=body.grant_types,
+        )
+        return {
+            "id": client.id,
+            "name": client.name,
+            "secret": secret,
+            "redirect_uris": client.redirect_uris,
+            "confidential": client.confidential,
+            "grant_types": client.grant_types,
+        }
+
+    @router.get("/oauth/clients")
+    async def list_clients(manager: AuthManager = Depends(get_auth_manager)) -> list[dict[str, Any]]:
+        return [
+            {
+                "id": c.id,
+                "name": c.name,
+                "redirect_uris": c.redirect_uris,
+                "confidential": c.confidential,
+                "grant_types": c.grant_types,
+            }
+            for c in manager.client_repository.all()
+        ]
+
+    @router.delete("/oauth/clients/{client_id}", status_code=204)
+    async def delete_client(
+        client_id: str, manager: AuthManager = Depends(get_auth_manager)
+    ) -> Response:
+        manager.client_repository.delete(client_id)
+        return Response(status_code=204)
+
+    # --- personal access tokens ---------------------------------------
+    @router.post("/oauth/personal-access-tokens", status_code=201)
+    async def create_pat(
+        body: PersonalAccessTokenCreate,
+        user=Depends(current_user),
+        manager: AuthManager = Depends(get_auth_manager),
+    ) -> dict[str, Any]:
+        user_id = manager.guard().provider.get_identifier(user)
+        issued = manager.token_service.create_personal_access_token(
+            user_id=user_id, name=body.name, scopes=body.scopes
+        )
+        return {
+            "jti": issued.jti,
+            "name": body.name,
+            "access_token": issued.access_token,
+            "scopes": issued.scopes,
+            "expires_in": issued.expires_in,
+        }
+
+    @router.get("/oauth/personal-access-tokens")
+    async def list_pats(
+        user=Depends(current_user),
+        manager: AuthManager = Depends(get_auth_manager),
+    ) -> list[dict[str, Any]]:
+        user_id = manager.guard().provider.get_identifier(user)
+        records = manager.token_service.repository.list_access_tokens(user_id, personal_access=True)
+        return [
+            {"jti": r.jti, "name": r.name, "scopes": r.scopes, "revoked": r.revoked}
+            for r in records
+            if not r.revoked
+        ]
+
+    @router.delete("/oauth/personal-access-tokens/{jti}", status_code=204)
+    async def delete_pat(
+        jti: str,
+        user=Depends(current_user),
+        manager: AuthManager = Depends(get_auth_manager),
+    ) -> Response:
+        record = manager.token_service.repository.find_access_token(jti)
+        user_id = manager.guard().provider.get_identifier(user)
+        # Only allow owners to revoke their own tokens.
+        if record is not None and record.user_id == user_id:
+            manager.token_service.revoke_access(jti)
+        return Response(status_code=204)
+
+    # --- password reset -----------------------------------------------
+    @router.post("/password/email")
+    async def send_reset_link(
+        body: ForgotPasswordRequest,
+        manager: AuthManager = Depends(get_auth_manager),
+    ) -> dict[str, Any]:
+        # Always respond identically whether or not the email exists, so the
+        # endpoint can't be used to enumerate accounts. The token is delivered
+        # out-of-band via the configured notifier, never in the HTTP response
+        # (unless debug_expose_reset_token is explicitly enabled).
+        #
+        # A throttled request is also swallowed to a generic 200: throttling only
+        # fires for existing accounts, so surfacing a 429 would let two rapid
+        # requests distinguish registered from unregistered emails. The broker
+        # still enforces the throttle server-side (no extra notification is sent).
+        generic = {"status": "If that account exists, a reset link has been sent."}
+        try:
+            token = manager.broker().send_reset_link(body.email)
+        except (InvalidGrant, ThrottleException):
+            return generic
+        if manager.debug_expose_reset_token:
+            return {**generic, "token": token}
+        return generic
+
+    @router.post("/password/reset")
+    async def reset_password(
+        body: ResetPasswordRequest,
+        manager: AuthManager = Depends(get_auth_manager),
+    ) -> dict[str, Any]:
+        manager.broker().reset(body.email, body.token, body.password)
+        return {"status": "password reset"}
+
+    return router

fastapi_startkit_auth/routes_spa.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends, Request, Response
+
+from .dependencies import get_auth_manager
+from .manager import AuthManager
+from .sessions.state import FORGET_KEY, SESSION_KEY
+
+
+def build_spa_router(prefix: str = "") -> APIRouter:
+    router = APIRouter(prefix=prefix)
+
+    @router.get("/__auth__/csrf-cookie", status_code=204)
+    def csrf_cookie(request: Request, manager: AuthManager = Depends(get_auth_manager)) -> Response:
+        """Prime a SPA for cookie auth (``axios.get("/__auth__/csrf-cookie")``).
+
+        Ensures a session exists — starting a guest one (no user) when the
+        request carries none — so the middleware pair can deliver both the
+        HttpOnly session cookie and the JS-readable CSRF cookie on the way out.
+        """
+        record = getattr(request.state, SESSION_KEY, None)
+        if record is None:
+            record = manager.session_store.create(
+                user_id=None,
+                guard=manager.session_guard_name(),
+                ttl=manager.session_config.get("ttl"),
+            )
+            setattr(request.state, SESSION_KEY, record)
+            setattr(request.state, FORGET_KEY, False)
+        # no-store: the response's only payload is Set-Cookie material; caching
+        # it would hand a shared cache a session bootstrap.
+        return Response(status_code=204, headers={"Cache-Control": "no-store"})
+
+    return router

fastapi_startkit_auth/security/__init__.py

@@ -0,0 +1,4 @@
+from .hashing import BcryptHasher, Hasher
+from .jwt import JWTEncoder
+
+__all__ = ["BcryptHasher", "Hasher", "JWTEncoder"]

fastapi_startkit_auth/security/hashing.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+import base64
+import hashlib
+from typing import Protocol, runtime_checkable
+
+import bcrypt
+
+
+@runtime_checkable
+class Hasher(Protocol):
+    """Password hashing contract. Swap implementations via the auth config."""
+
+    def make(self, plain: str) -> str: ...
+
+    def verify(self, plain: str, hashed: str) -> bool: ...
+
+
+class BcryptHasher:
+    """bcrypt hasher used in place of passlib.
+
+    passlib is avoided because it imports the stdlib ``crypt`` module, removed in
+    Python 3.13. Inputs are SHA-256 pre-hashed and base64-encoded so passwords
+    longer than bcrypt's 72-byte limit remain fully significant rather than being
+    silently truncated.
+    """
+
+    def __init__(self, rounds: int = 12) -> None:
+        self._rounds = rounds
+
+    def _prepare(self, plain: str) -> bytes:
+        digest = hashlib.sha256(plain.encode("utf-8")).digest()
+        return base64.b64encode(digest)
+
+    def make(self, plain: str) -> str:
+        salt = bcrypt.gensalt(self._rounds)
+        return bcrypt.hashpw(self._prepare(plain), salt).decode("utf-8")
+
+    def verify(self, plain: str, hashed: str) -> bool:
+        try:
+            return bcrypt.checkpw(self._prepare(plain), hashed.encode("utf-8"))
+        except (ValueError, TypeError):
+            return False

fastapi_startkit_auth/security/jwt.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+import time
+import uuid
+from typing import Any
+
+import jwt
+
+from ..exceptions import InvalidToken
+
+
+class JWTEncoder:
+    """Encode/decode signed JWTs for access tokens.
+
+    Every token gets a unique ``jti`` so it can be individually revoked and
+    introspected even though JWT verification itself is stateless.
+    """
+
+    def __init__(self, secret: str, algorithm: str = "HS256", leeway: int = 0) -> None:
+        if not secret:
+            raise ValueError("JWTEncoder requires a non-empty secret")
+        self._secret = secret
+        self._algorithm = algorithm
+        self._leeway = leeway
+
+    def encode(self, claims: dict[str, Any], ttl_seconds: int) -> str:
+        now = int(time.time())
+        payload = {
+            "iat": now,
+            "nbf": now,
+            "exp": now + ttl_seconds,
+            "jti": uuid.uuid4().hex,
+            **claims,
+        }
+        return jwt.encode(payload, self._secret, algorithm=self._algorithm)
+
+    def decode(self, token: str, verify_exp: bool = True) -> dict[str, Any]:
+        try:
+            return jwt.decode(
+                token,
+                self._secret,
+                algorithms=[self._algorithm],
+                leeway=self._leeway,
+                # sub may be null (client-credentials tokens have no user); we
+                # never rely on PyJWT's built-in sub type check.
+                options={"verify_exp": verify_exp, "verify_sub": False},
+            )
+        except jwt.PyJWTError as exc:
+            raise InvalidToken(str(exc)) from exc

fastapi_startkit_auth/sessions/__init__.py

@@ -0,0 +1,5 @@
+from .models import SessionRecord
+from .sql import SqlSessionStore
+from .store import InMemorySessionStore, SessionStore
+
+__all__ = ["SessionRecord", "SessionStore", "InMemorySessionStore", "SqlSessionStore"]

fastapi_startkit_auth/sessions/models.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class SessionRecord:
+    """Server-side record backing one session cookie.
+
+    The cookie carries only the opaque ``id``; everything else lives in the
+    store, so invalidation is authoritative. ``csrf_token`` is issued here so
+    Phase 2's CSRF protection can bind to the session without a model change.
+    """
+
+    id: str
+    user_id: Any
+    guard: str
+    csrf_token: str
+    created_at: float = field(default_factory=time.time)
+    last_activity: float = field(default_factory=time.time)
+    expires_at: float | None = None
+
+    def expired(self, idle_ttl: float | None = None, now: float | None = None) -> bool:
+        now = time.time() if now is None else now
+        if self.expires_at is not None and self.expires_at < now:
+            return True
+        return idle_ttl is not None and self.last_activity + idle_ttl < now

fastapi_startkit_auth/sessions/sql.py

@@ -0,0 +1,158 @@
+from __future__ import annotations
+
+import json
+import threading
+import time
+from typing import Any
+
+from .models import SessionRecord
+from .store import generate_csrf_token, generate_session_id
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS {table} (
+    id TEXT PRIMARY KEY,
+    user_id TEXT,
+    guard TEXT NOT NULL,
+    csrf_token TEXT NOT NULL,
+    created_at REAL NOT NULL,
+    last_activity REAL NOT NULL,
+    expires_at REAL
+)
+"""
+
+
+class SqlSessionStore:
+    """Persistent :class:`~.store.SessionStore` backed by a ``sessions`` table.
+
+    Works with any DB-API 2.0 connection using ``qmark`` placeholders (sqlite3
+    out of the box). ``user_id`` is JSON-encoded so int and str identifiers
+    round-trip with their original type, matching the in-memory store. A lock
+    serialises access because FastAPI runs sync endpoints in a thread pool.
+    """
+
+    def __init__(
+        self,
+        connection: Any,
+        table: str = "sessions",
+        idle_ttl: float | None = None,
+        create_table: bool = True,
+        purge_interval: float = 300,
+    ) -> None:
+        self._conn = connection
+        self._table = table
+        self._idle_ttl = idle_ttl
+        self._lock = threading.Lock()
+        self._purge_interval = purge_interval
+        self._last_purge = time.time()
+        if create_table:
+            with self._lock:
+                self._conn.execute(_SCHEMA.format(table=table))
+                self._conn.commit()
+
+    def _maybe_purge(self) -> None:
+        """Drop expired rows periodically so the table stays bounded without a
+        scheduler (mirrors ``TokenService``'s purge-on-issue)."""
+        now = time.time()
+        # Check-and-update under the lock so concurrent creates cannot both
+        # claim the same purge window and sweep twice.
+        with self._lock:
+            if now - self._last_purge < self._purge_interval:
+                return
+            self._last_purge = now
+        self.purge_expired()
+
+    def create(self, *, user_id: Any, guard: str, ttl: float | None) -> SessionRecord:
+        self._maybe_purge()
+        now = time.time()
+        record = SessionRecord(
+            id=generate_session_id(),
+            user_id=user_id,
+            guard=guard,
+            csrf_token=generate_csrf_token(),
+            created_at=now,
+            last_activity=now,
+            expires_at=(now + ttl) if ttl is not None else None,
+        )
+        with self._lock:
+            self._conn.execute(
+                f"INSERT INTO {self._table} (id, user_id, guard, csrf_token, created_at, last_activity, expires_at) "
+                "VALUES (?, ?, ?, ?, ?, ?, ?)",
+                (
+                    record.id,
+                    json.dumps(record.user_id),
+                    record.guard,
+                    record.csrf_token,
+                    record.created_at,
+                    record.last_activity,
+                    record.expires_at,
+                ),
+            )
+            self._conn.commit()
+        return record
+
+    def find(self, session_id: str) -> SessionRecord | None:
+        with self._lock:
+            row = self._conn.execute(
+                f"SELECT id, user_id, guard, csrf_token, created_at, last_activity, expires_at "
+                f"FROM {self._table} WHERE id = ?",
+                (session_id,),
+            ).fetchone()
+        if row is None:
+            return None
+        record = SessionRecord(
+            id=row[0],
+            user_id=json.loads(row[1]),
+            guard=row[2],
+            csrf_token=row[3],
+            created_at=row[4],
+            last_activity=row[5],
+            expires_at=row[6],
+        )
+        if record.expired(self._idle_ttl):
+            self.invalidate(session_id)
+            return None
+        return record
+
+    def touch(self, session_id: str) -> None:
+        with self._lock:
+            self._conn.execute(
+                f"UPDATE {self._table} SET last_activity = ? WHERE id = ?",
+                (time.time(), session_id),
+            )
+            self._conn.commit()
+
+    def regenerate_id(self, session_id: str) -> SessionRecord | None:
+        record = self.find(session_id)
+        if record is None:
+            return None
+        new_id = generate_session_id()
+        with self._lock:
+            self._conn.execute(
+                f"UPDATE {self._table} SET id = ? WHERE id = ?",
+                (new_id, session_id),
+            )
+            self._conn.commit()
+        record.id = new_id
+        return record
+
+    def invalidate(self, session_id: str) -> bool:
+        with self._lock:
+            cursor = self._conn.execute(
+                f"DELETE FROM {self._table} WHERE id = ?", (session_id,)
+            )
+            self._conn.commit()
+        return cursor.rowcount > 0
+
+    def purge_expired(self) -> None:
+        now = time.time()
+        with self._lock:
+            self._conn.execute(
+                f"DELETE FROM {self._table} WHERE expires_at IS NOT NULL AND expires_at < ?",
+                (now,),
+            )
+            if self._idle_ttl is not None:
+                self._conn.execute(
+                    f"DELETE FROM {self._table} WHERE last_activity + ? < ?",
+                    (self._idle_ttl, now),
+                )
+            self._conn.commit()