@cdxgen/cdxgen 13.2.0 → 13.3.0

package/types/lib/evinser/swiftsem.d.ts

@@ -1,11 +1,66 @@
+/**
+ * Convert a SwiftPM target or package name into its module name.
+ *
+ * @param {String} name Target or package name
+ * @returns {String} Module name
+ */
+export declare function toModuleName(name: string): string;
+/**
+ * Decide whether a module belongs to tests or to an aggregate product and so
+ * must not contribute build symbols or semantic context.
+ *
+ * @param {String} moduleName Module name
+ * @returns {boolean} `true` when the module should be skipped
+ */
+export declare function isTestOrAggregateModule(moduleName: string): boolean;
+/**
+ * Parse the JSON printed by `swift -print-target-info`.
+ *
+ * `paths.runtimeResourcePath` is `<toolchain>/usr/lib/swift` for every
+ * toolchain layout (Xcode, `.xctoolchain` bundles, swiftly, Linux tarballs),
+ * so it names the toolchain that actually compiles the project.
+ *
+ * @param {Object} targetInfo Parsed `-print-target-info` output
+ * @returns {undefined|Object} `{ compilerVersion, triple, runtimeResourcePath, toolchainDir }`
+ */
+export declare function parseSwiftTargetInfo(targetInfo: Object): undefined | Object;
+/**
+ * Identify the toolchain that `swift` resolves to inside a project directory.
+ *
+ * The query runs in the project directory because toolchain managers such as
+ * swiftly select the toolchain per directory (`.swift-version`), so the
+ * compiler that builds a project can differ from the one on the PATH of the
+ * calling process.
+ *
+ * @param {String} basePath Project directory
+ * @returns {undefined|Object} Toolchain details, see parseSwiftTargetInfo
+ */
+export declare function resolveSwiftToolchain(basePath: string): undefined | Object;
+/**
+ * Environment overrides that make sourcekitten load the SourceKit of the
+ * toolchain that builds the project.
+ *
+ * Without guidance sourcekitten uses the toolchain of the selected Xcode (or
+ * the `swift` found on the PATH on Linux). SourceKit cannot load modules
+ * produced by a different compiler version, so every reference to a
+ * dependency then goes unresolved. On macOS sourcekitten honours
+ * `XCODE_DEFAULT_TOOLCHAIN_OVERRIDE` ahead of `xcrun`; on Linux it honours
+ * `LINUX_SOURCEKIT_LIB_PATH`. Explicitly configured values always win.
+ *
+ * @param {Object} toolchain Toolchain details from resolveSwiftToolchain
+ * @param {String} [platform] Platform name, defaults to process.platform
+ * @returns {undefined|Object} Environment overrides for sourcekitten
+ */
+export declare function sourcekittenEnvForToolchain(toolchain: Object, platform?: string): undefined | Object;
 /**
  * Retrieve the structure information of a .swift file in json format
  *
  * @param {String} filePath Path to .swift file
+ * @param {Object} [env] Environment overrides for sourcekitten
  *
  * @returns {undefined|Object} JSON representation of the swift file or undefined.
  */
-export declare function getStructure(filePath: string): undefined | Object;
+export declare function getStructure(filePath: string, env?: Object): undefined | Object;
 /**
  * Parse the data from the structure command
  *
@@ -13,35 +68,150 @@ export declare function getStructure(filePath: string): undefined | Object;
  * @returns {Object|undefined} Parsed value
  */
 export declare function parseStructure(structureJson: Object): Object | undefined;
+/**
+ * Split a Swift command line, as printed by a verbose build or given in an
+ * environment variable, into arguments.
+ *
+ * Paths on Windows use backslash separators, so a backslash there is literal
+ * unless it precedes a double quote (the `CommandLineToArgvW` rules). Single
+ * quotes, which SwiftPM uses to quote arguments on every platform, keep their
+ * content literal. Elsewhere shell quoting applies.
+ *
+ * @param {String} commandString Command line
+ * @param {String} [platform] Platform name, defaults to process.platform
+ * @returns {Array<String>} Arguments
+ */
+export declare function splitSwiftCommandArgs(commandString: string, platform?: string): Array<string>;
 /**
  * Method to perform swift build in verbose mode.
  *
+ * `SWIFT_BUILD_ARGS` adds arguments to the build, for example
+ * `--build-system native` to use the llbuild engine with Swift 6.4.
+ *
  * @param {String} basePath Path
  * @returns {undefined|String} Verbose build output
  */
 export declare function verboseBuild(basePath: string): undefined | string;
 /**
- * Method to parse the verbose swift build output to identify key compiler parameters.
+ * Reduce one module's compiler invocation to the arguments that affect how
+ * its sources are type-checked.
+ *
+ * Only known argument classes are kept, so outputs, incremental build
+ * bookkeeping, response files, and flags a SourceKit build may not know are
+ * dropped. The order of the kept arguments is preserved, which keeps paired
+ * clang arguments such as `-Xcc -I -Xcc <path>` intact. The module cache is
+ * dropped as well: the build's cache may hold modules of other toolchains.
+ *
+ * @param {Array<String>} tokens Tokenized compiler invocation
+ * @returns {Array<String>} Sanitized compiler arguments
+ */
+export declare function sanitizeSwiftModuleArgs(tokens: Array<string>): Array<string>;
+/**
+ * Extract the per-module compiler invocations printed by a verbose swift
+ * build.
+ *
+ * Both engines print one driver invocation per module that carries
+ * `-module-name`: llbuild prints `swiftc ... -module-name X ... @sources`,
+ * while the Swift Build engine prints `builtin-SwiftDriver -- swiftc ...
+ * -module-name X ... @<target>.SwiftFileList`. llbuild also prints the
+ * frontend jobs of each module, which are only used when no driver line is
+ * found. Package manifest and plugin compilations are skipped.
+ *
+ * @param {String} buildOutput Verbose build output
+ * @param {String} [platform] Platform that printed the output, which decides
+ *   its quoting rules; defaults to process.platform
+ * @returns {Object} Map of module name to `{ args, sources, isDriver }`
+ */
+export declare function parseSwiftModuleInvocations(buildOutput: string, platform?: string): Object;
+/**
+ * Parse the llbuild engine's build description
+ * (`.build/<triple>/debug/description.json`).
+ *
+ * Its `swiftCommands` record every Swift module the build compiled, with the
+ * exact source list and compiler arguments. Host-tool variants
+ * (`...-tool.module`, built for macros and plugins) are used only when a
+ * module has no regular variant.
+ *
+ * @param {Object} descriptionJson Parsed description.json
+ * @returns {Object} Map of module name to `{ args, sources, isDriver }`
+ */
+export declare function parseSwiftBuildDescription(descriptionJson: Object): Object;
+/**
+ * Merge the sanitized arguments of several modules into one argument list,
+ * used when a source file cannot be attributed to a single module. The first
+ * module's single-value flags win, include paths accumulate, and `-Xcc`
+ * values are merged per clang argument group.
+ *
+ * @param {Array<Array<String>>} argLists Sanitized argument lists, most relevant first
+ * @returns {Array<String>} Merged arguments
+ */
+export declare function mergeSwiftModuleArgs(argLists: Array<Array<string>>): Array<string>;
+/**
+ * Method to parse the verbose swift build output to identify key compiler
+ * parameters. The arguments of the root package's modules are merged, or of
+ * every module when the root modules are unknown.
  *
  * @param {String} buildOutput Verbose build output
- * @returns {Object} compiler build parameters
+ * @param {Array<String>|Set<String>} [rootModules] Module names of the root package
+ * @returns {Object} `{ params, compilerArgs }` where params maps module names to their arguments
  */
-export declare function extractCompilerParamsFromBuild(buildOutput: string): Object;
+export declare function extractCompilerParamsFromBuild(buildOutput: string, rootModules?: Array<string> | Set<string>): Object;
 /**
  * Method to index a swift file and extract metadata
  *
  * @param {String} filePath Path to .swift file
- * @param {String|Array<string>} compilerArgs Compiler arguments extracted from verbose build log
+ * @param {String|Array<string>} compilerArgs Compiler arguments. They should
+ *   list every source of the file's module so that references across files
+ *   resolve; the file itself is appended when missing.
+ * @param {Object} [env] Environment overrides for sourcekitten
  * @returns {undefined|Object} metadata
  */
-export declare function index(filePath: string, compilerArgs: string | Array<string>): undefined | Object;
+export declare function index(filePath: string, compilerArgs: string | Array<string>, env?: Object): undefined | Object;
 /**
  * Parse the data from the index command
  *
+ * Besides the symbol names and lines, the unified symbol resolution (USR) of
+ * every indexed entity is recorded with its lines. A USR identifies the
+ * declaration the compiler resolved a reference to, including the module
+ * that declares it, which is what attributes a usage to a dependency.
+ *
  * @param {Object} indexJson Json from the index command
  * @returns {Object|undefined} Parsed value
  */
 export declare function parseIndex(indexJson: Object): Object | undefined;
+/**
+ * Identify the module that declares an entity from its demangled name.
+ *
+ * Qualified names start with the module (`Yams.dump(object:...)`), and
+ * members declared in extensions carry the extending module
+ * (`(extension in Yams):Swift.String.yaml`), which is what a usage of the
+ * member depends on.
+ *
+ * @param {String} demangled Output of `swift demangle --compact`
+ * @returns {undefined|String} Module name
+ */
+export declare function moduleFromDemangledName(demangled: string): undefined | string;
+/**
+ * Identify the module of a mangled Swift name without the demangler. Only the
+ * leading module context is decoded, so extension members are attributed to
+ * the extended type's module.
+ *
+ * @param {String} mangled Mangled name starting with `$s`
+ * @returns {undefined|String} Module name
+ */
+export declare function moduleFromMangledPrefix(mangled: string): undefined | string;
+/**
+ * Identify the declaring module of each USR.
+ *
+ * Swift USRs are demangled in one batch with `swift demangle`; clang module
+ * references (`c:@M@<module>`, emitted for import declarations) carry the
+ * module name directly. Other clang USRs name no module and are skipped.
+ *
+ * @param {Array<String>} usrs USRs to resolve
+ * @param {String} basePath Directory to run the demangler in
+ * @returns {Map<String, String>} USR to module name
+ */
+export declare function resolveUsrModules(usrs: Array<string>, basePath: string): Map<string, string>;
 /**
  * Method to execute dump-package package command.
  *
@@ -61,9 +231,10 @@ export declare function parseDumpPackage(dumpJson: Object): Object | undefined;
  *
  * @param {String} moduleName Module name
  * @param {String|Array<string>} compilerArgs Compiler arguments extracted from verbose build log
+ * @param {Object} [env] Environment overrides for sourcekitten
  * @returns {undefined|Object} JSON representation of the swift module or undefined.
  */
-export declare function moduleInfo(moduleName: string, compilerArgs: string | Array<string>): undefined | Object;
+export declare function moduleInfo(moduleName: string, compilerArgs: string | Array<string>, env?: Object): undefined | Object;
 /**
  * Parse the data from module-info command to replicate the swift interface
  *
@@ -72,32 +243,126 @@ export declare function moduleInfo(moduleName: string, compilerArgs: string | Ar
  */
 export declare function parseModuleInfo(moduleInfoJson: Object): Object | undefined;
 /**
- * Method to collect the build symbols from the output file maps generated by swift build.
+ * Method to collect the build symbols from the output file maps generated by
+ * swift build.
+ *
+ * Both build engines are supported: the llbuild engine writes per-module
+ * `output-file-map.json` files, while the Swift Build engine (default from
+ * Swift 6.4) writes per-target `<target>-OutputFileMap.json` files under
+ * `.build/out/Intermediates.noindex`.
  *
  * @param {String} basePath Path
  * @param {Object} options CLI options
- * @returns {Object} symbols map
+ * @param {Array<String>} [fileMaps] Output file maps, found under basePath when omitted
+ * @returns {Object} symbols map keyed by module name
  */
-export declare function collectBuildSymbols(basePath: string, options: Object): Object;
+export declare function collectBuildSymbols(basePath: string, options: Object, fileMaps?: Array<string>): Object;
 /**
- * Method to parse output file map to identify the module and their symbols.
- * This list is imprecise when compared with the data from module-info command.
+ * Method to parse output file map to identify the module, its sources, and
+ * their symbols. The symbol list is imprecise; the sources are exact.
+ *
+ * The module name is derived from the containing directory for llbuild maps
+ * (`<Module>.build` and, since Swift 6.4, `<Module>-tool.build`) and from the
+ * file name for Swift Build maps (`<target>-OutputFileMap.json`, where the
+ * target name still needs to be sanitised into a module name).
  *
  * @param filemap {String} File name
- * @returns {Object} parsed module metadata
+ * @returns {Object} parsed module metadata `{ moduleName, moduleSymbols, sourceFiles }`
  */
 export declare function parseOutputFileMap(filemap: string): Object;
+/**
+ * Parse `.build/workspace-state.json` into the dependency packages of the
+ * workspace and the directory each one was materialised in.
+ *
+ * @param {Object} stateJson Parsed workspace-state.json
+ * @param {String} basePath Root package directory
+ * @returns {Array<Object>} `{ identity, name, location, kind, dir }` per package
+ */
+export declare function parseSwiftWorkspaceState(stateJson: Object, basePath: string): Array<Object>;
+/**
+ * Parse the Swift Build engine's project model (`.build/manifest.pif`) into
+ * the module names each package declares.
+ *
+ * The manifest is a list of workspace, project, and target objects linked
+ * through their `signature` hashes. A project's guid is `PACKAGE:<identity>`
+ * and each target records its `PRODUCT_MODULE_NAME`. Unlike the verbose
+ * build output, the manifest lists modules whose compilation never started,
+ * which keeps the module-to-package mapping complete when a build fails.
+ *
+ * @param {Array} manifestJson Parsed manifest.pif contents
+ * @returns {Object} Map of package identity to module names
+ */
+export declare function parseSwiftBuildManifest(manifestJson: any[]): Object;
+/**
+ * Collect the modules imported by a Swift source file, with their lines.
+ *
+ * Declarations such as `@testable import Foo`, `public import Foo`,
+ * `@_implementationOnly import cmark_gfm`, and `import struct Foo.Bar` are
+ * recognised; comments, string literals, and `canImport` conditions are not
+ * imports.
+ *
+ * @param {String} sourceText Swift source
+ * @returns {Array<Object>} `{ module, line }` per import declaration
+ */
+export declare function parseSwiftImports(sourceText: string): Array<Object>;
+/**
+ * Collect the clang module names declared at the top level of a module map.
+ *
+ * @param {String} moduleMapText module.modulemap contents
+ * @returns {Object} `{ modules, headerPaths }`
+ */
+export declare function parseClangModuleMap(moduleMapText: string): Object;
+/**
+ * Build a description of every module in a completed swift build: its
+ * compiler arguments, sources, and owning package.
+ *
+ * Arguments come from the llbuild build description when present and from
+ * the verbose build output otherwise (the only source for the Swift Build
+ * engine); sources come from the same places or from the output file maps.
+ * Packages come from `workspace-state.json`, and every module is attributed
+ * to the package whose directory holds its sources. Clang modules are
+ * discovered through their module maps.
+ *
+ * @param {String} basePath Root package directory
+ * @param {String} buildOutput Verbose build output
+ * @param {Object} options CLI options
+ * @param {Object} [rootMetadata] Parsed dump-package of the root package
+ * @returns {Object} `{ modules, packages, root, clangModules, fileMaps }`
+ */
+export declare function collectSwiftBuildPlan(basePath: string, buildOutput: string, options: Object, rootMetadata?: Object): Object;
+/**
+ * Check that sourcekitten can load SourceKit, with a trivial syntax request.
+ *
+ * A missing binary, a binary without its Swift runtime (`error while loading
+ * shared libraries: libswiftCore.so`), or one linked against a different
+ * Swift runtime than the toolchain provides (Linux has no stable Swift ABI, so
+ * such a binary crashes inside libswiftCore) fails every request; the probe
+ * turns that into one clear message instead of silent empty results.
+ *
+ * @param {Object} [env] Environment overrides for sourcekitten
+ * @returns {boolean} `true` when sourcekitten answered the probe
+ */
+export declare function isSourcekittenUsable(env?: Object): boolean;
 /**
  * Create a precise semantics slices file for a swift project.
  *
+ * The project is built once in verbose mode. Every source file of the root
+ * package's (non-test) modules is then indexed with sourcekitten using that
+ * module's own compiler arguments and source list, with sourcekitten aligned
+ * to the toolchain that compiled the project. The declaring module of every
+ * resolved reference is recovered from its USR, which attributes each usage
+ * to the package that provides the module (`moduleReferences`).
+ *
  * @param basePath basePath Path
  * @param options options CLI options
  */
 export declare function createSemanticsSlices(basePath: any, options: any): {
+    projectPath: any;
+    toolchain: any;
     packageMetadata: Object | undefined;
+    packages: any;
+    packageModules: {};
     buildSymbols: Object;
-    moduleInfos: {};
-    fileStructures: {};
     fileIndexes: {};
 } | undefined;
 //# sourceMappingURL=swiftsem.d.ts.map

package/types/lib/evinser/swiftsem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"swiftsem.d.ts","sourceRoot":"","sources":["../../../lib/evinser/swiftsem.js"],"names":[],"mappings":"AAwEA;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,QAAQ,QAAA,GAFxB,SAAS,GAAC,MAAM,CAI5B;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,aAAa,EAHjC,MAGiC,GAF/B,MAAM,GAAC,SAAS,CAiB5B;AAqCD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,QAAQ,QAAA,GAFxB,SAAS,SAAO,CAa5B;AAED;;;;;GAKG;AACH,wBAAgB,8BAA8B,CAAC,WAAW,QAAA,GAF7C,MAAM,CA+JlB;AAED;;;;;;GAMG;AACH,wBAAgB,KAAK,CAAC,QAAQ,QAAA,EAAE,YAAY,EAHjC,SAAO,KAAK,CAAC,MAAM,CAGc,GAF/B,SAAS,GAAC,MAAM,CAc5B;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,SAAS,EAHzB,MAGyB,GAFvB,MAAM,GAAC,SAAS,CA6B5B;AAsED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,QAAQ,QAAA,GAFvB,SAAS,GAAC,MAAM,CAY5B;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAH9B,MAG8B,GAF5B,MAAM,GAAC,SAAS,CA4B5B;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,UAAU,QAAA,EAAE,YAAY,EAHxC,SAAO,KAAK,CAAC,MAAM,CAGqB,GAFtC,SAAS,GAAC,MAAM,CAa5B;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,cAAc,EAHnC,MAGmC,GAFjC,MAAM,GAAC,SAAS,CAqF5B;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,QAAA,EAAE,OAAO,EAH1C,MAG0C,GAFxC,MAAM,CAkBlB;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,QAAA,GAF7B,MAAM,CAgBlB;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,KAAA,EAAE,OAAO,KAAA;;;;;;cAoGtD"}
+{"version":3,"file":"swiftsem.d.ts","sourceRoot":"","sources":["../../../lib/evinser/swiftsem.js"],"names":[],"mappings":"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"}

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

@@ -1,28 +1,121 @@
 import crypto from "node:crypto";
 /**
- * Recursively applies signatures to the BOM and its granular components.
+ * Renders a value taken from a document for a message. JSON can make any field
+ * an object or array, and interpolating those directly can throw.
+ *
+ * @param {any} value - Value to render
+ * @returns {string} - Printable text
+ */
+export declare function displayValue(value: any): string;
+/**
+ * Wraps shared-secret material for HMAC (HS256, HS384, HS512) signing or
+ * verification.
+ *
+ * HMAC is only ever used with a key produced by this function (or any secret
+ * KeyObject). Public and private keys are refused, so a document cannot switch
+ * a verifier to HMAC and use its public key as the secret.
+ *
+ * @param {string|Buffer|crypto.KeyObject} material - Secret bytes, a UTF-8 string, or a secret KeyObject
+ * @returns {crypto.KeyObject} - A secret KeyObject
+ */
+export declare function loadSharedSecret(material: string | Buffer | crypto.KeyObject): crypto.KeyObject;
+/**
+ * Loads the key used to verify signatures.
+ *
+ * Strings and Buffers are always parsed as asymmetric keys (a private key is
+ * reduced to its public half). To verify HMAC signatures, pass the result of
+ * {@link loadSharedSecret} instead.
+ *
+ * @param {string|Buffer|Object|crypto.KeyObject} key - PEM text, a createPublicKey() input, or a KeyObject
+ * @returns {crypto.KeyObject} - A public or secret KeyObject
+ */
+export declare function loadVerificationKey(key: string | Buffer | Object | crypto.KeyObject): crypto.KeyObject;
+/**
+ * Generates a PEM key pair suitable for the given JSF algorithm.
+ *
+ * @param {string} algorithm - JSF algorithm identifier
+ * @returns {{ publicKey: string, privateKey: string }} - PEM encoded SPKI public key and PKCS#8 private key
+ */
+export declare function generateSigningKeyPair(algorithm: string): {
+    publicKey: string;
+    privateKey: string;
+};
+/**
+ * Applies JSF signatures to the BOM and, optionally, its components, services,
+ * and annotations.
+ *
+ * Nested elements are signed by default. When a `signers` or `chain` signature
+ * is appended to a BOM that already has a root signature, nested elements are
+ * skipped by default, because changing them would invalidate the existing root
+ * signature; explicitly requesting nested signing in that case is an error.
  *
  * @param {Object} bomJson - CycloneDX BOM Object
- * @param {Object} options - Signing options { privateKey, algorithm, mode, ... }
+ * @param {Object} options - Signing options
+ * @param {string|Buffer|Object|crypto.KeyObject} options.privateKey - Private key (PEM or KeyObject), or the shared secret for HS* algorithms
+ * @param {string} [options.algorithm] - JSF algorithm identifier (default RS512). It must match the key type.
+ * @param {Object} [options.publicKeyJwk] - JWK of the signing key's public key to embed
+ * @param {string} [options.keyId] - Key ID to embed
+ * @param {string} [options.mode] - 'replace' (default), 'signers', or 'chain'
+ * @param {boolean} [options.signComponents] - Sign each component
+ * @param {boolean} [options.signServices] - Sign each service
+ * @param {boolean} [options.signAnnotations] - Sign each annotation
  * @returns {Object} - Signed BOM Object
  */
-export declare function signBom(bomJson: Object, options?: Object): Object;
+export declare function signBom(bomJson: Object, options?: {
+    privateKey: string | Buffer | Object | crypto.KeyObject;
+    algorithm?: string;
+    publicKeyJwk?: Object;
+    keyId?: string;
+    mode?: string;
+    signComponents?: boolean;
+    signServices?: boolean;
+    signAnnotations?: boolean;
+}): Object;
 /**
- * Verifies the integrity of a specific element node (e.g., BOM root, Component, Service, Annotation).
- * Resolves standard JSF signatures, multisignature (signers), and chains.
+ * Verifies the signature of a single node (e.g., BOM root, Component, Service,
+ * Annotation). Handles single signatures, multi-signatures (signers), and
+ * signature chains, and returns the first signature object that matches the key.
+ *
+ * A signature only matches when its declared algorithm fits the key type, its
+ * embedded publicKey (if any) is the verification key, and its value covers the
+ * node content plus the signature metadata as JSF defines.
  *
  * @param {Object} node - The BOM or granular object to verify
- * @param {string|crypto.KeyObject} publicKey - The public key corresponding to the signature
- * @returns {boolean|Object} - Signature block if signature is valid. False otherwise.
+ * @param {string|Buffer|Object|crypto.KeyObject} publicKey - Verification key. Strings and Buffers are parsed as public keys; use loadSharedSecret() for HMAC.
+ * @param {Object} [options]
+ * @param {string[]} [options.reasons] - When no signature matches, receives the reason each entry was rejected
+ * @returns {boolean|Object} - Matching signature object if valid. False otherwise.
  */
-export declare function verifyNode(node: Object, publicKey: string | crypto.KeyObject): boolean | Object;
+export declare function verifyNode(node: Object, publicKey: string | Buffer | Object | crypto.KeyObject, options?: {
+    reasons?: string[];
+}): boolean | Object;
 /**
- * Verifies the integrity of a BOM's top-level signature, as well as nested components, services, and annotations.
- * Returns true only if the root signature is valid AND all signed nested elements are valid.
+ * Verifies a BOM's top-level signature, as well as nested components, services,
+ * and annotations. Returns the root match only if the root signature is valid
+ * AND every signed nested element is valid for the same key.
  *
  * @param {Object} bom - CycloneDX BOM Object
- * @param {string|crypto.KeyObject} publicKey - The public key corresponding to the signature
- * @returns {boolean|Object} - Signature block if signature is valid. False otherwise.
+ * @param {string|Buffer|Object|crypto.KeyObject} publicKey - Verification key (see verifyNode)
+ * @param {Object} [options] - Same options as verifyNode
+ * @returns {boolean|Object} - Signature object if valid. False otherwise.
+ */
+export declare function verifyBom(bom: Object, publicKey: string | Buffer | Object | crypto.KeyObject, options?: Object): boolean | Object;
+/**
+ * Checks every signature entry of a node against a set of trusted keys. An
+ * entry is verified when one of the keys verifies that entry.
+ *
+ * `cdx-sign` uses this before appending to a signature chain, because the new
+ * chain entry vouches for every earlier entry.
+ *
+ * @param {Object} node - The BOM or granular object whose signature is checked
+ * @param {Array<string|Buffer|Object|crypto.KeyObject>} [keys] - Trusted verification keys (see verifyNode)
+ * @returns {Array<{ index: number, algorithm: any, keyId: any, verified: boolean, reasons: string[] }>} - One result per signature entry; empty for an unsigned node
  */
-export declare function verifyBom(bom: Object, publicKey: string | crypto.KeyObject): boolean | Object;
+export declare function checkSignatureEntries(node: Object, keys?: Array<string | Buffer | Object | crypto.KeyObject>): Array<{
+    index: number;
+    algorithm: any;
+    keyId: any;
+    verified: boolean;
+    reasons: string[];
+}>;
 //# sourceMappingURL=bomSigner.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"bomSigner.d.ts","sourceRoot":"","sources":["../../../lib/helpers/bomSigner.js"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,aAAa,CAAC;AAiIjC;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAJpB,MAIoB,EAAE,OAAO,GAH7B,MAGkC,GAFhC,MAAM,CAkDlB;AAuDD;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAJpB,MAIoB,EAAE,SAAS,EAH/B,MAAM,GAAC,MAAM,CAAC,SAGiB,GAF7B,OAAO,GAAC,MAAM,CA0B1B;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAJlB,MAIkB,EAAE,SAAS,EAH7B,MAAM,GAAC,MAAM,CAAC,SAGe,GAF3B,OAAO,GAAC,MAAM,CAgC1B"}
+{"version":3,"file":"bomSigner.d.ts","sourceRoot":"","sources":["../../../lib/helpers/bomSigner.js"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,aAAa,CAAC;AAuCjC;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAHvB,GAGuB,GAFrB,MAAM,CAWlB;AAgID;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAH9B,MAAM,GAAC,MAAM,GAAC,MAAM,CAAC,SAGS,GAF5B,MAAM,CAAC,SAAS,CA2B5B;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAH5B,MAAM,GAAC,MAAM,GAAC,MAAM,GAAC,MAAM,CAAC,SAGA,GAF1B,MAAM,CAAC,SAAS,CAW5B;AAwBD;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,EAHrC,MAGqC,GAFnC;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CA2BrD;AA+ND;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAZpB,MAYoB,EAAE,OAAO,GAVrC;IAAuD,UAAU,EAAzD,MAAM,GAAC,MAAM,GAAC,MAAM,GAAC,MAAM,CAAC,SAAS,CAC7C;IAAyB,SAAS,AAAlC,CACA,EADQ,MAAM,CACd;IAAyB,YAAY,AAArC,CACA,EADQ,MAAM,CACd;IAAyB,KAAK,AAA9B,CACA,EADQ,MAAM,CACd;IAAyB,IAAI,AAA7B,CACA,EADQ,MAAM,CACd;IAA0B,cAAc,AAAxC,CACA,EADQ,OAAO,CACf;IAA0B,YAAY,AAAtC,CACA,EADQ,OAAO,CACf;IAA0B,eAAe,AAAzC,CACA,EADQ,OAAO,CACf;CAE0C,GAFhC,MAAM,CA+DlB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,UAAU,CAAC,IAAI,EANpB,MAMoB,EAAE,SAAS,EAL/B,MAAM,GAAC,MAAM,GAAC,MAAM,GAAC,MAAM,CAAC,SAKG,EAAE,OAAO,AAJhD,CAEA,EADA;IAA2B,OAAO,AAAlC,CACA,EADQ,MAAM,EAAE,CAChB;CAEqD,GAF3C,OAAO,GAAC,MAAM,CA8B1B;AAED;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,GAAG,EALlB,MAKkB,EAAE,SAAS,EAJ7B,MAAM,GAAC,MAAM,GAAC,MAAM,GAAC,MAAM,CAAC,SAIC,EAAE,OAAO,AAH9C,CACA,EADQ,MAG2C,GAFzC,OAAO,GAAC,MAAM,CAiC1B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAJ/B,MAI+B,EAAE,IAAI,AAH7C,CACA,EADQ,KAAK,CAAC,MAAM,GAAC,MAAM,GAAC,MAAM,GAAC,MAAM,CAAC,SAAS,CAGD,GAFxC,KAAK,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,GAAG,CAAC;IAAC,KAAK,EAAE,GAAG,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CA2CtG"}