lumberfi-authorization 0.1.0__py3-none-any.whl

authorization/__init__.py

@@ -0,0 +1,25 @@
+from .descope_client import init_client, validate_session
+from .authorization import validate_token_optional, validate_token_required
+from .exceptions import (
+    SDKError,
+    ClientNotConfigured,
+    TokenMissing,
+    TokenInvalid,
+    PermissionDenied,
+    NotAuthorized,
+    ValidationError,
+)
+
+__all__ = [
+    "init_client",
+    "validate_session",
+    "validate_token_optional",
+    "validate_token_required",
+    "SDKError",
+    "ClientNotConfigured",
+    "TokenMissing",
+    "TokenInvalid",
+    "PermissionDenied",
+    "NotAuthorized",
+    "ValidationError",
+]

authorization/__version__.py

@@ -0,0 +1,3 @@
+"""Version information for lumberfi-authorization package."""
+
+__version__ = "0.1.0"

authorization/authorization.py

@@ -0,0 +1,73 @@
+import re
+from typing import Tuple, Optional, Protocol, Mapping
+from .descope_client import validate_session
+from .exceptions import NotAuthorized, PermissionDenied, SDKError
+import logging
+AUTHORIZATION_HEADER_NAME = "Authorization"
+BEARER_RE = re.compile(r"^[Bb]earer (.+)$")
+
+
+class RequestLike(Protocol):
+    headers: Mapping[str, str]
+
+
+class TokenValidator:
+    """Token validator that only authorizes tokens by validating with Descope.
+
+    Methods return the validated session dict (from Descope) and the raw token.
+    """
+
+    def parse_bearer(self, request: RequestLike) -> Optional[str]:
+        headers = getattr(request, "headers", {}) or {}
+        if isinstance(headers, dict):
+            auth_header_value = headers.get(AUTHORIZATION_HEADER_NAME) or headers.get(AUTHORIZATION_HEADER_NAME.lower())
+        else:
+            try:
+                auth_header_value = headers.get(AUTHORIZATION_HEADER_NAME)
+            except Exception:
+                auth_header_value = None
+        if not auth_header_value:
+            return None
+        match = BEARER_RE.match(auth_header_value)
+        if not match:
+            return None
+        return match.group(1)
+
+    def validate_optional(self, request: RequestLike) -> Tuple[Optional[dict], Optional[str]]:
+        token = self.parse_bearer(request)
+        if not token:
+            return (None, None)
+        try:
+            session = validate_session(token)
+            return (session, token)
+        except SDKError:
+            # For optional validation, silently return None on any SDK error
+            return (None, None)
+        except Exception as e:
+            # Catch any unexpected errors and return None
+            logging.debug(f"Unexpected error during optional token validation: {e}")
+            return (None, None)
+
+    def validate_required(self, request: RequestLike) -> Tuple[dict, str]:
+        token = self.parse_bearer(request)
+        if not token:
+            raise NotAuthorized(f'Request does not contain "{AUTHORIZATION_HEADER_NAME}" header')
+        try:
+            logging.debug("Validating token with Descope")
+            session = validate_session(token)
+            return (session, token)
+        except SDKError:
+            # Re-raise SDK errors as-is (ClientNotConfigured, etc.)
+            raise
+        except Exception as error:
+            # Wrap unexpected errors in PermissionDenied for invalid tokens
+            raise PermissionDenied(f"Token validation failed: {str(error)}")
+
+
+# Convenience functions
+def validate_token_optional(request: RequestLike) -> Tuple[Optional[dict], Optional[str]]:
+    return TokenValidator().validate_optional(request)
+
+
+def validate_token_required(request: RequestLike) -> Tuple[dict, str]:
+    return TokenValidator().validate_required(request)

authorization/descope_client.py

@@ -0,0 +1,92 @@
+import os
+from typing import Optional, Any
+from .exceptions import ClientNotConfigured, ValidationError
+
+try:
+    from descope import DescopeClient
+except ImportError:
+    DescopeClient = None
+
+# internally stored client instance
+_descope_client: Optional[Any] = None
+
+
+def init_client(
+    project_id: Optional[str] = None,
+    management_key: Optional[str] = None,
+    client: Optional[Any] = None
+) -> Any:
+    """Initialize the descope client for SDK use.
+
+    You can either pass an existing `client` instance or provide `project_id` and
+    `management_key` to construct one. If the Descope SDK isn't installed, attempting
+    to build a client will raise ImportError.
+
+    Args:
+        project_id: Descope project ID. If not provided, will try to use
+                   DESCOPE_PROJECT_ID environment variable.
+        management_key: Descope management key. If not provided, will try to use
+                       DESCOPE_MANAGEMENT_KEY environment variable.
+        client: Optional existing DescopeClient instance to use instead of creating one.
+
+    Returns:
+        The configured DescopeClient instance.
+
+    Raises:
+        ImportError: If descope package is not available and client is not provided.
+        RuntimeError: If project_id and management_key are not provided and client is None.
+    """
+    global _descope_client
+
+    if client is not None:
+        _descope_client = client
+        return _descope_client
+
+    if DescopeClient is None:
+        raise ImportError("descope package is not available. Install it with: pip install descope")
+
+    pid = project_id or os.getenv("DESCOPE_PROJECT_ID")
+    mkey = management_key or os.getenv("DESCOPE_MANAGEMENT_KEY")
+
+    if not pid or not mkey:
+        raise RuntimeError(
+            "project_id and management_key are required to create DescopeClient. "
+            "Either pass them as arguments or set DESCOPE_PROJECT_ID and "
+            "DESCOPE_MANAGEMENT_KEY environment variables."
+        )
+
+    _descope_client = DescopeClient(project_id=pid, management_key=mkey)
+    return _descope_client
+
+
+def validate_session(session_token: str) -> dict:
+    """Validate a session token using the configured Descope client.
+
+    Args:
+        session_token: The session token to validate.
+
+    Returns:
+        The validated session dictionary from Descope.
+
+    Raises:
+        ClientNotConfigured: If the client is not configured. Call init_client(...) first.
+        ValidationError: If token validation fails due to an unexpected error.
+    """
+    global _descope_client
+
+    if _descope_client is None:
+        # Try to auto-initialize from environment variables
+        try:
+            init_client()
+        except (ImportError, RuntimeError):
+            raise ClientNotConfigured(
+                "Descope client not configured. Call init_client(...) to configure the SDK"
+            )
+
+    try:
+        return _descope_client.validate_session(session_token=session_token)
+    except Exception as e:
+        # Wrap Descope client errors in ValidationError for better error handling
+        if isinstance(e, ClientNotConfigured):
+            raise
+        raise ValidationError(f"Token validation failed: {str(e)}") from e

authorization/exceptions.py

@@ -0,0 +1,214 @@
+"""Custom exceptions for the lumberfi-authorization SDK.
+
+These exceptions are framework-agnostic and can be used in any Python environment
+(Django, Flask, FastAPI, etc.). All exceptions inherit from SDKError for easy
+exception handling.
+
+Example:
+    try:
+        session, token = validate_token_required(request)
+    except NotAuthenticated:
+        # Handle missing or malformed token
+        pass
+    except PermissionDenied:
+        # Handle invalid or expired token
+        pass
+    except SDKError:
+        # Catch any SDK-related error
+        pass
+"""
+
+from typing import List, Optional
+
+
+class SDKError(Exception):
+    """Base exception for all SDK-related errors.
+
+    All exceptions in this module inherit from this class, making it easy to
+    catch any SDK-related error with a single except clause.
+
+    Attributes:
+        message: Human-readable error message.
+        error_code: Optional error code for programmatic error handling.
+
+    Example:
+        try:
+            # SDK operations
+            pass
+        except SDKError as e:
+            # Handle any SDK error
+            print(f"SDK Error: {e}")
+    """
+
+    def __init__(self, message: str, error_code: Optional[str] = None):
+        """Initialize SDKError.
+
+        Args:
+            message: Human-readable error message.
+            error_code: Optional error code for programmatic handling.
+        """
+        super().__init__(message)
+        self.message = message
+        self.error_code = error_code
+
+    def __str__(self) -> str:
+        """Return string representation of the error."""
+        if self.error_code:
+            return f"[{self.error_code}] {self.message}"
+        return self.message
+
+
+class ClientNotConfigured(SDKError):
+    """Raised when the Descope client has not been initialized.
+
+    This exception is raised when attempting to validate a token before
+    initializing the SDK with init_client().
+
+    Example:
+        # Without calling init_client() first
+        try:
+            validate_session("token")
+        except ClientNotConfigured:
+            init_client(project_id="...", management_key="...")
+    """
+
+    def __init__(self, message: str = "Descope client not configured. Call init_client(...) to configure the SDK"):
+        """Initialize ClientNotConfigured.
+
+        Args:
+            message: Custom error message. Defaults to a helpful message.
+        """
+        super().__init__(message, error_code="CLIENT_NOT_CONFIGURED")
+
+
+class TokenMissing(SDKError):
+    """Raised when a required token is missing from the request.
+
+    This exception indicates that the Authorization header is completely
+    missing from the request, or the header format is incorrect.
+
+    Example:
+        try:
+            session, token = validate_token_required(request)
+        except TokenMissing:
+            # Request doesn't have Authorization header
+            return {"error": "Authentication required"}, 401
+    """
+
+    def __init__(self, message: str = "Authorization token is missing from the request"):
+        """Initialize TokenMissing.
+
+        Args:
+            message: Custom error message. Defaults to a helpful message.
+        """
+        super().__init__(message, error_code="TOKEN_MISSING")
+
+
+class TokenInvalid(SDKError):
+    """Raised when a token is invalid according to the authorization provider.
+
+    This exception is raised when the token exists but is invalid, expired,
+    or malformed according to Descope's validation.
+
+    Attributes:
+        token: The token that failed validation (if available).
+
+    Example:
+        try:
+            session = validate_session("invalid_token")
+        except TokenInvalid as e:
+            # Token is invalid or expired
+            print(f"Invalid token: {e}")
+    """
+
+    def __init__(self, message: str = "Token is invalid or expired", token: Optional[str] = None):
+        """Initialize TokenInvalid.
+
+        Args:
+            message: Custom error message. Defaults to a helpful message.
+            token: The invalid token (optional, for logging purposes).
+        """
+        super().__init__(message, error_code="TOKEN_INVALID")
+        self.token = token
+
+
+class PermissionDenied(SDKError):
+    """Raised when an operation is not permitted due to authorization failure.
+
+    This exception is raised when token validation fails, indicating that
+    the user does not have permission to access the resource. This can
+    happen due to invalid tokens, expired tokens, or insufficient permissions.
+
+    Example:
+        try:
+            session, token = validate_token_required(request)
+        except PermissionDenied:
+            # Token validation failed
+            return {"error": "Access denied"}, 403
+    """
+
+    def __init__(self, message: str = "Permission denied"):
+        """Initialize PermissionDenied.
+
+        Args:
+            message: Custom error message. Defaults to a helpful message.
+        """
+        super().__init__(message, error_code="PERMISSION_DENIED")
+
+
+class NotAuthorized(SDKError):
+    """Raised when an authentication/authorization token is missing or malformed.
+
+    This exception is raised when the Authorization header is missing,
+    malformed, or doesn't contain a valid Bearer token format.
+
+    Example:
+        try:
+            session, token = validate_token_required(request)
+        except NotAuthorized:
+            # Missing or malformed Authorization header
+            return {"error": "Authentication required"}, 401
+    """
+
+    def __init__(self, message: str = "Authentication required"):
+        """Initialize NotAuthorized.
+
+        Args:
+            message: Custom error message. Defaults to a helpful message.
+        """
+        super().__init__(message, error_code="NOT_AUTHENTICATED")
+
+
+class ValidationError(SDKError):
+    """Raised when token validation fails due to an unexpected error.
+
+    This exception is raised when token validation encounters an unexpected
+    error during the validation process (e.g., network issues, service
+    unavailability).
+
+    Example:
+        try:
+            session = validate_session(token)
+        except ValidationError as e:
+            # Unexpected error during validation
+            logger.error(f"Validation error: {e}")
+    """
+
+    def __init__(self, message: str = "Token validation failed"):
+        """Initialize ValidationError.
+
+        Args:
+            message: Custom error message. Defaults to a helpful message.
+        """
+        super().__init__(message, error_code="VALIDATION_ERROR")
+
+
+__all__: List[str] = [
+    "SDKError",
+    "ClientNotConfigured",
+    "TokenMissing",
+    "TokenInvalid",
+    "PermissionDenied",
+    "NotAuthorized",
+    "ValidationError",
+]

lumberfi_authorization-0.1.0.dist-info/METADATA

@@ -0,0 +1,33 @@
+Metadata-Version: 2.4
+Name: lumberfi-authorization
+Version: 0.1.0
+Summary: SDK for Descope token authorization and validation
+Author: Lumberfi
+Maintainer: Lumberfi
+License: MIT
+Project-URL: Homepage, https://github.com/lumberfi/lumberfi-authorization
+Project-URL: Documentation, https://github.com/lumberfi/lumberfi-authorization#readme
+Project-URL: Repository, https://github.com/lumberfi/lumberfi-authorization
+Project-URL: Issues, https://github.com/lumberfi/lumberfi-authorization/issues
+Keywords: descope,authorization,authentication,sdk,token,validation
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Security
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: descope==1.6.7
+Provides-Extra: dev
+Requires-Dist: pytest==8.3.2; extra == "dev"
+Requires-Dist: pytest-cov==5.0.0; extra == "dev"
+Requires-Dist: black==24.8.0; extra == "dev"
+Requires-Dist: flake8==6.1.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Dynamic: license-file

lumberfi_authorization-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+authorization/__init__.py,sha256=yQUywlR5tI533sP8IbblmFXPuMmXMLGbblzGinnm3J8,570
+authorization/__version__.py,sha256=b1FPckCmbhW1sdf17fwBpMTnxm8zEaMzzZeGmyuJ2ZI,85
+authorization/authorization.py,sha256=d8P7qyFf63-Ae96K_f1BjxBqFVbCfLw7dcn-PPm46Hw,2797
+authorization/descope_client.py,sha256=IrBSePEV8cf6h4CtlFb0WdyEfCCaNVMPEdO1-C0upG0,3203
+authorization/exceptions.py,sha256=wMzieKeksDUFJtMPNR1AiDbXeWyF3arnas1vakfDIOE,6691
+lumberfi_authorization-0.1.0.dist-info/licenses/LICENSE,sha256=4lZHi0OmL4hr3P_9OzgNpDPa0BWArET8vn02ovTBDA4,1065
+lumberfi_authorization-0.1.0.dist-info/METADATA,sha256=sPUjBJflv5yPPfTk11iTjynKEhySBmfdxT8BiIsJ0XY,1436
+lumberfi_authorization-0.1.0.dist-info/WHEEL,sha256=qELbo2s1Yzl39ZmrAibXA2jjPLUYfnVhUNTlyF1rq0Y,92
+lumberfi_authorization-0.1.0.dist-info/top_level.txt,sha256=1Fzfnhfl_A4cLRIexFIl5IfF-Q1AGm-10TmkiQo3f3Y,14
+lumberfi_authorization-0.1.0.dist-info/RECORD,,

lumberfi_authorization-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

lumberfi_authorization-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lumberfi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

lumberfi_authorization-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+authorization