For the technical audience
Decisions ADR-1051 to ADR-1071
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-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-hostersSNI passthrough (ADR-1047) and DoT need each node to hold a certificate for its tenant's names, including a wildcard.
Context
SNI passthrough (ADR-1047) and DoT need each node to hold a certificate for its tenant's names, including a wildcard. Configured devices use those names at home too, so an expired certificate breaks DNS at home for them: renewal must not depend on the tenant paying, or on the cloud being up for long. #40 requires that no DNS-provider credential sits on customer hardware for hosted names, and asks for provider integrations (Azure DNS, Cloudflare, Route 53, GoDaddy, Network Solutions and others) for self-hosters, who today run lego by hand. Let's Encrypt lifetimes fall to 64 days on 2027-02-10 and 45 days on 2028-02-16; 5 certificates per exact name set per 7 days, with no override; ARI renewals are exempt from the limits, first issuances are not. Let's Encrypt announced DNS-PERSIST-01 on 2026-02-18 (staging; production not yet confirmed). CT logs can take up to about a day to show a certificate.
Decision
- Hosted names: each node generates its own key and CSR with
rcgen(linked) for<slug>.<suffix>,*.<slug>.<suffix>, its own<node>.<slug>.<suffix>and (amended 2026-11-19, ADR-1064 point 2) the DNS names<slug>-dns.<suffix>and*.<slug>-dns.<suffix>(so each node's name set is distinct for the 5-per-set limit). The CSR goes over the tunnel to the cloud's certificate helper, which checks every name against the tenant's slug and its bound cluster, completes DNS-01 in the cloud zone (adding and removing its own TXT values with Azure DNS etags, never replacing the set) and returns the chain. Renewal is timed by ARI. The private key never leaves the node. - The home keep-alive: renewal through the helper never depends on billing. A tenant that ever linked keeps free renewal and its local records through suspension, cancellation and non-payment, until it unlinks. Suspension stops only the relay. A failed renewal is a health warning at 30 days before expiry and severe at 7.
- DNS-PERSIST-01: when it is in Let's Encrypt production, the cloud publishes one standing validation record per node's ACME account and the node renews directly with the on-node ACME client of point 7, taking the cloud off the renewal path. T36.7 includes a spike against staging.
- Unlink and move off: before Disconnect, the node lists the devices that used hosted names in the last 30 days, with the steps to move each one, and keeps serving the current certificate until it expires.
- The suffix publishes CAA with RFC 8657
accounturi(the service's ACME accounts) andvalidationmethods=dns-01. This keeps other ACME accounts out; it does nothing against a compromised cloud. - CT watch: the primary polls SSLMate's Cert Spotter API (
/v1/issuances, free within 100 queries an hour) once an hour per slug, never a cloud source, and compares the results with the helper's signed issuance log and its own keys. The cloud resolver's own certificate (amended 2026-11-19, ADR-1064 point 2) is accepted only when it covers nothing but<slug>-dns.<suffix>and*.<slug>-dns.<suffix>and is in the signed log. Any other certificate for its names with a key that is not a member's, or one missing from the signed log, raises severe health and an event marker and blocks relayed sign-in and sessions until a LAN admin acknowledges (ADR-1049 point 3). The watch is off the DNS path; its own failure is degraded health only. No new crate. - Self-hosted names: a
[[dns_provider]]plug-in table in the AGPL node, credentials as stored secrets (ADR-903, ADR-917) scoped as narrowly as each provider allows, with CNAME delegation of_acme-challengerecommended when a provider cannot scope a token (and the only path for providers without a documented DNS API). It serves on-node ACME DNS-01, dynamic DNS on the tenant's own domain, custom names' A, AAAA and CAA records and optional publishing of chosen names. Writes are audited and never for agents. The on-node ACME client is a permissive crate (for exampleinstant-acme) aftercargo-deny, with its image delta reported.
Consequences
Hosted tenants get trusted HTTPS and DoT with no credentials at home, and cancelling never breaks DNS at home. The keep-alive costs the service a renewal per node every few weeks for tenants who no longer pay, which is negligible, and it is a promise that a compromised or failed cloud could break until DNS-PERSIST-01 removes the dependency. The cloud remains able to mint certificates for hosted names; CAA keeps others out, and the signed log and the CT watch make the cloud's own issuance visible and switch remote access off, but they do not prevent the first hours of a man-in-the-middle. Rejected: replicating one key as a stored secret (a node's key leaves the node), DNS credentials on customer hardware for hosted names, renewal tied to billing (lock-in that breaks home DNS), and crt.sh as the CT source (unreliable and rate limited).
Builds on ADR-1047 ADR-1049 ADR-1064 ADR-903 ADR-917
Referenced by ADR-1049 ADR-1052 ADR-1061 ADR-1062 ADR-1064
Link to this decision · In the specification
ADR-1052 The open-core boundary, data handling and the launch platform of WrenDNS CloudADR-1033 makes WrenDNS AGPL-3.0-or-later with a commercial licence from MySummitKeep, LLC and anticipates open core.
Context
ADR-1033 makes WrenDNS AGPL-3.0-or-later with a commercial licence from MySummitKeep, LLC and anticipates open core. #41 proposes the hosted control plane, the roaming resolver and dynamic DNS as paid tiers. docs/legal/privacy.md §3 says none of the software's data is sent to MySummitKeep. Raw TCP ingress for SNI passthrough and DoT is not available on Container Apps' HTTP ingress, and its TCP ingress needs a VNet and cannot use 80 or 443. Windows DoH entries and custom names' A records pin one address, which DNS failover cannot move. Public DoT and DoH endpoints draw floods, and Azure's infrastructure protection is not tuned per customer. A roaming device's address is location data, including children's.
Decision
- Everything that runs on customer hardware is AGPL in this repository: the tunnel client, enrolment, the hosted-provider role mapping,
max_role, the node-held factor, relayed-stream restrictions, the CT watch, custom roles, locations, DNS-provider integrations, on-node ACME, device keys and onboarding, and (amended 2026-11-19) change verification and signer enrolment (ADR-1061), entry revisions, the merge and the cloud view (ADR-1063), platform-content verification (ADR-1062) and the managed-update helper (ADR-1066). The node stays fully usable without the cloud. - The broker, portal, issuer, certificate helper, the cloud resolver's multi-tenant shell and (amended 2026-11-19) the policy mirror, the change queue, the signing page and the content signer are separate programs in a separate repository, under a proprietary licence or FSL, speaking a protocol documented in this repository (
spec/14, T36.4), and they treat every node frame as untrusted input. They contain no AGPL code from outside the CLA and no AGPL third-party crates. Self-hosters keep Tailscale or Cloudflare Tunnel as documented free alternatives; whether the broker itself is published is the owner's decision. - Data: no query log at rest in the cloud. In home-relay mode the cloud never sees a query in clear; a later fallback resolver ships events home through a bounded memory buffer after the tenant's privacy level (ADR-102) and keeps counters only. The broker holds roaming devices' addresses in memory only and logs no per-connection or per-device address; it keeps hourly counters per tenant and device-key ID. The cloud stores identities, slugs, IDs, device-key IDs and DoT labels (never DoH keys), custom names, issuance records, tunnel metadata and counters (30 days) and its event log (1 year). MySummitKeep acts as processor under a DPA; one US region at launch under SCCs; an EU region on demand. Amended 2026-11-19 by the owner decisions on cloud writes: for linked clusters with
[cloud.sync]on, the cloud also keeps a per-tenant mirror of the synced policy kinds (ADR-1063 point 1; redacted as API-014 requires, no credential or stored secret, device bindings by opaque device ID with no MAC or IP matchers, local records only when the tenant opts them in separately, purged within 30 days of unlinking or of sync being turned off; encrypted at rest with keys the cloud holds, which protects against a storage leak and not against the cloud itself), the change queue and parked conflicts (until applied, resolved or expired, at most 14 days after parking), the public keys of enrolled signers, compiled list blobs for the cloud resolver, and, for tenants with the cloud resolver, the SHA-256 of each DoH key (ADR-1064 point 5; the resolver sees a raw key in each request path it answers and does not store it). The cloud resolver sees roaming queries in clear while it answers them (only while home is unreachable, which the node checks, ADR-1064 point 8), ships the events home through a bounded memory buffer after the privacy level and keeps counters only. - Launch platform: the portal and issuer on Container Apps (Consumption, HTTP ingress, managed certificate); the broker on two small VMs (active and warm standby) behind one dual-stack floating static edge address that a watchdog moves to the standby on failover (a Standard Load Balancer frontend when there are more VMs); B-series credit use measured, with a move to a non-burstable size on sustained deficit; DDoS IP Protection on the edge IPv4 from the beta; PostgreSQL Flexible B1ms; Azure DNS for the suffix with one wildcard record and the record-set limit increase requested in phase 2. Estimated about $41 a month at launch, $362 at 1,000 tenants and $1,432 at 10,000 (without DDoS protection $163 and $1,034; hosted.md's cost model, Azure retail prices of 2026-11-19, egress counted conservatively). Amended 2026-11-19: Microsoft Entra External ID for accounts (free to 50,000 MAU, ADR-1065) behind Azure Front Door Standard for
login.wrendns.com(about $35 a month base, not verified), an HSM-backed Azure Key Vault key for content signing (ADR-1062), and the cloud resolver as its own process on the broker VMs (ADR-1064), whose compute T36.12 measures before the totals are restated. - Tiers: self-hosted (free, AGPL), Cloud, Cloud Plus and Business as proposed in hosted.md, with device limits derived from the measured stream budget (ADR-1047 point 6) (amended 2026-11-19: the Cloud tier no longer says roaming fails closed, since the cloud resolver is in the MVP, ADR-1064; two-way sync and the cloud resolver are placed in Cloud by the design, the final placement being the owner's); no free cloud tier for roaming; the home keep-alive (ADR-1051 point 2) free for every tenant that ever linked; prices are the owner's.
- Before launch: the privacy policy gains a hosted-service section (including roaming addresses held in memory only), the terms gain the DPA and subprocessor list, and counsel reviews the licence split, COPPA and GDPR Art. 8 (ADR-1033 item 6).
Consequences
The protections tenants rely on are open and auditable; the paid service is a separate product. A competitor hosting a modified WrenDNS is bound by AGPL §13. The platform costs tens of dollars a month before the first customer; DDoS protection is the largest fixed cost from the beta. A failover moves one address and changes nothing on any device. Rejected: everything AGPL (no defensible paid service), the broker on Container Apps alone (no TCP 443 passthrough), DNS failover of tunnel. (pinned clients cannot follow) and a per-device address log (location history with no use the node does not already cover).
Requirements API-014
Builds on ADR-102 ADR-1033 ADR-1047 ADR-1051 ADR-1061 ADR-1062 ADR-1063 ADR-1064 ADR-1065 ADR-1066
Referenced by ADR-1047 ADR-1050 ADR-1055 ADR-1058 ADR-1059 ADR-1063 ADR-1064 ADR-1065 ADR-1070
Link to this decision · In the specification
ADR-1053 A plain-HTTP redirect listener for the HTTPS web UI: staged, TLS-only, validated Hostthe test Pis serve the UI and API on 443 with [api] tls.
Context
the test Pis serve the UI and API on 443 with [api] tls. http://host/ on port 80 should reach them. The API port already redirects plain requests on its own port (307), but a browser typing a bare name asks port 80.
Decision
[api] http_redirect: off by default, or a socket address such as"0.0.0.0:80". It opens a second, plain-HTTP listener that answers every request with a308tohttps://<the request's Host without its port>[:<the API's port when it isn't 443>]<path and query>, and/livez,/readyzand/healthzas the API port does (limited to[access] allowed_networkslike it). Nothing else is served; every response carriesCache-Control: no-store.- No open redirect. The
Hostheader is echoed intoLocation, so it must be a hostname (labels of letters, digits and hyphens; a numeric last label is refused unless the whole is an IPv4 address), an IPv4 address or a bracketed IPv6 address without a zone, with an optional numeric port, and exactly one Host header. Anything else (userinfo, a path, spaces, control characters, a second header) is a 400 with noLocation. The path and query come from the request line and can't change the host part. - Valid only with
[api] tls, and the address may not be[api] listenor have port 0: otherwise a validation error. A stored value whose TLS was removed later is ignored, not applied. - Guarded as a
stagedrow (api-http-redirect, ADR-914, ADR-956), notwindow: opening a listener that serves only a redirect cannot lock anyone out, so there is nothing to confirm through a new address; and the listener is started once with the API at start (like[api] listenandtls), so the change waits for the next start (Restart now where a supervisor is declared). It never weakens anything. A file value wins and locks the control. The UI field is on Settings -> System with the guarded card, with a help topic. - Failure. A bind failure (port 80 without
CAP_NET_BIND_SERVICE, or taken) is logged and affects neither DNS nor the API, and is not a failed start for the staged entry's probation. The systemd unit already grants the capability; Helm and Compose are documented only (no default ports). - Listener checks gain two plain-HTTP probes of the redirect listener:
GET /livezmust answer 200 andGET /must answer 308 with anhttps://Location. They are not DNS listeners and never count toward "not answering DNS".
Consequences
the config schema, the support-bundle classify table and docs/recovery.md list the new field and ID; no API route, MCP tool or OpenAPI change (the guarded routes carry any row); no new dependency. The API port's own same-port 307 still echoes the raw Host header; hardening it with the new validator is left for the owner to schedule.
Link to this decision · In the specification
ADR-1055 The AI-services catalog: in-house, authored from vendor documentation, kept in WrenDNS Cloud, with kinds, hostname roles, vendor-stated facts and a refusing validator, compiled per tenant into an opaque class map and per-group lists#42 asks for a curated AI-services catalog with sub-kinds, a vendor, a risk note and whether a business tenant exists.
Context
#42 asks for a curated AI-services catalog with sub-kinds, a vendor, a risk note and whether a business tenant exists. No maintained, openly licensed AI-services feed with kinds or metadata exists: UT1's ai list is about 75 flat domains with its licence unconfirmed at the source, AdGuard's HostlistsRegistry is GPL-3.0 (AGENTS rule 6, ADR-1033 §5), and commercial categorisation (Talos, DNSFilter, Sophos, Defender for Cloud Apps, OEM URL databases) forbids redistribution and would send queried names to another party. Vendor apex domains also carry marketing and docs, and many vendors list shared CDN fronts as dependencies. The owner decided on 2026-11-19 that the catalog is in-house from vendor documentation, that Shadow AI is commercial and hosted-only (ADR-1059), and that risk information is vendor-stated facts, dated and linked.
Decision
- The catalog is MySummitKeep's own data in WrenDNS Cloud's private repository (ADR-1052 §2), code-reviewed, with a
catalog_version; it is not in this repository and not AGPL. Every entry is authored from the vendor's own documentation and cites it (evidence,checked). UT1's list is only an input to the weekly job's "names to investigate"; AdGuard's registry is not used even as a reference; no third-party feed is used. - Kinds:
chat,api,coding,embedded,model_hosting,agent,local. Each rule has a role (app,api,upload,auth,static,download,vendor,dependency); onlyapp,apianduploadcount as use. Entries carryai_only,dns_visibility,tenant_split(hostname, header_only, none) with enterprise and consumer hosts or atenant_pattern,ambienthostnames recorded per OS family with anassistantflag,enterprise_option, and per-tier vendor-stated facts (trains_on_inputs,retention,region,jurisdiction). No computed risk score; the portal shows facts as "the vendor states (date, link)". - The validator refuses public suffixes (the Public Suffix List including its private section), a shared-infrastructure denylist (CDN and cloud fronts,
windows.net,cloudflare.com), subtree rules under protected parents by family (Google, Microsoft, GitHub, Apple, Amazon, Meta, X, as listed indocs/design/shadow-ai.md), avendorsubtree on anything but anai_onlyvendor's registrable domain, hostnames outside the vendor's registrable domains without a recorded justification, a display URL that is not https on the vendor's domains or a fixed allowlist, entries without evidence, and more than 2,000 services or 12,000 rules. Acheckeddate more than 90 days beforecatalog_versionwarns, never refuses. Tests include one refused entry per protected family. The same validator runs on a tenant's local entries, which are also capped (50 entries, 200 patterns), added only by a tenant admin (event-logged, never an agent), flagged as tenant-defined in the class map, listed separately on the node and not matched at privacy level 1 (ADR-1058 point 2). The catalog part of every class map is the same for all tenants, and its hash percatalog_versionis published on wrendns.com so a node can show that its map's catalog part matches. - Compilation, per tenant, in the cloud: a class map (patterns to opaque
u16class numbers, exact names and subtrees only, no metadata) for the node's export (ADR-1060), and two lists per group,ai-block-<group>andai-allow-<group>, from the group's policy (ADR-1057). Display URLs and metadata never reach the node. - Publishing is continuous: a reviewed change reaches every tenant's class map and lists within about a minute; a change may add names to a kind or service a group already blocks and never changes a group's mode; a bad change is rolled back by publishing the previous version.
- A weekly job resolves every rule, diffs the normalised extracted text of every evidence URL and opens one grouped issue for changes and one for candidates; nothing enters without review.
- The open node's
presets/services/ai.toml, ChatGPT'smessaging.tomlentry and theaicategory stay unchanged as the free node's basic AI blocking; nothing is migrated.
Consequences
Licence-clean, reviewable data whose breadth grows by our own curation (150 to 250 services at first, about 1,000 later, against commercial catalogues of 1,000+), updated without node releases. The catalog is not auditable by self-hosters, and a node holding a class map and lists can be read by its operator, so the hostnames are not secret, only the metadata and the curation. A standing curation cost. Rejected: a third-party open list (none fits; GPL or share-alike), a commercial OEM feed (cost, redistribution, privacy), the catalog compiled into the AGPL node (owner decision 2), one list per service (does not scale under MAX_LISTS), a risk score (implies judgment we cannot maintain). Supersedes the first draft's in-repository catalog, its migration and aliases, and its signed update channel.
Builds on ADR-1033 ADR-1052 ADR-1057 ADR-1058 ADR-1059 ADR-1060
Referenced by ADR-1060
Link to this decision · In the specification
ADR-1056 Shadow AI detection runs in WrenDNS Cloud on merged 5-minute activity bitmaps, with deterministic, evidence-carrying findings, confidence in words, a per-device visibility state and a first-use alert that groups and rate-limits itselfDNS lookups follow TTLs and connection reuse; prefetch and link previews trigger lookups without use; OS and browser assistants may contact AI hosts at idle.
Context
DNS lookups follow TTLs and connection reuse; prefetch and link previews trigger lookups without use; OS and browser assistants may contact AI hosts at idle. Clients split lookups across a cluster's resolvers and pods. Bypass (browser DoH, Private Relay, VPNs) makes use invisible. The owner decided that detection, findings and first-seen live in the cloud (decision 2), the use rule (decision 5), and that the default alert is every first use per device, quiet for the first day, with rate limiting and grouping (decision 8).
Decision
- The cloud ingests the node's export batches (ADR-1060) as untrusted input (ADR-1047 point 10), maps class numbers to (service, role) with the tenant's class-map version, and OR-merges day bitmaps per (tenant, device pseudonym, service, role, day), so the same period seen by two nodes, or a batch sent twice, counts once.
- Confidence in words: Confirmed (endpoint-agent confirmation, a later phase), Likely (use-role hostnames in at least 2 active 5-minute periods or on 2 days, on merged evidence), Possible, Visited (vendor only). A device "used" a service only at Likely or better. Ambient hostnames count only against devices of the OS family they were measured on; built-in assistant hosts put the device in an "OS assistant present" state never counted as use. Lowered by ambient hostnames, uncertain identity and device class. The ambient lab (T37.5) runs before the first release, on real iOS and Android devices as well as VMs, with the owner's own devices only with the owner's go-ahead.
- Volume is active time ("about"), never a count of requests. "Interactive or automated" is a "looks like" with evidence (roles, device class, the spread across hours of the device's own day bitmaps for the service, rhythm bins);
codingis never called automated. - A per-device visibility state (full, opted out by this network, partial, blind since, no data). The canary and Private Relay names are read against the node's reported
[special]switches; DoH bootstrap names and the node's quiet-while-present spans feed it (judged on the node, so no hourly counts or presence timeline leave it); "no data" marks the cloud's own gaps. Avisibility_gapfinding needs a quiet-while-present span and a known bypass sign, states only those facts and never refers to AI use. - First-seen per (device, service) and (group, service) is a row in the cloud's store holding the first-seen and last-seen dates, kept for the tenant's evidence retention after the last use, never longer. The alert
shadow_ai_first_usefires on each device's first Likely use of each service not approved for its group, with: a quiet first day after a fresh start (first Shadow AI day, a newly linked cluster, or turning it back on, since turning it off purges first-seen) ending in one baseline message; grouping per (group, service) for up to 15 minutes, naming up to 5 devices; a burst rule (more than 10 devices on one service in an hour becomes one service-level message); at most 10 messages an hour and 50 a day per destination, then an hourly summary; late data labelled, and older than 7 days sent to the digest only; mutes with an expiry. Allow and Block groups never alert. Recipients: email only to tenant members holding the Shadow AI permission; third-party destinations (webhooks, Slack-compatible, ntfy) get the service, group, a device count and a link unless a tenant admin opts in to device names; no message or digest carries the CMDB owner, an address or evidence. - People are named only from the CMDB
ownerthe node reports; names are resolved from the latest directory entry at read time; nothing is written back to the node. - ECH keys are not stripped from HTTPS answers: the resolver already sees the name.
- Unknown services (candidates) and local model servers are later phases with their own design notes; candidates would need names outside the class map to leave the node.
Consequences
No node logic and no query-path cost; findings are explainable and conservative, at the price of missing single-visit use, and arrive about 5 to 15 minutes after the second active period. A new install yields one baseline message, not hundreds. Rejected: detection on the node (owner decision 2), any lookup counting as use, an alert per service per group only (owner decision 8), automatic bypass blocking. Supersedes the first draft's node sink and primary-side merge.
Link to this decision · In the specification
ADR-1057 AI policy modes per group, kind and service: Off, Allow, Monitor and Block in v1; enforcement as two cloud lists per group; approved tenants only where hostnames separate them; Warn later#42 asks for Allow, Monitor, Warn and Block per group, exceptions per device, and approved tenants where the vendor separates them by hostname.
Context
#42 asks for Allow, Monitor, Warn and Block per group, exceptions per device, and approved tenants where the vendor separates them by hostname. There is no HTTPS block page (spec/00). ChatGPT, Claude and Gemini share hostnames across consumer and business tenants; GitHub Copilot separates plans by host and Azure OpenAI by resource subdomain. The cloud cannot change a node's configuration (ADR-1047 point 3) and authorization stays on the node (ADR-1049). The owner decided no Warn in v1 and approved tenants only where hostnames split.
Decision
- Modes Off, Allow, Monitor and Block, set in the portal per group with a default and per kind, overridden per service. Every group starts at Monitor when Shadow AI is turned on (ADR-1058).
- The cloud compiles each group's effective policy into
ai-block-<group>(kinds and services on Block, minus Allow overrides and approved tenants;dependencynames only with their service;vendornames only forai_onlyentries) andai-allow-<group>(exact names of approved services and tenants). They reach the node as cloud-published lists (ADR-1060) that an admin subscribes the group to once, on the node (on the LAN, or over a hosted name only under ADR-1049 point 3), the allow list a separate opt-in; later policy changes arrive as list contents. A group on Off is named in the cloud's batch replies so the node stops sending its devices. "Block all AI" coversai_onlykinds and services only. - Per-device exceptions are the node's device-scoped quick rules (ADR-067), reached from the portal through the remote UI.
- Approved tenants are offered only where
tenant_split = "hostname"; elsewhere the portal says the tenant isn't visible to DNS and points to the vendor's proxy-based control. No TLS inspection or header injection. - Explain on the node names the cloud list that decided an answer; the portal names the policy line behind it. Policy changes by agents are plans a human applies (ADR-994 §8).
- Warn is a later phase (FLT-904 reserved), with its own design note after T24.39; the first draft's Warn design (chat and agent only, browser names only, a node-side acknowledgement overlay after the security lists, a Monitor fallback) is its starting point, and it must keep working while the cloud is unreachable.
Consequences
Block costs nothing new on the query path. A group's policy takes effect only after the one-time subscription on the node, which the portal shows as "not linked on the node". A business cannot block personal ChatGPT while allowing its workspace by DNS, and is told so. Rejected: the cloud writing node configuration (ADR-1047 point 3), one list per service (MAX_LISTS), Warn in v1 (owner decision 10), a tenant control for every service (silently does nothing).
Builds on ADR-067 ADR-1047 ADR-1049 ADR-1058 ADR-1060 ADR-994
Referenced by ADR-1055 ADR-1060
Link to this decision · In the specification
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 everADR-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.
Context
ADR-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. Shadow AI is monitoring of people's internet use (New York §52-c, Connecticut §31-48d as rewritten by Public Act 26-73, Delaware §705, CCPA/CPRA, the UK ICO's guidance, BetrVG §87(1) No. 6, GDPR). With hosted-only (ADR-1059) per-device records reach MySummitKeep as the tenant's processor, including records of devices minors use. The owner decided: off until an admin turns it on and acknowledges a notice, then Monitor (decision 3); full per-device findings at level 1, matched before hashing, with an extra acknowledgement and the level-1 description saying Shadow AI is an exception; off at level 2 and above (decision 4); minors the operator's responsibility (decision 9).
Decision
- Off on a new tenant and every node. Turning it on takes a tenant admin in the portal, acknowledging a notice (what is recorded, that WrenDNS Cloud receives and keeps it, that the operator must tell the people monitored, a link to the notice template), and an admin on the node turning on the export, which shows what will be sent, on the LAN or over a hosted name only under ADR-1049 point 3 (a cloud in the middle must not turn on its own export). Neither is an agent's action. Then every group starts at Monitor.
- Privacy level 0: the export as ADR-1060. Level 1: the same, with names in the class map matched before they are hashed and device names sent in clear, after an extra acknowledgement on the node; tenant-defined patterns (local entries) are not matched at level 1, so the exception covers the catalog's AI services and not arbitrary names; this amends ADR-102 for this one export, and the level-1 description in the UI, the docs and the privacy notes say "Shadow AI findings are an exception" (the only Shadow AI wording in the open node). Levels 2 and 3: the export refuses to turn on and stops if the level is raised, discarding what is unsent; the portal says it needs level 0 or 1, keeps what it holds only to its retention and offers a purge of that cluster's data. Raising 0 to 1 pauses the export until the level-1 acknowledgement is given.
[exclusions]and[exclusions.log]both keep a device or name out of the export, which is an off-node per-device record like an event sink (OBS-903); the export's owngroupssetting limits it further.- No prompts, responses, file contents or filenames, ever; only names in the class map leave the node, as class numbers, at 5-minute resolution.
- The per-device views need the tenant's Shadow AI permission; the read scope
shadow_ai:readis in no default grant; every read of a device's history is in the tenant's event log; a tenant admin can export and purge per device or per CMDB owner, not as an agent operation. - A person is named only from the CMDB
owner. Minors: the operator's responsibility; Shadow AI is not marketed for children and parents are pointed to the node's categories and groups; counsel reviews COPPA and GDPR Art. 8 for Shadow AI's data before launch with ADR-1052 §6's review. - One notice template (records which AI services each device reaches by name and when, sends the record to WrenDNS Cloud for N days, never what is typed or uploaded), with optional fields for monitoring locations and the date given (Connecticut) and for categories and purposes (CCPA/CPRA). Counsel reviews it, the vendor-facts wording and the data model before sale (ADR-1033 item 6).
Consequences
No one is monitored by accident and the idle memory gate is untouched by default. Level 1 is no longer "every name hashed" for an operator who turns Shadow AI on, and says so. Rejected: Monitor on by default (monitoring without an informed choice), off at level 1 (owner decision 4), per-group counts only at level 1 (owner decision 4).
Requirements OBS-903
Builds on ADR-102 ADR-1033 ADR-1049 ADR-1052 ADR-1059 ADR-1060
Referenced by ADR-1055 ADR-1057 ADR-1060
Link to this decision · In the specification
ADR-1059 Shadow AI is a commercial, hosted-only feature of WrenDNS Cloud: the boundary, what the cloud keeps and for how long (amends ADR-1052 §3 and ADR-1047 point 8), latency, offline behaviour and tiersThe first draft made every Shadow AI feature free in the AGPL node and sold a signed catalog update channel.
Context
The first draft made every Shadow AI feature free in the AGPL node and sold a signed catalog update channel. The owner decided on 2026-11-19 that Shadow AI is commercial-only and hosted-only: detection, policy evaluation, findings, reports and the catalog live in WrenDNS Cloud (ADR-1052's proprietary service), computed from data the node sends; the open node gains only a small generic export; enforcement comes back as ordinary group policy; and the cloud's data model changes ADR-1052 §3 ("no query logs or per-device address logs at rest, hourly counters only"). ADR-1047 point 8 says the portal never renders node data and that a fleet view would be "an opt-in summary push". ADR-1052 §1 keeps everything that runs on customer hardware AGPL.
Decision
- Boundary. The catalog, detection, confidence, findings, policy, pages, alert, digest, API and MCP tools are in the service's repository under its licence. The open node gains the generic name-class counters export and cloud-published list sources (ADR-1060), AGPL, with no Shadow AI logic or catalog (its only Shadow AI wording is the level-1 description and acknowledgement that owner decision 4 requires). Everything the node already has (the
aicategory,ai.toml) stays free. - What the cloud keeps, amending ADR-1052 §3 by the owner's decision. For tenants that turn Shadow AI on: daily evidence rows per (device pseudonym, service, role, day) with the merged 5-minute bitmap, lookup and blocked counts and rhythm bins, 90 days by default (7 to 365 by the tenant); findings no longer than their evidence; first-seen rows (first-seen and last-seen dates) for the evidence retention after the last use, never longer; a device directory, only for devices with class-map matches (pseudonym, name, group, class, OS family, identity certainty, CMDB owner, latest private LAN address only), until 30 days after its last evidence row expires; quiet-while-present spans as the evidence rows; alert and digest bodies as the evidence rows, with the fact of sending (time, destination, kind, counts) 1 year in the event log; notice acknowledgements for the tenant's life plus 1 year. Never kept: names outside the tenant's class map, query timestamps, answers, public or roaming addresses, hourly activity or presence timelines, content. MySummitKeep uses the data only to provide that tenant's Shadow AI: never across tenants, for catalog curation, model training, benchmarking or marketing. Turning Shadow AI off, removing the add-on, unlinking or deleting the tenant starts a purge of every Shadow AI row at once, complete within 30 days; point-in-time backups age out after that. For every other tenant ADR-1052 §3 is unchanged.
- ADR-1047 point 8 is amended: the portal renders Shadow AI data derived from the opt-in export (the "opt-in summary push" it anticipated); it still never renders other node data.
- Latency: export every 5 minutes (plus up to 60 s of jitter); a Likely finding about 5 to 15 minutes after the second active period; alerts after grouping (up to 15 minutes); a policy change in the portal on the node's answers in about 20 to 60 s (ADR-1060's heartbeat hint), hourly at worst while heartbeats fail.
- Offline: DNS never depends on the cloud. With the cloud unreachable the node keeps its last good class map and lists and buffers batches on the primary (at most 7 days or 4 MiB, oldest dropped); the cloud shows the gap and qualifies findings in it; late first uses are labelled, and older than 7 days go to the digest only. On cancellation the lists are frozen, never emptied: served unchanged for 90 days, kept by the node after that, with "Keep as a local list" and "Unsubscribe" on the node.
- Tiers: a paid add-on for Cloud and Cloud Plus and included in Business (the design's placement; the final placement and every price are the owner's). It needs a linked cluster (M36).
- Never sold: a risk score, a third-party feed, anything that makes DNS depend on the cloud.
Consequences
Shadow AI is a defensible paid product and the open node stays small and generic; self-hosters without the cloud get no Shadow AI, only the existing ai blocking. MySummitKeep becomes a processor of per-device monitoring records, which raises the stakes of the DPA, the privacy policy's hosted-service section, COPPA and GDPR Art. 8 review, breach handling and the service's security. The cloud's storage grows by a few MB per tenant. Rejected: every feature free in the node with a paid catalog channel (the first draft, superseded by owner decision 2), counts only in the cloud (owner decisions 2 and 4 want per-device findings), a query log in the cloud (more than detection needs). Supersedes the first draft's ADR-1059 entirely, including its amendment of ADR-995 and the delayed-open option.
Builds on ADR-1047 ADR-1052 ADR-1060 ADR-995
Referenced by ADR-1047 ADR-1055 ADR-1058 ADR-1060
Link to this decision · In the specification
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 changesOwner 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".
Context
Owner 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". The cloud needs per-device evidence for catalogued names only, and the node cannot match names it doesn't have; sending every name would be a query log in the cloud. Lists are already downloaded at runtime (ADR-995 §4) and kept on failure (FLT-004, OBS-023). The first version of this ADR had the cloud publish two lists per group that a LAN admin subscribed to once, because the cloud then never wrote configuration. Owner decision D (2026-11-19, with the decisions on cloud writes): Shadow AI Block and Allow become ordinary signed policy changes (ADR-1061, ADR-1063), replacing the subscribed lists; catalogs reach the node over the platform channel signed by the content key (ADR-1062).
Decision
- The name-class counters export (
[cloud.export], OBS-904), off by default, admin-only, guarded, never for agents. The node requests the class map up the tunnel and receives it as platform content signed by the content key (scopeclass_map, ADR-1062): exact names and subtrees mapped to opaqueu16class numbers, each class with up to 4 opaqueu8tags (at most 64 tags; the cloud uses them for kinds), at most 12,000 patterns and 2,000 classes; public suffixes and anything else refused; the last good map kept. Enforced on the node (added 2026-11-19 after the security review): a class map whose content envelope names any tenant but*is refused, so the same map for everyone is checked rather than promised; the node ships the catalog validator's protected-parent and shared-infrastructure denylist as generic data and refuses a subtree under any of them; a version that adds more than 1,000 patterns to the map held is held for 72 hours with a notice unless an admin releases or refuses it sooner (ADR-1062 point 3). The map is the catalog part only and is the same for every tenant, so the hash the service publishes for eachcatalog_versionidentifies it exactly. Tenant-defined patterns are not content: they are the synced kindclass_local(at most 50 entries and 200 patterns), changed only by signed changes (ADR-1061) and flagged tenant-defined, and they are not matched at privacy level 1. On the telemetry thread the node matches each drained event's name once (a suffix match, up to one FST probe per label). Per (device, class, UTC day) it keeps a 288-bit bitmap of 5-minute periods, the lookup count and blocked count, and 8 rhythm bins. For each device with a class-map match in the last 7 days, and no other, it keeps a directory entry (a pseudonym keyed on the node, display name, group, device class, OS family, identity certainty, CMDB owner, latest private LAN address only) and quiet-while-present spans (present by lease, neighbour table or inventory while its lookups are under 10% of its own 7-day median for at least 2 hours; start and end to 5 minutes, with any bypass sign), judged on the node so no hourly counts or presence timeline leave it. Per batch it sends the[special]switch states and the privacy level.[exclusions],[exclusions.log]and the export'sgroupssetting are honoured, and the cloud's batch reply may name groups to omit, which only ever narrows what is sent. At most 4,096 pairs, 64 classes per device and 1,024 devices per class. The primary OR-merges members' bitmaps, resolver pods included, through the federated read (ADR-053) and sends one batch per cluster every 5 minutes as control frames on the tunnel, buffering at most 7 days or 4 MiB on disk; an emergency primary sends nothing. Privacy levels as ADR-1058 point 2. Nothing on the query path;QueryEventunchanged. - Class rules (FLT-903, generic): the synced kind
class_rule{group, action: block | allow, classes: [u16], tags: [u8] (block only)}. For each group the node compiles a block set (the patterns of the named classes and tags, from the class map andclass_local) and an allow set (only the exact names of the named classes; a subtree in an allowed class is ignored and reported, and a name a security or threat list blocks is dropped and reported). Both are compiled into the snapshot like lists, so replicas and resolver pods enforce them without receiving content (as ADR-994 point 10). The Lists page shows them as "class rules of <group>", with the class map's version, size and the diff of each change; Explain names the class rule; every change is in the audit log. - Block and Allow are signed policy changes (owner decision D). Every change to a class rule or a
class_localentry is a cloud change signed with the editor's change-signing passkey (ADR-1061), merged and applied on the primary as ADR-1063 says, under the editor's node role; it needs[cloud.sync]with those kinds in its allowlist and no other subscription. Turning the export on stays an admin-only guarded change made on the LAN (or by commit on a Git-managed cluster). The platform channel never changes a class rule: new class-map content can change which names a class or tag holds, within the caps, but never which classes a group blocks or allows, and allow rules name classes only, never tags, so content can widen a kind-level Block but never an Allow. - Extending ADR-1047: down the tunnel the cloud may also return the signed class map the node asked for, and the cloud's heartbeat acknowledgement carries its current version so the node fetches a change within about one heartbeat (point 5); with no hint the node polls hourly.
- Frozen, never emptied. When the class map stops being updated (cancellation, unlinking, an expired map), the node keeps its last good copy and shows "class map no longer updated" (the one exception: a map signed by a content key revoked as compromised after its
compromised_aftertime is dropped for the last map signed by a valid key, ADR-1062 point 2); class rules are the tenant's own configuration and stay. The node offers "Convert to local lists" (each group's compiled block and allow names written as ordinary inline lists) and "Remove class rules". - Both features are documented in
spec/14(the frames and objects) and in the node's docs ("What the node sends"), with a "show the last batch" view, and work for any hosted analytics or managed policy, not only Shadow AI. - What this replaces elsewhere: ADR-1055's per-tenant compile now covers only the catalog part, identical for every tenant (point 1), with tenant local entries as
class_local; ADR-1057's two cloud lists per group become each group's class rules (point 2); ADR-1059's "cloud-published list sources" and its frozen lists read as class rules over the frozen class map.
Consequences
The node stays generic and auditable; the cloud learns only catalogued names, as numbers, at 5-minute resolution. A Block or Allow cannot be created by the cloud on its own: it needs an editor's signature and the editor's node role. A compromise of the content key, or misuse of its sign operation by a compromised service, could put any name that is not a public suffix or under a protected parent into a class (so the export reports it and a kind-level Block covers it) within the caps, for every tenant at once and never for one alone; revocation drops what it signed after compromised_after; the hold on large additions, the visible diffs, the published hash of the catalog part (the same for every tenant, so a pattern aimed at one tenant stands out), the audit log and the export's LAN opt-in limit this but do not remove it, which is part of trusting the service. Rejected: the subscribed ai-block-<group> and ai-allow-<group> lists (owner decision D), the cloud pushing configuration unsigned (contradicts ADR-1049's "an issuer compromise on its own is useless"), sending every name (a query log in the cloud), a node-side catalog (owner decision 2), per-service lists on the node (MAX_LISTS), and tags in allow rules (content could then widen an Allow).
Requirements FLT-004 OBS-023
Builds on ADR-053 ADR-1047 ADR-1049 ADR-1055 ADR-1057 ADR-1058 ADR-1059 ADR-1061 ADR-1062 ADR-1063 ADR-994 ADR-995
Referenced by ADR-1055 ADR-1056 ADR-1057 ADR-1058 ADR-1059 ADR-1062 ADR-1063 ADR-1064
Link to this decision · In the specification
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)The 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.
Context
The 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. Approval is the editor's signature alone, and a compromised cloud or identity provider can delay or drop changes but cannot create or alter them. Microsoft Entra External ID (ADR-1065) runs its own sign-in ceremony with its own challenge and reports only amr=fido; its credential management API registers and deletes passkeys, and its list response carries no public key, so it cannot give a raw assertion over our challenge. A WebAuthn RP ID must be the page's host or a registrable suffix of it, never an IP address, so a LAN hostname (node1.home.example, 192.0.2.10, a .local name) can never be one; the hosted name <slug>.<suffix> can, and it reaches the node at home (split horizon) and away (the relay, which does not decrypt). Verification is plain public-key cryptography: the RP ID is only a hash in authenticatorData and the origin a string in clientDataJSON, so a node can verify offline. Synced passkeys report signCount 0. WebAuthn has no trusted display of what is signed (txAuthSimple was removed in Level 2; Secure Payment Confirmation covers payments only), so the page that shows the change decides what the editor believes they sign. The security review of 2026-11-19 found that a page the portal serves cannot be that page: the portal serves the HTML that carries any Subresource Integrity hashes, and at enrolment its own script computes the fingerprint it shows and sends the public key, so a compromised portal could swap both and break A(1)'s "cannot create or alter". Tailscale's tailnet lock is the closest prior art: the control plane relays, signer keys live on user devices, nodes verify. ring (ECDSA P-256, RSA) and ed25519-dalek are linked.
Decision
- Where a change is signed (security review decision 1, confirmed by the owner 2026-11-19). Whenever home is reachable, on the node's own signing page at
https://<slug>.<suffix>/cloud/sign/<change id>(also served at<node>.<slug>.<suffix>), served by the node through the relay away and directly at home. The portal sends the node a proposed change (an unsigned patch that changes nothing, ADR-1047 point 3) and opens that page. The node works out the diff from the patch and its own current entries, renders the summary itself with a fixed rendering of the ops, builds the envelope and asks for an assertion with RP ID<slug>.<suffix>; the page needs a node session (over the relay, ADR-1049 point 2's hosted sign-in plus node-held factor). Altering that page needs a certificate for a UI name, which the CT watch reports (ADR-1051 point 6). Only while no member of the cluster is connected, an edit is signed onsign.wrendns.com, a host that serves nothing but the signing page (its own RP ID, a strict CSP, no third-party script), with the editor's portal signing passkey; the envelope sayssigned_at: "portal", and the node treats every such change as high-risk (point 6). Subresource Integrity is not claimed as a defence. - Signing passkeys, never Entra's: a node signing passkey (RP ID
<slug>.<suffix>; it may be the same credential as the editor's node-held sign-in passkey, ADR-1049 point 2, because only the node's pages issue either challenge and signing challenges are domain-separated hashes) and an optional portal signing passkey (RP IDsign.wrendns.com). Requests useuserVerification: "required"andattestation: "none"; the AAGUID (shown as the authenticator's model) and the BE and BS flags are recorded for display only, since withattestation: "none"they are unverified. A per-site "device-bound signers only" option that requires attestation is left for a later business tier. Accepted algorithms: ES256 (-7), EdDSA (-8) and RS256 (-257, for older Windows Hello). - Enrolment on the node, once, at home (owner decision A(1); security review decision 4, confirmed by the owner 2026-11-19). A node signing passkey is registered on the node's own page, so the node receives the COSE public key from the browser directly. A portal signing passkey is registered on
sign.wrendns.comand its credential ID, COSE key, AAGUID, flags and hosted subject come down the tunnel as a signer request. Either is pending until confirmed in a session made on the LAN (ADR-1049 point 2) with a step-up: the editor's own node-held factor, or a LAN admin's own factor (passkey, TOTP or local password) together with the 6-character presence code shown on the editor's enrolment page on the node. A hosted sign-in alone never confirms a signer. A confirmed signer's changes apply only after a cool-off (4 hours by default, 1 to 24 hours per site), and the node sends its ownsigner_addedalert to every destination it holds; that rule is guarded and cannot be turned off while sync is on. Signers are a replicated, guarded kindchange_signer(key ID, kind node or portal, RP ID, subject, public key, algorithm, AAGUID, BE, who confirmed it and how, when, cool-off end), never synced from the cloud and never for agents. A signer is removed by its own signed change, by an admin's signed change or by a LAN admin, and is refused at once after that; unmapping or disabling the subject (ADR-1049 point 2) disables its signers, including on a cloudSubjectDisablednotice, which disables and never deletes them (amended 2026-11-19 by ADR-1069 point 5); a signer enrolled during onboarding under a group rule is confirmed by an admin-signed invitation or by the factor of a subject a node admin approved on the LAN, never by a factor enrolled from a hosted sign-in alone (revised after the identity security review), and itssigner_addedalerts are grouped into one per 15 minutes per cluster (ADR-1069 point 8); a tenant admin may suspend a signer in the cloud resolver from the portal (ADR-1064 point 6). Two node signing passkeys per editor are recommended. There is no cloud escrow and no recovery code: a lost passkey is replaced by enrolling a new one at home, and until then that editor's remote changes wait. A portal signing passkey's key passes through the cloud, so it is trusted at registration, as tailnet lock trusts its control plane; this is stated in the threat model. - The signed envelope, canonical JSON (RFC 8785, JCS):
{v: 1, tenant, cluster_id, change_id (UUIDv7), signed_at ("node" | "portal"), qseq (portal-signed only), signer_key_id, subject, created, not_after, nonce (16 random bytes, single use: from the node for node-signed changes, from the cloud for portal-signed ones), roaming_now (ADR-1064 point 6), summary (the text shown to the editor), reads: [{kind, name, hash}] (the read set, ADR-1063 point 4), entries: [{kind, name, base: {rev, hash} or null for a create, ops}]}. The challenge isSHA-256("wrendns-change-v1" || 0x00 || JCS(envelope)), and every verifier recomputes it from the envelope it received. Ops are per-entry patches (ADR-1063 point 4), not whole bodies, so a merged result still applies exactly what was signed. The node parses envelopes with a strict I-JSON parser that refuses duplicate keys and unknown fields, and refuses (never normalises) a domain name that is not lowercase A-labels without a trailing dot, so the bytes signed are the bytes applied. A change holds at most 2,000 ops and 1 MiB. - Verification on the primary, before anything else: parse
clientDataJSON;type == "webauthn.get";challengeequals the recomputed hash;originis exactly one of the cluster's own hosted origins (https://<slug>.<suffix>,https://<node>.<slug>.<suffix>) withrpIdHashof<slug>.<suffix>for a node signer, or exactlyhttps://sign.wrendns.comwith itsrpIdHashfor a portal signer, matchingsigned_at;crossOriginabsent or false andtopOriginabsent; UP and UV set; the assertion's credential ID equalssigner_key_id; the signature overauthenticatorData || SHA-256(clientDataJSON)verifies with that signer's key. Then: the signer is enrolled, not removed, past its cool-off; the envelope'ssubjectequals the signer's enrolled subject, and that subject is mapped (ADR-1049 point 2) (amended 2026-11-19 by ADR-1069 point 3: or granted by an active group rule, and in either case not disabled; the role is then the hand mapping's or the rule's); the role comes from the signer's enrolled subject only, and that role, under the hosted provider'smax_role(security review decision 7, confirmed by the owner 2026-11-19), permits every(kind, verb)in the change (ADR-1049 point 5); every kind is in the sync allowlist (ADR-1063 point 1); every read-set hash still matches;not_afterhas not passed, judged against a time never earlier than the latest authenticated time the node has seen (NTS where configured, the platform timestamp of ADR-1062 point 2), so a node without a clock cannot be made to accept a change the cloud held back;qseq, when present, is above the cluster's high-water mark; the change ID is in no row's origin; for a portal-signed change,summaryequals the node's fixed rendering of the ops. Any failure is Rejected with a reason code and audited; nothing applies. - High-risk changes and approval. Approval is the editor's signature alone (owner decision A(1)); there is no two-person rule by default. High-risk changes are: filtering turned off for a group, a block list removed, an allow rule on a subtree, a cloud allow that overrides a block whose origin is home, a block of a whole top-level domain or of a public suffix's subtree, any change to the default group,
[special]and safe search, alert rules, a group deleted, and every portal-signed change. A per-site option, off by default and set on the LAN, asks for confirmation in a LAN session for high-risk changes; whether or not it is on,cloud_change_appliedfires for each of them. - The display gap, and what remains. For node-signed changes the node renders what is signed, so the gap is closed except against a cloud that mints a certificate for a UI name and sits in the middle while the editor signs (reported by the CT watch, then remote access is blocked). It stays open for portal-signed changes, made only while home is unreachable. Limits in both cases: the node applies only synced kinds, only within the signer's permissions, never guarded settings (ADR-1049 point 3); every applied cloud change is listed on the node (Settings → WrenDNS Cloud → Changes from the cloud: signer, subject, where it was signed, time, and the node's own rendering of the diff) and is an event; the alert rules
cloud_change_appliedandsigner_addedare guarded and never synced (ADR-1063 point 1), so a change cannot switch off or retarget the alert that reports it; and point 6's high-risk handling. Together with relayed-session writes to kinds that are not synced under a minted certificate (ADR-1049 point 3), these are the ways a compromised cloud can still cause a change; the threat model states them. - Audit. The node's hash-chained audit records
oidc:<issuer>/<sub> via cloud, the change ID, the signer key ID, where it was signed, the envelope and the assertion, so anyone holding the signer's public key can verify the entry later. - No new crate expected:
ringanded25519-dalekverify, and a bounded reader in the node parses the COSE key andauthenticatorData; T36.15 reports the image delta and runscargo-denyif it needs one after all.
Consequences
A compromise of the cloud's back end (queue, mirror, broker, database) or of Entra can delay or drop changes but cannot create, alter, replay or reorder one. A compromise of the portal front end can no longer alter a change signed while home is reachable without also minting a certificate the CT watch reports; it can still alter a portal-signed change made while home is down, or substitute a portal signing key at registration, and those changes are high-risk. Remote editing needs a passkey enrolled at home first, a node session for the signing page, and a second passkey prompt besides sign-in; a new signer waits out its cool-off. Rejected: reusing the Entra sign-in passkey (Entra gives no raw assertion; capturing its key at registration relies on an RP-ID override Microsoft documents only as current behaviour, and an Entra admin deletion would silently orphan the signer), RP ID wrendns.com (any subdomain, including docs and the login host, could ask for a signature), signing every change on a portal page (a compromised portal controls what is shown and any SRI hashes; the first version of this ADR), comparing a fingerprint the portal computes (the portal can show its own key's fingerprint), the WebAuthn counter for replay (synced passkeys report 0), cloud escrow or a cloud-held recovery key (the cloud must not be able to sign), passkeys for LAN hostnames or addresses (they cannot be RP IDs; the first version rejected node-local passkeys for this reason, which does not apply to the hosted name), and Related Origins (a static allowlist, not supported by Entra, partial browser support).
Builds on ADR-1047 ADR-1049 ADR-1051 ADR-1062 ADR-1063 ADR-1064 ADR-1065 ADR-1069
Referenced by ADR-1047 ADR-1049 ADR-1052 ADR-1060 ADR-1062 ADR-1063 ADR-1064 ADR-1065 ADR-1068 ADR-1069
Link to this decision · In the specification
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)Owner 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.
Context
Owner 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. Separate signing keys are pinned on the node, the existing release key for binaries and a new content-signing key for catalogs and lists, each limited to its purpose, with offline roots, rotation and revocation. It only delivers signed content and runs actions the owner opted into, and can never change user policy. The release key (ADR-1034, minisign Ed25519) stands alone with no root above it, so rotating it means reinstalling through install.sh. ADR-1060's cloud lists were authenticated only by the tunnel's TLS to the broker. Azure Key Vault has no Ed25519 keys; ring verifies ECDSA P-256.
Decision
- Scope. The platform channel carries signed content (the class map, ADR-1060; lists a node subscribed to from MySummitKeep), signed release notices for opted-in managed updates (ADR-1066), the certificate keep-alive (ADR-1051, unchanged: the node's own CSR) and hints (current versions in the heartbeat acknowledgement). It runs only actions the node's owner turned on in guarded settings on the LAN. It never changes user policy: a platform signature never authorizes a cloud change or any write to configuration, and a passkey assertion never authorizes content. Platform frames are their own tunnel frame types with their own verifier.
- Keys.
- The root: two offline Ed25519 keys held by the owner (either may sign), made in a ceremony like ADR-1034's and never online. Their public keys ship in the next release beside
RELEASE_KEY. - The key manifest, signed by a root key:
{seq, issued, expires (1 year), keys: [{id, alg, public, scopes, not_before, not_after}], revoked: [{id, compromised_after}]}, published on wrendns.com and delivered over the tunnel. A node keeps the highest-seqmanifest that verifies, and always fetches it from wrendns.com too (hourly, off the DNS path), so a cloud that withholds manifests over the tunnel cannot hold back a revocation. - The release key (ADR-1034), scope
release:SHA256SUMSandreleases.jsononly. - The update key (added after the security review; security review decision 3, confirmed by the owner 2026-11-19): an owner-held hardware key, scope
release_auto, whose signature a release needs in addition to the release key's before managed updates may install it (ADR-1066 point 1). - The content key: EC P-256, non-exportable, HSM-backed in Azure Key Vault, scopes
class_mapandlists, delegated by the manifest for 90 days at a time. Only the catalog publishing pipeline, with its own identity and triggered by a reviewed catalog commit, may call its sign operation; misuse of that API by a compromised service is the likelier threat than theft of the key. - The timestamp key (added after the security review): Key Vault, scope
timestamp. Every hour it signs{manifest_seq, streams: {stream: seq}, issued, expires (24 hours)}, the timestamp role of The Update Framework. A node whose freshest statement has expired, or that holds less than a statement names, raisesplatform_stale(degraded) rather than trusting a frozen view; its time also serves as a lower bound on the node's clock (ADR-1061 point 5). - Rotation is a new manifest; a revoked key ID is refused at once. Revocation undoes what a stolen key signed (security review decision 8, confirmed by the owner 2026-11-19): content that a revoked key signed after its
compromised_aftertime is dropped, and the node falls back to the last content of that stream signed by a valid key, or to none for that stream with severe health. This is the one exception to the freeze rule, because a frozen malicious class map would otherwise stay "last good" indefinitely. When the newest manifest a node holds has expired, it refuses new content, keeps the last good copy of everything it holds (never empties a list or a map), raises the degraded reasonplatform_keys_expiredand keeps verifying releases with keys still inside their own validity.
- The root: two offline Ed25519 keys held by the owner (either may sign), made in a ceremony like ADR-1034's and never online. Their public keys ship in the next release beside
- The content envelope:
{scope, tenant ("*" for public content), stream, seq, issued, expires, sha256, size}, signed over"wrendns-content-v1" || 0x00 || JCS(envelope). The node refuses a wrong scope, another tenant, aseqnot above the one it holds (rollback) and anything already expired on arrival; when what it holds expires, it keeps the last good copy (the freeze rule) and says so. The content type's own caps (ADR-1060 point 1's map limits) apply after the signature check. Scope rules enforced on the node (added after the security review):class_mapcontent must carry tenant*; the node refuses a map with a subtree under the protected-parent and shared-infrastructure denylist it ships; platform-signedlistsare never accepted as allow sources, so content can never widen an Allow; and a version that adds more than 1,000 patterns to what the node holds is held for 72 hours with a notice, which an admin may release or refuse sooner. - Self-hosted nodes use the same root and release key for
self-update(ADR-038) andinstall.sh, fetching the manifest from wrendns.com; nothing needs the cloud.
Consequences
A compromise of the online service (portal, broker, mirror, queue) cannot sign content or releases, though it could misuse the content key's sign operation if it reached the publishing identity. A compromise of the content key can change which names a class holds, within the caps and the node's denylist and for every tenant at once (and so widen a kind-level Block, ADR-1060), until it is revoked, and revocation then drops what it signed; it can never allow a name or change which classes a group blocks. A compromise of the release key alone cannot install anything through managed updates. Every key can rotate without reinstalling nodes. The owner gains a root ceremony, a hardware update key and two Key Vault HSM keys. Rejected: signing content with the release key (an online key would put every binary at risk), an Ed25519 content key in software inside the service (no HSM), tunnel TLS alone (ADR-1060's first version), and one key for everything.
Builds on ADR-038 ADR-1034 ADR-1051 ADR-1060 ADR-1061 ADR-1066
Referenced by ADR-1047 ADR-1052 ADR-1060 ADR-1061 ADR-1066
Link to this decision · In the specification
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 editsOwner 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.
Context
Owner 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. Today API writes are rows in the primary's state.db managed(kind, name, body, updated, updated_by) (ADR-040); shared rows travel whole in the node_managed blob of the signed manifest (ADR-1016), without node_only rows (ADR-052); a promoted primary adopts that blob (ADR-1016, ADR-1019). If-Match carries one node-local counter (config_version in meta, crates/wrendns-store/src/state/managed.rs) with no epoch, so after a failover a stale tag from the old primary could match the new primary's counter by coincidence (found by reading the code, not yet tested), and any change anywhere fails every concurrent write with 412. Idempotency-Key rows are node-local. ADR-054 says a write with no primary is never queued. in_sync skips witnesses (ADR-1011). The history keeps 20 manifests.
Decision
- Scope. Off by default;
[cloud.sync]is guarded, admin-only, set on the LAN and never for agents, with a per-kind allowlist. Synced kinds, the everyday policy of owner decision A(1), ticked when sync is turned on: groups (their filtering fields), quick rules, lists (definitions with no credential; a list source added by a cloud change must behttpsto a public address), schedules, alert rules (never a destination's secret; destinations are shown by name) other than the guarded ones below, categories and profiles,[special]and safe search, block responses, device-to-group assignment, and class rules (ADR-1060). Revised after the security review (security review decision 6, confirmed by the owner 2026-11-19): device-to-group assignment syncs by opaque device ID, display name and device-key ID only, never a MAC, IP or hostname matcher; local records made through the API are a separate opt-in, not ticked by default, because they describe the internal layout. Never synced: guarded settings (listeners, TLS, cluster, secrets, auth,[cloud]), users, tokens, roles and signers, the guarded alert rules (cloud_change_applied,signer_added, and alerts on signer, audit and cloud events; so no cloud change can switch off or retarget the alert that reports it), node-managed entries (ADR-968),node_onlyentries (ADR-052), anything holding a credential, upstreams and forwards, discovery and the CMDB, and entries defined in files (shown read-only in the portal as "from the node's files"). - Entry revisions. Every managed row gains
rev = (epoch, n),body_hash(SHA-256 of the JCS body),origin(lan:<user>,cloud:<change_id>,adopted:<seq>) and a tombstone kept 30 days. They ride in thenode_managedblob as additive fields (the document stays version 1 and older nodes ignore them, CLU-010). Equality is judged bybody_hash, never byrev, so adoption (ADR-1016, ADR-1019) and failovers do not make every entry look changed. - The ETag carries the epoch:
"<epoch>.<n>"instead of the node-local counter, plus a per-entryIf-Matchon entry routes. This also closes the stale-tag case above; T36.16 writes the failing test first. - Merge on the primary, entry by entry, of the signed patch (ADR-1061 point 4; ops
create,delete,setof top-level fields, andaddandremovefor set-valued fields such as domain lists and members):- the entry's
body_hashequals the base hash: apply (the fast path); - home changed the entry, but no field the patch sets was changed at home, and no element is added on one side and removed on the other: apply the patch onto home's body (merged automatically);
- otherwise (the same field changed to different values on both sides, a delete against an edit, a create of a name that exists with another body): a conflict, and home wins.
- a non-null base whose entry no longer exists because its tombstone was purged is a conflict, never a create, so a deleted entry cannot come back.
- The read set (added after the security review): the envelope names, with their base hashes, the entries a change refers to without editing them (the target group of a device assignment, a list a rule names); if any of them changed, the change is a conflict. This catches conflicts between entries, such as a device moved into a group whose filtering home has just turned off. A cloud allow that overrides a block whose origin is home is high-risk (ADR-1061 point 6) and flagged on the node. A change is atomic: if any entry conflicts or the result fails validation, nothing of it applies. A change over 2,000 ops or 1 MiB, or whose compile would exceed the node's memory gate (ADR-1031), is Rejected. A conflict answers with home's current body and revision; a validation failure is Rejected with the reason (as a 422 would).
- the entry's
- Conflicts are parked in the portal (owner decision B), with home's version beside the cloud edit and three resolutions: keep home's (the edit is discarded), apply mine (a new change based on home's current revision, signed again), or edit and merge (edited in the portal, then signed). A parked change nobody resolves expires after 14 days and home's version stays. The node records each conflict in its audit log and holds nothing parked.
- States. Pending: in the cloud's queue, or delivered and not yet committed. Applied: committed by the primary in the stable head
(e, s); while a staged rollout runs (ADR-116), shown as "in canary" until it reaches the stable head. Accepted: every member thein_synccheck counts (witnesses skipped, ADR-1011; resolver pods counted) and the cloud resolver's copy (ADR-1064; when the tenant has one) report a version at or above(e, s). Terminal: Rejected (with the reason), Conflict (parked) and Expired. Ten minutes after Applied without Accepted, the portal shows "Applied, waiting for <node>"; the cluster's existing lag reasons are unchanged. The portal reads every state from the primary's acknowledgements. - The queue (amends ADR-054's "never queued" for cloud-origin changes only; LAN writes keep the 503). The cloud keeps an ordered queue per cluster; each change carries its
qseq, base revisions, change ID andnot_after. It is delivered in order, only to the primary whose signed lease a majority of the tenant's tunnels confirm (ADR-1048 point 6), naming the expected epoch. A replica, a node at another epoch, an emergency primary (ADR-048) and a pinned cluster (ADR-116) refuse, and the change stays Pending until it expires; an expired change is never delivered and the editor is told. On a Git-managed cluster a change is Rejectedgitops_managedand the portal shows the TOML to commit (keepInGit). The user sees Pending, never a failure that later applies, which answers ADR-054's concern. - Idempotent across failovers. The change ID is stored in the row's origin, which replicates, and the
qseqhigh-water mark rides in the blob, so a re-delivered change never applies twice. A new primary that lacks a change committed by the old one gets it again against its own lease, with the original base, and the merge decides. An orphaned version of the old primary (ADR-051) that matches a re-delivered change is tagged "re-delivered as cloud change <id>". - Up-sync: on-prem edits flow up at once. After each stable version, the primary sends a cloud view delta: the synced entries changed since the cloud's cursor
(epoch, seq), redacted as API-014 requires, with revisions, hashes, origins and tombstones, plus the signer set with each signer's effective permissions as(kind, verb)pairs aftermax_roleand the sync allowlist, its cool-off end, the high-risk LAN confirmation setting, device bindings by opaque ID, list blob hashes and the cluster's timezone, signed with the cluster signing key (spec/12 §4) under the domainwrendns-cloud-view-v1. When a version becomes Accepted (point 6), the primary signs an Accepted statement{cluster_id, epoch, seq}with the cluster key underwrendns-cloud-accepted-v1(added after the security review, for ADR-1064 point 3). Every hour and after every promotion it sends a full per-kind digest, so gaps beyond the 20-version history reconcile. The cloud verifies against the cluster key it pinned at enrolment and renews the pin when the CA rotates; it uses no cluster channel, is never a member (ADR-1048 point 7) and holds no stored secret. LAN edits made while the cloud is unreachable need no queue: the cursor catches up. - The portal's editor validates with the node's published rules, so most mistakes are caught before signing; the node's validation decides.
Consequences
Nothing is lost silently: a conflict is shown, never overwritten. A cloud edit made while home is offline applies later only if home has not changed the same fields. The cloud keeps a mirror of the synced policy at rest (ADR-1052 §3, amended). Every managed row grows by a few dozen bytes. Rejected: last writer wins by timestamp (Pi clocks drift), the cloud winning conflicts, rejecting every cloud edit (one-way sync), Accepted at a majority (a witness holds no version and manual promotion has no up-to-date check), applying the non-conflicting part of a change (it would split what the editor signed as one), and conflicts parked on the node (the owner chose the portal).
Requirements API-014 CLU-010
Builds on ADR-040 ADR-048 ADR-051 ADR-052 ADR-054 ADR-1011 ADR-1016 ADR-1019 ADR-1031 ADR-1048 ADR-1052 ADR-1060 ADR-1061 ADR-1064 ADR-116 ADR-968
Referenced by ADR-1047 ADR-1049 ADR-1052 ADR-1060 ADR-1061 ADR-1064
Link to this decision · In the specification
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" overrideOwner 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.
Context
Owner 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. While home is offline, cloud edits queue (signed, with expiry), the cloud resolver keeps the last Accepted policy, and an explicit "apply to roaming now" override reconciles when home returns. Under ADR-1047 the broker never decrypts, but a resolver in the cloud must end TLS for the names devices use. ADR-1050 put DoH on <slug>.<suffix>, the UI's own host, and DoT labels under *.<slug>.<suffix>, so a cloud certificate for them would also be valid for the UI and its sessions, and would defeat the CT watch (ADR-1051 point 6). The shared manifest carries credentials (ADR-1016 point 1). ADR-1031's gates make one resolver process per tenant impractical.
Decision
- Routing. The broker sends a roaming DoH or DoT connection to the home cluster while a ready member's tunnel is up (ADR-1047 point 7), and to the cloud resolver otherwise; the choice is made per connection. When home is back, connections held by the cloud resolver are closed once idle, within 5 minutes, so devices return home.
- DNS names get their own site, so the cloud never holds a certificate for a UI name: DoH at
https://<slug>-dns.<suffix>/dns-query/<device-key>and DoT at<dot-label>.<slug>-dns.<suffix>. The cloud resolver's certificate (key made in the cloud, every issuance in the helper's signed log) covers only<slug>-dns.<suffix>and*.<slug>-dns.<suffix>; each node's own certificate names them too (ADR-1051 point 1). The CT watch accepts a cloud certificate only for those names and only when it is in the signed log; anything else still blocks remote access. Slugs may not end in-dns; local records answer the-dnsnames at home with the VIP. - Policy: the last Accepted cloud view (ADR-1063 point 9): groups' filtering, quick rules, lists, schedules in the cluster's timezone, categories,
[special], safe search, block responses, device bindings and class rules with the class map (ADR-1060). Never local records, CMDB or location names, private-range PTR,node_onlyentries or credentials, whatever the view carries. The cloud resolver holds the newest view it has verified and reports its version (which is what lets a change become Accepted, ADR-1063 point 6), but serves only a view that carries the primary's signed Accepted statement (ADR-1063 point 9), so the cloud cannot mark an Applied orphan as Accepted. No rollback: older views carry valid signatures too, so the resolver keeps its own(epoch, seq)high-water mark per tenant, in its own store apart from the mirror and the queue, and never serves a view below it. Upstreams are MySummitKeep's own resolvers; the tenant's upstreams are not used. - Lists. The view carries each list's compiled blob hash. The cloud compiles public sources itself with the same compiler and uses its result only when the hash matches the primary's; otherwise it fetches the compiled blob from home while home is reachable and keeps it (encrypted per tenant). A list whose source carries a credential is only ever fetched as a blob from home.
- Device identity: device-key IDs and DoT labels with their group, and the SHA-256 of each 128-bit DoH key, kept only for tenants with the cloud resolver (amends ADR-1050 point 5 and ADR-1052 §3's "never DoH keys"; a 128-bit random key cannot be recovered from its hash). The node never sends a key, but each DoH request carries one in its path, so the resolver sees the raw key while it answers and does not store it. Keys are looked up by the tenant named in the SNI together with the key's hash, never by the hash alone. Unknown keys get 404 and unknown labels REFUSED, as at home.
- "Apply to roaming now" (revised after the security review; security review decision 5, confirmed by the owner 2026-11-19). Offered only while home is unreachable (no longer for a change "Applied, waiting for <node>", which would serve a version that is not Accepted). An editor may sign a queued change with
roaming_now: true(in the signed bytes, ADR-1061 point 4). The cloud resolver verifies the signature and checks it against the last Accepted view's signer set: the signer's effective(kind, verb)permissions (aftermax_roleand the sync allowlist), its cool-off, and whether a tenant admin has suspended it; it refuses a high-risk overlay (ADR-1061 point 6, which includes every portal-signed change) when the cluster has the LAN confirmation option on. It then applies the change as an overlay on that policy for at most 24 hours, whatever the change'snot_after. When home returns the change is delivered as usual: once it is Accepted the overlay is dropped (the new view holds it); on a Conflict or a Rejection the overlay is dropped at once and the editor is told. Suspension: a tenant admin may suspend a signer in the cloud resolver from the portal at once, ending its overlays; suspending only takes power away, so the cloud may hold it, and the node is told so that it can remove the signer too. - Isolation and data: multi-tenant, never a cluster member. A tenant's views and compiled list blobs come from a node that may be modified, so they are untrusted input: blobs are validated and capped before use, and each tenant runs under its own memory and CPU limits. The cache is shared only for unmodified public answers and partitioned per tenant for answers policy changed;
[special], safe-search and block-response rewrites never reach the shared cache. Query events are shipped home through a bounded memory buffer after the tenant's privacy level (ADR-102), counters only kept. It runs as its own process on the broker VMs (TCP 853 ingress); memory per tenant and the cold start are measured in T36.12. - Trust. The hosted threat model already lets a compromise of the whole cloud serve wrong roaming answers. The view signature, the Accepted statement, the resolver's own high-water mark and the signed override stop a fault or a partial compromise (the mirror or the queue) from changing roaming policy. A compromised broker could also send roaming connections to the cloud resolver while home is up, to read them; the node compares the query events the resolver ships home with its own record of when its tunnel was up and ready, and raises the severe alert
cloud_resolver_while_home_upfor events in such periods beyond a 2-minute failover grace (added after the security review).
Consequences
Roaming devices keep their filtering while home is down; the cloud sees those queries in clear while it answers them, and a compromised broker could make it answer while home is up, which the node reports; each tenant gets a second certificate and a third site; the cost model gains the resolver's compute. Rejected: failing closed (owner decision C), shipping the full manifest (credentials), serving Applied versions (an orphan of a failed primary could be served), the tenant's own upstreams (private ones are unreachable from the cloud), and DNS names under <slug>.<suffix> (a cloud certificate would cover the UI).
Builds on ADR-1016 ADR-102 ADR-1031 ADR-1047 ADR-1050 ADR-1051 ADR-1052 ADR-1060 ADR-1061 ADR-1063
Referenced by ADR-1050 ADR-1051 ADR-1052 ADR-1061 ADR-1063 ADR-1069
Link to this decision · In the specification
ADR-1065 Portal sign-in through Microsoft Entra External ID; the portal's issuer stays the one identity nodes trust (Accepted 2026-11-19; implements owner decision A(1)'s identity provider, which is final, and ADR-1049 point 1's hosted issuer; #41, T36.20)Owner decision A(1): portal sign-in uses Microsoft Entra External ID for accounts, MFA, passkeys and recovery, replacing or implementing ADR-1049's hosted issuer.
Context
Owner decision A(1): portal sign-in uses Microsoft Entra External ID for accounts, MFA, passkeys and recovery, replacing or implementing ADR-1049's hosted issuer. Facts checked 2026-11-19 (hosted.md, Sources): passkeys in external tenants work only for email+password and username+password local accounts and only with Microsoft-hosted sign-in, need MFA in the last 5 minutes and a custom URL domain, and have no built-in registration screen (the credential management API); a custom domain needs Azure Front Door in front of <tenant>.ciamlogin.com; requiring MFA needs a Conditional Access policy, free with the core offer up to 50,000 MAU; authentication strengths are not available in external tenants, so phishing-resistant MFA cannot be required by policy; TOTP becomes generally available at the end of November 2026; the stable user ID is oid, and sub differs from it in External ID; amr is an optional claim; whether auth_time and acr are honoured in external tenants is not verified. Nodes already trust one hosted issuer with two redirect URIs per node (ADR-1049 point 1).
Decision
- Entra holds the accounts: sign-up, sign-in, MFA, passkeys and recovery. (Amended 2026-11-19 by ADR-1067: Entra External ID holds consumer accounts, organizations' break-glass owners and invited outside members; organization members sign in through their own IdP via the portal's broker.) The portal's OIDC issuer authenticates people only through Entra (OIDC with PKCE, a confidential client) and stores no password. Nodes keep trusting the portal's issuer, which keeps per-tenant redirect URIs and the tenant claim on the service side (one Entra app registration cannot hold a redirect URI per node; T36.20 confirms its limit).
- Subject: the issuer asserts Entra's
oidassub, with the email and the WrenDNS tenant ID, so node mappings (ADR-1049 point 2) survive any change of sign-in method. (Amended 2026-11-19 by ADR-1067 point 2: the issuer asserts a portal-minted, immutable user ID assubfor every account, keyed for External ID accounts on Entra'soid, because enterprise users have no External IDoid; nothing is built yet, so nothing migrates.) - Methods: email with password, with MFA required for every account by a Conditional Access policy: a passkey, TOTP once it is generally available, or an email one-time code. Passkey sign-in is offered. Google, Apple and other social sign-in come later; those users cannot use Entra passkeys. The
amrclaim is recorded in the portal's event log. (Amended 2026-11-19 by ADR-1067 point 3: the policy covers External ID accounts; users federated through External ID's SAML route are excluded, their MFA being their IdP's, recorded throughamrandacrwhere asserted.) - The custom domain
login.wrendns.comthrough Azure Front Door Standard (required for passkey registration), then a support request to block the defaultciamlogin.comhost; passkey registration is a page under the login host using the credential management API. - Recent sign-in for sensitive portal actions (members, billing, signer enrolment requests) uses
prompt=loginand checksiat, notauth_timeoracr. - Sign-in and signing stay apart. The Entra passkey (RP ID
login.wrendns.com) never signs a change; the signing passkeys (RP ID<slug>.<suffix>on the node's own signing page, orsign.wrendns.comwhile home is unreachable, ADR-1061 points 1 and 2, revised after the security review) never sign in to the portal. A compromised Entra tenant is ADR-1049's compromised issuer: it can mint identities, which get no node access without a node mapping and the node-held factor, and it cannot sign a change. - Cost: the core offer is free to 50,000 MAU (admins count); SMS is not used; Front Door's base fee (about USD 35 a month, not verified) is added to the platform (ADR-1052 point 4).
Consequences
No password store of our own, mature MFA and recovery, and a branded sign-in host. The service depends on Microsoft for accounts, and on local accounts for passkeys. Rejected: an account store in the portal, nodes trusting Entra directly (redirect URIs per node, and a second issuer on every node), using the Entra passkey to sign changes (ADR-1061), and staying on ciamlogin.com (no Entra passkeys).
Builds on ADR-1049 ADR-1052 ADR-1061 ADR-1067
Referenced by ADR-1049 ADR-1052 ADR-1061 ADR-1067
Link to this decision · In the specification
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)Owner 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.
Context
Owner 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-046 says the UI never self-updates a node, and self-update (ADR-038) is a manual root step. ADR-116's staged rollouts cover configuration versions only (canary and stable heads, a guard read from heartbeats, pins). ADR-118 puts a node in maintenance (not ready, still answering). CLU-010 allows N-1 mixing during upgrades.
Decision
- Opt-in on the node:
[updates] managed(guarded, admin-only, set on the LAN, never for agents, off by default), with a maintenance window, the channel and a bake time. Native systemd installs only, through a rootwrendns-updatehelper unit that fetches the release from wrendns.com itself (never a byte the cloud hands it), verifies it with the release key under the key manifest (ADR-1062) and keeps the previous binary as.prev. Containers and Helm keep the existing update hints. Revised after the security review (security review decision 3, confirmed by the owner 2026-11-19), because the release key lives in the online release workflow and canaries and ADR-116's guard catch crashes, not malice: a release that managed updates may install carries two signatures, the release key's and the owner's hardware update key's (scoperelease_auto, ADR-1062 point 2); it must have been in the append-only release log on wrendns.com (each entry hash-chained to the one before and signed) for at least 24 hours, counted from the node's own first sighting of that entry, before any node installs it; and the helper refuses any version below the running one, except when restoring.prev. - The cloud never triggers an update. The platform channel delivers the signed
releases.jsonwith signed fleet rings (a percentage ramp by a hash of the cluster ID) and a hint; the primary decides to start, inside its window. A self-hosted cluster does the same from wrendns.com. - Order: canaries first, then replicas one at a time, then the primary last after handing its role over (ADR-118); every node passes ADR-116's guard and the bake time; a failed guard stops the rollout and restores
.prev; versions mix as CLU-010 allows. No update starts during a pin, a bake or a failover drill. - Every step is audited, an event and a health note; MCP gains a read tool
update_status; agents get plans only.
Consequences
Unattended Pis stay current without the owner signing in, using a guard already proven for configuration, and a bad release is caught on a canary. A compromise of the release key alone cannot reach any node automatically, and a malicious release is public in the log for a day before it installs; each automatic release costs the owner a hardware-key signature. Rejected: the release key alone for automatic installs (one online key would be root on every opted-in node), the cloud starting updates (it would start code on a node), updates outside the cluster's order (the primary could restart first), and containers updating themselves (their orchestrator owns the image).
Requirements CLU-010
Builds on ADR-038 ADR-046 ADR-1062 ADR-116 ADR-118
Referenced by ADR-1047 ADR-1052 ADR-1062
Link to this decision · In the specification
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 ownersThe 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).
Context
The 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). Research checked 2026-11-19 (hosted.md, Sources): apps in an external tenant are always single-tenant, so a multi-tenant Enterprise app needs a workforce tenant; External ID can federate custom OIDC and SAML IdPs, but passes only standard profile claims (no groups), shows every IdP added to a user flow as a button on the sign-in page (one user flow per app), routes new users by domain only for SAML, shows an unsuppressible confirmation for domain_hint to an Entra IdP, does not trust the customer's MFA (so Conditional Access would ask twice), accepts a customer Entra tenant only as custom OIDC with a client secret the customer makes and rotates, and does not support Entra-to-Entra SAML. A multi-tenant app accepts tokens from any Entra tenant. Enterprise users have no External ID oid, so ADR-1065 point 2's subject cannot hold. Native SAML means XML signature handling (signature wrapping, XXE) and, in Rust, a C dependency. Nodes trust one issuer, the portal's (ADR-1049 point 1).
Decision
- Two tenant types. A personal tenant (every Cloud and Cloud Plus tenant) has members who sign in through Entra External ID only (ADR-1065). An organization tenant (Business, ADR-1070) adds enterprise connections, verified domains, SCIM (ADR-1068) and group mappings (ADR-1069), and has External ID members only as break-glass owners or invited outside members. A personal tenant becomes an organization on moving to Business, and cannot go back while it has a connection or SCIM credentials.
- The subject is a portal-minted user ID (amends ADR-1065 point 2):
usr_and a random 128-bit value, immutable, never reused (tombstoned on deletion), asserted to nodes assubwith the email and the WrenDNS tenant ID. The portal keys each account on (upstream issuer, upstream immutable ID): the external tenant'soid; Entra ID's (tid,oid); a generic IdP's (iss,sub); SAML's (entity ID, persistent NameID); and for SCIM the organization's SCIMidwith anexternalIdequal to the connection's immutable ID. Accounts are never linked by email, automatically or on request; an enterprise account belongs to one organization; a consumer account with the same address is another account. An organization owner may re-link an account to a new upstream ID (audited, recent sign-in, every owner alerted), which keeps itssub; because node mappings, signers and grants hang onsub, a re-link sends each cluster aSubjectRelinkednotice that disables the subject there until a node admin restores it (ADR-1069 point 5). A SCIMexternalIdis immutable once the account has signed in; a write that changes it is refused (ADR-1068 point 2). (Revised after the identity security review, H1.) - The portal's issuer is a federation broker with one or more enterprise connections per organization, and nodes keep trusting only the portal's issuer:
- Entra ID through the WrenDNS Cloud Enterprise app: a multi-tenant confidential client (v2.0,
private_key_jwtwith a certificate, scopesopenid profile email, nooffline_access) registered in a separate WrenDNS workforce tenant owned by MySummitKeep (<workforce-tenant>.onmicrosoft.com), never in the External ID tenant; that tenant has no users but PIM-protected administrators with phishing-resistant MFA, and any change to the app's credentials, redirect URIs or owners alerts MySummitKeep's security contact. An organization admin grants admin consent once; the portal records the consentingtidand accepts a token for that organization only whenissis exactlyhttps://login.microsoftonline.com/<tid>/v2.0andtidmatches; guest accounts (acct= 1) are refused unless the organization owner allows them; sign-in uses the tenant-specific authorize endpoint. The setup page tells the admin to turn on "assignment required". - Generic OIDC for every other OIDC IdP (Okta, Google Workspace, Ping, Auth0, Keycloak): issuer, client ID and a secret or a
private_key_jwtkey entered by the organization admin; discovery read once and the issuer and JWKS URI pinned; code flow with PKCE,state,nonceand exactiss,audandazpchecks, reusing ADR-951's verifier; secrets encrypted under a Key Vault key, never shown again, rotatable. Shared issuers are refused or restricted: no Microsoft issuer as a generic connection (Entra customers use the Enterprise app), Google only whenhdis one of the organization's verified domains andemail_verifiedis true, and every other issuer specific to the customer. Mix-up (RFC 9207): a callback path per connection,statebound to the connection, browser session,nonceand PKCE verifier, the response'sisschecked when sent, and a code sent only to the token endpoint of the connection the sign-in started on. (Revised after the identity security review, H3.) - SAML-only IdPs through Entra External ID's SAML federation until native SAML has passed its own security review (T36.26): the broker routes with
domain_hintand accepts the result only when theidpclaim names that organization's federation and the account is linked to the organization; such accounts are keyed on (the federation's WrenDNS-assigned ID, the External IDoid); an entity ID another organization's federation uses is refused; the MFA policy's exclusion is by the federation's issuer, never by email domain or a portal-written group; and T36.26 verifies that External ID never joins a federated sign-in to an existing local account by email before the route opens. Native SAML, when built, accepts only aResponsewith exactly one signedAssertion, verified with the connection's pinned certificates only (neverKeyInfo), RSA-SHA256 or stronger, and then reads only the element the verifier returns as signed (against signature wrapping); exclusive canonicalization with values read after it; no DTD or external entity; exactDestination,Recipient,AudienceandIssuer;InResponseTobound to the browser session's request (so no IdP-initiated responses); time checks with 3 minutes of skew; a replay cache of assertion IDs; encrypted assertions decrypted and then verified; a persistent NameID; and a signing-certificate change in metadata approved by an owner. - MFA for enterprise users is their IdP's; the External ID MFA policy (ADR-1065 point 3, amended) covers External ID accounts only and excludes SAML-federated users.
amrandacrare recorded when asserted; an organization may require listed values (off by default).
- Entra ID through the WrenDNS Cloud Enterprise app: a multi-tenant confidential client (v2.0,
- Verified domains: a TXT record
_wrendns-verify.<domain>with a per-organization random value, checked through two validating public resolvers, rechecked daily, lost after 7 days of failures; one organization per domain; subdomains separately, a subdomain of another organization's verified domain only with that organization's consent; public mail domains and the product's own domains refused. - Home-realm discovery by email domain, only for verified domains with an active connection; an organization sign-in URL
https://dns.wrendns.com/sso/<org-slug>otherwise; IdP-initiated responses refused (Entra's My Apps tile starts an SP-initiated sign-in). The email routes and never authorizes. - Enforce SSO per verified domain, off by default, an owner setting: External ID sign-up with such an address is refused and sent to the connection, and External ID accounts with such an address cannot join or sign in to that organization. Personal tenants are not affected.
- Break-glass owners: every organization keeps at least one owner who is an External ID local account with MFA and a passkey, exempt from enforcement and SCIM; each break-glass sign-in must use the passkey (checked through
amr; an email one-time code is refused there); the last one cannot be removed, deprovisioned or demoted; their sign-ins alert every owner; owners confirm the list every 90 days. Node break-glass stays node-local (local users, ADR-944). - Every connection change, domain event and SSO sign-in is in the tenant log (ADR-1070 point 3).
- Identity settings are owner-only: connections, verified domains, enforcement, SCIM credentials, portal group mappings and re-links need an owner with a recent sign-in and alert every owner; a portal
admin(which a group mapping can grant) cannot change them; SCIM never writes owners; a connection's issuer andtidare immutable, so a new issuer is a new connection with new accounts. (Added after the identity security review.)
Consequences
Entra customers get the Enterprise app onboarding the owner asked for without handing over a secret, other IdPs work through OIDC, and the consumer sign-in page shows no customer IdP. The broker is more code to own and is now part of the issuer's attack surface; a bug in connection handling is a compromised issuer, which ADR-1049's node-side checks contain. MySummitKeep runs a second Entra tenant. SAML-only customers get a weaker path until native SAML ships. Rejected: federating every customer IdP into External ID (no groups, visible buttons, double MFA, a secret per Entra customer, no Enterprise app); building native SAML first (attack surface before demand); buying a broker (WorkOS, Auth0, Keycloak: another processor holding every enterprise sign-in and per-connection fees; the node trust model is the same either way, so it can be revisited); keeping Entra's oid as sub (enterprise users have none); linking by email (account takeover; Microsoft's gallery validation rejects matching on a mutable identifier).
Builds on ADR-1049 ADR-1065 ADR-1068 ADR-1069 ADR-1070 ADR-944 ADR-951
Referenced by ADR-1049 ADR-1065 ADR-1068 ADR-1070
Link to this decision · In the specification
ADR-1068 A SCIM 2.0 service provider per organization: users and groups, PUT and PATCH, soft and hard delete, three credential kinds scoped to one organization, rate limits, and no power over sign-in, nodes or signingThe owner requires SCIM 2.0 provisioning of users and groups from the customer's IdP.
Context
The owner requires SCIM 2.0 provisioning of users and groups from the customer's IdP. Entra's provisioning service needs /Users with eq filters on userName and externalId, PATCH, soft delete with active=false (disabled users still returned), an empty 200 ListResponse for no match, /Schemas, /ResourceTypes and /ServiceProviderConfig, unique group displayName, membership by PATCH add and remove, excludedAttributes=members, at least 25 requests a second per tenant for gallery apps, and has known PATCH deviations; it authenticates by per-customer OAuth client credentials, workload identity federation (RFC 7523) or, for non-gallery apps, a long-lived bearer token. Okta never DELETEs users, sends nothing on suspension, uses PUT for wizard apps and needs GET /Groups/{id} with members and stable pagination; it authenticates by OAuth bearer, Basic or a header token. Google Workspace's custom SCIM is a limited beta with a bearer token only. The cloud must not be able to grant node access (ADR-1049).
Decision
- One base per organization on a host of its own:
https://scim.wrendns.com/scim/v2/<org-id>/, with/Users,/Groups,/Schemas,/ResourceTypesand/ServiceProviderConfig;POST,GET,PUT,PATCHandDELETE;eqfilters onuserName,externalIdandemails[type eq "work"].valuefor users and ondisplayNameandexternalIdfor groups; an empty 200ListResponseon no match;startIndexandcountup to 100 with integer totals in a stable order;excludedAttributes=members; members returned onGET /Groups/{id}; multi-member PATCH answered 204; no Bulk at first. Lenient on Entra's deviations (opandOperationscase, path-less replace, string booleans). - What it writes: user identity attributes (
userName,externalIduntil the account first signs in and immutable after, a change refused with 400mutability,name,displayName,emails,active), groups (displayNameunique per organization,externalId) and memberships; unknown attributes accepted and dropped. Never portal roles, connections, mappings or anything on a node. - Lifecycle:
active=falsedisables the account at once and keeps it readable;active=truerestores the portal account only (ADR-1069 point 6);DELETEdisables and removes the record after 30 days, tombstoning the portal user ID. - Credentials, each bound to one organization's base and to SCIM only: Entra workload identity federation (a JWT checked against the pinned tenant's JWKS with
issexact,tidpinned,audthe SCIM audience registered for that organization, andoidandsubequal to the enterprise application's service principal recorded at consent, so no other principal of that tenant qualifies; exchanged for a one-hour token; preferred), OAuth client credentials per organization (one-hour tokens), and a header token (256 random bits, shown once, stored as SHA-256, two at once for rotation, at most a year, warned 30 days before) for Okta and Google. - Limits: TLS 1.2 or later with Microsoft's cipher list; 1 MiB per request and 1,000 members per PATCH; about 25 requests a second per organization with 429 and
Retry-After; per-tier user and group caps (ADR-1070); an optional source-range allowlist; failed authentication rate-limited and alerted to owners after 10 in an hour. - Isolation: the SCIM host sets no cookies, refuses CORS, logs no bodies, and its service identity can write identity and membership rows only, with no access to the mirror, queue, signing pages or tunnel. Payloads are untrusted input (size and depth limits, strings escaped where shown).
- No other power: a SCIM credential never signs in, never reaches a node and never signs a change (ADR-1061); a sign-in needs the IdP to assert the matching immutable ID (ADR-1067 point 2); SCIM data affects nodes only through ADR-1069's rules and limits.
- Every SCIM write, credential event and failed authentication is in the tenant log. Microsoft's SCIM validator and provisioning validation and Okta's SCIM tests pass before the first organization uses it.
Consequences
Entra, Okta and (beta) Google can provision and deprovision promptly. A stolen SCIM credential can create, change and disable accounts and memberships in one organization: a lockout risk (ADR-1069 point 7) and, through mapped groups, a bounded grant risk (ADR-1069 point 4), never a sign-in or a signature. Rejected: a long-lived bearer token as the only credential (not allowed for new Entra gallery apps), OAuth only (Google and many Okta setups need a header token), one credential for every customer (Entra does not support it), and the SCIM API on the portal's own origin (shared cookies and CSP).
Builds on ADR-1049 ADR-1061 ADR-1067 ADR-1069 ADR-1070
Referenced by ADR-1067 ADR-1070
Link to this decision · In the specification
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 approvalSCIM can create identities and group memberships in the cloud, but a compromised cloud must not be able to grant node access (ADR-1049).
Context
SCIM can create identities and group memberships in the cloud, but a compromised cloud must not be able to grant node access (ADR-1049). Today the node ignores the issuer's group claims, maps subjects one by one with pending as the default, and needs a node-held factor enrolled on the LAN on every relayed sign-in; signers are enrolled at home with a step-up, a cool-off and a signer_added alert (ADR-1061 point 3); max_role defaults to operator and caps relayed sessions and signed changes. A business with 200 users cannot approve and enrol them one by one. Removing access only reduces power, which the cloud may already do (signer suspension in the cloud resolver, ADR-1064 point 6), but a cloud that removes access can lock people out. JIT gives zero setup but no deprovisioning; SCIM gives prompt deprovisioning and groups. SCIM requests carry no signature from the customer's IdP, so nothing but the cloud could sign a membership.
Decision
- JIT and SCIM. JIT is on by default only for connections whose issuer is the organization's own (the Entra connection with its pinned
tid, an Okta org's issuer) or whose tokens carry a restricting claim (Google'shdin a verified domain); JIT accounts get portal rolememberand nothing on nodes. Once SCIM is enabled it is authoritative: sign-in links only to SCIM-provisioned accounts by the immutable ID equal toexternalId, a JIT account no SCIM user matches within 7 days is disabled with notice to admins, and a sign-in with no SCIM match is refused. - Portal group mappings (cloud only): an IdP group, by SCIM ID and
externalId, never display name, maps to portal rolememberoradmin, neverowner; audited in the tenant log. - Node group rules: a replicated, guarded node kind
hosted_group_rule(rule ID, organization and connection, the group's SCIM ID andexternalId, its display name for display only, role, cluster IDs, onboarding mode, signer, envelope and assertion, cool-off end), never synced from the cloud and never for agents. A rule is made, changed or removed only by a node admin who signs it with a node signing passkey on the node's own page in a session made on the LAN, or through ADR-1049 point 3's admin-from-away routes (verified custom name, or LAN approval of the action). The portal may send an unsigned draft. The role isviewer,operatoror a custom role withinoperator's permissions, neveradmin; the subset check is repeated at every use (a custom role later widened beyondoperatormakes the rule inert and raisesgroup_rule_invalid), and the role is capped bymax_role. A rule's signature and an invitation batch's use their own challenge prefixes (wrendns-group-rule-v1,wrendns-invitation-v1), so an assertion over a change, a rule or a batch never counts as another. A cluster accepts rules only while it has at least one enabled node-local admin account. A hand mapping in the subject-to-role table overrides rules; among rules the highest role wins, under the cap. A new rule takes effect after a cool-off (4 hours by default) and raises a guardedgroup_rule_addedalert that cannot be turned off while the node is linked. (Amends ADR-1049 point 1: the node still ignores group claims in tokens; memberships arrive only as the updates below and count only under a rule the node's admin signed.) - Membership updates: the node lists its rules' group IDs in its heartbeat; the cloud sends
MembershipUpdateframes (organization, group, subject,addorremove, SCIM event ID, per-organization sequence) for those groups only. The node accepts frames and notices only for its own tenant and a rule's organization, ignores a sequence number already seen, and lets a subject granted by rule sign in only with tokens whose tenant claim is that organization. Aremoveapplies at once, unsigned. Anaddmakes the subject granted by rule, active only after onboarding on that cluster (point 8), and still subject to the node-held factor and signer enrolment. Velocity limit: at most 20 grants by rule per cluster per hour and 200 per day (guarded, set on the LAN); beyond that, adds wait as pending for an admin and the node raisesgroup_grant_burst(degraded). Every grant and removal is audited with the rule, the SCIM event ID and sequence, and asubject_granted_by_ruleevent; admins get a digest at most every 15 minutes. - The deprovisioning fast path: SCIM
active=falseorDELETE, a portal admin disabling an account, or an owner re-linking one (sent asSubjectRelinked, handled the same way, because the samesubmay now be another person), disables it in the portal at once (sessions and refresh tokens revoked, no new tokens) and sends each cluster aSubjectDisablednotice and removes for its groups through the tenant's authenticated tunnel, accepted unsigned because they only remove power. The primary, within one heartbeat, marks the subject disabled, ends all its sessions (relayed and LAN), disables (does not delete) its signers so pending and queued changes from them are refused, withdraws its grants by rule and keeps its hand mapping inactive; the node audit records the notice. (Amends ADR-1049 point 2 and ADR-1061 point 3: a cloud notice disables a subject and its signers; it never deletes them.) - Reactivation restores the portal account only. On nodes the subject stays disabled until a node admin restores it (per subject or "restore all disabled since <time>"), in a session made on the LAN or by an admin's signed change under ADR-1049 point 3; grants by rule then return through point 4's path and limits.
- Abuse limits on removal, and the availability risk stated: a compromised cloud, a stolen SCIM credential or the customer's IdP admin can lock hosted users out. Notices never touch node-local users, DNS, the cluster or settings; nothing is deleted, and one LAN action restores; when more than 10 subjects, or more than a fifth of a cluster's hosted subjects, are disabled within an hour, the node applies the notices and raises severe
cloud_mass_disablewith alerts to every destination; each notice carries its SCIM event ID, or is marked as a portal action when it has none. - Onboarding at scale, one ceremony per user per cluster, since one node passkey (RP ID
<slug>.<suffix>) may be both the node-held factor and the signing passkey (ADR-1061 point 2), and always with a signal that does not come from the cloud: a hosted sign-in, on the LAN or not, never enrols the factor that then confirms the signer (ADR-1061 point 3's "a hosted sign-in alone never confirms a signer"). A rule's mode:invitation(default): a node admin, on the LAN or by a signed admin change, creates a batch of invitations signed once with the admin's node signing passkey, each bound to one subject, single use, 72 hours by default (at most 7 days), with a role no higher than the rule's, and a link and 8-character code shown once and exportable as CSV, so the admin delivers them by their own channel to the address in the organization's own directory, and the cloud never sees the codes; the user signs in with SSO on the LAN or over the relay, enters the code on the node's page and registers the passkey, which the invitation confirms as a signer; the cool-off applies andsigner_addedalerts from onboarding are grouped into one per 15 minutes per cluster. (Amends ADR-1049 point 2: a node factor may be enrolled from away only by such an invitation.)confirm: each granted subject waits for a node admin's approval in a session made on the LAN, on a bulk-approve screen; an approved subject then registers the passkey at its first sign-in in a session made on the LAN. Self-service onboarding by an SSO sign-in on the LAN alone is not offered. Personal tenants keep ADR-1049's one-by-one flow. - The node factor on the LAN in organization tenants: a guarded
[cloud] factor_on_lan, on by default when the linked tenant is an organization and off for personal tenants, requires the node factor on every hosted sign-in of a subject that has one, on the LAN as well; a subject without one sees only the onboarding page there. Node-local users are not affected. (Amends ADR-1049 point 2 for organization tenants, because an office LAN is shared with many people.) - Unsigned frames, stated:
SubjectDisabled,SubjectRelinkedand membership removes are the only unsigned frames that change node state, and they only remove power; a membership add is unsigned but counts only under a rule a node admin signed, within its capped role and the velocity limit. This narrows the design's "nothing unsigned changes a node's configuration" (ADR-1061, Consequences) to those frames.
Consequences
A business can onboard hundreds of users with one signed rule per group and cluster, and remove them within a heartbeat of the IdP doing so. A compromised cloud or stolen SCIM credential can grant an onboarded user the rule's role (never admin, never above max_role, at most 20 an hour without an admin seeing it), add minted subjects that still need an invitation code it never saw or a node admin's approval on the LAN, and lock hosted users out until a LAN admin restores them; an invitation redeemed over hosted names is as strong as the CT watch. Rejected: trusting SCIM memberships on nodes without a rule (the cloud would grant access), rules up to admin (a cloud compromise would be admin on every rule's cluster), signed membership updates (nobody but the cloud could sign them), holding removals for approval (a departed employee keeps access), cloud-restored access on reactivation (the cloud could re-grant), self-service onboarding by an SSO sign-in on the LAN alone (a compromised cloud plus a device on the office LAN could onboard a minted subject), and verifying the customer IdP's own groups claim on the node (Entra-only, group overage, and a second issuer on every node; it may be revisited as an end-to-end proof).
Builds on ADR-1049 ADR-1061 ADR-1064
Referenced by ADR-1049 ADR-1061 ADR-1067 ADR-1068 ADR-1070
Link to this decision · In the specification
ADR-1070 SSO, SCIM, node group rules and audit-log export are included in Business, with no Enterprise add-on; Entra gallery and Okta Integration Network listings after general availabilityADR-1052's Business tier already says "SSO from the business's own IdP federated through the issuer".
Context
ADR-1052's Business tier already says "SSO from the business's own IdP federated through the issuer". Business buyers expect SSO (OIDC and SAML), SCIM and audit logs; many vendors charge a steep premium for them (the "SSO tax", catalogued at sso.tax), SCIM is now the more common paywall, and Tailscale removed its SSO premium in April 2024. Listing in the Entra app gallery needs publisher verification (a Partner One ID), the gallery's SSO and provisioning validation (25 SCIM tests, in preview), documentation and support contacts; the Okta Integration Network has its own tests. Prices are the owner's.
Decision
- Business includes organization tenants (ADR-1067), enterprise connections (OIDC first, SAML when T36.26 ships), verified domains and enforcement, break-glass owners, SCIM (ADR-1068), portal group mappings and node group rules (ADR-1069), and audit-log export, with no Enterprise add-on. The plan is named "Business: SSO and SCIM included". Cloud and Cloud Plus stay personal tenants on External ID.
- Caps per organization on users, groups and connections are set by the owner with the price; the SCIM server enforces them (ADR-1068 point 5).
- Audit export: the tenant log (connections, domains, SSO sign-ins with
amrandacr, JIT, every SCIM write, credential events, mappings, membership updates and disable notices sent, break-glass sign-ins, re-links) as an NDJSON download and a webhook signed with a per-organization HMAC key and retried with backoff; kept at least 400 days in Business (the owner sets the figure); SIEM connectors later. The node's own hash-chained audit stays authoritative for node events (ADR-1049 point 7). - Listings in the Entra app gallery (OIDC and SCIM) and the Okta Integration Network come after general availability (T36.27), with the workforce tenant's publisher verification first.
Consequences
No SSO tax in the offer; Business carries the cost of the broker, the SCIM server and the export. The listings make onboarding a search in the customer's admin console. Rejected: SSO in Business with SCIM and export as a paid add-on (the "SCIM tax" buyers now complain about), and SSO in every paid tier (consumer tiers have no organization to federate).
Builds on ADR-1049 ADR-1052 ADR-1067 ADR-1068 ADR-1069
Referenced by ADR-1067 ADR-1068
Link to this decision · In the specification
ADR-1071 The network map: a Wiring view and a Places view over one graph, device detail pages, motion from real data, and non-IP devices from Home Assistant read-only through their hubThe owner proposed a network map earlier and, after looking at the public netpulse demo, said its animations are "more like what I envisioned" and that the work "is worth developing".
Context
The owner proposed a network map earlier and, after looking at the public netpulse demo, said its animations are "more like what I envisioned" and that the work "is worth developing". netpulse is AGPL-3.0: the clean-room rule and the commercial licence (ADR-1033) mean only ideas from its rendered pages are used, never its code. WrenDNS already reads UniFi ports and LLDP into the CMDB, and each device's Home Assistant area with its name.
Decision
- One graph, two views.
GET /api/v1/topologyserves nodes, links and places; the Wiring view draws the physical network and the Places view groups by site, floor and area. Clicking a node in either opens its detail page. - Hand-written SVG in a lazy chunk, with no graph or animation library; a deterministic layout with per-user pins; the links table is the text equivalent of the map.
- Motion shows real data. Dot speed and density follow measured per-link rates and DNS query rates; blocked queries are red and stop at the node; a link with no traffic is still. Off under
prefers-reduced-motion, paused in a hidden tab, with a toggle. - Non-IP devices (Zigbee, Z-Wave, Thread, Matter) come read-only from Home Assistant's device list and appear only in Places, linked to their hub; they never enter the clients list, the query log or policy.
- Order and scope: first among the enhancements after the speed wave, all four parts (Wiring, Places, device pages, clients list) as one big development wave that starts once the repository is public, so GitHub Actions minutes are free; #40's location names and T24.45 folded in.
Consequences
The map's motion is a monitoring signal, not decoration, so it needs per-link rates from the integrations and a quantised, capped animation budget. The UI budget is protected by loading the map only when it opens. Rejected: decorative motion (it would show a dead link as busy), a graph library (size budget), and reading netpulse's source (licence).
Builds on ADR-1033
Link to this decision · In the specification
No decision matches. Try fewer words, or another status or area.