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

fastapi_startkit_auth/middleware/session.py

@@ -0,0 +1,117 @@
+from __future__ import annotations
+
+from http.cookies import SimpleCookie
+from typing import Any
+
+from starlette.datastructures import MutableHeaders
+from starlette.responses import Response
+from starlette.types import ASGIApp, Message, Receive, Scope, Send
+
+from ..sessions.state import FORGET_KEY, LOADED_ID_KEY, SESSION_KEY
+from ..sessions.store import SessionStore
+
+
+class SessionMiddleware:
+    """Loads the server-side session from the cookie and issues the cookie back.
+
+    Before the app runs: parse the configured cookie, look the id up in the
+    store, and attach the live :class:`SessionRecord` (or ``None``) to
+    ``request.state``. After the app decides (via ``Auth.login`` / ``logout``):
+
+    - a session with an id different from the incoming cookie gets ``Set-Cookie``
+      with the configured flags (HttpOnly / SameSite / Secure);
+    - an explicit logout — or a stale cookie that resolved to no session —
+      gets a deletion ``Set-Cookie``.
+    """
+
+    def __init__(
+        self,
+        app: ASGIApp,
+        store: SessionStore,
+        cookie: str = "startkit_session",
+        ttl: float | None = 7200,
+        http_only: bool = True,
+        same_site: str = "lax",
+        secure: bool = True,
+        domain: str | None = None,
+        path: str = "/",
+    ) -> None:
+        self.app = app
+        self.store = store
+        self.cookie = cookie
+        self.ttl = ttl
+        self.http_only = http_only
+        self.same_site = same_site
+        self.secure = secure
+        self.domain = domain
+        self.path = path
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] != "http":
+            await self.app(scope, receive, send)
+            return
+
+        state = scope.setdefault("state", {})
+        incoming_id = self._read_cookie(scope)
+        record = self.store.find(incoming_id) if incoming_id else None
+        if record is not None:
+            self.store.touch(record.id)
+        state[SESSION_KEY] = record
+        state[LOADED_ID_KEY] = incoming_id
+        state[FORGET_KEY] = False
+
+        async def send_wrapper(message: Message) -> None:
+            if message["type"] == "http.response.start":
+                header = self._cookie_header(state)
+                if header is not None:
+                    MutableHeaders(scope=message).append("set-cookie", header)
+            await send(message)
+
+        await self.app(scope, receive, send_wrapper)
+
+    def _read_cookie(self, scope: Scope) -> str | None:
+        raw = next(
+            (value for name, value in scope.get("headers", []) if name == b"cookie"),
+            None,
+        )
+        if raw is None:
+            return None
+        jar: SimpleCookie = SimpleCookie()
+        jar.load(raw.decode("latin-1"))
+        morsel = jar.get(self.cookie)
+        return morsel.value if morsel is not None else None
+
+    def _cookie_header(self, state: dict[str, Any]) -> str | None:
+        record = state.get(SESSION_KEY)
+        incoming_id = state.get(LOADED_ID_KEY)
+        response = Response()
+        if record is not None:
+            if record.id == incoming_id:
+                return None
+            response.set_cookie(
+                self.cookie,
+                record.id,
+                max_age=int(self.ttl) if self.ttl is not None else None,
+                path=self.path,
+                domain=self.domain,
+                secure=self.secure,
+                httponly=self.http_only,
+                samesite=self.same_site,
+            )
+        elif state.get(FORGET_KEY) or incoming_id:
+            # Explicit logout, or a cookie that resolved to no live session.
+            response.delete_cookie(
+                self.cookie,
+                path=self.path,
+                domain=self.domain,
+                secure=self.secure,
+                httponly=self.http_only,
+                samesite=self.same_site,
+            )
+        else:
+            return None
+        return next(
+            value.decode("latin-1")
+            for name, value in response.raw_headers
+            if name == b"set-cookie"
+        )

fastapi_startkit_auth/passwords/__init__.py

@@ -0,0 +1,4 @@
+from .broker import PasswordBroker
+from .repository import InMemoryPasswordResetRepository, PasswordResetToken
+
+__all__ = ["PasswordBroker", "InMemoryPasswordResetRepository", "PasswordResetToken"]

fastapi_startkit_auth/passwords/broker.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+import secrets
+from typing import Callable
+
+from ..exceptions import InvalidGrant, ThrottleException
+from ..providers.base import UserProvider
+from ..security.hashing import BcryptHasher, Hasher
+from .repository import InMemoryPasswordResetRepository
+
+
+class PasswordBroker:
+    """Password reset flow backed by the ``password_reset_tokens`` table.
+
+    Tokens are stored hashed, expire after ``expire_minutes``, and are
+    rate-limited per user by ``throttle_seconds`` — matching Laravel's broker.
+    The plaintext token is returned from ``send_reset_link`` so the caller can
+    deliver it (e.g. by email); only its hash is persisted.
+    """
+
+    def __init__(
+        self,
+        user_provider: UserProvider,
+        repository: InMemoryPasswordResetRepository | None = None,
+        hasher: Hasher | None = None,
+        expire_minutes: int = 60,
+        throttle_seconds: int = 60,
+        notifier: Callable[[str, str], None] | None = None,
+    ) -> None:
+        self._users = user_provider
+        self._repo = repository or InMemoryPasswordResetRepository()
+        self._hasher = hasher or BcryptHasher()
+        self._expire_minutes = expire_minutes
+        self._throttle_seconds = throttle_seconds
+        self._notifier = notifier
+
+    def _find_user(self, email: str):
+        return self._users.retrieve_by_credentials({"email": email, "username": email})
+
+    def send_reset_link(self, email: str) -> str:
+        user = self._find_user(email)
+        if user is None:
+            # Do equivalent hashing work before failing so response timing does
+            # not reveal whether the email is registered.
+            self._hasher.make(secrets.token_urlsafe(40))
+            raise InvalidGrant("We can't find a user with that email address.")
+        if self._repo.recently_created(email, self._throttle_seconds):
+            raise ThrottleException("Please wait before requesting another reset link.")
+        token = secrets.token_urlsafe(40)
+        self._repo.create(email, self._hasher.make(token))
+        if self._notifier is not None:
+            self._notifier(email, token)
+        return token
+
+    def reset(self, email: str, token: str, new_password: str) -> bool:
+        record = self._repo.find(email)
+        if record is None:
+            raise InvalidGrant("This password reset token is invalid.")
+        if record.age() > self._expire_minutes * 60:
+            self._repo.delete(email)
+            raise InvalidGrant("This password reset token has expired.")
+        if not self._hasher.verify(token, record.hashed_token):
+            raise InvalidGrant("This password reset token is invalid.")
+        user = self._find_user(email)
+        if user is None:
+            raise InvalidGrant("We can't find a user with that email address.")
+        self._users.update_password(user, new_password)
+        self._repo.delete(email)
+        return True

fastapi_startkit_auth/passwords/repository.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+
+
+@dataclass
+class PasswordResetToken:
+    """A row in the ``password_reset_tokens`` table."""
+
+    email: str
+    hashed_token: str
+    created_at: float
+
+    def age(self) -> float:
+        return time.time() - self.created_at
+
+
+class InMemoryPasswordResetRepository:
+    """Stores at most one active reset token per identifier (email).
+
+    Mirrors Laravel's ``password_reset_tokens`` table where issuing a new token
+    replaces any previous one for the same user.
+    """
+
+    def __init__(self) -> None:
+        self._tokens: dict[str, PasswordResetToken] = {}
+
+    def create(self, email: str, hashed_token: str) -> PasswordResetToken:
+        rec = PasswordResetToken(email=email, hashed_token=hashed_token, created_at=time.time())
+        self._tokens[email] = rec
+        return rec
+
+    def find(self, email: str) -> PasswordResetToken | None:
+        return self._tokens.get(email)
+
+    def delete(self, email: str) -> None:
+        self._tokens.pop(email, None)
+
+    def recently_created(self, email: str, throttle_seconds: int) -> bool:
+        rec = self._tokens.get(email)
+        if rec is None:
+            return False
+        return rec.age() < throttle_seconds

fastapi_startkit_auth/provider.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse
+
+from .exceptions import AuthError
+from .manager import AuthManager
+from .middleware.csrf import CsrfMiddleware
+from .middleware.session import SessionMiddleware
+from .routes import build_router
+from .routes_spa import build_spa_router
+
+
+async def _auth_error_handler(request: Request, exc: AuthError) -> JSONResponse:
+    headers = {}
+    if exc.status_code == 401:
+        headers["WWW-Authenticate"] = "Bearer"
+    return JSONResponse(status_code=exc.status_code, content=exc.to_dict(), headers=headers)
+
+
+class AuthProvider:
+    """Registers the auth stack onto a FastAPI application.
+
+    Instantiated with an :class:`AuthConfig`, it builds the :class:`AuthManager`,
+    stores it on ``app.state.auth_manager`` (where the dependencies read it),
+    mounts the OAuth2 router, and installs the OAuth2 error handler.
+    """
+
+    def __init__(self, config: Any, prefix: str = "") -> None:
+        self.config = config
+        self.prefix = prefix
+        self.manager = AuthManager(config)
+
+    def register(self, app: FastAPI) -> None:
+        app.state.auth_manager = self.manager
+        app.include_router(build_router(prefix=self.prefix))
+        app.add_exception_handler(AuthError, _auth_error_handler)
+        if self.manager.has_session_guard():
+            session = self.manager.session_config
+            if self.manager.spa_enabled():
+                spa = self.manager.spa_config
+                app.include_router(build_spa_router(prefix=self.prefix))
+                # Added before SessionMiddleware so it ends up inside it and
+                # sees the loaded session on the request state.
+                app.add_middleware(
+                    CsrfMiddleware,
+                    cookie=spa["csrf_cookie"],
+                    header=spa["csrf_header"],
+                    exempt_paths=spa["csrf_exempt_paths"],
+                    stateful_origins=spa["stateful_origins"],
+                    ttl=session["ttl"],
+                    same_site=session["same_site"],
+                    secure=session["secure"],
+                    domain=session["domain"],
+                    path=session["path"],
+                )
+            app.add_middleware(
+                SessionMiddleware,
+                store=self.manager.session_store,
+                cookie=session["cookie"],
+                ttl=session["ttl"],
+                http_only=session["http_only"],
+                same_site=session["same_site"],
+                secure=session["secure"],
+                domain=session["domain"],
+                path=session["path"],
+            )

fastapi_startkit_auth/providers/__init__.py

@@ -0,0 +1,4 @@
+from .base import UserProvider
+from .memory import InMemoryUserProvider
+
+__all__ = ["UserProvider", "InMemoryUserProvider"]

fastapi_startkit_auth/providers/base.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+User = Any
+
+
+@runtime_checkable
+class UserProvider(Protocol):
+    """Retrieves and verifies users from a backing store.
+
+    Kept deliberately small so any store (ORM, in-memory, external service) can
+    implement it. Credential *lookup* is separate from credential *verification*
+    so timing and hashing stay under the provider's control.
+    """
+
+    def retrieve_by_id(self, identifier: Any) -> User | None:
+        """Return the user with this primary identifier, or ``None``."""
+
+    def retrieve_by_credentials(self, credentials: dict[str, Any]) -> User | None:
+        """Find a user by identifying fields (e.g. email); does NOT check the password."""
+
+    def validate_credentials(self, user: User, credentials: dict[str, Any]) -> bool:
+        """Return whether ``credentials`` authenticate ``user``."""
+
+    def dummy_verify(self) -> None:
+        """Burn a credential verification against a throwaway hash.
+
+        Called when ``retrieve_by_credentials`` finds no user, so the
+        absent-user path takes as long as a real password check and login
+        timing does not enumerate accounts.
+        """
+
+    def get_identifier(self, user: User) -> Any:
+        """Return the primary identifier stored in a token's ``sub`` claim."""
+
+    def update_password(self, user: User, plain: str) -> None:
+        """Persist a new hashed password for ``user`` (used by password resets)."""

fastapi_startkit_auth/providers/memory.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+import secrets
+from typing import Any
+
+from ..security.hashing import BcryptHasher, Hasher
+
+
+class InMemoryUserProvider:
+    """Dict-backed user provider for tests, demos, and prototypes.
+
+    Users are plain dicts keyed by an ``id`` field. Real deployments swap this
+    for an ORM-backed provider via the ``providers`` config, but the contract is
+    identical.
+    """
+
+    def __init__(
+        self,
+        hasher: Hasher | None = None,
+        id_field: str = "id",
+        username_field: str = "email",
+        password_field: str = "password",
+    ) -> None:
+        self._hasher = hasher or BcryptHasher()
+        self._id_field = id_field
+        self._username_field = username_field
+        self._password_field = password_field
+        self._users: dict[Any, dict[str, Any]] = {}
+        # Precomputed hash for constant-time verification of absent users.
+        self._dummy_hash = self._hasher.make(secrets.token_urlsafe(16))
+
+    def add(self, user: dict[str, Any]) -> dict[str, Any]:
+        self._users[user[self._id_field]] = user
+        return user
+
+    def create(self, *, password: str, **fields: Any) -> dict[str, Any]:
+        fields[self._password_field] = self._hasher.make(password)
+        return self.add(fields)
+
+    def retrieve_by_id(self, identifier: Any) -> dict[str, Any] | None:
+        return self._users.get(identifier)
+
+    def retrieve_by_credentials(self, credentials: dict[str, Any]) -> dict[str, Any] | None:
+        username = credentials.get(self._username_field)
+        if username is None:
+            return None
+        for user in self._users.values():
+            if user.get(self._username_field) == username:
+                return user
+        return None
+
+    def validate_credentials(self, user: dict[str, Any], credentials: dict[str, Any]) -> bool:
+        if user is None:
+            return False
+        supplied = credentials.get(self._password_field)
+        if supplied is None:
+            return False
+        return self._hasher.verify(supplied, user.get(self._password_field, ""))
+
+    def dummy_verify(self) -> None:
+        """Run a throwaway hash verification to equalise timing for absent users."""
+        self._hasher.verify("invalid", self._dummy_hash)
+
+    def get_identifier(self, user: dict[str, Any]) -> Any:
+        return user[self._id_field]
+
+    def update_password(self, user: dict[str, Any], plain: str) -> None:
+        stored = self._users[user[self._id_field]]
+        stored[self._password_field] = self._hasher.make(plain)

fastapi_startkit_auth/providers/model.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+import secrets
+from typing import Any
+
+from ..security.hashing import BcryptHasher, Hasher
+
+
+def _attr(obj: Any, name: str) -> Any:
+    if isinstance(obj, dict):
+        return obj.get(name)
+    return getattr(obj, name, None)
+
+
+class ModelUserProvider:
+    """User provider backed by an active-record-style model class.
+
+    Works with masoniteorm (``config providers['users']['driver'] = 'masoniteorm'``)
+    and any ORM whose model exposes ``find(id)`` and ``where(field, value).first()``.
+    The model isn't imported here, keeping the ORM an optional dependency.
+    """
+
+    def __init__(
+        self,
+        model: Any,
+        hasher: Hasher | None = None,
+        id_field: str = "id",
+        username_field: str = "email",
+        password_field: str = "password",
+    ) -> None:
+        self._model = model
+        self._hasher = hasher or BcryptHasher()
+        self._id_field = id_field
+        self._username_field = username_field
+        self._password_field = password_field
+        self._dummy_hash = self._hasher.make(secrets.token_urlsafe(16))
+
+    def dummy_verify(self) -> None:
+        """Run a throwaway hash verification to equalise timing for absent users."""
+        self._hasher.verify("invalid", self._dummy_hash)
+
+    def retrieve_by_id(self, identifier: Any) -> Any | None:
+        return self._model.find(identifier)
+
+    def retrieve_by_credentials(self, credentials: dict[str, Any]) -> Any | None:
+        username = credentials.get(self._username_field)
+        if username is None:
+            return None
+        return self._model.where(self._username_field, username).first()
+
+    def validate_credentials(self, user: Any, credentials: dict[str, Any]) -> bool:
+        if user is None:
+            return False
+        supplied = credentials.get(self._password_field)
+        if supplied is None:
+            return False
+        return self._hasher.verify(supplied, _attr(user, self._password_field) or "")
+
+    def get_identifier(self, user: Any) -> Any:
+        return _attr(user, self._id_field)
+
+    def update_password(self, user: Any, plain: str) -> None:
+        hashed = self._hasher.make(plain)
+        if isinstance(user, dict):
+            user[self._password_field] = hashed
+        else:
+            setattr(user, self._password_field, hashed)
+        save = getattr(user, "save", None)
+        if callable(save):
+            save()

fastapi_startkit_auth/publishable/cors.py

@@ -0,0 +1,44 @@
+"""CORS configuration for SPA cookie authentication.
+
+Published into the application as ``config/cors.py`` by::
+
+    python artisan provider:publish -p auth
+
+Cookie-authenticated cross-origin requests require ``allow_credentials=True``,
+and browsers reject a wildcard ``*`` origin when credentials are enabled —
+always list the exact first-party origins here, matching
+``AuthConfig.spa["stateful_origins"]``.
+
+Wire it into Starlette's CORS middleware::
+
+    from starlette.middleware.cors import CORSMiddleware
+    from config import cors
+
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=cors.ALLOW_ORIGINS,
+        allow_credentials=cors.ALLOW_CREDENTIALS,
+        allow_methods=cors.ALLOW_METHODS,
+        allow_headers=cors.ALLOW_HEADERS,
+        expose_headers=cors.EXPOSE_HEADERS,
+        max_age=cors.MAX_AGE,
+    )
+"""
+
+# Exact first-party SPA origins (scheme + host + port). Never use "*" here:
+# credentials would silently stop working in every browser.
+ALLOW_ORIGINS = [
+    "http://localhost:5173",
+]
+
+# Required so the browser sends the session cookie and accepts Set-Cookie.
+ALLOW_CREDENTIALS = True
+
+ALLOW_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"]
+
+# X-XSRF-TOKEN is the CSRF header the auth package's middleware verifies.
+ALLOW_HEADERS = ["Authorization", "Content-Type", "X-XSRF-TOKEN", "X-Requested-With"]
+
+EXPOSE_HEADERS: list[str] = []
+
+MAX_AGE = 600