Spike native shells and define local-first integrations

crates/lumbridge-buzz/src/lib.rs

@@ -0,0 +1,209 @@
+//! Credential-free Buzz protocol preparation for Lumbridge.
+//!
+//! This crate validates the user's pane-sharing decision and delegates event
+//! construction to the upstream Buzz SDK. Signing, uploading, and publishing
+//! belong to platform adapters that can resolve an OS credential-store handle.
+
+use std::fmt;
+
+use nostr::EventBuilder;
+use uuid::Uuid;
+
+/// A locally configured Buzz identity without private key material.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct BuzzAccount {
+    /// Lumbridge-local stable identifier.
+    pub id: String,
+    /// Human-readable account label.
+    pub label: String,
+    /// Buzz relay/server URL.
+    pub relay_url: String,
+    /// Public Nostr identity in hexadecimal form.
+    pub public_key: String,
+    /// Opaque reference resolved by Keychain or Secret Service.
+    pub secret_store_handle: String,
+}
+
+/// Metadata produced after an approved screenshot has been uploaded.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct UploadedPaneImage {
+    /// Publicly retrievable attachment URL returned by Buzz storage.
+    pub url: String,
+    /// MIME type, normally `image/png` or `image/webp`.
+    pub media_type: String,
+    /// Lower-case SHA-256 digest of the uploaded bytes.
+    pub sha256: String,
+    /// Exact byte length of the upload.
+    pub size_bytes: u64,
+    /// Optional pixel dimensions.
+    pub dimensions: Option<(u32, u32)>,
+}
+
+impl UploadedPaneImage {
+    fn imeta(&self) -> Vec<String> {
+        let mut tag = vec![
+            "imeta".to_owned(),
+            format!("url {}", self.url),
+            format!("m {}", self.media_type),
+            format!("x {}", self.sha256),
+            format!("size {}", self.size_bytes),
+        ];
+        if let Some((width, height)) = self.dimensions {
+            tag.push(format!("dim {width}x{height}"));
+        }
+        tag
+    }
+}
+
+/// The explicit human approval associated with a pane share.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ShareApproval {
+    /// Destination selected in the preview UI.
+    pub channel_id: Uuid,
+    /// Final caption visible in the preview UI.
+    pub caption: String,
+    /// Whether redaction has run for this exact captured image.
+    pub redaction_reviewed: bool,
+    /// Whether the user confirmed the exact image, caption, and destination.
+    pub user_confirmed: bool,
+}
+
+/// Errors that prevent preparation of a pane share.
+#[derive(Debug)]
+pub enum ShareError {
+    /// Redaction review is mandatory before sharing a pane.
+    RedactionNotReviewed,
+    /// A user must confirm the final preview and destination.
+    NotConfirmed,
+    /// The uploaded attachment metadata is malformed.
+    InvalidAttachment(&'static str),
+    /// Buzz rejected the message fields.
+    Buzz(buzz_sdk::SdkError),
+}
+
+impl fmt::Display for ShareError {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::RedactionNotReviewed => formatter.write_str("pane redaction was not reviewed"),
+            Self::NotConfirmed => formatter.write_str("pane share was not confirmed"),
+            Self::InvalidAttachment(reason) => {
+                write!(formatter, "invalid pane attachment: {reason}")
+            }
+            Self::Buzz(error) => write!(formatter, "Buzz rejected pane share: {error}"),
+        }
+    }
+}
+
+impl std::error::Error for ShareError {}
+
+impl From<buzz_sdk::SdkError> for ShareError {
+    fn from(error: buzz_sdk::SdkError) -> Self {
+        Self::Buzz(error)
+    }
+}
+
+/// Build an unsigned Buzz message only after the share safety gate passes.
+///
+/// The returned builder must be signed by an identity obtained from the OS
+/// credential store and then published by the Buzz transport adapter.
+///
+/// # Errors
+///
+/// Returns an error when review/confirmation is missing, attachment metadata is
+/// unsafe, or the Buzz SDK rejects the event.
+pub fn prepare_pane_share(
+    approval: &ShareApproval,
+    image: &UploadedPaneImage,
+) -> Result<EventBuilder, ShareError> {
+    if !approval.redaction_reviewed {
+        return Err(ShareError::RedactionNotReviewed);
+    }
+    if !approval.user_confirmed {
+        return Err(ShareError::NotConfirmed);
+    }
+    if !matches!(image.media_type.as_str(), "image/png" | "image/webp") {
+        return Err(ShareError::InvalidAttachment("unsupported image type"));
+    }
+    if image.sha256.len() != 64 || !image.sha256.bytes().all(|byte| byte.is_ascii_hexdigit()) {
+        return Err(ShareError::InvalidAttachment(
+            "SHA-256 must be 64 hexadecimal characters",
+        ));
+    }
+    if image.size_bytes == 0 {
+        return Err(ShareError::InvalidAttachment("image is empty"));
+    }
+
+    let content = if approval.caption.trim().is_empty() {
+        format!("![Lumbridge pane]({})", image.url)
+    } else {
+        format!(
+            "{}\n\n![Lumbridge pane]({})",
+            approval.caption.trim(),
+            image.url
+        )
+    };
+    buzz_sdk::build_message(
+        approval.channel_id,
+        &content,
+        None,
+        &[],
+        false,
+        &[image.imeta()],
+    )
+    .map_err(Into::into)
+}
+
+#[cfg(test)]
+mod tests {
+    use nostr::{Keys, Kind};
+
+    use super::{ShareApproval, ShareError, UploadedPaneImage, prepare_pane_share};
+
+    fn image() -> UploadedPaneImage {
+        UploadedPaneImage {
+            url: "https://buzz.example/upload/pane.png".into(),
+            media_type: "image/png".into(),
+            sha256: "a".repeat(64),
+            size_bytes: 42_000,
+            dimensions: Some((1_720, 1_400)),
+        }
+    }
+
+    fn approval() -> ShareApproval {
+        ShareApproval {
+            channel_id: uuid::uuid!("5088492f-f83b-41e1-b2cd-95cc741b4521"),
+            caption: "Lumbridge GPUI spike".into(),
+            redaction_reviewed: true,
+            user_confirmed: true,
+        }
+    }
+
+    #[test]
+    fn requires_review_and_confirmation() {
+        let mut decision = approval();
+        decision.redaction_reviewed = false;
+        assert!(matches!(
+            prepare_pane_share(&decision, &image()),
+            Err(ShareError::RedactionNotReviewed)
+        ));
+
+        decision.redaction_reviewed = true;
+        decision.user_confirmed = false;
+        assert!(matches!(
+            prepare_pane_share(&decision, &image()),
+            Err(ShareError::NotConfirmed)
+        ));
+    }
+
+    #[test]
+    fn builds_a_signable_buzz_stream_message() {
+        let event = prepare_pane_share(&approval(), &image())
+            .expect("approved share should build")
+            .sign_with_keys(&Keys::generate())
+            .expect("test identity should sign");
+
+        assert_eq!(event.kind, Kind::Custom(9));
+        assert!(event.content.contains("Lumbridge GPUI spike"));
+        assert!(event.content.contains("pane.png"));
+    }
+}