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

exonware/xwsystem/security/contracts.py

@@ -1,17 +1,16 @@
 #!/usr/bin/env python3
+#exonware/xwsystem/src/exonware/xwsystem/security/contracts.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 protocol interfaces for XWSystem.
 """
 
-from abc import ABC, abstractmethod
-from typing import Any, Optional, Union, Iterator, Callable, Protocol
-from typing_extensions import runtime_checkable
+from typing import Any, Optional, Iterator, Callable, Protocol, runtime_checkable
 import hashlib
 
 # Import enums from types module
@@ -29,15 +28,15 @@ from .defs import (
 # SECURITY INTERFACES
 # ============================================================================
 
-class ISecure(ABC):
+@runtime_checkable
+class ISecure(Protocol):
     """
     Interface for secure objects.
     
     Enforces consistent security behavior across XWSystem.
     """
     
-    @abstractmethod
-    def encrypt(self, data: Union[str, bytes], algorithm: EncryptionAlgorithm = EncryptionAlgorithm.AES_256) -> Union[str, bytes]:
+    def encrypt(self, data: str | bytes, algorithm: EncryptionAlgorithm = EncryptionAlgorithm.AES_256) -> str | bytes:
         """
         Encrypt data.
         
@@ -48,10 +47,9 @@ class ISecure(ABC):
         Returns:
             Encrypted data
         """
-        pass
+        ...
     
-    @abstractmethod
-    def decrypt(self, encrypted_data: Union[str, bytes], algorithm: EncryptionAlgorithm = EncryptionAlgorithm.AES_256) -> Union[str, bytes]:
+    def decrypt(self, encrypted_data: str | bytes, algorithm: EncryptionAlgorithm = EncryptionAlgorithm.AES_256) -> str | bytes:
         """
         Decrypt data.
         
@@ -62,10 +60,9 @@ class ISecure(ABC):
         Returns:
             Decrypted data
         """
-        pass
+        ...
     
-    @abstractmethod
-    def hash(self, data: Union[str, bytes], algorithm: HashAlgorithm = HashAlgorithm.SHA256) -> str:
+    def hash(self, data: str | bytes, algorithm: HashAlgorithm = HashAlgorithm.SHA256) -> str:
         """
         Hash data.
         
@@ -76,10 +73,9 @@ class ISecure(ABC):
         Returns:
             Hash string
         """
-        pass
+        ...
     
-    @abstractmethod
-    def verify_hash(self, data: Union[str, bytes], hash_value: str, algorithm: HashAlgorithm = HashAlgorithm.SHA256) -> bool:
+    def verify_hash(self, data: str | bytes, hash_value: str, algorithm: HashAlgorithm = HashAlgorithm.SHA256) -> bool:
         """
         Verify data against hash.
         
@@ -91,9 +87,8 @@ class ISecure(ABC):
         Returns:
             True if hash matches
         """
-        pass
+        ...
     
-    @abstractmethod
     def generate_key(self, algorithm: EncryptionAlgorithm = EncryptionAlgorithm.AES_256) -> bytes:
         """
         Generate encryption key.
@@ -104,9 +99,8 @@ class ISecure(ABC):
         Returns:
             Generated key
         """
-        pass
+        ...
     
-    @abstractmethod
     def generate_salt(self, length: int = 32) -> bytes:
         """
         Generate random salt.
@@ -117,9 +111,8 @@ class ISecure(ABC):
         Returns:
             Generated salt
         """
-        pass
+        ...
     
-    @abstractmethod
     def secure_random(self, length: int) -> bytes:
         """
         Generate secure random bytes.
@@ -130,21 +123,21 @@ class ISecure(ABC):
         Returns:
             Random bytes
         """
-        pass
+        ...
 
 
 # ============================================================================
 # AUTHENTICATION INTERFACES
 # ============================================================================
 
-class IAuthenticatable(ABC):
+@runtime_checkable
+class IAuthenticatable(Protocol):
     """
     Interface for authentication.
     
     Enforces consistent authentication behavior across XWSystem.
     """
     
-    @abstractmethod
     def authenticate(self, credentials: dict[str, Any]) -> bool:
         """
         Authenticate user with credentials.
@@ -155,9 +148,8 @@ class IAuthenticatable(ABC):
         Returns:
             True if authenticated
         """
-        pass
+        ...
     
-    @abstractmethod
     def authorize(self, user: str, resource: str, action: str) -> bool:
         """
         Authorize user for resource action.
@@ -170,9 +162,8 @@ class IAuthenticatable(ABC):
         Returns:
             True if authorized
         """
-        pass
+        ...
     
-    @abstractmethod
     def logout(self, user: str) -> bool:
         """
         Logout user.
@@ -183,9 +174,8 @@ class IAuthenticatable(ABC):
         Returns:
             True if logged out
         """
-        pass
+        ...
     
-    @abstractmethod
     def is_authenticated(self, user: str) -> bool:
         """
         Check if user is authenticated.
@@ -196,9 +186,8 @@ class IAuthenticatable(ABC):
         Returns:
             True if authenticated
         """
-        pass
+        ...
     
-    @abstractmethod
     def get_user_permissions(self, user: str) -> list[str]:
         """
         Get user permissions.
@@ -209,9 +198,8 @@ class IAuthenticatable(ABC):
         Returns:
             List of permissions
         """
-        pass
+        ...
     
-    @abstractmethod
     def set_user_permissions(self, user: str, permissions: list[str]) -> None:
         """
         Set user permissions.
@@ -220,9 +208,8 @@ class IAuthenticatable(ABC):
             user: User identifier
             permissions: List of permissions
         """
-        pass
+        ...
     
-    @abstractmethod
     def validate_credentials(self, credentials: dict[str, Any]) -> bool:
         """
         Validate credential format.
@@ -233,9 +220,8 @@ class IAuthenticatable(ABC):
         Returns:
             True if valid format
         """
-        pass
+        ...
     
-    @abstractmethod
     def get_authentication_method(self) -> AuthenticationMethod:
         """
         Get authentication method.
@@ -243,21 +229,21 @@ class IAuthenticatable(ABC):
         Returns:
             Authentication method
         """
-        pass
+        ...
 
 
 # ============================================================================
 # AUDIT INTERFACES
 # ============================================================================
 
-class IAuditable(ABC):
+@runtime_checkable
+class IAuditable(Protocol):
     """
     Interface for audit trails.
     
     Enforces consistent audit behavior across XWSystem.
     """
     
-    @abstractmethod
     def log_action(self, action: AuditEvent, user: str, resource: str, details: dict[str, Any] = None) -> None:
         """
         Log audit action.
@@ -268,9 +254,8 @@ class IAuditable(ABC):
             resource: Resource identifier
             details: Additional details
         """
-        pass
+        ...
     
-    @abstractmethod
     def get_audit_trail(self, user: Optional[str] = None, resource: Optional[str] = None, 
                        start_time: Optional[float] = None, end_time: Optional[float] = None) -> list[dict[str, Any]]:
         """
@@ -285,9 +270,8 @@ class IAuditable(ABC):
         Returns:
             List of audit entries
         """
-        pass
+        ...
     
-    @abstractmethod
     def clear_audit_trail(self, older_than: Optional[float] = None) -> int:
         """
         Clear audit trail.
@@ -298,9 +282,8 @@ class IAuditable(ABC):
         Returns:
             Number of entries cleared
         """
-        pass
+        ...
     
-    @abstractmethod
     def export_audit_trail(self, file_path: str, format: str = "json") -> bool:
         """
         Export audit trail to file.
@@ -312,9 +295,8 @@ class IAuditable(ABC):
         Returns:
             True if exported successfully
         """
-        pass
+        ...
     
-    @abstractmethod
     def get_audit_stats(self) -> dict[str, Any]:
         """
         Get audit statistics.
@@ -322,9 +304,8 @@ class IAuditable(ABC):
         Returns:
             Audit statistics dictionary
         """
-        pass
+        ...
     
-    @abstractmethod
     def is_audit_enabled(self) -> bool:
         """
         Check if auditing is enabled.
@@ -332,35 +313,33 @@ class IAuditable(ABC):
         Returns:
             True if enabled
         """
-        pass
+        ...
     
-    @abstractmethod
     def enable_audit(self) -> None:
         """
         Enable auditing.
         """
-        pass
+        ...
     
-    @abstractmethod
     def disable_audit(self) -> None:
         """
         Disable auditing.
         """
-        pass
+        ...
 
 
 # ============================================================================
 # AUTHORIZATION INTERFACES
 # ============================================================================
 
-class IAuthorization(ABC):
+@runtime_checkable
+class IAuthorization(Protocol):
     """
     Interface for authorization.
     
     Enforces consistent authorization behavior across XWSystem.
     """
     
-    @abstractmethod
     def check_permission(self, user: str, resource: str, action: str) -> bool:
         """
         Check user permission for resource action.
@@ -373,9 +352,8 @@ class IAuthorization(ABC):
         Returns:
             True if permitted
         """
-        pass
+        ...
     
-    @abstractmethod
     def grant_permission(self, user: str, resource: str, action: str) -> bool:
         """
         Grant permission to user.
@@ -388,9 +366,8 @@ class IAuthorization(ABC):
         Returns:
             True if granted
         """
-        pass
+        ...
     
-    @abstractmethod
     def revoke_permission(self, user: str, resource: str, action: str) -> bool:
         """
         Revoke permission from user.
@@ -403,9 +380,8 @@ class IAuthorization(ABC):
         Returns:
             True if revoked
         """
-        pass
+        ...
     
-    @abstractmethod
     def get_user_roles(self, user: str) -> list[str]:
         """
         Get user roles.
@@ -416,9 +392,8 @@ class IAuthorization(ABC):
         Returns:
             List of role names
         """
-        pass
+        ...
     
-    @abstractmethod
     def assign_role(self, user: str, role: str) -> bool:
         """
         Assign role to user.
@@ -430,9 +405,8 @@ class IAuthorization(ABC):
         Returns:
             True if assigned
         """
-        pass
+        ...
     
-    @abstractmethod
     def remove_role(self, user: str, role: str) -> bool:
         """
         Remove role from user.
@@ -444,9 +418,8 @@ class IAuthorization(ABC):
         Returns:
             True if removed
         """
-        pass
+        ...
     
-    @abstractmethod
     def get_role_permissions(self, role: str) -> list[str]:
         """
         Get role permissions.
@@ -457,9 +430,8 @@ class IAuthorization(ABC):
         Returns:
             List of permissions
         """
-        pass
+        ...
     
-    @abstractmethod
     def set_role_permissions(self, role: str, permissions: list[str]) -> None:
         """
         Set role permissions.
@@ -468,34 +440,33 @@ class IAuthorization(ABC):
             role: Role name
             permissions: List of permissions
         """
-        pass
+        ...
 
 
 # ============================================================================
 # SECURITY VALIDATION INTERFACES
 # ============================================================================
 
-class ISecurityValidator(ABC):
+@runtime_checkable
+class ISecurityValidator(Protocol):
     """
     Interface for security validation.
     
     Enforces consistent security validation across XWSystem.
     """
     
-    @abstractmethod
     def validate_password(self, password: str) -> tuple[bool, list[str]]:
         """
         Validate password strength.
         
         Args:
-            password: Password to validate
+            ...word: Password to validate
             
         Returns:
             Tuple of (is_valid, error_messages)
         """
-        pass
+        ...
     
-    @abstractmethod
     def validate_input(self, input_data: str, input_type: str) -> tuple[bool, list[str]]:
         """
         Validate input data.
@@ -507,9 +478,8 @@ class ISecurityValidator(ABC):
         Returns:
             Tuple of (is_valid, error_messages)
         """
-        pass
+        ...
     
-    @abstractmethod
     def sanitize_input(self, input_data: str) -> str:
         """
         Sanitize input data.
@@ -520,9 +490,8 @@ class ISecurityValidator(ABC):
         Returns:
             Sanitized data
         """
-        pass
+        ...
     
-    @abstractmethod
     def detect_sql_injection(self, input_data: str) -> bool:
         """
         Detect SQL injection attempts.
@@ -533,9 +502,8 @@ class ISecurityValidator(ABC):
         Returns:
             True if SQL injection detected
         """
-        pass
+        ...
     
-    @abstractmethod
     def detect_xss(self, input_data: str) -> bool:
         """
         Detect XSS attempts.
@@ -546,9 +514,8 @@ class ISecurityValidator(ABC):
         Returns:
             True if XSS detected
         """
-        pass
+        ...
     
-    @abstractmethod
     def validate_certificate(self, certificate: bytes) -> tuple[bool, str]:
         """
         Validate certificate.
@@ -559,9 +526,8 @@ class ISecurityValidator(ABC):
         Returns:
             Tuple of (is_valid, error_message)
         """
-        pass
+        ...
     
-    @abstractmethod
     def check_security_headers(self, headers: dict[str, str]) -> dict[str, bool]:
         """
         Check security headers.
@@ -572,21 +538,21 @@ class ISecurityValidator(ABC):
         Returns:
             Dictionary of header validation results
         """
-        pass
+        ...
 
 
 # ============================================================================
 # SECURITY MONITORING INTERFACES
 # ============================================================================
 
-class ISecurityMonitor(ABC):
+@runtime_checkable
+class ISecurityMonitor(Protocol):
     """
     Interface for security monitoring.
     
     Enforces consistent security monitoring across XWSystem.
     """
     
-    @abstractmethod
     def detect_intrusion(self, event_data: dict[str, Any]) -> bool:
         """
         Detect intrusion attempts.
@@ -597,9 +563,8 @@ class ISecurityMonitor(ABC):
         Returns:
             True if intrusion detected
         """
-        pass
+        ...
     
-    @abstractmethod
     def monitor_failed_logins(self, user: str, max_attempts: int = 5) -> bool:
         """
         Monitor failed login attempts.
@@ -611,9 +576,8 @@ class ISecurityMonitor(ABC):
         Returns:
             True if threshold exceeded
         """
-        pass
+        ...
     
-    @abstractmethod
     def detect_anomaly(self, behavior_data: dict[str, Any]) -> bool:
         """
         Detect anomalous behavior.
@@ -624,9 +588,8 @@ class ISecurityMonitor(ABC):
         Returns:
             True if anomaly detected
         """
-        pass
+        ...
     
-    @abstractmethod
     def get_security_alerts(self) -> list[dict[str, Any]]:
         """
         Get security alerts.
@@ -634,16 +597,14 @@ class ISecurityMonitor(ABC):
         Returns:
             List of security alerts
         """
-        pass
+        ...
     
-    @abstractmethod
     def clear_security_alerts(self) -> None:
         """
         Clear security alerts.
         """
-        pass
+        ...
     
-    @abstractmethod
     def get_threat_level(self) -> SecurityLevel:
         """
         Get current threat level.
@@ -651,9 +612,8 @@ class ISecurityMonitor(ABC):
         Returns:
             Current threat level
         """
-        pass
+        ...
     
-    @abstractmethod
     def set_threat_level(self, level: SecurityLevel) -> None:
         """
         Set threat level.
@@ -661,9 +621,8 @@ class ISecurityMonitor(ABC):
         Args:
             level: Threat level to set
         """
-        pass
+        ...
     
-    @abstractmethod
     def get_security_metrics(self) -> dict[str, Any]:
         """
         Get security metrics.
@@ -671,21 +630,21 @@ class ISecurityMonitor(ABC):
         Returns:
             Security metrics dictionary
         """
-        pass
+        ...
 
 
 # ============================================================================
 # SECURITY POLICY INTERFACES
 # ============================================================================
 
-class ISecurityPolicy(ABC):
+@runtime_checkable
+class ISecurityPolicy(Protocol):
     """
     Interface for security policies.
     
     Enforces consistent security policy behavior across XWSystem.
     """
     
-    @abstractmethod
     def get_policy(self, policy_name: str) -> dict[str, Any]:
         """
         Get security policy.
@@ -696,9 +655,8 @@ class ISecurityPolicy(ABC):
         Returns:
             Policy dictionary
         """
-        pass
+        ...
     
-    @abstractmethod
     def set_policy(self, policy_name: str, policy: dict[str, Any]) -> None:
         """
         Set security policy.
@@ -707,9 +665,8 @@ class ISecurityPolicy(ABC):
             policy_name: Policy name
             policy: Policy dictionary
         """
-        pass
+        ...
     
-    @abstractmethod
     def validate_policy(self, policy: dict[str, Any]) -> tuple[bool, list[str]]:
         """
         Validate security policy.
@@ -720,9 +677,8 @@ class ISecurityPolicy(ABC):
         Returns:
             Tuple of (is_valid, error_messages)
         """
-        pass
+        ...
     
-    @abstractmethod
     def apply_policy(self, policy_name: str, context: dict[str, Any]) -> bool:
         """
         Apply security policy.
@@ -734,9 +690,8 @@ class ISecurityPolicy(ABC):
         Returns:
             True if policy applied successfully
         """
-        pass
+        ...
     
-    @abstractmethod
     def list_policies(self) -> list[str]:
         """
         List all security policies.
@@ -744,9 +699,8 @@ class ISecurityPolicy(ABC):
         Returns:
             List of policy names
         """
-        pass
+        ...
     
-    @abstractmethod
     def remove_policy(self, policy_name: str) -> bool:
         """
         Remove security policy.
@@ -757,9 +711,8 @@ class ISecurityPolicy(ABC):
         Returns:
             True if removed
         """
-        pass
+        ...
     
-    @abstractmethod
     def get_policy_violations(self) -> list[dict[str, Any]]:
         """
         Get policy violations.
@@ -767,28 +720,27 @@ class ISecurityPolicy(ABC):
         Returns:
             List of policy violations
         """
-        pass
+        ...
     
-    @abstractmethod
     def clear_policy_violations(self) -> None:
         """
         Clear policy violations.
         """
-        pass
+        ...
 
 
 # ============================================================================
 # SECURITY TOKEN INTERFACES
 # ============================================================================
 
-class ISecurityToken(ABC):
+@runtime_checkable
+class ISecurityToken(Protocol):
     """
     Interface for security tokens.
     
     Enforces consistent security token behavior across XWSystem.
     """
     
-    @abstractmethod
     def generate_token(self, payload: dict[str, Any], expires_in: int = 3600) -> str:
         """
         Generate security token.
@@ -800,9 +752,8 @@ class ISecurityToken(ABC):
         Returns:
             Generated token
         """
-        pass
+        ...
     
-    @abstractmethod
     def validate_token(self, token: str) -> tuple[bool, dict[str, Any]]:
         """
         Validate security token.
@@ -813,9 +764,8 @@ class ISecurityToken(ABC):
         Returns:
             Tuple of (is_valid, payload)
         """
-        pass
+        ...
     
-    @abstractmethod
     def refresh_token(self, token: str, expires_in: int = 3600) -> str:
         """
         Refresh security token.
@@ -827,9 +777,8 @@ class ISecurityToken(ABC):
         Returns:
             Refreshed token
         """
-        pass
+        ...
     
-    @abstractmethod
     def revoke_token(self, token: str) -> bool:
         """
         Revoke security token.
@@ -840,9 +789,8 @@ class ISecurityToken(ABC):
         Returns:
             True if revoked
         """
-        pass
+        ...
     
-    @abstractmethod
     def is_token_expired(self, token: str) -> bool:
         """
         Check if token is expired.
@@ -853,9 +801,8 @@ class ISecurityToken(ABC):
         Returns:
             True if expired
         """
-        pass
+        ...
     
-    @abstractmethod
     def get_token_info(self, token: str) -> dict[str, Any]:
         """
         Get token information.
@@ -866,9 +813,8 @@ class ISecurityToken(ABC):
         Returns:
             Token information dictionary
         """
-        pass
+        ...
     
-    @abstractmethod
     def list_active_tokens(self, user: Optional[str] = None) -> list[str]:
         """
         List active tokens.
@@ -879,9 +825,8 @@ class ISecurityToken(ABC):
         Returns:
             List of active tokens
         """
-        pass
+        ...
     
-    @abstractmethod
     def cleanup_expired_tokens(self) -> int:
         """
         Cleanup expired tokens.
@@ -889,7 +834,7 @@ class ISecurityToken(ABC):
         Returns:
             Number of tokens cleaned up
         """
-        pass
+        ...
 
 
 # ============================================================================
@@ -897,22 +842,22 @@ class ISecurityToken(ABC):
 # ============================================================================
 
 @runtime_checkable
-class Hashable(Protocol):
+class IHashable(Protocol):
     """Protocol for objects that can be hashed securely."""
     
-    def hash(self, data: Union[str, bytes], **kwargs: Any) -> str:
+    def hash(self, data: str | bytes, **kwargs: Any) -> str:
         """Generate hash of data."""
         ...
 
 
 @runtime_checkable
-class Encryptable(Protocol):
+class IEncryptable(Protocol):
     """Protocol for objects that support encryption/decryption."""
     
-    def encrypt(self, data: Union[str, bytes], **kwargs: Any) -> bytes:
+    def encrypt(self, data: str | bytes, **kwargs: Any) -> bytes:
         """Encrypt data."""
         ...
     
-    def decrypt(self, data: bytes, **kwargs: Any) -> Union[str, bytes]:
+    def decrypt(self, data: bytes, **kwargs: Any) -> str | bytes:
         """Decrypt data."""
         ...