@mitre/hdf-schema 3.6.0-rc.5 → 3.7.0-rc.1

package/README.md

@@ -189,19 +189,25 @@ All schemas use **JSON Schema draft/2020-12**.
 Interactive schema reference documentation is published at:
 **<https://mitre.github.io/hdf-libs/schemas/>**
 
+### What's new in v3.7.0
+
+- **`Milestone.title` — optional single-line label.** A short label on each POA&M `Milestone`, suitable where a consumer needs a title (for example an OSCAL POA&M remediation or task). It is optional and does not replace `description`, which remains the full milestone text; a consumer needing a title where none is supplied derives one. The value carries the project's single-line-label constraint — `minLength: 1` plus a pattern (OSCAL's `StringDatatype`, spelled with explicit character classes so ECMA-262 and Go regexp engines agree) banning line breaks and leading/trailing whitespace.
+- **`Evidence.data` tightened.** `data` now requires `minLength: 1` (an empty evidence body no longer validates), and when `encoding` is exactly `base64` (lowercase) the data must be bare base64 matching `^[0-9A-Za-z+/]+={0,2}$` (OSCAL's `Base64Datatype`): no `data:` URI prefix, URL, or line breaks. **Tightening:** a v3.6.x document with an empty `data`, or with a `base64`-encoded value that carries a `data:` prefix or line breaks, now fails validation — strip the prefix/whitespace or correct the encoding label.
+- **Compatibility.** `Milestone.title` is additive and optional, so a v3.6.x document validates unchanged under v3.7.0. The `Evidence.data` change is a validation tightening, not a structural one: documents whose evidence bodies were already non-empty and (for `base64`) bare validate cleanly; the rest must be corrected. A v3.7.0 document carrying `Milestone.title` will not validate against the v3.6.x schemas, which reject unevaluated properties; strip the field or validate against v3.7.0.
+
 ### What's new in v3.6.0
 
-- **No structural schema changes.** Every document type and primitive is structurally identical to v3.5.x: no fields, enum values, or constraints were added, removed, renamed, or tightened. v3.5.x documents validate unchanged under v3.6.0, and documents produced under v3.6.0 validate against the v3.5.x schemas.
+- **`preAmendmentChecksum` on the Results root.** Optional `Checksum` recording the document's hash as it stood immediately before the most recent amendment application, written by `hdf amend apply`. It covers the results file's raw bytes as read, not a canonical form, and records only the most recent application rather than accumulating. Distinct from the override-level `previousChecksum`, which chains amendments to one another over a canonical form. This is the only structural change in v3.6.0; everything else below is description-level.
 - **`previousChecksum` semantics stated precisely** (description-only, on `Standalone_Override`, `Status_Override`, and the POA&M element) — each amendment's checksum is recorded by the *next* one, so an in-place edit is detectable only for an amendment that has a later one chained to it. The chain is not tamper-proof: the final amendment, the document envelope, deleted trailing amendments, and a wholesale recompute are outside what it can detect; use `signature` for non-repudiation. The field is omitted (not `null`) on the first amendment. This is the contract `hdf amend verify` enforces.
 - **Schema descriptions reflowed into paragraphs** and the source files pretty-printed one value per line. Cosmetic in the source, but the bundled `dist/schemas/` descriptions now carry paragraph breaks, which IDE tooltips render.
 - **`computeEffectiveStatus` helper delegates to the canonical status ladder** in `@mitre/hdf-utilities`. **Behavior change** for `@mitre/hdf-schema/helpers` consumers: the helper no longer returns a pre-set `effectiveStatus` verbatim, and it now applies the governing non-expired `statusOverrides` entry and the error roll-up ahead of the impact-0 `notApplicable` short-circuit, matching the CLI and converters.
 - **`@mitre/hdf-schema/testhdf` sub-path export** — test-only builders (`req`, `baseline`, `doc`, `results`, `baselineDoc`, `override`, `amendments`, `system`, `plan`, `evidencePackage`, `changeEvent`, `comparison`, and friends) that construct schema-valid documents for downstream test suites, with a Go counterpart at `github.com/mitre/hdf-libs/hdf-schema/testhdf/go`.
-- **Compatibility.** Fully compatible in both directions at the schema level. The only behavior change is in the `computeEffectiveStatus` helper above.
+- **Compatibility.** The one schema addition is optional, so v3.5.x documents validate unchanged under v3.6.0. A v3.6.0 document carrying `preAmendmentChecksum` will not validate against the v3.5.x schemas, which reject unevaluated properties; strip the field or validate against v3.6.0.
 
 ### What's new in v3.5.0
 
-- **`hdf-requirement-change-event` document type** — a new schema for the continuous-monitoring change-event stream (ADR-0005): per-requirement events (`new`/`absent`/`updated`/`fixed`/`regressed`) with a full after-state, thin before-state, and per-key sequence, chained for deterministic replay from a seed. Produced by `hdf events derive`.
-- **`External_Reference` primitive + `externalReferences[]` wiring** — a generalized, STIX-2.1-aligned reference (required `sourceName` plus one of `externalId`/`href`/`description`, open `rel`/`kind`, optional lossless embedded `document`) wired across the document types, including on the inline `Status_Override`. Backs the STIX CTI enrichment feature (ADR-0006).
+- **`hdf-requirement-change-event` document type** — a new schema for the continuous-monitoring change-event stream: per-requirement events (`new`/`absent`/`updated`/`fixed`/`regressed`) with a full after-state, thin before-state, and per-key sequence, chained for deterministic replay from a seed. Produced by `hdf events derive`.
+- **`External_Reference` primitive + `externalReferences[]` wiring** — a generalized, STIX-2.1-aligned reference (required `sourceName` plus one of `externalId`/`href`/`description`, open `rel`/`kind`, optional lossless embedded `document`) wired across the document types, including on the inline `Status_Override`. Backs the STIX CTI enrichment feature.
 - **`Change_Reason` gains `dispositionChanged` and `effectiveImpactChanged`** — the diff engine's amendment-axis change reasons are now part of the comparison vocabulary.
 - **POA&M `expiresAt` is now required** — a POA&M is a time-boxed acceptance of an open finding; the deadline is no longer optional. **Breaking:** previously-valid HDF documents with deadline-less POA&Ms now fail validation. Source a real remediation/vendor-fix date.
 - **Compatibility.** The additions are additive except the required POA&M `expiresAt`; v3.4.x documents without deadline-less POA&Ms validate cleanly under v3.5.0. See CHANGELOG.

package/dist/go/hdf.go

@@ -141,6 +141,16 @@ type HDFResults struct {
 	// Reference to an hdf-plan document describing the assessment plan that produced these                            
 	// results. May be a relative path, absolute URI, or fragment identifier.                                          
 	PlanRef                                                                                     *string                `json:"planRef,omitempty"`
+	// Hash of this results document as it stood immediately before the most recent amendment                          
+	// application. Written by `hdf amend apply` when it applies at least one override; an apply                       
+	// that matches nothing leaves the document untouched. The hash covers the results file's                          
+	// RAW BYTES as read, not a canonical form, so reproducing it requires the byte-identical                          
+	// original — reformatting or re-serializing the source changes the value. Only the most                           
+	// recent pre-application state is recorded: applying amendments to an already-amended                             
+	// document REPLACES this value, so it is a single link back one step, not a growing chain.                        
+	// Distinct from the `previousChecksum` inside an override, which chains amendments to each                        
+	// other and is computed over a canonical JSON form.                                                               
+	PreAmendmentChecksum                                                                        *Checksum              `json:"preAmendmentChecksum,omitempty"`
 	// Optional reference to automated remediation resources (Ansible playbooks, Terraform                             
 	// scripts, etc.) for fixing failing requirements found in this assessment.                                        
 	Remediation                                                                                 *Remediation           `json:"remediation,omitempty"`
@@ -647,11 +657,14 @@ type Evidence struct {
 	// Identity of who or what captured this evidence.                                                     
 	CapturedBy                                                                                *Identity    `json:"capturedBy,omitempty"`
 	// The evidence content. For screenshots/files: base64-encoded data or URL. For code/logs:             
-	// the raw text. For URLs: the URL string.                                                             
+	// the raw text. For URLs: the URL string. Must not be empty. When encoding is 'base64',               
+	// data must be bare base64 matching ^[0-9A-Za-z+/]+={0,2}$ (OSCAL's Base64Datatype): no               
+	// data: URI prefix, URL, or line breaks.                                                              
 	Data                                                                                      string       `json:"data"`
 	// Human-readable description of what this evidence shows.                                             
 	Description                                                                               *string      `json:"description,omitempty"`
-	// Encoding used for the data. Example: 'base64', 'utf-8'.                                             
+	// Encoding used for the data. Example: 'base64', 'utf-8'. The value 'base64' (exactly,                
+	// lowercase) requires data to be bare base64.                                                         
 	Encoding                                                                                  *string      `json:"encoding,omitempty"`
 	// MIME type of the evidence. Example: 'image/png', 'text/plain', 'application/json'.                  
 	MIMEType                                                                                  *string      `json:"mimeType,omitempty"`
@@ -716,16 +729,21 @@ type PoamElement struct {
 
 // A milestone or task within a POA&M remediation plan.
 type Milestone struct {
-	// Actual completion timestamp. ISO 8601 format.                
-	CompletedAt                                     *time.Time      `json:"completedAt,omitempty"`
-	// Identity of who completed this milestone.                    
-	CompletedBy                                     *Identity       `json:"completedBy,omitempty"`
-	// Description of this milestone or task.                       
-	Description                                     string          `json:"description"`
-	// Estimated completion date. ISO 8601 format.                  
-	EstimatedCompletion                             time.Time       `json:"estimatedCompletion"`
-	// Current status of this milestone.                            
-	Status                                          MilestoneStatus `json:"status"`
+	// Actual completion timestamp. ISO 8601 format.                                                           
+	CompletedAt                                                                                *time.Time      `json:"completedAt,omitempty"`
+	// Identity of who completed this milestone.                                                               
+	CompletedBy                                                                                *Identity       `json:"completedBy,omitempty"`
+	// Description of this milestone or task.                                                                  
+	Description                                                                                string          `json:"description"`
+	// Estimated completion date. ISO 8601 format.                                                             
+	EstimatedCompletion                                                                        time.Time       `json:"estimatedCompletion"`
+	// Current status of this milestone.                                                                       
+	Status                                                                                     MilestoneStatus `json:"status"`
+	// Short single-line label for this milestone, suitable where a consumer needs a title (for                
+	// example an OSCAL POA&M remediation or task). No line breaks, and no leading or trailing                 
+	// whitespace. The description remains the full text of the milestone; the title does not                  
+	// replace it.                                                                                             
+	Title                                                                                      *string         `json:"title,omitempty"`
 }
 
 // A digital signature following W3C Data Integrity Proofs pattern. Supports hardware security