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

provide/foundation/crypto/certificates/certificate.py

@@ -0,0 +1,290 @@
+"""Main Certificate class."""
+
+from datetime import UTC, datetime
+from functools import cached_property
+from typing import Self
+
+from attrs import Factory, define, field
+
+try:
+    from cryptography import x509
+    from cryptography.hazmat.primitives import serialization
+    from cryptography.hazmat.primitives.asymmetric import ec, rsa
+    from cryptography.x509 import Certificate as X509Certificate
+    
+    _HAS_CRYPTO = True
+except ImportError:
+    x509 = None
+    serialization = None
+    ec = None
+    rsa = None
+    X509Certificate = None
+    _HAS_CRYPTO = False
+
+from provide.foundation import logger
+from provide.foundation.crypto.certificates.base import CertificateBase, CertificateError, PublicKey
+from provide.foundation.crypto.certificates.generator import generate_certificate
+from provide.foundation.crypto.certificates.loader import load_certificate_from_pem
+from provide.foundation.crypto.certificates.operations import create_x509_certificate
+from provide.foundation.crypto.certificates.trust import verify_trust as verify_trust_impl
+from provide.foundation.crypto.constants import (
+    DEFAULT_CERTIFICATE_CURVE,
+    DEFAULT_CERTIFICATE_KEY_TYPE,
+    DEFAULT_CERTIFICATE_VALIDITY_DAYS,
+    DEFAULT_RSA_KEY_SIZE,
+)
+
+
+@define(slots=True, eq=False, hash=False, repr=False)
+class Certificate:
+    """X.509 certificate management using attrs."""
+
+    cert_pem_or_uri: str | None = field(default=None, kw_only=True)
+    key_pem_or_uri: str | None = field(default=None, kw_only=True)
+    generate_keypair: bool = field(default=False, kw_only=True)
+    key_type: str = field(default=DEFAULT_CERTIFICATE_KEY_TYPE, kw_only=True)
+    key_size: int = field(default=DEFAULT_RSA_KEY_SIZE, kw_only=True)
+    ecdsa_curve: str = field(default=DEFAULT_CERTIFICATE_CURVE, kw_only=True)
+    common_name: str = field(default="localhost", kw_only=True)
+    alt_names: list[str] | None = field(
+        default=Factory(lambda: ["localhost"]), kw_only=True
+    )
+    organization_name: str = field(default="Default Organization", kw_only=True)
+    validity_days: int = field(default=DEFAULT_CERTIFICATE_VALIDITY_DAYS, kw_only=True)
+
+    _base: CertificateBase = field(init=False, repr=False)
+    _private_key: "KeyPair | None" = field(init=False, default=None, repr=False)
+    _cert: "X509Certificate" = field(init=False, repr=False)
+    _trust_chain: list["Certificate"] = field(init=False, factory=list, repr=False)
+
+    cert: str = field(init=False, default="", repr=True)
+    key: str | None = field(init=False, default=None, repr=False)
+
+    def __attrs_post_init__(self) -> None:
+        """Handle loading or generation logic after attrs initialization."""
+        if self.generate_keypair:
+            # Generate new certificate
+            base, x509_cert, private_key, cert_pem, key_pem = generate_certificate(
+                common_name=self.common_name,
+                organization_name=self.organization_name,
+                validity_days=self.validity_days,
+                key_type=self.key_type,
+                key_size=self.key_size,
+                ecdsa_curve=self.ecdsa_curve,
+                alt_names=self.alt_names,
+                is_ca=False,
+                is_client_cert=True,
+            )
+            self._base = base
+            self._cert = x509_cert
+            self._private_key = private_key
+            self.cert = cert_pem
+            self.key = key_pem
+        else:
+            # Load existing certificate
+            if not self.cert_pem_or_uri:
+                raise CertificateError(
+                    "cert_pem_or_uri required when not generating"
+                )
+            
+            base, x509_cert, private_key, cert_pem, key_pem = load_certificate_from_pem(
+                self.cert_pem_or_uri,
+                self.key_pem_or_uri
+            )
+            self._base = base
+            self._cert = x509_cert
+            self._private_key = private_key
+            self.cert = cert_pem
+            self.key = key_pem
+
+    # Properties
+    @property
+    def trust_chain(self) -> list["Certificate"]:
+        """Returns the list of trusted certificates associated with this one."""
+        return self._trust_chain
+
+    @trust_chain.setter
+    def trust_chain(self, value: list["Certificate"]) -> None:
+        """Sets the list of trusted certificates."""
+        self._trust_chain = value
+
+    @cached_property
+    def is_valid(self) -> bool:
+        """Checks if the certificate is currently valid based on its dates."""
+        if not hasattr(self, "_base"):
+            return False
+        now = datetime.now(UTC)
+        valid = self._base.not_valid_before <= now <= self._base.not_valid_after
+        return valid
+
+    @property
+    def is_ca(self) -> bool:
+        """Checks if the certificate has the Basic Constraints CA flag set to True."""
+        if not hasattr(self, "_cert"):
+            return False
+        try:
+            ext = self._cert.extensions.get_extension_for_oid(
+                x509.oid.ExtensionOID.BASIC_CONSTRAINTS
+            )
+            if isinstance(ext.value, x509.BasicConstraints):
+                return ext.value.ca
+            return False
+        except x509.ExtensionNotFound:
+            logger.debug("📜🔍⚠️ is_ca: Basic Constraints extension not found")
+            return False
+
+    @property
+    def subject(self) -> str:
+        """Returns the certificate subject as an RFC4514 string."""
+        if not hasattr(self, "_base"):
+            return "SubjectNotInitialized"
+        return self._base.subject.rfc4514_string()
+
+    @property
+    def issuer(self) -> str:
+        """Returns the certificate issuer as an RFC4514 string."""
+        if not hasattr(self, "_base"):
+            return "IssuerNotInitialized"
+        return self._base.issuer.rfc4514_string()
+
+    @property
+    def public_key(self) -> "PublicKey | None":
+        """Returns the public key object from the certificate."""
+        if not hasattr(self, "_base"):
+            return None
+        return self._base.public_key
+
+    @property
+    def serial_number(self) -> int | None:
+        """Returns the certificate serial number."""
+        if not hasattr(self, "_base"):
+            return None
+        return self._base.serial_number
+
+    # Factory methods - moved to factory.py but kept as classmethods for compatibility
+    @classmethod
+    def create_ca(
+        cls,
+        common_name: str,
+        organization_name: str,
+        validity_days: int,
+        key_type: str = DEFAULT_CERTIFICATE_KEY_TYPE,
+        key_size: int = DEFAULT_RSA_KEY_SIZE,
+        ecdsa_curve: str = DEFAULT_CERTIFICATE_CURVE,
+    ) -> "Certificate":
+        """Creates a new self-signed CA certificate."""
+        from provide.foundation.crypto.certificates.factory import create_ca_certificate
+        return create_ca_certificate(
+            common_name, organization_name, validity_days, 
+            key_type, key_size, ecdsa_curve
+        )
+
+    @classmethod
+    def create_signed_certificate(
+        cls,
+        ca_certificate: "Certificate",
+        common_name: str,
+        organization_name: str,
+        validity_days: int,
+        alt_names: list[str] | None = None,
+        key_type: str = DEFAULT_CERTIFICATE_KEY_TYPE,
+        key_size: int = DEFAULT_RSA_KEY_SIZE,
+        ecdsa_curve: str = DEFAULT_CERTIFICATE_CURVE,
+        is_client_cert: bool = False,
+    ) -> "Certificate":
+        """Creates a new certificate signed by the provided CA certificate."""
+        from provide.foundation.crypto.certificates.factory import create_signed_certificate
+        return create_signed_certificate(
+            ca_certificate, common_name, organization_name, validity_days,
+            alt_names, key_type, key_size, ecdsa_curve, is_client_cert
+        )
+
+    @classmethod
+    def create_self_signed_server_cert(
+        cls,
+        common_name: str,
+        organization_name: str,
+        validity_days: int,
+        alt_names: list[str] | None = None,
+        key_type: str = DEFAULT_CERTIFICATE_KEY_TYPE,
+        key_size: int = DEFAULT_RSA_KEY_SIZE,
+        ecdsa_curve: str = DEFAULT_CERTIFICATE_CURVE,
+    ) -> "Certificate":
+        """Creates a new self-signed end-entity certificate suitable for a server."""
+        from provide.foundation.crypto.certificates.factory import create_self_signed_server_cert
+        return create_self_signed_server_cert(
+            common_name, organization_name, validity_days,
+            alt_names, key_type, key_size, ecdsa_curve
+        )
+
+    def verify_trust(self, other_cert: Self) -> bool:
+        """Verifies if the `other_cert` is trusted based on this certificate's trust chain."""
+        return verify_trust_impl(self, other_cert, self._trust_chain)
+
+    def _create_x509_certificate(
+        self,
+        issuer_name_override: "x509.Name | None" = None,
+        signing_key_override: "KeyPair | None" = None,
+        is_ca: bool = False,
+        is_client_cert: bool = False,
+    ) -> "X509Certificate":
+        """Internal helper to build and sign the X.509 certificate object."""
+        return create_x509_certificate(
+            base=self._base,
+            private_key=self._private_key,
+            alt_names=self.alt_names,
+            issuer_name_override=issuer_name_override,
+            signing_key_override=signing_key_override,
+            is_ca=is_ca,
+            is_client_cert=is_client_cert,
+        )
+
+    def _validate_signature(
+        self, signed_cert: "Certificate", signing_cert: "Certificate"
+    ) -> bool:
+        """Internal helper: Validates signature and issuer/subject match."""
+        from provide.foundation.crypto.certificates.trust import validate_signature_wrapper
+        return validate_signature_wrapper(signed_cert, signing_cert)
+
+    def __eq__(self, other: object) -> bool:
+        """Custom equality based on subject and serial number."""
+        if not isinstance(other, Certificate):
+            return NotImplemented
+        if not hasattr(self, "_base") or not hasattr(other, "_base"):
+            return False
+        eq = (
+            self._base.subject == other._base.subject
+            and self._base.serial_number == other._base.serial_number
+        )
+        return eq
+
+    def __hash__(self) -> int:
+        """Custom hash based on subject and serial number."""
+        if not hasattr(self, "_base"):
+            logger.warning("📜🔍⚠️ __hash__ called before _base initialized")
+            return hash((None, None))
+
+        h = hash((self._base.subject, self._base.serial_number))
+        return h
+
+    def __repr__(self) -> str:
+        try:
+            subject_str = self.subject
+            issuer_str = self.issuer
+            valid_str = str(self.is_valid)
+            ca_str = str(self.is_ca)
+        except AttributeError:
+            subject_str = "PartiallyInitialized"
+            issuer_str = "PartiallyInitialized"
+            valid_str = "Unknown"
+            ca_str = "Unknown"
+
+        return (
+            f"Certificate(subject='{subject_str}', issuer='{issuer_str}', "
+            f"common_name='{self.common_name}', valid={valid_str}, ca={ca_str}, "
+            f"key_type='{self.key_type}')"
+        )
+
+
+# Type alias for backwards compatibility
+KeyPair = rsa.RSAPrivateKey | ec.EllipticCurvePrivateKey | None

provide/foundation/crypto/certificates/factory.py

@@ -0,0 +1,213 @@
+"""Certificate factory methods."""
+
+try:
+    from cryptography import x509
+    from cryptography.hazmat.primitives import serialization
+    
+    _HAS_CRYPTO = True
+except ImportError:
+    x509 = None
+    serialization = None
+    _HAS_CRYPTO = False
+
+from provide.foundation import logger
+from provide.foundation.crypto.certificates.base import CertificateError, _require_crypto
+from provide.foundation.crypto.certificates.operations import create_x509_certificate
+from provide.foundation.crypto.constants import (
+    DEFAULT_CERTIFICATE_CURVE,
+    DEFAULT_CERTIFICATE_KEY_TYPE,
+    DEFAULT_CERTIFICATE_VALIDITY_DAYS,
+    DEFAULT_RSA_KEY_SIZE,
+)
+
+
+def create_ca_certificate(
+    common_name: str,
+    organization_name: str,
+    validity_days: int,
+    key_type: str = DEFAULT_CERTIFICATE_KEY_TYPE,
+    key_size: int = DEFAULT_RSA_KEY_SIZE,
+    ecdsa_curve: str = DEFAULT_CERTIFICATE_CURVE,
+) -> "Certificate":
+    """Creates a new self-signed CA certificate."""
+    # Import here to avoid circular dependency
+    from provide.foundation.crypto.certificates.certificate import Certificate
+    
+    logger.info(
+        f"📜🔑🏭 Creating new CA certificate: CN={common_name}, Org={organization_name}"
+    )
+    ca_cert_obj = Certificate(
+        generate_keypair=True,
+        common_name=common_name,
+        organization_name=organization_name,
+        validity_days=validity_days,
+        key_type=key_type,
+        key_size=key_size,
+        ecdsa_curve=ecdsa_curve,
+        alt_names=[common_name],
+    )
+    # Re-sign to ensure CA flags are correctly set for a CA
+    logger.info("📜🔑🏭 Re-signing generated CA certificate to ensure is_ca=True")
+    actual_ca_x509_cert = create_x509_certificate(
+        base=ca_cert_obj._base,
+        private_key=ca_cert_obj._private_key,
+        alt_names=ca_cert_obj.alt_names,
+        is_ca=True,
+        is_client_cert=False,
+    )
+    ca_cert_obj._cert = actual_ca_x509_cert
+    ca_cert_obj.cert = actual_ca_x509_cert.public_bytes(
+        serialization.Encoding.PEM
+    ).decode("utf-8")
+    return ca_cert_obj
+
+
+def create_signed_certificate(
+    ca_certificate: "Certificate",
+    common_name: str,
+    organization_name: str,
+    validity_days: int,
+    alt_names: list[str] | None = None,
+    key_type: str = DEFAULT_CERTIFICATE_KEY_TYPE,
+    key_size: int = DEFAULT_RSA_KEY_SIZE,
+    ecdsa_curve: str = DEFAULT_CERTIFICATE_CURVE,
+    is_client_cert: bool = False,
+) -> "Certificate":
+    """Creates a new certificate signed by the provided CA certificate."""
+    # Import here to avoid circular dependency
+    from provide.foundation.crypto.certificates.certificate import Certificate
+    
+    logger.info(
+        f"📜🔑🏭 Creating new certificate signed by CA '{ca_certificate.subject}': "
+        f"CN={common_name}, Org={organization_name}, ClientCert={is_client_cert}"
+    )
+    if not ca_certificate._private_key:
+        raise CertificateError(
+            message="CA certificate's private key is not available for signing.",
+            hint="Ensure the CA certificate object was loaded or created with its private key.",
+        )
+    if not ca_certificate.is_ca:
+        logger.warning(
+            f"📜🔑⚠️ Signing certificate (Subject: {ca_certificate.subject}) "
+            "is not marked as a CA. This might lead to validation issues."
+        )
+    
+    new_cert_obj = Certificate(
+        generate_keypair=True,
+        common_name=common_name,
+        organization_name=organization_name,
+        validity_days=validity_days,
+        alt_names=alt_names or [common_name],
+        key_type=key_type,
+        key_size=key_size,
+        ecdsa_curve=ecdsa_curve,
+    )
+    
+    signed_x509_cert = create_x509_certificate(
+        base=new_cert_obj._base,
+        private_key=new_cert_obj._private_key,
+        alt_names=new_cert_obj.alt_names,
+        issuer_name_override=ca_certificate._base.subject,
+        signing_key_override=ca_certificate._private_key,
+        is_ca=False,
+        is_client_cert=is_client_cert,
+    )
+    
+    new_cert_obj._cert = signed_x509_cert
+    new_cert_obj.cert = signed_x509_cert.public_bytes(
+        serialization.Encoding.PEM
+    ).decode("utf-8")
+    
+    logger.info(
+        f"📜🔑✅ Successfully created and signed certificate for "
+        f"CN={common_name} by CA='{ca_certificate.subject}'"
+    )
+    return new_cert_obj
+
+
+def create_self_signed_server_cert(
+    common_name: str,
+    organization_name: str,
+    validity_days: int,
+    alt_names: list[str] | None = None,
+    key_type: str = DEFAULT_CERTIFICATE_KEY_TYPE,
+    key_size: int = DEFAULT_RSA_KEY_SIZE,
+    ecdsa_curve: str = DEFAULT_CERTIFICATE_CURVE,
+) -> "Certificate":
+    """Creates a new self-signed end-entity certificate suitable for a server."""
+    # Import here to avoid circular dependency
+    from provide.foundation.crypto.certificates.certificate import Certificate
+    
+    logger.info(
+        f"📜🔑🏭 Creating new self-signed SERVER certificate: "
+        f"CN={common_name}, Org={organization_name}"
+    )
+    
+    cert_obj = Certificate(
+        generate_keypair=True,
+        common_name=common_name,
+        organization_name=organization_name,
+        validity_days=validity_days,
+        alt_names=alt_names or [common_name],
+        key_type=key_type,
+        key_size=key_size,
+        ecdsa_curve=ecdsa_curve,
+    )
+    
+    if not cert_obj._private_key:
+        raise CertificateError(
+            "Private key not generated for self-signed server certificate"
+        )
+    
+    actual_x509_cert = create_x509_certificate(
+        base=cert_obj._base,
+        private_key=cert_obj._private_key,
+        alt_names=cert_obj.alt_names,
+        is_ca=False,
+        is_client_cert=False,
+    )
+    
+    cert_obj._cert = actual_x509_cert
+    cert_obj.cert = actual_x509_cert.public_bytes(
+        serialization.Encoding.PEM
+    ).decode("utf-8")
+    
+    logger.info(
+        f"📜🔑✅ Successfully created self-signed SERVER certificate for CN={common_name}"
+    )
+    return cert_obj
+
+
+# Convenience functions for common use cases
+def create_self_signed(
+    common_name: str = "localhost",
+    alt_names: list[str] | None = None,
+    organization: str = "Default Organization",
+    validity_days: int = DEFAULT_CERTIFICATE_VALIDITY_DAYS,
+    key_type: str = DEFAULT_CERTIFICATE_KEY_TYPE,
+) -> "Certificate":
+    """Create a self-signed certificate (convenience function)."""
+    _require_crypto()
+    return create_self_signed_server_cert(
+        common_name=common_name,
+        organization_name=organization,
+        validity_days=validity_days,
+        alt_names=alt_names or [common_name],
+        key_type=key_type,
+    )
+
+
+def create_ca(
+    common_name: str,
+    organization: str = "Default CA Organization",
+    validity_days: int = DEFAULT_CERTIFICATE_VALIDITY_DAYS * 2,  # CAs live longer
+    key_type: str = DEFAULT_CERTIFICATE_KEY_TYPE,
+) -> "Certificate":
+    """Create a CA certificate (convenience function)."""
+    _require_crypto()
+    return create_ca_certificate(
+        common_name=common_name,
+        organization_name=organization,
+        validity_days=validity_days,
+        key_type=key_type,
+    )

provide/foundation/crypto/certificates/generator.py

@@ -0,0 +1,138 @@
+"""Certificate generation utilities."""
+
+from datetime import UTC, datetime, timedelta
+import traceback
+
+try:
+    from cryptography import x509
+    from cryptography.hazmat.primitives import serialization
+    from cryptography.hazmat.primitives.asymmetric import ec, rsa
+    
+    _HAS_CRYPTO = True
+except ImportError:
+    x509 = None
+    serialization = None
+    ec = None
+    rsa = None
+    _HAS_CRYPTO = False
+
+from provide.foundation import logger
+from provide.foundation.crypto.certificates.base import (
+    CertificateBase,
+    CertificateConfig,
+    CertificateError,
+    CurveType,
+    KeyType,
+)
+from provide.foundation.crypto.certificates.operations import create_x509_certificate
+from provide.foundation.crypto.constants import (
+    DEFAULT_CERTIFICATE_CURVE,
+    DEFAULT_CERTIFICATE_KEY_TYPE,
+    DEFAULT_CERTIFICATE_VALIDITY_DAYS,
+    DEFAULT_RSA_KEY_SIZE,
+)
+
+
+def generate_certificate(
+    common_name: str,
+    organization_name: str,
+    validity_days: int,
+    key_type: str = DEFAULT_CERTIFICATE_KEY_TYPE,
+    key_size: int = DEFAULT_RSA_KEY_SIZE,
+    ecdsa_curve: str = DEFAULT_CERTIFICATE_CURVE,
+    alt_names: list[str] | None = None,
+    is_ca: bool = False,
+    is_client_cert: bool = False,
+) -> tuple[CertificateBase, "x509.Certificate", "rsa.RSAPrivateKey | ec.EllipticCurvePrivateKey", str, str]:
+    """
+    Generate a new certificate with a keypair.
+    
+    Returns:
+        Tuple of (CertificateBase, X509Certificate, private_key, cert_pem, key_pem)
+    """
+    try:
+        logger.debug("📜🔑🚀 Generating new keypair")
+        
+        now = datetime.now(UTC)
+        not_valid_before = now - timedelta(days=1)
+        not_valid_after = now + timedelta(days=validity_days)
+        
+        # Parse key type
+        normalized_key_type_str = key_type.lower()
+        match normalized_key_type_str:
+            case "rsa":
+                gen_key_type = KeyType.RSA
+            case "ecdsa":
+                gen_key_type = KeyType.ECDSA
+            case _:
+                raise ValueError(
+                    f"Unsupported key_type string: '{key_type}'. "
+                    "Must be 'rsa' or 'ecdsa'."
+                )
+        
+        # Configure key parameters
+        gen_curve: CurveType | None = None
+        gen_key_size = None
+        
+        if gen_key_type == KeyType.ECDSA:
+            try:
+                gen_curve = CurveType[ecdsa_curve.upper()]
+            except KeyError as e_curve:
+                raise ValueError(
+                    f"Unsupported ECDSA curve: {ecdsa_curve}"
+                ) from e_curve
+        else:  # RSA
+            gen_key_size = key_size
+        
+        # Build configuration
+        conf: CertificateConfig = {
+            "common_name": common_name,
+            "organization": organization_name,
+            "alt_names": alt_names or ["localhost"],
+            "key_type": gen_key_type,
+            "not_valid_before": not_valid_before,
+            "not_valid_after": not_valid_after,
+        }
+        if gen_curve is not None:
+            conf["curve"] = gen_curve
+        if gen_key_size is not None:
+            conf["key_size"] = gen_key_size
+        logger.debug(f"📜🔑🚀 Generation config: {conf}")
+        
+        # Generate base certificate and private key
+        base, private_key = CertificateBase.create(conf)
+        
+        # Create X.509 certificate
+        x509_cert = create_x509_certificate(
+            base=base,
+            private_key=private_key,
+            alt_names=alt_names or ["localhost"],
+            is_ca=is_ca,
+            is_client_cert=is_client_cert,
+        )
+        
+        if x509_cert is None:
+            raise CertificateError(
+                "Certificate object (_cert) is None after creation"
+            )
+        
+        # Convert to PEM format
+        cert_pem = x509_cert.public_bytes(serialization.Encoding.PEM).decode("utf-8")
+        key_pem = private_key.private_bytes(
+            encoding=serialization.Encoding.PEM,
+            format=serialization.PrivateFormat.PKCS8,
+            encryption_algorithm=serialization.NoEncryption(),
+        ).decode("utf-8")
+        
+        logger.debug("📜🔑✅ Generated cert and key")
+        
+        return base, x509_cert, private_key, cert_pem, key_pem
+        
+    except Exception as e:
+        logger.error(
+            f"📜❌ Failed to generate certificate. Error: {type(e).__name__}: {e}",
+            extra={"error": str(e), "trace": traceback.format_exc()},
+        )
+        raise CertificateError(
+            f"Failed to initialize certificate. Original error: {type(e).__name__}"
+        ) from e