feat: guarantee correct URL (#996)

Serialization/normalization guarantees valid URI values according to JSON/XML specification

fixes #992
---------

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

Author: 3 people

HISTORY.md

@@ -4,6 +4,12 @@ All notable changes to this project will be documented in this file.
 
 ## unreleased
 
+* Changed
+  * Serialization/normalization guarantees valid URI values according to JSON/XML specification ([#992] via [#996])
+
+[#992]: https://github.com/CycloneDX/cyclonedx-javascript-library/issues/992
+[#996]: https://github.com/CycloneDX/cyclonedx-javascript-library/pull/996
+
 ## 6.1.3 -- 2023-12-09
 
 * Fixed

src/_helpers/uri.ts

@@ -0,0 +1,51 @@
+/*!
+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 escapeMap: Readonly<Record<string, string>> = Object.freeze({
+  ' ': '%20',
+  '[': '%5B',
+  ']': '%5D',
+  '<': '%3C',
+  '>': '%3E',
+  '{': '%7B',
+  '}': '%7D'
+})
+
+/**
+ * Make a string valid to
+ * - XML::anyURI spec.
+ * - JSON::iri-reference spec.
+ *
+ * BEST EFFORT IMPLEMENTATION
+ *
+ * @see http://www.w3.org/TR/xmlschema-2/#anyURI
+ * @see http://www.datypic.com/sc/xsd/t-xsd_anyURI.html
+ * @see https://datatracker.ietf.org/doc/html/rfc2396
+ * @see https://datatracker.ietf.org/doc/html/rfc3987
+ */
+export function escapeUri<T extends (string | undefined)> (value: T): T {
+  if (value === undefined) {
+    return value
+  }
+  for (const [s, r] of Object.entries(escapeMap)) {
+    /* @ts-expect-error -- TS does not properly detect that value is to be forced as string, here */
+    value = value.replace(s, r)
+  }
+  return value
+}

src/serialize/json/normalize.ts

@@ -21,6 +21,7 @@ import { isNotUndefined } from '../../_helpers/notUndefined'
 import type { SortableIterable } from '../../_helpers/sortable'
 import type { Stringable } from '../../_helpers/stringable'
 import { treeIteratorSymbol } from '../../_helpers/tree'
+import { escapeUri } from '../../_helpers/uri'
 import * as Models from '../../models'
 import { isSupportedSpdxId } from '../../spdx'
 import { Version as SpecVersion } from '../../spec'
@@ -311,8 +312,10 @@ export class OrganizationalContactNormalizer extends BaseJsonNormalizer<Models.O
 
 export class OrganizationalEntityNormalizer extends BaseJsonNormalizer<Models.OrganizationalEntity> {
   normalize (data: Models.OrganizationalEntity, options: NormalizerOptions): Normalized.OrganizationalEntity {
-    const urls = normalizeStringableIter(data.url, options)
-      .filter(JsonSchema.isIriReference)
+    const urls = normalizeStringableIter(
+      Array.from(data.url, (s) => escapeUri(s.toString())),
+      options
+    ).filter(JsonSchema.isIriReference)
     return {
       name: data.name || undefined,
       url: urls.length > 0
@@ -438,7 +441,7 @@ export class LicenseNormalizer extends BaseJsonNormalizer<Models.License> {
   }
 
   #normalizeNamedLicense (data: Models.NamedLicense, options: NormalizerOptions): Normalized.NamedLicense {
-    const url = data.url?.toString()
+    const url = escapeUri(data.url?.toString())
     return {
       license: {
         name: data.name,
@@ -453,13 +456,16 @@ export class LicenseNormalizer extends BaseJsonNormalizer<Models.License> {
   }
 
   #normalizeSpdxLicense (data: Models.SpdxLicense, options: NormalizerOptions): Normalized.SpdxLicense {
+    const url = escapeUri(data.url?.toString())
     return {
       license: {
         id: data.id,
         text: data.text === undefined
           ? undefined
           : this._factory.makeForAttachment().normalize(data.text, options),
-        url: data.url?.toString()
+        url: JsonSchema.isIriReference(url)
+          ? url
+          : undefined
       }
     }
   }
@@ -493,7 +499,7 @@ export class LicenseNormalizer extends BaseJsonNormalizer<Models.License> {
 
 export class SWIDNormalizer extends BaseJsonNormalizer<Models.SWID> {
   normalize (data: Models.SWID, options: NormalizerOptions): Normalized.SWID {
-    const url = data.url?.toString()
+    const url = escapeUri(data.url?.toString())
     return {
       tagId: data.tagId,
       name: data.name,
@@ -514,7 +520,7 @@ export class ExternalReferenceNormalizer extends BaseJsonNormalizer<Models.Exter
   normalize (data: Models.ExternalReference, options: NormalizerOptions): Normalized.ExternalReference | undefined {
     return this._factory.spec.supportsExternalReferenceType(data.type)
       ? {
-          url: data.url.toString(),
+          url: escapeUri(data.url.toString()),
           type: data.type,
           hashes: this._factory.spec.supportsExternalReferenceHashes && data.hashes.size > 0
             ? this._factory.makeForHash().normalizeIterable(data.hashes, options)
@@ -726,7 +732,7 @@ export class VulnerabilityRatingNormalizer extends BaseJsonNormalizer<Models.Vul
 
 export class VulnerabilityAdvisoryNormalizer extends BaseJsonNormalizer<Models.Vulnerability.Advisory> {
   normalize (data: Models.Vulnerability.Advisory, options: NormalizerOptions): Normalized.Vulnerability.Advisory | undefined {
-    const url = data.url.toString()
+    const url = escapeUri(data.url.toString())
     if (!JsonSchema.isIriReference(url)) {
       // invalid value -> cannot render
       return undefined

src/serialize/xml/normalize.ts

@@ -21,6 +21,7 @@ import { isNotUndefined } from '../../_helpers/notUndefined'
 import type { SortableIterable } from '../../_helpers/sortable'
 import type { Stringable } from '../../_helpers/stringable'
 import { treeIteratorSymbol } from '../../_helpers/tree'
+import { escapeUri } from '../../_helpers/uri'
 import * as Models from '../../models'
 import { isSupportedSpdxId } from '../../spdx'
 import { Version as SpecVersion } from '../../spec'
@@ -388,8 +389,10 @@ export class OrganizationalEntityNormalizer extends BaseXmlNormalizer<Models.Org
       name: elementName,
       children: [
         makeOptionalTextElement(data.name, 'name'),
-        ...makeTextElementIter(data.url, options, 'url')
-          .filter(({ children: u }) => XmlSchema.isAnyURI(u)),
+        ...makeTextElementIter(Array.from(
+          data.url, (s): string => escapeUri(s.toString())
+        ), options, 'url'
+        ).filter(({ children: u }) => XmlSchema.isAnyURI(u)),
         ...this._factory.makeForOrganizationalContact().normalizeIterable(data.contact, options, 'contact')
       ].filter(isNotUndefined)
     }
@@ -554,7 +557,7 @@ export class LicenseNormalizer extends BaseXmlNormalizer<Models.License> {
   }
 
   #normalizeNamedLicense (data: Models.NamedLicense, options: NormalizerOptions): SimpleXml.Element {
-    const url = data.url?.toString()
+    const url = escapeUri(data.url?.toString())
     return {
       type: 'element',
       name: 'license',
@@ -571,7 +574,7 @@ export class LicenseNormalizer extends BaseXmlNormalizer<Models.License> {
   }
 
   #normalizeSpdxLicense (data: Models.SpdxLicense, options: NormalizerOptions): SimpleXml.Element {
-    const url = data.url?.toString()
+    const url = escapeUri(data.url?.toString())
     return {
       type: 'element',
       name: 'license',
@@ -614,7 +617,7 @@ export class LicenseNormalizer extends BaseXmlNormalizer<Models.License> {
 
 export class SWIDNormalizer extends BaseXmlNormalizer<Models.SWID> {
   normalize (data: Models.SWID, options: NormalizerOptions, elementName: string): SimpleXml.Element {
-    const url = data.url?.toString()
+    const url = escapeUri(data.url?.toString())
     return {
       type: 'element',
       name: elementName,
@@ -641,7 +644,7 @@ 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 url = escapeUri(data.url.toString())
     const hashes: SimpleXml.Element | undefined = this._factory.spec.supportsExternalReferenceHashes && data.hashes.size > 0
       ? {
           type: 'element',
@@ -874,7 +877,7 @@ export class VulnerabilityNormalizer extends BaseXmlNormalizer<Models.Vulnerabil
 
 export class VulnerabilitySourceNormalizer extends BaseXmlNormalizer<Models.Vulnerability.Source> {
   normalize (data: Models.Vulnerability.Source, options: NormalizerOptions, elementName: string): SimpleXml.Element {
-    const url = data.url?.toString()
+    const url = escapeUri(data.url?.toString())
     return {
       type: 'element',
       name: elementName,
@@ -940,7 +943,7 @@ export class VulnerabilityRatingNormalizer extends BaseXmlNormalizer<Models.Vuln
 
 export class VulnerabilityAdvisoryNormalizer extends BaseXmlNormalizer<Models.Vulnerability.Advisory> {
   normalize (data: Models.Vulnerability.Advisory, options: NormalizerOptions, elementName: string): SimpleXml.Element | undefined {
-    const url = data.url.toString()
+    const url = escapeUri(data.url.toString())
     if (!XmlSchema.isAnyURI(url)) {
       // invalid value -> cannot render
       return undefined

tests/_data/models.js

@@ -21,10 +21,6 @@ const { PackageURL } = require('packageurl-js')
 
 const { Enums, Models, Types } = require('../../')
 
-/* eslint-disable jsdoc/valid-types */
-
-/* eslint-enable jsdoc/valid-types */
-
 /**
  * @returns {Models.Bom}
  */
@@ -268,6 +264,34 @@ module.exports.createComplexStructure = function () {
     )
   )
 
+  bom.components.add(
+    new Models.Component(
+      Enums.ComponentType.Library, 'component-with-unescaped-urls', {
+        bomRef: 'component-with-unescaped-urls',
+        externalReferences: new Models.ExternalReferenceRepository(
+          [
+            ['encode anyUri: urn', 'urn:example:org'],
+            ['encode anyUri: https', 'https://example.org/p?k=v#f'],
+            ['encode anyUri: mailto', 'mailto:[email protected]'],
+            ['encode anyUri: relative path', '../foo/bar'],
+            ['encode anyUri: space', 'https://example.org/foo bar'],
+            ['encode anyUri: []', 'https://example.org/?bar[test]=baz'],
+            ['encode anyUri: <>', 'https://example.org/#<test>'],
+            ['encode anyUri: {}', 'https://example.org/#{test}'],
+            ['encode anyUri: non-ASCII', 'https://example.org/édition'],
+            ['encode anyUri: partially encoded', 'https://example.org/?bar[test%5D=baz']
+          ].map(
+            ([desc, uri]) => new Models.ExternalReference(
+              uri, Enums.ExternalReferenceType.Other, {
+                comment: desc
+              }
+            )
+          )
+        )
+      }
+    )
+  )
+
   const someVulnerableComponent = new Models.Component(
     Enums.ComponentType.Library,
     'component-with-vulnerabilities',