added mechanism for clash safety of between sessions and added readme file

Author: Syed Raza Abbas

README.md

@@ -10,6 +10,118 @@ 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()`.
+
+
+
 ## Publishing
 
 The core team handles publishing.

kinde_sdk/auth/user_session.py

@@ -52,6 +52,19 @@ def set_user_data(self, user_id: str, user_info: Dict[str, Any], token_data: Dic
     #         }
     #         self.storage.set(user_id, serialized_data)
 
+    # def _save_to_storage(self, user_id: str):
+    #     """Save session data to storage."""
+    #     session_data = self.user_sessions.get(user_id)
+    #     if session_data:
+    #         # We need to serialize the session data
+    #         # Token manager can't be directly serialized
+    #         serialized_data = {
+    #             "user_info": session_data["user_info"],
+    #             "tokens": session_data["token_manager"].tokens,
+    #         }
+    #         self.storage_manager.set(user_id, serialized_data)
+
+    
     def _save_to_storage(self, user_id: str):
         """Save session data to storage."""
         session_data = self.user_sessions.get(user_id)
@@ -62,6 +75,8 @@ def _save_to_storage(self, user_id: str):
                 "user_info": session_data["user_info"],
                 "tokens": session_data["token_manager"].tokens,
             }
+            # Store with user: prefix to make it user-specific but device-independent
+            # if you want device-specific sessions, remove the "user:" prefix
             self.storage_manager.set(user_id, serialized_data)
 
     # def _load_from_storage(self, user_id: str) -> bool:
@@ -196,7 +211,8 @@ def logout(self, user_id: str) -> None:
 
             # Delete from storage
             # self.storage.delete(user_id)
-            self.storage_manager.delete(user_id)
+            # self.storage_manager.delete(user_id)
+            self.storage_manager.clear_device_data()
 
     def cleanup_expired_sessions(self) -> None:
         """Remove expired sessions from memory and storage."""

kinde_sdk/core/storage/storage_manager.py

@@ -1,5 +1,7 @@
 # core/storage/storage_manager.py
 import threading
+import uuid
+import time
 from typing import Dict, Any, Optional
 from .storage_factory import StorageFactory
 from .storage_interface import StorageInterface
@@ -22,21 +24,52 @@ def __init__(self):
 
         self._storage = None
         self._initialized = True
+        self._device_id = None
 
-    def initialize(self, config: Dict[str, Any] = None):
+    def initialize(self, config: Dict[str, Any] = None, device_id: Optional[str] = None):
         """
         Initialize the storage with the provided configuration.
         
         Args:
             config (Dict[str, Any], optional): Configuration dictionary for storage.
                 If None, defaults to in-memory storage.
+            device_id (str, optional): A unique identifier for the current device/session.
+                If None, a random identifier will be generated.
         """
         with self._lock:
             if config is None:
                 config = {"type": "memory"}
 
             self._storage = StorageFactory.create_storage(config)
+            # Set or generate device ID
+            if device_id:
+                self._device_id = device_id
+            elif not self._device_id:
+                # Generate a persistent device ID if none provided
+                self._device_id = str(uuid.uuid4())
+                
+            # Store the device ID in storage for persistence
+            self._storage.set("_device_id", {"value": self._device_id, "timestamp": time.time()})
 
+    def get_device_id(self) -> str:
+        """
+        Get the current device ID.
+        
+        Returns:
+            str: The current device ID
+        """
+        if not self._device_id:
+            # Try to load from storage
+            stored_device = self.get("_device_id")
+            if stored_device and "value" in stored_device:
+                self._device_id = stored_device["value"]
+            else:
+                # Generate a new device ID
+                self._device_id = str(uuid.uuid4())
+                self.set("_device_id", {"value": self._device_id, "timestamp": time.time()})
+                
+        return self._device_id
+    
     @property
     def storage(self) -> Optional[StorageInterface]:
         """
@@ -51,6 +84,34 @@ def storage(self) -> Optional[StorageInterface]:
 
         return self._storage
 
+    def _get_namespaced_key(self, key: str) -> str:
+        """
+        Create a namespaced key that includes the device ID to prevent
+        session clashes between same user on different devices.
+        
+        Args:
+            key (str): The original key
+            
+        Returns:
+            str: A namespaced key including device ID
+        """
+        device_id = self.get_device_id()
+        
+        # If the key is for the device ID itself, don't namespace it
+        if key == "_device_id":
+            return key
+            
+        # Special handling for keys that should be global (shared across devices)
+        if key.startswith("global:"):
+            return key
+            
+        # For user-specific but device-independent storage (like OAuth state)
+        if key.startswith("user:"):
+            return key
+            
+        # For device-specific user data (default)
+        return f"device:{device_id}:{key}"
+    
     def get(self, key: str) -> Optional[Dict]:
         """
         Retrieve data from storage by key.
@@ -64,7 +125,8 @@ def get(self, key: str) -> Optional[Dict]:
         if self._storage is None:
             self.initialize()
 
-        return self._storage.get(key)
+        namespaced_key = self._get_namespaced_key(key)
+        return self._storage.get(namespaced_key)
 
     def set(self, key: str, value: Dict) -> None:
         """
@@ -77,7 +139,9 @@ def set(self, key: str, value: Dict) -> None:
         if self._storage is None:
             self.initialize()
 
-        self._storage.set(key, value)
+        namespaced_key = self._get_namespaced_key(key)
+        self._storage.set(namespaced_key, value)
+
 
     def delete(self, key: str) -> None:
         """
@@ -89,4 +153,34 @@ def delete(self, key: str) -> None:
         if self._storage is None:
             self.initialize()
 
-        self._storage.delete(key)
+        namespaced_key = self._get_namespaced_key(key)
+        self._storage.delete(namespaced_key)
+
+    def clear_device_data(self) -> None:
+        """
+        Clear all data associated with the current device.
+        Useful for complete logout/reset scenarios.
+        
+        Note: This is implementation dependent and works best with
+        storage backends that support prefix-based operations.
+        """
+        if self._storage is None:
+            return
+            
+        device_id = self.get_device_id()
+        prefix = f"device:{device_id}:"
+        
+        # This is a naive implementation for storage that doesn't support prefix operations
+        # For more efficient implementations, extend StorageInterface with prefix operations
+        
+        # Note: This implementation works with memory storage as a fallback
+        # but won't be efficient for all storage types
+        if hasattr(self._storage, "clear_prefix"):
+            # If the storage implementation supports prefix clearing
+            self._storage.clear_prefix(prefix)
+        else:
+            # Fallback implementation - less efficient
+            if hasattr(self._storage, "_storage") and isinstance(self._storage._storage, dict):
+                keys_to_delete = [k for k in self._storage._storage.keys() if k.startswith(prefix)]
+                for k in keys_to_delete:
+                    self._storage.delete(k)