rite_model/

types.rs

//! Shared semantic types for the ceremony domain model.

use serde::{Deserialize, Serialize};
use std::fmt;

/// Ceremony metadata (name and optional description).
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Metadata {
    /// Human-readable ceremony name.
    pub name: String,
    /// Optional description.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub description: Option<String>,
}

/// Extract the role type from a role ID.
///
/// `"witness__1"` → `"witness"`, `"operator"` → `"operator"`.
pub fn role_type(id: &str) -> &str {
    id.split_once("__").map_or(id, |(prefix, _)| prefix)
}

/// Derive a display name from a step or section ID.
///
/// Splits on `_` and `-`, title-cases each word, joins with space.
/// `"verify_time"` → `"Verify Time"`, `"generate_root_ca"` → `"Generate Root Ca"`.
///
/// Note: this naive title-casing does not handle acronyms; `"root_ca"` becomes `"Root Ca"`
/// rather than `"Root CA"`. A lookup table for common ceremony acronyms (CA, CSR, PKI, HSM,
/// TPM) could improve this. See `derive_role_name` for the same limitation.
pub fn derive_step_name(id: &str) -> String {
    id.split(['_', '-'])
        .map(|word| {
            let mut chars = word.chars();
            match chars.next() {
                None => String::new(),
                Some(c) => c.to_uppercase().to_string() + chars.as_str(),
            }
        })
        .collect::<Vec<_>>()
        .join(" ")
}

/// Derive a display name from a role ID.
///
/// Title-cases each word (split on `_`, `-`, and `__`), including the discriminator suffix.
/// `"witness__1"` → `"Witness 1"`, `"hsm_operator__primary"` → `"Hsm Operator Primary"`.
pub fn derive_role_name(id: &str) -> String {
    id.replace("__", " ")
        .split(['_', '-', ' '])
        .filter(|s| !s.is_empty())
        .map(|word| {
            let mut chars = word.chars();
            match chars.next() {
                None => String::new(),
                Some(c) => c.to_uppercase().to_string() + chars.as_str(),
            }
        })
        .collect::<Vec<_>>()
        .join(" ")
}

/// Action types available in ceremony steps.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
#[non_exhaustive]
pub enum ActionType {
    /// Verify system clock is correct before ceremony proceeds.
    ///
    /// Displays current time and requires operator confirmation.
    /// Should be placed as the first step to ensure all timestamps are valid.
    ClockCheck,
    /// Human attests to something with yes/no decision (single person).
    ///
    /// Use when the verification requires human judgment about external state.
    /// Example: "Verify all network cables are disconnected".
    Confirm,
    /// Machine compares two known values and records pass/fail (automatic).
    ///
    /// Use when both values are known to the system and comparison is deterministic.
    /// Example: Compare computed `SHA-256` hash against expected value.
    CheckValue,
    /// Two-party verbal verification: reader speaks value aloud, confirmer verifies.
    ///
    /// Use when a value must be verified against something external (physical label,
    /// document). Supports NATO phonetic alphabet and hex formatting.
    OralReadback,
    /// Capture machine information (hostname, CPU, OS) as evidence.
    ///
    /// Records device identity to prove which machine ran the ceremony.
    /// Should be placed early in ceremony to establish machine context.
    MachineInfo,

    /// Generate a key: a keypair for an asymmetric algorithm, one secret for
    /// a symmetric one.
    GenerateKey,
    /// Encrypt a private key under another key so it can leave the machine.
    ///
    /// The OpenSSL backend produces a CMS `AuthEnvelopedData` under
    /// AES-256-GCM. Which encapsulation that takes follows the recipient key,
    /// and the transcript records what the wrap actually did.
    ///
    /// Reads `wrapping_key:` to wrap under a key the backend holds, or
    /// `recipient:` to wrap to a public key held outside the ceremony.
    WrapKey,
    /// Decrypt a wrapped key and import it into a backend under a new label.
    UnwrapKey,
    /// Export public key from keypair.
    ExportPublic,
    /// Sign arbitrary data with a backend-managed key.
    ///
    /// The signature algorithm follows from the key unless `algorithm:` names
    /// another one the key accepts. Requires a backend implementing `SignBackend`.
    SignData,
    /// Verify a signature over data, given the signer's public key.
    ///
    /// Needs no backend: verification takes only a public key, so it works on
    /// evidence the ceremony did not produce. The key may be a bare public key
    /// or a certificate carrying one. Naming a `backend:` delegates the check
    /// to that backend instead.
    VerifySignature,
    /// Formal attestation statement.
    Attest,
    /// Fold human-supplied entropy into the ceremony seed.
    ///
    /// A participant supplies a free-form random value (for example, the
    /// result of rolling physical dice), which is mixed into the entropy
    /// source's ratchet. Any later drawn value reflects the contribution and
    /// stays re-derivable by `rite verify`.
    GatherEntropy,
    /// TPM attestation with PCR measurements and cryptographic quotes.
    ///
    /// Requires the `rite-tpm` backend.
    TpmAttest,

    /// Read X.509 certificate from PIV smart card slot.
    ///
    /// No PIN required; reading certificates is unauthenticated on PIV cards.
    /// Requires a PIV backend.
    PivReadCertificate,
    /// Sign data using PIV smart card on-device key.
    ///
    /// Handles PIN verification internally before signing.
    /// Requires a PIV backend.
    PivSign,
    /// Generate a `YubiKey` attestation certificate for a PIV slot (Yubico extension).
    ///
    /// Slot `F9` signs the key's certificate to prove it was generated on-device.
    /// Requires the `rite-yubikey` backend.
    YubikeyAttestSlot,

    /// Issue an X.509 certificate from a PKCS#10 CSR.
    ///
    /// Takes a CSR and a backend-managed signing key, assembles the `TBSCertificate`,
    /// signs it via the backend's `SignBackend`, and produces a DER-encoded certificate.
    /// Works with any backend implementing `SignBackend` (software, PKCS#11, `YubiKey`).
    IssueCertificate,
    /// Generate a PKCS#10 CSR signed by a backend-managed key.
    ///
    /// Takes a backend-managed signing key and subject parameters, assembles a
    /// `CertReqInfo`, signs it via the backend's `SignBackend`, and produces a
    /// `DER`-encoded `CSR`.
    GenerateCsr,
}

/// Whether an action needs the `backend:` field on its step.
///
/// Three states, not two: an action can also run without a backend and accept
/// one anyway. Verification is the case that forces the distinction, since a
/// signature check needs only a public key but a validated deployment may
/// require it inside the boundary.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
#[non_exhaustive]
pub enum BackendUsage {
    /// The step must name a backend; omitting it is an error.
    Required,
    /// The step runs in software unless it names a backend, which then does the
    /// work instead. Naming one changes who performs the operation, not what
    /// the step accepts or produces.
    SoftwareUnlessNamed,
    /// The action never uses a backend; naming one is a mistake worth warning about.
    Unused,
}

/// The certificate shape an `issue_certificate` step asks for.
///
/// DSL vocabulary rather than a backend concern: the author writes the name,
/// and the handler turns it into X.509 extensions. `path_len` is a separate
/// parameter, not part of a profile's identity, so this enum carries no
/// run-specific values.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
#[non_exhaustive]
pub enum CertProfile {
    /// Self-signed CA at the top of a chain.
    RootCa,
    /// CA below another, constrained by `path_len`.
    SubCa,
    /// TLS server certificate.
    TlsServer,
    /// Code-signing certificate.
    CodeSigning,
    /// A leaf with no CA rights and no extended key usage.
    EndEntity,
}

impl fmt::Display for CertProfile {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            CertProfile::RootCa => write!(f, "root_ca"),
            CertProfile::SubCa => write!(f, "sub_ca"),
            CertProfile::TlsServer => write!(f, "tls_server"),
            CertProfile::CodeSigning => write!(f, "code_signing"),
            CertProfile::EndEntity => write!(f, "end_entity"),
        }
    }
}

impl std::str::FromStr for CertProfile {
    type Err = UnknownCertProfile;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        match s {
            "root_ca" => Ok(Self::RootCa),
            // `intermediate_ca` is the same shape under the name the PKI
            // world more often uses for it.
            "sub_ca" | "intermediate_ca" => Ok(Self::SubCa),
            "tls_server" => Ok(Self::TlsServer),
            "code_signing" => Ok(Self::CodeSigning),
            "end_entity" => Ok(Self::EndEntity),
            _ => Err(UnknownCertProfile),
        }
    }
}

/// A `profile:` value naming no certificate shape.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct UnknownCertProfile;

impl fmt::Display for UnknownCertProfile {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(
            f,
            "supported profiles: root_ca, sub_ca, tls_server, code_signing, end_entity"
        )
    }
}

/// What an action requires of its step's `reads:` map.
///
/// See [`ActionType::reads_contract`].
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub struct ReadsContract {
    /// Inputs every step of this action must name.
    pub required: &'static [&'static str],
    /// Groups from which exactly one input must be named. Each group holds the
    /// alternatives in the order they should be listed to the author.
    pub exactly_one_of: &'static [&'static [&'static str]],
    /// `with:` fields that mean nothing unless the step also names a given
    /// input, as `(field, input)` pairs.
    ///
    /// Where an action offers two paths over one operation, a parameter can
    /// belong to only one of them. On the other path it would be parsed and
    /// never read, so the step would run without whatever the parameter asked
    /// for. This says which parameter needs which input.
    pub with_field_requires: &'static [(&'static str, &'static str)],
}

impl ReadsContract {
    /// The contract of an action that constrains its inputs in neither way.
    pub const NONE: Self = Self::required(&[]);

    /// The contract of an action that requires these inputs and offers no
    /// alternatives between them.
    #[must_use]
    pub const fn required(fields: &'static [&'static str]) -> Self {
        Self {
            required: fields,
            exactly_one_of: &[],
            with_field_requires: &[],
        }
    }

    /// Whether this contract constrains the `reads:` map at all.
    ///
    /// `with_field_requires` is a rule over `with:`, so it is not counted here.
    pub fn is_empty(&self) -> bool {
        self.required.is_empty() && self.exactly_one_of.is_empty()
    }
}

impl ActionType {
    /// Every action type, for callers that need to enumerate them.
    ///
    /// Maintained by hand: `#[non_exhaustive]` means no downstream crate can
    /// derive this list, and adding a variant produces no error outside this
    /// crate. Adding one here is what keeps editor completion and any other
    /// catalogue from silently missing it. The test below catches omissions.
    pub const ALL: &'static [ActionType] = &[
        ActionType::ClockCheck,
        ActionType::Confirm,
        ActionType::CheckValue,
        ActionType::OralReadback,
        ActionType::MachineInfo,
        ActionType::GenerateKey,
        ActionType::WrapKey,
        ActionType::UnwrapKey,
        ActionType::ExportPublic,
        ActionType::SignData,
        ActionType::VerifySignature,
        ActionType::Attest,
        ActionType::GatherEntropy,
        ActionType::TpmAttest,
        ActionType::PivReadCertificate,
        ActionType::PivSign,
        ActionType::YubikeyAttestSlot,
        ActionType::IssueCertificate,
        ActionType::GenerateCsr,
    ];

    /// How this action relates to the `backend:` field on its step.
    ///
    /// TODO: Replace this with a nested enum split — `ActionType::Backend(BackendAction)` vs
    /// `ActionType::Local(LocalAction)`, once a home is found for the actions that are
    /// neither. This is a breaking change to every match on `ActionType` variants.
    pub fn backend_usage(self) -> BackendUsage {
        match self {
            ActionType::GenerateKey
            | ActionType::SignData
            | ActionType::WrapKey
            | ActionType::UnwrapKey
            | ActionType::ExportPublic
            | ActionType::GenerateCsr
            | ActionType::IssueCertificate
            | ActionType::PivReadCertificate
            | ActionType::PivSign
            | ActionType::YubikeyAttestSlot
            | ActionType::TpmAttest => BackendUsage::Required,

            ActionType::VerifySignature => BackendUsage::SoftwareUnlessNamed,

            ActionType::ClockCheck
            | ActionType::Confirm
            | ActionType::CheckValue
            | ActionType::OralReadback
            | ActionType::MachineInfo
            | ActionType::Attest
            | ActionType::GatherEntropy => BackendUsage::Unused,
        }
    }

    /// Returns the `with:` field names that are required for this action.
    ///
    /// The resolver reports a diagnostic for each missing field.
    ///
    /// TODO: Replace the stringly-typed `with: serde_json::Value` in `schema::StepBody` with a
    /// typed `WithFields` enum (one variant per action, carrying its required fields as named
    /// struct members). Serde would then enforce required fields at parse time and this method
    /// would no longer be needed. This is a breaking change to the schema and lowering layers.
    pub fn required_with_fields(self) -> &'static [&'static str] {
        match self {
            ActionType::CheckValue => &["actual", "expected"],
            ActionType::GenerateCsr => &["subject"],

            ActionType::ClockCheck
            | ActionType::Confirm
            | ActionType::OralReadback
            | ActionType::MachineInfo
            | ActionType::GenerateKey
            | ActionType::WrapKey
            | ActionType::UnwrapKey
            | ActionType::ExportPublic
            | ActionType::SignData
            | ActionType::VerifySignature
            | ActionType::Attest
            | ActionType::GatherEntropy
            | ActionType::TpmAttest
            | ActionType::PivReadCertificate
            | ActionType::PivSign
            | ActionType::YubikeyAttestSlot
            | ActionType::IssueCertificate => &[],
        }
    }

    /// Every `with:` key this action accepts.
    ///
    /// Nothing else may appear under `with:`. Serde ignores a key it does not
    /// know, so without this a misspelled field, or one that used to exist, is
    /// dropped in silence and the ceremony quietly stops doing what its author
    /// wrote. That is the failure this list exists to prevent, and it covers
    /// typos and removed fields alike rather than naming them one at a time.
    ///
    /// Required keys are the subset in
    /// [`required_with_fields`](Self::required_with_fields); the rest are
    /// optional. Nested keys are not listed: only the top level of the block
    /// is checked, because a nested shape belongs to the handler's own params
    /// type.
    pub fn known_with_fields(self) -> &'static [&'static str] {
        match self {
            ActionType::ClockCheck | ActionType::Confirm => &["message"],
            ActionType::CheckValue => &["actual", "expected", "message", "sensitive"],
            ActionType::OralReadback => &["value", "format", "characters", "sensitive", "message"],
            ActionType::MachineInfo => &[
                "include_machine_id",
                "include_cpu",
                "include_os",
                "include_security_features",
                "message",
            ],
            ActionType::GenerateKey => &["algorithm", "policy", "slot"],
            ActionType::WrapKey => &["scheme", "expect_recipient"],
            ActionType::UnwrapKey => &["algorithm", "expect_key", "label", "policy"],
            ActionType::SignData | ActionType::VerifySignature => &["algorithm", "message"],
            ActionType::Attest => &["statement"],
            ActionType::GatherEntropy => &["instruction"],
            ActionType::IssueCertificate => &["profile", "validity_days", "issuer_cn", "path_len"],
            ActionType::GenerateCsr => &["subject", "san"],
            ActionType::PivReadCertificate | ActionType::YubikeyAttestSlot => &["slot", "message"],
            ActionType::PivSign => &["slot", "algorithm", "message"],
            // `export_public` takes its inputs through `reads:` alone, and
            // `tpm_attest` has no handler in any build yet, so neither has a
            // `with:` shape to accept. For the second, `unsupported_actions`
            // is what reports the step itself.
            ActionType::ExportPublic | ActionType::TpmAttest => &[],
        }
    }

    /// Returns the `reads:` inputs this action requires, and the groups from
    /// which exactly one input must be named.
    ///
    /// A group is how an action offers two paths over the same operation. The
    /// input the author names selects the path, so naming both is ambiguous and
    /// naming neither leaves the path undetermined. The resolver reports either
    /// on the step.
    pub fn reads_contract(self) -> ReadsContract {
        match self {
            ActionType::WrapKey => ReadsContract {
                required: &["key_to_wrap"],
                exactly_one_of: &[&["wrapping_key", "recipient"]],
                // `expect_recipient` is compared against the recipient a wrap
                // is given, and only the external path has one.
                with_field_requires: &[("expect_recipient", "recipient")],
            },
            ActionType::UnwrapKey => ReadsContract::required(&["unwrapping_key", "wrapped_data"]),
            ActionType::SignData => ReadsContract::required(&["key", "data"]),
            ActionType::VerifySignature => ReadsContract::required(&["key", "data", "signature"]),
            ActionType::IssueCertificate => ReadsContract::required(&["signing_key", "csr"]),
            ActionType::GenerateCsr => ReadsContract::required(&["signing_key"]),

            ActionType::ClockCheck
            | ActionType::Confirm
            | ActionType::CheckValue
            | ActionType::OralReadback
            | ActionType::MachineInfo
            | ActionType::GenerateKey
            | ActionType::ExportPublic
            | ActionType::Attest
            | ActionType::GatherEntropy
            | ActionType::TpmAttest
            | ActionType::PivReadCertificate
            | ActionType::PivSign
            | ActionType::YubikeyAttestSlot => ReadsContract::NONE,
        }
    }

    /// Short human-readable description of what this action does.
    ///
    /// Used as fallback prose in script generation, TUI step display, and LSP
    /// hover when no explicit `description` or `message` parameter is present.
    pub fn describe(&self) -> &'static str {
        match self {
            ActionType::ClockCheck => "Verify system clock against a reference time.",
            ActionType::Confirm => "Confirm readiness or completion of a manual step.",
            ActionType::CheckValue => "Verify a value matches an expected result.",
            ActionType::OralReadback => "Read back a value aloud for verification.",
            ActionType::MachineInfo => "Record system and environment information.",
            ActionType::Attest => "Record a signed attestation from a participant.",
            ActionType::GatherEntropy => "Fold human-supplied entropy into the ceremony seed.",
            ActionType::TpmAttest => "Record TPM platform attestation (PCR values).",
            ActionType::GenerateKey => "Generate a cryptographic key.",
            ActionType::ExportPublic => "Export the public component of a keypair.",
            ActionType::SignData => "Sign data with a ceremony key.",
            ActionType::VerifySignature => "Verify a signature against a public key.",
            ActionType::WrapKey => "Encrypt a key under another key for transport.",
            ActionType::UnwrapKey => "Decrypt a wrapped key and import it into a backend.",
            ActionType::GenerateCsr => "Generate a Certificate Signing Request.",
            ActionType::IssueCertificate => "Issue an X.509 certificate from a CSR.",
            ActionType::PivReadCertificate => "Read a certificate from a PIV smart card slot.",
            ActionType::PivSign => "Sign data using a PIV smart card key.",
            ActionType::YubikeyAttestSlot => "Attest a YubiKey PIV slot key.",
        }
    }
}

impl std::fmt::Display for ActionType {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            ActionType::ClockCheck => write!(f, "clock_check"),
            ActionType::Confirm => write!(f, "confirm"),
            ActionType::CheckValue => write!(f, "check_value"),
            ActionType::OralReadback => write!(f, "oral_readback"),
            ActionType::MachineInfo => write!(f, "machine_info"),
            ActionType::GenerateKey => write!(f, "generate_key"),
            ActionType::WrapKey => write!(f, "wrap_key"),
            ActionType::UnwrapKey => write!(f, "unwrap_key"),
            ActionType::ExportPublic => write!(f, "export_public"),
            ActionType::SignData => write!(f, "sign_data"),
            ActionType::VerifySignature => write!(f, "verify_signature"),
            ActionType::Attest => write!(f, "attest"),
            ActionType::GatherEntropy => write!(f, "gather_entropy"),
            ActionType::TpmAttest => write!(f, "tpm_attest"),
            ActionType::PivReadCertificate => write!(f, "piv_read_certificate"),
            ActionType::PivSign => write!(f, "piv_sign"),
            ActionType::YubikeyAttestSlot => write!(f, "yubikey_attest_slot"),
            ActionType::IssueCertificate => write!(f, "issue_certificate"),
            ActionType::GenerateCsr => write!(f, "generate_csr"),
        }
    }
}

/// Type of output produced by a ceremony.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
#[non_exhaustive]
pub enum OutputType {
    /// Public key in PEM format.
    PublicKey,
    /// A key wrapped for transport, in the container its scheme names.
    WrappedKey,
    /// X.509 certificate.
    Certificate,
    /// DNSSEC signed resource record set.
    SignedRrset,
    /// Certificate Transparency Signed Certificate Timestamp.
    Sct,

    // Documents
    /// Generic document.
    Document,
    /// Ceremony log or transcript.
    CeremonyLog,
}

impl std::fmt::Display for OutputType {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            OutputType::PublicKey => write!(f, "public_key"),
            OutputType::WrappedKey => write!(f, "wrapped_key"),
            OutputType::Certificate => write!(f, "certificate"),
            OutputType::SignedRrset => write!(f, "signed_rrset"),
            OutputType::Sct => write!(f, "sct"),
            OutputType::Document => write!(f, "document"),
            OutputType::CeremonyLog => write!(f, "ceremony_log"),
        }
    }
}

impl OutputType {
    /// Returns the default file extension for this output type.
    pub fn default_extension(&self) -> &'static str {
        match self {
            OutputType::PublicKey | OutputType::Certificate => "pem",
            OutputType::WrappedKey | OutputType::SignedRrset | OutputType::Sct => "bin",
            OutputType::Document => "txt",
            OutputType::CeremonyLog => "json",
        }
    }
}

/// Type of a ceremony parameter.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
#[non_exhaustive]
pub enum ParameterType {
    /// Text value.
    String,
    /// Date value (`YYYY-MM-DD`).
    Date,
    /// Integer value.
    Integer,
    /// Boolean value.
    Boolean,
}

impl std::fmt::Display for ParameterType {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            ParameterType::String => write!(f, "string"),
            ParameterType::Date => write!(f, "date (YYYY-MM-DD)"),
            ParameterType::Integer => write!(f, "integer"),
            ParameterType::Boolean => write!(f, "boolean (true/false)"),
        }
    }
}

/// Typed preset for common post-ceremony duty categories.
///
/// Provides built-in prose for scripts when no description is given.
/// Use `Custom` for duties that don't fit a preset; description is then required.
///
/// Note: physical handling steps (sealing hardware, etc.) belong as `physical_action`
/// steps in ceremony execution, not here.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
#[serde(rename_all = "snake_case")]
#[non_exhaustive]
pub enum DutyType {
    /// Return materials to secure storage location.
    ReturnToVault,
    /// Hand key shares to assigned custodians.
    DistributeShares,
    /// Distribute backup media to designated recipients.
    DistributeMedia,
    /// Archive ceremony materials at storage locations.
    ArchiveMaterials,
    /// Publish ceremony record and witness attestations.
    PublishRecord,
    /// Notify stakeholders of ceremony completion.
    NotifyStakeholders,
    /// Import generated keys into operational system.
    ImportKeys,
    /// Free-form duty; description is required.
    Custom,
}

impl DutyType {
    /// Returns the built-in display name for this duty type.
    pub fn display_name(&self) -> &'static str {
        match self {
            DutyType::ReturnToVault => "Return to Vault",
            DutyType::DistributeShares => "Distribute Key Shares",
            DutyType::DistributeMedia => "Distribute Backup Media",
            DutyType::ArchiveMaterials => "Archive Materials",
            DutyType::PublishRecord => "Publish Record",
            DutyType::NotifyStakeholders => "Notify Stakeholders",
            DutyType::ImportKeys => "Import Keys",
            DutyType::Custom => "Custom Duty",
        }
    }

    /// Returns the built-in prose description for this duty type.
    ///
    /// Returns `None` for `Custom` (description must be provided explicitly).
    pub fn built_in_prose(&self) -> Option<&'static str> {
        match self {
            DutyType::ReturnToVault => Some("Return materials to secure storage"),
            DutyType::DistributeShares => Some("Distribute key shares to assigned custodians"),
            DutyType::DistributeMedia => Some("Distribute backup media to designated recipients"),
            DutyType::ArchiveMaterials => {
                Some("Archive ceremony materials at designated storage locations")
            }
            DutyType::PublishRecord => Some("Publish ceremony record and witness attestations"),
            DutyType::NotifyStakeholders => Some("Notify stakeholders of ceremony completion"),
            DutyType::ImportKeys => Some("Import generated keys into operational system"),
            DutyType::Custom => None,
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn role_type_extracts_prefix() {
        assert_eq!(role_type("witness__1"), "witness");
        assert_eq!(role_type("hsm_operator__primary"), "hsm_operator");
        assert_eq!(role_type("operator"), "operator");
        assert_eq!(role_type("witness__"), "witness");
    }

    #[test]
    fn derive_step_name_title_cases() {
        assert_eq!(derive_step_name("verify_time"), "Verify Time");
        assert_eq!(derive_step_name("generate_root_ca"), "Generate Root Ca");
        assert_eq!(derive_step_name("wrap_root_ca_key"), "Wrap Root Ca Key");
        assert_eq!(derive_step_name("witness1_attest"), "Witness1 Attest");
        assert_eq!(derive_step_name("clock-check"), "Clock Check");
        assert_eq!(derive_step_name("opening"), "Opening");
    }

    #[test]
    fn derive_role_name_title_cases() {
        assert_eq!(derive_role_name("witness__1"), "Witness 1");
        assert_eq!(
            derive_role_name("hsm_operator__primary"),
            "Hsm Operator Primary"
        );
        assert_eq!(derive_role_name("operator"), "Operator");
        assert_eq!(derive_role_name("ceremony-admin"), "Ceremony Admin");
    }

    #[test]
    fn action_type_serde_roundtrip() {
        // `snake_case` rename means these exact strings appear in ceremony YAML.
        // A variant rename or serde attr change breaks YAML parsing silently.
        let cases: &[(ActionType, &str)] = &[
            (ActionType::ClockCheck, "\"clock_check\""),
            (ActionType::Confirm, "\"confirm\""),
            (ActionType::CheckValue, "\"check_value\""),
            (ActionType::OralReadback, "\"oral_readback\""),
            (ActionType::MachineInfo, "\"machine_info\""),
            (ActionType::GenerateKey, "\"generate_key\""),
            (ActionType::WrapKey, "\"wrap_key\""),
            (ActionType::UnwrapKey, "\"unwrap_key\""),
            (ActionType::ExportPublic, "\"export_public\""),
            (ActionType::Attest, "\"attest\""),
            (ActionType::TpmAttest, "\"tpm_attest\""),
            (ActionType::PivReadCertificate, "\"piv_read_certificate\""),
            (ActionType::PivSign, "\"piv_sign\""),
            (ActionType::YubikeyAttestSlot, "\"yubikey_attest_slot\""),
            (ActionType::IssueCertificate, "\"issue_certificate\""),
            (ActionType::GenerateCsr, "\"generate_csr\""),
        ];
        for &(variant, expected) in cases {
            let serialized = serde_json::to_string(&variant).unwrap();
            assert_eq!(serialized, expected, "serialize {variant:?}");
            let deserialized: ActionType = serde_json::from_str(expected).unwrap();
            assert_eq!(deserialized, variant, "deserialize {expected}");
        }
    }

    #[test]
    fn action_type_display_matches_serde() {
        // Display is used in transcript output and error messages; serde in YAML parsing.
        // They must agree or transcripts reference action names that differ from YAML.
        let actions = [
            ActionType::ClockCheck,
            ActionType::Confirm,
            ActionType::CheckValue,
            ActionType::OralReadback,
            ActionType::MachineInfo,
            ActionType::GenerateKey,
            ActionType::WrapKey,
            ActionType::UnwrapKey,
            ActionType::ExportPublic,
            ActionType::Attest,
            ActionType::TpmAttest,
            ActionType::PivReadCertificate,
            ActionType::PivSign,
            ActionType::YubikeyAttestSlot,
            ActionType::IssueCertificate,
            ActionType::GenerateCsr,
        ];
        for action in actions {
            let display = action.to_string();
            let serde_json = serde_json::to_string(&action).unwrap();
            assert_eq!(
                display,
                serde_json.trim_matches('"'),
                "Display and serde disagree for {action:?}"
            );
        }
    }

    #[test]
    fn output_type_serde_roundtrip() {
        // These strings appear in ceremony YAML `output:` blocks and in file extension
        // mapping. A rename breaks both YAML parsing and output file naming.
        let cases: &[(OutputType, &str)] = &[
            (OutputType::PublicKey, "\"public_key\""),
            (OutputType::WrappedKey, "\"wrapped_key\""),
            (OutputType::Certificate, "\"certificate\""),
            (OutputType::Document, "\"document\""),
            (OutputType::CeremonyLog, "\"ceremony_log\""),
        ];
        for &(variant, expected) in cases {
            let serialized = serde_json::to_string(&variant).unwrap();
            assert_eq!(serialized, expected, "serialize {variant:?}");
            let deserialized: OutputType = serde_json::from_str(expected).unwrap();
            assert_eq!(deserialized, variant, "deserialize {expected}");
        }
    }

    #[test]
    fn parameter_type_serde_roundtrip() {
        // These strings appear in ceremony YAML `parameters:` blocks.
        let cases: &[(ParameterType, &str)] = &[
            (ParameterType::String, "\"string\""),
            (ParameterType::Date, "\"date\""),
            (ParameterType::Integer, "\"integer\""),
            (ParameterType::Boolean, "\"boolean\""),
        ];
        for (variant, expected) in cases {
            let serialized = serde_json::to_string(variant).unwrap();
            assert_eq!(serialized, *expected, "serialize {variant:?}");
            let deserialized: ParameterType = serde_json::from_str(expected).unwrap();
            // ParameterType does not implement PartialEq; check the display instead.
            assert_eq!(
                serde_json::to_string(&deserialized).unwrap(),
                *expected,
                "deserialize {expected}"
            );
        }
    }

    #[test]
    fn duty_type_serde_roundtrip() {
        // These strings appear in ceremony YAML `after:` blocks.
        let cases: &[(DutyType, &str)] = &[
            (DutyType::ReturnToVault, "\"return_to_vault\""),
            (DutyType::DistributeShares, "\"distribute_shares\""),
            (DutyType::DistributeMedia, "\"distribute_media\""),
            (DutyType::ArchiveMaterials, "\"archive_materials\""),
            (DutyType::PublishRecord, "\"publish_record\""),
            (DutyType::NotifyStakeholders, "\"notify_stakeholders\""),
            (DutyType::ImportKeys, "\"import_keys\""),
            (DutyType::Custom, "\"custom\""),
        ];
        for (variant, expected) in cases {
            let serialized = serde_json::to_string(variant).unwrap();
            assert_eq!(serialized, *expected, "serialize {variant:?}");
            let deserialized: DutyType = serde_json::from_str(expected).unwrap();
            assert_eq!(deserialized, *variant, "deserialize {expected}");
        }
    }

    #[test]
    fn duty_type_custom_has_no_built_in_prose() {
        // The runtime branches on this: if built_in_prose returns None, the description
        // field is required. A regression here would panic or produce empty script output.
        assert!(
            DutyType::Custom.built_in_prose().is_none(),
            "Custom duty must have no built-in prose"
        );
        // All other variants must have prose.
        for duty in [
            DutyType::ReturnToVault,
            DutyType::DistributeShares,
            DutyType::DistributeMedia,
            DutyType::ArchiveMaterials,
            DutyType::PublishRecord,
            DutyType::NotifyStakeholders,
            DutyType::ImportKeys,
        ] {
            assert!(
                duty.built_in_prose().is_some(),
                "{duty:?} must have built-in prose"
            );
        }
    }

    /// `ActionType::ALL` is written by hand, so it can fall behind the enum.
    ///
    /// The match below is exhaustive, so adding a variant fails to compile
    /// here. That is the whole mechanism: it puts a compiler error next to the
    /// list an author has to extend. The name check then catches a variant
    /// listed twice, and `rite-ls` compares its own catalogue against `ALL`,
    /// which is what catches one left out.
    /// A required field the action does not accept would be reported as
    /// unknown, which is the opposite of the message intended, and nothing
    /// makes the two lists agree on their own.
    #[test]
    fn every_required_field_is_also_a_known_field() {
        for action in ActionType::ALL {
            let known = action.known_with_fields();
            for field in action.required_with_fields() {
                assert!(
                    known.contains(field),
                    "{action} requires '{field}' and does not accept it"
                );
            }
        }
    }

    #[test]
    fn all_lists_every_action_type() {
        for action in ActionType::ALL {
            match action {
                ActionType::ClockCheck
                | ActionType::Confirm
                | ActionType::CheckValue
                | ActionType::OralReadback
                | ActionType::MachineInfo
                | ActionType::GenerateKey
                | ActionType::WrapKey
                | ActionType::UnwrapKey
                | ActionType::ExportPublic
                | ActionType::SignData
                | ActionType::VerifySignature
                | ActionType::Attest
                | ActionType::GatherEntropy
                | ActionType::TpmAttest
                | ActionType::PivReadCertificate
                | ActionType::PivSign
                | ActionType::YubikeyAttestSlot
                | ActionType::IssueCertificate
                | ActionType::GenerateCsr => {}
            }
        }

        let names: std::collections::BTreeSet<String> =
            ActionType::ALL.iter().map(ToString::to_string).collect();
        assert_eq!(
            names.len(),
            ActionType::ALL.len(),
            "two actions share a DSL name"
        );
    }
}