Serial number (#597)

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

Author: jkowalleck

HISTORY.md

@@ -4,6 +4,22 @@ All notable changes to this project will be documented in this file.
 
 ## unreleased
 
+* Fixed
+  * "Bom.serialNumber" data model can have values following the alternative format allowed in CycloneDX XML specification ([#588] via [#])
+  * `Serialize.{JSON,XML}.Normalize.BomNormalizer.normalize` now omits invalid/unsupported values for serialNumber ([#588] via [#])
+* Changed
+  * Property `Models.Bom.serialNumber` is of type `string`, was type-aliased `Types.UrnUuid = string` ([#588] via [#])  
+    Also the setter no longer throws exceptions, since no string format is illegal.  
+    This is considered a non-breaking behaviour change, because the corresponding normalizers assure valid data results.
+* Added
+  * Bom serialNumber generator: `Utils.BomUtility.randomSerialNumber()` ([#588] via [#])
+* Deprecation
+  * Type alias `Types.UrnUuid = string` became deprecated (via [#])  
+    Use type `string` instead.
+  * Function `Types.isUrnUuid` became deprecated (via [#])
+
+[#588]: https://github.com/CycloneDX/cyclonedx-javascript-library/issues/588
+
 ## 1.12.2 - 2023-03-28
 
 * Fixed

src/index.common.ts

@@ -22,4 +22,5 @@ export * as Models from './models'
 export * as SPDX from './spdx'
 export * as Spec from './spec'
 export * as Types from './types'
+export * as Utils from './utils'
 // do not export the _helpers, they are for internal use only

src/models/bom.ts

@@ -17,8 +17,8 @@ SPDX-License-Identifier: Apache-2.0
 Copyright (c) OWASP Foundation. All Rights Reserved.
 */
 
-import type { PositiveInteger, UrnUuid } from '../types'
-import { isPositiveInteger, isUrnUuid } from '../types'
+import type { PositiveInteger } from '../types'
+import { isPositiveInteger } from '../types'
 import { ComponentRepository } from './component'
 import { Metadata } from './metadata'
 import { VulnerabilityRepository } from './vulnerability'
@@ -40,7 +40,7 @@ export class Bom {
   #version: PositiveInteger = 1
 
   /** @see {@link serialNumber} */
-  #serialNumber?: UrnUuid
+  #serialNumber?: string
 
   // Property `bomFormat` is not part of model, it is runtime information.
   // Property `specVersion` is not part of model, it is runtime information.
@@ -74,17 +74,13 @@ export class Bom {
     this.#version = value
   }
 
-  get serialNumber (): UrnUuid | undefined {
+  get serialNumber (): string | undefined {
     return this.#serialNumber
   }
 
-  /**
-   * @throws {@link TypeError} if value is neither {@link UrnUuid} nor `undefined`
-   */
-  set serialNumber (value: UrnUuid | undefined) {
-    if (value !== undefined && !isUrnUuid(value)) {
-      throw new TypeError('Not UrnUuid nor undefined')
-    }
-    this.#serialNumber = value
+  set serialNumber (value: string | undefined) {
+    this.#serialNumber = value === ''
+      ? undefined
+      : value
   }
 }

src/serialize/json/normalize.ts

@@ -132,7 +132,9 @@ export class BomNormalizer extends BaseJsonNormalizer<Models.Bom> {
       bomFormat: 'CycloneDX',
       specVersion: this._factory.spec.version,
       version: data.version,
-      serialNumber: data.serialNumber,
+      serialNumber: this.#isEligibleSerialNumber(data.serialNumber)
+        ? data.serialNumber
+        : undefined,
       metadata: this._factory.makeForMetadata().normalize(data.metadata, options),
       components: data.components.size > 0
         ? this._factory.makeForComponent().normalizeIterable(data.components, options)
@@ -143,6 +145,12 @@ export class BomNormalizer extends BaseJsonNormalizer<Models.Bom> {
         : undefined
     }
   }
+
+  #isEligibleSerialNumber (v: string | undefined): boolean {
+    return v !== undefined &&
+      // see https://github.com/CycloneDX/specification/blob/ef71717ae0ecb564c0b4c9536d6e9e57e35f2e69/schema/bom-1.4.schema.json#L39
+      /^urn:uuid:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(v)
+  }
 }
 
 export class MetadataNormalizer extends BaseJsonNormalizer<Models.Metadata> {

src/serialize/json/types.ts

@@ -20,7 +20,7 @@ Copyright (c) OWASP Foundation. All Rights Reserved.
 import type * as Enums from '../../enums'
 import type { HashContent } from '../../models'
 import type { SpdxId } from '../../spdx'
-import type { CPE, Integer, UrnUuid } from '../../types'
+import type { CPE, Integer } from '../../types'
 
 // eslint-disable-next-line @typescript-eslint/no-namespace
 export namespace JsonSchema {
@@ -69,7 +69,7 @@ export namespace Normalized {
     bomFormat: 'CycloneDX'
     specVersion: string
     version: Integer
-    serialNumber?: UrnUuid
+    serialNumber?: string
     metadata?: Metadata
     components?: Component[]
     externalReferences?: ExternalReference[]

src/serialize/xml/normalize.ts

@@ -145,7 +145,9 @@ export class BomNormalizer extends BaseXmlNormalizer<Models.Bom> {
       namespace: xmlNamespace.get(this._factory.spec.version),
       attributes: {
         version: data.version,
-        serialNumber: data.serialNumber
+        serialNumber: this.#isEligibleSerialNumber(data.serialNumber)
+          ? data.serialNumber
+          : undefined
       },
       children: [
         data.metadata
@@ -158,6 +160,12 @@ export class BomNormalizer extends BaseXmlNormalizer<Models.Bom> {
       ].filter(isNotUndefined)
     }
   }
+
+  #isEligibleSerialNumber (v: string | undefined): boolean {
+    return v !== undefined &&
+      // see https://github.com/CycloneDX/specification/blob/ef71717ae0ecb564c0b4c9536d6e9e57e35f2e69/schema/bom-1.4.xsd#L699
+      /^urn:uuid:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$|^\{[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\}$/.test(v)
+  }
 }
 
 export class MetadataNormalizer extends BaseXmlNormalizer<Models.Metadata> {

src/types/urn.ts

@@ -22,12 +22,19 @@ Copyright (c) OWASP Foundation. All Rights Reserved.
  * {@link https://datatracker.ietf.org/doc/html/rfc4122 | RFC 4122}.
  *
  * @see {@link isUrnUuid}
+ *
+ * @deprecated Use `string` instead.
  */
 export type UrnUuid = string
 
-/* regular expression was taken from the CycloneDX schema definitions. */
+/* regular expression was taken from the CycloneDX schema definitions.
+ * see https://github.com/CycloneDX/specification/blob/ef71717ae0ecb564c0b4c9536d6e9e57e35f2e69/schema/bom-1.4.schema.json#L39
+ */
 const urnUuidPattern = /^urn:uuid:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/
 
+/**
+ * @deprecated This function will be removed during next mayor release.
+ */
 export function isUrnUuid (value: any): value is UrnUuid {
   return typeof value === 'string' &&
        urnUuidPattern.test(value)

src/utils/bomUtility.ts

@@ -0,0 +1,33 @@
+/*!
+This file is part of CycloneDX JavaScript Library.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+SPDX-License-Identifier: Apache-2.0
+Copyright (c) OWASP Foundation. All Rights Reserved.
+*/
+export function randomSerialNumber (): string {
+  const b = [
+    Math.round(Math.random() * 0xFFFF),
+    Math.round(Math.random() * 0xFFFF),
+    Math.round(Math.random() * 0xFFFF),
+    // UUID version 4
+    Math.round(Math.random() * 0x0FFF) | 0x4000,
+    // UUID version 4 variant 1
+    Math.round(Math.random() * 0x3FFF) | 0x8000,
+    Math.round(Math.random() * 0xFFFF),
+    Math.round(Math.random() * 0xFFFF),
+    Math.round(Math.random() * 0xFFFF)
+  ].map(n => n.toString(16).padStart(4, '0'))
+  return `urn:uuid:${b[0]}${b[1]}-${b[2]}-${b[3]}-${b[4]}-${b[5]}${b[6]}${b[7]}`
+}

src/utils/index.ts

@@ -0,0 +1,19 @@
+/*!
+This file is part of CycloneDX JavaScript Library.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+SPDX-License-Identifier: Apache-2.0
+Copyright (c) OWASP Foundation. All Rights Reserved.
+*/
+export * as BomUtility from './bomUtility'

tests/unit/Models.Bom.spec.js

@@ -96,4 +96,17 @@ suite('Models.Bom', () => {
       })
     )
   )
+
+  suite('can set serialNumber', () => {
+    test('empty string', () => {
+      const bom = new Bom()
+      bom.serialNumber = ''
+      assert.strictEqual(bom.serialNumber, undefined)
+    })
+    test('something', () => {
+      const bom = new Bom()
+      bom.serialNumber = 'something'
+      assert.strictEqual(bom.serialNumber, 'something')
+    })
+  })
 })

tests/unit/Utils.BomUtility.spec.js

@@ -0,0 +1,40 @@
+/*!
+This file is part of CycloneDX JavaScript Library.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+SPDX-License-Identifier: Apache-2.0
+Copyright (c) OWASP Foundation. All Rights Reserved.
+*/
+
+const assert = require('assert')
+const { suite, test } = require('mocha')
+
+const {
+  Utils: {
+    BomUtility
+  }
+} = require('../../')
+
+suite('Utils.BomUtility', () => {
+  suite('randomSerialNumber()', () => {
+    test('has correct format according to XSD', () => {
+      const value = BomUtility.randomSerialNumber()
+      assert.match(value, /^urn:uuid:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$|^\\{[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\\}$/)
+    })
+    test('has correct format according to JSON schema', () => {
+      const value = BomUtility.randomSerialNumber()
+      assert.match(value, /^urn:uuid:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/)
+    })
+  })
+})