Security

Authentication & Authorization

User & Role Management

SoliDB uses a granular Role-Based Access Control (RBAC) system. Users are assigned one or more roles, and roles define specific permissions to access databases and resources.

Permission Structure

Permissions are defined by an action and a scope.

{
  "action": "write",       // admin, write, read
  "scope": "database",     // global, database
  "database": "products"   // Required if scope is "database"
}

Built-in Roles

Production Configuration

For production deployments, configure these environment variables to verify security and persistence:

# REQUIRED: Set a secure JWT secret (32+ characters)
# If not set, a random secret is generated on startup (invalidating tokens on restart)
export JWT_SECRET="your-secure-random-secret-here"

# OPTIONAL: Set admin password (otherwise randomly generated)
# Useful for automated deployments where you can't read logs
export SOLIDB_ADMIN_PASSWORD="your-secure-password"

# RECOMMENDED: Restrict browser origins allowed by CORS and WebSocket upgrades.
# Comma-separated list of scheme://host[:port]. Default is deny-all when unset.
# Use "*" only in development; the wildcard disables credentialed CORS.
export SOLIDB_CORS_ALLOWED_ORIGINS="https://app.example.com,https://admin.example.com"

# OPTIONAL: Allowlist for solidb.redirect() destinations from Lua scripts.
# Comma-separated list of scheme://host[:port]. When unset, all redirects are allowed.
export SOLIDB_ALLOWED_REDIRECT_ORIGINS="https://app.example.com"

# Per-client API rate limit: requests per window, and window length.
# 0 disables the limiter entirely.
export SOLIDB_API_RATE_LIMIT=600
export SOLIDB_API_RATE_WINDOW_SECS=60

# Behind a proxy that overwrites X-Forwarded-For: key rate limits on the
# forwarded address instead of the socket peer. Only set this when the
# proxy is trusted — otherwise clients can spoof their own identity.
export SOLIDB_TRUST_PROXY_HEADERS=1

Transport Security (TLS)

SoliDB speaks plain HTTP by default and expects a reverse proxy to terminate TLS. When that is not an option — a single-binary deployment, an appliance, an edge node — the server can terminate TLS itself. The implementation uses rustls, so the build stays free of OpenSSL.

# PEM certificate chain and private key. Both flags are required together;
# passing one without the other refuses to start rather than silently
# listening in plaintext.
solidb --port 6745 --data-dir ./data \
       --tls-cert /etc/solidb/fullchain.pem \
       --tls-key  /etc/solidb/privkey.pem

What runs inside the tunnel

It depends on which port mode you run. In dual-port mode (--port and --replication-port differ), the API port serves HTTPS and replication stays on its own port, configured separately.

In multiplexed mode (one port for everything), the listener sniffs the first byte of each connection and only performs a handshake when the client actually offers a TLS ClientHello. An HTTPS client gets the tunnel — and because the multiplexer then sniffs the decrypted stream exactly as it does plaintext, both HTTP and the binary driver protocol work inside it. A plaintext peer is passed through untouched.

Refusing plaintext

If nothing on the port needs plaintext — a single node with no native-protocol clients and no peers — you can close it off:

# Drop any connection on the multiplexed port that does not offer TLS.
export SOLIDB_TLS_REQUIRE=1

Handshakes are bounded at 10 seconds in both port modes, so a client that connects and stalls cannot hold a file descriptor open indefinitely.

Cluster Security

For multi-node clusters, SoliDB uses a sheared secret keyfile to authenticate nodes.

# 1. Generate a secure keyfile (do this once)
openssl rand -base64 756 > solidb-keyfile
chmod 600 solidb-keyfile

# 2. Copy the keyfile to all nodes

# 3. Start with keyfile authentication
solidb --keyfile solidb-keyfile --peer node2:6746 --peer node3:6746

# 4. Enforce keyfile in production: refuse to start if missing.
export SOLIDB_REQUIRE_KEYFILE=true

The cluster communication protocol uses HMAC-SHA256 to sign all handshake messages, ensuring that only nodes possessing the shared keyfile can join the cluster. Set SOLIDB_REQUIRE_KEYFILE=true so that nodes started without a keyfile fail closed instead of silently accepting unauthenticated peers.

Built-in Protections

Recommendations