vti-voting 0.9.0

//! What a manifest must say and what a ballot may answer: the rules JSON Schema cannot state,
//! as checks over the generated wire types.
//!
//! The schema already holds every shape; these hold the relations between fields — that a
//! manifest's times are in order, that a choice's bounds fit its options, that a ballot answers
//! each question exactly once and only as its question admits. A ballot box runs
//! [`check_manifest`] at registration and [`check_ballot`] before the pairing check of every
//! cast (VTI-VOT-045); a VTA runs [`check_ballot`] before it builds a cast (VTI-VOT-032).
//!
//! Received JSON is read against the schema before it is parsed into these types; the
//! cross-field rules here assume a document that already passed it.

use std::collections::HashSet;

use sha2::{Digest, Sha256};
use vti_specs::voting::{
    ballot::cast::v0_1::{Answer, Ballot},
    election::register::v0_4::{Manifest, Question, RollRuleRule, SecrecyLevel},
};

/// A broken rule. Each variant is one error local part of the voting families.
#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
#[non_exhaustive]
pub enum RuleError {
    /// `invalidManifest`.
    #[error("invalid manifest: {0}")]
    InvalidManifest(String),
    /// `unsupportedSecrecy`: version 0.1 serves open elections only.
    #[error("secrecy level {0} is not served by this version")]
    UnsupportedSecrecy(String),
    /// `manifestMismatch`.
    #[error("the ballot names another election or manifest")]
    ManifestMismatch,
    /// `ballotInvalid`.
    #[error("invalid ballot: {0}")]
    BallotInvalid(String),
    #[error("serialization: {0}")]
    Serialization(String),
}

/// The members a manifest registered under `voting/election/register/0.1` (voting/_shared/0.1)
/// named its instants by, renamed `…At` in voting/_shared/0.2.
const V0_1_INSTANTS: [&str; 3] = ["registrationOpens", "votingOpens", "votingCloses"];

/// Refuse a manifest in the shape of `voting/election/register/0.1`.
///
/// Every party now reads only the 0.2 manifest. One registered under 0.1 cannot be read as
/// 0.2: its digest — which every ticket, ballot and certification is bound to — is over its
/// 0.1 member names, so renaming them would make it a different election. It is refused by
/// name instead of failing as a manifest missing `registrationOpensAt`.
///
/// # Errors
/// [`RuleError::InvalidManifest`] naming the election and what to do.
pub fn require_current_manifest(manifest: &serde_json::Value) -> Result<(), RuleError> {
    if V0_1_INSTANTS.iter().any(|k| manifest.get(k).is_some()) {
        let id = manifest
            .get("electionId")
            .and_then(serde_json::Value::as_str)
            .unwrap_or("(unnamed)");
        return Err(RuleError::InvalidManifest(format!(
            "election {id} was registered under voting/election/register/0.1 (its manifest \
             names registrationOpens, votingOpens and votingCloses); this build reads only \
             the 0.2 manifest and cannot carry it over. Finish or cancel it on the previous \
             release, or remove it"
        )));
    }
    Ok(())
}

/// Why a board entry written under `voting/board/read/0.1` cannot be served or audited, if it is
/// one: a lifecycle entry (`opened`, `closed`, `closedEarly`, `cancelled`) naming its instant `at`
/// (voting/_shared/0.1) where voting/_shared/0.2 names it `occurredAt`.
///
/// The leaf hash is over the entry's member names, so renaming it would change the board's root
/// and break every receipt and checkpoint already issued against it. It is refused by name
/// instead.
pub(crate) fn v0_1_lifecycle_entry(index: u64, entry: &serde_json::Value) -> Option<String> {
    let lifecycle = matches!(
        entry.get("kind").and_then(serde_json::Value::as_str),
        Some("opened" | "closed" | "closedEarly" | "cancelled")
    );
    (lifecycle && entry.get("at").is_some() && entry.get("occurredAt").is_none()).then(|| {
        format!(
            "board entry {index} names its instant `at` (voting/board/read/0.1); this build \
             serves and reads only voting/board/read/0.2, whose lifecycle entries name it \
             `occurredAt`, and cannot rename it without changing the board. Finish or cancel \
             the election on the previous release, or remove it"
        )
    })
}

/// SHA-256 of the manifest's RFC 8785 (JCS) canonicalization, over the JSON as received.
///
/// # Errors
/// [`RuleError::Serialization`] if the value cannot be canonicalized.
pub fn manifest_digest(manifest: &serde_json::Value) -> Result<[u8; 32], RuleError> {
    let jcs = serde_json_canonicalizer::to_vec(manifest)
        .map_err(|e| RuleError::Serialization(e.to_string()))?;
    Ok(Sha256::digest(jcs).into())
}

/// A SHA-256 digest as the wire carries it: a multihash (`0x12 0x20 ‖ digest`), multibase
/// base58btc.
pub fn digest_multibase(digest: &[u8; 32]) -> String {
    let mut mh = Vec::with_capacity(34);
    mh.extend([0x12, 0x20]);
    mh.extend(digest);
    multibase::encode(multibase::Base::Base58Btc, mh)
}

/// The raw digest of a [`digest_multibase`] value, if it is one.
pub fn digest_from_multibase(text: &str) -> Option<[u8; 32]> {
    let (_, bytes) = multibase::decode(text).ok()?;
    match bytes.as_slice() {
        [0x12, 0x20, rest @ ..] => rest.try_into().ok(),
        _ => None,
    }
}

/// The question's key, or `None` for a question type this version does not know: the
/// generated enum grows with the specification, and an unknown type is refused, never guessed.
pub(crate) fn key(q: &Question) -> Option<&str> {
    match q {
        Question::Choice { key, .. }
        | Question::Ranking { key, .. }
        | Question::Score { key, .. }
        | Question::Text { key, .. } => Some(key.as_str()),
        _ => None,
    }
}

fn optional(q: &Question) -> bool {
    match q {
        Question::Choice { optional, .. }
        | Question::Ranking { optional, .. }
        | Question::Score { optional, .. }
        | Question::Text { optional, .. } => *optional,
        _ => false,
    }
}

pub(crate) fn option_keys(q: &Question) -> Vec<&str> {
    match q {
        Question::Choice { options, .. }
        | Question::Ranking { options, .. }
        | Question::Score { options, .. } => options.iter().map(|o| o.key.as_str()).collect(),
        _ => Vec::new(),
    }
}

fn bad_manifest(why: impl Into<String>) -> RuleError {
    RuleError::InvalidManifest(why.into())
}

/// The most trustees an election may have (`TrusteeIndex` runs 1..=64).
pub const MAX_TRUSTEES: usize = 64;

/// The trustee rules of a sealed or tallied-encrypted manifest (VTI-VOT-060 – 064): trustees
/// named, `2 <= threshold <= n <= 64`, neither the community nor the ballot box among them, no
/// running totals, and — tallied-encrypted — choice questions only.
fn check_trustees(m: &Manifest) -> Result<(), RuleError> {
    let Some(t) = &m.trustees else {
        return Err(bad_manifest(
            "a sealed or tallied-encrypted election names its trustees",
        ));
    };
    let n = t.dids.len();
    if n > MAX_TRUSTEES {
        return Err(bad_manifest(format!(
            "at most {MAX_TRUSTEES} trustees, not {n}"
        )));
    }
    if t.threshold < 2 || t.threshold > n as i64 {
        return Err(bad_manifest(
            "the trustees' threshold must satisfy 2 <= threshold <= trustees",
        ));
    }
    if t.dids
        .iter()
        .map(|d| d.as_str())
        .collect::<HashSet<_>>()
        .len()
        != n
    {
        return Err(bad_manifest("a trustee is named twice"));
    }
    if t.dids
        .iter()
        .any(|d| d.as_str() == m.community.as_str() || d.as_str() == m.ballot_box.as_str())
    {
        return Err(bad_manifest(
            "neither the community nor the ballot box is a trustee",
        ));
    }
    if m.results_before_close {
        return Err(bad_manifest(
            "running totals are an open election's alone (VTI-VOT-061)",
        ));
    }
    if m.secrecy == SecrecyLevel::TalliedEncrypted
        && m.questions
            .iter()
            .any(|q| !matches!(q, Question::Choice { .. }))
    {
        return Err(bad_manifest(
            "a tallied-encrypted election asks choice questions only (VTI-VOT-064)",
        ));
    }
    Ok(())
}

/// The secrecy levels served: all three. The encrypted levels are served end to end — the
/// trustees' ceremony and encrypted casts at the ballot box ([`crate::service`]), their
/// certification ([`crate::audit`]) — so a ballot box registers them and a VTC creates them.
/// `unsupportedSecrecy` remains for a level a service built from this crate would not serve.
pub const SERVED_LEVELS: &[SecrecyLevel] = &[
    SecrecyLevel::Open,
    SecrecyLevel::Sealed,
    SecrecyLevel::TalliedEncrypted,
];

/// A manifest's cross-field rules (VTI-VOT-010), as a ballot box checks it at registration and
/// a VTC at creation. `ballot_box` is the checking service's own DID, when it is one.
///
/// # Errors
/// [`RuleError::UnsupportedSecrecy`] for a level not in [`SERVED_LEVELS`]; otherwise
/// [`RuleError::InvalidManifest`] naming the first rule broken.
pub fn check_manifest(m: &Manifest, ballot_box: Option<&str>) -> Result<(), RuleError> {
    check_manifest_serving(m, ballot_box, SERVED_LEVELS)
}

/// [`check_manifest`] for a service serving `served`.
///
/// # Errors
/// As [`check_manifest`].
pub fn check_manifest_serving(
    m: &Manifest,
    ballot_box: Option<&str>,
    served: &[SecrecyLevel],
) -> Result<(), RuleError> {
    if !served.contains(&m.secrecy) {
        return Err(RuleError::UnsupportedSecrecy(m.secrecy.to_string()));
    }
    if m.secrecy == SecrecyLevel::Open {
        if m.trustees.is_some() {
            return Err(bad_manifest("an open election has no trustees"));
        }
    } else {
        check_trustees(m)?;
    }
    if !(m.registration_opens_at <= m.voting_opens_at && m.voting_opens_at < m.voting_closes_at) {
        return Err(bad_manifest(
            "the times must satisfy registrationOpensAt <= votingOpensAt < votingClosesAt",
        ));
    }
    if let Some(own) = ballot_box
        && m.ballot_box.as_str() != own
    {
        return Err(bad_manifest("ballotBox names another service"));
    }
    // VTI-VOT-065: at least 1 (the generated type is non-zero, so the schema's `minimum`
    // already holds it); below the SHOULD of 10 the member is told before taking a ticket
    // (VTI-VOT-090), which the disclosure derives from the manifest. A manifest received
    // under a version whose schema says 10 was refused by that schema before it got here.
    let listed = m.roll.listed.as_ref().map_or(0, Vec::len);
    match m.roll.rule {
        RollRuleRule::Listed | RollRuleRule::MembersAndListed if listed == 0 => {
            return Err(bad_manifest(
                "a roll that lists parties must list at least one",
            ));
        }
        RollRuleRule::Members if listed != 0 => {
            return Err(bad_manifest("a members-only roll lists nobody"));
        }
        // VTI-VOT-025, VTI-VOT-026: a credential roll names exactly one DID and lists nobody.
        // The schema states both; they are held here too, as every rule the relation needs.
        RollRuleRule::Credential if m.roll.member_of.is_none() => {
            return Err(bad_manifest("a credential roll names the DID in memberOf"));
        }
        RollRuleRule::Credential if listed != 0 => {
            return Err(bad_manifest("a credential roll lists nobody"));
        }
        _ => {}
    }
    if m.roll.member_of.is_some() && m.roll.rule != RollRuleRule::Credential {
        return Err(bad_manifest("only a credential roll names memberOf"));
    }
    if m.board
        .auditors
        .iter()
        .any(|a| a.as_str() == m.community.as_str() || a.as_str() == m.ballot_box.as_str())
    {
        return Err(bad_manifest(
            "neither the community nor the ballot box audits its own election",
        ));
    }
    let mut seen = HashSet::new();
    for q in &m.questions {
        let Some(k) = key(q) else {
            return Err(bad_manifest(
                "a question of a type this version does not serve",
            ));
        };
        if !seen.insert(k) {
            return Err(bad_manifest(format!("question key {k} repeats")));
        }
        let opts = option_keys(q);
        if opts.iter().collect::<HashSet<_>>().len() != opts.len() {
            return Err(bad_manifest(format!("question {k} repeats an option key")));
        }
        match q {
            Question::Choice {
                min_selections,
                max_selections,
                options,
                ..
            } => {
                let max = max_selections.get();
                if *min_selections > max || max > options.len() as u64 {
                    return Err(bad_manifest(format!(
                        "question {k}: minSelections <= maxSelections <= options"
                    )));
                }
            }
            Question::Score { min, max, .. } if min >= max => {
                return Err(bad_manifest(format!("question {k}: min < max")));
            }
            _ => {}
        }
    }
    Ok(())
}

/// A manifest as received, checked as a community checks one it is asked to create
/// (`vtc/elections/create`): the current 0.2 shape ([`require_current_manifest`]), its typed
/// form, [`check_manifest`], and voting not already closed at `now`.
///
/// Everything a community checks that needs nothing but the manifest and the clock — what is
/// left needs the community itself: that `community` is its DID, that `ballotBox` is one of its
/// trusted voting services (VTI-VOT-082), and that `electionId` is unused. The VTC runs it on
/// every create; an operator's tool can run it offline first (`cnm elections manifest check`).
/// The caller validates `manifest` against the schema first.
///
/// # Errors
/// As [`check_manifest`]; [`RuleError::InvalidManifest`] for a 0.1 manifest, one that does not
/// parse, or one whose voting has already closed.
pub fn check_new_manifest(
    manifest: &serde_json::Value,
    now: chrono::DateTime<chrono::Utc>,
) -> Result<Manifest, RuleError> {
    require_current_manifest(manifest)?;
    let m: Manifest =
        serde_json::from_value(manifest.clone()).map_err(|e| bad_manifest(e.to_string()))?;
    check_manifest(&m, None)?;
    if m.voting_closes_at <= now {
        return Err(bad_manifest("votingClosesAt is already past"));
    }
    Ok(m)
}

fn bad_ballot(why: impl Into<String>) -> RuleError {
    RuleError::BallotInvalid(why.into())
}

/// How many answer members an answer carries. Exactly one is admitted; the schema states it as
/// `minProperties`/`maxProperties`, which the generated type cannot.
fn members(a: &Answer) -> usize {
    usize::from(a.choice.is_some())
        + usize::from(a.ranking.is_some())
        + usize::from(!a.scores.is_empty())
        + usize::from(a.text.is_some())
        + usize::from(a.abstain.is_some())
}

/// A ballot against the manifest it was cast under (VTI-VOT-032, VTI-VOT-045).
/// `manifest_digest` is the registered manifest's.
///
/// # Errors
/// [`RuleError::ManifestMismatch`] if the ballot names another election or manifest;
/// [`RuleError::BallotInvalid`] naming the first rule broken.
pub fn check_ballot(m: &Manifest, manifest_digest: &[u8; 32], b: &Ballot) -> Result<(), RuleError> {
    if b.election_id.as_str() != m.election_id.as_str()
        || digest_from_multibase(b.manifest_digest.as_str()).as_ref() != Some(manifest_digest)
    {
        return Err(RuleError::ManifestMismatch);
    }
    let mut answered = HashSet::new();
    for a in &b.answers {
        let qkey = a.question.as_str();
        let Some(q) = m.questions.iter().find(|q| key(q) == Some(qkey)) else {
            return Err(bad_ballot(format!("no question {qkey}")));
        };
        if !answered.insert(qkey) {
            return Err(bad_ballot(format!("question {qkey} answered twice")));
        }
        if members(a) != 1 {
            return Err(bad_ballot(format!(
                "question {qkey}: exactly one answer member"
            )));
        }
        if a.abstain.is_some() {
            if a.abstain != Some(serde_json::Value::Bool(true)) {
                return Err(bad_ballot(format!("question {qkey}: abstain is true")));
            }
            if !optional(q) {
                return Err(bad_ballot(format!(
                    "question {qkey} may not be left unanswered"
                )));
            }
            continue;
        }
        let opts: HashSet<&str> = option_keys(q).into_iter().collect();
        match q {
            Question::Choice {
                min_selections,
                max_selections,
                ..
            } => {
                let Some(choice) = &a.choice else {
                    return Err(bad_ballot(format!("question {qkey} takes a choice")));
                };
                let n = choice.len() as u64;
                if n < *min_selections || n > max_selections.get() {
                    return Err(bad_ballot(format!("question {qkey}: selection count")));
                }
                if choice.iter().collect::<HashSet<_>>().len() != choice.len()
                    || choice.iter().any(|k| !opts.contains(k.as_str()))
                {
                    return Err(bad_ballot(format!(
                        "question {qkey}: unknown or repeated option"
                    )));
                }
            }
            Question::Ranking { partial, .. } => {
                let Some(ranking) = &a.ranking else {
                    return Err(bad_ballot(format!("question {qkey} takes a ranking")));
                };
                let distinct = ranking.iter().collect::<HashSet<_>>().len() == ranking.len();
                let known = ranking.iter().all(|k| opts.contains(k.as_str()));
                let complete = if *partial {
                    !ranking.is_empty()
                } else {
                    ranking.len() == opts.len()
                };
                if !(distinct && known && complete) {
                    return Err(bad_ballot(format!("question {qkey}: ranking")));
                }
            }
            Question::Score { min, max, .. } => {
                let scored: HashSet<&str> = a.scores.keys().map(|k| k.as_str()).collect();
                if scored != opts {
                    return Err(bad_ballot(format!("question {qkey}: score every option")));
                }
                if a.scores.values().any(|v| v < min || v > max) {
                    return Err(bad_ballot(format!("question {qkey}: score out of bounds")));
                }
            }
            Question::Text { max_length, .. } => {
                let Some(text) = &a.text else {
                    return Err(bad_ballot(format!("question {qkey} takes text")));
                };
                if text.as_str().chars().count() as u64 > max_length.get() {
                    return Err(bad_ballot(format!("question {qkey}: text too long")));
                }
            }
            _ => return Err(bad_ballot(format!("question {qkey}: unsupported type"))),
        }
    }
    if let Some(q) = m
        .questions
        .iter()
        .find(|q| key(q).is_none_or(|k| !answered.contains(k)))
    {
        return Err(bad_ballot(format!(
            "question {} unanswered (an optional question is answered with abstain)",
            key(q).unwrap_or("?")
        )));
    }
    Ok(())
}

#[cfg(test)]
mod tests {
    use serde_json::json;

    use super::v0_1_lifecycle_entry;

    /// A lifecycle entry written under `voting/board/read/0.1` (`at`) is refused by name; one
    /// written under 0.2 (`occurredAt`), and every other kind, is read.
    #[test]
    fn a_0_1_lifecycle_entry_is_refused_by_name() {
        let old = json!({ "kind": "opened", "at": "2026-11-09T09:00:00Z" });
        assert!(v0_1_lifecycle_entry(3, &old).is_some_and(|why| why.contains("board entry 3")));
        let new = json!({ "kind": "closed", "occurredAt": "2026-11-09T09:00:00Z" });
        assert!(v0_1_lifecycle_entry(0, &new).is_none());
        let cast = json!({ "kind": "cast", "cast": {} });
        assert!(v0_1_lifecycle_entry(0, &cast).is_none());
    }
}