lib

Core libraries for Radroots
git clone https://radroots.dev/git/lib.git
Log | Files | Refs | README

nip17.rs (16708B)


      1 //! Focused NIP-17/NIP-59 message wrapping and unwrapping.
      2 //!
      3 //! This module creates and opens protocol events only. Relay selection,
      4 //! delivery, retries, persistence, and runtime ownership remain outside this
      5 //! crate.
      6 
      7 #![forbid(unsafe_code)]
      8 
      9 extern crate alloc;
     10 
     11 use alloc::{string::String, vec::Vec};
     12 
     13 use nostr::nips::nip59;
     14 use nostr::{
     15     Event, EventBuilder, Kind, NostrSigner, PublicKey, Tag, TagKind, Timestamp, UnsignedEvent,
     16 };
     17 use radroots_event::envelope::kind::{KIND_MESSAGE, KIND_MESSAGE_FILE};
     18 use radroots_event::social::message::Message;
     19 use radroots_event::social::message_file::MessageFile;
     20 use radroots_event::wire::Nip01EventWireParts;
     21 use radroots_event_codec::decode::RadrootsParsedData;
     22 use radroots_event_codec::decode::message_file as message_file_decode;
     23 use radroots_event_codec::decode::{EventParseError, message as message_decode};
     24 use radroots_event_codec::encode::message_file as message_file_encode;
     25 use radroots_event_codec::encode::{EventEncodeError, message as message_encode};
     26 
     27 mod opening;
     28 
     29 /// Stable, source-redacted failures from the focused NIP-17 adapter.
     30 #[derive(Clone, Debug, PartialEq, Eq)]
     31 #[non_exhaustive]
     32 pub enum Error {
     33     MessageEncode,
     34     MessageDecode,
     35     GiftWrap,
     36     Signer,
     37     InvalidRecipient,
     38     UnsupportedRumorKind { kind: u32 },
     39 }
     40 
     41 impl Error {
     42     /// Returns a stable machine-readable failure code.
     43     #[must_use]
     44     pub const fn code(&self) -> &'static str {
     45         match self {
     46             Self::MessageEncode => "message_encode",
     47             Self::MessageDecode => "message_decode",
     48             Self::GiftWrap => "gift_wrap",
     49             Self::Signer => "signer",
     50             Self::InvalidRecipient => "invalid_recipient",
     51             Self::UnsupportedRumorKind { .. } => "unsupported_rumor_kind",
     52         }
     53     }
     54 }
     55 
     56 impl core::fmt::Display for Error {
     57     fn fmt(&self, formatter: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
     58         match self {
     59             Self::MessageEncode => formatter.write_str("failed to encode NIP-17 message"),
     60             Self::MessageDecode => formatter.write_str("failed to decode NIP-17 message"),
     61             Self::GiftWrap => formatter.write_str("failed to process NIP-59 gift wrap"),
     62             Self::Signer => formatter.write_str("NIP-17 signer failed"),
     63             Self::InvalidRecipient => formatter.write_str("NIP-17 recipient is invalid"),
     64             Self::UnsupportedRumorKind { kind } => {
     65                 write!(formatter, "unsupported NIP-17 rumor kind {kind}")
     66             }
     67         }
     68     }
     69 }
     70 
     71 impl core::error::Error for Error {}
     72 
     73 impl From<EventEncodeError> for Error {
     74     fn from(_: EventEncodeError) -> Self {
     75         Self::MessageEncode
     76     }
     77 }
     78 
     79 impl From<EventParseError> for Error {
     80     fn from(_: EventParseError) -> Self {
     81         Self::MessageDecode
     82     }
     83 }
     84 
     85 impl From<nip59::Error> for Error {
     86     fn from(_: nip59::Error) -> Self {
     87         Self::GiftWrap
     88     }
     89 }
     90 
     91 impl From<nostr::event::builder::Error> for Error {
     92     fn from(_: nostr::event::builder::Error) -> Self {
     93         Self::GiftWrap
     94     }
     95 }
     96 
     97 impl From<nostr::signer::SignerError> for Error {
     98     fn from(_: nostr::signer::SignerError) -> Self {
     99         Self::Signer
    100     }
    101 }
    102 
    103 impl From<nostr::key::Error> for Error {
    104     fn from(_: nostr::key::Error) -> Self {
    105         Self::InvalidRecipient
    106     }
    107 }
    108 
    109 #[derive(Clone)]
    110 pub enum Rumor {
    111     Message(RadrootsParsedData<Message>),
    112     MessageFile(Box<RadrootsParsedData<MessageFile>>),
    113 }
    114 
    115 impl core::fmt::Debug for Rumor {
    116     fn fmt(&self, formatter: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
    117         match self {
    118             Self::Message(_) => formatter
    119                 .debug_struct("Rumor::Message")
    120                 .finish_non_exhaustive(),
    121             Self::MessageFile(_) => formatter
    122                 .debug_struct("Rumor::MessageFile")
    123                 .finish_non_exhaustive(),
    124         }
    125     }
    126 }
    127 
    128 #[derive(Clone, Debug)]
    129 pub struct WrapOptions {
    130     include_sender: bool,
    131     rumor_created_at: Option<u64>,
    132     gift_wrap_tags: Vec<Vec<String>>,
    133 }
    134 
    135 impl Default for WrapOptions {
    136     fn default() -> Self {
    137         Self {
    138             include_sender: true,
    139             rumor_created_at: None,
    140             gift_wrap_tags: Vec::new(),
    141         }
    142     }
    143 }
    144 
    145 impl WrapOptions {
    146     #[must_use]
    147     pub fn include_sender(mut self, include_sender: bool) -> Self {
    148         self.include_sender = include_sender;
    149         self
    150     }
    151 
    152     #[must_use]
    153     pub fn with_rumor_created_at(mut self, created_at: u64) -> Self {
    154         self.rumor_created_at = Some(created_at);
    155         self
    156     }
    157 
    158     #[must_use]
    159     pub fn with_gift_wrap_tags(mut self, tags: Vec<Vec<String>>) -> Self {
    160         self.gift_wrap_tags = tags;
    161         self
    162     }
    163 
    164     pub const fn includes_sender(&self) -> bool {
    165         self.include_sender
    166     }
    167 
    168     pub const fn rumor_created_at(&self) -> Option<u64> {
    169         self.rumor_created_at
    170     }
    171 
    172     pub fn gift_wrap_tags(&self) -> &[Vec<String>] {
    173         &self.gift_wrap_tags
    174     }
    175 }
    176 
    177 fn tags_from_slices(tag_slices: &[Vec<String>]) -> Vec<Tag> {
    178     let mut tags = Vec::with_capacity(tag_slices.len());
    179     for slice in tag_slices {
    180         if slice.is_empty() {
    181             continue;
    182         }
    183         let key = slice[0].clone();
    184         let values = slice[1..].to_vec();
    185         tags.push(Tag::custom(TagKind::Custom(key.into()), values));
    186     }
    187     tags
    188 }
    189 
    190 fn rumor_from_parts(
    191     parts: Nip01EventWireParts,
    192     author: PublicKey,
    193     created_at: Option<u64>,
    194 ) -> Result<UnsignedEvent, Error> {
    195     let kind =
    196         u16::try_from(parts.kind).map_err(|_| Error::UnsupportedRumorKind { kind: parts.kind })?;
    197     let tags = tags_from_slices(&parts.tags);
    198     let timestamp = match created_at {
    199         Some(ts) => Timestamp::from_secs(ts),
    200         None => Timestamp::now(),
    201     };
    202     let mut rumor = UnsignedEvent::new(author, timestamp, Kind::Custom(kind), tags, parts.content);
    203     rumor.ensure_id();
    204     Ok(rumor)
    205 }
    206 
    207 fn parse_recipients(
    208     recipients: &[radroots_event::social::message::MessageRecipient],
    209 ) -> Result<Vec<PublicKey>, Error> {
    210     let mut out = Vec::with_capacity(recipients.len());
    211     for recipient in recipients {
    212         out.push(recipient.public_key.parse::<PublicKey>()?);
    213     }
    214     Ok(out)
    215 }
    216 
    217 fn push_unique(recipients: &mut Vec<PublicKey>, pubkey: PublicKey) {
    218     if recipients.iter().any(|r| r == &pubkey) {
    219         return;
    220     }
    221     recipients.push(pubkey);
    222 }
    223 
    224 async fn wrap_rumor<T>(
    225     signer: &T,
    226     rumor: UnsignedEvent,
    227     mut recipients: Vec<PublicKey>,
    228     options: &WrapOptions,
    229 ) -> Result<Vec<Event>, Error>
    230 where
    231     T: NostrSigner,
    232 {
    233     let sender_pubkey = signer.get_public_key().await?;
    234     if options.include_sender {
    235         push_unique(&mut recipients, sender_pubkey);
    236     }
    237     let extra_tags = tags_from_slices(&options.gift_wrap_tags);
    238 
    239     let mut out = Vec::with_capacity(recipients.len());
    240     for recipient in recipients {
    241         let event =
    242             EventBuilder::gift_wrap(signer, &recipient, rumor.clone(), extra_tags.clone()).await?;
    243         out.push(event);
    244     }
    245     Ok(out)
    246 }
    247 
    248 pub async fn wrap_message<T>(
    249     signer: &T,
    250     message: &Message,
    251     options: WrapOptions,
    252 ) -> Result<Vec<Event>, Error>
    253 where
    254     T: NostrSigner,
    255 {
    256     let parts = message_encode::to_wire_parts(message)?;
    257     let author = signer.get_public_key().await?;
    258     let rumor = rumor_from_parts(parts, author, options.rumor_created_at)?;
    259     let recipients = parse_recipients(&message.recipients)?;
    260     wrap_rumor(signer, rumor, recipients, &options).await
    261 }
    262 
    263 pub async fn wrap_message_file<T>(
    264     signer: &T,
    265     message: &MessageFile,
    266     options: WrapOptions,
    267 ) -> Result<Vec<Event>, Error>
    268 where
    269     T: NostrSigner,
    270 {
    271     let parts = message_file_encode::to_wire_parts(message)?;
    272     let author = signer.get_public_key().await?;
    273     let rumor = rumor_from_parts(parts, author, options.rumor_created_at)?;
    274     let recipients = parse_recipients(&message.recipients)?;
    275     wrap_rumor(signer, rumor, recipients, &options).await
    276 }
    277 
    278 pub async fn unwrap_gift_wrap<T>(signer: &T, gift_wrap: &Event) -> Result<Rumor, Error>
    279 where
    280     T: NostrSigner,
    281 {
    282     let mut opened = opening::open(signer, gift_wrap).await?;
    283     let rumor = &mut opened.0;
    284     let id = rumor.id().to_string();
    285     let author = rumor.pubkey.to_string();
    286     let published_at = rumor.created_at.as_secs();
    287     let kind = rumor.kind.as_u16() as u32;
    288     let tags: Vec<Vec<String>> = rumor
    289         .tags
    290         .as_slice()
    291         .iter()
    292         .map(|t| t.as_slice().to_vec())
    293         .collect();
    294     let content = rumor.content.clone();
    295 
    296     match kind {
    297         KIND_MESSAGE => {
    298             let metadata =
    299                 message_decode::data_from_event(id, author, published_at, kind, content, tags)?;
    300             Ok(Rumor::Message(metadata))
    301         }
    302         KIND_MESSAGE_FILE => {
    303             let metadata = message_file_decode::data_from_event(
    304                 id,
    305                 author,
    306                 published_at,
    307                 kind,
    308                 content,
    309                 tags,
    310             )?;
    311             Ok(Rumor::MessageFile(Box::new(metadata)))
    312         }
    313         other => Err(Error::UnsupportedRumorKind { kind: other }),
    314     }
    315 }
    316 
    317 #[cfg(all(test, feature = "nip17"))]
    318 mod opening_tests;
    319 
    320 #[cfg(all(test, feature = "nip17"))]
    321 mod tests {
    322     use super::*;
    323     use crate::test_fixtures::{FIXTURE_ALICE, FIXTURE_BOB};
    324     use nostr::{Keys, SecretKey};
    325     use radroots_event::social::message::{Message, MessageRecipient};
    326     use radroots_event::social::message_file::{MessageFile, MessageFileDimensions};
    327 
    328     fn sender_keys() -> Keys {
    329         Keys::new(SecretKey::from_hex(FIXTURE_ALICE.secret_key_hex).unwrap())
    330     }
    331 
    332     fn receiver_keys() -> Keys {
    333         Keys::new(SecretKey::from_hex(FIXTURE_BOB.secret_key_hex).unwrap())
    334     }
    335 
    336     #[test]
    337     fn rumor_kind_conversion_is_range_checked() {
    338         let author = sender_keys().public_key();
    339         let max = rumor_from_parts(
    340             Nip01EventWireParts {
    341                 kind: u32::from(u16::MAX),
    342                 content: String::new(),
    343                 tags: Vec::new(),
    344             },
    345             author,
    346             Some(1_700_000_000),
    347         )
    348         .expect("maximum NIP-01 kind");
    349         assert_eq!(max.kind.as_u16(), u16::MAX);
    350 
    351         let overflow = u32::from(u16::MAX) + 1;
    352         assert!(matches!(
    353             rumor_from_parts(
    354                 Nip01EventWireParts {
    355                     kind: overflow,
    356                     content: String::new(),
    357                     tags: Vec::new(),
    358                 },
    359                 author,
    360                 Some(1_700_000_000),
    361             ),
    362             Err(Error::UnsupportedRumorKind { kind }) if kind == overflow
    363         ));
    364     }
    365 
    366     #[test]
    367     fn adapter_error_codes_are_stable_and_source_redacted() {
    368         let errors = [
    369             Error::MessageEncode,
    370             Error::MessageDecode,
    371             Error::GiftWrap,
    372             Error::Signer,
    373             Error::InvalidRecipient,
    374             Error::UnsupportedRumorKind { kind: 70_000 },
    375         ];
    376         assert_eq!(
    377             errors.iter().map(Error::code).collect::<Vec<_>>(),
    378             vec![
    379                 "message_encode",
    380                 "message_decode",
    381                 "gift_wrap",
    382                 "signer",
    383                 "invalid_recipient",
    384                 "unsupported_rumor_kind",
    385             ]
    386         );
    387         for error in &errors {
    388             let rendered = format!("{error:?} {error}");
    389             assert!(!rendered.contains("nsec"));
    390             assert!(!rendered.contains("private"));
    391         }
    392     }
    393 
    394     #[tokio::test]
    395     async fn sender_recovery_uses_one_wrap_even_when_already_a_recipient() {
    396         let sender = sender_keys();
    397         let receiver = receiver_keys();
    398         for already_included in [false, true] {
    399             let mut recipients = vec![MessageRecipient {
    400                 public_key: receiver.public_key().to_string(),
    401                 relay_url: None,
    402             }];
    403             if already_included {
    404                 recipients.push(MessageRecipient {
    405                     public_key: sender.public_key().to_string(),
    406                     relay_url: None,
    407                 });
    408             }
    409             let message = Message {
    410                 recipients,
    411                 content: "synthetic sender recovery inquiry".to_owned(),
    412                 reply_to: None,
    413                 subject: None,
    414             };
    415             let options = WrapOptions::default()
    416                 .with_rumor_created_at(1_700_000_002)
    417                 .with_gift_wrap_tags(vec![Vec::new(), vec!["client".into(), "fixture".into()]]);
    418             assert!(options.includes_sender());
    419             assert_eq!(options.rumor_created_at(), Some(1_700_000_002));
    420             assert_eq!(options.gift_wrap_tags().len(), 2);
    421             let events = wrap_message(&sender, &message, options).await.unwrap();
    422             assert_eq!(events.len(), 2);
    423             for participant in [&sender, &receiver] {
    424                 let recipient = participant.public_key().to_string();
    425                 let addressed: Vec<_> = events
    426                     .iter()
    427                     .filter(|event| {
    428                         event
    429                             .tags
    430                             .iter()
    431                             .any(|tag| tag.as_slice() == ["p".to_owned(), recipient.clone()])
    432                     })
    433                     .collect();
    434                 assert_eq!(addressed.len(), 1);
    435                 match unwrap_gift_wrap(participant, addressed[0]).await.unwrap() {
    436                     Rumor::Message(metadata) => assert_eq!(metadata.data.content, message.content),
    437                     other => panic!("expected recovered message, got {other:?}"),
    438                 }
    439             }
    440         }
    441     }
    442 
    443     #[tokio::test]
    444     async fn wrap_and_unwrap_message() {
    445         let sender = sender_keys();
    446         let receiver = receiver_keys();
    447         let message = Message {
    448             recipients: vec![MessageRecipient {
    449                 public_key: receiver.public_key().to_string(),
    450                 relay_url: None,
    451             }],
    452             content: "hello".to_string(),
    453             reply_to: None,
    454             subject: None,
    455         };
    456         let options = WrapOptions::default()
    457             .include_sender(false)
    458             .with_rumor_created_at(1_700_000_000);
    459 
    460         let events = wrap_message(&sender, &message, options).await.unwrap();
    461         assert_eq!(events.len(), 1);
    462 
    463         let rumor = unwrap_gift_wrap(&receiver, &events[0]).await.unwrap();
    464         match rumor {
    465             Rumor::Message(metadata) => {
    466                 assert_eq!(metadata.data.content, "hello");
    467                 assert_eq!(metadata.data.recipients.len(), 1);
    468             }
    469             other => panic!("expected message rumor, got {other:?}"),
    470         }
    471     }
    472 
    473     #[tokio::test]
    474     async fn wrap_and_unwrap_message_file() {
    475         let sender = sender_keys();
    476         let receiver = receiver_keys();
    477         let message = MessageFile {
    478             recipients: vec![MessageRecipient {
    479                 public_key: receiver.public_key().to_string(),
    480                 relay_url: None,
    481             }],
    482             file_url: "https://files.example/encrypted.bin".to_string(),
    483             reply_to: None,
    484             subject: None,
    485             file_type: "image/jpeg".to_string(),
    486             encryption_algorithm: "aes-gcm".to_string(),
    487             decryption_key: "key".to_string(),
    488             decryption_nonce: "nonce".to_string(),
    489             encrypted_hash: "hash".to_string(),
    490             original_hash: None,
    491             size: Some(1200),
    492             dimensions: Some(MessageFileDimensions { w: 1200, h: 800 }),
    493             blurhash: None,
    494             thumb: None,
    495             fallbacks: Vec::new(),
    496         };
    497         let options = WrapOptions::default()
    498             .include_sender(false)
    499             .with_rumor_created_at(1_700_000_001);
    500 
    501         let events = wrap_message_file(&sender, &message, options).await.unwrap();
    502         assert_eq!(events.len(), 1);
    503 
    504         let rumor = unwrap_gift_wrap(&receiver, &events[0]).await.unwrap();
    505         let rendered = format!("{rumor:?}");
    506         for private_value in [
    507             message.file_url.as_str(),
    508             message.decryption_key.as_str(),
    509             message.decryption_nonce.as_str(),
    510             message.encrypted_hash.as_str(),
    511         ] {
    512             assert!(!rendered.contains(private_value));
    513         }
    514         match rumor {
    515             Rumor::MessageFile(metadata) => {
    516                 assert_eq!(metadata.data.file_url, message.file_url);
    517                 assert_eq!(metadata.data.encrypted_hash, message.encrypted_hash);
    518             }
    519             other => panic!("expected message file rumor, got {other:?}"),
    520         }
    521     }
    522 }