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

fastapi_startkit_auth/__init__.py

@@ -0,0 +1,67 @@
+"""Passport-style OAuth2 + JWT authentication for FastAPI.
+
+Public API mirrors the config-driven guard/provider/passwords model of Laravel
+Passport while staying idiomatic FastAPI:
+
+    from fastapi_startkit_auth import Application, AuthProvider, AuthConfig
+
+Attributes are resolved lazily so importing a single submodule never forces the
+whole package to load.
+"""
+from __future__ import annotations
+
+import importlib
+from typing import Any
+
+__version__ = "0.2.0"
+
+_EXPORTS = {
+    "AuthConfig": ("fastapi_startkit_auth.config", "AuthConfig"),
+    "AuthProvider": ("fastapi_startkit_auth.provider", "AuthProvider"),
+    "Application": ("fastapi_startkit_auth.application", "Application"),
+    "AuthManager": ("fastapi_startkit_auth.manager", "AuthManager"),
+    "current_user": ("fastapi_startkit_auth.dependencies", "current_user"),
+    "optional_user": ("fastapi_startkit_auth.dependencies", "optional_user"),
+    "require_scopes": ("fastapi_startkit_auth.dependencies", "require_scopes"),
+    "require_abilities": ("fastapi_startkit_auth.dependencies", "require_abilities"),
+    "AuthError": ("fastapi_startkit_auth.exceptions", "AuthError"),
+    "InvalidGrant": ("fastapi_startkit_auth.exceptions", "InvalidGrant"),
+    "InvalidClient": ("fastapi_startkit_auth.exceptions", "InvalidClient"),
+    "InvalidToken": ("fastapi_startkit_auth.exceptions", "InvalidToken"),
+    "InsufficientScope": ("fastapi_startkit_auth.exceptions", "InsufficientScope"),
+    "InvalidSession": ("fastapi_startkit_auth.exceptions", "InvalidSession"),
+    "CsrfTokenMismatch": ("fastapi_startkit_auth.exceptions", "CsrfTokenMismatch"),
+    "Auth": ("fastapi_startkit_auth.facade", "Auth"),
+    "SessionGuard": ("fastapi_startkit_auth.guards.session", "SessionGuard"),
+    "SessionMiddleware": ("fastapi_startkit_auth.middleware.session", "SessionMiddleware"),
+    "CsrfMiddleware": ("fastapi_startkit_auth.middleware.csrf", "CsrfMiddleware"),
+    "AuthServiceProvider": ("fastapi_startkit_auth.startkit", "AuthServiceProvider"),
+    "SessionRecord": ("fastapi_startkit_auth.sessions.models", "SessionRecord"),
+    "SessionStore": ("fastapi_startkit_auth.sessions.store", "SessionStore"),
+    "InMemorySessionStore": ("fastapi_startkit_auth.sessions.store", "InMemorySessionStore"),
+    "SqlSessionStore": ("fastapi_startkit_auth.sessions.sql", "SqlSessionStore"),
+    "TokenGuard": ("fastapi_startkit_auth.guards.token", "TokenGuard"),
+    "ApiTokenManager": ("fastapi_startkit_auth.apitokens.manager", "ApiTokenManager"),
+    "NewApiToken": ("fastapi_startkit_auth.apitokens.manager", "NewApiToken"),
+    "ApiTokenRecord": ("fastapi_startkit_auth.apitokens.models", "ApiTokenRecord"),
+    "ApiTokenRepository": ("fastapi_startkit_auth.apitokens.repository", "ApiTokenRepository"),
+    "InMemoryApiTokenRepository": (
+        "fastapi_startkit_auth.apitokens.repository",
+        "InMemoryApiTokenRepository",
+    ),
+    "SqlApiTokenRepository": ("fastapi_startkit_auth.apitokens.sql", "SqlApiTokenRepository"),
+}
+
+__all__ = list(_EXPORTS)
+
+
+def __getattr__(name: str) -> Any:
+    try:
+        module_name, attr = _EXPORTS[name]
+    except KeyError:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}") from None
+    return getattr(importlib.import_module(module_name), attr)
+
+
+def __dir__() -> list[str]:
+    return sorted(__all__)

fastapi_startkit_auth/apitokens/__init__.py

@@ -0,0 +1,13 @@
+from .manager import ApiTokenManager, NewApiToken
+from .models import ApiTokenRecord
+from .repository import ApiTokenRepository, InMemoryApiTokenRepository
+from .sql import SqlApiTokenRepository
+
+__all__ = [
+    "ApiTokenManager",
+    "ApiTokenRecord",
+    "ApiTokenRepository",
+    "InMemoryApiTokenRepository",
+    "NewApiToken",
+    "SqlApiTokenRepository",
+]

fastapi_startkit_auth/apitokens/manager.py

@@ -0,0 +1,122 @@
+from __future__ import annotations
+
+import secrets
+import threading
+import time
+from dataclasses import dataclass
+from typing import Any
+
+from ..exceptions import InvalidToken
+from .models import ApiTokenRecord
+from .repository import ApiTokenRepository, generate_token_secret, hash_token_secret
+
+# Every verification failure raises this exact message so responses (and their
+# timing, via the dummy compare below) never reveal whether the id exists.
+_GENERIC_FAILURE = "The API token is invalid."
+
+_DUMMY_HASH = hash_token_secret("!" + generate_token_secret())
+
+
+@dataclass(repr=False)
+class NewApiToken:
+    """The one and only carrier of a token's plaintext.
+
+    ``plain_text`` (``"{id}|{secret}"``) exists here and nowhere else — the
+    repository stores only the secret's hash, so it cannot be shown again.
+    """
+
+    record: ApiTokenRecord
+    plain_text: str
+
+    def __repr__(self) -> str:
+        # The dataclass auto-repr would leak the live secret into logs,
+        # error-tracker locals, and test output; show only the id half.
+        return (
+            f"NewApiToken(record={self.record!r}, plain_text='{self.record.id}|***redacted***')"
+        )
+
+
+class ApiTokenManager:
+    """Issues, verifies, revokes, and lists opaque API tokens.
+
+    Exposed as ``AuthManager.api_tokens``; apps wire their own management
+    routes around it (the package ships none, per the app-owns-routes
+    decision).
+    """
+
+    def __init__(
+        self,
+        repository: ApiTokenRepository,
+        default_ttl: float | None = None,
+        purge_interval: float = 300,
+    ) -> None:
+        self.repository = repository
+        self._default_ttl = default_ttl
+        self._purge_interval = purge_interval
+        self._purge_lock = threading.Lock()
+        self._last_purge = time.time()
+
+    def _maybe_purge(self) -> None:
+        """Drop expired records periodically so stores stay bounded without a
+        scheduler (mirrors the purge-on-issue pattern of ``TokenService``)."""
+        now = time.time()
+        with self._purge_lock:
+            if now - self._last_purge < self._purge_interval:
+                return
+            self._last_purge = now
+        self.repository.purge_expired()
+
+    def create(
+        self,
+        user_id: Any,
+        name: str | None = None,
+        abilities: list[str] | None = None,
+        expires_at: float | None = None,
+    ) -> NewApiToken:
+        """Issue a token for ``user_id``; the plaintext is returned exactly once.
+
+        ``expires_at`` overrides the configured default ttl; ``None`` with no
+        configured ttl means the token never expires. ``abilities`` default to
+        the unrestricted ``["*"]``.
+        """
+        self._maybe_purge()
+        if expires_at is None and self._default_ttl is not None:
+            expires_at = time.time() + self._default_ttl
+        secret = generate_token_secret()
+        record = self.repository.create(
+            user_id=user_id,
+            token_hash=hash_token_secret(secret),
+            name=name,
+            abilities=list(abilities) if abilities else ["*"],
+            expires_at=expires_at,
+        )
+        return NewApiToken(record=record, plain_text=f"{record.id}|{secret}")
+
+    def verify(self, token: str) -> ApiTokenRecord:
+        """Resolve ``"{id}|{secret}"`` to its live record or raise 401.
+
+        Lookup is by id (O(1), no scan); the secret comparison is constant-time
+        against the stored hash — or against a dummy hash when the id is
+        unknown, so the miss path costs the same as a mismatch.
+        """
+        token_id, sep, secret = token.partition("|")
+        expected = _DUMMY_HASH
+        record = None
+        if sep and token_id and secret:
+            record = self.repository.find(token_id)
+            if record is not None:
+                expected = record.token_hash
+        matched = secrets.compare_digest(hash_token_secret(secret), expected)
+        if record is None or not matched or record.expired:
+            raise InvalidToken(_GENERIC_FAILURE)
+        self.repository.touch(record.id)
+        return record
+
+    def revoke(self, token_id: str) -> bool:
+        return self.repository.revoke(token_id)
+
+    def revoke_all(self, user_id: Any) -> int:
+        return self.repository.revoke_all_for_user(user_id)
+
+    def tokens_for(self, user_id: Any) -> list[ApiTokenRecord]:
+        return self.repository.list_for_user(user_id)

fastapi_startkit_auth/apitokens/models.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class ApiTokenRecord:
+    """Server-side record backing one opaque API token.
+
+    The caller holds ``"{id}|{secret}"``; this record stores only the SHA-256
+    hex digest of the secret, so a leaked store cannot mint valid tokens.
+    ``abilities`` reuse the scope vocabulary (``["*"]`` = unrestricted), so
+    ``require_scopes`` works unchanged on token-authenticated requests.
+    """
+
+    id: str
+    user_id: Any
+    token_hash: str
+    name: str | None = None
+    abilities: list[str] = field(default_factory=lambda: ["*"])
+    last_used_at: float | None = None
+    expires_at: float | None = None
+    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()

fastapi_startkit_auth/apitokens/repository.py

@@ -0,0 +1,120 @@
+from __future__ import annotations
+
+import hashlib
+import secrets
+import time
+from typing import Any, Protocol, runtime_checkable
+
+from .models import ApiTokenRecord
+
+
+def generate_token_id() -> str:
+    return secrets.token_urlsafe(16)
+
+
+def generate_token_secret() -> str:
+    return secrets.token_urlsafe(40)
+
+
+def hash_token_secret(secret: str) -> str:
+    """SHA-256 at rest: correct for high-entropy random secrets (bcrypt would
+    add per-request latency without adding security for non-guessable input)."""
+    return hashlib.sha256(secret.encode()).hexdigest()
+
+
+@runtime_checkable
+class ApiTokenRepository(Protocol):
+    """Contract every API-token backend satisfies.
+
+    Mirrors the ``SessionStore`` pattern: the package ships an in-memory
+    default and a SQL implementation, and apps may implement the same surface
+    against any other store. Implementations must never see or persist the
+    plaintext secret — only its hash arrives here.
+    """
+
+    def create(
+        self,
+        *,
+        user_id: Any,
+        token_hash: str,
+        name: str | None,
+        abilities: list[str],
+        expires_at: float | None,
+    ) -> ApiTokenRecord:
+        """Persist and return a new token record with a fresh id."""
+
+    def find(self, token_id: str) -> ApiTokenRecord | None:
+        """Return the live record for this id, or ``None`` if unknown/expired."""
+
+    def touch(self, token_id: str) -> None:
+        """Record usage (updates ``last_used_at``)."""
+
+    def revoke(self, token_id: str) -> bool:
+        """Delete the record (revocation is row deletion); returns whether it existed."""
+
+    def revoke_all_for_user(self, user_id: Any) -> int:
+        """Delete every token belonging to ``user_id``; returns how many."""
+
+    def list_for_user(self, user_id: Any) -> list[ApiTokenRecord]:
+        """Return the user's live (non-expired) token records."""
+
+    def purge_expired(self) -> None:
+        """Drop expired records (maintenance)."""
+
+
+class InMemoryApiTokenRepository:
+    """Default dict-backed token repository for tests, demos, and prototypes."""
+
+    def __init__(self) -> None:
+        self._tokens: dict[str, ApiTokenRecord] = {}
+
+    def create(
+        self,
+        *,
+        user_id: Any,
+        token_hash: str,
+        name: str | None,
+        abilities: list[str],
+        expires_at: float | None,
+    ) -> ApiTokenRecord:
+        record = ApiTokenRecord(
+            id=generate_token_id(),
+            user_id=user_id,
+            token_hash=token_hash,
+            name=name,
+            abilities=list(abilities),
+            expires_at=expires_at,
+        )
+        self._tokens[record.id] = record
+        return record
+
+    def find(self, token_id: str) -> ApiTokenRecord | None:
+        record = self._tokens.get(token_id)
+        if record is None:
+            return None
+        if record.expired:
+            del self._tokens[token_id]
+            return None
+        return record
+
+    def touch(self, token_id: str) -> None:
+        record = self._tokens.get(token_id)
+        if record is not None:
+            record.last_used_at = time.time()
+
+    def revoke(self, token_id: str) -> bool:
+        return self._tokens.pop(token_id, None) is not None
+
+    def revoke_all_for_user(self, user_id: Any) -> int:
+        doomed = [tid for tid, rec in self._tokens.items() if rec.user_id == user_id]
+        for tid in doomed:
+            del self._tokens[tid]
+        return len(doomed)
+
+    def list_for_user(self, user_id: Any) -> list[ApiTokenRecord]:
+        return [
+            rec for rec in self._tokens.values() if rec.user_id == user_id and not rec.expired
+        ]
+
+    def purge_expired(self) -> None:
+        self._tokens = {tid: rec for tid, rec in self._tokens.items() if not rec.expired}

fastapi_startkit_auth/apitokens/sql.py

@@ -0,0 +1,152 @@
+from __future__ import annotations
+
+import json
+import threading
+import time
+from typing import Any
+
+from .models import ApiTokenRecord
+from .repository import generate_token_id
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS {table} (
+    id TEXT PRIMARY KEY,
+    user_id TEXT,
+    token_hash TEXT NOT NULL,
+    name TEXT,
+    abilities TEXT NOT NULL,
+    last_used_at REAL,
+    expires_at REAL,
+    created_at REAL NOT NULL
+)
+"""
+
+_COLUMNS = "id, user_id, token_hash, name, abilities, last_used_at, expires_at, created_at"
+
+
+class SqlApiTokenRepository:
+    """Persistent :class:`~.repository.ApiTokenRepository` backed by a
+    ``personal_api_tokens`` table.
+
+    Works with any DB-API 2.0 connection using ``qmark`` placeholders (sqlite3
+    out of the box). ``user_id`` and ``abilities`` are JSON-encoded so
+    identifier types and ability lists round-trip exactly, matching the
+    in-memory repository. A lock serialises access because FastAPI runs sync
+    endpoints in a thread pool.
+    """
+
+    def __init__(
+        self,
+        connection: Any,
+        table: str = "personal_api_tokens",
+        create_table: bool = True,
+    ) -> None:
+        self._conn = connection
+        self._table = table
+        self._lock = threading.Lock()
+        if create_table:
+            with self._lock:
+                self._conn.execute(_SCHEMA.format(table=table))
+                self._conn.commit()
+
+    def create(
+        self,
+        *,
+        user_id: Any,
+        token_hash: str,
+        name: str | None,
+        abilities: list[str],
+        expires_at: float | None,
+    ) -> ApiTokenRecord:
+        record = ApiTokenRecord(
+            id=generate_token_id(),
+            user_id=user_id,
+            token_hash=token_hash,
+            name=name,
+            abilities=list(abilities),
+            expires_at=expires_at,
+        )
+        with self._lock:
+            self._conn.execute(
+                f"INSERT INTO {self._table} ({_COLUMNS}) VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
+                (
+                    record.id,
+                    json.dumps(record.user_id),
+                    record.token_hash,
+                    record.name,
+                    json.dumps(record.abilities),
+                    record.last_used_at,
+                    record.expires_at,
+                    record.created_at,
+                ),
+            )
+            self._conn.commit()
+        return record
+
+    def find(self, token_id: str) -> ApiTokenRecord | None:
+        with self._lock:
+            row = self._conn.execute(
+                f"SELECT {_COLUMNS} FROM {self._table} WHERE id = ?", (token_id,)
+            ).fetchone()
+        if row is None:
+            return None
+        record = self._to_record(row)
+        if record.expired:
+            self.revoke(token_id)
+            return None
+        return record
+
+    def touch(self, token_id: str) -> None:
+        with self._lock:
+            self._conn.execute(
+                f"UPDATE {self._table} SET last_used_at = ? WHERE id = ?",
+                (time.time(), token_id),
+            )
+            self._conn.commit()
+
+    def revoke(self, token_id: str) -> bool:
+        with self._lock:
+            cursor = self._conn.execute(
+                f"DELETE FROM {self._table} WHERE id = ?", (token_id,)
+            )
+            self._conn.commit()
+        return cursor.rowcount > 0
+
+    def revoke_all_for_user(self, user_id: Any) -> int:
+        with self._lock:
+            cursor = self._conn.execute(
+                f"DELETE FROM {self._table} WHERE user_id = ?", (json.dumps(user_id),)
+            )
+            self._conn.commit()
+        return cursor.rowcount
+
+    def list_for_user(self, user_id: Any) -> list[ApiTokenRecord]:
+        now = time.time()
+        with self._lock:
+            rows = self._conn.execute(
+                f"SELECT {_COLUMNS} FROM {self._table} "
+                "WHERE user_id = ? AND (expires_at IS NULL OR expires_at >= ?)",
+                (json.dumps(user_id), now),
+            ).fetchall()
+        return [self._to_record(row) for row in rows]
+
+    def purge_expired(self) -> None:
+        with self._lock:
+            self._conn.execute(
+                f"DELETE FROM {self._table} WHERE expires_at IS NOT NULL AND expires_at < ?",
+                (time.time(),),
+            )
+            self._conn.commit()
+
+    @staticmethod
+    def _to_record(row: Any) -> ApiTokenRecord:
+        return ApiTokenRecord(
+            id=row[0],
+            user_id=json.loads(row[1]),
+            token_hash=row[2],
+            name=row[3],
+            abilities=json.loads(row[4]),
+            last_used_at=row[5],
+            expires_at=row[6],
+            created_at=row[7],
+        )

fastapi_startkit_auth/application.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from typing import Any, Iterable
+
+from fastapi import FastAPI
+
+
+class Application:
+    """Thin composition root mirroring ``Application([(AuthProvider, AuthConfig)])``.
+
+    Creates a FastAPI app and registers each ``(ProviderClass, config)`` pair
+    onto it. The resulting FastAPI instance is exposed as ``.api`` and the
+    Application is itself ASGI-callable, so it can be served directly::
+
+        app = Application([(AuthProvider, AuthConfig)])
+        # uvicorn app:app        -> uses Application.__call__
+        # uvicorn app:app.api    -> uses the FastAPI instance
+    """
+
+    def __init__(
+        self,
+        providers: Iterable[tuple[type, Any]] | None = None,
+        api: FastAPI | None = None,
+    ) -> None:
+        self.api = api or FastAPI(title="FastAPI Startkit Auth")
+        self.providers: list[Any] = []
+        for provider_cls, config in providers or []:
+            provider = provider_cls(config)
+            provider.register(self.api)
+            self.providers.append(provider)
+
+    @property
+    def auth(self):
+        """Return the AuthManager of the first registered provider."""
+        return self.providers[0].manager if self.providers else None
+
+    async def __call__(self, scope, receive, send):
+        await self.api(scope, receive, send)

fastapi_startkit_auth/clients/__init__.py

@@ -0,0 +1,4 @@
+from .models import Client
+from .repository import InMemoryClientRepository
+
+__all__ = ["Client", "InMemoryClientRepository"]

fastapi_startkit_auth/clients/models.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class Client:
+    """An OAuth2 client (application).
+
+    Confidential clients authenticate with a secret; public clients (SPAs, native
+    apps) do not and must use the authorization-code + PKCE flow. An empty
+    ``grant_types`` means the client may use any supported grant.
+    """
+
+    id: str
+    name: str
+    secret: str | None = None
+    redirect_uris: list[str] = field(default_factory=list)
+    confidential: bool = True
+    grant_types: list[str] = field(default_factory=list)
+    revoked: bool = False
+
+    def allows_redirect(self, uri: str) -> bool:
+        return uri in self.redirect_uris
+
+    def allows_grant(self, grant_type: str) -> bool:
+        if not self.grant_types:
+            return True
+        return grant_type in self.grant_types

fastapi_startkit_auth/clients/repository.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+import secrets
+import uuid
+
+from ..security.hashing import BcryptHasher, Hasher
+from .models import Client
+
+
+class InMemoryClientRepository:
+    """Client registry with hashed-secret storage.
+
+    ``register`` returns the plaintext secret exactly once (mirroring how real
+    OAuth servers surface credentials); only its hash is retained.
+    """
+
+    def __init__(self, hasher: Hasher | None = None) -> None:
+        self._hasher = hasher or BcryptHasher()
+        self._clients: dict[str, Client] = {}
+
+    def register(
+        self,
+        *,
+        name: str,
+        redirect_uris: list[str] | None = None,
+        confidential: bool = True,
+        grant_types: list[str] | None = None,
+    ) -> tuple[Client, str | None]:
+        client_id = uuid.uuid4().hex
+        plain_secret: str | None = None
+        stored_secret: str | None = None
+        if confidential:
+            plain_secret = secrets.token_urlsafe(40)
+            stored_secret = self._hasher.make(plain_secret)
+        client = Client(
+            id=client_id,
+            name=name,
+            secret=stored_secret,
+            redirect_uris=list(redirect_uris or []),
+            confidential=confidential,
+            grant_types=list(grant_types or []),
+        )
+        self._clients[client_id] = client
+        return client, plain_secret
+
+    def add(self, client: Client) -> Client:
+        self._clients[client.id] = client
+        return client
+
+    def find(self, client_id: str) -> Client | None:
+        return self._clients.get(client_id)
+
+    def all(self) -> list[Client]:
+        return list(self._clients.values())
+
+    def authenticate(self, client_id: str, secret: str | None) -> Client | None:
+        client = self._clients.get(client_id)
+        if client is None or client.revoked:
+            return None
+        if not client.confidential:
+            return client
+        if secret is None or client.secret is None:
+            return None
+        if self._hasher.verify(secret, client.secret):
+            return client
+        return None
+
+    def delete(self, client_id: str) -> bool:
+        return self._clients.pop(client_id, None) is not None