@quantakrypto/core 0.1.0

package/dist/scan.js

@@ -0,0 +1,168 @@
+/**
+ * Scan orchestrator. Walks the target (or an explicit file list), runs the
+ * applicable detectors over each file, parses dependency manifests, aggregates
+ * everything into an inventory, and returns a {@link ScanResult} with timing and
+ * the tool version.
+ *
+ * Detector scope (source vs config) is driven by each {@link Detector}'s
+ * declared `scope` (defaulting to "source"), not by ruleId prefixes. The
+ * detector set comes from {@link defaultRegistry} unless overridden via
+ * `options.detectors`.
+ */
+import { readFile, stat } from "node:fs/promises";
+import * as path from "node:path";
+import { walkFiles, toPosix, isBinaryPath, looksMinified } from "./walk.js";
+import { sourceDetectors } from "./detectors/source.js";
+import { pemDetector } from "./detectors/pem.js";
+import { defaultRegistry, detectorScope } from "./registry.js";
+import { isManifestFile, scanManifest } from "./dependencies.js";
+import { buildInventory } from "./inventory.js";
+import { VERSION } from "./version.js";
+/**
+ * The full set of built-in detectors exposed on the public API. The PEM
+ * detector applies to every text file; the source detectors apply only to
+ * JS/TS. The manifest scanner is handled separately (it parses JSON rather than
+ * running a Detector).
+ */
+export const detectors = [...sourceDetectors, pemDetector];
+/** Stable comparator: by file, then line, then ruleId. Exported for reuse. */
+export function compareFindings(a, b) {
+    if (a.location.file !== b.location.file)
+        return a.location.file < b.location.file ? -1 : 1;
+    if (a.location.line !== b.location.line)
+        return a.location.line - b.location.line;
+    return a.ruleId < b.ruleId ? -1 : a.ruleId > b.ruleId ? 1 : 0;
+}
+/** Resolve the active detector list for a scan (override or the default registry). */
+function resolveDetectors(options) {
+    return options.detectors ?? defaultRegistry.all();
+}
+/**
+ * Run all applicable detectors + the manifest scanner over a single file's
+ * contents, honouring the source / config / dependencies toggles. Pure: no I/O.
+ * Exported so the parallel worker and unit tests can drive it directly.
+ */
+export function detectFile(file, content, dets, toggles) {
+    const out = [];
+    for (const det of dets) {
+        if (!det.appliesTo(file))
+            continue;
+        const isConfig = detectorScope(det) === "config";
+        if (isConfig ? !toggles.config : !toggles.source)
+            continue;
+        out.push(...det.detect({ file, content }));
+    }
+    if (toggles.deps && isManifestFile(file)) {
+        out.push(...scanManifest(file, content));
+    }
+    return out;
+}
+/**
+ * Recursively scan a directory (or single file, or explicit file list) for
+ * classical asymmetric crypto. Honours the source / dependencies / config
+ * toggles (all default true) and reports progress through `options.onFile`.
+ */
+export async function scan(options) {
+    const startedAt = new Date();
+    const doSource = options.source !== false;
+    const doDeps = options.dependencies !== false;
+    const doConfig = options.config !== false;
+    const scanMinified = options.scanMinified === true;
+    const dets = resolveDetectors(options);
+    // Resolve whether the root is a file so we can rebuild absolute paths to read.
+    const rootStat = await stat(options.root);
+    const rootIsFile = rootStat.isFile();
+    const baseDir = rootIsFile ? path.dirname(options.root) : options.root;
+    const singleFileName = rootIsFile ? path.basename(options.root) : null;
+    const findings = [];
+    let filesScanned = 0;
+    // Source of relative paths: an explicit file list (incremental) or the walker.
+    const relPaths = options.files
+        ? filterExplicitFiles(options.files, options)
+        : walkFiles(options.root, {
+            include: options.include,
+            exclude: options.exclude,
+            noDefaultIgnores: options.noDefaultIgnores,
+            maxFileSize: options.maxFileSize,
+        });
+    for await (const rel of relPaths) {
+        // In single-file mode, walkFiles yields the basename; map back to the file.
+        const absPath = singleFileName ? options.root : path.join(baseDir, ...rel.split("/"));
+        const reportedPath = singleFileName ? toPosix(rel) : rel;
+        options.onFile?.(reportedPath);
+        let content;
+        try {
+            content = await readFile(absPath, "utf8");
+        }
+        catch {
+            continue; // unreadable / vanished file — skip.
+        }
+        // Skip machine-minified / generated content (unless explicitly enabled).
+        // Manifests are always scanned (their findings are dependency findings).
+        if (!scanMinified && !isManifestFile(reportedPath) && looksMinified(content)) {
+            continue;
+        }
+        filesScanned += 1;
+        findings.push(...detectFile(reportedPath, content, dets, {
+            source: doSource,
+            config: doConfig,
+            deps: doDeps,
+        }));
+    }
+    // Stable ordering: by file, then line, then ruleId.
+    findings.sort(compareFindings);
+    const inventory = buildInventory(findings);
+    const finishedAt = new Date();
+    return {
+        root: options.root,
+        findings,
+        filesScanned,
+        inventory,
+        startedAt: startedAt.toISOString(),
+        finishedAt: finishedAt.toISOString(),
+        toolVersion: VERSION,
+    };
+}
+/**
+ * Filter an explicit relative file list down to the paths that pass the binary
+ * filter and the include/exclude patterns, yielding them in sorted order for
+ * deterministic output. Size limits are enforced later (we still read manifests
+ * over the cap). Non-existent files are simply skipped at read time.
+ */
+async function* filterExplicitFiles(files, options) {
+    const include = options.include ?? [];
+    const exclude = options.exclude ?? [];
+    const seen = new Set();
+    const list = [...files]
+        .map((f) => toPosix(f))
+        .filter((f) => {
+        if (seen.has(f))
+            return false;
+        seen.add(f);
+        return true;
+    })
+        .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+    for (const rel of list) {
+        if (isBinaryPath(rel))
+            continue;
+        if (include.length > 0 && !matchesAny(rel, include))
+            continue;
+        if (matchesAny(rel, exclude))
+            continue;
+        yield rel;
+    }
+}
+/** Local substring/prefix matcher (mirrors the walker's pattern semantics). */
+function matchesAny(rel, patterns) {
+    for (const pattern of patterns) {
+        if (!pattern)
+            continue;
+        const p = toPosix(pattern).replace(/\/+$/, "");
+        if (rel.includes(p))
+            return true;
+        if (rel === p || rel.startsWith(`${p}/`))
+            return true;
+    }
+    return false;
+}
+//# sourceMappingURL=scan.js.map

package/dist/scan.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,190 @@
+/**
+ * @quantakrypto/core — shared types (the locked public contract).
+ *
+ * These types are the stable interface between every tool in the monorepo
+ * (qScan, the MCP server, the GitHub Action). Treat additions as backwards
+ * compatible; treat renames/removals as breaking.
+ */
+/** How serious a finding is, ordered most → least severe. */
+export type Severity = "critical" | "high" | "medium" | "low" | "info";
+/** How sure the detector is that the finding is a real use of the algorithm. */
+export type Confidence = "high" | "medium" | "low";
+/** What kind of cryptographic concern a finding represents. */
+export type FindingCategory = "kem" | "key-exchange" | "signature" | "tls" | "certificate" | "dependency" | "hash" | "rng";
+/** Classical asymmetric algorithm families that are not quantum-safe. */
+export type AlgorithmFamily = "RSA" | "ECDH" | "ECDSA" | "EdDSA" | "DH" | "DSA" | "X25519" | "X448" | "ECIES" | "unknown";
+/** A precise location inside a scanned file. */
+export interface SourceLocation {
+    /** Path relative to the scan root, using POSIX separators. */
+    file: string;
+    /** 1-based line number. */
+    line: number;
+    /** 1-based column number, if known. */
+    column?: number;
+    /** 1-based end line, for multi-line matches. */
+    endLine?: number;
+    /** The matched source text (trimmed, single line). */
+    snippet?: string;
+}
+/** A single detected concern. */
+export interface Finding {
+    /** Stable rule identifier, e.g. "rsa-keygen", "ecdh-usage", "tls-legacy-version", "dep-vulnerable". */
+    ruleId: string;
+    title: string;
+    category: FindingCategory;
+    severity: Severity;
+    confidence: Confidence;
+    /** The classical algorithm involved, when applicable. */
+    algorithm?: AlgorithmFamily;
+    /** True when this is exposed to "harvest now, decrypt later". */
+    hndl: boolean;
+    /** One-line human explanation of the concern. */
+    message: string;
+    /** Suggested post-quantum remediation (e.g. ML-KEM, hybrid X25519MLKEM768). */
+    remediation?: string;
+    /** Associated CWE identifier, e.g. "CWE-327" (broken crypto), "CWE-326" (weak strength). */
+    cwe?: string;
+    location: SourceLocation;
+}
+/** A known quantum-vulnerable dependency entry. */
+export interface VulnerableDependency {
+    /** Package name. */
+    name: string;
+    ecosystem: "npm";
+    /** Why it's flagged (what classical crypto it provides). */
+    reason: string;
+    /** Algorithm families the package primarily exposes. */
+    algorithms: AlgorithmFamily[];
+    severity: Severity;
+}
+/**
+ * Which logical scope a detector belongs to. Drives the source/config scope
+ * toggles in {@link ScanOptions} (replacing the old ruleId-prefix inference).
+ */
+export type DetectorScope = "source" | "config";
+/**
+ * The programming language / surface a detector targets. `"any"` means the
+ * detector is language-agnostic (e.g. PEM material, config files).
+ */
+export type DetectorLanguage = "js" | "python" | "go" | "java" | "any";
+/** A pluggable source detector. Detectors are pure and stateless. */
+export interface Detector {
+    /** Unique id, used as the Finding.ruleId prefix space. */
+    id: string;
+    /** Human description of what the detector looks for. */
+    description: string;
+    /**
+     * Logical scope of this detector's findings. Used by `scan()` to honour the
+     * `config` / `source` toggles. Defaults to `"source"` when omitted (for
+     * backward compatibility with externally-defined detectors).
+     */
+    scope?: DetectorScope;
+    /**
+     * Language this detector targets, for documentation / registry filtering.
+     * Defaults to `"js"` when omitted.
+     */
+    language?: DetectorLanguage;
+    /** Whether this detector should run against the given file path. */
+    appliesTo(filePath: string): boolean;
+    /** Inspect a single file's contents and return zero or more findings. */
+    detect(input: DetectorInput): Finding[];
+}
+export interface DetectorInput {
+    /** Path relative to the scan root (POSIX). */
+    file: string;
+    /** Full file contents. */
+    content: string;
+}
+/** Options controlling a scan. */
+export interface ScanOptions {
+    /** Absolute or relative directory (or single file) to scan. */
+    root: string;
+    /**
+     * Restrict the walk to paths matching one of these include patterns
+     * (substring or relative-path-prefix match). When omitted, all non-excluded
+     * files are scanned. Wired into the walker.
+     */
+    include?: string[];
+    /** Extra exclude patterns (in addition to the built-in defaults). */
+    exclude?: string[];
+    /** Disable the built-in ignore list (node_modules, .git, dist, …). */
+    noDefaultIgnores?: boolean;
+    /** Scan source files for inline crypto usage. Default: true. */
+    source?: boolean;
+    /** Scan dependency manifests/lockfiles for vulnerable libraries. Default: true. */
+    dependencies?: boolean;
+    /** Scan config files (TLS, certificates). Default: true. */
+    config?: boolean;
+    /** Max file size to read, in bytes. Default: 2 MiB. */
+    maxFileSize?: number;
+    /**
+     * Scan minified / generated / bundled files (large single-line content)
+     * instead of skipping them. Default: false (skip them for speed).
+     */
+    scanMinified?: boolean;
+    /**
+     * Explicit relative file list (POSIX, relative to `root`) to scan instead of
+     * walking the tree. Used for incremental / changed-files scans. Each path is
+     * still subject to the binary / size filters. When set, the directory walk is
+     * bypassed entirely.
+     */
+    files?: string[];
+    /**
+     * Override / extend the built-in detector set. When omitted, the default
+     * registry's detectors are used.
+     */
+    detectors?: Detector[];
+    /** Optional progress callback. */
+    onFile?: (file: string) => void;
+}
+/** Extra options for {@link scanParallel}, layered onto {@link ScanOptions}. */
+export interface ParallelScanOptions extends ScanOptions {
+    /**
+     * Number of worker threads. Default: `os.availableParallelism()`. A value of
+     * 0 or 1 forces the in-process serial path.
+     */
+    concurrency?: number;
+    /**
+     * Combined-size floor (bytes) below which the scan always runs in-process.
+     * Default: 2 MiB. Also stays serial below `parallelFileThreshold` files.
+     */
+    parallelThresholdBytes?: number;
+    /** File-count floor below which the scan always runs in-process. Default: 200. */
+    parallelFileThreshold?: number;
+    /** Target bytes per worker chunk. Default: 4 MiB. */
+    chunkBytes?: number;
+}
+/** Aggregated counts produced from a scan's findings. */
+export interface CryptoInventory {
+    byAlgorithm: Partial<Record<AlgorithmFamily, number>>;
+    byCategory: Partial<Record<FindingCategory, number>>;
+    bySeverity: Record<Severity, number>;
+    /** Number of findings exposed to harvest-now-decrypt-later. */
+    hndlCount: number;
+    /** 0–100 readiness score (100 = no classical asymmetric crypto found). */
+    readinessScore: number;
+}
+/** The full result of a scan. */
+export interface ScanResult {
+    /** The scan root (as provided). */
+    root: string;
+    findings: Finding[];
+    filesScanned: number;
+    inventory: CryptoInventory;
+    /** ISO timestamps. */
+    startedAt: string;
+    finishedAt: string;
+    /** Tool version that produced the result. */
+    toolVersion: string;
+}
+/** Output formats qScan / reporters can emit. */
+export type ReportFormat = "human" | "json" | "sarif";
+/** A remediation recommendation for a classical algorithm. */
+export interface Remediation {
+    algorithm: AlgorithmFamily;
+    /** Short recommended replacement, e.g. "ML-KEM-768 (hybrid X25519MLKEM768)". */
+    recommendation: string;
+    /** Longer rationale. */
+    detail: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,9 @@
+/**
+ * @quantakrypto/core — shared types (the locked public contract).
+ *
+ * These types are the stable interface between every tool in the monorepo
+ * (qScan, the MCP server, the GitHub Action). Treat additions as backwards
+ * compatible; treat renames/removals as breaking.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/dist/version.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The tool version surfaced in reports. Kept in its own module so reporters and
+ * the scan orchestrator can import it without creating a cycle through index.ts.
+ * Keep in sync with packages/core/package.json.
+ */
+export declare const VERSION = "0.1.0";
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,eAAO,MAAM,OAAO,UAAU,CAAC"}

package/dist/version.js

@@ -0,0 +1,7 @@
+/**
+ * The tool version surfaced in reports. Kept in its own module so reporters and
+ * 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.1.0";
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC"}

package/dist/walk.d.ts

@@ -0,0 +1,37 @@
+/** Directories ignored by default (can be disabled with noDefaultIgnores). */
+export declare const DEFAULT_IGNORES: readonly string[];
+/** Default maximum file size to read: 2 MiB. */
+export declare const DEFAULT_MAX_FILE_SIZE: number;
+/** Options accepted by {@link walkFiles}. */
+export interface WalkOptions {
+    /**
+     * Restrict to paths matching one of these include patterns (substring or
+     * relative-path-prefix match). When omitted/empty, all files pass.
+     */
+    include?: string[];
+    /** Extra exclude patterns (substring or relative-path-prefix match). */
+    exclude?: string[];
+    /** Disable the built-in directory ignore list. */
+    noDefaultIgnores?: boolean;
+    /** Max file size in bytes; larger files are skipped. */
+    maxFileSize?: number;
+}
+/** Normalise a path to forward-slash POSIX separators. */
+export declare function toPosix(p: string): string;
+/** True if the file's extension marks it as binary / non-text. */
+export declare function isBinaryPath(rel: string): boolean;
+/** True if the path looks like generated / bundled output (by name). */
+export declare function isGeneratedPath(rel: string): boolean;
+/**
+ * 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 declare function looksMinified(content: string): boolean;
+/**
+ * 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 declare function walkFiles(root: string, options?: WalkOptions): AsyncGenerator<string>;
+//# sourceMappingURL=walk.d.ts.map

package/dist/walk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"walk.d.ts","sourceRoot":"","sources":["../src/walk.ts"],"names":[],"mappings":"AAUA,8EAA8E;AAC9E,eAAO,MAAM,eAAe,EAAE,SAAS,MAAM,EAW5C,CAAC;AAEF,gDAAgD;AAChD,eAAO,MAAM,qBAAqB,QAAkB,CAAC;AAyErD,6CAA6C;AAC7C,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,wEAAwE;IACxE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,kDAAkD;IAClD,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,wDAAwD;IACxD,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,0DAA0D;AAC1D,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAEzC;AA6BD,kEAAkE;AAClE,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAMjD;AASD,wEAAwE;AACxE,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAmBtD;AAED;;;;GAIG;AACH,wBAAuB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,cAAc,CAAC,MAAM,CAAC,CAsBhG"}