fhirsmith 0.18.2 → 1.0.0

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;
   }
@@ -302,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);
@@ -338,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);
@@ -415,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";
@@ -425,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 => {
@@ -461,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";
@@ -473,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 => {
@@ -530,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) {
@@ -598,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}`);
       }
@@ -657,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/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/registry-template.html

@@ -55,8 +55,6 @@
 		<div class="container">  <!-- container -->
 		<div style="background-color: #ad1f2f; padding: 6px; color: white;">  <!-- container -->
 
-  <a href="http://www.hl7.org/fhir" style="color: gold" title="Fast Healthcare Interoperability Resources - Home Page"><img border="0" src="/icon-fhir-16.png" style="vertical-align: text-bottom"/> <b>FHIR</b></a> &copy; HL7.org &nbsp;|&nbsp;
-  <a href="https://github.com/HealthIntersections/FHIRsmith/blob/main/README.md" style="color: gold"><img border="0" src="/FHIRsmith16.png" style="vertical-align: text-bottom"/> FHIRsmith</a> [%ver%] &nbsp;|&nbsp;
   <a href="/" style="color: gold"> Server Home</a> &nbsp;|&nbsp;
   <a href="/tx-reg" style="color: gold">Registry Home</a>  &nbsp;|&nbsp;
   <a href="/tx-reg/resolve" style="color: gold">Resolve</a>  &nbsp;|&nbsp;
@@ -75,7 +73,7 @@
             	<div class="inner-wrapper">
  <div class="col-9">
 
-  <h2><img border="0" src="../FHIRsmith32.png" style="vertical-align: text-bottom"/> [%title%] </h2>
+  <h2><a href="https://github.com/HealthIntersections/FHIRsmith/blob/main/README.md" title="FHIRsmith [%ver%]"><img border="0" src="/FHIRsmith32.png" alt="FHIRsmith Logo" style="vertical-align: text-bottom"/></a> [%title%] </h2>
 
 [%content%]
 
@@ -93,8 +91,7 @@
 		<div class="container">  <!-- container -->
 			<div class="inner-wrapper">
 				<p>
-                    <a href="http://www.hl7.org/fhir" style="color: gold" title="Fast Healthcare Interoperability Resources - Home Page"><img border="0" src="/icon-fhir-16.png" style="vertical-align: text-bottom"/> <b>FHIR</b></a> &copy; HL7.org 2011+.  &nbsp;|&nbsp;
-                    <a href="https://github.com/HealthIntersections/FHIRsmith/blob/main/README.md" style="color: gold"><img border="0" src="/FHIRsmith16.png" style="vertical-align: text-bottom"/> FHIRsmith</a>  [%ver%]  &copy; HealthIntersections.com.au 2023+ &nbsp;|&nbsp;
+                    <a href="https://github.com/HealthIntersections/FHIRsmith/blob/main/README.md" style="color: gold"><img border="0" src="/FHIRsmith16.png" alt="FHIRsmith Logo" style="vertical-align: text-bottom"/> FHIRsmith</a>  [%ver%]  &copy; HealthIntersections.com.au 2023+ &nbsp;|&nbsp;
        Terminology Registry [%crawler-status%] &nbsp;|
                     &nbsp; ([%ms%] ms)
                     [%sponsorMessage%]
@@ -118,10 +115,10 @@
 ================================================== -->
   <!-- Placed at the end of the document so the pages load faster -->
 <!-- <script src="/assets/js/jquery.js"/> -->
-<script src="/assets/js/bootstrap.min.js"/>
-<script src="/assets/js/respond.min.js"/>
+<script src="/assets/js/bootstrap.min.js"></script>
+<script src="/assets/js/respond.min.js"></script>
 
-<script src="/assets/js/fhir.js"/>
+<script src="/assets/js/fhir.js"></script>
 
   <!-- Analytics Below
 ================================================== -->

package/registry/registry.js

@@ -91,6 +91,7 @@ class RegistryModule {
         timeout: config.timeout || 30000,
         userAgent: config.userAgent || 'FHIRRegistryServer/1.0',
         apiKeys: config.apiKeys || {},
+        oauth: config.oauth || {},
         maxResponseMB: config.maxResponseMB,
         uptimeWindowDays: config.uptimeWindowDays,
         uptimeRetentionDays: config.uptimeRetentionDays
@@ -1559,7 +1560,7 @@ class RegistryModule {
     // Query information section
     html += '<div class="card mb-4">';
     html += '<div class="card-header">';
-    html += '<h2 class="card-title">Query Information</h2>';
+    html += '<h3 class="card-title">Query Information</h3>';
     html += '</div>';
     html += '<div class="card-body">';
     html += `<p><strong>FHIR Version:</strong> ${escape(fhirVersion)}</p>`;
@@ -1577,7 +1578,7 @@ class RegistryModule {
     // Authoritative servers section
     html += '<div class="card mb-4">';
     html += '<div class="card-header">';
-    html += '<h2 class="card-title">Authoritative Servers</h2>';
+    html += '<h3 class="card-title">Authoritative Servers</h3>';
     html += '</div>';
     html += '<div class="card-body">';
 
@@ -1616,7 +1617,7 @@ class RegistryModule {
     // Candidate servers section
     html += '<div class="card mb-4">';
     html += '<div class="card-header">';
-    html += '<h2 class="card-title">Candidate Servers</h2>';
+    html += '<h3 class="card-title">Candidate Servers</h3>';
     html += '</div>';
     html += '<div class="card-body">';
 
@@ -1867,7 +1868,7 @@ class RegistryModule {
           case 'error': levelStyle = 'color: #d9534f; font-weight: bold;'; break;
           case 'warn': levelStyle = 'color: #f0ad4e;'; break;
           case 'debug': levelStyle = 'color: #5cb85c;'; break;
-          default: levelStyle = 'color: #0275d8;'; // info
+          default: levelStyle = 'color: #0056b3;'; // info
         }
 
         // Format: [time] [LEVEL] message

package/root-bare-template.html

@@ -71,9 +71,12 @@
 
 <body style="margin-left: 10px">
 
-<h2>[%title%] </h2>
+<!-- the page's one h1, the size of an h2 as before -->
+<h1 style="font-size:1.5em;margin:0.83em 0">[%title%] </h1>
 
+<main>
 [%content%]
+</main>
 
 
       <!-- JS and analytics only. -->
@@ -81,10 +84,10 @@
 ================================================== -->
   <!-- Placed at the end of the document so the pages load faster -->
 <!-- <script src="/assets/js/jquery.js"/> -->
-<script src="/assets/js/bootstrap.min.js"/>
-<script src="/assets/js/respond.min.js"/>
+<script src="/assets/js/bootstrap.min.js"></script>
+<script src="/assets/js/respond.min.js"></script>
 
-<script src="/assets/js/fhir.js"/>
+<script src="/assets/js/fhir.js"></script>
 
   <!-- Analytics Below
 ================================================== -->

package/root-template.html

@@ -53,8 +53,6 @@
 		<div id="stripe"> </div>
 		<div class="container">  <!-- container -->
 		<div style="background-color: #ad1f2f; padding: 6px; color: white;">  <!-- container -->
-  <a href="http://www.hl7.org/fhir" style="color: gold" title="Fast Healthcare Interoperability Resources - Home Page"><img border="0" src="/icon-fhir-16.png" style="vertical-align: text-bottom"/> <b>FHIR</b></a> &copy; HL7.org &nbsp;|&nbsp;
-  <a href="https://github.com/HealthIntersections/FHIRsmith/blob/main/README.md" style="color: gold"><img border="0" src="/FHIRsmith16.png" style="vertical-align: text-bottom"/> FHIRsmith</a> [%ver%] &nbsp;|&nbsp;
   <a href="/" style="color: gold"> Server Home</a>
   &nbsp;
   &nbsp;
@@ -70,7 +68,7 @@
             	<div class="inner-wrapper">
  <div class="col-9">
 
-  <h2><img border="0" src="/FHIRsmith32.png" style="vertical-align: text-bottom"/> FHIRsmith: [%title%] </h2>
+     <h2><a href="https://github.com/HealthIntersections/FHIRsmith/blob/main/README.md" title="FHIRsmith [%ver%]"><img border="0" src="/FHIRsmith32.png" alt="FHIRsmith Logo" style="vertical-align: text-bottom"/></a> FHIRsmith: [%title%] </h2>
 
 [%content%]
 
@@ -89,8 +87,7 @@
 		<div class="container">  <!-- container -->
 			<div class="inner-wrapper">
 				<p>
-                    <a href="http://www.hl7.org/fhir" style="color: gold" title="Fast Healthcare Interoperability Resources - Home Page"><img border="0" src="/icon-fhir-16.png" style="vertical-align: text-bottom"/> <b>FHIR</b></a> &copy; HL7.org 2011+.  &nbsp;|&nbsp;
-                    <a href="https://github.com/HealthIntersections/FHIRsmith/blob/main/README.md" style="color: gold"><img border="0" src="/FHIRsmith16.png" style="vertical-align: text-bottom"/> FHIRsmith</a>  [%ver%]  &copy; HealthIntersections.com.au 2023+ &nbsp;|
+                    <a href="https://github.com/HealthIntersections/FHIRsmith/blob/main/README.md" style="color: gold"><img border="0" src="/FHIRsmith16.png" alt="FHIRsmith Logo" style="vertical-align: text-bottom"/> FHIRsmith</a>  [%ver%]  &copy; HealthIntersections.com.au 2023+ &nbsp;|
                     &nbsp; ([%ms%] ms)
                     [%sponsorMessage%]
         </p>
@@ -113,10 +110,10 @@
 ================================================== -->
   <!-- Placed at the end of the document so the pages load faster -->
 <!-- <script src="/assets/js/jquery.js"/> -->
-<script src="/assets/js/bootstrap.min.js"/>
-<script src="/assets/js/respond.min.js"/>
+<script src="/assets/js/bootstrap.min.js"></script>
+<script src="/assets/js/respond.min.js"></script>
 
-<script src="/assets/js/fhir.js"/>
+<script src="/assets/js/fhir.js"></script>
 
   <!-- Analytics Below
 ================================================== -->