softchat/

media.rs

//! Softchat inline attachment metadata, compatibility crypto, and NIP-98 plans.

use std::collections::BTreeSet;
use std::fmt;
use std::sync::{Mutex, MutexGuard};

use base64::Engine;
use base64::engine::general_purpose::STANDARD;
use chacha20::ChaCha20;
use chacha20::cipher::{KeyIvInit, StreamCipher, StreamCipherSeek};
use chacha20poly1305::aead::{Aead, KeyInit};
use chacha20poly1305::{ChaCha20Poly1305, Key, Nonce};
use nostr::secp256k1::rand::RngCore;
use nostr::secp256k1::rand::rngs::OsRng;
use poly1305::universal_hash::UniversalHash;
use poly1305::{Block as Poly1305Block, Poly1305, Tag as Poly1305Tag};
use serde::{Deserialize, Serialize};
use sha2::{Digest, Sha256};
use subtle::ConstantTimeEq;
use url::Url;
use zeroize::Zeroize;

use crate::{LocalIdentity, NostrEventDraft, NostrEventKind, NostrTag, SoftchatError};

/// Maximum number of fields after the leading `imeta` tag name.
pub const MAX_ATTACHMENT_METADATA_FIELDS: usize = 128;
/// Maximum number of fallback URLs in one canonical attachment.
pub const MAX_ATTACHMENT_FALLBACKS: usize = 16;
/// Maximum input for the whole-buffer released-client compatibility helper.
///
/// Production large-file adapters must use staged files and a reviewed
/// streaming implementation rather than crossing FFI with this operation.
pub const MAX_ATTACHMENT_COMPATIBILITY_BYTES: usize = 16 * 1024 * 1024;
/// Maximum plaintext bytes processed by one staged streaming operation.
pub const MAX_ATTACHMENT_STREAM_BYTES: u64 = 16 * 1024 * 1024 * 1024;
/// Maximum bytes accepted by one cross-language streaming call.
pub const MAX_ATTACHMENT_STREAM_CHUNK_BYTES: usize = 1024 * 1024;
/// Maximum normalized URL bytes accepted by one NIP-98 plan.
pub const MAX_HTTP_AUTHORIZATION_URL_BYTES: usize = 8 * 1024;
/// Maximum request-body bytes hashed by the whole-buffer NIP-98 helper.
pub const MAX_HTTP_AUTHORIZATION_PAYLOAD_BYTES: usize = MAX_ATTACHMENT_COMPATIBILITY_BYTES;
const ATTACHMENT_KEY_BYTES: usize = 32;
const ATTACHMENT_NONCE_BYTES: usize = 12;
const ATTACHMENT_TAG_BYTES: usize = 16;

/// Parsed canonical Softchat `imeta` metadata.
#[derive(Clone, Debug, Default, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
#[cfg_attr(feature = "native-bindings", derive(uniffi::Record))]
pub struct AttachmentMetadata {
    /// Required absolute HTTPS URL.
    pub url: String,
    /// Optional lowercase MIME type.
    pub mime_type: Option<String>,
    /// Optional SHA-256 hash of the referenced object.
    pub sha256: Option<String>,
    /// Optional SHA-256 hash of the pre-transform object.
    pub original_sha256: Option<String>,
    /// Optional byte size.
    pub byte_size: Option<u64>,
    /// Optional positive `<width>x<height>` dimensions.
    pub dimensions: Option<String>,
    /// Optional display name.
    pub name: Option<String>,
    /// Optional magnet URI.
    pub magnet: Option<String>,
    /// Optional torrent info hash.
    pub infohash: Option<String>,
    /// Optional blurhash.
    pub blurhash: Option<String>,
    /// Optional absolute HTTPS thumbnail URL.
    pub thumbnail_url: Option<String>,
    /// Optional absolute HTTPS preview URL.
    pub image_url: Option<String>,
    /// Optional summary.
    pub summary: Option<String>,
    /// Optional accessibility text.
    pub alt: Option<String>,
    /// Sorted absolute HTTPS fallback URLs.
    pub fallback_urls: Vec<String>,
    /// Optional storage service identifier.
    pub service: Option<String>,
    /// Opaque versioned encryption metadata. Never include it in diagnostics.
    pub encryption: Option<String>,
    /// Unknown raw `key value` fields retained in received order.
    pub unknown_fields: Vec<String>,
}

impl AttachmentMetadata {
    /// Parse a complete raw `imeta` tag.
    ///
    /// # Errors
    ///
    /// Returns [`SoftchatError::InvalidAttachmentMetadata`] for duplicate
    /// singleton fields, missing required values, or invalid typed values.
    pub fn from_tag(values: &[String]) -> Result<Self, SoftchatError> {
        if values.first().map(String::as_str) != Some("imeta")
            || values.len() < 2
            || values.len() - 1 > MAX_ATTACHMENT_METADATA_FIELDS
        {
            return Err(SoftchatError::InvalidAttachmentMetadata);
        }

        let mut result = Self::default();
        let mut seen = BTreeSet::new();
        for raw in &values[1..] {
            let (key, value) = split_field(raw)?;
            if key == "fallback" {
                if result.fallback_urls.len() >= MAX_ATTACHMENT_FALLBACKS {
                    return Err(SoftchatError::InvalidAttachmentMetadata);
                }
                validate_https_url(value)?;
                result.fallback_urls.push(value.to_owned());
                continue;
            }
            if is_known_singleton(key) && !seen.insert(key.to_owned()) {
                return Err(SoftchatError::InvalidAttachmentMetadata);
            }
            match key {
                "url" => {
                    validate_https_url(value)?;
                    result.url = value.to_owned();
                }
                "m" => {
                    validate_mime(value)?;
                    result.mime_type = Some(value.to_owned());
                }
                "x" => {
                    validate_sha256(value)?;
                    result.sha256 = Some(value.to_owned());
                }
                "ox" => {
                    validate_sha256(value)?;
                    result.original_sha256 = Some(value.to_owned());
                }
                "size" => {
                    result.byte_size = Some(
                        value
                            .parse()
                            .map_err(|_| SoftchatError::InvalidAttachmentMetadata)?,
                    );
                }
                "dim" => {
                    validate_dimensions(value)?;
                    result.dimensions = Some(value.to_owned());
                }
                "name" => result.name = Some(value.to_owned()),
                "magnet" => {
                    if !value.starts_with("magnet:?") {
                        return Err(SoftchatError::InvalidAttachmentMetadata);
                    }
                    result.magnet = Some(value.to_owned());
                }
                "i" => result.infohash = Some(value.to_owned()),
                "blurhash" => result.blurhash = Some(value.to_owned()),
                "thumb" => {
                    validate_https_url(value)?;
                    result.thumbnail_url = Some(value.to_owned());
                }
                "image" => {
                    validate_https_url(value)?;
                    result.image_url = Some(value.to_owned());
                }
                "summary" => result.summary = Some(value.to_owned()),
                "alt" => result.alt = Some(value.to_owned()),
                "service" => result.service = Some(value.to_owned()),
                "enc" => result.encryption = Some(value.to_owned()),
                _ => result.unknown_fields.push(raw.clone()),
            }
        }
        if result.url.is_empty() {
            return Err(SoftchatError::InvalidAttachmentMetadata);
        }
        result.fallback_urls.sort();
        Ok(result)
    }

    /// Emit the canonical field order from the accepted Softchat profile.
    ///
    /// # Errors
    ///
    /// Returns [`SoftchatError::InvalidAttachmentMetadata`] if the value is
    /// malformed or contains a duplicate known field through `unknown_fields`.
    pub fn to_tag(&self) -> Result<NostrTag, SoftchatError> {
        self.validate_for_write()?;
        let mut values = vec!["imeta".to_owned(), format!("url {}", self.url)];
        push_optional(&mut values, "m", &self.mime_type);
        push_optional(&mut values, "x", &self.sha256);
        push_optional(&mut values, "ox", &self.original_sha256);
        if let Some(byte_size) = self.byte_size {
            values.push(format!("size {byte_size}"));
        }
        push_optional(&mut values, "dim", &self.dimensions);
        push_optional(&mut values, "name", &self.name);
        push_optional(&mut values, "magnet", &self.magnet);
        push_optional(&mut values, "i", &self.infohash);
        push_optional(&mut values, "blurhash", &self.blurhash);
        push_optional(&mut values, "thumb", &self.thumbnail_url);
        push_optional(&mut values, "image", &self.image_url);
        push_optional(&mut values, "summary", &self.summary);
        push_optional(&mut values, "alt", &self.alt);
        let mut fallbacks = self.fallback_urls.clone();
        fallbacks.sort();
        for fallback in fallbacks {
            values.push(format!("fallback {fallback}"));
        }
        push_optional(&mut values, "service", &self.service);
        push_optional(&mut values, "enc", &self.encryption);
        values.extend(self.unknown_fields.iter().cloned());
        NostrTag::new(values).map_err(|_| SoftchatError::InvalidAttachmentMetadata)
    }

    fn validate_for_write(&self) -> Result<(), SoftchatError> {
        validate_https_url(&self.url)?;
        if let Some(value) = &self.mime_type {
            validate_mime(value)?;
        }
        for value in [&self.sha256, &self.original_sha256].into_iter().flatten() {
            validate_sha256(value)?;
        }
        if let Some(value) = &self.dimensions {
            validate_dimensions(value)?;
        }
        for value in [&self.thumbnail_url, &self.image_url].into_iter().flatten() {
            validate_https_url(value)?;
        }
        if self.fallback_urls.len() > MAX_ATTACHMENT_FALLBACKS {
            return Err(SoftchatError::InvalidAttachmentMetadata);
        }
        for value in &self.fallback_urls {
            validate_https_url(value)?;
        }
        let mut unknown_keys = BTreeSet::new();
        for raw in &self.unknown_fields {
            let (key, _) = split_field(raw)?;
            if is_known_singleton(key) || key == "fallback" || !unknown_keys.insert(key) {
                return Err(SoftchatError::InvalidAttachmentMetadata);
            }
        }
        if self.to_field_count() > MAX_ATTACHMENT_METADATA_FIELDS {
            return Err(SoftchatError::InvalidAttachmentMetadata);
        }
        Ok(())
    }

    fn to_field_count(&self) -> usize {
        1 + [
            self.mime_type.is_some(),
            self.sha256.is_some(),
            self.original_sha256.is_some(),
            self.byte_size.is_some(),
            self.dimensions.is_some(),
            self.name.is_some(),
            self.magnet.is_some(),
            self.infohash.is_some(),
            self.blurhash.is_some(),
            self.thumbnail_url.is_some(),
            self.image_url.is_some(),
            self.summary.is_some(),
            self.alt.is_some(),
            self.service.is_some(),
            self.encryption.is_some(),
        ]
        .into_iter()
        .filter(|present| *present)
        .count()
            + self.fallback_urls.len()
            + self.unknown_fields.len()
    }
}

/// Final authentication and hash values for one staged attachment transform.
#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
#[serde(rename_all = "camelCase")]
#[cfg_attr(feature = "native-bindings", derive(uniffi::Record))]
pub struct AttachmentStreamFinal {
    /// Detached 16-byte Poly1305 tag appended after encrypted bytes.
    pub authentication_tag: Vec<u8>,
    /// Lowercase SHA-256 of the complete plaintext.
    pub plaintext_sha256: String,
    /// Lowercase SHA-256 of `nonce || ciphertext || tag`.
    pub encrypted_sha256: String,
    /// Complete plaintext/ciphertext byte count, excluding nonce and tag.
    pub byte_count: u64,
}

struct AttachmentStreamState {
    cipher: ChaCha20,
    mac: Poly1305,
    mac_tail: Vec<u8>,
    plaintext_hash: Sha256,
    encrypted_hash: Sha256,
    byte_count: u64,
}

impl fmt::Debug for AttachmentStreamState {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter
            .debug_struct("AttachmentStreamState")
            .field("byte_count", &self.byte_count)
            .finish_non_exhaustive()
    }
}

impl AttachmentStreamState {
    fn new(mut key_bytes: Vec<u8>, nonce: &[u8]) -> Result<Self, SoftchatError> {
        if key_bytes.len() != ATTACHMENT_KEY_BYTES || nonce.len() != ATTACHMENT_NONCE_BYTES {
            key_bytes.zeroize();
            return Err(SoftchatError::AttachmentEncryptionFailed);
        }
        let mut cipher = ChaCha20::new_from_slices(&key_bytes, nonce).map_err(|_| {
            key_bytes.zeroize();
            SoftchatError::AttachmentEncryptionFailed
        })?;
        key_bytes.zeroize();

        let mut mac_key = poly1305::Key::default();
        cipher.apply_keystream(&mut mac_key);
        let mac = Poly1305::new(&mac_key);
        mac_key.zeroize();
        cipher.seek(64);

        let mut encrypted_hash = Sha256::new();
        encrypted_hash.update(nonce);
        Ok(Self {
            cipher,
            mac,
            mac_tail: Vec::with_capacity(poly1305::BLOCK_SIZE),
            plaintext_hash: Sha256::new(),
            encrypted_hash,
            byte_count: 0,
        })
    }

    fn reserve_chunk(
        &mut self,
        chunk_len: usize,
        error: SoftchatError,
    ) -> Result<(), SoftchatError> {
        if chunk_len > MAX_ATTACHMENT_STREAM_CHUNK_BYTES {
            return Err(error);
        }
        let chunk_len = u64::try_from(chunk_len).map_err(|_| error)?;
        self.byte_count = self
            .byte_count
            .checked_add(chunk_len)
            .filter(|total| *total <= MAX_ATTACHMENT_STREAM_BYTES)
            .ok_or(error)?;
        Ok(())
    }

    fn authenticate_ciphertext(&mut self, ciphertext: &[u8]) {
        let mut remaining = ciphertext;
        if !self.mac_tail.is_empty() {
            let needed = poly1305::BLOCK_SIZE - self.mac_tail.len();
            let copied = needed.min(remaining.len());
            self.mac_tail.extend_from_slice(&remaining[..copied]);
            remaining = &remaining[copied..];
            if self.mac_tail.len() == poly1305::BLOCK_SIZE {
                self.mac
                    .update(&[Poly1305Block::clone_from_slice(&self.mac_tail)]);
                self.mac_tail.clear();
            }
        }

        let mut blocks = remaining.chunks_exact(poly1305::BLOCK_SIZE);
        for block in &mut blocks {
            self.mac.update(&[Poly1305Block::clone_from_slice(block)]);
        }
        self.mac_tail.extend_from_slice(blocks.remainder());
    }

    fn finish_mac(mut self) -> (Poly1305Tag, Sha256, Sha256, u64) {
        if !self.mac_tail.is_empty() {
            let mut block = Poly1305Block::default();
            block[..self.mac_tail.len()].copy_from_slice(&self.mac_tail);
            self.mac.update(&[block]);
            self.mac_tail.zeroize();
        }

        let mut lengths = Poly1305Block::default();
        lengths[8..].copy_from_slice(&self.byte_count.to_le_bytes());
        self.mac.update(&[lengths]);
        let tag = self.mac.finalize();
        (
            tag,
            self.plaintext_hash,
            self.encrypted_hash,
            self.byte_count,
        )
    }
}

/// Incremental encryption compatible with released clients' combined
/// `nonce12 || ciphertext || tag16` attachment format.
///
/// The host writes [`Self::nonce`] first, each [`Self::update`] result to a
/// private staged file, then [`AttachmentStreamFinal::authentication_tag`].
/// It publishes the staged file only after `finish` succeeds.
///
/// [Guide and performance](https://softchat-sdk.jackl.dev/media-and-http/#stream-encryption)
#[cfg_attr(feature = "native-bindings", derive(uniffi::Object))]
pub struct AttachmentEncryptionStream {
    encryption_descriptor: String,
    nonce: [u8; ATTACHMENT_NONCE_BYTES],
    state: Mutex<Option<AttachmentStreamState>>,
}

impl fmt::Debug for AttachmentEncryptionStream {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter
            .debug_struct("AttachmentEncryptionStream")
            .finish_non_exhaustive()
    }
}

#[cfg_attr(feature = "native-bindings", uniffi::export)]
impl AttachmentEncryptionStream {
    /// Start one stream with a Rust-generated 256-bit attachment key.
    ///
    /// The returned [`Self::encryption_descriptor`] is the released
    /// base64-encoded `enc` value retained in authenticated attachment
    /// metadata. Raw key bytes never cross the language boundary.
    ///
    /// # Errors
    ///
    /// Returns a stable attachment-encryption failure.
    #[cfg_attr(feature = "native-bindings", uniffi::constructor)]
    pub fn random() -> Result<Self, SoftchatError> {
        let mut key_bytes = vec![0_u8; ATTACHMENT_KEY_BYTES];
        OsRng.fill_bytes(&mut key_bytes);
        Self::new(key_bytes)
    }

    /// Start one random-nonce attachment encryption stream.
    ///
    /// # Errors
    ///
    /// Returns a stable failure unless `key_bytes` contains exactly 32 bytes.
    #[cfg_attr(feature = "native-bindings", uniffi::constructor)]
    pub fn new(key_bytes: Vec<u8>) -> Result<Self, SoftchatError> {
        if key_bytes.len() != ATTACHMENT_KEY_BYTES {
            return Err(SoftchatError::AttachmentEncryptionFailed);
        }
        let encryption_descriptor = STANDARD.encode(&key_bytes);
        let mut nonce = [0_u8; ATTACHMENT_NONCE_BYTES];
        OsRng.fill_bytes(&mut nonce);
        Self::new_with_nonce_and_descriptor(key_bytes, nonce, encryption_descriptor)
    }

    /// Return the released-client base64 `enc` metadata value.
    ///
    /// This descriptor grants decryption authority and must never be logged.
    #[must_use]
    pub fn encryption_descriptor(&self) -> String {
        self.encryption_descriptor.clone()
    }

    /// Return the 12-byte prefix that must be written before ciphertext.
    #[must_use]
    pub fn nonce(&self) -> Vec<u8> {
        self.nonce.to_vec()
    }

    /// Encrypt one bounded plaintext chunk.
    ///
    /// # Errors
    ///
    /// Returns a stable failure after finish/cancel or when cumulative or
    /// per-call bounds are exceeded.
    pub fn update(&self, mut plaintext: Vec<u8>) -> Result<Vec<u8>, SoftchatError> {
        let mut guard = lock_stream(&self.state);
        let state = guard
            .as_mut()
            .ok_or(SoftchatError::AttachmentEncryptionFailed)?;
        state.reserve_chunk(plaintext.len(), SoftchatError::AttachmentTooLarge)?;
        state.plaintext_hash.update(&plaintext);
        state.cipher.apply_keystream(&mut plaintext);
        state.authenticate_ciphertext(&plaintext);
        state.encrypted_hash.update(&plaintext);
        Ok(plaintext)
    }

    /// Finish authentication and consume the stream.
    ///
    /// # Errors
    ///
    /// Returns a stable failure after finish or cancellation.
    pub fn finish(&self) -> Result<AttachmentStreamFinal, SoftchatError> {
        let state = lock_stream(&self.state)
            .take()
            .ok_or(SoftchatError::AttachmentEncryptionFailed)?;
        let (tag, plaintext_hash, mut encrypted_hash, byte_count) = state.finish_mac();
        encrypted_hash.update(tag);
        Ok(AttachmentStreamFinal {
            authentication_tag: tag.to_vec(),
            plaintext_sha256: hex::encode(plaintext_hash.finalize()),
            encrypted_sha256: hex::encode(encrypted_hash.finalize()),
            byte_count,
        })
    }

    /// Cancel and zeroize remaining stream state.
    pub fn cancel(&self) {
        lock_stream(&self.state).take();
    }
}

impl AttachmentEncryptionStream {
    #[cfg(test)]
    fn new_with_nonce(
        key_bytes: Vec<u8>,
        nonce: [u8; ATTACHMENT_NONCE_BYTES],
    ) -> Result<Self, SoftchatError> {
        if key_bytes.len() != ATTACHMENT_KEY_BYTES {
            return Err(SoftchatError::AttachmentEncryptionFailed);
        }
        let encryption_descriptor = STANDARD.encode(&key_bytes);
        Self::new_with_nonce_and_descriptor(key_bytes, nonce, encryption_descriptor)
    }

    fn new_with_nonce_and_descriptor(
        key_bytes: Vec<u8>,
        nonce: [u8; ATTACHMENT_NONCE_BYTES],
        encryption_descriptor: String,
    ) -> Result<Self, SoftchatError> {
        Ok(Self {
            state: Mutex::new(Some(AttachmentStreamState::new(key_bytes, &nonce)?)),
            encryption_descriptor,
            nonce,
        })
    }
}

/// Incremental authenticated decryption for a private staged destination.
///
/// `update` returns unauthenticated plaintext bytes. The host must write them
/// only to a private temporary destination and must delete that destination
/// unless [`Self::finish`] authenticates the final tag. No plaintext may be
/// displayed, indexed, or atomically published before that success.
#[cfg_attr(feature = "native-bindings", derive(uniffi::Object))]
pub struct AttachmentDecryptionStream {
    state: Mutex<Option<AttachmentStreamState>>,
}

impl fmt::Debug for AttachmentDecryptionStream {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter
            .debug_struct("AttachmentDecryptionStream")
            .finish_non_exhaustive()
    }
}

#[cfg_attr(feature = "native-bindings", uniffi::export)]
impl AttachmentDecryptionStream {
    /// Start decryption from released base64 `enc` metadata and nonce prefix.
    ///
    /// # Errors
    ///
    /// All malformed descriptor, nonce, and key failures map to one redacted
    /// attachment-decryption error.
    #[cfg_attr(feature = "native-bindings", uniffi::constructor)]
    pub fn from_encryption_descriptor(
        encryption_descriptor: String,
        nonce: Vec<u8>,
    ) -> Result<Self, SoftchatError> {
        let key_bytes = STANDARD
            .decode(encryption_descriptor)
            .map_err(|_| SoftchatError::AttachmentDecryptionFailed)?;
        Self::new(key_bytes, nonce)
    }

    /// Start decryption from the 12-byte combined-format prefix.
    ///
    /// # Errors
    ///
    /// Returns a stable failure for an invalid key or nonce length.
    #[cfg_attr(feature = "native-bindings", uniffi::constructor)]
    pub fn new(key_bytes: Vec<u8>, nonce: Vec<u8>) -> Result<Self, SoftchatError> {
        AttachmentStreamState::new(key_bytes, &nonce)
            .map(|state| Self {
                state: Mutex::new(Some(state)),
            })
            .map_err(|_| SoftchatError::AttachmentDecryptionFailed)
    }

    /// Decrypt one bounded ciphertext chunk into private staged bytes.
    ///
    /// # Errors
    ///
    /// Returns a stable failure after finish/cancel or when bounds are
    /// exceeded.
    pub fn update(&self, mut ciphertext: Vec<u8>) -> Result<Vec<u8>, SoftchatError> {
        let mut guard = lock_stream(&self.state);
        let state = guard
            .as_mut()
            .ok_or(SoftchatError::AttachmentDecryptionFailed)?;
        state.reserve_chunk(ciphertext.len(), SoftchatError::AttachmentTooLarge)?;
        state.authenticate_ciphertext(&ciphertext);
        state.encrypted_hash.update(&ciphertext);
        state.cipher.apply_keystream(&mut ciphertext);
        state.plaintext_hash.update(&ciphertext);
        Ok(ciphertext)
    }

    /// Authenticate the final 16-byte tag before an atomic staged-file move.
    ///
    /// # Errors
    ///
    /// Returns a stable decryption failure for a wrong key, tampering, invalid
    /// tag length, cancellation, or repeated finish.
    pub fn finish(
        &self,
        authentication_tag: Vec<u8>,
    ) -> Result<AttachmentStreamFinal, SoftchatError> {
        if authentication_tag.len() != ATTACHMENT_TAG_BYTES {
            return Err(SoftchatError::AttachmentDecryptionFailed);
        }
        let state = lock_stream(&self.state)
            .take()
            .ok_or(SoftchatError::AttachmentDecryptionFailed)?;
        let (computed_tag, plaintext_hash, mut encrypted_hash, byte_count) = state.finish_mac();
        let expected_tag = Poly1305Tag::clone_from_slice(&authentication_tag);
        if !bool::from(computed_tag.ct_eq(&expected_tag)) {
            return Err(SoftchatError::AttachmentDecryptionFailed);
        }
        encrypted_hash.update(&authentication_tag);
        Ok(AttachmentStreamFinal {
            authentication_tag,
            plaintext_sha256: hex::encode(plaintext_hash.finalize()),
            encrypted_sha256: hex::encode(encrypted_hash.finalize()),
            byte_count,
        })
    }

    /// Cancel and zeroize remaining stream state.
    pub fn cancel(&self) {
        lock_stream(&self.state).take();
    }
}

fn lock_stream<T>(mutex: &Mutex<T>) -> MutexGuard<'_, T> {
    match mutex.lock() {
        Ok(guard) => guard,
        Err(poisoned) => poisoned.into_inner(),
    }
}

/// Immutable NIP-98 authorization result for platform HTTP adapters.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct HttpAuthorizationPlan {
    /// Uppercase HTTP method bound by the event.
    pub method: String,
    /// Exact normalized URL bound by the event.
    pub url: String,
    /// Lowercase payload SHA-256, or empty when the request has no body.
    pub payload_sha256: String,
    /// Complete `Nostr <base64-event-json>` header value.
    pub authorization_header: String,
    /// Signed authorization event for diagnostics-free validation.
    pub event: crate::SignedNostrEvent,
    /// Redirects require a fresh plan; adapters must not forward this header.
    pub allow_authorization_on_redirect: bool,
}

/// Binding record for an immutable NIP-98 authorization result.
#[cfg(any(
    feature = "sqlite-storage",
    feature = "native-bindings",
    all(feature = "javascript-bindings", target_arch = "wasm32"),
    test
))]
#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
#[serde(rename_all = "camelCase")]
#[cfg_attr(feature = "native-bindings", derive(uniffi::Record))]
#[allow(
    unreachable_pub,
    reason = "UniFFI requires a public type inside this private adapter module"
)]
pub struct FfiHttpAuthorizationPlan {
    /// Uppercase HTTP method bound by the event.
    pub method: String,
    /// Exact normalized URL bound by the event.
    pub url: String,
    /// Lowercase payload SHA-256, or empty when the request has no body.
    pub payload_sha256: String,
    /// Complete `Nostr <base64-event-json>` header value.
    pub authorization_header: String,
    /// Flat signed-event binding value.
    pub event: crate::event::SignedEvent,
    /// Redirects require a fresh plan.
    pub allow_authorization_on_redirect: bool,
}

#[cfg(any(
    feature = "sqlite-storage",
    feature = "native-bindings",
    all(feature = "javascript-bindings", target_arch = "wasm32"),
    test
))]
impl From<HttpAuthorizationPlan> for FfiHttpAuthorizationPlan {
    fn from(plan: HttpAuthorizationPlan) -> Self {
        Self {
            method: plan.method,
            url: plan.url,
            payload_sha256: plan.payload_sha256,
            authorization_header: plan.authorization_header,
            event: crate::event::SignedEvent::from(&plan.event),
            allow_authorization_on_redirect: plan.allow_authorization_on_redirect,
        }
    }
}

/// Parse one complete `imeta` tag at generated binding boundaries.
///
/// # Errors
///
/// Returns a stable metadata error for malformed input.
#[cfg_attr(feature = "native-bindings", uniffi::export)]
pub fn parse_attachment_metadata(
    tag_values: Vec<String>,
) -> Result<AttachmentMetadata, SoftchatError> {
    AttachmentMetadata::from_tag(&tag_values)
}

/// Encrypt a bounded released-client-compatible attachment value.
///
/// The output is `12-byte nonce || ciphertext || 16-byte tag`, matching
/// CryptoKit `ChaChaPoly.SealedBox.combined` and the released Android writer.
/// Large files must use platform-owned staged-file adapters; this helper is
/// intentionally bounded so callers cannot accidentally buffer arbitrary
/// attachments across FFI.
///
/// # Errors
///
/// Returns a stable key, size, or encryption failure.
#[cfg_attr(feature = "native-bindings", uniffi::export)]
pub fn encrypt_attachment_bytes(
    plaintext: Vec<u8>,
    key_bytes: Vec<u8>,
) -> Result<Vec<u8>, SoftchatError> {
    validate_attachment_input(plaintext.len(), key_bytes.len())?;
    let cipher = ChaCha20Poly1305::new(Key::from_slice(&key_bytes));
    let mut nonce_bytes = [0_u8; ATTACHMENT_NONCE_BYTES];
    OsRng.fill_bytes(&mut nonce_bytes);
    let ciphertext = cipher
        .encrypt(Nonce::from_slice(&nonce_bytes), plaintext.as_ref())
        .map_err(|_| SoftchatError::AttachmentEncryptionFailed)?;
    let mut output = Vec::with_capacity(ATTACHMENT_NONCE_BYTES + ciphertext.len());
    output.extend_from_slice(&nonce_bytes);
    output.extend_from_slice(&ciphertext);
    Ok(output)
}

/// Authenticate and decrypt a bounded released-client attachment value.
///
/// # Errors
///
/// All malformed nonce, tag, key, and authentication failures map to one
/// redacted error.
#[cfg_attr(feature = "native-bindings", uniffi::export)]
pub fn decrypt_attachment_bytes(
    encrypted: Vec<u8>,
    key_bytes: Vec<u8>,
) -> Result<Vec<u8>, SoftchatError> {
    if key_bytes.len() != ATTACHMENT_KEY_BYTES
        || encrypted.len() < ATTACHMENT_NONCE_BYTES + ATTACHMENT_TAG_BYTES
        || encrypted.len()
            > MAX_ATTACHMENT_COMPATIBILITY_BYTES + ATTACHMENT_NONCE_BYTES + ATTACHMENT_TAG_BYTES
    {
        return Err(SoftchatError::AttachmentDecryptionFailed);
    }
    let (nonce_bytes, ciphertext) = encrypted.split_at(ATTACHMENT_NONCE_BYTES);
    let cipher = ChaCha20Poly1305::new(Key::from_slice(&key_bytes));
    cipher
        .decrypt(Nonce::from_slice(nonce_bytes), ciphertext)
        .map_err(|_| SoftchatError::AttachmentDecryptionFailed)
}

/// Create an immutable, signed NIP-98 HTTP authorization plan.
///
/// Platform adapters execute the request and must create a fresh plan after
/// any redirect. The Authorization header is deliberately not reusable on a
/// different method or URL.
///
/// # Errors
///
/// Returns [`SoftchatError::InvalidHttpAuthorization`] for invalid methods,
/// URLs, payload bounds, or signing failures.
pub fn create_nip98_authorization(
    identity: &LocalIdentity,
    method: &str,
    url: &str,
    payload: Option<&[u8]>,
    created_at: u64,
) -> Result<HttpAuthorizationPlan, SoftchatError> {
    if payload.is_some_and(|value| value.len() > MAX_HTTP_AUTHORIZATION_PAYLOAD_BYTES) {
        return Err(SoftchatError::InvalidHttpAuthorization);
    }
    let method = validate_http_method(method)?;
    let url = validate_http_url(url)?;
    let payload_sha256 = payload.map(|bytes| hex::encode(Sha256::digest(bytes)));
    create_nip98_authorization_for_validated_hash(identity, method, url, payload_sha256, created_at)
}

/// Create a NIP-98 plan from a SHA-256 produced while streaming a request body.
///
/// This is the production attachment-upload path: platform HTTP/file code
/// streams the body, then passes its lowercase hexadecimal digest without
/// copying the full payload across FFI.
///
/// # Errors
///
/// Returns [`SoftchatError::InvalidHttpAuthorization`] for an invalid method,
/// URL, digest, timestamp, or signing failure.
pub fn create_nip98_authorization_for_payload_hash(
    identity: &LocalIdentity,
    method: &str,
    url: &str,
    payload_sha256: &str,
    created_at: u64,
) -> Result<HttpAuthorizationPlan, SoftchatError> {
    let method = validate_http_method(method)?;
    let url = validate_http_url(url)?;
    validate_sha256(payload_sha256).map_err(|_| SoftchatError::InvalidHttpAuthorization)?;
    create_nip98_authorization_for_validated_hash(
        identity,
        method,
        url,
        Some(payload_sha256.to_owned()),
        created_at,
    )
}

fn create_nip98_authorization_for_validated_hash(
    identity: &LocalIdentity,
    method: String,
    url: Url,
    payload_sha256: Option<String>,
    created_at: u64,
) -> Result<HttpAuthorizationPlan, SoftchatError> {
    let mut tags = vec![
        NostrTag::new(vec!["u", url.as_str()])
            .map_err(|_| SoftchatError::InvalidHttpAuthorization)?,
        NostrTag::new(vec!["method", method.as_str()])
            .map_err(|_| SoftchatError::InvalidHttpAuthorization)?,
    ];
    if let Some(hash) = &payload_sha256 {
        tags.push(
            NostrTag::new(vec!["payload", hash.as_str()])
                .map_err(|_| SoftchatError::InvalidHttpAuthorization)?,
        );
    }
    let event = identity
        .sign_event(
            NostrEventDraft::new(created_at, NostrEventKind::HTTP_AUTHENTICATION, tags, "")
                .map_err(|_| SoftchatError::InvalidHttpAuthorization)?,
        )
        .map_err(|_| SoftchatError::InvalidHttpAuthorization)?;
    let event_json = event
        .to_json()
        .map_err(|_| SoftchatError::InvalidHttpAuthorization)?;
    Ok(HttpAuthorizationPlan {
        method,
        url: url.to_string(),
        payload_sha256: payload_sha256.unwrap_or_default(),
        authorization_header: format!("Nostr {}", STANDARD.encode(event_json)),
        event,
        allow_authorization_on_redirect: false,
    })
}

fn split_field(raw: &str) -> Result<(&str, &str), SoftchatError> {
    let (key, value) = raw
        .split_once(' ')
        .ok_or(SoftchatError::InvalidAttachmentMetadata)?;
    if key.is_empty() || value.is_empty() {
        return Err(SoftchatError::InvalidAttachmentMetadata);
    }
    Ok((key, value))
}

fn is_known_singleton(key: &str) -> bool {
    matches!(
        key,
        "url"
            | "m"
            | "x"
            | "ox"
            | "size"
            | "dim"
            | "name"
            | "magnet"
            | "i"
            | "blurhash"
            | "thumb"
            | "image"
            | "summary"
            | "alt"
            | "service"
            | "enc"
    )
}

fn validate_https_url(value: &str) -> Result<(), SoftchatError> {
    let url = Url::parse(value).map_err(|_| SoftchatError::InvalidAttachmentMetadata)?;
    if url.scheme() != "https"
        || url.host_str().is_none()
        || !url.username().is_empty()
        || url.password().is_some()
        || url.fragment().is_some()
    {
        return Err(SoftchatError::InvalidAttachmentMetadata);
    }
    Ok(())
}

fn validate_mime(value: &str) -> Result<(), SoftchatError> {
    if value.is_empty()
        || value.bytes().any(|byte| byte.is_ascii_uppercase())
        || !value.contains('/')
        || value.chars().any(char::is_whitespace)
    {
        return Err(SoftchatError::InvalidAttachmentMetadata);
    }
    Ok(())
}

fn validate_sha256(value: &str) -> Result<(), SoftchatError> {
    if value.len() != 64
        || !value
            .bytes()
            .all(|byte| byte.is_ascii_hexdigit() && !byte.is_ascii_uppercase())
    {
        return Err(SoftchatError::InvalidAttachmentMetadata);
    }
    Ok(())
}

fn validate_dimensions(value: &str) -> Result<(), SoftchatError> {
    let (width, height) = value
        .split_once('x')
        .ok_or(SoftchatError::InvalidAttachmentMetadata)?;
    let width: u32 = width
        .parse()
        .map_err(|_| SoftchatError::InvalidAttachmentMetadata)?;
    let height: u32 = height
        .parse()
        .map_err(|_| SoftchatError::InvalidAttachmentMetadata)?;
    if width == 0 || height == 0 {
        return Err(SoftchatError::InvalidAttachmentMetadata);
    }
    Ok(())
}

fn push_optional(values: &mut Vec<String>, key: &str, value: &Option<String>) {
    if let Some(value) = value {
        values.push(format!("{key} {value}"));
    }
}

fn validate_attachment_input(
    plaintext_length: usize,
    key_length: usize,
) -> Result<(), SoftchatError> {
    if key_length != ATTACHMENT_KEY_BYTES {
        return Err(SoftchatError::AttachmentEncryptionFailed);
    }
    if plaintext_length > MAX_ATTACHMENT_COMPATIBILITY_BYTES {
        return Err(SoftchatError::AttachmentTooLarge);
    }
    Ok(())
}

fn validate_http_method(method: &str) -> Result<String, SoftchatError> {
    if method.is_empty()
        || method.len() > 32
        || !method.bytes().all(|byte| byte.is_ascii_alphabetic())
    {
        return Err(SoftchatError::InvalidHttpAuthorization);
    }
    Ok(method.to_ascii_uppercase())
}

fn validate_http_url(value: &str) -> Result<Url, SoftchatError> {
    if value.is_empty() || value.len() > MAX_HTTP_AUTHORIZATION_URL_BYTES {
        return Err(SoftchatError::InvalidHttpAuthorization);
    }
    let url = Url::parse(value).map_err(|_| SoftchatError::InvalidHttpAuthorization)?;
    if !matches!(url.scheme(), "http" | "https")
        || url.host_str().is_none()
        || url.username() != ""
        || url.password().is_some()
        || url.fragment().is_some()
    {
        return Err(SoftchatError::InvalidHttpAuthorization);
    }
    Ok(url)
}

#[cfg(test)]
mod tests {
    use super::*;

    const ALICE_SECRET: &str = "5c0c523f52a5b6fad39ed2403092df8cebc36318b39383bca6c00808626fab3a";

    #[test]
    fn parses_released_attachment_and_emits_canonical_order() -> Result<(), SoftchatError> {
        let raw = vec![
            "imeta".to_owned(),
            "url https://cdn.example/voice.m4a".to_owned(),
            "m audio/mp4".to_owned(),
            "name voice note.m4a".to_owned(),
            "thumb https://cdn.example/voice.webp".to_owned(),
            "enc v1:synthetic".to_owned(),
            "future retained value".to_owned(),
        ];
        let metadata = AttachmentMetadata::from_tag(&raw)?;
        assert_eq!(metadata.name.as_deref(), Some("voice note.m4a"));
        assert_eq!(
            metadata.to_tag()?.values(),
            [
                "imeta",
                "url https://cdn.example/voice.m4a",
                "m audio/mp4",
                "name voice note.m4a",
                "thumb https://cdn.example/voice.webp",
                "enc v1:synthetic",
                "future retained value",
            ]
        );
        Ok(())
    }

    #[test]
    fn attachment_metadata_rejects_duplicates_and_invalid_typed_fields() {
        for values in [
            vec!["imeta", "url https://a.example", "url https://b.example"],
            vec!["imeta", "url http://a.example"],
            vec!["imeta", "url https://[email protected]/file"],
            vec!["imeta", "url https://user:[email protected]/file"],
            vec!["imeta", "url https://a.example/file#fragment"],
            vec!["imeta", "url https://a.example", "m Image/PNG"],
            vec!["imeta", "url https://a.example", "dim 0x1"],
            vec!["imeta", "url https://a.example", "x ab"],
        ] {
            let values = values.into_iter().map(str::to_owned).collect::<Vec<_>>();
            assert!(AttachmentMetadata::from_tag(&values).is_err());
        }
    }

    #[test]
    fn attachment_crypto_matches_combined_shape_and_authenticates() -> Result<(), SoftchatError> {
        let key = (0_u8..32).collect::<Vec<_>>();
        let plaintext = b"authenticated attachment".to_vec();
        let encrypted = encrypt_attachment_bytes(plaintext.clone(), key.clone())?;
        assert_eq!(
            encrypted.len(),
            plaintext.len() + ATTACHMENT_NONCE_BYTES + ATTACHMENT_TAG_BYTES
        );
        assert_eq!(decrypt_attachment_bytes(encrypted.clone(), key)?, plaintext);
        let mut tampered = encrypted;
        if let Some(last) = tampered.last_mut() {
            *last ^= 1;
        }
        assert!(decrypt_attachment_bytes(tampered, vec![0; 32]).is_err());
        Ok(())
    }

    #[test]
    fn streaming_attachment_crypto_matches_released_combined_format() -> Result<(), SoftchatError> {
        let key = vec![0x42; ATTACHMENT_KEY_BYTES];
        let nonce = [0x24; ATTACHMENT_NONCE_BYTES];
        let plaintext = (0..131_111)
            .map(|index| (index % 251) as u8)
            .collect::<Vec<_>>();

        let expected_ciphertext = ChaCha20Poly1305::new(Key::from_slice(&key))
            .encrypt(Nonce::from_slice(&nonce), plaintext.as_ref())
            .map_err(|_| SoftchatError::AttachmentEncryptionFailed)?;
        let expected_split = expected_ciphertext.len() - ATTACHMENT_TAG_BYTES;

        let encryptor = AttachmentEncryptionStream::new_with_nonce(key.clone(), nonce)?;
        let mut ciphertext = Vec::new();
        for chunk in plaintext.chunks(997) {
            ciphertext.extend(encryptor.update(chunk.to_vec())?);
        }
        let encrypted_final = encryptor.finish()?;
        assert_eq!(ciphertext, expected_ciphertext[..expected_split]);
        assert_eq!(
            encrypted_final.authentication_tag,
            expected_ciphertext[expected_split..]
        );
        assert_eq!(
            encrypted_final.plaintext_sha256,
            hex::encode(Sha256::digest(&plaintext))
        );

        let decryptor = AttachmentDecryptionStream::new(key.clone(), nonce.to_vec())?;
        let mut decrypted = Vec::new();
        for chunk in ciphertext.chunks(509) {
            decrypted.extend(decryptor.update(chunk.to_vec())?);
        }
        let decrypted_final = decryptor.finish(expected_ciphertext[expected_split..].to_vec())?;
        assert_eq!(decrypted, plaintext);
        assert_eq!(
            decrypted_final.encrypted_sha256,
            encrypted_final.encrypted_sha256
        );

        let tampered = AttachmentDecryptionStream::new(key, nonce.to_vec())?;
        let _staged_plaintext = tampered.update(ciphertext)?;
        let mut bad_tag = expected_ciphertext[expected_split..].to_vec();
        bad_tag[0] ^= 1;
        assert!(matches!(
            tampered.finish(bad_tag),
            Err(SoftchatError::AttachmentDecryptionFailed)
        ));
        Ok(())
    }

    #[test]
    fn streaming_attachment_crypto_supports_empty_files_and_cancellation()
    -> Result<(), SoftchatError> {
        let key = vec![0x55; ATTACHMENT_KEY_BYTES];
        let nonce = [0x11; ATTACHMENT_NONCE_BYTES];
        let expected = ChaCha20Poly1305::new(Key::from_slice(&key))
            .encrypt(Nonce::from_slice(&nonce), [].as_ref())
            .map_err(|_| SoftchatError::AttachmentEncryptionFailed)?;
        let encryptor = AttachmentEncryptionStream::new_with_nonce(key.clone(), nonce)?;
        assert_eq!(encryptor.finish()?.authentication_tag, expected);

        let cancelled = AttachmentEncryptionStream::new(key)?;
        cancelled.cancel();
        assert!(matches!(
            cancelled.update(vec![1]),
            Err(SoftchatError::AttachmentEncryptionFailed)
        ));
        Ok(())
    }

    #[test]
    fn random_stream_descriptor_round_trips_without_exporting_raw_key() -> Result<(), SoftchatError>
    {
        let plaintext = b"descriptor-owned key".to_vec();
        let encryptor = AttachmentEncryptionStream::random()?;
        let descriptor = encryptor.encryption_descriptor();
        assert_eq!(
            STANDARD
                .decode(&descriptor)
                .map_err(|_| SoftchatError::AttachmentEncryptionFailed)?
                .len(),
            ATTACHMENT_KEY_BYTES
        );
        let nonce = encryptor.nonce();
        let ciphertext = encryptor.update(plaintext.clone())?;
        let final_value = encryptor.finish()?;

        let decryptor = AttachmentDecryptionStream::from_encryption_descriptor(descriptor, nonce)?;
        assert_eq!(decryptor.update(ciphertext)?, plaintext);
        decryptor.finish(final_value.authentication_tag)?;
        assert!(
            AttachmentDecryptionStream::from_encryption_descriptor(
                "not-base64".to_owned(),
                vec![0; ATTACHMENT_NONCE_BYTES],
            )
            .is_err()
        );
        Ok(())
    }

    #[test]
    fn nip98_plan_binds_method_url_payload_and_forbids_redirect_reuse() -> Result<(), SoftchatError>
    {
        let identity = LocalIdentity::from_secret_hex(ALICE_SECRET)?;
        let plan = create_nip98_authorization(
            &identity,
            "PUT",
            "https://files.example/upload?part=1",
            Some(b"payload"),
            1_700_000_000,
        )?;
        assert_eq!(plan.method, "PUT");
        assert_eq!(plan.payload_sha256, hex::encode(Sha256::digest(b"payload")));
        assert!(plan.authorization_header.starts_with("Nostr "));
        assert!(!plan.allow_authorization_on_redirect);
        assert_eq!(plan.event.kind(), NostrEventKind::HTTP_AUTHENTICATION);
        assert!(plan.event.tags().any(|tag| tag == ["method", "PUT"]));
        let streamed = create_nip98_authorization_for_payload_hash(
            &identity,
            "PUT",
            "https://files.example/upload?part=1",
            &plan.payload_sha256,
            1_700_000_001,
        )?;
        assert_eq!(streamed.payload_sha256, plan.payload_sha256);
        assert!(
            streamed
                .event
                .tags()
                .any(|tag| tag == ["payload", plan.payload_sha256.as_str()])
        );
        assert!(
            create_nip98_authorization_for_payload_hash(
                &identity,
                "PUT",
                "https://files.example/upload",
                "not-a-digest",
                1,
            )
            .is_err()
        );
        assert!(
            create_nip98_authorization(&identity, "P UT", "https://files.example/upload", None, 1,)
                .is_err()
        );
        assert!(
            create_nip98_authorization(
                &identity,
                "PUT",
                "https://files.example/upload",
                Some(&vec![0; MAX_HTTP_AUTHORIZATION_PAYLOAD_BYTES + 1]),
                1,
            )
            .is_err()
        );
        assert!(
            create_nip98_authorization(
                &identity,
                "PUT",
                &format!(
                    "https://files.example/{}",
                    "x".repeat(MAX_HTTP_AUTHORIZATION_URL_BYTES)
                ),
                None,
                1,
            )
            .is_err()
        );
        Ok(())
    }
}