@quantakrypto/core 0.1.0

package/src/remediation.ts

@@ -0,0 +1,173 @@
+/**
+ * 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).
+ */
+import type { AlgorithmFamily, Remediation } from "./types.js";
+
+/** Canonical remediation table, keyed by algorithm family. */
+const REMEDIATIONS: Record<AlgorithmFamily, Remediation> = {
+  RSA: {
+    algorithm: "RSA",
+    recommendation: "ML-KEM-768 for encryption/KEM; ML-DSA-65 for signatures",
+    detail:
+      "RSA is broken by Shor's algorithm. For key transport / encryption move to " +
+      "ML-KEM-768 (FIPS 203), ideally as the hybrid X25519MLKEM768. For digital " +
+      "signatures move to ML-DSA-65 (FIPS 204) or SLH-DSA (FIPS 205).",
+  },
+  ECDH: {
+    algorithm: "ECDH",
+    recommendation: "hybrid X25519MLKEM768 (ML-KEM-768)",
+    detail:
+      "Elliptic-curve Diffie-Hellman is broken by Shor's algorithm and is exposed " +
+      "to harvest-now-decrypt-later. Adopt the hybrid X25519MLKEM768 key exchange so " +
+      "confidentiality survives even if one component is broken.",
+  },
+  ECDSA: {
+    algorithm: "ECDSA",
+    recommendation: "ML-DSA-65 (FIPS 204)",
+    detail:
+      "ECDSA signatures can be forged by a quantum attacker via Shor's algorithm. " +
+      "Migrate to ML-DSA (Dilithium, FIPS 204) or SLH-DSA (SPHINCS+, FIPS 205) for " +
+      "long-lived signatures.",
+  },
+  EdDSA: {
+    algorithm: "EdDSA",
+    recommendation: "ML-DSA-65 (FIPS 204)",
+    detail:
+      "Ed25519 / Ed448 (EdDSA) are classical signatures broken by Shor's algorithm. " +
+      "Replace with ML-DSA-65 (FIPS 204) or SLH-DSA (FIPS 205) for forgery resistance.",
+  },
+  DH: {
+    algorithm: "DH",
+    recommendation: "hybrid X25519MLKEM768 (ML-KEM-768)",
+    detail:
+      "Finite-field Diffie-Hellman is broken by Shor's algorithm and exposed to " +
+      "harvest-now-decrypt-later. Move to a hybrid PQC KEM such as X25519MLKEM768.",
+  },
+  DSA: {
+    algorithm: "DSA",
+    recommendation: "ML-DSA-65 (FIPS 204)",
+    detail:
+      "DSA is a classical, quantum-broken signature scheme (and already deprecated). " +
+      "Replace with ML-DSA-65 (FIPS 204) or SLH-DSA (FIPS 205).",
+  },
+  X25519: {
+    algorithm: "X25519",
+    recommendation: "hybrid X25519MLKEM768 (ML-KEM-768)",
+    detail:
+      "X25519 is a modern, well-built classical key-agreement primitive but is still " +
+      "broken by Shor's algorithm. Wrap it in the hybrid X25519MLKEM768 construction " +
+      "so it stays useful during the PQC transition.",
+  },
+  X448: {
+    algorithm: "X448",
+    recommendation: "hybrid X25519MLKEM768 (ML-KEM-768)",
+    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.",
+  },
+  ECIES: {
+    algorithm: "ECIES",
+    recommendation: "ML-KEM-768 hybrid encryption",
+    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.",
+  },
+  unknown: {
+    algorithm: "unknown",
+    recommendation: "review for post-quantum migration",
+    detail:
+      "This usage involves classical public-key cryptography. Audit it and plan a " +
+      "migration to NIST PQC standards (ML-KEM / FIPS 203, ML-DSA / FIPS 204).",
+  },
+};
+
+/** Look up the recommended post-quantum remediation for a classical algorithm. */
+export function remediationFor(algorithm: AlgorithmFamily): Remediation | undefined {
+  return REMEDIATIONS[algorithm];
+}
+
+/** Convenience: just the short recommendation string for a family (always defined). */
+export function remediationText(algorithm: AlgorithmFamily): string {
+  return REMEDIATIONS[algorithm].recommendation;
+}
+
+/* -------------------------------------------------------------------------- */
+/* Security-tier guidance (CNSA 2.0 Category 5) + stateful HBS (SP 800-208)     */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Security tier for remediation guidance.
+ *  - `"category-3"` (default): commercial use — ML-KEM-768 / ML-DSA-65.
+ *  - `"category-5"`: CNSA 2.0 national-security-systems / long-lived secrets —
+ *    ML-KEM-1024 / ML-DSA-87.
+ */
+export type SecurityTier = "category-3" | "category-5";
+
+/** Per-tier KEM / signature parameter sets. */
+export const TIER_PARAMS: Record<SecurityTier, { kem: string; signature: string; note: string }> = {
+  "category-3": {
+    kem: "ML-KEM-768 (FIPS 203)",
+    signature: "ML-DSA-65 (FIPS 204)",
+    note: "NIST Category 3 — default for general commercial use.",
+  },
+  "category-5": {
+    kem: "ML-KEM-1024 (FIPS 203)",
+    signature: "ML-DSA-87 (FIPS 204)",
+    note: "NIST Category 5 — CNSA 2.0 for national-security systems and long-lived secrets (2030/2033 milestones).",
+  },
+};
+
+/**
+ * Tier-aware remediation. Returns the base family remediation plus the
+ * parameter sets for the requested CNSA tier. Category 5 surfaces the
+ * ML-KEM-1024 / ML-DSA-87 sets mandated by CNSA 2.0; category 3 is the
+ * commercial default.
+ */
+export function remediationForTier(
+  algorithm: AlgorithmFamily,
+  tier: SecurityTier = "category-3",
+): Remediation {
+  const base = REMEDIATIONS[algorithm];
+  const params = TIER_PARAMS[tier];
+  // Confidentiality families lean on the KEM; signature families on the signer.
+  const isConfidentiality =
+    algorithm === "RSA" ||
+    algorithm === "ECDH" ||
+    algorithm === "DH" ||
+    algorithm === "X25519" ||
+    algorithm === "X448" ||
+    algorithm === "ECIES";
+  const primary = isConfidentiality ? params.kem : params.signature;
+  return {
+    algorithm,
+    recommendation: `${base.recommendation} — ${tier}: ${primary}`,
+    detail: `${base.detail} ${params.note} For this tier use ${params.kem} (KEM) and ${params.signature} (signatures).`,
+  };
+}
+
+/**
+ * Guidance for stateful hash-based signatures (SP 800-208: LMS / XMSS / HSS).
+ * These are NIST-approved for firmware / boot signing but are STATEFUL — each
+ * private key may sign a bounded number of messages and the state MUST be
+ * managed to avoid catastrophic key reuse. Surfaced where a long-lived,
+ * low-volume signing root is appropriate.
+ */
+export const STATEFUL_HBS_NOTE =
+  "For firmware / secure-boot signing, the stateful hash-based signatures " +
+  "LMS, XMSS and HSS (NIST SP 800-208) are approved alternatives to ML-DSA, " +
+  "but they are STATEFUL: the signer must never reuse a one-time key index. " +
+  "Use only with rigorous state management; otherwise prefer stateless ML-DSA " +
+  "(FIPS 204) or SLH-DSA (FIPS 205).";
+
+/** 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.
+  return (
+    algorithm === "RSA" || algorithm === "ECDSA" || algorithm === "EdDSA" || algorithm === "DSA"
+  );
+}

package/src/report.ts

@@ -0,0 +1,340 @@
+/**
+ * Reporters: turn a {@link ScanResult} into SARIF 2.1.0, a clean JSON object,
+ * 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 { ScanResult, Severity } from "./types.js";
+import { VERSION } from "./version.js";
+
+/** Minimal SARIF 2.1.0 log shape (kept permissive on purpose). */
+export interface SarifLog {
+  $schema: string;
+  version: "2.1.0";
+  runs: unknown[];
+}
+
+const SARIF_SCHEMA =
+  "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json";
+
+const INFORMATION_URI = "https://github.com/qproof-tools/qproof";
+
+/** Map our severity to a SARIF result level. */
+function sarifLevel(severity: Severity): "error" | "warning" | "note" {
+  switch (severity) {
+    case "critical":
+    case "high":
+      return "error";
+    case "medium":
+      return "warning";
+    default:
+      return "note";
+  }
+}
+
+/** Map our severity to a SARIF rule-level default (used in rules[].defaultConfiguration). */
+function sarifRank(severity: Severity): number {
+  switch (severity) {
+    case "critical":
+      return 100;
+    case "high":
+      return 80;
+    case "medium":
+      return 50;
+    case "low":
+      return 20;
+    default:
+      return 5;
+  }
+}
+
+/** Serialize a scan result as SARIF 2.1.0. */
+export function toSarif(result: ScanResult): SarifLog {
+  // Build the unique rule set (one rule per ruleId encountered) and collect the
+  // set of CWE taxa referenced by any rule.
+  const ruleIndex = new Map<string, number>();
+  const rules: Array<Record<string, unknown>> = [];
+  const cweTaxa = new Set<string>();
+  for (const f of result.findings) {
+    if (f.cwe) cweTaxa.add(f.cwe);
+    if (ruleIndex.has(f.ruleId)) continue;
+    ruleIndex.set(f.ruleId, rules.length);
+    rules.push({
+      id: f.ruleId,
+      name: f.ruleId,
+      shortDescription: { text: f.title },
+      fullDescription: { text: f.message },
+      defaultConfiguration: { level: sarifLevel(f.severity), rank: sarifRank(f.severity) },
+      ...(f.remediation ? { help: { text: `Remediation: ${f.remediation}` } } : {}),
+      properties: {
+        category: f.category,
+        ...(f.algorithm ? { algorithm: f.algorithm } : {}),
+        hndl: f.hndl,
+        ...(f.cwe ? { cwe: f.cwe, "security-severity": securitySeverity(f.severity) } : {}),
+        ...(f.cwe ? { tags: ["security", f.cwe] } : {}),
+      },
+      ...(f.cwe
+        ? {
+            relationships: [
+              { target: { id: f.cwe, toolComponent: { name: "CWE" } }, kinds: ["relevant"] },
+            ],
+          }
+        : {}),
+    });
+  }
+
+  const results = result.findings.map((f) => {
+    const region: Record<string, number> = { startLine: f.location.line };
+    if (typeof f.location.column === "number") region.startColumn = f.location.column;
+    if (typeof f.location.endLine === "number") region.endLine = f.location.endLine;
+
+    return {
+      ruleId: f.ruleId,
+      ruleIndex: ruleIndex.get(f.ruleId),
+      level: sarifLevel(f.severity),
+      message: { text: f.message },
+      properties: {
+        category: f.category,
+        severity: f.severity,
+        confidence: f.confidence,
+        hndl: f.hndl,
+        ...(f.algorithm ? { algorithm: f.algorithm } : {}),
+        ...(f.remediation ? { remediation: f.remediation } : {}),
+        ...(f.cwe ? { cwe: f.cwe } : {}),
+      },
+      ...(f.cwe
+        ? {
+            taxa: [
+              {
+                target: { id: f.cwe, toolComponent: { name: "CWE" } },
+              },
+            ],
+          }
+        : {}),
+      locations: [
+        {
+          physicalLocation: {
+            artifactLocation: { uri: f.location.file },
+            region: {
+              ...region,
+              ...(f.location.snippet ? { snippet: { text: f.location.snippet } } : {}),
+            },
+          },
+        },
+      ],
+    };
+  });
+
+  // CWE taxonomy component (SARIF taxonomies), referenced by rules + results.
+  const taxonomies =
+    cweTaxa.size > 0
+      ? [
+          {
+            name: "CWE",
+            informationUri: "https://cwe.mitre.org/",
+            organization: "MITRE",
+            shortDescription: { text: "The MITRE Common Weakness Enumeration" },
+            taxa: [...cweTaxa].sort().map((id) => ({
+              id,
+              helpUri: `https://cwe.mitre.org/data/definitions/${id.replace(/^CWE-/, "")}.html`,
+            })),
+          },
+        ]
+      : [];
+
+  return {
+    $schema: SARIF_SCHEMA,
+    version: "2.1.0",
+    runs: [
+      {
+        tool: {
+          driver: {
+            name: "qScan",
+            informationUri: INFORMATION_URI,
+            version: result.toolVersion || VERSION,
+            rules,
+          },
+        },
+        ...(taxonomies.length > 0 ? { taxonomies } : {}),
+        results,
+      },
+    ],
+  };
+}
+
+/** GitHub-code-scanning `security-severity` (0–10) derived from our severity. */
+function securitySeverity(severity: Severity): string {
+  switch (severity) {
+    case "critical":
+      return "9.5";
+    case "high":
+      return "8.0";
+    case "medium":
+      return "5.0";
+    case "low":
+      return "3.0";
+    default:
+      return "1.0";
+  }
+}
+
+/** Serialize a scan result as a plain JSON-friendly object. */
+export function toJson(result: ScanResult): Record<string, unknown> {
+  return {
+    toolVersion: result.toolVersion,
+    root: result.root,
+    startedAt: result.startedAt,
+    finishedAt: result.finishedAt,
+    filesScanned: result.filesScanned,
+    inventory: {
+      readinessScore: result.inventory.readinessScore,
+      hndlCount: result.inventory.hndlCount,
+      bySeverity: result.inventory.bySeverity,
+      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: f.location.snippet,
+      },
+    })),
+  };
+}
+
+/* -------------------------------------------------------------------------- */
+/* Human-readable summary                                                      */
+/* -------------------------------------------------------------------------- */
+
+/** Raw ANSI codes (no chalk). Disabled when colour is off. */
+const ANSI = {
+  reset: "\x1b[0m",
+  bold: "\x1b[1m",
+  dim: "\x1b[2m",
+  red: "\x1b[31m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  blue: "\x1b[34m",
+  magenta: "\x1b[35m",
+  cyan: "\x1b[36m",
+} as const;
+
+/** Severity ordering for grouping / sorting, most → least severe. */
+const SEVERITY_ORDER: Severity[] = ["critical", "high", "medium", "low", "info"];
+
+function severityColor(sev: Severity): string {
+  switch (sev) {
+    case "critical":
+      return ANSI.magenta;
+    case "high":
+      return ANSI.red;
+    case "medium":
+      return ANSI.yellow;
+    case "low":
+      return ANSI.blue;
+    default:
+      return ANSI.dim;
+  }
+}
+
+function scoreColor(score: number): string {
+  if (score >= 80) return ANSI.green;
+  if (score >= 50) return ANSI.yellow;
+  return ANSI.red;
+}
+
+/**
+ * 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 {
+  const color = options?.color ?? false;
+  const c = (code: string, text: string): string => (color ? `${code}${text}${ANSI.reset}` : text);
+
+  const lines: string[] = [];
+  const inv = result.inventory;
+
+  lines.push(c(ANSI.bold, "qScan — post-quantum readiness report"));
+  lines.push(c(ANSI.dim, `tool v${result.toolVersion} · root: ${result.root}`));
+  lines.push("");
+
+  // Readiness score banner.
+  lines.push(
+    `Readiness score: ${c(`${ANSI.bold}${scoreColor(inv.readinessScore)}`, `${inv.readinessScore}/100`)}`,
+  );
+  lines.push(
+    `Files scanned:   ${result.filesScanned}   Findings: ${result.findings.length}   HNDL-exposed: ${c(
+      inv.hndlCount > 0 ? ANSI.red : ANSI.green,
+      String(inv.hndlCount),
+    )}`,
+  );
+  lines.push("");
+
+  // Severity breakdown.
+  const sevParts = SEVERITY_ORDER.filter((s) => inv.bySeverity[s] > 0).map((s) =>
+    c(severityColor(s), `${s}: ${inv.bySeverity[s]}`),
+  );
+  lines.push(`By severity:  ${sevParts.length ? sevParts.join("   ") : c(ANSI.green, "none")}`);
+
+  // Algorithm breakdown.
+  const algoParts = Object.entries(inv.byAlgorithm)
+    .sort((a, b) => b[1] - a[1])
+    .map(([k, v]) => `${k}: ${v}`);
+  if (algoParts.length) lines.push(`By algorithm: ${algoParts.join("   ")}`);
+  lines.push("");
+
+  if (result.findings.length === 0) {
+    lines.push(c(ANSI.green, "No classical asymmetric cryptography detected. ✓"));
+    return lines.join("\n");
+  }
+
+  // Top findings, grouped by severity (most severe first), capped for readability.
+  const sorted = [...result.findings].sort(
+    (a, b) => SEVERITY_ORDER.indexOf(a.severity) - SEVERITY_ORDER.indexOf(b.severity),
+  );
+  const MAX_SHOWN = 25;
+  lines.push(
+    c(ANSI.bold, `Top findings (${Math.min(MAX_SHOWN, sorted.length)} of ${sorted.length}):`),
+  );
+
+  for (const f of sorted.slice(0, MAX_SHOWN)) {
+    const loc = `${f.location.file}:${f.location.line}${
+      f.location.column ? `:${f.location.column}` : ""
+    }`;
+    const tag = c(severityColor(f.severity), `[${f.severity}]`);
+    const hndl = f.hndl ? c(ANSI.red, " (HNDL)") : "";
+    lines.push(`  ${tag} ${f.title}${hndl}`);
+    lines.push(c(ANSI.dim, `      ${loc} — ${f.message}`));
+    if (f.remediation) lines.push(c(ANSI.cyan, `      → ${f.remediation}`));
+  }
+
+  if (sorted.length > MAX_SHOWN) {
+    lines.push(c(ANSI.dim, `  …and ${sorted.length - MAX_SHOWN} more.`));
+  }
+
+  lines.push("");
+  if (inv.hndlCount > 0) {
+    lines.push(
+      c(
+        ANSI.yellow,
+        `Note: ${inv.hndlCount} finding(s) are exposed to "harvest now, decrypt later" — ` +
+          "encrypted traffic captured today can be decrypted once a quantum computer exists. " +
+          "Prioritise migrating key exchange / encryption to hybrid PQC (X25519MLKEM768).",
+      ),
+    );
+  }
+
+  return lines.join("\n");
+}

package/src/scan-worker.ts

@@ -0,0 +1,80 @@
+/**
+ * Worker-thread entry for {@link scanParallel}. Built to `dist/scan-worker.js`
+ * and spawned by `parallel.ts`. Each worker reads its assigned files and runs
+ * the SAME pure detector pipeline as the serial scan (`detectFile`), returning
+ * `{ findings, filesScanned }` per chunk. No shared mutable state.
+ *
+ * This file performs side effects (wires up message handlers) only when it is
+ * actually running inside a worker thread, so importing it from the main thread
+ * (e.g. for coverage) is harmless.
+ */
+import { readFileSync } from "node:fs";
+import * as path from "node:path";
+import { parentPort, workerData } from "node:worker_threads";
+
+import type { Finding } from "./types.js";
+import { defaultRegistry } from "./registry.js";
+import { detectFile } from "./scan.js";
+import { looksMinified } from "./walk.js";
+import { isManifestFile } from "./dependencies.js";
+
+interface WorkerToggles {
+  source: boolean;
+  config: boolean;
+  deps: boolean;
+  scanMinified: boolean;
+}
+
+interface ChunkRequest {
+  index: number;
+  files: string[];
+}
+
+if (parentPort) {
+  const data = (workerData ?? {}) as { baseDir: string; toggles: WorkerToggles };
+  const baseDir = data.baseDir;
+  const toggles = data.toggles;
+  const dets = defaultRegistry.all();
+  const port = parentPort;
+
+  port.on("message", (req: ChunkRequest) => {
+    try {
+      const findings: Finding[] = [];
+      let filesScanned = 0;
+      const scannedNames: string[] = [];
+
+      for (const rel of req.files) {
+        const abs = path.join(baseDir, ...rel.split("/"));
+        let content: string;
+        try {
+          content = readFileSync(abs, "utf8");
+        } catch {
+          continue; // vanished / unreadable — skip.
+        }
+        if (!toggles.scanMinified && !isManifestFile(rel) && looksMinified(content)) {
+          continue;
+        }
+        filesScanned += 1;
+        scannedNames.push(rel);
+        findings.push(
+          ...detectFile(rel, content, dets, {
+            source: toggles.source,
+            config: toggles.config,
+            deps: toggles.deps,
+          }),
+        );
+      }
+
+      port.postMessage({
+        index: req.index,
+        files: scannedNames,
+        result: { findings, filesScanned },
+      });
+    } catch (err) {
+      port.postMessage({
+        index: req.index,
+        error: err instanceof Error ? err.message : String(err),
+      });
+    }
+  });
+}