ginxsom/docs/README_ADMIN_API.md

Ginxsom Admin API

A Nostr-compliant admin interface for the Ginxsom Blossom server that provides programmatic access to server statistics, configuration, and file management operations.

Overview

The admin API allows server administrators to:

• View server statistics (file counts, storage usage, user metrics)
• Retrieve and update server configuration settings
• Browse recent uploaded files with pagination
• Monitor server health and disk usage

All operations require Nostr authentication using admin-authorized public keys.

Quick Start

1. Configure Admin Access

Add your admin pubkey to the server configuration:

# Generate admin keys (keep private key secure!)
ADMIN_PRIVKEY=$(nak key generate)
ADMIN_PUBKEY=$(echo "$ADMIN_PRIVKEY" | nak key public)

# Configure server
sqlite3 db/ginxsom.db << EOF
INSERT OR REPLACE INTO server_config (key, value, description) VALUES
    ('admin_pubkey', '$ADMIN_PUBKEY', 'Nostr public key authorized for admin operations'),
    ('admin_enabled', 'true', 'Enable admin interface');
EOF

2. Build and Start Server

make clean && make
spawn-fcgi -s /tmp/ginxsom-fcgi.sock -n ./build/ginxsom-fcgi
nginx -c $(pwd)/config/local-nginx.conf

3. Test the API

# Run the complete test suite
./tests/admin_test.sh

# Or test individual endpoints
export ADMIN_PRIVKEY="your_private_key_here"
./tests/admin_test.sh

API Endpoints

GET /api/health

System health check (no authentication required).

curl http://localhost:9001/api/health

GET /api/stats

Server statistics and metrics.

{
  "status": "success",
  "data": {
    "total_files": 1234,
    "total_bytes": 104857600,
    "total_size_mb": 100.0,
    "unique_uploaders": 56,
    "avg_file_size": 85049,
    "file_types": {
      "image/png": 45,
      "image/jpeg": 32
    }
  }
}

GET /api/config

Current server configuration.

{
  "status": "success",
  "data": {
    "max_file_size": "104857600",
    "require_auth": "false",
    "server_name": "ginxsom",
    "nip94_enabled": "true"
  }
}

PUT /api/config

Update server configuration.

{
  "max_file_size": "209715200",
  "require_auth": "true",
  "nip94_enabled": "true"
}

GET /api/files

Recent uploaded files with pagination.

{
  "status": "success",
  "data": {
    "files": [
      {
        "sha256": "abc123...",
        "size": 184292,
        "type": "application/pdf",
        "uploaded_at": 1725105921,
        "uploader_pubkey": "def456...",
        "url": "http://localhost:9001/abc123.pdf"
      }
    ],
    "total": 1234,
    "limit": 50,
    "offset": 0
  }
}

Manual API Usage with nak and curl

Generate Admin Authentication Event

# Create an authenticated event
EVENT=$(nak event -k 24242 -c "admin_request" \
    --tag t="GET" \
    --tag expiration="$(date -d '+1 hour' +%s)" \
    --sec "$ADMIN_PRIVKEY")

# Send authenticated request
AUTH_HEADER="Nostr $(echo "$EVENT" | base64 -w 0)"
curl -H "Authorization: $AUTH_HEADER" http://localhost:9001/api/stats

Update Configuration

# Create PUT event (method in tag)
EVENT=$(nak event -k 24242 -c "admin_request" \
    --tag t="PUT" \
    --tag expiration="$(date -d '+1 hour' +%s)" \
    --sec "$ADMIN_PRIVKEY")

AUTH_HEADER="Nostr $(echo "$EVENT" | base64 -w 0)"

curl -X PUT -H "Authorization: $AUTH_HEADER" \
     -H "Content-Type: application/json" \
     -d '{"max_file_size": "209715200", "require_auth": "true"}' \
     http://localhost:9001/api/config

Security Features

• Nostr Authentication: All admin operations require valid Nostr kind 24242 events
• Pubkey Verification: Only events signed by configured admin pubkeys are accepted
• Event Expiration: Admin events must include expiration timestamps for security
• Access Control: Separate enable/disable flag for admin interface

Development and Testing

Prerequisites

• nak (https://github.com/fiatjaf/nak)
• curl, jq
• sqlite3

Run Tests

# Make test script executable
chmod +x tests/admin_test.sh

# Run complete test suite
./tests/admin_test.sh

# Run with specific admin key
export ADMIN_PRIVKEY="your_private_key"
./tests/admin_test.sh

Build System

# Clean build
make clean

# Build with debug info
make debug

# Run FastCGI process
make run

Files Added/Modified

• src/admin_api.h - Admin API function declarations
• src/admin_api.c - Complete admin API implementation
• src/main.c - Updated with admin API routing
• config/local-nginx.conf - Updated with admin API routes
• tests/admin_test.sh - Complete test suite
• Makefile - Updated to compile admin_api.c
• README_ADMIN_API.md - This documentation

Future Enhancements

• Nostr Relay Integration: Automatic relay subscription for remote admin control
• Admin Pubkey Rotation: Support for multiple admin keys and key rotation
• Audit Logging: Detailed logging of admin operations
• Rate Limiting: Prevent abuse of admin endpoints
• Web Dashboard: Optional HTML/CSS/JavaScript frontend

---

The admin API provides a secure, Nostr-compliant interface for server management through command-line tools while maintaining full compatibility with the existing Blossom protocol implementation.