@quantakrypto/core 0.4.3 → 0.5.0

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/standards.ts

@@ -0,0 +1,186 @@
+/**
+ * Single source of truth for the post-quantum standards this tool depends on.
+ *
+ * The scanner's credibility rests on its recommendations tracking the current
+ * NIST / CNSA / IETF state. That tracking used to be ad-hoc — facts were spread
+ * across `remediation.ts` with no dates, no citations, and nothing to catch code
+ * drifting from the published standards. This module makes the standards facts
+ * explicit, dated, and cited, and the companion drift test
+ * (`test/standards.test.ts`) fails the build if the runtime constants
+ * (`TIER_PARAMS`, `PQC_TRANSITION_NOTE`, `STATEFUL_HBS_NOTE`) fall out of sync
+ * with what is recorded here.
+ *
+ * ## Cadence
+ *
+ * Re-verify every quarter (see `docs/standards/pqc-standards.md` for the runbook).
+ * On each review: check the sources below for changes, update the facts + their
+ * `asOf`, and roll `lastReviewed` / `nextReview` forward. `scripts/standards-check.mjs`
+ * (advisory, runs in CI) flags when `nextReview` has passed so a review can't be
+ * silently skipped. `standardsReviewStatus(now)` is the pure predicate behind it.
+ */
+
+/** A single standards fact with its citation and when it was last verified. */
+export interface StandardsCitation {
+  /** One-line statement of the fact. */
+  readonly summary: string;
+  /** Spec identifier / publication (and URL where stable). */
+  readonly source: string;
+  /** `YYYY-MM` — when this fact was last verified against its source. */
+  readonly asOf: string;
+}
+
+/** The full post-quantum standards snapshot the tool tracks. */
+export interface PqcStandards {
+  /** `YYYY-MM-DD` — when the whole snapshot was last reviewed. */
+  readonly lastReviewed: string;
+  /** `YYYY-MM-DD` — when the next review is due. */
+  readonly nextReview: string;
+  /** Cadence, in months, between reviews. */
+  readonly reviewIntervalMonths: number;
+
+  /** NIST's finalized PQC FIPS (the recommendation targets). */
+  readonly fips: {
+    readonly mlKem: StandardsCitation; // FIPS 203
+    readonly mlDsa: StandardsCitation; // FIPS 204
+    readonly slhDsa: StandardsCitation; // FIPS 205
+  };
+
+  /**
+   * CNSA 2.0 security tiers → the KEM / signature parameter sets. These MUST
+   * mirror `remediation.TIER_PARAMS`; the drift test asserts they stay identical.
+   */
+  readonly cnsa: {
+    readonly category3: { readonly kem: string; readonly signature: string };
+    readonly category5: { readonly kem: string; readonly signature: string };
+    readonly source: string;
+    readonly asOf: string;
+  };
+
+  /** Stateful hash-based signatures (firmware / boot signing). */
+  readonly statefulHbs: StandardsCitation; // SP 800-208
+
+  /** The migration deadline the transition note surfaces. */
+  readonly transitionTimeline: {
+    /** Year after which classical public-key crypto is deprecated. */
+    readonly deprecateAfter: number;
+    /** Year after which it is disallowed. */
+    readonly disallowAfter: number;
+    readonly source: string;
+    readonly asOf: string;
+  };
+
+  /** Emerging / backup standards worth tracking beyond the current FIPS. */
+  readonly emerging: readonly StandardsCitation[];
+
+  /** Recommended hybrid key-exchange groups. */
+  readonly hybrids: readonly StandardsCitation[];
+}
+
+/**
+ * The current snapshot. Update on each quarterly review; the drift test keeps the
+ * runtime remediation constants aligned with it.
+ */
+export const PQC_STANDARDS: PqcStandards = {
+  lastReviewed: "2026-07-19",
+  nextReview: "2026-10-19",
+  reviewIntervalMonths: 3,
+
+  fips: {
+    mlKem: {
+      summary: "ML-KEM (Kyber) key encapsulation — finalized August 2024.",
+      source: "NIST FIPS 203",
+      asOf: "2026-07",
+    },
+    mlDsa: {
+      summary: "ML-DSA (Dilithium) lattice signatures — finalized August 2024.",
+      source: "NIST FIPS 204",
+      asOf: "2026-07",
+    },
+    slhDsa: {
+      summary: "SLH-DSA (SPHINCS+) stateless hash-based signatures — finalized August 2024.",
+      source: "NIST FIPS 205",
+      asOf: "2026-07",
+    },
+  },
+
+  cnsa: {
+    category3: { kem: "ML-KEM-768 (FIPS 203)", signature: "ML-DSA-65 (FIPS 204)" },
+    category5: { kem: "ML-KEM-1024 (FIPS 203)", signature: "ML-DSA-87 (FIPS 204)" },
+    source: "NSA CNSA 2.0 (national-security systems; 2030/2033 migration milestones)",
+    asOf: "2026-07",
+  },
+
+  statefulHbs: {
+    summary:
+      "LMS/HSS and XMSS/XMSSMT stateful hash-based signatures (incl. the SHAKE256 and " +
+      "192-bit parameter sets) are approved for firmware/boot signing, but are STATEFUL.",
+    source: "NIST SP 800-208",
+    asOf: "2026-07",
+  },
+
+  transitionTimeline: {
+    deprecateAfter: 2030,
+    disallowAfter: 2035,
+    source: "NIST IR 8547 (transition to post-quantum cryptography standards)",
+    asOf: "2026-07",
+  },
+
+  emerging: [
+    {
+      summary:
+        "HQC — NIST's code-based backup KEM (selected March 2025; draft FIPS expected ~2026), a " +
+        "diversity hedge against ML-KEM's lattice assumption.",
+      source: "NIST PQC (HQC selection)",
+      asOf: "2026-07",
+    },
+    {
+      summary: "FN-DSA / Falcon — compact lattice signatures.",
+      source: "NIST draft FIPS 206",
+      asOf: "2026-07",
+    },
+    {
+      summary: "X-Wing — X25519 + ML-KEM-768 hybrid KEM for HPKE-style encryption.",
+      source: "IETF draft-connolly-cfrg-xwing-kem",
+      asOf: "2026-07",
+    },
+  ],
+
+  hybrids: [
+    {
+      summary: "X25519MLKEM768 — the default TLS 1.3 hybrid key-exchange group.",
+      source: "IETF draft-ietf-tls-ecdhe-mlkem",
+      asOf: "2026-07",
+    },
+    {
+      summary: "SecP384r1MLKEM1024 — the Category-5 / CNSA hybrid key-exchange group.",
+      source: "IETF draft-ietf-tls-ecdhe-mlkem",
+      asOf: "2026-07",
+    },
+  ],
+};
+
+/** Result of {@link standardsReviewStatus}. */
+export interface StandardsReviewStatus {
+  /** True when `now` is on or after `nextReview` — a review is due. */
+  readonly due: boolean;
+  /** The `nextReview` date being compared against (`YYYY-MM-DD`). */
+  readonly nextReview: string;
+  /** Whole days from `now` until `nextReview` (negative when overdue). */
+  readonly daysUntil: number;
+}
+
+/**
+ * Whether a standards review is due as of `now`. Pure (takes `now` explicitly) so
+ * it is deterministic in tests; the CI script passes the real clock. Compares on
+ * whole UTC days so a same-day run is not spuriously "overdue".
+ */
+export function standardsReviewStatus(
+  now: Date,
+  standards: PqcStandards = PQC_STANDARDS,
+): StandardsReviewStatus {
+  const MS_PER_DAY = 86_400_000;
+  const next = Date.parse(`${standards.nextReview}T00:00:00Z`);
+  const today = Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate());
+  const daysUntil = Math.round((next - today) / MS_PER_DAY);
+  return { due: daysUntil <= 0, nextReview: standards.nextReview, daysUntil };
+}

package/src/types.ts

@@ -134,7 +134,13 @@ export type DetectorLanguage =
   | "csharp"
   | "rust"
   | "ruby"
+  | "php"
+  | "elixir"
   | "c"
+  | "swift"
+  | "objc"
+  | "dart"
+  | "solidity"
   | "any";
 
 /**
@@ -342,10 +348,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.3";
+export const VERSION = "0.5.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).