@opentermsarchive/engine 14.1.0 → 15.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opentermsarchive/engine",
-  "version": "14.1.0",
+  "version": "15.0.0",
   "description": "Tracks and makes visible changes to the terms of online services",
   "homepage": "https://opentermsarchive.org",
   "bugs": {

package/src/archivist/recorder/repositories/git/dataMapper.js

@@ -30,6 +30,10 @@ const MULTIPLE_SOURCE_DOCUMENTS_PREFIX = 'This version was recorded after extrac
 
 export const COMMIT_MESSAGE_PREFIXES_REGEXP = new RegExp(`^(${Object.values(COMMIT_MESSAGE_PREFIXES).join('|')})`);
 
+export function isTechnicalUpgrade(message) {
+  return message.startsWith(COMMIT_MESSAGE_PREFIXES.technicalUpgrade) || message.startsWith(COMMIT_MESSAGE_PREFIXES.deprecated_refilter);
+}
+
 export function toPersistence(record, snapshotIdentiferTemplate) {
   const { serviceId, termsType, documentId, snapshotIds = [], mimeType, metadata } = record;
 

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

@@ -22,7 +22,7 @@ export default class Git {
 
     this.git = simpleGit(this.path, {
       trimmed: true,
-      maxConcurrentProcesses: 1,
+      maxConcurrentProcesses: 1, // Concurrent runs on the same repository race the index and the commit-graph and can corrupt them
     });
 
     await this.git.init();
@@ -106,7 +106,8 @@ export default class Git {
 
       return commits;
     } catch (error) {
-      if (/unknown revision or path not in the working tree|does not have any commits yet/.test(error.message)) {
+      // `bad object` is raised for a well-formed but absent object ID; like an unknown revision, it means "no match" rather than a hard failure
+      if (/unknown revision or path not in the working tree|does not have any commits yet|bad object/.test(error.message)) {
         return [];
       }
 
@@ -132,15 +133,24 @@ export default class Git {
     await fs.rm(path.join(this.path, '.git', 'objects', 'info', 'commit-graph.lock'), { force: true }); // Remove a leftover commit-graph lock from a previous `commit-graph write` that was killed mid-write (e.g. the process was terminated during a deploy or restart). The commit-graph is a disposable cache rebuilt by `writeCommitGraph`, so clearing a stale lock is safe and prevents every subsequent run from failing.
     await this.git.reset('hard');
 
-    return this.git.clean('f', '-d');
+    return this.git.clean('f', '-d'); // Force-remove untracked files (`f`) and untracked directories (`-d`)
   }
 
   getFullHash(shortHash) {
-    return this.git.show([ shortHash, '--pretty=%H', '-s' ]);
+    return this.git.show([
+      shortHash,
+      '--pretty=%H', // Print the full 40-character commit hash
+      '-s', // Suppress the diff output, only the formatted hash is wanted
+    ]);
   }
 
   restore(path, commit) {
-    return this.git.raw([ 'restore', '-s', commit, '--', path ]);
+    return this.git.raw([
+      'restore',
+      '-s', commit, // Take the file contents from this specific commit rather than from the index
+      '--', // Everything after is a pathspec, not a revision or option
+      path,
+    ]);
   }
 
   async destroyHistory() {
@@ -154,14 +164,86 @@ export default class Git {
   }
 
   async listFiles(path) {
-    return (await this.git.raw([ 'ls-files', path ])).split('\n');
+    return (await this.git.raw([ 'ls-files', '--', path ])).split('\n'); // Everything after "--" is a pathspec, not a revision or option
   }
 
   async writeCommitGraph() {
-    await this.git.raw([ 'commit-graph', 'write', '--reachable', '--changed-paths' ]);
+    await this.git.raw([
+      'commit-graph',
+      'write',
+      '--reachable', // Cover every commit reachable from the refs, so the whole history is indexed
+      '--changed-paths', // Also store the changed-path Bloom filters that speed up path-limited log/diff
+    ]);
   }
 
   async updateCommitGraph() {
-    await this.git.raw([ 'commit-graph', 'write', '--reachable', '--changed-paths', '--append' ]);
+    await this.git.raw([
+      'commit-graph',
+      'write',
+      '--reachable',
+      '--changed-paths',
+      '--append', // Extend the existing commit-graph instead of rewriting it in full
+    ]);
+  }
+
+  async listPathRevisions(pathFilter) {
+    let output;
+
+    try {
+      // Ordering and technical-upgrade filtering are done by the caller in memory, so `--author-date-order`/`--grep`/`--name-only` are deliberately omitted to keep this walk lean
+      output = await this.git.raw([
+        'log',
+        '--no-merges',
+        '--format=%H%x09%at%x09%s', // Tab-separated hash, author date and subject: the minimum needed to order versions and detect technical upgrades, with no diff or message body loaded
+        '--', // Everything after is a pathspec, never a revision or an option
+        pathFilter,
+      ]);
+    } catch (error) {
+      if (/unknown revision or path not in the working tree|does not have any commits yet/.test(error.message)) {
+        return [];
+      }
+
+      throw error;
+    }
+
+    if (!output) {
+      return [];
+    }
+
+    return output.trim().split('\n').filter(Boolean).map(line => {
+      const [ hash, timestamp, ...subjectParts ] = line.split('\t');
+
+      return { hash, timestamp: parseInt(timestamp, 10), subject: subjectParts.join('\t') };
+    });
+  }
+
+  async getDiffStats(commitHash) {
+    const output = await this.git.raw([
+      'show',
+      '--numstat', // Report added/deleted line counts per file as tab-separated numbers, instead of a textual diff
+      '--format=', // Drop the commit header so the output holds only the numstat lines
+      commitHash,
+    ]);
+
+    let additions = 0;
+    let deletions = 0;
+
+    for (const line of output.trim().split('\n')) {
+      if (!line) {
+        continue;
+      }
+
+      const [ added, deleted ] = line.split('\t');
+
+      // Binary files show '-' for additions/deletions
+      if (added !== '-') {
+        additions += parseInt(added, 10);
+      }
+      if (deleted !== '-') {
+        deletions += parseInt(deleted, 10);
+      }
+    }
+
+    return { additions, deletions };
   }
 }

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

@@ -15,6 +15,25 @@ import Git from './git.js';
 
 const fs = fsApi.promises;
 
+const RECORD_ID_REGEXP = /^[0-9a-f]{7,40}$/i; // Git commit SHA 7 (abbreviated) to 40 (full) hexadecimal characters. Prevent value such as `--output=…` to be parsed as a command-line option
+
+const CONTROL_CHARACTERS_REGEXP = /\p{Cc}/u; // Matches any Unicode "control" character: the C0 range (U+0000 to U+001F), DEL (U+007F) and the C1 range (U+0080 to U+009F), i.e. 65 non-printable characters including NUL. The `u` flag is required for the `\p{...}` property escape to be recognised, otherwise the pattern would match the literal text `p{Cc}`. Legitimate service IDs, terms types and document IDs never contain these, and NUL in particular can truncate a value once it reaches git or the filesystem, so any segment holding one is rejected.
+
+// Keeps hostile values from reaching git, where a pathspec that resolves outside the repository (such as `../foo/*`) aborts with an error that exposes the repository location.
+function isPlainPathSegment(segment) {
+  return segment.length > 0
+    && segment !== '.'
+    && segment !== '..'
+    && !segment.includes('/')
+    && !segment.includes('\\')
+    && !CONTROL_CHARACTERS_REGEXP.test(segment);
+}
+
+function canMatchRecordFilePath(...pathSegments) {
+  // A non-string segment means "not provided" (`undefined`, or `false` for an absent document ID) and constrains nothing
+  return pathSegments.every(segment => typeof segment !== 'string' || isPlainPathSegment(segment));
+}
+
 export default class GitRepository extends RepositoryInterface {
   constructor({ path, author, publish, snapshotIdentiferTemplate }) {
     super();
@@ -64,6 +83,10 @@ export default class GitRepository extends RepositoryInterface {
   }
 
   async findLatest(serviceId, termsType, documentId) {
+    if (!canMatchRecordFilePath(serviceId, termsType, documentId)) {
+      return null;
+    }
+
     const matchingFilesPaths = await this.git.listFiles(DataMapper.generateFilePath(serviceId, termsType, documentId));
 
     if (!matchingFilesPaths.length) {
@@ -76,35 +99,95 @@ export default class GitRepository extends RepositoryInterface {
   }
 
   async findByDate(serviceId, termsType, date, documentId) {
+    if (!canMatchRecordFilePath(serviceId, termsType, documentId)) {
+      return null;
+    }
+
     const filePath = DataMapper.generateFilePath(serviceId, termsType, documentId);
-    const commit = await this.git.getCommit([ `--until=${date?.toISOString()}`, filePath ]);
+    const commit = await this.git.getCommit([ `--until=${date?.toISOString()}`, '--', filePath ]);
 
     return this.#toDomain(commit);
   }
 
   async findById(recordId) {
-    const commit = await this.git.getCommit([recordId]);
+    if (!RECORD_ID_REGEXP.test(recordId)) {
+      return null;
+    }
+
+    const commit = await this.git.getCommit([ '--end-of-options', recordId ]); // `--end-of-options` forces git to treat `recordId` as a revision, never as an option: a second line of defence that keeps the lookup safe from argument injection even if the format guard above is ever relaxed
 
     return this.#toDomain(commit);
   }
 
+  async findMetadataById(recordId) {
+    if (!RECORD_ID_REGEXP.test(recordId)) {
+      return null;
+    }
+
+    const commit = await this.git.getCommit([ '--end-of-options', recordId ]); // `--end-of-options` forces git to treat `recordId` as a revision, never as an option: a second line of defence that keeps the lookup safe from argument injection even if the format guard above is ever relaxed
+
+    return this.#toDomain(commit, { deferContentLoading: true });
+  }
+
   async findAll({ limit, offset, includeTechnicalUpgrades = true } = {}) {
     return Promise.all((await this.#getCommits({ limit, offset, includeTechnicalUpgrades })).map(commit => this.#toDomain(commit, { deferContentLoading: true })));
   }
 
+  async findByServiceAndTermsType(serviceId, termsType, { limit, offset, includeTechnicalUpgrades = true } = {}) {
+    if (!canMatchRecordFilePath(serviceId, termsType)) {
+      return [];
+    }
+
+    const pathPattern = DataMapper.generateFilePath(serviceId, termsType);
+
+    return Promise.all((await this.#getCommits({ pathFilter: pathPattern, limit, offset, includeTechnicalUpgrades })).map(commit => this.#toDomain(commit, { deferContentLoading: true })));
+  }
+
   async findByService(serviceId, { limit, offset, includeTechnicalUpgrades = true } = {}) {
+    if (!canMatchRecordFilePath(serviceId)) {
+      return [];
+    }
+
     const pathPattern = DataMapper.generateFilePath(serviceId);
 
     return Promise.all((await this.#getCommits({ pathFilter: pathPattern, limit, offset, includeTechnicalUpgrades })).map(commit => this.#toDomain(commit, { deferContentLoading: true })));
   }
 
-  async findByServiceAndTermsType(serviceId, termsType, { limit, offset, includeTechnicalUpgrades = true } = {}) {
+  async getNavigationIds(serviceId, termsType, versionId, { includeTechnicalUpgrades = true } = {}) {
+    if (!canMatchRecordFilePath(serviceId, termsType)) {
+      return { first: null, prev: null, next: null, last: null };
+    }
+
     const pathPattern = DataMapper.generateFilePath(serviceId, termsType);
+    let revisions = await this.git.listPathRevisions(pathPattern); // single lean walk of the terms history
 
-    return Promise.all((await this.#getCommits({ pathFilter: pathPattern, limit, offset, includeTechnicalUpgrades })).map(commit => this.#toDomain(commit, { deferContentLoading: true })));
+    if (!includeTechnicalUpgrades) {
+      revisions = revisions.filter(revision => !DataMapper.isTechnicalUpgrade(revision.subject));
+    }
+
+    // Deterministic total order: most recent first, commit SHA as a stable tiebreaker for versions sharing the same fetch date (git stores second precision).
+    // prev/next are then adjacent entries in this single order, so navigation always round-trips, unlike the previous chronological/topological mix.
+    revisions.sort((a, b) => b.timestamp - a.timestamp || (a.hash < b.hash ? -1 : 1));
+
+    const index = revisions.findIndex(revision => revision.hash === versionId);
+
+    if (index === -1) {
+      return { first: null, prev: null, next: null, last: null };
+    }
+
+    return {
+      last: revisions[0].hash,
+      first: revisions[revisions.length - 1].hash,
+      next: index > 0 ? revisions[index - 1].hash : null,
+      prev: index < revisions.length - 1 ? revisions[index + 1].hash : null,
+    };
   }
 
   async count(serviceId, termsType) {
+    if (!canMatchRecordFilePath(serviceId, termsType)) {
+      return 0;
+    }
+
     const grepOptions = Object.values(DataMapper.COMMIT_MESSAGE_PREFIXES).map(prefix => `--grep=${prefix}`);
     const pathOptions = [];
 
@@ -158,6 +241,10 @@ export default class GitRepository extends RepositoryInterface {
     record.content = pdfBuffer;
   }
 
+  getDiffStats(recordId) {
+    return this.git.getDiffStats(recordId);
+  }
+
   async #getCommits({ pathFilter, reverse = false, limit, offset, includeTechnicalUpgrades = true } = {}) {
     const prefixes = includeTechnicalUpgrades
       ? DataMapper.COMMIT_MESSAGE_PREFIXES

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', () => {