@quantakrypto/core 0.1.0

package/src/config.ts

@@ -0,0 +1,295 @@
+/**
+ * `quantakrypto.config.json` loader (ROADMAP P2-9, see docs/CONFIG.md).
+ *
+ * Reads an optional project configuration file, validates the *types* of known
+ * keys, ignores unknown keys (forward compatibility), and maps it onto a
+ * `Partial<ScanOptions>` plus the two policy keys qScan consumes
+ * (`severityThreshold`, `baseline`). It performs NO scanning and has no
+ * side-effects beyond a single `readFile`.
+ *
+ * Precedence (resolved by the consumer, not here): flags > config > defaults.
+ *
+ * The parsed object is treated as **untrusted input** in the same spirit as a
+ * scanned manifest (THREAT-MODEL Q-09): we only membership-test known keys and
+ * never deep-merge the parsed object into anything.
+ */
+import { readFile } from "node:fs/promises";
+import * as path from "node:path";
+
+import type { ScanOptions, Severity } from "./types.js";
+
+/** Canonical config file name discovered at a scan root. */
+export const CONFIG_FILENAME = "quantakrypto.config.json";
+
+/** Severity levels accepted by `severityThreshold`, for validation. */
+const SEVERITIES: readonly Severity[] = ["critical", "high", "medium", "low", "info"];
+
+/** Detector-family toggle names recognised in the `detectors` object. */
+const DETECTOR_FAMILIES = [
+  "node-crypto",
+  "webcrypto",
+  "crypto-libs",
+  "jwt-jose",
+  "tls-config",
+  "pem-material",
+  "dependencies",
+] as const;
+
+/**
+ * The slice of options a `quantakrypto.config.json` can set. A subset of
+ * {@link ScanOptions} (the file-selection + scope keys) extended with the two
+ * policy keys qScan owns: `severityThreshold` and `baseline`.
+ *
+ * `root`, `files`, `detectors` (the programmatic detector array), and `onFile`
+ * are intentionally NOT configurable from a file — they are call-site concerns.
+ */
+export interface QuantakryptoFileConfig extends Partial<
+  Pick<
+    ScanOptions,
+    | "include"
+    | "exclude"
+    | "noDefaultIgnores"
+    | "maxFileSize"
+    | "scanMinified"
+    | "source"
+    | "dependencies"
+    | "config"
+  >
+> {
+  /** Gate severity (drives the exit code). Maps to qScan's `severityThreshold`. */
+  severityThreshold?: Severity;
+  /** Path to a baseline file, relative to the config file's directory. */
+  baseline?: string;
+}
+
+/** Result of {@link loadConfig}: the resolved config plus where it came from. */
+export interface LoadConfigResult {
+  /** Validated, mapped config. Empty object when no file was found. */
+  config: QuantakryptoFileConfig;
+  /** Absolute path of the file that was loaded, when one was. */
+  path?: string;
+  /**
+   * Non-fatal warnings (unknown keys, unknown future `version`). The caller may
+   * surface these; they never abort the load.
+   */
+  warnings: string[];
+}
+
+/** Thrown when a known key has a malformed *value* (a usage error: exit 2). */
+export class ConfigError extends Error {
+  override readonly name = "ConfigError";
+  /** The config file path the error relates to, when known. */
+  readonly path: string | undefined;
+  constructor(message: string, configPath?: string) {
+    super(message);
+    this.path = configPath;
+  }
+}
+
+function isObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/** Validate an optional boolean field; returns it or undefined, or throws. */
+function asBool(obj: Record<string, unknown>, key: string, file: string): boolean | undefined {
+  if (!(key in obj)) return undefined;
+  const v = obj[key];
+  if (typeof v !== "boolean") {
+    throw new ConfigError(`"${key}" must be a boolean (got ${typeof v})`, file);
+  }
+  return v;
+}
+
+/** Validate an optional non-negative-integer field. */
+function asInt(obj: Record<string, unknown>, key: string, file: string): number | undefined {
+  if (!(key in obj)) return undefined;
+  const v = obj[key];
+  if (typeof v !== "number" || !Number.isInteger(v) || v < 0) {
+    throw new ConfigError(`"${key}" must be a non-negative integer`, file);
+  }
+  return v;
+}
+
+/** Validate an optional string[] field (every element must be a string). */
+function asStringArray(
+  obj: Record<string, unknown>,
+  key: string,
+  file: string,
+): string[] | undefined {
+  if (!(key in obj)) return undefined;
+  const v = obj[key];
+  if (!Array.isArray(v) || !v.every((x): x is string => typeof x === "string")) {
+    throw new ConfigError(`"${key}" must be an array of strings`, file);
+  }
+  return [...v];
+}
+
+/**
+ * Map the validated raw JSON object onto a {@link QuantakryptoFileConfig}. Throws
+ * {@link ConfigError} on a malformed *value* for any known key; collects
+ * warnings for unknown keys and unrecognised `version`.
+ */
+function mapConfig(
+  raw: Record<string, unknown>,
+  file: string,
+  warnings: string[],
+): QuantakryptoFileConfig {
+  // Known top-level keys. Anything else is a warning, not an error.
+  const KNOWN = new Set([
+    "$schema",
+    "version",
+    "include",
+    "exclude",
+    "noDefaultIgnores",
+    "maxFileSize",
+    "scanMinified",
+    "detectors",
+    "languages",
+    "severityThreshold",
+    "baseline",
+  ]);
+  for (const key of Object.keys(raw)) {
+    if (!KNOWN.has(key)) warnings.push(`unknown config key "${key}" ignored`);
+  }
+
+  // version: known forward-compat warning only.
+  if ("version" in raw) {
+    const version = raw["version"];
+    if (typeof version !== "number" || !Number.isInteger(version)) {
+      throw new ConfigError(`"version" must be an integer`, file);
+    }
+    if (version !== 1) {
+      warnings.push(`config "version" ${version} is newer than supported (1); best-effort`);
+    }
+  }
+
+  const out: QuantakryptoFileConfig = {};
+
+  const include = asStringArray(raw, "include", file);
+  if (include) out.include = include;
+  const exclude = asStringArray(raw, "exclude", file);
+  if (exclude) out.exclude = exclude;
+
+  const noDefaultIgnores = asBool(raw, "noDefaultIgnores", file);
+  if (noDefaultIgnores !== undefined) out.noDefaultIgnores = noDefaultIgnores;
+  const scanMinified = asBool(raw, "scanMinified", file);
+  if (scanMinified !== undefined) out.scanMinified = scanMinified;
+
+  const maxFileSize = asInt(raw, "maxFileSize", file);
+  if (maxFileSize !== undefined) out.maxFileSize = maxFileSize;
+
+  // detectors.<family> bool map → source / dependencies / config scope toggles.
+  // A family turned off is equivalent to its `--no-*` flag (per docs/CONFIG.md
+  // §4.1). We collapse the per-family map onto the three scan-scope toggles:
+  //   dependencies → ScanOptions.dependencies
+  //   pem-material + tls-config → ScanOptions.config (config-scope detectors)
+  //   the JS source families → ScanOptions.source (source-scope detectors)
+  // Only an explicit `false` flips a toggle off; absent/true leaves the default.
+  if ("detectors" in raw) {
+    const det = raw["detectors"];
+    if (!isObject(det)) {
+      throw new ConfigError(`"detectors" must be an object of family→boolean`, file);
+    }
+    for (const key of Object.keys(det)) {
+      if (!(DETECTOR_FAMILIES as readonly string[]).includes(key)) {
+        warnings.push(`unknown detector family "${key}" ignored`);
+        continue;
+      }
+      const v = det[key];
+      if (typeof v !== "boolean") {
+        throw new ConfigError(`"detectors.${key}" must be a boolean`, file);
+      }
+      if (v) continue; // true = default; nothing to disable.
+      switch (key) {
+        case "dependencies":
+          out.dependencies = false;
+          break;
+        case "tls-config":
+        case "pem-material":
+          out.config = false;
+          break;
+        default:
+          // node-crypto / webcrypto / crypto-libs / jwt-jose are source-scope.
+          out.source = false;
+          break;
+      }
+    }
+  }
+
+  // languages: forward-looking (inert until the plugin registry lands). Validate
+  // the type so the file format is stable, but do not map it anywhere.
+  const languages = asStringArray(raw, "languages", file);
+  if (languages) warnings.push(`"languages" is accepted but inert until detector plugins land`);
+
+  // severityThreshold: enum.
+  if ("severityThreshold" in raw) {
+    const sev = raw["severityThreshold"];
+    if (typeof sev !== "string" || !(SEVERITIES as readonly string[]).includes(sev)) {
+      throw new ConfigError(`"severityThreshold" must be one of: ${SEVERITIES.join(", ")}`, file);
+    }
+    out.severityThreshold = sev as Severity;
+  }
+
+  // baseline: path string, resolved relative to the config file's directory.
+  if ("baseline" in raw) {
+    const baseline = raw["baseline"];
+    if (typeof baseline !== "string" || baseline.length === 0) {
+      throw new ConfigError(`"baseline" must be a non-empty path string`, file);
+    }
+    out.baseline = path.isAbsolute(baseline) ? baseline : path.join(path.dirname(file), baseline);
+  }
+
+  return out;
+}
+
+/**
+ * Load a `quantakrypto.config.json` for a scan.
+ *
+ * By default reads `<root>/quantakrypto.config.json`. Pass an explicit file path as
+ * `root` (or via the caller's `--config` flag) to read a named file instead —
+ * if the path's basename is `quantakrypto.config.json` it is read directly; otherwise
+ * the path is treated as a directory and the file is looked up inside it. When
+ * an explicit path is given but missing, that is an error; an *absent*
+ * auto-discovered file is tolerated (returns an empty config).
+ *
+ * @param root Directory to look in, OR an explicit config file path.
+ * @param opts.explicit When true, a missing file is an error (the user named it).
+ * @throws {ConfigError} On malformed JSON, a bad value for a known key, or a
+ *   missing explicitly-named file.
+ */
+export async function loadConfig(
+  root: string,
+  opts: { explicit?: boolean } = {},
+): Promise<LoadConfigResult> {
+  // Resolve the file path: an explicit *.json file is used verbatim; otherwise
+  // treat `root` as a directory and append the canonical name.
+  const base = path.basename(root);
+  const file =
+    base === CONFIG_FILENAME || base.endsWith(".json")
+      ? path.resolve(root)
+      : path.resolve(root, CONFIG_FILENAME);
+
+  let text: string;
+  try {
+    text = await readFile(file, "utf8");
+  } catch {
+    if (opts.explicit) {
+      throw new ConfigError(`config file not found: ${file}`, file);
+    }
+    return { config: {}, warnings: [] }; // tolerant when auto-discovering.
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch (err) {
+    throw new ConfigError(`invalid JSON in ${file}: ${(err as Error).message}`, file);
+  }
+  if (!isObject(parsed)) {
+    throw new ConfigError(`config must be a JSON object, got ${typeof parsed}`, file);
+  }
+
+  const warnings: string[] = [];
+  const config = mapConfig(parsed, file, warnings);
+  return { config, path: file, warnings };
+}

package/src/cwe.ts

@@ -0,0 +1,20 @@
+/**
+ * CWE (Common Weakness Enumeration) identifiers used to tag findings. These
+ * feed SARIF rule taxa / properties and the CBOM export, and let downstream
+ * compliance tooling map quantaKrypto findings to a standard weakness taxonomy.
+ */
+
+/** CWE-327: Use of a Broken or Risky Cryptographic Algorithm. */
+export const CWE_BROKEN_CRYPTO = "CWE-327";
+
+/** CWE-326: Inadequate Encryption Strength. */
+export const CWE_WEAK_STRENGTH = "CWE-326";
+
+/** CWE-295: Improper Certificate Validation. */
+export const CWE_CERT_VALIDATION = "CWE-295";
+
+/** CWE-798: Use of Hard-coded Credentials (embedded private keys). */
+export const CWE_HARDCODED_KEY = "CWE-798";
+
+/** CWE-1240: Use of a Cryptographic Primitive with a Risky Implementation. */
+export const CWE_RISKY_PRIMITIVE = "CWE-1240";

package/src/dependencies.ts

@@ -0,0 +1,299 @@
+/**
+ * Curated database of npm packages that primarily expose classical asymmetric
+ * cryptography (and are therefore quantum-vulnerable), plus a manifest scanner
+ * that flags any of them found in package.json / package-lock.json.
+ *
+ * The list is intentionally focused on libraries whose *purpose* is classical
+ * public-key crypto. General-purpose packages that merely call out to Node's
+ * crypto are out of scope here (those are caught by the source detectors).
+ */
+import type { AlgorithmFamily, Finding, VulnerableDependency } from "./types.js";
+import { makeFinding } from "./detect-utils.js";
+import { remediationText } from "./remediation.js";
+import { CWE_BROKEN_CRYPTO } from "./cwe.js";
+
+/** Known quantum-vulnerable npm dependencies. */
+export const vulnerableDependencies: VulnerableDependency[] = [
+  {
+    name: "node-forge",
+    ecosystem: "npm",
+    reason: "Pure-JS implementation of RSA, RSA-OAEP, and X.509 PKI.",
+    algorithms: ["RSA"],
+    severity: "high",
+  },
+  {
+    name: "elliptic",
+    ecosystem: "npm",
+    reason: "Elliptic-curve ECDSA/ECDH (secp256k1, p256, ed25519).",
+    algorithms: ["ECDSA", "ECDH", "EdDSA"],
+    severity: "high",
+  },
+  {
+    name: "jsrsasign",
+    ecosystem: "npm",
+    reason: "RSA/ECDSA/DSA signing, JWT, and X.509 in pure JS.",
+    algorithms: ["RSA", "ECDSA", "DSA"],
+    severity: "high",
+  },
+  {
+    name: "node-rsa",
+    ecosystem: "npm",
+    reason: "Classical RSA encryption and signing.",
+    algorithms: ["RSA"],
+    severity: "high",
+  },
+  {
+    name: "ursa",
+    ecosystem: "npm",
+    reason: "OpenSSL-backed RSA encryption and signing bindings.",
+    algorithms: ["RSA"],
+    severity: "high",
+  },
+  {
+    name: "sshpk",
+    ecosystem: "npm",
+    reason: "Parses/handles SSH and PEM keys (RSA, ECDSA, Ed25519, DSA).",
+    algorithms: ["RSA", "ECDSA", "EdDSA", "DSA"],
+    severity: "medium",
+  },
+  {
+    name: "jsonwebtoken",
+    ecosystem: "npm",
+    reason: "JWTs commonly signed with RS256/ES256 (classical RSA/ECDSA).",
+    algorithms: ["RSA", "ECDSA"],
+    severity: "high",
+  },
+  {
+    name: "jose",
+    ecosystem: "npm",
+    reason: "JWS/JWE with classical RSA-OAEP, RSA-PSS, ECDH-ES and ECDSA.",
+    algorithms: ["RSA", "ECDH", "ECDSA", "EdDSA"],
+    severity: "high",
+  },
+  {
+    name: "jws",
+    ecosystem: "npm",
+    reason: "JSON Web Signatures using classical RS/ES algorithms.",
+    algorithms: ["RSA", "ECDSA"],
+    severity: "high",
+  },
+  {
+    name: "eccrypto",
+    ecosystem: "npm",
+    reason: "ECIES (ECDH-based) encryption and ECDSA signatures.",
+    algorithms: ["ECIES", "ECDH", "ECDSA"],
+    severity: "high",
+  },
+  {
+    name: "secp256k1",
+    ecosystem: "npm",
+    reason: "secp256k1 ECDSA/ECDH bindings (blockchain keys).",
+    algorithms: ["ECDSA", "ECDH"],
+    severity: "high",
+  },
+  {
+    name: "tweetnacl",
+    ecosystem: "npm",
+    reason: "X25519 key exchange and Ed25519 signatures (modern but classical).",
+    algorithms: ["X25519", "EdDSA"],
+    severity: "low",
+  },
+  {
+    name: "ed25519",
+    ecosystem: "npm",
+    reason: "Ed25519 signatures (classical).",
+    algorithms: ["EdDSA"],
+    severity: "low",
+  },
+  {
+    name: "@noble/curves",
+    ecosystem: "npm",
+    reason: "Audited classical curves: ECDSA, ECDH, Ed25519, X25519, secp256k1.",
+    algorithms: ["ECDSA", "ECDH", "EdDSA", "X25519"],
+    severity: "medium",
+  },
+  {
+    name: "@noble/secp256k1",
+    ecosystem: "npm",
+    reason: "secp256k1 ECDSA/ECDH (classical).",
+    algorithms: ["ECDSA", "ECDH"],
+    severity: "medium",
+  },
+  {
+    name: "@noble/ed25519",
+    ecosystem: "npm",
+    reason: "Ed25519 signatures and X25519 key exchange (classical).",
+    algorithms: ["EdDSA", "X25519"],
+    severity: "low",
+  },
+  {
+    name: "paseto",
+    ecosystem: "npm",
+    reason: "PASETO public tokens signed with classical Ed25519 (v2/v4) or RSA.",
+    algorithms: ["EdDSA", "RSA"],
+    severity: "medium",
+  },
+  {
+    name: "bcrypto",
+    ecosystem: "npm",
+    reason: "Broad classical crypto suite: RSA, ECDSA, ECDH, Ed25519, DSA.",
+    algorithms: ["RSA", "ECDSA", "ECDH", "EdDSA", "DSA"],
+    severity: "high",
+  },
+  {
+    name: "ecpair",
+    ecosystem: "npm",
+    reason: "secp256k1 ECDSA key pairs for Bitcoin.",
+    algorithms: ["ECDSA"],
+    severity: "medium",
+  },
+  {
+    name: "keypair",
+    ecosystem: "npm",
+    reason: "Pure-JS RSA key pair generation.",
+    algorithms: ["RSA"],
+    severity: "high",
+  },
+];
+
+/** Fast lookup map by package name. */
+const BY_NAME = new Map<string, VulnerableDependency>(
+  vulnerableDependencies.map((d) => [d.name, d]),
+);
+
+/**
+ * Precompiled `"name":` lookup regex per known package (P1-9): the package set
+ * is static, so we build the (escaped-name → RegExp) map once at module load
+ * rather than recompiling a fresh RegExp per found package per manifest.
+ */
+const KEY_REGEX_BY_NAME = new Map<string, RegExp>(
+  vulnerableDependencies.map((d): [string, RegExp] => {
+    const escaped = d.name.replace(/[.*+?^${}()|[\]\\/]/g, "\\$&");
+    return [d.name, new RegExp(`"${escaped}"\\s*:`)];
+  }),
+);
+
+/** Algorithm families that expose confidentiality (HNDL) rather than only signing. */
+const CONFIDENTIALITY_FAMILIES: ReadonlySet<AlgorithmFamily> = new Set<AlgorithmFamily>([
+  "RSA",
+  "ECDH",
+  "DH",
+  "ECIES",
+  "X25519",
+  "X448",
+]);
+
+/**
+ * Build a remediation string covering ALL families a package exposes (C5),
+ * rather than only `algorithms[0]`. De-duplicates the per-family recommendation
+ * strings and joins them, so a signature+KEM library points at both replacements.
+ */
+function multiFamilyRemediation(algorithms: readonly AlgorithmFamily[]): string {
+  const parts = new Set<string>();
+  for (const a of algorithms) parts.add(remediationText(a));
+  return [...parts].join("; ");
+}
+
+/** True if a file path looks like a manifest we can parse for dependencies. */
+export function isManifestFile(file: string): boolean {
+  const base = file.split("/").pop() ?? file;
+  return base === "package.json" || base === "package-lock.json";
+}
+
+/**
+ * Build a finding for a vulnerable dependency located in a manifest. The
+ * location points at the line where the package name appears in the file (best
+ * effort), falling back to line 1.
+ */
+function dependencyFinding(
+  dep: VulnerableDependency,
+  file: string,
+  content: string,
+  index: number,
+): Finding {
+  // Use the first listed algorithm for the headline family, but derive the
+  // remediation from ALL families the package exposes (C5).
+  const algorithm = dep.algorithms[0] ?? "unknown";
+  return makeFinding({
+    ruleId: "dep-vulnerable",
+    title: `Quantum-vulnerable dependency: ${dep.name}`,
+    category: "dependency",
+    severity: dep.severity,
+    confidence: "high",
+    algorithm,
+    // Confidentiality libs are HNDL-exposed; signature-only ones are not.
+    hndl: dep.algorithms.some((a) => CONFIDENTIALITY_FAMILIES.has(a)),
+    cwe: CWE_BROKEN_CRYPTO,
+    message: `${dep.name} — ${dep.reason}`,
+    remediation: multiFamilyRemediation(dep.algorithms),
+    file,
+    content,
+    index,
+  });
+}
+
+/** Locate the offset of a JSON key `"name"` in the manifest text (or 0). */
+function offsetOfKey(content: string, name: string): number {
+  // Use the precompiled per-name regex (non-global; .exec from position 0).
+  const re = KEY_REGEX_BY_NAME.get(name);
+  if (!re) return 0;
+  const m = re.exec(content);
+  return m ? m.index : 0;
+}
+
+/**
+ * Scan a single manifest file's contents for vulnerable dependencies.
+ *
+ * - `package.json`: dependencies / devDependencies / peerDependencies / optionalDependencies.
+ * - `package-lock.json` (v2/v3): the `packages` map keys (node_modules/<name>),
+ *   plus legacy `dependencies` map for v1.
+ *
+ * Returns one finding per distinct vulnerable package name found in the file.
+ */
+export function scanManifest(file: string, content: string): Finding[] {
+  let json: unknown;
+  try {
+    json = JSON.parse(content);
+  } catch {
+    return []; // not valid JSON — skip quietly.
+  }
+  if (json === null || typeof json !== "object") return [];
+
+  const found = new Set<string>();
+  const obj = json as Record<string, unknown>;
+
+  const collectFromRecord = (rec: unknown): void => {
+    if (rec === null || typeof rec !== "object") return;
+    for (const key of Object.keys(rec as Record<string, unknown>)) {
+      if (BY_NAME.has(key)) found.add(key);
+    }
+  };
+
+  // package.json dependency sections.
+  collectFromRecord(obj.dependencies);
+  collectFromRecord(obj.devDependencies);
+  collectFromRecord(obj.peerDependencies);
+  collectFromRecord(obj.optionalDependencies);
+
+  // package-lock.json v2/v3 "packages" map: keys are "node_modules/<name>".
+  const packages = obj.packages;
+  if (packages !== null && typeof packages === "object") {
+    for (const key of Object.keys(packages as Record<string, unknown>)) {
+      if (!key) continue; // root package entry
+      const marker = "node_modules/";
+      const idx = key.lastIndexOf(marker);
+      const name = idx >= 0 ? key.slice(idx + marker.length) : key;
+      if (BY_NAME.has(name)) found.add(name);
+    }
+  }
+
+  const findings: Finding[] = [];
+  for (const name of found) {
+    const dep = BY_NAME.get(name);
+    if (!dep) continue;
+    findings.push(dependencyFinding(dep, file, content, offsetOfKey(content, name)));
+  }
+  // Deterministic ordering by package name.
+  findings.sort((a, b) => (a.title < b.title ? -1 : a.title > b.title ? 1 : 0));
+  return findings;
+}