@cyclonedx/cyclonedx-library 1.0.0-beta.1

package/src/_index.node.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 * as Enums from './enums'
+export * as Factories from './factories'
+export * as Models from './models'
+export * as Serialize from './serialize/_index.node'
+export * as SPDX from './spdx'
+export * as Spec from './spec'
+export * as Types from './types'
+
+/** @internal until the resources-module was finalized and showed value */
+export * as Resources from './resources.node'
+
+// do not export the helpers, they are for internal use only

package/src/_index.web.ts

@@ -0,0 +1,27 @@
+/*!
+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 Types from './types'
+export * as Enums from './enums'
+export * as SPDX from './spdx'
+export * as Models from './models'
+export * as Factories from './factories'
+export * as Spec from './spec'
+export * as Serialize from './serialize/_index.web'
+// do not export the helpers, they are for internal use only

package/src/enums/attachmentEncoding.ts

@@ -0,0 +1,22 @@
+/*!
+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 enum AttachmentEncoding {
+  Base64 = 'base64',
+}

package/src/enums/componentScope.ts

@@ -0,0 +1,24 @@
+/*!
+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 enum ComponentScope {
+  Required = 'required',
+  Optional = 'optional',
+  Excluded = 'excluded',
+}

package/src/enums/componentType.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.
+*/
+
+export enum ComponentType {
+  Application = 'application',
+  Framework = 'framework',
+  Library = 'library',
+  Container = 'container',
+  OperatingSystem = 'operating-system',
+  Device = 'device',
+  Firmware = 'firmware',
+  File = 'file',
+}

package/src/enums/externalReferenceType.ts

@@ -0,0 +1,37 @@
+/*!
+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 enum ExternalReferenceType {
+  VCS = 'vcs',
+  IssueTracker = 'issue-tracker',
+  Website = 'website',
+  Advisories = 'advisories',
+  BOM = 'bom',
+  MailingList = 'mailing-list',
+  Social = 'social',
+  Chat = 'chat',
+  Documentation = 'documentation',
+  Support = 'support',
+  Distribution = 'distribution',
+  License = 'license',
+  BuildMeta = 'build-meta',
+  BuildSystem = 'build-system',
+  ReleaseNotes = 'release-notes',
+  Other = 'other',
+}

package/src/enums/hashAlogorithm.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 enum HashAlgorithm {
+  MD5 = 'MD5',
+  'SHA-1' = 'SHA-1',
+  'SHA-256' = 'SHA-256',
+  'SHA-384' = 'SHA-384',
+  'SHA-512' = 'SHA-512',
+  'SHA3-256' = 'SHA3-256',
+  'SHA3-384' = 'SHA3-384',
+  'SHA3-512' = 'SHA3-512',
+  'BLAKE2b-256' = 'BLAKE2b-256',
+  'BLAKE2b-384' = 'BLAKE2b-384',
+  'BLAKE2b-512' = 'BLAKE2b-512',
+  BLAKE3 = 'BLAKE3',
+}

package/src/enums/index.ts

@@ -0,0 +1,24 @@
+/*!
+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 './attachmentEncoding'
+export * from './componentScope'
+export * from './componentType'
+export * from './externalReferenceType'
+export * from './hashAlogorithm'

package/src/factories/index.ts

@@ -0,0 +1,20 @@
+/*!
+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 './licenseFactory'

package/src/factories/licenseFactory.ts

@@ -0,0 +1,62 @@
+/*!
+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 { DisjunctiveLicense, License, LicenseExpression, NamedLicense, SpdxLicense } from '../models'
+import { fixupSpdxId } from '../spdx'
+
+export class LicenseFactory {
+  makeFromString (value: string): License {
+    try {
+      return this.makeExpression(value)
+    } catch (Error) {
+      return this.makeDisjunctive(value)
+    }
+  }
+
+  /**
+   * @throws {RangeError} if expression is not eligible
+   */
+  makeExpression (value: string): LicenseExpression {
+    return new LicenseExpression(value)
+  }
+
+  makeDisjunctive (value: string): DisjunctiveLicense {
+    try {
+      return this.makeDisjunctiveWithId(value)
+    } catch (error) {
+      return this.makeDisjunctiveWithName(value)
+    }
+  }
+
+  /**
+   * @throws {RangeError} if value is not supported SPDX id
+   */
+  makeDisjunctiveWithId (value: string | any): SpdxLicense {
+    const spdxId = fixupSpdxId(String(value))
+    if (undefined === spdxId) {
+      throw new RangeError('Unsupported SPDX id')
+    }
+
+    return new SpdxLicense(spdxId)
+  }
+
+  makeDisjunctiveWithName (value: string | any): NamedLicense {
+    return new NamedLicense(String(value))
+  }
+}

package/src/helpers/README.md

@@ -0,0 +1,3 @@
+# Helpers
+
+these are internal helpers, that are not intended to be exported/published

package/src/helpers/types.ts

@@ -0,0 +1,28 @@
+/*!
+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 type NotUndefined<T> = T extends undefined ? never : T
+
+export function isNotUndefined<T> (value: T | undefined): value is NotUndefined<T> {
+  return value !== undefined
+}
+
+export interface Stringable {
+  toString: () => string
+}

package/src/models/attachment.ts

@@ -0,0 +1,37 @@
+/*!
+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 { AttachmentEncoding } from '../enums'
+
+interface OptionalProperties {
+  contentType?: Attachment['contentType']
+  encoding?: Attachment['encoding']
+}
+
+export class Attachment {
+  contentType?: string
+  content: string
+  encoding?: AttachmentEncoding
+
+  constructor (content: string, op: OptionalProperties = {}) {
+    this.contentType = op.contentType
+    this.content = content
+    this.encoding = op.encoding
+  }
+}

package/src/models/bom.ts

@@ -0,0 +1,85 @@
+/*!
+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 { isPositiveInteger, isUrnUuid, PositiveInteger, UrnUuid } from '../types'
+import { Metadata } from './metadata'
+import { ComponentRepository } from './component'
+
+interface OptionalProperties {
+  metadata?: Bom['metadata']
+  components?: Bom['components']
+  version?: Bom['version']
+  serialNumber?: Bom['serialNumber']
+}
+
+export class Bom {
+  metadata: Metadata
+  components: ComponentRepository
+
+  /** @see version */
+  #version: PositiveInteger = 1
+
+  /** @see serialNumber */
+  #serialNumber?: UrnUuid
+
+  // Property `bomFormat` is not part of model, it is runtime information.
+  // Property `specVersion` is not part of model, it is runtime information.
+
+  // Property `dependencies` is not part of this model, but part of `Component` and other models.
+  // The dependency graph can be normalized on render-time, no need to store it in the bom model.
+
+  /**
+   * @throws {TypeError} if {@see op.version} is not {@see PositiveInteger} nor {@see undefined}
+   * @throws {TypeError} if {@see op.serialNumber} is neither {@see UrnUuid} nor {@see undefined}
+   */
+  constructor (op: OptionalProperties = {}) {
+    this.metadata = op.metadata ?? new Metadata()
+    this.components = op.components ?? new ComponentRepository()
+    this.version = op.version ?? this.version
+    this.serialNumber = op.serialNumber
+  }
+
+  get version (): PositiveInteger {
+    return this.#version
+  }
+
+  /**
+   * @throws {TypeError} if value is not {@see PositiveInteger}
+   */
+  set version (value: PositiveInteger) {
+    if (!isPositiveInteger(value)) {
+      throw new TypeError('Not PositiveInteger')
+    }
+    this.#version = value
+  }
+
+  get serialNumber (): UrnUuid | undefined {
+    return this.#serialNumber
+  }
+
+  /**
+   * @throws {TypeError} if value is neither {@see UrnUuid} nor {@see undefined}
+   */
+  set serialNumber (value: UrnUuid | undefined) {
+    if (value !== undefined && !isUrnUuid(value)) {
+      throw new TypeError('Not UrnUuid nor undefined')
+    }
+    this.#serialNumber = value
+  }
+}

package/src/models/bomRef.ts

@@ -0,0 +1,41 @@
+/*!
+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.
+*/
+
+/**
+ * Proxy for the BomRef.
+ * This way a `BomRef` gets unique by the in-memory-address of the object.
+ */
+export class BomRef {
+  value?: string
+
+  constructor (value?: string) {
+    this.value = value
+  }
+
+  compare (other: BomRef): number {
+    return (this.toString()).localeCompare(other.toString())
+  }
+
+  toString (): string {
+    return this.value ?? ''
+  }
+}
+
+export class BomRefRepository extends Set<BomRef> {
+}

package/src/models/component.ts

@@ -0,0 +1,136 @@
+/*!
+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 { PackageURL } from 'packageurl-js'
+
+import { CPE, isCPE } from '../types'
+import { ComponentScope, ComponentType } from '../enums'
+import { BomRef, BomRefRepository } from './bomRef'
+import { HashRepository } from './hash'
+import { OrganizationalEntity } from './organizationalEntity'
+import { ExternalReferenceRepository } from './externalReference'
+import { LicenseRepository } from './license'
+import { SWID } from './swid'
+
+interface OptionalProperties {
+  bomRef?: BomRef['value']
+  author?: Component['author']
+  copyright?: Component['copyright']
+  description?: Component['description']
+  externalReferences?: Component['externalReferences']
+  group?: Component['group']
+  hashes?: Component['hashes']
+  licenses?: Component['licenses']
+  publisher?: Component['publisher']
+  purl?: Component['purl']
+  scope?: Component['scope']
+  supplier?: Component['supplier']
+  swid?: Component['swid']
+  version?: Component['version']
+  dependencies?: Component['dependencies']
+  cpe?: Component['cpe']
+}
+
+export class Component {
+  type: ComponentType
+  name: string
+  author?: string
+  copyright?: string
+  description?: string
+  externalReferences: ExternalReferenceRepository
+  group?: string
+  hashes: HashRepository
+  licenses: LicenseRepository
+  publisher?: string
+  purl?: PackageURL
+  scope?: ComponentScope
+  supplier?: OrganizationalEntity
+  swid?: SWID
+  version?: string
+  dependencies: BomRefRepository
+
+  /** @see bomRef */
+  readonly #bomRef: BomRef
+
+  /** @see cpe */
+  #cpe?: CPE
+
+  /**
+   * @throws {TypeError} if {@see op.cpe} is neither {@see CPE} nor {@see undefined}
+   */
+  constructor (type: ComponentType, name: string, op: OptionalProperties = {}) {
+    this.#bomRef = new BomRef(op.bomRef)
+    this.type = type
+    this.name = name
+    this.author = op.author
+    this.copyright = op.copyright
+    this.externalReferences = op.externalReferences ?? new ExternalReferenceRepository()
+    this.group = op.group
+    this.hashes = op.hashes ?? new HashRepository()
+    this.licenses = op.licenses ?? new LicenseRepository()
+    this.publisher = op.publisher
+    this.purl = op.purl
+    this.scope = op.scope
+    this.swid = op.swid
+    this.version = op.version
+    this.dependencies = op.dependencies ?? new BomRefRepository()
+    this.cpe = op.cpe
+  }
+
+  get bomRef (): BomRef {
+    return this.#bomRef
+  }
+
+  get cpe (): CPE | undefined {
+    return this.#cpe
+  }
+
+  /**
+   * @throws {TypeError} if value is neither {@see CPE} nor {@see undefined}
+   */
+  set cpe (value: CPE | undefined) {
+    if (value !== undefined && !isCPE(value)) {
+      throw new TypeError('Not CPE nor undefined')
+    }
+    this.#cpe = value
+  }
+
+  compare (other: Component): number {
+    const bomRefCompare = this.bomRef.compare(other.bomRef)
+    if (bomRefCompare !== 0) {
+      return bomRefCompare
+    }
+    if (this.purl !== undefined && other.purl !== undefined) {
+      return this.purl.toString().localeCompare(other.purl.toString())
+    }
+    if (this.#cpe !== undefined && other.#cpe !== undefined) {
+      return this.#cpe.toString().localeCompare(other.#cpe.toString())
+    }
+    /* eslint-disable-next-line @typescript-eslint/strict-boolean-expressions -- run compares in weighted order */
+    return (this.group ?? '').localeCompare(other.group ?? '') ||
+      this.name.localeCompare(other.name) ||
+      (this.version ?? '').localeCompare(other.version ?? '')
+  }
+}
+
+export class ComponentRepository extends Set<Component> {
+  static compareItems (a: Component, b: Component): number {
+    return a.compare(b)
+  }
+}