auth0-server-python 1.0.0b1__py3-none-any.whl

auth_types/__init__.py

@@ -0,0 +1,222 @@
+"""
+Type definitions for auth0-server-python SDK.
+These Pydantic models provide type safety and validation for all SDK data structures.
+"""
+
+from typing import Dict, List, Optional, Any, Union
+from pydantic import BaseModel, Field
+from datetime import datetime
+
+
+class UserClaims(BaseModel):
+    """
+    User profile information as returned by Auth0.
+    Contains standard OIDC claims about the authenticated user.
+    """
+    sub: str
+    name: Optional[str] = None
+    nickname: Optional[str] = None
+    given_name: Optional[str] = None
+    family_name: Optional[str] = None
+    picture: Optional[str] = None
+    email: Optional[str] = None
+    email_verified: Optional[bool] = None
+    org_id: Optional[str] = None
+    
+    class Config:
+        extra = "allow"  # Allow additional fields not defined in the model
+
+
+class TokenSet(BaseModel):
+    """
+    Represents a set of tokens issued by Auth0.
+    Contains the access token and related metadata.
+    """
+    audience: str
+    access_token: str
+    scope: Optional[str] = None
+    expires_at: int
+
+
+class ConnectionTokenSet(TokenSet):
+    """
+    Token set specific to a connection.
+    Extends TokenSet with connection-specific information.
+    """
+    connection: str
+    login_hint: str
+
+
+class InternalStateData(BaseModel):
+    """
+    Internal data used for managing state.
+    Not meant to be accessed directly by SDK users.
+    """
+    sid: str
+    created_at: int
+
+
+class SessionData(BaseModel):
+    """
+    Represents a user session with Auth0.
+    Contains user information and tokens.
+    """
+    user: Optional[UserClaims] = None
+    id_token: Optional[str] = None
+    refresh_token: Optional[str] = None
+    token_sets: List[TokenSet] = Field(default_factory=list)
+    connection_token_sets: List[ConnectionTokenSet] = Field(default_factory=list)
+    
+    class Config:
+        extra = "allow"  # Allow additional fields not defined in the model
+
+
+class StateData(SessionData):
+    """
+    Complete state data stored in the state store.
+    Extends SessionData with internal management information.
+    """
+    internal: InternalStateData
+
+
+class TransactionData(BaseModel):
+    """
+    Represents data for an in-progress authentication transaction.
+    Used during the authorization code flow to correlate requests.
+    """
+    audience: Optional[str] = None
+    code_verifier: str
+    app_state: Optional[Any] = None
+    
+    class Config:
+        extra = "allow"  # Allow additional fields not defined in the model
+
+
+class LogoutTokenClaims(BaseModel):
+    """
+    Claims expected in a logout token.
+    Used for backchannel logout processing.
+    """
+    sub: str
+    sid: str
+
+
+class EncryptedStoreOptions(BaseModel):
+    """
+    Options for encrypted stores.
+    Contains the secret used for encryption.
+    """
+    secret: str
+
+
+class ServerClientOptionsBase(BaseModel):
+    """
+    Base options for configuring the Auth0 server client.
+    Contains core settings required for all clients.
+    """
+    domain: str
+    client_id: str
+    client_secret: str
+    client_assertion_signing_key: Optional[str] = None
+    client_assertion_signing_alg: Optional[str] = None
+    authorization_params: Optional[Dict[str, Any]] = Field(default_factory=dict)
+    transaction_identifier: Optional[str] = "_a0_tx"
+    state_identifier: Optional[str] = "_a0_session"
+    custom_fetch: Optional[Any] = None  # Function type hint would be more complex
+
+
+class ServerClientOptionsWithSecret(ServerClientOptionsBase):
+    """
+    Client options using a secret for encryption.
+    Extends base options with secret and duration settings.
+    """
+    secret: str
+    state_absolute_duration: Optional[int] = 259200  # 3 days in seconds
+
+
+class StartInteractiveLoginOptions(BaseModel):
+    """
+    Options for starting the interactive login process.
+    Configures how the authorization request is constructed.
+    """
+    pushed_authorization_requests: Optional[bool] = False
+    app_state: Optional[Any] = None
+    authorization_params: Optional[Dict[str, Any]] = None
+
+
+class LoginBackchannelOptions(BaseModel):
+    """
+    Options for backchannel authentication.
+    Configures how the backchannel authentication request is constructed.
+    """
+    binding_message: Optional[str] = None
+    login_hint: Optional[Dict[str, str]] = None
+    authorization_params: Optional[Dict[str, Any]] = None
+
+
+class LogoutOptions(BaseModel):
+    """
+    Options for logout operations.
+    Configures how the logout request is constructed.
+    """
+    return_to: Optional[str] = None
+
+
+class AuthorizationParameters(BaseModel):
+    """
+    Parameters used in authorization requests.
+    Based on standard OAuth2/OIDC parameters.
+    """
+    scope: Optional[str] = None
+    audience: Optional[str] = None
+    redirect_uri: Optional[str] = None
+    
+    class Config:
+        extra = "allow"  # Allow additional OAuth parameters
+        
+class AuthorizationDetails(BaseModel):
+    """
+    Authorization details returned from Auth0.
+    Used for Resource Access Rights (RAR).
+    """
+    type: str
+    actions: Optional[List[str]] = None
+    locations: Optional[List[str]] = None
+    datatypes: Optional[List[str]] = None
+    identifier: Optional[str] = None
+    
+    class Config:
+        extra = "allow"  # Allow additional fields not defined in the model
+
+
+class LoginBackchannelOptions(BaseModel):
+    """
+    Options for Client-Initiated Backchannel Authentication.
+    """
+    binding_message: str
+    login_hint: Dict[str, str]  # Should contain a 'sub' field
+    authorization_params: Optional[Dict[str, Any]] = None
+    
+    class Config:
+        extra = "allow"  # Allow additional fields not defined in the model
+
+
+class LoginBackchannelResult(BaseModel):
+    """
+    Result from Client-Initiated Backchannel Authentication.
+    """
+    authorization_details: Optional[List[AuthorizationDetails]] = None
+
+
+class AccessTokenForConnectionOptions(BaseModel):
+    """
+    Options for retrieving an access token for a specific connection.
+    """
+    connection: str
+    login_hint: Optional[str] = None
+
+class StartLinkUserOptions(BaseModel):
+    connection: str
+    connection_scope: Optional[str] = None
+    authorization_params: Optional[Dict[str, Any]] = None
+    app_state: Optional[Any] = None

encryption/__init__.py

@@ -0,0 +1,4 @@
+from .encrypt import encrypt, decrypt
+
+
+_all__=["encrypt", "decrypt"]

encryption/encrypt.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+from typing import Any
+
+import json
+from cryptography.hazmat.primitives.kdf.hkdf import HKDF
+from cryptography.hazmat.primitives import hashes
+from jwcrypto import jwk, jwe
+from jwcrypto.common import base64url_encode
+
+# Constants equivalent to the TypeScript version
+ENC = 'A256CBC-HS512'
+ALG = 'dir'
+DIGEST = hashes.SHA256()
+BYTE_LENGTH = 64
+ENCRYPTION_INFO = b'Auth0 Generated ryption'
+
+
+
+def derive_encryption_key(secret: bytes, salt: bytes) -> bytes:
+    """
+    Derives a key using HKDF with SHA-256.
+    """
+    hkdf = HKDF(
+        algorithm=DIGEST,
+        length=BYTE_LENGTH,
+        salt=salt,
+        info=ENCRYPTION_INFO,
+    )
+    return hkdf.derive(secret)
+
+def encrypt(payload: dict, secret: str, salt: str) -> str:
+    """
+    Encrypts the given payload into a JWE using the direct algorithm and A256CBC-HS512 encryption.
+    """
+    # Convert secret and salt to bytes
+    secret_bytes = secret.encode('utf-8')
+    salt_bytes = salt.encode('utf-8')
+        
+    # Derive the encryption key
+    encryption_secret = derive_encryption_key(secret_bytes, salt_bytes)
+        
+    # Create a symmetric key for JWE. jwcrypto expects the key as a base64url-encoded string.
+    key = jwk.JWK(k=base64url_encode(encryption_secret), kty="oct")
+        
+    payload_json = json.dumps(payload)
+        
+    # Create a JWE object with the specified header
+    jwetoken = jwe.JWE(
+        payload_json,
+        protected={'alg': ALG, 'enc': ENC}
+    )
+
+    jwetoken.add_recipient(key)
+    c = jwetoken.serialize(compact=True)
+        
+    # Return the compact serialization of the token
+    return jwetoken.serialize(compact=True)
+
+def decrypt(token: str, secret: str, salt: str) -> dict:
+    """
+    Decrypts the JWE token back to the original payload.
+    """
+    secret_bytes = secret.encode('utf-8')
+    salt_bytes = salt.encode('utf-8')
+        
+    encryption_secret = derive_encryption_key(secret_bytes, salt_bytes)
+    key = jwk.JWK(k=base64url_encode(encryption_secret), kty="oct")
+
+    jwetoken = jwe.JWE()
+    jwetoken.deserialize(token)
+    jwetoken.decrypt(key)
+    payload_json = jwetoken.payload.decode('utf-8')
+    return json.loads(payload_json)

error/__init__.py

@@ -0,0 +1,119 @@
+"""
+Error classes for the auth0-server-python SDK.
+These exceptions provide specific error types for different failure scenarios.
+"""
+
+class Auth0Error(Exception):
+    """Base class for all Auth0 SDK errors."""
+    
+    def __init__(self, message=None):
+        self.message = message
+        super().__init__(message)
+
+
+class MissingTransactionError(Auth0Error):
+    """
+    Error raised when a required transaction is missing.
+    This typically happens during the callback phase when the transaction
+    from the initial authorization request cannot be found.
+    """
+    code = "missing_transaction_error"
+    
+    def __init__(self, message=None):
+        super().__init__(message or "The transaction is missing.")
+        self.name = "MissingTransactionError"
+
+
+class ApiError(Auth0Error):
+    """
+    Error raised when an API request to Auth0 fails.
+    Contains details about the original error from Auth0.
+    """
+    
+    def __init__(self, code: str, message: str, cause=None):
+        super().__init__(message)
+        self.code = code
+        self.cause = cause
+        
+        # Extract additional error details if available
+        if cause:
+            self.error = getattr(cause, "error", None)
+            self.error_description = getattr(cause, "error_description", None)
+        else:
+            self.error = None
+            self.error_description = None
+
+
+class AccessTokenError(Auth0Error):
+    """Error raised when there's an issue with access tokens."""
+    
+    def __init__(self, code: str, message: str):
+        super().__init__(message)
+        self.code = code
+        self.name = "AccessTokenError"
+
+
+class MissingRequiredArgumentError(Auth0Error):
+    """
+    Error raised when a required argument is missing.
+    Includes the name of the missing argument in the error message.
+    """
+    code = "missing_required_argument_error"
+    
+    def __init__(self, argument: str):
+        message = f"The argument '{argument}' is required but was not provided."
+        super().__init__(message)
+        self.name = "MissingRequiredArgumentError"
+        self.argument = argument
+
+
+class BackchannelLogoutError(Auth0Error):
+    """
+    Error raised during backchannel logout processing.
+    This can happen when validating or processing logout tokens.
+    """
+    code = "backchannel_logout_error"
+    
+    def __init__(self, message: str):
+        super().__init__(message)
+        self.name = "BackchannelLogoutError"
+
+
+class AccessTokenForConnectionError(Auth0Error):
+    """Error when retrieving access tokens for a specific connection fails."""
+    
+    def __init__(self, code: str, message: str):
+        super().__init__(message)
+        self.code = code
+        self.name = "AccessTokenForConnectionError"
+
+class StartLinkUserError(Auth0Error):
+    """
+    Error raised when user linking process fails to start.
+    This typically happens when trying to link accounts without 
+    having an authenticated user first.
+    """
+    code = "start_link_user_error"
+    
+    def __init__(self, message: str):
+        super().__init__(message)
+        self.name = "StartLinkUserError"
+
+
+# Error code enumerations - these can be used to identify specific error scenarios
+
+class AccessTokenErrorCode:
+    """Error codes for access token operations."""
+    MISSING_SESSION = "missing_session"
+    MISSING_REFRESH_TOKEN = "missing_refresh_token"
+    FAILED_TO_REFRESH_TOKEN = "failed_to_refresh_token"
+    FAILED_TO_REQUEST_TOKEN = "failed_to_request_token"
+    REFRESH_TOKEN_ERROR = "refresh_token_error"
+
+
+class AccessTokenForConnectionErrorCode:
+    """Error codes for connection-specific token operations."""
+    MISSING_REFRESH_TOKEN = "missing_refresh_token"
+    FAILED_TO_RETRIEVE = "failed_to_retrieve"
+    API_ERROR = "api_error"
+    FETCH_ERROR = "retrieval_error"

store/__init__.py

@@ -0,0 +1,7 @@
+from .abstract import AbstractDataStore, StateStore, TransactionStore
+
+__all__ = [
+    "AbstractDataStore", 
+    "StateStore", 
+    "TransactionStore",
+]

store/abstract.py

@@ -0,0 +1,113 @@
+from abc import ABC, abstractmethod
+from typing import Generic, TypeVar, Optional, Dict, Any
+
+from encryption import encrypt, decrypt
+
+T = TypeVar('T')  # Generic type for the data stored
+
+class AbstractDataStore(Generic[T], ABC):
+    """
+    Abstract base class for data stores.
+    Provides common functionality for different store implementations.
+    """
+    
+    def __init__(self, options: Dict[str, Any]):
+        """
+        Initialize the data store with options.
+        
+        Args:
+            options: Configuration options including encryption secret
+        """
+        self._options = options
+    
+    @abstractmethod
+    async def set(self, identifier: str, state: T, remove_if_expires: bool = False, options: Optional[Dict[str, Any]] = None) -> None:
+        """
+        Store data with the given identifier.
+        
+        Args:
+            identifier: Unique key for the stored data
+            state: Data to store
+            remove_if_expires: Whether to auto-remove expired data
+            options: Additional operation-specific options
+        """
+        pass
+    
+    @abstractmethod
+    async def get(self, identifier: str, options: Optional[Dict[str, Any]] = None) -> Optional[T]:
+        """
+        Retrieve data by identifier.
+        
+        Args:
+            identifier: Unique key for the stored data
+            options: Additional operation-specific options
+            
+        Returns:
+            The stored data or None if not found
+        """
+        pass
+    
+    @abstractmethod
+    async def delete(self, identifier: str, options: Optional[Dict[str, Any]] = None) -> None:
+        """
+        Delete data by identifier.
+        
+        Args:
+            identifier: Unique key for the stored data
+            options: Additional operation-specific options
+        """
+        pass
+    
+    def encrypt(self, identifier: str, state_data: Dict[str, Any]) -> T:
+        """
+        Encrypt data before storing.
+        
+        Args:
+            identifier: Unique key used as part of encryption salt
+            state_data: Data to encrypt
+            
+        Returns:
+            Encrypted string representation of the data
+        """
+        return encrypt(state_data, self._options.get("secret"), identifier)
+    
+    def decrypt(self, identifier: str, encrypted_data: str) -> T:
+        """
+        Decrypt data after retrieval.
+        
+        Args:
+            identifier: Unique key used as part of encryption salt
+            encrypted_data: Encrypted data to decrypt
+            
+        Returns:
+            Decrypted data
+        """
+        return decrypt(encrypted_data, self._options.get("secret"), identifier)
+
+
+class StateStore(AbstractDataStore[Dict[str, Any]]):
+    """
+    Abstract store for persistent session data.
+    Extends AbstractDataStore with logout token functionality.
+    """
+    
+    async def delete_by_logout_token(self, claims: Dict[str, Any], options: Optional[Dict[str, Any]] = None) -> None:
+        """
+        Delete sessions based on logout token claims.
+        
+        Args:
+            claims: Claims from the logout token
+            options: Additional operation-specific options
+            
+        Note:
+            Default implementation throws NotImplementedError.
+            Concrete implementations should override this method.
+        """
+        raise NotImplementedError("Method not implemented.")
+
+
+class TransactionStore(AbstractDataStore[Dict[str, Any]]):
+    """
+    Abstract store for temporary transaction data during auth flows.
+    """
+    pass

utils/__init__.py

@@ -0,0 +1,7 @@
+"""
+Utility functions for auth0-server-python SDK.
+These helpers provide common functionality used across the SDK.
+"""
+from .helpers import PKCE, State, URL
+
+__all__ = ["PKCE", "State", "URL"]