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

fastapi_startkit_auth/config.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class AuthConfig:
+    """Config-driven auth definition, mirroring Laravel's ``config/auth.php``.
+
+    Subclass and override the class attributes. ``default``/``guards``/
+    ``providers``/``passwords`` match the Passport model; the remaining
+    attributes tune JWT signing and token lifetimes and all have sane defaults so
+    a minimal config only needs to set ``key`` and a provider.
+
+    Example::
+
+        class AuthConfig(BaseAuthConfig):
+            key = os.environ["APP_KEY"]
+            default = {"guard": "api", "passwords": "users"}
+            guards = {"api": {"driver": "passport", "provider": "users"}}
+            providers = {"users": {"driver": "masoniteorm", "model": User}}
+            passwords = {"users": {"provider": "users", "table": "password_reset_tokens",
+                                    "expire": 60, "throttle": 60}}
+    """
+
+    default: dict[str, str] = {"guard": "api", "passwords": "users"}
+    guards: dict[str, dict[str, Any]] = {"api": {"driver": "passport", "provider": "users"}}
+    providers: dict[str, dict[str, Any]] = {}
+    passwords: dict[str, dict[str, Any]] = {}
+
+    # --- session settings (cookie auth; used by {"driver": "session"} guards) --
+    # ``store`` selects the backend: "memory" (default), "sql" (requires a
+    # DB-API ``connection`` — or zero-arg factory — plus optional ``table``),
+    # or "instance" (a ready-made SessionStore under ``instance``). Overrides
+    # are merged over these defaults, so partial dicts are fine.
+    # ``purge_interval`` throttles the SQL store's opportunistic purge-on-create
+    # (seconds between sweeps of expired rows).
+    session: dict[str, Any] = {
+        "store": "memory",
+        "cookie": "startkit_session",
+        "ttl": 7200,
+        "idle_ttl": None,
+        "http_only": True,
+        "same_site": "lax",
+        "secure": True,
+        "domain": None,
+        "path": "/",
+        "purge_interval": 300,
+    }
+
+    # --- SPA settings (CSRF protection on top of session guards) -------
+    # ``enabled`` turns on the ``/__auth__/csrf-cookie`` endpoint and the
+    # double-submit CSRF middleware. ``stateful_origins`` (Sanctum-style) lists
+    # the first-party origins allowed to make cookie-authenticated unsafe
+    # requests; empty disables the Origin check. ``csrf_exempt_paths`` entries
+    # match exactly, or as a prefix when they end with ``*``.
+    spa: dict[str, Any] = {
+        "enabled": False,
+        "csrf_cookie": "XSRF-TOKEN",
+        "csrf_header": "X-XSRF-TOKEN",
+        "csrf_exempt_paths": [],
+        "stateful_origins": [],
+    }
+
+    # --- API token settings (opaque tokens; used by {"driver": "token"} guards) --
+    # ``store`` selects the backend like the session block: "memory" (default),
+    # "sql" (requires a DB-API ``connection`` — or zero-arg factory — plus
+    # optional ``table``), or "instance" (a ready-made ApiTokenRepository under
+    # ``instance``). ``header`` is where the guard reads the token: the default
+    # "Authorization" expects a ``Bearer`` scheme, any other name is read raw.
+    # ``ttl`` is the default token lifetime in seconds (None = non-expiring);
+    # ``purge_interval`` throttles the opportunistic purge-on-issue.
+    api_tokens: dict[str, Any] = {
+        "store": "memory",
+        "header": "Authorization",
+        "ttl": None,
+        "purge_interval": 300,
+    }
+
+    # --- JWT / token settings (overridable) ----------------------------
+    key: str | None = None
+    algorithm: str = "HS256"
+    access_token_ttl: int = 3600            # 1 hour
+    refresh_token_ttl: int = 60 * 60 * 24 * 14   # 14 days
+    personal_access_token_ttl: int = 60 * 60 * 24 * 365  # 1 year
+    authorization_code_ttl: int = 600       # 10 minutes
+    bcrypt_rounds: int = 12
+
+    # Called as ``notifier(email, token)`` when a reset link is requested so the
+    # app can deliver the token (e.g. email it). The plaintext token is NEVER put
+    # in the HTTP response unless ``debug_expose_reset_token`` is explicitly True.
+    password_reset_notifier: Any = None
+    debug_expose_reset_token: bool = False
+
+    @classmethod
+    def get(cls, name: str, default: Any = None) -> Any:
+        return getattr(cls, name, default)
+
+
+def as_config_class(config: Any) -> type[AuthConfig]:
+    """Accept either an ``AuthConfig`` subclass or an instance and return a class-like accessor."""
+    if isinstance(config, type):
+        return config
+    return config.__class__

fastapi_startkit_auth/dependencies.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from fastapi import Depends, Request
+from fastapi.security import OAuth2PasswordBearer
+
+from .exceptions import AuthError, InsufficientScope, InvalidToken
+from .guards.guard import AuthContext
+from .manager import AuthManager
+
+# auto_error=False so we can raise our own OAuth2-style JSON errors instead of
+# FastAPI's default {"detail": ...} response.
+_bearer = OAuth2PasswordBearer(tokenUrl="oauth/token", auto_error=False)
+
+
+def get_auth_manager(request: Request) -> AuthManager:
+    manager = getattr(request.app.state, "auth_manager", None)
+    if manager is None:  # pragma: no cover - misconfiguration guard
+        raise RuntimeError(
+            "No AuthManager on the application. Did you register AuthProvider via Application?"
+        )
+    return manager
+
+
+def current_context(
+    request: Request,
+    token: str | None = Depends(_bearer),
+    manager: AuthManager = Depends(get_auth_manager),
+) -> AuthContext:
+    """Resolve the request credential to an :class:`AuthContext` or raise 401.
+
+    The default guard decides the mechanism: guards that implement
+    ``authenticate(request)`` (session driver) read the request/cookie state,
+    everything else takes the bearer-token path. Route code is identical either
+    way.
+    """
+    guard = manager.guard()
+    authenticate = getattr(guard, "authenticate", None)
+    if authenticate is not None:
+        return authenticate(request)
+    if not token:
+        raise InvalidToken("Not authenticated.")
+    return guard.user_from_token(token)
+
+
+def current_user(context: AuthContext = Depends(current_context)) -> Any:
+    """Return the authenticated user model (401 if the token carries no user)."""
+    if context.user is None:
+        raise InvalidToken("This token is not associated with a user.")
+    return context.user
+
+
+def optional_user(
+    request: Request,
+    token: str | None = Depends(_bearer),
+    manager: AuthManager = Depends(get_auth_manager),
+) -> Any | None:
+    """Return the authenticated user, or ``None`` if unauthenticated/invalid."""
+    guard = manager.guard()
+    authenticate = getattr(guard, "authenticate", None)
+    try:
+        if authenticate is not None:
+            return authenticate(request).user
+        if not token:
+            return None
+        return guard.user_from_token(token).user
+    except AuthError:
+        return None
+
+
+def require_scopes(*scopes: str, mode: str = "all") -> Callable[..., AuthContext]:
+    """Dependency factory enforcing token abilities (Passport-style scopes).
+
+    ``mode="all"`` requires every scope; ``mode="any"`` requires at least one.
+    Raises 403 ``insufficient_scope`` when the token lacks them.
+    """
+    required = list(scopes)
+
+    def dependency(context: AuthContext = Depends(current_context)) -> AuthContext:
+        ok = context.can_any(required) if mode == "any" else context.can_all(required)
+        if not ok:
+            raise InsufficientScope(
+                f"Requires scope(s): {' '.join(required)} (mode={mode})."
+            )
+        return context
+
+    return dependency
+
+
+# Sanctum-flavored name for the same check: API-token abilities live in
+# ``AuthContext.scopes``, so scope and ability enforcement are one mechanism.
+require_abilities = require_scopes

fastapi_startkit_auth/exceptions.py

@@ -0,0 +1,90 @@
+"""Auth error hierarchy.
+
+Error codes follow the OAuth2 error registry (RFC 6749 §5.2) so they can be
+surfaced verbatim in token-endpoint responses.
+"""
+from __future__ import annotations
+
+
+class AuthError(Exception):
+    """Base class for all authentication/authorization failures."""
+
+    error = "invalid_request"
+    status_code = 400
+
+    def __init__(self, description: str | None = None) -> None:
+        self.description = description or self.__class__.__doc__ or self.error
+        super().__init__(self.description)
+
+    def to_dict(self) -> dict:
+        return {"error": self.error, "error_description": self.description}
+
+
+class InvalidRequest(AuthError):
+    """The request is missing a required parameter or is otherwise malformed."""
+
+    error = "invalid_request"
+    status_code = 400
+
+
+class InvalidClient(AuthError):
+    """Client authentication failed (unknown client or bad secret)."""
+
+    error = "invalid_client"
+    status_code = 401
+
+
+class InvalidGrant(AuthError):
+    """The provided credentials, code, or refresh token are invalid or expired."""
+
+    error = "invalid_grant"
+    status_code = 400
+
+
+class UnsupportedGrantType(AuthError):
+    """The authorization server does not support this grant type."""
+
+    error = "unsupported_grant_type"
+    status_code = 400
+
+
+class UnauthorizedClient(AuthError):
+    """The client is not permitted to use this grant type."""
+
+    error = "unauthorized_client"
+    status_code = 400
+
+
+class InvalidToken(AuthError):
+    """The access token is expired, malformed, revoked, or otherwise invalid."""
+
+    error = "invalid_token"
+    status_code = 401
+
+
+class InvalidSession(AuthError):
+    """The session cookie is missing, expired, or no longer valid."""
+
+    error = "invalid_session"
+    status_code = 401
+
+
+class CsrfTokenMismatch(AuthError):
+    """The request is missing a valid CSRF token for this session."""
+
+    error = "csrf_token_mismatch"
+    status_code = 403
+
+
+class InsufficientScope(AuthError):
+    """The token does not carry the scopes required for this resource."""
+
+    error = "insufficient_scope"
+    status_code = 403
+
+
+class ThrottleException(AuthError):
+    """Too many requests for this action; retry later."""
+
+    error = "throttled"
+    status_code = 429

fastapi_startkit_auth/facade.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import Depends, Request
+
+from .dependencies import get_auth_manager
+from .exceptions import AuthError
+from .guards.session import SessionGuard
+from .manager import AuthManager
+from .sessions.models import SessionRecord
+
+
+class Auth:
+    """Request-scoped facade over the manager and the request's session.
+
+    Wire it into your own login/logout routes (the package ships none)::
+
+        from fastapi_startkit_auth import Auth
+
+        @api.post("/login")
+        def login(payload: Credentials, auth: Auth = Depends(Auth.scoped)):
+            if not auth.attempt(payload.model_dump()):
+                raise InvalidSession("Invalid credentials.")
+            return {"ok": True}
+
+        @api.post("/logout")
+        def logout(auth: Auth = Depends(Auth.scoped)):
+            auth.logout()
+    """
+
+    def __init__(self, manager: AuthManager, request: Request) -> None:
+        self._manager = manager
+        self._request = request
+
+    @classmethod
+    def scoped(cls, request: Request, manager: AuthManager = Depends(get_auth_manager)) -> "Auth":
+        """FastAPI dependency: ``auth: Auth = Depends(Auth.scoped)``."""
+        return cls(manager, request)
+
+    def guard(self, name: str | None = None) -> Any:
+        return self._manager.guard(name)
+
+    def login(self, user_or_id: Any, guard: str | None = None) -> SessionRecord:
+        """Start a session for a user instance or a user id.
+
+        Always regenerates the session id (fixation protection) and rides the
+        middleware to deliver the cookie.
+        """
+        session_guard = self._session_guard(guard)
+        user = self._resolve_user(user_or_id, session_guard)
+        return session_guard.login(self._request, user)
+
+    def attempt(self, credentials: dict[str, Any], guard: str | None = None) -> bool:
+        """Log in by credentials; ``False`` on any failure (no enumeration)."""
+        session_guard = self._session_guard(guard)
+        provider = session_guard.provider
+        user = provider.retrieve_by_credentials(credentials)
+        if user is None:
+            dummy = getattr(provider, "dummy_verify", None)
+            if dummy is not None:
+                dummy()
+            return False
+        if not provider.validate_credentials(user, credentials):
+            return False
+        session_guard.login(self._request, user)
+        return True
+
+    def logout(self, guard: str | None = None) -> None:
+        self._session_guard(guard).logout(self._request)
+
+    def user(self, guard: str | None = None) -> Any | None:
+        """The authenticated user, or ``None`` — never raises."""
+        resolved = self.guard(guard)
+        authenticate = getattr(resolved, "authenticate", None)
+        if authenticate is None:
+            return None
+        try:
+            return authenticate(self._request).user
+        except AuthError:
+            return None
+
+    def id(self, guard: str | None = None) -> Any | None:
+        user = self.user(guard)
+        if user is None:
+            return None
+        return self.guard(guard).provider.get_identifier(user)
+
+    def check(self, guard: str | None = None) -> bool:
+        return self.user(guard) is not None
+
+    def _session_guard(self, name: str | None) -> SessionGuard:
+        resolved = self.guard(name)
+        if not isinstance(resolved, SessionGuard):
+            raise RuntimeError(
+                f"Auth guard {resolved.name!r} is not a session guard; "
+                'login/logout require a {"driver": "session"} guard.'
+            )
+        return resolved
+
+    def _resolve_user(self, user_or_id: Any, session_guard: SessionGuard) -> Any:
+        if not isinstance(user_or_id, (int, str)):
+            return user_or_id
+        user = session_guard.provider.retrieve_by_id(user_or_id)
+        if user is None:
+            raise ValueError(f"No user with id {user_or_id!r} in guard {session_guard.name!r}'s provider.")
+        return user

fastapi_startkit_auth/grants/__init__.py

@@ -0,0 +1,13 @@
+from .authorization_code import AuthorizationCodeGrant
+from .client_credentials import ClientCredentialsGrant
+from .password import PasswordGrant
+from .pkce import verify_pkce
+from .refresh import RefreshTokenGrant
+
+__all__ = [
+    "PasswordGrant",
+    "ClientCredentialsGrant",
+    "RefreshTokenGrant",
+    "AuthorizationCodeGrant",
+    "verify_pkce",
+]

fastapi_startkit_auth/grants/authorization_code.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+import secrets
+import time
+from typing import Any
+
+from ..clients.models import Client
+from ..exceptions import InvalidGrant, InvalidRequest
+from ..tokens.service import IssuedToken, TokenService
+from .pkce import verify_pkce
+
+
+class AuthorizationCodeGrant:
+    """Authorization-code grant with PKCE (RFC 6749 §4.1 + RFC 7636).
+
+    PKCE is mandatory for public (secretless) clients and for any exchange where
+    the client did not authenticate — both at code issuance (a public client
+    cannot obtain a code without a ``code_challenge``) and at exchange (the
+    verifier must match). Confidential clients that authenticate may omit PKCE,
+    but any challenge they do supply is still verified.
+
+    ``issue_code`` is called after the resource owner approves a request;
+    ``handle`` exchanges the resulting single-use code for tokens.
+    """
+
+    def __init__(self, token_service: TokenService, code_ttl: int = 600) -> None:
+        self._tokens = token_service
+        self._code_ttl = code_ttl
+
+    def issue_code(
+        self,
+        *,
+        client: Client,
+        user_id: Any,
+        scopes: list[str],
+        redirect_uri: str | None,
+        code_challenge: str | None,
+        code_challenge_method: str | None,
+    ) -> str:
+        if not client.confidential and not code_challenge:
+            raise InvalidRequest("A PKCE code_challenge is required for public clients.")
+        code = secrets.token_urlsafe(40)
+        self._tokens.repository.store_auth_code(
+            code=code,
+            client_id=client.id,
+            user_id=user_id,
+            scopes=scopes,
+            redirect_uri=redirect_uri,
+            code_challenge=code_challenge,
+            code_challenge_method=code_challenge_method,
+            expires_at=time.time() + self._code_ttl,
+        )
+        return code
+
+    def handle(
+        self,
+        *,
+        client: Client,
+        code: str,
+        redirect_uri: str | None,
+        code_verifier: str | None,
+        client_authenticated: bool = False,
+    ) -> IssuedToken:
+        record = self._tokens.repository.pull_auth_code(code)
+        if record is None or record.expired:
+            raise InvalidGrant("The authorization code is invalid or expired.")
+        if record.client_id != client.id:
+            raise InvalidGrant("The authorization code was issued to a different client.")
+        if record.redirect_uri != redirect_uri:
+            raise InvalidGrant("The redirect URI does not match the authorization request.")
+        # PKCE is mandatory unless the client proved its identity with a secret.
+        pkce_required = not client_authenticated
+        if pkce_required and not record.code_challenge:
+            raise InvalidGrant("PKCE is required: this code was not bound to a code_challenge.")
+        if record.code_challenge:
+            if not verify_pkce(code_verifier or "", record.code_challenge, record.code_challenge_method):
+                raise InvalidGrant("PKCE verification failed.")
+        return self._tokens.issue(
+            user_id=record.user_id,
+            client_id=client.id,
+            scopes=record.scopes,
+            with_refresh=True,
+        )

fastapi_startkit_auth/grants/client_credentials.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from ..clients.models import Client
+from ..tokens.service import IssuedToken, TokenService
+
+
+class ClientCredentialsGrant:
+    """Machine-to-machine grant (RFC 6749 §4.4). No user, no refresh token."""
+
+    def __init__(self, token_service: TokenService) -> None:
+        self._tokens = token_service
+
+    def handle(self, *, client: Client, scopes: list[str]) -> IssuedToken:
+        return self._tokens.issue(
+            user_id=None,
+            client_id=client.id,
+            scopes=scopes,
+            with_refresh=False,
+        )

fastapi_startkit_auth/grants/password.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from ..exceptions import InvalidGrant
+from ..providers.base import UserProvider
+from ..tokens.service import IssuedToken, TokenService
+
+
+class PasswordGrant:
+    """Resource-owner password credentials grant (RFC 6749 §4.3)."""
+
+    def __init__(self, token_service: TokenService, user_provider: UserProvider) -> None:
+        self._tokens = token_service
+        self._users = user_provider
+
+    def handle(self, *, username: str, password: str, scopes: list[str], client_id: str | None) -> IssuedToken:
+        credentials = {"username": username, "email": username, "password": password}
+        user = self._users.retrieve_by_credentials(credentials)
+        if user is None:
+            # Perform equivalent hashing work so response timing doesn't reveal
+            # whether the account exists, then fail with the same generic error.
+            dummy = getattr(self._users, "dummy_verify", None)
+            if callable(dummy):
+                dummy()
+            raise InvalidGrant("The provided credentials are incorrect.")
+        if not self._users.validate_credentials(user, credentials):
+            raise InvalidGrant("The provided credentials are incorrect.")
+        return self._tokens.issue(
+            user_id=self._users.get_identifier(user),
+            client_id=client_id,
+            scopes=scopes,
+            with_refresh=True,
+        )

fastapi_startkit_auth/grants/pkce.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+
+
+def _b64url(data: bytes) -> str:
+    return base64.urlsafe_b64encode(data).rstrip(b"=").decode()
+
+
+def verify_pkce(code_verifier: str, code_challenge: str, method: str | None) -> bool:
+    """Validate a PKCE ``code_verifier`` against a stored challenge (RFC 7636).
+
+    ``S256`` compares the base64url-encoded SHA-256 of the verifier; ``plain``
+    (and a missing method) compares verbatim. Comparison is constant-time.
+    """
+    if not code_verifier or not code_challenge:
+        return False
+    method = (method or "plain").upper()
+    if method == "S256":
+        expected = _b64url(hashlib.sha256(code_verifier.encode()).digest())
+    elif method == "PLAIN":
+        expected = code_verifier
+    else:
+        return False
+    return hmac.compare_digest(expected, code_challenge)

fastapi_startkit_auth/grants/refresh.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from ..tokens.service import IssuedToken, TokenService
+
+
+class RefreshTokenGrant:
+    """Refresh-token grant (RFC 6749 §6) with rotation handled by TokenService."""
+
+    def __init__(self, token_service: TokenService) -> None:
+        self._tokens = token_service
+
+    def handle(self, *, refresh_token: str, scopes: list[str] | None) -> IssuedToken:
+        return self._tokens.refresh(refresh_token, scopes=scopes)

fastapi_startkit_auth/guards/__init__.py

@@ -0,0 +1,5 @@
+from .guard import AuthContext, Guard, PassportGuard
+from .session import SessionGuard
+from .token import TokenGuard
+
+__all__ = ["AuthContext", "Guard", "PassportGuard", "SessionGuard", "TokenGuard"]

fastapi_startkit_auth/guards/guard.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Protocol, runtime_checkable
+
+from ..exceptions import InvalidToken
+from ..providers.base import UserProvider
+from ..tokens.service import TokenService
+
+
+@dataclass
+class AuthContext:
+    """The authenticated principal resolved from a bearer token.
+
+    ``user`` is ``None`` for client-credentials tokens (machine-to-machine).
+    ``can``/``can_any`` implement Passport-style ability checks against the
+    token's scopes.
+    """
+
+    user: Any | None
+    scopes: list[str] = field(default_factory=list)
+    client_id: str | None = None
+    jti: str | None = None
+
+    def can(self, scope: str) -> bool:
+        return "*" in self.scopes or scope in self.scopes
+
+    def can_any(self, scopes: list[str]) -> bool:
+        return any(self.can(s) for s in scopes)
+
+    def can_all(self, scopes: list[str]) -> bool:
+        return all(self.can(s) for s in scopes)
+
+
+@runtime_checkable
+class Guard(Protocol):
+    """Structural contract every auth guard driver satisfies.
+
+    A guard pairs a named user provider with a mechanism for turning a request
+    credential into an :class:`AuthContext`. ``PassportGuard`` (JWT bearer),
+    ``SessionGuard`` (cookie), and ``TokenGuard`` (opaque API token) are the
+    built-in drivers; app-defined drivers register their own factories with
+    :class:`~fastapi_startkit_auth.manager.AuthManager` and implement this same
+    surface.
+    """
+
+    name: str
+    provider: UserProvider
+
+    def user_from_token(self, access_token: str) -> AuthContext: ...
+
+
+class PassportGuard:
+    """Resolves a request's bearer token to an :class:`AuthContext`.
+
+    Corresponds to a ``{"driver": "passport"}`` guard entry: it pairs the shared
+    :class:`TokenService` (which validates signature, expiry, and revocation)
+    with the guard's configured user provider.
+    """
+
+    def __init__(self, name: str, token_service: TokenService, provider: UserProvider) -> None:
+        self.name = name
+        self._tokens = token_service
+        self.provider = provider
+
+    def user_from_token(self, access_token: str) -> AuthContext:
+        claims = self._tokens.authenticate(access_token)
+        user = self._resolve_user(claims.get("sub"))
+        return AuthContext(
+            user=user,
+            scopes=list(claims.get("scopes", [])),
+            client_id=claims.get("client_id"),
+            jti=claims.get("jti"),
+        )
+
+    def _resolve_user(self, sub: Any) -> Any | None:
+        if sub is None:
+            return None
+        user = self.provider.retrieve_by_id(sub)
+        # JWT `sub` is always a string; retry with an int id for numeric keys.
+        if user is None and isinstance(sub, str) and sub.isdigit():
+            user = self.provider.retrieve_by_id(int(sub))
+        if user is None:
+            raise InvalidToken("The token subject no longer exists.")
+        return user