feat: npmjs related symbols and parsing (#1246)

jkowalleck · web-flow · commit a8f441da0fcb · 2025-06-05T12:29:25.000+02:00
fixes #1247 ## Added * `factories.FromNodePackageJson.makeExternalReferences` supports "dist" field * New symbols under `utils.NpmJs` * `defaultRepoMatcher` * `parsePackageIntegrity` ---- TODO - [x] implementation - [x] tests --------- Signed-off-by: Jan Kowalleck <jan.kowalleck@gmail.com>
diff --git a/HISTORY.md b/HISTORY.md
@@ -6,6 +6,15 @@ All notable changes to this project will be documented in this file.
 
 <!-- add unreleased items here -->
 
+* Added
+  * `factories.FromNodePackageJson.makeExternalReferences()` supports "dist" field ([#1247] via [#1246]) 
+  * New symbols under `utils.NpmjsUtility` (via [#1246]) 
+    * `defaultRegistryMatcher`
+    * `parsePackageIntegrity`
+
+[#1246]: https://github.com/CycloneDX/cyclonedx-javascript-library/pull/1246
+[#1247]: https://github.com/CycloneDX/cyclonedx-javascript-library/issues/1247
+
 ## 8.1.0 -- 2025-06-04
 
 Support for _Node.js_ v24.
diff --git a/package.json b/package.json
@@ -149,8 +149,8 @@
       "default": "./dist.node/types/index.js"
     },
     "./Utils": {
-      "types": "./dist.d/utils/index.d.ts",
-      "default": "./dist.node/utils/index.js"
+      "types": "./dist.d/utils/index.node.d.ts",
+      "default": "./dist.node/utils/index.node.js"
     },
     "./Validation": {
       "types": "./dist.d/validation/index.node.d.ts",
diff --git a/src/_helpers/packageJson.ts b/src/_helpers/packageJson.ts
@@ -62,4 +62,5 @@ export interface PackageJson {
     directory?: string
   }
   // ... to be continued
+  dist?: any // see https://github.com/CycloneDX/cyclonedx-node-npm/issues/1300
 }
diff --git a/src/factories/fromNodePackageJson.node.ts b/src/factories/fromNodePackageJson.node.ts
@@ -29,12 +29,15 @@ Copyright (c) OWASP Foundation. All Rights Reserved.
 import type { PackageURL } from 'packageurl-js'
 import { PurlQualifierNames } from 'packageurl-js'
 
-import {tryCanonicalizeGitUrl} from "../_helpers/gitUrl"
+import { tryCanonicalizeGitUrl } from "../_helpers/gitUrl"
 import { isNotUndefined } from '../_helpers/notUndefined'
 import type { PackageJson } from '../_helpers/packageJson'
 import { ExternalReferenceType } from '../enums/externalReferenceType'
+import { HashAlgorithm } from "../enums/hashAlogorithm";
 import type { Component } from '../models/component'
 import { ExternalReference } from '../models/externalReference'
+import { HashDictionary } from '../models/hash'
+import { defaultRegistryMatcher, parsePackageIntegrity } from '../utils/npmjsUtility.node'
 import { PackageUrlFactory as PlainPackageUrlFactory } from './packageUrl'
 
 /**
@@ -47,6 +50,7 @@ export class ExternalReferenceFactory {
     try { refs.push(this.makeVcs(data)) } catch { /* pass */ }
     try { refs.push(this.makeHomepage(data)) } catch { /* pass */ }
     try { refs.push(this.makeIssueTracker(data)) } catch { /* pass */ }
+    try { refs.push(this.makeDist(data)) } catch { /* pass */ }
 
     return refs.filter(isNotUndefined)
   }
@@ -100,13 +104,32 @@ export class ExternalReferenceFactory {
       ? new ExternalReference(url, ExternalReferenceType.IssueTracker, { comment })
       : undefined
   }
-}
 
-/**
- * The default repository is `https://registry.npmjs.org`.
- * @see {@link https://github.com/package-url/purl-spec/blob/master/PURL-TYPES.rst#npm}
- */
-const npmDefaultRepositoryMatcher = /^https?:\/\/registry\.npmjs\.org(:?\/|$)/
+  makeDist(data: PackageJson): ExternalReference | undefined {
+    // "dist" might be used in bundled dependencies' manifests.
+    // docs: https://blog.npmjs.org/post/172999548390/new-pgp-machinery
+    /* eslint-disable-next-line @typescript-eslint/no-unsafe-assignment -- acknowledged */
+    const { tarball, integrity, shasum } = data.dist ?? {}
+    if (typeof tarball === 'string') {
+      const hashes = new HashDictionary()
+      let comment = 'as detected from PackageJson property "dist.tarball"'
+      if (typeof integrity === 'string') {
+        try {
+          // actually not the hash of the file, but more of an integrity-check -- lets use it anyway.
+          // see https://blog.npmjs.org/post/172999548390/new-pgp-machinery
+          hashes.set(...parsePackageIntegrity(integrity))
+          comment += ' and property "dist.integrity"'
+        } catch { /* pass */ }
+      }
+      if (typeof shasum === 'string' && shasum.length === 40) {
+        hashes.set(HashAlgorithm["SHA-1"], shasum)
+        comment += ' and property "dist.shasum"'
+      }
+      return new ExternalReference(tarball, ExternalReferenceType.Distribution, { hashes, comment })
+    }
+    return undefined
+  }
+}
 
 /**
  * Node-specific PackageUrlFactory.
@@ -134,13 +157,13 @@ export class PackageUrlFactory extends PlainPackageUrlFactory<'npm'> {
    * - "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 {
+  #finalizeQualifiers(purl: PackageURL): PackageURL {
     const qualifiers = new Map(Object.entries(purl.qualifiers ?? {}))
 
     const downloadUrl = qualifiers.get(PurlQualifierNames.DownloadUrl)
     if (downloadUrl !== undefined) {
       qualifiers.delete(PurlQualifierNames.VcsUrl)
-      if (npmDefaultRepositoryMatcher.test(downloadUrl)) {
+      if (defaultRegistryMatcher.test(downloadUrl)) {
         qualifiers.delete(PurlQualifierNames.DownloadUrl)
       }
     }
diff --git a/src/index.common.ts b/src/index.common.ts
@@ -22,5 +22,4 @@ 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
diff --git a/src/index.node.ts b/src/index.node.ts
@@ -28,6 +28,7 @@ export * from './index.common'
 export * as Builders from './builders/index.node'
 export * as Factories from './factories/index.node'
 export * as Serialize from './serialize/index.node'
+export * as Utils from './utils/index.node'
 export * as Validation from './validation/index.node'
 
 /**
diff --git a/src/index.web.ts b/src/index.web.ts
@@ -23,6 +23,7 @@ export * from './index.common'
 
 export * as Factories from './factories/index.web'
 export * as Serialize from './serialize/index.web'
+export * as Utils from './utils/index.web'
 export * as Validation from './validation/index.web'
 
 // endregion web-specifics
diff --git a/src/utils/index.common.ts b/src/utils/index.common.ts
diff --git a/src/utils/index.node.ts b/src/utils/index.node.ts
@@ -0,0 +1,26 @@
+/*!
+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 * from './index.common'
+
+// region node-specifics
+
+export * as NpmjsUtility from './npmjsUtility.node'
+
+// endregion node-specifics
diff --git a/src/utils/index.web.ts b/src/utils/index.web.ts
@@ -0,0 +1,26 @@
+/*!
+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 * from './index.common'
+
+// region web-specifics
+
+// ... nothing yet
+
+// endregion web-specifics
diff --git a/src/utils/npmjsUtility.node.ts b/src/utils/npmjsUtility.node.ts
@@ -0,0 +1,89 @@
+/*!
+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.
+*/
+
+import {HashAlgorithm} from '../enums/hashAlogorithm'
+
+/**
+ * See {@link https://docs.npmjs.com/cli/v9/configuring-npm/package-lock-json#packages | package lock docs} for "integrity".
+ * See {@link https://blog.npmjs.org/post/172999548390/new-pgp-machinery | new pgp machinery} for "integrity".
+ *
+ * integrity: A sha512 or sha1 [Standard Subresource Integrity](https://w3c.github.io/webappsec/specs/subresourceintegrity/) string for the artifact that was unpacked in this location.
+ */
+const integrityRE: ReadonlyMap<HashAlgorithm, RegExp> = new Map([
+  // !!! this list is pre-sorted, starting with most-common usage.
+
+  /* base64 alphabet: `A-Za-z0-9+/` and `=` for padding
+   * SHA-512 => base64 over 512 bit => 86 chars + 2 chars padding.
+   * examples:
+   * - sha512-zvj65TkFeIt3i6aj5bIvJDzjjQQGs4o/sNoezg1F1kYap9Nu2jcUdpwzRSJTHMMzG0H7bZkn4rNQpImhuxWX2A==
+   * - sha512-DXUS22Y57/LAFSg3x7Vi6RNAuLpTXwxB9S2nIA7msBb/Zt8p7XqMwdpdc1IU7CkOQUPgAqR5fWvxuKCbneKGmA==
+   * - sha512-5BejraMXMC+2UjefDvrH0Fo/eLwZRV6859SXRg+FgbhA0R0l6lDqDGAQYhKbXhPN2ofk2kY5sgGyLNL907UXpA==
+   */
+  [HashAlgorithm['SHA-512'], /^sha512-([a-z0-9+/]{86}==)$/i],
+
+  /* base64 alphabet: `A-Za-z0-9+/` and `=` for padding
+   * SHA-1 => base64 over 160 bit => 27 chars + 1 chars padding.
+   * examples:
+   * - sha1-aSbRsZT7xze47tUTdW3i/Np+pAg=
+   * - sha1-Kq5sNclPz7QV2+lfQIuc6R7oRu0=
+   * - sha1-XV8g50dxuFICXD7bZslGLuuRPQM=
+   */
+  [HashAlgorithm['SHA-1'], /^sha1-([a-z0-9+/]{27}=)$/i],
+
+  /* base64 alphabet: `A-Za-z0-9+/` and `=` for padding
+   * SHA-256 => base64 over 256 bit => 43 chars + 1 chars padding.
+   * examples:
+   * - sha256-jxzgcB+8dLn7Cjjyg7stGWMftZf6rbdvgoE85TOzmT4=
+   * - sha256-47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=
+   * - sha256-+8Gp+Fjqnhd5FpZL2Iw9N7kaHoRBJ2XimVB3fyZcS3U=
+   */
+  [HashAlgorithm['SHA-256'], /^sha256-([a-z0-9+/]{43}=)$/i],
+
+  /* base64 alphabet: `A-Za-z0-9+/` and `=` for padding
+   * SHA-384 => base64 over 384 bit => 64 chars + 0 chars padding.
+   * example:
+   * - sha384-aDkxLz2zQ0dwcNPAsr7NQXs1cVTUh5TQHXjPtGF+1auBmne2gy9lQt0Yu3OBMe9+
+   * - sha384-oqVuAfXRKap7fdgcCY5uykM6+R9GqQ8K/uxy9rx7HNQlGYl1kPzQho1wx4JwY8wC
+   * - sha384-/b2OdaZ/KfcBpOBAOF4uI5hjA+oQI5IRr5B/y7g1eLPkF8txzmRu/QgZ3YwIjeG9
+   */
+  [HashAlgorithm['SHA-384'], /^sha384-([a-z0-9+/]{64})$/i]
+])
+
+/**
+ * @throws {@link RangeError} if value is unparsable
+ */
+export function parsePackageIntegrity (integrity: string): [HashAlgorithm, string] {
+  for (const [hashAlgorithm, hashRE] of integrityRE) {
+    const hashMatchBase64 = hashRE.exec(integrity) ?? []
+    if (hashMatchBase64.length === 2) {
+      return [
+        hashAlgorithm,
+        Buffer.from(hashMatchBase64[1], 'base64').toString('hex')
+      ]
+    }
+  }
+  throw new RangeError('unparsable value')
+}
+
+
+/**
+ * The default registry is `https://registry.npmjs.org`.
+ * @see {@link https://github.com/package-url/purl-spec/blob/master/PURL-TYPES.rst#npm}
+ */
+export const defaultRegistryMatcher = /^https?:\/\/registry\.npmjs\.org(:?\/|$)/
diff --git a/tests/integration/Factories.FromNodePackageJson.ExternalReferenceFactory.test.js b/tests/integration/Factories.FromNodePackageJson.ExternalReferenceFactory.test.js
diff --git a/tests/unit/Factories.FromNodePackageJson.PackageUrlFactory.js b/tests/unit/Factories.FromNodePackageJson.PackageUrlFactory.js
diff --git a/tests/unit/Utils.NpmjsUtility.spec.js b/tests/unit/Utils.NpmjsUtility.spec.js

Original file line number	Diff line number	Diff line change
`@@ -62,4 +62,5 @@ export interface PackageJson {`
`62`	`62`	`directory?: string`
`63`	`63`	`}`
`64`	`64`	`// ... to be continued`
	`65`	`+ dist?: any // see https://github.com/CycloneDX/cyclonedx-node-npm/issues/1300`
`65`	`66`	`}`