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 ⚪ PARTIAL

Current Status

• nginx endpoint configured (PUT /mirror)
• FastCGI routing established
• URL downloading implementation
• Hash verification after download
• Authorization handling for mirroring
• Inter-server mirroring testing

---

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 ⚪ NOT IMPLEMENTED

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
  • MIME type restrictions
  • Authentication validation
  • Duplicate detection
  • Banned hash checking
• Proper HTTP status codes (200, 400, 401, 403, 411, 413, 415)
• X-Reason headers for error messages

Upload Policy Configuration

• Server configuration system
• Maximum file size limits
• 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