@vaultcompass/conductor 0.14.0 → 0.16.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/resolve.js CHANGED
@@ -59,7 +59,7 @@
59
59
  // depend on a package cache the report cannot describe, and a gate that
60
60
  // "ran" from an unknown version is worse than one that is honestly
61
61
  // reported missing.
62
- import { accessSync, constants, statSync } from 'node:fs';
62
+ import { accessSync, constants, lstatSync, statSync } from 'node:fs';
63
63
  import path from 'node:path';
64
64
  import { profileFor } from './products.js';
65
65
  export const CANDIDATES = {
@@ -220,6 +220,8 @@ export function resolveGateBinary(gate, repoRoot, pathValue, options = {}) {
220
220
  const prefix = gate.args ?? inferred?.prefix ?? table[0].prefix;
221
221
  const candidateName = inferred?.name ?? baseName(gate.command);
222
222
  const candidate = inferred ?? table[0];
223
+ const argumentPaths = argumentPathsOf(gate, repoRoot);
224
+ const dataArguments = dataArgumentPaths(gate, repoRoot);
223
225
  // A build directory holds plain .js files with a shebang but no
224
226
  // executable bit surprisingly often (a fresh tsc output, a file copied
225
227
  // out of a tarball). Running it through this same Node is exactly what
@@ -231,6 +233,8 @@ export function resolveGateBinary(gate, repoRoot, pathValue, options = {}) {
231
233
  // Node is the command; the script is what actually decides anything.
232
234
  program: gate.command,
233
235
  argvPrefix: [gate.command, ...prefix],
236
+ argumentPaths,
237
+ dataArguments,
234
238
  source: 'policy',
235
239
  candidate: candidateName,
236
240
  versionProbe: candidate.versionSafe && profileFor(gate.product).versionProbe !== null
@@ -241,13 +245,21 @@ export function resolveGateBinary(gate, repoRoot, pathValue, options = {}) {
241
245
  : versionProbeFor(gate.product, candidate, gate.command, repoRoot, pathValue, skipNodeModules),
242
246
  };
243
247
  }
248
+ // A command that is not itself a gate name (an interpreter, typically)
249
+ // and whose args hand it a script is asked through the script, or the
250
+ // version reported is the interpreter's (audit 2026-10-27, N4). A
251
+ // version-unsafe candidate keeps its sibling lookup: rule 2 above.
252
+ const viaScript = inferred === undefined && candidate.versionSafe ? scriptVersionProbe(gate, repoRoot) : null;
244
253
  return {
245
254
  command: gate.command,
246
255
  program: gate.command,
247
256
  argvPrefix: prefix,
257
+ argumentPaths,
258
+ dataArguments,
248
259
  source: 'policy',
249
260
  candidate: candidateName,
250
- versionProbe: versionProbeFor(gate.product, candidate, gate.command, repoRoot, pathValue, skipNodeModules),
261
+ versionProbe: viaScript ??
262
+ versionProbeFor(gate.product, candidate, gate.command, repoRoot, pathValue, skipNodeModules),
251
263
  };
252
264
  }
253
265
  for (const candidate of table) {
@@ -259,6 +271,8 @@ export function resolveGateBinary(gate, repoRoot, pathValue, options = {}) {
259
271
  command: found.command,
260
272
  program: found.command,
261
273
  argvPrefix: [...candidate.prefix],
274
+ argumentPaths: [],
275
+ dataArguments: [],
262
276
  source: found.source,
263
277
  candidate: candidate.name,
264
278
  versionProbe: versionProbeFor(gate.product, candidate, found.command, repoRoot, pathValue, skipNodeModules),
@@ -270,3 +284,274 @@ export function resolveGateBinary(gate, repoRoot, pathValue, options = {}) {
270
284
  export function candidateNames(product) {
271
285
  return CANDIDATES[product].map((candidate) => candidate.name);
272
286
  }
287
+ /**
288
+ * The extensions an interpreter can add to an entry before it looks at the
289
+ * entry as written: Node's main-entry resolution tries `.js`, `.json` and
290
+ * `.node` BEFORE a directory of the same name (`node tools/gate` runs
291
+ * `tools/gate.js` over `tools/gate/index.js`, measured on Node 22), and the
292
+ * ES module forms are listed too, so a sibling a loader might take is vetted
293
+ * whether or not this Node takes it (audit 2026-10-27 fix round, MB1 and
294
+ * MB2).
295
+ */
296
+ const LOADABLE_EXTENSIONS = ['.js', '.mjs', '.cjs', '.json', '.node'];
297
+ function existsAtAll(candidate) {
298
+ try {
299
+ lstatSync(candidate);
300
+ return true;
301
+ }
302
+ catch {
303
+ return false;
304
+ }
305
+ }
306
+ /**
307
+ * Whether the policy's `command:` is itself the gate program, so its `args:`
308
+ * are that gate's own argv rather than something an interpreter will load.
309
+ *
310
+ * True only when the command's NAME is a candidate name (`vault-guard`,
311
+ * `intent-guard.js`, executable or not). False for anything else: an
312
+ * interpreter such as `node` or `python3`, a renamed gate binary, and any
313
+ * wrapper or dispatcher whose name is not a gate name, a non-executable
314
+ * `my-build.js` included. Only when true are the product's subcommand words
315
+ * (`scan`, `source`) exempt from being read as paths, and the args read as
316
+ * the gate's own data rather than as code (`dataArgumentPaths`): an
317
+ * interpreter handed `scan` runs `scan.js` or `scan/index.js`, so for it the
318
+ * word is a path like any other (audit 2026-10-27 fix round, MB3).
319
+ *
320
+ * The name is the only test. An earlier version also counted every
321
+ * non-executable `.js` command, because this package runs one through its own
322
+ * Node with the script as the program; but how a file is RUN says nothing
323
+ * about what it LOADS, and a dispatcher that requires the script its first
324
+ * argument names let a pull request rewrite `scan.js` and pass (audit
325
+ * 2026-10-28, MB1).
326
+ */
327
+ export function commandIsGateProgram(gate) {
328
+ if (gate.command === undefined) {
329
+ return true;
330
+ }
331
+ const name = baseName(gate.command);
332
+ return CANDIDATES[gate.product].some((candidate) => candidate.name === name);
333
+ }
334
+ /**
335
+ * Every path an interpreter could load for one `args:` entry, as absolute
336
+ * paths, in the order checked; empty when the entry names nothing on disk
337
+ * (audit 2026-10-27, B1, and its fix round).
338
+ *
339
+ * Relative entries are resolved against `repoRoot`. That is the working
340
+ * directory of the version probe and of the gate's own spawn for every
341
+ * product except one whose base config can name further files
342
+ * (`followsConfigExtend`): on a pull request that gate runs from a temporary
343
+ * directory holding the base ref's copies (src/gate-runner.ts, spawnCwd), so
344
+ * a relative script there resolves against base copies or not at all, never
345
+ * against the head tree. The rules, in order:
346
+ *
347
+ * - An option with no `=` (`--json`, `-r`) names nothing. An option with one
348
+ * (`--config=tools/cfg.json`, `--import=./hook.mjs`) is read for the value
349
+ * after the first `=`, since that is where an interpreter takes a file to
350
+ * load and a gate takes a file to read its rules from.
351
+ * - Nothing else is exempt, the product's own subcommand words (`scan`,
352
+ * `source`) included: this is only ever asked for a command that is not
353
+ * the gate itself (commandIsGateProgram), and an interpreter handed `scan`
354
+ * runs `scan.js` or `scan/index.js`. The gate itself has no code args;
355
+ * its args are data (dataArgumentPaths).
356
+ * - The entry as written, when it exists as a file, a directory or a
357
+ * symlink, without following the symlink, so the caller can refuse an
358
+ * in-tree link on its own entry.
359
+ * - Then every `<entry>.js`, `.mjs`, `.cjs`, `.json` and `.node` that exists,
360
+ * slash or not, and whether or not the entry itself exists: Node tries
361
+ * those before a directory of the same name, and a bare `run` runs
362
+ * `run.js`. A sibling the head ADDED is listed too, which is what refuses
363
+ * it: the base does not track it.
364
+ *
365
+ * A directory's contents are covered by the caller's tree comparison, so
366
+ * `index.js` and `package.json` inside it are not listed separately; a
367
+ * `main` that points outside the directory is not vetted, the same limit as
368
+ * a program's directory. Everything else, a Python `-m` module name, a bare
369
+ * package specifier an interpreter resolves for itself, code passed as a
370
+ * string (`node -e`, `bash -c`), is not recognised as a path. The README says
371
+ * so.
372
+ */
373
+ export function argumentCandidates(arg, repoRoot) {
374
+ let value = arg;
375
+ if (arg.startsWith('-')) {
376
+ const equals = arg.indexOf('=');
377
+ if (equals < 0) {
378
+ return [];
379
+ }
380
+ value = arg.slice(equals + 1);
381
+ }
382
+ if (value === '') {
383
+ return [];
384
+ }
385
+ const absolute = path.resolve(repoRoot, value);
386
+ return [absolute, ...LOADABLE_EXTENSIONS.map((extension) => absolute + extension)].filter(existsAtAll);
387
+ }
388
+ /**
389
+ * Extensions that mark an args entry as CODE whatever the command is named
390
+ * (review 2026-10-28, N-e). None of the five gates reads such a file as data,
391
+ * so a gate-named command losing the code rule for them buys nothing, while a
392
+ * wrapper carrying a gate's name that hands `tools/run.js` to an interpreter
393
+ * would otherwise be vetted by that file's bytes alone, weaker than v0.15.0.
394
+ */
395
+ const CODE_EXTENSIONS = ['.js', '.mjs', '.cjs', '.node', '.ts', '.mts', '.cts', '.py', '.sh', '.bash', '.rb', '.pl'];
396
+ function hasCodeExtension(value) {
397
+ return CODE_EXTENSIONS.some((extension) => value.endsWith(extension));
398
+ }
399
+ /**
400
+ * A gate-named command's args entries, read by POSITION as that gate's own
401
+ * argv (review 2026-10-28, B1 and N-b):
402
+ *
403
+ * - `--name=value` and `-x=value`: the value, an option value;
404
+ * - `--name` or `-x` with no `=`: the NEXT entry is its value, unless that
405
+ * entry is itself an option. Which options take a value is the gate's
406
+ * business and not known here, so a word after any such option is read
407
+ * as one; that is the fail-closed direction (a positional written after a
408
+ * flag is vetted as data, and the refusal says to write it first);
409
+ * - `-xvalue`, a short option joined to its value (pflag shorthand): the
410
+ * rest of the word, an option value. Bundled flags (`-rv`) read the same
411
+ * way name nothing on disk, so they cost one lookup and refuse nothing;
412
+ * - a bare word that is one of the product's subcommands: nothing;
413
+ * - any other word: a positional.
414
+ */
415
+ /**
416
+ * Flags that take NO value, per product, read from each gate's own `--help`
417
+ * (osv-scanner 2.4.0 `scan source`, gitleaks 8.30.1 `git`, dep-guard 0.17.0
418
+ * and vault-guard 1.12.1 `scan`, intent-guard 1.10.2 `check`). The word after
419
+ * one of these is NOT its value, so `osv-scanner scan source -r .` keeps `.`
420
+ * as a positional scan target (re-review 2026-10-28, R1). Any flag not listed
421
+ * stays fail-closed: the word after it is read as its value. A wrong entry
422
+ * would let a value be read as a positional, which leaves a directory
423
+ * unvetted, so entries come only from a gate's own help text.
424
+ */
425
+ const NO_VALUE_FLAGS = {
426
+ 'osv-scanner': [
427
+ '-r', '--recursive', '--no-ignore', '--include-git-root', '--serve', '--offline',
428
+ '--offline-vulnerabilities', '--download-offline-databases', '--no-resolve',
429
+ '--allow-no-lockfiles', '--all-packages', '--all-vulns',
430
+ '--experimental-flag-deprecated-packages', '--experimental-no-default-plugins', '-h', '--help',
431
+ ],
432
+ gitleaks: [
433
+ '-v', '--verbose', '--pre-commit', '--staged', '--ignore-gitleaks-allow', '--no-banner',
434
+ '--no-color', '--redact', '-h', '--help',
435
+ ],
436
+ 'dep-guard': ['--staged', '--online', '--no-online', '-h', '--help'],
437
+ 'vault-guard': ['--staged', '-h', '--help'],
438
+ 'intent-guard': ['--staged', '--no-require-frozen', '--log', '--json', '-h', '--help', '-v', '--version'],
439
+ };
440
+ function gateArgEntries(gate) {
441
+ const entries = [];
442
+ let pendingOption = false;
443
+ for (const arg of gate.args ?? []) {
444
+ if (arg.startsWith('-') && arg !== '-') {
445
+ pendingOption = false;
446
+ const equals = arg.indexOf('=');
447
+ if (equals >= 0) {
448
+ entries.push({ value: arg.slice(equals + 1), positional: false, entry: arg });
449
+ }
450
+ else if (!arg.startsWith('--') && arg.length > 2) {
451
+ entries.push({ value: arg.slice(2), positional: false, entry: arg });
452
+ }
453
+ else {
454
+ // A flag the gate's own help says takes no value leaves the next word
455
+ // a positional (NO_VALUE_FLAGS); any other flag claims it.
456
+ pendingOption = !NO_VALUE_FLAGS[gate.product].includes(arg);
457
+ }
458
+ continue;
459
+ }
460
+ if (pendingOption) {
461
+ pendingOption = false;
462
+ entries.push({ value: arg, positional: false, entry: arg });
463
+ continue;
464
+ }
465
+ if (CANDIDATES[gate.product].some((candidate) => candidate.prefix.includes(arg))) {
466
+ continue;
467
+ }
468
+ entries.push({ value: arg, positional: true, entry: arg });
469
+ }
470
+ return entries.filter((each) => each.value !== '');
471
+ }
472
+ /**
473
+ * The args entries vetted as CODE: every entry when the command is not the
474
+ * gate itself, and only the code-extension values (`hasCodeExtension`) when
475
+ * it is. Each goes through `argumentCandidates`, here and in the preview.
476
+ */
477
+ export function codeArguments(gate) {
478
+ if (!commandIsGateProgram(gate)) {
479
+ return gate.args ?? [];
480
+ }
481
+ return gateArgEntries(gate)
482
+ .filter((each) => hasCodeExtension(each.value))
483
+ .map((each) => each.value);
484
+ }
485
+ /** `argumentCandidates` for every code argument (`codeArguments`), flattened. */
486
+ function argumentPathsOf(gate, repoRoot) {
487
+ return codeArguments(gate).flatMap((arg) => argumentCandidates(arg, repoRoot));
488
+ }
489
+ /**
490
+ * The args entries of a gate-named command that are its own DATA, when
491
+ * `command:` is the gate itself (commandIsGateProgram), in args order; empty
492
+ * for every other command (audit 2026-10-28, N1, and its review, B1, N-a,
493
+ * N-b, N-e).
494
+ *
495
+ * Every non-code entry (`gateArgEntries`, less the code-extension ones in
496
+ * `codeArguments`) is listed with its position, resolved against the
497
+ * repository root, WHETHER OR NOT the head's disk has it and whatever kind of
498
+ * thing the disk holds there: a head must not be able to delete a path or
499
+ * change it from a file to a directory to move it out of vetting. What each
500
+ * one is, and so which rule applies, is decided from the base tree by
501
+ * refuseHeadControlledData. No `<entry>.js` sibling is tried: that is how an
502
+ * interpreter resolves a name, and this command is not one.
503
+ *
504
+ * What this trusts is the NAME: a program named like a gate is taken to be
505
+ * that gate, except that a code-extension entry keeps the code rule. A
506
+ * wrapper given a gate's name that hands an extension-less entry to an
507
+ * interpreter is a wrapper, vetted no further than this (README,
508
+ * pull-request trust boundary).
509
+ */
510
+ export function dataArgumentPaths(gate, repoRoot) {
511
+ if (gate.command === undefined || !commandIsGateProgram(gate)) {
512
+ return [];
513
+ }
514
+ return gateArgEntries(gate)
515
+ .filter((each) => !hasCodeExtension(each.value))
516
+ .map((each) => ({ path: path.resolve(repoRoot, each.value), positional: each.positional, entry: each.entry }));
517
+ }
518
+ /**
519
+ * The version probe for a policy `command:` that is not itself a gate name,
520
+ * when its `args:` hand it a script: the args up to and including the first
521
+ * non-option entry, when that entry names something the interpreter can load
522
+ * (argumentCandidates: a file, a directory, or a bare or extension-less name
523
+ * with a loadable sibling), then the product's own probe argv. The entry is
524
+ * passed as written, so the interpreter resolves it exactly as it will for
525
+ * the scan. So `node tools/gate/run.mjs scan` is asked `node
526
+ * tools/gate/run.mjs --version`, `node tools/gate` is asked `node tools/gate
527
+ * --version`, and the version reported is the script's, not Node's (audit
528
+ * 2026-10-27, N4). Null when the first non-option entry names nothing, or
529
+ * there is none, and the caller keeps the probe it would have made anyway.
530
+ *
531
+ * Only the first: everything after the script is the script's own argv, and
532
+ * carrying a subcommand or a target into a probe would make it do work,
533
+ * which is the one thing a probe must not do.
534
+ * An interpreter flag that takes a file as a separate entry (`-r
535
+ * ./setup.js`) makes that file the first, so the probe asks the interpreter
536
+ * and reports its version, as it did before; under an expected-version pin
537
+ * that is could-not-run, the fail-closed direction.
538
+ */
539
+ function scriptVersionProbe(gate, repoRoot) {
540
+ const spec = profileFor(gate.product).versionProbe;
541
+ if (spec === null || gate.command === undefined || gate.args === undefined) {
542
+ return null;
543
+ }
544
+ for (let index = 0; index < gate.args.length; index += 1) {
545
+ const arg = gate.args[index];
546
+ if (arg.startsWith('-')) {
547
+ continue;
548
+ }
549
+ // Only the FIRST non-option entry can be the script. A later file is the
550
+ // script's own argument (`my-build check rules.json`), and a probe that
551
+ // carried the subcommand before it would make the gate do work.
552
+ return argumentCandidates(arg, repoRoot).length > 0
553
+ ? { command: gate.command, argv: [...gate.args.slice(0, index + 1), ...spec.argv] }
554
+ : null;
555
+ }
556
+ return null;
557
+ }
@@ -323,7 +323,9 @@ export declare function treeEntryAt(repoRoot: string, ref: string, relativePath:
323
323
  * Vetting the target is what catches a link whose own path is outside the
324
324
  * tree pointing into it; it never decides the in-repo case.
325
325
  */
326
- export declare function refuseHeadControlledProgram(repoRoot: string, trustBase: string, programPath: string): string | null;
326
+ export declare function refuseHeadControlledProgram(repoRoot: string, trustBase: string, programPath: string,
327
+ /** True when asked for an interpreter's `args:` entry, which words the root refusal for an argument. */
328
+ fromArgs?: boolean): string | null;
327
329
  /**
328
330
  * Whether a gate's reported version is at least `minimum`.
329
331
  *
@@ -336,3 +338,80 @@ export declare function refuseHeadControlledProgram(repoRoot: string, trustBase:
336
338
  * for every repository pinning an older gate.
337
339
  */
338
340
  export declare function atLeastVersion(version: string | null, minimum: string): boolean;
341
+ /**
342
+ * Why a path named in a gate's `args:` cannot be trusted on a pull-request
343
+ * run, or null (audit 2026-10-27, B1).
344
+ *
345
+ * An interpreter `command:` takes the program as an argument: with
346
+ * `command: /usr/bin/node` and `args: [tools/gate/run.mjs, scan]` the script
347
+ * judges and Node only runs it, so vetting `command:` alone let a pull request
348
+ * rewrite the script and choose its own judge. `argumentCandidates`
349
+ * (src/resolve.ts) lists every path an interpreter could load for an entry,
350
+ * the entry and each of its loadable siblings (`tools/gate.js` beside
351
+ * `tools/gate/`), and each one is asked here separately; this decides
352
+ * whether that one path is the base's.
353
+ *
354
+ * - A FILE, or a symlink of any kind, goes through refuseHeadControlledProgram
355
+ * unchanged: blob and containing directory identical at both refs, an
356
+ * in-tree link refused on its own entry, the root refused, anything outside
357
+ * the tree accepted. The same rule as a `command:`, because it is the same
358
+ * question.
359
+ * - A DIRECTORY inside the tree is accepted only when it is a tracked tree
360
+ * at both refs with the same tree object id: when no sibling file wins,
361
+ * an interpreter handed a directory (`node tools/gate`) runs what is
362
+ * inside it, so the whole subtree is the unit, as it is beside a program.
363
+ * A sibling file that would win is a separate candidate, vetted as a file.
364
+ * - THE REPOSITORY ROOT ITSELF is refused (`node .` runs the head's own
365
+ * package.json main). Approving it would mean comparing the whole tree,
366
+ * which differs on every pull request; conductor already hands every gate
367
+ * the repository it scans, so no gate needs the root in `args:`.
368
+ *
369
+ * NOTHING HERE READS THE WORKING TREE's CONTENTS, as for the program: both
370
+ * sides are `git ls-tree` listings. Only whether the entry is a directory is
371
+ * read from disk, and a link is never followed for that, so a link is always
372
+ * vetted as a link.
373
+ */
374
+ export declare function refuseHeadControlledArgument(repoRoot: string, trustBase: string, argumentPath: string): string | null;
375
+ /**
376
+ * Why a path a gate's own `args:` name cannot be trusted on a pull-request
377
+ * run, or null (audit 2026-10-28, N1, and its review, B1 and N-a).
378
+ *
379
+ * Asked only when `command:` is the gate itself (dataArgumentPaths in
380
+ * src/resolve.ts), whose args are its own argv: a rules file such as
381
+ * `--config=.gitleaks.toml`, or a rules directory such as dep-guard's
382
+ * `--corpus-dir`, is read as data, not loaded as code. Its contents still
383
+ * decide what the gate reports, so a pull request that rewrote them would
384
+ * choose the rules that judge it; but nothing beside a file runs, so a
385
+ * file's directory is not compared and a file at the repository root is
386
+ * fine.
387
+ *
388
+ * WHAT THE PATH IS COMES FROM THE BASE TREE, never from the head's disk, so a
389
+ * head cannot delete a path or turn a file into a directory to change which
390
+ * rule applies:
391
+ *
392
+ * - Outside the working tree, by its own spelling and by its realpath:
393
+ * accepted, as for a program.
394
+ * - The repository root: accepted as a POSITIONAL entry (`scan .`, the
395
+ * repository the gate is handed anyway, which is the thing being judged
396
+ * and cannot be the base's on any pull request), refused as an OPTION
397
+ * VALUE (`--corpus-dir=.` would make the whole head tree the rules).
398
+ * - A tree at the base: a positional entry is a scan target and is not
399
+ * compared (the head's version of it is what the gate is there to judge).
400
+ * An option value is data: the head must hold a tree with the same tree
401
+ * object id, or it is refused.
402
+ * - A blob at the base: a tracked regular file at both refs with the same
403
+ * blob, whatever its position. An in-tree link is refused on its own entry
404
+ * (a link entry), as everywhere else, because what it points at is the
405
+ * head's choice. A head that deleted it or replaced it is refused.
406
+ * - Absent at the base: accepted only if the head has nothing there either,
407
+ * tracked or on disk (a word that is not a path, `--format=json`);
408
+ * otherwise it is a path this pull request chose, and refused.
409
+ *
410
+ * Only whether something exists on disk at a path the base does not track is
411
+ * read from the working tree; every other answer is a `git ls-tree` listing.
412
+ */
413
+ export declare function refuseHeadControlledData(repoRoot: string, trustBase: string, data: {
414
+ path: string;
415
+ positional: boolean;
416
+ entry?: string;
417
+ }): string | null;