@secureport/core 0.2.1 → 0.4.0

package/dist/report/model.js

@@ -0,0 +1,197 @@
+import { SEVERITY_ORDER } from '../severity.js';
+/** Works out what a run established about the issues carried into it. */
+function describeRetest(snapshot) {
+    const { baseline } = snapshot;
+    if (baseline === undefined)
+        return undefined;
+    const entries = snapshot.issues.map((issue) => ({
+        issue,
+        verdict: verdictFor(issue),
+    }));
+    // `SEVERITY_ORDER` rather than `severityRank`, which counts the other way:
+    // it returns 4 for `critical` so that a larger number is a worse problem.
+    // Sorting on it ascending put the advisories at the top of the table, which
+    // is how this shipped until a golden file showed it.
+    entries.sort((a, b) => {
+        const bySeverity = SEVERITY_ORDER.indexOf(a.issue.issue.effectiveSeverity) -
+            SEVERITY_ORDER.indexOf(b.issue.issue.effectiveSeverity);
+        return bySeverity === 0
+            ? b.issue.issue.lastSeen.getTime() - a.issue.issue.lastSeen.getTime()
+            : bySeverity;
+    });
+    const counts = {
+        fixed: 0,
+        still_present: 0,
+        returned: 0,
+        not_retested: 0,
+        new: 0,
+    };
+    for (const entry of entries)
+        counts[entry.verdict]++;
+    const checkable = counts.fixed + counts.still_present + counts.returned;
+    return {
+        baseline,
+        entries,
+        counts,
+        fixRate: checkable === 0 ? null : counts.fixed / checkable,
+    };
+}
+/**
+ * The verdict for one issue.
+ *
+ * Turns on whether this run produced evidence for it, not on its status alone:
+ * an issue left open because the run never covered it looks identical to one
+ * left open because the run found it again, and telling a reader those are the
+ * same thing is the failure this report exists to avoid.
+ */
+function verdictFor(entry) {
+    if (entry.change === 'resolved')
+        return 'fixed';
+    if (entry.change === 'regressed')
+        return 'returned';
+    if (entry.change === 'new')
+        return 'new';
+    return entry.findings.length > 0 ? 'still_present' : 'not_retested';
+}
+/** Works out what a report cannot establish, from the run rather than a template. */
+function describeLimitations(snapshot, basis) {
+    const limitations = [];
+    if (!basis.includesManual) {
+        limitations.push('This is evidence of automated security testing. It is not a human-led penetration ' +
+            'test and does not carry the assurance of one.');
+    }
+    limitations.push('Findings should be verified by a qualified technician before this document is relied ' +
+        'upon as audit evidence.');
+    limitations.push(`Testing covered only ${snapshot.run.coverage.paths.join(', ')}. Anything outside that ` +
+        'was not examined, and its absence from this document is not evidence that it is sound.');
+    limitations.push(`This reflects the state of the target as of ${snapshot.run.createdAt
+        .toISOString()
+        .slice(0, 10)}. It says nothing about the target before or after that date.`);
+    limitations.push('Automated testing cannot establish the absence of a vulnerability. A clean result means ' +
+        'nothing was detected, not that nothing is there.');
+    if (snapshot.suppressed.length > 0) {
+        limitations.push(`${snapshot.suppressed.length} finding${snapshot.suppressed.length === 1 ? ' has' : 's have'} been ` +
+            'suppressed and excluded from the counts above. They are listed in full in the appendix.');
+    }
+    limitations.push('This document does not certify compliance with any standard, framework or regulation.');
+    return limitations;
+}
+const DEFAULT_TITLES = Object.freeze({
+    pen: 'Penetration Test Report',
+    vap: 'Vulnerability Assessment Report',
+    exec: 'Executive Summary',
+    attest: 'Attestation of Security Testing',
+    retest: 'Retest Report',
+});
+/** Works out how the findings were produced, from the run rather than a claim. */
+function describeBasis(snapshot) {
+    const kind = snapshot.run.kind;
+    const engines = snapshot.run.engines;
+    const includesManual = snapshot.issues.some((i) => i.issue.origin === 'manual');
+    const automated = kind === 'scan';
+    const uploaded = kind === 'upload';
+    const parts = [];
+    if (automated) {
+        parts.push('Findings were produced by automated vulnerability scanning against the scope described below.');
+    }
+    if (uploaded) {
+        parts.push('Findings were imported from an external testing tool and reconciled against previous runs.');
+    }
+    if (kind === 'manual')
+        parts.push('Findings were recorded manually by a tester.');
+    if (includesManual && kind !== 'manual') {
+        parts.push('Some findings were recorded manually by a tester.');
+    }
+    if (!includesManual && kind !== 'manual') {
+        parts.push('No part of this assessment constitutes a manual penetration test.');
+    }
+    if (automated || uploaded) {
+        parts.push('Automated findings should be verified by a qualified technician before this report is ' +
+            'submitted as audit evidence.');
+    }
+    return { includesManual, automated, uploaded, engines, statement: parts.join(' ') };
+}
+/**
+ * Derives everything a report shows, once, from a snapshot.
+ *
+ * Both renderers consume this rather than the snapshot, so a number in the
+ * Markdown and the same number in the HTML cannot drift apart — they are the
+ * same value formatted twice.
+ *
+ * Suppressed issues are already separated by the snapshot and stay separated
+ * here: they never reach {@link ReportModel.sections}, are excluded from
+ * {@link ReportModel.outstanding} and from the exposure score, and appear only
+ * in the suppressed appendix (invariant 7).
+ *
+ * @param snapshot - Issue state as of a run.
+ * @param options - Title, attribution, and the render time.
+ * @returns The model both renderers format.
+ */
+export function buildReportModel(snapshot, options) {
+    const outstanding = {
+        critical: 0,
+        high: 0,
+        medium: 0,
+        low: 0,
+        advisory: 0,
+    };
+    const bySeverity = new Map();
+    const resolved = [];
+    let breached = 0;
+    for (const entry of snapshot.issues) {
+        if (entry.issue.status === 'resolved') {
+            resolved.push(entry);
+            continue;
+        }
+        const severity = entry.issue.effectiveSeverity;
+        const group = bySeverity.get(severity);
+        if (group)
+            group.push(entry);
+        else
+            bySeverity.set(severity, [entry]);
+        if (entry.issue.status === 'open' || entry.issue.status === 'regressed') {
+            outstanding[severity]++;
+            if (entry.slaStatus === 'breached')
+                breached++;
+        }
+    }
+    resolved.sort((a, b) => b.issue.lastSeen.getTime() - a.issue.lastSeen.getTime());
+    const sections = [];
+    for (const severity of SEVERITY_ORDER) {
+        const issues = bySeverity.get(severity);
+        if (issues === undefined || issues.length === 0)
+            continue;
+        sections.push({
+            severity,
+            // Most recently seen first: what a reader wants at the top of a section
+            // is what the latest run actually found.
+            issues: [...issues].sort((a, b) => b.issue.lastSeen.getTime() - a.issue.lastSeen.getTime()),
+        });
+    }
+    const outstandingTotal = SEVERITY_ORDER.reduce((sum, s) => sum + outstanding[s], 0);
+    const basis = describeBasis(snapshot);
+    const retest = describeRetest(snapshot);
+    // Rendering a retest of nothing is the over-claim §7 warns about: the
+    // document's whole content is a comparison, and one run does not have one.
+    if (options.kind === 'retest' && retest === undefined) {
+        throw new TypeError('a retest report needs a baseline: build the snapshot with `previous` set to the run being retested');
+    }
+    return {
+        kind: options.kind,
+        title: options.title ?? DEFAULT_TITLES[options.kind],
+        snapshot,
+        generatedAt: options.now,
+        ...(options.preparedBy === undefined ? {} : { preparedBy: options.preparedBy }),
+        ...(options.preparedFor === undefined ? {} : { preparedFor: options.preparedFor }),
+        basis,
+        limitations: describeLimitations(snapshot, basis),
+        sections,
+        resolved,
+        outstanding,
+        outstandingTotal,
+        exposureScore: snapshot.run.exposureScore,
+        breached,
+        ...(retest === undefined ? {} : { retest }),
+    };
+}
+//# sourceMappingURL=model.js.map

package/dist/report/model.js.map

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

package/dist/run.d.ts

@@ -0,0 +1,134 @@
+import type { Severity } from './severity.js';
+/**
+ * What kind of run this was.
+ *
+ * - `scan` — Secureport originated the traffic.
+ * - `upload` — someone brought results from elsewhere.
+ * - `manual` — a human recorded a finding directly.
+ *
+ * **An upload is first-class, not a lesser scan.** Much of the value is in
+ * tracking results a customer already has, and a model that treated uploads as
+ * second-class would make that path feel second-class too.
+ */
+export type RunKind = 'scan' | 'upload' | 'manual';
+/**
+ * What set the run going.
+ *
+ * Recorded on every run from the first line of code, because it is what lets
+ * you say "the Action ran 340 times this quarter" — the sentence that shows
+ * automation is actually being used rather than merely installed.
+ */
+export type RunTrigger = 'github_action' | 'cli' | 'api' | 'scheduled' | 'web';
+/**
+ * What a run actually exercised.
+ *
+ * The reason auto-resolution is 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.
+ *
+ * Scan runs record what they genuinely reached. Upload runs take a declared
+ * scope, defaulting to the whole target — the person uploading is asserting
+ * what their results cover.
+ */
+export interface Coverage {
+    /**
+     * Location patterns the run covered, as globs, e.g.
+     * `https://app.example.com/**`.
+     *
+     * An issue whose location matches none of these is untouched by this run,
+     * whatever else happened.
+     */
+    readonly paths: readonly string[];
+    /** Ports exercised, where the run was port-aware. */
+    readonly ports?: readonly number[];
+    /** Engines that took part. */
+    readonly engines: readonly string[];
+}
+/**
+ * One execution against a target.
+ */
+export interface Run {
+    /** Unique id. */
+    readonly id: string;
+    /** Organisation this run belongs to. */
+    readonly orgId: string;
+    /** Target it ran against. */
+    readonly targetId: string;
+    /** What kind of run it was. */
+    readonly kind: RunKind;
+    /** What set it going. */
+    readonly trigger: RunTrigger;
+    /** What it exercised. */
+    readonly coverage: Coverage;
+    /**
+     * The verification this run relied on, for runs that originate traffic.
+     *
+     * Recorded per run rather than per organisation, because verification
+     * belongs to a target: verifying production must never authorise scanning
+     * staging, even on the same wildcard domain (invariant 11).
+     */
+    readonly verificationId?: string;
+    /** When it started. */
+    readonly startedAt: Date;
+    /** When it finished. */
+    readonly finishedAt?: Date;
+}
+/**
+ * A count of issues per {@link Severity}.
+ *
+ * Every severity is present, including zeroes, so a report renders a complete
+ * table without deciding what a missing key means.
+ */
+export type SeverityCounts = Readonly<Record<Severity, number>>;
+/**
+ * What a run did, in the terms a reader cares about.
+ *
+ * The change summary every report opens with, and the row analytics aggregate.
+ * Computed once by reconciliation and stored, so no report has to recount
+ * findings at render time.
+ */
+export interface RunSummary {
+    /** The run this summarises. */
+    readonly runId: string;
+    /** Organisation it belongs to. */
+    readonly orgId: string;
+    /** Target it ran against. */
+    readonly targetId: string;
+    /** What kind of run it was. */
+    readonly kind: RunKind;
+    /** What set it going. */
+    readonly trigger: RunTrigger;
+    /** Engines that took part. */
+    readonly engines: readonly string[];
+    /** What the run exercised. */
+    readonly coverage: Coverage;
+    /** How long it took. */
+    readonly durationMs: number;
+    /** Issues opened for the first time by this run. */
+    readonly new: SeverityCounts;
+    /** Issues already open that this run saw again. */
+    readonly stillOpen: SeverityCounts;
+    /** Issues this run resolved. */
+    readonly resolved: SeverityCounts;
+    /** Issues that were resolved and that this run found again. */
+    readonly regressed: SeverityCounts;
+    /**
+     * Issues currently suppressed.
+     *
+     * Reported separately and **never folded into the other counts**: an ignored
+     * issue is excluded from metrics but never from the suppressed appendix
+     * (invariant 7).
+     */
+    readonly ignored: SeverityCounts;
+    /**
+     * Exposure at the end of this run.
+     *
+     * `Σ over open issues of severityWeight × min(daysOpen, 90)`. Simple,
+     * explainable and monotone — it can only fall by fixing things or by time not
+     * passing.
+     */
+    readonly exposureScore: number;
+    /** When the summary was computed. */
+    readonly createdAt: Date;
+}
+//# sourceMappingURL=run.d.ts.map

package/dist/run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../src/run.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C;;;;;;;;;;GAUG;AACH,MAAM,MAAM,OAAO,GAAG,MAAM,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAEnD;;;;;;GAMG;AACH,MAAM,MAAM,UAAU,GAAG,eAAe,GAAG,KAAK,GAAG,KAAK,GAAG,WAAW,GAAG,KAAK,CAAC;AAE/E;;;;;;;;;;GAUG;AACH,MAAM,WAAW,QAAQ;IACvB;;;;;;OAMG;IACH,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAElC,qDAAqD;IACrD,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAEnC,8BAA8B;IAC9B,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED;;GAEG;AACH,MAAM,WAAW,GAAG;IAClB,iBAAiB;IACjB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAEpB,wCAAwC;IACxC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB,6BAA6B;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B,+BAA+B;IAC/B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAEvB,yBAAyB;IACzB,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAE7B,yBAAyB;IACzB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAE5B;;;;;;OAMG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IAEjC,uBAAuB;IACvB,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC;IAEzB,wBAAwB;IACxB,QAAQ,CAAC,UAAU,CAAC,EAAE,IAAI,CAAC;CAC5B;AAED;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,QAAQ,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC;AAEhE;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB,+BAA+B;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB,kCAAkC;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB,6BAA6B;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B,+BAA+B;IAC/B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAEvB,yBAAyB;IACzB,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAE7B,8BAA8B;IAC9B,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAEpC,8BAA8B;IAC9B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAE5B,wBAAwB;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B,oDAAoD;IACpD,QAAQ,CAAC,GAAG,EAAE,cAAc,CAAC;IAE7B,mDAAmD;IACnD,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAC;IAEnC,gCAAgC;IAChC,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAElC,+DAA+D;IAC/D,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAC;IAEnC;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IAEjC;;;;;;OAMG;IACH,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAE/B,qCAAqC;IACrC,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC;CAC1B"}

package/dist/run.js

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

package/dist/run.js.map

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

package/dist/severity.d.ts

@@ -0,0 +1,191 @@
+/**
+ * How urgent an issue is.
+ *
+ * Five levels, ordered most to least urgent. `advisory` is the bottom of the
+ * scale rather than a separate "informational" category: it carries a weight of
+ * zero in the exposure score and no SLA, but it is still an issue, still
+ * tracked across runs, and still appears in reports.
+ *
+ * @see {@link SEVERITY_ORDER} for comparing two severities.
+ * @see {@link SEVERITY_WEIGHTS} for the exposure-score weights.
+ */
+export type Severity = 'critical' | 'high' | 'medium' | 'low' | 'advisory';
+/**
+ * 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 declare const SEVERITY_ORDER: readonly ["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 declare function severityRank(severity: Severity): number;
+/**
+ * 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 declare const SEVERITY_WEIGHTS: Readonly<Record<Severity, number>>;
+/**
+ * Why a finding was given the severity it has.
+ *
+ * Recorded on every finding because auditors ask, and because a severity with
+ * no provenance is not evidence. Listed here in precedence order — an earlier
+ * source wins over a later one:
+ *
+ * 1. `explicit` — stated by the scanner or the operator for this exact finding.
+ * 2. `cvss` — derived from a CVSS base score via {@link severityFromCvss}.
+ * 3. `engine_default` — the engine's own rating for the rule that fired.
+ * 4. `advisory` — taken from a published advisory for the associated CVE.
+ *
+ * Note the unfortunate collision: `advisory` is both the lowest
+ * {@link Severity} and the least-preferred severity *source*. They are
+ * unrelated — a finding can be `critical` from an `advisory` source. The names
+ * come from `00-DOMAIN.md` §3 and are kept so code and document agree.
+ */
+export type SeveritySource = 'explicit' | 'cvss' | 'engine_default' | 'advisory';
+/**
+ * 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 declare const SEVERITY_SOURCE_PRECEDENCE: readonly ["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 declare function severityFromCvss(score: number): Severity;
+/**
+ * How long each severity may stay open before it breaches, and how long before
+ * breaching an issue starts warning.
+ *
+ * A policy rather than a constant because remediation windows are a customer
+ * agreement, not a property of the domain: a payments company and a hobby
+ * project do not owe the same turnaround on a `high`.
+ *
+ * @see {@link DEFAULT_SLA_POLICY} for the shipped default.
+ */
+export interface SlaPolicy {
+    /**
+     * Days allowed to remediate an issue of each severity, from `firstSeen`.
+     *
+     * `null` means no deadline applies — the issue is tracked and reported, but
+     * it can never be "due" or "breached". `advisory` is `null` by default.
+     */
+    readonly durationDays: Readonly<Record<Severity, number | null>>;
+    /**
+     * How many days before the deadline an issue starts reporting `due_soon`.
+     *
+     * Exists so a report can distinguish "you have time" from "this is about to
+     * breach" without the reader doing arithmetic.
+     */
+    readonly dueSoonDays: number;
+}
+/**
+ * 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 declare const DEFAULT_SLA_POLICY: SlaPolicy;
+/**
+ * Where an issue stands against its remediation deadline.
+ *
+ * - `within` — inside the window, and not close enough to warn about.
+ * - `due_soon` — inside the window but within {@link SlaPolicy.dueSoonDays}.
+ * - `breached` — past the deadline.
+ *
+ * An issue with no deadline (see {@link DEFAULT_SLA_POLICY}) is always
+ * `within`: it cannot breach something it was never given.
+ */
+export type SlaStatus = 'within' | 'due_soon' | 'breached';
+/**
+ * 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 declare function slaDueAt(severity: Severity, firstSeen: Date, policy?: SlaPolicy): Date | null;
+/**
+ * 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 declare function slaStatus(dueAt: Date | null, now: Date, policy?: SlaPolicy): SlaStatus;
+//# sourceMappingURL=severity.d.ts.map

package/dist/severity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"severity.d.ts","sourceRoot":"","sources":["../src/severity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,MAAM,QAAQ,GAAG,UAAU,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,GAAG,UAAU,CAAC;AAE3E;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,4DAA6D,CAAC;AAEzF;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,CAEvD;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,gBAAgB,EAAE,QAAQ,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,CAM9D,CAAC;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG,MAAM,GAAG,gBAAgB,GAAG,UAAU,CAAC;AAEjF;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,6DAK7B,CAAC;AAEX;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,QAAQ,CASxD;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,SAAS;IACxB;;;;;OAKG;IACH,QAAQ,CAAC,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC;IAEjE;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,kBAAkB,EAAE,SAS/B,CAAC;AAEH;;;;;;;;;GASG;AACH,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,UAAU,GAAG,UAAU,CAAC;AAE3D;;;;;;;;;;;;;GAaG;AACH,wBAAgB,QAAQ,CACtB,QAAQ,EAAE,QAAQ,EAClB,SAAS,EAAE,IAAI,EACf,MAAM,GAAE,SAA8B,GACrC,IAAI,GAAG,IAAI,CAIb;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CACvB,KAAK,EAAE,IAAI,GAAG,IAAI,EAClB,GAAG,EAAE,IAAI,EACT,MAAM,GAAE,SAA8B,GACrC,SAAS,CAKX"}