AGENTS.md

This file provides guidance to agents when working with code in this repository.

Critical Architecture Rules (Non-Obvious Only)

Hybrid Request Handling: GET requests served directly by nginx from disk, HEAD/PUT/DELETE go through FastCGI
Database vs Filesystem: Database is authoritative for blob existence - filesystem is just storage medium
Two-Phase Authentication: Nostr event validation PLUS Blossom protocol validation (kind 24242 + method tags)
Config Architecture: File-based signed events override database config - enables cryptographic config verification
Memory-Only Secrets: Server private keys never persisted to database - stored in process memory only
Extension Decoupling: File storage uses MIME-based extensions, URL serving accepts any extension via nginx wildcards
FastCGI Socket Communication: nginx communicates with C app via Unix socket, not TCP - affects deployment
Authentication Rules Engine: Optional rules system with priority-based evaluation and caching layer
Blob Descriptor Format: Returns NIP-94 compliant metadata with canonical URLs based on configured origin
Admin API Isolation: Admin endpoints use separate authentication from blob operations - different event structures