auths_keri/

events.rs

//! Canonical KERI event types: Inception (ICP), Rotation (ROT), Interaction (IXN).
//!
//! These types are the single authoritative definition of KERI events for the
//! entire workspace. All other crates import from here.

use serde::ser::SerializeMap;
use serde::{Deserialize, Serialize, Serializer};
use std::fmt;

use crate::capability::Capability;
use crate::types::{CesrKey, ConfigTrait, Prefix, Said, Threshold, VersionString};

/// KERI protocol version prefix string.
pub const KERI_VERSION_PREFIX: &str = "KERI10JSON";

// ── KeriSequence ─────────────────────────────────────────────────────────────

/// A KERI sequence number, stored internally as u64 and serialized as a hex string.
///
/// Sequence numbers are spec-compliant hex strings: "0", "1", "a", "ff", etc.
///
/// Usage:
/// ```ignore
/// let seq = KeriSequence::new(10);
/// assert_eq!(seq.value(), 10);
/// assert_eq!(serde_json::to_string(&seq).unwrap(), "\"a\"");
/// ```
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct KeriSequence(u128);

#[cfg(feature = "schema")]
impl schemars::JsonSchema for KeriSequence {
    fn schema_name() -> String {
        "KeriSequence".to_string()
    }

    fn json_schema(_gen: &mut schemars::r#gen::SchemaGenerator) -> schemars::schema::Schema {
        schemars::schema::SchemaObject {
            instance_type: Some(schemars::schema::InstanceType::String.into()),
            ..Default::default()
        }
        .into()
    }
}

impl KeriSequence {
    /// Create a new sequence number.
    pub fn new(value: u128) -> Self {
        Self(value)
    }

    /// Return the full u128 value.
    pub fn value(self) -> u128 {
        self.0
    }
}

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

impl Serialize for KeriSequence {
    fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
        serializer.serialize_str(&format!("{:x}", self.0))
    }
}

impl<'de> Deserialize<'de> for KeriSequence {
    fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
        let s = String::deserialize(deserializer)?;
        let value = u128::from_str_radix(&s, 16)
            .map_err(|_| serde::de::Error::custom(format!("invalid hex sequence: {s:?}")))?;
        Ok(KeriSequence(value))
    }
}

// ── Seal ─────────────────────────────────────────────────────────────────────

/// KERI seal — anchors external data in an event's `a` field.
///
/// Variants are distinguished by field shape (untagged), not by a "type" discriminator.
/// Per the spec, seal fields MUST appear in the specified order.
///
/// Usage:
/// ```
/// use auths_keri::Seal;
/// let seal = Seal::digest("EDigest123");
/// assert!(seal.digest_value().is_some());
/// ```
#[derive(Debug, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub enum Seal {
    /// Digest seal: `{"d": "<SAID>"}`
    Digest {
        /// SAID of the anchored data.
        d: Said,
    },
    /// Source event seal: `{"s": "<hex-sn>", "d": "<SAID>"}`
    SourceEvent {
        /// Sequence number.
        s: KeriSequence,
        /// Event SAID.
        d: Said,
    },
    /// Key event seal: `{"i": "<AID>", "s": "<hex-sn>", "d": "<SAID>"}`
    KeyEvent {
        /// AID.
        i: Prefix,
        /// Sequence number.
        s: KeriSequence,
        /// Event SAID.
        d: Said,
    },
    /// Event-location seal (KERI v1.1 §7): `{"i","s","p","t","d"}`.
    EventLocation {
        /// AID.
        i: Prefix,
        /// Sequence number.
        s: KeriSequence,
        /// Prior event SAID.
        p: Said,
        /// Event type (ilk).
        t: String,
        /// Event SAID.
        d: Said,
    },
    /// Latest establishment event seal: `{"i": "<AID>"}`
    LatestEstablishment {
        /// AID.
        i: Prefix,
    },
    /// Merkle tree root digest seal: `{"rd": "<digest>"}` (non-spec extension).
    #[cfg(feature = "seal-extensions")]
    MerkleRoot {
        /// Root digest.
        rd: Said,
    },
    /// Registrar backer seal: `{"bi": "<AID>", "d": "<SAID>"}` (non-spec extension).
    #[cfg(feature = "seal-extensions")]
    RegistrarBacker {
        /// Backer AID.
        bi: Prefix,
        /// Metadata SAID.
        d: Said,
    },
}

impl Seal {
    /// Create a digest seal from a SAID.
    pub fn digest(said: impl Into<String>) -> Self {
        Self::Digest {
            d: Said::new_unchecked(said.into()),
        }
    }

    /// Create a key event seal.
    pub fn key_event(prefix: Prefix, sequence: KeriSequence, said: Said) -> Self {
        Self::KeyEvent {
            i: prefix,
            s: sequence,
            d: said,
        }
    }

    /// Get the digest from this seal, if it has one.
    pub fn digest_value(&self) -> Option<&Said> {
        match self {
            Seal::Digest { d } => Some(d),
            Seal::SourceEvent { d, .. } => Some(d),
            Seal::KeyEvent { d, .. } => Some(d),
            Seal::EventLocation { d, .. } => Some(d),
            Seal::LatestEstablishment { .. } => None,
            #[cfg(feature = "seal-extensions")]
            Seal::RegistrarBacker { d, .. } => Some(d),
            #[cfg(feature = "seal-extensions")]
            Seal::MerkleRoot { rd } => Some(rd),
        }
    }
}

impl Serialize for Seal {
    fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
        match self {
            Seal::Digest { d } => {
                let mut map = serializer.serialize_map(Some(1))?;
                map.serialize_entry("d", d)?;
                map.end()
            }
            Seal::SourceEvent { s, d } => {
                let mut map = serializer.serialize_map(Some(2))?;
                map.serialize_entry("s", s)?;
                map.serialize_entry("d", d)?;
                map.end()
            }
            Seal::KeyEvent { i, s, d } => {
                let mut map = serializer.serialize_map(Some(3))?;
                map.serialize_entry("i", i)?;
                map.serialize_entry("s", s)?;
                map.serialize_entry("d", d)?;
                map.end()
            }
            Seal::EventLocation { i, s, p, t, d } => {
                let mut map = serializer.serialize_map(Some(5))?;
                map.serialize_entry("i", i)?;
                map.serialize_entry("s", s)?;
                map.serialize_entry("p", p)?;
                map.serialize_entry("t", t)?;
                map.serialize_entry("d", d)?;
                map.end()
            }
            Seal::LatestEstablishment { i } => {
                let mut map = serializer.serialize_map(Some(1))?;
                map.serialize_entry("i", i)?;
                map.end()
            }
            #[cfg(feature = "seal-extensions")]
            Seal::MerkleRoot { rd } => {
                let mut map = serializer.serialize_map(Some(1))?;
                map.serialize_entry("rd", rd)?;
                map.end()
            }
            #[cfg(feature = "seal-extensions")]
            Seal::RegistrarBacker { bi, d } => {
                let mut map = serializer.serialize_map(Some(2))?;
                map.serialize_entry("bi", bi)?;
                map.serialize_entry("d", d)?;
                map.end()
            }
        }
    }
}

impl<'de> Deserialize<'de> for Seal {
    fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
        let map: serde_json::Map<String, serde_json::Value> =
            serde_json::Map::deserialize(deserializer)?;

        let want_str = |k: &str| -> Result<String, D::Error> {
            map.get(k)
                .and_then(|v| v.as_str())
                .map(|v| v.to_string())
                .ok_or_else(|| {
                    serde::de::Error::custom(format!("seal field `{k}` must be a string"))
                })
        };
        let want_seq =
            |k: &str| -> Result<KeriSequence, D::Error> {
                serde_json::from_value(map.get(k).cloned().ok_or_else(|| {
                    serde::de::Error::custom(format!("seal field `{k}` required"))
                })?)
                .map_err(serde::de::Error::custom)
            };

        // Match on the EXACT sorted field set — no silent field-dropping (F-37).
        let mut keys: Vec<&str> = map.keys().map(String::as_str).collect();
        keys.sort_unstable();

        match keys.as_slice() {
            ["d"] => Ok(Seal::Digest {
                d: Said::new_unchecked(want_str("d")?),
            }),
            ["d", "s"] => Ok(Seal::SourceEvent {
                s: want_seq("s")?,
                d: Said::new_unchecked(want_str("d")?),
            }),
            ["d", "i", "s"] => Ok(Seal::KeyEvent {
                i: Prefix::new_unchecked(want_str("i")?),
                s: want_seq("s")?,
                d: Said::new_unchecked(want_str("d")?),
            }),
            ["d", "i", "p", "s", "t"] => Ok(Seal::EventLocation {
                i: Prefix::new_unchecked(want_str("i")?),
                s: want_seq("s")?,
                p: Said::new_unchecked(want_str("p")?),
                t: want_str("t")?,
                d: Said::new_unchecked(want_str("d")?),
            }),
            ["i"] => Ok(Seal::LatestEstablishment {
                i: Prefix::new_unchecked(want_str("i")?),
            }),
            #[cfg(feature = "seal-extensions")]
            ["rd"] => Ok(Seal::MerkleRoot {
                rd: Said::new_unchecked(want_str("rd")?),
            }),
            #[cfg(feature = "seal-extensions")]
            ["bi", "d"] => Ok(Seal::RegistrarBacker {
                bi: Prefix::new_unchecked(want_str("bi")?),
                d: Said::new_unchecked(want_str("d")?),
            }),
            other => Err(serde::de::Error::custom(format!(
                "unrecognized seal field set: {other:?}"
            ))),
        }
    }
}

// ── Event Types ───────────────────────────────────────────────────────────────

/// Inception event — creates a new KERI identity.
///
/// The inception event establishes the identifier prefix and commits
/// to the first rotation key via the `n` (next) field.
///
/// Spec field order: `[v, t, d, i, s, kt, k, nt, n, bt, b, c, a]`
#[derive(Debug, Clone, Deserialize, PartialEq, Eq)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct IcpEvent {
    /// Version string
    pub v: VersionString,
    /// SAID (Self-Addressing Identifier) — Blake3 hash of event
    pub d: Said,
    /// Identifier prefix (same as `d` for self-addressing inception)
    pub i: Prefix,
    /// Sequence number (always 0 for inception)
    pub s: KeriSequence,
    /// Key signing threshold (hex integer or fractional weight list)
    pub kt: Threshold,
    /// Current public key(s), CESR-encoded
    pub k: Vec<CesrKey>,
    /// Next key signing threshold
    pub nt: Threshold,
    /// Next key commitment(s) — Blake3 digests of next public key(s)
    pub n: Vec<Said>,
    /// Witness/backer threshold
    pub bt: Threshold,
    /// Witness/backer list (ordered AIDs)
    #[serde(default)]
    pub b: Vec<Prefix>,
    /// Configuration traits (e.g., EstablishmentOnly, DoNotDelegate)
    #[serde(default)]
    pub c: Vec<ConfigTrait>,
    /// Anchored seals
    #[serde(default)]
    pub a: Vec<Seal>,
}

/// Parameter struct for [`IcpEvent::new`]. Mirrors the existing
/// field set 1-for-1 so call-site migration is a mechanical prefix/
/// suffix wrap. Future wire-format additions land on `IcpEvent` via
/// a `with_*` method, not by widening this `Init` struct — that's
/// what makes the pattern future-proof.
pub struct IcpEventInit {
    /// Version string (`KERI10JSON…`); a placeholder until finalized.
    pub v: VersionString,
    /// Self-addressing identifier (the event SAID); blank until finalized.
    pub d: Said,
    /// Identifier prefix; for inception this equals the SAID (self-addressing).
    pub i: Prefix,
    /// Sequence number (0 for inception).
    pub s: KeriSequence,
    /// Signing threshold over the current keys `k`.
    pub kt: Threshold,
    /// Current signing keys (CESR-encoded verkeys).
    pub k: Vec<CesrKey>,
    /// Next-key threshold over the pre-rotation commitments `n`.
    pub nt: Threshold,
    /// Pre-rotation commitments (digests of the next keys).
    pub n: Vec<Said>,
    /// Backer (witness) threshold.
    pub bt: Threshold,
    /// Backer (witness) prefixes.
    pub b: Vec<Prefix>,
    /// Configuration traits (e.g. establishment-only, do-not-delegate).
    pub c: Vec<ConfigTrait>,
    /// Anchored seals.
    pub a: Vec<Seal>,
}

impl IcpEvent {
    /// Construct an `IcpEvent` from its required fields.
    pub fn new(init: IcpEventInit) -> Self {
        Self {
            v: init.v,
            d: init.d,
            i: init.i,
            s: init.s,
            kt: init.kt,
            k: init.k,
            nt: init.nt,
            n: init.n,
            bt: init.bt,
            b: init.b,
            c: init.c,
            a: init.a,
        }
    }
}

/// Spec field order: v, t, d, i, s, kt, k, nt, n, bt, b, c, a
impl Serialize for IcpEvent {
    fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
        let field_count = 13;
        let mut map = serializer.serialize_map(Some(field_count))?;
        map.serialize_entry("v", &self.v)?;
        map.serialize_entry("t", "icp")?;
        map.serialize_entry("d", &self.d)?;
        map.serialize_entry("i", &self.i)?;
        map.serialize_entry("s", &self.s)?;
        map.serialize_entry("kt", &self.kt)?;
        map.serialize_entry("k", &self.k)?;
        map.serialize_entry("nt", &self.nt)?;
        map.serialize_entry("n", &self.n)?;
        map.serialize_entry("bt", &self.bt)?;
        map.serialize_entry("b", &self.b)?;
        map.serialize_entry("c", &self.c)?;
        map.serialize_entry("a", &self.a)?;
        map.end()
    }
}

/// Rotation event — rotates to pre-committed key.
///
/// Spec field order: `[v, t, d, i, s, p, kt, k, nt, n, bt, br, ba, a]`
#[derive(Debug, Clone, Deserialize, PartialEq, Eq)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct RotEvent {
    /// Version string
    pub v: VersionString,
    /// SAID of this event
    pub d: Said,
    /// Identifier prefix
    pub i: Prefix,
    /// Sequence number (increments with each event)
    pub s: KeriSequence,
    /// Previous event SAID (creates the hash chain)
    pub p: Said,
    /// Key signing threshold
    pub kt: Threshold,
    /// New current key(s), CESR-encoded
    pub k: Vec<CesrKey>,
    /// Next key signing threshold
    pub nt: Threshold,
    /// New next key commitment(s) — Blake3 digests
    pub n: Vec<Said>,
    /// Witness/backer threshold
    pub bt: Threshold,
    /// List of backers to remove (processed first)
    #[serde(default)]
    pub br: Vec<Prefix>,
    /// List of backers to add (processed after removals)
    #[serde(default)]
    pub ba: Vec<Prefix>,
    /// Configuration traits
    #[serde(default)]
    pub c: Vec<ConfigTrait>,
    /// Anchored seals
    #[serde(default)]
    pub a: Vec<Seal>,
}

/// Parameter struct for [`RotEvent::new`]. See [`IcpEventInit`] for
/// the pattern rationale.
pub struct RotEventInit {
    /// Version string (`KERI10JSON…`); a placeholder until finalized.
    pub v: VersionString,
    /// Self-addressing identifier (the event SAID); blank until finalized.
    pub d: Said,
    /// Identifier prefix of the rotating identity.
    pub i: Prefix,
    /// Sequence number (strictly greater than the prior event's).
    pub s: KeriSequence,
    /// Prior event SAID (the back-link establishing the chain).
    pub p: Said,
    /// Signing threshold over the new current keys `k`.
    pub kt: Threshold,
    /// New current signing keys (CESR-encoded verkeys) revealed by this rotation.
    pub k: Vec<CesrKey>,
    /// Next-key threshold over the new pre-rotation commitments `n`.
    pub nt: Threshold,
    /// New pre-rotation commitments (digests of the next keys).
    pub n: Vec<Said>,
    /// Backer (witness) threshold after applying the backer deltas.
    pub bt: Threshold,
    /// Backer (witness) prefixes to remove.
    pub br: Vec<Prefix>,
    /// Backer (witness) prefixes to add.
    pub ba: Vec<Prefix>,
    /// Configuration traits (e.g. `RB`/`NRB`) updated by this rotation.
    pub c: Vec<ConfigTrait>,
    /// Anchored seals carried in this event's `a[]`.
    pub a: Vec<Seal>,
}

impl RotEvent {
    /// Construct a `RotEvent` from its required fields.
    pub fn new(init: RotEventInit) -> Self {
        Self {
            v: init.v,
            d: init.d,
            i: init.i,
            s: init.s,
            p: init.p,
            kt: init.kt,
            k: init.k,
            nt: init.nt,
            n: init.n,
            bt: init.bt,
            br: init.br,
            ba: init.ba,
            c: init.c,
            a: init.a,
        }
    }
}

/// Spec field order: v, t, d, i, s, p, kt, k, nt, n, bt, br, ba, a
impl Serialize for RotEvent {
    fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
        let field_count = 14;
        let mut map = serializer.serialize_map(Some(field_count))?;
        map.serialize_entry("v", &self.v)?;
        map.serialize_entry("t", "rot")?;
        map.serialize_entry("d", &self.d)?;
        map.serialize_entry("i", &self.i)?;
        map.serialize_entry("s", &self.s)?;
        map.serialize_entry("p", &self.p)?;
        map.serialize_entry("kt", &self.kt)?;
        map.serialize_entry("k", &self.k)?;
        map.serialize_entry("nt", &self.nt)?;
        map.serialize_entry("n", &self.n)?;
        map.serialize_entry("bt", &self.bt)?;
        map.serialize_entry("br", &self.br)?;
        map.serialize_entry("ba", &self.ba)?;
        map.serialize_entry("a", &self.a)?;
        map.end()
    }
}

/// Interaction event — anchors data without key rotation.
///
/// Spec field order: `[v, t, d, i, s, p, a]`
#[derive(Debug, Clone, Deserialize, PartialEq, Eq)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct IxnEvent {
    /// Version string
    pub v: VersionString,
    /// SAID of this event
    pub d: Said,
    /// Identifier prefix
    pub i: Prefix,
    /// Sequence number
    pub s: KeriSequence,
    /// Previous event SAID
    pub p: Said,
    /// Anchored seals (the main purpose of IXN events)
    pub a: Vec<Seal>,
}

/// Parameter struct for [`IxnEvent::new`].
pub struct IxnEventInit {
    pub v: VersionString,
    pub d: Said,
    pub i: Prefix,
    pub s: KeriSequence,
    pub p: Said,
    pub a: Vec<Seal>,
}

impl IxnEvent {
    /// Construct an `IxnEvent` from its required fields.
    pub fn new(init: IxnEventInit) -> Self {
        Self {
            v: init.v,
            d: init.d,
            i: init.i,
            s: init.s,
            p: init.p,
            a: init.a,
        }
    }
}

/// Spec field order: v, t, d, i, s, p, a
impl Serialize for IxnEvent {
    fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
        let field_count = 7;
        let mut map = serializer.serialize_map(Some(field_count))?;
        map.serialize_entry("v", &self.v)?;
        map.serialize_entry("t", "ixn")?;
        map.serialize_entry("d", &self.d)?;
        map.serialize_entry("i", &self.i)?;
        map.serialize_entry("s", &self.s)?;
        map.serialize_entry("p", &self.p)?;
        map.serialize_entry("a", &self.a)?;
        map.end()
    }
}

/// Unified event enum for processing any KERI event type.
///
/// Uses serde's tagged enum feature to deserialize based on the `t` field.
///
/// Usage:
/// ```ignore
/// let event: Event = serde_json::from_str(json)?;
/// match event {
///     Event::Icp(icp) => { /* inception */ }
///     Event::Rot(rot) => { /* rotation */ }
///     Event::Ixn(ixn) => { /* interaction */ }
/// }
/// ```
/// Delegated inception event — creates a delegated KERI identity.
///
/// Same as ICP plus the `di` (delegator identifier prefix) field.
/// Spec field order: `[v, t, d, i, s, kt, k, nt, n, bt, b, c, a, di]`
#[derive(Debug, Clone, Deserialize, PartialEq, Eq)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct DipEvent {
    /// Version string
    pub v: VersionString,
    /// SAID
    pub d: Said,
    /// Identifier prefix (same as `d` for self-addressing)
    pub i: Prefix,
    /// Sequence number (always 0)
    pub s: KeriSequence,
    /// Key signing threshold
    pub kt: Threshold,
    /// Current public key(s)
    pub k: Vec<CesrKey>,
    /// Next key signing threshold
    pub nt: Threshold,
    /// Next key commitment(s)
    pub n: Vec<Said>,
    /// Witness/backer threshold
    pub bt: Threshold,
    /// Witness/backer list
    #[serde(default)]
    pub b: Vec<Prefix>,
    /// Configuration traits
    #[serde(default)]
    pub c: Vec<ConfigTrait>,
    /// Anchored seals
    #[serde(default)]
    pub a: Vec<Seal>,
    /// Delegator identifier prefix
    pub di: Prefix,
    /// Delegate-side source seal (`-G` `SealSourceCouple`): a back-reference to
    /// the delegator's anchoring event. Carried in the CESR **attachment**, never
    /// in the event body — so it is `#[serde(skip)]` (absent from the JSON and from
    /// SAID computation) and populated after the delegator anchors (the cooperative
    /// double-anchor). `None` until/unless the anchoring event is known.
    #[serde(skip)]
    pub source_seal: Option<SourceSeal>,
}

/// Parameter struct for [`DipEvent::new`].
pub struct DipEventInit {
    /// Version string (KERI version + serialization + byte count).
    pub v: VersionString,
    /// Self-addressing identifier (SAID) of this event.
    pub d: Said,
    /// Identifier prefix (AID); self-addressing for a delegated AID (`i == d`).
    pub i: Prefix,
    /// Sequence number (0 for inception).
    pub s: KeriSequence,
    /// Current signing threshold.
    pub kt: Threshold,
    /// Current signing public keys (CESR-encoded).
    pub k: Vec<CesrKey>,
    /// Next (rotation) threshold.
    pub nt: Threshold,
    /// Next-key commitments (pre-rotation digests).
    pub n: Vec<Said>,
    /// Backer (witness) threshold.
    pub bt: Threshold,
    /// Backer (witness) list.
    pub b: Vec<Prefix>,
    /// Configuration traits.
    pub c: Vec<ConfigTrait>,
    /// Anchored seals.
    pub a: Vec<Seal>,
    /// Delegator prefix — the AID delegating this identifier.
    pub di: Prefix,
}

impl DipEvent {
    /// Construct a `DipEvent` from its required fields.
    pub fn new(init: DipEventInit) -> Self {
        Self {
            v: init.v,
            d: init.d,
            i: init.i,
            s: init.s,
            kt: init.kt,
            k: init.k,
            nt: init.nt,
            n: init.n,
            bt: init.bt,
            b: init.b,
            c: init.c,
            a: init.a,
            di: init.di,
            source_seal: None,
        }
    }
}

/// Spec field order: v, t, d, i, s, kt, k, nt, n, bt, b, c, a, di
impl Serialize for DipEvent {
    fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
        let field_count = 14;
        let mut map = serializer.serialize_map(Some(field_count))?;
        map.serialize_entry("v", &self.v)?;
        map.serialize_entry("t", "dip")?;
        map.serialize_entry("d", &self.d)?;
        map.serialize_entry("i", &self.i)?;
        map.serialize_entry("s", &self.s)?;
        map.serialize_entry("kt", &self.kt)?;
        map.serialize_entry("k", &self.k)?;
        map.serialize_entry("nt", &self.nt)?;
        map.serialize_entry("n", &self.n)?;
        map.serialize_entry("bt", &self.bt)?;
        map.serialize_entry("b", &self.b)?;
        map.serialize_entry("c", &self.c)?;
        map.serialize_entry("a", &self.a)?;
        map.serialize_entry("di", &self.di)?;
        map.end()
    }
}

/// Delegated rotation event — rotates keys for a delegated identity.
///
/// Same field set as ROT but type `drt`. Validation requires checking the
/// delegator's KEL for an anchoring seal.
/// Spec field order: `[v, t, d, i, s, p, kt, k, nt, n, bt, br, ba, a]`
#[derive(Debug, Clone, Deserialize, PartialEq, Eq)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct DrtEvent {
    /// Version string
    pub v: VersionString,
    /// SAID
    pub d: Said,
    /// Identifier prefix
    pub i: Prefix,
    /// Sequence number
    pub s: KeriSequence,
    /// Previous event SAID
    pub p: Said,
    /// Key signing threshold
    pub kt: Threshold,
    /// New current key(s)
    pub k: Vec<CesrKey>,
    /// Next key signing threshold
    pub nt: Threshold,
    /// New next key commitment(s)
    pub n: Vec<Said>,
    /// Witness/backer threshold
    pub bt: Threshold,
    /// Backers to remove
    #[serde(default)]
    pub br: Vec<Prefix>,
    /// Backers to add
    #[serde(default)]
    pub ba: Vec<Prefix>,
    /// Configuration traits
    #[serde(default)]
    pub c: Vec<ConfigTrait>,
    /// Anchored seals
    #[serde(default)]
    pub a: Vec<Seal>,
    /// Delegator identifier prefix (KERI §11).
    pub di: Prefix,
    /// Delegate-side source seal (`-G` `SealSourceCouple`) — see
    /// [`DipEvent::source_seal`]. Carried in the attachment, set after the
    /// delegator anchors this rotation.
    #[serde(skip)]
    pub source_seal: Option<SourceSeal>,
}

/// Parameter struct for [`DrtEvent::new`].
pub struct DrtEventInit {
    /// Version string (KERI version + serialization + byte count).
    pub v: VersionString,
    /// Self-addressing identifier (SAID) of this event.
    pub d: Said,
    /// Identifier prefix (AID) — the existing delegated AID (not self-addressing).
    pub i: Prefix,
    /// Sequence number.
    pub s: KeriSequence,
    /// Prior event SAID (chains to the previous event).
    pub p: Said,
    /// Current signing threshold.
    pub kt: Threshold,
    /// Current signing public keys (CESR-encoded) — the revealed pre-rotated keys.
    pub k: Vec<CesrKey>,
    /// Next (rotation) threshold.
    pub nt: Threshold,
    /// Next-key commitments (pre-rotation digests).
    pub n: Vec<Said>,
    /// Backer (witness) threshold.
    pub bt: Threshold,
    /// Backers (witnesses) to remove.
    pub br: Vec<Prefix>,
    /// Backers (witnesses) to add.
    pub ba: Vec<Prefix>,
    /// Configuration traits.
    pub c: Vec<ConfigTrait>,
    /// Anchored seals.
    pub a: Vec<Seal>,
    /// Delegator prefix — the AID delegating this identifier.
    pub di: Prefix,
}

impl DrtEvent {
    /// Construct a `DrtEvent` from its required fields.
    pub fn new(init: DrtEventInit) -> Self {
        Self {
            v: init.v,
            d: init.d,
            i: init.i,
            s: init.s,
            p: init.p,
            kt: init.kt,
            k: init.k,
            nt: init.nt,
            n: init.n,
            bt: init.bt,
            br: init.br,
            ba: init.ba,
            c: init.c,
            a: init.a,
            di: init.di,
            source_seal: None,
        }
    }
}

/// Spec field order (KERI §11): v, t, d, i, s, p, kt, k, nt, n, bt, br, ba, a, di
impl Serialize for DrtEvent {
    fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
        let field_count = 15;
        let mut map = serializer.serialize_map(Some(field_count))?;
        map.serialize_entry("v", &self.v)?;
        map.serialize_entry("t", "drt")?;
        map.serialize_entry("d", &self.d)?;
        map.serialize_entry("i", &self.i)?;
        map.serialize_entry("s", &self.s)?;
        map.serialize_entry("p", &self.p)?;
        map.serialize_entry("kt", &self.kt)?;
        map.serialize_entry("k", &self.k)?;
        map.serialize_entry("nt", &self.nt)?;
        map.serialize_entry("n", &self.n)?;
        map.serialize_entry("bt", &self.bt)?;
        map.serialize_entry("br", &self.br)?;
        map.serialize_entry("ba", &self.ba)?;
        map.serialize_entry("a", &self.a)?;
        map.serialize_entry("di", &self.di)?;
        map.end()
    }
}

/// Unified event enum for processing any KERI event type.
#[derive(Debug, Clone, Deserialize, PartialEq, Eq)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[serde(tag = "t")]
pub enum Event {
    /// Inception event
    #[serde(rename = "icp")]
    Icp(IcpEvent),
    /// Rotation event
    #[serde(rename = "rot")]
    Rot(RotEvent),
    /// Interaction event
    #[serde(rename = "ixn")]
    Ixn(IxnEvent),
    /// Delegated inception event
    #[serde(rename = "dip")]
    Dip(DipEvent),
    /// Delegated rotation event
    #[serde(rename = "drt")]
    Drt(DrtEvent),
}

impl Serialize for Event {
    fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
        match self {
            Event::Icp(e) => e.serialize(serializer),
            Event::Rot(e) => e.serialize(serializer),
            Event::Ixn(e) => e.serialize(serializer),
            Event::Dip(e) => e.serialize(serializer),
            Event::Drt(e) => e.serialize(serializer),
        }
    }
}

impl Event {
    /// Get the SAID of this event.
    pub fn said(&self) -> &Said {
        match self {
            Event::Icp(e) => &e.d,
            Event::Rot(e) => &e.d,
            Event::Ixn(e) => &e.d,
            Event::Dip(e) => &e.d,
            Event::Drt(e) => &e.d,
        }
    }

    /// Get the sequence number of this event.
    pub fn sequence(&self) -> KeriSequence {
        match self {
            Event::Icp(e) => e.s,
            Event::Rot(e) => e.s,
            Event::Ixn(e) => e.s,
            Event::Dip(e) => e.s,
            Event::Drt(e) => e.s,
        }
    }

    /// Get the identifier prefix.
    pub fn prefix(&self) -> &Prefix {
        match self {
            Event::Icp(e) => &e.i,
            Event::Rot(e) => &e.i,
            Event::Ixn(e) => &e.i,
            Event::Dip(e) => &e.i,
            Event::Drt(e) => &e.i,
        }
    }

    /// Get the previous event SAID (None for inception/delegated inception).
    pub fn previous(&self) -> Option<&Said> {
        match self {
            Event::Icp(_) | Event::Dip(_) => None,
            Event::Rot(e) => Some(&e.p),
            Event::Ixn(e) => Some(&e.p),
            Event::Drt(e) => Some(&e.p),
        }
    }

    /// Get the current keys (only for establishment events).
    pub fn keys(&self) -> Option<&[CesrKey]> {
        match self {
            Event::Icp(e) => Some(&e.k),
            Event::Rot(e) => Some(&e.k),
            Event::Dip(e) => Some(&e.k),
            Event::Drt(e) => Some(&e.k),
            Event::Ixn(_) => None,
        }
    }

    /// Get the next key commitments (only for establishment events).
    pub fn next_commitments(&self) -> Option<&[Said]> {
        match self {
            Event::Icp(e) => Some(&e.n),
            Event::Rot(e) => Some(&e.n),
            Event::Dip(e) => Some(&e.n),
            Event::Drt(e) => Some(&e.n),
            Event::Ixn(_) => None,
        }
    }

    /// Get the anchored seals.
    pub fn anchors(&self) -> &[Seal] {
        match self {
            Event::Icp(e) => &e.a,
            Event::Rot(e) => &e.a,
            Event::Ixn(e) => &e.a,
            Event::Dip(e) => &e.a,
            Event::Drt(e) => &e.a,
        }
    }

    /// Get the delegator AID (only for delegated inception).
    pub fn delegator(&self) -> Option<&Prefix> {
        match self {
            Event::Dip(e) => Some(&e.di),
            _ => None,
        }
    }

    /// Check if this is an inception event (including delegated).
    pub fn is_inception(&self) -> bool {
        matches!(self, Event::Icp(_) | Event::Dip(_))
    }

    /// Check if this is a rotation event (including delegated).
    pub fn is_rotation(&self) -> bool {
        matches!(self, Event::Rot(_) | Event::Drt(_))
    }

    /// Check if this is an interaction event.
    pub fn is_interaction(&self) -> bool {
        matches!(self, Event::Ixn(_))
    }

    /// Check if this is a delegated event.
    pub fn is_delegated(&self) -> bool {
        matches!(self, Event::Dip(_) | Event::Drt(_))
    }

    /// Get the delegate-side source seal (`-G` back-reference to the delegator's
    /// anchoring event), if this is a delegated event that has been anchored.
    pub fn source_seal(&self) -> Option<&SourceSeal> {
        match self {
            Event::Dip(e) => e.source_seal.as_ref(),
            Event::Drt(e) => e.source_seal.as_ref(),
            _ => None,
        }
    }
}

// ── Signed Event (externalized signatures) ──────────────────────────────────

/// A single indexed controller signature.
///
/// The `index` maps to the position in the key list (`k` field) of the
/// signing key. Per the CESR spec, indexed signatures carry their key
/// index in the derivation code.
///
/// Usage:
/// ```
/// use auths_keri::IndexedSignature;
/// let sig = IndexedSignature { index: 0, prior_index: None, sig: vec![0u8; 64] };
/// assert_eq!(sig.index, 0);
/// ```
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct IndexedSignature {
    /// Index into the new key list `k[]` (which current key signed).
    pub index: u32,
    /// For a rotation signature, the index into the prior event's next-key
    /// commitment list `n[]` that this signature reveals (CESR *ondex*).
    ///
    /// `Some(j)` emits a dual-index ("Big", `2A`) siger; `None` emits the
    /// single-index code (`A`) with ondex == index — preserving the wire
    /// bytes of every single-index signer (inception, symmetric rotation).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub prior_index: Option<u32>,
    /// Raw signature bytes (64 bytes for Ed25519).
    #[serde(with = "hex::serde")]
    pub sig: Vec<u8>,
}

/// A delegate-side source seal — the parsed form of a CESR `-G` `SealSourceCouple`.
///
/// A delegated event (`dip`/`drt`) carries one of these as an **attachment** (never
/// in the body) to bind itself back to the *specific* delegator event that anchored
/// it: `s` is that anchoring event's sequence number (CESR `Seqner`), `d` is its
/// SAID (CESR `Saider`). Together with the delegator-side `Seal::KeyEvent` (which
/// points the other way) this forms the **bilateral** delegation binding keripy
/// requires. Byte-aligned with keripy 1.3.4's `-G` couple.
#[derive(Debug, Clone, PartialEq, Eq)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct SourceSeal {
    /// Sequence number of the delegator's anchoring event.
    pub s: KeriSequence,
    /// SAID of the delegator's anchoring event.
    pub d: Said,
}

/// Delegator-anchored scope/expiry for a delegated agent (Epic E.7).
///
/// Carried as a `Seal::Digest` in the **delegator's** anchoring `ixn` — authority
/// comes from the party that controls the delegator key, never agent-self-asserted.
/// The digest value is a structured marker string (not a SAID) namespaced under
/// `agentscope:`, so it never collides with a real digest, a revocation (bare
/// prefix), or an `agent:` role marker. Advisory authorization; the principled
/// upgrade is a targeted ACDC (Epic F).
#[derive(Debug, Clone, PartialEq, Eq, Default)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct AgentScope {
    /// Capabilities granted to the agent (empty = unrestricted). Capability strings
    /// may contain `:` (e.g. `repo:foo`) but not `,` (the list separator).
    pub capabilities: Vec<Capability>,
    /// Expiry as Unix epoch seconds; `None` = never expires.
    pub expires_at: Option<i64>,
}

/// Marker prefix for an agent-scope `Seal::Digest` value.
const AGENT_SCOPE_MARKER: &str = "agentscope:";

/// Encode an agent-scope seal value: `agentscope:{prefix}:{expires_or_0}:{caps_csv}`.
///
/// Args:
/// * `agent_prefix`: The agent's KEL prefix the scope applies to.
/// * `scope`: The granted capabilities + optional expiry.
///
/// Usage:
/// ```
/// use auths_keri::{AgentScope, Capability, encode_agent_scope};
/// let s = AgentScope {
///     capabilities: vec![Capability::sign_commit()],
///     expires_at: Some(99),
/// };
/// assert_eq!(encode_agent_scope("Eabc", &s), "agentscope:Eabc:99:sign_commit");
/// ```
pub fn encode_agent_scope(agent_prefix: &str, scope: &AgentScope) -> String {
    let expires = scope.expires_at.unwrap_or(0);
    let caps = scope
        .capabilities
        .iter()
        .map(Capability::as_str)
        .collect::<Vec<_>>()
        .join(",");
    format!("{AGENT_SCOPE_MARKER}{agent_prefix}:{expires}:{caps}")
}

/// Decode an agent-scope seal value into `(agent_prefix, AgentScope)`, or `None` if
/// the value is not an `agentscope:` marker or any capability fails validation.
/// Inverse of [`encode_agent_scope`].
///
/// Args:
/// * `value`: A `Seal::Digest` value to interpret.
pub fn decode_agent_scope(value: &str) -> Option<(String, AgentScope)> {
    // {prefix}:{expires}:{caps_csv} — prefix is a `:`-free KERI prefix; caps may
    // contain `:`, so the 3-way split keeps the caps tail intact.
    let rest = value.strip_prefix(AGENT_SCOPE_MARKER)?;
    let mut parts = rest.splitn(3, ':');
    let prefix = parts.next()?.to_string();
    let expires: i64 = parts.next()?.parse().ok()?;
    let caps_csv = parts.next().unwrap_or("");
    let capabilities = if caps_csv.is_empty() {
        Vec::new()
    } else {
        caps_csv
            .split(',')
            .map(Capability::parse)
            .collect::<Result<Vec<_>, _>>()
            .ok()?
    };
    Some((
        prefix,
        AgentScope {
            capabilities,
            expires_at: (expires != 0).then_some(expires),
        },
    ))
}

/// Serialize source seals to a CESR text-domain `-G##<Seqner><Saider>…`
/// `SealSourceCouples` group, byte-aligned with keripy 1.3.4.
///
/// Each couple is a `Seqner` (`0A`-coded 128-bit sequence) followed by a `Saider`
/// (the anchoring event's SAID). Reads back via [`parse_source_seal_couples`].
///
/// Args:
/// * `couples`: The delegate-side source seals to encode.
///
/// Usage:
/// ```ignore
/// let bytes = serialize_source_seal_couples(&[SourceSeal { s, d }])?;
/// ```
pub fn serialize_source_seal_couples(couples: &[SourceSeal]) -> Result<Vec<u8>, AttachmentError> {
    use cesride::{Counter, Matter, Saider, Seqner, counter};

    let count = u32::try_from(couples.len())
        .map_err(|_| AttachmentError::Encode("too many source seal couples".into()))?;
    let mut out = Counter::new_with_code_and_count(counter::Codex::SealSourceCouples, count)
        .and_then(|c| c.qb64())
        .map_err(|e| AttachmentError::Encode(e.to_string()))?;

    for couple in couples {
        let seqner = Seqner::new_with_sn(couple.s.value())
            .and_then(|s| s.qb64())
            .map_err(|e| AttachmentError::Encode(e.to_string()))?;
        let saider = Saider::new_with_qb64(couple.d.as_str())
            .and_then(|s| s.qb64())
            .map_err(|e| AttachmentError::Encode(e.to_string()))?;
        out.push_str(&seqner);
        out.push_str(&saider);
    }

    Ok(out.into_bytes())
}

/// Parse a CESR `-G##` `SealSourceCouples` group into [`SourceSeal`]s.
///
/// Inverse of [`serialize_source_seal_couples`]; code-directed so each `Seqner`
/// and `Saider` width is read from its CESR hard code.
///
/// Args:
/// * `bytes`: The `-G`-prefixed couple-group bytes (e.g. from an attachment tail).
pub fn parse_source_seal_couples(bytes: &[u8]) -> Result<Vec<SourceSeal>, AttachmentError> {
    let s = std::str::from_utf8(bytes)
        .map_err(|e| AttachmentError::Decode(format!("non-utf8 source-seal group: {e}")))?;
    let (couples, rest) = parse_source_seal_group(s)?;
    if !rest.is_empty() {
        return Err(AttachmentError::Decode(format!(
            "trailing bytes after source-seal group: {rest:?}"
        )));
    }
    Ok(couples)
}

/// Parse one `-G` `SealSourceCouples` group at the head of `s`, returning the
/// couples and the unconsumed remainder.
fn parse_source_seal_group(s: &str) -> Result<(Vec<SourceSeal>, &str), AttachmentError> {
    use cesride::{Matter, Saider, Seqner};

    // CESR qb64 is ASCII; reject non-ASCII at the boundary so the byte-offset slices
    // below cannot split a multi-byte char and panic.
    if !s.is_ascii() {
        return Err(AttachmentError::Decode("non-ASCII CESR attachment".into()));
    }
    let rest = s.strip_prefix("-G").ok_or_else(|| {
        AttachmentError::Decode("source-seal group must start with -G counter code".into())
    })?;
    if rest.len() < 2 {
        return Err(AttachmentError::Decode(
            "truncated -G counter header".into(),
        ));
    }
    let (count_b64, mut cursor) = rest.split_at(2);
    let count = decode_count_b64(count_b64)?;

    let mut out = Vec::with_capacity(count);
    for _ in 0..count {
        // Seqner is fixed-width (`0A` + 22 base64 = 24 chars; a 128-bit number).
        if cursor.len() < SEQNER_QB64_LEN {
            return Err(AttachmentError::Decode(
                "truncated Seqner in -G couple".into(),
            ));
        }
        let (seqner_qb64, after_seqner) = cursor.split_at(SEQNER_QB64_LEN);
        let seqner = Seqner::new_with_qb64(seqner_qb64)
            .map_err(|e| AttachmentError::Decode(format!("Seqner: {e}")))?;
        let sn = seqner
            .sn()
            .map_err(|e| AttachmentError::Decode(format!("Seqner sn: {e}")))?;

        // Saider is code-directed; the leading char fixes its full width.
        let first = *after_seqner.as_bytes().first().ok_or_else(|| {
            AttachmentError::Decode("truncated -G couple: expected a Saider".into())
        })?;
        let fs = saider_qb64_len(first).ok_or_else(|| {
            AttachmentError::Decode(format!("unsupported Saider code byte {first:?}"))
        })?;
        if after_seqner.len() < fs {
            return Err(AttachmentError::Decode(
                "truncated Saider in -G couple".into(),
            ));
        }
        let (saider_qb64, remainder) = after_seqner.split_at(fs);
        let saider = Saider::new_with_qb64(saider_qb64)
            .and_then(|s| s.qb64())
            .map_err(|e| AttachmentError::Decode(format!("Saider: {e}")))?;
        cursor = remainder;

        out.push(SourceSeal {
            s: KeriSequence::new(sn),
            d: Said::new_unchecked(saider),
        });
    }
    Ok((out, cursor))
}

/// Parse a delegated event's combined attachment — the controller signature group
/// (`-A`) followed by an optional source-seal group (`-G`).
///
/// Returns the indexed signatures and any source seals. Used by storage read paths
/// to re-attach a delegated event's `-G` back-reference after a JSON round-trip.
///
/// Args:
/// * `bytes`: The full attachment bytes (`-A…` then optional `-G…`).
pub fn parse_delegated_attachment(
    bytes: &[u8],
) -> Result<(Vec<IndexedSignature>, Vec<SourceSeal>), AttachmentError> {
    let s = std::str::from_utf8(bytes)
        .map_err(|e| AttachmentError::Decode(format!("non-utf8 attachment: {e}")))?;
    if s.is_empty() {
        return Ok((vec![], vec![]));
    }
    let (sigs, rest) = parse_sig_group(s)?;
    if rest.is_empty() {
        return Ok((sigs, vec![]));
    }
    let (couples, tail) = parse_source_seal_group(rest)?;
    if !tail.is_empty() {
        return Err(AttachmentError::Decode(format!(
            "trailing bytes after delegated attachment: {tail:?}"
        )));
    }
    Ok((sigs, couples))
}

/// A device-signed delegated inception serialized for a single wire field.
///
/// Carried as base64url-no-pad(JSON) wherever a transport needs a signed `dip`
/// in one string (e.g. a pairing response's `responder_inception_event`). The
/// CESR signature attachment travels alongside the event so the receiver can
/// replay the signed dip exactly as the device emitted it.
///
/// This is the ONE wire form for a signed dip — every producer (CLI joiner,
/// mobile FFI) and consumer (the anchoring initiator) goes through
/// [`encode_signed_dip`] / [`decode_signed_dip`].
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct WireSignedDip {
    /// The device's delegated-inception event.
    pub event: DipEvent,
    /// base64url-no-pad of the device's CESR signature attachment over the dip.
    pub attachment_b64: String,
}

/// Encode a device-signed dip into its single-string wire form.
///
/// Args:
/// * `dip`: The finalized, device-signed delegated-inception event.
/// * `attachment`: The device's CESR signature attachment bytes (from
///   [`serialize_attachment`]).
pub fn encode_signed_dip(dip: &DipEvent, attachment: &[u8]) -> Result<String, AttachmentError> {
    use base64::{Engine, engine::general_purpose::URL_SAFE_NO_PAD};
    let wire = WireSignedDip {
        event: dip.clone(),
        attachment_b64: URL_SAFE_NO_PAD.encode(attachment),
    };
    let json =
        serde_json::to_vec(&wire).map_err(|e| AttachmentError::Encode(format!("dip json: {e}")))?;
    Ok(URL_SAFE_NO_PAD.encode(json))
}

/// Decode a single-string wire form back into the dip and its attachment bytes.
/// Inverse of [`encode_signed_dip`].
///
/// Args:
/// * `encoded`: The base64url-no-pad(JSON) wire string.
pub fn decode_signed_dip(encoded: &str) -> Result<(DipEvent, Vec<u8>), AttachmentError> {
    use base64::{Engine, engine::general_purpose::URL_SAFE_NO_PAD};
    let json = URL_SAFE_NO_PAD
        .decode(encoded)
        .map_err(|e| AttachmentError::Decode(format!("dip envelope: {e}")))?;
    let wire: WireSignedDip = serde_json::from_slice(&json)
        .map_err(|e| AttachmentError::Decode(format!("dip json: {e}")))?;
    let attachment = URL_SAFE_NO_PAD
        .decode(&wire.attachment_b64)
        .map_err(|e| AttachmentError::Decode(format!("dip attachment: {e}")))?;
    Ok((wire.event, attachment))
}

/// Single-string wire form of a signed rotation: base64url-no-pad of the
/// JSON `{event, attachment_b64}` pair.
///
/// This is the ONE wire form for a signed `rot` in transit — every producer
/// (the mobile FFI's shared-KEL rotation assembler) and consumer (the daemon
/// endpoint that receives a co-authored rotation) goes through
/// [`encode_signed_rot`] / [`decode_signed_rot`]. Mirrors [`WireSignedDip`].
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct WireSignedRot {
    /// The rotation event.
    pub event: RotEvent,
    /// base64url-no-pad of the CESR indexed-signature attachment over the rot.
    pub attachment_b64: String,
}

/// Encode a signed rot into its single-string wire form.
///
/// Args:
/// * `rot`: The finalized, signed rotation event.
/// * `attachment`: The CESR indexed-signature attachment bytes (from
///   [`serialize_attachment`]).
pub fn encode_signed_rot(rot: &RotEvent, attachment: &[u8]) -> Result<String, AttachmentError> {
    use base64::{Engine, engine::general_purpose::URL_SAFE_NO_PAD};
    let wire = WireSignedRot {
        event: rot.clone(),
        attachment_b64: URL_SAFE_NO_PAD.encode(attachment),
    };
    let json =
        serde_json::to_vec(&wire).map_err(|e| AttachmentError::Encode(format!("rot json: {e}")))?;
    Ok(URL_SAFE_NO_PAD.encode(json))
}

/// Decode a single-string wire form back into the rot and its attachment bytes.
/// Inverse of [`encode_signed_rot`].
///
/// Args:
/// * `encoded`: The base64url-no-pad(JSON) wire string.
pub fn decode_signed_rot(encoded: &str) -> Result<(RotEvent, Vec<u8>), AttachmentError> {
    use base64::{Engine, engine::general_purpose::URL_SAFE_NO_PAD};
    let json = URL_SAFE_NO_PAD
        .decode(encoded)
        .map_err(|e| AttachmentError::Decode(format!("rot envelope: {e}")))?;
    let wire: WireSignedRot = serde_json::from_slice(&json)
        .map_err(|e| AttachmentError::Decode(format!("rot json: {e}")))?;
    let attachment = URL_SAFE_NO_PAD
        .decode(&wire.attachment_b64)
        .map_err(|e| AttachmentError::Decode(format!("rot attachment: {e}")))?;
    Ok((wire.event, attachment))
}

/// CESR `Seqner` qb64 width: `0A` hard code (2) + 22 base64 chars = 24.
const SEQNER_QB64_LEN: usize = 24;

/// qb64 full width of a 32-byte digest `Saider` from its leading code char.
/// Blake3-256 (`E`), Blake2b-256 (`F`), Blake2s-256 (`G`), SHA3-256 (`H`),
/// SHA2-256 (`I`) are all single-char-coded 44-char primitives. Mirrors cesride
/// `matter` sizage for the digest family auths emits.
fn saider_qb64_len(first: u8) -> Option<usize> {
    matches!(first, b'E' | b'F' | b'G' | b'H' | b'I').then_some(44)
}

/// An event paired with its detached signature(s).
///
/// Per the KERI spec, signatures are NOT part of the event body. They are
/// attached externally (CESR attachment codes in streams, or stored alongside
/// in databases). The event body is what gets hashed for the SAID.
///
/// Usage:
/// ```ignore
/// use auths_keri::{SignedEvent, IndexedSignature, Event};
///
/// // After creating and finalizing an event:
/// let signed = SignedEvent::new(event, vec![IndexedSignature { index: 0, sig: sig_bytes }]);
/// ```
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct SignedEvent {
    /// The event body (no signature data).
    pub event: Event,
    /// Controller-indexed signatures (detached from body).
    pub signatures: Vec<IndexedSignature>,
}

impl SignedEvent {
    /// Create a new signed event from an event and its signatures.
    pub fn new(event: Event, signatures: Vec<IndexedSignature>) -> Self {
        Self { event, signatures }
    }

    /// Get the SAID of the inner event.
    pub fn said(&self) -> &Said {
        self.event.said()
    }

    /// Get the sequence number of the inner event.
    pub fn sequence(&self) -> KeriSequence {
        self.event.sequence()
    }

    /// Get the identifier prefix of the inner event.
    pub fn prefix(&self) -> &Prefix {
        self.event.prefix()
    }
}

/// Serialize a list of externalized signatures to CESR text-domain
/// `-A##<siger1><siger2>…` indexed-signature group bytes.
///
/// Wire format: `-A` prefix + 2-char base64url count + each signature as
/// a CESR `Siger` (qb64). Reads back via `parse_attachment`.
pub fn serialize_attachment(signatures: &[IndexedSignature]) -> Result<Vec<u8>, AttachmentError> {
    use cesride::{Indexer, Siger, indexer};

    let mut out = String::new();
    out.push_str("-A");
    out.push_str(&encode_count_b64(signatures.len())?);

    for sig in signatures {
        // Ed25519 indexed signature (auths' sign paths produce Ed25519). A
        // distinct prior-commitment index (`prior_index != index`) needs the
        // dual-index "Big" code `2A`, which carries both indices; otherwise the
        // single-index `A` (ondex == index) keeps the legacy 88-char bytes.
        let (code, ondex) = if sig.prior_index.is_some_and(|j| j != sig.index) {
            (indexer::Codex::Ed25519_Big, sig.prior_index)
        } else {
            (indexer::Codex::Ed25519, None)
        };
        let siger = Siger::new(
            None,
            Some(sig.index),
            ondex,
            Some(code),
            Some(&sig.sig),
            None,
            None,
            None,
        )
        .map_err(|e| AttachmentError::Encode(e.to_string()))?;
        let qb64 = siger
            .qb64()
            .map_err(|e| AttachmentError::Encode(e.to_string()))?;
        out.push_str(&qb64);
    }

    Ok(out.into_bytes())
}

/// CESR Indexer hard-code length: codes whose first char is a digit (`0`–`4`)
/// are multi-char selectors; all others are single-char. Mirrors cesride's
/// `indexer` hardage (whose tables are `pub(crate)`).
fn indexer_hard_len(first: u8) -> usize {
    if first.is_ascii_digit() { 2 } else { 1 }
}

/// `(full qb64 size, ondex size)` for a CESR Indexer signature code, mirroring
/// cesride `indexer/tables.rs` (its `sizage` is `pub(crate)`, not callable here).
///
/// `os > 0` marks a dual-index ("Big") code carrying a *distinct* prior-commitment
/// index (ondex); single-index codes have `os == 0` (ondex echoes index).
fn indexer_sizage(code: &str) -> Option<(usize, usize)> {
    Some(match code {
        // single-index: Ed25519 A/B, secp256k1 C/D, P-256 E/F (+ Crt variants)
        "A" | "B" | "C" | "D" | "E" | "F" => (88, 0),
        // dual-index ("Big"): Ed25519 2A/2B, secp256k1 2C/2D, P-256 2E/2F
        "2A" | "2B" | "2C" | "2D" | "2E" | "2F" => (92, 2),
        // large/huge index variants (completeness; not emitted by auths)
        "0A" | "0B" => (156, 1),
        "3A" | "3B" => (160, 3),
        _ => return None,
    })
}

/// Parse a CESR `-A##` indexed-signature group into the constituent
/// `IndexedSignature`s.
///
/// Code-directed: each siger's width is read from its CESR hard code (so a group
/// may mix single-index `A` (88 ch) and dual-index `2A` (92 ch), or curves). A
/// signature under a dual-index code populates `prior_index` from its ondex.
pub fn parse_attachment(bytes: &[u8]) -> Result<Vec<IndexedSignature>, AttachmentError> {
    let s = std::str::from_utf8(bytes)
        .map_err(|e| AttachmentError::Decode(format!("non-utf8 attachment: {e}")))?;

    if s.is_empty() {
        return Ok(vec![]);
    }

    let (sigs, rest) = parse_sig_group(s)?;
    if !rest.is_empty() {
        return Err(AttachmentError::Decode(format!(
            "trailing bytes after signature group: {rest:?}"
        )));
    }
    Ok(sigs)
}

/// Parse one `-A` indexed-signature group at the head of `s`, returning the
/// signatures and the unconsumed remainder (e.g. a trailing `-G` source-seal
/// group on a delegated event).
fn parse_sig_group(s: &str) -> Result<(Vec<IndexedSignature>, &str), AttachmentError> {
    use cesride::{Indexer, Siger};

    // CESR qb64 is ASCII; reject non-ASCII at the boundary so the byte-offset slices
    // below cannot split a multi-byte char and panic.
    if !s.is_ascii() {
        return Err(AttachmentError::Decode("non-ASCII CESR attachment".into()));
    }
    let rest = s.strip_prefix("-A").ok_or_else(|| {
        AttachmentError::Decode("attachment must start with -A counter code".into())
    })?;
    if rest.len() < 2 {
        return Err(AttachmentError::Decode("truncated counter header".into()));
    }
    let (count_b64, body) = rest.split_at(2);
    let count = decode_count_b64(count_b64)?;

    let mut out = Vec::with_capacity(count);
    let mut cursor = body;
    for _ in 0..count {
        let first = *cursor.as_bytes().first().ok_or_else(|| {
            AttachmentError::Decode("truncated group: expected another signature".into())
        })?;
        let hs = indexer_hard_len(first);
        if cursor.len() < hs {
            return Err(AttachmentError::Decode("truncated siger hard code".into()));
        }
        let code = &cursor[..hs];
        let (fs, os) = indexer_sizage(code)
            .ok_or_else(|| AttachmentError::Decode(format!("unknown indexer code {code:?}")))?;
        if cursor.len() < fs {
            return Err(AttachmentError::Decode(format!(
                "insufficient bytes for {code} siger: need {fs}, have {}",
                cursor.len()
            )));
        }
        let (siger_qb64, remainder) = cursor.split_at(fs);
        cursor = remainder;

        let siger = Siger::new(None, None, None, None, None, None, Some(siger_qb64), None)
            .map_err(|e| AttachmentError::Decode(format!("Siger: {e}")))?;
        // A distinct prior-commitment index is carried only by dual-index codes
        // (os > 0); single-index codes report ondex == index, which is not a binding.
        let prior_index = (os > 0).then(|| siger.ondex());

        out.push(IndexedSignature {
            index: siger.index(),
            prior_index,
            sig: siger.raw(),
        });
    }

    Ok((out, cursor))
}

/// Pair an ordered KEL with its per-event CESR signature attachments,
/// producing the [`SignedEvent`]s an authenticated replay
/// ([`validate_signed_kel`](crate::validate_signed_kel)) consumes.
///
/// FAIL-CLOSED on count mismatch: a KEL whose attachment list is absent or
/// short is an *unauthenticated* KEL — it is refused here rather than letting
/// any caller fall back to a structural-only replay (the RT-002 forge). Every
/// stateless verify entrypoint (WASM, mobile FFI) routes through this one
/// definition so the refusal rule cannot drift between transports.
///
/// Args:
/// * `events`: The ordered KEL events, e.g. from [`parse_kel_json`](crate::parse_kel_json).
/// * `attachments`: One CESR `-A##` indexed-signature group per event, as raw
///   bytes (the text-domain `.cesr` form; transport encodings like hex are the
///   caller's adapter concern).
///
/// Usage:
/// ```ignore
/// let events = auths_keri::parse_kel_json(kel_json)?;
/// let signed = auths_keri::pair_kel_attachments(events, &attachment_bytes)?;
/// let state = auths_keri::validate_signed_kel(&signed, None)?;
/// ```
pub fn pair_kel_attachments(
    events: Vec<Event>,
    attachments: &[impl AsRef<[u8]>],
) -> Result<Vec<SignedEvent>, AttachmentError> {
    if attachments.len() != events.len() {
        return Err(AttachmentError::CountMismatch {
            events: events.len(),
            attachments: attachments.len(),
        });
    }
    events
        .into_iter()
        .zip(attachments)
        .map(|(event, att)| {
            // A delegated (`dip`/`drt`) event's attachment is `-A <sig> ++ -G
            // <source seal>`; a plain event's is just `-A <sig>`. The JSON body
            // of a delegated event carries no source seal (it lives in the
            // attachment), so restore it here — the bilateral delegation
            // binding then re-verifies it against the delegator KEL; it is
            // never trusted from the attachment alone.
            let (signatures, seals) = parse_delegated_attachment(att.as_ref())?;
            let event = rehydrate_source_seal(event, seals.into_iter().next());
            Ok(SignedEvent::new(event, signatures))
        })
        .collect()
}

/// Re-attach a delegated event's source seal from its parsed attachment; plain
/// events and sealless attachments pass through unchanged.
fn rehydrate_source_seal(event: Event, seal: Option<SourceSeal>) -> Event {
    let Some(seal) = seal else {
        return event;
    };
    match event {
        Event::Dip(mut e) => {
            e.source_seal = Some(seal);
            Event::Dip(e)
        }
        Event::Drt(mut e) => {
            e.source_seal = Some(seal);
            Event::Drt(e)
        }
        other => other,
    }
}

/// Error shape for attachment encode/decode.
#[derive(Debug, thiserror::Error)]
#[non_exhaustive]
pub enum AttachmentError {
    /// Encoding an indexed signature into CESR failed.
    #[error("attachment encode: {0}")]
    Encode(String),
    /// Decoding a CESR attachment stream failed (bad counter, malformed Siger, etc.).
    #[error("attachment decode: {0}")]
    Decode(String),
    /// The KEL and its attachment list disagree in length: at least one event
    /// has no signature group, so the KEL is unauthenticated. Refused outright
    /// instead of degrading to a structural-only replay.
    #[error(
        "KEL/attachment count mismatch ({events} events vs {attachments} attachments): the KEL is unauthenticated, refusing"
    )]
    CountMismatch {
        /// Number of events in the KEL.
        events: usize,
        /// Number of signature attachments supplied.
        attachments: usize,
    },
}

/// CESR base64url alphabet, ordered so `B64_ALPHA[n]` is the char for n.
const B64_ALPHA: &[u8; 64] = b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";

fn encode_count_b64(count: usize) -> Result<String, AttachmentError> {
    if count >= 64 * 64 {
        return Err(AttachmentError::Encode(format!(
            "count {count} exceeds 2-char base64url max (4095)"
        )));
    }
    let hi = B64_ALPHA[(count >> 6) & 0x3f] as char;
    let lo = B64_ALPHA[count & 0x3f] as char;
    Ok(format!("{hi}{lo}"))
}

fn decode_count_b64(s: &str) -> Result<usize, AttachmentError> {
    let mut it = s.chars();
    let hi = it
        .next()
        .and_then(b64_index)
        .ok_or_else(|| AttachmentError::Decode(format!("invalid count hi char: {s:?}")))?;
    let lo = it
        .next()
        .and_then(b64_index)
        .ok_or_else(|| AttachmentError::Decode(format!("invalid count lo char: {s:?}")))?;
    Ok((hi << 6) | lo)
}

fn b64_index(c: char) -> Option<usize> {
    B64_ALPHA.iter().position(|&b| b as char == c)
}

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

    #[test]
    fn attachment_roundtrip_single_sig() {
        let sigs = vec![IndexedSignature {
            index: 0,
            prior_index: None,
            sig: vec![0x42u8; 64],
        }];
        let bytes = serialize_attachment(&sigs).unwrap();
        let s = std::str::from_utf8(&bytes).unwrap();
        assert!(s.starts_with("-AAB"), "expected -AAB prefix, got {s:?}");
        let back = parse_attachment(&bytes).unwrap();
        assert_eq!(back.len(), 1);
        assert_eq!(back[0].index, 0);
        assert_eq!(back[0].sig, vec![0x42u8; 64]);
    }

    #[test]
    fn attachment_parsers_reject_multibyte_without_panicking() {
        // qb64 is ASCII; a multi-byte UTF-8 char in a -A signature or -G seal group
        // must fail closed, not panic on a non-char-boundary slice.
        assert!(parse_attachment("-AAB\u{42c}".as_bytes()).is_err());
        assert!(parse_delegated_attachment("-AAB\u{42c}".as_bytes()).is_err());

        // -G source-seal group with a multi-byte char straddling the Seqner slice.
        let mut seal = String::from("-GAB");
        seal.push_str(&"A".repeat(23));
        seal.push('\u{42c}');
        assert!(parse_source_seal_couples(seal.as_bytes()).is_err());
    }

    #[test]
    fn cesr_length_tables_match_cesride_encoding() {
        use cesride::{Diger, Matter, matter};
        // saider_qb64_len: pin the Blake3-256 SAID code auths emits to cesride's width.
        let digest = Diger::new(
            None,
            Some(matter::Codex::Blake3_256),
            Some(&[0u8; 32]),
            None,
            None,
            None,
        )
        .and_then(|d| d.qb64())
        .unwrap();
        assert_eq!(saider_qb64_len(digest.as_bytes()[0]), Some(digest.len()));

        // indexer_sizage: pin the single-index (`A`) and dual-index (`2A`) Ed25519 siger
        // widths auths emits, by measuring a real encoded siger (after the 4-char counter).
        for prior_index in [None, Some(1u32)] {
            let att = serialize_attachment(&[IndexedSignature {
                index: 0,
                prior_index,
                sig: vec![0u8; 64],
            }])
            .unwrap();
            let att = std::str::from_utf8(&att).unwrap();
            let siger = &att[4..];
            let code = &siger[..indexer_hard_len(siger.as_bytes()[0])];
            assert_eq!(
                indexer_sizage(code).map(|(fs, _)| fs),
                Some(siger.len()),
                "indexer_sizage({code:?}) drifted from cesride's {} chars",
                siger.len()
            );
        }
    }

    #[test]
    fn attachment_roundtrip_three_sigs() {
        let sigs = vec![
            IndexedSignature {
                index: 0,
                prior_index: None,
                sig: vec![0x01u8; 64],
            },
            IndexedSignature {
                index: 1,
                prior_index: None,
                sig: vec![0x02u8; 64],
            },
            IndexedSignature {
                index: 2,
                prior_index: None,
                sig: vec![0x03u8; 64],
            },
        ];
        let bytes = serialize_attachment(&sigs).unwrap();
        let s = std::str::from_utf8(&bytes).unwrap();
        assert!(s.starts_with("-AAD"), "expected -AAD prefix, got {s:?}");
        let back = parse_attachment(&bytes).unwrap();
        assert_eq!(back.len(), 3);
        for (i, sig) in back.iter().enumerate() {
            assert_eq!(sig.index, i as u32);
        }
    }

    #[test]
    fn attachment_empty() {
        let bytes = serialize_attachment(&[]).unwrap();
        assert_eq!(bytes, b"-AAA");
        let back = parse_attachment(&bytes).unwrap();
        assert!(back.is_empty());
    }

    #[test]
    fn keri_sequence_serializes_as_hex() {
        assert_eq!(
            serde_json::to_string(&KeriSequence::new(0)).unwrap(),
            "\"0\""
        );
        assert_eq!(
            serde_json::to_string(&KeriSequence::new(10)).unwrap(),
            "\"a\""
        );
        assert_eq!(
            serde_json::to_string(&KeriSequence::new(255)).unwrap(),
            "\"ff\""
        );
    }

    #[test]
    fn keri_sequence_deserializes_from_hex() {
        let s: KeriSequence = serde_json::from_str("\"0\"").unwrap();
        assert_eq!(s.value(), 0);
        let s: KeriSequence = serde_json::from_str("\"a\"").unwrap();
        assert_eq!(s.value(), 10);
        let s: KeriSequence = serde_json::from_str("\"ff\"").unwrap();
        assert_eq!(s.value(), 255);
    }

    #[test]
    fn keri_sequence_rejects_invalid_hex() {
        assert!(serde_json::from_str::<KeriSequence>("\"not_hex\"").is_err());
    }

    #[test]
    fn icp_event_always_serializes_d_a_c() {
        use crate::types::{CesrKey, Threshold, VersionString};
        let icp = IcpEvent {
            v: VersionString::placeholder(),
            d: Said::default(),
            i: Prefix::new_unchecked("ETest123".to_string()),
            s: KeriSequence::new(0),
            kt: Threshold::Simple(1),
            k: vec![CesrKey::new_unchecked("DKey123".to_string())],
            nt: Threshold::Simple(1),
            n: vec![Said::new_unchecked("ENext456".to_string())],
            bt: Threshold::Simple(0),
            b: vec![],
            c: vec![],
            a: vec![],
        };
        let json = serde_json::to_string(&icp).unwrap();
        // d, a, c are always serialized (spec requires all fields)
        assert!(json.contains("\"d\":"), "d must always be present");
        assert!(json.contains("\"a\":"), "a must always be present");
        assert!(json.contains("\"c\":"), "c must always be present");
        // x is still conditionally omitted (empty)
        assert!(!json.contains("\"x\":"), "empty x must be omitted");
        assert!(json.contains("\"s\":\"0\""), "s must serialize as hex");
    }

    #[test]
    fn event_enum_deserializes_by_t_field() {
        let json = r#"{"v":"KERI10JSON000000_","t":"icp","d":"ETestSaid","i":"E123","s":"0","kt":"1","k":["DKey"],"nt":"1","n":["ENext"],"bt":"0","b":[]}"#;
        let event: Event = serde_json::from_str(json).unwrap();
        assert!(event.is_inception());
        assert_eq!(event.sequence().value(), 0);
    }

    #[test]
    fn digest_seal_roundtrips() {
        let seal = Seal::digest("EDigest123");
        let json = serde_json::to_string(&seal).unwrap();
        assert_eq!(json, r#"{"d":"EDigest123"}"#);
        let parsed: Seal = serde_json::from_str(&json).unwrap();
        assert_eq!(seal, parsed);
    }

    #[test]
    fn seal_event_location_roundtrips() {
        // A.8 (F-36): the KERI §7 event-location seal {i,s,p,t,d} round-trips.
        let seal = Seal::EventLocation {
            i: Prefix::new_unchecked("EPrefix".to_string()),
            s: KeriSequence::new(3),
            p: Said::new_unchecked("EPrior".to_string()),
            t: "ixn".to_string(),
            d: Said::new_unchecked("EDigest".to_string()),
        };
        let json = serde_json::to_string(&seal).unwrap();
        let parsed: Seal = serde_json::from_str(&json).unwrap();
        assert_eq!(seal, parsed);
        assert_eq!(parsed.digest_value().map(|d| d.as_str()), Some("EDigest"));
    }

    #[test]
    fn seal_rejects_malformed_i_s() {
        // A.8 (F-37): a malformed {i,s} seal (no d) must error, not silently
        // collapse to a LatestEstablishment {i} that drops `s`.
        let r: Result<Seal, _> = serde_json::from_str(r#"{"i":"EPrefix","s":"3"}"#);
        assert!(r.is_err(), "malformed {{i,s}} seal must be rejected");
        // and an entirely unknown field set errors too.
        let r2: Result<Seal, _> = serde_json::from_str(r#"{"zz":"x"}"#);
        assert!(r2.is_err());
    }

    #[test]
    fn key_event_seal_roundtrips() {
        let seal = Seal::key_event(
            Prefix::new_unchecked("EPrefix".to_string()),
            KeriSequence::new(1),
            Said::new_unchecked("ESaid".to_string()),
        );
        let json = serde_json::to_string(&seal).unwrap();
        let parsed: Seal = serde_json::from_str(&json).unwrap();
        assert_eq!(seal, parsed);
    }

    #[test]
    fn indexed_signature_serde_roundtrip() {
        let sig = IndexedSignature {
            index: 2,
            prior_index: None,
            sig: vec![0xab; 64],
        };
        let json = serde_json::to_string(&sig).unwrap();
        assert!(json.contains("\"index\":2"));
        assert!(
            !json.contains("prior_index"),
            "a None prior_index must be omitted from the wire: {json}"
        );
        let parsed: IndexedSignature = serde_json::from_str(&json).unwrap();
        assert_eq!(parsed, sig);
    }

    #[test]
    fn signed_event_accessors() {
        use crate::types::{CesrKey, Threshold, VersionString};
        let icp = IcpEvent {
            v: VersionString::placeholder(),
            d: Said::new_unchecked("ESAID123".to_string()),
            i: Prefix::new_unchecked("EPrefix".to_string()),
            s: KeriSequence::new(0),
            kt: Threshold::Simple(1),
            k: vec![CesrKey::new_unchecked("DKey".to_string())],
            nt: Threshold::Simple(1),
            n: vec![Said::new_unchecked("ENext".to_string())],
            bt: Threshold::Simple(0),
            b: vec![],
            c: vec![],
            a: vec![],
        };
        let signed = SignedEvent::new(
            Event::Icp(icp),
            vec![IndexedSignature {
                index: 0,
                prior_index: None,
                sig: vec![0u8; 64],
            }],
        );
        assert_eq!(signed.said().as_str(), "ESAID123");
        assert_eq!(signed.sequence().value(), 0);
        assert_eq!(signed.prefix().as_str(), "EPrefix");
        assert_eq!(signed.signatures.len(), 1);
        assert_eq!(signed.signatures[0].index, 0);
    }

    #[test]
    fn seal_digest_value() {
        let seal = Seal::digest("ETest123");
        assert_eq!(seal.digest_value().unwrap().as_str(), "ETest123");
        let latest = Seal::LatestEstablishment {
            i: Prefix::new_unchecked("EPrefix".to_string()),
        };
        assert!(latest.digest_value().is_none());
    }
}