Skip to content

Security

View as Markdown

Durable Runner is a single-tenant runner: it trusts its operators completely and its network not at all. Everything below is the model as it stands today — including what it deliberately does not do.

Handlers live on a private network; their calls are unsigned. The runner POSTs to registered URLs with no signing, no key, no mTLS — the --handler allowlist and your network segmentation are the entire boundary. Anything that can reach a handler’s URL can invoke it. Keep handlers on loopback or a private segment the runner host also sits on; never expose a handler port to anything routable.

Two keys, environment only. DURABLE_API_KEY (write + admin) and DURABLE_READ_KEY (reads only). Both ≥ 32 chars, read at startup, never accepted on a command line. The whole surface is Authorization: Bearer; there are no per-user tokens, no sessions, no ACLs beyond read/write.

--open-reads is loopback-only — and never behind a proxy. It exists for a developer’s own machine: refused at startup on a non-loopback listen, Host-checked against rebinding. A proxy breaks the assumption it’s built on — remote requests arrive looking local. With a proxy in front, reads take DURABLE_READ_KEY and --open-reads stays off.

The Inspector keeps its key in sessionStorage only — nothing is written to localStorage, a cookie, or the URL, so the key dies with the tab. Give it the read key: a sessionStorage leak then costs read access, not the write side. Never paste DURABLE_API_KEY into a browser you don’t fully control.

The journal is plaintext. Submitted inputs and handler replies are stored verbatim — the journal, snapshots and backups are all equally sensitive. Filesystem permissions (0700/service user) and disk encryption are the mitigations; treat backups/ exactly as sensitively as the journal itself.

  • No TLS of its own. Terminate at a proxy; keep --listen loopback.
  • No request signing to handlers — private network or nothing.
  • No tenant isolation — one server, one trust domain; the op_key namespace is shared.
  • No exactly-once claims — at-least-once plus idempotent handlers is the honest ceiling; a handler can’t be made safe by the runner alone.
  • Keys are never logged, and job payloads never appear in the server’s log either.

One address can’t hold every connection or spend every request. --rate-limit-per-addr (100/s default, 429 rate_limited + Retry-After), --max-conns-per-addr for untrusted peers, and --max-conns-per-proxy for trusted proxies — a proxy aggregates clients, so it gets its own allowance. --trusted-proxy (repeatable CIDR) is the trust line: the client address comes from CF-Connecting-IP only behind those ranges — list your proxy ranges precisely, since a too-wide range lets any caller name its own address. IPv6 keys at /64 with a /48 aggregate; v4-mapped addresses count as IPv4. Details: configuration.

Terminal window
./target/release/durable-server --journal journal-trust --listen 127.0.0.1:58301 \
--trusted-proxy 10.0.0.0/8 --max-conns-per-proxy 512 >trust-server.log 2>&1 &
TRUST=$!
for _ in $(seq 1 100); do curl -sf http://127.0.0.1:58301/health >/dev/null && break; sleep 0.1; done
curl -s http://127.0.0.1:58301/health
kill $TRUST 2>/dev/null; wait $TRUST 2>/dev/null || true; rm -rf journal-trust trust-server.log
{"ok":true}

The forged header rule, in words: CF-Connecting-IP is believed only from a peer inside --trusted-proxy, because anyone can set it — the rate key is the real client behind your proxy, never a header a stranger sent.

  • DURABLE_API_KEY ≥ 32 chars, generated (openssl rand -hex 32), in an env file 0600 — never a flag, never committed.
  • DURABLE_READ_KEY set wherever a read-only credential is enough (Inspector, dashboards).
  • –listen on loopback behind the proxy, or on a private interface only — never a public bind without a proxy plan.
  • –open-reads off on anything proxied or shared.
  • –trusted-proxy listing exactly your proxy ranges — a wide range lets a caller claim any client address.
  • Per-client rate and connection limits on behind anything untrusted.
  • Handler ports reachable only from the runner host.
  • Journal and –backup-root on local disk, 0700, service-user owned.
  • /ready driving the load balancer; space_ok and errors alerting.
  • A tested restore — backups is the drill.

Was this page helpful?

Either answer opens a short issue on GitHub, so you can say what worked or what was missing.