Skip to content

Durable Authority

Operating the durable authority: identities, credentials, multi-voter TLS, storage and service management. For a walkthrough, start with the Durable Authority guide.


PropertyDurable authority
Publish unitAtomic per-namespace transaction
VersionsAssigned by the authority
Concurrency controlCompare-and-set on keys and namespaces
RetriesExactly-once results per session sequence
AuthenticationBearer tokens, namespace authorization
Transport securityPublisher TLS; mutual TLS between voters
Consensus stateDurable terms, votes and log
Applying a changeCopies the affected tree paths only
DistributionAuthenticated snapshots and deltas to managed agents

FieldRequiredMeaning
cluster, group, epochyesIndependent nonzero 128-bit identities, 32 hex digits
directoryyesStorage directory, relative to the config file
credentialsyesProducer and reader credentials (below)
nodewith votersThis process’s voter ID
votersmulti-voter3 or 5 voters: id, IP host, port, certificate_sha256
peer_tlsmulti-votercertificate, key, ca for mutual TLS between voters
publisher_tlsmulti-voter, or any non-loopback bindcertificate, key, ca for publisher HTTPS
publisher_bindnoPublisher listen address, loopback by default
publisher_namenoCertificate name --status verifies, localhost by default
consensus_limitsnolog_entries (64–65,536) and log_bytes (2–64 MiB)
retained_statenoLocal recovery envelope: command_bytes (1 MiB), log_bytes (64 MiB), log_entries (65,536), batch_bytes (2 MiB), batch_entries (256). Each is at least its operating limit; see below
journal_limitsnohard_bytes, hard_entries, control_bytes, control_entries, replacement_bytes (512 MiB), replacement_entries
delivery_limitsnoheap_bytes (default 128 MiB) and wire_bytes (default 256 MiB)
storage_backendnoauto, or native/fallback on Linux

The replacement pool (journal_limits.replacement_bytes) must hold the application image, the encoded retained log (retained_state.log_bytes and log_entries) and 4096 bytes: 336,931,316 bytes with the defaults. A node that falls short refuses to start and names each term and the shortfall, for example `the replacement pool holds 72690163 bytes but the application image (4194304)

  • the encoded retained suffix (68491764) + the publication allowance (4096) need 72690164, short by 1 byte. Lowering consensus_limits` does not lower this requirement.

Each credential:

FieldMeaning
tokenBearer token, at least 32 characters, unique
producerUnique producer name
namespacesNamespaces this credential may write and read
principalOptional stable principal for scope identity; defaults to the producer
policy_epochOptional nonzero policy epoch, default 1; bump it when grants change
publishOptional, default true; false makes a read-only agent credential

Rotating a token while keeping the producer name preserves the producer’s session; changing the restore identity fences older requests.


  1. Generate fresh cluster, group and epoch identities and fresh, empty stores for every voter.
  2. Issue each voter a leaf certificate and record the SHA-256 fingerprint of its DER encoding in every voter’s voters list. A peer is admitted only if its certificate chains to peer_tls.ca and matches its pin.
  3. Give every voter the same identities, voter list and limits; set node per process. A voter with a different quorum or application profile fails peer admission before any data is exchanged.
  4. Configure publisher_tls for publishers; non-loopback publisher binds require it.

The replicated profile uses a 100 ms heartbeat, a 500 ms RPC deadline and randomized 1–2 s elections. TLS below 1.2, early data and renegotiation are disabled.


The authority persists Raft terms, votes and log entries, and periodic application checkpoints, to its directory. Checkpoints start automatically when retained entries or bytes reach half their configured limits; old files are reclaimed by bounded maintenance afterwards.

On macOS and FreeBSD the authority drives storage through a completion-based backend; on Linux it uses io_uring when available, with a fallback. storage_backend makes that choice explicit on Linux. Startup recovery is synchronous and completes before requests are admitted.


Run detent-authority --authority CONFIG in the foreground under the service manager; see System Services. Use a private state directory owned by the service account.

Terminal window
detent-authority --status --authority /etc/detent/authority.json

With publisher TLS, --status checks the HTTPS endpoint with CA and name verification and a two-second deadline.