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 }