fhirsmith 0.16.1 → 0.17.0

package/CHANGELOG.md

@@ -5,6 +5,53 @@ All notable changes to Health Intersections FHIRsmith will be documented in this
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.17.0] - 2026-10-17
+
+An extensive security review, which hardened many things, but no actual securty notifications needed. Plus improvemnts to text search in terminology filters
+
+### Security
+
+- HTML pages (all modules using the shared page template): content containing `` $` `` or `$'` - which HTML escaping leaves alone - made the template insert a copy of part of itself into the page, garbling it. No way to inject script through it was found, but the page is now built without that substitution
+- Packages: a tarball whose package.json version was not entirely semver (e.g. `1.0.0/../../x`) was accepted, and its mirror file written outside the mirror folder. The version must now be whole semver, and the mirror file must be in the mirror folder
+- Rendered resources: links to `javascript:`, `data:` or `vbscript:` URLs taken from resource content are neutralised
+- tx: values from loaded packages are escaped (and URL-encoded in links) on the problems page, the resource tabs, and the operations form's list of value sets
+- tx: CodeSystems, ValueSets and ConceptMaps whose narrative (or a contained resource's) has active content - script, event handler attributes, `javascript:` URLs, frames, objects, forms, svg and the like - are not loaded, and a warning says what was found. The Original Narrative tab also refuses such a narrative. The check is in `library/narrative-check.js` for other uses. The package value set and concept map caches are renamed so that they are rebuilt and re-checked once
+- xig: the database is downloaded over https (it was http, so it could theoretically have been replaced in transit, and its narratives are shown as they are), and a redirect off https is refused
+- Extension tracker: the profiles page put the resource types from submissions into a script without escaping, so anyone could submit data that ran script on that page. They are now escaped
+- Extension tracker: submissions must carry the token the IG Publisher sends (`token` in the ext-tracker config; without it, no token is needed), and must look like what the IG Publisher sends - the expected properties only, codes, URLs, resource types and element paths where those belong, and limited sizes. Anything else is refused, and the refusal logged
+- Registry: server and registry URLs from registry lists (which other people host) were put into links without escaping, so a listed URL could add script to the registry's pages; and links were made from any URL, including `javascript:`. Links are now escaped, and made only from http(s) URLs
+- Registry: the crawler limits each server's response to `maxResponseMB` (default 100) once unzipped, so a server can't exhaust the registry's memory
+- xig: POST /xig/update, which re-downloads the database (about 3 GB), needed no authentication. It now needs the `updateToken` from the xig config in an `x-update-token` header (or the form now on /xig/stats, which starts an update and returns straight away), and is disabled when no updateToken is configured
+- xig: a search parameter given more than once, or a very long one, is handled (the first is used, and each is capped at 200 characters) instead of failing the page
+- OCL: the configured token can see the private repos of its account, and what it finds is served to anyone through the terminology server. Sources and collections are now served only when they are public (`public_access` View or Edit), whether they are found by discovery or by `$resolveReference`; anything that can't be confirmed public is left out. The token's account should still be one that can see only public repos
+- OCL: a repo path returned by OCL is only used if it is a relative path on the OCL server, so a request carrying the token can't be sent to another host
+- Packages: the crawler limits what a package can cost it: the download (`maxDownloadMB`, default 250), the total unzipped (`maxUnpackedMB`, 4096), the files it reads (`maxFileMB`, 50) and the number of files (`maxFiles`, 250000), all in the packages `crawler` config. Packages are now unpacked as a stream, keeping only package.json, .index.json, ig.ini and one .json file at a time, so a decompression bomb can't exhaust memory
+
+### Added
+
+- `TerminologyCapabilities.expansion.textFilter` describes how text filters match
+- OCL: with a `token=` on the `ocl:` source line, canonical URLs are resolved through OCL's `$resolveReference` (ConceptMap source systems, ValueSet collections and their compose sources), rather than by searching the listings. Without a token nothing changes
+- OCL: a source's latest released version is served as its default version, as OCL itself does; HEAD is still available as version `HEAD` (needs the token)
+- README: what to do after upgrading Node.js (`npm rebuild`, or reinstall)
+
+### Changed
+
+- Text filters on code systems loaded from files and packages ignore case, and accents on Latin, Greek and Cyrillic letters (`colera` finds `Cólera`), and a search of several words matches when each word starts a word of the display or of one designation, in any order (`diabetes tipo 2` finds `Diabetes mellitus tipo 2`). These matches rank below matches of the whole text, shorter displays first.
+- `$expand` with a text filter returns the best matches first on code systems loaded from files and packages, and on OCL code systems, as it already did on SNOMED CT
+- OCL: sources and collections are discovered from the global `/sources/` and `/collections/` listings (falling back to each organisation's), and only organisation-owned ones are served - repos owned by a user are not
+- OCL: a source's mappings are fetched from `{source}/mappings/` instead of walking every concept
+
+### Fixed
+
+- LOINC: text filter matches came in reverse description order (Z to A) when the expansion asked for them sorted. They now come in description order either way
+- LOINC: an `is-a` filter left out the concept itself, so it gave the same codes as `descendent-of`. It now includes the concept, as FHIR defines `is-a`
+- OCL: `$translate` never returned anything from OCL concept maps. The maps declared OCL repo paths as their source and target scopes, which aren't value sets, so every translation failed with not-found; and `NARROWER-THAN` / `BROADER-THAN` mappings had relationship codes that aren't FHIR codes. The scopes are gone, the map types become `source-is-narrower-than-target` / `source-is-broader-than-target` (and `NOT-SAME-AS` becomes `not-related-to`), and `Q-AND-A` and `CONCEPT-SET` mappings, which aren't translations, are left out
+- tx: a package value set or concept map cache whose build was cut short (the server stopped part way through) was used as it was, missing whatever hadn't been written. A cache is now marked complete when it's built, and one without the mark is rebuilt - so existing caches are rebuilt once, on the first start of this version
+
+### Tx Conformance Statement
+
+FHIRsmith v0.17.0 passed all 3630 HL7 terminology service tests (modes tx.fhir.org+omop+general+snomed+mimetypes+icd-11+closure, tests v1.9.6, runner v7.0.2)
+
 ## [0.16.1] - 2026-10-16
 
 ### Added

package/README.md

@@ -14,7 +14,7 @@ This server provides a set of server-side services that are useful for the FHIR
 * [Package server](packages/readme.md) - **NPM-style FHIR package registry** with search, versioning, and downloads, consistent with the FHIR NPM Specification (as running at http://packages2.fhir.org/packages). Its API is described by an OpenAPI 3.1 spec at `/packages/openapi.json` (and `.yaml`), with a browsable reference at `/packages/openapi`
 * [XIG server](xig/readme.md) -  **Comprehensive FHIR IG analytics** with resource breakdowns by version, authority, and realm (as running at http://packages2.fhir.org/packages)
 * [Publisher](publisher/readme.md) - FHIR publishing services (as running at [healthintersections.com.au](http://www.healthintersections.com.au/publisher))
-* [Testing](testing/readme.md) - **TestReport repository**: receives FHIR TestReports from TxTester and other test tools, with a FHIR API and web pages (as running at https://testing.fhir.org/testing). Its API is described by an OpenAPI 3.1 spec at `/testing/openapi.json` (and `.yaml`), with a browsable reference at `/testing/openapi`
+* [Testing](testing/readme.md) - **TestReport repository**: receives FHIR TestReports from TxTester and other test tools, with a FHIR API and web pages (as running at https://npm.fhir.org/testing). Its API is described by an OpenAPI 3.1 spec at `/testing/openapi.json` (and `.yaml`), with a browsable reference at `/testing/openapi`
 * [VCL](vcl/readme.md) - **Parse VCL expressions** into FHIR ValueSet resources (as running at http://fhir.org/vcl)
 * (Coming) Token services
 
@@ -81,7 +81,7 @@ During development with a cloned repository, the data directory defaults to `[ro
 is provided by the host — see Deployment below.
 
 ### Prerequisites
-- Node.js 16+
+- Node.js 24+
 - NPM or Yarn
 - Java 17+ (for FHIR validator, also for the test cases)
 
@@ -207,6 +207,15 @@ Or run it inline:
 FHIRSMITH_DATA_DIR=/var/lib/fhirsmith fhirsmith
 ```
 
+### Changing the Node.js version
+
+Some of FHIRsmith's dependencies (the SQLite drivers) are native modules, built for the
+version of Node.js that installed them. After upgrading Node.js, rebuild them - `npm rebuild`
+in the FHIRsmith folder, or `npm rebuild -g fhirsmith` for a global install - or reinstall
+FHIRsmith. Otherwise the server stops at startup with "compiled against a different Node.js
+version". (With nvm, each Node.js version has its own global packages, so install FHIRsmith
+again under the new version.) Docker images aren't affected.
+
 ### Docker Installation
 
 The server is available as a Docker image. Mount a host directory as the data directory:
@@ -339,30 +348,29 @@ GitHub Actions will automatically:
 
 or do it via a PR
 
-4. Tag and push the release:
+4. Run the tx tests (`npx jest tests/tx/test-cases.test.js`), then tag and push the release:
 ```bash
-   git tag vX.Y.Z
-   git push origin vX.Y.Z
+   ./release.sh X.Y.Z
 ```
 
+   `gr.sh` checks that the release is ready - on `main` and pushed, the three versions in
+   `package.json` and `package-lock.json` match, `CHANGELOG.md` has a dated section with the
+   conformance statement, and `test-cases-report.json` passed, is from this version and is
+   newer than the last code change - then submits the report to
+   [npm.fhir.org](https://npm.fhir.org/testing) (set `FHIRSMITH_TESTING_TOKEN` if it needs a
+   token), and only if that is accepted, tags `vX.Y.Z` and pushes the tag.
+
+   The tx test run writes `test-cases-report.json` next to `test-cases-summary.txt` (both
+   are ignored by git). The report records the version in `package.json` when the tests
+   ran, so run the tx tests after step 2. To submit a report on its own (to a different
+   /testing server, say): `node utilities/submit-test-report.js [-server {url}] [-token {token}]`.
+
 5. Monitor the release:
     - Check [GitHub Actions](https://github.com/HealthIntersections/fhirsmith/actions) for the Release workflow
     - Verify the [GitHub Release](https://github.com/HealthIntersections/fhirsmith/releases) was created
     - Confirm Docker images are available at [GHCR](https://github.com/HealthIntersections/fhirsmith/pkgs/container/fhirsmith)
 
-6. Submit the tx conformance report to [testing.fhir.org](https://testing.fhir.org/testing):
-```bash
-   node utilities/submit-test-report.js -token {token}
-```
-
-   The tx test run writes `test-cases-report.json` next to `test-cases-summary.txt` (both
-   are ignored by git); this uploads it as a TestReport. The report records the version in
-   `package.json` when the tests ran, so for it to name the release, run the tx tests
-   after step 2 - the script warns if the report is from a different version, or from a
-   snapshot. Use `-server {url}` to send it to a different /testing server; the token can
-   also come from `FHIRSMITH_TESTING_TOKEN`.
-
-7. Update `package.json` to have the next release version -SNAPSHOT
+6. Update `package.json` to have the next release version -SNAPSHOT
 
 **If a release fails:**
 - Delete the tag: `git tag -d vX.Y.Z && git push origin :refs/tags/vX.Y.Z`

package/config-template.json

@@ -61,7 +61,11 @@
     },
     "xig": {
       "enabled": false,
-      "autoUpdate": true
+      "autoUpdate": true,
+      // shared secret for POST /xig/update, which re-downloads the database on demand. Send
+      // it in the x-update-token header. Omit this and the endpoint is disabled entirely -
+      // the scheduled update (autoUpdate) is unaffected either way.
+      "updateToken": "change-this-to-a-secure-random-string"
     },
     "packages": {
       "enabled": false,
@@ -73,7 +77,17 @@
       "crawlToken": "change-this-to-a-secure-random-string",
       "crawler": {
         "enabled": true,
-        "schedule": "0 * * * *"
+        "schedule": "0 * * * *",
+        // limits on a package, so a hostile or broken one (a decompression bomb, say) costs
+        // a bounded amount. These are the defaults. maxDownloadMB: the package file;
+        // maxUnpackedMB: its files once unzipped (streamed, so this limits work, not
+        // memory); maxFileMB: a file the crawler reads (package.json, .index.json, ig.ini
+        // and each .json, for its url) - memory use is bounded by this; maxFiles: the number
+        // of files in a package
+        "maxDownloadMB": 250,
+        "maxUnpackedMB": 4096,
+        "maxFileMB": 50,
+        "maxFiles": 250000
       },
       // /packages/npm-check: checks any registry against the npm registry protocol. On by
       // default; the other settings are the defaults. "control": false stops the daily
@@ -92,7 +106,9 @@
       "crawlInterval": 30,
       "timeout": 30000,
       "userAgent": "YourServer/1.0",
-      "apiKeys": {}
+      "apiKeys": {},
+      // the most a crawled server's response can be, once unzipped
+      "maxResponseMB": 100
     },
     "publisher": {
       "enabled": true,
@@ -271,7 +287,12 @@
     "ext-tracker": {
       "enabled": true,
       "database": "/var/fhir/data/extension-tracker.db",
-      "url": "/ext-tracker"
+      "url": "/ext-tracker",
+      // the token submissions must carry (Authorization: Bearer ...). The IG Publisher sends
+      // 9D1C23C0-3915-4542-882E-2BCC55645DF8 - it's in the publisher's source, so it is not a
+      // secret, but it keeps out submissions that aren't from the publisher. Omit it and
+      // submissions need no token
+      "token": "9D1C23C0-3915-4542-882E-2BCC55645DF8"
     },
     // TestReports from TxTester and other tools, at /testing. See testing/readme.md
     "testing": {

package/extension-tracker/extension-tracker.js

@@ -4,9 +4,100 @@ const Database = require('better-sqlite3');
 const htmlServer = require('../library/html-server');
 const escape = require('escape-html');
 const packageJson = require('../package.json');
+const { tokenMatches, tokenConfigured } = require('../library/request-token');
 
 const TEMPLATE_NAME = 'ext-tracker';
 
+// What the IG Publisher submits (ExtensionTracker.generate() in the publisher): anything
+// that doesn't look like that is refused, which keeps what anyone can put in the database
+// (and so in these pages) to the shapes the pages expect
+const CODE = /^[A-Za-z0-9._-]{1,100}$/;
+const VERSION = /^[A-Za-z0-9._+-]{1,50}$/;
+const FHIR_VERSION = /^\d+\.\d+\.\d+(-[A-Za-z0-9.-]+)?$/;
+const URL_LIKE = /^[A-Za-z][A-Za-z0-9+.-]*:[^\s"'<>\\]{1,1000}$/;
+const RESOURCE_TYPE = /^[A-Za-z][A-Za-z0-9_]{0,99}$/;
+// an element path, e.g. Patient.name or ImplementationGuide.definition.page (a logical
+// model's type can be a URL)
+const PATH = /^[A-Za-z][\w.:/#%[\]-]{0,511}$/;
+const TYPE_CODE = /^[^\s"'<>\\]{1,256}$/;
+const MAX_TITLE = 1024;
+const MAX_ITEMS = 20000;
+
+/**
+ * Checks that a submission looks like what the IG Publisher sends.
+ *
+ * @returns {string[]} what is wrong (empty if nothing)
+ */
+function validateSubmission(data) {
+  const errors = [];
+  const check = (ok, message) => {
+    if (!ok && errors.length < 10) {
+      errors.push(message);
+    }
+  };
+  const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+  const str = (v, re) => typeof v === 'string' && re.test(v);
+  const optionalTitle = (v) => v === undefined || v === null || (typeof v === 'string' && v.length <= MAX_TITLE);
+  const onlyKeys = (obj, keys, where) => {
+    for (const k of Object.keys(obj)) {
+      check(keys.includes(k), `${where}: unexpected property ${JSON.stringify(k.substring(0, 50))}`);
+    }
+  };
+
+  if (!isObject(data)) {
+    return ['the submission must be a JSON object'];
+  }
+  onlyKeys(data, ['package', 'version', 'fhirVersion', 'jurisdiction', 'extensions', 'profiles', 'usage'], 'submission');
+  check(str(data.package, CODE), 'package must be a package id');
+  check(str(data.version, VERSION), 'version must be a version');
+  check(str(data.fhirVersion, FHIR_VERSION), 'fhirVersion must be a FHIR version (e.g. 4.0.1)');
+  check(data.jurisdiction === undefined || data.jurisdiction === null || str(data.jurisdiction, CODE), 'jurisdiction must be a code');
+
+  let items = 0;
+  if (data.extensions !== undefined) {
+    check(Array.isArray(data.extensions), 'extensions must be an array');
+    for (const [i, ext] of (Array.isArray(data.extensions) ? data.extensions : []).entries()) {
+      items++;
+      if (!isObject(ext)) {
+        check(false, `extensions[${i}] must be an object`);
+        continue;
+      }
+      onlyKeys(ext, ['url', 'title', 'types'], `extensions[${i}]`);
+      check(str(ext.url, URL_LIKE), `extensions[${i}].url must be a URL`);
+      check(optionalTitle(ext.title), `extensions[${i}].title must be text`);
+      check(ext.types === undefined || (Array.isArray(ext.types) && ext.types.every(t => str(t, TYPE_CODE))), `extensions[${i}].types must be an array of type codes`);
+      items += Array.isArray(ext.types) ? ext.types.length : 0;
+    }
+  }
+  if (data.profiles !== undefined) {
+    check(isObject(data.profiles), 'profiles must be an object');
+    for (const [type, list] of Object.entries(isObject(data.profiles) ? data.profiles : {})) {
+      check(RESOURCE_TYPE.test(type), `profiles: ${JSON.stringify(type.substring(0, 50))} is not a resource type`);
+      check(Array.isArray(list), `profiles.${type} must be an array`);
+      for (const [i, prof] of (Array.isArray(list) ? list : []).entries()) {
+        items++;
+        if (!isObject(prof)) {
+          check(false, `profiles.${type}[${i}] must be an object`);
+          continue;
+        }
+        onlyKeys(prof, ['url', 'title'], `profiles.${type}[${i}]`);
+        check(str(prof.url, URL_LIKE), `profiles.${type}[${i}].url must be a URL`);
+        check(optionalTitle(prof.title), `profiles.${type}[${i}].title must be text`);
+      }
+    }
+  }
+  if (data.usage !== undefined) {
+    check(isObject(data.usage), 'usage must be an object');
+    for (const [url, locations] of Object.entries(isObject(data.usage) ? data.usage : {})) {
+      check(URL_LIKE.test(url), `usage: ${JSON.stringify(url.substring(0, 50))} is not a URL`);
+      check(Array.isArray(locations) && locations.every(l => str(l, PATH)), `usage[${JSON.stringify(url.substring(0, 50))}] must be an array of element paths`);
+      items += Array.isArray(locations) ? locations.length : 0;
+    }
+  }
+  check(items <= MAX_ITEMS, `the submission has more than ${MAX_ITEMS} items`);
+  return errors;
+}
+
 class ExtensionTrackerModule {
   constructor(stats) {
     this.stats = stats;
@@ -15,6 +106,7 @@ class ExtensionTrackerModule {
   }
 
   initialize(config, app) {
+    this.config = config;
     const dbPath = config.database || path.join(config.folder || '.', 'extension-tracker.db');
     this.db = new Database(dbPath);
     this.db.pragma('journal_mode = WAL');
@@ -130,10 +222,12 @@ class ExtensionTrackerModule {
    * @param {string} cookiePrefix - cookie name prefix for persistence
    */
   buildColumnFilters(tableId, columns, cookiePrefix) {
+    // goes inside a <script>, and the options are submitted data: with no '<' in it, no
+    // value can close the script element
     const colsJson = JSON.stringify(columns.map(c => ({
       type: c.type || 'text',
       options: c.options || []
-    })));
+    }))).replace(/</g, '\\u003c');
 
     return `
       <script>
@@ -246,8 +340,21 @@ class ExtensionTrackerModule {
     const startTime = Date.now();
     const data = req.body;
 
-    if (!data.package || !data.version || !data.fhirVersion) {
-      return res.status(400).json({ error: 'Missing required fields: package, version, fhirVersion' });
+    // The IG Publisher sends a token. It is in the publisher's source, so it is no secret,
+    // but it keeps out anything that isn't trying to look like the publisher
+    if (tokenConfigured(this.config.token)) {
+      const auth = req.get('Authorization') || '';
+      const supplied = auth.replace(/^Bearer\s+/i, '');
+      if (!tokenMatches(this.config.token, supplied)) {
+        return res.status(401).json({ error: 'A valid token is required in the Authorization header' });
+      }
+    }
+
+    const errors = validateSubmission(data);
+    if (errors.length > 0) {
+      // logged, so that a real publisher submission refused by a rule that is too strict is seen
+      console.log(`Extension tracker: refused a submission for ${String(data?.package).substring(0, 100)} from ${req.ip}: ${errors.slice(0, 3).join('; ')}`);
+      return res.status(400).json({ error: 'Not a valid submission', issues: errors });
     }
 
     try {
@@ -695,3 +802,4 @@ class ExtensionTrackerModule {
 }
 
 module.exports = ExtensionTrackerModule;
+module.exports.validateSubmission = validateSubmission;

package/extension-tracker/readme.md

@@ -14,11 +14,14 @@ Tracks extensions, profiles, and extension usage across FHIR Implementation Guid
 
 - **database**: path to the SQLite database file (auto-created if missing)
 - **url** (optional): URL base to mount at (defaults to `/ext-tracker`)
+- **token** (optional): the token a submission must carry, as `Authorization: Bearer <token>`. The IG Publisher sends `9D1C23C0-3915-4542-882E-2BCC55645DF8`. It is in the publisher's source, so it is not a secret, but it keeps out submissions that aren't from the publisher. Without it, submissions need no token
 
 ## POST — Submit IG Data
 
 POST JSON to the module root. Required fields: `package`, `version`, `fhirVersion`. Optional: `jurisdiction`, `extensions`, `profiles`, `usage`.
 
+A submission must look like what the IG Publisher sends, or it is refused (400): no other properties; `package`, `version`, `fhirVersion` and `jurisdiction` are codes; extension, profile and usage keys are URLs; `profiles` is keyed by resource type; usage locations are element paths; titles are text of at most 1024 characters; and no more than 20000 items in all.
+
 ```
 POST /ext-tracker
 Content-Type: application/json

package/library/html-server.js

@@ -70,32 +70,32 @@ class HtmlServer {
     
     // Perform template replacements
     let html = template
-      .replace(/\[%title%\]/g, escape(title))
-      .replace(/\[%content%\]/g, content) // Content is assumed to be already-safe HTML
+      .replace(/\[%title%\]/g, () => escape(title))
+      .replace(/\[%content%\]/g, () => content) // Content is assumed to be already-safe HTML
       // [%ver%] is the FHIRsmith version in every template (it follows the FHIRsmith link)
-      .replace(/\[%ver%\]/g, escape(packageJson.version))
-      .replace(/\[%download-date%\]/g, escape(renderOptions.downloadDate))
+      .replace(/\[%ver%\]/g, () => escape(packageJson.version))
+      .replace(/\[%download-date%\]/g, () => escape(renderOptions.downloadDate))
       // "last updated 35 minutes ago" / "not yet updated", for the crawler-driven modules
-      .replace(/\[%crawler-status%\]/g, escape(renderOptions.crawlerStatus || 'not yet updated'))
-      .replace(/\[%total-resources%\]/g, escape(renderOptions.totalResources.toLocaleString()))
-      .replace(/\[%total-packages%\]/g, escape(renderOptions.totalPackages.toLocaleString()))
-      .replace(/\[%endpoint-path%\]/g, escape(renderOptions.endpointpath))
-      .replace(/\[%fhir-version%\]/g, escape(renderOptions.fhirversion))
-      .replace(/\[%ms%\]/g, escape(renderOptions.processingTime.toString()))
-      .replace(/\[%sponsorMessage%\]/g, sponsorMessage)
-      .replace(/\[%about%\]/g, renderOptions.about || '')
+      .replace(/\[%crawler-status%\]/g, () => escape(renderOptions.crawlerStatus || 'not yet updated'))
+      .replace(/\[%total-resources%\]/g, () => escape(renderOptions.totalResources.toLocaleString()))
+      .replace(/\[%total-packages%\]/g, () => escape(renderOptions.totalPackages.toLocaleString()))
+      .replace(/\[%endpoint-path%\]/g, () => escape(renderOptions.endpointpath))
+      .replace(/\[%fhir-version%\]/g, () => escape(renderOptions.fhirversion))
+      .replace(/\[%ms%\]/g, () => escape(renderOptions.processingTime.toString()))
+      .replace(/\[%sponsorMessage%\]/g, () => sponsorMessage)
+      .replace(/\[%about%\]/g, () => renderOptions.about || '')
       // raw HTML, like [%about%]: the caller decides whether the nav item exists at all
-      .replace(/\[%library-link%\]/g, renderOptions.libraryLink || '')
+      .replace(/\[%library-link%\]/g, () => renderOptions.libraryLink || '')
       // raw HTML too: the OpenAPI description, where a template's module has one in some places only
-      .replace(/\[%api-link%\]/g, renderOptions.apiLink || '')
-      .replace(/\[%api-head%\]/g, renderOptions.apiHead || '');
+      .replace(/\[%api-link%\]/g, () => renderOptions.apiLink || '')
+      .replace(/\[%api-head%\]/g, () => renderOptions.apiHead || '');
     
     // Handle any custom template variables
     if (options.templateVars) {
       for (const [key, value] of Object.entries(options.templateVars)) {
         const placeholder = `[%${key}%]`;
         const escapedValue = typeof value === 'string' ? escape(value) : String(value);
-        html = html.replace(new RegExp(placeholder.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'g'), escapedValue);
+        html = html.replace(new RegExp(placeholder.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'g'), () => escapedValue);
       }
     }
     

package/library/html.js

@@ -1,6 +1,12 @@
 const {validateParameter, validateOptionalParameter} = require("./utilities");
 const escape = require('escape-html');
 
+// Attributes that take a URL, and the schemes that make a URL run script. Browsers ignore
+// leading whitespace and control characters, and embedded tabs and newlines, in the scheme.
+const URL_ATTRIBUTES = new Set(['href', 'src', 'action', 'formaction', 'xlink:href']);
+// eslint-disable-next-line no-control-regex -- control characters are exactly what browsers skip
+const UNSAFE_URL = /^[\s\x00-\x1f]*(j[\s]*a[\s]*v[\s]*a[\s]*s[\s]*c[\s]*r[\s]*i[\s]*p[\s]*t|v[\s]*b[\s]*s[\s]*c[\s]*r[\s]*i[\s]*p[\s]*t|d[\s]*a[\s]*t[\s]*a)[\s]*:/i;
+
 const NodeType = {
   Document: 'Document',
   Element: 'Element',
@@ -25,6 +31,9 @@ class XhtmlNode {
   // Attribute methods
   setAttribute(name, value) {
     if (value != null) {
+      if (URL_ATTRIBUTES.has(String(name).toLowerCase()) && UNSAFE_URL.test(String(value))) {
+        value = '#'; // a link that runs script (javascript:, data:, vbscript:) - from resource content
+      }
       this.attributes.set(name, value);
     }
     return this;

package/library/narrative-check.js

@@ -0,0 +1,203 @@
+//
+// Copyright 2026, Health Intersections Pty Ltd (http://www.healthintersections.com.au)
+//
+// Licensed under BSD-3: https://opensource.org/license/bsd-3-clause
+//
+
+/**
+ * Checks FHIR narrative (and any other XHTML that will be shown in a page) for active
+ * content: anything that can run script, submit or navigate on its own, load another
+ * document, or restyle the page around it.
+ *
+ * FHIR's rule is that narrative "SHALL contain only the basic HTML formatting elements ...,
+ * <a> elements (either name or href), images and internally contained style attributes",
+ * and "SHALL NOT contain a head, a body element, external stylesheet references, deprecated
+ * elements, scripts, forms, base/link/xlink, frames, iframes, objects or event related
+ * attributes". This checks the active-content part of that, not the whole rule.
+ *
+ * The XHTML is parsed the way a browser parses it when it is inserted into a page (parse5
+ * implements the HTML parsing algorithm), so entity-encoded, mixed-case or malformed markup
+ * is checked as the browser would see it, not as it is written.
+ */
+
+const parse5 = require('parse5');
+
+// Elements that run script, load or embed another document, submit data, or change how
+// the page around them is read. svg and math are here because FHIR narrative has no
+// inline graphics (images are <img>), and both can carry script.
+const ACTIVE_ELEMENTS = new Set([
+  'script', 'style', 'link', 'meta', 'base',
+  'iframe', 'frame', 'frameset', 'object', 'embed', 'applet', 'portal', 'template',
+  'form', 'input', 'button', 'select', 'textarea', 'isindex', 'keygen',
+  'svg', 'math', 'head', 'body', 'html'
+]);
+
+// Attributes that hold a URL
+const URL_ATTRIBUTES = new Set([
+  'href', 'src', 'action', 'formaction', 'xlink:href', 'background', 'poster', 'srcset',
+  'data', 'codebase', 'cite', 'longdesc', 'usemap', 'dynsrc', 'lowsrc', 'ping', 'manifest'
+]);
+
+// Attributes that are active whatever their value
+const ACTIVE_ATTRIBUTES = new Set(['srcdoc', 'http-equiv', 'formaction']);
+
+// CSS in a style attribute that runs script or binds behaviour (old IE and Gecko)
+const ACTIVE_CSS = /expression\(|javascript:|vbscript:|-moz-binding|behavior:|@import/;
+
+// The scheme of a URL, as a browser reads it: leading spaces and control characters
+// are ignored, and so are tabs and newlines anywhere
+function urlScheme(url) {
+  // eslint-disable-next-line no-control-regex -- control characters are what browsers strip
+  const cleaned = String(url).replace(/^[\x00-\x20]+/, '').replace(/[\t\n\r]/g, '');
+  const m = /^([a-zA-Z][a-zA-Z0-9+.-]*):/.exec(cleaned);
+  return m ? { scheme: m[1].toLowerCase(), rest: cleaned.substring(m[0].length) } : null;
+}
+
+// Every URL in an attribute value (srcset has several)
+function urlsIn(name, value) {
+  if (name === 'srcset') {
+    return String(value).split(',').map(s => s.trim().split(/\s+/)[0]).filter(Boolean);
+  }
+  return [value];
+}
+
+// CSS with comments removed and escapes decoded, so \65 xpression( is seen as expression(
+function normaliseCss(css) {
+  return String(css)
+    .replace(/\/\*[\s\S]*?\*\//g, '')
+    .replace(/\\([0-9a-fA-F]{1,6})\s?/g, (_, hex) => {
+      const cp = parseInt(hex, 16);
+      return cp > 0 && cp <= 0x10ffff ? String.fromCodePoint(cp) : '';
+    })
+    .replace(/\\(.)/g, '$1')
+    .replace(/\s+/g, '')
+    .toLowerCase();
+}
+
+function describe(node) {
+  return `<${node.tagName}>`;
+}
+
+function checkAttribute(node, attr, problems) {
+  const name = (attr.prefix ? `${attr.prefix}:${attr.name}` : attr.name).toLowerCase();
+  const value = attr.value || '';
+  if (name.startsWith('on')) {
+    problems.push(`an event handler attribute (${name}) on ${describe(node)}`);
+    return;
+  }
+  if (ACTIVE_ATTRIBUTES.has(name)) {
+    problems.push(`a ${name} attribute on ${describe(node)}`);
+    return;
+  }
+  if (name === 'style') {
+    if (ACTIVE_CSS.test(normaliseCss(value))) {
+      problems.push(`script or behaviour in the style attribute of ${describe(node)}`);
+    }
+    return;
+  }
+  if (URL_ATTRIBUTES.has(name)) {
+    for (const url of urlsIn(name, value)) {
+      const s = urlScheme(url);
+      if (!s) {
+        continue;
+      }
+      if (s.scheme === 'javascript' || s.scheme === 'vbscript' || s.scheme === 'livescript') {
+        problems.push(`a ${s.scheme}: URL in the ${name} of ${describe(node)}`);
+      } else if (s.scheme === 'data') {
+        // an inline image is fine: an image can't run script
+        const isImage = node.tagName === 'img' && (name === 'src' || name === 'srcset')
+          && /^image\//i.test(s.rest.trim());
+        if (!isImage) {
+          problems.push(`a data: URL in the ${name} of ${describe(node)}`);
+        }
+      }
+    }
+  }
+}
+
+function walk(node, problems) {
+  if (node.tagName) {
+    if (ACTIVE_ELEMENTS.has(node.tagName.toLowerCase())) {
+      problems.push(`a ${describe(node)} element`);
+    }
+    for (const attr of node.attrs || []) {
+      checkAttribute(node, attr, problems);
+    }
+  }
+  // a <template>'s content is a separate fragment
+  for (const child of [...(node.childNodes || []), ...(node.content ? [node.content] : [])]) {
+    walk(child, problems);
+  }
+}
+
+/**
+ * Checks XHTML for active content.
+ *
+ * @param {string} xhtml - e.g. a narrative's text.div
+ * @returns {string|null} what was found (the first few things, if several), or null if
+ *   there is no active content
+ */
+function checkNarrative(xhtml) {
+  if (xhtml == null || xhtml === '') {
+    return null;
+  }
+  if (typeof xhtml !== 'string') {
+    return 'the narrative is not a string';
+  }
+  const problems = [];
+  walk(parse5.parseFragment(xhtml), problems);
+  if (problems.length === 0) {
+    return null;
+  }
+  const shown = [...new Set(problems)];
+  const more = shown.length > 3 ? ` (and ${shown.length - 3} more)` : '';
+  return `active content in the narrative: ${shown.slice(0, 3).join('; ')}${more}`;
+}
+
+/**
+ * Checks every narrative in a resource: its own, its contained resources', and those of
+ * the resources in a Bundle's entries.
+ *
+ * @param {object} resource - the resource as JSON
+ * @returns {string|null} what was found, with where, or null
+ */
+function checkResourceNarratives(resource) {
+  const check = (res, where) => {
+    if (!res || typeof res !== 'object') {
+      return null;
+    }
+    const found = checkNarrative(res.text?.div);
+    if (found) {
+      return `${where}: ${found}`;
+    }
+    for (const [i, c] of (Array.isArray(res.contained) ? res.contained : []).entries()) {
+      const r = check(c, `${where}.contained[${i}]${c?.id ? ` (#${c.id})` : ''}`);
+      if (r) {
+        return r;
+      }
+    }
+    for (const [i, e] of (Array.isArray(res.entry) ? res.entry : []).entries()) {
+      const r = check(e?.resource, `${where}.entry[${i}]`);
+      if (r) {
+        return r;
+      }
+    }
+    return null;
+  };
+  return check(resource, resource?.resourceType ? `${resource.resourceType}${resource.id ? '/' + resource.id : ''}` : 'resource');
+}
+
+/**
+ * As checkResourceNarratives, but throws.
+ *
+ * @param {object} resource
+ * @param {string} [context] - for the message, e.g. the package it came from
+ */
+function assertNoActiveContent(resource, context) {
+  const found = checkResourceNarratives(resource);
+  if (found) {
+    throw new Error(context ? `${context}: ${found}` : found);
+  }
+}
+
+module.exports = { checkNarrative, checkResourceNarratives, assertNoActiveContent };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fhirsmith",
-  "version": "0.16.1",
+  "version": "0.17.0",
   "txVersion": "1.9.6",
   "description": "A Node.js server that provides a collection of tools to serve the FHIR ecosystem",
   "main": "server.js",
@@ -56,6 +56,7 @@
     "natural": "^8.1.1",
     "node-cron": "^4.6.0",
     "pako": "^2.1.0",
+    "parse5": "^7.3.0",
     "passport": "^0.7.0",
     "passport-facebook": "^3.0.0",
     "passport-github2": "^0.1.12",