exonware-xwsystem 0.1.0.1__py3-none-any.whl → 0.1.0.4__py3-none-any.whl

exonware/xwsystem/security/crypto.py

@@ -1,8 +1,9 @@
+#exonware/xwsystem/src/exonware/xwsystem/security/crypto.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.1.0.1
+Version: 0.1.0.4
 Generation Date: September 04, 2025
 
 Cryptographic utilities for secure data handling and protection.
@@ -13,7 +14,7 @@ import hmac
 import secrets
 import time
 from base64 import b64decode, b64encode
-from typing import Any, Optional, Union
+from typing import Any, Optional
 
 from cryptography.fernet import Fernet
 from cryptography.hazmat.primitives import hashes, serialization
@@ -31,7 +32,7 @@ class SecureHash:
     """Secure hashing utilities."""
     
     @staticmethod
-    def sha256(data: Union[str, bytes]) -> str:
+    def sha256(data: str | bytes) -> str:
         """
         Compute SHA-256 hash.
 
@@ -46,7 +47,7 @@ class SecureHash:
         return hashlib.sha256(data).hexdigest()
 
     @staticmethod
-    def sha512(data: Union[str, bytes]) -> str:
+    def sha512(data: str | bytes) -> str:
         """
         Compute SHA-512 hash.
 
@@ -61,7 +62,7 @@ class SecureHash:
         return hashlib.sha512(data).hexdigest()
 
     @staticmethod
-    def blake2b(data: Union[str, bytes], key: Optional[bytes] = None) -> str:
+    def blake2b(data: str | bytes, key: Optional[bytes] = None) -> str:
         """
         Compute BLAKE2b hash.
 
@@ -80,7 +81,7 @@ class SecureHash:
             return hashlib.blake2b(data, key=key).hexdigest()
 
     @staticmethod
-    def hmac_sha256(data: Union[str, bytes], key: Union[str, bytes]) -> str:
+    def hmac_sha256(data: str | bytes, key: str | bytes) -> str:
         """
         Compute HMAC-SHA256.
 
@@ -98,7 +99,7 @@ class SecureHash:
         return hmac.new(key, data, hashlib.sha256).hexdigest()
 
     @staticmethod
-    def verify_hmac(data: Union[str, bytes], key: Union[str, bytes], expected_hmac: str) -> bool:
+    def verify_hmac(data: str | bytes, key: str | bytes, expected_hmac: str) -> bool:
         """
         Verify HMAC-SHA256.
 
@@ -231,7 +232,7 @@ class SymmetricEncryption:
         key = b64encode(kdf.derive(password.encode('utf-8')))
         return key, salt
 
-    def encrypt(self, data: Union[str, bytes]) -> bytes:
+    def encrypt(self, data: str | bytes) -> bytes:
         """
         Encrypt data.
 
@@ -337,7 +338,7 @@ class AsymmetricEncryption:
         instance = cls(private_pem, public_pem)
         return instance, private_pem, public_pem
 
-    def encrypt(self, data: Union[str, bytes]) -> bytes:
+    def encrypt(self, data: str | bytes) -> bytes:
         """
         Encrypt data with public key.
 
@@ -384,7 +385,7 @@ class AsymmetricEncryption:
             )
         )
 
-    def sign(self, data: Union[str, bytes]) -> bytes:
+    def sign(self, data: str | bytes) -> bytes:
         """
         Sign data with private key.
 
@@ -409,7 +410,7 @@ class AsymmetricEncryption:
             hashes.SHA256()
         )
 
-    def verify(self, data: Union[str, bytes], signature: bytes) -> bool:
+    def verify(self, data: str | bytes, signature: bytes) -> bool:
         """
         Verify signature with public key.
 
@@ -627,7 +628,7 @@ def _hash_password_pbkdf2(password: str) -> str:
     
     # Generate random salt
     salt = secrets.token_bytes(32)
-    iterations = 100000  # OWASP recommended minimum
+    iterations = 100000  # OWASP minimum
     
     # Derive key using PBKDF2
     kdf = PBKDF2HMAC(
@@ -781,7 +782,7 @@ class AsyncSymmetricEncryption:
         """Get the encryption key."""
         return self._encryption.key
     
-    async def encrypt(self, data: Union[str, bytes]) -> bytes:
+    async def encrypt(self, data: str | bytes) -> bytes:
         """Encrypt data (async)."""
         import asyncio
         return await asyncio.to_thread(self._encryption.encrypt, data)
@@ -819,7 +820,7 @@ class AsyncAsymmetricEncryption:
         async_encryption = cls(private_pem, public_pem)
         return async_encryption, private_pem, public_pem
     
-    async def encrypt(self, data: Union[str, bytes]) -> bytes:
+    async def encrypt(self, data: str | bytes) -> bytes:
         """Encrypt data with public key (async)."""
         import asyncio
         return await asyncio.to_thread(self._encryption.encrypt, data)
@@ -829,12 +830,12 @@ class AsyncAsymmetricEncryption:
         import asyncio
         return await asyncio.to_thread(self._encryption.decrypt, encrypted_data)
     
-    async def sign(self, data: Union[str, bytes]) -> bytes:
+    async def sign(self, data: str | bytes) -> bytes:
         """Sign data with private key (async)."""
         import asyncio
         return await asyncio.to_thread(self._encryption.sign, data)
     
-    async def verify(self, data: Union[str, bytes], signature: bytes) -> bool:
+    async def verify(self, data: str | bytes, signature: bytes) -> bool:
         """Verify signature with public key (async)."""
         import asyncio
         return await asyncio.to_thread(self._encryption.verify, data, signature)

exonware/xwsystem/security/defs.py

@@ -1,10 +1,11 @@
 #!/usr/bin/env python3
+#exonware/xwsystem/src/exonware/xwsystem/security/defs.py
 #exonware/xwsystem/security/types.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.1.0.1
+Version: 0.1.0.4
 Generation Date: 07-Sep-2025
 
 Security types and enums for XWSystem.

exonware/xwsystem/security/errors.py

@@ -1,9 +1,10 @@
+#exonware/xwsystem/src/exonware/xwsystem/security/errors.py
 #exonware/xwsystem/security/errors.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.1.0.1
+Version: 0.1.0.4
 Generation Date: September 04, 2025
 
 Security module errors - exception classes for security functionality.

exonware/xwsystem/security/facade.py

@@ -0,0 +1,321 @@
+#exonware/xwsystem/src/exonware/xwsystem/security/facade.py
+"""
+Company: eXonware.com
+Author: Eng. Muhammad AlShehri
+Email: connect@exonware.com
+Version: 0.1.0.4
+Generation Date: January 2026
+
+XWSecurity & XWCrypto - Unified Security Facades
+
+Simplified API for security operations:
+- Hashing (SHA-256, SHA-512, BLAKE2b, HMAC)
+- Password hashing and verification
+- Encryption (Symmetric, Asymmetric)
+- Secure storage
+- Path validation
+"""
+
+from typing import Any, Optional, Tuple
+
+from .crypto import (
+    SecureHash,
+    SecureRandom,
+    SymmetricEncryption,
+    AsymmetricEncryption,
+    SecureStorage,
+    AsyncSecureStorage,
+    AsyncSymmetricEncryption,
+    AsyncAsymmetricEncryption,
+    hash_password,
+    verify_password,
+    generate_api_key,
+    generate_session_token,
+)
+from .path_validator import PathValidator, PathSecurityError
+from ..config.logging_setup import get_logger
+
+logger = get_logger(__name__)
+
+
+class XWSecurity:
+    """
+    Unified security facade - simple API for security operations.
+    
+    Examples:
+        >>> # Hashing
+        >>> hash_value = XWSecurity.hash("password", algorithm="sha256")
+        >>> is_valid = XWSecurity.verify_hash("password", hash_value)
+        
+        >>> # Password hashing
+        >>> hashed = XWSecurity.hash_password("mypassword")
+        >>> XWSecurity.verify_password("mypassword", hashed)
+        
+        >>> # Path validation
+        >>> XWSecurity.validate_path("/safe/dir/file.txt", base_path="/safe")
+        
+        >>> # Secure storage
+        >>> storage = XWSecurity.Storage()
+        >>> storage.set("api_key", "sk_...")
+        >>> value = storage.get("api_key")
+    """
+    
+    @staticmethod
+    def hash(data: str | bytes, algorithm: str = "sha256") -> str:
+        """
+        Hash data with specified algorithm.
+        
+        Args:
+            data: Data to hash
+            algorithm: Hash algorithm ("sha256", "sha512", "blake2b", "hmac_sha256")
+            
+        Returns:
+            Hex digest string
+        """
+        if algorithm == "sha256":
+            return SecureHash.sha256(data)
+        elif algorithm == "sha512":
+            return SecureHash.sha512(data)
+        elif algorithm == "blake2b":
+            return SecureHash.blake2b(data)
+        else:
+            raise ValueError(f"Unknown algorithm: {algorithm}")
+    
+    @staticmethod
+    def verify_hash(data: str | bytes, hash_value: str, algorithm: str = "sha256") -> bool:
+        """
+        Verify hash matches data.
+        
+        Args:
+            data: Original data
+            hash_value: Hash to verify against
+            algorithm: Hash algorithm used
+            
+        Returns:
+            True if hash matches
+        """
+        computed = XWSecurity.hash(data, algorithm)
+        return computed == hash_value
+    
+    @staticmethod
+    def hash_password(password: str, rounds: int = 12) -> str:
+        """
+        Hash password securely.
+        
+        Args:
+            password: Password to hash
+            rounds: Bcrypt rounds (default: 12)
+            
+        Returns:
+            Hashed password string
+        """
+        return hash_password(password, rounds)
+    
+    @staticmethod
+    def verify_password(password: str, hashed_password: str) -> bool:
+        """
+        Verify password against hash.
+        
+        Args:
+            password: Plain password
+            hashed_password: Hashed password
+            
+        Returns:
+            True if password matches
+        """
+        return verify_password(password, hashed_password)
+    
+    @staticmethod
+    def validate_path(path: str, base_path: Optional[str] = None) -> str:
+        """
+        Validate and sanitize file path.
+        
+        Args:
+            path: Path to validate
+            base_path: Base directory (prevents directory traversal)
+            
+        Returns:
+            Validated path
+            
+        Raises:
+            PathSecurityError: If path is invalid
+        """
+        validator = PathValidator(base_path) if base_path else PathValidator()
+        return validator.validate_path(path)
+    
+    @staticmethod
+    def generate_api_key(length: int = 32) -> str:
+        """Generate cryptographically secure API key."""
+        return generate_api_key(length)
+    
+    @staticmethod
+    def generate_session_token(length: int = 32) -> str:
+        """Generate cryptographically secure session token."""
+        return generate_session_token(length)
+    
+    class Storage:
+        """Secure encrypted key-value storage."""
+        
+        def __init__(self, password: Optional[str] = None):
+            """
+            Initialize secure storage.
+            
+            Args:
+                password: Optional password for encryption (auto-generated if None)
+            """
+            self._storage = SecureStorage() if password is None else SecureStorage.from_password(password)
+        
+        def set(self, key: str, value: Any) -> None:
+            """Store encrypted value."""
+            self._storage.store(key, value)
+        
+        def get(self, key: str) -> Any:
+            """Retrieve and decrypt value."""
+            return self._storage.retrieve(key)
+        
+        def delete(self, key: str) -> bool:
+            """Delete stored value."""
+            return self._storage.delete(key)
+
+
+class XWCrypto:
+    """
+    Unified cryptography facade - simple API for encryption operations.
+    
+    Examples:
+        >>> # Symmetric encryption
+        >>> crypto = XWCrypto()  # Auto-generates key
+        >>> encrypted = crypto.encrypt("secret data")
+        >>> decrypted = crypto.decrypt(encrypted)
+        
+        >>> # Password-based encryption
+        >>> crypto = XWCrypto.from_password("mypassword")
+        >>> encrypted = crypto.encrypt("data")
+        
+        >>> # Asymmetric encryption
+        >>> public, private = XWCrypto.generate_key_pair()
+        >>> encrypted = XWCrypto.encrypt("data", public_key=public)
+        >>> decrypted = XWCrypto.decrypt(encrypted, private_key=private)
+    """
+    
+    def __init__(self, key: Optional[bytes] = None):
+        """
+        Initialize crypto with key.
+        
+        Args:
+            key: Optional encryption key (auto-generated if None)
+        """
+        if key is None:
+            self._crypto = SymmetricEncryption()
+            self._key = self._crypto.key
+        else:
+            self._crypto = SymmetricEncryption(key)
+            self._key = key
+    
+    @classmethod
+    def from_password(cls, password: str) -> "XWCrypto":
+        """
+        Create crypto instance from password.
+        
+        Args:
+            password: Password for key derivation
+            
+        Returns:
+            XWCrypto instance
+        """
+        instance = cls.__new__(cls)
+        # Derive key from password
+        key, _ = SymmetricEncryption.derive_key_from_password(password)
+        instance._crypto = SymmetricEncryption(key)
+        instance._key = key
+        return instance
+    
+    def encrypt(self, data: str | bytes) -> bytes:
+        """Encrypt data using instance's crypto."""
+        return self._crypto.encrypt(data)
+    
+    def decrypt(self, encrypted_data: bytes) -> str | bytes:
+        """Decrypt data using instance's crypto."""
+        return self._crypto.decrypt(encrypted_data)
+    
+    @property
+    def key(self) -> bytes:
+        """Get encryption key."""
+        return self._key
+    
+    @staticmethod
+    def encrypt_static(data: str | bytes, password: Optional[str] = None, public_key: Optional[bytes] = None, key: Optional[bytes] = None) -> bytes:
+        """
+        Static method to encrypt data.
+        
+        Args:
+            data: Data to encrypt
+            password: Password for symmetric encryption (key derivation)
+            public_key: Public key for asymmetric encryption
+            key: Direct encryption key (for symmetric)
+            
+        Returns:
+            Encrypted data
+        """
+        if public_key:
+            crypto = AsymmetricEncryption(public_key=public_key)
+            return crypto.encrypt(data)
+        elif password:
+            # Use deterministic salt based on password for consistent encryption/decryption
+            # Note: This is less secure than random salt but allows same password to work
+            import hashlib
+            salt = hashlib.sha256(password.encode()).digest()[:16]  # Deterministic salt
+            key, _ = SymmetricEncryption.derive_key_from_password(password, salt=salt)
+            crypto = SymmetricEncryption(key)
+            return crypto.encrypt(data)
+        elif key:
+            crypto = SymmetricEncryption(key)
+            return crypto.encrypt(data)
+        else:
+            # Auto-generate key for one-time encryption
+            crypto = SymmetricEncryption()
+            return crypto.encrypt(data)
+    
+    @staticmethod  
+    def decrypt_static(encrypted_data: bytes, password: Optional[str] = None, private_key: Optional[bytes] = None, key: Optional[bytes] = None) -> bytes:
+        """
+        Static method to decrypt data.
+        
+        Args:
+            encrypted_data: Encrypted data
+            password: Password for symmetric decryption (key derivation)
+            private_key: Private key for asymmetric decryption
+            key: Direct decryption key (for symmetric)
+            
+        Returns:
+            Decrypted data
+        """
+        if private_key:
+            crypto = AsymmetricEncryption(private_key=private_key)
+            return crypto.decrypt(encrypted_data)
+        elif password:
+            # Use same deterministic salt for decryption
+            import hashlib
+            salt = hashlib.sha256(password.encode()).digest()[:16]  # Deterministic salt
+            key, _ = SymmetricEncryption.derive_key_from_password(password, salt=salt)
+            crypto = SymmetricEncryption(key)
+            return crypto.decrypt(encrypted_data)
+        elif key:
+            crypto = SymmetricEncryption(key)
+            return crypto.decrypt(encrypted_data)
+        else:
+            raise ValueError("Either password, key, or private_key must be provided")
+    
+    @staticmethod
+    def generate_key_pair(key_size: int = 2048) -> Tuple[bytes, bytes]:
+        """
+        Generate RSA key pair.
+        
+        Args:
+            key_size: Key size in bits (default: 2048)
+            
+        Returns:
+            Tuple of (public_key, private_key)
+        """
+        crypto = AsymmetricEncryption.generate_key_pair(key_size)
+        return crypto.public_key, crypto.private_key