fhirsmith 0.18.1 → 1.0.0

package/registry/api.js

@@ -27,6 +27,20 @@ function securityFlags(security) {
   }
 }
 
+// Code systems that tx.fhir.org handles specially. When the registry doesn't settle where
+// a request involving one of these goes, it goes to the primary server (see chooseServer)
+const SNOMED_CT = 'http://snomed.info/sct';
+const PRIMARY_SERVER_SYSTEMS = ['http://unitsofmeasure.org', 'http://loinc.org', SNOMED_CT,
+  'http://www.nlm.nih.gov/research/umls/rxnorm', 'http://hl7.org/fhir/sid/cvx', 'urn:ietf:bcp:13', 'urn:ietf:bcp:47',
+  'urn:ietf:rfc:3986', 'http://www.ama-assn.org/go/cpt', 'urn:oid:1.2.36.1.2001.1005.17', 'urn:iso:std:iso:3166',
+  'http://varnomen.hgvs.org', 'http://unstats.un.org/unsd/methods/m49/m49.htm', 'urn:iso:std:iso:4217',
+  'http://hl7.org/fhir/sid/ndc', 'http://fhir.ohdsi.org/CodeSystem/concepts', 'http://fdasis.nlm.nih.gov', 'https://www.usps.com/'];
+
+function isTxFhirOrg(server) {
+  const s = server.replace('http://', 'https://');
+  return s.startsWith('https://tx.fhir.org/') || s.startsWith('https://tx-dev.fhir.org/');
+}
+
 class RegistryAPI {
   constructor(crawler) {
     this.crawler = crawler;
@@ -592,6 +606,170 @@ class RegistryAPI {
     };
   }
 
+  /**
+   * Choose one server for a request that involves a set of code systems.
+   *
+   * This is a server side copy of the routing logic in the HL7 Java tooling
+   * (TerminologyClientManager.chooseServer in org.hl7.fhir.core), for clients that aren't
+   * Java. It doesn't replace that code. The Java client does the work that needs its own
+   * context before routing, and so must the caller here:
+   *
+   * - systems: the code systems involved, as url or url|version, from the codings and the
+   *   value set's includes and excludes, following imported value sets. Versions fixed by
+   *   expansion parameters (system-version, force-system-version) should already be applied.
+   *   If the caller couldn't follow an import, it should just use its default server.
+   * - language: only for language sensitive requests (see resolveCodeSystem).
+   *
+   * Differences from the Java code:
+   * - 'Does a candidate really have the code system' is answered from the content mode the
+   *   server reported in its TerminologyCapabilities, not by searching the server. If it
+   *   didn't report one, the candidate is assumed to be usable.
+   * - The 'primary server' for the systems tx.fhir.org handles specially is the default.
+   * - The value set's source server is found by resolving the value set here.
+   * - Ties are broken by order (the first system, then registration order), not hash order.
+   *
+   * @returns {{server: string, log: string[]}} the server to use, and why
+   */
+  chooseServer(fhirVersion, systems, defaultServer, valueSet = '', usage = '', language = '') {
+    if (!fhirVersion) {
+      throw new Error('A FHIR version is required');
+    }
+    if (!defaultServer) {
+      throw new Error('A default server is required');
+    }
+    const log = [];
+    const list = [...new Set((systems || []).filter(s => s))];
+    if (valueSet) {
+      log.push(`Value set: ${valueSet}`);
+    }
+    if (list.length === 0) {
+      log.push('No code systems: using the default server');
+      return { server: defaultServer, log };
+    }
+    const server = this._chooseServer(fhirVersion, list, defaultServer, valueSet, usage, language, log);
+    return { server, log };
+  }
+
+  _chooseServer(fhirVersion, systems, defaultServer, valueSet, usage, language, log) {
+    // what the registry says about each system on its own
+    const choices = systems.map(system => {
+      const r = this.resolveCodeSystem(fhirVersion, system, false, usage, language).result;
+      const choice = { system, authoritative: [], candidates: [], content: {} };
+      for (const e of r.authoritative || []) {
+        if (!choice.authoritative.includes(e.url)) choice.authoritative.push(e.url);
+      }
+      for (const e of r.candidates || []) {
+        if (!choice.candidates.includes(e.url)) {
+          choice.candidates.push(e.url);
+          choice.content[e.url] = e.content;
+        }
+      }
+      log.push(`${system}: authoritative [${choice.authoritative.join(', ')}], candidates [${choice.candidates.join(', ')}]`);
+      return choice;
+    });
+    // the registry knows no server at all for the system
+    const unresolved = c => c.authoritative.length === 0 && c.candidates.length === 0;
+
+    // 1. a server that's authoritative for all of them
+    for (const c of choices) {
+      for (const s of c.authoritative) {
+        if (choices.every(t => t.authoritative.includes(s))) {
+          log.push(`Found authoritative server ${s}`);
+          return s;
+        }
+      }
+    }
+
+    // 2. a server that's authoritative for one of them, and a candidate for the others. A
+    // system that no server is known for doesn't constrain the choice
+    for (const c of choices) {
+      for (const s of c.authoritative) {
+        if (choices.every(t => unresolved(t) || t.authoritative.includes(s) || t.candidates.includes(s))) {
+          log.push(`Found partially authoritative server ${s}`);
+          return s;
+        }
+      }
+    }
+
+    // 3. code systems with special handling on tx.fhir.org, that might not be resolved above.
+    // We don't want them going to secondary servers by accident
+    const bases = systems.map(s => s.includes('|') ? s.substring(0, s.indexOf('|')) : s);
+    if (systems.length > 1 && bases.includes(SNOMED_CT)) {
+      log.push(`Several code systems including SNOMED CT: choosing for SNOMED CT alone`);
+      return this._chooseServer(fhirVersion, [SNOMED_CT], defaultServer, valueSet, usage, language, log);
+    }
+    const special = bases.find(b => PRIMARY_SERVER_SYSTEMS.includes(b));
+    if (special) {
+      log.push(`Use primary server (the default) for ${special}`);
+      return defaultServer;
+    }
+
+    // 4. a server that's a candidate for all of them (again, systems no server is known for
+    // don't constrain the choice), and that has a usable copy of the code systems
+    for (const c of choices) {
+      for (const s of c.candidates) {
+        if (choices.every(t => unresolved(t) || t.candidates.includes(s)) &&
+          this._supportsAll(s, choices, unresolved, log)) {
+          log.push(`Found candidate server ${s}`);
+          return s;
+        }
+      }
+    }
+
+    // 5. no agreement - take the one that is most authoritative
+    const counts = new Map();
+    for (const c of choices) {
+      for (const s of c.authoritative) {
+        counts.set(s, (counts.get(s) || 0) + 1);
+      }
+    }
+    let max = null;
+    for (const [s, n] of counts) {
+      if (max === null || n > counts.get(max)) max = s;
+    }
+    if (max !== null) {
+      log.push(`Found most authoritative server ${max}`);
+      return max;
+    }
+
+    // 6. nothing. Use the server the value set comes from, if it comes from one, else the default
+    const why = systems.length === 1 ? 'Not handled by any servers' : 'Handled by multiple servers';
+    if (valueSet) {
+      const r = this.resolveValueSet(fhirVersion, valueSet, false, usage).result;
+      let source = (r.authoritative || []).concat(r.candidates || []).map(e => e.url)[0];
+      if (source === 'https://vsac.nlm.nih.gov') {
+        source = defaultServer;
+      }
+      if (source) {
+        log.push(`${why}. Using source @ '${source}'`);
+        return source;
+      }
+    }
+    log.push(`${why}. Using the default server`);
+    return defaultServer;
+  }
+
+  /**
+   * Whether a candidate server has a usable copy (complete or fragment) of each code system
+   * it's a candidate for. Systems for which tx.fhir.org is a candidate aren't checked
+   */
+  _supportsAll(server, choices, unresolved, log) {
+    if (isTxFhirOrg(server)) {
+      return true;
+    }
+    for (const t of choices) {
+      if (unresolved(t) || !t.candidates.includes(server) || t.candidates.some(isTxFhirOrg)) {
+        continue;
+      }
+      const content = t.content[server];
+      if (content && content !== 'complete' && content !== 'fragment') {
+        log.push(`Candidate server ${server} dropped for ${t.system}: its copy of the code system is '${content}'`);
+        return false;
+      }
+    }
+    return true;
+  }
+
   /**
    * The ecosystem Discovery API (GET {root} as JSON): one row per server endpoint.
    *
@@ -774,7 +952,7 @@ class RegistryAPI {
       }
       html += '</td>\n';
 
-      html += `<td>${row.security}/td>\n`;
+      html += `<td>${escape(row.security)}</td>\n`;
 
       html += '</tr>\n';
     }

package/registry/crawler.js

@@ -2,10 +2,6 @@
 // Crawler for gathering server information from terminology servers
 
 const axios = require('axios');
-const dns = require('dns');
-const http = require('http');
-const https = require('https');
-const ipaddr = require('ipaddr.js');
 const {
   ServerRegistries,
   ServerRegistry,
@@ -13,24 +9,11 @@ const {
   ServerVersionInformation,
 } = require('./model');
 const { UptimeHistory } = require('./uptime');
+const { ServerCredentials } = require('../library/server-credentials');
+const { createGuardedAgents } = require('../library/ssrf-guard');
 const {Extensions} = require("../tx/library/extensions");
 const {debugLog} = require("../tx/operation-context");
 
-// True if an IP literal is anything other than a normal public (unicast) address:
-// loopback, private, link-local (incl. 169.254.169.254 cloud metadata), unique-local,
-// CGNAT, multicast, reserved, etc. IPv4-mapped IPv6 addresses are unwrapped first.
-function isNonPublicAddress(ip) {
-  try {
-    let addr = ipaddr.parse(ip);
-    if (addr.kind() === 'ipv6' && addr.isIPv4MappedAddress()) {
-      addr = addr.toIPv4Address();
-    }
-    return addr.range() !== 'unicast';
-  } catch (e) {
-    return true; // unparseable - treat as unsafe
-  }
-}
-
 const MASTER_URL = 'https://fhir.github.io/ig-registry/tx-servers.json';
 
 class RegistryCrawler {
@@ -42,7 +25,10 @@ class RegistryCrawler {
       masterUrl: config.masterUrl || MASTER_URL,
       userAgent: config.userAgent || 'HealthIntersections/FhirServer',
       crawlInterval: config.crawlInterval || 5 * 60 * 1000, // 5 minutes default
-      apiKeys: config.apiKeys || {}, // Map of server URL or code to API key
+      apiKeys: config.apiKeys || {}, // server code -> API key (sent as Api-Key)
+      // server code -> { tokenEndpoint, clientId, clientSecret, scope }: an OAuth2
+      // client_credentials grant; the token is sent as Authorization: Bearer
+      oauth: config.oauth || {},
       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,
@@ -61,65 +47,30 @@ class RegistryCrawler {
     this.totalBytes = 0;
     this.log = console;
     this.abortController = null;
+    // API keys and OAuth tokens for the servers that need them (shared with the tx module's
+    // ecosystem resolution: library/server-credentials.js)
+    this.credentials = new ServerCredentials({
+      apiKeys: this.config.apiKeys,
+      oauth: this.config.oauth,
+      timeout: this.config.timeout,
+      userAgent: this.config.userAgent,
+      agents: () => this.guardedAgents(),
+      signal: () => this.abortController?.signal,
+      log: (level, message) => this.addLogEntry(level, message)
+    });
   }
 
   useLog(logv) {
     this.log = logv;
   }
 
-  // A DNS lookup wrapper that rejects any host resolving to a non-public address.
-  // Enforced at connection time (so it also covers redirect targets and defeats
-  // DNS-rebinding), this is the SSRF guard for outbound fetches. The registry is
-  // crawled from server-supplied "next" links, so the target host is not trusted.
-  // Set config.allowPrivateAddresses = true to disable (e.g. for local test servers).
-  ssrfLookup() {
-    const allowPrivate = !!(this.config && this.config.allowPrivateAddresses);
-    return (hostname, options, callback) => {
-      if (typeof options === 'function') {
-        callback = options;
-        options = {};
-      }
-      const wantAll = !!(options && options.all);
-      dns.lookup(hostname, Object.assign({}, options, { all: true }), (err, addresses) => {
-        if (err) {
-          callback(err);
-          return;
-        }
-        if (!allowPrivate) {
-          for (const a of addresses) {
-            if (isNonPublicAddress(a.address)) {
-              callback(new Error('Blocked request to non-public address ' + a.address + ' (host ' + hostname + ')'));
-              return;
-            }
-          }
-        }
-        if (wantAll) {
-          callback(null, addresses);
-        } else {
-          callback(null, addresses[0].address, addresses[0].family);
-        }
-      });
-    };
-  }
-
-  // http/https agents that route every connection through the SSRF lookup.
+  // http/https agents that only connect to public addresses: the SSRF guard for outbound
+  // fetches (library/ssrf-guard.js). The registry is crawled from server-supplied "next" links,
+  // so the target host is not trusted. Set config.allowPrivateAddresses = true to disable (e.g.
+  // for local test servers).
   guardedAgents() {
     if (!this._guardedAgents) {
-      const lookup = this.ssrfLookup();
-      class GuardedHttpAgent extends http.Agent {
-        createConnection(options, cb) {
-          return super.createConnection(Object.assign({}, options, { lookup }), cb);
-        }
-      }
-      class GuardedHttpsAgent extends https.Agent {
-        createConnection(options, cb) {
-          return super.createConnection(Object.assign({}, options, { lookup }), cb);
-        }
-      }
-      this._guardedAgents = {
-        httpAgent: new GuardedHttpAgent({ keepAlive: true }),
-        httpsAgent: new GuardedHttpsAgent({ keepAlive: true })
-      };
+      this._guardedAgents = createGuardedAgents({ allowPrivate: !!this.config.allowPrivateAddresses });
     }
     return this._guardedAgents;
   }
@@ -160,6 +111,8 @@ class RegistryCrawler {
       }
       
       newData.doco = masterJson.documentation || '';
+      newData.registration = masterJson.registration || '';
+      newData.ecosystemDoco = masterJson['ecosystem-documentation'] || '';
       
       // Process each registry
       const registries = masterJson.registries || [];
@@ -300,7 +253,7 @@ class RegistryCrawler {
     const version = new ServerVersionInformation();
     version.version = versionConfig.version;
     version.address = versionConfig.url;
-    version.security = this.getApiKey(server.code) == null ? "open" : "api-key";
+    version.security = this.getOAuthConfig(server.code) ? "oauth" : this.getApiKey(server.code) == null ? "open" : "api-key";
     
     if (!version.address) {
       this.addLogEntry('error', `No URL for version ${version.version} of ${server.name}`, server.address);
@@ -336,7 +289,7 @@ class RegistryCrawler {
       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`);
+      this.addLogEntry('info', `  Server ${version.address}: ${version.lastTat} for ${version.codeSystems.length} CodeSystems and ${version.valueSets.length} ValueSets (${version.security})`);
       
     } catch (error) {
       debugLog(error);
@@ -413,7 +366,7 @@ class RegistryCrawler {
   async processServerVersionR3(version, server, exclusions) {
     // Get capability statement
     const capabilityUrl = `${version.address}/metadata`;
-    const capability = await this.fetchJson(capabilityUrl, server.name);
+    const capability = await this.fetchJson(capabilityUrl, server.code, version.address);
     
     version.version = capability.fhirVersion || '3.0.2';
     version.software = capability.software ? capability.software.name : "unknown";
@@ -423,7 +376,7 @@ class RegistryCrawler {
     // Get terminology capabilities (R3 uses Parameters resource)
     try {
       const termCapUrl = `${version.address}/metadata?mode=terminology`;
-      const termCap = await this.fetchJson(termCapUrl, server.name);
+      const termCap = await this.fetchJson(termCapUrl, server.code, version.address);
       
       if (termCap.parameter) {
         termCap.parameter.forEach(param => {
@@ -459,7 +412,7 @@ class RegistryCrawler {
   async processServerVersionR4or5(version, server, defVersion, exclusions) {
     // Get capability statement
     const capabilityUrl = `${version.address}/metadata`;
-    const capability = await this.fetchJson(capabilityUrl, server.code);
+    const capability = await this.fetchJson(capabilityUrl, server.code, version.address);
     
     version.version = capability.fhirVersion || defVersion;
     version.software = capability.software ? capability.software.name : "unknown";
@@ -471,7 +424,7 @@ class RegistryCrawler {
     // Get terminology capabilities
     try {
       const termCapUrl = `${version.address}/metadata?mode=terminology`;
-      const termCap = await this.fetchJson(termCapUrl, server.code);
+      const termCap = await this.fetchJson(termCapUrl, server.code, version.address);
       
       if (termCap.codeSystem) {
         termCap.codeSystem.forEach(cs => {
@@ -528,7 +481,7 @@ class RegistryCrawler {
 
         if (this.abortController?.signal.aborted) break;
         this.log.debug(`Fetching value sets from ${searchUrl}`);
-        const bundle = await this.fetchJson(searchUrl, server.code);
+        const bundle = await this.fetchJson(searchUrl, server.code, version.address);
 
         // Process entries in this page
         if (bundle.entry) {
@@ -596,36 +549,27 @@ class RegistryCrawler {
 
   /**
    * Fetch JSON from a URL
+   * @param {string} url
+   * @param {string} serverCode - the code the server's credentials (apiKeys, oauth) are under
+   * @param {string} [credentialBase] - the server's own address. When given, credentials are
+   *   sent only to that origin: next links come from the server, and may point anywhere
    */
-  async fetchJson(url, serverName) {
+  async fetchJson(url, serverCode, credentialBase) {
     try {
       // Add timestamp to bypass cache
       const fetchUrl = url.includes('?') 
         ? `${url}&_ts=${Date.now()}`
         : `${url}?_ts=${Date.now()}`;
-      
-      // Get API key if configured
-      const apiKey = this.getApiKey(serverName);
-      const headers = {
-        'Accept': 'application/json, application/fhir+json',
-        'User-Agent': this.config.userAgent
-      };
-      
-      if (apiKey) {
-        headers['Api-Key'] = apiKey;
+
+      const sendCredentials = !credentialBase || this.sameOrigin(url, credentialBase);
+      const useOAuth = sendCredentials && !!this.getOAuthConfig(serverCode);
+
+      let response = await this.getJson(fetchUrl, await this.credentialHeaders(serverCode, sendCredentials, false));
+      if (response.status === 401 && useOAuth) {
+        // the token was revoked or expired early: get a new one, and try once more
+        response = await this.getJson(fetchUrl, await this.credentialHeaders(serverCode, sendCredentials, true));
       }
-      
-      const response = await axios.get(fetchUrl, {
-        timeout: this.config.timeout,
-        headers: headers,
-        signal: this.abortController?.signal,
-        validateStatus: (status) => status < 500, // Don't throw on 4xx
-        // counted as it is unzipped, so a small response that unzips to a lot is stopped too
-        maxContentLength: this.config.maxResponseBytes,
-        httpAgent: this.guardedAgents().httpAgent,
-        httpsAgent: this.guardedAgents().httpsAgent
-      });
-      
+
       if (response.status >= 400) {
         throw new Error(`HTTP ${response.status}: ${response.statusText}`);
       }
@@ -655,16 +599,50 @@ class RegistryCrawler {
     }
   }
 
+  async getJson(fetchUrl, credentials) {
+    return axios.get(fetchUrl, {
+      timeout: this.config.timeout,
+      headers: Object.assign({
+        'Accept': 'application/json, application/fhir+json',
+        'User-Agent': this.config.userAgent
+      }, credentials),
+      signal: this.abortController?.signal,
+      validateStatus: (status) => status < 500, // Don't throw on 4xx
+      // counted as it is unzipped, so a small response that unzips to a lot is stopped too
+      maxContentLength: this.config.maxResponseBytes,
+      httpAgent: this.guardedAgents().httpAgent,
+      httpsAgent: this.guardedAgents().httpsAgent
+    });
+  }
+
+  sameOrigin(url, base) {
+    try {
+      return new URL(url).origin === new URL(base).origin;
+    } catch (e) {
+      return false;
+    }
+  }
+
   /**
-   * Get API key for a given URL
+   * The headers that carry a server's credentials (see ServerCredentials)
    */
-  getApiKey(name) {
-    // Check for exact URL match
-    if (this.config.apiKeys[name]) {
-      return this.config.apiKeys[name];
+  async credentialHeaders(serverCode, sendCredentials, renewToken) {
+    if (!sendCredentials) {
+      return {};
     }
-    
-    return null;
+    return this.credentials.headers(serverCode, renewToken);
+  }
+
+  getApiKey(name) {
+    return this.credentials.getApiKey(name);
+  }
+
+  getOAuthConfig(name) {
+    return this.credentials.getOAuthConfig(name);
+  }
+
+  async getAccessToken(serverCode, renew = false) {
+    return this.credentials.getAccessToken(serverCode, renew);
   }
 
   /**

package/registry/documentation/api.md

@@ -15,12 +15,13 @@ contract:
 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`:
+There are two operations from the ecosystem IG, and one extension, all `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 |
+| `/tx-reg/choose-server` | **Server choice** - which one server to use for a request involving several code systems (JSON only; [below](#server-choice-get-tx-regchoose-server)) |
 
 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
@@ -143,7 +144,72 @@ when empty, so an empty object means nobody hosts it.
 * Resolve takes `version` as an alternative to `url|version`.
 * Resolve omits `authoritative` and `candidates` when they are empty.
 
-## Operational pages
+## Server choice: `GET /tx-reg/choose-server`
+
+Not in the ecosystem IG. A request often involves several code systems - a value set that
+includes LOINC and a national code system, a CodeableConcept with codings from three - and
+resolution answers for one at a time. The HL7 Java tooling combines the answers into a choice
+of one server (`TerminologyClientManager.chooseServer` in org.hl7.fhir.core); this makes the
+same choice here for clients that aren't Java. It doesn't replace the Java code, which still
+does its own choosing.
+
+| Parameter | |
+|---|---|
+| `fhirVersion` | Required, as for resolve |
+| `system` | A code system the request involves, `url` or `url\|version`. Repeat it for each (`system=a&system=b`) - the one parameter that isn't first-value-only |
+| `default` | Required. The client's default terminology server: the fallback, and the server for the code systems tx.fhir.org handles specially |
+| `valueSet` | The value set the request is about, `url` or `url\|version`, if there is one |
+| `language` | As for resolve, but only for language sensitive requests (an expansion where the display language matters, a validation that checks a display, a lookup that returns designations) |
+| `usage` | As for resolve |
+
+```json
+{
+  "server": "https://tx.ontoserver.csiro.au/fhir",
+  "log": [
+    "https://healthterminologies.gov.au/fhir/CodeSystem/x: authoritative [https://tx.ontoserver.csiro.au/fhir], candidates []",
+    "http://terminology.hl7.org/CodeSystem/v2-0203: authoritative [http://tx.fhir.org/r4], candidates [https://tx.ontoserver.csiro.au/fhir]",
+    "Found partially authoritative server https://tx.ontoserver.csiro.au/fhir"
+  ]
+}
+```
+
+`log` is for people: what resolution says about each code system, then the rule that decided.
+
+### What the client does first
+
+What the Java tooling works out before it chooses, a client must too:
+
+* The code systems: from the codings, and from the value set's includes and excludes,
+  following imported value sets. The imports are often only in the client's own context (the
+  IG being built), so the registry can't follow them. If the client can't follow one, it
+  should use its default server without asking.
+* Versions: those fixed by the expansion parameters (`system-version`,
+  `force-system-version`) applied to the systems.
+* Language: for an expansion, the `displayLanguage` of the expansion parameters if no other.
+
+### How the choice is made
+
+In order:
+
+1. A server authoritative for all the code systems.
+2. A server authoritative for one, and authoritative or a candidate for each of the others.
+3. Several code systems including SNOMED CT: the choice for SNOMED CT alone. Otherwise, if a
+   code system is one tx.fhir.org handles specially (LOINC, UCUM, RxNorm, CVX, NDC, CPT,
+   BCP-13/47, ISO 3166/4217 ...): the default.
+4. A server that is a candidate for all of them, and has a usable copy of each - its
+   TerminologyCapabilities says `complete` or `fragment`, or gives no content mode. Not
+   checked for a code system tx.fhir.org is also a candidate for.
+5. The server authoritative for the most of them (the first, on a tie).
+6. The server the value set comes from (by resolving `valueSet`), else the default.
+
+In 2 and 4, a code system that no server hosts doesn't count against a server.
+
+Where this differs from the Java tooling: step 4 uses the content mode the registry scanned
+instead of searching the server, and trusts a server that didn't say; the special handling in
+step 3 sends to `default` rather than to whichever of tx.fhir.org / tx-dev the client has used;
+ties go to the first rather than to hash order. Step 3 is tx.fhir.org specific, and applies to
+any ecosystem for now.
+
 
 These are HTML, not part of the API, and never secured:
 

package/registry/documentation/configuration.md

@@ -12,6 +12,7 @@ The registry is configured under `modules.registry` in the server's configuratio
   "timeout": 30000,
   "userAgent": "YourServer/1.0",
   "apiKeys": {},
+  "oauth": {},
   "maxResponseMB": 100,
   "uptimeWindowDays": 30,
   "uptimeRetentionDays": 90,
@@ -25,6 +26,39 @@ The registry is configured under `modules.registry` in the server's configuratio
 |---|---|---|
 | `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. |
+| `oauth` | `{}` | OAuth2 client credentials for servers the registry needs a token to scan, by server code - see [below](#oauth). An endpoint scanned with a token is reported as `security: oauth` in the API. |
+
+Credentials are only sent to the origin (scheme, host and port) of the server's registered
+address. A `next` link that points somewhere else is still followed, but without them.
+
+### OAuth
+
+For a server that issues tokens by the OAuth2 `client_credentials` grant, the registry asks
+the token endpoint for a token, sending its client id and secret in the form body
+(`client_secret_post`), and sends the token as `Authorization: Bearer`. The token is reused
+until it is about to expire (`expires_in`; 5 minutes if the endpoint doesn't say), and
+replaced early if the server answers 401. A server with an `oauth` entry is not sent its
+`apiKeys` entry.
+
+```json
+"oauth": {
+  "nzhts": {
+    "tokenEndpoint": "https://authenticate.nzhts.digital.health.nz/auth/realms/nzhts/protocol/openid-connect/token",
+    "clientId": "hl7",
+    "clientSecret": "...",
+    "scope": ""
+  }
+}
+```
+
+| Property | |
+|---|---|
+| `tokenEndpoint` | The token endpoint. Must be `https:`. Redirects are not followed. |
+| `clientId`, `clientSecret` | The client's credentials, from the server's operator. |
+| `scope` | Optional. Sent if present and not empty. |
+
+The field names are those of the HL7 Java tooling's `oauthClientCredentials` settings, so the
+same values can be copied between the two.
 
 ## Scanning
 

package/registry/documentation/internals.md

@@ -28,7 +28,10 @@ How the module works, for anyone changing it. The user-facing behaviour is in
 `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"`);
+1. fetch the master registration file (`formatVersion` must be `"1"`); its optional
+   `registration` and `ecosystem-documentation` URLs are the "Register your own server" and
+   "Documentation" links on the home page (each is omitted if the file doesn't give it), since
+   they depend on the ecosystem;
 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

package/registry/documentation/readme.md

@@ -27,8 +27,9 @@ 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).
+FHIR version) and its claims. The format is documented on the IG's ecosystem page; HL7's own
+ecosystem (its locations, and how to register a server in it) 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: