feat(vpn): add VPN client editing and connected client visibility in ops server

2026-03-31 09:53:37 +00:00
parent cfb727b86d
commit 11ca64a1cd
14 changed files with 447 additions and 30 deletions
--- a/readme.storage.md
+++ b/readme.storage.md
@@ -0,0 +1,120 @@
+# DCRouter Storage Overview
+
+DCRouter uses two complementary storage systems: **StorageManager** for configuration and state, and **CacheDb** for time-limited cached data.
+
+## StorageManager (Key-Value Store)
+
+A lightweight, pluggable key-value store for configuration, credentials, and runtime state. Data is persisted as flat JSON files on disk by default.
+
+### Default Path
+
+```
+~/.serve.zone/dcrouter/storage/
+```
+
+Configurable via `options.storage.fsPath` or `options.baseDir`.
+
+### Backends
+
+```typescript
+// Filesystem (default)
+storage: { fsPath: '/var/lib/dcrouter/data' }
+
+// Custom (Redis, S3, etc.)
+storage: {
+  readFunction: async (key) => await redis.get(key),
+  writeFunction: async (key, value) => await redis.set(key, value),
+}
+
+// In-memory (omit storage config — data lost on restart)
+```
+
+### What's Stored
+
+| Prefix | Contents | Managed By |
+|--------|----------|------------|
+| `/vpn/server-keys` | VPN server Noise + WireGuard keypairs | `VpnManager` |
+| `/vpn/clients/{clientId}` | VPN client registrations (keys, tags, description, assigned IP) | `VpnManager` |
+| `/config-api/routes/{uuid}.json` | Programmatic routes (created via OpsServer API) | `RouteConfigManager` |
+| `/config-api/tokens/{uuid}.json` | API tokens (hashed secrets, scopes, expiry) | `ApiTokenManager` |
+| `/config-api/overrides/{routeName}.json` | Hardcoded route overrides (enable/disable) | `RouteConfigManager` |
+| `/email/bounces/suppression-list.json` | Email bounce suppression list | `smartmta` |
+| `/certs/*` | TLS certificates and ACME state | `SmartAcme` (via `StorageBackedCertManager`) |
+
+### API
+
+```typescript
+// Read/write JSON
+await storageManager.getJSON<T>(key);
+await storageManager.setJSON(key, value);
+
+// Raw string read/write
+await storageManager.get(key);
+await storageManager.set(key, value);
+
+// List keys by prefix
+await storageManager.list('/vpn/clients/');
+
+// Delete
+await storageManager.delete(key);
+```
+
+## CacheDb (Embedded MongoDB)
+
+An embedded MongoDB-compatible database (via `@push.rocks/smartdb` + `@push.rocks/smartdata`) for cached data with automatic TTL-based cleanup.
+
+### Default Path
+
+```
+~/.serve.zone/dcrouter/tsmdb/
+```
+
+Configurable via `options.cacheConfig.storagePath`.
+
+### What's Cached
+
+| Document Type | Default TTL | Purpose |
+|--------------|-------------|---------|
+| `CachedEmail` | 30 days | Email metadata cache for dashboard display |
+| `CachedIPReputation` | 1 day | IP reputation lookup results (DNSBL checks) |
+
+### Configuration
+
+```typescript
+cacheConfig: {
+  enabled: true,                                    // default: true
+  storagePath: '~/.serve.zone/dcrouter/tsmdb',     // default
+  dbName: 'dcrouter',                               // default
+  cleanupIntervalHours: 1,                          // how often to purge expired records
+  ttlConfig: {
+    emails: 30,          // days
+    ipReputation: 1,     // days
+    bounces: 30,         // days (reserved)
+    dkimKeys: 90,        // days (reserved)
+    suppression: 30,     // days (reserved)
+  },
+}
+```
+
+### How It Works
+
+1. `CacheDb` starts a `LocalSmartDb` instance (embedded MongoDB process)
+2. `smartdata` connects to it via Unix socket
+3. Document classes (`CachedEmail`, `CachedIPReputation`) are decorated with `@Collection` and use `smartdata` ORM
+4. `CacheCleaner` runs on a timer, purging records older than their configured TTL
+
+### Disabling
+
+For development or lightweight deployments, disable the cache to avoid starting a MongoDB process:
+
+```typescript
+cacheConfig: { enabled: false }
+```
+
+## When to Use Which
+
+| Use Case | System | Why |
+|----------|--------|-----|
+| VPN keys, API tokens, routes, certs | **StorageManager** | Small JSON blobs, key-value access, no queries needed |
+| Email metadata, IP reputation | **CacheDb** | Time-series data, TTL expiry, potential for queries/aggregation |
+| Runtime state (connected clients, metrics) | **Neither** | In-memory only, rebuilt on startup |