v0.1.13 - Fix Kind 23458 test script: use websocat for bidirectional relay communication and correct nak decrypt flag (-p instead of --recipient-pubkey). Admin command system now fully functional end-to-end with NIP-44 encryption.
This commit is contained in:
Your Name
126
README.md
126
README.md
@@ -369,6 +369,132 @@ Error responses include specific error codes:
|
||||
- `no_blob_hashes`: Missing valid SHA-256 hashes
|
||||
- `unsupported_media_type`: Non-JSON Content-Type
|
||||
|
||||
## Administrator API
|
||||
|
||||
Ginxsom uses an **event-based administration system** where all configuration and management commands are sent as signed Nostr events using the admin private key. All admin commands use **NIP-44 encrypted command arrays** for security.
|
||||
|
||||
### Authentication
|
||||
|
||||
All admin commands require signing with the admin private key configured in the server. The admin public key is stored in the database and checked against incoming Kind 23458 events.
|
||||
|
||||
### Event Structure
|
||||
|
||||
**Admin Command Event (Kind 23458):**
|
||||
```json
|
||||
{
|
||||
"id": "event_id",
|
||||
"pubkey": "admin_public_key",
|
||||
"created_at": 1234587890,
|
||||
"kind": 23458,
|
||||
"content": "NIP44_ENCRYPTED_COMMAND_ARRAY",
|
||||
"tags": [
|
||||
["p", "blossom_server_pubkey"]
|
||||
],
|
||||
"sig": "event_signature"
|
||||
}
|
||||
```
|
||||
|
||||
The `content` field contains a NIP-44 encrypted JSON array representing the command.
|
||||
|
||||
**Admin Response Event (Kind 23459):**
|
||||
```json
|
||||
{
|
||||
"id": "response_event_id",
|
||||
"pubkey": "blossom_server_pubkey",
|
||||
"created_at": 1234587890,
|
||||
"kind": 23459,
|
||||
"content": "NIP44_ENCRYPTED_RESPONSE_OBJECT",
|
||||
"tags": [
|
||||
["p", "admin_public_key"],
|
||||
["e", "request_event_id"]
|
||||
],
|
||||
"sig": "response_event_signature"
|
||||
}
|
||||
```
|
||||
|
||||
The `content` field contains a NIP-44 encrypted JSON response object.
|
||||
|
||||
### Admin Commands
|
||||
|
||||
All commands are sent as NIP-44 encrypted JSON arrays in the event content:
|
||||
|
||||
| Command Type | Command Format | Description |
|
||||
|--------------|----------------|-------------|
|
||||
| **Configuration Management** |
|
||||
| `config_query` | `["config_query", "all"]` | Query all configuration parameters |
|
||||
| `config_update` | `["config_update", [{"key": "max_file_size", "value": "209715200", ...}]]` | Update configuration parameters |
|
||||
| **Statistics & Monitoring** |
|
||||
| `stats_query` | `["stats_query"]` | Get comprehensive database and storage statistics |
|
||||
| `system_status` | `["system_command", "system_status"]` | Get system status and health metrics |
|
||||
| **Blossom Operations** |
|
||||
| `blob_list` | `["blob_list", "all"]` or `["blob_list", "pubkey", "abc123..."]` | List blobs with filtering |
|
||||
| `storage_stats` | `["storage_stats"]` | Get detailed storage statistics |
|
||||
| `mirror_status` | `["mirror_status"]` | Get status of mirroring operations |
|
||||
| `report_query` | `["report_query", "all"]` | Query content reports (BUD-09) |
|
||||
| **Database Queries** |
|
||||
| `sql_query` | `["sql_query", "SELECT * FROM blobs LIMIT 10"]` | Execute read-only SQL query |
|
||||
|
||||
### Configuration Categories
|
||||
|
||||
**Blossom Settings:**
|
||||
- `max_file_size`: Maximum upload size in bytes
|
||||
- `storage_path`: Blob storage directory path
|
||||
- `cdn_origin`: CDN URL for blob descriptors
|
||||
- `enable_nip94`: Include NIP-94 tags in responses
|
||||
|
||||
**Relay Client Settings:**
|
||||
- `enable_relay_connect`: Enable relay client functionality
|
||||
- `kind_0_content`: Profile metadata JSON
|
||||
- `kind_10002_tags`: Relay list JSON array
|
||||
|
||||
**Authentication Settings:**
|
||||
- `auth_enabled`: Enable auth rules system
|
||||
- `require_auth_upload`: Require authentication for uploads
|
||||
- `require_auth_delete`: Require authentication for deletes
|
||||
|
||||
**Limits:**
|
||||
- `max_blobs_per_user`: Per-user blob limit
|
||||
- `rate_limit_uploads`: Uploads per minute
|
||||
- `max_total_storage`: Total storage limit in bytes
|
||||
|
||||
### Response Format
|
||||
|
||||
All admin commands return signed EVENT responses via the relay connection. Responses use NIP-44 encrypted JSON content with structured data.
|
||||
|
||||
**Success Response Example:**
|
||||
```json
|
||||
{
|
||||
"query_type": "stats_query",
|
||||
"timestamp": 1234587890,
|
||||
"database_size_bytes": 1048576,
|
||||
"storage_size_bytes": 10737418240,
|
||||
"total_blobs": 1543,
|
||||
"blob_types": [
|
||||
{"type": "image/jpeg", "count": 856, "size_bytes": 5368709120}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Error Response Example:**
|
||||
```json
|
||||
{
|
||||
"query_type": "config_update",
|
||||
"status": "error",
|
||||
"error": "invalid configuration value",
|
||||
"timestamp": 1234587890
|
||||
}
|
||||
```
|
||||
|
||||
### Security Features
|
||||
|
||||
- **Cryptographic Authentication**: Only admin pubkey can send commands
|
||||
- **NIP-44 Encryption**: All commands and responses are encrypted
|
||||
- **Command Logging**: All admin actions logged to database
|
||||
- **SQL Safety**: Only SELECT statements allowed with timeout and row limits
|
||||
- **Rate Limiting**: Prevents admin command flooding
|
||||
|
||||
For detailed command specifications and examples, see [`docs/ADMIN_COMMANDS_PLAN.md`](docs/ADMIN_COMMANDS_PLAN.md).
|
||||
|
||||
## File Storage
|
||||
|
||||
### Current (Flat) Structure
|
||||
|
||||
Reference in New Issue
Block a user