@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/README.md +159 -1123
- package/dist/gate-runner.d.ts +20 -0
- package/dist/gate-runner.js +64 -2
- package/dist/output-sarif.js +2 -2
- package/dist/output-text.js +24 -8
- package/dist/policy-diff.d.ts +9 -0
- package/dist/policy-diff.js +12 -4
- package/dist/resolve.d.ts +131 -0
- package/dist/resolve.js +287 -2
- package/dist/trust-base.d.ts +80 -1
- package/dist/trust-base.js +258 -5
- package/package.json +1 -1
package/dist/gate-runner.d.ts
CHANGED
|
@@ -519,6 +519,13 @@ export declare function preparationTimedOut(gate: GatePolicy, stopped: {
|
|
|
519
519
|
* only the first left the probe free to spawn whatever the head put at the
|
|
520
520
|
* second, and a probe RUNS a program as thoroughly as a scan does.
|
|
521
521
|
*
|
|
522
|
+
* And every path the policy's `args:` name (`binary.argumentPaths`), because
|
|
523
|
+
* an interpreter `command:` takes the program as an argument: with `command:
|
|
524
|
+
* /usr/bin/node` and `args: [tools/gate/run.mjs]` the script judges, and
|
|
525
|
+
* vetting Node alone let a pull request rewrite the script (audit 2026-10-27,
|
|
526
|
+
* B1). The version probe's argv is a prefix of those same args, so it is
|
|
527
|
+
* covered by the same loop.
|
|
528
|
+
*
|
|
522
529
|
* The first refusal wins and the rest is not consulted. The verdict is the
|
|
523
530
|
* same either way, and the sentence a reader has to act on should name one
|
|
524
531
|
* file rather than two.
|
|
@@ -655,3 +662,16 @@ export declare function runGate(gate: GatePolicy, options: RunGateOptions): Gate
|
|
|
655
662
|
*/
|
|
656
663
|
/** The oldest git a history gate runs under on a pull-request run. */
|
|
657
664
|
export declare const HISTORY_GIT_FLOOR = "2.31.0";
|
|
665
|
+
/**
|
|
666
|
+
* cleanOutputLine, then every remaining character outside printable ASCII
|
|
667
|
+
* escaped as \uXXXX (escapeNonAscii). For every preview line: there a gate
|
|
668
|
+
* reads the head's own control files, so a rule id or a message can be
|
|
669
|
+
* head-chosen text, a right-to-left override included (audit 2026-10-27,
|
|
670
|
+
* N3). cleanOutputLine alone breaks a workflow command and keeps the
|
|
671
|
+
* override. The primary run is NOT safe by the same argument: its rule ids
|
|
672
|
+
* come from base-approved config, but its file paths are the head's own
|
|
673
|
+
* names. So the primary text report escapes finding paths (subjectLabel,
|
|
674
|
+
* src/output-text.ts), and only those; a primary gate message or stderr
|
|
675
|
+
* excerpt that quotes a path keeps its characters, a known limit.
|
|
676
|
+
*/
|
|
677
|
+
export declare function cleanPreviewLine(raw: string): string;
|
package/dist/gate-runner.js
CHANGED
|
@@ -30,8 +30,9 @@ import { checkEmptiedAgainstBase, compareWithBase, comparisonFailed, } from './o
|
|
|
30
30
|
import { ExternalConfigError, materializeExternalConfig, nestedConfigProposals, } from './external-config.js';
|
|
31
31
|
import { osvLockfileKind, profileFor } from './products.js';
|
|
32
32
|
import { unreadManifestsNote } from './unread-manifests.js';
|
|
33
|
-
import {
|
|
34
|
-
import {
|
|
33
|
+
import { escapeNonAscii } from './policy-diff.js';
|
|
34
|
+
import { atLeastVersion, refuseHeadControlledArgument, refuseHeadControlledData, refuseHeadControlledProgram, } from './trust-base.js';
|
|
35
|
+
import { ResolveError, argumentCandidates, candidateNames, codeArguments, nodeModulesCandidate, resolveGateBinary, } from './resolve.js';
|
|
35
36
|
/** The longest excerpt of a gate's own reason that is carried. */
|
|
36
37
|
export const GATE_SAID_MAX_CHARS = 160;
|
|
37
38
|
/**
|
|
@@ -653,6 +654,13 @@ const EMPTY_RUN = {
|
|
|
653
654
|
* only the first left the probe free to spawn whatever the head put at the
|
|
654
655
|
* second, and a probe RUNS a program as thoroughly as a scan does.
|
|
655
656
|
*
|
|
657
|
+
* And every path the policy's `args:` name (`binary.argumentPaths`), because
|
|
658
|
+
* an interpreter `command:` takes the program as an argument: with `command:
|
|
659
|
+
* /usr/bin/node` and `args: [tools/gate/run.mjs]` the script judges, and
|
|
660
|
+
* vetting Node alone let a pull request rewrite the script (audit 2026-10-27,
|
|
661
|
+
* B1). The version probe's argv is a prefix of those same args, so it is
|
|
662
|
+
* covered by the same loop.
|
|
663
|
+
*
|
|
656
664
|
* The first refusal wins and the rest is not consulted. The verdict is the
|
|
657
665
|
* same either way, and the sentence a reader has to act on should name one
|
|
658
666
|
* file rather than two.
|
|
@@ -667,6 +675,21 @@ export function refuseHeadControlledBinary(repoRoot, trustBase, binary) {
|
|
|
667
675
|
return refusal;
|
|
668
676
|
}
|
|
669
677
|
}
|
|
678
|
+
for (const argument of binary.argumentPaths) {
|
|
679
|
+
const refusal = refuseHeadControlledArgument(repoRoot, trustBase, argument);
|
|
680
|
+
if (refusal !== null) {
|
|
681
|
+
return refusal;
|
|
682
|
+
}
|
|
683
|
+
}
|
|
684
|
+
// A command that is the gate itself reads the rest of its args as data
|
|
685
|
+
// (audit 2026-10-28, N1, and its review): what each path is comes from the
|
|
686
|
+
// base tree, and a file or an option-value directory must be the base's.
|
|
687
|
+
for (const data of binary.dataArguments) {
|
|
688
|
+
const refusal = refuseHeadControlledData(repoRoot, trustBase, data);
|
|
689
|
+
if (refusal !== null) {
|
|
690
|
+
return refusal;
|
|
691
|
+
}
|
|
692
|
+
}
|
|
670
693
|
return null;
|
|
671
694
|
}
|
|
672
695
|
/**
|
|
@@ -1287,6 +1310,30 @@ function previewRefusal(gate, repoRoot) {
|
|
|
1287
1310
|
detail: `preview under the proposed rules: the base command ${gate.command} is inside the working tree, so this gate was not run`,
|
|
1288
1311
|
};
|
|
1289
1312
|
}
|
|
1313
|
+
// THE SAME FOR A PATH IN args:, for the same reason (audit 2026-10-27, B1):
|
|
1314
|
+
// an interpreter command takes the program as an argument, and a script in
|
|
1315
|
+
// the tree imports from the head as surely as a command there does. Refused
|
|
1316
|
+
// outright, as the command is, rather than by the base-equality rule: that
|
|
1317
|
+
// rule still runs in runGate on every preview spawn, so this is the
|
|
1318
|
+
// stricter of the two. The root counts as inside, and so does a link whose
|
|
1319
|
+
// own entry is in the tree, wherever it points (its directory is checked).
|
|
1320
|
+
// The candidate set is the primary run's (argumentCandidates): the entry and
|
|
1321
|
+
// every loadable sibling of it, so a head-added tools/gate.js beside a base
|
|
1322
|
+
// tools/gate/ is refused here too. The entries are the primary run's code
|
|
1323
|
+
// arguments (codeArguments): every entry for a command that is not the gate
|
|
1324
|
+
// itself, and only the code-extension ones for one that is. The gate's
|
|
1325
|
+
// other args are data it reads (audit 2026-10-28, N1), and runGate's data
|
|
1326
|
+
// check (refuseHeadControlledData, through refuseHeadControlledBinary) runs
|
|
1327
|
+
// on every preview spawn, an option-value directory included (review B1).
|
|
1328
|
+
for (const arg of codeArguments(gate)) {
|
|
1329
|
+
const candidates = argumentCandidates(arg, repoRoot);
|
|
1330
|
+
if (candidates.some((named) => realPathInside(repoRoot, named) || realPathInside(repoRoot, path.dirname(named)))) {
|
|
1331
|
+
return {
|
|
1332
|
+
reason: 'gate-program-refused',
|
|
1333
|
+
detail: `preview under the proposed rules: the base args entry ${arg} names a path inside the working tree, so this gate was not run`,
|
|
1334
|
+
};
|
|
1335
|
+
}
|
|
1336
|
+
}
|
|
1290
1337
|
return null;
|
|
1291
1338
|
}
|
|
1292
1339
|
/**
|
|
@@ -2359,3 +2406,18 @@ function spawnAndRead(ctx) {
|
|
|
2359
2406
|
};
|
|
2360
2407
|
}
|
|
2361
2408
|
}
|
|
2409
|
+
/**
|
|
2410
|
+
* cleanOutputLine, then every remaining character outside printable ASCII
|
|
2411
|
+
* escaped as \uXXXX (escapeNonAscii). For every preview line: there a gate
|
|
2412
|
+
* reads the head's own control files, so a rule id or a message can be
|
|
2413
|
+
* head-chosen text, a right-to-left override included (audit 2026-10-27,
|
|
2414
|
+
* N3). cleanOutputLine alone breaks a workflow command and keeps the
|
|
2415
|
+
* override. The primary run is NOT safe by the same argument: its rule ids
|
|
2416
|
+
* come from base-approved config, but its file paths are the head's own
|
|
2417
|
+
* names. So the primary text report escapes finding paths (subjectLabel,
|
|
2418
|
+
* src/output-text.ts), and only those; a primary gate message or stderr
|
|
2419
|
+
* excerpt that quotes a path keeps its characters, a known limit.
|
|
2420
|
+
*/
|
|
2421
|
+
export function cleanPreviewLine(raw) {
|
|
2422
|
+
return escapeNonAscii(cleanOutputLine(raw));
|
|
2423
|
+
}
|
package/dist/output-sarif.js
CHANGED
|
@@ -118,7 +118,7 @@
|
|
|
118
118
|
// normalize.ts, which is where the omission would stop mattering if the
|
|
119
119
|
// field were ever carried.
|
|
120
120
|
import { gateExitBlocks } from './exit-codes.js';
|
|
121
|
-
import {
|
|
121
|
+
import { cleanPreviewLine } from './gate-runner.js';
|
|
122
122
|
import { NATIVE_CONTRACT_PATH, isLegacyContractPath } from './intent-prepare.js';
|
|
123
123
|
import { INTENT_WARNING } from './normalize.js';
|
|
124
124
|
import { gateOutcomeWords, skewFound, skewPlace } from './output-text.js';
|
|
@@ -724,7 +724,7 @@ function previewNotifications(result) {
|
|
|
724
724
|
return [];
|
|
725
725
|
}
|
|
726
726
|
return guardPreview(() => preview.gates.map((gate) => {
|
|
727
|
-
const outcome =
|
|
727
|
+
const outcome = cleanPreviewLine(gateOutcomeWords(gate));
|
|
728
728
|
return {
|
|
729
729
|
id: 'conductor/preview-under-proposed-rules',
|
|
730
730
|
message: 'Preview under the proposed rules, which does not affect the verdict: ' +
|
package/dist/output-text.js
CHANGED
|
@@ -23,20 +23,26 @@
|
|
|
23
23
|
// everywhere is worth more here than a nicer-looking terminal.
|
|
24
24
|
import { compareFindings } from './envelope.js';
|
|
25
25
|
import { EXIT_BLOCKED, EXIT_COULD_NOT_RUN, gateExitBlocks } from './exit-codes.js';
|
|
26
|
-
import { CONDUCTOR_OWN_REASONS, cleanOutputLine, conductorStatedReason, resolutionPlace, versionCharacters, versionSkewRemedy, } from './gate-runner.js';
|
|
26
|
+
import { CONDUCTOR_OWN_REASONS, cleanOutputLine, cleanPreviewLine, conductorStatedReason, resolutionPlace, versionCharacters, versionSkewRemedy, } from './gate-runner.js';
|
|
27
27
|
import { isLegacyContractPath, legacyChangedSentence } from './intent-prepare.js';
|
|
28
28
|
import { SPEC_DIR } from './intent-spec.js';
|
|
29
29
|
import { PRODUCT_FOR_ROLE } from './policy.js';
|
|
30
|
+
import { escapeNonAscii } from './policy-diff.js';
|
|
30
31
|
import { guardPreview } from './run.js';
|
|
32
|
+
// A file path in a finding is the head's choice on any pull-request run (a
|
|
33
|
+
// file named with a right-to-left override in it), so in the text report,
|
|
34
|
+
// and so in the pull-request comment, every path is printed with
|
|
35
|
+
// escapeNonAscii (audit 2026-10-27 fix round, N3). SARIF keeps the real path:
|
|
36
|
+
// code scanning has to find the file.
|
|
31
37
|
function subjectLabel(finding) {
|
|
32
38
|
const subject = finding.subject;
|
|
33
39
|
switch (subject.kind) {
|
|
34
40
|
case 'package':
|
|
35
|
-
return `${subject.name} (${subject.manifest})`;
|
|
41
|
+
return `${subject.name} (${escapeNonAscii(subject.manifest)})`;
|
|
36
42
|
case 'location':
|
|
37
|
-
return `${subject.file}:${subject.line}:${subject.column}`;
|
|
43
|
+
return `${escapeNonAscii(subject.file)}:${subject.line}:${subject.column}`;
|
|
38
44
|
case 'paths':
|
|
39
|
-
return subject.paths.join(', ');
|
|
45
|
+
return subject.paths.map(escapeNonAscii).join(', ');
|
|
40
46
|
case 'contract':
|
|
41
47
|
return subject.category === undefined ? 'intent contract' : `contract: ${subject.category}`;
|
|
42
48
|
case 'none':
|
|
@@ -83,7 +89,7 @@ function osvSubject(entry) {
|
|
|
83
89
|
const name = first.subject.kind === 'package' ? first.subject.name : '';
|
|
84
90
|
const installed = typeof first.details.version === 'string' ? first.details.version : '';
|
|
85
91
|
const where = entry.length === 1 && first.subject.kind === 'package'
|
|
86
|
-
? `(${first.subject.manifest})`
|
|
92
|
+
? `(${escapeNonAscii(first.subject.manifest)})`
|
|
87
93
|
: `${entry.length} lockfiles`;
|
|
88
94
|
const fixed = typeof first.details.fixedVersion === 'string' ? `fix ${first.details.fixedVersion}` : 'no fix listed';
|
|
89
95
|
const dev = entry.filter(isDev).length;
|
|
@@ -150,7 +156,7 @@ function findingLines(entry, verbose, shortProblem) {
|
|
|
150
156
|
lines.push(...gitleaksLines(finding));
|
|
151
157
|
}
|
|
152
158
|
if (verbose && entry.length > 1) {
|
|
153
|
-
const manifests = entry.map((each) => (each.subject.kind === 'package' ? each.subject.manifest : ''));
|
|
159
|
+
const manifests = entry.map((each) => (each.subject.kind === 'package' ? escapeNonAscii(each.subject.manifest) : ''));
|
|
154
160
|
lines.push(` lockfiles: ${manifests.join(', ')}`);
|
|
155
161
|
}
|
|
156
162
|
return lines;
|
|
@@ -229,6 +235,14 @@ function enforcementNote(gate) {
|
|
|
229
235
|
`${gate.exitCode ?? '?'}, and enforce is false for it in .guardrails.yaml, so the commit ` +
|
|
230
236
|
'proceeds. Set enforce: true there to make it block.');
|
|
231
237
|
}
|
|
238
|
+
// A gate that ran and checked nothing (an intent gate with no contract, a
|
|
239
|
+
// scanner with nothing to scan) found nothing because it looked at nothing,
|
|
240
|
+
// and "found nothing to block on" reads as a clean result (audit
|
|
241
|
+
// 2026-10-28, N5). The same predicate and words as the verdict's list.
|
|
242
|
+
if (gateCheckedNothing(gate)) {
|
|
243
|
+
return (' not enforced: enforce is false for this gate in .guardrails.yaml, and it checked ' +
|
|
244
|
+
`nothing here: ${checkedNothingWording(gate)}. This is not a clean result.`);
|
|
245
|
+
}
|
|
232
246
|
return ' not enforced: enforce is false for this gate in .guardrails.yaml. It found nothing to block on here.';
|
|
233
247
|
}
|
|
234
248
|
/**
|
|
@@ -750,7 +764,9 @@ export function previewLines(result, verbose) {
|
|
|
750
764
|
}
|
|
751
765
|
return lines;
|
|
752
766
|
}, (message) => [`preview: could not be completed (${message})`]);
|
|
753
|
-
|
|
767
|
+
// cleanPreviewLine, not cleanOutputLine: a head .vault-guard.json can name
|
|
768
|
+
// a pattern id with a right-to-left override in it (audit 2026-10-27, N3).
|
|
769
|
+
return ['', PREVIEW_HEADER, ...body].map(cleanPreviewLine);
|
|
754
770
|
}
|
|
755
771
|
/**
|
|
756
772
|
* The preview's job log lines: one per preview gate in the per-gate lines'
|
|
@@ -767,7 +783,7 @@ export function previewLogLines(result) {
|
|
|
767
783
|
...preview.overBudget.map((role) => `conductor: preview ${role} (${PRODUCT_FOR_ROLE[role]}) over budget`),
|
|
768
784
|
...(preview.deferred.includes('intent') ? ['conductor: preview intent (intent-guard) deferred'] : []),
|
|
769
785
|
], (message) => [`conductor: preview could not be completed (${message})`]);
|
|
770
|
-
return lines.map(
|
|
786
|
+
return lines.map(cleanPreviewLine);
|
|
771
787
|
}
|
|
772
788
|
/**
|
|
773
789
|
* One plain line per gate, for the job log: which gate, which version, what
|
package/dist/policy-diff.d.ts
CHANGED
|
@@ -14,6 +14,15 @@ export declare const HEAD_POLICY_KEY = ".guardrails.yaml";
|
|
|
14
14
|
* file's. A null head (absent or unparseable) is one change that says so.
|
|
15
15
|
*/
|
|
16
16
|
export declare function diffPolicies(base: Policy, head: Policy | null): PolicyKeyChange[];
|
|
17
|
+
/**
|
|
18
|
+
* Every character outside printable ASCII as a \uXXXX escape (an astral
|
|
19
|
+
* character as its two surrogate escapes), so head-chosen text cannot smuggle
|
|
20
|
+
* a bidi override or a zero-width character into the report. Used for a head
|
|
21
|
+
* policy value here, and for every preview line (cleanPreviewLine,
|
|
22
|
+
* src/gate-runner.ts), whose gate text the head's own control files can
|
|
23
|
+
* choose (audit 2026-10-27, N3).
|
|
24
|
+
*/
|
|
25
|
+
export declare function escapeNonAscii(text: string): string;
|
|
17
26
|
/** One proposal line for one changed key. */
|
|
18
27
|
export declare function policyChangeLine(change: PolicyKeyChange): string;
|
|
19
28
|
/**
|
package/dist/policy-diff.js
CHANGED
|
@@ -92,14 +92,22 @@ export function diffPolicies(base, head) {
|
|
|
92
92
|
}
|
|
93
93
|
return changes;
|
|
94
94
|
}
|
|
95
|
+
/**
|
|
96
|
+
* Every character outside printable ASCII as a \uXXXX escape (an astral
|
|
97
|
+
* character as its two surrogate escapes), so head-chosen text cannot smuggle
|
|
98
|
+
* a bidi override or a zero-width character into the report. Used for a head
|
|
99
|
+
* policy value here, and for every preview line (cleanPreviewLine,
|
|
100
|
+
* src/gate-runner.ts), whose gate text the head's own control files can
|
|
101
|
+
* choose (audit 2026-10-27, N3).
|
|
102
|
+
*/
|
|
103
|
+
export function escapeNonAscii(text) {
|
|
104
|
+
return text.replace(/[^\x20-\x7e]/g, (ch) => `\\u${ch.charCodeAt(0).toString(16).padStart(4, '0')}`);
|
|
105
|
+
}
|
|
95
106
|
function renderValue(value) {
|
|
96
107
|
if (value === undefined)
|
|
97
108
|
return '(absent)';
|
|
98
109
|
const text = JSON.stringify(value) ?? '(absent)';
|
|
99
|
-
|
|
100
|
-
// astral character as its two surrogate escapes), so a head option value
|
|
101
|
-
// cannot smuggle a bidi override or a zero-width character into the report.
|
|
102
|
-
const escaped = text.replace(/[^\x20-\x7e]/g, (ch) => `\\u${ch.charCodeAt(0).toString(16).padStart(4, '0')}`);
|
|
110
|
+
const escaped = escapeNonAscii(text);
|
|
103
111
|
if (escaped.length <= MAX_VALUE_LENGTH)
|
|
104
112
|
return escaped;
|
|
105
113
|
// Keep whole tokens up to 77 characters, so no escape sequence is split.
|
package/dist/resolve.d.ts
CHANGED
|
@@ -18,6 +18,15 @@ export interface VersionProbe {
|
|
|
18
18
|
command: string;
|
|
19
19
|
argv: string[];
|
|
20
20
|
}
|
|
21
|
+
/** One args entry of a gate-named command that could name a path (`dataArgumentPaths`). */
|
|
22
|
+
export interface DataArgument {
|
|
23
|
+
/** Absolute, resolved against the repository root. */
|
|
24
|
+
path: string;
|
|
25
|
+
/** False for an option's value (`--x=v`, the word after `--x`, `-xv`): data the gate reads. */
|
|
26
|
+
positional: boolean;
|
|
27
|
+
/** The args entry as written, for the refusal message. */
|
|
28
|
+
entry: string;
|
|
29
|
+
}
|
|
21
30
|
export interface ResolvedBinary {
|
|
22
31
|
/** What to spawn. */
|
|
23
32
|
command: string;
|
|
@@ -34,6 +43,38 @@ export interface ResolvedBinary {
|
|
|
34
43
|
program: string;
|
|
35
44
|
/** Arguments placed before the ones the umbrella adds. */
|
|
36
45
|
argvPrefix: string[];
|
|
46
|
+
/**
|
|
47
|
+
* Every file or directory the policy's own `args:` names on disk, as an
|
|
48
|
+
* absolute path, with every loadable sibling of each (`argumentCandidates`),
|
|
49
|
+
* in args order. Empty when the policy has no `args:`.
|
|
50
|
+
*
|
|
51
|
+
* Carried because an interpreter `command:` hands the program to run as an
|
|
52
|
+
* ARGUMENT: with `command: /usr/bin/node` and `args: [tools/gate/run.mjs]`
|
|
53
|
+
* the script is what judges, not Node, and the pull-request provenance check
|
|
54
|
+
* has to vet it the way it vets `program` (audit 2026-10-27, B1). Only the
|
|
55
|
+
* policy's args, never a candidate's built-in prefix (`scan`, `source`):
|
|
56
|
+
* those are subcommands this package wrote, and a directory of the same
|
|
57
|
+
* name in somebody's repository is not a program.
|
|
58
|
+
*
|
|
59
|
+
* When `command:` is the gate itself (commandIsGateProgram) only the args
|
|
60
|
+
* entries with a code extension are listed here (`codeArguments`); the
|
|
61
|
+
* rest of its args are its own argv, read as data, and land in
|
|
62
|
+
* `dataArguments` instead.
|
|
63
|
+
*/
|
|
64
|
+
argumentPaths: string[];
|
|
65
|
+
/**
|
|
66
|
+
* Every args entry that could name a path, when `command:` is the gate
|
|
67
|
+
* itself (`dataArgumentPaths`), in args order, by POSITION and never by
|
|
68
|
+
* what the head's disk holds. Empty for every other command, and when
|
|
69
|
+
* resolution found the gate.
|
|
70
|
+
*
|
|
71
|
+
* The pull-request check (refuseHeadControlledData) decides from the BASE
|
|
72
|
+
* tree what each one is: a file must be the base's blob, a directory given
|
|
73
|
+
* as an option's value must be the base's tree, and a positional directory
|
|
74
|
+
* is a scan target and is not compared (audit 2026-10-28, N1, and its
|
|
75
|
+
* review, B1 and N-a).
|
|
76
|
+
*/
|
|
77
|
+
dataArguments: DataArgument[];
|
|
37
78
|
source: ResolutionSource;
|
|
38
79
|
/** The candidate name this matched, for the report's gate header. */
|
|
39
80
|
candidate: string;
|
|
@@ -89,3 +130,93 @@ export declare function nodeModulesCandidate(gate: GatePolicy, repoRoot: string)
|
|
|
89
130
|
export declare function resolveGateBinary(gate: GatePolicy, repoRoot: string, pathValue: string, options?: ResolveOptions): ResolvedBinary | null;
|
|
90
131
|
/** Every name resolution would try, for the missing-gate finding's message. */
|
|
91
132
|
export declare function candidateNames(product: Product): string[];
|
|
133
|
+
/**
|
|
134
|
+
* Whether the policy's `command:` is itself the gate program, so its `args:`
|
|
135
|
+
* are that gate's own argv rather than something an interpreter will load.
|
|
136
|
+
*
|
|
137
|
+
* True only when the command's NAME is a candidate name (`vault-guard`,
|
|
138
|
+
* `intent-guard.js`, executable or not). False for anything else: an
|
|
139
|
+
* interpreter such as `node` or `python3`, a renamed gate binary, and any
|
|
140
|
+
* wrapper or dispatcher whose name is not a gate name, a non-executable
|
|
141
|
+
* `my-build.js` included. Only when true are the product's subcommand words
|
|
142
|
+
* (`scan`, `source`) exempt from being read as paths, and the args read as
|
|
143
|
+
* the gate's own data rather than as code (`dataArgumentPaths`): an
|
|
144
|
+
* interpreter handed `scan` runs `scan.js` or `scan/index.js`, so for it the
|
|
145
|
+
* word is a path like any other (audit 2026-10-27 fix round, MB3).
|
|
146
|
+
*
|
|
147
|
+
* The name is the only test. An earlier version also counted every
|
|
148
|
+
* non-executable `.js` command, because this package runs one through its own
|
|
149
|
+
* Node with the script as the program; but how a file is RUN says nothing
|
|
150
|
+
* about what it LOADS, and a dispatcher that requires the script its first
|
|
151
|
+
* argument names let a pull request rewrite `scan.js` and pass (audit
|
|
152
|
+
* 2026-10-28, MB1).
|
|
153
|
+
*/
|
|
154
|
+
export declare function commandIsGateProgram(gate: GatePolicy): boolean;
|
|
155
|
+
/**
|
|
156
|
+
* Every path an interpreter could load for one `args:` entry, as absolute
|
|
157
|
+
* paths, in the order checked; empty when the entry names nothing on disk
|
|
158
|
+
* (audit 2026-10-27, B1, and its fix round).
|
|
159
|
+
*
|
|
160
|
+
* Relative entries are resolved against `repoRoot`. That is the working
|
|
161
|
+
* directory of the version probe and of the gate's own spawn for every
|
|
162
|
+
* product except one whose base config can name further files
|
|
163
|
+
* (`followsConfigExtend`): on a pull request that gate runs from a temporary
|
|
164
|
+
* directory holding the base ref's copies (src/gate-runner.ts, spawnCwd), so
|
|
165
|
+
* a relative script there resolves against base copies or not at all, never
|
|
166
|
+
* against the head tree. The rules, in order:
|
|
167
|
+
*
|
|
168
|
+
* - An option with no `=` (`--json`, `-r`) names nothing. An option with one
|
|
169
|
+
* (`--config=tools/cfg.json`, `--import=./hook.mjs`) is read for the value
|
|
170
|
+
* after the first `=`, since that is where an interpreter takes a file to
|
|
171
|
+
* load and a gate takes a file to read its rules from.
|
|
172
|
+
* - Nothing else is exempt, the product's own subcommand words (`scan`,
|
|
173
|
+
* `source`) included: this is only ever asked for a command that is not
|
|
174
|
+
* the gate itself (commandIsGateProgram), and an interpreter handed `scan`
|
|
175
|
+
* runs `scan.js` or `scan/index.js`. The gate itself has no code args;
|
|
176
|
+
* its args are data (dataArgumentPaths).
|
|
177
|
+
* - The entry as written, when it exists as a file, a directory or a
|
|
178
|
+
* symlink, without following the symlink, so the caller can refuse an
|
|
179
|
+
* in-tree link on its own entry.
|
|
180
|
+
* - Then every `<entry>.js`, `.mjs`, `.cjs`, `.json` and `.node` that exists,
|
|
181
|
+
* slash or not, and whether or not the entry itself exists: Node tries
|
|
182
|
+
* those before a directory of the same name, and a bare `run` runs
|
|
183
|
+
* `run.js`. A sibling the head ADDED is listed too, which is what refuses
|
|
184
|
+
* it: the base does not track it.
|
|
185
|
+
*
|
|
186
|
+
* A directory's contents are covered by the caller's tree comparison, so
|
|
187
|
+
* `index.js` and `package.json` inside it are not listed separately; a
|
|
188
|
+
* `main` that points outside the directory is not vetted, the same limit as
|
|
189
|
+
* a program's directory. Everything else, a Python `-m` module name, a bare
|
|
190
|
+
* package specifier an interpreter resolves for itself, code passed as a
|
|
191
|
+
* string (`node -e`, `bash -c`), is not recognised as a path. The README says
|
|
192
|
+
* so.
|
|
193
|
+
*/
|
|
194
|
+
export declare function argumentCandidates(arg: string, repoRoot: string): string[];
|
|
195
|
+
/**
|
|
196
|
+
* The args entries vetted as CODE: every entry when the command is not the
|
|
197
|
+
* gate itself, and only the code-extension values (`hasCodeExtension`) when
|
|
198
|
+
* it is. Each goes through `argumentCandidates`, here and in the preview.
|
|
199
|
+
*/
|
|
200
|
+
export declare function codeArguments(gate: GatePolicy): string[];
|
|
201
|
+
/**
|
|
202
|
+
* The args entries of a gate-named command that are its own DATA, when
|
|
203
|
+
* `command:` is the gate itself (commandIsGateProgram), in args order; empty
|
|
204
|
+
* for every other command (audit 2026-10-28, N1, and its review, B1, N-a,
|
|
205
|
+
* N-b, N-e).
|
|
206
|
+
*
|
|
207
|
+
* Every non-code entry (`gateArgEntries`, less the code-extension ones in
|
|
208
|
+
* `codeArguments`) is listed with its position, resolved against the
|
|
209
|
+
* repository root, WHETHER OR NOT the head's disk has it and whatever kind of
|
|
210
|
+
* thing the disk holds there: a head must not be able to delete a path or
|
|
211
|
+
* change it from a file to a directory to move it out of vetting. What each
|
|
212
|
+
* one is, and so which rule applies, is decided from the base tree by
|
|
213
|
+
* refuseHeadControlledData. No `<entry>.js` sibling is tried: that is how an
|
|
214
|
+
* interpreter resolves a name, and this command is not one.
|
|
215
|
+
*
|
|
216
|
+
* What this trusts is the NAME: a program named like a gate is taken to be
|
|
217
|
+
* that gate, except that a code-extension entry keeps the code rule. A
|
|
218
|
+
* wrapper given a gate's name that hands an extension-less entry to an
|
|
219
|
+
* interpreter is a wrapper, vetted no further than this (README,
|
|
220
|
+
* pull-request trust boundary).
|
|
221
|
+
*/
|
|
222
|
+
export declare function dataArgumentPaths(gate: GatePolicy, repoRoot: string): DataArgument[];
|