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 /<sha256>) 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
- [x] Create directory structure (`blobs/`, `db/`, `logs/`)
- [x] SQLite schema with `blobs` table (sha256, size, type, uploaded_at, uploader_pubkey, filename)
- [x] Database initialization scripts and proper indexes

### GET /<sha256> Endpoint
- [x] nginx static file serving with extension support (.txt, .jpg, .png, etc.)
- [x] Extension fallback via `try_files` directive
- [x] Proper MIME type detection and headers
- [x] Cache headers (Cache-Control, immutable)
- [x] 404 handling for missing blobs

### HEAD /<sha256> Endpoint  
- [x] FastCGI metadata handler
- [x] Database metadata queries
- [x] Proper HTTP headers (Content-Type, Content-Length)
- [x] SHA-256 extraction from URL paths
- [x] 404 responses for missing blobs

### Testing Status
- [x] File serving works with all supported extensions
- [x] HEAD requests return correct metadata
- [x] 404 responses for missing files
- [ ] Performance testing with large files

---

## BUD-02: File Upload & Authentication ✅ **COMPLETE**

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

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

### GET /list/<pubkey> Endpoint
- [x] Extract pubkey from URL path
- [x] Database queries for user's blobs
- [x] Optional authorization with kind 24242 event validation
- [x] Support for `since`/`until` query parameters
- [x] JSON array responses with blob descriptors

### DELETE /<sha256> Endpoint
- [x] SHA-256 extraction from URL
- [x] Required authorization with kind 24242 validation
- [x] Ownership verification (uploader_pubkey matching)
- [x] File and database cleanup
- [x] Proper error handling for missing files

### Testing Status
- [x] Upload with valid nostr authentication (HTTP 200)
- [x] Upload without authentication (proper error responses)
- [x] Hash mismatch validation (409 Conflict)
- [x] List endpoint returns proper JSON
- [x] Delete endpoint with ownership checks
- [x] 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
- [x] CURL library integration and HTTP client functions
- [x] `write_callback()` - Download response data with dynamic buffering
- [x] `header_callback()` - Extract Content-Type headers
- [x] `download_blob_from_url()` - Complete HTTP download with security controls
- [x] Memory management and error handling

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

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

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

---

## BUD-05: Media Optimization ⚪ **PARTIAL**

### Current Status  
- [x] nginx endpoint configured (`HEAD/PUT /media`)
- [x] 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
- [x] `HEAD /upload` endpoint implementation
- [x] Client header parsing (X-SHA-256, X-Content-Length, X-Content-Type)
- [x] Pre-flight validation without file transfer:
  - [x] SHA-256 format validation
  - [x] File size limit checking (100MB default)
  - [ ] MIME type restrictions (policy 415 not enforced yet)
  - [x] Authentication validation (optional via rules system)
  - [x] Duplicate detection (policy configurable)
  - [x] Banned hash checking (via rules engine)
- [x] Proper HTTP status codes (200, 400, 401, 409, 411, 413; 415 reserved for future MIME policy)
- [x] 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
- [x] Configuration system with SQLite server_config table
- [x] `nip94_enabled` configuration key (default: true)
- [x] `cdn_origin` configuration key (default: "http://localhost:9001")
- [x] Centralized MIME type to extension mapping [`mime_to_extension()`](src/main.c:2024)
- [x] Canonical blob URL generation [`nip94_build_blob_url()`](src/main.c:2055)
- [x] NIP-94 metadata field emission [`nip94_emit_field()`](src/main.c:2201)

### Image Dimension Detection
- [x] PNG dimension parsing from IHDR chunk [`parse_png_dimensions()`](src/main.c:2065)
- [x] JPEG dimension parsing from SOF0/SOF2 markers [`parse_jpeg_dimensions()`](src/main.c:2089)
- [x] WebP dimension parsing for VP8/VP8L/VP8X formats [`parse_webp_dimensions()`](src/main.c:2141)
- [x] Universal dimension dispatcher [`nip94_get_dimensions()`](src/main.c:2184)

### Integration Points
- [x] PUT /upload endpoint enhanced with NIP-94 metadata
- [x] PUT /mirror endpoint enhanced with NIP-94 metadata
- [x] Configuration-driven origin override for CDN support
- [x] Conditional metadata emission based on `nip94_enabled` setting
- [x] Proper JSON comma handling for optional nip94 field

### NIP-94 Tags Implemented
- [x] `url` tag - Canonical blob URL with proper origin and extension
- [x] `m` tag - MIME type (Content-Type)
- [x] `x` tag - SHA-256 hash (lowercase hex)
- [x] `size` tag - File size in bytes
- [x] `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
- [x] NIP-94 minimal tags (url, m, x, size) present in responses
- [x] Image dimension detection working for PNG 1x1 test case
- [x] Configuration-based enable/disable functionality
- [x] CDN origin override affecting both descriptor and nip94 URLs
- [x] Mirror endpoint NIP-94 integration (network-dependent)

---

## BUD-09: Content Reporting ✅ **COMPLETE**

### NIP-56 Report Event System
- [x] Full NIP-56 kind 1984 report event implementation
- [x] Report event structure validation (kind, required fields, x tags)
- [x] SHA-256 blob hash extraction from x tags [`extract_blob_hashes_from_report()`](src/main.c:2408)
- [x] Report type validation (nudity, malware, profanity, illegal, spam, impersonation, other)
- [x] Nostr cryptographic signature verification
- [x] Event timestamp and expiration validation

### PUT /report Endpoint
- [x] nginx endpoint configuration (`PUT /report`)
- [x] FastCGI routing and request handling [`handle_report_request()`](src/main.c:2516)
- [x] JSON request body parsing and validation
- [x] Content-Type enforcement (application/json required)
- [x] Request size limits (1 byte to 10KB)
- [x] HTTP method validation (PUT only, 405 for others)

### Report Validation Features
- [x] Event structure validation [`validate_report_event_structure()`](src/main.c:2355)
- [x] NIP-56 compliance checking (kind 1984, x tags required)
- [x] SHA-256 hash format validation (64-char hex)
- [x] Report type extensibility (accepts unknown types per NIP-56)
- [x] Multiple blob reporting (multiple x tags supported)
- [x] Optional tag support (e, p, server tags)

### Report Storage System
- [x] Optional report storage in database [`store_blob_report()`](src/main.c:2485)
- [x] Reporter pubkey extraction and storage
- [x] Report type and content preservation
- [x] Timestamp tracking for moderation review
- [x] Configurable storage policy (server MAY store reports)

### Error Handling & Security
- [x] 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
- [x] HTTP status code compliance (200, 400, 405, 415)
- [x] Detailed error messages with troubleshooting information

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

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

### Integration Points
- [x] Full integration with existing nostr authentication system
- [x] Database integration for optional report storage
- [x] nginx FastCGI routing configuration
- [x] Error response standardization with existing endpoints