@vaultcompass/conductor 0.2.4 → 0.4.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.
@@ -0,0 +1,414 @@
1
+ // Pull-request mode for the umbrella: the policy comes from the base ref.
2
+ //
3
+ // The hole this closes is the umbrella's own, and it is the sharpest one in
4
+ // the family because the policy file can name a program to run. On a
5
+ // pull-request run the author controls every file in the tree being judged,
6
+ // `.guardrails.yaml` included, so one commit could point a gate's `command:`
7
+ // at a script the same commit added, or set `enabled: false` on the gate
8
+ // that would have caught what else is in it, and the report would say the
9
+ // run was clean. The gate ran. It just ran the pull request's own program,
10
+ // under the pull request's own rules.
11
+ //
12
+ // The fix is not a heuristic about which policy edits look suspicious. It is
13
+ // base versus head, and it is plain git: with `--trust-base <ref>` the
14
+ // umbrella reads its policy from that ref and judges the head tree. A policy
15
+ // difference never takes effect for the run, and the report says it was
16
+ // proposed. Outside pull-request mode nothing changes, because a pre-commit
17
+ // hook and a direct run on your own checkout are already inside the trust
18
+ // boundary.
19
+ //
20
+ // Three rules hold this file together, and all three are intent-guard's,
21
+ // mirrored on purpose so the two gates cannot disagree about what a trust
22
+ // base is:
23
+ //
24
+ // - READS ONLY, AND NEVER INTO THE REPOSITORY. `git rev-parse` and
25
+ // `git show`, both of which only read. No checkout switch, no worktree, no
26
+ // stash, no write of any kind. An umbrella that moved somebody's HEAD to
27
+ // do its job would be a worse bug than the one it fixes.
28
+ //
29
+ // - FAIL CLOSED ON THE REF. A ref that will not resolve is could-not-run for
30
+ // every enabled gate. It is never a reason to fall back to the head,
31
+ // because falling back to the head is exactly the behaviour being removed,
32
+ // and it would be reachable by anyone who could make the base ref
33
+ // unfetchable.
34
+ //
35
+ // - THE BASE MUST NOT BE THE HEAD, by commit AND by tree. A trust base that
36
+ // resolves to the head commit puts the boundary back where it started
37
+ // while still reporting as on, and two different commits can carry one
38
+ // identical tree, which has the same effect and passes a commit
39
+ // comparison. Both are real misconfigurations rather than curiosities:
40
+ // on a pull_request event `github.sha` IS the merge commit, and what
41
+ // GitHub publishes as the merge ref carries the head branch's tree
42
+ // whenever the base has not moved since the fork.
43
+ import { spawnSync } from 'node:child_process';
44
+ import { realpathSync } from 'node:fs';
45
+ import path from 'node:path';
46
+ import { parse as parseYaml } from 'yaml';
47
+ import { POLICY_FILE_NAME } from './policy.js';
48
+ /**
49
+ * What a rev resolves to at this repository, or null when it does not.
50
+ *
51
+ * `--quiet` suppresses git's own explanation, so there is nothing worth
52
+ * forwarding on failure: the caller writes a sentence a reader can act on
53
+ * rather than repeating the command line that failed.
54
+ */
55
+ function resolveRev(repoRoot, rev, kind) {
56
+ const child = spawnSync('git', ['rev-parse', '--verify', '--quiet', `${rev}^{${kind}}`], {
57
+ cwd: repoRoot,
58
+ encoding: 'utf8',
59
+ });
60
+ if (child.error !== undefined || child.status !== 0) {
61
+ return null;
62
+ }
63
+ const value = (child.stdout ?? '').trim();
64
+ return value === '' ? null : value;
65
+ }
66
+ /**
67
+ * Why this ref cannot be a trust base, or null when it can.
68
+ *
69
+ * A string rather than a thrown error, because the caller does not print it
70
+ * and stop: every enabled gate becomes could-not-run carrying this sentence,
71
+ * so the report names the gates that did not run rather than only the ref
72
+ * that was wrong.
73
+ *
74
+ * The four sentences mirror intent-guard's own refusals, which the umbrella
75
+ * would otherwise meet second-hand as a child's exit 2. Refusing here means
76
+ * the umbrella never spawns a child at all on a base it has already decided
77
+ * it cannot judge against, and it means the two gates give a user the same
78
+ * answer to the same mistake.
79
+ */
80
+ export function refuseTrustBaseRef(repoRoot, ref) {
81
+ const base = resolveRev(repoRoot, ref, 'commit');
82
+ if (base === null) {
83
+ return (`cannot read the policy from base ref "${ref}": it does not resolve to a commit in ` +
84
+ 'this repository. Nothing was checked. In CI, fetch the base branch (actions/checkout ' +
85
+ 'with fetch-depth: 0) before running the gates.');
86
+ }
87
+ const head = resolveRev(repoRoot, 'HEAD', 'commit');
88
+ if (head === null) {
89
+ return (`cannot resolve HEAD to compare against base ref "${ref}": this is not a repository ` +
90
+ 'with any commits. Pull-request mode needs both a base commit and a head commit. ' +
91
+ 'Nothing was checked.');
92
+ }
93
+ if (base === head) {
94
+ return (`refusing "${ref}" as the trust base: it resolves to ${head}, the same commit as HEAD, ` +
95
+ 'so the policy would come from the tree being judged and pull-request mode would be off ' +
96
+ 'while still reporting as on. Pass the base branch (for example origin/main), not the ' +
97
+ 'head commit: on a pull_request event github.sha is the merge commit, which is HEAD. ' +
98
+ 'Nothing was checked.');
99
+ }
100
+ const baseTree = resolveRev(repoRoot, ref, 'tree');
101
+ const headTree = resolveRev(repoRoot, 'HEAD', 'tree');
102
+ if (baseTree !== null && headTree !== null && baseTree === headTree) {
103
+ return (`refusing "${ref}" as the trust base: it is a different commit from HEAD but carries an ` +
104
+ `identical tree (${headTree}), so the policy would come from the tree being judged and ` +
105
+ 'there would be nothing for pull-request mode to compare. A pull request merge ref looks ' +
106
+ 'exactly like this when the base has not moved. Pass the base branch (for example ' +
107
+ 'origin/main), not the head or merge commit. Nothing was checked.');
108
+ }
109
+ return null;
110
+ }
111
+ /**
112
+ * The policy file's contents at a ref, or null when that ref carries none.
113
+ *
114
+ * `git show`, never a checkout switch and never a read from the working
115
+ * tree. The `./` is load-bearing for the same reason it is in intent-guard:
116
+ * it makes git resolve the path relative to the working directory, which is
117
+ * the repository root here, rather than to wherever the repository root would
118
+ * be from somewhere else.
119
+ */
120
+ export function readPolicyAtRef(repoRoot, ref) {
121
+ const child = spawnSync('git', ['show', `${ref}:./${POLICY_FILE_NAME}`], {
122
+ cwd: repoRoot,
123
+ encoding: 'utf8',
124
+ maxBuffer: 32 * 1024 * 1024,
125
+ });
126
+ if (child.error !== undefined || child.status !== 0) {
127
+ return null;
128
+ }
129
+ return child.stdout ?? '';
130
+ }
131
+ /**
132
+ * Whether two policy files differ in what they SAY.
133
+ *
134
+ * Compared as parsed documents rather than as bytes, so a reflowed list, a
135
+ * changed quote style or an edited comment is not reported as a proposal to
136
+ * change the rules; a report that cries wolf on whitespace is a report
137
+ * reviewers learn to skip. When either side will not parse, the raw text is
138
+ * compared instead, which is the fail-closed direction: an unparseable head
139
+ * policy is reported as a change rather than quietly matching.
140
+ *
141
+ * BOTH SIDES COME FROM `git show`, base and head alike, and that is not an
142
+ * accident of implementation. intent-guard read its head side from the
143
+ * working tree with a call that follows symlinks, so a pull request that
144
+ * replaced a control file with a link compared equal to the base and was
145
+ * reported as changing nothing. One reader for both sides is the only way the
146
+ * two can be compared on equal terms, and it also means an uncommitted local
147
+ * edit is not reported as something the pull request proposes.
148
+ */
149
+ export function policyDiffers(base, head) {
150
+ if (base === null && head === null) {
151
+ return false;
152
+ }
153
+ if (base === null || head === null) {
154
+ return true;
155
+ }
156
+ try {
157
+ return JSON.stringify(parseYaml(base) ?? null) !== JSON.stringify(parseYaml(head) ?? null);
158
+ }
159
+ catch {
160
+ return base !== head;
161
+ }
162
+ }
163
+ /** The one line the report prints when the head proposes a different policy. */
164
+ export const POLICY_PROPOSAL_LINE = 'policy changed in this pull request';
165
+ /**
166
+ * One path's tree entry at a ref, or null when the ref has no such path.
167
+ *
168
+ * `ls-tree` rather than `git show`, because the BLOB ID is the thing being
169
+ * compared and `show` prints contents without telling you what kind of entry
170
+ * produced them. The mode comes with it, so a regular file can be told from a
171
+ * symlink, a submodule or a directory in the same read.
172
+ */
173
+ export function treeEntryAt(repoRoot, ref, relativePath) {
174
+ const child = spawnSync('git', ['ls-tree', ref, '--', `./${relativePath}`], {
175
+ cwd: repoRoot,
176
+ encoding: 'utf8',
177
+ });
178
+ if (child.error !== undefined || child.status !== 0) {
179
+ return null;
180
+ }
181
+ const line = (child.stdout ?? '').split('\n').find((entry) => entry.trim().length > 0);
182
+ if (line === undefined) {
183
+ return null;
184
+ }
185
+ const [mode, type, sha] = line.split(/\s+/);
186
+ if (mode === undefined || type === undefined || sha === undefined) {
187
+ return null;
188
+ }
189
+ return { mode, type, sha };
190
+ }
191
+ /** The two modes that mean an ordinary file git will hand back. */
192
+ function isRegularFileMode(mode) {
193
+ return mode === '100644' || mode === '100755';
194
+ }
195
+ /**
196
+ * The working-tree root, resolved through symlinks, or null.
197
+ *
198
+ * realpath on BOTH sides of every comparison below. On macOS the temporary
199
+ * directory is reached through a symlink, so one repository root has two
200
+ * spellings, one of them with an extra leading segment, and a prefix test on
201
+ * the raw strings answers "outside" for a file that is plainly inside.
202
+ */
203
+ function realOrNull(candidate) {
204
+ try {
205
+ return realpathSync(candidate);
206
+ }
207
+ catch {
208
+ return null;
209
+ }
210
+ }
211
+ /** Whether `candidate` is the working tree or something under it. */
212
+ function insideWorkingTree(repoReal, candidate) {
213
+ const relative = path.relative(repoReal, candidate);
214
+ return relative !== '' && !relative.startsWith('..') && !path.isAbsolute(relative);
215
+ }
216
+ /**
217
+ * A path with its PARENT resolved through symlinks but its own last component
218
+ * left alone.
219
+ *
220
+ * Resolving the whole path would follow the program's own symlink, which is a
221
+ * different question and is asked separately below. Resolving nothing at all
222
+ * was a bug: the repository root arrives here realpath'd, so on a machine
223
+ * where the working tree sits under a symlinked mount (a macOS temporary
224
+ * directory, for one) the unresolved spelling of a file plainly inside the
225
+ * tree compares as OUTSIDE it, and the entry was quietly skipped. Only the
226
+ * link's target was then vetted, and the link's own entry never was.
227
+ */
228
+ function withResolvedParent(candidate) {
229
+ const parent = path.dirname(candidate);
230
+ return path.join(realOrNull(parent) ?? parent, path.basename(candidate));
231
+ }
232
+ /**
233
+ * The tree object id of one directory at a ref, or null.
234
+ *
235
+ * The repository root is its own case: it has no containing directory, so the
236
+ * comparison is the whole root tree, which `rev-parse` gives directly.
237
+ */
238
+ function treeShaAt(repoRoot, ref, relativeDir) {
239
+ if (relativeDir === '' || relativeDir === '.') {
240
+ return resolveRev(repoRoot, ref, 'tree');
241
+ }
242
+ const entry = treeEntryAt(repoRoot, ref, relativeDir);
243
+ return entry === null || entry.type !== 'tree' ? null : entry.sha;
244
+ }
245
+ /**
246
+ * Why this gate's PROGRAM cannot be trusted on a pull-request run, or null.
247
+ *
248
+ * Reading the rules from the base ref is worth nothing if the pull request
249
+ * chooses the program that applies them, and it can, three ways that all look
250
+ * ordinary in a diff:
251
+ *
252
+ * - A base policy whose `command:` points INSIDE the repository, at
253
+ * something like `vendor/vault-guard`. The path came from the base and is
254
+ * therefore approved; the FILE AT THAT PATH is whatever the head commit
255
+ * put there. The umbrella then runs the pull request's own program, is
256
+ * told the scan was clean, and reports a clean scan.
257
+ *
258
+ * - No `command:` at all. Resolution prefers the repository's own
259
+ * `node_modules/.bin` over PATH, deliberately, so that a project pin beats
260
+ * a global install. A head that commits `node_modules/.bin/vault-guard`
261
+ * shadows the real gate, and a stub that answers `--version` with a
262
+ * plausible number passes every check the umbrella makes. The composite
263
+ * action installs nothing, so the plant survives an install step.
264
+ *
265
+ * - A base-approved WRAPPER. `vendor/vault-guard` is byte for byte what the
266
+ * base approved and is the path the policy names; it execs
267
+ * `vendor/impl.sh`, which the head rewrote. Nothing in the diff touches
268
+ * the path the policy names, so a per-file check waves it through. This
269
+ * one was found by a reviewer after the first two were closed, and it is
270
+ * why the unit of approval is a directory rather than a file.
271
+ *
272
+ * THE RULE. A program is acceptable when it is outside the working tree
273
+ * entirely: on PATH, or an absolute `command:` somewhere else on the machine.
274
+ * A pull request cannot write those. A program INSIDE the working tree is
275
+ * acceptable only when BOTH hold: it is a tracked regular file whose blob is
276
+ * IDENTICAL at the trust base and at HEAD, AND the tree object id of its
277
+ * CONTAINING DIRECTORY is identical at those two refs. The first is the same
278
+ * base-versus-head test the rules themselves get, applied to the thing that
279
+ * enforces them; the second extends it to everything beside the program,
280
+ * which is what the wrapper shape needs and what a per-file test cannot give.
281
+ *
282
+ * A tree object id covers a whole subtree in one comparison, so this needs no
283
+ * knowledge of what a wrapper calls. WHAT IS VETTED IS THE PROGRAM FILE AND
284
+ * ITS DIRECTORY SUBTREE AND NOTHING ELSE: anything the program reaches
285
+ * outside that directory is not vetted, so an in-repo gate has to be
286
+ * self-contained within its own directory. That limit is stated in the README
287
+ * in those words, because an adopter has to be able to satisfy it.
288
+ *
289
+ * A PROGRAM AT THE REPOSITORY ROOT IS REFUSED. There the containing directory
290
+ * is the whole repository, so the comparison is the root tree and every pull
291
+ * request that changed anything differs, which is every pull request.
292
+ * Refusing with the remedy in the message beats a rule that silently means
293
+ * "no pull request may change anything".
294
+ *
295
+ * NOTHING HERE READS THE WORKING TREE. Both sides come from `git ls-tree`, so
296
+ * an uncommitted local edit cannot make a file look approved and a tracked
297
+ * file cannot be vouched for by a copy on disk that git has never seen.
298
+ *
299
+ * NODE_MODULES IS NEVER BASE-APPROVED, and the reason is worth stating
300
+ * because "but the lockfile is committed" is the obvious objection. What is
301
+ * under `node_modules` is chosen by the head's own manifest and lockfile and
302
+ * installed by a step that runs before this one; git has no record of those
303
+ * bytes at either ref, so `ls-tree` finds nothing and the rule refuses. That
304
+ * is the correct answer rather than a limitation: a pull request that edits
305
+ * its lockfile to pull a different build of a gate has chosen its own judge
306
+ * just as surely as one that commits a stub.
307
+ *
308
+ * BOTH THE PROGRAM'S OWN PATH AND ITS REALPATH ARE VETTED, because a
309
+ * head-committed symlink is a choice of program too. An in-repo symlink is
310
+ * refused on its OWN entry, before its target matters: it is either untracked
311
+ * or its tree entry is a link rather than a regular file, and either refuses.
312
+ * Vetting the target is what catches a link whose own path is outside the
313
+ * tree pointing into it; it never decides the in-repo case.
314
+ */
315
+ export function refuseHeadControlledProgram(repoRoot, trustBase, programPath) {
316
+ const repoReal = realOrNull(repoRoot);
317
+ if (repoReal === null) {
318
+ return `the repository root ${repoRoot} could not be resolved, so the gate program could not be checked against "${trustBase}". Nothing was checked by this gate.`;
319
+ }
320
+ const candidates = new Set();
321
+ for (const candidate of [withResolvedParent(programPath), realOrNull(programPath)]) {
322
+ if (candidate !== null && insideWorkingTree(repoReal, candidate)) {
323
+ candidates.add(candidate);
324
+ }
325
+ }
326
+ if (candidates.size === 0) {
327
+ // Outside the working tree: on PATH, or an absolute path elsewhere on the
328
+ // machine. A pull request cannot write either.
329
+ return null;
330
+ }
331
+ for (const candidate of candidates) {
332
+ const relative = path.relative(repoReal, candidate).split(path.sep).join('/');
333
+ const base = treeEntryAt(repoRoot, trustBase, relative);
334
+ const head = treeEntryAt(repoRoot, 'HEAD', relative);
335
+ if (base === null || head === null) {
336
+ return (`the ${trustBase === '' ? 'base' : `"${trustBase}"`} ref does not track the gate program ` +
337
+ `at ${relative}, so it is a file this pull request controls and running it would let the ` +
338
+ 'pull request choose the program that judges it. Nothing under node_modules is ever ' +
339
+ 'base-approved: what is there is chosen by the head own manifest and lockfile, and git ' +
340
+ 'has no record of those bytes at either ref. Install the gate on PATH, or point ' +
341
+ 'command: at a path outside the repository. Nothing was checked by this gate.');
342
+ }
343
+ if (!isRegularFileMode(base.mode) || !isRegularFileMode(head.mode)) {
344
+ return (`the gate program at ${relative} is not a regular file at both "${trustBase}" and the ` +
345
+ 'head commit, so what would actually run is decided by something other than the ' +
346
+ 'approved bytes. Nothing was checked by this gate.');
347
+ }
348
+ if (base.sha !== head.sha) {
349
+ return (`the gate program at ${relative} is not the one "${trustBase}" approved: this pull ` +
350
+ 'request changes it, so running it would let the pull request choose the program that ' +
351
+ 'judges it. Land the change on the base branch first. Nothing was checked by this gate.');
352
+ }
353
+ // AND THE DIRECTORY AROUND IT. The file check alone is defeated by a
354
+ // wrapper: `vendor/vault-guard` execs `vendor/impl.sh`, the pull request
355
+ // leaves the wrapper byte for byte alone and rewrites the helper beside
356
+ // it, and nothing in the diff touches the path the policy names. So the
357
+ // unit of approval is the program's DIRECTORY SUBTREE, compared as one
358
+ // tree object id, which covers every file under it at once without this
359
+ // package having to know what a wrapper calls.
360
+ const directory = path.posix.dirname(relative);
361
+ const baseTree = treeShaAt(repoRoot, trustBase, directory);
362
+ const headTree = treeShaAt(repoRoot, 'HEAD', directory);
363
+ if (baseTree === null || headTree === null || baseTree !== headTree) {
364
+ if (directory === '' || directory === '.') {
365
+ // At the root the containing directory IS the whole repository, so
366
+ // this compares root trees and any pull request that changed anything
367
+ // differs, which is every pull request. Refusing with the remedy
368
+ // beats a rule that silently means "no pull request may change
369
+ // anything".
370
+ return (`the gate program at ${relative} is at the repository root, so the directory that ` +
371
+ 'would have to be unchanged for it to be trusted is the whole repository, and this ' +
372
+ `pull request differs from "${trustBase}" somewhere in it. Move a vendored gate into ` +
373
+ 'its own directory, or install it on PATH. Nothing was checked by this gate.');
374
+ }
375
+ return (`a file beside the gate program in ${directory} is not what "${trustBase}" approved: the ` +
376
+ `program at ${relative} is unchanged, but the directory around it is not, and a gate is ` +
377
+ 'rarely one file. A wrapper that execs a helper beside it runs whatever this pull ' +
378
+ 'request put there. Land the change on the base branch first, or install the gate on ' +
379
+ 'PATH. Nothing was checked by this gate.');
380
+ }
381
+ }
382
+ return null;
383
+ }
384
+ /**
385
+ * Whether a gate's reported version is at least `minimum`.
386
+ *
387
+ * Numeric per component, not a string comparison, or "1.10.0" would sort
388
+ * below "1.4.0". A version that cannot be read at all answers FALSE, which is
389
+ * the safe direction for the one thing this decides: whether to hand a child
390
+ * a flag an older build of it would reject outright. A gate that refused an
391
+ * unknown flag would exit non-zero with no JSON, which the umbrella reports
392
+ * as could-not-run, so guessing high turns a working run into a broken one
393
+ * for every repository pinning an older gate.
394
+ */
395
+ export function atLeastVersion(version, minimum) {
396
+ if (version === null) {
397
+ return false;
398
+ }
399
+ const parse = (value) => {
400
+ const match = /^v?(\d+)\.(\d+)\.(\d+)/.exec(value.trim());
401
+ return match === null ? [] : [Number(match[1]), Number(match[2]), Number(match[3])];
402
+ };
403
+ const actual = parse(version);
404
+ const wanted = parse(minimum);
405
+ if (actual.length !== 3 || wanted.length !== 3) {
406
+ return false;
407
+ }
408
+ for (let index = 0; index < 3; index += 1) {
409
+ if (actual[index] !== wanted[index]) {
410
+ return actual[index] > wanted[index];
411
+ }
412
+ }
413
+ return true;
414
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@vaultcompass/conductor",
3
- "version": "0.2.4",
3
+ "version": "0.4.0",
4
4
  "type": "module",
5
5
  "description": "Umbrella installer and combined report over the independently installable guardrail gates.",
6
6
  "license": "MIT",