provide-foundation 0.0.0.dev0__py3-none-any.whl

provide/foundation/crypto/keys.py

@@ -0,0 +1,188 @@
+"""Unified key generation for all cryptographic algorithms."""
+
+from typing import Any, Protocol, Union
+
+from cryptography.hazmat.primitives.asymmetric import ec, rsa
+
+from provide.foundation import logger
+from provide.foundation.crypto.constants import (
+    DEFAULT_ECDSA_CURVE,
+    DEFAULT_RSA_KEY_SIZE,
+    SUPPORTED_EC_CURVES,
+    SUPPORTED_KEY_TYPES,
+    SUPPORTED_RSA_SIZES,
+)
+from provide.foundation.crypto.signatures import generate_ed25519_keypair
+
+
+class KeyPair(Protocol):
+    """Protocol for key pairs."""
+
+    def public_key(self) -> Any:
+        """Get public key."""
+        ...
+
+
+# Type aliases for different key types
+RSAKeyPair = tuple[rsa.RSAPublicKey, rsa.RSAPrivateKey]
+ECKeyPair = tuple[ec.EllipticCurvePublicKey, ec.EllipticCurvePrivateKey]
+Ed25519KeyPair = tuple[bytes, bytes]
+
+KeyPairType = Union[RSAKeyPair, ECKeyPair, Ed25519KeyPair]
+
+
+def generate_rsa_keypair(key_size: int = DEFAULT_RSA_KEY_SIZE) -> RSAKeyPair:
+    """Generate RSA key pair.
+
+    Args:
+        key_size: RSA key size in bits (2048, 3072, or 4096)
+
+    Returns:
+        tuple: (public_key, private_key)
+
+    Raises:
+        ValueError: If key size is not supported
+    """
+    if key_size not in SUPPORTED_RSA_SIZES:
+        raise ValueError(
+            f"Unsupported RSA key size: {key_size}. "
+            f"Supported sizes: {sorted(SUPPORTED_RSA_SIZES)}"
+        )
+
+    logger.debug(f"🔑 Generating RSA key pair (size: {key_size})")
+
+    private_key = rsa.generate_private_key(
+        public_exponent=65537,
+        key_size=key_size,
+    )
+    public_key = private_key.public_key()
+
+    logger.debug(f"✅ Generated RSA key pair ({key_size} bits)")
+    return public_key, private_key
+
+
+def generate_ec_keypair(curve: str = DEFAULT_ECDSA_CURVE) -> ECKeyPair:
+    """Generate ECDSA key pair.
+
+    Args:
+        curve: Elliptic curve name (secp256r1, secp384r1, or secp521r1)
+
+    Returns:
+        tuple: (public_key, private_key)
+
+    Raises:
+        ValueError: If curve is not supported
+        AttributeError: If curve name is invalid
+    """
+    if curve not in SUPPORTED_EC_CURVES:
+        raise ValueError(
+            f"Unsupported EC curve: {curve}. "
+            f"Supported curves: {sorted(SUPPORTED_EC_CURVES)}"
+        )
+
+    logger.debug(f"🔑 Generating ECDSA key pair (curve: {curve})")
+
+    # Map curve name to cryptography curve object
+    curve_obj = getattr(ec, curve.upper())()
+
+    private_key = ec.generate_private_key(curve_obj)
+    public_key = private_key.public_key()
+
+    logger.debug(f"✅ Generated ECDSA key pair ({curve})")
+    return public_key, private_key
+
+
+def generate_keypair(
+    key_type: str,
+    key_size: int | None = None,
+    curve: str | None = None,
+) -> KeyPairType:
+    """Generate a key pair of the specified type.
+
+    Args:
+        key_type: Type of key to generate ("rsa", "ecdsa", or "ed25519")
+        key_size: Key size in bits (required for RSA)
+        curve: Curve name (required for ECDSA)
+
+    Returns:
+        KeyPair: Generated key pair
+
+    Raises:
+        ValueError: If key_type is not supported or required params missing
+    """
+    key_type_lower = key_type.lower()
+
+    if key_type_lower not in SUPPORTED_KEY_TYPES:
+        raise ValueError(
+            f"Unsupported key type: {key_type}. "
+            f"Supported types: {sorted(SUPPORTED_KEY_TYPES)}"
+        )
+
+    match key_type_lower:
+        case "rsa":
+            if key_size is None:
+                key_size = DEFAULT_RSA_KEY_SIZE
+                logger.debug(f"🔑 Using default RSA key size: {key_size}")
+            return generate_rsa_keypair(key_size)
+
+        case "ecdsa":
+            if curve is None:
+                curve = DEFAULT_ECDSA_CURVE
+                logger.debug(f"🔑 Using default ECDSA curve: {curve}")
+            return generate_ec_keypair(curve)
+
+        case "ed25519":
+            # Ed25519 has fixed parameters
+            if key_size is not None or curve is not None:
+                logger.warning(
+                    "🔑 Ed25519 has fixed parameters - ignoring key_size/curve"
+                )
+            return generate_ed25519_keypair()
+
+        case _:
+            # This shouldn't happen due to the check above
+            raise ValueError(f"Internal error: unhandled key type {key_type}")
+
+
+# Convenience functions for specific use cases
+def generate_signing_keypair() -> Ed25519KeyPair:
+    """Generate Ed25519 keypair for digital signatures.
+
+    This is the recommended choice for new digital signature use cases.
+
+    Returns:
+        tuple: (private_key_bytes, public_key_bytes)
+    """
+    return generate_ed25519_keypair()
+
+
+def generate_tls_keypair(
+    key_type: str = "ecdsa",
+    curve: str = DEFAULT_ECDSA_CURVE,
+) -> ECKeyPair | RSAKeyPair:
+    """Generate keypair suitable for TLS/certificates.
+
+    Args:
+        key_type: Either "ecdsa" (recommended) or "rsa"
+        curve: ECDSA curve (only used if key_type is "ecdsa")
+
+    Returns:
+        KeyPair: Generated key pair
+    """
+    if key_type == "ecdsa":
+        return generate_ec_keypair(curve)
+    elif key_type == "rsa":
+        return generate_rsa_keypair(DEFAULT_RSA_KEY_SIZE)
+    else:
+        raise ValueError(f"TLS key type must be 'ecdsa' or 'rsa', got {key_type}")
+
+
+# Legacy compatibility functions (for smooth migration)
+def generate_key_pair() -> Ed25519KeyPair:
+    """Legacy compatibility function.
+
+    This maintains compatibility with existing flavorpack code.
+    New code should use generate_signing_keypair() or generate_keypair().
+    """
+    logger.debug("🔑 Using legacy generate_key_pair() function")
+    return generate_ed25519_keypair()

provide/foundation/crypto/signatures.py

@@ -0,0 +1,144 @@
+"""Digital signature operations using Ed25519."""
+
+try:
+    from cryptography.exceptions import InvalidSignature
+    from cryptography.hazmat.primitives.asymmetric import ed25519
+
+    _HAS_CRYPTO = True
+except ImportError:
+    InvalidSignature = None
+    ed25519 = None
+    _HAS_CRYPTO = False
+
+from provide.foundation import logger
+from provide.foundation.crypto.constants import (
+    ED25519_PRIVATE_KEY_SIZE,
+    ED25519_PUBLIC_KEY_SIZE,
+    ED25519_SIGNATURE_SIZE,
+)
+
+
+def _require_crypto() -> None:
+    """Ensure cryptography is available."""
+    if not _HAS_CRYPTO:
+        raise ImportError(
+            "Cryptography features require optional dependencies. "
+            "Install with: pip install 'provide-foundation[crypto]'"
+        )
+
+
+def generate_ed25519_keypair() -> tuple[bytes, bytes]:
+    """Generate Ed25519 key pair for digital signatures.
+
+    Returns:
+        tuple: (private_key_bytes, public_key_bytes)
+            - private_key_bytes: 32-byte Ed25519 private key seed
+            - public_key_bytes: 32-byte Ed25519 public key
+    """
+    _require_crypto()
+    logger.debug("🔐 Generating Ed25519 key pair")
+
+    # Generate a new Ed25519 private key
+    private_key = ed25519.Ed25519PrivateKey.generate()
+
+    # Get the raw bytes for compatibility with other implementations
+    private_key_bytes = private_key.private_bytes_raw()
+    public_key_bytes = private_key.public_key().public_bytes_raw()
+
+    # Validate key sizes
+    assert len(private_key_bytes) == ED25519_PRIVATE_KEY_SIZE
+    assert len(public_key_bytes) == ED25519_PUBLIC_KEY_SIZE
+
+    logger.debug(
+        f"✅ Generated Ed25519 key pair (public: {len(public_key_bytes)} bytes)"
+    )
+    return private_key_bytes, public_key_bytes
+
+
+def sign_data(data: bytes, private_key: bytes) -> bytes:
+    """Sign data with Ed25519 private key.
+
+    Args:
+        data: The data to sign
+        private_key: 32-byte Ed25519 private key seed
+
+    Returns:
+        bytes: 64-byte Ed25519 signature
+
+    Raises:
+        ValueError: If private key is wrong size
+    """
+    _require_crypto()
+    if len(private_key) != ED25519_PRIVATE_KEY_SIZE:
+        raise ValueError(
+            f"Private key must be {ED25519_PRIVATE_KEY_SIZE} bytes, "
+            f"got {len(private_key)}"
+        )
+
+    logger.debug(f"🔏 Signing {len(data)} bytes of data with Ed25519")
+
+    # Reconstruct the private key from the seed bytes
+    private_key_obj = ed25519.Ed25519PrivateKey.from_private_bytes(private_key)
+
+    # Sign the data
+    signature = private_key_obj.sign(data)
+
+    # Validate signature size
+    assert len(signature) == ED25519_SIGNATURE_SIZE
+
+    logger.debug(f"✅ Created Ed25519 signature ({len(signature)} bytes)")
+    return signature
+
+
+def verify_signature(data: bytes, signature: bytes, public_key: bytes) -> bool:
+    """Verify Ed25519 signature.
+
+    Args:
+        data: The data that was signed
+        signature: 64-byte Ed25519 signature
+        public_key: 32-byte Ed25519 public key
+
+    Returns:
+        bool: True if signature is valid, False otherwise
+    """
+    _require_crypto()
+    if len(signature) != ED25519_SIGNATURE_SIZE:
+        logger.warning(
+            f"❌ Invalid signature size: expected {ED25519_SIGNATURE_SIZE}, "
+            f"got {len(signature)}"
+        )
+        return False
+
+    if len(public_key) != ED25519_PUBLIC_KEY_SIZE:
+        logger.warning(
+            f"❌ Invalid public key size: expected {ED25519_PUBLIC_KEY_SIZE}, "
+            f"got {len(public_key)}"
+        )
+        return False
+
+    logger.debug(f"🔍 Verifying Ed25519 signature for {len(data)} bytes of data")
+
+    try:
+        public_key_obj = ed25519.Ed25519PublicKey.from_public_bytes(public_key)
+        public_key_obj.verify(signature, data)
+        logger.debug("✅ Ed25519 signature verification successful")
+        return True
+    except InvalidSignature:
+        logger.debug("❌ Invalid Ed25519 signature")
+        return False
+    except Exception as e:
+        logger.error(f"❌ Ed25519 signature verification error: {e}")
+        return False
+
+
+# Convenience function for generating signing keypairs
+def generate_signing_keypair() -> tuple[bytes, bytes]:
+    """Generate Ed25519 keypair for signing (convenience function).
+
+    This is an alias for generate_ed25519_keypair() that makes intent clear.
+
+    Returns:
+        tuple: (private_key_bytes, public_key_bytes)
+    """
+    _require_crypto()
+    return generate_ed25519_keypair()

provide/foundation/crypto/utils.py

@@ -0,0 +1,164 @@
+"""Utility functions for hashing and cryptographic operations."""
+
+import hashlib
+
+
+def quick_hash(data: bytes) -> int:
+    """Generate a quick non-cryptographic hash for lookups.
+
+    This uses Python's built-in hash function which is fast but not
+    cryptographically secure. Use only for hash tables and caching.
+
+    Args:
+        data: Data to hash
+
+    Returns:
+        32-bit hash value
+    """
+    # Use Python's built-in hash for speed, mask to 32 bits
+    return hash(data) & 0xFFFFFFFF
+
+
+def hash_name(name: str) -> int:
+    """Generate a 64-bit hash of a string for fast lookup.
+
+    This is useful for creating numeric identifiers from strings.
+
+    Args:
+        name: String to hash
+
+    Returns:
+        64-bit integer hash
+    """
+    # Use first 8 bytes of SHA256 for good distribution
+    hash_bytes = hashlib.sha256(name.encode("utf-8")).digest()[:8]
+    return int.from_bytes(hash_bytes, byteorder="little")
+
+
+def compare_hash(hash1: str, hash2: str) -> bool:
+    """Compare two hash values in a case-insensitive manner.
+
+    Args:
+        hash1: First hash value
+        hash2: Second hash value
+
+    Returns:
+        True if hashes match (case-insensitive)
+    """
+    return hash1.lower() == hash2.lower()
+
+
+def format_hash(
+    hash_value: str,
+    group_size: int = 8,
+    groups: int = 0,
+    separator: str = " ",
+) -> str:
+    """Format a hash value for display.
+
+    Args:
+        hash_value: Hash value to format
+        group_size: Number of characters per group
+        groups: Number of groups to show (0 for all)
+        separator: Separator between groups
+
+    Returns:
+        Formatted hash string
+
+    Examples:
+        >>> format_hash("abc123def456", group_size=4, separator="-")
+        "abc1-23de-f456"
+        >>> format_hash("abc123def456", group_size=4, groups=2)
+        "abc1 23de"
+    """
+    if group_size <= 0:
+        return hash_value
+
+    formatted_parts = []
+    for i in range(0, len(hash_value), group_size):
+        formatted_parts.append(hash_value[i : i + group_size])
+        if groups > 0 and len(formatted_parts) >= groups:
+            break
+
+    return separator.join(formatted_parts)
+
+
+def truncate_hash(hash_value: str, length: int = 16, suffix: str = "...") -> str:
+    """Truncate a hash for display purposes.
+
+    Args:
+        hash_value: Hash value to truncate
+        length: Number of characters to keep
+        suffix: Suffix to append
+
+    Returns:
+        Truncated hash string
+
+    Examples:
+        >>> truncate_hash("abc123def456789", length=8)
+        "abc123de..."
+    """
+    if len(hash_value) <= length:
+        return hash_value
+    return hash_value[:length] + suffix
+
+
+def hash_to_int(hash_value: str) -> int:
+    """Convert a hex hash string to an integer.
+
+    Args:
+        hash_value: Hex hash string
+
+    Returns:
+        Integer representation of the hash
+    """
+    return int(hash_value, 16)
+
+
+def int_to_hash(value: int, length: int | None = None) -> str:
+    """Convert an integer to a hex hash string.
+
+    Args:
+        value: Integer value
+        length: Desired length (will pad with zeros)
+
+    Returns:
+        Hex string representation
+    """
+    hex_str = format(value, "x")
+    if length and len(hex_str) < length:
+        hex_str = hex_str.zfill(length)
+    return hex_str
+
+
+def is_valid_hash(hash_value: str, algorithm: str | None = None) -> bool:
+    """Check if a string is a valid hash value.
+
+    Args:
+        hash_value: String to check
+        algorithm: Optional algorithm to validate length against
+
+    Returns:
+        True if string appears to be a valid hash
+    """
+    # Check if it's a valid hex string
+    try:
+        int(hash_value, 16)
+    except ValueError:
+        return False
+
+    # If algorithm specified, check length
+    if algorithm:
+        from provide.foundation.crypto.algorithms import (
+            get_digest_size,
+            validate_algorithm,
+        )
+
+        try:
+            validate_algorithm(algorithm)
+            expected_length = get_digest_size(algorithm) * 2  # hex is 2 chars per byte
+            return len(hash_value) == expected_length
+        except Exception:
+            return False
+
+    return True

provide/foundation/errors/__init__.py

@@ -0,0 +1,96 @@
+"""
+Foundation error handling system.
+
+Provides a comprehensive exception hierarchy, error context management,
+and utilities for robust error handling throughout the application.
+"""
+
+from provide.foundation.errors.auth import AuthenticationError, AuthorizationError
+from provide.foundation.errors.base import FoundationError
+from provide.foundation.errors.config import (
+    ConfigurationError,
+    ConfigValidationError,
+    ValidationError,
+)
+from provide.foundation.errors.context import (
+    ErrorCategory,
+    ErrorContext,
+    ErrorSeverity,
+    capture_error_context,
+)
+from provide.foundation.errors.decorators import (
+    fallback_on_error,
+    retry_on_error,
+    suppress_and_log,
+    with_error_handling,
+)
+from provide.foundation.errors.handlers import (
+    ErrorHandler,
+    error_boundary,
+    handle_error,
+    transactional,
+)
+from provide.foundation.errors.integration import (
+    IntegrationError,
+    NetworkError,
+    TimeoutError,
+)
+from provide.foundation.errors.process import (
+    CommandNotFoundError,
+    ProcessError,
+    ProcessTimeoutError,
+)
+from provide.foundation.errors.resources import (
+    AlreadyExistsError,
+    NotFoundError,
+    ResourceError,
+)
+from provide.foundation.errors.runtime import ConcurrencyError, RuntimeError, StateError
+from provide.foundation.errors.safe_decorators import log_only_error_context
+from provide.foundation.errors.types import (
+    ErrorCode,
+    ErrorMetadata,
+    RetryPolicy,
+)
+
+__all__ = [
+    "AlreadyExistsError",
+    "AuthenticationError",
+    "AuthorizationError",
+    "CommandNotFoundError",
+    "ConcurrencyError",
+    "ConfigurationError",
+    "ConfigValidationError",
+    "ErrorCategory",
+    # Types
+    "ErrorCode",
+    # Context
+    "ErrorContext",
+    "ErrorHandler",
+    "ErrorMetadata",
+    "ErrorSeverity",
+    # Base exceptions
+    "FoundationError",
+    "IntegrationError",
+    "NetworkError",
+    "NotFoundError",
+    "ProcessError",
+    "ProcessTimeoutError",
+    "ResourceError",
+    "RetryPolicy",
+    "RuntimeError",
+    "StateError",
+    "TimeoutError",
+    "ValidationError",
+    "capture_error_context",
+    # Handlers
+    "error_boundary",
+    "fallback_on_error",
+    "handle_error",
+    "log_only_error_context",
+    "retry_on_error",
+    "suppress_and_log",
+    "transactional",
+    # Decorators
+    "with_error_handling",
+]

provide/foundation/errors/auth.py

@@ -0,0 +1,73 @@
+"""Authentication and authorization exceptions."""
+
+from typing import Any
+
+from provide.foundation.errors.base import FoundationError
+
+
+class AuthenticationError(FoundationError):
+    """Raised when authentication fails.
+
+    Args:
+        message: Error message describing the authentication failure.
+        auth_method: Optional authentication method used.
+        realm: Optional authentication realm.
+        **kwargs: Additional context passed to FoundationError.
+
+    Examples:
+        >>> raise AuthenticationError("Invalid credentials")
+        >>> raise AuthenticationError("Token expired", auth_method="jwt")
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        auth_method: str | None = None,
+        realm: str | None = None,
+        **kwargs: Any,
+    ) -> None:
+        if auth_method:
+            kwargs.setdefault("context", {})["auth.method"] = auth_method
+        if realm:
+            kwargs.setdefault("context", {})["auth.realm"] = realm
+        super().__init__(message, **kwargs)
+
+    def _default_code(self) -> str:
+        return "AUTH_ERROR"
+
+
+class AuthorizationError(FoundationError):
+    """Raised when authorization fails.
+
+    Args:
+        message: Error message describing the authorization failure.
+        required_permission: Optional required permission.
+        resource: Optional resource being accessed.
+        actor: Optional actor (user/service) attempting access.
+        **kwargs: Additional context passed to FoundationError.
+
+    Examples:
+        >>> raise AuthorizationError("Access denied")
+        >>> raise AuthorizationError("Insufficient permissions", required_permission="admin")
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        required_permission: str | None = None,
+        resource: str | None = None,
+        actor: str | None = None,
+        **kwargs: Any,
+    ) -> None:
+        if required_permission:
+            kwargs.setdefault("context", {})["authz.permission"] = required_permission
+        if resource:
+            kwargs.setdefault("context", {})["authz.resource"] = resource
+        if actor:
+            kwargs.setdefault("context", {})["authz.actor"] = actor
+        super().__init__(message, **kwargs)
+
+    def _default_code(self) -> str:
+        return "AUTHZ_ERROR"