# 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