@quantakrypto/core 0.5.0 → 0.6.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 {

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 {

package/src/version.ts

@@ -3,4 +3,4 @@
  * the scan orchestrator can import it without creating a cycle through index.ts.
  * Keep in sync with packages/core/package.json.
  */
-export const VERSION = "0.5.0";
+export const VERSION = "0.6.0";

package/src/walk.ts

@@ -291,12 +291,34 @@ export function looksMinified(content: string): boolean {
   return avgLine > 1_000;
 }
 
+/** A scannable file plus the byte size the walker already stat'd for it. */
+export interface WalkedFile {
+  /** Relative POSIX path from the walk root. */
+  rel: string;
+  /** File size in bytes (from the walker's own stat; never re-stat downstream). */
+  size: number;
+}
+
 /**
  * Recursively yield scannable file paths (relative to `root`, POSIX) under a
  * directory. If `root` points at a single file, yields just that file's
- * basename (subject to the size / binary filters).
+ * basename (subject to the size / binary filters). Thin wrapper over
+ * {@link walkFilesSized} that drops the size (the historical string-yielding API).
  */
 export async function* walkFiles(root: string, options: WalkOptions = {}): AsyncGenerator<string> {
+  for await (const f of walkFilesSized(root, options)) yield f.rel;
+}
+
+/**
+ * Like {@link walkFiles} but yields each file WITH the byte size the walker
+ * already obtained while applying the size limit. Callers that need sizes (the
+ * parallel scanner's byte-balanced chunking) consume this directly so they do
+ * not stat every file a second time (P2 double-stat elimination).
+ */
+export async function* walkFilesSized(
+  root: string,
+  options: WalkOptions = {},
+): AsyncGenerator<WalkedFile> {
   const include = options.include ?? [];
   const exclude = options.exclude ?? [];
   const maxFileSize = options.maxFileSize ?? DEFAULT_MAX_FILE_SIZE;
@@ -312,7 +334,7 @@ export async function* walkFiles(root: string, options: WalkOptions = {}): Async
       isIncluded(name, include) &&
       passesSizeLimit(name, rootStat.size, maxFileSize)
     ) {
-      yield name;
+      yield { rel: name, size: rootStat.size };
     }
     return;
   }
@@ -327,20 +349,33 @@ interface WalkContext {
   ignores: readonly string[];
 }
 
+/**
+ * Manifests bypass the normal file-size cap (they carry the whole dependency
+ * tree and must not be dropped), but still get a generous hard ceiling so a
+ * pathological or hostile lockfile can't be read unbounded and OOM the scan.
+ * 16 MiB comfortably covers real monorepo lockfiles (npm's own is well under 5).
+ */
+export const MANIFEST_MAX_BYTES = 16 * 1024 * 1024;
+
 /**
  * True if a file passes the size limit. Dependency manifests (package.json /
- * package-lock.json) are exempt from the cap so large lockfiles still get
- * scanned for vulnerable dependencies instead of being silently dropped.
+ * package-lock.json / yarn.lock / …) get the larger {@link MANIFEST_MAX_BYTES}
+ * ceiling instead of the ordinary cap, so large lockfiles still get scanned for
+ * vulnerable dependencies without letting an enormous one exhaust memory.
+ * Exported for unit testing.
  */
-function passesSizeLimit(rel: string, size: number, maxFileSize: number): boolean {
-  // Dependency manifests are always read (they can exceed the size cap but carry
-  // the whole dependency tree). Uses the single {@link isManifestFile} definition.
-  if (isManifestFile(rel)) return true;
+export function passesSizeLimit(rel: string, size: number, maxFileSize: number): boolean {
+  // Uses the single {@link isManifestFile} definition.
+  if (isManifestFile(rel)) return size <= MANIFEST_MAX_BYTES;
   return size <= maxFileSize;
 }
 
 /** Internal recursive directory walker. `relDir` is POSIX-relative to the root. */
-async function* walkDir(absDir: string, relDir: string, ctx: WalkContext): AsyncGenerator<string> {
+async function* walkDir(
+  absDir: string,
+  relDir: string,
+  ctx: WalkContext,
+): AsyncGenerator<WalkedFile> {
   let entries: Dirent[];
   try {
     entries = await readdir(absDir, { withFileTypes: true });
@@ -377,13 +412,15 @@ async function* walkDir(absDir: string, relDir: string, ctx: WalkContext): Async
     if (!manifest && isBinaryPath(rel)) continue;
     if (!manifest && isGeneratedPath(rel)) continue;
 
+    let size: number;
     try {
       const s = await stat(abs);
       if (!passesSizeLimit(rel, s.size, ctx.maxFileSize)) continue;
+      size = s.size;
     } catch {
       continue;
     }
 
-    yield rel;
+    yield { rel, size };
   }
 }