@opentermsarchive/engine 14.1.0 → 15.1.0

package/src/archivist/recorder/repositories/git/index.test.js

@@ -400,6 +400,59 @@ describe('GitRepository', () => {
           expect(await subject.findById('inexistantID')).to.equal(null);
         });
       });
+
+      context('when the requested ID is well formed but absent from the repository', () => {
+        it('returns null rather than throwing a "bad object" error', async () => {
+          expect(await subject.findById('ecd9407eb26b1bf0613186175ee80edbdeedd47f')).to.equal(null);
+        });
+      });
+
+      context('when the requested ID could be interpreted as a git option', () => {
+        const INJECTION_PROOF_FILE_PATH = path.resolve(__dirname, 'findById-argument-injection-proof.txt');
+
+        after(() => fs.rmSync(INJECTION_PROOF_FILE_PATH, { force: true }));
+
+        it('returns null without letting the ID reach git as an argument', async () => {
+          expect(await subject.findById(`--output=${INJECTION_PROOF_FILE_PATH}`)).to.equal(null);
+          expect(fs.existsSync(INJECTION_PROOF_FILE_PATH), 'a version ID must never be interpreted as a git option').to.be.false;
+        });
+      });
+    });
+
+    describe('#findMetadataById', () => {
+      let id;
+
+      before(async () => {
+        ({ id } = await subject.save(new Version({
+          serviceId: SERVICE_PROVIDER_ID,
+          termsType: TERMS_TYPE,
+          content: CONTENT,
+          fetchDate: FETCH_DATE,
+          snapshotIds: [SNAPSHOT_ID],
+          mimeType: HTML_MIME_TYPE,
+          metadata: METADATA,
+        })));
+      });
+
+      after(() => subject.removeAll());
+
+      it('returns the record', async () => {
+        const record = await subject.findMetadataById(id);
+
+        expect(record).to.be.an.instanceof(Version);
+        expect(record.id).to.include(id);
+      });
+
+      context('when the requested ID could be interpreted as a git option', () => {
+        const INJECTION_PROOF_FILE_PATH = path.resolve(__dirname, 'findMetadataById-argument-injection-proof.txt');
+
+        after(() => fs.rmSync(INJECTION_PROOF_FILE_PATH, { force: true }));
+
+        it('returns null without letting the ID reach git as an argument', async () => {
+          expect(await subject.findMetadataById(`--output=${INJECTION_PROOF_FILE_PATH}`)).to.equal(null);
+          expect(fs.existsSync(INJECTION_PROOF_FILE_PATH), 'a version ID must never be interpreted as a git option').to.be.false;
+        });
+      });
     });
 
     describe('#findByDate', () => {
@@ -485,6 +538,37 @@ describe('GitRepository', () => {
           expect(record.metadata).to.deep.equal(METADATA);
         });
       });
+
+      context('when the service ID is a git argument injection attempt', () => {
+        const INJECTION_PROOF_FILE_PATH = path.resolve(__dirname, 'findByDate-argument-injection-proof.*');
+
+        before(async () => {
+          await subject.save(new Version({
+            serviceId: SERVICE_PROVIDER_ID,
+            termsType: TERMS_TYPE,
+            content: CONTENT,
+            fetchDate: FETCH_DATE,
+            snapshotIds: [SNAPSHOT_ID],
+          }));
+        });
+
+        after(async () => {
+          fs.rmSync(INJECTION_PROOF_FILE_PATH, { force: true });
+          await subject.removeAll();
+        });
+
+        it('treats the service ID as a path so it cannot reach git as an option', async () => {
+          await subject.findByDate(`--output=${__dirname}`, 'findByDate-argument-injection-proof', FETCH_DATE_LATER);
+
+          expect(fs.existsSync(INJECTION_PROOF_FILE_PATH), 'a service ID must never be interpreted as a git option').to.be.false;
+        });
+      });
+
+      context('when the service ID is a path traversal attempt', () => {
+        it('returns null instead of erroring', async () => {
+          expect(await subject.findByDate('../../outside', TERMS_TYPE, FETCH_DATE)).to.equal(null);
+        });
+      });
     });
 
     describe('#findAll', () => {
@@ -645,6 +729,13 @@ describe('GitRepository', () => {
         });
       });
 
+      context('when the service ID or terms type is a path traversal attempt', () => {
+        it('returns an empty array instead of erroring', async () => {
+          expect(await subject.findByServiceAndTermsType('../../outside', TERMS_TYPE)).to.be.an('array').that.is.empty;
+          expect(await subject.findByServiceAndTermsType(SERVICE_PROVIDER_ID, '../../outside')).to.be.an('array').that.is.empty;
+        });
+      });
+
       context('with includeTechnicalUpgrades: false', () => {
         let filteredRecords;
         let technicalUpgradeId;
@@ -761,6 +852,12 @@ describe('GitRepository', () => {
         });
       });
 
+      context('when the service ID is a path traversal attempt', () => {
+        it('returns an empty array instead of erroring', async () => {
+          expect(await subject.findByService('../../outside')).to.be.an('array').that.is.empty;
+        });
+      });
+
       context('with includeTechnicalUpgrades: false', () => {
         let filteredRecords;
         let technicalUpgradeId;
@@ -842,6 +939,12 @@ describe('GitRepository', () => {
         });
       });
 
+      context('when the service ID is a path traversal attempt', () => {
+        it('returns zero instead of erroring', async () => {
+          expect(await subject.count('../../outside', TERMS_TYPE)).to.equal(0);
+        });
+      });
+
       context('with only serviceId filter', () => {
         it('returns count for all terms types of a service', async () => {
           // Add a version with different terms type
@@ -860,6 +963,167 @@ describe('GitRepository', () => {
       });
     });
 
+    describe('#getNavigationIds', () => {
+      let firstVersion;
+      let middleVersion;
+      let lastVersion;
+
+      before(async function () {
+        this.timeout(5000);
+
+        firstVersion = await subject.save(new Version({
+          serviceId: SERVICE_PROVIDER_ID,
+          termsType: TERMS_TYPE,
+          content: 'first content',
+          fetchDate: FETCH_DATE_EARLIER,
+          snapshotIds: [SNAPSHOT_ID],
+        }));
+
+        middleVersion = await subject.save(new Version({
+          serviceId: SERVICE_PROVIDER_ID,
+          termsType: TERMS_TYPE,
+          content: 'middle content',
+          fetchDate: FETCH_DATE,
+          snapshotIds: [SNAPSHOT_ID],
+        }));
+
+        lastVersion = await subject.save(new Version({
+          serviceId: SERVICE_PROVIDER_ID,
+          termsType: TERMS_TYPE,
+          content: 'last content',
+          fetchDate: FETCH_DATE_LATER,
+          snapshotIds: [SNAPSHOT_ID],
+        }));
+      });
+
+      after(() => subject.removeAll());
+
+      context('for the oldest version', () => {
+        let navigationIds;
+
+        before(async () => { navigationIds = await subject.getNavigationIds(SERVICE_PROVIDER_ID, TERMS_TYPE, firstVersion.id); });
+
+        it('has no previous version', () => expect(navigationIds.prev).to.be.null);
+        it('points to the next version', () => expect(navigationIds.next).to.equal(middleVersion.id));
+        it('points to itself as first', () => expect(navigationIds.first).to.equal(firstVersion.id));
+        it('points to the newest version as last', () => expect(navigationIds.last).to.equal(lastVersion.id));
+      });
+
+      context('for a middle version', () => {
+        let navigationIds;
+
+        before(async () => { navigationIds = await subject.getNavigationIds(SERVICE_PROVIDER_ID, TERMS_TYPE, middleVersion.id); });
+
+        it('points to the previous version', () => expect(navigationIds.prev).to.equal(firstVersion.id));
+        it('points to the next version', () => expect(navigationIds.next).to.equal(lastVersion.id));
+        it('points to the oldest version as first', () => expect(navigationIds.first).to.equal(firstVersion.id));
+        it('points to the newest version as last', () => expect(navigationIds.last).to.equal(lastVersion.id));
+      });
+
+      context('for the newest version', () => {
+        let navigationIds;
+
+        before(async () => { navigationIds = await subject.getNavigationIds(SERVICE_PROVIDER_ID, TERMS_TYPE, lastVersion.id); });
+
+        it('points to the previous version', () => expect(navigationIds.prev).to.equal(middleVersion.id));
+        it('has no next version', () => expect(navigationIds.next).to.be.null);
+        it('points to itself as last', () => expect(navigationIds.last).to.equal(lastVersion.id));
+      });
+
+      context('when the version does not exist', () => {
+        it('returns only null IDs', async () => {
+          expect(await subject.getNavigationIds(SERVICE_PROVIDER_ID, TERMS_TYPE, 'ffffffffffffffffffffffffffffffffffffffff')).to.deep.equal({ first: null, prev: null, next: null, last: null });
+        });
+      });
+
+      context('when the service ID is a path traversal attempt', () => {
+        it('returns only null IDs instead of erroring', async () => {
+          expect(await subject.getNavigationIds('../../outside', TERMS_TYPE, firstVersion.id)).to.deep.equal({ first: null, prev: null, next: null, last: null });
+        });
+      });
+
+      context('when a technical upgrade is recorded out of chronological order', () => {
+        // A technical upgrade re-renders an old snapshot: it carries an OLD fetch date but is committed last (topologically recent).
+        // The previous implementation mixed chronological (findPrevious) and topological (findNext) order, so prev/next disagreed here.
+        // The navigation IDs are now derived from a single chronological order, so they stay exact inverses.
+        const TECHNICAL_UPGRADE_DATE = new Date('2000-01-01T09:00:00.000Z'); // between firstVersion (06:00) and middleVersion (12:00)
+        let technicalUpgrade;
+
+        before(async () => {
+          technicalUpgrade = await subject.save(new Version({
+            serviceId: SERVICE_PROVIDER_ID,
+            termsType: TERMS_TYPE,
+            content: 'technical upgrade content',
+            fetchDate: TECHNICAL_UPGRADE_DATE,
+            isTechnicalUpgrade: true,
+            snapshotIds: [SNAPSHOT_ID],
+          }));
+        });
+
+        it('orders it by its fetch date, not its commit position', async () => {
+          const navigationIds = await subject.getNavigationIds(SERVICE_PROVIDER_ID, TERMS_TYPE, technicalUpgrade.id);
+
+          expect(navigationIds.prev).to.equal(firstVersion.id);
+          expect(navigationIds.next).to.equal(middleVersion.id);
+        });
+
+        it('keeps prev and next as exact inverses (round-trips)', async () => {
+          const fromFirst = await subject.getNavigationIds(SERVICE_PROVIDER_ID, TERMS_TYPE, firstVersion.id);
+
+          expect(fromFirst.next).to.equal(technicalUpgrade.id);
+
+          const backFromUpgrade = await subject.getNavigationIds(SERVICE_PROVIDER_ID, TERMS_TYPE, fromFirst.next);
+
+          expect(backFromUpgrade.prev).to.equal(firstVersion.id);
+        });
+
+        it('can exclude technical upgrades from the sequence', async () => {
+          const navigationIds = await subject.getNavigationIds(SERVICE_PROVIDER_ID, TERMS_TYPE, firstVersion.id, { includeTechnicalUpgrades: false });
+
+          expect(navigationIds.next).to.equal(middleVersion.id);
+        });
+      });
+    });
+
+    describe('#getNavigationIds with versions sharing the same fetch date', () => {
+      // Git stores commit dates at second precision, so distinct versions can share a fetch date.
+      // The record ID tiebreaker must keep the order deterministic so prev/next still round-trip.
+      let ids;
+
+      before(async function () {
+        this.timeout(5000);
+        ids = [];
+        for (const content of [ 'tie A', 'tie B', 'tie C' ]) {
+          ids.push((await subject.save(new Version({ serviceId: SERVICE_PROVIDER_ID, termsType: TERMS_TYPE, content, fetchDate: FETCH_DATE, snapshotIds: [SNAPSHOT_ID] }))).id);
+        }
+      });
+
+      after(() => subject.removeAll());
+
+      it('round-trips next then prev for every version', async () => {
+        for (const id of ids) {
+          const navigationIds = await subject.getNavigationIds(SERVICE_PROVIDER_ID, TERMS_TYPE, id);
+
+          if (navigationIds.next) {
+            expect((await subject.getNavigationIds(SERVICE_PROVIDER_ID, TERMS_TYPE, navigationIds.next)).prev).to.equal(id);
+          }
+        }
+      });
+
+      it('exposes all three versions as a single ordered chain', async () => {
+        const head = await subject.getNavigationIds(SERVICE_PROVIDER_ID, TERMS_TYPE, ids[0]);
+        const walked = new Set([head.first]);
+        let cursor = head.first;
+
+        while (cursor) {
+          walked.add(cursor);
+          cursor = (await subject.getNavigationIds(SERVICE_PROVIDER_ID, TERMS_TYPE, cursor)).next;
+        }
+
+        expect(walked).to.have.lengthOf(ids.length);
+      });
+    });
+
     describe('#findLatest', () => {
       context('when there are records for the given service', () => {
         let lastSnapshotId;
@@ -920,6 +1184,30 @@ describe('GitRepository', () => {
           expect(latestRecord).to.equal(null);
         });
       });
+
+      context('when the service ID could be interpreted as a git option', () => {
+        before(async () => {
+          await subject.save(new Version({
+            serviceId: SERVICE_PROVIDER_ID,
+            termsType: TERMS_TYPE,
+            content: CONTENT,
+            fetchDate: FETCH_DATE,
+            snapshotIds: [SNAPSHOT_ID],
+          }));
+        });
+
+        after(() => subject.removeAll());
+
+        it('treats the service ID as a path and returns null instead of erroring', async () => {
+          expect(await subject.findLatest('--not-a-git-option', TERMS_TYPE)).to.equal(null);
+        });
+      });
+
+      context('when the service ID is a path traversal attempt', () => {
+        it('returns null instead of erroring', async () => {
+          expect(await subject.findLatest('../../outside', TERMS_TYPE)).to.equal(null);
+        });
+      });
     });
 
     describe('#iterate', () => {

package/src/archivist/recorder/repositories/interface.js

@@ -69,6 +69,15 @@ class RepositoryInterface {
     throw new Error(`#findById method is not implemented in ${this.constructor.name}`);
   }
 
+  /**
+   * Find the metadata of the record that matches the given record ID, without loading its content
+   * @param   {string}          recordId - Record ID of the record to find
+   * @returns {Promise<Record>}          Promise that will be resolved with the found record (without content) or null if none match the given ID
+   */
+  async findMetadataById(recordId) {
+    throw new Error(`#findMetadataById method is not implemented in ${this.constructor.name}`);
+  }
+
   /**
    * Find all records, in descending chronological order (newest first; opposite of #iterate)
    * For performance reasons, the content of the records will not be loaded by default. Use #loadRecordContent to load the content of individual records
@@ -99,6 +108,20 @@ class RepositoryInterface {
     throw new Error(`#findByService method is not implemented in ${this.constructor.name}`);
   }
 
+  /**
+   * Get the IDs locating a version within the history of its terms: the first (oldest) and last (newest) versions, as well as the immediately previous (older) and next (newer) ones
+   * These IDs are computed from a single deterministic chronological order (by fetch date, with the record ID as a stable tiebreaker), so navigating prev/next always round-trips
+   * @param   {string}                                                                 serviceId                          - Service ID of the version
+   * @param   {string}                                                                 termsType                          - Terms type of the version
+   * @param   {string}                                                                 versionId                          - ID of the version to locate within its terms history
+   * @param   {object}                                                                 [options]                          - Query options
+   * @param   {boolean}                                                                [options.includeTechnicalUpgrades] - When false, exclude technical upgrade records from the sequence. Default: true
+   * @returns {Promise<{first: ?string, prev: ?string, next: ?string, last: ?string}>}                                    Promise resolved with the related version IDs, each null when there is none
+   */
+  async getNavigationIds(serviceId, termsType, versionId, options = {}) {
+    throw new Error(`#getNavigationIds method is not implemented in ${this.constructor.name}`);
+  }
+
   /**
    * Find all records for a specific service and terms type, in descending chronological order
    * For performance reasons, the content of the records will not be loaded by default. Use #loadRecordContent to load the content of individual records
@@ -152,6 +175,17 @@ class RepositoryInterface {
   async loadRecordContent(record) {
     throw new Error(`#loadRecordContent method is not implemented in ${this.constructor.name}`);
   }
+
+  /**
+   * Get the number of lines added and deleted by a record, relative to the previous state of the same terms
+   * This is an optional capability: backends that retain diffs (Git) override it, while backends that store full snapshots (MongoDB) inherit this default and report the statistics as unavailable
+   * @param   {string}                                            recordId - Record ID to get diff stats for
+   * @returns {Promise<{additions: ?number, deletions: ?number}>}          Promise resolved with the number of added and deleted lines, each null when the backend cannot provide them
+   */
+  // eslint-disable-next-line class-methods-use-this, no-unused-vars
+  getDiffStats(recordId) {
+    return { additions: null, deletions: null };
+  }
 }
 
 export default RepositoryInterface;

package/src/archivist/recorder/repositories/mongo/index.js

@@ -88,6 +88,19 @@ export default class MongoRepository extends RepositoryInterface {
     return this.#toDomain(mongoDocument);
   }
 
+  async findMetadataById(recordId) {
+    if (!ObjectId.isValid(recordId)) {
+      return null;
+    }
+
+    const document = await this.collection.findOne(
+      { _id: ObjectId.createFromHexString(recordId) },
+      { projection: { content: 0 } },
+    );
+
+    return document ? this.#toDomain(document, { deferContentLoading: true }) : null;
+  }
+
   async findAll({ limit, offset, includeTechnicalUpgrades = true } = {}) {
     const filter = includeTechnicalUpgrades ? {} : { isTechnicalUpgrade: { $ne: true } };
     let query = this.collection.find(filter).project({ content: 0 }).sort({ fetchDate: -1 });
@@ -146,6 +159,46 @@ export default class MongoRepository extends RepositoryInterface {
       .map(mongoDocument => this.#toDomain(mongoDocument, { deferContentLoading: true })));
   }
 
+  async getNavigationIds(serviceId, termsType, versionId, { includeTechnicalUpgrades = true } = {}) {
+    const empty = { first: null, prev: null, next: null, last: null };
+
+    if (!ObjectId.isValid(versionId)) {
+      return empty;
+    }
+
+    const _id = ObjectId.createFromHexString(versionId);
+    const filter = { serviceId, termsType };
+
+    if (!includeTechnicalUpgrades) {
+      filter.isTechnicalUpgrade = { $ne: true };
+    }
+
+    const current = await this.collection.findOne({ ...filter, _id }, { projection: { fetchDate: 1 } });
+
+    if (!current) {
+      return empty;
+    }
+
+    const { fetchDate } = current;
+    const idOnly = { projection: { _id: 1 } };
+
+    // Deterministic total order (fetchDate, then _id) ascending; prev is the greatest record strictly before the current one, next the least strictly after.
+    // Using _id as a tiebreaker makes prev and next well-defined even for versions sharing the same fetch date, so navigation always round-trips.
+    const [ oldest, newest, previous, next ] = await Promise.all([
+      this.collection.find(filter, idOnly).sort({ fetchDate: 1, _id: 1 }).limit(1).next(),
+      this.collection.find(filter, idOnly).sort({ fetchDate: -1, _id: -1 }).limit(1).next(),
+      this.collection.find({ ...filter, $or: [{ fetchDate: { $lt: fetchDate } }, { fetchDate, _id: { $lt: _id } }] }, idOnly).sort({ fetchDate: -1, _id: -1 }).limit(1).next(),
+      this.collection.find({ ...filter, $or: [{ fetchDate: { $gt: fetchDate } }, { fetchDate, _id: { $gt: _id } }] }, idOnly).sort({ fetchDate: 1, _id: 1 }).limit(1).next(),
+    ]);
+
+    return {
+      first: oldest?._id?.toString() || null,
+      last: newest?._id?.toString() || null,
+      prev: previous?._id?.toString() || null,
+      next: next?._id?.toString() || null,
+    };
+  }
+
   count(serviceId, termsType) {
     const filter = {};
 

package/src/archivist/recorder/repositories/mongo/index.test.js

@@ -988,6 +988,177 @@ describe('MongoRepository', () => {
       });
     });
 
+    describe('#getNavigationIds', () => {
+      let firstVersion;
+      let middleVersion;
+      let lastVersion;
+
+      before(async () => {
+        firstVersion = await subject.save(new Version({
+          serviceId: SERVICE_PROVIDER_ID,
+          termsType: TERMS_TYPE,
+          content: 'first content',
+          fetchDate: FETCH_DATE_EARLIER,
+          snapshotIds: [SNAPSHOT_ID],
+        }));
+
+        middleVersion = await subject.save(new Version({
+          serviceId: SERVICE_PROVIDER_ID,
+          termsType: TERMS_TYPE,
+          content: 'middle content',
+          fetchDate: FETCH_DATE,
+          snapshotIds: [SNAPSHOT_ID],
+        }));
+
+        lastVersion = await subject.save(new Version({
+          serviceId: SERVICE_PROVIDER_ID,
+          termsType: TERMS_TYPE,
+          content: 'last content',
+          fetchDate: FETCH_DATE_LATER,
+          snapshotIds: [SNAPSHOT_ID],
+        }));
+      });
+
+      after(() => subject.removeAll());
+
+      context('for the oldest version', () => {
+        let navigationIds;
+
+        before(async () => { navigationIds = await subject.getNavigationIds(SERVICE_PROVIDER_ID, TERMS_TYPE, firstVersion.id); });
+
+        it('has no previous version', () => expect(navigationIds.prev).to.be.null);
+        it('points to the next version', () => expect(navigationIds.next).to.equal(middleVersion.id));
+        it('points to itself as first', () => expect(navigationIds.first).to.equal(firstVersion.id));
+        it('points to the newest version as last', () => expect(navigationIds.last).to.equal(lastVersion.id));
+      });
+
+      context('for a middle version', () => {
+        let navigationIds;
+
+        before(async () => { navigationIds = await subject.getNavigationIds(SERVICE_PROVIDER_ID, TERMS_TYPE, middleVersion.id); });
+
+        it('points to the previous version', () => expect(navigationIds.prev).to.equal(firstVersion.id));
+        it('points to the next version', () => expect(navigationIds.next).to.equal(lastVersion.id));
+        it('points to the oldest version as first', () => expect(navigationIds.first).to.equal(firstVersion.id));
+        it('points to the newest version as last', () => expect(navigationIds.last).to.equal(lastVersion.id));
+      });
+
+      context('for the newest version', () => {
+        let navigationIds;
+
+        before(async () => { navigationIds = await subject.getNavigationIds(SERVICE_PROVIDER_ID, TERMS_TYPE, lastVersion.id); });
+
+        it('points to the previous version', () => expect(navigationIds.prev).to.equal(middleVersion.id));
+        it('has no next version', () => expect(navigationIds.next).to.be.null);
+        it('points to itself as last', () => expect(navigationIds.last).to.equal(lastVersion.id));
+      });
+
+      context('when the version does not exist', () => {
+        it('returns only null IDs', async () => {
+          expect(await subject.getNavigationIds(SERVICE_PROVIDER_ID, TERMS_TYPE, 'ffffffffffffffffffffffff')).to.deep.equal({ first: null, prev: null, next: null, last: null });
+        });
+      });
+
+      context('when a technical upgrade is recorded out of chronological order', () => {
+        // A technical upgrade re-renders an old snapshot: it carries an OLD fetch date but is inserted last.
+        // The navigation IDs are derived from a single chronological order, so prev/next stay exact inverses.
+        const TECHNICAL_UPGRADE_DATE = new Date('2000-01-01T09:00:00.000Z'); // between firstVersion (06:00) and middleVersion (12:00)
+        let technicalUpgrade;
+
+        before(async () => {
+          technicalUpgrade = await subject.save(new Version({
+            serviceId: SERVICE_PROVIDER_ID,
+            termsType: TERMS_TYPE,
+            content: 'technical upgrade content',
+            fetchDate: TECHNICAL_UPGRADE_DATE,
+            isTechnicalUpgrade: true,
+            snapshotIds: [SNAPSHOT_ID],
+          }));
+        });
+
+        it('orders it by its fetch date, not its insertion order', async () => {
+          const navigationIds = await subject.getNavigationIds(SERVICE_PROVIDER_ID, TERMS_TYPE, technicalUpgrade.id);
+
+          expect(navigationIds.prev).to.equal(firstVersion.id);
+          expect(navigationIds.next).to.equal(middleVersion.id);
+        });
+
+        it('keeps prev and next as exact inverses (round-trips)', async () => {
+          const fromFirst = await subject.getNavigationIds(SERVICE_PROVIDER_ID, TERMS_TYPE, firstVersion.id);
+
+          expect(fromFirst.next).to.equal(technicalUpgrade.id);
+
+          const backFromUpgrade = await subject.getNavigationIds(SERVICE_PROVIDER_ID, TERMS_TYPE, fromFirst.next);
+
+          expect(backFromUpgrade.prev).to.equal(firstVersion.id);
+        });
+
+        it('can exclude technical upgrades from the sequence', async () => {
+          const navigationIds = await subject.getNavigationIds(SERVICE_PROVIDER_ID, TERMS_TYPE, firstVersion.id, { includeTechnicalUpgrades: false });
+
+          expect(navigationIds.next).to.equal(middleVersion.id);
+        });
+      });
+    });
+
+    describe('#getNavigationIds with versions sharing the same fetch date', () => {
+      // Distinct versions can share a fetch date; the _id tiebreaker must keep the order deterministic so prev/next still round-trip.
+      let ids;
+
+      before(async () => {
+        ids = [];
+        for (const content of [ 'tie A', 'tie B', 'tie C' ]) {
+          ids.push((await subject.save(new Version({ serviceId: SERVICE_PROVIDER_ID, termsType: TERMS_TYPE, content, fetchDate: FETCH_DATE, snapshotIds: [SNAPSHOT_ID] }))).id);
+        }
+      });
+
+      after(() => subject.removeAll());
+
+      it('round-trips next then prev for every version', async () => {
+        for (const id of ids) {
+          const navigationIds = await subject.getNavigationIds(SERVICE_PROVIDER_ID, TERMS_TYPE, id);
+
+          if (navigationIds.next) {
+            expect((await subject.getNavigationIds(SERVICE_PROVIDER_ID, TERMS_TYPE, navigationIds.next)).prev).to.equal(id);
+          }
+        }
+      });
+
+      it('exposes all three versions as a single ordered chain', async () => {
+        const head = await subject.getNavigationIds(SERVICE_PROVIDER_ID, TERMS_TYPE, ids[0]);
+        const walked = new Set([head.first]);
+        let cursor = head.first;
+
+        while (cursor) {
+          walked.add(cursor);
+          cursor = (await subject.getNavigationIds(SERVICE_PROVIDER_ID, TERMS_TYPE, cursor)).next;
+        }
+
+        expect(walked).to.have.lengthOf(ids.length);
+      });
+    });
+
+    describe('#getDiffStats', () => {
+      // Diff statistics are an optional repository capability; MongoDB stores full snapshots rather than diffs, so it inherits the interface default that reports them as unavailable.
+      let versionId;
+
+      before(async () => {
+        ({ id: versionId } = await subject.save(new Version({
+          serviceId: SERVICE_PROVIDER_ID,
+          termsType: TERMS_TYPE,
+          content: CONTENT,
+          fetchDate: FETCH_DATE,
+          snapshotIds: [SNAPSHOT_ID],
+        })));
+      });
+
+      after(() => subject.removeAll());
+
+      it('reports additions and deletions as unavailable', async () => {
+        expect(await subject.getDiffStats(versionId)).to.deep.equal({ additions: null, deletions: null });
+      });
+    });
+
     describe('#findLatest', () => {
       context('when there are records for the given service', () => {
         let lastSnapshotId;

package/src/archivist/services/index.test.js

@@ -431,7 +431,7 @@ describe('Services', () => {
         expect(secondSourceDocument.filters).to.be.an('array');
         expect(secondSourceDocument.filters).to.have.length(2);
         expect(secondSourceDocument.filters[0]).to.be.a('function');
-        expect(secondSourceDocument.filters[0].name).to.equal('removeQueryParams');
+        expect(secondSourceDocument.filters[0].name).to.equal(realFilterNames[0]);
         expect(secondSourceDocument.filters[1]).to.be.a('function');
         expect(secondSourceDocument.filters[1].name).to.equal('removePrintButton');
       });

package/src/collection-api/middlewares/errors.js

@@ -2,5 +2,5 @@ import logger from '../logger.js';
 
 export default function errorsMiddleware(err, req, res, next) {
   logger.error(err.stack);
-  res.status(500).json({ error: err.message });
+  res.status(500).json({ error: 'Internal Server Error' }); // Never echo internal error details: they can expose server internals such as filesystem paths
 }

package/src/collection-api/routes/index.js

@@ -38,6 +38,7 @@ export default async function apiRouter(basePath) {
   const collection = await getCollection();
   const versionsStorageConfig = config.get('@opentermsarchive/engine.recorder.versions.storage');
   const versionsRepository = await RepositoryFactory.create(versionsStorageConfig).initialize();
+  const snapshotsRepository = await RepositoryFactory.create(config.get('@opentermsarchive/engine.recorder.snapshots.storage')).initialize();
   const feedConfig = config.get('@opentermsarchive/engine.collection-api.feed');
 
   if (!collection.metadata?.id) {
@@ -50,7 +51,7 @@ export default async function apiRouter(basePath) {
 
   router.use(await metadataRouter(collection, services));
   router.use(servicesRouter(services));
-  router.use(versionsRouter(versionsRepository));
+  router.use(versionsRouter(versionsRepository, snapshotsRepository));
   router.use(feedRouter(services, versionsRepository, versionsStorageConfig.type, feedConfig.limit, feedConfig.versionUrlTemplate));
 
   return router;