tests

.roo/rules-architect/AGENTS.md

@@ -0,0 +1,16 @@
+# 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

.roo/rules-ask/AGENTS.md

@@ -0,0 +1,16 @@
+# AGENTS.md
+
+This file provides guidance to agents when working with code in this repository.
+
+## Critical Documentation Context (Non-Obvious Only)
+
+- **"FastCGI App"**: This is NOT a web server - it's a FastCGI application that nginx calls for dynamic operations
+- **Two Config Systems**: File-based config (XDG) is priority 1, database config is fallback - don't assume standard config locations
+- **Blob Storage Strategy**: Files stored WITH extensions but URLs accept any extension - counterintuitive to typical web serving
+- **Admin API Auth**: Uses Nostr cryptographic events (kind 24242) not standard bearer tokens or sessions
+- **Database Schema**: `blobs` table stores metadata, physical files in `blobs/` directory - database is authoritative
+- **Build Requirements**: Requires local SQLite build, nostr_core_lib submodule, and specific FastCGI libraries
+- **Testing Setup**: Tests require `nak` tool for Nostr event generation - not standard HTTP testing
+- **Development Ports**: Local development uses port 9001, production typically uses nginx proxy on standard ports
+- **Setup Wizard**: Interactive setup creates cryptographically signed config files - not typical config generation
+- **Extension Handling**: nginx config uses wildcards to serve files regardless of URL extension - Blossom protocol compliance

.roo/rules-code/AGENTS.md

@@ -0,0 +1,18 @@
+# AGENTS.md
+
+This file provides guidance to agents when working with code in this repository.
+
+## Critical Coding Rules (Non-Obvious Only)
+
+- **nostr_core_lib Integration**: Must use `nostr_sha256()` and `nostr_bytes_to_hex()` from nostr_core, NOT standard crypto libs
+- **Database Connection Pattern**: Always use `sqlite3_open_v2()` with `SQLITE_OPEN_READONLY` or `SQLITE_OPEN_READWRITE` flags
+- **Memory Management**: File data buffers must be freed after use - common pattern is `malloc()` for upload data, `free()` on all paths
+- **Error Handling**: FastCGI responses must use `printf("Status: XXX\r\n")` format, NOT standard HTTP response format
+- **String Safety**: Always null-terminate strings from SQLite results - use `strncpy()` with size-1 and explicit null termination
+- **Hash Validation**: SHA-256 hashes must be exactly 64 hex chars - validate with custom `validate_sha256_format()` function
+- **MIME Type Mapping**: Use centralized `mime_to_extension()` function - never hardcode file extensions
+- **Authentication**: Nostr event parsing uses cJSON - always call `cJSON_Delete()` after use to prevent memory leaks
+- **Configuration Loading**: File config takes priority over database - check XDG paths first, fallback to database
+- **Blob Metadata**: Database is single source of truth - use `get_blob_metadata()`, not filesystem checks
+- **nostr_core_lib Build**: Uses `build.sh` script, NOT `make` - run `./build.sh` to compile the library
+- **Server Testing**: Use `./restart-all.sh` to properly restart and test ginxsom server, NOT direct binary execution

.roo/rules-debug/AGENTS.md

@@ -0,0 +1,16 @@
+# AGENTS.md
+
+This file provides guidance to agents when working with code in this repository.
+
+## Critical Debug Rules (Non-Obvious Only)
+
+- **FastCGI Socket Issues**: If socket `/tmp/ginxsom-fcgi.sock` exists but connection fails, remove it manually before restart
+- **Local SQLite Binary**: Debug with `./sqlite3-build/sqlite3 db/ginxsom.db`, NOT system sqlite3
+- **Authentication Debug**: Failed auth shows error codes in nostr_core format - use `nostr_strerror()` for meanings
+- **Memory Leaks**: cJSON objects MUST be deleted after use - common leak source in auth parsing
+- **File Permissions**: Blob files need 644 permissions or nginx can't serve them - check with `ls -la blobs/`
+- **Database Locks**: SQLite connection must be closed on ALL code paths or database locks occur
+- **Config Loading**: File config errors are silent - check stderr for "CONFIG:" messages during startup
+- **Admin Key Mismatch**: Database admin_pubkey vs .admin_keys file often cause auth failures
+- **Nginx Port Conflicts**: Local nginx on 9001 conflicts with system nginx on 80 - check with `netstat -tlnp`
+- **Hash Calculation**: File data buffer must be complete before `nostr_sha256()` call or hash is wrong