synta-python 0.3.0

//! Python bindings for RFC 2634 Extended Security Services (ESS) builders.
//!
//! Exposes three builder classes:
//!
//! - [`PySigningCertificateBuilder`] — ``SigningCertificate`` (§5.4)
//! - [`PyReceiptRequestBuilder`] — ``ReceiptRequest`` (§2.7)
//! - [`PyESSSecurityLabelBuilder`] — ``ESSSecurityLabel`` (§3.2)

use pyo3::prelude::*;
use pyo3::types::PyBytes;

// ── PySigningCertificateBuilder ───────────────────────────────────────────────

/// Python-facing wrapper for [`synta_certificate::SigningCertificateBuilder`].
///
/// Builds a DER-encoded ``SigningCertificate`` (RFC 2634 §5.4).
///
/// ``SigningCertificate`` is a CMS signed attribute that identifies the
/// signer's certificate by its SHA-1 hash and optionally by its
/// issuer/serial number.
///
/// At least one certificate ID must be added before calling :meth:`build`.
///
/// Example::
///
///     import synta
///
///     # SHA-1 hash of the signer's DER certificate
///     import hashlib
///     cert_sha1 = hashlib.sha1(cert_der).digest()
///
///     sc_der = (
///         synta.SigningCertificateBuilder()
///         .add_cert_id(cert_sha1, None)
///         .build()
///     )
#[pyclass(name = "SigningCertificateBuilder")]
pub struct PySigningCertificateBuilder {
    inner: synta_certificate::SigningCertificateBuilder,
    built: bool,
}

#[pymethods]
impl PySigningCertificateBuilder {
    /// Create a new, empty ``SigningCertificateBuilder``.
    #[new]
    fn new() -> Self {
        Self {
            inner: synta_certificate::SigningCertificateBuilder::new(),
            built: false,
        }
    }

    /// Add a certificate entry identified by its SHA-1 hash.
    ///
    /// :param cert_hash: 20-byte SHA-1 hash of the complete DER-encoded
    ///     certificate.
    /// :param issuer_serial_der: optional pre-encoded ``IssuerSerial``
    ///     SEQUENCE DER TLV, or ``None`` to omit.
    /// :raises ValueError: if ``issuer_serial_der`` decoding fails
    ///     (deferred to :meth:`build`).
    fn add_cert_id<'py>(
        slf: Bound<'py, Self>,
        cert_hash: &[u8],
        issuer_serial_der: Option<&[u8]>,
    ) -> Bound<'py, Self> {
        {
            let mut guard = slf.borrow_mut();
            let old = std::mem::replace(
                &mut guard.inner,
                synta_certificate::SigningCertificateBuilder::new(),
            );
            guard.inner = old.add_cert_id(cert_hash, issuer_serial_der);
        }
        slf
    }

    /// Add a certificate policy OID to the optional ``policies`` field.
    ///
    /// :param policy_oid: policy OID as a list of integer arc components.
    /// :raises ValueError: if the OID is invalid (deferred to :meth:`build`).
    fn add_policy<'py>(slf: Bound<'py, Self>, policy_oid: Vec<u32>) -> Bound<'py, Self> {
        {
            let mut guard = slf.borrow_mut();
            let old = std::mem::replace(
                &mut guard.inner,
                synta_certificate::SigningCertificateBuilder::new(),
            );
            guard.inner = old.add_policy(&policy_oid);
        }
        slf
    }

    /// Build the DER-encoded ``SigningCertificate`` SEQUENCE.
    ///
    /// :returns: DER bytes of the ``SigningCertificate``.
    /// :raises ValueError: if no certificate IDs were added, if DER encoding
    ///     fails, or if called more than once.
    fn build<'py>(&mut self, py: Python<'py>) -> PyResult<Bound<'py, PyBytes>> {
        if self.built {
            return Err(pyo3::exceptions::PyValueError::new_err(
                "build() has already been called; create a new builder",
            ));
        }
        self.built = true;
        let inner = std::mem::replace(
            &mut self.inner,
            synta_certificate::SigningCertificateBuilder::new(),
        );
        let der = inner
            .build()
            .map_err(pyo3::exceptions::PyValueError::new_err)?;
        Ok(PyBytes::new(py, &der))
    }

    fn __repr__(&self) -> String {
        "SigningCertificateBuilder()".to_string()
    }
}

// ── PyReceiptRequestBuilder ───────────────────────────────────────────────────

/// Python-facing wrapper for [`synta_certificate::ReceiptRequestBuilder`].
///
/// Builds a DER-encoded ``ReceiptRequest`` (RFC 2634 §2.7).
///
/// A ``ReceiptRequest`` is a CMS signed attribute that requests a signed
/// receipt.  Required fields: ``signed_content_identifier`` and one
/// ``receipts_from_*`` call.
///
/// Example::
///
///     import synta
///
///     rr_der = (
///         synta.ReceiptRequestBuilder()
///         .signed_content_identifier(b"\\x01\\x02\\x03\\x04")
///         .receipts_from_all()
///         .add_receipt_to_email("receipts@example.com")
///         .build()
///     )
#[pyclass(name = "ReceiptRequestBuilder")]
pub struct PyReceiptRequestBuilder {
    inner: synta_certificate::ReceiptRequestBuilder,
    built: bool,
}

#[pymethods]
impl PyReceiptRequestBuilder {
    /// Create a new, empty ``ReceiptRequestBuilder``.
    #[new]
    fn new() -> Self {
        Self {
            inner: synta_certificate::ReceiptRequestBuilder::new(),
            built: false,
        }
    }

    /// Set the ``signedContentIdentifier`` (an OCTET STRING value).
    ///
    /// :param id: the content identifier bytes.
    fn signed_content_identifier<'py>(slf: Bound<'py, Self>, id: &[u8]) -> Bound<'py, Self> {
        {
            let mut guard = slf.borrow_mut();
            let old = std::mem::replace(
                &mut guard.inner,
                synta_certificate::ReceiptRequestBuilder::new(),
            );
            guard.inner = old.signed_content_identifier(id);
        }
        slf
    }

    /// Request receipts from all recipients (``allReceipts [0]``).
    fn receipts_from_all<'py>(slf: Bound<'py, Self>) -> Bound<'py, Self> {
        {
            let mut guard = slf.borrow_mut();
            let old = std::mem::replace(
                &mut guard.inner,
                synta_certificate::ReceiptRequestBuilder::new(),
            );
            guard.inner = old.receipts_from_all();
        }
        slf
    }

    /// Request receipts from first-tier recipients only
    /// (``firstTierRecipients``, value 1 within the ``allOrFirstTier [0]`` CHOICE).
    /// (``firstTierOnly [1]``).
    fn receipts_from_first_tier<'py>(slf: Bound<'py, Self>) -> Bound<'py, Self> {
        {
            let mut guard = slf.borrow_mut();
            let old = std::mem::replace(
                &mut guard.inner,
                synta_certificate::ReceiptRequestBuilder::new(),
            );
            guard.inner = old.receipts_from_first_tier();
        }
        slf
    }

    /// Add an email address to the ``receiptsTo`` list.
    ///
    /// Each entry in ``receiptsTo`` is a ``GeneralNames`` (SEQUENCE OF
    /// GeneralName).  This convenience method wraps a single RFC 822 name.
    ///
    /// :param email: email address string.
    /// :raises ValueError: if the email address is invalid (deferred to
    ///     :meth:`build`).
    fn add_receipt_to_email<'py>(slf: Bound<'py, Self>, email: &str) -> Bound<'py, Self> {
        {
            let mut guard = slf.borrow_mut();
            let old = std::mem::replace(
                &mut guard.inner,
                synta_certificate::ReceiptRequestBuilder::new(),
            );
            guard.inner = old.add_receipt_to_email(email);
        }
        slf
    }

    /// Add a pre-encoded ``GeneralNames`` DER TLV to the ``receiptsTo`` list.
    ///
    /// :param general_names_der: DER-encoded ``GeneralNames`` SEQUENCE TLV.
    fn add_receipt_to_raw<'py>(
        slf: Bound<'py, Self>,
        general_names_der: &[u8],
    ) -> Bound<'py, Self> {
        {
            let mut guard = slf.borrow_mut();
            let old = std::mem::replace(
                &mut guard.inner,
                synta_certificate::ReceiptRequestBuilder::new(),
            );
            guard.inner = old.add_receipt_to_raw(general_names_der);
        }
        slf
    }

    /// Build the DER-encoded ``ReceiptRequest`` SEQUENCE.
    ///
    /// :returns: DER bytes of the ``ReceiptRequest``.
    /// :raises ValueError: if required fields are missing, DER encoding fails,
    ///     or if called more than once.
    fn build<'py>(&mut self, py: Python<'py>) -> PyResult<Bound<'py, PyBytes>> {
        if self.built {
            return Err(pyo3::exceptions::PyValueError::new_err(
                "build() has already been called; create a new builder",
            ));
        }
        self.built = true;
        let inner = std::mem::replace(
            &mut self.inner,
            synta_certificate::ReceiptRequestBuilder::new(),
        );
        let der = inner
            .build()
            .map_err(pyo3::exceptions::PyValueError::new_err)?;
        Ok(PyBytes::new(py, &der))
    }

    fn __repr__(&self) -> String {
        "ReceiptRequestBuilder()".to_string()
    }
}

// ── PyESSSecurityLabelBuilder ─────────────────────────────────────────────────

/// Python-facing wrapper for [`synta_certificate::ESSSecurityLabelBuilder`].
///
/// Builds a DER-encoded ``ESSSecurityLabel`` SET (RFC 2634 §3.2).
///
/// An ``ESSSecurityLabel`` is a CMS signed attribute carrying an information
/// security label.  The ``security_policy`` OID is required; all other fields
/// are optional.
///
/// Example::
///
///     import synta
///
///     # Custom policy OID (1.3.6.1.5.5.7.13.1 is a test OID)
///     policy_oid = [1, 3, 6, 1, 5, 5, 7, 13, 1]
///
///     label_der = (
///         synta.ESSSecurityLabelBuilder()
///         .security_policy(policy_oid)
///         .classification(3)       # CONFIDENTIAL
///         .privacy_mark_utf8("CONFIDENTIAL")
///         .build()
///     )
#[pyclass(name = "ESSSecurityLabelBuilder")]
pub struct PyESSSecurityLabelBuilder {
    inner: synta_certificate::ESSSecurityLabelBuilder,
    built: bool,
}

#[pymethods]
impl PyESSSecurityLabelBuilder {
    /// Create a new, empty ``ESSSecurityLabelBuilder``.
    #[new]
    fn new() -> Self {
        Self {
            inner: synta_certificate::ESSSecurityLabelBuilder::new(),
            built: false,
        }
    }

    /// Set the ``securityPolicyIdentifier`` OID.
    ///
    /// This field is required.
    ///
    /// :param policy_oid: OID arc components as a list of ints.
    /// :raises ValueError: if the OID is invalid (deferred to :meth:`build`).
    fn security_policy<'py>(slf: Bound<'py, Self>, policy_oid: Vec<u32>) -> Bound<'py, Self> {
        {
            let mut guard = slf.borrow_mut();
            let old = std::mem::replace(
                &mut guard.inner,
                synta_certificate::ESSSecurityLabelBuilder::new(),
            );
            guard.inner = old.security_policy(&policy_oid);
        }
        slf
    }

    /// Set the optional ``securityClassification`` value.
    ///
    /// Standard RFC 2634 §3.2 values: 0=UNMARKED, 1=UNCLASSIFIED,
    /// 2=RESTRICTED, 3=CONFIDENTIAL, 4=SECRET, 5=TOP_SECRET.
    ///
    /// :param value: classification integer (0–32767).
    /// :raises ValueError: if ``value`` exceeds 32767 (deferred to :meth:`build`).
    fn classification<'py>(slf: Bound<'py, Self>, value: u16) -> Bound<'py, Self> {
        {
            let mut guard = slf.borrow_mut();
            let old = std::mem::replace(
                &mut guard.inner,
                synta_certificate::ESSSecurityLabelBuilder::new(),
            );
            guard.inner = old.classification(value);
        }
        slf
    }

    /// Set the optional ``privacyMark`` as a UTF8String.
    ///
    /// :param mark: the privacy mark text string.
    fn privacy_mark_utf8<'py>(slf: Bound<'py, Self>, mark: &str) -> Bound<'py, Self> {
        {
            let mut guard = slf.borrow_mut();
            let old = std::mem::replace(
                &mut guard.inner,
                synta_certificate::ESSSecurityLabelBuilder::new(),
            );
            guard.inner = old.privacy_mark_utf8(mark);
        }
        slf
    }

    /// Set the optional ``privacyMark`` as a PrintableString.
    ///
    /// :param mark: the privacy mark text string (ASCII printable characters only).
    /// :raises ValueError: if ``mark`` contains characters not allowed in
    ///     PrintableString (deferred to :meth:`build`).
    fn privacy_mark_printable<'py>(slf: Bound<'py, Self>, mark: &str) -> Bound<'py, Self> {
        {
            let mut guard = slf.borrow_mut();
            let old = std::mem::replace(
                &mut guard.inner,
                synta_certificate::ESSSecurityLabelBuilder::new(),
            );
            guard.inner = old.privacy_mark_printable(mark);
        }
        slf
    }

    /// Add a pre-encoded ``SecurityCategory`` DER TLV to the security categories field.
    ///
    /// Each call appends one ``SecurityCategory`` to the ``securityCategories``
    /// ``SET OF SecurityCategory`` field (RFC 2634 §3.2).
    ///
    /// :param security_category_der: DER-encoded ``SecurityCategory`` SEQUENCE TLV.
    fn add_security_category_raw<'py>(
        slf: Bound<'py, Self>,
        security_category_der: &[u8],
    ) -> Bound<'py, Self> {
        {
            let mut guard = slf.borrow_mut();
            let old = std::mem::replace(
                &mut guard.inner,
                synta_certificate::ESSSecurityLabelBuilder::new(),
            );
            guard.inner = old.add_security_category_raw(security_category_der);
        }
        slf
    }

    /// Build the DER-encoded ``ESSSecurityLabel`` SET.
    ///
    /// :returns: DER bytes of the ``ESSSecurityLabel``.
    /// :raises ValueError: if ``security_policy`` was not set, DER encoding
    ///     fails, or if called more than once.
    fn build<'py>(&mut self, py: Python<'py>) -> PyResult<Bound<'py, PyBytes>> {
        if self.built {
            return Err(pyo3::exceptions::PyValueError::new_err(
                "build() has already been called; create a new builder",
            ));
        }
        self.built = true;
        let inner = std::mem::replace(
            &mut self.inner,
            synta_certificate::ESSSecurityLabelBuilder::new(),
        );
        let der = inner
            .build()
            .map_err(pyo3::exceptions::PyValueError::new_err)?;
        Ok(PyBytes::new(py, &der))
    }

    fn __repr__(&self) -> String {
        "ESSSecurityLabelBuilder()".to_string()
    }
}

// ── register ──────────────────────────────────────────────────────────────────

/// Register ESS builder classes into the given module.
pub(super) fn register_ess_classes(m: &Bound<'_, PyModule>) -> PyResult<()> {
    m.add_class::<PySigningCertificateBuilder>()?;
    m.add_class::<PyReceiptRequestBuilder>()?;
    m.add_class::<PyESSSecurityLabelBuilder>()?;
    Ok(())
}