_synta/

certificate.rs

//! Python bindings for X.509 and related PKI types.
//!
//! Exposes [`PyCertificate`], [`PyCsr`], [`PyCrl`], and [`PyOcspResponse`] as
//! pyo3 classes, along with OID-lookup helper functions and the
//! ``synta.oids`` / ``synta.oids.attr`` submodules.
//!
//! This module is part of the `synta-python` cdylib.  Call [`register_module`]
//! from the `#[pymodule]` entry point to expose these types to Python.

use std::str::FromStr;
use std::sync::OnceLock;

use pyo3::prelude::*;
use pyo3::types::{PyBytes, PyList, PyString};
use pyo3::PyClass;

use synta::traits::Encode;
use synta::{Decoder, Encoding, ObjectIdentifier};
use synta_certificate::{Certificate, Time};

use crate::types::PyObjectIdentifier;

/// Re-encode an ASN.1 `Element` to DER bytes, returning `None` for a missing
/// optional field.  Used by the algorithm-parameter getters.
fn encode_element_opt<'py>(
    py: Python<'py>,
    elem: Option<&synta::Element<'_>>,
) -> PyResult<Option<Bound<'py, PyBytes>>> {
    match elem {
        None => Ok(None),
        Some(e) => {
            let mut encoder = synta::Encoder::new(Encoding::Der);
            e.encode(&mut encoder)
                .map_err(|err| pyo3::exceptions::PyValueError::new_err(format!("{err}")))?;
            let bytes = encoder
                .finish()
                .map_err(|err| pyo3::exceptions::PyValueError::new_err(format!("{err}")))?;
            Ok(Some(PyBytes::new(py, &bytes)))
        }
    }
}

/// Decode a raw DER Name SEQUENCE and format it as an RFC 4514-style string.
fn decode_name_debug(raw: &[u8]) -> String {
    synta_certificate::name::format_dn(raw)
}

/// Accept either a Python ``str`` (dotted-decimal OID) or an
/// ``ObjectIdentifier`` object and return the underlying Rust value.
fn oid_from_pyany(obj: &Bound<'_, PyAny>) -> PyResult<ObjectIdentifier> {
    if let Ok(oid_ref) = obj.extract::<PyRef<PyObjectIdentifier>>() {
        return Ok(oid_ref.inner.clone());
    }
    if let Ok(s) = obj.extract::<String>() {
        return ObjectIdentifier::from_str(&s)
            .map_err(|_| pyo3::exceptions::PyValueError::new_err(format!("invalid OID: {s}")));
    }
    Err(pyo3::exceptions::PyTypeError::new_err(
        "oid must be a str or ObjectIdentifier",
    ))
}

/// Shared implementation for every `from_pem` static method.
///
/// Decodes all PEM blocks in `data` and constructs a Python object for each
/// by calling `make_obj(py, der_bytes)`.  The closure is responsible for
/// parsing the DER bytes and wrapping the result as a `Bound<'py, PyAny>`;
/// this lets the caller use concrete types (with their full `Py::new` bounds)
/// without any generic `PyClass` constraint here.
///
/// Returns a single object for one block, a `list` for multiple blocks, and
/// raises `ValueError` when no block is found.
fn pem_blocks_to_pyobject<'py, F>(
    py: Python<'py>,
    data: &[u8],
    make_obj: F,
) -> PyResult<Bound<'py, PyAny>>
where
    F: for<'a> Fn(Python<'py>, Bound<'a, PyBytes>) -> PyResult<Bound<'py, PyAny>>,
{
    let blocks = synta_certificate::pem_blocks(data);
    match blocks.len() {
        0 => Err(pyo3::exceptions::PyValueError::new_err(
            "no PEM block found in input",
        )),
        1 => make_obj(py, PyBytes::new(py, &blocks[0].1)),
        _ => {
            let list = PyList::empty(py);
            for (_, der) in &blocks {
                list.append(make_obj(py, PyBytes::new(py, der))?)?;
            }
            Ok(list.into_any())
        }
    }
}

/// Shared implementation for every `to_pem` static method.
///
/// Accepts either a single Python object of type `T` or a `list` of them,
/// serialises each to a PEM block labelled `label`, and returns the
/// concatenated bytes.  The `get_der` closure extracts the raw DER bytes from
/// a Rust reference to `T`.
///
/// Using a closure (rather than a trait method) avoids requiring `T: PyClass`
/// with internal PyO3 initialiser bounds while still letting the caller use
/// concrete types.
fn pyobject_to_pem<'py, T, D>(
    py: Python<'py>,
    label: &str,
    obj_or_list: &Bound<'_, PyAny>,
    get_der: D,
) -> PyResult<Bound<'py, PyBytes>>
where
    T: PyClass,
    D: for<'r> Fn(&'r T) -> &'r [u8],
{
    let mut pem: Vec<u8> = Vec::new();
    if let Ok(list) = obj_or_list.cast::<PyList>() {
        for item in list.iter() {
            let bound_t = item.cast::<T>().map_err(|_| {
                pyo3::exceptions::PyTypeError::new_err(format!(
                    "list items must be {label} objects"
                ))
            })?;
            let borrow = bound_t.borrow();
            pem.extend_from_slice(&synta_certificate::der_to_pem(label, get_der(&borrow)));
        }
    } else {
        let bound_t = obj_or_list.cast::<T>().map_err(|_| {
            pyo3::exceptions::PyTypeError::new_err(format!(
                "expected a {label} object or list[{label}]"
            ))
        })?;
        let borrow = bound_t.borrow();
        pem.extend_from_slice(&synta_certificate::der_to_pem(label, get_der(&borrow)));
    }
    Ok(PyBytes::new(py, &pem))
}

/// X.509 Certificate accessible from Python.
///
/// Example (inside a Python extension that called `register_module`):
///
/// ```python
/// cert = Certificate.from_der(open("cert.der", "rb").read())
/// print(cert.subject)
/// ```
#[pyclass(frozen, name = "Certificate")]
pub struct PyCertificate {
    // Holds a strong reference to the Python bytes object that backs the
    // DER data.  The CPython refcount prevents the underlying bytes buffer
    // from being freed for the full lifetime of this struct.  After the
    // struct is collected by Python's GC, `_data` drops (in Rust's
    // declaration order) and decrements the refcount; by that point no
    // Rust code can hold a borrow of this struct, so no read of `raw`
    // can occur through `&self` after drop begins.
    _data: Py<PyBytes>,
    // Raw slice pointing into `_data`'s buffer.  SAFETY: valid as long as
    // `_data` is alive; CPython bytes objects have a fixed-address buffer
    // that is never relocated.  Stored here so the OnceLock init closure in
    // `cert()` can access the bytes without requiring a GIL token.
    raw: &'static [u8],
    // Full decoded certificate, heap-allocated and initialised lazily on first
    // field access.  `Box` keeps the 568-byte `Certificate` off the struct so
    // that `PyCertificate` stays within CPython's 512-byte `pymalloc`
    // threshold (after adding the Python object header).  Allocating through
    // pymalloc instead of the system allocator is roughly 3× faster, which is
    // measurable at parse-only speeds.  The full recursive decode is deferred
    // so that parse-only workloads pay only the shallow envelope-scan cost.
    inner: OnceLock<Box<Certificate<'static>>>,
    // Byte range within `_data` covering the complete TBSCertificate TLV.
    tbs_range: std::ops::Range<usize>,
    // Lazily-computed Python objects.  Each field is initialised on first
    // Python access and returned via clone_ref on every subsequent call,
    // avoiding repeated allocation and PyO3 string construction.
    issuer_cache: OnceLock<Py<PyString>>,
    subject_cache: OnceLock<Py<PyString>>,
    signature_algorithm_cache: OnceLock<Py<PyString>>,
    not_before_cache: OnceLock<Py<PyString>>,
    not_after_cache: OnceLock<Py<PyString>>,
    public_key_algorithm_cache: OnceLock<Py<PyString>>,
    serial_number_cache: OnceLock<Py<PyAny>>,
    signature_value_cache: OnceLock<Py<PyBytes>>,
    public_key_cache: OnceLock<Py<PyBytes>>,
    tbs_bytes_cache: OnceLock<Py<PyBytes>>,
    signature_algorithm_oid_cache: OnceLock<Py<PyObjectIdentifier>>,
    public_key_algorithm_oid_cache: OnceLock<Py<PyObjectIdentifier>>,
    signature_algorithm_params_cache: OnceLock<Option<Py<PyBytes>>>,
    public_key_algorithm_params_cache: OnceLock<Option<Py<PyBytes>>>,
    extensions_der_cache: OnceLock<Option<Py<PyBytes>>>,
    issuer_raw_der_cache: OnceLock<Py<PyBytes>>,
    subject_raw_der_cache: OnceLock<Py<PyBytes>>,
}

impl PyCertificate {
    /// Return the fully-decoded certificate, triggering a full recursive
    /// `Certificate::decode()` on the first call.
    ///
    /// The result is cached in `inner` so subsequent calls are a single
    /// atomic load.  Returns `Err(PyValueError)` if the full decode fails
    /// (e.g. malformed inner content that passed the shallow envelope scan
    /// in `from_der`).  Unlike a panic, this surfaces as a catchable Python
    /// `ValueError` rather than an uncatchable `PanicException`.
    fn cert(&self) -> PyResult<&Certificate<'static>> {
        if let Some(v) = self.inner.get() {
            return Ok(v.as_ref());
        }
        let mut decoder = Decoder::new(self.raw, Encoding::Der);
        let decoded = decoder.decode().map_err(|e| {
            pyo3::exceptions::PyValueError::new_err(format!("Certificate DER decode failed: {e}"))
        })?;
        let _ = self.inner.set(Box::new(decoded));
        Ok(self.inner.get().unwrap().as_ref())
    }
}

#[pymethods]
impl PyCertificate {
    /// Parse a DER-encoded X.509 certificate.
    #[staticmethod]
    fn from_der(py: Python<'_>, data: Bound<'_, PyBytes>) -> PyResult<Self> {
        // Store the Python bytes object directly — no copy of the DER data.
        let py_bytes = data.unbind();

        // SAFETY: `py_bytes` holds a strong reference (Py<PyBytes>) that
        // keeps the Python bytes object alive for the lifetime of this struct.
        // CPython's bytes objects have a fixed-address, non-relocating payload
        // buffer (CPython has no moving GC for bytes objects).  The slice
        // lifetime is extended to 'static; the actual safety invariants are:
        //   (1) All reads of `raw` go through `&self` (a borrow of the struct).
        //       No borrow of the struct can outlive the struct, so `raw` is
        //       never read after the struct begins dropping.
        //   (2) `raw: &'static [u8]` has no destructor (it is a fat pointer
        //       with no heap allocation), so Rust dropping `_data` before `raw`
        //       (fields drop in declaration order) does not cause a
        //       use-after-free during the drop sequence itself.
        //   (3) `inner` contains `Certificate<'static>` references into the
        //       buffer; dropping `Box<Certificate<'static>>` frees the box
        //       allocation but does not read through the contained &'static
        //       slices (borrows have no destructors in Rust).
        // CPython-only: this pattern does not hold for PyPy or GraalPy,
        // which may relocate or compact heap objects.
        let raw: &'static [u8] = unsafe {
            let s = py_bytes.bind(py).as_bytes();
            std::slice::from_raw_parts(s.as_ptr(), s.len())
        };

        // Shallow structural scan: validate the Certificate SEQUENCE envelope
        // and locate the TBSCertificate TLV range.  This is ~4 decoder
        // operations — roughly 10× faster than a full Certificate::decode().
        // The full decode is deferred to the first field access via `cert()`.
        //
        // Certificate ::= SEQUENCE {
        //     tbsCertificate   TBSCertificate,   -- child 0: SEQUENCE
        //     signatureAlgorithm AlgorithmIdentifier, -- child 1: SEQUENCE
        //     signature        BIT STRING            -- child 2
        // }
        let tbs_range = {
            let mut d = Decoder::new(raw, Encoding::Der);
            // Outer Certificate SEQUENCE tag + length.
            d.read_tag()
                .map_err(|e| pyo3::exceptions::PyValueError::new_err(format!("{e}")))?;
            d.read_length()
                .map_err(|e| pyo3::exceptions::PyValueError::new_err(format!("{e}")))?;
            // TBSCertificate: record the full TLV range (tag + length + content).
            let tbs_start = d.position();
            d.read_tag()
                .map_err(|e| pyo3::exceptions::PyValueError::new_err(format!("{e}")))?;
            let tbs_len = d
                .read_length()
                .map_err(|e| pyo3::exceptions::PyValueError::new_err(format!("{e}")))?;
            let tbs_content_len = tbs_len
                .definite()
                .map_err(|e| pyo3::exceptions::PyValueError::new_err(format!("{e}")))?;
            tbs_start..(d.position() + tbs_content_len)
        };

        Ok(Self {
            _data: py_bytes,
            raw,
            inner: OnceLock::new(),
            tbs_range,
            issuer_cache: OnceLock::new(),
            subject_cache: OnceLock::new(),
            signature_algorithm_cache: OnceLock::new(),
            not_before_cache: OnceLock::new(),
            not_after_cache: OnceLock::new(),
            public_key_algorithm_cache: OnceLock::new(),
            serial_number_cache: OnceLock::new(),
            signature_value_cache: OnceLock::new(),
            public_key_cache: OnceLock::new(),
            tbs_bytes_cache: OnceLock::new(),
            signature_algorithm_oid_cache: OnceLock::new(),
            public_key_algorithm_oid_cache: OnceLock::new(),
            signature_algorithm_params_cache: OnceLock::new(),
            public_key_algorithm_params_cache: OnceLock::new(),
            extensions_der_cache: OnceLock::new(),
            issuer_raw_der_cache: OnceLock::new(),
            subject_raw_der_cache: OnceLock::new(),
        })
    }

    /// Parse a DER-encoded X.509 certificate and perform a full RFC 5280 decode immediately.
    ///
    /// Unlike :meth:`from_der`, which performs only a shallow 4-operation
    /// envelope scan and defers the full :class:`Certificate` decode to the
    /// first field access, this method triggers the complete recursive
    /// ``Certificate::decode()`` at construction time.
    ///
    /// Use this when you need all fields to be available without any
    /// lazy-decode latency on the first getter call, or when benchmarking the
    /// true full-parse cost that is comparable to Criterion's ``rust_typed``
    /// numbers.
    ///
    /// ```python
    /// # Full parse happens here — no deferred work on first field access.
    /// cert = Certificate.full_from_der(der)
    /// print(cert.issuer)   # warm path only
    /// ```
    #[staticmethod]
    fn full_from_der(py: Python<'_>, data: Bound<'_, PyBytes>) -> PyResult<Self> {
        let cert = Self::from_der(py, data)?;
        // Prime the OnceLock: runs the full Certificate::decode() now.
        cert.cert()?;
        Ok(cert)
    }

    /// Parse a PEM-encoded X.509 certificate.
    ///
    /// Strips the ``-----BEGIN CERTIFICATE-----`` / ``-----END CERTIFICATE-----``
    /// boundary lines, decodes the base64 body, and calls :meth:`from_der`.
    /// No external dependencies are required — the decoder is implemented in
    /// pure Rust inside ``synta-certificate``.
    ///
    /// Returns a single :class:`Certificate` when the input contains exactly
    /// one PEM block.  When multiple blocks are present (e.g. a certificate
    /// chain file), returns a :class:`list` of :class:`Certificate` objects in
    /// the order they appear.  Raises :exc:`ValueError` if no PEM block is
    /// found.
    ///
    /// ```python
    /// # Single certificate — returns Certificate directly.
    /// cert = Certificate.from_pem(open("cert.pem", "rb").read())
    /// print(cert.subject)
    ///
    /// # Certificate chain — returns list[Certificate].
    /// chain = Certificate.from_pem(open("chain.pem", "rb").read())
    /// for cert in chain:
    ///     print(cert.subject)
    /// ```
    #[staticmethod]
    fn from_pem<'py>(py: Python<'py>, data: Bound<'_, PyBytes>) -> PyResult<Bound<'py, PyAny>> {
        pem_blocks_to_pyobject(py, data.as_bytes(), |py, bytes| {
            let obj = Self::from_der(py, bytes)?;
            Ok(Py::new(py, obj)?.into_bound(py).into_any())
        })
    }

    /// Convert to a ``cryptography.x509.Certificate`` (PyCA) object.
    ///
    /// Passes the original DER bytes directly to
    /// ``cryptography.x509.load_der_x509_certificate``; no re-encoding is
    /// performed.  Requires the ``cryptography`` package to be installed.
    ///
    /// ```python
    /// synta_cert = synta.Certificate.from_der(der)
    /// pyca_cert  = synta_cert.to_pyca()
    /// # Full cryptographic operations are now available via PyCA:
    /// pyca_cert.public_key().verify(signature, message, ...)
    /// ```
    fn to_pyca<'py>(&self, py: Python<'py>) -> PyResult<Bound<'py, PyAny>> {
        let m = py.import("cryptography.x509").map_err(|_| {
            pyo3::exceptions::PyImportError::new_err(
                "the 'cryptography' package is required; install it with: pip install cryptography",
            )
        })?;
        m.call_method1(
            "load_der_x509_certificate",
            (self._data.clone_ref(py).into_bound(py),),
        )
    }

    /// Construct a ``Certificate`` from a ``cryptography.x509.Certificate``.
    ///
    /// Serialises the PyCA certificate to DER via
    /// ``cert.public_bytes(Encoding.DER)`` and parses the result with
    /// :meth:`from_der`.  Requires the ``cryptography`` package to be
    /// installed.
    ///
    /// **Fast path** — if the object exposes a ``_synta_der_bytes`` attribute
    /// whose value is a ``bytes`` object, that buffer is used directly and
    /// the ``public_bytes()`` call is skipped entirely.  Wrapper classes that
    /// already hold the raw DER (e.g. an ``IPACertificate`` loaded from LDAP)
    /// can opt in by setting the attribute at construction time:
    ///
    /// ```python
    /// class IPACertificate:
    ///     def __init__(self, der: bytes):
    ///         self._synta_der_bytes = der          # enables fast path
    ///         self._pyca = x509.load_der_x509_certificate(der)
    ///
    /// # Zero re-encoding cost — DER is read from _synta_der_bytes directly:
    /// synta_cert = synta.Certificate.from_pyca(ipa_cert)
    /// ```
    ///
    /// Without the attribute the standard path is used:
    ///
    /// ```python
    /// pyca_cert  = cryptography.x509.load_pem_x509_certificate(pem)
    /// synta_cert = synta.Certificate.from_pyca(pyca_cert)
    /// ```
    #[staticmethod]
    fn from_pyca(py: Python<'_>, pyca_cert: Bound<'_, PyAny>) -> PyResult<Self> {
        // Optional fast path: if the caller has cached raw DER bytes on the
        // object under the `_synta_der_bytes` attribute, use that directly to
        // avoid the re-encoding cost of `public_bytes(Encoding.DER)`.  This
        // lets wrappers like FreeIPA's `IPACertificate` opt in by setting
        // `self._synta_der_bytes = der` at construction time.
        if let Ok(attr) = pyca_cert.getattr("_synta_der_bytes") {
            if let Ok(der_bytes) = attr.cast_into::<PyBytes>() {
                return Self::from_der(py, der_bytes);
            }
        }

        let ser = py
            .import("cryptography.hazmat.primitives.serialization")
            .map_err(|_| {
                pyo3::exceptions::PyImportError::new_err(
                    "the 'cryptography' package is required; install it with: pip install cryptography",
                )
            })?;
        let der_bytes: Bound<'_, PyBytes> = pyca_cert
            .call_method1("public_bytes", (ser.getattr("Encoding")?.getattr("DER")?,))?
            .cast_into()?;
        Self::from_der(py, der_bytes)
    }

    /// Serialize one certificate or a list of certificates to PEM format.
    ///
    /// The mirror of :meth:`from_pem`: accepts either a single
    /// :class:`Certificate` or a :class:`list` of them, and returns a
    /// :class:`bytes` value containing one or more
    /// ``-----BEGIN CERTIFICATE-----`` blocks concatenated in order.
    ///
    /// ```python
    /// # Single certificate:
    /// pem = Certificate.to_pem(cert)
    /// open("cert.pem", "wb").write(pem)
    ///
    /// # Certificate chain:
    /// pem = Certificate.to_pem([leaf, intermediate, root])
    /// open("chain.pem", "wb").write(pem)
    /// ```
    #[staticmethod]
    fn to_pem<'py>(
        py: Python<'py>,
        obj_or_list: Bound<'_, PyAny>,
    ) -> PyResult<Bound<'py, PyBytes>> {
        pyobject_to_pem::<Self, _>(py, "CERTIFICATE", &obj_or_list, |c| c.raw)
    }

    /// Serial number as a Python int.
    ///
    /// Returns a native Python `int` regardless of size (X.509 serials can be
    /// up to 20 bytes / 160 bits per RFC 5280).  The Python object is created
    /// once and cached; subsequent accesses return a reference to the same object.
    #[getter]
    fn serial_number<'py>(&self, py: Python<'py>) -> PyResult<Bound<'py, PyAny>> {
        // `get_or_try_init` is not stable on `OnceLock`, so build the value
        // outside the lock if the cache is empty, then store it.
        if let Some(cached) = self.serial_number_cache.get() {
            return Ok(cached.clone_ref(py).into_bound(py));
        }
        let serial = &self.cert()?.tbs_certificate.serial_number;
        let py_int: Py<PyAny> = if let Ok(v) = serial.as_i64() {
            // Fast path: fits in i64 (covers traditional short serials)
            v.into_pyobject(py)?.into_any().unbind()
        } else if let Ok(v) = serial.as_i128() {
            // Fits in i128 (covers up to 16-byte random serials)
            v.into_pyobject(py)?.into_any().unbind()
        } else {
            // Large serial (17–20 bytes): call int.from_bytes() directly.
            // Using call_method avoids the parse+compile overhead of py.eval()
            // on every cold-path invocation.  `signed` is keyword-only in
            // Python's int.from_bytes signature, so it must go in kwargs.
            let bytes_obj = PyBytes::new(py, serial.as_bytes());
            let kwargs = pyo3::types::PyDict::new(py);
            kwargs.set_item(pyo3::intern!(py, "signed"), true)?;
            py.get_type::<pyo3::types::PyInt>()
                .call_method(
                    pyo3::intern!(py, "from_bytes"),
                    (bytes_obj, pyo3::intern!(py, "big")),
                    Some(&kwargs),
                )
                .map(|r| r.unbind())?
        };
        // Ignore a racing writer; both produce the same value.
        let _ = self.serial_number_cache.set(py_int.clone_ref(py));
        Ok(py_int.into_bound(py))
    }

    /// Issuer distinguished name as a string.
    #[getter]
    fn issuer<'py>(&self, py: Python<'py>) -> PyResult<Bound<'py, PyString>> {
        if let Some(cached) = self.issuer_cache.get() {
            return Ok(cached.clone_ref(py).into_bound(py));
        }
        let s = decode_name_debug(self.cert()?.tbs_certificate.issuer.as_bytes());
        let py_str = PyString::new(py, &s).unbind();
        let _ = self.issuer_cache.set(py_str.clone_ref(py));
        Ok(py_str.into_bound(py))
    }

    /// Subject distinguished name as a string.
    #[getter]
    fn subject<'py>(&self, py: Python<'py>) -> PyResult<Bound<'py, PyString>> {
        if let Some(cached) = self.subject_cache.get() {
            return Ok(cached.clone_ref(py).into_bound(py));
        }
        let s = decode_name_debug(self.cert()?.tbs_certificate.subject.as_bytes());
        let py_str = PyString::new(py, &s).unbind();
        let _ = self.subject_cache.set(py_str.clone_ref(py));
        Ok(py_str.into_bound(py))
    }

    /// Signature algorithm name (e.g. "RSA", "ECDSA", "Ed25519", "ML-DSA-65"),
    /// or the dotted OID notation for unrecognized algorithms.
    #[getter]
    fn signature_algorithm<'py>(&self, py: Python<'py>) -> PyResult<Bound<'py, PyString>> {
        if let Some(cached) = self.signature_algorithm_cache.get() {
            return Ok(cached.clone_ref(py).into_bound(py));
        }
        let oid = &self.cert()?.signature_algorithm.algorithm;
        let name = synta_certificate::identify_signature_algorithm(oid);
        let s = if name != "Other" {
            name.to_string()
        } else {
            oid.to_string()
        };
        let py_str = PyString::new(py, &s).unbind();
        let _ = self.signature_algorithm_cache.set(py_str.clone_ref(py));
        Ok(py_str.into_bound(py))
    }

    /// Raw signature bytes.
    ///
    /// The `bytes` object is created once on first access and the same Python
    /// object is returned (by reference) on every subsequent call.
    #[getter]
    fn signature_value<'py>(&self, py: Python<'py>) -> PyResult<Bound<'py, PyBytes>> {
        if let Some(cached) = self.signature_value_cache.get() {
            return Ok(cached.clone_ref(py).into_bound(py));
        }
        let py_bytes = PyBytes::new(py, self.cert()?.signature_value.as_bytes()).unbind();
        let _ = self.signature_value_cache.set(py_bytes.clone_ref(py));
        Ok(py_bytes.into_bound(py))
    }

    /// notBefore time as a string.
    #[getter]
    fn not_before<'py>(&self, py: Python<'py>) -> PyResult<Bound<'py, PyString>> {
        if let Some(cached) = self.not_before_cache.get() {
            return Ok(cached.clone_ref(py).into_bound(py));
        }
        let s = match &self.cert()?.tbs_certificate.validity.not_before {
            Time::UtcTime(t) => t.to_string(),
            Time::GeneralTime(t) => t.to_string(),
        };
        let py_str = PyString::new(py, &s).unbind();
        let _ = self.not_before_cache.set(py_str.clone_ref(py));
        Ok(py_str.into_bound(py))
    }

    /// notAfter time as a string.
    #[getter]
    fn not_after<'py>(&self, py: Python<'py>) -> PyResult<Bound<'py, PyString>> {
        if let Some(cached) = self.not_after_cache.get() {
            return Ok(cached.clone_ref(py).into_bound(py));
        }
        let s = match &self.cert()?.tbs_certificate.validity.not_after {
            Time::UtcTime(t) => t.to_string(),
            Time::GeneralTime(t) => t.to_string(),
        };
        let py_str = PyString::new(py, &s).unbind();
        let _ = self.not_after_cache.set(py_str.clone_ref(py));
        Ok(py_str.into_bound(py))
    }

    /// Subject public-key algorithm name (e.g. "RSA", "ECDSA", "Ed25519", "ML-DSA-65"),
    /// or the dotted OID notation for unrecognized algorithms.
    #[getter]
    fn public_key_algorithm<'py>(&self, py: Python<'py>) -> PyResult<Bound<'py, PyString>> {
        if let Some(cached) = self.public_key_algorithm_cache.get() {
            return Ok(cached.clone_ref(py).into_bound(py));
        }
        let oid = &self
            .cert()?
            .tbs_certificate
            .subject_public_key_info
            .algorithm
            .algorithm;
        let s = synta_certificate::identify_public_key_algorithm(oid)
            .map(|s| s.to_string())
            .unwrap_or_else(|| oid.to_string());
        let py_str = PyString::new(py, &s).unbind();
        let _ = self.public_key_algorithm_cache.set(py_str.clone_ref(py));
        Ok(py_str.into_bound(py))
    }

    /// Raw subject public-key bytes.
    ///
    /// The `bytes` object is created once on first access and the same Python
    /// object is returned (by reference) on every subsequent call.
    #[getter]
    fn public_key<'py>(&self, py: Python<'py>) -> PyResult<Bound<'py, PyBytes>> {
        if let Some(cached) = self.public_key_cache.get() {
            return Ok(cached.clone_ref(py).into_bound(py));
        }
        let py_bytes = PyBytes::new(
            py,
            self.cert()?
                .tbs_certificate
                .subject_public_key_info
                .subject_public_key
                .as_bytes(),
        )
        .unbind();
        let _ = self.public_key_cache.set(py_bytes.clone_ref(py));
        Ok(py_bytes.into_bound(py))
    }

    /// Version field (0 = v1, 1 = v2, 2 = v3), or None if absent.
    #[getter]
    fn version(&self) -> PyResult<Option<i64>> {
        Ok(self
            .cert()?
            .tbs_certificate
            .version
            .as_ref()
            .and_then(|v| v.as_i64().ok()))
    }

    /// Complete DER encoding of this certificate (the original bytes passed to
    /// ``from_der``).
    fn to_der<'py>(&self, py: Python<'py>) -> Bound<'py, PyBytes> {
        self._data.clone_ref(py).into_bound(py)
    }

    /// Raw DER bytes of the TBSCertificate structure (the bytes that were
    /// signed by the issuer's key).
    #[getter]
    fn tbs_bytes<'py>(&self, py: Python<'py>) -> Bound<'py, PyBytes> {
        self.tbs_bytes_cache
            .get_or_init(|| {
                let data = self._data.bind(py).as_bytes();
                PyBytes::new(py, &data[self.tbs_range.clone()]).unbind()
            })
            .clone_ref(py)
            .into_bound(py)
    }

    /// OID of the signature algorithm
    /// (e.g. ``ObjectIdentifier("1.2.840.113549.1.1.11")`` for sha256WithRSAEncryption).
    ///
    /// Unlike ``signature_algorithm``, this always returns the machine-readable
    /// OID, even for algorithms that synta does not recognise by name.
    #[getter]
    fn signature_algorithm_oid<'py>(
        &self,
        py: Python<'py>,
    ) -> PyResult<Bound<'py, PyObjectIdentifier>> {
        if let Some(cached) = self.signature_algorithm_oid_cache.get() {
            return Ok(cached.clone_ref(py).into_bound(py));
        }
        let obj = Py::new(
            py,
            PyObjectIdentifier::from_oid(self.cert()?.signature_algorithm.algorithm.clone()),
        )?;
        let _ = self.signature_algorithm_oid_cache.set(obj.clone_ref(py));
        Ok(obj.into_bound(py))
    }

    /// Raw DER bytes of the signature algorithm parameters, or ``None`` if
    /// the AlgorithmIdentifier has no parameters field (e.g. Ed25519).
    #[getter]
    fn signature_algorithm_params<'py>(
        &self,
        py: Python<'py>,
    ) -> PyResult<Option<Bound<'py, PyBytes>>> {
        if let Some(cached) = self.signature_algorithm_params_cache.get() {
            return Ok(cached.as_ref().map(|b| b.clone_ref(py).into_bound(py)));
        }
        let computed =
            encode_element_opt(py, self.cert()?.signature_algorithm.parameters.as_ref())?;
        let to_store = computed.as_ref().map(|b| b.as_unbound().clone_ref(py));
        let _ = self.signature_algorithm_params_cache.set(to_store);
        Ok(computed)
    }

    /// OID of the subject public-key algorithm
    /// (e.g. ``ObjectIdentifier("1.2.840.10045.2.1")`` for id-ecPublicKey).
    #[getter]
    fn public_key_algorithm_oid<'py>(
        &self,
        py: Python<'py>,
    ) -> PyResult<Bound<'py, PyObjectIdentifier>> {
        if let Some(cached) = self.public_key_algorithm_oid_cache.get() {
            return Ok(cached.clone_ref(py).into_bound(py));
        }
        let obj = Py::new(
            py,
            PyObjectIdentifier::from_oid(
                self.cert()?
                    .tbs_certificate
                    .subject_public_key_info
                    .algorithm
                    .algorithm
                    .clone(),
            ),
        )?;
        let _ = self.public_key_algorithm_oid_cache.set(obj.clone_ref(py));
        Ok(obj.into_bound(py))
    }

    /// Raw DER bytes of the public-key algorithm parameters, or ``None``.
    ///
    /// For EC keys this is an OID naming the curve (e.g. secp256r1).
    /// For RSA and Ed25519 this is typically ``None`` or a NULL element.
    #[getter]
    fn public_key_algorithm_params<'py>(
        &self,
        py: Python<'py>,
    ) -> PyResult<Option<Bound<'py, PyBytes>>> {
        if let Some(cached) = self.public_key_algorithm_params_cache.get() {
            return Ok(cached.as_ref().map(|b| b.clone_ref(py).into_bound(py)));
        }
        let computed = encode_element_opt(
            py,
            self.cert()?
                .tbs_certificate
                .subject_public_key_info
                .algorithm
                .parameters
                .as_ref(),
        )?;
        let to_store = computed.as_ref().map(|b| b.as_unbound().clone_ref(py));
        let _ = self.public_key_algorithm_params_cache.set(to_store);
        Ok(computed)
    }

    /// Raw DER bytes of the extensions SEQUENCE OF, or ``None`` for v1/v2
    /// certificates that carry no extensions.
    ///
    /// The returned bytes begin with the SEQUENCE tag (``0x30``) and contain
    /// the full SEQUENCE OF Extension encoding.  Pass them to a ``Decoder``
    /// to iterate the individual extensions:
    ///
    /// ```python
    /// ext_der = cert.extensions_der
    /// if ext_der:
    ///     dec = synta.Decoder(ext_der, synta.Encoding.DER)
    ///     exts_dec = dec.decode_sequence()
    ///     while not exts_dec.is_empty():
    ///         ext_tlv = exts_dec.decode_raw_tlv()
    /// ```
    #[getter]
    fn extensions_der<'py>(&self, py: Python<'py>) -> PyResult<Option<Bound<'py, PyBytes>>> {
        if let Some(cached) = self.extensions_der_cache.get() {
            return Ok(cached.as_ref().map(|b| b.clone_ref(py).into_bound(py)));
        }
        let computed = self
            .cert()?
            .tbs_certificate
            .extensions
            .as_ref()
            .map(|raw: &synta::RawDer<'_>| PyBytes::new(py, raw.as_bytes()));
        let to_store = computed.as_ref().map(|b| b.as_unbound().clone_ref(py));
        let _ = self.extensions_der_cache.set(to_store);
        Ok(computed)
    }

    /// Return the DER content of a named extension's value, or ``None``.
    ///
    /// Searches the certificate's extension list for an extension whose
    /// ``extnID`` equals *oid* (dotted-decimal notation, e.g.
    /// ``"2.5.29.17"`` for SubjectAltName).  When found, the bytes inside
    /// the ``extnValue`` OCTET STRING — the DER-encoded extension-specific
    /// structure — are returned.  Returns ``None`` when the certificate
    /// carries no extensions or the named OID is absent.
    ///
    /// Example — parse SubjectAltName:
    ///
    /// ```python
    ///     san_der = cert.get_extension_value_der("2.5.29.17")
    ///     if san_der:
    ///         dec = synta.Decoder(san_der, synta.Encoding.DER)
    ///         san_seq = dec.decode_sequence()
    ///         while not san_seq.is_empty():
    ///             tag_num, tag_class, _ = san_seq.peek_tag()
    ///             child = san_seq.decode_implicit_tag(tag_num, tag_class)
    ///             if tag_num == 2:  # dNSName
    ///                 print(child.remaining_bytes().decode("ascii"))
    /// ```
    fn get_extension_value_der<'py>(
        &self,
        py: Python<'py>,
        oid: &Bound<'_, PyAny>,
    ) -> PyResult<Option<Bound<'py, PyBytes>>> {
        let target = oid_from_pyany(oid)?;
        let raw = match self.cert()?.tbs_certificate.extensions.as_ref() {
            Some(r) => r,
            None => return Ok(None),
        };
        for ext in &synta_certificate::decode_extensions(raw.as_bytes()) {
            if ext.extn_id == target {
                return Ok(Some(PyBytes::new(py, ext.extn_value.as_bytes())));
            }
        }
        Ok(None)
    }

    /// Return the Subject Alternative Names of this certificate.
    ///
    /// Combines looking up the SAN extension (OID ``2.5.29.17``) and parsing
    /// its ``GeneralName`` entries into a single call.  Returns a
    /// :class:`list` of ``(tag_number: int, content: bytes)`` tuples in
    /// document order; returns an empty list when the certificate carries no
    /// SAN extension.
    ///
    /// Tag numbers follow RFC 5280 §4.2.1.6 — the same convention as
    /// :func:`~synta.parse_general_names`.  Named constants for every tag are
    /// available in :mod:`synta.general_name`:
    ///
    /// | :attr:`~synta.general_name.RFC822_NAME` (1) | raw IA5String bytes (e-mail) |
    /// | :attr:`~synta.general_name.DNS_NAME` (2)    | raw IA5String bytes |
    /// | :attr:`~synta.general_name.DIRECTORY_NAME` (4) | complete Name SEQUENCE TLV |
    /// | :attr:`~synta.general_name.URI` (6)         | raw IA5String bytes |
    /// | :attr:`~synta.general_name.IP_ADDRESS` (7)  | 4 bytes (IPv4) or 16 bytes (IPv6) |
    /// | :attr:`~synta.general_name.REGISTERED_ID` (8) | raw OID value bytes |
    ///
    /// ```python,ignore
    /// import ipaddress
    /// import synta.general_name as gn
    ///
    /// for tag_num, content in cert.subject_alt_names():
    ///     if tag_num == gn.DNS_NAME:
    ///         print("DNS:", content.decode("ascii"))
    ///     elif tag_num == gn.IP_ADDRESS:
    ///         print("IP:", ipaddress.ip_address(content))
    ///     elif tag_num == gn.RFC822_NAME:
    ///         print("email:", content.decode("ascii"))
    ///     elif tag_num == gn.DIRECTORY_NAME:
    ///         attrs = synta.parse_name_attrs(content)
    ///         print("DirName:", attrs)
    ///     elif tag_num == gn.URI:
    ///         print("URI:", content.decode("ascii"))
    /// ```
    fn subject_alt_names<'py>(&self, py: Python<'py>) -> PyResult<Bound<'py, PyList>> {
        use pyo3::types::{PyBytes, PyList, PyTuple};
        let list = PyList::empty(py);
        for (tag_num, content) in self.cert()?.subject_alt_names() {
            let tuple = PyTuple::new(
                py,
                [
                    tag_num.into_pyobject(py)?.into_any(),
                    PyBytes::new(py, &content).into_any(),
                ],
            )?;
            list.append(tuple)?;
        }
        Ok(list)
    }

    /// Raw DER bytes of the issuer Name SEQUENCE.
    #[getter]
    fn issuer_raw_der<'py>(&self, py: Python<'py>) -> PyResult<Bound<'py, PyBytes>> {
        if let Some(cached) = self.issuer_raw_der_cache.get() {
            return Ok(cached.clone_ref(py).into_bound(py));
        }
        let py_bytes = PyBytes::new(py, self.cert()?.tbs_certificate.issuer.as_bytes()).unbind();
        let _ = self.issuer_raw_der_cache.set(py_bytes.clone_ref(py));
        Ok(py_bytes.into_bound(py))
    }

    /// Raw DER bytes of the subject Name SEQUENCE.
    #[getter]
    fn subject_raw_der<'py>(&self, py: Python<'py>) -> PyResult<Bound<'py, PyBytes>> {
        if let Some(cached) = self.subject_raw_der_cache.get() {
            return Ok(cached.clone_ref(py).into_bound(py));
        }
        let py_bytes = PyBytes::new(py, self.cert()?.tbs_certificate.subject.as_bytes()).unbind();
        let _ = self.subject_raw_der_cache.set(py_bytes.clone_ref(py));
        Ok(py_bytes.into_bound(py))
    }

    fn __repr__(&self) -> PyResult<String> {
        let cert = self.cert()?;
        let serial = &cert.tbs_certificate.serial_number;
        let serial_str = if let Ok(v) = serial.as_i64() {
            v.to_string()
        } else {
            format!("<{} bytes>", serial.as_bytes().len())
        };
        Ok(format!(
            "Certificate(subject={:?}, serial={})",
            decode_name_debug(cert.tbs_certificate.subject.as_bytes()),
            serial_str,
        ))
    }
}

// ── Helpers for CSR / CRL (Name is decoded eagerly, not stored as RawDer) ─────

/// Re-encode a parsed `Name` to DER and format it as an RFC 4514 DN string.
fn name_to_dn_string(name: &synta_certificate::Name<'_>) -> String {
    let mut enc = synta::Encoder::new(synta::Encoding::Der);
    if name.encode(&mut enc).is_err() {
        return String::new();
    }
    synta_certificate::name::format_dn(&enc.finish().unwrap_or_default())
}

/// Re-encode a parsed `Name` to its DER bytes.
fn name_to_der_bytes(name: &synta_certificate::Name<'_>) -> Vec<u8> {
    let mut enc = synta::Encoder::new(synta::Encoding::Der);
    if name.encode(&mut enc).is_err() {
        return Vec::new();
    }
    enc.finish().unwrap_or_default()
}

/// Map an `OCSPResponseStatus` enum value to its RFC 6960 display name.
fn ocsp_status_str(status: synta_certificate::ocsp::OCSPResponseStatus) -> &'static str {
    use synta_certificate::ocsp::OCSPResponseStatus::*;
    match status {
        Successful => "successful",
        MalformedRequest => "malformedRequest",
        InternalError => "internalError",
        TryLater => "tryLater",
        SigRequired => "sigRequired",
        Unauthorized => "unauthorized",
    }
}

// ── PyCsr ─────────────────────────────────────────────────────────────────────

/// PKCS #10 Certificate Signing Request accessible from Python.
///
/// ```python
/// csr = CertificationRequest.from_der(open("req.der", "rb").read())
/// print(csr.subject)
/// print(csr.public_key_algorithm)
/// ```
#[pyclass(frozen, name = "CertificationRequest")]
pub struct PyCsr {
    _data: Py<PyBytes>,
    raw: &'static [u8],
    inner: OnceLock<Box<synta_certificate::csr::CertificationRequest<'static>>>,
    subject_cache: OnceLock<Py<PyString>>,
    subject_raw_der_cache: OnceLock<Py<PyBytes>>,
    signature_algorithm_cache: OnceLock<Py<PyString>>,
    signature_algorithm_oid_cache: OnceLock<Py<PyObjectIdentifier>>,
    signature_cache: OnceLock<Py<PyBytes>>,
    public_key_algorithm_cache: OnceLock<Py<PyString>>,
    public_key_algorithm_oid_cache: OnceLock<Py<PyObjectIdentifier>>,
    public_key_cache: OnceLock<Py<PyBytes>>,
}

impl PyCsr {
    fn csr(&self) -> PyResult<&synta_certificate::csr::CertificationRequest<'static>> {
        if let Some(v) = self.inner.get() {
            return Ok(v.as_ref());
        }
        let mut decoder = Decoder::new(self.raw, Encoding::Der);
        let decoded = decoder.decode().map_err(|e| {
            pyo3::exceptions::PyValueError::new_err(format!(
                "CertificationRequest DER decode failed: {e}"
            ))
        })?;
        let _ = self.inner.set(Box::new(decoded));
        Ok(self.inner.get().unwrap().as_ref())
    }
}

#[pymethods]
impl PyCsr {
    /// Parse a DER-encoded PKCS #10 Certificate Signing Request.
    #[staticmethod]
    fn from_der(py: Python<'_>, data: Bound<'_, PyBytes>) -> PyResult<Self> {
        let py_bytes = data.unbind();
        // SAFETY: `py_bytes` holds a strong reference (Py<PyBytes>) that
        // keeps the Python bytes object alive for the lifetime of this struct.
        // CPython's bytes objects have a fixed-address, non-relocating payload
        // buffer (CPython has no moving GC).  The slice lifetime is extended
        // to 'static; the actual safety invariants are:
        //   (1) All reads of `raw` go through `&self`; no borrow of the struct
        //       can outlive the struct, so `raw` is never read after drop begins.
        //   (2) `raw: &'static [u8]` has no destructor (fat pointer, no heap
        //       allocation), so field drop order does not cause use-after-free.
        //   (3) `inner` contains only borrow-typed fields; dropping
        //       Box<CertificationRequest<'static>> does not read through the
        //       contained &'static slices (borrows have no destructors).
        // CPython-only: does not hold for PyPy or GraalPy.
        let raw: &'static [u8] = unsafe {
            let s = py_bytes.bind(py).as_bytes();
            std::slice::from_raw_parts(s.as_ptr(), s.len())
        };
        // Minimal structural scan: outer SEQUENCE tag + length.
        {
            let mut d = Decoder::new(raw, Encoding::Der);
            d.read_tag()
                .map_err(|e| pyo3::exceptions::PyValueError::new_err(format!("{e}")))?;
            d.read_length()
                .map_err(|e| pyo3::exceptions::PyValueError::new_err(format!("{e}")))?;
        }
        Ok(Self {
            _data: py_bytes,
            raw,
            inner: OnceLock::new(),
            subject_cache: OnceLock::new(),
            subject_raw_der_cache: OnceLock::new(),
            signature_algorithm_cache: OnceLock::new(),
            signature_algorithm_oid_cache: OnceLock::new(),
            signature_cache: OnceLock::new(),
            public_key_algorithm_cache: OnceLock::new(),
            public_key_algorithm_oid_cache: OnceLock::new(),
            public_key_cache: OnceLock::new(),
        })
    }

    /// Parse a PEM-encoded PKCS #10 Certificate Signing Request.
    ///
    /// Returns a single :class:`CertificationRequest` for one PEM block, or a
    /// :class:`list` of :class:`CertificationRequest` objects when multiple
    /// blocks are present.  Raises :exc:`ValueError` if no PEM block is found.
    ///
    /// ```python
    /// csr = CertificationRequest.from_pem(open("csr.pem", "rb").read())
    /// print(csr.subject)
    /// ```
    #[staticmethod]
    fn from_pem<'py>(py: Python<'py>, data: Bound<'_, PyBytes>) -> PyResult<Bound<'py, PyAny>> {
        pem_blocks_to_pyobject(py, data.as_bytes(), |py, bytes| {
            let obj = Self::from_der(py, bytes)?;
            Ok(Py::new(py, obj)?.into_bound(py).into_any())
        })
    }

    /// Serialize one CSR or a list of CSRs to PEM format.
    ///
    /// ```python
    /// pem = CertificationRequest.to_pem(csr)
    /// pem = CertificationRequest.to_pem([csr1, csr2])
    /// ```
    #[staticmethod]
    fn to_pem<'py>(
        py: Python<'py>,
        obj_or_list: Bound<'_, PyAny>,
    ) -> PyResult<Bound<'py, PyBytes>> {
        pyobject_to_pem::<Self, _>(py, "CERTIFICATE REQUEST", &obj_or_list, |c| c.raw)
    }

    /// Subject distinguished name as a string.
    #[getter]
    fn subject<'py>(&self, py: Python<'py>) -> PyResult<Bound<'py, PyString>> {
        if let Some(cached) = self.subject_cache.get() {
            return Ok(cached.clone_ref(py).into_bound(py));
        }
        let s = name_to_dn_string(&self.csr()?.certification_request_info.subject);
        let py_str = PyString::new(py, &s).unbind();
        let _ = self.subject_cache.set(py_str.clone_ref(py));
        Ok(py_str.into_bound(py))
    }

    /// Raw DER bytes of the subject Name SEQUENCE.
    #[getter]
    fn subject_raw_der<'py>(&self, py: Python<'py>) -> PyResult<Bound<'py, PyBytes>> {
        if let Some(cached) = self.subject_raw_der_cache.get() {
            return Ok(cached.clone_ref(py).into_bound(py));
        }
        let bytes = name_to_der_bytes(&self.csr()?.certification_request_info.subject);
        let py_bytes = PyBytes::new(py, &bytes).unbind();
        let _ = self.subject_raw_der_cache.set(py_bytes.clone_ref(py));
        Ok(py_bytes.into_bound(py))
    }

    /// CSR version (0 = v1 per RFC 2986).
    #[getter]
    fn version(&self) -> PyResult<i64> {
        Ok(self
            .csr()?
            .certification_request_info
            .version
            .as_i64()
            .unwrap_or(0))
    }

    /// Signature algorithm name (e.g. "RSA", "ECDSA", "Ed25519").
    #[getter]
    fn signature_algorithm<'py>(&self, py: Python<'py>) -> PyResult<Bound<'py, PyString>> {
        if let Some(cached) = self.signature_algorithm_cache.get() {
            return Ok(cached.clone_ref(py).into_bound(py));
        }
        let oid = &self.csr()?.signature_algorithm.algorithm;
        let name = synta_certificate::identify_signature_algorithm(oid);
        let s = if name != "Other" {
            name.to_string()
        } else {
            oid.to_string()
        };
        let py_str = PyString::new(py, &s).unbind();
        let _ = self.signature_algorithm_cache.set(py_str.clone_ref(py));
        Ok(py_str.into_bound(py))
    }

    /// OID of the signature algorithm.
    #[getter]
    fn signature_algorithm_oid<'py>(
        &self,
        py: Python<'py>,
    ) -> PyResult<Bound<'py, PyObjectIdentifier>> {
        if let Some(cached) = self.signature_algorithm_oid_cache.get() {
            return Ok(cached.clone_ref(py).into_bound(py));
        }
        let obj = Py::new(
            py,
            PyObjectIdentifier::from_oid(self.csr()?.signature_algorithm.algorithm.clone()),
        )?;
        let _ = self.signature_algorithm_oid_cache.set(obj.clone_ref(py));
        Ok(obj.into_bound(py))
    }

    /// Raw signature bytes.
    #[getter]
    fn signature<'py>(&self, py: Python<'py>) -> PyResult<Bound<'py, PyBytes>> {
        if let Some(cached) = self.signature_cache.get() {
            return Ok(cached.clone_ref(py).into_bound(py));
        }
        let py_bytes = PyBytes::new(py, self.csr()?.signature.as_bytes()).unbind();
        let _ = self.signature_cache.set(py_bytes.clone_ref(py));
        Ok(py_bytes.into_bound(py))
    }

    /// Public-key algorithm name (e.g. "RSA", "ECDSA", "Ed25519").
    #[getter]
    fn public_key_algorithm<'py>(&self, py: Python<'py>) -> PyResult<Bound<'py, PyString>> {
        if let Some(cached) = self.public_key_algorithm_cache.get() {
            return Ok(cached.clone_ref(py).into_bound(py));
        }
        let oid = &self
            .csr()?
            .certification_request_info
            .subject_pkinfo
            .algorithm
            .algorithm;
        let s = synta_certificate::identify_public_key_algorithm(oid)
            .map(|s| s.to_string())
            .unwrap_or_else(|| oid.to_string());
        let py_str = PyString::new(py, &s).unbind();
        let _ = self.public_key_algorithm_cache.set(py_str.clone_ref(py));
        Ok(py_str.into_bound(py))
    }

    /// OID of the subject public-key algorithm.
    #[getter]
    fn public_key_algorithm_oid<'py>(
        &self,
        py: Python<'py>,
    ) -> PyResult<Bound<'py, PyObjectIdentifier>> {
        if let Some(cached) = self.public_key_algorithm_oid_cache.get() {
            return Ok(cached.clone_ref(py).into_bound(py));
        }
        let obj = Py::new(
            py,
            PyObjectIdentifier::from_oid(
                self.csr()?
                    .certification_request_info
                    .subject_pkinfo
                    .algorithm
                    .algorithm
                    .clone(),
            ),
        )?;
        let _ = self.public_key_algorithm_oid_cache.set(obj.clone_ref(py));
        Ok(obj.into_bound(py))
    }

    /// Raw subject public-key bytes.
    #[getter]
    fn public_key<'py>(&self, py: Python<'py>) -> PyResult<Bound<'py, PyBytes>> {
        if let Some(cached) = self.public_key_cache.get() {
            return Ok(cached.clone_ref(py).into_bound(py));
        }
        let py_bytes = PyBytes::new(
            py,
            self.csr()?
                .certification_request_info
                .subject_pkinfo
                .subject_public_key
                .as_bytes(),
        )
        .unbind();
        let _ = self.public_key_cache.set(py_bytes.clone_ref(py));
        Ok(py_bytes.into_bound(py))
    }

    /// Complete DER encoding of this CSR (the original bytes passed to ``from_der``).
    fn to_der<'py>(&self, py: Python<'py>) -> Bound<'py, PyBytes> {
        self._data.clone_ref(py).into_bound(py)
    }

    fn __repr__(&self) -> PyResult<String> {
        Ok(format!(
            "CertificationRequest(subject={:?})",
            name_to_dn_string(&self.csr()?.certification_request_info.subject),
        ))
    }
}

// ── PyCrl ─────────────────────────────────────────────────────────────────────

/// X.509 Certificate Revocation List accessible from Python.
///
/// ```python
/// crl = CertificateList.from_der(open("crl.der", "rb").read())
/// print(crl.issuer)
/// print(crl.revoked_count)
/// ```
#[pyclass(frozen, name = "CertificateList")]
pub struct PyCrl {
    _data: Py<PyBytes>,
    raw: &'static [u8],
    inner: OnceLock<Box<synta_certificate::crl::CertificateList<'static>>>,
    issuer_cache: OnceLock<Py<PyString>>,
    issuer_raw_der_cache: OnceLock<Py<PyBytes>>,
    this_update_cache: OnceLock<Py<PyString>>,
    next_update_cache: OnceLock<Option<Py<PyString>>>,
    signature_algorithm_cache: OnceLock<Py<PyString>>,
    signature_algorithm_oid_cache: OnceLock<Py<PyObjectIdentifier>>,
    signature_value_cache: OnceLock<Py<PyBytes>>,
}

impl PyCrl {
    fn crl(&self) -> PyResult<&synta_certificate::crl::CertificateList<'static>> {
        if let Some(v) = self.inner.get() {
            return Ok(v.as_ref());
        }
        let mut decoder = Decoder::new(self.raw, Encoding::Der);
        let decoded = decoder.decode().map_err(|e| {
            pyo3::exceptions::PyValueError::new_err(format!(
                "CertificateList DER decode failed: {e}"
            ))
        })?;
        let _ = self.inner.set(Box::new(decoded));
        Ok(self.inner.get().unwrap().as_ref())
    }
}

#[pymethods]
impl PyCrl {
    /// Parse a DER-encoded X.509 Certificate Revocation List.
    #[staticmethod]
    fn from_der(py: Python<'_>, data: Bound<'_, PyBytes>) -> PyResult<Self> {
        let py_bytes = data.unbind();
        // SAFETY: `py_bytes` holds a strong reference (Py<PyBytes>) that
        // keeps the Python bytes object alive for the lifetime of this struct.
        // CPython's bytes objects have a fixed-address, non-relocating payload
        // buffer (CPython has no moving GC).  The slice lifetime is extended
        // to 'static; the actual safety invariants are:
        //   (1) All reads of `raw` go through `&self`; no borrow of the struct
        //       can outlive the struct, so `raw` is never read after drop begins.
        //   (2) `raw: &'static [u8]` has no destructor (fat pointer, no heap
        //       allocation), so field drop order does not cause use-after-free.
        //   (3) `inner` contains only borrow-typed fields; dropping
        //       Box<CertificateList<'static>> does not read through the
        //       contained &'static slices (borrows have no destructors).
        // CPython-only: does not hold for PyPy or GraalPy.
        let raw: &'static [u8] = unsafe {
            let s = py_bytes.bind(py).as_bytes();
            std::slice::from_raw_parts(s.as_ptr(), s.len())
        };
        {
            let mut d = Decoder::new(raw, Encoding::Der);
            d.read_tag()
                .map_err(|e| pyo3::exceptions::PyValueError::new_err(format!("{e}")))?;
            d.read_length()
                .map_err(|e| pyo3::exceptions::PyValueError::new_err(format!("{e}")))?;
        }
        Ok(Self {
            _data: py_bytes,
            raw,
            inner: OnceLock::new(),
            issuer_cache: OnceLock::new(),
            issuer_raw_der_cache: OnceLock::new(),
            this_update_cache: OnceLock::new(),
            next_update_cache: OnceLock::new(),
            signature_algorithm_cache: OnceLock::new(),
            signature_algorithm_oid_cache: OnceLock::new(),
            signature_value_cache: OnceLock::new(),
        })
    }

    /// Parse a PEM-encoded X.509 Certificate Revocation List.
    ///
    /// Returns a single :class:`CertificateList` for one PEM block, or a
    /// :class:`list` of :class:`CertificateList` objects when multiple blocks
    /// are present.  Raises :exc:`ValueError` if no PEM block is found.
    ///
    /// ```python
    /// crl = CertificateList.from_pem(open("crl.pem", "rb").read())
    /// print(crl.issuer)
    /// ```
    #[staticmethod]
    fn from_pem<'py>(py: Python<'py>, data: Bound<'_, PyBytes>) -> PyResult<Bound<'py, PyAny>> {
        pem_blocks_to_pyobject(py, data.as_bytes(), |py, bytes| {
            let obj = Self::from_der(py, bytes)?;
            Ok(Py::new(py, obj)?.into_bound(py).into_any())
        })
    }

    /// Serialize one CRL or a list of CRLs to PEM format.
    ///
    /// ```python
    /// pem = CertificateList.to_pem(crl)
    /// pem = CertificateList.to_pem([crl1, crl2])
    /// ```
    #[staticmethod]
    fn to_pem<'py>(
        py: Python<'py>,
        obj_or_list: Bound<'_, PyAny>,
    ) -> PyResult<Bound<'py, PyBytes>> {
        pyobject_to_pem::<Self, _>(py, "X509 CRL", &obj_or_list, |c| c.raw)
    }

    /// Issuer distinguished name as a string.
    #[getter]
    fn issuer<'py>(&self, py: Python<'py>) -> PyResult<Bound<'py, PyString>> {
        if let Some(cached) = self.issuer_cache.get() {
            return Ok(cached.clone_ref(py).into_bound(py));
        }
        let s = name_to_dn_string(&self.crl()?.tbs_cert_list.issuer);
        let py_str = PyString::new(py, &s).unbind();
        let _ = self.issuer_cache.set(py_str.clone_ref(py));
        Ok(py_str.into_bound(py))
    }

    /// Raw DER bytes of the issuer Name SEQUENCE.
    #[getter]
    fn issuer_raw_der<'py>(&self, py: Python<'py>) -> PyResult<Bound<'py, PyBytes>> {
        if let Some(cached) = self.issuer_raw_der_cache.get() {
            return Ok(cached.clone_ref(py).into_bound(py));
        }
        let bytes = name_to_der_bytes(&self.crl()?.tbs_cert_list.issuer);
        let py_bytes = PyBytes::new(py, &bytes).unbind();
        let _ = self.issuer_raw_der_cache.set(py_bytes.clone_ref(py));
        Ok(py_bytes.into_bound(py))
    }

    /// thisUpdate time as a string.
    #[getter]
    fn this_update<'py>(&self, py: Python<'py>) -> PyResult<Bound<'py, PyString>> {
        if let Some(cached) = self.this_update_cache.get() {
            return Ok(cached.clone_ref(py).into_bound(py));
        }
        let s = match &self.crl()?.tbs_cert_list.this_update {
            Time::UtcTime(t) => t.to_string(),
            Time::GeneralTime(t) => t.to_string(),
        };
        let py_str = PyString::new(py, &s).unbind();
        let _ = self.this_update_cache.set(py_str.clone_ref(py));
        Ok(py_str.into_bound(py))
    }

    /// nextUpdate time as a string, or ``None`` if absent.
    #[getter]
    fn next_update<'py>(&self, py: Python<'py>) -> PyResult<Option<Bound<'py, PyString>>> {
        if let Some(cached) = self.next_update_cache.get() {
            return Ok(cached.as_ref().map(|s| s.clone_ref(py).into_bound(py)));
        }
        let computed: Option<Bound<'py, PyString>> =
            self.crl()?.tbs_cert_list.next_update.as_ref().map(|t| {
                let s = match t {
                    Time::UtcTime(t) => t.to_string(),
                    Time::GeneralTime(t) => t.to_string(),
                };
                PyString::new(py, &s)
            });
        let to_store = computed.as_ref().map(|s| s.as_unbound().clone_ref(py));
        let _ = self.next_update_cache.set(to_store);
        Ok(computed)
    }

    /// Signature algorithm name (e.g. "RSA", "ECDSA").
    #[getter]
    fn signature_algorithm<'py>(&self, py: Python<'py>) -> PyResult<Bound<'py, PyString>> {
        if let Some(cached) = self.signature_algorithm_cache.get() {
            return Ok(cached.clone_ref(py).into_bound(py));
        }
        let oid = &self.crl()?.signature_algorithm.algorithm;
        let name = synta_certificate::identify_signature_algorithm(oid);
        let s = if name != "Other" {
            name.to_string()
        } else {
            oid.to_string()
        };
        let py_str = PyString::new(py, &s).unbind();
        let _ = self.signature_algorithm_cache.set(py_str.clone_ref(py));
        Ok(py_str.into_bound(py))
    }

    /// OID of the signature algorithm.
    #[getter]
    fn signature_algorithm_oid<'py>(
        &self,
        py: Python<'py>,
    ) -> PyResult<Bound<'py, PyObjectIdentifier>> {
        if let Some(cached) = self.signature_algorithm_oid_cache.get() {
            return Ok(cached.clone_ref(py).into_bound(py));
        }
        let obj = Py::new(
            py,
            PyObjectIdentifier::from_oid(self.crl()?.signature_algorithm.algorithm.clone()),
        )?;
        let _ = self.signature_algorithm_oid_cache.set(obj.clone_ref(py));
        Ok(obj.into_bound(py))
    }

    /// Raw signature bytes.
    #[getter]
    fn signature_value<'py>(&self, py: Python<'py>) -> PyResult<Bound<'py, PyBytes>> {
        if let Some(cached) = self.signature_value_cache.get() {
            return Ok(cached.clone_ref(py).into_bound(py));
        }
        let py_bytes = PyBytes::new(py, self.crl()?.signature_value.as_bytes()).unbind();
        let _ = self.signature_value_cache.set(py_bytes.clone_ref(py));
        Ok(py_bytes.into_bound(py))
    }

    /// Number of revoked certificates in this CRL (0 if no revoked entries).
    #[getter]
    fn revoked_count(&self) -> PyResult<usize> {
        Ok(self
            .crl()?
            .tbs_cert_list
            .revoked_certificates
            .as_ref()
            .map(|v| v.len())
            .unwrap_or(0))
    }

    /// Complete DER encoding of this CRL (the original bytes passed to ``from_der``).
    fn to_der<'py>(&self, py: Python<'py>) -> Bound<'py, PyBytes> {
        self._data.clone_ref(py).into_bound(py)
    }

    fn __repr__(&self) -> PyResult<String> {
        let crl = self.crl()?;
        Ok(format!(
            "CertificateList(issuer={:?}, revoked_count={})",
            name_to_dn_string(&crl.tbs_cert_list.issuer),
            crl.tbs_cert_list
                .revoked_certificates
                .as_ref()
                .map(|v| v.len())
                .unwrap_or(0),
        ))
    }
}

// ── PyOcspResponse ────────────────────────────────────────────────────────────

/// OCSP Response (RFC 6960) accessible from Python.
///
/// ```python
/// resp = OCSPResponse.from_der(open("resp.der", "rb").read())
/// print(resp.status)
/// if resp.response_bytes:
///     basic = resp.response_bytes  # DER of BasicOCSPResponse
/// ```
#[pyclass(frozen, name = "OCSPResponse")]
pub struct PyOcspResponse {
    _data: Py<PyBytes>,
    raw: &'static [u8],
    inner: OnceLock<Box<synta_certificate::ocsp::OCSPResponse<'static>>>,
    status_cache: OnceLock<Py<PyString>>,
    response_type_oid_cache: OnceLock<Option<Py<PyObjectIdentifier>>>,
    response_bytes_cache: OnceLock<Option<Py<PyBytes>>>,
}

impl PyOcspResponse {
    fn ocsp(&self) -> PyResult<&synta_certificate::ocsp::OCSPResponse<'static>> {
        if let Some(v) = self.inner.get() {
            return Ok(v.as_ref());
        }
        let mut decoder = Decoder::new(self.raw, Encoding::Der);
        let decoded = decoder.decode().map_err(|e| {
            pyo3::exceptions::PyValueError::new_err(format!("OCSPResponse DER decode failed: {e}"))
        })?;
        let _ = self.inner.set(Box::new(decoded));
        Ok(self.inner.get().unwrap().as_ref())
    }
}

#[pymethods]
impl PyOcspResponse {
    /// Parse a DER-encoded OCSP Response.
    #[staticmethod]
    fn from_der(py: Python<'_>, data: Bound<'_, PyBytes>) -> PyResult<Self> {
        let py_bytes = data.unbind();
        // SAFETY: `py_bytes` holds a strong reference (Py<PyBytes>) that
        // keeps the Python bytes object alive for the lifetime of this struct.
        // CPython's bytes objects have a fixed-address, non-relocating payload
        // buffer (CPython has no moving GC).  The slice lifetime is extended
        // to 'static; the actual safety invariants are:
        //   (1) All reads of `raw` go through `&self`; no borrow of the struct
        //       can outlive the struct, so `raw` is never read after drop begins.
        //   (2) `raw: &'static [u8]` has no destructor (fat pointer, no heap
        //       allocation), so field drop order does not cause use-after-free.
        //   (3) `inner` contains only borrow-typed fields; dropping
        //       Box<OCSPResponse<'static>> does not read through the contained
        //       &'static slices (borrows have no destructors).
        // CPython-only: does not hold for PyPy or GraalPy.
        let raw: &'static [u8] = unsafe {
            let s = py_bytes.bind(py).as_bytes();
            std::slice::from_raw_parts(s.as_ptr(), s.len())
        };
        {
            let mut d = Decoder::new(raw, Encoding::Der);
            d.read_tag()
                .map_err(|e| pyo3::exceptions::PyValueError::new_err(format!("{e}")))?;
            d.read_length()
                .map_err(|e| pyo3::exceptions::PyValueError::new_err(format!("{e}")))?;
        }
        Ok(Self {
            _data: py_bytes,
            raw,
            inner: OnceLock::new(),
            status_cache: OnceLock::new(),
            response_type_oid_cache: OnceLock::new(),
            response_bytes_cache: OnceLock::new(),
        })
    }

    /// Parse a PEM-encoded OCSP Response.
    ///
    /// Returns a single :class:`OCSPResponse` for one PEM block, or a
    /// :class:`list` of :class:`OCSPResponse` objects when multiple blocks are
    /// present.  Raises :exc:`ValueError` if no PEM block is found.
    ///
    /// ```python
    /// resp = OCSPResponse.from_pem(open("ocsp.pem", "rb").read())
    /// print(resp.status)
    /// ```
    #[staticmethod]
    fn from_pem<'py>(py: Python<'py>, data: Bound<'_, PyBytes>) -> PyResult<Bound<'py, PyAny>> {
        pem_blocks_to_pyobject(py, data.as_bytes(), |py, bytes| {
            let obj = Self::from_der(py, bytes)?;
            Ok(Py::new(py, obj)?.into_bound(py).into_any())
        })
    }

    /// Serialize one OCSP response or a list of them to PEM format.
    ///
    /// ```python
    /// pem = OCSPResponse.to_pem(resp)
    /// pem = OCSPResponse.to_pem([resp1, resp2])
    /// ```
    #[staticmethod]
    fn to_pem<'py>(
        py: Python<'py>,
        obj_or_list: Bound<'_, PyAny>,
    ) -> PyResult<Bound<'py, PyBytes>> {
        pyobject_to_pem::<Self, _>(py, "OCSP RESPONSE", &obj_or_list, |c| c.raw)
    }

    /// Response status string (e.g. ``"successful"``, ``"tryLater"``).
    #[getter]
    fn status<'py>(&self, py: Python<'py>) -> PyResult<Bound<'py, PyString>> {
        if let Some(cached) = self.status_cache.get() {
            return Ok(cached.clone_ref(py).into_bound(py));
        }
        let s = ocsp_status_str(self.ocsp()?.response_status);
        let py_str = PyString::new(py, s).unbind();
        let _ = self.status_cache.set(py_str.clone_ref(py));
        Ok(py_str.into_bound(py))
    }

    /// Dotted-decimal OID of the response type, or ``None`` for error responses
    /// that carry no ``responseBytes`` (e.g. ``tryLater``).
    ///
    /// For successful responses this is typically the id-pkix-ocsp-basic OID
    /// (``"1.3.6.1.5.5.7.48.1.1"``).
    #[getter]
    fn response_type_oid<'py>(
        &self,
        py: Python<'py>,
    ) -> PyResult<Option<Bound<'py, PyObjectIdentifier>>> {
        if let Some(cached) = self.response_type_oid_cache.get() {
            return Ok(cached.as_ref().map(|o| o.clone_ref(py).into_bound(py)));
        }
        let computed: Option<Py<PyObjectIdentifier>> = self
            .ocsp()?
            .response_bytes
            .as_ref()
            .map(|rb| Py::new(py, PyObjectIdentifier::from_oid(rb.response_type.clone())))
            .transpose()?;
        let _ = self
            .response_type_oid_cache
            .set(computed.as_ref().map(|o| o.clone_ref(py)));
        Ok(computed.map(|o| o.into_bound(py)))
    }

    /// Raw DER bytes of the embedded response (the OCTET STRING content of
    /// ``ResponseBytes``), or ``None`` for error responses.
    ///
    /// For id-pkix-ocsp-basic responses, these bytes are a DER-encoded
    /// ``BasicOCSPResponse``.
    #[getter]
    fn response_bytes<'py>(&self, py: Python<'py>) -> PyResult<Option<Bound<'py, PyBytes>>> {
        if let Some(cached) = self.response_bytes_cache.get() {
            return Ok(cached.as_ref().map(|b| b.clone_ref(py).into_bound(py)));
        }
        let computed: Option<Bound<'py, PyBytes>> = self
            .ocsp()?
            .response_bytes
            .as_ref()
            .map(|rb| PyBytes::new(py, rb.response.as_bytes()));
        let to_store = computed.as_ref().map(|b| b.as_unbound().clone_ref(py));
        let _ = self.response_bytes_cache.set(to_store);
        Ok(computed)
    }

    /// Complete DER encoding of this OCSP response (the original bytes passed to ``from_der``).
    fn to_der<'py>(&self, py: Python<'py>) -> Bound<'py, PyBytes> {
        self._data.clone_ref(py).into_bound(py)
    }

    fn __repr__(&self) -> PyResult<String> {
        Ok(format!(
            "OCSPResponse(status={})",
            ocsp_status_str(self.ocsp()?.response_status),
        ))
    }
}

// ── PKCS#7 / PKCS#12 free functions ─────────────────────────────────────────

/// Build a `PyList[Certificate]` from a `Vec<Vec<u8>>` of DER-encoded certs.
fn der_certs_to_pylist<'py>(
    py: Python<'py>,
    der_certs: Vec<Vec<u8>>,
) -> PyResult<Bound<'py, PyList>> {
    let list = PyList::empty(py);
    for der in der_certs {
        let py_bytes = PyBytes::new(py, &der);
        let cert = PyCertificate::from_der(py, py_bytes)?;
        list.append(Py::new(py, cert)?.into_bound(py))?;
    }
    Ok(list)
}

/// Extract X.509 certificates from a PKCS#7 SignedData blob (DER or BER).
///
/// Accepts raw DER or BER input; BER indefinite-length encodings (common in
/// PKCS#7 files produced by older tools) are handled transparently.  Returns
/// a list of :class:`Certificate` objects in document order.
///
/// Raises :exc:`ValueError` on any ASN.1 structural error or if the input
/// is not id-signedData.
///
/// ```python,ignore
/// data = open("bundle.p7b", "rb").read()
/// certs = synta.load_der_pkcs7_certificates(data)
/// for cert in certs:
///     print(cert.subject)
/// ```
#[pyfunction]
pub fn load_der_pkcs7_certificates<'py>(
    py: Python<'py>,
    data: &[u8],
) -> PyResult<Bound<'py, PyList>> {
    let der_certs = synta_certificate::certs_from_pkcs7(data)
        .map_err(|e| pyo3::exceptions::PyValueError::new_err(format!("{e}")))?;
    der_certs_to_pylist(py, der_certs)
}

/// Extract X.509 certificates from a PEM-encoded PKCS#7 SignedData blob.
///
/// Decodes PEM block(s) in ``data`` (any label is accepted: ``PKCS7``,
/// ``CMS``, ``CERTIFICATE``, etc.) then calls
/// :func:`load_der_pkcs7_certificates` on each DER payload.  All certificates
/// across all blocks are returned as a single flat list.
///
/// Raises :exc:`ValueError` if no PEM block is found or if any block fails
/// to parse as PKCS#7 SignedData.
///
/// ```python,ignore
/// data = open("bundle.pem", "rb").read()
/// certs = synta.load_pem_pkcs7_certificates(data)
/// for cert in certs:
///     print(cert.subject)
/// ```
#[pyfunction]
pub fn load_pem_pkcs7_certificates<'py>(
    py: Python<'py>,
    data: &[u8],
) -> PyResult<Bound<'py, PyList>> {
    let blocks = synta_certificate::pem_blocks(data);
    if blocks.is_empty() {
        return Err(pyo3::exceptions::PyValueError::new_err(
            "no PEM block found in input",
        ));
    }
    let mut all_certs: Vec<Vec<u8>> = Vec::new();
    for (_, der) in &blocks {
        let certs = synta_certificate::certs_from_pkcs7(der)
            .map_err(|e| pyo3::exceptions::PyValueError::new_err(format!("{e}")))?;
        all_certs.extend(certs);
    }
    der_certs_to_pylist(py, all_certs)
}

/// Extract X.509 certificates from a PKCS#12 archive.
///
/// Accepts raw DER or BER input; the encoding is detected automatically.
/// Returns a list of :class:`Certificate` objects in document order.
/// Non-certificate bag types (``keyBag``, ``pkcs8ShroudedKeyBag``,
/// ``crlBag``, ``secretBag``) are silently skipped.
///
/// ``password`` is the archive password as raw bytes (UTF-8 without a NUL
/// terminator).  Pass ``b""`` or omit the argument for password-less archives.
///
/// Encrypted bags are supported when the ``openssl`` Cargo feature is enabled.
/// Without that feature a :exc:`ValueError` is raised on any encrypted bag.
///
/// ```python,ignore
/// data = open("archive.p12", "rb").read()
/// certs = synta.load_pkcs12_certificates(data, b"s3cr3t")
/// for cert in certs:
///     print(cert.subject)
/// ```
#[pyfunction]
#[pyo3(signature = (data, password = None))]
pub fn load_pkcs12_certificates<'py>(
    py: Python<'py>,
    data: &[u8],
    password: Option<&[u8]>,
) -> PyResult<Bound<'py, PyList>> {
    let pw = password.unwrap_or(b"");
    #[cfg(feature = "openssl")]
    let der_certs =
        synta_certificate::certs_from_pkcs12(data, pw, &synta_certificate::OpensslDecryptor)
            .map_err(|e| pyo3::exceptions::PyValueError::new_err(format!("{e}")))?;
    #[cfg(not(feature = "openssl"))]
    let der_certs = synta_certificate::certs_from_pkcs12(data, pw, &synta_certificate::NoCrypto)
        .map_err(|e| pyo3::exceptions::PyValueError::new_err(format!("{e}")))?;
    der_certs_to_pylist(py, der_certs)
}

/// Extract PKCS#8 private keys from a PKCS#12 archive.
///
/// Returns a :class:`list` of :class:`bytes` objects, one per private key
/// found in ``keyBag`` (unencrypted) and ``pkcs8ShroudedKeyBag`` (encrypted,
/// decrypted when the ``openssl`` Cargo feature is enabled and ``password``
/// is given) entries.  Each element is a DER-encoded ``OneAsymmetricKey``
/// (PKCS#8) structure, suitable for passing to a cryptography library.
///
/// ``certBag``, ``crlBag``, ``secretBag`` and any unknown bag types are
/// silently skipped.
///
/// ```python,ignore
/// data = open("archive.p12", "rb").read()
/// keys = synta.load_pkcs12_keys(data, b"s3cr3t")
/// for key_der in keys:
///     from cryptography.hazmat.primitives.serialization import load_der_private_key
///     key = load_der_private_key(key_der, None)
/// ```
#[pyfunction]
#[pyo3(signature = (data, password = None))]
pub fn load_pkcs12_keys<'py>(
    py: Python<'py>,
    data: &[u8],
    password: Option<&[u8]>,
) -> PyResult<Bound<'py, PyList>> {
    let pw = password.unwrap_or(b"");
    #[cfg(feature = "openssl")]
    let der_keys =
        synta_certificate::keys_from_pkcs12(data, pw, &synta_certificate::OpensslDecryptor)
            .map_err(|e| pyo3::exceptions::PyValueError::new_err(format!("{e}")))?;
    #[cfg(not(feature = "openssl"))]
    let der_keys = synta_certificate::keys_from_pkcs12(data, pw, &synta_certificate::NoCrypto)
        .map_err(|e| pyo3::exceptions::PyValueError::new_err(format!("{e}")))?;
    let list = PyList::empty(py);
    for der in der_keys {
        list.append(PyBytes::new(py, &der))?;
    }
    Ok(list)
}

/// Extract both certificates and private keys from a PKCS#12 archive.
///
/// Returns a 2-tuple ``(certs, keys)`` where:
///
/// - ``certs`` is a :class:`list` of :class:`Certificate` objects.
/// - ``keys`` is a :class:`list` of :class:`bytes`, each a DER-encoded
///   PKCS#8 ``OneAsymmetricKey`` structure.
///
/// Encrypted bags are decrypted with ``password`` when the ``openssl``
/// Cargo feature is enabled; without it, encrypted bags are silently
/// skipped and a :exc:`ValueError` is raised only on structural errors.
/// Pass ``b""`` or omit ``password`` for password-less archives.
///
/// Use :func:`load_pkcs12_certificates` if you only need certificates, or
/// :func:`load_pkcs12_keys` if you only need keys.
///
/// ```python,ignore
/// data = open("archive.p12", "rb").read()
/// certs, keys = synta.load_pkcs12(data, b"s3cr3t")
/// for cert in certs:
///     print(cert.subject)
/// for key_der in keys:
///     from cryptography.hazmat.primitives.serialization import load_der_private_key
///     key = load_der_private_key(key_der, None)
/// ```
#[pyfunction]
#[pyo3(signature = (data, password = None))]
pub fn load_pkcs12<'py>(
    py: Python<'py>,
    data: &[u8],
    password: Option<&[u8]>,
) -> PyResult<Bound<'py, pyo3::types::PyTuple>> {
    let pw = password.unwrap_or(b"");
    #[cfg(feature = "openssl")]
    let pki = synta_certificate::pki_from_pkcs12(data, pw, &synta_certificate::OpensslDecryptor)
        .map_err(|e| pyo3::exceptions::PyValueError::new_err(format!("{e}")))?;
    #[cfg(not(feature = "openssl"))]
    let pki = synta_certificate::pki_from_pkcs12(data, pw, &synta_certificate::NoCrypto)
        .map_err(|e| pyo3::exceptions::PyValueError::new_err(format!("{e}")))?;
    let certs = der_certs_to_pylist(py, pki.certs)?;
    let keys = PyList::empty(py);
    for der in pki.keys {
        keys.append(PyBytes::new(py, &der))?;
    }
    pyo3::types::PyTuple::new(py, [certs.into_any(), keys.into_any()])
}

/// Auto-detect the encoding of ``data`` and return every PKI object as a
/// ``(label, der_bytes)`` tuple, in document order.
///
/// Supported formats: PEM (any label), PKCS#7 / CMS SignedData (DER or BER),
/// PKCS#12 PFX (DER or BER), and raw DER.
///
/// **Labels:**
///
/// - PEM blocks whose payload is a PKCS#7 ``ContentInfo`` (detected by
///   structure, not label) are expanded: the embedded certificates are
///   extracted and each is returned as ``("CERTIFICATE", der)``.
/// - All other PEM block types pass through with their original label
///   (e.g. ``"CERTIFICATE"``, ``"PRIVATE KEY"``).  Malformed PEM blocks
///   (bad base64, truncated header) are silently skipped.
/// - Binary PKCS#7 and raw DER yield ``"CERTIFICATE"`` labels.
/// - Binary PKCS#12 yields ``"CERTIFICATE"`` for ``certBag`` entries and
///   ``"PRIVATE KEY"`` for ``keyBag`` / ``pkcs8ShroudedKeyBag`` entries.
///
/// **Decryption:**
///
/// ``password`` applies only to PKCS#12 archives.  When ``password`` is
/// given **and** the library was built with the ``openssl`` Cargo feature,
/// encrypted SafeBags are decrypted.  Otherwise encrypted bags are silently
/// skipped; unencrypted certificates in the same archive are still returned.
///
/// :raises ValueError: For any structural failure:
///
///   - A PKCS#7 block (binary or PEM-wrapped) has malformed DER, or its
///     ``contentType`` OID is not ``id-signedData``.
///   - The PKCS#12 input has a structural ASN.1 error.
///   - ``password`` was supplied with the ``openssl`` feature enabled and
///     decryption of an encrypted SafeBag failed (e.g. wrong password,
///     unsupported cipher).
///   - The PKCS#12 authSafe uses an unsupported ``ContentInfo`` type.
///
/// :raises TypeError: If ``data`` is not :class:`bytes`, or ``password``
///   is not :class:`bytes` or ``None``.
///
/// ```python,ignore
/// data = open("bundle.p7b", "rb").read()
/// blocks = synta.read_pki_blocks(data)
/// for label, der in blocks:
///     print(f"{label}: {len(der)} bytes")
///
/// # PKCS#12 with encryption
/// data = open("archive.p12", "rb").read()
/// blocks = synta.read_pki_blocks(data, b"s3cr3t")
/// ```
#[pyfunction]
#[pyo3(signature = (data, password = None))]
pub fn read_pki_blocks<'py>(
    py: Python<'py>,
    data: &[u8],
    password: Option<&[u8]>,
) -> PyResult<Bound<'py, PyList>> {
    let pw = password.unwrap_or(b"");
    #[cfg(feature = "openssl")]
    let blocks = if password.is_some() {
        synta_certificate::read_pki_blocks(
            data,
            pw,
            Some(&synta_certificate::OpensslDecryptor as &dyn synta_certificate::PkiDecryptor),
        )
    } else {
        synta_certificate::read_pki_blocks(data, pw, None::<&dyn synta_certificate::PkiDecryptor>)
    };
    #[cfg(not(feature = "openssl"))]
    let blocks =
        synta_certificate::read_pki_blocks(data, pw, None::<&dyn synta_certificate::PkiDecryptor>);
    let blocks = blocks.map_err(|e| pyo3::exceptions::PyValueError::new_err(format!("{e}")))?;
    let list = PyList::empty(py);
    for (label, der) in blocks {
        let tuple = pyo3::types::PyTuple::new(
            py,
            [
                PyString::new(py, &label).into_any(),
                PyBytes::new(py, &der).into_any(),
            ],
        )?;
        list.append(tuple)?;
    }
    Ok(list)
}

// ── PyKEMRecipientInfo ────────────────────────────────────────────────────────

/// KEM Recipient Info (RFC 9629) accessible from Python.
///
/// ``KEMRecipientInfo`` carries a quantum-safe KEM-encapsulated content-encryption
/// key inside a CMS ``EnvelopedData`` structure.  It is carried as an
/// ``OtherRecipientInfo`` alternative identified by ``id-ori-kem``.
///
/// ```python,ignore
/// kemri = KEMRecipientInfo.from_der(raw)
/// print(kemri.kem_algorithm_oid)  # e.g. ObjectIdentifier("1.3.6.1.4.1.22554.5.6.1")
/// key_bytes = kemri.encrypted_key
/// ```
#[pyclass(frozen, name = "KEMRecipientInfo")]
pub struct PyKEMRecipientInfo {
    _data: Py<PyBytes>,
    raw: &'static [u8],
    inner: OnceLock<Box<synta_certificate::cms_kem_types::KEMRecipientInfo<'static>>>,
    // OID caches
    kem_algorithm_oid_cache: OnceLock<Py<PyObjectIdentifier>>,
    kdf_algorithm_oid_cache: OnceLock<Py<PyObjectIdentifier>>,
    key_encryption_algorithm_oid_cache: OnceLock<Py<PyObjectIdentifier>>,
    // Optional DER params caches
    kem_algorithm_params_cache: OnceLock<Option<Py<PyBytes>>>,
    kdf_algorithm_params_cache: OnceLock<Option<Py<PyBytes>>>,
    key_encryption_algorithm_params_cache: OnceLock<Option<Py<PyBytes>>>,
    // Byte field caches
    recipient_id_cache: OnceLock<Py<PyBytes>>,
    kem_ciphertext_cache: OnceLock<Py<PyBytes>>,
    encrypted_key_cache: OnceLock<Py<PyBytes>>,
    // Optional byte field caches
    ukm_cache: OnceLock<Option<Py<PyBytes>>>,
}

impl PyKEMRecipientInfo {
    fn kemri(&self) -> PyResult<&synta_certificate::cms_kem_types::KEMRecipientInfo<'static>> {
        if let Some(v) = self.inner.get() {
            return Ok(v.as_ref());
        }
        let mut decoder = Decoder::new(self.raw, Encoding::Der);
        let decoded = decoder.decode().map_err(|e| {
            pyo3::exceptions::PyValueError::new_err(format!(
                "KEMRecipientInfo DER decode failed: {e}"
            ))
        })?;
        let _ = self.inner.set(Box::new(decoded));
        Ok(self.inner.get().unwrap().as_ref())
    }
}

#[pymethods]
impl PyKEMRecipientInfo {
    /// Parse a DER-encoded ``KEMRecipientInfo`` SEQUENCE.
    #[staticmethod]
    fn from_der(py: Python<'_>, data: Bound<'_, PyBytes>) -> PyResult<Self> {
        let py_bytes = data.unbind();
        // SAFETY: `py_bytes` holds a strong reference (Py<PyBytes>) that
        // keeps the Python bytes object alive for the lifetime of this struct.
        // CPython's bytes objects have a fixed-address, non-relocating payload
        // buffer (CPython has no moving GC).  The slice lifetime is extended
        // to 'static; the actual safety invariants are:
        //   (1) All reads of `raw` go through `&self`; no borrow of the struct
        //       can outlive the struct, so `raw` is never read after drop begins.
        //   (2) `raw: &'static [u8]` has no destructor (fat pointer, no heap
        //       allocation), so field drop order does not cause use-after-free.
        //   (3) `inner` contains only borrow-typed fields in the decoded type;
        //       dropping the Box does not read through the contained &'static
        //       slices (borrows have no destructors in Rust).
        // CPython-only: does not hold for PyPy or GraalPy.
        let raw: &'static [u8] = unsafe {
            let s = py_bytes.bind(py).as_bytes();
            std::slice::from_raw_parts(s.as_ptr(), s.len())
        };
        {
            let mut d = Decoder::new(raw, Encoding::Der);
            d.read_tag()
                .map_err(|e| pyo3::exceptions::PyValueError::new_err(format!("{e}")))?;
            d.read_length()
                .map_err(|e| pyo3::exceptions::PyValueError::new_err(format!("{e}")))?;
        }
        Ok(Self {
            _data: py_bytes,
            raw,
            inner: OnceLock::new(),
            kem_algorithm_oid_cache: OnceLock::new(),
            kdf_algorithm_oid_cache: OnceLock::new(),
            key_encryption_algorithm_oid_cache: OnceLock::new(),
            kem_algorithm_params_cache: OnceLock::new(),
            kdf_algorithm_params_cache: OnceLock::new(),
            key_encryption_algorithm_params_cache: OnceLock::new(),
            recipient_id_cache: OnceLock::new(),
            kem_ciphertext_cache: OnceLock::new(),
            encrypted_key_cache: OnceLock::new(),
            ukm_cache: OnceLock::new(),
        })
    }

    /// Complete DER encoding of this ``KEMRecipientInfo``
    /// (the original bytes passed to ``from_der``).
    fn to_der<'py>(&self, py: Python<'py>) -> Bound<'py, PyBytes> {
        self._data.clone_ref(py).into_bound(py)
    }

    /// CMS version (always ``0`` for KEMRecipientInfo per RFC 9629).
    #[getter]
    fn version(&self) -> PyResult<i64> {
        Ok(self.kemri()?.version.as_i64().unwrap_or(0))
    }

    /// Raw DER bytes of the ``RecipientIdentifier`` CHOICE field.
    ///
    /// Decode with :class:`Decoder` to distinguish ``issuerAndSerialNumber``
    /// (SEQUENCE) from ``subjectKeyIdentifier`` (context tag ``[0]``).
    #[getter]
    fn recipient_id<'py>(&self, py: Python<'py>) -> PyResult<Bound<'py, PyBytes>> {
        if let Some(cached) = self.recipient_id_cache.get() {
            return Ok(cached.clone_ref(py).into_bound(py));
        }
        let py_bytes = PyBytes::new(py, self.kemri()?.rid.as_bytes()).unbind();
        let _ = self.recipient_id_cache.set(py_bytes.clone_ref(py));
        Ok(py_bytes.into_bound(py))
    }

    /// OID of the KEM algorithm (the ``kem`` field).
    ///
    /// For ML-KEM-768 this is ``2.16.840.1.101.3.4.4.2``.
    #[getter]
    fn kem_algorithm_oid<'py>(&self, py: Python<'py>) -> PyResult<Bound<'py, PyObjectIdentifier>> {
        if let Some(cached) = self.kem_algorithm_oid_cache.get() {
            return Ok(cached.clone_ref(py).into_bound(py));
        }
        let obj = Py::new(
            py,
            PyObjectIdentifier::from_oid(self.kemri()?.kem.algorithm.clone()),
        )?;
        let _ = self.kem_algorithm_oid_cache.set(obj.clone_ref(py));
        Ok(obj.into_bound(py))
    }

    /// Raw DER bytes of the KEM algorithm parameters, or ``None``.
    #[getter]
    fn kem_algorithm_params<'py>(&self, py: Python<'py>) -> PyResult<Option<Bound<'py, PyBytes>>> {
        if let Some(cached) = self.kem_algorithm_params_cache.get() {
            return Ok(cached.as_ref().map(|b| b.clone_ref(py).into_bound(py)));
        }
        let computed = encode_element_opt(py, self.kemri()?.kem.parameters.as_ref())?;
        let to_store = computed.as_ref().map(|b| b.as_unbound().clone_ref(py));
        let _ = self.kem_algorithm_params_cache.set(to_store);
        Ok(computed)
    }

    /// Raw bytes of the KEM ciphertext (``kemct`` field, the encapsulated key).
    #[getter]
    fn kem_ciphertext<'py>(&self, py: Python<'py>) -> PyResult<Bound<'py, PyBytes>> {
        if let Some(cached) = self.kem_ciphertext_cache.get() {
            return Ok(cached.clone_ref(py).into_bound(py));
        }
        let py_bytes = PyBytes::new(py, self.kemri()?.kemct.as_bytes()).unbind();
        let _ = self.kem_ciphertext_cache.set(py_bytes.clone_ref(py));
        Ok(py_bytes.into_bound(py))
    }

    /// OID of the key-derivation algorithm (the ``kdf`` field).
    #[getter]
    fn kdf_algorithm_oid<'py>(&self, py: Python<'py>) -> PyResult<Bound<'py, PyObjectIdentifier>> {
        if let Some(cached) = self.kdf_algorithm_oid_cache.get() {
            return Ok(cached.clone_ref(py).into_bound(py));
        }
        let obj = Py::new(
            py,
            PyObjectIdentifier::from_oid(self.kemri()?.kdf.algorithm.clone()),
        )?;
        let _ = self.kdf_algorithm_oid_cache.set(obj.clone_ref(py));
        Ok(obj.into_bound(py))
    }

    /// Raw DER bytes of the KDF algorithm parameters, or ``None``.
    #[getter]
    fn kdf_algorithm_params<'py>(&self, py: Python<'py>) -> PyResult<Option<Bound<'py, PyBytes>>> {
        if let Some(cached) = self.kdf_algorithm_params_cache.get() {
            return Ok(cached.as_ref().map(|b| b.clone_ref(py).into_bound(py)));
        }
        let computed = encode_element_opt(py, self.kemri()?.kdf.parameters.as_ref())?;
        let to_store = computed.as_ref().map(|b| b.as_unbound().clone_ref(py));
        let _ = self.kdf_algorithm_params_cache.set(to_store);
        Ok(computed)
    }

    /// KEK (key-encryption key) length in bytes (``kekLength`` field, range 1..65535).
    #[getter]
    fn kek_length(&self) -> PyResult<i64> {
        Ok(self.kemri()?.kek_length.as_i64().unwrap_or(0))
    }

    /// User keying material bytes (``ukm`` field), or ``None`` if absent.
    #[getter]
    fn ukm<'py>(&self, py: Python<'py>) -> PyResult<Option<Bound<'py, PyBytes>>> {
        if let Some(cached) = self.ukm_cache.get() {
            return Ok(cached.as_ref().map(|b| b.clone_ref(py).into_bound(py)));
        }
        let computed = self
            .kemri()?
            .ukm
            .as_ref()
            .map(|u| PyBytes::new(py, u.as_bytes()));
        let to_store = computed.as_ref().map(|b| b.as_unbound().clone_ref(py));
        let _ = self.ukm_cache.set(to_store);
        Ok(computed)
    }

    /// OID of the key-encryption (key-wrap) algorithm (the ``wrap`` field).
    #[getter]
    fn key_encryption_algorithm_oid<'py>(
        &self,
        py: Python<'py>,
    ) -> PyResult<Bound<'py, PyObjectIdentifier>> {
        if let Some(cached) = self.key_encryption_algorithm_oid_cache.get() {
            return Ok(cached.clone_ref(py).into_bound(py));
        }
        let obj = Py::new(
            py,
            PyObjectIdentifier::from_oid(self.kemri()?.wrap.algorithm.clone()),
        )?;
        let _ = self
            .key_encryption_algorithm_oid_cache
            .set(obj.clone_ref(py));
        Ok(obj.into_bound(py))
    }

    /// Raw DER bytes of the key-encryption algorithm parameters, or ``None``.
    #[getter]
    fn key_encryption_algorithm_params<'py>(
        &self,
        py: Python<'py>,
    ) -> PyResult<Option<Bound<'py, PyBytes>>> {
        if let Some(cached) = self.key_encryption_algorithm_params_cache.get() {
            return Ok(cached.as_ref().map(|b| b.clone_ref(py).into_bound(py)));
        }
        let computed = encode_element_opt(py, self.kemri()?.wrap.parameters.as_ref())?;
        let to_store = computed.as_ref().map(|b| b.as_unbound().clone_ref(py));
        let _ = self.key_encryption_algorithm_params_cache.set(to_store);
        Ok(computed)
    }

    /// Encrypted content-encryption key bytes (the ``encryptedKey`` OCTET STRING).
    #[getter]
    fn encrypted_key<'py>(&self, py: Python<'py>) -> PyResult<Bound<'py, PyBytes>> {
        if let Some(cached) = self.encrypted_key_cache.get() {
            return Ok(cached.clone_ref(py).into_bound(py));
        }
        let py_bytes = PyBytes::new(py, self.kemri()?.encrypted_key.as_bytes()).unbind();
        let _ = self.encrypted_key_cache.set(py_bytes.clone_ref(py));
        Ok(py_bytes.into_bound(py))
    }

    fn __repr__(&self) -> PyResult<String> {
        let kemri = self.kemri()?;
        Ok(format!(
            "KEMRecipientInfo(kem={}, kdf={}, kek_length={})",
            kemri.kem.algorithm,
            kemri.kdf.algorithm,
            kemri.kek_length.as_i64().unwrap_or(0),
        ))
    }
}

// ── PyCMSORIforKEMOtherInfo ───────────────────────────────────────────────────

/// CMS ORI KEM Other Info (RFC 9629 §6.2) accessible from Python.
///
/// ``CMSORIforKEMOtherInfo`` is used as the ``otherInfo`` input to the KDF
/// when deriving a KEK from a KEM shared secret.  It binds the key-encryption
/// algorithm, KEK length, and optional UKM to the KDF computation.
///
/// ```python,ignore
/// info = CMSORIforKEMOtherInfo.from_der(raw)
/// print(info.kek_length)      # e.g. 32
/// print(info.key_encryption_algorithm_oid)
/// ```
#[pyclass(frozen, name = "CMSORIforKEMOtherInfo")]
pub struct PyCMSORIforKEMOtherInfo {
    _data: Py<PyBytes>,
    raw: &'static [u8],
    inner: OnceLock<Box<synta_certificate::cms_kem_types::CMSORIforKEMOtherInfo<'static>>>,
    key_encryption_algorithm_oid_cache: OnceLock<Py<PyObjectIdentifier>>,
    key_encryption_algorithm_params_cache: OnceLock<Option<Py<PyBytes>>>,
    ukm_cache: OnceLock<Option<Py<PyBytes>>>,
}

impl PyCMSORIforKEMOtherInfo {
    fn info(&self) -> PyResult<&synta_certificate::cms_kem_types::CMSORIforKEMOtherInfo<'static>> {
        if let Some(v) = self.inner.get() {
            return Ok(v.as_ref());
        }
        let mut decoder = Decoder::new(self.raw, Encoding::Der);
        let decoded = decoder.decode().map_err(|e| {
            pyo3::exceptions::PyValueError::new_err(format!(
                "CMSORIforKEMOtherInfo DER decode failed: {e}"
            ))
        })?;
        let _ = self.inner.set(Box::new(decoded));
        Ok(self.inner.get().unwrap().as_ref())
    }
}

#[pymethods]
impl PyCMSORIforKEMOtherInfo {
    /// Parse a DER-encoded ``CMSORIforKEMOtherInfo`` SEQUENCE.
    #[staticmethod]
    fn from_der(py: Python<'_>, data: Bound<'_, PyBytes>) -> PyResult<Self> {
        let py_bytes = data.unbind();
        // SAFETY: `py_bytes` holds a strong reference (Py<PyBytes>) that
        // keeps the Python bytes object alive for the lifetime of this struct.
        // CPython's bytes objects have a fixed-address, non-relocating payload
        // buffer (CPython has no moving GC).  The slice lifetime is extended
        // to 'static; the actual safety invariants are:
        //   (1) All reads of `raw` go through `&self`; no borrow of the struct
        //       can outlive the struct, so `raw` is never read after drop begins.
        //   (2) `raw: &'static [u8]` has no destructor (fat pointer, no heap
        //       allocation), so field drop order does not cause use-after-free.
        //   (3) `inner` contains only borrow-typed fields in the decoded type;
        //       dropping the Box does not read through the contained &'static
        //       slices (borrows have no destructors in Rust).
        // CPython-only: does not hold for PyPy or GraalPy.
        let raw: &'static [u8] = unsafe {
            let s = py_bytes.bind(py).as_bytes();
            std::slice::from_raw_parts(s.as_ptr(), s.len())
        };
        {
            let mut d = Decoder::new(raw, Encoding::Der);
            d.read_tag()
                .map_err(|e| pyo3::exceptions::PyValueError::new_err(format!("{e}")))?;
            d.read_length()
                .map_err(|e| pyo3::exceptions::PyValueError::new_err(format!("{e}")))?;
        }
        Ok(Self {
            _data: py_bytes,
            raw,
            inner: OnceLock::new(),
            key_encryption_algorithm_oid_cache: OnceLock::new(),
            key_encryption_algorithm_params_cache: OnceLock::new(),
            ukm_cache: OnceLock::new(),
        })
    }

    /// Complete DER encoding of this ``CMSORIforKEMOtherInfo``
    /// (the original bytes passed to ``from_der``).
    fn to_der<'py>(&self, py: Python<'py>) -> Bound<'py, PyBytes> {
        self._data.clone_ref(py).into_bound(py)
    }

    /// OID of the key-encryption (key-wrap) algorithm.
    #[getter]
    fn key_encryption_algorithm_oid<'py>(
        &self,
        py: Python<'py>,
    ) -> PyResult<Bound<'py, PyObjectIdentifier>> {
        if let Some(cached) = self.key_encryption_algorithm_oid_cache.get() {
            return Ok(cached.clone_ref(py).into_bound(py));
        }
        let obj = Py::new(
            py,
            PyObjectIdentifier::from_oid(self.info()?.wrap.algorithm.clone()),
        )?;
        let _ = self
            .key_encryption_algorithm_oid_cache
            .set(obj.clone_ref(py));
        Ok(obj.into_bound(py))
    }

    /// Raw DER bytes of the key-encryption algorithm parameters, or ``None``.
    #[getter]
    fn key_encryption_algorithm_params<'py>(
        &self,
        py: Python<'py>,
    ) -> PyResult<Option<Bound<'py, PyBytes>>> {
        if let Some(cached) = self.key_encryption_algorithm_params_cache.get() {
            return Ok(cached.as_ref().map(|b| b.clone_ref(py).into_bound(py)));
        }
        let computed = encode_element_opt(py, self.info()?.wrap.parameters.as_ref())?;
        let to_store = computed.as_ref().map(|b| b.as_unbound().clone_ref(py));
        let _ = self.key_encryption_algorithm_params_cache.set(to_store);
        Ok(computed)
    }

    /// KEK length in bytes (``kekLength`` field, range 1..65535).
    #[getter]
    fn kek_length(&self) -> PyResult<i64> {
        Ok(self.info()?.kek_length.as_i64().unwrap_or(0))
    }

    /// User keying material bytes (``ukm`` field), or ``None`` if absent.
    #[getter]
    fn ukm<'py>(&self, py: Python<'py>) -> PyResult<Option<Bound<'py, PyBytes>>> {
        if let Some(cached) = self.ukm_cache.get() {
            return Ok(cached.as_ref().map(|b| b.clone_ref(py).into_bound(py)));
        }
        let computed = self
            .info()?
            .ukm
            .as_ref()
            .map(|u| PyBytes::new(py, u.as_bytes()));
        let to_store = computed.as_ref().map(|b| b.as_unbound().clone_ref(py));
        let _ = self.ukm_cache.set(to_store);
        Ok(computed)
    }

    fn __repr__(&self) -> PyResult<String> {
        let info = self.info()?;
        Ok(format!(
            "CMSORIforKEMOtherInfo(wrap={}, kek_length={})",
            info.wrap.algorithm,
            info.kek_length.as_i64().unwrap_or(0),
        ))
    }
}

// Build and register the ``synta.cms`` submodule.

// ── PyContentInfo ─────────────────────────────────────────────────────────────

/// CMS ContentInfo (RFC 5652 §3) accessible from Python.
///
/// ``ContentInfo`` is the outermost CMS envelope.  It names the content type
/// via an OID and carries the content itself (e.g. a ``SignedData`` or
/// ``EnvelopedData`` SEQUENCE) as an opaque DER blob.
///
/// ```python,ignore
/// ci = ContentInfo.from_der(raw)
/// if ci.content_type_oid == synta.cms.ID_SIGNED_DATA:
///     signed_data_der = ci.content   # raw DER of the [0] EXPLICIT wrapper
/// ```
#[pyclass(frozen, name = "ContentInfo")]
pub struct PyContentInfo {
    _data: Py<PyBytes>,
    raw: &'static [u8],
    inner: OnceLock<Box<synta_certificate::pkcs7_types::ContentInfo<'static>>>,
    content_type_oid_cache: OnceLock<Py<PyObjectIdentifier>>,
    content_cache: OnceLock<Py<PyBytes>>,
}

impl PyContentInfo {
    fn content_info(&self) -> PyResult<&synta_certificate::pkcs7_types::ContentInfo<'static>> {
        if let Some(v) = self.inner.get() {
            return Ok(v.as_ref());
        }
        // Use BER so that indefinite-length PKCS#7 wrappers are accepted.
        let mut decoder = Decoder::new(self.raw, Encoding::Ber);
        let decoded = decoder.decode().map_err(|e| {
            pyo3::exceptions::PyValueError::new_err(format!("ContentInfo BER decode failed: {e}"))
        })?;
        let _ = self.inner.set(Box::new(decoded));
        Ok(self.inner.get().unwrap().as_ref())
    }
}

#[pymethods]
impl PyContentInfo {
    /// Parse a DER- or BER-encoded CMS ``ContentInfo`` SEQUENCE.
    ///
    /// BER indefinite-length encodings (common in PKCS#7 files produced by
    /// older tools and OpenSSL) are accepted in addition to strict DER.
    /// Raises :exc:`ValueError` if the outer SEQUENCE envelope is malformed.
    #[staticmethod]
    fn from_der(py: Python<'_>, data: Bound<'_, PyBytes>) -> PyResult<Self> {
        let py_bytes = data.unbind();
        let raw: &'static [u8] = unsafe {
            let s = py_bytes.bind(py).as_bytes();
            std::slice::from_raw_parts(s.as_ptr(), s.len())
        };
        {
            let mut d = Decoder::new(raw, Encoding::Ber);
            d.read_tag()
                .map_err(|e| pyo3::exceptions::PyValueError::new_err(format!("{e}")))?;
            d.read_length()
                .map_err(|e| pyo3::exceptions::PyValueError::new_err(format!("{e}")))?;
        }
        Ok(Self {
            _data: py_bytes,
            raw,
            inner: OnceLock::new(),
            content_type_oid_cache: OnceLock::new(),
            content_cache: OnceLock::new(),
        })
    }

    /// Return the original bytes passed to :meth:`from_der`.
    fn to_der<'py>(&self, py: Python<'py>) -> Bound<'py, PyBytes> {
        self._data.clone_ref(py).into_bound(py)
    }

    /// OID identifying the content type
    /// (e.g. :data:`ID_SIGNED_DATA`, :data:`ID_ENVELOPED_DATA`).
    #[getter]
    fn content_type_oid<'py>(&self, py: Python<'py>) -> PyResult<Bound<'py, PyObjectIdentifier>> {
        if let Some(cached) = self.content_type_oid_cache.get() {
            return Ok(cached.clone_ref(py).into_bound(py));
        }
        let obj = Py::new(
            py,
            PyObjectIdentifier::from_oid(self.content_info()?.content_type.clone()),
        )?;
        let _ = self.content_type_oid_cache.set(obj.clone_ref(py));
        Ok(obj.into_bound(py))
    }

    /// Raw DER bytes of the ``content`` field.
    ///
    /// This is the entire ``[0] EXPLICIT`` TLV; callers that need the inner
    /// value (e.g. the ``SignedData`` SEQUENCE) should strip the context tag
    /// and length with a :class:`~synta.Decoder`.
    #[getter]
    fn content<'py>(&self, py: Python<'py>) -> PyResult<Bound<'py, PyBytes>> {
        if let Some(cached) = self.content_cache.get() {
            return Ok(cached.clone_ref(py).into_bound(py));
        }
        let py_bytes = PyBytes::new(py, self.content_info()?.content.as_bytes()).unbind();
        let _ = self.content_cache.set(py_bytes.clone_ref(py));
        Ok(py_bytes.into_bound(py))
    }

    fn __repr__(&self) -> PyResult<String> {
        Ok(format!(
            "ContentInfo(content_type={})",
            self.content_info()?.content_type,
        ))
    }
}

// ── PyIssuerAndSerialNumber ───────────────────────────────────────────────────

/// CMS IssuerAndSerialNumber (RFC 5652 §10.2.4) accessible from Python.
///
/// Identifies a recipient or signer by the issuer distinguished name and
/// certificate serial number of their certificate.  Used as one alternative
/// of the ``RecipientIdentifier`` CHOICE inside :class:`KEMRecipientInfo`.
///
/// ```python,ignore
/// ias = IssuerAndSerialNumber.from_der(raw)
/// print(ias.issuer)          # "CN=My CA,O=Example,C=US"
/// print(ias.serial_number)   # 12345678
/// ```
#[pyclass(frozen, name = "IssuerAndSerialNumber")]
pub struct PyIssuerAndSerialNumber {
    _data: Py<PyBytes>,
    raw: &'static [u8],
    inner: OnceLock<Box<synta_certificate::cms_2010_types::IssuerAndSerialNumber<'static>>>,
    issuer_cache: OnceLock<Py<PyString>>,
    issuer_raw_der_cache: OnceLock<Py<PyBytes>>,
    serial_number_cache: OnceLock<Py<PyAny>>,
}

impl PyIssuerAndSerialNumber {
    fn ias(&self) -> PyResult<&synta_certificate::cms_2010_types::IssuerAndSerialNumber<'static>> {
        if let Some(v) = self.inner.get() {
            return Ok(v.as_ref());
        }
        let mut decoder = Decoder::new(self.raw, Encoding::Der);
        let decoded = decoder.decode().map_err(|e| {
            pyo3::exceptions::PyValueError::new_err(format!(
                "IssuerAndSerialNumber DER decode failed: {e}"
            ))
        })?;
        let _ = self.inner.set(Box::new(decoded));
        Ok(self.inner.get().unwrap().as_ref())
    }
}

#[pymethods]
impl PyIssuerAndSerialNumber {
    /// Parse a DER-encoded ``IssuerAndSerialNumber`` SEQUENCE.
    /// Raises :exc:`ValueError` if the outer SEQUENCE envelope is malformed.
    #[staticmethod]
    fn from_der(py: Python<'_>, data: Bound<'_, PyBytes>) -> PyResult<Self> {
        let py_bytes = data.unbind();
        // SAFETY: `py_bytes` holds a strong reference (Py<PyBytes>) that
        // keeps the Python bytes object alive for the lifetime of this struct.
        // CPython's bytes objects have a fixed-address, non-relocating payload
        // buffer (CPython has no moving GC).  The slice lifetime is extended
        // to 'static; the actual safety invariants are:
        //   (1) All reads of `raw` go through `&self`; no borrow of the struct
        //       can outlive the struct, so `raw` is never read after drop begins.
        //   (2) `raw: &'static [u8]` has no destructor (fat pointer, no heap
        //       allocation), so field drop order does not cause use-after-free.
        //   (3) `inner` contains only borrow-typed fields in the decoded type;
        //       dropping the Box does not read through the contained &'static
        //       slices (borrows have no destructors in Rust).
        // CPython-only: does not hold for PyPy or GraalPy.
        let raw: &'static [u8] = unsafe {
            let s = py_bytes.bind(py).as_bytes();
            std::slice::from_raw_parts(s.as_ptr(), s.len())
        };
        {
            let mut d = Decoder::new(raw, Encoding::Der);
            d.read_tag()
                .map_err(|e| pyo3::exceptions::PyValueError::new_err(format!("{e}")))?;
            d.read_length()
                .map_err(|e| pyo3::exceptions::PyValueError::new_err(format!("{e}")))?;
        }
        Ok(Self {
            _data: py_bytes,
            raw,
            inner: OnceLock::new(),
            issuer_cache: OnceLock::new(),
            issuer_raw_der_cache: OnceLock::new(),
            serial_number_cache: OnceLock::new(),
        })
    }

    /// Return the original bytes passed to :meth:`from_der`.
    fn to_der<'py>(&self, py: Python<'py>) -> Bound<'py, PyBytes> {
        self._data.clone_ref(py).into_bound(py)
    }

    /// Issuer distinguished name as an RFC 4514-style string.
    #[getter]
    fn issuer<'py>(&self, py: Python<'py>) -> PyResult<Bound<'py, PyString>> {
        if let Some(cached) = self.issuer_cache.get() {
            return Ok(cached.clone_ref(py).into_bound(py));
        }
        let s = name_to_dn_string(&self.ias()?.issuer);
        let py_str = PyString::new(py, &s).unbind();
        let _ = self.issuer_cache.set(py_str.clone_ref(py));
        Ok(py_str.into_bound(py))
    }

    /// Raw DER bytes of the issuer ``Name`` SEQUENCE.
    #[getter]
    fn issuer_raw_der<'py>(&self, py: Python<'py>) -> PyResult<Bound<'py, PyBytes>> {
        if let Some(cached) = self.issuer_raw_der_cache.get() {
            return Ok(cached.clone_ref(py).into_bound(py));
        }
        let bytes = name_to_der_bytes(&self.ias()?.issuer);
        let py_bytes = PyBytes::new(py, &bytes).unbind();
        let _ = self.issuer_raw_der_cache.set(py_bytes.clone_ref(py));
        Ok(py_bytes.into_bound(py))
    }

    /// Certificate serial number as a Python ``int``.
    ///
    /// Returns a Python ``int`` for serials that fit in 128 bits; for larger
    /// values calls ``int.from_bytes(raw, "big", signed=True)``.
    #[getter]
    fn serial_number<'py>(&self, py: Python<'py>) -> PyResult<Bound<'py, PyAny>> {
        if let Some(cached) = self.serial_number_cache.get() {
            return Ok(cached.clone_ref(py).into_bound(py));
        }
        let serial = &self.ias()?.serial_number;
        let py_int: Py<PyAny> = if let Ok(v) = serial.as_i64() {
            v.into_pyobject(py)?.into_any().unbind()
        } else if let Ok(v) = serial.as_i128() {
            v.into_pyobject(py)?.into_any().unbind()
        } else {
            let bytes_obj = PyBytes::new(py, serial.as_bytes());
            let kwargs = pyo3::types::PyDict::new(py);
            kwargs.set_item(pyo3::intern!(py, "signed"), true)?;
            py.get_type::<pyo3::types::PyInt>()
                .call_method(
                    pyo3::intern!(py, "from_bytes"),
                    (bytes_obj, pyo3::intern!(py, "big")),
                    Some(&kwargs),
                )
                .map(|r| r.unbind())?
        };
        let _ = self.serial_number_cache.set(py_int.clone_ref(py));
        Ok(py_int.into_bound(py))
    }

    fn __repr__(&self) -> PyResult<String> {
        let ias = self.ias()?;
        let serial = &ias.serial_number;
        Ok(format!(
            "IssuerAndSerialNumber(issuer={:?}, serial={})",
            name_to_dn_string(&ias.issuer),
            serial
                .as_i64()
                .map(|v| v.to_string())
                .unwrap_or_else(|_| format!("<{} bytes>", serial.as_bytes().len())),
        ))
    }
}

// ── PySignedData ──────────────────────────────────────────────────────────────

/// CMS ``SignedData`` (RFC 5652 §5) accessible from Python.
///
/// Obtained by parsing the inner content of a :class:`ContentInfo` whose
/// ``content_type_oid`` equals :data:`~synta.cms.ID_SIGNED_DATA`.  Strip the
/// ``[0] EXPLICIT`` wrapper from ``ci.content`` before calling
/// :meth:`from_der`.
///
/// ```python,ignore
/// ci = ContentInfo.from_der(raw)
/// sd = SignedData.from_der(ci.content[4:])  # strip [0] EXPLICIT tag+len
/// print(sd.version)
/// for si in sd.signer_infos:
///     print(si.digest_algorithm_oid)
/// ```
#[pyclass(frozen, name = "SignedData")]
pub struct PySignedData {
    _data: Py<PyBytes>,
    raw: &'static [u8],
    inner: OnceLock<Box<synta_certificate::cms_rfc5652_types::SignedData<'static>>>,
    encap_content_type_cache: OnceLock<Py<PyObjectIdentifier>>,
    encap_content_cache: OnceLock<Option<Py<PyBytes>>>,
    certificates_cache: OnceLock<Option<Py<PyBytes>>>,
    crls_cache: OnceLock<Option<Py<PyBytes>>>,
    signer_infos_cache: OnceLock<Py<PyList>>,
}

impl PySignedData {
    fn signed_data(&self) -> PyResult<&synta_certificate::cms_rfc5652_types::SignedData<'static>> {
        if let Some(v) = self.inner.get() {
            return Ok(v.as_ref());
        }
        let mut decoder = Decoder::new(self.raw, Encoding::Ber);
        let decoded = decoder.decode().map_err(|e| {
            pyo3::exceptions::PyValueError::new_err(format!("SignedData BER decode failed: {e}"))
        })?;
        let _ = self.inner.set(Box::new(decoded));
        Ok(self.inner.get().unwrap().as_ref())
    }
}

#[pymethods]
impl PySignedData {
    /// Parse a DER- or BER-encoded CMS ``SignedData`` SEQUENCE.
    #[staticmethod]
    fn from_der(py: Python<'_>, data: Bound<'_, PyBytes>) -> PyResult<Self> {
        let py_bytes = data.unbind();
        let raw: &'static [u8] = unsafe {
            let s = py_bytes.bind(py).as_bytes();
            std::slice::from_raw_parts(s.as_ptr(), s.len())
        };
        {
            let mut d = Decoder::new(raw, Encoding::Ber);
            d.read_tag()
                .map_err(|e| pyo3::exceptions::PyValueError::new_err(format!("{e}")))?;
            d.read_length()
                .map_err(|e| pyo3::exceptions::PyValueError::new_err(format!("{e}")))?;
        }
        Ok(Self {
            _data: py_bytes,
            raw,
            inner: OnceLock::new(),
            encap_content_type_cache: OnceLock::new(),
            encap_content_cache: OnceLock::new(),
            certificates_cache: OnceLock::new(),
            crls_cache: OnceLock::new(),
            signer_infos_cache: OnceLock::new(),
        })
    }

    /// Return the original bytes passed to :meth:`from_der`.
    fn to_der<'py>(&self, py: Python<'py>) -> Bound<'py, PyBytes> {
        self._data.clone_ref(py).into_bound(py)
    }

    /// CMS version integer.
    #[getter]
    fn version(&self) -> PyResult<i64> {
        Ok(self.signed_data()?.version.as_i64().unwrap_or(0))
    }

    /// OID identifying the encapsulated content type.
    #[getter]
    fn encap_content_type<'py>(&self, py: Python<'py>) -> PyResult<Bound<'py, PyObjectIdentifier>> {
        if let Some(cached) = self.encap_content_type_cache.get() {
            return Ok(cached.clone_ref(py).into_bound(py));
        }
        let obj = Py::new(
            py,
            PyObjectIdentifier::from_oid(
                self.signed_data()?
                    .encap_content_info
                    .e_content_type
                    .clone(),
            ),
        )?;
        let _ = self.encap_content_type_cache.set(obj.clone_ref(py));
        Ok(obj.into_bound(py))
    }

    /// Raw bytes of the encapsulated content OCTET STRING value, or ``None``.
    #[getter]
    fn encap_content<'py>(&self, py: Python<'py>) -> PyResult<Option<Bound<'py, PyBytes>>> {
        if let Some(cached) = self.encap_content_cache.get() {
            return Ok(cached.as_ref().map(|b| b.clone_ref(py).into_bound(py)));
        }
        let computed = self
            .signed_data()?
            .encap_content_info
            .e_content
            .as_ref()
            .map(|c| PyBytes::new(py, c.as_bytes()));
        let to_store = computed.as_ref().map(|b| b.as_unbound().clone_ref(py));
        let _ = self.encap_content_cache.set(to_store);
        Ok(computed)
    }

    /// Raw content bytes of the ``certificates`` field (IMPLICIT ``[0]``), or ``None``.
    ///
    /// These are the **value** bytes captured during IMPLICIT decoding (no
    /// context-tag prefix).  Feed them to a :class:`~synta.Decoder` to iterate
    /// the individual certificate TLVs.
    #[getter]
    fn certificates<'py>(&self, py: Python<'py>) -> PyResult<Option<Bound<'py, PyBytes>>> {
        if let Some(cached) = self.certificates_cache.get() {
            return Ok(cached.as_ref().map(|b| b.clone_ref(py).into_bound(py)));
        }
        let computed = self
            .signed_data()?
            .certificates
            .as_ref()
            .map(|c| PyBytes::new(py, c.as_bytes()));
        let to_store = computed.as_ref().map(|b| b.as_unbound().clone_ref(py));
        let _ = self.certificates_cache.set(to_store);
        Ok(computed)
    }

    /// Raw content bytes of the ``crls`` field (IMPLICIT ``[1]``), or ``None``.
    #[getter]
    fn crls<'py>(&self, py: Python<'py>) -> PyResult<Option<Bound<'py, PyBytes>>> {
        if let Some(cached) = self.crls_cache.get() {
            return Ok(cached.as_ref().map(|b| b.clone_ref(py).into_bound(py)));
        }
        let computed = self
            .signed_data()?
            .crls
            .as_ref()
            .map(|c| PyBytes::new(py, c.as_bytes()));
        let to_store = computed.as_ref().map(|b| b.as_unbound().clone_ref(py));
        let _ = self.crls_cache.set(to_store);
        Ok(computed)
    }

    /// List of :class:`SignerInfo` objects (one per signer).
    #[getter]
    fn signer_infos<'py>(&self, py: Python<'py>) -> PyResult<Bound<'py, PyList>> {
        if let Some(cached) = self.signer_infos_cache.get() {
            return Ok(cached.clone_ref(py).into_bound(py));
        }
        let list = PyList::empty(py);
        for si in self.signed_data()?.signer_infos.elements() {
            let mut enc = synta::Encoder::new(Encoding::Der);
            si.encode(&mut enc)
                .map_err(|e| pyo3::exceptions::PyValueError::new_err(format!("{e}")))?;
            let der = enc
                .finish()
                .map_err(|e| pyo3::exceptions::PyValueError::new_err(format!("{e}")))?;
            let pybytes = PyBytes::new(py, &der).unbind();
            // SAFETY: `pybytes` is a freshly-allocated PyBytes that owns the
            // `der` bytes.  CPython bytes have a fixed-address payload buffer.
            // `pybytes` is moved into `PySignerInfo::_data`, which holds a
            // strong reference for the lifetime of that struct.  `raw_static`
            // (no destructor) is stored in `PySignerInfo::raw`.  No read of
            // `raw_static` can occur after `_data` is dropped (through `&self`
            // borrows that cannot outlive the struct).
            // CPython-only: does not hold for PyPy or GraalPy.
            let raw_static: &'static [u8] = unsafe {
                let s = pybytes.bind(py).as_bytes();
                std::slice::from_raw_parts(s.as_ptr(), s.len())
            };
            let si_obj = Py::new(
                py,
                PySignerInfo {
                    _data: pybytes,
                    raw: raw_static,
                    inner: OnceLock::new(),
                    sid_cache: OnceLock::new(),
                    digest_algorithm_oid_cache: OnceLock::new(),
                    digest_algorithm_params_cache: OnceLock::new(),
                    signature_algorithm_oid_cache: OnceLock::new(),
                    signature_algorithm_params_cache: OnceLock::new(),
                    signature_cache: OnceLock::new(),
                    signed_attrs_cache: OnceLock::new(),
                    unsigned_attrs_cache: OnceLock::new(),
                },
            )?;
            list.append(si_obj.into_bound(py))?;
        }
        let list_unbound = list.unbind();
        let _ = self.signer_infos_cache.set(list_unbound.clone_ref(py));
        Ok(list_unbound.into_bound(py))
    }

    fn __repr__(&self) -> PyResult<String> {
        let sd = self.signed_data()?;
        Ok(format!(
            "SignedData(version={}, signer_count={})",
            sd.version.as_i64().unwrap_or(0),
            sd.signer_infos.len(),
        ))
    }
}

// ── PySignerInfo ──────────────────────────────────────────────────────────────

/// CMS ``SignerInfo`` (RFC 5652 §5.3) accessible from Python.
///
/// Represents one signer's information within a :class:`SignedData`.
/// Retrieve instances via :attr:`SignedData.signer_infos` or construct
/// directly with :meth:`from_der`.
///
/// ```python,ignore
/// for si in sd.signer_infos:
///     print(si.digest_algorithm_oid)
///     print(si.signature_algorithm_oid)
/// ```
#[pyclass(frozen, name = "SignerInfo")]
pub struct PySignerInfo {
    _data: Py<PyBytes>,
    raw: &'static [u8],
    inner: OnceLock<Box<synta_certificate::cms_rfc5652_types::SignerInfo<'static>>>,
    sid_cache: OnceLock<Py<PyBytes>>,
    digest_algorithm_oid_cache: OnceLock<Py<PyObjectIdentifier>>,
    digest_algorithm_params_cache: OnceLock<Option<Py<PyBytes>>>,
    signature_algorithm_oid_cache: OnceLock<Py<PyObjectIdentifier>>,
    signature_algorithm_params_cache: OnceLock<Option<Py<PyBytes>>>,
    signature_cache: OnceLock<Py<PyBytes>>,
    signed_attrs_cache: OnceLock<Option<Py<PyBytes>>>,
    unsigned_attrs_cache: OnceLock<Option<Py<PyBytes>>>,
}

impl PySignerInfo {
    fn signer_info(&self) -> PyResult<&synta_certificate::cms_rfc5652_types::SignerInfo<'static>> {
        if let Some(v) = self.inner.get() {
            return Ok(v.as_ref());
        }
        let mut decoder = Decoder::new(self.raw, Encoding::Der);
        let decoded = decoder.decode().map_err(|e| {
            pyo3::exceptions::PyValueError::new_err(format!("SignerInfo DER decode failed: {e}"))
        })?;
        let _ = self.inner.set(Box::new(decoded));
        Ok(self.inner.get().unwrap().as_ref())
    }
}

#[pymethods]
impl PySignerInfo {
    /// Parse a DER-encoded CMS ``SignerInfo`` SEQUENCE.
    #[staticmethod]
    fn from_der(py: Python<'_>, data: Bound<'_, PyBytes>) -> PyResult<Self> {
        let py_bytes = data.unbind();
        // SAFETY: `py_bytes` holds a strong reference (Py<PyBytes>) that
        // keeps the Python bytes object alive for the lifetime of this struct.
        // CPython's bytes objects have a fixed-address, non-relocating payload
        // buffer (CPython has no moving GC).  The slice lifetime is extended
        // to 'static; the actual safety invariants are:
        //   (1) All reads of `raw` go through `&self`; no borrow of the struct
        //       can outlive the struct, so `raw` is never read after drop begins.
        //   (2) `raw: &'static [u8]` has no destructor (fat pointer, no heap
        //       allocation), so field drop order does not cause use-after-free.
        //   (3) `inner` contains only borrow-typed fields in the decoded type;
        //       dropping the Box does not read through the contained &'static
        //       slices (borrows have no destructors in Rust).
        // CPython-only: does not hold for PyPy or GraalPy.
        let raw: &'static [u8] = unsafe {
            let s = py_bytes.bind(py).as_bytes();
            std::slice::from_raw_parts(s.as_ptr(), s.len())
        };
        {
            let mut d = Decoder::new(raw, Encoding::Der);
            d.read_tag()
                .map_err(|e| pyo3::exceptions::PyValueError::new_err(format!("{e}")))?;
            d.read_length()
                .map_err(|e| pyo3::exceptions::PyValueError::new_err(format!("{e}")))?;
        }
        Ok(Self {
            _data: py_bytes,
            raw,
            inner: OnceLock::new(),
            sid_cache: OnceLock::new(),
            digest_algorithm_oid_cache: OnceLock::new(),
            digest_algorithm_params_cache: OnceLock::new(),
            signature_algorithm_oid_cache: OnceLock::new(),
            signature_algorithm_params_cache: OnceLock::new(),
            signature_cache: OnceLock::new(),
            signed_attrs_cache: OnceLock::new(),
            unsigned_attrs_cache: OnceLock::new(),
        })
    }

    /// Return the original bytes passed to :meth:`from_der`.
    fn to_der<'py>(&self, py: Python<'py>) -> Bound<'py, PyBytes> {
        self._data.clone_ref(py).into_bound(py)
    }

    /// CMS version integer.
    #[getter]
    fn version(&self) -> PyResult<i64> {
        Ok(self.signer_info()?.version.as_i64().unwrap_or(0))
    }

    /// Raw TLV bytes of the ``SignerIdentifier`` CHOICE field.
    ///
    /// Peek the tag byte to distinguish ``issuerAndSerialNumber`` (SEQUENCE,
    /// tag ``0x30``) from ``subjectKeyIdentifier`` (context ``[0]``, tag
    /// ``0x80``).
    #[getter]
    fn sid<'py>(&self, py: Python<'py>) -> PyResult<Bound<'py, PyBytes>> {
        if let Some(cached) = self.sid_cache.get() {
            return Ok(cached.clone_ref(py).into_bound(py));
        }
        let py_bytes = PyBytes::new(py, self.signer_info()?.sid.as_bytes()).unbind();
        let _ = self.sid_cache.set(py_bytes.clone_ref(py));
        Ok(py_bytes.into_bound(py))
    }

    /// OID of the message-digest algorithm.
    #[getter]
    fn digest_algorithm_oid<'py>(
        &self,
        py: Python<'py>,
    ) -> PyResult<Bound<'py, PyObjectIdentifier>> {
        if let Some(cached) = self.digest_algorithm_oid_cache.get() {
            return Ok(cached.clone_ref(py).into_bound(py));
        }
        let obj = Py::new(
            py,
            PyObjectIdentifier::from_oid(self.signer_info()?.digest_algorithm.algorithm.clone()),
        )?;
        let _ = self.digest_algorithm_oid_cache.set(obj.clone_ref(py));
        Ok(obj.into_bound(py))
    }

    /// Raw DER bytes of the digest-algorithm parameters, or ``None``.
    #[getter]
    fn digest_algorithm_params<'py>(
        &self,
        py: Python<'py>,
    ) -> PyResult<Option<Bound<'py, PyBytes>>> {
        if let Some(cached) = self.digest_algorithm_params_cache.get() {
            return Ok(cached.as_ref().map(|b| b.clone_ref(py).into_bound(py)));
        }
        let computed =
            encode_element_opt(py, self.signer_info()?.digest_algorithm.parameters.as_ref())?;
        let to_store = computed.as_ref().map(|b| b.as_unbound().clone_ref(py));
        let _ = self.digest_algorithm_params_cache.set(to_store);
        Ok(computed)
    }

    /// OID of the signature algorithm.
    #[getter]
    fn signature_algorithm_oid<'py>(
        &self,
        py: Python<'py>,
    ) -> PyResult<Bound<'py, PyObjectIdentifier>> {
        if let Some(cached) = self.signature_algorithm_oid_cache.get() {
            return Ok(cached.clone_ref(py).into_bound(py));
        }
        let obj = Py::new(
            py,
            PyObjectIdentifier::from_oid(self.signer_info()?.signature_algorithm.algorithm.clone()),
        )?;
        let _ = self.signature_algorithm_oid_cache.set(obj.clone_ref(py));
        Ok(obj.into_bound(py))
    }

    /// Raw DER bytes of the signature-algorithm parameters, or ``None``.
    #[getter]
    fn signature_algorithm_params<'py>(
        &self,
        py: Python<'py>,
    ) -> PyResult<Option<Bound<'py, PyBytes>>> {
        if let Some(cached) = self.signature_algorithm_params_cache.get() {
            return Ok(cached.as_ref().map(|b| b.clone_ref(py).into_bound(py)));
        }
        let computed = encode_element_opt(
            py,
            self.signer_info()?.signature_algorithm.parameters.as_ref(),
        )?;
        let to_store = computed.as_ref().map(|b| b.as_unbound().clone_ref(py));
        let _ = self.signature_algorithm_params_cache.set(to_store);
        Ok(computed)
    }

    /// Raw bytes of the signature value.
    #[getter]
    fn signature<'py>(&self, py: Python<'py>) -> PyResult<Bound<'py, PyBytes>> {
        if let Some(cached) = self.signature_cache.get() {
            return Ok(cached.clone_ref(py).into_bound(py));
        }
        let py_bytes = PyBytes::new(py, self.signer_info()?.signature.as_bytes()).unbind();
        let _ = self.signature_cache.set(py_bytes.clone_ref(py));
        Ok(py_bytes.into_bound(py))
    }

    /// Raw content bytes of the ``signedAttrs`` field (IMPLICIT ``[0]``), or ``None``.
    ///
    /// To verify the signature, replace the leading context-specific tag byte
    /// with the SET tag ``0x31`` before hashing.
    #[getter]
    fn signed_attrs<'py>(&self, py: Python<'py>) -> PyResult<Option<Bound<'py, PyBytes>>> {
        if let Some(cached) = self.signed_attrs_cache.get() {
            return Ok(cached.as_ref().map(|b| b.clone_ref(py).into_bound(py)));
        }
        let computed = self
            .signer_info()?
            .signed_attrs
            .as_ref()
            .map(|a| PyBytes::new(py, a.as_bytes()));
        let to_store = computed.as_ref().map(|b| b.as_unbound().clone_ref(py));
        let _ = self.signed_attrs_cache.set(to_store);
        Ok(computed)
    }

    /// Raw content bytes of the ``unsignedAttrs`` field (IMPLICIT ``[1]``), or ``None``.
    #[getter]
    fn unsigned_attrs<'py>(&self, py: Python<'py>) -> PyResult<Option<Bound<'py, PyBytes>>> {
        if let Some(cached) = self.unsigned_attrs_cache.get() {
            return Ok(cached.as_ref().map(|b| b.clone_ref(py).into_bound(py)));
        }
        let computed = self
            .signer_info()?
            .unsigned_attrs
            .as_ref()
            .map(|a| PyBytes::new(py, a.as_bytes()));
        let to_store = computed.as_ref().map(|b| b.as_unbound().clone_ref(py));
        let _ = self.unsigned_attrs_cache.set(to_store);
        Ok(computed)
    }

    fn __repr__(&self) -> PyResult<String> {
        let si = self.signer_info()?;
        Ok(format!(
            "SignerInfo(version={}, digest_algorithm={})",
            si.version.as_i64().unwrap_or(0),
            si.digest_algorithm.algorithm,
        ))
    }
}

// ── PyEnvelopedData ───────────────────────────────────────────────────────────

/// CMS ``EnvelopedData`` (RFC 5652 §6) accessible from Python.
///
/// Obtained by parsing the inner content of a :class:`ContentInfo` whose
/// ``content_type_oid`` equals :data:`~synta.cms.ID_ENVELOPED_DATA`.
#[pyclass(frozen, name = "EnvelopedData")]
pub struct PyEnvelopedData {
    _data: Py<PyBytes>,
    raw: &'static [u8],
    inner: OnceLock<Box<synta_certificate::cms_rfc5652_types::EnvelopedData<'static>>>,
    originator_info_cache: OnceLock<Option<Py<PyBytes>>>,
    recipient_infos_cache: OnceLock<Py<PyBytes>>,
    content_type_cache: OnceLock<Py<PyObjectIdentifier>>,
    content_encryption_algorithm_oid_cache: OnceLock<Py<PyObjectIdentifier>>,
    content_encryption_algorithm_params_cache: OnceLock<Option<Py<PyBytes>>>,
    encrypted_content_cache: OnceLock<Option<Py<PyBytes>>>,
    unprotected_attrs_cache: OnceLock<Option<Py<PyBytes>>>,
}

impl PyEnvelopedData {
    fn enveloped_data(
        &self,
    ) -> PyResult<&synta_certificate::cms_rfc5652_types::EnvelopedData<'static>> {
        if let Some(v) = self.inner.get() {
            return Ok(v.as_ref());
        }
        let mut decoder = Decoder::new(self.raw, Encoding::Ber);
        let decoded = decoder.decode().map_err(|e| {
            pyo3::exceptions::PyValueError::new_err(format!("EnvelopedData BER decode failed: {e}"))
        })?;
        let _ = self.inner.set(Box::new(decoded));
        Ok(self.inner.get().unwrap().as_ref())
    }
}

#[pymethods]
impl PyEnvelopedData {
    /// Parse a DER- or BER-encoded CMS ``EnvelopedData`` SEQUENCE.
    #[staticmethod]
    fn from_der(py: Python<'_>, data: Bound<'_, PyBytes>) -> PyResult<Self> {
        let py_bytes = data.unbind();
        let raw: &'static [u8] = unsafe {
            let s = py_bytes.bind(py).as_bytes();
            std::slice::from_raw_parts(s.as_ptr(), s.len())
        };
        {
            let mut d = Decoder::new(raw, Encoding::Ber);
            d.read_tag()
                .map_err(|e| pyo3::exceptions::PyValueError::new_err(format!("{e}")))?;
            d.read_length()
                .map_err(|e| pyo3::exceptions::PyValueError::new_err(format!("{e}")))?;
        }
        Ok(Self {
            _data: py_bytes,
            raw,
            inner: OnceLock::new(),
            originator_info_cache: OnceLock::new(),
            recipient_infos_cache: OnceLock::new(),
            content_type_cache: OnceLock::new(),
            content_encryption_algorithm_oid_cache: OnceLock::new(),
            content_encryption_algorithm_params_cache: OnceLock::new(),
            encrypted_content_cache: OnceLock::new(),
            unprotected_attrs_cache: OnceLock::new(),
        })
    }

    /// Return the original bytes passed to :meth:`from_der`.
    fn to_der<'py>(&self, py: Python<'py>) -> Bound<'py, PyBytes> {
        self._data.clone_ref(py).into_bound(py)
    }

    /// CMS version integer.
    #[getter]
    fn version(&self) -> PyResult<i64> {
        Ok(self.enveloped_data()?.version.as_i64().unwrap_or(0))
    }

    /// DER-encoded ``OriginatorInfo`` SEQUENCE, or ``None`` if absent.
    #[getter]
    fn originator_info<'py>(&self, py: Python<'py>) -> PyResult<Option<Bound<'py, PyBytes>>> {
        if let Some(cached) = self.originator_info_cache.get() {
            return Ok(cached.as_ref().map(|b| b.clone_ref(py).into_bound(py)));
        }
        let computed = match &self.enveloped_data()?.originator_info {
            None => None,
            Some(oi) => {
                let mut enc = synta::Encoder::new(Encoding::Der);
                oi.encode(&mut enc)
                    .map_err(|e| pyo3::exceptions::PyValueError::new_err(format!("{e}")))?;
                let bytes = enc
                    .finish()
                    .map_err(|e| pyo3::exceptions::PyValueError::new_err(format!("{e}")))?;
                Some(PyBytes::new(py, &bytes))
            }
        };
        let to_store = computed.as_ref().map(|b| b.as_unbound().clone_ref(py));
        let _ = self.originator_info_cache.set(to_store);
        Ok(computed)
    }

    /// Raw TLV bytes of the ``RecipientInfos`` SET field.
    #[getter]
    fn recipient_infos<'py>(&self, py: Python<'py>) -> PyResult<Bound<'py, PyBytes>> {
        if let Some(cached) = self.recipient_infos_cache.get() {
            return Ok(cached.clone_ref(py).into_bound(py));
        }
        let py_bytes = PyBytes::new(py, self.enveloped_data()?.recipient_infos.as_bytes()).unbind();
        let _ = self.recipient_infos_cache.set(py_bytes.clone_ref(py));
        Ok(py_bytes.into_bound(py))
    }

    /// OID identifying the encrypted content type.
    #[getter]
    fn content_type<'py>(&self, py: Python<'py>) -> PyResult<Bound<'py, PyObjectIdentifier>> {
        if let Some(cached) = self.content_type_cache.get() {
            return Ok(cached.clone_ref(py).into_bound(py));
        }
        let obj = Py::new(
            py,
            PyObjectIdentifier::from_oid(
                self.enveloped_data()?
                    .encrypted_content_info
                    .content_type
                    .clone(),
            ),
        )?;
        let _ = self.content_type_cache.set(obj.clone_ref(py));
        Ok(obj.into_bound(py))
    }

    /// OID of the content-encryption algorithm.
    #[getter]
    fn content_encryption_algorithm_oid<'py>(
        &self,
        py: Python<'py>,
    ) -> PyResult<Bound<'py, PyObjectIdentifier>> {
        if let Some(cached) = self.content_encryption_algorithm_oid_cache.get() {
            return Ok(cached.clone_ref(py).into_bound(py));
        }
        let obj = Py::new(
            py,
            PyObjectIdentifier::from_oid(
                self.enveloped_data()?
                    .encrypted_content_info
                    .content_encryption_algorithm
                    .algorithm
                    .clone(),
            ),
        )?;
        let _ = self
            .content_encryption_algorithm_oid_cache
            .set(obj.clone_ref(py));
        Ok(obj.into_bound(py))
    }

    /// Raw DER bytes of the content-encryption algorithm parameters, or ``None``.
    #[getter]
    fn content_encryption_algorithm_params<'py>(
        &self,
        py: Python<'py>,
    ) -> PyResult<Option<Bound<'py, PyBytes>>> {
        if let Some(cached) = self.content_encryption_algorithm_params_cache.get() {
            return Ok(cached.as_ref().map(|b| b.clone_ref(py).into_bound(py)));
        }
        let computed = encode_element_opt(
            py,
            self.enveloped_data()?
                .encrypted_content_info
                .content_encryption_algorithm
                .parameters
                .as_ref(),
        )?;
        let to_store = computed.as_ref().map(|b| b.as_unbound().clone_ref(py));
        let _ = self.content_encryption_algorithm_params_cache.set(to_store);
        Ok(computed)
    }

    /// Raw bytes of the encrypted content OCTET STRING value (IMPLICIT ``[0]``),
    /// or ``None`` if absent.
    #[getter]
    fn encrypted_content<'py>(&self, py: Python<'py>) -> PyResult<Option<Bound<'py, PyBytes>>> {
        if let Some(cached) = self.encrypted_content_cache.get() {
            return Ok(cached.as_ref().map(|b| b.clone_ref(py).into_bound(py)));
        }
        let computed = self
            .enveloped_data()?
            .encrypted_content_info
            .encrypted_content
            .as_ref()
            .map(|c| PyBytes::new(py, c.as_bytes()));
        let to_store = computed.as_ref().map(|b| b.as_unbound().clone_ref(py));
        let _ = self.encrypted_content_cache.set(to_store);
        Ok(computed)
    }

    /// Raw content bytes of the ``unprotectedAttrs`` field (IMPLICIT ``[1]``),
    /// or ``None`` if absent.
    #[getter]
    fn unprotected_attrs<'py>(&self, py: Python<'py>) -> PyResult<Option<Bound<'py, PyBytes>>> {
        if let Some(cached) = self.unprotected_attrs_cache.get() {
            return Ok(cached.as_ref().map(|b| b.clone_ref(py).into_bound(py)));
        }
        let computed = self
            .enveloped_data()?
            .unprotected_attrs
            .as_ref()
            .map(|a| PyBytes::new(py, a.as_bytes()));
        let to_store = computed.as_ref().map(|b| b.as_unbound().clone_ref(py));
        let _ = self.unprotected_attrs_cache.set(to_store);
        Ok(computed)
    }

    fn __repr__(&self) -> PyResult<String> {
        Ok(format!(
            "EnvelopedData(version={})",
            self.enveloped_data()?.version.as_i64().unwrap_or(0),
        ))
    }
}

// ── PyEncryptedData ───────────────────────────────────────────────────────────

/// CMS ``EncryptedData`` (RFC 5652 §8) accessible from Python.
///
/// Obtained by parsing the inner content of a :class:`ContentInfo` whose
/// ``content_type_oid`` equals :data:`~synta.cms.ID_ENCRYPTED_DATA`.
#[pyclass(frozen, name = "EncryptedData")]
pub struct PyEncryptedData {
    _data: Py<PyBytes>,
    raw: &'static [u8],
    inner: OnceLock<Box<synta_certificate::cms_rfc5652_types::EncryptedData<'static>>>,
    content_type_cache: OnceLock<Py<PyObjectIdentifier>>,
    content_encryption_algorithm_oid_cache: OnceLock<Py<PyObjectIdentifier>>,
    content_encryption_algorithm_params_cache: OnceLock<Option<Py<PyBytes>>>,
    encrypted_content_cache: OnceLock<Option<Py<PyBytes>>>,
    unprotected_attrs_cache: OnceLock<Option<Py<PyBytes>>>,
}

impl PyEncryptedData {
    fn encrypted_data(
        &self,
    ) -> PyResult<&synta_certificate::cms_rfc5652_types::EncryptedData<'static>> {
        if let Some(v) = self.inner.get() {
            return Ok(v.as_ref());
        }
        let mut decoder = Decoder::new(self.raw, Encoding::Ber);
        let decoded = decoder.decode().map_err(|e| {
            pyo3::exceptions::PyValueError::new_err(format!("EncryptedData BER decode failed: {e}"))
        })?;
        let _ = self.inner.set(Box::new(decoded));
        Ok(self.inner.get().unwrap().as_ref())
    }
}

#[pymethods]
impl PyEncryptedData {
    /// Parse a DER- or BER-encoded CMS ``EncryptedData`` SEQUENCE.
    #[staticmethod]
    fn from_der(py: Python<'_>, data: Bound<'_, PyBytes>) -> PyResult<Self> {
        let py_bytes = data.unbind();
        let raw: &'static [u8] = unsafe {
            let s = py_bytes.bind(py).as_bytes();
            std::slice::from_raw_parts(s.as_ptr(), s.len())
        };
        {
            let mut d = Decoder::new(raw, Encoding::Ber);
            d.read_tag()
                .map_err(|e| pyo3::exceptions::PyValueError::new_err(format!("{e}")))?;
            d.read_length()
                .map_err(|e| pyo3::exceptions::PyValueError::new_err(format!("{e}")))?;
        }
        Ok(Self {
            _data: py_bytes,
            raw,
            inner: OnceLock::new(),
            content_type_cache: OnceLock::new(),
            content_encryption_algorithm_oid_cache: OnceLock::new(),
            content_encryption_algorithm_params_cache: OnceLock::new(),
            encrypted_content_cache: OnceLock::new(),
            unprotected_attrs_cache: OnceLock::new(),
        })
    }

    /// Return the original bytes passed to :meth:`from_der`.
    fn to_der<'py>(&self, py: Python<'py>) -> Bound<'py, PyBytes> {
        self._data.clone_ref(py).into_bound(py)
    }

    /// CMS version integer.
    #[getter]
    fn version(&self) -> PyResult<i64> {
        Ok(self.encrypted_data()?.version.as_i64().unwrap_or(0))
    }

    /// OID identifying the encrypted content type.
    #[getter]
    fn content_type<'py>(&self, py: Python<'py>) -> PyResult<Bound<'py, PyObjectIdentifier>> {
        if let Some(cached) = self.content_type_cache.get() {
            return Ok(cached.clone_ref(py).into_bound(py));
        }
        let obj = Py::new(
            py,
            PyObjectIdentifier::from_oid(
                self.encrypted_data()?
                    .encrypted_content_info
                    .content_type
                    .clone(),
            ),
        )?;
        let _ = self.content_type_cache.set(obj.clone_ref(py));
        Ok(obj.into_bound(py))
    }

    /// OID of the content-encryption algorithm.
    #[getter]
    fn content_encryption_algorithm_oid<'py>(
        &self,
        py: Python<'py>,
    ) -> PyResult<Bound<'py, PyObjectIdentifier>> {
        if let Some(cached) = self.content_encryption_algorithm_oid_cache.get() {
            return Ok(cached.clone_ref(py).into_bound(py));
        }
        let obj = Py::new(
            py,
            PyObjectIdentifier::from_oid(
                self.encrypted_data()?
                    .encrypted_content_info
                    .content_encryption_algorithm
                    .algorithm
                    .clone(),
            ),
        )?;
        let _ = self
            .content_encryption_algorithm_oid_cache
            .set(obj.clone_ref(py));
        Ok(obj.into_bound(py))
    }

    /// Raw DER bytes of the content-encryption algorithm parameters, or ``None``.
    #[getter]
    fn content_encryption_algorithm_params<'py>(
        &self,
        py: Python<'py>,
    ) -> PyResult<Option<Bound<'py, PyBytes>>> {
        if let Some(cached) = self.content_encryption_algorithm_params_cache.get() {
            return Ok(cached.as_ref().map(|b| b.clone_ref(py).into_bound(py)));
        }
        let computed = encode_element_opt(
            py,
            self.encrypted_data()?
                .encrypted_content_info
                .content_encryption_algorithm
                .parameters
                .as_ref(),
        )?;
        let to_store = computed.as_ref().map(|b| b.as_unbound().clone_ref(py));
        let _ = self.content_encryption_algorithm_params_cache.set(to_store);
        Ok(computed)
    }

    /// Raw bytes of the encrypted content OCTET STRING value (IMPLICIT ``[0]``),
    /// or ``None`` if absent.
    #[getter]
    fn encrypted_content<'py>(&self, py: Python<'py>) -> PyResult<Option<Bound<'py, PyBytes>>> {
        if let Some(cached) = self.encrypted_content_cache.get() {
            return Ok(cached.as_ref().map(|b| b.clone_ref(py).into_bound(py)));
        }
        let computed = self
            .encrypted_data()?
            .encrypted_content_info
            .encrypted_content
            .as_ref()
            .map(|c| PyBytes::new(py, c.as_bytes()));
        let to_store = computed.as_ref().map(|b| b.as_unbound().clone_ref(py));
        let _ = self.encrypted_content_cache.set(to_store);
        Ok(computed)
    }

    /// Raw content bytes of the ``unprotectedAttrs`` field (IMPLICIT ``[1]``),
    /// or ``None`` if absent.
    #[getter]
    fn unprotected_attrs<'py>(&self, py: Python<'py>) -> PyResult<Option<Bound<'py, PyBytes>>> {
        if let Some(cached) = self.unprotected_attrs_cache.get() {
            return Ok(cached.as_ref().map(|b| b.clone_ref(py).into_bound(py)));
        }
        let computed = self
            .encrypted_data()?
            .unprotected_attrs
            .as_ref()
            .map(|a| PyBytes::new(py, a.as_bytes()));
        let to_store = computed.as_ref().map(|b| b.as_unbound().clone_ref(py));
        let _ = self.unprotected_attrs_cache.set(to_store);
        Ok(computed)
    }

    /// Build a new :class:`EncryptedData` by encrypting ``plaintext`` with
    /// ``key``.
    ///
    /// - ``algorithm_oid``: dotted-decimal OID string or
    ///   :class:`~synta.ObjectIdentifier` for the content-encryption algorithm
    ///   (e.g. ``"2.16.840.1.101.3.4.1.2"`` for AES-128-CBC).
    /// - ``content_type_oid``: optional content-type OID (default:
    ///   ``id-data`` = ``"1.2.840.113549.1.7.1"``).
    ///
    /// A fresh random IV is generated for each call.
    ///
    /// Raises :exc:`NotImplementedError` when built without the ``openssl``
    /// Cargo feature.
    #[staticmethod]
    #[pyo3(signature = (plaintext, key, algorithm_oid, content_type_oid = None))]
    fn create(
        py: Python<'_>,
        plaintext: &[u8],
        key: &[u8],
        algorithm_oid: &Bound<'_, PyAny>,
        content_type_oid: Option<&Bound<'_, PyAny>>,
    ) -> PyResult<Self> {
        let enc_alg_oid = oid_from_pyany(algorithm_oid)?;

        let ct_oid = match content_type_oid {
            Some(obj) => oid_from_pyany(obj)?,
            None => synta::ObjectIdentifier::new(synta_certificate::pkcs7_types::ID_DATA)
                .expect("id-data is a valid OID"),
        };

        #[cfg(feature = "openssl")]
        {
            use synta_certificate::CmsEncryptor as _;
            let der = synta_certificate::OpensslEncryptor
                .create_encrypted_data(
                    ct_oid.components(),
                    enc_alg_oid.components(),
                    plaintext,
                    key,
                )
                .map_err(|e| pyo3::exceptions::PyValueError::new_err(format!("{e}")))?;
            let py_bytes = PyBytes::new(py, &der).unbind();
            Self::from_der(py, py_bytes.into_bound(py))
        }

        #[cfg(not(feature = "openssl"))]
        {
            let _ = (py, plaintext, key, enc_alg_oid, ct_oid);
            Err(pyo3::exceptions::PyNotImplementedError::new_err(
                "CMS encryption requires the 'openssl' feature; \
                 rebuild synta-python with --features openssl",
            ))
        }
    }

    /// Decrypt the encrypted content using a raw symmetric key.
    ///
    /// ``key`` must be the raw symmetric key bytes matching the
    /// content-encryption algorithm (e.g. 16 bytes for AES-128-CBC,
    /// 32 bytes for AES-256-CBC).
    ///
    /// Raises :exc:`NotImplementedError` when built without the
    /// ``openssl`` Cargo feature.
    fn decrypt<'py>(&self, py: Python<'py>, key: &[u8]) -> PyResult<Bound<'py, PyBytes>> {
        #[cfg(feature = "openssl")]
        {
            use synta_certificate::CmsDecryptor as _;
            let ed = self.encrypted_data()?;
            let mut enc = synta::Encoder::new(synta::Encoding::Der);
            ed.encrypted_content_info
                .content_encryption_algorithm
                .encode(&mut enc)
                .map_err(|e| pyo3::exceptions::PyValueError::new_err(format!("{e}")))?;
            let algorithm_der = enc
                .finish()
                .map_err(|e| pyo3::exceptions::PyValueError::new_err(format!("{e}")))?;
            let ciphertext = ed
                .encrypted_content_info
                .encrypted_content
                .as_ref()
                .ok_or_else(|| {
                    pyo3::exceptions::PyValueError::new_err(
                        "EncryptedData has no encryptedContent field",
                    )
                })?
                .as_bytes();
            let plaintext = synta_certificate::OpensslDecryptor
                .decrypt(&algorithm_der, ciphertext, key)
                .map_err(|e| pyo3::exceptions::PyValueError::new_err(format!("{e}")))?;
            Ok(PyBytes::new(py, &plaintext))
        }
        #[cfg(not(feature = "openssl"))]
        {
            let _ = (py, key);
            Err(pyo3::exceptions::PyNotImplementedError::new_err(
                "CMS decryption requires the 'openssl' feature; \
                 rebuild synta-python with --features openssl",
            ))
        }
    }

    fn __repr__(&self) -> PyResult<String> {
        Ok(format!(
            "EncryptedData(version={})",
            self.encrypted_data()?.version.as_i64().unwrap_or(0),
        ))
    }
}

// ── PyDigestedData ────────────────────────────────────────────────────────────

/// CMS ``DigestedData`` (RFC 5652 §7) accessible from Python.
///
/// Obtained by parsing the inner content of a :class:`ContentInfo` whose
/// ``content_type_oid`` is the id-digestedData OID.
#[pyclass(frozen, name = "DigestedData")]
pub struct PyDigestedData {
    _data: Py<PyBytes>,
    raw: &'static [u8],
    inner: OnceLock<Box<synta_certificate::cms_rfc5652_types::DigestedData<'static>>>,
    digest_algorithm_oid_cache: OnceLock<Py<PyObjectIdentifier>>,
    digest_algorithm_params_cache: OnceLock<Option<Py<PyBytes>>>,
    encap_content_type_cache: OnceLock<Py<PyObjectIdentifier>>,
    encap_content_cache: OnceLock<Option<Py<PyBytes>>>,
    digest_cache: OnceLock<Py<PyBytes>>,
}

impl PyDigestedData {
    fn digested_data(
        &self,
    ) -> PyResult<&synta_certificate::cms_rfc5652_types::DigestedData<'static>> {
        if let Some(v) = self.inner.get() {
            return Ok(v.as_ref());
        }
        let mut decoder = Decoder::new(self.raw, Encoding::Ber);
        let decoded = decoder.decode().map_err(|e| {
            pyo3::exceptions::PyValueError::new_err(format!("DigestedData BER decode failed: {e}"))
        })?;
        let _ = self.inner.set(Box::new(decoded));
        Ok(self.inner.get().unwrap().as_ref())
    }
}

#[pymethods]
impl PyDigestedData {
    /// Parse a DER- or BER-encoded CMS ``DigestedData`` SEQUENCE.
    #[staticmethod]
    fn from_der(py: Python<'_>, data: Bound<'_, PyBytes>) -> PyResult<Self> {
        let py_bytes = data.unbind();
        let raw: &'static [u8] = unsafe {
            let s = py_bytes.bind(py).as_bytes();
            std::slice::from_raw_parts(s.as_ptr(), s.len())
        };
        {
            let mut d = Decoder::new(raw, Encoding::Ber);
            d.read_tag()
                .map_err(|e| pyo3::exceptions::PyValueError::new_err(format!("{e}")))?;
            d.read_length()
                .map_err(|e| pyo3::exceptions::PyValueError::new_err(format!("{e}")))?;
        }
        Ok(Self {
            _data: py_bytes,
            raw,
            inner: OnceLock::new(),
            digest_algorithm_oid_cache: OnceLock::new(),
            digest_algorithm_params_cache: OnceLock::new(),
            encap_content_type_cache: OnceLock::new(),
            encap_content_cache: OnceLock::new(),
            digest_cache: OnceLock::new(),
        })
    }

    /// Return the original bytes passed to :meth:`from_der`.
    fn to_der<'py>(&self, py: Python<'py>) -> Bound<'py, PyBytes> {
        self._data.clone_ref(py).into_bound(py)
    }

    /// CMS version integer.
    #[getter]
    fn version(&self) -> PyResult<i64> {
        Ok(self.digested_data()?.version.as_i64().unwrap_or(0))
    }

    /// OID of the digest algorithm.
    #[getter]
    fn digest_algorithm_oid<'py>(
        &self,
        py: Python<'py>,
    ) -> PyResult<Bound<'py, PyObjectIdentifier>> {
        if let Some(cached) = self.digest_algorithm_oid_cache.get() {
            return Ok(cached.clone_ref(py).into_bound(py));
        }
        let obj = Py::new(
            py,
            PyObjectIdentifier::from_oid(self.digested_data()?.digest_algorithm.algorithm.clone()),
        )?;
        let _ = self.digest_algorithm_oid_cache.set(obj.clone_ref(py));
        Ok(obj.into_bound(py))
    }

    /// Raw DER bytes of the digest-algorithm parameters, or ``None``.
    #[getter]
    fn digest_algorithm_params<'py>(
        &self,
        py: Python<'py>,
    ) -> PyResult<Option<Bound<'py, PyBytes>>> {
        if let Some(cached) = self.digest_algorithm_params_cache.get() {
            return Ok(cached.as_ref().map(|b| b.clone_ref(py).into_bound(py)));
        }
        let computed = encode_element_opt(
            py,
            self.digested_data()?.digest_algorithm.parameters.as_ref(),
        )?;
        let to_store = computed.as_ref().map(|b| b.as_unbound().clone_ref(py));
        let _ = self.digest_algorithm_params_cache.set(to_store);
        Ok(computed)
    }

    /// OID identifying the encapsulated content type.
    #[getter]
    fn encap_content_type<'py>(&self, py: Python<'py>) -> PyResult<Bound<'py, PyObjectIdentifier>> {
        if let Some(cached) = self.encap_content_type_cache.get() {
            return Ok(cached.clone_ref(py).into_bound(py));
        }
        let obj = Py::new(
            py,
            PyObjectIdentifier::from_oid(
                self.digested_data()?
                    .encap_content_info
                    .e_content_type
                    .clone(),
            ),
        )?;
        let _ = self.encap_content_type_cache.set(obj.clone_ref(py));
        Ok(obj.into_bound(py))
    }

    /// Raw bytes of the encapsulated content OCTET STRING value, or ``None``.
    #[getter]
    fn encap_content<'py>(&self, py: Python<'py>) -> PyResult<Option<Bound<'py, PyBytes>>> {
        if let Some(cached) = self.encap_content_cache.get() {
            return Ok(cached.as_ref().map(|b| b.clone_ref(py).into_bound(py)));
        }
        let computed = self
            .digested_data()?
            .encap_content_info
            .e_content
            .as_ref()
            .map(|c| PyBytes::new(py, c.as_bytes()));
        let to_store = computed.as_ref().map(|b| b.as_unbound().clone_ref(py));
        let _ = self.encap_content_cache.set(to_store);
        Ok(computed)
    }

    /// Raw bytes of the message digest (OCTET STRING value).
    #[getter]
    fn digest<'py>(&self, py: Python<'py>) -> PyResult<Bound<'py, PyBytes>> {
        if let Some(cached) = self.digest_cache.get() {
            return Ok(cached.clone_ref(py).into_bound(py));
        }
        let py_bytes = PyBytes::new(py, self.digested_data()?.digest.as_bytes()).unbind();
        let _ = self.digest_cache.set(py_bytes.clone_ref(py));
        Ok(py_bytes.into_bound(py))
    }

    fn __repr__(&self) -> PyResult<String> {
        let dd = self.digested_data()?;
        Ok(format!(
            "DigestedData(version={}, digest_algorithm={})",
            dd.version.as_i64().unwrap_or(0),
            dd.digest_algorithm.algorithm,
        ))
    }
}

// ── PyAuthenticatedData ───────────────────────────────────────────────────────

/// CMS ``AuthenticatedData`` (RFC 5652 §9) accessible from Python.
///
/// Obtained by parsing the inner content of a :class:`ContentInfo` whose
/// ``content_type_oid`` is the id-ct-authData OID.
#[pyclass(frozen, name = "AuthenticatedData")]
pub struct PyAuthenticatedData {
    _data: Py<PyBytes>,
    raw: &'static [u8],
    inner: OnceLock<Box<synta_certificate::cms_rfc5652_types::AuthenticatedData<'static>>>,
    originator_info_cache: OnceLock<Option<Py<PyBytes>>>,
    recipient_infos_cache: OnceLock<Py<PyBytes>>,
    mac_algorithm_oid_cache: OnceLock<Py<PyObjectIdentifier>>,
    mac_algorithm_params_cache: OnceLock<Option<Py<PyBytes>>>,
    digest_algorithm_oid_cache: OnceLock<Option<Py<PyObjectIdentifier>>>,
    digest_algorithm_params_cache: OnceLock<Option<Py<PyBytes>>>,
    encap_content_type_cache: OnceLock<Py<PyObjectIdentifier>>,
    encap_content_cache: OnceLock<Option<Py<PyBytes>>>,
    mac_cache: OnceLock<Py<PyBytes>>,
    auth_attrs_cache: OnceLock<Option<Py<PyBytes>>>,
    unauth_attrs_cache: OnceLock<Option<Py<PyBytes>>>,
}

impl PyAuthenticatedData {
    fn authenticated_data(
        &self,
    ) -> PyResult<&synta_certificate::cms_rfc5652_types::AuthenticatedData<'static>> {
        if let Some(v) = self.inner.get() {
            return Ok(v.as_ref());
        }
        let mut decoder = Decoder::new(self.raw, Encoding::Ber);
        let decoded = decoder.decode().map_err(|e| {
            pyo3::exceptions::PyValueError::new_err(format!(
                "AuthenticatedData BER decode failed: {e}"
            ))
        })?;
        let _ = self.inner.set(Box::new(decoded));
        Ok(self.inner.get().unwrap().as_ref())
    }
}

#[pymethods]
impl PyAuthenticatedData {
    /// Parse a DER- or BER-encoded CMS ``AuthenticatedData`` SEQUENCE.
    #[staticmethod]
    fn from_der(py: Python<'_>, data: Bound<'_, PyBytes>) -> PyResult<Self> {
        let py_bytes = data.unbind();
        let raw: &'static [u8] = unsafe {
            let s = py_bytes.bind(py).as_bytes();
            std::slice::from_raw_parts(s.as_ptr(), s.len())
        };
        {
            let mut d = Decoder::new(raw, Encoding::Ber);
            d.read_tag()
                .map_err(|e| pyo3::exceptions::PyValueError::new_err(format!("{e}")))?;
            d.read_length()
                .map_err(|e| pyo3::exceptions::PyValueError::new_err(format!("{e}")))?;
        }
        Ok(Self {
            _data: py_bytes,
            raw,
            inner: OnceLock::new(),
            originator_info_cache: OnceLock::new(),
            recipient_infos_cache: OnceLock::new(),
            mac_algorithm_oid_cache: OnceLock::new(),
            mac_algorithm_params_cache: OnceLock::new(),
            digest_algorithm_oid_cache: OnceLock::new(),
            digest_algorithm_params_cache: OnceLock::new(),
            encap_content_type_cache: OnceLock::new(),
            encap_content_cache: OnceLock::new(),
            mac_cache: OnceLock::new(),
            auth_attrs_cache: OnceLock::new(),
            unauth_attrs_cache: OnceLock::new(),
        })
    }

    /// Return the original bytes passed to :meth:`from_der`.
    fn to_der<'py>(&self, py: Python<'py>) -> Bound<'py, PyBytes> {
        self._data.clone_ref(py).into_bound(py)
    }

    /// CMS version integer.
    #[getter]
    fn version(&self) -> PyResult<i64> {
        Ok(self.authenticated_data()?.version.as_i64().unwrap_or(0))
    }

    /// DER-encoded ``OriginatorInfo`` SEQUENCE, or ``None`` if absent.
    #[getter]
    fn originator_info<'py>(&self, py: Python<'py>) -> PyResult<Option<Bound<'py, PyBytes>>> {
        if let Some(cached) = self.originator_info_cache.get() {
            return Ok(cached.as_ref().map(|b| b.clone_ref(py).into_bound(py)));
        }
        let computed = match &self.authenticated_data()?.originator_info {
            None => None,
            Some(oi) => {
                let mut enc = synta::Encoder::new(Encoding::Der);
                oi.encode(&mut enc)
                    .map_err(|e| pyo3::exceptions::PyValueError::new_err(format!("{e}")))?;
                let bytes = enc
                    .finish()
                    .map_err(|e| pyo3::exceptions::PyValueError::new_err(format!("{e}")))?;
                Some(PyBytes::new(py, &bytes))
            }
        };
        let to_store = computed.as_ref().map(|b| b.as_unbound().clone_ref(py));
        let _ = self.originator_info_cache.set(to_store);
        Ok(computed)
    }

    /// Raw TLV bytes of the ``RecipientInfos`` SET field.
    #[getter]
    fn recipient_infos<'py>(&self, py: Python<'py>) -> PyResult<Bound<'py, PyBytes>> {
        if let Some(cached) = self.recipient_infos_cache.get() {
            return Ok(cached.clone_ref(py).into_bound(py));
        }
        let bytes =
            PyBytes::new(py, self.authenticated_data()?.recipient_infos.as_bytes()).unbind();
        let _ = self.recipient_infos_cache.set(bytes.clone_ref(py));
        Ok(bytes.into_bound(py))
    }

    /// OID of the MAC algorithm.
    #[getter]
    fn mac_algorithm_oid<'py>(&self, py: Python<'py>) -> PyResult<Bound<'py, PyObjectIdentifier>> {
        if let Some(cached) = self.mac_algorithm_oid_cache.get() {
            return Ok(cached.clone_ref(py).into_bound(py));
        }
        let obj = Py::new(
            py,
            PyObjectIdentifier::from_oid(
                self.authenticated_data()?.mac_algorithm.algorithm.clone(),
            ),
        )?;
        let _ = self.mac_algorithm_oid_cache.set(obj.clone_ref(py));
        Ok(obj.into_bound(py))
    }

    /// Raw DER bytes of the MAC algorithm parameters, or ``None``.
    #[getter]
    fn mac_algorithm_params<'py>(&self, py: Python<'py>) -> PyResult<Option<Bound<'py, PyBytes>>> {
        if let Some(cached) = self.mac_algorithm_params_cache.get() {
            return Ok(cached.as_ref().map(|b| b.clone_ref(py).into_bound(py)));
        }
        let computed = encode_element_opt(
            py,
            self.authenticated_data()?.mac_algorithm.parameters.as_ref(),
        )?;
        let to_store = computed.as_ref().map(|b| b.as_unbound().clone_ref(py));
        let _ = self.mac_algorithm_params_cache.set(to_store);
        Ok(computed)
    }

    /// OID of the digest algorithm (``[1] IMPLICIT``), or ``None`` if absent.
    #[getter]
    fn digest_algorithm_oid<'py>(
        &self,
        py: Python<'py>,
    ) -> PyResult<Option<Bound<'py, PyObjectIdentifier>>> {
        if let Some(cached) = self.digest_algorithm_oid_cache.get() {
            return Ok(cached.as_ref().map(|b| b.clone_ref(py).into_bound(py)));
        }
        let computed: Option<Py<PyObjectIdentifier>> =
            match &self.authenticated_data()?.digest_algorithm {
                None => None,
                Some(da) => Some(Py::new(
                    py,
                    PyObjectIdentifier::from_oid(da.algorithm.clone()),
                )?),
            };
        let to_store = computed.as_ref().map(|b| b.clone_ref(py));
        let _ = self.digest_algorithm_oid_cache.set(to_store);
        Ok(computed.map(|b| b.into_bound(py)))
    }

    /// Raw DER bytes of the digest-algorithm parameters, or ``None``.
    #[getter]
    fn digest_algorithm_params<'py>(
        &self,
        py: Python<'py>,
    ) -> PyResult<Option<Bound<'py, PyBytes>>> {
        if let Some(cached) = self.digest_algorithm_params_cache.get() {
            return Ok(cached.as_ref().map(|b| b.clone_ref(py).into_bound(py)));
        }
        let computed = encode_element_opt(
            py,
            self.authenticated_data()?
                .digest_algorithm
                .as_ref()
                .and_then(|da| da.parameters.as_ref()),
        )?;
        let to_store = computed.as_ref().map(|b| b.as_unbound().clone_ref(py));
        let _ = self.digest_algorithm_params_cache.set(to_store);
        Ok(computed)
    }

    /// OID identifying the encapsulated content type.
    #[getter]
    fn encap_content_type<'py>(&self, py: Python<'py>) -> PyResult<Bound<'py, PyObjectIdentifier>> {
        if let Some(cached) = self.encap_content_type_cache.get() {
            return Ok(cached.clone_ref(py).into_bound(py));
        }
        let obj = Py::new(
            py,
            PyObjectIdentifier::from_oid(
                self.authenticated_data()?
                    .encap_content_info
                    .e_content_type
                    .clone(),
            ),
        )?;
        let _ = self.encap_content_type_cache.set(obj.clone_ref(py));
        Ok(obj.into_bound(py))
    }

    /// Raw bytes of the encapsulated content OCTET STRING value, or ``None``.
    #[getter]
    fn encap_content<'py>(&self, py: Python<'py>) -> PyResult<Option<Bound<'py, PyBytes>>> {
        if let Some(cached) = self.encap_content_cache.get() {
            return Ok(cached.as_ref().map(|b| b.clone_ref(py).into_bound(py)));
        }
        let computed = self
            .authenticated_data()?
            .encap_content_info
            .e_content
            .as_ref()
            .map(|c| PyBytes::new(py, c.as_bytes()));
        let to_store = computed.as_ref().map(|b| b.as_unbound().clone_ref(py));
        let _ = self.encap_content_cache.set(to_store);
        Ok(computed)
    }

    /// Raw bytes of the MAC (message authentication code) value.
    #[getter]
    fn mac<'py>(&self, py: Python<'py>) -> PyResult<Bound<'py, PyBytes>> {
        if let Some(cached) = self.mac_cache.get() {
            return Ok(cached.clone_ref(py).into_bound(py));
        }
        let bytes = PyBytes::new(py, self.authenticated_data()?.mac.as_bytes()).unbind();
        let _ = self.mac_cache.set(bytes.clone_ref(py));
        Ok(bytes.into_bound(py))
    }

    /// Raw content bytes of the ``authAttrs`` field (IMPLICIT ``[2]``), or ``None``.
    ///
    /// To verify the MAC, replace the leading context-specific tag byte with
    /// the SET tag ``0x31`` before feeding to the MAC function.
    #[getter]
    fn auth_attrs<'py>(&self, py: Python<'py>) -> PyResult<Option<Bound<'py, PyBytes>>> {
        if let Some(cached) = self.auth_attrs_cache.get() {
            return Ok(cached.as_ref().map(|b| b.clone_ref(py).into_bound(py)));
        }
        let computed = self
            .authenticated_data()?
            .auth_attrs
            .as_ref()
            .map(|a| PyBytes::new(py, a.as_bytes()));
        let to_store = computed.as_ref().map(|b| b.as_unbound().clone_ref(py));
        let _ = self.auth_attrs_cache.set(to_store);
        Ok(computed)
    }

    /// Raw content bytes of the ``unauthAttrs`` field (IMPLICIT ``[3]``), or ``None``.
    #[getter]
    fn unauth_attrs<'py>(&self, py: Python<'py>) -> PyResult<Option<Bound<'py, PyBytes>>> {
        if let Some(cached) = self.unauth_attrs_cache.get() {
            return Ok(cached.as_ref().map(|b| b.clone_ref(py).into_bound(py)));
        }
        let computed = self
            .authenticated_data()?
            .unauth_attrs
            .as_ref()
            .map(|a| PyBytes::new(py, a.as_bytes()));
        let to_store = computed.as_ref().map(|b| b.as_unbound().clone_ref(py));
        let _ = self.unauth_attrs_cache.set(to_store);
        Ok(computed)
    }

    fn __repr__(&self) -> PyResult<String> {
        let ad = self.authenticated_data()?;
        Ok(format!(
            "AuthenticatedData(version={})",
            ad.version.as_i64().unwrap_or(0),
        ))
    }
}

/// Exposes CMS (RFC 5652) content types, CMS-KEM (RFC 9629) types, and OID
/// constants.  Installs the module into ``sys.modules`` so that
/// ``from synta.cms import ContentInfo`` works.
fn register_cms_submodule(parent: &Bound<'_, PyModule>) -> PyResult<()> {
    let py = parent.py();
    let m = PyModule::new(py, "cms")?;

    m.add_class::<PyContentInfo>()?;
    m.add_class::<PySignedData>()?;
    m.add_class::<PySignerInfo>()?;
    m.add_class::<PyEnvelopedData>()?;
    m.add_class::<PyEncryptedData>()?;
    m.add_class::<PyDigestedData>()?;
    m.add_class::<PyAuthenticatedData>()?;
    m.add_class::<PyIssuerAndSerialNumber>()?;
    m.add_class::<PyKEMRecipientInfo>()?;
    m.add_class::<PyCMSORIforKEMOtherInfo>()?;

    // Content-type OIDs (RFC 5652 §14)
    m.add(
        "ID_DATA",
        oid_const(py, synta_certificate::pkcs7_types::ID_DATA),
    )?;
    m.add(
        "ID_SIGNED_DATA",
        oid_const(py, synta_certificate::pkcs7_types::ID_SIGNED_DATA),
    )?;
    m.add(
        "ID_ENVELOPED_DATA",
        oid_const(py, synta_certificate::pkcs7_types::ID_ENVELOPED_DATA),
    )?;
    m.add(
        "ID_ENCRYPTED_DATA",
        oid_const(py, synta_certificate::pkcs7_types::ID_ENCRYPTED_DATA),
    )?;
    m.add(
        "ID_DIGESTED_DATA",
        oid_const(py, synta_certificate::oids::CMS_DIGESTED_DATA),
    )?;
    m.add(
        "ID_CT_AUTH_DATA",
        oid_const(py, synta_certificate::oids::CMS_AUTH_DATA),
    )?;
    // OtherRecipientInfo OIDs (RFC 9629 §6.2)
    m.add(
        "ID_ORI",
        oid_const(py, synta_certificate::cms_kem_types::ID_ORI),
    )?;
    m.add(
        "ID_ORI_KEM",
        oid_const(py, synta_certificate::cms_kem_types::ID_ORI_KEM),
    )?;
    // Content-encryption algorithm OIDs (NIST AES, RFC 3565)
    m.add(
        "ID_AES128_CBC",
        oid_const(py, synta_certificate::pkcs12_types::ID_AES128_CBC),
    )?;
    m.add(
        "ID_AES192_CBC",
        oid_const(py, synta_certificate::pkcs12_types::ID_AES192_CBC),
    )?;
    m.add(
        "ID_AES256_CBC",
        oid_const(py, synta_certificate::pkcs12_types::ID_AES256_CBC),
    )?;

    crate::install_submodule(
        parent,
        &m,
        "synta.cms",
        Some(
            "synta.cms — CMS (RFC 5652) and CMS-KEM (RFC 9629) types.\n\
             \n\
             Provides ContentInfo, SignedData, SignerInfo, EnvelopedData,\n\
             EncryptedData, DigestedData, AuthenticatedData,\n\
             IssuerAndSerialNumber, KEMRecipientInfo, CMSORIforKEMOtherInfo,\n\
             along with content-type and OtherRecipientInfo OID constants.",
        ),
    )
}

/// Call this from a cdylib extension crate's `#[pymodule]` function:
///
/// ```rust,ignore
/// #[pymodule]
/// fn my_extension(_py: Python, m: &Bound<'_, PyModule>) -> PyResult<()> {
///     synta_certificate::python::register_module(m)
/// }
/// ```
pub fn register_module(m: &Bound<'_, PyModule>) -> PyResult<()> {
    m.add_class::<PyObjectIdentifier>()?;
    m.add_class::<PyCertificate>()?;
    m.add_class::<PyCsr>()?;
    m.add_class::<PyCrl>()?;
    m.add_class::<PyOcspResponse>()?;
    m.add_function(wrap_pyfunction!(load_der_pkcs7_certificates, m)?)?;
    m.add_function(wrap_pyfunction!(load_pem_pkcs7_certificates, m)?)?;
    m.add_function(wrap_pyfunction!(load_pkcs12_certificates, m)?)?;
    m.add_function(wrap_pyfunction!(load_pkcs12_keys, m)?)?;
    m.add_function(wrap_pyfunction!(load_pkcs12, m)?)?;
    m.add_function(wrap_pyfunction!(read_pki_blocks, m)?)?;
    register_oids_submodule(m)?;
    register_cms_submodule(m)?;
    register_general_name_submodule(m)?;
    Ok(())
}

// ── OID helper functions (exposed in synta.oids) ─────────────────────────────
//
// Each function accepts either a PyObjectIdentifier or a dotted-decimal str,
// delegating to the corresponding crate-level helper in lib.rs.

/// Return the canonical display name for a signature algorithm OID.
///
/// Recognises RSA (PKCS #1) variants, ECDSA variants, EdDSA, ML-DSA (FIPS
/// 204), and SLH-DSA (FIPS 205). Returns ``"Other"`` for unknown OIDs.
///
/// :param oid: :class:`~synta.ObjectIdentifier` or dotted-decimal ``str``.
/// :returns: algorithm name string (one of the ``synta.oids`` name constants).
#[pyfunction]
fn identify_signature_algorithm(oid: &Bound<'_, PyAny>) -> PyResult<&'static str> {
    let inner = oid_from_pyany(oid)?;
    Ok(synta_certificate::identify_signature_algorithm(&inner))
}

/// Return the canonical display name for a public-key algorithm OID, if known.
///
/// Recognises RSA, EC/ECDSA, DSA, EdDSA, ML-DSA, and ML-KEM.
/// Returns ``None`` for unrecognised OIDs.
///
/// :param oid: :class:`~synta.ObjectIdentifier` or dotted-decimal ``str``.
/// :returns: algorithm name string or ``None``.
#[pyfunction]
fn identify_public_key_algorithm(oid: &Bound<'_, PyAny>) -> PyResult<Option<&'static str>> {
    let inner = oid_from_pyany(oid)?;
    Ok(synta_certificate::identify_public_key_algorithm(&inner))
}

/// Return the short ASN.1 name for a well-known EC named-curve OID.
///
/// Returns ``None`` for unrecognised curves.
///
/// :param oid: :class:`~synta.ObjectIdentifier` or dotted-decimal ``str``.
/// :returns: e.g. ``"prime256v1"``, ``"secp384r1"``, or ``None``.
#[pyfunction]
fn ec_curve_short_name(oid: &Bound<'_, PyAny>) -> PyResult<Option<&'static str>> {
    let inner = oid_from_pyany(oid)?;
    Ok(synta_certificate::ec_curve_short_name(inner.components()))
}

/// Return the NIST name for a well-known EC named-curve OID.
///
/// Returns ``None`` for curves with no NIST name (e.g. ``secp256k1``).
///
/// :param oid: :class:`~synta.ObjectIdentifier` or dotted-decimal ``str``.
/// :returns: e.g. ``"P-256"``, ``"P-384"``, or ``None``.
#[pyfunction]
fn ec_curve_nist_name(oid: &Bound<'_, PyAny>) -> PyResult<Option<&'static str>> {
    let inner = oid_from_pyany(oid)?;
    Ok(synta_certificate::ec_curve_nist_name(inner.components()))
}

/// Return the key size in bits for a well-known EC named-curve OID.
///
/// Returns the field size (security parameter) as reported by OpenSSL.
/// Returns ``None`` for unrecognised curves.
///
/// :param oid: :class:`~synta.ObjectIdentifier` or dotted-decimal ``str``.
/// :returns: e.g. ``256``, ``384``, ``521``, or ``None``.
#[pyfunction]
fn ec_curve_key_bits(oid: &Bound<'_, PyAny>) -> PyResult<Option<usize>> {
    let inner = oid_from_pyany(oid)?;
    Ok(synta_certificate::ec_curve_key_bits(inner.components()))
}

/// Return the display name for a well-known X.509v3 extension OID.
///
/// Covers all RFC 5280 standard extensions and the Certificate Transparency
/// SCT extension. Returns the dotted-decimal string for unknown OIDs.
///
/// :param oid: :class:`~synta.ObjectIdentifier` or dotted-decimal ``str``.
/// :returns: human-readable name, e.g. ``"X509v3 Subject Alternative Name"``.
#[pyfunction]
fn extension_oid_name(oid: &Bound<'_, PyAny>) -> PyResult<String> {
    let inner = oid_from_pyany(oid)?;
    Ok(synta_certificate::extension_oid_name(&inner))
}

// ── OID constants submodule ──────────────────────────────────────────────────

/// Convert a well-known `&[u32]` component slice to a Python `ObjectIdentifier`.
///
/// Panics at module-init time if the slice is not a valid OID — every caller
/// passes a constant generated from the ASN.1 schema, so a panic here is a
/// bug in the source data.
fn oid_const(py: Python<'_>, components: &[u32]) -> Py<PyAny> {
    let inner = ObjectIdentifier::new(components)
        .expect("oid constant has invalid components — bug in synta-certificate");
    Py::new(py, PyObjectIdentifier::from_oid(inner))
        .expect("PyObjectIdentifier allocation failed")
        .into_any()
}

/// Build and register the ``synta.oids`` submodule.
///
/// Also registers ``synta.oids.attr`` for DN attribute OIDs and installs both
/// into ``sys.modules`` so that ``from synta.oids import ...`` works.
fn register_oids_submodule(parent: &Bound<'_, PyModule>) -> PyResult<()> {
    let py = parent.py();
    let m = PyModule::new(py, "oids")?;

    // ── ML-DSA (FIPS 204) ────────────────────────────────────────────────────
    m.add(
        "ML_DSA_44",
        oid_const(py, synta_certificate::oids::ML_DSA_44),
    )?;
    m.add(
        "ML_DSA_65",
        oid_const(py, synta_certificate::oids::ML_DSA_65),
    )?;
    m.add(
        "ML_DSA_87",
        oid_const(py, synta_certificate::oids::ML_DSA_87),
    )?;

    // ── ML-KEM (FIPS 203) ────────────────────────────────────────────────────
    m.add(
        "ML_KEM_512",
        oid_const(py, synta_certificate::oids::ML_KEM_512),
    )?;
    m.add(
        "ML_KEM_768",
        oid_const(py, synta_certificate::oids::ML_KEM_768),
    )?;
    m.add(
        "ML_KEM_1024",
        oid_const(py, synta_certificate::oids::ML_KEM_1024),
    )?;

    // ── SLH-DSA (FIPS 205) ───────────────────────────────────────────────────
    m.add(
        "SLH_DSA_SHA2_128S",
        oid_const(py, synta_certificate::oids::ID_SLH_DSA_SHA2_128S),
    )?;
    m.add(
        "SLH_DSA_SHA2_128F",
        oid_const(py, synta_certificate::oids::ID_SLH_DSA_SHA2_128F),
    )?;
    m.add(
        "SLH_DSA_SHA2_192S",
        oid_const(py, synta_certificate::oids::ID_SLH_DSA_SHA2_192S),
    )?;
    m.add(
        "SLH_DSA_SHA2_192F",
        oid_const(py, synta_certificate::oids::ID_SLH_DSA_SHA2_192F),
    )?;
    m.add(
        "SLH_DSA_SHA2_256S",
        oid_const(py, synta_certificate::oids::ID_SLH_DSA_SHA2_256S),
    )?;
    m.add(
        "SLH_DSA_SHA2_256F",
        oid_const(py, synta_certificate::oids::ID_SLH_DSA_SHA2_256F),
    )?;
    m.add(
        "SLH_DSA_SHAKE_128S",
        oid_const(py, synta_certificate::oids::ID_SLH_DSA_SHAKE_128S),
    )?;
    m.add(
        "SLH_DSA_SHAKE_128F",
        oid_const(py, synta_certificate::oids::ID_SLH_DSA_SHAKE_128F),
    )?;
    m.add(
        "SLH_DSA_SHAKE_192S",
        oid_const(py, synta_certificate::oids::ID_SLH_DSA_SHAKE_192S),
    )?;
    m.add(
        "SLH_DSA_SHAKE_192F",
        oid_const(py, synta_certificate::oids::ID_SLH_DSA_SHAKE_192F),
    )?;
    m.add(
        "SLH_DSA_SHAKE_256S",
        oid_const(py, synta_certificate::oids::ID_SLH_DSA_SHAKE_256S),
    )?;
    m.add(
        "SLH_DSA_SHAKE_256F",
        oid_const(py, synta_certificate::oids::ID_SLH_DSA_SHAKE_256F),
    )?;

    // ── EdDSA (RFC 8410) ─────────────────────────────────────────────────────
    m.add("ED25519", oid_const(py, synta_certificate::oids::ED25519))?;
    m.add("ED448", oid_const(py, synta_certificate::oids::ED448))?;

    // ── RSA (PKCS #1) ────────────────────────────────────────────────────────
    m.add(
        "RSA_ENCRYPTION",
        oid_const(py, synta_certificate::oids::RSA_ENCRYPTION),
    )?;
    m.add(
        "MD5_WITH_RSA",
        oid_const(py, synta_certificate::oids::MD5_WITH_RSA),
    )?;
    m.add(
        "SHA1_WITH_RSA",
        oid_const(py, synta_certificate::oids::SHA1_WITH_RSA),
    )?;
    m.add(
        "SHA256_WITH_RSA",
        oid_const(py, synta_certificate::oids::SHA256_WITH_RSA),
    )?;
    m.add(
        "SHA384_WITH_RSA",
        oid_const(py, synta_certificate::oids::SHA384_WITH_RSA),
    )?;
    m.add(
        "SHA512_WITH_RSA",
        oid_const(py, synta_certificate::oids::SHA512_WITH_RSA),
    )?;
    // Prefix OID covering all PKCS #1 RSA variants
    m.add("RSA", oid_const(py, synta_certificate::oids::RSA))?;

    // ── ECDSA (ANSI X9.62 / RFC 5758) ────────────────────────────────────────
    m.add(
        "EC_PUBLIC_KEY",
        oid_const(py, synta_certificate::oids::EC_PUBLIC_KEY),
    )?;
    m.add(
        "ECDSA_WITH_SHA1",
        oid_const(py, synta_certificate::oids::ECDSA_WITH_SHA1),
    )?;
    m.add(
        "ECDSA_WITH_SHA256",
        oid_const(py, synta_certificate::oids::ECDSA_WITH_SHA256),
    )?;
    m.add(
        "ECDSA_WITH_SHA384",
        oid_const(py, synta_certificate::oids::ECDSA_WITH_SHA384),
    )?;
    m.add(
        "ECDSA_WITH_SHA512",
        oid_const(py, synta_certificate::oids::ECDSA_WITH_SHA512),
    )?;
    // Prefix OID covering all ECDSA signature variants
    m.add("ECDSA", oid_const(py, synta_certificate::oids::ECDSA_SIG))?;

    // ── EC named curves (SEC 2 / RFC 5480) ───────────────────────────────────
    m.add(
        "EC_CURVE_P256",
        oid_const(py, synta_certificate::oids::EC_CURVE_P256),
    )?;
    m.add(
        "EC_CURVE_P384",
        oid_const(py, synta_certificate::oids::EC_CURVE_P384),
    )?;
    m.add(
        "EC_CURVE_P521",
        oid_const(py, synta_certificate::oids::EC_CURVE_P521),
    )?;
    m.add(
        "EC_CURVE_SECP256K1",
        oid_const(py, synta_certificate::oids::EC_CURVE_SECP256K1),
    )?;

    // ── SHA-2 hash algorithms (FIPS 180-4) ───────────────────────────────────
    m.add("SHA224", oid_const(py, synta_certificate::oids::ID_SHA224))?;
    m.add("SHA256", oid_const(py, synta_certificate::oids::ID_SHA256))?;
    m.add("SHA384", oid_const(py, synta_certificate::oids::ID_SHA384))?;
    m.add("SHA512", oid_const(py, synta_certificate::oids::ID_SHA512))?;
    m.add(
        "SHA512_224",
        oid_const(py, synta_certificate::oids::ID_SHA512_224),
    )?;
    m.add(
        "SHA512_256",
        oid_const(py, synta_certificate::oids::ID_SHA512_256),
    )?;

    // ── SHA-3 hash algorithms and XOFs (FIPS 202) ────────────────────────────
    m.add(
        "SHA3_224",
        oid_const(py, synta_certificate::oids::ID_SHA3_224),
    )?;
    m.add(
        "SHA3_256",
        oid_const(py, synta_certificate::oids::ID_SHA3_256),
    )?;
    m.add(
        "SHA3_384",
        oid_const(py, synta_certificate::oids::ID_SHA3_384),
    )?;
    m.add(
        "SHA3_512",
        oid_const(py, synta_certificate::oids::ID_SHA3_512),
    )?;
    m.add(
        "SHAKE128",
        oid_const(py, synta_certificate::oids::ID_SHAKE128),
    )?;
    m.add(
        "SHAKE256",
        oid_const(py, synta_certificate::oids::ID_SHAKE256),
    )?;

    // ── X.509v3 extension OIDs (RFC 5280 / 2.5.29.*) ─────────────────────────
    m.add(
        "SUBJECT_KEY_IDENTIFIER",
        oid_const(py, synta_certificate::oids::SUBJECT_KEY_IDENTIFIER),
    )?;
    m.add(
        "KEY_USAGE",
        oid_const(py, synta_certificate::oids::KEY_USAGE),
    )?;
    m.add(
        "SUBJECT_ALT_NAME",
        oid_const(py, synta_certificate::oids::SUBJECT_ALT_NAME),
    )?;
    m.add(
        "ISSUER_ALT_NAME",
        oid_const(py, synta_certificate::oids::ISSUER_ALT_NAME),
    )?;
    m.add(
        "BASIC_CONSTRAINTS",
        oid_const(py, synta_certificate::oids::BASIC_CONSTRAINTS),
    )?;
    m.add(
        "CRL_DISTRIBUTION_POINTS",
        oid_const(py, synta_certificate::oids::CRL_DISTRIBUTION_POINTS),
    )?;
    m.add(
        "CERTIFICATE_POLICIES",
        oid_const(py, synta_certificate::oids::CERTIFICATE_POLICIES),
    )?;
    m.add(
        "AUTHORITY_KEY_IDENTIFIER",
        oid_const(py, synta_certificate::oids::AUTHORITY_KEY_IDENTIFIER),
    )?;
    m.add(
        "EXTENDED_KEY_USAGE",
        oid_const(py, synta_certificate::oids::EXTENDED_KEY_USAGE),
    )?;
    m.add(
        "AUTHORITY_INFO_ACCESS",
        oid_const(py, synta_certificate::oids::AUTHORITY_INFO_ACCESS),
    )?;
    m.add(
        "CT_PRECERT_SCTS",
        oid_const(py, synta_certificate::oids::CT_PRECERT_SCTS),
    )?;

    // ── Extended Key Usage key-purpose OIDs (RFC 5280 §4.2.1.12) ─────────────
    m.add(
        "KP_SERVER_AUTH",
        oid_const(py, synta_certificate::oids::KP_SERVER_AUTH),
    )?;
    m.add(
        "KP_CLIENT_AUTH",
        oid_const(py, synta_certificate::oids::KP_CLIENT_AUTH),
    )?;
    m.add(
        "KP_CODE_SIGNING",
        oid_const(py, synta_certificate::oids::KP_CODE_SIGNING),
    )?;
    m.add(
        "KP_EMAIL_PROTECTION",
        oid_const(py, synta_certificate::oids::KP_EMAIL_PROTECTION),
    )?;
    m.add(
        "KP_TIME_STAMPING",
        oid_const(py, synta_certificate::oids::KP_TIME_STAMPING),
    )?;
    m.add(
        "KP_OCSP_SIGNING",
        oid_const(py, synta_certificate::oids::KP_OCSP_SIGNING),
    )?;
    m.add(
        "ANY_EXTENDED_KEY_USAGE",
        oid_const(py, synta_certificate::oids::ANY_EXTENDED_KEY_USAGE),
    )?;

    // ── PKINIT OIDs (RFC 4556 + RFC 6112 + RFC 8636) ─────────────────────────
    m.add(
        "PKINIT_SAN",
        oid_const(py, synta_certificate::oids::ID_PKINIT_SAN),
    )?;
    m.add(
        "PKINIT_KP_CLIENT_AUTH",
        oid_const(py, synta_certificate::oids::ID_PKINIT_KPCLIENT_AUTH),
    )?;
    m.add(
        "PKINIT_KP_KDC",
        oid_const(py, synta_certificate::oids::ID_PKINIT_KPKDC),
    )?;
    m.add(
        "PKINIT_AUTH_DATA",
        oid_const(py, synta_certificate::oids::ID_PKINIT_AUTH_DATA),
    )?;
    m.add(
        "PKINIT_DHKEY_DATA",
        oid_const(py, synta_certificate::oids::ID_PKINIT_DHKEY_DATA),
    )?;
    m.add(
        "PKINIT_RKEY_DATA",
        oid_const(py, synta_certificate::oids::ID_PKINIT_RKEY_DATA),
    )?;
    m.add(
        "PKINIT_KDF",
        oid_const(py, synta_certificate::oids::ID_PKINIT_KDF),
    )?;
    m.add(
        "PKINIT_KDF_SHA1",
        oid_const(py, synta_certificate::oids::ID_PKINIT_KDF_AH_SHA1),
    )?;
    m.add(
        "PKINIT_KDF_SHA256",
        oid_const(py, synta_certificate::oids::ID_PKINIT_KDF_AH_SHA256),
    )?;
    m.add(
        "PKINIT_KDF_SHA384",
        oid_const(py, synta_certificate::oids::ID_PKINIT_KDF_AH_SHA384),
    )?;
    m.add(
        "PKINIT_KDF_SHA512",
        oid_const(py, synta_certificate::oids::ID_PKINIT_KDF_AH_SHA512),
    )?;

    // ── Microsoft PKI OIDs (AD CS) ────────────────────────────────────────────
    m.add(
        "MS_SAN_UPN",
        oid_const(py, synta_certificate::oids::ID_MS_SAN_UPN),
    )?;
    m.add(
        "MS_CERTIFICATE_TEMPLATE_NAME",
        oid_const(py, synta_certificate::oids::ID_MS_CERTIFICATE_TEMPLATE_NAME),
    )?;
    m.add(
        "MS_CERTIFICATE_TEMPLATE",
        oid_const(py, synta_certificate::oids::ID_MS_CERTIFICATE_TEMPLATE),
    )?;
    m.add(
        "MS_KP_SMARTCARD_LOGON",
        oid_const(py, synta_certificate::oids::ID_MS_KP_SMARTCARD_LOGON),
    )?;
    m.add(
        "MS_NTDS_REPLICATION",
        oid_const(py, synta_certificate::oids::ID_MS_NTDS_REPLICATION),
    )?;

    // ── CMS content-type OIDs (RFC 5652 §14) ─────────────────────────────────
    m.add("CMS_DATA", oid_const(py, synta_certificate::oids::CMS_DATA))?;
    m.add(
        "CMS_SIGNED_DATA",
        oid_const(py, synta_certificate::oids::CMS_SIGNED_DATA),
    )?;
    m.add(
        "CMS_ENVELOPED_DATA",
        oid_const(py, synta_certificate::oids::CMS_ENVELOPED_DATA),
    )?;
    m.add(
        "CMS_DIGESTED_DATA",
        oid_const(py, synta_certificate::oids::CMS_DIGESTED_DATA),
    )?;
    m.add(
        "CMS_ENCRYPTED_DATA",
        oid_const(py, synta_certificate::oids::CMS_ENCRYPTED_DATA),
    )?;
    m.add(
        "CMS_AUTH_DATA",
        oid_const(py, synta_certificate::oids::CMS_AUTH_DATA),
    )?;
    // ── CMS-KEM OtherRecipientInfo OIDs (RFC 9629 §6.2) ──────────────────────
    m.add("CMS_ORI", oid_const(py, synta_certificate::oids::CMS_ORI))?;
    m.add(
        "CMS_ORI_KEM",
        oid_const(py, synta_certificate::oids::CMS_ORI_KEM),
    )?;

    // ── PKCS#9 attribute OIDs (RFC 2985 / RFC 5652 §11 / RFC 2986 / RFC 7292) ─
    m.add(
        "PKCS9_EMAIL_ADDRESS",
        oid_const(py, synta_certificate::oids::PKCS9_EMAIL_ADDRESS),
    )?;
    m.add(
        "PKCS9_CONTENT_TYPE",
        oid_const(py, synta_certificate::oids::PKCS9_CONTENT_TYPE),
    )?;
    m.add(
        "PKCS9_MESSAGE_DIGEST",
        oid_const(py, synta_certificate::oids::PKCS9_MESSAGE_DIGEST),
    )?;
    m.add(
        "PKCS9_SIGNING_TIME",
        oid_const(py, synta_certificate::oids::PKCS9_SIGNING_TIME),
    )?;
    m.add(
        "PKCS9_COUNTERSIGNATURE",
        oid_const(py, synta_certificate::oids::PKCS9_COUNTERSIGNATURE),
    )?;
    m.add(
        "PKCS9_CHALLENGE_PASSWORD",
        oid_const(py, synta_certificate::oids::PKCS9_CHALLENGE_PASSWORD),
    )?;
    m.add(
        "PKCS9_EXTENSION_REQUEST",
        oid_const(py, synta_certificate::oids::PKCS9_EXTENSION_REQUEST),
    )?;
    m.add(
        "PKCS9_FRIENDLY_NAME",
        oid_const(py, synta_certificate::oids::PKCS9_FRIENDLY_NAME),
    )?;
    m.add(
        "PKCS9_LOCAL_KEY_ID",
        oid_const(py, synta_certificate::oids::PKCS9_LOCAL_KEY_ID),
    )?;

    // ── Helper functions ─────────────────────────────────────────────────────
    m.add_function(wrap_pyfunction!(identify_signature_algorithm, &m)?)?;
    m.add_function(wrap_pyfunction!(identify_public_key_algorithm, &m)?)?;
    m.add_function(wrap_pyfunction!(ec_curve_short_name, &m)?)?;
    m.add_function(wrap_pyfunction!(ec_curve_nist_name, &m)?)?;
    m.add_function(wrap_pyfunction!(ec_curve_key_bits, &m)?)?;
    m.add_function(wrap_pyfunction!(extension_oid_name, &m)?)?;

    // ── DN attribute OID submodule ────────────────────────────────────────────
    let attr = PyModule::new(py, "attr")?;
    attr.add(
        "__doc__",
        "OIDs for X.500 Distinguished Name attribute types (RFC 4519).",
    )?;
    attr.add(
        "COMMON_NAME",
        oid_const(py, synta_certificate::oids::attr::COMMON_NAME),
    )?;
    attr.add(
        "COUNTRY",
        oid_const(py, synta_certificate::oids::attr::COUNTRY),
    )?;
    attr.add("STATE", oid_const(py, synta_certificate::oids::attr::STATE))?;
    attr.add(
        "LOCALITY",
        oid_const(py, synta_certificate::oids::attr::LOCALITY),
    )?;
    attr.add(
        "ORGANIZATION",
        oid_const(py, synta_certificate::oids::attr::ORGANIZATION),
    )?;
    attr.add(
        "ORG_UNIT",
        oid_const(py, synta_certificate::oids::attr::ORG_UNIT),
    )?;
    attr.add(
        "ORG_IDENTIFIER",
        oid_const(py, synta_certificate::oids::attr::ORG_IDENTIFIER),
    )?;
    attr.add(
        "STREET",
        oid_const(py, synta_certificate::oids::attr::STREET),
    )?;
    attr.add(
        "SURNAME",
        oid_const(py, synta_certificate::oids::attr::SURNAME),
    )?;
    attr.add(
        "GIVEN_NAME",
        oid_const(py, synta_certificate::oids::attr::GIVEN_NAME),
    )?;
    attr.add(
        "INITIALS",
        oid_const(py, synta_certificate::oids::attr::INITIALS),
    )?;
    attr.add("TITLE", oid_const(py, synta_certificate::oids::attr::TITLE))?;
    attr.add(
        "SERIAL_NUMBER",
        oid_const(py, synta_certificate::oids::attr::SERIAL_NUMBER),
    )?;
    attr.add(
        "EMAIL_ADDRESS",
        oid_const(py, synta_certificate::oids::attr::EMAIL_ADDRESS),
    )?;
    attr.add(
        "USER_ID",
        oid_const(py, synta_certificate::oids::attr::USER_ID),
    )?;
    attr.add(
        "DOMAIN_COMPONENT",
        oid_const(py, synta_certificate::oids::attr::DOMAIN_COMPONENT),
    )?;

    crate::install_submodule(&m, &attr, "synta.oids.attr", None)?;
    crate::install_submodule(
        parent,
        &m,
        "synta.oids",
        Some("OID constants for X.509 signature, public-key, and extension algorithms."),
    )
}

// ── GeneralName tag constants (synta.general_name) ───────────────────────────

fn register_general_name_submodule(parent: &Bound<'_, PyModule>) -> PyResult<()> {
    let py = parent.py();
    let m = PyModule::new(py, "general_name")?;

    // ── GeneralName alternatives ─────────────────────────────────────────────
    m.add("OTHER_NAME", synta_certificate::general_name::OTHER_NAME)?;
    m.add("RFC822_NAME", synta_certificate::general_name::RFC822_NAME)?;
    m.add("DNS_NAME", synta_certificate::general_name::DNS_NAME)?;
    m.add(
        "X400_ADDRESS",
        synta_certificate::general_name::X400_ADDRESS,
    )?;
    m.add(
        "DIRECTORY_NAME",
        synta_certificate::general_name::DIRECTORY_NAME,
    )?;
    m.add(
        "EDI_PARTY_NAME",
        synta_certificate::general_name::EDI_PARTY_NAME,
    )?;
    m.add("URI", synta_certificate::general_name::URI)?;
    m.add("IP_ADDRESS", synta_certificate::general_name::IP_ADDRESS)?;
    m.add(
        "REGISTERED_ID",
        synta_certificate::general_name::REGISTERED_ID,
    )?;

    crate::install_submodule(
        parent,
        &m,
        "synta.general_name",
        Some(concat!(
            "Context-specific tag numbers for the ``GeneralName`` CHOICE type ",
            "(RFC 5280 \u{a7}4.2.1.6).\n\n",
            "These integer constants correspond to the first element of tuples returned by\n",
            ":func:`~synta.parse_general_names` and ",
            ":meth:`~synta.Certificate.subject_alt_names`.\n\n",
            "Example usage::\n\n",
            "    import synta.general_name as gn\n",
            "    for tag, content in cert.subject_alt_names():\n",
            "        if tag == gn.DNS_NAME:\n",
            "            print('DNS:', content.decode())\n",
            "        elif tag == gn.IP_ADDRESS:\n",
            "            print('IP:', content.hex())",
        )),
    )
}