@lockhawk/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Faith Onyebueke
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,558 @@
+/** Qualitative severity bands (CVSS-aligned, plus `unknown` for un-scored advisories). */
+type Severity = 'critical' | 'high' | 'medium' | 'low' | 'none' | 'unknown';
+/** Ordering used for `--severity-threshold` and `--fail-on` comparisons. */
+declare const SEVERITY_RANK: Record<Severity, number>;
+/** `true` when `level` is at least as severe as `threshold`. */
+declare function severityAtLeast(level: Severity, threshold: Severity): boolean;
+type PackageManager = 'npm' | 'yarn' | 'pnpm';
+/** How a dependency is reachable from the project root. */
+type DepScope = 'prod' | 'dev' | 'optional' | 'peer';
+/** Unique identity of an installed package: `name@version`. */
+type PkgKey = string;
+/** Build a {@link PkgKey} from a name and version. */
+declare function pkgKey(name: string, version: string): PkgKey;
+/** A single installed package in the dependency graph. */
+interface DepNode {
+    /** `name@version` — the node's key in {@link DependencyGraph.nodes}. */
+    key: PkgKey;
+    name: string;
+    version: string;
+    /** Strongest scope by which this node is reachable (prod beats dev/optional). */
+    scope: DepScope;
+    /** Whether this is a direct dependency of the project root. */
+    direct: boolean;
+    /** Keys of packages this node depends on (edges out). */
+    dependencies: PkgKey[];
+    /** Set when the package has no queryable registry version (file:/link:/git:). */
+    unscannable?: {
+        reason: string;
+    };
+}
+/** The normalized dependency tree, independent of which package manager produced it. */
+interface DependencyGraph {
+    manager: PackageManager;
+    lockfilePath: string;
+    lockfileVersion?: string | number;
+    root: {
+        name: string;
+        version?: string;
+    };
+    /** All installed packages, keyed by {@link PkgKey}. */
+    nodes: Record<PkgKey, DepNode>;
+    /** Keys of the project's direct dependencies. */
+    directKeys: PkgKey[];
+}
+interface OsvEvent {
+    introduced?: string;
+    fixed?: string;
+    last_affected?: string;
+    limit?: string;
+}
+interface OsvRange {
+    type: 'SEMVER' | 'ECOSYSTEM' | 'GIT';
+    events: OsvEvent[];
+    repo?: string;
+}
+interface OsvSeverity {
+    /** e.g. `CVSS_V3`, `CVSS_V4`. */
+    type: string;
+    /** CVSS vector string. */
+    score: string;
+}
+interface OsvAffected {
+    package?: {
+        ecosystem?: string;
+        name?: string;
+        purl?: string;
+    };
+    ranges?: OsvRange[];
+    versions?: string[];
+    severity?: OsvSeverity[];
+    ecosystem_specific?: Record<string, unknown>;
+    database_specific?: Record<string, unknown>;
+}
+interface OsvReference {
+    type?: string;
+    url: string;
+}
+interface OsvVulnerability {
+    id: string;
+    modified?: string;
+    published?: string;
+    /** RFC3339 timestamp; when present the advisory has been retracted and must be ignored. */
+    withdrawn?: string;
+    aliases?: string[];
+    related?: string[];
+    summary?: string;
+    details?: string;
+    severity?: OsvSeverity[];
+    affected?: OsvAffected[];
+    references?: OsvReference[];
+    database_specific?: Record<string, unknown>;
+}
+/** Resolved severity for a finding, with provenance so the UI never shows a bare number. */
+interface SeverityInfo {
+    level: Severity;
+    /** Numeric CVSS base score (0–10) when computable. */
+    score?: number;
+    /** CVSS vector string the score was derived from. */
+    vector?: string;
+    /** e.g. `CVSS:3.1`, `CVSS:4.0`. */
+    cvssVersion?: string;
+    source: 'cvss' | 'database' | 'unknown';
+}
+/** One vulnerability affecting one installed package version. */
+interface Finding {
+    /** Canonical id (prefers CVE, then GHSA, then the OSV id). */
+    id: string;
+    /** All known identifiers for this advisory, including the canonical one. */
+    aliases: string[];
+    packageName: string;
+    version: string;
+    scope: DepScope;
+    direct: boolean;
+    severity: SeverityInfo;
+    summary: string;
+    details?: string;
+    references: string[];
+    /** Versions that resolve this advisory (derived from OSV `fixed` events). */
+    fixedVersions: string[];
+    /** Human-readable mitigation guidance. */
+    recommendation?: string;
+    /** Each path runs root → … → `name@version`, explaining why the package is present. */
+    dependencyPaths: PkgKey[][];
+    source: string;
+}
+interface DatabaseInfo {
+    source: 'offline' | 'online' | 'mixed';
+    recordCount?: number;
+    /** ISO timestamp of when the offline DB was last refreshed. */
+    lastUpdated?: string;
+    ageHours?: number;
+    stale: boolean;
+    warnings: string[];
+}
+interface ScanSummary {
+    total: number;
+    critical: number;
+    high: number;
+    medium: number;
+    low: number;
+    unknown: number;
+    none: number;
+    /** Number of distinct vulnerable packages (not advisories). */
+    vulnerablePackages: number;
+    /** Number of findings that have at least one known fixed version. */
+    fixable: number;
+}
+interface ScanStats {
+    totalPackages: number;
+    uniquePackages: number;
+    directDependencies: number;
+    unscannable: number;
+    durationMs?: number;
+}
+interface UnscannablePackage {
+    name: string;
+    version: string;
+    reason: string;
+}
+/** The complete output of a scan — what reporters serialize and the dashboard renders. */
+interface ScanResult {
+    schemaVersion: 1;
+    tool: {
+        name: string;
+        version: string;
+    };
+    /** ISO timestamp. */
+    scannedAt: string;
+    target: {
+        path: string;
+        manager: PackageManager;
+        lockfile: string;
+        root: {
+            name: string;
+            version?: string;
+        };
+    };
+    database: DatabaseInfo;
+    summary: ScanSummary;
+    stats: ScanStats;
+    findings: Finding[];
+    unscannable: UnscannablePackage[];
+}
+type SourceMode = 'auto' | 'offline' | 'online';
+interface ScanOptions {
+    /** Project directory to scan (defaults to cwd). */
+    path?: string;
+    /** Vulnerability-source strategy. */
+    mode?: SourceMode;
+    cacheDir?: string;
+    cacheTtlHours?: number;
+    noCache?: boolean;
+    concurrency?: number;
+    /** Ignore dev dependencies. */
+    prodOnly?: boolean;
+    /** Advisory ids (CVE/GHSA/OSV) to suppress. */
+    ignore?: string[];
+    /** Fail hard on network errors instead of degrading to cache (fail-open). */
+    strictNetwork?: boolean;
+    /** Limit the scan to a single workspace by name. */
+    workspace?: string;
+    /** Drop findings below this severity from the report. */
+    severityThreshold?: Severity;
+    /** Progress callback (used by the CLI spinner). */
+    onProgress?: (message: string) => void;
+}
+
+interface DetectedLockfile {
+    manager: PackageManager;
+    /** Absolute or relative path to the lockfile. */
+    path: string;
+    filename: string;
+}
+/**
+ * Find the lockfile to scan in `dir`. If several are present we prefer pnpm,
+ * then yarn, then npm — mirroring how a project that committed multiple
+ * lockfiles is most likely actually installed.
+ */
+declare function detectLockfile(dir: string): DetectedLockfile | undefined;
+interface RootManifest {
+    name: string;
+    version?: string;
+    dependencies: Record<string, string>;
+    devDependencies: Record<string, string>;
+    optionalDependencies: Record<string, string>;
+    peerDependencies: Record<string, string>;
+}
+/** Read and normalize the project's `package.json` (used to determine direct deps). */
+declare function readRootManifest(dir: string): RootManifest;
+
+/**
+ * Manager-agnostic parser output. Each lockfile parser produces one of these;
+ * a single {@link buildDependencyGraph} step then classifies scopes by
+ * reachability and assembles the final {@link DependencyGraph}.
+ *
+ * Computing scope from reachability (rather than per-package `dev` flags) is
+ * what lets us treat npm, yarn and pnpm uniformly — pnpm v9 lockfiles, for
+ * instance, no longer carry a per-package `dev` field.
+ */
+interface RawNode {
+    key: PkgKey;
+    name: string;
+    version: string;
+    /** Keys of packages this node depends on (edges out). May contain duplicates. */
+    dependencies: PkgKey[];
+    /** Set when there is no queryable registry version (file:/link:/git:/workspace). */
+    unscannable?: {
+        reason: string;
+    };
+}
+interface RawGraph {
+    manager: PackageManager;
+    lockfilePath: string;
+    lockfileVersion?: string | number;
+    root: {
+        name: string;
+        version?: string;
+    };
+    nodes: Record<PkgKey, RawNode>;
+    /** Direct production dependencies of the project root. */
+    directProd: PkgKey[];
+    /** Direct dev dependencies of the project root. */
+    directDev: PkgKey[];
+    /** Direct optional dependencies of the project root. */
+    directOptional: PkgKey[];
+    unscannable: UnscannablePackage[];
+}
+/**
+ * Classify every node's scope by reachability and assemble the normalized graph.
+ * Priority when a node is reachable multiple ways: prod > optional > dev.
+ */
+declare function buildDependencyGraph(raw: RawGraph): DependencyGraph;
+
+declare class LockfileError extends Error {
+    constructor(message: string);
+}
+/** Parse a detected lockfile into the manager-agnostic {@link RawGraph}. */
+declare function parseLockfile(detected: DetectedLockfile): RawGraph;
+/**
+ * Detect, parse and normalize the lockfile in `dir` into a {@link DependencyGraph}.
+ * Throws {@link LockfileError} when no lockfile is present or parsing fails.
+ */
+declare function loadDependencyGraph(dir: string): DependencyGraph;
+
+/** Label for the project root used as the first element of a dependency path. */
+declare function rootLabel(graph: DependencyGraph): string;
+/**
+ * Shortest dependency path from the project root to `targetKey`, answering
+ * "why is this package in my tree?". Returns `[root, …, target]` or `null` if
+ * the target is not reachable. Uses BFS from a virtual root connected to the
+ * project's direct dependencies.
+ */
+declare function shortestPath(graph: DependencyGraph, targetKey: PkgKey): PkgKey[] | null;
+
+/**
+ * Whether `version` is affected by a single OSV `affected` entry — the heart of
+ * accuracy. We honor enumerated `versions[]` exactly and walk `ranges[].events`
+ * with the canonical OSV sweep. We never coerce a non-semver installed version
+ * into a range match (that would manufacture false positives); such versions
+ * only match via the explicit `versions[]` list.
+ */
+declare function isVersionAffected(version: string, affected: OsvAffected): boolean;
+interface VulnMatch {
+    affected: boolean;
+    /** Distinct `fixed` versions across the matching affected entries. */
+    fixedVersions: string[];
+}
+/**
+ * Whether a whole OSV record affects `name@version` for the npm ecosystem, and
+ * which fixed versions it advertises. Withdrawn advisories never match.
+ */
+declare function vulnerabilityAffects(name: string, version: string, vuln: OsvVulnerability): VulnMatch;
+/**
+ * The lowest advertised fixed version strictly greater than `installed`
+ * (the nearest safe upgrade), or `undefined` if none is known.
+ */
+declare function nearestFix(installed: string, fixedVersions: string[]): string | undefined;
+
+/** Pick the human-facing id: prefer CVE, then GHSA, then the raw OSV id. */
+declare function canonicalId(ids: Iterable<string>): string;
+/**
+ * Collapse advisories that describe the same vulnerability. Records are grouped
+ * by the connected components of their shared ids/aliases (a CVE surfaced under
+ * both a GHSA and an OSV id becomes one finding), then each group is merged into
+ * a single representative carrying the union of aliases, references and severity.
+ */
+declare function dedupeVulnerabilities(vulns: OsvVulnerability[]): OsvVulnerability[];
+
+interface FindingsOptions {
+    /** Skip dev-only dependencies. */
+    prodOnly?: boolean;
+    /** Advisory ids/aliases to suppress. */
+    ignore?: Set<string>;
+}
+/**
+ * Turn a dependency graph plus a per-package advisory lookup into findings.
+ *
+ * `candidatesFor(name)` returns advisories that *name* the package; this
+ * function performs the authoritative version match, de-duplicates aliased
+ * advisories, scores severity and traces the dependency path. Keeping the
+ * version match here (rather than trusting the source) means offline and online
+ * sources share one accuracy-critical code path.
+ */
+declare function buildFindings(graph: DependencyGraph, candidatesFor: (name: string) => OsvVulnerability[], options?: FindingsOptions): Finding[];
+
+interface CvssResult {
+    score: number;
+    level: Severity;
+    /** e.g. `CVSS:3.1`. */
+    version: string;
+}
+/** Map a numeric CVSS base score to its qualitative band. */
+declare function levelFromScore(score: number): Severity;
+/** Map a qualitative label (GHSA-style) to a {@link Severity}. */
+declare function levelFromLabel(label: string): Severity;
+/** Compute a base score from a CVSS v3.0/v3.1/v4.0 vector string, or null if unparseable. */
+declare function scoreFromVector(vector: string): CvssResult | null;
+/**
+ * Resolve the severity of a whole advisory, with provenance. Prefers a computed
+ * CVSS v3 score (highest across all vectors), then the advisory's qualitative
+ * `database_specific.severity`, then `unknown`.
+ */
+declare function resolveSeverity(vuln: OsvVulnerability): SeverityInfo;
+
+/**
+ * In-memory index of OSV advisories for the npm ecosystem, keyed by package
+ * name. Populated either from the downloaded offline DB zip (M3) or from online
+ * API responses, then queried per installed package during a scan.
+ *
+ * Withdrawn advisories are dropped on insert so they can never produce a finding.
+ */
+declare class OsvDatabase {
+    private readonly byName;
+    private readonly ids;
+    add(vuln: OsvVulnerability): void;
+    addAll(vulns: Iterable<OsvVulnerability>): void;
+    /** Candidate advisories that name `packageName` (still need a version check). */
+    vulnerabilitiesFor(packageName: string): OsvVulnerability[];
+    /** Number of distinct advisories indexed. */
+    get size(): number;
+}
+
+interface PackageRef {
+    name: string;
+    version: string;
+}
+interface OnlineClientOptions {
+    cacheDir: string;
+    concurrency?: number;
+    noCache?: boolean;
+    cacheTtlHours?: number;
+    retries?: number;
+}
+/**
+ * Online OSV source. Uses the batch endpoint (which returns only matched ids)
+ * then hydrates each unique id to a full record — caching records by id so
+ * repeat scans do no network work. All matching is re-validated downstream by
+ * `buildFindings`, so this client only has to gather candidate records.
+ */
+declare class OsvClient {
+    private readonly opts;
+    private readonly limit;
+    constructor(opts: OnlineClientOptions);
+    /** Fetch advisories affecting the given packages, keyed by package name. */
+    fetchAdvisories(packages: PackageRef[]): Promise<Map<string, OsvVulnerability[]>>;
+    private queryBatch;
+    private hydrate;
+    private getVulnerability;
+    private request;
+    private readCache;
+    private writeCache;
+}
+
+/** A source prepared for a specific package set: synchronous lookup + provenance. */
+interface ResolvedSource {
+    candidatesFor(name: string): OsvVulnerability[];
+    database: DatabaseInfo;
+}
+/** Strategy for obtaining advisories (offline DB, online API, or auto). */
+interface VulnSource {
+    prepare(packages: PackageRef[]): Promise<ResolvedSource>;
+}
+interface SourceOptions {
+    cacheDir: string;
+    concurrency?: number;
+    noCache?: boolean;
+    cacheTtlHours?: number;
+    /** Fail hard on network errors instead of degrading to cache. */
+    strictNetwork?: boolean;
+    /** Offline DB older than this many hours is flagged stale (default 24). */
+    staleAfterHours?: number;
+}
+/** Reads advisories from the on-disk offline database. */
+declare class OfflineSource implements VulnSource {
+    private readonly opts;
+    constructor(opts: SourceOptions);
+    prepare(packages: PackageRef[]): Promise<ResolvedSource>;
+}
+/** Queries the live OSV.dev API. Fail-open unless `strictNetwork` is set. */
+declare class OnlineSource implements VulnSource {
+    private readonly opts;
+    constructor(opts: SourceOptions);
+    prepare(packages: PackageRef[]): Promise<ResolvedSource>;
+}
+/**
+ * Prefers a fresh offline DB (fast, zero network), falls back to the online API,
+ * and finally to a stale offline DB if the network is down — always degrading
+ * gracefully so a scan never hard-fails on a transient outage.
+ */
+declare class AutoSource implements VulnSource {
+    private readonly opts;
+    constructor(opts: SourceOptions);
+    prepare(packages: PackageRef[]): Promise<ResolvedSource>;
+}
+/** Build the right source for the requested mode. */
+declare function createSource(mode: SourceMode, opts: SourceOptions): VulnSource;
+
+declare const TOOL: {
+    readonly name: "lockhawk";
+    readonly version: "0.1.0";
+};
+/**
+ * Run a full scan: load and normalize the lockfile, query OSV for the unique
+ * scannable packages, build findings, and assemble a {@link ScanResult}.
+ *
+ * A `source` can be injected (used by tests and by the CLI once it has resolved
+ * options); otherwise one is created from `options.mode`.
+ */
+declare function scan(options?: ScanOptions, source?: VulnSource): Promise<ScanResult>;
+/** Unique `name@version` packages worth querying (skips local/unscannable, optionally dev). */
+declare function uniqueScannablePackages(graph: DependencyGraph, prodOnly?: boolean): PackageRef[];
+/** Lowest severity that should trigger a non-zero exit given a `--fail-on` threshold. */
+declare function shouldFail(summary: ScanSummary, failOn: Severity): boolean;
+
+interface OfflineMeta {
+    ecosystem: 'npm';
+    source: string;
+    /** ISO timestamp of the last successful refresh/check. */
+    lastUpdated: string;
+    recordCount: number;
+    packageCount: number;
+    etag?: string;
+    lastModified?: string;
+}
+interface UpdateResult {
+    status: 'updated' | 'unchanged';
+    meta: OfflineMeta;
+}
+declare class OfflineDbMissingError extends Error {
+    constructor();
+}
+/** Read the offline DB metadata, or `undefined` if it has never been built. */
+declare function readOfflineMeta(cacheDir: string): Promise<OfflineMeta | undefined>;
+/**
+ * Download (or conditionally refresh) the npm OSV database and rebuild the
+ * per-package shards. Uses ETag / Last-Modified so an unchanged DB costs a
+ * single 304 and no rewrite. `nowIso` is injected so callers stamp the time
+ * (the engine never calls Date.now itself in pure paths).
+ */
+declare function updateOfflineDatabase(opts: {
+    cacheDir: string;
+    nowIso: string;
+    force?: boolean;
+    onProgress?: (message: string) => void;
+}): Promise<UpdateResult>;
+/**
+ * Load advisories for the given package names. Names are grouped by shard
+ * bucket so each bucket file is read at most once, and a scan only touches the
+ * buckets its dependencies fall into.
+ */
+declare function loadAdvisoriesForPackages(cacheDir: string, names: Iterable<string>): Promise<Map<string, OsvVulnerability[]>>;
+
+/**
+ * Resolve the on-disk cache directory, honoring (in priority order):
+ *   1. an explicit override (the `--cache-dir` flag)
+ *   2. the `LOCKHAWK_CACHE` environment variable
+ *   3. the OS-conventional cache location (via env-paths)
+ */
+declare function resolveCacheDir(override?: string): string;
+/** Directory holding the offline OSV database for the npm ecosystem. */
+declare function offlineDbDir(cacheDir: string): string;
+/** Number of advisory shard buckets — bounds the on-disk file count for CI caching. */
+declare const SHARD_BUCKETS = 4096;
+/** FNV-1a hash → stable shard bucket for a package name. */
+declare function shardBucket(packageName: string): number;
+/** Metadata file describing offline-DB freshness. */
+declare function offlineMetaPath(cacheDir: string): string;
+
+/** Serialize a scan result as pretty-printed JSON. */
+declare function toJson(result: ScanResult): string;
+
+interface SarifLog {
+    $schema: string;
+    version: '2.1.0';
+    runs: unknown[];
+}
+/**
+ * Convert a scan result to SARIF 2.1.0 for GitHub code scanning / Azure DevOps.
+ * One rule per advisory; results carry stable `partialFingerprints` so the same
+ * finding is not re-flagged as new on every run.
+ */
+declare function toSarif(result: ScanResult): SarifLog;
+/** Stringified SARIF log. */
+declare function toSarifString(result: ScanResult): string;
+
+/** Placeholder the report UI shell embeds so we can inject scan data at scan time. */
+declare const DATA_MARKER = "<!--LOCKHAWK_DATA-->";
+/**
+ * Produce a self-contained HTML report. When given the built report-UI `shell`
+ * (M6), the scan data is injected into it; otherwise a dependency-free fallback
+ * template is rendered so `--format html` always works.
+ */
+declare function toHtml(result: ScanResult, shell?: string): string;
+
+/** Render a scan result as JUnit XML (one failed test per finding). */
+declare function toJunit(result: ScanResult): string;
+
+export { AutoSource, type CvssResult, DATA_MARKER, type DatabaseInfo, type DepNode, type DepScope, type DependencyGraph, type DetectedLockfile, type Finding, type FindingsOptions, LockfileError, OfflineDbMissingError, type OfflineMeta, OfflineSource, type OnlineClientOptions, OnlineSource, type OsvAffected, OsvClient, OsvDatabase, type OsvEvent, type OsvRange, type OsvReference, type OsvSeverity, type OsvVulnerability, type PackageManager, type PackageRef, type PkgKey, type RawGraph, type RawNode, type ResolvedSource, type RootManifest, SEVERITY_RANK, SHARD_BUCKETS, type SarifLog, type ScanOptions, type ScanResult, type ScanStats, type ScanSummary, type Severity, type SeverityInfo, type SourceMode, type SourceOptions, TOOL, type UnscannablePackage, type UpdateResult, type VulnMatch, type VulnSource, buildDependencyGraph, buildFindings, canonicalId, createSource, dedupeVulnerabilities, detectLockfile, isVersionAffected, levelFromLabel, levelFromScore, loadAdvisoriesForPackages, loadDependencyGraph, nearestFix, offlineDbDir, offlineMetaPath, parseLockfile, pkgKey, readOfflineMeta, readRootManifest, resolveCacheDir, resolveSeverity, rootLabel, scan, scoreFromVector, severityAtLeast, shardBucket, shortestPath, shouldFail, toHtml, toJson, toJunit, toSarif, toSarifString, uniqueScannablePackages, updateOfflineDatabase, vulnerabilityAffects };