ginxsom/docs/ADMIN_COMMANDS_PLAN.md

Ginxsom Admin Commands Implementation Plan

Overview

This document outlines the implementation plan for Ginxsom's admin command system, adapted from c-relay's event-based administration system. Commands are sent as NIP-44 encrypted Kind 23456 events and responses are returned as Kind 23457 events.

Command Analysis: c-relay vs Ginxsom

Commands to Implement (Blossom-Relevant)

c-relay Command	Ginxsom Equivalent	Rationale
config_query	config_query	Query Blossom server configuration
config_update	config_update	Update server settings dynamically
stats_query	stats_query	Database statistics (blobs, storage, etc.)
system_status	system_status	Server health and status
sql_query	sql_query	Direct database queries for debugging
N/A	blob_list	List blobs by pubkey or criteria
N/A	storage_stats	Storage usage and capacity info
N/A	mirror_status	Status of mirroring operations
N/A	report_query	Query content reports (BUD-09)

Commands to Exclude (Not Blossom-Relevant)

c-relay Command	Reason for Exclusion
auth_add_blacklist	Blossom uses different auth model (per-blob, not per-pubkey)
auth_add_whitelist	Same as above
auth_delete_rule	Same as above
auth_query_all	Same as above
system_clear_auth	Same as above

Note: Blossom's authentication is event-based per operation (upload/delete), not relay-level whitelist/blacklist. Auth rules in Ginxsom are configured via the auth_rules table but managed differently than c-relay.

Event Structure

Admin Command Event (Kind 23456)

{
  "id": "event_id",
  "pubkey": "admin_public_key",
  "created_at": 1234567890,
  "kind": 23456,
  "content": "NIP44_ENCRYPTED_COMMAND_ARRAY",
  "tags": [
    ["p", "blossom_server_pubkey"]
  ],
  "sig": "event_signature"
}

Admin Response Event (Kind 23457)

{
  "id": "response_event_id",
  "pubkey": "blossom_server_pubkey",
  "created_at": 1234567890,
  "kind": 23457,
  "content": "NIP44_ENCRYPTED_RESPONSE_OBJECT",
  "tags": [
    ["p", "admin_public_key"],
    ["e", "request_event_id"]
  ],
  "sig": "response_event_signature"
}

Command Specifications

1. Configuration Management

config_query

Query server configuration parameters.

Command Format:

["config_query", "all"]
["config_query", "category", "blossom"]
["config_query", "key", "max_file_size"]

Response:

{
  "query_type": "config_all",
  "total_results": 15,
  "timestamp": 1234567890,
  "data": [
    {
      "key": "max_file_size",
      "value": "104857600",
      "data_type": "integer",
      "category": "blossom",
      "description": "Maximum file size in bytes"
    },
    {
      "key": "enable_relay_connect",
      "value": "true",
      "data_type": "boolean",
      "category": "relay",
      "description": "Enable relay client functionality"
    }
  ]
}

Configuration Categories:

• blossom: Blossom protocol settings (max_file_size, storage_path, etc.)
• relay: Relay client settings (enable_relay_connect, kind_0_content, etc.)
• auth: Authentication settings (auth_enabled, nip42_required, etc.)
• limits: Rate limits and quotas
• system: System-level settings

config_update

Update configuration parameters dynamically.

Command Format:

["config_update", [
  {
    "key": "max_file_size",
    "value": "209715200",
    "data_type": "integer",
    "category": "blossom"
  },
  {
    "key": "enable_relay_connect",
    "value": "true",
    "data_type": "boolean",
    "category": "relay"
  }
]]

Response:

{
  "query_type": "config_update",
  "status": "success",
  "total_results": 2,
  "timestamp": 1234567890,
  "data": [
    {
      "key": "max_file_size",
      "value": "209715200",
      "status": "updated",
      "restart_required": false
    },
    {
      "key": "enable_relay_connect",
      "value": "true",
      "status": "updated",
      "restart_required": true
    }
  ]
}

2. Statistics and Monitoring

stats_query

Get comprehensive database and storage statistics.

Command Format:

["stats_query"]

Response:

{
  "query_type": "stats_query",
  "timestamp": 1234567890,
  "database_size_bytes": 1048576,
  "storage_size_bytes": 10737418240,
  "total_blobs": 1543,
  "unique_uploaders": 234,
  "blob_types": [
    {"type": "image/jpeg", "count": 856, "size_bytes": 5368709120, "percentage": 55.4},
    {"type": "image/png", "count": 432, "size_bytes": 3221225472, "percentage": 28.0},
    {"type": "video/mp4", "count": 123, "size_bytes": 2147483648, "percentage": 8.0}
  ],
  "time_stats": {
    "total": 1543,
    "last_24h": 45,
    "last_7d": 234,
    "last_30d": 876
  },
  "top_uploaders": [
    {"pubkey": "abc123...", "blob_count": 234, "total_bytes": 1073741824, "percentage": 15.2},
    {"pubkey": "def456...", "blob_count": 187, "total_bytes": 858993459, "percentage": 12.1}
  ]
}

system_status

Get current system status and health metrics.

Command Format:

["system_command", "system_status"]

Response:

{
  "query_type": "system_status",
  "timestamp": 1234567890,
  "uptime_seconds": 86400,
  "version": "0.1.0",
  "relay_client": {
    "enabled": true,
    "connected_relays": 1,
    "relay_status": [
      {
        "url": "wss://relay.laantungir.net",
        "state": "connected",
        "events_received": 12,
        "events_published": 3
      }
    ]
  },
  "storage": {
    "path": "/home/teknari/lt_gitea/ginxsom/blobs",
    "total_bytes": 10737418240,
    "available_bytes": 53687091200,
    "usage_percentage": 16.7
  },
  "database": {
    "path": "db/52e366edfa4e9cc6a6d4653828e51ccf828a2f5a05227d7a768f33b5a198681a.db",
    "size_bytes": 1048576,
    "total_blobs": 1543
  }
}

3. Blossom-Specific Commands

blob_list

List blobs with filtering options.

Command Format:

["blob_list", "all"]
["blob_list", "pubkey", "abc123..."]
["blob_list", "type", "image/jpeg"]
["blob_list", "recent", 50]

Response:

{
  "query_type": "blob_list",
  "total_results": 50,
  "timestamp": 1234567890,
  "data": [
    {
      "sha256": "b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553",
      "size": 184292,
      "type": "application/pdf",
      "uploaded_at": 1725105921,
      "uploader_pubkey": "abc123...",
      "url": "https://cdn.example.com/b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf"
    }
  ]
}

storage_stats

Get detailed storage statistics.

Command Format:

["storage_stats"]

Response:

{
  "query_type": "storage_stats",
  "timestamp": 1234567890,
  "storage_path": "/home/teknari/lt_gitea/ginxsom/blobs",
  "total_bytes": 10737418240,
  "available_bytes": 53687091200,
  "used_bytes": 10737418240,
  "usage_percentage": 16.7,
  "blob_count": 1543,
  "average_blob_size": 6958592,
  "largest_blob": {
    "sha256": "abc123...",
    "size": 104857600,
    "type": "video/mp4"
  },
  "by_type": [
    {"type": "image/jpeg", "count": 856, "total_bytes": 5368709120},
    {"type": "image/png", "count": 432, "total_bytes": 3221225472}
  ]
}

mirror_status

Get status of blob mirroring operations (BUD-04).

Command Format:

["mirror_status"]
["mirror_status", "sha256", "abc123..."]

Response:

{
  "query_type": "mirror_status",
  "timestamp": 1234567890,
  "total_mirrors": 23,
  "data": [
    {
      "sha256": "abc123...",
      "source_url": "https://cdn.example.com/abc123.jpg",
      "status": "completed",
      "mirrored_at": 1725105921,
      "size": 1048576
    }
  ]
}

report_query

Query content reports (BUD-09).

Command Format:

["report_query", "all"]
["report_query", "blob", "abc123..."]
["report_query", "type", "nudity"]

Response:

{
  "query_type": "report_query",
  "total_results": 12,
  "timestamp": 1234567890,
  "data": [
    {
      "report_id": 1,
      "blob_sha256": "abc123...",
      "report_type": "nudity",
      "reporter_pubkey": "def456...",
      "content": "Inappropriate content",
      "reported_at": 1725105921
    }
  ]
}

4. Database Queries

sql_query

Execute read-only SQL queries for debugging.

Command Format:

["sql_query", "SELECT * FROM blobs LIMIT 10"]

Response:

{
  "query_type": "sql_query",
  "request_id": "request_event_id",
  "timestamp": 1234567890,
  "query": "SELECT * FROM blobs LIMIT 10",
  "execution_time_ms": 12,
  "row_count": 10,
  "columns": ["sha256", "size", "type", "uploaded_at", "uploader_pubkey"],
  "rows": [
    ["b1674191...", 184292, "application/pdf", 1725105921, "abc123..."]
  ]
}

Security:

• Only SELECT statements allowed
• Query timeout: 5 seconds
• Result row limit: 1000 rows
• All queries logged

Implementation Architecture

1. Command Processing Flow

1. Relay client receives Kind 23456 event
2. Verify sender is admin_pubkey
3. Decrypt content using NIP-44
4. Parse command array
5. Validate command structure
6. Execute command handler
7. Generate response object
8. Encrypt response using NIP-44
9. Create Kind 23457 event
10. Publish to relays

2. Code Structure

New Files:

• src/admin_commands.c - Command handlers
• src/admin_commands.h - Command interface
• src/nip44.c - NIP-44 encryption wrapper (uses nostr_core_lib)
• src/nip44.h - NIP-44 interface

Modified Files:

• src/relay_client.c - Add command processing to on_admin_command_event()
• src/main.c - Initialize admin command system

3. Database Schema Additions

-- Admin command log
CREATE TABLE IF NOT EXISTS admin_commands (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    event_id TEXT NOT NULL,
    command_type TEXT NOT NULL,
    admin_pubkey TEXT NOT NULL,
    executed_at INTEGER NOT NULL,
    execution_time_ms INTEGER,
    status TEXT NOT NULL,
    error TEXT
);

-- Create index for command history queries
CREATE INDEX IF NOT EXISTS idx_admin_commands_executed 
ON admin_commands(executed_at DESC);

4. Configuration Keys

Blossom Category:

• max_file_size - Maximum upload size in bytes
• storage_path - Blob storage directory
• cdn_origin - CDN URL for blob descriptors
• enable_nip94 - Include NIP-94 tags in responses

Relay Category:

• enable_relay_connect - Enable relay client
• kind_0_content - Profile metadata JSON
• kind_10002_tags - Relay list JSON array

Auth Category:

• auth_enabled - Enable auth rules system
• require_auth_upload - Require auth for uploads
• require_auth_delete - Require auth for deletes

Limits Category:

• max_blobs_per_user - Per-user blob limit
• rate_limit_uploads - Uploads per minute
• max_total_storage - Total storage limit in bytes

Implementation Phases

Phase 1: NIP-44 Encryption Support

• Integrate nostr_core_lib NIP-44 functions
• Create encryption/decryption wrappers
• Test with sample data

Phase 2: Command Infrastructure

• Create admin_commands.c/h
• Implement command parser
• Add command logging to database
• Implement response builder

Phase 3: Core Commands

• Implement config_query
• Implement config_update
• Implement stats_query
• Implement system_status

Phase 4: Blossom Commands

• Implement blob_list
• Implement storage_stats
• Implement mirror_status
• Implement report_query

Phase 5: Advanced Features

• Implement sql_query with security
• Add command history tracking
• Implement rate limiting for admin commands

Phase 6: Testing & Documentation

• Create test suite for each command
• Update README.md with admin API section
• Create example scripts using nak tool

Security Considerations

1. Authentication: Only admin_pubkey can send commands
2. Encryption: All commands/responses use NIP-44
3. Logging: All admin actions logged to database
4. Rate Limiting: Prevent admin command flooding
5. SQL Safety: Only SELECT allowed, with timeout and row limits
6. Input Validation: Strict validation of all command parameters

Testing Strategy

1. Unit Tests: Test each command handler independently
2. Integration Tests: Test full command flow with encryption
3. Security Tests: Verify auth checks and SQL injection prevention
4. Performance Tests: Ensure commands don't block relay operations
5. Manual Tests: Use nak tool to send real encrypted commands

Documentation Updates

Add new section to README.md after "Content Reporting (BUD-09)":

## Administrator API

Ginxsom uses an event-based administration system where commands are sent as 
NIP-44 encrypted Kind 23456 events and responses are returned as Kind 23457 
events. This provides secure, cryptographically authenticated remote management.

[Full admin API documentation here]