@quantakrypto/core 0.5.0 → 0.7.0

package/src/index.ts

@@ -83,6 +83,42 @@ export { changedFiles } from "./changed.js";
 export { loadConfig, ConfigError, CONFIG_FILENAME } from "./config.js";
 export type { QuantakryptoFileConfig, LoadConfigResult } from "./config.js";
 
+// HNDL (harvest-now-decrypt-later) data-risk quantifier (see docs/HNDL.md).
+export {
+  HNDL_MODEL_VERSION,
+  HNDL_FILENAME,
+  SEVERITY_VULNERABILITY,
+  CONFIDENCE_WEIGHT,
+  CLASSIFICATION_SENSITIVITY,
+  NON_HNDL_DISCOUNT,
+  DEFAULT_QUANTUM_THREAT_YEARS,
+  DEFAULT_MIGRATION_HORIZON_YEARS,
+  DEFAULT_UNBOUND_CLASSIFICATION,
+  HndlError,
+  computeHndl,
+  vulnerabilityFactor,
+  moscaFactor,
+  globMatch,
+  findingFingerprint,
+  findingScope,
+  parseHndlMap,
+  loadHndlMap,
+  scaffoldHndlYaml,
+} from "./hndl.js";
+export type {
+  DataClassification,
+  HndlScope,
+  HndlDataAsset,
+  HndlHorizon,
+  HndlDefaults,
+  HndlMap,
+  ExposureRationale,
+  FindingExposure,
+  AssetExposure,
+  HndlSummary,
+  HndlReport,
+} from "./hndl.js";
+
 // Filesystem walker (relative POSIX paths, default ignores, size/binary filters).
 export { walkFiles, isBinaryPath, looksMinified } from "./walk.js";
 
@@ -122,6 +158,22 @@ export { mergeCboms } from "./cbom-merge.js";
 // OpenVEX 0.2.0 export — quantum-readiness posture as VEX statements.
 export { toOpenVex } from "./vex.js";
 export type { OpenVexDocument, OpenVexStatement, OpenVexOptions } from "./vex.js";
+// Crypto-agility manifest: agent-consumable crypto-posture document.
+export {
+  buildCryptoAgilityManifest,
+  validateCryptoAgilityManifest,
+  CRYPTO_AGILITY_MANIFEST_VERSION,
+  CRYPTO_AGILITY_WELL_KNOWN_PATH,
+} from "./crypto-agility.js";
+export type {
+  CryptoAgilityManifest,
+  CryptoAgilityManifestOptions,
+  CryptoAgilityPosture,
+  CryptoAgilityCbomSummary,
+  CryptoAgilityFamily,
+  CryptoAgilityPolicy,
+  ManifestValidation,
+} from "./crypto-agility.js";
 // ISO/IEC 27001 A.8.24 evidence-chain readiness report.
 export { buildReadinessReport, signReadinessReport, verifyReadinessReport } from "./evidence.js";
 export type {
@@ -137,6 +189,25 @@ export type {
 export { buildPolicyMapping, parseCryptoPolicy } from "./policy.js";
 export type { CryptoPolicy, PolicyVerdict, PolicyMapping, PolicyFindingVerdict } from "./policy.js";
 
+// Compliance mandates → dated, clause-named verdicts + gate (policy-as-code).
+export {
+  MANDATES,
+  mandateIds,
+  getMandate,
+  assertKnownMandates,
+  evaluateMandates,
+  mandateGateFails,
+} from "./mandates.js";
+export type {
+  Mandate,
+  MandateRule,
+  MandateRuleTier,
+  MandateStatus,
+  MandateFindingVerdict,
+  MandateEvaluation,
+  MandateGateOptions,
+} from "./mandates.js";
+
 // Remediation lookup (family + tier-aware + profile-aware) and stateful-HBS guidance.
 export {
   remediationFor,

package/src/mandates.ts

@@ -0,0 +1,365 @@
+/**
+ * Policy-as-code compliance mandates → dated, clause-named verdicts for findings.
+ *
+ * `CryptoPolicy` (policy.ts) classifies findings by algorithm family but is
+ * date-blind. A mandate adds the missing dimension: named clauses with an effective
+ * DATE ("CNSA 2.0 disallows classical public-key crypto after 2035"). The evaluator
+ * compares each finding's algorithm against the selected mandates and today's date,
+ * so a finding on a prohibited family reads as `due` (every deadline still ahead),
+ * `deprecated` (the DEPRECATE deadline has passed — a warning), or `violation` (the
+ * DISALLOW deadline has passed — a failure), always naming the governing clause,
+ * deadline, and citation. This is what turns the inventory into an enforceable,
+ * mandate-mapped gate rather than a neutral list.
+ *
+ * Pure and deterministic (the caller supplies `now`), so it is trivially testable.
+ * qScan consumes it today for the `--mandate` gate; because it operates on the
+ * shared `Finding[]`, qProbe or the GitHub Action can reuse it unchanged.
+ *
+ * Catalog scope: the two regimes that carry hard algorithm deadlines — CNSA 2.0 and
+ * NIST IR 8547. DORA / NIS2 / PCI DSS require approved cryptography but set no
+ * independent algorithm date; they inherit these timelines and are cited in docs.
+ */
+import type { AlgorithmFamily, Finding } from "./types.js";
+import { PQC_STANDARDS } from "./standards.js";
+
+/**
+ * All Shor-broken classical asymmetric families — the mandate's SCOPE. A finding
+ * on one of these is adjudicated against the selected mandates; findings on
+ * anything else (hashes, RNG, dependency, or TLS-configuration findings) are out
+ * of scope for a PQC-asymmetric mandate and are tallied as `notInScope` instead
+ * of inflating the conformant count.
+ */
+const CLASSICAL_PUBLIC_KEY: readonly AlgorithmFamily[] = [
+  "RSA",
+  "ECDH",
+  "ECDSA",
+  "EdDSA",
+  "DH",
+  "DSA",
+  "X25519",
+  "X448",
+  "ECIES",
+];
+
+/**
+ * The PROHIBITED subset the dated clauses apply to. X25519 and X448 are
+ * deliberately excluded: they are the classical half of the recommended hybrid
+ * key exchange (X25519MLKEM768 — permitted and recommended under the NIST
+ * profile), and a static scan cannot distinguish a standalone exchange from the
+ * hybrid's classical leg. Prohibiting them would false-positive exactly the orgs
+ * that hybridized correctly, so they stay in scope but read `conformant`.
+ */
+const PROHIBITED_FAMILIES: readonly AlgorithmFamily[] = CLASSICAL_PUBLIC_KEY.filter(
+  (family) => family !== "X25519" && family !== "X448",
+);
+
+/**
+ * Effective dates derived from the standards source of truth
+ * (`PQC_STANDARDS.transitionTimeline`), so a quarterly standards update moves the
+ * mandate deadlines automatically (test/standards.test.ts asserts they agree).
+ *
+ * Boundary choice: "deprecate AFTER 2030" leaves the whole stated year permitted,
+ * so each clause takes effect on the LAST day of its year (`YYYY-12-31`) —
+ * conservative by a single day, unlike `YYYY-01-01`, which would bite roughly a
+ * year early.
+ */
+const { deprecateAfter, disallowAfter } = PQC_STANDARDS.transitionTimeline;
+const DEPRECATE_EFFECTIVE = `${deprecateAfter}-12-31`;
+const DISALLOW_EFFECTIVE = `${disallowAfter}-12-31`;
+
+/** Which enforcement tier a clause encodes: warn (`deprecate`) or fail (`disallow`). */
+export type MandateRuleTier = "deprecate" | "disallow";
+
+export interface MandateRule {
+  /** The named clause this rule encodes (verbatim in the gate's failure message). */
+  clause: string;
+  /** Enforcement tier: a passed `deprecate` date warns; a passed `disallow` date fails. */
+  tier: MandateRuleTier;
+  /** Algorithm families prohibited from the effective date onward. */
+  prohibits: AlgorithmFamily[];
+  /** ISO date (YYYY-MM-DD) the prohibition takes effect. */
+  effective: string;
+  /** One-line human description of the clause. */
+  note: string;
+}
+
+export interface Mandate {
+  id: string;
+  name: string;
+  authority: string;
+  citation: string;
+  /** When this catalog entry was last reviewed against the source. */
+  asOf: string;
+  rules: MandateRule[];
+}
+
+/** The bundled mandate catalog. Keyed by `--mandate <id>`. */
+export const MANDATES: Record<string, Mandate> = {
+  "cnsa-2.0": {
+    id: "cnsa-2.0",
+    name: "CNSA 2.0",
+    authority: "NSA",
+    citation: "NSA Commercial National Security Algorithm Suite 2.0 (CNSA 2.0)",
+    asOf: "2026-07",
+    rules: [
+      {
+        clause: `CNSA 2.0 — deprecate classical PKC after ${deprecateAfter}`,
+        tier: "deprecate",
+        prohibits: [...PROHIBITED_FAMILIES],
+        effective: DEPRECATE_EFFECTIVE,
+        note: "Classical public-key cryptography deprecated; systems should use CNSA 2.0 PQC exclusively.",
+      },
+      {
+        clause: `CNSA 2.0 — disallow classical PKC after ${disallowAfter}`,
+        tier: "disallow",
+        prohibits: [...PROHIBITED_FAMILIES],
+        effective: DISALLOW_EFFECTIVE,
+        note: "Classical public-key cryptography disallowed; the migration must be complete.",
+      },
+    ],
+  },
+  "nist-ir-8547": {
+    id: "nist-ir-8547",
+    name: "NIST IR 8547",
+    authority: "NIST",
+    citation: "NIST IR 8547 (Transition to Post-Quantum Cryptography Standards)",
+    asOf: "2026-07",
+    rules: [
+      {
+        clause: `NIST IR 8547 — deprecate classical PKC after ${deprecateAfter}`,
+        tier: "deprecate",
+        prohibits: [...PROHIBITED_FAMILIES],
+        effective: DEPRECATE_EFFECTIVE,
+        note: `112-bit-security classical public-key algorithms deprecated after ${deprecateAfter}.`,
+      },
+      {
+        clause: `NIST IR 8547 — disallow classical PKC after ${disallowAfter}`,
+        tier: "disallow",
+        prohibits: [...PROHIBITED_FAMILIES],
+        effective: DISALLOW_EFFECTIVE,
+        note: `Classical public-key algorithms disallowed after ${disallowAfter}.`,
+      },
+    ],
+  },
+};
+
+export const mandateIds = (): string[] => Object.keys(MANDATES);
+export const getMandate = (id: string): Mandate | undefined => MANDATES[id];
+
+/**
+ * Validate mandate ids loudly, matching `parseCryptoPolicy`'s fail-loud
+ * convention: a mistyped id must never silently evaluate to an empty gate.
+ * Throws an `Error` naming every unknown id and the known catalog.
+ * `evaluateMandates` itself stays lenient (unknown ids are skipped) so callers
+ * decide where to fail.
+ */
+export function assertKnownMandates(ids: readonly string[]): void {
+  const unknown = ids.filter((id) => !MANDATES[id]);
+  if (unknown.length > 0) {
+    throw new Error(
+      `unknown mandate id(s): ${unknown.join(", ")}; known mandates: ${mandateIds().join(", ")}`,
+    );
+  }
+}
+
+/**
+ * A finding's status against a mandate, worst last:
+ * - `conformant` — in scope (classical asymmetric) but prohibited by no selected
+ *   clause (e.g. X25519 as the presumed hybrid leg).
+ * - `due` — prohibited, with every deadline still ahead.
+ * - `deprecated` — the DEPRECATE deadline has passed; a warning, not a failure.
+ * - `violation` — the DISALLOW deadline has passed; fails the default gate.
+ */
+export type MandateStatus = "conformant" | "due" | "deprecated" | "violation";
+
+export interface MandateFindingVerdict {
+  ruleId: string;
+  algorithm: AlgorithmFamily | "unknown";
+  file: string;
+  line: number;
+  /** Mandate id (e.g. "cnsa-2.0"). */
+  mandate: string;
+  /**
+   * The governing clause: the next upcoming clause when `due`, the passed
+   * DEPRECATE clause when `deprecated`, the passed DISALLOW clause on `violation`.
+   */
+  clause: string;
+  /** ISO effective date of the governing clause. */
+  effective: string;
+  status: MandateStatus;
+  /** Whole months from `now` to the governing deadline; negative once it has passed. */
+  monthsUntil: number;
+  /**
+   * ISO effective date of this mandate's DISALLOW clause for the family, or null
+   * when the mandate carries none. The gate's `leadMonths` measures against this.
+   */
+  disallowEffective: string | null;
+  /** Whole months from `now` to `disallowEffective`; null when there is none. */
+  monthsUntilDisallow: number | null;
+  citation: string;
+}
+
+export interface MandateEvaluation {
+  /** The `now` the evaluation was computed against (ISO). */
+  now: string;
+  /** Mandate ids evaluated. */
+  mandates: string[];
+  /**
+   * Counts of IN-SCOPE findings (classical asymmetric families) by their worst
+   * status across the selected mandates. Out-of-scope findings are excluded so
+   * the conformant count is an honest statement about asymmetric crypto only.
+   */
+  summary: Record<MandateStatus, number>;
+  /**
+   * Findings outside the mandate's scope (hashes, RNG, dependency, TLS-config…),
+   * which a PQC-asymmetric mandate does not adjudicate.
+   */
+  notInScope: number;
+  /** One row per (prohibited finding × applicable mandate). */
+  findings: MandateFindingVerdict[];
+  /** Earliest still-future deadline across non-violation rows, or null. */
+  nextDeadline: string | null;
+  /** True when at least one DISALLOW deadline has passed (a `violation` exists). */
+  hasViolation: boolean;
+}
+
+const MONTH_MS = 2_629_800_000; // average month
+
+function monthsBetween(fromMs: number, toMs: number): number {
+  return Math.round((toMs - fromMs) / MONTH_MS);
+}
+
+const STATUS_RANK: Record<MandateStatus, number> = {
+  conformant: 0,
+  due: 1,
+  deprecated: 2,
+  violation: 3,
+};
+
+/**
+ * Evaluate findings against the selected mandates as of `now`. Unknown mandate
+ * ids are ignored — callers validate up front with {@link assertKnownMandates}.
+ * A finding outside the classical-asymmetric scope is counted in `notInScope`;
+ * an in-scope finding no selected mandate prohibits is `conformant`. Neither
+ * contributes a verdict row.
+ */
+export function evaluateMandates(
+  findings: readonly Finding[],
+  mandateIdList: readonly string[],
+  now: Date,
+): MandateEvaluation {
+  const nowMs = now.getTime();
+  const selected = mandateIdList.map(getMandate).filter((m): m is Mandate => Boolean(m));
+
+  const rows: MandateFindingVerdict[] = [];
+  const perFindingWorst: MandateStatus[] = [];
+  let notInScope = 0;
+  let nextDeadlineMs: number | null = null;
+
+  for (const f of findings) {
+    const algo = f.algorithm ?? "unknown";
+    if (!CLASSICAL_PUBLIC_KEY.includes(algo as AlgorithmFamily)) {
+      notInScope++;
+      continue;
+    }
+    let worst: MandateStatus = "conformant";
+    for (const mandate of selected) {
+      // The applicable clauses for this family, earliest deadline first.
+      const applicable = mandate.rules
+        .filter((r) => r.prohibits.includes(algo as AlgorithmFamily))
+        .sort((a, b) => a.effective.localeCompare(b.effective));
+      if (applicable.length === 0) continue;
+
+      // Tier the clauses so both stay live: a passed DISALLOW clause is a
+      // violation; a passed DEPRECATE clause (disallow still ahead) is the
+      // deprecated warning tier; otherwise the finding is due against the next
+      // upcoming clause.
+      const passed = applicable.filter((r) => nowMs >= new Date(r.effective).getTime());
+      const passedDisallow = passed.filter((r) => r.tier === "disallow");
+      let status: MandateStatus;
+      let governing: MandateRule;
+      if (passedDisallow.length > 0) {
+        status = "violation";
+        governing = passedDisallow[0];
+      } else if (passed.length > 0) {
+        status = "deprecated";
+        governing = passed[passed.length - 1];
+      } else {
+        status = "due";
+        governing = applicable[0];
+      }
+
+      // The disallow clause (earliest, if several) anchors `leadMonths`.
+      const disallowRule = applicable.find((r) => r.tier === "disallow") ?? null;
+      const disallowMs = disallowRule ? new Date(disallowRule.effective).getTime() : null;
+
+      if (status !== "violation") {
+        for (const r of applicable) {
+          const effMs = new Date(r.effective).getTime();
+          if (effMs > nowMs && (nextDeadlineMs === null || effMs < nextDeadlineMs))
+            nextDeadlineMs = effMs;
+        }
+      }
+      if (STATUS_RANK[status] > STATUS_RANK[worst]) worst = status;
+      rows.push({
+        ruleId: f.ruleId,
+        algorithm: algo,
+        file: f.location.file,
+        line: f.location.line,
+        mandate: mandate.id,
+        clause: governing.clause,
+        effective: governing.effective,
+        status,
+        monthsUntil: monthsBetween(nowMs, new Date(governing.effective).getTime()),
+        disallowEffective: disallowRule ? disallowRule.effective : null,
+        monthsUntilDisallow: disallowMs !== null ? monthsBetween(nowMs, disallowMs) : null,
+        citation: mandate.citation,
+      });
+    }
+    perFindingWorst.push(worst);
+  }
+
+  const summary: Record<MandateStatus, number> = {
+    conformant: 0,
+    due: 0,
+    deprecated: 0,
+    violation: 0,
+  };
+  for (const s of perFindingWorst) summary[s]++;
+
+  return {
+    now: now.toISOString(),
+    mandates: selected.map((m) => m.id),
+    summary,
+    notInScope,
+    findings: rows,
+    nextDeadline:
+      nextDeadlineMs !== null ? new Date(nextDeadlineMs).toISOString().slice(0, 10) : null,
+    hasViolation: summary.violation > 0,
+  };
+}
+
+export interface MandateGateOptions {
+  /** Fail when a DISALLOW deadline is within this many months (early enforcement). */
+  leadMonths?: number;
+  /** Fail on any mandate-prohibited finding regardless of the deadlines. */
+  failNow?: boolean;
+}
+
+/**
+ * The gate decision under the "deadline-aware" default: fail only once a DISALLOW
+ * deadline has passed (`violation`). A passed DEPRECATE date (`deprecated`) is a
+ * warning and does not fail the build. `leadMonths` fails early when a disallow
+ * deadline is within the window; `failNow` fails on any prohibited finding
+ * immediately.
+ */
+export function mandateGateFails(ev: MandateEvaluation, opts: MandateGateOptions = {}): boolean {
+  if (ev.hasViolation) return true;
+  if (opts.failNow) return ev.findings.length > 0;
+  if (opts.leadMonths !== undefined) {
+    return ev.findings.some(
+      (v) => v.monthsUntilDisallow !== null && v.monthsUntilDisallow <= opts.leadMonths!,
+    );
+  }
+  return false;
+}

package/src/parallel.ts

@@ -17,7 +17,7 @@ import { fileURLToPath } from "node:url";
 import type { Worker as NodeWorker } from "node:worker_threads";
 
 import type { Finding, ParallelScanOptions, ScanResult } from "./types.js";
-import { walkFiles } from "./walk.js";
+import { walkFilesSized } from "./walk.js";
 import { isAnalyzableSource } from "./detect-utils.js";
 import { buildInventory } from "./inventory.js";
 import { compareFindings, filterExplicitFileList, scan } from "./scan.js";
@@ -115,30 +115,31 @@ function shouldParallelize(options: ParallelScanOptions, files: SizedFile[]): bo
  * explicit `files` list or the walker. Sizes power byte-balanced chunking.
  */
 async function enumerateFiles(options: ParallelScanOptions, baseDir: string): Promise<SizedFile[]> {
-  const rels: string[] = [];
+  const sized: SizedFile[] = [];
   if (options.files) {
+    // Explicit file list: the walker isn't involved, so stat each once here.
     // Apply the SAME include/exclude/binary filtering the serial path uses via
-    // `filterExplicitFiles`, so `--parallel` is byte-for-byte identical to serial.
-    for (const rel of filterExplicitFileList(options.files, options)) rels.push(rel);
-  } else {
-    for await (const rel of walkFiles(options.root, {
-      include: options.include,
-      exclude: options.exclude,
-      noDefaultIgnores: options.noDefaultIgnores,
-      maxFileSize: options.maxFileSize,
-    })) {
-      rels.push(rel);
+    // `filterExplicitFileList`, so `--parallel` is byte-for-byte identical to serial.
+    for (const rel of filterExplicitFileList(options.files, options)) {
+      let size = 0;
+      try {
+        size = (await stat(path.join(baseDir, ...rel.split("/")))).size;
+      } catch {
+        // Unreadable now; keep with size 0 (the worker read will skip if it's gone).
+      }
+      sized.push({ rel, size });
     }
+    return sized;
   }
 
-  const sized: SizedFile[] = [];
-  for (const rel of rels) {
-    let size = 0;
-    try {
-      size = (await stat(path.join(baseDir, ...rel.split("/")))).size;
-    } catch {
-      // Unreadable now; keep with size 0 — worker read will skip if it's gone.
-    }
+  // Directory walk: reuse the size the walker already stat'd while enforcing the
+  // size limit, so files are not stat'd a second time here (double-stat fix).
+  for await (const { rel, size } of walkFilesSized(options.root, {
+    include: options.include,
+    exclude: options.exclude,
+    noDefaultIgnores: options.noDefaultIgnores,
+    maxFileSize: options.maxFileSize,
+  })) {
     sized.push({ rel, size });
   }
   return sized;

package/src/report.ts

@@ -11,6 +11,8 @@ import { remediationFor, remediationForTier, remediationForProfile } from "./rem
 import type { SecurityTier } from "./remediation.js";
 import type { StandardsProfile } from "./standards-profiles.js";
 import { fingerprintFinding } from "./baseline.js";
+import { findingFingerprint } from "./hndl.js";
+import type { FindingExposure, HndlReport } from "./hndl.js";
 
 /** Minimal SARIF 2.1.0 log shape (kept permissive on purpose). */
 export interface SarifLog {
@@ -36,6 +38,29 @@ export interface ReportOptions {
    * {@link toJson}.
    */
   catalog?: RuleMeta[];
+  /**
+   * Optional HNDL exposure analysis ({@link computeHndl}). When supplied, each
+   * finding gains its `exposure` fields (score, bound data asset, rationale)
+   * keyed by fingerprint, and the report carries the repo-level HNDL summary.
+   * Purely additive: it never changes finding identity, ordering, or exit codes.
+   */
+  hndl?: HndlReport;
+}
+
+/** The per-finding exposure block emitted in JSON / SARIF, or undefined. */
+function exposureFor(f: Finding, hndl: HndlReport | undefined): FindingExposure | undefined {
+  if (!hndl) return undefined;
+  return hndl.byFingerprint.get(findingFingerprint(f));
+}
+
+/** The repo HNDL summary block shared by JSON output and the SARIF run. */
+function hndlSummaryBlock(hndl: HndlReport): Record<string, unknown> {
+  return {
+    modelVersion: hndl.modelVersion,
+    horizon: hndl.horizon,
+    summary: hndl.summary,
+    assets: hndl.assets,
+  };
 }
 
 const SARIF_SCHEMA =
@@ -105,6 +130,16 @@ function sarifRule(spec: {
   };
 }
 
+/** SARIF result.properties fragment for a finding's HNDL exposure, or empty. */
+function exposureProperties(exposure: FindingExposure | undefined): Record<string, unknown> {
+  if (!exposure) return {};
+  return {
+    exposureScore: exposure.exposureScore,
+    dataAsset: exposure.dataAsset,
+    exposureRationale: exposure.rationale,
+  };
+}
+
 /** Serialize a scan result as SARIF 2.1.0. */
 export function toSarif(result: ScanResult, opts?: ReportOptions): SarifLog {
   const redactSnippets = opts?.redactSnippets ?? false;
@@ -171,6 +206,10 @@ export function toSarif(result: ScanResult, opts?: ReportOptions): SarifLog {
       // edit above it. `quantakrypto/v1` names our scheme.
       partialFingerprints: { "quantakrypto/v1": fingerprintFinding(f) },
       properties: {
+        // Same stable identity mirrored into properties so non-GitHub SARIF
+        // consumers (our platform ingest) can read one uniform `fingerprint`
+        // field across JSON and SARIF without reaching into partialFingerprints.
+        fingerprint: fingerprintFinding(f),
         category: f.category,
         severity: f.severity,
         confidence: f.confidence,
@@ -178,6 +217,7 @@ export function toSarif(result: ScanResult, opts?: ReportOptions): SarifLog {
         ...(f.algorithm ? { algorithm: f.algorithm } : {}),
         ...(f.remediation ? { remediation: f.remediation } : {}),
         ...(f.cwe ? { cwe: f.cwe } : {}),
+        ...exposureProperties(exposureFor(f, opts?.hndl)),
       },
       ...(f.cwe
         ? {
@@ -233,6 +273,7 @@ export function toSarif(result: ScanResult, opts?: ReportOptions): SarifLog {
           },
         },
         ...(taxonomies.length > 0 ? { taxonomies } : {}),
+        ...(opts?.hndl ? { properties: { hndl: hndlSummaryBlock(opts.hndl) } } : {}),
         results,
       },
     ],
@@ -258,6 +299,7 @@ function securitySeverity(severity: Severity): string {
 /** Serialize a scan result as a plain JSON-friendly object. */
 export function toJson(result: ScanResult, opts?: ReportOptions): Record<string, unknown> {
   const redactSnippets = opts?.redactSnippets ?? false;
+  const hndl = opts?.hndl;
   return {
     toolVersion: result.toolVersion,
     root: result.root,
@@ -273,25 +315,48 @@ export function toJson(result: ScanResult, opts?: ReportOptions): Record<string,
       byCategory: result.inventory.byCategory,
       byAlgorithm: result.inventory.byAlgorithm,
     },
-    findings: result.findings.map((f) => ({
-      ruleId: f.ruleId,
-      title: f.title,
-      category: f.category,
-      severity: f.severity,
-      confidence: f.confidence,
-      algorithm: f.algorithm,
-      hndl: f.hndl,
-      message: f.message,
-      remediation: f.remediation,
-      cwe: f.cwe,
-      location: {
-        file: f.location.file,
-        line: f.location.line,
-        column: f.location.column,
-        endLine: f.location.endLine,
-        snippet: emittedSnippet(f, redactSnippets),
-      },
-    })),
+    ...(hndl ? { hndl: hndlSummaryBlock(hndl) } : {}),
+    findings: result.findings.map((f) => {
+      const exposure = exposureFor(f, hndl);
+      return {
+        // Stable, line-INSENSITIVE identity of the finding: sha256 of
+        // ruleId | normalized-POSIX-repo-relative-path | normalized-snippet
+        // (the SARIF partialFingerprints trick, line number deliberately
+        // excluded). Reused verbatim from the baseline module so JSON identity,
+        // SARIF partialFingerprints, and the baseline suppression set are one and
+        // the same value. A line move does NOT change it; when no snippet context
+        // exists it falls back to ruleId|path. This is the cross-run identity the
+        // platform keys posture drift on.
+        fingerprint: fingerprintFinding(f),
+        ruleId: f.ruleId,
+        title: f.title,
+        category: f.category,
+        severity: f.severity,
+        confidence: f.confidence,
+        algorithm: f.algorithm,
+        hndl: f.hndl,
+        message: f.message,
+        remediation: f.remediation,
+        cwe: f.cwe,
+        location: {
+          file: f.location.file,
+          line: f.location.line,
+          column: f.location.column,
+          endLine: f.location.endLine,
+          snippet: emittedSnippet(f, redactSnippets),
+        },
+        ...(exposure
+          ? {
+              exposure: {
+                fingerprint: exposure.fingerprint,
+                exposureScore: exposure.exposureScore,
+                dataAsset: exposure.dataAsset,
+                rationale: exposure.rationale,
+              },
+            }
+          : {}),
+      };
+    }),
   };
 }
 

package/src/types.ts

@@ -95,7 +95,15 @@ export interface Finding {
 }
 
 /** Package ecosystems the dependency scanner understands. */
-export type DependencyEcosystem = "npm" | "pypi" | "cargo" | "go" | "maven" | "rubygems" | "nuget";
+export type DependencyEcosystem =
+  | "npm"
+  | "pypi"
+  | "cargo"
+  | "go"
+  | "maven"
+  | "rubygems"
+  | "nuget"
+  | "composer";
 
 /** A known quantum-vulnerable dependency entry. */
 export interface VulnerableDependency {