@quantakrypto/core 0.1.0

package/README.md

@@ -0,0 +1,337 @@
+# @quantakrypto/core
+
+Shared post-quantum readiness library for the quantakrypto toolchain. It finds
+**classical, non-quantum-safe asymmetric cryptography** in a codebase — inline
+crypto calls, embedded keys/certificates, and quantum-vulnerable npm
+dependencies — and turns the results into an inventory, a readiness score, and
+machine- or human-readable reports.
+
+- **Zero runtime dependencies.** Node built-ins only.
+- **ESM + NodeNext**, TypeScript strict, Node ≥ 20.
+- Powers `@quantakrypto/qscan` (CLI), the MCP server, and the GitHub Action.
+
+## Why it exists
+
+Shor's algorithm breaks RSA, (EC)DH, ECDSA, DSA and EdDSA. Two threats follow:
+
+- **Harvest now, decrypt later (HNDL).** Traffic protected by classical key
+  exchange / public-key encryption (ECDH, DH, RSA-OAEP) can be recorded today
+  and decrypted once a cryptographically relevant quantum computer exists.
+  Findings carry an `hndl: true` flag.
+- **Forgery.** Classical signatures (RSA-PSS, ECDSA, EdDSA, DSA, JWT `RS*/PS*/ES*/EdDSA`)
+  can be forged by a quantum attacker. These are `hndl: false` but still high
+  severity.
+
+`@quantakrypto/core` flags both, and points each finding at a NIST PQC replacement
+(ML-KEM / FIPS 203, ML-DSA / FIPS 204, SLH-DSA / FIPS 205, hybrid
+`X25519MLKEM768`).
+
+## Install
+
+```bash
+npm install @quantakrypto/core
+```
+
+## Quick start
+
+```ts
+import { scan, formatSummary, toSarif, toJson } from "@quantakrypto/core";
+
+const result = await scan({ root: "./", onFile: (f) => process.stderr.write(`scanning ${f}\n`) });
+
+console.log(formatSummary(result, { color: true })); // human report
+const sarif = toSarif(result);                        // SARIF 2.1.0 for CI
+const json = toJson(result);                          // structured object
+```
+
+## API
+
+### `scan(options: ScanOptions): Promise<ScanResult>`
+
+Recursively scans a directory (or a single file) and returns findings, an
+inventory, file count, timing, and the tool version.
+
+```ts
+interface ScanOptions {
+  root: string;                 // directory or single file
+  include?: string[];           // restrict the walk to matching paths (substring/prefix)
+  exclude?: string[];           // extra exclude patterns (substring/prefix)
+  noDefaultIgnores?: boolean;   // disable node_modules/.git/dist/… ignores
+  source?: boolean;             // scan source files (default true)
+  dependencies?: boolean;       // scan package.json / package-lock.json (default true)
+  config?: boolean;             // scan PEM/TLS/cert config (default true)
+  maxFileSize?: number;         // bytes; default 2 MiB (manifests are exempt)
+  scanMinified?: boolean;       // scan minified/generated files (default false: skip them)
+  files?: string[];             // explicit relative file list (incremental scans)
+  detectors?: Detector[];       // override/extend the built-in detector set
+  onFile?: (file: string) => void; // progress callback (relative POSIX path)
+}
+```
+
+- **`include`** is now wired into the walker: when set, only paths matching one
+  of the patterns are scanned.
+- **`files`** bypasses the directory walk entirely and scans the given relative
+  paths (used for incremental / changed-files scans — pair it with
+  `changedFiles`). Binary and missing files are skipped; manifests over the size
+  cap are still read.
+- **`scanMinified`** is off by default; machine-minified / generated / bundled
+  content (`*.bundle.js`, `*.generated.ts`, long single-line files, …) is
+  skipped for speed unless you opt in.
+
+### `scanParallel(options): Promise<ScanResult>`
+
+A worker-thread pool over the file list with a **deterministic** result merge
+(byte-identical to `scan`). Falls back automatically to the in-process `scan`
+for small workloads (below ~200 files / ~2 MiB) and whenever `worker_threads`
+is unavailable. Extra options:
+
+```ts
+interface ParallelScanOptions extends ScanOptions {
+  concurrency?: number;            // worker count; default os.availableParallelism()
+  parallelThresholdBytes?: number; // serial below this total size (default 2 MiB)
+  parallelFileThreshold?: number;  // serial below this file count (default 200)
+  chunkBytes?: number;             // target bytes per worker chunk (default 4 MiB)
+}
+```
+
+### `changedFiles(root, since?): Promise<string[]>`
+
+Returns relative POSIX paths that changed in a git work tree (uncommitted +
+untracked, plus a `since` ref/range when provided). Tolerant of non-git
+directories — returns `[]`. Feed the result into `ScanOptions.files` for
+incremental scans.
+
+```ts
+const files = await changedFiles(".", "origin/main...HEAD");
+const result = await scan({ root: ".", files });
+```
+
+### `walkFiles(root, options?): AsyncGenerator<string>`
+
+Recursive async generator yielding scannable text files as **relative POSIX
+paths**. Skips default-ignored directories (`node_modules`, `.git`, `dist`,
+`build`, `.next`, `out`, `coverage`, `vendor`, `.turbo`, `.cache`), honours
+`exclude` patterns (substring or path-prefix), skips obvious binaries by
+extension, and skips files larger than `maxFileSize` (default 2 MiB). `root`
+may be a single file.
+
+```ts
+for await (const file of walkFiles("./src", { exclude: ["legacy"] })) {
+  console.log(file); // e.g. "components/Button.tsx"
+}
+```
+
+### `detectors: Detector[]` / `defaultRegistry` / `DetectorRegistry`
+
+The built-in, pure detectors. Each declares a `scope` (`"source"` | `"config"`),
+a `language`, `appliesTo(filePath)`, and `detect({ file, content })`. `scan()`
+drives the source/config scope toggles from the detector's **declared `scope`**
+(not from ruleId prefixes). Detector families:
+
+| Detector | Scope | Catches |
+| --- | --- | --- |
+| `node-crypto` | source | `generateKeyPair(Sync)('rsa'\|'ec'\|'dsa'\|'dh'\|'x25519'\|'x448'\|'ed25519'\|'ed448')`, `createSign/createVerify`, one-shot `crypto.sign/verify`, `createDiffieHellman`, `getDiffieHellman('modpN')`, `createECDH`, `publicEncrypt/privateDecrypt`, `diffieHellman` |
+| `webcrypto` | source | `subtle.{generateKey,importKey,deriveKey,deriveBits,sign,verify,…}` with `RSA-OAEP`, `RSA-PSS`, `RSASSA-PKCS1-v1_5`, `ECDH`, `ECDSA` |
+| `crypto-libs` | source | `node-forge` (`pki.rsa.generateKeyPair`, `ed25519`), `elliptic` (`new EC(...)`), `jsrsasign`, `node-rsa`, direct `secp256k1.*` usage |
+| `jwt-jose` | source | JWT/JOSE alg strings (`RS/PS/ES*`, `EdDSA`) and `ECDH-ES*` key agreement (HNDL) |
+| `tls-config` | config | `minVersion/secureProtocol: 'TLSv1'/'TLSv1.1'`, `rejectUnauthorized: false`, weak ciphers (RC4/DES/3DES/MD5/NULL/EXPORT) |
+| `pem-material` | config | PEM keys/certs in any file: `RSA/EC/DSA/PKCS#8/OPENSSH/PGP PRIVATE KEY`, `PGP MESSAGE`, `CERTIFICATE` |
+| `ssh-cert` | config | SSH public keys (`ssh-rsa`, `ssh-ed25519`, `ecdsa-sha2-*`) and X.509 certificate signature algorithms (`sha256WithRSAEncryption`, `ecdsa-with-SHA256`, …) |
+
+`defaultRegistry` is a `DetectorRegistry` preloaded with these built-ins. The
+registry is the plugin point:
+
+```ts
+import { DetectorRegistry, defaultRegistry, scan } from "@quantakrypto/core";
+
+const registry = defaultRegistry.clone().register(myDetector);
+const result = await scan({ root: ".", detectors: registry.all() });
+```
+
+`DetectorRegistry` exposes `register(d)`, `get(id)`, `has(id)`, `all()` and
+`clone()`. Ids must be unique (duplicate registration throws).
+
+#### Adding a detector / language
+
+1. Create `src/detectors/<lang>.ts` exporting one or more `Detector`s. Set
+   `language` (`"js" | "python" | "go" | "java" | "any"`), `scope`
+   (`"source" | "config"`), an `appliesTo(path)` extension check, and a pure
+   `detect({ file, content })` returning `Finding[]` (use `makeFinding` from
+   `detect-utils` for consistent location/remediation/CWE handling).
+2. If the language uses new file extensions, ensure the walker treats them as
+   text (they are scanned unless listed as binary in `walk.ts`).
+3. For a new dependency ecosystem, extend `VulnerableDependency.ecosystem` and
+   add a manifest matcher in `dependencies.ts`.
+4. Register it: `defaultRegistry.register(myDetector)`, or pass
+   `{ detectors: [...] }` to `scan`. No edit to `scan()` is required — scope is
+   honoured from the detector's declared `scope`.
+
+### `vulnerableDependencies: VulnerableDependency[]`
+
+Curated database (~20 entries) of npm packages whose purpose is classical
+asymmetric crypto: `node-forge`, `elliptic`, `jsrsasign`, `node-rsa`, `ursa`,
+`sshpk`, `jsonwebtoken`, `jose`, `jws`, `eccrypto`, `secp256k1`, `tweetnacl`,
+`ed25519`, `@noble/curves`, `@noble/secp256k1`, `@noble/ed25519`, `paseto`,
+`bcrypto`, `ecpair`, `keypair`. `scan()` matches these against `package.json`
+and `package-lock.json` and emits `category: "dependency"` findings located at
+the manifest.
+
+### `buildInventory(findings: Finding[]): CryptoInventory`
+
+Aggregates findings into per-algorithm / per-category / per-severity counts, the
+HNDL count, and a `readinessScore` (0–100, 100 = no classical asymmetric crypto
+found). The score starts at 100 and subtracts severity-weighted penalties with
+diminishing returns per severity bucket, clamped to `[0, 100]`.
+
+### Reporters
+
+- `toSarif(result): SarifLog` — valid **SARIF 2.1.0** (`$schema`, `version`,
+  `runs[0].tool.driver { name: "qScan", informationUri, version, rules[] }`,
+  `results[]` with `ruleId`, `level` (error/warning/note), `message.text`,
+  `locations[].physicalLocation` with `artifactLocation.uri` and
+  `region.startLine/startColumn`).
+- `toJson(result): Record<string, unknown>` — clean, JSON-serialisable object.
+- `formatSummary(result, { color? }): string` — human report with the readiness
+  score, severity/algorithm breakdown, top findings, and an HNDL note. Colour is
+  off by default and uses raw ANSI codes when enabled.
+
+### `remediationFor(algorithm): Remediation | undefined` / `remediationForTier(algorithm, tier?)`
+
+`remediationFor` returns the recommended PQC replacement for a classical family.
+`remediationForTier` adds a **security tier**: `"category-3"` (default,
+commercial — ML-KEM-768 / ML-DSA-65) or `"category-5"` (CNSA 2.0 / long-lived —
+ML-KEM-1024 / ML-DSA-87).
+
+```ts
+remediationFor("ECDH");
+// { algorithm: "ECDH", recommendation: "hybrid X25519MLKEM768 (ML-KEM-768)", detail: … }
+
+remediationForTier("ECDH", "category-5");
+// recommendation mentions ML-KEM-1024; detail cites CNSA 2.0 (2030/2033 milestones)
+```
+
+`STATEFUL_HBS_NOTE` / `statefulHbsApplies(algorithm)` surface the SP 800-208
+stateful hash-based signatures (LMS / XMSS / HSS) guidance for firmware / boot
+signing (stateful — use only with rigorous state management).
+
+### Baseline (`fingerprintFinding`, `baselineFromFindings`, `applyBaseline`, `loadBaseline`, `saveBaseline`)
+
+The single canonical baseline scheme shared by qScan and the Action. A baseline
+is `{ version, fingerprints: string[] }`. A fingerprint is the SHA-256 hex of
+`ruleId|file|normalizedSnippet` — **line-insensitive** (survives line shifts)
+and snippet-whitespace-normalized (survives reformatting).
+
+```ts
+import { saveBaseline, loadBaseline, applyBaseline } from "@quantakrypto/core";
+
+await saveBaseline(".quantakrypto-baseline.json", result.findings);          // write
+const baseline = await loadBaseline(".quantakrypto-baseline.json");          // read (tolerant)
+const { newFindings, suppressed } = applyBaseline(result.findings, baseline);
+```
+
+### `toCbom(result): CycloneDxBom`
+
+A CycloneDX 1.6 **cryptographic bill of materials** (CBOM): one
+`cryptographic-asset` component per distinct (algorithm, primitive) pair, with
+occurrence evidence and `quantumVulnerable` / `harvestNowDecryptLater` flags.
+Deterministic output.
+
+### CWE tagging
+
+Every detector sets a `Finding.cwe` (`CWE-327` broken crypto, `CWE-326` weak
+strength, `CWE-295` cert validation, `CWE-798` hardcoded key). `toSarif` maps it
+into `rules[].properties`, result `taxa`, and a run-level CWE `taxonomies`
+component; `toJson` includes it. Constants are exported (`CWE_BROKEN_CRYPTO`, …).
+
+### `VERSION: string`
+
+Tool version surfaced in reports (kept in sync with `package.json`).
+
+## API reference
+
+| Export | Kind | Summary |
+| --- | --- | --- |
+| `scan` | fn | Scan a dir / file / explicit file list → `ScanResult` |
+| `scanParallel` | fn | Worker-pool scan with deterministic merge + serial fallback |
+| `changedFiles` | fn | Git-aware changed-files list for incremental scans |
+| `detectFile` | fn | Pure per-file detect (used by workers / tests) |
+| `compareFindings` | fn | Stable finding comparator (file → line → ruleId) |
+| `mergeChunkResults`, `chunkByBytes` | fn | Pure parallel merge / byte-chunking helpers |
+| `walkFiles`, `isBinaryPath`, `isGeneratedPath`, `looksMinified` | fn | Walker + file-classification helpers |
+| `detectors` | const | Built-in detector array (mirrors `defaultRegistry.all()`) |
+| `DetectorRegistry`, `defaultRegistry`, `detectorScope` | class/const/fn | Detector plugin point |
+| `buildInventory` | fn | Aggregate findings → `CryptoInventory` |
+| `vulnerableDependencies` | const | Curated quantum-vulnerable npm DB |
+| `toSarif`, `toJson`, `formatSummary` | fn | Reporters (SARIF 2.1.0 / JSON / human) |
+| `toCbom` | fn | CycloneDX 1.6 CBOM export |
+| `remediationFor`, `remediationForTier`, `TIER_PARAMS` | fn/const | PQC remediation (family + CNSA tier) |
+| `STATEFUL_HBS_NOTE`, `statefulHbsApplies` | const/fn | SP 800-208 LMS/XMSS guidance |
+| `fingerprintFinding`, `baselineFromFindings`, `applyBaseline`, `loadBaseline`, `saveBaseline`, `BASELINE_VERSION` | fn/const | Canonical baseline |
+| `CWE_BROKEN_CRYPTO`, `CWE_WEAK_STRENGTH`, `CWE_CERT_VALIDATION`, `CWE_HARDCODED_KEY`, `CWE_RISKY_PRIMITIVE` | const | CWE identifiers |
+| `VERSION` | const | Tool version |
+
+Types: `Finding` (now with optional `cwe`), `ScanOptions`/`ParallelScanOptions`,
+`ScanResult`, `Detector` (now with `scope`/`language`), `DetectorScope`,
+`DetectorLanguage`, `Baseline`, `CycloneDxBom`, `CbomComponent`, `SecurityTier`,
+`AlgorithmFamily` (now includes `X448`), and the rest of the locked contract in
+[`src/types.ts`](./src/types.ts).
+
+## Core types
+
+See [`src/types.ts`](./src/types.ts) for the locked contract. Highlights:
+
+```ts
+type Severity = "critical" | "high" | "medium" | "low" | "info";
+
+type AlgorithmFamily =
+  | "RSA" | "ECDH" | "ECDSA" | "EdDSA"
+  | "DH"  | "DSA"  | "X25519" | "X448" | "ECIES" | "unknown";
+
+type FindingCategory =
+  | "kem" | "key-exchange" | "signature"
+  | "tls" | "certificate"  | "dependency" | "hash" | "rng";
+
+interface Finding {
+  ruleId: string;
+  title: string;
+  category: FindingCategory;
+  severity: Severity;
+  confidence: "high" | "medium" | "low";
+  algorithm?: AlgorithmFamily;
+  hndl: boolean;          // harvest-now-decrypt-later exposure
+  message: string;
+  remediation?: string;
+  cwe?: string;           // e.g. "CWE-327"
+  location: { file: string; line: number; column?: number; endLine?: number; snippet?: string };
+}
+
+interface CryptoInventory {
+  byAlgorithm: Partial<Record<AlgorithmFamily, number>>;
+  byCategory: Partial<Record<FindingCategory, number>>;
+  bySeverity: Record<Severity, number>;
+  hndlCount: number;
+  readinessScore: number; // 0–100
+}
+```
+
+## Example
+
+A runnable example lives in [`examples/scan-example.mjs`](./examples/scan-example.mjs):
+
+```bash
+node examples/scan-example.mjs ./path/to/project
+```
+
+## Development
+
+```bash
+npm run build   # tsc -b
+npm test        # node --import tsx --test test/*.test.ts
+```
+
+Tests use only `node:test` + `node:assert`. The package has **zero runtime
+dependencies**.
+
+## License
+
+Apache-2.0

package/dist/baseline.d.ts

@@ -0,0 +1,37 @@
+import type { Finding } from "./types.js";
+/** Current on-disk baseline schema version. */
+export declare const BASELINE_VERSION: 1;
+/** The on-disk baseline shape: a version tag and a set of fingerprints. */
+export interface Baseline {
+    version: number;
+    fingerprints: string[];
+}
+/**
+ * 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 declare function fingerprintFinding(f: Finding): string;
+/** Build a {@link Baseline} from a set of findings (deduped, sorted). */
+export declare function baselineFromFindings(findings: readonly Finding[]): Baseline;
+/**
+ * Split findings into those NOT in the baseline (`newFindings`) and those that
+ * ARE (`suppressed`). Order within each group is preserved from the input.
+ */
+export declare function applyBaseline(findings: readonly Finding[], baseline: Baseline): {
+    newFindings: Finding[];
+    suppressed: Finding[];
+};
+/**
+ * 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 declare function loadBaseline(path: string): Promise<Baseline>;
+/**
+ * Write a baseline derived from the given findings to disk as pretty JSON
+ * (trailing newline). Returns the baseline that was written.
+ */
+export declare function saveBaseline(path: string, findings: readonly Finding[]): Promise<Baseline>;
+//# sourceMappingURL=baseline.d.ts.map

package/dist/baseline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"baseline.d.ts","sourceRoot":"","sources":["../src/baseline.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE1C,+CAA+C;AAC/C,eAAO,MAAM,gBAAgB,EAAG,CAAU,CAAC;AAE3C,2EAA2E;AAC3E,MAAM,WAAW,QAAQ;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAQD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,CAIrD;AAED,yEAAyE;AACzE,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,GAAG,QAAQ,CAO3E;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,SAAS,OAAO,EAAE,EAC5B,QAAQ,EAAE,QAAQ,GACjB;IAAE,WAAW,EAAE,OAAO,EAAE,CAAC;IAAC,UAAU,EAAE,OAAO,EAAE,CAAA;CAAE,CASnD;AAeD;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAYlE;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,CAAC,QAAQ,CAAC,CAIhG"}

package/dist/baseline.js

@@ -0,0 +1,99 @@
+/**
+ * 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";
+/** Current on-disk baseline schema version. */
+export const BASELINE_VERSION = 1;
+/** Collapse all whitespace runs to single spaces and trim (snippet stability). */
+function normalizeSnippet(snippet) {
+    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) {
+    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) {
+    const set = new Set();
+    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, baseline) {
+    const accepted = new Set(baseline.fingerprints);
+    const newFindings = [];
+    const suppressed = [];
+    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) {
+    if (value === null || typeof value !== "object") {
+        return { version: BASELINE_VERSION, fingerprints: [] };
+    }
+    const obj = value;
+    const version = typeof obj.version === "number" ? obj.version : BASELINE_VERSION;
+    const fingerprints = Array.isArray(obj.fingerprints)
+        ? obj.fingerprints.filter((x) => 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) {
+    let text;
+    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, findings) {
+    const baseline = baselineFromFindings(findings);
+    await writeFile(path, `${JSON.stringify(baseline, null, 2)}\n`, "utf8");
+    return baseline;
+}
+//# sourceMappingURL=baseline.js.map

package/dist/baseline.js.map

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

package/dist/cbom.d.ts

@@ -0,0 +1,25 @@
+import type { ScanResult } from "./types.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>;
+}
+/**
+ * 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 declare function toCbom(result: ScanResult): CycloneDxBom;
+//# sourceMappingURL=cbom.d.ts.map

package/dist/cbom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cbom.d.ts","sourceRoot":"","sources":["../src/cbom.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAA6C,UAAU,EAAE,MAAM,YAAY,CAAC;AAGxF,yEAAyE;AACzE,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,WAAW,CAAC;IACvB,WAAW,EAAE,KAAK,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,UAAU,EAAE,aAAa,EAAE,CAAC;CAC7B;AAED,0DAA0D;AAC1D,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,qBAAqB,CAAC;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC1C,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AA8BD;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,YAAY,CAqFvD"}

package/dist/cbom.js

@@ -0,0 +1,131 @@
+/**
+ * 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 { VERSION } from "./version.js";
+/** CycloneDX cryptographic primitive for a finding category. */
+function primitiveFor(category) {
+    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) {
+    return algorithm !== "unknown";
+}
+/** Deterministic bom-ref for a (algorithm, primitive) asset key. */
+function bomRef(key) {
+    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) {
+    // Group findings by (algorithm | primitive).
+    const groups = new Map();
+    for (const f of result.findings) {
+        const algorithm = 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 = [...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",
+            "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) {
+    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)}`;
+}
+//# sourceMappingURL=cbom.js.map

package/dist/cbom.js.map

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

package/dist/changed.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 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 declare function changedFiles(root: string, since?: string): Promise<string[]>;
+//# sourceMappingURL=changed.d.ts.map