feat: Factories.FromNodePackageJson.PackageUrlFactory to omits PURL's npm defaults (#207)

feat: `Factories.FromNodePackageJson.PackageUrlFactory`

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

Author: jkowalleck

HISTORY.md

@@ -4,9 +4,14 @@ All notable changes to this project will be documented in this file.
 
 ## unreleased
 
+* Added
+  * New class `Factories.FromNodePackageJson.PackageUrlFactory` that acts like `Factories.PackageUrlFactory`, but
+    omits PackageUrl's npm-specific "default derived" qualifier values for `download_url` & `vcs_url`. ([#204] via [#207])
 * Build
   * Use _TypeScript_ `v4.8.2` now, was `v4.7.4`. (via [#190])
 
+[#204]: https://github.com/CycloneDX/cyclonedx-javascript-library/issues/178
+[#207]: https://github.com/CycloneDX/cyclonedx-javascript-library/pull/207
 [#190]: https://github.com/CycloneDX/cyclonedx-javascript-library/pull/190
 
 ## 1.3.4 - 2022-08-16

src/factories/fromNodePackageJson.node.ts

@@ -17,15 +17,23 @@ SPDX-License-Identifier: Apache-2.0
 Copyright (c) OWASP Foundation. All Rights Reserved.
 */
 
+import { PackageURL } from 'packageurl-js'
+
 import * as Models from '../models'
 import * as Enums from '../enums'
+import { PackageUrlFactory as PlainPackageUrlFactory } from './packageUrl'
 import { isNotUndefined } from '../helpers/notUndefined'
 import { PackageJson } from '../helpers/packageJson'
+import { PackageUrlQualifierNames } from '../helpers/packageUrl'
 
 /**
+ * Node-specifics.
  * @see {@link https://docs.npmjs.com/cli/v8/configuring-npm/package-json PackageJson spec}
  */
 
+/**
+ * Node-specific ExternalReferenceFactory.
+ */
 export class ExternalReferenceFactory {
   makeExternalReferences (data: PackageJson): Models.ExternalReference[] {
     const refs: Array<Models.ExternalReference | undefined> = []
@@ -86,3 +94,49 @@ export class ExternalReferenceFactory {
       : undefined
   }
 }
+
+const npmDefaultRegistryMatcher = /^https?:\/\/registry\.npmjs\.org/
+
+/**
+ * Node-specific PackageUrlFactory.
+ */
+export class PackageUrlFactory extends PlainPackageUrlFactory {
+  override makeFromComponent (component: Models.Component, sort: boolean = false): PackageURL | undefined {
+    const purl = super.makeFromComponent(component, sort)
+    return purl === undefined
+      ? undefined
+      : this.#finalizeQualifiers(purl)
+  }
+
+  /**
+   * Will strip unnecessary qualifiers according to {@link https://github.com/package-url/purl-spec/blob/master/PURL-SPECIFICATION.rst#known-qualifiers-keyvalue-pairs PURL-SPECIFICATION}:
+   * > Do not abuse qualifiers: it can be tempting to use many qualifier keys but their usage should be limited
+   * > to the bare minimum for proper package identification to ensure that a purl stays compact and readable
+   * > in most cases.
+   *
+   * Therefore:
+   * - "vcs_url" is stripped, if a "download_url" is given.
+   * - "download_url" is stripped, if it is NPM's default registry ("registry.npmjs.org")
+   * - "checksum" is stripped, unless a "download_url" or "vcs_url" is given.
+   */
+  #finalizeQualifiers (purl: PackageURL): PackageURL {
+    const qualifiers = new Map(Object.entries(purl.qualifiers ?? {}))
+
+    const downloadUrl = qualifiers.get(PackageUrlQualifierNames.DownloadURL)
+    if (downloadUrl !== undefined) {
+      qualifiers.delete(PackageUrlQualifierNames.VcsUrl)
+      if (npmDefaultRegistryMatcher.test(downloadUrl)) {
+        qualifiers.delete(PackageUrlQualifierNames.DownloadURL)
+      }
+    }
+    if (!qualifiers.has(PackageUrlQualifierNames.DownloadURL) && !qualifiers.has(PackageUrlQualifierNames.VcsUrl)) {
+      // nothing to base a checksum on
+      qualifiers.delete(PackageUrlQualifierNames.Checksum)
+    }
+    purl.qualifiers = qualifiers.size > 0
+      ? Object.fromEntries(qualifiers.entries())
+      : undefined
+
+    return purl
+  }
+}

src/factories/index.node.ts

@@ -21,5 +21,6 @@ export * from './index.common'
 
 /** @since 1.2.0 */
 export * as FromNodePackageJson from './fromNodePackageJson.node'
+
 /** @deprecated use {@link FromNodePackageJson} instead of {@link FromPackageJson} */
 export * as FromPackageJson from './fromNodePackageJson.node'

src/factories/packageUrl.ts

@@ -17,9 +17,11 @@ SPDX-License-Identifier: Apache-2.0
 Copyright (c) OWASP Foundation. All Rights Reserved.
 */
 
-import { Component } from '../models'
 import { PackageURL } from 'packageurl-js'
+
 import { ExternalReferenceType } from '../enums'
+import { Component } from '../models'
+import { PackageUrlQualifierNames } from '../helpers/packageUrl'
 
 export class PackageUrlFactory {
   readonly #type: PackageURL['type']
@@ -55,25 +57,27 @@ export class PackageUrlFactory {
       // Everything is possible: URL-encoded, not encoded, with schema, without schema
       switch (extRef.type) {
         case ExternalReferenceType.VCS:
-          [qualifiers.vcs_url, subpath] = url.split('#', 2)
+          [qualifiers[PackageUrlQualifierNames.VcsUrl], subpath] = url.split('#', 2)
           break
         case ExternalReferenceType.Distribution:
-          qualifiers.download_url = url
+          qualifiers[PackageUrlQualifierNames.DownloadURL] = url
           break
       }
     }
 
     const hashes = component.hashes
     if (hashes.size > 0) {
-      qualifiers.checksum = Array.from(
-        sort ? hashes.sorted() : hashes,
+      qualifiers[PackageUrlQualifierNames.Checksum] = Array.from(
+        sort
+          ? hashes.sorted()
+          : hashes,
         ([hashAlgo, hashCont]) => `${hashAlgo.toLowerCase()}:${hashCont.toLowerCase()}`
       ).join(',')
     }
 
     try {
       // Do not beautify the parameters here, because that is in the domain of PackageURL and its representation.
-      // No need to convert an empty `subpath` string to `undefined` and such.
+      // No need to convert an empty "subpath" string to `undefined` and such.
       return new PackageURL(
         this.#type,
         component.group,

src/helpers/packageUrl.ts

@@ -0,0 +1,29 @@
+/*!
+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.
+*/
+
+/**
+ * Known PURL qualifier names.
+ * To be used until {@link https://github.com/package-url/packageurl-js/pull/34} gets merged
+ * and {@link https://github.com/package-url/packageurl-js/issues/35} gets sorted out.
+ */
+export const enum PackageUrlQualifierNames {
+  DownloadURL = 'download_url',
+  VcsUrl = 'vcs_url',
+  Checksum = 'checksum',
+}