v2.1.28 - Add kind-3 fallback for relay discovery (NIP-65 pre-standard relay lists in contact list r tags)

Implemented comprehensive database query tracking to identify clients causing
high CPU usage through excessive database queries. The relay now tracks and
displays query statistics per WebSocket connection in the admin UI.

Features Added:
- Track db_queries_executed and db_rows_returned per connection
- Calculate query rate (queries/minute) and row rate (rows/minute)
- Display stats in admin UI grouped by IP address and WebSocket
- Show: IP, Subscriptions, Queries, Rows, Query Rate, Duration

Implementation:
- Added tracking fields to per_session_data structure
- Increment counters in handle_req_message() and handle_count_message()
- Extract stats from pss in query_subscription_details()
- Updated admin UI to display IP address and query metrics

Use Case:
Admins can now identify abusive clients by monitoring:
- High query rates (>50 queries/min indicates polling abuse)
- High row counts (>10K rows/min indicates broad filter abuse)
- Query patterns (high queries + low rows = targeted, high both = crawler)

This enables informed decisions about which IPs to blacklist based on
actual resource consumption rather than just connection count.

.gitignore

@@ -2,5 +2,13 @@ nostr_core_lib/
 nips/
 build/
 relay.log
+relay.pid
 Trash/
 src/version.h
+dev-config/
+db/
+copy_executable_local.sh
+nostr_login_lite/
+style_guide/
+nostr-tools
+.test_keysadmin/cache/

.gitmodules

@@ -1,3 +1,6 @@
-[submodule "nostr_core_lib"]
-	path = nostr_core_lib
-	url = https://git.laantungir.net/laantungir/nostr_core_lib.git
+[submodule "c_utils_lib"]
+	path = c_utils_lib
+	url = ssh://git@git.laantungir.net:2222/laantungir/c_utils_lib.git
+[submodule "text_graph"]
+	path = text_graph
+	url = ssh://git@git.laantungir.net:2222/laantungir/text_graph.git

.relay.laantungir.net.keys

@@ -0,0 +1,2 @@
+ADMIN_PUBKEY='6a04ab98d9e4774ad806e302dddeb63bea16b5cb5f223ee77478e861bb583eb3'
+SERVER_PRIVKEY='1111111111111111111111111111111111111111111111111111111111111111'

.roo/architect/AGENTS.md

@@ -0,0 +1,298 @@
+
+# AGENTS.md - AI Agent Integration Guide for Architect Mode
+
+**Project-Specific Information for AI Agents Working with C-Relay-PG in Architect Mode**
+
+## Critical Architecture Understanding
+
+### System Architecture Overview
+C-Relay-PG implements a **unique event-based configuration architecture** that fundamentally differs from traditional Nostr relays:
+
+```
+┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
+│   WebSocket     │    │  Configuration   │    │    Database     │
+│   + HTTP        │◄──►│  Event System    │◄──►│   (SQLite)      │
+│   (Port 8888)   │    │  (Kind 33334)    │    │  Schema v4      │
+└─────────────────┘    └──────────────────┘    └─────────────────┘
+         │                       │                       │
+         ▼                       ▼                       ▼
+┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
+│ nostr_core_lib  │    │   Admin Key      │    │ Event Storage   │
+│ (Crypto/Sigs)   │    │   Management     │    │ + Subscriptions │
+└─────────────────┘    └──────────────────┘    └─────────────────┘
+```
+
+### Core Architectural Principles
+
+#### 1. Event-Driven Configuration
+**Design Philosophy**: Configuration as cryptographically signed events rather than files
+- **Benefits**: Auditability, remote management, tamper-evidence
+- **Trade-offs**: Complexity in configuration changes, admin key management burden
+- **Implementation**: Kind 33334 events stored in same database as relay events
+
+#### 2. Identity-Based Database Naming
+**Design Philosophy**: Database file named by relay's generated public key
+- **Benefits**: Prevents database conflicts, enables multi-relay deployments
+- **Trade-offs**: Cannot predict database filename, complicates backup strategies
+- **Implementation**: `<relay_pubkey>.db` created in build/ directory
+
+#### 3. Single-Binary Deployment
+**Design Philosophy**: All functionality embedded in one executable
+- **Benefits**: Simple deployment, no external dependencies to manage
+- **Trade-offs**: Larger binary size, harder to modularize
+- **Implementation**: SQL schema embedded as header file, nostr_core_lib as submodule
+
+#### 4. Dual-Protocol Support
+**Design Philosophy**: WebSocket (Nostr) and HTTP (NIP-11) on same port
+- **Benefits**: Simplified port management, reduced infrastructure complexity
+- **Trade-offs**: Protocol detection overhead, libwebsockets dependency
+- **Implementation**: Request routing based on HTTP headers and upgrade requests
+
+## Architectural Decision Analysis
+
+### Configuration System Design
+**Traditional Approach vs C-Relay-PG:**
+```
+Traditional:           C-Relay-PG:
+config.json     →     kind 33334 events
+ENV variables   →     cryptographically signed tags
+File watching   →     database polling/restart
+```
+
+**Implications for Extensions:**
+- Configuration changes require event signing capabilities
+- No hot-reloading without architectural changes
+- Admin key loss = complete database reset required
+
+### Database Architecture Decisions
+**Schema Design Philosophy:**
+- **Event Tags as JSON**: Separate table with JSON column instead of normalized relations
+- **Application-Level Filtering**: NIP-40 expiration handled in C, not SQL
+- **Embedded Schema**: Version 4 schema compiled into binary
+
+**Scaling Considerations:**
+- SQLite suitable for small-to-medium relays (< 10k concurrent connections)
+- Single-writer limitation of SQLite affects write-heavy workloads
+- JSON tag storage optimizes for read performance over write normalization
+
+### Memory Management Architecture
+**Thread Safety Model:**
+- Global subscription manager with mutex protection
+- Per-client subscription limits enforced in memory
+- WebSocket connection state managed by libwebsockets
+
+**Resource Management:**
+- JSON objects use reference counting (jansson library)
+- String duplication pattern for configuration values
+- Automatic cleanup on client disconnect
+
+## Architectural Extension Points
+
+### Adding New Configuration Options
+**Required Changes:**
+1. Update [`default_config_event.h`](src/default_config_event.h) template
+2. Add parsing logic in [`config.c`](src/config.c) `load_config_from_database()`
+3. Add global config struct field in [`config.h`](src/config.h)
+4. Update documentation in [`docs/configuration_guide.md`](docs/configuration_guide.md)
+
+### Adding New NIP Support
+**Integration Pattern:**
+1. Event validation in [`request_validator.c`](src/request_validator.c)
+2. Protocol handling in [`main.c`](src/main.c) WebSocket callback
+3. Database storage considerations in schema
+4. Add test in `tests/` directory
+
+### Scaling Architecture
+**Current Limitations:**
+- Single process, no horizontal scaling
+- SQLite single-writer bottleneck
+- Memory-based subscription management
+
+**Potential Extensions:**
+- Redis for subscription state sharing
+- PostgreSQL for better concurrent write performance
+- Load balancer for read scaling with multiple instances
+
+## Deployment Architecture Patterns
+
+### Development Deployment
+```
+Developer Machine:
+├── ./make_and_restart_relay.sh
+├── build/c_relay_pg_x86
+├── build/<relay_pubkey>.db
+└── relay.log
+```
+
+### Production SystemD Deployment
+```
+/opt/c-relay-pg/:
+├── c_relay_pg_x86
+├── <relay_pubkey>.db
+├── systemd service (c-relay-pg.service)
+└── c-relay-pg user isolation
+```
+
+### Container Deployment Architecture
+```
+Container:
+├── Multi-stage build (deps + binary)
+├── Volume mount for database persistence
+├── Health checks via NIP-11 endpoint
+└── Signal handling for graceful shutdown
+```
+
+### Reverse Proxy Architecture
+```
+Internet → Nginx/HAProxy → C-Relay-PG
+                       ├── WebSocket upgrade handling
+                       ├── SSL termination
+                       └── Rate limiting
+```
+
+## Security Architecture Considerations
+
+### Key Management Design
+**Admin Key Security Model:**
+- Generated once, displayed once, never stored
+- Required for all configuration changes
+- Loss requires complete database reset
+
+**Relay Identity Model:**
+- Separate keypair for relay identity
+- Public key used for database naming
+- Private key never exposed to clients
+
+### Event Validation Pipeline
+```
+WebSocket Input → JSON Parse → Schema Validate → Signature Verify → Store
+                             ↓                 ↓                  ↓
+                    reject    reject          reject           success
+```
+
+### Attack Surface Analysis
+**Network Attack Vectors:**
+- WebSocket connection flooding (mitigated by libwebsockets limits)
+- JSON parsing attacks (handled by jansson library bounds checking)
+- SQLite injection (prevented by prepared statements)
+
+**Configuration Attack Vectors:**
+- Admin key compromise (complete relay control)
+- Event signature forgery (prevented by nostr_core_lib validation)
+- Replay attacks (event timestamp validation required)
+
+## Non-Obvious Architectural Considerations
+
+### Database Evolution Strategy
+**Current Limitations:**
+- Schema changes require database recreation
+- No migration system for configuration events
+- Version 4 schema embedded in binary
+
+**Future Architecture Needs:**
+- Schema versioning and migration system
+- Backward compatibility for configuration events
+- Database backup/restore procedures
+
+### Configuration Event Lifecycle
+**Event Flow:**
+```
+Admin Signs Event → WebSocket Submit → Validate → Store → Restart Required
+                                    ↓            ↓         ↓
+                              Signature Check   Database  Config Reload
+```
+
+**Architectural Implications:**
+- No hot configuration reloading
+- Configuration changes require planned downtime
+- Event ordering matters for multiple simultaneous changes
+
+### Cross-Architecture Deployment
+**Build System Architecture:**
+- Auto-detection of host architecture
+- Cross-compilation support for ARM64
+- Architecture-specific binary outputs
+
+**Deployment Implications:**
+- Binary must match target architecture
+- Dependencies must be available for target architecture
+- Debug tooling architecture-specific
+
+### Performance Architecture Characteristics
+**Bottlenecks:**
+1. **SQLite Write Performance**: Single writer limitation
+2. **JSON Parsing**: Per-event parsing overhead
+3. **Signature Validation**: Cryptographic operations per event
+4. **Memory Management**: JSON object lifecycle management
+
+**Optimization Points:**
+- Prepared statement reuse
+- Connection pooling for concurrent reads
+- Event batching for bulk operations
+- Subscription indexing strategies
+
+### Integration Architecture Patterns
+**Monitoring Integration:**
+- NIP-11 endpoint for health checks
+- Log file monitoring for operational metrics
+- Database query monitoring for performance
+- Process monitoring for resource usage
+
+**Backup Architecture:**
+- Database file backup (SQLite file copy)
+- Configuration event export/import
+- Admin key secure storage (external to relay)
+
+### Future Extension Architectures
+**Multi-Relay Coordination:**
+- Database sharding by event kind
+- Cross-relay event synchronization
+- Distributed configuration management
+
+**Plugin Architecture Possibilities:**
+- Event processing pipeline hooks
+- Custom validation plugins
+- External authentication providers
+
+**Scaling Architecture Options:**
+- Read replicas with PostgreSQL migration
+- Event stream processing with message queues
+- Microservice decomposition (auth, storage, validation)
+
+## Architectural Anti-Patterns to Avoid
+
+1. **Configuration File Addition**: Breaks event-based config paradigm
+2. **Direct Database Modification**: Bypasses signature validation
+3. **Hard-Coded Ports**: Conflicts with auto-fallback system
+4. **Schema Modifications**: Requires database recreation
+5. **Admin Key Storage**: Violates security model
+6. **Blocking Operations**: Interferes with WebSocket event loop
+7. **Memory Leaks**: JSON objects must be properly reference counted
+8. **Thread Unsafe Operations**: Global state requires proper synchronization
+
+## Architecture Decision Records (Implicit)
+
+### Decision: Event-Based Configuration
+**Context**: Traditional config files vs. cryptographic auditability
+**Decision**: Store configuration as signed Nostr events
+**Consequences**: Complex configuration changes, enhanced security, remote management capability
+
+### Decision: SQLite Database
+**Context**: Database choice for relay storage
+**Decision**: Embedded SQLite with JSON tag storage
+**Consequences**: Simple deployment, single-writer limitation, application-level filtering
+
+### Decision: Single Binary Deployment
+**Context**: Dependency management vs. deployment simplicity
+**Decision**: Embed all dependencies and schema in binary
+**Consequences**: Larger binary, simple deployment, version coupling
+
+### Decision: Dual Protocol Support
+**Context**: WebSocket for Nostr, HTTP for NIP-11
+**Decision**: Same port serves both protocols
+**Consequences**: Simplified deployment, protocol detection overhead, libwebsockets dependency
+
+These architectural decisions form the foundation of C-Relay-PG's unique approach to Nostr relay implementation and should be carefully considered when planning extensions or modifications.
+**
+
+[Response interrupted by a tool use result. Only one tool may be used at a time and should be placed at the end of the message.]

.roo/commands/push.md

@@ -0,0 +1,7 @@
+---
+description: "Brief description of what this command does"
+---
+
+Run increment_and_push.sh, and supply a good git commit message. For example:
+
+./increment_and_push.sh "Fixed the bug with nip05 implementation"

.rooignore

@@ -0,0 +1 @@
+src/embedded_web_content.c

.test_keys

@@ -0,0 +1,2 @@
+ADMIN_PUBKEY='8ff74724ed641b3c28e5a86d7c5cbc49c37638ace8c6c38935860e7a5eedde0e'
+SERVER_PRIVKEY='1111111111111111111111111111111111111111111111111111111111111111'

AGENTS.md

@@ -0,0 +1,152 @@
+# AGENTS.md - AI Agent Integration Guide
+
+**Project-Specific Information for AI Agents Working with C-Relay-PG**
+
+## Critical Build Commands
+
+### Primary Build Command
+```bash
+./make_and_restart_relay.sh
+```
+**Never use `make` directly.** The project requires the custom restart script which:
+- Handles database preservation/cleanup based on flags
+- Manages architecture-specific binary detection (x86/ARM64)
+- Performs automatic process cleanup and port management
+- Starts relay in background with proper logging
+
+### Architecture-Specific Binary Outputs
+- **x86_64**: `./build/c_relay_pg_x86`
+- **ARM64**: `./build/c_relay_pg_arm64`
+- **Other**: `./build/c_relay_pg_$(ARCH)`
+
+### Database File Naming Convention
+- **Format**: `<relay_pubkey>.db` (NOT `.nrdb` as shown in docs)
+- **Location**: Created in `build/` directory during execution
+- **Cleanup**: Use `--preserve-database` flag to retain between builds
+
+## Critical Integration Issues
+
+### Event-Based Configuration System
+- **No traditional config files** - all configuration stored in config table
+- Admin private key shown **only once** on first startup
+- Configuration changes require cryptographically signed events
+- Database path determined by generated relay pubkey
+
+### First-Time Startup Sequence
+1. Relay generates admin keypair and relay keypair
+2. Creates database file with relay pubkey as filename
+3. Stores default configuration in config table
+4. **CRITICAL**: Admin private key displayed once and never stored on disk
+
+### Port Management
+- Default port 8888 with automatic fallback (8889, 8890, etc.)
+- Script performs port availability checking before libwebsockets binding
+- Process cleanup includes force-killing processes on port 8888
+
+### Database Schema Dependencies
+- Uses embedded SQL schema (`sql_schema.h`)
+- Schema version 4 with JSON tag storage
+- **Critical**: Event expiration filtering done at application level, not SQL level
+
+### Admin API Event Structure
+```json
+{
+  "kind": 23456,
+  "content": "base64_nip44_encrypted_command_array",
+  "tags": [
+    ["p", "<relay_pubkey>"]
+  ]
+}
+```
+
+**Configuration Commands** (encrypted in content):
+- `["relay_description", "My Relay"]`
+- `["max_subscriptions_per_client", "25"]`
+- `["pow_min_difficulty", "16"]`
+
+**Auth Rule Commands** (encrypted in content):
+- `["blacklist", "pubkey", "hex_pubkey_value"]`
+- `["whitelist", "pubkey", "hex_pubkey_value"]`
+
+**Query Commands** (encrypted in content):
+- `["auth_query", "all"]`
+- `["system_command", "system_status"]`
+
+### Process Management
+```bash
+# Kill existing relay processes
+pkill -f "c_relay_pg_"
+
+# Check running processes
+ps aux | grep c_relay_pg_
+
+# Force kill port binding
+fuser -k 8888/tcp
+```
+
+### Cross-Compilation Specifics
+- ARM64 requires explicit dependency installation: `make install-arm64-deps`
+- Uses `aarch64-linux-gnu-gcc` with specific library paths
+- PKG_CONFIG_PATH must be set for ARM64: `/usr/lib/aarch64-linux-gnu/pkgconfig`
+
+### Testing Integration
+- Tests expect relay running on default port
+- Use `tests/quick_error_tests.sh` for validation
+- Event configuration tests: `tests/event_config_tests.sh`
+
+### SystemD Integration Considerations
+- Service runs as `c-relay-pg` user in `/opt/c-relay-pg`
+- Database files created in WorkingDirectory automatically
+- No environment variables needed (event-based config)
+- Resource limits: 65536 file descriptors, 4096 processes
+
+### Development vs Production Differences
+- Development: `make_and_restart_relay.sh` (default database cleanup)
+- Production: `make_and_restart_relay.sh --preserve-database`
+- Debug build requires manual gdb attachment to architecture-specific binary
+
+### Critical File Dependencies
+- `nostr_core_lib/` submodule must be initialized and built first
+- Version header auto-generated from git tags: `src/version.h`
+- Schema embedded in binary from `src/sql_schema.h`
+
+### WebSocket Protocol Specifics
+- Supports both WebSocket (Nostr protocol) and HTTP (NIP-11)
+- NIP-11 requires `Accept: application/nostr+json` header
+- CORS headers automatically added for NIP-11 compliance
+
+### Memory Management Notes
+- Persistent subscription system with thread-safe global manager
+- Per-session subscription limits enforced
+- Event filtering done at C level, not SQL level for NIP-40 expiration
+
+### Configuration Override Behavior
+- CLI port override applies during first-time startup and existing relay restarts
+- After database creation, all config comes from events (but CLI overrides can still be applied)
+- Database path cannot be changed after initialization
+
+## Non-Obvious Pitfalls
+
+1. **Database Lock Issues**: Script handles SQLite locking by killing existing processes first
+2. **Port Race Conditions**: Pre-check + libwebsockets binding can still fail due to timing
+3. **Key Loss**: Admin private key loss requires complete database deletion and restart
+4. **Architecture Detection**: Build system auto-detects but cross-compilation requires manual setup
+5. **Event Storage**: Ephemeral events (kind 20000-29999) accepted but not stored
+6. **Signature Validation**: All events validated with `nostr_verify_event_signature()` from nostr_core_lib
+
+## Quick Debugging Commands
+```bash
+# Check relay status
+ps aux | grep c_relay_pg_ && netstat -tln | grep 8888
+
+# View logs
+tail -f relay.log
+
+# Test WebSocket connection
+wscat -c ws://localhost:8888
+
+# Test NIP-11 endpoint
+curl -H "Accept: application/nostr+json" http://localhost:8888
+
+# Find database files
+find . -name "*.db" -type f

API.md

@@ -0,0 +1,995 @@
+# C-Relay-PG API Documentation
+
+Complete API reference for the C-Relay-PG event-based administration system and advanced features.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Authentication](#authentication)
+- [Admin API](#admin-api)
+  - [Event Structure](#event-structure)
+  - [Configuration Management](#configuration-management)
+  - [Auth Rules Management](#auth-rules-management)
+  - [System Commands](#system-commands)
+  - [Database Queries](#database-queries)
+- [Configuration Reference](#configuration-reference)
+- [Real-time Monitoring](#real-time-monitoring)
+- [Direct Message Admin](#direct-message-admin)
+- [Response Formats](#response-formats)
+- [Error Handling](#error-handling)
+- [Examples](#examples)
+
+## Overview
+
+C-Relay-PG uses an innovative **event-based administration system** where all configuration and management commands are sent as cryptographically signed Nostr events. This provides:
+
+- **Cryptographic security**: All commands must be signed with the admin private key
+- **Audit trail**: Complete history of all administrative actions
+- **Real-time updates**: Configuration changes applied instantly
+- **Standard protocol**: Uses Nostr events, no custom protocols
+- **NIP-44 encryption**: All admin commands and responses are encrypted
+
+### Key Concepts
+
+1. **Admin Keypair**: Generated on first startup, used to sign all admin commands
+2. **Relay Keypair**: The relay's identity on the Nostr network
+3. **Admin Events**: Kind 23456 events with NIP-44 encrypted commands
+4. **Response Events**: Kind 23457 events with NIP-44 encrypted responses
+5. **Event-Based Config**: All settings stored as events in the database
+
+## Authentication
+
+### Admin Private Key
+
+The admin private key is displayed **only once** during first startup:
+
+```
+========================================
+IMPORTANT: SAVE THIS ADMIN PRIVATE KEY
+========================================
+Admin Private Key: nsec1abc123...
+Admin Public Key: npub1def456...
+========================================
+```
+
+**Critical**: Save this key immediately. It cannot be recovered and is required for all administrative operations.
+
+### Secure Storage
+
+Store the admin private key securely:
+
+```bash
+# Environment variable
+export C_RELAY_ADMIN_KEY="nsec1abc123..."
+
+# Secure file
+echo "nsec1abc123..." > ~/.c-relay-pg-admin
+chmod 600 ~/.c-relay-pg-admin
+
+# Password manager (recommended)
+# Store in 1Password, Bitwarden, etc.
+```
+
+### Key Loss Recovery
+
+If you lose the admin private key:
+
+1. Stop the relay
+2. Delete the database file (`*.db`)
+3. Restart the relay (generates new keys)
+4. **Note**: This deletes all events and configuration
+
+## Admin API
+
+### Event Structure
+
+All admin commands use the same event structure with NIP-44 encrypted content.
+
+#### Admin Command Event (Kind 23456)
+
+```json
+{
+  "id": "computed_event_id",
+  "pubkey": "admin_public_key_hex",
+  "created_at": 1234567890,
+  "kind": 23456,
+  "content": "AqHBUgcM7dXFYLQuDVzGwMST1G8jtWYyVvYxXhVGEu4nAb4LVw...",
+  "tags": [
+    ["p", "relay_public_key_hex"]
+  ],
+  "sig": "event_signature"
+}
+```
+
+**Fields**:
+- `kind`: Must be `23456` for admin commands
+- `pubkey`: Admin public key (hex format)
+- `content`: NIP-44 encrypted JSON array containing the command
+- `tags`: Must include `["p", "relay_pubkey"]` tag
+- `sig`: Valid signature from admin private key
+
+#### Encrypted Content Format
+
+The `content` field contains a NIP-44 encrypted JSON array:
+
+```json
+["command_name", "param1", "param2", ...]
+```
+
+Examples:
+```json
+["config_query", "all"]
+["config_update", [{"key": "relay_name", "value": "My Relay", ...}]]
+["blacklist", "pubkey", "abc123..."]
+["auth_query", "all"]
+["sql_query", "SELECT * FROM events LIMIT 10"]
+```
+
+#### Admin Response Event (Kind 23457)
+
+```json
+{
+  "id": "response_event_id",
+  "pubkey": "relay_public_key_hex",
+  "created_at": 1234567890,
+  "kind": 23457,
+  "content": "BpKCVhfN8eYtRmPqSvWxZnMkL2gHjUiOp3rTyEwQaS5dFg...",
+  "tags": [
+    ["p", "admin_public_key_hex"],
+    ["e", "request_event_id"]
+  ],
+  "sig": "response_signature"
+}
+```
+
+**Fields**:
+- `kind`: Always `23457` for admin responses
+- `pubkey`: Relay public key (hex format)
+- `content`: NIP-44 encrypted JSON response object
+- `tags`: Includes `["p", "admin_pubkey"]` and optionally `["e", "request_id"]`
+- `sig`: Valid signature from relay private key
+
+### Configuration Management
+
+#### Query All Configuration
+
+**Command**:
+```json
+["config_query", "all"]
+```
+
+**Response** (decrypted):
+```json
+{
+  "query_type": "config_all",
+  "total_results": 27,
+  "timestamp": 1234567890,
+  "data": [
+    {
+      "key": "relay_name",
+      "value": "C-Relay-PG",
+      "data_type": "string",
+      "category": "relay",
+      "description": "Relay name displayed in NIP-11"
+    },
+    {
+      "key": "auth_enabled",
+      "value": "false",
+      "data_type": "boolean",
+      "category": "auth",
+      "description": "Enable whitelist/blacklist authentication"
+    }
+  ]
+}
+```
+
+#### Update Configuration
+
+**Command**:
+```json
+["config_update", [
+  {
+    "key": "relay_name",
+    "value": "My Awesome Relay",
+    "data_type": "string",
+    "category": "relay"
+  },
+  {
+    "key": "max_subscriptions_per_client",
+    "value": "50",
+    "data_type": "integer",
+    "category": "limits"
+  }
+]]
+```
+
+**Response** (decrypted):
+```json
+{
+  "query_type": "config_update",
+  "status": "success",
+  "total_results": 2,
+  "timestamp": 1234567890,
+  "data": [
+    {
+      "key": "relay_name",
+      "value": "My Awesome Relay",
+      "status": "updated"
+    },
+    {
+      "key": "max_subscriptions_per_client",
+      "value": "50",
+      "status": "updated"
+    }
+  ]
+}
+```
+
+### Auth Rules Management
+
+#### Add Blacklist Rule
+
+**Command**:
+```json
+["blacklist", "pubkey", "abc123def456..."]
+```
+
+**Response** (decrypted):
+```json
+{
+  "query_type": "auth_add",
+  "status": "success",
+  "message": "Blacklist rule added successfully",
+  "timestamp": 1234567890
+}
+```
+
+#### Add Whitelist Rule
+
+**Command**:
+```json
+["whitelist", "pubkey", "def456abc123..."]
+```
+
+#### Delete Auth Rule
+
+**Command**:
+```json
+["delete_auth_rule", "blacklist", "pubkey", "abc123def456..."]
+```
+
+**Response** (decrypted):
+```json
+{
+  "query_type": "auth_delete",
+  "status": "success",
+  "message": "Auth rule deleted successfully",
+  "timestamp": 1234567890
+}
+```
+
+#### Query All Auth Rules
+
+**Command**:
+```json
+["auth_query", "all"]
+```
+
+**Response** (decrypted):
+```json
+{
+  "query_type": "auth_rules_all",
+  "total_results": 5,
+  "timestamp": 1234567890,
+  "data": [
+    {
+      "rule_type": "blacklist",
+      "pattern_type": "pubkey",
+      "pattern_value": "abc123...",
+      "action": "deny"
+    },
+    {
+      "rule_type": "whitelist",
+      "pattern_type": "pubkey",
+      "pattern_value": "def456...",
+      "action": "allow"
+    }
+  ]
+}
+```
+
+#### Query Specific Rule Type
+
+**Command**:
+```json
+["auth_query", "whitelist"]
+```
+
+#### Query Specific Pattern
+
+**Command**:
+```json
+["auth_query", "pattern", "abc123..."]
+```
+
+### System Commands
+
+#### System Status
+
+**Command**:
+```json
+["system_command", "system_status"]
+```
+
+**Response** (decrypted):
+```json
+{
+  "query_type": "system_status",
+  "timestamp": 1234567890,
+  "status": "running",
+  "uptime_seconds": 86400,
+  "version": "0.6.0",
+  "relay_pubkey": "relay_public_key_hex",
+  "database_size_bytes": 10485760,
+  "total_events": 15432,
+  "active_connections": 42,
+  "active_subscriptions": 156
+}
+```
+
+#### Clear All Auth Rules
+
+**Command**:
+```json
+["system_command", "clear_all_auth_rules"]
+```
+
+**Response** (decrypted):
+```json
+{
+  "query_type": "system_command",
+  "status": "success",
+  "message": "All auth rules cleared",
+  "timestamp": 1234567890
+}
+```
+
+#### Database Statistics
+
+**Command**:
+```json
+["stats_query"]
+```
+
+**Response** (decrypted):
+```json
+{
+  "query_type": "stats_query",
+  "timestamp": 1234567890,
+  "database_size_bytes": 10485760,
+  "total_events": 15432,
+  "database_created_at": 1234567800,
+  "latest_event_at": 1234567890,
+  "event_kinds": [
+    {
+      "kind": 1,
+      "count": 12000,
+      "percentage": 77.8
+    },
+    {
+      "kind": 0,
+      "count": 2500,
+      "percentage": 16.2
+    }
+  ],
+  "time_stats": {
+    "total": 15432,
+    "last_24h": 234,
+    "last_7d": 1456,
+    "last_30d": 5432
+  },
+  "top_pubkeys": [
+    {
+      "pubkey": "abc123...",
+      "event_count": 1234,
+      "percentage": 8.0
+    }
+  ]
+}
+```
+
+### Database Queries
+
+#### SQL Query Command
+
+Execute read-only SQL queries against the relay database.
+
+**Command**:
+```json
+["sql_query", "SELECT * FROM events ORDER BY created_at DESC LIMIT 10"]
+```
+
+**Response** (decrypted):
+```json
+{
+  "query_type": "sql_query",
+  "request_id": "request_event_id",
+  "timestamp": 1234567890,
+  "query": "SELECT * FROM events ORDER BY created_at DESC LIMIT 10",
+  "execution_time_ms": 45,
+  "row_count": 10,
+  "columns": ["id", "pubkey", "created_at", "kind", "content", "tags", "sig"],
+  "rows": [
+    ["abc123...", "def456...", 1234567890, 1, "Hello world", "[]", "sig123..."],
+    ["ghi789...", "jkl012...", 1234567880, 0, "{\"name\":\"Alice\"}", "[]", "sig456..."]
+  ]
+}
+```
+
+#### Security Features
+
+- **Read-only**: Only SELECT statements allowed
+- **Query timeout**: 5 seconds maximum
+- **Result limit**: 1000 rows maximum
+- **Logging**: All queries logged with execution time
+- **Validation**: SQL injection protection
+
+#### Available Tables and Views
+
+**Core Tables**:
+- `events` - All Nostr events
+- `config` - Configuration parameters
+- `auth_rules` - Authentication rules
+- `subscription_events` - Subscription lifecycle log
+- `event_broadcasts` - Event broadcast log
+
+**Views**:
+- `recent_events` - Last 1000 events
+- `event_stats` - Event statistics by type
+- `subscription_analytics` - Subscription metrics
+- `active_subscriptions_log` - Currently active subscriptions
+- `event_kinds_view` - Event distribution by kind
+- `top_pubkeys_view` - Top 10 pubkeys by event count
+- `time_stats_view` - Time-based statistics
+
+#### Example Queries
+
+**Recent events**:
+```sql
+SELECT id, pubkey, created_at, kind 
+FROM events 
+ORDER BY created_at DESC 
+LIMIT 20
+```
+
+**Event distribution**:
+```sql
+SELECT * FROM event_kinds_view 
+ORDER BY count DESC
+```
+
+**Active subscriptions**:
+```sql
+SELECT * FROM active_subscriptions_log 
+ORDER BY created_at DESC
+```
+
+**Database statistics**:
+```sql
+SELECT
+  (SELECT COUNT(*) FROM events) as total_events,
+  (SELECT COUNT(*) FROM subscription_events) as total_subscriptions,
+  (SELECT COUNT(DISTINCT pubkey) FROM events) as unique_pubkeys
+```
+
+**Events by specific pubkey**:
+```sql
+SELECT id, created_at, kind, content 
+FROM events 
+WHERE pubkey = 'abc123...' 
+ORDER BY created_at DESC 
+LIMIT 50
+```
+
+**Events in time range**:
+```sql
+SELECT COUNT(*) as count, kind 
+FROM events 
+WHERE created_at BETWEEN 1234567000 AND 1234567890 
+GROUP BY kind 
+ORDER BY count DESC
+```
+
+## Configuration Reference
+
+### Basic Relay Settings
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `relay_name` | string | "C-Relay-PG" | Relay name (NIP-11) |
+| `relay_description` | string | "C Nostr Relay" | Relay description |
+| `relay_contact` | string | "" | Admin contact info |
+| `relay_software` | string | "c-relay-pg" | Software identifier |
+| `relay_version` | string | auto | Software version |
+| `supported_nips` | string | "1,9,11,13,15,20,33,40,42,45,50,70" | Supported NIPs |
+| `language_tags` | string | "*" | Supported languages |
+| `relay_countries` | string | "*" | Supported countries |
+| `posting_policy` | string | "" | Posting policy URL |
+| `payments_url` | string | "" | Payment URL |
+
+### Connection & Limits
+
+| Key | Type | Default | Range | Restart Required |
+|-----|------|---------|-------|------------------|
+| `max_connections` | integer | 1000 | 1-10000 | Yes |
+| `max_subscriptions_per_client` | integer | 25 | 1-100 | No |
+| `max_total_subscriptions` | integer | 5000 | 100-50000 | No |
+| `max_message_length` | integer | 65536 | 1024-1048576 | No |
+| `max_event_tags` | integer | 2000 | 10-10000 | No |
+| `max_content_length` | integer | 65536 | 1-1048576 | No |
+
+### Authentication & Access Control
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `auth_enabled` | boolean | false | Enable whitelist/blacklist |
+| `nip42_auth_required` | boolean | false | Require NIP-42 auth |
+| `nip42_auth_required_kinds` | string | "" | Kinds requiring NIP-42 |
+| `nip42_challenge_timeout` | integer | 300 | Challenge timeout (seconds) |
+
+### Proof of Work (NIP-13)
+
+| Key | Type | Default | Values | Description |
+|-----|------|---------|--------|-------------|
+| `pow_min_difficulty` | integer | 0 | 0-40 | Minimum PoW difficulty |
+| `pow_mode` | string | "optional" | disabled/optional/required | PoW enforcement mode |
+
+### Event Expiration (NIP-40)
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `nip40_expiration_enabled` | boolean | true | Enable expiration support |
+| `nip40_expiration_strict` | boolean | false | Reject expired events |
+| `nip40_expiration_filter` | boolean | true | Filter expired from results |
+| `nip40_expiration_grace_period` | integer | 300 | Grace period (seconds) |
+
+### Monitoring
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `kind_24567_reporting_throttle_sec` | integer | 5 | Monitoring event throttle |
+
+### Dynamic vs Restart-Required
+
+**Dynamic (No Restart)**:
+- All NIP-11 relay information
+- Authentication settings
+- Subscription limits
+- Event validation limits
+- Proof of Work settings
+- Expiration settings
+
+**Restart Required**:
+- `max_connections`
+- `relay_port`
+- Database settings
+
+## Real-time Monitoring
+
+C-Relay-PG provides subscription-based real-time monitoring using ephemeral events (kind 24567).
+
+### Activation
+
+Subscribe to kind 24567 events to activate monitoring:
+
+```json
+["REQ", "monitoring-sub", {"kinds": [24567]}]
+```
+
+### Monitoring Event Types
+
+Subscribe to specific monitoring types using d-tag filters:
+
+```json
+["REQ", "event-kinds", {"kinds": [24567], "#d": ["event_kinds"]}]
+["REQ", "time-stats", {"kinds": [24567], "#d": ["time_stats"]}]
+["REQ", "top-pubkeys", {"kinds": [24567], "#d": ["top_pubkeys"]}]
+["REQ", "cpu-metrics", {"kinds": [24567], "#d": ["cpu_metrics"]}]
+```
+
+### Event Structure
+
+```json
+{
+  "kind": 24567,
+  "pubkey": "relay_pubkey",
+  "created_at": 1234567890,
+  "content": "{\"data_type\":\"event_kinds\",\"timestamp\":1234567890,...}",
+  "tags": [
+    ["d", "event_kinds"]
+  ]
+}
+```
+
+### Monitoring Types
+
+#### Event Distribution (`event_kinds`)
+
+```json
+{
+  "data_type": "event_kinds",
+  "timestamp": 1234567890,
+  "total_events": 15432,
+  "kinds": [
+    {"kind": 1, "count": 12000, "percentage": 77.8},
+    {"kind": 0, "count": 2500, "percentage": 16.2}
+  ]
+}
+```
+
+#### Time Statistics (`time_stats`)
+
+```json
+{
+  "data_type": "time_stats",
+  "timestamp": 1234567890,
+  "total_events": 15432,
+  "last_24h": 234,
+  "last_7d": 1456,
+  "last_30d": 5432
+}
+```
+
+#### Top Publishers (`top_pubkeys`)
+
+```json
+{
+  "data_type": "top_pubkeys",
+  "timestamp": 1234567890,
+  "top_pubkeys": [
+    {"pubkey": "abc123...", "count": 1234, "percentage": 8.0},
+    {"pubkey": "def456...", "count": 987, "percentage": 6.4}
+  ]
+}
+```
+
+#### CPU Metrics (`cpu_metrics`)
+
+```json
+{
+  "data_type": "cpu_metrics",
+  "timestamp": 1234567890,
+  "cpu_percent": 12.5,
+  "memory_mb": 45.2,
+  "uptime_seconds": 86400
+}
+```
+
+#### Active Subscriptions (`active_subscriptions`) - Admin Only
+
+```json
+{
+  "data_type": "active_subscriptions",
+  "timestamp": 1234567890,
+  "total_subscriptions": 156,
+  "subscriptions_by_client": [
+    {"client_id": "client1", "count": 12},
+    {"client_id": "client2", "count": 8}
+  ]
+}
+```
+
+### Configuration
+
+Control monitoring frequency:
+
+```json
+["config_update", [{
+  "key": "kind_24567_reporting_throttle_sec",
+  "value": "10",
+  "data_type": "integer",
+  "category": "monitoring"
+}]]
+```
+
+### Performance
+
+- Events are ephemeral (not stored)
+- Automatic activation/deactivation based on subscriptions
+- Throttling prevents excessive event generation
+- Minimal overhead when no clients monitoring
+
+## Direct Message Admin
+
+Control your relay by sending direct messages from any Nostr client.
+
+### Setup
+
+1. The relay has its own keypair (shown on startup)
+2. The relay knows the admin public key
+3. Send NIP-17 direct messages to the relay
+
+### Available Commands
+
+Send a DM containing any of these keywords:
+
+| Command | Aliases | Response |
+|---------|---------|----------|
+| Statistics | stats, statistics | Database statistics |
+| Configuration | config, configuration | Current configuration |
+
+### Example
+
+Using any Nostr client that supports NIP-17:
+
+1. Find the relay's public key (shown on startup)
+2. Send a DM: "stats"
+3. Receive a DM with current relay statistics
+
+### Response Format
+
+The relay responds with a NIP-17 DM containing:
+
+**Stats Response**:
+```
+Relay Statistics
+================
+Total Events: 15,432
+Database Size: 10.5 MB
+Active Connections: 42
+Active Subscriptions: 156
+Uptime: 1 day, 2 hours
+```
+
+**Config Response**:
+```
+Relay Configuration
+===================
+Name: My Awesome Relay
+Description: Community relay
+Max Subscriptions: 25
+Auth Enabled: false
+PoW Difficulty: 0
+```
+
+## Response Formats
+
+### Success Response
+
+```json
+{
+  "query_type": "command_name",
+  "status": "success",
+  "message": "Operation completed successfully",
+  "timestamp": 1234567890,
+  "data": [...]
+}
+```
+
+### Error Response
+
+```json
+{
+  "query_type": "command_name",
+  "status": "error",
+  "error": "Error description",
+  "timestamp": 1234567890
+}
+```
+
+### Query Response
+
+```json
+{
+  "query_type": "query_name",
+  "total_results": 10,
+  "timestamp": 1234567890,
+  "data": [...]
+}
+```
+
+## Error Handling
+
+### Common Errors
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| `invalid_signature` | Event signature invalid | Check admin private key |
+| `unauthorized` | Wrong admin pubkey | Use correct admin key |
+| `invalid_command` | Unknown command | Check command format |
+| `validation_failed` | Invalid parameter value | Check parameter ranges |
+| `database_error` | Database operation failed | Check database integrity |
+| `timeout` | Query took too long | Simplify query or increase timeout |
+
+### Error Response Example
+
+```json
+{
+  "query_type": "config_update",
+  "status": "error",
+  "error": "field validation failed: invalid port number '99999' (must be 1-65535)",
+  "timestamp": 1234567890
+}
+```
+
+## Examples
+
+### JavaScript/TypeScript Example
+
+```javascript
+import { SimplePool, nip44, getPublicKey, finalizeEvent } from 'nostr-tools';
+
+const adminPrivkey = 'your_admin_privkey_hex';
+const adminPubkey = getPublicKey(adminPrivkey);
+const relayPubkey = 'relay_pubkey_hex';
+const relayUrl = 'ws://localhost:8888';
+
+// Create admin command
+async function sendAdminCommand(command) {
+  const pool = new SimplePool();
+  
+  // Encrypt command with NIP-44
+  const encryptedContent = await nip44.encrypt(
+    adminPrivkey,
+    relayPubkey,
+    JSON.stringify(command)
+  );
+  
+  // Create event
+  const event = finalizeEvent({
+    kind: 23456,
+    created_at: Math.floor(Date.now() / 1000),
+    tags: [['p', relayPubkey]],
+    content: encryptedContent
+  }, adminPrivkey);
+  
+  // Publish event
+  await pool.publish([relayUrl], event);
+  
+  // Subscribe to response
+  const sub = pool.sub([relayUrl], [{
+    kinds: [23457],
+    '#p': [adminPubkey],
+    since: Math.floor(Date.now() / 1000)
+  }]);
+  
+  return new Promise((resolve) => {
+    sub.on('event', async (event) => {
+      // Decrypt response
+      const decrypted = await nip44.decrypt(
+        adminPrivkey,
+        relayPubkey,
+        event.content
+      );
+      resolve(JSON.parse(decrypted));
+      sub.unsub();
+    });
+  });
+}
+
+// Query configuration
+const config = await sendAdminCommand(['config_query', 'all']);
+console.log(config);
+
+// Update configuration
+const result = await sendAdminCommand(['config_update', [
+  {
+    key: 'relay_name',
+    value: 'My Relay',
+    data_type: 'string',
+    category: 'relay'
+  }
+]]);
+console.log(result);
+
+// Add blacklist rule
+const blacklist = await sendAdminCommand([
+  'blacklist',
+  'pubkey',
+  'abc123...'
+]);
+console.log(blacklist);
+
+// Execute SQL query
+const query = await sendAdminCommand([
+  'sql_query',
+  'SELECT * FROM events ORDER BY created_at DESC LIMIT 10'
+]);
+console.log(query);
+```
+
+### Python Example
+
+```python
+from nostr_sdk import Keys, Client, EventBuilder, Filter, nip44
+
+admin_privkey = "your_admin_privkey_hex"
+relay_pubkey = "relay_pubkey_hex"
+relay_url = "ws://localhost:8888"
+
+# Initialize
+keys = Keys.parse(admin_privkey)
+client = Client(keys)
+client.add_relay(relay_url)
+client.connect()
+
+# Send admin command
+async def send_admin_command(command):
+    # Encrypt command
+    encrypted = nip44.encrypt(
+        keys.secret_key(),
+        relay_pubkey,
+        json.dumps(command)
+    )
+    
+    # Create event
+    event = EventBuilder.new(
+        kind=23456,
+        content=encrypted,
+        tags=[["p", relay_pubkey]]
+    ).to_event(keys)
+    
+    # Publish
+    await client.send_event(event)
+    
+    # Wait for response
+    filter = Filter().kind(23457).pubkey(relay_pubkey).since(int(time.time()))
+    events = await client.get_events_of([filter], timeout=5)
+    
+    if events:
+        # Decrypt response
+        decrypted = nip44.decrypt(
+            keys.secret_key(),
+            relay_pubkey,
+            events[0].content()
+        )
+        return json.loads(decrypted)
+
+# Query configuration
+config = await send_admin_command(["config_query", "all"])
+print(config)
+```
+
+### Bash/curl Example
+
+```bash
+#!/bin/bash
+
+# Note: This is a simplified example. Real implementation requires:
+# - NIP-44 encryption
+# - Event signing
+# - WebSocket connection
+
+RELAY_URL="ws://localhost:8888"
+ADMIN_PRIVKEY="your_admin_privkey"
+RELAY_PUBKEY="relay_pubkey"
+
+# Use nostrtool or similar for proper event creation
+nostrtool event \
+  --kind 23456 \
+  --content "$(echo '["config_query","all"]' | nip44-encrypt)" \
+  --tag p "$RELAY_PUBKEY" \
+  --private-key "$ADMIN_PRIVKEY" \
+  | nostrtool send "$RELAY_URL"
+```
+
+---
+
+## Additional Resources
+
+- **[Configuration Guide](docs/configuration_guide.md)** - Detailed configuration options
+- **[Deployment Guide](docs/deployment_guide.md)** - Production deployment
+- **[NIP-42 Authentication](docs/NIP-42_Authentication.md)** - Authentication setup
+- **[User Guide](docs/user_guide.md)** - End-user documentation
+
+## Support
+
+For API questions or issues:
+- Open an issue on GitHub
+- Check existing documentation
+- Join the Nostr community
+
+---
+
+**API Version**: 0.6.0  
+**Last Updated**: 2026-01-23

Dockerfile.alpine-musl

@@ -0,0 +1,153 @@
+# Alpine-based MUSL static binary builder for C-Relay-PG
+# Produces truly portable binaries with zero runtime dependencies
+
+ARG DEBUG_BUILD=false
+ARG DB_BACKEND=sqlite
+
+FROM alpine:3.19 AS builder
+
+# Re-declare build arguments in this stage
+ARG DEBUG_BUILD=false
+ARG DB_BACKEND=sqlite
+
+# Install build dependencies
+RUN apk add --no-cache \
+    build-base \
+    musl-dev \
+    git \
+    cmake \
+    pkgconfig \
+    autoconf \
+    automake \
+    libtool \
+    openssl-dev \
+    openssl-libs-static \
+    zlib-dev \
+    zlib-static \
+    curl-dev \
+    curl-static \
+    sqlite-dev \
+    sqlite-static \
+    postgresql-dev \
+    linux-headers \
+    wget \
+    bash \
+    openssh-client
+
+# Set working directory
+WORKDIR /build
+
+# Build libsecp256k1 static (cached layer - only rebuilds if Alpine version changes)
+RUN cd /tmp && \
+    git clone https://github.com/bitcoin-core/secp256k1.git && \
+    cd secp256k1 && \
+    ./autogen.sh && \
+    ./configure --enable-static --disable-shared --prefix=/usr \
+        CFLAGS="-fPIC" && \
+    make -j$(nproc) && \
+    make install && \
+    rm -rf /tmp/secp256k1
+
+# Build libwebsockets static with minimal features (cached layer)
+RUN cd /tmp && \
+    git clone --depth 1 --branch v4.3.3 https://github.com/warmcat/libwebsockets.git && \
+    cd libwebsockets && \
+    mkdir build && cd build && \
+    cmake .. \
+        -DLWS_WITH_STATIC=ON \
+        -DLWS_WITH_SHARED=OFF \
+        -DLWS_WITH_SSL=ON \
+        -DLWS_WITHOUT_TESTAPPS=ON \
+        -DLWS_WITHOUT_TEST_SERVER=ON \
+        -DLWS_WITHOUT_TEST_CLIENT=ON \
+        -DLWS_WITHOUT_TEST_PING=ON \
+        -DLWS_WITH_HTTP2=OFF \
+        -DLWS_WITH_LIBUV=OFF \
+        -DLWS_WITH_LIBEVENT=OFF \
+        -DLWS_IPV6=ON \
+        -DCMAKE_BUILD_TYPE=Release \
+        -DCMAKE_INSTALL_PREFIX=/usr \
+        -DCMAKE_C_FLAGS="-fPIC" && \
+    make -j$(nproc) && \
+    make install && \
+    rm -rf /tmp/libwebsockets
+
+# Submodules are provided in the local build context and copied explicitly below.
+# Avoid network/SSH dependency inside Docker image build.
+
+# Copy nostr_core_lib source files (cached unless nostr_core_lib changes)
+COPY nostr_core_lib /build/nostr_core_lib/
+
+# Copy c_utils_lib source files (cached unless c_utils_lib changes)
+COPY c_utils_lib /build/c_utils_lib/
+
+# Build c_utils_lib static library for relay logging utilities
+# (build only debug.c to avoid broken/missing version header surface in submodule revision)
+RUN cd c_utils_lib && \
+    mkdir -p build && \
+    gcc -U_FORTIFY_SOURCE -D_FORTIFY_SOURCE=0 -Wall -Wextra -std=c99 -O2 -g \
+        -Isrc -Iinclude -c src/debug.c -o build/debug.o && \
+    ar rcs libc_utils.a build/debug.o
+
+# Build nostr_core_lib with required NIPs (cached unless nostr_core_lib changes)
+# Disable fortification in build.sh to prevent __*_chk symbol issues
+# NIPs: 001(Basic), 004(Encryption), 006(Keys), 013(PoW), 017(DMs), 019(Bech32), 044(Encryption), 059(Gift Wrap - required by NIP-17)
+# NIP-04 is required by nostr_signer.c (NIP-46 bunker signer uses NIP-04 encryption)
+RUN cd nostr_core_lib && \
+    chmod +x build.sh && \
+    sed -i 's/CFLAGS="-Wall -Wextra -std=c99 -fPIC -O2"/CFLAGS="-U_FORTIFY_SOURCE -D_FORTIFY_SOURCE=0 -Wall -Wextra -std=c99 -fPIC -O2"/' build.sh && \
+    rm -f *.o *.a 2>/dev/null || true && \
+    ./build.sh --nips=1,4,6,13,17,19,44,59
+
+# Copy c-relay-pg source files LAST (only this layer rebuilds on source changes)
+COPY src/ /build/src/
+COPY Makefile /build/Makefile
+
+# Build c-relay-pg with full static linking (only rebuilds when src/ changes)
+# Disable fortification to avoid __*_chk symbols that don't exist in MUSL
+# Use conditional compilation flags based on DEBUG_BUILD and DB_BACKEND build args
+RUN if [ "$DEBUG_BUILD" = "true" ]; then \
+        CFLAGS="-g -O2 -DDEBUG"; \
+        STRIP_CMD="echo 'Keeping debug symbols'"; \
+        echo "Building with DEBUG symbols enabled (optimized with -O2)"; \
+    else \
+        CFLAGS="-O2"; \
+        STRIP_CMD="strip /build/c_relay_pg_static"; \
+        echo "Building optimized production binary (symbols stripped)"; \
+    fi && \
+    if [ "$DB_BACKEND" = "postgres" ]; then \
+        DB_FLAGS="-DDB_BACKEND_POSTGRES -DHAVE_LIBPQ"; \
+        DB_LIBS="-lpq -lpgcommon -lpgport"; \
+        echo "Compiling with PostgreSQL backend"; \
+    else \
+        DB_FLAGS=""; \
+        DB_LIBS=""; \
+        echo "Compiling with SQLite backend"; \
+    fi && \
+    gcc -static $CFLAGS $DB_FLAGS -Wall -Wextra -std=c99 \
+    -U_FORTIFY_SOURCE -D_FORTIFY_SOURCE=0 \
+    -I. -Ic_utils_lib/src -Inostr_core_lib -Inostr_core_lib/nostr_core \
+    -Inostr_core_lib/cjson -Inostr_core_lib/nostr_websocket -I/usr/include/postgresql \
+    src/main.c src/config.c src/dm_admin.c src/request_validator.c \
+    src/nip009.c src/nip011.c src/nip013.c src/nip040.c src/nip042.c \
+    src/websockets.c src/subscriptions.c src/api.c src/embedded_web_content.c src/ip_ban.c \
+    src/caching_inbox_poller.c src/caching_service_launcher.c \
+    src/db_ops.c src/db_ops_sqlite.c src/db_ops_postgres.c src/thread_pool.c \
+    -o /build/c_relay_pg_static \
+    c_utils_lib/libc_utils.a \
+    nostr_core_lib/libnostr_core_x64.a \
+    -lwebsockets -lssl -lcrypto -lsqlite3 -lsecp256k1 \
+    -lcurl -lz -lpthread -lm -ldl $DB_LIBS && \
+    eval "$STRIP_CMD"
+
+# Verify it's truly static
+RUN echo "=== Binary Information ===" && \
+    file /build/c_relay_pg_static && \
+    ls -lh /build/c_relay_pg_static && \
+    echo "=== Checking for dynamic dependencies ===" && \
+    (ldd /build/c_relay_pg_static 2>&1 || echo "Binary is static") && \
+    echo "=== Build complete ==="
+
+# Output stage - just the binary
+FROM scratch AS output
+COPY --from=builder /build/c_relay_pg_static /c_relay_pg_static

Makefile

@@ -1,27 +1,40 @@
-# C-Relay Makefile
+# C-Relay-PG Makefile
 
 CC = gcc
 CFLAGS = -Wall -Wextra -std=c99 -g -O2
-INCLUDES = -I. -Inostr_core_lib -Inostr_core_lib/nostr_core -Inostr_core_lib/cjson -Inostr_core_lib/nostr_websocket
-LIBS = -lsqlite3 -lwebsockets -lz -ldl -lpthread -lm -L/usr/local/lib -lsecp256k1 -lssl -lcrypto -L/usr/local/lib -lcurl
+INCLUDES = -I. -Ic_utils_lib/src -Inostr_core_lib -Inostr_core_lib/nostr_core -Inostr_core_lib/cjson -Inostr_core_lib/nostr_websocket -I/usr/include/postgresql
+LIBS = -lsqlite3 -lwebsockets -lz -ldl -lpthread -lm -L/usr/local/lib -lsecp256k1 -lssl -lcrypto -L/usr/local/lib -lcurl -Lc_utils_lib -lc_utils
+
+DB_BACKEND ?= sqlite
 
 # Build directory
 BUILD_DIR = build
 
 # Source files
-MAIN_SRC = src/main.c src/config.c
+MAIN_SRC = src/main.c src/config.c src/dm_admin.c src/request_validator.c src/nip009.c src/nip011.c src/nip013.c src/nip040.c src/nip042.c src/websockets.c src/subscriptions.c src/api.c src/embedded_web_content.c src/ip_ban.c src/thread_pool.c src/caching_inbox_poller.c src/caching_service_launcher.c
+DB_OPS_SRC = src/db_ops.c
+
+ifeq ($(DB_BACKEND),postgres)
+    CFLAGS += -DDB_BACKEND_POSTGRES -DHAVE_LIBPQ
+    DB_OPS_SRC += src/db_ops_postgres.c
+    LIBS += -lpq
+else
+    DB_OPS_SRC += src/db_ops_sqlite.c
+endif
+
 NOSTR_CORE_LIB = nostr_core_lib/libnostr_core_x64.a
+C_UTILS_LIB = c_utils_lib/libc_utils.a
 
 # Architecture detection
 ARCH = $(shell uname -m)
 ifeq ($(ARCH),x86_64)
-    TARGET = $(BUILD_DIR)/c_relay_x86
+    TARGET = $(BUILD_DIR)/c_relay_pg_x86
 else ifeq ($(ARCH),aarch64)
-    TARGET = $(BUILD_DIR)/c_relay_arm64
+    TARGET = $(BUILD_DIR)/c_relay_pg_arm64
 else ifeq ($(ARCH),arm64)
-    TARGET = $(BUILD_DIR)/c_relay_arm64
+    TARGET = $(BUILD_DIR)/c_relay_pg_arm64
 else
-    TARGET = $(BUILD_DIR)/c_relay_$(ARCH)
+    TARGET = $(BUILD_DIR)/c_relay_pg_$(ARCH)
 endif
 
 # Default target
@@ -32,73 +45,67 @@ $(BUILD_DIR):
 	mkdir -p $(BUILD_DIR)
 
 # Check if nostr_core_lib is built
+# Explicitly specify NIPs to ensure NIP-44 (encryption) is included
+# NIPs: 1 (basic), 6 (keys), 13 (PoW), 17 (DMs), 19 (bech32), 44 (encryption), 59 (gift wrap)
 $(NOSTR_CORE_LIB):
-	@echo "Building nostr_core_lib..."
-	cd nostr_core_lib && ./build.sh
+	@echo "Building nostr_core_lib with required NIPs (including NIP-44 for encryption)..."
+	cd nostr_core_lib && ./build.sh --nips=1,6,13,17,19,44,59
 
-# Generate version.h from git tags
-src/version.h:
-	@if [ -d .git ]; then \
-		echo "Generating version.h from git tags..."; \
-		VERSION=$$(git describe --tags --always --dirty 2>/dev/null || echo "unknown"); \
-		if echo "$$VERSION" | grep -q "^v[0-9]"; then \
-			CLEAN_VERSION=$$(echo "$$VERSION" | sed 's/^v//'); \
+# Check if c_utils_lib is built
+$(C_UTILS_LIB):
+	@echo "Building c_utils_lib..."
+	cd c_utils_lib && ./build.sh lib
+
+# Update main.h version information (requires main.h to exist)
+src/main.h:
+	@if [ ! -f src/main.h ]; then \
+		echo "ERROR: src/main.h not found!"; \
+		echo "Please ensure src/main.h exists with relay metadata."; \
+		echo "Copy from a backup or create manually with proper relay configuration."; \
+		exit 1; \
+	fi; \
+	if [ -d .git ]; then \
+		echo "Updating main.h version information from git tags..."; \
+		RAW_VERSION=$$(git describe --tags --always 2>/dev/null || echo "unknown"); \
+		if echo "$$RAW_VERSION" | grep -q "^v[0-9]"; then \
+			CLEAN_VERSION=$$(echo "$$RAW_VERSION" | sed 's/^v//' | cut -d- -f1); \
+			VERSION="v$$CLEAN_VERSION"; \
 			MAJOR=$$(echo "$$CLEAN_VERSION" | cut -d. -f1); \
 			MINOR=$$(echo "$$CLEAN_VERSION" | cut -d. -f2); \
-			PATCH=$$(echo "$$CLEAN_VERSION" | cut -d. -f3 | cut -d- -f1); \
+			PATCH=$$(echo "$$CLEAN_VERSION" | cut -d. -f3); \
 		else \
-			CLEAN_VERSION="0.0.0-$$VERSION"; \
+			VERSION="v0.0.0"; \
 			MAJOR=0; MINOR=0; PATCH=0; \
 		fi; \
-		echo "/* Auto-generated version information */" > src/version.h; \
-		echo "#ifndef VERSION_H" >> src/version.h; \
-		echo "#define VERSION_H" >> src/version.h; \
-		echo "" >> src/version.h; \
-		echo "#define VERSION \"$$VERSION\"" >> src/version.h; \
-		echo "#define VERSION_MAJOR $$MAJOR" >> src/version.h; \
-		echo "#define VERSION_MINOR $$MINOR" >> src/version.h; \
-		echo "#define VERSION_PATCH $$PATCH" >> src/version.h; \
-		echo "" >> src/version.h; \
-		echo "#endif /* VERSION_H */" >> src/version.h; \
-		echo "Generated version.h with version: $$VERSION"; \
-	elif [ ! -f src/version.h ]; then \
-		echo "Git not available and version.h missing, creating fallback version.h..."; \
-		VERSION="unknown"; \
-		echo "/* Auto-generated version information */" > src/version.h; \
-		echo "#ifndef VERSION_H" >> src/version.h; \
-		echo "#define VERSION_H" >> src/version.h; \
-		echo "" >> src/version.h; \
-		echo "#define VERSION \"$$VERSION\"" >> src/version.h; \
-		echo "#define VERSION_MAJOR 0" >> src/version.h; \
-		echo "#define VERSION_MINOR 0" >> src/version.h; \
-		echo "#define VERSION_PATCH 0" >> src/version.h; \
-		echo "" >> src/version.h; \
-		echo "#endif /* VERSION_H */" >> src/version.h; \
-		echo "Created fallback version.h with version: $$VERSION"; \
+		echo "Updating version information in existing main.h..."; \
+		sed -i "s/#define VERSION \".*\"/#define VERSION \"$$VERSION\"/g" src/main.h; \
+		sed -i "s/#define VERSION_MAJOR [0-9]*/#define VERSION_MAJOR $$MAJOR/g" src/main.h; \
+		sed -i "s/#define VERSION_MINOR [0-9]*/#define VERSION_MINOR $$MINOR/g" src/main.h; \
+		sed -i "s/#define VERSION_PATCH [0-9]*/#define VERSION_PATCH $$PATCH/g" src/main.h; \
+		echo "Updated main.h version to: $$VERSION"; \
 	else \
-		echo "Git not available, preserving existing version.h"; \
+		echo "Git not available, preserving existing main.h version information"; \
 	fi
 
-# Force version.h regeneration (useful for development)
+# Update main.h version information (requires existing main.h)
 force-version:
-	@echo "Force regenerating version.h..."
-	@rm -f src/version.h
-	@$(MAKE) src/version.h
+	@echo "Force updating main.h version information..."
+	@$(MAKE) src/main.h
 
 # Build the relay
-$(TARGET): $(BUILD_DIR) src/version.h $(MAIN_SRC) $(NOSTR_CORE_LIB)
-	@echo "Compiling C-Relay for architecture: $(ARCH)"
-	$(CC) $(CFLAGS) $(INCLUDES) $(MAIN_SRC) -o $(TARGET) $(NOSTR_CORE_LIB) $(LIBS)
+$(TARGET): $(BUILD_DIR) src/main.h src/sql_schema.h $(MAIN_SRC) $(DB_OPS_SRC) $(NOSTR_CORE_LIB) $(C_UTILS_LIB)
+	@echo "Compiling C-Relay-PG for architecture: $(ARCH) (backend: $(DB_BACKEND))"
+	$(CC) $(CFLAGS) $(INCLUDES) $(MAIN_SRC) $(DB_OPS_SRC) -o $(TARGET) $(NOSTR_CORE_LIB) $(C_UTILS_LIB) $(LIBS)
 	@echo "Build complete: $(TARGET)"
 
 # Build for specific architectures
-x86: $(BUILD_DIR) src/version.h $(MAIN_SRC) $(NOSTR_CORE_LIB)
-	@echo "Building C-Relay for x86_64..."
-	$(CC) $(CFLAGS) $(INCLUDES) $(MAIN_SRC) -o $(BUILD_DIR)/c_relay_x86 $(NOSTR_CORE_LIB) $(LIBS)
-	@echo "Build complete: $(BUILD_DIR)/c_relay_x86"
+x86: $(BUILD_DIR) src/main.h src/sql_schema.h $(MAIN_SRC) $(DB_OPS_SRC) $(NOSTR_CORE_LIB) $(C_UTILS_LIB)
+	@echo "Building C-Relay-PG for x86_64 (backend: $(DB_BACKEND))..."
+	$(CC) $(CFLAGS) $(INCLUDES) $(MAIN_SRC) $(DB_OPS_SRC) -o $(BUILD_DIR)/c_relay_pg_x86 $(NOSTR_CORE_LIB) $(C_UTILS_LIB) $(LIBS)
+	@echo "Build complete: $(BUILD_DIR)/c_relay_pg_x86"
 
-arm64: $(BUILD_DIR) src/version.h $(MAIN_SRC) $(NOSTR_CORE_LIB)
-	@echo "Cross-compiling C-Relay for ARM64..."
+arm64: $(BUILD_DIR) src/main.h src/sql_schema.h $(MAIN_SRC) $(DB_OPS_SRC) $(NOSTR_CORE_LIB) $(C_UTILS_LIB)
+	@echo "Cross-compiling C-Relay-PG for ARM64 (backend: $(DB_BACKEND))..."
 	@if ! command -v aarch64-linux-gnu-gcc >/dev/null 2>&1; then \
 		echo "ERROR: ARM64 cross-compiler not found."; \
 		echo "Install with: make install-cross-tools"; \
@@ -121,9 +128,9 @@ arm64: $(BUILD_DIR) src/version.h $(MAIN_SRC) $(NOSTR_CORE_LIB)
 	fi
 	@echo "Using aarch64-linux-gnu-gcc with ARM64 libraries..."
 	PKG_CONFIG_PATH=/usr/lib/aarch64-linux-gnu/pkgconfig:/usr/share/pkgconfig \
-	aarch64-linux-gnu-gcc $(CFLAGS) $(INCLUDES) $(MAIN_SRC) -o $(BUILD_DIR)/c_relay_arm64 $(NOSTR_CORE_LIB) \
+	aarch64-linux-gnu-gcc $(CFLAGS) $(INCLUDES) $(MAIN_SRC) $(DB_OPS_SRC) -o $(BUILD_DIR)/c_relay_pg_arm64 $(NOSTR_CORE_LIB) $(C_UTILS_LIB) \
 		-L/usr/lib/aarch64-linux-gnu $(LIBS)
-	@echo "Build complete: $(BUILD_DIR)/c_relay_arm64"
+	@echo "Build complete: $(BUILD_DIR)/c_relay_pg_arm64"
 
 # Install ARM64 cross-compilation dependencies
 install-arm64-deps:
@@ -161,20 +168,21 @@ test: $(TARGET)
 	@echo "Running tests..."
 	./tests/1_nip_test.sh
 
-# Initialize database
+# Initialize database (now handled automatically when server starts)
 init-db:
-	@echo "Initializing database..."
-	./db/init.sh --force
+	@echo "Database initialization is now handled automatically when the server starts."
+	@echo "The schema is embedded in the binary - no external files needed."
+	@echo "To manually recreate database: rm -f db/c_nostr_relay.db && ./build/c_relay_pg_x86"
 
 # Clean build artifacts
 clean:
 	rm -rf $(BUILD_DIR)
-	rm -f src/version.h
 	@echo "Clean complete"
 
-# Clean everything including nostr_core_lib
+# Clean everything including nostr_core_lib and c_utils_lib
 clean-all: clean
 	cd nostr_core_lib && make clean 2>/dev/null || true
+	cd c_utils_lib && make clean 2>/dev/null || true
 
 # Install dependencies (Ubuntu/Debian)
 install-deps:
@@ -184,7 +192,7 @@ install-deps:
 
 # Help
 help:
-	@echo "C-Relay Build System"
+	@echo "C-Relay-PG Build System"
 	@echo ""
 	@echo "Targets:"
 	@echo "  all              Build the relay for current architecture (default)"
@@ -208,6 +216,23 @@ help:
 	@echo "  make check-toolchain     # Check what compilers are available"
 	@echo "  make test                # Run tests"
 	@echo "  make init-db             # Set up database"
-	@echo "  make force-version       # Force regenerate version.h from git"
+	@echo "  make force-version       # Force regenerate main.h from git"
 
+# Build fully static MUSL binaries using Docker
+static-musl-x86_64:
+	@echo "Building fully static MUSL binary for x86_64..."
+	docker buildx build --platform linux/amd64 -f examples/deployment/static-builder.Dockerfile -t c-relay-pg-static-builder-x86_64 --load .
+	docker run --rm -v $(PWD)/build:/output c-relay-pg-static-builder-x86_64 sh -c "cp /c_relay_pg_static_musl_x86_64 /output/"
+	@echo "Static binary created: build/c_relay_pg_static_musl_x86_64"
+
+static-musl-arm64:
+	@echo "Building fully static MUSL binary for ARM64..."
+	docker buildx build --platform linux/arm64 -f examples/deployment/static-builder.Dockerfile -t c-relay-pg-static-builder-arm64 --load .
+	docker run --rm -v $(PWD)/build:/output c-relay-pg-static-builder-arm64 sh -c "cp /c_relay_pg_static_musl_x86_64 /output/c_relay_pg_static_musl_arm64"
+	@echo "Static binary created: build/c_relay_pg_static_musl_arm64"
+
+static-musl: static-musl-x86_64 static-musl-arm64
+	@echo "Built static MUSL binaries for both architectures"
+
+.PHONY: static-musl-x86_64 static-musl-arm64 static-musl
 .PHONY: all x86 arm64 test init-db clean clean-all install-deps install-cross-tools install-arm64-deps check-toolchain help force-version

NOSTR_RELEASE.md

@@ -0,0 +1,65 @@
+# Relay
+
+I am releasing the code for the nostr relay that I wrote use myself. The code is free for anyone to use in any way that they wish.
+
+Some of the features of this relay are conventional, and some are unconventional.
+
+## The conventional
+
+This relay is written in C99 with a sqlite database.
+
+It implements the following NIPs.
+
+- [x] NIP-01: Basic protocol flow implementation
+- [x] NIP-09: Event deletion
+- [x] NIP-11: Relay information document
+- [x] NIP-13: Proof of Work
+- [x] NIP-15: End of Stored Events Notice
+- [x] NIP-20: Command Results
+- [x] NIP-33: Parameterized Replaceable Events
+- [x] NIP-40: Expiration Timestamp
+- [x] NIP-42: Authentication of clients to relays
+- [x] NIP-45: Counting results
+- [x] NIP-50: Keywords filter
+- [x] NIP-70: Protected Events
+
+## The unconventional
+
+### The binaries are fully self contained.
+
+It should just run in linux without having to worry about what you have on your system. I want to download and run. No docker. No dependency hell.
+
+I'm not bothering with other operating systems.
+
+### The relay is a full nostr citizen with it's own public and private keys.
+
+For example, you can see my relay's profile (wss://relay.laantungir.net) running here:
+
+[Primal link](https://primal.net/p/nprofile1qqswn2jsmm8lq8evas0v9vhqkdpn9nuujt90mtz60nqgsxndy66es4qjjnhr7)
+
+What this means in practice is that when you start the relay, it generates keys for itself, and for it's administrator (You can specify these if you wish)
+
+Now the program and the administrator can have verifed communication between the two, simply by using nostr events. For example, the administrator can send DMs to the relay, asking it's status, and changing it's configuration through any client that can handle nip17 DMs. The relay can also send notifications to the administrator about it's current status, or it can publish it's status on a regular schedule directly to NOSTR as kind-1 notes.
+
+Also included is a more standard administrative web front end. This front end communicates to the relay using an extensive api, which again is nostr events signed by the administrator. You can completely control the relay through signed nostr events.
+
+## Screenshots
+
+![](https://git.laantungir.net/laantungir/c-relay-pg/raw/branch/master/screenshots/main.png)
+Main page with real time updates.
+
+![](https://git.laantungir.net/laantungir/c-relay-pg/raw/branch/master/screenshots/config.png)
+Set your configuration preferences.
+
+![](https://git.laantungir.net/laantungir/c-relay-pg/raw/branch/master/screenshots/subscriptions.png)
+View current subscriptions
+
+![](https://git.laantungir.net/laantungir/c-relay-pg/raw/branch/master/screenshots/white-blacklists.png)
+Add npubs to white or black lists.
+
+![](https://git.laantungir.net/laantungir/c-relay-pg/raw/branch/master/screenshots/sqlQuery.png)
+Run sql queries on the database.
+
+![](https://git.laantungir.net/laantungir/c-relay-pg/raw/branch/master/screenshots/main-light.png)
+Light mode.
+

README.md

@@ -1,22 +1,285 @@
-A nostr relay in C with sqlite on the back end.
+# C-Relay-PG: High-Performance Nostr Relay
 
-<!--
-NOTE FOR ASSISTANTS: When updating the NIPs checklist below, ONLY change [ ] to [x] to mark as complete.
-Do NOT modify the formatting, add emojis, or change the text. Keep the simple format consistent.
--->
+A blazingly fast, production-ready Nostr relay implemented in C with an innovative event-based configuration system. Built for performance, security, and ease of deployment.
 
+## 🚀 Why C-Relay-PG?
 
-### [NIPs](https://github.com/nostr-protocol/nips)
+### Event-Based Configuration
+Unlike traditional relays that require config files, C-Relay-PG uses **cryptographically signed Nostr events** for all configuration. This means:
+- **Zero config files** - Everything stored in the database
+- **Real-time updates** - Changes applied instantly without restart
+- **Cryptographic security** - All changes must be signed by admin
+- **Complete audit trail** - Every configuration change is timestamped and signed
+- **Version control built-in** - Configuration history is part of the event stream
 
-- [x] NIP-01: Basic protocol flow implementation
-- [x] NIP-09: Event deletion
-- [x] NIP-11: Relay information document
-- [x] NIP-13: Proof of Work
-- [x] NIP-15: End of Stored Events Notice
-- [x] NIP-20: Command Results
-- [x] NIP-33: Parameterized Replaceable Events
-- [x] NIP-40: Expiration Timestamp
-- [ ] NIP-42: Authentication of clients to relays
-- [ ] NIP-45: Counting results.
-- [ ] NIP-50: Keywords filter.
-- [ ] NIP-70: Protected Events
+### Built-in Web Admin Interface
+Access a full-featured web dashboard at `http://localhost:8888/api/` with:
+- Real-time configuration management
+- Database statistics and analytics
+- Auth rules management (whitelist/blacklist)
+- NIP-42 authentication for secure access
+- No external dependencies - all files embedded in the binary
+
+### Direct Message Admin System
+Control your relay by sending direct messages from any Nostr client:
+- Send "stats" to get relay statistics
+- Send "config" to view current configuration
+- Full Nostr citizen with its own keypair
+- Works with any NIP-17 compatible client
+
+### Performance & Efficiency
+- **Written in C** - Maximum performance and minimal resource usage
+- **SQLite backend** - Reliable, fast, and self-contained
+- **Static binary available** - Single file deployment with zero dependencies
+- **Efficient memory management** - Optimized for long-running operation
+- **WebSocket native** - Built on libwebsockets for optimal protocol support
+
+## 📋 Supported NIPs
+
+C-Relay-PG implements a comprehensive set of Nostr Improvement Proposals:
+
+- ✅ **NIP-01**: Basic protocol flow implementation
+- ✅ **NIP-09**: Event deletion
+- ✅ **NIP-11**: Relay information document
+- ✅ **NIP-13**: Proof of Work
+- ✅ **NIP-15**: End of Stored Events Notice
+- ✅ **NIP-20**: Command Results
+- ✅ **NIP-33**: Parameterized Replaceable Events
+- ✅ **NIP-40**: Expiration Timestamp
+- ✅ **NIP-42**: Authentication of clients to relays
+- ✅ **NIP-45**: Counting results
+- ✅ **NIP-50**: Keywords filter
+- ✅ **NIP-70**: Protected Events
+
+## 🎯 Key Features
+
+### Security
+- **NIP-42 Authentication** - Cryptographic client authentication
+- **Proof of Work** - Configurable PoW requirements (NIP-13)
+- **Protected Events** - Support for encrypted/protected content (NIP-70)
+- **Whitelist/Blacklist** - Flexible access control by pubkey
+- **Admin key security** - Private key shown only once, never stored
+
+### Flexibility
+- **Dynamic configuration** - Most settings update without restart
+- **Subscription management** - Configurable limits per client and globally
+- **Event expiration** - Automatic cleanup of expired events (NIP-40)
+- **Parameterized events** - Full support for replaceable events (NIP-33)
+- **Keyword search** - Built-in full-text search (NIP-50)
+
+### Monitoring
+- **Real-time statistics** - Live event distribution and metrics
+- **Subscription-based monitoring** - Ephemeral events (kind 24567) for dashboards
+- **SQL query API** - Direct database queries for advanced analytics
+- **Resource tracking** - CPU, memory, and database size monitoring
+- **Event broadcast logging** - Complete audit trail of all operations
+
+### Developer-Friendly
+- **Comprehensive test suite** - Automated tests for all NIPs
+- **Clear documentation** - Detailed guides for deployment and configuration
+- **SystemD integration** - Production-ready service files included
+- **Docker support** - Container deployment with Alpine Linux
+- **Cross-platform** - Builds on Linux, macOS, and Windows (WSL)
+
+## 🚀 Quick Start
+
+### Option 1: Static Binary (Recommended)
+
+Download and run - no dependencies required:
+
+```bash
+# Download the latest static release
+wget https://git.laantungir.net/laantungir/c-relay-pg/releases/download/v0.6.0/c-relay-pg-v0.6.0-linux-x86_64-static
+chmod +x c-relay-pg-v0.6.0-linux-x86_64-static
+mv c-relay-pg-v0.6.0-linux-x86_64-static c-relay-pg
+
+# Run the relay
+./c-relay-pg
+```
+
+**Important**: On first startup, save the **Admin Private Key** displayed in the console. You'll need it for all administrative operations.
+
+### Option 2: Build from Source
+
+```bash
+# Install dependencies (Ubuntu/Debian)
+sudo apt install -y build-essential git sqlite3 libsqlite3-dev \
+    libwebsockets-dev libssl-dev libsecp256k1-dev libcurl4-openssl-dev zlib1g-dev
+
+# Clone and build
+git clone https://github.com/your-org/c-relay-pg.git
+cd c-relay-pg
+git submodule update --init --recursive
+./make_and_restart_relay.sh
+```
+
+The relay will start on port 8888 (or the next available port).
+
+## 🌐 Access the Web Interface
+
+Once running, open your browser to:
+
+```
+http://localhost:8888/api/
+```
+
+The web interface provides:
+- Configuration management with live updates
+- Database statistics and event distribution charts
+- Auth rules management (whitelist/blacklist)
+- SQL query interface for advanced analytics
+- Real-time monitoring dashboard
+
+## 📦 Installation Options
+
+### Production Deployment (SystemD)
+
+```bash
+# Clone repository
+git clone https://github.com/your-org/c-relay-pg.git
+cd c-relay-pg
+git submodule update --init --recursive
+
+# Build
+make clean && make
+
+# Install as system service
+sudo systemd/install-service.sh
+
+# Start and enable
+sudo systemctl start c-relay-pg
+sudo systemctl enable c-relay-pg
+
+# Capture admin keys from logs
+sudo journalctl -u c-relay-pg | grep "Admin Private Key"
+```
+
+### Docker Deployment
+
+```bash
+# Build Docker image
+docker build -f Dockerfile.alpine-musl -t c-relay-pg .
+
+# Run container
+docker run -d \
+  --name c-relay-pg \
+  -p 8888:8888 \
+  -v /path/to/data:/data \
+  c-relay-pg
+```
+
+### Cloud Deployment
+
+Quick deployment scripts for popular cloud providers:
+
+```bash
+# AWS, GCP, DigitalOcean, etc.
+sudo examples/deployment/simple-vps/deploy.sh
+```
+
+See [`docs/deployment_guide.md`](docs/deployment_guide.md) for detailed deployment instructions.
+
+## 🔧 Configuration
+
+C-Relay-PG uses an innovative event-based configuration system. All settings are managed through signed Nostr events.
+
+### Basic Configuration
+
+Use the web interface at `http://localhost:8888/api/` or send admin commands via the API.
+
+### Common Settings
+
+- **Relay Information**: Name, description, contact info
+- **Connection Limits**: Max subscriptions per client, total subscriptions
+- **Authentication**: Enable/disable NIP-42, whitelist/blacklist rules
+- **Proof of Work**: Minimum difficulty, enforcement mode
+- **Event Validation**: Max tags, content length, message size
+- **Expiration**: Enable/disable NIP-40 event expiration
+
+### Dynamic Updates
+
+Most configuration changes take effect immediately without restart:
+- Relay information (NIP-11)
+- Authentication settings
+- Subscription limits
+- Event validation rules
+- Proof of Work settings
+
+See [`docs/configuration_guide.md`](docs/configuration_guide.md) for complete configuration reference.
+
+## 📚 Documentation
+
+- **[API Documentation](API.md)** - Complete API reference and advanced features
+- **[Configuration Guide](docs/configuration_guide.md)** - Detailed configuration options
+- **[Deployment Guide](docs/deployment_guide.md)** - Production deployment instructions
+- **[User Guide](docs/user_guide.md)** - End-user documentation
+- **[NIP-42 Authentication](docs/NIP-42_Authentication.md)** - Authentication setup guide
+
+## 🧪 Testing
+
+Run the comprehensive test suite:
+
+```bash
+# Run all tests
+./tests/run_all_tests.sh
+
+# Run NIP-specific tests
+./tests/run_nip_tests.sh
+
+# Test specific NIPs
+./tests/42_nip_test.sh  # NIP-42 authentication
+./tests/13_nip_test.sh  # NIP-13 proof of work
+```
+
+## 🔒 Security
+
+### Admin Key Management
+
+The admin private key is displayed **only once** during first startup. Store it securely:
+
+```bash
+# Save to secure location
+echo "ADMIN_PRIVKEY=your_admin_private_key" > ~/.c-relay-pg-admin
+chmod 600 ~/.c-relay-pg-admin
+```
+
+### Production Security
+
+- Use HTTPS/WSS with reverse proxy (nginx/Apache)
+- Enable NIP-42 authentication for client verification
+- Configure whitelist/blacklist for access control
+- Set up firewall rules to restrict access
+- Enable Proof of Work to prevent spam
+- Regular database backups
+
+See [`docs/deployment_guide.md`](docs/deployment_guide.md#security-hardening) for security hardening guide.
+
+## 🤝 Contributing
+
+Contributions are welcome! Please:
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes with tests
+4. Submit a pull request
+
+## 📄 License
+
+[Add your license here]
+
+## 🔗 Links
+
+- **Repository**: [https://github.com/your-org/c-relay-pg](https://github.com/your-org/c-relay-pg)
+- **Releases**: [https://git.laantungir.net/laantungir/c-relay-pg/releases](https://git.laantungir.net/laantungir/c-relay-pg/releases)
+- **Issues**: [https://github.com/your-org/c-relay-pg/issues](https://github.com/your-org/c-relay-pg/issues)
+- **Nostr Protocol**: [https://github.com/nostr-protocol/nostr](https://github.com/nostr-protocol/nostr)
+
+## 💬 Support
+
+- Open an issue on GitHub
+- Join the Nostr community
+- Contact via Nostr DM (relay pubkey shown on startup)
+
+---
+
+**Built with ❤️ for the Nostr protocol**

Real-Time Traffic Monitoring Commands.md

@@ -0,0 +1,174 @@
+# Real-Time Traffic Monitoring Commands (Direct Server Use)
+
+Copy and paste these commands directly on your server.
+
+## Quick Status Checks
+
+### See IPs visiting in the last few minutes:
+```bash
+sudo tail -500 /var/log/nginx/access.log | awk '{print $1}' | sort | uniq -c | sort -rn | head -20
+```
+
+### See what status codes they're getting:
+```bash
+sudo tail -500 /var/log/nginx/access.log | awk '{print $1, $9}' | grep '216.73.216.38'
+```
+
+### Count status codes (200 vs 403):
+```bash
+sudo tail -500 /var/log/nginx/access.log | awk '{print $9}' | sort | uniq -c
+```
+
+## Real-Time Monitoring
+
+### Watch live traffic (updates every 2 seconds):
+```bash
+watch -n 2 'sudo tail -200 /var/log/nginx/access.log | awk "{print \$1}" | sort | uniq -c | sort -rn | head -15'
+```
+
+### See live log entries as they happen:
+```bash
+sudo tail -f /var/log/nginx/access.log
+```
+
+### Live GoAccess dashboard:
+```bash
+sudo tail -f /var/log/nginx/access.log | goaccess -
+```
+
+## Active Connections
+
+### See who's connected RIGHT NOW:
+```bash
+sudo netstat -tn | grep ':443' | awk '{print $5}' | cut -d: -f1 | sort | uniq -c | sort -rn
+```
+
+### Alternative (using ss command):
+```bash
+sudo ss -tn | grep ':443' | awk '{print $5}' | cut -d: -f1 | sort | uniq -c | sort -rn
+```
+
+## Detailed Analysis
+
+### Last 100 requests with timestamps:
+```bash
+sudo tail -100 /var/log/nginx/access.log | awk '{print $4, $1}' | sed 's/\[//'
+```
+
+### See what blocked IPs are trying to access:
+```bash
+sudo tail -500 /var/log/nginx/access.log | grep '216.73.216.38' | awk '{print $7}' | head -10
+```
+
+### Show all 403 (blocked) requests:
+```bash
+sudo tail -500 /var/log/nginx/access.log | awk '$9==403 {print $1}' | sort | uniq -c | sort -rn
+```
+
+### Show all successful (200) requests:
+```bash
+sudo tail -500 /var/log/nginx/access.log | awk '$9==200 {print $1}' | sort | uniq -c | sort -rn | head -10
+```
+
+## Comprehensive Monitoring Script
+
+### Create a monitoring script:
+```bash
+cat > /tmp/monitor-traffic.sh << 'EOF'
+#!/bin/bash
+echo "=== Traffic in last 5 minutes ==="
+echo "Time: $(date)"
+echo ""
+echo "Top IPs:"
+sudo tail -1000 /var/log/nginx/access.log | awk '{print $1}' | sort | uniq -c | sort -rn | head -10
+echo ""
+echo "Blocked IPs (403 errors):"
+sudo tail -1000 /var/log/nginx/access.log | awk '$9==403 {print $1}' | sort | uniq -c | sort -rn
+echo ""
+echo "Successful requests (200):"
+sudo tail -1000 /var/log/nginx/access.log | awk '$9==200 {print $1}' | sort | uniq -c | sort -rn | head -5
+echo ""
+echo "Status Code Summary:"
+sudo tail -1000 /var/log/nginx/access.log | awk '{print $9}' | sort | uniq -c | sort -rn
+EOF
+chmod +x /tmp/monitor-traffic.sh
+```
+
+### Run the monitoring script:
+```bash
+/tmp/monitor-traffic.sh
+```
+
+## Auto-Refreshing Dashboard
+
+### Live dashboard (refreshes every 5 seconds):
+```bash
+watch -n 5 'echo "=== Last 5 minutes ==="
+date
+echo ""
+echo "Top IPs:"
+sudo tail -1000 /var/log/nginx/access.log | awk "{print \$1}" | sort | uniq -c | sort -rn | head -10
+echo ""
+echo "Status Codes:"
+sudo tail -1000 /var/log/nginx/access.log | awk "{print \$9}" | sort | uniq -c | sort -rn'
+```
+
+Press `Ctrl+C` to exit.
+
+## GoAccess HTML Report (Live Updating)
+
+### Generate live HTML report:
+```bash
+sudo goaccess /var/log/nginx/access.log -o /var/www/html/live-stats.html --real-time-html --daemonize
+```
+
+Then visit: https://git.laantungir.net/live-stats.html
+
+### Stop the live report:
+```bash
+sudo pkill -f "goaccess.*live-stats"
+```
+
+## Filter by Time
+
+### Get timestamp from 5 minutes ago:
+```bash
+date -d '5 minutes ago' '+%d/%b/%Y:%H:%M'
+```
+
+### Analyze only recent logs (replace timestamp):
+```bash
+sudo awk '/01\/Feb\/2026:19:09/,0' /var/log/nginx/access.log | goaccess -
+```
+
+## Check Gitea CPU
+
+### Current CPU usage:
+```bash
+ps aux | grep gitea | grep -v grep
+```
+
+### Watch CPU in real-time:
+```bash
+watch -n 2 'ps aux | grep gitea | grep -v grep'
+```
+
+## Most Useful Command for Quick Check
+
+This one-liner shows everything you need:
+```bash
+
+echo "=== Quick Status ===" && \
+echo "Time: $(date)" && \
+echo "" && \
+echo "Top 10 IPs (last 1000 requests):" && \
+sudo tail -1000 /var/log/nginx/access.log | awk '{print $1}' | sort | uniq -c | sort -rn | head -10 && \
+echo "" && \
+echo "Status Codes:" && \
+sudo tail -1000 /var/log/nginx/access.log | awk '{print $9}' | sort | uniq -c && \
+echo "" && \
+echo "Gitea CPU:" && \
+ps aux | grep gitea | grep -v grep
+```
+
+Copy any of these commands and run them directly on your server!

STATIC_MUSL_GUIDE.md

@@ -0,0 +1,612 @@
+# Static MUSL Build Guide for C Programs
+
+## Overview
+
+This guide explains how to build truly portable static binaries using Alpine Linux and MUSL libc. These binaries have **zero runtime dependencies** and work on any Linux distribution without modification.
+
+This guide is specifically tailored for C programs that use:
+- **nostr_core_lib** - Nostr protocol implementation
+- **nostr_login_lite** - Nostr authentication library
+- Common dependencies: libwebsockets, OpenSSL, SQLite, curl, secp256k1
+
+## Why MUSL Static Binaries?
+
+### Advantages Over glibc
+
+| Feature | MUSL Static | glibc Static | glibc Dynamic |
+|---------|-------------|--------------|---------------|
+| **Portability** | ✓ Any Linux | ⚠ glibc only | ✗ Requires matching libs |
+| **Binary Size** | ~7-10 MB | ~12-15 MB | ~2-3 MB |
+| **Dependencies** | None | NSS libs | Many system libs |
+| **Deployment** | Single file | Single file + NSS | Binary + libraries |
+| **Compatibility** | Universal | glibc version issues | Library version hell |
+
+### Key Benefits
+
+1. **True Portability**: Works on Alpine, Ubuntu, Debian, CentOS, Arch, etc.
+2. **No Library Hell**: No `GLIBC_2.XX not found` errors
+3. **Simple Deployment**: Just copy one file
+4. **Reproducible Builds**: Same Docker image = same binary
+5. **Security**: No dependency on system libraries with vulnerabilities
+
+## Quick Start
+
+### Prerequisites
+
+- Docker installed and running
+- Your C project with source code
+- Internet connection for downloading dependencies
+
+### Basic Build Process
+
+```bash
+# 1. Copy the Dockerfile template (see below)
+cp /path/to/c-relay-pg/Dockerfile.alpine-musl ./Dockerfile.static
+
+# 2. Customize for your project (see Customization section)
+vim Dockerfile.static
+
+# 3. Build the static binary
+docker build --platform linux/amd64 -f Dockerfile.static -t my-app-builder .
+
+# 4. Extract the binary
+docker create --name temp-container my-app-builder
+docker cp temp-container:/build/my_app_static ./my_app_static
+docker rm temp-container
+
+# 5. Verify it's static
+ldd ./my_app_static  # Should show "not a dynamic executable"
+```
+
+## Dockerfile Template
+
+Here's a complete Dockerfile template you can customize for your project:
+
+```dockerfile
+# Alpine-based MUSL static binary builder
+# Produces truly portable binaries with zero runtime dependencies
+
+FROM alpine:3.19 AS builder
+
+# Install build dependencies
+RUN apk add --no-cache \
+    build-base \
+    musl-dev \
+    git \
+    cmake \
+    pkgconfig \
+    autoconf \
+    automake \
+    libtool \
+    openssl-dev \
+    openssl-libs-static \
+    zlib-dev \
+    zlib-static \
+    curl-dev \
+    curl-static \
+    sqlite-dev \
+    sqlite-static \
+    linux-headers \
+    wget \
+    bash
+
+WORKDIR /build
+
+# Build libsecp256k1 static (required for Nostr)
+RUN cd /tmp && \
+    git clone https://github.com/bitcoin-core/secp256k1.git && \
+    cd secp256k1 && \
+    ./autogen.sh && \
+    ./configure --enable-static --disable-shared --prefix=/usr \
+        CFLAGS="-fPIC" && \
+    make -j$(nproc) && \
+    make install && \
+    rm -rf /tmp/secp256k1
+
+# Build libwebsockets static (if needed for WebSocket support)
+RUN cd /tmp && \
+    git clone --depth 1 --branch v4.3.3 https://github.com/warmcat/libwebsockets.git && \
+    cd libwebsockets && \
+    mkdir build && cd build && \
+    cmake .. \
+        -DLWS_WITH_STATIC=ON \
+        -DLWS_WITH_SHARED=OFF \
+        -DLWS_WITH_SSL=ON \
+        -DLWS_WITHOUT_TESTAPPS=ON \
+        -DLWS_WITHOUT_TEST_SERVER=ON \
+        -DLWS_WITHOUT_TEST_CLIENT=ON \
+        -DLWS_WITHOUT_TEST_PING=ON \
+        -DLWS_WITH_HTTP2=OFF \
+        -DLWS_WITH_LIBUV=OFF \
+        -DLWS_WITH_LIBEVENT=OFF \
+        -DLWS_IPV6=ON \
+        -DCMAKE_BUILD_TYPE=Release \
+        -DCMAKE_INSTALL_PREFIX=/usr \
+        -DCMAKE_C_FLAGS="-fPIC" && \
+    make -j$(nproc) && \
+    make install && \
+    rm -rf /tmp/libwebsockets
+
+# Copy git configuration for submodules
+COPY .gitmodules /build/.gitmodules
+COPY .git /build/.git
+
+# Initialize submodules
+RUN git submodule update --init --recursive
+
+# Copy and build nostr_core_lib
+COPY nostr_core_lib /build/nostr_core_lib/
+RUN cd nostr_core_lib && \
+    chmod +x build.sh && \
+    sed -i 's/CFLAGS="-Wall -Wextra -std=c99 -fPIC -O2"/CFLAGS="-U_FORTIFY_SOURCE -D_FORTIFY_SOURCE=0 -Wall -Wextra -std=c99 -fPIC -O2"/' build.sh && \
+    rm -f *.o *.a 2>/dev/null || true && \
+    ./build.sh --nips=1,6,13,17,19,44,59
+
+# Copy and build nostr_login_lite (if used)
+# COPY nostr_login_lite /build/nostr_login_lite/
+# RUN cd nostr_login_lite && make static
+
+# Copy your application source
+COPY src/ /build/src/
+COPY Makefile /build/Makefile
+
+# Build your application with full static linking
+RUN gcc -static -O2 -Wall -Wextra -std=c99 \
+    -U_FORTIFY_SOURCE -D_FORTIFY_SOURCE=0 \
+    -I. -Inostr_core_lib -Inostr_core_lib/nostr_core \
+    -Inostr_core_lib/cjson -Inostr_core_lib/nostr_websocket \
+    src/*.c \
+    -o /build/my_app_static \
+    nostr_core_lib/libnostr_core_x64.a \
+    -lwebsockets -lssl -lcrypto -lsqlite3 -lsecp256k1 \
+    -lcurl -lz -lpthread -lm -ldl && \
+    strip /build/my_app_static
+
+# Verify it's truly static
+RUN echo "=== Binary Information ===" && \
+    file /build/my_app_static && \
+    ls -lh /build/my_app_static && \
+    echo "=== Checking for dynamic dependencies ===" && \
+    (ldd /build/my_app_static 2>&1 || echo "Binary is static")
+
+# Output stage - just the binary
+FROM scratch AS output
+COPY --from=builder /build/my_app_static /my_app_static
+```
+
+## Customization Guide
+
+### 1. Adjust Dependencies
+
+**Add dependencies** by modifying the `apk add` section:
+
+```dockerfile
+RUN apk add --no-cache \
+    build-base \
+    musl-dev \
+    # Add your dependencies here:
+    libpng-dev \
+    libpng-static \
+    libjpeg-turbo-dev \
+    libjpeg-turbo-static
+```
+
+**Remove unused dependencies** to speed up builds:
+- Remove `libwebsockets` section if you don't need WebSocket support
+- Remove `sqlite` if you don't use databases
+- Remove `curl` if you don't make HTTP requests
+
+### 2. Configure nostr_core_lib NIPs
+
+Specify which NIPs your application needs:
+
+```bash
+./build.sh --nips=1,6,19  # Minimal: Basic protocol, keys, bech32
+./build.sh --nips=1,6,13,17,19,44,59  # Full: All common NIPs
+./build.sh --nips=all  # Everything available
+```
+
+**Common NIP combinations:**
+- **Basic client**: `1,6,19` (events, keys, bech32)
+- **With encryption**: `1,6,19,44` (add modern encryption)
+- **With DMs**: `1,6,17,19,44,59` (add private messages)
+- **Relay/server**: `1,6,13,17,19,42,44,59` (add PoW, auth)
+
+### 3. Modify Compilation Flags
+
+**For your application:**
+
+```dockerfile
+RUN gcc -static -O2 -Wall -Wextra -std=c99 \
+    -U_FORTIFY_SOURCE -D_FORTIFY_SOURCE=0 \  # REQUIRED for MUSL
+    -I. -Inostr_core_lib \                    # Include paths
+    src/*.c \                                  # Your source files
+    -o /build/my_app_static \                 # Output binary
+    nostr_core_lib/libnostr_core_x64.a \     # Nostr library
+    -lwebsockets -lssl -lcrypto \             # Link libraries
+    -lsqlite3 -lsecp256k1 -lcurl \
+    -lz -lpthread -lm -ldl
+```
+
+**Debug build** (with symbols, no optimization):
+
+```dockerfile
+RUN gcc -static -g -O0 -DDEBUG \
+    -U_FORTIFY_SOURCE -D_FORTIFY_SOURCE=0 \
+    # ... rest of flags
+```
+
+### 4. Multi-Architecture Support
+
+Build for different architectures:
+
+```bash
+# x86_64 (Intel/AMD)
+docker build --platform linux/amd64 -f Dockerfile.static -t my-app-x86 .
+
+# ARM64 (Apple Silicon, Raspberry Pi 4+)
+docker build --platform linux/arm64 -f Dockerfile.static -t my-app-arm64 .
+```
+
+## Build Script Template
+
+Create a `build_static.sh` script for convenience:
+
+```bash
+#!/bin/bash
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+BUILD_DIR="$SCRIPT_DIR/build"
+DOCKERFILE="$SCRIPT_DIR/Dockerfile.static"
+
+# Detect architecture
+ARCH=$(uname -m)
+case "$ARCH" in
+    x86_64)
+        PLATFORM="linux/amd64"
+        OUTPUT_NAME="my_app_static_x86_64"
+        ;;
+    aarch64|arm64)
+        PLATFORM="linux/arm64"
+        OUTPUT_NAME="my_app_static_arm64"
+        ;;
+    *)
+        echo "Unknown architecture: $ARCH"
+        exit 1
+        ;;
+esac
+
+echo "Building for platform: $PLATFORM"
+mkdir -p "$BUILD_DIR"
+
+# Build Docker image
+docker build \
+    --platform "$PLATFORM" \
+    -f "$DOCKERFILE" \
+    -t my-app-builder:latest \
+    --progress=plain \
+    .
+
+# Extract binary
+CONTAINER_ID=$(docker create my-app-builder:latest)
+docker cp "$CONTAINER_ID:/build/my_app_static" "$BUILD_DIR/$OUTPUT_NAME"
+docker rm "$CONTAINER_ID"
+
+chmod +x "$BUILD_DIR/$OUTPUT_NAME"
+
+echo "✓ Build complete: $BUILD_DIR/$OUTPUT_NAME"
+echo "✓ Size: $(du -h "$BUILD_DIR/$OUTPUT_NAME" | cut -f1)"
+
+# Verify
+if ldd "$BUILD_DIR/$OUTPUT_NAME" 2>&1 | grep -q "not a dynamic executable"; then
+    echo "✓ Binary is fully static"
+else
+    echo "⚠ Warning: Binary may have dynamic dependencies"
+fi
+```
+
+Make it executable:
+
+```bash
+chmod +x build_static.sh
+./build_static.sh
+```
+
+## Common Issues and Solutions
+
+### Issue 1: Fortification Errors
+
+**Error:**
+```
+undefined reference to '__snprintf_chk'
+undefined reference to '__fprintf_chk'
+```
+
+**Cause**: GCC's `-O2` enables fortification by default, which uses glibc-specific functions.
+
+**Solution**: Add these flags to **all** compilation commands:
+```bash
+-U_FORTIFY_SOURCE -D_FORTIFY_SOURCE=0
+```
+
+This must be applied to:
+1. nostr_core_lib build.sh
+2. Your application compilation
+3. Any other libraries you build
+
+### Issue 2: Missing Symbols from nostr_core_lib
+
+**Error:**
+```
+undefined reference to 'nostr_create_event'
+undefined reference to 'nostr_sign_event'
+```
+
+**Cause**: Required NIPs not included in nostr_core_lib build.
+
+**Solution**: Add missing NIPs:
+```bash
+./build.sh --nips=1,6,19  # Add the NIPs you need
+```
+
+### Issue 3: Docker Permission Denied
+
+**Error:**
+```
+permission denied while trying to connect to the Docker daemon socket
+```
+
+**Solution**:
+```bash
+sudo usermod -aG docker $USER
+newgrp docker  # Or logout and login
+```
+
+### Issue 4: Binary Won't Run on Target System
+
+**Checks**:
+```bash
+# 1. Verify it's static
+ldd my_app_static  # Should show "not a dynamic executable"
+
+# 2. Check architecture
+file my_app_static  # Should match target system
+
+# 3. Test on different distributions
+docker run --rm -v $(pwd):/app alpine:latest /app/my_app_static --version
+docker run --rm -v $(pwd):/app ubuntu:latest /app/my_app_static --version
+```
+
+## Project Structure Example
+
+Organize your project for easy static builds:
+
+```
+my-nostr-app/
+├── src/
+│   ├── main.c
+│   ├── handlers.c
+│   └── utils.c
+├── nostr_core_lib/          # Git submodule
+├── nostr_login_lite/        # Git submodule (if used)
+├── Dockerfile.static        # Static build Dockerfile
+├── build_static.sh          # Build script
+├── Makefile                 # Regular build
+└── README.md
+```
+
+### Makefile Integration
+
+Add static build targets to your Makefile:
+
+```makefile
+# Regular dynamic build
+all: my_app
+
+my_app: src/*.c
+	gcc -O2 src/*.c -o my_app \
+		nostr_core_lib/libnostr_core_x64.a \
+		-lssl -lcrypto -lsecp256k1 -lz -lpthread -lm
+
+# Static MUSL build via Docker
+static:
+	./build_static.sh
+
+# Clean
+clean:
+	rm -f my_app build/my_app_static_*
+
+.PHONY: all static clean
+```
+
+## Deployment
+
+### Single Binary Deployment
+
+```bash
+# Copy to server
+scp build/my_app_static_x86_64 user@server:/opt/my-app/
+
+# Run (no dependencies needed!)
+ssh user@server
+/opt/my-app/my_app_static_x86_64
+```
+
+### SystemD Service
+
+```ini
+[Unit]
+Description=My Nostr Application
+After=network.target
+
+[Service]
+Type=simple
+User=myapp
+WorkingDirectory=/opt/my-app
+ExecStart=/opt/my-app/my_app_static_x86_64
+Restart=always
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target
+```
+
+### Docker Container (Minimal)
+
+```dockerfile
+FROM scratch
+COPY my_app_static_x86_64 /app
+ENTRYPOINT ["/app"]
+```
+
+Build and run:
+```bash
+docker build -t my-app:latest .
+docker run --rm my-app:latest --help
+```
+
+## Reusing c-relay-pg Files
+
+You can directly copy these files from c-relay-pg:
+
+### 1. Dockerfile.alpine-musl
+```bash
+cp /path/to/c-relay-pg/Dockerfile.alpine-musl ./Dockerfile.static
+```
+
+Then customize:
+- Change binary name (line 125)
+- Adjust source files (line 122-124)
+- Modify include paths (line 120-121)
+
+### 2. build_static.sh
+```bash
+cp /path/to/c-relay-pg/build_static.sh ./
+```
+
+Then customize:
+- Change `OUTPUT_NAME` variable (lines 66, 70)
+- Update Docker image name (line 98)
+- Modify verification commands (lines 180-184)
+
+### 3. .dockerignore (Optional)
+```bash
+cp /path/to/c-relay-pg/.dockerignore ./
+```
+
+Helps speed up Docker builds by excluding unnecessary files.
+
+## Best Practices
+
+1. **Version Control**: Commit your Dockerfile and build script
+2. **Tag Builds**: Include git commit hash in binary version
+3. **Test Thoroughly**: Verify on multiple distributions
+4. **Document Dependencies**: List required NIPs and libraries
+5. **Automate**: Use CI/CD to build on every commit
+6. **Archive Binaries**: Keep old versions for rollback
+
+## Performance Comparison
+
+| Metric | MUSL Static | glibc Dynamic |
+|--------|-------------|---------------|
+| Binary Size | 7-10 MB | 2-3 MB + libs |
+| Startup Time | ~50ms | ~40ms |
+| Memory Usage | Similar | Similar |
+| Portability | ✓ Universal | ✗ System-dependent |
+| Deployment | Single file | Binary + libraries |
+
+## References
+
+- [MUSL libc](https://musl.libc.org/)
+- [Alpine Linux](https://alpinelinux.org/)
+- [nostr_core_lib](https://github.com/chebizarro/nostr_core_lib)
+- [Static Linking Best Practices](https://www.musl-libc.org/faq.html)
+- [c-relay-pg Implementation](./docs/musl_static_build.md)
+
+## Example: Minimal Nostr Client
+
+Here's a complete example of building a minimal Nostr client:
+
+```c
+// minimal_client.c
+#include "nostr_core/nostr_core.h"
+#include <stdio.h>
+
+int main() {
+    // Generate keypair
+    char nsec[64], npub[64];
+    nostr_generate_keypair(nsec, npub);
+    
+    printf("Generated keypair:\n");
+    printf("Private key (nsec): %s\n", nsec);
+    printf("Public key (npub): %s\n", npub);
+    
+    // Create event
+    cJSON *event = nostr_create_event(1, "Hello, Nostr!", NULL);
+    nostr_sign_event(event, nsec);
+    
+    char *json = cJSON_Print(event);
+    printf("\nSigned event:\n%s\n", json);
+    
+    free(json);
+    cJSON_Delete(event);
+    return 0;
+}
+```
+
+**Dockerfile.static:**
+```dockerfile
+FROM alpine:3.19 AS builder
+RUN apk add --no-cache build-base musl-dev git autoconf automake libtool \
+    openssl-dev openssl-libs-static zlib-dev zlib-static
+
+WORKDIR /build
+
+# Build secp256k1
+RUN cd /tmp && git clone https://github.com/bitcoin-core/secp256k1.git && \
+    cd secp256k1 && ./autogen.sh && \
+    ./configure --enable-static --disable-shared --prefix=/usr CFLAGS="-fPIC" && \
+    make -j$(nproc) && make install
+
+# Copy and build nostr_core_lib
+COPY nostr_core_lib /build/nostr_core_lib/
+RUN cd nostr_core_lib && \
+    sed -i 's/CFLAGS="-Wall/CFLAGS="-U_FORTIFY_SOURCE -D_FORTIFY_SOURCE=0 -Wall/' build.sh && \
+    ./build.sh --nips=1,6,19
+
+# Build application
+COPY minimal_client.c /build/
+RUN gcc -static -O2 -Wall -std=c99 \
+    -U_FORTIFY_SOURCE -D_FORTIFY_SOURCE=0 \
+    -Inostr_core_lib -Inostr_core_lib/nostr_core -Inostr_core_lib/cjson \
+    minimal_client.c -o /build/minimal_client_static \
+    nostr_core_lib/libnostr_core_x64.a \
+    -lssl -lcrypto -lsecp256k1 -lz -lpthread -lm -ldl && \
+    strip /build/minimal_client_static
+
+FROM scratch
+COPY --from=builder /build/minimal_client_static /minimal_client_static
+```
+
+**Build and run:**
+```bash
+docker build -f Dockerfile.static -t minimal-client .
+docker create --name temp minimal-client
+docker cp temp:/minimal_client_static ./
+docker rm temp
+
+./minimal_client_static
+```
+
+## Conclusion
+
+Static MUSL binaries provide the best portability for C applications. While they're slightly larger than dynamic binaries, the benefits of zero dependencies and universal compatibility make them ideal for:
+
+- Server deployments across different Linux distributions
+- Embedded systems and IoT devices
+- Docker containers (FROM scratch)
+- Distribution to users without dependency management
+- Long-term archival and reproducibility
+
+Follow this guide to create portable, self-contained binaries for your Nostr applications!

admin/api/auth.php

@@ -0,0 +1,37 @@
+<?php
+/** admin2/api/auth.php — Auth rules + WoT status. */
+require_once __DIR__ . '/../lib/helpers.php';
+$pdo = db();
+
+if ($_SERVER['REQUEST_METHOD'] === 'POST') {
+    $input = json_decode(file_get_contents('php://input'), true);
+    $action = $input['action'] ?? '';
+    try {
+        if ($action === 'add') {
+            $pdo->prepare("INSERT INTO auth_rules (rule_type, pattern_type, pattern_value) VALUES (?, 'pubkey', ?)")->execute([$input['rule_type'], $input['pattern_value']]);
+            json_response(['message' => 'Rule added']);
+        } elseif ($action === 'remove') {
+            $pdo->prepare("DELETE FROM auth_rules WHERE id = ?")->execute([intval($input['id'])]);
+            json_response(['message' => 'Rule removed']);
+        } elseif ($action === 'set_wot_level') {
+            $pdo->prepare("UPDATE config SET value = ? WHERE key = 'wot_level'")->execute([strval($input['level'])]);
+            json_response(['message' => 'WoT level set']);
+        } elseif ($action === 'sync_wot') {
+            json_response(['message' => 'WoT sync not available via PHP (requires relay)']);
+        }
+    } catch (PDOException $e) { json_response(['error' => $e->getMessage()]); }
+}
+
+// GET: WoT status
+if (isset($_GET['action']) && $_GET['action'] === 'wot') {
+    $level = $pdo->query("SELECT value FROM config WHERE key = 'wot_level'")->fetchColumn() ?: '0';
+    $wl_count = 0;
+    try { $wl_count = intval($pdo->query("SELECT count(*) FROM auth_rules WHERE rule_type = 'whitelist'")->fetchColumn()); } catch (PDOException $e) {}
+    $descriptions = ['0' => 'Level 0: Open relay — anyone can read and write', '1' => 'Level 1: Write only — WoT users can write', '2' => 'Level 2: Full — WoT users only'];
+    json_response(['kind3_status' => 'N/A (PHP admin)', 'whitelist_count' => $wl_count, 'level_description' => $descriptions[$level] ?? $descriptions['0']]);
+}
+
+// GET: auth rules
+$rules = [];
+try { $rules = $pdo->query("SELECT id, rule_type, pattern_type, pattern_value FROM auth_rules ORDER BY id")->fetchAll(); } catch (PDOException $e) {}
+json_response(['rules' => $rules]);

admin/api/caching.php

@@ -0,0 +1,123 @@
+<?php
+/** admin2/api/caching.php — Caching service status + follows + reset actions. */
+require_once __DIR__ . '/../lib/helpers.php';
+$pdo = db();
+
+// --- POST actions: reset backfill (all or per-user) ---
+if ($_SERVER['REQUEST_METHOD'] === 'POST') {
+    $input = json_decode(file_get_contents('php://input'), true) ?: [];
+    $action = $input['action'] ?? '';
+    $pubkey = $input['pubkey'] ?? '';
+
+    if ($action === 'reset_all') {
+        // Reset backfill progress for ALL followed authors, then bump config
+        // generation so the running caching service hot-reloads and re-drains.
+        try {
+            $pdo->beginTransaction();
+            $pdo->exec("UPDATE caching_followed_pubkeys
+                        SET until_cursor = 0, backfill_complete = FALSE,
+                            events_fetched = 0,
+                            updated_at = EXTRACT(EPOCH FROM NOW())::BIGINT");
+            // Also reset per-relay progress rows
+            $pdo->exec("UPDATE caching_backfill_relay_progress
+                        SET complete = FALSE, events_fetched = 0,
+                            until_cursor = 0, last_status = 'reset',
+                            consecutive_errors = 0,
+                            updated_at = EXTRACT(EPOCH FROM NOW())::BIGINT");
+            // Bump config generation to trigger hot-reload
+            $pdo->exec("UPDATE config SET value = (COALESCE(value::int, 0) + 1)::text
+                        WHERE key = 'caching_config_generation'");
+            $pdo->commit();
+            json_response(['ok' => true, 'message' => 'All backfill progress reset. Caching service will re-drain.']);
+        } catch (PDOException $e) {
+            $pdo->rollBack();
+            json_response(['ok' => false, 'error' => $e->getMessage()], 500);
+        }
+    } elseif ($action === 'reset_user' && $pubkey) {
+        // Reset backfill progress for a single followed author.
+        try {
+            $pdo->beginTransaction();
+            $stmt = $pdo->prepare("UPDATE caching_followed_pubkeys
+                                   SET until_cursor = 0, backfill_complete = FALSE,
+                                       events_fetched = 0,
+                                       updated_at = EXTRACT(EPOCH FROM NOW())::BIGINT
+                                   WHERE pubkey = ?");
+            $stmt->execute([$pubkey]);
+            // Also reset per-relay progress for this author
+            $stmt2 = $pdo->prepare("UPDATE caching_backfill_relay_progress
+                                    SET complete = FALSE, events_fetched = 0,
+                                        until_cursor = 0, last_status = 'reset',
+                                        consecutive_errors = 0,
+                                        updated_at = EXTRACT(EPOCH FROM NOW())::BIGINT
+                                    WHERE author_pubkey = ?");
+            $stmt2->execute([$pubkey]);
+            // Bump config generation to trigger hot-reload
+            $pdo->exec("UPDATE config SET value = (COALESCE(value::int, 0) + 1)::text
+                        WHERE key = 'caching_config_generation'");
+            $pdo->commit();
+            json_response(['ok' => true, 'message' => "Backfill reset for pubkey. Caching service will re-fetch."]);
+        } catch (PDOException $e) {
+            $pdo->rollBack();
+            json_response(['ok' => false, 'error' => $e->getMessage()], 500);
+        }
+    } else {
+        json_response(['ok' => false, 'error' => 'Unknown action'], 400);
+    }
+    exit;
+}
+
+// Caching config values (for toggle controls)
+$config = [];
+try {
+    $cfg_rows = $pdo->query("SELECT key, value FROM config WHERE key IN ('caching_enabled','caching_inbox_enabled','caching_live_enabled','caching_backfill_enabled')")->fetchAll();
+    foreach ($cfg_rows as $r) { $config[$r['key']] = $r['value']; }
+} catch (PDOException $e) {}
+
+// Service state
+$state = [];
+try { $state = $pdo->query("SELECT * FROM caching_service_state WHERE id = 1")->fetch() ?: []; } catch (PDOException $e) {}
+
+// Active target
+$active = ['pubkey' => '', 'relay' => ''];
+try { $active = $pdo->query("SELECT active_pubkey AS pubkey, active_relay AS relay FROM caching_backfill_active WHERE id = 1")->fetch() ?: $active; } catch (PDOException $e) {}
+
+// Inbox
+$inbox = ['pending' => 0, 'live' => 0, 'backfill' => 0];
+try {
+    $inbox = $pdo->query("SELECT COUNT(*) AS pending, COUNT(*) FILTER (WHERE source_class='live') AS live, COUNT(*) FILTER (WHERE source_class='backfill') AS backfill FROM caching_event_inbox")->fetch() ?: $inbox;
+} catch (PDOException $e) {}
+
+// Follows (paginated, with names from profiles cache + per-relay progress)
+$follows = [];
+try {
+    $follows = $pdo->query("
+        SELECT fp.pubkey, fp.is_root, fp.backfill_complete, fp.events_fetched,
+               fp.last_event_at,
+               p.name, p.display_name,
+               (SELECT count(*) FROM events WHERE pubkey = fp.pubkey) AS total_events,
+               (SELECT count(*) FROM caching_backfill_relay_progress WHERE author_pubkey = fp.pubkey) AS relay_count,
+               (SELECT count(*) FROM caching_backfill_relay_progress WHERE author_pubkey = fp.pubkey AND complete = false) AS relay_incomplete
+        FROM caching_followed_pubkeys fp
+        LEFT JOIN profiles p ON p.pubkey = fp.pubkey
+        ORDER BY fp.is_root DESC, fp.events_fetched DESC LIMIT 1000
+    ")->fetchAll();
+    // Fetch per-relay progress for all followed pubkeys in one query
+    $relayProgress = [];
+    try {
+        $rpRows = $pdo->query("
+            SELECT author_pubkey, relay_url, complete, events_fetched, until_cursor, last_status, updated_at
+            FROM caching_backfill_relay_progress
+            ORDER BY author_pubkey, events_fetched DESC
+        ")->fetchAll();
+        foreach ($rpRows as $rp) {
+            $relayProgress[$rp['author_pubkey']][] = $rp;
+        }
+    } catch (PDOException $e) {}
+    foreach ($follows as &$f) {
+        $f['name'] = profile_display_name($f);
+        $f['npub'] = function_exists('hex_to_npub') ? hex_to_npub($f['pubkey']) : substr($f['pubkey'], 0, 20);
+        $f['relays'] = $relayProgress[$f['pubkey']] ?? [];
+    }
+} catch (PDOException $e) {}
+
+json_response(['state' => $state, 'active' => $active, 'inbox' => $inbox, 'follows' => $follows, 'config' => $config]);

admin/api/chart.php

@@ -0,0 +1,120 @@
+<?php
+/**
+ * admin2/api/chart.php — Standalone ASCII chart endpoint.
+ *
+ * Returns a plain-text ASCII X-bar chart of event counts over time.
+ * Works in both the browser (injected into a <div>) and the terminal:
+ *
+ *   curl http://localhost:8088/api/chart.php?range=hour
+ *   curl http://localhost:8088/api/chart.php?range=day
+ *   curl http://localhost:8088/api/chart.php?range=month
+ *   curl http://localhost:8088/api/chart.php?range=year
+ *
+ * Caching: the hour chart is never cached (live). Day/month/year are
+ * cached to file with TTLs to avoid expensive queries on every request.
+ */
+
+require_once __DIR__ . '/../lib/helpers.php';
+require_once __DIR__ . '/../lib/ascii_chart.php';
+
+// --- Range configuration ---
+$ranges = [
+    'hour'  => ['span' => 3600,     'bin' => 45,     'bins' => 80,  'ttl' => 0,        'title' => 'New Events — Last Hour'],
+    'day'   => ['span' => 86400,    'bin' => 1080,   'bins' => 80,  'ttl' => 3600,     'title' => 'New Events — Last 24 Hours'],
+    'month' => ['span' => 2592000,  'bin' => 32400,  'bins' => 80,  'ttl' => 86400,    'title' => 'New Events — Last 30 Days'],
+    'year'  => ['span' => 31536000, 'bin' => 394200, 'bins' => 80,  'ttl' => 2592000,  'title' => 'New Events — Last Year'],
+];
+
+$range = $_GET['range'] ?? 'hour';
+if (!isset($ranges[$range])) {
+    http_response_code(400);
+    header('Content-Type: text/plain; charset=utf-8');
+    echo "Invalid range. Use: hour, day, month, or year.\n";
+    exit;
+}
+
+$cfg = $ranges[$range];
+
+// --- Set content type ---
+header('Content-Type: text/plain; charset=utf-8');
+
+// --- Check cache ---
+if ($cfg['ttl'] > 0) {
+    $cached = get_cached_chart($range, $cfg['ttl']);
+    if ($cached !== null) {
+        echo $cached;
+        exit;
+    }
+}
+
+// --- Run binning query ---
+$pdo = db();
+$now = time();
+$epoch = $now - $cfg['span'];
+$bin_size = $cfg['bin'];
+$num_bins = $cfg['bins'];
+
+try {
+    // Calculate the bin offset so the rightmost bin aligns with "now"
+    // bin index 0 = oldest, bin index (num_bins-1) = newest
+    $base_bin = (int)floor($epoch / $bin_size);
+
+    $sql = "SELECT FLOOR(created_at / {$bin_size})::BIGINT - {$base_bin} AS bin, COUNT(*) AS cnt
+            FROM events
+            WHERE created_at >= {$epoch}
+            GROUP BY bin
+            ORDER BY bin";
+    $rows = $pdo->query($sql)->fetchAll();
+} catch (PDOException $e) {
+    echo "Chart query failed: " . $e->getMessage() . "\n";
+    exit;
+}
+
+// --- Build bin array (zero-filled, fixed length) ---
+// Index 0 = oldest, index N-1 = newest (natural time order from SQL)
+$bins = build_bin_array($rows, $num_bins);
+
+// Reverse so newest bin is at index 0 (leftmost) and oldest at right.
+// This matches the original text_graph.js display: new data enters
+// from the left and proceeds rightward as it ages.
+$bins = array_reverse($bins);
+
+// --- Render ASCII chart ---
+$ascii = render_ascii_chart($bins, [
+    'title'          => $cfg['title'],
+    'max_height'     => 11,
+    'bin_duration'   => $bin_size,
+    'label_interval' => max(1, (int)floor($num_bins / 15)), // ~15 labels across
+]);
+
+// --- Write to cache (if TTL > 0) ---
+if ($cfg['ttl'] > 0) {
+    set_cached_chart($range, $ascii);
+}
+
+echo $ascii;
+
+
+// ================================
+// CACHE HELPERS
+// ================================
+
+function get_cache_dir(): string {
+    return __DIR__ . '/../cache';
+}
+
+function get_cached_chart(string $range, int $ttl): ?string {
+    $file = get_cache_dir() . "/chart_{$range}.txt";
+    if (!file_exists($file)) return null;
+    if (filemtime($file) < (time() - $ttl)) return null;
+    $content = @file_get_contents($file);
+    return ($content !== false) ? $content : null;
+}
+
+function set_cached_chart(string $range, string $ascii): void {
+    $dir = get_cache_dir();
+    if (!is_dir($dir)) {
+        @mkdir($dir, 0775, true);
+    }
+    @file_put_contents($dir . "/chart_{$range}.txt", $ascii);
+}

admin/api/config.php

@@ -0,0 +1,20 @@
+<?php
+/** admin2/api/config.php — Config table read/edit (all keys). */
+require_once __DIR__ . '/../lib/helpers.php';
+$pdo = db();
+
+if ($_SERVER['REQUEST_METHOD'] === 'POST') {
+    $input = json_decode(file_get_contents('php://input'), true);
+    $key = $input['key'] ?? '';
+    $value = $input['value'] ?? '';
+    if (!$key) json_response(['error' => 'Missing key']);
+    try {
+        $pdo->prepare("UPDATE config SET value = ? WHERE key = ?")->execute([$value, $key]);
+        json_response(['message' => "Updated $key"]);
+    } catch (PDOException $e) {
+        json_response(['error' => $e->getMessage()]);
+    }
+}
+
+$rows = $pdo->query("SELECT key, value FROM config ORDER BY key")->fetchAll();
+json_response(['config' => $rows]);

admin/api/dm.php

@@ -0,0 +1,16 @@
+<?php
+/** admin2/api/dm.php — Direct messages (kind 4/14/15). */
+require_once __DIR__ . '/../lib/helpers.php';
+$pdo = db();
+
+$limit = min(200, intval($_GET['limit'] ?? 50));
+$rows = $pdo->prepare("SELECT id, pubkey, kind, created_at, content FROM events WHERE kind IN (4, 14, 15) ORDER BY created_at DESC LIMIT $limit");
+$rows->execute();
+$messages = $rows->fetchAll();
+
+foreach ($messages as &$m) {
+    $m['created_at'] = date('Y-m-d H:i:s', intval($m['created_at']));
+    $m['content'] = substr($m['content'] ?? '', 0, 300);
+}
+
+json_response(['messages' => $messages]);

admin/api/events.php

@@ -0,0 +1,32 @@
+<?php
+/** admin2/api/events.php — Recent relay events (paginated). */
+require_once __DIR__ . '/../lib/helpers.php';
+$pdo = db();
+
+$limit  = min(200, intval($_GET['limit'] ?? 50));
+$offset = intval($_GET['offset'] ?? 0);
+$kind   = $_GET['kind'] ?? '';
+
+$where = [];
+$params = [];
+if ($kind !== '') { $where[] = 'kind = ?'; $params[] = intval($kind); }
+$where_sql = $where ? 'WHERE ' . implode(' AND ', $where) : '';
+
+$rows = $pdo->prepare("SELECT e.id, e.pubkey, e.kind, e.created_at, e.content,
+                              p.name, p.display_name
+                         FROM events e
+                         LEFT JOIN profiles p ON p.pubkey = e.pubkey
+                         $where_sql
+                         ORDER BY e.created_at DESC LIMIT $limit OFFSET $offset");
+$rows->execute($params);
+$events = $rows->fetchAll();
+
+foreach ($events as &$e) {
+    $e['created_at'] = date('Y-m-d H:i:s', intval($e['created_at']));
+    $e['content'] = substr($e['content'] ?? '', 0, 200);
+    // Resolve display name from profiles cache; fall back to truncated pubkey.
+    $best = profile_display_name($e);
+    $e['display_name'] = $best !== '' ? $best : substr($e['pubkey'] ?? '', 0, 16) . '…';
+}
+
+json_response(['events' => $events]);

admin/api/ipbans.php

@@ -0,0 +1,35 @@
+<?php
+/** admin2/api/ipbans.php — IP ban management. */
+require_once __DIR__ . '/../lib/helpers.php';
+$pdo = db();
+
+if ($_SERVER['REQUEST_METHOD'] === 'POST') {
+    $input = json_decode(file_get_contents('php://input'), true);
+    $action = $input['action'] ?? '';
+    try {
+        if ($action === 'add') {
+            $until = time() + intval($input['duration'] ?? 86400);
+            $pdo->prepare("INSERT INTO ip_bans (ip, banned_until, ban_count) VALUES (?, ?, 1) ON CONFLICT (ip) DO UPDATE SET banned_until = ?, ban_count = ip_bans.ban_count + 1")->execute([$input['ip'], $until, $until]);
+            json_response(['message' => 'IP banned']);
+        } elseif ($action === 'remove') {
+            $pdo->prepare("DELETE FROM ip_bans WHERE ip = ?")->execute([$input['ip']]);
+            json_response(['message' => 'Ban removed']);
+        }
+    } catch (PDOException $e) { json_response(['error' => $e->getMessage()]); }
+}
+
+$now = time();
+$total = 0; $active = 0; $issued = 0;
+$bans = [];
+try {
+    $total  = intval($pdo->query("SELECT count(*) FROM ip_bans")->fetchColumn());
+    $active = intval($pdo->query("SELECT count(*) FROM ip_bans WHERE banned_until > $now")->fetchColumn());
+    $issued = intval($pdo->query("SELECT COALESCE(sum(ban_count),0) FROM ip_bans")->fetchColumn());
+    $bans = $pdo->query("SELECT ip, banned_until, ban_count, failures, authed_successfully, connection_attempts FROM ip_bans ORDER BY banned_until DESC LIMIT 100")->fetchAll();
+    foreach ($bans as &$b) {
+        $b['status'] = intval($b['banned_until']) > $now ? 'banned' : 'expired';
+        $b['banned_until'] = date('Y-m-d H:i:s', intval($b['banned_until']));
+    }
+} catch (PDOException $e) {}
+
+json_response(['total' => $total, 'active' => $active, 'issued' => $issued, 'bans' => $bans]);

admin/api/profile.php

@@ -0,0 +1,38 @@
+<?php
+/**
+ * admin/api/profile.php — Single-profile lookup from the profiles cache.
+ * Returns cached kind-0 metadata for a given pubkey.
+ *
+ * Usage: profile.php?pubkey=<64-char-hex>
+ * Returns: { "pubkey": "...", "name": "...", "display_name": "...",
+ *             "best_name": "...", "picture": "...", "nip05": "...",
+ *             "about": "...", "website": "...", "lud16": "..." }
+ *           or { "error": "not found" } with HTTP 404 if no profile is cached.
+ */
+require_once __DIR__ . '/../lib/helpers.php';
+
+$pubkey = trim($_GET['pubkey'] ?? '');
+if (!preg_match('/^[0-9a-fA-F]{64}$/', $pubkey)) {
+    http_response_code(400);
+    json_response(['error' => 'Invalid pubkey']);
+}
+
+$pdo = db();
+try {
+    $stmt = $pdo->prepare(
+        "SELECT pubkey, name, display_name, about, picture, banner,
+                nip05, website, lud16, lud06
+         FROM profiles WHERE pubkey = ?"
+    );
+    $stmt->execute([$pubkey]);
+    $row = $stmt->fetch();
+    if (!$row) {
+        http_response_code(404);
+        json_response(['error' => 'not found']);
+    }
+    $row['best_name'] = profile_display_name($row);
+    json_response($row);
+} catch (PDOException $e) {
+    http_response_code(500);
+    json_response(['error' => 'Database error']);
+}

admin/api/query.php

@@ -0,0 +1,24 @@
+<?php
+/** admin2/api/query.php — Direct SQL query (SELECT only, admin only). */
+require_once __DIR__ . '/../lib/helpers.php';
+$pdo = db();
+
+if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
+    json_response(['error' => 'POST only']);
+}
+
+$input = json_decode(file_get_contents('php://input'), true);
+$sql = trim($input['sql'] ?? '');
+
+if (!$sql) json_response(['error' => 'No query provided']);
+if (!preg_match('/^\s*SELECT/i', $sql)) json_response(['error' => 'Only SELECT queries are allowed']);
+
+$start = microtime(true);
+try {
+    $stmt = $pdo->query($sql);
+    $rows = $stmt->fetchAll();
+    $time_ms = round((microtime(true) - $start) * 1000, 1);
+    json_response(['rows' => $rows, 'row_count' => count($rows), 'time_ms' => $time_ms]);
+} catch (PDOException $e) {
+    json_response(['error' => $e->getMessage()]);
+}

admin/api/stats.php

@@ -0,0 +1,154 @@
+<?php
+/**
+ * admin2/api/stats.php — Statistics page data.
+ * Returns DB size, event counts, kind distribution, top pubkeys,
+ * time-based stats, and event-rate delta (for the chart).
+ */
+require_once __DIR__ . '/../lib/helpers.php';
+
+$pdo = db();
+
+// Database size
+$db_size = '-';
+try {
+    $bytes = $pdo->query("SELECT pg_database_size(current_database())")->fetchColumn();
+    $db_size = format_bytes(intval($bytes));
+} catch (PDOException $e) {}
+
+// Total events
+$total_events = intval($pdo->query("SELECT COUNT(*) FROM events")->fetchColumn());
+
+// Event rate: events with first_seen in last 10 seconds
+$events_delta = 0;
+try {
+    $events_delta = intval($pdo->query("SELECT COUNT(*) FROM events WHERE first_seen >= EXTRACT(EPOCH FROM NOW())::BIGINT - 10")->fetchColumn());
+} catch (PDOException $e) {}
+
+// Process info (from pg_stat_activity)
+$process_id = '-';
+$ws_connections = '-';
+try {
+    $pid = $pdo->query("SELECT pg_backend_pid()")->fetchColumn();
+    $process_id = strval($pid);
+    $ws_connections = intval($pdo->query("SELECT count(*) FROM pg_stat_activity WHERE state = 'active' AND pid != pg_backend_pid()")->fetchColumn());
+} catch (PDOException $e) {}
+
+// Active subscriptions
+$active_subscriptions = 0;
+try {
+    $active_subscriptions = intval($pdo->query("SELECT count(*) FROM subscriptions WHERE active = true")->fetchColumn());
+} catch (PDOException $e) {}
+
+// Memory/CPU (from /proc on Linux)
+$memory_usage = '-';
+$cpu_usage = '-';
+$cpu_core = '-';
+if (is_readable('/proc/meminfo')) {
+    $mem = parse_ini_file('/proc/meminfo');
+    $total = intval($mem['MemTotal'] ?? 0) * 1024;
+    $avail = intval($mem['MemAvailable'] ?? 0) * 1024;
+    if ($total > 0) $memory_usage = format_bytes($total - $avail) . ' / ' . format_bytes($total);
+}
+if (is_readable('/proc/cpuinfo')) {
+    $cores = intval(shell_exec('nproc 2>/dev/null') ?: 1);
+    $cpu_core = strval($cores) . ' cores';
+}
+$cpu_usage = @file_get_contents('/proc/loadavg');
+if ($cpu_usage !== false) $cpu_usage = trim(explode(' ', $cpu_usage)[0] ?? '-');
+
+// Oldest / newest event
+$oldest_event = '-';
+$newest_event = '-';
+try {
+    $oldest = $pdo->query("SELECT to_timestamp(MIN(created_at)) FROM events")->fetchColumn();
+    $newest = $pdo->query("SELECT to_timestamp(MAX(created_at)) FROM events")->fetchColumn();
+    if ($oldest) $oldest_event = substr($oldest, 0, 19);
+    if ($newest) $newest_event = substr($newest, 0, 19);
+} catch (PDOException $e) {}
+
+// Time-based stats
+$now = time();
+$events_24h = 0; $events_7d = 0; $events_30d = 0;
+try {
+    $events_24h = intval($pdo->query("SELECT COUNT(*) FROM events WHERE created_at >= $now - 86400")->fetchColumn());
+    $events_7d  = intval($pdo->query("SELECT COUNT(*) FROM events WHERE created_at >= $now - 604800")->fetchColumn());
+    $events_30d = intval($pdo->query("SELECT COUNT(*) FROM events WHERE created_at >= $now - 2592000")->fetchColumn());
+} catch (PDOException $e) {}
+
+// Kind distribution
+$kinds = [];
+try {
+    $rows = $pdo->query("SELECT kind, COUNT(*) AS cnt FROM events GROUP BY kind ORDER BY cnt DESC LIMIT 20")->fetchAll();
+    foreach ($rows as $r) {
+        $kinds[] = ['kind' => intval($r['kind']), 'count' => intval($r['cnt']), 'pct' => $total_events > 0 ? round(intval($r['cnt']) / $total_events * 100, 1) : 0];
+    }
+} catch (PDOException $e) {}
+
+// Top pubkeys (with names from profiles cache)
+$top_pubkeys = [];
+try {
+    $rows = $pdo->query("
+        SELECT pubkey, COUNT(*) AS cnt
+        FROM events
+        GROUP BY pubkey
+        ORDER BY cnt DESC LIMIT 20
+    ")->fetchAll();
+    // Batch-resolve profile names from the profiles cache table.
+    $pubkeys = array_column($rows, 'pubkey');
+    $pmap = profile_map($pubkeys);
+    foreach ($rows as $r) {
+        $pk = $r['pubkey'];
+        $prof = $pmap[$pk] ?? null;
+        $top_pubkeys[] = [
+            'pubkey' => $pk,
+            'name'   => $prof ? $prof['best_name'] : '',
+            'count'  => intval($r['cnt']),
+            'pct'    => $total_events > 0 ? round(intval($r['cnt']) / $total_events * 100, 1) : 0,
+        ];
+    }
+} catch (PDOException $e) {}
+
+// Name-field usage stats (from profiles cache)
+$name_field_usage = ['both' => 0, 'name_only' => 0, 'display_only' => 0, 'neither' => 0, 'both_differ' => 0, 'total' => 0];
+try {
+    $row = $pdo->query("
+        SELECT count(*) FILTER (WHERE name <> '' AND display_name <> '')  AS both,
+               count(*) FILTER (WHERE name <> '' AND display_name =  '')  AS name_only,
+               count(*) FILTER (WHERE name =  '' AND display_name <> '')  AS display_only,
+               count(*) FILTER (WHERE name =  '' AND display_name =  '')  AS neither,
+               count(*) FILTER (WHERE name <> '' AND display_name <> '' AND name <> display_name) AS both_differ,
+               count(*) AS total
+          FROM profiles
+    ")->fetch();
+    if ($row) {
+        $name_field_usage = array_map('intval', $row);
+    }
+} catch (PDOException $e) {}
+
+json_response([
+    'db_size'             => $db_size,
+    'total_events'        => $total_events,
+    'events_delta'        => $events_delta,
+    'process_id'          => $process_id,
+    'ws_connections'      => $ws_connections,
+    'active_subscriptions' => $active_subscriptions,
+    'memory_usage'        => $memory_usage,
+    'cpu_usage'           => $cpu_usage,
+    'cpu_core'            => $cpu_core,
+    'oldest_event'        => $oldest_event,
+    'newest_event'        => $newest_event,
+    'events_24h'          => $events_24h,
+    'events_7d'           => $events_7d,
+    'events_30d'          => $events_30d,
+    'kinds'               => $kinds,
+    'top_pubkeys'         => $top_pubkeys,
+    'name_field_usage'    => $name_field_usage,
+]);
+
+/** Format bytes as human-readable. */
+function format_bytes(int $bytes): string {
+    if ($bytes < 1024) return $bytes . ' B';
+    if ($bytes < 1048576) return round($bytes / 1024, 1) . ' KB';
+    if ($bytes < 1073741824) return round($bytes / 1048576, 1) . ' MB';
+    return round($bytes / 1073741824, 2) . ' GB';
+}

admin/api/subscriptions.php

@@ -0,0 +1,11 @@
+<?php
+/** admin2/api/subscriptions.php — Active subscription details. */
+require_once __DIR__ . '/../lib/helpers.php';
+$pdo = db();
+
+$subs = [];
+try {
+    $subs = $pdo->query("SELECT id, sub_id, pubkey, filters, created_at, events_sent FROM subscriptions ORDER BY created_at DESC LIMIT 100")->fetchAll();
+} catch (PDOException $e) {}
+
+json_response(['subscriptions' => $subs]);

admin/assets/app.js

@@ -0,0 +1,956 @@
+/*
+ * admin2 — Full PHP admin for C-Relay-PG.
+ * Replaces the 7457-line api/index.js with a lightweight AJAX-based
+ * controller that fetches data from PHP API endpoints (api/*.php)
+ * instead of Nostr WebSocket admin commands.
+ */
+
+const REFRESH_MS = 10000;
+let currentPage = 'statistics';
+let statsInterval = null;
+
+// HTML-escape helper for safe interpolation into innerHTML.
+// Prevents stored XSS from user-controlled data (profile names, event
+// content, config values, etc.) being parsed as HTML by the browser.
+const esc = (s) => {
+    const str = String(s ?? '');
+    return str.replace(/[&<>"']/g, (ch) => {
+        return '&#' + ch.charCodeAt(0) + ';';
+    });
+};
+
+// Auth state
+let nlLite = null;
+let userPubkey = null;
+let isLoggedIn = false;
+let relayAnimationTimer = null;
+
+// Server-rendered ASCII chart state
+let currentChartRange = 'hour';
+let chartLoadTimer = null;
+
+// ================================
+// NAVIGATION
+// ================================
+
+function toggleNav() {
+    document.getElementById('side-nav').classList.toggle('open');
+    document.getElementById('side-nav-overlay').classList.toggle('show');
+}
+
+document.getElementById('side-nav-overlay')?.addEventListener('click', toggleNav);
+
+document.querySelectorAll('.nav-item').forEach(btn => {
+    btn.addEventListener('click', () => {
+        const page = btn.getAttribute('data-page');
+        switchPage(page);
+        document.getElementById('side-nav').classList.remove('open');
+        document.getElementById('side-nav-overlay').classList.remove('show');
+    });
+});
+
+function switchPage(pageName) {
+    currentPage = pageName;
+    document.querySelectorAll('.nav-item').forEach(item => {
+        item.classList.remove('active');
+        if (item.getAttribute('data-page') === pageName) item.classList.add('active');
+    });
+
+    const sections = [
+        'databaseStatisticsSection', 'subscriptionDetailsSection', 'div_config',
+        'authRulesSection', 'wotSection', 'ipBansSection', 'relayEventsSection',
+        'cachingSection', 'nip17DMSection', 'sqlQuerySection'
+    ];
+    sections.forEach(id => { const el = document.getElementById(id); if (el) el.style.display = 'none'; });
+
+    const pageMap = {
+        'statistics': 'databaseStatisticsSection',
+        'subscriptions': 'subscriptionDetailsSection',
+        'configuration': 'div_config',
+        'ip-bans': 'ipBansSection',
+        'relay-events': 'relayEventsSection',
+        'caching': 'cachingSection',
+        'dm': 'nip17DMSection',
+        'database': 'sqlQuerySection'
+    };
+
+    if (pageName === 'authorization') {
+        document.getElementById('authRulesSection').style.display = 'block';
+        document.getElementById('wotSection').style.display = 'block';
+        loadAuthRules();
+        loadWotStatus();
+    } else {
+        const target = pageMap[pageName];
+        if (target) document.getElementById(target).style.display = 'block';
+    }
+
+    // Load data for the page
+    const loaders = {
+        'statistics': loadStats,
+        'subscriptions': loadSubscriptions,
+        'configuration': loadConfig,
+        'ip-bans': loadIpBans,
+        'relay-events': loadEvents,
+        'caching': loadCaching,
+        'dm': loadDMs,
+    };
+    if (loaders[pageName]) loaders[pageName]();
+
+    // Start/stop auto-refresh for statistics
+    if (pageName === 'statistics') {
+        if (!statsInterval) {
+            loadStats();
+            statsInterval = setInterval(loadStats, REFRESH_MS);
+            console.log('[admin2] auto-refresh started, interval:', REFRESH_MS, 'ms');
+        }
+    } else {
+        if (statsInterval) { clearInterval(statsInterval); statsInterval = null; }
+    }
+}
+
+// ================================
+// STATISTICS
+// ================================
+
+async function loadStats() {
+    console.log('[admin2] loading stats at', new Date().toLocaleTimeString());
+    // Fire the RELAY letter animation on every refresh — visual indicator the page is updating
+    startRelayAnimation();
+    try {
+        const res = await fetch('api/stats.php');
+        if (!res.ok) { console.warn('[admin2] stats.php returned', res.status); return; }
+        const d = await res.json();
+        console.log('[admin2] stats loaded — events:', d.total_events, 'rate:', d.events_delta, '/10s');
+
+        const set = (id, val) => { const el = document.getElementById(id); if (el) el.textContent = val; };
+        set('db-size', d.db_size || '-');
+        set('total-events', (d.total_events ?? 0).toLocaleString());
+        set('process-id', d.process_id || '-');
+        set('websocket-connections', d.ws_connections ?? '-');
+        set('active-subscriptions', d.active_subscriptions ?? '-');
+        set('memory-usage', d.memory_usage || '-');
+        set('cpu-usage', d.cpu_usage || '-');
+        set('cpu-core', d.cpu_core || '-');
+        set('oldest-event', d.oldest_event || '-');
+        set('newest-event', d.newest_event || '-');
+        set('events-24h', (d.events_24h ?? 0).toLocaleString());
+        set('events-7d', (d.events_7d ?? 0).toLocaleString());
+        set('events-30d', (d.events_30d ?? 0).toLocaleString());
+
+        // Kind distribution
+        if (d.kinds) {
+            const tbody = document.getElementById('stats-kinds-table-body');
+            tbody.innerHTML = d.kinds.map(k =>
+                `<tr><td>${k.kind}</td><td>${k.count.toLocaleString()}</td><td>${k.pct}%</td></tr>`
+            ).join('');
+        }
+
+        // Top pubkeys
+        if (d.top_pubkeys) {
+            const tbody = document.getElementById('stats-pubkeys-table-body');
+            tbody.innerHTML = d.top_pubkeys.map((p, i) =>
+                `<tr><td>${i+1}</td><td><bdi>${esc(p.name) || '<i>unknown</i>'}</bdi></td><td class="pubkey">${esc(p.pubkey.substring(0,16))}…</td><td>${p.count.toLocaleString()}</td><td>${p.pct}%</td></tr>`
+            ).join('');
+        }
+
+        // Name-field usage stats (from profiles cache)
+        if (d.name_field_usage && d.name_field_usage.total > 0) {
+            const u = d.name_field_usage;
+            const el = document.getElementById('name-field-usage');
+            if (el) {
+                el.innerHTML = `
+                    <div class="name-usage-stats">
+                        <span class="name-usage-label">Profile name fields (${u.total} profiles):</span>
+                        <span class="name-usage-item">Both: ${u.both}</span>
+                        <span class="name-usage-item">name only: ${u.name_only}</span>
+                        <span class="name-usage-item">display_name only: ${u.display_only}</span>
+                        <span class="name-usage-item name-usage-differ">Differ: ${u.both_differ}</span>
+                    </div>`;
+            }
+        }
+
+        // Refresh the chart on every stats poll (server handles caching for non-hour ranges)
+        loadChart(currentChartRange);
+    } catch (e) { console.error('[admin2] stats error:', e); }
+}
+
+// ================================
+// EVENT RATE CHART (server-rendered ASCII via chart.php)
+// ================================
+
+// Fetch the ASCII chart from the server and inject it into the div.
+// The chart is rendered server-side as plain text — works in both
+// browser and terminal (curl http://localhost:8088/api/chart.php?range=hour)
+async function loadChart(range) {
+    const el = document.getElementById('event-rate-chart');
+    if (!el) return;
+    try {
+        const res = await fetch('api/chart.php?range=' + encodeURIComponent(range));
+        if (!res.ok) { el.textContent = 'Chart load failed (HTTP ' + res.status + ')'; return; }
+        const text = await res.text();
+        el.textContent = text;
+        // Newest data is at the left (index 0) — scroll to start so it's visible
+        el.scrollLeft = 0;
+    } catch (e) {
+        console.error('[admin2] chart load error:', e);
+        el.textContent = 'Chart load error: ' + e.message;
+    }
+}
+
+// Chart range tab click handlers
+document.querySelectorAll('.chart-tab').forEach(tab => {
+    tab.addEventListener('click', () => {
+        const range = tab.getAttribute('data-range');
+        if (!range || range === currentChartRange) return;
+        currentChartRange = range;
+        document.querySelectorAll('.chart-tab').forEach(t => t.classList.remove('active'));
+        tab.classList.add('active');
+        loadChart(range);
+    });
+});
+
+// ================================
+// SUBSCRIPTIONS
+// ================================
+
+async function loadSubscriptions() {
+    try {
+        const res = await fetch('api/subscriptions.php');
+        const d = await res.json();
+        const tbody = document.getElementById('subscription-details-table-body');
+        if (!d.subscriptions || d.subscriptions.length === 0) {
+            tbody.innerHTML = '<tr><td colspan="5" style="text-align:center;font-style:italic">No subscriptions active</td></tr>';
+            return;
+        }
+        tbody.innerHTML = d.subscriptions.map(s =>
+            `<tr><td>${esc(s.sub_id) || '-'}</td><td class="pubkey">${esc((s.pubkey||'-').substring(0,16))}</td><td>${esc(s.filters) || '-'}</td><td>${esc(s.created) || '-'}</td><td>${s.events_sent ?? 0}</td></tr>`
+        ).join('');
+    } catch (e) { console.error('[admin2] subscriptions error:', e); }
+}
+
+// ================================
+// CONFIGURATION
+// ================================
+
+async function loadConfig() {
+    try {
+        const res = await fetch('api/config.php');
+        const d = await res.json();
+        const tbody = document.getElementById('config-table-body');
+        if (!d.config || d.config.length === 0) {
+            tbody.innerHTML = '<tr><td colspan="3" style="text-align:center;font-style:italic">No config entries</td></tr>';
+            return;
+        }
+        tbody.innerHTML = d.config.map(c =>
+            `<tr><td>${esc(c.key)}</td><td>${esc(c.value)}</td><td><button onclick="editConfig('${esc(c.key)}')">EDIT</button></td></tr>`
+        ).join('');
+    } catch (e) { console.error('[admin2] config error:', e); }
+}
+
+function editConfig(key) {
+    const newVal = prompt('Enter new value for ' + key + ':');
+    if (newVal === null) return;
+    fetch('api/config.php', {
+        method: 'POST',
+        headers: {'Content-Type': 'application/json'},
+        body: JSON.stringify({key, value: newVal})
+    }).then(r => r.json()).then(d => {
+        alert(d.message || 'Saved');
+        loadConfig();
+    }).catch(e => alert('Error: ' + e));
+}
+
+// ================================
+// AUTH RULES
+// ================================
+
+async function loadAuthRules() {
+    try {
+        const res = await fetch('api/auth.php');
+        const d = await res.json();
+        const tbody = document.getElementById('authRulesTableBody');
+        if (!d.rules || d.rules.length === 0) {
+            tbody.innerHTML = '<tr><td colspan="5" style="text-align:center;font-style:italic">No auth rules</td></tr>';
+            return;
+        }
+        tbody.innerHTML = d.rules.map(r =>
+            `<tr><td>${esc(r.rule_type)}</td><td>${esc(r.pattern_type)}</td><td>${esc(r.pattern_value)}</td><td>${esc(r.status) || 'active'}</td><td><button onclick="removeAuthRule(${r.id})">REMOVE</button></td></tr>`
+        ).join('');
+    } catch (e) { console.error('[admin2] auth error:', e); }
+}
+
+async function addAuthRule(type) {
+    const pk = document.getElementById('authRulePubkey').value.trim();
+    if (!pk) { alert('Enter a pubkey first'); return; }
+    const res = await fetch('api/auth.php', {
+        method: 'POST',
+        headers: {'Content-Type': 'application/json'},
+        body: JSON.stringify({action: 'add', rule_type: type, pattern_value: pk})
+    });
+    const d = await res.json();
+    alert(d.message || 'Done');
+    loadAuthRules();
+}
+
+async function removeAuthRule(id) {
+    const res = await fetch('api/auth.php', {
+        method: 'POST',
+        headers: {'Content-Type': 'application/json'},
+        body: JSON.stringify({action: 'remove', id})
+    });
+    const d = await res.json();
+    alert(d.message || 'Done');
+    loadAuthRules();
+}
+
+// ================================
+// WEB OF TRUST
+// ================================
+
+async function loadWotStatus() {
+    try {
+        const res = await fetch('api/auth.php?action=wot');
+        const d = await res.json();
+        const ind = document.getElementById('wotKind3Indicator');
+        if (ind) ind.textContent = d.kind3_status || 'Unknown';
+        const cnt = document.getElementById('wotWhitelistCount');
+        if (cnt) cnt.textContent = d.whitelist_count ?? '—';
+        const desc = document.getElementById('wotLevelDescription');
+        if (desc) desc.textContent = d.level_description || '';
+    } catch (e) { console.error('[admin2] wot error:', e); }
+}
+
+async function setWotLevel(level) {
+    const res = await fetch('api/auth.php', {
+        method: 'POST',
+        headers: {'Content-Type': 'application/json'},
+        body: JSON.stringify({action: 'set_wot_level', level})
+    });
+    const d = await res.json();
+    alert(d.message || 'Done');
+    loadWotStatus();
+}
+
+async function syncWot() {
+    const res = await fetch('api/auth.php', {
+        method: 'POST',
+        headers: {'Content-Type': 'application/json'},
+        body: JSON.stringify({action: 'sync_wot'})
+    });
+    const d = await res.json();
+    alert(d.message || 'Done');
+    loadWotStatus();
+}
+
+// ================================
+// IP BANS
+// ================================
+
+async function loadIpBans() {
+    try {
+        const res = await fetch('api/ipbans.php');
+        const d = await res.json();
+        document.getElementById('ip-bans-total').textContent = d.total ?? '-';
+        document.getElementById('ip-bans-active').textContent = d.active ?? '-';
+        document.getElementById('ip-bans-issued').textContent = d.issued ?? '-';
+        const tbody = document.getElementById('ip-bans-tbody');
+        if (!d.bans || d.bans.length === 0) {
+            tbody.innerHTML = '<tr><td colspan="5" style="text-align:center">No IP bans</td></tr>';
+            return;
+        }
+        tbody.innerHTML = d.bans.map(b =>
+            `<tr><td>${esc(b.ip)}</td><td>${esc(b.status)}</td><td>${esc(b.banned_until)}</td><td>${b.failures ?? 0}</td><td><button onclick="removeBan('${esc(b.ip)}')">REMOVE</button></td></tr>`
+        ).join('');
+    } catch (e) { console.error('[admin2] ipbans error:', e); }
+}
+
+async function addBan() {
+    const ip = document.getElementById('ban-ip-input').value.trim();
+    const duration = document.getElementById('ban-duration-select').value;
+    if (!ip) { alert('Enter an IP address'); return; }
+    const res = await fetch('api/ipbans.php', {
+        method: 'POST',
+        headers: {'Content-Type': 'application/json'},
+        body: JSON.stringify({action: 'add', ip, duration: parseInt(duration)})
+    });
+    const d = await res.json();
+    document.getElementById('add-ban-status').textContent = d.message || 'Done';
+    loadIpBans();
+}
+
+async function removeBan(ip) {
+    const res = await fetch('api/ipbans.php', {
+        method: 'POST',
+        headers: {'Content-Type': 'application/json'},
+        body: JSON.stringify({action: 'remove', ip})
+    });
+    const d = await res.json();
+    alert(d.message || 'Done');
+    loadIpBans();
+}
+
+// ================================
+// RELAY EVENTS
+// ================================
+
+async function loadEvents() {
+    try {
+        const res = await fetch('api/events.php?limit=50');
+        const d = await res.json();
+        const tbody = document.getElementById('live-relay-events-table-body');
+        if (!d.events || d.events.length === 0) {
+            tbody.innerHTML = '<tr><td colspan="5" style="text-align:center">No events</td></tr>';
+            return;
+        }
+        tbody.innerHTML = d.events.map(e =>
+            `<tr><td>${esc(e.created_at)}</td><td>${e.kind}</td><td><bdi>${esc(e.display_name || (e.pubkey||'').substring(0,16) + '…')}</bdi></td><td class="pubkey">${esc((e.id||'').substring(0,16))}…</td><td>${esc((e.content||'').substring(0,80))}</td></tr>`
+        ).join('');
+    } catch (err) { console.error('[admin2] events error:', err); }
+}
+
+// ================================
+// CACHING
+// ================================
+
+async function loadCaching() {
+    try {
+        const res = await fetch('api/caching.php');
+        const d = await res.json();
+        // Config toggle state
+        if (d.config) {
+            const enabled = d.config.caching_enabled === 'true';
+            const inboxEnabled = d.config.caching_inbox_enabled === 'true';
+            const enLabel = document.getElementById('caching-enabled-label');
+            const enBtn = document.getElementById('caching-toggle-btn');
+            const inLabel = document.getElementById('caching-inbox-enabled-label');
+            const inBtn = document.getElementById('caching-inbox-toggle-btn');
+            if (enLabel) enLabel.textContent = 'Caching: ' + (enabled ? 'ON' : 'OFF');
+            if (enBtn) enBtn.textContent = enabled ? 'Turn OFF' : 'Turn ON';
+            if (inLabel) inLabel.textContent = 'Inbox: ' + (inboxEnabled ? 'ON' : 'OFF');
+            if (inBtn) inBtn.textContent = inboxEnabled ? 'Turn OFF' : 'Turn ON';
+        }
+        // Service status
+        const ssEl = document.getElementById('caching-service-status');
+        if (ssEl && d.state) {
+            const s = d.state;
+            const hb = s.heartbeat_at ? new Date(s.heartbeat_at * 1000).toLocaleTimeString() : '—';
+            ssEl.innerHTML = `<p>State: <strong>${esc(s.service_state)}</strong> | Follows: ${s.followed_author_count ?? 0} | Connected relays: ${s.connected_relay_count ?? 0}/${s.selected_relay_count ?? 0} | Backfill: ${s.backfill_authors_complete ?? 0}/${s.backfill_authors_total ?? 0} | Events fetched: ${s.events_fetched ?? 0} | Inbox inserts: ${s.inbox_inserts ?? 0} | Heartbeat: ${hb}</p>`;
+        }
+        // Inbox status
+        const isEl = document.getElementById('caching-inbox-status');
+        if (isEl && d.inbox) {
+            isEl.innerHTML = `<p>Pending: ${d.inbox.pending} | Live: ${d.inbox.live} | Backfill: ${d.inbox.backfill}</p>`;
+        }
+        // Follows table
+        const tbody = document.getElementById('caching-follows-table-body');
+        if (tbody && d.follows) {
+            if (d.follows.length === 0) {
+                tbody.innerHTML = '<tr><td colspan="6" style="text-align:center;font-style:italic">No followed pubkeys</td></tr>';
+            } else {
+                const activePk = d.active && d.active.pubkey ? d.active.pubkey : '';
+                tbody.innerHTML = d.follows.map((f, i) => {
+                    const npub = f.npub || f.pubkey.substring(0, 20);
+                    const isActive = activePk && f.pubkey === activePk;
+                    const relaySummary = f.relay_incomplete > 0
+                        ? `<span class="status-working">${f.relay_count - f.relay_incomplete}/${f.relay_count} done</span>`
+                        : `${f.relay_count ?? 0} relays`;
+                    // Per-relay detail row (hidden by default, toggle via click)
+                    let relayDetail = '';
+                    if (f.relays && f.relays.length > 0) {
+                        relayDetail = '<div class="relay-progress-list">' +
+                            f.relays.map(r => {
+                                const statusIcon = r.complete ? '✓' : '⏳';
+                                const statusBadge = r.complete
+                                    ? `<span class="relay-status relay-done">${esc(r.last_status || 'eose')}</span>`
+                                    : `<span class="relay-status relay-pending">${esc(r.last_status || 'pending')}</span>`;
+                                const relayHost = r.relay_url.replace(/^wss?:\/\//, '').replace(/\/relay$/, '');
+                                return `<div class="relay-progress-row"><span class="relay-icon">${statusIcon}</span><span class="relay-url" title="${esc(r.relay_url)}">${esc(relayHost)}</span><span class="relay-events">${r.events_fetched} evts</span>${statusBadge}</div>`;
+                            }).join('') +
+                            '</div>';
+                    }
+                    const refreshBtn = `<button type="button" class="refresh-user-btn" onclick="event.stopPropagation(); refreshCachingUser('${esc(f.pubkey)}', '${esc(f.name || '')}')">↻ Refresh this user</button>`;
+                    const rowClass = isActive ? 'follows-row follows-row-active' : 'follows-row';
+                    const activeIcon = isActive ? '⚡ ' : '';
+                    return `<tr class="${rowClass}" onclick="this.nextElementSibling.style.display = this.nextElementSibling.style.display === 'none' ? '' : 'none'"><td><bdi>${activeIcon}${esc(f.name) || '<i>unknown</i>'}</bdi></td><td class="npub-link">${esc(npub)}…</td><td>${f.is_root ? '✓' : ''}</td><td>${f.total_events ?? 0}</td><td>${f.backfill_complete ? '✓' : '…'}</td><td>${relaySummary}</td></tr><tr class="follows-detail" style="display:none"><td colspan="6"><div class="follows-detail-content">${relayDetail || '<i>No relay progress data</i>'}<div class="follows-detail-actions">${refreshBtn}</div></div></td></tr>`;
+                }).join('');
+            }
+        }
+        // Active target
+        const fsEl = document.getElementById('caching-follows-status');
+        if (fsEl) {
+            if (d.active && d.active.pubkey && d.active.relay) {
+                fsEl.innerHTML = `<span class="status-working">⚡ Backfilling: ${d.active.pubkey.substring(0,16)}… @ ${esc(d.active.relay)}</span>`;
+            } else if (d.state && d.state.service_state === 'running') {
+                const incomplete = d.state.backfill_authors_complete < d.state.backfill_authors_total;
+                fsEl.innerHTML = incomplete
+                    ? `<span class="status-working">⚡ Backfill in progress…</span>`
+                    : `<span class="status-complete">✓ Backfill complete — listening for live events</span>`;
+            } else {
+                fsEl.innerHTML = `<span class="status-complete">✓ Caching complete</span>`;
+            }
+        }
+    } catch (e) { console.error('[admin2] caching error:', e); }
+}
+
+// Toggle caching_enabled config via the config API.
+async function toggleCachingEnabled() {
+    try {
+        const res = await fetch('api/caching.php');
+        const d = await res.json();
+        const current = d.config?.caching_enabled === 'true';
+        const newVal = current ? 'false' : 'true';
+        await fetch('api/config.php', {
+            method: 'POST',
+            headers: {'Content-Type': 'application/json'},
+            body: JSON.stringify({key: 'caching_enabled', value: newVal})
+        });
+        loadCaching();
+    } catch (e) { console.error('[admin2] toggle caching error:', e); }
+}
+
+// Toggle caching_inbox_enabled config via the config API.
+async function toggleCachingInboxEnabled() {
+    try {
+        const res = await fetch('api/caching.php');
+        const d = await res.json();
+        const current = d.config?.caching_inbox_enabled === 'true';
+        const newVal = current ? 'false' : 'true';
+        await fetch('api/config.php', {
+            method: 'POST',
+            headers: {'Content-Type': 'application/json'},
+            body: JSON.stringify({key: 'caching_inbox_enabled', value: newVal})
+        });
+        loadCaching();
+    } catch (e) { console.error('[admin2] toggle inbox error:', e); }
+}
+
+// Re-run all caching: resets backfill progress for all followed authors and
+// bumps caching_config_generation so the running service hot-reloads and
+// re-drains from the beginning.
+async function rerunAllCaching() {
+    if (!confirm('Reset backfill progress for ALL followed authors? The caching service will re-download everything from scratch.')) return;
+    const btn = document.getElementById('caching-rerun-all-btn');
+    if (btn) { btn.disabled = true; btn.textContent = 'Resetting…'; }
+    try {
+        const res = await fetch('api/caching.php', {
+            method: 'POST',
+            headers: {'Content-Type': 'application/json'},
+            body: JSON.stringify({action: 'reset_all'})
+        });
+        const d = await res.json();
+        if (d.ok) {
+            if (btn) { btn.textContent = '✓ Reset — re-draining'; }
+            setTimeout(() => { if (btn) { btn.disabled = false; btn.textContent = 'Re-run All Caching'; } loadCaching(); }, 2000);
+        } else {
+            alert('Reset failed: ' + (d.error || 'unknown error'));
+            if (btn) { btn.disabled = false; btn.textContent = 'Re-run All Caching'; }
+        }
+    } catch (e) {
+        console.error('[admin2] rerunAllCaching error:', e);
+        alert('Reset failed: ' + e.message);
+        if (btn) { btn.disabled = false; btn.textContent = 'Re-run All Caching'; }
+    }
+}
+
+// Refresh a single user: resets backfill progress for one followed author
+// and bumps caching_config_generation so the service re-fetches that author.
+async function refreshCachingUser(pubkey, name) {
+    if (!confirm('Reset backfill progress for ' + (name || pubkey.substring(0, 16) + '…') + '? The caching service will re-download this user\'s events from scratch.')) return;
+    try {
+        const res = await fetch('api/caching.php', {
+            method: 'POST',
+            headers: {'Content-Type': 'application/json'},
+            body: JSON.stringify({action: 'reset_user', pubkey: pubkey})
+        });
+        const d = await res.json();
+        if (d.ok) {
+            loadCaching();
+        } else {
+            alert('Refresh failed: ' + (d.error || 'unknown error'));
+        }
+    } catch (e) {
+        console.error('[admin2] refreshCachingUser error:', e);
+        alert('Refresh failed: ' + e.message);
+    }
+}
+
+// ================================
+// DMs
+// ================================
+
+async function loadDMs() {
+    try {
+        const res = await fetch('api/dm.php?limit=50');
+        const d = await res.json();
+        const el = document.getElementById('dm-inbox');
+        if (!d.messages || d.messages.length === 0) {
+            el.innerHTML = '<div class="log-entry">No messages found.</div>';
+            return;
+        }
+        el.innerHTML = d.messages.map(m =>
+            `<div class="log-entry"><strong>kind ${m.kind}</strong> from <span class="pubkey">${esc((m.pubkey||'').substring(0,16))}…</span> at ${esc(m.created_at)}:<br>${esc((m.content||'').substring(0,200))}</div>`
+        ).join('');
+    } catch (e) { console.error('[admin2] dm error:', e); }
+}
+
+// ================================
+// SQL QUERY
+// ================================
+
+async function executeQuery() {
+    const sql = document.getElementById('sql-input').value.trim();
+    if (!sql) { alert('Enter a SQL query'); return; }
+    if (!sql.toUpperCase().startsWith('SELECT')) { alert('Only SELECT queries are allowed'); return; }
+    try {
+        const res = await fetch('api/query.php', {
+            method: 'POST',
+            headers: {'Content-Type': 'application/json'},
+            body: JSON.stringify({sql})
+        });
+        const d = await res.json();
+        const info = document.getElementById('query-info');
+        const tableDiv = document.getElementById('query-table');
+        if (d.error) {
+            info.textContent = 'Error: ' + d.error;
+            tableDiv.innerHTML = '';
+            return;
+        }
+        info.textContent = `${d.row_count} rows in ${d.time_ms}ms`;
+        if (d.rows && d.rows.length > 0) {
+            const cols = Object.keys(d.rows[0]);
+            let html = '<table class="config-table"><thead><tr>';
+            cols.forEach(c => html += `<th>${c}</th>`);
+            html += '</tr></thead><tbody>';
+            d.rows.forEach(r => {
+                html += '<tr>';
+                cols.forEach(c => html += `<td>${r[c] ?? ''}</td>`);
+                html += '</tr>';
+            });
+            html += '</tbody></table>';
+            tableDiv.innerHTML = html;
+        } else {
+            tableDiv.innerHTML = '<p>No rows returned.</p>';
+        }
+    } catch (e) { console.error('[admin2] query error:', e); }
+}
+
+// ================================
+// DARK MODE
+// ================================
+
+document.getElementById('nav-dark-mode-btn')?.addEventListener('click', () => {
+    document.body.classList.toggle('dark-mode');
+    localStorage.setItem('admin2-dark-mode', document.body.classList.contains('dark-mode'));
+    const btn = document.getElementById('nav-dark-mode-btn');
+    if (btn) btn.textContent = document.body.classList.contains('dark-mode') ? 'LIGHT MODE' : 'DARK MODE';
+});
+
+if (localStorage.getItem('admin2-dark-mode') === 'true') {
+    document.body.classList.add('dark-mode');
+    const btn = document.getElementById('nav-dark-mode-btn');
+    if (btn) btn.textContent = 'LIGHT MODE';
+}
+
+// ================================
+// RELAY LETTER ANIMATION
+// ================================
+
+// Animate the RELAY letters with an underline sweep. Fires on every stats
+// refresh so the user gets a visual cue that the page is updating.
+function startRelayAnimation() {
+    const letters = document.querySelectorAll('.relay-letter');
+    if (letters.length === 0) return;
+
+    // Cancel any in-flight animation so rapid refreshes don't overlap
+    if (relayAnimationTimer) { clearTimeout(relayAnimationTimer); relayAnimationTimer = null; }
+
+    let currentIndex = 0;
+    letters.forEach(l => l.classList.remove('underlined'));
+
+    function animateLetter() {
+        letters.forEach(letter => letter.classList.remove('underlined'));
+        if (letters[currentIndex]) {
+            letters[currentIndex].classList.add('underlined');
+        }
+        currentIndex++;
+        if (currentIndex > letters.length) {
+            // Sweep complete — clear underlines and pause before next refresh
+            letters.forEach(letter => letter.classList.remove('underlined'));
+            relayAnimationTimer = null;
+            return;
+        }
+        relayAnimationTimer = setTimeout(animateLetter, 100);
+    }
+    animateLetter();
+}
+
+// ================================
+// RELAY PUBKEY COPY-TO-CLIPBOARD
+// ================================
+
+document.getElementById('relay-pubkey-container')?.addEventListener('click', async () => {
+    const el = document.getElementById('relay-pubkey');
+    if (!el || !el.textContent.trim()) return;
+    try {
+        await navigator.clipboard.writeText(el.textContent.replace(/\s+/g, ''));
+        const container = document.getElementById('relay-pubkey-container');
+        container.classList.add('copied');
+        setTimeout(() => container.classList.remove('copied'), 500);
+    } catch (e) { console.warn('[admin2] clipboard copy failed:', e); }
+});
+
+// ================================
+// AUTH — nostr_login_lite modal
+// ================================
+
+const loginModal = document.getElementById('login-modal');
+const loginModalContainer = document.getElementById('login-modal-container');
+const profileArea = document.getElementById('profile-area');
+const headerUserName = document.getElementById('header-user-name');
+const headerUserImage = document.getElementById('header-user-image');
+const logoutDropdown = document.getElementById('logout-dropdown');
+
+function showLoginModal() {
+    if (loginModal && loginModalContainer) {
+        if (window.NOSTR_LOGIN_LITE && typeof window.NOSTR_LOGIN_LITE.embed === 'function') {
+            // Clear previous embed before re-embedding
+            loginModalContainer.innerHTML = '';
+            window.NOSTR_LOGIN_LITE.embed('#login-modal-container', { seamless: true });
+        }
+        loginModal.style.display = 'flex';
+    }
+}
+
+function hideLoginModal() {
+    if (loginModal) loginModal.style.display = 'none';
+}
+
+function showProfileInHeader() {
+    if (profileArea) profileArea.style.display = 'flex';
+}
+
+function hideProfileFromHeader() {
+    if (profileArea) profileArea.style.display = 'none';
+}
+
+// Toggle logout dropdown when clicking the profile area
+profileArea?.addEventListener('click', (e) => {
+    // Only toggle if the click wasn't on the logout button itself
+    if (e.target.closest('.logout-btn')) return;
+    if (logoutDropdown) {
+        logoutDropdown.style.display = (logoutDropdown.style.display === 'none' || !logoutDropdown.style.display) ? 'block' : 'none';
+    }
+});
+
+// Hide logout dropdown when clicking elsewhere
+document.addEventListener('click', (e) => {
+    if (logoutDropdown && logoutDropdown.style.display === 'block' && !e.target.closest('#profile-area')) {
+        logoutDropdown.style.display = 'none';
+    }
+});
+
+// Update header profile display from logged-in user's pubkey.
+// Sets a placeholder from the npub immediately, then fetches the kind 0
+// profile event from public relays to populate the name + picture.
+function updateProfileDisplay(pubkey) {
+    if (!pubkey) return;
+    let npub = '';
+    try {
+        if (pubkey.length === 64 && /^[0-9a-fA-F]+$/.test(pubkey)) {
+            npub = window.NostrTools.nip19.npubEncode(pubkey);
+        }
+    } catch (err) { console.warn('[admin2] npub encode failed:', err); }
+
+    // Placeholder until the profile fetch resolves
+    if (headerUserName) {
+        headerUserName.textContent = npub ? npub.substring(0, 16) + '…' : pubkey.substring(0, 16) + '…';
+    }
+    if (headerUserImage) headerUserImage.style.display = 'none';
+
+    // Fetch kind 0 profile from public relays (same approach as original api page)
+    loadUserProfile(pubkey, npub);
+}
+
+// Apply profile data to the header name + profile picture.
+// Uses best_name from the server (resolved per profile_name_preference).
+function applyProfileToHeader(name, picture) {
+    if (headerUserName) headerUserName.textContent = name || 'Anonymous User';
+    if (headerUserImage && picture && typeof picture === 'string' &&
+        (picture.startsWith('http://') || picture.startsWith('https://'))) {
+        headerUserImage.src = picture;
+        headerUserImage.style.display = 'block';
+        headerUserImage.onerror = function() { this.style.display = 'none'; };
+    } else if (headerUserImage) {
+        headerUserImage.style.display = 'none';
+    }
+}
+
+// Fetch the user's profile. Tries the local profiles cache first
+// (admin/api/profile.php), then falls back to public relays if the
+// relay has no cached kind-0 for this pubkey.
+async function loadUserProfile(pubkey, npub) {
+    if (!pubkey) return;
+
+    // Try local profiles cache first.
+    try {
+        const res = await fetch('api/profile.php?pubkey=' + encodeURIComponent(pubkey));
+        if (res.ok) {
+            const profile = await res.json();
+            if (profile && profile.best_name !== undefined) {
+                applyProfileToHeader(profile.best_name, profile.picture);
+                console.log('[admin2] profile loaded from local cache for', profile.best_name);
+                return;
+            }
+        }
+    } catch (e) {
+        // Local endpoint not available — fall through to public relays.
+    }
+
+    // Fall back to public relays.
+    if (!window.NostrTools || !window.NostrTools.SimplePool) {
+        if (headerUserName) headerUserName.textContent = npub ? npub.substring(0, 16) + '…' : 'Anonymous User';
+        return;
+    }
+    const relays = [
+        'wss://relay.damus.io',
+        'wss://relay.nostr.band',
+        'wss://nos.lol',
+        'wss://relay.primal.net',
+        'wss://relay.snort.social'
+    ];
+    try {
+        const pool = new window.NostrTools.SimplePool();
+        const timeoutPromise = new Promise((_, reject) =>
+            setTimeout(() => reject(new Error('Profile query timeout')), 5000)
+        );
+        const queryPromise = pool.querySync(relays, {
+            kinds: [0],
+            authors: [pubkey],
+            limit: 1
+        });
+        const events = await Promise.race([queryPromise, timeoutPromise]);
+        try { await pool.close(relays); } catch (e) {}
+
+        if (events && events.length > 0) {
+            const profile = JSON.parse(events[0].content);
+            // Use best_name resolution: display_name first, then name.
+            const name = profile.display_name || profile.name || profile.displayName || 'Anonymous User';
+            const picture = profile.picture || profile.image || null;
+            applyProfileToHeader(name, picture);
+            console.log('[admin2] profile loaded from public relays for', name);
+        } else {
+            if (headerUserName) headerUserName.textContent = 'Anonymous User';
+            console.log('[admin2] no profile event found for', pubkey);
+        }
+    } catch (err) {
+        console.warn('[admin2] profile load failed:', err.message);
+        if (headerUserName) headerUserName.textContent = npub ? npub.substring(0, 16) + '…' : 'Error loading profile';
+    }
+}
+
+// Initialize nostr_login_lite and show modal if not already authenticated
+async function initializeAuth() {
+    if (!window.NOSTR_LOGIN_LITE) {
+        console.warn('[admin2] NOSTR_LOGIN_LITE not loaded — skipping auth modal');
+        return;
+    }
+    try {
+        await window.NOSTR_LOGIN_LITE.init({
+            theme: 'default',
+            methods: {
+                extension: true,
+                local: true,
+                seedphrase: true,
+                readonly: true,
+                connect: true,
+                remote: true,
+                otp: false
+            },
+            floatingTab: { enabled: false }
+        });
+        nlLite = window.NOSTR_LOGIN_LITE;
+        console.log('[admin2] nostr_login_lite initialized');
+
+        // Check for existing auth state
+        let alreadyLoggedIn = false;
+        try {
+            const stored = localStorage.getItem('nostr_login_lite_auth');
+            if (stored) {
+                const parsed = JSON.parse(stored);
+                if (parsed && parsed.pubkey) {
+                    userPubkey = parsed.pubkey;
+                    isLoggedIn = true;
+                    alreadyLoggedIn = true;
+                    showProfileInHeader();
+                    updateProfileDisplay(userPubkey);
+                    hideLoginModal();
+                    console.log('[admin2] existing auth restored for', userPubkey);
+                }
+            }
+        } catch (e) { /* no stored auth */ }
+
+        if (!alreadyLoggedIn) {
+            console.log('[admin2] no existing auth — showing login modal');
+            showLoginModal();
+        }
+
+        // Listen for auth events
+        window.addEventListener('nlMethodSelected', (event) => {
+            const { pubkey, method, error } = event.detail || {};
+            if (method && pubkey) {
+                userPubkey = pubkey;
+                isLoggedIn = true;
+                console.log('[admin2] login success via', method, pubkey);
+                hideLoginModal();
+                showProfileInHeader();
+                updateProfileDisplay(pubkey);
+            } else if (error) {
+                console.warn('[admin2] auth error:', error);
+            }
+        });
+
+        window.addEventListener('nlLogout', () => {
+            console.log('[admin2] logout event received');
+            userPubkey = null;
+            isLoggedIn = false;
+            hideProfileFromHeader();
+            if (logoutDropdown) logoutDropdown.style.display = 'none';
+            showLoginModal();
+        });
+
+    } catch (err) {
+        console.error('[admin2] nostr_login_lite init failed:', err);
+    }
+}
+
+// Logout function — clears auth state and re-shows login modal
+async function logout() {
+    console.log('[admin2] logging out...');
+    try {
+        if (nlLite && typeof nlLite.logout === 'function') {
+            await nlLite.logout();
+        }
+    } catch (e) { console.warn('[admin2] nlLite.logout error:', e); }
+    userPubkey = null;
+    isLoggedIn = false;
+    hideProfileFromHeader();
+    if (logoutDropdown) logoutDropdown.style.display = 'none';
+    showLoginModal();
+    console.log('[admin2] logged out');
+}
+
+// ================================
+// INIT
+// ================================
+
+switchPage('statistics');
+
+// Start the RELAY animation immediately on page load
+startRelayAnimation();
+
+// Initialize auth + load initial chart on DOM ready
+document.addEventListener('DOMContentLoaded', () => {
+    setTimeout(initializeAuth, 100);
+    // Load the default (hour) chart immediately
+    loadChart(currentChartRange);
+});

admin/cache/chart_day.txt

@@ -0,0 +1,15 @@
+                            New Events — Last 24 Hours
+
+ 11 |                                                          X                     
+ 10 |                                                          XX                    
+  9 |                                                          XX                    
+  8 |                                                          XX                    
+  7 |                                                          XX             X     X
+  6 |                                                          XX             X     X
+  5 |                                                          XX             X     X
+  4 |                                                  X       XX             X    XX
+  3 |                                                  X       XXX            X    XX
+  2 |       X                                          X     X XXX            X    XX
+  1 |   X  XX X   X  X  X   X  X  X   X  X  X   X  X  XX  X  X XXXX   X  X  X X X  XX
+    +--------------------------------------------------------------------------------
+     0s   1h   3h   4h   6h   7h   9h   10h  12h  13h  15h  16h  18h  19h  21h  22h 

admin/cache/chart_month.txt

@@ -0,0 +1,15 @@
+                            New Events — Last 30 Days
+
+ 81 |                X                                                               
+ 73 |               XX                          X                                    
+ 65 |               XX                          X                                    
+ 57 |               XX                          X X                             X    
+ 49 |     X  X      XX                         XX X             X               X    
+ 41 |     X  X X    XX     X      X  X    XXX XXX XXX   X       X      X        X    
+ 33 |     X  X X  XXXX    XX  X X X XX    XXX XXXXXXXX  XX      X      X  X  X  X XX 
+ 25 |X   XX XX XX XXXX    XX  XXX X XX  XXXXXXXXXXXXXXXXXXXX XX XXX    X  XX XX XXXXX
+ 17 |X   XXXXX XX XXXXXXXXXXXXXXX X XX XXXXXXXXXXXXXXXXXXXXXXXX XXXXXXXXX XX XXXXXXXX
+  9 |XXX XXXXXXXX XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXXX
+  1 |XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+    +--------------------------------------------------------------------------------
+     0s   1d   3d   5d   7d   9d   11d  13d  15d  16d  18d  20d  22d  24d  26d  28d 

admin/cache/chart_year.txt

@@ -0,0 +1,15 @@
+                              New Events — Last Year
+
+531 |   X                         XX                                                 
+478 |   X   X       X            XXX                                           X     
+425 | X X  XX       X         XX XXX                                           X     
+372 | XXX  XX       X         XX XXX                                           X     
+319 |XXXXXXXXXXX    X    X X XXXXXXX                                           X     
+266 |XXXXXXXXXXXX X XX   XXX XXXXXXXXX                                         X     
+213 |XXXXXXXXXXXXXX XXX  XXXXXXXXXXXXX                                        XX   X 
+160 |XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX  X                   X               XXXX  X 
+107 |XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX XX XX   XX   X X X  XX  XXX X     XXXXXXX  X 
+ 54 |XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXXX XXXXXXXXXXX
+  1 |XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+    +--------------------------------------------------------------------------------
+     0s   22d  45d  68d  91d  114d 136d 159d 182d 205d 228d 250d 273d 296d 319d 342d

admin/index.php

@@ -0,0 +1,429 @@
+<?php
+/**
+ * admin2 — Full PHP admin for C-Relay-PG.
+ * Recreates the original api/ admin interface with a PHP/PDO backend
+ * instead of Nostr WebSocket admin commands.
+ */
+require_once __DIR__ . '/lib/helpers.php';
+$pdo = db();
+
+// Fetch relay info for the header (from config table)
+$relay_name = '';
+$relay_desc = '';
+$relay_pubkey = '';
+$relay_version = '';
+try {
+    $relay_name = $pdo->query("SELECT value FROM config WHERE key = 'relay_name'")->fetchColumn() ?: 'C-Relay-PG';
+    $relay_desc = $pdo->query("SELECT value FROM config WHERE key = 'relay_description'")->fetchColumn() ?: '';
+    $relay_pubkey = $pdo->query("SELECT value FROM config WHERE key = 'relay_pubkey'")->fetchColumn() ?: '';
+    $relay_version = $pdo->query("SELECT value FROM config WHERE key = 'relay_version'")->fetchColumn() ?: '';
+} catch (PDOException $e) {}
+
+// Convert relay pubkey (hex) to npub and format into 3 lines of 3 groups of 7 chars
+$relay_npub = $relay_pubkey;
+if ($relay_pubkey && preg_match('/^[0-9a-fA-F]{64}$/', $relay_pubkey)) {
+    $relay_npub = hex_to_npub($relay_pubkey);
+}
+// Format npub (63 chars) into 3 lines of "xxxxxxx xxxxxxx xxxxxxx"
+$formatted_npub = $relay_npub;
+if (strlen($relay_npub) === 63) {
+    $line1 = substr($relay_npub, 0, 7) . ' ' . substr($relay_npub, 7, 7) . ' ' . substr($relay_npub, 14, 7);
+    $line2 = substr($relay_npub, 21, 7) . ' ' . substr($relay_npub, 28, 7) . ' ' . substr($relay_npub, 35, 7);
+    $line3 = substr($relay_npub, 42, 7) . ' ' . substr($relay_npub, 49, 7) . ' ' . substr($relay_npub, 56, 7);
+    $formatted_npub = $line1 . "\n" . $line2 . "\n" . $line3;
+}
+$display_name = $relay_version ? ($relay_name . ' ' . $relay_version) : $relay_name;
+?>
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>C-Relay-PG Admin</title>
+    <link rel="stylesheet" href="assets/index.css">
+</head>
+
+<body>
+    <!-- Side Navigation Menu -->
+    <nav class="side-nav" id="side-nav">
+        <ul class="nav-menu">
+            <li><button class="nav-item" data-page="statistics">Statistics</button></li>
+            <li><button class="nav-item" data-page="subscriptions">Subscriptions</button></li>
+            <li><button class="nav-item" data-page="configuration">Configuration</button></li>
+            <li><button class="nav-item" data-page="authorization">Authorization</button></li>
+            <li><button class="nav-item" data-page="ip-bans">IP BAN</button></li>
+            <li><button class="nav-item" data-page="relay-events">Relay Events</button></li>
+            <li><button class="nav-item" data-page="caching">Caching</button></li>
+            <li><button class="nav-item" data-page="dm">DM</button></li>
+            <li><button class="nav-item" data-page="database">Database Query</button></li>
+        </ul>
+        <div class="nav-footer">
+            <button class="nav-footer-btn" id="nav-dark-mode-btn">DARK MODE</button>
+        </div>
+    </nav>
+
+    <!-- Side Navigation Overlay -->
+    <div class="side-nav-overlay" id="side-nav-overlay"></div>
+
+    <!-- Header with title and profile display -->
+    <div class="section">
+        <div class="header-content">
+            <div class="header-title clickable" id="header-title" onclick="toggleNav()">
+                <span class="relay-letter" data-letter="R">R</span>
+                <span class="relay-letter" data-letter="E">E</span>
+                <span class="relay-letter" data-letter="L">L</span>
+                <span class="relay-letter" data-letter="A">A</span>
+                <span class="relay-letter" data-letter="Y">Y</span>
+            </div>
+            <div class="relay-info">
+                <div id="relay-name" class="relay-name"><?= e($display_name) ?></div>
+                <div id="relay-description" class="relay-description"><?= e($relay_desc) ?></div>
+                <div id="relay-pubkey-container" class="relay-pubkey-container" title="Click to copy npub">
+                    <div id="relay-pubkey" class="relay-pubkey"><?= e($formatted_npub) ?></div>
+                </div>
+            </div>
+            <div class="profile-area" id="profile-area" style="display: none;">
+                <div class="admin-label">admin</div>
+                <div class="profile-container">
+                    <img id="header-user-image" class="header-user-image" alt="Profile" style="display: none;">
+                    <span id="header-user-name" class="header-user-name">Loading...</span>
+                </div>
+                <!-- Logout dropdown (under admin picture) -->
+                <div class="logout-dropdown" id="logout-dropdown" style="display: none;">
+                    <button type="button" class="logout-btn" onclick="logout()">LOGOUT</button>
+                </div>
+            </div>
+        </div>
+    </div>
+
+    <!-- Login Modal Overlay (nostr_login_lite) -->
+    <div id="login-modal" class="login-modal-overlay" style="display: none;">
+        <div class="login-modal-content">
+            <div id="login-modal-container"></div>
+        </div>
+    </div>
+
+    <!-- Access Denied Overlay (shown when non-admin user logs in) -->
+    <div id="access-denied-overlay" class="access-denied-overlay" style="display: none;">
+        <div class="access-denied-content">
+            <div class="access-denied-icon">⛔</div>
+            <h2>ACCESS DENIED</h2>
+            <p class="access-denied-message">This interface is restricted to the relay administrator.</p>
+            <p class="access-denied-submessage">The logged-in account does not have admin privileges.</p>
+            <button type="button" class="access-denied-logout-btn" onclick="logout()">LOGOUT</button>
+        </div>
+    </div>
+
+    <!-- DATABASE STATISTICS Section -->
+    <div class="section flex-section" id="databaseStatisticsSection">
+        <div class="section-header">DATABASE STATISTICS</div>
+
+        <!-- Event Rate Graph — range selector tabs + ASCII chart (server-rendered) -->
+        <div class="chart-range-tabs">
+            <button class="chart-tab active" data-range="hour">1H</button>
+            <button class="chart-tab" data-range="day">1D</button>
+            <button class="chart-tab" data-range="month">1M</button>
+            <button class="chart-tab" data-range="year">1Y</button>
+        </div>
+        <div id="event-rate-chart" class="event-rate-chart-container">Loading chart...</div>
+
+        <!-- Database Overview Table -->
+        <div class="input-group">
+            <div class="config-table-container">
+                <table class="config-table" id="stats-overview-table">
+                    <thead><tr><th>Metric</th><th>Value</th></tr></thead>
+                    <tbody id="stats-overview-table-body">
+                        <tr><td>Database Size</td><td id="db-size">-</td></tr>
+                        <tr><td>Total Events</td><td id="total-events">-</td></tr>
+                        <tr><td>Process ID</td><td id="process-id">-</td></tr>
+                        <tr><td>WebSocket Connections</td><td id="websocket-connections">-</td></tr>
+                        <tr><td>Active Subscriptions</td><td id="active-subscriptions">-</td></tr>
+                        <tr><td>Memory Usage</td><td id="memory-usage">-</td></tr>
+                        <tr><td>CPU Usage</td><td id="cpu-usage">-</td></tr>
+                        <tr><td>CPU Core</td><td id="cpu-core">-</td></tr>
+                        <tr><td>Oldest Event</td><td id="oldest-event">-</td></tr>
+                        <tr><td>Newest Event</td><td id="newest-event">-</td></tr>
+                    </tbody>
+                </table>
+            </div>
+        </div>
+
+        <!-- Event Kind Distribution Table -->
+        <div class="input-group">
+            <label>Event Kind Distribution:</label>
+            <div class="config-table-container">
+                <table class="config-table" id="stats-kinds-table">
+                    <thead><tr><th>Event Kind</th><th>Count</th><th>Percentage</th></tr></thead>
+                    <tbody id="stats-kinds-table-body">
+                        <tr><td colspan="3" style="text-align: center; font-style: italic;">Loading...</td></tr>
+                    </tbody>
+                </table>
+            </div>
+        </div>
+
+        <!-- Time-based Statistics Table -->
+        <div class="input-group">
+            <label>Time-based Statistics:</label>
+            <div class="config-table-container">
+                <table class="config-table" id="stats-time-table">
+                    <thead><tr><th>Period</th><th>Events</th></tr></thead>
+                    <tbody id="stats-time-table-body">
+                        <tr><td>Last 24 Hours</td><td id="events-24h">-</td></tr>
+                        <tr><td>Last 7 Days</td><td id="events-7d">-</td></tr>
+                        <tr><td>Last 30 Days</td><td id="events-30d">-</td></tr>
+                    </tbody>
+                </table>
+            </div>
+        </div>
+
+        <!-- Top Pubkeys Table -->
+        <div class="input-group">
+            <label>Top Pubkeys by Event Count:</label>
+            <div class="config-table-container">
+                <table class="config-table" id="stats-pubkeys-table">
+                    <thead><tr><th>Rank</th><th>Name</th><th>Pubkey</th><th>Event Count</th><th>Percentage</th></tr></thead>
+                    <tbody id="stats-pubkeys-table-body">
+                        <tr><td colspan="5" style="text-align: center; font-style: italic;">Loading...</td></tr>
+                    </tbody>
+                </table>
+            </div>
+        </div>
+
+        <!-- Name-field usage stats (from profiles cache) -->
+        <div class="input-group" id="name-field-usage" style="display:none;"></div>
+    </div>
+
+    <!-- SUBSCRIPTION DETAILS Section -->
+    <div class="section flex-section" id="subscriptionDetailsSection" style="display: none;">
+        <div class="section-header">ACTIVE SUBSCRIPTION DETAILS</div>
+        <div class="input-group">
+            <div class="config-table-container">
+                <table class="config-table" id="subscription-details-table">
+                    <thead><tr><th>Sub ID</th><th>Pubkey</th><th>Filters</th><th>Created</th><th>Events Sent</th></tr></thead>
+                    <tbody id="subscription-details-table-body">
+                        <tr><td colspan="5" style="text-align: center; font-style: italic;">Loading...</td></tr>
+                    </tbody>
+                </table>
+            </div>
+        </div>
+    </div>
+
+    <!-- CONFIGURATION Section -->
+    <div id="div_config" class="section flex-section" style="display: none;">
+        <div class="section-header">RELAY CONFIGURATION</div>
+        <div id="config-display">
+            <div class="config-table-container">
+                <table class="config-table" id="config-table">
+                    <thead><tr><th>Parameter</th><th>Value</th><th>Actions</th></tr></thead>
+                    <tbody id="config-table-body">
+                        <tr><td colspan="3" style="text-align: center; font-style: italic;">Loading...</td></tr>
+                    </tbody>
+                </table>
+            </div>
+            <div class="inline-buttons">
+                <button type="button" id="fetch-config-btn" onclick="loadConfig()">REFRESH</button>
+            </div>
+        </div>
+    </div>
+
+    <!-- AUTH RULES Section -->
+    <div class="section flex-section" id="authRulesSection" style="display: none;">
+        <div class="section-header">AUTH RULES MANAGEMENT</div>
+        <div id="authRulesTableContainer">
+            <table class="config-table" id="authRulesTable">
+                <thead><tr><th>Rule Type</th><th>Pattern Type</th><th>Pattern Value</th><th>Status</th><th>Actions</th></tr></thead>
+                <tbody id="authRulesTableBody">
+                    <tr><td colspan="5" style="text-align: center; font-style: italic;">Loading...</td></tr>
+                </tbody>
+            </table>
+        </div>
+        <div id="authRuleInputSections" style="display: block;">
+            <div class="input-group">
+                <label for="authRulePubkey">Public Key (npub or hex):</label>
+                <input type="text" id="authRulePubkey" placeholder="npub1... or 64-character hex pubkey">
+            </div>
+            <div class="inline-buttons">
+                <button type="button" onclick="addAuthRule('whitelist')">ADD TO WHITELIST</button>
+                <button type="button" onclick="addAuthRule('blacklist')">ADD TO BLACKLIST</button>
+                <button type="button" onclick="loadAuthRules()">REFRESH</button>
+            </div>
+        </div>
+    </div>
+
+    <!-- WEB OF TRUST Section -->
+    <div class="section flex-section" id="wotSection" style="display: none;">
+        <div class="section-header">WEB OF TRUST</div>
+        <div id="wotKind3Status" class="wot-status-row">
+            <span>Admin Contact List (kind 3):</span>
+            <span id="wotKind3Indicator" class="wot-indicator wot-unknown">Loading...</span>
+        </div>
+        <div class="wot-level-selector">
+            <label>WoT Level:</label>
+            <div class="inline-buttons">
+                <button type="button" class="wot-level-btn" onclick="setWotLevel(0)">OFF</button>
+                <button type="button" class="wot-level-btn" onclick="setWotLevel(1)">WRITE ONLY</button>
+                <button type="button" class="wot-level-btn" onclick="setWotLevel(2)">FULL</button>
+            </div>
+            <div class="wot-level-description" id="wotLevelDescription">Loading...</div>
+        </div>
+        <div class="wot-stats-row">
+            <span>Whitelisted Pubkeys:</span>
+            <span id="wotWhitelistCount">—</span>
+        </div>
+        <div class="inline-buttons">
+            <button type="button" onclick="syncWot()">SYNC FROM KIND 3</button>
+            <button type="button" onclick="loadWotStatus()">REFRESH STATUS</button>
+        </div>
+    </div>
+
+    <!-- NIP-17 DIRECT MESSAGES Section -->
+    <div class="section" id="nip17DMSection" style="display: none;">
+        <div class="section-header"><h2>NIP-17 DIRECT MESSAGES</h2></div>
+        <div class="input-group">
+            <label>Received Messages (kind 4/14/15):</label>
+            <div id="dm-inbox" class="log-panel" style="height: 300px; overflow-y: auto;">
+                <div class="log-entry">Loading...</div>
+            </div>
+        </div>
+    </div>
+
+    <!-- IP BANS Section -->
+    <div class="section" id="ipBansSection" style="display: none;">
+        <div class="section-header">IP BAN MANAGEMENT</div>
+        <div class="input-group">
+            <div class="config-table-container">
+                <table class="config-table" id="ip-bans-stats-table">
+                    <thead><tr><th>Total IPs Tracked</th><th>Currently Banned</th><th>Total Bans Issued</th></tr></thead>
+                    <tbody>
+                        <tr><td id="ip-bans-total">-</td><td id="ip-bans-active">-</td><td id="ip-bans-issued">-</td></tr>
+                    </tbody>
+                </table>
+            </div>
+        </div>
+        <div class="input-group">
+            <h3>Manually Ban IP Address</h3>
+            <div class="form-group">
+                <label for="ban-ip-input">IP Address:</label>
+                <input type="text" id="ban-ip-input" placeholder="192.168.1.100">
+            </div>
+            <div class="form-group">
+                <label for="ban-duration-select">Ban Duration:</label>
+                <select id="ban-duration-select">
+                    <option value="3600">1 Hour</option>
+                    <option value="86400" selected>24 Hours</option>
+                    <option value="604800">7 Days</option>
+                    <option value="2592000">30 Days</option>
+                    <option value="31536000">1 Year</option>
+                    <option value="999999999">Permanent</option>
+                </select>
+            </div>
+            <div class="inline-buttons">
+                <button type="button" onclick="addBan()">BAN IP</button>
+                <button type="button" onclick="loadIpBans()">REFRESH</button>
+            </div>
+            <div id="add-ban-status" class="status-message"></div>
+        </div>
+        <div class="input-group">
+            <label>Banned IP Addresses:</label>
+            <div class="config-table-container">
+                <table class="config-table" id="ip-bans-table">
+                    <thead><tr><th>IP Address</th><th>Status</th><th>Banned Until</th><th>Failures</th><th>Actions</th></tr></thead>
+                    <tbody id="ip-bans-tbody">
+                        <tr><td colspan="5" style="text-align: center;">Loading...</td></tr>
+                    </tbody>
+                </table>
+            </div>
+        </div>
+    </div>
+
+    <!-- RELAY EVENTS Section -->
+    <div class="section" id="relayEventsSection" style="display: none;">
+        <div class="section-header">RELAY EVENTS MANAGEMENT</div>
+        <div class="input-group">
+            <h3>Recent Events</h3>
+            <div class="inline-buttons">
+                <button type="button" onclick="loadEvents()">REFRESH</button>
+            </div>
+            <div class="config-table-container">
+                <table class="config-table" id="live-relay-events-table">
+                    <thead><tr><th>Time</th><th>Kind</th><th>Name</th><th>ID</th><th>Content Preview</th></tr></thead>
+                    <tbody id="live-relay-events-table-body">
+                        <tr><td colspan="5" style="text-align: center;">Loading...</td></tr>
+                    </tbody>
+                </table>
+            </div>
+        </div>
+    </div>
+
+    <!-- CACHING Section -->
+    <div class="section" id="cachingSection" style="display: none;">
+        <div class="section-header">CACHING</div>
+        <div class="input-group">
+            <h3>Caching Controls</h3>
+            <div id="caching-controls" class="inline-buttons">
+                <span id="caching-enabled-label">Caching: ?</span>
+                <button type="button" id="caching-toggle-btn" onclick="toggleCachingEnabled()">Toggle Caching</button>
+                <span id="caching-inbox-enabled-label">Inbox: ?</span>
+                <button type="button" id="caching-inbox-toggle-btn" onclick="toggleCachingInboxEnabled()">Toggle Inbox</button>
+            </div>
+        </div>
+        <div class="input-group">
+            <h3>Caching Service Status</h3>
+            <div id="caching-service-status" class="status-display">
+                <p>Loading...</p>
+            </div>
+            <div class="inline-buttons" style="margin-top:8px">
+                <button type="button" id="caching-rerun-all-btn" onclick="rerunAllCaching()">Re-run All Caching</button>
+            </div>
+        </div>
+        <div class="input-group">
+            <h3>Relay Inbox Status</h3>
+            <div id="caching-inbox-status" class="status-display">
+                <p>Loading...</p>
+            </div>
+        </div>
+        <div class="input-group">
+            <h3>Followed Pubkeys <span style="font-size:11px;font-weight:normal;color:var(--text-muted,#888)">(click a row for per-relay details)</span></h3>
+            <div id="caching-follows-status" class="status-message"></div>
+            <div class="config-table-container">
+                <table class="config-table" id="caching-follows-table">
+                    <thead><tr><th>Name</th><th>npub</th><th>Root?</th><th>Events in DB</th><th>Backfill</th><th>Relays</th></tr></thead>
+                    <tbody id="caching-follows-table-body">
+                        <tr><td colspan="6" style="text-align: center; font-style: italic;">Loading...</td></tr>
+                    </tbody>
+                </table>
+            </div>
+        </div>
+        <div class="inline-buttons">
+            <button type="button" onclick="loadCaching()">REFRESH</button>
+        </div>
+    </div>
+
+    <!-- SQL QUERY Section -->
+    <div class="section" id="sqlQuerySection" style="display: none;">
+        <div class="section-header"><h2>SQL QUERY CONSOLE</h2></div>
+        <div class="input-group">
+            <label for="sql-input">SQL Query (SELECT only):</label>
+            <textarea id="sql-input" rows="5" placeholder="SELECT * FROM events LIMIT 10"></textarea>
+        </div>
+        <div class="input-group">
+            <div class="inline-buttons">
+                <button type="button" onclick="executeQuery()">EXECUTE QUERY</button>
+                <button type="button" onclick="document.getElementById('sql-input').value=''">CLEAR</button>
+            </div>
+        </div>
+        <div class="input-group">
+            <label>Query Results:</label>
+            <div id="query-info" class="info-box"></div>
+            <div id="query-table" class="config-table-container"></div>
+        </div>
+    </div>
+
+    <!-- Nostr libraries for nostr_login_lite auth modal -->
+    <script src="assets/nostr.bundle.js"></script>
+    <script src="assets/nostr-lite.js"></script>
+    <script src="assets/app.js"></script>
+</body>
+
+</html>

admin/lib/ascii_chart.php

@@ -0,0 +1,147 @@
+<?php
+/**
+ * admin2/lib/ascii_chart.php — Server-side ASCII X-bar chart renderer.
+ *
+ * Produces a monospaced ASCII bar chart (using 'X' characters) from an
+ * array of bin counts. Mirrors the layout of the original text_graph.js
+ * ASCIIBarChart: Y-axis count labels, X-bar columns, X-axis with
+ * elapsed-time labels.
+ *
+ * The output is a plain text string suitable for both browser <div>
+ * injection (white-space: pre) and terminal display via curl.
+ */
+
+/**
+ * Render an ASCII bar chart from an array of bin counts.
+ *
+ * @param array  $bins     Array of integer counts (one per time bin, left=oldest)
+ * @param array  $options  {
+ *     @var string $title         Chart title (centered at top)
+ *     @var int    $max_height    Chart height in rows (default 11)
+ *     @var string $x_axis_label  Label below the X-axis (default '')
+ *     @var int    $bin_duration  Seconds per bin — for X-axis elapsed labels
+ *     @var int    $label_interval Label every N bins (default 5)
+ * }
+ * @return string The ASCII chart as a multi-line string.
+ */
+function render_ascii_chart(array $bins, array $options = []): string {
+    $title         = $options['title'] ?? 'New Events';
+    $max_height    = $options['max_height'] ?? 11;
+    $x_axis_label  = $options['x_axis_label'] ?? '';
+    $bin_duration  = $options['bin_duration'] ?? 10;
+    $label_interval = $options['label_interval'] ?? 5;
+
+    $num_bins = count($bins);
+    if ($num_bins === 0) {
+        return "No data available.\n";
+    }
+
+    $max_count = max($bins);
+    if ($max_count < 1) $max_count = 1; // Avoid division by zero for all-empty bins
+
+    // Scaling: each X represents scale_factor counts
+    $scale_factor = max(1, (int)ceil($max_count / $max_height));
+    $scaled_max = (int)ceil($max_count / $scale_factor) * $scale_factor;
+
+    $output = '';
+
+    // --- Title (centered) ---
+    $chart_width = 4 + $num_bins; // 4 = Y-axis number width (3) + separator (1)
+    if ($title !== '') {
+        $title_padding = (int)floor(($chart_width - strlen($title)) / 2);
+        if ($title_padding < 0) $title_padding = 0;
+        $output .= str_repeat(' ', $title_padding) . $title . "\n\n";
+    }
+
+    // --- Bar rows (top to bottom) ---
+    for ($row = $max_height; $row > 0; $row--) {
+        $row_count = ($row - 1) * $scale_factor + 1;
+        $line = str_pad((string)$row_count, 3, ' ', STR_PAD_LEFT) . ' |';
+
+        for ($i = 0; $i < $num_bins; $i++) {
+            $count = $bins[$i];
+            $scaled_height = ($count > 0) ? (int)ceil($count / $scale_factor) : 0;
+            $line .= ($scaled_height >= $row) ? 'X' : ' ';
+        }
+        $output .= $line . "\n";
+    }
+
+    // --- X-axis line ---
+    $output .= '    +' . str_repeat('-', $num_bins) . "\n";
+
+    // --- X-axis labels (elapsed time every label_interval bins) ---
+    $label_line = '     ';
+    $labels = [];
+    for ($i = 0; $i < $num_bins; $i++) {
+        if ($i % $label_interval === 0) {
+            $elapsed_sec = $i * $bin_duration;
+            $labels[] = format_elapsed_time($elapsed_sec);
+        }
+    }
+    // Build label line with spacing
+    for ($i = 0; $i < count($labels); $i++) {
+        $label_line .= $labels[$i];
+        if ($i < count($labels) - 1) {
+            $spacing = $label_interval - strlen($labels[$i]);
+            if ($spacing < 1) $spacing = 1;
+            $label_line .= str_repeat(' ', $spacing);
+        }
+    }
+    // Pad to match X-axis dash line length
+    $min_label_len = 4 + $num_bins;
+    if (strlen($label_line) < $min_label_len) {
+        $label_line .= str_repeat(' ', $min_label_len - strlen($label_line));
+    }
+    $output .= $label_line . "\n";
+
+    // --- X-axis label (if provided) ---
+    if ($x_axis_label !== '') {
+        $label_pad = (int)floor(($num_bins - strlen($x_axis_label)) / 2);
+        if ($label_pad < 0) $label_pad = 0;
+        $output .= "\n" . '     ' . str_repeat(' ', $label_pad) . $x_axis_label . "\n";
+    }
+
+    return $output;
+}
+
+/**
+ * Format an elapsed time in seconds as a compact label.
+ *   < 60s  → "Ns"
+ *   < 1h   → "Nm"
+ *   < 1d   → "Nh"
+ *   else   → "Nd"
+ */
+function format_elapsed_time(int $seconds): string {
+    if ($seconds < 60) {
+        return $seconds . 's';
+    } elseif ($seconds < 3600) {
+        return (int)floor($seconds / 60) . 'm';
+    } elseif ($seconds < 86400) {
+        return (int)floor($seconds / 3600) . 'h';
+    } else {
+        return (int)floor($seconds / 86400) . 'd';
+    }
+}
+
+/**
+ * Build a fixed-length bin array from SQL query rows.
+ *
+ * The query returns only non-empty bins. This function creates a
+ * zero-filled array of $num_bins length and overlays the counts
+ * at the correct positions, so empty time slots show as blank
+ * columns — the chart always advances in time.
+ *
+ * @param array $rows    Query rows with 'bin' (int) and 'cnt' (int)
+ * @param int   $num_bins  Total number of bins (fixed length)
+ * @return array Zero-filled array of counts
+ */
+function build_bin_array(array $rows, int $num_bins): array {
+    $bins = array_fill(0, $num_bins, 0);
+    foreach ($rows as $r) {
+        $idx = (int)$r['bin'];
+        if ($idx >= 0 && $idx < $num_bins) {
+            $bins[$idx] = (int)$r['cnt'];
+        }
+    }
+    return $bins;
+}

admin/lib/config.php

@@ -0,0 +1,27 @@
+<?php
+/**
+ * C-Relay-PG Admin — Database connection configuration.
+ *
+ * This file is NOT web-accessible (denied by nginx location block).
+ * It contains the PostgreSQL connection string used by all admin pages.
+ *
+ * Edit these values to match your relay's PostgreSQL credentials.
+ */
+
+// PostgreSQL connection parameters.
+// These should match the --db-* flags passed to the c-relay-pg binary
+// or the connection string passed to caching_relay -p "...".
+return [
+    'db_host'     => 'localhost',
+    'db_port'     => '5432',
+    'db_name'     => 'crelay',
+    'db_user'     => 'crelay',
+    'db_password' => 'crelay',
+
+    // Page sizes for paginated tables.
+    'follows_per_page' => 50,
+    'relays_per_page'  => 50,
+
+    // Auto-refresh interval for dashboard polling (milliseconds).
+    'refresh_ms' => 10000,
+];

admin/lib/db.php

@@ -0,0 +1,48 @@
+<?php
+/**
+ * C-Relay-PG Admin — PDO database connection helper.
+ *
+ * Provides a singleton PDO connection to the relay's PostgreSQL database.
+ * All admin pages use db() to get the connection.
+ */
+
+require_once __DIR__ . '/config.php';
+
+function db(): PDO {
+    static $pdo = null;
+    if ($pdo === null) {
+        $cfg = require __DIR__ . '/config.php';
+        // Build DSN — supports both TCP (host=localhost) and Unix socket
+        // (host=/var/run/postgresql). Omit password if empty (peer auth).
+        $dsn = sprintf(
+            'pgsql:host=%s;port=%d;dbname=%s;user=%s',
+            $cfg['db_host'],
+            $cfg['db_port'],
+            $cfg['db_name'],
+            $cfg['db_user']
+        );
+        if (!empty($cfg['db_password'])) {
+            $dsn .= ';password=' . $cfg['db_password'];
+        }
+        try {
+            $pdo = new PDO($dsn, null, null, [
+                PDO::ATTR_ERRMODE            => PDO::ERRMODE_EXCEPTION,
+                PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC,
+                PDO::ATTR_EMULATE_PREPARES   => false,
+            ]);
+        } catch (PDOException $e) {
+            http_response_code(500);
+            die('Database connection failed: ' . htmlspecialchars($e->getMessage()));
+        }
+    }
+    return $pdo;
+}
+
+/** Get a config value from the admin config file. */
+function cfg(string $key, $default = null) {
+    static $cfg = null;
+    if ($cfg === null) {
+        $cfg = require __DIR__ . '/config.php';
+    }
+    return $cfg[$key] ?? $default;
+}

admin/lib/helpers.php

@@ -0,0 +1,247 @@
+<?php
+/**
+ * C-Relay-PG Admin — Shared helper functions.
+ */
+
+require_once __DIR__ . '/db.php';
+
+/** HTML-escape a string. */
+function e(?string $s): string {
+    return htmlspecialchars($s ?? '', ENT_QUOTES, 'UTF-8');
+}
+
+/** Format a Unix timestamp as a human-readable relative time. */
+function time_ago(int $ts): string {
+    if ($ts <= 0) return 'never';
+    $diff = time() - $ts;
+    if ($diff < 60)    return $diff . 's ago';
+    if ($diff < 3600)  return floor($diff / 60) . 'm ago';
+    if ($diff < 86400) return floor($diff / 3600) . 'h ago';
+    return floor($diff / 86400) . 'd ago';
+}
+
+/** Format a Unix timestamp as a date/time string. */
+function fmt_date(int $ts): string {
+    if ($ts <= 0) return '-';
+    return date('Y-m-d H:i:s', $ts);
+}
+
+/**
+ * Convert a 64-char hex pubkey to npub (bech32).
+ * Uses the standard bech32 encoding (NIP-19).
+ */
+function hex_to_npub(string $hex): string {
+    if (!preg_match('/^[0-9a-fA-F]{64}$/', $hex)) return $hex;
+    $hex = strtolower($hex);
+
+    // Bech32 constants
+    $charset = 'qpzry9x8gf2tvdw0s3jn54khce6mua7l';
+    $data = [];
+    for ($i = 0; $i < strlen($hex); $i += 2) {
+        $data[] = intval(substr($hex, $i, 2), 16);
+    }
+    // Convert 8-bit groups to 5-bit groups
+    $conv = [];
+    $buffer = 0;
+    $bits = 0;
+    foreach ($data as $byte) {
+        $buffer = ($buffer << 8) | $byte;
+        $bits += 8;
+        while ($bits >= 5) {
+            $conv[] = ($buffer >> ($bits - 5)) & 31;
+            $bits -= 5;
+        }
+    }
+    if ($bits > 0) {
+        $conv[] = ($buffer << (5 - $bits)) & 31;
+    }
+
+    // Compute checksum — HRP values are positions of each char in the charset.
+    $values = array_merge(
+        array_map(function($c) {
+            return strpos('qpzry9x8gf2tvdw0s3jn54khce6mua7l', $c);
+        }, str_split('npub')),
+        $conv
+    );
+    $gen = [0x3b6a57b2, 0x26508e6d, 0x1ea119fa, 0x3d4233dd, 0x2a1462b3];
+    $chk = 1;
+    foreach ($values as $v) {
+        $top = $chk >> 25;
+        $chk = (($chk & 0x1ffffff) << 5) ^ $v;
+        for ($i = 0; $i < 5; $i++) {
+            if (($top >> $i) & 1) $chk ^= $gen[$i];
+        }
+    }
+    $chk ^= 1;
+    $checksum = [];
+    for ($i = 0; $i < 6; $i++) {
+        $checksum[] = ($chk >> (5 * (5 - $i))) & 31;
+    }
+
+    $result = 'npub1';
+    foreach (array_merge($conv, $checksum) as $v) {
+        $result .= $charset[$v];
+    }
+    return $result;
+}
+
+/** Truncate a string to $len chars with ellipsis. */
+function trunc(string $s, int $len = 16): string {
+    if (strlen($s) <= $len) return $s;
+    return substr($s, 0, $len) . '…';
+}
+
+/** Build pagination links HTML. */
+function pagination(int $page, int $per_page, int $total, string $base_url): string {
+    $total_pages = max(1, ceil($total / $per_page));
+    if ($total_pages <= 1) return '';
+
+    $html = '<div class="pagination">';
+    if ($page > 1) {
+        $html .= '<a href="' . e($base_url) . '?page=' . ($page - 1) . '">← Prev</a>';
+    }
+    $html .= '<span>Page ' . $page . ' of ' . $total_pages . ' (' . $total . ' total)</span>';
+    if ($page < $total_pages) {
+        $html .= '<a href="' . e($base_url) . '?page=' . ($page + 1) . '">Next →</a>';
+    }
+    $html .= '</div>';
+    return $html;
+}
+
+/** Get the current page number from the query string. */
+function current_page(): int {
+    $p = intval($_GET['page'] ?? 1);
+    return max(1, $p);
+}
+
+/** JSON response helper for AJAX endpoints. */
+function json_response($data): void {
+    header('Content-Type: application/json');
+    echo json_encode($data, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE);
+    exit;
+}
+
+/** Get a query parameter with a default. */
+function query_param(string $key, $default = null) {
+    return $_GET[$key] ?? $default;
+}
+
+/**
+ * Batch-resolve profiles from the profiles cache table.
+ * Returns [pubkey_hex => ['name'=>..., 'display_name'=>...,
+ *                         'best_name'=>..., 'picture'=>..., 'nip05'=>...]].
+ * Pubkeys with no cached profile are absent from the result.
+ */
+function profile_map(array $pubkeys): array {
+    if (empty($pubkeys)) return [];
+    $pdo = db();
+    $map = [];
+    try {
+        // Build parameterized IN clause: WHERE pubkey = ANY(?)
+        // PDO PostgreSQL supports passing an array as a string literal.
+        $placeholders = implode(',', array_fill(0, count($pubkeys), '?'));
+        $stmt = $pdo->prepare(
+            "SELECT pubkey, name, display_name, picture, nip05 FROM profiles "
+            . "WHERE pubkey IN ($placeholders)"
+        );
+        $stmt->execute(array_values($pubkeys));
+        $rows = $stmt->fetchAll();
+        foreach ($rows as $r) {
+            $map[$r['pubkey']] = [
+                'name'         => $r['name'] ?? '',
+                'display_name' => $r['display_name'] ?? '',
+                'best_name'    => profile_display_name($r),
+                'picture'      => $r['picture'] ?? '',
+                'nip05'        => $r['nip05'] ?? '',
+            ];
+        }
+    } catch (PDOException $e) {}
+    return $map;
+}
+
+/**
+ * Apply the profile_name_preference config key to resolve the display name.
+ * Never returns null. Returns '' if neither field is set.
+ */
+function profile_display_name(array $profile): string {
+    $name = $profile['name'] ?? '';
+    $display_name = $profile['display_name'] ?? '';
+    static $pref = null;
+    if ($pref === null) {
+        try {
+            $pdo = db();
+            $pref = $pdo->query("SELECT value FROM config WHERE key = 'profile_name_preference'")->fetchColumn() ?: 'display_name';
+        } catch (PDOException $e) {
+            $pref = 'display_name';
+        }
+    }
+    if ($pref === 'name') {
+        return $name !== '' ? $name : $display_name;
+    }
+    // Default: prefer display_name, fall back to name.
+    return $display_name !== '' ? $display_name : $name;
+}
+
+/**
+ * Render the shared HTML header with side navigation.
+ * Pass the active page name to highlight the current nav item.
+ */
+function admin_header(string $active = '', string $title = 'C-Relay-PG Admin'): void {
+    $pages = [
+        'dashboard' => ['index.php',       'Dashboard'],
+        'follows'   => ['follows.php',     'Follows'],
+        'relays'    => ['relays.php',      'Relays'],
+        'config'    => ['config-edit.php', 'Config'],
+        'inbox'     => ['inbox.php',       'Inbox'],
+    ];
+?>
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title><?= e($title) ?></title>
+    <link rel="stylesheet" href="assets/style.css">
+</head>
+<body>
+    <!-- Side Navigation -->
+    <nav class="side-nav" id="side-nav">
+        <ul class="nav-menu">
+<?php foreach ($pages as $key => [$url, $label]): ?>
+            <li><a class="nav-item<?= $active === $key ? ' active' : '' ?>" href="<?= e($url) ?>"><?= e($label) ?></a></li>
+<?php endforeach; ?>
+        </ul>
+    </nav>
+    <div class="side-nav-overlay" id="side-nav-overlay" onclick="closeNav()"></div>
+
+    <!-- Header -->
+    <div class="main-header">
+        <div class="header-content">
+            <button class="menu-btn" onclick="openNav()">☰</button>
+            <div class="header-title" onclick="location.href='index.php'">
+                <span class="relay-letter">R</span><span class="relay-letter">E</span><span class="relay-letter">L</span><span class="relay-letter">A</span><span class="relay-letter">Y</span>
+            </div>
+            <div style="width:40px"></div>
+        </div>
+    </div>
+
+    <script>
+    function openNav() {
+        document.getElementById('side-nav').classList.add('open');
+        document.getElementById('side-nav-overlay').classList.add('show');
+    }
+    function closeNav() {
+        document.getElementById('side-nav').classList.remove('open');
+        document.getElementById('side-nav-overlay').classList.remove('show');
+    }
+    </script>
+<?php
+}
+
+/** Render the shared HTML footer. */
+function admin_footer(): void {
+?>
+</body>
+</html>
+<?php
+}

admin/serve.sh

@@ -0,0 +1,27 @@
+#!/bin/bash
+# Launch the admin2 PHP built-in server, fully detached from the calling shell.
+# Usage: ./admin2/serve.sh [port]   (default port 8088)
+PORT="${1:-8088}"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+# Kill any existing instance on this port.
+pkill -f "php -S 127.0.0.1:$PORT" 2>/dev/null
+sleep 1
+
+# Start fully detached in its own session so SIGTERM to the launcher
+# does not propagate to the PHP server.
+setsid php -S 127.0.0.1:$PORT -t "$SCRIPT_DIR" > "$SCRIPT_DIR/php_server.log" 2>&1 < /dev/null &
+PHP_PID=$!
+disown $PHP_PID 2>/dev/null
+
+# Give it a moment to bind, then report.
+sleep 1
+if kill -0 "$PHP_PID" 2>/dev/null; then
+    echo "admin PHP server started on http://127.0.0.1:$PORT (PID $PHP_PID)"
+    echo "Serving from: $SCRIPT_DIR"
+    echo "Log: $SCRIPT_DIR/php_server.log"
+else
+    echo "ERROR: PHP server failed to start. Log:"
+    cat "$SCRIPT_DIR/php_server.log" 2>/dev/null
+    exit 1
+fi

api/embedded.html

@@ -0,0 +1,58 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Embedded NOSTR_LOGIN_LITE</title>
+  <style>
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+      margin: 0;
+      padding: 40px;
+      background: white;
+      display: flex;
+      justify-content: center;
+      align-items: center;
+      min-height: 100vh;
+    }
+
+    .container {
+      max-width: 400px;
+      width: 100%;
+    }
+
+    #login-container {
+      /* No styling - let embedded modal blend seamlessly */
+    }
+  </style>
+</head>
+<body>
+  <div class="container">
+    <div id="login-container"></div>
+  </div>
+
+  <script src="../lite/nostr.bundle.js"></script>
+  <script src="../lite/nostr-lite.js"></script>
+
+  <script>
+    document.addEventListener('DOMContentLoaded', async () => {
+      await window.NOSTR_LOGIN_LITE.init({
+        theme:'default',
+        methods: {
+          extension: true,
+          local: true,
+          seedphrase: true,
+          readonly: true,
+          connect: true,
+          remote: true,
+          otp: true
+        }
+      });
+
+      window.NOSTR_LOGIN_LITE.embed('#login-container', {
+        seamless: true
+      });
+    });
+  </script>
+</body>
+</html>

api/index.html

@@ -0,0 +1,811 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>C-Relay-PG Admin</title>
+    <link rel="stylesheet" href="/api/index.css">
+</head>
+
+<body>
+    <!-- Side Navigation Menu -->
+    <nav class="side-nav" id="side-nav">
+        <ul class="nav-menu">
+            <li><button class="nav-item" data-page="statistics">Statistics</button></li>
+            <li><button class="nav-item" data-page="subscriptions">Subscriptions</button></li>
+            <li><button class="nav-item" data-page="configuration">Configuration</button></li>
+            <li><button class="nav-item" data-page="authorization">Authorization</button></li>
+            <li><button class="nav-item" data-page="ip-bans">IP BANS</button></li>
+            <li><button class="nav-item" data-page="relay-events">Relay Events</button></li>
+            <li><button class="nav-item" data-page="caching">Caching</button></li>
+            <li><button class="nav-item" data-page="dm">DM</button></li>
+            <li><button class="nav-item" data-page="database">Database Query</button></li>
+        </ul>
+        <div class="nav-footer">
+            <button class="nav-footer-btn" id="nav-dark-mode-btn">DARK MODE</button>
+            <button class="nav-footer-btn" id="nav-logout-btn">LOGOUT</button>
+        </div>
+    </nav>
+
+    <!-- Side Navigation Overlay -->
+    <div class="side-nav-overlay" id="side-nav-overlay"></div>
+
+    <!-- Header with title and profile display -->
+    <div class="section">
+
+        <div class="header-content">
+            <div class="header-title clickable" id="header-title">
+                <span class="relay-letter" data-letter="R">R</span>
+                <span class="relay-letter" data-letter="E">E</span>
+                <span class="relay-letter" data-letter="L">L</span>
+                <span class="relay-letter" data-letter="A">A</span>
+                <span class="relay-letter" data-letter="Y">Y</span>
+            </div>
+            <div class="relay-info">
+                <div id="relay-name" class="relay-name">C-Relay-PG</div>
+                <div id="relay-description" class="relay-description">Loading...</div>
+                <div id="relay-pubkey-container" class="relay-pubkey-container">
+                    <div id="relay-pubkey" class="relay-pubkey">Loading...</div>
+                </div>
+            </div>
+            <div class="profile-area" id="profile-area" style="display: none;">
+                <div class="admin-label">admin</div>
+                <div class="profile-container">
+                    <img id="header-user-image" class="header-user-image" alt="Profile" style="display: none;">
+                    <span id="header-user-name" class="header-user-name">Loading...</span>
+                </div>
+                <!-- Logout dropdown -->
+                <!-- Dropdown menu removed - buttons moved to sidebar -->
+            </div>
+        </div>
+
+    </div>
+
+    <!-- Login Modal Overlay -->
+    <div id="login-modal" class="login-modal-overlay" style="display: none;">
+        <div class="login-modal-content">
+            <div id="login-modal-container"></div>
+        </div>
+    </div>
+
+    <!-- Access Denied Overlay (shown when non-admin user logs in) -->
+    <div id="access-denied-overlay" class="access-denied-overlay" style="display: none;">
+        <div class="access-denied-content">
+            <div class="access-denied-icon">⛔</div>
+            <h2>ACCESS DENIED</h2>
+            <p class="access-denied-message">This interface is restricted to the relay administrator.</p>
+            <p class="access-denied-submessage">The logged-in account does not have admin privileges.</p>
+            <button type="button" class="access-denied-logout-btn" onclick="logout()">LOGOUT</button>
+        </div>
+    </div>
+
+    <!-- DATABASE STATISTICS Section -->
+    <!-- Subscribe to kind 24567 events to receive real-time monitoring data -->
+    <div class="section flex-section" id="databaseStatisticsSection" style="display: none;">
+        <div class="section-header">
+            DATABASE STATISTICS
+        </div>
+
+        <!-- Event Rate Graph Container -->
+        <div id="event-rate-chart"></div>
+
+        <!-- Database Overview Table -->
+        <div class="input-group">
+            <div class="config-table-container">
+                <table class="config-table" id="stats-overview-table">
+                    <thead>
+                        <tr>
+                            <th>Metric</th>
+                            <th>Value</th>
+                        </tr>
+                    </thead>
+                    <tbody id="stats-overview-table-body">
+                        <tr>
+                            <td>Database Size</td>
+                            <td id="db-size">-</td>
+                        </tr>
+                        <tr>
+                            <td>Total Events</td>
+                            <td id="total-events">-</td>
+                        </tr>
+                        <tr>
+                            <td>Process ID</td>
+                            <td id="process-id">-</td>
+                        </tr>
+                        <tr>
+                            <td>WebSocket Connections</td>
+                            <td id="websocket-connections">-</td>
+                        </tr>
+                        <tr>
+                            <td>Active Subscriptions</td>
+                            <td id="active-subscriptions">-</td>
+                        </tr>
+                        <tr>
+                            <td>Memory Usage</td>
+                            <td id="memory-usage">-</td>
+                        </tr>
+                        <tr>
+                            <td>CPU Usage</td>
+                            <td id="cpu-usage">-</td>
+                        </tr>
+                        <tr>
+                            <td>CPU Core</td>
+                            <td id="cpu-core">-</td>
+                        </tr>
+                        <tr>
+                            <td>Oldest Event</td>
+                            <td id="oldest-event">-</td>
+                        </tr>
+                        <tr>
+                            <td>Newest Event</td>
+                            <td id="newest-event">-</td>
+                        </tr>
+                    </tbody>
+                </table>
+            </div>
+        </div>
+
+        <!-- Event Kind Distribution Table -->
+        <div class="input-group">
+            <label>Event Kind Distribution:</label>
+            <div class="config-table-container">
+                <table class="config-table" id="stats-kinds-table">
+                    <thead>
+                        <tr>
+                            <th>Event Kind</th>
+                            <th>Count</th>
+                            <th>Percentage</th>
+                        </tr>
+                    </thead>
+                    <tbody id="stats-kinds-table-body">
+                        <tr>
+                            <td colspan="3" style="text-align: center; font-style: italic;">No data loaded</td>
+                        </tr>
+                    </tbody>
+                </table>
+            </div>
+        </div>
+
+        <!-- Time-based Statistics Table -->
+        <div class="input-group">
+            <label>Time-based Statistics:</label>
+            <div class="config-table-container">
+                <table class="config-table" id="stats-time-table">
+                    <thead>
+                        <tr>
+                            <th>Period</th>
+                            <th>Events</th>
+                        </tr>
+                    </thead>
+                    <tbody id="stats-time-table-body">
+                        <tr>
+                            <td>Last 24 Hours</td>
+                            <td id="events-24h">-</td>
+                        </tr>
+                        <tr>
+                            <td>Last 7 Days</td>
+                            <td id="events-7d">-</td>
+                        </tr>
+                        <tr>
+                            <td>Last 30 Days</td>
+                            <td id="events-30d">-</td>
+                        </tr>
+                    </tbody>
+                </table>
+            </div>
+        </div>
+
+        <!-- Top Pubkeys Table -->
+        <div class="input-group">
+            <label>Top Pubkeys by Event Count:</label>
+            <div class="config-table-container">
+                <table class="config-table" id="stats-pubkeys-table">
+                    <thead>
+                        <tr>
+                            <th>Rank</th>
+                            <th>Name</th>
+                            <th>Pubkey</th>
+                            <th>Event Count</th>
+                            <th>Percentage</th>
+                        </tr>
+                    </thead>
+                    <tbody id="stats-pubkeys-table-body">
+                        <tr>
+                            <td colspan="5" style="text-align: center; font-style: italic;">No data loaded</td>
+                        </tr>
+                    </tbody>
+                </table>
+            </div>
+        </div>
+
+    </div>
+
+    <!-- SUBSCRIPTION DETAILS Section (Admin Only) -->
+    <div class="section flex-section" id="subscriptionDetailsSection" style="display: none;">
+        <div class="section-header">
+            ACTIVE SUBSCRIPTION DETAILS
+        </div>
+
+        <div class="input-group">
+            <div class="config-table-container">
+                <table class="config-table" id="subscription-details-table">
+                    <tbody id="subscription-details-table-body">
+                        <tr>
+                            <td colspan="4" style="text-align: center; font-style: italic;">No subscriptions active</td>
+                        </tr>
+                    </tbody>
+                </table>
+            </div>
+        </div>
+    </div>
+
+    <!-- Testing Section -->
+    <div id="div_config" class="section flex-section" style="display: none;">
+        <div class="section-header">
+            RELAY CONFIGURATION
+        </div>
+        <div id="config-display" class="hidden">
+            <div class="config-table-container">
+                <table class="config-table" id="config-table">
+                    <thead>
+                        <tr>
+                            <th>Parameter</th>
+                            <th>Value</th>
+                            <th>Actions</th>
+                        </tr>
+                    </thead>
+                    <tbody id="config-table-body">
+                    </tbody>
+                </table>
+            </div>
+
+            <div class="inline-buttons">
+                <button type="button" id="fetch-config-btn">REFRESH</button>
+            </div>
+
+
+        </div>
+    </div>
+
+    <!-- Auth Rules Management - Moved after configuration -->
+    <!-- AUTH RULES MANAGEMENT SECTION -->
+    <div class="section flex-section" id="authRulesSection" style="display: none;">
+        <div class="section-header">
+AUTH RULES MANAGEMENT
+        </div>
+
+        <!-- Auth Rules Table -->
+        <div id="authRulesTableContainer" style="display: none;">
+            <table class="config-table" id="authRulesTable">
+                <thead>
+                    <tr>
+                        <th>Rule Type</th>
+                        <th>Pattern Type</th>
+                        <th>Pattern Value</th>
+                        <th>Status</th>
+                        <th>Actions</th>
+                    </tr>
+                </thead>
+                <tbody id="authRulesTableBody">
+                </tbody>
+            </table>
+        </div>
+
+        <!-- Auth Rule Input Section -->
+        <div id="authRuleInputSections" style="display: block;">
+            <div class="input-group">
+                <label for="authRulePubkey">Public Key (npub or hex):</label>
+                <input type="text" id="authRulePubkey" placeholder="npub1... or 64-character hex pubkey">
+            </div>
+            <div id="whitelistWarning" class="warning-box" style="display: none;">
+                <strong>⚠️ WARNING:</strong> Adding whitelist rules changes relay behavior to whitelist-only
+                mode.
+                Only whitelisted users will be able to interact with the relay.
+            </div>
+            <div class="inline-buttons">
+                <button type="button" id="addWhitelistBtn" onclick="addWhitelistRule()">ADD TO
+                    WHITELIST</button>
+                <button type="button" id="addBlacklistBtn" onclick="addBlacklistRule()">ADD TO
+                    BLACKLIST</button>
+                <button type="button" id="refreshAuthRulesBtn">REFRESH</button>
+            </div>
+        </div>
+    </div>
+
+    <!-- WEB OF TRUST SECTION -->
+    <div class="section flex-section" id="wotSection" style="display: none;">
+        <div class="section-header">
+WEB OF TRUST
+        </div>
+
+        <!-- Kind 3 Status Indicator -->
+        <div id="wotKind3Status" class="wot-status-row">
+            <span>Admin Contact List (kind 3):</span>
+            <span id="wotKind3Indicator" class="wot-indicator wot-unknown">Checking...</span>
+        </div>
+
+        <!-- WoT Level Selector -->
+        <div class="wot-level-selector">
+            <label>WoT Level:</label>
+            <div class="inline-buttons">
+                <button type="button" id="wotLevel0Btn" class="wot-level-btn" onclick="setWotLevel(0)">
+                    OFF
+                </button>
+                <button type="button" id="wotLevel1Btn" class="wot-level-btn" onclick="setWotLevel(1)">
+                    WRITE ONLY
+                </button>
+                <button type="button" id="wotLevel2Btn" class="wot-level-btn" onclick="setWotLevel(2)">
+                    FULL
+                </button>
+            </div>
+            <div class="wot-level-description" id="wotLevelDescription">
+                Level 0: Open relay — anyone can read and write
+            </div>
+        </div>
+
+        <!-- WoT Stats -->
+        <div class="wot-stats-row">
+            <span>Whitelisted Pubkeys:</span>
+            <span id="wotWhitelistCount">—</span>
+        </div>
+
+        <!-- Sync Button -->
+        <div class="inline-buttons">
+            <button type="button" id="wotSyncBtn" onclick="syncWot()">SYNC FROM KIND 3</button>
+            <button type="button" id="wotRefreshBtn" onclick="loadWotStatus()">REFRESH STATUS</button>
+        </div>
+    </div>
+
+
+
+
+
+
+
+    <!-- NIP-17 DIRECT MESSAGES Section -->
+    <div class="section" id="nip17DMSection" style="display: none;">
+        <div class="section-header">
+            <h2>NIP-17 DIRECT MESSAGES</h2>
+        </div>
+
+        <!-- Outbox -->
+        <div>
+            <label for="dm-outbox">Send Message to Relay:</label>
+            <textarea id="dm-outbox" rows="4" placeholder="Enter your message to send to the relay..."></textarea>
+        </div>
+
+        <!-- Send Button -->
+        <div class="input-group">
+            <button type="button" id="send-dm-btn">SEND MESSAGE</button>
+        </div>
+
+        <!-- Inbox -->
+        <div class="input-group">
+            <label>Received Messages from Relay:</label>
+            <div id="dm-inbox" class="log-panel" style="height: 200px;">
+                <div class="log-entry">No messages received yet.</div>
+            </div>
+        </div>
+    </div>
+
+    <!-- IP BANS Section -->
+    <div class="section" id="ipBansSection" style="display: none;">
+        <div class="section-header">
+            IP BAN MANAGEMENT
+        </div>
+
+        <!-- Statistics Cards -->
+        <div class="input-group">
+            <div class="config-table-container">
+                <table class="config-table" id="ip-bans-stats-table">
+                    <thead>
+                        <tr>
+                            <th>Total IPs Tracked</th>
+                            <th>Currently Banned</th>
+                            <th>Total Bans Issued</th>
+                        </tr>
+                    </thead>
+                    <tbody>
+                        <tr>
+                            <td id="ip-bans-total">-</td>
+                            <td id="ip-bans-active">-</td>
+                            <td id="ip-bans-issued">-</td>
+                        </tr>
+                    </tbody>
+                </table>
+            </div>
+        </div>
+
+        <!-- Add Ban Form -->
+        <div class="input-group">
+            <h3>Manually Ban IP Address</h3>
+            <div class="form-group">
+                <label for="ban-ip-input">IP Address:</label>
+                <input type="text" id="ban-ip-input" placeholder="192.168.1.100">
+            </div>
+            <div class="form-group">
+                <label for="ban-duration-select">Ban Duration:</label>
+                <select id="ban-duration-select">
+                    <option value="3600">1 Hour</option>
+                    <option value="86400" selected>24 Hours</option>
+                    <option value="604800">7 Days</option>
+                    <option value="2592000">30 Days</option>
+                    <option value="31536000">1 Year</option>
+                    <option value="999999999">Permanent</option>
+                </select>
+            </div>
+            <div class="inline-buttons">
+                <button type="button" id="add-ban-btn">BAN IP</button>
+            </div>
+            <div id="add-ban-status" class="status-message"></div>
+        </div>
+
+        <!-- Whitelist Management -->
+        <div class="input-group">
+            <h3>IP Whitelist (Never Banned)</h3>
+            <p style="font-size:13px;opacity:0.8;">IPs in this list are never idle-banned. Comma-separated.</p>
+            <div class="form-group">
+                <label for="whitelist-ip-input">Add IP to Whitelist:</label>
+                <input type="text" id="whitelist-ip-input" placeholder="103.81.231.220">
+            </div>
+            <div class="inline-buttons">
+                <button type="button" id="add-whitelist-btn">ADD TO WHITELIST</button>
+            </div>
+            <div id="whitelist-status" class="status-message"></div>
+            <div id="whitelist-current" style="margin-top:8px;font-size:13px;"></div>
+        </div>
+
+        <!-- Filter Controls -->
+        <div class="input-group">
+            <div class="inline-buttons">
+                <button type="button" id="ip-ban-filter-all" class="active">All IPs</button>
+                <button type="button" id="ip-ban-filter-banned">Currently Banned</button>
+                <button type="button" id="ip-ban-filter-expired">Expired</button>
+                <button type="button" id="refresh-ip-bans-btn">REFRESH</button>
+            </div>
+        </div>
+
+        <!-- IP Bans List -->
+        <div class="input-group">
+            <label>Banned IP Addresses:</label>
+            <div class="config-table-container">
+                <table class="config-table" id="ip-bans-table">
+                        <thead>
+                            <tr>
+                                <th>IP Address</th>
+                                <th>Status</th>
+                                <th>Banned Until</th>
+                                <th>Failures</th>
+                                <th>Authed Successfully</th>
+                                <th>Connection Attempts</th>
+                                <th>Actions</th>
+                            </tr>
+                        </thead>
+                    <tbody id="ip-bans-tbody">
+                        <tr>
+                                                    <td colspan="7" style="text-align: center;">Click REFRESH to load IP bans</td>
+                                                </tr>
+                    </tbody>
+                </table>
+            </div>
+        </div>
+    </div>
+
+    <!-- RELAY EVENTS Section -->
+    <div class="section" id="relayEventsSection" style="display: none;">
+        <div class="section-header">
+            RELAY EVENTS MANAGEMENT
+        </div>
+
+        <!-- Live Relay Event Feed -->
+        <div class="input-group">
+            <h3>Live Relay Event Feed (Normal Nostr Subscription)</h3>
+            <div class="config-table-container">
+                <table class="config-table" id="live-relay-events-table">
+                    <thead>
+                        <tr>
+                            <th>Time</th>
+                            <th>Kind</th>
+                            <th>Pubkey</th>
+                            <th>ID</th>
+                            <th>Content Preview</th>
+                        </tr>
+                    </thead>
+                    <tbody id="live-relay-events-table-body">
+                        <tr>
+                            <td colspan="5" style="text-align: center;">Waiting for live events...</td>
+                        </tr>
+                    </tbody>
+                </table>
+            </div>
+        </div>
+
+        <!-- Kind 0: User Metadata -->
+        <div class="input-group">
+            <h3>Kind 0: User Metadata</h3>
+            <div class="form-group">
+                <label for="kind0-name">Name:</label>
+                <input type="text" id="kind0-name" placeholder="Relay Name">
+            </div>
+            <div class="form-group">
+                <label for="kind0-about">About:</label>
+                <textarea id="kind0-about" rows="3" placeholder="Relay Description"></textarea>
+            </div>
+            <div class="form-group">
+                <label for="kind0-picture">Picture URL:</label>
+                <input type="url" id="kind0-picture" placeholder="https://example.com/logo.png">
+            </div>
+            <div class="form-group">
+                <label for="kind0-banner">Banner URL:</label>
+                <input type="url" id="kind0-banner" placeholder="https://example.com/banner.png">
+            </div>
+            <div class="form-group">
+                <label for="kind0-nip05">NIP-05:</label>
+                <input type="text" id="kind0-nip05" placeholder="relay@example.com">
+            </div>
+            <div class="form-group">
+                <label for="kind0-website">Website:</label>
+                <input type="url" id="kind0-website" placeholder="https://example.com">
+            </div>
+            <div class="inline-buttons">
+                <button type="button" id="submit-kind0-btn">UPDATE METADATA</button>
+            </div>
+            <div id="kind0-status" class="status-message"></div>
+        </div>
+
+        <!-- Kind 10050: DM Relay List -->
+        <div class="input-group">
+            <h3>Kind 10050: DM Relay List</h3>
+            <div class="form-group">
+                <label for="kind10050-relays">Relay URLs (one per line):</label>
+                <textarea id="kind10050-relays" rows="4" placeholder="wss://relay1.com&#10;wss://relay2.com"></textarea>
+            </div>
+            <div class="inline-buttons">
+                <button type="button" id="submit-kind10050-btn">UPDATE DM RELAYS</button>
+            </div>
+            <div id="kind10050-status" class="status-message"></div>
+        </div>
+
+        <!-- Kind 10002: Relay List -->
+        <div class="input-group">
+            <h3>Kind 10002: Relay List</h3>
+            <div id="kind10002-relay-entries">
+                <!-- Dynamic relay entries will be added here -->
+            </div>
+            <div class="inline-buttons">
+                <button type="button" id="add-relay-entry-btn">ADD RELAY</button>
+                <button type="button" id="submit-kind10002-btn">UPDATE RELAYS</button>
+            </div>
+            <div id="kind10002-status" class="status-message"></div>
+        </div>
+    </div>
+
+    <!-- CACHING Section -->
+    <div class="section" id="cachingSection" style="display: none;">
+        <div class="section-header">CACHING</div>
+
+        <!-- Caching Service Status (read-only) -->
+        <div class="input-group">
+            <h3>Caching Service Status</h3>
+            <div id="caching-service-status" class="status-display">
+                <p>Service status will appear here after connecting.</p>
+            </div>
+        </div>
+
+        <!-- Relay Inbox Status (read-only) -->
+        <div class="input-group">
+            <h3>Relay Inbox Status</h3>
+            <div id="caching-inbox-status" class="status-display">
+                <p>Inbox status will appear here after connecting.</p>
+            </div>
+        </div>
+
+        <!-- Caching Configuration (editable) -->
+        <div class="input-group">
+            <h3>Caching Configuration</h3>
+
+            <div class="form-group">
+                <label for="caching-enabled">Enable Caching:</label>
+                <select id="caching-enabled">
+                    <option value="false">Disabled</option>
+                    <option value="true">Enabled</option>
+                </select>
+            </div>
+
+            <div class="form-group">
+                <label for="caching-inbox-enabled">Enable Inbox Consumer:</label>
+                <select id="caching-inbox-enabled">
+                    <option value="false">Disabled</option>
+                    <option value="true">Enabled</option>
+                </select>
+            </div>
+
+            <div class="form-group">
+                <label for="caching-root-npubs">Root Npubs (one per line):</label>
+                <textarea id="caching-root-npubs" rows="4" placeholder="npub1...">npub13lm5wf8dvsdnc2894pkhch9uf8phvw9varrv8zf4sc885hhdmc8q6lx7ks</textarea>
+            </div>
+
+            <div class="form-group">
+                <label for="caching-bootstrap-relays">Bootstrap Relays (one per line):</label>
+                <textarea id="caching-bootstrap-relays" rows="4" placeholder="wss://relay.damus.io">wss://relay.damus.io
+wss://nos.lol
+wss://relay.primal.net
+wss://laantungir.net/relay</textarea>
+            </div>
+
+            <div class="form-group">
+                <label for="caching-kinds">Kinds (comma-separated):</label>
+                <input type="text" id="caching-kinds" placeholder="1,3,6,10000,30023" value="0,1,3,6,10000,10002,30023">
+            </div>
+
+            <div class="form-group">
+                <label for="caching-admin-kinds">Admin Kinds (comma-separated, * for all):</label>
+                <input type="text" id="caching-admin-kinds" placeholder="*">
+            </div>
+
+            <div class="form-group">
+                <label for="caching-live-enabled">Live Subscriptions:</label>
+                <select id="caching-live-enabled">
+                    <option value="true">Enabled</option>
+                    <option value="false">Disabled</option>
+                </select>
+            </div>
+
+            <div class="form-group">
+                <label for="caching-backfill-enabled">Backfill:</label>
+                <select id="caching-backfill-enabled">
+                    <option value="true">Enabled</option>
+                    <option value="false">Disabled</option>
+                </select>
+            </div>
+
+            <div class="form-group">
+                <label for="caching-backfill-windows">Backfill Windows (seconds, comma-separated):</label>
+                <input type="text" id="caching-backfill-windows" placeholder="86400,604800,2592000,7776000,31536000">
+            </div>
+
+            <div class="form-group">
+                <label for="caching-backfill-page-size">Backfill Page Size:</label>
+                <input type="number" id="caching-backfill-page-size" placeholder="50">
+            </div>
+
+            <div class="form-group">
+                <label for="caching-backfill-tick-interval">Backfill Tick Interval (ms):</label>
+                <input type="number" id="caching-backfill-tick-interval" placeholder="5000">
+            </div>
+
+            <div class="form-group">
+                <label for="caching-inbox-batch-size">Inbox Batch Size:</label>
+                <input type="number" id="caching-inbox-batch-size" placeholder="150">
+            </div>
+
+            <div class="form-group">
+                <label for="caching-inbox-active-poll">Inbox Active Poll (ms):</label>
+                <input type="number" id="caching-inbox-active-poll" placeholder="200">
+            </div>
+
+            <div class="form-group">
+                <label for="caching-inbox-idle-poll">Inbox Idle Poll (ms):</label>
+                <input type="number" id="caching-inbox-idle-poll" placeholder="5000">
+            </div>
+
+            <div class="form-group">
+                <label for="caching-service-binary-path">Caching Service Binary Path:</label>
+                <input type="text" id="caching-service-binary-path" placeholder="./caching_relay" value="./caching_relay">
+            </div>
+
+            <div class="form-group">
+                <label for="caching-service-pg-conn">Caching Service PG Connection:</label>
+                <input type="text" id="caching-service-pg-conn" placeholder="host=localhost port=5432 dbname=crelay user=crelay password=crelay" value="host=localhost port=5432 dbname=crelay user=crelay password=crelay">
+            </div>
+
+            <div class="inline-buttons">
+                <button type="button" id="caching-apply-btn">APPLY CONFIGURATION</button>
+                <button type="button" id="caching-reset-progress-btn">RESET BACKFILL PROGRESS</button>
+            </div>
+            <div id="caching-config-status" class="status-message"></div>
+        </div>
+
+        <div class="input-group">
+            <h3>Caching Service Control</h3>
+            <p>Start or stop the external caching service process. Set <code>caching_service_binary_path</code> and <code>caching_service_pg_conn</code> above and click APPLY CONFIGURATION before starting.</p>
+            <div class="inline-buttons">
+                <button type="button" id="caching-start-service-btn">START CACHING SERVICE</button>
+                <button type="button" id="caching-stop-service-btn">STOP CACHING SERVICE</button>
+            </div>
+            <div id="caching-service-control-status" class="status-message"></div>
+        </div>
+
+        <div class="input-group">
+            <h3>Followed Pubkeys</h3>
+            <p>Pubkeys being cached with their profile names, event counts, outbox relays, and backfill status.</p>
+            <div id="caching-follows-status" class="status-message"></div>
+            <table id="caching-follows-table" style="width: 100%; border-collapse: collapse; font-size: 13px;">
+                <thead>
+                    <tr style="border-bottom: 2px solid var(--border-color, #444); text-align: left;">
+                        <th style="padding: 6px 8px;">Name</th>
+                        <th style="padding: 6px 8px;">npub</th>
+                        <th style="padding: 6px 8px;">Root?</th>
+                        <th style="padding: 6px 8px;">Events in DB</th>
+                        <th style="padding: 6px 8px;">Backfill</th>
+                        <th style="padding: 6px 8px; width: 40%;">Relays (status, events fetched)</th>
+                    </tr>
+                </thead>
+                <tbody id="caching-follows-table-body">
+                    <tr><td colspan="6" style="text-align: center; font-style: italic; padding: 12px;">Loading follows status...</td></tr>
+                </tbody>
+            </table>
+        </div>
+    </div>
+
+    <!-- SQL QUERY Section -->
+    <div class="section" id="sqlQuerySection" style="display: none;">
+        <div class="section-header">
+            <h2>SQL QUERY CONSOLE</h2>
+        </div>
+
+        <!-- Query Selector -->
+        <div class="input-group">
+            <label for="query-dropdown">Quick Queries & History:</label>
+            <select id="query-dropdown" onchange="loadSelectedQuery()">
+                <option value="">-- Select a query --</option>
+                <optgroup label="Common Queries">
+                    <option value="recent_events">Recent Events</option>
+                    <option value="event_stats">Event Statistics</option>
+                    <option value="subscriptions">Active Subscriptions</option>
+                    <option value="top_pubkeys">Top Pubkeys</option>
+                    <option value="event_kinds">Event Kinds Distribution</option>
+                    <option value="time_stats">Time-based Statistics</option>
+                </optgroup>
+                <optgroup label="IP Ban Queries">
+                    <option value="banned_ips_summary">Banned IPs Summary</option>
+                    <option value="banned_ips_list">All Banned IP Addresses</option>
+                </optgroup>
+                <optgroup label="Query History" id="history-group">
+                    <!-- Dynamically populated from localStorage -->
+                </optgroup>
+            </select>
+        </div>
+
+        <!-- Query Editor -->
+        <div class="input-group">
+            <label for="sql-input">SQL Query:</label>
+            <textarea id="sql-input" rows="5" placeholder="SELECT * FROM events LIMIT 10"></textarea>
+        </div>
+
+        <!-- Query Actions -->
+        <div class="input-group">
+            <div class="inline-buttons">
+                <button type="button" id="execute-sql-btn">EXECUTE QUERY</button>
+                <button type="button" id="clear-sql-btn">CLEAR</button>
+                <button type="button" id="clear-history-btn">CLEAR HISTORY</button>
+            </div>
+        </div>
+
+        <!-- Query Results -->
+        <div class="input-group">
+            <label>Query Results:</label>
+            <div id="query-info" class="info-box"></div>
+            <div id="query-table" class="config-table-container"></div>
+        </div>
+    </div>
+
+    <!-- Load the official nostr-tools bundle first -->
+    <!-- <script src="https://laantungir.net/nostr-login-lite/nostr.bundle.js"></script> -->
+    <script src="/api/nostr.bundle.js"></script>
+
+    <!-- Load NOSTR_LOGIN_LITE main library -->
+    <!-- <script src="https://laantungir.net/nostr-login-lite/nostr-lite.js"></script> -->
+    <script src="/api/nostr-lite.js"></script>
+    <!-- Load text_graph library -->
+    <script src="/api/text_graph.js"></script>
+
+
+
+
+
+    <script src="/api/index.js"></script>
+</body>
+
+</html>

api/template.html

@@ -0,0 +1,813 @@
+<!DOCTYPE html>
+<?xml version="1.0" encoding="UTF-8"?>
+<html lang="en" dir="ltr">
+
+<head>
+  <meta charset="utf-8" />
+  <title>TEMPLATE</title>
+
+  <link rel="stylesheet" href="./css/client.css" />
+
+  <!-- Initialize theme BEFORE any components load -->
+  <script>
+    (function () {
+      const savedTheme = localStorage.getItem('theme');
+      if (savedTheme === 'dark') {
+        document.documentElement.classList.add('dark-mode');
+        if (document.body) {
+          document.body.classList.add('dark-mode');
+        }
+      }
+    })();
+  </script>
+  <link rel="shortcut icon" type="image/x-icon" href="./favicon/favicon-dots2.ico" />
+
+  <!-- SVG.js library (required by HamburgerMorphing) -->
+  <script src="https://cdn.jsdelivr.net/npm/@svgdotjs/svg.js@3.0/dist/svg.min.js"></script>
+</head>
+
+<body>
+  <!-- ================================================================
+       HAMBURGER BUTTON (Fixed, separate from header)
+       ================================================================
+       The hamburger button is a fixed element outside the header
+       to ensure it stays visible above the sidenav (z-index: 10 > 3).
+       ================================================================ -->
+  <div id="divSvgHam" class="divHeaderButtons">
+    <!-- HamburgerMorphing will be injected here -->
+  </div>
+
+  <!-- ================================================================
+       HEADER
+       ================================================================
+       Standard header with title (center).
+       ================================================================ -->
+  <div id="divHeader">
+    <div id="divHeaderFlexLeft">
+      <!-- Hamburger is now separate fixed element -->
+    </div>
+
+    <div id="divHeaderFlexCenter">
+      <div class="divHeaderText"></div>
+    </div>
+
+    <div id="divHeaderFlexRight">
+      <!-- No button in header right - logout is in sidenav footer -->
+    </div>
+  </div>
+
+  <!-- ================================================================
+       BODY
+       ================================================================
+       Main content area. Add your page-specific content here.
+       ================================================================ -->
+  <div id="divBody">
+   
+    
+  </div>
+
+  <!-- ================================================================
+       FOOTER
+       ================================================================
+       Three-section footer layout:
+       - Left: Relay status animations (HamburgerMorphing instances)
+       - Center: General status information
+       - Right: Additional information
+       ================================================================ -->
+  <div id="divFooter">
+    <div id="divFooterLeft" class="divFooterBox"></div>
+    <div id="divFooterCenter" class="divFooterBox"></div>
+    <div id="divFooterRight" class="divFooterBox"></div>
+    <div id="divFooterBalance" class="divFooterBox">0 sats</div>
+  </div>
+
+  <!-- ================================================================
+       SIDENAV
+       ================================================================
+       Slide-out navigation panel. Opens from left when hamburger clicked.
+       Uses flexbox layout to pin version bar to bottom.
+       Includes a version bar footer with theme toggle and logout buttons.
+       ================================================================ -->
+  <div id="divSideNav">
+    <div id="divSideNavHeader">
+      <!-- No close button - use main hamburger to close -->
+    </div>
+
+    <div id="divSideNavBody">
+      <div id="divFiles"></div>
+    </div>
+
+    <div id="divAiSection" class="sidenavSection"> 
+      <div id="divAiSectionTitle" class="sidenavSectionTitle">AI</div>
+      <div id="divAiList" class="sidenavSectionList">
+        <div id="divAiProvidersList">No saved providers yet.</div>
+      </div>
+    </div>
+
+
+    <div id="divRelaySection">
+      <div id="divRelaySectionTitle">
+        リレー
+      </div>
+      <div id="divRelayList">
+        Loading relays...
+      </div>
+    </div>
+
+    <div id="divBlossomSection">
+
+      <div id="divBlossomSectionTitle">ブロッサム</div>
+
+      <div id="divBlossomList">Loading blossom servers...</div>
+
+    </div>
+
+
+    <div id="divVersionBar">
+      <span id="versionDisplay">v0.0.1</span>
+      <div id="divVersionBarButtons">
+        <button id="themeToggleButton" title="Toggle Dark/Light Mode">
+          <div id="themeToggleHamburgerContainer"></div>
+        </button>
+        <button id="logoutButton" title="Logout">
+          <div id="logoutHamburgerContainer"></div>
+        </button>
+      </div>
+    </div>
+  </div>
+
+  <!-- ================================================================
+       REQUIRED SCRIPTS
+       ================================================================
+       These scripts must be loaded in this order:
+       1. nostr.bundle.js - Nostr tools library
+       2. nostr-lite.js - Authentication modal (nostr-login-lite)
+       ================================================================ -->
+  <script src="./nostr.bundle.js"></script>
+  <script src="./nostr-lite.js"></script>
+
+  <script type="module">
+    /* ================================================================
+       IMPORTS
+       ================================================================
+       Import shared NDK functionality from init-ndk.mjs:
+       - initNDKPage() - Initialize authentication and worker
+       - getPubkey() - Get current user's pubkey
+       - subscribe() - Create NDK subscriptions
+       - publishEvent() - Publish events via NDK
+       - disconnect() - Disconnect from worker
+       - getRelayData() - Get relay connection data
+       - getRelayStats() - Get relay activity statistics
+       
+       Import HamburgerMorphing for animated icons
+       ================================================================ */
+    import {
+      initNDKPage,
+      getPubkey, injectHeaderAvatar,
+      subscribe,
+      publishEvent,
+      disconnect,
+      getVersion,
+      updateVersionDisplay,
+      getUserSettings,
+      patchUserSettings,
+      onUserSettings
+    } from './js/init-ndk.mjs';
+    import { HamburgerMorphing } from "./hamburger_morphing/hamburger.mjs";
+    import { initFooterRelayStatus, updateFooterRelayStatus, initSidenavRelaySection, updateSidenavRelaySection, setRelayActivityState } from './js/relay-ui.mjs';
+
+    import { initBlossomSection, updateBlossomSection } from './js/blossom-ui.mjs';
+    
+    import { initAiSectionWithLocalConfig } from './js/ai-ui.mjs';
+// Version will be loaded asynchronously
+    const versionInfo = await getVersion();
+    const VERSION = versionInfo.VERSION;
+    console.log(`[template.html ${VERSION}] Loading...`);
+
+    /* ================================================================
+       GLOBAL VARIABLES
+       ================================================================
+       Track state for hamburger menu, relay status, and theme.
+       ================================================================ */
+    let updateIntervalId = null;
+    let currentPubkey = null;
+
+    /*
+      AUTH STATE MODEL (Template reference)
+      ------------------------------------------------------------------
+      This template now demonstrates three auth modes for standalone pages:
+
+      - required (default):
+        Behaves like existing pages: login is required immediately.
+
+      - optional:
+        Page can render public/read-only data without login, but can still
+        prompt login later for user actions (publish, settings, etc).
+
+      - none:
+        Never auto-login on load (pure public page).
+
+      URL behavior in this template:
+      - If ?auth=required|optional|none is present, it wins.
+      - Otherwise, if URL includes ?npub=... or ?pubkey=..., mode defaults
+        to optional because pages with explicit profile targets are commonly
+        public-readable.
+      - Otherwise, mode defaults to required.
+    */
+    let isAuthenticated = false;
+    let authMode = 'required';
+    let authedPageInitialized = false;
+    let relayActivityListenersBound = false;
+    
+    // Hamburger menu
+    let hamburgerInstance = null;
+    let isNavOpen = false;
+    
+    // Version bar buttons
+    let logoutHamburger = null;
+    let themeToggleHamburger = null;
+    let isDarkMode = false;
+
+    // App-wide user settings (NIP-78 kind 30078, d:user-settings)
+    let pageSettings = {};
+    let unsubscribeUserSettings = null;
+
+    /* ================================================================
+       DOM VARIABLES
+       ================================================================
+       Cache DOM element references for better performance.
+       ================================================================ */
+    const divBody = document.getElementById("divBody");
+    const divSideNav = document.getElementById("divSideNav");
+    const divSideNavBody = document.getElementById("divSideNavBody");
+    const divFooterCenter = document.getElementById("divFooterCenter");
+    const divFooterRight = document.getElementById("divFooterRight");
+
+    /* ================================================================
+       HAMBURGER MENU
+       ================================================================
+       Initialize and control the animated hamburger menu.
+       ================================================================ */
+    function initHamburgerMenu() {
+      hamburgerInstance = new HamburgerMorphing('#divSvgHam', {
+        foreground: 'var(--primary-color)',
+        background: 'var(--secondary-color)',
+        hover: 'var(--accent-color)'
+      });
+      hamburgerInstance.animateTo('burger');
+    }
+
+    /* ================================================================
+       SIDENAV FUNCTIONS
+       ================================================================
+       Open/close sidenav with hamburger morphing animation.
+       ================================================================ */
+    function openNav() {
+      divSideNav.style.zIndex = 3;
+      divSideNav.style.width = "clamp(400px, 50vw, 600px)";
+      isNavOpen = true;
+      if (hamburgerInstance) {
+        hamburgerInstance.animateTo('arrow_left');
+      }
+
+      
+      // Initialize version bar buttons when sidenav opens (lazy load)
+      if (!logoutHamburger) {
+        logoutHamburger = new HamburgerMorphing('#logoutHamburgerContainer', {
+          size: 24,
+          foreground: 'var(--primary-color)',
+          background: 'var(--secondary-color)',
+          hover: 'var(--accent-color)'
+        });
+        logoutHamburger.animateTo('x');
+      }
+      
+      if (!themeToggleHamburger) {
+        themeToggleHamburger = new HamburgerMorphing('#themeToggleHamburgerContainer', {
+          size: 24,
+          foreground: 'var(--primary-color)',
+          background: 'var(--secondary-color)',
+          hover: 'var(--accent-color)'
+        });
+        
+        // Determine current theme
+        const savedTheme = localStorage.getItem('theme');
+        isDarkMode = savedTheme === 'dark' || document.body.classList.contains('dark-mode');
+        const initialShape = isDarkMode ? 'moon' : 'circle';
+        themeToggleHamburger.animateTo(initialShape);
+      }
+    }
+
+    function closeNav() {
+      divSideNav.style.width = "0vw";
+      divSideNav.style.zIndex = -1;
+      isNavOpen = false;
+      if (hamburgerInstance) {
+        hamburgerInstance.animateTo('burger');
+      }
+    }
+
+    function toggleNav() {
+      if (isNavOpen) {
+        closeNav();
+      } else {
+        openNav();
+      }
+    }
+
+
+    /* ================================================================
+       AUTH MODE HELPERS
+       ================================================================
+       These functions are meant as reusable guidance for future pages.
+       ================================================================ */
+    function hasTargetPubkeyInUrl() {
+      const params = new URLSearchParams(window.location.search || '');
+      const npub = String(params.get('npub') || '').trim();
+      const pubkey = String(params.get('pubkey') || '').trim();
+      return Boolean(npub || pubkey);
+    }
+
+    function resolveAuthModeFromUrl() {
+      const params = new URLSearchParams(window.location.search || '');
+      const explicitAuth = String(params.get('auth') || '').trim().toLowerCase();
+      if (explicitAuth === 'required' || explicitAuth === 'optional' || explicitAuth === 'none') {
+        return explicitAuth;
+      }
+
+      // Convention: explicit target profiles are public-readable by default.
+      if (hasTargetPubkeyInUrl()) {
+        return 'optional';
+      }
+
+      return 'required';
+    }
+
+    function isAuthRequiredError(error) {
+      const message = String(error?.message || error || '').toLowerCase();
+      return message.includes('authentication required');
+    }
+
+    async function initializeAuthentication(mode) {
+      // required: existing behavior, throw if auth fails.
+      if (mode === 'required') {
+        await initNDKPage();
+        currentPubkey = await getPubkey();
+        isAuthenticated = true;
+        return;
+      }
+
+      // none: public page, no login attempt on load.
+      if (mode === 'none') {
+        isAuthenticated = false;
+        currentPubkey = null;
+        return;
+      }
+
+      // optional: try silent/normal init; if auth required, continue public.
+      try {
+        await initNDKPage();
+        currentPubkey = await getPubkey();
+        isAuthenticated = true;
+      } catch (error) {
+        if (isAuthRequiredError(error)) {
+          console.log('[template.html] Optional auth mode: continuing unauthenticated');
+          isAuthenticated = false;
+          currentPubkey = null;
+          return;
+        }
+        throw error;
+      }
+    }
+
+    async function initializeAuthenticatedPageFeatures() {
+      if (!isAuthenticated || authedPageInitialized) return;
+
+      await injectHeaderAvatar(currentPubkey);
+      console.log('[template.html] Authenticated as:', currentPubkey);
+
+      // Hydrate app-wide user settings for this page
+      try {
+        pageSettings = await getUserSettings();
+      } catch (error) {
+        console.warn('[template.html] getUserSettings failed:', error);
+        pageSettings = {};
+      }
+
+      // Subscribe to live user settings updates (cross-tab + publish echoes)
+      if (!unsubscribeUserSettings) {
+        unsubscribeUserSettings = onUserSettings((settings) => {
+          pageSettings = settings || {};
+          // TODO: Re-render page-specific UI from pageSettings here.
+        });
+      }
+
+      // Initialize relay-dependent UI only once authenticated.
+      initFooterRelayStatus();
+      initSidenavRelaySection();
+      await initBlossomSection();
+        initAiSectionWithLocalConfig();
+      await UpdateFooter();
+
+      if (!updateIntervalId) {
+        updateIntervalId = setInterval(UpdateFooter, 1000);
+      }
+
+      // Relay activity listeners only matter after worker init/auth.
+      if (!relayActivityListenersBound) {
+        window.addEventListener('ndkRelayActivity', (event) => {
+          const { relayUrl, activity, stats } = event.detail;
+          console.log(`[template.html] Relay activity: ${relayUrl} - ${activity}`, stats);
+          setRelayActivityState(relayUrl, activity);
+        });
+
+        window.addEventListener('message', (event) => {
+          if (event.data && event.data.type === 'relayActivity') {
+            const { relayUrl, activity } = event.data;
+            console.log(`[template.html] Relay activity: ${relayUrl} - ${activity}`);
+            setRelayActivityState(relayUrl, activity);
+          }
+        });
+
+        relayActivityListenersBound = true;
+      }
+
+      authedPageInitialized = true;
+    }
+
+    async function promptLoginIfNeeded() {
+      if (isAuthenticated) return true;
+
+      await initNDKPage();
+      currentPubkey = await getPubkey();
+      isAuthenticated = true;
+      await initializeAuthenticatedPageFeatures();
+      return true;
+    }
+
+    /* ================================================================
+       UPDATE FOOTER
+       ================================================================
+       Update footer sections with relay status, pubkey, and other info.
+       Called periodically by update loop.
+       ================================================================ */
+    const UpdateFooter = async () => {
+
+      try {
+        // Update relay status visuals in footer and sidenav
+        await updateFooterRelayStatus();
+        await updateSidenavRelaySection();
+        
+        await updateBlossomSection();
+        // Clear center and right sections
+        divFooterCenter.innerHTML = '';
+        divFooterRight.innerHTML = '';
+      } catch (error) {
+        console.error('[template.html] Error updating footer:', error);
+      }
+    };
+
+    /* ================================================================
+       LOGOUT
+       ================================================================
+       Complete logout process:
+       1. Stop update loop
+       2. Disconnect from NDK worker
+       3. Logout from nostr-login-lite
+       4. Clear all storage (localStorage, sessionStorage, IndexedDB)
+       5. Reload page
+       ================================================================ */
+    const Logout = async () => {
+      console.log("[template.html] Starting logout process...");
+
+      // Stop the update loop
+      if (updateIntervalId) {
+        clearInterval(updateIntervalId);
+        updateIntervalId = null;
+      }
+
+      // Disconnect from worker
+      disconnect();
+
+      // Logout from nostr-login-lite
+      if (window.NOSTR_LOGIN_LITE && window.NOSTR_LOGIN_LITE.logout) {
+        await window.NOSTR_LOGIN_LITE.logout();
+      }
+
+      // Clear all storage
+      localStorage.clear();
+      sessionStorage.clear();
+
+      // Clear IndexedDB
+      if (window.indexedDB) {
+        const databases = await window.indexedDB.databases();
+        for (const db of databases) {
+          if (db.name) {
+            window.indexedDB.deleteDatabase(db.name);
+          }
+        }
+      }
+
+      console.log("[template.html] Logged out, reloading page");
+      location.reload(true);
+    };
+
+    /* ================================================================
+       EVENT LISTENERS
+       ================================================================
+       Wire up UI interactions.
+       Main hamburger button click handler is set up in main() after initialization.
+       ================================================================ */
+
+    /* ================================================================
+       SUBSCRIPTION EXAMPLE
+       ================================================================
+       Example of how to subscribe to Nostr events:
+       
+       const sub = subscribe(
+         { kinds: [1], authors: [pubkey], limit: 10 },
+         { closeOnEose: false, cacheUsage: 'CACHE_FIRST' }
+       );
+       
+       Cache usage options:
+       - 'CACHE_FIRST' - Check cache first, then relays
+       - 'ONLY_RELAY' - Only query relays
+       - 'ONLY_CACHE' - Only query cache
+       - 'PARALLEL' - Query cache and relays simultaneously
+       
+       Listen for events via window events:
+       window.addEventListener('ndkEvent', (event) => {
+         const evt = event.detail;
+         console.log('Received event:', evt);
+       });
+       ================================================================ */
+
+    /* ================================================================
+       PUBLISH EXAMPLE
+       ================================================================
+       Example of how to publish a Nostr event:
+       
+       const event = {
+         created_at: Math.floor(Date.now() / 1000),
+         kind: 1,
+         tags: [],
+         content: "Hello, Nostr!"
+       };
+       
+       try {
+         const result = await publishEvent(event);
+         console.log("✅ Published to:", result.relayResults.successful);
+         console.log("❌ Failed:", result.relayResults.failed);
+         console.log("Total relays:", result.totalRelays);
+       } catch (error) {
+         console.error("Publish error:", error);
+       }
+       
+       Note: Events are automatically signed by the NDK worker using
+       the message-based signer (which calls window.nostr.signEvent).
+       ================================================================ */
+
+    /* ================================================================
+       USER SETTINGS EXAMPLE (NIP-78)
+       ================================================================
+       Read/subscribe/write helper pattern for all pages:
+
+       // Read latest merged settings (cache + relay hydrated by worker)
+       const settings = await getUserSettings();
+
+       // Subscribe to cross-tab updates
+       const unsubscribe = onUserSettings((nextSettings) => {
+         // Re-render page from nextSettings
+       });
+
+       // Patch only your feature namespace
+       await patchUserSettings({
+         myFeature: {
+           someFlag: true
+         }
+       });
+
+       // On page teardown (if applicable)
+       // unsubscribe();
+       ================================================================ */
+
+    /* ================================================================
+       INITIALIZATION
+       ================================================================
+       Main initialization sequence:
+       1. Initialize hamburger menu
+       2. Set up hamburger click handler
+       3. Resolve auth mode from URL/query policy
+       4. Initialize authentication based on mode
+       5. Initialize authenticated-only features (if signed in)
+       6. Set up version bar button listeners
+       7. Restore sidenav state
+       8. Update version display
+
+       Notes:
+       - required mode = existing behavior (prompt login on load)
+       - optional mode = allow public load, login later on demand
+       - none mode = no auto-login on load
+       ================================================================ */
+    (async function main() {
+      console.log("[template.html] Starting initialization...");
+      
+      try {
+        // Initialize hamburger menu first
+        initHamburgerMenu();
+        
+        // Add click handler to hamburger
+        const divSvgHam = document.getElementById('divSvgHam');
+        if (divSvgHam) {
+          divSvgHam.addEventListener('click', toggleNav);
+        }
+        
+        // Initialize version bar buttons
+        const themeToggleButton = document.getElementById('themeToggleButton');
+        const logoutButton = document.getElementById('logoutButton');
+        
+        if (themeToggleButton) {
+          themeToggleButton.addEventListener('click', () => {
+            isDarkMode = !isDarkMode;
+            if (isDarkMode) {
+              localStorage.setItem('theme', 'dark');
+            } else {
+              localStorage.setItem('theme', 'light');
+            }
+            // Save sidenav state before reload
+            localStorage.setItem('sidenavWasOpen', isNavOpen ? 'true' : 'false');
+            window.location.reload();
+          });
+        }
+        
+        if (logoutButton) {
+          logoutButton.addEventListener('click', async () => {
+            try {
+              // In optional/none modes this doubles as a "Sign in" entry point.
+              if (!isAuthenticated) {
+                await promptLoginIfNeeded();
+                return;
+              }
+              await Logout();
+            } catch (error) {
+              console.error('Logout/login action failed:', error);
+            }
+          });
+        }
+
+        // Resolve and initialize page auth policy.
+        authMode = resolveAuthModeFromUrl();
+        console.log('[template.html] Resolved auth mode:', authMode);
+        await initializeAuthentication(authMode);
+
+        // Initialize authenticated features only when signed in.
+        await initializeAuthenticatedPageFeatures();
+        
+        /* ============================================================
+           EXAMPLE: Subscribe to events
+           ============================================================
+           Uncomment to subscribe to user's notes:
+           
+           const notesSub = subscribe(
+             { kinds: [1], authors: [currentPubkey], limit: 10 },
+             { closeOnEose: false, cacheUsage: 'CACHE_FIRST' }
+           );
+           console.log("[template.html] Subscribed to kind 1");
+           ============================================================ */
+        
+        /* ============================================================
+           EXAMPLE: Listen for events from worker
+           ============================================================
+           Uncomment to handle incoming events:
+           
+           window.addEventListener('ndkEvent', (event) => {
+             const evt = event.detail;
+             console.log("[template.html] Received event:", evt.kind, evt.pubkey);
+             
+             if (evt.pubkey === currentPubkey) {
+               if (evt.kind === 1) {
+                 // Handle note event
+                 console.log("Note:", evt.content);
+               }
+             }
+           });
+           ============================================================ */
+        
+        /* ============================================================
+           EXAMPLE: Listen for cached profile
+           ============================================================
+           Uncomment to handle cached profile data:
+           
+           window.addEventListener('ndkProfile', (event) => {
+             console.log("[template.html] Cached profile:", event.detail);
+             // event.detail contains profile object (name, about, etc.)
+           });
+           ============================================================ */
+        
+        // Restore sidenav state if it was open before theme toggle
+        const sidenavWasOpen = localStorage.getItem('sidenavWasOpen');
+        if (sidenavWasOpen === 'true') {
+          localStorage.removeItem('sidenavWasOpen');
+          openNav();
+        }
+
+        // Optional UX note for public mode pages.
+        if (!isAuthenticated && (authMode === 'optional' || authMode === 'none')) {
+          divFooterCenter.textContent = 'Public mode';
+          divFooterRight.textContent = 'Sign in from side menu for private features';
+        }
+
+        // Update version display
+        await updateVersionDisplay();
+        
+        console.log('[template.html] Initialization complete');
+      } catch (error) {
+        console.error('[template.html] Initialization failed:', error);
+        divBody.innerHTML = `<div style="text-align: center; padding: 50px;">
+          <div style="font-size: 24px; margin-bottom: 20px; color: red;">❌ Authentication Error</div>
+          <div style="font-size: 16px; color: #666;">${error.message}</div>
+          <div style="margin-top: 20px;">
+            <button onclick="location.reload()" style="padding: 10px 20px; font-size: 16px;">Retry</button>
+          </div>
+        </div>`;
+      }
+    })();
+
+    /* ================================================================
+       WORKER MESSAGE TYPES
+       ================================================================
+       The NDK worker can send these message types:
+       
+       1. 'response' - Response to init/subscribe/publish requests
+          - data.profile - User profile (from init)
+          - data.relays - User relays (from init)
+          - data.success - Publish success status
+          - data.relayResults - Relay publish results
+       
+       2. 'event' - Nostr event from subscription
+          - Dispatched as 'ndkEvent' window event
+          - event.detail contains the Nostr event
+       
+       3. 'eose' - End of stored events for subscription
+          - Dispatched as 'ndkEose' window event
+          - event.detail.subId contains subscription ID
+       
+       4. 'signRequest' - Request to sign event/encrypt/decrypt
+          - Handled automatically by init-ndk.mjs
+          - Calls window.nostr methods and sends response
+       
+       5. 'error' - Error from worker
+          - Logged to console automatically
+       
+       6. 'relayActivity' - Relay read/write activity notification
+          - Dispatched as 'ndkRelayActivity' window event
+          - Used to animate relay status icons in footer
+       ================================================================ */
+
+    /* ================================================================
+       DISTRIBUTED ARCHITECTURE NOTES
+       ================================================================
+       Each page is independently accessible and self-contained:
+       
+       1. Authentication persists via nostr-login-lite localStorage
+          - Login once on any page
+          - All other pages automatically authenticated
+       
+       2. NDK SharedWorker is shared across all tabs/pages
+          - Single NDK instance manages all connections
+          - Subscriptions from all pages handled by one worker
+          - Events broadcast to all connected pages
+       
+       3. Dexie cache is shared across all pages
+          - IndexedDB persists across sessions
+          - Cache-first queries are fast
+          - Reduces relay load
+       
+       4. User settings are centralized and shared
+          - Worker hydrates kind 30078 (`d:user-settings`) on init
+          - Pages read via getUserSettings()
+          - Pages patch via patchUserSettings({ featureNamespace: ... })
+          - Pages subscribe via onUserSettings() for live updates
+
+       5. Each page can be distributed independently
+          - Copy template.html and customize
+          - No dependencies on other pages
+          - Works standalone or as part of suite
+       
+       6. Message-based signer bridges worker and page
+          - Worker's NDK uses MessageBasedSigner
+          - Signer sends sign requests to page
+          - Page calls window.nostr.signEvent()
+          - Response sent back to worker
+          - NDK completes signing and publishing
+       
+       7. Relay status visualization
+          - Footer left section shows connected relays
+          - Each relay has animated icon (HamburgerMorphing)
+          - Icons morph based on activity (read/write)
+          - Temporary animations show real-time activity
+       ================================================================ */
+  </script>
+</body>
+
+</html>

api/text_graph.js

@@ -0,0 +1,463 @@
+/**
+ * ASCIIBarChart - A dynamic ASCII-based vertical bar chart renderer
+ * 
+ * Creates real-time animated bar charts using monospaced characters (X)
+ * with automatic scaling, labels, and responsive font sizing.
+ */
+class ASCIIBarChart {
+    /**
+     * Create a new ASCII bar chart
+     * @param {string} containerId - The ID of the HTML element to render the chart in
+     * @param {Object} options - Configuration options
+     * @param {number} [options.maxHeight=20] - Maximum height of the chart in rows
+     * @param {number} [options.maxDataPoints=30] - Maximum number of data columns before scrolling
+     * @param {string} [options.title=''] - Chart title (displayed centered at top)
+     * @param {string} [options.xAxisLabel=''] - X-axis label (displayed centered at bottom)
+     * @param {string} [options.yAxisLabel=''] - Y-axis label (displayed vertically on left)
+     * @param {boolean} [options.autoFitWidth=true] - Automatically adjust font size to fit container width
+     * @param {boolean} [options.useBinMode=false] - Enable time bin mode for data aggregation
+     * @param {number} [options.binDuration=10000] - Duration of each time bin in milliseconds (10 seconds default)
+     * @param {string} [options.xAxisLabelFormat='elapsed'] - X-axis label format: 'elapsed', 'bins', 'timestamps', 'ranges'
+     * @param {boolean} [options.debug=false] - Enable debug logging
+     */
+    constructor(containerId, options = {}) {
+        this.container = document.getElementById(containerId);
+        this.data = [];
+        this.maxHeight = options.maxHeight || 20;
+        this.maxDataPoints = options.maxDataPoints || 30;
+        this.totalDataPoints = 0; // Track total number of data points added
+        this.title = options.title || '';
+        this.xAxisLabel = options.xAxisLabel || '';
+        this.yAxisLabel = options.yAxisLabel || '';
+        this.autoFitWidth = options.autoFitWidth !== false; // Default to true
+        this.debug = options.debug || false; // Debug logging option
+
+        // Time bin configuration
+        this.useBinMode = options.useBinMode !== false; // Default to true
+        this.binDuration = options.binDuration || 4000; // 4 seconds default
+        this.xAxisLabelFormat = options.xAxisLabelFormat || 'elapsed';
+
+        // Time bin data structures
+        this.bins = [];
+        this.currentBinIndex = -1;
+        this.binStartTime = null;
+        this.binCheckInterval = null;
+        this.chartStartTime = Date.now();
+
+        // Set up resize observer if auto-fit is enabled
+        if (this.autoFitWidth) {
+            this.resizeObserver = new ResizeObserver(() => {
+                this.adjustFontSize();
+            });
+            this.resizeObserver.observe(this.container);
+        }
+
+        // Initialize first bin if bin mode is enabled
+        if (this.useBinMode) {
+            this.initializeBins();
+        }
+    }
+
+    /**
+     * Add a new data point to the chart
+     * @param {number} value - The numeric value to add
+     */
+    addValue(value) {
+        // Time bin mode: add value to current active bin count
+        this.checkBinRotation(); // Ensure we have an active bin
+        this.bins[this.currentBinIndex].count += value;  // Changed from ++ to += value
+        this.totalDataPoints++;
+
+        this.render();
+        this.updateInfo();
+    }
+
+    /**
+     * Clear all data from the chart
+     */
+    clear() {
+        this.data = [];
+        this.totalDataPoints = 0;
+
+        if (this.useBinMode) {
+            this.bins = [];
+            this.currentBinIndex = -1;
+            this.binStartTime = null;
+            this.initializeBins();
+        }
+
+        this.render();
+        this.updateInfo();
+    }
+
+    /**
+     * Calculate the width of the chart in characters
+     * @returns {number} The chart width in characters
+     * @private
+     */
+    getChartWidth() {
+        let dataLength = this.maxDataPoints; // Always use maxDataPoints for consistent width
+
+        if (dataLength === 0) return 50; // Default width for empty chart
+
+        const yAxisPadding = this.yAxisLabel ? 2 : 0;
+        const yAxisNumbers = 3; // Width of Y-axis numbers
+        const separator = 1; // The '|' character
+        // const dataWidth = dataLength * 2; // Each column is 2 characters wide  // TEMP: commented for no-space test
+        const dataWidth = dataLength; // Each column is 1 character wide  // TEMP: adjusted for no-space columns
+        const padding = 1; // Extra padding
+
+        const totalWidth = yAxisPadding + yAxisNumbers + separator + dataWidth + padding;
+
+        // Only log when width changes
+        if (this.debug && this.lastChartWidth !== totalWidth) {
+            console.log('getChartWidth changed:', { dataLength, totalWidth, previous: this.lastChartWidth });
+            this.lastChartWidth = totalWidth;
+        }
+
+        return totalWidth;
+    }
+
+    /**
+     * Adjust font size to fit container width
+     * @private
+     */
+    adjustFontSize() {
+        if (!this.autoFitWidth) return;
+
+        const containerWidth = this.container.clientWidth;
+        const chartWidth = this.getChartWidth();
+
+        if (chartWidth === 0) return;
+
+        // Calculate optimal font size
+        // For monospace fonts, character width is approximately 0.6 * font size
+        // Use a slightly smaller ratio to fit more content
+        const charWidthRatio = 0.7;
+        const padding = 30; // Reduce padding to fit more content
+        const availableWidth = containerWidth - padding;
+        const optimalFontSize = Math.floor((availableWidth / chartWidth) / charWidthRatio);
+
+        // Set reasonable bounds (min 4px, max 20px)
+        const fontSize = Math.max(4, Math.min(20, optimalFontSize));
+
+        // Only log when font size changes
+        if (this.debug && this.lastFontSize !== fontSize) {
+            console.log('fontSize changed:', { containerWidth, chartWidth, fontSize, previous: this.lastFontSize });
+            this.lastFontSize = fontSize;
+        }
+
+        this.container.style.fontSize = fontSize + 'px';
+        this.container.style.lineHeight = '1.0';
+    }
+
+    /**
+     * Render the chart to the container
+     * @private
+     */
+    render() {
+        let dataToRender = [];
+        let maxValue = 0;
+        let minValue = 0;
+        let valueRange = 0;
+
+        if (this.useBinMode) {
+            // Bin mode: render bin counts
+            if (this.bins.length === 0) {
+                this.container.textContent = 'No data yet. Click Start to begin.';
+                return;
+            }
+            // Always create a fixed-length array filled with 0s, then overlay actual bin data
+            dataToRender = new Array(this.maxDataPoints).fill(0);
+
+            // Overlay actual bin data (most recent bins, reversed for left-to-right display)
+            const startIndex = Math.max(0, this.bins.length - this.maxDataPoints);
+            const recentBins = this.bins.slice(startIndex);
+
+            // Reverse the bins so most recent is on the left, and overlay onto the fixed array
+            recentBins.reverse().forEach((bin, index) => {
+                if (index < this.maxDataPoints) {
+                    dataToRender[index] = bin.count;
+                }
+            });
+
+            if (this.debug) {
+                console.log('render() dataToRender:', dataToRender, 'bins length:', this.bins.length);
+            }
+            maxValue = Math.max(...dataToRender);
+            minValue = Math.min(...dataToRender);
+            valueRange = maxValue - minValue;
+        } else {
+            // Legacy mode: render individual values
+            if (this.data.length === 0) {
+                this.container.textContent = 'No data yet. Click Start to begin.';
+                return;
+            }
+            dataToRender = this.data;
+            maxValue = Math.max(...this.data);
+            minValue = Math.min(...this.data);
+            valueRange = maxValue - minValue;
+        }
+
+        let output = '';
+        const scale = this.maxHeight;
+
+        // Calculate scaling factor: each X represents at least 1 count
+        const maxCount = Math.max(...dataToRender);
+        const scaleFactor = Math.max(1, Math.ceil(maxCount / scale)); // 1 X = scaleFactor counts
+        const scaledMax = Math.ceil(maxCount / scaleFactor) * scaleFactor;
+
+        // Calculate Y-axis label width (for vertical text)
+        const yLabelWidth = this.yAxisLabel ? 2 : 0;
+        const yAxisPadding = this.yAxisLabel ? '  ' : '';
+
+        // Add title if provided (centered)
+        if (this.title) {
+            // const chartWidth = 4 + this.maxDataPoints * 2; // Y-axis numbers + data columns  // TEMP: commented for no-space test
+            const chartWidth = 4 + this.maxDataPoints; // Y-axis numbers + data columns  // TEMP: adjusted for no-space columns
+            const titlePadding = Math.floor((chartWidth - this.title.length) / 2);
+            output += yAxisPadding + ' '.repeat(Math.max(0, titlePadding)) + this.title + '\n\n';
+        }
+
+        // Draw from top to bottom
+        for (let row = scale; row > 0; row--) {
+            let line = '';
+
+            // Add vertical Y-axis label character
+            if (this.yAxisLabel) {
+                const L = this.yAxisLabel.length;
+                const startRow = Math.floor((scale - L) / 2) + 1;
+                const relativeRow = scale - row + 1; // 1 at top, scale at bottom
+                if (relativeRow >= startRow && relativeRow < startRow + L) {
+                    const labelIndex = relativeRow - startRow;
+                    line += this.yAxisLabel[labelIndex] + ' ';
+                } else {
+                    line += '  ';
+                }
+            }
+
+            // Calculate the actual count value this row represents (1 at bottom, increasing upward)
+            const rowCount = (row - 1) * scaleFactor + 1;
+
+            // Add Y-axis label (show actual count values)
+            line += String(rowCount).padStart(3, ' ') + ' |';
+
+            // Draw each column
+            for (let i = 0; i < dataToRender.length; i++) {
+                const count = dataToRender[i];
+                const scaledHeight = Math.ceil(count / scaleFactor);
+
+                if (scaledHeight >= row) {
+                    // line += ' X';  // TEMP: commented out space between columns
+                    line += 'X';  // TEMP: no space between columns
+                } else {
+                    // line += '  ';  // TEMP: commented out space between columns
+                    line += ' ';  // TEMP: single space for empty columns
+                }
+            }
+
+            output += line + '\n';
+        }
+
+        // Draw X-axis
+        // output += yAxisPadding + '    +' + '-'.repeat(this.maxDataPoints * 2) + '\n';  // TEMP: commented out for no-space test
+        output += yAxisPadding + '    +' + '-'.repeat(this.maxDataPoints) + '\n';  // TEMP: back to original length
+
+        // Draw X-axis labels based on mode and format
+        let xAxisLabels = yAxisPadding + '     ';  // Initial padding to align with X-axis
+
+        // Determine label interval (every 5 columns)
+        const labelInterval = 5;
+
+        // Generate all labels first and store in array
+        let labels = [];
+        for (let i = 0; i < this.maxDataPoints; i++) {
+            if (i % labelInterval === 0) {
+                let label = '';
+                if (this.useBinMode) {
+                    // For bin mode, show labels for all possible positions
+                    // i=0 is leftmost (most recent), i=maxDataPoints-1 is rightmost (oldest)
+                    const elapsedSec = (i * this.binDuration) / 1000;
+                    // Format with appropriate precision for sub-second bins
+                    if (this.binDuration < 1000) {
+                        // Show decimal seconds for sub-second bins
+                        label = elapsedSec.toFixed(1) + 's';
+                    } else {
+                        // Show whole seconds for 1+ second bins
+                        label = String(Math.round(elapsedSec)) + 's';
+                    }
+                } else {
+                    // For legacy mode, show data point numbers
+                    const startIndex = Math.max(1, this.totalDataPoints - this.maxDataPoints + 1);
+                    label = String(startIndex + i);
+                }
+                labels.push(label);
+            }
+        }
+
+        // Build the label string with calculated spacing
+        for (let i = 0; i < labels.length; i++) {
+            const label = labels[i];
+            xAxisLabels += label;
+
+            // Add spacing: labelInterval - label.length (except for last label)
+            if (i < labels.length - 1) {
+                const spacing = labelInterval - label.length;
+                xAxisLabels += ' '.repeat(spacing);
+            }
+        }
+
+        // Ensure the label line extends to match the X-axis dash line length
+        // The dash line is this.maxDataPoints characters long, starting after "    +"
+        const dashLineLength = this.maxDataPoints;
+        const minLabelLineLength = yAxisPadding.length + 4 + dashLineLength; // 4 for "    "
+        if (xAxisLabels.length < minLabelLineLength) {
+            xAxisLabels += ' '.repeat(minLabelLineLength - xAxisLabels.length);
+        }
+        output += xAxisLabels + '\n';
+
+        // Add X-axis label if provided
+        if (this.xAxisLabel) {
+            // const labelPadding = Math.floor((this.maxDataPoints * 2 - this.xAxisLabel.length) / 2);  // TEMP: commented for no-space test
+            const labelPadding = Math.floor((this.maxDataPoints - this.xAxisLabel.length) / 2);  // TEMP: adjusted for no-space columns
+            output += '\n' + yAxisPadding + '     ' + ' '.repeat(Math.max(0, labelPadding)) + this.xAxisLabel + '\n';
+        }
+
+        this.container.textContent = output;
+
+        // Adjust font size to fit width (only once at initialization)
+        if (this.autoFitWidth) {
+            this.adjustFontSize();
+        }
+
+        // Update the external info display
+        if (this.useBinMode) {
+            const binCounts = this.bins.map(bin => bin.count);
+            const scaleFactor = Math.max(1, Math.ceil(maxValue / scale));
+            document.getElementById('values').textContent = `[${dataToRender.join(', ')}]`;
+            document.getElementById('max-value').textContent = maxValue;
+            document.getElementById('scale').textContent = `Min: ${minValue}, Max: ${maxValue}, 1X=${scaleFactor} counts`;
+        } else {
+            document.getElementById('values').textContent = `[${this.data.join(', ')}]`;
+            document.getElementById('max-value').textContent = maxValue;
+            document.getElementById('scale').textContent = `Min: ${minValue}, Max: ${maxValue}, Height: ${scale}`;
+        }
+    }
+
+    /**
+     * Update the info display
+     * @private
+     */
+    updateInfo() {
+        if (this.useBinMode) {
+            const totalCount = this.bins.reduce((sum, bin) => sum + bin.count, 0);
+            document.getElementById('count').textContent = totalCount;
+        } else {
+            document.getElementById('count').textContent = this.data.length;
+        }
+    }
+
+    /**
+     * Initialize the bin system
+     * @private
+     */
+    initializeBins() {
+        this.bins = [];
+        this.currentBinIndex = -1;
+        this.binStartTime = null;
+        this.chartStartTime = Date.now();
+
+        // Create first bin
+        this.rotateBin();
+
+        // Set up automatic bin rotation check
+        this.binCheckInterval = setInterval(() => {
+            this.checkBinRotation();
+        }, 100); // Check every 100ms for responsiveness
+    }
+
+    /**
+     * Check if current bin should rotate and create new bin if needed
+     * @private
+     */
+    checkBinRotation() {
+        if (!this.useBinMode || !this.binStartTime) return;
+
+        const now = Date.now();
+        if ((now - this.binStartTime) >= this.binDuration) {
+            this.rotateBin();
+        }
+    }
+
+    /**
+     * Rotate to a new bin, finalizing the current one
+     */
+    rotateBin() {
+        // Finalize current bin if it exists
+        if (this.currentBinIndex >= 0) {
+            this.bins[this.currentBinIndex].isActive = false;
+        }
+
+        // Create new bin
+        const newBin = {
+            startTime: Date.now(),
+            count: 0,
+            isActive: true
+        };
+
+        this.bins.push(newBin);
+        this.currentBinIndex = this.bins.length - 1;
+        this.binStartTime = newBin.startTime;
+
+        // Keep only the most recent bins
+        if (this.bins.length > this.maxDataPoints) {
+            this.bins.shift();
+            this.currentBinIndex--;
+        }
+
+        // Ensure currentBinIndex points to the last bin (the active one)
+        this.currentBinIndex = this.bins.length - 1;
+
+        // Force a render to update the display immediately
+        this.render();
+        this.updateInfo();
+    }
+
+    /**
+     * Format X-axis label for a bin based on the configured format
+     * @param {number} binIndex - Index of the bin
+     * @returns {string} Formatted label
+     * @private
+     */
+    formatBinLabel(binIndex) {
+        const bin = this.bins[binIndex];
+        if (!bin) return '  ';
+
+        switch (this.xAxisLabelFormat) {
+            case 'bins':
+                return String(binIndex + 1).padStart(2, ' ');
+
+            case 'timestamps':
+                const time = new Date(bin.startTime);
+                return time.toLocaleTimeString('en-US', {
+                    hour12: false,
+                    hour: '2-digit',
+                    minute: '2-digit',
+                    second: '2-digit'
+                }).replace(/:/g, '');
+
+            case 'ranges':
+                const startSec = Math.floor((bin.startTime - this.chartStartTime) / 1000);
+                const endSec = startSec + Math.floor(this.binDuration / 1000);
+                return `${startSec}-${endSec}`;
+
+            case 'elapsed':
+            default:
+                // For elapsed time, always show time relative to the first bin (index 0)
+                // This keeps the leftmost label as 0s and increases to the right
+                const firstBinTime = this.bins[0] ? this.bins[0].startTime : this.chartStartTime;
+                const elapsedSec = Math.floor((bin.startTime - firstBinTime) / 1000);
+                return String(elapsedSec).padStart(2, ' ') + 's';
+        }
+    }
+}

build_and_push.sh

@@ -1,391 +0,0 @@
-#!/bin/bash
-set -e
-
-# Colors for output
-RED='\033[0;31m'
-GREEN='\033[0;32m'
-YELLOW='\033[1;33m'
-BLUE='\033[0;34m'
-NC='\033[0m'
-
-print_status() { echo -e "${BLUE}[INFO]${NC} $1"; }
-print_success() { echo -e "${GREEN}[SUCCESS]${NC} $1"; }
-print_warning() { echo -e "${YELLOW}[WARNING]${NC} $1"; }
-print_error() { echo -e "${RED}[ERROR]${NC} $1"; }
-
-# Global variables
-COMMIT_MESSAGE=""
-RELEASE_MODE=false
-
-# Parse command line arguments
-while [[ $# -gt 0 ]]; do
-    case $1 in
-        -r|--release)
-            RELEASE_MODE=true
-            shift
-            ;;
-        -h|--help)
-            show_usage
-            exit 0
-            ;;
-        *)
-            # First non-flag argument is the commit message
-            if [[ -z "$COMMIT_MESSAGE" ]]; then
-                COMMIT_MESSAGE="$1"
-            fi
-            shift
-            ;;
-    esac
-done
-
-show_usage() {
-    echo "C-Relay Build and Push Script"
-    echo ""
-    echo "Usage:"
-    echo "  $0 \"commit message\"           - Default: compile, increment patch, commit & push"
-    echo "  $0 -r \"commit message\"        - Release: compile x86+arm64, increment minor, create release"
-    echo ""
-    echo "Examples:"
-    echo "  $0 \"Fixed event validation bug\""
-    echo "  $0 --release \"Major release with new features\""
-    echo ""
-    echo "Default Mode (patch increment):"
-    echo "  - Compile C-Relay"
-    echo "  - Increment patch version (v1.2.3 → v1.2.4)"
-    echo "  - Git add, commit with message, and push"
-    echo ""
-    echo "Release Mode (-r flag):"
-    echo "  - Compile C-Relay for x86_64 and arm64"
-    echo "  - Increment minor version, zero patch (v1.2.3 → v1.3.0)"
-    echo "  - Git add, commit, push, and create Gitea release"
-    echo ""
-    echo "Requirements for Release Mode:"
-    echo "  - For ARM64 builds: make install-arm64-deps (optional - will build x86_64 only if missing)"
-    echo "  - Gitea token in ~/.gitea_token for release uploads"
-}
-
-# Validate inputs
-if [[ -z "$COMMIT_MESSAGE" ]]; then
-    print_error "Commit message is required"
-    echo ""
-    show_usage
-    exit 1
-fi
-
-# Check if we're in a git repository
-check_git_repo() {
-    if ! git rev-parse --git-dir > /dev/null 2>&1; then
-        print_error "Not in a git repository"
-        exit 1
-    fi
-}
-
-# Function to get current version and increment appropriately
-increment_version() {
-    local increment_type="$1"  # "patch" or "minor"
-    
-    print_status "Getting current version..."
-    
-    # Get the highest version tag (not chronologically latest)
-    LATEST_TAG=$(git tag -l 'v*.*.*' | sort -V | tail -n 1 || echo "")
-    if [[ -z "$LATEST_TAG" ]]; then
-        LATEST_TAG="v0.0.0"
-        print_warning "No version tags found, starting from $LATEST_TAG"
-    fi
-    
-    # Extract version components (remove 'v' prefix)
-    VERSION=${LATEST_TAG#v}
-    
-    # Parse major.minor.patch using regex
-    if [[ $VERSION =~ ^([0-9]+)\.([0-9]+)\.([0-9]+)$ ]]; then
-        MAJOR=${BASH_REMATCH[1]}
-        MINOR=${BASH_REMATCH[2]}
-        PATCH=${BASH_REMATCH[3]}
-    else
-        print_error "Invalid version format in tag: $LATEST_TAG"
-        print_error "Expected format: v0.1.0"
-        exit 1
-    fi
-    
-    # Increment version based on type
-    if [[ "$increment_type" == "minor" ]]; then
-        # Minor release: increment minor, zero patch
-        NEW_MINOR=$((MINOR + 1))
-        NEW_PATCH=0
-        NEW_VERSION="v${MAJOR}.${NEW_MINOR}.${NEW_PATCH}"
-        print_status "Release mode: incrementing minor version"
-    else
-        # Default: increment patch
-        NEW_PATCH=$((PATCH + 1))
-        NEW_VERSION="v${MAJOR}.${MINOR}.${NEW_PATCH}"
-        print_status "Default mode: incrementing patch version"
-    fi
-    
-    print_status "Current version: $LATEST_TAG"
-    print_status "New version: $NEW_VERSION"
-    
-    # Export for use in other functions
-    export NEW_VERSION
-}
-
-# Function to compile the C-Relay project
-compile_project() {
-    print_status "Compiling C-Relay..."
-    
-    # Clean previous build
-    if make clean > /dev/null 2>&1; then
-        print_success "Cleaned previous build"
-    else
-        print_warning "Clean failed or no Makefile found"
-    fi
-    
-    # Compile the project
-    if make > /dev/null 2>&1; then
-        print_success "C-Relay compiled successfully"
-    else
-        print_error "Compilation failed"
-        exit 1
-    fi
-}
-
-# Function to build release binaries
-build_release_binaries() {
-    print_status "Building release binaries..."
-    
-    # Build x86_64 version
-    print_status "Building x86_64 version..."
-    make clean > /dev/null 2>&1
-    if make x86 > /dev/null 2>&1; then
-        if [[ -f "build/c_relay_x86" ]]; then
-            cp build/c_relay_x86 c-relay-x86_64
-            print_success "x86_64 binary created: c-relay-x86_64"
-        else
-            print_error "x86_64 binary not found after compilation"
-            exit 1
-        fi
-    else
-        print_error "x86_64 build failed"
-        exit 1
-    fi
-    
-    # Try to build ARM64 version
-    print_status "Attempting ARM64 build..."
-    make clean > /dev/null 2>&1
-    if make arm64 > /dev/null 2>&1; then
-        if [[ -f "build/c_relay_arm64" ]]; then
-            cp build/c_relay_arm64 c-relay-arm64
-            print_success "ARM64 binary created: c-relay-arm64"
-        else
-            print_warning "ARM64 binary not found after compilation"
-        fi
-    else
-        print_warning "ARM64 build failed - ARM64 cross-compilation not properly set up"
-        print_status "Only x86_64 binary will be included in release"
-    fi
-    
-    # Restore normal build
-    make clean > /dev/null 2>&1
-    make > /dev/null 2>&1
-}
-
-# Function to commit and push changes
-git_commit_and_push() {
-    print_status "Preparing git commit..."
-    
-    # Stage all changes
-    if git add . > /dev/null 2>&1; then
-        print_success "Staged all changes"
-    else
-        print_error "Failed to stage changes"
-        exit 1
-    fi
-    
-    # Check if there are changes to commit
-    if git diff --staged --quiet; then
-        print_warning "No changes to commit"
-    else
-        # Commit changes
-        if git commit -m "$NEW_VERSION - $COMMIT_MESSAGE" > /dev/null 2>&1; then
-            print_success "Committed changes"
-        else
-            print_error "Failed to commit changes"
-            exit 1
-        fi
-    fi
-    
-    # Create new git tag
-    if git tag "$NEW_VERSION" > /dev/null 2>&1; then
-        print_success "Created tag: $NEW_VERSION"
-    else
-        print_warning "Tag $NEW_VERSION already exists"
-    fi
-    
-    # Push changes and tags
-    print_status "Pushing to remote repository..."
-    if git push > /dev/null 2>&1; then
-        print_success "Pushed changes"
-    else
-        print_error "Failed to push changes"
-        exit 1
-    fi
-    
-    if git push --tags > /dev/null 2>&1; then
-        print_success "Pushed tags"
-    else
-        print_warning "Failed to push tags"
-    fi
-}
-
-# Function to create Gitea release
-create_gitea_release() {
-    print_status "Creating Gitea release..."
-    
-    # Check for Gitea token
-    if [[ ! -f "$HOME/.gitea_token" ]]; then
-        print_warning "No ~/.gitea_token found. Skipping release creation."
-        print_warning "Create ~/.gitea_token with your Gitea access token to enable releases."
-        return 0
-    fi
-    
-    local token=$(cat "$HOME/.gitea_token" | tr -d '\n\r')
-    local api_url="https://git.laantungir.net/api/v1/repos/laantungir/c-relay"
-    
-    # Create release
-    print_status "Creating release $NEW_VERSION..."
-    local response=$(curl -s -X POST "$api_url/releases" \
-         -H "Authorization: token $token" \
-         -H "Content-Type: application/json" \
-         -d "{\"tag_name\": \"$NEW_VERSION\", \"name\": \"$NEW_VERSION\", \"body\": \"$COMMIT_MESSAGE\"}")
-    
-    if echo "$response" | grep -q '"id"'; then
-        print_success "Created release $NEW_VERSION"
-        upload_release_binaries "$api_url" "$token"
-    elif echo "$response" | grep -q "already exists"; then
-        print_warning "Release $NEW_VERSION already exists"
-        upload_release_binaries "$api_url" "$token"
-    else
-        print_error "Failed to create release $NEW_VERSION"
-        print_error "Response: $response"
-        
-        # Try to check if the release exists anyway
-        print_status "Checking if release exists..."
-        local check_response=$(curl -s -H "Authorization: token $token" "$api_url/releases/tags/$NEW_VERSION")
-        if echo "$check_response" | grep -q '"id"'; then
-            print_warning "Release exists but creation response was unexpected"
-            upload_release_binaries "$api_url" "$token"
-        else
-            print_error "Release does not exist and creation failed"
-            return 1
-        fi
-    fi
-}
-
-# Function to upload release binaries
-upload_release_binaries() {
-    local api_url="$1"
-    local token="$2"
-    
-    # Get release ID with more robust parsing
-    print_status "Getting release ID for $NEW_VERSION..."
-    local response=$(curl -s -H "Authorization: token $token" "$api_url/releases/tags/$NEW_VERSION")
-    local release_id=$(echo "$response" | grep -o '"id":[0-9]*' | head -n1 | cut -d: -f2)
-    
-    if [[ -z "$release_id" ]]; then
-        print_error "Could not get release ID for $NEW_VERSION"
-        print_error "API Response: $response"
-        
-        # Try to list all releases to debug
-        print_status "Available releases:"
-        curl -s -H "Authorization: token $token" "$api_url/releases" | grep -o '"tag_name":"[^"]*"' | head -5
-        return 1
-    fi
-    
-    print_success "Found release ID: $release_id"
-    
-    # Upload x86_64 binary
-    if [[ -f "c-relay-x86_64" ]]; then
-        print_status "Uploading x86_64 binary..."
-        if curl -s -X POST "$api_url/releases/$release_id/assets" \
-                -H "Authorization: token $token" \
-                -F "attachment=@c-relay-x86_64;filename=c-relay-${NEW_VERSION}-linux-x86_64" > /dev/null; then
-            print_success "Uploaded x86_64 binary"
-        else
-            print_warning "Failed to upload x86_64 binary"
-        fi
-    fi
-    
-    # Upload ARM64 binary
-    if [[ -f "c-relay-arm64" ]]; then
-        print_status "Uploading ARM64 binary..."
-        if curl -s -X POST "$api_url/releases/$release_id/assets" \
-                -H "Authorization: token $token" \
-                -F "attachment=@c-relay-arm64;filename=c-relay-${NEW_VERSION}-linux-arm64" > /dev/null; then
-            print_success "Uploaded ARM64 binary"
-        else
-            print_warning "Failed to upload ARM64 binary"
-        fi
-    fi
-}
-
-# Function to clean up release binaries
-cleanup_release_binaries() {
-    if [[ -f "c-relay-x86_64" ]]; then
-        rm -f c-relay-x86_64
-        print_status "Cleaned up x86_64 binary"
-    fi
-    if [[ -f "c-relay-arm64" ]]; then
-        rm -f c-relay-arm64
-        print_status "Cleaned up ARM64 binary"
-    fi
-}
-
-# Main execution
-main() {
-    print_status "C-Relay Build and Push Script"
-    
-    # Check prerequisites
-    check_git_repo
-    
-    if [[ "$RELEASE_MODE" == true ]]; then
-        print_status "=== RELEASE MODE ==="
-        
-        # Increment minor version for releases
-        increment_version "minor"
-        
-        # Compile project first
-        compile_project
-        
-        # Build release binaries
-        build_release_binaries
-        
-        # Commit and push
-        git_commit_and_push
-        
-        # Create Gitea release with binaries
-        create_gitea_release
-        
-        # Cleanup
-        cleanup_release_binaries
-        
-        print_success "Release $NEW_VERSION completed successfully!"
-        print_status "Binaries uploaded to Gitea release"
-        
-    else
-        print_status "=== DEFAULT MODE ==="
-        
-        # Increment patch version for regular commits
-        increment_version "patch"
-        
-        # Compile project
-        compile_project
-        
-        # Commit and push
-        git_commit_and_push
-        
-        print_success "Build and push completed successfully!"
-        print_status "Version $NEW_VERSION pushed to repository"
-    fi
-}
-
-# Execute main function
-main

build_static.sh

@@ -0,0 +1,271 @@
+#!/bin/bash
+
+# Build fully static MUSL binaries for C-Relay-PG using Alpine Docker
+# Produces truly portable binaries with zero runtime dependencies
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+BUILD_DIR="$SCRIPT_DIR/build"
+DOCKERFILE="$SCRIPT_DIR/Dockerfile.alpine-musl"
+
+# Parse command line arguments
+DEBUG_BUILD=false
+DB_BACKEND="${DB_BACKEND:-postgres}"
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --debug)
+            DEBUG_BUILD=true
+            shift
+            ;;
+        --db-backend)
+            if [[ -z "$2" ]]; then
+                echo "ERROR: --db-backend requires a value (sqlite|postgres)"
+                exit 1
+            fi
+            DB_BACKEND="$2"
+            shift 2
+            ;;
+        --db-backend=*)
+            DB_BACKEND="${1#*=}"
+            shift
+            ;;
+        *)
+            echo "ERROR: Unknown argument: $1"
+            echo "Usage: $0 [--debug] [--db-backend postgres|sqlite]"
+            exit 1
+            ;;
+    esac
+done
+
+if [[ "$DB_BACKEND" != "sqlite" && "$DB_BACKEND" != "postgres" ]]; then
+    echo "ERROR: Invalid DB backend '$DB_BACKEND'. Use sqlite or postgres."
+    exit 1
+fi
+
+if [[ "$DEBUG_BUILD" == "true" ]]; then
+    echo "=========================================="
+    echo "C-Relay-PG MUSL Static Binary Builder (DEBUG MODE)"
+    echo "=========================================="
+else
+    echo "=========================================="
+    echo "C-Relay-PG MUSL Static Binary Builder (PRODUCTION MODE)"
+    echo "=========================================="
+fi
+echo "Project directory: $SCRIPT_DIR"
+echo "Build directory: $BUILD_DIR"
+echo "Debug build: $DEBUG_BUILD"
+echo "DB backend: $DB_BACKEND"
+echo ""
+
+# Create build directory
+mkdir -p "$BUILD_DIR"
+
+# Check if Docker is available
+if ! command -v docker &> /dev/null; then
+    echo "ERROR: Docker is not installed or not in PATH"
+    echo ""
+    echo "Docker is required to build MUSL static binaries."
+    echo "Please install Docker:"
+    echo "  - Ubuntu/Debian: sudo apt install docker.io"
+    echo "  - Or visit: https://docs.docker.com/engine/install/"
+    echo ""
+    exit 1
+fi
+
+# Check if Docker daemon is running
+if ! docker info &> /dev/null; then
+    echo "ERROR: Docker daemon is not running or user not in docker group"
+    echo ""
+    echo "Please start Docker and ensure you're in the docker group:"
+    echo "  - sudo systemctl start docker"
+    echo "  - sudo usermod -aG docker $USER && newgrp docker"
+    echo "  - Or start Docker Desktop"
+    echo ""
+    exit 1
+fi
+
+DOCKER_CMD="docker"
+
+echo "✓ Docker is available and running"
+echo ""
+
+# Detect architecture
+ARCH=$(uname -m)
+case "$ARCH" in
+    x86_64)
+        PLATFORM="linux/amd64"
+        OUTPUT_NAME="c_relay_pg_static_x86_64"
+        ;;
+    aarch64|arm64)
+        PLATFORM="linux/arm64"
+        OUTPUT_NAME="c_relay_pg_static_arm64"
+        ;;
+    *)
+        echo "WARNING: Unknown architecture: $ARCH"
+        echo "Defaulting to linux/amd64"
+        PLATFORM="linux/amd64"
+        OUTPUT_NAME="c_relay_pg_static_${ARCH}"
+        ;;
+esac
+
+# Append _debug suffix to output name for debug builds so production binary is never overwritten
+if [ "$DEBUG_BUILD" = true ]; then
+    OUTPUT_NAME="${OUTPUT_NAME}_debug"
+fi
+
+echo "Building for platform: $PLATFORM"
+echo "Output binary: $OUTPUT_NAME"
+echo ""
+
+# Check if Alpine base image is cached
+echo "Checking for cached Alpine Docker image..."
+if ! docker images alpine:3.19 --format "{{.Repository}}:{{.Tag}}" | grep -q "alpine:3.19"; then
+    echo "⚠ Alpine 3.19 image not found in cache"
+    echo "Attempting to pull Alpine 3.19 image..."
+    if ! docker pull alpine:3.19; then
+        echo ""
+        echo "ERROR: Failed to pull Alpine 3.19 image"
+        echo "This is required for the static build."
+        echo ""
+        echo "Possible solutions:"
+        echo "  1. Check your internet connection"
+        echo "  2. Try again later (Docker Hub may be temporarily unavailable)"
+        echo "  3. If you have IPv6 issues, disable IPv6 for Docker"
+        echo ""
+        exit 1
+    fi
+    echo "✓ Alpine 3.19 image pulled successfully"
+else
+    echo "✓ Alpine 3.19 image found in cache"
+fi
+echo ""
+
+# Build the Docker image
+echo "=========================================="
+echo "Step 1: Building Alpine Docker image"
+echo "=========================================="
+echo "This will:"
+echo "  - Use Alpine Linux (native MUSL)"
+echo "  - Build all dependencies statically"
+echo "  - Compile c-relay-pg with full static linking"
+echo ""
+
+$DOCKER_CMD build \
+    --platform "$PLATFORM" \
+    --build-arg DEBUG_BUILD=$DEBUG_BUILD \
+    --build-arg DB_BACKEND=$DB_BACKEND \
+    -f "$DOCKERFILE" \
+    -t c-relay-pg-musl-builder:latest \
+    --progress=plain \
+    . || {
+        echo ""
+        echo "ERROR: Docker build failed"
+        echo "Check the output above for details"
+        exit 1
+    }
+
+echo ""
+echo "✓ Docker image built successfully"
+echo ""
+
+# Extract the binary from the container
+echo "=========================================="
+echo "Step 2: Extracting static binary"
+echo "=========================================="
+
+# Build the builder stage to extract the binary
+$DOCKER_CMD build \
+    --platform "$PLATFORM" \
+    --build-arg DEBUG_BUILD=$DEBUG_BUILD \
+    --build-arg DB_BACKEND=$DB_BACKEND \
+    --target builder \
+    -f "$DOCKERFILE" \
+    -t c-relay-pg-static-builder-stage:latest \
+    . > /dev/null 2>&1
+
+# Create a temporary container to copy the binary
+CONTAINER_ID=$($DOCKER_CMD create c-relay-pg-static-builder-stage:latest)
+
+# Copy binary from container
+$DOCKER_CMD cp "$CONTAINER_ID:/build/c_relay_pg_static" "$BUILD_DIR/$OUTPUT_NAME" || {
+    echo "ERROR: Failed to extract binary from container"
+    $DOCKER_CMD rm "$CONTAINER_ID" 2>/dev/null
+    exit 1
+}
+
+# Clean up container
+$DOCKER_CMD rm "$CONTAINER_ID" > /dev/null
+
+echo "✓ Binary extracted to: $BUILD_DIR/$OUTPUT_NAME"
+echo ""
+
+# Make binary executable
+chmod +x "$BUILD_DIR/$OUTPUT_NAME"
+
+# Verify the binary
+echo "=========================================="
+echo "Step 3: Verifying static binary"
+echo "=========================================="
+echo ""
+
+echo "Checking for dynamic dependencies:"
+if LDD_OUTPUT=$(timeout 5 ldd "$BUILD_DIR/$OUTPUT_NAME" 2>&1); then
+    if echo "$LDD_OUTPUT" | grep -q "not a dynamic executable"; then
+        echo "✓ Binary is fully static (no dynamic dependencies)"
+        TRULY_STATIC=true
+    elif echo "$LDD_OUTPUT" | grep -q "statically linked"; then
+        echo "✓ Binary is statically linked"
+        TRULY_STATIC=true
+    else
+        echo "⚠ WARNING: Binary may have dynamic dependencies:"
+        echo "$LDD_OUTPUT"
+        TRULY_STATIC=false
+    fi
+else
+    # ldd failed or timed out - check with file command instead
+    if file "$BUILD_DIR/$OUTPUT_NAME" | grep -q "statically linked"; then
+        echo "✓ Binary is statically linked (verified with file command)"
+        TRULY_STATIC=true
+    else
+        echo "⚠ Could not verify static linking (ldd check failed)"
+        TRULY_STATIC=false
+    fi
+fi
+echo ""
+
+echo "File size: $(ls -lh "$BUILD_DIR/$OUTPUT_NAME" | awk '{print $5}')"
+echo ""
+
+# Test if binary runs
+echo "Testing binary execution:"
+if "$BUILD_DIR/$OUTPUT_NAME" --version 2>&1 | head -5; then
+    echo "✓ Binary executes successfully"
+else
+    echo "⚠ Binary execution test failed (this may be normal if --version is not supported)"
+fi
+echo ""
+
+# Summary
+echo "=========================================="
+echo "Build Summary"
+echo "=========================================="
+echo "Binary: $BUILD_DIR/$OUTPUT_NAME"
+echo "Size: $(du -h "$BUILD_DIR/$OUTPUT_NAME" | cut -f1)"
+echo "Platform: $PLATFORM"
+if [ "$DEBUG_BUILD" = true ]; then
+    echo "Build Type: DEBUG (with symbols, no optimization)"
+else
+    echo "Build Type: PRODUCTION (optimized, stripped)"
+fi
+echo "DB Backend: $DB_BACKEND"
+if [ "$TRULY_STATIC" = true ]; then
+    echo "Linkage: Fully static binary (Alpine MUSL-based)"
+    echo "Portability: Works on ANY Linux distribution"
+else
+    echo "Linkage: Static binary (may have minimal dependencies)"
+fi
+echo ""
+echo "✓ Build complete!"
+echo ""

c-relay-pg.code-workspace

@@ -0,0 +1,8 @@
+{
+	"folders": [
+		{
+			"path": "."
+		}
+	],
+	"settings": {}
+}

caching/.gitignore

@@ -0,0 +1,31 @@
+# Database files (from c-relay running in this directory)
+*.db
+*.db-shm
+*.db-wal
+
+# Build artifacts
+*.o
+*.a
+
+# Binary (built into root, not version-controlled)
+caching_relay
+caching_relay_static_*
+
+# Logs
+*.log
+crelay.log
+
+# Test configs (not for version control)
+test_config*.jsonc
+
+# Note: caching_relay_config.jsonc IS version-controlled (it's the default
+# config + state store). Don't ignore it.
+
+# Docker build context temp (copied nostr_core_lib during static build)
+nostr_core_lib/
+
+# Editor
+*.swp
+*.swo
+*~
+.vscode/

caching/Dockerfile.alpine-musl

@@ -0,0 +1,128 @@
+# Alpine-based MUSL static binary builder for caching_relay
+# Produces a truly portable binary with zero runtime dependencies.
+# Adapted from c-relay's Dockerfile.alpine-musl.
+
+ARG DEBUG_BUILD=false
+
+FROM alpine:3.19 AS builder
+
+ARG DEBUG_BUILD=false
+
+# Install build dependencies
+RUN apk add --no-cache \
+    build-base \
+    musl-dev \
+    git \
+    cmake \
+    pkgconfig \
+    autoconf \
+    automake \
+    libtool \
+    openssl-dev \
+    openssl-libs-static \
+    zlib-dev \
+    zlib-static \
+    curl-dev \
+    curl-static \
+    sqlite-dev \
+    postgresql-dev \
+    linux-headers \
+    wget \
+    bash
+
+WORKDIR /build
+
+# Build libsecp256k1 static
+RUN cd /tmp && \
+    git clone https://github.com/bitcoin-core/secp256k1.git && \
+    cd secp256k1 && \
+    ./autogen.sh && \
+    ./configure --enable-static --disable-shared --prefix=/usr \
+        CFLAGS="-fPIC" && \
+    make -j$(nproc) && \
+    make install && \
+    rm -rf /tmp/secp256k1
+
+# Build libwebsockets static with minimal features
+RUN cd /tmp && \
+    git clone --depth 1 --branch v4.3.3 https://github.com/warmcat/libwebsockets.git && \
+    cd libwebsockets && \
+    mkdir build && cd build && \
+    cmake .. \
+        -DLWS_WITH_STATIC=ON \
+        -DLWS_WITH_SHARED=OFF \
+        -DLWS_WITH_SSL=ON \
+        -DLWS_WITHOUT_TESTAPPS=ON \
+        -DLWS_WITHOUT_TEST_SERVER=ON \
+        -DLWS_WITHOUT_TEST_CLIENT=ON \
+        -DLWS_WITHOUT_TEST_PING=ON \
+        -DLWS_WITH_HTTP2=OFF \
+        -DLWS_WITH_LIBUV=OFF \
+        -DLWS_WITH_LIBEVENT=OFF \
+        -DLWS_IPV6=ON \
+        -DCMAKE_BUILD_TYPE=Release \
+        -DCMAKE_INSTALL_PREFIX=/usr \
+        -DCMAKE_C_FLAGS="-fPIC" && \
+    make -j$(nproc) && \
+    make install && \
+    rm -rf /tmp/libwebsockets
+
+# Copy nostr_core_lib source (sibling project)
+COPY nostr_core_lib /build/nostr_core_lib/
+
+# Build nostr_core_lib with the NIPs needed by the relay pool + signer:
+# 1 (basic), 6 (keys), 19 (npub bech32), 4 (legacy encryption, signer dep),
+# 42 (auth, relay pool dep), 44 (modern encryption, signer dep)
+RUN cd nostr_core_lib && \
+    chmod +x build.sh && \
+    sed -i 's/CFLAGS="-Wall -Wextra -std=c99 -fPIC -O2"/CFLAGS="-U_FORTIFY_SOURCE -D_FORTIFY_SOURCE=0 -Wall -Wextra -std=c99 -fPIC -O2"/' build.sh && \
+    rm -f *.o *.a 2>/dev/null || true && \
+    ./build.sh --nips=1,4,6,19,42,44 && \
+    if [ -f libnostr_core_arm64.a ]; then \
+        cp libnostr_core_arm64.a libnostr_core.a; \
+    elif [ -f libnostr_core_x64.a ]; then \
+        cp libnostr_core_x64.a libnostr_core.a; \
+    else \
+        echo "ERROR: No supported nostr_core static library produced"; \
+        ls -la *.a 2>/dev/null || true; \
+        exit 1; \
+    fi
+
+# Copy caching_relay source LAST (only this layer rebuilds on source changes)
+COPY src/ /build/src/
+
+# Build caching_relay with full static linking.
+# No sqlite (the daemon doesn't use it), no c_utils (not needed).
+RUN if [ "$DEBUG_BUILD" = "true" ]; then \
+        CFLAGS="-g -O2 -DDEBUG -fno-omit-frame-pointer"; \
+        STRIP_CMD="echo 'Keeping debug symbols'"; \
+    else \
+        CFLAGS="-O2"; \
+        STRIP_CMD="strip /build/caching_relay_static"; \
+    fi && \
+    gcc -static $CFLAGS -Wall -Wextra -std=c99 \
+    -U_FORTIFY_SOURCE -D_FORTIFY_SOURCE=0 \
+    -I. -Isrc -Inostr_core_lib -Inostr_core_lib/nostr_core \
+    -Inostr_core_lib/cjson -Inostr_core_lib/nostr_websocket \
+    -I/usr/include/postgresql \
+    src/main.c src/debug.c src/jsonc_strip.c src/config.c src/state.c \
+    src/follow_graph.c src/relay_sink.c src/live_subscriber.c \
+    src/backfill.c src/relay_discovery.c \
+    src/pg_inbox.c src/pg_config.c src/forward_catchup.c \
+    -o /build/caching_relay_static \
+    nostr_core_lib/libnostr_core.a \
+    -lwebsockets -lssl -lcrypto -lsecp256k1 \
+    -lcurl -lz -lpthread -lm -ldl -lpq -lpgcommon -lpgport && \
+    eval "$STRIP_CMD"
+
+# Verify it's truly static
+RUN echo "=== Binary Information ===" && \
+    file /build/caching_relay_static && \
+    ls -lh /build/caching_relay_static && \
+    echo "=== Checking for dynamic dependencies ===" && \
+    (ldd /build/caching_relay_static 2>&1 || echo "Binary is static") && \
+    echo "=== Build complete ==="
+
+# Output stage - just the binary
+FROM scratch AS output
+COPY --from=builder /build/caching_relay_static /caching_relay_static

caching/Makefile

@@ -0,0 +1,67 @@
+# caching_relay Makefile - statically linked C99 binary, c-relay style
+
+# Use bash for reliable glob expansion in recipes (dash handles globs differently).
+SHELL := /bin/bash
+
+CC = gcc
+CFLAGS = -Wall -Wextra -std=c99 -g -O2
+
+# nostr_core_lib is inside the c-relay-pg project root (one dir up from caching/).
+NOSTR_CORE_DIR = ../nostr_core_lib
+
+INCLUDES = -I. -Isrc -I$(NOSTR_CORE_DIR) -I$(NOSTR_CORE_DIR)/nostr_core \
+           -I$(NOSTR_CORE_DIR)/cjson -I$(NOSTR_CORE_DIR)/nostr_websocket \
+           -I/usr/include/postgresql
+
+# -lsqlite3: nostr_core_lib's request_validator.x64.o references SQLite symbols;
+# we use --whole-archive so the linker pulls in all objects (needed for NIP-42
+# cross-references within the archive), which means SQLite must be satisfied.
+# No c_utils_lib: nostr_core_lib does not depend on it for the NIPs we use.
+# -lpq: PostgreSQL client library for the caching_event_inbox integration.
+LIBS = -lwebsockets -lssl -lcrypto -lsecp256k1 -lcurl -lz -ldl -lpthread -lm -lpq -lsqlite3
+
+MAIN_SRC = src/main.c src/debug.c src/jsonc_strip.c src/config.c src/state.c \
+           src/follow_graph.c src/relay_sink.c src/live_subscriber.c \
+           src/backfill.c src/forward_catchup.c src/relay_discovery.c \
+           src/pg_inbox.c src/pg_config.c
+
+# Architecture detection
+ARCH = $(shell uname -m)
+ifeq ($(ARCH),x86_64)
+    NOSTR_CORE_LIB = $(NOSTR_CORE_DIR)/libnostr_core_x64.a
+else ifeq ($(ARCH),aarch64)
+    NOSTR_CORE_LIB = $(NOSTR_CORE_DIR)/libnostr_core_arm64.a
+else ifeq ($(ARCH),arm64)
+    NOSTR_CORE_LIB = $(NOSTR_CORE_DIR)/libnostr_core_arm64.a
+else
+    NOSTR_CORE_LIB = $(NOSTR_CORE_DIR)/libnostr_core_x64.a
+endif
+
+# Binary goes in the c-relay-pg build/ directory so the launcher can find it.
+TARGET = ../build/caching_relay
+
+all: $(TARGET)
+
+# Build nostr_core_lib with the NIPs needed by the relay pool + signer:
+# 1 (basic), 6 (keys), 19 (npub bech32), 4 (legacy encryption, signer dep),
+# 42 (auth, relay pool dep), 44 (modern encryption, signer dep)
+$(NOSTR_CORE_LIB):
+	@echo "Building nostr_core_lib with required NIPs..."
+	cd $(NOSTR_CORE_DIR) && ./build.sh --nips=1,4,6,19,42,44
+
+$(TARGET): $(MAIN_SRC) $(NOSTR_CORE_LIB)
+	@echo "Compiling caching_relay for architecture: $(ARCH)"
+	@# Extract all objects from the static library and link them directly.
+	@# This avoids archive symbol resolution ordering issues (NIP-42 cross-refs).
+	@# Use a fixed temp dir and chain all commands with && so failures stop the build.
+	@rm -rf /tmp/cr_lib && mkdir -p /tmp/cr_lib && \
+	    ar x $(NOSTR_CORE_LIB) --output=/tmp/cr_lib && \
+	    echo "Extracted $$(ls /tmp/cr_lib/*.o | wc -l) objects" && \
+	    $(CC) $(CFLAGS) $(INCLUDES) $(MAIN_SRC) /tmp/cr_lib/*.o -o $(TARGET) $(LIBS) && \
+	    rm -rf /tmp/cr_lib && \
+	    echo "Build complete: $(TARGET)"
+
+clean:
+	rm -f $(TARGET)
+
+.PHONY: all clean

caching/README.md

@@ -0,0 +1,297 @@
+# caching_relay
+
+A C99 daemon that caches Nostr events from people you follow into a local relay,
+so your Nostr client can point at a single fast local relay instead of fanning
+out to dozens of upstream relays.
+
+## What it does
+
+1. Reads a `.jsonc` config file listing your **root npub(s)**, upstream relays,
+   a local relay URL, and the event kinds to cache.
+2. For each root npub, fetches its kind-3 contact list to discover **followed
+   pubkeys** (your follows + their follows).
+3. **Live-subscribes** to new events of the configured kinds from the union of
+   followed pubkeys.
+4. **Backfills** historical events using a progressive window-expansion strategy
+   (24h → 7d → 30d → 90d → 365d), round-robin per pubkey, throttled to be polite
+   to upstream relays.
+5. **Re-publishes** every fetched event to the local relay via a plain WebSocket
+   `EVENT` client connection (relay-agnostic - works with c-relay, c-relay-pg,
+   or any Nostr relay).
+6. Persists its backfill progress **in the config file itself** so a restart
+   resumes where it left off.
+
+## Build
+
+### Static binary (recommended, c-relay style)
+
+Produces a truly portable statically-linked MUSL binary with zero runtime
+dependencies:
+
+```bash
+./build_static.sh
+# or with debug symbols:
+./build_static.sh --debug
+# or cross-compile for arm64:
+./build_static.sh --arch arm64
+```
+
+Output: `caching_relay` (in the project root).
+
+Requires Docker. The build runs in an Alpine container that compiles
+libsecp256k1, libwebsockets, and nostr_core_lib from source, then statically
+links everything.
+
+### Local build (if you have the shared libs installed)
+
+```bash
+make
+```
+
+Output: `caching_relay` (in the project root).
+
+Requires: `libwebsockets`, `openssl`, `libsecp256k1`, `libcurl`, `zlib` shared
+libraries, and a pre-built `../nostr_core_lib/libnostr_core_x64.a`.
+
+## Usage
+
+```bash
+./caching_relay -d 3
+```
+
+The daemon looks for `caching_relay_config.jsonc` in the current directory by default.
+You can override with `-c`:
+
+```bash
+./caching_relay -c /path/to/my_config.jsonc -d 3
+```
+
+Options:
+- `-c, --config <file>` - Path to `.jsonc` config file (default: `./caching_relay_config.jsonc`)
+- `-d, --debug <level>` - Log level 1-4 (1=error, 2=warn, 3=info, 4=debug). Default 3.
+- `-h, --help` - Show help
+
+Signals:
+- `SIGINT` / `SIGTERM` - Graceful shutdown (saves state, closes connections)
+- `SIGHUP` - Reload config (preserves backfill state)
+
+## Config file
+
+The config file [`caching_relay_config.jsonc`](caching_relay_config.jsonc) lives in the
+project root. It is JSONC (JSON with `//` and `/* */` comments). The daemon
+rewrites it as plain JSON when saving state (comments are not preserved on
+rewrite).
+
+Key fields:
+
+| Field | Description |
+|-------|-------------|
+| `root_npubs` | npubs whose kind-3 follows list we crawl |
+| `upstream_relays` | bootstrap relays for initial discovery (kind-3, kind-10002). Outbox relays are discovered dynamically via NIP-65. |
+| `local_relay` | relay to publish cached events into (never queried) |
+| `kinds` | event kinds to cache for followed people (e.g. `[1, 3, 6, 10000, 30023]`) |
+| `admin_kinds` | kinds to follow specifically for root (admin) npubs. Use `["*"]` for all kinds. If omitted, admin uses same `kinds` as everyone else. |
+| `backfill.window_schedule_seconds` | progressive window sizes in seconds |
+| `backfill.events_per_tick` | max events per pubkey per backfill tick |
+| `backfill.tick_interval_seconds` | delay between pubkey backfills (throttle) |
+| `live.enabled` | enable live subscription |
+| `follow_graph_refresh_seconds` | how often to re-resolve the follow graph |
+| `state.*` | managed by the daemon - do not hand-edit |
+
+## Architecture
+
+See [`plans/plan.md`](plans/plan.md) for the full architecture document with
+Mermaid diagrams.
+
+The daemon uses a **NIP-65 outbox model**: instead of querying a fixed set of
+bootstrap relays for everything, it discovers which relays each followed pubkey
+actually posts to (via kind 10002 relay lists) and connects to those relays
+dynamically. The `upstream_relays` in the config serve only as **bootstrap
+relays** -- the initial set used to discover kind-3 and kind-10002 events before
+the outbox relay map is built.
+
+### Relay pool selection: minimum covering set
+
+After discovering each followed pubkey's outbox relays (from their kind 10002),
+the daemon computes the **minimum set of relays that covers all followed
+pubkeys**. This is the classic set cover problem, solved with a greedy
+approximation:
+
+1. Build a map: `{relay_url -> set of pubkeys that list it in their 10002}`
+2. Greedily pick the relay that covers the most uncovered pubkeys
+3. Repeat until all pubkeys are covered (or no more relays to pick)
+4. Always include the bootstrap relays in the final set (they may have events
+   from pubkeys that don't publish a kind 10002)
+
+This minimizes the number of WebSocket connections while ensuring every
+followed pubkey is reachable. The daemon logs the selected relay set and which
+pubkeys each relay covers.
+
+Pubkeys that have no kind 10002 (or whose 10002 lists no relays) are covered by
+the bootstrap relays as a fallback.
+
+```
+                    ┌─────────────────────────────────────────┐
+                    │              caching_relay               │
+                    │                                          │
+   upstream relays  │  upstream_pool          sink_pool        │  local relay
+   (damus, nos.lol) │  (query + subscribe)    (publish only)   │  (c-relay)
+        │           │          │                   │           │      │
+        │           │   follow_graph         relay_sink        │      │
+        └──────────►│   live_subscriber ──────►│              ├─────►│
+                    │   backfill ──────────────►│              │      │
+                    │          │                   │           │      │
+                    │       state + seen ring      │           │      │
+                    └──────────────────────────────────────────┘      │
+```
+
+Two `nostr_relay_pool_t` instances:
+- **upstream_pool** - holds bootstrap relays initially, then dynamically adds
+  outbox relays discovered from kind 10002. Used for `query_sync` (kind-3 fetch,
+  kind-10002 fetch, backfill) and the long-lived live subscription.
+- **sink_pool** - holds only the local relay; used exclusively for
+  `publish_async`. Never queried.
+
+## Startup Flow
+
+### First-time startup (empty local relay)
+
+The daemon has never run before. The local relay has no cached events. The
+daemon must bootstrap from the config's `upstream_relays` to discover the
+outbox relays for each followed pubkey.
+
+```
+ START
+   |
+   v
+ Load config (caching_relay_config.jsonc)
+   |  - root_npubs, upstream_relays (bootstrap), kinds, admin_kinds
+   |  - state.backfilled_until == 0  =>  first-time startup
+   |
+   v
+ Create upstream_pool with bootstrap relays only
+ Create sink_pool with local_relay
+   |
+   v
+ Phase 1: Resolve follow graph (from bootstrap relays)
+   |  - For each root npub: query_sync kind=3 from bootstrap relays
+   |  - Parse "p" tags => followed pubkey set
+   |  - Log: "follow: resolved N followed pubkeys"
+   |
+   v
+ Phase 2: Discover outbox relays (NIP-65, kind 10002) from bootstrap relays
+   |  - For each followed pubkey: query_sync kind=10002 from bootstrap relays
+   |  - Parse "r" tags => per-pubkey relay list
+   |  - Publish all kind-10002 events to local relay (cache them)
+   |  - Dynamically add discovered relays to upstream_pool
+   |  - Log: "relay_discovery: found N relays from M pubkeys"
+   |  - Log: "upstream_pool: now connected to N relays" + list them
+   |
+   v
+ Phase 3: Open live subscriptions on upstream_pool
+   |  - follows_sub: non-admin pubkeys + regular kinds
+   |  - admin_sub: admin npubs + admin_kinds (or all kinds)
+   |
+   v
+ Phase 4: Begin progressive backfill
+   |  - Window 0: 24h  -> query each pubkey from their outbox relays
+   |  - Window 1: 7d   -> ...
+   |  - Window 2: 30d  -> ...
+   |  - Publish all fetched events to local relay
+   |  - Save state to config file as each window completes
+   |
+   v
+ Steady-state: live sub + periodic follow-graph refresh + periodic
+   kind-10002 refresh + backfill re-cycle
+   |
+   v
+ SHUTDOWN (SIGINT/SIGTERM) -> save state -> clean exit
+```
+
+### Subsequent startup (local relay already has cached events)
+
+The daemon has run before. The local relay already has kind-3 and kind-10002
+events cached from the previous run. The daemon can read these from the local
+relay directly (fast, no network round-trip to bootstrap relays) and only falls
+back to bootstrap relays for pubkeys it cannot find locally.
+
+```
+ START
+   |
+   v
+ Load config (caching_relay_config.jsonc)
+   |  - state.backfilled_until > 0  =>  subsequent startup
+   |  - state.current_window_index, backfill_cursor preserved
+   |
+   v
+ Create upstream_pool with bootstrap relays
+ Create sink_pool with local_relay
+   |
+   v
+ Phase 1: Resolve follow graph (from LOCAL relay first, bootstrap fallback)
+   |  - Query local relay for kind=3 per root npub
+   |  - If found locally: use it (fast, no upstream query)
+   |  - If not found: fall back to bootstrap relays
+   |  - Parse "p" tags => followed pubkey set
+   |  - Log: "follow: resolved N followed pubkeys (L local, B bootstrap)"
+   |
+   v
+ Phase 2: Discover outbox relays (from LOCAL relay first, bootstrap fallback)
+   |  - Query local relay for kind=10002 per followed pubkey
+   |  - If found locally: use it (fast)
+   |  - If not found: fall back to bootstrap relays, cache result to local
+   |  - Parse "r" tags => per-pubkey relay list
+   |  - Dynamically add discovered relays to upstream_pool
+   |  - Log: "relay_discovery: found N relays (L local, B bootstrap)"
+   |  - Log: "upstream_pool: now connected to N relays" + list them
+   |
+   v
+ Phase 3: Open live subscriptions on upstream_pool
+   |  - (same as first-time)
+   |
+   v
+ Phase 4: Resume backfill from saved state
+   |  - Resume at state.current_window_index, state.backfill_cursor
+   |  - No re-pull of already-backfilled windows
+   |  - Continue progressive window expansion from where it left off
+   |
+   v
+ Steady-state (same as first-time)
+   |
+   v
+ SHUTDOWN -> save state -> clean exit
+```
+
+### Relay logging
+
+The daemon logs all relay activity so you can see exactly which relays are
+being used:
+
+- `upstream: added wss://relay.damus.io` -- each relay added to the pool
+- `relay_discovery: found 47 relays from 195 pubkeys` -- outbox discovery summary
+- `upstream_pool: 50 relays connected:` -- full relay list at startup
+- `relay_discovery: pubkey X -> wss://relay.example.com (local)` -- per-pubkey
+  relay source (local cache vs bootstrap)
+- `backfill: pubkey[3/195] abc123 -> wss://relay.example.com (12 events)` --
+  which relay served each backfill query
+
+## Dependencies
+
+- [nostr_core_lib](../nostr_core_lib) - built with NIPs 1, 4, 6, 19, 42, 44
+- libwebsockets, openssl, libsecp256k1, libcurl, zlib (all statically linked
+  in the Docker build)
+
+## Testing
+
+Start a local c-relay, then run the daemon:
+
+```bash
+# Start local relay (from c-relay project)
+cd ../c-relay/build && ./c_relay_static_x86_64 -p 8888 &
+
+# Run the caching daemon (uses ./caching_relay_config.jsonc by default)
+./caching_relay -d 3
+
+# Verify events are cached (from another terminal)
+nak req -k 1 -l 10 ws://127.0.0.1:8888
+```

caching/VERSION

@@ -0,0 +1 @@
+0.0.2

caching/build_static.sh

@@ -0,0 +1,147 @@
+#!/bin/bash
+
+# Build fully static MUSL binary for caching_relay using Alpine Docker.
+# Produces a truly portable binary with zero runtime dependencies.
+# Adapted from c-relay's build_static.sh.
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+DOCKERFILE="$SCRIPT_DIR/Dockerfile.alpine-musl"
+
+# Parse command line arguments
+DEBUG_BUILD=false
+TARGET_ARCH=""
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --debug)
+            DEBUG_BUILD=true
+            shift
+            ;;
+        --arch)
+            if [[ -z "$2" ]]; then
+                echo "ERROR: --arch requires a value"
+                echo "Usage: $0 [--debug] [--arch <arm64|x86_64>]"
+                exit 1
+            fi
+            case "$2" in
+                arm64|x86_64)
+                    TARGET_ARCH="$2"
+                    ;;
+                *)
+                    echo "ERROR: Unsupported architecture '$2'"
+                    echo "Supported values: arm64, x86_64"
+                    exit 1
+                    ;;
+            esac
+            shift 2
+            ;;
+        *)
+            echo "ERROR: Unknown argument '$1'"
+            echo "Usage: $0 [--debug] [--arch <arm64|x86_64>]"
+            exit 1
+            ;;
+    esac
+done
+
+if [ "$DEBUG_BUILD" = true ]; then
+    echo "=========================================="
+    echo "caching_relay MUSL Static Binary Builder (DEBUG MODE)"
+    echo "=========================================="
+else
+    echo "=========================================="
+    echo "caching_relay MUSL Static Binary Builder (PRODUCTION MODE)"
+    echo "=========================================="
+fi
+echo "Project directory: $SCRIPT_DIR"
+echo ""
+
+if ! command -v docker &> /dev/null; then
+    echo "ERROR: Docker is not installed or not in PATH"
+    exit 1
+fi
+if ! docker info &> /dev/null; then
+    echo "ERROR: Docker daemon is not running or user not in docker group"
+    exit 1
+fi
+echo "Docker is available and running"
+echo ""
+
+# Detect host architecture
+ARCH=$(uname -m)
+case "$ARCH" in
+    x86_64)  ARCH="x86_64";;
+    aarch64) ARCH="arm64";;
+    arm64)   ARCH="arm64";;
+esac
+if [[ -n "$TARGET_ARCH" ]]; then
+    ARCH="$TARGET_ARCH"
+    echo "Using target architecture: $ARCH"
+else
+    echo "Detected host architecture: $ARCH"
+fi
+echo ""
+
+# nostr_core_lib is inside the c-relay-pg project root (one dir up from caching/).
+# Copy it into the Docker build context (excluding .git and build artifacts).
+NOSTR_CORE_DIR="$SCRIPT_DIR/../nostr_core_lib"
+if [ ! -d "$NOSTR_CORE_DIR" ]; then
+    echo "ERROR: nostr_core_lib not found at $NOSTR_CORE_DIR"
+    exit 1
+fi
+
+NEEDS_COPY=1
+if [ -d "$SCRIPT_DIR/nostr_core_lib" ] && [ ! -L "$SCRIPT_DIR/nostr_core_lib" ]; then
+    # Already a real directory (e.g. from a previous run); assume it's good.
+    NEEDS_COPY=0
+fi
+if [ "$NEEDS_COPY" = "1" ]; then
+    echo "Copying nostr_core_lib into build context..."
+    rm -rf "$SCRIPT_DIR/nostr_core_lib"
+    mkdir -p "$SCRIPT_DIR/nostr_core_lib"
+    rsync -a --exclude='.git' --exclude='*.a' --exclude='*.o' \
+          --exclude='.venv*' --exclude='backups' --exclude='verify_*' \
+          --exclude='rewrite_mirror' --exclude='websocket_debug' \
+          "$NOSTR_CORE_DIR/" "$SCRIPT_DIR/nostr_core_lib/"
+    COPIED_NOSTR_CORE=1
+fi
+
+# Build args
+BUILD_ARGS="--build-arg DEBUG_BUILD=$DEBUG_BUILD"
+if [ "$ARCH" = "arm64" ] && [ "$(uname -m)" != "aarch64" ] && [ "$(uname -m)" != "arm64" ]; then
+    BUILD_ARGS="$BUILD_ARGS --platform linux/arm64"
+fi
+
+IMAGE_TAG="caching_relay_builder:latest"
+
+echo "Building Docker image..."
+docker build $BUILD_ARGS \
+    -f "$DOCKERFILE" \
+    -t "$IMAGE_TAG" \
+    "$SCRIPT_DIR" 2>&1
+
+BUILD_RC=$?
+
+# Clean up the copied nostr_core_lib to keep the project dir tidy.
+if [ "${COPIED_NOSTR_CORE:-0}" = "1" ]; then
+    echo "Cleaning up copied nostr_core_lib from build context..."
+    rm -rf "$SCRIPT_DIR/nostr_core_lib"
+fi
+
+if [ $BUILD_RC -ne 0 ]; then
+    exit $BUILD_RC
+fi
+
+echo ""
+echo "Extracting binary from image..."
+# The output stage is FROM scratch with no CMD, so pass an empty command.
+CONTAINER_ID=$(docker create "$IMAGE_TAG" "")
+docker cp "$CONTAINER_ID:/caching_relay_static" "$SCRIPT_DIR/caching_relay"
+docker rm "$CONTAINER_ID" >/dev/null
+chmod +x "$SCRIPT_DIR/caching_relay"
+
+echo ""
+echo "=== Build complete ==="
+ls -lh "$SCRIPT_DIR/caching_relay"
+file "$SCRIPT_DIR/caching_relay"

caching/src/backfill.c

@@ -0,0 +1,456 @@
+/*
+ * caching_relay - relay-by-relay per-author until-cursor drain backfill.
+ *
+ * Each (author, relay) pair has its own persistent until_cursor stored in
+ * the caching_backfill_relay_progress table. Each backfill tick picks the
+ * next author that still has at least one incomplete relay (round-robin),
+ * then queries each incomplete relay one at a time with
+ *   since=0 & until=cursor & limit=page_size
+ * publishes the page, and advances that relay's cursor to
+ * oldest_event_created_at - 1. A relay is marked complete when a page
+ * returns fewer than page_size events (the relay is drained for this
+ * author). An author is marked complete in caching_followed_pubkeys when
+ * all their relay progress rows are complete.
+ */
+#define _GNU_SOURCE
+#include "backfill.h"
+#include "follow_graph.h"
+#include "pg_inbox.h"
+#include "debug.h"
+
+#include "../nostr_core_lib/cjson/cJSON.h"
+
+#include <string.h>
+#include <stdlib.h>
+#include <time.h>
+
+/* ------------------------------------------------------------------ */
+/* Global access for status reporting                                  */
+/* ------------------------------------------------------------------ */
+
+/* Singleton pointer set in cr_backfill_init, used by the accessor
+ * functions below so the main loop / status reporter can see what
+ * the backfill is currently working on. */
+static cr_backfill_t *g_bf = NULL;
+
+const char *cr_backfill_active_pubkey(void) {
+    return g_bf ? g_bf->active_pubkey : "";
+}
+const char *cr_backfill_active_relay(void) {
+    return g_bf ? g_bf->active_relay : "";
+}
+int cr_backfill_active_got_eose(void) {
+    return g_bf ? g_bf->active_relay_got_eose : 0;
+}
+
+/* ------------------------------------------------------------------ */
+/* EOSE callback for synchronous_query_relays_with_progress            */
+/* ------------------------------------------------------------------ */
+
+/* Context passed to the query callback. Records whether the relay sent
+ * EOSE (we got everything) or timed out (partial result). */
+typedef struct {
+    int  got_eose;     /* 1 if EOSE received, 0 if timed out/errored */
+    int  events_count; /* events reported by callback */
+    char last_status[256]; /* last status string from callback (may include message) */
+} backfill_query_ctx_t;
+
+static void backfill_query_callback(const char *relay_url, const char *status,
+                                     const char *event_id, int events_received,
+                                     int total_relays, int completed_relays,
+                                     void *user_data) {
+    (void)relay_url; (void)total_relays; (void)completed_relays;
+    backfill_query_ctx_t *ctx = (backfill_query_ctx_t *)user_data;
+    if (!ctx || !status) return;
+
+    /* Ignore the synthetic "all_complete" status from core_relays.c — it
+     * is sent AFTER the real EOSE/timeout and would overwrite the real
+     * status with a misleading "all_complete" string, and clobber
+     * events_count with total_unique_events. The real per-relay status
+     * (eose/timeout/error) is what we need for completion decisions. */
+    if (strcmp(status, "all_complete") == 0) {
+        return;
+    }
+
+    /* For NOTICE/CLOSED/error, event_id carries the descriptive message
+     * content (relay's own text for NOTICE/CLOSED, or our transport-level
+     * diagnosis for error). Include it in the status for display.
+     * Priority: relay's own response (NOTICE/CLOSED) > our error > bare
+     * status string. */
+    if ((strcmp(status, "NOTICE") == 0 || strcmp(status, "CLOSED") == 0) &&
+        event_id && event_id[0] != '\0') {
+        snprintf(ctx->last_status, sizeof(ctx->last_status), "%s: %s", status, event_id);
+    } else if (strcmp(status, "error") == 0) {
+        if (event_id && event_id[0] != '\0') {
+            snprintf(ctx->last_status, sizeof(ctx->last_status), "error: %s", event_id);
+        } else {
+            snprintf(ctx->last_status, sizeof(ctx->last_status), "error");
+        }
+    } else {
+        snprintf(ctx->last_status, sizeof(ctx->last_status), "%s", status);
+    }
+
+    if (strcmp(status, "eose") == 0) {
+        ctx->got_eose = 1;
+    } else if (strcmp(status, "timeout") == 0) {
+        ctx->got_eose = 0;
+    } else if (strcmp(status, "error") == 0) {
+        ctx->got_eose = 0;
+    }
+    /* NOTICE/CLOSED don't change got_eose — the relay might still send
+     * events or EOSE after a NOTICE. */
+    ctx->events_count = events_received;
+}
+
+/* ------------------------------------------------------------------ */
+/* Helpers                                                             */
+/* ------------------------------------------------------------------ */
+
+/* Returns 1 if the PostgreSQL inbox is initialized (PG mode active).
+ * Probes the config table; a non-NULL result means the connection is up. */
+static int pg_mode_active(void) {
+    char *v = pg_inbox_get_config_value("caching_root_npubs");
+    if (v) { free(v); return 1; }
+    char *v2 = pg_inbox_get_config_value("caching_kinds");
+    if (v2) { free(v2); return 1; }
+    return 0;
+}
+
+/* Find the oldest (minimum) created_at among an array of event JSON objects.
+ * Returns 1 and sets *out_oldest, or 0 if no events / no valid created_at. */
+static int find_oldest_created_at(cJSON **events, int count, long *out_oldest) {
+    long oldest = 0;
+    int found = 0;
+    for (int i = 0; i < count; i++) {
+        cJSON *ca = cJSON_GetObjectItem(events[i], "created_at");
+        if (!ca || !cJSON_IsNumber(ca)) continue;
+        long ts = (long)ca->valuedouble;
+        if (!found || ts < oldest) {
+            oldest = ts;
+            found = 1;
+        }
+    }
+    if (found && out_oldest) *out_oldest = oldest;
+    return found;
+}
+
+/* Find the newest (maximum) created_at among an array of event JSON objects.
+ * Returns 1 and sets *out_newest, or 0 if no events / no valid created_at. */
+static int find_newest_created_at(cJSON **events, int count, long *out_newest) {
+    long newest = 0;
+    int found = 0;
+    for (int i = 0; i < count; i++) {
+        cJSON *ca = cJSON_GetObjectItem(events[i], "created_at");
+        if (!ca || !cJSON_IsNumber(ca)) continue;
+        long ts = (long)ca->valuedouble;
+        if (!found || ts > newest) {
+            newest = ts;
+            found = 1;
+        }
+    }
+    if (found && out_newest) *out_newest = newest;
+    return found;
+}
+
+/* Build the kinds array for a given pubkey (admin vs regular).
+ * Returns NULL if no kinds filter should be applied (admin_all_kinds). */
+static cJSON *build_kinds(cr_config_t *cfg, const char *pk) {
+    int is_admin = cr_follow_is_root(cfg, pk);
+    if (is_admin && cfg->admin_all_kinds) {
+        return NULL;
+    }
+    cJSON *kinds = cJSON_CreateArray();
+    if (is_admin && cfg->admin_kind_count > 0) {
+        for (int i = 0; i < cfg->admin_kind_count; i++)
+            cJSON_AddItemToArray(kinds, cJSON_CreateNumber(cfg->admin_kinds[i]));
+    } else {
+        for (int i = 0; i < cfg->kind_count; i++)
+            cJSON_AddItemToArray(kinds, cJSON_CreateNumber(cfg->kinds[i]));
+    }
+    return kinds;
+}
+
+/* Resolve the relay URL list to query for a given pubkey. Sets *out_urls and
+ * *out_n. Caller frees *out_urls (but not the strings, which alias internal
+ * storage). Returns 0 on success, -1 if no relays available. */
+static int resolve_relays(nostr_relay_pool_t *upstream,
+                          const cr_relay_map_t *relay_map,
+                          const char *pk,
+                          const char ***out_urls,
+                          int *out_n) {
+    *out_urls = NULL;
+    *out_n = 0;
+
+    /* Collect outbox relays for this author (from kind-10002). */
+    int outbox_count = 0;
+    const cr_outbox_entry_t *oe = NULL;
+    if (relay_map) {
+        oe = cr_relay_map_get_outbox(relay_map, pk);
+        if (oe) outbox_count = oe->relay_count;
+    }
+
+    /* Also collect all upstream (bootstrap) relays. We query BOTH the
+     * author's outbox relays AND the bootstrap relays to maximize coverage.
+     * Different relays may have different subsets of the author's events. */
+    char **listed = NULL;
+    nostr_pool_relay_status_t *statuses = NULL;
+    int upstream_count = nostr_relay_pool_list_relays(upstream, &listed, &statuses);
+
+    /* Merge outbox + upstream, deduplicating by URL. */
+    int max_total = outbox_count + upstream_count;
+    if (max_total <= 0) {
+        free(listed);
+        free(statuses);
+        return 0;
+    }
+
+    const char **urls = malloc(max_total * sizeof(char *));
+    if (!urls) { free(listed); free(statuses); return -1; }
+
+    int n = 0;
+
+    /* Add outbox relays first. */
+    if (oe) {
+        for (int j = 0; j < oe->relay_count && n < max_total; j++) {
+            urls[n++] = oe->relays[j];
+        }
+    }
+
+    /* Add upstream relays, skipping duplicates. */
+    for (int j = 0; j < upstream_count && n < max_total; j++) {
+        int dup = 0;
+        for (int k = 0; k < n; k++) {
+            if (strcmp(urls[k], listed[j]) == 0) { dup = 1; break; }
+        }
+        if (!dup) {
+            urls[n++] = listed[j];
+        }
+    }
+
+    free(listed);
+    free(statuses);
+
+    *out_urls = urls;
+    *out_n = n;
+    return 0;
+}
+
+/* ------------------------------------------------------------------ */
+/* Init                                                                */
+/* ------------------------------------------------------------------ */
+
+void cr_backfill_init(cr_backfill_t *bf, cr_config_t *cfg) {
+    (void)cfg;
+    memset(bf, 0, sizeof(*bf));
+    g_bf = bf;  /* Set singleton for status accessors */
+
+    /* In PG mode, check whether any incomplete authors remain in the DB.
+     * If so, backfill is in progress; otherwise we're in steady state.
+     * Outside PG mode there is no per-author table, so we just start. */
+    if (pg_mode_active()) {
+        int complete = 0, total = 0;
+        if (pg_inbox_count_backfill_progress(&complete, &total) == 0) {
+            bf->in_progress = (total > 0 && complete < total) ? 1 : 0;
+            DEBUG_INFO("backfill: init complete=%d/%d -> in_progress=%d",
+                        complete, total, bf->in_progress);
+            return;
+        }
+        /* Count query failed - assume in progress so we keep trying. */
+        bf->in_progress = 1;
+        DEBUG_WARN("backfill: init could not read progress counts, "
+                    "defaulting to in_progress=1");
+        return;
+    }
+
+    /* Legacy (non-PG) mode: no per-author table; just start. */
+    bf->in_progress = 1;
+    DEBUG_INFO("backfill: init (legacy mode) in_progress=1");
+}
+
+/* ------------------------------------------------------------------ */
+/* Tick                                                                */
+/* ------------------------------------------------------------------ */
+
+int cr_backfill_tick(cr_backfill_t *bf, cr_config_t *cfg,
+                     nostr_relay_pool_t *upstream,
+                     cr_pubkey_set_t *followed,
+                     cr_sink_t *sink, const cr_relay_map_t *relay_map) {
+    (void)followed;     /* followed set is tracked in the DB now */
+    (void)relay_map;    /* relays are tracked per-author in the DB */
+
+    if (!cfg->backfill.enabled) return -2;
+    if (!bf->in_progress) return -2;
+
+    /* Throttle: one query per tick_interval. */
+    time_t now = time(NULL);
+    if (bf->last_tick && (now - bf->last_tick) < cfg->backfill.tick_interval_seconds)
+        return 0;
+
+    /* Pick the next author that has at least one incomplete relay progress
+     * row (round-robin). */
+    char pk[CR_HEX_LEN];
+    if (pg_inbox_pick_next_author_with_incomplete_relays(pk, sizeof(pk),
+                                            &bf->author_round_cursor) != 0) {
+        /* No incomplete authors - steady state. */
+        bf->in_progress = 0;
+        DEBUG_INFO("backfill: no authors with incomplete relays, steady-state");
+        return -2;
+    }
+
+    int page_size = cfg->backfill.events_per_tick;
+    if (page_size < 1) page_size = 500;
+
+    bf->last_tick = now;
+
+    /* Get the incomplete relays for this author. */
+    cJSON *relays = pg_inbox_get_incomplete_relays(pk);
+    if (!relays) {
+        DEBUG_WARN("backfill: no incomplete relays returned for %s", pk);
+        /* Author has no relay rows - mark complete so we don't loop. */
+        pg_inbox_check_and_mark_author_complete(pk);
+        return 1;
+    }
+
+    int relay_count = cJSON_GetArraySize(relays);
+    DEBUG_TRACE("backfill: author %s has %d incomplete relay(s)", pk, relay_count);
+
+    cr_sink_set_source_class(sink, CR_SINK_CLASS_BACKFILL);
+
+    /* Query each incomplete relay one at a time. */
+    for (int r = 0; r < relay_count; r++) {
+        cJSON *entry = cJSON_GetArrayItem(relays, r);
+        if (!entry) continue;
+        cJSON *url_node = cJSON_GetObjectItem(entry, "relay_url");
+        cJSON *cur_node = cJSON_GetObjectItem(entry, "until_cursor");
+        if (!url_node || !cJSON_IsString(url_node)) continue;
+        const char *relay_url = cJSON_GetStringValue(url_node);
+        long until_cursor = (cur_node && cJSON_IsNumber(cur_node))
+                            ? (long)cur_node->valuedouble : 0;
+        if (until_cursor == 0) until_cursor = (long)now;
+
+        /* Build the filter for this single relay. */
+        cJSON *filter = cJSON_CreateObject();
+        cJSON *authors = cJSON_CreateArray();
+        cJSON_AddItemToArray(authors, cJSON_CreateString(pk));
+        cJSON_AddItemToObject(filter, "authors", authors);
+        cJSON *kinds = build_kinds(cfg, pk);
+        if (kinds) cJSON_AddItemToObject(filter, "kinds", kinds);
+        cJSON_AddItemToObject(filter, "since", cJSON_CreateNumber(0.0));
+        cJSON_AddItemToObject(filter, "until", cJSON_CreateNumber((double)until_cursor));
+        cJSON_AddItemToObject(filter, "limit", cJSON_CreateNumber((double)page_size));
+
+        DEBUG_TRACE("backfill: %s @ %s (until=%ld, limit=%d)",
+                    pk, relay_url, until_cursor, page_size);
+
+        /* Record the active target for UI status display (both
+         * in-memory for local accessors and in PG for the relay). */
+        strncpy(bf->active_pubkey, pk, sizeof(bf->active_pubkey) - 1);
+        bf->active_pubkey[sizeof(bf->active_pubkey) - 1] = '\0';
+        strncpy(bf->active_relay, relay_url, sizeof(bf->active_relay) - 1);
+        bf->active_relay[sizeof(bf->active_relay) - 1] = '\0';
+        bf->active_relay_got_eose = 0;
+        pg_inbox_set_active_target(pk, relay_url);
+
+        /* Query this single relay using synchronous_query_relays_with_progress
+         * which gives us an EOSE/timeout callback — the relay's own signal
+         * of whether it sent everything or we timed out. */
+        backfill_query_ctx_t qctx = {0, 0};
+        const char *one_url = relay_url;
+        int ev_count = 0;
+        cJSON **events = synchronous_query_relays_with_progress(
+            &one_url, 1, filter, RELAY_QUERY_ALL_RESULTS,
+            &ev_count, 30,  /* timeout in seconds */
+            backfill_query_callback, &qctx,
+            0, NULL  /* nip42 disabled, no private key */);
+        cJSON_Delete(filter);
+
+        bf->active_relay_got_eose = qctx.got_eose;
+
+        if (!events || ev_count == 0) {
+            /* No events from this relay - it is drained for this author.
+             * (ev_count == 0 with EOSE means truly empty; without EOSE it
+             * means a connection failure — keep incomplete to retry.
+             * The pg_inbox_update_relay_progress SQL will auto-mark
+             * complete once consecutive_errors reaches 3.) */
+            int mark_complete = qctx.got_eose ? 1 : 0;
+            pg_inbox_update_relay_progress(pk, relay_url, until_cursor,
+                                            mark_complete, 0, qctx.last_status);
+            free(events);
+            if (!qctx.got_eose) {
+                /* Error or timeout with no events — surface the
+                 * descriptive status at WARN so operators can see why. */
+                DEBUG_WARN("backfill: %s @ %s failed: %s (will auto-complete after 3 consecutive errors)",
+                           pk, relay_url, qctx.last_status);
+            } else {
+                DEBUG_LOG("backfill: %s @ %s complete (no events, eose)",
+                          pk, relay_url);
+            }
+            continue;
+        }
+
+        /* Find oldest and newest timestamps, then publish every event. */
+        long oldest_ts = 0;
+        long newest_ts = 0;
+        find_oldest_created_at(events, ev_count, &oldest_ts);
+        find_newest_created_at(events, ev_count, &newest_ts);
+
+        for (int k = 0; k < ev_count; k++) {
+            cr_sink_publish(sink, events[k]);
+            cJSON_Delete(events[k]);
+        }
+        free(events);
+        bf->events_total += ev_count;
+
+        /* Update last_event_at for forward catch-up gap tracking. */
+        if (newest_ts > 0) {
+            pg_inbox_update_last_event_at(pk, newest_ts);
+        }
+
+        DEBUG_LOG("backfill: %s @ %s -> %d events (until=%ld, oldest=%ld, eose=%d)",
+                  pk, relay_url, ev_count, until_cursor, oldest_ts, qctx.got_eose);
+
+        /* Completion decision based on EOSE status:
+         * - ev_count >= page_size: saturated, advance cursor, keep incomplete
+         * - ev_count < page_size AND got EOSE: relay is truly drained
+         * - ev_count < page_size AND no EOSE (timeout): partial result,
+         *   advance cursor but keep incomplete to retry next tick
+         * - Guard: if cursor didn't advance (oldest_ts >= until_cursor),
+         *   mark complete to avoid infinite loop on identical timestamps. */
+        long next_cursor = (oldest_ts > 0) ? oldest_ts - 1 : 0;
+        int cursor_advanced = (oldest_ts > 0 && oldest_ts < until_cursor);
+
+        if (ev_count >= page_size) {
+            pg_inbox_update_relay_progress(pk, relay_url, next_cursor, 0, ev_count, qctx.last_status);
+        } else if (qctx.got_eose) {
+            /* Relay sent EOSE with < page_size events — truly drained. */
+            pg_inbox_update_relay_progress(pk, relay_url, next_cursor, 1, ev_count, qctx.last_status);
+        } else {
+            /* Timed out before EOSE — partial result. Keep incomplete
+             * to retry, unless the cursor didn't advance (stall guard).
+             * Timeouts DO count toward the consecutive_errors limit
+             * (a relay that consistently times out is effectively dead
+             * for backfill purposes), so the SQL will auto-mark
+             * complete after 3 consecutive timeouts/errors. */
+            int mark_complete = cursor_advanced ? 0 : 1;
+            pg_inbox_update_relay_progress(pk, relay_url, next_cursor,
+                                            mark_complete, ev_count, qctx.last_status);
+            DEBUG_WARN("backfill: %s @ %s partial: %s (%d events, will auto-complete after 3 consecutive timeouts/errors)",
+                       pk, relay_url, qctx.last_status, ev_count);
+        }
+    }
+
+    /* Clear active target — done with this author. */
+    bf->active_relay[0] = '\0';
+    pg_inbox_set_active_target(pk, "");
+
+    cJSON_Delete(relays);
+
+    /* After querying all incomplete relays for this author, check whether
+     * the author is now fully complete. */
+    int crc = pg_inbox_check_and_mark_author_complete(pk);
+    if (crc == 1) {
+        DEBUG_LOG("backfill: author %s fully complete (all relays drained)", pk);
+    }
+
+    return 1;
+}

caching/src/backfill.h

@@ -0,0 +1,58 @@
+/*
+ * caching_relay - per-author until-cursor drain backfill.
+ *
+ * Each followed author has a single persistent cursor (starting at `now`)
+ * stored in the caching_followed_pubkeys table. Each backfill tick picks
+ * the next incomplete author (round-robin), queries
+ *   since=0 & until=cursor & limit=page_size
+ * publishes the page, and sets cursor = oldest_event_created_at - 1.
+ * Repeat until a page returns fewer than page_size events (beginning of
+ * the author's history reached), then mark the author complete.
+ */
+#ifndef CACHING_RELAY_BACKFILL_H
+#define CACHING_RELAY_BACKFILL_H
+
+#include "config.h"
+#include "state.h"
+#include "relay_sink.h"
+#include "relay_discovery.h"
+#include "../nostr_core_lib/nostr_core/nostr_core.h"
+
+typedef struct {
+    int      in_progress;        /* 1 if any incomplete authors remain */
+    long     events_total;       /* events pulled across all ticks (diagnostic) */
+    time_t   last_tick;          /* last time an author was queried (throttle) */
+    int      author_round_cursor;/* round-robin cursor for author selection */
+    /* Current backfill target (for UI status display). */
+    char     active_pubkey[65];  /* pubkey currently being backfilled (or "") */
+    char     active_relay[256];  /* relay URL currently being queried (or "") */
+    int      active_relay_got_eose; /* 1 if last query got EOSE, 0 if timed out */
+} cr_backfill_t;
+
+/* Global access to the current backfill target for status reporting.
+ * Returns pointers to static storage in the singleton cr_backfill_t.
+ * Safe to call from the main loop; not thread-safe but backfill is
+ * single-threaded. */
+const char *cr_backfill_active_pubkey(void);
+const char *cr_backfill_active_relay(void);
+int cr_backfill_active_got_eose(void);
+
+/* Initialize backfill state. Checks the caching_followed_pubkeys table for
+ * any incomplete authors; sets in_progress accordingly. */
+void cr_backfill_init(cr_backfill_t *bf, cr_config_t *cfg);
+
+/* Perform one backfill tick. Picks the next incomplete author from the DB
+ * (round-robin), queries one page of history, publishes it to the sink, and
+ * updates the per-author cursor in the DB.
+ *
+ * Returns:
+ *   1  if a tick was performed (an author was queried)
+ *   0  if throttled (tick_interval not elapsed) - caller should pump pools
+ *  -2  if backfill is complete (no incomplete authors) - caller goes steady-state
+ */
+int cr_backfill_tick(cr_backfill_t *bf, cr_config_t *cfg,
+                     nostr_relay_pool_t *upstream,
+                     cr_pubkey_set_t *followed,
+                     cr_sink_t *sink, const cr_relay_map_t *relay_map);
+
+#endif /* CACHING_RELAY_BACKFILL_H */

caching/src/config.c

@@ -0,0 +1,290 @@
+/*
+ * caching_relay - config parsing + persistent state (in the .jsonc file itself)
+ */
+#define _GNU_SOURCE
+#include "config.h"
+#include "jsonc_strip.h"
+#include "debug.h"
+
+#include "../nostr_core_lib/cjson/cJSON.h"
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <errno.h>
+#include <unistd.h>
+#include <fcntl.h>
+
+static int read_file(const char *path, char **out, size_t *out_len) {
+    FILE *f = fopen(path, "rb");
+    if (!f) {
+        DEBUG_ERROR("cannot open config '%s': %s", path, strerror(errno));
+        return -1;
+    }
+    if (fseek(f, 0, SEEK_END) != 0) { fclose(f); return -1; }
+    long sz = ftell(f);
+    if (sz < 0) { fclose(f); return -1; }
+    rewind(f);
+    char *buf = malloc(sz + 1);
+    if (!buf) { fclose(f); return -1; }
+    size_t n = fread(buf, 1, sz, f);
+    fclose(f);
+    buf[n] = '\0';
+    *out = buf;
+    if (out_len) *out_len = n;
+    return 0;
+}
+
+static void copy_string_array(cJSON *arr, char *dst, int max, int *count_out,
+                              int elem_len) {
+    int count = 0;
+    if (arr && cJSON_IsArray(arr)) {
+        cJSON *item;
+        cJSON_ArrayForEach(item, arr) {
+            if (count >= max) break;
+            if (!cJSON_IsString(item)) continue;
+            const char *s = cJSON_GetStringValue(item);
+            if (!s) continue;
+            strncpy(dst + count * elem_len, s, elem_len - 1);
+            dst[count * elem_len + (elem_len - 1)] = '\0';
+            count++;
+        }
+    }
+    *count_out = count;
+}
+
+static void copy_int_array(cJSON *arr, int *dst, int max, int *count_out) {
+    int count = 0;
+    if (arr && cJSON_IsArray(arr)) {
+        cJSON *item;
+        cJSON_ArrayForEach(item, arr) {
+            if (count >= max) break;
+            if (cJSON_IsNumber(item)) {
+                dst[count++] = (int)cJSON_GetNumberValue(item);
+            }
+        }
+    }
+    *count_out = count;
+}
+
+static void copy_long_array(cJSON *arr, long *dst, int max, int *count_out) {
+    int count = 0;
+    if (arr && cJSON_IsArray(arr)) {
+        cJSON *item;
+        cJSON_ArrayForEach(item, arr) {
+            if (count >= max) break;
+            if (cJSON_IsNumber(item)) {
+                dst[count++] = (long)cJSON_GetNumberValue(item);
+            }
+        }
+    }
+    *count_out = count;
+}
+
+int cr_config_load(cr_config_t *cfg, const char *path) {
+    memset(cfg, 0, sizeof(*cfg));
+    strncpy(cfg->path, path, sizeof(cfg->path) - 1);
+
+    char *raw = NULL;
+    size_t raw_len = 0;
+    if (read_file(path, &raw, &raw_len) != 0) return -1;
+
+    char *stripped = jsonc_strip_comments(raw, raw_len);
+    free(raw);
+    if (!stripped) {
+        DEBUG_ERROR("failed to strip comments from config");
+        return -1;
+    }
+
+    cJSON *root = cJSON_Parse(stripped);
+    free(stripped);
+    if (!root) {
+        DEBUG_ERROR("failed to parse config JSON");
+        return -1;
+    }
+
+    /* root_npubs */
+    copy_string_array(cJSON_GetObjectItem(root, "root_npubs"),
+                      (char *)cfg->root_npubs, CR_MAX_ROOT_NPUBS,
+                      &cfg->root_npub_count, CR_NPUB_LEN);
+
+    /* upstream_relays */
+    copy_string_array(cJSON_GetObjectItem(root, "upstream_relays"),
+                      (char *)cfg->upstream_relays, CR_MAX_UPSTREAM,
+                      &cfg->upstream_count, CR_URL_LEN);
+
+    /* local_relay */
+    cJSON *local = cJSON_GetObjectItem(root, "local_relay");
+    if (local && cJSON_IsString(local)) {
+        strncpy(cfg->local_relay, cJSON_GetStringValue(local), CR_URL_LEN - 1);
+    }
+
+    /* kinds */
+    copy_int_array(cJSON_GetObjectItem(root, "kinds"),
+                   cfg->kinds, CR_MAX_KINDS, &cfg->kind_count);
+
+    /* admin_kinds - kinds to follow specifically for root (admin) npubs.
+     * Supports [*] to mean "all kinds" (no kind filter for admin). */
+    cJSON *ak = cJSON_GetObjectItem(root, "admin_kinds");
+    if (ak && cJSON_IsArray(ak)) {
+        cJSON *item;
+        cJSON_ArrayForEach(item, ak) {
+            if (cJSON_IsString(item)) {
+                const char *s = cJSON_GetStringValue(item);
+                if (s && strcmp(s, "*") == 0) {
+                    cfg->admin_all_kinds = 1;
+                    break;
+                }
+            }
+        }
+        if (!cfg->admin_all_kinds) {
+            copy_int_array(ak, cfg->admin_kinds, CR_MAX_KINDS, &cfg->admin_kind_count);
+        }
+    }
+
+    /* backfill */
+    cJSON *bf = cJSON_GetObjectItem(root, "backfill");
+    if (bf) {
+        cfg->backfill.enabled = cJSON_IsTrue(cJSON_GetObjectItem(bf, "enabled"));
+        cJSON *ept = cJSON_GetObjectItem(bf, "events_per_tick");
+        if (ept) cfg->backfill.events_per_tick = (int)cJSON_GetNumberValue(ept);
+        cJSON *tis = cJSON_GetObjectItem(bf, "tick_interval_seconds");
+        if (tis) cfg->backfill.tick_interval_seconds = (int)cJSON_GetNumberValue(tis);
+    }
+
+    /* live */
+    cJSON *lv = cJSON_GetObjectItem(root, "live");
+    if (lv) {
+        cfg->live.enabled = cJSON_IsTrue(cJSON_GetObjectItem(lv, "enabled"));
+        cJSON *rsi = cJSON_GetObjectItem(lv, "resubscribe_interval_seconds");
+        if (rsi) cfg->live.resubscribe_interval_seconds = (int)cJSON_GetNumberValue(rsi);
+    }
+
+    /* follow_graph_refresh_seconds */
+    cJSON *fgr = cJSON_GetObjectItem(root, "follow_graph_refresh_seconds");
+    if (fgr) cfg->follow_graph_refresh_seconds = (int)cJSON_GetNumberValue(fgr);
+
+    /* state */
+    cJSON *st = cJSON_GetObjectItem(root, "state");
+    if (st) {
+        cJSON *bu = cJSON_GetObjectItem(st, "backfilled_until");
+        if (bu) cfg->state.backfilled_until = (long)cJSON_GetNumberValue(bu);
+    }
+
+    cJSON_Delete(root);
+
+    /* Defaults if missing. */
+    if (cfg->backfill.events_per_tick == 0) cfg->backfill.events_per_tick = 500;
+    if (cfg->backfill.tick_interval_seconds == 0) cfg->backfill.tick_interval_seconds = 5;
+    if (cfg->live.resubscribe_interval_seconds == 0) cfg->live.resubscribe_interval_seconds = 300;
+    if (cfg->follow_graph_refresh_seconds == 0) cfg->follow_graph_refresh_seconds = 600;
+
+    /* Validation. */
+    if (cfg->root_npub_count == 0) {
+        DEBUG_ERROR("config: at least one root_npub required");
+        return -1;
+    }
+    if (cfg->upstream_count == 0) {
+        DEBUG_ERROR("config: at least one upstream_relay required");
+        return -1;
+    }
+    if (cfg->local_relay[0] == '\0') {
+        DEBUG_ERROR("config: local_relay required");
+        return -1;
+    }
+    if (cfg->kind_count == 0) {
+        DEBUG_ERROR("config: at least one kind required");
+        return -1;
+    }
+
+    DEBUG_INFO("config loaded: %d root npubs, %d upstream relays, %d kinds",
+                cfg->root_npub_count, cfg->upstream_count, cfg->kind_count);
+    return 0;
+}
+
+/* Build a fresh cJSON tree from the in-memory config and write it out.
+ * We re-emit plain JSON (comments are not preserved on rewrite). */
+int cr_config_save_state(cr_config_t *cfg) {
+    cJSON *root = cJSON_CreateObject();
+
+    cJSON *npubs = cJSON_CreateArray();
+    for (int i = 0; i < cfg->root_npub_count; i++)
+        cJSON_AddItemToArray(npubs, cJSON_CreateString(cfg->root_npubs[i]));
+    cJSON_AddItemToObject(root, "root_npubs", npubs);
+
+    cJSON *upstream = cJSON_CreateArray();
+    for (int i = 0; i < cfg->upstream_count; i++)
+        cJSON_AddItemToArray(upstream, cJSON_CreateString(cfg->upstream_relays[i]));
+    cJSON_AddItemToObject(root, "upstream_relays", upstream);
+
+    cJSON_AddItemToObject(root, "local_relay", cJSON_CreateString(cfg->local_relay));
+
+    cJSON *kinds = cJSON_CreateArray();
+    for (int i = 0; i < cfg->kind_count; i++)
+        cJSON_AddItemToArray(kinds, cJSON_CreateNumber(cfg->kinds[i]));
+    cJSON_AddItemToObject(root, "kinds", kinds);
+
+    /* admin_kinds */
+    cJSON *akinds = cJSON_CreateArray();
+    if (cfg->admin_all_kinds) {
+        cJSON_AddItemToArray(akinds, cJSON_CreateString("*"));
+    } else {
+        for (int i = 0; i < cfg->admin_kind_count; i++)
+            cJSON_AddItemToArray(akinds, cJSON_CreateNumber(cfg->admin_kinds[i]));
+    }
+    cJSON_AddItemToObject(root, "admin_kinds", akinds);
+
+    cJSON *bf = cJSON_CreateObject();
+    cJSON_AddItemToObject(bf, "enabled", cJSON_CreateBool(cfg->backfill.enabled));
+    cJSON_AddItemToObject(bf, "events_per_tick", cJSON_CreateNumber(cfg->backfill.events_per_tick));
+    cJSON_AddItemToObject(bf, "tick_interval_seconds", cJSON_CreateNumber(cfg->backfill.tick_interval_seconds));
+    cJSON_AddItemToObject(root, "backfill", bf);
+
+    cJSON *lv = cJSON_CreateObject();
+    cJSON_AddItemToObject(lv, "enabled", cJSON_CreateBool(cfg->live.enabled));
+    cJSON_AddItemToObject(lv, "resubscribe_interval_seconds", cJSON_CreateNumber(cfg->live.resubscribe_interval_seconds));
+    cJSON_AddItemToObject(root, "live", lv);
+
+    cJSON_AddItemToObject(root, "follow_graph_refresh_seconds",
+                          cJSON_CreateNumber(cfg->follow_graph_refresh_seconds));
+
+    cJSON *st = cJSON_CreateObject();
+    cJSON_AddItemToObject(st, "backfilled_until", cJSON_CreateNumber(cfg->state.backfilled_until));
+    cJSON_AddItemToObject(root, "state", st);
+
+    char *json = cJSON_Print(root);
+    cJSON_Delete(root);
+    if (!json) {
+        DEBUG_ERROR("config save: failed to serialize");
+        return -1;
+    }
+
+    /* Atomic write: temp file + rename. */
+    char tmp[1100];
+    snprintf(tmp, sizeof(tmp), "%s.tmp", cfg->path);
+    int fd = open(tmp, O_WRONLY | O_CREAT | O_TRUNC, 0644);
+    if (fd < 0) {
+        DEBUG_ERROR("config save: cannot open tmp '%s': %s", tmp, strerror(errno));
+        free(json);
+        return -1;
+    }
+    size_t jlen = strlen(json);
+    ssize_t w = write(fd, json, jlen);
+    close(fd);
+    free(json);
+    if (w < 0 || (size_t)w != jlen) {
+        DEBUG_ERROR("config save: short write");
+        return -1;
+    }
+    if (rename(tmp, cfg->path) != 0) {
+        DEBUG_ERROR("config save: rename failed: %s", strerror(errno));
+        return -1;
+    }
+    DEBUG_LOG("config state saved: backfilled_until=%ld",
+                 cfg->state.backfilled_until);
+    return 0;
+}
+
+void cr_config_free(cr_config_t *cfg) {
+    (void)cfg;
+}

caching/src/config.h

@@ -0,0 +1,79 @@
+/*
+ * caching_relay - config parsing + persistent state (in the .jsonc file itself)
+ */
+#ifndef CACHING_RELAY_CONFIG_H
+#define CACHING_RELAY_CONFIG_H
+
+#include <stddef.h>
+#include <time.h>
+
+/* Maximums to keep things statically sized and simple. */
+#define CR_MAX_ROOT_NPUBS   16
+#define CR_MAX_UPSTREAM     32
+#define CR_MAX_KINDS        32
+#define CR_NPUB_LEN         64   /* npub1... bech32, generous */
+#define CR_URL_LEN          256
+#define CR_HEX_PUBKEY_LEN   65   /* 64 hex chars + NUL */
+
+typedef struct {
+    int    enabled;
+    int    events_per_tick;      /* per-query page size (default 500) */
+    int    tick_interval_seconds;
+} cr_backfill_config_t;
+
+typedef struct {
+    int enabled;
+    int resubscribe_interval_seconds;
+} cr_live_config_t;
+
+/* Persistent state. The per-author until-cursor drain model stores all
+ * backfill progress in the caching_followed_pubkeys table, so the only
+ * state kept here is the legacy-mode first-time flag (used to drive relay
+ * discovery caching behavior). */
+typedef struct {
+    long backfilled_until;       /* legacy: 0 = first-time startup */
+} cr_state_t;
+
+typedef struct {
+    char  root_npubs[CR_MAX_ROOT_NPUBS][CR_NPUB_LEN];
+    int   root_npub_count;
+    /* Decoded hex pubkeys for root npubs (filled by follow_graph). */
+    char  root_hex[CR_MAX_ROOT_NPUBS][CR_HEX_PUBKEY_LEN];
+    int   root_hex_ready;
+
+    char  upstream_relays[CR_MAX_UPSTREAM][CR_URL_LEN];
+    int   upstream_count;
+
+    char  local_relay[CR_URL_LEN];
+
+    int   kinds[CR_MAX_KINDS];
+    int   kind_count;
+
+    /* Kinds to follow specifically for the root (admin) npubs.
+     * If admin_all_kinds is 1, grab everything (no kind filter). */
+    int   admin_kinds[CR_MAX_KINDS];
+    int   admin_kind_count;
+    int   admin_all_kinds;
+
+    cr_backfill_config_t backfill;
+    cr_live_config_t     live;
+    int                  follow_graph_refresh_seconds;
+
+    cr_state_t state;
+
+    /* Path the config was loaded from (for state write-back). */
+    char path[1024];
+} cr_config_t;
+
+/* Load + validate config from a .jsonc file. Returns 0 on success, -1 on error.
+ * On success cfg->path is set and cfg->state is populated from the file. */
+int cr_config_load(cr_config_t *cfg, const char *path);
+
+/* Persist the state sub-object back into the config file (temp + rename).
+ * Preserves all other config fields. Returns 0 on success, -1 on error. */
+int cr_config_save_state(cr_config_t *cfg);
+
+/* Free any heap resources held by cfg (currently none, but kept for future). */
+void cr_config_free(cr_config_t *cfg);
+
+#endif /* CACHING_RELAY_CONFIG_H */

caching/src/debug.c

@@ -0,0 +1,71 @@
+#include "debug.h"
+#include <stdarg.h>
+#include <string.h>
+
+/**
+ * @file debug.c
+ * @brief Debug and logging system implementation
+ *
+ * Provides a configurable logging system with timestamp formatting,
+ * level-based filtering, and optional file:line information.
+ */
+
+// Global debug level (default: no debug output)
+debug_level_t g_debug_level = DEBUG_LEVEL_NONE;
+
+/**
+ * @brief Initialize the debug system with a specific level
+ * @param level Debug level (0-5, clamped to valid range)
+ */
+void debug_init(int level) {
+    if (level < 0) level = 0;
+    if (level > 5) level = 5;
+    g_debug_level = (debug_level_t)level;
+}
+
+/**
+ * @brief Core logging function
+ * @param level Debug level for this message
+ * @param file Source file name (__FILE__)
+ * @param line Source line number (__LINE__)
+ * @param format printf-style format string
+ * @param ... Variable arguments for format string
+ */
+void debug_log(debug_level_t level, const char* file, int line, const char* format, ...) {
+    // Get timestamp
+    time_t now = time(NULL);
+    struct tm* tm_info = localtime(&now);
+    char timestamp[32];
+    strftime(timestamp, sizeof(timestamp), "%Y-%m-%d %H:%M:%S", tm_info);
+
+    // Get level string
+    const char* level_str = "UNKNOWN";
+    switch (level) {
+        case DEBUG_LEVEL_ERROR: level_str = "ERROR"; break;
+        case DEBUG_LEVEL_WARN:  level_str = "WARN "; break;
+        case DEBUG_LEVEL_INFO:  level_str = "INFO "; break;
+        case DEBUG_LEVEL_DEBUG: level_str = "DEBUG"; break;
+        case DEBUG_LEVEL_TRACE: level_str = "TRACE"; break;
+        default: break;
+    }
+
+    // Print prefix with timestamp and level
+    printf("[%s] [%s] ", timestamp, level_str);
+
+    // Print source location when debug level is TRACE (5) or higher
+    if (file && g_debug_level >= DEBUG_LEVEL_TRACE) {
+        // Extract just the filename (not full path)
+        const char* filename = strrchr(file, '/');
+        filename = filename ? filename + 1 : file;
+        printf("[%s:%d] ", filename, line);
+    }
+
+    // Print message
+    va_list args;
+    va_start(args, format);
+    vprintf(format, args);
+    va_end(args);
+
+    printf("\n");
+    fflush(stdout);
+}

caching/src/debug.h

@@ -0,0 +1,65 @@
+#ifndef C_UTILS_DEBUG_H
+#define C_UTILS_DEBUG_H
+
+/**
+ * @file debug.h
+ * @brief Debug and logging system with configurable verbosity levels
+ *
+ * Provides a simple, efficient logging system with 5 levels:
+ * - ERROR: Critical errors
+ * - WARN: Warnings
+ * - INFO: Informational messages
+ * - DEBUG: Debug messages
+ * - TRACE: Detailed trace with file:line info
+ */
+
+#include <stdio.h>
+#include <time.h>
+
+// Debug levels
+typedef enum {
+    DEBUG_LEVEL_NONE = 0,  /**< No debug output */
+    DEBUG_LEVEL_ERROR = 1, /**< Critical errors only */
+    DEBUG_LEVEL_WARN = 2,  /**< Warnings and above */
+    DEBUG_LEVEL_INFO = 3,  /**< Informational messages and above */
+    DEBUG_LEVEL_DEBUG = 4, /**< Debug messages and above */
+    DEBUG_LEVEL_TRACE = 5  /**< Detailed trace with file:line info */
+} debug_level_t;
+
+// Global debug level (set at runtime via CLI)
+extern debug_level_t g_debug_level;
+
+/**
+ * @brief Initialize the debug system
+ * @param level Debug level (0-5, clamped to valid range)
+ */
+void debug_init(int level);
+
+/**
+ * @brief Core logging function
+ * @param level Debug level for this message
+ * @param file Source file name (__FILE__)
+ * @param line Source line number (__LINE__)
+ * @param format printf-style format string
+ * @param ... Variable arguments for format string
+ */
+void debug_log(debug_level_t level, const char* file, int line, const char* format, ...);
+
+// Convenience macros that check level before calling
+// Note: TRACE level (5) and above include file:line information for ALL messages
+#define DEBUG_ERROR(...) \
+    do { if (g_debug_level >= DEBUG_LEVEL_ERROR) debug_log(DEBUG_LEVEL_ERROR, __FILE__, __LINE__, __VA_ARGS__); } while(0)
+
+#define DEBUG_WARN(...) \
+    do { if (g_debug_level >= DEBUG_LEVEL_WARN) debug_log(DEBUG_LEVEL_WARN, __FILE__, __LINE__, __VA_ARGS__); } while(0)
+
+#define DEBUG_INFO(...) \
+    do { if (g_debug_level >= DEBUG_LEVEL_INFO) debug_log(DEBUG_LEVEL_INFO, __FILE__, __LINE__, __VA_ARGS__); } while(0)
+
+#define DEBUG_LOG(...) \
+    do { if (g_debug_level >= DEBUG_LEVEL_DEBUG) debug_log(DEBUG_LEVEL_DEBUG, __FILE__, __LINE__, __VA_ARGS__); } while(0)
+
+#define DEBUG_TRACE(...) \
+    do { if (g_debug_level >= DEBUG_LEVEL_TRACE) debug_log(DEBUG_LEVEL_TRACE, __FILE__, __LINE__, __VA_ARGS__); } while(0)
+
+#endif /* C_UTILS_DEBUG_H */

caching/src/follow_graph.c

@@ -0,0 +1,129 @@
+/*
+ * caching_relay - follow graph resolution
+ */
+#define _GNU_SOURCE
+#include "follow_graph.h"
+#include "debug.h"
+
+#include <string.h>
+#include <stdlib.h>
+#include <ctype.h>
+
+int cr_follow_is_root(const cr_config_t *cfg, const char *hex) {
+    if (!cfg->root_hex_ready) return 0;
+    for (int i = 0; i < cfg->root_npub_count; i++) {
+        if (strcmp(cfg->root_hex[i], hex) == 0) return 1;
+    }
+    return 0;
+}
+
+/* Check if a string is a 64-character hex pubkey (no npub prefix). */
+static int is_hex_pubkey(const char *s) {
+    if (!s || strlen(s) != 64) return 0;
+    for (int i = 0; i < 64; i++) {
+        if (!isxdigit((unsigned char)s[i])) return 0;
+    }
+    return 1;
+}
+
+int cr_follow_decode_roots(cr_config_t *cfg) {
+    for (int i = 0; i < cfg->root_npub_count; i++) {
+        const char *input = cfg->root_npubs[i];
+        if (is_hex_pubkey(input)) {
+            /* Already a 64-char hex pubkey — copy directly. */
+            strncpy(cfg->root_hex[i], input, 64);
+            cfg->root_hex[i][64] = '\0';
+        } else {
+            /* Assume npub (bech32) format — decode to hex. */
+            unsigned char pubkey[32];
+            if (nostr_decode_npub(input, pubkey) != NOSTR_SUCCESS) {
+                DEBUG_ERROR("follow: failed to decode root pubkey '%s' "
+                            "(not a valid npub or 64-char hex)", input);
+                return -1;
+            }
+            nostr_bytes_to_hex(pubkey, 32, cfg->root_hex[i]);
+        }
+    }
+    cfg->root_hex_ready = 1;
+    DEBUG_INFO("follow: decoded %d root pubkeys", cfg->root_npub_count);
+    return 0;
+}
+
+/* Parse "p" tags from a kind-3 event and add pubkeys to the set. */
+static int parse_p_tags(cJSON *event, cr_pubkey_set_t *followed) {
+    cJSON *tags = cJSON_GetObjectItem(event, "tags");
+    if (!tags || !cJSON_IsArray(tags)) return 0;
+    int added = 0;
+    cJSON *tag;
+    cJSON_ArrayForEach(tag, tags) {
+        if (!cJSON_IsArray(tag)) continue;
+        cJSON *name = cJSON_GetArrayItem(tag, 0);
+        if (!name || !cJSON_IsString(name)) continue;
+        if (strcmp(cJSON_GetStringValue(name), "p") != 0) continue;
+        cJSON *pk = cJSON_GetArrayItem(tag, 1);
+        if (!pk || !cJSON_IsString(pk)) continue;
+        const char *hex = cJSON_GetStringValue(pk);
+        if (strlen(hex) != 64) continue;
+        if (cr_pubkey_set_add(followed, hex) == 1) added++;
+    }
+    return added;
+}
+
+int cr_follow_resolve(cr_config_t *cfg, nostr_relay_pool_t *upstream,
+                      cr_pubkey_set_t *followed) {
+    if (!cfg->root_hex_ready) {
+        if (cr_follow_decode_roots(cfg) != 0) return -1;
+    }
+
+    /* Seed the followed set with the root pubkeys themselves. */
+    for (int i = 0; i < cfg->root_npub_count; i++) {
+        cr_pubkey_set_add(followed, cfg->root_hex[i]);
+    }
+
+    int total_follows = 0;
+    for (int i = 0; i < cfg->root_npub_count; i++) {
+        /* Build filter: authors=[root], kinds=[3], limit=1 (most recent). */
+        cJSON *filter = cJSON_CreateObject();
+        cJSON *authors = cJSON_CreateArray();
+        cJSON_AddItemToArray(authors, cJSON_CreateString(cfg->root_hex[i]));
+        cJSON_AddItemToObject(filter, "authors", authors);
+        cJSON *kinds = cJSON_CreateArray();
+        cJSON_AddItemToArray(kinds, cJSON_CreateNumber(3));
+        cJSON_AddItemToObject(filter, "kinds", kinds);
+        cJSON_AddItemToObject(filter, "limit", cJSON_CreateNumber(1));
+
+        const char **urls = NULL;
+        int n = 0;
+        char **listed = NULL;
+        nostr_pool_relay_status_t *statuses = NULL;
+        int listed_count = nostr_relay_pool_list_relays(upstream, &listed, &statuses);
+        if (listed_count > 0) {
+            urls = malloc(listed_count * sizeof(char *));
+            for (int j = 0; j < listed_count; j++) { urls[n++] = listed[j]; }
+        }
+        free(listed);
+        free(statuses);
+
+        int ev_count = 0;
+        cJSON **events = nostr_relay_pool_query_sync(upstream, urls, n,
+                                                     filter, &ev_count, 15000);
+        free(urls);
+        cJSON_Delete(filter);
+
+        if (events && ev_count > 0) {
+            int added = parse_p_tags(events[0], followed);
+            total_follows += added;
+            DEBUG_INFO("follow: root %d: kind-3 found, +%d follows (total set %d)",
+                        i, added, followed->count);
+            for (int k = 0; k < ev_count; k++) cJSON_Delete(events[k]);
+            free(events);
+        } else {
+            DEBUG_WARN("follow: root %d: no kind-3 found", i);
+            free(events);
+        }
+    }
+
+    DEBUG_INFO("follow: resolved %d total followed pubkeys (set size %d)",
+                total_follows, followed->count);
+    return 0;
+}

caching/src/follow_graph.h

@@ -0,0 +1,27 @@
+/*
+ * caching_relay - follow graph resolution.
+ *
+ * Decodes root npubs (NIP-19) to hex, queries their most recent kind-3
+ * contact list from the upstream pool, parses the "p" tags, and populates
+ * the in-memory followed-pubkey set (root pubkeys + their follows).
+ */
+#ifndef CACHING_RELAY_FOLLOW_GRAPH_H
+#define CACHING_RELAY_FOLLOW_GRAPH_H
+
+#include "config.h"
+#include "state.h"
+#include "../nostr_core_lib/nostr_core/nostr_core.h"
+
+/* Check if a hex pubkey is one of the root (admin) npubs. Returns 1 if yes. */
+int cr_follow_is_root(const cr_config_t *cfg, const char *hex);
+
+/* Decode all root_npubs in cfg into cfg->root_hex[]. Returns 0 on success. */
+int cr_follow_decode_roots(cr_config_t *cfg);
+
+/* Resolve the follow graph: for each root hex pubkey, query the most recent
+ * kind-3 from the upstream pool, parse "p" tags, and add root + follows to
+ * the followed set. Returns 0 on success, -1 on hard failure. */
+int cr_follow_resolve(cr_config_t *cfg, nostr_relay_pool_t *upstream,
+                      cr_pubkey_set_t *followed);
+
+#endif /* CACHING_RELAY_FOLLOW_GRAPH_H */

caching/src/forward_catchup.c

@@ -0,0 +1,200 @@
+/*
+ * caching_relay - forward catch-up implementation.
+ *
+ * See forward_catchup.h for design.
+ */
+#include "forward_catchup.h"
+#include "pg_inbox.h"
+#include "config.h"
+#include "follow_graph.h"
+#include "relay_sink.h"
+#include "debug.h"
+
+#include <cjson/cJSON.h>
+#include <time.h>
+#include <string.h>
+#include <stdlib.h>
+
+/* Find the newest (maximum) created_at among an array of event JSON objects.
+ * Returns 1 and sets *out_newest, or 0 if no events / no valid created_at. */
+static int find_newest_created_at(cJSON **events, int count, long *out_newest) {
+    long newest = 0;
+    int found = 0;
+    for (int i = 0; i < count; i++) {
+        cJSON *ca = cJSON_GetObjectItem(events[i], "created_at");
+        if (!ca || !cJSON_IsNumber(ca)) continue;
+        long ts = (long)ca->valuedouble;
+        if (!found || ts > newest) {
+            newest = ts;
+            found = 1;
+        }
+    }
+    if (found && out_newest) *out_newest = newest;
+    return found;
+}
+
+/* Build the kinds array for a given pubkey (admin vs regular).
+ * Returns NULL if no kinds filter should be applied (admin_all_kinds). */
+static cJSON *build_kinds(cr_config_t *cfg, const char *pk) {
+    int is_admin = cr_follow_is_root(cfg, pk);
+    if (is_admin && cfg->admin_all_kinds) {
+        return NULL;
+    }
+    cJSON *kinds = cJSON_CreateArray();
+    if (is_admin && cfg->admin_kind_count > 0) {
+        for (int i = 0; i < cfg->admin_kind_count; i++)
+            cJSON_AddItemToArray(kinds, cJSON_CreateNumber(cfg->admin_kinds[i]));
+    } else {
+        for (int i = 0; i < cfg->kind_count; i++)
+            cJSON_AddItemToArray(kinds, cJSON_CreateNumber(cfg->kinds[i]));
+    }
+    return kinds;
+}
+
+/* Get relay URLs for an author from the relay progress table.
+ * Returns a cJSON array of relay_url strings. Caller must cJSON_Delete().
+ * Returns NULL on error or if no relays found. */
+static cJSON *get_author_relays(const char *pk) {
+    /* Use pg_inbox_get_incomplete_relays for incomplete authors.
+     * For completed authors, we need all relays — query directly. */
+    cJSON *incomplete = pg_inbox_get_incomplete_relays(pk);
+    if (incomplete && cJSON_GetArraySize(incomplete) > 0) {
+        /* Extract just the relay_url strings. */
+        cJSON *urls = cJSON_CreateArray();
+        int n = cJSON_GetArraySize(incomplete);
+        for (int i = 0; i < n; i++) {
+            cJSON *entry = cJSON_GetArrayItem(incomplete, i);
+            cJSON *url = cJSON_GetObjectItemCaseSensitive(entry, "relay_url");
+            if (url && cJSON_IsString(url) && url->valuestring[0]) {
+                cJSON_AddItemToArray(urls, cJSON_CreateString(url->valuestring));
+            }
+        }
+        cJSON_Delete(incomplete);
+        if (cJSON_GetArraySize(urls) > 0) return urls;
+        cJSON_Delete(urls);
+    }
+    if (incomplete) cJSON_Delete(incomplete);
+
+    /* For completed authors, fall back to the upstream pool's connected
+     * relays. The caller will use the pool directly. */
+    return NULL;
+}
+
+int cr_forward_catchup(cr_config_t *cfg,
+                        nostr_relay_pool_t *upstream,
+                        cr_sink_t *sink) {
+    if (!cfg || !upstream || !sink) return -1;
+
+    cJSON *authors = pg_inbox_get_authors_for_catchup();
+    if (!authors) {
+        DEBUG_INFO("forward_catchup: no authors with last_event_at > 0");
+        return 0;
+    }
+
+    int author_count = cJSON_GetArraySize(authors);
+    if (author_count == 0) {
+        cJSON_Delete(authors);
+        DEBUG_INFO("forward_catchup: no authors need catch-up");
+        return 0;
+    }
+
+    DEBUG_INFO("forward_catchup: checking %d authors for missed events", author_count);
+
+    long now = (long)time(NULL);
+    int page_size = cfg->backfill.events_per_tick;
+    if (page_size < 1) page_size = 500;
+
+    cr_sink_set_source_class(sink, CR_SINK_CLASS_BACKFILL);
+
+    int total_events_published = 0;
+    int authors_caught_up = 0;
+
+    for (int i = 0; i < author_count; i++) {
+        cJSON *entry = cJSON_GetArrayItem(authors, i);
+        if (!entry) continue;
+
+        cJSON *pk_node = cJSON_GetObjectItemCaseSensitive(entry, "pubkey");
+        cJSON *lea_node = cJSON_GetObjectItemCaseSensitive(entry, "last_event_at");
+        if (!pk_node || !cJSON_IsString(pk_node) || !lea_node || !cJSON_IsNumber(lea_node))
+            continue;
+
+        const char *pk = pk_node->valuestring;
+        long last_event_at = (long)lea_node->valuedouble;
+
+        if (last_event_at <= 0 || last_event_at >= now) continue;
+
+        /* Build filter: since = last_event_at + 1, until = now. */
+        cJSON *filter = cJSON_CreateObject();
+        cJSON *authors_arr = cJSON_CreateArray();
+        cJSON_AddItemToArray(authors_arr, cJSON_CreateString(pk));
+        cJSON_AddItemToObject(filter, "authors", authors_arr);
+        cJSON *kinds = build_kinds(cfg, pk);
+        if (kinds) cJSON_AddItemToObject(filter, "kinds", kinds);
+        cJSON_AddItemToObject(filter, "since", cJSON_CreateNumber((double)(last_event_at + 1)));
+        cJSON_AddItemToObject(filter, "until", cJSON_CreateNumber((double)now));
+        cJSON_AddItemToObject(filter, "limit", cJSON_CreateNumber((double)page_size));
+
+        /* Try to get author-specific relays first; fall back to upstream pool. */
+        cJSON *author_relays = get_author_relays(pk);
+
+        int ev_count = 0;
+        cJSON **events = NULL;
+
+        if (author_relays && cJSON_GetArraySize(author_relays) > 0) {
+            /* Query using the author's outbox relays. */
+            int n_relays = cJSON_GetArraySize(author_relays);
+            const char **urls = malloc(sizeof(char *) * n_relays);
+            for (int r = 0; r < n_relays; r++) {
+                cJSON *u = cJSON_GetArrayItem(author_relays, r);
+                urls[r] = cJSON_IsString(u) ? u->valuestring : "";
+            }
+            events = synchronous_query_relays_with_progress(
+                urls, n_relays, filter, RELAY_QUERY_ALL_RESULTS,
+                &ev_count, 30, NULL, NULL, 0, NULL);
+            free(urls);
+        } else {
+            /* Fall back: query all connected upstream relays.
+             * Use the pool's relay list. We pass NULL for urls to let
+             * the pool use all connected relays. */
+            events = synchronous_query_relays_with_progress(
+                NULL, 0, filter, RELAY_QUERY_ALL_RESULTS,
+                &ev_count, 30, NULL, NULL, 0, NULL);
+        }
+        cJSON_Delete(author_relays);
+        cJSON_Delete(filter);
+
+        if (events && ev_count > 0) {
+            /* Publish all events. */
+            long newest = 0;
+            find_newest_created_at(events, ev_count, &newest);
+
+            for (int k = 0; k < ev_count; k++) {
+                cr_sink_publish(sink, events[k]);
+                cJSON_Delete(events[k]);
+            }
+            free(events);
+            total_events_published += ev_count;
+            authors_caught_up++;
+
+            /* Update last_event_at to the newest event we saw. */
+            if (newest > 0) {
+                pg_inbox_update_last_event_at(pk, newest);
+            }
+
+            DEBUG_LOG("forward_catchup: %s -> %d events (since=%ld, until=%ld)",
+                      pk, ev_count, last_event_at + 1, now);
+        } else {
+            /* No events in the gap — update last_event_at to now so we
+             * don't re-query the same empty window next time. */
+            pg_inbox_update_last_event_at(pk, now);
+            if (events) free(events);
+        }
+    }
+
+    cJSON_Delete(authors);
+
+    DEBUG_INFO("forward_catchup: %d authors checked, %d had events, %d total events published",
+              author_count, authors_caught_up, total_events_published);
+
+    return 0;
+}

caching/src/forward_catchup.h

@@ -0,0 +1,30 @@
+/*
+ * caching_relay - forward catch-up for gap bridging.
+ *
+ * When the caching service starts (or caching is re-enabled after being
+ * off), events posted by followed authors during the downtime are missed
+ * by the backward-drain backfill (which walks toward the beginning of
+ * time) and by the live subscriber (which starts at `since = now`).
+ *
+ * The forward catch-up queries `since = last_event_at + 1, until = now`
+ * for each followed author to bridge that gap. `last_event_at` is the
+ * `created_at` of the most recent event we've ever seen for the author,
+ * maintained by the backfill and live subscriber.
+ */
+#ifndef CACHING_RELAY_FORWARD_CATCHUP_H
+#define CACHING_RELAY_FORWARD_CATCHUP_H
+
+#include "config.h"
+#include "relay_sink.h"
+#include "../nostr_core_lib/nostr_core/nostr_core.h"
+
+/* Run forward catch-up for all followed authors with last_event_at > 0.
+ * For each author, queries events from last_event_at + 1 to now on one
+ * outbox relay and publishes them to the sink.
+ *
+ * Returns 0 on success, -1 on error. */
+int cr_forward_catchup(cr_config_t *cfg,
+                        nostr_relay_pool_t *upstream,
+                        cr_sink_t *sink);
+
+#endif /* CACHING_RELAY_FORWARD_CATCHUP_H */

caching/src/jsonc_strip.c

@@ -0,0 +1,69 @@
+/*
+ * caching_relay - strip JSONC comments so cJSON can parse it.
+ */
+#define _GNU_SOURCE
+#include "jsonc_strip.h"
+
+#include <stdlib.h>
+#include <string.h>
+
+char *jsonc_strip_comments(const char *input, size_t len) {
+    if (!input) return NULL;
+    if (len == 0) len = strlen(input);
+
+    /* Worst case: output is same size as input (no comments). +1 for NUL. */
+    char *out = malloc(len + 1);
+    if (!out) return NULL;
+
+    size_t i = 0, o = 0;
+    int in_string = 0;
+    int escape = 0;
+
+    while (i < len) {
+        char c = input[i];
+
+        if (in_string) {
+            out[o++] = c;
+            if (escape) {
+                escape = 0;
+            } else if (c == '\\') {
+                escape = 1;
+            } else if (c == '"') {
+                in_string = 0;
+            }
+            i++;
+            continue;
+        }
+
+        /* Not in a string. */
+        if (c == '"') {
+            in_string = 1;
+            out[o++] = c;
+            i++;
+            continue;
+        }
+
+        /* Line comment // */
+        if (c == '/' && i + 1 < len && input[i + 1] == '/') {
+            i += 2;
+            while (i < len && input[i] != '\n') i++;
+            continue;
+        }
+
+        /* Block comment / * ... * / */
+        if (c == '/' && i + 1 < len && input[i + 1] == '*') {
+            i += 2;
+            while (i < len && !(input[i] == '*' && i + 1 < len && input[i + 1] == '/')) i++;
+            if (i < len) i += 2; /* skip closing */
+            /* Preserve a space so tokens don't merge. */
+            out[o++] = ' ';
+            continue;
+        }
+
+        out[o++] = c;
+        i++;
+    }
+
+    out[o] = '\0';
+    return out;
+}

caching/src/jsonc_strip.h

@@ -0,0 +1,16 @@
+/*
+ * caching_relay - strip JSONC comments so cJSON can parse it.
+ *
+ * cJSON does not natively understand JSONC. This produces a heap buffer the
+ * caller must free() containing the comment-stripped JSON. String literals are
+ * respected so a double-slash inside a string is preserved.
+ */
+#ifndef CACHING_RELAY_JSONC_STRIP_H
+#define CACHING_RELAY_JSONC_STRIP_H
+
+#include <stddef.h>
+
+/* Returns malloc'd buffer (null-terminated) or NULL on alloc failure. */
+char *jsonc_strip_comments(const char *input, size_t len);
+
+#endif /* CACHING_RELAY_JSONC_STRIP_H */

caching/src/live_subscriber.c

@@ -0,0 +1,199 @@
+/*
+ * caching_relay - live subscription on the upstream pool
+ */
+#define _GNU_SOURCE
+#include "live_subscriber.h"
+#include "follow_graph.h"
+#include "pg_inbox.h"
+#include "debug.h"
+
+#include <string.h>
+#include <stdlib.h>
+#include <time.h>
+
+/* Context passed as user_data to the subscription callbacks. */
+typedef struct {
+    cr_sink_t    *sink;
+    cr_live_t    *live;
+    cr_config_t  *cfg;
+} cr_live_ctx_t;
+
+static cr_live_ctx_t g_live_ctx;
+
+static void live_on_event(cJSON *event, const char *relay_url, void *user_data) {
+    cr_live_ctx_t *ctx = (cr_live_ctx_t *)user_data;
+    (void)relay_url;
+    ctx->live->events_received++;
+    cr_sink_publish(ctx->sink, event);
+
+    /* Update last_event_at for forward catch-up gap tracking. */
+    cJSON *ev_pubkey = cJSON_GetObjectItem(event, "pubkey");
+    cJSON *ev_created = cJSON_GetObjectItem(event, "created_at");
+    if (ev_pubkey && cJSON_IsString(ev_pubkey) &&
+        ev_created && cJSON_IsNumber(ev_created)) {
+        pg_inbox_update_last_event_at(ev_pubkey->valuestring,
+                                      (long)ev_created->valuedouble);
+    }
+
+    /* Detect admin kind-3 (contact list) changes from a root pubkey and
+     * signal the main loop to refresh the follow graph immediately. */
+    if (ctx->cfg) {
+        cJSON *kind = cJSON_GetObjectItem(event, "kind");
+        cJSON *pubkey = cJSON_GetObjectItem(event, "pubkey");
+        if (kind && cJSON_IsNumber(kind) && kind->valuedouble == 3.0 &&
+            pubkey && cJSON_IsString(pubkey)) {
+            if (cr_follow_is_root(ctx->cfg, cJSON_GetStringValue(pubkey))) {
+                ctx->live->follow_graph_changed = 1;
+                DEBUG_INFO("live: root kind-3 detected from %s, "
+                           "signaling follow graph refresh",
+                           cJSON_GetStringValue(pubkey));
+            }
+        }
+    }
+}
+
+static void live_on_eose(cJSON **events, int event_count, void *user_data) {
+    (void)events; (void)event_count; (void)user_data;
+    DEBUG_LOG("live: EOSE (stored events flushed), staying open");
+}
+
+/* Build a filter for non-admin followed pubkeys with regular kinds. */
+static cJSON *build_follows_filter(cr_config_t *cfg, cr_pubkey_set_t *followed) {
+    cJSON *filter = cJSON_CreateObject();
+    cJSON *authors = cJSON_CreateArray();
+    for (int i = 0; i < followed->count; i++) {
+        /* Skip admin pubkeys - they get their own subscription. */
+        if (cr_follow_is_root(cfg, followed->items[i])) continue;
+        cJSON_AddItemToArray(authors, cJSON_CreateString(followed->items[i]));
+    }
+    cJSON_AddItemToObject(filter, "authors", authors);
+
+    cJSON *kinds = cJSON_CreateArray();
+    for (int i = 0; i < cfg->kind_count; i++)
+        cJSON_AddItemToArray(kinds, cJSON_CreateNumber(cfg->kinds[i]));
+    cJSON_AddItemToObject(filter, "kinds", kinds);
+
+    cJSON_AddItemToObject(filter, "since", cJSON_CreateNumber((double)time(NULL)));
+    return filter;
+}
+
+/* Build a filter for admin (root) pubkeys with admin_kinds (or all kinds). */
+static cJSON *build_admin_filter(cr_config_t *cfg) {
+    cJSON *filter = cJSON_CreateObject();
+    cJSON *authors = cJSON_CreateArray();
+    for (int i = 0; i < cfg->root_npub_count; i++)
+        cJSON_AddItemToArray(authors, cJSON_CreateString(cfg->root_hex[i]));
+    cJSON_AddItemToObject(filter, "authors", authors);
+
+    /* If admin_all_kinds, omit the kinds filter entirely (grab everything). */
+    if (!cfg->admin_all_kinds && cfg->admin_kind_count > 0) {
+        cJSON *kinds = cJSON_CreateArray();
+        for (int i = 0; i < cfg->admin_kind_count; i++)
+            cJSON_AddItemToArray(kinds, cJSON_CreateNumber(cfg->admin_kinds[i]));
+        cJSON_AddItemToObject(filter, "kinds", kinds);
+    }
+
+    cJSON_AddItemToObject(filter, "since", cJSON_CreateNumber((double)time(NULL)));
+    return filter;
+}
+
+static int get_relay_urls(nostr_relay_pool_t *upstream, const char ***urls_out) {
+    char **listed = NULL;
+    nostr_pool_relay_status_t *statuses = NULL;
+    int n = nostr_relay_pool_list_relays(upstream, &listed, &statuses);
+    const char **urls = NULL;
+    if (n > 0) {
+        urls = malloc(n * sizeof(char *));
+        for (int j = 0; j < n; j++) urls[j] = listed[j];
+    }
+    free(listed);
+    free(statuses);
+    *urls_out = urls;
+    return n;
+}
+
+static nostr_pool_subscription_t *open_subscription(nostr_relay_pool_t *upstream,
+                                                     cJSON *filter) {
+    const char **urls = NULL;
+    int n = get_relay_urls(upstream, &urls);
+
+    nostr_pool_subscription_t *sub = nostr_relay_pool_subscribe(
+        upstream, urls, n, filter,
+        live_on_event, live_on_eose, &g_live_ctx,
+        0, 1, NOSTR_POOL_EOSE_FULL_SET, 0, 0);
+    free(urls);
+    return sub;
+}
+
+static int open_subs(cr_live_t *live, cr_config_t *cfg, nostr_relay_pool_t *upstream,
+                     cr_pubkey_set_t *followed, cr_sink_t *sink) {
+    g_live_ctx.sink = sink;
+    g_live_ctx.live = live;
+    g_live_ctx.cfg  = cfg;
+
+    int admin_count = 0;
+    int follows_count = 0;
+    for (int i = 0; i < followed->count; i++) {
+        if (cr_follow_is_root(cfg, followed->items[i])) admin_count++;
+        else follows_count++;
+    }
+
+    /* Follows subscription (non-admin pubkeys, regular kinds). */
+    if (follows_count > 0) {
+        cJSON *filter = build_follows_filter(cfg, followed);
+        live->follows_sub = open_subscription(upstream, filter);
+        cJSON_Delete(filter);
+        if (!live->follows_sub) {
+            DEBUG_ERROR("live: follows subscribe failed");
+        } else {
+            DEBUG_INFO("live: follows sub - %d authors, %d kinds",
+                        follows_count, cfg->kind_count);
+        }
+    }
+
+    /* Admin subscription (root npubs, admin_kinds or all kinds). */
+    if (admin_count > 0 || cfg->root_npub_count > 0) {
+        cJSON *filter = build_admin_filter(cfg);
+        live->admin_sub = open_subscription(upstream, filter);
+        cJSON_Delete(filter);
+        if (!live->admin_sub) {
+            DEBUG_ERROR("live: admin subscribe failed");
+        } else {
+            if (cfg->admin_all_kinds) {
+                DEBUG_INFO("live: admin sub - %d authors, ALL kinds",
+                            cfg->root_npub_count);
+            } else {
+                DEBUG_INFO("live: admin sub - %d authors, %d kinds",
+                            cfg->root_npub_count, cfg->admin_kind_count);
+            }
+        }
+    }
+
+    live->last_resubscribe = time(NULL);
+    return 0;
+}
+
+int cr_live_open(cr_live_t *live, cr_config_t *cfg, nostr_relay_pool_t *upstream,
+                 cr_pubkey_set_t *followed, cr_sink_t *sink) {
+    memset(live, 0, sizeof(*live));
+    return open_subs(live, cfg, upstream, followed, sink);
+}
+
+int cr_live_resubscribe(cr_live_t *live, cr_config_t *cfg,
+                        nostr_relay_pool_t *upstream, cr_pubkey_set_t *followed,
+                        cr_sink_t *sink) {
+    cr_live_close(live);
+    DEBUG_INFO("live: resubscribing (events so far: %ld)", live->events_received);
+    return open_subs(live, cfg, upstream, followed, sink);
+}
+
+void cr_live_close(cr_live_t *live) {
+    if (live->follows_sub) {
+        nostr_pool_subscription_close(live->follows_sub);
+        live->follows_sub = NULL;
+    }
+    if (live->admin_sub) {
+        nostr_pool_subscription_close(live->admin_sub);
+        live->admin_sub = NULL;
+    }
+}

caching/src/live_subscriber.h

@@ -0,0 +1,38 @@
+/*
+ * caching_relay - live subscription on the upstream pool.
+ *
+ * Builds filters from the followed-pubkey set + configured kinds, opens
+ * long-lived subscriptions, and routes on_event to the relay sink.
+ *
+ * Two subscriptions are opened:
+ *   1. "follows" sub: non-admin followed pubkeys + regular kinds
+ *   2. "admin" sub: root (admin) npubs + admin_kinds (or all kinds if [*])
+ */
+#ifndef CACHING_RELAY_LIVE_SUBSCRIBER_H
+#define CACHING_RELAY_LIVE_SUBSCRIBER_H
+
+#include "config.h"
+#include "state.h"
+#include "relay_sink.h"
+#include "../nostr_core_lib/nostr_core/nostr_core.h"
+
+typedef struct {
+    nostr_pool_subscription_t *follows_sub;  /* non-admin pubkeys, regular kinds */
+    nostr_pool_subscription_t *admin_sub;    /* admin pubkeys, admin_kinds */
+    long                       events_received;
+    time_t                     last_resubscribe;
+    int                        follow_graph_changed; /* set when a root npub publishes a kind-3 */
+} cr_live_t;
+
+/* Open the live subscription(s). Returns 0 on success. */
+int  cr_live_open(cr_live_t *live, cr_config_t *cfg, nostr_relay_pool_t *upstream,
+                  cr_pubkey_set_t *followed, cr_sink_t *sink);
+
+/* Close + reopen the subscription(s). Returns 0 on success. */
+int  cr_live_resubscribe(cr_live_t *live, cr_config_t *cfg,
+                         nostr_relay_pool_t *upstream, cr_pubkey_set_t *followed,
+                         cr_sink_t *sink);
+
+void cr_live_close(cr_live_t *live);
+
+#endif /* CACHING_RELAY_LIVE_SUBSCRIBER_H */

caching/src/main.c

@@ -0,0 +1,639 @@
+/*
+ * caching_relay - a daemon that caches Nostr events from followed people
+ * into a local relay.
+ *
+ * Architecture: see plans/plan.md. Two nostr_relay_pool_t instances:
+ *   - upstream_pool: query/subscribe to upstream relays
+ *   - sink_pool (in cr_sink_t): publish-only to the local relay
+ *
+ * Build: see Makefile. Statically linked C99 binary, c-relay style.
+ */
+#define _GNU_SOURCE
+#include "main.h"
+#include "debug.h"
+#include "config.h"
+#include "state.h"
+#include "follow_graph.h"
+#include "relay_sink.h"
+#include "live_subscriber.h"
+#include "backfill.h"
+#include "forward_catchup.h"
+#include "relay_discovery.h"
+#include "pg_inbox.h"
+#include "pg_config.h"
+
+#include "../nostr_core_lib/nostr_core/nostr_core.h"
+#include "../nostr_core_lib/nostr_core/nostr_log.h"
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <signal.h>
+#include <time.h>
+#include <unistd.h>
+#include <getopt.h>
+
+/* Forward nostr_core_lib's internal logging to our debug system. */
+static void nostr_log_forwarder(int level, const char *component,
+                                const char *message, void *user_data) {
+    (void)user_data;
+    /* Map nostr log levels to our debug levels (they're the same 1-5). */
+    if (level >= 5) {
+        DEBUG_TRACE("[nostr:%s] %s", component ? component : "?", message ? message : "");
+    } else if (level >= 4) {
+        DEBUG_LOG("[nostr:%s] %s", component ? component : "?", message ? message : "");
+    } else if (level >= 3) {
+        DEBUG_INFO("[nostr:%s] %s", component ? component : "?", message ? message : "");
+    } else if (level >= 2) {
+        DEBUG_WARN("[nostr:%s] %s", component ? component : "?", message ? message : "");
+    } else {
+        DEBUG_ERROR("[nostr:%s] %s", component ? component : "?", message ? message : "");
+    }
+}
+
+/* Initialize per-relay backfill progress rows for every followed pubkey.
+ * For each author, merges its discovered outbox relays (from relay_map)
+ * with the bootstrap (upstream) relays from cfg, then inserts one
+ * caching_backfill_relay_progress row per relay (ON CONFLICT DO NOTHING).
+ * Safe to call repeatedly - existing rows are left untouched. */
+static void init_relay_progress_for_all(const cr_config_t *cfg,
+                                        const cr_relay_map_t *relay_map,
+                                        const cr_pubkey_set_t *followed) {
+    if (!followed || followed->count <= 0) return;
+
+    /* Bootstrap relay URLs from cfg->upstream_relays. */
+    const char **bootstrap = NULL;
+    int bootstrap_n = cfg->upstream_count;
+    if (bootstrap_n > 0) {
+        bootstrap = malloc(bootstrap_n * sizeof(char *));
+        if (!bootstrap) return;
+        for (int i = 0; i < bootstrap_n; i++)
+            bootstrap[i] = cfg->upstream_relays[i];
+    }
+
+    for (int i = 0; i < followed->count; i++) {
+        const char *pk = followed->items[i];
+        if (!pk || !*pk) continue;
+
+        /* Collect this author's outbox relays. */
+        const cr_outbox_entry_t *oe = NULL;
+        int outbox_n = 0;
+        if (relay_map) {
+            oe = cr_relay_map_get_outbox(relay_map, pk);
+            if (oe) outbox_n = oe->relay_count;
+        }
+
+        int total = outbox_n + bootstrap_n;
+        if (total <= 0) continue;
+
+        const char **urls = malloc(total * sizeof(char *));
+        if (!urls) continue;
+        int n = 0;
+        if (oe) {
+            for (int j = 0; j < oe->relay_count && n < total; j++)
+                urls[n++] = oe->relays[j];
+        }
+        for (int j = 0; j < bootstrap_n && n < total; j++) {
+            int dup = 0;
+            for (int k = 0; k < n; k++) {
+                if (strcmp(urls[k], bootstrap[j]) == 0) { dup = 1; break; }
+            }
+            if (!dup) urls[n++] = bootstrap[j];
+        }
+
+        if (n > 0) {
+            pg_inbox_init_relay_progress_for_author(pk, urls, n);
+        }
+        free(urls);
+    }
+
+    free(bootstrap);
+}
+
+volatile sig_atomic_t g_shutdown = 0;
+static volatile sig_atomic_t g_reload  = 0;
+
+static void on_signal(int sig) {
+    if (sig == SIGINT || sig == SIGTERM) g_shutdown = 1;
+    else if (sig == SIGHUP) g_reload = 1;
+}
+
+static void usage(const char *prog) {
+    fprintf(stderr,
+        "caching_relay %s - cache Nostr events from followed people into a local relay\n"
+        "\n"
+        "Usage: %s [-c <config.jsonc>] [-p <pg-conn>] [options]\n"
+        "\n"
+        "Options:\n"
+        "  -c, --config <file>   Path to .jsonc config file (default: ./caching_relay_config.jsonc)\n"
+        "  -p, --pg-conn <str>   PostgreSQL connection string (libpq format). When provided,\n"
+        "                        config is read from the c-relay-pg config table and fetched\n"
+        "                        events are inserted into the caching_event_inbox table instead\n"
+        "                        of being published via WebSocket to a local relay.\n"
+        "  -d, --debug <level>   Log level 0-5 (0=none, 1=error, 2=warn, 3=info, 4=debug, 5=trace). Default 3.\n"
+        "  -r, --restart         Reset state to first-time startup (ignore local relay cache,\n"
+        "                        re-discover all kind-10002 from bootstrap relays, reset backfill)\n"
+        "  -h, --help            Show this help\n"
+        "\n"
+        "Without -p, the daemon uses the .jsonc config file and publishes to a local relay\n"
+        "via WebSocket (legacy mode). With -p, it uses PostgreSQL for config and inbox.\n"
+        "The config file is also the persistent state store in legacy mode; the daemon\n"
+        "rewrites it as backfill progresses. See plans/plan.md and caching_relay_config.jsonc.\n",
+        CR_VERSION, prog);
+}
+
+int main(int argc, char **argv) {
+    const char *config_path = NULL;
+    const char *pg_conn = NULL;
+    int log_level = DEBUG_LEVEL_INFO;
+    int restart = 0;
+
+    static struct option longopts[] = {
+        {"config",  required_argument, 0, 'c'},
+        {"pg-conn", required_argument, 0, 'p'},
+        {"debug",   required_argument, 0, 'd'},
+        {"restart", no_argument,       0, 'r'},
+        {"help",    no_argument,       0, 'h'},
+        {0, 0, 0, 0}
+    };
+    int opt;
+    while ((opt = getopt_long(argc, argv, "c:p:d:rh", longopts, NULL)) != -1) {
+        switch (opt) {
+            case 'c': config_path = optarg; break;
+            case 'p': pg_conn = optarg; break;
+            case 'd': log_level = atoi(optarg); break;
+            case 'r': restart = 1; break;
+            case 'h': usage(argv[0]); return 0;
+            default:  usage(argv[0]); return 1;
+        }
+    }
+    /* In PostgreSQL mode, the .jsonc config file is optional. */
+    if (!config_path && !pg_conn) {
+        /* Default: look for caching_relay.jsonc in the current directory. */
+        config_path = "caching_relay_config.jsonc";
+        if (access(config_path, F_OK) != 0) {
+            fprintf(stderr, "ERROR: no config specified and default '%s' not found\n\n", config_path);
+            usage(argv[0]);
+            return 1;
+        }
+    }
+    if (log_level < 0) log_level = 0;
+    if (log_level > 5) log_level = 5;
+
+    debug_init(log_level);
+
+    /* Enable nostr_core_lib internal logging and forward to our debug system.
+     * This shows the actual WebSocket messages (REQ filters, EVENT responses)
+     * at debug level 5 (trace). */
+    nostr_set_log_callback(nostr_log_forwarder, NULL);
+    nostr_set_log_level((nostr_log_level_t)log_level);
+
+    DEBUG_INFO("caching_relay %s starting (config=%s, pg-conn=%s, loglevel=%d%s)",
+                CR_VERSION,
+                config_path ? config_path : "(none)",
+                pg_conn ? "yes" : "no",
+                log_level, restart ? ", RESTART" : "");
+
+    /* Signals. */
+    struct sigaction sa;
+    memset(&sa, 0, sizeof(sa));
+    sa.sa_handler = on_signal;
+    sigaction(SIGINT, &sa, NULL);
+    sigaction(SIGTERM, &sa, NULL);
+    sigaction(SIGHUP, &sa, NULL);
+    /* Ignore SIGPIPE - relay pool handles its own socket errors. */
+    signal(SIGPIPE, SIG_IGN);
+
+    /* PostgreSQL inbox mode: connect and load config from the config table. */
+    long config_generation = -1;
+    if (pg_conn) {
+        if (pg_inbox_init(pg_conn) != 0) {
+            DEBUG_ERROR("failed to connect to PostgreSQL");
+            return 1;
+        }
+        config_generation = pg_inbox_get_config_generation();
+        if (config_generation < 0) {
+            DEBUG_WARN("could not read caching_config_generation (defaulting to 0)");
+            config_generation = 0;
+        }
+        DEBUG_INFO("config generation: %ld", config_generation);
+    }
+
+    /* Load config. */
+    cr_config_t cfg;
+    if (pg_conn) {
+        if (pg_config_load(&cfg) != 0) {
+            DEBUG_ERROR("failed to load config from PostgreSQL");
+            pg_inbox_shutdown();
+            return 1;
+        }
+    } else {
+        if (cr_config_load(&cfg, config_path) != 0) return 1;
+    }
+
+    /* --restart: reset state to first-time startup. */
+    if (restart) {
+        DEBUG_INFO("RESTART: resetting state to first-time startup");
+        cfg.state.backfilled_until = 0;
+        if (pg_conn) {
+            /* Reset per-author backfill progress (caching_followed_pubkeys)
+             * so the next run starts fresh. The followed set itself is
+             * preserved; only cursor/completion state is reset. */
+            pg_inbox_reset_backfill_progress();
+        } else {
+            cr_config_save_state(&cfg);
+        }
+    }
+
+    /* Init crypto. */
+    if (nostr_crypto_init() != NOSTR_SUCCESS) {
+        DEBUG_ERROR("nostr_crypto_init failed");
+        return 1;
+    }
+
+    /* In-memory state. */
+    cr_seen_ring_t seen;
+    cr_seen_ring_init(&seen);
+    cr_pubkey_set_t followed;
+    cr_pubkey_set_init(&followed);
+
+    /* Upstream pool. */
+    nostr_relay_pool_t *upstream = nostr_relay_pool_create(nostr_pool_reconnect_config_default());
+    if (!upstream) {
+        DEBUG_ERROR("failed to create upstream pool");
+        return 1;
+    }
+    for (int i = 0; i < cfg.upstream_count; i++) {
+        if (nostr_relay_pool_add_relay(upstream, cfg.upstream_relays[i]) != NOSTR_SUCCESS) {
+            DEBUG_WARN("failed to add upstream relay %s (continuing)", cfg.upstream_relays[i]);
+        } else {
+            DEBUG_INFO("upstream: added %s", cfg.upstream_relays[i]);
+        }
+    }
+
+    /* Sink: WebSocket pool (legacy) or PostgreSQL inbox. */
+    cr_sink_t sink;
+    if (pg_conn) {
+        if (cr_sink_init_pg(&sink, &seen) != 0) {
+            DEBUG_ERROR("failed to init sink (pg)");
+            return 1;
+        }
+    } else {
+        if (cr_sink_init(&sink, cfg.local_relay, &seen) != 0) {
+            DEBUG_ERROR("failed to init sink");
+            return 1;
+        }
+    }
+
+    /* Give the sink pool a moment to connect to the local relay before we
+     * start publishing (relay discovery caches kind-10002 events to local).
+     * No-op in PostgreSQL inbox mode (cr_sink_pump does nothing). */
+    if (!pg_conn) {
+        DEBUG_INFO("waiting for sink connection to establish...");
+        for (int i = 0; i < 30 && !g_shutdown; i++) {
+            cr_sink_pump(&sink, 100);
+        }
+    }
+
+    /* Resolve follow graph. */
+    if (g_shutdown) goto shutdown;
+    if (cr_follow_resolve(&cfg, upstream, &followed) != 0) {
+        DEBUG_ERROR("follow graph resolution failed");
+        return 1;
+    }
+
+    /* Sync the followed set to the DB so the backfill tick can iterate
+     * over it (per-author until-cursor drain). Also run the one-time
+     * migration from the old caching_backfill_progress table. */
+    if (pg_conn) {
+        pg_inbox_migrate_backfill_progress();
+        const char **root_pks = malloc(cfg.root_npub_count * sizeof(char *));
+        for (int i = 0; i < cfg.root_npub_count; i++)
+            root_pks[i] = cfg.root_hex[i];
+        pg_inbox_sync_followed_pubkeys((const char **)followed.items,
+                                        followed.count, root_pks,
+                                        cfg.root_npub_count);
+        free(root_pks);
+    }
+
+    if (g_shutdown) goto shutdown;
+
+    /* Discover outbox relays (NIP-65) and compute minimum covering set. */
+    int is_first_time = (cfg.state.backfilled_until == 0);
+    cr_relay_map_t relay_map;
+    if (cr_relay_discovery_run(&relay_map, &cfg, upstream, &sink, &followed,
+                                is_first_time) != 0) {
+        DEBUG_WARN("relay discovery failed, continuing with bootstrap relays only");
+        memset(&relay_map, 0, sizeof(relay_map));
+    }
+
+    /* Add discovered outbox relays to the upstream pool. */
+    for (int i = 0; i < relay_map.selected_count; i++) {
+        /* Check if already in the pool (bootstrap relays may already be there). */
+        char **listed = NULL;
+        nostr_pool_relay_status_t *statuses = NULL;
+        int n = nostr_relay_pool_list_relays(upstream, &listed, &statuses);
+        int already = 0;
+        for (int j = 0; j < n; j++) {
+            if (strcmp(listed[j], relay_map.selected_relays[i]) == 0) {
+                already = 1; break;
+            }
+        }
+        free(listed);
+        free(statuses);
+        if (!already) {
+            if (nostr_relay_pool_add_relay(upstream, relay_map.selected_relays[i]) == NOSTR_SUCCESS) {
+                DEBUG_INFO("upstream: added outbox relay %s", relay_map.selected_relays[i]);
+            }
+        }
+    }
+
+    /* Log final upstream pool. */
+    {
+        char **listed = NULL;
+        nostr_pool_relay_status_t *statuses = NULL;
+        int n = nostr_relay_pool_list_relays(upstream, &listed, &statuses);
+        DEBUG_INFO("upstream_pool: %d relays connected:", n);
+        for (int j = 0; j < n; j++) {
+            DEBUG_INFO("  %s", listed[j]);
+        }
+        free(listed);
+        free(statuses);
+    }
+
+    /* Create per-relay backfill progress rows for every followed pubkey
+     * (outbox relays + bootstrap relays). Existing rows are left untouched
+     * so cursor/completion state is preserved across restarts. */
+    if (pg_conn) {
+        init_relay_progress_for_all(&cfg, &relay_map, &followed);
+    }
+
+    /* Forward catch-up: bridge the gap for events posted while caching
+     * was off. Runs once at startup (not on --restart, which does a full
+     * re-drain from now). For each followed author with last_event_at > 0,
+     * queries since = last_event_at + 1, until = now. */
+    if (pg_conn && !restart && cfg.backfill.enabled) {
+        DEBUG_INFO("forward catch-up: bridging gap for followed authors");
+        cr_forward_catchup(&cfg, upstream, &sink);
+    }
+
+    /* Open live subscription. */
+    cr_live_t live;
+    if (cfg.live.enabled) {
+        if (cr_live_open(&live, &cfg, upstream, &followed, &sink) != 0) {
+            DEBUG_WARN("live subscription failed to open (will retry on resubscribe)");
+        }
+    } else {
+        memset(&live, 0, sizeof(live));
+    }
+
+    /* Init backfill. */
+    cr_backfill_t bf;
+    cr_backfill_init(&bf, &cfg);
+
+    time_t last_follow_refresh = time(NULL);
+    time_t last_state_save = time(NULL);
+    time_t last_status_heartbeat = 0;
+
+    /* Initial status heartbeat in PostgreSQL mode. */
+    if (pg_conn) {
+        int bf_complete = 0, bf_total = 0;
+        pg_inbox_count_backfill_progress(&bf_complete, &bf_total);
+        pg_inbox_update_status("starting", config_generation, (long)time(NULL),
+                               followed.count, relay_map.selected_count, 0,
+                               bf_complete, bf_total, 0, 0, NULL, 0);
+    }
+
+    DEBUG_INFO("entering main loop");
+
+    while (!g_shutdown) {
+        if (g_reload) {
+            g_reload = 0;
+            DEBUG_INFO("SIGHUP: reloading config (state preserved)");
+            cr_config_t newcfg;
+            int reload_ok = 0;
+            if (pg_conn) {
+                if (pg_config_load(&newcfg) == 0 &&
+                    cr_follow_decode_roots(&newcfg) == 0) reload_ok = 1;
+            } else if (config_path) {
+                if (cr_config_load(&newcfg, config_path) == 0) reload_ok = 1;
+            }
+            if (reload_ok) {
+                /* Preserve runtime state across reload. */
+                newcfg.state = cfg.state;
+                cr_config_free(&cfg);
+                cfg = newcfg;
+                DEBUG_INFO("config reloaded");
+                /* Force an immediate follow-graph refresh so any new
+                 * root npubs are picked up right away. */
+                last_follow_refresh = 0;
+            } else {
+                DEBUG_ERROR("config reload failed, keeping old config");
+            }
+        }
+
+        /* PostgreSQL: check for config generation change and reload. */
+        if (pg_conn) {
+            int changed = pg_config_generation_changed(config_generation);
+            if (changed == 1) {
+                long new_gen = pg_inbox_get_config_generation();
+                DEBUG_INFO("config generation changed (%ld -> %ld), reloading",
+                           config_generation, new_gen);
+                cr_config_t newcfg;
+                if (pg_config_load(&newcfg) == 0) {
+                    /* Decode root npubs to hex — pg_config_load fills
+                     * root_npubs[] but NOT root_hex[] / root_hex_ready.
+                     * Without this, cr_follow_is_root() returns 0 for
+                     * everything and the new root's follows are never
+                     * resolved. */
+                    if (cr_follow_decode_roots(&newcfg) != 0) {
+                        DEBUG_ERROR("config reload: failed to decode root npubs, keeping old config");
+                        cr_config_free(&newcfg);
+                    } else {
+                        newcfg.state = cfg.state;
+                        cr_config_free(&cfg);
+                        cfg = newcfg;
+                        config_generation = new_gen;
+                        DEBUG_INFO("config reloaded from PostgreSQL");
+                        /* Force an immediate follow-graph refresh so the
+                         * new root npub's follows are picked up right
+                         * away (instead of waiting up to
+                         * follow_graph_refresh_seconds). */
+                        last_follow_refresh = 0;
+                        /* Resubscribe live with new config. */
+                        if (cfg.live.enabled) {
+                            cr_live_resubscribe(&live, &cfg, upstream, &followed, &sink);
+                        }
+                    }
+                } else {
+                    DEBUG_ERROR("PostgreSQL config reload failed, keeping old config");
+                }
+            } else if (changed < 0) {
+                DEBUG_WARN("config generation check failed");
+            }
+        }
+
+        /* Pump upstream pool (drives live subscription callbacks). */
+        nostr_relay_pool_run(upstream, 100);
+
+        /* Pump sink pool (flush publish callbacks). */
+        cr_sink_pump(&sink, 50);
+
+        /* Backfill tick. */
+        int brc = cr_backfill_tick(&bf, &cfg, upstream, &followed, &sink, &relay_map);
+        (void)brc;
+
+        /* Immediate follow-graph refresh when a root npub publishes a new
+         * kind-3 contact list (detected by the live subscriber). */
+        if (cfg.live.enabled && live.follow_graph_changed) {
+            live.follow_graph_changed = 0;
+            DEBUG_INFO("live: admin kind-3 detected, refreshing follow graph immediately");
+            cr_pubkey_set_t new_followed;
+            cr_pubkey_set_init(&new_followed);
+            if (cr_follow_resolve(&cfg, upstream, &new_followed) == 0) {
+                int changed = (new_followed.count != followed.count);
+                if (!changed) {
+                    for (int i = 0; i < followed.count; i++) {
+                        if (!cr_pubkey_set_contains(&new_followed, followed.items[i])) {
+                            changed = 1; break;
+                        }
+                    }
+                }
+                cr_pubkey_set_free(&followed);
+                followed = new_followed;
+                if (pg_conn) {
+                    const char **root_pks = malloc(cfg.root_npub_count * sizeof(char *));
+                    for (int i = 0; i < cfg.root_npub_count; i++)
+                        root_pks[i] = cfg.root_hex[i];
+                    pg_inbox_sync_followed_pubkeys((const char **)followed.items,
+                                                    followed.count, root_pks,
+                                                    cfg.root_npub_count);
+                    free(root_pks);
+                    /* Create relay progress rows for newly added follows.
+                     * Existing rows are preserved (ON CONFLICT DO NOTHING). */
+                    init_relay_progress_for_all(&cfg, &relay_map, &followed);
+                }
+                if (changed && cfg.live.enabled) {
+                    cr_live_resubscribe(&live, &cfg, upstream, &followed, &sink);
+                }
+                /* Reset the backfill in_progress flag in case we had entered
+                 * steady-state; new follows need to be drained. */
+                bf.in_progress = 1;
+                last_follow_refresh = time(NULL);
+            } else {
+                DEBUG_WARN("immediate follow graph refresh failed");
+                cr_pubkey_set_free(&new_followed);
+            }
+        }
+
+        /* Periodic follow-graph refresh. */
+        time_t now = time(NULL);
+        if (cfg.follow_graph_refresh_seconds > 0 &&
+            (now - last_follow_refresh) >= cfg.follow_graph_refresh_seconds) {
+            DEBUG_INFO("refreshing follow graph");
+            cr_pubkey_set_t new_followed;
+            cr_pubkey_set_init(&new_followed);
+            if (cr_follow_resolve(&cfg, upstream, &new_followed) == 0) {
+                /* If the set changed, resubscribe live. */
+                int changed = (new_followed.count != followed.count);
+                if (!changed) {
+                    for (int i = 0; i < followed.count; i++) {
+                        if (!cr_pubkey_set_contains(&new_followed, followed.items[i])) {
+                            changed = 1; break;
+                        }
+                    }
+                }
+                cr_pubkey_set_free(&followed);
+                followed = new_followed;
+                /* Sync the refreshed followed set to the DB so newly added
+                 * follows get backfilled and dropped follows stop. Existing
+                 * cursor/completion state is preserved (upsert only touches
+                 * is_root and last_seen). */
+                if (pg_conn) {
+                    const char **root_pks = malloc(cfg.root_npub_count * sizeof(char *));
+                    for (int i = 0; i < cfg.root_npub_count; i++)
+                        root_pks[i] = cfg.root_hex[i];
+                    pg_inbox_sync_followed_pubkeys((const char **)followed.items,
+                                                    followed.count, root_pks,
+                                                    cfg.root_npub_count);
+                    free(root_pks);
+                    /* Create relay progress rows for newly added follows.
+                     * Existing rows are preserved (ON CONFLICT DO NOTHING). */
+                    init_relay_progress_for_all(&cfg, &relay_map, &followed);
+                }
+                if (changed && cfg.live.enabled) {
+                    cr_live_resubscribe(&live, &cfg, upstream, &followed, &sink);
+                }
+                /* Reset the backfill in_progress flag in case we had entered
+                 * steady-state; new follows need to be drained. The backfill
+                 * tick will quickly re-enter steady-state if there are no
+                 * incomplete authors, so this is cheap. */
+                bf.in_progress = 1;
+            } else {
+                DEBUG_WARN("follow graph refresh failed");
+                cr_pubkey_set_free(&new_followed);
+            }
+            last_follow_refresh = now;
+        }
+
+        /* Periodic live resubscribe. */
+        if (cfg.live.enabled && cfg.live.resubscribe_interval_seconds > 0 &&
+            (now - live.last_resubscribe) >= cfg.live.resubscribe_interval_seconds) {
+            cr_live_resubscribe(&live, &cfg, upstream, &followed, &sink);
+        }
+
+        /* Periodic state save (in case backfill didn't just save). */
+        if ((now - last_state_save) >= 60) {
+            if (!pg_conn) cr_config_save_state(&cfg);
+            last_state_save = now;
+        }
+
+        /* PostgreSQL: periodic status heartbeat. */
+        if (pg_conn && (now - last_status_heartbeat) >= 15) {
+            long events_fetched = live.events_received + bf.events_total;
+            long inbox_inserts  = sink.published_ok;
+            int connected = 0;
+            {
+                char **listed = NULL;
+                nostr_pool_relay_status_t *statuses = NULL;
+                int n = nostr_relay_pool_list_relays(upstream, &listed, &statuses);
+                for (int j = 0; j < n; j++) {
+                    if (statuses[j] == NOSTR_POOL_RELAY_CONNECTED) connected++;
+                }
+                free(listed);
+                free(statuses);
+            }
+            int bf_complete = 0, bf_total = 0;
+            pg_inbox_count_backfill_progress(&bf_complete, &bf_total);
+            pg_inbox_update_status("running", config_generation, (long)now,
+                                   followed.count, relay_map.selected_count,
+                                   connected, bf_complete, bf_total,
+                                   events_fetched, inbox_inserts, NULL, 0);
+            last_status_heartbeat = now;
+        }
+    }
+
+    /* Graceful shutdown. */
+ shutdown:
+     DEBUG_INFO("shutting down...");
+     cr_live_close(&live);
+     if (!pg_conn) cr_config_save_state(&cfg);
+     if (pg_conn) {
+         int bf_complete = 0, bf_total = 0;
+         pg_inbox_count_backfill_progress(&bf_complete, &bf_total);
+         pg_inbox_update_status("stopped", config_generation, (long)time(NULL),
+                                followed.count, relay_map.selected_count, 0,
+                                bf_complete, bf_total,
+                                live.events_received + bf.events_total,
+                                sink.published_ok, NULL, 0);
+     }
+     cr_sink_destroy(&sink);
+     nostr_relay_pool_destroy(upstream);
+     cr_pubkey_set_free(&followed);
+     cr_relay_map_free(&relay_map);
+     cr_config_free(&cfg);
+     if (pg_conn) pg_inbox_shutdown();
+     nostr_crypto_cleanup();
+     DEBUG_INFO("clean exit");
+     return 0;
+ }

caching/src/main.h

@@ -0,0 +1,16 @@
+/*
+ * caching_relay - main header
+ *
+ * Version information is auto-updated by increment_and_push.sh.
+ * Git tags are the source of truth for versioning.
+ */
+#ifndef CACHING_RELAY_MAIN_H
+#define CACHING_RELAY_MAIN_H
+
+// Version information (auto-updated by increment_and_push.sh)
+#define CR_VERSION_MAJOR 0
+#define CR_VERSION_MINOR 0
+#define CR_VERSION_PATCH 2
+#define CR_VERSION "v0.0.2"
+
+#endif /* CACHING_RELAY_MAIN_H */

caching/src/pg_config.c

@@ -0,0 +1,218 @@
+/*
+ * caching_relay - read caching configuration from the c-relay-pg PostgreSQL
+ * config table and populate the existing cr_config_t structure.
+ */
+#define _GNU_SOURCE
+#include "pg_config.h"
+#include "pg_inbox.h"
+#include "debug.h"
+
+#include <stdlib.h>
+#include <string.h>
+
+/* ------------------------------------------------------------------ */
+/* Helpers                                                             */
+/* ------------------------------------------------------------------ */
+
+/* Split a comma-separated string into a string array (fixed-size rows).
+ * Trims leading/trailing whitespace from each token. */
+static void split_csv_str(const char *s, char *dst, int max, int elem_len,
+                          int *count_out) {
+    int count = 0;
+    if (!s) { *count_out = 0; return; }
+
+    /* Work on a mutable copy because strtok_r modifies its input. */
+    char *copy = strdup(s);
+    if (!copy) { *count_out = 0; return; }
+
+    char *saveptr = NULL;
+    char *tok = strtok_r(copy, ",", &saveptr);
+    while (tok && count < max) {
+        /* Trim leading spaces. */
+        while (*tok == ' ' || *tok == '\t') tok++;
+        /* Trim trailing spaces. */
+        char *end = tok + strlen(tok) - 1;
+        while (end > tok && (*end == ' ' || *end == '\t' || *end == '\r' || *end == '\n')) {
+            *end-- = '\0';
+        }
+        if (*tok != '\0') {
+            strncpy(dst + count * elem_len, tok, elem_len - 1);
+            dst[count * elem_len + (elem_len - 1)] = '\0';
+            count++;
+        }
+        tok = strtok_r(NULL, ",", &saveptr);
+    }
+    free(copy);
+    *count_out = count;
+}
+
+/* Split a comma-separated string of integers into an int array. */
+static void split_csv_int(const char *s, int *dst, int max, int *count_out) {
+    int count = 0;
+    if (!s) { *count_out = 0; return; }
+
+    char *copy = strdup(s);
+    if (!copy) { *count_out = 0; return; }
+
+    char *saveptr = NULL;
+    char *tok = strtok_r(copy, ",", &saveptr);
+    while (tok && count < max) {
+        while (*tok == ' ' || *tok == '\t') tok++;
+        if (*tok != '\0') {
+            dst[count++] = atoi(tok);
+        }
+        tok = strtok_r(NULL, ",", &saveptr);
+    }
+    free(copy);
+    *count_out = count;
+}
+
+/* Split a comma-separated string of longs into a long array. */
+static void split_csv_long(const char *s, long *dst, int max, int *count_out) {
+    int count = 0;
+    if (!s) { *count_out = 0; return; }
+
+    char *copy = strdup(s);
+    if (!copy) { *count_out = 0; return; }
+
+    char *saveptr = NULL;
+    char *tok = strtok_r(copy, ",", &saveptr);
+    while (tok && count < max) {
+        while (*tok == ' ' || *tok == '\t') tok++;
+        if (*tok != '\0') {
+            dst[count++] = strtol(tok, NULL, 10);
+        }
+        tok = strtok_r(NULL, ",", &saveptr);
+    }
+    free(copy);
+    *count_out = count;
+}
+
+/* Read a config key as a freshly-allocated string. Returns NULL if missing. */
+static char *get_key(const char *key) {
+    return pg_inbox_get_config_value(key);
+}
+
+/* Read a config key as a boolean ("true"/"1"/"yes" -> 1). */
+static int get_bool(const char *key, int default_val) {
+    char *v = get_key(key);
+    if (!v) return default_val;
+    int r = (strcmp(v, "true") == 0 || strcmp(v, "1") == 0 ||
+             strcmp(v, "yes") == 0 || strcmp(v, "on") == 0);
+    free(v);
+    return r;
+}
+
+/* Read a config key as a long. */
+static long get_long(const char *key, long default_val) {
+    char *v = get_key(key);
+    if (!v) return default_val;
+    long r = strtol(v, NULL, 10);
+    free(v);
+    return r;
+}
+
+/* Read a config key as an int. */
+static int get_int(const char *key, int default_val) {
+    return (int)get_long(key, (long)default_val);
+}
+
+/* ------------------------------------------------------------------ */
+/* Public API                                                          */
+/* ------------------------------------------------------------------ */
+
+int pg_config_load(cr_config_t *cfg) {
+    if (!cfg) return -1;
+    memset(cfg, 0, sizeof(*cfg));
+
+    /* root_npubs */
+    char *npubs = get_key("caching_root_npubs");
+    split_csv_str(npubs, (char *)cfg->root_npubs, CR_MAX_ROOT_NPUBS,
+                  CR_NPUB_LEN, &cfg->root_npub_count);
+    free(npubs);
+
+    /* bootstrap_relays -> upstream_relays */
+    char *relays = get_key("caching_bootstrap_relays");
+    split_csv_str(relays, (char *)cfg->upstream_relays, CR_MAX_UPSTREAM,
+                  CR_URL_LEN, &cfg->upstream_count);
+    free(relays);
+
+    /* local_relay - no longer required for PostgreSQL mode, but keep a
+     * placeholder for compatibility. The caller may override it. */
+    cfg->local_relay[0] = '\0';
+
+    /* kinds */
+    char *kinds = get_key("caching_kinds");
+    split_csv_int(kinds, cfg->kinds, CR_MAX_KINDS, &cfg->kind_count);
+    free(kinds);
+
+    /* admin_kinds - supports "*" to mean all kinds */
+    char *akinds = get_key("caching_admin_kinds");
+    if (akinds) {
+        /* Check for "*" anywhere in the list. */
+        if (strstr(akinds, "*") != NULL) {
+            cfg->admin_all_kinds = 1;
+        } else {
+            split_csv_int(akinds, cfg->admin_kinds, CR_MAX_KINDS,
+                          &cfg->admin_kind_count);
+        }
+        free(akinds);
+    }
+
+    /* live */
+    cfg->live.enabled = get_bool("caching_live_enabled", 1);
+    cfg->live.resubscribe_interval_seconds =
+        get_int("caching_live_resubscribe_seconds", 300);
+
+    /* backfill */
+    cfg->backfill.enabled = get_bool("caching_backfill_enabled", 1);
+    cfg->backfill.events_per_tick =
+        get_int("caching_backfill_page_size", 500);
+    /* tick interval is stored in ms in the config table; convert to seconds. */
+    int tick_ms = get_int("caching_backfill_tick_interval_ms", 5000);
+    cfg->backfill.tick_interval_seconds = (tick_ms + 999) / 1000;
+    if (cfg->backfill.tick_interval_seconds < 1)
+        cfg->backfill.tick_interval_seconds = 1;
+
+    /* follow graph refresh */
+    cfg->follow_graph_refresh_seconds =
+        get_int("caching_follow_graph_refresh_seconds", 600);
+
+    /* Defaults if missing. */
+    if (cfg->backfill.events_per_tick == 0)
+        cfg->backfill.events_per_tick = 500;
+    if (cfg->backfill.tick_interval_seconds == 0)
+        cfg->backfill.tick_interval_seconds = 5;
+    if (cfg->live.resubscribe_interval_seconds == 0)
+        cfg->live.resubscribe_interval_seconds = 300;
+    if (cfg->follow_graph_refresh_seconds == 0)
+        cfg->follow_graph_refresh_seconds = 600;
+
+    /* State: per-author backfill progress lives in caching_followed_pubkeys.
+     * backfilled_until is only used as a first-time flag in legacy mode. */
+    cfg->state.backfilled_until = 0;
+
+    /* Validation. */
+    if (cfg->root_npub_count == 0) {
+        DEBUG_ERROR("pg_config: at least one caching_root_npubs required");
+        return -1;
+    }
+    if (cfg->upstream_count == 0) {
+        DEBUG_ERROR("pg_config: at least one caching_bootstrap_relays required");
+        return -1;
+    }
+    if (cfg->kind_count == 0) {
+        DEBUG_ERROR("pg_config: at least one caching_kinds required");
+        return -1;
+    }
+
+    DEBUG_INFO("pg_config loaded: %d root npubs, %d upstream relays, %d kinds",
+               cfg->root_npub_count, cfg->upstream_count, cfg->kind_count);
+    return 0;
+}
+
+int pg_config_generation_changed(long last_generation) {
+    long cur = pg_inbox_get_config_generation();
+    if (cur < 0) return -1;
+    return (cur != last_generation) ? 1 : 0;
+}

caching/src/pg_config.h

@@ -0,0 +1,19 @@
+/*
+ * caching_relay - read caching configuration from the c-relay-pg PostgreSQL
+ * config table and populate the existing cr_config_t structure.
+ */
+#ifndef CACHING_RELAY_PG_CONFIG_H
+#define CACHING_RELAY_PG_CONFIG_H
+
+#include "config.h" /* cr_config_t */
+
+/* Load caching configuration from the c-relay-pg PostgreSQL config table.
+ * Populates the cr_config_t fields from the config table.
+ * Returns 0 on success, -1 on error. */
+int pg_config_load(cr_config_t *cfg);
+
+/* Check if the config generation has changed since the last load.
+ * Returns 1 if changed, 0 if not, -1 on error. */
+int pg_config_generation_changed(long last_generation);
+
+#endif /* CACHING_RELAY_PG_CONFIG_H */

caching/src/pg_inbox.h

@@ -0,0 +1,165 @@
+/*
+ * caching_relay - PostgreSQL inbox connection and operations.
+ *
+ * Manages the libpq connection to the c-relay-pg PostgreSQL database and
+ * provides functions to insert fetched events into the caching_event_inbox
+ * table, update the caching_service_state singleton, and read configuration
+ * from the shared config table.
+ */
+#ifndef CACHING_RELAY_PG_INBOX_H
+#define CACHING_RELAY_PG_INBOX_H
+
+#include <stddef.h>
+
+/* Forward declaration so the header does not pull in cJSON everywhere. */
+typedef struct cJSON cJSON;
+
+/* Initialize PostgreSQL connection using the given connection string.
+ * Returns 0 on success, -1 on error. */
+int pg_inbox_init(const char *connection_string);
+
+/* Close the PostgreSQL connection. */
+void pg_inbox_shutdown(void);
+
+/* Insert an event into the caching_event_inbox table.
+ * event_json is the raw Nostr event JSON string.
+ * source_relay may be NULL. source_class is "live", "discovery", or "backfill".
+ * priority is 0 (live/discovery) or 1 (backfill).
+ * Returns 0 on success (including conflict-skip), -1 on error. */
+int pg_inbox_insert_event(const char *event_json, const char *source_relay,
+                          const char *source_class, int priority);
+
+/* Update the caching_service_state singleton row.
+ * All string parameters may be NULL (left unchanged).
+ * Returns 0 on success, -1 on error. */
+int pg_inbox_update_status(const char *service_state,
+                           long config_generation,
+                           long heartbeat_at,
+                           int followed_author_count,
+                           int selected_relay_count,
+                           int connected_relay_count,
+                           int backfill_authors_complete,
+                           int backfill_authors_total,
+                           long events_fetched,
+                           long inbox_inserts,
+                           const char *last_error,
+                           long last_error_at);
+
+/* Read a config value from the c-relay-pg config table.
+ * Returns a malloc'd string (caller must free) or NULL if not found/error. */
+char *pg_inbox_get_config_value(const char *key);
+
+/* Read the current config generation.
+ * Returns the generation number, or -1 on error. */
+long pg_inbox_get_config_generation(void);
+
+/* ------------------------------------------------------------------ */
+/* Per-author until-cursor drain backfill model                         */
+/* ------------------------------------------------------------------ */
+
+/* Reset all backfill progress: set until_cursor=0 and backfill_complete=FALSE
+ * for all rows in caching_followed_pubkeys (the followed set itself is
+ * preserved). Used by the "Reset Backfill" API button and --restart.
+ * Returns 0 on success, -1 on error. */
+int pg_inbox_reset_backfill_progress(void);
+
+/* Upsert all followed pubkeys into caching_followed_pubkeys.
+ * For each pubkey: INSERT if new (until_cursor=0, backfill_complete=FALSE),
+ * or UPDATE is_root and last_seen if existing (until_cursor and
+ * backfill_complete are NOT touched). root_pubkeys marks which entries are
+ * root follows. Returns 0 on success, -1 on error. */
+int pg_inbox_sync_followed_pubkeys(const char **pubkeys, int count,
+                                    const char **root_pubkeys, int root_count);
+
+/* Pick the next incomplete author for backfill, round-robin.
+ * On success fills out_pk, out_until_cursor and out_is_root, advances
+ * *round_cursor, and returns 0. Returns -1 if no incomplete authors or
+ * on error. */
+int pg_inbox_pick_next_backfill_author(char *out_pk, int pk_len,
+                                        long *out_until_cursor,
+                                        int *out_is_root,
+                                        int *round_cursor);
+
+/* Update the cursor and completion state for an author.
+ * events_this_page is added to the running events_fetched counter.
+ * Returns 0 on success, -1 on error. */
+int pg_inbox_update_backfill_progress(const char *pk, long until_cursor,
+                                       int complete, int events_this_page);
+
+/* One-time migration from the old caching_backfill_progress table to the
+ * new caching_followed_pubkeys table. Only runs if the new table is empty
+ * and the old table has rows. Returns 0 on success (including no-op),
+ * -1 on error. */
+int pg_inbox_migrate_backfill_progress(void);
+
+/* Count complete/total authors for status reporting.
+ * Returns 0 on success, -1 on error. */
+int pg_inbox_count_backfill_progress(int *out_complete, int *out_total);
+
+/* ------------------------------------------------------------------ */
+/* Per-relay backfill progress (relay-by-relay drain model)            */
+/* ------------------------------------------------------------------ */
+
+/* Initialize relay progress rows for an author. Creates one row per relay
+ * URL with until_cursor=0, complete=FALSE. Skips rows that already exist
+ * (ON CONFLICT DO NOTHING). Returns 0 on success, -1 on error. */
+int pg_inbox_init_relay_progress_for_author(const char *pk,
+                                             const char **relay_urls,
+                                             int relay_count);
+
+/* Pick the next author that has at least one incomplete relay progress row.
+ * Round-robin via *round_cursor. On success fills out_pk and returns 0.
+ * Returns -1 if no incomplete authors or on error. */
+int pg_inbox_pick_next_author_with_incomplete_relays(char *out_pk, int pk_len,
+                                                       int *round_cursor);
+
+/* Get incomplete relays for an author. Returns a cJSON array of
+ * {relay_url, until_cursor} objects (caller frees with cJSON_Delete).
+ * Returns NULL on error or if no incomplete relays. */
+cJSON *pg_inbox_get_incomplete_relays(const char *pk);
+
+/* Update relay progress: advance cursor and/or mark complete.
+ * events_this_page is added to the running events_fetched counter.
+ * last_status is a short string like "eose", "timeout", "error", or NULL
+ * to leave unchanged. Returns 0 on success, -1 on error. */
+int pg_inbox_update_relay_progress(const char *pk, const char *relay_url,
+                                    long until_cursor, int complete,
+                                    int events_this_page,
+                                    const char *last_status);
+
+/* Check if all relays for an author are complete. If so, mark the author
+ * as backfill_complete=TRUE in caching_followed_pubkeys.
+ * Returns 1 if marked complete, 0 if still incomplete, -1 on error. */
+int pg_inbox_check_and_mark_author_complete(const char *pk);
+
+/* ------------------------------------------------------------------ */
+/* Active backfill target (for UI status display)                     */
+/* ------------------------------------------------------------------ */
+
+/* Set the currently-active backfill target (pubkey + relay being queried).
+ * Either parameter may be NULL/empty to clear. Creates the
+ * caching_backfill_active table if needed (single-row singleton).
+ * Returns 0 on success, -1 on error. */
+int pg_inbox_set_active_target(const char *pubkey, const char *relay_url);
+
+/* Read the active backfill target. Fills out_pubkey/out_relay with
+ * the current values (or empty strings if none). Buffers must be
+ * at least 65 and 256 bytes respectively.
+ * Returns 0 on success, -1 on error. */
+int pg_inbox_get_active_target(char *out_pubkey, int pk_len,
+                                char *out_relay, int relay_len);
+
+/* ------------------------------------------------------------------ */
+/* Forward catch-up support (last_event_at tracking)                  */
+/* ------------------------------------------------------------------ */
+
+/* Returns a cJSON array of {pubkey, last_event_at} objects for all
+ * followed authors where last_event_at > 0. Caller must cJSON_Delete().
+ * Returns NULL on error. */
+cJSON* pg_inbox_get_authors_for_catchup(void);
+
+/* Update last_event_at for a pubkey to the GREATEST of current and
+ * the given value. Returns 0 on success, -1 on error. */
+int pg_inbox_update_last_event_at(const char *pk, long event_created_at);
+
+#endif /* CACHING_RELAY_PG_INBOX_H */

caching/src/relay_discovery.c

@@ -0,0 +1,561 @@
+/*
+ * caching_relay - NIP-65 outbox relay discovery
+ */
+#define _GNU_SOURCE
+#include "relay_discovery.h"
+#include "debug.h"
+
+#include <string.h>
+#include <stdlib.h>
+#include <signal.h>
+
+/* Access the shutdown flag from main.c so we can abort discovery early. */
+extern volatile sig_atomic_t g_shutdown;
+
+/* Normalize a relay URL: strip trailing slash for consistency. */
+static void normalize_url(char *url, size_t maxlen) {
+    size_t len = strlen(url);
+    while (len > 0 && url[len - 1] == '/') {
+        url[--len] = '\0';
+    }
+    (void)maxlen;
+}
+
+/* ---- helpers ---- */
+
+static int get_pool_urls(nostr_relay_pool_t *pool, const char ***urls_out) {
+    char **listed = NULL;
+    nostr_pool_relay_status_t *statuses = NULL;
+    int n = nostr_relay_pool_list_relays(pool, &listed, &statuses);
+    const char **urls = NULL;
+    if (n > 0) {
+        urls = malloc(n * sizeof(char *));
+        for (int j = 0; j < n; j++) urls[j] = listed[j];
+    }
+    free(listed);
+    free(statuses);
+    *urls_out = urls;
+    return n;
+}
+
+/* Query the most recent kind 10002 for a single pubkey from a pool.
+ * Returns the event (caller must cJSON_Delete) or NULL. */
+static cJSON *query_kind10002(nostr_relay_pool_t *pool, const char *hex) {
+    cJSON *filter = cJSON_CreateObject();
+    cJSON *authors = cJSON_CreateArray();
+    cJSON_AddItemToArray(authors, cJSON_CreateString(hex));
+    cJSON_AddItemToObject(filter, "authors", authors);
+    cJSON *kinds = cJSON_CreateArray();
+    cJSON_AddItemToArray(kinds, cJSON_CreateNumber(10002));
+    cJSON_AddItemToObject(filter, "kinds", kinds);
+    cJSON_AddItemToObject(filter, "limit", cJSON_CreateNumber(1));
+
+    const char **urls = NULL;
+    int n = get_pool_urls(pool, &urls);
+    int ev_count = 0;
+    cJSON **events = nostr_relay_pool_query_sync(pool, urls, n, filter, &ev_count, 10000);
+    free(urls);
+    cJSON_Delete(filter);
+
+    cJSON *result = NULL;
+    if (events && ev_count > 0) {
+        result = events[0]; /* take first (most recent) */
+        for (int k = 1; k < ev_count; k++) cJSON_Delete(events[k]);
+    }
+    free(events);
+    return result;
+}
+
+/* Parse "r" tags from a kind 10002 event into an outbox entry.
+ * Only includes relays with "read" marker or no marker (assume both).
+ * Skips "write" only relays. */
+static int parse_r_tags(cJSON *event, cr_outbox_entry_t *entry) {
+    memset(entry, 0, sizeof(*entry));
+    cJSON *pubkey = cJSON_GetObjectItem(event, "pubkey");
+    if (pubkey && cJSON_IsString(pubkey)) {
+        strncpy(entry->pubkey, cJSON_GetStringValue(pubkey), CR_HEX_LEN - 1);
+    }
+
+    cJSON *tags = cJSON_GetObjectItem(event, "tags");
+    if (!tags || !cJSON_IsArray(tags)) return 0;
+
+    int added = 0;
+    cJSON *tag;
+    cJSON_ArrayForEach(tag, tags) {
+        if (!cJSON_IsArray(tag)) continue;
+        cJSON *name = cJSON_GetArrayItem(tag, 0);
+        if (!name || !cJSON_IsString(name)) continue;
+        if (strcmp(cJSON_GetStringValue(name), "r") != 0) continue;
+        cJSON *url = cJSON_GetArrayItem(tag, 1);
+        if (!url || !cJSON_IsString(url)) continue;
+        const char *relay_url = cJSON_GetStringValue(url);
+        if (!relay_url || !relay_url[0]) continue;
+
+        /* Check marker (3rd element): "read", "write", or absent. */
+        cJSON *marker = cJSON_GetArrayItem(tag, 2);
+        if (marker && cJSON_IsString(marker)) {
+            const char *m = cJSON_GetStringValue(marker);
+            if (strcmp(m, "write") == 0) continue; /* skip write-only relays */
+        }
+        /* No marker or "read" => include. */
+
+        if (entry->relay_count >= CR_MAX_RELAYS_PER_PUBKEY) break;
+        strncpy(entry->relays[entry->relay_count], relay_url, CR_URL_LEN - 1);
+        entry->relays[entry->relay_count][CR_URL_LEN - 1] = '\0';
+        normalize_url(entry->relays[entry->relay_count], CR_URL_LEN);
+        entry->relay_count++;
+        added++;
+    }
+    return added;
+}
+
+/* ---- greedy set cover ---- */
+
+/* Build relay -> pubkey coverage map and compute minimum covering set. */
+static void compute_covering_set(cr_relay_map_t *map, cr_config_t *cfg,
+                                 const cr_pubkey_set_t *followed) {
+    /* Build a temporary relay -> pubkeys map. */
+    typedef struct {
+        char url[CR_URL_LEN];
+        char pubkeys[CR_MAX_PUBKEYS_PER_RELAY][CR_HEX_LEN];
+        int  pubkey_count;
+    } relay_cov_t;
+
+    relay_cov_t *relays = calloc(CR_MAX_DISCOVERED_RELAYS, sizeof(relay_cov_t));
+    int relay_count = 0;
+
+    /* Always include bootstrap relays in the coverage map. */
+    for (int i = 0; i < cfg->upstream_count && relay_count < CR_MAX_DISCOVERED_RELAYS; i++) {
+        strncpy(relays[relay_count].url, cfg->upstream_relays[i], CR_URL_LEN - 1);
+        relays[relay_count].url[CR_URL_LEN - 1] = '\0';
+        normalize_url(relays[relay_count].url, CR_URL_LEN);
+        relay_count++;
+    }
+
+    /* Add outbox relays and build coverage. */
+    for (int i = 0; i < map->outbox_count; i++) {
+        cr_outbox_entry_t *oe = &map->outboxes[i];
+        for (int r = 0; r < oe->relay_count; r++) {
+            /* Find or create relay entry. */
+            int found = -1;
+            for (int j = 0; j < relay_count; j++) {
+                if (strcmp(relays[j].url, oe->relays[r]) == 0) { found = j; break; }
+            }
+            if (found < 0) {
+                if (relay_count >= CR_MAX_DISCOVERED_RELAYS) break;
+                strncpy(relays[relay_count].url, oe->relays[r], CR_URL_LEN - 1);
+                found = relay_count++;
+            }
+            /* Add this pubkey to the relay's coverage. */
+            if (relays[found].pubkey_count < CR_MAX_PUBKEYS_PER_RELAY) {
+                strncpy(relays[found].pubkeys[relays[found].pubkey_count],
+                        oe->pubkey, CR_HEX_LEN - 1);
+                relays[found].pubkey_count++;
+            }
+        }
+    }
+
+    /* Greedy set cover. */
+    char *covered = calloc(followed->count, 1); /* 1 if pubkey is covered */
+    map->selected_count = 0;
+    map->coverage = calloc(map->outbox_count, sizeof(int));
+    for (int i = 0; i < map->outbox_count; i++) map->coverage[i] = -1;
+
+    int uncovered_count = followed->count;
+
+    /* Helper: find index of a pubkey in the followed set. */
+    /* (linear search, fine for our scale) */
+
+    while (uncovered_count > 0 && map->selected_count < CR_MAX_DISCOVERED_RELAYS) {
+        int best_relay = -1;
+        int best_count = 0;
+
+        for (int r = 0; r < relay_count; r++) {
+            /* Count how many uncovered pubkeys this relay covers. */
+            int count = 0;
+            for (int p = 0; p < relays[r].pubkey_count; p++) {
+                /* Find this pubkey in followed set. */
+                for (int i = 0; i < followed->count; i++) {
+                    if (strcmp(followed->items[i], relays[r].pubkeys[p]) == 0) {
+                        if (!covered[i]) count++;
+                        break;
+                    }
+                }
+            }
+            if (count > best_count) {
+                best_count = count;
+                best_relay = r;
+            }
+        }
+
+        if (best_relay < 0 || best_count == 0) break; /* no more coverage possible */
+
+        /* Select this relay. */
+        strncpy(map->selected_relays[map->selected_count],
+                relays[best_relay].url, CR_URL_LEN - 1);
+        map->selected_count++;
+
+        /* Mark covered pubkeys and record coverage. */
+        for (int p = 0; p < relays[best_relay].pubkey_count; p++) {
+            for (int i = 0; i < followed->count; i++) {
+                if (strcmp(followed->items[i], relays[best_relay].pubkeys[p]) == 0) {
+                    if (!covered[i]) {
+                        covered[i] = 1;
+                        uncovered_count--;
+                        /* Record which selected relay covers this outbox entry. */
+                        for (int oe_i = 0; oe_i < map->outbox_count; oe_i++) {
+                            if (strcmp(map->outboxes[oe_i].pubkey,
+                                       relays[best_relay].pubkeys[p]) == 0) {
+                                if (map->coverage[oe_i] < 0) {
+                                    map->coverage[oe_i] = map->selected_count - 1;
+                                }
+                            }
+                        }
+                    }
+                    break;
+                }
+            }
+        }
+    }
+
+    /* Log results. */
+    DEBUG_INFO("relay_discovery: selected %d relays to cover %d/%d pubkeys",
+                map->selected_count, followed->count - uncovered_count, followed->count);
+    for (int i = 0; i < map->selected_count; i++) {
+        DEBUG_INFO("  relay[%d]: %s", i, map->selected_relays[i]);
+    }
+    if (uncovered_count > 0) {
+        DEBUG_WARN("relay_discovery: %d pubkeys have no outbox relays (covered by bootstrap)",
+                    uncovered_count);
+    }
+
+    free(covered);
+    free(relays);
+}
+
+/* ---- batched kind-10002 query ---- */
+
+/* Query kind 10002 for a batch of up to 100 pubkeys from a pool.
+ * Returns a cJSON array of events (caller must cJSON_Delete each + free).
+ * Sets *out_count to the number of events returned. */
+static cJSON **query_kind10002_batch(nostr_relay_pool_t *pool,
+                                      const char **pubkeys, int pubkey_count,
+                                      int *out_count) {
+    cJSON *filter = cJSON_CreateObject();
+    cJSON *authors = cJSON_CreateArray();
+    for (int i = 0; i < pubkey_count; i++)
+        cJSON_AddItemToArray(authors, cJSON_CreateString(pubkeys[i]));
+    cJSON_AddItemToObject(filter, "authors", authors);
+    cJSON *kinds = cJSON_CreateArray();
+    cJSON_AddItemToArray(kinds, cJSON_CreateNumber(10002));
+    cJSON_AddItemToObject(filter, "kinds", kinds);
+
+    const char **urls = NULL;
+    int n = get_pool_urls(pool, &urls);
+
+    /* TRACE: log the query being sent. */
+    if (g_debug_level >= DEBUG_LEVEL_TRACE) {
+        char *filter_str = cJSON_PrintUnformatted(filter);
+        DEBUG_TRACE("query_kind10002_batch: querying %d relays for %d pubkeys", n, pubkey_count);
+        if (filter_str) {
+            /* Only print first 200 chars of filter to avoid huge output */
+            if (strlen(filter_str) > 200) filter_str[200] = '\0';
+            DEBUG_TRACE("  filter: %s...", filter_str);
+            free(filter_str);
+        }
+    }
+
+    int ev_count = 0;
+    cJSON **events = nostr_relay_pool_query_sync(pool, urls, n, filter, &ev_count, 30000);
+    free(urls);
+    cJSON_Delete(filter);
+
+    DEBUG_TRACE("query_kind10002_batch: returned %d events", ev_count);
+
+    *out_count = ev_count;
+    return events;
+}
+
+/* ---- batched kind-3 fallback query ---- */
+
+/* Query kind 3 (contact list) for a batch of pubkeys from a pool.
+ * Kind-3 events historically contain "r" tags with relay URLs (pre-NIP-65).
+ * We use this as a fallback for pubkeys that don't have kind-10002.
+ * Returns a cJSON array of events (caller must cJSON_Delete each + free).
+ * Sets *out_count to the number of events returned. */
+static cJSON **query_kind3_batch(nostr_relay_pool_t *pool,
+                                  const char **pubkeys, int pubkey_count,
+                                  int *out_count) {
+    cJSON *filter = cJSON_CreateObject();
+    cJSON *authors = cJSON_CreateArray();
+    for (int i = 0; i < pubkey_count; i++)
+        cJSON_AddItemToArray(authors, cJSON_CreateString(pubkeys[i]));
+    cJSON_AddItemToObject(filter, "authors", authors);
+    cJSON *kinds = cJSON_CreateArray();
+    cJSON_AddItemToArray(kinds, cJSON_CreateNumber(3));
+    cJSON_AddItemToObject(filter, "kinds", kinds);
+    /* limit=1 per author: we only need the most recent kind-3.
+     * The relay pool query_sync returns the most recent events. */
+    cJSON_AddItemToObject(filter, "limit", cJSON_CreateNumber(pubkey_count));
+
+    const char **urls = NULL;
+    int n = get_pool_urls(pool, &urls);
+
+    DEBUG_TRACE("query_kind3_batch: querying %d relays for %d pubkeys", n, pubkey_count);
+
+    int ev_count = 0;
+    cJSON **events = nostr_relay_pool_query_sync(pool, urls, n, filter, &ev_count, 30000);
+    free(urls);
+    cJSON_Delete(filter);
+
+    DEBUG_TRACE("query_kind3_batch: returned %d events", ev_count);
+
+    *out_count = ev_count;
+    return events;
+}
+
+/* Process a batch of kind-10002 events: parse r-tags, populate outbox entries,
+ * publish to local relay. Returns count of events processed. */
+static int process_10002_batch(cJSON **events, int ev_count,
+                               cr_relay_map_t *map, cr_sink_t *sink,
+                               const char *source) {
+    int processed = 0;
+    for (int k = 0; k < ev_count; k++) {
+        cJSON *event = events[k];
+        if (!event) continue;
+
+        /* Get pubkey from event. */
+        cJSON *pk = cJSON_GetObjectItem(event, "pubkey");
+        if (!pk || !cJSON_IsString(pk)) { cJSON_Delete(event); continue; }
+        const char *hex = cJSON_GetStringValue(pk);
+
+        /* Find or create outbox entry for this pubkey. */
+        cr_outbox_entry_t *oe = NULL;
+        for (int i = 0; i < map->outbox_count; i++) {
+            if (strcmp(map->outboxes[i].pubkey, hex) == 0) { oe = &map->outboxes[i]; break; }
+        }
+        if (!oe) {
+            if (map->outbox_count >= /* followed->count passed in via map size */ 99999) {
+                cJSON_Delete(event); continue;
+            }
+            oe = &map->outboxes[map->outbox_count];
+            strncpy(oe->pubkey, hex, CR_HEX_LEN - 1);
+            map->outbox_count++;
+        }
+
+        int n = parse_r_tags(event, oe);
+        (void)n;
+
+        if (strcmp(source, "bootstrap") == 0) {
+            cr_sink_publish(sink, event);
+            /* Pump sink pool every 16 events to avoid pending publish overflow
+             * (NOSTR_POOL_MAX_PENDING_PUBLISHES = 32). */
+            if (processed > 0 && (processed % 16) == 0) {
+                cr_sink_pump(sink, 200);
+            }
+        }
+
+        processed++;
+        cJSON_Delete(event);
+    }
+    free(events);
+
+    /* Log sink stats after each batch. */
+    DEBUG_INFO("relay_discovery: batch processed %d events (sink: ok=%ld reject=%ld dup=%ld err=%ld)",
+               processed, sink->published_ok, sink->published_failed,
+               sink->published_dup, 0L);
+
+    return processed;
+}
+
+/* ---- main discovery function ---- */
+
+#define CR_10002_BATCH_SIZE 100
+
+int cr_relay_discovery_run(cr_relay_map_t *map, cr_config_t *cfg,
+                           nostr_relay_pool_t *upstream, cr_sink_t *sink,
+                           const cr_pubkey_set_t *followed, int is_first_time) {
+    memset(map, 0, sizeof(*map));
+    map->outboxes = calloc(followed->count, sizeof(cr_outbox_entry_t));
+    if (!map->outboxes) return -1;
+    map->outbox_count = 0;
+
+    DEBUG_INFO("relay_discovery: discovering outbox relays for %d pubkeys (%s)",
+                followed->count, is_first_time ? "first-time" : "local-first");
+
+    int found_local = 0, found_bootstrap = 0, found_none = 0;
+
+    /* Pre-populate outbox entries for all followed pubkeys (empty, for coverage
+     * tracking of pubkeys with no 10002). */
+    for (int i = 0; i < followed->count; i++) {
+        strncpy(map->outboxes[i].pubkey, followed->items[i], CR_HEX_LEN - 1);
+    }
+    map->outbox_count = followed->count;
+
+    /* Track which pubkeys we've found 10002 for. */
+    char *found = calloc(followed->count, 1);
+
+    /* Phase 1: If subsequent startup, batch-query local relay first. */
+    if (!is_first_time && sink && sink->pool) {
+        DEBUG_INFO("relay_discovery: querying local relay for kind-10002 (batched)...");
+
+        for (int start = 0; start < followed->count && !g_shutdown; start += CR_10002_BATCH_SIZE) {
+            int batch = followed->count - start;
+            if (batch > CR_10002_BATCH_SIZE) batch = CR_10002_BATCH_SIZE;
+
+            int ev_count = 0;
+            cJSON **events = query_kind10002_batch(sink->pool,
+                                                   (const char **)&followed->items[start],
+                                                   batch, &ev_count);
+            if (events && ev_count > 0) {
+                for (int k = 0; k < ev_count; k++) {
+                    cJSON *pk = cJSON_GetObjectItem(events[k], "pubkey");
+                    if (pk && cJSON_IsString(pk)) {
+                        const char *hex = cJSON_GetStringValue(pk);
+                        for (int i = 0; i < followed->count; i++) {
+                            if (strcmp(followed->items[i], hex) == 0) {
+                                if (!found[i]) { found[i] = 1; found_local++; }
+                                break;
+                            }
+                        }
+                    }
+                }
+                process_10002_batch(events, ev_count, map, sink, "local");
+                /* Pump sink pool to flush published events. */
+                cr_sink_pump(sink, 500);
+            } else {
+                free(events);
+            }
+        }
+        DEBUG_INFO("relay_discovery: local relay provided %d kind-10002 events", found_local);
+    }
+
+    /* Phase 2: Batch-query bootstrap relays for pubkeys not found locally. */
+    int remaining = 0;
+    for (int i = 0; i < followed->count; i++) if (!found[i]) remaining++;
+
+    if (remaining > 0) {
+        DEBUG_INFO("relay_discovery: querying bootstrap relays for %d remaining pubkeys (batched)...",
+                    remaining);
+
+        /* Build list of remaining pubkeys. */
+        const char **remaining_pk = malloc(remaining * sizeof(char *));
+        int ridx = 0;
+        for (int i = 0; i < followed->count; i++) {
+            if (!found[i]) remaining_pk[ridx++] = followed->items[i];
+        }
+
+        for (int start = 0; start < remaining && !g_shutdown; start += CR_10002_BATCH_SIZE) {
+            int batch = remaining - start;
+            if (batch > CR_10002_BATCH_SIZE) batch = CR_10002_BATCH_SIZE;
+
+            int ev_count = 0;
+            cJSON **events = query_kind10002_batch(upstream,
+                                                   &remaining_pk[start],
+                                                   batch, &ev_count);
+            if (events && ev_count > 0) {
+                for (int k = 0; k < ev_count; k++) {
+                    cJSON *pk = cJSON_GetObjectItem(events[k], "pubkey");
+                    if (pk && cJSON_IsString(pk)) {
+                        const char *hex = cJSON_GetStringValue(pk);
+                        for (int i = 0; i < followed->count; i++) {
+                            if (strcmp(followed->items[i], hex) == 0) {
+                                if (!found[i]) { found[i] = 1; found_bootstrap++; }
+                                break;
+                            }
+                        }
+                    }
+                }
+                process_10002_batch(events, ev_count, map, sink, "bootstrap");
+                /* Pump sink pool to flush published events. */
+                cr_sink_pump(sink, 500);
+            } else {
+                free(events);
+            }
+        }
+        free(remaining_pk);
+    }
+
+    /* Phase 3: Kind-3 fallback for pubkeys still without relay lists.
+     * Kind-3 (contact list) events historically contain "r" tags with relay
+     * URLs (pre-NIP-65). This catches older users who never published kind-10002. */
+    int remaining_k3 = 0;
+    for (int i = 0; i < followed->count; i++) if (!found[i]) remaining_k3++;
+
+    if (remaining_k3 > 0) {
+        DEBUG_INFO("relay_discovery: querying bootstrap relays for kind-3 fallback (%d pubkeys)...",
+                    remaining_k3);
+
+        const char **remaining_pk = malloc(remaining_k3 * sizeof(char *));
+        int ridx = 0;
+        for (int i = 0; i < followed->count; i++) {
+            if (!found[i]) remaining_pk[ridx++] = followed->items[i];
+        }
+
+        int found_k3 = 0;
+        for (int start = 0; start < remaining_k3 && !g_shutdown; start += CR_10002_BATCH_SIZE) {
+            int batch = remaining_k3 - start;
+            if (batch > CR_10002_BATCH_SIZE) batch = CR_10002_BATCH_SIZE;
+
+            int ev_count = 0;
+            cJSON **events = query_kind3_batch(upstream,
+                                                &remaining_pk[start],
+                                                batch, &ev_count);
+            if (events && ev_count > 0) {
+                for (int k = 0; k < ev_count; k++) {
+                    cJSON *pk = cJSON_GetObjectItem(events[k], "pubkey");
+                    if (pk && cJSON_IsString(pk)) {
+                        const char *hex = cJSON_GetStringValue(pk);
+                        for (int i = 0; i < followed->count; i++) {
+                            if (strcmp(followed->items[i], hex) == 0) {
+                                if (!found[i]) { found[i] = 1; found_k3++; }
+                                break;
+                            }
+                        }
+                    }
+                }
+                /* process_10002_batch works for kind-3 too — same r-tag format */
+                process_10002_batch(events, ev_count, map, sink, "bootstrap");
+                cr_sink_pump(sink, 500);
+            } else {
+                free(events);
+            }
+        }
+        free(remaining_pk);
+        DEBUG_INFO("relay_discovery: kind-3 fallback found %d additional pubkeys with relays", found_k3);
+    }
+
+    found_none = followed->count - found_local - found_bootstrap;
+    /* Recalculate found_none after kind-3 fallback */
+    int still_none = 0;
+    for (int i = 0; i < followed->count; i++) if (!found[i]) still_none++;
+    DEBUG_INFO("relay_discovery: %d local, %d bootstrap, %d none",
+                found_local, found_bootstrap, still_none);
+
+    free(found);
+
+    /* Compute minimum covering set. */
+    compute_covering_set(map, cfg, followed);
+
+    return 0;
+}
+
+void cr_relay_map_free(cr_relay_map_t *map) {
+    if (map->outboxes) {
+        free(map->outboxes);
+        map->outboxes = NULL;
+    }
+    if (map->coverage) {
+        free(map->coverage);
+        map->coverage = NULL;
+    }
+    map->outbox_count = 0;
+    map->selected_count = 0;
+}
+
+const cr_outbox_entry_t *cr_relay_map_get_outbox(const cr_relay_map_t *map, const char *hex) {
+    for (int i = 0; i < map->outbox_count; i++) {
+        if (strcmp(map->outboxes[i].pubkey, hex) == 0) return &map->outboxes[i];
+    }
+    return NULL;
+}

caching/src/relay_discovery.h

@@ -0,0 +1,67 @@
+/*
+ * caching_relay - NIP-65 outbox relay discovery.
+ *
+ * For each followed pubkey, fetches their kind 10002 (relay list) and parses
+ * the "r" tags to build a per-pubkey outbox relay map. Then computes the
+ * minimum covering set of relays (greedy set cover) that covers all followed
+ * pubkeys.
+ *
+ * On first-time startup, queries bootstrap relays for kind 10002.
+ * On subsequent startups, queries the local relay first (fast), falls back
+ * to bootstrap relays for any pubkey not found locally.
+ */
+#ifndef CACHING_RELAY_RELAY_DISCOVERY_H
+#define CACHING_RELAY_RELAY_DISCOVERY_H
+
+#include "config.h"
+#include "state.h"
+#include "relay_sink.h"
+#include "../nostr_core_lib/nostr_core/nostr_core.h"
+
+#define CR_MAX_RELAYS_PER_PUBKEY  8
+#define CR_MAX_PUBKEYS_PER_RELAY  512
+#define CR_MAX_DISCOVERED_RELAYS  128
+
+/* Per-pubkey outbox relay list. */
+typedef struct {
+    char pubkey[CR_HEX_LEN];
+    char relays[CR_MAX_RELAYS_PER_PUBKEY][CR_URL_LEN];
+    int  relay_count;
+} cr_outbox_entry_t;
+
+/* Result of relay discovery. */
+typedef struct {
+    cr_outbox_entry_t *outboxes;      /* per-pubkey relay lists (heap) */
+    int                outbox_count;
+
+    /* The selected minimum covering set of relay URLs. */
+    char               selected_relays[CR_MAX_DISCOVERED_RELAYS][CR_URL_LEN];
+    int                selected_count;
+
+    /* Per-pubkey: which selected relay covers this pubkey (index into selected_relays).
+     * -1 means covered by bootstrap relays only. */
+    int               *coverage;      /* heap, outbox_count entries */
+} cr_relay_map_t;
+
+/* Discover outbox relays for all followed pubkeys.
+ *
+ *   cfg       - config (provides bootstrap relays, local_relay, root_hex)
+ *   upstream  - upstream pool (has bootstrap relays; discovered relays will be added)
+ *   sink      - sink pool (local relay, for publishing 10002 events + querying on subsequent startup)
+ *   followed  - the followed pubkey set
+ *   is_first_time - 1 if first startup (query bootstrap only), 0 if subsequent (local-first)
+ *
+ * Returns 0 on success, -1 on hard error. On success, map is populated.
+ * Caller must call cr_relay_map_free() when done.
+ */
+int  cr_relay_discovery_run(cr_relay_map_t *map, cr_config_t *cfg,
+                            nostr_relay_pool_t *upstream, cr_sink_t *sink,
+                            const cr_pubkey_set_t *followed, int is_first_time);
+
+/* Free heap resources in a relay map. */
+void cr_relay_map_free(cr_relay_map_t *map);
+
+/* Get the outbox relays for a specific pubkey. Returns NULL if not found. */
+const cr_outbox_entry_t *cr_relay_map_get_outbox(const cr_relay_map_t *map, const char *hex);
+
+#endif /* CACHING_RELAY_RELAY_DISCOVERY_H */

caching/src/relay_sink.c

@@ -0,0 +1,161 @@
+/*
+ * caching_relay - relay sink: publishes fetched events to the local relay.
+ *
+ * See relay_sink.h for the dual-mode (WebSocket / PostgreSQL inbox) design.
+ */
+#define _GNU_SOURCE
+#include "relay_sink.h"
+#include "pg_inbox.h"
+#include "debug.h"
+
+#include <string.h>
+#include <stdlib.h>
+
+/* ------------------------------------------------------------------ */
+/* WebSocket mode callback                                             */
+/* ------------------------------------------------------------------ */
+
+static void sink_publish_cb(const char *relay_url, const char *event_id,
+                             int success, const char *message, void *user_data) {
+    cr_sink_t *sink = (cr_sink_t *)user_data;
+    if (success) {
+        sink->published_ok++;
+        DEBUG_TRACE("sink: OK %s from %s", event_id ? event_id : "?",
+                    relay_url ? relay_url : "?");
+    } else {
+        sink->published_failed++;
+        /* REJECT is important - show at INFO level so it's visible at level 3. */
+        DEBUG_INFO("sink: REJECT %s from %s: %s", event_id ? event_id : "?",
+                    relay_url ? relay_url : "?",
+                    message ? message : "(no message)");
+    }
+}
+
+/* ------------------------------------------------------------------ */
+/* Init                                                                */
+/* ------------------------------------------------------------------ */
+
+int cr_sink_init(cr_sink_t *sink, const char *local_relay_url, cr_seen_ring_t *seen) {
+    memset(sink, 0, sizeof(*sink));
+    sink->seen = seen;
+    sink->source_class = CR_SINK_CLASS_LIVE;
+    strncpy(sink->url, local_relay_url, sizeof(sink->url) - 1);
+
+    sink->pool = nostr_relay_pool_create(nostr_pool_reconnect_config_default());
+    if (!sink->pool) {
+        DEBUG_ERROR("sink: failed to create pool");
+        return -1;
+    }
+    if (nostr_relay_pool_add_relay(sink->pool, local_relay_url) != NOSTR_SUCCESS) {
+        DEBUG_ERROR("sink: failed to add relay %s", local_relay_url);
+        nostr_relay_pool_destroy(sink->pool);
+        sink->pool = NULL;
+        return -1;
+    }
+    DEBUG_INFO("sink: initialized (WebSocket) for %s", local_relay_url);
+    return 0;
+}
+
+int cr_sink_init_pg(cr_sink_t *sink, cr_seen_ring_t *seen) {
+    memset(sink, 0, sizeof(*sink));
+    sink->seen = seen;
+    sink->source_class = CR_SINK_CLASS_LIVE;
+    sink->pool = NULL; /* PostgreSQL inbox mode - no WebSocket pool. */
+    DEBUG_INFO("sink: initialized (PostgreSQL inbox)");
+    return 0;
+}
+
+void cr_sink_set_source_class(cr_sink_t *sink, const char *class_ptr) {
+    if (sink) sink->source_class = class_ptr ? class_ptr : CR_SINK_CLASS_LIVE;
+}
+
+void cr_sink_destroy(cr_sink_t *sink) {
+    if (sink && sink->pool) {
+        nostr_relay_pool_destroy(sink->pool);
+        sink->pool = NULL;
+    }
+}
+
+/* ------------------------------------------------------------------ */
+/* Publish                                                             */
+/* ------------------------------------------------------------------ */
+
+int cr_sink_publish_from(cr_sink_t *sink, cJSON *event, const char *source_relay) {
+    if (!sink || !event) return -1;
+
+    cJSON *id = cJSON_GetObjectItem(event, "id");
+    if (!id || !cJSON_IsString(id)) {
+        DEBUG_WARN("sink: event missing id, skipping");
+        return -1;
+    }
+    const char *eid = cJSON_GetStringValue(id);
+
+    if (cr_seen_ring_add(sink->seen, eid) == 0) {
+        sink->published_dup++;
+        return 0; /* already seen recently */
+    }
+
+    /* PostgreSQL inbox mode. */
+    if (!sink->pool) {
+        char *json = cJSON_PrintUnformatted(event);
+        if (!json) {
+            DEBUG_WARN("sink: failed to serialize event %s", eid);
+            sink->published_failed++;
+            return -1;
+        }
+        const char *klass = sink->source_class ? sink->source_class
+                                               : CR_SINK_CLASS_LIVE;
+        int priority = (strcmp(klass, CR_SINK_CLASS_BACKFILL) == 0) ? 1 : 0;
+
+        cJSON *kind = cJSON_GetObjectItem(event, "kind");
+        cJSON *pubkey = cJSON_GetObjectItem(event, "pubkey");
+        int kind_num = (kind && cJSON_IsNumber(kind)) ? (int)cJSON_GetNumberValue(kind) : -1;
+        DEBUG_TRACE("sink: INBOX event id=%s kind=%d pubkey=%s class=%s",
+                    eid, kind_num,
+                    pubkey && cJSON_IsString(pubkey) ? cJSON_GetStringValue(pubkey) : "?",
+                    klass);
+
+        int rc = pg_inbox_insert_event(json, source_relay, klass, priority);
+        free(json);
+        if (rc != 0) {
+            sink->published_failed++;
+            return -1;
+        }
+        sink->published_ok++;
+        return 1;
+    }
+
+    /* WebSocket mode. */
+    const char *urls[1] = { sink->url };
+    cJSON *kind = cJSON_GetObjectItem(event, "kind");
+    cJSON *pubkey = cJSON_GetObjectItem(event, "pubkey");
+    int kind_num = (kind && cJSON_IsNumber(kind)) ? (int)cJSON_GetNumberValue(kind) : -1;
+    DEBUG_TRACE("sink: SEND event id=%s kind=%d pubkey=%s to %s",
+                eid, kind_num,
+                pubkey && cJSON_IsString(pubkey) ? cJSON_GetStringValue(pubkey) : "?",
+                sink->url);
+
+    int rc = nostr_relay_pool_publish_async(sink->pool, urls, 1, event,
+                                            sink_publish_cb, sink);
+    if (rc < 0) {
+        DEBUG_WARN("sink: publish_async error rc=%d for %s", rc, eid);
+        return -1;
+    }
+    if (rc == 0) {
+        DEBUG_INFO("sink: publish SKIPPED (not connected) for %s", eid);
+        return 0;
+    }
+    DEBUG_TRACE("sink: publish_async rc=%d for %s", rc, eid);
+    return 1;
+}
+
+int cr_sink_publish(cr_sink_t *sink, cJSON *event) {
+    return cr_sink_publish_from(sink, event, NULL);
+}
+
+void cr_sink_pump(cr_sink_t *sink, int timeout_ms) {
+    if (sink && sink->pool) {
+        nostr_relay_pool_run(sink->pool, timeout_ms);
+    }
+    /* No-op in PostgreSQL inbox mode. */
+}

caching/src/relay_sink.h

@@ -0,0 +1,75 @@
+/*
+ * caching_relay - relay sink: publishes fetched events to the local relay.
+ *
+ * Two modes:
+ *   - WebSocket mode (legacy): a dedicated single-relay pool publishes via
+ *     nostr_relay_pool_publish_async(). Used when no PostgreSQL connection
+ *     string is provided.
+ *   - PostgreSQL inbox mode: events are inserted directly into the
+ *     caching_event_inbox table via pg_inbox_insert_event(). Used when the
+ *     daemon is started with --pg-conn.
+ *
+ * The public function signatures are identical in both modes so that callers
+ * (live_subscriber, backfill, relay_discovery) do not need to change.
+ */
+#ifndef CACHING_RELAY_RELAY_SINK_H
+#define CACHING_RELAY_RELAY_SINK_H
+
+#include "state.h"
+#include "../nostr_core_lib/nostr_core/nostr_core.h"
+
+/* Source class labels for the inbox priority field. */
+#define CR_SINK_CLASS_LIVE      "live"
+#define CR_SINK_CLASS_DISCOVERY "discovery"
+#define CR_SINK_CLASS_BACKFILL  "backfill"
+
+typedef struct {
+    /* WebSocket mode only (NULL in PostgreSQL inbox mode). */
+    nostr_relay_pool_t     *pool;
+    char                    url[256];
+
+    /* PostgreSQL inbox mode: source class used for priority assignment.
+     * Defaults to "live". Set to "backfill" by the backfill module.
+     * Ignored in WebSocket mode. */
+    const char             *source_class;
+
+    cr_seen_ring_t         *seen;   /* shared seen ring for dedup */
+    long                    published_ok;
+    long                    published_failed;
+    long                    published_dup;
+} cr_sink_t;
+
+/* Create the sink.
+ *
+ * In WebSocket mode (pg_mode = 0): creates a relay pool and adds
+ * local_relay_url.
+ * In PostgreSQL inbox mode (pg_mode != 0): no pool is created; the URL is
+ * ignored. Events are inserted via pg_inbox_insert_event() (the pg_inbox
+ * module must be initialized beforehand).
+ *
+ * The original two-argument signature is preserved via cr_sink_init() below
+ * for backward compatibility; it defaults to WebSocket mode. */
+int  cr_sink_init(cr_sink_t *sink, const char *local_relay_url, cr_seen_ring_t *seen);
+
+/* Initialize the sink in PostgreSQL inbox mode. */
+int  cr_sink_init_pg(cr_sink_t *sink, cr_seen_ring_t *seen);
+
+/* Set the source class for priority assignment in PostgreSQL inbox mode.
+ * class_ptr must point to a static string literal (e.g. CR_SINK_CLASS_LIVE). */
+void cr_sink_set_source_class(cr_sink_t *sink, const char *class_ptr);
+
+void cr_sink_destroy(cr_sink_t *sink);
+
+/* Publish a cJSON event. Dedups against the seen ring.
+ * Returns 1 if enqueued/inserted, 0 if dup (skipped), -1 on error. */
+int  cr_sink_publish(cr_sink_t *sink, cJSON *event);
+
+/* Variant that records the originating relay URL in PostgreSQL inbox mode.
+ * In WebSocket mode the source_relay is ignored. */
+int  cr_sink_publish_from(cr_sink_t *sink, cJSON *event, const char *source_relay);
+
+/* Pump the sink pool briefly to flush pending publish callbacks.
+ * No-op in PostgreSQL inbox mode. */
+void cr_sink_pump(cr_sink_t *sink, int timeout_ms);
+
+#endif /* CACHING_RELAY_RELAY_SINK_H */

caching/src/state.c

@@ -0,0 +1,76 @@
+/*
+ * caching_relay - in-memory runtime state
+ */
+#define _GNU_SOURCE
+#include "state.h"
+
+#include <stdlib.h>
+#include <string.h>
+
+/* ---- pubkey set ---- */
+
+void cr_pubkey_set_init(cr_pubkey_set_t *s) {
+    s->items = NULL;
+    s->count = 0;
+    s->capacity = 0;
+}
+
+void cr_pubkey_set_free(cr_pubkey_set_t *s) {
+    for (int i = 0; i < s->count; i++) free(s->items[i]);
+    free(s->items);
+    s->items = NULL;
+    s->count = 0;
+    s->capacity = 0;
+}
+
+void cr_pubkey_set_clear(cr_pubkey_set_t *s) {
+    cr_pubkey_set_free(s);
+    cr_pubkey_set_init(s);
+}
+
+int cr_pubkey_set_contains(const cr_pubkey_set_t *s, const char *hex) {
+    for (int i = 0; i < s->count; i++) {
+        if (strcmp(s->items[i], hex) == 0) return 1;
+    }
+    return 0;
+}
+
+int cr_pubkey_set_add(cr_pubkey_set_t *s, const char *hex) {
+    if (!hex || !hex[0]) return 0;
+    if (cr_pubkey_set_contains(s, hex)) return 0;
+    if (s->count >= s->capacity) {
+        int newcap = s->capacity ? s->capacity * 2 : 64;
+        char **ni = realloc(s->items, newcap * sizeof(char *));
+        if (!ni) return -1;
+        s->items = ni;
+        s->capacity = newcap;
+    }
+    s->items[s->count] = strdup(hex);
+    if (!s->items[s->count]) return -1;
+    s->count++;
+    return 1;
+}
+
+/* ---- seen-event ring buffer ---- */
+
+void cr_seen_ring_init(cr_seen_ring_t *r) {
+    memset(r, 0, sizeof(*r));
+}
+
+int cr_seen_ring_contains(const cr_seen_ring_t *r, const char *id) {
+    for (int i = 0; i < r->count; i++) {
+        int idx = (r->head - 1 - i + CR_SEEN_RING_SIZE) % CR_SEEN_RING_SIZE;
+        if (strcmp(r->ids[idx], id) == 0) return 1;
+    }
+    return 0;
+}
+
+int cr_seen_ring_add(cr_seen_ring_t *r, const char *id) {
+    if (!id || !id[0]) return 0;
+    if (cr_seen_ring_contains(r, id)) return 0;
+    strncpy(r->ids[r->head], id, CR_HEX_LEN - 1);
+    r->ids[r->head][CR_HEX_LEN - 1] = '\0';
+    r->head = (r->head + 1) % CR_SEEN_RING_SIZE;
+    if (r->count < CR_SEEN_RING_SIZE) r->count++;
+    return 1;
+}

caching/src/state.h

@@ -0,0 +1,41 @@
+/*
+ * caching_relay - in-memory runtime state:
+ *   - followed-pubkey set (hex pubkeys)
+ *   - seen-event-id ring buffer (to avoid redundant publish attempts)
+ */
+#ifndef CACHING_RELAY_STATE_H
+#define CACHING_RELAY_STATE_H
+
+#include <stddef.h>
+
+/* Hex pubkey is 64 chars + NUL. Event id is 64 hex chars + NUL. */
+#define CR_HEX_LEN 65
+
+/* A simple dynamic string set for followed pubkeys. */
+typedef struct {
+    char  **items;
+    int     count;
+    int     capacity;
+} cr_pubkey_set_t;
+
+void cr_pubkey_set_init(cr_pubkey_set_t *s);
+void cr_pubkey_set_free(cr_pubkey_set_t *s);
+int  cr_pubkey_set_add(cr_pubkey_set_t *s, const char *hex); /* 1 if added, 0 if dup */
+int  cr_pubkey_set_contains(const cr_pubkey_set_t *s, const char *hex);
+void cr_pubkey_set_clear(cr_pubkey_set_t *s);
+
+/* Fixed-size ring buffer of event ids for dedup. */
+#define CR_SEEN_RING_SIZE 4096
+
+typedef struct {
+    char  ids[CR_SEEN_RING_SIZE][CR_HEX_LEN];
+    int   head;
+    int   count;
+} cr_seen_ring_t;
+
+void cr_seen_ring_init(cr_seen_ring_t *r);
+/* Returns 1 if the id was newly inserted, 0 if it was already present. */
+int  cr_seen_ring_add(cr_seen_ring_t *r, const char *id);
+int  cr_seen_ring_contains(const cr_seen_ring_t *r, const char *id);
+
+#endif /* CACHING_RELAY_STATE_H */

config.csv

@@ -0,0 +1 @@
+key,value,data_type,description,category,requires_restart,created_at,updated_at

db/README.md

@@ -1,228 +0,0 @@
-# C Nostr Relay Database
-
-This directory contains the SQLite database schema and initialization scripts for the C Nostr Relay implementation.
-
-## Files
-
-- **`schema.sql`** - Complete database schema based on nostr-rs-relay v18
-- **`init.sh`** - Database initialization script
-- **`c_nostr_relay.db`** - SQLite database file (created after running init.sh)
-
-## Quick Start
-
-1. **Initialize the database:**
-   ```bash
-   cd db
-   ./init.sh
-   ```
-
-2. **Force reinitialize (removes existing database):**
-   ```bash
-   ./init.sh --force
-   ```
-
-3. **Initialize with optimization and info:**
-   ```bash
-   ./init.sh --info --optimize
-   ```
-
-## Database Schema
-
-The schema is fully compatible with the Nostr protocol and includes:
-
-### Core Tables
-
-- **`event`** - Main event storage with all Nostr event data
-- **`tag`** - Denormalized tag index for efficient queries
-- **`user_verification`** - NIP-05 verification tracking
-- **`account`** - User account management (optional)
-- **`invoice`** - Lightning payment tracking (optional)
-
-### Key Features
-
-- ✅ **NIP-01 compliant** - Full basic protocol support
-- ✅ **Replaceable events** - Supports kinds 0, 3, 10000-19999
-- ✅ **Parameterized replaceable** - Supports kinds 30000-39999 with `d` tags
-- ✅ **Event deletion** - NIP-09 soft deletion with `hidden` column
-- ✅ **Event expiration** - NIP-40 automatic cleanup
-- ✅ **Authentication** - NIP-42 client authentication
-- ✅ **NIP-05 verification** - Domain-based identity verification
-- ✅ **Performance optimized** - Comprehensive indexing strategy
-
-### Schema Version
-
-Current version: **v18** (compatible with nostr-rs-relay v18)
-
-## Database Structure
-
-### Event Storage
-```sql
-CREATE TABLE event (
-    id INTEGER PRIMARY KEY,
-    event_hash BLOB NOT NULL,        -- 32-byte SHA256 hash
-    first_seen INTEGER NOT NULL,     -- relay receive timestamp
-    created_at INTEGER NOT NULL,     -- event creation timestamp
-    expires_at INTEGER,              -- NIP-40 expiration
-    author BLOB NOT NULL,            -- 32-byte pubkey
-    delegated_by BLOB,               -- NIP-26 delegator
-    kind INTEGER NOT NULL,           -- event kind
-    hidden INTEGER DEFAULT FALSE,   -- soft deletion flag
-    content TEXT NOT NULL            -- complete JSON event
-);
-```
-
-### Tag Indexing
-```sql
-CREATE TABLE tag (
-    id INTEGER PRIMARY KEY,
-    event_id INTEGER NOT NULL,
-    name TEXT,                       -- tag name ("e", "p", etc.)
-    value TEXT,                      -- tag value
-    created_at INTEGER NOT NULL,     -- denormalized for performance
-    kind INTEGER NOT NULL            -- denormalized for performance
-);
-```
-
-## Performance Features
-
-### Optimized Indexes
-- **Hash-based lookups** - `event_hash_index` for O(1) event retrieval
-- **Author queries** - `author_index`, `author_created_at_index`
-- **Kind filtering** - `kind_index`, `kind_created_at_index`
-- **Tag searching** - `tag_covering_index` for efficient tag queries
-- **Composite queries** - Multi-column indexes for complex filters
-
-### Query Optimization
-- **Denormalized tags** - Includes `kind` and `created_at` in tag table
-- **Binary storage** - BLOBs for hex data (pubkeys, hashes)
-- **WAL mode** - Write-Ahead Logging for concurrent access
-- **Automatic cleanup** - Triggers for data integrity
-
-## Usage Examples
-
-### Basic Operations
-
-1. **Insert an event:**
-   ```sql
-   INSERT INTO event (event_hash, first_seen, created_at, author, kind, content)
-   VALUES (?, ?, ?, ?, ?, ?);
-   ```
-
-2. **Query by author:**
-   ```sql
-   SELECT content FROM event 
-   WHERE author = ? AND hidden != TRUE
-   ORDER BY created_at DESC;
-   ```
-
-3. **Filter by tags:**
-   ```sql
-   SELECT e.content FROM event e
-   JOIN tag t ON e.id = t.event_id
-   WHERE t.name = 'p' AND t.value = ? AND e.hidden != TRUE;
-   ```
-
-### Advanced Queries
-
-1. **Get replaceable event (latest only):**
-   ```sql
-   SELECT content FROM event
-   WHERE author = ? AND kind = ? AND hidden != TRUE
-   ORDER BY created_at DESC LIMIT 1;
-   ```
-
-2. **Tag-based filtering (NIP-01 filters):**
-   ```sql
-   SELECT e.content FROM event e
-   WHERE e.id IN (
-     SELECT t.event_id FROM tag t
-     WHERE t.name = ? AND t.value IN (?, ?, ?)
-   ) AND e.hidden != TRUE;
-   ```
-
-## Maintenance
-
-### Regular Operations
-
-1. **Check database integrity:**
-   ```bash
-   sqlite3 c_nostr_relay.db "PRAGMA integrity_check;"
-   ```
-
-2. **Optimize database:**
-   ```bash
-   sqlite3 c_nostr_relay.db "PRAGMA optimize; VACUUM; ANALYZE;"
-   ```
-
-3. **Clean expired events:**
-   ```sql
-   DELETE FROM event WHERE expires_at <= strftime('%s', 'now');
-   ```
-
-### Monitoring
-
-1. **Database size:**
-   ```bash
-   ls -lh c_nostr_relay.db
-   ```
-
-2. **Table statistics:**
-   ```sql
-   SELECT name, COUNT(*) as count FROM (
-     SELECT 'events' as name FROM event UNION ALL
-     SELECT 'tags' as name FROM tag UNION ALL
-     SELECT 'verifications' as name FROM user_verification
-   ) GROUP BY name;
-   ```
-
-## Migration Support
-
-The schema includes a migration system for future updates:
-
-```sql
-CREATE TABLE schema_info (
-    version INTEGER PRIMARY KEY,
-    applied_at INTEGER NOT NULL,
-    description TEXT
-);
-```
-
-## Security Considerations
-
-1. **Input validation** - Always validate event JSON and signatures
-2. **Rate limiting** - Implement at application level
-3. **Access control** - Use `account` table for permissions
-4. **Backup strategy** - Regular database backups recommended
-
-## Compatibility
-
-- **SQLite version** - Requires SQLite 3.8.0+
-- **nostr-rs-relay** - Schema compatible with v18
-- **NIPs supported** - 01, 02, 05, 09, 10, 11, 26, 40, 42
-- **C libraries** - Compatible with sqlite3 C API
-
-## Troubleshooting
-
-### Common Issues
-
-1. **Database locked error:**
-   - Ensure proper connection closing in your C code
-   - Check for long-running transactions
-
-2. **Performance issues:**
-   - Run `PRAGMA optimize;` regularly
-   - Consider `VACUUM` if database grew significantly
-
-3. **Schema errors:**
-   - Verify SQLite version compatibility
-   - Check foreign key constraints
-
-### Getting Help
-
-- Check the main project README for C implementation details
-- Review nostr-rs-relay documentation for reference implementation
-- Consult Nostr NIPs for protocol specifications
-
-## License
-
-This database schema is part of the C Nostr Relay project and follows the same license terms.

db/init.sh

@@ -1,234 +0,0 @@
-#!/bin/bash
-
-# C Nostr Relay Database Initialization Script
-# Creates and initializes the SQLite database with proper schema
-
-set -e  # Exit on any error
-
-# Configuration
-DB_DIR="$(dirname "$0")"
-DB_NAME="c_nostr_relay.db"
-DB_PATH="${DB_DIR}/${DB_NAME}"
-SCHEMA_FILE="${DB_DIR}/schema.sql"
-
-# Colors for output
-RED='\033[0;31m'
-GREEN='\033[0;32m'
-YELLOW='\033[1;33m'
-BLUE='\033[0;34m'
-NC='\033[0m' # No Color
-
-# Logging functions
-log_info() {
-    echo -e "${BLUE}[INFO]${NC} $1"
-}
-
-log_success() {
-    echo -e "${GREEN}[SUCCESS]${NC} $1"
-}
-
-log_warning() {
-    echo -e "${YELLOW}[WARNING]${NC} $1"
-}
-
-log_error() {
-    echo -e "${RED}[ERROR]${NC} $1"
-}
-
-# Check if SQLite3 is installed
-check_sqlite() {
-    if ! command -v sqlite3 &> /dev/null; then
-        log_error "sqlite3 is not installed. Please install it first:"
-        echo "  Ubuntu/Debian: sudo apt-get install sqlite3"
-        echo "  CentOS/RHEL:   sudo yum install sqlite"
-        echo "  macOS:         brew install sqlite3"
-        exit 1
-    fi
-    
-    local version=$(sqlite3 --version | cut -d' ' -f1)
-    log_info "Using SQLite version: $version"
-}
-
-# Create database directory if it doesn't exist
-create_db_directory() {
-    if [ ! -d "$DB_DIR" ]; then
-        log_info "Creating database directory: $DB_DIR"
-        mkdir -p "$DB_DIR"
-    fi
-}
-
-# Backup existing database if it exists
-backup_existing_db() {
-    if [ -f "$DB_PATH" ]; then
-        local backup_path="${DB_PATH}.backup.$(date +%Y%m%d_%H%M%S)"
-        log_warning "Existing database found. Creating backup: $backup_path"
-        cp "$DB_PATH" "$backup_path"
-    fi
-}
-
-# Initialize the database with schema
-init_database() {
-    log_info "Initializing database: $DB_PATH"
-    
-    if [ ! -f "$SCHEMA_FILE" ]; then
-        log_error "Schema file not found: $SCHEMA_FILE"
-        exit 1
-    fi
-    
-    # Remove existing database if --force flag is used
-    if [ "$1" = "--force" ] && [ -f "$DB_PATH" ]; then
-        log_warning "Force flag detected. Removing existing database."
-        rm -f "$DB_PATH"
-    fi
-    
-    # Create the database and apply schema
-    log_info "Applying schema from: $SCHEMA_FILE"
-    if sqlite3 "$DB_PATH" < "$SCHEMA_FILE"; then
-        log_success "Database schema applied successfully"
-    else
-        log_error "Failed to apply database schema"
-        exit 1
-    fi
-}
-
-# Verify database integrity
-verify_database() {
-    log_info "Verifying database integrity..."
-    
-    # Check if database file exists and is not empty
-    if [ ! -s "$DB_PATH" ]; then
-        log_error "Database file is empty or doesn't exist"
-        exit 1
-    fi
-    
-    # Run SQLite integrity check
-    local integrity_result=$(sqlite3 "$DB_PATH" "PRAGMA integrity_check;")
-    if [ "$integrity_result" = "ok" ]; then
-        log_success "Database integrity check passed"
-    else
-        log_error "Database integrity check failed: $integrity_result"
-        exit 1
-    fi
-    
-    # Verify schema version
-    local schema_version=$(sqlite3 "$DB_PATH" "PRAGMA user_version;")
-    log_info "Database schema version: $schema_version"
-    
-    # Check that main tables exist (including configuration tables)
-    local table_count=$(sqlite3 "$DB_PATH" "SELECT count(*) FROM sqlite_master WHERE type='table' AND name IN ('events', 'schema_info', 'server_config');")
-    if [ "$table_count" -eq 3 ]; then
-        log_success "Core tables created successfully (including configuration tables)"
-    else
-        log_error "Missing core tables (expected 3, found $table_count)"
-        exit 1
-    fi
-}
-
-# Display database information
-show_db_info() {
-    log_info "Database Information:"
-    echo "  Location: $DB_PATH"
-    echo "  Size: $(du -h "$DB_PATH" | cut -f1)"
-    
-    log_info "Database Tables:"
-    sqlite3 "$DB_PATH" "SELECT name FROM sqlite_master WHERE type='table' ORDER BY name;" | sed 's/^/  - /'
-    
-    log_info "Database Indexes:"
-    sqlite3 "$DB_PATH" "SELECT name FROM sqlite_master WHERE type='index' AND name NOT LIKE 'sqlite_%' ORDER BY name;" | sed 's/^/  - /'
-    
-    log_info "Database Views:"
-    sqlite3 "$DB_PATH" "SELECT name FROM sqlite_master WHERE type='view' ORDER BY name;" | sed 's/^/  - /'
-}
-
-# Run database optimization
-optimize_database() {
-    log_info "Running database optimization..."
-    sqlite3 "$DB_PATH" "PRAGMA optimize; VACUUM; ANALYZE;"
-    log_success "Database optimization completed"
-}
-
-# Print usage information
-print_usage() {
-    echo "Usage: $0 [OPTIONS]"
-    echo ""
-    echo "Initialize SQLite database for C Nostr Relay"
-    echo ""
-    echo "Options:"
-    echo "  --force     Remove existing database before initialization"
-    echo "  --info      Show database information after initialization"
-    echo "  --optimize  Run database optimization after initialization"
-    echo "  --help      Show this help message"
-    echo ""
-    echo "Examples:"
-    echo "  $0                    # Initialize database (with backup if exists)"
-    echo "  $0 --force           # Force reinitialize database"
-    echo "  $0 --info --optimize # Initialize with info and optimization"
-}
-
-# Main execution
-main() {
-    local force_flag=false
-    local show_info=false
-    local optimize=false
-    
-    # Parse command line arguments
-    while [[ $# -gt 0 ]]; do
-        case $1 in
-            --force)
-                force_flag=true
-                shift
-                ;;
-            --info)
-                show_info=true
-                shift
-                ;;
-            --optimize)
-                optimize=true
-                shift
-                ;;
-            --help)
-                print_usage
-                exit 0
-                ;;
-            *)
-                log_error "Unknown option: $1"
-                print_usage
-                exit 1
-                ;;
-        esac
-    done
-    
-    log_info "Starting C Nostr Relay database initialization..."
-    
-    # Execute initialization steps
-    check_sqlite
-    create_db_directory
-    
-    if [ "$force_flag" = false ]; then
-        backup_existing_db
-    fi
-    
-    if [ "$force_flag" = true ]; then
-        init_database --force
-    else
-        init_database
-    fi
-    
-    verify_database
-    
-    if [ "$optimize" = true ]; then
-        optimize_database
-    fi
-    
-    if [ "$show_info" = true ]; then
-        show_db_info
-    fi
-    
-    log_success "Database initialization completed successfully!"
-    echo ""
-    echo "Database ready at: $DB_PATH"
-    echo "You can now start your C Nostr Relay application."
-}
-
-# Execute main function with all arguments
-main "$@"

db/schema.sql

@@ -1,299 +0,0 @@
--- C Nostr Relay Database Schema
--- SQLite schema for storing Nostr events with JSON tags support
-
--- Schema version tracking
-PRAGMA user_version = 3;
-
--- Enable foreign key support
-PRAGMA foreign_keys = ON;
-
--- Optimize for performance
-PRAGMA journal_mode = WAL;
-PRAGMA synchronous = NORMAL;
-PRAGMA cache_size = 10000;
-
--- Core events table with hybrid single-table design
-CREATE TABLE events (
-    id TEXT PRIMARY KEY,                -- Nostr event ID (hex string)
-    pubkey TEXT NOT NULL,               -- Public key of event author (hex string)
-    created_at INTEGER NOT NULL,       -- Event creation timestamp (Unix timestamp)
-    kind INTEGER NOT NULL,              -- Event kind (0-65535)
-    event_type TEXT NOT NULL CHECK (event_type IN ('regular', 'replaceable', 'ephemeral', 'addressable')),
-    content TEXT NOT NULL,              -- Event content (text content only)
-    sig TEXT NOT NULL,                  -- Event signature (hex string)
-    tags JSON NOT NULL DEFAULT '[]',   -- Event tags as JSON array
-    first_seen INTEGER NOT NULL DEFAULT (strftime('%s', 'now'))  -- When relay received event
-);
-
--- Core performance indexes
-CREATE INDEX idx_events_pubkey ON events(pubkey);
-CREATE INDEX idx_events_kind ON events(kind);
-CREATE INDEX idx_events_created_at ON events(created_at DESC);
-CREATE INDEX idx_events_event_type ON events(event_type);
-
--- Composite indexes for common query patterns
-CREATE INDEX idx_events_kind_created_at ON events(kind, created_at DESC);
-CREATE INDEX idx_events_pubkey_created_at ON events(pubkey, created_at DESC);
-CREATE INDEX idx_events_pubkey_kind ON events(pubkey, kind);
-
--- Schema information table
-CREATE TABLE schema_info (
-    key TEXT PRIMARY KEY,
-    value TEXT NOT NULL,
-    updated_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now'))
-);
-
--- Insert schema metadata
-INSERT INTO schema_info (key, value) VALUES
-    ('version', '3'),
-    ('description', 'Hybrid single-table Nostr relay schema with JSON tags and configuration management'),
-    ('created_at', strftime('%s', 'now'));
-
--- Helper views for common queries
-CREATE VIEW recent_events AS
-SELECT id, pubkey, created_at, kind, event_type, content
-FROM events
-WHERE event_type != 'ephemeral'
-ORDER BY created_at DESC
-LIMIT 1000;
-
-CREATE VIEW event_stats AS
-SELECT 
-    event_type,
-    COUNT(*) as count,
-    AVG(length(content)) as avg_content_length,
-    MIN(created_at) as earliest,
-    MAX(created_at) as latest
-FROM events
-GROUP BY event_type;
-
--- Optimization: Trigger for automatic cleanup of ephemeral events older than 1 hour
-CREATE TRIGGER cleanup_ephemeral_events
-    AFTER INSERT ON events
-    WHEN NEW.event_type = 'ephemeral'
-BEGIN
-    DELETE FROM events 
-    WHERE event_type = 'ephemeral' 
-    AND first_seen < (strftime('%s', 'now') - 3600);
-END;
-
--- Replaceable event handling trigger
-CREATE TRIGGER handle_replaceable_events
-    AFTER INSERT ON events
-    WHEN NEW.event_type = 'replaceable'
-BEGIN
-    DELETE FROM events 
-    WHERE pubkey = NEW.pubkey 
-    AND kind = NEW.kind 
-    AND event_type = 'replaceable'
-    AND id != NEW.id;
-END;
-
--- Persistent Subscriptions Logging Tables (Phase 2)
--- Optional database logging for subscription analytics and debugging
-
--- Subscription events log
-CREATE TABLE subscription_events (
-    id INTEGER PRIMARY KEY AUTOINCREMENT,
-    subscription_id TEXT NOT NULL,           -- Subscription ID from client
-    client_ip TEXT NOT NULL,                 -- Client IP address
-    event_type TEXT NOT NULL CHECK (event_type IN ('created', 'closed', 'expired', 'disconnected')),
-    filter_json TEXT,                        -- JSON representation of filters (for created events)
-    events_sent INTEGER DEFAULT 0,           -- Number of events sent to this subscription
-    created_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now')),
-    ended_at INTEGER,                        -- When subscription ended (for closed/expired/disconnected)
-    duration INTEGER                         -- Computed: ended_at - created_at
-);
-
--- Subscription metrics summary
-CREATE TABLE subscription_metrics (
-    id INTEGER PRIMARY KEY AUTOINCREMENT,
-    date TEXT NOT NULL,                      -- Date (YYYY-MM-DD)
-    total_created INTEGER DEFAULT 0,         -- Total subscriptions created
-    total_closed INTEGER DEFAULT 0,          -- Total subscriptions closed
-    total_events_broadcast INTEGER DEFAULT 0, -- Total events broadcast
-    avg_duration REAL DEFAULT 0,            -- Average subscription duration
-    peak_concurrent INTEGER DEFAULT 0,       -- Peak concurrent subscriptions
-    updated_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now')),
-    UNIQUE(date)
-);
-
--- Event broadcasting log (optional, for detailed analytics)
-CREATE TABLE event_broadcasts (
-    id INTEGER PRIMARY KEY AUTOINCREMENT,
-    event_id TEXT NOT NULL,                  -- Event ID that was broadcast
-    subscription_id TEXT NOT NULL,           -- Subscription that received it
-    client_ip TEXT NOT NULL,                 -- Client IP
-    broadcast_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now')),
-    FOREIGN KEY (event_id) REFERENCES events(id)
-);
-
--- Indexes for subscription logging performance
-CREATE INDEX idx_subscription_events_id ON subscription_events(subscription_id);
-CREATE INDEX idx_subscription_events_type ON subscription_events(event_type);
-CREATE INDEX idx_subscription_events_created ON subscription_events(created_at DESC);
-CREATE INDEX idx_subscription_events_client ON subscription_events(client_ip);
-
-CREATE INDEX idx_subscription_metrics_date ON subscription_metrics(date DESC);
-
-CREATE INDEX idx_event_broadcasts_event ON event_broadcasts(event_id);
-CREATE INDEX idx_event_broadcasts_sub ON event_broadcasts(subscription_id);
-CREATE INDEX idx_event_broadcasts_time ON event_broadcasts(broadcast_at DESC);
-
--- Trigger to update subscription duration when ended
-CREATE TRIGGER update_subscription_duration
-    AFTER UPDATE OF ended_at ON subscription_events
-    WHEN NEW.ended_at IS NOT NULL AND OLD.ended_at IS NULL
-BEGIN
-    UPDATE subscription_events
-    SET duration = NEW.ended_at - NEW.created_at
-    WHERE id = NEW.id;
-END;
-
--- View for subscription analytics
-CREATE VIEW subscription_analytics AS
-SELECT
-    date(created_at, 'unixepoch') as date,
-    COUNT(*) as subscriptions_created,
-    COUNT(CASE WHEN ended_at IS NOT NULL THEN 1 END) as subscriptions_ended,
-    AVG(CASE WHEN duration IS NOT NULL THEN duration END) as avg_duration_seconds,
-    MAX(events_sent) as max_events_sent,
-    AVG(events_sent) as avg_events_sent,
-    COUNT(DISTINCT client_ip) as unique_clients
-FROM subscription_events
-GROUP BY date(created_at, 'unixepoch')
-ORDER BY date DESC;
-
--- View for current active subscriptions (from log perspective)
-CREATE VIEW active_subscriptions_log AS
-SELECT
-    subscription_id,
-    client_ip,
-    filter_json,
-    events_sent,
-    created_at,
-    (strftime('%s', 'now') - created_at) as duration_seconds
-FROM subscription_events
-WHERE event_type = 'created'
-AND subscription_id NOT IN (
-    SELECT subscription_id FROM subscription_events
-    WHERE event_type IN ('closed', 'expired', 'disconnected')
-);
-
--- ================================
--- CONFIGURATION MANAGEMENT TABLES
--- ================================
-
--- Core server configuration table
-CREATE TABLE server_config (
-    key TEXT PRIMARY KEY,                    -- Configuration key (unique identifier)
-    value TEXT NOT NULL,                     -- Configuration value (stored as string)
-    description TEXT,                        -- Human-readable description
-    config_type TEXT DEFAULT 'user' CHECK (config_type IN ('system', 'user', 'runtime')),
-    data_type TEXT DEFAULT 'string' CHECK (data_type IN ('string', 'integer', 'boolean', 'json')),
-    validation_rules TEXT,                   -- JSON validation rules (optional)
-    is_sensitive INTEGER DEFAULT 0,          -- 1 if value should be masked in logs
-    requires_restart INTEGER DEFAULT 0,      -- 1 if change requires server restart
-    created_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now')),
-    updated_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now'))
-);
-
--- Configuration change history table
-CREATE TABLE config_history (
-    id INTEGER PRIMARY KEY AUTOINCREMENT,
-    config_key TEXT NOT NULL,               -- Key that was changed
-    old_value TEXT,                         -- Previous value (NULL for new keys)
-    new_value TEXT NOT NULL,                -- New value
-    changed_by TEXT DEFAULT 'system',       -- Who made the change (system/admin/user)
-    change_reason TEXT,                     -- Optional reason for change
-    changed_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now')),
-    FOREIGN KEY (config_key) REFERENCES server_config(key)
-);
-
--- Configuration validation errors log
-CREATE TABLE config_validation_log (
-    id INTEGER PRIMARY KEY AUTOINCREMENT,
-    config_key TEXT NOT NULL,
-    attempted_value TEXT,
-    validation_error TEXT NOT NULL,
-    error_source TEXT DEFAULT 'validation',  -- validation/parsing/constraint
-    attempted_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now'))
-);
-
--- Cache for file-based configuration events
-CREATE TABLE config_file_cache (
-    file_path TEXT PRIMARY KEY,             -- Full path to config file
-    file_hash TEXT NOT NULL,                -- SHA256 hash of file content
-    event_id TEXT,                          -- Nostr event ID from file
-    event_pubkey TEXT,                      -- Admin pubkey that signed event
-    loaded_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now')),
-    validation_status TEXT CHECK (validation_status IN ('valid', 'invalid', 'unverified')),
-    validation_error TEXT                   -- Error details if invalid
-);
-
--- Performance indexes for configuration tables
-CREATE INDEX idx_server_config_type ON server_config(config_type);
-CREATE INDEX idx_server_config_updated ON server_config(updated_at DESC);
-CREATE INDEX idx_config_history_key ON config_history(config_key);
-CREATE INDEX idx_config_history_time ON config_history(changed_at DESC);
-CREATE INDEX idx_config_validation_key ON config_validation_log(config_key);
-CREATE INDEX idx_config_validation_time ON config_validation_log(attempted_at DESC);
-
--- Trigger to update timestamp on configuration changes
-CREATE TRIGGER update_config_timestamp
-    AFTER UPDATE ON server_config
-BEGIN
-    UPDATE server_config SET updated_at = strftime('%s', 'now') WHERE key = NEW.key;
-END;
-
--- Trigger to log configuration changes to history
-CREATE TRIGGER log_config_changes
-    AFTER UPDATE ON server_config
-    WHEN OLD.value != NEW.value
-BEGIN
-    INSERT INTO config_history (config_key, old_value, new_value, changed_by, change_reason)
-    VALUES (NEW.key, OLD.value, NEW.value, 'system', 'configuration update');
-END;
-
--- Active Configuration View
-CREATE VIEW active_config AS
-SELECT
-    key,
-    value,
-    description,
-    config_type,
-    data_type,
-    requires_restart,
-    updated_at
-FROM server_config
-WHERE config_type IN ('system', 'user')
-ORDER BY config_type, key;
-
--- Runtime Statistics View
-CREATE VIEW runtime_stats AS
-SELECT
-    key,
-    value,
-    description,
-    updated_at
-FROM server_config
-WHERE config_type = 'runtime'
-ORDER BY key;
-
--- Configuration Change Summary
-CREATE VIEW recent_config_changes AS
-SELECT
-    ch.config_key,
-    sc.description,
-    ch.old_value,
-    ch.new_value,
-    ch.changed_by,
-    ch.change_reason,
-    ch.changed_at
-FROM config_history ch
-JOIN server_config sc ON ch.config_key = sc.key
-ORDER BY ch.changed_at DESC
-LIMIT 50;
-
--- Runtime Statistics (initialized by server on startup)
--- These will be populated when configuration system initializes

deploy_local.sh

@@ -0,0 +1,12 @@
+#!/bin/bash
+# Restart the service
+sudo systemctl stop c-relay-pg.service
+
+# Copy the binary to the deployment location
+cp build/c_relay_pg_static_x86_64 ~/Storage/c_relay_pg/crelay
+
+# Restart the service
+sudo systemctl restart c-relay-pg.service
+
+# Show service status
+sudo systemctl status c-relay-pg.service --no-pager -l

deploy_lt.sh

@@ -0,0 +1,203 @@
+#!/bin/bash
+
+# C-Relay-PG PostgreSQL Deployment Script
+# Deploys static relay binary and configures PostgreSQL 18 + systemd service on remote server.
+
+set -euo pipefail
+
+# Configuration
+REMOTE_HOST="ubuntu@laantungir.net"
+LOCAL_BINARY="build/c_relay_pg_static_x86_64"
+LOCAL_CACHING_BINARY="build/caching_relay"
+REMOTE_BINARY_DIR="/usr/local/bin/c_relay_pg"
+REMOTE_BINARY_PATH="/usr/local/bin/c_relay_pg/c_relay_pg"
+REMOTE_CACHING_BINARY_PATH="/opt/c-relay-pg/caching_relay"
+SERVICE_NAME="c-relay-pg"
+
+LOCAL_SERVICE_FILE="systemd/c-relay.service"
+LOCAL_PG_SETUP_SCRIPT="systemd/setup_postgres_18.sh"
+
+if [ ! -f "$LOCAL_BINARY" ]; then
+    echo "ERROR: Binary not found: $LOCAL_BINARY"
+    echo "Build it first (e.g. ./make_and_restart_relay.sh)"
+    exit 1
+fi
+
+if [ ! -f "$LOCAL_SERVICE_FILE" ]; then
+    echo "ERROR: Service file not found: $LOCAL_SERVICE_FILE"
+    exit 1
+fi
+
+if [ ! -f "$LOCAL_PG_SETUP_SCRIPT" ]; then
+    echo "ERROR: PostgreSQL setup script not found: $LOCAL_PG_SETUP_SCRIPT"
+    exit 1
+fi
+
+echo "==> Uploading artifacts to $REMOTE_HOST"
+scp "$LOCAL_BINARY" "$REMOTE_HOST:/tmp/c_relay_pg.tmp"
+scp "$LOCAL_SERVICE_FILE" "$REMOTE_HOST:/tmp/c-relay-pg.service"
+scp "$LOCAL_PG_SETUP_SCRIPT" "$REMOTE_HOST:/tmp/setup_postgres_18.sh"
+# Upload the caching_relay binary if it was built locally. The caching
+# service is NOT started by this deploy (the systemd unit does not pass
+# --start-caching), but the binary is placed in the relay's WorkingDirectory
+# so it is ready for when caching is enabled via event-based config.
+if [ -f "$LOCAL_CACHING_BINARY" ]; then
+    scp "$LOCAL_CACHING_BINARY" "$REMOTE_HOST:/tmp/caching_relay.tmp"
+else
+    echo "WARNING: caching_relay binary not found locally ($LOCAL_CACHING_BINARY) — skipping caching binary upload"
+fi
+
+# Upload admin PHP files (tar to preserve directory structure, exclude
+# cache logs and the dev-only serve.sh / php_server.log).
+echo "==> Packaging admin files"
+tar czf /tmp/admin_deploy.tar.gz \
+    --exclude='admin/serve.sh' \
+    --exclude='admin/php_server.log' \
+    --exclude='admin/cache' \
+    -C . admin/
+scp /tmp/admin_deploy.tar.gz "$REMOTE_HOST:/tmp/admin_deploy.tar.gz"
+
+echo "==> Running remote install/configuration"
+ssh "$REMOTE_HOST" 'bash -s' <<'EOF'
+set -euo pipefail
+
+SERVICE_NAME="c-relay-pg"
+RELAY_USER="c-relay-pg"
+REMOTE_BINARY_DIR="/usr/local/bin/c_relay_pg"
+REMOTE_BINARY_PATH="/usr/local/bin/c_relay_pg/c_relay_pg"
+REMOTE_CACHING_BINARY_PATH="/opt/c-relay-pg/caching_relay"
+
+echo "[remote] Ensuring service user exists"
+if ! id "$RELAY_USER" >/dev/null 2>&1; then
+  sudo useradd --system --home-dir /opt/c-relay-pg --shell /usr/sbin/nologin "$RELAY_USER"
+fi
+
+echo "[remote] Ensuring required directories exist"
+sudo mkdir -p "$REMOTE_BINARY_DIR" /opt/c-relay-pg /etc/c-relay-pg
+sudo chown "$RELAY_USER:$RELAY_USER" /opt/c-relay-pg
+
+echo "[remote] Installing PostgreSQL 18 (PGDG) if missing"
+if ! dpkg -s postgresql-18 >/dev/null 2>&1; then
+  sudo apt-get update
+  sudo apt-get install -y curl ca-certificates lsb-release gnupg
+  sudo install -d /usr/share/postgresql-common/pgdg
+  sudo curl -fsSL https://www.postgresql.org/media/keys/ACCC4CF8.asc -o /usr/share/postgresql-common/pgdg/apt.postgresql.org.asc
+  echo "deb [signed-by=/usr/share/postgresql-common/pgdg/apt.postgresql.org.asc] https://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" | sudo tee /etc/apt/sources.list.d/pgdg.list >/dev/null
+  sudo apt-get update
+  sudo apt-get install -y postgresql-18
+fi
+
+sudo systemctl enable postgresql
+sudo systemctl restart postgresql
+
+echo "[remote] Configuring PostgreSQL role/database"
+sudo chmod +x /tmp/setup_postgres_18.sh
+sudo /tmp/setup_postgres_18.sh
+
+echo "[remote] Installing relay binary"
+if [ -f "$REMOTE_BINARY_PATH" ]; then
+  sudo cp "$REMOTE_BINARY_PATH" "${REMOTE_BINARY_PATH}.backup.$(date +%Y%m%d_%H%M%S)"
+fi
+sudo mv /tmp/c_relay_pg.tmp "$REMOTE_BINARY_PATH"
+sudo chown "$RELAY_USER:$RELAY_USER" "$REMOTE_BINARY_PATH"
+sudo chmod +x "$REMOTE_BINARY_PATH"
+
+echo "[remote] Installing caching_relay binary (if uploaded)"
+if [ -f /tmp/caching_relay.tmp ]; then
+  sudo mv /tmp/caching_relay.tmp "$REMOTE_CACHING_BINARY_PATH"
+  sudo chown "$RELAY_USER:$RELAY_USER" "$REMOTE_CACHING_BINARY_PATH"
+  sudo chmod +x "$REMOTE_CACHING_BINARY_PATH"
+  echo "  -> caching_relay installed at $REMOTE_CACHING_BINARY_PATH (not started; enable via config when ready)"
+else
+  echo "  -> no caching_relay binary uploaded, skipping"
+fi
+
+echo "[remote] Installing admin PHP files"
+# Back up existing config.php and .htpasswd so we don't lose production
+# credentials (DB password, basic-auth) across deploys.
+if [ -f /opt/c-relay-pg/admin/lib/config.php ]; then
+  sudo cp /opt/c-relay-pg/admin/lib/config.php /tmp/admin_config_backup
+  echo "  -> backed up config.php"
+fi
+if [ -f /opt/c-relay-pg/admin/.htpasswd ]; then
+  sudo cp /opt/c-relay-pg/admin/.htpasswd /tmp/admin_htpasswd_backup
+  echo "  -> backed up .htpasswd"
+fi
+# Extract the new admin files (overwrites old admin at /opt/c-relay-pg/admin/).
+sudo mkdir -p /opt/c-relay-pg/admin
+sudo tar xzf /tmp/admin_deploy.tar.gz -C /opt/c-relay-pg/
+# Restore config.php and .htpasswd if they were backed up.
+if [ -f /tmp/admin_config_backup ]; then
+  sudo cp /tmp/admin_config_backup /opt/c-relay-pg/admin/lib/config.php
+  echo "  -> restored config.php"
+fi
+if [ -f /tmp/admin_htpasswd_backup ]; then
+  sudo cp /tmp/admin_htpasswd_backup /opt/c-relay-pg/admin/.htpasswd
+  echo "  -> restored .htpasswd"
+fi
+# Set ownership: www-data (nginx/php-fpm) for web-served files,
+# but keep .htpasswd readable by nginx.
+sudo chown -R www-data:www-data /opt/c-relay-pg/admin/
+sudo chmod 640 /opt/c-relay-pg/admin/.htpasswd 2>/dev/null || true
+# Ensure the cache directory exists (for chart text files).
+sudo mkdir -p /opt/c-relay-pg/admin/cache
+sudo chown www-data:www-data /opt/c-relay-pg/admin/cache
+echo "  -> admin files installed at /opt/c-relay-pg/admin/"
+
+# Also update admin2 if it exists (symlink or copy to keep it in sync).
+if [ -d /opt/c-relay-pg/admin2 ]; then
+  sudo rm -rf /opt/c-relay-pg/admin2
+  sudo cp -a /opt/c-relay-pg/admin /opt/c-relay-pg/admin2
+  sudo chown -R www-data:www-data /opt/c-relay-pg/admin2/
+  echo "  -> admin2 synced at /opt/c-relay-pg/admin2/"
+fi
+
+echo "[remote] Installing systemd unit"
+sudo mv /tmp/c-relay-pg.service /etc/systemd/system/c-relay-pg.service
+sudo chown root:root /etc/systemd/system/c-relay-pg.service
+sudo chmod 644 /etc/systemd/system/c-relay-pg.service
+
+echo "[remote] Killing stale caching_relay processes (safety)"
+# The caching service is forked by the relay with setsid(), so it detaches
+# from the relay's process group and survives when the relay is killed.
+# Without this, every restart orphans the previous caching_relay child and
+# a new relay forks another, leading to many stale processes with dead PG
+# connections spamming errors. Kill them here so the new relay starts clean.
+CACHING_PIDS=$(pgrep -f "caching_relay" || echo "")
+if [ -n "$CACHING_PIDS" ]; then
+  echo "  -> killing stale caching_relay PIDs: $CACHING_PIDS"
+  kill -9 $CACHING_PIDS 2>/dev/null || true
+  sleep 1
+else
+  echo "  -> no stale caching_relay processes found"
+fi
+
+echo "[remote] Reloading and restarting service"
+sudo systemctl daemon-reload
+sudo systemctl enable "$SERVICE_NAME"
+sudo systemctl restart "$SERVICE_NAME"
+
+echo "[remote] Health checks"
+sudo systemctl --no-pager --full status "$SERVICE_NAME" | sed -n '1,25p'
+sudo -u "$RELAY_USER" psql -d crelay -c "SELECT current_user, current_database();"
+
+# Verify admin page is accessible (HTTP 200 or 401 = auth required, both are OK).
+ADMIN_CODE=$(curl -s -o /dev/null -w "%{http_code}" "http://127.0.0.1/admin/" 2>/dev/null || echo "000")
+if [ "$ADMIN_CODE" = "200" ] || [ "$ADMIN_CODE" = "401" ]; then
+  echo "  -> admin page accessible (HTTP $ADMIN_CODE)"
+else
+  echo "  -> WARNING: admin page returned HTTP $ADMIN_CODE (expected 200 or 401)"
+fi
+
+# Clean up temp files.
+rm -f /tmp/admin_deploy.tar.gz
+sudo rm -f /tmp/admin_htpasswd_backup /tmp/admin_config_backup
+EOF
+
+# Clean up local temp tarball.
+rm -f /tmp/admin_deploy.tar.gz
+
+echo "Deployment complete: $REMOTE_HOST"
+echo ""
+echo "Admin interface: https://laantungir.net/admin/"
+echo "Caching is NOT auto-started. Enable it via the admin UI when ready."

deploy_lt_debug.sh

@@ -0,0 +1,122 @@
+#!/bin/bash
+
+# C-Relay-PG Debug Binary Deployment Script
+# Deploys build/c_relay_pg_static_x86_64_debug to server for CPU profiling
+#
+# Usage:
+#   ./deploy_lt_debug.sh           -- deploy debug binary and restart
+#   ./deploy_lt_debug.sh --profile -- deploy, then run perf and fetch results
+#
+# After deploying, profile with:
+#   sudo perf record -g -p $(pgrep c_relay_pg) -- sleep 30
+#   sudo perf report --stdio --sort=symbol --no-children -n 2>/dev/null | head -80
+#
+# Restore production binary:
+#   ./deploy_lt.sh
+
+set -e
+
+LOCAL_DEBUG_BINARY="build/c_relay_pg_static_x86_64_debug"
+REMOTE_BINARY_PATH="/usr/local/bin/c_relay_pg/c_relay_pg"
+REMOTE_PROD_BACKUP="/usr/local/bin/c_relay_pg/c_relay_pg.production"
+SERVICE_NAME="c-relay-pg"
+REMOTE_HOST="ubuntu@laantungir.com"
+
+# Check debug binary exists
+if [ ! -f "$LOCAL_DEBUG_BINARY" ]; then
+    echo "ERROR: Debug binary not found: $LOCAL_DEBUG_BINARY"
+    echo ""
+    echo "Build it first with:"
+    echo "  ./build_static.sh --debug"
+    echo ""
+    exit 1
+fi
+
+echo "=========================================="
+echo "C-Relay-PG Debug Deployment"
+echo "=========================================="
+echo "Binary: $LOCAL_DEBUG_BINARY ($(du -h "$LOCAL_DEBUG_BINARY" | cut -f1))"
+echo "Target: $REMOTE_HOST:$REMOTE_BINARY_PATH"
+echo ""
+echo "WARNING: Debug binary has symbols and is larger than production."
+echo "         It is safe to run but should not be left deployed long-term."
+echo ""
+
+# Backup production binary (only if not already backed up)
+echo "Backing up production binary..."
+ssh "$REMOTE_HOST" "
+    if [ ! -f '$REMOTE_PROD_BACKUP' ]; then
+        sudo cp '$REMOTE_BINARY_PATH' '$REMOTE_PROD_BACKUP'
+        echo 'Production binary backed up to $REMOTE_PROD_BACKUP'
+    else
+        echo 'Production backup already exists, skipping'
+    fi
+"
+
+# Upload debug binary
+echo "Uploading debug binary..."
+scp "$LOCAL_DEBUG_BINARY" "$REMOTE_HOST:/tmp/c_relay_pg_debug.tmp"
+
+# Install debug binary
+echo "Installing debug binary..."
+ssh "$REMOTE_HOST" "
+    sudo mv '/tmp/c_relay_pg_debug.tmp' '$REMOTE_BINARY_PATH'
+    sudo chown c-relay-pg:c-relay-pg '$REMOTE_BINARY_PATH'
+    sudo chmod +x '$REMOTE_BINARY_PATH'
+"
+
+# Restart service
+echo "Restarting c-relay-pg service..."
+ssh "$REMOTE_HOST" "sudo systemctl daemon-reload && sudo systemctl restart '$SERVICE_NAME'"
+
+echo ""
+echo "✓ Debug binary deployed and service restarted"
+echo ""
+
+# If --profile flag, run perf automatically
+if [ "$1" = "--profile" ]; then
+    echo "=========================================="
+    echo "Running perf profile (30 seconds)..."
+    echo "=========================================="
+    echo ""
+    
+    # Wait for relay to start
+    sleep 3
+    
+    ssh "$REMOTE_HOST" "
+        PID=\$(pgrep c_relay_pg)
+        if [ -z \"\$PID\" ]; then
+            echo 'ERROR: c_relay_pg not running'
+            exit 1
+        fi
+        echo \"Profiling PID \$PID for 30 seconds...\"
+        sudo perf record -g -p \$PID -- sleep 30
+        echo ''
+        echo '=== TOP FUNCTIONS BY CPU ==='
+        sudo perf report --stdio --sort=symbol --no-children -n 2>/dev/null | head -60
+    "
+else
+    echo "=========================================="
+    echo "Next Steps: Profile the relay"
+    echo "=========================================="
+    echo ""
+    echo "SSH to server and run:"
+    echo "  sudo perf record -g -p \$(pgrep c_relay_pg) -- sleep 30"
+    echo "  sudo perf report --stdio --sort=symbol --no-children -n 2>/dev/null | head -60"
+    echo ""
+    echo "Or run with --profile to do it automatically:"
+    echo "  ./deploy_lt_debug.sh --profile"
+fi
+
+echo ""
+echo "=========================================="
+echo "Restore Production Binary When Done"
+echo "=========================================="
+echo ""
+echo "Run this to restore the production binary:"
+echo "  ./deploy_lt.sh"
+echo ""
+echo "Or manually on the server:"
+echo "  sudo cp '$REMOTE_PROD_BACKUP' '$REMOTE_BINARY_PATH'"
+echo "  sudo systemctl restart $SERVICE_NAME"
+echo ""

docs/NIP-42_Authentication.md

@@ -0,0 +1,295 @@
+# NIP-42 Authentication Implementation
+
+## Overview
+
+This relay implements NIP-42 (Authentication of clients to relays) providing granular authentication controls for event submission and subscription operations. The implementation supports both challenge-response authentication and per-connection state management.
+
+## Architecture
+
+### Core Components
+
+1. **Per-Session Authentication State** (`struct per_session_data`)
+   - `authenticated`: Boolean flag indicating authentication status
+   - `authenticated_pubkey[65]`: Hex-encoded public key of authenticated user
+   - `active_challenge[65]`: Current authentication challenge
+   - `challenge_created`: Timestamp when challenge was generated
+   - `challenge_expires`: Challenge expiration timestamp
+   - `nip42_auth_required_events`: Whether auth is required for EVENT submission
+   - `nip42_auth_required_subscriptions`: Whether auth is required for REQ operations
+   - `auth_challenge_sent`: Flag indicating if challenge has been sent
+
+2. **Challenge Management** (via `request_validator.c`)
+   - `nostr_nip42_generate_challenge()`: Generates cryptographically secure challenges
+   - `nostr_nip42_verify_auth_event()`: Validates signed authentication events
+   - Challenge storage and cleanup with expiration handling
+
+3. **WebSocket Protocol Integration**
+   - AUTH message handling in `nostr_relay_callback()`
+   - Challenge generation and transmission
+   - Authentication verification and session state updates
+
+## Configuration Options
+
+### Event-Based Configuration
+
+NIP-42 authentication is configured using kind 33334 configuration events with the following tags:
+
+| Tag | Description | Default | Values |
+|-----|-------------|---------|--------|
+| `nip42_auth_required_events` | Require auth for EVENT submission | `false` | `true`/`false` |
+| `nip42_auth_required_subscriptions` | Require auth for REQ operations | `false` | `true`/`false` |
+
+### Example Configuration Event
+
+```json
+{
+  "kind": 33334,
+  "content": "C Nostr Relay Configuration",
+  "tags": [
+    ["d", "<relay_pubkey>"],
+    ["nip42_auth_required_events", "true"],
+    ["nip42_auth_required_subscriptions", "false"],
+    ["relay_description", "Authenticated Nostr Relay"]
+  ],
+  "created_at": 1640995200,
+  "pubkey": "<admin_pubkey>",
+  "id": "<event_id>",
+  "sig": "<signature>"
+}
+```
+
+## Authentication Flow
+
+### 1. Challenge Generation
+
+When authentication is required and client is not authenticated:
+
+```
+Client -> Relay: ["EVENT", <event>] (unauthenticated)
+Relay -> Client: ["AUTH", <challenge>]
+```
+
+The challenge is a 64-character hex string generated using cryptographically secure random numbers.
+
+### 2. Authentication Response
+
+Client creates and signs an authentication event (kind 22242):
+
+```json
+{
+  "kind": 22242,
+  "content": "",
+  "tags": [
+    ["relay", "ws://relay.example.com"],
+    ["challenge", "<challenge_from_relay>"]
+  ],
+  "created_at": <current_timestamp>,
+  "pubkey": "<client_pubkey>",
+  "id": "<event_id>",
+  "sig": "<signature>"
+}
+```
+
+Client sends this event back to relay:
+
+```
+Client -> Relay: ["AUTH", <signed_auth_event>]
+```
+
+### 3. Verification and Session Update
+
+The relay:
+1. Validates the authentication event signature
+2. Verifies the challenge matches the one sent
+3. Checks challenge expiration (default: 10 minutes)
+4. Updates session state with authenticated public key
+5. Sends confirmation notice
+
+```
+Relay -> Client: ["NOTICE", "NIP-42 authentication successful"]
+```
+
+## Granular Authentication Controls
+
+### Separate Controls for Events vs Subscriptions
+
+The implementation provides separate authentication requirements:
+
+- **Event Submission**: Control whether clients must authenticate to publish events
+- **Subscription Access**: Control whether clients must authenticate to create subscriptions
+
+This allows flexible relay policies:
+- **Public Read, Authenticated Write**: `events=true, subscriptions=false`
+- **Fully Authenticated**: `events=true, subscriptions=true`
+- **Public Access**: `events=false, subscriptions=false` (default)
+- **Authenticated Read Only**: `events=false, subscriptions=true`
+
+### Per-Connection State
+
+Each WebSocket connection maintains its own authentication state:
+- Authentication persists for the lifetime of the connection
+- Challenges expire after 10 minutes
+- Session cleanup on connection close
+
+## Security Features
+
+### Challenge Security
+- 64-character hexadecimal challenges (256 bits of entropy)
+- Cryptographically secure random generation
+- Challenge expiration to prevent replay attacks
+- One-time use challenges
+
+### Event Validation
+- Complete signature verification using secp256k1
+- Event ID validation
+- Challenge-response binding verification
+- Timestamp validation with configurable tolerance
+
+### Session Management
+- Thread-safe per-session state management
+- Automatic cleanup on disconnection
+- Challenge expiration handling
+
+## Client Integration
+
+### Using nak Client
+
+```bash
+# Generate keypair
+PRIVKEY=$(nak key --gen)
+PUBKEY=$(nak key --pub $PRIVKEY)
+
+# Connect and authenticate automatically
+nak event -k 1 --content "Authenticated message" --sec $PRIVKEY --relay ws://localhost:8888
+
+# nak handles NIP-42 authentication automatically when required
+```
+
+### Manual WebSocket Integration
+
+```javascript
+const ws = new WebSocket('ws://localhost:8888');
+
+ws.onmessage = (event) => {
+  const message = JSON.parse(event.data);
+  
+  if (message[0] === 'AUTH') {
+    const challenge = message[1];
+    
+    // Create auth event (kind 22242)
+    const authEvent = {
+      kind: 22242,
+      content: "",
+      tags: [
+        ["relay", "ws://localhost:8888"],
+        ["challenge", challenge]
+      ],
+      created_at: Math.floor(Date.now() / 1000),
+      pubkey: clientPubkey,
+      // ... calculate id and signature
+    };
+    
+    // Send auth response
+    ws.send(JSON.stringify(["AUTH", authEvent]));
+  }
+};
+
+// Send event (may trigger AUTH challenge)
+ws.send(JSON.stringify(["EVENT", myEvent]));
+```
+
+## Administration
+
+### Enabling Authentication
+
+1. **Get Admin Private Key**: Extract from relay startup logs (shown once)
+2. **Create Configuration Event**: Use nak or custom tooling
+3. **Publish Configuration**: Send to relay with admin signature
+
+```bash
+# Enable auth for events only
+nak event -k 33334 \
+  --content "C Nostr Relay Configuration" \
+  --tag "d=$RELAY_PUBKEY" \
+  --tag "nip42_auth_required_events=true" \
+  --tag "nip42_auth_required_subscriptions=false" \
+  --sec $ADMIN_PRIVKEY \
+  --relay ws://localhost:8888
+```
+
+### Monitoring Authentication
+
+- Check relay logs for authentication events
+- Monitor `NOTICE` messages for auth status
+- Use `get_settings.sh` script to view current configuration
+
+```bash
+./get_settings.sh
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Challenge Expiration**
+   - Default: 10 minutes
+   - Client must respond within expiration window
+   - Generate new challenge for expired attempts
+
+2. **Signature Verification Failures**
+   - Verify event structure matches NIP-42 specification
+   - Check challenge value matches exactly
+   - Ensure proper secp256k1 signature generation
+
+3. **Configuration Not Applied**
+   - Verify admin private key is correct
+   - Check configuration event signature
+   - Ensure relay pubkey in 'd' tag matches relay
+
+### Debug Commands
+
+```bash
+# Check supported NIPs
+curl -H "Accept: application/nostr+json" http://localhost:8888 | jq .supported_nips
+
+# View current configuration
+nak req -k 33334 ws://localhost:8888 | jq .
+
+# Test authentication flow
+./tests/42_nip_test.sh
+```
+
+## Performance Considerations
+
+- Challenge generation: ~1ms overhead per unauthenticated connection
+- Authentication verification: ~2-5ms per auth event
+- Memory overhead: ~200 bytes per connection for auth state
+- Database impact: Configuration events cached, minimal query overhead
+
+## Integration with Other NIPs
+
+### NIP-01 (Basic Protocol)
+- AUTH messages integrated into standard WebSocket flow
+- Compatible with existing EVENT/REQ/CLOSE message handling
+
+### NIP-11 (Relay Information)
+- NIP-42 advertised in `supported_nips` array
+- Authentication requirements reflected in relay metadata
+
+### NIP-20 (Command Results)
+- OK responses include authentication-related error messages
+- NOTICE messages provide authentication status updates
+
+## Future Extensions
+
+### Potential Enhancements
+- Role-based authentication (admin, user, read-only)
+- Time-based access controls
+- Rate limiting based on authentication status
+- Integration with external authentication providers
+
+### Configuration Extensions
+- Per-kind authentication requirements
+- Whitelist/blacklist integration
+- Custom challenge expiration times
+- Authentication logging and metrics

docs/admin_api_plan.md

@@ -0,0 +1,460 @@
+# C-Relay-PG Administrator API Implementation Plan
+
+## Problem Analysis
+
+### Current Issues Identified:
+
+1. **Schema Mismatch**: Storage system (config.c) vs Validation system (request_validator.c) use different column names and values
+2. **Missing API Endpoint**: No way to clear auth_rules table for testing
+3. **Configuration Gap**: Auth rules enforcement may not be properly enabled
+4. **Documentation Gap**: Admin API commands not documented
+
+### Root Cause: Auth Rules Schema Inconsistency
+
+**Current Schema (sql_schema.h lines 140-150):**
+```sql
+CREATE TABLE auth_rules (
+    rule_type TEXT CHECK (rule_type IN ('whitelist', 'blacklist')),
+    pattern_type TEXT CHECK (pattern_type IN ('pubkey', 'hash')),  
+    pattern_value TEXT,
+    action TEXT CHECK (action IN ('allow', 'deny')),
+    active INTEGER DEFAULT 1
+);
+```
+
+**Storage Implementation (config.c):**
+- Stores: `rule_type='blacklist'`, `pattern_type='pubkey'`, `pattern_value='hex'`, `action='allow'`
+
+**Validation Implementation (request_validator.c):**
+- Queries: `rule_type='pubkey_blacklist'`, `rule_target='hex'`, `operation='event'`, `enabled=1`
+
+**MISMATCH**: Validator looks for non-existent columns and wrong rule_type values!
+
+## Proposed Solution Architecture
+
+### Phase 1: API Documentation & Standardization
+
+#### Admin API Commands (via WebSocket with admin private key)
+
+**Kind 23456: Unified Admin API (Ephemeral)**
+- Configuration management: Update relay settings, limits, authentication policies
+- Auth rules: Add/remove/query whitelist/blacklist rules
+- System commands: clear rules, status, cache management
+- **Unified Format**: All commands use NIP-44 encrypted content with `["p", "relay_pubkey"]` tags
+- **Command Types**:
+  - Configuration: `["config_key", "config_value"]`
+  - Auth rules: `["rule_type", "pattern_type", "pattern_value"]`
+  - Queries: `["auth_query", "filter"]` or `["system_command", "command_name"]`
+- **Security**: All admin commands use NIP-44 encryption for privacy and security
+
+#### Configuration Commands (using Kind 23456)
+
+1. **Update Configuration**:
+   ```json
+   {
+     "kind": 23456,
+     "content": "base64_nip44_encrypted_command_array",
+     "tags": [["p", "relay_pubkey"]]
+   }
+   ```
+   *Encrypted content contains:* `["relay_description", "My Relay"]`
+
+2. **Query System Status**:
+   ```json
+   {
+     "kind": 23456,
+     "content": "base64_nip44_encrypted_command_array",
+     "tags": [["p", "relay_pubkey"]]
+   }
+   ```
+   *Encrypted content contains:* `["system_command", "system_status"]`
+
+#### Auth Rules and System Commands (using Kind 23456)
+
+1. **Clear All Auth Rules**:
+   ```json
+   {
+     "kind": 23456,
+     "content": "base64_nip44_encrypted_command_array",
+     "tags": [["p", "relay_pubkey"]]
+   }
+   ```
+   *Encrypted content contains:* `["system_command", "clear_all_auth_rules"]`
+
+2. **Query All Auth Rules**:
+   ```json
+   {
+     "kind": 23456,
+     "content": "base64_nip44_encrypted_command_array",
+     "tags": [["p", "relay_pubkey"]]
+   }
+   ```
+   *Encrypted content contains:* `["auth_query", "all"]`
+
+3. **Add Blacklist Rule**:
+   ```json
+   {
+     "kind": 23456,
+     "content": "base64_nip44_encrypted_command_array",
+     "tags": [["p", "relay_pubkey"]]
+   }
+   ```
+   *Encrypted content contains:* `["blacklist", "pubkey", "deadbeef1234abcd..."]`
+
+### Phase 2: Auth Rules Schema Alignment
+
+#### Option A: Fix Validator to Match Schema (RECOMMENDED)
+
+**Update request_validator.c:**
+```sql
+-- OLD (broken):
+WHERE rule_type = 'pubkey_blacklist' AND rule_target = ? AND operation = ? AND enabled = 1
+
+-- NEW (correct):
+WHERE rule_type = 'blacklist' AND pattern_type = 'pubkey' AND pattern_value = ? AND active = 1
+```
+
+**Benefits:**
+- Matches actual database schema
+- Simpler rule_type values ('blacklist' vs 'pubkey_blacklist')  
+- Uses existing columns (pattern_value vs rule_target)
+- Consistent with storage implementation
+
+#### Option B: Update Schema to Match Validator (NOT RECOMMENDED)
+
+Would require changing schema, migration scripts, and storage logic.
+
+### Phase 3: Implementation Priority
+
+#### High Priority (Critical for blacklist functionality):
+1. Fix request_validator.c schema mismatch
+2. Ensure auth_required configuration is enabled
+3. Update tests to use unified ephemeral event kind (23456)
+4. Test blacklist enforcement
+
+#### Medium Priority (Enhanced Admin Features):
+1. **Implement NIP-44 Encryption Support**:
+   - Detect NIP-44 encrypted content for Kind 23456 events
+   - Parse `encrypted_tags` field from content JSON
+   - Decrypt using admin privkey and relay pubkey
+   - Process decrypted tags as normal commands
+2. Add clear_all_auth_rules system command
+3. Add auth rule query functionality (both standard and encrypted modes)
+4. Add configuration discovery (list available config keys)
+5. Enhanced error reporting in admin API
+6. Conflict resolution (same pubkey in whitelist + blacklist)
+
+#### Security Priority (NIP-44 Implementation):
+1. **Encryption Detection Logic**: Check for empty tags + encrypted_tags field
+2. **Key Pair Management**: Use admin private key + relay public key for NIP-44
+3. **Backward Compatibility**: Support both standard and encrypted modes
+4. **Error Handling**: Graceful fallback if decryption fails
+5. **Performance**: Cache decrypted results to avoid repeated decryption
+
+#### Low Priority (Documentation & Polish):
+1. Complete README.md API documentation
+2. Example usage scripts
+3. Admin client tools
+
+### Phase 4: Expected API Structure
+
+#### README.md Documentation Format:
+
+```markdown
+# C-Relay-PG Administrator API
+
+## Authentication
+All admin commands require signing with the admin private key generated during first startup.
+
+## Unified Admin API (Kind 23456 - Ephemeral)
+Update relay configuration parameters or query available settings.
+
+**Configuration Update Event:**
+```json
+{
+  "kind": 23456,
+  "content": "base64_nip44_encrypted_command_array",
+  "tags": [["p", "relay_pubkey"]]
+}
+```
+*Encrypted content contains:* `["relay_description", "My Relay Description"]`
+
+**Auth Rules Management:**
+
+**Add Rule Event:**
+```json
+{
+  "kind": 23456,
+  "content": "{\"action\":\"add\",\"description\":\"Block malicious user\"}",
+  "tags": [
+    ["blacklist", "pubkey", "deadbeef1234..."]
+  ]
+}
+```
+
+**Remove Rule Event:**
+```json
+{
+  "kind": 23456,
+  "content": "{\"action\":\"remove\",\"description\":\"Unblock user\"}",
+  "tags": [
+    ["blacklist", "pubkey", "deadbeef1234..."]
+  ]
+}
+```
+
+**Query All Auth Rules:**
+```json
+{
+  "kind": 23456,
+  "content": "{\"query\":\"list_auth_rules\",\"description\":\"Get all rules\"}",
+  "tags": [
+    ["auth_query", "all"]
+  ]
+}
+```
+
+**Query Whitelist Rules Only:**
+```json
+{
+  "kind": 23456,
+  "content": "{\"query\":\"list_auth_rules\",\"description\":\"Get whitelist\"}",
+  "tags": [
+    ["auth_query", "whitelist"]
+  ]
+}
+```
+
+**Check Specific Pattern:**
+```json
+{
+  "kind": 23456,
+  "content": "{\"query\":\"check_pattern\",\"description\":\"Check if pattern exists\"}",
+  "tags": [
+    ["auth_query", "pattern", "deadbeef1234..."]
+  ]
+}
+```
+
+## System Management (Kind 23456 - Ephemeral)
+System administration commands using the same kind as auth rules.
+
+**Clear All Auth Rules:**
+```json
+{
+  "kind": 23456,
+  "content": "{\"action\":\"clear_all\",\"description\":\"Clear all auth rules\"}",
+  "tags": [
+    ["system_command", "clear_all_auth_rules"]
+  ]
+}
+```
+
+**System Status:**
+```json
+{
+  "kind": 23456,
+  "content": "{\"action\":\"system_status\",\"description\":\"Get system status\"}",
+  "tags": [
+    ["system_command", "system_status"]
+  ]
+}
+```
+
+## Response Format
+All admin commands return JSON responses via WebSocket:
+
+**Success Response:**
+```json
+["OK", "event_id", true, "success_message"]
+```
+
+**Error Response:**  
+```json
+["OK", "event_id", false, "error_message"]
+```
+
+## Configuration Keys
+- `relay_description`: Relay description text
+- `relay_contact`: Contact information  
+- `auth_enabled`: Enable authentication system
+- `max_connections`: Maximum concurrent connections
+- `pow_min_difficulty`: Minimum proof-of-work difficulty
+- ... (full list of config keys)
+
+## Examples
+
+### Enable Authentication & Add Blacklist
+```bash
+# 1. Enable auth system
+nak event -k 23456 --content "base64_nip44_encrypted_command" \
+  -t "auth_enabled=true" \
+  --sec $ADMIN_PRIVKEY | nak event ws://localhost:8888
+
+# 2. Add user to blacklist
+nak event -k 23456 --content '{"action":"add","description":"Spam user"}' \
+  -t "blacklist=pubkey;$SPAM_USER_PUBKEY" \
+  --sec $ADMIN_PRIVKEY | nak event ws://localhost:8888
+
+# 3. Query all auth rules
+nak event -k 23456 --content '{"query":"list_auth_rules","description":"Get all rules"}' \
+  -t "auth_query=all" \
+  --sec $ADMIN_PRIVKEY | nak event ws://localhost:8888
+
+# 4. Clear all rules for testing
+nak event -k 23456 --content '{"action":"clear_all","description":"Clear all rules"}' \
+  -t "system_command=clear_all_auth_rules" \
+  --sec $ADMIN_PRIVKEY | nak event ws://localhost:8888
+```
+
+## Expected Response Formats
+
+### Configuration Query Response
+```json
+["EVENT", "subscription_id", {
+  "kind": 23457,
+  "content": "base64_nip44_encrypted_response",
+  "tags": [["p", "admin_pubkey"]]
+}]
+```
+
+### Current Config Response
+```json
+["EVENT", "subscription_id", {
+  "kind": 23457,
+  "content": "base64_nip44_encrypted_response",
+  "tags": [["p", "admin_pubkey"]]
+}]
+```
+
+### Auth Rules Query Response
+```json
+["EVENT", "subscription_id", {
+  "kind": 23456,
+  "content": "{\"auth_rules\": [{\"rule_type\": \"blacklist\", \"pattern_type\": \"pubkey\", \"pattern_value\": \"deadbeef...\"}, {\"rule_type\": \"whitelist\", \"pattern_type\": \"pubkey\", \"pattern_value\": \"cafebabe...\"}]}",
+  "tags": [["response_type", "auth_rules_list"], ["query_type", "all"]]
+}]
+```
+
+### Pattern Check Response
+```json
+["EVENT", "subscription_id", {
+  "kind": 23456,
+  "content": "{\"pattern_exists\": true, \"rule_type\": \"blacklist\", \"pattern_value\": \"deadbeef...\"}",
+  "tags": [["response_type", "pattern_check"], ["pattern", "deadbeef..."]]
+}]
+```
+
+## Implementation Steps
+
+1. **Document API** (this file) ✅
+2. **Update to ephemeral event kinds** ✅
+3. **Fix request_validator.c** schema mismatch
+4. **Update tests** to use unified Kind 23456
+5. **Add auth rule query functionality**
+6. **Add configuration discovery feature**
+7. **Test blacklist functionality**
+8. **Add remaining system commands**
+
+## Testing Plan
+
+1. Fix schema mismatch and test basic blacklist
+2. Add clear_auth_rules and test table cleanup
+3. Test whitelist/blacklist conflict scenarios  
+4. Test all admin API commands end-to-end
+5. Update integration tests
+
+This plan addresses the immediate blacklist issue while establishing a comprehensive admin API framework for future expansion.
+
+## NIP-44 Encryption Implementation Details
+
+### Server-Side Detection Logic
+```c
+// In admin event processing function
+bool is_encrypted_command(struct nostr_event *event) {
+    // Check if Kind 23456 with NIP-44 encrypted content
+    if (event->kind == 23456 &&
+        event->tags_count == 0) {
+        return true;
+    }
+    return false;
+}
+
+cJSON *decrypt_admin_tags(struct nostr_event *event) {
+    cJSON *content_json = cJSON_Parse(event->content);
+    if (!content_json) return NULL;
+    
+    cJSON *encrypted_tags = cJSON_GetObjectItem(content_json, "encrypted_tags");
+    if (!encrypted_tags) {
+        cJSON_Delete(content_json);
+        return NULL;
+    }
+    
+    // Decrypt using NIP-44 with admin pubkey and relay privkey
+    char *decrypted = nip44_decrypt(
+        cJSON_GetStringValue(encrypted_tags),
+        admin_pubkey,           // Shared secret with admin
+        relay_private_key       // Our private key
+    );
+    
+    cJSON *decrypted_tags = cJSON_Parse(decrypted);
+    free(decrypted);
+    cJSON_Delete(content_json);
+    
+    return decrypted_tags; // Returns tag array: [["key1", "val1"], ["key2", "val2"]]
+}
+```
+
+### Admin Event Processing Flow
+1. **Receive Event**: Kind 23456 with admin signature
+2. **Check Mode**: Empty tags = encrypted, populated tags = standard
+3. **Decrypt if Needed**: Extract and decrypt `encrypted_tags` from content
+4. **Process Commands**: Use decrypted/standard tags for command processing
+5. **Execute**: Same logic for both modes after tag extraction
+6. **Respond**: Standard response format (optionally encrypt response)
+
+### Security Benefits
+- **Command Privacy**: Admin operations invisible in event tags
+- **Replay Protection**: NIP-44 includes timestamp/randomness
+- **Key Management**: Uses existing admin/relay key pair
+- **Backward Compatible**: Standard mode still works
+- **Performance**: Only decrypt when needed (empty tags detection)
+
+### NIP-44 Library Integration
+The relay will need to integrate a NIP-44 encryption/decryption library:
+
+```c
+// Required NIP-44 functions
+char* nip44_encrypt(const char* plaintext, const char* sender_privkey, const char* recipient_pubkey);
+char* nip44_decrypt(const char* ciphertext, const char* recipient_privkey, const char* sender_pubkey);
+```
+
+### Implementation Priority (Updated)
+
+#### Phase 1: Core Infrastructure (Complete)
+- [x] Event-based admin authentication system
+- [x] Kind 23456 (Unified Admin API) processing
+- [x] Basic configuration parameter updates
+- [x] Auth rule add/remove/clear functionality
+- [x] Updated to ephemeral event kinds
+- [x] Designed NIP-44 encryption support
+
+#### Phase 2: NIP-44 Encryption Support (Next Priority)
+- [ ] **Add NIP-44 library dependency** to project
+- [ ] **Implement encryption detection logic** (`is_encrypted_command()`)
+- [ ] **Add decrypt_admin_tags() function** with NIP-44 support
+- [ ] **Update admin command processing** to handle both modes
+- [ ] **Test encrypted admin commands** end-to-end
+
+#### Phase 3: Enhanced Features
+- [ ] **Auth rule query functionality** (both standard and encrypted modes)
+- [ ] **Configuration discovery API** (list available config keys)
+- [ ] **Enhanced error messages** with encryption status
+- [ ] **Performance optimization** (caching, async decrypt)
+
+#### Phase 4: Schema Fixes (Critical)
+- [ ] **Fix request_validator.c** schema mismatch
+- [ ] **Enable blacklist enforcement** with encrypted commands
+- [ ] **Update tests** to use both standard and encrypted modes
+
+This enhanced admin API provides enterprise-grade security while maintaining ease of use for basic operations.

docs/agent_browser_testing.md

@@ -0,0 +1,190 @@
+# Agent Browser Testing Guide for C-Relay-PG
+
+This document explains how to use the `agent-browser` CLI tool to test the c-relay-pg admin web UI from an AI agent context (no physical display required).
+
+## Prerequisites
+
+- **agent-browser** installed globally: `npm install -g agent-browser`
+- Binary location: `/home/user/.nvm/versions/node/v24.14.1/bin/agent-browser`
+- The relay must be running locally (default port 8888)
+- Test keys configured in `.test_keys`
+
+## Starting the Relay for Local Testing
+
+```bash
+./make_and_restart_relay.sh -t
+```
+
+This reads `.test_keys` and starts the relay with:
+- `ADMIN_PUBKEY` — the hex public key of the admin account
+- `ADMIN_PRIVKEY` — the hex secret key (used for browser login, not by the relay itself)
+- `SERVER_PRIVKEY` — the relay's own private key
+
+## Key URLs
+
+| URL | Purpose |
+|-----|---------|
+| `http://127.0.0.1:8888/api/index.html` | Admin web UI (the correct entry point) |
+| `http://127.0.0.1:8888/` | Returns 406 without NIP-11 Accept header — **do not use for browser testing** |
+| `http://127.0.0.1:8888/` with `Accept: application/nostr+json` | NIP-11 relay info JSON |
+
+**Important:** The root URL `/` is a WebSocket/NIP-11 endpoint, not an HTML page. Always use `/api/index.html` for browser testing.
+
+## Admin Login Credentials
+
+The admin nsec for the current `.test_keys` configuration:
+
+```
+nsec: nsec1zkn0hlt4jvcvn9yt5p7ea4m7f82pf3ph0gj3d4rlcz4s64x5z86satv9qm
+hex:  15a6fbfd759330c9948ba07d9ed77e49d414c4377a2516d47fc0ab0d54d411f5
+npub: npub1tlyzk6slzt8d989f4pn3synk98fea64ea3jmrdc7dtd0kw8uxlas9a9fwr
+hex pubkey: 5fc82b6a1f12ced29ca9a86718127629d39eeab9ec65b1b71e6adafb38fc37fb
+```
+
+## Complete Login Flow with agent-browser
+
+### Step 1: Open the admin UI
+
+```bash
+agent-browser open http://127.0.0.1:8888/api/index.html
+agent-browser wait --load networkidle
+```
+
+### Step 2: Take an interactive snapshot to see what is on screen
+
+```bash
+agent-browser snapshot -i
+```
+
+You will see a login modal with buttons like:
+- `"Browser Extension"` — skip this
+- `"Local Key"` — **use this one**
+- `"Seed Phrase"` — skip
+- `"Nostr Connect"` — skip
+- `"Read Only"` — skip
+
+### Step 3: Click "Local Key"
+
+```bash
+agent-browser click @e15
+```
+
+(The ref number may vary — use the ref from the snapshot output for the "Local Key" button.)
+
+After clicking, a text input appears asking for the secret key.
+
+### Step 4: Enter the admin nsec
+
+```bash
+agent-browser fill @e14 "nsec1zkn0hlt4jvcvn9yt5p7ea4m7f82pf3ph0gj3d4rlcz4s64x5z86satv9qm"
+```
+
+(Use the ref from the snapshot for the textbox element.)
+
+### Step 5: Click "Import Key"
+
+```bash
+agent-browser snapshot -i
+```
+
+Check the snapshot — the "Import Key" button should now be enabled. Click it:
+
+```bash
+agent-browser click @e15
+```
+
+### Step 6: Click "Continue" on the success screen
+
+After import, a success screen appears with "Continue" button:
+
+```bash
+agent-browser wait 800
+agent-browser snapshot -i
+agent-browser click @e19
+```
+
+(Use the ref from the snapshot for the "Continue" button.)
+
+### Step 7: Wait for admin UI to load
+
+```bash
+agent-browser wait 5000
+agent-browser snapshot -i
+```
+
+You should now see the admin dashboard with:
+- Statistics table (Database Size, Total Events, PID, etc.)
+- Navigation buttons (Statistics, Subscriptions, Configuration, Authorization, etc.)
+- Admin profile area showing "admin" label
+
+## Navigating Admin Sections
+
+After login, use the sidebar navigation buttons:
+
+```bash
+# View configuration
+agent-browser click @e8    # Configuration button ref
+
+# View authorization rules
+agent-browser click @e9    # Authorization button ref
+
+# View statistics
+agent-browser click @e6    # Statistics button ref
+
+# Always snapshot after navigation to see results
+agent-browser wait 2500
+agent-browser snapshot -i
+```
+
+## Checking for Errors
+
+```bash
+# View browser console logs
+agent-browser console
+
+# View JavaScript errors
+agent-browser errors
+
+# View relay server logs
+tail -n 100 relay.log
+```
+
+## Chained Command Example (Full Login in One Shot)
+
+```bash
+agent-browser open http://127.0.0.1:8888/api/index.html && \
+agent-browser wait --load networkidle && \
+agent-browser snapshot -i
+```
+
+Then use refs from the snapshot to complete login steps.
+
+## Tips for AI Agents
+
+1. **Always use `/api/index.html`** — never the root URL
+2. **Use `snapshot -i`** after every action to see the current interactive elements and their refs
+3. **Refs change** between snapshots — always re-snapshot before clicking
+4. **Wait after clicks** — use `agent-browser wait 2000` (milliseconds) between actions that trigger async operations
+5. **The login flow has 3 screens**: method selection → key input → success confirmation
+6. **Console logs are cumulative** — they show all logs since page load, which is useful for debugging admin API responses
+7. **The relay log** at `relay.log` shows server-side processing of admin commands
+8. **Command chaining** with `&&` works — the browser daemon persists between commands
+
+## Verifying Admin API is Working
+
+After login, the statistics page should show populated data:
+- Database Size (e.g., "4 KB")
+- Process ID (the relay PID)
+- WebSocket Connections count
+- Memory Usage
+
+If these show "-" or "Loading...", check:
+1. `relay.log` for errors
+2. `agent-browser console` for JavaScript errors
+3. `agent-browser errors` for page-level errors
+
+## Closing the Browser
+
+```bash
+agent-browser close --all
+```

docs/c_utils_lib_architecture.md

@@ -0,0 +1,457 @@
+# c_utils_lib Architecture Plan
+
+## Overview
+
+`c_utils_lib` is a standalone C utility library designed to provide reusable, general-purpose functions for C projects. It serves as a learning repository and a practical toolkit for common C programming tasks.
+
+## Design Philosophy
+
+1. **Zero External Dependencies**: Only standard C library dependencies
+2. **Modular Design**: Each utility is independent and can be used separately
+3. **Learning-Oriented**: Well-documented code suitable for learning C
+4. **Production-Ready**: Battle-tested utilities from real projects
+5. **Cross-Platform**: Works on Linux, macOS, and other POSIX systems
+
+## Repository Structure
+
+```
+c_utils_lib/
+├── README.md                    # Main documentation
+├── LICENSE                      # MIT License
+├── VERSION                      # Current version (e.g., v0.1.0)
+├── build.sh                     # Build script
+├── Makefile                     # Build system
+├── .gitignore                   # Git ignore rules
+│
+├── include/                     # Public headers
+│   ├── c_utils.h               # Main header (includes all utilities)
+│   ├── debug.h                 # Debug/logging system
+│   ├── version.h               # Version utilities
+│   ├── string_utils.h          # String utilities (future)
+│   └── memory_utils.h          # Memory utilities (future)
+│
+├── src/                        # Implementation files
+│   ├── debug.c                 # Debug system implementation
+│   ├── version.c               # Version utilities implementation
+│   ├── string_utils.c          # String utilities (future)
+│   └── memory_utils.c          # Memory utilities (future)
+│
+├── examples/                   # Usage examples
+│   ├── debug_example.c         # Debug system example
+│   ├── version_example.c       # Version utilities example
+│   └── Makefile                # Examples build system
+│
+├── tests/                      # Unit tests
+│   ├── test_debug.c            # Debug system tests
+│   ├── test_version.c          # Version utilities tests
+│   ├── run_tests.sh            # Test runner
+│   └── Makefile                # Tests build system
+│
+└── docs/                       # Additional documentation
+    ├── API.md                  # Complete API reference
+    ├── INTEGRATION.md          # How to integrate into projects
+    ├── VERSIONING.md           # Versioning system guide
+    └── CONTRIBUTING.md         # Contribution guidelines
+```
+
+## Initial Utilities (v0.1.0)
+
+### 1. Debug System (`debug.h`, `debug.c`)
+
+**Purpose**: Unified logging and debugging system with configurable verbosity levels.
+
+**Features**:
+- 5 debug levels: NONE, ERROR, WARN, INFO, DEBUG, TRACE
+- Timestamp formatting
+- File/line information at TRACE level
+- Macro-based API for zero-cost when disabled
+- Thread-safe (future enhancement)
+
+**API**:
+```c
+// Initialization
+void debug_init(int level);
+
+// Logging macros
+DEBUG_ERROR(format, ...);
+DEBUG_WARN(format, ...);
+DEBUG_INFO(format, ...);
+DEBUG_LOG(format, ...);
+DEBUG_TRACE(format, ...);
+
+// Global debug level
+extern debug_level_t g_debug_level;
+```
+
+**Usage Example**:
+```c
+#include <c_utils/debug.h>
+
+int main() {
+    debug_init(DEBUG_LEVEL_INFO);
+    DEBUG_INFO("Application started");
+    DEBUG_ERROR("Critical error: %s", error_msg);
+    return 0;
+}
+```
+
+### 2. Version Utilities (`version.h`, `version.c`)
+
+**Purpose**: Reusable versioning system for C projects using git tags.
+
+**Features**:
+- Automatic version extraction from git tags
+- Semantic versioning support (MAJOR.MINOR.PATCH)
+- Version comparison functions
+- Header file generation for embedding version info
+- Build number tracking
+
+**API**:
+```c
+// Version structure
+typedef struct {
+    int major;
+    int minor;
+    int patch;
+    char* git_hash;
+    char* build_date;
+} version_info_t;
+
+// Get version from git
+int version_get_from_git(version_info_t* version);
+
+// Generate version header file
+int version_generate_header(const char* output_path, const char* prefix);
+
+// Compare versions
+int version_compare(version_info_t* v1, version_info_t* v2);
+
+// Format version string
+char* version_to_string(version_info_t* version);
+```
+
+**Usage Example**:
+```c
+#include <c_utils/version.h>
+
+// In your build system:
+version_generate_header("src/version.h", "MY_APP");
+
+// In your code:
+#include "version.h"
+printf("Version: %s\n", MY_APP_VERSION);
+```
+
+**Integration with Projects**:
+```bash
+# In project Makefile
+version.h:
+	c_utils_lib/bin/generate_version src/version.h MY_PROJECT
+```
+
+## Build System
+
+### Static Library Output
+
+```
+libc_utils.a          # Static library for linking
+```
+
+### Build Targets
+
+```bash
+make                  # Build static library
+make examples         # Build examples
+make test             # Run tests
+make install          # Install to system (optional)
+make clean            # Clean build artifacts
+```
+
+### Build Script (`build.sh`)
+
+```bash
+#!/bin/bash
+# Simplified build script similar to nostr_core_lib
+
+case "$1" in
+    lib|"")
+        make
+        ;;
+    examples)
+        make examples
+        ;;
+    test)
+        make test
+        ;;
+    clean)
+        make clean
+        ;;
+    install)
+        make install
+        ;;
+    *)
+        echo "Usage: ./build.sh [lib|examples|test|clean|install]"
+        exit 1
+        ;;
+esac
+```
+
+## Versioning System Design
+
+### How It Works
+
+1. **Git Tags as Source of Truth**
+   - Version tags: `v0.1.0`, `v0.2.0`, etc.
+   - Follows semantic versioning
+
+2. **Automatic Header Generation**
+   - Script reads git tags
+   - Generates header with version macros
+   - Includes build date and git hash
+
+3. **Reusable Across Projects**
+   - Each project calls `version_generate_header()`
+   - Customizable prefix (e.g., `C_RELAY_VERSION`, `NOSTR_CORE_VERSION`)
+   - No hardcoded version numbers in source
+
+### Example Generated Header
+
+```c
+// Auto-generated by c_utils_lib version system
+#ifndef MY_PROJECT_VERSION_H
+#define MY_PROJECT_VERSION_H
+
+#define MY_PROJECT_VERSION "v0.1.0"
+#define MY_PROJECT_VERSION_MAJOR 0
+#define MY_PROJECT_VERSION_MINOR 1
+#define MY_PROJECT_VERSION_PATCH 0
+#define MY_PROJECT_GIT_HASH "a1b2c3d"
+#define MY_PROJECT_BUILD_DATE "2025-10-15"
+
+#endif
+```
+
+### Integration Pattern
+
+```makefile
+# In consuming project's Makefile
+VERSION_SCRIPT = c_utils_lib/bin/generate_version
+
+src/version.h: .git/refs/tags/*
+	$(VERSION_SCRIPT) src/version.h MY_PROJECT
+
+my_app: src/version.h src/main.c
+	$(CC) src/main.c -o my_app -Ic_utils_lib/include -Lc_utils_lib -lc_utils
+```
+
+## Future Utilities (Roadmap)
+
+### String Utilities (`string_utils.h`)
+- Safe string operations (bounds checking)
+- String trimming, splitting, joining
+- Case conversion
+- Pattern matching helpers
+
+### Memory Utilities (`memory_utils.h`)
+- Safe allocation wrappers
+- Memory pool management
+- Leak detection helpers (debug builds)
+- Arena allocators
+
+### Configuration Utilities (`config_utils.h`)
+- INI file parsing
+- JSON configuration (using cJSON)
+- Environment variable helpers
+- Command-line argument parsing
+
+### File Utilities (`file_utils.h`)
+- Safe file operations
+- Directory traversal
+- Path manipulation
+- File watching (inotify wrapper)
+
+### Time Utilities (`time_utils.h`)
+- Timestamp formatting
+- Duration calculations
+- Timer utilities
+- Rate limiting helpers
+
+## Integration Guide
+
+### As Git Submodule
+
+```bash
+# In your project
+git submodule add https://github.com/yourusername/c_utils_lib.git
+git submodule update --init --recursive
+
+# Build the library
+cd c_utils_lib && ./build.sh lib && cd ..
+
+# Update your Makefile
+INCLUDES += -Ic_utils_lib/include
+LIBS += -Lc_utils_lib -lc_utils
+```
+
+### In Your Makefile
+
+```makefile
+# Check if c_utils_lib is built
+c_utils_lib/libc_utils.a:
+	cd c_utils_lib && ./build.sh lib
+
+# Link against it
+my_app: c_utils_lib/libc_utils.a src/main.c
+	$(CC) src/main.c -o my_app \
+		-Ic_utils_lib/include \
+		-Lc_utils_lib -lc_utils
+```
+
+### In Your Code
+
+```c
+// Option 1: Include everything
+#include <c_utils/c_utils.h>
+
+// Option 2: Include specific utilities
+#include <c_utils/debug.h>
+#include <c_utils/version.h>
+
+int main() {
+    debug_init(DEBUG_LEVEL_INFO);
+    DEBUG_INFO("Starting application version %s", MY_APP_VERSION);
+    return 0;
+}
+```
+
+## Migration Plan for c-relay-pg
+
+### Phase 1: Extract Debug System
+1. Create `c_utils_lib` repository
+2. Move [`debug.c`](../src/debug.c) and [`debug.h`](../src/debug.h)
+3. Create build system
+4. Add basic tests
+
+### Phase 2: Add Versioning System
+1. Extract version generation logic from c-relay-pg
+2. Create reusable version utilities
+3. Update c-relay-pg to use new system
+4. Update nostr_core_lib to use new system
+
+### Phase 3: Add as Submodule
+1. Add `c_utils_lib` as submodule to c-relay-pg
+2. Update c-relay-pg Makefile
+3. Update includes in c-relay-pg source files
+4. Remove old debug files from c-relay-pg
+
+### Phase 4: Documentation & Examples
+1. Create comprehensive README
+2. Add usage examples
+3. Write integration guide
+4. Document API
+
+## Benefits
+
+### For c-relay-pg
+- Cleaner separation of concerns
+- Reusable utilities across projects
+- Easier to maintain and test
+- Consistent logging across codebase
+
+### For Learning C
+- Real-world utility implementations
+- Best practices examples
+- Modular design patterns
+- Build system examples
+
+### For Future Projects
+- Drop-in utility library
+- Proven, tested code
+- Consistent patterns
+- Time savings
+
+## Testing Strategy
+
+### Unit Tests
+- Test each utility independently
+- Mock external dependencies
+- Edge case coverage
+- Memory leak detection (valgrind)
+
+### Integration Tests
+- Test with real projects (c-relay-pg, nostr_core_lib)
+- Cross-platform testing
+- Performance benchmarks
+
+### Continuous Integration
+- GitHub Actions for automated testing
+- Multiple compiler versions (gcc, clang)
+- Multiple platforms (Linux, macOS)
+- Static analysis (cppcheck, clang-tidy)
+
+## Documentation Standards
+
+### Code Documentation
+- Doxygen-style comments
+- Function purpose and parameters
+- Return value descriptions
+- Usage examples in comments
+
+### API Documentation
+- Complete API reference in `docs/API.md`
+- Usage examples for each function
+- Common patterns and best practices
+- Migration guides
+
+### Learning Resources
+- Detailed explanations of implementations
+- Links to relevant C standards
+- Common pitfalls and how to avoid them
+- Performance considerations
+
+## License
+
+MIT License - permissive and suitable for learning and commercial use.
+
+## Version History
+
+- **v0.1.0** (Planned)
+  - Initial release
+  - Debug system
+  - Version utilities
+  - Basic documentation
+
+- **v0.2.0** (Future)
+  - String utilities
+  - Memory utilities
+  - Enhanced documentation
+
+- **v0.3.0** (Future)
+  - Configuration utilities
+  - File utilities
+  - Time utilities
+
+## Success Criteria
+
+1. ✅ Successfully integrated into c-relay-pg
+2. ✅ Successfully integrated into nostr_core_lib
+3. ✅ All tests passing
+4. ✅ Documentation complete
+5. ✅ Examples working
+6. ✅ Zero external dependencies (except standard library)
+7. ✅ Cross-platform compatibility verified
+
+## Next Steps
+
+1. Create repository structure
+2. Implement debug system
+3. Implement version utilities
+4. Create build system
+5. Write tests
+6. Create documentation
+7. Integrate into c-relay-pg
+8. Publish to GitHub
+
+---
+
+**Note**: This is a living document. Update as the library evolves and new utilities are added.