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

fastapi_startkit_auth/guards/session.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import Request
+
+from ..exceptions import InvalidSession
+from ..providers.base import UserProvider
+from ..sessions.models import SessionRecord
+from ..sessions.state import FORGET_KEY, SESSION_KEY
+from ..sessions.store import SessionStore
+from .guard import AuthContext
+
+
+class SessionGuard:
+    """Cookie/session guard: resolves the server-side session to a user.
+
+    Corresponds to a ``{"driver": "session"}`` guard entry. The middleware puts
+    the loaded :class:`SessionRecord` on ``request.state``; this guard turns it
+    into an :class:`AuthContext` and owns the login/logout primitives used by
+    the ``Auth`` facade. Session-authenticated requests get the wildcard scope,
+    like a first-party browser login.
+    """
+
+    def __init__(self, name: str, store: SessionStore, provider: UserProvider, ttl: float | None) -> None:
+        self.name = name
+        self.store = store
+        self.provider = provider
+        self.ttl = ttl
+
+    def user_from_token(self, access_token: str) -> AuthContext:
+        """Resolve a raw session id (the cookie value) to an ``AuthContext``."""
+        record = self.store.find(access_token)
+        if record is None:
+            raise InvalidSession("Not authenticated.")
+        return self._context(record)
+
+    def authenticate(self, request: Request) -> AuthContext:
+        """Resolve the session attached to the request by the middleware."""
+        record = getattr(request.state, SESSION_KEY, None)
+        if record is None:
+            raise InvalidSession("Not authenticated.")
+        return self._context(record)
+
+    def login(self, request: Request, user: Any) -> SessionRecord:
+        """Start a fresh session for ``user``.
+
+        Always issues a new session id (fixation protection): any session that
+        arrived with the request is invalidated server-side and the middleware
+        sends the new id in the cookie.
+        """
+        previous = getattr(request.state, SESSION_KEY, None)
+        record = self.store.create(
+            user_id=self.provider.get_identifier(user),
+            guard=self.name,
+            ttl=self.ttl,
+        )
+        if previous is not None:
+            self.store.invalidate(previous.id)
+        setattr(request.state, SESSION_KEY, record)
+        setattr(request.state, FORGET_KEY, False)
+        return record
+
+    def logout(self, request: Request) -> None:
+        """Invalidate the server-side session and mark the cookie for deletion."""
+        record = getattr(request.state, SESSION_KEY, None)
+        if record is not None:
+            self.store.invalidate(record.id)
+        setattr(request.state, SESSION_KEY, None)
+        setattr(request.state, FORGET_KEY, True)
+
+    def _context(self, record: SessionRecord) -> AuthContext:
+        if record.user_id is None:
+            # Guest session (issued by /__auth__/csrf-cookie): it carries a CSRF
+            # token but no user, and must survive 401s so the SPA can log in.
+            raise InvalidSession("Not authenticated.")
+        user = self.provider.retrieve_by_id(record.user_id)
+        if user is None:
+            self.store.invalidate(record.id)
+            raise InvalidSession("The session user no longer exists.")
+        return AuthContext(user=user, scopes=["*"])

fastapi_startkit_auth/guards/token.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+from fastapi import Request
+
+from ..apitokens.manager import ApiTokenManager
+from ..exceptions import InvalidToken
+from ..providers.base import UserProvider
+from .guard import AuthContext
+
+
+class TokenGuard:
+    """Opaque API-token guard (Sanctum-style).
+
+    Corresponds to a ``{"driver": "token"}`` guard entry. Resolves
+    ``Authorization: Bearer {id}|{secret}`` — or the raw token in a configured
+    custom header — through :class:`ApiTokenManager` and turns the record's
+    abilities into the ``AuthContext`` scopes, so ``require_scopes`` works
+    unchanged.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        tokens: ApiTokenManager,
+        provider: UserProvider,
+        header: str = "Authorization",
+    ) -> None:
+        self.name = name
+        self._tokens = tokens
+        self.provider = provider
+        self.header = header
+
+    def authenticate(self, request: Request) -> AuthContext:
+        """Resolve the request's configured token header to an ``AuthContext``."""
+        token = self._extract(request)
+        if not token:
+            raise InvalidToken("Not authenticated.")
+        return self.user_from_token(token)
+
+    def user_from_token(self, access_token: str) -> AuthContext:
+        record = self._tokens.verify(access_token)
+        user = self.provider.retrieve_by_id(record.user_id)
+        if user is None:
+            # Orphaned token (user deleted): revoke it, fail generically.
+            self._tokens.revoke(record.id)
+            raise InvalidToken("The API token is invalid.")
+        return AuthContext(user=user, scopes=list(record.abilities))
+
+    def _extract(self, request: Request) -> str | None:
+        raw = request.headers.get(self.header)
+        if raw is None:
+            return None
+        if self.header.lower() == "authorization":
+            scheme, _, value = raw.partition(" ")
+            if scheme.lower() != "bearer":
+                return None
+            return value.strip()
+        return raw.strip()

fastapi_startkit_auth/manager.py

@@ -0,0 +1,320 @@
+from __future__ import annotations
+
+import secrets
+import warnings
+from typing import Any, Callable
+
+from .apitokens.manager import ApiTokenManager
+from .apitokens.repository import ApiTokenRepository, InMemoryApiTokenRepository
+from .apitokens.sql import SqlApiTokenRepository
+from .clients.repository import InMemoryClientRepository
+from .config import AuthConfig, as_config_class
+from .grants.authorization_code import AuthorizationCodeGrant
+from .grants.client_credentials import ClientCredentialsGrant
+from .grants.password import PasswordGrant
+from .grants.refresh import RefreshTokenGrant
+from .guards.guard import Guard, PassportGuard
+from .guards.session import SessionGuard
+from .guards.token import TokenGuard
+from .passwords.broker import PasswordBroker
+from .passwords.repository import InMemoryPasswordResetRepository
+from .providers.base import UserProvider
+from .providers.memory import InMemoryUserProvider
+from .providers.model import ModelUserProvider
+from .security.hashing import BcryptHasher
+from .security.jwt import JWTEncoder
+from .sessions.sql import SqlSessionStore
+from .sessions.store import InMemorySessionStore, SessionStore
+from .tokens.repository import InMemoryTokenRepository
+from .tokens.service import TokenService
+
+GuardFactory = Callable[[str, dict[str, Any]], Guard]
+
+
+def _resolve_connection(connection: Any) -> Any:
+    """Return an open DB-API connection from either a connection or a factory.
+
+    A raw connection (e.g. ``sqlite3.Connection``) is itself callable, so we
+    duck-type on ``execute`` — which every SQL store relies on — instead of
+    ``callable()`` to tell an already-open connection apart from a zero-arg
+    factory that produces one.
+    """
+    if hasattr(connection, "execute"):
+        return connection
+    if callable(connection):
+        return connection()
+    return connection
+
+
+class AuthManager:
+    """Central registry built from an :class:`AuthConfig`.
+
+    Wires the shared hasher, JWT encoder, token store/service, client registry,
+    guards, providers, grant handlers, and password brokers, and resolves them by
+    the names declared in config. This is what ``AuthProvider`` registers onto the
+    application and what the FastAPI dependencies read from.
+    """
+
+    def __init__(self, config: Any) -> None:
+        self._config = as_config_class(config)
+        cfg = self._config
+
+        rounds = cfg.get("bcrypt_rounds", 12)
+        self.hasher = BcryptHasher(rounds=rounds)
+
+        key = cfg.get("key")
+        if not key:
+            key = secrets.token_urlsafe(48)
+            warnings.warn(
+                "AuthConfig.key is not set; generated an ephemeral signing key. "
+                "Tokens will be invalidated on restart. Set a stable key in production.",
+                stacklevel=2,
+            )
+        self.encoder = JWTEncoder(secret=key, algorithm=cfg.get("algorithm", "HS256"))
+
+        self.token_repository = InMemoryTokenRepository()
+        self.token_service = TokenService(
+            encoder=self.encoder,
+            repository=self.token_repository,
+            access_ttl=cfg.get("access_token_ttl", 3600),
+            refresh_ttl=cfg.get("refresh_token_ttl", 1209600),
+            personal_access_ttl=cfg.get("personal_access_token_ttl", 31536000),
+        )
+        self.client_repository = InMemoryClientRepository(hasher=self.hasher)
+
+        self._notifier = cfg.get("password_reset_notifier")
+        self.debug_expose_reset_token = bool(cfg.get("debug_expose_reset_token", False))
+
+        self.session_config = {**AuthConfig.session, **cfg.get("session", {})}
+        self.spa_config = {**AuthConfig.spa, **cfg.get("spa", {})}
+        self.api_tokens_config = {**AuthConfig.api_tokens, **cfg.get("api_tokens", {})}
+        self._session_store: SessionStore | None = None
+        self._api_tokens: ApiTokenManager | None = None
+
+        self._providers: dict[str, UserProvider] = {
+            name: self._build_provider(spec) for name, spec in cfg.get("providers", {}).items()
+        }
+        self._guard_drivers: dict[str, GuardFactory] = {}
+        self.register_guard_driver("passport", self._build_passport_guard)
+        self.register_guard_driver("session", self._build_session_guard)
+        self.register_guard_driver("token", self._build_token_guard)
+        self._guards: dict[str, Guard] = {
+            name: self._build_guard(name, spec) for name, spec in cfg.get("guards", {}).items()
+        }
+        self._brokers: dict[str, PasswordBroker] = {
+            name: self._build_broker(spec) for name, spec in cfg.get("passwords", {}).items()
+        }
+
+    # --- construction helpers -----------------------------------------
+    def _build_provider(self, spec: dict[str, Any]) -> UserProvider:
+        driver = spec.get("driver", "instance")
+        if driver == "instance":
+            return spec["instance"]
+        if driver == "factory":
+            return spec["factory"]()
+        if driver == "memory":
+            provider = InMemoryUserProvider(
+                hasher=self.hasher,
+                username_field=spec.get("username_field", "email"),
+            )
+            for user in spec.get("users", []):
+                provider.add(user)
+            return provider
+        if driver in ("masoniteorm", "orm", "model"):
+            return ModelUserProvider(
+                model=spec["model"],
+                hasher=self.hasher,
+                username_field=spec.get("username_field", "email"),
+                password_field=spec.get("password_field", "password"),
+                id_field=spec.get("id_field", "id"),
+            )
+        raise ValueError(f"Unknown user provider driver: {driver!r}")
+
+    def register_guard_driver(self, driver: str, factory: GuardFactory) -> None:
+        """Register a factory that builds a guard for a config ``driver`` key.
+
+        Guards are constructed by their ``spec["driver"]`` rather than hardcoded,
+        so app-defined drivers register alongside the built-in ``passport``,
+        ``session``, and ``token`` drivers without touching the resolution
+        logic.
+
+        Ordering: config-declared guards are built during ``__init__`` right after
+        the ``passport`` driver registers, so calling this post-construction does
+        NOT retroactively build config-declared guards — register custom drivers
+        before or at construction (e.g. in a subclass ``__init__`` before
+        ``super().__init__``, or by extending this manager).
+        """
+        self._guard_drivers[driver] = factory
+
+    def _build_guard(self, name: str, spec: dict[str, Any]) -> Guard:
+        driver = spec.get("driver", "passport")
+        factory = self._guard_drivers.get(driver)
+        if factory is None:
+            raise ValueError(f"Unknown auth guard driver: {driver!r}")
+        return factory(name, spec)
+
+    def _build_passport_guard(self, name: str, spec: dict[str, Any]) -> Guard:
+        provider = self._require_provider(spec.get("provider"))
+        return PassportGuard(name=name, token_service=self.token_service, provider=provider)
+
+    def _build_session_guard(self, name: str, spec: dict[str, Any]) -> Guard:
+        provider = self._require_provider(spec.get("provider"))
+        if not self.session_config.get("secure", True):
+            warnings.warn(
+                "AuthConfig.session['secure'] is False; the session cookie will be sent "
+                "over plain HTTP. Enable it in production.",
+                stacklevel=2,
+            )
+        return SessionGuard(
+            name=name,
+            store=self.session_store,
+            provider=provider,
+            ttl=self.session_config.get("ttl"),
+        )
+
+    def _build_token_guard(self, name: str, spec: dict[str, Any]) -> Guard:
+        provider = self._require_provider(spec.get("provider"))
+        return TokenGuard(
+            name=name,
+            tokens=self.api_tokens,
+            provider=provider,
+            header=self.api_tokens_config.get("header", "Authorization"),
+        )
+
+    @property
+    def api_tokens(self) -> ApiTokenManager:
+        """The API-token manager, built on first use.
+
+        Lazy for the same reason as :attr:`session_store`: apps without a token
+        guard never pay for (or have to configure) the repository — notably the
+        SQL connection.
+        """
+        if self._api_tokens is None:
+            self._api_tokens = ApiTokenManager(
+                repository=self._build_api_token_repository(),
+                default_ttl=self.api_tokens_config.get("ttl"),
+                purge_interval=self.api_tokens_config.get("purge_interval", 300),
+            )
+        return self._api_tokens
+
+    def _build_api_token_repository(self) -> ApiTokenRepository:
+        spec = self.api_tokens_config
+        kind = spec.get("store", "memory")
+        if kind == "memory":
+            return InMemoryApiTokenRepository()
+        if kind == "sql":
+            connection = spec.get("connection")
+            if connection is None:
+                raise ValueError('AuthConfig.api_tokens with store "sql" requires a "connection".')
+            connection = _resolve_connection(connection)
+            return SqlApiTokenRepository(
+                connection,
+                table=spec.get("table", "personal_api_tokens"),
+            )
+        if kind == "instance":
+            return spec["instance"]
+        raise ValueError(f"Unknown api_tokens store: {kind!r}")
+
+    @property
+    def session_store(self) -> SessionStore:
+        """The configured session store, built on first use.
+
+        Lazy so apps without a session guard never pay for (or have to
+        configure) a store — notably the SQL connection.
+        """
+        if self._session_store is None:
+            self._session_store = self._build_session_store()
+        return self._session_store
+
+    def _build_session_store(self) -> SessionStore:
+        spec = self.session_config
+        kind = spec.get("store", "memory")
+        idle_ttl = spec.get("idle_ttl")
+        if kind == "memory":
+            return InMemorySessionStore(idle_ttl=idle_ttl)
+        if kind == "sql":
+            connection = spec.get("connection")
+            if connection is None:
+                raise ValueError('AuthConfig.session with store "sql" requires a "connection".')
+            connection = _resolve_connection(connection)
+            return SqlSessionStore(
+                connection,
+                table=spec.get("table", "sessions"),
+                idle_ttl=idle_ttl,
+                purge_interval=spec.get("purge_interval", 300),
+            )
+        if kind == "instance":
+            return spec["instance"]
+        raise ValueError(f"Unknown session store: {kind!r}")
+
+    def session_guard_name(self) -> str | None:
+        """Name of the first configured session guard, or ``None``."""
+        return next(
+            (name for name, guard in self._guards.items() if isinstance(guard, SessionGuard)),
+            None,
+        )
+
+    def has_session_guard(self) -> bool:
+        return self.session_guard_name() is not None
+
+    def spa_enabled(self) -> bool:
+        return bool(self.spa_config.get("enabled"))
+
+    def _build_broker(self, spec: dict[str, Any]) -> PasswordBroker:
+        provider = self._resolve_broker_provider(spec.get("provider"))
+        return PasswordBroker(
+            user_provider=provider,
+            repository=InMemoryPasswordResetRepository(),
+            hasher=self.hasher,
+            expire_minutes=spec.get("expire", 60),
+            throttle_seconds=spec.get("throttle", 60),
+            notifier=self._notifier,
+        )
+
+    def _resolve_broker_provider(self, name: str | None) -> UserProvider:
+        # The passwords `provider` key may reference a providers entry; fall back
+        # to the default guard's provider if the name doesn't resolve.
+        if name and name in self._providers:
+            return self._providers[name]
+        default_guard = self._config.get("default", {}).get("guard")
+        guard_spec = self._config.get("guards", {}).get(default_guard, {})
+        return self._require_provider(guard_spec.get("provider"))
+
+    def _require_provider(self, name: str | None) -> UserProvider:
+        if name not in self._providers:
+            raise ValueError(f"Auth provider {name!r} is not defined in AuthConfig.providers")
+        return self._providers[name]
+
+    # --- public accessors ---------------------------------------------
+    def guard(self, name: str | None = None) -> Guard:
+        name = name or self._config.get("default", {}).get("guard")
+        if name not in self._guards:
+            raise ValueError(f"Auth guard {name!r} is not defined in AuthConfig.guards")
+        return self._guards[name]
+
+    def provider(self, name: str) -> UserProvider:
+        return self._require_provider(name)
+
+    def broker(self, name: str | None = None) -> PasswordBroker:
+        name = name or self._config.get("default", {}).get("passwords")
+        if name not in self._brokers:
+            raise ValueError(f"Password broker {name!r} is not defined in AuthConfig.passwords")
+        return self._brokers[name]
+
+    def default_guard_name(self) -> str:
+        return self._config.get("default", {}).get("guard")
+
+    # --- grant factories ----------------------------------------------
+    def password_grant(self, guard: str | None = None) -> PasswordGrant:
+        return PasswordGrant(self.token_service, self.guard(guard).provider)
+
+    def client_credentials_grant(self) -> ClientCredentialsGrant:
+        return ClientCredentialsGrant(self.token_service)
+
+    def refresh_grant(self) -> RefreshTokenGrant:
+        return RefreshTokenGrant(self.token_service)
+
+    def authorization_code_grant(self) -> AuthorizationCodeGrant:
+        return AuthorizationCodeGrant(
+            self.token_service, code_ttl=self._config.get("authorization_code_ttl", 600)
+        )

fastapi_startkit_auth/middleware/__init__.py

@@ -0,0 +1,4 @@
+from .csrf import CsrfMiddleware
+from .session import SessionMiddleware
+
+__all__ = ["CsrfMiddleware", "SessionMiddleware"]

fastapi_startkit_auth/middleware/csrf.py

@@ -0,0 +1,160 @@
+from __future__ import annotations
+
+import secrets
+from http.cookies import SimpleCookie
+from typing import Any, Iterable
+
+from starlette.datastructures import MutableHeaders
+from starlette.responses import JSONResponse, Response
+from starlette.types import ASGIApp, Message, Receive, Scope, Send
+
+from ..exceptions import CsrfTokenMismatch
+from ..sessions.state import FORGET_KEY, SESSION_KEY
+
+UNSAFE_METHODS = frozenset({"POST", "PUT", "PATCH", "DELETE"})
+
+
+class CsrfMiddleware:
+    """Session-bound double-submit CSRF protection for SPA cookie auth.
+
+    Runs *inside* :class:`~.session.SessionMiddleware` (added to the app before
+    it), so the session record is already on the request state.
+
+    Request phase — unsafe methods (POST/PUT/PATCH/DELETE) on requests that
+    carry a live session must present the configured header (default
+    ``X-XSRF-TOKEN``) matching the session's ``csrf_token``; the comparison is
+    constant-time and failure is a 403 ``csrf_token_mismatch``. Requests
+    without a session (bearer/token clients — no ambient credential) and safe
+    methods are exempt, as are configured exempt paths. When
+    ``stateful_origins`` is set, a foreign ``Origin`` header is rejected before
+    the token is even checked (defense in depth).
+
+    Response phase — whenever the session's CSRF token differs from the
+    incoming CSRF cookie (first issue, or rotation on login), the cookie
+    (default ``XSRF-TOKEN``) is (re)set. It is deliberately **not** HttpOnly:
+    the SPA must read it to echo it in the header, and it is useless to an
+    attacker without the HttpOnly session cookie. A stale cookie with no
+    backing session is deleted.
+    """
+
+    def __init__(
+        self,
+        app: ASGIApp,
+        cookie: str = "XSRF-TOKEN",
+        header: str = "X-XSRF-TOKEN",
+        exempt_paths: Iterable[str] = (),
+        stateful_origins: Iterable[str] = (),
+        ttl: float | None = 7200,
+        same_site: str = "lax",
+        secure: bool = True,
+        domain: str | None = None,
+        path: str = "/",
+    ) -> None:
+        self.app = app
+        self.cookie = cookie
+        self.header = header.lower().encode("latin-1")
+        self.exempt_paths = tuple(exempt_paths)
+        self.stateful_origins = frozenset(stateful_origins)
+        self.ttl = ttl
+        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", {})
+        record = state.get(SESSION_KEY)
+        if scope["method"] in UNSAFE_METHODS and record is not None:
+            rejection = self._reject(scope, record)
+            if rejection is not None:
+                await rejection(scope, receive, send)
+                return
+
+        incoming_token = self._read_cookie(scope)
+
+        async def send_wrapper(message: Message) -> None:
+            if message["type"] == "http.response.start":
+                header = self._cookie_header(state, incoming_token)
+                if header is not None:
+                    MutableHeaders(scope=message).append("set-cookie", header)
+            await send(message)
+
+        await self.app(scope, receive, send_wrapper)
+
+    def _reject(self, scope: Scope, record: Any) -> Response | None:
+        origin = self._header_value(scope, b"origin")
+        if self.stateful_origins and origin is not None and origin not in self.stateful_origins:
+            return self._forbidden("Origin is not in the configured stateful origins.")
+        if self._exempt(scope["path"]):
+            return None
+        supplied = self._header_value(scope, self.header)
+        if supplied is None or not secrets.compare_digest(
+            supplied.encode("latin-1"), record.csrf_token.encode("latin-1")
+        ):
+            return self._forbidden("CSRF token missing or invalid.")
+        return None
+
+    @staticmethod
+    def _forbidden(description: str) -> Response:
+        error = CsrfTokenMismatch(description)
+        return JSONResponse(status_code=error.status_code, content=error.to_dict())
+
+    def _exempt(self, path: str) -> bool:
+        for pattern in self.exempt_paths:
+            if pattern.endswith("*"):
+                if path.startswith(pattern[:-1]):
+                    return True
+            elif path == pattern:
+                return True
+        return False
+
+    @staticmethod
+    def _header_value(scope: Scope, name: bytes) -> str | None:
+        raw = next((value for key, value in scope.get("headers", []) if key == name), None)
+        return raw.decode("latin-1") if raw is not None else None
+
+    def _read_cookie(self, scope: Scope) -> str | None:
+        raw = self._header_value(scope, b"cookie")
+        if raw is None:
+            return None
+        jar: SimpleCookie = SimpleCookie()
+        jar.load(raw)
+        morsel = jar.get(self.cookie)
+        return morsel.value if morsel is not None else None
+
+    def _cookie_header(self, state: dict[str, Any], incoming_token: str | None) -> str | None:
+        record = state.get(SESSION_KEY)
+        response = Response()
+        if record is not None:
+            if incoming_token == record.csrf_token:
+                return None
+            response.set_cookie(
+                self.cookie,
+                record.csrf_token,
+                max_age=int(self.ttl) if self.ttl is not None else None,
+                path=self.path,
+                domain=self.domain,
+                secure=self.secure,
+                httponly=False,
+                samesite=self.same_site,
+            )
+        elif state.get(FORGET_KEY) or incoming_token is not None:
+            response.delete_cookie(
+                self.cookie,
+                path=self.path,
+                domain=self.domain,
+                secure=self.secure,
+                httponly=False,
+                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"
+        )