c-relay/admin_spec.md

# Ginxsom Admin System - Comprehensive Specification

## Overview

The Ginxsom admin system provides both programmatic (API-based) and interactive (web-based) administration capabilities for the Ginxsom Blossom server. The system is designed around Nostr-based authentication and supports multiple administration workflows including first-run setup, ongoing configuration management, and operational monitoring.

## Architecture Components

### 1. Configuration System
- **File-based configuration**: Signed Nostr events stored as JSON files following XDG Base Directory specification
- **Database configuration**: Key-value pairs stored in SQLite for runtime configuration
- **Interactive setup**: Command-line wizard for initial server configuration
- **Manual setup**: Scripts for generating signed configuration events

### 2. Authentication & Authorization
- **Nostr-based auth**: All admin operations require valid Nostr event signatures
- **Admin pubkey verification**: Only configured admin public keys can perform admin operations
- **Event validation**: Full cryptographic verification of Nostr events including structure, signature, and expiration
- **Method-specific authorization**: Different event types for different operations (upload, admin, delete, etc.)

### 3. API System
- **RESTful endpoints**: `/api/*` routes for programmatic administration
- **Command-line testing**: Complete test suite using `nak` and `curl`
- **JSON responses**: Structured data for all admin operations
- **CORS support**: Cross-origin requests for web admin interface

### 4. Web Interface (Future)
- **Single-page application**: Self-contained HTML file with inline CSS/JS
- **Real-time monitoring**: Statistics and system health dashboards
- **Configuration management**: GUI for server settings
- **File management**: Browse and manage uploaded blobs

## Configuration System Architecture

### File-based Configuration (Priority 1)

**Location**: Follows XDG Base Directory Specification
- `$XDG_CONFIG_HOME/ginxsom/ginxsom_config_event.json`
- Falls back to `$HOME/.config/ginxsom/ginxsom_config_event.json`

**Format**: Signed Nostr event containing server configuration
```json
{
  "kind": 33333,
  "created_at": 1704067200,
  "tags": [
    ["server_privkey", "server_private_key_hex"],
    ["cdn_origin", "https://cdn.example.com"],
    ["max_file_size", "104857600"],
    ["nip94_enabled", "true"]
  ],
  "content": "Ginxsom server configuration",
  "pubkey": "admin_public_key_hex",
  "id": "event_id_hash",
  "sig": "event_signature"
}
```

**Loading Process**:
1. Check for file-based config at XDG location
2. Validate Nostr event structure and signature
3. Extract configuration from event tags
4. Apply settings to server (database storage)
5. Fall back to database-only config if file missing/invalid

### Database Configuration (Priority 2)

**Table**: `server_config`
```sql
CREATE TABLE server_config (
    key TEXT PRIMARY KEY,
    value TEXT NOT NULL,
    description TEXT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```

**Key Configuration Items**:
- `admin_pubkey`: Authorized admin public key
- `admin_enabled`: Enable/disable admin interface
- `cdn_origin`: Base URL for blob access
- `max_file_size`: Maximum upload size in bytes
- `nip94_enabled`: Enable NIP-94 metadata emission
- `auth_rules_enabled`: Enable authentication rules system

### Setup Workflows

#### Interactive Setup (Command Line)
```bash
# First-run detection
if [[ ! -f "$XDG_CONFIG_HOME/ginxsom/ginxsom_config_event.json" ]]; then
    echo "=== Ginxsom First-Time Setup Required ==="
    echo "1. Run interactive setup wizard"
    echo "2. Exit and create config manually"
    read -p "Choice (1/2): " choice
    
    if [[ "$choice" == "1" ]]; then
        ./scripts/setup.sh
    else
        echo "Manual setup: Run ./scripts/generate_config.sh"
        exit 1
    fi
fi
```

#### Manual Setup (Script-based)
```bash
# Generate configuration event
./scripts/generate_config.sh --admin-key <admin_pubkey> \
    --server-key <server_privkey> \
    --cdn-origin "https://cdn.example.com" \
    --output "$XDG_CONFIG_HOME/ginxsom/ginxsom_config_event.json"
```

### C Implementation Functions

#### Configuration Loading
```c
// Get XDG-compliant config file path
int get_config_file_path(char* path, size_t path_size);

// Load and validate config event from file
int load_server_config(const char* config_path);

// Extract config from validated event and apply to server
int apply_config_from_event(cJSON* event);

// Interactive setup runner for first-run
int run_interactive_setup(const char* config_path);
```

#### Security Features
- Server private key stored only in memory (never in database)
- Config file must be signed Nostr event
- Full cryptographic validation of config events
- Admin pubkey verification for all operations

## Admin API Specification

### Authentication Model

All admin API endpoints (except `/api/health`) require Nostr authentication:

**Authorization Header Format**:
```
Authorization: Nostr <base64-encoded-event>
```

**Required Event Structure**:
```json
{
  "kind": 24242,
  "created_at": 1704067200,
  "tags": [
    ["t", "GET"],
    ["expiration", "1704070800"]
  ],
  "content": "admin_request",
  "pubkey": "admin_public_key",
  "id": "event_id",
  "sig": "event_signature"
}
```

### API Endpoints

#### GET /api/health
**Purpose**: System health check (no authentication required)
**Response**:
```json
{
  "status": "success",
  "data": {
    "database": "connected",
    "blob_directory": "accessible",
    "server_time": 1704067200,
    "uptime": 3600,
    "disk_usage": {
      "total_bytes": 1073741824,
      "used_bytes": 536870912,
      "available_bytes": 536870912,
      "usage_percent": 50.0
    }
  }
}
```

#### GET /api/stats
**Purpose**: Server statistics and metrics
**Authentication**: Required (admin pubkey)
**Response**:
```json
{
  "status": "success",
  "data": {
    "total_files": 1234,
    "total_bytes": 104857600,
    "total_size_mb": 100.0,
    "unique_uploaders": 56,
    "first_upload": 1693929600,
    "last_upload": 1704067200,
    "avg_file_size": 85049,
    "file_types": {
      "image/png": 45,
      "image/jpeg": 32,
      "application/pdf": 12,
      "other": 8
    }
  }
}
```

#### GET /api/config
**Purpose**: Retrieve current server configuration
**Authentication**: Required (admin pubkey)
**Response**:
```json
{
  "status": "success",
  "data": {
    "cdn_origin": "http://localhost:9001",
    "max_file_size": "104857600",
    "nip94_enabled": "true",
    "auth_rules_enabled": "false",
    "auth_cache_ttl": "300"
  }
}
```

#### PUT /api/config
**Purpose**: Update server configuration
**Authentication**: Required (admin pubkey)
**Request Body**:
```json
{
  "max_file_size": "209715200",
  "nip94_enabled": "true",
  "cdn_origin": "https://cdn.example.com"
}
```
**Response**:
```json
{
  "status": "success",
  "message": "Configuration updated successfully",
  "updated_keys": ["max_file_size", "cdn_origin"]
}
```

#### GET /api/files
**Purpose**: List recent files with pagination
**Authentication**: Required (admin pubkey)
**Parameters**:
- `limit` (default: 50): Number of files to return
- `offset` (default: 0): Pagination offset
**Response**:
```json
{
  "status": "success",
  "data": {
    "files": [
      {
        "sha256": "b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553",
        "size": 184292,
        "type": "application/pdf",
        "uploaded_at": 1725105921,
        "uploader_pubkey": "79be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798",
        "filename": "document.pdf",
        "url": "http://localhost:9001/b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf"
      }
    ],
    "total": 1234,
    "limit": 50,
    "offset": 0
  }
}
```

## Implementation Status

### ✅ Completed Components
1. **Database-based configuration loading** - Implemented in main.c
2. **Admin API authentication system** - Implemented in admin_api.c
3. **Nostr event validation** - Full cryptographic verification
4. **Admin pubkey verification** - Database-backed authorization
5. **Basic API endpoints** - Health, stats, config, files

### ✅ Recently Completed Components
1. **File-based configuration system** - Fully implemented in main.c with XDG compliance
2. **Interactive setup wizard** - Complete shell script with guided setup process (`scripts/setup.sh`)
3. **Manual config generation** - Full-featured command-line config generator (`scripts/generate_config.sh`)
4. **Testing infrastructure** - Comprehensive admin API test suite (`scripts/test_admin.sh`)
5. **Documentation system** - Complete setup and usage documentation (`scripts/README.md`)

### 📋 Planned Components
1. **Web admin interface** - Single-page HTML application
2. **Enhanced monitoring** - Real-time statistics dashboard
3. **Bulk operations** - Multi-file management APIs
4. **Configuration validation** - Advanced config checking
5. **Audit logging** - Admin action tracking

## Setup Instructions

### 1. Enable Admin Interface
```bash
# Configure admin pubkey and enable interface
sqlite3 db/ginxsom.db << EOF
INSERT OR REPLACE INTO server_config (key, value, description) VALUES
    ('admin_pubkey', 'your_admin_public_key_here', 'Authorized admin public key'),
    ('admin_enabled', 'true', 'Enable admin interface');
EOF
```

### 2. Test API Access
```bash
# Generate admin authentication event
ADMIN_PRIVKEY="your_admin_private_key"
EVENT=$(nak event -k 24242 -c "admin_request" \
    --tag t="GET" \
    --tag expiration="$(date -d '+1 hour' +%s)" \
    --sec "$ADMIN_PRIVKEY")

# Test admin API
AUTH_HEADER="Nostr $(echo "$EVENT" | base64 -w 0)"
curl -H "Authorization: $AUTH_HEADER" http://localhost:9001/api/stats
```

### 3. Configure File-based Setup (Future)
```bash
# Create XDG config directory
mkdir -p "$XDG_CONFIG_HOME/ginxsom"

# Generate signed config event
./scripts/generate_config.sh \
    --admin-key "your_admin_pubkey" \
    --server-key "generated_server_privkey" \
    --output "$XDG_CONFIG_HOME/ginxsom/ginxsom_config_event.json"
```

## Security Considerations

### Authentication Security
- **Event expiration**: All admin events must include expiration timestamps
- **Signature validation**: Full secp256k1 cryptographic verification
- **Replay protection**: Event IDs tracked to prevent reuse
- **Admin key rotation**: Support for updating admin pubkeys

### Configuration Security
- **File permissions**: Config files should be readable only by server user
- **Private key handling**: Server private keys never stored in database
- **Config validation**: All configuration changes validated before application
- **Backup verification**: Config events cryptographically verifiable

### Operational Security
- **Access logging**: All admin operations logged with timestamps
- **Rate limiting**: API endpoints protected against abuse
- **Input validation**: All user input sanitized and validated
- **Database security**: Prepared statements prevent SQL injection

## Future Enhancements

### 1. Web Admin Interface
- Self-contained HTML file with inline CSS/JavaScript
- Real-time monitoring dashboards
- Visual configuration management
- File upload/management interface

### 2. Advanced Monitoring
- Performance metrics collection
- Alert system for critical events
- Historical data trending
- Resource usage tracking

### 3. Multi-admin Support
- Multiple authorized admin pubkeys
- Role-based permissions (read-only vs full admin)
- Admin action audit trails
- Delegation capabilities

### 4. Integration Features
- Nostr relay integration for admin events
- Webhook notifications for admin actions
- External authentication providers
- API key management for programmatic access

This specification represents the current understanding and planned development of the Ginxsom admin system, focusing on security, usability, and maintainability.