@cyclonedx/cyclonedx-library 1.0.0-beta.1

package/src/models/externalReference.ts

@@ -0,0 +1,48 @@
+/*!
+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 { ExternalReferenceType } from '../enums'
+
+interface OptionalProperties {
+  comment?: ExternalReference['comment']
+}
+
+export class ExternalReference {
+  url: URL | string
+  type: ExternalReferenceType
+  comment?: string
+
+  constructor (url: URL | string, type: ExternalReferenceType, op: OptionalProperties = {}) {
+    this.url = url
+    this.type = type
+    this.comment = op.comment
+  }
+
+  compare (other: ExternalReference): number {
+    /* eslint-disable-next-line @typescript-eslint/strict-boolean-expressions -- run compares in weighted order */
+    return this.type.localeCompare(other.type) ||
+      this.url.toString().localeCompare(other.url.toString())
+  }
+}
+
+export class ExternalReferenceRepository extends Set<ExternalReference> {
+  static compareItems (a: ExternalReference, b: ExternalReference): number {
+    return a.compare(b)
+  }
+}

package/src/models/hash.ts

@@ -0,0 +1,38 @@
+/*!
+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'
+
+// no regex for the HashContent in here. It applies at runtime of a normalization/serialization process.
+export type HashContent = string
+
+export type Hash = readonly [
+  // order matters: it must reflect [key, value] of HashRepository -
+  // this way a HashRepository can be constructed from multiple Hash objects.
+  algorithm: HashAlgorithm,
+  content: HashContent
+]
+
+export class HashRepository extends Map<Hash[0], Hash[1]> {
+  static compareItems (a: Hash, b: Hash): number {
+    /* eslint-disable-next-line @typescript-eslint/strict-boolean-expressions -- run compares in weighted order */
+    return a[0].localeCompare(b[0]) ||
+      a[1].localeCompare(b[1])
+  }
+}

package/src/models/index.ts

@@ -0,0 +1,31 @@
+/*!
+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 './attachment'
+export * from './bom'
+export * from './bomRef'
+export * from './component'
+export * from './externalReference'
+export * from './hash'
+export * from './license'
+export * from './metadata'
+export * from './organizationalContact'
+export * from './organizationalEntity'
+export * from './swid'
+export * from './tool'

package/src/models/license.ts

@@ -0,0 +1,133 @@
+/*!
+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 { isSupportedSpdxId, SpdxId } from '../spdx'
+import { Attachment } from './attachment'
+
+export class LicenseExpression {
+  static isEligibleExpression (expression: string | any): boolean {
+    // smallest known: (A or B)
+    return typeof expression === 'string' &&
+      expression.length >= 8 &&
+      expression[0] === '(' &&
+      expression[expression.length - 1] === ')'
+  }
+
+  /** @see expression */
+  #expression!: string
+
+  /**
+   * @throws {RangeError} if {@see expression} is not eligible({@see LicenseExpression.isEligibleExpression})
+   */
+  constructor (expression: string) {
+    this.expression = expression
+  }
+
+  get expression (): string {
+    return this.#expression
+  }
+
+  /**
+   * @throws {RangeError} if expression is not eligible({@see LicenseExpression.isEligibleExpression})
+   */
+  set expression (value: string) {
+    if (!LicenseExpression.isEligibleExpression(value)) {
+      throw new RangeError('Not eligible expression')
+    }
+    this.#expression = value
+  }
+
+  compare (other: LicenseExpression): number {
+    return this.#expression.localeCompare(other.#expression)
+  }
+}
+
+interface NamedLicenseOptionalProperties {
+  text?: NamedLicense['text']
+  url?: NamedLicense['url']
+}
+
+export class NamedLicense {
+  name: string
+  text?: Attachment
+  url?: URL | string
+
+  constructor (name: string, op: NamedLicenseOptionalProperties = {}) {
+    this.name = name
+    this.text = op.text
+    this.url = op.url
+  }
+
+  compare (other: NamedLicense): number {
+    return this.name.localeCompare(other.name)
+  }
+}
+
+interface SpdxLicenseOptionalProperties {
+  text?: SpdxLicense['text']
+  url?: SpdxLicense['url']
+}
+
+export class SpdxLicense {
+  text?: Attachment
+  url?: URL | string
+
+  /** @see id */
+  #id!: SpdxId
+
+  /**
+   * @throws {RangeError} if {@see id} is not supported SPDX id({@see isSupportedSpdxId})
+   */
+  constructor (id: SpdxId, op: SpdxLicenseOptionalProperties = {}) {
+    this.id = id
+    this.text = op.text
+    this.url = op.url
+  }
+
+  get id (): SpdxId {
+    return this.#id
+  }
+
+  /**
+   * @throws {RangeError} if value is not supported SPDX id({@see isSupportedSpdxId})
+   */
+  set id (value: SpdxId) {
+    if (!isSupportedSpdxId(value)) {
+      throw new RangeError('Unknown SPDX id')
+    }
+    this.#id = value
+  }
+
+  compare (other: SpdxLicense): number {
+    return this.#id.localeCompare(other.#id)
+  }
+}
+
+export type DisjunctiveLicense = NamedLicense | SpdxLicense
+export type License = DisjunctiveLicense | LicenseExpression
+
+export class LicenseRepository extends Set<License> {
+  static compareItems (a: License, b: License): number {
+    if (a.constructor === b.constructor) {
+      // @ts-expect-error -- classes are from same type -> they are comparable
+      return a.compare(b)
+    }
+    return a.constructor.name.localeCompare(b.constructor.name)
+  }
+}

package/src/models/metadata.ts

@@ -0,0 +1,50 @@
+/*!
+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 { Component } from './component'
+import { ToolRepository } from './tool'
+import { OrganizationalEntity } from './organizationalEntity'
+import { OrganizationalContactRepository } from './organizationalContact'
+
+interface OptionalProperties {
+  timestamp?: Metadata['timestamp']
+  tools?: Metadata['tools']
+  authors?: Metadata['authors']
+  component?: Metadata['component']
+  manufacture?: Metadata['manufacture']
+  supplier?: Metadata['supplier']
+}
+
+export class Metadata {
+  timestamp?: Date
+  tools: ToolRepository
+  authors: OrganizationalContactRepository
+  component?: Component
+  manufacture?: OrganizationalEntity
+  supplier?: OrganizationalEntity
+
+  constructor (op: OptionalProperties = {}) {
+    this.timestamp = op.timestamp
+    this.tools = op.tools ?? new ToolRepository()
+    this.authors = op.authors ?? new OrganizationalContactRepository()
+    this.component = op.component
+    this.manufacture = op.manufacture
+    this.supplier = op.supplier
+  }
+}

package/src/models/organizationalContact.ts

@@ -0,0 +1,49 @@
+/*!
+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.
+*/
+
+interface OptionalProperties {
+  name?: OrganizationalContact['name']
+  email?: OrganizationalContact['email']
+  phone?: OrganizationalContact['phone']
+}
+
+export class OrganizationalContact {
+  name?: string
+  email?: string
+  phone?: string
+
+  constructor (op: OptionalProperties = {}) {
+    this.name = op.name
+    this.email = op.email
+    this.phone = op.phone
+  }
+
+  compare (other: OrganizationalContact): number {
+    /* eslint-disable-next-line @typescript-eslint/strict-boolean-expressions -- run compares in weighted order */
+    return (this.name ?? '').localeCompare(other.name ?? '') ||
+      (this.email ?? '').localeCompare(other.email ?? '') ||
+      (this.phone ?? '').localeCompare(other.phone ?? '')
+  }
+}
+
+export class OrganizationalContactRepository extends Set<OrganizationalContact> {
+  static compareItems (a: OrganizationalContact, b: OrganizationalContact): number {
+    return a.compare(b)
+  }
+}

package/src/models/organizationalEntity.ts

@@ -0,0 +1,38 @@
+/*!
+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 { OrganizationalContactRepository } from './organizationalContact'
+
+interface OptionalProperties {
+  name?: OrganizationalEntity['name']
+  url?: OrganizationalEntity['url']
+  contact?: OrganizationalEntity['contact']
+}
+
+export class OrganizationalEntity {
+  name?: string
+  url: Set<URL | string>
+  contact: OrganizationalContactRepository
+
+  constructor (op: OptionalProperties = {}) {
+    this.name = op.name
+    this.url = op.url ?? new Set()
+    this.contact = op.contact ?? new OrganizationalContactRepository()
+  }
+}

package/src/models/swid.ts

@@ -0,0 +1,71 @@
+/*!
+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 { isNonNegativeInteger, NonNegativeInteger } from '../types'
+import { Attachment } from './attachment'
+
+interface OptionalProperties {
+  version?: SWID['version']
+  patch?: SWID['patch']
+  text?: SWID['text']
+  url?: SWID['url']
+  tagVersion?: SWID['tagVersion']
+}
+
+/**
+ * @see {@link https://csrc.nist.gov/projects/Software-Identification-SWID}
+ */
+export class SWID {
+  tagId: string
+  name: string
+  version?: string
+  patch?: boolean
+  text?: Attachment
+  url?: URL | string
+
+  /** @see tagVersion */
+  #tagVersion?: NonNegativeInteger
+
+  /**
+   * @throws {TypeError} if {@see op.tagVersion} is neither {@see NonNegativeInteger} nor {@see undefined}
+   */
+  constructor (tagId: string, name: string, op: OptionalProperties = {}) {
+    this.tagId = tagId
+    this.name = name
+    this.version = op.version
+    this.patch = op.patch
+    this.text = op.text
+    this.url = op.url
+    this.tagVersion = op.tagVersion
+  }
+
+  get tagVersion (): NonNegativeInteger | undefined {
+    return this.#tagVersion
+  }
+
+  /**
+   * @throws {TypeError} if value is neither {@see NonNegativeInteger} nor {@see undefined}
+   */
+  set tagVersion (value: NonNegativeInteger | undefined) {
+    if (value !== undefined && !isNonNegativeInteger(value)) {
+      throw new TypeError('Not NonNegativeInteger nor undefined')
+    }
+    this.#tagVersion = value
+  }
+}

package/src/models/tool.ts

@@ -0,0 +1,58 @@
+/*!
+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 { HashRepository } from './hash'
+import { ExternalReferenceRepository } from './externalReference'
+
+interface OptionalProperties {
+  vendor?: Tool['vendor']
+  name?: Tool['name']
+  version?: Tool['version']
+  hashes?: Tool['hashes']
+  externalReferences?: Tool['externalReferences']
+}
+
+export class Tool {
+  vendor?: string
+  name?: string
+  version?: string
+  hashes: HashRepository
+  externalReferences: ExternalReferenceRepository
+
+  constructor (op: OptionalProperties = {}) {
+    this.vendor = op.vendor
+    this.name = op.name
+    this.version = op.version
+    this.hashes = op.hashes ?? new HashRepository()
+    this.externalReferences = op.externalReferences ?? new ExternalReferenceRepository()
+  }
+
+  compare (other: Tool): number {
+    /* eslint-disable-next-line @typescript-eslint/strict-boolean-expressions -- run compares in weighted order */
+    return (this.vendor ?? '').localeCompare(other.vendor ?? '') ||
+      (this.name ?? '').localeCompare(other.name ?? '') ||
+      (this.version ?? '').localeCompare(other.version ?? '')
+  }
+}
+
+export class ToolRepository extends Set<Tool> {
+  static compareItems (a: Tool, b: Tool): number {
+    return a.compare(b)
+  }
+}

package/src/resources.node.ts

@@ -0,0 +1,59 @@
+/*!
+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 path from 'path'
+
+import { Version } from './spec'
+
+/** @internal */
+export const ROOT = path.resolve(__dirname, '..', 'res')
+
+/** @internal */
+export const FILES = Object.freeze({
+  CDX: Object.freeze({
+    XML_SCHEMA: Object.freeze(Object.fromEntries([
+      [Version.v1dot0, path.resolve(ROOT, 'bom-1.0.SNAPSHOT.xsd')],
+      [Version.v1dot1, path.resolve(ROOT, 'bom-1.1.SNAPSHOT.xsd')],
+      [Version.v1dot2, path.resolve(ROOT, 'bom-1.2.SNAPSHOT.xsd')],
+      [Version.v1dot3, path.resolve(ROOT, 'bom-1.3.SNAPSHOT.xsd')],
+      [Version.v1dot4, path.resolve(ROOT, 'bom-1.4.SNAPSHOT.xsd')]
+    ]) as { [key in Version]?: string }),
+    JSON_SCHEMA: Object.freeze(Object.fromEntries([
+      // v1.0 is not defined in JSON
+      // v1.1 is not defined in JSON
+      [Version.v1dot2, path.resolve(ROOT, 'bom-1.2.SNAPSHOT.schema.json')],
+      [Version.v1dot3, path.resolve(ROOT, 'bom-1.3.SNAPSHOT.schema.json')],
+      [Version.v1dot4, path.resolve(ROOT, 'bom-1.4.SNAPSHOT.schema.json')]
+    ]) as { [key in Version]?: string }),
+    JSON_STRICT_SCHEMA: Object.freeze(Object.fromEntries([
+      // v1.0 is not defined in JSON
+      // v1.1 is not defined in JSON
+      [Version.v1dot2, path.resolve(ROOT, 'bom-1.2-strict.SNAPSHOT.schema.json')],
+      [Version.v1dot3, path.resolve(ROOT, 'bom-1.3-strict.SNAPSHOT.schema.json')]
+      // v1.4 is already strict - no special file here
+    ]) as { [key in Version]?: string })
+  }),
+  SPDX: Object.freeze({
+    XML_SCHEMA: path.resolve(ROOT, 'spdx.SNAPSHOT.xsd'),
+    JSON_SCHEMA: path.resolve(ROOT, 'spdx.SNAPSHOT.schema.json')
+  }),
+  JSF: Object.freeze({
+    JSON_SCHEMA: path.resolve(ROOT, 'jsf-0.82.SNAPSHOT.schema.json')
+  })
+})

package/src/serialize/_index.node.ts

@@ -0,0 +1,23 @@
+/*!
+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'
+
+export * from './xmlSerializer.node'
+// export * from './xmlDeserializer.node' // TODO

package/src/serialize/_index.web.ts

@@ -0,0 +1,23 @@
+/*!
+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'
+
+export * from './xmlSerializer.web'
+// export * from './xmlDeserializer.web' // TODO

package/src/serialize/baseSerializer.ts

@@ -0,0 +1,52 @@
+/*!
+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 { Bom, BomRef } from '../models'
+import { BomRefDiscriminator } from './bomRefDiscriminator'
+import { NormalizerOptions, Serializer, SerializerOptions } from './types'
+
+export abstract class BaseSerializer<NormalizedBom> implements Serializer {
+  serialize (bom: Bom, options?: SerializerOptions & NormalizerOptions): string {
+    const bomRefDiscriminator = new BomRefDiscriminator(this.#getAllBomRefs(bom))
+    try {
+      // This IS NOT the place to put meaning to the BomRef values. This would be out of scope.
+      // This IS the place to make BomRef values (temporary) unique in their own document scope.
+      bomRefDiscriminator.discriminate()
+
+      const normalized = this._normalize(bom, options)
+      return this._serialize(normalized, options)
+    } finally {
+      bomRefDiscriminator.reset()
+    }
+  }
+
+  #getAllBomRefs (bom: Bom): Iterable<BomRef> {
+    const bomRefs = new Set<BomRef>()
+    if (bom.metadata.component !== undefined) {
+      bomRefs.add(bom.metadata.component.bomRef)
+    }
+    for (const { bomRef } of bom.components) {
+      bomRefs.add(bomRef)
+    }
+    return bomRefs.values()
+  }
+
+  protected abstract _normalize (bom: Bom, options?: NormalizerOptions): NormalizedBom
+  protected abstract _serialize (normalizedBom: NormalizedBom, options?: SerializerOptions): string
+}