@cyclonedx/cyclonedx-library 1.0.0-beta.1

package/src/serialize/json/types.ts

@@ -0,0 +1,187 @@
+/*!
+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 * as Enums from '../../enums'
+import { HashContent } from '../../models'
+import { SpdxId } from '../../spdx'
+import { CPE, Integer, UrnUuid } from '../../types'
+
+// eslint-disable-next-line @typescript-eslint/no-namespace
+export namespace JsonSchema {
+
+  /**
+   * @see isIriReference
+   */
+  export type IriReference = string
+  /**
+   * Test whether format is JSON::iri-reference - best-effort.
+   *
+   * @see {@link https://datatracker.ietf.org/doc/html/rfc3987}
+   */
+  export function isIriReference (value: IriReference | any): value is IriReference {
+    return typeof value === 'string' &&
+      value.length > 0
+    // TODO add more validation according to spec
+  }
+
+  /**
+   * @see isIdnEmail
+   */
+  export type IdnEmail = string
+  /**
+   * Test whether format is JSON::idn-email - best-effort.
+   *
+   * @see {@link https://datatracker.ietf.org/doc/html/rfc6531}
+   */
+  export function isIdnEmail (value: IdnEmail | any): value is IdnEmail {
+    return typeof value === 'string' &&
+      value.length > 0
+    // TODO add more validation according to spec
+  }
+
+  export type DateTime = string
+
+}
+
+// eslint-disable-next-line @typescript-eslint/no-namespace
+export namespace Normalized {
+
+  export type RefType = string
+
+  export interface Bom {
+    $schema?: string
+    bomFormat: 'CycloneDX'
+    specVersion: string
+    version: Integer
+    serialNumber?: UrnUuid
+    metadata?: Metadata
+    components?: Component[]
+    externalReferences?: ExternalReference[]
+    dependencies?: Dependency[]
+  }
+
+  export interface Metadata {
+    timestamp?: JsonSchema.DateTime
+    tools?: Tool[]
+    authors?: OrganizationalContact[]
+    component?: Component
+    manufacture?: OrganizationalEntity
+    supplier?: OrganizationalEntity
+    licenses?: License[]
+  }
+
+  export interface Tool {
+    vendor?: string
+    name?: string
+    version?: string
+    hashes?: Hash[]
+    externalReferences?: ExternalReference[]
+  }
+
+  export interface OrganizationalContact {
+    name?: string
+    email?: JsonSchema.IdnEmail
+    phone?: string
+  }
+
+  export interface OrganizationalEntity {
+    name?: string
+    url?: JsonSchema.IriReference[]
+    contact?: OrganizationalContact[]
+  }
+
+  export interface Hash {
+    alg: Enums.HashAlgorithm
+    content: HashContent
+  }
+
+  export interface Component {
+    type: Enums.ComponentType
+    name: string
+    'mime-type'?: string
+    'bom-ref'?: RefType
+    supplier?: OrganizationalEntity
+    author?: string
+    publisher?: string
+    group?: string
+    version?: string
+    description?: string
+    scope?: Enums.ComponentScope
+    hashes?: Hash[]
+    licenses?: License[]
+    copyright?: string
+    cpe?: CPE
+    purl?: string
+    swid?: SWID
+    modified?: boolean
+    externalReferences?: ExternalReference[]
+    components?: Component[]
+  }
+
+  export interface NamedLicense {
+    license: {
+      name: string
+      text?: Attachment
+      url?: string
+    }
+  }
+
+  export interface SpdxLicense {
+    license: {
+      /** @see {@link http://cyclonedx.org/schema/spdx} */
+      id: SpdxId
+      text?: Attachment
+      url?: string
+    }
+  }
+
+  export interface LicenseExpression {
+    expression: string
+  }
+
+  export type License = NamedLicense | SpdxLicense | LicenseExpression
+
+  export interface SWID {
+    tagId: string
+    name: string
+    version?: string
+    tagVersion?: Integer
+    patch?: boolean
+    text?: Attachment
+    url?: JsonSchema.IriReference
+  }
+
+  export interface ExternalReference {
+    url: string
+    type: Enums.ExternalReferenceType
+    comment?: string
+  }
+
+  export interface Attachment {
+    content?: string
+    contentType?: string
+    encoding?: Enums.AttachmentEncoding
+  }
+
+  export interface Dependency {
+    ref: RefType
+    dependsOn?: RefType[]
+  }
+
+}

package/src/serialize/jsonSerializer.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 { Bom } from '../models'
+import { Format, UnsupportedFormatError } from '../spec'
+import { NormalizerOptions, SerializerOptions } from './types'
+import { BaseSerializer } from './baseSerializer'
+import { Factory as NormalizerFactory } from './json/normalize'
+import { Normalized } from './json/types'
+
+/**
+ * Multi purpose Json serializer.
+ */
+export class JsonSerializer extends BaseSerializer<Normalized.Bom> {
+  readonly #normalizerFactory: NormalizerFactory
+
+  /**
+   * @throws {UnsupportedFormatError} if {@see normalizerFactory.spec} does not support {@see Format.JSON}.
+   */
+  constructor (normalizerFactory: NormalizerFactory) {
+    if (!normalizerFactory.spec.supportsFormat(Format.JSON)) {
+      throw new UnsupportedFormatError('Spec does not support JSON format.')
+    }
+
+    super()
+    this.#normalizerFactory = normalizerFactory
+  }
+
+  protected _normalize (
+    bom: Bom,
+    options: NormalizerOptions = {}
+  ): Normalized.Bom {
+    return this.#normalizerFactory.makeForBom()
+      .normalize(bom, options)
+  }
+
+  protected _serialize (
+    bom: Normalized.Bom,
+    { space }: SerializerOptions = {}
+  ): string {
+    return JSON.stringify(bom, null, space)
+  }
+}

package/src/serialize/types.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 { Bom } from '../models'
+
+export interface NormalizerOptions {
+  /**
+   * Whether to sort lists in normalization results. Sorted lists make the output reproducible.
+   */
+  sortLists?: boolean
+}
+
+export interface SerializerOptions {
+  /**
+   * Add indention in the serialization result. Indention increases readability for humans.
+   */
+  space?: string | number
+}
+
+export interface Serializer {
+  serialize: (bom: Bom, options?: SerializerOptions & NormalizerOptions) => string
+}

package/src/serialize/xml/index.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 * as Types from './types'
+
+export * as Normalize from './normalize'
+// export * as Denormalize from './denormalize' // TODO