fhirsmith 0.16.1 → 0.18.0

package/registry/documentation/readme.md

@@ -0,0 +1,100 @@
+# Terminology Server Registry
+
+The registry (`/tx-reg`) is the *coordination server* of a terminology server ecosystem: a
+set of FHIR terminology servers, run by different organisations, that together serve the
+code systems and value sets an implementer community needs. Each server hosts some of the
+content and may be *authoritative* for some of it; the registry knows who hosts what, and
+tells clients which server to ask for a given code system or value set. HL7's ecosystem
+registry runs at https://tx.fhir.org/tx-reg (moving to https://ecosystem.hl7.org).
+
+| Page | |
+|---|---|
+| this page | What the registry does, and the specifications it implements |
+| [configuration.md](configuration.md) | `modules.registry` settings |
+| [api.md](api.md) | The API: discovery, resolution, and how resolution decides |
+| [security.md](security.md) | Closing the API: API token, users and tokens, OpenID Connect |
+| [documents.md](documents.md) | Documents the registry stores and serves: ecosystem policy and configuration |
+| [internals.md](internals.md) | Scanning, storage, the pages, the code and the tests |
+
+## The specifications
+
+**The terminology ecosystem IG.** The ecosystem, its registration files and the coordination
+server's API are specified by HL7's
+[FHIR Terminology Ecosystem IG](https://build.fhir.org/ig/HL7/fhir-tx-ecosystem-ig/), on its
+[ecosystem page](https://build.fhir.org/ig/HL7/fhir-tx-ecosystem-ig/ecosystem.html). That page
+is normative for what the registry answers; where this implementation extends or departs from
+it, [api.md](api.md) says so.
+
+**The registration files.** The ecosystem is declared by a *master registration file* that
+lists *registries*, each of which lists *servers*, each of which lists its endpoints (one per
+FHIR version) and its claims. The format is documented in the ig-registry repository's
+[tx-registry-doco.md](https://github.com/FHIR/ig-registry/blob/master/tx-registry-doco.md).
+HL7's master file is https://fhir.github.io/ig-registry/tx-servers.json, and its registries
+are the per-affiliate `*-tx-servers.json` files in the same repository (HL7 International,
+HL7 Australia, HL7 Europe, and so on). A server's registration carries:
+
+* `authoritative` and `authoritative-valuesets`: URL masks (with `*` wildcards) of the code
+  systems and value sets the server is the authority for;
+* `languages`: language specific authority claims, BCP-47 tag to code system masks;
+* `usage`: if present, the only purposes the server may be used for (the HL7 Java tools say
+  `publication`, `validation` or `code-generation`);
+* `exclusions`: code system and value set masks the server hosts but withholds from the
+  ecosystem;
+* `fhirVersions`: the endpoints, each a FHIR version and a URL.
+
+**What the registry reads from the servers.** Claims are what a server says about itself; what
+it actually hosts, the registry learns by scanning each endpoint with standard FHIR:
+
+* [`GET [base]/metadata`](https://hl7.org/fhir/http.html#capabilities), the
+  [CapabilityStatement](https://hl7.org/fhir/capabilitystatement.html), for
+  `software.name`, `software.version` and `software.releaseDate` (the software page);
+* `GET [base]/metadata?mode=terminology`, the
+  [TerminologyCapabilities](https://hl7.org/fhir/terminologycapabilities.html), for the code
+  systems and versions the endpoint hosts (`codeSystem[].uri`, `codeSystem[].version[].code`);
+* `GET [base]/ValueSet?_elements=url,version`, a [search](https://hl7.org/fhir/search.html)
+  for the value sets it hosts.
+
+Content a server hosts is what makes it a *candidate* for that content; a claim makes it
+*authoritative*. A server is never returned for content it does not host, whatever it claims.
+
+**FHIR versions.** Endpoints are scanned as R3, R4 (including R4B) or R5 by the major version
+in their registration, and requests may name a version as a release code (`R4`, `R5`) or a
+number (`4.0.1`, `4.0`).
+
+**SNOMED CT.** SNOMED CT versions are edition URIs,
+`http://snomed.info/sct/{edition}/version/{date}`
+([SNOMED CT URI standard](https://confluence.ihtsdotools.org/display/DOCURI)). The registry
+treats a request for an edition (`http://snomed.info/sct|http://snomed.info/sct/32506021000036107`)
+as satisfied by any endpoint hosting any version of that edition; a request for a dated
+version must match exactly.
+
+**The API description.** The API is described by an [OpenAPI 3.1](https://spec.openapis.org/oas/v3.1.0)
+document at `/tx-reg/openapi.json` (and `.yaml`), with a browsable reference at
+`/tx-reg/openapi`. Every response advertises it with a
+`Link: </tx-reg/openapi.json>; rel="service-desc"` header
+([RFC 8631](https://www.rfc-editor.org/rfc/rfc8631)).
+
+**Security.** When the API is closed, clients present a token as an HTTP bearer token
+([RFC 6750](https://www.rfc-editor.org/rfc/rfc6750)) or an `Api-Key` header. Enterprise
+clients can present a JWT ([RFC 7519](https://www.rfc-editor.org/rfc/rfc7519)) from an
+[OpenID Connect](https://openid.net/specs/openid-connect-core-1_0.html) provider, which the
+registry verifies against the provider's keys
+([OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html),
+[JWK, RFC 7517](https://www.rfc-editor.org/rfc/rfc7517)), typically obtained with the OAuth 2.0
+client credentials grant ([RFC 6749 §4.4](https://www.rfc-editor.org/rfc/rfc6749#section-4.4)).
+See [security.md](security.md).
+
+## Who uses it
+
+The main client is the HL7 Java tooling: `TerminologyClientManager` in `org.hl7.fhir.r5`
+(used by the validator, the IG publisher and everything built on them) calls `/resolve` for
+each code system or value set it meets, remembers the answer per code system and language, and
+routes each terminology operation to the server the registry named. Other clients - the
+registry's own pages, scripts, other servers - use the same two endpoints.
+
+## Running one
+
+A registry is a FHIRsmith server with the `registry` module enabled; nothing else is needed
+([configuration.md](configuration.md)). Pointing `masterUrl` at your own master registration
+file makes a registry for your own ecosystem - a national or enterprise set of servers - with
+the same API, and [security.md](security.md) closes it to your own clients.

package/registry/documentation/security.md

@@ -0,0 +1,199 @@
+# Securing the registry
+
+By default the registry is open, as HL7's ecosystem registry is: anyone can call the API. A
+registry run for a narrower community - an enterprise, a national programme, a vendor's
+customers - can be closed with `modules.registry.security`, in any combination of three ways:
+
+| Method | Who it suits |
+|---|---|
+| `apiToken` | A handful of clients you configure yourself: one token, every client sends it |
+| `users` | Clients you want to tell apart - issue, expire and revoke tokens one by one, see who is calling |
+| `oidc` | An enterprise with an identity provider: it decides who may call, and issues the tokens |
+
+The methods combine: a registry can accept its enterprise's JWTs *and* have a few locally
+managed users for clients that can't do OAuth. The users are mostly software - a validator
+in a build pipeline, a server resolving terminology - not people, and the design follows
+from that.
+
+## What is closed
+
+Only the JSON API: `GET /tx-reg/` and `GET /tx-reg/resolve` when they answer JSON. The HTML
+pages (home, resolve form, software, log), the OpenAPI description and the login page stay
+open, so a client - or the person configuring one - can always find out how to authenticate.
+A request without a valid token gets:
+
+```http
+HTTP/1.1 401 Unauthorized
+WWW-Authenticate: Bearer realm="tx-reg"
+Content-Type: application/json
+
+{ "error": "unauthorized",
+  "message": "This registry requires a token: send it as Authorization: Bearer {token} or Api-Key: {token}",
+  "documentation": "/tx-reg/openapi" }
+```
+
+(The message says `The token is not valid for this registry` when one was sent.) An open
+registry ignores any token sent to it.
+
+Failed authentications are limited per address. After `failedAuthPerWindow` requests
+answered 401 in 15 minutes (default 60), the address's requests with a token that isn't
+valid get `429 Too Many Requests` for the rest of the window. The token is checked first, so a
+request with a valid token always goes through, even from an address over the limit. One
+client behind a NAT retrying a bad token doesn't lock out the others. Only 401s count. This
+stops anyone guessing tokens. JWTs without an `exp` claim are refused. General request volume is still the proxy's
+business (nginx). `0` turns the limit off. It applies to the JSON API only; the pages
+aren't guarded, so they aren't limited.
+
+## How a client sends a token
+
+As an HTTP bearer token, or in an `Api-Key` header (`X-API-Key` is accepted too):
+
+```http
+GET /tx-reg/resolve?fhirVersion=R4&url=http://loinc.org
+Authorization: Bearer txr_k3Jd9...
+
+GET /tx-reg/resolve?fhirVersion=R4&url=http://loinc.org
+Api-Key: txr_k3Jd9...
+```
+
+The HL7 Java tooling (validator, IG publisher, and everything that uses
+`TerminologyClientManager`) sends either for a server listed in its `fhir-settings.json`, so a
+secured registry needs no change to the tools, only a settings entry:
+
+```json
+{ "servers": [
+  { "url": "https://ecosystem.example.org/tx-reg",
+    "authenticationType": "token", "token": "txr_k3Jd9..." }
+] }
+```
+
+(`"authenticationType": "apikey", "apikey": "..."` sends the `Api-Key` header instead.) Note
+that the tooling can *send* a token but not *obtain* one, so a Java client of an OIDC-secured
+registry needs a long-lived token - from a local user, or an OIDC client credential arranged
+outside the tool.
+
+## Method 1: a single API token
+
+```json
+"security": { "apiToken": "a long random string" }
+```
+
+Every client sends the same token. Compared in constant time; nothing is stored. Rotating it
+means changing the configuration and every client at once, which is why this suits only a few
+clients you control.
+
+## Method 2: users with their own tokens
+
+```json
+"security": {
+  "users": {
+    "database": "registry-auth.db",
+    "adminUsername": "admin",
+    "adminPassword": "...",
+    "sessionSecret": "a long random string",
+    "cookieSecure": true,
+    "loginAttemptsPerWindow": 20
+  }
+}
+```
+
+Users are kept in a SQLite database (`database`: a file in the data folder's `databases`
+directory, an absolute path, or `:memory:`). The administrator's login comes from the
+configuration, as in the other FHIRsmith modules; without `adminPassword` nobody can create
+users. Sessions are kept in the same database, so with a configured `sessionSecret` logins
+survive a restart. Changing or removing a user's password ends that user's other sessions.
+Pages that a visitor only reads (documents and their history) start no session for them.
+`cookieSecure` (default true) marks
+the login cookie `Secure`, which needs HTTPS and a proxy that passes `X-Forwarded-Proto`
+([configuration.md](configuration.md#behind-a-proxy)). Logins are rate limited to
+`loginAttemptsPerWindow` per 15 minutes per address.
+
+**Administering users.** The administrator logs in at `/tx-reg/login` and manages users at
+`/tx-reg/admin/users`: create a user (a login, a name, optional notes and password, and
+whether it is an administrator), then on the user's page edit it, enable or disable it, set or
+remove its password, issue and revoke tokens, or delete it. A user flagged **administrator**
+can do all of this too, and edit [documents](documents.md); the configured administrator is
+the root that cannot be locked out. The users list shows each user's active tokens, request count and last
+use; an "other clients" table shows requests made with the API token and by OIDC clients.
+
+**Tokens.** A token is `txr_` followed by 256 random bits (base64url, 47 characters). It is
+shown once, on the page after it is issued, and only its SHA-256 hash is stored - a stolen
+database yields no tokens, and the hash (rather than bcrypt) is right because the token is
+already high-entropy and is checked on every API call. A token can carry a label and an
+expiry (in days); it stops working when it expires, when it is revoked, or when its user is
+disabled. Each token's requests are counted, in memory, and written to the database once a
+minute. The first 12 characters are kept in clear as the token's name on the pages.
+
+**Self service.** A user with a password can log in and manage its own tokens at
+`/tx-reg/account`: see them and their usage, issue new ones, revoke old ones, and change the
+password. To rotate a token without an outage: issue the new one, move the client to it,
+revoke the old one. A user without a password cannot log in at all; its tokens still work.
+The password is only for the pages - it is never accepted on the API.
+
+**Web security.** The pages use the same protections as the other FHIRsmith modules: a
+`SameSite=Lax`, `HttpOnly` session cookie; a CSRF token on every form; cross-site form posts
+refused by `Origin`; bcrypt for passwords, with the same comparison time whether or not the
+username exists; the session regenerated at login; every value from the database escaped on
+output. Logins, user changes and token issue/revocation are logged.
+
+## Method 3: OpenID Connect
+
+```json
+"security": {
+  "oidc": {
+    "issuer": "https://login.microsoftonline.com/{tenant}/v2.0",
+    "audience": "api://ecosystem.example.org",
+    "requiredScope": "registry.read",
+    "jwksUri": "https://login.microsoftonline.com/{tenant}/discovery/v2.0/keys",
+    "algorithms": ["RS256"]
+  }
+}
+```
+
+The enterprise's identity provider (Entra ID, Okta, Keycloak, Ping, Auth0 - anything that
+implements OpenID Connect) issues JWTs; the registry verifies them and lets the bearer in. The
+enterprise therefore decides who may use the registry, with its own onboarding and
+offboarding, and no secret is ever shared with the registry.
+
+A software client registers an application with the provider and obtains a token with the
+OAuth 2.0 client credentials grant, then sends it as `Authorization: Bearer`. (A person's
+token from the usual browser login flow works the same way, if it has the right audience.)
+
+**What is checked.** The signature, against the issuer's published keys; `iss` equal to
+`issuer`; `aud` containing `audience` (a string, or a list of acceptable values); `exp` and
+`nbf`, with 60 seconds' tolerance; and, if `requiredScope` is set, that value among the
+token's scopes - the space-separated `scp` or `scope` claim, or the `roles` list (Entra ID puts
+application permissions in `roles`). Any failure is a 401, and the reason is logged.
+
+**Keys.** With `jwksUri`, keys are fetched from there. Without it, the registry reads
+`{issuer}/.well-known/openid-configuration` on the first request and uses its `jwks_uri`;
+if that fails the request is refused and discovery is retried on the next. Keys are cached
+and refreshed when an unknown key id appears (at most every 30 seconds). Both URLs must be
+https. `algorithms` restricts the accepted signing algorithms; the default is the asymmetric
+set (RSA, RSA-PSS, ECDSA, EdDSA) - symmetric HMAC algorithms are never accepted, since a shared
+secret would defeat the point.
+
+**Identifying the client.** Requests are counted per client, by the token's `azp`,
+`client_id`, `appid` or `sub` claim, and shown in the "other clients" table on the users page
+when `users` is also configured. The registry keeps no record of OIDC clients beyond that.
+
+**Which check a token gets.** A token of three dot-separated parts is treated as a JWT and
+verified against the provider when `oidc` is configured; anything else is compared with
+`apiToken`, then looked up among the users' tokens. So the three methods never confuse one
+another's tokens.
+
+This needs the `jose` package (a dependency of FHIRsmith); a registry configured for OIDC
+without it refuses to start, with a message saying so.
+
+## What is not done, and could be
+
+* **Trusted proxy headers.** An enterprise that fronts the registry with its own gateway
+  (mTLS, SSO, API keys it already issues) could pass the caller's identity in a header the
+  registry trusts from that proxy only. Not implemented; the gateway can simply hold the
+  registry's API token today.
+* **Single sign-on for the pages.** The administrator and users log in with passwords. The
+  OIDC provider could authenticate people to the pages too.
+* **Token introspection, LDAP, SCIM.** Considered and set aside until a deployment needs one.
+  Introspection (RFC 7662) suits opaque enterprise tokens at the cost of a call per request;
+  LDAP is a human-login technology; SCIM would synchronise the enterprise's users into method
+  2 but still leave the tokens to be issued here.

package/registry/documents.js

@@ -0,0 +1,309 @@
+// registry/documents.js
+// Documents the registry stores and serves: enterprise configuration and policy, as
+// markdown or JSON. Each has a name, a type, whether it is public, and when (and by whom)
+// it was last edited; every change is logged with the content as it was.
+//
+//   public documents     anyone can read
+//   other documents      anyone logged in (a browser session - never an API token)
+//   editing, deleting    administrators (the configured one, or a user flagged admin)
+//
+// Markdown is rendered without raw HTML (commonmark's safe mode: inline and block HTML is
+// left out, and links to javascript: and the like are not made), so a document can't put
+// script on a page that shares its origin with other modules; JSON is shown escaped.
+// Editing is a textarea.
+//
+// Routes (added to the registry's router by RegistryAuth, since they need its session):
+//   GET  /docs                     the list
+//   GET  /docs/new, POST /docs     create
+//   GET  /docs/{name}              the document: rendered for a browser, raw otherwise
+//   GET  /docs/{name}/edit, POST   edit (name, type, public, content)
+//   POST /docs/{name}/delete
+//   GET  /docs/{name}/history      the log; /history/{entry} shows a past version
+
+const express = require('express');
+const escape = require('escape-html');
+const commonmark = require('commonmark');
+
+const NAME_RE = /^[a-z0-9][a-z0-9._-]{0,99}$/i;
+const RESERVED = new Set(['new']);
+const TYPES = { md: 'text/markdown; charset=utf-8', json: 'application/json; charset=utf-8' };
+const MAX_SIZE = 2 * 1024 * 1024;
+
+function str(v) {
+  return typeof v === 'string' ? v : '';
+}
+
+/** Render markdown to HTML: no raw HTML, and no links to javascript: and the like */
+function renderMarkdown(md) {
+  const parsed = new commonmark.Parser().parse(md);
+  return new commonmark.HtmlRenderer({ safe: true }).render(parsed);
+}
+
+/** The JSON pretty-printed, or null if it doesn't parse */
+function prettyJson(text) {
+  try {
+    return JSON.stringify(JSON.parse(text), null, 2);
+  } catch {
+    return null;
+  }
+}
+
+class RegistryDocuments {
+  /**
+   * @param {RegistryAuth} auth the session, csrf and store live there
+   * @param {object} logger
+   */
+  constructor(auth, logger) {
+    this.auth = auth;
+    this.store = auth.store;
+    this.log = logger || console;
+  }
+
+  setupRoutes(router) {
+    const a = this.auth;
+    const h = fn => (req, res) => Promise.resolve().then(() => fn(req, res)).catch(e => {
+      this.log.error(`Registry documents: ${e.message}`);
+      a.sendError(req, res, 500, e.message);
+    });
+    const admin = (req, res, next) => {
+      const user = a.currentUser(req);
+      if (!user) {
+        return res.redirect(req.baseUrl + '/login');
+      }
+      if (!user.isAdmin) {
+        return a.sendError(req, res, 403, 'Only an administrator can do that');
+      }
+      req.user = user;
+      next();
+    };
+    // the session is read on every page, so that a logged in user sees the private
+    // documents; CSRF only matters for the forms
+    router.get('/docs', a.session, a.csrfIfLoggedIn, h((req, res) => this.sendList(req, res)));
+    router.get('/docs/new', a.session, a.csrf, admin, h((req, res) => this.sendForm(req, res, null)));
+    // a document's form carries up to MAX_SIZE of content, URL-encoded (up to three times as
+    // long): the auth pages' 64kb form parser is too small for it. One a bit over is caught
+    // by save(), with the form's own message
+    const docForm = express.urlencoded({ extended: false, limit: 3 * MAX_SIZE + 64 * 1024 });
+    router.post('/docs', a.sameOrigin, a.session, docForm, a.csrf, admin, h((req, res) => this.save(req, res, null)));
+    router.get('/docs/:name', a.session, a.csrfIfLoggedIn, h((req, res) => this.sendDocument(req, res)));
+    router.get('/docs/:name/edit', a.session, a.csrf, admin, h((req, res) => this.sendForm(req, res, this.find(req))));
+    router.post('/docs/:name', a.sameOrigin, a.session, docForm, a.csrf, admin, h((req, res) => this.save(req, res, this.find(req))));
+    router.post('/docs/:name/delete', a.sameOrigin, a.session, a.form, a.csrf, admin, h((req, res) => this.delete(req, res)));
+    router.get('/docs/:name/history', a.session, a.csrfIfLoggedIn, h((req, res) => this.sendHistory(req, res)));
+    router.get('/docs/:name/history/:entry', a.session, a.csrfIfLoggedIn, h((req, res) => this.sendVersion(req, res)));
+  }
+
+  find(req) {
+    const name = str(req.params.name);
+    return NAME_RE.test(name) ? this.store.documentByName(name) : null;
+  }
+
+  /**
+   * May this request read the document - or a past version of it (a log entry, which has
+   * its own public flag)? Public: anyone; else a logged in user
+   */
+  canRead(req, doc) {
+    return !!doc.public || !!this.auth.currentUser(req);
+  }
+
+  wantsHtml(req) {
+    return !!(req.headers.accept && req.headers.accept.includes('text/html'));
+  }
+
+  // ---- reading ----
+
+  sendList(req, res) {
+    const base = escape(req.baseUrl || '');
+    const user = this.auth.currentUser(req);
+    const docs = this.store.documents().filter(d => d.public || user);
+    let h = '';
+    if (user && user.isAdmin) {
+      h += `<p style="float: right"><a class="btn btn-primary btn-sm" href="${base}/docs/new">New document</a></p>`;
+    }
+    h += '<p>Documents this registry publishes: configuration and policy for its ecosystem. ' +
+      (user ? '' : 'Documents that are not public are shown to logged in users.') + '</p>';
+    h += '<table class="grid"><thead><tr><th>Name</th><th>Type</th><th>Visibility</th><th>Last edited</th><th>By</th><th>Size</th></tr></thead><tbody>';
+    for (const d of docs) {
+      h += `<tr><td><a href="${base}/docs/${encodeURIComponent(d.name)}">${escape(d.name)}</a></td><td>${escape(d.type)}</td>` +
+        `<td>${d.public ? 'public' : 'logged in users'}</td><td>${escape(d.updated_at.substring(0, 16).replace('T', ' '))}</td>` +
+        `<td>${escape(d.updated_by)}</td><td>${d.size}</td></tr>`;
+    }
+    if (docs.length === 0) {
+      h += '<tr><td colspan="6"><i>no documents</i></td></tr>';
+    }
+    h += '</tbody></table>';
+    this.auth.renderPage(req, res, 'Documents', h, 200);
+  }
+
+  sendDocument(req, res) {
+    const doc = this.find(req);
+    if (!doc) {
+      return this.notFound(req, res);
+    }
+    if (!this.canRead(req, doc)) {
+      return this.denied(req, res);
+    }
+    if (!this.wantsHtml(req)) {
+      res.setHeader('Content-Type', TYPES[doc.type] || 'text/plain; charset=utf-8');
+      res.setHeader('Last-Modified', new Date(doc.updated_at).toUTCString());
+      res.setHeader('Cache-Control', doc.public ? 'public, max-age=60' : 'private, no-store');
+      return res.send(doc.content);
+    }
+    const base = escape(req.baseUrl || '');
+    const user = this.auth.currentUser(req);
+    let h = `<p class="text-muted"><small>${escape(doc.type === 'md' ? 'Markdown' : 'JSON')} &middot; ` +
+      `${doc.public ? 'public' : 'logged in users'} &middot; last edited ${escape(doc.updated_at.substring(0, 16).replace('T', ' '))} by ${escape(doc.updated_by)} &middot; ` +
+      `<a href="${base}/docs/${encodeURIComponent(doc.name)}/history">history</a>`;
+    if (user && user.isAdmin) {
+      h += ` &middot; <a href="${base}/docs/${encodeURIComponent(doc.name)}/edit">edit</a>`;
+    }
+    h += '</small></p>';
+    h += this.renderContent(doc);
+    this.auth.renderPage(req, res, doc.name, h, 200);
+  }
+
+  renderContent(doc) {
+    if (doc.type === 'json') {
+      const pretty = prettyJson(doc.content);
+      return `<pre class="json">${escape(pretty === null ? doc.content : pretty)}</pre>`;
+    }
+    return `<div class="document">${renderMarkdown(doc.content)}</div>`;
+  }
+
+  sendHistory(req, res) {
+    const doc = this.find(req);
+    if (!doc) {
+      return this.notFound(req, res);
+    }
+    if (!this.canRead(req, doc)) {
+      return this.denied(req, res);
+    }
+    const base = escape(req.baseUrl || '');
+    const url = `${base}/docs/${encodeURIComponent(doc.name)}`;
+    let h = `<p><a href="${url}">&laquo; ${escape(doc.name)}</a></p>`;
+    h += '<table class="grid"><thead><tr><th>When</th><th>Who</th><th>Action</th><th>Name</th><th>Type</th><th>Visibility</th><th>Size</th></tr></thead><tbody>';
+    // the versions this request may read: a version from when the document was private
+    // stays private, whatever the document is now
+    const versions = this.store.documentLog(doc.id).filter(e => this.canRead(req, e));
+    for (const e of versions) {
+      h += `<tr><td><a href="${url}/history/${e.id}">${escape(e.at.substring(0, 19).replace('T', ' '))}</a></td><td>${escape(e.by)}</td>` +
+        `<td>${escape(e.action)}</td><td>${escape(e.name)}</td><td>${escape(e.type)}</td><td>${e.public ? 'public' : 'logged in users'}</td><td>${e.size}</td></tr>`;
+    }
+    h += '</tbody></table>';
+    this.auth.renderPage(req, res, `History of ${doc.name}`, h, 200);
+  }
+
+  sendVersion(req, res) {
+    const doc = this.find(req);
+    if (!doc) {
+      return this.notFound(req, res);
+    }
+    if (!this.canRead(req, doc)) {
+      return this.denied(req, res);
+    }
+    const entry = this.store.documentLogEntry(doc.id, Number(req.params.entry));
+    if (!entry) {
+      return this.notFound(req, res);
+    }
+    if (!this.canRead(req, entry)) {
+      return this.denied(req, res);
+    }
+    const base = escape(req.baseUrl || '');
+    let h = `<p><a href="${base}/docs/${encodeURIComponent(doc.name)}/history">&laquo; history</a></p>`;
+    h += `<div class="alert alert-info">The document as ${escape(entry.action)} at ${escape(entry.at.substring(0, 19).replace('T', ' '))} by ${escape(entry.by)}` +
+      (entry.name !== doc.name ? `, then named <code>${escape(entry.name)}</code>` : '') + '.</div>';
+    h += this.renderContent(entry);
+    this.auth.renderPage(req, res, `${doc.name} at ${entry.at.substring(0, 16).replace('T', ' ')}`, h, 200);
+  }
+
+  notFound(req, res) {
+    if (this.wantsHtml(req)) {
+      return this.auth.sendError(req, res, 404, 'No such document');
+    }
+    res.status(404).json({ error: 'not-found', message: 'No such document' });
+  }
+
+  // a document that exists but is not public looks the same as one that doesn't, to a
+  // stranger: a browser is sent to log in, anything else gets 404
+  denied(req, res) {
+    if (this.wantsHtml(req)) {
+      return res.redirect(`${req.baseUrl || ''}/login`);
+    }
+    res.status(404).json({ error: 'not-found', message: 'No such document' });
+  }
+
+  // ---- editing ----
+
+  sendForm(req, res, doc, values, error) {
+    if (req.params.name && !doc) {
+      return this.notFound(req, res);
+    }
+    const base = escape(req.baseUrl || '');
+    const v = values || (doc ? { name: doc.name, type: doc.type, public: doc.public, content: doc.content } : { name: '', type: 'md', public: false, content: '' });
+    const action = doc ? `${base}/docs/${encodeURIComponent(doc.name)}` : `${base}/docs`;
+    let h = error ? `<div class="alert alert-danger">${escape(error)}</div>` : '';
+    h += `<form method="post" action="${action}"><input type="hidden" name="_csrf" value="${escape(res.locals._csrf || '')}"/>` +
+      '<div class="row g-3" style="max-width: 900px">' +
+      `<div class="col-md-5"><label class="form-label" for="d-name">Name</label><input class="form-control" id="d-name" name="name" value="${escape(v.name)}" required maxlength="100" pattern="[A-Za-z0-9][A-Za-z0-9._-]*"/>` +
+      '<div class="form-text">Letters, digits, dots, hyphens and underscores; it is the document\'s address</div></div>' +
+      '<div class="col-md-3"><label class="form-label" for="d-type">Type</label><select class="form-select" id="d-type" name="type">' +
+      `<option value="md"${v.type === 'md' ? ' selected' : ''}>Markdown</option><option value="json"${v.type === 'json' ? ' selected' : ''}>JSON</option></select></div>` +
+      `<div class="col-md-4"><label class="form-label">&nbsp;</label><div><label><input type="checkbox" name="public" value="1"${v.public ? ' checked' : ''}/> Public (anyone can read it)</label></div></div>` +
+      `<div class="col-12"><label class="form-label" for="d-content">Content</label><textarea class="form-control" id="d-content" name="content" rows="28" style="font-family: monospace" spellcheck="false">${escape(v.content)}</textarea></div>` +
+      `<div class="col-12"><button type="submit" class="btn btn-primary">${doc ? 'Save' : 'Create'}</button> ` +
+      `<a class="btn btn-secondary" href="${doc ? action : base + '/docs'}">Cancel</a></div></div></form>`;
+    if (doc) {
+      h += `<form method="post" action="${action}/delete" style="margin-top: 2em" onsubmit="return confirm('Delete this document?')">` +
+        `<input type="hidden" name="_csrf" value="${escape(res.locals._csrf || '')}"/><button type="submit" class="btn btn-outline-danger btn-sm">Delete document</button></form>`;
+    }
+    this.auth.renderPage(req, res, doc ? `Edit ${doc.name}` : 'New document', h, error ? 400 : 200);
+  }
+
+  save(req, res, doc) {
+    if (req.params.name && !doc) {
+      return this.notFound(req, res);
+    }
+    const values = {
+      name: str(req.body.name).trim(),
+      type: str(req.body.type) === 'json' ? 'json' : 'md',
+      public: req.body.public === '1',
+      content: str(req.body.content).replace(/\r\n/g, '\n')
+    };
+    let error = null;
+    if (!NAME_RE.test(values.name) || RESERVED.has(values.name.toLowerCase())) {
+      error = 'The name must be 1-100 letters, digits, dots, hyphens or underscores, starting with a letter or digit';
+    } else if (values.content.length > MAX_SIZE) {
+      error = `The document is too large (${values.content.length} characters; the limit is ${MAX_SIZE})`;
+    } else if (values.type === 'json' && prettyJson(values.content) === null) {
+      error = 'The content is not valid JSON';
+    } else {
+      const existing = this.store.documentByName(values.name);
+      if (existing && (!doc || existing.id !== doc.id)) {
+        error = `There is already a document named '${values.name}'`;
+      }
+    }
+    if (error) {
+      return this.sendForm(req, res, doc, values, error);
+    }
+    if (doc) {
+      this.store.updateDocument(doc.id, values, req.user.login);
+      this.log.info(`Registry documents: '${values.name}' edited by ${req.user.login}`);
+    } else {
+      this.store.createDocument(values, req.user.login);
+      this.log.info(`Registry documents: '${values.name}' created by ${req.user.login}`);
+    }
+    res.redirect(`${req.baseUrl || ''}/docs/${encodeURIComponent(values.name)}`);
+  }
+
+  delete(req, res) {
+    const doc = this.find(req);
+    if (!doc) {
+      return this.notFound(req, res);
+    }
+    this.store.deleteDocument(doc.id, req.user.login);
+    this.log.info(`Registry documents: '${doc.name}' deleted by ${req.user.login}`);
+    res.redirect(`${req.baseUrl || ''}/docs`);
+  }
+}
+
+module.exports = { RegistryDocuments, renderMarkdown, NAME_RE };

package/registry/openapi.yaml

@@ -34,6 +34,14 @@ info:
 
     **Parameters are read leniently**: unknown parameters are ignored, and a repeated
     parameter takes its first value.
+
+    **Authentication.** A registry may be configured to require a token on the JSON API
+    (`modules.registry.security`; the HTML pages and this description stay open). Send it
+    as `Authorization: Bearer {token}` or `Api-Key: {token}`. Depending on the registry's
+    configuration the token is one the administrator set, one issued to a user on the
+    registry's pages, or a JWT from the enterprise's OpenID Connect provider. Without a
+    valid token the API answers `401` with a `WWW-Authenticate: Bearer` header. An open
+    registry ignores any token sent.
   license:
     name: BSD-3-Clause
     url: https://opensource.org/license/bsd-3-clause
@@ -96,6 +104,7 @@ paths:
             text/html:
               schema: { type: string }
         '400': { $ref: '#/components/responses/BadRequest' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
         '500': { $ref: '#/components/responses/ServerError' }
 
   /resolve:
@@ -171,8 +180,20 @@ paths:
           content:
             application/json:
               schema: { $ref: '#/components/schemas/Error' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
 
 components:
+  securitySchemes:
+    bearer:
+      type: http
+      scheme: bearer
+      description: "The token - the registry's own, or an OIDC JWT - as `Authorization: Bearer {token}`"
+    apiKey:
+      type: apiKey
+      in: header
+      name: Api-Key
+      description: "The same token as `Api-Key: {token}` (what the HL7 Java tooling sends for an `apikey` server in fhir-settings.json)"
+
   parameters:
     fhirVersionOptional:
       name: fhirVersion
@@ -196,6 +217,15 @@ components:
       content:
         application/json:
           schema: { $ref: '#/components/schemas/Error' }
+    Unauthorized:
+      description: "The registry requires a token, and the request carried none or an invalid one. `WWW-Authenticate` names the scheme."
+      headers:
+        WWW-Authenticate:
+          schema: { type: string }
+          example: Bearer realm="tx-reg"
+      content:
+        application/json:
+          schema: { $ref: '#/components/schemas/Error' }
     ServerError:
       description: The server failed to process the request
       content: