swiftpy-framework 0.1.0__py3-none-any.whl

swiftpy/auth/token_blacklist.py

@@ -0,0 +1,300 @@
+from __future__ import annotations
+
+import asyncio
+import math
+import time
+from collections.abc import Awaitable, Sequence
+from typing import Any, Protocol
+
+import redis.asyncio as aioredis
+
+from swiftpy.auth.jwt_issuer import JWTIssuer
+from swiftpy.core.config import Config
+from swiftpy.core.container import Container, get_container
+from swiftpy.support.redis_config import build_redis_url
+
+
+class _BlacklistPipeline(Protocol):
+    def exists(self, *names: str) -> Any: ...
+    def get(self, name: str, /) -> Any: ...
+    def execute(self) -> Awaitable[list[Any]]: ...
+
+
+class _BlacklistRedisClient(Protocol):
+    def pipeline(self) -> _BlacklistPipeline: ...
+    def set(
+        self, name: str, value: str, /, ex: int | None = None
+    ) -> Awaitable[bool | str | bytes | None]: ...
+    def scan(
+        self,
+        cursor: int = 0,
+        match: str | None = None,
+        count: int | None = None,
+    ) -> Awaitable[tuple[int, Sequence[bytes | str]]]: ...
+    def delete(self, *names: str) -> Awaitable[int]: ...
+    def aclose(self) -> Awaitable[None]: ...
+
+
+def _validate_positive_ttl(ttl: int | None) -> int | None:
+    """Validate explicit blacklist TTL overrides so <= 0 never silently extends to 7 days."""
+    if ttl is None:
+        return None
+    if isinstance(ttl, bool) or not isinstance(ttl, int) or ttl <= 0:
+        raise ValueError("ttl must be a positive integer")
+    return ttl
+
+
+def is_token_blacklist_enabled(config: Config | None = None) -> bool:
+    """Return whether JWT token blacklist revocation checking is enabled."""
+    cfg = config
+    if cfg is None:
+        try:
+            cfg = Config.get_instance()
+        except (RuntimeError, ValueError):
+            return True
+
+    for key in (
+        "auth.guards.jwt.blacklist_enabled",
+        "auth.jwt.blacklist_enabled",
+        "auth.blacklist_enabled",
+    ):
+        val = cfg.get(key)
+        if val is not None:
+            if isinstance(val, bool):
+                return val
+            if isinstance(val, str):
+                return val.strip().lower() not in ("false", "0", "no", "off")
+            return bool(val)
+    return True
+
+
+class TokenBlacklist:
+    """
+    Redis-backed token revocation list for JWT logout and invalidation (Decision D-1, P2-A3).
+
+    Keys are stored with a TTL capped at min(exp - now, max_token_lifetime),
+    ensuring Redis automatically reclaims memory once the token would have
+    expired normally, while preventing attacker-controlled memory exhaustion.
+    """
+
+    def __init__(
+        self,
+        redis_client: _BlacklistRedisClient | None = None,
+        redis_url: str | None = None,
+        prefix: str = "jwt_blacklist:",
+        default_ttl: int = 604800,  # 7 days
+        max_token_lifetime: int = 604800,  # 7 days
+        issuer: JWTIssuer | None = None,
+        config: Config | None = None,
+        container: Container | None = None,
+    ) -> None:
+        self._client: _BlacklistRedisClient | None = redis_client
+        self._redis_url = redis_url
+        self.prefix = prefix
+        self.default_ttl = default_ttl
+        self.max_token_lifetime = max_token_lifetime
+        self._issuer = issuer
+        self._config = config
+        self._container = container
+        self._owns_client = redis_client is None
+        self._lock = asyncio.Lock()
+        self._local_cache: dict[tuple[str, str], float] = {}
+        self._local_cache_ttl: float = 2.0
+
+    async def get_client(self) -> _BlacklistRedisClient:
+        """Lazily initialize and return the async Redis client safely under lock."""
+        if self._client is None:
+            async with self._lock:
+                if self._client is None:
+                    url = self._redis_url
+                    if not url:
+                        cfg = self._config
+                        if cfg is None:
+                            try:
+                                cfg = Config.get_instance()
+                            except (RuntimeError, ValueError):
+                                cfg = Config()
+                        url = build_redis_url(cfg, section="auth")
+
+                    created: _BlacklistRedisClient = aioredis.from_url(
+                        url, decode_responses=True
+                    )
+                    self._client = created
+                    self._owns_client = True
+
+        assert self._client is not None
+        return self._client
+
+    async def revoke(self, jti: str, ttl: int | None = None) -> None:
+        """
+        Revoke a token by its unique JWT ID (jti) with an optional TTL in seconds.
+        """
+        if not jti:
+            raise ValueError("JWT ID (jti) cannot be empty")
+
+        validated_ttl = _validate_positive_ttl(ttl)
+        client = await self.get_client()
+        key = f"{self.prefix}{jti}"
+        raw_ttl = validated_ttl if validated_ttl is not None else self.default_ttl
+        expiration = min(raw_ttl, self.max_token_lifetime)
+
+        self._local_cache.clear()
+        await client.set(key, "revoked", ex=expiration)
+
+    async def revoke_token(
+        self,
+        token: str,
+        issuer: JWTIssuer | None = None,
+    ) -> None:
+        """
+        Revoke an issued JWT by verifying its signature and calculating the remaining TTL.
+        Cryptographically verifies token signature before revoking to prevent
+        attacker-chosen TTL / unbounded memory DoS (P2-A3).
+        """
+        active_issuer = issuer or self._issuer
+        if (
+            active_issuer is None
+            and self._container is not None
+            and self._container.has(JWTIssuer)
+        ):
+            active_issuer = self._container.resolve(JWTIssuer)
+        if active_issuer is None:
+            try:
+                container = get_container()
+                if container.has(JWTIssuer):
+                    active_issuer = container.resolve(JWTIssuer)
+            except RuntimeError:
+                pass
+
+        if active_issuer is None:
+            raise ValueError(
+                "JWTIssuer is required to cryptographically verify token signature before revocation."
+            )
+
+        # Cryptographically verify signature; exp and future nbf are handled below so future-active tokens can be pre-emptively revoked
+        payload = active_issuer.decode_token(token, verify_exp=False, verify_nbf=False)
+
+        jti = payload.get("jti")
+        if not jti:
+            raise ValueError("Token does not contain a 'jti' claim to revoke")
+
+        exp = payload.get("exp")
+        ttl: int
+        if (
+            exp is not None
+            and not isinstance(exp, bool)
+            and isinstance(exp, (int, float))
+            and math.isfinite(exp)
+        ):
+            remaining = int(exp - time.time())
+            if remaining <= 0:
+                # Token has already expired; naturally rejected by exp check, skip Redis allocation
+                return
+            ttl = min(remaining, self.max_token_lifetime)
+        else:
+            ttl = min(self.default_ttl, self.max_token_lifetime)
+
+        await self.revoke(jti, ttl=ttl)
+
+    async def revoke_all_for_subject(
+        self,
+        subject: str | int,
+        ttl: int | None = None,
+    ) -> None:
+        """
+        Revoke all tokens issued for a given subject (user_id) at or before the current timestamp.
+        Used for logout-all, password reset, or account compromise (P2-A3).
+        """
+        if subject is None or str(subject) == "":
+            raise ValueError("Subject cannot be empty")
+
+        validated_ttl = _validate_positive_ttl(ttl)
+        client = await self.get_client()
+        sub_key = f"{self.prefix}sub:{subject}"
+        raw_ttl = (
+            validated_ttl if validated_ttl is not None else self.max_token_lifetime
+        )
+        expiration = min(raw_ttl, self.max_token_lifetime)
+        now = int(time.time())
+        self._local_cache.clear()
+        await client.set(sub_key, str(now), ex=expiration)
+
+    async def is_revoked(
+        self,
+        jti: str,
+        subject: str | int | None = None,
+        issued_at: int | None = None,
+    ) -> bool:
+        """
+        Determine whether a JWT ID (jti) or subject has been revoked.
+        O(1) check against individual jti and per-subject not_before timestamp.
+        """
+        if not jti and not subject:
+            return False
+
+        cache_key = (jti or "", str(subject) if subject is not None else "")
+        now = time.monotonic()
+        cached_ts = self._local_cache.get(cache_key)
+        if cached_ts is not None and (now - cached_ts) < self._local_cache_ttl:
+            return False
+
+        client = await self.get_client()
+
+        pipe = client.pipeline()
+        has_jti = bool(jti)
+        has_sub = subject is not None
+
+        if has_jti:
+            pipe.exists(f"{self.prefix}{jti}")
+        if has_sub:
+            pipe.get(f"{self.prefix}sub:{subject}")
+
+        results = await pipe.execute()
+
+        res_idx = 0
+        if has_jti:
+            if results[res_idx]:
+                return True
+            res_idx += 1
+
+        if has_sub:
+            sub_cutoff = results[res_idx]
+            if sub_cutoff is not None:
+                cutoff_ts = int(sub_cutoff)
+                if issued_at is None or issued_at <= cutoff_ts:
+                    return True
+
+        if len(self._local_cache) > 10000:
+            self._local_cache.clear()
+        self._local_cache[cache_key] = now
+        return False
+
+    async def clear(self) -> None:
+        """
+        Remove all blacklisted tokens matching this prefix (primarily for tests/maintenance).
+        """
+        self._local_cache.clear()
+        client = await self.get_client()
+        match_pattern = f"{self.prefix}*"
+        cursor = 0
+        keys_to_delete: list[str] = []
+
+        while True:
+            cursor, keys = await client.scan(
+                cursor=cursor, match=match_pattern, count=100
+            )
+            if keys:
+                keys_to_delete.extend(
+                    k.decode("utf-8") if isinstance(k, bytes) else str(k) for k in keys
+                )
+            if cursor == 0:
+                break
+
+        if keys_to_delete:
+            await client.delete(*keys_to_delete)
+
+    async def close(self) -> None:
+        """Close the underlying Redis client connection pool."""
+        if self._client is not None and self._owns_client:
+            await self._client.aclose()
+            self._client = None

swiftpy/cache/__init__.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from swiftpy.cache.cache import Cache, CacheManager
+from swiftpy.cache.driver import CacheDriver
+from swiftpy.cache.drivers.memory import MemoryDriver
+from swiftpy.cache.drivers.redis import RedisDriver
+
+__all__ = [
+    "Cache",
+    "CacheDriver",
+    "CacheManager",
+    "MemoryDriver",
+    "RedisDriver",
+]

swiftpy/cache/cache.py

@@ -0,0 +1,251 @@
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+import redis.asyncio as aioredis
+
+from swiftpy.cache.driver import CacheDriver
+from swiftpy.cache.drivers.memory import MemoryDriver
+from swiftpy.cache.drivers.redis import RedisDriver
+from swiftpy.core.config import Config
+from swiftpy.support.redis_config import resolve_redis_params
+
+
+class Cache:
+    """
+    Cache manager for SwiftPY applications.
+
+    Provides a unified interface across caching backends (Redis, in-memory)
+    with driver management, configuration integration, and stampede-safe caching.
+    """
+
+    def __init__(
+        self,
+        config: Config | None = None,
+        default_driver: str | None = None,
+    ) -> None:
+        if config is None:
+            try:
+                self.config = Config.get_instance()
+            except RuntimeError:
+                self.config = Config()
+        else:
+            self.config = config
+
+        self._default_driver_name = default_driver
+        self._drivers: dict[str, CacheDriver] = {}
+        self._custom_creators: dict[str, Callable[..., CacheDriver]] = {}
+        self._shared_pools: dict[tuple[Any, ...], aioredis.ConnectionPool] = {}
+
+    @property
+    def default_driver_name(self) -> str:
+        if self._default_driver_name:
+            return self._default_driver_name
+        return str(self.config.get("cache.default", "redis"))
+
+    def extend(
+        self,
+        driver_name: str,
+        factory: Callable[..., CacheDriver],
+    ) -> None:
+        """Register a custom cache driver creator."""
+        self._custom_creators[driver_name] = factory
+
+    def driver(self, name: str | None = None) -> CacheDriver:
+        """
+        Resolve a cache driver instance by name, or return the default driver.
+        """
+        driver_name = name or self.default_driver_name
+
+        if driver_name in self._drivers:
+            return self._drivers[driver_name]
+
+        driver_instance = self._resolve_driver(driver_name)
+        self._drivers[driver_name] = driver_instance
+        return driver_instance
+
+    def store(self, name: str | None = None) -> CacheDriver:
+        """Alias for driver()."""
+        return self.driver(name)
+
+    def _build_store_prefix(self, store_config: dict[str, Any]) -> str:
+        """Resolve cache store prefix consistently including optional app.name namespace."""
+        app_name = str(self.config.get("app.name", "")).strip()
+        raw_val = (
+            store_config["prefix"]
+            if "prefix" in store_config
+            else self.config.get("cache.prefix", "swiftpy_cache:")
+        )
+        raw_prefix = str(raw_val) if raw_val is not None else "swiftpy_cache:"
+        if (
+            app_name
+            and not raw_prefix.startswith(f"{app_name}:")
+            and not raw_prefix.startswith(f"{app_name}_")
+        ):
+            return f"{app_name}:{raw_prefix}"
+        return raw_prefix
+
+    def _resolve_store_ttl(self, store_config: dict[str, Any]) -> float | None:
+        """Resolve default TTL while distinguishing explicit None or 0.0 values."""
+        default_ttl = (
+            store_config["ttl"]
+            if "ttl" in store_config
+            else self.config.get("cache.default_ttl", None)
+        )
+        return float(default_ttl) if default_ttl is not None else None
+
+    def _resolve_driver(self, name: str) -> CacheDriver:
+        if name in self._custom_creators:
+            creator = self._custom_creators[name]
+            return creator()
+
+        stores = self.config.get("cache.stores", {})
+        store_config: dict[str, Any] = {}
+        if isinstance(stores, dict) and name in stores:
+            raw = stores[name]
+            if isinstance(raw, dict):
+                store_config = raw
+
+        driver_type = store_config.get("driver", name)
+
+        if driver_type == "memory":
+            prefix = self._build_store_prefix(store_config)
+            ttl_val = self._resolve_store_ttl(store_config)
+            raw_max_items = (
+                store_config["max_items"]
+                if "max_items" in store_config
+                else self.config.get("cache.max_items", 1000)
+            )
+            max_items = int(raw_max_items) if raw_max_items is not None else None
+            return MemoryDriver(prefix=prefix, default_ttl=ttl_val, max_items=max_items)
+
+        if driver_type == "redis":
+            prefix = self._build_store_prefix(store_config)
+            ttl_val = self._resolve_store_ttl(store_config)
+            host = store_config.get("host")
+            port = store_config.get("port")
+            password = store_config.get("password")
+            database = store_config.get("database", 0)
+            redis_url = store_config.get(
+                "url", self.config.get("cache.redis_url") or self.config.get("cache.url")
+            )
+            max_connections = int(
+                store_config.get(
+                    "max_connections", self.config.get("cache.max_connections", 50)
+                )
+            )
+            timeout = float(
+                store_config.get("timeout", self.config.get("cache.timeout", 30.0))
+            )
+
+            pool_key = (
+                redis_url,
+                str(host) if host is not None else None,
+                int(port) if port is not None else None,
+                str(password) if password is not None else None,
+                int(database) if database is not None else 0,
+                max_connections,
+                timeout,
+            )
+
+            if pool_key not in self._shared_pools:
+                if redis_url:
+                    pool = aioredis.ConnectionPool.from_url(
+                        redis_url,
+                        decode_responses=True,
+                        max_connections=max_connections,
+                        timeout=timeout,
+                    )
+                else:
+                    params = resolve_redis_params(
+                        section="cache",
+                        host=str(host) if host is not None else None,
+                        port=int(port) if port is not None else None,
+                        password=str(password) if password is not None else None,
+                        database=int(database) if database is not None else 0,
+                    )
+                    pool = aioredis.BlockingConnectionPool(
+                        host=params["host"],
+                        port=params["port"],
+                        db=params["database"],
+                        password=params["password"] or None,
+                        decode_responses=True,
+                        max_connections=max_connections,
+                        timeout=timeout,
+                    )
+                self._shared_pools[pool_key] = pool
+
+            return RedisDriver(
+                connection_pool=self._shared_pools[pool_key],
+                prefix=prefix,
+                default_ttl=ttl_val,
+                max_connections=max_connections,
+                timeout=timeout,
+            )
+
+        raise ValueError(f"Unsupported cache driver: '{name}'")
+
+    async def get(self, key: str, default: Any = None) -> Any:
+        return await self.driver().get(key, default)
+
+    async def set(
+        self,
+        key: str,
+        value: Any,
+        ttl: float | None = None,
+    ) -> bool:
+        return await self.driver().set(key, value, ttl)
+
+    async def remember(
+        self,
+        key: str,
+        ttl: float | None,
+        callback: Callable[[], Any] | Callable[[], Awaitable[Any]],
+        lock_timeout: float = 10.0,
+    ) -> Any:
+        return await self.driver().remember(
+            key, ttl, callback, lock_timeout=lock_timeout
+        )
+
+    async def forget(self, key: str) -> bool:
+        return await self.driver().forget(key)
+
+    async def has(self, key: str) -> bool:
+        return await self.driver().has(key)
+
+    async def flush(self) -> bool:
+        return await self.driver().flush()
+
+    async def pull(self, key: str, default: Any = None) -> Any:
+        return await self.driver().pull(key, default)
+
+    async def add(
+        self,
+        key: str,
+        value: Any,
+        ttl: float | None = None,
+    ) -> bool:
+        return await self.driver().add(key, value, ttl)
+
+    async def increment(
+        self, key: str, value: int = 1, ttl: float | None = None
+    ) -> int:
+        return await self.driver().increment(key, value, ttl=ttl)
+
+    async def decrement(
+        self, key: str, value: int = 1, ttl: float | None = None
+    ) -> int:
+        return await self.driver().decrement(key, value, ttl=ttl)
+
+    async def close(self) -> None:
+        for drv in self._drivers.values():
+            await drv.close()
+        self._drivers.clear()
+        for pool in self._shared_pools.values():
+            await pool.disconnect()
+        self._shared_pools.clear()
+
+
+# CacheManager is an alias for Cache for consistency across naming styles
+CacheManager = Cache