For the technical audience

Decisions ADR-901 to ADR-948

Every architecture decision record (ADR) behind WrenDNS: what we knew, what we chose, and what it costs. This page is built from the specification on every change, so it's always the current record.

ADR-901 Device names in DNS: built off the path from the names WrenDNS already has, after configured data, one label eachAccepted 2026-11-16CLUDNST22.1 (DNS-023).

Context

T22.1 (DNS-023). People want DNS kept in step with DHCP leases (dnsmasq's and Technitium's DHCP do it) but ADR-091 keeps DHCP with the router. WrenDNS already holds the routers' leases, Home Assistant's names, mDNS names, and named devices, by address.

Decision

  • Off by default. [local] device_domain turns it on (home.arpa, RFC 8375, in the docs); local is refused (RFC 6762). device_ttl 60 s (names follow DHCP). mDNS names only with device_mdns and the listener on.
  • Sources and their order for an address: a named device matched by exactly that address or by the lease's MAC (a CIDR client names a set of devices, so never) → a router's or Home Assistant's name (ADR-902's order) → an mDNS name; this node's routers first, then the peers' (CLU-002).
  • One label per name: lowercase ASCII letters, digits, and hyphens, at most 63 bytes; apostrophes dropped, everything else separates words. No punycode: a name with no ASCII letters or digits is skipped.
  • Reserved labels: wpad and isatap (how Windows finds a proxy and an IPv6 tunnel: a device that names itself so could take over other machines' traffic; dnsmasq and Windows DNS's global query block list refuse them) and localhost are never device names.
  • Collisions: one label, one address: the better source, then the lower address, keeps it; the others get neither A nor PTR (half-registered names would point the PTR somewhere the A doesn't). Counted in the log line for each change.
  • Where it answers: after [[record]] and hosts files, after a zone's own records, before the zone's NXDOMAIN or NODATA; never filtered, like other local data. An unknown name under the domain falls through as before (a route may send the domain to the router).
  • On the path: a LocalData (the same allocation-free lookup as local records) behind an ArcSwap on the pipeline, rebuilt by a task every 10 s only when its inputs changed. The query path checks Policy::device_dns first: off, one branch; on, one lock-free load and the usual empty-map early return.

Alternatives rejected

a zone generated into the configuration (the configuration is signed, versioned, and replicated; leases change every few minutes); RFC 2136 dynamic updates from the router (UniFi doesn't send them); rebuilding on every lease change (the routers are read every few minutes; 10 s is soon enough and bounded).

Consequences

names appear within about 10 s of a router read; renaming a device in WrenDNS renames it in DNS; the PTRs make reverse lookups of private addresses answer for named devices (RFC 6303's NXDOMAIN still applies to the rest).

Requirements CLU-002 DNS-023

Builds on ADR-091 ADR-902

Referenced by ADR-910 ADR-914 ADR-958 ADR-983

ADR-902 More naming sources: UniFi reservations and networks, Home Assistant through a template, and a fixed order when sources disagreeAccepted 2026-11-16APIT22.2, T22.3 (API-012, API-013).

Context

T22.2, T22.3 (API-012, API-013). ADR-080 left UniFi's offline known clients undone; Home Assistant knows curated names for IoT devices (by MAC, not IP); a home has a router and Home Assistant naming the same address. ADR-080's lease view kept whichever router was read last (a HashMap walk).

Decision

  • UniFi: after stat/sta, read rest/user and rest/networkconf with the same key or session. Only known clients with use_fixedip and a fixed_ip are kept (a last address may belong to someone else by now); a connected device's current address wins over its reservation. Networks: the ones with an ip_subnet, not WAN or VPN; the subnet from the gateway's address and prefix; the VLAN only when enabled; the pool only when DHCP is on. Both reads are optional: refused or failed, the connected clients still name devices, and one log line says what was skipped (again only when that changes).
  • Home Assistant (type = "home_assistant", api_key_file = a long-lived access token): its registry has no REST endpoint, and a WebSocket client would be a new dependency in the binary. One POST /api/template renders a fixed, read-only template (every device with an entity and a mac connection: name_by_user, name, its MACs, its area; every device_tracker with mac and ip). Rendering templates needs an administrator's token; the error says so. Addresses: the routers' answers for that MAC, else Home Assistant's trackers; a device with no address is skipped. Routers are polled before Home Assistant in each round so its devices find this round's addresses.
  • Order when two sources name one address: a name a person gave in Home Assistant (name_by_user) → the routers' names, in [[router]] order → a Home Assistant integration's name (often the model: Shelly Plus 1PM). A better source without a name doesn't hide a worse one's. Each lease records the [[router]] that named it (router, optional in the peer wire form, so N-1 peers interoperate).
  • Networks API is read on the node that reads the routers, like the leases (not federated). Agent tokens read GET /api/v1/dhcp/leases and GET /api/v1/networks with config:read (the inventory is no more sensitive than /clients, which already needs it).

Alternatives rejected

a WebSocket client for Home Assistant's registry (a new dependency on the binary for one read); Home Assistant's names always winning (its integrations' default names are model names, worse than a router's alias); known UniFi clients without a reservation (stale addresses would name the wrong device in DNS, T22.1).

Consequences

two more GETs per UniFi poll; one template render per Home Assistant poll (sub-second on a few thousand entities); names in the query log and DNS can now come from Home Assistant.

Requirements API-012 API-013

Builds on ADR-080

Referenced by ADR-901 ADR-907 ADR-910 ADR-912 ADR-942 ADR-998 ADR-999

ADR-903 Secrets entered in the UI: a write-only encrypted store referenced by name, replicated to full members outside configuration versions, with files still winningAccepted 2026-11-16AGTAPICLUNFROBSOPSOn 2026-11-16 the owner asked that anything configured today through a secret file can also be entered in the UI, and that the files keep working.

Context

On 2026-11-16 the owner asked that anything configured today through a secret file can also be entered in the UI, and that the files keep working. The owner fixed four points:

  1. A secret entered in the UI replicates to full cluster members over the mTLS cluster channel and is re-encrypted on each node. It never reaches ephemeral resolver pods.
  2. Secrets are encrypted in state.db with a per-node key: <data_dir>/secrets.key (0600) by default, or one that comes from an environment variable or a mounted file.
  3. A backup carries secrets only when they are encrypted with a passphrase given at backup time, and the backup says so when it leaves them out.
  4. A *_file or inline value in the configuration files wins. The UI shows it as set by file and won't edit it.

The code this ADR changes is at commit 412add6.

  • Where secrets live now.
    • Most are files named by a *_file path and read when used: routers.rs:112-119, alerts.rs:737-745,809-817, sinks.rs:719-725, gitsource.rs:205-210,419-422, auth_setup.rs:69-78, wrendns-cluster/src/net.rs:1008-1015.
    • The rest are inline values: auth.oidc.provider[].client_secret (schema.rs:2745), upstream[].headers (schema.rs:520-522) and telemetry.otlp.headers (schema.rs:2388).
    • SafeString prints the plain value in both Debug and Serialize (wrendns-config/src/types.rs:49-75).
  • Existing leaks.
    • GET /api/v1/config/entries returns serde_json::to_value(e) (api_backend.rs:2895), so upstream headers and exec args come back unredacted. On a replica the primary's body is passed through unchanged (federated.rs:2439-2450).
    • The write path copies bodies into these places:
      • the idempotency table (config_api.rs:190,1850-1860);
      • the audit {before, after} (config_api.rs:1902-1913);
      • a second audit entry on the primary for every forwarded write (forward.rs:232-237);
      • the keepInGit TOML (api_backend.rs:5223-5260);
      • the forward to the primary (federated.rs:2412-2422). forward::Write derives Debug with the raw body (forward.rs:31).
    • wrendns config check --print prints inline secrets (main.rs:1622-1623).
    • The Git webhook returns the internal error (file path, I/O error) with its 401 to anyone (api_backend.rs:3285-3289). It also HMACs with secret.trim(), so an empty secret file gives an empty key that anyone can forge (gitsource.rs:419-432).
  • Existing exfiltration paths.
    • An operator can point an alert destination's token_file at any file the process can read (for example <data_dir>/cluster/ca.key or /proc/self/environ) and its url at their own host (alerts.rs:809-817).
    • An operator, or an agent with config:write:upstreams, can create an exec:// upstream (validate.rs:19,1462-1468). The plugin is spawned with the parent's whole environment and no env_clear/env_remove (wrendns-upstream/src/plugin.rs:55-62). Self-update spawns the same way (selfupdate.rs:101,201).
    • The primary applies a forwarded write with only by: String and no role (forward.rs:34-44,182-191).
  • Precedents for secrets between nodes.
    • ADR-045 replicates TOTP secrets, stored as plain BLOBs (wrendns-store/src/state/identity.rs:33,142).
    • ADR-051 sends the CA key in KeyShare (wire.rs:75-83).
    • ADR-143 withholds identities from ephemeral members (net.rs:2530-2545). Witnesses are non-ephemeral but serve no DNS or UI (node.rs:39,747-751).
    • So ADR-045's "never cross the cluster channel" really covers only file secrets.
  • Ordering and versions.
    • Configuration orders by (epoch, seq) with a base for orphan detection (sync.rs:36-60) and is fenced (net.rs:645-647).
    • Pins and canary rollouts gate everything in ClusterManifest (spec/12 §4, CLU-013).
    • ClusterManifest has no deny_unknown_fields, and heartbeats are prost messages, so new optional fields are N-1-safe.
    • Config structs do use deny_unknown_fields (schema.rs:3,1249), and with_shared refuses unknown shared keys (shared.rs:84-90). An N-1 replica therefore refuses a version that uses a new field, the same limit ADR quick-rules records (spec/11:1242).
  • Startup-only readers.
    • [[router]] (server.rs:1099-1106). resolver_pod there only lowers the log level, so pods do poll today (routers.rs:724-738).
    • OIDC. Auth.oidc is a OnceLock, set_oidc silently ignores every set after the first (wrendns-api/src/auth/mod.rs:315,404,465-467), and in-flight flows live inside Oidc.flows (oidc.rs:107,279).
    • Sinks (sinks.rs:66-72). Sink::record takes &mut self (ring.rs:527) and DROPS is a OnceLock (sinks.rs:52,112).
    • Alerts, Git and the bootstrap secret re-read at use.
  • Settings only in files: [[router]], OIDC providers, sinks, [cluster.git], [identify] and the Groups form's device_classes.
  • Spec inconsistency: ADR-045's implementation note says OIDC provider settings replicate, but auth is in NODE_LOCAL (shared.rs:15-26).
  • Other code facts.
    • The release profile aborts on panic (Cargo.toml:46-51).
    • state.db runs WAL with no secure_delete (state.rs:250-254).
    • [api] tls defaults to none (schema.rs:2618-2625).
    • The edition is 2024, so std::env::remove_var is unsafe (AGENTS rule 7).
  • Already linked: ring 0.17.14 (direct in crates/wrendns), blake3 and arc-swap (direct), argon2 0.6.0 (wrendns-api), zeroize 1.9.0 (transitive). The image is about 14.70–14.75 MiB against the 15 MiB gate.

Decision

1. Scope.

FieldDecisionWhy
router[].api_key / api_secret / password (UniFi, OPNsense, Home Assistant token)In (T23.3, T23.7–8)The main case. A router whose credential is stored polls on the primary (or a standalone node) only. The others get its names through ADR-125's peer leases, which keeps ADR-125's "not every node polls" rule. A router whose credential is a file keeps polling where it does today, except that ephemeral pods now skip it explicitly.
alerts.destination[].token / passwordIn (T23.6)Read at each delivery, on the primary or a standalone node.
cluster.git.credentials / webhook_secretIn (T23.12)Read at each poll or request. Replication means every Git-eligible primary has them.
telemetry.sink[].token, telemetry.otlp.headersIn (T23.11)Telemetry never affects DNS (02 §8). On ephemeral pods a sink that needs a stored secret is skipped and logged once at info.
auth.oidc.provider[].client_secretIn (T23.10)Only full members serve the UI.
upstream[].headers, upstream[].tls_client_keyLaterThey sit on the answering path, and resolver pods would never have the value (decision 1, CLU-004). Inline and file values keep working, and T23.1 redacts them.
upstream[].args, URL and proxy userinfoOut (redacted only)Not credential fields by design. exec:///unix:// become admin-only (T23.2).
listen[].tls.key, api.tls.keyLater (P2), status only nowA node's own identity, already hot-reloaded (wrendns-net/src/tls.rs:26-78). Replicating one node's key is wrong, and a bad API key could lock out the UI.
cluster.bootstrap_secretOut, status onlyPods need it before the channel is trusted (ADR-058).
allowed_signers_file, trust_anchors_file, *.tls_ca, signatures_fileNot secretsA router's CA becomes an inline tls_ca_pem (T23.8). The others stay files.

Non-secret settings that exist only in files are phased with the forms that need them:

  • a router kind (T23.7);
  • oidc_provider and sink kinds (T23.10–11);
  • Git *_ref fields. [cluster.git] itself stays file-only, pinned by set-authority (ADR-049);
  • identify-settings and [[group]] device_classes (T23.13).

2. Data model.

  • A new table, not managed. Migration 11 creates: secrets(name TEXT PRIMARY KEY, kind TEXT NOT NULL, key_id BLOB, nonce BLOB, ciphertext BLOB, stamp_epoch INTEGER NOT NULL, stamp_seq INTEGER NOT NULL, deleted INTEGER NOT NULL DEFAULT 0, origin TEXT NOT NULL, updated INTEGER NOT NULL, updated_by TEXT NOT NULL).
    • A row with deleted=1 is a tombstone with no ciphertext.
    • Tombstones are kept for 90 days, and at most 512 of them, so offline members still learn of deletions.
    • The managed copy paths (shared_part, config/entries, keepInGit, audit) never see this table.
  • Stamps. Every change is stamped (epoch, seq). On a cluster that is the current epoch and a per-epoch counter, taken under fence and the lease check (may_publish, ADR-056). On a standalone node it is (0, n). A stamp is never reused, delete-then-recreate included.
  • The secrets head is {stamp, digest}. digest = BLAKE3 over the sorted (name, kind, stamp, deleted) list. It holds no value and no value hash.
  • Names match ^[a-z0-9][a-z0-9._-]{0,62}$. kind is text (pem is reserved).
  • Values.
    • At most 8 KiB, UTF-8, trimmed.
    • Empty after trimming is refused, and webhook_secret needs at least 16 characters.
    • text refuses every control character (as SafeString does). pem will allow \n.
    • "<redacted>" is refused as a value.
  • Limits: at most 128 live secrets, and at most 512 KiB of encoded values in one fetch (section 6).
  • References. Each field gets a sibling <field>_ref = "<name>":
    • router[].api_key_ref / api_secret_ref / password_ref;
    • alerts.destination[].token_ref / password_ref;
    • auth.oidc.provider[].client_secret_ref;
    • telemetry.sink[].token_ref;
    • telemetry.otlp.header_refs = {"<Header>" = "<name>"};
    • cluster.git.credentials_ref / webhook_secret_ref.

These fields are serialized only when set, so configurations without them still converge on N-1 replicas. The UI names a new secret <kind>.<entry>.<field>, while the configuration always holds the explicit name, so a Git-managed file can say api_key_ref = "unifi".

  • Validation (validate.rs):
    • At most one of inline, _file and _ref per field.
    • A missing _ref is a load warning (DNS never depends on the store) and a 422 secret_missing on an API write.
    • "<redacted>" in a file is a load error.
  • Precedence, judged against the file layer and not the effective entry (decision 4). The file layer is TOML, WRENDNS_* and CLI; on a replica, for a shared section, it is the primary's file layer as published.
    1. If the file layer sets the field inline or by _file, the source is inline/file. The UI shows "Set by file (<path>, read on each node)" and whether it is readable on this node. An API write that sets, drops or replaces it, whether by _ref, an ADR-069 override or a hidden entry, is refused with 409 set_by_file. An override that changes other fields gets the file's credential field carried over by the server.
    2. Otherwise a _ref gives stored.
    3. Otherwise the source is none.
  • Kinds.
    • router and oidc_provider follow ADR-040: names defined in the files are read-only through the API.
    • Alert destinations keep ADR-069, constrained by rule 1.
  • One resolver. wrendns::secrets::Credential::resolve(inline, file, ref) -> Resolved { value: SecretValue, source } replaces the six read sites.
  • SecretValue.
    • Its Debug and Display print <redacted>, it has no Serialize, and it is zeroized on drop.
    • The claim is limited to our own buffers: prost, TLS and stream buffers are not zeroized, and the docs say so.
  • Readable checks open the file read-only with O_NONBLOCK and close it without reading. A file that isn't a regular file reports "not usable". stat alone can't tell readability.

3. Encryption and the node key.

  • Cipher. ChaCha20-Poly1305 from ring::aead, so no new crate. It is fast on a Pi 4, which has no AES instructions.
  • Nonce: 96 random bits from SystemRandom per encryption. With a few thousand writes per key this stays far below 2^32.
  • Associated data: "wrendns-secret\x01" ‖ key_id ‖ kind ‖ name ‖ be64(stamp_epoch) ‖ be64(stamp_seq), with kind and name each preceded by its be16 length (note 39).
  • Key format.
    • A key is 32 random bytes, written as ttsk1:<base64url, no padding>.
    • key_id is the first 8 bytes of blake3::derive_key("wrendns secrets key-id v1", key).
    • Subkeys are derived as "wrendns secrets aead v1" and "wrendns secrets idempotency v1".
  • Key source, first match wins:
    1. WRENDNS_SECRETS_KEY;
    2. [node] secrets_key_file (env WRENDNS_NODE_SECRETS_KEY_FILE; the only spelling documented);
    3. <data_dir>/secrets.key.

The previous key comes from WRENDNS_SECRETS_PREVIOUS_KEY or [node] secrets_previous_key_file. Both variables join RESERVED (env.rs:22-44). Spawned processes (plugins, self-update) have them, WRENDNS_BOOTSTRAP_ADMIN_PASSWORD* and WRENDNS_TOKEN removed with Command::env_remove; no unsafe. The docs prefer a file, and on Kubernetes secretKeyRef over a literal value.

  • Creating the data-dir key. secrets.key is generated only when the secrets table holds no rows and no tombstones.
    • It is created with O_CREAT|O_EXCL, mode 0600, written and fsynced, never renamed over an existing file.
    • A key file readable by others, or owned by another user, gives a warning. Group read by the process's own gid doesn't warn (kubelet with fsGroup).
  • Rotation.
    • At start, rows under the previous key_id are re-encrypted in one transaction, followed by wal_checkpoint(TRUNCATE).
    • wrendns secrets rotate-key is offline and covers the data-dir key only. It writes secrets.key.new, re-encrypts, commits, checkpoints, then renames. A leftover .new file is tried by key_id at the next start.
  • Locked store. The store is locked when:
    • a configured source (1 or 2) can't be read or parsed;
    • source 3 is missing while rows exist;
    • or no row decrypts under any available key.

While locked:

  • nothing is generated, and secret writes return 503 secrets_locked;
  • status reads work, and health shows secrets_locked (degraded, OBS-015);
  • DNS and /readyz are unaffected.

One exception: a replica whose rows are all origin='cluster' may generate a new key, drop those rows and refetch.

  • Row states. A row whose key_id matches neither key is unreadable, and one that fails authentication is corrupt. Re-entering the value, or a sync, repairs it.
  • When a secret can't be read. An integration that needs an unreadable secret reports "not configured: secret <name> can't be read on this node (<reason>)" and logs once until that changes. The metric is wrendns_secrets{state}.
  • Threat model (docs/secrets.md).
    • With the data-dir key, the store protects copies of state.db and backups, not someone who holds the whole data directory.
    • Admins are trusted not to misuse a stored secret, but cannot read one back (except through a passphrase backup, section 8).
    • Operators and agents can neither read nor redirect one.

4. API and rules.

  • Routes.
    • GET /api/v1/secrets[/{name}] (operator; agents with config:read) returns metadata only:
      • name, kind, set, stamp, updated, updatedBy, origin;
      • usedBy [{kind, name, field, source, node?}];
      • nodes [{node, applied, unreadable}];
      • credentials: every credential field on this node with its source, its path and whether it is readable.

On a replica this is proxied to the primary when one is reachable (as config_entries is). Otherwise it is local with stale: true.

  • PUT /api/v1/secrets/{name} takes {"value", "kind"}, and DELETE /api/v1/secrets/{name}. Both need admin, answer with metadata only, and carry Cache-Control: no-store.
    • DELETE of a referenced secret is 409 secret_in_use, listing users across nodes (section 6). If a full member's references are unknown (offline), it needs ?force=true.
  • Transport. PUT /secrets and a passphrase POST /backup are refused with 403 insecure_transport unless the request is HTTPS (is_https, including trusted proxies) or comes from loopback.
    • [api] allow_secrets_over_http = true (node-local, file only) lifts this.
    • The UI explains and links to [api] tls = { self_signed = true } (ADR-149).
  • Agents: 403 agent_not_allowed on secret writes whatever the scopes.
  • AGT conformance.
    • AGT-001: value is writeOnly.
    • AGT-002: ?dryRun=true checks name, kind and size, reports wouldCreate/wouldReplace and the entries that would become configured, and stores nothing.
    • AGT-003: the stored request is PUT /secrets/{name} plus the hex keyed BLAKE3 of the value under the idempotency subkey. The same key with a different value is 409.
    • AGT-005: audited as secret.put|delete {name, kind, stamp, usedBy}, never the value or its length.
    • If-Match takes the secrets head as an ETag.
  • On a replica, writes are forwarded to the primary as a dedicated RPC kind secret.put/secret.delete, not a variant of api.write, so an N-1 primary refuses it by kind.
    • The value travels as SecretValue, and the request type's Debug redacts.
    • The forward carries role and agent (below), and logs only the operation and the name.
    • With no primary reachable, the answer is 409.
  • When writes are allowed.
    • Lease and fence: a primary without a valid lease, or past the fence, refuses with 409.
    • GitOps authority: secret writes are allowed (secrets are state, never in Git, ADR-049); entry writes stay 409 gitops_managed.
    • Emergency primary: 409.
    • Pin or canary rollout: allowed. The secrets head travels outside ClusterManifest (section 6), so pins and rollouts neither hold it back nor bump seq.
  • Credential rules for entries (T23.2):
    • Creating or changing any *_file or *_ref, or the destination fields of an entry that has any credential (inline, file or ref), needs admin. Destination fields are url, proxy, host, tls_server_name, tls_ca, bootstrap and the scheme.
    • The router, oidc_provider and sink kinds are admin-only.
    • Creating, or switching to, an exec:// or unix:// upstream needs admin, on writes and on checks/upstream alike.
    • API-set paths:
      • are canonicalized at write and at use;
      • must not be under /proc, /sys, /dev, data_dir, or any configured key, previous-key, bootstrap or TLS key path, and these denials apply to every API-settable path (list[].path, tls_ca included);
      • *_file must also sit under [node] secret_file_dirs (node file only; default /run/secrets, /var/run/secrets, /etc/wrendns/secrets).
      • An existing API-set path outside these rules stops being read and reports the reason in credential_issues.
    • An admin write that changes the destination of an entry with a _ref, or points a _ref at a secret already used by a different kind, is audited as credential.redirect and raises the alert event credential_redirected.
    • Forwarded writes carry role and agent, and the primary re-checks every rule. A credential-affecting write forwarded without a role (an N-1 replica) is refused with 409 upgrade_required.
  • Redaction everywhere bodies are copied (T23.1).
    • wrendns-config::credentials::PATHS lists:
      • upstream[].headers.*, upstream[].args[*];
      • URL userinfo passwords in upstream[].url, upstream[].proxy and alerts.destination[].url;
      • auth.oidc.provider[].client_secret, telemetry.otlp.headers.*.
    • It is applied by:
      • config_entries (again on a replica after decoding);
      • write responses, both audit sites (config_api.rs:1902-1913, forward.rs:232-237, apply_ack);
      • the stored idempotency response;
      • keepInGit, forward logging, config check --print (--show-secrets opts in);
      • GET /cluster/compare, every MCP read tool and resource, and the support package.
    • Values come back as "<redacted>", and ConfigEntry.redacted lists the paths.
    • The marker rule: a PUT that sends "<redacted>" keeps the current value only when the entry's destination fields are unchanged. Otherwise it is 422 credential_reentry_required. With no current value it is 422 too. POST /checks/* never resolves markers.
    • Idempotency. The stored request is the keyed BLAKE3 of the canonical full body (node key, idempotency subkey), and the stored response is redacted. With the store locked, a write carrying an Idempotency-Key whose body holds a credential path is 503.
    • Migration 10 purges existing idempotency rows. state.db gets PRAGMA secure_delete=ON, plus wal_checkpoint(TRUNCATE) after the migration, after rotation and after secret deletes.
    • A test fails when a field classed secret in wrendns-support/src/classify.rs is in neither PATHS nor a reasoned allow-list (usernames). *_ref fields are class name.
  • The Git webhook answers a generic 401 and logs the detail, and refuses empty secrets.
  • Delivery errors keep hosts only, never URL queries. The Gotify token is percent-encoded (alerts.rs:821-825).

5. MCP and agents.

  • New read-only tools. secrets_status wraps GET /api/v1/secrets (config:read). list_routers wraps GET /api/v1/routers.
  • No write tools for secrets, or for the router, oidc_provider, sink or identify-settings kinds. These have no agent scope. A value would otherwise sit in AGT-007 plan memory, the approval diff and the agent's transcript, as with OPS-011 and ADR-156.
  • Plans meet the marker rule. MCP plans that merge from config/entries (mcp.rs:2321,2372) carry "<redacted>", so a plan that changes an upstream's destination fails at apply with credential_reentry_required, and the plan summary says so.
  • Agent forbidden list. POST /api/v1/backup, /checks/router* and the secret writes join it (agent.rs:590-598).
  • spec/13 §3 records these exceptions.

6. Replication (CLU-015, decision 1).

  • The head travels in heartbeats, not in configuration. The primary's Heartbeat (prost, new optional tags) carries secrets_head {epoch, seq, digest}. Nothing goes in ClusterManifest, so pins, canary bakes, If-Match configVersion, version history and lag are unaffected. N-1 nodes ignore the tags (CLU-010).
  • Fetching. A full replica sends the RPC secrets.fetch {since_digest} when the head's digest differs from its own.
    • It sends it only to the node it holds as primary of the highest epoch it has seen, and ignores a head from a lower epoch (spec/12 fencing rule 4).
    • Fetches happen at most once per head, back off from 30 s to 10 min on failure, and never run while the local store is locked.
    • Fetching never gates manifest application, applied or readiness (ADR-058).
  • The primary answers only a peer that its registry records as !ephemeral && !witness.
    • The answer is {head, items: [{name, kind, value?, stamp, deleted, updated, updated_by, held?}]}.
    • A row the primary can't decrypt is sent as held (no value), and the replica keeps its own row with that stamp.
    • A locked primary, or one that generated a new key, answers secrets_unavailable, and replicas keep their set.
    • An emergency primary still answers.
    • The answer is protobuf bytes, capped at 900 KiB encoded and paged beyond that. It never touches the blob store, so no plaintext reaches anyone's disk.
  • The replica checks that the answer's head equals the announced head and that the digest recomputed from the items matches. Otherwise it discards the answer.
  • Applying.
    • The replica re-encrypts each value under its own key.
    • In one transaction it upserts origin='cluster' rows by stamp: a higher stamp wins, and a tombstone deletes.
    • It never deletes a name by its absence from the set.
  • Orphans. Rows a demoted primary stamped in an epoch after the new primary's base are orphaned. They are not deleted, but listed under Conflicts as "re-enter on the current primary" and not used.
  • Origin.
    • On the primary every row is authoritative and stored as origin='cluster'. At cluster init and at join, a standalone node's rows become cluster rows on the primary.
    • On a joining replica, local rows stay usable on that node, and are flagged shadowed when a cluster row of the same name arrives.
    • On removal (ADR-155) or leave, cluster rows are purged and the purge is audited.
  • Reverse heal. A primary with unreadable rows fetches them from a registry-full replica holding the same stamp. The replica answers only the current primary.
  • Heartbeats from members carry secrets_applied (head), secrets_unreadable, credential_issues (at most 32 paths) and secret_refs: the names this node's node-local fields reference, at most 128, sent on change and every 60 s. DELETE checks the union of these.
  • Ephemeral pods hold no secrets, need no key, never generate secrets.key and never report secrets_locked.
  • Node-managed entries (oidc_provider, sink) are configuration, not secrets, so they are versioned. ClusterManifest gains an optional node_managed: BlobRef holding references only, which N-1 nodes ignore.
    • Every member persists the last one it applied.
    • Each member validates and merges it separately from the shared part, under its own files, where file ids win. A failure drops only those entries, logs once, and leaves the shared part and DNS untouched (CLU-004).
    • A newly promoted primary publishes the inherited blob overlaid with its own rows, and seeds its managed rows from it.
    • A primary with a Git source carries the blob unchanged, and writes of these kinds there are 409 gitops_managed.
    • Ephemeral members skip entries that need a stored secret, with one info log.

7. Hot reload. Nothing here touches the query path.

  • Routers.
    • routers::run reads the live [[router]] from Sources at each round, and no longer returns on an empty list. It recomputes interval each round.
    • Changed or removed routers are rebuilt or dropped, and unchanged routers keep their state.
    • A Notify on a router or secret change polls, debounced to at least 5 s.
    • Polling follows section 1's rule: stored credentials on the primary or a standalone node, file credentials as today, and ephemeral pods skip explicitly.
    • Failures are logged once until they change, and names stay as last read.
    • The release build aborts on panic, so routers.rs gets clippy::unwrap_used, expect_used and indexing_slicing denied, and malformed answers are tested.
  • OIDC.
    • Auth.oidc becomes ArcSwapOption<Oidc>.
    • In-flight flows (PKCE verifier, nonce) and the discovery cache move into Auth, so a swap keeps sign-ins in progress.
    • Rebuilds run one at a time with a generation counter, and a stale result is discarded.
    • A provider whose discovery fails keeps its previous settings, or is left out with a reason.
    • Sessions and the break-glass admin are untouched.
  • Sinks.
    • The drainer-owned EventSinks receives a new Vec<Out> through a channel try_recv once per batch.
    • DROPS becomes swappable.
    • Spill files are keyed by name plus a hash of the URL. A removed sink's thread is joined (2 s bound) before its name is reused, and its spill file is deleted.
    • OTLP headers are resolved per export batch.
  • Alerts and Git use the resolver at use. The store keeps ciphertext in memory and decrypts at use.

8. Backups (amends ADR-063 and API-007).

  • Never in a backup: the secrets table, its tombstones and the head. They are dropped like sessions and idempotency (backup.rs:302), and sqlite_copy vacuums. The node key is never included either.
  • With a passphrase of at least 12 characters, the archive gains data/secrets.enc:
    • ChaCha20-Poly1305 over the JSON list {name, kind, value, updated, updated_by};
    • the key from Argon2id v1.3, m = 19,456 KiB, t = 2, p = 1 (the same as password hashing), with a 16-byte salt and 32 bytes of output, parameters recorded;
    • a 12-byte random nonce;
    • associated data "wrendns-backup-secrets v1" ‖ backup_id.

One KDF runs at a time per process; a second request gets 429. Restore refuses m > 256 MiB or t > 10.

  • Manifest and version. The manifest gains secrets {included, count, omittedReason?, kdf, aead, nonce, backupId}. VERSION becomes 2 only when secrets.enc is present, so older builds refuse it; archives without secrets stay version 1.
  • Without a passphrase, the CLI, the API header and the UI all say "N stored secrets were left out". The backup also warns when the configuration files or managed rows hold inline credentials, which are copied as they are.
  • Restore (offline):
    • --secrets-passphrase-file F, a TTY prompt, or --skip-secrets. A version 2 archive with neither is refused before anything moves.
    • A wrong passphrase reports "wrong passphrase or damaged archive" and moves nothing.
    • The key is resolved from the same configuration (-c) and environment as the server. Restore refuses, rather than generating, when a configured source is unavailable, and prints the source and key_id it used.
    • Rows are re-stamped in the restoring node's current epoch, inside the staged state.db.
  • API.
    • POST /api/v1/backup (admin; not agents; HTTPS rule from section 4) takes {includeQlog?, passphrase?} and answers with X-Wrendns-Backup-Secrets: included|omitted; count=N.
    • With a passphrase it needs an interactive session signed in within the last 10 minutes; tokens get 403 reauth_required, with a hint to run wrendns backup create on the node.
    • It is audited as backup.create {secretsIncluded, count}, and with secrets included it raises the alert event secrets_exported.
    • It takes no Idempotency-Key, because it changes no state.
    • GET /api/v1/backup stays and omits secrets.

9. UI.

  • Settings → "Integrations & secrets":
    • stored secrets (name, used by, updated, by, readable per node, Replace, Clear);
    • credential fields set by file (path, readable on this node);
    • store state (key source, locked/unreadable/ephemeral);
    • orphaned rows.
  • SecretField.svelte:
    • a write-only type=password input, never pre-filled, with autocomplete="off", spellcheck="false", data-1p-ignore, data-lpignore and no show toggle;
    • states: Not set, Set (updated, by), Set by file, Inline in the file, Unreadable on <node>, and Can't be set over plain HTTP.
  • Saving is PUT /secrets/<auto-name>, then the entry with _ref. A failure in between leaves at most an unused secret, which the page lists.
  • Every "?" has a help topic.

10. What this amends.

  • ADR-045: the channel rule covers file secrets only, and its OIDC implementation note is corrected.
  • ADR-048 and OPS-005: secret writes are allowed under GitOps authority.
  • ADR-049: references by name.
  • ADR-063, API-007: section 8.
  • ADR-069: credential fields of alert destinations follow section 2 rule 1.
  • ADR-116 and CLU-013: secrets are not configuration versions; pins and rollouts don't gate them.
  • ADR-120: "key files at the same paths" or a stored secret. Stored-credential routers poll on the primary.
  • ADR-125: confirmed for stored-credential routers.
  • ADR-156: the credential table moves to wrendns-config, and *_ref fields are class name.
  • T9.6:
    • The criterion becomes "secret values pass only through /api/v1/secrets".
    • config:write:alerts no longer covers credential or destination fields of a destination that has a credential, so those plan_* alert changes get 403.
  • Also: the comment at config_api.rs:656-657; spec/08 §3.3, §6 and §8; spec/12 §4 and §6; spec/13 §3.

New direct dependencies. No new crates are added.

  • zeroize becomes a direct dependency of crates/wrendns. It is already in the lock through RustCrypto, and it is needed for SecretValue.
  • argon2 becomes direct there too, for backup.rs. It is already linked through wrendns-api.

Alternatives rejected

  • Reusing managed for values: every copy path would carry them.
  • A shared cluster key, privacy.key or the CA key: one node's compromise would expose everyone's, and decision 2 says per-node keys.
  • Values as content-addressed blobs: replicas write blobs to disk.
  • The secrets head in ClusterManifest: every secret write would become a configuration version, gated by pins and rollouts.
  • Deletion by absence: one primary that can't read its rows would wipe every replica.
  • A plain per-node counter as the version: it goes backwards after failover.
  • Router secrets only on the polling node: that breaks when the primary moves, and the owner chose replication.
  • Every full member polling every stored-credential router: ADR-125 rejected it.
  • Secrets on ephemeral pods: decision 1.
  • Upstream refs now: pods answer most queries and would lack the value.
  • *_secret suffixes, or *_file = "secret:<name>": awkward names, overloaded paths.
  • Values in entry bodies: that is the general write path again.
  • Plain HTTP allowed silently: the value would cross the network in clear.
  • env_clear() for plugins: it breaks plugins that need PATH or proxy variables. env_remove of the named variables plus admin-only exec:// covers the risk, since a same-user process could read secrets.key anyway.
  • Argon2 at m = 64 MiB inside the DNS process: it competes with NFR-001's working set.
  • The chacha20poly1305/aes-gcm crates: ring already provides the cipher. AES-256-GCM: slower on a Pi.
  • MCP write tools, or operator role for secret writes: both are exfiltration paths.
  • UI-made OIDC providers and sinks kept node-local: each node would need its own write route, against the single management plane.

Consequences

  • Who benefits. Home and Pi users can run routers, alerts, Git, sinks and OIDC from the UI. File and Kubernetes Secret setups behave as before and win.
  • Timing. A secret set on any node reaches every full member within one heartbeat plus one RPC. Resolver pods still need *_file mounts for sinks and OTLP.
  • Behavior changes (T23.2):
    • Operators and agents can no longer change *_file paths, credential-bearing destinations, or exec:///unix:// upstreams.
    • Existing API-set file paths outside secret_file_dirs stop being read.
    • Stored-credential routers poll on the primary only.
  • Mixed versions (CLU-010). As with quick rules, an N-1 replica refuses a configuration version that uses a new *_ref or tls_ca_pem field, and keeps its last good version until it is upgraded. An API write that adds one warns, naming the older members. Credential-affecting writes forwarded by N-1 replicas are refused.
  • Plain HTTP. Secret entry over plain HTTP from another host is refused unless [api] allow_secrets_over_http is set.
  • Helm.
    • The default key lives in the data directory.
    • secretsKey.existingSecret is recommended.
    • secretsKey.generate=true (Helm lookup) is documented as unsafe under helm template or Argo CD.
    • With persistence off, stored secrets are lost at every restart, and the health reason secrets_ephemeral says so.
  • Unchanged: the query path, and the crate list. Image growth is limited to 0.10 MiB for the milestone, recorded per task.
  • Old audit entries. Entries written before T23.1 may hold upstream headers and can't be rewritten (hash chain). The release note says so.

Owner decisions on the open questions (2026-11-16):

  1. The admin-only credential rules (T23.2) ship right away, with T23.1, not with the UI.
  2. Upstream credentials (headers, tls_client_key) stay file or inline only, redacted everywhere; no task sends secrets to resolver pods.
  3. OIDC providers and sinks made in the UI reach every full member as node-managed configuration; providers and sinks defined in files stay per node.
  4. Entering a secret over plain HTTP from another host is refused unless [api] allow_secrets_over_http = true.
  5. Agents get no write scope for router or [identify] fields for now (admin-only, as above). Revisit after T23.8.
  6. Audit entries written before T23.1 stay as they are (the hash chain forbids rewriting); the release note warns about them.

Implementation notes (T23.1, 2026-11-16; Proposed, for the owner):

  1. Sites with nothing to redact. apply_ack audits finding IDs and a count, never a configuration body, so it is unchanged. compare.rs (GET /cluster/compare) carries only numbers and node labels. The surfaces that do carry shared configuration are the pin and version diffs (rollout/surface.rs, also the 409 cluster_pinned body): both sides are redacted before the diff. GET /upstreams' endpoint goes through the URL redaction too.
  2. Checks and markers. "Checks never resolve markers" is implemented as a refusal: POST /checks/upstream with <redacted> at a credential path is 422 credential_reentry_required, so a check never runs with a literal marker as a header.
  3. Destination comparison. Absent, null, "" and [] count as the same value; URLs are compared with their passwords replaced by the marker, so a changed user name or host is a changed destination. A URL's user information runs to the last @ before any ? or # (conservative: a stray / in a password is still redacted).
  4. The node key in T23.1. wrendns::secrets loads the key at start on full members, in a blocking task (DNS never waits for it). With no secrets table yet, the data-directory key is made whenever it is missing; T23.3 adds the empty-table condition and the locked state. A key file with any "other" permission bit or group write warns; the owner check needs the process's uid (no libc in the binary) and is left to T23.3. zeroize isn't used yet (it becomes direct in T23.3).
  5. Idempotency without a key. With the key unavailable, a write carrying Idempotency-Key and a credential is 503 secrets_locked (the code is added now); one without a credential keeps a plain BLAKE3 of the request, which holds nothing secret.
  6. Delivery errors. Besides percent-encoding the Gotify token, an HTTP error that quotes the request has the token replaced by the marker.
  7. Release notes. deploy/release/notes/v0.8.0.md is started as a draft with the upgrade items (older audit entries, the purge, the new key), and preflight.sh refuses notes whose first line begins _Draft.

Implementation notes (T23.1 review fixes, 2026-11-16; Proposed, for the owner):

  1. Every URL field. §4's table names three URL fields; the support package classes eleven more url (upstream[].relay, list[].url, router[].url, cluster.git.repo, cluster.join_url, telemetry.otlp.endpoint, telemetry.ship.to, telemetry.sink[].url, updates.index_url, auth.oidc.public_url, auth.oidc.provider[].issuer). All are in PATHS as URL passwords, and the completeness test now also fails for a url-class field missing from it. list is an entry kind for redaction and the marker rule, and POST /checks/list refuses markers like the upstream check. A URL that sends the marker keeps its password only while that URL itself is unchanged (it is replaced whole by the stored one), so a field that isn't a destination (relay) can't carry a stored password to a new host. The Cluster page's repo (and a Git error quoting it, and the config.git audit entry), GET /lists' source and fetch error (the walk found it once a list URL was planted), and a router's errors are redacted too.
  2. Markers and an N−1 primary. A replica forwards a body that sends <redacted> back only to a primary whose advertised version is at least 0.8.0 (forward::MARKERS_SINCE); otherwise 409 upgrade_required (a new code, which T23.2 reuses for role-less forwards). A primary whose version is unknown counts as older. Resolving markers on the replica instead was rejected: the replica's copy can lag the primary's and would restore an outdated value.
  3. Plans. Plan.body is shown redacted (GET /plans, list_plans, approve and reject); the body apply_plan replays is kept apart (write_body, never serialized). wrendns-api now depends on wrendns-config for the table (a workspace crate, no new dependency).
  4. Pin diffs. Both sides are redacted before the diff; a credential that changed while reading the same redacted (a header's value, only a URL's password) is added as a replace with the marker as its value, so a pin that holds back only a credential change still shows one.
  5. Smaller points. keepInGit text from an older primary that doesn't parse is replaced by its leading comments and a note, never passed through. A body whose credentials are all markers holds no credential (no 503 secrets_locked for it). A failed key load is retried after 30 s instead of kept until restart. secrets.key is written to secrets.key.tmp (O_EXCL, 0600, fsync), hard-linked into place (no replace), and the directory synced. The Gotify token is scrubbed from errors in its percent-encoded form too. Plugins inherit no WRENDNS_* variable but WRENDNS_PLUGIN_SOCKET and WRENDNS_UPSTREAM (environment configuration can carry credentials); the self-update keeps the named list, since the restarted server needs its own settings.

Implementation notes (T23.2, 2026-11-16; Proposed, for the owner):

  1. Credential files. alerts.destination[].token_file/password_file and upstream[].tls_client_key (§1 classes the client key a secret) are the credential files: changing one is admin-only and an API-set one must be under [node] secret_file_dirs. tls_ca, tls_client_cert and list[].path get the denied places only. credentials::API_PATHS lists them, and api_014_api_paths_cover_path_fields holds it to the support package's path-like fields of those kinds.
  2. "Stops being read". Done where the API's entries are merged (managed::merge, on the primary or a standalone node): a refused path is replaced by /proc/wrendns-refused/<field>, where nothing can be read, so the list or alert fails as with a missing file (an upstream's is cleared instead: note 22). It is judged by that node's settings, and replicas receive the result with the shared configuration. A path an override keeps from the files' entry of the same name is the files' (an operator editing a file-defined email destination doesn't break its password_file). At write, only paths that change are checked; stored ones are judged at use. credential_issues is shown now as ConfigEntry.credentialIssues (and a warning at each reload); the heartbeat field (T23.5) and GET /secrets' credentials (T23.4) reuse credential_rules::issues.
  3. Redirect audit and alert. Until *_ref exists (T23.3), credential.redirect covers an admin's destination change of any entry that holds a credential (a header or argument, a URL password, a credential file), not only one with a _ref; "a _ref pointed at a secret of another kind" comes with T23.3. The record is made where the change is applied (so a forwarded one gets it on the primary), with the user as a system actor, beside the usual <kind>.put; the dry run warns. AlertWhen::CredentialRedirected (credential_redirected) reads the last hour of those records, once each (a one-off condition). As with any new condition, an N−1 replica refuses a configuration version whose rule uses it.
  4. Programs. Besides creating or switching to exec:///unix://, changing an existing plugin's url or args is admin-only (they are what runs); its weight or timeout stays an operator's. A forwarded domain's servers become upstreams, so an exec:///unix:// server there is admin-only too (it was a way around the rule). POST /checks/upstream with a tls_client_key is admin-only as well, and a draft's paths are confined (the check reads them).
  5. Role-less forwards. "Credential-affecting" is: any admin-only change, or an entry that holds or would hold a credential. Other writes from an N−1 replica still apply, so a rolling upgrade keeps working for them. A new replica forwarding to an N−1 primary isn't refused for these rules (the older primary never checked them; upgrading the primary first is already the advice).
  6. Who counts as admin. The admin role and no agent token: an agent token is never admin here, even with cluster:admin and an admin owner (§3's threat model). The marker rule's 422 comes before the role rule's 403. Problem codes: path_not_allowed (422) is new, and upgrade_required's title becomes "Upgrade needed" since it now also names an old replica.
  7. Paths. Absolute only, no .., compared after following every symbolic link, a dangling one included (followed by hand, so a link can't wait for its target). The denied files are [node] secrets_key_file and secrets_previous_key_file, [cluster] bootstrap_secret_file, and listen[].tls.key and [api] tls.key; the data directory covers secrets.key, the cluster's certificates and state.db. [node] secret_file_dirs is read from this node's files and environment (node never leaves a node). The check is at write and at each reload, on the resolved path, but the configured string is read: a link swapped between reloads is followed (note 26).
  8. UI. ConfigEditor fields take admin (always, or decided from the entry as read); the Alerts page shows the token and password files to operators read-only, and the address and CA once the destination holds a credential. Rows with a refused path show "<field> not read". The Upstreams page isn't marked yet (the API refuses the same changes with a 403 that names the field).

Implementation notes (T23.2 review fixes, 2026-11-16; Proposed, for the owner):

  1. Destination fields. §4's list (url, proxy, host, tls_server_name, tls_ca, bootstrap) gains tls_insecure_skip_verify and spki_pins (turning certificate checks off, or swapping the pins, sends the credential to whoever is on the path, which is worse than a new CA) and an alert destination's type (it changes how the credential is sent). They count for the admin-only rule and for the marker rule alike; absent and false are the same value.
  2. Refused upstream paths (CLU-004). Note 14's /proc/wrendns-refused/<field> is kept for alert destinations and lists, which read their files when used. An upstream reads its TLS files when the router is built, and one it can't read fails the whole configuration (the node would start answering nothing, on every replica that restarts). So a refused tls_ca, tls_client_cert or tls_client_key of an upstream is cleared instead: the upstream runs on the system's roots, without a client certificate (its certificate and key are cleared together, since one without the other doesn't validate). No refused file is read and no credential is sent anywhere new; an mTLS server refuses the connection, and the group fails over. Dropping the upstream was rejected: it would empty groups (invalid) and drop routes.
  3. Paths that aren't a credential's. tls_ca, tls_client_cert and list[].path may not name a credential file this node's own configuration uses (an upstream's client key, an alert destination's, router's, sink's or OIDC provider's file, the Git credentials and webhook secret), and a list's path may not be under secret_file_dirs (a secret that parses as a name becomes a rule GET /explain confirms, and a line that doesn't is quoted in the list's error). A CA or client certificate may still sit in a secrets directory, beside its key. /var/run/secrets/kubernetes.io (and /run/secrets/kubernetes.io) is denied for every API path, admins included: the default secret_file_dirs covers it, and the pod's service-account token is never a file an entry should read. The default directories are unchanged; denying the subtree is the conservative reading of the ADR's default.
  4. A promoted primary. A primary promoted from replica builds on the last cluster version (ADR-051), so "the files' entry of that name" is judged against the node's own files (managed::merge_on), not that version: a path an older primary published as the API's is judged, not taken for the files'. Writes already compared against the node's own files (Sources::file_config).
  5. Deviation: replicas don't judge again (for the owner to accept). §4 says paths are checked at write and at use. Here the node that merges the API's entries (the primary, or a standalone node) judges them with its own rules, and a replica uses what it receives: the shared configuration doesn't say which entries the API made, so a replica can't tell an API path from one in the primary's files (which are never confined), and judging every path there would break file-defined ones. A path that is fine on the primary can thus be in a replica's own data directory or key file when the two differ. Closing it needs the version to carry which entries are the API's; proposed with T23.5 (heartbeats carry credential_issues).
  6. Smaller points. The credential_redirected alert names only the new address's scheme and host (a URL's path can hold a secret, and the alert goes to every destination of the rule); the audit record keeps the rest. The alert reads the last hour of the applying node's audit log, so a change applied just before a failover isn't alerted by the new primary (documented). A path is resolved and checked, but the configured string is what's read later, so a symbolic link swapped between reloads is followed; only someone who can write a secrets or listed directory can do that, which is outside §3's threat model (note 19).
  7. T23.2 is ticked with AC7 and AC8 open, as T23.1 was: the Playwright test is written but hasn't run (no browser in the dev container), and no image was built to record the size delta. AGENTS.md rule 10 says done means the criteria pass in CI; the owner accepts the tick, or it is unticked until CI has run both.

Implementation notes (T23.3, 2026-11-16; Proposed, for the owner):

  1. One store per process. wrendns::secrets::SecretStore is made at start without I/O, loaded in a blocking task, and retried every 30 s while locked (a key mounted later unlocks it without a restart). It also owns T23.1's key slot, so the idempotency hashes and the store use the same key, and "made only for an empty table" covers both. A configured key that can't be read leaves no key for the idempotency hashes either (503 as before).
  2. The replica's self-heal runs from that upkeep when the cluster says this node is a replica and the store is locked, only for the data-directory key (an unreadable WRENDNS_SECRETS_KEY or secrets_key_file is whoever configured it to fix, and generating beside it would hide the mistake) and only when every row is origin='cluster'. It drops the rows and starts over with a working key; fetching them again is T23.5's.
  3. secrets_ephemeral needs to be told. A node can't tell an emptyDir from a volume, so the chart sets WRENDNS_DATA_EPHEMERAL=1 (a reserved variable, not a configuration key) on the controller when persistence.enabled is false; any other deployment may set it. The reason shows only while secrets are stored, so a fresh install without persistence isn't degraded.
  4. The read sites. Credential::resolve (inline first, then the file, then the reference: the files win even if a merge somehow kept two) replaces the routers' reads (UniFi, OPNsense, Home Assistant), alert tokens and email passwords, sink tokens, the Git credentials and webhook secret, and the OIDC client secret; OTLP header_refs are resolved per request. The cluster bootstrap secret (wrendns-cluster/src/net.rs) keeps its plain file read: §1 makes it status only, and it lives in another crate.
  5. "The files win" at write and at merge. §2's rule 1 is implemented for alert destinations, the only API kind with a stored field so far: an override that leaves a file-set credential out has it carried over; one that sets, replaces or removes it is 409 set_by_file; a DELETE that would hide a file-defined destination with a credential is refused too (the ADR's "a hidden entry"), a behavior change named in the release note. At merge, a file-set credential replaces whatever an override stored for it (an override saved before the files set it), so the merged entry keeps one source per field. The router, OIDC provider and sink kinds reuse secret_refs::carry_file_credentials when they arrive (T23.7, T23.10, T23.11). The file layer judged is this node's own files, as T23.2's paths are (note 24).
  6. References at write. A _ref naming a secret this node doesn't store is 422 secret_missing (new code, with set_by_file). A _ref changed to a secret that an entry of another kind references in the effective configuration is audited as credential.redirect with secretUsedBy (note 15's deferred case); the alert names the field and the secret's name.
  7. Rotation. wrendns secrets rotate-key refuses while the data directory's lock is held (as backup restore does), re-encrypts the rows readable under the old key (others are left as they were and counted), and recover_rotation decides a leftover secrets.key.new by whether any row is under its key_id. Re-encryption keeps each row's stamp and takes a new nonce.
  8. Recovery gap (a decision for the owner). A store locked because none of its rows decrypt, and holding rows made on this node, can't be cleared: §3 refuses every secret write while locked (deletes included), and no command discards unreadable rows. The conservative reading is kept (nothing is ever discarded on its own); docs/secrets.md says to keep a copy of the key. Proposed: an offline wrendns secrets forget --unreadable, or letting T23.4's DELETE /secrets/{name} remove an unreadable row while locked.
  9. Helm's generated key is ttsk1: + randAlphaNum 42 + A: the last character keeps the trailing bits zero, as the decoder requires, for about 250 bits of entropy. The Secret keeps helm.sh/resource-policy: keep, and its file is mounted 0440 (group read through fsGroup, which the key check doesn't warn about).
  10. What isn't wiped. SecretValue, the node keys and their subkeys are wiped on drop; copies handed to code that wants a String (the OIDC provider settings, the SMTP login) aren't, beyond §2's stated limit; the UniFi login body and the OPNsense key pair are. The metric is wrendns_secrets{state="readable|unreadable|corrupt"}; the store's own state is in health, not a gauge.
  11. T23.3 is ticked with AC14–AC16 open, as T23.1 and T23.2 were: the Helm template test is written and in CI but wasn't run (no helm in the dev container), cargo deny wasn't run (no cargo-deny; Cargo.lock gains no package), and no image was built for the size delta. argon2 is a direct dependency as the task lists, but nothing in the binary crate uses it until T23.9.

Review fixes (T23.3, 2026-11-16; Proposed, for the owner):

  1. Associated data, status, and the key's edges. (a) §3's associated data had no boundary between kind and name: the row (text, x) gave the same bytes as (tex, tx), so someone who can write state.db without the key could move a ciphertext to another name and have it decrypt. kind and name are now each preceded by their be16 length, and open treats a kind other than text or pem as corrupt. No value was stored under the old form (the write API is T23.4), so nothing needs migrating. (b) wrendns secrets status writes nothing: it doesn't finish or drop a leftover secrets.key.new (a rotate-key running beside it would otherwise lose its new key, and every secret with it), doesn't re-encrypt, and creates no database; it reports the leftover file and counts rows under the previous key as readable. (c) rotate-key also refuses when the data directory's lock can't be taken at all (whether the server runs is then unknown). (d) A secrets_previous_key_file that no longer exists is a warning, not a locked store: the docs say to remove the previous key after rotating, and §3 locks only for sources 1 and 2. A previous key that exists but can't be read or parsed still locks (conservative). (e) The owner check (note 4's deferral): the process's uid is the owner of /proc/self (no libc); a key owned by another user warns, root excepted (it can read the file anyway, and kubelet's Secret mounts are root's), a slightly less strict reading of §3. (f) The replica's self-heal clears rows only when a new key fixes the lock (secrets.key missing, or none of the rows decrypts), not for a key file or database that can't be read.
  2. Locks and blocking. SecretStore::configure took the settings' lock and then the store's, while a load holds the store's and then reads the settings: a reload that changed the key settings during a load hung both, and with them health, metrics and the API (CLU-004). configure now takes only the settings' lock and marks the store stale; the next use loads again. A reload's missing-reference warning runs in a blocking task. Left as it is: an API request that finds the store due for a retry (the secret_missing check, idempotency) loads it on that request's thread, at most once every 30 s while locked; health and metrics never load.
  3. Smaller points. wal_checkpoint(TRUNCATE) reports whether it finished; when another connection kept it busy past the 5 s timeout, the server logs a warning and rotate-key prints a note (ciphertext may stay in state.db-wal until a later checkpoint). The Idempotency-Key 503 applies when the key itself can't be read; a key that opens none of the rows still keys the retry records, so a store locked that way doesn't refuse them (the docs say so; §4 is read that way). <redacted> is refused at load at every credential path (credentials::PATHS), URL passwords included, the error naming the field. A body that sends null or "" for a credential key the files set is 409 set_by_file, not carried over. The backup still drops the secrets_stamp counter with the table (§8 keeps the store out of backups): a restored node starts its stamps again at (epoch, 1), which relies on T23.5's epochs and T23.9's re-stamping. The UniFi key and session cookie are wiped after a poll. backup restore still goes on when the data directory's lock can't be taken (outside T23.3; worth the same refusal).

Implementation notes (T23.4, 2026-11-16; Proposed, for the owner):

  1. Status codes. A value, kind or name the rules refuse, and a 129th secret, are 400 invalid_parameter (T23.3's StoreError::problem), not 422: nothing about the configuration is invalid. Three codes are new: insecure_transport (403), agent_not_allowed (403) and secret_in_use (409). A primary without its lease and an emergency primary answer 409 as §4 says (entry writes answer 503 for a lapsed lease); dry runs are held to the same, and to the locked store (503).
  2. set_by_file on a secret write. §4 lists it without saying when. Read conservatively: a PUT of the name the UI gives a credential (<kind>.<entry>.<field>, lowercased, header: as header.) is refused when this node's files set that credential inline or by file, since the secret would never be used. Any other name is accepted. The check reads the files of the node that applies the write (the primary): a replica's own file-set credentials (auth.oidc, [cluster.git] are node-local) aren't seen when it forwards (review of T23.4; proposed: the forwarding replica checks its own files first, or T23.5's heartbeats carry them).
  3. The webhook rule (16 characters) applies when a webhook_secret_ref in the configuration names the secret at write time; a reference made later to a shorter secret isn't checked (a load warning could; proposed with T23.12). Like note 43 it sees the primary's references only: a replica's node-local webhook_secret_ref isn't consulted for a PUT (peers' references are fetched for deletes only); the same proposal covers it.
  4. ?force and references. force only goes past members whose references can't be read (offline, older, or not answering within 2 s); a known reference refuses even with it. A shared-configuration reference that a lagging member still holds counts too (conservative).
  5. References across nodes are asked at delete time. Until heartbeats carry secret_refs (T23.5), the primary asks each full member of its registry (!ephemeral && !witness) over api.read (Read::SecretRefs); a node-local reference names its node. T23.5 switches this to the heartbeats' union.
  6. Transport. "From loopback" is the connection's peer being a loopback address (::ffff:127.0.0.1 from a [::] listener too) with no X-Forwarded-For/Forwarded/X-Real-IP header (a request a local proxy forwarded from afar isn't). X-Forwarded-Proto: https counts here only from a peer listed in [api] trusted_proxies; unlike is_https, loopback isn't implied, since a plain-HTTP proxy or relay on the same host would pass a remote client's header through (review of T23.4). A TLS proxy on the same host is listed as 127.0.0.1/32. Reads aren't held to it (they carry no value). [api] allow_secrets_over_http is read from the node's files at each request (node-local, no restart). In-process MCP calls have no peer address, so they'd need HTTPS; there is no MCP write tool anyway.
  7. The head as an ETag is <epoch>.<seq>.<first 16 hex digits of the digest>, sent on reads and write answers; If-Match takes it (412 version_conflict). The idempotency record of a PUT is PUT /secrets/<name> kind=<kind> and the keyed BLAKE3 of the trimmed value (the kind included, so another kind with the same key is 409); an empty Idempotency-Key is no key; a DELETE's is its request line (?force included), which holds nothing secret.
  8. Replicas and GET. A replica shows the primary's list and head, with its own store, credential fields, node-local references and its own row per secret; without the primary (or with one too old to answer) its own view with stale: true. nodes lists only the nodes that answered until T23.5's heartbeats; replicas hold no rows yet, so a stored secret is the primary's only and integrations elsewhere report it not set.
  9. Forwarding. The value crosses the cluster channel in the JSON body of secret.put (mTLS); the replica serialises it into one buffer sized up front (so it isn't reallocated) and moves that buffer into the call; from there the channel's buffers, like the HTTP and JSON layers' copies on the way in and ctl's request body, aren't wiped (§2's stated limit; only buffers WrenDNS keeps are). The primary takes it only from a full member of its registry, checks every rule again, reads its epoch under the role-change lock (Cluster::primary_epoch, new in wrendns-cluster: Primary with its lease) and stamps and stores the row after releasing it, so no SQLite write or fsync runs under the lock role changes take (a step-down in between leaves a row of the old epoch, which the new primary's epoch outranks: §2's orphans, the argument publish_as makes), and audits <user> via <node>. An older primary answers "unknown call": 409 upgrade_required naming its version.
  10. Agents. agent_not_allowed covers PUT/DELETE/POST on /api/v1/secrets*, POST /api/v1/backup and POST /api/v1/checks/router* before any scope is looked at (the last two don't exist yet; the rule is in place for T23.7 and T23.9). Reading needs config:read; operators read too, viewers don't.
  11. Mixed versions (T23.3's deferral): a write that adds a *_ref the entry didn't have warns, naming the members older than 0.8.0. Only alert destinations take references through the API so far.
  12. Not done here. Note 35's recovery gap stays: a locked store refuses DELETE too. The image size delta (AC17) isn't measured (no image build here; one direct zeroize edge in wrendns-api, no new crate in Cargo.lock).

Merge review fixes (M23, 2026-11-16; Proposed, for the owner):

  1. Amendment to §4: URL user names and secret query values (Proposed). §4 replaces a URL's password with the marker and keeps the rest of the URL. Read literally, that leaks a token used as the user name (https://ghp_…@github.com/org/repo.git) and a list URL's token in its query (https://lists.example/ads.txt?token=…), which reach GET /lists, MCP reads, ctl, replica reads, Git audit rows and config entries. Proposed: a URL without a password has its user name replaced by the marker, and the values of query parameters named token, key, apikey, api_key, access_token, auth, sig, signature or password (names compared without case) are replaced too. A URL with a password keeps its user name as before. Round trips stay as §4 has them: a URL that sends the marker keeps its stored value while its destination is unchanged. The support package's Url class already drops the path and query.
  2. Idempotency record of POST /lists/refresh. The record keeps the keyed fingerprint (idempotency_request) like the configuration writes, not the request text (§4).
  3. Primary's GET /lists passes through the same redaction as a replica's read (redact::lists), so a URL written or normalised differently from the configured one is covered too.
  4. List fetches never send user information. A list URL with user:pass@ is refused as a fatal fetch error (the URL is not quoted); Host carries the host and port only. Basic auth isn't built, as no base64 dependency is wanted for it.
  5. Open serialization (OPS-014). State::open runs its setup under a process-wide lock and sets the busy timeout first; journal_mode=WAL is retried on busy with a bounded backoff (50 × 20 ms), since SQLite doesn't always run the busy handler for it.

Requirements AGT-001 AGT-002 AGT-003 AGT-005 AGT-007 API-007 CLU-004 CLU-010 CLU-013 CLU-015 NFR-001 OBS-015 OPS-005 OPS-011 OPS-014

Builds on ADR-040 ADR-045 ADR-048 ADR-049 ADR-051 ADR-056 ADR-058 ADR-063 ADR-069 ADR-116 ADR-120 ADR-125 ADR-143 ADR-149 ADR-155 ADR-156

Referenced by ADR-1003 ADR-1005 ADR-1006 ADR-1007 ADR-1025 ADR-1027 ADR-1045 ADR-1048 ADR-1051 ADR-907 ADR-908 ADR-914 ADR-917 ADR-918 ADR-919 ADR-921 ADR-926 ADR-956 ADR-961 ADR-965 ADR-966 ADR-967 ADR-968 ADR-984 ADR-985 ADR-993 ADR-998 ADR-999

ADR-904 Pi-hole's special names: iCloud Private Relay blocked by default, resolver.arpa kept local with DDR, domain-needed opt-inAccepted 2026-11-16DNSDNS-019, spec/03 §3 step 4 (DDR promised at P1).

Context

DNS-019, spec/03 §3 step 4 (DDR promised at P1). Pi-hole users rely on three behaviours we lacked: Pi-hole answers iCloud Private Relay's names NXDOMAIN by default (Apple's documented opt-out for networks: devices then use the network's DNS, so filtering applies); it answers resolver.arpa locally (designatedResolver); and domain-needed keeps bare names off upstreams. RFC 9462 §6.5 says forwarders shouldn't forward resolver.arpa: an upstream's DDR answer names a resolver whose certificate can't cover our address.

Decision

  • iCloud Private Relay: [special] block_icloud_private_relay, default true (a behaviour change, for Pi-hole parity): exactly mask.icloud.com and mask-h2.icloud.com → NXDOMAIN (with SOA), all types, before local data and filtering; status special. A bool, like block_firefox_canary.
  • resolver.arpa: always local, no switch. With [special] ddr_name (the host name in the listeners' certificate), _dns.resolver.arpa SVCB answers one record (RFC 9460/9461) per DoT, DoH, DoH3 and DoQ listener on this node, in listener order (priority 1, 2, …), TTL 300, AA: alpn (dot, h2, h3, doq), the listener's port, ipv4hint/ipv6hint only for a listener bound to a specific address, and dohpath = the listener path + {?dns} (default /dns-query{?dns}). Left out: listeners bound to loopback (no other device can reach them) and listeners with proxy_protocol = true (a direct connection fails without the PROXY v2 header); advertising nothing leaves a device on plain DNS, while advertising an unreachable resolver can leave it with none. The records are built with the policy, off the query path. Anything else in resolver.arpa → NOERROR, no data, SOA. [special] is shared but listeners are node-local, so each node advertises its own. Clients check that the certificate covers the IP they use (an IP SAN); documented, not checked.
  • domain-needed: [special] single_label_nxdomain, default false. One-label names asked for A, AAAA, or HTTPS (dnsmasq's A/AAAA, plus HTTPS because browsers send it for the same bare names) → NXDOMAIN at the routing step: after local records, zones, device names, quick rules, the filter and rewrites, unless a [[route]] matches (the same test as RFC 6303 private PTRs). Other types (DS, NS, SOA, DNSKEY of a TLD, which validators ask) still go upstream.
  • Classifier: one walk over the labels picks the top-level label; each rule compares only under its own TLD. No allocation (02 §3).
  • Importer: v6 dns.domainNeeded, dns.specialDomains.iCloudPrivateRelay, mozillaCanary; v5 DNS_FQDN_REQUIRED, BLOCK_ICLOUD_PR, MOZILLA_CANARY (the last two on unless an explicit false, any case, trimmed). Written only where Pi-hole differs from our defaults. designatedResolver = false has no equivalent (never forwarded, per RFC 9462); bogusPriv stays an import note.

Alternatives rejected

a string enum icloud_private_relay = "block"|"allow"; NXDOMAIN for resolver.arpa (RFC 9462 and Pi-hole use NODATA); the DDR target from the certificate's SAN (needs X.509 parsing in the policy crate); domain-needed for every type (breaks DS/NS of TLDs under DNSSEC); forwarding resolver.arpa when no ddr_name is set.

Consequences

Apple devices with Private Relay on show "Private Relay is turned off for this network" until an admin flips the switch. Windows 11, iOS 16+ and macOS 13+ discover encrypted DNS by themselves once ddr_name and an IP-SAN certificate are in place. Behind port mappings the advertised ports are the listeners' own (a per-node ddr_port is a possible follow-up), and a load balancer that adds PROXY headers gets no DDR (a possible opt-in later).

Requirements DNS-019

Referenced by ADR-914

ADR-905 Update lists now: one queued round per request, on the node that downloads listsAccepted 2026-11-16AGTCLUOBSspec/07 §2 promises POST /lists/refresh, but only SIGUSR1 refreshed lists, and on a cluster replica nothing could (replicas don't download lists, CLU-003) while its Lists page showed every list as "pending".

Context

spec/07 §2 promises POST /lists/refresh, but only SIGUSR1 refreshed lists, and on a cluster replica nothing could (replicas don't download lists, CLU-003) while its Lists page showed every list as "pending". Pi-hole users expect "Update Gravity".

Decision

  • POST /api/v1/lists/refresh (body {}, null, or {"names": [...]}; ?dryRun=true; Idempotency-Key) queues the enabled lists named, or every enabled list, on the node that downloads lists, and answers 202 with queued, skipped (disabled), alreadyRefreshing, node and note. An unknown name is 404 with the real names in the hint. A node that doesn't download lists (role resolver, or no fetcher) answers 409 lists_not_here. A dry run queues nothing and isn't audited (AGT-002); a key replays the first answer for 24 h and a reused key with another body is 409 (AGT-003). Audited as lists.refresh.
  • Rounds: requests made before a round starts merge into it; a request made while lists download starts exactly one more round after it. Progress is per list, not a job: refreshing (queued or downloading) and lastSuccessUnixSeconds on GET /lists. No new change marker: lists.refreshed already marks a refresh that changed the snapshot (OBS-033).
  • Scope: people need the operator role; agents reuse config:write:lists plus the reason header (saving a list already makes it download, so this grants nothing new). Group-restricted agent tokens are refused.
  • Cluster: the primary downloads (CLU-003). A replica forwards Write::ListsRefresh (by, names, dry_run, reason), and the primary audits it with actor "<user> via <entry site>", kind cluster, and the user's reason. An N−1 primary refuses the unknown write and the replica answers 503. Without a reachable primary, a node with its own fetcher uses it, otherwise 503; an emergency primary that followed a primary has no fetcher and answers 503 (list refresh paused, spec/12 §5). A replica's GET /lists shows the primary's lists and download state (Read::Lists) with every node's hits added up (Read::ListHits, OBS-009); when the primary doesn't answer, missingNodes names it and the replica shows its own view. ctl lists refresh --wait stops only when the primary is among missingNodes: a replica that misses only its hits doesn't stop it. The primary is named as missingNodes names it (its pod, else its site, else its node ID; ctl also matches its site and node ID, so an empty site is never a blank name). missingNodes also names nodes whose hits are missing (OBS-009). In a mixed-version window an N−1 primary that answers Read::Lists but not Read::ListHits is in missingNodes too, so it stops --wait. This is deliberate: missingNodes doesn't say which read was missed, and the primary's own hits are missing, so the conservative stop is kept (the download state there was read, which is why the Lists page words its notice as "not confirmed from the primary" rather than "this node's own").
  • Surfaces: the Lists page Update now (operators; progress, failures named, "last confirmed current" from the oldest enabled list); wrendns ctl lists refresh [names] [--dry-run] [--wait] [--reason], where --wait exits non-zero after 5 minutes or when the primary is unread; MCP refresh_lists, an immediate audited op with no plan (spec/13 §3.2), like flush_cache: it changes no configuration and costs one conditional request per unchanged list.

Consequences

SIGUSR1 still refreshes only the node that gets it. The fetcher's new lock is taken only when a download starts or ends, on a refresh request, and on a lists read; the query path is unchanged.

Requirements AGT-002 AGT-003 CLU-003 OBS-009 OBS-033

Referenced by ADR-937

ADR-906 Fork ADR numbers: fork-only ADRs take the next free number from 901 upAccepted 2026-11-16This fork (nbacheller/wrendns) and upstream (paimonsoror/telltaledns) both record decisions as ADRs.

Context

This fork (nbacheller/wrendns) and upstream (paimonsoror/telltaledns) both record decisions as ADRs. Upstream's numbering ended at ADR-164, so the fork's first five decisions after it (numbers 165 to 169) sat where upstream's next decisions would go, and one number could mean two decisions once a sync brought them together.

Decision

  • Fork-only ADRs take the next free number at or above 901, in order, and a number is never reused.
  • Upstream's ADR numbers are kept as they are; the fork does not renumber them.
  • On each upstream sync, check upstream's new ADR and requirement IDs against this file. If one of them lands on a fork ADR number, renumber the fork ADR (901 and up), never upstream's.

Consequences

On 2026-11-16 the fork's numbers 165 to 169 became 901 to 905, and every reference in code, spec, docs, site, UI, and bench was updated to match. Upstream's numbers stay below 901, so the two ranges do not meet.

Builds on ADR-164

Referenced by ADR-907

ADR-907 Network inventory scope: SNMP, gateway reads and imported scans; no built-in probingAccepted 2026-11-16CLUOn 2026-11-16 the owner asked what WrenDNS can learn about devices that never use DNS or DHCP.

Context

On 2026-11-16 the owner asked what WrenDNS can learn about devices that never use DNS or DHCP. Some sources already exist:

  • the routers' leases and networks (ADR-080, ADR-902);
  • Home Assistant names by MAC (ADR-902);
  • passive mDNS (ADR-081);
  • the kernel neighbour table. Today it is used only for MAC client matching (wrendns_net::neighbors()).

These are missing:

  • the gateway's ARP table across VLANs;
  • which switch port each MAC is on;
  • the identity of printers and network gear;
  • devices with static addresses that UniFi doesn't list.

Active probing is out of scope by owner decision (2026-11-16). That covers ICMP sweeps, TCP connect probes and ARP/mDNS solicitation. An operator's own scanner supplies that data, and WrenDNS imports its output.

This ADR keeps the read-only router posture of ADR-080 and ADR-902. ADR-091 (no DHCP server) is a separate decision and is not affected. ADR-081 is not affected either: mDNS stays passive. M22 ("Network inventory and home integrations") was the first inventory milestone, and M25 builds on it.

Decision

  • What M25 adds. Four inputs, all read-only:
    1. An SNMP poller (ADR-908) of infrastructure listed in the configuration. It reads:
      • gateway and router ARP tables;
      • IF-MIB;
      • the switches' BRIDGE/Q-BRIDGE forwarding tables per VLAN;
      • LLDP neighbours.

It also reads the identity of hosts already in the inventory (sysName, sysDescr, sysObjectID, Printer MIB), using per-subnet credentials. The public community is never tried unless the owner opts in for that subnet (ADR-909).

  1. More read-only UniFi and Home Assistant API reads (ADR-912).
  2. Uploaded results of a scan the owner runs: nmap XML, or a simple ip,mac,hostname CSV (ADR-913).
  3. A merged inventory keyed by MAC across all sources (ADR-910).
  • What WrenDNS never does. It never generates discovery traffic of its own:
    • no ICMP;
    • no TCP connect probes;
    • no ARP, NDP or mDNS solicitation;
    • no SSDP, NBNS or WS-Discovery;
    • no scheduling or launching of scans.

The code has no target planner and no range iterator.

  • Where SNMP goes. SNMP requests go to only two kinds of address:
    • each [[discovery.snmp_agent]].address;
    • addresses that have a current binding from class 1–3 and lie inside a configured [[discovery.subnet]] CIDR. Class 1–3 means router leases or UniFi current clients, the filtered local neighbour table, or SNMP ARP from a listed agent (ADR-910).

Entries known only from imports, from the IP-only class or from UniFi stat/alluser history are never SNMP destinations. An address range is never walked. A subnet CIDR is a filter on inventory addresses, never a list of targets.

  • Destinations. Every SNMP destination is an IPv4 literal inside RFC 1918. Host names are refused, so there is no resolution and no rebinding. Always refused:
    • loopback, 0.0.0.0/8 and 169.254.0.0/16;
    • multicast, limited broadcast and subnet broadcast;
    • 100.64.0.0/10 (RFC 6598, which Tailscale uses);
    • every IPv6 address (M25 is IPv4 only, like the leases);
    • the host's own addresses;
    • anything outside RFC 1918.
  • Placement. [discovery] is a shared section with one designated node:
    • node = "<node-id>". If unset, the current primary, or the standalone node.
    • Never ephemeral resolver pods or witnesses.
    • Every other node reads the inventory through a federated Read::Discovery (ADR-910).
  • Isolation (CLU-004).
    • Two worker processes re-executed from the running binary (ADR-908, ADR-913):
      • wrendns discovery-worker handles SNMP I/O and the BER/USM codec;
      • wrendns discovery-worker --import is a short-lived, credential-free process for import parsing.
    • A worker panic, hang, allocation failure or OOM cannot abort the DNS process, which builds with panic = "abort".
    • The merge runs in the main process on one dedicated OS thread named wrendns-inventory. It calls wrendns_net::background_thread() and runs its own new_current_thread() runtime, like kubernetes.rs. The extra UniFi and Home Assistant reads also run there (ADR-912).
    • Nothing in discovery is tokio::spawned on the main runtime.
    • Results leave the thread only through ArcSwap stores.
    • The thread and the workers are not created while enabled = false, or on a node that isn't the designated one. Reload starts or stops them.
  • What remains in the main process. The merge thread and the worker frame decoder still run in the main process, so a panic there aborts DNS. The only mitigations are:
    • the ADR-908 module lints (indexing_slicing, arithmetic_side_effects, panic, unreachable);
    • the inventory_merge and worker_frames fuzz targets.
  • Writes and audit.
    • The section is edited through the config entries API as a managed kind, discovery: admin only, with dry run, If-Match, audit and secrets redacted.
    • No agent scope writes the discovery kind. Agents get 403.
    • A setting made in a file shows as "set by file" and can't be edited through the API.
    • At startup and on reload, a change to the effective [discovery] hash is audited as discovery.config_changed (source=file).
    • These are audited too: scan imports, deleting an import, SNMP tests, finding mutes, and the public passes and circuit-breaker trips.
    • Humans need the operator role for imports, deleting imports and mutes. Agents need ops:discovery, which is an Operator-role scope.
    • snmp/test is admin only for humans. Agents need ops:discovery_test, an Admin-role scope.
    • Discovery never writes router or gateway configuration, never sends an SNMP SET, and never blocks or moves a device. Quarantine stays an explicit action (06 §7).
  • N−1 (CLU-010).
    • [discovery] and [local] device_inventory_addresses are serialized only when set, like ADR-903's _ref fields.
    • An N−1 replica refuses a version that holds them.
    • The API refuses the first write of [discovery] with 409 members_too_old while any full member runs N−1.
    • config check warns when the file sets the section in a mixed-version cluster.

Alternatives rejected

  • Built-in ICMP/TCP/ARP/mDNS probing: out of scope by owner decision. It also brings IDS self-blocking of the DNS host, neighbour-table overflow and conntrack pressure.
  • [discovery] as node-local configuration: there would be no audited write path. ADR-161 rejected the same thing for mutes.
  • SNMP on every node: each node has a different view of the network, and the traffic and IDS exposure would double.
  • Host names as SNMP addresses: anyone who can change DNS records could redirect a credential.
  • Identity reads to any inventory address: one CSV import could turn the reads into a sweep of a whole /16.

Consequences

  • WrenDNS now sends SNMP read requests on the LAN. They go to listed devices, and, with an identity credential, to hosts that a router, the neighbour table or a gateway ARP table currently sees.
  • Devices that no source sees stay unknown until the owner imports a scan. Imported devices get no identity reads until a class 1–3 source binds their address.
  • Amends ADR-080 and ADR-902: "read-only toward the gateway" now also covers SNMP reads. Nothing writes.
  • Proposed amendment of ADR-906: the upstream-sync collision check also covers requirement prefixes (DSC) and milestone numbers (M25).
  • ADR-081, ADR-091, ADR-117 and ADR-161 are unchanged.

Owner decisions (2026-11-16): the owner accepted the recommendations for questions 1–12 and 14–16 of the M25 design, and answered question 13 by a test. These ADRs (ADR-907 to ADR-913) stay Proposed until the owner accepts the ADRs themselves.

  • Accepted recommendations:
    • 1a: SNMP credentials as *_file first, once T23.1–T23.3 are in; *_ref in T25.8.
    • 2a: The aes 0.8 crate with hand-written CFB-128 for v3 privacy (ADR-911).
    • 3a: A hand-written restricted nmap XML parser (ADR-913).
    • 4a: Imports kept on the scanning (designated) node; replication is a follow-up.
    • 5c: Retention configurable, defaults 7 days (SNMP, neighbour and history-only entries) and 30 days (imports).
    • 6a: Inventory addresses in DNS opt-in, off by default (DSC-012).
    • 7a: public is a validation error without public_ids_acknowledged and a gateway agent or UniFi router (ADR-909).
    • 8a: The primary is the designated node when node is unset.
    • 9a: 30 days of stat/alluser history.
    • 10a: Home Assistant devices without entities go in the inventory only.
    • 11a: Open ports and OS guesses from imports kept, capped at 16 ports, behind discovery:read.
    • 12a: No MD5 or DES.
    • 14a: Imported addresses never get identity reads; only class 1–3 bindings are SNMP destinations.
    • 15a: No discovery at privacy level 2 or above.
    • 16a: Split agent scopes: ops:discovery (Operator) and ops:discovery_test (Admin).
  • Question 13, answered by a test:
    • A UniFi gateway serves ipNetToPhysicalTable over SNMPv3 with SHA and AES, with IPv4 and IPv6 entries, most of them with a MAC; ipNetToMediaTable has the IPv4 ones. T25.6 stays as written for ARP (option a). M25 is IPv4 only, so the IPv6 rows are counted and ignored; they are a possible source for T24.8 (IPv6 device names) later.
    • The gateway has no BRIDGE, Q-BRIDGE or LLDP MIB. On networks whose switches and APs are not UniFi, port mapping therefore needs SNMP agents on the switches themselves; the UniFi API (ADR-912's devices read) can't supply it there. T25.6 says so.
    • A gateway that still answers v1/v2c public is a finding: the SNMP setup docs flag it to turn off once v3 works.
    • A network printer that answers v2c public with the Printer MIB is the case the ADR-909 opt-in is for.

Requirements CLU-004 CLU-010 DSC-012

Builds on ADR-080 ADR-081 ADR-091 ADR-117 ADR-161 ADR-902 ADR-903 ADR-906 ADR-908 ADR-909 ADR-910 ADR-911 ADR-912 ADR-913

Referenced by ADR-1002 ADR-1004 ADR-1007 ADR-908 ADR-909 ADR-910 ADR-913 ADR-923 ADR-928 ADR-930 ADR-969

ADR-908 SNMP poller: v2c and v3 USM, read-only, in a worker processAccepted 2026-11-16On a typical home network, the most valuable SNMP data is the gateway's ARP table: ipNetToPhysicalTable (1.3.6.1.2.1.4.35), falling back to ipNetToMediaTable (1.3.6.1.2.1.4.22).

Context

On a typical home network, the most valuable SNMP data is the gateway's ARP table: ipNetToPhysicalTable (1.3.6.1.2.1.4.35), falling back to ipNetToMediaTable (1.3.6.1.2.1.4.22). It gives a MAC for every address on every VLAN. Next in value:

  • managed switches' forwarding tables per VLAN, mapped to ports;
  • LLDP neighbours;
  • the identity of printers and network gear.

The repo has no SNMP code. Constraints:

  • The release build aborts on panic.
  • ring covers HMAC-SHA-1/SHA-2 and the digests, but has no raw AES block.
  • Many UniFi devices run Net-SNMP, and UniFi uses one v3 password for both auth and priv.
  • Whether a UniFi gateway serves its ARP table over SNMP was unconfirmed when this was written. A test confirmed it does, over v3 with SHA and AES (ADR-907, owner decisions).
  • On systemd, the unit's default OOMPolicy=stop stops the whole unit when the kernel OOM-kills any process in it.
  • On Kubernetes with cgroup v2, kubelet 1.28 and later sets memory.oom.group=1, so an OOM kills every process in the container.

Decision

  • Crate. A new crate, wrendns-snmp.
    • Lints: #![forbid(unsafe_code)] and #![deny(clippy::indexing_slicing, clippy::arithmetic_side_effects, clippy::panic, clippy::unreachable)].
    • A hand-written minimal BER codec. Definite lengths only, a depth cap of 8, a message cap of 64 KiB and a cap of 256 varbinds per PDU.
    • Types: INTEGER, OCTET STRING, OID, NULL, IpAddress, Counter32, Gauge32, TimeTicks and Counter64, plus the noSuchObject, noSuchInstance and endOfMibView exceptions.
    • It is off the hot path and not on the AGENTS.md bench-smoke list.
  • PDUs. It sends GET, GETNEXT and GETBULK, and receives Response and Report. The encoder has no SetRequest type, and no other write PDU type or tag constant. A CI grep test checks this.
  • v3 USM (RFC 3414, RFC 7860, RFC 3826).
    • Engine discovery uses Report messages. Replies must match msgID and requestID. At most one unauthenticated time resync per agent per minute. Superseded in part by the 2026-11-17 amendment below and ADR-931 (Proposed): only an authenticated Report moves the clock.
    • Amended 2026-11-17 (m25-snmp review): unauthenticated Reports are never used for the clock. Discovery accepts only a noAuthNoPriv Report whose varbind is usmStatsUnknownEngineIDs. An authenticated notInTimeWindow Report takes the agent's clock, at most once per agent per minute, and the request is sent once more. Message and request IDs start at a random value on separate counters, so a spoofed datagram cannot guess them. A v3 reply must match the request's security level, engine ID and user. The cached engine is dropped after a failed exchange, so a forged engine ID cannot stay in place. The MAC is compared in constant time, and the community is compared the same way. Credential files (2026-11-17, m25-snmp review): the file is opened no-follow and non-blocking, and its identity is checked against the canonical path (ADR-932, Proposed). An authPriv request accepts an authNoPriv time-window Report with request ID 0 or the request's ID, when its MAC verifies (ADR-931, Proposed).
    • Key handling (amended 2026-11-17): Ku and Kul are held in Zeroizing, and the privacy key is zeroized, with aes built with its zeroize feature. ring's digest and HMAC contexts keep password-derived state that cannot be zeroized; this is accepted, because they are dropped at the end of the round and never cached. The privacy salt is eight random octets per message (64 bits from SystemRandom), not RFC 3826's seeded counter: no counter state is kept across restarts, and the repeat chance under one key is negligible.
    • Ku is the 1 MiB password-to-key expansion. It is computed once per credential per poll round with ring::digest, held in a Zeroizing buffer, and dropped at the end of the round.
    • Kul, the key localised per engine, is one short hash. It is computed on demand and never cached.
    • Authentication: HMAC-SHA-96, and HMAC-SHA-256/384/512 truncated per RFC 7860 (ring::hmac).
    • Privacy: AES-128-CFB (ADR-911).
    • Security levels: authNoPriv and authPriv. priv_password_* defaults to the auth password.
    • Refused at config time, with a reason: MD5, SHA-224, DES, AES-192/256, and v3 noAuthNoPriv.
  • Worker process. The designated node runs the poller in wrendns discovery-worker.
    • Binary. The worker is started from /proc/self/exe, the inode that is actually running, not current_exe(). The image doesn't grow, and an upgraded file on disk is never started by mistake.
    • Version handshake. The first frame is a handshake: build ID plus protocol version. On a mismatch the worker is refused and the health reason discovery_worker_version_mismatch is raised.
    • Environment. Cleared with env_clear(). No arguments carry secrets. Jobs and credentials arrive on stdin only.
    • Frames. Each frame is a u32 big-endian length, a type byte, then the payload:
      • JSON control and result frames, at most 1 MiB, with large results split across frames;
      • binary chunk frames, at most 512 KiB.

The main side reads frames on the wrendns-inventory thread with a bounded, panic-free reader.

  • Stderr. Captured and logged with a rate limit, never inherited.
  • Memory limit. At start the worker sets RLIMIT_DATA to worker_memory_mib (default 64, range 32–128). An allocation failure then aborts only the worker, well below the cgroup limit. RLIMIT_AS is not used, because reserved virtual mappings would trip it.
  • Other hardening at start.
    • oom_score_adj is set to 1000.
    • PR_SET_DUMPABLE=0 and RLIMIT_CORE=0 are set, so an abort never writes a core dump that holds Ku or passwords.
    • All of these go through one safe wrapper in wrendns-net, with a // SAFETY: comment (AGENTS rule 7).
  • Runtime. It calls background_thread() and runs one current-thread runtime.
  • Sockets. It holds no listening sockets, only connected UDP client sockets. It exits on stdin EOF.
  • Supervisor. Restarts the worker with backoff: 1 s, doubling up to 5 min. Three crashes within 10 minutes raise discovery_worker_failing (degraded, never DNS). While the worker is down, results go stale and DNS is unaffected.
  • systemd. deploy/systemd/wrendns.service sets OOMPolicy=continue, so a kernel OOM kill of the worker never stops the unit.
  • Infrastructure polling ([[discovery.snmp_agent]]).
    • Interval. Each agent is polled every interval_secs (default 300, minimum 60).
    • Pacing.
      • One request in flight per agent.
      • At least 50 ms between requests and at most 20 requests/s per agent.
      • Timeout 1.5 s, with 2 retries.
      • A walk stops after 3 timeouts in a row or 30 s of wall clock.
    • Sizes. GETBULK max_repetitions is 5–25 (default 10). Each table is capped at 5,000 rows. One 64 KiB receive buffer per agent is reused.
    • Replies. A reply counts only if it comes from the address the request went to.
    • Tables.
      • arp: ipNetToPhysicalTable, else ipNetToMediaTable.
      • ifmib: ifTable and ifXTable names, plus ipAddressTable/ipAddrTable for the agent's own addresses.
      • bridge: dot1qTpFdbTable, else dot1dTpFdbTable, with ports mapped through dot1dBasePortIfIndex.
        • dot1qTpFdbTable is indexed by dot1qFdbId, which is not the VLAN ID. It is mapped to the VLAN ID through dot1qVlanCurrentTable's dot1qVlanFdbId.
        • A port counts as an uplink or trunk, and its MACs give no location, if it has more than 8 learned MACs, or an LLDP neighbour that is itself a listed agent or a UniFi device.
        • Per-VLAN contexts (community@vlan, v3 contextName) are left Open.
      • lldp: the LLDP-MIB remote table (1.0.8802.1.1.2), at most 4 neighbours per port.
  • Capability record.
    • On the first poll and on snmp/test, each listed table root gets one GETNEXT.
    • The record is kept and shown: tables answered, security level reached, engine ID, sysObjectID.
    • Capabilities are never assumed. A table that doesn't answer is skipped until the next test, and the skip is logged once.
  • Host identity reads.
    • Who. An address inside a [[discovery.subnet]] that names a host_credential, and that has a current class 1–3 binding (ADR-907).
    • What. One GET of sysName, sysDescr, sysObjectID and sysLocation. If sysObjectID or the device class says printer, also a GET of prtGeneralPrinterName. No walks.
    • How often. At most once per host per identity_interval_hours (default 24, minimum 6). At most 5 hosts/s in total and 1,024 hosts per pass.
    • Replies. An answer from any address other than the one asked is dropped.
  • Credential roles.
    • [[discovery.snmp_credential]] has role = "infrastructure" | "host".
    • It is a validation error for a subnet to name an infrastructure credential, or for an agent to name a host credential. A device on the LAN therefore never receives the gateway's credential.
    • A v2c host credential warns: every host in the subnet learns the community in cleartext.
  • Untrusted strings. Every string from a device:
    • is cut: sysName and sysLocation to 64 B, sysDescr and the printer name to 255 B;
    • has control characters removed (the SafeString::new rule);
    • is rendered as text only.

MCP tool descriptions mark these fields as device-supplied data, not instructions.

  • Credentials (ADR-903).
    • community, auth_password and priv_password each take either *_file or *_ref. Inline values are a validation error. Files win, as in ADR-903.
    • Refs are named discovery.<credential-name>.<field>, for example discovery.infra-v3.auth_password.
    • A missing ref on an API write answers 422 secret_missing. At load time a missing ref warns, and the agent or subnet is skipped.
    • They are write-only, added to credentials::PATHS and API_PATHS, held as SecretValue (redacting Debug, zeroized), never as SafeString, and sent to the worker only over stdin.
  • Diagnostic CLI. wrendns snmp walk --agent <name> [--table arp|ifmib|bridge|lldp]. It takes a configured agent name only, never an address, and prints rows with secrets redacted.

Alternatives rejected

  • An SNMP crate such as snmp2 or csnmp: new dependencies with incomplete USM, and their panic behaviour isn't ours to control.
  • The codec in wrendns-proto: that is a hot-path crate.
  • Polling in the main process, relying only on lints and fuzzing: one missed panic aborts DNS.
  • Relying on oom_score_adj alone: systemd's OOMPolicy=stop and Kubernetes' memory.oom.group kill DNS with the worker.
  • current_exe(): after an upgrade it can start a newer binary than the one running.
  • Caching Kul per engine: the cache grows with every v3 host.
  • MD5 and DES: weak, and ring has no MD5.
  • An address-based snmp/test: it would be a destination chosen at request time.

Consequences

  • About 3–6 MiB more RSS while discovery is on. The worker is capped by worker_memory_mib.
  • Sending v3 to a host exposes the password to offline guessing by that host: it chooses the engine ID and receives an HMAC over a known message. This is why credentials have roles. The docs say to give hosts a low-value, shared identity.
  • v2c host credentials are cleartext on the subnet.
  • When a switch shows a MAC on several ports at once (a loop, or a move in progress), the most recently seen port is recorded.
  • On Kubernetes outside the host network, the SNMP source address is the node IP after SNAT. Device access lists must allow that address.

Builds on ADR-903 ADR-907 ADR-911 ADR-931 ADR-932

Referenced by ADR-1001 ADR-1002 ADR-907 ADR-910 ADR-913 ADR-929 ADR-931 ADR-933 ADR-934 ADR-969 ADR-980 ADR-988

ADR-909 The public community for identity reads, by explicit per-subnet opt-inAccepted 2026-11-16Many printers and cheap devices answer v2c public.

Context

Many printers and cheap devices answer v2c public. The owner approved trying it on 2026-11-16, with four conditions: an explicit per-subnet opt-in, off by default, audited, and with the IDS risk written down.

An IDS reads this traffic as credential guessing. Snort 1:1411 "SNMP public access udp" and the ET SNMP rules fire on it. UniFi IPS with "Block Source IP" could block the DNS host itself, and the whole LAN would lose DNS.

Decision

  • The switch.
    • [[discovery.subnet]] snmp_try_public defaults to false.
    • Setting it to true is a validation error unless both of these hold:
      • the same subnet sets public_ids_acknowledged = true, which confirms the DNS host is on the gateway's IPS allow list (UniFi: Security → Detection allow list);
      • the gateway is covered by a listed snmp_agent, or by a UniFi [[router]] that the designated node polls. The circuit breaker needs one of them.
    • Both fields are set through the admin-only discovery kind and audited. A setting made in a file shows as set by file and is covered by the startup audit (ADR-907).
  • Which hosts.
    • Only addresses inside that subnet that have a current class 1–3 binding (ADR-907).
    • Only when the subnet has no host_credential, or that credential has just failed for this host.
    • Never infrastructure agents, which need a configured credential.
  • What is sent. One v2c GET of sysName, sysDescr, sysObjectID and sysLocation, with community public. The code has no other built-in community string. No walks, no SET.
  • Limits.
    • At most 1 host per second, and at most 1 retry.
    • One attempt per host per 7 days, and failed attempts count. The key is the MAC when known, otherwise the IP, so an address change doesn't reset it.
    • The limit survives restarts in the inventory file. That file is written at most once a minute after a pass.
  • Empty start. When the inventory starts empty (a failover, or the file is missing), no public pass runs for 7 days.
  • Circuit breaker. All public attempts stop for 24 h, and the stop is audited, if during a pass either of these happens:
    • three sysUpTime GETs in a row to the listed gateway agent go unanswered (they are sent every 10 s during the pass), or the UniFi poll fails;
    • the health reason upstream_down or upstream_group_down appears.

The breaker never uses ICMP or TCP.

  • Audit and visibility.
    • Each pass writes one audit summary: subnet, hosts tried, hosts that answered.
    • While any subnet has the switch on:
      • config check warns;
      • the UI shows a banner;
      • GET /discovery says so.
    • Answers are tagged identitySource = "snmp-default-community".
    • A host that answers gets the default_community finding (ADR-910).

Alternatives rejected

  • A list of common communities: that is guessing.
  • On by default: IDS self-blocking.
  • Trying it on infrastructure agents: the owner configures those.
  • A warning instead of the acknowledgement error: the failure takes DNS down for the LAN.
  • A breaker based on reachability probes: that would be active probing (ADR-907).

Consequences

  • Printers and similar devices on an opted-in subnet are identified without per-device setup.
  • The gateway's IDS logs may still show the attempts. The docs carry:
    • the risk text;
    • how to allow-list the host;
    • a note that a device answering public is itself a security finding.

Builds on ADR-907 ADR-910

Referenced by ADR-907 ADR-910

ADR-910 Inventory merge model: keyed by MAC, address bindings with a time limit, never DNS policyAccepted 2026-11-16AGTDNSOBSSources disagree, and each has its own trust: Constraints:

Context

Sources disagree, and each has its own trust:

  • UniFi current clients and reservations;
  • OPNsense leases;
  • Home Assistant names by MAC;
  • the local neighbour table;
  • SNMP ARP and bridge tables;
  • SNMP identity;
  • imported scans, which are claims from a file;
  • passive mDNS.

Constraints:

  • devices::Names is IPv4-keyed, and every peer pulls it every 60 s. A full inventory there would exceed MAX_RPC and silently break router-name sharing.
  • wrendns_policy::Neighbors decides MAC-based client matching.
  • ADR-117 bounds identify.rs to 1,024 devices for 1 day.
  • ADR-102 sets what is kept and shown at each privacy level. At level 2, nothing that identifies a client is kept.

Decision

  • Model.
    • The MAC is the key. An entry has:
      • mac;
      • up to 4 addresses, each with its source and lastSeen;
      • display names, each with source and rank;
      • the OUI vendor;
      • VLAN and network;
      • switch port and AP (from UniFi or the SNMP bridge table);
      • LLDP neighbours (up to 4);
      • an identity record: sysName, sysDescr, a vendor index into the PEN preset, and the printer name;
      • up to 16 open TCP ports, from imports;
      • a source bitmask;
      • an import-ID bitmask (16 bits, one per kept import);
      • firstSeen and lastSeen;
      • findings and mutes.
    • A result with no MAC goes into a separate IP-only class, keyed ip:<addr>. Examples: an import from a routed scanner, or an identity answer before any MAC is known.
      • Capped at 1,024 entries, oldest dropped first.
      • A MAC is never invented.
      • When a MAC source binds the address, the entry merges into the MAC entry.
    • Caps:
      • 4,096 MAC entries;
      • at most 8,192 import-derived rows in total, with the oldest import dropped first;
      • per-entry caps as in ADR-908.

About 600 B per entry at worst.

  • Which address is current. Precedence for a MAC's current address:
    1. UniFi stat/sta, OPNsense leases and UniFi reservations (ADR-902 rules).
    2. The local neighbour table, in states REACHABLE, STALE, DELAY or PROBE. A row is accepted only if the address lies in a configured subnet and Neighbor.ifindex is not a container or overlay interface: lo, docker*, br-*, veth*, cni*, flannel*, cali*, vxlan*, tun*, tap*, wg*, tailscale*, zt*.
    3. SNMP ARP from listed infrastructure agents.
    4. Imports.
    5. UniFi stat/alluser last_ip. This is history only, never current.

Rules:

  • The most recent binding from the best class is primary. The others are kept as aliases and shown.
  • Same address, different MAC: the newest observation from classes 1–3 wins. An import or history never replaces a class 1–3 binding. The case is flagged ip_conflict.
  • A MAC with the locally administered bit set is flagged randomized. No stable-identity finding is raised for it.
  • Only class 1–3 bindings make an address an SNMP destination (ADR-907).
  • Display names (inventory only), in rank order:
    1. the configured client name;
    2. Home Assistant name_by_user;
    3. the router alias or host name, in [[router]] order;
    4. a Home Assistant integration's name;
    5. passive mDNS;
    6. SNMP sysName or printer name;
    7. an import's host name.

Ranks 6 and 7 are labelled with their source.

  • Containment.
    • Inventory data never enters any of these: router_leases, peer_names.routers, mdns_names, wrendns_policy::Neighbors, client matching, or identify.rs's seen chain. This covers SNMP, imports, stat/alluser, stat/device, entityless Home Assistant devices and the neighbour-table source.
    • Device DNS names (ADR-901) are never created from it. The one exception is the opt-in below, which supplies an address and never a name.
    • Feeding policy would need its own ADR, because ARP spoofing lands in the gateway's table.
    • Passive mDNS naming under ADR-901 is unchanged.
  • Device addresses in DNS (opt-in). With [local] device_inventory_addresses = true (default false), a MAC can get an address from the inventory. This applies when the MAC already has a name in DNS-023's sources but no address there. The address comes from class 2 or class 3 only, and only if it was:
    • seen in the last poll;
    • not flagged ip_conflict;
    • not flagged randomized.

These bindings, {mac, ip, name} with at most 1,024 rows, reach other nodes in a new Names.inventory field. The field is #[serde(default)], so it is N−1 safe, and it amends ADR-125. The bindings rank below every existing source in the device_dns order, which amends ADR-901's source order.

  • Findings. Findings live on the entry, not in AnomalyKind, so ADR-161 is unchanged.
    • default_community (ADR-909).
    • ip_conflict.
    • new_device: the first time any source sees a MAC, after a 24 h learning period from first enable. It is raised through the existing new-device alert with source = "inventory", so ADR-102 applies (off at privacy level 1 and above).

When the inventory starts empty (a failover, or the file is missing), no new_device alerts are raised for 24 h. A mute applies to one entry and one kind, with an optional expiry, and is kept in the inventory file. Nothing blocks or moves a device.

  • Retention.
    • Entries seen only by SNMP, the neighbour table or history age out retention_days after lastSeen (default 7).
    • Import rows age out [discovery.import] retention_days after their import (default 30).
    • An entry that another source still sees is never removed.
    • A host counts as absent only after two polls in a row miss it.
  • Storage.
    • Held in ArcSwap on the designated node.
    • Persisted to <data_dir>/inventory.json: mode 0600, atomic rename. Written at most every 15 min and on shutdown. After a public pass or an import, at most once a minute.
    • Left out of backups.
    • Left out of support packages unless asked for with --include-inventory, which goes through ADR-156's pseudonymisation.
    • Not replicated as configuration.
  • Cluster read. Read::Discovery, federated, with AGT-011 missingNodes:
    • A non-designated node asks the designated node for a filtered page of at most 500 rows.
    • Each answer is capped at 256 KiB (MAX_RPC/4). The server enforces the cap by trimming the page.
    • An N−1 node answers "unknown call" and is listed in missingNodes.
  • Privacy (ADR-102).
    • At level 1, sysName and host names are hashed like client names.
    • At level 2 and above, [discovery] enabled = true is a validation error, because nothing that identifies a client may be kept. The other route, a Proposed amendment of ADR-102, is an owner question.

Alternatives rejected

  • Extending Names with the full inventory: it exceeds the RPC frame and spreads open ports to resolver pods.
  • An IP-keyed inventory: it loses devices that move addresses.
  • Feeding Neighbors: ARP spoofing would move devices between groups.
  • New AnomalyKind variants: they clash with ADR-161's mute model, OBS-014 IDs and N−1 deserialisation.
  • Feeding identify's seen chain: it breaks ADR-117's bounds.
  • Storing every import row separately: up to 65,536 rows outside the caps.

Consequences

  • Clients → Discovered and the Networks counts see devices the routers don't list.
  • After a failover to a new designated node, the inventory starts empty until the next polls, and imports must be uploaded again (ADR-913).
  • With DSC-012 on, a spoofed MAC could claim a named device's address. ADR-902 already accepts the same exposure for leases.
  • SNMP identity does not improve identify's class guesses in M25. Left Open.
  • Closes T22.3's Open item "the neighbor table as a MAC → address source".

Requirements AGT-011 DNS-023 DSC-012 OBS-014

Builds on ADR-102 ADR-117 ADR-125 ADR-156 ADR-161 ADR-901 ADR-902 ADR-907 ADR-908 ADR-909 ADR-913

Referenced by ADR-1000 ADR-1004 ADR-1005 ADR-907 ADR-909 ADR-912 ADR-913 ADR-923 ADR-924 ADR-942

ADR-911 Dependency aes 0.8 for SNMPv3 privacyAccepted 2026-11-16The owner asked for authPriv.

Context

The owner asked for authPriv. RFC 3826 needs AES-128 in CFB-128 mode. ring exposes AES only inside AEADs and QUIC header protection. cipher 0.4.4, inout, crypto-common and cpufeatures 0.2.17 are already in Cargo.lock, pulled in through crypto_box and chacha20.

Decision

  • Add RustCrypto aes 0.8 (MIT/Apache-2.0) to wrendns-snmp only.
  • Write CFB-128 by hand, about 20 lines, instead of adding cfb-mode. The IV is engineBoots ‖ engineTime ‖ salt.
  • PR justification line: "aes 0.8: SNMPv3 AES-128-CFB privacy (RFC 3826); ring exposes no raw AES block; cipher/cpufeatures already in tree; +12.4 KiB measured (x86_64 probe crate)."
  • Gates:
    • cargo deny check passes, and cargo tree -d shows no duplicate versions;
    • the size delta is measured with deploy/image/size.py --oci on amd64, arm64 and arm/v7 (armv7 builds the software fixslice path, arm64 the ARMv8 path);
    • the RFC 3826 test vectors pass on all three.
  • aes uses unsafe CPU intrinsics internally. As with ring, third-party crates fall outside AGENTS rule 7, which applies to workspace code.

Alternatives rejected

  • Hand-written AES: table lookups leak through cache timing, and hand-rolled crypto needs its own review.
  • authNoPriv only: the owner asked for privacy. It stays the fallback if the size gate fails.
  • cfb-mode: one more crate for 20 lines.

Consequences

  • About 12–20 KiB per architecture, to be measured.
  • A Pi 4 has no AES instructions, so it uses constant-time software AES. At SNMP rates the cost is negligible.

Referenced by ADR-907 ADR-908 ADR-956

ADR-912 Extra read-only UniFi reads for the inventoryAccepted 2026-11-16ADR-080 and ADR-902 read stat/sta, rest/user (reservations only) and rest/networkconf.

Context

ADR-080 and ADR-902 read stat/sta, rest/user (reservations only) and rest/networkconf. UniFi also knows:

  • offline and historical clients (stat/alluser);
  • switch-port MAC tables with VLAN, and LLDP (stat/device);
  • per-client is_wired, sw_mac, sw_port, ap_mac, vlan, first_seen and last_seen.

UniFi has no ARP endpoint. ADR-902 rejected known clients without a reservation as DNS names, because a stale address names the wrong device. routers.rs runs as tokio::spawn on the main multi-thread runtime (server.rs:1100), the same runtime that serves TCP, DoH and cache misses.

Decision

  • With [discovery] unifi_reads set, the designated discovery node makes these extra reads for each UniFi [[router]], with the same key or session:
    • client_fields: more fields from the existing stat/sta/rest/user answers, at no extra request cost;
    • all_users: POST stat/alluser with within = unifi_all_users_within_hours (default 720, maximum 8,760);
    • devices: GET stat/device, for infrastructure identity, the port mac_table (VLAN, static, age), lldp_table and uplink.
  • Where they run. The all_users and devices reads, and the parsing of the extra client_fields, run on the wrendns-inventory thread's runtime. They reuse the router's session and credentials. routers.rs only shares the session and a copy of the raw answers it already holds. None of this work runs on the main runtime.
  • Each read is optional. A refused or failed read is logged once per change.
  • Caps: 4 MiB and 8,192 rows per read.
  • Results go only into the inventory (ADR-910):
    • as class 1 (current clients), class 5 (history) and port locations;
    • never into router_leases, peer_names or device_dns;
    • counted against the 4,096-entry cap.

Ports whose mac_table holds more than 8 MACs, or that are UniFi uplinks, give no location.

  • Home Assistant. With home_assistant_all_devices = true (default true when discovery is on), a second fixed, read-only template runs on the inventory thread. It lists registry devices that have a mac connection and no entity (name_by_user, name, area). The answer is capped at 1 MiB. These names go into the inventory only. ADR-902's DNS-name template is unchanged.
  • Amends the "Not done" of ADR-080 and ADR-902.

Alternatives rejected

  • Running the extra reads inside routers.rs on the main runtime: up to 4 MiB of JSON parsed next to DNS work.
  • The Integration API: a second code path with fewer fields.
  • The fingerprint map (/v2/api/fingerprint_devices): numeric IDs and an unofficial endpoint. Left Open.
  • stat/alluser as DNS names: ADR-902's stale-address reasoning.

Consequences

  • One or two more requests per UniFi poll, on one node.
  • On UniFi switches, wired static devices show their switch port without SNMP.
  • The field names come from reverse-engineered docs and are checked against a real console in e2e.

Builds on ADR-080 ADR-902 ADR-910

Referenced by ADR-1003 ADR-907 ADR-998 ADR-999

ADR-913 Importing scan results the owner produced: nmap XML and a simple CSVAccepted 2026-11-16Only a scanner can find devices that no source sees.

Context

Only a scanner can find devices that no source sees. The owner runs one themselves, for example nmap -sn -oX or nmap -sS -p … -oX on a host on that VLAN.

WrenDNS has no XML parser, and the uploaded file is untrusted input. The usual risks are XXE, entity expansion and very large files. Two existing stores would also hold whole bodies:

  • the plan store keeps up to 500 plans for 24 h with the whole body (plans.rs:30);
  • the idempotency table writes the full request into state.db (managed.rs:186).

Decision

  • Formats. Nothing else is accepted:
    • nmap XML (-oX, nmaprun 1.0x);
    • CSV with the header ip,mac,hostname. mac and hostname are optional, each field may have one optional pair of double quotes, and the file is UTF-8.
  • Parser. A hand-written restricted XML tokenizer in crates/wrendns/src/discovery/import/, under the ADR-908 lints.
    • Accepted: the XML declaration, processing instructions (ignored), comments, and a <!DOCTYPE …> without an internal subset.
    • Refused:
      • a [ internal subset, and external IDs;
      • CDATA;
      • a declared encoding other than UTF-8 (an optional BOM is allowed).
    • Entities. Only the five predefined entities and numeric character references are allowed. A numeric reference must be an XML Char, so &#0; and C0 controls other than tab, LF and CR are refused. No entity is ever defined or expanded.
    • Limits: depth 16, 200,000 elements, 32 attributes per element.
    • Attribute values. The 4 KiB cap applies to the attributes the reader uses. Over-long values on ignored elements, such as --script output, are skipped and counted, and they still count toward max_bytes.
    • Truncation. A file that ends before </nmaprun> (an interrupted scan) answers 422.
  • What is read. Everything else is ignored.
    • host/status[@state="up"];
    • address (ipv4, and mac with vendor);
    • hostnames/hostname: up to 4, each at most 253 B;
    • ports/port[@protocol="tcp"]/state[@state="open"]: up to 16 port numbers;
    • the top osmatch@name, cut to 64 B;
    • nmaprun@start, the scan time.
  • Where parsing runs. In a separate, short-lived wrendns discovery-worker --import process. It never receives credentials and exits after one parse.
    • It gets the same hardening as ADR-908: /proc/self/exe, the version handshake, env_clear(), RLIMIT_DATA, PR_SET_DUMPABLE=0, RLIMIT_CORE=0, oom_score_adj 1000.
    • The body arrives as binary chunk frames of at most 512 KiB, and the parse has 10 s of wall clock.
    • A parse failure answers 422. A worker crash or timeout answers 503. DNS is unaffected.
  • Limits.
    • The body is at most max_bytes (default 8 MiB, maximum 32 MiB) and at most max_hosts host rows (default 4,096).
    • The import route sets an explicit DefaultBodyLimit equal to max_bytes, and reads the body as a counted stream that is forwarded chunk by chunk. It never buffers the body as Bytes.
    • One import in progress per node.
    • At most 10 imports per hour (429 with Retry-After).
    • The last keep imports are kept (default 16).
  • What is merged.
    • Rows whose address is in a configured [[discovery.subnet]] become source import, tagged with the import ID. A row with a MAC goes into class 4. A row without one goes into the IP-only class.
    • Rows outside every subnet, or at a refused address (ADR-907), are counted as dropped.
    • Imports never override class 1–3 bindings, never feed DNS or policy, and never make an address an SNMP destination (ADR-907, ADR-910).
    • Device strings are sanitised as in ADR-908.
  • Provenance.
    • Each import records:
      • its ID and time;
      • the user or agent, and the reason;
      • the format and the scan's own start time;
      • counts: merged, IP-only, dropped, skipped over-long values.
    • DELETE removes an import's rows.
  • API and surfaces.
    • POST /api/v1/discovery/imports:
      • Content-Type: application/xml or text/csv;
      • ?dryRun=true parses and returns the summary and the first 20 rows, and keeps nothing;
      • Idempotency-Key and X-Wrendns-Reason.
    • For imports, the idempotency replay record stores a SHA-256 of the body and the response, never the body.
    • On a non-designated node, an upload of at most 768 KiB is forwarded to the designated node. A larger one answers 413 import_too_large_to_forward, naming the node to upload to.
    • Humans need the operator role. Agents need ops:discovery and a reason. When [agents] require_approval is on, agent imports go through the plan.
    • Audited as discovery.import and discovery.import_deleted.
    • Also available in the UI, ctl and MCP (plan_import_scan → apply_plan).
  • Plans.
    • plan_import_scan (content at most 768 KiB) parses in the import worker when the plan is made.
    • The plan stores only the parsed summary and at most 20 preview rows. The parsed rows sit in a separate bounded staging area: at most 2 open import plans per node, at most 4,096 rows each, dropped on apply, discard or expiry.
    • The raw content is never stored and never appears in list_plans.
  • Storage. Parsed rows only, never the raw file. They live in the inventory file on the designated node, as the import-ID bitmask on each entry plus per-import counts. At most 8,192 import-derived rows in total; the oldest import is dropped first.

Alternatives rejected

  • quick-xml or roxmltree: a new dependency for a small, fixed subset of XML.
  • Parsing in the SNMP worker: credentials and untrusted XML would share one process.
  • Keeping raw bodies in plans or idempotency records: up to about 375 MiB in memory, above MemoryMax=256M, and agents could read the raw scan.
  • Running nmap or scheduling scans: out of scope (ADR-907).
  • Keeping raw uploads: size, and data that was never needed.
  • Replicating imports to all full members: left as an owner question.

Consequences

  • The operator's scans show up within seconds and can be removed again.
  • Results from a routed scanner have no MAC until another source binds the address.
  • Imported addresses get no SNMP identity reads until a class 1–3 source sees them.
  • Imports are lost when the designated node changes.

Builds on ADR-907 ADR-908 ADR-910

Referenced by ADR-907 ADR-910 ADR-939

ADR-914 Which settings the UI may change, and how risky ones are guardedAccepted 2026-11-16AGTAPICLUOn 2026-11-16 the owner made a standing rule: every setting, route and tool gets a UI control (spec/10, API-901).

Notes

How the guarded tier works is detailed in ADR-956 (framework) and ADR-957 (recovery), Accepted 2026-11-17.

Context

On 2026-11-16 the owner made a standing rule: every setting, route and tool gets a UI control (spec/10, API-901). An audit of the fork against the UI found settings with no control at all:

  • [special] (M24, ADR-904) and most of [local] (M22, ADR-901). Both are shared sections, not node-local (wrendns-config/src/shared.rs NODE_LOCAL).
  • [clients] mdns, which [local] device_mdns needs before it does anything.
  • OTLP export ([telemetry.otlp]), which is node-local.
  • [agents] enabled, the agents kill switch (AGT-009).
  • The security gates and bootstrap settings: the secrets key files, secret_file_dirs, allow_secrets_over_http, allow_insecure_basic, the listeners and their TLS, api.listen/api.tls, api.trusted_proxies, cluster init, join and bootstrap, [cluster.git], node.* identity and storage, the watchdog, and the file paths trust_anchors_file, signatures_file, hosts_files and zone.file.

The audit recommended showing the last group read-only. The owner chose admin controls instead (2026-11-16), on condition that the design is safe. The risks are concrete:

  • a wrong listener, API address, TLS or proxy change locks every admin out of the UI, and a wrong DNS listener change takes the LAN's DNS down;
  • a key typed into the store it protects is protected by nothing;
  • a widened secret_file_dirs would undo T23.2's path rules, and allow_secrets_over_http or allow_insecure_basic puts credentials on the wire in clear;
  • a cluster init or join replaces a node's configuration.

Decision

  • Three tiers. Every setting is in exactly one:
    1. Ordinary: a managed kind with the role the area already has (viewers read; operators or admins change), as for groups and upstreams.
    2. Admin-only fields: a field inside an ordinary kind that only an admin may change, enforced by the server. An operator's change is 403 naming the field, and the UI marks the field admin: true (the T23.2 pattern).
    3. Guarded: the security gates and bootstrap settings below. Admin role only, with the guardrails in the next point.
  • Rules for every tier.
    • The file still wins over every UI value (ADR-040). A value set in a file is shown as "set by file" with the file's path, and an API write of it is 409 set_by_file. Removing it from the file uncovers the UI value, and the UI says so before that happens.
    • Role checks are on the server. The UI only hides or disables what the server would refuse.
    • A section that is node-local (NODE_LOCAL) becomes editable only through node_managed (T23.10), as an entry for the node it applies to (node/<node-id>/<kind>). Only that node applies it. An N−1 node ignores node_managed, so its own file stays in force.
    • A change that fails to apply keeps the previous configuration, and DNS keeps answering (CLU-004).
    • A change to auth-policy or the sign-in settings is refused (409 would_lock_out_admins) if no admin could still sign in afterwards (for example, TOTP made required for admins while no admin has enrolled).
  • Ordinary and admin-only kinds this ADR adds.
    • special: a shared singleton kind (/api/v1/special-names/default) for all [special] fields. Operators change it. ddr_name is admin-only, because it is one name for the whole cluster tied to every member's certificates (T24.12).
    • local: a shared singleton kind (/api/v1/local-settings/default) for device_domain, device_ttl, device_mdns, auto_ptr and default_ttl. Operators change it. hosts_files is a path and is guarded (below). device_inventory_addresses (DSC-012) is admin-only (T24.13, T25.16).
    • clients: a shared singleton kind that takes only mdns in M24, admin-only, because turning it on opens multicast listening on every member. mdns_port stays file-only and is shown read-only. The other [clients] fields join the kind in T27.9 under the operator role.
    • otlp: a node_managed kind for [telemetry.otlp] (endpoint, headers through header_refs), admin-only like sink (T23.11).
    • agents: a shared singleton kind for [agents]. Turning agents off (enabled = false) needs the operator role; turning them on needs an admin. The server compares the old and new values, so an operator's write that turns agents on is 403. No agent scope writes this kind, so an agent can neither switch itself on nor off. rate_per_minute and require_approval are admin-only (T27.6).
  • The guarded tier. Every guarded change:
    • is admin role only, checked on the server; agent tokens are refused whatever their scopes (403 agent_not_allowed, on the spec/13 §3 list), and there is no MCP tool, plan or config:write:* scope for it;
    • needs an interactive admin session; API tokens of any kind get 403 reauth_required with a hint naming the file or CLI step (as ADR-903 §8 does for passphrase backups);
    • has a dry run that says what the change does, which nodes it reaches and what it can break;
    • needs a typed confirmation: the request carries confirm, which must equal a phrase the dry run returns (the node ID and the setting, for example pi-a listen). The server checks it, so a script or a forged request can't skip it;
    • is audited as settings.guarded (who, node, setting, before and after with credentials redacted, the reason) and raises the one-off alert condition guarded_setting_changed;
    • is a node_managed entry on the node it applies to when the setting is node-local. A change to one node never reaches another.
  • Weakening changes. These are flagged in red as weakening security, and need a sign-in within the last 10 minutes (403 reauth_required, T23.9) on top of the confirmation:
    • adding a directory to secret_file_dirs;
    • turning on allow_secrets_over_http or allow_insecure_basic;
    • adding a trusted_proxies entry;
    • turning off the watchdog;
    • removing or downgrading TLS on the API or on a DoT/DoH/DoQ listener, or moving api.listen from loopback-only to a wider address;
    • in auth-policy (T27.6), removing a role from totp_required_roles.

Narrowing secret_file_dirs is not weakening, but the dry run lists every *_file reference the change would refuse.

  • Address and transport changes: confirm or roll back. Changes to [[listen]] (addresses, ports, TLS), api.listen, api.tls and api.trusted_proxies are applied as pending:
    • The node applies the change and starts a confirmation window, 120 s by default ([api] confirm_window_secs, 30 to 600, file-only).
    • The change is kept only if the same admin confirms it within the window, with a request that arrives through the new address and transport. For a DNS listener change, the confirmation also needs the node's own probe of the new listener to answer.
    • Otherwise the node restores the previous values, audits settings.guarded_rolled_back, and the UI says why.
    • A restart inside the window starts with the previous values. A pending change is held in memory on the target node only. The node_managed entry is written and replicated only when the change is confirmed. For a change to another node, the primary forwards the pending change, and the confirmation must reach that node's new address directly. The response to the change carries a single-use confirmToken, bound to the admin, node and change and valid for the window, so the admin need not sign in again on the new origin.
    • While a change is pending, the node keeps the previous API and DNS sockets bound alongside the new ones; the old ones close only when the change is confirmed, and stay if it rolls back. If a bind fails, nothing changes. The server refuses (409 would_disconnect_you) a change that would leave a node with no API listener or no DNS listener once confirmed, or that removes the API listener the request came in on in the same request that is meant to confirm it.
  • The secrets key. A key is never entered through the store it protects, or through any API body.
    • The UI shows the key's status: its source (environment, secrets_key_file, or secrets.key in the data directory), key_id, whether a previous key is configured, how many rows are still under it, and whether the store is locked or ephemeral.
    • Rotation is by pointing at a new key file the admin has already put on the node. The UI shows the steps (create the file with the format and permissions in docs/secrets.md, owned by the service user, mode 0600) and the offline alternative, wrendns secrets rotate-key with the node stopped. The admin then enters the new file's path. The server checks that the file exists, is a regular file with mode 0600 owned by the service user, and holds a valid key, without ever returning its content. It then writes a guarded entry for that node: secrets_previous_key_file = the current key's path, secrets_key_file = the new path. Re-encryption runs as at start-up (ops_014_previous_key_reencrypts_at_start, crash-safe). When no rows remain under the previous key, the UI offers to clear secrets_previous_key_file.
    • A key from the environment is shown as "set by environment" and can't be rotated from the UI.
  • Cluster init, join and bootstrap. These are explicit steps in a Cluster page wizard, each its own guarded change, never a field in a form:
    • "Make this node a primary" (cluster.init);
    • "Join a cluster" (cluster.join_url and the bootstrap secret). The secret is entered write-only, over HTTPS or loopback (the API-015 rule), used for that join and never stored. A failed join leaves the node as it was. The dry run says that the node's configuration will be replaced by the primary's;
    • "Leave the cluster";
    • [cluster.git] (repository, branch, path, authority). The dry run says when configuration authority moves to Git. The credentials stay T23.12's SecretField.
  • Other guarded settings.
    • node.* identity and storage (node ID, data directory): staged for the node's next restart and shown as "pending restart". A node ID change is refused while the node is a cluster member. A data-directory change never moves data unless the admin opts into Copy state (ADR-956 section 1(a): state.db and the default secrets.key only, never cluster/), and the dry run says what does not carry over.
    • The watchdog ([watchdog]): guarded; turning it off is weakening.
    • The file paths trust_anchors_file, signatures_file, hosts_files and [[zone]] file: admin-only, confined by T23.2's path rules (the denied prefixes, the key files, every credential file the node uses, secret_file_dirs). The dry run parses the file and reports counts and line numbers, never its content.
    • config_version is the schema version, not a choice. It is shown read-only and is the one setting with no control.

Alternatives rejected

  • Read-only display of the security and bootstrap settings, with the CLI step shown (the audit's recommendation): the owner chose admin controls.
  • Guarded changes for operators: each of these settings can lock people out, put credentials in clear, or replace a node's configuration.
  • Agent scopes for guarded changes: a plan's diff and an agent's transcript would carry the change, and a prompt injection could open the node.
  • Applying listener and API changes at once without a window: one typo locks every admin out until someone edits the file on the node.
  • Setting the key through the API or the secret store: the store would hold its own key, and the key would cross the network.
  • Confirmation in the UI only: a script or forged request would skip it. The phrase is checked by the server.

Consequences

  • Every setting but config_version has a UI control, and docs/ and help topics say which tier each one is in.
  • An admin can change listeners, TLS and proxies from the UI, and a mistake undoes itself within the window.
  • Guarded changes need two requests (the change and the confirmation), and weakening ones need a recent sign-in, so they can't be done from a long-idle session.
  • The files keep the last word, so a node can always be recovered by editing its file and restarting.
  • On installs whose file (or environment) sets a guarded value, its control shows "set by file" and the command to hand it to the UI (remove the key from the file and restart); the docs say which install bundles set which guarded values. Key rotation from the UI works only when the key path is not set by file or environment.
  • Adds the problem codes would_disconnect_you, would_lock_out_admins, the audit actions settings.guarded and settings.guarded_rolled_back, and the alert condition guarded_setting_changed. reauth_required comes from T23.9.
  • Amends ADR-040 (UI values for the sections above) and AGT-009 (the kill switch's role rule). T23.12's "[cluster.git] itself stays file-only" becomes a guarded wizard step (T27.16).
  • Tasks: T24.12 (special), T24.13 (local, clients mdns), T24.18 (Pi-hole import, admin-only), T25.16 (device_inventory_addresses), T23.11 (otlp), T27.6 (agents), T27.13 to T27.17 (the guarded tier).

Requirements AGT-009 API-015 API-901 CLU-004 DSC-012

Builds on ADR-040 ADR-901 ADR-903 ADR-904 ADR-956 ADR-957

Referenced by ADR-1006 ADR-1007 ADR-1008 ADR-1019 ADR-1053 ADR-918 ADR-940 ADR-956 ADR-957 ADR-958 ADR-959 ADR-977 ADR-984 ADR-999

ADR-915 Image size: optimize cold code for size, embed only the gzip UI, and ship only the tz database the code readsAccepted 2026-11-16FLTNFRNFR-001 (01, 00 §5) caps the compressed image at 15 MiB per architecture (deploy/image/size.py).

Notes

Status note (upstream sync, 2026-11-17): partly superseded by ADR-168 and ADR-169. The zoneinfo step described here (the fork's own tz database, shipped whole) is replaced by upstream's zic -b fat build, and the CA bundle that ADR-168 drops is no longer copied. The other cuts stand.

Context

NFR-001 (01, 00 §5) caps the compressed image at 15 MiB per architecture (deploy/image/size.py). At 177ef45 the amd64 image measured 15.13 MiB, up from 14.76 MiB at 412add6. The new code (secrets, credential rules, lists refresh, federated paths, ctl, OpenAPI schemas) grew the stripped binary by 0.91 MiB. The dependency and UI changes added almost nothing. The binary is already at opt-level = 3, fat LTO, one codegen unit and panic = "abort", so the remaining savings come from what is compiled at a lower opt-level and from what is embedded.

Decision

Reduce the image in the order of saving against risk, without dropping a feature and without touching the DNS hot path (02 §3):

  1. API and MCP code at opt-level = "s". [profile.release.package.wrendns-api] takes opt-level s; the rest of the workspace keeps opt-level 3. wrendns-api holds the handlers, OpenAPI and MCP code, which are cold next to the DNS path. Measured: amd64 15.13 to 14.58 MiB.
  2. Tz database without right/. The image ships the TZif zones that jiff reads (schedules, FLT-010), without the right/ leap-second zones, tzdata.zi, *.tab and leap* files. Measured: 14.58 to 14.39 MiB. Known effect: a schedule that names a right/... zone no longer resolves. Schedules use the ordinary zone names.
  3. Embed only the gzip of each text UI file. ui/scripts/postbuild.mjs removes the raw copy of a text file once its .gz is written. The binary embeds the .gz. A client that accepts gzip gets it as before. Any other client gets the same bytes inflated on the request, with miniz_oxide (already in the lock file, so no new package). Binary files (PNG, ICO, WOFF2) stay raw. Measured: 14.39 to 14.16 MiB. The postbuild script also resolves its dist path on Windows, where it failed before.

Final amd64 image: 14.16 MiB (headroom 0.84 MiB under NFR-001, 0.69 MiB under the 14.85 MiB target).

Consequences

  • The API and MCP handlers run as size-optimized code. The DNS path crates keep opt-level 3, and their code is unchanged, so make bench-smoke is not required by rule 4 for these changes. The API latency at opt-level s was not benchmarked here and is a follow-up.
  • A right/... zone name stops resolving in a schedule, with an error that names the zone. No feature is lost.
  • The UI's raw text files are no longer in ui/dist. Tools that read dist directly (for example vite preview) must use ui/dist/*.gz, or run npm run build without the postbuild step.
  • Not taken, recorded here for the owner: wrendns-config at opt-level s (about 0.2 MiB more, with per-query helpers in the policy path, so it needs a benchmark first), opt-level = "z" (about 0.5 MiB more, slower API handling), dropping the system CA bundle (0.12 MiB, needs its own ADR because the spec says the image ships one), and trimming serde code for Config (0.1 to 0.2 MiB, a refactor).

Requirements FLT-010 NFR-001

Builds on ADR-168 ADR-169

Referenced by ADR-916

ADR-916 The fork's image gate is 25 MiB compressed per architectureAccepted 2026-11-16OPS00 §5 and OPS-001 cap the image at 15 MiB compressed per architecture, from upstream's footprint priority.

Context

00 §5 and OPS-001 cap the image at 15 MiB compressed per architecture, from upstream's footprint priority. On 2026-11-16 the fork's merged work (the Pi-hole parity work, the upstream sync and M23 wave 1, about 17,500 lines) took amd64 from 14.76 to 15.13 MiB. Three cuts that drop nothing brought it back under (ADR-915), but M25 (an SNMP codec, aes, an XML parser), M26 (the map UI) and M27 (UI for every setting) will add more. The owner runs Pi 4/5 and Linux hosts, where 25 MiB pulls in seconds. Memory (RSS) is the budget that limits small hosts, and it is unchanged (00 §5: idle ≤ 20 MiB, ≤ 64 MiB loaded).

Decision

the owner chose to raise the fork's gate to 25 MiB compressed per architecture (deploy/image/size.py LIMIT, make image-all, the image workflow). Upstream's 15 MiB stays upstream's. Every task still reports its image delta (deploy/image/size.py --oci) in its Done note, so growth stays visible, and a milestone that adds more than 2 MiB says why. ADR-915's cuts are kept. The RSS budgets, the FROM scratch image, the static musl binary and the multi-arch matrix are unchanged.

Alternatives rejected

keeping 15 MiB (constant trimming work for little gain on small hosts); 20 MiB (less room for M25–M27); no gate at all (growth goes unnoticed).

Consequences

Pi Zero-class devices, OpenWrt or OPNsense packages (upstream #12, #49) are a poorer fit. A change from upstream that relies on the 15 MiB headroom needs no special handling, since the fork's gate is looser. On an upstream sync, keep LIMIT at 25 MiB.

Requirements OPS-001

Builds on ADR-915

Referenced by ADR-1020 ADR-1030 ADR-1031 ADR-958 ADR-959 ADR-994

ADR-917 Replication details for stored secrets: orphans by epoch, a joining node's hand-over, the shadow table, and the reverse healAccepted 2026-11-17CLUADR-903 §6 fixes what replicates (stamped rows over the cluster channel, tombstones, orphans, re-encryption under each member's key, the reverse heal).

Context

ADR-903 §6 fixes what replicates (stamped rows over the cluster channel, tombstones, orphans, re-encryption under each member's key, the reverse heal). Building it left points it doesn't settle, which T23.5 had to decide.

Decision

  1. Orphans without a base stamp. A live cluster row that a member holds, that the current primary doesn't list, and whose stamp's epoch is older than the primary's, is an orphan: kept, flagged, never used, never deleted. ADR-903 §6 judges "stamped in an epoch after the new primary's base". The base isn't needed: the primary lists every cluster row it holds, so anything from an older epoch it doesn't list is one it never had, or its own orphan, and both are unusable. This judges more rows than the base rule would, and only ever toward "not used".
  2. A primary's orphans are not shared. The primary's export leaves out its own orphan rows, and its head is computed over the rows it shares, so a member's head and the primary's agree when both hold the same shared rows.
  3. A stale row yields to the primary's listing. A listed name whose row a member holds from an older epoch takes the primary's row, whatever the stamps say; the displaced row goes to the shadow table, not dropped.
  4. The shadow table (migration 12, secrets_shadow, same columns as secrets; migration 13 keys it by (name, origin)). It holds one slot per name and origin: a local row a cluster row displaced, and a cluster row a newer listing displaced (a stale copy under point 3, or a tombstone that a later live listing replaces under point 10). A tombstone that stays a conflict is not displaced: it stays the row in secrets. A displacement never replaces a local shadow. Shadows are never used, appear in status as shadows, are sealed under the node key like the rows (rotation, the start-time re-encryption and the backup strip cover them), and come back as the local row when the cluster's rows are purged. The purge drops the cluster shadows. Reverse heal and heal-as-replica refuse while a local shadow exists: it is this node's own value, and it's recovered by hand (docs/secrets.md). A heal refuses while an orphan it can still read exists, and drops one it can't read (point 15).
  5. Joining. ADR-903 §6 says a standalone node's rows "become cluster rows on the primary" at join. Implemented as secrets.adopt: a joining full member offers its own rows once per primary epoch; the primary takes the names it doesn't hold, stamped in its epoch, and reports the rest as conflicts. At cluster init the primary's own standalone rows become cluster rows in place, once.
  6. Heartbeats. The fields are tags 33 to 38 of Heartbeat. secrets_head is the node's own head; secrets_applied is the primary head the node last verified and applied (its own head on the primary). Nodes without the tags read as "not reported" and are never fetched from.
  7. Reverse heal is all-or-nothing. A locked primary whose rows are all the cluster's is refilled only from a replica that holds every one of its rows at the same stamp (tombstones included). A partial answer changes nothing.
  8. Removal purges. The sync task purges a member's cluster rows once the cluster lists it as removed (removed.json), and the purge is audited as secrets.purge. A full member has no leave path (only resolver pods leave), so none purges on leave.
  9. Where the tests are. The seeded partition and failover schedules are in wrendns's secrets module, over the store, not in wrendns-cluster/tests/sim.rs (the election simulator), because the replicated state is the store's. The two-node tests run over the real mTLS channel in-process (secrets_api_tests), and the two-process test runs the built binary (crates/wrendns/tests/secrets_cluster.rs).
  10. A listing doesn't undo a deletion, unless it's a later write. A cluster tombstone of an older epoch that a newer primary lists as live stays a tombstone row on the replica, and the name is reported as a conflict (Applied.conflicts) and audited as secret.conflict, when the listed row's stamp is older than the tombstone's: a value the deletion superseded, held by a primary that never had the deletion. A listing stamped after the tombstone is a later write, possibly a re-creation in a later epoch: it is taken, and the tombstone goes to the cluster shadow slot (point 4). The stamps decide, not the epochs alone: checking the epoch alone kept a secret created again after an epoch change from ever reaching a replica (review N1). A same-epoch tombstone still yields to a higher stamp, as before. Before this point, the listing brought the revoked value back silently (review M4).
  11. An emergency primary's answer is not authoritative. FetchAns.authoritative is false for an emergency primary (absent means true, so an older primary's answer reads as authoritative). A replica applies a non-authoritative answer by stamp only: it fills a name where it holds none, or an older cluster row, and displaces nothing and orphans nothing. An emergency primary's sync pass does no hand-over, refill or key replacement (ADR-903 section 4; review M1).
  12. Hand-over is audited and never re-creates a name. Each name the primary takes is audited as secret.adopt, and each refusal as secret.adopt_conflict, with the joining peer. A name the cluster holds, live or deleted, is a conflict; a row the primary can't accept (an unknown kind, an invalid value) is a conflict rather than a silent skip (review M3). Gating adoption to one epoch of the joiner's join is not done: the registry records no join epoch, so it is open for the owner.
  13. A replica answers the reverse heal for the current primary. A replica's registry lists only itself, so the primary's registry check can't pass there. A replica answers secrets.fetch only for the primary of the highest epoch, which is always a full member; a primary answers only full members (!ephemeral && !witness && !removed). Found by the two-node reverse heal test (review M5).
  14. Pulls are checked against the heartbeat. A replica applies an answer only when its head is the head the heartbeat announced and its primary is in the heartbeat's epoch. An answer that runs ahead of the heartbeat is not backed off: the heartbeat is a pass behind the answer, so the next pass (a few seconds later) asks again, nothing is applied, and a run of such answers is logged at warn from the third (review L1; the code does this from 2026-11-17). A failed pull is backed off as before.
  15. A heal drops what no key can read. A heal (heal-as-replica, or the primary's reverse heal) drops an orphan this node can't decrypt, with the other rows it can't read, and refuses while an orphan it can read exists: an orphan is no replica's row (the cluster doesn't list it, and an older epoch stamped it), so no fetch restores it, and keeping it locked the node for good when it had lost its key (review N2). The heal's audit record secrets.heal names the dropped orphans and gives the counts of rows and cluster shadows cleared (names and counts, never values), and the log says the same. A local shadow still refuses a heal (point 4). Recovery of a locked node whose local shadow is the blocker is the documented step in docs/secrets.md.

Consequences

No new crate. Two migrations (12 and 13). Everything the sync does to the store, the registry, the credentials or a file runs on a blocking thread (tick), so the runtime that serves DNS never waits on it (CLU-004; review M2); nothing reads the manifest, so pins and canary bakes don't gate replication. A heartbeat grows by a few dozen bytes when a node holds secrets. Plaintext intermediates on the channel are only partly zeroized: the answer and hand-over buffers cross the channel as Vec<u8> (review L2, partly).

Alternatives rejected

a base-stamp orphan rule (it needs the primary to record a base at promotion, and it misses rows the base rule would call fresh); deleting orphans (a row must never vanish without a tombstone); the shadow row in secrets under a second name (it breaks the one-row-per-name invariant every reader relies on).

Status

Accepted 2026-11-17. The owner accepted every ADR for the overnight run. Points 1 and 5 deviate from ADR-903 §6's wording. Points 10, 14 and 15 are the review fixes of 2026-11-17 (N1 to N3 of the second review), and point 10 supersedes the epoch-only rule of its first form.

Requirements CLU-004

Builds on ADR-903

Referenced by ADR-1005 ADR-1021 ADR-1027 ADR-1045 ADR-1051

ADR-918 Shared settings sections: field-level file precedence, what a request may leave out, and admin-only fieldsAccepted 2026-11-17CLUT24.12 ([special]) and T24.13 ([local], and [clients] with mdns only) make three one-entry sections changeable from the UI and API under ADR-914's tiers.

Context

T24.12 ([special]) and T24.13 ([local], and [clients] with mdns only) make three one-entry sections changeable from the UI and API under ADR-914's tiers. The one-entry kinds so far (rate limit, exclusions, simulation) replace the file's whole section. For these, that would let an API value override a field the files set, which ADR-040 and ADR-914 forbid. ADR-914 didn't settle three details: which fields the files win over, what a request that leaves out a file-set field means, and what an empty device_domain means.

Decision

  • Files win field by field. The loader records the dotted keys (special.ddr_name, local.device_domain, clients.mdns) that the configuration files and environment set explicitly (Config.file_set). At merge time a stored field whose key is in that set is ignored, so the file's value applies. The UI shows it as "set by file".
  • Requests. A PUT stores every editable field (fields left out take their defaults, as the other one-entry kinds do), except a file-set field left out, which keeps the file's value (as a credential does under ADR-903 §2). A PUT that sets a file-set field to another value is 409 set_by_file naming the field. Setting it to the file's own value changes nothing and is accepted.
  • Read-only fields. hosts_files and mdns_port are shown in the entry and can't be set here: sending back the value the entry shows is accepted, another value is refused (422, naming the field).
  • device_domain. An empty string or null means no device names (off). It isn't an invalid domain.
  • Admin-only fields (special.ddr_name, clients.mdns). A change to one is checked on the server: an agent's is 403 agent_not_allowed; an operator's is 403 naming the field; a change forwarded from a node too old to say who made it is 409 upgrade_required. An agent can't write [clients] at all: no agent scope reaches /api/v1/clients-settings/default.
  • Plans. The MCP plans for these sections fill the fields left out from the entry as it is now, as the other plans do.

Alternatives rejected

  • A stored partial section laid over the file: a file change would then leave an old API value hidden under a field the file no longer sets. Full sections are stored instead.
  • Silently ignoring a file-set field in a request: the UI would show a value it can't set. A 409 naming the field says so.
  • Treating device_domain = "" as invalid: the UI and agents both need a way to turn names off with the same form.

Consequences

  • ConfigEntry gains setByFile and answering (optional fields, so an older node's answers still read). Explanation gains special (optional).
  • Environment-set keys count as file-set, so the UI says "set by file" for them too. A separate "set by environment" label is a follow-up.
  • A file change takes effect on the next reload. A stored value for a field the file now sets is ignored at once, and kept in state.db until someone reverts it.
  • [clients] mdns takes effect after a restart (H1). The mDNS listener starts once, at start-up (restart_only_changes lists it). A change is stored at once, but the dry run and the write say it takes a restart on every node, and device names follow mDNS only while the listener the node started with runs (device_dns::run takes the start-up value). Starting and stopping the listener on reload is a follow-up.
  • Set-by-file marks come from the files (M2). The API marks a field from file.file_set (the loaded files), not from the configuration in effect: a merged configuration doesn't carry file_set (it isn't serialized). plan_settings checks against the files too, so the marks and the refusals agree.
  • Known divergence on a promoted primary (M2, not fixed here). overlay lays the stored section over the files, skipping only the fields the node's own files set. On a promoted primary, a field the files set can keep the value the cluster version stored, not the node's own file value, so that node's effective value can differ from its file (the UI still marks the field "set by file"). The files-win rule is therefore not yet exact on that path. Fixing it (drop stored values for file-set keys when a node is promoted, or carry the node's own file_set through overlay) is a follow-up, and the next change to these sections on a promoted primary must not rely on the stored value.
  • Version gate (M3, CLU-010). The settings kinds go only to a primary at 0.8.0 or later (SETTINGS_KINDS_SINCE). An older primary gets 409 upgrade_required from the replica before anything is forwarded, not an opaque failure.

Requirements CLU-010

Builds on ADR-040 ADR-903 ADR-914

Referenced by ADR-956

ADR-919 Secret fields in the UI: save writes the secret first, clear unlinks, and a file the configuration sets stays read-onlyAccepted 2026-11-17T23.6 adds the Integrations &amp; secrets page and SecretField, the one control every credential is entered through (ADR-903 §9).

Context

T23.6 adds the Integrations & secrets page and SecretField, the one control every credential is entered through (ADR-903 §9). The API has two rules that shape the form: a *_ref naming an unset secret is refused (422 secret_missing), and a delete of a secret a field still names is refused (409 secret_in_use). So a form can't save an entry and its new secret in one request, and can't delete a secret through an entry that still names it.

Decision

  • Save writes the secret at once. "Save secret" stores the value (PUT /api/v1/secrets/{name}) before the entry is applied, then sets the entry's *_ref in the draft. The stored value exists even if the entry is never applied; the Integrations & secrets page lists it as unused.
  • Clear unlinks; it doesn't delete. "Clear" removes the reference from the draft, and the entry stops using the secret when it is applied. The state reads "will be cleared" until then, and Undo restores the reference. The stored value stays until someone deletes it on the Integrations & secrets page: a delete before the apply would be refused with 409 secret_in_use, and another entry may use the same secret.
  • Names. A new secret is named <kind>.<entry>.<field>: for an alert destination's token, alert.<entry>.token, with the entry's name lowercased and slugged (runs of other characters become -) and cut so the whole name is at most 63 characters. An entry with no usable name has no default, so the field waits for a name and alert..token is never proposed. The name is editable before it is saved.
  • An existing secret is offered, not deleted. An entry whose default name is already stored shows "already stored" with Use it (which links the entry) and Replace; it never shows Delete. On the Integrations & secrets page a typed name that is stored is a replacement: the name stays editable and the value goes under it.
  • A typed value holds Check and Apply. A value typed into a field and neither saved nor discarded would otherwise be dropped without a word. The form disables Check and Apply until it is saved (Save secret) or discarded (Discard).
  • Writes carry the head. Every secret write sends the secrets head's etag, as the page last read it, as If-Match (ADR-903 §2). A head that has moved is refused with 412: the page says so and reads the list again.
  • Unreadable and inline. A stored secret this node can't read shows "can't read it" with Replace. A *_file the node can't read shows the reason beside "set by file". A value the file sets inline is read-only ("set inline").
  • Set by file. A *_file the configuration sets is shown read-only with its path and, when this node can judge it, whether it's readable; the API refuses changes to it (ADR-903 §2). A *_file set through the API (not by the files) is not read-only: an admin's stored secret replaces it in the draft, and Remove the path drops it on an entry with no stored secret. A *_ref the files name is not reported as set by the file: set_by_file lists the inline value and the *_file path, as the server has always done, so an admin can still change the reference.
  • Plain HTTP. The field explains a 403 insecure_transport (turn on HTTPS, or [api] allow_secrets_over_http), and warns before the save when the page itself is on plain HTTP from another host. The page can't tell whether the node allows plain HTTP for secrets, so the warning says the server may refuse.
  • No show toggle, no prefill. The value input is a password field with autocomplete="new-password" and password-manager ignore attributes. ADR-903 §9 says autocomplete="off"; new-password is chosen because it tells a password manager that this is a new credential to store, not a login to fill, which is what the field takes; the owner should confirm it while this ADR is Proposed. After a save, a failure or a replacement the input is empty; the value is never returned by any API, so a page can't show it again.
  • Entries report file-set credentials. ConfigEntry.setByFile lists the credential fields the configuration files set for an entry (token_file, an inline secret), for file-only entries too; before this it was empty for them, so a file's token looked editable.

Alternatives rejected

  • Deleting the secret when it is cleared: refused while the entry still names it, and a second entry may use it.
  • Saving the entry and the secret in one request: the API takes them separately (the secret store has its own rules, ADR-903 §4), and a failed entry save would leave an unlinked value.
  • A reveal or copy button: it would contradict write-only (ADR-903 §9).

Consequences

  • The form makes two requests for a new secret (the value, then the entry); a cancelled drawer leaves an unused secret, which the Integrations & secrets page shows.
  • SecretField is reusable: the routers (T23.8) and the other forms (T24.16) pass the draft's *_ref, the *_file path and the role, and get the same states.
  • Operators see status only: the Integrations & secrets tab and the field show the same states, with the controls left out.
  • The image gate is unaffected unless the bundle grows past the budget (400 KiB gzipped; now about 252 KiB).

Builds on ADR-903

ADR-921 Router integrations as a managed kind: admin-only, file-read-only, named secrets, no file paths through the APIAccepted 2026-11-17APIT23.7 makes [[router]] a kind the API and UI change (ADR-903 §2, §7; API-016).

Context

T23.7 makes [[router]] a kind the API and UI change (ADR-903 §2, §7; API-016). ADR-903 §2 says router follows ADR-040 (names the files define are read-only through the API) and §9 says every credential is entered through SecretField. It doesn't settle three details: who may write a router, whether an API body may name a file path, and how a certificate is entered, since tls_ca is a file and ADR-903 §1 says the router's CA "becomes an inline tls_ca_pem (T23.8)" without a field.

Decision

  • Admin only. Creating, changing, or removing a router is an admin's (403 for operators; agents never, by their forbidden list and scopes). A forwarded write without a role (an older node) is 409 upgrade_required, as credential writes are (ADR-903 §4).
  • Files win. A name the files define is read-only here: PUT and DELETE are 409 set_by_file (ADR-040). The files' entry shows as source: file.
  • Named secrets only. api_key_ref, api_secret_ref, and password_ref name stored secrets (422 secret_missing when none has the name). A body that names api_key_file, api_secret_file, password_file, or tls_ca is 422 invalid_config: the API takes no file paths for a router, because a path the API can set is a path an admin can point at any readable file (ADR-903 §4, the path rules). The files keep their paths.
  • The certificate as text. tls_ca_pem holds PEM certificates (16 KiB at most; each must decode, and at least one is required; exclusive with tls_ca). The form saves the chain the console presents (its certificate and the CAs it sends), so a console signed by a private CA is trusted with its CA, and nothing else is trusted for that router: a router client trusts those certificates in its settings, not the public roots (ADR-120). Review of T23.7: a bare marker or a body that isn't base64 is refused.
  • Ephemeral pods read no router (ADR-903 §7 and the Helm resolver pods' note in ADR-120): the controller, or the primary for a stored credential, reads them.

Consequences

  • A router made in the UI can't use a file: an operator who wants a file adds it to the configuration file (the UI says so).
  • tls_insecure_skip_verify is not offered by the UI and is still file-only.
  • The MCP surface gets list_routers (read-only). No MCP tool, and no agent scope, writes or checks a router (ADR-903 §5).

Requirements API-016

Builds on ADR-040 ADR-120 ADR-903

Referenced by ADR-1019 ADR-967 ADR-984

ADR-922 Router hot reload: the live list, per-router state, debounced reads, and checks that never send a stored key to a new addressAccepted 2026-11-17CLUrouters::run took the [[router]] list at start-up and returned at once when it was empty (T8.2).

Context

routers::run took the [[router]] list at start-up and returned at once when it was empty (T8.2). T23.7 needs a router added, changed, or removed through the API to take effect without a restart, with the others' names kept (CLU-004, 02 §8), and T23.8 needs a check of a draft that reads a router once.

Decision

  • The live list. The poll loop reads Sources.config each round. A reload (any node's configuration change, or a secret the store changes) wakes it at once (Sources.routers_changed).
  • Per-router state. A router keeps its last answer while its settings are unchanged. A changed router is read again, debounced to at least 5 s after its last read; it keeps its last names until that read succeeds, unless its address or kind changed (another device: its names go at once), and its status reads waiting until then (review of T23.7). A removed router drops its answer, so its leases go with the next round. A router whose stored credential may have changed is read again, debounced the same way. The store is not asked on the loop (a lock held at start-up delayed the runtime's workers).
  • Failure isolation. Each read runs on its own task and reports through a channel. A router that fails (refused, timed out, malformed, oversized) keeps its last answer and is retried within 15 s; the others are not delayed. DNS is never on this path.
  • Who reads. A stored credential is read on the primary or a standalone node only; a replica gets its names through the peer leases (ADR-125). A file credential is read as before on every full member, and a resolver pod reads nothing.
  • Status. Each router's last read (state, time, error without any password, devices, networks, and where it's read) is kept for GET /api/v1/routers.
  • Checks. POST /api/v1/checks/router reads a draft once and saves nothing. It sends a stored credential only where it was saved for: the saved router's own secret, when the draft's address and TLS settings equal the saved router's, or the secret named for this router (<kind>.<name>.<field>) when either no router is saved under the draft's name (a new router) or the draft's address and TLS settings equal the saved router's, and no other entry of any kind (router, alert destination, sink, OIDC provider, Git source) uses it. Any other reference is dropped; the check runs without it and says so (credentialSent: false) (review of T23.8; review NEW-1 and NEW-2: a saved router's named key never goes to a new address, and a secret another kind uses is never sent for a router's name). Both checks are admin-only and refused to agents. POST /api/v1/checks/router-certificate makes one TLS handshake and returns the names, fingerprint, and PEM; it trusts nothing, and the PEM is saved only by the form.

Consequences

  • A stored key never goes to an address the admin didn't save it for, even by an admin's check.
  • Residual (review NEW-1): a new router that reuses the name of a deleted router can have that router's leftover named secret sent to its new address, since no saved entry under the name records the old address. Deleting a router does not remove its secret; the admin can delete the secret itself.
  • A router whose console renews its certificate fails until the new certificate is saved (ADR-120).
  • The poll loop, its reads, and its failures are tested with local fake routers only (HTTP, and TLS on 127.0.0.1).

Requirements CLU-004

Builds on ADR-120 ADR-125

ADR-923 Source classes for the sources ADR-910 leaves open: Home Assistant, mDNS, configured namesAccepted 2026-11-17ADR-910 sets the precedence classes for UniFi and OPNsense (class 1), the neighbour table (class 2), SNMP ARP (class 3), imports (class 4) and UniFi history (class 5).

Context

ADR-910 sets the precedence classes for UniFi and OPNsense (class 1), the neighbour table (class 2), SNMP ARP (class 3), imports (class 4) and UniFi history (class 5). It does not place Home Assistant, passive mDNS, SNMP identity or the configured client name. The first draft of this ADR put Home Assistant and mDNS at class 2. The T25.1 review (2026-11-17) found that an unauthenticated mDNS announcement would then make its address an SNMP destination (ADR-907), and that an identity answer would back its own eligibility.

Decision

  • Home Assistant trackers and passive mDNS announcements carry their addresses as claims with no class. They never make an address current, never make it an SNMP destination (ADR-907), and never win a conflict. They sort after the classed bindings, with imports. Both come from the device or its tracker, not from a router's own table.
  • SNMP identity (sysName and printer names) and the configured client name ([[client]]) carry no class. SNMP identity carries names only. The configured name attaches to entries and never creates one. An SNMP ARP binding is class 3.
  • A claim with no MAC whose address a MAC entry holds as a current binding attaches to that entry, with its names and ports. Any other claim with no MAC goes to the IP-only class (ADR-910).
  • Name ranks follow ADR-910 exactly. A name's label is labelled with its source for ranks 6 and 7. A name replaces the earlier name of the same kind from the same origin (the [[router]] for router aliases), so a rename shows.
  • Conflicts: the newest class 1–3 claim wins the address. A class 4, class 5 or unclassed claim never removes a current binding and raises no conflict: it is a claim, not a current owner. A current claim on an address another MAC entry holds as current flags both entries ip_conflict, with a hold of 900 seconds from that claim (conflict_until). A competing claim refreshes the hold, and the flag clears only after the hold has passed (the sweep checks the hold, not the owner count, because the displaced binding is gone from the address at once). IP-only entries take no part in conflicts.
  • A claim with no MAC attaches to the MAC entry that holds its address as a current binding, or failing that, to the MAC entry that holds it from the same source (so a device's own mDNS record does not split off an IP-only duplicate when its router binding expires).
  • Each source keeps its own record of an address (per address, source and import). A source refreshes only its own record, so another source's claim on the same address never keeps a stale binding alive (ADR-924).
  • A randomised MAC (the locally administered bit set) gets randomized and never raises new_device.

Alternatives rejected

Home Assistant at class 1 (its trackers come from a template, not a router's table, so a stale tracker would outrank a live neighbour entry). Home Assistant and mDNS at class 2 (the first draft: an unauthenticated mDNS announcement would make its address SNMP-eligible).

Consequences

a device seen by Home Assistant and by the neighbour table has one current address, the neighbour's, and Home Assistant's stays a claim. The address that ADR-910's DNS opt-in (DSC-012) may use therefore comes only from classes 2 and 3; an mDNS-only address never supplies one. The owner confirms the classes at the T25.0 review. Until then this conservative choice stands.

Requirements DSC-012

Builds on ADR-907 ADR-910 ADR-924

Referenced by ADR-1003 ADR-1004 ADR-925

ADR-924 Inventory retention and expiry: two missed polls, per-entry caps, and the import rulesAccepted 2026-11-17ADR-910 fixes the caps and says a host counts as absent only after two polls in a row miss it, without saying how a poll interval maps to time, or what an entry with no address left should do.

Context

ADR-910 fixes the caps and says a host counts as absent only after two polls in a row miss it, without saying how a poll interval maps to time, or what an entry with no address left should do.

Decision

  • A source's binding expires when seen + max_age < now. max_age is twice the source's poll interval: 120 s for the neighbour table (polled every 60 s), 900 s for the routers and mDNS (their cadence is "every few minutes", devices.rs).
  • An entry with no address, no import, and no change for retention_days (7) is removed. An entry with only a name and no address stays until that retention passes; names are not expired separately.
  • Imports: an import past [discovery.import] retention_days (30) is removed with all its rows. Deleting an import removes its bindings, clears its ports when no other import holds the entry, drops import-only names, and removes entries left empty.
  • Caps: the oldest MAC entry (by last_seen) goes at 4,096, the oldest IP-only entry at 1,024, and the oldest import goes first when the import count reaches 16 or the import rows pass 8,192. A single import over 4,096 rows is refused.
  • A conflict flag clears on the sweep once no two entries claim the address.
  • The import ports (open TCP) are kept on the entry, sorted and capped at 16. They are cleared when the last import holding the entry goes.
  • Each source's record of an address is its own (per address, source and import). A claim from another source never refreshes it, so an import cannot keep a stale neighbour binding alive (T25.1 review).
  • Mutes are capped at 1,024 (the oldest goes first) and pruned by the sweep for entries that are gone or for mutes that have expired.
  • A stored inventory.json is checked on load: an import bit past 15 or a bit no kept import holds is dropped with its bindings and ports, and the 8,192-row cap is applied again. A file this version cannot read (a corrupt file, or another version) is moved to inventory.json.bad and the inventory starts empty, so the owner's data is kept, not overwritten.

Alternatives rejected

a fixed per-source TTL with no link to the poll interval (it would drop hosts on a slow router poll); per-row import expiry (more state for the same effect).

Consequences

a host the neighbour table drops for two minutes loses its neighbour binding, and it keeps its other bindings. A router that is slow to answer keeps its binding for 15 minutes.

Builds on ADR-910

Referenced by ADR-1004 ADR-1005 ADR-1024 ADR-923 ADR-942

ADR-925 Inventory thread and its inputs before [discovery]: off by default, the Home Assistant feed deferredAccepted 2026-11-17T25.1 builds the inventory thread (wrendns-inventory) and its read-only sources.

Context

T25.1 builds the inventory thread (wrendns-inventory) and its read-only sources. The switch that starts them is [discovery], which is T25.2. Nothing in the server reads Home Assistant's raw answer after routers.rs folds it into the lease view, and the owner has not yet decided how a discovery node is chosen.

Decision

  • The thread's spawn exists and is tested through tick, but no startup path calls it. T25.2 wires it behind [discovery] enabled (default false) and the designated-node rule (DSC-001). discovery/mod.rs allows dead code for that reason.
  • Sources wired in T25.1: the filtered kernel neighbour table, the routers' lease view (devices::Leases, class 1, a lease with a router name), and the passive mDNS lease view (a claim with no class, ADR-923; IP-only when no MAC, and attached to the MAC entry that holds the address otherwise). Home Assistant's named devices are a pure function (sources::ha_observations, tested on fixtures). Its live feed needs routers.rs to keep the last raw answer, and that stays Open until T25.10 (DSC-009) reads Home Assistant's registry anyway.
  • inventory_merge is a fuzz target that includes crates/wrendns/src/discovery/inventory.rs by path, so the fuzzer runs the same source the server builds, without a dependency on the binary crate.

Alternatives rejected

starting the thread now (an off-by-default feature would then run on every node); a separate wrendns-inventory crate (the module needs devices and routers, which live in the binary crate, and the merge is small).

Consequences

the inventory is not visible to any API until T25.12. Nothing in wrendns reads inventory.json yet. The Home Assistant feed is Open.

Requirements DSC-001 DSC-009

Builds on ADR-923

ADR-926 Credential rules in the forms: judged from the saved entry, and a draft that needs an admin is heldAccepted 2026-11-17APIT24.16 puts ADR-903 §4's admin rules in every form (API-014).

Context

T24.16 puts ADR-903 §4's admin rules in every form (API-014). The server already refuses each change; the forms must show the owner who may make it and why, and must not let an operator fill in a change that will be refused. Two details are open: a form's lock can only use what is saved, and the upstream headers and arguments have no field in the form until T27.3.

Decision

  1. Locks are judged from the saved entry. A field's admin rule reads the entry as it was read, and the credential paths it keeps (ConfigEntry.redacted: headers, arguments, a password in an address). A draft's own value doesn't make a field read-only, since a field that locks while it's being typed can't be corrected. A draft that switches to a program address (exec://, unix://), or changes a saved program entry's arguments, instead holds Check and Apply with the reason (ConfigEditor adminOnly, which is given the saved entry, or none for a new one), and the server refuses it too. A saved program entry changed only in its weight, timeout or other fields is not held.
  2. The rules as the forms apply them.
    • Upstreams: url is an admin's when the entry keeps a credential or runs a program (saved); tls_server_name when it keeps one. "Keeps a credential" is the server's holds_credential: a redacted path, a credential file (tls_client_key), or a stored reference (*_ref, *_refs).
    • Alerts: type is an admin's when the destination holds a credential (the existing url, tls_ca and secret rules are unchanged).
    • Names on my network, forwards: a server that is exec:// or unix:// is an admin's, and Save is off for an operator.
    • Every kept credential shows the badge "kept: re-enter to change" in its row.
  3. Headers and arguments. They have no field in the upstream form until T27.3. A change of the address that the server refuses for a kept header says which field, and that the form can't enter it: use wrendns ctl or the configuration file. No headers field is added here, so the message is the resolution this task owes (T24.16's "or the message above").

Consequences

  • A form can be stale about a rule the server adds later. The server stays the authority: every refusal still comes back as a problem code, and its message reads as a sentence (ADR-927).
  • An operator who pastes an exec:// address sees the reason and a disabled Save, not a refusal after the fact.

Requirements API-014

Builds on ADR-903 ADR-927

ADR-927 Problem codes read as sentences in the UI; the server's detail stays on the errorAccepted 2026-11-17T24.16 asks that ApiError give readable messages for the credential codes (path_not_allowed, set_by_file, credential_reentry_required, upgrade_required, secret_missing, secret_in_use, secrets_locked, insecure_transport, lists_not_here).

Context

T24.16 asks that ApiError give readable messages for the credential codes (path_not_allowed, set_by_file, credential_reentry_required, upgrade_required, secret_missing, secret_in_use, secrets_locked, insecure_transport, lists_not_here). Until now ApiError.message was the server's detail, which names the field well but reads as a log line. Two places (SecretField, SecretsPanel) matched the detail's text to recognise a secret that is in use elsewhere.

Decision

  1. The problem code is the contract. ui/src/lib/api.ts maps each listed code to a sentence, which becomes ApiError.message. The server's text stays on ApiError.detail, unchanged.
  2. A code with no sentence reads as the server's detail, as before.
  3. Recognition of a case by its text uses detail, never the sentence (secret_in_use "can't be read now").
  4. The field a detail names (its first backquoted token, never the <redacted> marker) is quoted in the sentence, so the owner sees which setting to change. A credential_reentry_required sentence follows the detail's case: a check never uses a stored value (Test it), no stored value to keep, or the destination changed. A header or an argument's hint is not shown beside its sentence, since the sentence already says how to enter it.
  5. The Routers page's credential input (CredentialInput.svelte, T23.8's open item) is replaced by SecretField and removed. Its Playwright tests use the field's data-mode and its save button.

Consequences

  • A sentence is text the owner reads, so changing one is a UI change: the Playwright test api_015 errors read as sentences names each code and the words it must show.
  • The sentences are in English only, as the rest of the UI is.

Referenced by ADR-926

ADR-928 [discovery] as a managed kind: admin-only, no agent scope, and the first write waits for N−1 membersAccepted 2026-11-17CLUADR-907 makes [discovery] a shared section written through the config entries API as the managed kind discovery, admin-only, with dry run, If-Match and audit, and says the first write waits while any member runs N−1 (CLU-010).

Context

ADR-907 makes [discovery] a shared section written through the config entries API as the managed kind discovery, admin-only, with dry run, If-Match and audit, and says the first write waits while any member runs N−1 (CLU-010). It doesn't say where the kind lives, what the version threshold is, or whether later writes wait too.

Decision

  • The kind is discovery at /api/v1/discovery-settings/default. The path is -settings because /api/v1/discovery is the inventory's own read (T25.12).
  • Every field is admin-only (settings_kinds::admin_keys): an operator's change is 403 naming the field, and an agent is 403 (agent_not_allowed). The auth table refuses the whole /api/v1/discovery prefix to agents until discovery:read exists.
  • The first write (none stored through the API yet) is refused with 409 members_too_old while any member reports a version older than DISCOVERY_SINCE = 0.8.0, or one that can't be read. Later writes don't wait: the members already took the first.
  • A forwarded write to a primary older than 0.8.0 is refused with 409 upgrade_required (as the other settings kinds are, CLU-010).
  • Review of T25.2 (2026-11-17): an unreleased build reports dev, which no gate can read. This node's own dev counts as the crate's version (forward::gate_version), because the code it runs knows every kind it has, so a dev cluster's own node is not "too old". Another node's dev stays unreadable and is refused. Release builds carry their version (CI stamps it), so they pass.
  • DISCOVERY_SINCE is 0.8.0, the release that carries the section, the same as SETTINGS_KINDS_SINCE. The gate is tested with the real build version through the real route (dsc_001_current_build_passes_the_gate).

Alternatives rejected

waiting on every write (a member that is upgraded and back would still need the first write to be accepted, so this only added a second wait); the threshold at 0.9.0 (the workspace is 0.8.0 until it ships, so every node, the node itself included, counted as too old and the first write could never succeed); a feature flag advertised by each member (it would need a new field in the membership record; the version already says what a member knows, and the gate is the same check the other kinds make).

Consequences

DISCOVERY_SINCE moves with the release that carries this section. The first write on a cluster with an older member is refused until that member is upgraded, which the UI says.

Requirements CLU-010

Builds on ADR-907

Referenced by ADR-1001 ADR-1005 ADR-948

ADR-929 Discovery worker protocol v1, its debug-only fault jobs, and the status API before T25.12Accepted 2026-11-17CLUT25.3 builds the worker processes of ADR-908 before the SNMP codec (T25.4) and the import parser (T25.11) exist.

Context

T25.3 builds the worker processes of ADR-908 before the SNMP codec (T25.4) and the import parser (T25.11) exist. The worker needs a protocol that those tasks can build on, and a way for the tests to see a worker panic, hang or run out of memory without a test-only build of the server.

Decision

  • Frames are a u32 big-endian length (counting the kind byte), one kind byte, then the payload: kind 1 JSON (at most 1 MiB), kind 2 binary chunk (at most 512 KiB). The length is checked before any payload is read or allocated (discovery::frames).
  • Messages are JSON objects tagged by t: hello, job, result. Protocol 1. A hello mismatch of protocol or build is answered with the worker's own hello and an exit code of 3; the parent raises discovery_worker_version_mismatch and starts nothing else.
  • The fault job (panic, hang, alloc) exists only in debug builds, so the integration tests can run a real worker through a panic, a hang and an allocation past RLIMIT_DATA. A release worker answers it as an unknown op. The bench-only override of the pacing floor is T25.4's, with the pacing.
  • The status API GET /api/v1/discovery/status (DSC-014) is added now, for the worker card and the health reasons. It shows whether the node runs the inventory and each worker's state. It is discovery:read (DSC-013) only from T25.12, so agents get 403 on it until then (auth::agent).

Alternatives rejected

a fault switch in an environment variable (the environment is cleared for the worker, and a variable the parent can't set would be a second channel); a test-only build (the systemd e2e needs the release binary).

  • Review of T25.3 (2026-11-17), the parent's side: the stderr of a worker is read one line at a time and each line is kept to 400 bytes (the rest is read and dropped up to the newline), with control characters escaped before logging, so a worker can't grow this process's memory or forge a log line (ADR-908, CLU-004). A worker that reports a limit other than the one asked for (dumpable, another data limit, another oom_score_adj) is refused and restarts with backoff. A job's timeout is per op: a ping has 10 s, every other op 30 s (the SNMP walk budget of ADR-908); a new op names its own timeout in supervisor::timeout_for.

Consequences

the worker frame reader is the one piece of discovery code that reads bytes from a child process. Both readers are fuzzed by worker_frames: the synchronous one the worker uses and the async one the main process uses (frames::read_frame_async, which moved into frames.rs for that). The target fails if the two readers disagree on any input. The status API is read-only and unauthenticated only as far as every other status route is.

Requirements CLU-004 DSC-013 DSC-014

Builds on ADR-908

ADR-930 The designated node, its names, and the audit of [discovery]Accepted 2026-11-17ADR-907 says [discovery] node names the node that runs discovery, else the primary or the standalone node, and never an ephemeral pod or a witness.

Context

ADR-907 says [discovery] node names the node that runs discovery, else the primary or the standalone node, and never an ephemeral pod or a witness. It doesn't say what a name is matched against, or when the section is audited. T25.2 settles both.

Decision

  • node matches a member's cluster node ID or the node's configured name ([node] name, or the hostname). An operator who knows the name in the UI doesn't need the hash. A name that matches nothing runs nothing, and the status shows designated: false on every node.
  • An ephemeral pod or a witness is never designated, even when named (gate::designated).
  • The inventory thread and the workers start and stop at start-up and on every reload, from the same gate (discovery::runtime::Runtime::reconcile). An API change reaches the designated node through the reload it already triggers.
  • [discovery] is audited as discovery.config_changed with source = file: at start when the files set the section, and on a file reload that changes it. Changes made through the API are audited by the API with their author (as for every managed kind). The start-up record reads the files' own copy (Sources.file_config), never the merged config, so a section the API set is not labelled as coming from the file (review of T25.3).
  • Reconciles run in the order their reloads happened. Each reload takes a generation (Runtime::next_generation) where it is handled, and a reconcile whose generation is older than the newest applied one is skipped. Two quick reloads (on, then off) can't leave the inventory running when the configuration says off (dsc_001_reconciles_apply_in_order, review of T25.3).

Alternatives rejected

matching the node ID only (the hash is unreadable in the UI); auditing every reload whether or not the section changed (noise in the log every SIGHUP).

Consequences

a node renamed in the file is no longer designated by that name, and the status says so. The owner confirms the name rule while this ADR is Proposed.

Builds on ADR-907

Referenced by ADR-1005 ADR-998

ADR-931 SNMPv3 time window: only authenticated Reports move the clock; an authNoPriv Report answers an authPriv requestAccepted 2026-11-17The m25-snmp review (2026-11-17) found that the ADR-908 amendment of the same day moved the one-per-minute resync limit from unauthenticated to authenticated Reports, and that an authPriv request could not be resynced at all.

Context

The m25-snmp review (2026-11-17) found that the ADR-908 amendment of the same day moved the one-per-minute resync limit from unauthenticated to authenticated Reports, and that an authPriv request could not be resynced at all. RFC 3414 §3.2.7a says a notInTimeWindow Report is sent at authNoPriv, and the agent checks the time before it decrypts the scopedPDU. The agent's Report therefore arrived at a level the client dropped, and it often carried request-ID 0. An agent that answers discovery with boots and time 0/0 (RFC 3414 §4 allows this) never worked at authPriv. Decision (proposed):

  • An unauthenticated Report never sets the agent's clock. Only a Report whose MAC verifies may.
  • For an authPriv request, a Report at authNoPriv is accepted if its MAC verifies, and its request ID is 0 or the request's ID. Any other reply at authNoPriv is dropped.
  • At most one authenticated time resync per agent per minute. The request is sent once more, with the new boots and time.
  • The window follows RFC 3414 §3.2.7b: boots at 2^31 - 1 are stale, and equal boots more than 150 s behind are stale.

Alternatives rejected

  • Downgrading the request to authNoPriv after a failure: weakens the level the owner configured.
  • Keeping an unauthenticated resync with a per-minute limit: a spoofed Report could still move the clock once a minute.

Consequences

  • The ADR-908 amendment (2026-11-17) that describes the resync is kept as written, and this ADR governs the rule. Owner decision: accept this ADR, which then supersedes the one-per-minute wording of ADR-908.
  • Interop with real net-snmp v3 agents is Open until the TT_SNMPD_* values are supplied.

Builds on ADR-908

Referenced by ADR-908 ADR-980

ADR-932 Credential file open: no followed symlink, no FIFO block, and the libc constantsAccepted 2026-11-17The m25-snmp review (2026-11-17) found two races in wrendns-snmp's credential read.

Context

The m25-snmp review (2026-11-17) found two races in wrendns-snmp's credential read. The path was canonicalized and then opened by name, so a link swapped in between pointed outside the secret directories. A FIFO was opened before its metadata was checked, so the open could block.

Decision

  • The file is opened with O_NOFOLLOW | O_NONBLOCK (libc 0.2, the constants only, through OpenOptionsExt::custom_flags, which is safe code). A final symlink fails the open, and a FIFO does not block.
  • The metadata is read from the handle, and only a regular file of at most 4096 bytes is read.
  • The canonical path is canonicalized again after the open. Its device and inode must match the handle's (Unix; off Unix the canonical path alone is the check).
  • The read buffer is allocated for the cap (4097 bytes) up front, so a read never reallocates and leaves no unzeroized copy.
  • The decoded v2c community is held in Zeroizing.

Alternatives rejected

a std-only check (symlink_metadata before the open) leaves the same race; an openat walk of each path component is more code than the risk needs for admin-owned secret directories.

Consequences

  • A swap of a directory on the path between the last identity check and the read is not detected. The secret directories are admin-owned ([node] secret_file_dirs), so this is accepted.
  • libc is a dependency of wrendns-snmp only. The lock already has it, so no new package enters the tree. The image delta is 0 bytes until T25.6 links the crate into wrendns.
  • Owner decision: accept or reject the libc constants.

Referenced by ADR-908

ADR-933 The worker's seccomp filter covers 32-bit ARM, so a discovery worker runs on armv7Accepted 2026-11-17install_worker_seccomp covered x86_64 and aarch64, and returned Unsupported elsewhere (fail closed, ADR-908).

Context

install_worker_seccomp covered x86_64 and aarch64, and returned Unsupported elsewhere (fail closed, ADR-908). The image ships linux/arm/v7 (.github/workflows/image.yml) and the release ships wrendns-armv7-linux. On a 32-bit Pi, enabling discovery crash-looped the worker (discovery_worker_failing) and left the feature unusable. The review (N3) asked for a recorded decision.

Decision

write the filter for 32-bit ARM. AUDIT_ARCH_ARM (0x40000028) is the architecture check. The deny-list uses the ARM EABI numbers from libc (bind 282, listen 284, ptrace 26, the process_vm_* and io_uring calls at their generic numbers), and the x32 range check (ADR-934) applies to it too, where it does nothing. Everything else is as on the other architectures: the worker holds no capability, sets no_new_privs, and a call from another architecture kills it.

Alternatives rejected

keeping the refusal and naming the architecture in the health reason (leaves the feature unusable on the 32-bit Pi the image ships); a worker without a filter on armv7 (drops the "cannot share the DNS port" guarantee that the other architectures keep).

Consequences

the armv7 filter is type-checked and clippy-checked for armv7-unknown-linux-gnueabihf (the test binary included), and the filter's numbers come from libc's ARM table. It has not run on armv7 hardware here. A check on Pi hardware is an Open item in spec/10 (T25.3).

Builds on ADR-908 ADR-934

Referenced by ADR-1001 ADR-934 ADR-939 ADR-988

ADR-934 Worker spawn and filter hardening under the systemd unit: no ambient capability, no capset call without one, a non-dumpable parent, and the x32 and io_uring calls refusedAccepted 2026-11-17The review of the T25.3 fixes (276315b) found four gaps in ADR-908's worker hardening.

Context

The review of the T25.3 fixes (276315b) found four gaps in ADR-908's worker hardening.

  • N1 (HIGH). The unit sets AmbientCapabilities=CAP_NET_BIND_SERVICE and SystemCallFilter=~@privileged. A child inherits the ambient set, so the worker held CAP_NET_BIND_SERVICE, and drop_worker_capabilities called capset, which @privileged contains. A filtered call with no error number kills the process (SIGSYS), so every worker died on every systemd install.
  • N2 (MEDIUM). The filter checked the native syscall numbers only. An x32 call (nr | 0x40000000) reached bind and bound a loopback port (demonstrated on WSL2, kernel 6.6). io_uring's bind and listen skip the filter on kernels 6.11 and later. A worker of the same uid could open /proc/<parent>/mem under Yama ptrace scope 0, because the parent is dumpable.
  • N3 (MEDIUM) is ADR-933.

Decision

  • Ambient cleared before exec. wrendns_net::worker::prepare_spawn makes every discovery worker spawn clear the child's ambient capability set between fork and exec. The call is prctl(PR_CAP_AMBIENT_CLEAR_ALL), which takes no pointers. A non-root worker then execs with no capability.
  • capset only when a capability is held. drop_worker_capabilities reads CapPrm and CapEff from /proc/thread-self/status and calls capset only when either is non-zero. A worker with none never calls it. A root worker (tests, or a container run as root) still drops its capabilities. An inheritable bit alone grants nothing, since there is no exec file capability and no ambient one.
  • Parent not dumpable. prepare_spawn also makes the parent not dumpable (PR_SET_DUMPABLE 0), so a worker of the same uid can't open its /proc/<pid>/mem (EACCES without CAP_SYS_PTRACE). It is called before each spawn, so only a process that runs discovery changes. The costs: this process refuses core dumps and debugger attach. The supervisor is the only caller.
  • Review of the m25-b branch (N6, N7, N8, 2026-11-17). Not dumpable makes the /proc/self files that belong to the owner (/proc/self/io, mode 0400) root-owned, so a non-root wrendns (the systemd unit, the image, the chart) lost the host's write-rate metric, the SD-card wear signal on a Pi. Measured as uid 65534 (/proc/self/io refused, while status, limits, maps, smaps, exe, fd, task and the /proc/self owner stay readable by the process itself): prepare_spawn opens /proc/self/io before it makes the process not dumpable (sys::pin_self_io), and wrendns_net::self_io_text re-reads that descriptor with pread at offset 0. The trade-off that remains for operators: once discovery runs, a non-root administrator can't read this process's /proc/<pid>/io, environ, mem, or attach a debugger or strace to it. Root still can (CAP_SYS_PTRACE). It is in docs/running.md. The non-root test dsc_002_write_rate_survives_a_worker_spawn (uid 65534, run from a root test binary by re-executing it) is the proof.
  • The parent-read test (N7). dsc_002_worker_cannot_read_its_parent makes the middle process dumpable first, in both modes, because a process that changed uid at exec is already not dumpable and the shield would pass without prepare_spawn. The decisive check is that prepare_spawn clears the dumpable flag (any Yama setting). The open is an end-to-end control that runs only under Yama scope 0, where the worker can read a dumpable parent. Under scope 1 (the Ubuntu default and this container) Yama refuses the open either way, so the control is skipped and printed as skipped.
  • Filter. The seccomp filter refuses every number at or above 0x40000000 (the x32 range) with EPERM, and also refuses io_uring_setup, io_uring_enter and io_uring_register with EPERM. The arch check and the native deny-list are unchanged, plus arm (ADR-933).
  • Tests (wrendns-net worker::tests): dsc_002_worker_refuses_x32_and_io_uring; dsc_002_worker_without_capabilities_never_calls_capset (the filter kills a capset call, and a worker with none survives; the control dies with SIGSYS); dsc_002_worker_cannot_read_its_parent (the middle process is made dumpable first; prepare_spawn must clear the flag; the open control runs only under Yama scope 0); dsc_002_spawn_clears_ambient_capabilities (as root: the raised ambient set is inherited without prepare_spawn and cleared with it).

Alternatives rejected

  • SystemCallErrorNumber=EPERM in the unit: the worker would get EPERM for capset, and harden fails closed. It would also change what every other filtered call in the unit returns. The capset skip fixes the cause and keeps the unit as it is.
  • A second uid for the worker: the image, the chart and the unit run one user (ADR-908), and a second one adds deployment work for a read this kernel setting already blocks.
  • Leaving the parent dumpable and relying on Yama: Yama 0 is common on hosts and in containers, and it is the case that was open.

Consequences

the systemd unit is not yet run on a systemd host (the review ran none either), so the @privileged claim rests on systemd-analyze syscall-filter @privileged listing capset, and on the kill test. The ambient and capset tests need root (they skip otherwise). The worker's CapInh can be non-zero under the unit, since systemd sets an inheritable bit for ambient capabilities; it grants nothing, and the test asserts the permitted, effective and ambient sets only.

Builds on ADR-908 ADR-933

Referenced by ADR-1001 ADR-933 ADR-939 ADR-988

ADR-937 Per-list "Update now" and a Confirmed current column on the Lists pageAccepted 2026-11-17FLTT24.17 (FLT-004, ADR-905) asks for an "Update now" in each row of the Lists status table, and a per-list freshness display.

Context

T24.17 (FLT-004, ADR-905) asks for an "Update now" in each row of the Lists status table, and a per-list freshness display. The API already takes names (ADR-905), so no server change is needed. The task doesn't say what an off list's row does (the server reports an off list as skipped and queues nothing), or what freshness an inline list has (inline rules have no download to confirm).

Decision

  • A row's Update now sends POST /api/v1/lists/refresh with {"names": ["<that list>"]}, the same request as the page-wide button. It shows for operators only (can('operator')), and is disabled while that list is refreshing, while any row's request is in flight, and when the list is off. The off row's tooltip says to turn the list on; the server is not asked.
  • A refresh of one list reads "<name> updated" in the status line; the whole-set sentence ("every enabled list confirmed current …") stays for a refresh of every enabled list.
  • Confirmed current (for every role) shows ago(lastSuccessUnixSeconds), which reads "never" for an enabled download list that never downloaded. An off download list that never downloaded reads a muted "off" instead (nothing to confirm, and "never" would suggest a fault). An inline list reads "inline", since it has no download to confirm.
  • The status line says "Downloading <name>…" from the click until the answer, so a row's request is never reported as done before it is answered. The whole-set wording is chosen by the refresh's scope (every enabled list, or one row), not by counting the lists.
  • No dry-run control: dryRun stays for agents and wrendns ctl.

Consequences

no API, OpenAPI, MCP or config change; the help topic list-update-now covers per-row updates. The per-row request is audited as lists.refresh with its names, like the page-wide one.

Requirements FLT-004

Builds on ADR-905

ADR-939 The Pi-hole import's worker: a child process with an empty environmentAccepted 2026-11-17An uploaded Pi-hole export is untrusted input.

Context

An uploaded Pi-hole export is untrusted input. A zip bomb, a malformed archive or a gravity.db built to crash the reader must not reach the DNS process (ADR-913 says why: a panic or an allocation failure in an in-process parser aborts DNS). ADR-913 names a worker mode (wrendns discovery-worker --import) that lives on the M25 branch, not in this tree.

Decision

  • The worker. A hidden subcommand, wrendns pihole-import-worker PATH, run by the server as a child process of the same binary. It reads the file, converts it with the importer (pihole::convert), and prints one JSON object. It has no configuration, no state database and no secrets.
  • Isolation. env_clear(), stdin null, stdout piped, a 60-second timeout, and kill on drop. The worker starts with the discovery workers' spawn preparation (wrendns_net::worker::prepare_spawn: no ambient capability, and this process not dumpable, so the worker can't read the server's memory). The worker applies the discovery workers' hardening first (wrendns_net::worker::harden, ADR-933 and ADR-934: RLIMIT_DATA at 1 GiB, no capability, no_new_privs, the seccomp filter that refuses bind, listen, ptrace, process_vm_*, io_uring and x32 calls, not dumpable); if that fails, it prints the reason and converts nothing. The server reads the worker's stdout through take(64 MiB + 1), so an answer over the cap stops the read there and kills the worker. The upload is written to a 0600 temporary file that's removed after the worker returns, on a blocking thread.
  • Limits. The HTTP body limit is 64 MiB. The archive reader's limits apply (archive.rs: 256 MiB per entry (lowered by ADR-988's review, 2026-11-18) and in all, no zip64, no encrypted entries, CRC checked, no path is written). A gravity.db is opened read-only from a temporary copy.
  • Failures. A file the importer can't read is 422 with the reason; a worker that stops, or takes too long, is 422 too, and DNS keeps answering.

Alternatives rejected

  • Parsing in the server process. A panic there aborts DNS; the worker's crash is contained.
  • Reusing ADR-913's --import worker now. It isn't in this tree. The import reuses the discovery workers' hardening (wrendns_net::worker), not their mode; when the M25 branch's --import mode lands, the two can share one mode.

Consequences

  • The tokio crate's process feature is enabled, which adds no crate. The image delta is the feature's code; not measured here (the release image build measures it).
  • The worker runs the same binary, so it has the same version as the server.
  • Preparing a spawn makes the server process not dumpable, as it already is once discovery's workers start: its core dumps and a debugger's attach are refused.
  • Two previews run at once at most (the rest get 503 unavailable until one ends), so the memory of uploads and workers is bounded (review of T24.18, LOW 4).

Builds on ADR-913 ADR-933 ADR-934 ADR-988

Referenced by ADR-988

ADR-940 Importing a Pi-hole export: a plan, applied as one configuration change, admins onlyAccepted 2026-11-17AGTT24.18 puts the Pi-hole import on the admin page: upload, preview, apply.

Context

T24.18 puts the Pi-hole import on the admin page: upload, preview, apply. An import replaces configuration in bulk, and the API writes configuration one entry at a time (ADR-069). ADR-040 makes the config files' names read-only through the API. ADR-914 says bulk changes are admin changes with a typed confirmation and an audit record.

Decision

  • Who. Admins only. An agent's token is refused by the auth layer (403 forbidden) and by the handler (agent_not_allowed); operators and viewers get 403. spec/13 §3 lists the import among the operations no agent may make.
  • Preview. Changes nothing. It returns a plan: a planId, what would be added, changed or skipped (each with its reason and where it points: a URL or file, the servers, the members, the record values), the notes, and the comparison when asked (ADR-941). A plan is held in this node's memory for ten minutes (at most eight are kept), like an agent's plan (AGT-007). A restart discards them. A plan's ID is 32 random bytes, and only the admin who previewed it may apply or discard it; another admin gets 404.
  • Retries. The three routes take Idempotency-Key as the configuration writes do (AGT-003): a retried apply or discard gets the first answer, a preview is keyed on a hash of its body and options, and a successful answer is kept under the admin's key for a day.
  • Apply. The plan's writes go in one transaction (put_managed_batch), and the version moves once. Before the write, the merged configuration (the files plus the stored entries plus the plan) must load; the configuration version must still be the preview's, or the answer is 409 and the preview is run again. The node then reloads. If the change is stored but the reload fails, the audit record is written anyway, with applied: false, and the answer is 500 saying the change was saved, so the audit log never misses a change that happened.
  • Names. An entry of a name that exists is replaced (change), as an API override replaces the file's (ADR-069); the file's entry comes back when the override is deleted. A name the config files define is skipped for local names, conditional forwards and devices, because ADR-040 keeps those read-only through the API (the merge ignores a stored device of a name the files use, so writing one would store a dead row). A file list (a file:// adlist in the export) is flagged in the notes, since it reads a file on this machine. A stored rate limit replaces the file's [ratelimit] section as a whole, and the item says so.
  • The default groups. Pi-hole's lists join the default group's lists, and Pi-hole's upstreams join the default upstream group's members. Their other settings stay. An omitted list means every list (lists omitted), so the merge keeps it omitted.
  • Conditional forwards. Each Pi-hole route is a forward entry with the servers of its group's upstreams. The pihole-forward-N upstreams and groups aren't written. A suffix is routed once: when a v5 rev-server and a dnsmasq server=/domain/ name the same domain, the first is kept and the conflict is noted.
  • DNSSEC. The mode is a file setting, not an API one, so it's reported as skipped with the line to add to the file.
  • Audit. Applying is audited as import.pihole with the counts and the configuration version. A preview isn't written to the audit log.
  • The UI. The apply needs the word IMPORT typed in. The page is a Settings tab that admins alone see. Its comparison takes the Pi-hole address, this node's address (default 127.0.0.1:53) and extra sample names.

Alternatives rejected

  • Writing the file. The API can't write the configuration files (ADR-040), and the CLI already writes them for a person who reads the output.
  • One request per entry. A failure in the middle would leave half an import in place, and each write re-checks the whole configuration.
  • Keeping plans in the state database. An import is short-lived, like an agent's plan; a restart discards it, which is the safe side.

Consequences

  • Undoing an import means deleting the entries it added. The audit record lists the counts; the preview lists the names.
  • A change replaces an entry of the same name: the import page says so before the apply.
  • The plan's bodies are the entries the store keeps: a credential isn't part of a Pi-hole import, so no secret passes through it.

Requirements AGT-003 AGT-007

Builds on ADR-040 ADR-069 ADR-914 ADR-941

ADR-941 The Pi-hole import's comparison: the sample, the resolver it asks, and when it stopsAccepted 2026-11-17T24.6 asks for wrendns import pihole --compare, which resolves a sample through the Pi-hole and WrenDNS and reports the differences.

Context

T24.6 asks for wrendns import pihole --compare, which resolves a sample through the Pi-hole and WrenDNS and reports the differences. The task text doesn't say which names, which WrenDNS, or what happens when a server doesn't answer.

Decision

  • Sample. The imported local names and CNAME names, up to 20 exact deny entries, and the names given with --sample. A and AAAA are asked of both servers. At most 200 names.
  • The WrenDNS side. The node's own resolver at --wrendns (127.0.0.1:53 by default). It answers from its running configuration, so before the import is applied the report shows what the node answers now, and the help says so.
  • Transport. Plain UDP, two seconds a query, no retries. A server that doesn't answer five queries in a row is named in the report and isn't asked again; when neither answers, the comparison stops.
  • What counts as a difference. The rcode, or the sorted addresses and names of the answer. TTLs are ignored.
  • Read-only. It sends standard queries and nothing else. The import page's comparison (T24.18) is the same function.
  • Budget. The whole comparison stops after 60 seconds, and the report says how many names it covered. A server that answers every other query never reaches the five-in-a-row limit, so the budget is what bounds the time. The addresses are the admin's to give (the admin already holds the configuration), so the UDP goes wherever the admin names.

Alternatives rejected

  • Comparing the configuration offline. It wouldn't show what a client gets over DNS (rewrites, blocking, the cache and the special names all act in the resolver).
  • TCP or DoT to the Pi-hole. What the household's devices get is the UDP answer; the comparison should match that.
  • Retrying silent servers. A wrong address would then cost minutes; five silent queries say it clearly.

Consequences

  • A comparison in the UI asks the WrenDNS address the admin gives, by default the node that serves the page. In a cluster, it's that node's resolver unless another address is given.
  • The sample is a sample: a difference in a name that isn't in it goes unreported.

Referenced by ADR-940

ADR-942 UniFi offline clients on the fork's router model: offline_days 0 keeps the reservationsAccepted 2026-11-17The upstream merge brought T8.2's offline clients (ADR-166): the console's client history and the configured clients, named by their last address, for offline_days (30 by default, 0 for connected clients only).

Context

The upstream merge brought T8.2's offline clients (ADR-166): the console's client history and the configured clients, named by their last address, for offline_days (30 by default, 0 for connected clients only). The fork had already made a DHCP reservation (T22.2, ADR-902) name its device while it is offline, whatever the history says. Both can't hold at offline_days = 0. Decision (proposed; the conservative reading of both):

  • The history and the configured clients (rest/user) are read only while offline_days > 0. A dated row names a device only inside the window; an undated row can't be judged against it, so it is kept (unifi_known keeps it), as in ADR-166. The configured clients are read like the history rows: an alias without a reservation names its offline device too. The fork's earlier worry (a configured client's last address may belong to someone else by now) applies equally to the history rows, which are kept; the window and offline_days are the control for both.
  • A reservation names its device at any offline_days, including 0. It is the router's configuration, not a history, and the fork's T22.2 behaviour is kept. The Routers form's help topic (router-offline-clients) says so.
  • Offline devices stay out of "seen" (ADR-166), and the fork's reservations still count as seen (the T22.2 decision); a reservation is therefore not an offline device here.
  • An offline client is not a current answer anywhere else either (sync review, 2026-11-17): it gives no address binding to discovery (ADR-910, ADR-924), publishes no DNS name, isn't counted in a network's devices, and is left out of /dhcp/leases, which has no offline marker yet (an owner decision, Open in spec/10 T8.2). It still names the device in the query log.

Consequences

offline_days = 0 means "no history names", not "no offline names". The owner may prefer the stricter reading (0 also drops reservations); that is a change to unifi_reserved in routers.rs, one line, and a test. Owner decision (2026-11-17): /dhcp/leases and the UI list offline clients, marked offline (as upstream does); they stay out of DNS names, discovery's address bindings and a network's device count, as above. Built 2026-11-17 (spec/10 T8.2): DhcpLease.offline is always serialized; the offline row's dnsName is absent.

Builds on ADR-166 ADR-902 ADR-910 ADR-924

Referenced by ADR-945

ADR-943 Svelte attribute quantifiers: {n} in a quoted attribute is written as a JS expression, and a guard keeps it that wayAccepted 2026-11-17, owner decisionUpstream issue #64, "2FA can't be enabled".

Context

Upstream issue #64, "2FA can't be enabled". Svelte 5 reads {6} inside a quoted attribute value as an expression, so pattern="[0-9]{6}" reached the browser as [0-9]6 and no six-digit code matched. The TOTP enrolment (Settings) and the sign-in code (Login) both had the bug.

Decision

  • Every such attribute in ui/src is written as pattern={"[0-9]{6}"}, a string expression, so the braces reach the DOM unchanged.
  • ui/scripts/check-quantifiers.mjs runs first in npm run check. It fails when any quoted attribute in a .svelte file, double- or single-quoted and across lines, contains {digits} or {digits,digits}. It is a source check, so it catches the pattern before a build.
  • The Playwright suite enrols TOTP with a real RFC 6238 code and signs in with one, so a regression that breaks the pattern also fails the suite.

Consequences

A new quoted attribute with a quantifier fails npm run check until it is written as an expression.

ADR-944 Break-glass sign-in defaults to loopback, and a proxied request is never break-glassAccepted 2026-11-17, owner decisionUpstream issue #63.

Context

Upstream issue #63. The default [auth.oidc] allowed_admin_networks was the private networks plus loopback, so with disable_local_login = true any LAN device could try a password. The owner asked for a safer default. Two things make a loopback-only default need care: a reverse proxy on the same host is not in [api] trusted_proxies, so every proxied client arrives as 127.0.0.1 and would pass; and with Docker port publishing the peer is the bridge gateway, so an admin on the host is locked out of break-glass.

Decision

  • allowed_admin_networks is optional. Absent means loopback only (127.0.0.0/8, ::1). Set means exactly that list, and [] allows nothing. The serde default distinguishes absent from set, so an explicit list is never overwritten by the default.
  • A request that carries X-Forwarded-For, X-Forwarded-Host, X-Forwarded-Proto, X-Forwarded-Port, X-Real-IP or Forwarded from a peer that is not a trusted proxy is never break-glass while the loopback default applies. Its address is the proxy's, so it can't be checked. This applies to form sign-in, HTTP Basic and the /auth/status localLogin flag. An explicit list skips this rule, because the operator chose those networks.
  • In-process MCP calls (OnBehalfOf) keep the address they were made with and are checked against the same networks.
  • Startup logs a WARN when disable_local_login is on and allowed_admin_networks is unset. It names the proxy and Docker cases. A trusted proxy in [api] trusted_proxies names the real client and is checked normally.
  • Recovery: set allowed_admin_networks (for Docker, the bridge gateway's address) and restart. docker exec gives no password sign-in: the image has no browser or curl, and wrendns ctl uses a token. Settings are file-only and need a restart, so no API can widen break-glass remotely.
  • Migration: no file is rewritten. Operators who used the old private-network default and disable_local_login must set allowed_admin_networks explicitly; the startup WARN and docs/running.md say so.

Consequences

Break-glass from the LAN now needs one config line. Docker and proxy setups need a documented path (the bridge gateway in allowed_admin_networks, or the proxy listed). A proxy on the host that isn't listed locks its clients out of break-glass rather than letting them in. This is the conservative reading of the owner's request, and the owner can change the default by one line in schema.rs if they prefer private networks.

Referenced by ADR-1047 ADR-1067 ADR-961 ADR-987

ADR-945 The leases list shows offline clients, marked offlineAccepted 2026-11-17ADR-942 keeps an offline UniFi client out of DNS names, discovery's bindings and a network's device count, and left /dhcp/leases without it because the API had no marker.

Context

ADR-942 keeps an offline UniFi client out of DNS names, discovery's bindings and a network's device count, and left /dhcp/leases without it because the API had no marker. The owner chose to show it.

Decision

GET /api/v1/dhcp/leases lists every router lease, including the offline clients, each with offline (always present: true for an offline client, false for connected and reserved rows). An offline row has no dnsName. The listing is the only thing that changes: device_dns, discovery's lease_observations and networks()'s device count still skip offline rows. The UI marks them with an "offline" badge (Clients → Discovered, Networks → a network's devices).

Alternatives rejected

leaving them out (the owner's earlier reading, which hid a device the admin may want to see); a separate endpoint for offline clients (a second list the admin would have to join by hand).

Consequences

a client that gives an offline row has no last-seen time, since the lease carries only its end time. Adding one needs the router's history timestamp kept on the lease (later work).

Builds on ADR-942

ADR-946 Federated reads run off the runtime workers: block_in_place under the blocking helperAccepted 2026-11-17upstream #7.

Context

upstream #7. call_one and gather in crates/wrendns/src/federated.rs run a plain thread that blocks on the runtime. Called from a worker, the worker is held while the cluster stream's writer and reader tasks need workers to finish the call, so two concurrent reads to a peer that doesn't answer wedged a two-worker runtime. Several async handlers called a federated read directly on a worker.

Decision

  • The wait. call_one and gather run their future through run_off_the_worker: on a multi-thread runtime, block_on inside block_in_place, which hands the worker's queued tasks to another thread first, with no extra thread. A current-thread runtime has no other thread to take them, so its future runs on a scoped thread. block_in_place is a no-op off a runtime, so a blocking-pool caller takes the multi-thread path too.
  • The handlers. A federated read in an async handler runs through blocking(). The Backend methods that can reach call_one or gather are annotations, anomalies, blocking_pause, blocking_resume, blocking_state, cache_entries, cache_flush, cache_lookup, cache_stats, client_rhythm, clients, config_entries, config_version, exemplars, health, heatmap_network, identities, identity, kubernetes_workloads, latency, lists, list_hits, new_devices, overblocking, probes, queries, secrets_status, shadow_lists, timeseries, top, top_clients_rolling, top_in_group, top_range and upstream_checks. Every async caller of one of them now uses blocking() or spawn_blocking. The ones that didn't were clients, config_entries, the ETag reads (local_names, forwards, rules, a config write's response), and a config write's group check, which reads the devices for a group-restricted agent only. The other Backend methods read local state and stay direct. slo_parts, a Federated helper that calls gather directly, has one async caller, the attribution handler, which runs it through blocking().
  • No worker floor. The optional floor of runtime workers is not added. The Pi-profile RSS can't be measured here, and the fix doesn't depend on the count: the regression test passes on two workers.

Alternatives rejected

  • Refusing federated reads on a worker in debug builds. It catches the mistake in tests, but a release build would still wedge.
  • Making the Backend methods async. Every method and its local store would need async plumbing for no gain: blocking() is the existing pattern for backend reads.

Consequences

a federated read on a worker costs a hand-off rather than wedging the node. A new async caller of a federated read must use blocking(), and a new Backend method that reaches call_one or gather joins the list above.

Referenced by ADR-956 ADR-958

ADR-947 A promotion reaches every replica in the heartbeats; a key share repeats every 30 sAccepted 2026-11-17CLUthe three-node run (deploy/cluster3, T21.5) killed the primary.

Context

the three-node run (deploy/cluster3, T21.5) killed the primary. The replica elected in its place became primary, and the other replica followed the dead old primary (its configuration fetch went to primary:8443) and missed every later version. Two causes in wrendns-cluster:

  • a member's primary flag came only from its Hello, at connect time. A replica that connected before the election kept the old view, and primary_urls left the new primary's URL out as a replica's;
  • the primary sent its key share once per stream. A peer that refused it (the flag was stale, so the sender wasn't "the primary" yet) never got another, so it could not be promoted later.

Decision

  • The heartbeat carries the sender's primary flag as an optional field (tag 39). A sender sets it at every heartbeat, and the receiver updates the member's flag. An older node sends no flag, and the flag a peer holds stays. Both directions are compatible without a protocol bump (CLU-010).
  • The primary sends its key share to an eligible peer again every 30 s (KEY_SHARE_RESEND), unchanged. The acceptance check is unchanged: the sender must be the primary in the receiver's view, at the same epoch or a newer one.

Alternatives rejected

  • A protocol version bump. The field is optional both ways, so a bump would only force a mixed cluster to upgrade together.
  • Deriving the primary from the epoch. A node's epoch alone doesn't say whether it holds the role now, and a former primary keeps the epoch it had.
  • Acknowledging key shares. A wire change for a refusal that a resend already covers.

Consequences

a primary's heartbeat grows by two bytes, and an eligible peer gets about 2 KiB every 30 s. A replica takes a new primary from the next heartbeat after the promotion. Tests: clu_005_a_promotion_reaches_a_replica_in_the_heartbeats, clu_005_a_key_share_is_sent_again_after_its_interval, clu_005_the_heartbeat_primary_flag_is_optional_both_ways.

Addendum (T21.5 review, 2026-11-17). The three-node run also showed how an election starts. A node's election state is made when automatic failover turns on, and again when the voter set changes. Such a node had no lease to go by (none was granted yet), so its first try came at once: a replica stood 70 ms after the third voter joined and deposed a primary that had not renewed yet. A node that isn't the primary now waits one lease period (LEASE_MS, 15 s) before its first try (Elector::defer_first_try). The primary doesn't wait: it stands at once and takes its lease. Safety is unchanged (a voter still refuses a newer epoch while a lease it granted runs); the first election after a start is later, by up to 15 s. Tests: clu_005_d_a_new_candidate_waits_a_lease_before_its_first_try. The primary's key-share send is one decision (key_share_send: a changed frame at once, the same frame every 30 s), tested by clu_005_c_the_key_share_is_sent_on_change_and_on_the_interval. A repeat of the next CA key that the trust doesn't include yet doesn't rewrite ca-pending.key when the file already holds that key (clu_005_b_a_pending_ca_key_is_written_once).

Requirements CLU-010

Referenced by ADR-954 ADR-960

ADR-948 The [discovery] first write, and members that are stopped or run a dev buildAccepted 2026-11-17, owner decisionCLUADR-928's title says "the first write waits for N−1 members".

Context

ADR-928's title says "the first write waits for N−1 members". Its decision says the first write is refused with 409 members_too_old while a member runs a version older than DISCOVERY_SINCE (0.8.0), or one that can't be read. The three-node run checked both readings. With all three up, the first write passes when the replicas report 0.8.0. With replica-b stopped, the real first write also passes: the gate reads the version the cluster recorded for it, and a stopped member is neither older nor unreadable. A cluster of dev builds does refuse the first write, since a peer's dev is unreadable to the gate, and the refusal names both replicas. The run's image therefore stamps the release version (0.8.0), the way CI stamps a release build.

Decision (proposed): keep the gate as ADR-928's decision states it: members are judged by the version the cluster recorded for them, not by whether they are up. The test follows that. The title of ADR-928 says "waits", which this doesn't do.

Open for the owner

  • Should a stopped member block the first write until it is back (the title's reading)? That is a new rule: a member that's down would hold up a setting, and the first write has no later retry.
  • Should a dev build report a readable version to its peers, so a dev cluster can use [discovery]? Today it can't, and the refusal is correct for the decision as written.

Consequences

no code change until the owner decides. The test pins the current behaviour (deploy/cluster3/e2e.sh, check e).

Owner decision (2026-11-17):

  • A stopped member doesn't block the first write. Members are judged by the version the cluster recorded for them, as above. The title of ADR-928 is read as its decision.
  • A build without a release stamp reports the crate version with a -dev suffix (for example 0.8.0-dev) instead of dev, and peers and the gate read it as that version. A dev cluster can then use [discovery] without a release stamp. This is T21.6.

Addendum (T21.5 review, 2026-11-17). A [discovery] the primary sets with a value that isn't the default was refused by every replica whose own section was at its defaults. The section is left out of a node's serialization at its defaults (CLU-010), so the configuration merge didn't know the key and refused the whole version ("the primary sent a setting this version doesn't know"). The merge now always has the discovery key: at its default when the primary doesn't send one (so a cleared section resets the replicas, as the other shared sections do), and the primary's value when it does. Test: clu_010_a_discovery_section_is_shared_both_ways (wrendns-config). Check (e) of the three-node run writes worker_memory_mib = 48 and reads it back on replica-b, which is what found it.

Requirements CLU-010

Builds on ADR-928