kipuka/ca/

issue.rs

//! Certificate issuance from CSR with CA/B Forum compliance.
//!
//! Implements RFC 7030 §4.2 enrollment and applies profile-based
//! constraints. Validates CSR contents against CA/B Forum Baseline
//! Requirements before signing.
//!
//! Certificate signing uses the `synta-certificate` `CertificateBuilder`
//! with `OpensslCertificateSigner` for the actual cryptographic operations.

use std::sync::Arc;

use chrono::{DateTime, Utc};
use serde::{Deserialize, Serialize};
use thiserror::Error;
use tracing::{debug, info, warn};

/// Errors during certificate issuance.
#[derive(Debug, Error)]
pub enum IssuanceError {
    /// The CSR is malformed or cannot be parsed.
    #[error("invalid CSR: {0}")]
    InvalidCsr(String),

    /// The CSR key does not meet minimum size requirements.
    #[error("key too small: {algorithm} {bits}-bit (minimum {min_bits}-bit required)")]
    KeyTooSmall {
        algorithm: String,
        bits: u32,
        min_bits: u32,
    },

    /// The requested validity period exceeds the maximum.
    #[error("validity period {requested_days} days exceeds maximum {max_days} days")]
    ValidityTooLong { requested_days: u32, max_days: u32 },

    /// A required extension is missing from the profile.
    #[error("missing required extension: {0}")]
    MissingExtension(String),

    /// The enrollment profile does not exist.
    #[error("unknown enrollment profile: {0}")]
    UnknownProfile(String),

    /// CA signing operation failed.
    #[error("signing failed: {0}")]
    SigningError(String),

    /// Database storage error.
    #[error("storage error: {0}")]
    StorageError(String),

    /// The CSR algorithm is not permitted by the enrollment profile.
    #[error("algorithm not allowed: {algorithm} not in profile '{profile}'")]
    AlgorithmNotAllowed { algorithm: String, profile: String },

    /// The CSR subject contains a prohibited DN attribute.
    #[error("prohibited DN attribute: {name} ({oid})")]
    ProhibitedDnAttribute { oid: String, name: String },
}

impl IssuanceError {
    /// Whether this failure was caused by the *client's* request content
    /// (the CSR) rather than a server-side fault.
    ///
    /// This is the single source of truth for HTTP/CoAP status classification:
    /// client-content faults must surface as `4xx` (RFC 7030 §4.2.3 — the
    /// requester can fix the CSR and retry), while server/profile/signing
    /// faults must surface as `5xx` (the client cannot fix them, and internal
    /// detail must not leak).  A misclassification here would either blame the
    /// client for a server misconfiguration or hide a bad CSR behind a 500.
    ///
    /// Note the two profile-driven variants — [`MissingExtension`] and
    /// [`ValidityTooLong`] — are **server** errors: they originate from the
    /// server's [`EnrollmentProfile`] (`check_required_extensions`,
    /// `check_validity_period`), not from anything the client sent.
    ///
    /// [`MissingExtension`]: Self::MissingExtension
    /// [`ValidityTooLong`]: Self::ValidityTooLong
    pub fn is_client_error(&self) -> bool {
        match self {
            // Faults in the client-supplied CSR — the requester can fix and retry.
            Self::InvalidCsr(_)
            | Self::KeyTooSmall { .. }
            | Self::AlgorithmNotAllowed { .. }
            | Self::ProhibitedDnAttribute { .. } => true,
            // Server-side faults: signing, storage, and profile configuration.
            Self::SigningError(_)
            | Self::StorageError(_)
            | Self::MissingExtension(_)
            | Self::ValidityTooLong { .. }
            | Self::UnknownProfile(_) => false,
        }
    }
}

/// Result of a successful certificate issuance.
#[derive(Debug, Clone)]
pub struct IssuanceResult {
    /// DER-encoded issued certificate.
    pub certificate_der: Vec<u8>,
    /// Serial number (hex string).
    pub serial_number: String,
    /// Subject DN of the issued certificate.
    pub subject_dn: String,
    /// Not Before timestamp.
    pub not_before: DateTime<Utc>,
    /// Not After timestamp.
    pub not_after: DateTime<Utc>,
}

/// CA signing key — either a PEM key from disk or an HSM-backed key.
///
/// When `Hsm` is used, the private key never leaves the HSM; signing
/// is performed via PKCS#11 `C_Sign` operations.
pub enum CaSigningKey<'a> {
    /// PEM-encoded private key loaded from disk.
    Pem(&'a [u8]),
    /// HSM-backed private key accessed via PKCS#11.
    Hsm {
        /// Reference to the HSM context with an active session.
        context: &'a Arc<kipuka_hsm::HsmContext>,
        /// Object label of the private key in the PKCS#11 token.
        key_label: &'a str,
    },
}

/// Owned signing key — either PEM bytes from disk or an HSM context + label.
///
/// Unlike [`CaSigningKey`] (which borrows), this type owns all data,
/// making it easy to return from an async resolver without lifetime issues.
/// Call [`ResolvedSigningKey::as_signing_key`] to obtain a borrowed
/// [`CaSigningKey`] for passing to [`issue_certificate`].
pub enum ResolvedSigningKey {
    /// PEM-encoded private key loaded from disk.
    Pem(Vec<u8>),
    /// HSM-backed private key accessed via PKCS#11.
    Hsm {
        /// Shared HSM context with an active session.
        context: std::sync::Arc<kipuka_hsm::HsmContext>,
        /// Object label of the private key in the PKCS#11 token.
        key_label: String,
    },
}

impl ResolvedSigningKey {
    /// Borrow as a [`CaSigningKey`] suitable for [`issue_certificate`].
    pub fn as_signing_key(&self) -> CaSigningKey<'_> {
        match self {
            ResolvedSigningKey::Pem(pem) => CaSigningKey::Pem(pem),
            ResolvedSigningKey::Hsm { context, key_label } => {
                CaSigningKey::Hsm { context, key_label }
            }
        }
    }
}

/// Resolve the CA signing key from configuration (async — uses `tokio::fs::read`).
///
/// Returns a [`ResolvedSigningKey`] that owns all key material.  Use
/// [`ResolvedSigningKey::as_signing_key`] to obtain a borrowed reference
/// for [`issue_certificate`].
pub async fn resolve_signing_key(
    ca_cfg: &crate::config::CaConfig,
    hsm: Option<&std::sync::Arc<kipuka_hsm::HsmContext>>,
) -> Result<ResolvedSigningKey, crate::error::KipukaError> {
    if ca_cfg.is_hsm_backed() {
        let hsm_ctx = hsm.ok_or_else(|| {
            crate::error::KipukaError::Ca("HSM not configured but CA has pkcs11_uri".into())
        })?;
        let pkcs11_uri = ca_cfg.pkcs11_uri.as_deref().ok_or_else(|| {
            crate::error::KipukaError::Ca(
                "CA marked as HSM-backed but pkcs11_uri not configured".into(),
            )
        })?;
        let key_label = parse_pkcs11_object_label(pkcs11_uri)
            .map_err(|e| crate::error::KipukaError::Ca(format!("invalid pkcs11_uri: {e}")))?;
        Ok(ResolvedSigningKey::Hsm {
            context: std::sync::Arc::clone(hsm_ctx),
            key_label,
        })
    } else {
        let pem = tokio::fs::read(&ca_cfg.key_file).await.map_err(|e| {
            crate::error::KipukaError::Ca(format!("failed to read CA key {}: {e}", ca_cfg.key_file))
        })?;
        Ok(ResolvedSigningKey::Pem(pem))
    }
}

/// Resolve the CA signing key from configuration (sync — uses `std::fs::read`).
///
/// Identical to [`resolve_signing_key`] but suitable for non-async contexts
/// such as the STAR background renewal task.
pub fn resolve_signing_key_sync(
    ca_cfg: &crate::config::CaConfig,
    hsm: Option<&std::sync::Arc<kipuka_hsm::HsmContext>>,
) -> Result<ResolvedSigningKey, crate::error::KipukaError> {
    if ca_cfg.is_hsm_backed() {
        let hsm_ctx = hsm.ok_or_else(|| {
            crate::error::KipukaError::Ca("HSM not configured but CA has pkcs11_uri".into())
        })?;
        let pkcs11_uri = ca_cfg.pkcs11_uri.as_deref().ok_or_else(|| {
            crate::error::KipukaError::Ca(
                "CA marked as HSM-backed but pkcs11_uri not configured".into(),
            )
        })?;
        let key_label = parse_pkcs11_object_label(pkcs11_uri)
            .map_err(|e| crate::error::KipukaError::Ca(format!("invalid pkcs11_uri: {e}")))?;
        Ok(ResolvedSigningKey::Hsm {
            context: std::sync::Arc::clone(hsm_ctx),
            key_label,
        })
    } else {
        let pem = std::fs::read(&ca_cfg.key_file).map_err(|e| {
            crate::error::KipukaError::Ca(format!("failed to read CA key {}: {e}", ca_cfg.key_file))
        })?;
        Ok(ResolvedSigningKey::Pem(pem))
    }
}

/// Extract the `object` (key label) from a PKCS#11 URI.
///
/// PKCS#11 URI format: `pkcs11:token=TOKEN;object=KEY_LABEL;type=private`
///
/// Returns the value of the `object` attribute, which is the CKA_LABEL
/// used to find the private key in the PKCS#11 token.
///
/// Per RFC 7512 §2.3, values may be percent-encoded; this function
/// decodes `%XX` sequences.
pub(crate) fn parse_pkcs11_object_label(uri: &str) -> Result<String, String> {
    let path = uri
        .strip_prefix("pkcs11:")
        .ok_or_else(|| format!("not a pkcs11: URI: {uri}"))?;

    for part in path.split(';') {
        if let Some((key, value)) = part.split_once('=')
            && key == "object"
        {
            return pkcs11_percent_decode(value);
        }
    }

    Err(format!("pkcs11 URI missing 'object' attribute: {uri}"))
}

/// Percent-decode a PKCS#11 URI value per RFC 7512 §2.3.
fn pkcs11_percent_decode(s: &str) -> Result<String, String> {
    let mut result = Vec::with_capacity(s.len());
    let bytes = s.as_bytes();
    let mut i = 0;
    while i < bytes.len() {
        if bytes[i] == b'%' && i + 2 < bytes.len() {
            let hi = hex_digit(bytes[i + 1])
                .ok_or_else(|| format!("invalid percent-encoding at position {i}"))?;
            let lo = hex_digit(bytes[i + 2])
                .ok_or_else(|| format!("invalid percent-encoding at position {}", i + 1))?;
            result.push((hi << 4) | lo);
            i += 3;
        } else {
            result.push(bytes[i]);
            i += 1;
        }
    }
    String::from_utf8(result).map_err(|e| format!("invalid UTF-8 after percent-decoding: {e}"))
}

fn hex_digit(b: u8) -> Option<u8> {
    match b {
        b'0'..=b'9' => Some(b - b'0'),
        b'a'..=b'f' => Some(b - b'a' + 10),
        b'A'..=b'F' => Some(b - b'A' + 10),
        _ => None,
    }
}

/// Enrollment profile defining constraints for issued certificates.
///
/// Supports classical (RSA, ECDSA), post-quantum (ML-DSA, ML-KEM),
/// and composite hybrid algorithms for PQC migration scenarios.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct EnrollmentProfile {
    /// Profile name (referenced in OTP records and EST label config).
    pub name: String,
    /// Maximum validity period in days.
    pub max_validity_days: u32,
    /// Optional shorter validity for automatic renewal.
    #[serde(default)]
    pub max_validity_seconds: Option<u64>,
    /// Absolute issuance deadline (for renewal order lifetime).
    #[serde(default)]
    pub max_not_after: Option<DateTime<Utc>>,
    /// Key usage flags to set (e.g., digitalSignature, keyEncipherment).
    pub key_usage: Vec<String>,
    /// Extended key usage OIDs (e.g., serverAuth, clientAuth).
    pub extended_key_usage: Vec<String>,
    /// Whether to include Subject Key Identifier.
    pub include_ski: bool,
    /// Whether to include Authority Key Identifier.
    pub include_aki: bool,
    /// Minimum RSA key size in bits.
    pub min_rsa_bits: u32,
    /// Minimum ECDSA curve (P-256, P-384).
    pub min_ecdsa_curve: String,
    /// Whether to inject Certificate Transparency SCTs.
    pub ct_enabled: bool,

    /// Certificate Policies OIDs (BR §7.1.2.7.9).
    /// DV: `["2.23.140.1.2.1"]`, OV: `["2.23.140.1.2.2"]`.
    #[serde(default)]
    pub certificate_policies: Vec<String>,

    // --- Post-Quantum Cryptography (FIPS 203/204) ---
    /// Allowed ML-DSA levels for signing key CSRs (FIPS 204).
    /// Empty means ML-DSA is not accepted for this profile.
    /// Values: "ml-dsa-44", "ml-dsa-65", "ml-dsa-87".
    #[serde(default)]
    pub allowed_ml_dsa_levels: Vec<String>,

    /// Allowed ML-KEM levels for KEM key CSRs (FIPS 203).
    /// Used with /serverkeygen for KRA-based key generation.
    /// Values: "ml-kem-512", "ml-kem-768", "ml-kem-1024".
    #[serde(default)]
    pub allowed_ml_kem_levels: Vec<String>,

    /// Whether to accept composite ML-DSA+classical CSRs.
    /// Per draft-ietf-lamps-pq-composite-sigs-19.
    #[serde(default)]
    pub allow_composite_ml_dsa: bool,

    /// Require dual certificates (paired legacy + PQC) for hybrid
    /// migration scenarios per IDM-5563 lifecycle requirements.
    /// When true, a classical enrollment triggers automatic paired
    /// PQC enrollment (and vice versa) as linked certificates.
    #[serde(default)]
    pub require_dual_cert: bool,

    /// Include the TLS Feature Extension (RFC 7633, OID 1.3.6.1.5.5.7.1.24)
    /// in issued certificates.
    ///
    /// RFC 7633 Section 4: when set, the issued certificate declares that
    /// the TLS server presenting it MUST provide an OCSP stapled response
    /// (status_request, TLS extension type 5) during the TLS handshake.
    /// Clients that understand this extension MUST abort the handshake if
    /// the server fails to staple a valid OCSP response.
    ///
    /// This is required for NIAP CA PP compliance and is commonly referred
    /// to as "must-staple".
    ///
    /// When `true`, the certificate will contain:
    /// ```text
    /// TLS Feature Extension (id-pe-tlsfeature):
    ///   OID:   1.3.6.1.5.5.7.1.24
    ///   Value: SEQUENCE { INTEGER 5 }   -- status_request
    /// ```
    ///
    /// Default: `false`.
    #[serde(default)]
    pub must_staple: bool,
}

impl Default for EnrollmentProfile {
    fn default() -> Self {
        Self {
            name: "default".into(),
            max_validity_days: cab_forum_max_validity_days(),
            max_validity_seconds: None,
            max_not_after: None,
            key_usage: vec!["digitalSignature".into(), "keyEncipherment".into()],
            extended_key_usage: vec!["serverAuth".into()],
            include_ski: true,
            include_aki: true,
            min_rsa_bits: 2048,
            min_ecdsa_curve: "P-256".into(),
            ct_enabled: false,
            certificate_policies: vec!["2.23.140.1.2.1".into()],
            // PQC defaults: accept all ML-DSA and ML-KEM levels
            allowed_ml_dsa_levels: vec!["ml-dsa-44".into(), "ml-dsa-65".into(), "ml-dsa-87".into()],
            allowed_ml_kem_levels: vec![
                "ml-kem-512".into(),
                "ml-kem-768".into(),
                "ml-kem-1024".into(),
            ],
            allow_composite_ml_dsa: true,
            require_dual_cert: false,
            must_staple: false,
        }
    }
}

/// DER-encoded TLS Feature Extension value for must-staple certificates.
///
/// RFC 7633 Section 4 / RFC 6066 Section 8:
///   TLSFeature ::= SEQUENCE OF INTEGER
///   status_request(5)
///
/// ASN.1 DER encoding of SEQUENCE { INTEGER 5 }:
///   30 03        -- SEQUENCE, length 3
///     02 01 05   -- INTEGER, length 1, value 5
///
/// OID: 1.3.6.1.5.5.7.1.24 (id-pe-tlsfeature)
pub const TLS_FEATURE_MUST_STAPLE_DER: &[u8] = &[0x30, 0x03, 0x02, 0x01, 0x05];

/// OID for the TLS Feature Extension (id-pe-tlsfeature).
///
/// RFC 7633 Section 4: 1.3.6.1.5.5.7.1.24
pub const OID_TLS_FEATURE: &str = "1.3.6.1.5.5.7.1.24";

/// OID components for the TLS Feature Extension.
const OID_TLS_FEATURE_COMPONENTS: &[u32] = &[1, 3, 6, 1, 5, 5, 7, 1, 24];

/// Issue a certificate from a CSR.
///
/// Performs CA/B Forum compliance checks before signing:
/// - Key size minimums (RSA 2048+, ECDSA P-256+)
/// - Maximum validity period (398 days for public, 47 days from March 2029)
/// - Required extensions (AKI, SKI, Key Usage, Basic Constraints)
/// - Certificate Transparency SCT injection (when configured)
///
/// # Arguments
///
/// * `csr_der` - DER-encoded PKCS#10 Certificate Signing Request
/// * `profile` - Enrollment profile with constraints to apply
/// * `ca_cert_der` - DER-encoded CA certificate (for issuer DN and AKI)
/// * `signing_key` - CA signing key (PEM from disk or HSM-backed)
/// * `hash_algorithm` - Hash algorithm name (e.g. "sha256")
///
/// # Returns
///
/// [`IssuanceResult`] on success with the DER-encoded certificate and metadata.
pub fn issue_certificate(
    csr_der: &[u8],
    profile: &EnrollmentProfile,
    ca_cert_der: &[u8],
    signing_key: CaSigningKey<'_>,
    hash_algorithm: &str,
    ocsp_url: Option<&str>,
    crl_url: Option<&str>,
) -> Result<IssuanceResult, IssuanceError> {
    // Step 0: Verify CSR proof-of-possession (RFC 7030 §4.2 / RFC 2986 §3).
    //
    // This is the central PoP gate for *every* direct-signing enrollment path
    // (simpleenroll, simplereenroll, CMS-EST, CoAP, STAR, CMP/fullcmc, and the
    // software serverkeygen path). Enforcing it here — rather than per-route —
    // guarantees a CA never signs a CSR whose private key the requester has not
    // proven possession of, regardless of which transport delivered the request.
    verify_csr_pop(csr_der)?;

    // Step 1: Parse and validate CSR.
    validate_csr(csr_der)?;
    issue_verified_request(
        csr_der,
        profile,
        ca_cert_der,
        signing_key,
        hash_algorithm,
        ocsp_url,
        crl_url,
    )
}

// Private: only the PKCS#10 and CRMF verification boundaries may call this.
fn issue_verified_request(
    csr_der: &[u8],
    profile: &EnrollmentProfile,
    ca_cert_der: &[u8],
    signing_key: CaSigningKey<'_>,
    hash_algorithm: &str,
    ocsp_url: Option<&str>,
    crl_url: Option<&str>,
) -> Result<IssuanceResult, IssuanceError> {
    // Step 1a: Check subject DN for prohibited attributes (BR §7.1.2.10.2).
    check_subject_dn_compliance(csr_der)?;

    // Step 2: Check key size against profile minimums.
    check_key_size(csr_der, profile)?;

    // Step 3: Validate requested validity against CA/B Forum limits.
    check_validity_period(profile)?;

    // Step 4: Verify required extensions will be present.
    check_required_extensions(profile)?;

    // Step 5: Parse the CSR to extract subject and public key.
    let csr = synta_certificate::csr::CertificationRequest::from_der(csr_der)
        .map_err(|e| IssuanceError::InvalidCsr(format!("CSR parse failed: {e}")))?;

    let csr_subject_der = csr
        .certification_request_info
        .subject
        .to_der()
        .map_err(|e| IssuanceError::InvalidCsr(format!("CSR subject encode failed: {e}")))?;

    let csr_spki_der = csr
        .certification_request_info
        .subject_pkinfo
        .to_der()
        .map_err(|e| IssuanceError::InvalidCsr(format!("CSR SPKI encode failed: {e}")))?;

    // Step 6: Parse the CA certificate to extract issuer DN and SPKI (for AKI).
    let ca_cert = synta_certificate::Certificate::from_der(ca_cert_der)
        .map_err(|e| IssuanceError::SigningError(format!("CA cert parse failed: {e}")))?;

    let ca_subject_der = ca_cert.tbs_certificate.subject.0;
    let ca_spki_der = ca_cert
        .tbs_certificate
        .subject_public_key_info
        .to_der()
        .map_err(|e| IssuanceError::SigningError(format!("CA SPKI encode failed: {e}")))?;

    // Step 7: Prepare the signing backend (PEM or HSM).
    let pem_key: Option<synta_certificate::BackendPrivateKey>;
    match &signing_key {
        CaSigningKey::Pem(pem) => {
            pem_key = Some(
                synta_certificate::BackendPrivateKey::from_pem(pem, None).map_err(|e| {
                    IssuanceError::SigningError(format!("CA key parse failed: {e}"))
                })?,
            );
            debug!("loaded CA private key from PEM");
        }
        CaSigningKey::Hsm { key_label, .. } => {
            pem_key = None;
            debug!(key_label = %key_label, "using HSM-backed CA signing key");
        }
    }

    // Step 8: Generate serial number — 20 bytes of random data (RFC 5280 §4.1.2.2
    // recommends at least 64 bits of entropy; we use 159 bits with leading 0 for positive).
    let serial_bytes = generate_serial_bytes();
    let serial = synta::Integer::from_unsigned_bytes(&serial_bytes);
    let serial_hex = hex::encode(&serial_bytes);

    // Step 9: Compute validity period.
    let now = Utc::now();
    let mut not_after_chrono = now + chrono::Duration::days(profile.max_validity_days as i64);
    if let Some(seconds) = profile.max_validity_seconds {
        let seconds = i64::try_from(seconds)
            .map_err(|_| IssuanceError::SigningError("validity overflow".into()))?;
        not_after_chrono = not_after_chrono.min(
            now.checked_add_signed(chrono::Duration::seconds(seconds))
                .ok_or_else(|| IssuanceError::SigningError("validity overflow".into()))?,
        );
    }
    if let Some(limit) = profile.max_not_after {
        not_after_chrono = not_after_chrono.min(limit);
    }
    crate::auth::certificate::valid_now(ca_cert_der).map_err(IssuanceError::SigningError)?;
    not_after_chrono = not_after_chrono.min(
        crate::auth::certificate::time(&ca_cert.tbs_certificate.validity.not_after)
            .map_err(IssuanceError::SigningError)?,
    );
    if not_after_chrono <= now {
        return Err(IssuanceError::SigningError(
            "empty certificate validity period".into(),
        ));
    }

    let not_before_time = chrono_to_synta_time(now)
        .map_err(|e| IssuanceError::SigningError(format!("not_before time conversion: {e}")))?;
    let not_after_time = chrono_to_synta_time(not_after_chrono)
        .map_err(|e| IssuanceError::SigningError(format!("not_after time conversion: {e}")))?;

    // Step 10: Build extensions.
    debug!(
        profile = %profile.name,
        max_days = profile.max_validity_days,
        ct = profile.ct_enabled,
        must_staple = profile.must_staple,
        "building certificate from CSR"
    );

    let mut builder = synta_certificate::CertificateBuilder::new()
        .issuer_name(ca_subject_der)
        .subject_name(&csr_subject_der)
        .public_key_der(&csr_spki_der)
        .serial_number(serial)
        .not_valid_before(not_before_time)
        .not_valid_after(not_after_time);

    // SANs are the requested identities already authorized by the route policy.
    // All CA/usage/policy extensions remain controlled by the enrollment profile.
    for (oid, critical, value) in requested_extensions(csr_der)? {
        if oid.components() == synta_certificate::oids::SUBJECT_ALT_NAME {
            builder = builder.add_extension(oid, critical, &value);
        }
    }

    // Basic Constraints: CA:FALSE (critical, per CA/B Forum BR §7.1.2.7).
    if let Some(bc_der) = synta_certificate::encode_basic_constraints(false, None) {
        builder =
            builder.add_extension_oid(synta_certificate::oids::BASIC_CONSTRAINTS, true, &bc_der);
    }

    // Key Usage (critical, per CA/B Forum BR §7.1.2.1).
    let ku_bits = profile_key_usage_bits(profile);
    if let Some(ku_der) = synta_certificate::encode_key_usage(ku_bits) {
        builder = builder.add_extension_oid(synta_certificate::oids::KEY_USAGE, true, &ku_der);
    }

    // Extended Key Usage (non-critical).
    let eku_der = profile_extended_key_usage(profile);
    if let Some(eku) = eku_der {
        builder =
            builder.add_extension_oid(synta_certificate::oids::EXTENDED_KEY_USAGE, false, &eku);
    }

    // Certificate Policies (non-critical, per CA/B Forum BR §7.1.2.7.9).
    if !profile.certificate_policies.is_empty() {
        let cp_der = encode_certificate_policies(&profile.certificate_policies)?;
        builder = builder.add_extension_oid(
            synta_certificate::oids::CERTIFICATE_POLICIES,
            false,
            &cp_der,
        );
    }

    // Subject Key Identifier (non-critical, per CA/B Forum BR §7.1.2.7.2).
    if profile.include_ski {
        let hasher = synta_certificate::OpensslKeyIdHasher;
        if let Some(ski_der) = synta_certificate::encode_subject_key_identifier(
            &csr_spki_der,
            synta_certificate::KeyIdMethod::Rfc5280Sha1,
            &hasher,
        ) {
            builder = builder.add_extension_oid(
                synta_certificate::oids::SUBJECT_KEY_IDENTIFIER,
                false,
                &ski_der,
            );
        }
    }

    // Authority Key Identifier (non-critical, per CA/B Forum BR §7.1.2.7.3).
    if profile.include_aki {
        let hasher = synta_certificate::OpensslKeyIdHasher;
        if let Some(aki_der) = synta_certificate::encode_authority_key_identifier(
            &ca_spki_der,
            synta_certificate::KeyIdMethod::Rfc5280Sha1,
            &hasher,
        ) {
            builder = builder.add_extension_oid(
                synta_certificate::oids::AUTHORITY_KEY_IDENTIFIER,
                false,
                &aki_der,
            );
        }
    }

    // Authority Information Access (non-critical, per CA/B Forum BR §7.1.2.7.7).
    if let Some(url) = ocsp_url {
        let aia_der = encode_aia_extension(url)?;
        builder = builder.add_extension_oid(
            synta_certificate::oids::AUTHORITY_INFO_ACCESS,
            false,
            &aia_der,
        );
    }

    // CRL Distribution Points (non-critical, per CA/B Forum BR §7.1.2.7.7).
    if let Some(url) = crl_url {
        let cdp_der = encode_cdp_extension(url)?;
        builder = builder.add_extension_oid(
            synta_certificate::oids::CRL_DISTRIBUTION_POINTS,
            false,
            &cdp_der,
        );
    }

    // TLS Feature Extension (must-staple) per RFC 7633 §4.
    if profile.must_staple {
        debug!(
            oid = OID_TLS_FEATURE,
            "including TLS Feature Extension (must-staple) per RFC 7633 §4"
        );
        builder = builder.add_extension_oid(
            OID_TLS_FEATURE_COMPONENTS,
            false,
            TLS_FEATURE_MUST_STAPLE_DER,
        );
    }

    // Step 11: Sign the certificate.
    // For ML-DSA CAs, the hash algorithm is built into the signing algorithm
    // (FIPS 204) — pass "none" so synta-certificate uses the key's native
    // algorithm without a separate hash. For classical keys (RSA, ECDSA),
    // the hash_algorithm selects SHA-256/384/512.
    let cert_der = match &signing_key {
        CaSigningKey::Pem(_) => {
            use synta_certificate::PrivateKey as _;
            let ca_pkey = pem_key.as_ref().expect("PEM key loaded in step 7");
            let effective_hash = if hash_algorithm == "none" {
                ""
            } else {
                hash_algorithm
            };
            let signer = ca_pkey.as_signer(effective_hash);
            builder.sign(&signer).map_err(|e| {
                IssuanceError::SigningError(format!("certificate signing failed: {e}"))
            })?
        }
        CaSigningKey::Hsm { context, key_label } => {
            // HSM path: build TBS, sign via PKCS#11, assemble.
            let hsm_signer = HsmCertificateSigner {
                context,
                key_label,
                hash_algorithm,
            };
            builder.sign(&hsm_signer).map_err(|e| {
                IssuanceError::SigningError(format!("HSM certificate signing failed: {e}"))
            })?
        }
    };

    // Step 12: Format subject DN for logging and DB storage.
    let subject_dn = synta_certificate::format_dn(&csr_subject_der);

    info!(
        serial = %serial_hex,
        profile = %profile.name,
        subject = %subject_dn,
        not_after = %not_after_chrono,
        cert_len = cert_der.len(),
        "certificate issued"
    );

    Ok(IssuanceResult {
        certificate_der: cert_der,
        serial_number: serial_hex,
        subject_dn,
        not_before: now,
        not_after: not_after_chrono,
    })
}

/// Generate a 20-byte random serial number suitable for RFC 5280 §4.1.2.2.
///
/// The first byte is masked to 0x7F to guarantee the integer is positive
/// (no leading 0x00 padding needed).  This gives 159 bits of entropy,
/// well above the 64-bit minimum recommended by CA/B Forum.
fn generate_serial_bytes() -> Vec<u8> {
    use rand::Rng;
    let mut bytes = vec![0u8; 20];
    rand::rng().fill_bytes(&mut bytes);
    // Ensure positive by clearing the high bit.
    bytes[0] &= 0x7F;
    // Ensure non-zero first byte.
    if bytes[0] == 0 {
        bytes[0] = 1;
    }
    bytes
}

/// Convert a chrono DateTime<Utc> to a synta_certificate::Time.
///
/// Per RFC 5280 §4.1.2.5:
/// - Dates before 2050: use UTCTime (YYMMDDHHMMSSZ)
/// - Dates from 2050 onward: use GeneralizedTime (YYYYMMDDHHMMSSZ)
fn chrono_to_synta_time(dt: DateTime<Utc>) -> Result<synta_certificate::Time, String> {
    let year = dt.format("%Y").to_string().parse::<u16>().unwrap_or(2024);
    let month = dt.format("%m").to_string().parse::<u8>().unwrap_or(1);
    let day = dt.format("%d").to_string().parse::<u8>().unwrap_or(1);
    let hour = dt.format("%H").to_string().parse::<u8>().unwrap_or(0);
    let minute = dt.format("%M").to_string().parse::<u8>().unwrap_or(0);
    let second = dt.format("%S").to_string().parse::<u8>().unwrap_or(0);

    if year < 2050 {
        let utc_time = synta::UtcTime::new(year, month, day, hour, minute, second)
            .map_err(|e| format!("UtcTime creation failed: {e}"))?;
        Ok(synta_certificate::Time::UtcTime(utc_time))
    } else {
        let gen_time = synta::GeneralizedTime::new(year, month, day, hour, minute, second, None)
            .map_err(|e| format!("GeneralizedTime creation failed: {e}"))?;
        Ok(synta_certificate::Time::GeneralTime(gen_time))
    }
}

/// Convert profile key usage strings to a bitmask for `encode_key_usage`.
fn profile_key_usage_bits(profile: &EnrollmentProfile) -> u16 {
    use synta_certificate::{
        KEY_USAGE_DATA_ENCIPHERMENT, KEY_USAGE_DIGITAL_SIGNATURE, KEY_USAGE_KEY_AGREEMENT,
        KEY_USAGE_KEY_ENCIPHERMENT, KEY_USAGE_NON_REPUDIATION,
    };

    let mut bits: u16 = 0;
    for ku in &profile.key_usage {
        match ku.as_str() {
            "digitalSignature" => bits |= 1 << KEY_USAGE_DIGITAL_SIGNATURE,
            "nonRepudiation" | "contentCommitment" => bits |= 1 << KEY_USAGE_NON_REPUDIATION,
            "keyEncipherment" => bits |= 1 << KEY_USAGE_KEY_ENCIPHERMENT,
            "dataEncipherment" => bits |= 1 << KEY_USAGE_DATA_ENCIPHERMENT,
            "keyAgreement" => bits |= 1 << KEY_USAGE_KEY_AGREEMENT,
            other => {
                warn!(key_usage = %other, "unknown key usage flag in profile; skipping");
            }
        }
    }
    bits
}

/// Build Extended Key Usage DER from profile strings.
fn profile_extended_key_usage(profile: &EnrollmentProfile) -> Option<Vec<u8>> {
    if profile.extended_key_usage.is_empty() {
        return None;
    }

    let mut builder = synta_certificate::ExtendedKeyUsageBuilder::new();
    for eku in &profile.extended_key_usage {
        builder = match eku.as_str() {
            "serverAuth" => builder.server_auth(),
            "clientAuth" => builder.client_auth(),
            "codeSigning" => builder.code_signing(),
            "emailProtection" => builder.email_protection(),
            "timeStamping" => builder.time_stamping(),
            "OCSPSigning" | "ocspSigning" => builder.ocsp_signing(),
            other => {
                warn!(eku = %other, "unknown extended key usage in profile; skipping");
                builder
            }
        };
    }
    builder.build().ok()
}

/// Validate CSR structure.
fn validate_csr(csr_der: &[u8]) -> Result<(), IssuanceError> {
    if csr_der.is_empty() {
        return Err(IssuanceError::InvalidCsr("empty CSR".into()));
    }

    // Check for ASN.1 SEQUENCE tag (0x30) at start.
    if csr_der[0] != 0x30 {
        return Err(IssuanceError::InvalidCsr(
            "does not start with ASN.1 SEQUENCE".into(),
        ));
    }

    use synta_certificate::SignatureVerifier;
    let csr = synta_certificate::csr::CertificationRequest::from_der(csr_der)
        .map_err(|e| IssuanceError::InvalidCsr(format!("PKCS#10 parse failed: {e}")))?;
    let encode_error = |e| IssuanceError::InvalidCsr(format!("CSR encoding: {e}"));
    let cri = csr
        .certification_request_info
        .to_der()
        .map_err(encode_error)?;
    let algorithm = csr.signature_algorithm.to_der().map_err(encode_error)?;
    let spki = csr
        .certification_request_info
        .subject_pkinfo
        .to_der()
        .map_err(encode_error)?;
    synta_certificate::default_signature_verifier()
        .verify_certificate_signature(&cri, &algorithm, csr.signature.as_bytes(), &spki)
        .map_err(|e| IssuanceError::InvalidCsr(format!("CSR proof of possession failed: {e}")))?;

    debug!(len = csr_der.len(), "CSR structure validated");
    Ok(())
}

/// Check CSR subject DN for prohibited attributes (BR §7.1.2.10.2).
fn check_subject_dn_compliance(csr_der: &[u8]) -> Result<(), IssuanceError> {
    let csr = synta_certificate::csr::CertificationRequest::from_der(csr_der)
        .map_err(|e| IssuanceError::InvalidCsr(format!("CSR parse failed: {e}")))?;

    let subject_der = csr
        .certification_request_info
        .subject
        .to_der()
        .map_err(|e| IssuanceError::InvalidCsr(format!("subject DN encode failed: {e}")))?;

    let attrs = synta_certificate::parse_name_attrs(&subject_der);
    for (oid, _value) in &attrs {
        if oid == "2.5.4.11" {
            return Err(IssuanceError::ProhibitedDnAttribute {
                oid: oid.clone(),
                name: "organizationalUnitName".into(),
            });
        }
    }

    Ok(())
}

/// Check key size from CSR against profile minimums.
fn check_key_size(csr_der: &[u8], profile: &EnrollmentProfile) -> Result<(), IssuanceError> {
    // Parse the CSR to extract the public key info.
    let csr = synta_certificate::csr::CertificationRequest::from_der(csr_der).map_err(|e| {
        IssuanceError::InvalidCsr(format!("CSR parse failed in key size check: {e}"))
    })?;

    let spki = &csr.certification_request_info.subject_pkinfo;
    let alg_oid = spki.algorithm.algorithm.components();
    let key_bits = spki.subject_public_key.bit_len();

    let pk_info = synta_certificate::decode_public_key_info(
        &spki.algorithm.algorithm,
        spki.algorithm.parameters.as_ref(),
        spki.subject_public_key.as_bytes(),
        key_bits,
    );

    match &pk_info {
        synta_certificate::PublicKeyInfo::Rsa { bit_count, .. } => {
            debug!(
                algorithm = "RSA",
                key_bits = bit_count,
                "CSR public key info"
            );
            if (*bit_count as u32) < profile.min_rsa_bits {
                return Err(IssuanceError::KeyTooSmall {
                    algorithm: "RSA".into(),
                    bits: *bit_count as u32,
                    min_bits: profile.min_rsa_bits,
                });
            }
        }
        synta_certificate::PublicKeyInfo::Ec {
            bit_count,
            curve_nist_name,
            ..
        } => {
            let curve_name = curve_nist_name.unwrap_or("unknown");
            debug!(
                algorithm = "EC",
                curve = curve_name,
                key_bits = bit_count,
                "CSR public key info"
            );
            let min_bits: usize = match profile.min_ecdsa_curve.as_str() {
                "P-256" => 256,
                "P-384" => 384,
                "P-521" => 521,
                _ => 256,
            };
            if *bit_count < min_bits {
                return Err(IssuanceError::KeyTooSmall {
                    algorithm: format!("EC {curve_name}"),
                    bits: *bit_count as u32,
                    min_bits: min_bits as u32,
                });
            }
        }
        synta_certificate::PublicKeyInfo::Unknown {
            alg_name,
            bit_count,
            ..
        } => {
            // FIPS 204 (ML-DSA) and FIPS 203 (ML-KEM) OID-to-level mapping
            const PQC_ALGORITHMS: &[(&str, &str, &str)] = &[
                ("2.16.840.1.101.3.4.3.17", "ML-DSA-44", "ml-dsa-44"),
                ("2.16.840.1.101.3.4.3.18", "ML-DSA-65", "ml-dsa-65"),
                ("2.16.840.1.101.3.4.3.19", "ML-DSA-87", "ml-dsa-87"),
                ("2.16.840.1.101.3.4.4.1", "ML-KEM-512", "ml-kem-512"),
                ("2.16.840.1.101.3.4.4.2", "ML-KEM-768", "ml-kem-768"),
                ("2.16.840.1.101.3.4.4.3", "ML-KEM-1024", "ml-kem-1024"),
            ];

            let oid_str = alg_oid
                .iter()
                .map(|c| c.to_string())
                .collect::<Vec<_>>()
                .join(".");

            if let Some(&(_, display_name, level)) =
                PQC_ALGORITHMS.iter().find(|(oid, _, _)| *oid == oid_str)
            {
                debug!(
                    algorithm = display_name,
                    key_bits = bit_count,
                    "CSR public key"
                );
                let allowed = if level.starts_with("ml-dsa") {
                    &profile.allowed_ml_dsa_levels
                } else {
                    &profile.allowed_ml_kem_levels
                };
                if !allowed.is_empty() && !allowed.iter().any(|l| l == level) {
                    return Err(IssuanceError::AlgorithmNotAllowed {
                        algorithm: display_name.into(),
                        profile: profile.name.clone(),
                    });
                }
            } else if oid_str.starts_with("2.16.840.1.114027.80.5.2.") {
                // Composite ML-DSA (draft-ietf-lamps-pq-composite-sigs-19)
                debug!(algorithm = %alg_name, oid = %oid_str, "CSR public key: composite ML-DSA");
                if !profile.allow_composite_ml_dsa {
                    return Err(IssuanceError::AlgorithmNotAllowed {
                        algorithm: format!("composite ML-DSA ({oid_str})"),
                        profile: profile.name.clone(),
                    });
                }
            } else {
                debug!(
                    algorithm = %alg_name,
                    key_bits = bit_count,
                    alg_oid = ?alg_oid,
                    "CSR public key: unknown algorithm (skipping size check)"
                );
            }
        }
    }
    Ok(())
}

/// Validate the requested validity period.
fn check_validity_period(profile: &EnrollmentProfile) -> Result<(), IssuanceError> {
    let max_days = cab_forum_max_validity_days();

    if profile.max_validity_days > max_days {
        warn!(
            requested = profile.max_validity_days,
            max = max_days,
            "validity period exceeds CA/B Forum maximum"
        );
        return Err(IssuanceError::ValidityTooLong {
            requested_days: profile.max_validity_days,
            max_days,
        });
    }

    Ok(())
}

/// Encode Certificate Policies extension (RFC 5280 §4.2.1.4).
fn encode_certificate_policies(policy_oids: &[String]) -> Result<Vec<u8>, IssuanceError> {
    let mut builder = synta_certificate::CertificatePoliciesBuilder::new();
    for oid_str in policy_oids {
        let components: Vec<u32> = oid_str
            .split('.')
            .map(|s| s.parse())
            .collect::<Result<_, _>>()
            .map_err(|e| {
                IssuanceError::InvalidCsr(format!("invalid policy OID '{oid_str}': {e}"))
            })?;
        builder = builder.add_policy(&components);
    }
    builder.build().map_err(|e| {
        IssuanceError::SigningError(format!("Certificate Policies encoding failed: {e}"))
    })
}

/// Encode Authority Information Access extension (RFC 5280 §4.2.2.1).
fn encode_aia_extension(ocsp_url: &str) -> Result<Vec<u8>, IssuanceError> {
    synta_certificate::AuthorityInformationAccessBuilder::new()
        .ocsp(ocsp_url)
        .build()
        .map_err(|e| IssuanceError::SigningError(format!("AIA encoding failed: {e}")))
}

/// Encode CRL Distribution Points extension (RFC 5280 §4.2.1.13).
fn encode_cdp_extension(crl_url: &str) -> Result<Vec<u8>, IssuanceError> {
    synta_certificate::CRLDistributionPointsBuilder::new()
        .full_name_uri(crl_url)
        .build()
        .map_err(|e| IssuanceError::SigningError(format!("CDP encoding failed: {e}")))
}

/// CA/B Forum maximum validity period per Ballot SC-081v3.
///
/// Returns the maximum certificate validity in days based on the current
/// date. The schedule reduces validity over time:
///
/// | Effective Date | Maximum |
/// |----------------|---------|
/// | Before 2026-03-15 | 398 days |
/// | 2026-03-15 | 200 days |
/// | 2027-03-15 | 100 days |
/// | 2029-03-15 | 47 days |
pub fn cab_forum_max_validity_days() -> u32 {
    use chrono::NaiveDate;

    let today = Utc::now().date_naive();
    let p200 = NaiveDate::from_ymd_opt(2026, 3, 15).expect("valid date");
    let p100 = NaiveDate::from_ymd_opt(2027, 3, 15).expect("valid date");
    let p47 = NaiveDate::from_ymd_opt(2029, 3, 15).expect("valid date");

    if today < p200 {
        398
    } else if today < p100 {
        200
    } else if today < p47 {
        100
    } else {
        47
    }
}

// ── HSM CertificateSigner ────────────────────────────────────────────────────

/// `CertificateSigner` implementation that delegates signing to a PKCS#11 HSM.
///
/// Uses `CKM_SHA256_RSA_PKCS` (or SHA-384/SHA-512 variants) which hashes
/// the TBS data and signs in a single PKCS#11 `C_Sign` operation.
struct HsmCertificateSigner<'a> {
    context: &'a Arc<kipuka_hsm::HsmContext>,
    key_label: &'a str,
    hash_algorithm: &'a str,
}

/// Error type for HSM signing operations in the CertificateSigner trait.
#[derive(Debug)]
struct HsmSignerError(String);

impl std::fmt::Display for HsmSignerError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "{}", self.0)
    }
}

impl std::error::Error for HsmSignerError {}

impl<'a> synta_certificate::CertificateSigner for HsmCertificateSigner<'a> {
    type Error = HsmSignerError;

    fn signature_algorithm_der(&self) -> Result<Vec<u8>, Self::Error> {
        // Return the DER-encoded AlgorithmIdentifier for SHA-256 with RSA.
        //
        // AlgorithmIdentifier ::= SEQUENCE {
        //   algorithm   OBJECT IDENTIFIER,
        //   parameters  ANY OPTIONAL
        // }
        //
        // sha256WithRSAEncryption: OID 1.2.840.113549.1.1.11
        // Parameters: NULL
        match self.hash_algorithm {
            "sha256" => {
                // OID 1.2.840.113549.1.1.11 + NULL params
                Ok(vec![
                    0x30, 0x0d, // SEQUENCE, length 13
                    0x06, 0x09, // OID, length 9
                    0x2a, 0x86, 0x48, 0x86, 0xf7, 0x0d, 0x01, 0x01,
                    0x0b, // sha256WithRSAEncryption
                    0x05, 0x00, // NULL
                ])
            }
            "sha384" => {
                // OID 1.2.840.113549.1.1.12 + NULL params
                Ok(vec![
                    0x30, 0x0d, 0x06, 0x09, 0x2a, 0x86, 0x48, 0x86, 0xf7, 0x0d, 0x01, 0x01, 0x0c,
                    0x05, 0x00,
                ])
            }
            "sha512" => {
                // OID 1.2.840.113549.1.1.13 + NULL params
                Ok(vec![
                    0x30, 0x0d, 0x06, 0x09, 0x2a, 0x86, 0x48, 0x86, 0xf7, 0x0d, 0x01, 0x01, 0x0d,
                    0x05, 0x00,
                ])
            }
            other => Err(HsmSignerError(format!(
                "unsupported hash algorithm for HSM RSA signing: {other}"
            ))),
        }
    }

    fn sign_tbs(&self, tbs_der: &[u8]) -> Result<Vec<u8>, Self::Error> {
        // CKM_SHA256_RSA_PKCS (and variants) hash the data internally,
        // so we pass the raw TBS bytes directly.
        self.context
            .sign_data(self.key_label, tbs_der, self.hash_algorithm)
            .map_err(|e| HsmSignerError(format!("PKCS#11 sign failed: {e}")))
    }
}

/// Verify that required extensions are configured.
fn check_required_extensions(profile: &EnrollmentProfile) -> Result<(), IssuanceError> {
    if !profile.include_aki {
        return Err(IssuanceError::MissingExtension(
            "Authority Key Identifier (required by CA/B Forum)".into(),
        ));
    }
    if !profile.include_ski {
        return Err(IssuanceError::MissingExtension(
            "Subject Key Identifier (required by CA/B Forum)".into(),
        ));
    }
    if profile.key_usage.is_empty() {
        return Err(IssuanceError::MissingExtension(
            "Key Usage (required by CA/B Forum)".into(),
        ));
    }

    Ok(())
}

/// Decode requested extensions strictly; duplicate OIDs are ambiguous and rejected.
pub(crate) fn requested_extensions(
    csr_der: &[u8],
) -> Result<Vec<(synta::ObjectIdentifier, bool, Vec<u8>)>, IssuanceError> {
    let csr = synta_certificate::csr::CertificationRequest::from_der(csr_der)
        .map_err(|e| IssuanceError::InvalidCsr(e.to_string()))?;
    let mut result = Vec::new();
    if let Some(attrs) = &csr.certification_request_info.attributes {
        for attr in attrs.elements() {
            if attr.attr_type.components() != synta_certificate::oids::PKCS9_EXTENSION_REQUEST {
                continue;
            }
            for value in attr.attr_values.elements() {
                let extensions: Vec<synta_certificate::Extension<'_>> =
                    synta::Decoder::new(value.as_bytes(), synta::Encoding::Der)
                        .decode()
                        .map_err(|e| {
                            IssuanceError::InvalidCsr(format!("requested extensions: {e}"))
                        })?;
                for ext in extensions {
                    if result.iter().any(|(oid, _, _)| oid == &ext.extn_id) {
                        return Err(IssuanceError::InvalidCsr(
                            "duplicate requested extension".into(),
                        ));
                    }
                    result.push((
                        ext.extn_id,
                        ext.critical.as_ref().is_some_and(|v| v.0),
                        ext.extn_value.as_bytes().to_vec(),
                    ));
                }
            }
        }
    }
    Ok(result)
}

/// CRMF signing-key proof boundary. RA-verified and encryption PoP need separate
/// explicit RA/encipherment policies and are not implicitly trusted here.
pub(crate) fn issue_crmf_certificate(
    request: &synta_certificate::crmf_types::CertReqMsg<'_>,
    profile: &EnrollmentProfile,
    ca_cert_der: &[u8],
    signing_key: CaSigningKey<'_>,
    hash_algorithm: &str,
    ocsp_url: Option<&str>,
    crl_url: Option<&str>,
) -> Result<IssuanceResult, IssuanceError> {
    use synta_certificate::{SignatureVerifier, crmf_types::ProofOfPossession};
    let invalid = |e| IssuanceError::InvalidCsr(format!("CRMF encoding: {e}"));
    let template = &request.cert_req.cert_template;
    let subject = template
        .subject
        .as_ref()
        .ok_or_else(|| IssuanceError::InvalidCsr("CRMF subject required".into()))?
        .to_der()
        .map_err(invalid)?;
    let spki = template
        .public_key
        .as_ref()
        .ok_or_else(|| IssuanceError::InvalidCsr("CRMF public key required".into()))?
        .to_der()
        .map_err(invalid)?;
    let Some(ProofOfPossession::Signature(pop)) = &request.popo else {
        return Err(IssuanceError::InvalidCsr(
            "supported CRMF signature proof of possession required".into(),
        ));
    };
    // When subject and publicKey are in CertTemplate, RFC4211 requires signing
    // CertRequest itself, with poposkInput absent.
    if pop.poposk_input.is_some() {
        return Err(IssuanceError::InvalidCsr(
            "unexpected poposkInput for complete CertTemplate".into(),
        ));
    }
    let tbs = request.cert_req.to_der().map_err(invalid)?;
    let algorithm = pop.algorithm_identifier.to_der().map_err(invalid)?;
    synta_certificate::default_signature_verifier()
        .verify_certificate_signature(&tbs, &algorithm, pop.signature.as_bytes(), &spki)
        .map_err(|e| IssuanceError::InvalidCsr(format!("CRMF proof of possession failed: {e}")))?;
    let mut builder = synta_certificate::CsrBuilder::new()
        .subject_name(&subject)
        .public_key_der(&spki);
    if let Some(extensions) = &template.extensions {
        for ext in extensions {
            builder = builder.add_extension(
                ext.extn_id.clone(),
                ext.critical.as_ref().is_some_and(|v| v.0),
                ext.extn_value.as_bytes(),
            );
        }
    }
    // Internal representation only, after verifying the real CRMF signature.
    let cri = builder
        .build_cri(&algorithm)
        .map_err(|e| IssuanceError::InvalidCsr(e.to_string()))?;
    let csr = synta_certificate::CsrBuilder::assemble(&cri, &algorithm, pop.signature.as_bytes())
        .map_err(|e| IssuanceError::InvalidCsr(e.to_string()))?;
    issue_verified_request(
        &csr,
        profile,
        ca_cert_der,
        signing_key,
        hash_algorithm,
        ocsp_url,
        crl_url,
    )
}

/// Sign a protocol message with the configured CA key without exporting HSM keys.
pub(crate) fn sign_message(
    key: CaSigningKey<'_>,
    hash: &str,
    message: &[u8],
) -> Result<(Vec<u8>, Vec<u8>), crate::error::KipukaError> {
    use synta_certificate::{CertificateSigner, PrivateKey};
    let err = |e: String| crate::error::KipukaError::Ca(format!("message signing failed: {e}"));
    match key {
        CaSigningKey::Pem(pem) => {
            let key = synta_certificate::BackendPrivateKey::from_pem(pem, None)
                .map_err(|e| err(e.to_string()))?;
            let signer = key.as_signer(hash);
            Ok((
                signer
                    .signature_algorithm_der_erased()
                    .map_err(|e| err(e.to_string()))?,
                signer
                    .sign_tbs_erased(message)
                    .map_err(|e| err(e.to_string()))?,
            ))
        }
        CaSigningKey::Hsm { context, key_label } => {
            let signer = HsmCertificateSigner {
                context,
                key_label,
                hash_algorithm: hash,
            };
            Ok((
                signer
                    .signature_algorithm_der()
                    .map_err(|e| err(e.to_string()))?,
                signer.sign_tbs(message).map_err(|e| err(e.to_string()))?,
            ))
        }
    }
}

/// Store a newly issued certificate before reporting successful issuance.
pub(crate) async fn persist_certificate(
    state: &crate::state::AppState,
    ca_id: &str,
    profile: &str,
    result: &IssuanceResult,
) -> Result<(), crate::error::KipukaError> {
    persist_certificate_on(&state.db, ca_id, profile, result).await?;
    crate::audit::record_checked(
        &state.db,
        &state.audit,
        crate::audit::AuditEvent::new(crate::audit::AuditEventType::CertIssue)
            .with_detail(format!("ca_id={ca_id}, serial={}", result.serial_number)),
    )
    .await?;
    Ok(())
}

/// Persist within the caller's transaction, allowing STAR state and inventory to commit atomically.
pub(crate) async fn persist_certificate_on<'e, E: sqlx::Executor<'e, Database = sqlx::Any>>(
    executor: E,
    ca_id: &str,
    profile: &str,
    result: &IssuanceResult,
) -> Result<(), crate::error::KipukaError> {
    let cert = synta_certificate::Certificate::from_der(&result.certificate_der)
        .map_err(|e| crate::error::KipukaError::Ca(e.to_string()))?;
    let issuer = synta_certificate::format_dn(cert.tbs_certificate.issuer.as_bytes());
    sqlx::query(crate::db::pg_sql("INSERT INTO certificates (serial, subject_dn, issuer_dn, not_before, not_after, der_encoded, ca_id, profile, status) VALUES (?, ?, ?, ?, ?, ?, ?, ?, 'active')"))
        .bind(&result.serial_number).bind(&result.subject_dn).bind(issuer)
        .bind(result.not_before.format("%Y-%m-%dT%H:%M:%SZ").to_string())
        .bind(result.not_after.format("%Y-%m-%dT%H:%M:%SZ").to_string())
        .bind(&result.certificate_der).bind(ca_id).bind(profile).execute(executor).await
        .map_err(|e| crate::error::KipukaError::Db(format!("certificate persistence failed: {e}")))?;
    Ok(())
}

/// Verify CSR proof-of-possession (RFC 7030 §4.2, RFC 2986 §3).
///
/// A PKCS#10 CSR is self-signed: the `signature` field is produced with the
/// private key corresponding to the public key carried in the CSR's own
/// `SubjectPublicKeyInfo`. Verifying that signature over the
/// `CertificationRequestInfo` (the TBS portion) proves the requester holds the
/// private key — proof-of-possession. RFC 7030 §4.2 requires an EST server to
/// perform this check before issuing.
///
/// ML-KEM keys are a special case: ML-KEM is a key-encapsulation mechanism and
/// cannot produce a signature, so a FIPS 203 CSR carries proof-of-possession as
/// a *separate* ML-DSA signature (see RFC 9688 and issue #9/#17/#25) rather than
/// a self-signature. That mechanism is not implemented here, so we **fail
/// closed** — rejecting the CSR — rather than skipping PoP and issuing blindly.
fn verify_csr_pop(csr_der: &[u8]) -> Result<(), IssuanceError> {
    use synta_certificate::SignatureVerifier;

    let csr = synta_certificate::csr::CertificationRequest::from_der(csr_der)
        .map_err(|e| IssuanceError::InvalidCsr(format!("CSR parse failed: {e}")))?;

    // Reject key-encapsulation keys up front: they cannot self-sign, so the
    // generic verifier below would fail with a cryptic algorithm error. An
    // explicit rejection makes the fail-closed behaviour clear in the logs.
    let spki_alg_oid = &csr
        .certification_request_info
        .subject_pkinfo
        .algorithm
        .algorithm;
    if let Some(name) = synta_certificate::identify_public_key_algorithm(spki_alg_oid)
        && matches!(
            name,
            synta_certificate::names::ML_KEM_512
                | synta_certificate::names::ML_KEM_768
                | synta_certificate::names::ML_KEM_1024
        )
    {
        warn!(
            algorithm = %name,
            "rejecting ML-KEM CSR: separate ML-DSA proof-of-possession not yet supported"
        );
        return Err(IssuanceError::InvalidCsr(format!(
            "{name} is a key-encapsulation key and cannot self-sign; \
             ML-KEM proof-of-possession (a separate ML-DSA signature) is not yet supported"
        )));
    }

    // Encode the CertificationRequestInfo (the signed TBS portion).
    let cri_der = csr
        .certification_request_info
        .to_der()
        .map_err(|e| IssuanceError::InvalidCsr(format!("CSR CRI encode failed: {e}")))?;

    // Encode the signature algorithm identifier.
    let sig_alg_der = csr
        .signature_algorithm
        .to_der()
        .map_err(|e| IssuanceError::InvalidCsr(format!("CSR sig alg encode failed: {e}")))?;

    // Raw signature bytes from the BIT STRING.
    let signature_bits = csr.signature.as_bytes();

    // The CSR is self-signed, so the verifying key is the CSR's own SPKI.
    let spki_der = csr
        .certification_request_info
        .subject_pkinfo
        .to_der()
        .map_err(|e| IssuanceError::InvalidCsr(format!("CSR SPKI encode failed: {e}")))?;

    let verifier = synta_certificate::default_signature_verifier();
    verifier
        .verify_certificate_signature(&cri_der, &sig_alg_der, signature_bits, &spki_der)
        .map_err(|e| {
            warn!(error = %e, "CSR proof-of-possession verification failed");
            IssuanceError::InvalidCsr(format!(
                "CSR self-signature (proof-of-possession) verification failed: {e}"
            ))
        })?;

    debug!("CSR proof-of-possession verified");
    Ok(())
}

#[cfg(test)]
mod issuance_error_classification_tests {
    //! Pin the client/server split that drives HTTP and CoAP status codes.
    //!
    //! A regression here silently mislabels a bad CSR as a server fault (500,
    //! reason hidden) or blames the client for a server misconfiguration (400).

    use super::IssuanceError;
    use crate::error::KipukaError;

    #[test]
    fn csr_content_faults_are_client_errors() {
        let client = [
            IssuanceError::InvalidCsr("bad self-signature".into()),
            IssuanceError::KeyTooSmall {
                algorithm: "RSA".into(),
                bits: 1024,
                min_bits: 2048,
            },
            IssuanceError::AlgorithmNotAllowed {
                algorithm: "MD5".into(),
                profile: "default".into(),
            },
            IssuanceError::ProhibitedDnAttribute {
                oid: "2.5.4.5".into(),
                name: "serialNumber".into(),
            },
        ];
        for e in client {
            assert!(e.is_client_error(), "{e} must classify as a client error");
            assert!(
                matches!(KipukaError::from(e), KipukaError::BadRequest(_)),
                "a client CSR fault must map to BadRequest (400)"
            );
        }
    }

    #[test]
    fn server_and_profile_faults_are_server_errors() {
        // MissingExtension and ValidityTooLong come from the server-side
        // EnrollmentProfile, not the client's CSR — they must stay 500.
        let server = [
            IssuanceError::SigningError("HSM offline".into()),
            IssuanceError::StorageError("db write failed".into()),
            IssuanceError::MissingExtension("keyUsage".into()),
            IssuanceError::ValidityTooLong {
                requested_days: 900,
                max_days: 825,
            },
            IssuanceError::UnknownProfile("ghost".into()),
        ];
        for e in server {
            assert!(!e.is_client_error(), "{e} must classify as a server error");
            assert!(
                matches!(KipukaError::from(e), KipukaError::Ca(_)),
                "a server/profile fault must map to Ca (500)"
            );
        }
    }
}