tortoise-auth 0.2.0__py3-none-any.whl

tortoise_auth/__init__.py

@@ -0,0 +1,65 @@
+"""Async authentication and user management for Tortoise ORM."""
+
+__version__ = "0.2.0"
+
+from tortoise_auth.config import AuthConfig, configure, get_config
+from tortoise_auth.events import emit, emitter, on
+from tortoise_auth.exceptions import (
+    AuthenticationError,
+    BadSignatureError,
+    ConfigurationError,
+    EventError,
+    InvalidHashError,
+    InvalidPasswordError,
+    SignatureExpiredError,
+    SigningError,
+    TokenError,
+    TokenExpiredError,
+    TokenInvalidError,
+    TokenRevokedError,
+    TortoiseAuthError,
+)
+from tortoise_auth.models import (
+    AbstractUser,
+    BlacklistedToken,
+    OutstandingToken,
+)
+from tortoise_auth.services import AuthService
+from tortoise_auth.signing import Signer, TimestampSigner, make_token, verify_token
+from tortoise_auth.tokens import AuthResult, TokenBackend, TokenPair, TokenPayload
+from tortoise_auth.tokens.jwt import JWTBackend
+
+__all__ = [
+    "AbstractUser",
+    "AuthConfig",
+    "AuthResult",
+    "AuthService",
+    "AuthenticationError",
+    "BadSignatureError",
+    "BlacklistedToken",
+    "ConfigurationError",
+    "EventError",
+    "InvalidHashError",
+    "InvalidPasswordError",
+    "JWTBackend",
+    "OutstandingToken",
+    "SignatureExpiredError",
+    "Signer",
+    "SigningError",
+    "TimestampSigner",
+    "TokenBackend",
+    "TokenError",
+    "TokenExpiredError",
+    "TokenInvalidError",
+    "TokenPair",
+    "TokenPayload",
+    "TokenRevokedError",
+    "TortoiseAuthError",
+    "configure",
+    "emit",
+    "emitter",
+    "get_config",
+    "make_token",
+    "on",
+    "verify_token",
+]

tortoise_auth/config.py

@@ -0,0 +1,101 @@
+"""Global configuration for tortoise-auth."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from tortoise_auth.exceptions import ConfigurationError
+from tortoise_auth.hashers import default_password_hash
+from tortoise_auth.validators.common import CommonPasswordValidator
+from tortoise_auth.validators.length import MinimumLengthValidator
+from tortoise_auth.validators.numeric import NumericPasswordValidator
+from tortoise_auth.validators.similarity import UserAttributeSimilarityValidator
+
+if TYPE_CHECKING:
+    from pwdlib import PasswordHash
+
+    from tortoise_auth.validators import PasswordValidator
+
+
+def _default_validators() -> list[PasswordValidator]:
+    return [
+        MinimumLengthValidator(),
+        CommonPasswordValidator(),
+        NumericPasswordValidator(),
+        UserAttributeSimilarityValidator(),
+    ]
+
+
+@dataclass
+class AuthConfig:
+    """Configuration for tortoise-auth."""
+
+    user_model: str = ""
+
+    # Hasher parameters
+    argon2_time_cost: int = 3
+    argon2_memory_cost: int = 65536
+    argon2_parallelism: int = 4
+    bcrypt_rounds: int = 12
+    pbkdf2_iterations: int = 600_000
+
+    # Validators
+    password_validators: list[PasswordValidator] = field(default_factory=_default_validators)
+
+    # Token settings
+    access_token_lifetime: int = 900  # 15 minutes
+    refresh_token_lifetime: int = 604_800  # 7 days
+
+    # Password limits
+    max_password_length: int = 4096
+
+    # Signing (HMAC)
+    signing_secret: str = ""
+    signing_token_lifetime: int = 86_400  # 24 hours
+
+    # JWT settings
+    jwt_secret: str = ""
+    jwt_algorithm: str = "HS256"
+    jwt_issuer: str = ""
+    jwt_audience: str = ""
+    jwt_blacklist_enabled: bool = False
+
+    def validate(self) -> None:
+        """Validate config. Raises ConfigurationError."""
+        if self.access_token_lifetime <= 0:
+            raise ConfigurationError("access_token_lifetime must be positive")
+        if self.refresh_token_lifetime <= 0:
+            raise ConfigurationError("refresh_token_lifetime must be positive")
+
+    @property
+    def effective_signing_secret(self) -> str:
+        """Return signing_secret."""
+        return self.signing_secret
+
+    def get_password_hash(self) -> PasswordHash:
+        """Build a PasswordHash instance from current config."""
+        return default_password_hash(
+            argon2_time_cost=self.argon2_time_cost,
+            argon2_memory_cost=self.argon2_memory_cost,
+            argon2_parallelism=self.argon2_parallelism,
+            bcrypt_rounds=self.bcrypt_rounds,
+            pbkdf2_iterations=self.pbkdf2_iterations,
+        )
+
+
+_config: AuthConfig | None = None
+
+
+def configure(config: AuthConfig) -> None:
+    """Set the global auth configuration."""
+    global _config
+    _config = config
+
+
+def get_config() -> AuthConfig:
+    """Get the global auth configuration, creating a default if needed."""
+    global _config
+    if _config is None:
+        _config = AuthConfig()
+    return _config

tortoise_auth/events.py

@@ -0,0 +1,69 @@
+"""Async event emitter for tortoise-auth lifecycle hooks."""
+
+from __future__ import annotations
+
+import logging
+from collections import defaultdict
+from collections.abc import Callable, Coroutine
+from typing import Any
+
+from tortoise_auth.exceptions import EventError
+
+logger = logging.getLogger(__name__)
+
+Handler = Callable[..., Coroutine[Any, Any, Any]]
+
+
+class EventEmitter:
+    """Simple async event emitter with sequential handler execution."""
+
+    def __init__(self, *, propagate_errors: bool = False) -> None:
+        self.propagate_errors = propagate_errors
+        self._listeners: dict[str, list[Handler]] = defaultdict(list)
+
+    def on(self, event_name: str) -> Callable[[Handler], Handler]:
+        """Decorator to register a handler for an event."""
+
+        def decorator(handler: Handler) -> Handler:
+            self.add_listener(event_name, handler)
+            return handler
+
+        return decorator
+
+    def add_listener(self, event_name: str, handler: Handler) -> None:
+        """Register a handler for an event."""
+        self._listeners[event_name].append(handler)
+
+    def remove_listener(self, event_name: str, handler: Handler) -> None:
+        """Remove a handler for an event."""
+        self._listeners[event_name].remove(handler)
+
+    async def emit(self, event_name: str, *args: Any, **kwargs: Any) -> None:
+        """Emit an event, calling all registered handlers sequentially."""
+        for handler in self._listeners[event_name][:]:
+            try:
+                await handler(*args, **kwargs)
+            except Exception as exc:
+                error = EventError(event_name, handler.__name__, exc)
+                if self.propagate_errors:
+                    raise error from exc
+                logger.error(str(error))
+
+    def listeners(self, event_name: str) -> list[Handler]:
+        """Return a copy of the listener list for an event."""
+        return list(self._listeners[event_name])
+
+    def clear(self, event_name: str | None = None) -> None:
+        """Clear listeners. If event_name is None, clear all."""
+        if event_name is None:
+            self._listeners.clear()
+        else:
+            self._listeners.pop(event_name, None)
+
+
+# Module-level emitter instance and convenience aliases
+emitter = EventEmitter()
+on = emitter.on
+emit = emitter.emit
+add_listener = emitter.add_listener
+remove_listener = emitter.remove_listener

tortoise_auth/exceptions.py

@@ -0,0 +1,73 @@
+"""Exception classes for tortoise-auth."""
+
+
+class TortoiseAuthError(Exception):
+    """Base exception for all tortoise-auth errors."""
+
+
+class AuthenticationError(TortoiseAuthError):
+    """Raised when authentication fails."""
+
+
+class InvalidPasswordError(TortoiseAuthError):
+    """Raised when password validation fails.
+
+    Collects all validation errors before raising.
+    """
+
+    def __init__(self, errors: list[str]) -> None:
+        self.errors = errors
+        super().__init__("; ".join(errors))
+
+
+class InvalidHashError(TortoiseAuthError):
+    """Raised when a password hash is not recognized by any hasher."""
+
+    def __init__(self, hash: str) -> None:
+        self.hash = hash
+        super().__init__(f"Unknown password hashing algorithm for hash: {hash!r}")
+
+
+class ConfigurationError(TortoiseAuthError):
+    """Raised when configuration is invalid."""
+
+
+class EventError(TortoiseAuthError):
+    """Raised when an event handler fails."""
+
+    def __init__(self, event_name: str, handler_name: str, original: Exception) -> None:
+        self.event_name = event_name
+        self.handler_name = handler_name
+        self.original = original
+        super().__init__(
+            f"Handler {handler_name!r} for event {event_name!r} "
+            f"raised {type(original).__name__}: {original}"
+        )
+
+
+class TokenError(TortoiseAuthError):
+    """Raised when a token operation fails."""
+
+
+class TokenExpiredError(TokenError):
+    """Raised when a token has expired."""
+
+
+class TokenInvalidError(TokenError):
+    """Raised when a token is structurally invalid or cannot be decoded."""
+
+
+class TokenRevokedError(TokenError):
+    """Raised when a revoked token is presented."""
+
+
+class SigningError(TortoiseAuthError):
+    """Raised when token signing or verification fails."""
+
+
+class SignatureExpiredError(SigningError):
+    """Raised when a signed token has expired."""
+
+
+class BadSignatureError(SigningError):
+    """Raised when a signed token has an invalid signature."""

tortoise_auth/hashers/__init__.py

@@ -0,0 +1,61 @@
+"""Password hashing utilities for tortoise-auth."""
+
+from __future__ import annotations
+
+from pwdlib import PasswordHash
+from pwdlib.hashers import HasherProtocol
+from pwdlib.hashers.argon2 import Argon2Hasher
+from pwdlib.hashers.bcrypt import BcryptHasher
+
+from tortoise_auth.hashers.argon2 import default_hasher as _argon2_default
+from tortoise_auth.hashers.bcrypt import default_hasher as _bcrypt_default
+from tortoise_auth.hashers.pbkdf2 import PBKDF2Hasher
+
+
+def default_password_hash(
+    *,
+    argon2_time_cost: int = 3,
+    argon2_memory_cost: int = 65536,
+    argon2_parallelism: int = 4,
+    bcrypt_rounds: int = 12,
+    pbkdf2_iterations: int = 600_000,
+) -> PasswordHash:
+    """Create a PasswordHash with all supported hashers.
+
+    Argon2 is the primary hasher; Bcrypt and PBKDF2 are kept for migration.
+    """
+    return PasswordHash([
+        _argon2_default(
+            time_cost=argon2_time_cost,
+            memory_cost=argon2_memory_cost,
+            parallelism=argon2_parallelism,
+        ),
+        _bcrypt_default(rounds=bcrypt_rounds),
+        PBKDF2Hasher(iterations=pbkdf2_iterations),
+    ])
+
+
+def make_password(password: str) -> str:
+    """Hash a password using the primary hasher (Argon2)."""
+    return default_password_hash().hash(password)
+
+
+def check_password(password: str, hashed: str) -> tuple[bool, str | None]:
+    """Verify a password and return (valid, updated_hash).
+
+    If the hash was made with a non-primary hasher or outdated params,
+    ``updated_hash`` contains the re-hashed value for transparent migration.
+    """
+    return default_password_hash().verify_and_update(password, hashed)
+
+
+__all__ = [
+    "Argon2Hasher",
+    "BcryptHasher",
+    "HasherProtocol",
+    "PBKDF2Hasher",
+    "PasswordHash",
+    "check_password",
+    "default_password_hash",
+    "make_password",
+]

tortoise_auth/hashers/argon2.py

@@ -0,0 +1,20 @@
+"""Argon2 password hasher (wraps pwdlib)."""
+
+from pwdlib.hashers.argon2 import Argon2Hasher
+
+
+def default_hasher(
+    *,
+    time_cost: int = 3,
+    memory_cost: int = 65536,
+    parallelism: int = 4,
+) -> Argon2Hasher:
+    """Create an Argon2Hasher with OWASP-recommended defaults."""
+    return Argon2Hasher(
+        time_cost=time_cost,
+        memory_cost=memory_cost,
+        parallelism=parallelism,
+    )
+
+
+__all__ = ["Argon2Hasher", "default_hasher"]

tortoise_auth/hashers/bcrypt.py

@@ -0,0 +1,11 @@
+"""Bcrypt password hasher (wraps pwdlib)."""
+
+from pwdlib.hashers.bcrypt import BcryptHasher
+
+
+def default_hasher(*, rounds: int = 12) -> BcryptHasher:
+    """Create a BcryptHasher with OWASP-recommended defaults."""
+    return BcryptHasher(rounds=rounds)
+
+
+__all__ = ["BcryptHasher", "default_hasher"]

tortoise_auth/hashers/pbkdf2.py

@@ -0,0 +1,61 @@
+"""PBKDF2-SHA256 password hasher (Django-compatible format)."""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import os
+
+_DEFAULT_ITERATIONS = 600_000
+
+
+class PBKDF2Hasher:
+    """PBKDF2-SHA256 hasher implementing pwdlib's HasherProtocol.
+
+    Hash format: ``pbkdf2_sha256$iterations$salt_b64$hash_b64``
+    """
+
+    def __init__(self, iterations: int = _DEFAULT_ITERATIONS) -> None:
+        self.iterations = iterations
+
+    @classmethod
+    def identify(cls, hash: str | bytes) -> bool:
+        if isinstance(hash, bytes):
+            hash = hash.decode("utf-8")
+        return hash.startswith("pbkdf2_sha256$")
+
+    def hash(self, password: str | bytes, *, salt: bytes | None = None) -> str:
+        if isinstance(password, str):
+            password = password.encode("utf-8")
+        if salt is None:
+            salt = os.urandom(16)
+        dk = hashlib.pbkdf2_hmac("sha256", password, salt, self.iterations)
+        salt_b64 = base64.b64encode(salt).decode("ascii")
+        hash_b64 = base64.b64encode(dk).decode("ascii")
+        return f"pbkdf2_sha256${self.iterations}${salt_b64}${hash_b64}"
+
+    def verify(self, password: str | bytes, hash: str | bytes) -> bool:
+        if isinstance(password, str):
+            password = password.encode("utf-8")
+        if isinstance(hash, bytes):
+            hash = hash.decode("utf-8")
+        parts = hash.split("$")
+        if len(parts) != 4 or parts[0] != "pbkdf2_sha256":
+            return False
+        iterations = int(parts[1])
+        salt = base64.b64decode(parts[2])
+        stored_hash = base64.b64decode(parts[3])
+        dk = hashlib.pbkdf2_hmac("sha256", password, salt, iterations)
+        return hmac.compare_digest(dk, stored_hash)
+
+    def check_needs_rehash(self, hash: str | bytes) -> bool:
+        if isinstance(hash, bytes):
+            hash = hash.decode("utf-8")
+        parts = hash.split("$")
+        if len(parts) != 4:
+            return True
+        return int(parts[1]) != self.iterations
+
+
+__all__ = ["PBKDF2Hasher"]

tortoise_auth/integrations/__init__.py

@@ -0,0 +1 @@
+"""Framework integrations for tortoise-auth."""

tortoise_auth/integrations/starlette.py

@@ -0,0 +1,142 @@
+"""Starlette integration for tortoise-auth.
+
+Provides ``AuthenticationMiddleware``-compatible backend and route helpers
+so that ``request.user`` is automatically populated from a Bearer token.
+
+Usage::
+
+    from starlette.applications import Starlette
+    from starlette.middleware.authentication import AuthenticationMiddleware
+    from tortoise_auth.integrations.starlette import TokenAuthBackend
+
+    app = Starlette(...)
+    app.add_middleware(AuthenticationMiddleware, backend=TokenAuthBackend())
+"""
+
+from __future__ import annotations
+
+import functools
+from collections.abc import Callable
+from typing import Any
+
+from starlette.authentication import AuthCredentials, AuthenticationBackend
+from starlette.requests import HTTPConnection, Request
+from starlette.responses import JSONResponse, RedirectResponse, Response
+
+from tortoise_auth.exceptions import AuthenticationError, TokenError
+from tortoise_auth.services import AuthService
+
+__all__ = ["AnonymousUser", "TokenAuthBackend", "login_required", "require_auth"]
+
+
+class AnonymousUser:
+    """Unauthenticated user placeholder.
+
+    Compatible with Starlette's ``BaseUser`` protocol and
+    ``AbstractUser``'s boolean properties.
+    """
+
+    @property
+    def is_authenticated(self) -> bool:
+        return False
+
+    @property
+    def is_anonymous(self) -> bool:
+        return True
+
+    @property
+    def display_name(self) -> str:
+        return ""
+
+
+class TokenAuthBackend(AuthenticationBackend):
+    """Bearer-token authentication backend for Starlette's ``AuthenticationMiddleware``."""
+
+    def __init__(
+        self,
+        auth_service: AuthService | None = None,
+        *,
+        scopes: tuple[str, ...] = ("authenticated",),
+    ) -> None:
+        self._auth_service = auth_service
+        self._scopes = scopes
+
+    @property
+    def auth_service(self) -> AuthService:
+        if self._auth_service is None:
+            self._auth_service = AuthService()
+        return self._auth_service
+
+    async def authenticate(
+        self, conn: HTTPConnection
+    ) -> tuple[AuthCredentials, Any]:
+        anonymous = (AuthCredentials([]), AnonymousUser())
+
+        authorization = conn.headers.get("Authorization")
+        if not authorization:
+            return anonymous
+
+        parts = authorization.split(" ", 1)
+        if len(parts) != 2 or parts[0].lower() != "bearer":
+            return anonymous
+
+        token = parts[1]
+        try:
+            user = await self.auth_service.authenticate(token)
+        except (TokenError, AuthenticationError):
+            return anonymous
+
+        return AuthCredentials(list(self._scopes)), user
+
+
+def require_auth(request: Request) -> Any:
+    """Extract the authenticated user from a request or raise ``AuthenticationError``.
+
+    This is a synchronous helper intended for use inside route handlers::
+
+        async def my_route(request: Request) -> Response:
+            user = require_auth(request)
+            return JSONResponse({"email": user.email})
+    """
+    if not request.user.is_authenticated:
+        raise AuthenticationError("Authentication required")
+    return request.user
+
+
+def login_required(
+    fn: Callable[..., Any] | None = None,
+    *,
+    status_code: int = 401,
+    redirect_url: str | None = None,
+) -> Any:
+    """Decorator that rejects unauthenticated requests.
+
+    Supports usage with and without parentheses::
+
+        @login_required
+        async def view(request): ...
+
+        @login_required(status_code=403)
+        async def admin_view(request): ...
+
+        @login_required(redirect_url="/login")
+        async def html_view(request): ...
+    """
+
+    def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
+        @functools.wraps(func)
+        async def wrapper(request: Request, *args: Any, **kwargs: Any) -> Response:
+            if not request.user.is_authenticated:
+                if redirect_url is not None:
+                    return RedirectResponse(url=redirect_url, status_code=302)
+                return JSONResponse(
+                    {"detail": "Authentication required"},
+                    status_code=status_code,
+                )
+            return await func(request, *args, **kwargs)  # type: ignore[no-any-return]
+
+        return wrapper
+
+    if fn is not None:
+        return decorator(fn)
+    return decorator

tortoise_auth/models/__init__.py

@@ -0,0 +1,10 @@
+"""User and token models for tortoise-auth."""
+
+from tortoise_auth.models.base import AbstractUser
+from tortoise_auth.models.jwt_blacklist import BlacklistedToken, OutstandingToken
+
+__all__ = [
+    "AbstractUser",
+    "BlacklistedToken",
+    "OutstandingToken",
+]