Merge pull request #56 from kinde-oss/main_V2_auth_fixes_and_enhancements

Main v2 auth fixes and enhancements

Author: brettchaldecott

.github/workflows/ci.yml

@@ -5,7 +5,7 @@ on:
     branches: [ "main", "staging" ]
 
   push:
-    branches: [ "main", "staging", "main_V2" ]
+    branches: [ "main", "staging", "main_V2", "main_V2_auth_fixes_and_enhancements" ]
 
 concurrency:
   group: ${{ github.head_ref || github.run_id }}
@@ -44,7 +44,7 @@ jobs:
           pip install -r requirements.txt
 
       - name: Run tests
-        run:  pytest --cov-branch --cov-report=xml
+        run:  pytest --cov=kinde_sdk --cov-branch --cov-report=xml
 
       - name: Upload coverage reports to Codecov
         uses: codecov/codecov-action@v5

.gitignore

@@ -241,3 +241,4 @@ Icon
 Network Trash Folder
 Temporary Items
 .apdisk
+.vscode/launch.json

README.md

@@ -10,6 +10,121 @@ You can also use the [Python starter kit here](https://github.com/kinde-starter-
 
 For details on integrating this SDK into your project, head over to the [Kinde docs](https://kinde.com/docs/) and see the [Python SDK](https://kinde.com/docs/developer-tools/python-sdk/) doc 👍🏼.
 
+## Storage Usage Examples
+
+### Basic Usage
+```python
+from kinde_sdk.auth import OAuth
+from kinde_sdk.core.storage import StorageManager
+
+# Basic initialization via OAuth
+# This is the recommended way to initialize the storage system
+# OAuth automatically initializes the StorageManager with the provided config
+oauth = OAuth(
+    client_id="your_client_id",
+    client_secret="your_client_secret",
+    redirect_uri="your_redirect_uri"
+)
+
+# Direct access to the storage manager
+# This is safe to use after OAuth initialization
+storage_manager = StorageManager()
+
+# Store authentication data
+storage_manager.set("user_tokens", {
+    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+    "expires_at": 1678901234
+})
+
+# Retrieve tokens
+tokens = storage_manager.get("user_tokens")
+if tokens:
+    access_token = tokens.get("access_token")
+    # Use the access token for API requests
+    
+# Delete tokens when logging out
+storage_manager.delete("user_tokens")
+```
+
+### Using a Custom Storage Backend
+```python
+oauth = OAuth(
+    client_id="your_client_id",
+    storage_config={
+        "type": "local_storage",
+        "options": {
+            # backend-specific options
+        }
+    }
+)
+```
+
+### Handling Multi-Device Usage
+The StorageManager automatically assigns a unique device ID to each client instance, ensuring that
+the same user logged in on different devices won't experience session clashes. Keys are namespaced
+with the device ID by default.
+
+```python
+# Get the current device ID
+device_id = storage_manager.get_device_id()
+print(f"Current device ID: {device_id}")
+
+# Clear all data for the current device (useful for logout)
+storage_manager.clear_device_data()
+
+# For data that should be shared across all devices for the same user
+# Use the "user:" prefix
+storage_manager.set("user:shared_preferences", {"theme": "dark"})
+
+# For data that should be global across all users and devices
+# Use the "global:" prefix
+storage_manager.set("global:app_settings", {"version": "1.0.0"})
+```
+
+## Best Practices for Storage Management
+
+1. **Always initialize OAuth first**: The OAuth constructor initializes the StorageManager, so create your OAuth instance before accessing the storage.
+
+2. **Manual initialization (if needed)**: If you need to use StorageManager before creating an OAuth instance, explicitly initialize it first:
+```python
+# Manual initialization
+storage_manager = StorageManager()
+storage_manager.initialize({"type": "memory"})  # or your preferred storage config
+
+# You can also provide a specific device ID
+storage_manager.initialize(
+    config={"type": "memory"},
+    device_id="custom-device-identifier"
+)
+
+# Now safe to use
+storage_manager.set("some_key", {"some": "value"})
+```
+
+3. **Safe access pattern**: If you're unsure about initialization status, you can use this pattern:
+```python
+storage_manager = StorageManager()
+if not storage_manager._initialized:
+    storage_manager.initialize()
+    
+# Now safe to use
+data = storage_manager.get("some_key")
+```
+
+4. **Single configuration**: Configure the storage only once at application startup. Changing storage configuration mid-operation may lead to data inconsistency.
+
+5. **Access from anywhere**: After initialization, you can safely access the StorageManager from any part of your application without passing it around.
+
+6. **Device-specific data**: Understand that by default, data is stored with device-specific namespacing. To share data across devices, use the appropriate prefixes.
+
+7. **Complete logout**: To ensure all device-specific data is cleared during logout, call `storage_manager.clear_device_data()`.
+
+
+
+# After initializing both OAuth and KindeApiClient use the following fn to get proper urls
+api_client.fetch_openid_configuration(oauth)
+
 ## Publishing
 
 The core team handles publishing.

kinde_sdk/auth/enums.py

@@ -0,0 +1,20 @@
+from enum import Enum
+
+class GrantType(Enum):
+    """OAuth grant types."""
+    CLIENT_CREDENTIALS = "client_credentials"
+    AUTHORIZATION_CODE = "authorization_code"
+    AUTHORIZATION_CODE_WITH_PKCE = "authorization_code_with_pkce"
+
+class IssuerRouteTypes(Enum):
+    """Types of authentication routes."""
+    LOGIN = "login"
+    REGISTER = "register"
+
+class PromptTypes(Enum):
+    """Authentication prompt types."""
+    CREATE = "create"
+    LOGIN = "login"
+    CONSENT = "consent"
+    SELECT_ACCOUNT = "select_account"
+    NONE = "none"

kinde_sdk/auth/local_storage.py

@@ -0,0 +1,29 @@
+class LoginOptions:
+    """Login options constants for OAuth authentication."""
+    
+    # Standard OAuth parameters
+    RESPONSE_TYPE = "response_type"
+    REDIRECT_URI = "redirect_uri"
+    SCOPE = "scope"
+    AUDIENCE = "audience"
+    STATE = "state"
+    NONCE = "nonce"
+    CODE_CHALLENGE = "code_challenge"
+    CODE_CHALLENGE_METHOD = "code_challenge_method"
+    
+    # Organization parameters
+    ORG_CODE = "org_code"
+    ORG_NAME = "org_name"
+    IS_CREATE_ORG = "is_create_org"
+    
+    # User experience parameters
+    PROMPT = "prompt"
+    LANG = "lang"
+    LOGIN_HINT = "login_hint"
+    CONNECTION_ID = "connection_id"
+    REDIRECT_URL = "redirect_url"
+    HAS_SUCCESS_PAGE = "has_success_page"
+    WORKFLOW_DEPLOYMENT_ID = "workflow_deployment_id"
+    
+    # Additional parameters container
+    AUTH_PARAMS = "auth_params"