@secureport/core 0.3.0 → 1.0.0-rc.0

package/src/import/generic.ts

@@ -0,0 +1,258 @@
+import type { Finding } from '../finding.js';
+import type { Severity, SeveritySource } from '../severity.js';
+import { SEVERITY_ORDER, severityFromCvss } from '../severity.js';
+import { fingerprint, vulnKey, FINGERPRINT_VERSION } from '../fingerprint.js';
+import type { ImportOptions } from './nuclei.js';
+
+/**
+ * One finding in the generic Secureport format.
+ *
+ * **Written last, on purpose.** This is the shape the four scanner importers
+ * turned out to have in common, rather than a format designed in advance and
+ * then argued with. Everything an engine reliably supplies is here; everything
+ * only one of them had is not.
+ *
+ * Only `title` and `location` are required. A tool that knows nothing but "this
+ * is wrong, and it is here" can still produce a trackable finding — which is the
+ * point of having a generic format at all.
+ */
+export interface GenericFinding {
+  /** What is wrong. */
+  readonly title: string;
+
+  /** Where it is — a URL, a host, a `host:port`, or a file path. */
+  readonly location: string;
+
+  /** Fuller explanation. */
+  readonly description?: string;
+
+  /**
+   * Severity, if the tool rates it.
+   *
+   * Ignored when `cvssScore` is present: a score is more precise than a word,
+   * and `severitySource` records which was used.
+   */
+  readonly severity?: Severity;
+
+  /** CVSS base score, 0–10. Preferred over `severity` when both are given. */
+  readonly cvssScore?: number;
+
+  /** CVSS vector string. */
+  readonly cvssVector?: string;
+
+  /** CWE identifier, with or without the `CWE-` prefix. */
+  readonly cwe?: string;
+
+  /** CVE identifier. */
+  readonly cve?: string;
+
+  /** Broad grouping, e.g. `injection`. */
+  readonly category?: string;
+
+  /** The parameter implicated, where the weakness has one. */
+  readonly parameter?: string;
+
+  /** The port, for findings about a service rather than a path. */
+  readonly port?: number;
+
+  /** What produced it. Defaults to `generic`. */
+  readonly engine?: string;
+
+  /** The producing tool's own identifier for the rule. */
+  readonly ruleId?: string;
+
+  /** What to do about it. */
+  readonly recommendation?: string;
+
+  /** Further reading. */
+  readonly references?: readonly string[];
+
+  /** Pointers to stored evidence. */
+  readonly evidenceUri?: readonly string[];
+
+  /** The tool's confidence, 0–1. */
+  readonly confidence?: number;
+}
+
+/** A generic findings document. */
+export interface GenericDocument {
+  /**
+   * Format version.
+   *
+   * Present so this file can change shape later without guessing. An unknown
+   * version is refused rather than parsed optimistically.
+   */
+  readonly version: 1;
+
+  /** The findings. */
+  readonly findings: readonly GenericFinding[];
+}
+
+const SEVERITIES = new Set<string>(SEVERITY_ORDER);
+
+/** A non-empty trimmed string, or nothing. */
+const str = (v: unknown): string | undefined =>
+  typeof v === 'string' && v.trim() !== '' ? v.trim() : undefined;
+
+/** A finite number, or nothing. */
+const num = (v: unknown): number | undefined =>
+  typeof v === 'number' && Number.isFinite(v) ? v : undefined;
+
+/**
+ * A title reduced to something usable as a weakness key.
+ *
+ * The last resort, and only for the generic format. A tool that reports nothing
+ * but "this is wrong, and it is here" has no CWE, no category and no rule id —
+ * and `vulnKey` would rightly refuse, because there is nothing to key on.
+ * Refusing would mean the minimal case cannot be imported at all, which defeats
+ * the point of having a generic format.
+ *
+ * **Titles are a poor key and this is not pretending otherwise:** reword the
+ * title and the issue becomes a different issue, and two tools describing the
+ * same weakness differently never collide. Supplying a `ruleId`, a `cwe` or a
+ * `category` is strictly better and all three are preferred over this.
+ */
+const titleKey = (title: string): string =>
+  title
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/gu, '-')
+    .replace(/^-|-$/gu, '');
+
+/** An array of non-empty strings, or nothing. */
+const strArray = (v: unknown): string[] | undefined => {
+  if (!Array.isArray(v)) return undefined;
+  const items = (v as readonly unknown[]).map(str).filter((x): x is string => x !== undefined);
+  return items.length > 0 ? items : undefined;
+};
+
+/**
+ * Turns the generic Secureport format into {@link Finding}s.
+ *
+ * The escape hatch for everything with no importer of its own: a manual test, an
+ * internal tool, a scanner nobody has written a parser for. Fingerprinting,
+ * reconciliation and reports then work identically — a finding that arrives this
+ * way is not a second-class finding.
+ *
+ * Refuses the document rather than salvaging part of it. Unlike Nuclei's JSONL,
+ * where one bad line costs one record, this is a single document a human or a
+ * script wrote deliberately: a field in the wrong shape is a mistake worth
+ * hearing about, not one to route around silently.
+ *
+ * @param json - The contents of a generic findings document.
+ * @param options - Ownership, and the injected clock and id source.
+ * @returns One finding per entry, in document order.
+ * @throws SyntaxError If the text is not valid JSON.
+ * @throws TypeError If the document is not the expected shape, naming the entry
+ * and field at fault.
+ */
+export function importGeneric(json: string, options: ImportOptions): Finding[] {
+  const doc: unknown = JSON.parse(json);
+  if (typeof doc !== 'object' || doc === null) {
+    throw new TypeError('generic findings document must be an object');
+  }
+  const record = doc as Record<string, unknown>;
+
+  if (record['version'] !== 1) {
+    throw new TypeError(`unsupported generic findings version: ${String(record['version'])}`);
+  }
+  const raw = record['findings'];
+  if (!Array.isArray(raw)) {
+    throw new TypeError('generic findings document has no `findings` array');
+  }
+
+  return (raw as readonly unknown[]).map((item, index) => {
+    const where = `findings[${String(index)}]`;
+    if (typeof item !== 'object' || item === null) {
+      throw new TypeError(`${where} is not an object`);
+    }
+    const entry = item as Record<string, unknown>;
+
+    const title = str(entry['title']);
+    const location = str(entry['location']);
+    if (title === undefined) throw new TypeError(`${where}.title is required`);
+    if (location === undefined) throw new TypeError(`${where}.location is required`);
+
+    const stated = str(entry['severity']);
+    if (stated !== undefined && !SEVERITIES.has(stated)) {
+      throw new TypeError(`${where}.severity is not a severity: ${stated}`);
+    }
+
+    const score = num(entry['cvssScore']);
+    let detectedSeverity: Severity;
+    let severitySource: SeveritySource;
+    if (score !== undefined && score >= 0 && score <= 10) {
+      detectedSeverity = severityFromCvss(score);
+      severitySource = 'cvss';
+    } else if (stated !== undefined) {
+      detectedSeverity = stated as Severity;
+      // Somebody stated it for this finding specifically, which is the
+      // strongest provenance there is.
+      severitySource = 'explicit';
+    } else {
+      detectedSeverity = 'advisory';
+      severitySource = 'engine_default';
+    }
+
+    const engine = str(entry['engine']) ?? 'generic';
+    const ruleId = str(entry['ruleId']);
+    const rawCwe = str(entry['cwe']);
+    const cwe = rawCwe === undefined ? undefined : `CWE-${rawCwe.replace(/^CWE-/iu, '')}`;
+    const category = str(entry['category']);
+    const parameter = str(entry['parameter']);
+    const port = num(entry['port']);
+
+    // Nothing classifies this finding, so key on the title rather than refuse
+    // it. `sourceRuleId` stays absent: the tool supplied none, and recording a
+    // slug as though it had would be a lie about provenance.
+    const key =
+      cwe === undefined && category === undefined && ruleId === undefined
+        ? `${engine}:${titleKey(title)}`
+        : vulnKey({
+            sourceEngine: engine,
+            ...(ruleId === undefined ? {} : { sourceRuleId: ruleId }),
+            ...(cwe === undefined ? {} : { cwe }),
+            ...(category === undefined ? {} : { category }),
+          });
+
+    return {
+      id: options.newId(),
+      orgId: options.orgId,
+      runId: options.runId,
+      fingerprint: fingerprint({
+        targetId: options.targetId,
+        vulnKey: key,
+        location,
+        ...(parameter === undefined ? {} : { parameter }),
+        ...(port === undefined ? {} : { port }),
+      }),
+      fingerprintVersion: FINGERPRINT_VERSION,
+      title,
+      ...(str(entry['description']) === undefined
+        ? {}
+        : { description: str(entry['description'])! }),
+      detectedSeverity,
+      severitySource,
+      ...(score === undefined ? {} : { cvssScore: score }),
+      ...(str(entry['cvssVector']) === undefined ? {} : { cvssVector: str(entry['cvssVector'])! }),
+      ...(cwe === undefined ? {} : { cwe }),
+      ...(str(entry['cve']) === undefined ? {} : { cve: str(entry['cve'])!.toUpperCase() }),
+      vulnKey: key,
+      ...(category === undefined ? {} : { category: category.toLowerCase() }),
+      location,
+      ...(parameter === undefined ? {} : { parameter }),
+      ...(strArray(entry['evidenceUri']) === undefined
+        ? {}
+        : { evidenceUri: strArray(entry['evidenceUri'])! }),
+      ...(str(entry['recommendation']) === undefined
+        ? {}
+        : { recommendation: str(entry['recommendation'])! }),
+      ...(strArray(entry['references']) === undefined
+        ? {}
+        : { references: strArray(entry['references'])! }),
+      sourceEngine: engine,
+      ...(ruleId === undefined ? {} : { sourceRuleId: ruleId }),
+      ...(num(entry['confidence']) === undefined ? {} : { confidence: num(entry['confidence'])! }),
+      createdAt: options.now,
+    } satisfies Finding;
+  });
+}

package/src/import/nessus.ts

@@ -0,0 +1,136 @@
+import type { Finding } from '../finding.js';
+import type { Severity, SeveritySource } from '../severity.js';
+import { severityFromCvss } from '../severity.js';
+import { fingerprint, vulnKey, FINGERPRINT_VERSION } from '../fingerprint.js';
+import { childText, findAll, parseXml } from './xml.js';
+import type { ImportOptions } from './nuclei.js';
+
+/**
+ * Nessus reports severity as a number on the `ReportItem`.
+ *
+ * `0` is Info, which is the bottom of the scale here rather than a separate
+ * category. Nessus does reach `4` (Critical), unlike ZAP and Burp.
+ */
+const NESSUS_SEVERITY: Readonly<Record<string, Severity>> = Object.freeze({
+  '4': 'critical',
+  '3': 'high',
+  '2': 'medium',
+  '1': 'low',
+  '0': 'advisory',
+});
+
+/**
+ * Turns a `.nessus` export into {@link Finding}s.
+ *
+ * Nessus is host-oriented: every `ReportItem` hangs off a `ReportHost`, and the
+ * port and protocol are attributes rather than part of a URL. The location is
+ * assembled as `host:port`, which is **the only place the port survives** —
+ * `00-DOMAIN.md` §3 defines no `port` on a finding, so anything not in the
+ * location is lost. A network finding with no path still fingerprints
+ * distinctly per service because the port is inside its location.
+ *
+ * A consequence worth knowing: the fingerprint's last component is
+ * `parameter ?? port ?? ''`, so a Nessus port is counted twice — once inside
+ * the location and once as that component. Harmless, but it means a port
+ * cannot be recovered from a finding except by parsing its location. Recorded
+ * as backlog **B42**.
+ *
+ * Severity comes from the CVSS v3 base score where Nessus supplies one, and from
+ * its own numeric rating otherwise.
+ *
+ * A `ReportItem` with severity `0` and no port — Nessus's host-inventory
+ * plugins — still imports: an advisory is still a finding, and dropping it here
+ * would make coverage look narrower than it was.
+ *
+ * @param xml - The contents of a `.nessus` file.
+ * @param options - Ownership, and the injected clock and id source.
+ * @returns One finding per report item, in document order.
+ * @throws SyntaxError If the document is not well-formed XML.
+ */
+export function importNessus(xml: string, options: ImportOptions): Finding[] {
+  const root = parseXml(xml);
+  const findings: Finding[] = [];
+
+  for (const host of findAll(root, 'ReportHost')) {
+    const hostName = host.attrs['name'] ?? '';
+
+    for (const item of findAll(host, 'ReportItem')) {
+      const pluginId = item.attrs['pluginID'];
+      const title = item.attrs['pluginName'];
+      if (pluginId === undefined || title === undefined) continue;
+
+      const portText = item.attrs['port'];
+      const port = portText !== undefined && portText !== '0' ? Number(portText) : undefined;
+      const location = port === undefined ? hostName : `${hostName}:${String(port)}`;
+      if (location === '') continue;
+
+      const scoreText = childText(item, 'cvss3_base_score') ?? childText(item, 'cvss_base_score');
+      const score = scoreText === undefined ? undefined : Number(scoreText);
+
+      let detectedSeverity: Severity;
+      let severitySource: SeveritySource;
+      if (score !== undefined && Number.isFinite(score) && score >= 0 && score <= 10) {
+        detectedSeverity = severityFromCvss(score);
+        severitySource = 'cvss';
+      } else {
+        detectedSeverity = NESSUS_SEVERITY[item.attrs['severity'] ?? ''] ?? 'advisory';
+        severitySource = 'engine_default';
+      }
+
+      // Nessus writes the bare number, e.g. `79`.
+      const rawCwe = childText(item, 'cwe');
+      const cwe = rawCwe === undefined ? undefined : `CWE-${rawCwe.replace(/^CWE-/iu, '')}`;
+      const family = item.attrs['pluginFamily'];
+
+      const key = vulnKey({
+        sourceEngine: 'nessus',
+        sourceRuleId: pluginId,
+        ...(cwe === undefined ? {} : { cwe }),
+        ...(family === undefined ? {} : { category: family }),
+      });
+
+      const references = childText(item, 'see_also')
+        ?.split(/\s+/u)
+        .filter((token) => token.startsWith('http'));
+
+      findings.push({
+        id: options.newId(),
+        orgId: options.orgId,
+        runId: options.runId,
+        fingerprint: fingerprint({
+          targetId: options.targetId,
+          vulnKey: key,
+          location,
+          ...(port === undefined ? {} : { port }),
+        }),
+        fingerprintVersion: FINGERPRINT_VERSION,
+        title,
+        ...(childText(item, 'description') === undefined
+          ? {}
+          : { description: childText(item, 'description')! }),
+        detectedSeverity,
+        severitySource,
+        ...(score === undefined || !Number.isFinite(score) ? {} : { cvssScore: score }),
+        ...(childText(item, 'cvss3_vector') === undefined
+          ? {}
+          : { cvssVector: childText(item, 'cvss3_vector')! }),
+        ...(cwe === undefined ? {} : { cwe }),
+        ...(childText(item, 'cve') === undefined
+          ? {}
+          : { cve: childText(item, 'cve')!.toUpperCase() }),
+        vulnKey: key,
+        ...(family === undefined ? {} : { category: family.toLowerCase() }),
+        location,
+        ...(childText(item, 'solution') === undefined
+          ? {}
+          : { recommendation: childText(item, 'solution')! }),
+        ...(references === undefined || references.length === 0 ? {} : { references }),
+        sourceEngine: 'nessus',
+        sourceRuleId: pluginId,
+        createdAt: options.now,
+      });
+    }
+  }
+
+  return findings;
+}

package/src/import/xml.ts

@@ -0,0 +1,187 @@
+/**
+ * A parsed XML element.
+ *
+ * Deliberately minimal: a name, its attributes, its child elements and its
+ * text. No namespaces, no processing instructions, no mixed-content ordering —
+ * none of which appears in a Burp or Nessus export.
+ */
+export interface XmlNode {
+  /** The element name, as written. */
+  readonly name: string;
+
+  /** Attributes, with entities decoded. */
+  readonly attrs: Readonly<Record<string, string>>;
+
+  /** Child elements, in document order. */
+  readonly children: readonly XmlNode[];
+
+  /** All direct text and CDATA of this element, concatenated and trimmed. */
+  readonly text: string;
+}
+
+const ENTITIES: Readonly<Record<string, string>> = Object.freeze({
+  amp: '&',
+  lt: '<',
+  gt: '>',
+  quot: '"',
+  apos: "'",
+});
+
+/** Decodes the five XML entities and numeric character references. */
+function decodeEntities(text: string): string {
+  return text.replace(/&(#x?[0-9a-f]+|[a-z]+);/giu, (whole, body: string) => {
+    if (body.startsWith('#')) {
+      const code =
+        body[1]?.toLowerCase() === 'x' ? parseInt(body.slice(2), 16) : parseInt(body.slice(1), 10);
+      return Number.isFinite(code) && code >= 0 && code <= 0x10ffff
+        ? String.fromCodePoint(code)
+        : whole;
+    }
+    return ENTITIES[body.toLowerCase()] ?? whole;
+  });
+}
+
+interface MutableNode {
+  name: string;
+  attrs: Record<string, string>;
+  children: MutableNode[];
+  text: string;
+}
+
+/** Reads the attributes out of a start tag's body. */
+function parseAttrs(body: string): Record<string, string> {
+  const attrs: Record<string, string> = {};
+  const pattern = /([\w:.-]+)\s*=\s*("([^"]*)"|'([^']*)')/gu;
+  let match: RegExpExecArray | null;
+  while ((match = pattern.exec(body)) !== null) {
+    attrs[match[1]] = decodeEntities(match[3] ?? match[4] ?? '');
+  }
+  return attrs;
+}
+
+/**
+ * Parses the subset of XML that scanner exports actually use.
+ *
+ * **Deliberately narrow, and it throws rather than guesses.** Burp and Nessus
+ * both export machine-generated XML with a fixed shape: elements, attributes,
+ * text and CDATA. This handles exactly that, plus comments, the XML
+ * declaration, a DOCTYPE, self-closing tags and the five named entities with
+ * numeric character references.
+ *
+ * It does **not** handle namespaces, entity definitions or mixed-content
+ * ordering, and it has no opinion about schemas. Anything structurally
+ * unexpected — an unclosed element, a mismatched end tag, two root elements —
+ * is an error, because a parser that guesses at broken input produces findings
+ * that are quietly wrong, and a wrong finding is worse than a failed import.
+ *
+ * Hand-written rather than taken from a library because `@secureport/core` ships
+ * with zero runtime dependencies: it is imported by the hosted API and by third
+ * parties on equal terms, and a domain model that drags an XML parser in with it
+ * is a supply-chain decision made on everyone's behalf.
+ *
+ * @param source - The XML document.
+ * @returns The root element.
+ * @throws SyntaxError If the document is not well-formed, or has no root.
+ */
+export function parseXml(source: string): XmlNode {
+  const stack: MutableNode[] = [];
+  let root: MutableNode | undefined;
+  let i = 0;
+
+  while (i < source.length) {
+    const lt = source.indexOf('<', i);
+    if (lt === -1) break;
+
+    // Text before this tag belongs to the element currently open.
+    if (lt > i && stack.length > 0) {
+      stack[stack.length - 1].text += decodeEntities(source.slice(i, lt));
+    }
+
+    if (source.startsWith('<!--', lt)) {
+      const end = source.indexOf('-->', lt);
+      if (end === -1) throw new SyntaxError('unterminated comment');
+      i = end + 3;
+      continue;
+    }
+
+    if (source.startsWith('<![CDATA[', lt)) {
+      const end = source.indexOf(']]>', lt);
+      if (end === -1) throw new SyntaxError('unterminated CDATA section');
+      // CDATA is literal: no entity decoding, which is the whole point of it.
+      if (stack.length > 0) stack[stack.length - 1].text += source.slice(lt + 9, end);
+      i = end + 3;
+      continue;
+    }
+
+    if (source.startsWith('<?', lt) || source.startsWith('<!', lt)) {
+      const end = source.indexOf('>', lt);
+      if (end === -1) throw new SyntaxError('unterminated declaration');
+      i = end + 1;
+      continue;
+    }
+
+    const gt = source.indexOf('>', lt);
+    if (gt === -1) throw new SyntaxError('unterminated tag');
+    const raw = source.slice(lt + 1, gt);
+
+    if (raw.startsWith('/')) {
+      const name = raw.slice(1).trim();
+      const open = stack.pop();
+      if (open === undefined) throw new SyntaxError(`unexpected closing tag </${name}>`);
+      if (open.name !== name) {
+        throw new SyntaxError(`closing tag </${name}> does not match <${open.name}>`);
+      }
+      i = gt + 1;
+      continue;
+    }
+
+    const selfClosing = raw.endsWith('/');
+    const body = selfClosing ? raw.slice(0, -1) : raw;
+    const nameEnd = body.search(/[\s/]/u);
+    const name = (nameEnd === -1 ? body : body.slice(0, nameEnd)).trim();
+    if (name === '') throw new SyntaxError('tag with no name');
+
+    const node: MutableNode = {
+      name,
+      attrs: parseAttrs(nameEnd === -1 ? '' : body.slice(nameEnd)),
+      children: [],
+      text: '',
+    };
+
+    if (stack.length > 0) stack[stack.length - 1].children.push(node);
+    else if (root === undefined) root = node;
+    else throw new SyntaxError('more than one root element');
+
+    if (!selfClosing) stack.push(node);
+    i = gt + 1;
+  }
+
+  if (stack.length > 0) throw new SyntaxError(`unclosed element <${stack[stack.length - 1].name}>`);
+  if (root === undefined) throw new SyntaxError('no root element');
+
+  const finish = (node: MutableNode): XmlNode => ({
+    name: node.name,
+    attrs: node.attrs,
+    children: node.children.map(finish),
+    text: node.text.trim(),
+  });
+  return finish(root);
+}
+
+/** Every descendant with this name, at any depth. */
+export function findAll(node: XmlNode, name: string): XmlNode[] {
+  const found: XmlNode[] = [];
+  const walk = (current: XmlNode) => {
+    if (current.name === name) found.push(current);
+    for (const child of current.children) walk(child);
+  };
+  walk(node);
+  return found;
+}
+
+/** The text of the first direct child with this name, if it has any. */
+export function childText(node: XmlNode, name: string): string | undefined {
+  const child = node.children.find((c) => c.name === name);
+  const text = child?.text.trim();
+  return text === undefined || text === '' ? undefined : text;
+}

package/src/import/zap.ts

@@ -81,7 +81,7 @@ const splitReferences = (v: unknown): string[] | undefined => {
  * An alert with no instances still produces one finding, against the site — a
  * detection with no location is still a detection.
  *
- * Severity comes from ZAP's `riskcode`; see {@link ZAP_RISK} for why nothing
+ * Severity comes from ZAP's `riskcode`; see `ZAP_RISK` below for why nothing
  * here is ever `critical`.
  *
  * @param json - The contents of a ZAP JSON report.

package/src/index.ts

@@ -37,8 +37,27 @@ export { coversLocation } from './coverage.js';
 export type { ImportOptions } from './import/nuclei.js';
 export { importNuclei } from './import/nuclei.js';
 export { importZap } from './import/zap.js';
+export { importBurp } from './import/burp.js';
+export { importNessus } from './import/nessus.js';
+export type { GenericDocument, GenericFinding } from './import/generic.js';
+export { importGeneric } from './import/generic.js';
 export type { BuildSnapshotInput } from './snapshot-builder.js';
 export { buildSnapshot, parseSnapshot } from './snapshot-builder.js';
+export type {
+  ReportKind,
+  ReportModel,
+  ReportOptions,
+  ReportSection,
+  RetestEntry,
+  RetestOutcome,
+  RetestVerdict,
+  TestingBasis,
+} from './report/model.js';
+export { buildReportModel } from './report/model.js';
+export { renderMarkdown } from './report/markdown.js';
+export { renderHtml } from './report/html.js';
+export type { JsonReport } from './report/json.js';
+export { renderJson } from './report/json.js';
 export type { ReconcileInput, ReconcileResult } from './reconcile.js';
 export { reconcile } from './reconcile.js';
 export type { Coverage, Run, RunKind, RunSummary, RunTrigger, SeverityCounts } from './run.js';

package/src/reconcile.ts

@@ -1,4 +1,5 @@
 import type { Finding } from './finding.js';
+import { FINGERPRINT_VERSION } from './fingerprint.js';
 import type { Issue, IssueEvent } from './issue.js';
 import type { Run, RunKind, RunSummary, SeverityCounts } from './run.js';
 import {
@@ -155,6 +156,40 @@ function daysBetween(from: Date, to: Date): number {
   return Math.max(0, Math.floor((to.getTime() - from.getTime()) / 86_400_000));
 }
 
+/**
+ * Refuses to reconcile issues or findings computed by a different algorithm.
+ *
+ * **This prevents the worst failure in the product, and nothing checked for it
+ * until backlog B45 was raised.** If this package ships `fp_v2` and runs
+ * against a store of `fp_v1` issues, every fingerprint mismatches: every
+ * existing issue is unmatched and auto-resolves, every finding creates a new
+ * issue, and the history the product exists to keep is destroyed — silently,
+ * during an ordinary ingest.
+ *
+ * `fingerprintVersion` being stored on every row makes that *detectable*
+ * (invariant 8). Checking it here makes it *loud*. A version change is
+ * survivable only through the re-fingerprint migration described in
+ * `00-DOMAIN.md` §4, which is the one thing permitted to hold both versions at
+ * once — and it does so in memory, without writing.
+ *
+ * Findings are checked too, and separately: a store at the current version
+ * being handed findings from an older importer is the same mismatch arriving
+ * from the other direction.
+ */
+function assertOneFingerprintVersion(issues: readonly Issue[], findings: readonly Finding[]): void {
+  const found = new Set<string>();
+  for (const issue of issues) found.add(issue.fingerprintVersion);
+  for (const finding of findings) found.add(finding.fingerprintVersion);
+  found.delete(FINGERPRINT_VERSION);
+  if (found.size === 0) return;
+
+  throw new Error(
+    `reconcile() was given fingerprints at ${[...found].sort().join(', ')} but this package ` +
+      `computes ${FINGERPRINT_VERSION}. Matching across versions would resolve every existing ` +
+      'issue and recreate it as new. Run the re-fingerprint migration first (00-DOMAIN.md §4).',
+  );
+}
+
 /**
  * Turns a run's findings into issue state.
  *
@@ -204,6 +239,8 @@ export function reconcile(input: ReconcileInput): ReconcileResult {
   const actor = input.actor ?? 'reconciler';
   const slaPolicy = input.slaPolicy ?? DEFAULT_SLA_POLICY;
 
+  assertOneFingerprintVersion(issues, findings);
+
   const events: IssueEvent[] = [];
   const emit = (issueId: string, type: IssueEvent['type'], payload?: Record<string, unknown>) => {
     events.push({