fhirsmith 0.17.0 → 0.18.0

package/registry/crawler.js

@@ -12,6 +12,7 @@ const {
   ServerInformation,
   ServerVersionInformation,
 } = require('./model');
+const { UptimeHistory } = require('./uptime');
 const {Extensions} = require("../tx/library/extensions");
 const {debugLog} = require("../tx/operation-context");
 
@@ -44,11 +45,16 @@ class RegistryCrawler {
       apiKeys: config.apiKeys || {}, // Map of server URL or code to API key
       allowPrivateAddresses: config.allowPrivateAddresses || false, // SSRF opt-out for local test servers
       // the most a server's response can be, once unzipped: the servers are other people's
-      maxResponseBytes: (config.maxResponseMB || 100) * 1024 * 1024
+      maxResponseBytes: (config.maxResponseMB || 100) * 1024 * 1024,
+      uptimeRetentionDays: config.uptimeRetentionDays,
+      uptimeWindowDays: config.uptimeWindowDays
     };
     this.stats = stats;
 
     this.currentData = new ServerRegistries();
+    // one record per endpoint per scan: whether it answered. Reported on the software page
+    this.uptime = new UptimeHistory({ retentionDays: config.uptimeRetentionDays, windowDays: config.uptimeWindowDays });
+    this.scanTime = null; // when the scan in progress started (ms)
     this.crawlTimer = null;
     this.isCrawling = false;
     this.errors = [];
@@ -133,6 +139,7 @@ class RegistryCrawler {
 
     this.isCrawling = true;
     const startTime = new Date();
+    this.scanTime = startTime.getTime();
     this.errors = [];
     this.totalBytes = 0;
     
@@ -168,6 +175,7 @@ class RegistryCrawler {
       
       // Update the current data
       this.currentData = newData;
+      this.uptime.retain(this.endpointAddresses(newData), this.scanTime);
     } catch (error) {
       debugLog(error);
       this.addLogEntry('error', 'Exception Scanning:', error);
@@ -326,6 +334,7 @@ class RegistryCrawler {
       version.valueSets = [...new Set(version.valueSets)].sort();
       version.lastSuccess = new Date();
       version.lastTat = `${Date.now() - startTime}ms`;
+      this.uptime.record(version.address, true, this.scanTime || startTime);
 
       this.addLogEntry('info', `  Server ${version.address}: ${version.lastTat} for ${version.codeSystems.length} CodeSystems and ${version.valueSets.length} ValueSets`);
       
@@ -335,12 +344,33 @@ class RegistryCrawler {
       this.addLogEntry('error', `Server ${version.address}: Error after ${elapsed}ms: ${error.message}`);
       version.error = error.message;
       version.lastTat = `${elapsed}ms`;
+      // a scan cut short (the server shutting down) says nothing about the endpoint
+      if (!this.abortController?.signal.aborted) {
+        this.uptime.record(version.address, false, this.scanTime || startTime);
+      }
       this.carryForwardSoftware(version);
     }
     
     return version;
   }
 
+  /**
+   * Every endpoint address in a scan's data
+   */
+  endpointAddresses(data) {
+    const result = [];
+    for (const registry of (data && data.registries) || []) {
+      for (const server of registry.servers || []) {
+        for (const version of server.versions || []) {
+          if (version.address) {
+            result.push(version.address);
+          }
+        }
+      }
+    }
+    return result;
+  }
+
   /**
    * CapabilityStatement.software.releaseDate, if it means anything. A date within a few
    * minutes of now is the server's clock, not a release date: FHIRsmith up to 0.14.2 filled
@@ -710,6 +740,16 @@ class RegistryCrawler {
     return this.currentData.toJSON();
   }
 
+  loadUptime(json) {
+    this.uptime = UptimeHistory.fromJSON(json, {
+      retentionDays: this.config.uptimeRetentionDays, windowDays: this.config.uptimeWindowDays
+    });
+  }
+
+  saveUptime() {
+    return this.uptime.toJSON();
+  }
+
   /**
     * Add log entry to the crawler's log history
   * @param {string} level - Log level (info, error, warn, debug)

package/registry/documentation/api.md

@@ -0,0 +1,162 @@
+# Registry API
+
+The normative description of the coordination server API is the
+[ecosystem page](https://build.fhir.org/ig/HL7/fhir-tx-ecosystem-ig/ecosystem.html) of the
+terminology ecosystem IG. This page describes what this registry implements, including where
+it extends the IG. The machine-readable description is the OpenAPI 3.1 document, which is the
+contract:
+
+| URL | |
+|---|---|
+| `/tx-reg/openapi` | Browsable reference (HTML), with a "try it" form for each operation; the JSON for other clients |
+| `/tx-reg/openapi.json` | The description as JSON |
+| `/tx-reg/openapi.yaml` | The description as YAML - the source file, [openapi.yaml](../openapi.yaml) |
+
+Every response carries `Link: </tx-reg/openapi.json>; rel="service-desc"` (RFC 8631), and the
+HTML pages the matching `<link>` element.
+
+There are two operations, both `GET`:
+
+| Endpoint | |
+|---|---|
+| `/tx-reg/` | **Discovery** - the server endpoints in the ecosystem |
+| `/tx-reg/resolve` | **Resolution** - which endpoints to use for a code system or value set |
+
+Both answer JSON, or an HTML page when the request's `Accept` header contains `text/html`.
+`/tx-reg/resolve` in a browser without parameters is a form for trying it. Parameters are read
+leniently: unknown parameters are ignored, and a repeated parameter takes its first value
+(existing ecosystem clients depend on this).
+
+When the registry is secured ([security.md](security.md)) the JSON forms of both require a
+token, sent as `Authorization: Bearer {token}` or `Api-Key: {token}`; without one they answer
+`401` with `WWW-Authenticate: Bearer realm="tx-reg"`. The HTML pages and the OpenAPI
+description are always open.
+
+## Discovery: `GET /tx-reg/`
+
+Lists the endpoints in the ecosystem, one entry per server per FHIR version.
+
+| Parameter | |
+|---|---|
+| `registry` | Only endpoints from this registry (its code in the master file) |
+| `server` | Only endpoints of this server (its code in its registry) |
+| `fhirVersion` | Only endpoints for this FHIR version: `R4`, `R4B`, `R5` ... or `4.0.1`, `4.0` |
+| `url` | Only endpoints that host this code system (`url` or `url\|version`), the authoritative ones first |
+| `authoritativeOnly` | With `url`: only endpoints authoritative for it |
+| `language` | With `url`: prefer endpoints with a language specific claim for it |
+
+```json
+{
+  "last-update": "2026-10-21T22:30:11.412Z",
+  "master-url": "https://fhir.github.io/ig-registry/tx-servers.json",
+  "results": [
+    {
+      "server-name": "tx.fhir.org", "server-code": "tx.fhir.org",
+      "registry-name": "HL7 Terminology Services", "registry-code": "hl7",
+      "registry-url": "https://raw.githubusercontent.com/FHIR/ig-registry/master/hl7-tx-servers.json",
+      "url": "http://tx.fhir.org/r4", "fhirVersion": "4.0.1",
+      "error": null, "last-success": 184233, "systems": 2311,
+      "authoritative": ["http://hl7.org/fhir/*", "http://terminology.hl7.org/*"],
+      "authoritative-valuesets": ["http://hl7.org/fhir/ValueSet/*"],
+      "security": "open", "open": true
+    }
+  ]
+}
+```
+
+`error` is what went wrong the last time the endpoint was scanned (null if it worked), and
+`last-success` is how many milliseconds ago it was last scanned successfully. Without `url`,
+`authoritative` and `authoritative-valuesets` are the server's claim masks as registered, and
+there are no candidate lists - listing everything every server hosts would be enormous. With
+`url`, an entry has `candidate: [url]` when the endpoint hosts the code system without
+claiming authority for it, and with `language` too, `languages` gives the tag of the claim the
+endpoint matched on.
+
+## Resolution: `GET /tx-reg/resolve`
+
+Returns the endpoints to use for one code system or value set at one FHIR version: those
+authoritative for it, then the other candidates that host it. Choosing between several is the
+client's business (the Java tooling takes the first).
+
+| Parameter | |
+|---|---|
+| `fhirVersion` | Required. `R4`, `R4B`, `R5` ... or `4.0.1`, `4.0` |
+| `url` | The code system, `url` or `url\|version`. One of `url` and `valueSet` is required |
+| `version` | A version for `url`, instead of `url\|version` (an extension to the IG; ignored if `url` has one) |
+| `valueSet` | The value set, `url` or `url\|version` |
+| `authoritativeOnly` | Only authoritative endpoints, no candidates |
+| `language` | The language the client needs (BCP-47) |
+| `usage` | What the client is doing - `publication`, `validation`, `code-generation` - for servers that restrict their use |
+
+```json
+{
+  "formatVersion": "1",
+  "registry-url": "https://fhir.github.io/ig-registry/tx-servers.json",
+  "authoritative": [
+    { "server-name": "tx.fhir.org", "url": "http://tx.fhir.org/r4", "fhirVersion": "4.0.1",
+      "security": "open", "open": true }
+  ],
+  "candidates": [
+    { "server-name": "HL7 Europe Terminology Server", "url": "http://tx.hl7europe.eu/r4",
+      "fhirVersion": "4.0.1", "content": "complete", "security": "open", "open": true }
+  ]
+}
+```
+
+`access_info`, when present, is the server's own (markdown) note on how to get access.
+`content` on a candidate is the content mode the server reports for the code system
+(`complete`, `fragment` ...), if it reports one. `authoritative` and `candidates` are omitted
+when empty, so an empty object means nobody hosts it.
+
+### How resolution decides
+
+* An endpoint is only ever returned for content it actually hosts, as learned by scanning:
+  code systems from its TerminologyCapabilities, value sets from its ValueSet search. A claim
+  without the content gets nothing.
+* Code system versions: a SNOMED CT edition (`http://snomed.info/sct|http://snomed.info/sct/{edition}`)
+  is hosted by any endpoint that hosts a version of that edition; a dated SNOMED CT version
+  must match exactly. For every other code system, an endpoint that hosts the code system is
+  taken to host all its versions - servers rarely declare versions fully, and the server will
+  say if it hasn't got one.
+* Endpoints whose server claims authority for the URL (a mask in `authoritative`, or
+  `authoritative-valuesets`) are listed as `authoritative`; the others that host it as
+  `candidates`. An endpoint is never in both.
+* `language`: servers with a language specific claim (`languages` in the registration)
+  matching the request come first among the authoritative, the most specific tag first
+  (`de-CH` before `de`); a server with a claim for the code system but not the language is
+  still authoritative, after them; candidates are marked `language-support: unknown`. Value
+  set resolution has no language dimension.
+* `usage`: a server whose registration has a `usage` list is only returned when the request's
+  `usage` is in it. A request without `usage` gets only servers without the restriction.
+* `exclusions`: content a server's registration excludes is hidden from that server
+  entirely - it is neither authoritative nor a candidate for it.
+* The `url` of a FHIR-defined code system or value set may be given with or without the
+  `|version`; the FHIR version itself is taken from `fhirVersion`.
+
+### Differences from the ecosystem IG
+
+* Discovery without `url` returns claim masks, not candidate lists (above).
+* Entries carry the IG's security flags (`open`, `token`, `oauth` ...) and also a `security`
+  string (`open` or `api-key`), kept for existing clients. Both record how the *registry*
+  reaches the server: an endpoint is `api-key`/`token` when the registry is configured with a
+  key for it, and `open` otherwise. They say nothing about how the client will be let in.
+* Resolve takes `version` as an alternative to `url|version`.
+* Resolve omits `authoritative` and `candidates` when they are empty.
+
+## Operational pages
+
+These are HTML, not part of the API, and never secured:
+
+| URL | |
+|---|---|
+| `/tx-reg/software` | What each server runs, how old it is, and its uptime ([internals.md](internals.md#the-software-page)) |
+| `/tx-reg/log` | The scanner's log |
+| `/tx-reg/login`, `/tx-reg/account`, `/tx-reg/admin/users` | Login and user administration, when users are configured ([security.md](security.md)) |
+
+## Keeping the description honest
+
+[openapi.yaml](../openapi.yaml) is written by hand. `tests/registry/openapi.test.js` fails if
+the router has a route the description doesn't (unless the test's `EXCLUDED` table names it as
+operational), if the description has a route the router hasn't, or if the documented query
+parameters differ from `DISCOVERY_PARAMS` and `RESOLVE_PARAMS` in `registry.js`. Change the
+description with the code.

package/registry/documentation/configuration.md

@@ -0,0 +1,93 @@
+# Registry configuration
+
+The registry is configured under `modules.registry` in the server's configuration file (see
+[config-template.json](../../config-template.json) for the whole file). The minimum is
+`"enabled": true`; everything else has a default.
+
+```json
+"registry": {
+  "enabled": true,
+  "masterUrl": "https://fhir.github.io/ig-registry/tx-servers.json",
+  "crawlInterval": 30,
+  "timeout": 30000,
+  "userAgent": "YourServer/1.0",
+  "apiKeys": {},
+  "maxResponseMB": 100,
+  "uptimeWindowDays": 30,
+  "uptimeRetentionDays": 90,
+  "security": { }
+}
+```
+
+## The ecosystem
+
+| Setting | Default | |
+|---|---|---|
+| `masterUrl` | HL7's `tx-servers.json` | The ecosystem's master registration file ([readme.md](readme.md#the-specifications)). Point this at your own file to run a registry for your own ecosystem. |
+| `apiKeys` | `{}` | API keys for servers the registry needs one to scan, by server code (as in the server's registration). Sent as an `Api-Key` header. An endpoint scanned with a key is reported as `security: api-key` in the API. |
+
+## Scanning
+
+| Setting | Default | |
+|---|---|---|
+| `crawlInterval` | none | Minutes between scans. 0 or absent: the registry never scans, and answers from the data it last saved - useful for a read-only replica or a test. |
+| `timeout` | 30000 | Per-request timeout when scanning, in milliseconds. |
+| `userAgent` | `FHIRRegistryServer/1.0` | The `User-Agent` the scanner sends. Server operators see this in their logs, so name your registry. |
+| `maxResponseMB` | 100 | The most a scanned server's response may be once decompressed. The servers are other people's; a misbehaving one must not exhaust the registry's memory. |
+| `allowPrivateAddresses` | false | The scanner refuses to fetch from private, loopback and link-local addresses (SSRF protection - the URLs it follows come from registration files and servers it does not control). Set true only for a test registry whose servers are on localhost. |
+| `releasesUrl` | GitHub's FHIRsmith releases API | Where the software page learns FHIRsmith's release dates. `""` turns the lookup off (the dates in the shipped `CHANGELOG.md` are used instead). |
+
+## Uptime
+
+| Setting | Default | |
+|---|---|---|
+| `uptimeWindowDays` | 30 | The period the software page reports each server's uptime over. |
+| `uptimeRetentionDays` | 90 | How long per-endpoint scan outcomes are kept. |
+
+## Security
+
+`security` closes the JSON API. Absent, the registry is open. The block and its three methods
+are described in [security.md](security.md); in brief:
+
+```json
+"security": {
+  "apiToken": "one token every client sends",
+  "failedAuthPerWindow": 60,
+  "users": {
+    "database": "registry-auth.db",
+    "adminUsername": "admin",
+    "adminPassword": "...",
+    "sessionSecret": "...",
+    "cookieSecure": true,
+    "loginAttemptsPerWindow": 20
+  },
+  "oidc": {
+    "issuer": "https://login.microsoftonline.com/{tenant}/v2.0",
+    "audience": "api://ecosystem.hl7.org",
+    "requiredScope": "registry.read",
+    "jwksUri": "https://.../keys",
+    "algorithms": ["RS256", "ES256"]
+  }
+}
+```
+
+## Files
+
+The registry keeps its state in the server's data folder (`FHIRSMITH_DATA_DIR`, else `./data`):
+
+| File | |
+|---|---|
+| `registry/registry-data.json` | The result of the last scan - what every endpoint hosts. Loaded at startup, so the registry answers immediately after a restart. |
+| `registry/registry-uptime.json` | Per-endpoint scan outcomes, for the uptime figures. |
+| `databases/registry-auth.db` | Users and tokens, when `security.users` is configured (`database` names it; an absolute path or `:memory:` also works). |
+
+## Behind a proxy
+
+The registry is normally behind nginx (or similar) terminating TLS. Two things matter:
+
+* the proxy must pass `X-Forwarded-Proto`, and the server must trust it (`trustProxy` in the
+  server configuration), or the login cookie - `Secure` by default - is never set and logins
+  bounce straight back to the login page (`cookieSecure: false` is the escape for a registry
+  that really is served over plain HTTP);
+* the proxy must pass `Host` (or `X-Forwarded-Host`), or every form post is refused by the
+  same-origin check.

package/registry/documentation/documents.md

@@ -0,0 +1,74 @@
+# Documents
+
+A registry run for an ecosystem is a natural place to publish the ecosystem's own
+documentation: its policies, the configuration its clients should use, the terms under which
+servers are listed. The registry stores and serves such documents itself, so an administrator
+can keep them next to the registry without a separate website.
+
+Documents are available when `security.users` is configured ([security.md](security.md)):
+they live in the same database as the users, and who may read and edit them is decided by the
+same logins.
+
+## What a document is
+
+| | |
+|---|---|
+| **name** | Its address: `/tx-reg/docs/{name}`. Letters, digits, dots, hyphens and underscores, up to 100 characters, unique. Can be changed (the old address stops working). |
+| **type** | `md` (Markdown) or `json`. |
+| **public** | Whether anyone can read it. If not, only logged in users can. |
+| **last edited** | When, and by whom. |
+| **content** | The text, up to 2 MB. JSON must parse to be saved. |
+
+## Who sees what
+
+* A **public** document is readable by anyone: on the page, and as the raw file.
+* A document that is **not public** is readable by anyone who is logged in - any user, not
+  just administrators. This is for enterprise configuration and policy that should not be on
+  the open web. A logged in session is required: an API token, the configured API token or an
+  OIDC JWT does *not* give access to documents (they authenticate software to the API; the
+  documents are for people). To a stranger such a document does not exist: a browser is sent
+  to the login page, anything else gets 404, so names are not disclosed.
+* **Administrators** - the configured one, and any user with the administrator flag - create,
+  edit, rename and delete documents. An administrator user can also manage users.
+
+## Reading
+
+`GET /tx-reg/docs` lists the documents the reader may see. `GET /tx-reg/docs/{name}` returns
+the document: in a browser (`Accept: text/html`), rendered in the registry's pages - Markdown
+as HTML, JSON pretty-printed - with its metadata and links to its history and, for an
+administrator, to edit it; otherwise the raw content, as `text/markdown` or
+`application/json`, with `Last-Modified`, so a client such as `curl` or a script gets the
+file itself:
+
+```
+curl https://ecosystem.example.org/tx-reg/docs/client-configuration
+```
+
+Markdown is rendered without raw HTML: inline and block HTML in a document is left out (an
+HTML comment marks where), and links to `javascript:` and the like are not made. So a
+document can't put markup or script on a page that shares its origin with other modules.
+JSON documents are shown escaped.
+
+## Editing
+
+Editing is a text area with the four metadata fields above it - `/tx-reg/docs/new` to create,
+`/tx-reg/docs/{name}/edit` to change, and a delete button on the edit page. There is no rich
+editor: a document that needs one is written elsewhere and pasted in. Line endings are
+normalised to `\n`.
+
+## History
+
+Every change - creation, edit, rename, deletion - is logged with who made it, when, and the
+complete document as it then was. `/tx-reg/docs/{name}/history` lists the log, and each entry
+opens that version, rendered. Each version keeps the visibility it had then: a version from
+when the document was private is only for logged in users, even after the document has been
+made public. Deleting a
+document keeps its log, but the log is reached by the document's id, so it is no longer
+browsable once the document is gone; it remains in the database (`document_log`) for the
+administrator who needs it. A deleted name may be reused; the new document starts a new log.
+
+## Storage
+
+Two tables in the users' database (`databases/registry-auth.db`): `documents` (the current
+state) and `document_log` (every version). Nothing is cached; a document is read on each
+request.

package/registry/documentation/internals.md

@@ -0,0 +1,151 @@
+# Registry internals
+
+How the module works, for anyone changing it. The user-facing behaviour is in
+[api.md](api.md) and [security.md](security.md).
+
+## Code
+
+| File | |
+|---|---|
+| `registry.js` | `RegistryModule`: initialisation, routes, the HTML pages, scan scheduling, saving and loading state |
+| `api.js` | `RegistryAPI`: discovery and resolution over the scanned data, and the JSON-to-HTML rendering of their results |
+| `crawler.js` | `RegistryCrawler`: scanning the ecosystem |
+| `model.js` | The data model (`ServerRegistries` → `ServerRegistry` → `ServerInformation` → `ServerVersionInformation`), its JSON form, and `ServerRegistryUtilities` - mask matching and version matching |
+| `uptime.js` | `UptimeHistory`: per-endpoint scan outcomes, and the uptime calculation |
+| `fhirsmith-releases.js` | FHIRsmith's release list (GitHub, falling back to `CHANGELOG.md`), for dating servers on the software page |
+| `auth.js`, `auth-store.js` | `RegistryAuth` (API guard, OIDC verification, login/admin/account pages) and `AuthStore` (users, tokens, usage and documents in SQLite) |
+| `documents.js` | `RegistryDocuments`: the document pages, raw serving, editing and history ([documents.md](documents.md)) |
+| `openapi.yaml`, `openapi.js` | The API description, and the module that serves it |
+| `registry-template.html` | The page template (`[%title%]`, `[%content%]`, `[%account%]` for the login link, and the footer placeholders html-server fills) |
+
+`test-runner.js` is a leftover and does not run.
+
+`server.js` creates the module when `modules.registry.enabled` is set, calls
+`initialize(config)` and mounts `router` at `/tx-reg`. Nothing else in FHIRsmith depends on it.
+
+## Scanning
+
+`RegistryCrawler.crawl()` runs every `crawlInterval` minutes (first 5 seconds after start),
+and never concurrently with itself. A scan builds a fresh `ServerRegistries` from scratch:
+
+1. fetch the master registration file (`formatVersion` must be `"1"`);
+2. for each registry it lists, fetch the registry file and build a `ServerRegistry`;
+3. for each server, a `ServerInformation` with its claims (`authoritative`,
+   `authoritative-valuesets`, `languages`, `usage`, `exclusions`), and for each of its
+   `fhirVersions` a `ServerVersionInformation` - the *endpoint*;
+4. for each endpoint, by the major FHIR version in its registration: `/metadata` (software name,
+   version and release date), `/metadata?mode=terminology` (code systems and versions, sorted
+   and de-duplicated), `/ValueSet?_elements=url,version` (value set URLs, following `next`
+   links). R3 is handled separately from R4/R5 because it has no TerminologyCapabilities
+   resource: its `?mode=terminology` answer is a Parameters-shaped structure.
+
+If the whole scan fails (the master file can't be read) the previous data is kept and the
+outcome recorded. If an endpoint fails, the error is recorded on it, `lastSuccess` is left
+from the previous scan, and the software fields are carried forward from the previous data
+(`carryForwardSoftware`), so the software page does not lose track of a server that is down.
+The endpoint's code systems and value sets are *not* carried forward: a down server resolves
+nothing until it is back - but see `ServerVersionInformation.update()`, which is how a
+loaded-from-disk record is merged if that path is ever used.
+
+Every fetch goes through `fetchJson`, which adds a cache-busting `_ts`, sends the configured
+`User-Agent` and the server's `Api-Key` if there is one, limits the decompressed response to
+`maxResponseMB`, and resolves host names through `ssrfLookup`: an address that is not a public
+unicast address (loopback, private, link-local including the cloud metadata address, CGNAT,
+multicast ...) is refused, before and after DNS, so a hostile registration file cannot make the
+registry probe its own network. `allowPrivateAddresses` turns that off for local testing.
+
+Each endpoint probe also records its outcome in `UptimeHistory` with the scan's start time, and
+after a successful scan the history is trimmed to the endpoints that still exist.
+
+## State
+
+Two JSON files in the data folder's `registry` directory, written after every scan and read
+at startup:
+
+* `registry-data.json` - `ServerRegistries.toJSON()`: the ecosystem as last scanned, with
+  `"version": "1"`. Loading it is what lets a restarted registry answer at once.
+* `registry-uptime.json` - `UptimeHistory.toJSON()`: `{ version: "1", endpoints: { url:
+  [[timeMs, 1|0], ...] } }`, kept to `uptimeRetentionDays`.
+
+Users, tokens, usage and documents live in `databases/registry-auth.db` (better-sqlite3, WAL;
+the `admin` column on `users` is added on open if an older database lacks it). Request
+counts are accumulated in memory and flushed once a minute and at shutdown, so a busy registry
+is not writing SQLite on every API call.
+
+A scan builds a new tree and swaps it in whole (`RegistryModule.updateData()` is where a
+lock would go if one were ever needed; in Node's single thread the swap is atomic), so a
+request sees either the old ecosystem or the new, never a mixture.
+
+## Resolution
+
+`RegistryAPI.resolveCodeSystem()` and `resolveValueSet()` walk every endpoint of every server
+in every registry and keep those that (a) match the FHIR version
+(`ServerRegistryUtilities.versionMatches`, which accepts release codes and numbers), (b) are
+not excluded for the URL, (c) pass the `usage` test, and (d) actually host the URL
+(`hasMatchingCodeSystem`, with the SNOMED CT edition rule, or a value set lookup). Those whose
+server matches an authority claim (`ServerInformation.matchAuthCS`, which scores language
+specific claims so the most specific tag sorts first) go in `authoritative`; the rest in
+`candidates`, unless `authoritativeOnly`. Masks are matched by `ServerRegistryUtilities`, with
+`*` as the wildcard; actual content is matched without wildcards.
+
+`discover()` is the same walk without the hosting test (or with it, when `url` is given),
+producing one row per endpoint.
+
+## The pages
+
+All pages go through `RegistryModule.renderPage()`, which applies the template via
+`library/html-server` and fills `[%account%]` with the login, account or users link from
+`RegistryAuth.navLinks()`. Content that came from registration files or scanned servers -
+names, URLs, errors, software names - is other people's input, and is escaped on output; URLs
+are only linked when they are http(s) (`safeHref`). `tests/registry/registry-hostile-content.test.js`
+feeds script-laden registration data through every page to keep it that way.
+
+### The software page
+
+`buildSoftwareContent()` groups each server's endpoints by software name and version
+(`softwareRows`), so a server's R3/R4/R5 endpoints are one row under their common base URL
+(`commonBaseUrl`: the shared prefix of the endpoint URLs, backed up to a path boundary) unless
+they run different software. For FHIRsmith servers, `FhirsmithReleases.describe()` dates the
+version against the release list and says how many releases behind it is; other software is
+dated by the `software.releaseDate` it reports, as the UTC day (servers running the same
+release report it in different time zones). Uptime per row is `UptimeHistory.uptime()` over
+all the row's endpoints: the share of probes in the window that succeeded.
+
+### Login and administration
+
+`RegistryAuth` adds its routes only when `security.users` is configured. Sessions
+(`express-session`, cookie `txreg.sid`), CSRF (`lusca`) and the same-origin check
+(`library/same-origin`) are written out on every route rather than composed, so that static
+analysis can see the CSRF middleware on each cookie-using route - the convention the other
+modules follow. The API guard (`apiGuard()`) is a separate middleware on `/` and `/resolve`,
+applied only when the request does not accept HTML.
+
+## Security notes for maintainers
+
+* The registry fetches URLs it does not control. Keep every outbound request on `fetchJson`
+  (SSRF guard, size limit, timeout). The OIDC fetches (`fetch` for discovery, `jose` for keys)
+  go only to administrator-configured https URLs.
+* Everything rendered from scanned data or the database is escaped; `safeHref` for links.
+* API tokens are compared with `library/request-token` (constant time); user tokens by
+  SHA-256 lookup; passwords with bcrypt, and a login for an unknown user still runs a bcrypt
+  comparison so the timing does not reveal which users exist.
+* A user's own token operations are scoped by the user id from the session
+  (`revokeToken(userId, tokenId)`), never by the token id alone.
+
+## Tests
+
+`tests/registry`, run with `npx jest tests/registry`:
+
+| File | |
+|---|---|
+| `registry.test.js`, `registry-resolve.test.js` | Discovery and resolution against `test-data.json` |
+| `registry-language.test.js`, `registry-exclusions.test.js` | Language specific claims; exclusions |
+| `registry-software.test.js` | Release dating, the collapsed software rows, uptime history |
+| `registry-auth.test.js` | The three security methods end to end (supertest), including an OIDC provider stood up in the test with a generated key pair |
+| `registry-documents.test.js` | Documents: visibility, editing, history, validation; administrator users |
+| `registry-hostile-content.test.js` | Script injection through registration data, on every page |
+| `registry-footer.test.js` | The "last updated" footer |
+| `openapi.test.js` | The OpenAPI description agrees with the router and the parameter lists |
+
+`test-data.json` is a saved `registry-data.json` for a small fictional ecosystem; tests load it
+into a crawler with `loadData()` rather than scanning anything.