softchat/

nip19.rs

//! Bounded NIP-19 display identifiers used by Softchat.

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

use bech32::{Bech32, Hrp};

use crate::{NostrEventId, NostrEventKind, NostrPublicKey, SoftchatError};

/// Maximum accepted encoded identifier length.
///
/// NIP-19 recommends a 5,000-character limit. Softchat uses the same bound.
pub const MAX_NIP19_IDENTIFIER_CHARS: usize = 5_000;

/// Maximum relay hints retained in one shareable identifier.
pub const MAX_NIP19_RELAYS: usize = 8;

const MAX_RELAY_HINT_BYTES: usize = 255;
const TLV_SPECIAL: u8 = 0;
const TLV_RELAY: u8 = 1;
const TLV_AUTHOR: u8 = 2;
const TLV_KIND: u8 = 3;

/// Supported NIP-19 identifier family.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "native-bindings", derive(uniffi::Enum))]
pub enum Nip19IdentifierKind {
    /// Bare public key (`npub`).
    PublicKey,
    /// Bare event ID (`note`).
    EventId,
    /// Public key plus relay hints (`nprofile`).
    Profile,
    /// Event ID plus optional author, kind, and relay hints (`nevent`).
    Event,
}

/// One unknown NIP-19 TLV retained for forward-compatible re-encoding.
#[derive(Clone, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "native-bindings", derive(uniffi::Record))]
pub struct Nip19Tlv {
    /// Unknown one-byte TLV type.
    pub type_id: u32,
    /// Exact TLV value bytes.
    pub value: Vec<u8>,
}

/// A bounded, parsed NIP-19 value.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct Nip19Identifier {
    kind: Nip19IdentifierKind,
    primary_hex: String,
    relays: Vec<String>,
    author_hex: Option<String>,
    event_kind: Option<NostrEventKind>,
    unknown_tlvs: Vec<Nip19Tlv>,
}

impl Nip19Identifier {
    /// Parse one supported NIP-19 identifier.
    ///
    /// Secret keys and addressable-event coordinates are deliberately outside
    /// this display-only Softchat boundary. Unknown TLVs are retained.
    ///
    /// # Errors
    ///
    /// Returns [`SoftchatError::InvalidNip19Identifier`] for malformed,
    /// mixed-case, unsupported, oversized, duplicate, or invalid values.
    pub fn parse(encoded: &str) -> Result<Self, SoftchatError> {
        validate_encoded_shape(encoded)?;
        let (hrp, data) =
            bech32::decode(encoded).map_err(|_| SoftchatError::InvalidNip19Identifier)?;
        match hrp.as_str() {
            "npub" => parse_bare(Nip19IdentifierKind::PublicKey, &data),
            "note" => parse_bare(Nip19IdentifierKind::EventId, &data),
            "nprofile" => parse_tlv(Nip19IdentifierKind::Profile, &data),
            "nevent" => parse_tlv(Nip19IdentifierKind::Event, &data),
            _ => Err(SoftchatError::InvalidNip19Identifier),
        }
    }

    /// Encode the canonical lowercase representation.
    ///
    /// # Errors
    ///
    /// Returns [`SoftchatError::InvalidNip19Identifier`] if retained fields no
    /// longer satisfy the bounded Softchat profile.
    pub fn encode(&self) -> Result<String, SoftchatError> {
        let (hrp, bytes) = match self.kind {
            Nip19IdentifierKind::PublicKey => {
                let key = NostrPublicKey::from_hex(&self.primary_hex)
                    .map_err(|_| SoftchatError::InvalidNip19Identifier)?;
                ("npub", key.as_inner().to_bytes().to_vec())
            }
            Nip19IdentifierKind::EventId => {
                let id = NostrEventId::from_hex(&self.primary_hex)
                    .map_err(|_| SoftchatError::InvalidNip19Identifier)?;
                ("note", id.as_inner().as_bytes().to_vec())
            }
            Nip19IdentifierKind::Profile | Nip19IdentifierKind::Event => {
                let bytes = self.encode_tlvs()?;
                let hrp = if self.kind == Nip19IdentifierKind::Profile {
                    "nprofile"
                } else {
                    "nevent"
                };
                (hrp, bytes)
            }
        };
        let hrp = Hrp::parse(hrp).map_err(|_| SoftchatError::InvalidNip19Identifier)?;
        let encoded = bech32::encode::<Bech32>(hrp, &bytes)
            .map_err(|_| SoftchatError::InvalidNip19Identifier)?;
        validate_encoded_shape(&encoded)?;
        Ok(encoded)
    }

    /// Identifier family.
    #[must_use]
    pub const fn kind(&self) -> Nip19IdentifierKind {
        self.kind
    }

    /// Canonical public key or event ID hexadecimal value.
    #[must_use]
    pub fn primary_hex(&self) -> &str {
        &self.primary_hex
    }

    /// Ordered, validated relay hints.
    #[must_use]
    pub fn relays(&self) -> &[String] {
        &self.relays
    }

    /// Optional event author for `nevent`.
    #[must_use]
    pub fn author_hex(&self) -> Option<&str> {
        self.author_hex.as_deref()
    }

    /// Optional event kind for `nevent`.
    #[must_use]
    pub const fn event_kind(&self) -> Option<NostrEventKind> {
        self.event_kind
    }

    /// Unknown TLVs retained without interpretation.
    #[must_use]
    pub fn unknown_tlvs(&self) -> &[Nip19Tlv] {
        &self.unknown_tlvs
    }

    fn encode_tlvs(&self) -> Result<Vec<u8>, SoftchatError> {
        let mut output = Vec::new();
        let special = match self.kind {
            Nip19IdentifierKind::Profile => NostrPublicKey::from_hex(&self.primary_hex)
                .map(|key| key.as_inner().to_bytes().to_vec()),
            Nip19IdentifierKind::Event => NostrEventId::from_hex(&self.primary_hex)
                .map(|id| id.as_inner().as_bytes().to_vec()),
            Nip19IdentifierKind::PublicKey | Nip19IdentifierKind::EventId => {
                return Err(SoftchatError::InvalidNip19Identifier);
            }
        }
        .map_err(|_| SoftchatError::InvalidNip19Identifier)?;
        push_tlv(&mut output, TLV_SPECIAL, &special)?;
        validate_relays(&self.relays)?;
        for relay in &self.relays {
            push_tlv(&mut output, TLV_RELAY, relay.as_bytes())?;
        }
        if self.kind == Nip19IdentifierKind::Profile
            && (self.author_hex.is_some() || self.event_kind.is_some())
        {
            return Err(SoftchatError::InvalidNip19Identifier);
        }
        if let Some(author) = &self.author_hex {
            let author = NostrPublicKey::from_hex(author)
                .map_err(|_| SoftchatError::InvalidNip19Identifier)?;
            push_tlv(&mut output, TLV_AUTHOR, &author.as_inner().to_bytes())?;
        }
        if let Some(kind) = self.event_kind {
            push_tlv(
                &mut output,
                TLV_KIND,
                &u32::from(kind.as_u16()).to_be_bytes(),
            )?;
        }
        for unknown in &self.unknown_tlvs {
            let type_id =
                u8::try_from(unknown.type_id).map_err(|_| SoftchatError::InvalidNip19Identifier)?;
            if matches!(type_id, TLV_SPECIAL | TLV_RELAY | TLV_AUTHOR | TLV_KIND) {
                return Err(SoftchatError::InvalidNip19Identifier);
            }
            push_tlv(&mut output, type_id, &unknown.value)?;
        }
        Ok(output)
    }
}

/// Flat NIP-19 value for generated native bindings.
#[derive(Clone, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "native-bindings", derive(uniffi::Record))]
pub struct Nip19Value {
    /// Identifier family.
    pub kind: Nip19IdentifierKind,
    /// Canonical public key or event ID.
    pub primary_hex: String,
    /// Ordered relay hints.
    pub relays: Vec<String>,
    /// Optional event author.
    pub author_hex: Option<String>,
    /// Optional event kind.
    pub event_kind: Option<u32>,
    /// Unknown retained TLVs.
    pub unknown_tlvs: Vec<Nip19Tlv>,
}

impl From<&Nip19Identifier> for Nip19Value {
    fn from(value: &Nip19Identifier) -> Self {
        Self {
            kind: value.kind,
            primary_hex: value.primary_hex.clone(),
            relays: value.relays.clone(),
            author_hex: value.author_hex.clone(),
            event_kind: value.event_kind.map(|kind| u32::from(kind.as_u16())),
            unknown_tlvs: value.unknown_tlvs.clone(),
        }
    }
}

impl TryFrom<Nip19Value> for Nip19Identifier {
    type Error = SoftchatError;

    fn try_from(value: Nip19Value) -> Result<Self, Self::Error> {
        let event_kind = value
            .event_kind
            .map(NostrEventKind::try_from_u32)
            .transpose()
            .map_err(|_| SoftchatError::InvalidNip19Identifier)?;
        let value = Self {
            kind: value.kind,
            primary_hex: value.primary_hex,
            relays: value.relays,
            author_hex: value.author_hex,
            event_kind,
            unknown_tlvs: value.unknown_tlvs,
        };
        value.encode()?;
        Ok(value)
    }
}

/// Parse one supported NIP-19 value for generated native bindings.
#[cfg(any(
    feature = "native-bindings",
    all(feature = "javascript-bindings", target_arch = "wasm32"),
    test
))]
#[cfg_attr(feature = "native-bindings", uniffi::export)]
pub fn parse_nip19_identifier(encoded: String) -> Result<Nip19Value, SoftchatError> {
    Nip19Identifier::parse(&encoded).map(|value| Nip19Value::from(&value))
}

/// Encode one validated NIP-19 value for generated native bindings.
#[cfg(any(
    feature = "native-bindings",
    all(feature = "javascript-bindings", target_arch = "wasm32"),
    test
))]
#[cfg_attr(feature = "native-bindings", uniffi::export)]
pub fn encode_nip19_identifier(value: Nip19Value) -> Result<String, SoftchatError> {
    Nip19Identifier::try_from(value)?.encode()
}

fn validate_encoded_shape(encoded: &str) -> Result<(), SoftchatError> {
    if encoded.is_empty() || encoded.len() > MAX_NIP19_IDENTIFIER_CHARS {
        return Err(SoftchatError::InvalidNip19Identifier);
    }
    let has_lower = encoded.bytes().any(|byte| byte.is_ascii_lowercase());
    let has_upper = encoded.bytes().any(|byte| byte.is_ascii_uppercase());
    if has_lower && has_upper {
        return Err(SoftchatError::InvalidNip19Identifier);
    }
    Ok(())
}

fn parse_bare(kind: Nip19IdentifierKind, data: &[u8]) -> Result<Nip19Identifier, SoftchatError> {
    if data.len() != 32 {
        return Err(SoftchatError::InvalidNip19Identifier);
    }
    let primary_hex = match kind {
        Nip19IdentifierKind::PublicKey => {
            NostrPublicKey::from_hex(&hex::encode(data)).map(|key| key.to_hex())
        }
        Nip19IdentifierKind::EventId => {
            NostrEventId::from_hex(&hex::encode(data)).map(NostrEventId::to_hex)
        }
        Nip19IdentifierKind::Profile | Nip19IdentifierKind::Event => {
            return Err(SoftchatError::InvalidNip19Identifier);
        }
    }
    .map_err(|_| SoftchatError::InvalidNip19Identifier)?;
    Ok(Nip19Identifier {
        kind,
        primary_hex,
        relays: Vec::new(),
        author_hex: None,
        event_kind: None,
        unknown_tlvs: Vec::new(),
    })
}

fn parse_tlv(kind: Nip19IdentifierKind, data: &[u8]) -> Result<Nip19Identifier, SoftchatError> {
    let mut cursor = data;
    let mut primary_hex = None;
    let mut relays = Vec::new();
    let mut author_hex = None;
    let mut event_kind = None;
    let mut unknown_tlvs = Vec::new();
    while !cursor.is_empty() {
        let type_id = *cursor
            .first()
            .ok_or(SoftchatError::InvalidNip19Identifier)?;
        let length = usize::from(*cursor.get(1).ok_or(SoftchatError::InvalidNip19Identifier)?);
        let value = cursor
            .get(2..2 + length)
            .ok_or(SoftchatError::InvalidNip19Identifier)?;
        cursor = cursor
            .get(2 + length..)
            .ok_or(SoftchatError::InvalidNip19Identifier)?;
        match type_id {
            TLV_SPECIAL => {
                if primary_hex.is_some() || value.len() != 32 {
                    return Err(SoftchatError::InvalidNip19Identifier);
                }
                let hex = hex::encode(value);
                primary_hex = Some(match kind {
                    Nip19IdentifierKind::Profile => NostrPublicKey::from_hex(&hex)
                        .map(|key| key.to_hex())
                        .map_err(|_| SoftchatError::InvalidNip19Identifier)?,
                    Nip19IdentifierKind::Event => NostrEventId::from_hex(&hex)
                        .map(NostrEventId::to_hex)
                        .map_err(|_| SoftchatError::InvalidNip19Identifier)?,
                    Nip19IdentifierKind::PublicKey | Nip19IdentifierKind::EventId => {
                        return Err(SoftchatError::InvalidNip19Identifier);
                    }
                });
            }
            TLV_RELAY => {
                let relay = std::str::from_utf8(value)
                    .map_err(|_| SoftchatError::InvalidNip19Identifier)?
                    .to_owned();
                validate_relay(&relay)?;
                relays.push(relay);
                if relays.len() > MAX_NIP19_RELAYS {
                    return Err(SoftchatError::InvalidNip19Identifier);
                }
            }
            TLV_AUTHOR if kind == Nip19IdentifierKind::Event => {
                if author_hex.is_some() || value.len() != 32 {
                    return Err(SoftchatError::InvalidNip19Identifier);
                }
                author_hex = Some(
                    NostrPublicKey::from_hex(&hex::encode(value))
                        .map(|key| key.to_hex())
                        .map_err(|_| SoftchatError::InvalidNip19Identifier)?,
                );
            }
            TLV_KIND if kind == Nip19IdentifierKind::Event => {
                if event_kind.is_some() || value.len() != 4 {
                    return Err(SoftchatError::InvalidNip19Identifier);
                }
                let bytes: [u8; 4] = value
                    .try_into()
                    .map_err(|_| SoftchatError::InvalidNip19Identifier)?;
                event_kind = Some(
                    NostrEventKind::try_from_u32(u32::from_be_bytes(bytes))
                        .map_err(|_| SoftchatError::InvalidNip19Identifier)?,
                );
            }
            _ => unknown_tlvs.push(Nip19Tlv {
                type_id: u32::from(type_id),
                value: value.to_vec(),
            }),
        }
    }
    validate_relays(&relays)?;
    Ok(Nip19Identifier {
        kind,
        primary_hex: primary_hex.ok_or(SoftchatError::InvalidNip19Identifier)?,
        relays,
        author_hex,
        event_kind,
        unknown_tlvs,
    })
}

fn validate_relays(relays: &[String]) -> Result<(), SoftchatError> {
    if relays.len() > MAX_NIP19_RELAYS {
        return Err(SoftchatError::InvalidNip19Identifier);
    }
    for relay in relays {
        validate_relay(relay)?;
    }
    Ok(())
}

fn validate_relay(relay: &str) -> Result<(), SoftchatError> {
    if relay.is_empty()
        || relay.len() > MAX_RELAY_HINT_BYTES
        || (!relay.starts_with("ws://") && !relay.starts_with("wss://"))
        || nostr::RelayUrl::parse(relay).is_err()
    {
        return Err(SoftchatError::InvalidNip19Identifier);
    }
    Ok(())
}

fn push_tlv(output: &mut Vec<u8>, type_id: u8, value: &[u8]) -> Result<(), SoftchatError> {
    let length = u8::try_from(value.len()).map_err(|_| SoftchatError::InvalidNip19Identifier)?;
    output.push(type_id);
    output.push(length);
    output.extend_from_slice(value);
    Ok(())
}

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

    use super::*;

    #[derive(Deserialize)]
    #[serde(rename_all = "camelCase")]
    struct BareExample {
        encoded: String,
        public_key: String,
    }

    #[derive(Deserialize)]
    #[serde(rename_all = "camelCase")]
    struct ProfileExample {
        encoded: String,
        public_key: String,
        relays: Vec<String>,
    }

    #[derive(Deserialize)]
    struct Examples {
        npub: BareExample,
        nprofile: ProfileExample,
    }

    #[derive(Deserialize)]
    struct Fixture {
        examples: Examples,
    }

    fn official_fixture() -> Result<Fixture, serde_json::Error> {
        serde_json::from_str(include_str!(
            "../../../fixtures/nostr/nip19/nip19-official.json"
        ))
    }

    #[test]
    fn parses_official_public_key_and_profile_examples() -> Result<(), SoftchatError> {
        let fixture = official_fixture().map_err(|_| SoftchatError::InvalidNip19Identifier)?;
        let public_key = Nip19Identifier::parse(&fixture.examples.npub.encoded)?;
        assert_eq!(public_key.kind(), Nip19IdentifierKind::PublicKey);
        assert_eq!(public_key.primary_hex(), fixture.examples.npub.public_key);
        assert_eq!(public_key.encode()?, fixture.examples.npub.encoded);

        let profile = Nip19Identifier::parse(&fixture.examples.nprofile.encoded)?;
        assert_eq!(profile.kind(), Nip19IdentifierKind::Profile);
        assert_eq!(profile.primary_hex(), fixture.examples.nprofile.public_key);
        assert_eq!(profile.relays(), fixture.examples.nprofile.relays);
        assert_eq!(profile.encode()?, fixture.examples.nprofile.encoded);
        Ok(())
    }

    #[test]
    fn round_trips_nevent_unknown_tlv_and_rejects_mixed_case() -> Result<(), SoftchatError> {
        let value = Nip19Value {
            kind: Nip19IdentifierKind::Event,
            primary_hex: "44900586091b284416a0c001f677f9c49f7639a55c3f1e2ec130a8e1a7998e1b"
                .to_owned(),
            relays: vec!["wss://relay.example".to_owned()],
            author_hex: Some(
                "918e2da906df4ccd12c8ac672d8335add131a4cf9d27ce42b3bb3625755f0788".to_owned(),
            ),
            event_kind: Some(14),
            unknown_tlvs: vec![Nip19Tlv {
                type_id: 99,
                value: vec![0, 1, 2],
            }],
        };
        let encoded = encode_nip19_identifier(value.clone())?;
        assert_eq!(parse_nip19_identifier(encoded.clone())?, value);

        let mut mixed = encoded;
        mixed.replace_range(0..1, "N");
        assert!(matches!(
            Nip19Identifier::parse(&mixed),
            Err(SoftchatError::InvalidNip19Identifier)
        ));
        Ok(())
    }
}