swiftpy-framework 0.1.0__py3-none-any.whl

swiftpy/auth/auth_manager.py

@@ -0,0 +1,259 @@
+from __future__ import annotations
+
+import inspect
+import weakref
+from collections.abc import Callable, Iterator
+from typing import Any
+
+from swiftpy.auth.api_key_guard import ApiKeyGuard
+from swiftpy.auth.jwt_guard import JWTGuard
+from swiftpy.auth.jwt_issuer import JWTIssuer
+from swiftpy.auth.token_blacklist import TokenBlacklist
+from swiftpy.core.config import Config
+from swiftpy.core.container import Container, get_container
+from swiftpy.core.context import Context
+from swiftpy.database.pool import DatabasePool
+from swiftpy.http.request import Request
+
+
+class CurrentUser(dict[str, Any]):
+    """
+    Task-scoped authenticated user context resolvable through the DI container.
+
+    Resolves lazily from `Context` at access time when constructed without explicit
+    payload data, stays synchronized with context updates so C-level readers like
+    `dict(user)` and `json.dumps(user)` see live data, and is never cached in
+    the container scope while unauthenticated.
+    """
+
+    def __init__(self, data: dict[str, Any] | None = None) -> None:
+        self._lazy = data is None
+        self._last_synced: dict[str, Any] = {}
+        if data is None:
+            ctx_user = Context.get("__swiftpy_current_user__")
+            initial = dict(ctx_user) if isinstance(ctx_user, dict) else {}
+            super().__init__(initial)
+            self._last_synced = dict(initial)
+            Context.watch(
+                "__swiftpy_current_user__",
+                weakref.WeakMethod(self._apply_context_payload),
+            )
+        else:
+            super().__init__(data)
+
+    def _apply_context_payload(self, payload: Any) -> None:
+        if not self._lazy:
+            return
+        target = dict(payload) if isinstance(payload, dict) else {}
+        if target != self._last_synced or dict.keys(self) != target.keys():
+            super().clear()
+            super().update(target)
+            self._last_synced = target
+
+    def _sync(self) -> None:
+        if not self._lazy:
+            return
+        ctx_user = Context.get("__swiftpy_current_user__")
+        target = ctx_user if isinstance(ctx_user, dict) else {}
+        if target != self._last_synced:
+            self._apply_context_payload(target)
+
+    @property
+    def _cache_in_scope(self) -> bool:
+        self._sync()
+        return super().__len__() > 0
+
+    def __getitem__(self, key: str) -> Any:
+        self._sync()
+        return super().__getitem__(key)
+
+    def get(self, key: str, default: Any = None) -> Any:
+        self._sync()
+        return super().get(key, default)
+
+    def __contains__(self, key: object) -> bool:
+        self._sync()
+        return super().__contains__(key)
+
+    def __len__(self) -> int:
+        self._sync()
+        return super().__len__()
+
+    def __bool__(self) -> bool:
+        self._sync()
+        return super().__len__() > 0
+
+    def __iter__(self) -> Iterator[str]:
+        self._sync()
+        return super().__iter__()
+
+    def keys(self) -> Any:
+        self._sync()
+        return super().keys()
+
+    def values(self) -> Any:
+        self._sync()
+        return super().values()
+
+    def items(self) -> Any:
+        self._sync()
+        return super().items()
+
+    def copy(self) -> dict[str, Any]:
+        self._sync()
+        return super().copy()
+
+    def to_dict(self) -> dict[str, Any]:
+        self._sync()
+        return super().copy()
+
+    def __repr__(self) -> str:
+        self._sync()
+        return super().__repr__()
+
+    def __eq__(self, other: object) -> bool:
+        self._sync()
+        return super().__eq__(other)
+
+    def __ne__(self, other: object) -> bool:
+        self._sync()
+        return super().__ne__(other)
+
+    @property
+    def id(self) -> Any:
+        self._sync()
+        return super().get("id") or super().get("sub")
+
+    @property
+    def email(self) -> Any:
+        self._sync()
+        return super().get("email")
+
+    @property
+    def is_authenticated(self) -> bool:
+        self._sync()
+        return super().__len__() > 0
+
+
+def current_user() -> Any:
+    """
+    Retrieve the authenticated user payload/record for the current request task.
+    Returns None if unauthenticated.
+    """
+    return Context.get("__swiftpy_current_user__")
+
+
+class AuthManager:
+    """
+    Central authentication coordinator.
+
+    Resolves and caches configured guards ('jwt', 'api_key', or custom drivers),
+    and exposes the authenticated current_user() through the DI container
+    with strict task-scoped isolation.
+    """
+
+    def __init__(self, container: Container | None = None) -> None:
+        self._container = container
+        self._guards: dict[str, Any] = {}
+        self._custom_creators: dict[str, Callable[[Container], Any]] = {
+            "jwt": self._create_default_jwt_guard,
+            "api_key": self._create_default_api_key_guard,
+        }
+
+    @staticmethod
+    def _create_default_jwt_guard(c: Container) -> JWTGuard:
+        issuer = c.resolve(JWTIssuer) if c.has(JWTIssuer) else None
+        blacklist = c.resolve(TokenBlacklist) if c.has(TokenBlacklist) else None
+        return JWTGuard(issuer=issuer, blacklist=blacklist)
+
+    @staticmethod
+    def _create_default_api_key_guard(c: Container) -> ApiKeyGuard:
+        cfg = c.resolve(Config) if c.has(Config) else None
+        pool = c.resolve(DatabasePool) if c.has(DatabasePool) else None
+        return ApiKeyGuard.from_config(config=cfg, pool=pool)
+
+    @property
+    def container(self) -> Container:
+        if self._container is None:
+            self._container = get_container()
+        return self._container
+
+    def default_guard_name(self) -> str:
+        """Retrieve the name of the default guard from configuration."""
+        try:
+            if self.container.has(Config):
+                cfg = self.container.resolve(Config)
+                guard_name = cfg.get("auth.defaults.guard") or cfg.get("auth.default")
+                if guard_name and isinstance(guard_name, str):
+                    return guard_name
+        except RuntimeError:
+            pass
+
+        return "jwt"
+
+    def guard(self, name: str | None = None) -> Any:
+        """
+        Resolve a guard driver instance by name (e.g. 'jwt', 'api_key').
+        If name is None, resolves the default configured guard.
+        """
+        guard_name = name or self.default_guard_name()
+
+        if guard_name in self._guards:
+            return self._guards[guard_name]
+
+        guard_instance = self._resolve(guard_name)
+        self._guards[guard_name] = guard_instance
+        return guard_instance
+
+    def extend(self, name: str, creator: Callable[[Container], Any]) -> None:
+        """Register or override a guard creator factory and invalidate any cached guard."""
+        self._custom_creators[name] = creator
+        self._guards.pop(name, None)
+
+    def _resolve(self, name: str) -> Any:
+        if name in self._custom_creators:
+            return self._custom_creators[name](self.container)
+
+        raise ValueError(f"Auth guard [{name}] is not defined.")
+
+    async def authenticate(
+        self,
+        request: Request | None = None,
+        guard_name: str | None = None,
+    ) -> Any:
+        """
+        Authenticate the request by dispatching to the guard instance registered
+        for `guard_name` (or the default configured guard).
+        """
+        resolved_name = guard_name or self.default_guard_name()
+        g = self.guard(resolved_name)
+
+        if hasattr(g, "authenticate") and callable(g.authenticate):
+            res = g.authenticate(request)
+            if inspect.isawaitable(res):
+                return await res
+            return res
+
+        if callable(g):
+            res = g(request)
+            if inspect.isawaitable(res):
+                return await res
+            return res
+
+        raise TypeError(f"Guard [{resolved_name}] does not support authenticate()")
+
+    def current_user(self) -> Any:
+        """Return the current user from task-scoped context."""
+        return current_user()
+
+    def register_container_bindings(self, container: Container | None = None) -> None:
+        """
+        Register AuthManager as a singleton and CurrentUser as a task-scoped binding
+        in the dependency injection container.
+        """
+        c = container or self.container
+        c.instance(AuthManager, self)
+        c.scoped(
+            CurrentUser,
+            lambda _: CurrentUser(),
+        )

swiftpy/auth/exceptions.py

@@ -0,0 +1,71 @@
+from swiftpy.auth.jwt_issuer import (
+    InvalidAlgorithmError,
+    InvalidSignatureError,
+    InvalidTokenError,
+    JWTError,
+    TokenExpiredError,
+)
+from swiftpy.http.exceptions import HttpException
+
+
+class AuthenticationError(HttpException):
+    """Base exception for authentication failures resulting in HTTP 401."""
+
+    def __init__(
+        self,
+        message: str = "Unauthorized",
+        status_code: int = 401,
+        headers: dict[str, str] | None = None,
+    ) -> None:
+        super().__init__(
+            message=message,
+            status_code=status_code,
+            headers=headers or {"WWW-Authenticate": "Bearer"},
+        )
+
+
+class TokenRevokedError(AuthenticationError):
+    """Raised when a valid token has been revoked in the blacklist."""
+
+    def __init__(self, message: str = "Invalid or expired token") -> None:
+        super().__init__(message=message, status_code=401)
+
+
+class InvalidApiKeyError(AuthenticationError):
+    """Raised when an API key is invalid, inactive, or expired."""
+
+    def __init__(self, message: str = "Invalid API key") -> None:
+        super().__init__(
+            message=message,
+            status_code=401,
+            headers={"WWW-Authenticate": "ApiKey"},
+        )
+
+
+class AuthenticationServiceUnavailableError(HttpException):
+    """Raised when authentication infrastructure (e.g. Redis, Database) is unavailable, resulting in HTTP 503."""
+
+    def __init__(
+        self,
+        message: str = "Authentication service unavailable",
+        status_code: int = 503,
+        headers: dict[str, str] | None = None,
+    ) -> None:
+        super().__init__(
+            message=message,
+            status_code=status_code,
+            headers=headers or {"Retry-After": "30"},
+        )
+
+
+__all__ = [
+    "AuthenticationError",
+    "AuthenticationServiceUnavailableError",
+    "InvalidAlgorithmError",
+    "InvalidApiKeyError",
+    "InvalidSignatureError",
+    "InvalidTokenError",
+    "JWTError",
+    "TokenExpiredError",
+    "TokenRevokedError",
+]

swiftpy/auth/jwt_guard.py

@@ -0,0 +1,230 @@
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from swiftpy.auth.exceptions import (
+    AuthenticationError,
+    AuthenticationServiceUnavailableError,
+    InvalidAlgorithmError,
+    InvalidSignatureError,
+    InvalidTokenError,
+    JWTError,
+    TokenExpiredError,
+    TokenRevokedError,
+)
+from swiftpy.auth.jwt_issuer import JWTIssuer
+from swiftpy.auth.token_blacklist import TokenBlacklist, is_token_blacklist_enabled
+from swiftpy.core.config import Config
+from swiftpy.core.container import get_container
+from swiftpy.core.context import Context
+from swiftpy.http.middleware import Handler, Middleware
+from swiftpy.http.request import Request
+from swiftpy.http.response import Response, json_response, unauthorized
+
+logger = logging.getLogger("swiftpy.auth.jwt")
+
+
+async def require_jwt(
+    request: Request | None = None,
+    *,
+    issuer: JWTIssuer | None = None,
+    blacklist: TokenBlacklist | None = None,
+    token_type: str = "access",
+) -> dict[str, Any]:
+    """
+    Parse and validate a JWT from the HTTP Authorization header or WebSocket credentials.
+
+    Verifies:
+      1. Presence of Authorization: Bearer <token>, or for WebSockets, Sec-WebSocket-Protocol
+         or URL query parameter ('token' / 'access_token').
+         (Note: query parameter tokens carry log-leak risks as query strings are frequently
+         recorded in server access logs and proxy logs.)
+      2. Valid cryptographic signature (RS256 or HS256)
+      3. Token expiration (exp claim)
+      4. Algorithm authenticity (rejects 'none' or unauthorized algs)
+      5. Expected token type (default 'access')
+      6. Token revocation state in Redis blacklist (jti claim)
+
+    Attaches the authenticated payload to request.state and task Context.
+    """
+    # 1. Resolve request from argument or task Context
+    req = request or Context.get("request")
+    if req is None or not isinstance(req, Request):
+        raise RuntimeError(
+            "No active HTTP Request found. Pass 'request' explicitly or call within request pipeline."
+        )
+
+    # 2. Extract token from Authorization header or WebSocket handshake
+    token: str | None = None
+    raw_auth_headers = [
+        v.decode("latin1")
+        for k, v in req.scope.get("headers", [])
+        if k.lower() == b"authorization"
+    ]
+    if len(raw_auth_headers) > 1:
+        raise AuthenticationError("Multiple Authorization headers provided")
+    if raw_auth_headers:
+        auth_header = raw_auth_headers[0]
+        parts = auth_header.strip().split(" ", 1)
+        if len(parts) != 2 or parts[0].lower() != "bearer":
+            raise AuthenticationError(
+                "Invalid Authorization header format. Expected 'Bearer <token>'"
+            )
+        token = parts[1].strip()
+        if not token:
+            raise AuthenticationError("Bearer token is empty")
+    elif req.scope.get("type") == "websocket":
+        # Check Sec-WebSocket-Protocol (subprotocols)
+        subprotocols = req.scope.get("subprotocols", [])
+        if not subprotocols and "sec-websocket-protocol" in req.headers:
+            subprotocols = [p.strip() for p in req.headers["sec-websocket-protocol"].split(",") if p.strip()]
+
+        for i, proto in enumerate(subprotocols):
+            proto_clean = proto.strip()
+            if proto_clean.lower() in ("bearer", "access_token") and i + 1 < len(subprotocols):
+                token = subprotocols[i + 1].strip()
+                break
+            if proto_clean.lower().startswith("bearer."):
+                token = proto_clean[7:].strip()
+                break
+            if proto_clean.count(".") == 2:
+                token = proto_clean
+                break
+
+        # Check query parameters as fallback (with log-leak warning)
+        if not token:
+            token = req.query_params.get("token") or req.query_params.get("access_token")
+            if token:
+                logger.debug(
+                    "WebSocket authenticated via query parameter token. Note: Query parameter tokens "
+                    "carry log-leak risks as query strings are frequently logged in server and proxy logs."
+                )
+
+        if not token:
+            raise AuthenticationError("Missing Authorization header or WebSocket authentication credentials")
+    else:
+        raise AuthenticationError("Missing Authorization header")
+
+    # 3. Resolve JWTIssuer from parameters, container, or default
+    active_issuer = issuer
+    if active_issuer is None:
+        try:
+            container = get_container()
+            if container.has(JWTIssuer):
+                active_issuer = container.resolve(JWTIssuer)
+            elif container.has(Config):
+                active_issuer = JWTIssuer.from_config(container.resolve(Config))
+        except RuntimeError:
+            pass
+
+    if active_issuer is None:
+        active_issuer = JWTIssuer.from_config()
+
+    # 4. Resolve TokenBlacklist from parameters or container unless disabled in config
+    active_blacklist = blacklist
+    if active_blacklist is None:
+        try:
+            container = get_container()
+            cfg = container.resolve(Config) if container.has(Config) else None
+            if is_token_blacklist_enabled(cfg) and container.has(TokenBlacklist):
+                active_blacklist = container.resolve(TokenBlacklist)
+        except RuntimeError:
+            pass
+
+    # 5. Decode and cryptographically verify token (P2-A4: log detail server-side, return generic 401 message)
+    try:
+        payload = active_issuer.decode_token(
+            token,
+            verify_exp=True,
+            expected_type=token_type,
+        )
+    except (
+        TokenExpiredError,
+        InvalidSignatureError,
+        InvalidAlgorithmError,
+        InvalidTokenError,
+        JWTError,
+    ) as exc:
+        logger.warning("JWT authentication failed: %s", exc)
+        raise AuthenticationError("Invalid or expired token") from exc
+
+    # 6. Check Redis revocation blacklist if jti or subject is present
+    jti = payload.get("jti")
+    if active_blacklist is not None:
+        sub = payload.get("sub")
+        raw_iat = payload.get("iat")
+        iat = int(raw_iat) if isinstance(raw_iat, (int, float)) else None
+        try:
+            try:
+                is_rev = await active_blacklist.is_revoked(
+                    jti or "", subject=sub, issued_at=iat
+                )
+            except TypeError:
+                is_rev = bool(jti and await active_blacklist.is_revoked(jti))
+
+            if is_rev:
+                logger.warning(
+                    "JWT authentication failed: Token has been revoked (jti=%s, sub=%s)",
+                    jti,
+                    sub,
+                )
+                raise TokenRevokedError("Invalid or expired token")
+        except TokenRevokedError:
+            raise
+        except Exception as exc:
+            # If Redis connection fails unexpectedly, log server-side and fail closed with generic 503 (P2-A4)
+            logger.exception(
+                "Authentication service unavailable: Redis blacklist check failed"
+            )
+            raise AuthenticationServiceUnavailableError(
+                "Authentication service unavailable"
+            ) from exc
+
+    # 7. Attach authenticated user payload to request state and task context
+    req.state["user"] = payload
+    req.state["auth_guard"] = "jwt"
+    Context.set("__swiftpy_current_user__", payload)
+
+    return payload
+
+
+class JWTGuard(Middleware):
+    """
+    Middleware adapter for JWT authentication.
+    Applies require_jwt() and handles AuthenticationError (401) or
+    AuthenticationServiceUnavailableError (503).
+    """
+
+    def __init__(
+        self,
+        issuer: JWTIssuer | None = None,
+        blacklist: TokenBlacklist | None = None,
+        token_type: str = "access",
+    ) -> None:
+        self.issuer = issuer
+        self.blacklist = blacklist
+        self.token_type = token_type
+
+    async def authenticate(self, request: Request | None = None) -> dict[str, Any]:
+        """Authenticate the request using this guard's configured JWTIssuer and TokenBlacklist."""
+        return await require_jwt(
+            request,
+            issuer=self.issuer,
+            blacklist=self.blacklist,
+            token_type=self.token_type,
+        )
+
+    async def handle(self, request: Request, next_handler: Handler) -> Response:
+        try:
+            await self.authenticate(request)
+        except AuthenticationError as exc:
+            return unauthorized(exc.message, headers=exc.headers)
+        except AuthenticationServiceUnavailableError as exc:
+            return json_response(
+                {"detail": exc.message},
+                status_code=exc.status_code,
+                headers=exc.headers,
+            )
+
+        return await next_handler(request)