technitium-console/CONVENTIONS.md

# How this console is built

Read this through before touching anything. It is short and it saves you the
mistakes that have already been made.

## The rule that rules them all: design only, zero functionality

This console **replaces the Technitium DNS Server interface without changing what
it does**. Same controls, same steps, **same texts**, same validation order. Any
behavioural difference from the upstream console is a bug, even when it looks
like an improvement.

If you catch yourself thinking "while I am here, this could be better": no. That
is a different job.

The exceptions are few, decided and written down: see
[Deliberate deviations from upstream behaviour](#deliberate-deviations-from-upstream-behaviour).
The largest is the Blocking section, which replaces Allowed and Blocked. Those that
add something carry written limits of their own.

## Where the reference is

The console this one replaces is not in this repository. You read it from the
server's own repository, which has to be added as a remote once:

```bash
git remote add upstream https://github.com/TechnitiumSoftware/DnsServer.git
git fetch upstream master

git show upstream/master:DnsServerCore/www/js/zone.js
git show upstream/master:DnsServerCore/www/index.html
```

**The alert texts are contract.** Pull them out of there with
`grep -o 'showAlert("[^"]*", "[^"]*", "[^"]*"'` and copy them literally, without
rewording.

## Do not assume the shape of the responses: check it

There are two disposable instances in `dev/`:

- `dev` at <http://127.0.0.1:5380>: serves our build
- `ref` at <http://127.0.0.1:5381>: the upstream console, untouched

User `admin`, password `technitium-ui-dev`. Bring them up with
`docker compose up -d` from `dev/`.

```bash
T=$(curl -s "http://127.0.0.1:5381/api/user/login?user=admin&pass=technitium-ui-dev&includeInfo=false" | python3 -c "import sys,json;print(json.load(sys.stdin)['token'])")
curl -s "http://127.0.0.1:5381/api/zones/list?token=$T" | python3 -m json.tool | head -40
```

Three assumptions that have already turned out false, so you do not repeat them:

1. **Not everything comes wrapped in `response`.** `user/login`,
   `user/session/get` and `status` return the payload **flat**. Everything else
   does wrap it. That is why `apiRequest` **unwraps nothing**: it hands over the
   JSON as it came.
2. The second-factor literal is **`2fa-required`**, not `two-factor-auth-required`.
3. The statistics are flushed **by the minute**. A `dig` you just ran does not
   show on the Dashboard until the next flush; do not conclude something is broken.

## Upstream behaviours discovered along the way

Write down here whatever you find. What is already known:

- **Optional fields that look required.** In `apps/list`, the `updateVersion`,
  `updateUrl` and `updateAvailable` fields **only exist** if the app is in the
  store catalog and there is a compatible version there; an app installed from
  your own zip never brings them, and if the catalog query exhausts its 5 s
  timeout the list arrives whole but without them on any app. Typing them as
  required is a guaranteed bug. Be suspicious of every field you have only seen
  once.
- **A text field can come back as `null`.** `apps/config/get` returns
  `config: null` as soon as someone saves an empty configuration.
- **The upload endpoints are POST-only**: by GET the server answers **404**, not
  a JSON error.
- **On uploads, the file field name does not matter**: the server takes
  `Form.Files[0]`. But **do not set `Content-Type` by hand** or the `boundary`
  is lost and the server says the file is missing.
- **Deleting something that does not exist usually answers `ok`**, not an error.
- **There are two different paginations.** `zones/list` paginates on the server
  (`pageNumber`, `zonesPerPage`) and its paging fields **only appear if you send
  `pageNumber`**. `zones/records/get`, on the other hand, **does not paginate**:
  it is asked for with `listZone=true` and paginated on the client.
- **Where an alert comes out is not cosmetic**: in upstream, a modal's alerts
  come out inside the modal and a screen's come out on the screen. Honour it.
- **The server can return a domain different from the one you asked for.** When
  navigating the cache/allowed/blocked tree, `WebServiceOtherZonesApi.cs`
  **walks down on its own** while the node has no records and has exactly one
  child. Always draw `response.domain`, **never** the domain you asked for, or
  the tree and the table fall out of sync.
- **The same field can have two types depending on the endpoint.** In
  `cache/list` the `ttl` is an already-composed string (`"218 (3m38s)"`); in
  `allowed/list` and `blocked/list` it is a number with `ttlString` apart. Same
  with a SOA's `refresh`, `retry`, `expire` and `minimum`. Typing the records
  with a single shape is a guaranteed bug.
- **`0001-01-01T00:00:00` is .NET's `default(DateTime)`**: it means "never", not
  year 1.
- **Visibility rules that look the same and are not**: deleting a node is
  offered in cache if the node is not the root, and in allowed/blocked if the
  node has records. Do not make them uniform without looking.
- **A count may not be where you draw it.** `blocked/list` only reads the
  manually blocked zones; the downloaded block lists are counted **only** in
  `dashboard/stats/get` (`blockListZones`).
- **Careful with replicating the intent instead of the behaviour.** In
  `other-zones.js` there are three `domain.toLowerCase();` **without assigning
  the result**: they do nothing. What the code does is replicated, not what it
  looks like it wants to do.
- **`settings/get` OMITS the null keys**, it does not send them as `null`:
  fields like `temporaryDisableBlockingTill` or `blockListNextUpdatedOn` simply
  do not appear on a freshly installed server. Others do arrive as an explicit
  `null`. Declaring them required fails against a new install. And
  `blockListNextUpdatedOn` is not only a fresh-install gap: it is written only
  while a block list update is scheduled (WebServiceSettingsApi.cs:382-386), so
  saving an empty list makes it vanish from the answer. Settings › Blocking and
  the Lists tab of Blocking both read its absence as "Not Scheduled".
- **`logs/query` filters by ONE `responseType`** (WebServiceLogsApi.cs:182-185),
  but the Dashboard's `totalBlocked` adds up three: `Blocked`, `UpstreamBlocked`
  and `UpstreamBlockedCached` (StatsManager.cs:329-341). "The latest blocked
  queries" is therefore three queries, merged by time: that is what Recently
  Blocked does (`api/blocking.ts`).
- **Careful with `\r\n` when replicating a list textarea.** Upstream builds its
  textareas with `\r\n`, but the browser normalises to `\n` when reading the
  value of a `<textarea>` from the DOM, and its cleanup only substitutes `\n`.
  In React there is no intermediate DOM to normalise: copying the literal
  `\r\n` sends `forwarders=1.1.1.1%0D,8.8.8.8%0D` to the server. **It bites any
  screen with lists in a textarea.**
- **An empty list travels as the string `"false"`**, it is not omitted: it comes
  out of concatenating a boolean into the query. With three exceptions that fall
  to their default value.
- **A screen with sub-tabs can be ONE SINGLE form.** In Settings, "Save" sends
  the fields of all nine sub-tabs wherever you are. Chopping it up per tab would
  change what gets saved.
- **An action bar can mix different permissions**: in Settings, saving requires
  `Settings.canModify`, flushing the cache `Cache.canDelete` and the backup
  `Settings.canDelete`.
- **Asymmetric permissions**: some actions ask for `Delete` where you would
  expect `Modify`, and `apps/list` is allowed with read permission on Apps,
  Zones **or** Logs. Do not deduce the permission: look at it.
- **Not every endpoint returns JSON.** `logs/download` answers `text/plain` with
  the file when it goes well and `application/json` with the usual envelope when
  it fails. It cannot go through `apiRequest`: that would do `res.json()` and
  turn any log into a network failure. Upstream asks for it with
  `isTextResponse` and, if what arrives carries `status`, draws it **formatted
  inside the viewer itself**, as if it were the file's content
  (logs.js:170-172). The error does not come out as an alert.
- **Two endpoints of the same family can call the same datum differently**: the
  log file is asked for with `fileName` in `logs/download` and with `log` in
  `logs/delete`. And `logs/list` returns the name **without extension**, which
  is the one to send in both.
- **Confirming or not confirming is not symmetric.** In DHCP, disabling a scope
  and deleting it both ask; **enabling it asks nothing** (dhcp.js:583 vs 615).
  Only the path that cuts the service asks.
- **`dhcp/scopes/set` is a PARTIAL update**: each field is applied only if it
  comes in the request (`WebServiceDhcpApi.cs:390-650`), so a body with only
  `name` and `newName` renames without touching anything else (checked against a
  v15.4 instance). Upstream always sends all 36. And **a scope created with this
  endpoint is born enabled**, even though nothing says so.
- **`dhcp/scopes/get` OMITS fifteen optional keys** instead of sending them
  `null`: `domainName`, `domainSearchList`, `serverAddress`, `serverHostName`,
  `bootFileName`, `routerAddress`, `dnsServers`, `winsServers`, `ntpServers`,
  `ntpServerDomainNames`, `staticRoutes`, `vendorInfo`, `capwapAcIpAddresses`,
  `tftpServerAddresses`, `genericOptions` and `exclusions`. `reservedLeases` is
  the exception: it is always written, even as `[]`. Same for `interfaceAddress`
  in `scopes/list`.
- **A field can be omitted on purpose when saving**: with "Use This DNS Server"
  checked, upstream **does not send `dnsServers`** (dhcp.js:565). The server
  keeps the stored ones and `scopes/get` still returns them, so the list you see
  on screen is not the one that was just sent.
- **"Deleting something that does not exist answers `ok`" has exceptions.**
  `dhcp/scopes/delete` on a non-existent scope answers `ok`, but
  `dhcp/leases/remove` on a non-existent lease answers **error**
  (`No lease was found for client identifier: …`).
- **Two alerts that look like the same one and are not.** In Query Logs, the
  "the app is missing" one ends in "…from the Apps section." when "Query" fires
  it and **does not** when "Export" does (logs.js:391 vs 614). Copying one into
  both places changes a text.
- **The last page is asked for with `pageNumber=-1`**: the server resolves it.
  That is what the "Last" link of Query Logs does (logs.js:589), verified
  against the reference instance.
- **The `ts` cache-buster goes on only two of the six downloads**: the settings
  backup (main.js:3100) and `logs/download` (logs.js:196). `logs/export`,
  `zones/export`, `allowed/export` and `blocked/export` **do not carry it**. The
  server ignores it, but the URL that gets opened is not the same.
- **A form filter can live in `localStorage`**: "Logs Per Page" is stored under
  the key `optQueryLogsEntriesPerPage` and re-read on every reset (logs.js:23-26
  and 63-65). Careful: the form's default value is **10** and the server's is
  **25** (`WebServiceLogsApi.cs:162`); the form's wins because upstream always
  sends the parameter.
- **`serializeTableData` decodes TWICE.** It applies `htmlDecode` to a value the
  browser had already decoded when parsing the HTML, so typing `&amp;` in a cell
  sends `&`. In React there is no intermediate HTML: replicating it would mean
  introducing the bug by hand, and that is not done.
- **Quick Select forgets the Bypass List.** Picking a forwarder that carries a
  SOCKS5 or HTTP proxy (Tor) ticks the proxy type and enables its address, port,
  username and password, but not the Bypass List (main.js:594-603): it stays
  disabled until the proxy radio is clicked again. That is an omission, not a
  rule, and it is not replicated: here the five fields follow the proxy type.
- **Picking the line already chosen does nothing.** A native `select` fires
  `change` only when the value changes, and several stock lists rely on it
  (Group Details' "None" empties Members; Quick Add would add a deleted key
  back). `ui/Select` does the same, and the Quick Add and Quick Select lists
  keep the line chosen, as the stock ones do, until their form loads again.
- **A `set` can return less than its `get`, and what is missing has to be kept.**
  `admin/sso/set` does NOT bring `localGroups`: `WriteSsoConfig` only writes them
  with `includeGroups` and the `set` calls it with `false`
  (WebServiceAuthApi.cs:1790). Upstream survives because it stored them in a
  global variable when doing the `get`. Reloading the form with the save
  response without keeping them leaves the group-map dropdowns empty.
- **A secret can come back MASKED and has to be sent back that way.**
  `admin/sso/get` returns `ssoClientSecret: "************"` as soon as one is
  stored, and `SetSsoConfig` ignores that exact value
  (WebServiceAuthApi.cs:1738). It is what allows saving the form without typing
  the secret again: clearing the field "because it looks like filler" would
  delete the real secret.
- **The same action can send different parameters depending on where it is
  fired from.** `admin/sessions/delete` ALWAYS travels with `node` from the
  Sessions tab (the primary node if the session is an API token, the chosen node
  in any other case) and **with no `node` at all** from the user details modal
  unless it is an API token (auth.js:1050 vs 1382).
- **A checkbox can change the ENDPOINT, not a parameter.** The cluster's "Force
  Remove Node" picks between `primary/deleteSecondary` and
  `primary/removeSecondary`; "Force Leave" and "Force Delete" in the same block
  really are parameters. They cannot be made uniform.
- **Deleting something that does not exist does NOT always answer `ok`.**
  `admin/sessions/delete` with an invented partial token answers `error` with
  "No such active session was found for partial token: …". Checked live against
  a v15.4; it is the exception to the rule noted above.
- **The group list depends on the endpoint that serves it.**
  `admin/permissions/get?includeUsersAndGroups=true` includes `Everyone` and
  `admin/groups/list` does not; `admin/sso/get?includeGroups=true` excludes it on
  purpose (WebServiceAuthApi.cs:383). Three group lists, three contents.
- **Two sibling endpoints can return different shapes of the same object.**
  `admin/groups/create` answers `{name, description}` and `admin/groups/set`
  also answers `members`. Same with the user: `users/get` brings `groups` (all
  the server's), `users/set` does not bring it even though it does bring
  `memberOfGroups` and `sessions`, and `users/list` and `users/create` bring
  none of the three. Checked live.
- **Half the response disappears when the cluster is not initialised.**
  `admin/cluster/state` on a standalone server is THREE fields: `version`,
  `dnsServerDomain` and `clusterInitialized`. `clusterDomain`, the four
  intervals and `clusterNodes` only exist with a cluster
  (WebServiceClusterApi.cs:60-75). And within a node, `upSince`, `lastSeen` and
  `configLastSynced` are **omitted** when they hold `default`, they do not
  arrive as `null`.
- **The cluster's "Quick Add" compares by SUBSTRING.** `cluster.js:30` uses
  `existingList.indexOf(ip) < 0`, so with `10.0.0.10` already in the list the IP
  `10.0.0.1` is never added. It is a bug of theirs and it is replicated: what
  the code does is copied, not what it looks like it wants to do.
- **A success alert dismisses itself after 5 seconds.** `showAlert`
  (common.js:212) schedules a `hideAlert` for `success` alerts and only for
  those. It is replicated here.
- **A whole section may filter NOTHING by permission.** Inside Administration,
  upstream checks `Administration.canView` to show or hide the section
  (main.js:165 and 240) and from there shows every button, letting the server
  reject. Adding client-side gating there would be adding behaviour, not
  protecting it.
- **Asymmetric permissions, the concrete Administration case**:
  `permissions/set` and `sso/set` ask for `Administration.canDelete`, not
  `canModify` (WebServiceAuthApi.cs:1533 and 1692). In the cluster, nearly
  everything asks for `canDelete` (including `init`, `initJoin` and `promote`),
  but `setOptions`, `resync`, `updatePrimary` and `updateIpAddress` ask for
  `canModify`.
- **`zones/list` OMITS `dnssecStatus` and `hasDnssecPrivateKeys` on Catalog and
  Forwarder zones**, and the Catalog also omits `catalog`. They are types that
  cannot be signed, so the server does not even write the fields. Declaring them
  required lies about half the list and in TypeScript it shows late.
- **The same table calls the same column differently.** In
  `zones/permissions/get`, a user permission brings `username` and a group one
  brings `name`. Treating them as the same shape leaves half the table blank.
- **`records/delete` has no branch for CNAME, DNAME, SOA or APP**: all four fall
  to the `default`, which only sends `rdata` if it exists, and it exists for
  none of them. The server receives zone+domain+type and nothing else. And
  **deleting an NS does not send `glue`, but disabling it does**: same pair of
  actions, different set of parameters.
- **Disabling a record reads the expiry TTL FROM THE MODAL, not from the row**
  (`updateRecordState`, zone.js:6236). If the modal has never been opened, it
  sends the empty string; if it was opened, it sends whatever was left inside.
  It is an upstream bug: it is replicated, and that is why the records screen
  drags that value along.
- **A record filter starting with `*` looks for the literal wildcard**, it does
  not list everything: after converting the glob to a regex, `showEditZonePage`
  rewrites a leading `.*\.` to `\*\.`. It serves to find the `*.zone` record,
  which in DNS really is called that. It looks like a bug and it is not.
- **The name filter without a wildcard is EXACT**, not "contains": typing `www`
  does not find `www.sub`. And it lowercases what you typed but **not** the zone
  name.
- **`zones/create` is a POST with the parameters in the QUERY**: the body is
  reserved for the optional zone file (`fileImportZone`). Without a file,
  upstream sends a POST with no body at all.
- **`zones/import` has TWO ways of sending the file**: uploading it goes as
  multipart and pasting it into the textarea goes as **raw plain text** with
  `Content-Type: text/plain`. The server tells them apart by that type.
- **The bulk zone delete uses the SAME endpoint** with the parameter in plural
  (`zones=`, comma-separated) and returns `deleted` and `failed`. When some
  fail, the alert is NOT an error: it is a `warning` counting how many.
- **The pagination window slides backwards on reaching the end**: on the last
  page the last ten are visible, not just one. And the last is asked for with
  `pageNumber=-1`: the server resolves it.
- **In the zone options, six empty lists travel as the string `"false"` and two
  do NOT**: `primaryNameServerAddresses` and `queryAccessNetworkACL` travel
  empty as they are. It is not symmetry; it is what `saveZoneOptions` does.
- **A zone that is a member of a catalog inherits its options**, and that
  governs the whole interface of `modalZoneOptions`: if the catalog does not let
  it override a section, that tab DISAPPEARS; if it does, it appears editable;
  and if a secondary catalog administers it as well, it appears read-only.
- **The tab that comes up open in the zone options is not the first**: on a
  Catalog it is "Query Access", and on a Primary it depends on whether there are
  catalogs available.
- **`convertZone` offers only three destinations** (Primary, Forwarder and
  Catalog), and which of them are enabled depends on the source through a table
  that follows from nothing: a Primary can only go to Forwarder.
- **The year has to be padded to four digits.** `0001-01-01T00:00:00` is .NET's
  `default(DateTime)` and turns up on every unused record; without padding,
  `getFullYear()` gives "1-01-01", which is not what moment writes.
- **In "Add Zone", the Catalog type shows NOTHING**: it has no branch in the
  visibility `switch`, so only the name and the type remain.
- **"Secondary ROOT Zone" is not a type**: it is a Secondary with the root
  server addresses preloaded, `zoneTransferProtocol=Tcp` and `validateZone=true`.
  The type that travels is `Secondary`.
- **The labels and the values of the DNSSEC dropdowns do not match**: you see
  "SHA256 (default)" and `SHA256` travels; you see "Ed25519 (default)" and
  `ED25519` travels in UPPERCASE.
- **In the DNSSEC properties, `isRetiring` switches off every action** of a key,
  and the automatic rollover only exists for ZSKs.
- **Since v15.5 a user has a `type`, and a remote user LOSES a field.** `user/login`,
  `user/session/get`, `user/profile/get` and every `admin/users/*` bring `type`
  (`Local`, `RemoteSSO`, `RemoteLDAP`) next to the obsolete `isSsoUser`, and
  **`totpEnabled` is omitted for a `RemoteSSO` user**, not sent as `false`
  (WebServiceAuthApi.cs:77-82 and 140-146). In the details, `ssoManagedGroups` is
  now written ONLY for SSO users and `remotelyManagedGroups` for every type
  (`false` for `Local`, lines 158-172). A screen still reading `ssoManagedGroups`
  unlocks the groups of every LDAP user. Checked live against v15.5.1.
- **`admin/ldap/get` on a fresh install is half `null`**: `ldapServer`,
  `ldapBindUsername`, `ldapBindPassword`, `ldapSearchBase`, `ldapUserSearchFilter`
  and `ldapGroupAttribute` arrive as `null`, `ldapPort` as `389`, and
  `ldapAllowSignupOnlyForMappedUsers` is **`true` while `ldapAllowSignup` is
  `false`**: the box comes up checked and disabled. `ldap/set` repeats SSO's
  lesson and drops `localGroups` (line 2136). Checked live against v15.5.1.
- **"Test Connection" is not a dry run of "Save".** It validates server and port
  even with LDAP disabled, ignores the group map and never asks the "Ignore SSL"
  confirmation (auth.js:2526-2541). The server fills any missing parameter from
  the STORED config and swaps the masked password for the stored one
  (WebServiceAuthApi.cs:2146-2160). Its error answers with no `response` key at
  all: `{"server", "status": "error", "errorMessage"}`.
- **`zones/export` answers an error with HTTP 200 and JSON**, the file with
  `text/plain`: a missing zone gives `{"status":"error","errorMessage":"No such
  zone was found: …"}` and a bad token `invalid-token`, both 200. The v15.5 "Edit
  Zone File" dialog reads it as text and, like `logs/download`, puts any answer
  carrying `status` FORMATTED into its textarea (zone.js:1262-1263 in v15.5.1): no
  alert, not even for `invalid-token`. Checked against v15.5.1.
- **`zones/import?overwriteZone=true` replaces the WHOLE zone, NS included.** A
  file with only SOA+NS+one A leaves exactly that; an EMPTY `text/plain` body
  answers `ok` and leaves the SOA alone. An unparsable file fails before
  touching anything, with `errorMessage` ("The zone file parser failed to parse
  'rdata' field on line # 1.") AND `innerErrorMessage` ("An invalid IP address was
  specified."); upstream shows only the first. With `overwriteSoaSerial=false`
  the serial is not kept either: the server bumps it. Checked against v15.5.1.
- **"Edit Zone File" never sends `overwrite`** (zone.js:1293): the server
  defaults it to `true` (WebServiceZonesApi.cs:1930). And its textarea is never
  cleared on opening, only overwritten when the read succeeds. After a read that
  never arrives, "Save" (always enabled) would send what the previous opening
  left, possibly another zone's file. Replicated; clearing it instead would send
  an empty file, which with `overwriteZone=true` empties the zone.
- **Saving a zone file reloads the zone, never the list** (zone.js:1302-1303):
  from the list's row menu nothing is refreshed afterwards.
- **What "Save Settings" sends depends on the node selector** (main.js:1639-1644).
  `node=""` sends every block, `node=cluster` only the cluster-wide ones (default
  values, EDNS/QPM/advanced, TSIG, Recursion, Blocking, Proxy & Forwarders) and a
  node name only that node's own (local parameters, IPv6/socket pool, Web Service,
  Optional Protocols, Cache, Logging). A skipped block skips its VALIDATIONS too.
  On a standalone server the selector is hidden and holds an empty `<option>`
  (cluster.js:1047-1049), so the stock console loads `settings/get?node=` and
  saves `node=&…`, never `cluster`, which there would drop every node
  parameter. Checked on the stock v15.5.1 of the harness. Flush, backup and
  restore take the same selector's node.
- **The envelope's `server` is the domain of the server that ANSWERED**, written
  after the handler runs (DnsWebService.cs:2478): after a rename it already
  carries the new name, and on a proxied request it is the chosen node's. Upstream
  follows the web console to its new address only when it equals the session's
  domain, which `updateDnsSettingsDataAndGui` has just rewritten for `node=""` or
  the own node (main.js:2208-2217, 3177-3188).
- **After a save or a restore the console may navigate on its own**: 2.5 s later
  it opens the new HTTP/HTTPS address in the same tab (`checkForWebConsoleRedirection`,
  main.js:2293), unless the LAST LOAD decided a reverse proxy is in front
  because the page's port is not the web service's (`checkForReverseProxy`,
  main.js:2275). In the harness `ref` is published on 5381 while its web service
  listens on 5380, so there the proxy is always "detected" and nothing redirects;
  `dev` is 5380 on both sides and does follow a port change.
- **Some notes quote the LOADED settings, not the fields.** The DoH/DoT/DoQ/DoH(S)
  addresses and both real-IP header notes are written by `loadDnsSettings`
  (main.js:1303-1304, 1356-1357, 1369-1372): typing a new port or header does not
  change them until the next load or save. Their initial HTML text
  (`localhost:8053`, `tls-certificate-domain:853`) is a placeholder, not contract.
- **Since v15.6 prefetching has its own switch, `enableCachePrefetch`**, true on a
  fresh install. A Prefetch Trigger of 0 no longer turns it off; instead, a config
  saved by an older server with the trigger below 1 loads with the switch off
  (DnsServer.cs, config version 7). A v15.5 server neither sends nor reads the key,
  so this console shows it unchecked there and the save is harmless. Checked live
  against v15.6.0 and v15.5.1.
- **A cluster node's `version` (v15.6) is not always there.** The node itself
  always carries it; another node only once a heartbeat has brought it. Right
  after a join the secondary appears without it and in state `Unknown`, and about
  30 s later as `Connected` with `15.6`. Checked live on a two-node v15.6.0 cluster.
- **The row menus' jumps carry their arguments as TEXT.** Query Logs writes
  `queryDnsServer(…, '<qtype>', '<node>')` into the `onclick` (logs.js:525), so a
  row without a type sends the string `"null"` and DNS Client does NOT default it
  to "A"; the Dashboard passes a real `null` and does get "A" (main.js:2824,
  dnsclient.js:232). Both jumps pick the target's node only when given one that is
  not `cluster` (dnsclient.js:243, logs.js:634); from the Dashboard's aggregate
  the target keeps the node it had. `allowDomain`/`blockDomain` send no `node` at
  all: they always act on the server the console is on.
- **The Dashboard's count cards are links to Query Logs since v15.6.2**
  (index.html:205-257, logs.js:21-24). Nine of the eleven: Total Queries with no
  filter, the four response codes filling `RCODE` and the four response types
  filling `Response Type`; Clients and Dropped are not links. The jump passes no
  node and no period, so Query Logs keeps its node and its empty `From`/`To`, even
  with the Dashboard on another node or period. Here each card carries the jump
  in `dashboard/metrics.ts` (`open`).
- **The Top Stats modal follows the Dashboard's node and keeps its own alerts.**
  It reads `optDashboardClusterNode` for `getTop` (main.js:2932), and allowing or
  blocking from it reports in `divTopStatsAlert`, inside the modal, while the same
  action from the Dashboard's panels reports on the page (main.js:2986 vs 2825).
- **The same action can be worded differently per table.** Opening a user is
  "View User Details" in the Sessions row menu (auth.js:938) and "View Details" in
  the Users one (auth.js:1191).
- **A blocked answer says why, but only in one setting and never for "allowed".**
  With `allowTxtBlockingReport` on (the default), a blocked query carries an
  Extended DNS Error with `InfoCode: "Blocked"` and `ExtraText`
  `source=blocked-zone; domain=<rule>` (DnsServer.cs:4672) or
  `source=block-list-zone; blockListUrl=<url>; domain=<entry>`
  (BlockListZoneManager.cs:893), one option per list that carries the name, the
  same for every blocking type; `dnsClient/resolve` returns it in
  `result.EDNS.Options` and again in the OPT record of `Additional`. `domain` is
  the entry that matched, a PARENT of the name asked when a rule or a list covers a
  whole zone. With the setting off the answer carries nothing. Nothing marks an
  answer as allowed by an allow rule, and an unrelated `Synthesized` option ("Result
  from negative cache") can sit in the same list. The client library adds its own
  `DnsClientExtendedErrors` (`BlockedByUpstreamDnsServer`), which names no reason.
  A name the server refuses (`not a domain`) is an `error` envelope with no
  `response` at all. Checked live against v15.6.1 on 2026-10-15
  (`screens/blocking/check-domain.real.json`).

## How the code is written

- **Client**: always `apiRequest` from `src/api/client.ts`. Paths **relative and
  without a leading slash** (`'zones/list'`), because the server honours
  `X-Forwarded-Prefix`.
- **One `src/api/<family>.ts` file per endpoint family**, with its types. It
  should return data that is already usable, and `null` or an empty list on
  failure, but only where an empty result and a failure cannot be confused. If
  the screen would draw them the same, return the whole `ApiOutcome`: saying
  "no queries for this period" when the call never arrived is worse than an
  error.
- **Primitives** in `src/ui/`: `Button`, `Alert`, `Field`/`LabeledInput`,
  `Dialog`. Do not invent loose buttons or fields.
- **Colours always by token** (`var(--acc)`, `var(--ink)`…). Not one `#hex`,
  `rgb()`, named colour or colour inside an inline SVG outside
  `src/theme/tokens.css`, and inside it only in a theme block
  (`:root, [data-theme='dark']`, `[data-theme='light']`), so every colour is one a
  theme can redeclare. `color-scheme` too: only a theme block declares it, and
  every element inherits it. **`npm run lint:colours` (`dev/check-colour-tokens.mjs`)
  enforces it**, and `npm test` runs it too. What genuinely cannot be a token (the
  white behind the 2FA QR code) is allowed by file and literal in that script, with
  its reason.
- **One CSS module per component** (`X.module.css`).
- **Spacing, type and radii by token too.** In a `*.module.css` you do not write
  a px that is not one of the tokens in `theme/tokens.css`. A loose value is
  future drift: that is how the console reached 13 text sizes and 25 paddings.
- **Upstream's themes, without Amber.** System (the default), Light and Dark,
  picked in `Change Theme` (deviation 1 below). Each theme declares its colours in
  its own block of `src/theme/tokens.css`, and `npm run lint:colours` fails if the
  light block leaves out a colour the dark one declares. A theme is measured before
  it ships: contrast and chart distance against each one, not only against dark,
  with `node dev/theme-contrast.mjs` (every text and control token on every
  surface it is drawn on) and `node dev/palette-distance.mjs` (the chart series).
- **Everything is in ENGLISH**: the interface, the code, the comments and the
  tests. The console is `lang="en"` and the destination is a pull request
  upstream. **`npm run lint:language` is what enforces it**, and it exists because
  the rule was broken for three weeks without anybody noticing: the visual
  redesign left 1,098 pieces of Spanish across 67 files (comments, identifiers and
  nineteen file names) while the interface stayed English and every other gate
  stayed green. A rule nothing measures is a preference.
- **A name is never cut letter by letter.** `word-break: break-all`,
  `word-break: break-word` and `overflow-wrap: anywhere` are refused by
  `npm run lint:breaks` (`dev/check-word-breaks.mjs`, also run by `npm test`) outside a short list
  of things with no words (keys, signatures, raw output), each with its reason. A
  DNS name goes through `ui/DomainName`, a URL through `ui/UrlText`, other text
  through `overflow-wrap: break-word`.
- **No `BrowserRouter`**: the server's only `MapFallback` is `/api/{*path}`.
- **No CDN and no fonts in `data:`**: the server's CSP does not declare
  `font-src`. Images in `data:` are fine (`img-src 'self' data:`).

## Tests

- `npm test`: vitest. **Do not run `npm run build`** if someone else is
  working in the same checkout: it writes into `dist/` and you would step on each other.
- Every screen needs tests for: **the literal alert texts**, the **validation
  order**, which endpoint is called and with what body, and the behaviour with
  empty data.
- Query by label (`getByLabelText`), not by class.
- **Do not assume a call is the first one**: find it.
  `spy.mock.calls.find(c => c[0] === 'zones/list')`.
- With fake clocks, `findBy*` does not work: use
  `vi.useFakeTimers({ shouldAdvanceTime: true })` and
  `userEvent.setup({ delay: null })`.
- **No apostrophes in a test description written with single quotes.** "the
  server's failure" inside `it('…')` does not parse, and it takes the whole file
  with it. Reword it: "the failure from the server".

## Deliberate deviations from upstream behaviour

The rule is "zero functionality", with the exceptions below **decided and
written down**. Additional exceptions need the maintainer's authorization.

Security fixes authorized on 2026-10-04 add one transport exception: DNSSEC
signing and private-key import use POST form bodies instead of GET query
parameters. Upstream accepts both methods and reads these fields with
`GetQueryOrForm`. The endpoint, fields and user actions remain the same. Session
revocation and expiry cleanup are bound to the affected token rather than
mutable shared storage. Installer filesystem requirements are recorded in its
contract and SECURITY.md.

1. **Amber is not offered** (Adrián's decision). `Change Theme` is back as
   upstream has it: in the account menu, under the same `localStorage` key,
   `theme`, as the stock console (same origin, so a choice made in one holds in
   the other), with `system`, `light` or `dark`. System is the default and follows
   `prefers-color-scheme` live; a radio applies on click; nothing is written on
   load. Only the Amber radio is missing: a stored `amber` draws dark, is not
   overwritten, and the dialog shows no radio checked until the user picks. It is
   still the only one that *removes* something. The rules are in
   `src/theme/theme.ts`.
2. **The Blocking section** (`src/screens/blocking/`; what it offers is listed
   in the CHANGELOG, v1.2.0). It replaces Allowed and Blocked
   with Overview, Rules and Lists. Its Quick Add also offers the console's own
   catalogue (`extra-lists.json`) after Technitium's, and a search field.
   Its Overview's "Check, block or allow a domain" panel also has **Check**
   (`check-domain.ts`, `DomainCheck.tsx`): it tells whether this server blocks a
   name and why (which block lists, with the name the Lists tab gives each; which
   of your blocked rules; which of your allow rules lets it through; or not
   blocked). It asks what DNS Client asks, `dnsClient/resolve` against
   `this-server` (type A, UDP, no DNSSEC validation, no import), and reads the
   server's own blocking report from the answer; beside it, `settings/get` and
   `allowed/export`, each skipped when its permission is missing. It sends no
   `node`, as the Block and Allow beside it. Its query is a real one, counted and
   logged by the server like any DNS Client query. When the answer cannot prove
   the verdict it says so instead of guessing: "Cannot tell" when `Allow TXT
   Blocking Report` is off or when the `Blocking Bypass List` covers the server's
   own address, and a "Not blocked" lists the reads it did not have. Its words,
   all OURS: `Check`, the `Check, ` of the panel title, `Please enter a domain name
   to check.`, the verdict titles (`Blocked by a block list`, `Blocked by N block
   lists`, `Blocked by your rule`, `Blocked`, `Allowed by your rule`, `Not
   blocked`, `Not blocked: blocking is disabled`, `Not blocked: blocking is
   paused`, `Cannot tell`), `Listed as`, `Rule`, `Open Lists`, `Open Rules`, the
   two "Cannot tell" sentences and the four "not checked" / "Could not read"
   lines. Its next step is the panel's own `Block` and `Allow` and the tab that
   holds the rule or the list: it adds no action.

   The section is the only one that *adds* a screen. It stays inside four limits, and a
   change that crosses one is a bug:
   - **only endpoints the server already has**, and only ones upstream's console
     already calls, save `dashboard/metrics/json` for its live Last Hour
     (exception 5). `dev/check-endpoints.mjs` measures the other direction
     (upstream's endpoints this console covers), so a new path is checked by
     hand against upstream's `www/js`;
   - **upstream's actions, sentences and call sequences**: `Allow Domain` is
     still `blocked/delete` then `allowed/add` (`api/blocking.ts`);
   - **what is ours is in English and says so** in the header comment of its
     file;
   - **Settings › Blocking is untouched**: the Lists tab edits the same
     `blockListUrls`, through the same cleaning (`list-lines.ts` calls
     Settings' `cleanList`).

   Two behaviours a maintainer would not guess:
   - **`/allowed/` and `/blocked/` still exist as folders.** They are legacy
     routes (`LEGACY_ROUTES` in `app/static-routes.ts`): `translateLegacyRoute()`
     in `app/route.ts` rewrites them, with `replaceState`, to
     `blocking/rules/?rule=allowed|blocked` before the route is read, so old
     bookmarks land on the filtered Rules tab.
   - **`?rule=` belongs to Rules alone.** `Blocking.tsx` strips it on switching to
     Overview or Lists and on leaving the section, by replacing the current
     history entry, which is the Rules one. So Back after leaving Rules returns
     to Rules showing All, not the filter the user had. That is deliberate:
     keeping it would mean teaching `writeRoute` about one section's query.

   Three additions approved on 2026-10-15, inside the same four limits:
   - **Groups in Lists.** A comment line of `blockListUrls` is a group heading:
     the lists after it belong to it until the next heading, and the lists before
     the first one have no group. Headings can be added, renamed and removed (their
     lists stay, joining the group above), a new list can be put into a group, and
     a list moves up or down, across headings too. All of it is a change to the
     same lines, kept until Save. A heading is saved as `# Name` and refused when
     the server would not keep it as one comment line: a comma (the field travels
     comma-separated), a newline, more than 253 characters, or a name that reads as
     a list URL. Settings › Blocking still shows the headings as the comments they
     are. Order changes nothing that is blocked (`list-lines.ts`, GROUPS, with the
     server lines that say so).
   - **Rules' table deletes without asking, and offers Undo.** Its Delete sends
     `blocked/delete` or `allowed/delete` at once and leaves a notice (`ui/Toast`)
     whose Undo sends `blocked/add` or `allowed/add` for exactly the domains
     deleted, each to its list. Further deletes while it is up join it. Without
     `Modify` on the rule's list Undo could not work, so that Delete still asks.
     Upstream's confirmation stays everywhere else: the Tree view, Flush and every
     other section. This is the only place in the console where a confirmation was
     replaced.
   - **The sidebar marks Blocking when blocking is off or paused**, with the time
     it comes back in the entry's accessible name and title. It reads what the
     Overview's status block reads (`settings/get`, on the connected node), never
     without `Settings.canView`, and again after any settings write made from this
     console, when the browser tab is shown again and a second after a pause ends.
     No other sidebar entry carries a mark or a count.

   And words of its own in three places, approved on 2026-10-15, all OURS and
   declared in the header comment of the file that writes them:
   - **a subtitle under each tab's title**, one plain sentence saying what the tab
     is for (`OVERVIEW_SUBTITLE`, `RULES_SUBTITLE`, `LISTS_SUBTITLE`, drawn by
     `ui/SectionHeader`'s `subtitle`). No other section has one: they keep upstream's
     texts only. A sentence that stops being true of its tab changes in the same
     commit;
   - **Lists' save bar says what changed**: `Unsaved changes to the block list URLs:`
     followed by the counts `changesOf` computes (`list-lines.ts`, WHAT CHANGED):
     added, removed, switched on, switched off, changed, moved, and groups added,
     renamed and removed. Only the non-zero ones are written;
   - **the Lists tab carries a dot while there are unsaved changes**, read as
     `Lists, unsaved changes` (`ui/SubTabs`'s `marks`). The edits still live only
     while the tab is open, as before: leaving it leaves them, and the dot with them.
3. **Settings jumps to the sub-tab of the invalid field.** Upstream focuses a
   hidden input and the user sees nothing; with one panel mounted at a time,
   without that jump the alert would be impossible to resolve.

   And for the same reason (one save sends the fields of all nine panes, wherever
   you are), **Settings says what the save would change** (approved on
   2026-10-16, `screens/settings/pending.ts`). While a field would be sent with a
   value other than the one the server returned, the save bar reads
   `Unsaved changes:` followed by the panes that hold one and how many fields each,
   `General (2), Cache (1)`, in tab order, and each of those sub-tabs carries the
   dot Lists carries, read as `<Tab>, unsaved changes` (`ui/SubTabs`'s `marks`).
   Those two phrases are the only new words; the pane names are upstream's tab
   labels. It compares what the save would send, with the save's own cleaning, so
   a field put back as it was, a blank line in a list and an untouched field never
   count; nor does a field the save would not send (outside the chosen node's
   scope, or a proxy detail with no proxy type), nor the minutes of `Temporary
   Disable Now`, which is not a setting. It only displays: saving, Backup,
   Restore, Flush Cache and the blocking buttons behave exactly as before.
4. **The "Enable DNS-over-HTTP/3" checkbox re-enables itself.** In upstream it
   stays dead until the page is reloaded because nothing re-evaluates its state:
   that is a bug of theirs, and replicating it would mean introducing the fault
   on purpose.
5. **Last Hour moves in real time** (Adrián's decision, 2026-10-03), on the
   Dashboard and on Blocking › Overview, which read the same `stats/get`.
   Between the 60-second reloads the count tiles, the Queries chart and the
   Query Response Types doughnut (and on Overview its figures, sparklines, bars
   and ring) follow the server's lifetime counters (`dashboard/metrics/json`),
   read every 2 seconds (`dashboard/live.ts`, `dashboard/useLive.ts`). Overview
   gained the minute reload with it. Live readings keep their timestamps across
   reloads: only readings after the last server UTC label are added. Labels name
   the end of each closed minute (StatsManager.cs:675-704), so a response that has
   not consolidated a pending reading cannot erase it. The history is bounded
   to the displayed hour; gaps between measured minutes occupy chart slots.
   A polling interval that straddles the server boundary is assigned to its end
   until a later consolidated response replaces that approximation.
   A chart takes new figures in place and
   without animation (`Chart.tsx`), and a legend's switched-off series only come
   back with a new response, as upstream's rebuilt chart does. Its limits, and
   crossing one is a bug:
   - **only that endpoint**, which upstream documents in APIDOCS.md and its
     console does not call; `check-endpoints.mjs` counts upstream's endpoints, so
     it does not object;
   - **Clients, Query Types, Protocol Types, the tops and the Server panel never
     move**: the counters do not carry them, and distinct clients do not add up;
   - **if the endpoint fails three times in a row, live mode stops** until the
     next reload, and the screen is exactly what it was without it;
   - **Recently Blocked follows the displayed Blocked count** through its existing
     `logs/query` reads. Background refreshes keep the previous rows, serialize
     requests and invalidate queued work when token, node or permissions change;
   - **a hidden tab reads nothing**, the minute refresh included, and coming
     back reloads at once. That pause is the only change to an upstream request.
6. **The login screen has a cover** (Adrián's decision, 2026-10-15): a brand
   panel beside the stock form above 960 px, and a header above it below,
   compact under 560 px (`screens/LoginCover.tsx`). It changes the layout and
   nothing else. Its limits, and crossing one is a bug:
   - **the form is upstream's, whole**: every field, text, step (the OTP one
     included), validation, alert and behaviour of `Login.tsx` is untouched, and
     it stays alone inside `<main>`; the cover is an `<aside>` outside it, and
     upstream's `Technitium DNS Server` is still the only `<h1>`;
   - **its words are ours and say so** in the header comment of its file: the
     name, the headline and the four TXT records. They must not age (no "new")
     and each must be true of the console as it ships; a line that stops being
     true changes in the same commit. It shows the console's version from the
     build and nothing else: no screenshot and no figure, since nobody has
     logged in yet and anything that looks like data would be invented;
   - **it calls nothing**: no endpoint, no asset beyond the fonts the console
     already ships, and its colours are theme tokens measured on `--field` by
     `dev/theme-contrast.mjs`. Its only motion is the answer rows settling in,
     and `prefers-reduced-motion` removes it.

7. **The Dashboard compares and jumps** (Adrián's decision, 2026-10-15). It adds
   two things to the stock Dashboard (`screens/dashboard/compare.ts`, `jump.ts`):
   - **each figure's change against the previous period of the same length**, as
     an arrow and a percentage on its card, with what it is measured against
     written once, in the `Total Queries` card ("vs previous hour"). The
     previous period is a second `dashboard/stats/get` with `type=Custom`, whose
     instants are worked out from the labels of the answer on screen, so they follow
     the server's clock, its node and its grouping. Measured against v15.6.1 and
     v15.5.1 on 2026-10-15: Custom over a fixed period's own window gives the same
     ten counters, bucket by bucket, for all five fixed periods, and the same
     Clients wherever the request is exactly the window. Clients gets no change for
     Last Week (seven days by day cannot be asked; eight are, and the counters are
     summed over seven), for Last Year (asked by day; the server reaches a distinct
     count of months and of days through different merges) and for a minute that
     kept only part of its clients (more than 1,000). The other ten compare in
     every period;
   - **a jump from a chart to Query Logs**: a point of `Queries` opens its minute,
     hour, day or month as `From`/`To`; a segment of the `Query Response Types`,
     `Query Types` or `Protocol Types` bar opens that value over the period, where
     Query Logs has a field for it (`Dropped` and `Others` do not). It is the jump
     of the Top lists' "Show Query Logs" (`app/handoff.ts`), with the same node
     rule, the same arrival and the same alert when no logging app is installed.
     The three breakdowns are stacked bars in one card (the cockpit layout,
     Adrián's choice of 2026-10-15, `Breakdown.tsx`). Query Response Types keeps
     the stock legend's click-to-hide; on Query Types and Protocol Types there is
     no slice to hide, so their legend entries are the jump instead;
   - **a week by hour** (`Heatmap.tsx`, `heatmap.ts`): seven days of the browser's
     calendar by its 24 hours, each cell the queries of that hour, opening Query
     Logs for that hour on click. Custom groups by hour only up to 157 hours, so
     the week is asked in two back-to-back pieces and stitched; an hour that comes
     twice or not at all leaves the panel saying it could not load, never a double
     count or a quiet hole. Checked on 2026-10-15 against v15.6.1: the stitched
     hours equal Last Day's 24 and a single 157-hour request, hour by hour. The hour
     in progress is left out, as Last Day leaves it. It is asked once per node and
     per hour, not on each minute reload.

   Its limits, and crossing one is a bug:
   - **only `dashboard/stats/get`**, which the stock Dashboard already calls, and
     Query Logs' existing fields. A Last Hour reload waits for both reads so the
     changes do not blink; other periods ask once more per load; the week asks one
     or two more per hour;
   - **no change is drawn unless it is exact and current**: never while another
     period or node is loading, never after a failed read (of either period),
     never for a figure whose previous value is zero, never when the previous
     period has no queries at all (a server keeping statistics in memory only, or
     one that was not running yet). A previous period the server only partly
     recorded (it started inside it, or its stats files were deleted) is compared
     as recorded: the API cannot tell a quiet hour from a missing one;
   - **upstream's texts are untouched.** What is ours is in English, declared in the
     header comment of each file that writes it: "vs", "previous hour",
     "previous 24 hours", "previous 7 days", "previous 31 days", "previous 12
     months", "previous N minutes/hours/days" (`compare.ts`, `Figures.tsx`,
     `Dashboard.tsx`), the Queries hint "Click a point to open Query Logs for that
     minute/hour/day/month" (`Dashboard.tsx`), the week's title "Queries per Hour,
     Last 7 Days", its weekday names, each cell's "HH:00 to HH:00: N queries", its
     hint "Click a cell for that hour's Query Logs" and its scale's "Quiet" and
     "Busy" (`Heatmap.tsx`, `heatmap.ts`), and the legend entries' "Show Query Logs"
     title, which is upstream's own menu text. The two hints show only when the
     click can land;
   - **pointer only on the canvas and the bars.** A point of `Queries` and a
     segment of a breakdown bar take a click but no keyboard focus; the Query Types
     and Protocol Types legend entries are buttons, and the week is one keyboard
     stop whose arrows move between its cells.

8. **Query Logs folds its filters below 960 px** (approved on 2026-10-16;
   `FOLD_QUERY` in `screens/logs/QueryLogs.tsx`). At 390x844 the fourteen filters
   were one column 1,173 px tall and the first result row ended at y=1,905; at 768
   the table still started at y=1,001. Below 960 the panel closes to its title,
   which becomes the toggle, and `Query` closes it again; the legend keeps its seven
   pills and puts their conditions behind its title. Above 960 nothing of this
   exists. Its limits, and crossing one is a bug:
   - **a folded panel says what is set**: every field that differs from what
     `Reset` gives, by its field's own label and with the value the field shows
     (`activeFilters`), so a filtered table never reads as the whole log;
   - **nothing it sends changes**: the fields stay mounted while folded, and Query,
     Export, Reset, Live Update and the pager send exactly what they sent;
   - **a validation still lands on its field**: a folded panel opens before
     upstream's focus (logs.js:389-424 and 612-625) moves to the field that failed.

   Its words: none new. The toggles are the panel's existing title, `Filters`, and
   the legend's, `Row colours`; the list is the fields' own labels, each followed by
   a colon and its value.
9. **About has two panels for this console** (Adrián's decision, 2026-10-16;
   `screens/about/About.tsx`). Upstream's About speaks only of the server, and its
   card stays literal. Under the Server panel, `Web Console` gives this console's
   version (`__CONSOLE_VERSION__`), its license, one sentence saying it is not
   Technitium's, and four destinations as rows: `Source code`, `Release notes`,
   `Report a problem` (so a console fault does not go to Technitium's support) and
   `Ideas and questions`. `Support the Console` has one sentence, `Star on GitHub`
   and the four destinations of `.github/FUNDING.yml` as buttons. Its words are all
   ours and follow the README's `Support` and `Licence`.
10. **The console tells you when a newer console is out** (Adrián's decision,
    2026-10-18; `app/console-update.ts`, `app/Versions.tsx`, `update-check/`). The
    browser cannot ask GitHub (the CSP below has no `connect-src`), so the console
    asks its own server, with `dnsClient/resolve`, for the TXT of
    `latest.technitium-console.pages.dev` against
    `https://technitium-console.pages.dev/dns-query` (`protocol=HTTPS`, no DNSSEC,
    no import). That endpoint is this repo's `update-check/`, a Cloudflare Pages
    Function that answers `v=1 latest=X.Y.Z server=A.B`. When a newer release is
    made for the running server, the *Web Console* row gets the same `Update`
    mark as the server's, and a dialog with the two commands from the README,
    each with a Copy button (the console cannot run them: no call of the server's
    API replaces its files). Its limits, and a change that crosses one is a bug:
    - **only that call**, and **at most once a day per browser**: the result,
      failures included, is kept in `localStorage` under `consoleUpdateCheck`. A
      failed call writes a line in the server's log (`DnsWebService.cs:2556`), so
      one a day is the ceiling;
    - **only when `user/checkForUpdate` answers `dnsServerEnableCheckForUpdate:
      true`** and the session has *DNS Client: View*. The server's *Check for
      update* and a silenced notice turn both notices off; there is no setting of
      its own;
    - **never with `node`**: every node of a cluster serves its own console;
    - **silent on any failure**, and nothing from the answer is shown but the
      version numbers, each checked against `^\d+\.\d+(\.\d+)?$`;
    - **the record's format is frozen**: consoles already installed read `v=1`,
      `latest` and `server`, and ignore keys they do not know. Grow it, never
      change it;
    - **`server` is the oldest Technitium a release is made for**: it is
      `technitiumServerMinimum` in `package.json`, read by the endpoint at the
      release's tag, and it is bumped together with the CHANGELOG's table. A
      console never announces a release made for a newer server than the one
      running;
    - the endpoint announces a release only once `latest` on GHCR is that
      release's image, so that Docker users who pull get it; and a GitHub rate
      limit is a failure, not "nothing to announce": the last good record stands.
    Its words, all OURS: `Web Console update available` and `DNS Server update
    available` (the two marks' accessible names), `New Web Console Version
    Available!`, `To update, run the installer again:`, `On Docker:`, `Release
    Notes` and the dialog's `Note!`.
11. **A client with no domain shows no "."** (Adrián's decision, 2026-10-21;
    issue #22). Upstream writes `.` under a top client whose `domain` comes
    empty (`main.js:2799`, `main.js:2955`), the root, which is what every client
    with no PTR gets: most IPv6 clients. Users read it as a stray trailing dot on
    the address. The Dashboard's Top Clients card and the Top 1000 modal draw no
    domain line for it instead; a client with a domain still shows it. Nothing
    else changes: the same call, the same rows, the same name and menu.

## Four constraints the server imposes

These are not preferences: break them and the console works in development and
fails in production.

- **`base: './'`.** The server honours `X-Forwarded-Prefix` and mounts a
  `PathBase`. With absolute paths the console works locally and 404s behind a
  reverse proxy with a prefix. `dev/check-prefix.sh` checks it.
- **Real routes, one folder per route.** The server's only `MapFallback` is
  `/api/{*path}`, so a deep route with no file on disk would 404. The build emits
  one folder with its own `index.html` for each of the console's 34 routes (11
  sections and 23 sub-sections, from `SECTIONS`), plus the two legacy folders
  `/allowed/` and `/blocked/`: 36 in all. The URL is real (no `#/`) and F5 brings
  you back where you were, without touching a line of C#. See `vite.config.ts` and
  `app/static-routes.ts`.
- **Content-Security-Policy**: `default-src 'self'; script-src 'self'
  'unsafe-inline' 'unsafe-eval'; style-src 'self' 'unsafe-inline'; img-src 'self'
  data:`. There is no `font-src`, so **the fonts have to be files served from the
  same origin**: a font embedded as a `data:` URI inherits `default-src 'self'`
  and does not load. No CDN is possible either.
- **`public/` holds the assets the server or the console still need**:
  `favicon.ico`, `robots.txt`, `img/` (including `oidc.png`, which the login uses)
  and `json/*-builtin.json`. The build emits them again.

## Closing

When you finish, write down which endpoints you covered and **any upstream
behaviour you discovered that was not already noted**. That last part is the
most valuable thing you can contribute.