lib

verification.rs (13277B)

---

 //! Native event verification typestates.
 //!
 //! The types in this module make the ordered NIP-01 validation stages explicit.
 //! Their representations are private so a later stage can only be obtained by
 //! consuming the immediately preceding stage and successfully enforcing its
 //! invariant.
 
 use core::fmt;
 
 use crate::{
     contract::registry_v7::{
         ContractValidationError, EventContract, validate_event_contract_for_admission,
         validate_event_contract_registry_v7,
     },
     envelope::EventEnvelope,
     id::EventId,
     wire::compute_canonical_nip01_event_id,
 };
 
 /// A structurally valid event whose canonical identifier is not yet trusted.
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct RawEvent(EventEnvelope);
 
 impl RawEvent {
     #[must_use]
     pub const fn new(event: EventEnvelope) -> Self {
         Self(event)
     }
 
     #[must_use]
     pub const fn event(&self) -> &EventEnvelope {
         &self.0
     }
 
     #[must_use]
     pub fn into_event(self) -> EventEnvelope {
         self.0
     }
 
     /// Recomputes and verifies the canonical NIP-01 event identifier.
     pub fn verify_id(self) -> Result<IdVerifiedEvent, Error> {
         let expected = compute_canonical_nip01_event_id(
             &self.0.author().to_hex(),
             self.0.created_at_u64(),
             self.0.kind_u32(),
             &self.0.tags_as_vec(),
             self.0.content(),
         )
         .map_err(|_| Error::MalformedEnvelope)?;
         let actual = *self.0.id();
         if actual != expected {
             return Err(Error::IdMismatch { expected, actual });
         }
         Ok(IdVerifiedEvent(self.0))
     }
 }
 
 /// An event whose declared identifier matches its canonical NIP-01 digest.
 ///
 /// Its private representation rejects forged transitions:
 ///
 /// ```compile_fail
 /// use radroots_event::admission::{IdVerifiedEvent, RawEvent};
 ///
 /// fn forge(raw: RawEvent) -> IdVerifiedEvent {
 ///     IdVerifiedEvent(raw.into_event())
 /// }
 /// ```
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct IdVerifiedEvent(EventEnvelope);
 
 impl IdVerifiedEvent {
     #[must_use]
     pub const fn event(&self) -> &EventEnvelope {
         &self.0
     }
 
     #[must_use]
     pub fn into_event(self) -> EventEnvelope {
         self.0
     }
 
     /// Uses an explicit host capability to verify the signature over the
     /// already verified event ID.
     pub fn verify_signature<V>(self, verifier: &V) -> Result<SignatureVerifiedEvent, Error>
     where
         V: SignatureVerifier + ?Sized,
     {
         verifier.verify_signature(&self.0)?;
         Ok(SignatureVerifiedEvent(self.0))
     }
 }
 
 /// **Host SPI:** verifies an event signature.
 ///
 /// The event crate owns the verification state transition, while concrete
 /// cryptographic implementations belong to codec or signing crates. Downstream
 /// implementations are supported and must normalize rejection to
 /// [`Error::SignatureInvalid`]. The trait is dyn-compatible and requires
 /// `Send + Sync`; verification is a synchronous, deterministic, side-effect-free
 /// operation with no cancellation or deadline boundary and must not durably
 /// commit state.
 pub trait SignatureVerifier: Send + Sync {
     /// Returns success only when the envelope's signature is valid for its
     /// already verified canonical event identifier.
     fn verify_signature(&self, event: &EventEnvelope) -> Result<(), Error>;
 }
 
 /// An event whose canonical identifier and BIP-340 signature are verified.
 ///
 /// ```compile_fail
 /// use radroots_event::admission::{IdVerifiedEvent, SignatureVerifiedEvent};
 ///
 /// fn bypass_signature(event: IdVerifiedEvent) -> SignatureVerifiedEvent {
 ///     SignatureVerifiedEvent::new(event.into_event())
 /// }
 /// ```
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct SignatureVerifiedEvent(EventEnvelope);
 
 impl SignatureVerifiedEvent {
     #[must_use]
     pub const fn event(&self) -> &EventEnvelope {
         &self.0
     }
 
     #[must_use]
     pub fn into_event(self) -> EventEnvelope {
         self.0
     }
 
     /// Validates the event against the immutable registry-v7 contract set.
     pub fn validate_contract(self) -> Result<ContractValidatedEvent, Error> {
         let contract =
             validate_event_contract_registry_v7(&self.0).map_err(Error::ContractValidation)?;
         Ok(ContractValidatedEvent {
             event: self,
             contract,
         })
     }
 
     /// Validates a contract selected explicitly by the admission boundary.
     ///
     /// This transition supports profiles such as root updates, replies,
     /// comments, and deletion requests that intentionally cannot be selected
     /// solely from their public Nostr wire shape.
     pub fn validate_contract_for_admission(
         self,
         contract_id: &str,
     ) -> Result<ContractValidatedEvent, Error> {
         let contract = validate_event_contract_for_admission(&self.0, contract_id)
             .map_err(Error::ContractValidation)?;
         Ok(ContractValidatedEvent {
             event: self,
             contract,
         })
     }
 }
 
 /// A signature-verified event whose registry-selected contract is valid.
 ///
 /// ```compile_fail
 /// use radroots_event::admission::{ContractValidatedEvent, SignatureVerifiedEvent};
 ///
 /// fn bypass_contract(event: SignatureVerifiedEvent) -> ContractValidatedEvent {
 ///     ContractValidatedEvent::from(event)
 /// }
 /// ```
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct ContractValidatedEvent {
     event: SignatureVerifiedEvent,
     contract: &'static EventContract,
 }
 
 impl ContractValidatedEvent {
     #[must_use]
     pub const fn verified_event(&self) -> &SignatureVerifiedEvent {
         &self.event
     }
 
     #[must_use]
     pub const fn event(&self) -> &EventEnvelope {
         self.event.event()
     }
 
     #[must_use]
     pub const fn contract(&self) -> &'static EventContract {
         self.contract
     }
 
     #[must_use]
     pub const fn contract_id(&self) -> &'static str {
         self.contract.id
     }
 
     #[must_use]
     pub fn into_verified_event(self) -> SignatureVerifiedEvent {
         self.event
     }
 
     #[must_use]
     pub fn into_event(self) -> EventEnvelope {
         self.event.into_event()
     }
 }
 
 /// A failure while advancing an event verification typestate.
 #[non_exhaustive]
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub enum Error {
     MalformedEnvelope,
     IdMismatch { expected: EventId, actual: EventId },
     SignatureInvalid,
     ContractValidation(ContractValidationError),
 }
 
 impl Error {
     #[must_use]
     pub const fn code(&self) -> &'static str {
         match self {
             Self::MalformedEnvelope => "malformed_envelope",
             Self::IdMismatch { .. } => "id_mismatch",
             Self::SignatureInvalid => "signature_invalid",
             Self::ContractValidation(_) => "contract_validation",
         }
     }
 }
 
 impl fmt::Display for Error {
     fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
         match self {
             Self::MalformedEnvelope => formatter.write_str("malformed NIP-01 event envelope"),
             Self::IdMismatch { expected, actual } => write!(
                 formatter,
                 "NIP-01 event id mismatch: expected {}, got {}",
                 expected.to_hex(),
                 actual.to_hex()
             ),
             Self::SignatureInvalid => formatter.write_str("invalid NIP-01 event signature"),
             Self::ContractValidation(error) => {
                 write!(
                     formatter,
                     "event contract validation failed: {}",
                     error.code()
                 )
             }
         }
     }
 }
 
 #[cfg(feature = "std")]
 impl std::error::Error for Error {}
 
 #[cfg(test)]
 #[cfg_attr(coverage_nightly, coverage(off))]
 mod tests {
     use super::*;
     use crate::envelope::EventEnvelopeParts;
 
     struct Accept;
 
     impl SignatureVerifier for Accept {
         fn verify_signature(&self, _event: &EventEnvelope) -> Result<(), Error> {
             Ok(())
         }
     }
 
     struct Reject;
 
     impl SignatureVerifier for Reject {
         fn verify_signature(&self, _event: &EventEnvelope) -> Result<(), Error> {
             Err(Error::SignatureInvalid)
         }
     }
 
     fn valid_profile_event() -> EventEnvelope {
         EventEnvelope::new(EventEnvelopeParts {
             id: "762bee187e9e645b81ec26ade05a69b5e8398caf527be8de0d9a45311ed0c7a0"
                 .to_owned(),
             author: "585591529da0bab31b3b1b1f986611cf5f435dca84f978c89ee8a40cca7103df"
                 .to_owned(),
             created_at: 1_800_000_100,
             kind: 0,
             tags: vec![],
             content: "{\"display_name\":\"Moss Street Farm\",\"bot\":false,\"website\":\"https://mossstreet.example\",\"picture\":42}".to_owned(),
             sig: "4290da0bb6422986647bc8cd5f63bd52d49f41e7b665d3b47105b8109183e8d596f322c531d4061df53e1d2b70fda12d5d1c14f3720d7a56d9d0a03746af5109".to_owned(),
         })
         .expect("valid profile event")
     }
 
     #[test]
     fn raw_event_advances_only_after_id_verification() {
         let verified = RawEvent::new(valid_profile_event())
             .verify_id()
             .expect("verified id");
         assert_eq!(
             verified.event().id().to_hex(),
             "762bee187e9e645b81ec26ade05a69b5e8398caf527be8de0d9a45311ed0c7a0"
         );
     }
 
     #[test]
     fn positive_vector_reaches_contract_validated_state() {
         let verifier: &dyn SignatureVerifier = &Accept;
         let validated = RawEvent::new(valid_profile_event())
             .verify_id()
             .expect("verified id")
             .verify_signature(verifier)
             .expect("verified signature")
             .validate_contract()
             .expect("validated contract");
         assert_eq!(validated.contract_id(), "radroots.profile.metadata.v1");
     }
 
     #[test]
     fn signature_transition_fails_closed_when_verifier_rejects() {
         let error = RawEvent::new(valid_profile_event())
             .verify_id()
             .expect("verified id")
             .verify_signature(&Reject)
             .expect_err("signature must be rejected");
         assert_eq!(error, Error::SignatureInvalid);
     }
 
     #[test]
     fn typestate_accessors_and_consuming_transitions_preserve_the_envelope() {
         let envelope = valid_profile_event();
         let raw = RawEvent::new(envelope.clone());
         assert_eq!(raw.event(), &envelope);
         assert_eq!(raw.clone().into_event(), envelope);
 
         let id_verified = raw.verify_id().unwrap();
         assert_eq!(id_verified.event().kind_u32(), 0);
         assert_eq!(id_verified.clone().into_event().kind_u32(), 0);
         let signature_verified = id_verified.verify_signature(&Accept).unwrap();
         assert_eq!(signature_verified.event().kind_u32(), 0);
         assert_eq!(signature_verified.clone().into_event().kind_u32(), 0);
 
         let validated = signature_verified.validate_contract().unwrap();
         assert_eq!(validated.verified_event().event(), validated.event());
         assert_eq!(validated.contract().id, validated.contract_id());
         assert_eq!(
             validated.clone().into_verified_event().event().kind_u32(),
             0
         );
         assert_eq!(validated.into_event().kind_u32(), 0);
     }
 
     #[test]
     fn id_and_contract_failures_are_typed_and_diagnostic() {
         let wrong_id = EventEnvelope::new(EventEnvelopeParts {
             id: "0".repeat(64),
             author: "585591529da0bab31b3b1b1f986611cf5f435dca84f978c89ee8a40cca7103df".to_owned(),
             created_at: 1_800_000_100,
             kind: 0,
             tags: vec![],
             content: "{}".to_owned(),
             sig: "0".repeat(128),
         })
         .unwrap();
         assert!(matches!(
             RawEvent::new(wrong_id).verify_id(),
             Err(Error::IdMismatch { .. })
         ));
 
         let unknown = envelope_with_computed_id(65_535, vec![], "{}");
         let error = RawEvent::new(unknown)
             .verify_id()
             .unwrap()
             .verify_signature(&Accept)
             .unwrap()
             .validate_contract()
             .unwrap_err();
         assert!(matches!(error, Error::ContractValidation(_)));
 
         let errors = [
             Error::MalformedEnvelope,
             Error::IdMismatch {
                 expected: EventId::parse("1".repeat(64)).unwrap(),
                 actual: EventId::parse("2".repeat(64)).unwrap(),
             },
             Error::SignatureInvalid,
             error,
         ];
         for error in errors {
             assert!(!error.code().is_empty());
             assert!(!error.to_string().is_empty());
         }
     }
 
     fn envelope_with_computed_id(
         kind: u32,
         tags: Vec<Vec<String>>,
         content: &str,
     ) -> EventEnvelope {
         let author = "585591529da0bab31b3b1b1f986611cf5f435dca84f978c89ee8a40cca7103df";
         let created_at = 1_800_000_100;
         let id =
             compute_canonical_nip01_event_id(author, created_at, kind, &tags, content).unwrap();
         EventEnvelope::new(EventEnvelopeParts {
             id: id.to_hex(),
             author: author.to_owned(),
             created_at,
             kind,
             tags,
             content: content.to_owned(),
             sig: "0".repeat(128),
         })
         .unwrap()
     }
 }