@mitre/hdf-engine 3.7.2 → 3.8.0-next.42533588944.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -170,7 +170,8 @@ The `fetch` function is supplied by the caller, so this package never reads the
170
170
  ### Evidence
171
171
 
172
172
  - `parseEvidencePackage` / `ParseEvidencePackage` — package name and contents
173
- - `verifyChecksums` / `VerifyChecksums` — per-reference checksum status
173
+ - `verifyChecksums` / `VerifyChecksums` — per-reference checksum status. Asynchronous in TypeScript (`await verifyChecksums(...)`): it hashes the SHA family with Web Crypto so the package bundles for the browser.
174
+ - `checksumHex` / `ChecksumHex` — hash bytes under a named `Hash_Algorithm`; the one definition of which algorithms this codebase can verify. Asynchronous in TypeScript for the same reason.
174
175
  - `plannedBaselineRefs`, `coveredBaselineNames`, `coveredBaselinesInPackage` — plan coverage inputs
175
176
  - `agentOverridesInPackage` / `AgentOverridesInPackage` — agent-attributed overrides across a package
176
177
  - `completeness` / `Completeness` — planned versus covered
package/dist/index.d.ts CHANGED
@@ -1,9 +1,6 @@
1
1
  import { StatusOverrideInput } from "@mitre/hdf-utilities";
2
2
  import { EvaluatedRequirement, HDFBaseline, HDFResults, RequirementResult, Severity } from "@mitre/hdf-schema";
3
- //#region src/version.d.ts
4
- export declare const engineVersion = "3.7.2";
5
- //#endregion
6
- //#region src/merge.d.ts
3
+ export declare const engineVersion = "3.8.0-next.42533588944.1";
7
4
  /** One input to merge: a results document and the name it is recorded under. */
8
5
  interface MergeSource {
9
6
  name: string;
@@ -34,8 +31,6 @@ export declare const LABEL_SOURCE_DOCUMENT = "sourceDocument";
34
31
  * throws only when there is nothing to merge. Inputs are not mutated.
35
32
  */
36
33
  export declare function merge(sources: MergeSource[]): MergeResult;
37
- //#endregion
38
- //#region src/detect.d.ts
39
34
  /** The eight HDF document type strings, matching validators.Type* in Go. */
40
35
  type HdfDocType = 'results' | 'baseline' | 'system' | 'plan' | 'amendments' | 'evidence-package' | 'comparison' | 'requirement-change-event' | '';
41
36
  /**
@@ -44,8 +39,6 @@ type HdfDocType = 'results' | 'baseline' | 'system' | 'plan' | 'amendments' | 'e
44
39
  * HDF document type.
45
40
  */
46
41
  export declare function detect(input: string): HdfDocType;
47
- //#endregion
48
- //#region src/values.d.ts
49
42
  /**
50
43
  * A predicate field's value set, and the normalizer that accepts the three
51
44
  * spellings a policy may use for it: a bare scalar for the common single-value
@@ -68,8 +61,6 @@ export declare function detect(input: string): HdfDocType;
68
61
  type PredicateValue = string | string[] | {
69
62
  not: string | string[];
70
63
  };
71
- //#endregion
72
- //#region src/vocabulary.d.ts
73
64
  /**
74
65
  * The closed vocabulary a status filter may name: the schema's Result_Status
75
66
  * enum. It is the EFFECTIVE status that is compared — the resolver a caller
@@ -130,8 +121,6 @@ export declare function validSeverity(s: string): boolean;
130
121
  * rule and an `hdf query` invocation mean the same thing.
131
122
  */
132
123
  export declare function normalizeFilterValue(field: string, value: string): string;
133
- //#endregion
134
- //#region src/query.d.ts
135
124
  /**
136
125
  * FilterOptions configures a requirements query. Every filter input arrives here;
137
126
  * distinct filters combine with AND, repeated values within a filter with OR.
@@ -240,8 +229,6 @@ interface Match {
240
229
  * calling adapter rejects document types that carry no requirements.
241
230
  */
242
231
  export declare function filter(results: HDFResults, rawOptions: FilterOptions): Match[];
243
- //#endregion
244
- //#region src/effective.d.ts
245
232
  /**
246
233
  * Maps a requirement's schema overrides onto the shared helper's neutral shape,
247
234
  * whose timestamps are the RFC3339 strings the schema's Date fields came from.
@@ -254,8 +241,6 @@ export declare function overrideInputs(control: EvaluatedRequirement): StatusOve
254
241
  * canonical. An undefined reference means now.
255
242
  */
256
243
  export declare function effectiveImpactOf(control: EvaluatedRequirement, now?: string): number;
257
- //#endregion
258
- //#region src/compliance.d.ts
259
244
  interface SeverityCounts {
260
245
  critical: number;
261
246
  high: number;
@@ -460,8 +445,6 @@ export declare function ruleRefusal(count: number): string;
460
445
  * validateThresholds and evaluate. Parity: validateGrid in go/compliance.go.
461
446
  */
462
447
  export declare function validateGrid(config: ThresholdConfig, counts: StatusCounts, compliance: number, controlMap: ControlIDMapping[]): Violation[];
463
- //#endregion
464
- //#region src/rules.d.ts
465
448
  /**
466
449
  * The vocabulary a rule may name. It is deliberately the filter engine's own
467
450
  * vocabulary rather than a second one: a rule and an `hdf query` invocation then
@@ -551,8 +534,6 @@ interface ThresholdInput {
551
534
  * half-implement a policy without being told. Parity: Evaluate in go/rules.go.
552
535
  */
553
536
  export declare function evaluate(config: ThresholdConfig, input: ThresholdInput): Violation[];
554
- //#endregion
555
- //#region src/loader.d.ts
556
537
  /** Wire encoding of loader input (parity with Go InputFormat). */
557
538
  type InputFormat = 'json' | 'ndjson';
558
539
  interface LoadResult {
@@ -579,21 +560,51 @@ export declare function load(input: string | Uint8Array, maxSize?: number): Load
579
560
  * object stays 'json' (its first line is not itself a complete JSON value).
580
561
  */
581
562
  export declare function detectFormat(text: string): InputFormat;
582
- //#endregion
583
- //#region src/evidence.d.ts
584
- /** Classifies a single content entry's checksum verification. */
585
- type ChecksumStatus = 'match' | 'mismatch' | 'skipped' | 'error';
563
+ /** Classifies a single content entry's checksum verification. 'unsupported' is a
564
+ * recorded algorithm this build cannot compute — deliberately NOT 'error', since the
565
+ * bytes may be intact and the package valid. Every consumer switching on this type
566
+ * must handle it; leaving it to a default reports an unverified entry as verified. */
567
+ type ChecksumStatus = 'match' | 'mismatch' | 'skipped' | 'error' | 'unsupported';
586
568
  /** One content entry of an evidence package: a referenced document and its
587
569
  * recorded checksum ('' when the entry carries none). */
588
570
  interface EvidenceContent {
589
571
  uri: string;
590
572
  type: string;
591
573
  checksum: string;
574
+ /** The algorithm the package recorded, '' when it stated none. Optional so an
575
+ * omitted field behaves exactly like Go's zero-valued string: absent means
576
+ * sha256 at verification time. The sha256 default belongs to verification, not
577
+ * to the parse, so an unstated algorithm is not invented here. */
578
+ checksumAlgorithm?: string;
579
+ /** Distinguishes an entry carrying no checksum object from one carrying a
580
+ * checksum whose value is empty. `checksum` alone conflates them, and the
581
+ * difference matters: a recorded-but-blank value is unverifiable, whereas an
582
+ * absent checksum is simply not a claim. Optional so an omitted field behaves
583
+ * like Go's zero-valued bool. */
584
+ checksumRecorded?: boolean;
585
+ /** Set for an `externalEvidence[]` entry and absent for a `contents[]` one;
586
+ * `type` is the reverse. The schema gives the two arrays different fields — a
587
+ * content entry records a Content_Type, an external entry records a native
588
+ * Native_Format — so they are kept apart rather than collapsed into `type`,
589
+ * which would put 'raw-log' in a field whose vocabulary is the seven document
590
+ * types. Optional so an omitted field behaves like Go's zero-valued string. */
591
+ format?: string;
592
592
  }
593
593
  /** The verification outcome for one content entry. */
594
594
  interface ChecksumResult {
595
595
  uri: string;
596
596
  type: string;
597
+ /** Mirrors `EvidenceContent.format`: set for an `externalEvidence[]` entry,
598
+ * absent for a `contents[]` one, so a caller can report what an artifact is
599
+ * without reading `type`'s Content_Type vocabulary onto it. */
600
+ format?: string;
601
+ /** The algorithm this entry's checksum is recorded under, with an unstated one
602
+ * reported as the sha256 it defaults to. Absent for a skipped entry — one with no
603
+ * checksum VALUE to verify, whether it carries no checksum at all or one whose
604
+ * value is blank (Checksum.value has no minLength, so a blank value is
605
+ * schema-valid and may still name an algorithm). Nothing was hashed in either
606
+ * case, and naming an algorithm would imply a computation that never ran. */
607
+ algorithm?: string;
597
608
  status: ChecksumStatus;
598
609
  expected?: string;
599
610
  actual?: string;
@@ -615,10 +626,24 @@ export declare function parseEvidencePackage(pkg: string): {
615
626
  planRef: string;
616
627
  contents: EvidenceContent[];
617
628
  };
618
- /** Verifies each content entry's sha256 against fetch(uri), preserving entry
619
- * order. No checksum → skipped; a fetch throw → error; hash mismatch → mismatch
620
- * (carrying expected+actual). */
621
- export declare function verifyChecksums(contents: EvidenceContent[], fetch: FetchFn): ChecksumResult[];
629
+ /** Returns the `externalEvidence[]` entries as the same shape `contents[]` parses
630
+ * to, so ONE verification pass covers both arrays. It exists because verify
631
+ * examined `contents[]` only, and a wrong checksum in the other array passed at
632
+ * exit 0 while bundle refused the same package — the two commands disagreeing
633
+ * about one document.
634
+ *
635
+ * Additive on purpose: `verifyChecksums` is reused unchanged on what this returns,
636
+ * so the hashing has one implementation rather than one per array. */
637
+ export declare function parseExternalEvidence(pkg: string): EvidenceContent[];
638
+ /** Verifies each content entry against fetch(uri) using the algorithm the entry
639
+ * recorded, preserving entry order. No checksum → skipped; an algorithm this
640
+ * build cannot compute → unsupported, never mismatch (that would say their evidence
641
+ * changed when it did not) and never error, since the bytes may be intact; a fetch throw → error;
642
+ * hash mismatch → mismatch (carrying expected+actual).
643
+ *
644
+ * Asynchronous because the SHA family is hashed through Web Crypto, which is what lets
645
+ * this package bundle for the browser. */
646
+ export declare function verifyChecksums(contents: EvidenceContent[], fetch: FetchFn): Promise<ChecksumResult[]>;
622
647
  /** Extracts assessment baselineRefs from a plan document, deduped in first-seen
623
648
  * order. */
624
649
  export declare function plannedBaselineRefs(plan: string): string[];
@@ -636,6 +661,29 @@ export declare function agentOverridesInPackage(contents: EvidenceContent[], fet
636
661
  * covered when some results baseline shares its name. Missing is sorted so the
637
662
  * outcome is deterministic across languages and runs. */
638
663
  export declare function completeness(planned: string[], covered: string[]): CompletenessResult;
639
- //#endregion
664
+ /**
665
+ * Turns a recorded evidence reference into the path it names.
666
+ *
667
+ * A reference is a uri-reference — the schema says so on both `contents[].uri` and
668
+ * `externalEvidence[].uri` — so its percent-escapes are part of the encoding, not part of
669
+ * the name. The DECODED form is what the reference means. Before this, every consumer
670
+ * treated the value as opaque bytes, so the legal spelling of a filename containing a
671
+ * space failed while the illegal spelling worked: a producer following the declared
672
+ * format wrote a package this toolchain could not read.
673
+ *
674
+ * ORDERING MATTERS AND THE CALLER OWNS IT. Decoding can CREATE a parent traversal —
675
+ * `%2e%2e/x` becomes `../x` and `a%2Fb` gains a separator — so the decoded form, never the
676
+ * raw one, is what a caller must put through its containment check.
677
+ *
678
+ * A value whose percent is not a valid escape cannot be decoded, and that throws rather
679
+ * than being guessed at: falling back to the raw bytes would make resolution depend on
680
+ * whether a filename happens to contain a `%`.
681
+ *
682
+ * Present here even though no TypeScript consumer resolves a reference to a filesystem
683
+ * today — what a reference MEANS is language-independent, and a consumer that starts
684
+ * resolving must not be free to disagree with Go. Pinned across both by
685
+ * `testdata/reference-decode-vectors.json`.
686
+ */
687
+ export declare function decodeReference(uri: string): string;
640
688
  export type { ChecksumResult, ChecksumStatus, CompletenessResult, ComplianceBound, ControlIDMapping, EvidenceContent, FetchFn, FilterAlias, FilterOptions, HdfDocType, InputFormat, LoadResult, Match, MergeResult, MergeSource, MergeWarning, MergeWarningKind, RuleOptions, RulePredicate, SeverityCounts, StatusCounts, ThresholdBound, ThresholdConfig, ThresholdInput, ThresholdRule, ThresholdSeverity, Violation };
641
689
  //# sourceMappingURL=index.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","names":[],"sources":["../src/version.ts","../src/merge.ts","../src/detect.ts","../src/values.ts","../src/vocabulary.ts","../src/query.ts","../src/effective.ts","../src/compliance.ts","../src/rules.ts","../src/loader.ts","../src/evidence.ts"],"mappings":"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"}
1
+ {"version":3,"file":"index.d.ts","names":[],"sources":["../src/version.ts","../src/merge.ts","../src/detect.ts","../src/values.ts","../src/vocabulary.ts","../src/query.ts","../src/effective.ts","../src/compliance.ts","../src/rules.ts","../src/loader.ts","../src/evidence.ts"],"mappings":"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"}
package/dist/index.js CHANGED
@@ -1,10 +1,10 @@
1
- import { computeEffectiveImpact, extractCWEIDs, governingOverrideIndex, impactToSeverity, isGoZeroTime, parseTimestamp, validateInputSize, worstStatus } from "@mitre/hdf-utilities";
1
+ import { computeEffectiveImpact, extractCWEIDs, generateHash, governingOverrideIndex, impactToSeverity, isGoZeroTime, parseTimestamp, validateInputSize, worstStatus } from "@mitre/hdf-utilities";
2
2
  import { parseBaseline, parseResults } from "@mitre/hdf-parsers";
3
- import { createHash } from "node:crypto";
4
- //#region src/version.ts
5
- const engineVersion = "3.7.2";
6
- //#endregion
7
- //#region src/merge.ts
3
+ import { blake3 } from "@noble/hashes/blake3.js";
4
+ import { bytesToHex } from "@noble/hashes/utils.js";
5
+ // src/version.ts
6
+ const engineVersion = "3.8.0-next.42533588944.1";
7
+ // src/merge.ts
8
8
  /** Provenance label keys written on every merged baseline (ADR-0016 §3). */
9
9
  const LABEL_TOOL = "tool";
10
10
  const LABEL_TOOL_VERSION = "toolVersion";
@@ -72,10 +72,10 @@ function merge(sources) {
72
72
  results: {
73
73
  baselines,
74
74
  ...components.length > 0 ? { components } : {},
75
- extensions: { [MERGE_EXTENSION_KEY]: {
75
+ extensions: { passthrough: { [MERGE_EXTENSION_KEY]: {
76
76
  version: engineVersion,
77
77
  sources: provenance
78
- } },
78
+ } } },
79
79
  generator: {
80
80
  name: MERGE_GENERATOR_NAME,
81
81
  version: engineVersion
@@ -117,7 +117,7 @@ function millis(ts) {
117
117
  function toolVersion(doc) {
118
118
  return (doc.tool?.version ?? "").trim();
119
119
  }
120
- /** One input's root metadata, verbatim, for extensions["hdf-merge"].sources[]. */
120
+ /** One input's root metadata, verbatim, for extensions.passthrough["hdf-merge"].sources[]. */
121
121
  function sourceProvenance(index, src) {
122
122
  const entry = {
123
123
  index,
@@ -129,8 +129,7 @@ function sourceProvenance(index, src) {
129
129
  if (src.doc.runner !== void 0) entry.runner = src.doc.runner;
130
130
  return entry;
131
131
  }
132
- //#endregion
133
- //#region src/detect.ts
132
+ // src/detect.ts
134
133
  /**
135
134
  * Detect fingerprints an HDF document by its root keys and returns the schema
136
135
  * type string, or '' when the input is not a JSON object or matches no known
@@ -156,8 +155,7 @@ function detect(input) {
156
155
  if (has("requirements")) return "baseline";
157
156
  return "";
158
157
  }
159
- //#endregion
160
- //#region src/effective.ts
158
+ // src/effective.ts
161
159
  /**
162
160
  * Maps a requirement's schema overrides onto the shared helper's neutral shape,
163
161
  * whose timestamps are the RFC3339 strings the schema's Date fields came from.
@@ -200,8 +198,7 @@ function effectiveImpactOf(control, now) {
200
198
  overrides: overrideInputs(control)
201
199
  }, now);
202
200
  }
203
- //#endregion
204
- //#region src/compliance.ts
201
+ // src/compliance.ts
205
202
  /** Threshold status-key constants (SAF CLI-compatible keys). */
206
203
  const THRESHOLD_PASSED = "passed";
207
204
  const THRESHOLD_FAILED = "failed";
@@ -701,8 +698,7 @@ function checkSeverityThreshold(status, threshold, actual, actualControls, wrote
701
698
  check("total", threshold.total, actual.total);
702
699
  return violations;
703
700
  }
704
- //#endregion
705
- //#region src/vocabulary.ts
701
+ // src/vocabulary.ts
706
702
  /**
707
703
  * The closed vocabulary a status filter may name: the schema's Result_Status
708
704
  * enum. It is the EFFECTIVE status that is compared — the resolver a caller
@@ -817,8 +813,7 @@ function normalizeFilterValue(field, value) {
817
813
  default: return value;
818
814
  }
819
815
  }
820
- //#endregion
821
- //#region src/safematch.ts
816
+ // src/safematch.ts
822
817
  const MAX_PATTERN_LENGTH = 256;
823
818
  const REGEX_SPECIAL = /* @__PURE__ */ new Set([
824
819
  ".",
@@ -871,8 +866,7 @@ function safeGlobMatch(s, pattern) {
871
866
  }
872
867
  return re.test(s);
873
868
  }
874
- //#endregion
875
- //#region src/values.ts
869
+ // src/values.ts
876
870
  /** Whether the field constrains anything at all. */
877
871
  function valuesActive(v) {
878
872
  return v !== void 0 && (v.in.length > 0 || v.not.length > 0);
@@ -922,8 +916,7 @@ function normalizeValues(raw) {
922
916
  }
923
917
  throw new Error("a predicate value is a value, a list, or {not: ...}");
924
918
  }
925
- //#endregion
926
- //#region src/query.ts
919
+ // src/query.ts
927
920
  /**
928
921
  * filter returns the requirements across the result set's baselines that satisfy
929
922
  * options. Applies to requirement collections (results/baseline documents); the
@@ -1275,8 +1268,7 @@ function parseKevFilter(s) {
1275
1268
  default: return;
1276
1269
  }
1277
1270
  }
1278
- //#endregion
1279
- //#region src/rules.ts
1271
+ // src/rules.ts
1280
1272
  /**
1281
1273
  * Maps a predicate onto the engine filter. Every field is a pass-through: the
1282
1274
  * point of reusing the vocabulary is that there is nothing to translate, and a
@@ -1350,8 +1342,7 @@ function evaluate(config, input) {
1350
1342
  statusOf: input.statusOf
1351
1343
  }));
1352
1344
  }
1353
- //#endregion
1354
- //#region src/loader.ts
1345
+ // src/loader.ts
1355
1346
  /**
1356
1347
  * load is the schema-typed loader core. In order: validateInputSize (FIRST,
1357
1348
  * before any parse; maxSize <= 0 uses the default), wire-format detection
@@ -1402,8 +1393,7 @@ function isCompleteJSON(s) {
1402
1393
  return false;
1403
1394
  }
1404
1395
  }
1405
- //#endregion
1406
- //#region src/evidence.ts
1396
+ // src/evidence.ts
1407
1397
  /** Go decodes into a typed struct, so a JSON `null` document leaves zero values
1408
1398
  * while a wrong-typed one is a decode error. These three helpers give the TS
1409
1399
  * peer the same split instead of asserting a shape onto untrusted input. */
@@ -1433,10 +1423,13 @@ function parseEvidencePackage(pkg) {
1433
1423
  const doc = parseDocument(pkg, "evidence package");
1434
1424
  const contents = objectArray(doc.contents, "evidence package", "contents").map((c) => {
1435
1425
  const checksum = c.checksum;
1426
+ const isObject = typeof checksum === "object" && checksum !== null;
1436
1427
  return {
1437
1428
  uri: str(c.uri),
1438
1429
  type: str(c.type),
1439
- checksum: typeof checksum === "object" && checksum !== null ? str(checksum.value) : ""
1430
+ checksum: isObject ? str(checksum.value) : "",
1431
+ checksumAlgorithm: isObject ? str(checksum.algorithm) : "",
1432
+ checksumRecorded: isObject
1440
1433
  };
1441
1434
  });
1442
1435
  return {
@@ -1444,39 +1437,76 @@ function parseEvidencePackage(pkg) {
1444
1437
  contents
1445
1438
  };
1446
1439
  }
1447
- /** Verifies each content entry's sha256 against fetch(uri), preserving entry
1448
- * order. No checksum → skipped; a fetch throw → error; hash mismatch → mismatch
1449
- * (carrying expected+actual). */
1450
- function verifyChecksums(contents, fetch) {
1451
- return contents.map((c) => {
1452
- const r = {
1453
- uri: c.uri,
1454
- type: c.type,
1455
- status: "skipped"
1456
- };
1457
- if (c.checksum === "") return r;
1458
- let data;
1459
- try {
1460
- data = fetch(c.uri);
1461
- } catch (e) {
1462
- return {
1463
- ...r,
1464
- status: "error",
1465
- error: e instanceof Error ? e.message : String(e)
1466
- };
1467
- }
1468
- const actual = sha256Hex(data);
1469
- if (actual === c.checksum) return {
1470
- ...r,
1471
- status: "match"
1440
+ /** Returns the `externalEvidence[]` entries as the same shape `contents[]` parses
1441
+ * to, so ONE verification pass covers both arrays. It exists because verify
1442
+ * examined `contents[]` only, and a wrong checksum in the other array passed at
1443
+ * exit 0 while bundle refused the same package — the two commands disagreeing
1444
+ * about one document.
1445
+ *
1446
+ * Additive on purpose: `verifyChecksums` is reused unchanged on what this returns,
1447
+ * so the hashing has one implementation rather than one per array. */
1448
+ function parseExternalEvidence(pkg) {
1449
+ return objectArray(parseDocument(pkg, "evidence package").externalEvidence, "evidence package", "externalEvidence").map((e) => {
1450
+ const checksum = e.checksum;
1451
+ const isObject = typeof checksum === "object" && checksum !== null;
1452
+ return {
1453
+ uri: str(e.uri),
1454
+ type: "",
1455
+ format: str(e.format),
1456
+ checksum: isObject ? str(checksum.value) : "",
1457
+ checksumAlgorithm: isObject ? str(checksum.algorithm) : "",
1458
+ checksumRecorded: isObject
1472
1459
  };
1460
+ });
1461
+ }
1462
+ /** Verifies each content entry against fetch(uri) using the algorithm the entry
1463
+ * recorded, preserving entry order. No checksum → skipped; an algorithm this
1464
+ * build cannot compute → unsupported, never mismatch (that would say their evidence
1465
+ * changed when it did not) and never error, since the bytes may be intact; a fetch throw → error;
1466
+ * hash mismatch → mismatch (carrying expected+actual).
1467
+ *
1468
+ * Asynchronous because the SHA family is hashed through Web Crypto, which is what lets
1469
+ * this package bundle for the browser. */
1470
+ async function verifyChecksums(contents, fetch) {
1471
+ const results = [];
1472
+ for (const c of contents) results.push(await verifyChecksum(c, fetch));
1473
+ return results;
1474
+ }
1475
+ async function verifyChecksum(c, fetch) {
1476
+ const r = {
1477
+ uri: c.uri,
1478
+ type: c.type,
1479
+ status: "skipped"
1480
+ };
1481
+ if (c.format !== void 0 && c.format !== "") r.format = c.format;
1482
+ if (c.checksum === "") return r;
1483
+ r.algorithm = effectiveAlgorithm(c.checksumAlgorithm);
1484
+ if (!supportedAlgorithm(c.checksumAlgorithm)) return {
1485
+ ...r,
1486
+ status: "unsupported",
1487
+ error: unsupportedAlgorithmMessage(c.checksumAlgorithm)
1488
+ };
1489
+ let data;
1490
+ try {
1491
+ data = fetch(c.uri);
1492
+ } catch (e) {
1473
1493
  return {
1474
1494
  ...r,
1475
- status: "mismatch",
1476
- expected: c.checksum,
1477
- actual
1495
+ status: "error",
1496
+ error: e instanceof Error ? e.message : String(e)
1478
1497
  };
1479
- });
1498
+ }
1499
+ const actual = await checksumHex(c.checksumAlgorithm, data);
1500
+ if (actual === c.checksum) return {
1501
+ ...r,
1502
+ status: "match"
1503
+ };
1504
+ return {
1505
+ ...r,
1506
+ status: "mismatch",
1507
+ expected: c.checksum,
1508
+ actual
1509
+ };
1480
1510
  }
1481
1511
  /** Extracts assessment baselineRefs from a plan document, deduped in first-seen
1482
1512
  * order. */
@@ -1542,8 +1572,74 @@ function completeness(planned, covered) {
1542
1572
  complete: missing.length === 0
1543
1573
  };
1544
1574
  }
1545
- function sha256Hex(data) {
1546
- return createHash("sha256").update(data).digest("hex");
1575
+ /** The algorithms this build can verify — every value Hash_Algorithm admits. An
1576
+ * algorithm outside the enum is refused by name rather than silently treated as
1577
+ * something else. Kept identical to Go's ChecksumHex. */
1578
+ const SUPPORTED_ALGORITHMS = [
1579
+ "sha256",
1580
+ "sha384",
1581
+ "sha512",
1582
+ "blake3"
1583
+ ];
1584
+ /** Names the algorithm an entry's checksum is verified under: an unstated
1585
+ * algorithm means sha256, so reporting '' would understate it. */
1586
+ function effectiveAlgorithm(recorded) {
1587
+ return !recorded ? "sha256" : recorded;
1588
+ }
1589
+ function supportedAlgorithm(algorithm) {
1590
+ return !algorithm || SUPPORTED_ALGORITHMS.includes(algorithm);
1591
+ }
1592
+ /** Formats the algorithm list exactly as Go's ChecksumHex does, so the two languages
1593
+ * emit the SAME user-visible refusal rather than two spellings of it. */
1594
+ function algorithmList() {
1595
+ const all = SUPPORTED_ALGORITHMS;
1596
+ return `${all.slice(0, -1).join(", ")} and ${all[all.length - 1]}`;
1597
+ }
1598
+ function unsupportedAlgorithmMessage(algorithm) {
1599
+ return `unsupported checksum algorithm "${algorithm}": this build computes ${algorithmList()}`;
1600
+ }
1601
+ /** Hashes data with the named Hash_Algorithm, hex-encoded. An empty algorithm
1602
+ * means sha256, so a package that records only a value keeps its meaning. Rejects
1603
+ * an algorithm this build cannot compute.
1604
+ *
1605
+ * The SHA family goes through the shared Web Crypto helper rather than node:crypto,
1606
+ * which is what lets this package bundle for the browser; blake3 has no Web Crypto
1607
+ * equivalent and keeps its own implementation. */
1608
+ async function checksumHex(algorithm, data) {
1609
+ if (!supportedAlgorithm(algorithm)) throw new Error(unsupportedAlgorithmMessage(algorithm));
1610
+ if (algorithm === "blake3") return bytesToHex(blake3(data));
1611
+ return generateHash(data, { algorithm: !algorithm ? "sha256" : algorithm });
1612
+ }
1613
+ /**
1614
+ * Turns a recorded evidence reference into the path it names.
1615
+ *
1616
+ * A reference is a uri-reference — the schema says so on both `contents[].uri` and
1617
+ * `externalEvidence[].uri` — so its percent-escapes are part of the encoding, not part of
1618
+ * the name. The DECODED form is what the reference means. Before this, every consumer
1619
+ * treated the value as opaque bytes, so the legal spelling of a filename containing a
1620
+ * space failed while the illegal spelling worked: a producer following the declared
1621
+ * format wrote a package this toolchain could not read.
1622
+ *
1623
+ * ORDERING MATTERS AND THE CALLER OWNS IT. Decoding can CREATE a parent traversal —
1624
+ * `%2e%2e/x` becomes `../x` and `a%2Fb` gains a separator — so the decoded form, never the
1625
+ * raw one, is what a caller must put through its containment check.
1626
+ *
1627
+ * A value whose percent is not a valid escape cannot be decoded, and that throws rather
1628
+ * than being guessed at: falling back to the raw bytes would make resolution depend on
1629
+ * whether a filename happens to contain a `%`.
1630
+ *
1631
+ * Present here even though no TypeScript consumer resolves a reference to a filesystem
1632
+ * today — what a reference MEANS is language-independent, and a consumer that starts
1633
+ * resolving must not be free to disagree with Go. Pinned across both by
1634
+ * `testdata/reference-decode-vectors.json`.
1635
+ */
1636
+ function decodeReference(uri) {
1637
+ if (uri === "") return "";
1638
+ try {
1639
+ return decodeURIComponent(uri);
1640
+ } catch {
1641
+ throw new Error(`reference ${JSON.stringify(uri)} is not a valid uri-reference`);
1642
+ }
1547
1643
  }
1548
1644
  function dedupe(input) {
1549
1645
  const seen = /* @__PURE__ */ new Set();
@@ -1554,7 +1650,6 @@ function dedupe(input) {
1554
1650
  }
1555
1651
  return out;
1556
1652
  }
1557
- //#endregion
1558
- export { LABEL_SOURCE_DOCUMENT, LABEL_TOOL, LABEL_TOOL_VERSION, SEVERITY_VALUES, STATUS_VALUES, addCounts, advertisedFilterValues, agentOverrideCount, agentOverridesInPackage, calculateCompliance, completeness, countControlsByStatus, countControlsByStatusSeverity, coveredBaselineNames, coveredBaselinesInPackage, deriveSeverity, detect, detectFormat, effectiveImpactOf, engineVersion, evaluate, evaluateRules, filter, filterAliases, filterValues, load, mapControlIDs, mapControlIDsByStatus, merge, normalizeFilterValue, normalizeKey, normalizeThresholdConfig, overallStatus, overrideInputs, parseEvidencePackage, plannedBaselineRefs, ruleRefusal, severityBucket, severityTotals, validSeverity, validStatus, validateGrid, validateThresholds, verifyChecksums, violationMessages };
1653
+ export { LABEL_SOURCE_DOCUMENT, LABEL_TOOL, LABEL_TOOL_VERSION, SEVERITY_VALUES, STATUS_VALUES, addCounts, advertisedFilterValues, agentOverrideCount, agentOverridesInPackage, calculateCompliance, completeness, countControlsByStatus, countControlsByStatusSeverity, coveredBaselineNames, coveredBaselinesInPackage, decodeReference, deriveSeverity, detect, detectFormat, effectiveImpactOf, engineVersion, evaluate, evaluateRules, filter, filterAliases, filterValues, load, mapControlIDs, mapControlIDsByStatus, merge, normalizeFilterValue, normalizeKey, normalizeThresholdConfig, overallStatus, overrideInputs, parseEvidencePackage, parseExternalEvidence, plannedBaselineRefs, ruleRefusal, severityBucket, severityTotals, validSeverity, validStatus, validateGrid, validateThresholds, verifyChecksums, violationMessages };
1559
1654
 
1560
1655
  //# sourceMappingURL=index.js.map