Security
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.
The trust boundaries
Section titled “The trust boundaries”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.
What it does not do
Section titled “What it does not do”- No TLS of its own. Terminate at a proxy; keep
--listenloopback. - No request signing to handlers — private network or nothing.
- No tenant isolation — one server, one trust domain; the
op_keynamespace 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.
Per-client limits
Section titled “Per-client limits”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.
./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; donecurl -s http://127.0.0.1:58301/healthkill $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.
Checklist
Section titled “Checklist”DURABLE_API_KEY≥ 32 chars, generated (openssl rand -hex 32), in an env file0600— never a flag, never committed.DURABLE_READ_KEYset wherever a read-only credential is enough (Inspector, dashboards).–listenon loopback behind the proxy, or on a private interface only — never a public bind without a proxy plan.–open-readsoff on anything proxied or shared.–trusted-proxylisting 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-rooton local disk,0700, service-user owned. /readydriving the load balancer;space_okanderrorsalerting.- A tested restore — backups is the drill.