@cdxgen/cdxgen 13.6.0 → 13.7.0

package/types/lib/helpers/jssSigner.d.ts

@@ -0,0 +1,288 @@
+/**
+ * JSON Signature Scheme (JSS) signing and verification for CycloneDX 2.0.
+ *
+ * Implemented from Recommendation ITU-T X.590 (10/2023), "JSON signature
+ * scheme". Clause citations below refer to that text:
+ *
+ * - clause 6.2.1: the signature object members (`hash_algorithm`,
+ *   `algorithm`, `public_key`, `value`, the countersignature `signature`)
+ *   and, in its footnote, that one of `public_key`, `public_cert_chain`,
+ *   `cert_url` or `thumbprint` is present;
+ * - clause 6.2.2 and Table 1: the algorithm vocabulary;
+ * - clause 7.1.2: existing signatures are temporarily removed;
+ * - clause 7.1.3: the new signature object (without its value) is added;
+ * - clause 7.1.4: the entire JSON object is canonicalized with JCS
+ *   [IETF RFC 8785];
+ * - clause 7.1.5: the JCS version is hashed with `hash_algorithm`, and the
+ *   hash is presented in (lowercase) hex;
+ * - clause 7.1.6: that hash is signed with `algorithm` and the result is
+ *   base64URL-encoded;
+ * - clause 7.1.7: pre-existing signatures are restored at the start of the
+ *   list and the new entry is appended with its `value`;
+ * - clause 7.2: a countersignature is a signature object nested in the
+ *   `signature` member of the signature it countersigns. The countersigned
+ *   entry keeps its `value` in the signed view (7.2.1, 7.2.3, 7.2.4) and the
+ *   other entries are removed (7.2.2);
+ * - clause 8.1: verification keeps only the entry under verification
+ *   (8.1.1), removes its `value` (8.1.2), takes the key from the entry or a
+ *   trusted source (8.1.3), canonicalizes (8.1.4), hashes (8.1.5) and
+ *   validates (8.1.6).
+ *
+ * The signed message. The clause 7.1.6 example value
+ * (`F1Sj4V...`) and the clause 7.2.6 countersignature value (`b_7Xu5...`)
+ * are reproduced byte for byte only when the message given to the signing
+ * primitive is the UTF-8 text of the lowercase hex hash of clause 7.1.5
+ * (and 7.2.5). Ed25519 and Ed448 sign that message directly. RS*, PS* and
+ * ES* pass the same message to the JOSE primitive named in Table 1 (JWA
+ * [IETF RFC 7518] sections 3.3 to 3.5), which hashes it again with its own
+ * SHA-2 digest; clause 6.2.1 `hash_algorithm` notes that the signing
+ * process "sometimes uses an internal hashing algorithm". X.590 has no
+ * RSA or ECDSA example, so that part follows from the text and the Ed25519
+ * vectors rather than from a published vector.
+ *
+ * Trust. Clause 8.1.3 allows the key to be parsed from the entry or fetched
+ * from a trusted source, and clause 8.1.6 leaves "public key lookup methods"
+ * to policy. An embedded key with no trust anchor proves integrity only, so
+ * {@link verifyJss} requires caller-supplied trusted keys and uses the
+ * embedded key only with the explicit `allowEmbeddedKey` option, whose
+ * results carry `trusted: false`.
+ *
+ * The signature object shape is also fixed by the pinned draft schema,
+ * #/$defs/cyclonedx-jss_X590_2023_10-2.0/$defs/signatureObject. The
+ * `public_key` value is the base64 form of the DER SubjectPublicKeyInfo
+ * without the PEM armor (clause 6.2.1); the clause 7.1 examples store it
+ * without base64 padding, which the schema pattern also allows.
+ */
+import { KeyObject } from "node:crypto";
+/**
+ * Quantum-safe algorithm names from X.590 Table 1 (clause 6.2.2) that
+ * node:crypto cannot provide: every XMSS (IETF RFC 8391 section 5.3) and
+ * LMS (IETF RFC 8554 section 5.1) value of the table.
+ */
+export declare const UNSUPPORTED_JSS_ALGORITHMS: readonly string[];
+/**
+ * The clause 6.2.1 `hash_algorithm` values accepted, by their IANA Named
+ * Information Hash Algorithm Registry names, mapped to the node:crypto
+ * digest. Anything else (md5, sha1, sha-224, unknown names) is refused when
+ * signing and fails verification: clause 6.2.1 asks for a "current and
+ * widely accepted hashing algorithm" defined in the IANA registry.
+ */
+export declare const JSS_HASH_ALGORITHMS: any;
+/** JSS algorithm names this module signs and verifies. */
+export declare const JSS_SIGNATURE_ALGORITHMS: readonly (string | string[] | null)[];
+/**
+ * Whether this runtime's crypto provides Ed448. Bun links BoringSSL, which
+ * has no Ed448, so key generation and key loading fail there with an
+ * OpenSSL error; this check turns that into a clear message.
+ *
+ * @returns {boolean} true when Ed448 keys can be created
+ */
+export declare function isEd448Available(): boolean;
+/**
+ * Checks that a key fits a JSS algorithm, the binding X.590 Table 1 (clause
+ * 6.2.2) defines through JWA [IETF RFC 7518] sections 3.3 to 3.5 and
+ * [IETF RFC 8037]: RS* need an rsa key, PS* an rsa or rsa-pss key, both of
+ * at least 2048 bits; ES256, ES384 and ES512 need an ec key on P-256, P-384
+ * and P-521 exactly; Ed25519 and Ed448 need that key type. Sign and verify
+ * both call it, so a mislabelled entry fails before any signature math.
+ *
+ * @param {string} algorithm - JSS algorithm name
+ * @param {KeyObject} key - Public or private key
+ * @throws {Error} When the key does not fit the algorithm
+ */
+export declare function assertJssKeyMatchesAlgorithm(algorithm: string, key: KeyObject): void;
+/**
+ * Picks the JSS algorithm for a key: ES256, ES384 or ES512 by curve, RS256
+ * for rsa, PS256 for rsa-pss, Ed25519 or Ed448 for those key types.
+ *
+ * @param {KeyObject} key - Public or private key
+ * @returns {string} JSS algorithm name
+ * @throws {Error} For a key type no JSS algorithm here supports
+ */
+export declare function selectJssAlgorithmForKey(key: KeyObject): string;
+/**
+ * Sign a JSON object with JSS (X.590 clause 7.1). Existing entries stay
+ * valid: they are removed while the new entry is computed (clause 7.1.2)
+ * and restored ahead of it (clause 7.1.7). The input is not mutated.
+ *
+ * @param {object} document - The JSON object to sign
+ * @param {object} options
+ * @param {string} options.algorithm - JSS algorithm name (clause 6.2.2)
+ * @param {KeyObject|string|Buffer} options.privateKey - Private key (KeyObject or PEM)
+ * @param {string} [options.hashAlgorithm] - Clause 6.2.1 hash; one of {@link JSS_HASH_ALGORITHMS}
+ * @returns {object} A new object carrying the `signatures` array
+ */
+export declare function signJss(document: object, { algorithm, privateKey, hashAlgorithm }?: {
+    algorithm: string;
+    privateKey: KeyObject | string | Buffer;
+    hashAlgorithm?: string;
+}): object;
+/**
+ * Countersign a JSS signature (X.590 clause 7.2): the new signature object
+ * goes into the `signature` member at the end of the countersignature chain
+ * of `signatures[index]`, and covers the document plus that entry and its
+ * chain, values included. Other entries are left out of the signed view
+ * (clause 7.2.2) and restored ahead of the countersigned entry (clause
+ * 7.2.7). The input is not mutated.
+ *
+ * @param {object} document - The signed JSON object
+ * @param {object} options
+ * @param {string} options.algorithm - JSS algorithm name (clause 6.2.2)
+ * @param {KeyObject|string|Buffer} options.privateKey - Private key (KeyObject or PEM)
+ * @param {string} [options.hashAlgorithm] - Clause 6.2.1 hash
+ * @param {number} [options.index] - Entry to countersign; required when there are several
+ * @returns {object} A new object carrying the countersigned `signatures` array
+ */
+export declare function countersignJss(document: object, { algorithm, privateKey, hashAlgorithm, index }?: {
+    algorithm: string;
+    privateKey: KeyObject | string | Buffer;
+    hashAlgorithm?: string;
+    index?: number;
+}): object;
+/**
+ * Verify the JSS signatures of a JSON object (X.590 clauses 8.1 and 7.2).
+ *
+ * Each entry is verified on its own view: the other entries are removed
+ * (clause 8.1.1) and the entry loses only its `value` (clause 8.1.2) and any
+ * nested countersignature, so every other member (`signee`, `valid_until`,
+ * `revoked`, ...) is covered. Each countersignature in an entry's `signature`
+ * chain is verified on the clause 7.2 view and reported with `depth` > 0.
+ *
+ * Trust comes from the caller (clause 8.1.3 "fetch it from a trusted
+ * source"). An entry whose `public_key` is a trusted key is checked with that
+ * key only; an entry without `public_key` (thumbprint, certificate chain,
+ * certificate URL) is checked with every trusted key. The embedded key is
+ * used only with `allowEmbeddedKey`, and such results carry
+ * `trusted: false`.
+ *
+ * Policy: with trusted keys, the object verifies when at least one
+ * signature object verifies with a trusted key and no signature object that
+ * names a trusted key fails. With `requireAll`, every signature object must
+ * verify with a trusted key, and with `requireEveryKey` every trusted key
+ * must verify one of them. With `allowEmbeddedKey` and no trusted keys,
+ * every signature object must verify with its embedded key, and the result
+ * is `trusted: false`.
+ *
+ * @param {object} document - The signed JSON object
+ * @param {object} options
+ * @param {KeyObject|string|Buffer} [options.publicKey] - A trusted public key
+ * @param {Array<KeyObject|string|Buffer>} [options.publicKeys] - Trusted public keys
+ * @param {boolean} [options.allowEmbeddedKey] - Fall back to each entry's embedded public_key for an integrity-only check (results are `trusted: false`)
+ * @param {boolean} [options.requireAll] - Every signature object must verify with a trusted key
+ * @param {boolean} [options.requireEveryKey] - With requireAll, every trusted key must verify a signature object
+ * @returns {{valid: boolean, trusted: boolean, reasons: string[], keysMatched: boolean[], results: Array<{index: number, depth: number, path: string, algorithm: any, hashAlgorithm: any, status: string, valid: boolean, trusted: boolean, claimsTrustedKey: boolean, keyIndex: (number|undefined), reason: (string|undefined)}>}}
+ * @throws {Error} When neither a trusted key nor allowEmbeddedKey is given
+ */
+export declare function verifyJss(document: object, options?: {
+    publicKey?: KeyObject | string | Buffer;
+    publicKeys?: Array<KeyObject | string | Buffer>;
+    allowEmbeddedKey?: boolean;
+    requireAll?: boolean;
+    requireEveryKey?: boolean;
+}): {
+    valid: boolean;
+    trusted: boolean;
+    reasons: string[];
+    keysMatched: boolean[];
+    results: Array<{
+        index: number;
+        depth: number;
+        path: string;
+        algorithm: any;
+        hashAlgorithm: any;
+        status: string;
+        valid: boolean;
+        trusted: boolean;
+        claimsTrustedKey: boolean;
+        keyIndex: (number | undefined);
+        reason: (string | undefined);
+    }>;
+};
+/**
+ * Remove every JSS signature from a CycloneDX 2.0 BOM: the root and the
+ * nested members {@link signJssBom} signs. Members are only touched where
+ * they carry `signatures`. The input is not mutated.
+ *
+ * @param {object} bom20 - CycloneDX 2.0 document
+ * @returns {{bom: object, removed: number}} The unsigned document and the number of signature entries removed
+ */
+export declare function removeJssSignatures(bom20: object): {
+    bom: object;
+    removed: number;
+};
+/**
+ * Sign a CycloneDX 2.0 BOM: the root document plus, with `deep`, the nested
+ * members the draft schema gives a `signatures` member to (inventories, the
+ * components inside an inventory, compositions and annotations). Nested
+ * members are signed first and the root last, so the root signature covers
+ * them.
+ *
+ * Existing root entries stay valid when only the root is signed (clause
+ * 7.1.2). Signing nested members changes content that existing root entries
+ * cover (clause 7.1.4 canonicalizes the whole object), so `deep` signing of
+ * a BOM that already carries root signatures is refused unless
+ * `allowInvalidatingSignatures` is set.
+ *
+ * @param {object} bom20 - Rendered CycloneDX 2.0 document
+ * @param {object} options - Passed to {@link signJss}
+ * @param {boolean} [options.deep] - Also sign nested members (default true)
+ * @param {boolean} [options.allowInvalidatingSignatures] - Sign nested members even though existing root signatures will no longer verify
+ * @returns {object} The signed document
+ */
+export declare function signJssBom(bom20: object, options?: {
+    deep?: boolean;
+    allowInvalidatingSignatures?: boolean;
+}): object;
+/**
+ * Verify the JSS signatures of a CycloneDX 2.0 BOM, root and nested, with
+ * the same policy {@link verifyBomSignatures} applies to JSF:
+ *
+ * - the root must carry `specFormat` (or `bomFormat`) "CycloneDX" and
+ *   `specVersion`, and only members CycloneDX defines at the root;
+ * - the root signatures verify as {@link verifyJss} defines; with
+ *   `requireAll`, every root signature object verifies with a trusted key
+ *   and every trusted key verifies one of them;
+ * - with `deep` (default), every signed inventory, inventory component,
+ *   composition and annotation verifies the same way (without the
+ *   every-key rule) and carries none of `bomFormat`, `specFormat`,
+ *   `specVersion`;
+ * - a BOM without root signatures fails unless `allowNestedOnly` is set;
+ *   then `deep` must be on and every nested member must be signed.
+ *
+ * @param {object} bom20 - Signed CycloneDX 2.0 document
+ * @param {object} options - Trust options passed to {@link verifyJss}
+ * @param {boolean} [options.deep] - Also verify nested signatures (default true)
+ * @param {boolean} [options.requireAll] - Every signature object must verify with a trusted key
+ * @param {boolean} [options.allowNestedOnly] - Accept a BOM without root signatures when every nested member is signed
+ * @returns {{valid: boolean, trusted: boolean, errors: string[], root: (object|null), results: Array, nested: Array<{path: string, valid: boolean, trusted: boolean, reasons: string[], results: Array}>}}
+ * @throws {Error} When neither a trusted key nor allowEmbeddedKey is given
+ */
+export declare function verifyJssBom(bom20: object, options?: {
+    deep?: boolean;
+    requireAll?: boolean;
+    allowNestedOnly?: boolean;
+}): {
+    valid: boolean;
+    trusted: boolean;
+    errors: string[];
+    root: (object | null);
+    results: any[];
+    nested: Array<{
+        path: string;
+        valid: boolean;
+        trusted: boolean;
+        reasons: string[];
+        results: any[];
+    }>;
+};
+/**
+ * Generate a JSS key pair for an algorithm (used by --generate-key-and-sign).
+ *
+ * @param {string} algorithm - JSS algorithm name
+ * @returns {{privateKey: KeyObject, publicKey: KeyObject}}
+ */
+export declare function generateJssKeyPair(algorithm: string): {
+    privateKey: KeyObject;
+    publicKey: KeyObject;
+};
+//# sourceMappingURL=jssSigner.d.ts.map

package/types/lib/helpers/jssSigner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jssSigner.d.ts","sourceRoot":"","sources":["../../../lib/helpers/jssSigner.js"],"names":[],"mappings":"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"}

package/types/lib/helpers/vsixutils.d.ts

@@ -3,28 +3,136 @@
  */
 export declare const VSCODE_EXTENSION_PURL_TYPE = "vscode-extension";
 /**
- * IDE configuration entries describing where each IDE stores its extensions.
- * Each entry contains the IDE name and an array of candidate extension
- * directory paths for Windows, macOS, and Linux (including remote/server
- * environments).
+ * Namespace of the `pkg:generic` purl given to an installed editor, which has
+ * no package type of its own.
+ */
+export declare const IDE_PURL_NAMESPACE = "cdxgen-ide";
+/**
+ * VS Code-family editors and remote servers whose installed extensions cdxgen
+ * can inventory.
+ *
+ * Every editor built from VS Code installs extensions into
+ * `<home>/<dataFolderName>/extensions` on Windows, macOS and Linux alike, and
+ * its remote server installs them into `<home>/<serverDataFolderName>/extensions`
+ * on the remote host. Settings and global storage live elsewhere (for example
+ * `~/Library/Application Support/Cursor/User`), and that folder never holds
+ * extensions.
+ *
+ * `apps` lists where the editor itself is installed, relative to the
+ * platform's application folders, so its version can be read from
+ * `resources/app/product.json` and `package.json`.
+ */
+export declare const IDE_PRODUCTS: ({
+    id: string;
+    name: string;
+    dataFolderName: string;
+    serverDataFolderName: string;
+    apps: {
+        darwin: string[];
+        linux: string[];
+        win32: string[];
+    };
+} | {
+    serverDataFolderName?: undefined;
+    id: string;
+    name: string;
+    dataFolderName: string;
+    apps: {
+        darwin?: undefined;
+        linux?: undefined;
+        win32?: undefined;
+    };
+})[];
+/**
+ * Describe where each known editor and remote server installs extensions for
+ * the given home directory.
  *
- * The paths use platform-specific logic via `homedir()` and common
- * environment variables.
+ * Each desktop editor contributes one entry for its own extensions folder and,
+ * when it has a remote server, a second entry for the server's folder. For the
+ * current user's home, the `VSCODE_EXTENSIONS` environment variable, which VS
+ * Code reads in place of the default folder, adds one more entry.
+ *
+ * @param {string} [home] Home directory to resolve the folders against
+ * @returns {Array<{id: string, name: string, kind: string, dirs: string[]}>}
+ *   One entry per editor or server, with `kind` set to `desktop` or `server`
  */
-export declare function getIdeExtensionDirs(): {
+export declare function getIdeExtensionDirs(home?: string): Array<{
+    id: string;
     name: string;
-    dirs: any[];
-}[];
+    kind: string;
+    dirs: string[];
+}>;
 /**
- * Discover all existing IDE extension directories on the current system.
+ * Discover the extension folders that exist for the given home directory.
  *
- * @returns {Array<{name: string, dir: string}>} Array of objects with IDE name
- *   and the existing directory path.
+ * @param {string} [home] Home directory to resolve the folders against
+ * @returns {Array<{id: string, name: string, kind: string, dir: string, home: string}>}
+ *   One entry per existing folder
  */
-export declare function discoverIdeExtensionDirs(): Array<{
+export declare function discoverIdeExtensionDirs(home?: string): Array<{
+    id: string;
     name: string;
+    kind: string;
     dir: string;
+    home: string;
 }>;
+/**
+ * Find the editor or server an extensions folder belongs to from its path,
+ * such as `~/.cursor/extensions` or `/home/dev/.cursor-server/extensions`.
+ *
+ * @param {string} extensionsDir Path to an extensions folder
+ * @returns {{id: string, name: string, kind: string, home: string}|undefined}
+ *   The match, with the home folder it sits in, or undefined for a folder no
+ *   known editor uses
+ */
+export declare function identifyIdeFromExtensionsDir(extensionsDir: string): {
+    id: string;
+    name: string;
+    kind: string;
+    home: string;
+} | undefined;
+/**
+ * Read an editor's identity from the `product.json` and `package.json` in its
+ * `resources/app` folder (or the root of a remote server).
+ *
+ * Forks report their own release in different fields of `product.json`:
+ * `version` (Cursor, Kiro), `windsurfVersion` (Windsurf and Devin Desktop),
+ * `positronVersion`, `appVersion` (Trae) and `codeServerVersion`. VS Code
+ * itself has none of these and keeps its release in `package.json`, as every
+ * fork does for the VS Code release it is based on.
+ *
+ * @param {string} appDir Folder holding `product.json`
+ * @returns {Object|undefined} `{ version, vscodeVersion, commit, quality,
+ *   nameLong, dataFolderName, serverDataFolderName, appDir }`, or undefined
+ *   when there is no product.json
+ */
+export declare function readIdeProductInfo(appDir: string): Object | undefined;
+/**
+ * Find the installed editor (or remote server) for an extensions folder and
+ * read its identity.
+ *
+ * A remote server is looked up in the home the folder is in. A desktop editor
+ * and code-server are looked up in the application folders of the machine
+ * running cdxgen, so that lookup happens only when `probeApps` is true: for a
+ * scan of this host, not for a folder copied from another machine.
+ *
+ * @param {{id: string, kind: string}} ide Entry from discoverIdeExtensionDirs
+ * @param {string} [home] Home directory
+ * @param {Object} [options] Lookup options
+ * @param {boolean} [options.probeApps] Look in this machine's application
+ *   folders; defaults to true only for the current user's home
+ * @param {string[]} [options.appDirs] Folders to read in place of the
+ *   application folders
+ * @returns {Object|undefined} Result of readIdeProductInfo for the newest
+ *   installation whose data folder matches, or undefined
+ */
+export declare function findIdeProductInfo(ide: {
+    id: string;
+    kind: string;
+}, home?: string, options?: {
+    probeApps?: boolean;
+    appDirs?: string[];
+}): Object | undefined;
 /**
  * Parse a `.vsixmanifest` XML string and extract extension metadata.
  *
@@ -78,6 +186,14 @@ export declare function extractExtensionCapabilities(pkg: Object): Object;
  * @returns {Object|undefined} CycloneDX component object or undefined
  */
 export declare function toComponent(extInfo: Object, ideName?: string): Object | undefined;
+/**
+ * True when a .vsix path is a regular file. A FIFO or a device named `*.vsix`
+ * would block or never end, and a root scan does not follow a symlink.
+ *
+ * @param {string} vsixFile Path to the .vsix
+ * @returns {boolean} true when the archive can be opened
+ */
+export declare function isReadableVsix(vsixFile: string): boolean;
 /**
  * Extract a `.vsix` file (ZIP archive) to a temporary directory for deep
  * analysis. The caller is responsible for cleaning up the temp directory.
@@ -100,23 +216,156 @@ export declare function cleanupTempDir(tempDir: string): void;
  */
 export declare function parseVsixFile(vsixFile: string): Promise<Object | undefined>;
 /**
- * Parse a single installed extension directory (already extracted).
- * Looks for `package.json` (preferred) and `.vsixmanifest`.
+ * Read the install registry an editor keeps beside its extensions.
+ *
+ * `extensions.json` lists every installed extension with where it came from
+ * and when it was installed. `.obsolete` names the folders of extensions that
+ * were uninstalled or replaced by an update but are still on disk until the
+ * editor next starts. Folder names from either file are only compared with the
+ * names in the folder, never turned into paths.
+ *
+ * @param {string} extensionsDir Extensions folder
+ * @returns {{records: Map<string, Object>, obsolete: Set<string>, hasRegistry: boolean}}
+ *   Install records keyed by folder name, the obsolete folder names, and
+ *   whether an extensions.json was read
+ */
+export declare function readInstalledExtensionsRegistry(extensionsDir: string): {
+    records: Map<string, Object>;
+    obsolete: Set<string>;
+    hasRegistry: boolean;
+};
+/**
+ * Hash the `main` and `browser` entry files of an installed extension the way
+ * the extension host resolves them: the path as written, with a `.js` suffix,
+ * or as a folder holding `index.js`. Only regular files that stay inside the
+ * extension folder are read; a symlink, a FIFO or a path that leaves the
+ * folder is not.
+ *
+ * @param {string} extDir Installed extension folder
+ * @param {{main?: string, browser?: string}} entries Entry points from
+ *   package.json
+ * @returns {Array<{role: string, name: string, digest: string, path: string}>}
+ *   One entry per hashed file, with its path relative to the folder
+ */
+export declare function hashExtensionEntryFiles(extDir: string, entries: {
+    main?: string;
+    browser?: string;
+}): Array<{
+    role: string;
+    name: string;
+    digest: string;
+    path: string;
+}>;
+/**
+ * Describe the code an installed extension runs as `file` components with
+ * their SHA-256, so the extension can be matched against a published hash of
+ * a known good or known bad build.
+ *
+ * @param {string} extDir Installed extension folder
+ * @param {Object} capabilities Capabilities from extractExtensionCapabilities
+ * @param {string} parentRef bom-ref of the extension component
+ * @returns {Object[]} File components, empty when no entry file is found
+ */
+export declare function describeExtensionEntryFiles(extDir: string, capabilities: Object, parentRef: string): Object[];
+/**
+ * Parse a single installed extension folder.
  *
- * @param {string} extDir Absolute path to the extension directory (e.g. `~/.vscode/extensions/ms-python.python-2023.1.0`)
- * @param {string} [ideName] Optional IDE name
+ * `package.json` gives the identity and capabilities. The `.vsixmanifest` the
+ * editor keeps beside it adds the target platform, links and manifest
+ * properties, and the folder name supplies the platform when neither does.
+ *
+ * @param {string} extDir Absolute path to the extension folder (e.g. `~/.cursor/extensions/anthropic.claude-code-2.1.313-darwin-arm64`)
+ * @param {string} [ideName] Name of the editor the folder belongs to
+ * @param {Object} [installRecord] Entry for the folder from extensions.json
+ * @param {Object} [options] Parse options
+ * @param {boolean} [options.nameOnly] Read only the folder name, as a root
+ *   scan does for a symlinked folder
  * @returns {Object|undefined} CycloneDX component object or undefined
  */
-export declare function parseInstalledExtensionDir(extDir: string, ideName?: string): Object | undefined;
+export declare function parseInstalledExtensionDir(extDir: string, ideName?: string, installRecord?: Object, options?: {
+    nameOnly?: boolean;
+}): Object | undefined;
 /**
  * Attempt to extract extension metadata from a directory name following the
- * pattern `publisher.name-version`.
+ * pattern `publisher.name-version` or `publisher.name-version-platform`.
  *
  * @param {string} extDir Absolute path to extension directory
  * @param {string} [ideName] IDE name
  * @returns {Object|undefined} CycloneDX component or undefined
  */
 export declare function parseExtensionDirName(extDir: string, ideName?: string): Object | undefined;
+/**
+ * Decide whether a folder is an editor's extensions folder: one at a path a
+ * known editor uses, or one holding the `extensions.json` or `.obsolete` an
+ * editor writes. A source repository whose subfolders happen to include an
+ * extension is not one.
+ *
+ * @param {string} dir Folder to check
+ * @returns {boolean} True when the folder is an extensions folder
+ */
+export declare function isInstalledExtensionsDir(dir: string): boolean;
+/**
+ * Decide whether a folder is one installed extension: a `.vsixmanifest`, or a
+ * package.json with a publisher and a `vscode` engine.
+ *
+ * @param {string} dir Folder to check
+ * @returns {boolean} True for an extension folder
+ */
+export declare function isInstalledExtensionDir(dir: string): boolean;
+/**
+ * Build a CycloneDX component for an installed editor or remote server.
+ *
+ * @param {{id: string, name: string, kind: string, dirs?: string[], dir?: string, home?: string}} ide
+ *   Discovered extensions folder, or folders, of one editor
+ * @param {Object} [productInfo] Result of findIdeProductInfo
+ * @param {number} extensionCount Number of extension builds found
+ * @returns {Object} CycloneDX application component
+ */
+export declare function toIdeComponent(ide: {
+    id: string;
+    name: string;
+    kind: string;
+    dirs?: string[];
+    dir?: string;
+    home?: string;
+}, productInfo?: Object, extensionCount: number): Object;
+/**
+ * Collect the installed extensions of each editor folder, plus a component for
+ * each editor and the dependency edges from an editor to its extensions.
+ *
+ * One extension installed in two editors is one component: the editors are
+ * listed in `cdx:vscode-extension:ide`, every folder it was found in is an
+ * occurrence, and every copy's entry files are hashed. When two copies of the
+ * same build have different entry-file bytes, each digest becomes its own file
+ * component and the extension is marked `cdx:vscode-extension:entryHashMismatch`.
+ *
+ * @param {Array<{id?: string, name?: string, kind?: string, dir: string, home?: string, only?: string, probeApps?: boolean}>} ideDirs
+ *   Extensions folders, as returned by discoverIdeExtensionDirs. `only` limits
+ *   a folder to one extension; `home` and `probeApps` say where the editor's
+ *   own version is looked up (see findIdeProductInfo)
+ * @param {Object} [options] Collection options
+ * @param {boolean} [options.includeIdeComponents=true] Emit a component for
+ *   each editor and link it to its extensions
+ * @param {string} [options.home] Home directory used when a folder names none
+ * @param {boolean} [options.probeApps] Default for folders that do not say
+ * @returns {{components: Object[], dependencies: Object[]}} Inventory
+ */
+export declare function collectIdeInventory(ideDirs: Array<{
+    id?: string;
+    name?: string;
+    kind?: string;
+    dir: string;
+    home?: string;
+    only?: string;
+    probeApps?: boolean;
+}>, options?: {
+    includeIdeComponents?: boolean;
+    home?: string;
+    probeApps?: boolean;
+}): {
+    components: Object[];
+    dependencies: Object[];
+};
 /**
  * Collect all installed extensions from a set of IDE extension directories.
  *
@@ -127,4 +376,39 @@ export declare function collectInstalledExtensions(ideDirs: Array<{
     name: string;
     dir: string;
 }>): Object[];
+/**
+ * Merge two descriptions of the same extension build, such as a `.vsix` file
+ * and the folder it was installed into, so neither loses its hashes,
+ * occurrences, entry files or properties.
+ *
+ * @param {Object[]} components Components, some of which share a bom-ref
+ * @returns {Object[]} Components with one entry per extension bom-ref
+ */
+export declare function mergeExtensionComponents(components: Object[]): Object[];
+/**
+ * Add the host's editors and the extensions osquery could not see to an OBOM
+ * component list.
+ *
+ * osquery's `vscode_extensions` table reads `extensions.json` for a fixed set
+ * of editors, so extensions of other editors, and folders an editor never
+ * registered, are missing from its rows. The editor folders of each home are
+ * read here: an extension osquery already reported keeps its row and gains the
+ * editor names, the occurrences and the hashed entry files, and the rest are
+ * added. Every editor found also becomes a component. No dependency edges are
+ * added, because an OBOM has no dependency graph.
+ *
+ * @param {Object[]} pkgList OBOM components, which are updated in place
+ * @param {Object} [options] Collection options
+ * @param {string[]} [options.homes] Home directories to read
+ * @param {string} [options.home] One home directory to read, used when
+ *   `homes` is not given; defaults to the current user's
+ * @param {Array<Object>} [options.ideDirs] Extensions folders to read in place
+ *   of discovering them
+ * @returns {Object[]} Components to append to the OBOM
+ */
+export declare function collectObomIdeInventory(pkgList: Object[], options?: {
+    homes?: string[];
+    home?: string;
+    ideDirs?: Array<Object>;
+}): Object[];
 //# sourceMappingURL=vsixutils.d.ts.map