ginxsom 🌸

A high-performance Blossom server implementation in C, designed for optimal integration with nginx for blazing-fast file serving.

Overview

Ginxsom is a Blossom protocol server implemented as a FastCGI application that integrates seamlessly with nginx. Nginx handles static file serving directly while ginxsom processes authenticated operations (uploads, deletes, management) via FastCGI. This architecture provides optimal performance with nginx's excellent static file serving and C's efficiency for cryptographic operations.

Why Ginxsom?

• Performance: C application with nginx static serving = maximum throughput
• Simplicity: Clean separation between static serving (nginx) and dynamic operations (C app)
• Scalability: nginx handles the heavy file serving load, C app handles auth and metadata
• Standards Compliant: Full Blossom protocol implementation with nostr authentication

Architecture

┌─────────────┐    ┌──────────────┐    ┌─────────────────┐
│   Client    │    │    nginx     │    │ ginxsom FastCGI │
│             │───▶│              │───▶│                 │
│             │    │              │    │                 │
└─────────────┘    └──────────────┘    └─────────────────┘
                          │                      │
                          ▼                      ▼
                   ┌─────────────┐    ┌─────────────────┐
                   │    Blobs    │    │   SQLite DB     │
                   │ (flat files)│    │  (metadata)     │
                   └─────────────┘    └─────────────────┘

Request Flow

1. File Retrieval (GET /<sha256>): nginx serves directly from disk
2. File Upload (PUT /upload): nginx calls ginxsom via FastCGI for authentication + storage
3. File Management (DELETE, LIST): nginx calls ginxsom via FastCGI
4. Metadata Operations: ginxsom manages SQLite database

Blossom Protocol Support

ginxsom implements the following Blossom Upgrade Documents (BUDs):

• BUD-01: Server requirements and blob retrieval
• BUD-02: Blob upload and management
• BUD-04: Blob Mirroring
• BUD-05: Media Optimization (Partial)
• BUD-06: Upload Requirements
• BUD-07: Payment Integration (Not implemented)
• BUD-08: NIP-94 File Metadata Tags
• BUD-09: Content Reporting

Supported Endpoints

Endpoint	Method	Description	Handler	Status
/<sha256>	GET	Retrieve blob	nginx → disk	✅ Implemented
/<sha256>	HEAD	Check blob exists	nginx → FastCGI ginxsom	✅ Implemented
/upload	PUT	Upload new blob	nginx → FastCGI ginxsom	✅ Implemented
/upload	HEAD	Check upload requirements	nginx → FastCGI ginxsom	✅ Implemented
/list/<pubkey>	GET	List user's blobs	nginx → FastCGI ginxsom	✅ Implemented
/<sha256>	DELETE	Delete blob	nginx → FastCGI ginxsom	✅ Implemented
/mirror	PUT	Mirror blob from URL	nginx → FastCGI ginxsom	✅ Implemented
/report	PUT	Report blob content	nginx → FastCGI ginxsom	✅ Implemented

Installation

Prerequisites

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install build-essential libssl-dev libsqlite3-dev libfcgi-dev pkg-config

# RHEL/CentOS/Fedora  
sudo dnf install gcc make openssl-devel sqlite-devel fcgi-devel pkgconfig

# macOS
brew install openssl sqlite fcgi pkg-config

Building ginxsom

git clone https://github.com/yourusername/ginxsom.git
cd ginxsom
make

Installation

sudo make install
# Installs to /usr/local/bin/ginxsom

Configuration

ginxsom Configuration

Create /etc/ginxsom/config.conf:

[server]
socket_path = /run/ginxsom.sock
max_file_size = 104857600  # 100MB
storage_path = /var/lib/ginxsom/blobs
database_path = /var/lib/ginxsom/blobs.db

[auth]
require_auth_upload = true
require_auth_get = false
require_auth_list = false

[limits]
max_blobs_per_user = 1000
rate_limit_uploads = 10  # per minute

nginx Configuration

Production Configuration

Add to your nginx configuration:

server {
    listen 80;
    server_name your-blossom-server.com;
    
    # CORS headers for all responses
    add_header Access-Control-Allow-Origin *;
    add_header Access-Control-Allow-Methods "GET, HEAD, PUT, DELETE, OPTIONS";
    add_header Access-Control-Allow-Headers "Authorization, Content-Type, Content-Length, X-SHA-256, X-Content-Type, X-Content-Length";
    add_header Access-Control-Max-Age 86400;
    
    # Handle preflight OPTIONS requests
    if ($request_method = 'OPTIONS') {
        return 204;
    }
    
    # Static blob serving - nginx handles directly
    location ~ ^/([a-f0-9]{64})(\.[a-zA-Z0-9]+)?$ {
        root /var/lib/ginxsom/blobs;
        try_files /$1$2 =404;
        add_header Accept-Ranges bytes;
        
        # Set content type based on file extension if not detected
        location ~* \.(pdf)$ { add_header Content-Type application/pdf; }
        location ~* \.(jpg|jpeg)$ { add_header Content-Type image/jpeg; }
        location ~* \.(png)$ { add_header Content-Type image/png; }
        location ~* \.(mp4)$ { add_header Content-Type video/mp4; }
    }
    
    # All other requests go to ginxsom FastCGI
    location / {
        include fastcgi_params;
        fastcgi_pass unix:/run/ginxsom.sock;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        
        # Handle large uploads
        client_max_body_size 100M;
        fastcgi_request_buffering off;
    }
}

Local Development Configuration

For local development, use the provided config/local-nginx.conf:

# Local development server (runs on port 9001)
server {
    listen 9001;
    server_name localhost;
    root blobs;  # Relative to project directory
    
    # FastCGI backend
    upstream fastcgi_backend {
        server unix:/tmp/ginxsom-fcgi.sock;
    }
    
    # DELETE endpoint - requires authentication
    location ~ "^/([a-f0-9]{64}).*$" {
        if ($request_method != DELETE) {
            return 404;
        }
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root/ginxsom.fcgi;
        fastcgi_pass fastcgi_backend;
    }
    
    # Static blob serving with extension fallback
    location ~ "^/([a-f0-9]{64})(\.[a-zA-Z0-9]+)?$" {
        limit_except HEAD GET { deny all; }
        
        # HEAD requests go to FastCGI
        if ($request_method = HEAD) {
            rewrite ^/(.*)$ /fcgi-head/$1 last;
        }
        
        # GET requests served directly with extension fallback
        try_files /$1.jpg /$1.jpeg /$1.png /$1.webp /$1.gif /$1.pdf /$1.mp4 /$1.mp3 /$1.txt /$1.md =404;
    }
    
    # Upload endpoint
    location /upload {
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root/ginxsom.fcgi;
        fastcgi_pass fastcgi_backend;
        if ($request_method !~ ^(PUT)$ ) { return 405; }
    }
    
    # List blobs endpoint
    location ~ "^/list/([a-f0-9]{64}).*$" {
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root/ginxsom.fcgi;
        fastcgi_pass fastcgi_backend;
        if ($request_method !~ ^(GET)$ ) { return 405; }
    }
}

Start local development with:

# Start FastCGI daemon
./start-fcgi.sh

# Start nginx (uses local config)
./restart-nginx.sh

Usage

Starting the Server

# Start ginxsom FastCGI daemon
sudo spawn-fcgi -s /run/ginxsom.sock -f /usr/local/bin/ginxsom -u www-data -g www-data

# Or with systemd
sudo systemctl enable ginxsom
sudo systemctl start ginxsom

Testing

# Check server is running
curl -I http://localhost/upload

# Upload a file (requires nostr authorization)
curl -X PUT http://localhost/upload \
  -H "Authorization: Nostr eyJ..." \
  -H "Content-Type: application/pdf" \
  --data-binary @document.pdf

# Retrieve a file
curl http://localhost/b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf

API Documentation

Authentication

All write operations require nostr event authentication via the Authorization header:

Authorization: Nostr <base64-encoded-nostr-event>

The nostr event must be kind 24242 with appropriate tags:

• t tag: upload, delete, list, or get
• x tag: SHA-256 hash for blob-specific operations
• expiration tag: Unix timestamp when event expires

Blob Descriptors

Successful uploads return blob descriptors with optional NIP-94 metadata:

{
  "url": "https://cdn.example.com/b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf",
  "sha256": "b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553",
  "size": 184292,
  "type": "application/pdf",
  "uploaded": 1725105921,
  "nip94": [
    ["url", "https://cdn.example.com/b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf"],
    ["m", "application/pdf"],
    ["x", "b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553"],
    ["size", "184292"]
  ]
}

NIP-94 Tags:

• url: Canonical blob URL with proper CDN origin
• m: MIME type (Content-Type)
• x: SHA-256 hash (lowercase hex)
• size: File size in bytes
• dim: Image dimensions (when available, e.g., "1920x1080")

The nip94 field is included by default but can be disabled via server configuration.

Content Reporting (BUD-09)

ginxsom implements BUD-09 Content Reporting using NIP-56 report events for moderating inappropriate content. Users can submit cryptographically signed reports about blobs containing objectionable material.

Report Event Structure

Reports use NIP-56 kind 1984 events with the following structure:

{
  "kind": 1984,
  "content": "This content violates community guidelines",
  "tags": [
    ["x", "b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553", "nudity"],
    ["x", "a8472f6d93e42c1e5b4e6f9a1b3c8d4e6f9a1b3c5d7e8f0a1b2c3d4e5f6a7b8", "spam"]
  ],
  "created_at": 1725105921,
  "pubkey": "reporter_public_key",
  "id": "event_id",
  "sig": "cryptographic_signature"
}

Supported Report Types

• nudity: Adult or sexually explicit content
• malware: Malicious software or files
• profanity: Offensive language or content
• illegal: Content that violates laws
• spam: Unwanted promotional content
• impersonation: Content impersonating others
• other: Any other inappropriate content
• extensible: Unknown types are accepted per NIP-56

Report Submission

Submit reports to the /report endpoint:

# Generate report with nak tool
REPORT=$(nak event -k 1984 -c "Report description" -t "x=deadbeef...;nudity")

# Submit report
curl -X PUT http://localhost:9001/report \
  -H "Content-Type: application/json" \
  -d "$REPORT"

Response Format

Successful reports return confirmation:

{
  "message": "Report received",
  "reported_blobs": 2,
  "reporter": "reporter_pubkey_bytes"
}

Error responses include specific error codes:

• invalid_json: Malformed JSON
• invalid_report_event: Invalid NIP-56 structure
• no_blob_hashes: Missing valid SHA-256 hashes
• unsupported_media_type: Non-JSON Content-Type

File Storage

Current (Flat) Structure

/var/lib/ginxsom/blobs/
├── b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf
├── a8472f6d93e42c1e5b4e9f3a7b2c8d4e6f9a1b3c5d7e8f0a1b2c3d4e5f6a7b8.png
└── ...

Future (Optimized) Structure

/var/lib/ginxsom/blobs/
├── b1/
│   └── 67/
│       └── b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf
├── a8/
│   └── 47/
│       └── a8472f6d93e42c1e5b4e6f9a1b3c5d7e8f0a1b2c3d4e6f9a1b3c5d7e8f0a1b2c3d4e5f6a7b8.png

File and Extension Handling

ginxsom implements a sophisticated file and extension handling strategy that optimizes both performance and flexibility:

Database-Driven Architecture

The system uses the SQLite database as the single source of truth for blob existence and metadata:

-- Database schema (clean SHA-256 hashes, no extensions)
CREATE TABLE blobs (
    sha256 TEXT PRIMARY KEY,           -- Clean hash: b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553
    size INTEGER NOT NULL,
    type TEXT NOT NULL,
    uploaded_at INTEGER NOT NULL,
    uploader_pubkey TEXT,
    filename TEXT                      -- Original filename: document.pdf
);

Key Benefits:

• Database Lookup vs Filesystem: FastCGI queries the database instead of checking filesystem
• Single Source of Truth: Database definitively knows if a blob exists
• Extension Irrelevant: Database uses clean SHA-256 hashes without extensions
• Performance: Database queries are faster than filesystem stat() calls

URL and Extension Support

ginxsom supports flexible URL patterns for maximum client compatibility:

# Both forms work identically:
GET /b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553
GET /b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf

# HEAD requests work with or without extensions:
HEAD /b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553
HEAD /b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf

nginx File Storage Strategy

Files are stored on disk with extensions for nginx MIME type detection and optimal performance:

# Blossom-compliant nginx configuration
location ~ ^/([a-f0-9]{64}).*$ {
    root /var/lib/ginxsom/blobs;
    try_files /$1* =404;
}

How it works:

1. Hash-only lookup: nginx extracts the 64-character SHA-256 hash from the URL, ignoring any extension
2. Wildcard matching: try_files /$1* finds any file starting with that hash
3. Blossom compliance: Serves correct file regardless of URL extension

Examples:

Client requests: b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf

• nginx extracts hash: b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553
• nginx looks for: b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553*
• nginx finds: b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf
• nginx serves the PDF with correct Content-Type: application/pdf

Client requests: b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.mp3

• nginx extracts same hash: b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553
• nginx looks for: b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553*
• nginx finds: b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf
• nginx serves the PDF (not 404) with correct Content-Type: application/pdf

Key Benefits:

• Blossom Protocol Compliance: Accepts any extension, returns correct MIME type
• Performance: nginx serves files directly without FastCGI involvement
• Flexibility: URLs work with correct extension, wrong extension, or no extension
• MIME Detection: nginx determines Content-Type from actual file extension on disk

This approach ensures that files are always found by their SHA-256 hash regardless of what extension (if any) is used in the request URL, while maintaining nginx's excellent static file serving performance.

HEAD Request Handling

HEAD requests are processed differently to ensure accuracy:

1. nginx receives HEAD request: /b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf
2. nginx forwards to FastCGI: All HEAD requests go to ginxsom for metadata
3. ginxsom extracts clean hash: Strips .pdf → b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553
4. ginxsom queries database: SELECT size, type FROM blobs WHERE sha256 = ?
5. ginxsom returns headers: Content-Length, Content-Type, etc.

Why This Approach?

Performance:

• GET requests: nginx serves directly from disk (no database hit)
• HEAD requests: Single database query (no filesystem checking)
• Extension mismatches: Eliminated by database-driven approach

Reliability:

• Database is authoritative source of blob existence
• No race conditions between filesystem and metadata
• Consistent behavior regardless of URL format

Flexibility:

• Clients can use URLs with or without extensions
• Browser-friendly URLs with proper file extensions
• API-friendly clean hash URLs

Scalability:

• nginx handles the heavy lifting (file serving)
• FastCGI only processes metadata operations
• Database queries scale better than filesystem operations

Development

Project Structure

ginxsom/
├── src/
│   ├── main.c              # Main server loop
│   ├── config.c            # Configuration parsing
│   ├── server.c            # HTTP server logic
│   ├── auth.c              # Nostr authentication
│   ├── storage.c           # File storage operations
│   ├── database.c          # SQLite operations
│   └── utils.c             # Utility functions
├── include/
│   └── ginxsom.h           # Main header file
├── tests/
│   └── test_*.c            # Unit tests
├── docs/
│   └── api.md              # API documentation
├── Makefile
└── README.md

Building for Development

make debug    # Build with debug symbols
make test     # Run test suite
make clean    # Clean build artifacts

Dependencies

• libssl: For cryptographic operations (nostr event verification)
• libsqlite3: For metadata storage
• libfcgi: For FastCGI functionality

Performance Characteristics

• Static File Serving: nginx performance (typically >10k req/s)
• Upload Processing: Limited by disk I/O and crypto verification
• Memory Usage: Minimal - FastCGI processes are lightweight
• Concurrent Operations: nginx manages FastCGI process pool efficiently
• Process Management: nginx spawns/manages ginxsom FastCGI processes

Security Considerations

• All uploads require valid nostr event signatures
• SHA-256 verification prevents data corruption
• Rate limiting prevents abuse
• File size limits prevent disk exhaustion
• No script execution - blobs stored as static files

Monitoring

ginxsom provides metrics via /metrics endpoint:

# HELP ginxsom_uploads_total Total number of uploads processed
# TYPE ginxsom_uploads_total counter
ginxsom_uploads_total 1234

# HELP ginxsom_storage_bytes Total bytes stored
# TYPE ginxsom_storage_bytes gauge  
ginxsom_storage_bytes 1073741824

License

[License information here]

Contributing

[Contributing guidelines here]

---

Note: This project is under active development. Please report bugs and feature requests via GitHub issues.