This document describes ferrocache's threat model, the defenses currently implemented, deployment recipes for various scenarios, and the known limitations operators need to handle out-of-band.

ferrocache exposes four distinct attack surfaces. Each row below states the threat, the in-tree defense, and what an operator still has to do.

cargo run --release
# or
docker run -p 3000:3000 ghcr.io/nickleodoen/ferrocache:latest

No auth, no TLS. Fine for local development. Do not expose this port to the public internet.

The reverse proxy (nginx, caddy, ALB, Cloud Run, …) handles public TLS termination. ferrocache validates the bearer token; the proxy adds it to every request from authenticated upstream clients, or proxies straight through if clients carry the header themselves.

# On the ferrocache host:
export FERROCACHE_AUTH_TOKEN="$(openssl rand -hex 32)"
export FERROCACHE_PORT=3000
ferrocache  # listens on plain HTTP at :3000, only accessible from the proxy

# nginx snippet
server {
    listen 443 ssl http2;
    server_name cache.example.com;
    ssl_certificate     /etc/letsencrypt/live/cache.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/cache.example.com/privkey.pem;

    # Optional: rate-limit failed auth attempts
    limit_req zone=auth burst=10 nodelay;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
    }
}

Pre-flight, on a trusted machine (ideally not one of the cluster nodes):

# 1. Generate certs
git clone <ferrocache repo> && cd ferrocache
cargo run --bin gen_certs node1 node2 node3
# → ./certs/ca.pem
# → ./certs/node{1,2,3}/{cert.pem,key.pem}

# 2. Distribute. Each node gets the CA + its own cert/key. NOT other nodes' keys.
scp certs/ca.pem certs/node1/* node1:/etc/ferrocache/certs/
scp certs/ca.pem certs/node2/* node2:/etc/ferrocache/certs/
scp certs/ca.pem certs/node3/* node3:/etc/ferrocache/certs/

# 3. Wipe the local copy of the keys.
shred -u certs/node*/key.pem

On each node, run with auth + mTLS enabled:

export FERROCACHE_AUTH_TOKEN="$(cat /etc/ferrocache/auth-token)"  # same on every node

export FERROCACHE_CLUSTER__ENABLED=true
export FERROCACHE_CLUSTER__GOSSIP_ADDR=0.0.0.0:4000
export FERROCACHE_CLUSTER__API_ADDR=node1:3000  # change per node
export FERROCACHE_CLUSTER__SEED_NODES=node2:4000,node3:4000  # change per node

export FERROCACHE_CLUSTER__TLS__ENABLED=true
export FERROCACHE_CLUSTER__TLS__CA_CERT_PATH=/etc/ferrocache/certs/ca.pem
export FERROCACHE_CLUSTER__TLS__NODE_CERT_PATH=/etc/ferrocache/certs/cert.pem
export FERROCACHE_CLUSTER__TLS__NODE_KEY_PATH=/etc/ferrocache/certs/key.pem
export FERROCACHE_CLUSTER__TLS__INTERNAL_PORT=4443

ferrocache

Verify the cluster converged: curl -H "Authorization: Bearer $TOKEN" http://node1:3000/cluster/status should report node_count: 3.

The gen_certs binary produces certs valid until year 4096 — fine for development, not appropriate for production. For production:

• Use your existing PKI (HashiCorp Vault, AWS PCA, internal corporate CA).
• The cluster CA can be a standalone offline CA whose only job is signing ferrocache leaf certs. Its private key never needs to live on a ferrocache node.
• Each node's leaf cert needs subjectAltName covering the hostname/IP peers will dial it by, plus extKeyUsage = serverAuth, clientAuth since the same cert plays both roles in mTLS.
• ferrocache loads certs at startup from the configured paths. Rotation is a rolling restart: replace the files on disk, then restart one node at a time.
• ferrocache does not support CRLs or OCSP. If a node's key leaks, you must rotate the entire CA and reissue all node certs.

Public clients should never be able to reach the gossip or internal ports. If they can, they can spoof gossip membership or attempt mTLS handshakes (which they will fail without a valid client cert, but the noise is unnecessary).

Any of the cert path fields missing → ferrocache generates self-signed certs in memory and logs a warning. Each node's auto-generated CA is unique, so peers do not trust each other — useful only for single-node smoke tests.

• No at-rest encryption. WAL and snapshot files are plaintext on disk. Mitigate with full-disk encryption.
• No per-client ACLs. Authentication is binary: any caller with the token can do anything (read, write, compact). A future "read-only token" / "admin token" split is reasonable but not implemented.
• No certificate revocation. Compromised node keys require rotating the entire CA.
• No rate limiting on auth failures. Even with constant-time comparison, an attacker can grind tokens at line-rate. Handle at the reverse proxy.
• Token rotation requires a restart. Hot-reloading tokens isn't supported. Plan rotations during a maintenance window or rely on the rolling restart that mTLS rotation already requires.
• Gossip UDP is unencrypted. Ring metadata (node IDs, addresses) leaks to anyone with read access on the gossip port. Restrict via firewall.
• Tokens are loaded into memory and never zeroized. A core dump or /proc/<pid>/mem read by a privileged user reveals the token. Guard the host accordingly.
• Public-port TLS is out of scope. ferrocache itself only speaks plain HTTP on the public port. Use a reverse proxy for public TLS termination.