Transport Encryption

Threat Scenarios

Outgoing Request (Dashboard → Server):

1. Dashboard intercepts the fetch call for a sensitive endpoint
2. Request body is serialized to JSON
3. A random 16-byte IV is generated
4. Data is encrypted with AES-256-CBC using the shared key
5. SHA-256 checksum is computed for integrity
6. HMAC-SHA256 signature is computed over IV + ciphertext + timestamp + checksum
7. Payload is wrapped as { _enc: "<base64-encoded-payload>" }
8. Server receives, verifies HMAC, verifies timestamp, decrypts, verifies checksum
9. Handler sees the original plaintext JSON

Incoming Response (Server → Dashboard):

1. Server handler returns normal JSON response
2. Middleware checks if client sent x-transport-encryption: 1 header
3. If yes, response JSON is encrypted with the same algorithm
4. Response is wrapped as { _enc: "<base64-encoded-payload>" }
5. Response header x-transport-encrypted: 1 is set
6. Dashboard fetch interceptor detects the header, decrypts the response
7. Application code receives the original plaintext JSON

Encrypt All vs Selective

Encrypt All: Every API call between the dashboard and server is encrypted. Maximum security, slight overhead. Recommended for high-security environments.

Selective: Only the endpoint groups you choose are encrypted. Best balance of security and performance — encrypt sensitive groups (API keys, database, vault) while leaving low-risk endpoints (dashboard stats) in plaintext.

Sensitive Only: One-click preset that enables encryption for groups marked as "SENSITIVE" — models, auth, email, database, vault, and integrations.

Endpoint Groups

Endpoints are organized into 22 logical groups. Each group maps to a set of API path patterns. When you toggle a group, all its endpoints are encrypted/decrypted. Hover over any group in the UI to see the exact path patterns.

Custom Endpoints

If you have custom API endpoints (plugins, extensions, or custom routes), you can add their path patterns manually. Use * as a wildcard for single path segments. Example: /api/my-plugin/*/config

Key Generation & Storage

During initial setup, the wizard auto-generates a 256-bit key and attempts to:

1. Write to .env file — Works on persistent filesystems (localhost, VPS, bare metal)
2. Store in database — Backup copy in settings table (always works)
3. Display to user — For manual platform configuration (always shown)

On ephemeral platforms (fly.io, Railway, Docker), the .env write may fail silently. The wizard detects this and shows a clear warning with platform-specific instructions.

For Most Deployments

• Enable "Sensitive Only" — covers API keys, database creds, vault, auth, email, and integrations
• Set TRANSPORT_ENCRYPTION_KEY in your environment
• Keep payload max age at 300s unless you have specific latency issues
• Leave debug logging OFF

For High-Security Environments

• Enable "Encrypt All API Calls"
• Use a dedicated TRANSPORT_ENCRYPTION_KEY (not shared with other services)
• Reduce payload max age to 60-120 seconds
• Combine with HTTPS, HSTS, and strict CSP headers
• Enable audit logging to track all security events

For Development

• Can be left disabled — HTTPS may not be configured locally
• If testing encryption, enable debug logging temporarily
• The system gracefully degrades — if encryption fails, plaintext is sent

Dashboard shows errors after enabling encryption

Cause: Key mismatch between client and server, often after changing the encryption key.

Fix: Hard-refresh the dashboard (Ctrl+Shift+R / Cmd+Shift+R) to re-fetch the key token. If the issue persists, disable encryption, refresh, and re-enable.

"Encrypted payload expired" errors

Cause: Clock drift between the client browser and server exceeds the max age setting.

Fix: Sync clocks (NTP) or increase the payload max age in Advanced Settings.

"Invalid signature — payload tampered" errors

Cause: A proxy or middleware modified the request body after encryption.

Fix: Check for request-modifying proxies, WAFs, or middleware that transform JSON bodies.

API calls from external tools (curl, Postman) fail

Cause: External tools don't send the x-transport-encryption: 1 header, so the server doesn't encrypt responses. However, if you send an encrypted request body ({ _enc: "..." }), the server will try to decrypt it.

Fix: For external API access, either disable encryption for those endpoints or don't include the encryption header — the server only encrypts responses when the client explicitly requests it.

Performance impact

AES-256-CBC encryption/decryption is very fast (hardware-accelerated on modern CPUs). The overhead is typically <1ms per request. For "Encrypt All" mode, you might notice ~2-5ms total overhead across all dashboard API calls. This is negligible compared to network latency.

Cryptographic Specifications

Encrypted Payload Format

// Base64-encoded JSON envelope:
{
  "v": 1,           // Protocol version
  "iv": "...",      // Hex-encoded 16-byte IV
  "d": "...",       // Base64-encoded AES-256-CBC ciphertext
  "ts": 1709510400, // Unix timestamp (ms)
  "cs": "...",      // SHA-256 checksum (first 16 hex chars)
  "sig": "..."      // HMAC-SHA256 signature (first 32 hex chars)
}

// Wire format: { "_enc": "<base64 of above JSON>" }

Source Files

• Server middleware: src/middleware/transport-encryption.ts
• Dashboard client: src/dashboard/components/transport-encryption.js
• Settings UI: src/dashboard/pages/settings.js (ComprehensiveSecurityTab)
• Route wiring: src/engine/routes.ts