For the technical audience

Decisions

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.

325 decisions. Accepted 115 · Agreed with the project owner. Proposed 60 · Chosen during implementation where the specification left a gap. It is in effect, and waits for the owner's review. Accepted 2026-11-18 38 · Accepted 2026-11-17 31 · Accepted 2026-11-16 16 · Accepted 2026-11-18, owner decisions 4 · Accepted 2026-11-19, T31.2 4 · Accepted 2026-11-19, T33.6, API-005, DOC-006 4 · Accepted 2026-11-17, owner decision 3 · Accepted 2026-11-19 3 · Accepted 2026-11-17, owner decision: accepted as implemented once a second independent security review found nothing HIGH or MEDIUM, which it did not 2 · Accepted 2026-11-17, owner decisions 2 · Proposed 2026-11-18 2 · Accepted 2026-11-19, owner decision 2 · Accepted 2026-11-19, T33.2 2 · Accepted 2026-11-19, amended per the owner decisions on cloud writes; owner accepted all recommendations; #41, T36.1; revised after review the same day 2 · Superseded 1 · Accepted 2026-11-18, owner decision on the precedence 1 · Accepted 2026-11-18, owner decision on the open point 1 · Accepted 2026-11-18, owner decision: any named network wins 1 · Accepted 2026-11-18, owner decision: the CA-holder residual is accepted; per-node assertion keys are T27.19 1 · Accepted 2026-11-19, owner request; revised 2026-11-18 after review for ADR-998 1 · Accepted 2026-11-19, owner request; revised 2026-11-18 after review 1 · Accepted 2026-11-18; cause unproven until real Pis confirm it 1 · Accepted 2026-11-18, T24.34 1 · Proposed 2026-11-18, T24.29 1 · Proposed 2026-11-18, T24.38 1 · Accepted 2026-11-19, owner decision; counsel review before the first commercial sale 1 · Accepted 2026-11-19, records the owner's decision 4 of docs/design/ui-technical-info.md 1 · Accepted 2026-11-19, T33.2, T33.3 1 · Accepted 2026-11-19, owner step, OPS-004 1 · Accepted 2026-11-19, T33.5 1 · Accepted 2026-11-19, T24.43, owner request 1 · Accepted 2026-11-19, owner accepted all recommendations; #41, T36.1; revised after review the same day 1 · Accepted 2026-11-19, amended per the owner decisions on cloud writes; owner accepted all recommendations; #41, #28, T36.1; revised after review the same day 1 · Accepted 2026-11-19, amended per the owner decisions on cloud writes; owner accepted all recommendations; #41, #40, T36.1; answers M32's T32.5; revised after review the same day 1 · Accepted 2026-11-19, amended per the owner decisions on cloud writes; owner accepted all recommendations; #41, T36.1; under ADR-1033, counsel review before the first sale; revised after review the same day 1 · Accepted 2026-11-19, T24.44, owner request 1 · Accepted 2026-11-19, owner decisions 1, 2 and 6; #42, T37.1 1 · Accepted 2026-11-19, owner decisions 2, 5 and 8; #42, T37.1 1 · Accepted 2026-11-19, owner decisions 7 and 10; #42, T37.1 1 · Accepted 2026-11-19, owner decisions 3, 4 and 9; #42, T37.1; amends ADR-102 for the export 1 · Accepted 2026-11-19, owner decision 2; #42, T37.1; counsel review before sale, ADR-1033 item 6 1 · Accepted 2026-11-19, amended per the owner decisions on cloud writes; #42, T37.1; under ADR-1059; owner decision D replaces the subscribed cloud lists 1 · Accepted 2026-11-19; implements owner decision B, which is final; amends ADR-054 for cloud-origin changes only; #41, T36.16, T36.17 1 · Accepted 2026-11-19; implements owner decision C, which is final; revised after the security review the same day; amends ADR-1050 points 1, 4 and 5, ADR-1051 points 1 and 6, ADR-1052 §3 and point 5, and T36.12; #41, #28, T36.12 1 · Accepted 2026-11-19, owner accepted all eight identity decisions;; owner requirement of 2026-11-19; amends ADR-1065 points 1 to 3; #41, T36.21, T36.22, T36.26 1 · Accepted 2026-11-19, owner accepted all eight identity decisions;; owner requirement of 2026-11-19; #41, T36.23 1 · Accepted 2026-11-19, owner accepted all eight identity decisions;; owner requirement of 2026-11-19; revised after the identity security review the same day; amends ADR-1049 points 1 and 2 and ADR-1061 points 3 and 5; #41, T36.24, T36.25 1 · Accepted 2026-11-19, owner accepted all eight identity decisions;; owner requirement of 2026-11-19; amends ADR-1052 point 5's Business tier; #41, T36.25, T36.27 1 · Accepted 2026-11-19, owner accepted all recommendations; owner request of 2026-11-19; M38 1 ·

ADR-001 Language: RustAcceptedPerformance and footprint are paramount: a small, steady memory footprint on a Raspberry Pi and microsecond cache hits.
ADR-016 List fetcher behavior and configurationAcceptedFLTUPSFLT-004 and spec/05 §3.4 step 1 define the fetcher's duties (conditional GETs, size caps, retries, stored sources) but not its configuration, scheduling, name resolution, or edge cases.
ADR-019 Deterministic device anomaly detectionAcceptedOBSThe owner wants WrenDNS to notice when a device behaves differently: abnormal traffic, many queries to one domain, or IoT/appliance phone-homes, in a safe and deterministic way.
ADR-021 Groups, clients, and identificationAcceptedFLTFLT-005/006 and spec/03 §3 step 2 define groups and the identification chain, but not the configuration, the trust model for client-supplied identity, or how group lists meet the compiled snapshot.
ADR-027 Query-log segment format and searchAcceptedspec/06 §4 defines the query log: hourly columnar segments, blocks of up to 8192 rows, per-column encodings with zstd, a block index with a 1 KiB bloom over name and client IDs, a segment dictionary, dictionary-first search, and a small search pool with "1 thread on Pi by default".
ADR-029 Local sign-in detailsAcceptedAGTAPIspec/08 §6 and API-003 define local users (Argon2id), session cookies with CSRF, opt-in HTTP Basic, scoped API tokens, TOTP, lockout, RBAC, and a first-run setup token.
ADR-032 Live tail over Server-Sent EventsAcceptedOBSOBS-008 / 06 §6: GET /api/v1/queries/stream (SSE) "or /ws", server-side filters (client, group, status set, qname glob, upstream, min latency, node), and a per-subscriber rate cap (default 500 events/s) with inline drop counts.
ADR-034 OIDC sign-in: library, flow, and account rulesAcceptedAPIAPI-004 / 08 §6: Authorization Code + PKCE, discovery, multiple providers, claim → role mapping, JIT provisioning, optional verified email, back-channel and RP-initiated logout, ID-token validation with JWKS rotation, local sessions after sign-in, a canonical public_url, and disable_local_login with a break-glass admin from allowed_admin_networks.
ADR-035 Helm chart: allInOne first, client-IP proof in CIAcceptedOPST4.1 / OPS-002/003 asks for allInOne, scaled, and daemonSet shapes, Services with externalTrafficPolicy: Local, PDB, HPA, probes, NetworkPolicy, ServiceMonitor, cert-manager, existingSecret everywhere; AC: ct install on kind and k3d arm64, DNS via the LB, and client IPs preserved in the query log in an e2e test.
ADR-044 Cluster channel v1: identity files, reusable join tokens, and peer trustAcceptedCLUT5.1 implements CLU-001 under spec/12 §3, which fixes the shape (Ed25519 CA, join token with CA fingerprint + URLs + secret, 90-day node certificates, mTLS over HTTP/2 with protobuf, persistent streams, replicas dial out) but not the token format, how peers name each other in TLS, where identity lives, or whether a token is single-use.
ADR-121 Long pages get tabs; a tab never hides troubleProposedthe Cluster page had grown to about ten panels, Settings → System to eight (node housekeeping mixed with how queries are handled), and Clients to three tables, one of them a router's whole client list (dozens of rows on a home network).
ADR-952 The chrono and rsa advisories under the OIDC changeAccepted 2026-11-17, owner decision: accepted as implemented once a second independent security review found nothing HIGH or MEDIUM, which it did notdeny.toml ignored RUSTSEC-2026-0543 (chrono, unmaintained) and RUSTSEC-2023-0071 (rsa, timing side channel).
ADR-966 The backup endpoint's recent sign-in, transport and alertAccepted 2026-11-18ADR-903 §8 names the API's rules (admin, HTTPS, a session signed in within 10 minutes for a passphrase backup, header, audit, alert event) without saying how "signed in within 10 minutes" is known, what an OIDC session does, how the UI recovers from the refusal, or where the alert event comes from.
ADR-968 Node-managed entries replicate as one more blob of the signed version, seeded into a promoted primary's own rows onceAccepted 2026-11-18CLUADR-903 §6 says node-managed entries (oidc_provider now, sink and otlp with T23.11) are configuration, so they are versioned: ClusterManifest.node_managed holds references only, every member persists, validates and merges it apart from the shared part under its own files, a failure drops only those entries, and a promoted primary publishes the inherited blob overlaid with its own rows and seeds its managed rows from it.
ADR-992 List overlap is counted while the lists are compiled, by name and by side, and the prune plan is computed from those countsAccepted 2026-11-18AGTOBSthe owner asked (2026-11-18, through AskUserQuestion: "Overlap report + disable") for each list on the Lists page to show how many of its entries no other enabled list has and which lists cover the rest, and for a Prune action that previews the lists adding little or nothing at a threshold the admin sets (for example under 1 % unique) and turns them off after a confirmation, with undo.
ADR-994 Content categories and filter profiles are in scope; a profile is a groupAccepted 2026-11-18, owner decisionsFLTthe owner asked (2026-11-18, with two screenshots of UniFi's content filtering) to organise blocking into categories (groups such as "Adult and Sensitive Content", "AI & Crypto", "Business & Professional", "Culture & Entertainment", "Networking Infrastructure", "New or Risky Domains", "Security & Threat Protection", each with checkboxes and an "n of m" count) and to manage them in named filter profiles (a list with Name, Source, Filter Scope, Safe Search and Schedule, and an editor with Source, Ad Block, Safe Search per engine, Filtering Off, Enhanced or Basic, and a category picker with Search, Select All and Deselect All).
ADR-1004 The CMDB's model: configuration items from source records, reconciled by ordered rules, with a definitive source per attribute and a MACD lifecycleAccepted 2026-11-19, owner request; revised 2026-11-18 after review for ADR-998AGTCLUthe owner asked (2026-11-18, fork #21) for a CMDB: one configuration item per real thing on the network, built from every source that reports on it, with the owner declaring which source is definitive for each attribute and with changes going through move, add, change, delete (MACD).
ADR-1043 npm run check keeps the UI on-brandAccepted 2026-11-19, T33.6, API-005, DOC-006the brand pass fixed what the audit found; without a check the next change can bring a hard-coded colour, a removed focus ring or an exclamation mark back.
ADR-1049 Authorization stays on the node: the hosted issuer asserts identity only, every relayed sign-in needs a node-held factor, roles are mapped and capped on the node, and custom roles add create, update and remove per object kindAccepted 2026-11-19, amended per the owner decisions on cloud writes; owner accepted all recommendations; #41, T36.1; revised after review the same day#41 asks for single sign-on on the hosted site, RBAC with create, update and remove, and a hosted side trusted no further than the user's role.
ADR-1050 Configure-once names: a dedicated PSL-listed suffix with a separate site for device names, split-horizon records created on the node, a stable edge address, and roaming DoH and DoT through the home relay firstAccepted 2026-11-19, amended per the owner decisions on cloud writes; owner accepted all recommendations; #41, #28, T36.1; revised after review the same dayThe owner wants one device setting that reaches the local node at home and the same node away, and a per-tenant public resolver (#41).
ADR-1051 Certificates for configure-once names: the node makes its key and CSR, the cloud completes DNS-01 with a free home keep-alive, renewal by ARI, DNS-PERSIST-01 when available, CAA and a CT watch that blocks remote access; on-node ACME with provider integrations for self-hostersAccepted 2026-11-19, amended per the owner decisions on cloud writes; owner accepted all recommendations; #41, #40, T36.1; answers M32's T32.5; revised after review the same daySNI passthrough (ADR-1047) and DoT need each node to hold a certificate for its tenant's names, including a wildcard.
ADR-1058 Shadow AI privacy defaults: off until an admin turns it on with a monitoring notice, then Monitor; per-device findings at privacy levels 0 and 1 (matched before hashing at 1, after an extra acknowledgement), off at 2 and above; no content everAccepted 2026-11-19, owner decisions 3, 4 and 9; #42, T37.1; amends ADR-102 for the exportOBSADR-102 applies the privacy level before the analytics see an event and hashes every name kept or shown at level 1; a keyed hash cannot be matched against a catalog.
ADR-1060 The node side of hosted Shadow AI: a generic name-class counters export, and generic class rules over a content-signed class map, with Block and Allow arriving as signed policy changesAccepted 2026-11-19, amended per the owner decisions on cloud writes; #42, T37.1; under ADR-1059; owner decision D replaces the subscribed cloud listsFLTOBSOwner decision 2 gives the open node "only a small, generic, documented telemetry export (for example per-device, per-category or per-name-class counters over the existing outbound tunnel)" with no Shadow AI logic or catalog, and has enforcement "pushed back to the node as ordinary group or category policy through the existing configuration path".
ADR-1061 Change signing: every cloud-originated policy change carries the editor's passkey signature over the exact change, made on the node's own signing page whenever home is reachable, verified and authorized on the node against a signer enrolled at home (Accepted 2026-11-19; implements owner decision A(1) on cloud writes, which is final; revised after the security review the same day; #41, T36.15)ProposedThe owner decided on 2026-11-19 that the cloud control plane updates the linked home nodes, and that every cloud-originated change to a node's everyday policy is transaction-signed with the editor's change-signing passkey: a WebAuthn assertion whose challenge is a hash of the canonical change, verified on the node against a public key enrolled there once, on the LAN or approved by a LAN admin.
ADR-1062 The platform channel: machine-to-machine delivery of signed content and of actions the node opted into, under an offline root, the release key and a new content key, each limited to its purpose (Accepted 2026-11-19; implements owner decision A(2), which is final; extends ADR-1034; revised after the security review the same day; #41, #42, T36.18)ProposedOwner decision A(2): a second trusted channel, machine to machine and run by MySummitKeep, covers managed updates, catalog and list refreshes (including the Shadow AI catalog), certificate keep-alive and similar.
ADR-1063 Two-way sync, home preferred: per-entry revisions, signed patches merged three ways, home wins a same-entry conflict, Pending, Applied and Accepted states, and a queue for cloud editsAccepted 2026-11-19; implements owner decision B, which is final; amends ADR-054 for cloud-origin changes only; #41, T36.16, T36.17APICLUOwner decision B: policy is fine-grained entries, each with its own version; a cloud edit carries its base version and applies when the primary is still at it; non-overlapping changes merge; on a same-entry conflict home wins and the cloud edit is parked in the portal with three resolutions; a change goes Pending, Applied when the primary commits it, then Accepted once every node and the cloud resolver's copy report the version (reusing the in_sync check), with a timeout that flags lagging nodes; on-prem edits flow up at once, the primary publishing signed versions to a cloud that subscribes like a replica without being a cluster member or holding stored secrets.
ADR-1064 The cloud resolver is in the MVP: roaming devices are answered at home while home is reachable and by the cloud resolver from the last Accepted policy when it is not, with an explicit "apply to roaming now" overrideAccepted 2026-11-19; implements owner decision C, which is final; revised after the security review the same day; amends ADR-1050 points 1, 4 and 5, ADR-1051 points 1 and 6, ADR-1052 §3 and point 5, and T36.12; #41, #28, T36.12Owner decision C moves the cloud resolver (T36.12) into the MVP: it filters roaming devices with the synced policy, home is used when reachable, and "fails closed when home is down" goes.
ADR-1066 Opt-in managed updates through the platform channel, rolled out by the cluster itself (Accepted 2026-11-19; implements owner decision A(2)'s managed updates; amends ADR-046's "the UI never self-updates a node" for opted-in native installs; extends ADR-116's staged rollout to software; revised after the security review the same day; #41, T36.19)ProposedCLUOwner decision A(2) lists managed updates among the platform channel's opted-in actions, for example installing an update inside the node's maintenance window through the existing staged rollout.
ADR-1067 Organization tenants sign in through enterprise connections in the portal's broker: a multi-tenant WrenDNS Enterprise app for Entra ID with a pinned tid, generic OIDC for other IdPs, SAML through External ID until native SAML is reviewed; a portal-minted user ID as sub; verified domains, home-realm discovery, optional SSO enforcement and break-glass ownersAccepted 2026-11-19, owner accepted all eight identity decisions;; owner requirement of 2026-11-19; amends ADR-1065 points 1 to 3; #41, T36.21, T36.22, T36.26The owner's requirement of 2026-11-19: consumer users sign in through Entra External ID; commercial customers onboard through single sign-on as an enterprise application, federating their own IdP (Entra ID, Okta, Google Workspace and others; OIDC and SAML).
ADR-1069 JIT and SCIM together, portal group mappings in the cloud, node group rules signed by a node admin with capped roles and a velocity limit, an unsigned deprovisioning fast path with a mass-disable alarm, and passkey onboarding by admin-signed invitation or admin approvalAccepted 2026-11-19, owner accepted all eight identity decisions;; owner requirement of 2026-11-19; revised after the identity security review the same day; amends ADR-1049 points 1 and 2 and ADR-1061 points 3 and 5; #41, T36.24, T36.25SCIM can create identities and group memberships in the cloud, but a compromised cloud must not be able to grant node access (ADR-1049).