# Security

> The honest security model — unsigned handler calls on private networks, two keys, loopback-only open reads, a plaintext journal — and the checklist that follows.

Source: https://docs.durable-runner.404human.dev/self-hosting/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

**Handlers live on a private network; their calls are unsigned.** The runner `POST`s 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

- **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.

## 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](https://docs.durable-runner.404human.dev/self-hosting/configuration/).

```sh
./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
```

```json
{"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

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