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 File Metadata Tags ✅ COMPLETE

NIP-94 Integration

• Configuration system with SQLite server_config table
• nip94_enabled configuration key (default: true)
• cdn_origin configuration key (default: "http://localhost:9001")
• Centralized MIME type to extension mapping mime_to_extension()
• Canonical blob URL generation nip94_build_blob_url()
• NIP-94 metadata field emission nip94_emit_field()

Image Dimension Detection

• PNG dimension parsing from IHDR chunk parse_png_dimensions()
• JPEG dimension parsing from SOF0/SOF2 markers parse_jpeg_dimensions()
• WebP dimension parsing for VP8/VP8L/VP8X formats parse_webp_dimensions()
• Universal dimension dispatcher nip94_get_dimensions()

Integration Points

• PUT /upload endpoint enhanced with NIP-94 metadata
• PUT /mirror endpoint enhanced with NIP-94 metadata
• Configuration-driven origin override for CDN support
• Conditional metadata emission based on nip94_enabled setting
• Proper JSON comma handling for optional nip94 field

NIP-94 Tags Implemented

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

Configuration Keys

• nip94_enabled (boolean): Enable/disable NIP-94 metadata emission (default: true)
• cdn_origin (string): Base URL for blob URLs (default: "http://localhost:9001")

Testing Status

• NIP-94 minimal tags (url, m, x, size) present in responses
• Image dimension detection working for PNG 1x1 test case
• Configuration-based enable/disable functionality
• CDN origin override affecting both descriptor and nip94 URLs
• Mirror endpoint NIP-94 integration (network-dependent)

---

BUD-09: Content Reporting ✅ COMPLETE

NIP-56 Report Event System

• Full NIP-56 kind 1984 report event implementation
• Report event structure validation (kind, required fields, x tags)
• SHA-256 blob hash extraction from x tags extract_blob_hashes_from_report()
• Report type validation (nudity, malware, profanity, illegal, spam, impersonation, other)
• Nostr cryptographic signature verification
• Event timestamp and expiration validation

PUT /report Endpoint

• nginx endpoint configuration (PUT /report)
• FastCGI routing and request handling handle_report_request()
• JSON request body parsing and validation
• Content-Type enforcement (application/json required)
• Request size limits (1 byte to 10KB)
• HTTP method validation (PUT only, 405 for others)

Report Validation Features

• Event structure validation validate_report_event_structure()
• NIP-56 compliance checking (kind 1984, x tags required)
• SHA-256 hash format validation (64-char hex)
• Report type extensibility (accepts unknown types per NIP-56)
• Multiple blob reporting (multiple x tags supported)
• Optional tag support (e, p, server tags)

Report Storage System

• Optional report storage in database store_blob_report()
• Reporter pubkey extraction and storage
• Report type and content preservation
• Timestamp tracking for moderation review
• Configurable storage policy (server MAY store reports)

Error Handling & Security

• Comprehensive error responses with specific error codes:
  • invalid_json - Malformed JSON requests
  • invalid_content_length - Size limit violations
  • invalid_report_event - NIP-56 structure violations
  • no_blob_hashes - Missing or invalid SHA-256 hashes
  • unsupported_media_type - Non-JSON Content-Type
• HTTP status code compliance (200, 400, 405, 415)
• Detailed error messages with troubleshooting information

NIP-56 Compliance Features

• Report types: nudity, malware, profanity, illegal, spam, impersonation, other
• Extensible report type system (unknown types accepted)
• Multiple blob reporting via multiple x tags
• Optional metadata tags (e, p, server)
• Content field support (reports may include descriptions)
• Cryptographic signature verification via nostr event validation

Testing Status

• Comprehensive test suite with 22 test cases tests/report_test_bud09.sh
• All NIP-56 report types tested (nudity, malware, profanity, illegal, spam, impersonation, other)
• Event validation testing (missing x tags, wrong kind, invalid JSON)
• Error handling testing (empty body, wrong Content-Type, unsupported methods)
• Multiple blob reporting functionality
• Optional tag support with comprehensive NIP-56 structure
• Unknown report type extensibility
• Edge cases (empty content, long content, invalid hashes)

Integration Points

• Full integration with existing nostr authentication system
• Database integration for optional report storage
• nginx FastCGI routing configuration
• Error response standardization with existing endpoints