blossom-rs

Full-featured Blossom blob storage library for Rust.

Content-addressed blob storage over HTTP with BIP-340 Schnorr authorization via Nostr kind:24242/NIP-98 events.

Workspace

Features

• Decentralized git hosting — NIP-34 Nostr relay + GRASP git HTTP server (enabled by default)
• Blob storage — content-addressed BUD-01 with SHA256 integrity
• BUD-19 file locking — Git LFS lock/unlock/verify with ownership enforcement
• BUD-20 compression — zstd + xdelta3 delta encoding for LFS blobs
• BUD-03 server list — auto-publish kind:10063 events after upload
• NIP-94 file metadata — auto-publish kind:1063 events after upload
• Dual auth — kind:24242 (Blossom) and kind:27235 (NIP-98) Nostr event authentication
• Pluggable storage — memory (testing), filesystem, S3-compatible backends
• Database layer — SQLite/Postgres via SQLx, versioned migrations
• Relay admin — runtime whitelist/blacklist/admin pubkeys, kind filtering, persisted to DB
• Access control — whitelist with hot-reload, role-based, custom policies via trait
• Admin API — user management, quota CRUD, blob management, LFS stats, relay policy
• Rate limiting — token-bucket per-key throttling
• iroh P2P transport — QUIC transport for uploads with HTTP download fallback
• PKARR DHT discovery — publish _blossom, _iroh, _nostr TXT records
• Observability — OTEL-compatible structured tracing with OTLP export
• NIP-96 — Nostr file storage protocol endpoints
• Build integrity — signed release manifests, source Merkle tree attestation
• TLS, CORS, graceful shutdown — production-ready defaults
• Trait-based — BlossomSigner, BlobBackend, BlobDatabase, LockDatabase, AccessControl, MediaProcessor, WebhookNotifier

Quick Start

use blossom_rs::{BlobServer, FilesystemBackend, Signer};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let server = BlobServer::new(
        FilesystemBackend::new("./blobs")?,
        "http://localhost:3000",
    );

    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await?;
    axum::serve(listener, server.router()).await?;
    Ok(())
}

Full-Featured Server

use blossom_rs::{BlobServer, MemoryBackend, MemoryDatabase};
use blossom_rs::access::Whitelist;
use blossom_rs::ratelimit::{RateLimiter, RateLimitConfig};
use blossom_rs::webhooks::HttpNotifier;
use std::collections::HashSet;

let mut db = MemoryDatabase::new();
db.set_quota("pubkey_hex...", Some(50 * 1024 * 1024)).unwrap();

let server = BlobServer::builder(MemoryBackend::new(), "http://localhost:3000")
    .database(db)
    .access_control(Whitelist::new(HashSet::from(["pubkey_hex...".into()])))
    .require_auth()
    .max_upload_size(10 * 1024 * 1024)
    .body_limit(50 * 1024 * 1024)
    .rate_limiter(RateLimiter::new(RateLimitConfig { max_tokens: 60, refill_rate: 1.0 }))
    .webhook_notifier(HttpNotifier::new(vec!["https://hooks.example.com/blossom".into()]))
    .build();

Client

Keys are accepted as hex (64 chars) or nsec1 bech32 format.

use blossom_rs::{BlossomClient, Signer};

let signer = Signer::generate();
let client = BlossomClient::new(
    vec!["https://blossom.example.com".into()],
    signer,
);

let desc = client.upload(b"hello", "text/plain").await?;
let data = client.download(&desc.sha256).await?;

Feature Flags

Protocol Support

Architecture

All extension points are trait-based:

BlossomSigner   — BIP-340 signing (bring your own identity)
BlobBackend     — blob storage (Memory, Filesystem, S3)
BlobDatabase    — metadata persistence (Memory, SQLite, Postgres)
LockDatabase    — BUD-19 file locks (Memory, SQLite, Postgres)
AccessControl   — authorization (OpenAccess, Whitelist, custom)
WebhookNotifier — event notifications (Noop, HTTP POST, custom)
MediaProcessor  — image/video processing (Passthrough, ImageProcessor)
MediaLabeler    — content classification (Noop, BlockAll, custom)

Server Builder

BlobServer::builder(backend, "http://localhost:3000")
    .database(db)               // BlobDatabase impl
    .access_control(whitelist)  // AccessControl impl
    .require_auth()             // Enforce auth on uploads
    .max_upload_size(10_000_000) // BUD-06 size limit
    .allowed_types(vec!["image/png".into()]) // BUD-06 type filter
    .body_limit(50_000_000)     // HTTP body size limit
    .rate_limiter(limiter)      // Token-bucket rate limiting
    .webhook_notifier(notifier) // Lifecycle event webhooks
    .media_processor(processor) // BUD-05 image processing on PUT /media
    .lock_database(blossom_rs::locks::MemoryLockDatabase::new()) // BUD-19 file locking
    .build();

Observability

All key functions are instrumented with #[tracing::instrument] using OTEL semantic conventions:

Zero-cost by default — tracing is a no-op without a subscriber.

Opt-in OTLP export for Jaeger, Grafana Tempo, Seq, Honeycomb, etc.:

blossom-rs = { version = "0.1", features = ["otel"] }

let _guard = blossom_rs::otel::init_tracing("my-server", "info")?;

Testing

cargo test --workspace                          # 207 tests
cargo test --workspace --features db-sqlite     # Include SQLite backend tests
cargo llvm-cov --workspace --features db-sqlite # Coverage report

# Optional integration tests (require external services):
R2_ENDPOINT=... cargo test --features s3 --test s3_integration
RUN_POSTGRES_TESTS=1 cargo test --features db-postgres --test postgres_integration

CI/CD

• CI: On push/PR to master — cargo fmt --all --check, cargo build --workspace, cargo test --workspace, cargo clippy --workspace
• Publish: On v* tags — test, then publish blossom-rs → blossom-server + blossom-cli to crates.io
• Self-hosted runner for trusted pushes; GitHub-hosted for fork PRs

Acknowledgments

This library draws on patterns and design decisions from:

• route96 by v0l — Rust Blossom/NIP-96 server implementation. Reference for NIP-96 protocol, database schema patterns, media processing pipeline, EXIF validation, content labeling traits, whitelist access control, and file statistics. Licensed under MIT.

• hzrd149/blossom — The Blossom protocol specification (BUD-01 through BUD-06).

• The broader Nostr ecosystem for NIP-01, NIP-96, NIP-98, and BIP-340 standards.

License

MIT