@quantakrypto/core 0.4.1 → 0.4.3

package/src/remediation.ts

@@ -1,8 +1,9 @@
 /**
  * Post-quantum remediation guidance for each classical asymmetric algorithm
- * family. The recommendations follow NIST's standardized PQC algorithms
- * (ML-KEM / FIPS 203, ML-DSA / FIPS 204, SLH-DSA / FIPS 205) and the IETF
- * hybrid key-exchange drafts (X25519MLKEM768).
+ * family. The recommendations follow NIST's finalized PQC algorithms — ML-KEM
+ * (FIPS 203), ML-DSA (FIPS 204), SLH-DSA (FIPS 205) — and the IETF hybrid
+ * key-exchange groups (X25519MLKEM768, SecP384r1MLKEM1024). Forward-looking
+ * standards to track are captured in {@link PQC_TRANSITION_NOTE}.
  */
 import type { AlgorithmFamily, Remediation } from "./types.js";
 
@@ -63,19 +64,21 @@ const REMEDIATIONS: Record<AlgorithmFamily, Remediation> = {
   },
   X448: {
     algorithm: "X448",
-    recommendation: "hybrid X25519MLKEM768 (ML-KEM-768)",
+    recommendation: "hybrid SecP384r1MLKEM1024 (or X25519MLKEM768)",
     detail:
       "X448 (Goldilocks curve) is a modern classical key-agreement primitive at a " +
       "higher classical security level, but it is still broken by Shor's algorithm. " +
-      "Adopt a hybrid PQC KEM (X25519MLKEM768 / ML-KEM-768) during the transition.",
+      "To preserve that assurance level, prefer the SecP384r1MLKEM1024 hybrid " +
+      "(ML-KEM-1024); X25519MLKEM768 is acceptable at the commercial tier.",
   },
   ECIES: {
     algorithm: "ECIES",
-    recommendation: "ML-KEM-768 hybrid encryption",
+    recommendation: "ML-KEM-768 hybrid encryption (X-Wing for HPKE)",
     detail:
       "ECIES relies on classical ECDH for its key encapsulation and is exposed to " +
-      "harvest-now-decrypt-later. Replace the KEM step with ML-KEM-768 (FIPS 203), " +
-      "preferably in a hybrid construction.",
+      "harvest-now-decrypt-later. Replace the KEM step with ML-KEM-768 (FIPS 203) in " +
+      "a hybrid construction — for HPKE-style application-layer encryption, X-Wing " +
+      "(X25519 + ML-KEM-768) is the emerging hybrid KEM target.",
   },
   unknown: {
     algorithm: "unknown",
@@ -160,7 +163,24 @@ export function remediationForTier(
   const base = REMEDIATIONS[algorithm];
   const params = TIER_PARAMS[tier];
   // Confidentiality families lean on the KEM; signature families on the signer.
-  const primary = isConfidentialityFamily(algorithm) ? params.kem : params.signature;
+  const isConf = isConfidentialityFamily(algorithm);
+  const primary = isConf ? params.kem : params.signature;
+
+  // Category-5 (CNSA 2.0 / NSS) mandates the ML-KEM-1024 / ML-DSA-87 parameter
+  // sets and must NOT surface the category-3 X25519MLKEM768 hybrid (its PQC
+  // component is ML-KEM-768 — sub-CNSA). Lead with the mandated set; only point
+  // at a hybrid TLS group at the 1024 level (audit: quantum #1, crypto S5).
+  if (tier === "category-5") {
+    const hybridNote = isConf
+      ? " If a hybrid TLS group is required, use SecP384r1MLKEM1024 (draft-ietf-tls-ecdhe-mlkem) — not X25519MLKEM768, whose ML-KEM-768 component does not meet CNSA 2.0."
+      : "";
+    return {
+      algorithm,
+      recommendation: `${primary} — CNSA 2.0 mandates this parameter set (hybrids optional)`,
+      detail: `${base.detail} ${params.note} For CNSA 2.0 / national-security systems use ${params.kem} (KEM) and ${params.signature} (signatures).${hybridNote}`,
+    };
+  }
+
   return {
     algorithm,
     recommendation: `${base.recommendation} — ${tier}: ${primary}`,
@@ -182,6 +202,18 @@ export const STATEFUL_HBS_NOTE =
   "Use only with rigorous state management; otherwise prefer stateless ML-DSA " +
   "(FIPS 204) or SLH-DSA (FIPS 205).";
 
+/**
+ * Forward-looking PQC standards worth tracking beyond the current FIPS 203/204/205
+ * targets. Surfaced for operators planning multi-year migrations.
+ */
+export const PQC_TRANSITION_NOTE =
+  "Migration urgency: NIST IR 8547 deprecates classical public-key crypto after " +
+  "2030 and disallows it after 2035 — long-lived (harvest-now-decrypt-later) data " +
+  "must move sooner. Standards to track: HQC (NIST's code-based backup KEM, " +
+  "selected March 2025; draft FIPS expected ~2026) as a diversity hedge against " +
+  "ML-KEM; FN-DSA / Falcon (draft FIPS 206) for compact lattice signatures; and " +
+  "X-Wing (X25519 + ML-KEM-768) for HPKE-style hybrid encryption.";
+
 /** True when stateful HBS (SP 800-208) is a reasonable alternative for a family. */
 export function statefulHbsApplies(algorithm: AlgorithmFamily): boolean {
   // Signature families only — LMS/XMSS are signatures, not KEMs.

package/src/report.ts

@@ -3,10 +3,12 @@
  * or a human-readable text summary. No third-party dependencies — ANSI colour
  * is emitted with raw escape codes and is off by default.
  */
-import type { Finding, RuleMeta, ScanResult, Severity } from "./types.js";
+import type { AlgorithmFamily, Finding, RuleMeta, ScanResult, Severity } from "./types.js";
 import { VERSION } from "./version.js";
 import { SEVERITY_ORDER, sarifLevel } from "./severity.js";
 import { ANALYZABLE_LANGUAGES_LABEL } from "./detect-utils.js";
+import { remediationFor, remediationForTier } from "./remediation.js";
+import type { SecurityTier } from "./remediation.js";
 
 /** Minimal SARIF 2.1.0 log shape (kept permissive on purpose). */
 export interface SarifLog {
@@ -327,7 +329,10 @@ function scoreColor(score: number): string {
  * Render a human-readable summary of a scan result. Colour is off by default;
  * pass `{ color: true }` to emit ANSI escape codes.
  */
-export function formatSummary(result: ScanResult, options?: { color?: boolean }): string {
+export function formatSummary(
+  result: ScanResult,
+  options?: { color?: boolean; tier?: SecurityTier },
+): string {
   const color = options?.color ?? false;
   const c = (code: string, text: string): string => (color ? `${code}${text}${ANSI.reset}` : text);
 
@@ -427,5 +432,39 @@ export function formatSummary(result: ScanResult, options?: { color?: boolean })
     );
   }
 
+  if (options?.tier) {
+    lines.push("", ...formatTierGuidance(inv.byAlgorithm, options.tier));
+  }
+
   return lines.join("\n");
 }
+
+/**
+ * Per-family migration targets for a CNSA security tier — surfaces the otherwise
+ * library-only {@link remediationForTier} in human reports. Category 5 shows the
+ * ML-KEM-1024 / ML-DSA-87 sets CNSA 2.0 mandates for national-security systems and
+ * long-lived secrets. Returns plain (un-coloured) lines; the caller styles them.
+ */
+export function formatTierGuidance(
+  byAlgorithm: Record<string, number>,
+  tier: SecurityTier,
+): string[] {
+  const label = tier === "category-5" ? "CNSA 2.0 (Category 5)" : "Category 3 (commercial)";
+  const out: string[] = [`${label} migration targets:`];
+  const seen = new Set<string>();
+  for (const [k, n] of Object.entries(byAlgorithm)) {
+    if (n <= 0) continue;
+    const fam = k as AlgorithmFamily;
+    if (fam === "unknown" || !remediationFor(fam)) continue; // skip unmapped families
+    const rem = remediationForTier(fam, tier);
+    if (seen.has(rem.recommendation)) continue;
+    seen.add(rem.recommendation);
+    out.push(`  ${fam} → ${rem.recommendation}`);
+  }
+  if (tier === "category-5") {
+    out.push(
+      "  CNSA 2.0 mandates ML-KEM-1024 / ML-DSA-87 for national-security systems and long-lived secrets (2030/2033 milestones).",
+    );
+  }
+  return out;
+}

package/src/scan.ts

@@ -15,7 +15,18 @@ import * as path from "node:path";
 import type { Detector, Finding, ScanOptions, ScanResult } from "./types.js";
 import { walkFiles, toPosix, isBinaryPath, looksMinified, matchesAny } from "./walk.js";
 import { isAnalyzableSource } from "./detect-utils.js";
-import { stripCommentFindings, stripIgnoredFindings } from "./comments.js";
+import {
+  stripCommentFindings,
+  stripIgnoredFindings,
+  stripStringLiteralFindings,
+} from "./comments.js";
+
+/**
+ * Rules whose token is only meaningful as code, never inside a string literal.
+ * A match inside a string (e.g. `t.Error("SigningMethodPS256 …")`) is prose and
+ * is dropped. Rules that legitimately match quoted tokens are NOT listed here.
+ */
+const CODE_ONLY_RULES: ReadonlySet<string> = new Set(["go-jwt-signingmethod"]);
 import { hashContent, loadCache, rulesetFingerprint, saveCache } from "./cache.js";
 import type { CacheEntry } from "./cache.js";
 import { builtinDetectors, defaultRegistry, detectorScope } from "./registry.js";
@@ -71,6 +82,7 @@ export function detectFile(
   // `qscan-ignore-next-line` directives. Both run before the dependency scan
   // appends its findings (manifests carry neither).
   out = stripCommentFindings(out, content, file);
+  out = stripStringLiteralFindings(out, content, file, CODE_ONLY_RULES);
   out = stripIgnoredFindings(out, content);
 
   if (toggles.deps && isManifestFile(file)) {
@@ -118,7 +130,14 @@ export async function scan(options: ScanOptions): Promise<ScanResult> {
   const cacheFile = options.cacheFile;
   const ruleset = cacheFile ? rulesetFingerprint(dets, options.disabledRules) : "";
   const cache = cacheFile ? await loadCache(cacheFile, ruleset) : null;
-  const nextEntries: Map<string, CacheEntry> | null = cacheFile ? new Map() : null;
+  // A full scan starts with an empty next-cache so files that vanished are
+  // evicted. An INCREMENTAL scan (explicit `files` list) only visits a subset,
+  // so seed the next-cache with the existing entries — otherwise saving would
+  // drop every file we didn't happen to scan this run (audit: arch #4).
+  const incremental = Array.isArray(options.files);
+  const nextEntries: Map<string, CacheEntry> | null = cacheFile
+    ? new Map(incremental && cache ? cache : [])
+    : null;
 
   // Work-budget / cancellation controls (all optional, unlimited when omitted).
   const signal = options.signal;

package/src/types.ts

@@ -95,7 +95,7 @@ export interface Finding {
 }
 
 /** Package ecosystems the dependency scanner understands. */
-export type DependencyEcosystem = "npm" | "pypi" | "cargo" | "go" | "maven" | "rubygems";
+export type DependencyEcosystem = "npm" | "pypi" | "cargo" | "go" | "maven" | "rubygems" | "nuget";
 
 /** A known quantum-vulnerable dependency entry. */
 export interface VulnerableDependency {
@@ -107,6 +107,13 @@ export interface VulnerableDependency {
   /** Algorithm families the package primarily exposes. */
   algorithms: AlgorithmFamily[];
   severity: Severity;
+  /**
+   * Explicit harvest-now-decrypt-later override. When omitted, HNDL is inferred
+   * from whether any listed family is a confidentiality family. Set `false` for
+   * signing-only packages (e.g. JWS/JWT libraries) that list RSA/EC as families
+   * but never do key transport or key agreement — signatures are not HNDL-exposed.
+   */
+  hndl?: boolean;
 }
 
 /**

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.4.1";
+export const VERSION = "0.4.3";

package/src/worktree.ts

@@ -31,8 +31,10 @@ export async function withWorktree<T>(
   }
   const base = await mkdtemp(join(tmpdir(), "quantakrypto-wt-"));
   const dir = join(base, "wt");
-  await git(["worktree", "add", "--detach", dir], repoRoot);
+  // `worktree add` is INSIDE the try so a failure (locked index, disk full)
+  // still cleans up the temp dir in `finally` (audit: arch #6).
   try {
+    await git(["worktree", "add", "--detach", dir], repoRoot);
     return await fn(dir);
   } finally {
     try {
@@ -40,6 +42,12 @@ export async function withWorktree<T>(
     } catch {
       // best effort — the temp dir removal below still reclaims the disk.
     }
+    // Prune stale `.git/worktrees/<name>` metadata a failed add/remove can leave.
+    try {
+      await git(["worktree", "prune"], repoRoot);
+    } catch {
+      // best effort
+    }
     await rm(base, { recursive: true, force: true });
   }
 }