flask-advanced-auth 0.1.0__py3-none-any.whl

flask_advanced_auth/TokenProxy.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+"""
+Module contains proxy class for JWT token encoding and decoding.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any, Optional
+import jwt
+from .jwt_rules import JWTAuthenticationRules
+from datetime import datetime, timezone, timedelta
+
+
+class JsonWebToken(ABC):
+    """Abstract base class for JWT encode/decode operations (Proxy pattern)."""
+
+    @abstractmethod
+    def encode_token(self, payload: dict, secret_key: str, algorithm: str) -> str:
+        """Encode a payload into a JWT token string."""
+        pass
+
+    @abstractmethod
+    def decode_token(self, token: str, secret_key: str, algorithm: str) -> Optional[dict]:
+        """Decode a JWT token string into a payload dict."""
+        pass
+
+
+class PyJWT(JsonWebToken):
+    """Concrete JWT proxy using the PyJWT library."""
+
+    @property
+    def rule_handler(self) -> JWTAuthenticationRules:
+        return JWTAuthenticationRules()
+
+    def required_payload(self, rule_name: str, token_type: str) -> dict[str, Any]:
+        """Build the standard required payload fields (type + expiry)."""
+        token_lifetime: timedelta = self.rule_handler.get_token_lifetime(
+            rule_name, token_type
+        )
+        return {
+            "type": token_type,
+            "exp": datetime.now(timezone.utc) + token_lifetime,
+        }
+
+    def encode_token(
+        self,
+        payload: dict,
+        secret_key: str,
+        algorithm: str,
+        *args: Any,
+        **kwargs: Any,
+    ) -> str:
+        """Encode a payload dict into a signed JWT string."""
+        return jwt.encode(payload, key=secret_key, algorithm=algorithm, *args, **kwargs)
+
+    def decode_token(
+        self,
+        token: str,
+        secret_key: str,
+        algorithm: str,
+        *args: Any,
+        **kwargs: Any,
+    ) -> Optional[dict]:
+        """Decode and verify a JWT token."""
+        try:
+            return jwt.decode(
+                token, key=secret_key, algorithms=[algorithm], *args, **kwargs
+            )
+        except (jwt.ExpiredSignatureError, jwt.InvalidTokenError):
+            return None

flask_advanced_auth/__init__.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+"""
+flask-advanced-auth
+===================
+Advanced JWT authentication for Flask with multi-rule support,
+token tracking, and blacklisting.
+
+MIT License
+"""
+
+from .initialize import initialize_jwt_authentication
+from .jwt_rules import JWTAuthenticationRules
+from .factory import TokenFactory
+from .decorators import authenticate
+from .blacklist_token import BlackListed
+from .authentication_classes import (
+    BaseAuthentication,
+    AuthenticateJWT,
+    HeaderAuthentication,
+    CookieAuthentication,
+    QueryParamAuthentication,
+)
+from .helpers import refresh_access_token, logout
+from .models import AbstractTrackModelMixin, AbstractBlackListModelMixin
+from .database import Database
+from .exceptions import (
+    InvalidDefaultKeyType,
+    JWTRulesEmpty,
+    DefaultRuleDoesNotExist,
+    InvalidJWTRule,
+    JWTFieldValueError,
+    TokenExpired,
+    TokenInvalid,
+    TokenBlacklisted,
+    TokenTypeMismatch,
+)
+
+__version__ = "0.1.0"
+__author__ = "Waheed"
+__license__ = "MIT"
+
+__all__ = [
+    # Core bootstrap & rules
+    "initialize_jwt_authentication",
+    "JWTAuthenticationRules",
+    "Database",
+    # Factory & Decorator
+    "TokenFactory",
+    "authenticate",
+    "BlackListed",
+    # Authentication Strategies
+    "BaseAuthentication",
+    "AuthenticateJWT",
+    "HeaderAuthentication",
+    "CookieAuthentication",
+    "QueryParamAuthentication",
+    # Helpers
+    "refresh_access_token",
+    "logout",
+    # Model Mixins
+    "AbstractTrackModelMixin",
+    "AbstractBlackListModelMixin",
+    # Exceptions
+    "InvalidDefaultKeyType",
+    "JWTRulesEmpty",
+    "DefaultRuleDoesNotExist",
+    "InvalidJWTRule",
+    "JWTFieldValueError",
+    "TokenExpired",
+    "TokenInvalid",
+    "TokenBlacklisted",
+    "TokenTypeMismatch",
+]

flask_advanced_auth/authentication_classes.py

@@ -0,0 +1,168 @@
+from __future__ import annotations
+"""
+Module contains base and concrete authentication classes.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any, Optional, Union
+from flask import Request
+from .blacklist_token import BlackListed
+from .factory import TokenFactory
+
+
+class BaseAuthentication(ABC):
+    """Abstract base class for authentication strategies.
+
+    Subclass this to implement custom token extraction and validation logic.
+
+    Args:
+        token_headers: The prefix expected in the Authorization header (e.g. 'Bearer ').
+        token_type: The expected token type field value (e.g. 'access', 'refresh').
+        rule_name: The JWT rule name to use for validation.
+    """
+
+    def __init__(
+        self,
+        token_headers: str = "Bearer ",
+        token_type: str = "access",
+        rule_name: Optional[str] = None,
+    ) -> None:
+        self.token_headers: str = token_headers
+        self.token_type: str = token_type
+        self.rule_name: Optional[str] = rule_name
+
+    def parse_token(self, request: Request) -> Optional[str]:
+        """Extract the JWT string from the request Authorization header.
+
+        Expects the header format: ``Authorization: <prefix><token>``
+        where ``prefix`` is ``self.token_headers`` (e.g. ``'Bearer '``).
+        """
+        auth_header: Optional[str] = request.headers.get("Authorization")
+        if not auth_header:
+            return None
+        if not auth_header.startswith(self.token_headers):
+            return None
+        token = auth_header[len(self.token_headers):]
+        if not token:
+            return None
+        return token
+
+    @abstractmethod
+    def authenticate(self, token: str) -> Optional[dict[str, Any]]:
+        """Validate a token and return its payload, or None if invalid."""
+        pass
+
+    def authenticate_request(self, request: Request) -> Optional[dict[str, Any]]:
+        """Extract and authenticate the token from the request.
+
+        Args:
+            request: The Flask request object.
+
+        Returns:
+            The decoded token payload dict if valid, None otherwise.
+        """
+        token = self.parse_token(request)
+        if token is None:
+            return None
+        return self.authenticate(token)
+
+
+class AuthenticateJWT(BaseAuthentication):
+    """Standard JWT authentication — validates token extracted from Authorization header.
+
+    Checks:
+    1. Token is not blacklisted (if blacklisting is enabled for the rule).
+    2. Token signature and expiry are valid.
+    3. Token type matches the expected type.
+    """
+
+    def validate_token(self, token: str) -> Optional[dict[str, Any]]:
+        """Decode and verify a token using the configured rule."""
+        try:
+            return TokenFactory().validate_token(token, self.rule_name)
+        except Exception:
+            return None
+
+    def validate_token_type(self, decoded_payload: dict[str, Any]) -> bool:
+        """Check that the decoded payload's 'type' field matches self.token_type."""
+        return decoded_payload.get("type") == self.token_type
+
+    def authenticate(self, token: str) -> Optional[dict[str, Any]]:
+        """Validate a JWT token string.
+
+        Args:
+            token: The raw JWT string.
+
+        Returns:
+            The decoded payload if all checks pass, None otherwise.
+        """
+        if BlackListed().is_blacklisted(self.rule_name, token):
+            return None
+
+        payload: Optional[dict[str, Any]] = self.validate_token(token)
+        if payload is None:
+            return None
+
+        if not self.validate_token_type(payload):
+            return None
+
+        return payload
+
+
+class HeaderAuthentication(AuthenticateJWT):
+    """Explicit alias for Header-based JWT authentication."""
+    pass
+
+
+class CookieAuthentication(AuthenticateJWT):
+    """JWT authentication that extracts tokens from HTTP cookies.
+
+    Args:
+        token_headers: Unused (kept for interface compatibility).
+        token_type: Expected token type ('access' or 'refresh').
+        rule_name: JWT rule name.
+        cookie_name: Name of the cookie containing the token (default: 'access_token').
+    """
+
+    cookie_name: str = "access_token"
+
+    def __init__(
+        self,
+        token_headers: str = "Bearer ",
+        token_type: str = "access",
+        rule_name: Optional[str] = None,
+        cookie_name: str = "access_token",
+    ) -> None:
+        super().__init__(token_headers=token_headers, token_type=token_type, rule_name=rule_name)
+        self.cookie_name = cookie_name
+
+    def parse_token(self, request: Request) -> Optional[str]:
+        """Extract the token from request cookies."""
+        return request.cookies.get(self.cookie_name)
+
+
+class QueryParamAuthentication(AuthenticateJWT):
+    """JWT authentication that extracts tokens from URL query parameters.
+
+    Args:
+        token_headers: Unused (kept for interface compatibility).
+        token_type: Expected token type ('access' or 'refresh').
+        rule_name: JWT rule name.
+        param_name: Name of the query parameter (default: 'token').
+    """
+
+    param_name: str = "token"
+
+    def __init__(
+        self,
+        token_headers: str = "Bearer ",
+        token_type: str = "access",
+        rule_name: Optional[str] = None,
+        param_name: str = "token",
+    ) -> None:
+        super().__init__(token_headers=token_headers, token_type=token_type, rule_name=rule_name)
+        self.param_name = param_name
+
+    def parse_token(self, request: Request) -> Optional[str]:
+        """Extract the token from query arguments."""
+        return request.args.get(self.param_name)

flask_advanced_auth/blacklist_token.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+"""
+Module contains BlackListed class for token revocation.
+"""
+
+from abc import ABC, abstractmethod
+from .jwt_rules import JWTAuthenticationRules
+from .model_managers import ModelManager
+from typing import Any, Union, Optional
+
+
+class AbstractBlackList(ABC):
+    """Abstract interface for token blacklisting."""
+
+    @abstractmethod
+    def blacklist(self, rule_name: str, token: str) -> None:
+        """Add a token to the blacklist."""
+        pass
+
+    @abstractmethod
+    def is_blacklisted(self, rule_name: str, token: str) -> bool:
+        """Check whether a token is blacklisted."""
+        pass
+
+
+class BlackListed(AbstractBlackList):
+    """Blacklist manager that persists revoked tokens in a database table."""
+
+    def __init__(
+        self,
+        rule_handler: Optional[JWTAuthenticationRules] = None,
+        manager: Optional[ModelManager] = None,
+    ) -> None:
+        self.__rule_handler = rule_handler
+        self.__manager = manager
+
+    @property
+    def _rule_handler(self) -> JWTAuthenticationRules:
+        if self.__rule_handler is not None:
+            return self.__rule_handler
+        return JWTAuthenticationRules()
+
+    @_rule_handler.setter
+    def _rule_handler(self, value: JWTAuthenticationRules) -> None:
+        self.__rule_handler = value
+
+    @property
+    def _manager(self) -> ModelManager:
+        if self.__manager is None:
+            self.__manager = ModelManager()
+        return self.__manager
+
+    @_manager.setter
+    def _manager(self, value: ModelManager) -> None:
+        self.__manager = value
+
+    def blacklist_token(
+        self,
+        rule_name: str,
+        token: str,
+        *args: Any,
+        **kwargs: Any,
+    ) -> None:
+        """Persist a token to the rule's blacklist table."""
+        model_path: str = self._rule_handler.get_blacklisted_table_path(rule_name)
+        BlackListModel = self._manager.get_model(model_path=model_path)
+        model_instance = BlackListModel(token=token, **kwargs)
+        self._manager.register(model_instance)
+
+    def unregister_token_from_track_model(
+        self,
+        rule_name: str,
+        token: str,
+    ) -> None:
+        """Remove a token record from the rule's token-tracking table."""
+        model_path: str = self._rule_handler.get_track_created_table_path(rule_name)
+        model_instance = self._manager.get_instance(model_path=model_path, token=token)
+        if model_instance:
+            self._manager.unregister(model_instance)
+
+    def blacklist(
+        self,
+        rule_name: str,
+        token: str,
+        extra_blacklist_fields: dict = {},
+        remove_token_from_track_model: bool = False,
+    ) -> None:
+        """Blacklist a token and optionally remove it from the tracking table."""
+        self.blacklist_token(rule_name=rule_name, token=token, **extra_blacklist_fields)
+        if remove_token_from_track_model:
+            self.unregister_token_from_track_model(rule_name, token)
+
+    def is_blacklisted(self, rule_name: str, token: str) -> Union[Any, None]:
+        """Check whether a token is in the blacklist."""
+        if not self._rule_handler.get_blacklisted(rule_name):
+            return False
+        model_path: str = self._rule_handler.get_blacklisted_table_path(rule_name)
+        blacklisted_token = self._manager.get_instance(
+            model_path=model_path, token=token
+        )
+        return blacklisted_token

flask_advanced_auth/database.py

@@ -0,0 +1,108 @@
+from __future__ import annotations
+"""
+Module contains the Database singleton — wraps a Flask-SQLAlchemy db instance.
+"""
+
+from typing import Optional, Any, Type
+from flask_sqlalchemy import SQLAlchemy
+from .import_handler import import_handler
+
+_UNSET = object()
+
+
+class DatabasePathNotProvided(Exception):
+    """Raised when a database path is not provided on first initialization."""
+    pass
+
+
+class Database:
+    """Singleton that holds and provides access to the Flask-SQLAlchemy db instance.
+
+    The database instance is discovered via its dotted import path, e.g.
+    ``"myapp.database.db"``.
+
+    Example:
+        >>> # First call — initialize with the path
+        >>> Database("myapp.database.db")
+        >>> # Subsequent calls — access the db
+        >>> db = Database().db
+        >>> db.session.query(MyModel).filter_by(id=1).first()
+    """
+
+    _instance: Type["Database"] = None
+
+    def __new__(cls, *args: Any, **kwargs: Any) -> Any:
+        if cls._instance is None:
+            cls._instance = super(Database, cls).__new__(cls)
+        return cls._instance
+
+    def __init__(self, path: Optional[str] = _UNSET) -> None:
+        if path is None:
+            raise DatabasePathNotProvided(
+                "Database path must be provided on first initialization."
+            )
+        if path is not _UNSET:
+            self.database_path = path
+            self._initialized = True
+
+    @classmethod
+    def _reset(cls) -> None:
+        """Reset singleton state. Intended for use in tests only."""
+        cls._instance = None
+
+    @property
+    def database_path(self) -> str:
+        """The dotted import path to the SQLAlchemy db instance."""
+        if not hasattr(self, "_database_path"):
+            raise DatabasePathNotProvided(
+                "Database path has not been configured. Call initialize_jwt_authentication() first."
+            )
+        return self._database_path
+
+    @database_path.setter
+    def database_path(self, value: str) -> None:
+        if not isinstance(value, str):
+            raise DatabasePathNotProvided(
+                f"Database path must be a string, got {type(value)}"
+            )
+        self._database_path = value
+
+    @property
+    def db(self) -> SQLAlchemy:
+        """The SQLAlchemy database instance."""
+        return self.grab_database(self.database_path)
+
+    @staticmethod
+    def grab_database(path: str) -> SQLAlchemy:
+        """Import and return the SQLAlchemy db from the given dotted path."""
+        return import_handler.grab(path=path)
+
+    def model_instance_exists(self, model_class: Any, **kwargs: Any) -> Any:
+        """Query the database for a model instance matching the given filters.
+
+        Args:
+            model_class: The SQLAlchemy model class.
+            **kwargs: Filter arguments passed to ``filter_by()``.
+
+        Returns:
+            The first matching instance, or None.
+        """
+        return self.db.session.query(model_class).filter_by(**kwargs).first()
+
+    def get_model_by_path(self, model_path: str) -> Type:
+        """Return a model class from its dotted import path."""
+        return import_handler.grab(model_path)
+
+    def create_instance(self, instance: Any) -> None:
+        """Add and commit a new model instance to the database."""
+        self.db.session.add(instance)
+        self.db.session.commit()
+
+    def delete(self, instance: Any) -> None:
+        """Delete and commit removal of a model instance from the database."""
+        self.db.session.delete(instance)
+        self.db.session.commit()
+
+    def update(self, *args: Any, **kwargs: Any) -> None:
+        """Commit any pending changes to the database session."""
+        self.db.session.commit()

flask_advanced_auth/decorators.py

@@ -0,0 +1,126 @@
+from __future__ import annotations
+"""
+Module contains the @authenticate decorator for protecting Flask routes.
+"""
+
+from functools import wraps
+from flask import request, make_response, Response
+from typing import Any, Callable, Tuple, Union, Type, Optional
+from .authentication_classes import BaseAuthentication
+from .jwt_rules import JWTAuthenticationRules
+from .model_managers import ModelManager
+
+
+def authenticate(
+    auth_classes: list = None,
+    rule_name: Optional[str] = None,
+    token_type: str = "access",
+    assign_to_request: bool = False,
+    assignment_key: str = "instance",
+    model_id_key_name: str = "id",
+    return_func: Callable = make_response,
+    return_func_args: Tuple[Any, ...] = ({"error": "Unauthorized access"}, 401),
+    jwt_rules: JWTAuthenticationRules = None,
+) -> Callable:
+    """Decorator that protects a Flask route with JWT authentication.
+
+    At least one authentication class in ``auth_classes`` must successfully
+    authenticate the request for the view to be called.
+
+    Args:
+        auth_classes: List of :class:`BaseAuthentication` subclass **classes**
+            (not instances) to try in order. If any succeeds, the route is called.
+        rule_name: JWT rule name (None -> default rule).
+        token_type: Expected token type ('access' or 'refresh').
+        assign_to_request: If True, attaches the authenticated model instance to
+            ``request.<assignment_key>``.
+        assignment_key: The attribute name on the request object (default 'instance').
+        model_id_key_name: The primary key field name on the model (default 'id').
+        return_func: Callable invoked on auth failure (default: ``make_response``).
+        return_func_args: Arguments passed to ``return_func`` on failure.
+        jwt_rules: Override for the JWTAuthenticationRules singleton (for testing).
+
+    Returns:
+        The decorated view function or a failure response.
+
+    Raises:
+        TypeError: If auth_classes, return_func, or return_func_args are invalid types.
+    """
+    # Default to AuthenticateJWT if no classes provided
+    if auth_classes is None:
+        from .authentication_classes import AuthenticateJWT
+        auth_classes = [AuthenticateJWT]
+
+    if jwt_rules is None:
+        jwt_rules = JWTAuthenticationRules()
+
+    # Validate arguments
+    if not callable(return_func):
+        raise TypeError("return_func must be a callable.")
+    if not isinstance(return_func_args, tuple):
+        raise TypeError("return_func_args must be a tuple.")
+    if not isinstance(auth_classes, list) or not all(
+        (isinstance(auth, type) and issubclass(auth, BaseAuthentication))
+        for auth in auth_classes
+    ):
+        raise TypeError(
+            "auth_classes must be a list of BaseAuthentication subclass classes (not instances)."
+        )
+
+    # Grab token header prefix for this rule
+    token_header: str = jwt_rules.get_token_header(rule_name)
+
+    def decorator(view: Callable) -> Callable:
+        # FIX T-04: corrected indentation of return wrapper
+        @wraps(view)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            if not auth_classes:
+                return return_func(*return_func_args)
+
+            for auth_class in auth_classes:
+                auth_instance: BaseAuthentication = auth_class(
+                    token_header, token_type, rule_name
+                )
+                payload: Optional[dict[str, Any]] = auth_instance.authenticate_request(request)
+                if payload:
+                    if assign_to_request:
+                        instance = _get_instance(rule_name, payload, model_id_key_name, jwt_rules)
+                        setattr(request, assignment_key, instance)
+                    return view(*args, **kwargs)
+
+            # None of the auth_classes authenticated the request
+            return return_func(*return_func_args)
+
+        return wrapper
+
+    return decorator
+
+
+def _get_instance(
+    rule_name: Optional[str],
+    payload: dict[str, Any],
+    model_id_key_name: str = "id",
+    jwt_rules: Optional[JWTAuthenticationRules] = None,
+    model_manager: Optional[ModelManager] = None,
+) -> Any:
+    """Retrieve the model instance identified by the JWT payload.
+
+    Args:
+        rule_name: The JWT rule name.
+        payload: The decoded JWT payload dict.
+        model_id_key_name: The primary key field name (default 'id').
+        jwt_rules: JWTAuthenticationRules instance.
+        model_manager: ModelManager instance.
+
+    Returns:
+        The model instance, or None if not found.
+    """
+    if jwt_rules is None:
+        jwt_rules = JWTAuthenticationRules()
+    if model_manager is None:
+        model_manager = ModelManager()
+
+    table_class = model_manager.get_model(jwt_rules.get_table_path(rule_name))
+    id_key_name: str = f"{table_class.__tablename__}_{model_id_key_name}"
+    instance_id = payload.get(id_key_name)
+    return model_manager.get_instance(table_class, **{model_id_key_name: instance_id})