fhirsmith 0.18.1 → 1.0.0

package/packages/feed-check.js

@@ -0,0 +1,279 @@
+//
+// Copyright 2026, Health Intersections Pty Ltd (http://www.healthintersections.com.au)
+//
+// Licensed under BSD-3: https://opensource.org/license/bsd-3-clause
+//
+
+/**
+ * The feed check: reads a package feed the way the crawler does, and reports what it finds,
+ * without storing anything. For /packages/feed-check (feed-check-page.js is its HTML).
+ *
+ * For each item, as the crawler would: the guid, title, date and link; whether the registry's
+ * package-restrictions allow the package from this feed; the package itself (downloaded, unpacked
+ * with the crawler's limits, and checked as the crawler checks it before storing); and its
+ * signature, against the keys package-feeds.json lists for the feed. Also whether this registry
+ * already holds the version, and if so whether it is the same bytes. Pages (RFC 5005 next links)
+ * are followed until maxItems items have been checked. Every request goes through the crawler's
+ * SSRF guard.
+ */
+
+const crypto = require('crypto');
+const PackageCrawler = require('./package-crawler');
+
+const MB = 1024 * 1024;
+const QUIET = { info() {}, warn() {}, error() {}, debug() {} };
+
+class FeedCheck {
+  /**
+   * config: the packages module's config (crawler limits, allowPrivateAddresses).
+   * options: master() - the registry's feed list (package-feeds.json), or null; held(id, version)
+   * - {hash} (sha1) of the version if this registry holds it, or null; signing - the feed's
+   * signing information ({required, keys}) to use instead of the registry's, or null; maxItems;
+   * maxTotalMB.
+   */
+  constructor(config, options) {
+    this.config = config;
+    this.master = options.master;
+    this.held = options.held;
+    this.givenSigning = options.signing || null;
+    this.maxItems = options.maxItems;
+    this.maxTotalBytes = options.maxTotalMB * MB;
+  }
+
+  // A crawler that only reads: no database, nothing stored
+  reader() {
+    const c = Object.create(PackageCrawler.prototype);
+    c.config = this.config;
+    c.log = QUIET;
+    c.totalBytes = 0;
+    c.signatureMode = 'check';
+    c.abortController = null;
+    c.skippedFeeds = new Set();
+    // The crawler also reads local files (localFeedDirs). A feed being checked is someone
+    // else's, so everything it links to - pages, packages, signatures - must be http(s)
+    for (const name of ['fetchXml', 'fetchUrl', 'fetchJson']) {
+      const real = PackageCrawler.prototype[name];
+      c[name] = function (url, ...rest) {
+        if (!/^https?:\/\//i.test(String(url))) {
+          return Promise.reject(new Error(`Not fetched: ${url} is not an http(s) URL`));
+        }
+        return real.call(this, url, ...rest);
+      };
+    }
+    return c;
+  }
+
+  /** Checks the feed at url. progress(report) is called as items are checked. Returns the report. */
+  async run(url, progress = () => {}) {
+    const c = this.reader();
+    const feedUrl = c.fixUrl(url);
+    const report = {
+      url, started: new Date().toISOString(), finished: null,
+      registered: null, signing: null, signingSource: null, pages: [], items: [], errors: [], notes: [], truncated: false
+    };
+
+    let master = null;
+    try {
+      master = await this.master();
+    } catch (e) {
+      report.notes.push(`The registry's feed list couldn't be read, so package restrictions and signing keys aren't checked: ${e.message}`);
+    }
+    const entry = (master?.feeds || []).find(f => f && f.url && c.fixUrl(f.url) === feedUrl);
+    const restrictions = master?.['package-restrictions'] || [];
+    if (entry) {
+      report.registered = { name: entry.name || null };
+    } else if (master) {
+      report.notes.push(this.givenSigning
+        ? 'This feed isn\'t in the registry\'s feed list (package-feeds.json), so the crawler doesn\'t read it. Signatures are checked against the keys given.'
+        : 'This feed isn\'t in the registry\'s feed list (package-feeds.json), so the crawler doesn\'t read it, and there are no signing keys to check signatures against.');
+    }
+    // the signing information given with the check, if any, instead of the registry's
+    const signing = this.givenSigning ? c.signingFor(this.givenSigning) : entry ? c.signingFor(entry.signing) : null;
+    if (signing) {
+      report.signing = { required: signing.required, keys: signing.keys.map(k => k.keyid) };
+      report.signingSource = this.givenSigning ? 'given' : 'registry';
+    }
+
+    const seenPages = new Set();
+    const seenTitles = new Set();
+    let pageUrl = feedUrl;
+    while (pageUrl) {
+      if (seenPages.has(pageUrl)) {
+        report.errors.push(`The feed's pages loop: ${pageUrl} is linked as a next page again`);
+        break;
+      }
+      seenPages.add(pageUrl);
+      let xml;
+      try {
+        xml = await c.fetchXml(pageUrl);
+      } catch (e) {
+        report.errors.push(e.message);
+        break;
+      }
+      const channel = xml && xml.rss && xml.rss.channel;
+      if (!channel) {
+        report.errors.push(`${pageUrl} is not an RSS feed (there is no rss/channel)`);
+        break;
+      }
+      const items = Array.isArray(channel.item) ? channel.item : [channel.item].filter(Boolean);
+      report.pages.push({ url: pageUrl, items: items.length });
+      let stopped = false;
+      for (const item of items) {
+        if (report.items.length >= this.maxItems) {
+          report.truncated = true;
+          stopped = true;
+          break;
+        }
+        const result = await this.checkItem(c, item, feedUrl, signing, restrictions, seenTitles);
+        report.items.push(result);
+        progress(report);
+        if (result.rateLimited) {
+          report.errors.push('The feed\'s server is rate limiting requests (HTTP 429), so the check stopped');
+          stopped = true;
+          break;
+        }
+      }
+      if (stopped) {
+        break;
+      }
+      const links = channel['atom:link'] ? (Array.isArray(channel['atom:link']) ? channel['atom:link'] : [channel['atom:link']]) : [];
+      const next = links.find(l => l && l['@_rel'] === 'next' && l['@_href']);
+      pageUrl = next ? c.fixUrl(next['@_href']) : null;
+    }
+    if (report.pages.length > 0 && report.items.length === 0 && report.errors.length === 0) {
+      report.notes.push('The feed has no items');
+    }
+    report.downloadedMB = Math.round(c.totalBytes / MB * 10) / 10;
+    report.finished = new Date().toISOString();
+    return report;
+  }
+
+  async checkItem(c, item, feedUrl, signing, restrictions, seenTitles) {
+    const r = { title: null, guid: null, link: null, date: null, status: 'ok', problems: [], warnings: [], package: null, signature: null, held: null };
+    const text = v => (v && typeof v === 'object' ? v['#text'] : v);
+    r.title = text(item.title) ? String(text(item.title)).trim() : null;
+    r.guid = item.guid && text(item.guid) ? String(text(item.guid)) : null;
+    r.link = text(item.link) ? String(text(item.link)).trim() : null;
+    const done = () => {
+      r.status = r.skipped ? 'skipped' : r.problems.length > 0 ? 'error' : 'ok';
+      return r;
+    };
+
+    if (!r.guid) {
+      r.problems.push('There is no guid, so the crawler can\'t process this item');
+    }
+    if (!r.title) {
+      r.problems.push('There is no title (it should be {id}#{version})');
+      return done();
+    }
+    if (!/^[^#\s]+#[^#\s]+$/.test(r.title)) {
+      r.warnings.push(`The title isn't {id}#{version}: ${r.title}`);
+    }
+    if (text(item.notForPublication) === 'true' || text(item.notForPublication) === true) {
+      r.skipped = 'The item is marked notForPublication, so the crawler ignores it';
+      return done();
+    }
+    const allowed = c.isPackageAllowed(r.title, feedUrl, restrictions);
+    if (!allowed.allowed) {
+      r.problems.push(`The registry doesn't allow ${r.title.split('#')[0]} from this feed (it may come from ${allowed.allowedFeeds})`);
+    }
+    if (seenTitles.has(r.title)) {
+      r.warnings.push('This version is listed more than once in the feed; the crawler only takes the first');
+    }
+    seenTitles.add(r.title);
+    let date = null;
+    try {
+      date = c.parsePubDate(text(item.pubDate));
+      r.date = date.toISOString();
+    } catch (e) {
+      r.problems.push(`The pubDate isn't a valid date: ${text(item.pubDate) || '(missing)'}`);
+    }
+    if (!r.link) {
+      r.problems.push('There is no link to the package');
+      return done();
+    }
+    if (c.totalBytes >= this.maxTotalBytes) {
+      r.skipped = `Not downloaded: the check has already downloaded ${this.maxTotalBytes / MB} MB, its limit`;
+      return done();
+    }
+
+    let buf;
+    try {
+      buf = await c.fetchUrl(c.fixUrl(r.link));
+    } catch (e) {
+      r.problems.push(e.message);
+      r.rateLimited = e.message.includes('RATE_LIMITED');
+      return done();
+    }
+    let npm;
+    try {
+      npm = await c.extractNpmPackage(buf, `${feedUrl}#${r.guid}`);
+    } catch (e) {
+      r.problems.push(`The package can't be read: ${e.message}`);
+      return done();
+    }
+    r.package = {
+      id: npm.id, version: npm.version, fhirVersions: npm.fhirVersionList || null,
+      canonical: npm.canonical || null, sizeKB: Math.round(buf.length / 1024)
+    };
+    if (`${npm.id}#${npm.version}` !== r.title) {
+      r.warnings.push(`The feed says ${r.title}, but the package is ${npm.id}#${npm.version}; the crawler goes by the package`);
+    }
+    try {
+      c.checkPackageContent(npm, r.title, feedUrl);
+    } catch (e) {
+      r.problems.push(e.message);
+    }
+
+    // its signature
+    const sigUrl = c.signatureUrl(item);
+    if (signing) {
+      const itemLog = {};
+      let signature;
+      try {
+        signature = await c.fetchSignature(item);
+      } catch (e) {
+        signature = { url: sigUrl, fetchError: e.message };
+      }
+      const verdict = c.checkSignature(signing, signature, buf, npm.id, npm.version, date, itemLog);
+      const s = itemLog.signature || '';
+      r.signature = {
+        url: sigUrl,
+        state: s.startsWith('valid') ? 'confirmed' : s === 'unsigned' ? 'absent' : s.startsWith('invalid') ? 'rejected' : 'unfetchable',
+        detail: s
+      };
+      if (verdict.refuse) {
+        r.problems.push(`The crawler would refuse this package: ${verdict.refuse}`);
+      }
+    } else if (sigUrl) {
+      r.signature = { url: sigUrl, state: 'unchecked', detail: 'Not checked: there are no keys for this feed in the registry\'s feed list' };
+      try {
+        const signature = await c.fetchSignature(item);
+        if (signature.fetchError) {
+          r.signature.detail += `; and it couldn't be fetched: ${signature.fetchError}`;
+        } else {
+          const keyid = JSON.parse(signature.text)?.verificationMaterial?.publicKey?.hint;
+          if (keyid) {
+            r.signature.detail += `; it says it was signed with ${keyid}`;
+          }
+        }
+      } catch (e) {
+        r.signature.detail += `; and it couldn't be read: ${e.message}`;
+      }
+    } else {
+      r.signature = { url: null, state: 'absent', detail: 'The item has no fhir:signature' };
+    }
+
+    // whether this registry already has it
+    try {
+      const h = await this.held(npm.id, npm.version);
+      const sha1 = crypto.createHash('sha1').update(buf).digest('hex');
+      r.held = !h ? 'no' : h.hash === sha1 ? 'yes, the same bytes' : 'yes, but different bytes';
+    } catch (e) {
+      r.held = null;
+    }
+    return done();
+  }
+}
+
+module.exports = { FeedCheck };

package/packages/npm-check.js

@@ -18,14 +18,19 @@
  * Used by /packages/npm-check (a report on any registry) and by the test suites
  * tests/packages/npm-registry*.test.js, so all of them run the same checks.
  *
+ * A registry need not sign packages, but one that lists keys must sign every version with
+ * them: that is what `npm audit signatures` checks.
+ *
  * References:
  *   https://github.com/npm/registry/blob/main/docs/REGISTRY-API.md
  *   https://github.com/npm/registry/blob/main/docs/responses/package-metadata.md
+ *   https://docs.npmjs.com/about-registry-signatures
  */
 
 const crypto = require('crypto');
 const zlib = require('zlib');
 const axios = require('axios');
+const { verifySignature } = require('./npm-signing');
 
 // What the npm CLI sends when it fetches a package document
 const NPM_ACCEPT = 'application/vnd.npm.install-v1+json; q=1.0, application/json; q=0.8, */*';
@@ -40,7 +45,8 @@ const STEPS = [
   { id: 'search', title: '1. Search', request: 'GET /-/v1/search?text={name}' },
   { id: 'package', title: '2. Package document', request: 'GET /{name}' },
   { id: 'version', title: '3. Version document', request: 'GET /{name}/{version}' },
-  { id: 'tarball', title: '4. Tarball', request: 'GET {dist.tarball}' }
+  { id: 'tarball', title: '4. Tarball', request: 'GET {dist.tarball}' },
+  { id: 'signatures', title: '5. Signatures', request: 'GET /-/npm/v1/keys' }
 ];
 
 // A check's failure, with a message for people
@@ -302,6 +308,53 @@ const CHECKS = [
       c.eq(manifest.name, c.pkg, 'package.json name');
       c.eq(manifest.version, c.version, 'package.json version');
     }
+  },
+
+  // 5. signatures
+  {
+    step: 'signatures', uses: ['keys'], title: 'the registry\'s keys are a 404 (it doesn\'t sign) or a list of ECDSA P-256 public keys',
+    run(c) {
+      if (c.response('keys').status === 404) {
+        return;
+      }
+      c.status('keys', 200);
+      const keys = c.json('keys').keys;
+      c.ok(Array.isArray(keys) && keys.length > 0, 'keys is not a non-empty array');
+      keys.forEach((k, i) => {
+        c.ok(typeof k.keyid === 'string' && k.keyid.length > 0, `keys[${i}]: keyid is not a string`);
+        c.eq(k.keytype, 'ecdsa-sha2-nistp256', `keys[${i}].keytype`);
+        c.eq(k.scheme, 'ecdsa-sha2-nistp256', `keys[${i}].scheme`);
+        c.ok(k.expires === null || k.expires === undefined || isDate(k.expires), `keys[${i}]: expires is not null or a date: ${show(k.expires)}`);
+        try {
+          crypto.createPublicKey({ key: Buffer.from(k.key, 'base64'), format: 'der', type: 'spki' });
+        } catch (e) {
+          c.fail(`keys[${i}]: key is not a base64 SPKI public key: ${e.message}`);
+        }
+      });
+    }
+  },
+  {
+    step: 'signatures', uses: ['keys', 'packument', 'fullPackument'], title: 'if it has keys, every version is signed with one that was in force when it was published',
+    run(c) {
+      if (c.response('keys').status === 404) {
+        return;
+      }
+      const keys = c.json('keys').keys || [];
+      const doc = c.json('packument');
+      const time = c.json('fullPackument').time || {};
+      for (const [v, man] of Object.entries(doc.versions || {})) {
+        const dist = man.dist || {};
+        c.ok(SRI.test(dist.integrity || ''), `versions.${v}: no dist.integrity to sign`);
+        c.ok(Array.isArray(dist.signatures) && dist.signatures.length > 0, `versions.${v}: no dist.signatures`);
+        // as npm: a signature by any listed key will do
+        const good = dist.signatures.find(sig => {
+          const key = keys.find(k => k.keyid === sig.keyid);
+          return key && (!key.expires || Date.parse(time[v]) < Date.parse(key.expires)) &&
+            verifySignature(key, man.name, v, dist.integrity, sig.sig);
+        });
+        c.ok(good, `versions.${v}: no signature verifies against a key in force at ${time[v] || 'its (unknown) publication time'} (keyids ${dist.signatures.map(sig => sig.keyid).join(', ')})`);
+      }
+    }
   }
 ];
 
@@ -396,7 +449,7 @@ async function runNpmCheck(target, get) {
   const started = new Date();
   const search = extra => get(`${base}/-/v1/search?text=${encodeURIComponent(pkg)}${extra}`);
   const r = {};
-  [r.search, r.searchSize1, r.searchFrom1, r.packument, r.fullPackument, r.versionDoc, r.latestDoc, r.missing, r.missingVersion] = await Promise.all([
+  [r.search, r.searchSize1, r.searchFrom1, r.packument, r.fullPackument, r.versionDoc, r.latestDoc, r.missing, r.missingVersion, r.keys] = await Promise.all([
     search(`&size=${SEARCH_SIZE}`),
     search('&size=1'),
     search(`&size=${SEARCH_SIZE}&from=1`),
@@ -405,7 +458,8 @@ async function runNpmCheck(target, get) {
     get(packageUrl(base, pkg, version)),
     get(packageUrl(base, pkg, 'latest')),
     get(packageUrl(base, MISSING_PACKAGE)),
-    get(packageUrl(base, pkg, '99999.0.0'))
+    get(packageUrl(base, pkg, '99999.0.0')),
+    get(`${base}/-/npm/v1/keys`)
   ]);
   if (r.packument.status === 200) {
     try {

package/packages/npm-signing.js

@@ -0,0 +1,219 @@
+//
+// Copyright 2026, Health Intersections Pty Ltd (http://www.healthintersections.com.au)
+//
+// Licensed under BSD-3: https://opensource.org/license/bsd-3-clause
+//
+
+/**
+ * npm registry signatures.
+ *
+ * A registry signature says "this registry served name@version with this integrity". It is
+ * the registry's statement, not the publisher's, so it can be made for every package this
+ * server holds, wherever it was crawled from. npm checks them with `npm audit signatures`:
+ *
+ *   - GET {registry}/-/npm/v1/keys lists the registry's public keys. A registry without it
+ *     (a 404) is one that doesn't sign, and npm skips its packages.
+ *   - each version's dist.signatures is [{ keyid, sig }], where sig is the base64 DER ECDSA
+ *     P-256 / SHA-256 signature of `${name}@${version}:${dist.integrity}`, and
+ *     dist.integrity is the sha512 SRI string of the tarball.
+ *   - once a registry lists keys, a version with no signature (or a bad one) is an error.
+ *
+ * References:
+ *   https://docs.npmjs.com/about-registry-signatures
+ *   https://github.com/npm/cli/blob/latest/lib/utils/verify-signatures.js
+ *   https://github.com/npm/pacote/blob/main/lib/registry.js (verifySignatures)
+ */
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+
+const KEY_TYPE = 'ecdsa-sha2-nistp256';
+const HASH_SLICE = 4 * 1024 * 1024;
+
+// The message a registry signature is over
+function signedMessage(name, version, integrity) {
+  return `${name}@${version}:${integrity}`;
+}
+
+// sha512 SRI string of a tarball. Hashed in slices, yielding between them, so a large
+// package doesn't hold up the event loop.
+async function integrityOf(buffer) {
+  const hash = crypto.createHash('sha512');
+  for (let i = 0; i < buffer.length; i += HASH_SLICE) {
+    hash.update(buffer.subarray(i, i + HASH_SLICE));
+    if (i + HASH_SLICE < buffer.length) {
+      await new Promise(resolve => setImmediate(resolve));
+    }
+  }
+  return 'sha512-' + hash.digest('base64');
+}
+
+// The same, synchronously
+function integrityOfSync(buffer) {
+  return 'sha512-' + crypto.createHash('sha512').update(buffer).digest('base64');
+}
+
+// npm's key id: SHA256: and the base64 sha256 of the public key (SPKI DER)
+function keyIdOf(spkiDer) {
+  return 'SHA256:' + crypto.createHash('sha256').update(spkiDer).digest('base64');
+}
+
+// Checks a signature the way npm does (pacote's verifySignatures): key is an entry from
+// /-/npm/v1/keys. Returns true or false.
+function verifySignature(key, name, version, integrity, sig) {
+  try {
+    const pem = `-----BEGIN PUBLIC KEY-----\n${key.key}\n-----END PUBLIC KEY-----`;
+    const verifier = crypto.createVerify('SHA256');
+    verifier.write(signedMessage(name, version, integrity));
+    verifier.end();
+    return verifier.verify(pem, sig, 'base64');
+  } catch (e) {
+    return false;
+  }
+}
+
+class NpmSigner {
+  constructor(privateKey) {
+    const details = privateKey.asymmetricKeyDetails || {};
+    if (privateKey.asymmetricKeyType !== 'ec' || details.namedCurve !== 'prime256v1') {
+      throw new Error(`An npm signing key must be an EC P-256 (prime256v1) key; this one is ${privateKey.asymmetricKeyType} ${details.namedCurve || ''}`.trim());
+    }
+    this.privateKey = privateKey;
+    const der = crypto.createPublicKey(privateKey).export({ type: 'spki', format: 'der' });
+    this.publicKey = der.toString('base64');
+    this.keyid = keyIdOf(der);
+  }
+
+  /**
+   * The signing key in file (PEM, PKCS#8 or SEC1). If there is no file, a new key is made and
+   * saved there, readable only by this user. log is told when a key is made.
+   */
+  static load(file, log) {
+    if (!fs.existsSync(file)) {
+      const { privateKey } = crypto.generateKeyPairSync('ec', { namedCurve: 'prime256v1' });
+      fs.mkdirSync(path.dirname(file), { recursive: true });
+      try {
+        // wx: never replace a key that appeared meanwhile
+        fs.writeFileSync(file, privateKey.export({ type: 'pkcs8', format: 'pem' }), { mode: 0o600, flag: 'wx' });
+        log?.info?.(`Made a new npm signing key: ${file}`);
+      } catch (e) {
+        if (e.code !== 'EEXIST') {
+          throw e;
+        }
+      }
+    }
+    return new NpmSigner(crypto.createPrivateKey(fs.readFileSync(file)));
+  }
+
+  // The body of /-/npm/v1/keys
+  keysDocument() {
+    return {
+      keys: [{
+        expires: null,
+        keyid: this.keyid,
+        keytype: KEY_TYPE,
+        scheme: KEY_TYPE,
+        key: this.publicKey
+      }]
+    };
+  }
+
+  // The base64 DER signature for name@version with this integrity
+  sign(name, version, integrity) {
+    return crypto.sign('sha256', Buffer.from(signedMessage(name, version, integrity), 'utf8'), this.privateKey).toString('base64');
+  }
+}
+
+// --- publisher signatures ------------------------------------------------------------------------
+//
+// A publisher (the IG Publisher, org.hl7.fhir.utilities.npm.NpmPackageSigner) signs a package with a
+// partner file, {package}.tgz.sigstore.json, and its feed links it from the item (fhir:signature).
+// The file is a Sigstore bundle (v0.3) holding a DSSE envelope whose payload is an in-toto statement
+// with one subject: the package's purl (pkg:npm/{name}@{version}) and the sha512 of the .tgz. The
+// signature is ECDSA P-256 / SHA-256 (DER) over the DSSE pre-authentication encoding of the payload.
+// Which keys may sign a feed's packages is in package-feeds.json (feeds[].signing.keys).
+
+const BUNDLE_MEDIA_TYPE = 'application/vnd.dev.sigstore.bundle';
+const IN_TOTO_PAYLOAD = 'application/vnd.in-toto+json';
+const IN_TOTO_STATEMENT = 'https://in-toto.io/Statement/v1';
+
+// The npm package URL of a package version
+function purl(name, version) {
+  return 'pkg:npm/' + (name.startsWith('@') ? '%40' + name.substring(1) : name) + '@' + version;
+}
+
+// DSSE pre-authentication encoding: "DSSEv1" SP LEN(type) SP type SP LEN(body) SP body
+function pae(payloadType, payload) {
+  const type = Buffer.from(payloadType, 'utf8');
+  return Buffer.concat([Buffer.from(`DSSEv1 ${type.length} ${payloadType} ${payload.length} `, 'utf8'), payload]);
+}
+
+/**
+ * Checks a publisher's signature of a package. tgz is the package's bytes; bundle the parsed
+ * partner file; keys the feed's keys ([{keyid, key, expires}], key: base64 SPKI DER); name and
+ * version the package's own (from its package.json); publishedAt when it was published (a key
+ * that had expired by then doesn't count), or null. Returns {keyid, signedAt}; throws an Error
+ * saying what is wrong.
+ */
+function verifyPackageSignature(tgz, bundle, keys, name, version, publishedAt) {
+  if (!bundle || typeof bundle !== 'object' || typeof bundle.mediaType !== 'string' || !bundle.mediaType.startsWith(BUNDLE_MEDIA_TYPE)) {
+    throw new Error('not a Sigstore bundle');
+  }
+  const envelope = bundle.dsseEnvelope;
+  if (!envelope || envelope.payloadType !== IN_TOTO_PAYLOAD || typeof envelope.payload !== 'string') {
+    throw new Error('the bundle has no in-toto DSSE envelope');
+  }
+  const payload = Buffer.from(envelope.payload, 'base64');
+  const hint = bundle.verificationMaterial?.publicKey?.hint;
+  const signed = pae(IN_TOTO_PAYLOAD, payload);
+  const tried = [];
+  let signedBy = null;
+  for (const sig of Array.isArray(envelope.signatures) ? envelope.signatures : []) {
+    const keyid = sig.keyid || hint;
+    tried.push(keyid);
+    const key = (keys || []).find(k => k.keyid === keyid);
+    if (!key || typeof sig.sig !== 'string') {
+      continue;
+    }
+    if (key.expires && publishedAt && !(publishedAt.getTime() < Date.parse(key.expires))) {
+      continue;
+    }
+    try {
+      const ok = crypto.verify('sha256', signed,
+        { key: Buffer.from(key.key, 'base64'), format: 'der', type: 'spki' }, Buffer.from(sig.sig, 'base64'));
+      if (ok) {
+        signedBy = keyid;
+        break;
+      }
+    } catch (e) {
+      // a malformed key or signature: not this one
+    }
+  }
+  if (!signedBy) {
+    throw new Error(tried.length === 0 ? 'the bundle has no signatures'
+      : `no signature verifies against a key this feed lists (signed by ${tried.join(', ')})`);
+  }
+  let statement;
+  try {
+    statement = JSON.parse(payload.toString('utf8'));
+  } catch (e) {
+    throw new Error('the signed payload is not JSON');
+  }
+  if (statement._type !== IN_TOTO_STATEMENT) {
+    throw new Error(`the signed payload is not an in-toto v1 statement (_type is ${statement._type})`);
+  }
+  const expected = purl(name, version);
+  const digest = crypto.createHash('sha512').update(tgz).digest('hex');
+  const subjects = Array.isArray(statement.subject) ? statement.subject : [];
+  const named = subjects.filter(s => s && s.name === expected);
+  if (named.length === 0) {
+    throw new Error(`the signature is not for ${expected} (it is for ${subjects.map(s => s && s.name).join(', ') || 'nothing'})`);
+  }
+  if (!named.some(s => typeof s.digest?.sha512 === 'string' && s.digest.sha512.toLowerCase() === digest)) {
+    throw new Error('the signature is for different content: the package\'s sha512 doesn\'t match');
+  }
+  return { keyid: signedBy, signedAt: statement.predicate?.signedAt || null };
+}
+
+module.exports = { NpmSigner, integrityOf, integrityOfSync, verifySignature, signedMessage, keyIdOf, verifyPackageSignature, purl, pae };