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

fastapi_startkit_auth/sessions/state.py

@@ -0,0 +1,11 @@
+"""Request-state keys shared by the session middleware, guard, and facade.
+
+The middleware loads the session record under ``SESSION_KEY`` before the app
+runs and inspects the same keys afterwards to decide whether to set or delete
+the cookie. ``LOADED_ID_KEY`` holds the session id that arrived on the request
+(if any) so a changed id is detected; ``FORGET_KEY`` marks an explicit logout.
+"""
+
+SESSION_KEY = "auth_session"
+LOADED_ID_KEY = "auth_session_loaded_id"
+FORGET_KEY = "auth_session_forget"

fastapi_startkit_auth/sessions/store.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+import secrets
+import time
+from typing import Any, Protocol, runtime_checkable
+
+from .models import SessionRecord
+
+
+def generate_session_id() -> str:
+    return secrets.token_urlsafe(32)
+
+
+def generate_csrf_token() -> str:
+    return secrets.token_urlsafe(32)
+
+
+@runtime_checkable
+class SessionStore(Protocol):
+    """Contract every session backend satisfies.
+
+    Mirrors the repository pattern of ``InMemoryTokenRepository``: the package
+    ships an in-memory default and a SQL implementation, and apps may implement
+    the same surface against any other store.
+    """
+
+    def create(self, *, user_id: Any, guard: str, ttl: float | None) -> SessionRecord:
+        """Persist and return a new session with a fresh id and CSRF token."""
+
+    def find(self, session_id: str) -> SessionRecord | None:
+        """Return the live session for this id, or ``None`` if unknown/expired."""
+
+    def touch(self, session_id: str) -> None:
+        """Record activity on the session (slides the idle-expiry window)."""
+
+    def regenerate_id(self, session_id: str) -> SessionRecord | None:
+        """Re-key the session under a fresh id, invalidating the old id."""
+
+    def invalidate(self, session_id: str) -> bool:
+        """Delete the session server-side; returns whether it existed."""
+
+    def purge_expired(self) -> None:
+        """Drop expired sessions (maintenance)."""
+
+
+class InMemorySessionStore:
+    """Default dict-backed session store for tests, demos, and prototypes.
+
+    ``idle_ttl`` expires sessions that have been inactive longer than the
+    window, independently of the absolute ``expires_at`` set at creation.
+    """
+
+    def __init__(self, idle_ttl: float | None = None) -> None:
+        self._sessions: dict[str, SessionRecord] = {}
+        self._idle_ttl = idle_ttl
+
+    def create(self, *, user_id: Any, guard: str, ttl: float | None) -> SessionRecord:
+        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,
+        )
+        self._sessions[record.id] = record
+        return record
+
+    def find(self, session_id: str) -> SessionRecord | None:
+        record = self._sessions.get(session_id)
+        if record is None:
+            return None
+        if record.expired(self._idle_ttl):
+            del self._sessions[session_id]
+            return None
+        return record
+
+    def touch(self, session_id: str) -> None:
+        record = self._sessions.get(session_id)
+        if record is not None:
+            record.last_activity = time.time()
+
+    def regenerate_id(self, session_id: str) -> SessionRecord | None:
+        record = self.find(session_id)
+        if record is None:
+            return None
+        del self._sessions[session_id]
+        record.id = generate_session_id()
+        self._sessions[record.id] = record
+        return record
+
+    def invalidate(self, session_id: str) -> bool:
+        return self._sessions.pop(session_id, None) is not None
+
+    def purge_expired(self) -> None:
+        self._sessions = {
+            sid: rec for sid, rec in self._sessions.items() if not rec.expired(self._idle_ttl)
+        }

fastapi_startkit_auth/startkit.py

@@ -0,0 +1,38 @@
+"""Framework-native provider for `fastapi-startkit` applications.
+
+This module is the only place the package touches the optional framework
+dependency, and it is imported lazily (via the package ``__getattr__``), so
+plain-FastAPI installs never load it. Install the extra to use it::
+
+    pip install fastapi-startkit-auth[startkit]
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+try:
+    from fastapi_startkit.support import Provider
+except ImportError as exc:  # pragma: no cover - exercised via the package import test
+    raise ImportError(
+        "AuthServiceProvider requires the optional 'fastapi-startkit' framework. "
+        "Install it with: pip install fastapi-startkit-auth[startkit]"
+    ) from exc
+
+_PUBLISHABLE = Path(__file__).resolve().parent / "publishable"
+
+
+class AuthServiceProvider(Provider):
+    """Registers the auth package's publishable assets with the framework.
+
+    Add it to the application's ``providers=[...]`` list, then publish the
+    CORS stub with ``provider:publish -p auth`` (copied to ``config/cors.py``).
+    The stub's defaults are also merged under the ``cors`` config key, so the
+    published file only overrides them.
+    """
+
+    provider_key = "auth"
+
+    def register(self) -> None:
+        cors_stub = str(_PUBLISHABLE / "cors.py")
+        self.merge_config_from(cors_stub, "cors")
+        self.publishes({cors_stub: "config/cors.py"})

fastapi_startkit_auth/tokens/__init__.py

@@ -0,0 +1,9 @@
+from .models import AccessTokenRecord, AuthorizationCode, RefreshTokenRecord
+from .repository import InMemoryTokenRepository
+
+__all__ = [
+    "AccessTokenRecord",
+    "RefreshTokenRecord",
+    "AuthorizationCode",
+    "InMemoryTokenRepository",
+]

fastapi_startkit_auth/tokens/models.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class AccessTokenRecord:
+    """Server-side record of an issued JWT access token.
+
+    The JWT itself is stateless; this record is what makes revocation and
+    introspection possible and also backs personal access tokens.
+    """
+
+    jti: str
+    user_id: Any | None
+    client_id: str | None
+    scopes: list[str] = field(default_factory=list)
+    expires_at: float | None = None
+    revoked: bool = False
+    name: str | None = None
+    personal_access: bool = False
+    created_at: float = field(default_factory=lambda: time.time())
+
+    @property
+    def expired(self) -> bool:
+        return self.expires_at is not None and self.expires_at < time.time()
+
+    @property
+    def active(self) -> bool:
+        return not self.revoked and not self.expired
+
+
+@dataclass
+class RefreshTokenRecord:
+    token_id: str
+    access_jti: str
+    user_id: Any | None
+    client_id: str | None
+    scopes: list[str] = field(default_factory=list)
+    expires_at: float | None = None
+    revoked: bool = False
+    created_at: float = field(default_factory=lambda: time.time())
+
+    @property
+    def expired(self) -> bool:
+        return self.expires_at is not None and self.expires_at < time.time()
+
+    @property
+    def active(self) -> bool:
+        return not self.revoked and not self.expired
+
+
+@dataclass
+class AuthorizationCode:
+    code: str
+    client_id: str
+    user_id: Any
+    scopes: list[str]
+    redirect_uri: str | None
+    code_challenge: str | None
+    code_challenge_method: str | None
+    expires_at: float
+
+    @property
+    def expired(self) -> bool:
+        return self.expires_at < time.time()

fastapi_startkit_auth/tokens/repository.py

@@ -0,0 +1,129 @@
+from __future__ import annotations
+
+import time
+from typing import Any
+
+from .models import AccessTokenRecord, AuthorizationCode, RefreshTokenRecord
+
+
+class InMemoryTokenRepository:
+    """Default token store.
+
+    Holds access-token records (for revocation/introspection), refresh tokens,
+    and pending authorization codes. Implement the same method surface against a
+    real database to persist tokens across processes.
+    """
+
+    def __init__(self) -> None:
+        self._access: dict[str, AccessTokenRecord] = {}
+        self._refresh: dict[str, RefreshTokenRecord] = {}
+        self._codes: dict[str, AuthorizationCode] = {}
+
+    # --- access tokens -------------------------------------------------
+    def store_access_token(
+        self,
+        *,
+        jti: str,
+        user_id: Any | None,
+        client_id: str | None,
+        scopes: list[str],
+        expires_at: float | None,
+        name: str | None = None,
+        personal_access: bool = False,
+    ) -> AccessTokenRecord:
+        rec = AccessTokenRecord(
+            jti=jti,
+            user_id=user_id,
+            client_id=client_id,
+            scopes=list(scopes),
+            expires_at=expires_at,
+            name=name,
+            personal_access=personal_access,
+        )
+        self._access[jti] = rec
+        return rec
+
+    def find_access_token(self, jti: str) -> AccessTokenRecord | None:
+        return self._access.get(jti)
+
+    def revoke_access_token(self, jti: str) -> bool:
+        rec = self._access.get(jti)
+        if rec is None:
+            return False
+        rec.revoked = True
+        return True
+
+    def list_access_tokens(self, user_id: Any, personal_access: bool | None = None) -> list[AccessTokenRecord]:
+        out = [r for r in self._access.values() if r.user_id == user_id]
+        if personal_access is not None:
+            out = [r for r in out if r.personal_access == personal_access]
+        return out
+
+    # --- refresh tokens ------------------------------------------------
+    def store_refresh_token(
+        self,
+        *,
+        token_id: str,
+        access_jti: str,
+        user_id: Any | None,
+        client_id: str | None,
+        scopes: list[str],
+        expires_at: float | None,
+    ) -> RefreshTokenRecord:
+        rec = RefreshTokenRecord(
+            token_id=token_id,
+            access_jti=access_jti,
+            user_id=user_id,
+            client_id=client_id,
+            scopes=list(scopes),
+            expires_at=expires_at,
+        )
+        self._refresh[token_id] = rec
+        return rec
+
+    def find_refresh_token(self, token_id: str) -> RefreshTokenRecord | None:
+        return self._refresh.get(token_id)
+
+    def revoke_refresh_token(self, token_id: str) -> bool:
+        rec = self._refresh.get(token_id)
+        if rec is None:
+            return False
+        rec.revoked = True
+        return True
+
+    # --- authorization codes ------------------------------------------
+    def store_auth_code(
+        self,
+        *,
+        code: str,
+        client_id: str,
+        user_id: Any,
+        scopes: list[str],
+        redirect_uri: str | None,
+        code_challenge: str | None,
+        code_challenge_method: str | None,
+        expires_at: float,
+    ) -> AuthorizationCode:
+        rec = AuthorizationCode(
+            code=code,
+            client_id=client_id,
+            user_id=user_id,
+            scopes=list(scopes),
+            redirect_uri=redirect_uri,
+            code_challenge=code_challenge,
+            code_challenge_method=code_challenge_method,
+            expires_at=expires_at,
+        )
+        self._codes[code] = rec
+        return rec
+
+    def pull_auth_code(self, code: str) -> AuthorizationCode | None:
+        """Return and consume an authorization code (single use)."""
+        return self._codes.pop(code, None)
+
+    # --- maintenance ---------------------------------------------------
+    def purge_expired(self) -> None:
+        now = time.time()
+        self._access = {k: v for k, v in self._access.items() if not (v.expires_at and v.expires_at < now)}
+        self._refresh = {k: v for k, v in self._refresh.items() if not (v.expires_at and v.expires_at < now)}
+        self._codes = {k: v for k, v in self._codes.items() if v.expires_at >= now}

fastapi_startkit_auth/tokens/service.py

@@ -0,0 +1,189 @@
+from __future__ import annotations
+
+import secrets
+import time
+from dataclasses import dataclass
+from typing import Any
+
+from ..exceptions import InvalidGrant, InvalidToken
+from ..security.jwt import JWTEncoder
+from .repository import InMemoryTokenRepository
+
+
+@dataclass
+class IssuedToken:
+    """The result of minting a token, serialisable to an OAuth2 token response."""
+
+    access_token: str
+    token_type: str
+    expires_in: int
+    scopes: list[str]
+    jti: str
+    refresh_token: str | None = None
+
+    def to_response(self) -> dict[str, Any]:
+        body: dict[str, Any] = {
+            "access_token": self.access_token,
+            "token_type": self.token_type,
+            "expires_in": self.expires_in,
+            "scope": " ".join(self.scopes),
+        }
+        if self.refresh_token is not None:
+            body["refresh_token"] = self.refresh_token
+        return body
+
+
+class TokenService:
+    """Mints, rotates, revokes, and introspects tokens.
+
+    Access tokens are signed JWTs; a server-side record per ``jti`` enables
+    revocation and introspection. Refresh tokens are opaque high-entropy strings
+    mapped to stored records, and are rotated (old access + refresh revoked) on
+    every use.
+    """
+
+    def __init__(
+        self,
+        encoder: JWTEncoder,
+        repository: InMemoryTokenRepository | None = None,
+        access_ttl: int = 3600,
+        refresh_ttl: int = 1209600,
+        personal_access_ttl: int = 31536000,
+        purge_interval: int = 300,
+    ) -> None:
+        self.encoder = encoder
+        self.repository = repository or InMemoryTokenRepository()
+        self.access_ttl = access_ttl
+        self.refresh_ttl = refresh_ttl
+        self.personal_access_ttl = personal_access_ttl
+        self._purge_interval = purge_interval
+        self._last_purge = time.time()
+
+    def _maybe_purge(self) -> None:
+        """Drop expired records periodically so in-memory stores stay bounded."""
+        now = time.time()
+        if now - self._last_purge >= self._purge_interval:
+            self._last_purge = now
+            self.repository.purge_expired()
+
+    def issue(
+        self,
+        *,
+        user_id: Any | None,
+        client_id: str | None,
+        scopes: list[str],
+        with_refresh: bool = False,
+        ttl: int | None = None,
+        name: str | None = None,
+        personal_access: bool = False,
+    ) -> IssuedToken:
+        self._maybe_purge()
+        ttl = self.access_ttl if ttl is None else ttl
+        sub = None if user_id is None else str(user_id)
+        access_token = self.encoder.encode(
+            {
+                "sub": sub,
+                "client_id": client_id,
+                "scopes": list(scopes),
+                "token_type": "access",
+            },
+            ttl_seconds=ttl,
+        )
+        jti = self.encoder.decode(access_token, verify_exp=False)["jti"]
+        self.repository.store_access_token(
+            jti=jti,
+            user_id=user_id,
+            client_id=client_id,
+            scopes=list(scopes),
+            expires_at=time.time() + ttl,
+            name=name,
+            personal_access=personal_access,
+        )
+        refresh_token = None
+        if with_refresh:
+            refresh_token = self._issue_refresh(jti, user_id, client_id, scopes)
+        return IssuedToken(
+            access_token=access_token,
+            token_type="Bearer",
+            expires_in=ttl,
+            scopes=list(scopes),
+            jti=jti,
+            refresh_token=refresh_token,
+        )
+
+    def _issue_refresh(self, access_jti: str, user_id, client_id, scopes) -> str:
+        token_id = secrets.token_urlsafe(48)
+        self.repository.store_refresh_token(
+            token_id=token_id,
+            access_jti=access_jti,
+            user_id=user_id,
+            client_id=client_id,
+            scopes=list(scopes),
+            expires_at=time.time() + self.refresh_ttl,
+        )
+        return token_id
+
+    def create_personal_access_token(
+        self, *, user_id: Any, name: str, scopes: list[str], ttl: int | None = None
+    ) -> IssuedToken:
+        return self.issue(
+            user_id=user_id,
+            client_id=None,
+            scopes=scopes,
+            ttl=self.personal_access_ttl if ttl is None else ttl,
+            name=name,
+            personal_access=True,
+        )
+
+    def refresh(self, refresh_token: str, scopes: list[str] | None = None) -> IssuedToken:
+        record = self.repository.find_refresh_token(refresh_token)
+        if record is None or not record.active:
+            raise InvalidGrant("The refresh token is invalid, expired, or revoked.")
+
+        new_scopes = list(record.scopes)
+        if scopes is not None:
+            widened = set(scopes) - set(record.scopes)
+            if widened:
+                raise InvalidGrant("Requested scopes exceed those of the original grant.")
+            new_scopes = list(scopes)
+
+        # Rotate: revoke the previous access + refresh pair before minting a new one.
+        self.repository.revoke_access_token(record.access_jti)
+        self.repository.revoke_refresh_token(record.token_id)
+
+        return self.issue(
+            user_id=record.user_id,
+            client_id=record.client_id,
+            scopes=new_scopes,
+            with_refresh=True,
+        )
+
+    def authenticate(self, access_token: str) -> dict[str, Any]:
+        claims = self.encoder.decode(access_token)
+        record = self.repository.find_access_token(claims.get("jti", ""))
+        if record is None or not record.active:
+            raise InvalidToken("The access token has been revoked or is unknown.")
+        return claims
+
+    def revoke_access(self, jti: str) -> bool:
+        return self.repository.revoke_access_token(jti)
+
+    def revoke_refresh(self, token_id: str) -> bool:
+        return self.repository.revoke_refresh_token(token_id)
+
+    def introspect(self, access_token: str) -> dict[str, Any]:
+        try:
+            claims = self.authenticate(access_token)
+        except InvalidToken:
+            return {"active": False}
+        record = self.repository.find_access_token(claims["jti"])
+        return {
+            "active": True,
+            "scope": " ".join(record.scopes),
+            "client_id": record.client_id,
+            "sub": claims.get("sub"),
+            "token_type": "Bearer",
+            "exp": claims.get("exp"),
+            "iat": claims.get("iat"),
+            "jti": claims["jti"],
+        }