@socketsecurity/lib 5.27.0 → 6.0.0

package/dist/external-tools/bazel/resolve.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @file `resolveBazel()` — Bazel resolution entry point. Tries each source in
+ *   order:
+ *
+ *   1. PATH — `bazelisk` (preferred) or `bazel` on the system PATH
+ *   2. download — upstream GitHub release binary (only when `downloadIfMissing` is
+ *      passed) No VFS tier: Bazel's version comes from the project's
+ *      `.bazelversion`, not from a global pin, so a smol-bundled Bazel would
+ *      always be the wrong version for any project that pinned a different one.
+ *      Every Bazel use must go through the project-specific download path.
+ *      Returns `undefined` if all of the enabled sources miss. Memoized per
+ *      option-shape: calls with identical options return the same cached
+ *      promise. Calling without `downloadIfMissing` and then with
+ *      `downloadIfMissing` produces two distinct cache entries so the second
+ *      call can fall through to the download tier.
+ */
+import type { BinaryDownloader } from '../from-download';
+import type { HashSpec } from '../../integrity';
+import type { ResolvedBazel } from './types';
+export interface ResolveBazelOptions {
+    /**
+     * When set, the resolver falls through to a GitHub release download after the
+     * local-discovery tiers miss. Omit to keep the resolver read-only.
+     */
+    downloadIfMissing?: {
+        version: string;
+        platformArch: string;
+        integrity?: HashSpec | undefined;
+        downloader?: BinaryDownloader | undefined;
+    } | undefined;
+}
+export declare function cacheKey(opts: ResolveBazelOptions | undefined): string;
+export declare function doResolveBazel(opts?: ResolveBazelOptions | undefined): Promise<ResolvedBazel | undefined>;
+export declare function resetBazelResolution(): void;
+export declare function resolveBazel(opts?: ResolveBazelOptions | undefined): Promise<ResolvedBazel | undefined>;

package/dist/external-tools/bazel/resolve.js

@@ -0,0 +1,68 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var resolve_exports = {};
+__export(resolve_exports, {
+  cacheKey: () => cacheKey,
+  doResolveBazel: () => doResolveBazel,
+  resetBazelResolution: () => resetBazelResolution,
+  resolveBazel: () => resolveBazel
+});
+module.exports = __toCommonJS(resolve_exports);
+var import_from_download = require("./from-download");
+var import_from_path = require("./from-path");
+const resolutionCache = /* @__PURE__ */ new Map();
+function cacheKey(opts) {
+  if (!opts?.downloadIfMissing) {
+    return "local-only";
+  }
+  const { integrity, platformArch, version } = opts.downloadIfMissing;
+  const integrityKey = typeof integrity === "string" ? integrity : integrity ? `${integrity.type}:${integrity.value}` : "";
+  return `dl:${version}:${platformArch}:${integrityKey}`;
+}
+async function doResolveBazel(opts) {
+  const fromPath = await (0, import_from_path.bazelFromPath)();
+  if (fromPath) {
+    return fromPath;
+  }
+  if (opts?.downloadIfMissing) {
+    return (0, import_from_download.bazelFromDownload)(opts.downloadIfMissing);
+  }
+  return void 0;
+}
+function resetBazelResolution() {
+  resolutionCache.clear();
+}
+function resolveBazel(opts) {
+  const key = cacheKey(opts);
+  let cached = resolutionCache.get(key);
+  if (!cached) {
+    cached = doResolveBazel(opts);
+    resolutionCache.set(key, cached);
+  }
+  return cached;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  cacheKey,
+  doResolveBazel,
+  resetBazelResolution,
+  resolveBazel
+});

package/dist/external-tools/bazel/types.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @file Shared types for Bazel resolution.
+ */
+import type { ResolvedToolIntegrity } from '../from-download';
+export type BazelSource = 'download' | 'path';
+/**
+ * A resolved Bazel installation.
+ */
+export interface ResolvedBazel {
+    /**
+     * Absolute path to the `bazel` (or `bazelisk`) executable.
+     */
+    readonly path: string;
+    /**
+     * Which resolver tier found this.
+     */
+    readonly source: BazelSource;
+    /**
+     * See {@link ResolvedToolIntegrity}.
+     */
+    readonly integrity?: ResolvedToolIntegrity;
+}

package/dist/external-tools/bazel/types.js

@@ -0,0 +1,18 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var types_exports = {};
+module.exports = __toCommonJS(types_exports);

package/dist/external-tools/cdxgen/asset-names.d.ts

@@ -0,0 +1,58 @@
+/**
+ * @file Upstream cdxgen release asset-name mapping per `platform-arch`. cdxgen
+ *   ships per-platform SEA binaries starting in v12.0.x — bare executables, no
+ *   archive wrapper, with companion `.sha256` sidecars. Each platform has both
+ *   a "full" variant (bundles bun + deno runtimes for those project types) and
+ *   a "slim" variant (no bundled runtimes; relies on the host having them when
+ *   needed). We ship the slim variants by default: socket-lib consumers run
+ *   cdxgen for npm/pip/maven/etc. SBOM generation where the bundled runtimes
+ *   aren't on the hot path, and the slim binary is ~3× smaller. Consumers that
+ *   need full (bun/deno project scanning) can override by passing `variant:
+ *   'full'`. Asset URLs:
+ *   https://github.com/CycloneDX/cdxgen/releases/download/v<X.Y.Z>/cdxgen-<os>-<arch>[-musl][-slim][.exe]
+ *   Reference: https://github.com/CycloneDX/cdxgen/releases. Single source of
+ *   truth: the SEA binary IS the install path. The legacy `@cyclonedx/cdxgen`
+ *   npm package is not used as a fallback — every platform-arch the fleet
+ *   supports has a SEA build, and routing through npm for unsupported targets
+ *   would silently use a different distribution (different bundle composition,
+ *   different startup cost, different version-pin surface). One install path;
+ *   one cached binary.
+ */
+export interface CdxgenAssetEntry {
+    /**
+     * Full asset filename. Version-free — the release tag is the version.
+     */
+    readonly asset: string;
+}
+/**
+ * Pull `variant: 'slim'` (default — no bundled runtimes) or `'full'` (bundles
+ * bun + deno runtimes; ~3× larger).
+ */
+export type CdxgenVariant = 'full' | 'slim';
+export interface CdxgenDownloadOptions {
+    /**
+     * Cdxgen release version, e.g. `'12.4.1'`. Bare semver; the helper prepends
+     * `v` for the release tag.
+     */
+    version: string;
+    /**
+     * Fleet platform-arch token — looked up in the asset map. Returns `undefined`
+     * when no entry exists for the target.
+     */
+    platformArch: string;
+    /**
+     * Slim (no bundled bun/deno) or full (bundles both). Defaults to slim.
+     */
+    variant?: CdxgenVariant | undefined;
+}
+export declare function buildCdxgenAssetName(baseTriple: string, variant: CdxgenVariant, ext: '' | '.exe'): string;
+export declare function getCdxgenAssetEntry(platformArch: string, variant?: CdxgenVariant): CdxgenAssetEntry | undefined;
+/**
+ * Build the GitHub release-asset download URL for an upstream cdxgen binary.
+ * Returns `undefined` when no entry exists for the requested platform-arch.
+ */
+export declare function getCdxgenDownloadUrl(opts: CdxgenDownloadOptions): string | undefined;
+export declare function makeCdxgenEntry(baseTriple: string, variant: CdxgenVariant, ext?: '' | '.exe'): CdxgenAssetEntry;
+export declare function makeCdxgenPlatformMap(variant: CdxgenVariant): Readonly<Record<string, CdxgenAssetEntry>>;
+export declare const CDXGEN_SLIM_ASSET_MAP: Readonly<Record<string, CdxgenAssetEntry>>;
+export declare const CDXGEN_FULL_ASSET_MAP: Readonly<Record<string, CdxgenAssetEntry>>;

package/dist/external-tools/cdxgen/asset-names.js

@@ -0,0 +1,79 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var asset_names_exports = {};
+__export(asset_names_exports, {
+  CDXGEN_FULL_ASSET_MAP: () => CDXGEN_FULL_ASSET_MAP,
+  CDXGEN_SLIM_ASSET_MAP: () => CDXGEN_SLIM_ASSET_MAP,
+  buildCdxgenAssetName: () => buildCdxgenAssetName,
+  getCdxgenAssetEntry: () => getCdxgenAssetEntry,
+  getCdxgenDownloadUrl: () => getCdxgenDownloadUrl,
+  makeCdxgenEntry: () => makeCdxgenEntry,
+  makeCdxgenPlatformMap: () => makeCdxgenPlatformMap
+});
+module.exports = __toCommonJS(asset_names_exports);
+var import_object = require("../../primordials/object");
+function buildCdxgenAssetName(baseTriple, variant, ext) {
+  const slim = variant === "slim" ? "-slim" : "";
+  return `cdxgen-${baseTriple}${slim}${ext}`;
+}
+function getCdxgenAssetEntry(platformArch, variant = "slim") {
+  const map = variant === "full" ? CDXGEN_FULL_ASSET_MAP : CDXGEN_SLIM_ASSET_MAP;
+  return map[platformArch];
+}
+function getCdxgenDownloadUrl(opts) {
+  const { platformArch, variant = "slim", version } = opts;
+  const entry = getCdxgenAssetEntry(platformArch, variant);
+  if (!entry) {
+    return void 0;
+  }
+  return `https://github.com/CycloneDX/cdxgen/releases/download/v${version}/` + entry.asset;
+}
+function makeCdxgenEntry(baseTriple, variant, ext = "") {
+  return (0, import_object.ObjectFreeze)({
+    __proto__: null,
+    asset: buildCdxgenAssetName(baseTriple, variant, ext)
+  });
+}
+function makeCdxgenPlatformMap(variant) {
+  return (0, import_object.ObjectFreeze)({
+    __proto__: null,
+    "darwin-arm64": makeCdxgenEntry("darwin-arm64", variant),
+    "darwin-x64": makeCdxgenEntry("darwin-amd64", variant),
+    "linux-arm64": makeCdxgenEntry("linux-arm64", variant),
+    "linux-arm64-musl": makeCdxgenEntry("linux-arm64-musl", variant),
+    "linux-x64": makeCdxgenEntry("linux-amd64", variant),
+    "linux-x64-musl": makeCdxgenEntry("linux-amd64-musl", variant),
+    "win-arm64": makeCdxgenEntry("windows-arm64", variant, ".exe"),
+    "win-x64": makeCdxgenEntry("windows-amd64", variant, ".exe")
+  });
+}
+const CDXGEN_SLIM_ASSET_MAP = makeCdxgenPlatformMap("slim");
+const CDXGEN_FULL_ASSET_MAP = makeCdxgenPlatformMap("full");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CDXGEN_FULL_ASSET_MAP,
+  CDXGEN_SLIM_ASSET_MAP,
+  buildCdxgenAssetName,
+  getCdxgenAssetEntry,
+  getCdxgenDownloadUrl,
+  makeCdxgenEntry,
+  makeCdxgenPlatformMap
+});

package/dist/external-tools/cdxgen/from-download.d.ts

@@ -0,0 +1,43 @@
+/**
+ * @file `cdxgenFromDownload()` — fetches the upstream cdxgen SEA binary (slim
+ *   by default) and returns a `ResolvedCdxgen` pointing at the cached
+ *   executable. cdxgen ships bare-binary assets per platform (no archive
+ *   wrapper) with sidecar `.sha256` files; this helper passes the pinned
+ *   integrity through `downloadToolArchive`, then copies the downloaded blob to
+ *   `cdxgen[.exe]` and chmods it 0o755. Platforms upstream doesn't ship a SEA
+ *   for (none today; the asset map covers all 8 fleet targets) return
+ *   `undefined` — callers should fall back to `cdxgenFromNpm()` for those.
+ */
+import type { BinaryDownloader } from '../from-download';
+import type { HashSpec } from '../../integrity';
+import type { CdxgenVariant } from './asset-names';
+import type { ResolvedCdxgen } from './types';
+export interface CdxgenFromDownloadOptions {
+    /**
+     * Cdxgen release version, e.g. `'12.4.1'`.
+     */
+    version: string;
+    /**
+     * Fleet platform-arch token, e.g. `'darwin-arm64'`.
+     */
+    platformArch: string;
+    /**
+     * Slim (default — no bundled bun/deno) or full (bundles both).
+     */
+    variant?: CdxgenVariant | undefined;
+    /**
+     * Optional pinned integrity from `external-tools.json`.
+     */
+    integrity?: HashSpec | undefined;
+    /**
+     * Override the cache directory. By default the binary lands under
+     * `<getSocketDlxDir()>/cdxgen/<version>/<platformArch>-<variant>/`.
+     */
+    cacheDir?: string | undefined;
+    /**
+     * Inject a custom downloader. Forwarded to the underlying
+     * `downloadToolArchive`. Defaults to dlx.
+     */
+    downloader?: BinaryDownloader | undefined;
+}
+export declare function cdxgenFromDownload(opts: CdxgenFromDownloadOptions): Promise<ResolvedCdxgen | undefined>;

package/dist/external-tools/cdxgen/from-download.js

@@ -0,0 +1,83 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var from_download_exports = {};
+__export(from_download_exports, {
+  cdxgenFromDownload: () => cdxgenFromDownload
+});
+module.exports = __toCommonJS(from_download_exports);
+var import_node_fs = require("node:fs");
+var import_node_path = __toESM(require("node:path"));
+var import_node_process = __toESM(require("node:process"));
+var import_safe = require("../../fs/safe");
+var import_socket = require("../../paths/socket");
+var import_from_download = require("../from-download");
+var import_asset_names = require("./asset-names");
+async function cdxgenFromDownload(opts) {
+  const {
+    cacheDir,
+    downloader,
+    integrity,
+    platformArch,
+    variant = "slim",
+    version
+  } = opts;
+  const url = (0, import_asset_names.getCdxgenDownloadUrl)({ platformArch, variant, version });
+  const entry = (0, import_asset_names.getCdxgenAssetEntry)(platformArch, variant);
+  if (!url || !entry) {
+    return void 0;
+  }
+  const archive = await (0, import_from_download.downloadToolArchive)({
+    url,
+    name: `cdxgen-${version}-${platformArch}-${variant}-${entry.asset}`,
+    integrity,
+    downloader
+  });
+  const targetDir = cacheDir ?? import_node_path.default.join(
+    (0, import_socket.getSocketDlxDir)(),
+    "cdxgen",
+    version,
+    `${platformArch}-${variant}`
+  );
+  await (0, import_safe.safeMkdir)(targetDir);
+  const ext = import_node_process.default.platform === "win32" ? ".exe" : "";
+  const finalPath = import_node_path.default.join(targetDir, `cdxgen${ext}`);
+  await import_node_fs.promises.copyFile(archive.archivePath, finalPath);
+  await import_node_fs.promises.chmod(finalPath, 493);
+  return {
+    path: finalPath,
+    source: "download",
+    integrity: archive.integrity
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  cdxgenFromDownload
+});

package/dist/external-tools/cdxgen/from-path.d.ts

@@ -0,0 +1,5 @@
+/**
+ * @file `cdxgenFromPath()` — looks for `cdxgen` on the system PATH.
+ */
+import type { ResolvedCdxgen } from './types';
+export declare function cdxgenFromPath(): Promise<ResolvedCdxgen | undefined>;

package/dist/external-tools/cdxgen/from-path.js

@@ -0,0 +1,40 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var from_path_exports = {};
+__export(from_path_exports, {
+  cdxgenFromPath: () => cdxgenFromPath
+});
+module.exports = __toCommonJS(from_path_exports);
+var import_which = require("../../bin/which");
+async function cdxgenFromPath() {
+  const onPath = await (0, import_which.which)("cdxgen", { nothrow: true });
+  if (typeof onPath !== "string") {
+    return void 0;
+  }
+  return {
+    path: onPath,
+    source: "path"
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  cdxgenFromPath
+});

package/dist/external-tools/cdxgen/from-vfs.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @file `cdxgenFromVfs()` — extracts cdxgen from the smol binary's VFS. Returns
+ *   `undefined` when the binary doesn't carry a bundled cdxgen.
+ */
+import type { ResolvedCdxgen } from './types';
+export declare const CDXGEN_VFS_KEY = "cdxgen";
+export declare function cdxgenFromVfs(): Promise<ResolvedCdxgen | undefined>;

package/dist/external-tools/cdxgen/from-vfs.js

@@ -0,0 +1,47 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var from_vfs_exports = {};
+__export(from_vfs_exports, {
+  CDXGEN_VFS_KEY: () => CDXGEN_VFS_KEY,
+  cdxgenFromVfs: () => cdxgenFromVfs
+});
+module.exports = __toCommonJS(from_vfs_exports);
+var import_vfs = require("../../smol/vfs");
+const CDXGEN_VFS_KEY = "cdxgen";
+async function cdxgenFromVfs() {
+  const vfs = (0, import_vfs.getSmolVfs)();
+  if (!vfs) {
+    return void 0;
+  }
+  if (!vfs.has(CDXGEN_VFS_KEY)) {
+    return void 0;
+  }
+  const realPath = await vfs.extract(CDXGEN_VFS_KEY);
+  return {
+    path: realPath,
+    source: "vfs"
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CDXGEN_VFS_KEY,
+  cdxgenFromVfs
+});

package/dist/external-tools/cdxgen/resolve.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @file `resolveCdxgen()` — cdxgen resolution entry point. Tries each source in
+ *   order:
+ *
+ *   1. VFS — smol binary's embedded cdxgen (if packed)
+ *   2. PATH — `cdxgen` on the system PATH
+ *   3. download — upstream SEA binary from the GitHub release (slim by default;
+ *      pass `variant: 'full'` for the bun+deno-bundled flavor) Single source of
+ *      truth: SEA binary only. No npm-package fallback — every fleet
+ *      platform-arch is covered by the SEA matrix, and routing through npm
+ *      would split the install surface in two for no benefit. Returns
+ *      `undefined` if all of the enabled sources miss. Memoized per
+ *      option-shape.
+ */
+import type { BinaryDownloader } from '../from-download';
+import type { HashSpec } from '../../integrity';
+import type { CdxgenVariant } from './asset-names';
+import type { ResolvedCdxgen } from './types';
+export interface ResolveCdxgenOptions {
+    downloadIfMissing?: {
+        version: string;
+        platformArch: string;
+        variant?: CdxgenVariant | undefined;
+        integrity?: HashSpec | undefined;
+        cacheDir?: string | undefined;
+        downloader?: BinaryDownloader | undefined;
+    } | undefined;
+}
+export declare function cacheKey(opts: ResolveCdxgenOptions | undefined): string;
+export declare function doResolveCdxgen(opts?: ResolveCdxgenOptions | undefined): Promise<ResolvedCdxgen | undefined>;
+export declare function resetCdxgenResolution(): void;
+export declare function resolveCdxgen(opts?: ResolveCdxgenOptions | undefined): Promise<ResolvedCdxgen | undefined>;

package/dist/external-tools/cdxgen/resolve.js

@@ -0,0 +1,73 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var resolve_exports = {};
+__export(resolve_exports, {
+  cacheKey: () => cacheKey,
+  doResolveCdxgen: () => doResolveCdxgen,
+  resetCdxgenResolution: () => resetCdxgenResolution,
+  resolveCdxgen: () => resolveCdxgen
+});
+module.exports = __toCommonJS(resolve_exports);
+var import_from_download = require("./from-download");
+var import_from_path = require("./from-path");
+var import_from_vfs = require("./from-vfs");
+const resolutionCache = /* @__PURE__ */ new Map();
+function cacheKey(opts) {
+  if (!opts?.downloadIfMissing) {
+    return "local-only";
+  }
+  const { cacheDir, integrity, platformArch, variant, version } = opts.downloadIfMissing;
+  const integrityKey = typeof integrity === "string" ? integrity : integrity ? `${integrity.type}:${integrity.value}` : "";
+  return `dl:${version}:${platformArch}:${variant ?? "slim"}:${integrityKey}:${cacheDir ?? ""}`;
+}
+async function doResolveCdxgen(opts) {
+  const fromVfs = await (0, import_from_vfs.cdxgenFromVfs)();
+  if (fromVfs) {
+    return fromVfs;
+  }
+  const fromPath = await (0, import_from_path.cdxgenFromPath)();
+  if (fromPath) {
+    return fromPath;
+  }
+  if (opts?.downloadIfMissing) {
+    return (0, import_from_download.cdxgenFromDownload)(opts.downloadIfMissing);
+  }
+  return void 0;
+}
+function resetCdxgenResolution() {
+  resolutionCache.clear();
+}
+function resolveCdxgen(opts) {
+  const key = cacheKey(opts);
+  let cached = resolutionCache.get(key);
+  if (!cached) {
+    cached = doResolveCdxgen(opts);
+    resolutionCache.set(key, cached);
+  }
+  return cached;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  cacheKey,
+  doResolveCdxgen,
+  resetCdxgenResolution,
+  resolveCdxgen
+});

package/dist/external-tools/cdxgen/types.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @file Shared types for cdxgen resolution. cdxgen ships per-platform SEA
+ *   binaries starting in v12.0.x — that's the single install path. The legacy
+ *   `@cyclonedx/cdxgen` npm package is NOT used as a fallback: every fleet
+ *   platform-arch has a SEA build, and routing through npm for any target would
+ *   silently use a different distribution (different bundle composition,
+ *   different startup cost). One install path; one cached binary. The future
+ *   migration target is socket's `sdxgen` fork once that lands GA — the helper
+ *   API stays `resolveCdxgen()` for backward compatibility either way.
+ */
+import type { ResolvedToolIntegrity } from '../from-download';
+export type CdxgenSource = 'download' | 'path' | 'vfs';
+/**
+ * A resolved cdxgen installation.
+ */
+export interface ResolvedCdxgen {
+    /**
+     * Absolute path to the `cdxgen` executable.
+     *
+     * - `source === 'download'`: the SEA binary copied into the dlx cache.
+     * - `source === 'path'`: whatever `which cdxgen` returned.
+     * - `source === 'vfs'`: the smol binary's extracted bundle.
+     */
+    readonly path: string;
+    /**
+     * Which resolver tier found this.
+     */
+    readonly source: CdxgenSource;
+    /**
+     * See {@link ResolvedToolIntegrity}.
+     */
+    readonly integrity?: ResolvedToolIntegrity;
+}