@cdxgen/cdxgen 13.0.1 → 13.2.0

package/lib/inventory/mcpbBundle.js

@@ -0,0 +1,419 @@
+import { closeSync, openSync, readSync, statSync } from "node:fs";
+import { basename } from "node:path";
+import { inflateRawSync } from "node:zlib";
+
+import { DEBUG_MODE } from "../core/activity.js";
+import { sanitizeBomPropertyValue } from "../core/propertySanitizer.js";
+import { sanitizeMcpRefToken } from "./mcpDiscovery.js";
+import { scanTextForHiddenUnicode } from "./unicodeScan.js";
+
+const MCPB_BUNDLE_PATTERNS = ["**/*.mcpb", "**/*.dxt"];
+
+// Bound only what is decompressed. The archive itself is no longer fully
+// buffered: the End-Of-Central-Directory record, the central directory, and a
+// single local entry are read positionally, so a large vendored bundle is
+// inspected rather than silently skipped.
+const MAX_MANIFEST_BYTES = 4 * 1024 * 1024;
+// Cap the central directory read so a hostile archive cannot force a huge
+// allocation. 16 MiB comfortably covers tens of thousands of entries.
+const MAX_CENTRAL_DIR_BYTES = 16 * 1024 * 1024;
+// The EOCD record is 22 bytes plus an optional comment of up to 65535 bytes.
+const MAX_EOCD_SCAN_BYTES = 22 + 65535;
+const MAX_DESCRIPTION_BYTES = 1000;
+const EOCD_SIGNATURE = 0x06054b50;
+const CENTRAL_SIGNATURE = 0x02014b50;
+const LOCAL_SIGNATURE = 0x04034b50;
+
+const SECRET_FIELD_NAME_PATTERN =
+  /(token|secret|password|api[_-]?key|client[_-]?secret|authorization|credential)/iu;
+
+/**
+ * Read a byte range from an open file descriptor into a fresh buffer.
+ *
+ * @param {number} fd Open file descriptor
+ * @param {number} position Absolute byte offset
+ * @param {number} length Number of bytes to read
+ * @returns {Buffer|undefined} Filled buffer, or undefined on short read
+ */
+function readRange(fd, position, length) {
+  if (length <= 0) {
+    return Buffer.alloc(0);
+  }
+  const buffer = Buffer.alloc(length);
+  const bytesRead = readSync(fd, buffer, 0, length, position);
+  if (bytesRead !== length) {
+    return undefined;
+  }
+  return buffer;
+}
+
+/**
+ * Read and decompress the `manifest.json` entry from a zip archive using
+ * positional reads, without any third-party dependency and without buffering
+ * the whole archive. Only the End-Of-Central-Directory record, the central
+ * directory, and the single manifest entry are read, so an untrusted bundle is
+ * never fully expanded.
+ *
+ * Zip64 archives (more than 65535 entries, or offsets beyond 4 GiB) are not
+ * decoded; such a bundle is skipped with a debug log rather than mis-read.
+ *
+ * @param {string} filePath Path to the .mcpb/.dxt bundle
+ * @returns {string|undefined} Decoded manifest.json text, or undefined
+ */
+function readManifestFromBundle(filePath) {
+  let fd;
+  try {
+    const size = statSync(filePath).size;
+    if (size < 22) {
+      return undefined;
+    }
+    fd = openSync(filePath, "r");
+    const eocd = findEndOfCentralDirectory(fd, size);
+    if (!eocd) {
+      debugSkip(filePath, "no end-of-central-directory record");
+      return undefined;
+    }
+    if (eocd.entryCount === 0xffff || eocd.centralDirOffset === 0xffffffff) {
+      debugSkip(filePath, "zip64 archive is not supported");
+      return undefined;
+    }
+    if (eocd.centralDirSize > MAX_CENTRAL_DIR_BYTES) {
+      debugSkip(filePath, "central directory exceeds the read cap");
+      return undefined;
+    }
+    const central = readRange(fd, eocd.centralDirOffset, eocd.centralDirSize);
+    if (!central) {
+      debugSkip(filePath, "could not read the central directory");
+      return undefined;
+    }
+    const entry = findManifestEntry(central, eocd.entryCount);
+    if (!entry) {
+      return undefined;
+    }
+    const data = readLocalEntry(fd, size, entry);
+    if (data === undefined) {
+      debugSkip(filePath, "could not inflate the manifest entry");
+    }
+    return data;
+  } catch (err) {
+    debugSkip(filePath, err?.message || "read error");
+    return undefined;
+  } finally {
+    if (fd !== undefined) {
+      try {
+        closeSync(fd);
+      } catch {
+        // ignore close failures
+      }
+    }
+  }
+}
+
+function debugSkip(filePath, reason) {
+  if (DEBUG_MODE) {
+    console.log(`Skipping MCPB bundle ${filePath}: ${reason}`);
+  }
+}
+
+function findEndOfCentralDirectory(fd, size) {
+  const scanLength = Math.min(size, MAX_EOCD_SCAN_BYTES);
+  const start = size - scanLength;
+  const tail = readRange(fd, start, scanLength);
+  if (!tail) {
+    return undefined;
+  }
+  for (let offset = tail.length - 22; offset >= 0; offset--) {
+    if (tail.readUInt32LE(offset) === EOCD_SIGNATURE) {
+      return {
+        entryCount: tail.readUInt16LE(offset + 10),
+        centralDirSize: tail.readUInt32LE(offset + 12),
+        centralDirOffset: tail.readUInt32LE(offset + 16),
+      };
+    }
+  }
+  return undefined;
+}
+
+function findManifestEntry(central, entryCount) {
+  let pointer = 0;
+  for (let index = 0; index < entryCount; index++) {
+    if (pointer + 46 > central.length) {
+      return undefined;
+    }
+    if (central.readUInt32LE(pointer) !== CENTRAL_SIGNATURE) {
+      return undefined;
+    }
+    const compressionMethod = central.readUInt16LE(pointer + 10);
+    const compressedSize = central.readUInt32LE(pointer + 20);
+    const uncompressedSize = central.readUInt32LE(pointer + 24);
+    const fileNameLength = central.readUInt16LE(pointer + 28);
+    const extraLength = central.readUInt16LE(pointer + 30);
+    const commentLength = central.readUInt16LE(pointer + 32);
+    const localHeaderOffset = central.readUInt32LE(pointer + 42);
+    const fileName = central
+      .subarray(pointer + 46, pointer + 46 + fileNameLength)
+      .toString("utf-8");
+    const normalizedName = fileName.replaceAll("\\", "/");
+    const isManifest =
+      normalizedName === "manifest.json" ||
+      normalizedName.endsWith("/manifest.json");
+    if (isManifest && uncompressedSize <= MAX_MANIFEST_BYTES) {
+      return { compressionMethod, compressedSize, localHeaderOffset };
+    }
+    pointer += 46 + fileNameLength + extraLength + commentLength;
+  }
+  return undefined;
+}
+
+function readLocalEntry(fd, size, entry) {
+  const { localHeaderOffset, compressionMethod, compressedSize } = entry;
+  // Bound the compressed read for every method, not just stored entries. The
+  // size comes from the archive's own central directory, so without this a
+  // hostile bundle could declare a multi-gigabyte entry and force that much to
+  // be allocated before `maxOutputLength` ever gets a chance to apply. A
+  // deflate stream that inflates to at most MAX_MANIFEST_BYTES cannot
+  // meaningfully exceed that compressed.
+  if (compressedSize > MAX_MANIFEST_BYTES) {
+    return undefined;
+  }
+  const header = readRange(fd, localHeaderOffset, 30);
+  if (!header || header.readUInt32LE(0) !== LOCAL_SIGNATURE) {
+    return undefined;
+  }
+  const fileNameLength = header.readUInt16LE(26);
+  const extraLength = header.readUInt16LE(28);
+  const dataStart = localHeaderOffset + 30 + fileNameLength + extraLength;
+  if (dataStart + compressedSize > size) {
+    return undefined;
+  }
+  const compressed = readRange(fd, dataStart, compressedSize);
+  if (!compressed) {
+    return undefined;
+  }
+  try {
+    if (compressionMethod === 0) {
+      return compressed.toString("utf-8");
+    }
+    if (compressionMethod === 8) {
+      // Bound the inflated output: the central-directory size field is
+      // attacker-controlled, so the real guard is the output length limit.
+      return inflateRawSync(compressed, {
+        maxOutputLength: MAX_MANIFEST_BYTES,
+      }).toString("utf-8");
+    }
+  } catch {
+    return undefined;
+  }
+  return undefined;
+}
+
+function addUniqueProperty(properties, name, value) {
+  const sanitizedValue = sanitizeBomPropertyValue(name, value);
+  if (
+    sanitizedValue === undefined ||
+    sanitizedValue === null ||
+    sanitizedValue === ""
+  ) {
+    return;
+  }
+  if (
+    properties.some(
+      (property) =>
+        property.name === name && property.value === String(sanitizedValue),
+    )
+  ) {
+    return;
+  }
+  properties.push({ name, value: String(sanitizedValue) });
+}
+
+function countCollection(value) {
+  if (Array.isArray(value)) {
+    return value.length;
+  }
+  if (value && typeof value === "object") {
+    return Object.keys(value).length;
+  }
+  return 0;
+}
+
+/**
+ * Count how many declared user-configuration fields look secret-bearing.
+ *
+ * The MCPB client injects `user_config` values as environment variables when it
+ * launches the bundled server, so secret-typed fields are a credential surface
+ * worth surfacing. Only field names and types are inspected; no user-provided
+ * values are read or emitted.
+ *
+ * @param {Object|Array} userConfig Declared user_config block
+ * @returns {{ fieldCount: number, secretFieldCount: number }} field counts
+ */
+function summarizeUserConfig(userConfig) {
+  const entries = Array.isArray(userConfig)
+    ? userConfig.map((entry) => [entry?.key || entry?.name || "", entry])
+    : Object.entries(userConfig || {});
+  let secretFieldCount = 0;
+  for (const [key, definition] of entries) {
+    const type = String(definition?.type || "").toLowerCase();
+    const sensitive =
+      definition?.sensitive === true ||
+      type === "secret" ||
+      type === "password" ||
+      SECRET_FIELD_NAME_PATTERN.test(String(key));
+    if (sensitive) {
+      secretFieldCount++;
+    }
+  }
+  return { fieldCount: entries.length, secretFieldCount };
+}
+
+/**
+ * Count how many precompiled platform binaries a bundle declares across the
+ * `server.mcp_config.platform_overrides` / `compatibility.platforms` shapes
+ * used by MCPB manifests.
+ *
+ * @param {Object} manifest Parsed manifest.json
+ * @returns {number} platform binary count
+ */
+function platformBinaryCount(manifest) {
+  const overrides =
+    manifest?.server?.mcp_config?.platform_overrides ||
+    manifest?.server?.platform_overrides;
+  if (overrides) {
+    return countCollection(overrides);
+  }
+  const platforms = manifest?.compatibility?.platforms || manifest?.platforms;
+  return countCollection(platforms);
+}
+
+/**
+ * Build a component from a parsed MCPB manifest.
+ *
+ * @param {string} filePath Bundle path
+ * @param {Object} manifest Parsed manifest.json
+ * @returns {Object} CycloneDX component
+ */
+function componentFromManifest(filePath, manifest) {
+  const name =
+    (typeof manifest?.name === "string" && manifest.name) || basename(filePath);
+  const serverType = String(manifest?.server?.type || "").toLowerCase();
+  const userConfig = summarizeUserConfig(manifest?.user_config);
+  const properties = [
+    { name: "internal:SrcFile", value: filePath },
+    { name: "cdx:file:kind", value: "mcp-bundle" },
+    { name: "cdx:mcp:inventorySource", value: "mcp-bundle" },
+    // A bundle ships a whole local server plus its dependencies, so treat it as
+    // an install-time supply-chain surface that warrants review.
+    { name: "cdx:mcp:reviewNeeded", value: "true" },
+  ];
+  addUniqueProperty(
+    properties,
+    "cdx:mcpb:manifestVersion",
+    manifest?.manifest_version ? String(manifest.manifest_version) : undefined,
+  );
+  addUniqueProperty(properties, "cdx:mcpb:serverType", serverType || undefined);
+  addUniqueProperty(
+    properties,
+    "cdx:mcpb:toolCount",
+    String(countCollection(manifest?.tools)),
+  );
+  addUniqueProperty(
+    properties,
+    "cdx:mcpb:promptCount",
+    String(countCollection(manifest?.prompts)),
+  );
+  addUniqueProperty(
+    properties,
+    "cdx:mcpb:userConfigFieldCount",
+    String(userConfig.fieldCount),
+  );
+  if (userConfig.secretFieldCount) {
+    addUniqueProperty(
+      properties,
+      "cdx:mcpb:secretFieldCount",
+      String(userConfig.secretFieldCount),
+    );
+    addUniqueProperty(properties, "cdx:mcpb:injectsSecretEnv", "true");
+  }
+  const binaryCount = platformBinaryCount(manifest);
+  if (binaryCount) {
+    addUniqueProperty(
+      properties,
+      "cdx:mcpb:platformBinaryCount",
+      String(binaryCount),
+    );
+  }
+  const component = {
+    "bom-ref": `urn:mcp:bundle:${sanitizeMcpRefToken(name)}:${sanitizeMcpRefToken(basename(filePath))}`,
+    type: "application",
+    name,
+    properties,
+  };
+  if (manifest?.version) {
+    component.version = String(manifest.version);
+  }
+  // The description is attacker-controlled free text from an untrusted zip.
+  // Sanitize, truncate, and scan it for hidden Unicode like the sibling
+  // manifest/agent parsers do, rather than copying it verbatim.
+  if (typeof manifest?.description === "string") {
+    const sanitizedDescription = sanitizeBomPropertyValue(
+      "description",
+      manifest.description.slice(0, MAX_DESCRIPTION_BYTES),
+    );
+    if (sanitizedDescription) {
+      component.description = String(sanitizedDescription);
+    }
+    const hiddenUnicodeScan = scanTextForHiddenUnicode(manifest.description, {
+      syntax: "text",
+    });
+    if (hiddenUnicodeScan.hasHiddenUnicode) {
+      addUniqueProperty(
+        component.properties,
+        "cdx:file:hasHiddenUnicode",
+        "true",
+      );
+      addUniqueProperty(
+        component.properties,
+        "cdx:file:hiddenUnicodeCodePoints",
+        hiddenUnicodeScan.codePoints.join(","),
+      );
+    }
+  }
+  return component;
+}
+
+/**
+ * Parser for MCPB / DXT desktop-extension bundles.
+ *
+ * A bundle is a zip archive carrying a local MCP server, its dependencies, and
+ * a `manifest.json`. This parser reads only the manifest to describe the
+ * bundled server, the tools/prompts it exposes, the number of precompiled
+ * platform binaries, and whether it injects secret-typed configuration values
+ * as environment variables.
+ *
+ * @type {{id: string, patterns: string[], parse(files: string[], options?: Object): {components: Object[]}}}
+ */
+export const mcpbBundleParser = {
+  id: "mcp-bundle",
+  patterns: MCPB_BUNDLE_PATTERNS,
+  parse(files, _options = {}) {
+    const components = [];
+    for (const filePath of [...new Set(files || [])]) {
+      const manifestText = readManifestFromBundle(filePath);
+      if (!manifestText) {
+        continue;
+      }
+      let manifest;
+      try {
+        manifest = JSON.parse(manifestText);
+      } catch {
+        continue;
+      }
+      if (!manifest || typeof manifest !== "object") {
+        continue;
+      }
+      components.push(componentFromManifest(filePath, manifest));
+    }
+    return { components };
+  },
+};

package/lib/inventory/osinfo.js

@@ -288,6 +288,7 @@ export function getDistroInfo(root = "/") {
       purlType = "deb";
       break;
     case "alpine":
+    case "alpaquita":
     case "openwrt":
       purlType = "apk";
       break;

package/lib/inventory/plugins.js

@@ -19,6 +19,7 @@ const PLUGIN_ENV_COMMAND_NAMES = {
   trivy: "TRIVY_CMD",
   trustinspector: "TRUSTINSPECTOR_CMD",
   cdxui: "CDXUI_CMD",
+  kosi: "KOSI_CMD",
 };
 
 function isMusl() {
@@ -41,6 +42,7 @@ function hasUsablePluginsDir(pluginsDir) {
         "trivy",
         "trustinspector",
         "cdxui",
+        "kosi",
       ].some((pluginName) => safeExistsSync(join(pluginsDir, pluginName))))
   );
 }
@@ -431,6 +433,7 @@ function resolveBundledPluginBinary(toolName, pluginRuntime) {
     case "rusi":
     case "cdxrs":
     case "cdxui":
+    case "kosi":
       return join(
         pluginRuntime.pluginsDir,
         toolName,

package/lib/inventory/protobom.js

@@ -3,18 +3,19 @@ import { readFileSync } from "node:fs";
 import {
   bomStats,
   convertBom,
-  createBom,
   decodeBomBinary,
-  decodeBomJson,
   encodeBomBinary,
   encodeBomJson,
+  isSupportedSpecVersion,
   parseBomBinary,
-  parseBomJson,
   supportedSpecVersions,
+  toBomMessage,
 } from "@cdxgen/cdx-proto";
+import { isProtoBomFile } from "@cdxgen/cdx-proto/node";
 
 import { safeExistsSync, safeWriteSync } from "../core/fs.js";
-import { toCycloneDxSpecVersionString } from "./bomUtils.js";
+
+export { isProtoBomFile };
 
 const JSON_READ_OPTIONS = {
   ignoreUnknownFields: true,
@@ -28,35 +29,8 @@ const BINARY_WRITE_OPTIONS = {
   writeUnknownFields: true,
 };
 
-const PROTO_BOM_FILE_EXTENSIONS = [".cdx", ".cdx.bin", ".proto"];
-
 const DEFAULT_SPEC_VERSION =
   supportedSpecVersions[supportedSpecVersions.length - 1];
-const PROTO_SUPPORTED_SPEC_VERSIONS = new Set(
-  supportedSpecVersions.map((specVersion) =>
-    toCycloneDxSpecVersionString(specVersion),
-  ),
-);
-
-const isProtoMessageBom = (bom) =>
-  Boolean(
-    bom &&
-      typeof bom === "object" &&
-      !Array.isArray(bom) &&
-      typeof bom.$typeName === "string" &&
-      bom.specVersion,
-  );
-
-const hasExplicitSpecVersion = (bomJson) =>
-  Boolean(
-    bomJson &&
-      typeof bomJson === "object" &&
-      !Array.isArray(bomJson) &&
-      (bomJson.specVersion !== undefined || bomJson.spec_version !== undefined),
-  );
-
-const resolveExplicitSpecVersion = (bomJson) =>
-  bomJson?.specVersion ?? bomJson?.spec_version;
 
 const hasProvidedSpecVersion = (specVersion) =>
   specVersion !== undefined &&
@@ -66,19 +40,15 @@ const hasProvidedSpecVersion = (specVersion) =>
 /**
  * Determine whether a spec version is supported for protobuf serialization.
  *
+ * Delegates to cdx-proto's `isSupportedSpecVersion`, which accepts the
+ * spellings seen in the wild (`v1.6`, `1.6`, `1.6.0`) in addition to the
+ * canonical strings.
+ *
  * @param {string|undefined} specVersion CycloneDX spec version string
  * @returns {boolean} `true` when supported by `@cdxgen/cdx-proto`, or when no spec version is provided
  */
-export const isProtoSupportedSpecVersion = (specVersion) => {
-  if (!hasProvidedSpecVersion(specVersion)) {
-    return true;
-  }
-  const normalizedSpecVersion = toCycloneDxSpecVersionString(specVersion);
-  return (
-    normalizedSpecVersion !== undefined &&
-    PROTO_SUPPORTED_SPEC_VERSIONS.has(normalizedSpecVersion)
-  );
-};
+export const isProtoSupportedSpecVersion = (specVersion) =>
+  !hasProvidedSpecVersion(specVersion) || isSupportedSpecVersion(specVersion);
 
 /**
  * Assert that a spec version is supported by `@cdxgen/cdx-proto`.
@@ -94,56 +64,42 @@ export const assertProtoSupportedSpecVersion = (
   specVersion,
   operation = "protobuf operations",
 ) => {
-  if (!hasProvidedSpecVersion(specVersion)) {
-    return;
-  }
-  const normalizedSpecVersion = toCycloneDxSpecVersionString(specVersion);
   if (isProtoSupportedSpecVersion(specVersion)) {
     return;
   }
-  const displaySpecVersion = normalizedSpecVersion || `${specVersion}`.trim();
   throw new Error(
-    `CycloneDX ${displaySpecVersion} is not currently supported for ${operation}. @cdxgen/cdx-proto supports ${supportedSpecVersions.join(", ")} only.`,
+    `CycloneDX ${`${specVersion}`.trim()} is not currently supported for ${operation}. @cdxgen/cdx-proto supports ${supportedSpecVersions.join(", ")} only.`,
   );
 };
 
-const resolveBomMessage = (bomJson, specVersion = DEFAULT_SPEC_VERSION) => {
-  if (isProtoMessageBom(bomJson)) {
-    return bomJson;
-  }
-  const parsedBomJson =
-    typeof bomJson === "string" || bomJson instanceof String
-      ? JSON.parse(`${bomJson}`)
-      : bomJson;
-  if (
-    parsedBomJson &&
-    typeof parsedBomJson === "object" &&
-    !Array.isArray(parsedBomJson)
-  ) {
-    if (hasExplicitSpecVersion(parsedBomJson)) {
-      assertProtoSupportedSpecVersion(
-        resolveExplicitSpecVersion(parsedBomJson),
-        "protobuf serialization",
-      );
-      return parseBomJson(parsedBomJson, JSON_READ_OPTIONS);
+const resolveExplicitInputSpecVersion = (bomJson) => {
+  if (bomJson && typeof bomJson === "object" && !Array.isArray(bomJson)) {
+    const explicitSpecVersion = bomJson.specVersion ?? bomJson.spec_version;
+    if (hasProvidedSpecVersion(explicitSpecVersion)) {
+      return explicitSpecVersion;
     }
-    assertProtoSupportedSpecVersion(specVersion, "protobuf serialization");
-    return decodeBomJson(specVersion, parsedBomJson, JSON_READ_OPTIONS);
   }
-  return createBom(specVersion);
+  return undefined;
 };
 
 /**
- * Determine whether a path looks like a CycloneDX protobuf file.
+ * Coerce a BOM input into a decoded message via cdx-proto's `toBomMessage`
+ * (messages pass through, JSON strings are parsed, canonical JSON objects are
+ * decoded, anything else yields an empty BOM). The version is asserted first
+ * so an unsupported BOM keeps failing with cdxgen's operation-specific error
+ * rather than cdx-proto's generic one.
  *
- * @param {string} filePath File path
- * @returns {boolean} true when the path looks like a protobuf BOM file
+ * @param {string | Object} bomJson BOM Json, BOM Json string, or proto message
+ * @param {string | number} specVersion CycloneDX spec version fallback for BOMs without specVersion
+ * @param {string} operation Operation label used in the error message
+ * @returns {Object} Decoded BOM message
  */
-export const isProtoBomFile = (filePath) => {
-  const normalizedPath = `${filePath || ""}`.toLowerCase();
-  return PROTO_BOM_FILE_EXTENSIONS.some((extension) =>
-    normalizedPath.endsWith(extension),
+const toSerializableBomMessage = (bomJson, specVersion, operation) => {
+  assertProtoSupportedSpecVersion(
+    resolveExplicitInputSpecVersion(bomJson) ?? specVersion,
+    operation,
   );
+  return toBomMessage(bomJson, specVersion, JSON_READ_OPTIONS);
 };
 
 /**
@@ -159,7 +115,11 @@ export const writeBinary = (
   specVersion = DEFAULT_SPEC_VERSION,
 ) => {
   if (bomJson && binFile) {
-    const bomMessage = resolveBomMessage(bomJson, specVersion);
+    const bomMessage = toSerializableBomMessage(
+      bomJson,
+      specVersion,
+      "protobuf serialization",
+    );
     safeWriteSync(binFile, encodeBomBinary(bomMessage, BINARY_WRITE_OPTIONS));
   }
 };
@@ -196,19 +156,27 @@ export const readBinary = (binFile, asJson, specVersion) => {
  * @returns {Object} Component and dependency counts with JSON/binary byte sizes and compression ratio
  */
 export const getBomStats = (bomJson, specVersion = DEFAULT_SPEC_VERSION) =>
-  bomStats(resolveBomMessage(bomJson, specVersion));
+  bomStats(
+    toSerializableBomMessage(bomJson, specVersion, "protobuf statistics"),
+  );
 
 /**
  * Method to cross-convert a BOM between CycloneDX specification versions using
  * the protobuf schemas.
  *
- * Downgrades are lossy: fields that the target version does not define are
- * dropped and reported in `warnings` as field paths.
+ * cdx-proto's conversion is cardinality-safe: fields that change shape between
+ * versions (`metadata.licenses` and `evidence.identity`, singular in 1.5 and an
+ * array since 1.6) are reshaped automatically — wrapped on upgrade, collapsed
+ * to their first entry on downgrade — including `evidence.identity` on nested
+ * components, `metadata.component`, `metadata.tools.components[]`, and
+ * `formulation[].components[]`. Downgrades are otherwise lossy: fields the
+ * target version does not define are dropped and reported in `warnings` as
+ * field paths, alongside collapsed list siblings.
  *
- * This is the raw `@cdxgen/cdx-proto` conversion. It reshapes nothing that the
- * two schemas model with different cardinality, so a BOM crossing the 1.5/1.6
- * `evidence.identity` boundary must be normalized first. Prefer
- * `applySpecVersionCompatibility` from the postgen stage for that.
+ * Only the protobuf-supported versions (1.5–1.7) can be targeted here. For the
+ * full JSON-level normalization across every version cdxgen emits (component
+ * types, license attributes, 1.4/2.0 reshaping), prefer
+ * `applySpecVersionCompatibility` from the postgen stage.
  *
  * @param {string | Object} bomJson BOM Json, BOM Json string, or proto message
  * @param {string | number} targetSpecVersion Target CycloneDX spec version
@@ -221,11 +189,9 @@ export const convertBomSpecVersion = (
   specVersion = DEFAULT_SPEC_VERSION,
 ) => {
   assertProtoSupportedSpecVersion(targetSpecVersion, "protobuf conversion");
-  const normalizedTargetSpecVersion =
-    toCycloneDxSpecVersionString(targetSpecVersion) || `${targetSpecVersion}`;
   const { bom, warnings } = convertBom(
-    resolveBomMessage(bomJson, specVersion),
-    normalizedTargetSpecVersion,
+    toSerializableBomMessage(bomJson, specVersion, "protobuf conversion"),
+    targetSpecVersion,
   );
   return { bomJson: encodeBomJson(bom), warnings };
 };

package/lib/inventory/protobomLoader.js

@@ -1,3 +1,7 @@
+// Kept local (not imported from `@cdxgen/cdx-proto/node`) because this module
+// gates whether the optional protobuf dependency is loaded at all. The
+// authoritative list is `protoBomFileExtensions` in `@cdxgen/cdx-proto/node`;
+// keep the two in sync.
 const PROTO_BOM_FILE_EXTENSIONS = [".cdx", ".cdx.bin", ".proto"];
 
 /**

package/lib/inventory/rustFormulationParser.js

@@ -1,7 +1,7 @@
 import { readFileSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 
-import toml from "@iarna/toml";
+import * as toml from "smol-toml";
 
 import { safeExistsSync } from "../core/fs.js";