@secureport/core 0.2.1 → 0.4.0

package/dist/severity.js

@@ -0,0 +1,171 @@
+/**
+ * Every {@link Severity}, most urgent first.
+ *
+ * Iteration order is part of the contract: report sections, severity
+ * breakdowns and count tables all render in this order, so a reader sees the
+ * same shape everywhere.
+ */
+export const SEVERITY_ORDER = ['critical', 'high', 'medium', 'low', 'advisory'];
+/**
+ * Rank of a {@link Severity}, where a **higher number is more urgent**.
+ *
+ * Use this to compare severities rather than comparing the strings, which sort
+ * alphabetically and would put `advisory` above `critical`.
+ *
+ * @param severity - The severity to rank.
+ * @returns `4` for `critical` down to `0` for `advisory`.
+ *
+ * @example
+ * ```ts
+ * severityRank(finding.detectedSeverity) > severityRank(issue.severityAtIgnore);
+ * ```
+ */
+export function severityRank(severity) {
+    return SEVERITY_ORDER.length - 1 - SEVERITY_ORDER.indexOf(severity);
+}
+/**
+ * Exposure-score weight for each {@link Severity}.
+ *
+ * `exposure_score = Σ over open issues of weight × min(daysOpen, 90)`.
+ *
+ * `advisory` weighs nothing, so advisories never inflate the number — they are
+ * tracked and reported, but they do not represent exposure.
+ *
+ * These weights are **placeholders** until ten design partners have looked at
+ * the number, and are stated as such in `00-DOMAIN.md` §8. Treat a change to
+ * them as a change to a published contract.
+ */
+export const SEVERITY_WEIGHTS = Object.freeze({
+    critical: 10,
+    high: 5,
+    medium: 2,
+    low: 1,
+    advisory: 0,
+});
+/**
+ * Every {@link SeveritySource}, most authoritative first.
+ *
+ * The order is the precedence rule: when two sources offer a severity for the
+ * same finding, the one appearing earlier here wins.
+ */
+export const SEVERITY_SOURCE_PRECEDENCE = [
+    'explicit',
+    'cvss',
+    'engine_default',
+    'advisory',
+];
+/**
+ * Maps a CVSS base score to a {@link Severity}.
+ *
+ * Uses the CVSS v3.1 qualitative severity rating scale unchanged, so a score
+ * rated "High" by any other tool is rated `high` here. The one adaptation is
+ * at the bottom: CVSS calls `0.0` "None", and this model has no "none", so it
+ * becomes `advisory`.
+ *
+ * | CVSS score  | CVSS rating | {@link Severity} |
+ * | ----------- | ----------- | ---------------- |
+ * | 9.0 – 10.0  | Critical    | `critical`       |
+ * | 7.0 – 8.9   | High        | `high`           |
+ * | 4.0 – 6.9   | Medium      | `medium`         |
+ * | 0.1 – 3.9   | Low         | `low`            |
+ * | 0.0         | None        | `advisory`       |
+ *
+ * @param score - A CVSS base score between 0 and 10.
+ * @returns The corresponding severity.
+ * @throws RangeError If `score` is outside 0–10 or is not a number. A score
+ * that cannot be mapped is a data problem worth surfacing, not something to
+ * silently round into `advisory`.
+ *
+ * @example
+ * ```ts
+ * severityFromCvss(9.8); // 'critical'
+ * severityFromCvss(0);   // 'advisory'
+ * ```
+ */
+export function severityFromCvss(score) {
+    if (!Number.isFinite(score) || score < 0 || score > 10) {
+        throw new RangeError(`CVSS score must be between 0 and 10, received ${String(score)}`);
+    }
+    if (score >= 9)
+        return 'critical';
+    if (score >= 7)
+        return 'high';
+    if (score >= 4)
+        return 'medium';
+    if (score > 0)
+        return 'low';
+    return 'advisory';
+}
+/**
+ * The default remediation windows.
+ *
+ * Chosen to be defensible rather than derived: they line up with the windows
+ * most vulnerability-management programmes already run, so a customer can
+ * adopt them without an argument and override them without a migration.
+ *
+ * `advisory` has no deadline at all. Giving a zero-weight severity a due date
+ * would manufacture breaches out of things nobody agreed to fix.
+ *
+ * | Severity   | Window   |
+ * | ---------- | -------- |
+ * | `critical` | 7 days   |
+ * | `high`     | 30 days  |
+ * | `medium`   | 90 days  |
+ * | `low`      | 180 days |
+ * | `advisory` | none     |
+ *
+ * **These are defaults, not the domain.** `00-DOMAIN.md` says only that
+ * `sla_due_at` is "derived from effective severity"; the numbers are this
+ * package's opinion and are meant to be replaced by an org's own policy.
+ */
+export const DEFAULT_SLA_POLICY = Object.freeze({
+    durationDays: Object.freeze({
+        critical: 7,
+        high: 30,
+        medium: 90,
+        low: 180,
+        advisory: null,
+    }),
+    dueSoonDays: 7,
+});
+/**
+ * When an issue of this severity, first seen at this moment, is due.
+ *
+ * Pure: the deadline is computed from the arguments alone, so the same inputs
+ * always give the same answer and a test needs no control over the clock.
+ *
+ * @param severity - The issue's **effective** severity, not its detected one —
+ * an override is a deliberate statement about how urgent something is, and the
+ * deadline should follow it.
+ * @param firstSeen - When the issue was first seen. Never the current run:
+ * `first_seen` is never reset, so neither is the deadline (invariant 4).
+ * @param policy - The remediation windows to apply.
+ * @returns The deadline, or `null` where the severity has no window.
+ */
+export function slaDueAt(severity, firstSeen, policy = DEFAULT_SLA_POLICY) {
+    const days = policy.durationDays[severity];
+    if (days === null)
+        return null;
+    return new Date(firstSeen.getTime() + days * 24 * 60 * 60 * 1000);
+}
+/**
+ * Where an issue stands against a deadline, as of a given moment.
+ *
+ * Pure, and takes `now` explicitly rather than reading the clock, so a report
+ * rendered for a past run reports the status *as of that run* rather than as of
+ * today.
+ *
+ * @param dueAt - The deadline from {@link slaDueAt}, or `null` for no deadline.
+ * @param now - The moment to evaluate against.
+ * @param policy - Supplies the `due_soon` window.
+ * @returns The status. Always `within` when `dueAt` is `null`.
+ */
+export function slaStatus(dueAt, now, policy = DEFAULT_SLA_POLICY) {
+    if (dueAt === null)
+        return 'within';
+    if (now.getTime() > dueAt.getTime())
+        return 'breached';
+    const warnFrom = dueAt.getTime() - policy.dueSoonDays * 24 * 60 * 60 * 1000;
+    return now.getTime() >= warnFrom ? 'due_soon' : 'within';
+}
+//# sourceMappingURL=severity.js.map

package/dist/severity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"severity.js","sourceRoot":"","sources":["../src/severity.ts"],"names":[],"mappings":"AAaA;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,UAAU,CAAU,CAAC;AAEzF;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,YAAY,CAAC,QAAkB;IAC7C,OAAO,cAAc,CAAC,MAAM,GAAG,CAAC,GAAG,cAAc,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;AACtE,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAuC,MAAM,CAAC,MAAM,CAAC;IAChF,QAAQ,EAAE,EAAE;IACZ,IAAI,EAAE,CAAC;IACP,MAAM,EAAE,CAAC;IACT,GAAG,EAAE,CAAC;IACN,QAAQ,EAAE,CAAC;CACZ,CAAC,CAAC;AAqBH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG;IACxC,UAAU;IACV,MAAM;IACN,gBAAgB;IAChB,UAAU;CACF,CAAC;AAEX;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAa;IAC5C,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,IAAI,KAAK,GAAG,EAAE,EAAE,CAAC;QACvD,MAAM,IAAI,UAAU,CAAC,iDAAiD,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IACzF,CAAC;IACD,IAAI,KAAK,IAAI,CAAC;QAAE,OAAO,UAAU,CAAC;IAClC,IAAI,KAAK,IAAI,CAAC;QAAE,OAAO,MAAM,CAAC;IAC9B,IAAI,KAAK,IAAI,CAAC;QAAE,OAAO,QAAQ,CAAC;IAChC,IAAI,KAAK,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC;IAC5B,OAAO,UAAU,CAAC;AACpB,CAAC;AA8BD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAc,MAAM,CAAC,MAAM,CAAC;IACzD,YAAY,EAAE,MAAM,CAAC,MAAM,CAAC;QAC1B,QAAQ,EAAE,CAAC;QACX,IAAI,EAAE,EAAE;QACR,MAAM,EAAE,EAAE;QACV,GAAG,EAAE,GAAG;QACR,QAAQ,EAAE,IAAI;KACf,CAAC;IACF,WAAW,EAAE,CAAC;CACf,CAAC,CAAC;AAcH;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,QAAQ,CACtB,QAAkB,EAClB,SAAe,EACf,SAAoB,kBAAkB;IAEtC,MAAM,IAAI,GAAG,MAAM,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC;IAC3C,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC/B,OAAO,IAAI,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,GAAG,IAAI,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;AACpE,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,SAAS,CACvB,KAAkB,EAClB,GAAS,EACT,SAAoB,kBAAkB;IAEtC,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,QAAQ,CAAC;IACpC,IAAI,GAAG,CAAC,OAAO,EAAE,GAAG,KAAK,CAAC,OAAO,EAAE;QAAE,OAAO,UAAU,CAAC;IACvD,MAAM,QAAQ,GAAG,KAAK,CAAC,OAAO,EAAE,GAAG,MAAM,CAAC,WAAW,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;IAC5E,OAAO,GAAG,CAAC,OAAO,EAAE,IAAI,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,QAAQ,CAAC;AAC3D,CAAC"}

package/dist/snapshot-builder.d.ts

@@ -0,0 +1,78 @@
+import type { Finding } from './finding.js';
+import type { Run } from './run.js';
+import type { Snapshot, Target } from './snapshot.js';
+import { type SlaPolicy } from './severity.js';
+/**
+ * Everything needed to turn a run's findings into a report-ready snapshot.
+ */
+export interface BuildSnapshotInput {
+    /** The system under test. */
+    readonly target: Target;
+    /** The run being reported on. */
+    readonly run: Run;
+    /** The findings it produced. */
+    readonly findings: readonly Finding[];
+    /**
+     * The previous snapshot, if there is one.
+     *
+     * **This is what makes a retest work with no account and no database.** The
+     * prior snapshot carries the issues, so a second run can tell what is new,
+     * what is still open, what got fixed and what came back — from a JSON file on
+     * disk. Parse it with {@link parseSnapshot}.
+     */
+    readonly previous?: Snapshot;
+    /** The moment being reported at. */
+    readonly now: Date;
+    /** Supplies ids for issues and events. */
+    readonly newId: () => string;
+    /** Remediation windows. */
+    readonly slaPolicy?: SlaPolicy;
+    /** Consecutive covering misses before an issue resolves. */
+    readonly autoResolveThreshold?: number;
+    /** How long the run took. */
+    readonly durationMs?: number;
+}
+/**
+ * Builds the {@link Snapshot} a report renders from.
+ *
+ * Runs {@link reconcile} over the previous snapshot's issues and this run's
+ * findings, then works out what changed for each issue and precomputes the
+ * things a template would otherwise each derive slightly differently —
+ * `daysOpen`, `slaStatus`, and which findings are the evidence.
+ *
+ * **Two runs on disk are enough.** No account, no database: the previous
+ * snapshot is the state, and this function is the only thing that has to
+ * understand it. That is the whole bring-your-own-findings path.
+ *
+ * Suppressed issues are separated out into {@link Snapshot.suppressed} and do
+ * not appear in {@link Snapshot.issues}, so a template cannot count an accepted
+ * risk as an open one (invariant 7).
+ *
+ * @param input - The run, its findings, and optionally the previous snapshot.
+ * @returns A snapshot, ready to render.
+ */
+export declare function buildSnapshot(input: BuildSnapshotInput): Snapshot;
+/**
+ * Parses a snapshot written to disk, restoring the `Date` objects JSON lost.
+ *
+ * `JSON.stringify` turns every date into a string and `JSON.parse` leaves it as
+ * one, so a snapshot round-tripped through a file is **not** a `Snapshot` — its
+ * dates are strings wearing the type. Everything that then compares or
+ * subtracts them silently produces nonsense rather than failing.
+ *
+ * Use this rather than `JSON.parse` for any snapshot read back from disk.
+ *
+ * **It checks the shape, because this is where untrusted JSON enters.** A
+ * snapshot arrives from a file somebody chose, and the signature promises a
+ * `Snapshot` — so returning whatever parsed and letting the caller discover
+ * the difference is the function lying about its own return type. The check is
+ * deliberately shallow: the top-level shape, which is enough to tell a
+ * snapshot from any other JSON document and to make the failure say so.
+ *
+ * @param json - The contents of a snapshot file.
+ * @returns The snapshot, with dates revived.
+ * @throws SyntaxError If the text is not valid JSON.
+ * @throws TypeError If the JSON parsed but is not a snapshot.
+ */
+export declare function parseSnapshot(json: string): Snapshot;
+//# sourceMappingURL=snapshot-builder.d.ts.map

package/dist/snapshot-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-builder.d.ts","sourceRoot":"","sources":["../src/snapshot-builder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAE5C,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AACpC,OAAO,KAAK,EAAe,QAAQ,EAAkC,MAAM,EAAE,MAAM,eAAe,CAAC;AACnG,OAAO,EAAiC,KAAK,SAAS,EAAE,MAAM,eAAe,CAAC;AAG9E;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,6BAA6B;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB,iCAAiC;IACjC,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC;IAElB,gCAAgC;IAChC,QAAQ,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAC;IAEtC;;;;;;;OAOG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAE7B,oCAAoC;IACpC,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC;IAEnB,0CAA0C;IAC1C,QAAQ,CAAC,KAAK,EAAE,MAAM,MAAM,CAAC;IAE7B,2BAA2B;IAC3B,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC;IAE/B,4DAA4D;IAC5D,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAEvC,6BAA6B;IAC7B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAuBD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,QAAQ,CAyEjE;AAiBD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CA0BpD"}

package/dist/snapshot-builder.js

@@ -0,0 +1,172 @@
+import { DEFAULT_SLA_POLICY, slaStatus } from './severity.js';
+import { reconcile } from './reconcile.js';
+/**
+ * The key a finding and an issue share when they are the same issue.
+ *
+ * Mirrors the one reconciliation uses, including the version: a fingerprint
+ * means nothing without the algorithm that produced it. The separator is an
+ * escape rather than a literal control character — writing it as a raw byte has
+ * now put an invisible NUL into two source files, and `scripts/check-text.sh`
+ * exists because nothing else noticed.
+ */
+function issueKey(of) {
+    return `${of.fingerprintVersion}\u0000${of.fingerprint}`;
+}
+/** Whole days between two moments, floored. */
+function daysBetween(from, to) {
+    return Math.max(0, Math.floor((to.getTime() - from.getTime()) / 86_400_000));
+}
+/**
+ * Builds the {@link Snapshot} a report renders from.
+ *
+ * Runs {@link reconcile} over the previous snapshot's issues and this run's
+ * findings, then works out what changed for each issue and precomputes the
+ * things a template would otherwise each derive slightly differently —
+ * `daysOpen`, `slaStatus`, and which findings are the evidence.
+ *
+ * **Two runs on disk are enough.** No account, no database: the previous
+ * snapshot is the state, and this function is the only thing that has to
+ * understand it. That is the whole bring-your-own-findings path.
+ *
+ * Suppressed issues are separated out into {@link Snapshot.suppressed} and do
+ * not appear in {@link Snapshot.issues}, so a template cannot count an accepted
+ * risk as an open one (invariant 7).
+ *
+ * @param input - The run, its findings, and optionally the previous snapshot.
+ * @returns A snapshot, ready to render.
+ */
+export function buildSnapshot(input) {
+    const slaPolicy = input.slaPolicy ?? DEFAULT_SLA_POLICY;
+    const priorIssues = [
+        ...(input.previous?.issues.map((i) => i.issue) ?? []),
+        ...(input.previous?.suppressed.map((s) => s.issue) ?? []),
+    ];
+    const priorById = new Map(priorIssues.map((i) => [i.id, i]));
+    const { issues, summary } = reconcile({
+        issues: priorIssues,
+        findings: input.findings,
+        run: input.run,
+        now: input.now,
+        newId: input.newId,
+        slaPolicy,
+        ...(input.autoResolveThreshold === undefined
+            ? {}
+            : { autoResolveThreshold: input.autoResolveThreshold }),
+        ...(input.durationMs === undefined ? {} : { durationMs: input.durationMs }),
+    });
+    // Evidence, grouped by the issue it belongs to.
+    const byFingerprint = new Map();
+    for (const finding of input.findings) {
+        const key = issueKey(finding);
+        const existing = byFingerprint.get(key);
+        if (existing)
+            existing.push(finding);
+        else
+            byFingerprint.set(key, [finding]);
+    }
+    const reported = [];
+    const suppressed = [];
+    for (const issue of issues) {
+        if (issue.status === 'ignored') {
+            suppressed.push({
+                issue,
+                reason: issue.ignoreReason ?? 'accepted_risk',
+                comment: issue.ignoreComment ?? '',
+                ignoredBy: issue.ignoredBy ?? 'unknown',
+                ignoredAt: issue.lastSeen,
+                ...(issue.ignoreExpiresAt === undefined ? {} : { expiresAt: issue.ignoreExpiresAt }),
+                severityAtIgnore: issue.severityAtIgnore ?? issue.effectiveSeverity,
+            });
+            continue;
+        }
+        const prior = priorById.get(issue.id);
+        let change;
+        if (prior === undefined)
+            change = 'new';
+        else if (issue.status === 'resolved')
+            change = 'resolved';
+        else if (issue.status === 'regressed' && prior.status !== 'regressed')
+            change = 'regressed';
+        else
+            change = 'still_open';
+        reported.push({
+            issue,
+            change,
+            // From firstSeen, which is never reset, so a regression does not make a
+            // year-old problem look new.
+            daysOpen: daysBetween(issue.firstSeen, input.now),
+            slaStatus: slaStatus(issue.slaDueAt ?? null, input.now, slaPolicy),
+            findings: byFingerprint.get(issueKey(issue)) ?? [],
+        });
+    }
+    return {
+        run: summary,
+        ...(input.previous === undefined ? {} : { baseline: input.previous.run }),
+        target: input.target,
+        issues: reported,
+        suppressed,
+    };
+}
+/** Every field in the snapshot tree that JSON turns into a string. */
+const DATE_FIELDS = new Set([
+    'createdAt',
+    'firstSeen',
+    'lastSeen',
+    'resolvedAt',
+    'reopenedAt',
+    'slaDueAt',
+    'severityOverriddenAt',
+    'ignoreExpiresAt',
+    'ignoredAt',
+    'startedAt',
+    'finishedAt',
+]);
+/**
+ * Parses a snapshot written to disk, restoring the `Date` objects JSON lost.
+ *
+ * `JSON.stringify` turns every date into a string and `JSON.parse` leaves it as
+ * one, so a snapshot round-tripped through a file is **not** a `Snapshot` — its
+ * dates are strings wearing the type. Everything that then compares or
+ * subtracts them silently produces nonsense rather than failing.
+ *
+ * Use this rather than `JSON.parse` for any snapshot read back from disk.
+ *
+ * **It checks the shape, because this is where untrusted JSON enters.** A
+ * snapshot arrives from a file somebody chose, and the signature promises a
+ * `Snapshot` — so returning whatever parsed and letting the caller discover
+ * the difference is the function lying about its own return type. The check is
+ * deliberately shallow: the top-level shape, which is enough to tell a
+ * snapshot from any other JSON document and to make the failure say so.
+ *
+ * @param json - The contents of a snapshot file.
+ * @returns The snapshot, with dates revived.
+ * @throws SyntaxError If the text is not valid JSON.
+ * @throws TypeError If the JSON parsed but is not a snapshot.
+ */
+export function parseSnapshot(json) {
+    const parsed = JSON.parse(json, (key, value) => {
+        if (DATE_FIELDS.has(key) && typeof value === 'string') {
+            const parsed = new Date(value);
+            if (!Number.isNaN(parsed.getTime()))
+                return parsed;
+        }
+        return value;
+    });
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new TypeError('not a snapshot: expected a JSON object');
+    }
+    const record = parsed;
+    for (const field of ['run', 'target']) {
+        const value = record[field];
+        if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+            throw new TypeError(`not a snapshot: \`${field}\` is missing`);
+        }
+    }
+    for (const field of ['issues', 'suppressed']) {
+        if (!Array.isArray(record[field])) {
+            throw new TypeError(`not a snapshot: \`${field}\` is missing`);
+        }
+    }
+    return parsed;
+}
+//# sourceMappingURL=snapshot-builder.js.map

package/dist/snapshot-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-builder.js","sourceRoot":"","sources":["../src/snapshot-builder.ts"],"names":[],"mappings":"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"}

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,6 +1,6 @@
 {
   "name": "@secureport/core",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "description": "Shared domain model for Secureport. Imported by the hosted API the same way a third party would.",
   "keywords": [
     "security",
@@ -18,9 +18,9 @@
     "nessus",
     "security-reporting"
   ],
-  "homepage": "https://github.com/agbjordan/secureport/tree/main/packages/core#readme",
+  "homepage": "https://secureport.io/",
   "bugs": {
-    "url": "https://github.com/agbjordan/secureport/issues"
+    "email": "hello@secureport.io"
   },
   "type": "module",
   "main": "./dist/index.js",
@@ -37,6 +37,7 @@
     "LICENSE"
   ],
   "devDependencies": {
+    "@types/node": "^22.20.1",
     "typescript": "^5.7.2"
   },
   "license": "MIT",
@@ -49,7 +50,7 @@
     "access": "public"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.json",
+    "build": "rm -rf dist && tsc -p tsconfig.json",
     "typecheck": "tsc --noEmit"
   }
 }