softchat/

envelope.rs

//! Validated NIP-59 private-envelope construction and reading.

#![allow(
    unreachable_pub,
    reason = "UniFFI adapter records stay inside this private core module"
)]

use nostr::Keys;
use nostr::secp256k1::rand::Rng;
use nostr::secp256k1::rand::rngs::OsRng;
use serde::Serialize;

use crate::diagnostics::{self, Operation};
use crate::nip44_profile;
use crate::{
    LocalIdentity, MAX_PORTABLE_TIMESTAMP_SECONDS, Nip44EncryptedMessage, Nip44Payload,
    NostrEventDraft, NostrEventId, NostrEventKind, NostrPublicKey, NostrRumor, NostrTag,
    SignedNostrEvent, SoftchatError,
};

/// Maximum number of seconds subtracted independently from private timestamps.
pub const MAX_NIP59_TIMESTAMP_TWEAK_SECONDS: u64 = 172_800;

struct GiftWrapParameters<'a> {
    kind: Nip59EnvelopeKind,
    seal_created_at: u64,
    wrapper_created_at: u64,
    wrapper_keys: &'a Keys,
    notify_recipient: bool,
}

/// The relay-storage behavior requested for one NIP-59 wrapper.
#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
#[cfg_attr(feature = "native-bindings", derive(uniffi::Enum))]
pub enum Nip59EnvelopeKind {
    /// Kind `1059`, retained by relays.
    Durable,
    /// Kind `21059`, broadcast without relay persistence.
    Ephemeral,
}

impl Nip59EnvelopeKind {
    const fn event_kind(self) -> NostrEventKind {
        match self {
            Self::Durable => NostrEventKind::GIFT_WRAP,
            Self::Ephemeral => NostrEventKind::EPHEMERAL_GIFT_WRAP,
        }
    }

    fn from_event_kind(kind: NostrEventKind) -> Result<Self, SoftchatError> {
        if kind == NostrEventKind::GIFT_WRAP {
            Ok(Self::Durable)
        } else if kind == NostrEventKind::EPHEMERAL_GIFT_WRAP {
            Ok(Self::Ephemeral)
        } else {
            Err(SoftchatError::InvalidNip59Envelope)
        }
    }
}

/// Verified outer-envelope routing metadata that does not expose plaintext.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct Nip59EnvelopeRoute {
    outer_event_id: NostrEventId,
    recipient: NostrPublicKey,
    kind: Nip59EnvelopeKind,
}

impl Nip59EnvelopeRoute {
    /// Return the verified outer event ID.
    #[must_use]
    pub const fn outer_event_id(&self) -> NostrEventId {
        self.outer_event_id
    }

    /// Return the one canonical recipient advertised by the wrapper.
    #[must_use]
    pub fn recipient(&self) -> NostrPublicKey {
        self.recipient.clone()
    }

    /// Return the relay-storage behavior of the wrapper.
    #[must_use]
    pub const fn kind(&self) -> Nip59EnvelopeKind {
        self.kind
    }
}

/// Verify a bounded gift-wrap event and extract its account-routing hint.
///
/// This authenticates only the signed outer wrapper and its single canonical
/// recipient tag. The selected account must still unwrap and authenticate
/// every inner layer before exposing message content.
///
/// # Errors
///
/// Returns a stable event or envelope failure for malformed, forged,
/// unsupported, or ambiguously routed input.
pub fn route_nip59_envelope(json: &str) -> Result<Nip59EnvelopeRoute, SoftchatError> {
    let outer = SignedNostrEvent::from_json(json)?;
    let kind = Nip59EnvelopeKind::from_event_kind(outer.kind())?;
    let recipient = recipient_route(outer.tags())?;
    Ok(Nip59EnvelopeRoute {
        outer_event_id: outer.id(),
        recipient,
        kind,
    })
}

/// A rumor exposed only after every NIP-59 layer has authenticated.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct UnwrappedNip59Envelope {
    outer_event_id: NostrEventId,
    seal_event_id: NostrEventId,
    kind: Nip59EnvelopeKind,
    rumor: NostrRumor,
}

impl UnwrappedNip59Envelope {
    /// Return the verified one-time wrapper event ID.
    #[must_use]
    pub const fn outer_event_id(&self) -> NostrEventId {
        self.outer_event_id
    }

    /// Return the verified kind-13 seal event ID.
    #[must_use]
    pub const fn seal_event_id(&self) -> NostrEventId {
        self.seal_event_id
    }

    /// Return whether the outer event is durable or ephemeral.
    #[must_use]
    pub const fn kind(&self) -> Nip59EnvelopeKind {
        self.kind
    }

    /// Borrow the authenticated unsigned rumor.
    #[must_use]
    pub const fn rumor(&self) -> &NostrRumor {
        &self.rumor
    }

    /// Consume the envelope and return its authenticated rumor.
    #[must_use]
    pub fn into_rumor(self) -> NostrRumor {
        self.rumor
    }
}

/// Flat authenticated-envelope record for generated native bindings.
#[cfg(any(
    feature = "sqlite-storage",
    feature = "native-bindings",
    all(feature = "javascript-bindings", target_arch = "wasm32"),
    test
))]
#[derive(Clone, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "native-bindings", derive(uniffi::Record))]
#[cfg_attr(
    not(any(
        feature = "native-bindings",
        all(feature = "javascript-bindings", target_arch = "wasm32"),
        test
    )),
    allow(dead_code)
)]
pub struct UnwrappedEnvelope {
    /// Verified one-time wrapper event ID.
    pub outer_event_id: String,
    /// Verified kind-13 seal event ID.
    pub seal_event_id: String,
    /// Relay-storage behavior declared by the wrapper kind.
    pub kind: Nip59EnvelopeKind,
    /// Authenticated unsigned rumor.
    pub rumor: crate::event::RumorEvent,
}

#[cfg(any(
    feature = "sqlite-storage",
    feature = "native-bindings",
    all(feature = "javascript-bindings", target_arch = "wasm32"),
    test
))]
impl From<UnwrappedNip59Envelope> for UnwrappedEnvelope {
    fn from(envelope: UnwrappedNip59Envelope) -> Self {
        Self {
            outer_event_id: envelope.outer_event_id.to_hex(),
            seal_event_id: envelope.seal_event_id.to_hex(),
            kind: envelope.kind,
            rumor: crate::event::RumorEvent::from(&envelope.rumor),
        }
    }
}

impl LocalIdentity {
    /// Create one unsigned rumor whose author is this identity.
    ///
    /// The draft timestamp remains the canonical application timestamp.
    ///
    /// [Guide and performance](https://softchat-sdk.jackl.dev/private-messaging/#create-a-one-to-one-message)
    ///
    /// # Errors
    ///
    /// Returns a stable draft-validation or event-size failure.
    pub fn create_rumor(&self, draft: NostrEventDraft) -> Result<NostrRumor, SoftchatError> {
        NostrRumor::new(self.public_key(), draft)
    }

    /// Wrap one authenticated rumor for exactly one recipient.
    ///
    /// A fresh wrapper key is generated for every call. Seal and wrapper
    /// timestamps are sampled independently from `[now - 172800, now]`.
    ///
    /// [Guide and performance](https://softchat-sdk.jackl.dev/private-messaging/#wrap-recipient-and-sender-copies)
    ///
    /// # Errors
    ///
    /// Returns [`SoftchatError::Nip59EnvelopeCreationFailed`] if the rumor
    /// author, timestamp, nested size, encryption, or signing checks fail.
    pub fn gift_wrap(
        &self,
        recipient: &NostrPublicKey,
        rumor: &NostrRumor,
        kind: Nip59EnvelopeKind,
        now: u64,
    ) -> Result<SignedNostrEvent, SoftchatError> {
        self.gift_wrap_for_operation(recipient, rumor, kind, now, false)
    }

    pub(crate) fn gift_wrap_for_operation(
        &self,
        recipient: &NostrPublicKey,
        rumor: &NostrRumor,
        kind: Nip59EnvelopeKind,
        now: u64,
        notify_recipient: bool,
    ) -> Result<SignedNostrEvent, SoftchatError> {
        if rumor.public_key() != self.public_key()
            || validate_nip59_wire_size(rumor, kind, now, notify_recipient).is_err()
        {
            diagnostics::record_rejection(rumor.content().len());
            return Err(SoftchatError::Nip59EnvelopeCreationFailed);
        }

        self.gift_wrap_for_operation_prevalidated(recipient, rumor, kind, now, notify_recipient)
    }

    pub(crate) fn gift_wrap_for_operation_prevalidated(
        &self,
        recipient: &NostrPublicKey,
        rumor: &NostrRumor,
        kind: Nip59EnvelopeKind,
        now: u64,
        notify_recipient: bool,
    ) -> Result<SignedNostrEvent, SoftchatError> {
        if now > MAX_PORTABLE_TIMESTAMP_SECONDS || rumor.public_key() != self.public_key() {
            diagnostics::record_rejection(rumor.content().len());
            return Err(SoftchatError::Nip59EnvelopeCreationFailed);
        }

        let mut rng = OsRng;
        let largest_offset = now.min(MAX_NIP59_TIMESTAMP_TWEAK_SECONDS);
        let seal_offset = rng.gen_range(0..=largest_offset);
        let wrapper_offset = rng.gen_range(0..=largest_offset);
        let wrapper_keys = Keys::generate_with_rng(&mut rng);

        let result = self
            .gift_wrap_with_parameters(
                recipient,
                rumor,
                GiftWrapParameters {
                    kind,
                    seal_created_at: now - seal_offset,
                    wrapper_created_at: now - wrapper_offset,
                    wrapper_keys: &wrapper_keys,
                    notify_recipient,
                },
            )
            .map_err(|_| SoftchatError::Nip59EnvelopeCreationFailed);
        match &result {
            Ok(event) => diagnostics::record_success(
                Operation::WrapEnvelope,
                rumor.content().len(),
                event.content().len(),
            ),
            Err(_) => diagnostics::record_rejection(rumor.content().len()),
        }
        result
    }

    /// Authenticate and unwrap one already verified NIP-59 outer event.
    ///
    /// No rumor is returned unless route, kind, both encrypted layers, seal
    /// signature, seal shape, rumor ID, and author binding all validate.
    ///
    /// [Guide and performance](https://softchat-sdk.jackl.dev/private-messaging/#receive-and-classify)
    ///
    /// # Errors
    ///
    /// Every invalid layer maps to [`SoftchatError::InvalidNip59Envelope`].
    pub fn unwrap_gift_wrap(
        &self,
        outer: &SignedNostrEvent,
    ) -> Result<UnwrappedNip59Envelope, SoftchatError> {
        let result = self
            .unwrap_gift_wrap_inner(outer)
            .map_err(|_| SoftchatError::InvalidNip59Envelope);
        match &result {
            Ok(envelope) => diagnostics::record_success(
                Operation::UnwrapEnvelope,
                outer.content().len(),
                envelope.rumor().content().len(),
            ),
            Err(_) => diagnostics::record_rejection(outer.content().len()),
        }
        result
    }

    fn gift_wrap_with_parameters(
        &self,
        recipient: &NostrPublicKey,
        rumor: &NostrRumor,
        parameters: GiftWrapParameters<'_>,
    ) -> Result<SignedNostrEvent, SoftchatError> {
        if rumor.public_key() != self.public_key() {
            return Err(SoftchatError::Nip59EnvelopeCreationFailed);
        }

        let encrypted_rumor = nip44_profile::encrypt_utf8(
            self.keys().secret_key(),
            recipient.as_inner(),
            &rumor.to_json()?,
        )
        .map_err(|_| SoftchatError::Nip59EnvelopeCreationFailed)?;
        let seal = NostrEventDraft::new(
            parameters.seal_created_at,
            NostrEventKind::SEAL,
            Vec::new(),
            encrypted_rumor,
        )?
        .sign_with_keys(self.keys())?;

        let encrypted_seal = nip44_profile::encrypt_utf8(
            parameters.wrapper_keys.secret_key(),
            recipient.as_inner(),
            &seal.to_json()?,
        )
        .map_err(|_| SoftchatError::Nip59EnvelopeCreationFailed)?;
        let recipient_tag = NostrTag::new(vec!["p".to_owned(), recipient.to_hex()])?;
        let mut wrapper_tags = vec![recipient_tag];
        if parameters.notify_recipient {
            wrapper_tags.push(NostrTag::new(vec!["alert".to_owned()])?);
        }
        NostrEventDraft::new(
            parameters.wrapper_created_at,
            parameters.kind.event_kind(),
            wrapper_tags,
            encrypted_seal,
        )?
        .sign_with_keys(parameters.wrapper_keys)
    }

    fn unwrap_gift_wrap_inner(
        &self,
        outer: &SignedNostrEvent,
    ) -> Result<UnwrappedNip59Envelope, SoftchatError> {
        let kind = Nip59EnvelopeKind::from_event_kind(outer.kind())?;
        if recipient_route(outer.tags())? != self.public_key() {
            return Err(SoftchatError::InvalidNip59Envelope);
        }

        let encrypted_seal = Nip44EncryptedMessage::new(
            outer.public_key(),
            Nip44Payload::from_encoded(outer.content())?,
        );
        let seal_json = self.decrypt_utf8(&encrypted_seal)?;
        let seal = SignedNostrEvent::from_json(&seal_json)?;
        if seal.kind() != NostrEventKind::SEAL || !has_supported_seal_tags(&seal) {
            return Err(SoftchatError::InvalidNip59Envelope);
        }

        let encrypted_rumor = Nip44EncryptedMessage::new(
            seal.public_key(),
            Nip44Payload::from_encoded(seal.content())?,
        );
        let rumor_json = self.decrypt_utf8(&encrypted_rumor)?;
        let rumor = NostrRumor::from_json(&rumor_json)?;
        if rumor.public_key() != seal.public_key() {
            return Err(SoftchatError::InvalidNip59Envelope);
        }

        Ok(UnwrappedNip59Envelope {
            outer_event_id: outer.id(),
            seal_event_id: seal.id(),
            kind,
            rumor,
        })
    }
}

/// Preflight the complete double-wrapped wire shape without performing
/// cryptography or allocating ciphertext.
///
/// NIP-44 ciphertext length is deterministic for a plaintext byte length. The
/// seal and wrapper have fixed-size IDs, keys, and signatures, so compact JSON
/// probes can establish whether both encryption layers and the final NIP-01
/// event fit before any platform or database effect begins.
pub(crate) fn validate_nip59_wire_size(
    rumor: &NostrRumor,
    kind: Nip59EnvelopeKind,
    now: u64,
    notify_recipient: bool,
) -> Result<(), SoftchatError> {
    let rumor_json_bytes = rumor.to_json()?.len();
    validate_nip59_wire_size_bytes(rumor_json_bytes, kind, now, notify_recipient)
}

#[cfg(any(feature = "sqlite-storage", test))]
pub(crate) fn validate_nip59_draft_wire_size(
    draft: &NostrEventDraft,
    kind: Nip59EnvelopeKind,
    now: u64,
    notify_recipient: bool,
) -> Result<(), SoftchatError> {
    let rumor_json_bytes = draft
        .rumor_json_bytes()
        .map_err(|_| SoftchatError::Nip59EnvelopeCreationFailed)?;
    validate_nip59_wire_size_bytes(rumor_json_bytes, kind, now, notify_recipient)
}

fn validate_nip59_wire_size_bytes(
    rumor_json_bytes: usize,
    kind: Nip59EnvelopeKind,
    now: u64,
    notify_recipient: bool,
) -> Result<(), SoftchatError> {
    if now > MAX_PORTABLE_TIMESTAMP_SECONDS {
        return Err(SoftchatError::Nip59EnvelopeCreationFailed);
    }
    let encrypted_rumor_bytes = nip44_encoded_payload_len(rumor_json_bytes)
        .ok_or(SoftchatError::Nip59EnvelopeCreationFailed)?;
    let seal_json_bytes =
        signed_event_json_bytes(now, NostrEventKind::SEAL, &[], encrypted_rumor_bytes)?;
    let encrypted_seal_bytes = nip44_encoded_payload_len(seal_json_bytes)
        .ok_or(SoftchatError::Nip59EnvelopeCreationFailed)?;
    let mut wrapper_tags = vec![vec!["p", EVENT_KEY_PLACEHOLDER]];
    if notify_recipient {
        wrapper_tags.push(vec!["alert"]);
    }
    let wrapper_json_bytes =
        signed_event_json_bytes(now, kind.event_kind(), &wrapper_tags, encrypted_seal_bytes)?;
    if wrapper_json_bytes > crate::MAX_NOSTR_EVENT_JSON_BYTES {
        return Err(SoftchatError::Nip59EnvelopeCreationFailed);
    }
    Ok(())
}

const EVENT_KEY_PLACEHOLDER: &str =
    "0000000000000000000000000000000000000000000000000000000000000000";
const EVENT_SIGNATURE_PLACEHOLDER: &str = concat!(
    "0000000000000000000000000000000000000000000000000000000000000000",
    "0000000000000000000000000000000000000000000000000000000000000000"
);

fn nip44_encoded_payload_len(plaintext_bytes: usize) -> Option<usize> {
    if !(1..=crate::MAX_NIP44_WRITER_PLAINTEXT_BYTES).contains(&plaintext_bytes) {
        return None;
    }
    let padded_bytes = if plaintext_bytes <= 32 {
        32
    } else {
        let next_power = plaintext_bytes.checked_next_power_of_two()?;
        let chunk = if next_power <= 256 {
            32
        } else {
            next_power.checked_div(8)?
        };
        chunk.checked_mul(
            plaintext_bytes
                .checked_sub(1)?
                .checked_div(chunk)?
                .checked_add(1)?,
        )?
    };
    // version (1), nonce (32), legacy length prefix (2), padded plaintext,
    // and HMAC (32), followed by standard padded base64.
    let binary_bytes = padded_bytes.checked_add(67)?;
    binary_bytes.checked_add(2)?.checked_div(3)?.checked_mul(4)
}

fn signed_event_json_bytes(
    created_at: u64,
    kind: NostrEventKind,
    tags: &[Vec<&str>],
    content_bytes: usize,
) -> Result<usize, SoftchatError> {
    #[derive(Serialize)]
    struct SignedEventProbe<'a> {
        id: &'static str,
        pubkey: &'static str,
        created_at: u64,
        kind: u16,
        tags: &'a [Vec<&'a str>],
        content: &'static str,
        sig: &'static str,
    }

    let probe = SignedEventProbe {
        id: EVENT_KEY_PLACEHOLDER,
        pubkey: EVENT_KEY_PLACEHOLDER,
        created_at,
        kind: kind.as_u16(),
        tags,
        content: "",
        sig: EVENT_SIGNATURE_PLACEHOLDER,
    };
    serde_json::to_string(&probe)
        .map_err(|_| SoftchatError::Nip59EnvelopeCreationFailed)?
        .len()
        .checked_add(content_bytes)
        .ok_or(SoftchatError::Nip59EnvelopeCreationFailed)
}

fn has_supported_seal_tags(seal: &SignedNostrEvent) -> bool {
    let tags = seal.tags().collect::<Vec<_>>();
    match tags.as_slice() {
        [] => true,
        [tag]
            if tag.len() == 2
                && tag.first().map(String::as_str) == Some("expiration")
                && tag
                    .get(1)
                    .and_then(|value| value.parse::<u64>().ok())
                    .is_some() =>
        {
            true
        }
        _ => false,
    }
}

fn recipient_route<'a>(
    tags: impl Iterator<Item = &'a [String]>,
) -> Result<NostrPublicKey, SoftchatError> {
    let mut recipient = None;
    let mut recipient_tags = 0_u8;

    for tag in tags {
        if tag.first().map(String::as_str) != Some("p") {
            continue;
        }
        recipient_tags = recipient_tags
            .checked_add(1)
            .ok_or(SoftchatError::InvalidNip59Envelope)?;
        let raw_public_key = tag.get(1).ok_or(SoftchatError::InvalidNip59Envelope)?;
        let public_key = NostrPublicKey::from_hex(raw_public_key)?;
        if public_key.to_hex() != *raw_public_key {
            return Err(SoftchatError::InvalidNip59Envelope);
        }
        recipient = Some(public_key);
    }

    match (recipient_tags, recipient) {
        (1, Some(recipient)) => Ok(recipient),
        _ => Err(SoftchatError::InvalidNip59Envelope),
    }
}

#[cfg(test)]
mod tests {
    use nostr::SecretKey;
    use serde::Deserialize;

    use super::*;
    use crate::{AttachmentMetadata, ChatMessageDraft, ChatRelation};

    const ALICE_SECRET: &str = "5c0c523f52a5b6fad39ed2403092df8cebc36318b39383bca6c00808626fab3a";
    const BOB_SECRET: &str = "4b22aa260e4acb7021e32f38a6cdf4b673c6a277755bfce287e370c924dc936d";
    const WRAPPER_SECRET: &str = "8f40e50a84a7462e2b8d24c28898ef1f23359fff50d8c509e6fb7ce06e142f9c";
    const OFFICIAL_EXAMPLE: &str =
        include_str!("../../../fixtures/nostr/nip59/nip59-official-example.json");

    #[derive(Deserialize)]
    #[serde(rename_all = "camelCase")]
    struct OfficialExample {
        recipient_secret: String,
        rumor: serde_json::Value,
        seal: serde_json::Value,
        gift_wrap: serde_json::Value,
    }

    struct OuterParameters {
        kind: NostrEventKind,
        tags: Vec<NostrTag>,
        tamper_ciphertext: bool,
    }

    #[derive(Clone, Copy)]
    enum BoundaryShape {
        Plain,
        Reply,
        Group,
        Tags,
        Attachment,
    }

    fn direct_message_rumor(
        alice: &LocalIdentity,
        bob: &LocalIdentity,
    ) -> Result<NostrRumor, SoftchatError> {
        alice.create_rumor(NostrEventDraft::new(
            1_700_000_000,
            NostrEventKind::PRIVATE_DIRECT_MESSAGE,
            vec![NostrTag::new(vec![
                "p".to_owned(),
                bob.public_key().to_hex(),
            ])?],
            "hello Bob",
        )?)
    }

    fn custom_envelope(
        seal_signer: &LocalIdentity,
        recipient: &LocalIdentity,
        wrapper_keys: &Keys,
        rumor_json: &str,
        seal_tags: Vec<NostrTag>,
        outer: OuterParameters,
    ) -> Result<SignedNostrEvent, SoftchatError> {
        let encrypted_rumor = nip44_profile::encrypt_utf8(
            seal_signer.keys().secret_key(),
            recipient.public_key().as_inner(),
            rumor_json,
        )
        .map_err(|_| SoftchatError::EncryptionFailed)?;
        let seal = NostrEventDraft::new(
            1_700_000_100,
            NostrEventKind::SEAL,
            seal_tags,
            encrypted_rumor,
        )?
        .sign_with_keys(seal_signer.keys())?;
        let mut encrypted_seal = nip44_profile::encrypt_utf8(
            wrapper_keys.secret_key(),
            recipient.public_key().as_inner(),
            &seal.to_json()?,
        )
        .map_err(|_| SoftchatError::EncryptionFailed)?;
        if outer.tamper_ciphertext {
            let replacement = if encrypted_seal.ends_with('A') {
                "B"
            } else {
                "A"
            };
            encrypted_seal.replace_range(encrypted_seal.len() - 1.., replacement);
        }
        NostrEventDraft::new(1_700_000_200, outer.kind, outer.tags, encrypted_seal)?
            .sign_with_keys(wrapper_keys)
    }

    fn boundary_draft(
        alice: &LocalIdentity,
        bob: &LocalIdentity,
        shape: BoundaryShape,
        content: String,
    ) -> Result<NostrEventDraft, SoftchatError> {
        let carol = LocalIdentity::from_secret_hex(
            "0000000000000000000000000000000000000000000000000000000000000002",
        )?;
        let participants = match shape {
            BoundaryShape::Group => vec![bob.public_key(), carol.public_key()],
            _ => vec![bob.public_key()],
        };
        let relation = match shape {
            BoundaryShape::Reply => ChatRelation::Reply {
                event_id: NostrEventId::from_hex(&"11".repeat(32))?,
                relay_hint: Some("wss://relay.example/path".to_owned()),
                legacy_unmarked: false,
            },
            _ => ChatRelation::None,
        };
        let attachments = match shape {
            BoundaryShape::Attachment => vec![AttachmentMetadata {
                url: "https://media.example/attachment".to_owned(),
                mime_type: Some("image/jpeg".to_owned()),
                sha256: Some("22".repeat(32)),
                name: Some("boundary image.jpg".to_owned()),
                ..AttachmentMetadata::default()
            }],
            _ => Vec::new(),
        };
        let (emoji_tags, extension_tags) = match shape {
            BoundaryShape::Tags => (
                vec![NostrTag::new(vec![
                    "emoji",
                    "softchat",
                    "https://emoji.example/softchat.png",
                ])?],
                vec![NostrTag::new(vec!["client", "boundary-fixture"])?],
            ),
            _ => (Vec::new(), Vec::new()),
        };
        crate::chat::prepare_chat_message_draft(
            alice.public_key(),
            ChatMessageDraft {
                created_at: 1_700_172_800,
                participants,
                content,
                relation,
                attachments,
                emoji_tags,
                extension_tags,
            },
        )
    }

    fn boundary_rumor(
        alice: &LocalIdentity,
        bob: &LocalIdentity,
        shape: BoundaryShape,
        content: String,
    ) -> Result<NostrRumor, SoftchatError> {
        alice.create_rumor(boundary_draft(alice, bob, shape, content)?)
    }

    fn largest_valid_units(
        mut rumor: impl FnMut(usize) -> Result<NostrRumor, SoftchatError>,
        maximum_units: usize,
    ) -> Result<usize, SoftchatError> {
        let mut lower = 1;
        let mut upper = maximum_units
            .checked_add(1)
            .ok_or(SoftchatError::Nip59EnvelopeCreationFailed)?;
        while lower + 1 < upper {
            let middle = lower + (upper - lower) / 2;
            if validate_nip59_wire_size(
                &rumor(middle)?,
                Nip59EnvelopeKind::Durable,
                1_700_172_800,
                true,
            )
            .is_ok()
            {
                lower = middle;
            } else {
                upper = middle;
            }
        }
        Ok(lower)
    }

    #[test]
    fn round_trips_durable_and_ephemeral_envelopes() -> Result<(), SoftchatError> {
        let alice = LocalIdentity::from_secret_hex(ALICE_SECRET)?;
        let bob = LocalIdentity::from_secret_hex(BOB_SECRET)?;
        let rumor = direct_message_rumor(&alice, &bob)?;

        for kind in [Nip59EnvelopeKind::Durable, Nip59EnvelopeKind::Ephemeral] {
            let outer = alice.gift_wrap(&bob.public_key(), &rumor, kind, 1_700_172_800)?;
            let received = bob.unwrap_gift_wrap(&outer)?;
            assert_eq!(received.kind(), kind);
            assert_eq!(received.outer_event_id(), outer.id());
            assert_eq!(received.rumor(), &rumor);
            assert_ne!(received.seal_event_id(), outer.id());
        }
        Ok(())
    }

    #[test]
    fn wire_preflight_matches_double_wrap_at_every_product_message_boundary()
    -> Result<(), SoftchatError> {
        let alice = LocalIdentity::from_secret_hex(ALICE_SECRET)?;
        let bob = LocalIdentity::from_secret_hex(BOB_SECRET)?;
        let wrapper_secret =
            SecretKey::from_hex(WRAPPER_SECRET).map_err(|_| SoftchatError::InvalidSecretKey)?;
        let wrapper_keys = Keys::new(wrapper_secret);

        let verify = |shape, unit: &str| -> Result<(), SoftchatError> {
            let text = |units| unit.repeat(units);
            let maximum_units = crate::MAX_NIP44_WRITER_PLAINTEXT_BYTES / unit.len();
            let boundary = largest_valid_units(
                |units| boundary_rumor(&alice, &bob, shape, text(units)),
                maximum_units,
            )?;
            let accepted = boundary_rumor(&alice, &bob, shape, text(boundary))?;
            let rejected = boundary_rumor(&alice, &bob, shape, text(boundary + 1))?;
            let accepted_draft = boundary_draft(&alice, &bob, shape, text(boundary))?;
            let rejected_draft = boundary_draft(&alice, &bob, shape, text(boundary + 1))?;
            assert_eq!(
                accepted_draft.rumor_json_bytes()?,
                accepted.to_json()?.len()
            );
            assert_eq!(
                rejected_draft.rumor_json_bytes()?,
                rejected.to_json()?.len()
            );
            assert!(
                validate_nip59_wire_size(
                    &accepted,
                    Nip59EnvelopeKind::Durable,
                    1_700_172_800,
                    true,
                )
                .is_ok()
            );
            assert!(
                validate_nip59_wire_size(
                    &rejected,
                    Nip59EnvelopeKind::Durable,
                    1_700_172_800,
                    true,
                )
                .is_err()
            );
            assert!(
                validate_nip59_draft_wire_size(
                    &accepted_draft,
                    Nip59EnvelopeKind::Durable,
                    1_700_172_800,
                    true,
                )
                .is_ok()
            );
            assert!(
                validate_nip59_draft_wire_size(
                    &rejected_draft,
                    Nip59EnvelopeKind::Durable,
                    1_700_172_800,
                    true,
                )
                .is_err()
            );
            alice.gift_wrap_with_parameters(
                &bob.public_key(),
                &accepted,
                GiftWrapParameters {
                    kind: Nip59EnvelopeKind::Durable,
                    seal_created_at: 1_700_172_800,
                    wrapper_created_at: 1_700_172_800,
                    wrapper_keys: &wrapper_keys,
                    notify_recipient: true,
                },
            )?;
            assert!(
                alice
                    .gift_wrap_with_parameters(
                        &bob.public_key(),
                        &rejected,
                        GiftWrapParameters {
                            kind: Nip59EnvelopeKind::Durable,
                            seal_created_at: 1_700_172_800,
                            wrapper_created_at: 1_700_172_800,
                            wrapper_keys: &wrapper_keys,
                            notify_recipient: true,
                        },
                    )
                    .is_err()
            );
            Ok(())
        };

        for shape in [
            BoundaryShape::Plain,
            BoundaryShape::Reply,
            BoundaryShape::Group,
            BoundaryShape::Tags,
            BoundaryShape::Attachment,
        ] {
            verify(shape, "a")?;
        }
        verify(BoundaryShape::Plain, "🦀")?;
        verify(BoundaryShape::Plain, "\"")?;
        Ok(())
    }

    #[test]
    fn wire_preflight_uses_the_exact_nip44_encoded_length() -> Result<(), SoftchatError> {
        let alice = LocalIdentity::from_secret_hex(ALICE_SECRET)?;
        let bob = LocalIdentity::from_secret_hex(BOB_SECRET)?;
        for plaintext_bytes in [1, 32, 33, 256, 257, 65_408, 65_535] {
            let payload = nip44_profile::encrypt_utf8(
                alice.keys().secret_key(),
                bob.public_key().as_inner(),
                &"x".repeat(plaintext_bytes),
            )
            .map_err(|_| SoftchatError::EncryptionFailed)?;
            assert_eq!(
                nip44_encoded_payload_len(plaintext_bytes),
                Some(payload.len())
            );
        }
        Ok(())
    }

    #[test]
    fn routes_only_verified_single_recipient_wrappers() -> Result<(), SoftchatError> {
        let alice = LocalIdentity::from_secret_hex(ALICE_SECRET)?;
        let bob = LocalIdentity::from_secret_hex(BOB_SECRET)?;
        let rumor = direct_message_rumor(&alice, &bob)?;
        let outer = alice.gift_wrap(
            &bob.public_key(),
            &rumor,
            Nip59EnvelopeKind::Durable,
            1_700_172_800,
        )?;
        let route = route_nip59_envelope(&outer.to_json()?)?;

        assert_eq!(route.outer_event_id(), outer.id());
        assert_eq!(route.recipient(), bob.public_key());
        assert_eq!(route.kind(), Nip59EnvelopeKind::Durable);

        let duplicate_recipient = NostrEventDraft::new(
            outer.created_at(),
            NostrEventKind::GIFT_WRAP,
            vec![
                NostrTag::new(vec!["p".to_owned(), bob.public_key().to_hex()])?,
                NostrTag::new(vec!["p".to_owned(), bob.public_key().to_hex()])?,
            ],
            outer.content().to_owned(),
        )?
        .sign_with_keys(alice.keys())?;
        assert!(matches!(
            route_nip59_envelope(&duplicate_recipient.to_json()?),
            Err(SoftchatError::InvalidNip59Envelope)
        ));

        let wrong_kind = NostrEventDraft::new(
            outer.created_at(),
            NostrEventKind::SHORT_TEXT_NOTE,
            vec![NostrTag::new(vec![
                "p".to_owned(),
                bob.public_key().to_hex(),
            ])?],
            outer.content().to_owned(),
        )?
        .sign_with_keys(alice.keys())?;
        assert!(matches!(
            route_nip59_envelope(&wrong_kind.to_json()?),
            Err(SoftchatError::InvalidNip59Envelope)
        ));
        Ok(())
    }

    #[test]
    fn unwraps_the_official_nip59_example() -> Result<(), Box<dyn std::error::Error>> {
        let fixture: OfficialExample = serde_json::from_str(OFFICIAL_EXAMPLE)?;
        let recipient = LocalIdentity::from_secret_hex(&fixture.recipient_secret)?;
        let outer = SignedNostrEvent::from_json(&fixture.gift_wrap.to_string())?;
        let expected_rumor = NostrRumor::from_json(&fixture.rumor.to_string())?;
        let seal = SignedNostrEvent::from_json(&fixture.seal.to_string())?;

        let received = recipient.unwrap_gift_wrap(&outer)?;

        assert_eq!(received.kind(), Nip59EnvelopeKind::Durable);
        assert_eq!(received.outer_event_id(), outer.id());
        assert_eq!(received.seal_event_id(), seal.id());
        assert_eq!(received.rumor(), &expected_rumor);
        Ok(())
    }

    #[test]
    fn uses_fresh_wrapper_keys_and_private_timestamp_bounds() -> Result<(), SoftchatError> {
        let alice = LocalIdentity::from_secret_hex(ALICE_SECRET)?;
        let bob = LocalIdentity::from_secret_hex(BOB_SECRET)?;
        let rumor = direct_message_rumor(&alice, &bob)?;
        let now = 1_700_172_800;

        let first = alice.gift_wrap(&bob.public_key(), &rumor, Nip59EnvelopeKind::Durable, now)?;
        let second = alice.gift_wrap(&bob.public_key(), &rumor, Nip59EnvelopeKind::Durable, now)?;

        assert_ne!(first.public_key(), second.public_key());
        for outer in [&first, &second] {
            assert!((now - MAX_NIP59_TIMESTAMP_TWEAK_SECONDS..=now).contains(&outer.created_at()));
        }
        Ok(())
    }

    #[test]
    fn deterministic_hook_keeps_private_timestamps_independent() -> Result<(), SoftchatError> {
        let alice = LocalIdentity::from_secret_hex(ALICE_SECRET)?;
        let bob = LocalIdentity::from_secret_hex(BOB_SECRET)?;
        let rumor = direct_message_rumor(&alice, &bob)?;
        let wrapper_secret =
            SecretKey::from_hex(WRAPPER_SECRET).map_err(|_| SoftchatError::InvalidSecretKey)?;
        let wrapper_keys = Keys::new(wrapper_secret);

        let outer = alice.gift_wrap_with_parameters(
            &bob.public_key(),
            &rumor,
            GiftWrapParameters {
                kind: Nip59EnvelopeKind::Durable,
                seal_created_at: 1_700_000_100,
                wrapper_created_at: 1_700_000_200,
                wrapper_keys: &wrapper_keys,
                notify_recipient: false,
            },
        )?;
        let encrypted_seal = Nip44EncryptedMessage::new(
            outer.public_key(),
            Nip44Payload::from_encoded(outer.content())?,
        );
        let seal = SignedNostrEvent::from_json(&bob.decrypt_utf8(&encrypted_seal)?)?;

        assert_eq!(seal.created_at(), 1_700_000_100);
        assert_eq!(outer.created_at(), 1_700_000_200);
        assert_eq!(
            outer.public_key(),
            NostrPublicKey::from_inner(wrapper_keys.public_key())
        );
        Ok(())
    }

    #[test]
    fn rejects_wrong_recipient_and_wrong_rumor_author() -> Result<(), SoftchatError> {
        let alice = LocalIdentity::from_secret_hex(ALICE_SECRET)?;
        let bob = LocalIdentity::from_secret_hex(BOB_SECRET)?;
        let wrapper = LocalIdentity::from_secret_hex(WRAPPER_SECRET)?;
        let rumor = direct_message_rumor(&alice, &bob)?;
        let outer = alice.gift_wrap(
            &bob.public_key(),
            &rumor,
            Nip59EnvelopeKind::Durable,
            1_700_172_800,
        )?;

        assert!(matches!(
            wrapper.unwrap_gift_wrap(&outer),
            Err(SoftchatError::InvalidNip59Envelope)
        ));
        assert!(matches!(
            wrapper.gift_wrap(
                &bob.public_key(),
                &rumor,
                Nip59EnvelopeKind::Durable,
                1_700_172_800,
            ),
            Err(SoftchatError::Nip59EnvelopeCreationFailed)
        ));
        Ok(())
    }

    #[test]
    fn rejects_invalid_routes_kinds_seals_ciphertext_ids_and_author_binding()
    -> Result<(), SoftchatError> {
        let alice = LocalIdentity::from_secret_hex(ALICE_SECRET)?;
        let bob = LocalIdentity::from_secret_hex(BOB_SECRET)?;
        let carol = LocalIdentity::from_secret_hex(WRAPPER_SECRET)?;
        let rumor = direct_message_rumor(&alice, &bob)?;
        let wrapper_keys = Keys::new(
            SecretKey::from_hex(WRAPPER_SECRET).map_err(|_| SoftchatError::InvalidSecretKey)?,
        );
        let recipient_tag = NostrTag::new(vec!["p".to_owned(), bob.public_key().to_hex()])?;
        let alert_tag = NostrTag::new(vec!["alert".to_owned(), "true".to_owned()])?;

        let with_non_recipient_tag = custom_envelope(
            &alice,
            &bob,
            &wrapper_keys,
            &rumor.to_json()?,
            Vec::new(),
            OuterParameters {
                kind: NostrEventKind::GIFT_WRAP,
                tags: vec![recipient_tag.clone(), alert_tag.clone()],
                tamper_ciphertext: false,
            },
        )?;
        assert_eq!(
            bob.unwrap_gift_wrap(&with_non_recipient_tag)?.rumor(),
            &rumor
        );

        let duplicate_route = custom_envelope(
            &alice,
            &bob,
            &wrapper_keys,
            &rumor.to_json()?,
            Vec::new(),
            OuterParameters {
                kind: NostrEventKind::GIFT_WRAP,
                tags: vec![recipient_tag.clone(), recipient_tag.clone()],
                tamper_ciphertext: false,
            },
        )?;
        let uppercase_route = custom_envelope(
            &alice,
            &bob,
            &wrapper_keys,
            &rumor.to_json()?,
            Vec::new(),
            OuterParameters {
                kind: NostrEventKind::GIFT_WRAP,
                tags: vec![NostrTag::new(vec![
                    "p".to_owned(),
                    bob.public_key().to_hex().to_uppercase(),
                ])?],
                tamper_ciphertext: false,
            },
        )?;
        let wrong_kind = custom_envelope(
            &alice,
            &bob,
            &wrapper_keys,
            &rumor.to_json()?,
            Vec::new(),
            OuterParameters {
                kind: NostrEventKind::FILE_METADATA,
                tags: vec![recipient_tag.clone()],
                tamper_ciphertext: false,
            },
        )?;
        let tagged_seal = custom_envelope(
            &alice,
            &bob,
            &wrapper_keys,
            &rumor.to_json()?,
            vec![alert_tag],
            OuterParameters {
                kind: NostrEventKind::GIFT_WRAP,
                tags: vec![recipient_tag.clone()],
                tamper_ciphertext: false,
            },
        )?;
        let tampered_ciphertext = custom_envelope(
            &alice,
            &bob,
            &wrapper_keys,
            &rumor.to_json()?,
            Vec::new(),
            OuterParameters {
                kind: NostrEventKind::GIFT_WRAP,
                tags: vec![recipient_tag.clone()],
                tamper_ciphertext: true,
            },
        )?;

        let mut invalid_id: serde_json::Value =
            serde_json::from_str(&rumor.to_json()?).map_err(|_| SoftchatError::InvalidEventJson)?;
        invalid_id["id"] = serde_json::Value::String("00".repeat(32));
        let invalid_rumor_id = custom_envelope(
            &alice,
            &bob,
            &wrapper_keys,
            &invalid_id.to_string(),
            Vec::new(),
            OuterParameters {
                kind: NostrEventKind::GIFT_WRAP,
                tags: vec![recipient_tag.clone()],
                tamper_ciphertext: false,
            },
        )?;

        let spoofed_rumor = carol.create_rumor(NostrEventDraft::new(
            1_700_000_000,
            NostrEventKind::PRIVATE_DIRECT_MESSAGE,
            vec![recipient_tag.clone()],
            "spoofed",
        )?)?;
        let author_mismatch = custom_envelope(
            &alice,
            &bob,
            &wrapper_keys,
            &spoofed_rumor.to_json()?,
            Vec::new(),
            OuterParameters {
                kind: NostrEventKind::GIFT_WRAP,
                tags: vec![recipient_tag],
                tamper_ciphertext: false,
            },
        )?;

        for invalid in [
            duplicate_route,
            uppercase_route,
            wrong_kind,
            tagged_seal,
            tampered_ciphertext,
            invalid_rumor_id,
            author_mismatch,
        ] {
            assert!(matches!(
                bob.unwrap_gift_wrap(&invalid),
                Err(SoftchatError::InvalidNip59Envelope)
            ));
        }
        Ok(())
    }

    #[test]
    fn accepts_only_the_released_expiration_seal_compatibility_shape() -> Result<(), SoftchatError>
    {
        let alice = LocalIdentity::from_secret_hex(ALICE_SECRET)?;
        let bob = LocalIdentity::from_secret_hex(BOB_SECRET)?;
        let wrapper_keys = Keys::generate();
        let rumor = direct_message_rumor(&alice, &bob)?;
        let recipient_tag = NostrTag::new(vec!["p".to_owned(), bob.public_key().to_hex()])?;

        let compatible = custom_envelope(
            &alice,
            &bob,
            &wrapper_keys,
            &rumor.to_json()?,
            vec![NostrTag::new(vec![
                "expiration".to_owned(),
                "4102444800".to_owned(),
            ])?],
            OuterParameters {
                kind: NostrEventKind::GIFT_WRAP,
                tags: vec![recipient_tag.clone()],
                tamper_ciphertext: false,
            },
        )?;
        assert_eq!(bob.unwrap_gift_wrap(&compatible)?.rumor(), &rumor);

        for invalid_tags in [
            vec![NostrTag::new(vec![
                "expiration".to_owned(),
                "-1".to_owned(),
            ])?],
            vec![NostrTag::new(vec![
                "expiration".to_owned(),
                "not-a-number".to_owned(),
            ])?],
            vec![NostrTag::new(vec![
                "expiration".to_owned(),
                "4102444800".to_owned(),
                "extra".to_owned(),
            ])?],
            vec![
                NostrTag::new(vec!["expiration".to_owned(), "4102444800".to_owned()])?,
                NostrTag::new(vec!["expiration".to_owned(), "4102444801".to_owned()])?,
            ],
        ] {
            let outer = custom_envelope(
                &alice,
                &bob,
                &wrapper_keys,
                &rumor.to_json()?,
                invalid_tags,
                OuterParameters {
                    kind: NostrEventKind::GIFT_WRAP,
                    tags: vec![recipient_tag.clone()],
                    tamper_ciphertext: false,
                },
            )?;
            assert!(matches!(
                bob.unwrap_gift_wrap(&outer),
                Err(SoftchatError::InvalidNip59Envelope)
            ));
        }
        Ok(())
    }
}