feat: add ExternalReferences[].hashes (#985)

fixes #984

---------

Signed-off-by: Jan Kowalleck <[email protected]>

Author: jkowalleck

HISTORY.md

@@ -4,12 +4,18 @@ All notable changes to this project will be documented in this file.
 
 ## unreleased
 
+* Added
+  * Class `Models.ExternalReference` got a new property `hashes` ([#984] via [#985])
+  * Serializers and `ExternalReference`-Normalizers will take `Models.ExternalReference.hashes` into account ([#984] via [#985])
+
 * Build
   * Use _Webpack_ `v5.89.0` now, was `v5.88.2` (via [#979])
   * Use _ts-loader_ `v9.5.0` now, was `v9.4.4` (via [#977])
 
 [#977]: https://github.com/CycloneDX/cyclonedx-javascript-library/pull/977
 [#979]: https://github.com/CycloneDX/cyclonedx-javascript-library/pull/979 
+[#984]: https://github.com/CycloneDX/cyclonedx-javascript-library/issues/984
+[#985]: https://github.com/CycloneDX/cyclonedx-javascript-library/pull/985
 
 ## 6.0.0 -- 2023-08-26
 

src/models/externalReference.ts

@@ -21,19 +21,23 @@ import type { Comparable } from '../_helpers/sortable'
 import { SortableComparables } from '../_helpers/sortable'
 import type { ExternalReferenceType } from '../enums'
 import type { BomLink } from './bomLink'
+import { HashDictionary } from './hash'
 
 export interface OptionalExternalReferenceProperties {
+  hashes?: ExternalReference['hashes']
   comment?: ExternalReference['comment']
 }
 
 export class ExternalReference implements Comparable<ExternalReference> {
   url: URL | BomLink | string
   type: ExternalReferenceType
+  hashes: HashDictionary
   comment?: string
 
   constructor (url: ExternalReference['url'], type: ExternalReference['type'], op: OptionalExternalReferenceProperties = {}) {
     this.url = url
     this.type = type
+    this.hashes = op.hashes ?? new HashDictionary()
     this.comment = op.comment
   }
 

src/serialize/json/normalize.ts

@@ -516,6 +516,9 @@ export class ExternalReferenceNormalizer extends BaseJsonNormalizer<Models.Exter
       ? {
           url: data.url.toString(),
           type: data.type,
+          hashes: this._factory.spec.supportsExternalReferenceHashes && data.hashes.size > 0
+            ? this._factory.makeForHash().normalizeIterable(data.hashes, options)
+            : undefined,
           comment: data.comment || undefined
         }
       : undefined

src/serialize/json/types.ts

@@ -202,6 +202,7 @@ export namespace Normalized {
   export interface ExternalReference {
     url: JsonSchema.IriReference | BomLink
     type: Enums.ExternalReferenceType
+    hashes?: Hash[]
     comment?: string
   }
 

src/serialize/xml/normalize.ts

@@ -642,6 +642,13 @@ export class SWIDNormalizer extends BaseXmlNormalizer<Models.SWID> {
 export class ExternalReferenceNormalizer extends BaseXmlNormalizer<Models.ExternalReference> {
   normalize (data: Models.ExternalReference, options: NormalizerOptions, elementName: string): SimpleXml.Element | undefined {
     const url = data.url.toString()
+    const hashes: SimpleXml.Element | undefined = this._factory.spec.supportsExternalReferenceHashes && data.hashes.size > 0
+      ? {
+          type: 'element',
+          name: 'hashes',
+          children: this._factory.makeForHash().normalizeIterable(data.hashes, options, 'hash')
+        }
+      : undefined
     return this._factory.spec.supportsExternalReferenceType(data.type) &&
     XmlSchema.isAnyURI(url)
       ? {
@@ -652,7 +659,8 @@ export class ExternalReferenceNormalizer extends BaseXmlNormalizer<Models.Extern
           },
           children: [
             makeTextElement(url, 'url'),
-            makeOptionalTextElement(data.comment, 'comment')
+            makeOptionalTextElement(data.comment, 'comment'),
+            hashes
           ].filter(isNotUndefined)
         }
       : undefined

src/spec/_protocol.ts

@@ -43,6 +43,7 @@ export interface _SpecProtocol {
   supportsVulnerabilityRatingMethod: (rm: Vulnerability.RatingMethod | any) => boolean
   supportsComponentEvidence: boolean
   supportsMetadataLifecycles: boolean
+  supportsExternalReferenceHashes: boolean
 }
 
 /**
@@ -67,6 +68,7 @@ export class _Spec implements _SpecProtocol {
   readonly #supportsVulnerabilities: boolean
   readonly #supportsComponentEvidence: boolean
   readonly #supportsMetadataLifecycles: boolean
+  readonly #supportsExternalReferenceHashes: boolean
 
   constructor (
     version: Version,
@@ -82,7 +84,8 @@ export class _Spec implements _SpecProtocol {
     supportsVulnerabilities: boolean,
     vulnerabilityRatingMethods: Iterable<Vulnerability.RatingMethod>,
     supportsComponentEvidence: boolean,
-    supportsMetadataLifecycles: boolean
+    supportsMetadataLifecycles: boolean,
+    supportsExternalReferenceHashes: boolean
   ) {
     this.#version = version
     this.#formats = new Set(formats)
@@ -98,6 +101,7 @@ export class _Spec implements _SpecProtocol {
     this.#vulnerabilityRatingMethods = new Set(vulnerabilityRatingMethods)
     this.#supportsComponentEvidence = supportsComponentEvidence
     this.#supportsMetadataLifecycles = supportsMetadataLifecycles
+    this.#supportsExternalReferenceHashes = supportsExternalReferenceHashes
   }
 
   get version (): Version {
@@ -157,4 +161,8 @@ export class _Spec implements _SpecProtocol {
   get supportsMetadataLifecycles (): boolean {
     return this.#supportsMetadataLifecycles
   }
+
+  get supportsExternalReferenceHashes (): boolean {
+    return this.#supportsExternalReferenceHashes
+  }
 }

src/spec/consts.ts

@@ -78,6 +78,7 @@ export const Spec1dot2: Readonly<_SpecProtocol> = Object.freeze(new _Spec(
   false,
   [],
   false,
+  false,
   false
 ))
 
@@ -137,7 +138,8 @@ export const Spec1dot3: Readonly<_SpecProtocol> = Object.freeze(new _Spec(
   false,
   [],
   true,
-  false
+  false,
+  true
 ))
 
 /** Specification v1.4 */
@@ -203,7 +205,8 @@ export const Spec1dot4: Readonly<_SpecProtocol> = Object.freeze(new _Spec(
     Vulnerability.RatingMethod.Other
   ],
   true,
-  false
+  false,
+  true
 ))
 
 /** Specification v1.5 */
@@ -298,6 +301,7 @@ export const Spec1dot5: Readonly<_SpecProtocol> = Object.freeze(new _Spec(
     Vulnerability.RatingMethod.Other
   ],
   true,
+  true,
   true
 ))
 

tests/_data/models.js

@@ -107,6 +107,17 @@ module.exports.createComplexStructure = function () {
       new URL('https://localhost/acme/support'),
       Enums.ExternalReferenceType.Support
     ))
+    component.externalReferences.add(new Models.ExternalReference(
+      'https://localhost/download/acme.tar.gz',
+      Enums.ExternalReferenceType.Distribution,
+      {
+        hashes: new Models.HashDictionary([
+          [Enums.HashAlgorithm.MD5, '327b6f07435811239bc47e1544353273'],
+          [Enums.HashAlgorithm['SHA-1'], 'd53a205a336e07cf9eac45471b3870f9489288ec'],
+          [Enums.HashAlgorithm['SHA-256'], '1f2ec52b774368781bed1d1fb140a92e0eb6348090619c9291f9a5a3c8e8d151']
+        ])
+      }
+    ))
     component.externalReferences.add(new Models.ExternalReference(
       'git+https://localhost/acme.git',
       Enums.ExternalReferenceType.VCS