@secureport/core 0.2.0 → 0.3.0

package/README.md

@@ -6,17 +6,17 @@ model, one implementation.
 
 **MIT licensed. Zero runtime dependencies.**
 
-## Status: early scaffold
+## The model in one paragraph
 
-`0.2.x` is a deliberately small first release, published to prove the release
-path rather than to be built against. **The domain shapes below are being
-replaced wholesale in `0.3.0`** with the full model — `Finding`, `Issue`,
-`Run`, `RunSummary`, `Snapshot` and `Coverage`, content-addressed fingerprints,
-a CVSS-derived severity model, and a `reconcile()` that matches findings to
-issues by fingerprint rather than by title.
+A **run** produces **findings**. Findings are immutable evidence: one detection,
+in one run, with no status of its own. Each finding is fingerprinted and
+reconciled into an **issue** — the tracked record that persists across runs and
+carries status, severity, age and history. A **snapshot** is issue state as of a
+run, and is the only thing a report ever reads.
 
-If you are evaluating Secureport, wait for `0.3.0`. If you depend on `0.2.x`
-anyway, pin it exactly.
+The tracked entity is the **issue**, not the finding. Two scanners reporting the
+same weakness produce one issue with two sources, not two rows; an issue that
+comes back after being fixed is a regression, not a discovery.
 
 ## Install
 
@@ -24,36 +24,72 @@ anyway, pin it exactly.
 npm install @secureport/core
 ```
 
-## Usage
+## Status
+
+`0.3.x` ships the domain types, the severity model and the SLA policy.
+Still to come, in this order: the fingerprint, `reconcile()`, `SnapshotBuilder`
+and the scanner importers. Until `reconcile()` lands, this package describes the
+model rather than computing it.
+
+`0.2.x` had a placeholder `reconcile()` that matched issues by title. It is gone
+rather than deprecated — matching by title is not a simplified version of
+matching by fingerprint, it is a different and wrong answer.
+
+## Severity
+
+Five levels, ordered: `critical` · `high` · `medium` · `low` · `advisory`.
+
+Compare them with `severityRank`, never as strings — sorting the strings puts
+`advisory` first.
 
 ```ts
-import { reconcile, type Finding, type Issue } from '@secureport/core';
+import { severityFromCvss, severityRank, SEVERITY_WEIGHTS } from '@secureport/core';
+
+severityFromCvss(9.8); // 'critical'  — CVSS v3.1 rating scale, unchanged
+severityFromCvss(0); // 'advisory'  — CVSS calls this "None"
+
+severityRank('critical') > severityRank('high'); // true
+SEVERITY_WEIGHTS.advisory; // 0 — advisories never inflate the exposure score
+```
 
-const open: Issue[] = [
-  { id: 'ISS-1', title: 'Missing HSTS header', severity: 'medium', status: 'open' },
-];
+`severitySource` records _why_ a severity was assigned — `explicit`, `cvss`,
+`engine_default` or `advisory`, in that precedence order. A severity with no
+provenance is not evidence.
 
-const findings: Finding[] = [
-  { title: 'Missing HSTS header', severity: 'medium' },
-  { title: 'Directory listing enabled', severity: 'low' },
-];
+## Remediation deadlines
 
-let n = 2;
-const issues = reconcile(findings, open, () => `ISS-${n++}`);
-// ISS-1 is reused for the HSTS finding; ISS-2 opens for the directory listing.
+`sla_due_at` derives from an issue's **effective** severity, and both helpers
+are pure — neither reads the clock.
+
+```ts
+import { slaDueAt, slaStatus, DEFAULT_SLA_POLICY } from '@secureport/core';
+
+const due = slaDueAt('high', issue.firstSeen); // 30 days after firstSeen
+slaStatus(due, asOf); // 'within' | 'due_soon' | 'breached'
 ```
 
-## The model in one paragraph
+Windows default to 7 / 30 / 90 / 180 days for critical through low, and
+**advisory has no deadline at all** — a zero-weight severity should not
+manufacture breaches. Pass your own `SlaPolicy` to override; the defaults are
+this package's opinion, not the domain's.
 
-The tracked entity is the **issue**, not the finding. A **run** is one
-execution against a target. A **finding** is one detection within one run and
-is immutable — it never carries a status. Findings reconcile into **issues**,
-which persist across runs and carry status, severity and history. That
-distinction is the whole point of the package: two scanners reporting the same
-weakness produce one issue with two sources, not two rows.
+Deadlines run from `firstSeen`, which is never reset — so a regression does not
+give a year-old problem a fresh clock.
+
+## Reports
+
+Every report 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 someone with findings on disk and no
+account.
+
+The snapshot is the artefact; a PDF is a view of it.
 
 ## Contracts
 
-Every export is a semver contract. From `0.3.0`, `fingerprint_version` and the
-report JSON schema are versioned public contracts in their own right, and a
-deprecation policy lands before `1.0.0`.
+Every export is a semver contract. `fingerprintVersion` travels with every
+fingerprint everywhere, so a stored fingerprint can always be interpreted, and
+changing the algorithm means a migration that preserves history rather than a
+silent recomputation.
+
+A deprecation policy lands before `1.0.0`.

package/dist/coverage.d.ts

@@ -0,0 +1,21 @@
+import type { Coverage } from './run.js';
+/**
+ * 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 declare function coversLocation(location: string, coverage: Coverage): boolean;
+//# sourceMappingURL=coverage.d.ts.map

package/dist/coverage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coverage.d.ts","sourceRoot":"","sources":["../src/coverage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAwCzC;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAM5E"}

package/dist/coverage.js

@@ -0,0 +1,65 @@
+/** Escapes a literal so it can sit inside a regular expression. */
+function escapeLiteral(text) {
+    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) {
+    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) {
+    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, coverage) {
+    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));
+}
+//# sourceMappingURL=coverage.js.map

package/dist/coverage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"coverage.js","sourceRoot":"","sources":["../src/coverage.ts"],"names":[],"mappings":"AAEA,mEAAmE;AACnE,SAAS,aAAa,CAAC,IAAY;IACjC,OAAO,IAAI,CAAC,OAAO,CAAC,sBAAsB,EAAE,MAAM,CAAC,CAAC;AACtD,CAAC;AAED;;;;;;GAMG;AACH,SAAS,YAAY,CAAC,IAAY;IAChC,IAAI,GAAG,GAAG,EAAE,CAAC;IACb,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QACrB,IAAI,IAAI,KAAK,GAAG,EAAE,CAAC;YACjB,IAAI,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,GAAG,EAAE,CAAC;gBACxB,GAAG,IAAI,IAAI,CAAC;gBACZ,CAAC,EAAE,CAAC;YACN,CAAC;iBAAM,CAAC;gBACN,GAAG,IAAI,OAAO,CAAC;YACjB,CAAC;QACH,CAAC;aAAM,IAAI,IAAI,KAAK,GAAG,EAAE,CAAC;YACxB,GAAG,IAAI,MAAM,CAAC;QAChB,CAAC;aAAM,CAAC;YACN,GAAG,IAAI,aAAa,CAAC,IAAI,CAAC,CAAC;QAC7B,CAAC;IACH,CAAC;IACD,OAAO,IAAI,MAAM,CAAC,IAAI,GAAG,GAAG,EAAE,GAAG,CAAC,CAAC;AACrC,CAAC;AAED,mDAAmD;AACnD,SAAS,MAAM,CAAC,QAAgB;IAC9B,MAAM,KAAK,GAAG,kDAAkD,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAChF,OAAO,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAC9C,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,cAAc,CAAC,QAAgB,EAAE,QAAkB;IACjE,MAAM,IAAI,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC9B,IAAI,IAAI,KAAK,SAAS,IAAI,QAAQ,CAAC,KAAK,KAAK,SAAS,IAAI,QAAQ,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACpF,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC;YAAE,OAAO,KAAK,CAAC;IACnD,CAAC;IACD,OAAO,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC;AAC1E,CAAC"}

package/dist/finding.d.ts

@@ -0,0 +1,89 @@
+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;
+}
+//# sourceMappingURL=finding.d.ts.map

package/dist/finding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"finding.d.ts","sourceRoot":"","sources":["../src/finding.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAE9D;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,OAAO;IACtB,oCAAoC;IACpC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAEpB,oEAAoE;IACpE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB,gCAAgC;IAChC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB;;;;;;;OAOG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B;;;;;;;OAOG;IACH,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IAEpC,kDAAkD;IAClD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB,+CAA+C;IAC/C,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAE9B;;;;;OAKG;IACH,QAAQ,CAAC,gBAAgB,EAAE,QAAQ,CAAC;IAEpC,0DAA0D;IAC1D,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;IAExC,kEAAkE;IAClE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAE5B,kDAAkD;IAClD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAE7B,qCAAqC;IACrC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAEtB,4CAA4C;IAC5C,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAEtB;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB,6EAA6E;IAC7E,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAE3B,2DAA2D;IAC3D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B,qEAAqE;IACrE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAE5B,2EAA2E;IAC3E,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAEzC,2BAA2B;IAC3B,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IAEjC,iEAAiE;IACjE,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAExC,wEAAwE;IACxE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAE9B,2DAA2D;IAC3D,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAE/B,kEAAkE;IAClE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAE7B,qCAAqC;IACrC,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC;CAC1B"}

package/dist/finding.js

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

package/dist/finding.js.map

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

package/dist/fingerprint.d.ts

@@ -0,0 +1,185 @@
+/**
+ * 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 declare const FINGERPRINT_VERSION = "fp_v1";
+/**
+ * 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 declare const PATH_PLACEHOLDER = "{id}";
+/**
+ * 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 declare function normaliseLocation(location: string): string;
+/**
+ * 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 declare const VULN_KEY_MAP: Readonly<Record<string, string>>;
+/**
+ * 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 declare function vulnKey(input: VulnKeyInput): string;
+/**
+ * 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 declare function fingerprint(input: FingerprintInput): string;
+//# sourceMappingURL=fingerprint.d.ts.map

package/dist/fingerprint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fingerprint.d.ts","sourceRoot":"","sources":["../src/fingerprint.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,mBAAmB,UAAU,CAAC;AAQ3C;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,SAAS,CAAC;AA6BvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CA2B1D;AAiBD;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,sDAAsD;IACtD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAE9B,2DAA2D;IAC3D,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAE/B,qCAAqC;IACrC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAEtB,wCAAwC;IACxC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAcxD,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CAmBnD;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;OAOG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B,iEAAiE;IACjE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B,4DAA4D;IAC5D,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAE5B,0EAA0E;IAC1E,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,MAAM,CAO3D"}