@quantakrypto/core 0.4.4 → 0.6.0

package/dist/hndl.d.ts

@@ -0,0 +1,241 @@
+import type { Confidence, Finding, Severity } from "./types.js";
+/** Version of the exposure model. Bump on any weight / formula change. */
+export declare const HNDL_MODEL_VERSION: "1";
+/** Canonical `hndl.yml` file name discovered at a scan root. */
+export declare const HNDL_FILENAME = "hndl.yml";
+/** Data sensitivity classes, least → most sensitive. Vocabulary aligned with the
+ * readiness DPE (data-protection) practice. */
+export type DataClassification = "public" | "internal" | "confidential" | "regulated";
+/**
+ * Logical scope a finding belongs to, used for optional scope-bound assets. The
+ * two detector scopes ("source" / "config") plus "dependency" (manifest
+ * findings, which are not produced by a Detector).
+ */
+export type HndlScope = "source" | "config" | "dependency";
+/** Crypto-vulnerability weight (V) contributed by a finding's severity. */
+export declare const SEVERITY_VULNERABILITY: Record<Severity, number>;
+/** Crypto-vulnerability weight (V) scaled by detector confidence. */
+export declare const CONFIDENCE_WEIGHT: Record<Confidence, number>;
+/** Data-sensitivity weight (S) per classification. */
+export declare const CLASSIFICATION_SENSITIVITY: Record<DataClassification, number>;
+/**
+ * Discount applied to V when a finding is NOT harvest-now-decrypt-later exposed
+ * (e.g. a pure signature). A forged signature is a future-integrity problem, not
+ * a retroactive-confidentiality one, so it barely moves the HNDL needle.
+ */
+export declare const NON_HNDL_DISCOUNT = 0.15;
+/**
+ * Default years until a cryptographically-relevant quantum computer is assumed
+ * to exist (Z in Mosca's inequality). 15 years is a defensible mid-point of the
+ * commonly-cited Mosca / NIST window; override per-org in `hndl.yml`.
+ */
+export declare const DEFAULT_QUANTUM_THREAT_YEARS = 15;
+/**
+ * Default years to complete the org's PQC migration (Y in Mosca's inequality).
+ * Override per-org in `hndl.yml`.
+ */
+export declare const DEFAULT_MIGRATION_HORIZON_YEARS = 5;
+/** Classification assumed for findings that bind to no declared asset. */
+export declare const DEFAULT_UNBOUND_CLASSIFICATION: DataClassification;
+/** A single declared data asset from `hndl.yml`. */
+export interface HndlDataAsset {
+    /** Stable id (referenced by finding exposures + the website's `data_asset.key`). */
+    key: string;
+    /** Human name. */
+    name: string;
+    classification: DataClassification;
+    /** How long the data is retained, in years. */
+    retentionYears: number;
+    /** How long the data must remain confidential once captured, in years. */
+    secrecyLifetimeYears: number;
+    /** Path globs (POSIX, relative to scan root) whose findings bind to this asset. */
+    paths: string[];
+    /** Optional detector-scope filter: only findings of these scopes bind here. */
+    scopes?: HndlScope[];
+}
+/** The Mosca horizons that gate the exposure model. */
+export interface HndlHorizon {
+    /** Z: years until a cryptographically-relevant quantum computer is assumed. */
+    quantumThreatYears: number;
+    /** Y: years to complete the org's PQC migration. */
+    migrationHorizonYears: number;
+}
+/** Defaults applied to findings that bind to no declared asset. */
+export interface HndlDefaults {
+    classification: DataClassification;
+}
+/** A fully-parsed, validated `hndl.yml`. */
+export interface HndlMap {
+    version: number;
+    horizon: HndlHorizon;
+    defaults: HndlDefaults;
+    assets: HndlDataAsset[];
+}
+/** Thrown when `hndl.yml` is malformed (structure or a bad known value). */
+export declare class HndlError extends Error {
+    readonly name = "HndlError";
+    /** The `hndl.yml` path the error relates to, when known. */
+    readonly path: string | undefined;
+    constructor(message: string, hndlPath?: string);
+}
+/** Full, auditable breakdown of one finding's exposure score. */
+export interface ExposureRationale {
+    /** V - crypto-vulnerability factor (0..1). */
+    vulnerability: number;
+    /** S - data-sensitivity factor (0..1). */
+    sensitivity: number;
+    /** M - Mosca factor (0..1): fraction of the protection horizon past the threat. */
+    mosca: number;
+    classification: DataClassification;
+    retentionYears: number;
+    secrecyLifetimeYears: number;
+    /** X = max(retention, secrecy lifetime): the data's protection requirement. */
+    secrecyHorizonYears: number;
+    /** Z - quantum-threat horizon (years). */
+    quantumThreatYears: number;
+    /** Y - migration horizon (years). */
+    migrationHorizonYears: number;
+    /** (X + Y) - Z; positive means Mosca's inequality is breached. */
+    moscaMarginYears: number;
+    /** True when (X + Y) > Z (data captured today is exposed while still secret). */
+    moscaBreach: boolean;
+    /** Whether the finding is HNDL-exposed (drives {@link NON_HNDL_DISCOUNT}). */
+    hndl: boolean;
+    severity: Severity;
+    confidence: Confidence;
+    scope: HndlScope;
+    /** True when the finding matched a declared asset (false = defaults applied). */
+    bound: boolean;
+}
+/** A finding's computed exposure, keyed by fingerprint for website ingest. */
+export interface FindingExposure {
+    /** Finding identity: `finding.fingerprint` when present, else the canonical
+     * `fingerprintFinding()` hash. This is the join key the website stores. */
+    fingerprint: string;
+    ruleId: string;
+    file: string;
+    /** The bound data asset's stable key, or null when unbound. */
+    dataAsset: string | null;
+    /** 0..100 exposure score. */
+    exposureScore: number;
+    rationale: ExposureRationale;
+}
+/** Per-asset rollup for the repo summary. */
+export interface AssetExposure {
+    key: string;
+    name: string;
+    classification: DataClassification;
+    retentionYears: number;
+    secrecyLifetimeYears: number;
+    /** Number of findings bound to this asset. */
+    findings: number;
+    /** Highest exposure among this asset's findings. */
+    maxExposure: number;
+    /** True when the data's secrecy horizon outlives the quantum threat (X > Z). */
+    outlivesThreat: boolean;
+}
+/** Repo-level HNDL summary. */
+export interface HndlSummary {
+    findingsScored: number;
+    assetsDeclared: number;
+    /** Declared assets that bound at least one finding. */
+    assetsWithFindings: number;
+    /** Declared assets whose secrecy horizon outlives the quantum threat (X > Z). */
+    assetsOutlivingHorizon: number;
+    /** Findings whose Mosca inequality is breached ((X + Y) > Z). */
+    moscaBreaches: number;
+    maxExposure: number;
+    /** Rounded mean exposure across scored findings. */
+    meanExposure: number;
+    /** The worst findings, most-exposed first (capped). */
+    topExposures: FindingExposure[];
+}
+/** The complete HNDL analysis of a scan. */
+export interface HndlReport {
+    modelVersion: string;
+    horizon: HndlHorizon;
+    /** Per-finding exposures, in input order. */
+    exposures: FindingExposure[];
+    /** Fingerprint → exposure, for reporters to annotate each finding. */
+    byFingerprint: Map<string, FindingExposure>;
+    /** Per-asset rollups. */
+    assets: AssetExposure[];
+    summary: HndlSummary;
+}
+/**
+ * Identity key for a finding's exposure. Prefers a `finding.fingerprint` field
+ * when a build supplies one (another workstream is adding it to core's Finding
+ * type + reporters); falls back to the canonical `fingerprintFinding()` hash
+ * (`sha256(ruleId|file|normalizedSnippet)`) otherwise. INTEGRATION POINT: once
+ * `Finding.fingerprint` lands, this transparently switches to it - no caller
+ * change needed.
+ */
+export declare function findingFingerprint(f: Finding): string;
+/**
+ * The scope a finding belongs to. Dependency findings (from the manifest
+ * scanner, category "dependency") are "dependency"; everything else is looked up
+ * by ruleId in the detector registry, defaulting to "source".
+ */
+export declare function findingScope(f: Finding): HndlScope;
+/**
+ * Match a POSIX path against a glob supporting `**` (any path segments incl.
+ * `/`), `*` (any run of non-`/` chars), and `?` (a single non-`/` char). A
+ * trailing `/**` also matches the directory itself. Everything else is literal.
+ */
+export declare function globMatch(glob: string, filePath: string): boolean;
+/** V - crypto-vulnerability factor for a finding (0..1). */
+export declare function vulnerabilityFactor(f: Finding): number;
+/**
+ * M - the Mosca factor (0..1). `X` is the data's protection horizon
+ * (max of retention + secrecy lifetime), `Y` the migration horizon, `Z` the
+ * quantum-threat horizon. M is the fraction of `X + Y` that falls after `Z`:
+ * 0 when the threat is beyond the whole horizon, 1 when the threat is already
+ * here. Mosca's inequality (X + Y > Z) is exactly `M > 0`.
+ */
+export declare function moscaFactor(secrecyHorizonYears: number, horizon: HndlHorizon): number;
+/**
+ * Compute HNDL exposure for a set of findings against a declared data map.
+ *
+ * A finding binds to every declared asset whose path glob (and optional scope
+ * filter) matches its file; when several match, the WORST-CASE (highest)
+ * exposure is chosen and its asset recorded, since risk ranking should not be
+ * diluted by an incidental low-sensitivity overlap. A finding that binds to no
+ * asset is still scored, using the map's `defaults.classification` and the
+ * global horizons, and flagged `bound: false` so it is visibly a fallback. Its
+ * secrecy lifetime is assumed to be the quantum-threat horizon Z (the
+ * minimum-concern horizon; see {@link scoreFinding} call below and docs/HNDL.md
+ * §4), so the fallback classification produces a real, rankable exposure rather
+ * than a dead 0.
+ *
+ * Purely additive: it never mutates findings and never affects a scan's exit
+ * code.
+ */
+export declare function computeHndl(findings: readonly Finding[], map: HndlMap): HndlReport;
+/**
+ * Validate a parsed `hndl.yml` object into a typed {@link HndlMap}. Applies
+ * defaults for `version`, `horizon`, and `defaults`; requires each asset to have
+ * a unique `key`, a `name`, a valid `classification`, non-negative retention +
+ * secrecy lifetime, and at least one path glob.
+ */
+export declare function parseHndlMap(text: string, file?: string): HndlMap;
+/**
+ * Load and validate the `hndl.yml` for a scan. By default reads
+ * `<root>/hndl.yml`; pass an explicit `*.yml` path to read a named file. A
+ * missing file is always an error here (the caller opted into `--hndl`).
+ *
+ * @throws {HndlError} On a missing file, unreadable file, or malformed content.
+ */
+export declare function loadHndlMap(root: string): Promise<{
+    map: HndlMap;
+    path: string;
+}>;
+/**
+ * Scaffold an `hndl.yml` document seeded from a scan's findings. Config-scope,
+ * HNDL-exposed findings are the crypto-to-data join points (KMS, secrets-at-rest,
+ * database TDE, brokers, JOSE/JWE), so each directory that contains one becomes a
+ * proposed asset stub the user fills in. The returned string is valid `hndl.yml`
+ * (it round-trips through {@link parseHndlMap}); the classification / retention /
+ * secrecy values are conservative placeholders the user is expected to correct.
+ */
+export declare function scaffoldHndlYaml(findings: readonly Finding[]): string;
+//# sourceMappingURL=hndl.d.ts.map

package/dist/hndl.d.ts.map

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