@secureport/core 0.2.0 → 0.3.0

package/dist/snapshot.d.ts

@@ -0,0 +1,125 @@
+import type { Finding } from './finding.js';
+import type { IgnoreReason, Issue } from './issue.js';
+import type { RunSummary } from './run.js';
+import type { Severity, SlaStatus } from './severity.js';
+/**
+ * A system under test.
+ *
+ * Targets are the unit of authorisation as well as of organisation: staging,
+ * production and dev are separate targets with separate tokens and separate
+ * verification states.
+ */
+export interface Target {
+    /** Unique id. */
+    readonly id: string;
+    /** Organisation it belongs to. */
+    readonly orgId: string;
+    /** Human-readable name, as it appears on a report cover. */
+    readonly name: string;
+    /** What is being tested — a URL, host or repository. */
+    readonly url: string;
+}
+/**
+ * What happened to an issue between the baseline and this run.
+ *
+ * This is the axis every report opens on, because it is the question a reader
+ * actually has: not "what is wrong" but "what changed since last time".
+ */
+export type IssueChange = 'new' | 'still_open' | 'regressed' | 'resolved' | 'ignored';
+/**
+ * An issue as a report sees it: its own state, plus everything a template
+ * would otherwise have to compute.
+ *
+ * The derived fields are computed once, when the snapshot is built, so that
+ * five report templates in three formats cannot each work out `daysOpen`
+ * slightly differently.
+ */
+export interface SnapshotIssue {
+    /** The issue itself. */
+    readonly issue: Issue;
+    /** What happened to it relative to the baseline. */
+    readonly change: IssueChange;
+    /**
+     * Whole days between `firstSeen` and the run this snapshot is for.
+     *
+     * Measured from `firstSeen`, which is never reset, so a regression does not
+     * make a year-old problem look new.
+     */
+    readonly daysOpen: number;
+    /** Where it stands against its remediation deadline, as of this run. */
+    readonly slaStatus: SlaStatus;
+    /**
+     * The evidence behind it.
+     *
+     * Findings from this run, and from earlier ones where the report shows
+     * history. This is what makes a report checkable rather than merely
+     * assertive.
+     */
+    readonly findings: readonly Finding[];
+}
+/**
+ * A suppressed issue, as the appendix shows it.
+ *
+ * Deliberately its own shape rather than a flag on {@link SnapshotIssue}: the
+ * suppressed appendix answers a different question — not "what is wrong" but
+ * "what did you decide not to fix, and who decided it".
+ *
+ * **Every report carries this appendix, on by default.** It is an
+ * accepted-risk register, which is exactly what an auditor asks for, and
+ * hiding it would be both less useful and less honest.
+ */
+export interface SuppressedIssue {
+    /** The issue itself. */
+    readonly issue: Issue;
+    /** Why it was suppressed. */
+    readonly reason: IgnoreReason;
+    /** The justification given at the time. */
+    readonly comment: string;
+    /** Who suppressed it. */
+    readonly ignoredBy: string;
+    /** When. */
+    readonly ignoredAt: Date;
+    /** When the suppression lapses, if it does. */
+    readonly expiresAt?: Date;
+    /** Detected severity at the moment it was suppressed. */
+    readonly severityAtIgnore: Severity;
+}
+/**
+ * Issue state as of a run, plus a baseline to compare against.
+ *
+ * **The report engine's only input.** Every template consumes a `Snapshot` and
+ * nothing else — no database handle, no network, no clock. That is what makes
+ * a report reproducible, testable against golden files, and renderable by a
+ * third party who has findings on disk and no account.
+ *
+ * **The snapshot is the artefact; a PDF is a view of it.** Reports are rendered
+ * on demand and never stored (invariant 12). Snapshots are small, deterministic
+ * JSON, so caching one is cheap where storing a rendered document would buy
+ * retention policy, signed-URL expiry, encryption review and a deletion
+ * obligation in exchange for saving a render.
+ */
+export interface Snapshot {
+    /** The run this snapshot describes. */
+    readonly run: RunSummary;
+    /**
+     * What to compare against.
+     *
+     * The previous run for an ordinary report, or a specific named run for a
+     * retest. Absent for a first run, where there is nothing to compare to and
+     * every issue is `new`.
+     */
+    readonly baseline?: RunSummary;
+    /** The system under test. */
+    readonly target: Target;
+    /**
+     * Every issue in scope, with what changed and the evidence for it.
+     *
+     * Excludes suppressed issues, which appear in {@link Snapshot.suppressed}
+     * instead — the two lists are disjoint by construction so a template cannot
+     * accidentally count an accepted risk as an open one.
+     */
+    readonly issues: readonly SnapshotIssue[];
+    /** The accepted-risk register. */
+    readonly suppressed: readonly SuppressedIssue[];
+}
+//# sourceMappingURL=snapshot.d.ts.map

package/dist/snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.d.ts","sourceRoot":"","sources":["../src/snapshot.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACtD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAC3C,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAEzD;;;;;;GAMG;AACH,MAAM,WAAW,MAAM;IACrB,iBAAiB;IACjB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAEpB,kCAAkC;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB,4DAA4D;IAC5D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,wDAAwD;IACxD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,KAAK,GAAG,YAAY,GAAG,WAAW,GAAG,UAAU,GAAG,SAAS,CAAC;AAEtF;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B,wBAAwB;IACxB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IAEtB,oDAAoD;IACpD,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAE7B;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B,wEAAwE;IACxE,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAE9B;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAC;CACvC;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,eAAe;IAC9B,wBAAwB;IACxB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IAEtB,6BAA6B;IAC7B,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAE9B,2CAA2C;IAC3C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB,yBAAyB;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B,YAAY;IACZ,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC;IAEzB,+CAA+C;IAC/C,QAAQ,CAAC,SAAS,CAAC,EAAE,IAAI,CAAC;IAE1B,yDAAyD;IACzD,QAAQ,CAAC,gBAAgB,EAAE,QAAQ,CAAC;CACrC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,QAAQ;IACvB,uCAAuC;IACvC,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAC;IAEzB;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,UAAU,CAAC;IAE/B,6BAA6B;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,EAAE,SAAS,aAAa,EAAE,CAAC;IAE1C,kCAAkC;IAClC,QAAQ,CAAC,UAAU,EAAE,SAAS,eAAe,EAAE,CAAC;CACjD"}

package/dist/snapshot.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=snapshot.js.map

package/dist/snapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.js","sourceRoot":"","sources":["../src/snapshot.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,7 +1,27 @@
 {
   "name": "@secureport/core",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Shared domain model for Secureport. Imported by the hosted API the same way a third party would.",
+  "keywords": [
+    "security",
+    "pentest",
+    "penetration-testing",
+    "vulnerability",
+    "vulnerability-management",
+    "appsec",
+    "devsecops",
+    "sast",
+    "dast",
+    "nuclei",
+    "zap",
+    "burp",
+    "nessus",
+    "security-reporting"
+  ],
+  "homepage": "https://github.com/agbjordan/secureport/tree/main/packages/core#readme",
+  "bugs": {
+    "url": "https://github.com/agbjordan/secureport/issues"
+  },
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -17,6 +37,7 @@
     "LICENSE"
   ],
   "devDependencies": {
+    "@types/node": "^22.20.1",
     "typescript": "^5.7.2"
   },
   "license": "MIT",
@@ -29,7 +50,7 @@
     "access": "public"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.json",
+    "build": "rm -rf dist && tsc -p tsconfig.json",
     "typecheck": "tsc --noEmit"
   }
 }

package/src/coverage.ts

@@ -0,0 +1,65 @@
+import type { Coverage } from './run.js';
+
+/** Escapes a literal so it can sit inside a regular expression. */
+function escapeLiteral(text: string): string {
+  return text.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
+}
+
+/**
+ * Compiles a coverage glob into a regular expression.
+ *
+ * `**` matches anything including `/`; `*` matches anything except `/`, so
+ * `https://a.example/*` covers `/orders` but not `/orders/123`; `?` matches one
+ * character. Everything else is literal.
+ */
+function globToRegExp(glob: string): RegExp {
+  let out = '';
+  for (let i = 0; i < glob.length; i++) {
+    const char = glob[i];
+    if (char === '*') {
+      if (glob[i + 1] === '*') {
+        out += '.*';
+        i++;
+      } else {
+        out += '[^/]*';
+      }
+    } else if (char === '?') {
+      out += '[^/]';
+    } else {
+      out += escapeLiteral(char);
+    }
+  }
+  return new RegExp(`^${out}$`, 'u');
+}
+
+/** The port in a location, where it states one. */
+function portOf(location: string): number | undefined {
+  const match = /^[a-z][a-z0-9+.-]*:\/\/[^/]*?:(\d+)(?:[/?#]|$)/iu.exec(location);
+  return match ? Number(match[1]) : undefined;
+}
+
+/**
+ * Whether a run could have found something at this location.
+ *
+ * **This is what makes auto-resolution safe.** A run only resolves what it
+ * could have found (invariant 5): a quick profile that skipped `/admin` must
+ * not close an `/admin` issue, because not looking is not the same as not
+ * finding. Anything outside coverage is left entirely alone — not resolved, and
+ * not counted as a miss either.
+ *
+ * A location matches when it matches at least one covered path glob, **and**,
+ * where both the location and the coverage state a port, that port was
+ * exercised. The port rule errs towards leaving issues open: a scan of `:443`
+ * says nothing about `:8443`.
+ *
+ * @param location - The issue's location.
+ * @param coverage - What the run exercised.
+ * @returns `true` if the run could have found it.
+ */
+export function coversLocation(location: string, coverage: Coverage): boolean {
+  const port = portOf(location);
+  if (port !== undefined && coverage.ports !== undefined && coverage.ports.length > 0) {
+    if (!coverage.ports.includes(port)) return false;
+  }
+  return coverage.paths.some((glob) => globToRegExp(glob).test(location));
+}

package/src/finding.ts

@@ -0,0 +1,112 @@
+import type { Severity, SeveritySource } from './severity.js';
+
+/**
+ * One detection, in one run.
+ *
+ * **Findings are immutable evidence.** A finding is never updated after it is
+ * recorded (invariant 1) and it carries no status: whether something is open,
+ * fixed or accepted is a property of the {@link Issue} it reconciles into, not
+ * of the evidence for it. If a field here would need to change as a human works
+ * on the problem, it belongs on the issue instead.
+ *
+ * Many findings, from many runs and many engines, fold into one issue by
+ * {@link Finding.fingerprint}.
+ */
+export interface Finding {
+  /** Unique id for this detection. */
+  readonly id: string;
+
+  /** Organisation this finding belongs to. Every query carries it. */
+  readonly orgId: string;
+
+  /** The run that produced it. */
+  readonly runId: string;
+
+  /**
+   * Content address of the underlying weakness, used to reconcile findings
+   * into a single issue across runs and engines.
+   *
+   * Derived from the target, the {@link Finding.vulnKey}, the normalised
+   * location and the parameter — never from volatile evidence such as tokens,
+   * timestamps or response bodies, which would make every run look new.
+   */
+  readonly fingerprint: string;
+
+  /**
+   * Which fingerprint algorithm produced {@link Finding.fingerprint}.
+   *
+   * **A public contract.** It travels with every fingerprint everywhere
+   * (invariant 8) so a stored fingerprint can always be interpreted, and
+   * changing the algorithm means a re-fingerprint migration that preserves
+   * history rather than a silent recomputation.
+   */
+  readonly fingerprintVersion: string;
+
+  /** Short human-readable name for the weakness. */
+  readonly title: string;
+
+  /** Fuller explanation of what was detected. */
+  readonly description?: string;
+
+  /**
+   * Severity as detected for this finding.
+   *
+   * What the evidence says. The issue's `effectiveSeverity` may differ, because
+   * a human may have overridden it.
+   */
+  readonly detectedSeverity: Severity;
+
+  /** Why {@link Finding.detectedSeverity} is what it is. */
+  readonly severitySource: SeveritySource;
+
+  /** CVSS base score, where the engine or advisory supplied one. */
+  readonly cvssScore?: number;
+
+  /** CVSS vector string, where one was supplied. */
+  readonly cvssVector?: string;
+
+  /** CWE identifier, e.g. `CWE-79`. */
+  readonly cwe?: string;
+
+  /** CVE identifier, e.g. `CVE-2026-1234`. */
+  readonly cve?: string;
+
+  /**
+   * Engine-independent key for the weakness class.
+   *
+   * This is what makes a Nuclei detection and a ZAP detection of the same
+   * weakness collide into one issue. Without it there is no cross-engine
+   * deduplication, only per-engine.
+   */
+  readonly vulnKey: string;
+
+  /** Broad grouping for reports, e.g. `injection`, `tls`, `access-control`. */
+  readonly category?: string;
+
+  /** Where it was found — a URL, host, port or file path. */
+  readonly location: string;
+
+  /** The specific parameter implicated, where the weakness has one. */
+  readonly parameter?: string;
+
+  /** Pointers to stored evidence: request/response captures, screenshots. */
+  readonly evidenceUri?: readonly string[];
+
+  /** What to do about it. */
+  readonly recommendation?: string;
+
+  /** External reading: advisories, vendor bulletins, standards. */
+  readonly references?: readonly string[];
+
+  /** Which engine detected it, e.g. `nuclei`, `zap`, `burp`, `nessus`. */
+  readonly sourceEngine: string;
+
+  /** The engine's own identifier for the rule that fired. */
+  readonly sourceRuleId?: string;
+
+  /** The engine's confidence, where it reports one, from 0 to 1. */
+  readonly confidence?: number;
+
+  /** When the finding was recorded. */
+  readonly createdAt: Date;
+}

package/src/fingerprint.ts

@@ -0,0 +1,315 @@
+import { createHash } from 'node:crypto';
+
+/**
+ * Which fingerprint algorithm this build of the package implements.
+ *
+ * **A public contract, and the most consequential string in the package.** It
+ * is stored on every finding and every issue, everywhere, so that a fingerprint
+ * recorded a year ago can still be interpreted. Changing the algorithm means
+ * bumping this *and* running a per-organisation re-fingerprint migration that
+ * preserves history — never a silent recomputation, which would orphan every
+ * issue whose evidence no longer hashes to the same value.
+ *
+ * If you are tempted to "just tweak" the normaliser, that is this constant's
+ * job to prevent.
+ */
+export const FINGERPRINT_VERSION = 'fp_v1';
+
+/** A path segment that is entirely digits, e.g. the `123` in `/orders/123`. */
+const NUMERIC_SEGMENT = /^\d+$/u;
+
+/** A path segment that is a UUID in the canonical 8-4-4-4-12 form. */
+const UUID_SEGMENT = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/iu;
+
+/**
+ * The placeholder that a variable path segment collapses to.
+ *
+ * Exported because it appears in normalised locations, which appear in reports
+ * and in support conversations: someone reading `/orders/{id}` should be able
+ * to find out what produced it.
+ */
+export const PATH_PLACEHOLDER = '{id}';
+
+/**
+ * Decodes percent-encoding exactly once, and never throws.
+ *
+ * Once, not repeatedly: decoding until stable would make `%2541` and `%41`
+ * collapse to the same thing, so a target that double-encodes could be made to
+ * collide with one that does not.
+ *
+ * Malformed encoding is left alone rather than rejected. A fingerprint that
+ * throws on strange input is a fingerprint that loses a finding.
+ */
+function decodeOnce(value: string): string {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+}
+
+/**
+ * Collapses one path segment to {@link PATH_PLACEHOLDER} if it identifies a
+ * record rather than a route.
+ */
+function collapseSegment(segment: string): string {
+  if (NUMERIC_SEGMENT.test(segment) || UUID_SEGMENT.test(segment)) return PATH_PLACEHOLDER;
+  return segment;
+}
+
+/**
+ * Normalises a location so that the same weakness in the same place produces
+ * the same string, however the engine happened to write it down.
+ *
+ * This is the part of the fingerprint that decides whether `/orders/1` and
+ * `/orders/2` are one issue or two thousand. Applies, in order:
+ *
+ * - **Lowercases the host**, and converts an internationalised domain to
+ *   punycode, so `HTTPS://例え.テスト/x` and `https://xn--r8jz45g.xn--zckzah/x`
+ *   are one location.
+ * - **Drops a default port** (`:443` on https, `:80` on http) and keeps any
+ *   other, because `:8443` is a different service and `:443` is not.
+ * - **Decodes percent-encoding once.**
+ * - **Collapses numeric and UUID path segments** to `{id}`, so a per-record URL
+ *   does not open a per-record issue.
+ * - **Drops a trailing slash**, except on the root path where it is the path.
+ * - **Strips query values but keeps parameter names, sorted.** `?b=2&a=secret`
+ *   becomes `?a&b`. The names are structure and belong in identity; the values
+ *   are usually the payload that proved the weakness, which is evidence and
+ *   must never reach a fingerprint. Sorting means parameter order cannot split
+ *   one issue into two.
+ * - **Drops the fragment**, which the server never sees.
+ *
+ * Anything that is not a parseable absolute URL — a bare host, a file path, a
+ * `host:port` pair from a network scan — is normalised as a path alone. That is
+ * deliberate: refusing to fingerprint a non-HTTP finding would exclude whole
+ * classes of scanner from the model.
+ *
+ * @param location - Where the weakness was found.
+ * @returns The normalised location.
+ *
+ * @example
+ * ```ts
+ * normaliseLocation('HTTPS://API.Example.com:443/Orders/123/items/?b=2&a=secret#f');
+ * // 'https://api.example.com/Orders/{id}/items?a&b'
+ * ```
+ */
+export function normaliseLocation(location: string): string {
+  const trimmed = location.trim();
+
+  let url: URL | undefined;
+  try {
+    url = new URL(trimmed);
+  } catch {
+    url = undefined;
+  }
+
+  // Not an absolute URL: normalise it as a bare path and stop. `new URL` would
+  // otherwise turn `example.com/x` into the `example.com:` protocol.
+  if (!url || url.protocol === '' || !url.host) {
+    return normalisePathOnly(trimmed);
+  }
+
+  // Not `decodeOnce` here: normalisePathOnly decodes, and decoding on the way
+  // in as well would decode twice — which would fold `%252F` into `%2F` into
+  // `/` and let a double-encoding target collide with a single-encoding one.
+  const path = normalisePathOnly(url.pathname);
+
+  // `url.host` already carries punycode and lower case, and omits a default
+  // port for the scheme.
+  const names = [...new Set([...url.searchParams.keys()].map(decodeOnce))].sort();
+  const query = names.length > 0 ? `?${names.join('&')}` : '';
+
+  return `${url.protocol}//${url.host}${path}${query}`;
+}
+
+/**
+ * Normalises a path with no scheme or host.
+ */
+function normalisePathOnly(path: string): string {
+  const decoded = decodeOnce(path.trim());
+  if (decoded === '' || decoded === '/') return decoded === '' ? '' : '/';
+
+  const collapsed = decoded
+    .split('/')
+    .map((segment) => collapseSegment(segment))
+    .join('/');
+
+  return collapsed.length > 1 && collapsed.endsWith('/') ? collapsed.slice(0, -1) : collapsed;
+}
+
+/**
+ * What a scanner said it found, in the terms needed to name the weakness.
+ */
+export interface VulnKeyInput {
+  /** Which engine detected it, e.g. `nuclei`, `zap`. */
+  readonly sourceEngine: string;
+
+  /** The engine's own identifier for the rule that fired. */
+  readonly sourceRuleId?: string;
+
+  /** CWE identifier, e.g. `CWE-79`. */
+  readonly cwe?: string;
+
+  /** Broad grouping, e.g. `injection`. */
+  readonly category?: string;
+}
+
+/**
+ * Maps `engine:ruleId` to a shared, engine-independent weakness key.
+ *
+ * **This table is the entire mechanism of cross-engine deduplication.** Without
+ * it a ZAP detection and a Nuclei detection of the same weakness fall back to
+ * CWE, and where either engine omits the CWE they never collide at all — you
+ * get per-engine tracking wearing the clothes of an issue tracker.
+ *
+ * **It is deliberately small, and that is not laziness.** A mapping asserts
+ * that a specific rule id means a specific weakness, and a wrong assertion
+ * silently merges two unrelated issues — worse than not mapping at all, because
+ * the merge is invisible. Rule ids cannot be known honestly until real scanner
+ * output has been parsed, which is what 4.4a and 4.4b do with committed
+ * fixtures. The table grows there, from evidence.
+ *
+ * **Entries must be added in pairs, per weakness, across engines — a half-filled
+ * table is worse than an empty one.** The mapping beats the CWE fallback, so
+ * mapping ZAP's HSTS rule while leaving Nuclei's unmapped gives them *different*
+ * keys, when falling back to `CWE-319` on both sides would have collided them
+ * correctly. Adding one engine's rule silently un-deduplicates the weakness.
+ * Found by importing a fixture from each engine and watching them stop
+ * agreeing.
+ *
+ * `00-DOMAIN.md` §10 leaves the eventual size open, leaning towards the top
+ * ~200 Nuclei templates plus ZAP's plugin list, with CWE fallback beyond.
+ *
+ * Keys are `${sourceEngine}:${sourceRuleId}`, both lowercased.
+ */
+export const VULN_KEY_MAP: Readonly<Record<string, string>> = Object.freeze({
+  // ZAP plugin ids are stable and documented, which is why the seed is ZAP's.
+  'zap:40012': 'xss-reflected',
+  'zap:40014': 'xss-persistent',
+  'zap:40018': 'sql-injection',
+  'zap:10038': 'csp-missing',
+  'zap:10035': 'hsts-missing',
+  'zap:10021': 'x-content-type-options-missing',
+  'zap:10020': 'x-frame-options-missing',
+
+  // Nuclei's side of the pairs above. Anything mapped for one engine and not
+  // the other stops the two agreeing, so these travel together.
+  'nuclei:xss-reflected': 'xss-reflected',
+  'nuclei:missing-hsts': 'hsts-missing',
+});
+
+/**
+ * The engine-independent key for a weakness class.
+ *
+ * Resolution order, per `00-DOMAIN.md` §4:
+ *
+ * 1. {@link VULN_KEY_MAP}, looked up by `engine:ruleId`.
+ * 2. `cwe` alone.
+ * 3. `category` alone.
+ * 4. `engine:ruleId` itself.
+ *
+ * **The spec says `cwe + '/' + category`, and that was tried and abandoned.**
+ * Engines do not share a category vocabulary: ZAP supplies no category at all,
+ * so reflected XSS there keys as `CWE-79`, while Nuclei tags the same finding
+ * `xss` and keys as `CWE-79/xss`. The two never collide — so the fallback
+ * actively prevented the cross-engine deduplication it exists to provide, which
+ * a fixture from each engine demonstrated immediately.
+ *
+ * CWE alone is coarser, and the coarseness is bounded: the fingerprint also
+ * carries the normalised location and the parameter, so two findings only merge
+ * when they share a weakness class *and* a place. Two genuinely different
+ * weaknesses under one CWE, at the same URL and parameter, is the case this
+ * gets wrong — and `POST /issues/{a}/merge/{b}` exists because something will.
+ *
+ * Steps 3 and 4 keep a finding trackable when there is no CWE at all. **Step 4
+ * never deduplicates across engines**, which is the honest outcome for a rule
+ * nobody has mapped: it tracks correctly and merges nothing it should not.
+ *
+ * @param input - What the engine reported.
+ * @returns The weakness key.
+ * @throws TypeError If nothing identifying is present at all.
+ */
+export function vulnKey(input: VulnKeyInput): string {
+  const engine = input.sourceEngine.trim().toLowerCase();
+  const ruleId = input.sourceRuleId?.trim().toLowerCase();
+
+  if (engine !== '' && ruleId !== undefined && ruleId !== '') {
+    const mapped = VULN_KEY_MAP[`${engine}:${ruleId}`];
+    if (mapped !== undefined) return mapped;
+  }
+
+  const cwe = input.cwe?.trim().toUpperCase();
+  const category = input.category?.trim().toLowerCase();
+
+  if (cwe !== undefined && cwe !== '') return cwe;
+  if (category !== undefined && category !== '') return category;
+  if (engine !== '' && ruleId !== undefined && ruleId !== '') return `${engine}:${ruleId}`;
+
+  throw new TypeError(
+    'cannot derive a vuln_key: a finding needs a mapped rule, a CWE, a category, or an engine rule id',
+  );
+}
+
+/**
+ * Everything the fingerprint is computed from.
+ *
+ * Note what is absent: no title, no description, no evidence, no timestamp, no
+ * severity. **Volatile evidence never enters a fingerprint** — a nonce or a
+ * response body in here would make every run look like a fresh discovery, and
+ * the product's whole claim is that it can tell you what changed.
+ */
+export interface FingerprintInput {
+  /**
+   * The target the finding is on.
+   *
+   * Part of identity, which has a surprising consequence worth stating: the
+   * same weakness in staging and in production is **two issues**. They are two
+   * systems, fixed separately, and a verification of one must never authorise
+   * the other.
+   */
+  readonly targetId: string;
+
+  /** The engine-independent weakness key, from {@link vulnKey}. */
+  readonly vulnKey: string;
+
+  /** Where it was found. Normalised by {@link normaliseLocation}. */
+  readonly location: string;
+
+  /** The parameter implicated, where the weakness has one. */
+  readonly parameter?: string;
+
+  /** The port, for findings that are about a service rather than a path. */
+  readonly port?: number;
+}
+
+/**
+ * The content address of a weakness: `sha256(targetId | vulnKey | normalised
+ * location | parameter ?? port ?? '')`.
+ *
+ * Deterministic and pure — the same input always gives the same digest, on any
+ * machine, in any order, at any time. That is what lets findings from different
+ * runs and different engines reconcile into one issue.
+ *
+ * Uses Node's `node:crypto`, which is a builtin rather than a dependency, so
+ * the package still installs nothing. It does mean fingerprinting requires
+ * Node; report rendering does not, and rendering is the only part of this
+ * package a browser was ever going to run.
+ *
+ * @param input - The identifying facts.
+ * @returns A lowercase hex SHA-256 digest.
+ *
+ * @example
+ * ```ts
+ * const key = vulnKey({ sourceEngine: 'zap', sourceRuleId: '40012' });
+ * fingerprint({ targetId: 'tgt_1', vulnKey: key, location: '/search', parameter: 'q' });
+ * ```
+ */
+export function fingerprint(input: FingerprintInput): string {
+  const tail = input.parameter ?? (input.port !== undefined ? String(input.port) : '');
+  const material = [input.targetId, input.vulnKey, normaliseLocation(input.location), tail].join(
+    '|',
+  );
+
+  return createHash('sha256').update(material, 'utf8').digest('hex');
+}