laantungir/c-relay
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases 7 Wiki Activity

Working on API

Browse Source
This commit is contained in:
Your Name
2025-09-25 16:35:16 -04:00
parent 036b0823b9
commit bc6a7b3f20
9 changed files with 1530 additions and 894 deletions
Download Patch File Download Diff File Expand all files Collapse all files

371
README.md
View File

@@ -24,55 +24,66 @@ Do NOT modify the formatting, add emojis, or change the text. Keep the simple fo
## 🔧 Administrator API
C-Relay uses an innovative **event-based administration system** where all configuration and management commands are sent as signed Nostr events using the admin private key generated during first startup. Admin commands use ephemeral kinds 23455 and 23456 with **optional NIP-44 encryption** for enhanced security.
C-Relay uses an innovative **event-based administration system** where all configuration and management commands are sent as signed Nostr events using the admin private key generated during first startup. All admin commands use **tag-based parameters** for simplicity and compatibility.
### Authentication
All admin commands require signing with the admin private key displayed during first-time startup. **Save this key securely** - it cannot be recovered and is needed for all administrative operations.
### Security Options
### Event Structure
**Standard Mode (Plaintext):** Commands sent in tags as normal
**Encrypted Mode (NIP-44):** Commands encrypted in content field, no tags used
All admin commands use the same unified event structure with tag-based parameters:
### Kind 23455: Configuration Management (Ephemeral)
Update relay configuration parameters or query available settings.
**Configuration Update:**
**Admin Command Event:**
```json
{
"kind": 23455,
"content": "<optional nip-44 encrypted tags>",
"id": "event_id",
"pubkey": "admin_public_key",
"created_at": 1234567890,
"kind": 23456,
"content": "<nip44 encrypted command>",
"tags": [
["config_key1", "config_value1"],
["config_key2", "config_value2"]
]
["p", "relay_public_key"],
],
"sig": "event_signature"
}
```
**Query Available Config Keys:**
**Admin Response Event:**
```json
{
"kind": 23455,
"content": "<optional nip-44 encrypted tags>",
["EVENT", "temp_sub_id", {
"id": "response_event_id",
"pubkey": "relay_public_key",
"created_at": 1234567890,
"kind": 23457,
"content": "<nip44 encrypted response>",
"tags": [
["config_query", "list_all_keys"]
]
}
["p", "admin_public_key"]
],
"sig": "response_event_signature"
}]
```
**Get Current Configuration:**
```json
{
"kind": 23455,
"content": "<optional nip-44 encrypted tags>",
"tags": [
["config_query", "get_current_config"]
]
}
```
### Admin Commands
**Available Configuration Keys:**
All commands are sent as nip44 encrypted content. The following table lists all available commands:
| Command Type | Tag Format | Description |
|--------------|------------|-------------|
| **Configuration Management** |
| `config_update` | `["relay_description", "My Relay"]` | Update relay configuration parameters |
| `config_query` | `["config_query", "list_all_keys"]` | List all available configuration keys |
| **Auth Rules Management** |
| `auth_add_blacklist` | `["blacklist", "pubkey", "abc123..."]` | Add pubkey to blacklist |
| `auth_add_whitelist` | `["whitelist", "pubkey", "def456..."]` | Add pubkey to whitelist |
| `auth_query_all` | `["auth_query", "all"]` | Query all auth rules |
| `auth_query_type` | `["auth_query", "whitelist"]` | Query specific rule type |
| `auth_query_pattern` | `["auth_query", "pattern", "abc123..."]` | Query specific pattern |
| **System Commands** |
| `system_clear_auth` | `["system_command", "clear_all_auth_rules"]` | Clear all auth rules |
| `system_status` | `["system_command", "system_status"]` | Get system status |
### Available Configuration Keys
**Basic Relay Settings:**
- `relay_description`: Relay description text
@@ -92,259 +103,69 @@ Update relay configuration parameters or query available settings.
- `pow_min_difficulty`: Minimum proof-of-work difficulty
- `nip40_expiration_enabled`: Enable event expiration (`true`/`false`)
### Kind 23456: Auth Rules & System Management (Ephemeral)
Manage whitelist/blacklist rules and system administration commands.
**Add Blacklist Rule:**
```json
{
"kind": 23456,
"content": "<optional nip-44 encrypted tags>",
"tags": [
["blacklist", "pubkey", "deadbeef1234abcd..."]
]
}
```
**Add Whitelist Rule:**
```json
{
"kind": 23456,
"content": "<optional nip-44 encrypted tags>",
"tags": [
["whitelist", "pubkey", "cafebabe5678efgh..."]
]
}
```
**Remove Rule:**
```json
{
"kind": 23456,
"content": "<optional nip-44 encrypted tags>",
"tags": [
["blacklist", "pubkey", "deadbeef1234abcd..."]
]
}
```
**Query Auth Rules:**
```json
{
"kind": 23456,
"content": "<optional nip-44 encrypted tags>",
"tags": [
["auth_query", "all"]
]
}
```
**Query Specific Rule Type:**
```json
{
"kind": 23456,
"content": "<optional nip-44 encrypted tags>",
"tags": [
["auth_query", "whitelist"]
]
}
```
**Query Specific Pattern:**
```json
{
"kind": 23456,
"content": "<optional nip-44 encrypted tags>",
"tags": [
["auth_query", "pattern", "deadbeef1234abcd..."]
]
}
```
**Clear All Auth Rules:**
```json
{
"kind": 23456,
"content": "<optional nip-44 encrypted tags>",
"tags": [
["system_command", "clear_all_auth_rules"]
]
}
```
### Response Format
All admin commands return JSON responses via WebSocket:
All admin commands return **signed EVENT responses** via WebSocket following standard Nostr protocol. Responses use JSON content with structured data.
#### Response Examples
**Success Response:**
```json
["OK", "event_id", true, "Operation completed successfully"]
["EVENT", "temp_sub_id", {
"id": "response_event_id",
"pubkey": "relay_public_key",
"created_at": 1234567890,
"kind": 23457,
"content": "nip44 encrypted:{\"status\": \"success\", \"message\": \"Operation completed successfully\"}",
"tags": [
["p", "admin_public_key"]
],
"sig": "response_event_signature"
}]
```
**Error Response:**
```json
["OK", "event_id", false, "Error: invalid configuration value"]
```
### Command Examples
**Using `nak` CLI tool:**
```bash
# Set environment variables
ADMIN_PRIVKEY="your_admin_private_key_here"
RELAY_PUBKEY="your_relay_public_key_here"
RELAY_URL="ws://localhost:8888"
# List all available configuration keys
nak event -k 23455 --content "Discovery query" \
-t "config_query=list_all_keys" \
--sec $ADMIN_PRIVKEY | nak event $RELAY_URL
# Enable whitelist/blacklist auth rules
nak event -k 23455 --content "Enable auth rules" \
-t "auth_enabled=true" \
--sec $ADMIN_PRIVKEY | nak event $RELAY_URL
# Add user to blacklist
nak event -k 23456 --content "Block spam user" \
-t "blacklist=pubkey;$SPAM_USER_PUBKEY" \
--sec $ADMIN_PRIVKEY | nak event $RELAY_URL
# Add user to whitelist
nak event -k 23456 --content "Allow trusted user" \
-t "whitelist=pubkey;$TRUSTED_USER_PUBKEY" \
--sec $ADMIN_PRIVKEY | nak event $RELAY_URL
# Query all current auth rules
nak event -k 23456 --content "Get all auth rules" \
-t "auth_query=all" \
--sec $ADMIN_PRIVKEY | nak event $RELAY_URL
# Query only whitelist rules
nak event -k 23456 --content "Get whitelist rules" \
-t "auth_query=whitelist" \
--sec $ADMIN_PRIVKEY | nak event $RELAY_URL
# Query only blacklist rules
nak event -k 23456 --content "Get blacklist rules" \
-t "auth_query=blacklist" \
--sec $ADMIN_PRIVKEY | nak event $RELAY_URL
# Check if specific pattern exists
nak event -k 23456 --content "Check user status" \
-t "auth_query=pattern;$CHECK_USER_PUBKEY" \
--sec $ADMIN_PRIVKEY | nak event $RELAY_URL
# Clear all auth rules (for testing)
nak event -k 23456 --content "Clear all rules" \
-t "system_command=clear_all_auth_rules" \
--sec $ADMIN_PRIVKEY | nak event $RELAY_URL
# Update relay description
nak event -k 23455 --content "Update description" \
-t "relay_description=My awesome relay" \
--sec $ADMIN_PRIVKEY | nak event $RELAY_URL
# Set connection limits
nak event -k 23455 --content "Update limits" \
-t "max_connections=500" \
-t "max_subscriptions_per_client=10" \
--sec $ADMIN_PRIVKEY | nak event $RELAY_URL
```
**For encrypted commands (NIP-44), use empty tags and encrypted content:**
```bash
# Enable auth rules (encrypted)
ENCRYPTED_TAGS=$(echo '[["auth_enabled","true"]]' | nip44_encrypt_with_relay_pubkey)
nak event -k 23455 --content "{\"encrypted_tags\":\"$ENCRYPTED_TAGS\"}" \
--sec $ADMIN_PRIVKEY | nak event $RELAY_URL
# Add user to blacklist (encrypted)
ENCRYPTED_TAGS=$(echo '[["blacklist","pubkey","'$SPAM_USER_PUBKEY'"]]' | nip44_encrypt_with_relay_pubkey)
nak event -k 23456 --content "{\"encrypted_tags\":\"$ENCRYPTED_TAGS\"}" \
--sec $ADMIN_PRIVKEY | nak event $RELAY_URL
```
### Authentication Systems
C-Relay supports **two independent authentication systems**:
#### 1. Auth Rules (Whitelist/Blacklist)
- **Config Key**: `auth_enabled=true`
- **Purpose**: Block or allow specific pubkeys from publishing events
- **Method**: Database-driven rules enforcement
- **Use Case**: Spam prevention, content moderation
#### 2. NIP-42 Cryptographic Authentication
- **Config Key**: `nip42_auth_required=true`
- **Purpose**: Require cryptographic proof of pubkey ownership
- **Method**: Challenge-response authentication protocol
- **Use Case**: Verified identity, premium features
**Important**: These systems can be used independently or together:
- `auth_enabled=true` + `nip42_auth_required=false`: Only whitelist/blacklist rules
- `auth_enabled=false` + `nip42_auth_required=true`: Only NIP-42 auth challenges
- Both `true`: Users must pass NIP-42 auth AND not be blacklisted
### Security Considerations
- **Private Key Protection**: Admin private key grants full relay control
- **Network Access**: Admin commands should only be sent over secure connections
- **Backup**: Keep secure backups of admin private key
- **Rotation**: Consider implementing admin key rotation for production deployments
### Troubleshooting
**Common Issues:**
- `auth-required: not authorized admin`: Verify you're using the correct admin private key
- `invalid: missing or invalid kind`: Ensure event kind is 23455 or 23456
- `error: failed to process configuration event`: Check configuration key/value validity
- `no valid auth rules found`: Verify tag format uses semicolon syntax for multi-element tags
**Debug Commands:**
```bash
# Check if relay is accepting connections
echo '["REQ","test",{}]' | websocat ws://localhost:8888
# Test admin authentication
nak event -k 23455 --content "Test auth" \
-t "test_config=true" \
--sec $ADMIN_PRIVKEY | nak event ws://localhost:8888
# Discover available configuration keys
nak event -k 23455 --content "Discovery query" \
-t "config_query=list_all_keys" \
--sec $ADMIN_PRIVKEY | nak event ws://localhost:8888
# Query current auth rules
nak event -k 23456 --content "Get auth rules" \
-t "auth_query=all" \
--sec $ADMIN_PRIVKEY | nak event ws://localhost:8888
```
### Configuration Discovery
Before making changes, admins can query the relay to discover all available configuration options:
```bash
# Get list of all editable configuration keys with descriptions
nak event -k 23455 --content '{"query":"list_config_keys","description":"Discovery"}' \
-t "config_query=list_all_keys" \
--sec $ADMIN_PRIVKEY | nak event $RELAY_URL
# Get current values of all configuration parameters
nak event -k 23455 --content '{"query":"get_config","description":"Current state"}' \
-t "config_query=get_current_config" \
--sec $ADMIN_PRIVKEY | nak event $RELAY_URL
```
**Expected Response Format:**
```json
["EVENT", "subscription_id", {
"kind": 23455,
"content": "{\"config_keys\": [\"auth_enabled\", \"max_connections\", ...], \"descriptions\": {...}}",
"tags": [["response_type", "config_keys_list"]]
["EVENT", "temp_sub_id", {
"id": "response_event_id",
"pubkey": "relay_public_key",
"created_at": 1234567890,
"kind": 23457,
"content": "nip44 encrypted:{\"status\": \"error\", \"message\": \"Error: invalid configuration value\"}",
"tags": [
["p", "admin_public_key"]
],
"sig": "response_event_signature"
}]
```
**Auth Rules Query Response:**
```json
["EVENT", "temp_sub_id", {
"id": "response_event_id",
"pubkey": "relay_public_key",
"created_at": 1234567890,
"kind": 23457,
"content": "nip44 encrypted:{\"query_type\": \"auth_rules\", \"total_results\": 2, \"data\": [{\"rule_type\": \"blacklist\", \"pattern_type\": \"pubkey\", \"pattern_value\": \"abc123...\", \"action\": \"deny\"}]}",
"tags": [
["p", "admin_public_key"]
],
"sig": "response_event_signature"
}]
```
**Configuration Query Response:**
```json
["EVENT", "temp_sub_id", {
"id": "response_event_id",
"pubkey": "relay_public_key",
"created_at": 1234567890,
"kind": 23457,
"content": "nip44 encrypted:{\"query_type\": \"config_keys\", \"config_keys\": [\"auth_enabled\", \"max_connections\"], \"descriptions\": {\"auth_enabled\": \"Enable whitelist/blacklist rules\"}}",
"tags": [
["p", "admin_public_key"]
],
"sig": "response_event_signature"
}]
```