@quantakrypto/core 0.1.0

package/dist/walk.js

@@ -0,0 +1,260 @@
+/**
+ * Filesystem walker. A zero-dependency recursive async generator that yields
+ * scannable text files as relative POSIX paths. It honours a default ignore
+ * list, user-supplied exclude patterns, a max file size, and a binary-extension
+ * filter. The root may be a directory or a single file.
+ */
+import { readdir, stat } from "node:fs/promises";
+import * as path from "node:path";
+/** Directories ignored by default (can be disabled with noDefaultIgnores). */
+export const DEFAULT_IGNORES = [
+    "node_modules",
+    ".git",
+    "dist",
+    "build",
+    ".next",
+    "out",
+    "coverage",
+    "vendor",
+    ".turbo",
+    ".cache",
+];
+/** Default maximum file size to read: 2 MiB. */
+export const DEFAULT_MAX_FILE_SIZE = 2 * 1024 * 1024;
+/**
+ * File extensions we treat as binary / non-text and therefore skip. Keeping this
+ * as an extension allow-list-by-exclusion is cheap and avoids reading bytes.
+ */
+const BINARY_EXTENSIONS = new Set([
+    // images
+    ".png",
+    ".jpg",
+    ".jpeg",
+    ".gif",
+    ".webp",
+    ".bmp",
+    ".ico",
+    ".tiff",
+    ".avif",
+    // fonts
+    ".woff",
+    ".woff2",
+    ".ttf",
+    ".otf",
+    ".eot",
+    // archives / compressed
+    ".zip",
+    ".gz",
+    ".tgz",
+    ".bz2",
+    ".xz",
+    ".7z",
+    ".rar",
+    ".tar",
+    // media
+    ".mp3",
+    ".mp4",
+    ".mov",
+    ".avi",
+    ".mkv",
+    ".wav",
+    ".flac",
+    ".ogg",
+    ".webm",
+    // documents / binaries
+    ".pdf",
+    ".doc",
+    ".docx",
+    ".xls",
+    ".xlsx",
+    ".ppt",
+    ".pptx",
+    ".exe",
+    ".dll",
+    ".so",
+    ".dylib",
+    ".bin",
+    ".o",
+    ".a",
+    ".class",
+    ".wasm",
+    // data blobs / db
+    ".db",
+    ".sqlite",
+    ".sqlite3",
+    ".dat",
+    ".pack",
+    ".idx",
+    // misc
+    ".lock",
+    ".map",
+    ".min.js",
+    ".node",
+]);
+/** Normalise a path to forward-slash POSIX separators. */
+export function toPosix(p) {
+    return p.split(path.sep).join("/");
+}
+/** True if `rel` (a POSIX relative path) matches any pattern (substring/prefix). */
+function matchesAny(rel, patterns) {
+    for (const pattern of patterns) {
+        if (!pattern)
+            continue;
+        const p = toPosix(pattern).replace(/\/+$/, "");
+        // Substring match (handles "src/legacy" or "secrets")...
+        if (rel.includes(p))
+            return true;
+        // ...and explicit path-prefix match ("foo" should match "foo/bar.ts").
+        if (rel === p || rel.startsWith(`${p}/`))
+            return true;
+    }
+    return false;
+}
+/** True if `rel` (a POSIX relative path) matches any exclude pattern. */
+function isExcluded(rel, exclude) {
+    return matchesAny(rel, exclude);
+}
+/**
+ * True if `rel` passes the include filter. An empty include list means "include
+ * everything"; otherwise the file must match at least one include pattern.
+ */
+function isIncluded(rel, include) {
+    if (include.length === 0)
+        return true;
+    return matchesAny(rel, include);
+}
+/** True if the file's extension marks it as binary / non-text. */
+export function isBinaryPath(rel) {
+    const lower = rel.toLowerCase();
+    // Handle compound extensions like ".min.js" first.
+    if (lower.endsWith(".min.js"))
+        return true;
+    const ext = path.posix.extname(lower);
+    return BINARY_EXTENSIONS.has(ext);
+}
+/**
+ * Compound / pattern extensions that mark generated or bundled output we skip
+ * by default (beyond `.min.js` / `.map`, which {@link isBinaryPath} handles).
+ */
+const GENERATED_PATH_RE = /(?:\.min\.[mc]?js|[.-]min\.[mc]?js|\.bundle\.[mc]?js|\.chunk\.[mc]?js|\.generated\.[jt]sx?|_pb\.js|\.pb\.go)$/i;
+/** True if the path looks like generated / bundled output (by name). */
+export function isGeneratedPath(rel) {
+    return GENERATED_PATH_RE.test(rel.toLowerCase());
+}
+/**
+ * Heuristic content check for machine-minified / generated files with no
+ * telltale extension: a very long average line length, or any single line over
+ * ~50 KB, in the first ~64 KB sampled. Used at read time, not in the walker.
+ */
+export function looksMinified(content) {
+    const sample = content.length > 65_536 ? content.slice(0, 65_536) : content;
+    if (sample.length === 0)
+        return false;
+    let maxLine = 0;
+    let cur = 0;
+    let lines = 1;
+    for (let i = 0; i < sample.length; i++) {
+        if (sample.charCodeAt(i) === 10 /* \n */) {
+            if (cur > maxLine)
+                maxLine = cur;
+            cur = 0;
+            lines++;
+        }
+        else {
+            cur++;
+        }
+    }
+    if (cur > maxLine)
+        maxLine = cur;
+    if (maxLine > 50_000)
+        return true;
+    const avgLine = sample.length / lines;
+    return avgLine > 1_000;
+}
+/**
+ * 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).
+ */
+export async function* walkFiles(root, options = {}) {
+    const include = options.include ?? [];
+    const exclude = options.exclude ?? [];
+    const maxFileSize = options.maxFileSize ?? DEFAULT_MAX_FILE_SIZE;
+    const ignores = options.noDefaultIgnores ? [] : DEFAULT_IGNORES;
+    const rootStat = await stat(root);
+    // Single-file mode: yield the file itself (by basename) if it passes filters.
+    if (rootStat.isFile()) {
+        const name = toPosix(path.basename(root));
+        if (!isBinaryPath(name) &&
+            isIncluded(name, include) &&
+            passesSizeLimit(name, rootStat.size, maxFileSize)) {
+            yield name;
+        }
+        return;
+    }
+    yield* walkDir(root, "", { include, exclude, maxFileSize, ignores });
+}
+/**
+ * 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.
+ */
+function passesSizeLimit(rel, size, maxFileSize) {
+    if (isManifestPath(rel))
+        return true;
+    return size <= maxFileSize;
+}
+/** True if the path's basename is a dependency manifest we always read. */
+function isManifestPath(rel) {
+    const base = rel.split("/").pop() ?? rel;
+    return base === "package.json" || base === "package-lock.json";
+}
+/** Internal recursive directory walker. `relDir` is POSIX-relative to the root. */
+async function* walkDir(absDir, relDir, ctx) {
+    let entries;
+    try {
+        entries = await readdir(absDir, { withFileTypes: true });
+    }
+    catch {
+        // Unreadable directory (permissions, transient races) — skip silently.
+        return;
+    }
+    // Stable, deterministic ordering for reproducible scans.
+    entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    for (const entry of entries) {
+        const rel = relDir ? `${relDir}/${entry.name}` : entry.name;
+        const abs = path.join(absDir, entry.name);
+        if (entry.isSymbolicLink()) {
+            // Don't follow symlinks: avoids cycles and escaping the root.
+            continue;
+        }
+        if (entry.isDirectory()) {
+            if (ctx.ignores.includes(entry.name))
+                continue;
+            if (isExcluded(rel, ctx.exclude))
+                continue;
+            yield* walkDir(abs, rel, ctx);
+            continue;
+        }
+        if (!entry.isFile())
+            continue;
+        if (isExcluded(rel, ctx.exclude))
+            continue;
+        if (!isIncluded(rel, ctx.include))
+            continue;
+        if (isBinaryPath(rel))
+            continue;
+        if (isGeneratedPath(rel))
+            continue;
+        try {
+            const s = await stat(abs);
+            if (!passesSizeLimit(rel, s.size, ctx.maxFileSize))
+                continue;
+        }
+        catch {
+            continue;
+        }
+        yield rel;
+    }
+}
+//# sourceMappingURL=walk.js.map

package/dist/walk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"walk.js","sourceRoot":"","sources":["../src/walk.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@quantakrypto/core",
+  "version": "0.1.0",
+  "description": "Shared post-quantum readiness library: crypto detectors, vulnerable-dependency database, inventory + SARIF reporting. Zero runtime dependencies.",
+  "license": "Apache-2.0",
+  "author": "Dandelion Labs <hello@dandelionlabs.io> (https://dandelionlabs.io)",
+  "homepage": "https://github.com/dandelionlabs-io/qproof-tools/tree/main/packages/core#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dandelionlabs-io/qproof-tools.git",
+    "directory": "packages/core"
+  },
+  "bugs": {
+    "url": "https://github.com/dandelionlabs-io/qproof-tools/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "test": "node --import tsx --test test/*.test.ts"
+  }
+}

package/src/baseline.ts

@@ -0,0 +1,111 @@
+/**
+ * Canonical baseline module — the single source of truth for suppressing known
+ * findings across qScan and the GitHub Action (replacing their two divergent,
+ * mutually-unintelligible schemes).
+ *
+ * A baseline is a versioned set of finding fingerprints. A fingerprint is
+ * **line-insensitive** (so unrelated edits that shift line numbers don't
+ * invalidate it) and snippet-whitespace-normalized (so reformatting doesn't
+ * either). Identity = `sha256(ruleId | file | normalizedSnippet)`.
+ */
+import { createHash } from "node:crypto";
+import { readFile, writeFile } from "node:fs/promises";
+
+import type { Finding } from "./types.js";
+
+/** Current on-disk baseline schema version. */
+export const BASELINE_VERSION = 1 as const;
+
+/** The on-disk baseline shape: a version tag and a set of fingerprints. */
+export interface Baseline {
+  version: number;
+  fingerprints: string[];
+}
+
+/** Collapse all whitespace runs to single spaces and trim (snippet stability). */
+function normalizeSnippet(snippet: string | undefined): string {
+  if (!snippet) return "";
+  return snippet.replace(/\s+/g, " ").trim();
+}
+
+/**
+ * Stable, line-INSENSITIVE fingerprint of a finding: the hex SHA-256 of
+ * `ruleId|file|normalizedSnippet`. The line number is deliberately excluded so
+ * the fingerprint survives line shifts; the snippet's whitespace is normalized
+ * so it survives reformatting.
+ */
+export function fingerprintFinding(f: Finding): string {
+  const snippet = normalizeSnippet(f.location.snippet);
+  const input = `${f.ruleId}|${f.location.file}|${snippet}`;
+  return createHash("sha256").update(input, "utf8").digest("hex");
+}
+
+/** Build a {@link Baseline} from a set of findings (deduped, sorted). */
+export function baselineFromFindings(findings: readonly Finding[]): Baseline {
+  const set = new Set<string>();
+  for (const f of findings) set.add(fingerprintFinding(f));
+  return {
+    version: BASELINE_VERSION,
+    fingerprints: [...set].sort(),
+  };
+}
+
+/**
+ * Split findings into those NOT in the baseline (`newFindings`) and those that
+ * ARE (`suppressed`). Order within each group is preserved from the input.
+ */
+export function applyBaseline(
+  findings: readonly Finding[],
+  baseline: Baseline,
+): { newFindings: Finding[]; suppressed: Finding[] } {
+  const accepted = new Set(baseline.fingerprints);
+  const newFindings: Finding[] = [];
+  const suppressed: Finding[] = [];
+  for (const f of findings) {
+    if (accepted.has(fingerprintFinding(f))) suppressed.push(f);
+    else newFindings.push(f);
+  }
+  return { newFindings, suppressed };
+}
+
+/** Normalize an arbitrary parsed object into a valid {@link Baseline}. */
+function coerceBaseline(value: unknown): Baseline {
+  if (value === null || typeof value !== "object") {
+    return { version: BASELINE_VERSION, fingerprints: [] };
+  }
+  const obj = value as Record<string, unknown>;
+  const version = typeof obj.version === "number" ? obj.version : BASELINE_VERSION;
+  const fingerprints = Array.isArray(obj.fingerprints)
+    ? obj.fingerprints.filter((x): x is string => typeof x === "string")
+    : [];
+  return { version, fingerprints };
+}
+
+/**
+ * Load a baseline from disk. Returns an empty baseline (rather than throwing)
+ * when the file is missing or unparseable, so callers can treat "no baseline"
+ * and "absent baseline" uniformly.
+ */
+export async function loadBaseline(path: string): Promise<Baseline> {
+  let text: string;
+  try {
+    text = await readFile(path, "utf8");
+  } catch {
+    return { version: BASELINE_VERSION, fingerprints: [] };
+  }
+  try {
+    return coerceBaseline(JSON.parse(text));
+  } catch {
+    return { version: BASELINE_VERSION, fingerprints: [] };
+  }
+}
+
+/**
+ * Write a baseline derived from the given findings to disk as pretty JSON
+ * (trailing newline). Returns the baseline that was written.
+ */
+export async function saveBaseline(path: string, findings: readonly Finding[]): Promise<Baseline> {
+  const baseline = baselineFromFindings(findings);
+  await writeFile(path, `${JSON.stringify(baseline, null, 2)}\n`, "utf8");
+  return baseline;
+}

package/src/cbom.ts

@@ -0,0 +1,166 @@
+/**
+ * CBOM (Cryptographic Bill of Materials) export — CycloneDX 1.6 with
+ * `cryptographic-asset` components. Turns a {@link ScanResult} into a
+ * machine-readable inventory of the classical cryptographic assets discovered,
+ * for compliance / supply-chain tooling.
+ *
+ * Reference: CycloneDX 1.6 cryptography properties
+ * (https://cyclonedx.org/capabilities/cbom/). We emit one
+ * `cryptographic-asset` component per distinct (algorithm, primitive) pair
+ * observed, with occurrence evidence pointing back at the findings.
+ */
+import { createHash } from "node:crypto";
+
+import type { AlgorithmFamily, Finding, FindingCategory, ScanResult } from "./types.js";
+import { VERSION } from "./version.js";
+
+/** A CycloneDX 1.6 cryptographic bill of materials (kept permissive). */
+export interface CycloneDxBom {
+  bomFormat: "CycloneDX";
+  specVersion: "1.6";
+  serialNumber: string;
+  version: number;
+  metadata: Record<string, unknown>;
+  components: CbomComponent[];
+}
+
+/** A single CycloneDX `cryptographic-asset` component. */
+export interface CbomComponent {
+  type: "cryptographic-asset";
+  "bom-ref": string;
+  name: string;
+  cryptoProperties: Record<string, unknown>;
+  evidence?: Record<string, unknown>;
+}
+
+/** CycloneDX cryptographic primitive for a finding category. */
+function primitiveFor(category: FindingCategory): string {
+  switch (category) {
+    case "kem":
+      return "kem";
+    case "key-exchange":
+      return "key-agree";
+    case "signature":
+      return "signature";
+    case "certificate":
+      return "pki";
+    case "tls":
+      return "other";
+    default:
+      return "other";
+  }
+}
+
+/** True when the algorithm family is broken by Shor's algorithm (quantum). */
+function isQuantumVulnerable(algorithm: AlgorithmFamily): boolean {
+  return algorithm !== "unknown";
+}
+
+/** Deterministic bom-ref for a (algorithm, primitive) asset key. */
+function bomRef(key: string): string {
+  return `crypto:${createHash("sha256").update(key, "utf8").digest("hex").slice(0, 16)}`;
+}
+
+/**
+ * Build a CycloneDX 1.6 CBOM from a scan result. One component per distinct
+ * (algorithm + primitive) pair, with occurrence evidence (file:line) per
+ * finding. Output is deterministic (components and occurrences are sorted).
+ */
+export function toCbom(result: ScanResult): CycloneDxBom {
+  // Group findings by (algorithm | primitive).
+  const groups = new Map<
+    string,
+    { algorithm: AlgorithmFamily; primitive: string; findings: Finding[] }
+  >();
+
+  for (const f of result.findings) {
+    const algorithm: AlgorithmFamily = f.algorithm ?? "unknown";
+    const primitive = primitiveFor(f.category);
+    const key = `${algorithm}|${primitive}`;
+    let g = groups.get(key);
+    if (!g) {
+      g = { algorithm, primitive, findings: [] };
+      groups.set(key, g);
+    }
+    g.findings.push(f);
+  }
+
+  const components: CbomComponent[] = [...groups.entries()]
+    .sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0))
+    .map(([key, g]) => {
+      const occurrences = g.findings
+        .map((f) => ({
+          location: `${f.location.file}:${f.location.line}`,
+          ...(f.cwe ? { additionalContext: f.cwe } : {}),
+        }))
+        .sort((a, b) => (a.location < b.location ? -1 : a.location > b.location ? 1 : 0));
+
+      const anyHndl = g.findings.some((f) => f.hndl);
+
+      return {
+        type: "cryptographic-asset" as const,
+        "bom-ref": bomRef(key),
+        name: `${g.algorithm} (${g.primitive})`,
+        cryptoProperties: {
+          assetType: "algorithm",
+          algorithmProperties: {
+            primitive: g.primitive,
+            parameterSetIdentifier: g.algorithm,
+            executionEnvironment: "software-plain-ram",
+            classicalSecurityLevel: 0,
+            nistQuantumSecurityLevel: 0,
+            cryptoFunctions:
+              g.primitive === "signature"
+                ? ["sign", "verify"]
+                : g.primitive === "kem"
+                  ? ["encapsulate", "decapsulate"]
+                  : g.primitive === "key-agree"
+                    ? ["keygen"]
+                    : ["other"],
+          },
+          quantumVulnerable: isQuantumVulnerable(g.algorithm),
+          harvestNowDecryptLater: anyHndl,
+        },
+        evidence: { occurrences },
+      };
+    });
+
+  const serial = `urn:uuid:${stableUuid(result)}`;
+
+  return {
+    bomFormat: "CycloneDX",
+    specVersion: "1.6",
+    serialNumber: serial,
+    version: 1,
+    metadata: {
+      timestamp: result.finishedAt,
+      tools: {
+        components: [
+          {
+            type: "application",
+            name: "qScan",
+            version: result.toolVersion || VERSION,
+          },
+        ],
+      },
+      component: {
+        type: "application",
+        "bom-ref": "root",
+        name: result.root,
+      },
+    },
+    components,
+  };
+}
+
+/**
+ * Derive a stable UUID-shaped serial from the scan result so re-exporting the
+ * same result yields the same serial number (deterministic output).
+ */
+function stableUuid(result: ScanResult): string {
+  const h = createHash("sha256")
+    .update(`${result.root}|${result.toolVersion}|${result.findings.length}`, "utf8")
+    .digest("hex");
+  // Shape as a v4-ish UUID (variant/version nibbles forced).
+  return `${h.slice(0, 8)}-${h.slice(8, 12)}-4${h.slice(13, 16)}-8${h.slice(17, 20)}-${h.slice(20, 32)}`;
+}

package/src/changed.ts

@@ -0,0 +1,76 @@
+/**
+ * Incremental-scan helper: list the files that changed in a git working tree,
+ * for feeding into {@link ScanOptions.files}. Tolerant of non-git directories —
+ * returns an empty list rather than throwing.
+ */
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+/** Run a git command in `cwd`, returning stdout or `null` on any failure. */
+async function git(cwd: string, args: string[]): Promise<string | null> {
+  try {
+    const { stdout } = await execFileAsync("git", args, {
+      cwd,
+      maxBuffer: 64 * 1024 * 1024,
+      windowsHide: true,
+    });
+    return stdout;
+  } catch {
+    return null;
+  }
+}
+
+/** Split git output into trimmed, non-empty, POSIX-relative path lines. */
+function toLines(stdout: string | null): string[] {
+  if (!stdout) return [];
+  return stdout
+    .split("\n")
+    .map((l) => l.trim())
+    .filter((l) => l.length > 0);
+}
+
+/**
+ * Return the list of changed files (relative POSIX paths) under `root`.
+ *
+ * - With `since` (a ref / range), returns `git diff --name-only --diff-filter=ACMR <since>`
+ *   plus currently-modified-but-uncommitted files, deduped.
+ * - Without `since`, returns uncommitted changes (`git diff` working+staged) plus
+ *   untracked files (`git ls-files --others --exclude-standard`).
+ * - When `root` is not a git repository (or git is unavailable), returns `[]`.
+ *
+ * Deleted files are excluded (ACMR filter / existence is the caller's concern).
+ */
+export async function changedFiles(root: string, since?: string): Promise<string[]> {
+  // Confirm this is a git work tree first; bail out tolerantly if not.
+  const inside = await git(root, ["rev-parse", "--is-inside-work-tree"]);
+  if (inside === null || inside.trim() !== "true") return [];
+
+  const out = new Set<string>();
+
+  if (since) {
+    for (const f of toLines(
+      await git(root, ["diff", "--name-only", "--diff-filter=ACMR", since]),
+    )) {
+      out.add(f);
+    }
+  }
+
+  // Always include local uncommitted edits (staged + unstaged), filtered to ACMR.
+  for (const f of toLines(await git(root, ["diff", "--name-only", "--diff-filter=ACMR"]))) {
+    out.add(f);
+  }
+  for (const f of toLines(
+    await git(root, ["diff", "--name-only", "--diff-filter=ACMR", "--cached"]),
+  )) {
+    out.add(f);
+  }
+
+  // Untracked (but not ignored) files.
+  for (const f of toLines(await git(root, ["ls-files", "--others", "--exclude-standard"]))) {
+    out.add(f);
+  }
+
+  return [...out].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+}