lumberfi-authorization 0.1.0__tar.gz

lumberfi_authorization-0.1.0/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/MANIFEST.in

@@ -0,0 +1,7 @@
+include README.md
+include LICENSE
+include pyproject.toml
+recursive-include authorization *.py
+recursive-include authorization *.pyi
+global-exclude __pycache__
+global-exclude *.py[co]

lumberfi_authorization-0.1.0/PKG-INFO

@@ -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/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",
+]

lumberfi_authorization-0.1.0/authorization/__version__.py

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

lumberfi_authorization-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)

lumberfi_authorization-0.1.0/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

lumberfi_authorization-0.1.0/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/lumberfi_authorization.egg-info/PKG-INFO

@@ -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/lumberfi_authorization.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+MANIFEST.in
+pyproject.toml
+authorization/__init__.py
+authorization/__version__.py
+authorization/authorization.py
+authorization/descope_client.py
+authorization/exceptions.py
+lumberfi_authorization.egg-info/PKG-INFO
+lumberfi_authorization.egg-info/SOURCES.txt
+lumberfi_authorization.egg-info/dependency_links.txt
+lumberfi_authorization.egg-info/requires.txt
+lumberfi_authorization.egg-info/top_level.txt

lumberfi_authorization-0.1.0/lumberfi_authorization.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

lumberfi_authorization-0.1.0/lumberfi_authorization.egg-info/requires.txt

@@ -0,0 +1,8 @@
+descope==1.6.7
+
+[dev]
+pytest==8.3.2
+pytest-cov==5.0.0
+black==24.8.0
+flake8==6.1.0
+mypy>=1.0.0

lumberfi_authorization-0.1.0/lumberfi_authorization.egg-info/top_level.txt

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

lumberfi_authorization-0.1.0/pyproject.toml

@@ -0,0 +1,74 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "lumberfi-authorization"
+dynamic = ["version"]
+description = "SDK for Descope token authorization and validation"
+readme = "README.md"
+requires-python = ">=3.9"
+license = {text = "MIT"}
+authors = [
+    {name = "Lumberfi"}
+]
+maintainers = [
+    {name = "Lumberfi"}
+]
+keywords = ["descope", "authorization", "authentication", "sdk", "token", "validation"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Security",
+]
+
+dependencies = [
+    "descope==1.6.7",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest==8.3.2",
+    "pytest-cov==5.0.0",
+    "black==24.8.0",
+    "flake8==6.1.0",
+    "mypy>=1.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/lumberfi/lumberfi-authorization"
+Documentation = "https://github.com/lumberfi/lumberfi-authorization#readme"
+Repository = "https://github.com/lumberfi/lumberfi-authorization"
+Issues = "https://github.com/lumberfi/lumberfi-authorization/issues"
+
+[tool.setuptools]
+packages = ["authorization"]
+
+[tool.setuptools.dynamic]
+version = {attr = "authorization.__version__.__version__"}
+
+[tool.setuptools.package-data]
+authorization = ["py.typed"]
+
+[tool.black]
+line-length = 100
+target-version = ['py39']
+
+[tool.mypy]
+python_version = "3.9"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = false
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]

lumberfi_authorization-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+