@quantakrypto/core 0.4.4 → 0.6.0

package/src/scan.ts

@@ -13,7 +13,15 @@ import { readFile, stat } from "node:fs/promises";
 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 {
+  walkFiles,
+  toPosix,
+  isBinaryPath,
+  isKeystorePath,
+  looksMinified,
+  matchesAny,
+  DEFAULT_MAX_FILE_SIZE,
+} from "./walk.js";
 import { isAnalyzableSource } from "./detect-utils.js";
 import {
   stripCommentFindings,
@@ -26,7 +34,16 @@ import {
  * 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"]);
+const CODE_ONLY_RULES: ReadonlySet<string> = new Set([
+  "go-jwt-signingmethod",
+  // Identifier-form JWT alg constants (jjwt `SignatureAlgorithm.RS256`, auth0
+  // `Algorithm.RSA256`, C# `SecurityAlgorithms.*`, Rust `Algorithm::RS256`). Like the
+  // Go rule, these are only meaningful as code; the SAME token inside a string literal
+  // (an error message that names/forbids the alg) is prose, not a usage.
+  "java-jwt-alg",
+  "csharp-jwt-alg",
+  "rust-jwt-algorithm",
+]);
 import { hashContent, loadCache, rulesetFingerprint, saveCache } from "./cache.js";
 import type { CacheEntry } from "./cache.js";
 import { builtinDetectors, defaultRegistry, detectorScope } from "./registry.js";
@@ -169,23 +186,41 @@ export async function scan(options: ScanOptions): Promise<ScanResult> {
 
     options.onFile?.(reportedPath);
 
+    // Cryptographic keystores (.jks/.p12/…) are binary; read them byte-preserving
+    // (latin1) so the keystore detector can inspect magic bytes.
+    const keystore = isKeystorePath(reportedPath);
+    // Keystores are read whole into memory as latin1. The walker already caps file
+    // size, but the explicit-file-list (incremental) path does not — so stat and
+    // skip an oversized binary here to avoid reading a huge encrypted archive
+    // (`.gpg`) into a string.
+    if (keystore) {
+      try {
+        const { size } = await stat(absPath);
+        if (size > (options.maxFileSize ?? DEFAULT_MAX_FILE_SIZE)) continue;
+      } catch {
+        unreadable += 1;
+        continue;
+      }
+    }
     let content: string;
     try {
-      content = await readFile(absPath, "utf8");
+      content = await readFile(absPath, keystore ? "latin1" : "utf8");
     } catch {
       unreadable += 1; // permissions / vanished / decode failure — tracked, not silent.
       continue;
     }
 
     // Skip machine-minified / generated content (unless explicitly enabled).
-    // Manifests are always scanned (their findings are dependency findings).
-    if (!scanMinified && !isManifestFile(reportedPath) && looksMinified(content)) {
+    // Manifests and keystores are always scanned.
+    if (!scanMinified && !isManifestFile(reportedPath) && !keystore && looksMinified(content)) {
       skippedMinified += 1;
       continue;
     }
 
     // Cumulative-byte budget: enforced once this file's bytes are accounted for.
-    bytesScanned += Buffer.byteLength(content, "utf8");
+    // Use the read encoding so a latin1 keystore is counted at its on-disk size
+    // (a utf8 byteLength would double-count every byte ≥ 0x80).
+    bytesScanned += Buffer.byteLength(content, keystore ? "latin1" : "utf8");
     if (typeof maxBytes === "number" && bytesScanned > maxBytes) {
       throw new BudgetExceededError(`maxBytes budget exceeded (limit: ${maxBytes}).`);
     }

package/src/standards-profiles.ts

@@ -0,0 +1,136 @@
+/**
+ * Selectable STANDARDS PROFILES — the regime a scan's remediation, deadlines, and
+ * hybrid guidance are tailored to. Different national/regional authorities agree on
+ * the PQC primitives (ML-KEM / ML-DSA) but diverge on two things this tool must not
+ * hardcode: (a) the required PARAMETER SETS (a commercial ML-KEM-768 vs a
+ * national-security ML-KEM-1024), and (b) the HYBRID STANCE — whether classical+PQC
+ * hybridization is required, recommended, or optional during the transition. Baking
+ * in NIST/CNSA's "hybrids optional" is wrong for an ANSSI or BSI audience, where
+ * hybrid is required. `--profile <id>` selects the regime; `--policy` composes an
+ * org's own exceptions on top.
+ *
+ * Like {@link PqcStandards}, every profile carries a citation + `asOf` date and is
+ * re-verified on the quarterly standards cadence. These are guidance summaries, not
+ * legal advice — consult the cited source of record.
+ */
+
+/** Whether classical+PQC hybridization is required during the transition, per regime. */
+export type HybridStance = "required" | "recommended" | "optional";
+
+/** A regime's PQC guidance profile. */
+export interface StandardsProfile {
+  /** Stable id used by `--profile` (kebab-case). */
+  readonly id: string;
+  /** Human-readable name. */
+  readonly name: string;
+  /** The authority / document of record. */
+  readonly authority: string;
+  /** The KEM / signature parameter sets this regime calls for. */
+  readonly paramSets: { readonly kem: string; readonly signature: string };
+  /** Whether hybridization is required / recommended / optional under this regime. */
+  readonly hybridStance: HybridStance;
+  /** One-line regime-specific hybrid guidance surfaced in remediation. */
+  readonly hybridGuidance: string;
+  /** Year after which classical public-key crypto is deprecated under this regime. */
+  readonly deprecateAfter: number;
+  /** Year after which it is disallowed. */
+  readonly disallowAfter: number;
+  /** Spec identifier / publication of record. */
+  readonly citation: string;
+  /** `YYYY-MM` — when this profile was last verified against its source. */
+  readonly asOf: string;
+}
+
+/** The default profile id when `--profile` is not given. */
+export const DEFAULT_PROFILE_ID = "nist";
+
+/**
+ * Built-in regime profiles. Facts reflect each authority's published PQC-transition
+ * position as of the `asOf` date; verify against the cited source before relying on a
+ * deadline or a hybrid mandate for a compliance decision.
+ */
+export const STANDARDS_PROFILES: Readonly<Record<string, StandardsProfile>> = {
+  nist: {
+    id: "nist",
+    name: "NIST (general / commercial)",
+    authority: "NIST",
+    paramSets: { kem: "ML-KEM-768 (FIPS 203)", signature: "ML-DSA-65 (FIPS 204)" },
+    hybridStance: "recommended",
+    hybridGuidance:
+      "Hybrid key establishment (e.g. X25519MLKEM768) is permitted and recommended during the transition; pure ML-KEM is also acceptable (SP 800-227 / IR 8547).",
+    deprecateAfter: 2030,
+    disallowAfter: 2035,
+    citation: "NIST IR 8547 + FIPS 203/204/205",
+    asOf: "2026-07",
+  },
+  "cnsa-2.0": {
+    id: "cnsa-2.0",
+    name: "NSA CNSA 2.0 (national-security systems)",
+    authority: "NSA",
+    paramSets: { kem: "ML-KEM-1024 (FIPS 203)", signature: "ML-DSA-87 (FIPS 204)" },
+    hybridStance: "optional",
+    hybridGuidance:
+      "CNSA 2.0 targets pure PQC and does not require hybrids; if a hybrid TLS group is used, it must be SecP384r1MLKEM1024 — X25519MLKEM768's ML-KEM-768 component is sub-CNSA.",
+    deprecateAfter: 2030,
+    disallowAfter: 2035,
+    citation: "NSA CNSA 2.0 (2030/2033/2035 migration milestones)",
+    asOf: "2026-07",
+  },
+  "bsi-tr-02102": {
+    id: "bsi-tr-02102",
+    name: "BSI TR-02102 (Germany)",
+    authority: "BSI",
+    paramSets: { kem: "ML-KEM-768 (FIPS 203)", signature: "ML-DSA-65 (FIPS 204)" },
+    hybridStance: "required",
+    hybridGuidance:
+      "BSI requires PQC be deployed in HYBRID with an established classical scheme during the transition (defense-in-depth); FrodoKEM is the conservative KEM alternative to ML-KEM, and XMSS/LMS are approved for firmware signing.",
+    deprecateAfter: 2030,
+    disallowAfter: 2035,
+    citation: "BSI TR-02102-1 (Kryptographische Verfahren)",
+    asOf: "2026-07",
+  },
+  anssi: {
+    id: "anssi",
+    name: "ANSSI (France)",
+    authority: "ANSSI",
+    paramSets: { kem: "ML-KEM-1024 (FIPS 203)", signature: "ML-DSA-87 (FIPS 204)" },
+    hybridStance: "required",
+    hybridGuidance:
+      "ANSSI requires HYBRIDIZATION (classical + PQC) throughout the transition phase and does not endorse pure PQC alone yet; use the highest parameter set for long-lived assurance.",
+    deprecateAfter: 2030,
+    disallowAfter: 2035,
+    citation: "ANSSI — PQC transition position papers",
+    asOf: "2026-07",
+  },
+  "uk-ncsc": {
+    id: "uk-ncsc",
+    name: "UK NCSC",
+    authority: "NCSC",
+    paramSets: { kem: "ML-KEM-768 (FIPS 203)", signature: "ML-DSA-65 (FIPS 204)" },
+    hybridStance: "recommended",
+    hybridGuidance:
+      "NCSC recommends ML-KEM / ML-DSA and is broadly agnostic on hybridization (recommended, not mandated); its migration milestones are earlier — discovery/plan by 2028, high-priority migration by 2031, complete by 2035.",
+    deprecateAfter: 2031,
+    disallowAfter: 2035,
+    citation: "NCSC — Preparing for quantum-safe cryptography / PQC migration timeline",
+    asOf: "2026-07",
+  },
+};
+
+/** All built-in profile ids, in a stable order (default first). */
+export function standardsProfileIds(): string[] {
+  return [
+    DEFAULT_PROFILE_ID,
+    ...Object.keys(STANDARDS_PROFILES).filter((id) => id !== DEFAULT_PROFILE_ID),
+  ];
+}
+
+/** Look up a built-in profile by id, or `undefined` when unknown. */
+export function getStandardsProfile(id: string): StandardsProfile | undefined {
+  return STANDARDS_PROFILES[id];
+}
+
+/** The default profile (NIST). Always defined. */
+export function defaultStandardsProfile(): StandardsProfile {
+  return STANDARDS_PROFILES[DEFAULT_PROFILE_ID];
+}

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 {
@@ -137,6 +145,10 @@ export type DetectorLanguage =
   | "php"
   | "elixir"
   | "c"
+  | "swift"
+  | "objc"
+  | "dart"
+  | "solidity"
   | "any";
 
 /**
@@ -344,10 +356,11 @@ export interface ScanResult {
    */
   diagnostics?: ScanDiagnostics;
   /**
-   * Of `filesScanned`, how many were in a source language the scanner can
-   * actually analyze for inline crypto (JS/TS, Python, Go, Java). When this is 0 but
-   * `filesScanned` > 0, the readiness score reflects NO analyzable code — the
-   * crypto likely lives in an unsupported language (Go, Java, Rust, …) — and
+   * Of `filesScanned`, how many were in a source language the scanner can actually
+   * analyze for inline crypto (the 13 packs: JS/TS, Python, Go, Java/Kotlin/Scala,
+   * C#, Rust, Ruby, PHP, Elixir, C/C++, Swift, Objective-C, Dart). When this is 0
+   * but `filesScanned` > 0, the readiness score reflects NO analyzable code — the
+   * crypto likely lives in an unsupported language (Lua, Perl, …) — and
    * reporters surface that so a bare 100/100 can't read as "safe". Optional for
    * backward compatibility with hand-built results.
    */

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

package/src/vex.ts

@@ -0,0 +1,122 @@
+/**
+ * OpenVEX export — turn a {@link ScanResult} into an OpenVEX 0.2.0 document so
+ * the quantum-readiness posture flows into the SAME supply-chain pipeline that
+ * already ingests CVE-based VEX (Vulnerability Exploitability eXchange).
+ *
+ * Reference: OpenVEX spec (https://openvex.dev/, `@context` v0.2.0).
+ *
+ * Modeling choice (documented, honest): PQC findings have no CVE, so each qScan
+ * rule becomes a synthetic vulnerability `QK-<ruleId>`. Every finding is reported
+ * `status: "affected"` — the classical, Shor-breakable primitive IS present in
+ * the product by construction — with the rule's remediation as the VEX
+ * `action_statement`. A `--triage` exposure verdict, when present, is surfaced in
+ * `status_notes` (score / priority / rationale). qScan never downgrades a finding
+ * to `not_affected`: only the operator can attest a mitigation, so that judgment
+ * is deliberately left to them (they can post-process this document).
+ */
+import { createHash } from "node:crypto";
+
+import type { Finding, ScanResult } from "./types.js";
+
+/** A single OpenVEX statement: one synthetic vulnerability over its affected products. */
+export interface OpenVexStatement {
+  vulnerability: { name: string; description?: string };
+  products: { "@id": string }[];
+  status: "not_affected" | "affected" | "fixed" | "under_investigation";
+  /** Recommended action for an `affected` product (the rule's remediation). */
+  action_statement?: string;
+  /** Free-form status detail — carries the `--triage` exposure verdict when present. */
+  status_notes?: string;
+}
+
+/** An OpenVEX 0.2.0 document. */
+export interface OpenVexDocument {
+  "@context": "https://openvex.dev/ns/v0.2.0";
+  "@id": string;
+  author: string;
+  timestamp: string;
+  version: number;
+  statements: OpenVexStatement[];
+}
+
+/** Options for {@link toOpenVex}. */
+export interface OpenVexOptions {
+  /** Document author (VEX issuer). Default: `"qScan"`. */
+  author?: string;
+}
+
+/**
+ * A stable product identifier for a finding as an IRI (OpenVEX requires product
+ * `@id` to be an IRI): a `file:` URI with the line in the fragment, e.g.
+ * `file:src/a.ts#L3`.
+ */
+function productId(f: Finding): string {
+  return `file:${f.location.file}#L${f.location.line}`;
+}
+
+/**
+ * Build an OpenVEX 0.2.0 document from a scan result. One statement per distinct
+ * rule id, listing every affected `file:line` product. Output is deterministic
+ * (statements sorted by vulnerability name, products sorted and de-duplicated;
+ * the `@id` and `timestamp` derive from the result), so re-exporting the same
+ * scan yields byte-identical VEX.
+ */
+export function toOpenVex(result: ScanResult, opts: OpenVexOptions = {}): OpenVexDocument {
+  // Group findings by rule id → one VEX statement per rule.
+  const byRule = new Map<string, Finding[]>();
+  for (const f of result.findings) {
+    const list = byRule.get(f.ruleId);
+    if (list) list.push(f);
+    else byRule.set(f.ruleId, [f]);
+  }
+
+  const statements: OpenVexStatement[] = [...byRule.entries()]
+    .sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0))
+    .map(([ruleId, findings]) => {
+      const first = findings[0] as Finding;
+      // De-duplicate + sort the affected products (a rule can fire many times).
+      const products = [...new Set(findings.map(productId))].sort().map((id) => ({ "@id": id }));
+
+      // Surface a triage verdict (if any finding for this rule carries one). Findings
+      // of the same rule share a rule; the most-exposed verdict is the informative one.
+      const triaged = findings
+        .filter((f) => f.triage)
+        .sort((a, b) => (b.triage?.exposureScore ?? 0) - (a.triage?.exposureScore ?? 0))[0]?.triage;
+
+      const statement: OpenVexStatement = {
+        vulnerability: {
+          name: `QK-${ruleId}`,
+          description: first.message,
+        },
+        products,
+        status: "affected",
+        action_statement: first.remediation ?? "Migrate to a NIST PQC standard (FIPS 203/204/205).",
+      };
+      if (triaged) {
+        statement.status_notes =
+          `qScan triage — exposure ${triaged.exposureScore}/100, priority ${triaged.priority}: ` +
+          triaged.rationale;
+      }
+      return statement;
+    });
+
+  // Deterministic doc id + timestamp so the same scan yields identical VEX. The
+  // triage `status_notes` are part of the identity: a triaged and an untriaged
+  // export of the same scan are DIFFERENT documents and must not share an @id.
+  const digest = createHash("sha256").update(`${result.root}|${result.toolVersion}`, "utf8");
+  for (const s of statements) {
+    digest.update(
+      `\n${s.vulnerability.name}|${s.products.map((p) => p["@id"]).join(",")}|${s.status_notes ?? ""}`,
+    );
+  }
+  const id = `https://quantakrypto.com/vex/${digest.digest("hex").slice(0, 16)}`;
+
+  return {
+    "@context": "https://openvex.dev/ns/v0.2.0",
+    "@id": id,
+    author: opts.author ?? "qScan",
+    timestamp: result.finishedAt,
+    version: 1,
+    statements,
+  };
+}

package/src/walk.ts

@@ -11,7 +11,7 @@ import * as path from "node:path";
 import { isManifestFile } from "./dependencies.js";
 
 /** Directories ignored by default (can be disabled with noDefaultIgnores). */
-export const DEFAULT_IGNORES: readonly string[] = [
+const DEFAULT_IGNORES: readonly string[] = [
   "node_modules",
   ".git",
   "dist",
@@ -99,7 +99,7 @@ const BINARY_EXTENSIONS = new Set<string>([
 ]);
 
 /** Options accepted by {@link walkFiles}. */
-export interface WalkOptions {
+interface WalkOptions {
   /**
    * Restrict to paths matching one of these include patterns (substring or
    * relative-path-prefix match). When omitted/empty, all files pass.
@@ -222,6 +222,37 @@ export function isBinaryPath(rel: string): boolean {
   return BINARY_EXTENSIONS.has(ext);
 }
 
+/**
+ * Binary cryptographic key containers we DO want to scan — Java/PKCS#12 keystores
+ * and binary OpenPGP keyrings/messages. Unlike the images/archives above these are
+ * read byte-preserving (latin1) and exempted from the minified skip, so the
+ * keystore + openpgp detectors can identify them by magic number / packet tag.
+ * Kept separate from {@link BINARY_EXTENSIONS} so those detectors can opt in.
+ */
+const KEYSTORE_EXTENSIONS = new Set<string>([
+  ".jks",
+  ".keystore",
+  ".jceks",
+  ".bks",
+  ".p12",
+  ".pfx",
+  // Binary OpenPGP keyrings / messages (armored .asc is text; handled elsewhere).
+  ".gpg",
+  ".pgp",
+  ".kbx",
+]);
+
+/**
+ * True if the path is a binary cryptographic key container we scan byte-preserving.
+ * Uses a suffix match (not `extname`) so it agrees with the detectors' `hasExtension`
+ * even for a bare dotfile literally named e.g. `.gpg` (where `extname` returns "").
+ */
+export function isKeystorePath(rel: string): boolean {
+  const lower = rel.toLowerCase();
+  for (const ext of KEYSTORE_EXTENSIONS) if (lower.endsWith(ext)) return true;
+  return false;
+}
+
 /**
  * Compound / pattern extensions that mark generated or bundled output we skip
  * by default (beyond `.min.js` / `.map`, which {@link isBinaryPath} handles).
@@ -260,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;
@@ -281,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;
   }
@@ -296,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 });
@@ -346,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 };
   }
 }