securl 1.11.1 → 1.13.0

package/CHANGELOG.md

@@ -6,6 +6,18 @@ The format is based on Keep a Changelog and this package follows Semantic Versio
 
 ## [Unreleased]
 
+## [1.13.0] - 2026-06-28
+
+### Added
+- Added `buildEvidenceQualitySummary()` and the `securl/evidence-quality` package export for scan confidence, coverage gaps, and recommended follow-up.
+- Added `evidenceQuality` to completed analysis results and compact posture digests so API, mobile, and CLI clients can explain how trustworthy a scan read is.
+
+## [1.12.0] - 2026-06-27
+
+### Added
+- Added `buildPostureInsights()` and the `securl/posture-insights` package export for display-ready risk themes, top insights, and next-best actions.
+- Added `postureInsights` to completed analysis results so API, mobile, and CLI clients can render security judgement without reinterpreting raw findings.
+
 ## [1.11.1] - 2026-06-24
 
 ### Changed

package/README.md

@@ -194,7 +194,28 @@ console.log({
 
 Action-plan items include owner, effort, impact, confidence, score impact where available, evidence references, and verification guidance.
 
-### 7. Live certificate checks
+### 7. Posture insights
+
+Version `1.12.0+` includes a posture-insights helper for client surfaces that need display-ready risk themes and next-best actions.
+
+```ts
+import { analyzeUrl } from "securl";
+import { buildPostureInsights } from "securl/posture-insights";
+
+const result = await analyzeUrl("https://example.com");
+const insights = buildPostureInsights(result);
+
+console.log({
+  summary: insights.summary,
+  themes: insights.themes,
+  topInsights: insights.topInsights,
+  nextBestActions: insights.nextBestActions,
+});
+```
+
+Posture insights are derived from the action plan, so clients can render security judgement without reinterpreting raw findings, score drivers, exposure details, or vendor context.
+
+### 8. Live certificate checks
 
 Version `1.9.0+` includes a lightweight certificate helper for Cert Watch-style clients that only need the currently served TLS certificate.
 
@@ -266,6 +287,23 @@ console.log({
 });
 ```
 
+Version `1.13.0+` includes an evidence-quality helper for client surfaces that need to explain how much confidence to place in a scan result.
+
+```js
+import { buildEvidenceQualitySummary } from "securl/evidence-quality";
+
+const quality = buildEvidenceQualitySummary(resultWithEvidence);
+
+console.log({
+  level: quality.level,
+  score: quality.score,
+  gaps: quality.gaps,
+  followUp: quality.recommendedFollowUp,
+});
+```
+
+Evidence quality is also included in `buildPostureDigest()` output, so mobile and API clients can display scan confidence without loading the full result.
+
 ## Package trust and release signals
 
 - public source repository with package code under `packages/core`
@@ -313,7 +351,7 @@ It is also used by the SecURL app from the local workspace during development.
 - local package check: `npm run pack:core`
 - CI verification: `.github/workflows/core-package-checks.yml`
 - publish workflow: `.github/workflows/publish-core-package.yml`
-- publish requires an `NPM_TOKEN` repository secret
+- publish uses npm Trusted Publishing through GitHub Actions OIDC
 - publish uses npm provenance (`npm publish --provenance`)
 
 Recommended release flow:
@@ -341,6 +379,7 @@ Primary exports:
 - `buildPostureRiskEventsFromSnapshots(current, previous, diff)` - classify scan changes into alert-friendly risk events.
 - `buildPostureDigest(result)` - reduce a full scan result to a compact API/mobile-friendly digest.
 - `buildActionPlan(result)` - turn remediation, score drivers, exposure, and vendor context into prioritized fix actions.
+- `buildPostureInsights(result)` - summarize risk themes, top insights, and next-best actions for client surfaces.
 - `scanLiveCertificate(url)` - perform a TLS handshake-only certificate read for lightweight cert monitoring.
 - `buildObservationLedger(result)` - produce stable source, confidence, status, and freshness-aware posture observations.
 - `diffObservationLedgers(current, previous)` - compare stable observations and classify their operational impact.
@@ -349,18 +388,21 @@ Primary exports:
 - `buildPostureRemediationPlan(result)` - generate prioritized, owner-aware remediation actions from findings and score drivers.
 - `attachIssueEvidence(result)` - add structured evidence references to findings without changing their existing fields.
 - `buildPostureEvidenceSummary(result)` - produce compact evidence metadata for API, mobile, report, and explainability surfaces.
+- `buildEvidenceQualitySummary(result)` - summarize scan confidence, collection gaps, and recommended follow-up.
 
 Package subpath exports:
 
 - `securl/history-diff`
 - `securl/posture-digest`
 - `securl/action-plan`
+- `securl/posture-insights`
 - `securl/live-certificate`
 - `securl/observations`
 - `securl/observation-drift`
 - `securl/observation-policy`
 - `securl/posture-drift`
 - `securl/remediation-plan`
+- `securl/evidence-quality`
 - `securl/risk-events`
 - `securl/types`
 

package/RELEASING.md

@@ -35,6 +35,8 @@ git diff --name-status securl-v$(node -p "require('./packages/core/package.json'
 3. Push the tag.
 4. Let `.github/workflows/publish-core-package.yml` publish the package through short-lived npm OIDC credentials.
 
+The publish workflow verifies that the release commit is already contained in `origin/main` with `git merge-base --is-ancestor`. If a manual workflow dispatch is needed after a tag publish failure, run it from `main`; the package version comes from `packages/core/package.json`.
+
 ## Post-release
 
 1. Confirm the package is available on npm.

package/dist/evidenceQuality.d.ts

@@ -0,0 +1,2 @@
+import type { AnalysisResult, EvidenceQualitySummary } from "./types.js";
+export declare function buildEvidenceQualitySummary(analysis: AnalysisResult): EvidenceQualitySummary;

package/dist/evidenceQuality.js

@@ -0,0 +1,154 @@
+const OBSERVED_KINDS = new Set(["header", "tls", "cookie", "redirect", "dns", "html", "public_record"]);
+const normalizeArray = (value) => (Array.isArray(value) ? value : []);
+function clampScore(score) {
+    return Math.max(0, Math.min(100, Math.round(score)));
+}
+function levelForScore(score) {
+    if (score >= 80)
+        return "high";
+    if (score >= 55)
+        return "medium";
+    return "low";
+}
+function pushSignal(signals, id, label, detail, impact) {
+    signals.push({ id, label, detail, impact });
+}
+function buildSummary(level, analysis, gaps) {
+    if (analysis.assessmentLimitation?.limited) {
+        return "Evidence quality is limited because the target did not return a complete posture read.";
+    }
+    if (level === "high") {
+        return "Evidence quality is high enough to treat the posture result as a solid outside-in read.";
+    }
+    if (level === "medium") {
+        return "Evidence quality is usable, but a few collection gaps should be considered before treating the result as final.";
+    }
+    if (gaps.length > 0) {
+        return "Evidence quality is low, so treat this result as directional until the collection gaps are resolved.";
+    }
+    return "Evidence quality is low because the scan produced too little structured support for the result.";
+}
+export function buildEvidenceQualitySummary(analysis) {
+    const evidenceSummary = analysis.evidenceSummary;
+    const issues = normalizeArray(analysis.issues);
+    const timing = analysis.scanTiming;
+    const totalReferences = evidenceSummary?.totalEvidenceReferences ?? 0;
+    const observedReferences = evidenceSummary?.observedCount ?? 0;
+    const derivedReferences = evidenceSummary?.derivedCount ?? 0;
+    const observedRatio = totalReferences > 0 ? observedReferences / totalReferences : 0;
+    const kinds = Object.keys(evidenceSummary?.byKind ?? {});
+    const lowConfidence = issues.filter((issue) => issue.confidence === "low").length;
+    const mediumConfidence = issues.filter((issue) => issue.confidence === "medium").length;
+    const highConfidence = issues.filter((issue) => issue.confidence === "high").length;
+    const strengths = [];
+    const gaps = [];
+    let score = 50;
+    if (totalReferences >= 12) {
+        score += 18;
+        pushSignal(strengths, "evidence_volume", "Evidence volume", "The scan produced a broad set of structured evidence references.", "positive");
+    }
+    else if (totalReferences >= 5) {
+        score += 10;
+        pushSignal(strengths, "evidence_volume", "Evidence volume", "The scan produced enough structured evidence for a useful posture read.", "positive");
+    }
+    else {
+        score -= 18;
+        pushSignal(gaps, "low_evidence_volume", "Low evidence volume", "The scan produced fewer structured evidence references than expected.", "negative");
+    }
+    if (observedRatio >= 0.7) {
+        score += 16;
+        pushSignal(strengths, "observed_evidence", "Observed evidence", "Most evidence came from directly observed target data rather than derived context.", "positive");
+    }
+    else if (observedRatio >= 0.45) {
+        score += 6;
+    }
+    else {
+        score -= 14;
+        pushSignal(gaps, "derived_heavy", "Derived-heavy evidence", "The result relies heavily on derived evidence, so direct verification is thinner.", "negative");
+    }
+    if (kinds.length >= 5) {
+        score += 12;
+        pushSignal(strengths, "evidence_breadth", "Evidence breadth", "The scan collected evidence across several posture areas.", "positive");
+    }
+    else if (kinds.length <= 2) {
+        score -= 12;
+        pushSignal(gaps, "narrow_evidence", "Narrow evidence", "Evidence came from a small number of source types.", "negative");
+    }
+    if (analysis.assessmentLimitation?.limited) {
+        score -= 35;
+        pushSignal(gaps, "limited_assessment", "Limited assessment", analysis.assessmentLimitation.detail ?? "The target response limited collection.", "negative");
+    }
+    if (timing?.timedOut) {
+        score -= 18;
+        pushSignal(gaps, "scan_timeout", "Scan timeout", "The scan timed out before all enrichment completed.", "negative");
+    }
+    if (analysis.statusCode >= 500 || analysis.statusCode === 0) {
+        score -= 14;
+        pushSignal(gaps, "availability_status", "Availability status", `The target returned HTTP ${analysis.statusCode}, reducing confidence in the observed posture.`, "negative");
+    }
+    else if (analysis.statusCode >= 200 && analysis.statusCode < 400) {
+        score += 8;
+        pushSignal(strengths, "normal_response", "Normal response", `The target returned HTTP ${analysis.statusCode}, supporting a normal posture read.`, "positive");
+    }
+    if (lowConfidence > 0) {
+        score -= Math.min(14, lowConfidence * 4);
+        pushSignal(gaps, "low_confidence_findings", "Low-confidence findings", `${lowConfidence} finding${lowConfidence === 1 ? "" : "s"} had low confidence.`, "negative");
+    }
+    if (highConfidence > 0 && highConfidence >= lowConfidence + mediumConfidence) {
+        score += 8;
+        pushSignal(strengths, "high_confidence_findings", "High-confidence findings", "Most findings were supported with high-confidence evidence.", "positive");
+    }
+    if (!normalizeArray(analysis.headers).length) {
+        score -= 10;
+        pushSignal(gaps, "missing_header_set", "Missing header set", "No response header set was available for the scan.", "negative");
+    }
+    if (!analysis.certificate?.available) {
+        score -= 8;
+        pushSignal(gaps, "certificate_unavailable", "Certificate unavailable", "The scan could not read a served TLS certificate.", "negative");
+    }
+    else if (analysis.certificate.authorized !== false) {
+        score += 6;
+        pushSignal(strengths, "certificate_observed", "Certificate observed", "A served TLS certificate was observed during the scan.", "positive");
+    }
+    const finalScore = clampScore(score);
+    const level = levelForScore(finalScore);
+    const recommendedFollowUp = [
+        ...(analysis.assessmentLimitation?.limited ? ["Restore complete scan coverage and rescan before treating the grade as final."] : []),
+        ...(timing?.timedOut ? ["Rerun the scan with a longer timeout or narrower mode to complete enrichment."] : []),
+        ...(observedRatio < 0.45 ? ["Verify the top findings manually because direct observed evidence is thin."] : []),
+        ...(kinds.length <= 2 ? ["Collect another scan after the target returns normal headers, TLS, DNS, and HTML evidence."] : []),
+    ];
+    if (recommendedFollowUp.length === 0) {
+        recommendedFollowUp.push("Use the score drivers and top insights as the primary follow-up path.");
+    }
+    return {
+        generatedAt: new Date().toISOString(),
+        level,
+        score: finalScore,
+        summary: buildSummary(level, analysis, gaps),
+        evidence: {
+            totalReferences,
+            observedReferences,
+            derivedReferences,
+            observedRatio: Number(observedRatio.toFixed(2)),
+            kinds: kinds.filter((kind) => OBSERVED_KINDS.has(kind) || kind === "probe" || kind === "score_driver"),
+        },
+        scan: {
+            limited: Boolean(analysis.assessmentLimitation?.limited),
+            limitedKind: analysis.assessmentLimitation?.kind ?? null,
+            timedOut: Boolean(timing?.timedOut),
+            statusCode: analysis.statusCode,
+            responseTimeMs: analysis.responseTimeMs,
+        },
+        findings: {
+            total: issues.length,
+            lowConfidence,
+            mediumConfidence,
+            highConfidence,
+        },
+        strengths: strengths.slice(0, 5),
+        gaps: gaps.slice(0, 5),
+        recommendedFollowUp: recommendedFollowUp.slice(0, 4),
+        limitation: analysis.assessmentLimitation?.limited ? analysis.assessmentLimitation : null,
+    };
+}

package/dist/index.d.ts

@@ -15,6 +15,8 @@ export { buildObservationLedger } from "./observations.js";
 export { diffObservationLedgers } from "./observationDrift.js";
 export { DEFAULT_OBSERVATION_POLICY, evaluateObservationPolicy, validateObservationPolicy } from "./observationPolicy.js";
 export { buildActionPlan } from "./actionPlan.js";
+export { buildEvidenceQualitySummary } from "./evidenceQuality.js";
+export { buildPostureInsights } from "./postureInsights.js";
 export { scanLiveCertificate } from "./certificate.js";
 export { buildExposureBrief } from "./exposureBrief.js";
 export { buildVendorExposureBrief } from "./vendorExposure.js";

package/dist/index.js

@@ -2,7 +2,9 @@ import { URL } from "node:url";
 import { scanTls } from "./certificate.js";
 import { buildActionPlan } from "./actionPlan.js";
 import { buildCompromiseSignals, emptyCompromiseSignals } from "./compromiseSignals.js";
+import { buildEvidenceQualitySummary } from "./evidenceQuality.js";
 import { buildExposureBrief } from "./exposureBrief.js";
+import { buildPostureInsights } from "./postureInsights.js";
 import { buildVendorExposureBrief } from "./vendorExposure.js";
 import { parseSetCookie } from "./cookie-analysis.js";
 import { analyzeCookieHeaders } from "./cookieAnalysis.js";
@@ -510,18 +512,26 @@ async function buildLimitedResult(input, normalizedInput, failure, scanTiming) {
         remediationPlan,
         evidenceSummary: buildPostureEvidenceSummary({ ...evidenceResult, remediationPlan }),
     };
-    const resultWithBriefs = {
+    const resultWithQuality = {
         ...resultWithRemediation,
-        exposureBrief: buildExposureBrief(resultWithRemediation),
-        vendorExposure: buildVendorExposureBrief(resultWithRemediation),
+        evidenceQuality: buildEvidenceQualitySummary(resultWithRemediation),
+    };
+    const resultWithBriefs = {
+        ...resultWithQuality,
+        exposureBrief: buildExposureBrief(resultWithQuality),
+        vendorExposure: buildVendorExposureBrief(resultWithQuality),
     };
     const resultWithActions = {
         ...resultWithBriefs,
         actionPlan: buildActionPlan(resultWithBriefs),
     };
-    return {
+    const resultWithInsights = {
         ...resultWithActions,
-        observationLedger: buildObservationLedger(resultWithActions),
+        postureInsights: buildPostureInsights(resultWithActions),
+    };
+    return {
+        ...resultWithInsights,
+        observationLedger: buildObservationLedger(resultWithInsights),
     };
 }
 async function enrichCoreResult(result, profile) {
@@ -953,18 +963,26 @@ function buildTimedOutEnrichmentResult(result, pageAnalysisEnabled, timeoutMs, c
         remediationPlan,
         evidenceSummary: buildPostureEvidenceSummary({ ...evidenceResult, remediationPlan }),
     };
-    const resultWithBriefs = {
+    const resultWithQuality = {
         ...resultWithRemediation,
-        exposureBrief: buildExposureBrief(resultWithRemediation),
-        vendorExposure: buildVendorExposureBrief(resultWithRemediation),
+        evidenceQuality: buildEvidenceQualitySummary(resultWithRemediation),
+    };
+    const resultWithBriefs = {
+        ...resultWithQuality,
+        exposureBrief: buildExposureBrief(resultWithQuality),
+        vendorExposure: buildVendorExposureBrief(resultWithQuality),
     };
     const resultWithActions = {
         ...resultWithBriefs,
         actionPlan: buildActionPlan(resultWithBriefs),
     };
-    return {
+    const resultWithInsights = {
         ...resultWithActions,
-        observationLedger: buildObservationLedger(resultWithActions),
+        postureInsights: buildPostureInsights(resultWithActions),
+    };
+    return {
+        ...resultWithInsights,
+        observationLedger: buildObservationLedger(resultWithInsights),
     };
 }
 export async function analyzeUrl(input, options = {}) {
@@ -1035,18 +1053,26 @@ export async function analyzeUrl(input, options = {}) {
         remediationPlan,
         evidenceSummary: buildPostureEvidenceSummary({ ...resultWithEvidence, remediationPlan }),
     };
-    const resultWithBriefs = {
+    const resultWithQuality = {
         ...resultWithRemediation,
-        exposureBrief: buildExposureBrief(resultWithRemediation),
-        vendorExposure: buildVendorExposureBrief(resultWithRemediation),
+        evidenceQuality: buildEvidenceQualitySummary(resultWithRemediation),
+    };
+    const resultWithBriefs = {
+        ...resultWithQuality,
+        exposureBrief: buildExposureBrief(resultWithQuality),
+        vendorExposure: buildVendorExposureBrief(resultWithQuality),
     };
     const resultWithActions = {
         ...resultWithBriefs,
         actionPlan: buildActionPlan(resultWithBriefs),
     };
-    return {
+    const resultWithInsights = {
         ...resultWithActions,
-        observationLedger: buildObservationLedger(resultWithActions),
+        postureInsights: buildPostureInsights(resultWithActions),
+    };
+    return {
+        ...resultWithInsights,
+        observationLedger: buildObservationLedger(resultWithInsights),
     };
 }
 export const analyzeTarget = analyzeUrl;
@@ -1056,6 +1082,8 @@ export { buildObservationLedger } from "./observations.js";
 export { diffObservationLedgers } from "./observationDrift.js";
 export { DEFAULT_OBSERVATION_POLICY, evaluateObservationPolicy, validateObservationPolicy } from "./observationPolicy.js";
 export { buildActionPlan } from "./actionPlan.js";
+export { buildEvidenceQualitySummary } from "./evidenceQuality.js";
+export { buildPostureInsights } from "./postureInsights.js";
 export { scanLiveCertificate } from "./certificate.js";
 export { buildExposureBrief } from "./exposureBrief.js";
 export { buildVendorExposureBrief } from "./vendorExposure.js";

package/dist/postureDigest.d.ts

@@ -20,7 +20,7 @@ export declare function buildPostureDigest(analysis: AnalysisResult, { findingLi
         posture: "strong" | "weak" | "mixed";
         takeaways: string[];
         limited: boolean;
-        limitedKind: "other" | "blocked_edge_response" | "auth_required" | "rate_limited" | "service_unavailable";
+        limitedKind: "blocked_edge_response" | "auth_required" | "rate_limited" | "service_unavailable" | "other";
         limitation: import("./types.js").AssessmentLimitation;
         scoreDrivers: import("./types.js").ScoreDriver[];
     };
@@ -59,6 +59,34 @@ export declare function buildPostureDigest(analysis: AnalysisResult, { findingLi
             scoreImpact: number;
         }[];
     };
+    evidenceQuality: {
+        level: import("./types.js").EvidenceQualityLevel;
+        score: number;
+        summary: string;
+        evidence: {
+            totalReferences: number;
+            observedReferences: number;
+            derivedReferences: number;
+            observedRatio: number;
+            kinds: import("./types.js").ScanEvidenceKind[];
+        };
+        scan: {
+            limited: boolean;
+            limitedKind: import("./types.js").AssessmentLimitation["kind"];
+            timedOut: boolean;
+            statusCode: number;
+            responseTimeMs: number;
+        };
+        findings: {
+            total: number;
+            lowConfidence: number;
+            mediumConfidence: number;
+            highConfidence: number;
+        };
+        strengths: import("./types.js").EvidenceQualitySignal[];
+        gaps: import("./types.js").EvidenceQualitySignal[];
+        recommendedFollowUp: string[];
+    };
     remediationPlan: {
         summary: string;
         totalActions: number;

package/dist/postureDigest.js

@@ -1,3 +1,4 @@
+import { buildEvidenceQualitySummary } from "./evidenceQuality.js";
 const SEVERITY_ORDER = {
     critical: 0,
     warning: 1,
@@ -31,6 +32,7 @@ export function buildPostureDigest(analysis, { findingLimit = 8 } = {}) {
     const issues = normalizeArray(analysis.issues);
     const compromiseIndicators = normalizeArray(analysis.compromiseSignals?.indicators);
     const riskIndicators = compromiseIndicators.filter((indicator) => ["warning", "critical"].includes(indicator.severity));
+    const evidenceQuality = analysis.evidenceQuality ?? buildEvidenceQualitySummary(analysis);
     return {
         generatedAt: new Date().toISOString(),
         target: {
@@ -77,6 +79,17 @@ export function buildPostureDigest(analysis, { findingLimit = 8 } = {}) {
                 scoreImpact: reference.scoreImpact,
             })),
         } : null,
+        evidenceQuality: {
+            level: evidenceQuality.level,
+            score: evidenceQuality.score,
+            summary: evidenceQuality.summary,
+            evidence: evidenceQuality.evidence,
+            scan: evidenceQuality.scan,
+            findings: evidenceQuality.findings,
+            strengths: normalizeArray(evidenceQuality.strengths).slice(0, 5),
+            gaps: normalizeArray(evidenceQuality.gaps).slice(0, 5),
+            recommendedFollowUp: normalizeArray(evidenceQuality.recommendedFollowUp).slice(0, 4),
+        },
         remediationPlan: analysis.remediationPlan ? {
             summary: analysis.remediationPlan.summary,
             totalActions: analysis.remediationPlan.totalActions,

package/dist/postureInsights.d.ts

@@ -0,0 +1,2 @@
+import type { AnalysisResult, PostureInsights } from "./types.js";
+export declare function buildPostureInsights(analysis: AnalysisResult): PostureInsights;

package/dist/postureInsights.js

@@ -0,0 +1,127 @@
+import { buildActionPlan } from "./actionPlan.js";
+const SEVERITY_RANK = {
+    critical: 3,
+    warning: 2,
+    info: 1,
+};
+const THEME_LABELS = {
+    browser_hardening: "Browser hardening",
+    transport: "Transport security",
+    domain_trust: "Domain trust",
+    public_exposure: "Public exposure",
+    vendor_risk: "Vendor risk",
+    identity: "Identity surface",
+    availability: "Availability",
+    monitoring: "Monitoring",
+};
+function severityForAction(item) {
+    if (item.impact === "high" || (item.scoreImpact ?? 0) >= 10) {
+        return "critical";
+    }
+    if (item.impact === "medium" || (item.scoreImpact ?? 0) >= 4) {
+        return "warning";
+    }
+    return "info";
+}
+function highestSeverity(left, right) {
+    return SEVERITY_RANK[right] > SEVERITY_RANK[left] ? right : left;
+}
+function buildSummary(analysis, insights) {
+    if (analysis.assessmentLimitation?.limited) {
+        return "The scan was limited, so restore complete scan coverage before treating the posture read as final.";
+    }
+    if (!insights.length) {
+        return "No immediate posture action stands out from the passive evidence. Keep monitoring and rescan after meaningful changes.";
+    }
+    const critical = insights.filter((insight) => insight.severity === "critical").length;
+    if (critical > 0) {
+        return `${critical} critical insight${critical === 1 ? "" : "s"} should be reviewed first because ${critical === 1 ? "it carries" : "they carry"} the highest posture impact.`;
+    }
+    return `${insights.length} actionable insight${insights.length === 1 ? "" : "s"} ${insights.length === 1 ? "is" : "are"} available for follow-up.`;
+}
+function buildThemeSummaries(items) {
+    const themes = new Map();
+    for (const item of items) {
+        const severity = severityForAction(item);
+        const existing = themes.get(item.theme);
+        if (!existing) {
+            themes.set(item.theme, {
+                theme: item.theme,
+                label: THEME_LABELS[item.theme],
+                count: 1,
+                highestSeverity: severity,
+                highImpactActions: item.impact === "high" ? 1 : 0,
+                quickWins: item.effort === "low" ? 1 : 0,
+                owners: [item.owner],
+                scoreImpact: item.scoreImpact ?? 0,
+            });
+            continue;
+        }
+        existing.count += 1;
+        existing.highestSeverity = highestSeverity(existing.highestSeverity, severity);
+        existing.highImpactActions += item.impact === "high" ? 1 : 0;
+        existing.quickWins += item.effort === "low" ? 1 : 0;
+        existing.scoreImpact += item.scoreImpact ?? 0;
+        if (!existing.owners.includes(item.owner)) {
+            existing.owners.push(item.owner);
+        }
+    }
+    return [...themes.values()].sort((left, right) => {
+        const severityDelta = SEVERITY_RANK[right.highestSeverity] - SEVERITY_RANK[left.highestSeverity];
+        if (severityDelta !== 0)
+            return severityDelta;
+        const impactDelta = right.highImpactActions - left.highImpactActions;
+        if (impactDelta !== 0)
+            return impactDelta;
+        return right.scoreImpact - left.scoreImpact;
+    });
+}
+function toInsight(item) {
+    return {
+        id: `insight:${item.id}`,
+        title: item.title,
+        summary: item.whyNow,
+        severity: severityForAction(item),
+        theme: item.theme,
+        owner: item.owner,
+        effort: item.effort,
+        impact: item.impact,
+        confidence: item.confidence,
+        scoreImpact: item.scoreImpact,
+        nextAction: item.action,
+        verify: item.verify,
+        evidence: item.evidence,
+        relatedFindings: item.relatedFindings,
+        source: item.source,
+    };
+}
+function toNextBestAction(item) {
+    return {
+        id: item.id,
+        label: item.action,
+        theme: item.theme,
+        owner: item.owner,
+        effort: item.effort,
+        impact: item.impact,
+        severity: severityForAction(item),
+        verify: item.verify,
+    };
+}
+export function buildPostureInsights(analysis) {
+    const actionPlan = analysis.actionPlan ?? buildActionPlan(analysis);
+    const topItems = actionPlan.items.slice(0, 6);
+    const topInsights = topItems.map(toInsight);
+    const ownerOrder = ["edge", "app", "dns", "identity", "third_party"];
+    return {
+        generatedAt: new Date().toISOString(),
+        summary: buildSummary(analysis, topInsights),
+        posture: actionPlan.posture,
+        themes: buildThemeSummaries(actionPlan.items).map((theme) => ({
+            ...theme,
+            owners: [...theme.owners].sort((left, right) => ownerOrder.indexOf(left) - ownerOrder.indexOf(right)),
+        })),
+        topInsights,
+        nextBestActions: topItems.slice(0, 3).map(toNextBestAction),
+        limitation: actionPlan.limitation,
+    };
+}

package/dist/types.d.ts

@@ -172,6 +172,43 @@ export interface PostureEvidenceSummary {
     findingEvidence: PostureEvidenceSummaryReference[];
     limitation: AssessmentLimitation | null;
 }
+export type EvidenceQualityLevel = "high" | "medium" | "low";
+export interface EvidenceQualitySignal {
+    id: string;
+    label: string;
+    detail: string;
+    impact: "positive" | "negative" | "neutral";
+}
+export interface EvidenceQualitySummary {
+    generatedAt: string;
+    level: EvidenceQualityLevel;
+    score: number;
+    summary: string;
+    evidence: {
+        totalReferences: number;
+        observedReferences: number;
+        derivedReferences: number;
+        observedRatio: number;
+        kinds: ScanEvidenceKind[];
+    };
+    scan: {
+        limited: boolean;
+        limitedKind: AssessmentLimitation["kind"];
+        timedOut: boolean;
+        statusCode: number;
+        responseTimeMs: number;
+    };
+    findings: {
+        total: number;
+        lowConfidence: number;
+        mediumConfidence: number;
+        highConfidence: number;
+    };
+    strengths: EvidenceQualitySignal[];
+    gaps: EvidenceQualitySignal[];
+    recommendedFollowUp: string[];
+    limitation: AssessmentLimitation | null;
+}
 export type ExposureBriefLevel = "low" | "medium" | "high" | "critical" | "unknown";
 export type ExposureBriefCategory = "entry_point" | "trust_gap" | "abuse_signal" | "sensitive_exposure" | "third_party" | "identity" | "ai" | "infrastructure";
 export type ExposureBriefSource = "headers" | "tls" | "cookies" | "dns" | "html" | "public_record" | "third_party" | "ai" | "ct" | "api" | "exposure" | "derived";
@@ -274,6 +311,53 @@ export interface ActionPlan {
     nextReview: string;
     limitation: AssessmentLimitation | null;
 }
+export type PostureInsightSeverity = "info" | "warning" | "critical";
+export interface PostureInsightThemeSummary {
+    theme: ActionPlanTheme;
+    label: string;
+    count: number;
+    highestSeverity: PostureInsightSeverity;
+    highImpactActions: number;
+    quickWins: number;
+    owners: RemediationOwner[];
+    scoreImpact: number;
+}
+export interface PostureInsightItem {
+    id: string;
+    title: string;
+    summary: string;
+    severity: PostureInsightSeverity;
+    theme: ActionPlanTheme;
+    owner: RemediationOwner;
+    effort: RemediationEffort;
+    impact: RemediationImpact;
+    confidence: IssueConfidence;
+    scoreImpact: number | null;
+    nextAction: string;
+    verify: string;
+    evidence: ScanEvidenceReference[];
+    relatedFindings: string[];
+    source: ActionPlanItem["source"];
+}
+export interface PostureInsightAction {
+    id: string;
+    label: string;
+    theme: ActionPlanTheme;
+    owner: RemediationOwner;
+    effort: RemediationEffort;
+    impact: RemediationImpact;
+    severity: PostureInsightSeverity;
+    verify: string;
+}
+export interface PostureInsights {
+    generatedAt: string;
+    summary: string;
+    posture: ActionPlan["posture"];
+    themes: PostureInsightThemeSummary[];
+    topInsights: PostureInsightItem[];
+    nextBestActions: PostureInsightAction[];
+    limitation: AssessmentLimitation | null;
+}
 export interface CrawlPageResult {
     label: string;
     path: string;
@@ -961,9 +1045,11 @@ export interface AnalysisResult {
     remediation: RemediationSnippet[];
     remediationPlan?: RemediationPlan;
     evidenceSummary?: PostureEvidenceSummary;
+    evidenceQuality?: EvidenceQualitySummary;
     exposureBrief?: ExposureBrief;
     vendorExposure?: VendorExposureBrief;
     actionPlan?: ActionPlan;
+    postureInsights?: PostureInsights;
     crawl: CrawlSummary;
     securityTxt: SecurityTxtInfo;
     domainSecurity: DomainSecurityInfo;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "securl",
-  "version": "1.11.1",
+  "version": "1.13.0",
   "type": "module",
   "description": "Passive external security posture scanner for public URLs and web services.",
   "author": {
@@ -66,6 +66,10 @@
       "types": "./dist/postureRemediation.d.ts",
       "default": "./dist/postureRemediation.js"
     },
+    "./evidence-quality": {
+      "types": "./dist/evidenceQuality.d.ts",
+      "default": "./dist/evidenceQuality.js"
+    },
     "./exposure-brief": {
       "types": "./dist/exposureBrief.d.ts",
       "default": "./dist/exposureBrief.js"
@@ -78,6 +82,10 @@
       "types": "./dist/actionPlan.d.ts",
       "default": "./dist/actionPlan.js"
     },
+    "./posture-insights": {
+      "types": "./dist/postureInsights.d.ts",
+      "default": "./dist/postureInsights.js"
+    },
     "./live-certificate": {
       "types": "./dist/certificate.d.ts",
       "default": "./dist/certificate.js"