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

provide/foundation/crypto/certificates.py

@@ -0,0 +1,896 @@
+"""X.509 certificate generation and management."""
+
+from datetime import UTC, datetime, timedelta
+from enum import StrEnum, auto
+from functools import cached_property
+import os
+from pathlib import Path
+import traceback
+from typing import NotRequired, Self, TypeAlias, TypedDict, cast
+
+from attrs import Factory, define, field
+
+try:
+    from cryptography import x509
+    from cryptography.hazmat.backends import default_backend
+    from cryptography.hazmat.primitives import hashes, serialization
+    from cryptography.hazmat.primitives.asymmetric import ec, padding, rsa
+    from cryptography.hazmat.primitives.serialization import load_pem_private_key
+    from cryptography.x509 import Certificate as X509Certificate
+    from cryptography.x509.oid import ExtendedKeyUsageOID, NameOID
+
+    _HAS_CRYPTO = True
+except ImportError:
+    # Stub out cryptography types for type hints
+    x509 = None
+    default_backend = None
+    hashes = None
+    serialization = None
+    ec = None
+    padding = None
+    rsa = None
+    load_pem_private_key = None
+    X509Certificate = None
+    ExtendedKeyUsageOID = None
+    NameOID = None
+    _HAS_CRYPTO = False
+
+from provide.foundation import logger
+from provide.foundation.crypto.constants import (
+    DEFAULT_CERTIFICATE_CURVE,
+    DEFAULT_CERTIFICATE_KEY_TYPE,
+    DEFAULT_CERTIFICATE_VALIDITY_DAYS,
+    DEFAULT_RSA_KEY_SIZE,
+)
+from provide.foundation.errors.config import ValidationError
+
+
+def _require_crypto():
+    """Ensure cryptography is available for crypto operations."""
+    if not _HAS_CRYPTO:
+        raise ImportError(
+            "Cryptography features require optional dependencies. Install with: "
+            "pip install 'provide-foundation[crypto]'"
+        )
+
+
+class CertificateError(ValidationError):
+    """Certificate-related errors."""
+
+    def __init__(self, message: str, hint: str | None = None) -> None:
+        super().__init__(
+            message=message,
+            field="certificate",
+            value=None,
+            rule=hint or "Certificate operation failed",
+        )
+
+
+class KeyType(StrEnum):
+    RSA = auto()
+    ECDSA = auto()
+
+
+class CurveType(StrEnum):
+    SECP256R1 = auto()
+    SECP384R1 = auto()
+    SECP521R1 = auto()
+
+
+class CertificateConfig(TypedDict):
+    common_name: str
+    organization: str
+    alt_names: list[str]
+    key_type: KeyType
+    not_valid_before: datetime
+    not_valid_after: datetime
+    # Optional key generation parameters
+    key_size: NotRequired[int]
+    curve: NotRequired[CurveType]
+
+
+if _HAS_CRYPTO:
+    KeyPair: TypeAlias = rsa.RSAPrivateKey | ec.EllipticCurvePrivateKey
+    PublicKey: TypeAlias = rsa.RSAPublicKey | ec.EllipticCurvePublicKey
+else:
+    KeyPair: TypeAlias = None
+    PublicKey: TypeAlias = None
+
+
+@define(slots=True, frozen=True)
+class CertificateBase:
+    """Immutable base certificate data."""
+
+    subject: "x509.Name"
+    issuer: "x509.Name"
+    public_key: "PublicKey"
+    not_valid_before: datetime
+    not_valid_after: datetime
+    serial_number: int
+
+    @classmethod
+    def create(cls, config: CertificateConfig) -> tuple[Self, "KeyPair"]:
+        """Create a new certificate base and private key."""
+        _require_crypto()
+        try:
+            logger.debug("📜📝🚀 CertificateBase.create: Starting base creation")
+            not_valid_before = config["not_valid_before"]
+            not_valid_after = config["not_valid_after"]
+
+            if not_valid_before.tzinfo is None:
+                not_valid_before = not_valid_before.replace(tzinfo=UTC)
+            if not_valid_after.tzinfo is None:
+                not_valid_after = not_valid_after.replace(tzinfo=UTC)
+
+            logger.debug(
+                f"📜⏳✅ CertificateBase.create: Using validity: "
+                f"{not_valid_before} to {not_valid_after}"
+            )
+
+            private_key: KeyPair
+            match config["key_type"]:
+                case KeyType.RSA:
+                    key_size = config.get("key_size", DEFAULT_RSA_KEY_SIZE)
+                    logger.debug(f"📜🔑🚀 Generating RSA key (size: {key_size})")
+                    private_key = rsa.generate_private_key(
+                        public_exponent=65537, key_size=key_size
+                    )
+                case KeyType.ECDSA:
+                    curve_choice = config.get("curve", CurveType.SECP384R1)
+                    logger.debug(f"📜🔑🚀 Generating ECDSA key (curve: {curve_choice})")
+                    curve = getattr(ec, curve_choice.name)()
+                    private_key = ec.generate_private_key(curve)
+                case _:
+                    raise ValueError(
+                        f"Internal Error: Unsupported key type: {config['key_type']}"
+                    )
+
+            subject = cls._create_name(config["common_name"], config["organization"])
+            issuer = cls._create_name(config["common_name"], config["organization"])
+
+            serial_number = x509.random_serial_number()
+            logger.debug(f"📜🔑✅ Generated serial number: {serial_number}")
+
+            base = cls(
+                subject=subject,
+                issuer=issuer,
+                public_key=private_key.public_key(),
+                not_valid_before=not_valid_before,
+                not_valid_after=not_valid_after,
+                serial_number=serial_number,
+            )
+            logger.debug("📜📝✅ CertificateBase.create: Base creation complete")
+            return base, private_key
+
+        except Exception as e:
+            logger.error(
+                f"📜❌ CertificateBase.create: Failed: {e}",
+                extra={"error": str(e), "trace": traceback.format_exc()},
+            )
+            raise CertificateError(f"Failed to generate certificate base: {e}") from e
+
+    @staticmethod
+    def _create_name(common_name: str, org: str) -> "x509.Name":
+        """Helper method to construct an X.509 name."""
+        return x509.Name(
+            [
+                x509.NameAttribute(NameOID.COMMON_NAME, common_name),
+                x509.NameAttribute(NameOID.ORGANIZATION_NAME, org),
+            ]
+        )
+
+
+@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."""
+        try:
+            if self.generate_keypair:
+                logger.debug(
+                    "📜🔑🚀 Certificate.__attrs_post_init__: Generating new keypair"
+                )
+
+                now = datetime.now(UTC)
+                not_valid_before = now - timedelta(days=1)
+                not_valid_after = now + timedelta(days=self.validity_days)
+
+                normalized_key_type_str = self.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: '{self.key_type}'. "
+                            "Must be 'rsa' or 'ecdsa'."
+                        )
+
+                gen_curve: CurveType | None = None
+                gen_key_size = None
+
+                if gen_key_type == KeyType.ECDSA:
+                    try:
+                        gen_curve = CurveType[self.ecdsa_curve.upper()]
+                    except KeyError as e_curve:
+                        raise ValueError(
+                            f"Unsupported ECDSA curve: {self.ecdsa_curve}"
+                        ) from e_curve
+                else:  # RSA
+                    gen_key_size = self.key_size
+
+                conf: CertificateConfig = {
+                    "common_name": self.common_name,
+                    "organization": self.organization_name,
+                    "alt_names": self.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}")
+
+                self._base, self._private_key = CertificateBase.create(conf)
+
+                self._cert = self._create_x509_certificate(
+                    is_ca=False,
+                    is_client_cert=True,
+                )
+
+                if self._cert is None:
+                    raise CertificateError(
+                        "Certificate object (_cert) is None after creation"
+                    )
+
+                self.cert = self._cert.public_bytes(serialization.Encoding.PEM).decode(
+                    "utf-8"
+                )
+                if self._private_key:
+                    self.key = self._private_key.private_bytes(
+                        encoding=serialization.Encoding.PEM,
+                        format=serialization.PrivateFormat.PKCS8,
+                        encryption_algorithm=serialization.NoEncryption(),
+                    ).decode("utf-8")
+                else:
+                    self.key = None
+
+                logger.debug(
+                    "📜🔑✅ Certificate.__attrs_post_init__: Generated cert and key"
+                )
+
+            else:
+                if not self.cert_pem_or_uri:
+                    raise CertificateError(
+                        "cert_pem_or_uri required when not generating"
+                    )
+
+                logger.debug("📜🔑🚀 Loading certificate from provided data")
+                cert_data = self._load_from_uri_or_pem(self.cert_pem_or_uri)
+                self.cert = cert_data
+
+                logger.debug("📜🔑🔍 Loading X.509 certificate from PEM data")
+                self._cert = x509.load_pem_x509_certificate(cert_data.encode("utf-8"))
+                logger.debug("📜🔑✅ X.509 certificate object loaded from PEM")
+
+                if self.key_pem_or_uri:
+                    logger.debug("📜🔑🚀 Loading private key")
+                    key_data = self._load_from_uri_or_pem(self.key_pem_or_uri)
+                    self.key = key_data
+
+                    loaded_priv_key = load_pem_private_key(
+                        key_data.encode("utf-8"), password=None
+                    )
+                    if not isinstance(
+                        loaded_priv_key,
+                        rsa.RSAPrivateKey | ec.EllipticCurvePrivateKey,
+                    ):
+                        raise CertificateError(
+                            f"Loaded private key is of unsupported type: {type(loaded_priv_key)}. "
+                            "Expected RSA or ECDSA private key."
+                        )
+                    self._private_key = loaded_priv_key
+                    logger.debug("📜🔑✅ Private key object loaded and type validated")
+                else:
+                    self.key = None
+
+                loaded_not_valid_before = self._cert.not_valid_before_utc
+                loaded_not_valid_after = self._cert.not_valid_after_utc
+                if loaded_not_valid_before.tzinfo is None:
+                    loaded_not_valid_before = loaded_not_valid_before.replace(
+                        tzinfo=UTC
+                    )
+                if loaded_not_valid_after.tzinfo is None:
+                    loaded_not_valid_after = loaded_not_valid_after.replace(tzinfo=UTC)
+
+                cert_public_key = self._cert.public_key()
+                if not isinstance(
+                    cert_public_key, rsa.RSAPublicKey | ec.EllipticCurvePublicKey
+                ):
+                    raise CertificateError(
+                        f"Certificate's public key is of unsupported type: {type(cert_public_key)}. "
+                        "Expected RSA or ECDSA public key."
+                    )
+
+                self._base = CertificateBase(
+                    subject=self._cert.subject,
+                    issuer=self._cert.issuer,
+                    public_key=cert_public_key,
+                    not_valid_before=loaded_not_valid_before,
+                    not_valid_after=loaded_not_valid_after,
+                    serial_number=self._cert.serial_number,
+                )
+                logger.debug("📜🔑✅ Reconstructed CertificateBase from loaded cert")
+
+        except Exception as e:
+            logger.error(
+                f"📜❌ Certificate.__attrs_post_init__: Failed. 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
+
+    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."""
+        if not hasattr(self, "_base"):
+            raise CertificateError("Cannot create certificate without base information")
+
+        try:
+            logger.debug("📜📝🚀 _create_x509_certificate: Building certificate")
+
+            actual_issuer_name = (
+                issuer_name_override if issuer_name_override else self._base.issuer
+            )
+            actual_signing_key = (
+                signing_key_override if signing_key_override else self._private_key
+            )
+
+            if not actual_signing_key:
+                raise CertificateError(
+                    "Cannot sign certificate without a signing key (either own or override)"
+                )
+
+            builder = (
+                x509.CertificateBuilder()
+                .subject_name(self._base.subject)
+                .issuer_name(actual_issuer_name)
+                .public_key(self._base.public_key)
+                .serial_number(self._base.serial_number)
+                .not_valid_before(self._base.not_valid_before)
+                .not_valid_after(self._base.not_valid_after)
+            )
+
+            san_list = [x509.DNSName(name) for name in (self.alt_names or []) if name]
+            if san_list:
+                builder = builder.add_extension(
+                    x509.SubjectAlternativeName(san_list), critical=False
+                )
+                logger.debug(f"📜📝✅ Added SANs: {self.alt_names or []}")
+
+            builder = builder.add_extension(
+                x509.BasicConstraints(ca=is_ca, path_length=None),
+                critical=True,
+            )
+
+            if is_ca:
+                builder = builder.add_extension(
+                    x509.KeyUsage(
+                        digital_signature=False,
+                        key_encipherment=False,
+                        key_agreement=False,
+                        content_commitment=False,
+                        data_encipherment=False,
+                        key_cert_sign=True,
+                        crl_sign=True,
+                        encipher_only=False,
+                        decipher_only=False,
+                    ),
+                    critical=True,
+                )
+            else:
+                builder = builder.add_extension(
+                    x509.KeyUsage(
+                        digital_signature=True,
+                        key_encipherment=(
+                            True
+                            if not is_client_cert
+                            and isinstance(self._base.public_key, rsa.RSAPublicKey)
+                            else False
+                        ),
+                        key_agreement=(
+                            True
+                            if isinstance(
+                                self._base.public_key, ec.EllipticCurvePublicKey
+                            )
+                            else False
+                        ),
+                        content_commitment=False,
+                        data_encipherment=False,
+                        key_cert_sign=False,
+                        crl_sign=False,
+                        encipher_only=False,
+                        decipher_only=False,
+                    ),
+                    critical=True,
+                )
+                extended_usages = []
+                if is_client_cert:
+                    extended_usages.append(ExtendedKeyUsageOID.CLIENT_AUTH)
+                else:
+                    extended_usages.append(ExtendedKeyUsageOID.SERVER_AUTH)
+
+                if extended_usages:
+                    builder = builder.add_extension(
+                        x509.ExtendedKeyUsage(extended_usages),
+                        critical=False,
+                    )
+
+            logger.debug(
+                f"📜📝✅ Added BasicConstraints (is_ca={is_ca}), "
+                f"KeyUsage, ExtendedKeyUsage (is_client_cert={is_client_cert})"
+            )
+
+            signed_cert = builder.sign(
+                private_key=actual_signing_key,
+                algorithm=hashes.SHA256(),
+                backend=default_backend(),
+            )
+            logger.debug("📜📝✅ Certificate signed successfully")
+            return signed_cert
+
+        except Exception as e:
+            logger.error(
+                f"📜❌ _create_x509_certificate: Failed: {e}",
+                extra={"error": str(e), "trace": traceback.format_exc()},
+            )
+            raise CertificateError("Failed to create X.509 certificate object") from e
+
+    @staticmethod
+    def _load_from_uri_or_pem(data: str) -> str:
+        """Load PEM data either directly from a string or from a file URI."""
+        try:
+            if data.startswith("file://"):
+                path_str = data.removeprefix("file://")
+                if os.name == "nt" and path_str.startswith("//"):
+                    path = Path(path_str)
+                else:
+                    path_str = path_str.lstrip("/")
+                    if os.name != "nt" and data.startswith("file:///"):
+                        path_str = "/" + path_str
+                    path = Path(path_str)
+
+                logger.debug(f"📜📂🚀 Loading data from file: {path}")
+                with path.open("r", encoding="utf-8") as f:
+                    loaded_data = f.read().strip()
+                logger.debug("📜📂✅ Loaded data from file")
+                return loaded_data
+
+            loaded_data = data.strip()
+            if not loaded_data.startswith("-----BEGIN"):
+                logger.warning("📜📂⚠️ Data doesn't look like PEM format")
+            return loaded_data
+        except Exception as e:
+            logger.error(f"📜📂❌ Failed to load data: {e}", extra={"error": str(e)})
+            raise CertificateError(f"Failed to load data: {e}") from e
+
+    # 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
+
+    @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."""
+        logger.info(
+            f"📜🔑🏭 Creating new CA certificate: CN={common_name}, Org={organization_name}"
+        )
+        ca_cert_obj = cls(
+            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 = ca_cert_obj._create_x509_certificate(
+            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
+
+    @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."""
+        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 = cls(
+            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 = new_cert_obj._create_x509_certificate(
+            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
+
+    @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."""
+        logger.info(
+            f"📜🔑🏭 Creating new self-signed SERVER certificate: "
+            f"CN={common_name}, Org={organization_name}"
+        )
+
+        cert_obj = cls(
+            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 = cert_obj._create_x509_certificate(
+            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
+
+    def verify_trust(self, other_cert: Self) -> bool:
+        """Verifies if the `other_cert` is trusted based on this certificate's trust chain."""
+        if other_cert is None:
+            raise CertificateError("Cannot verify trust: other_cert is None")
+
+        logger.debug(
+            f"📜🔍🚀 Verifying trust for cert S/N {other_cert.serial_number} "
+            f"against chain of S/N {self.serial_number}"
+        )
+
+        if not other_cert.is_valid:
+            logger.debug(
+                "📜🔍⚠️ Trust verification failed: Other certificate is not valid"
+            )
+            return False
+        if not other_cert.public_key:
+            raise CertificateError(
+                "Cannot verify trust: Other certificate has no public key"
+            )
+
+        if self == other_cert:
+            logger.debug(
+                "📜🔍✅ Trust verified: Certificates are identical (based on subject/serial)"
+            )
+            return True
+
+        if other_cert in self._trust_chain:
+            logger.debug(
+                "📜🔍✅ Trust verified: Other certificate found in trust chain"
+            )
+            return True
+
+        for trusted_cert in self._trust_chain:
+            logger.debug(
+                f"📜🔍🔁 Checking signature against trusted cert S/N {trusted_cert.serial_number}"
+            )
+            if self._validate_signature(
+                signed_cert=other_cert, signing_cert=trusted_cert
+            ):
+                logger.debug(
+                    f"📜🔍✅ Trust verified: Other cert signed by trusted cert S/N "
+                    f"{trusted_cert.serial_number}"
+                )
+                return True
+
+        logger.debug(
+            "📜🔍❌ Trust verification failed: Other certificate not identical, "
+            "not in chain, and not signed by any cert in chain"
+        )
+        return False
+
+    def _validate_signature(
+        self, signed_cert: "Certificate", signing_cert: "Certificate"
+    ) -> bool:
+        """Internal helper: Validates signature and issuer/subject match."""
+        if not hasattr(signed_cert, "_cert") or not hasattr(signing_cert, "_cert"):
+            logger.error(
+                "📜🔍❌ Cannot validate signature: Certificate object(s) not initialized"
+            )
+            return False
+
+        if signed_cert._cert.issuer != signing_cert._cert.subject:
+            logger.debug(
+                f"📜🔍❌ Signature validation failed: Issuer/Subject mismatch. "
+                f"Signed Issuer='{signed_cert._cert.issuer}', "
+                f"Signing Subject='{signing_cert._cert.subject}'"
+            )
+            return False
+
+        try:
+            signing_public_key = signing_cert.public_key
+            if not signing_public_key:
+                logger.error(
+                    "📜🔍❌ Cannot validate signature: Signing certificate has no public key"
+                )
+                return False
+
+            signature = signed_cert._cert.signature
+            tbs_certificate_bytes = signed_cert._cert.tbs_certificate_bytes
+            signature_hash_algorithm = signed_cert._cert.signature_hash_algorithm
+
+            if not signature_hash_algorithm:
+                logger.error("📜🔍❌ Cannot validate signature: Unknown hash algorithm")
+                return False
+
+            if isinstance(signing_public_key, rsa.RSAPublicKey):
+                cast(rsa.RSAPublicKey, signing_public_key).verify(
+                    signature,
+                    tbs_certificate_bytes,
+                    padding.PKCS1v15(),
+                    signature_hash_algorithm,
+                )
+            elif isinstance(signing_public_key, ec.EllipticCurvePublicKey):
+                cast(ec.EllipticCurvePublicKey, signing_public_key).verify(
+                    signature,
+                    tbs_certificate_bytes,
+                    ec.ECDSA(signature_hash_algorithm),
+                )
+            else:
+                logger.error(
+                    f"📜🔍❌ Unsupported signing public key type: {type(signing_public_key)}"
+                )
+                return False
+
+            return True
+
+        except Exception as e:
+            logger.debug(f"📜🔍❌ Signature validation failed: {type(e).__name__}: {e}")
+            return False
+
+    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}')"
+        )
+
+
+# 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 Certificate.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 Certificate.create_ca(
+        common_name=common_name,
+        organization_name=organization,
+        validity_days=validity_days,
+        key_type=key_type,
+    )