_synta/

ext_builders.rs

//! Python bindings for X.509 extension DER value builders.
//!
//! Registers the ``synta.ext`` submodule with low-level DER-encoding helpers
//! for the most common X.509 v3 extension values.  Each function returns the
//! raw DER bytes of the extension's ``extnValue`` — the content inside the
//! OCTET STRING wrapper.
//!
//! ## Key identifier method constants
//!
//! Pass these to ``subject_key_identifier`` and ``authority_key_identifier``
//! as the ``method`` argument:
//!
//! | Constant | Value | Specification |
//! |----------|-------|---------------|
//! | `KEYID_RFC5280` | 0 | SHA-1 of BIT STRING value of subjectPublicKey (RFC 5280 §4.2.1.2) |
//! | `KEYID_RFC7093M1` | 1 | SHA-256 of BIT STRING value, truncated to 160 bits (RFC 7093 §2 m1) |
//! | `KEYID_RFC7093M2` | 2 | SHA-384 of BIT STRING value, truncated to 160 bits (RFC 7093 §2 m2) |
//! | `KEYID_RFC7093M3` | 3 | SHA-512 of BIT STRING value, truncated to 160 bits (RFC 7093 §2 m3) |
//! | `KEYID_RFC7093M4` | 4 | SHA-256 of full SubjectPublicKeyInfo DER (RFC 7093 §2 m4) |
//!
//! ## Key usage bitmask constants
//!
//! ``KU_*`` constants are ready-to-OR bitmasks for ``key_usage``:
//!
//! | Constant | Mask | Named bit (RFC 5280 §4.2.1.3) |
//! |----------|------|-------------------------------|
//! | `KU_DIGITAL_SIGNATURE` | 0x001 | `digitalSignature` |
//! | `KU_NON_REPUDIATION` | 0x002 | `contentCommitment` |
//! | `KU_KEY_ENCIPHERMENT` | 0x004 | `keyEncipherment` |
//! | `KU_DATA_ENCIPHERMENT` | 0x008 | `dataEncipherment` |
//! | `KU_KEY_AGREEMENT` | 0x010 | `keyAgreement` |
//! | `KU_KEY_CERT_SIGN` | 0x020 | `keyCertSign` |
//! | `KU_CRL_SIGN` | 0x040 | `cRLSign` |
//! | `KU_ENCIPHER_ONLY` | 0x080 | `encipherOnly` |
//! | `KU_DECIPHER_ONLY` | 0x100 | `decipherOnly` |
//!
//! ## Fluent builder classes
//!
//! Three builder classes accumulate entries and produce DER on ``.build()``:
//!
//! | Class | Short alias | Extension | OID |
//! |-------|-------------|-----------|-----|
//! | ``SubjectAlternativeNameBuilder`` | ``SAN`` | Subject Alternative Name | 2.5.29.17 |
//! | ``AuthorityInformationAccessBuilder`` | ``AIA`` | Authority Information Access | 1.3.6.1.5.5.7.1.1 |
//! | ``ExtendedKeyUsageBuilder`` | ``EKU`` | Extended Key Usage | 2.5.29.37 |

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

use synta_certificate::{
    default_key_id_hasher, encode_authority_key_identifier, encode_basic_constraints,
    encode_key_usage, encode_subject_key_identifier, AuthorityInformationAccessBuilder,
    ExtendedKeyUsageBuilder, KeyIdMethod, SubjectAlternativeNameBuilder,
};

// ── Key identifier method constants ──────────────────────────────────────────

/// RFC 5280 §4.2.1.2: SHA-1 of the BIT STRING value of ``subjectPublicKey``.
pub const KEYID_RFC5280: u8 = 0;

/// RFC 7093 §2 method 1: SHA-256 of BIT STRING value, truncated to 160 bits.
pub const KEYID_RFC7093M1: u8 = 1;

/// RFC 7093 §2 method 2: SHA-384 of BIT STRING value, truncated to 160 bits.
pub const KEYID_RFC7093M2: u8 = 2;

/// RFC 7093 §2 method 3: SHA-512 of BIT STRING value, truncated to 160 bits.
pub const KEYID_RFC7093M3: u8 = 3;

/// RFC 7093 §2 method 4: SHA-256 of the full ``SubjectPublicKeyInfo`` DER encoding.
pub const KEYID_RFC7093M4: u8 = 4;

// ── Key usage bitmask constants ───────────────────────────────────────────────

/// ``digitalSignature`` (bit 0) — RFC 5280 §4.2.1.3.
pub const KU_DIGITAL_SIGNATURE: u16 = 1 << 0;
/// ``contentCommitment`` / ``nonRepudiation`` (bit 1) — RFC 5280 §4.2.1.3.
pub const KU_NON_REPUDIATION: u16 = 1 << 1;
/// ``keyEncipherment`` (bit 2) — RFC 5280 §4.2.1.3.
pub const KU_KEY_ENCIPHERMENT: u16 = 1 << 2;
/// ``dataEncipherment`` (bit 3) — RFC 5280 §4.2.1.3.
pub const KU_DATA_ENCIPHERMENT: u16 = 1 << 3;
/// ``keyAgreement`` (bit 4) — RFC 5280 §4.2.1.3.
pub const KU_KEY_AGREEMENT: u16 = 1 << 4;
/// ``keyCertSign`` (bit 5) — RFC 5280 §4.2.1.3.
pub const KU_KEY_CERT_SIGN: u16 = 1 << 5;
/// ``cRLSign`` (bit 6) — RFC 5280 §4.2.1.3.
pub const KU_CRL_SIGN: u16 = 1 << 6;
/// ``encipherOnly`` (bit 7) — RFC 5280 §4.2.1.3; only meaningful when keyAgreement is set.
pub const KU_ENCIPHER_ONLY: u16 = 1 << 7;
/// ``decipherOnly`` (bit 8) — RFC 5280 §4.2.1.3; only meaningful when keyAgreement is set.
pub const KU_DECIPHER_ONLY: u16 = 1 << 8;

// ── Internal helper ───────────────────────────────────────────────────────────

fn method_from_int(m: u8) -> PyResult<KeyIdMethod> {
    match m {
        KEYID_RFC5280 => Ok(KeyIdMethod::Rfc5280Sha1),
        KEYID_RFC7093M1 => Ok(KeyIdMethod::Rfc7093Method1Sha256),
        KEYID_RFC7093M2 => Ok(KeyIdMethod::Rfc7093Method2Sha384),
        KEYID_RFC7093M3 => Ok(KeyIdMethod::Rfc7093Method3Sha512),
        KEYID_RFC7093M4 => Ok(KeyIdMethod::Rfc7093Method4 {
            algorithm_oid: synta_certificate::ID_SHA256.to_vec(),
        }),
        other => Err(PyValueError::new_err(format!(
            "unknown key identifier method {other}: \
             use KEYID_RFC5280, KEYID_RFC7093M1, KEYID_RFC7093M2, \
             KEYID_RFC7093M3, or KEYID_RFC7093M4"
        ))),
    }
}

// ── Python functions ──────────────────────────────────────────────────────────

/// Encode a ``BasicConstraints`` extension value (OID 2.5.29.19).
///
/// Returns the DER bytes of the ``BasicConstraints`` SEQUENCE for use as the
/// extension ``extnValue`` (inside the OCTET STRING wrapper):
///
/// ```text
/// BasicConstraints ::= SEQUENCE {
///     cA                  BOOLEAN DEFAULT FALSE,
///     pathLenConstraint   INTEGER (0..MAX) OPTIONAL }
/// ```
///
/// When ``ca`` is ``False`` the ``cA`` field is omitted (DER DEFAULT-FALSE
/// rule).  ``path_length`` is silently ignored when ``ca`` is ``False``.
///
/// ```python,ignore
/// import synta.ext as ext
///
/// # End-entity certificate: empty SEQUENCE (30 00)
/// ee_bc = ext.basic_constraints()
/// assert ee_bc == bytes([0x30, 0x00])
///
/// # CA with no path-length constraint (30 03 01 01 ff)
/// ca_bc = ext.basic_constraints(ca=True)
///
/// # CA with pathLen = 0 (30 06 01 01 ff 02 01 00)
/// ca_pl0 = ext.basic_constraints(ca=True, path_length=0)
/// ```
#[pyfunction]
#[pyo3(signature = (ca = false, path_length = None))]
fn basic_constraints<'py>(
    py: Python<'py>,
    ca: bool,
    path_length: Option<u64>,
) -> PyResult<Bound<'py, PyBytes>> {
    let der = encode_basic_constraints(ca, path_length)
        .ok_or_else(|| PyValueError::new_err("BasicConstraints DER encoding failed"))?;
    Ok(PyBytes::new(py, &der))
}

/// Encode a ``KeyUsage`` extension value (OID 2.5.29.15).
///
/// ``bits`` is an integer bitmask formed by OR-ing the ``KU_*`` constants
/// exported from this module.  Returns the DER BIT STRING value.
///
/// ```python,ignore
/// import synta.ext as ext
///
/// # digitalSignature only → 03 02 07 80
/// ku = ext.key_usage(ext.KU_DIGITAL_SIGNATURE)
///
/// # keyCertSign | cRLSign → 03 02 01 06
/// ku = ext.key_usage(ext.KU_KEY_CERT_SIGN | ext.KU_CRL_SIGN)
///
/// # Typical CA key usage
/// ku = ext.key_usage(
///     ext.KU_KEY_CERT_SIGN | ext.KU_CRL_SIGN | ext.KU_DIGITAL_SIGNATURE
/// )
/// ```
#[pyfunction]
fn key_usage<'py>(py: Python<'py>, bits: u16) -> PyResult<Bound<'py, PyBytes>> {
    let der = encode_key_usage(bits)
        .ok_or_else(|| PyValueError::new_err("KeyUsage DER encoding failed"))?;
    Ok(PyBytes::new(py, &der))
}

/// Encode a ``SubjectKeyIdentifier`` extension value (OID 2.5.29.14).
///
/// Decodes ``spki_der`` as a DER ``SubjectPublicKeyInfo`` and computes the
/// key identifier according to ``method`` (one of the ``KEYID_*`` constants
/// from this module).
///
/// Methods other than ``KEYID_RFC7093M4`` hash the BIT STRING value of
/// ``subjectPublicKey`` (the key bytes, without the unused-bits octet).
/// ``KEYID_RFC7093M4`` hashes the full ``SubjectPublicKeyInfo`` DER encoding.
///
/// Returns the DER OCTET STRING value, or raises :exc:`ValueError` if
/// ``spki_der`` cannot be decoded or if hashing fails.
///
/// ```python,ignore
/// import synta.ext as ext
///
/// # RFC 5280 default (SHA-1 of subjectPublicKey BIT STRING value)
/// ski_der = ext.subject_key_identifier(cert.subject_public_key_info_raw_der)
///
/// # RFC 7093 method 1 (SHA-256 of BIT STRING value, truncated to 160 bits)
/// ski_der = ext.subject_key_identifier(
///     cert.subject_public_key_info_raw_der,
///     method=ext.KEYID_RFC7093M1,
/// )
/// ```
#[pyfunction]
#[pyo3(signature = (spki_der, method = KEYID_RFC5280))]
fn subject_key_identifier<'py>(
    py: Python<'py>,
    spki_der: &[u8],
    method: u8,
) -> PyResult<Bound<'py, PyBytes>> {
    let m = method_from_int(method)?;
    encode_subject_key_identifier(spki_der, m, &default_key_id_hasher())
        .map(|v| PyBytes::new(py, &v))
        .ok_or_else(|| {
            PyValueError::new_err(
                "failed to encode SubjectKeyIdentifier: \
                 invalid SubjectPublicKeyInfo DER or hash error",
            )
        })
}

/// Encode an ``AuthorityKeyIdentifier`` extension value (OID 2.5.29.35).
///
/// Computes the key identifier from the issuer's ``SubjectPublicKeyInfo``
/// using the same input selection and hash rules as
/// :func:`subject_key_identifier`.  Sets only the ``keyIdentifier [0]``
/// field; ``authorityCertIssuer`` and ``authorityCertSerialNumber`` are not
/// included.
///
/// Returns the DER bytes of the ``AuthorityKeyIdentifier`` SEQUENCE, or
/// raises :exc:`ValueError` on error.
///
/// ```python,ignore
/// import synta.ext as ext
///
/// # RFC 5280 default (SHA-1 of issuer subjectPublicKey BIT STRING value)
/// aki_der = ext.authority_key_identifier(ca_cert.subject_public_key_info_raw_der)
///
/// # RFC 7093 method 1 (SHA-256 of BIT STRING value, truncated to 160 bits)
/// aki_der = ext.authority_key_identifier(
///     ca_cert.subject_public_key_info_raw_der,
///     method=ext.KEYID_RFC7093M1,
/// )
/// ```
#[pyfunction]
#[pyo3(signature = (issuer_spki_der, method = KEYID_RFC5280))]
fn authority_key_identifier<'py>(
    py: Python<'py>,
    issuer_spki_der: &[u8],
    method: u8,
) -> PyResult<Bound<'py, PyBytes>> {
    let m = method_from_int(method)?;
    encode_authority_key_identifier(issuer_spki_der, m, &default_key_id_hasher())
        .map(|v| PyBytes::new(py, &v))
        .ok_or_else(|| {
            PyValueError::new_err(
                "failed to encode AuthorityKeyIdentifier: \
                 invalid SubjectPublicKeyInfo DER or hash error",
            )
        })
}

// ── SubjectAlternativeNameBuilder ─────────────────────────────────────────────

/// Fluent builder for a ``SubjectAltName`` extension value (OID 2.5.29.17).
///
/// Accumulate :class:`GeneralName` entries with the fluent methods, then call
/// :meth:`build` to obtain the DER bytes of the ``GeneralNames`` SEQUENCE —
/// the content that goes inside the OCTET STRING wrapper in the ``Extension``
/// SEQUENCE.
///
/// The class is also available as the short alias ``synta.ext.SAN``.
///
/// ```python,ignore
/// import synta.ext as ext
///
/// san = ext.SAN() \
///     .dns_name("www.example.com") \
///     .dns_name("example.com") \
///     .rfc822_name("admin@example.com") \
///     .ip_address(b"\xc0\xa8\x01\x01") \
///     .build()
/// ```
#[pyclass(name = "SubjectAlternativeNameBuilder")]
pub struct PySubjectAlternativeNameBuilder {
    inner: SubjectAlternativeNameBuilder,
    built: bool,
}

#[pymethods]
impl PySubjectAlternativeNameBuilder {
    #[new]
    fn new() -> Self {
        Self {
            inner: SubjectAlternativeNameBuilder::new(),
            built: false,
        }
    }

    /// Add a ``dNSName [2]`` GeneralName.
    fn dns_name<'py>(slf: Bound<'py, Self>, name: &str) -> Bound<'py, Self> {
        let old = std::mem::replace(
            &mut slf.borrow_mut().inner,
            SubjectAlternativeNameBuilder::new(),
        );
        slf.borrow_mut().inner = old.dns_name(name);
        slf
    }

    /// Add an ``rfc822Name [1]`` GeneralName (email address).
    fn rfc822_name<'py>(slf: Bound<'py, Self>, email: &str) -> Bound<'py, Self> {
        let old = std::mem::replace(
            &mut slf.borrow_mut().inner,
            SubjectAlternativeNameBuilder::new(),
        );
        slf.borrow_mut().inner = old.rfc822_name(email);
        slf
    }

    /// Add a ``uniformResourceIdentifier [6]`` GeneralName (URI).
    fn uri<'py>(slf: Bound<'py, Self>, uri: &str) -> Bound<'py, Self> {
        let old = std::mem::replace(
            &mut slf.borrow_mut().inner,
            SubjectAlternativeNameBuilder::new(),
        );
        slf.borrow_mut().inner = old.uri(uri);
        slf
    }

    /// Add an ``iPAddress [7]`` GeneralName.
    ///
    /// Pass 4 bytes for IPv4 or 16 bytes for IPv6.
    fn ip_address<'py>(slf: Bound<'py, Self>, addr: &[u8]) -> Bound<'py, Self> {
        let old = std::mem::replace(
            &mut slf.borrow_mut().inner,
            SubjectAlternativeNameBuilder::new(),
        );
        slf.borrow_mut().inner = old.ip_address(addr);
        slf
    }

    /// Add a ``directoryName [4]`` GeneralName (EXPLICIT wrapper).
    ///
    /// ``name_der`` is the complete DER TLV bytes of the ``Name`` SEQUENCE
    /// (e.g. from :meth:`synta.NameBuilder.build`).  Silently ignored if
    /// ``name_der`` cannot be decoded.
    fn directory_name<'py>(slf: Bound<'py, Self>, name_der: &[u8]) -> Bound<'py, Self> {
        let old = std::mem::replace(
            &mut slf.borrow_mut().inner,
            SubjectAlternativeNameBuilder::new(),
        );
        slf.borrow_mut().inner = old.directory_name(name_der);
        slf
    }

    /// Build the DER-encoded ``GeneralNames`` SEQUENCE.
    ///
    /// Returns ``bytes``.  Returns ``b'\\x30\\x00'`` (empty SEQUENCE) if no
    /// entries have been added.  Raises :exc:`ValueError` if any entry failed
    /// DER encoding or if ``build()`` is called more than once on the same
    /// builder instance.
    fn build<'py>(&mut self, py: Python<'py>) -> PyResult<Bound<'py, PyBytes>> {
        if self.built {
            return Err(PyValueError::new_err(
                "SubjectAlternativeNameBuilder.build() has already been called; \
                 create a new builder instance",
            ));
        }
        self.built = true;
        let builder = std::mem::replace(&mut self.inner, SubjectAlternativeNameBuilder::new());
        let der = builder.build().map_err(PyValueError::new_err)?;
        Ok(PyBytes::new(py, &der))
    }
}

// ── AuthorityInformationAccessBuilder ─────────────────────────────────────────

/// Fluent builder for an ``AuthorityInfoAccessSyntax`` extension value
/// (OID 1.3.6.1.5.5.7.1.1, Authority Information Access, RFC 5280 §4.2.2.1).
///
/// Add OCSP and/or CA Issuers URIs with the fluent methods, then call
/// :meth:`build` to obtain the DER bytes of the ``AuthorityInfoAccessSyntax``
/// SEQUENCE — the content that goes inside the OCTET STRING wrapper.
///
/// The class is also available as the short alias ``synta.ext.AIA``.
///
/// ```python,ignore
/// import synta.ext as ext
///
/// aia = ext.AIA() \
///     .ocsp("http://ocsp.example.com") \
///     .ca_issuers("http://ca.example.com/ca.crt") \
///     .build()
/// ```
#[pyclass(name = "AuthorityInformationAccessBuilder")]
pub struct PyAuthorityInformationAccessBuilder {
    inner: AuthorityInformationAccessBuilder,
    built: bool,
}

#[pymethods]
impl PyAuthorityInformationAccessBuilder {
    #[new]
    fn new() -> Self {
        Self {
            inner: AuthorityInformationAccessBuilder::new(),
            built: false,
        }
    }

    /// Add an OCSP responder URI (``id-ad-ocsp``, 1.3.6.1.5.5.7.48.1).
    fn ocsp<'py>(slf: Bound<'py, Self>, uri: &str) -> Bound<'py, Self> {
        let old = std::mem::replace(
            &mut slf.borrow_mut().inner,
            AuthorityInformationAccessBuilder::new(),
        );
        slf.borrow_mut().inner = old.ocsp(uri);
        slf
    }

    /// Add a CA Issuers URI (``id-ad-caIssuers``, 1.3.6.1.5.5.7.48.2).
    fn ca_issuers<'py>(slf: Bound<'py, Self>, uri: &str) -> Bound<'py, Self> {
        let old = std::mem::replace(
            &mut slf.borrow_mut().inner,
            AuthorityInformationAccessBuilder::new(),
        );
        slf.borrow_mut().inner = old.ca_issuers(uri);
        slf
    }

    /// Build the DER-encoded ``AuthorityInfoAccessSyntax`` SEQUENCE.
    ///
    /// Returns ``bytes``.  Returns ``b'\\x30\\x00'`` (empty SEQUENCE) if no
    /// entries have been added.  Raises :exc:`ValueError` if any entry failed
    /// DER encoding or if ``build()`` is called more than once on the same
    /// builder instance.
    fn build<'py>(&mut self, py: Python<'py>) -> PyResult<Bound<'py, PyBytes>> {
        if self.built {
            return Err(PyValueError::new_err(
                "AuthorityInformationAccessBuilder.build() has already been called; \
                 create a new builder instance",
            ));
        }
        self.built = true;
        let builder = std::mem::replace(&mut self.inner, AuthorityInformationAccessBuilder::new());
        let der = builder.build().map_err(PyValueError::new_err)?;
        Ok(PyBytes::new(py, &der))
    }
}

// ── ExtendedKeyUsageBuilder ───────────────────────────────────────────────────

/// Fluent builder for an ``ExtKeyUsageSyntax`` extension value
/// (OID 2.5.29.37, Extended Key Usage, RFC 5280 §4.2.1.12).
///
/// Add well-known key purpose OIDs with the convenience methods or custom OIDs
/// via :meth:`add_oid`, then call :meth:`build` to obtain the DER bytes of the
/// ``ExtKeyUsageSyntax`` SEQUENCE.
///
/// The class is also available as the short alias ``synta.ext.EKU``.
///
/// ```python,ignore
/// import synta.ext as ext
///
/// # Typical TLS server certificate EKU
/// eku = ext.EKU().server_auth().client_auth().build()
///
/// # Custom OID
/// eku = ext.EKU().add_oid([1, 3, 6, 1, 5, 5, 7, 3, 1]).build()
/// ```
#[pyclass(name = "ExtendedKeyUsageBuilder")]
pub struct PyExtendedKeyUsageBuilder {
    inner: ExtendedKeyUsageBuilder,
    built: bool,
}

#[pymethods]
impl PyExtendedKeyUsageBuilder {
    #[new]
    fn new() -> Self {
        Self {
            inner: ExtendedKeyUsageBuilder::new(),
            built: false,
        }
    }

    /// Add ``id-kp-serverAuth`` (1.3.6.1.5.5.7.3.1).
    fn server_auth<'py>(slf: Bound<'py, Self>) -> Bound<'py, Self> {
        let old = std::mem::replace(&mut slf.borrow_mut().inner, ExtendedKeyUsageBuilder::new());
        slf.borrow_mut().inner = old.server_auth();
        slf
    }

    /// Add ``id-kp-clientAuth`` (1.3.6.1.5.5.7.3.2).
    fn client_auth<'py>(slf: Bound<'py, Self>) -> Bound<'py, Self> {
        let old = std::mem::replace(&mut slf.borrow_mut().inner, ExtendedKeyUsageBuilder::new());
        slf.borrow_mut().inner = old.client_auth();
        slf
    }

    /// Add ``id-kp-codeSigning`` (1.3.6.1.5.5.7.3.3).
    fn code_signing<'py>(slf: Bound<'py, Self>) -> Bound<'py, Self> {
        let old = std::mem::replace(&mut slf.borrow_mut().inner, ExtendedKeyUsageBuilder::new());
        slf.borrow_mut().inner = old.code_signing();
        slf
    }

    /// Add ``id-kp-emailProtection`` (1.3.6.1.5.5.7.3.4).
    fn email_protection<'py>(slf: Bound<'py, Self>) -> Bound<'py, Self> {
        let old = std::mem::replace(&mut slf.borrow_mut().inner, ExtendedKeyUsageBuilder::new());
        slf.borrow_mut().inner = old.email_protection();
        slf
    }

    /// Add ``id-kp-timeStamping`` (1.3.6.1.5.5.7.3.8).
    fn time_stamping<'py>(slf: Bound<'py, Self>) -> Bound<'py, Self> {
        let old = std::mem::replace(&mut slf.borrow_mut().inner, ExtendedKeyUsageBuilder::new());
        slf.borrow_mut().inner = old.time_stamping();
        slf
    }

    /// Add ``id-kp-OCSPSigning`` (1.3.6.1.5.5.7.3.9).
    fn ocsp_signing<'py>(slf: Bound<'py, Self>) -> Bound<'py, Self> {
        let old = std::mem::replace(&mut slf.borrow_mut().inner, ExtendedKeyUsageBuilder::new());
        slf.borrow_mut().inner = old.ocsp_signing();
        slf
    }

    /// Add a custom key purpose OID by component list.
    ///
    /// ``comps`` is a list of integers forming the OID arc, e.g.
    /// ``[1, 3, 6, 1, 5, 5, 7, 3, 1]`` for ``id-kp-serverAuth``.
    fn add_oid<'py>(slf: Bound<'py, Self>, comps: Vec<u32>) -> Bound<'py, Self> {
        let old = std::mem::replace(&mut slf.borrow_mut().inner, ExtendedKeyUsageBuilder::new());
        slf.borrow_mut().inner = old.add_oid(&comps);
        slf
    }

    /// Build the DER-encoded ``ExtKeyUsageSyntax`` SEQUENCE.
    ///
    /// Returns ``bytes``.  Returns ``b'\\x30\\x00'`` (empty SEQUENCE) if no
    /// OIDs have been added.  Raises :exc:`ValueError` if any OID was invalid
    /// or if ``build()`` is called more than once on the same builder instance.
    fn build<'py>(&mut self, py: Python<'py>) -> PyResult<Bound<'py, PyBytes>> {
        if self.built {
            return Err(PyValueError::new_err(
                "ExtendedKeyUsageBuilder.build() has already been called; \
                 create a new builder instance",
            ));
        }
        self.built = true;
        let builder = std::mem::replace(&mut self.inner, ExtendedKeyUsageBuilder::new());
        let der = builder.build().map_err(PyValueError::new_err)?;
        Ok(PyBytes::new(py, &der))
    }
}

// ── Module registration ───────────────────────────────────────────────────────

/// Register the ``synta.ext`` submodule.
///
/// Exposes DER builders for common X.509 v3 extension values together with
/// ``KEYID_*`` key-identifier method constants (RFC 5280 / RFC 7093) and
/// ``KU_*`` key-usage bitmask constants (RFC 5280 §4.2.1.3).
pub fn register_ext_module(parent: &Bound<'_, PyModule>) -> PyResult<()> {
    let py = parent.py();
    let m = PyModule::new(py, "ext")?;

    // Key identifier method constants (RFC 5280 / RFC 7093)
    m.add("KEYID_RFC5280", KEYID_RFC5280)?;
    m.add("KEYID_RFC7093M1", KEYID_RFC7093M1)?;
    m.add("KEYID_RFC7093M2", KEYID_RFC7093M2)?;
    m.add("KEYID_RFC7093M3", KEYID_RFC7093M3)?;
    m.add("KEYID_RFC7093M4", KEYID_RFC7093M4)?;

    // Key usage bitmask constants — OR these together and pass to key_usage()
    m.add("KU_DIGITAL_SIGNATURE", KU_DIGITAL_SIGNATURE)?;
    m.add("KU_NON_REPUDIATION", KU_NON_REPUDIATION)?;
    m.add("KU_KEY_ENCIPHERMENT", KU_KEY_ENCIPHERMENT)?;
    m.add("KU_DATA_ENCIPHERMENT", KU_DATA_ENCIPHERMENT)?;
    m.add("KU_KEY_AGREEMENT", KU_KEY_AGREEMENT)?;
    m.add("KU_KEY_CERT_SIGN", KU_KEY_CERT_SIGN)?;
    m.add("KU_CRL_SIGN", KU_CRL_SIGN)?;
    m.add("KU_ENCIPHER_ONLY", KU_ENCIPHER_ONLY)?;
    m.add("KU_DECIPHER_ONLY", KU_DECIPHER_ONLY)?;

    // Extension builder functions
    m.add_function(wrap_pyfunction!(basic_constraints, &m)?)?;
    m.add_function(wrap_pyfunction!(key_usage, &m)?)?;
    m.add_function(wrap_pyfunction!(subject_key_identifier, &m)?)?;
    m.add_function(wrap_pyfunction!(authority_key_identifier, &m)?)?;

    // Fluent builder classes
    m.add_class::<PySubjectAlternativeNameBuilder>()?;
    m.add_class::<PyAuthorityInformationAccessBuilder>()?;
    m.add_class::<PyExtendedKeyUsageBuilder>()?;

    // Short aliases for the builder classes
    m.add("SAN", m.getattr("SubjectAlternativeNameBuilder")?)?;
    m.add("AIA", m.getattr("AuthorityInformationAccessBuilder")?)?;
    m.add("EKU", m.getattr("ExtendedKeyUsageBuilder")?)?;

    crate::install_submodule(
        parent,
        &m,
        "synta.ext",
        Some(
            "X.509 v3 extension value DER builders: basic_constraints, key_usage, \
             subject_key_identifier, authority_key_identifier; \
             SubjectAlternativeNameBuilder (alias: SAN), \
             AuthorityInformationAccessBuilder (alias: AIA), \
             ExtendedKeyUsageBuilder (alias: EKU); \
             KEYID_* method constants (RFC 5280 §4.2.1.2 / RFC 7093); \
             KU_* key-usage bitmask constants (RFC 5280 §4.2.1.3).",
        ),
    )
}