Docs

Security

Liven provides two security modes: auth-key authentication and mutual TLS (mTLS/ZTNA). Both are designed for production use with zero-trust networking.

Security Modes

Configure the security mode in liven.toml:

[security]
mode = "auth_key"     # "auth_key" (default) or "none"

Production note: The none mode should only be used for local development. In production, always enable auth_key.

Master Key (Root Auth Key)

When you first start Liven with liven start, a master key is automatically generated. This is the root authentication key with full administrative access.

First-Time Startup

Run liven start
The master key is printed to stdout — save it immediately
The key is also saved to ./liven.key (mode 0600)
This key is inserted into the auth_keys system stream

# First-time startup output
$ liven start
═══════════════════════════════════════════════════════════════
🔑 MASTER KEY (SAVE THIS - SHOWN ONLY ONCE):
a3f8c2e1d4b5a6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1
═══════════════════════════════════════════════════════════════
Liven started on port 43121 (DB) and 43120 (Web UI)

Master Key Resolution Order

On subsequent starts, Liven resolves the master key in this order:

Environment variable: LIVEN_SECURITY_MASTER_KEY — highest priority, no file written
Key file: ./liven.key — auto-generated on first start with mode 0600 (readable only by owner)
Config file: master_key in liven.toml — legacy installations only

Best practice: Always use the environment variable in production. Add ./liven.key to your .gitignore — it should never be committed to version control.

Auth-Key Authentication

In auth-key mode, every client must present a valid key to connect. Keys are verified using BLAKE3 hashing and stored in the auth_keys system stream — never in configuration files.

How It Works

Client sends Connect { client_id: "key" } frame
Server hashes the key and looks it up in auth_keys
If found and status == "active", connection is granted with assigned role
If not found or revoked, connection is rejected with an error

Role-Based Access Control

Each key is assigned a role that determines its permissions. Roles are enforced on every operation — not just at connection time.

Role	Permissions	Use Case
read-only	Query, subscribe, list streams	Dashboards, monitoring, reporting
write	Read + Insert, update, upsert, empty	Applications, APIs, data ingestion
admin	Write + Drop streams, compaction, key management	Operations, maintenance

Every operation checks the connection's capabilities before execution. Invalid operations return a clear permission error without any data being processed.

Managing Keys via Web UI

Admin users can generate additional auth keys through the Web UI dashboard at http://localhost:43120. Navigate to the Security section to:

Generate new keys with specific roles
View existing keys (key IDs and roles, not raw keys)
Revoke keys instantly

Emergency Key Reset

If you lose access to all admin keys (including the master key), use the emergency reset command:

# Reset all administrative credentials and generate a new root key
liven reset-key

⚠️ Warning: liven reset-key removes all existing administrative credentials and generates a new master key. Use this only when you have lost access to all admin keys. Active connections using revoked keys will be terminated.

mTLS / ZTNA (Mutual TLS)

For zero-trust network architectures, Liven supports mutual TLS authentication. Both client and server present certificates, and the client's Common Name (CN) determines access.

Configuration

[security]
mode = "auth_key"  # Still required for capability mapping
[security.ztna]
enabled = true
cert_path = "./certs/server.crt"
key_path = "./certs/server.key"
client_ca_path = "./certs/ca.crt"

How It Works

Server presents its TLS certificate (signed by a trusted CA)
Client presents its TLS certificate (signed by the same CA)
Server validates client certificate and extracts the CN field
CN is looked up in the auth_keys stream to determine role
Connection is granted with the corresponding capabilities

This ensures that only clients with both a valid certificate and an active auth key can connect — defense in depth.

Development vs Production

When environment = "development" or ZTNA is not enabled, Liven uses cleartext TCP with auth-key authentication. This is suitable for local development. Production deployments should enable ZTNA and set environment = "production".

Connection & Resource Limits

Liven limits concurrent connections to prevent overload. Configure limits in liven.toml:

[server]
max_connections = 10000      # Maximum concurrent connections
broadcast_capacity = 4096    # Memory buffer for streaming subscriptions

When at capacity, new connections queue gracefully. Monitor current usage:

Via CLI

liven status

Returns server status including active connections.

Via Query

status()

Returns connection metrics as JSON:

{
  "active_connections": 342,
  "broadcast_subscribers": 485
}

Adjust max_connections based on your workload and available resources. The default of 10,000 is suitable for most production deployments.

Session-Based Web Auth

The Web UI uses cookie-based sessions. When you log in via the dashboard:

A session token is created and stored server-side
The token is sent as a secure, HTTP-only cookie
Each request validates the session before serving dashboard content
Sessions expire after inactivity and are automatically cleaned up

Security Checklist

For production deployments, verify these items:

security.mode = "auth_key" (not "none")
environment = "production" in server config
LIVEN_SECURITY_MASTER_KEY set via environment variable
liven.key excluded from version control
Client keys use least-privilege roles (read-only → write → admin)
ZTNA/mTLS enabled for network encryption (recommended)
Connection limits configured appropriately for workload