@mitre/hdf-utilities 3.4.3 → 3.5.0

package/README.md

@@ -69,22 +69,22 @@ Generate and verify cryptographic hashes for data integrity:
 ```typescript
 import { sha256, sha512, generateHash, hashObject, verifyHash } from '@mitre/hdf-utilities';
 
-// Quick SHA-256 hash
-const hash = sha256('content to hash');
+// Quick SHA-256 hash (hash functions are async)
+const hash = await sha256('content to hash');
 console.log(hash); // hex-encoded hash
 
 // Hash with custom options
-const customHash = generateHash('data', {
+const customHash = await generateHash('data', {
   algorithm: 'sha512',
   encoding: 'base64'
 });
 
 // Hash JavaScript objects (deterministic JSON serialization)
 const baseline = { name: 'My Baseline', version: '1.0' };
-const objectHash = hashObject(baseline, { algorithm: 'sha256' });
+const objectHash = await hashObject(baseline, { algorithm: 'sha256' });
 
 // Verify data integrity
-const isValid = verifyHash('original data', hash, { algorithm: 'sha256' });
+const isValid = await verifyHash('original data', hash, { algorithm: 'sha256' });
 if (!isValid) {
   console.error('Data integrity check failed!');
 }
@@ -229,42 +229,42 @@ Check if string can be parsed as JSON.
 
 ### Hash Utilities
 
-#### `sha256(data: string): string`
+#### `sha256(data: string): Promise<string>`
 
 Generate SHA-256 hash (hex-encoded).
 
 - **Parameters:**
   - `data` - String to hash
-- **Returns:** Hex-encoded hash string
+- **Returns:** Promise resolving to a hex-encoded hash string
 
-#### `sha512(data: string): string`
+#### `sha512(data: string): Promise<string>`
 
 Generate SHA-512 hash (hex-encoded).
 
 - **Parameters:**
   - `data` - String to hash
-- **Returns:** Hex-encoded hash string
+- **Returns:** Promise resolving to a hex-encoded hash string
 
-#### `generateHash(data: string, options?: HashOptions): string`
+#### `generateHash(data: string, options?: HashOptions): Promise<string>`
 
 Generate hash with custom algorithm and encoding.
 
 - **Parameters:**
   - `data` - String to hash
   - `options.algorithm` - Hash algorithm: `'sha256'` | `'sha512'` (default: `'sha256'`)
-  - `options.encoding` - Output encoding: `'hex'` | `'base64'` | `'base64url'` (default: `'hex'`)
-- **Returns:** Encoded hash string
+  - `options.encoding` - Output encoding: `'hex'` | `'base64'` (default: `'hex'`)
+- **Returns:** Promise resolving to the encoded hash string
 
-#### `hashObject(obj: unknown, options?: HashOptions): string`
+#### `hashObject(obj: unknown, options?: HashOptions): Promise<string>`
 
 Generate deterministic hash of JavaScript object.
 
 - **Parameters:**
   - `obj` - Object to hash (will be JSON-stringified)
   - `options` - Same as `generateHash`
-- **Returns:** Hash of serialized object
+- **Returns:** Promise resolving to the hash of the serialized object
 
-#### `verifyHash(data: string, expectedHash: string, options?: HashOptions): boolean`
+#### `verifyHash(data: string, expectedHash: string, options?: HashOptions): Promise<boolean>`
 
 Verify data matches expected hash.
 
@@ -272,7 +272,7 @@ Verify data matches expected hash.
   - `data` - Original data to verify
   - `expectedHash` - Expected hash value
   - `options` - Same hash options used during generation
-- **Returns:** `true` if hash matches, `false` otherwise
+- **Returns:** Promise resolving to `true` if the hash matches, `false` otherwise
 
 ### XML Utilities
 

package/dist/index.d.ts

@@ -28,6 +28,15 @@ import { formatTimestamp, formatTimestampSeconds, normalizeHdfTimestamps, parseT
 declare function severityToImpact(severity: null): null;
 declare function severityToImpact(severity: string): number;
 declare function severityToImpact(severity: string | null): number | null;
+/**
+ * Round an HDF impact value to 2 decimal places — its canonical precision —
+ * eliminating the representation noise that binary float division leaves behind
+ * (e.g. 9.8 / 10 = 0.9800000000000001). Impact is defined on 0.0–1.0 with a
+ * natural 0.01 grid (a 1-decimal CVSS score / 10), so this is lossless in
+ * intent. Use it wherever impact is COMPUTED (divided or otherwise
+ * arithmetically derived), not when assigned from a literal band.
+ */
+declare function roundImpact(x: number): number;
 /**
  * Map an impact score to a severity string.
  *
@@ -56,6 +65,80 @@ declare function impactToSeverity(impact: number | null): string | null;
  */
 declare function cvssScoreToSeverity(score: number): 'none' | 'low' | 'medium' | 'high' | 'critical';
 //#endregion
+//#region src/status/index.d.ts
+/**
+ * Canonical HDF result-status ordering and effective-status computation.
+ *
+ * This is the single source of truth for worst-wins roll-up and
+ * effective-status selection across hdf-libs (mirrored in Go as
+ * hdf-utilities/go status.go). The precedence rules are published in
+ * site/docs/architecture/status-determination.md; do not re-implement them.
+ */
+/** Canonical worst-wins ordering, worst first. */
+declare const STATUS_SEVERITY_ORDER: readonly string[];
+/** Severity rank of a status: higher = worse. Unknown statuses rank -1. */
+declare function statusRank(status: string): number;
+/**
+ * Rolls a list of result statuses up to the worst one. An empty list (or a
+ * list of only unknown statuses) rolls up to "notReviewed".
+ */
+declare function worstStatus(statuses: readonly string[]): string;
+/**
+ * Neutral shape of a status override for effective-status computation.
+ * Callers map their concrete types (schema objects or raw JSON) onto it.
+ */
+interface StatusOverrideInput {
+  /** Empty/undefined means the override carries no status and never governs. */
+  status?: string;
+  /** RFC3339 timestamp; undefined sorts earliest. */
+  appliedAt?: string;
+  /** RFC3339 timestamp; undefined means the override never expires. */
+  expiresAt?: string;
+}
+/**
+ * Selects the override that governs a requirement: the most recently applied
+ * (by appliedAt) non-expired override that carries a status — matching the
+ * schema's definition of disposition ("the most recent non-expired
+ * override"). Returns undefined when no override governs.
+ */
+declare function governingStatusOverride(overrides: readonly StatusOverrideInput[], referenceTimestamp?: string): StatusOverrideInput | undefined;
+/**
+ * Returns the index of the most recently applied (by appliedAt) non-expired
+ * override among those for which `eligible` returns true, or -1 when none
+ * qualifies. Generalizes governing-override selection to per-field
+ * eligibility: the schema defines effectiveStatus, effectiveImpact, and
+ * disposition each as "the most recent non-expired override" carrying the
+ * relevant field, so callers pass the field-presence check as the predicate.
+ */
+declare function governingOverrideIndex(overrides: readonly StatusOverrideInput[], eligible: (index: number) => boolean, referenceTimestamp?: string): number;
+/**
+ * Index variant of {@link governingStatusOverride}: returns -1 when no
+ * override governs. Callers holding richer concrete override types use the
+ * index to recover their own object.
+ */
+declare function governingStatusOverrideIndex(overrides: readonly StatusOverrideInput[], referenceTimestamp?: string): number;
+/** Neutral shape of a requirement for effective-status computation. */
+interface EffectiveStatusInput {
+  impact: number;
+  /** The stored effectiveStatus field; undefined means unset. */
+  effectiveStatus?: string;
+  resultStatuses?: readonly string[];
+  overrides?: readonly StatusOverrideInput[];
+}
+/**
+ * Determines a requirement's effective status — the single canonical
+ * implementation of the precedence in status-determination.md:
+ *
+ * 1. impact === 0 → "notApplicable", regardless of results or overrides
+ * 2. the governing (most recent non-expired) status override's status
+ * 3. the stored effectiveStatus, honored only when NO overrides are present —
+ *    effectiveStatus is state derived from overrides, so when every override
+ *    has expired it is stale and the result roll-up wins
+ * 4. worst-wins roll-up of the result statuses
+ * 5. no results → "notReviewed"
+ */
+declare function computeEffectiveStatus(input: EffectiveStatusInput, referenceTimestamp?: string): string;
+//#endregion
 //#region src/cvss/index.d.ts
 /**
  * CVSS vector parsing and validation utilities.
@@ -108,6 +191,42 @@ declare function parseCvssVector(vector: string): ParsedCvssVector;
  * @returns `{ valid, errors[] }` — never throws
  */
 declare function validateCvssVector(vector: string, version?: string): CvssValidationResult;
+/** A computed CVSS score. */
+interface CvssScore {
+  /** CVSS major.minor version the score was computed under (currently always "3.1"). */
+  version: string;
+  /** Base score (0.0–10.0). */
+  baseScore: number;
+  /**
+   * Temporal (Threat) score (0.0–10.0). Equals baseScore when no temporal
+   * metrics (E/RL/RC) are present, per the CVSS 3.1 spec.
+   */
+  temporalScore: number;
+}
+/**
+ * Compute the CVSS 3.1 Base and Temporal (Threat) scores for a vector string.
+ *
+ * Only CVSS 3.1 is supported here — CVSS 4.0's MacroVector engine lives
+ * separately — so any other version throws rather than returning a wrong number.
+ * The peer of the Go `ComputeCvssScore` (kept byte-identical via shared fixtures).
+ *
+ * @throws if the version is not 3.1, a required base metric is missing, or any
+ *   metric value is out of the 3.1 enum.
+ */
+declare function computeCvssScore(vector: string): CvssScore;
+/** Parse a CVSS 4.0 vector and return its MacroVector string. */
+declare function cvss40MacroVector(vector: string): string;
+/**
+ * Compute the CVSS 4.0 score for a vector string, split into a Base score
+ * (`baseScore`, with Exploit Maturity stripped to its worst-case default E:A) and
+ * a Threat score (`temporalScore`, with the E value present in the vector). For a
+ * base-only vector the two are equal. The peer of the Go `ComputeCvss40Score`,
+ * kept byte-identical via the shared data file and parity fixture.
+ *
+ * @throws if the version is not 4.0, a required base metric is missing, or any
+ *   metric value is out of the 4.0 enum.
+ */
+declare function computeCvss40Score(vector: string): CvssScore;
 //#endregion
 //#region src/cpe/index.d.ts
 /**
@@ -237,5 +356,5 @@ interface ParsedPurl {
  */
 declare function parsePurl(purlStr: string): ParsedPurl | null;
 //#endregion
-export { type CpePart, type CsvBuildOptions, type CsvParseOptions, type CvssValidationResult, type HashAlgorithm, type HashEncoding, type HashOptions, type ParsedCpe, type ParsedCvssVector, type ParsedPurl, type StringifyOptions, buildCsv, buildCsvArray, buildXml, cvssScoreToSeverity, extractColumn, extractColumn as extractCsvColumn, extractTextFromXml, findRows as findCsvRows, findRows, findValuesByKey as findJsonValues, findValuesByKey, findValuesByKey as findXmlValues, formatTimestamp, formatTimestampSeconds, generateHash, hashObject, impactToSeverity, isValidCsv, isValidJSON, isValidXml, normalizeHdfTimestamps, parseCpe, parseCsv, parseCsvArray, parseCvssVector, parseJSON, parsePurl, parseTimestamp, parseXml, parseXmlWithArrays, sanitizeCsvArray, sanitizeCsvObject, sanitizeCsvValue, severityToImpact, sha256, sha512, stringifyJSON, stripHtml, trimUtcFraction, validateCvssVector, verifyHash };
+export { type CpePart, type CsvBuildOptions, type CsvParseOptions, type CvssScore, type CvssValidationResult, type EffectiveStatusInput, type HashAlgorithm, type HashEncoding, type HashOptions, type ParsedCpe, type ParsedCvssVector, type ParsedPurl, STATUS_SEVERITY_ORDER, type StatusOverrideInput, type StringifyOptions, buildCsv, buildCsvArray, buildXml, computeCvss40Score, computeCvssScore, computeEffectiveStatus, cvss40MacroVector, cvssScoreToSeverity, extractColumn, extractColumn as extractCsvColumn, extractTextFromXml, findRows as findCsvRows, findRows, findValuesByKey as findJsonValues, findValuesByKey, findValuesByKey as findXmlValues, formatTimestamp, formatTimestampSeconds, generateHash, governingOverrideIndex, governingStatusOverride, governingStatusOverrideIndex, hashObject, impactToSeverity, isValidCsv, isValidJSON, isValidXml, normalizeHdfTimestamps, parseCpe, parseCsv, parseCsvArray, parseCvssVector, parseJSON, parsePurl, parseTimestamp, parseXml, parseXmlWithArrays, roundImpact, sanitizeCsvArray, sanitizeCsvObject, sanitizeCsvValue, severityToImpact, sha256, sha512, statusRank, stringifyJSON, stripHtml, trimUtcFraction, validateCvssVector, verifyHash, worstStatus };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../src/severity/index.ts","../src/cvss/index.ts","../src/cpe/index.ts","../src/purl/index.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;iBAgCgB,iBAAiB;iBACjB,iBAAiB;iBACjB,iBAAiB;;;;;;;iBAajB,iBAAiB;iBACjB,iBAAiB;iBACjB,iBAAiB;;;;;;;;;;;;;;;;;;iBA2BjB,oBACd;;;;;;;;;;;;;;;UChEe;;EAEf;;EAEA,SAAS;;UAGM;EACf;EACA;;;;;;;;;;;;iBA2Ic,gBAAgB,iBAAiB;;;;;;;;;;;;;;;;;;iBA4DjC,mBACd,gBACA,mBACC;;;;;;;;;;;;;;;;;;KChNS;;;;;;;;UASK;;EAEf;;EAEA,MAAM;EACN;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;EAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAuEc,SAAS,iBAAiB;;;;;;;;;;;;;;;;;;;UC/FzB;;EAEf;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA,YAAY;;EAEZ;;EAEA;;;;;;;;;;;;;;;;;;;;;iBAwBc,UAAU,kBAAkB"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/severity/index.ts","../src/status/index.ts","../src/cvss/index.ts","../src/cpe/index.ts","../src/purl/index.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;iBAgCgB,iBAAiB;iBACjB,iBAAiB;iBACjB,iBAAiB;;;;;;;;;iBAejB,YAAY;;;;;;;iBAUZ,iBAAiB;iBACjB,iBAAiB;iBACjB,iBAAiB;;;;;;;;;;;;;;;;;;iBA2BjB,oBACd;;;;;;;;;;;;cC7EW;;iBASG,WAAW;;;;;iBASX,YAAY;;;;;UAiBX;;EAEf;;EAEA;;EAEA;;;;;;;;iBAiBc,wBACd,oBAAoB,uBACpB,8BACC;;;;;;;;;iBAaa,uBACd,oBAAoB,uBACpB,WAAW,2BACX;;;;;;iBAmBc,6BACd,oBAAoB,uBACpB;;UAgBe;EACf;;EAEA;EACA;EACA,qBAAqB;;;;;;;;;;;;;;iBAeP,uBACd,OAAO,sBACP;;;;;;;;;;;;;;;UCrIe;;EAEf;;EAEA,SAAS;;UAGM;EACf;EACA;;;;;;;;;;;;iBA2Ic,gBAAgB,iBAAiB;;;;;;;;;;;;;;;;;;iBA4DjC,mBACd,gBACA,mBACC;;UAsCc;;EAEf;;EAEA;;;;;EAKA;;;;;;;;;;;;iBAsDc,iBAAiB,iBAAiB;;iBA6KlC,kBAAkB;;;;;;;;;;;iBAiMlB,mBAAmB,iBAAiB;;;;;;;;;;;;;;;;;;KCrqBxC;;;;;;;;UASK;;EAEf;;EAEA,MAAM;EACN;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;EAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAuEc,SAAS,iBAAiB;;;;;;;;;;;;;;;;;;;UC/FzB;;EAEf;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA,YAAY;;EAEZ;;EAEA;;;;;;;;;;;;;;;;;;;;;iBAwBc,UAAU,kBAAkB"}