ginxsom/IMPLEMENTATION.md

Ginxsom Blossom Server Implementation Status

This document tracks the implementation status of ginxsom, a high-performance FastCGI-based Blossom server designed to work with nginx.

Architecture Overview

• nginx: Handles static file serving (GET /) for maximum performance
• FastCGI Application: Handles authenticated operations, metadata queries, uploads
• SQLite Database: Stores blob metadata and server configuration
• File Storage: Flat directory structure in blobs/ directory

---

BUD-01: Blob Retrieval ✅ COMPLETE

Infrastructure & Database

• Create directory structure (blobs/, db/, logs/)
• SQLite schema with blobs table (sha256, size, type, uploaded_at, uploader_pubkey, filename)
• Database initialization scripts and proper indexes

GET / Endpoint

• nginx static file serving with extension support (.txt, .jpg, .png, etc.)
• Extension fallback via try_files directive
• Proper MIME type detection and headers
• Cache headers (Cache-Control, immutable)
• 404 handling for missing blobs

HEAD / Endpoint

• FastCGI metadata handler
• Database metadata queries
• Proper HTTP headers (Content-Type, Content-Length)
• SHA-256 extraction from URL paths
• 404 responses for missing blobs

Testing Status

• File serving works with all supported extensions
• HEAD requests return correct metadata
• 404 responses for missing files
• Performance testing with large files

---

BUD-02: File Upload & Authentication ✅ COMPLETE

Nostr Authentication System

• nostr_core_lib integration and compilation
• secp256k1 context initialization (CRITICAL BUG FIXED)
• Authentication functions:
  • parse_authorization_header() - Extract JSON from "Nostr base64(event)"
  • validate_blossom_event() - Validate kind 24242 events
  • authenticate_request() - Main authentication orchestrator
• Enhanced error handling with specific error types (event_expired, invalid_signature, etc.)
• API refactoring - upgraded from low-level crypto to nostr_crypto_init() API

PUT /upload Endpoint

• Authorization header parsing and validation
• File upload streaming to temporary location
• SHA-256 hash calculation during upload
• Hash validation against authorization
• File permissions (644) for nginx serving
• Database metadata storage (uploader_pubkey, filename)
• Blob descriptor JSON response

GET /list/ Endpoint

• Extract pubkey from URL path
• Database queries for user's blobs
• Optional authorization with kind 24242 event validation
• Support for since/until query parameters
• JSON array responses with blob descriptors

DELETE / Endpoint

• SHA-256 extraction from URL
• Required authorization with kind 24242 validation
• Ownership verification (uploader_pubkey matching)
• File and database cleanup
• Proper error handling for missing files

Testing Status

• Upload with valid nostr authentication (HTTP 200)
• Upload without authentication (proper error responses)
• Hash mismatch validation (409 Conflict)
• List endpoint returns proper JSON
• Delete endpoint with ownership checks
• File retrieval after upload working
• File size limit testing

---

BUD-03: Server List (User Server Lists) ⚪ FOR CLIENTS, NOT SERVERS

BUD-04: Blob Mirroring ✅ COMPLETE

HTTP Client Implementation

• CURL library integration and HTTP client functions
• write_callback() - Download response data with dynamic buffering
• header_callback() - Extract Content-Type headers
• download_blob_from_url() - Complete HTTP download with security controls
• Memory management and error handling

PUT /mirror Endpoint

• nginx endpoint configured (PUT /mirror)
• FastCGI routing and request handling
• JSON request body parsing (extract url field)
• URL validation and security checks (HTTPS-only, SSRF protection)
• Remote blob downloading with CURL
• SHA-256 hash calculation and verification
• Content-Type detection (headers, URL extension, file signature)
• File storage with proper extensions (.png, .jpg, etc.)
• Database metadata storage
• Blob descriptor JSON response

Security Features

• HTTPS-only URL validation (no HTTP allowed)
• SSRF protection (blocks localhost, private IPs: 127.x, 192.168.x, 10.x, 172.16-31.x)
• File size limits (100MB maximum)
• Request timeouts (30s total, 10s connect)
• SSL certificate verification
• Authorization hash verification (when provided)

Testing Status

• Mirror request with valid HTTPS URL (HTTP 200)
• Hash verification against downloaded content
• Content-Type detection from PNG file
• File accessibility after mirroring
• HEAD request metadata retrieval
• Error handling for invalid URLs
• Security validation (private IP blocking)

---

BUD-05: Media Optimization ⚪ PARTIAL

Current Status

• nginx endpoint configured (HEAD/PUT /media)
• FastCGI routing established
• Media processing libraries integration
• Optimization algorithms implementation
• Multi-format media handling
• Optimization pipeline testing

---

BUD-06: Upload Requirements ✅ COMPLETE

HEAD /upload Pre-flight Validation

• HEAD /upload endpoint implementation
• Client header parsing (X-SHA-256, X-Content-Length, X-Content-Type)
• Pre-flight validation without file transfer:
  • SHA-256 format validation
  • File size limit checking (100MB default)
  • MIME type restrictions (policy 415 not enforced yet)
  • Authentication validation (optional via rules system)
  • Duplicate detection (policy configurable)
  • Banned hash checking (via rules engine)
• Proper HTTP status codes (200, 400, 401, 409, 411, 413; 415 reserved for future MIME policy)
• X-Reason headers for error messages

Upload Policy Configuration

• Server configuration system
• Maximum file size limits (currently hard limit in code; move to config)
• Allowed MIME type restrictions
• Rate limiting implementation
• DOS protection benefits

---

BUD-07: Payment Integration ⚪ NOT IMPLEMENTED

Optional feature - not currently planned

• 402 Payment Required responses
• Lightning payment support
• Cashu payment integration
• Payment verification flows

---

BUD-08: NIP-94 Metadata ⚪ NOT IMPLEMENTED

Optional feature - not currently planned

• NIP-94 tag generation
• Extended blob descriptor responses
• Magnet link generation
• Metadata compatibility testing

---

BUD-09: Content Reporting ⚪ PARTIAL

Current Status

• nginx endpoint configured (PUT /report)
• FastCGI routing established
• NIP-56 report event handling
• Moderation interface
• Content filtering implementation
• Reporting workflow testing