ginxsom/docs/DATABASE_NAMING_DESIGN.md

Database Naming Design (c-relay Pattern)

Overview

Following c-relay's architecture, ginxsom will use pubkey-based database naming to ensure database-key consistency and prevent mismatched configurations.

Database Naming Convention

Database files are named after the blossom server's public key:

db/<blossom_pubkey>.db

Example:

db/52e366edfa4e9cc6a6d4653828e51ccf828a2f5a05227d7a768f33b5a198681a.db

Startup Scenarios

Scenario 1: No Arguments (Fresh Start)

./ginxsom-fcgi

Behavior:

1. Generate new server keypair
2. Create database file: db/<new_pubkey>.db
3. Store keys in the new database
4. Start server

Result: New instance with fresh keys and database

---

Scenario 2: Database File Specified

./ginxsom-fcgi --db-path db/52e366ed...198681a.db

Behavior:

1. Open specified database
2. Load blossom_seckey from database
3. Verify pubkey matches database filename
4. Load admin_pubkey if present
5. Start server

Validation:

• Database MUST exist
• Database MUST contain blossom_seckey
• Derived pubkey MUST match filename

Error Cases:

• Database doesn't exist → Error: "Database file not found"
• Database missing blossom_seckey → Error: "Invalid database: missing server keys"
• Pubkey mismatch → Error: "Database pubkey mismatch: expected X, got Y"

---

Scenario 3: Keys Specified (New Instance with Specific Keys)

./ginxsom-fcgi --server-privkey c4e0d2ed...309c48f1 --admin-pubkey 8ff74724...5eedde0e

Behavior:

1. Validate provided server private key
2. Derive server public key
3. Create database file: db/<derived_pubkey>.db
4. Store both keys in new database
5. Start server

Validation:

• server-privkey MUST be valid 64-char hex
• Derived database file MUST NOT already exist (prevents overwriting)

Error Cases:

• Invalid privkey format → Error: "Invalid server private key format"
• Database already exists → Error: "Database already exists for this pubkey"

---

Scenario 4: Test Mode

./ginxsom-fcgi --test-keys

Behavior:

1. Load keys from .test_keys file
2. Derive server public key from SERVER_PRIVKEY
3. Create/overwrite database: db/<test_pubkey>.db
4. Store test keys in database
5. Start server

Special Handling:

• Test mode ALWAYS overwrites existing database (for clean testing)
• Database name derived from test SERVER_PRIVKEY

---

Scenario 5: Database + Keys Specified (Validation Mode)

./ginxsom-fcgi --db-path db/52e366ed...198681a.db --server-privkey c4e0d2ed...309c48f1

Behavior:

1. Open specified database
2. Load blossom_seckey from database
3. Compare with provided --server-privkey
4. If match: continue normally
5. If mismatch: ERROR and exit

Purpose: Validation/verification that correct keys are being used

Error Cases:

• Key mismatch → Error: "Server private key doesn't match database"

---

Command Line Options

Updated Options

--db-path PATH          Database file path (must match pubkey if keys exist)
--storage-dir DIR       Storage directory for files (default: blobs)
--admin-pubkey KEY      Admin public key (only used when creating new database)
--server-privkey KEY    Server private key (creates new DB or validates existing)
--test-keys             Use test keys from .test_keys file
--generate-keys         Generate new keypair and create database (deprecated - default behavior)
--help, -h              Show this help message

Removed Options

• --generate-keys - No longer needed, this is default behavior when no args provided

---

Database Directory Structure

db/
├── 52e366edfa4e9cc6a6d4653828e51ccf828a2f5a05227d7a768f33b5a198681a.db  # Test instance
├── a1b2c3d4e5f6...xyz.db  # Production instance 1
├── f9e8d7c6b5a4...abc.db  # Production instance 2
└── schema.sql             # Schema template

Each database is completely independent and tied to its keypair.

---

Implementation Logic Flow

START
  │
  ├─ Parse command line arguments
  │
  ├─ Initialize crypto system
  │
  ├─ Determine mode:
  │   │
  │   ├─ Test mode (--test-keys)?
  │   │   ├─ Load keys from .test_keys
  │   │   ├─ Derive pubkey
  │   │   ├─ Set db_path = db/<pubkey>.db
  │   │   └─ Create/overwrite database
  │   │
  │   ├─ Keys provided (--server-privkey)?
  │   │   ├─ Validate privkey format
  │   │   ├─ Derive pubkey
  │   │   ├─ Set db_path = db/<pubkey>.db
  │   │   │
  │   │   ├─ Database specified (--db-path)?
  │   │   │   ├─ YES: Validate keys match database
  │   │   │   └─ NO: Create new database
  │   │   │
  │   │   └─ Store keys in database
  │   │
  │   ├─ Database specified (--db-path)?
  │   │   ├─ Open database
  │   │   ├─ Load blossom_seckey
  │   │   ├─ Derive pubkey
  │   │   ├─ Validate pubkey matches filename
  │   │   └─ Load admin_pubkey
  │   │
  │   └─ No arguments (fresh start)?
  │       ├─ Generate new keypair
  │       ├─ Set db_path = db/<new_pubkey>.db
  │       └─ Create new database with keys
  │
  ├─ Initialize database schema (if new)
  │
  ├─ Load/validate all keys
  │
  └─ Start FastCGI server

---

Migration Path

For Existing Installations

1. Backup current database:

   cp db/ginxsom.db db/ginxsom.db.backup
   

2. Extract current pubkey:

   PUBKEY=$(sqlite3 db/ginxsom.db "SELECT value FROM config WHERE key='blossom_pubkey'")
   

3. Rename database:

   mv db/ginxsom.db db/${PUBKEY}.db
   

4. Update restart-all.sh:

   • Remove hardcoded db/ginxsom.db references
   • Let application determine database name from keys

---

Benefits

1. Database-Key Consistency: Impossible to use wrong database with wrong keys
2. Multiple Instances: Can run multiple independent instances with different keys
3. Clear Identity: Database filename immediately identifies the server
4. Test Isolation: Test databases are clearly separate from production
5. No Accidental Overwrites: Each keypair has its own database
6. Follows c-relay Pattern: Proven architecture from production relay software

---

Error Messages

Clear, Actionable Errors

ERROR: Database file not found: db/52e366ed...198681a.db
  → Specify a different database or let the application create a new one

ERROR: Invalid database: missing server keys
  → Database is corrupted or not a valid ginxsom database

ERROR: Database pubkey mismatch
  Expected: 52e366edfa4e9cc6a6d4653828e51ccf828a2f5a05227d7a768f33b5a198681a
  Got:      a1b2c3d4e5f6789...
  → Database filename doesn't match the keys stored inside

ERROR: Server private key doesn't match database
  → The --server-privkey you provided doesn't match the database keys

ERROR: Database already exists for this pubkey: db/52e366ed...198681a.db
  → Use --db-path to open existing database or use different keys

---

Testing Strategy

Test Cases

1. Fresh start (no args) → Creates new database with generated keys
2. Specify database → Opens and validates existing database
3. Specify keys → Creates new database with those keys
4. Test mode → Uses test keys and creates test database
5. Database + matching keys → Validates and continues
6. Database + mismatched keys → Errors appropriately
7. Invalid database path → Clear error message
8. Corrupted database → Detects and reports

Test Script

#!/bin/bash
# Test database naming system

# Test 1: Fresh start
./ginxsom-fcgi --generate-keys
# Should create db/<new_pubkey>.db

# Test 2: Test mode
./ginxsom-fcgi --test-keys
# Should create db/52e366ed...198681a.db

# Test 3: Specify keys
./ginxsom-fcgi --server-privkey abc123...
# Should create db/<derived_pubkey>.db

# Test 4: Open existing
./ginxsom-fcgi --db-path db/52e366ed...198681a.db
# Should open and validate

# Test 5: Mismatch error
./ginxsom-fcgi --db-path db/52e366ed...198681a.db --server-privkey wrong_key
# Should error with clear message