@vaultcompass/conductor 0.6.0 → 0.8.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.
@@ -69,6 +69,93 @@ import { realpathSync } from 'node:fs';
69
69
  import path from 'node:path';
70
70
  import { parse as parseYaml } from 'yaml';
71
71
  import { POLICY_FILE_NAME } from './policy.js';
72
+ /**
73
+ * The private, fully spelled ref the composite action fetches the base branch
74
+ * into (action.yml, gates step). Nothing else writes it and no short name can
75
+ * shadow it: git resolves a short name like origin/main through refs/tags/
76
+ * BEFORE refs/remotes/, so a tag pushed by anyone able to push tags would
77
+ * otherwise choose the commit the rules are read from.
78
+ */
79
+ export const PRIVATE_TRUST_BASE_REF = 'refs/conductor/trust-base';
80
+ function refExists(repoRoot, fullRef) {
81
+ const child = spawnSync('git', ['show-ref', '--verify', '--quiet', fullRef], {
82
+ cwd: repoRoot,
83
+ encoding: 'utf8',
84
+ });
85
+ return child.error === undefined && child.status === 0;
86
+ }
87
+ /**
88
+ * The object id a fully spelled ref EXACTLY names, or null when there is no
89
+ * such ref. `show-ref --verify` looks at that ref and nothing else: it does
90
+ * not run git's name-resolution rules, so a tag stored as
91
+ * refs/tags/refs/conductor/trust-base is never taken for
92
+ * refs/conductor/trust-base.
93
+ */
94
+ export function exactRefObject(repoRoot, fullRef) {
95
+ const child = spawnSync('git', ['show-ref', '--verify', '--hash', fullRef], {
96
+ cwd: repoRoot,
97
+ encoding: 'utf8',
98
+ });
99
+ if (child.error !== undefined || child.status !== 0) {
100
+ return null;
101
+ }
102
+ const value = (child.stdout ?? '').trim();
103
+ return /^[0-9a-f]{40}([0-9a-f]{24})?$/.test(value) ? value : null;
104
+ }
105
+ /**
106
+ * A caller-given trust base that starts with "-", or null. Git allows a tag
107
+ * named refs/tags/--output=x, and such a name handed to git as an argument is
108
+ * read as an option, not a revision. Refused before any git call sees it; the
109
+ * git calls below also pass --end-of-options as a second line of defence.
110
+ */
111
+ export function refuseDashLeadingRef(ref) {
112
+ if (!ref.startsWith('-')) {
113
+ return null;
114
+ }
115
+ return (`refusing "${ref}" as the trust base: it starts with "-", which git would read as an ` +
116
+ 'option rather than a revision. Pass a ref name or a full commit id. Nothing was checked.');
117
+ }
118
+ /** A full 40- or 64-hex object id: never subject to ref name resolution. */
119
+ export function isFullObjectId(value) {
120
+ return /^([0-9a-f]{40}|[0-9a-f]{64})$/i.test(value);
121
+ }
122
+ /**
123
+ * Why a SHORT ref name cannot be trusted as spelled, or null.
124
+ *
125
+ * A name that matches more than one kind of ref (a tag and a remote-tracking
126
+ * ref or a branch) is resolved by git in its own precedence order, tags
127
+ * first, with no warning under --quiet. That is a choice made by whoever can
128
+ * create the tag, so it is refused rather than resolved. A ref already spelled
129
+ * from refs/ is unambiguous, and revision expressions (HEAD, HEAD~1, a sha) are
130
+ * not names and are left to the callers' own checks.
131
+ */
132
+ export function refuseAmbiguousRef(repoRoot, ref,
133
+ /** What the ref is used as, for the message: "the trust base", "the intent base". */
134
+ noun = 'the trust base') {
135
+ // The NAME part only: origin/main~0, origin/main^{commit} and origin/main@{0}
136
+ // resolve through the same tag-first rules as origin/main, so a revision
137
+ // suffix is cut off (from the first ~ ^ : or @{) before the check. A bare @
138
+ // is HEAD and is NOT a cut: a name may carry a literal @ (a branch and a tag
139
+ // both named feature@x, where git picks the tag), and cutting there hid it.
140
+ const cut = ref.search(/[~^:]|@\{/);
141
+ const name = cut === -1 ? ref : ref.slice(0, cut);
142
+ if (name === '' ||
143
+ name === 'HEAD' ||
144
+ name === '@' ||
145
+ name.startsWith('refs/') ||
146
+ /[\s{}\\]/.test(name) ||
147
+ isFullObjectId(name)) {
148
+ return null;
149
+ }
150
+ const matches = [`refs/tags/${name}`, `refs/heads/${name}`, `refs/remotes/${name}`].filter((full) => refExists(repoRoot, full));
151
+ if (matches.length <= 1) {
152
+ return null;
153
+ }
154
+ return (`refusing "${ref}" as ${noun}: the name "${name}" is ambiguous, it matches ${matches.join(' and ')}, ` +
155
+ 'and git would pick one of them by its own precedence (tags first). Whoever can push a tag ' +
156
+ 'could choose the base this way. Pass the ref spelled in full, for example ' +
157
+ 'refs/remotes/origin/main. Nothing was checked.');
158
+ }
72
159
  /**
73
160
  * What a rev resolves to at this repository, or null when it does not.
74
161
  *
@@ -76,8 +163,21 @@ import { POLICY_FILE_NAME } from './policy.js';
76
163
  * forwarding on failure: the caller writes a sentence a reader can act on
77
164
  * rather than repeating the command line that failed.
78
165
  */
79
- function resolveRev(repoRoot, rev, kind) {
80
- const child = spawnSync('git', ['rev-parse', '--verify', '--quiet', `${rev}^{${kind}}`], {
166
+ export function resolveRev(repoRoot, rev, kind) {
167
+ // A refs/ name is NEVER handed to git's name resolution: rev-parse would
168
+ // try refs/tags/<name> when the ref itself is absent, so a pushed tag named
169
+ // refs/conductor/trust-base would stand in for the private ref. The exact
170
+ // ref is read with show-ref and its object id is what gets resolved (a full
171
+ // object id is not subject to name resolution).
172
+ let target = rev;
173
+ if (rev.startsWith('refs/')) {
174
+ const exact = exactRefObject(repoRoot, rev);
175
+ if (exact === null) {
176
+ return null;
177
+ }
178
+ target = exact;
179
+ }
180
+ const child = spawnSync('git', ['rev-parse', '--verify', '--quiet', '--end-of-options', `${target}^{${kind}}`], {
81
181
  cwd: repoRoot,
82
182
  encoding: 'utf8',
83
183
  });
@@ -150,6 +250,14 @@ export function headTreeEqualsBase(repoRoot, ref) {
150
250
  * learns the trees matched even on this accepted path.
151
251
  */
152
252
  export function refuseTrustBaseRef(repoRoot, ref) {
253
+ const dashed = refuseDashLeadingRef(ref);
254
+ if (dashed !== null) {
255
+ return dashed;
256
+ }
257
+ const ambiguous = refuseAmbiguousRef(repoRoot, ref);
258
+ if (ambiguous !== null) {
259
+ return ambiguous;
260
+ }
153
261
  const base = resolveRev(repoRoot, ref, 'commit');
154
262
  if (base === null) {
155
263
  return (`cannot read the policy from base ref "${ref}": it does not resolve to a commit in ` +
@@ -211,11 +319,12 @@ export function refuseTrustBaseRef(repoRoot, ref) {
211
319
  * NAME on a pull_request or pull_request_target event, and empty everywhere
212
320
  * else -- a push, a schedule, workflow_dispatch, merge_group, a local run, or
213
321
  * a platform that never sets it. When it is set, the given ref is accepted
214
- * only when it resolves to the SAME COMMIT as origin/<githubBaseRef>, which
215
- * is exactly what the composite action itself always passes
216
- * (`--trust-base "origin/$GITHUB_BASE_REF"` in action.yml's gates step). So
217
- * an ordinary pull-request run sees the given ref and the expected ref as the
218
- * identical spelling and this returns null immediately, before
322
+ * only when it is the FULL COMMIT ID the composite action's "Fetch the trust
323
+ * base" step published (which must equal refs/conductor/trust-base, the
324
+ * authority, or refs/remotes/origin/<githubBaseRef>, both read with show-ref),
325
+ * or is that private ref itself, or -- for an explicit trust base -- resolves
326
+ * to the same commit as refs/remotes/origin/<githubBaseRef>. So an ordinary
327
+ * pull-request run through the action returns null here, before
219
328
  * refuseTrustBaseRef's own checks -- HEAD, and the equal-tree exception from
220
329
  * issue #69/#73 -- ever run: this check is narrower than those and says
221
330
  * nothing about HEAD or about tree equality, only about whether the given ref
@@ -223,11 +332,11 @@ export function refuseTrustBaseRef(repoRoot, ref) {
223
332
  * request's own branch, or anything else that disagrees, is refused with both
224
333
  * refs and both commits named.
225
334
  *
226
- * FAILS CLOSED when origin/<githubBaseRef> itself does not resolve, naming
227
- * it: reachable on the default actions/checkout (fetch-depth: 1), which does
228
- * not carry the base branch at all. The README already asks for
229
- * fetch-depth: 0, and a checkout that does not carry the base branch is not a
230
- * reason to skip the comparison.
335
+ * FAILS CLOSED when neither the private ref nor refs/remotes/origin/
336
+ * <githubBaseRef> exists, naming them: reachable through the CLI on the
337
+ * default actions/checkout (fetch-depth: 1), which does not carry the base
338
+ * branch at all. The README already asks for fetch-depth: 0, and a checkout
339
+ * that does not carry the base branch is not a reason to skip the comparison.
231
340
  *
232
341
  * When the GIVEN ref does not resolve at all, this returns null rather than
233
342
  * refusing: refuseTrustBaseRef is the function with its own sentence for an
@@ -241,24 +350,85 @@ export function refuseTrustBaseForPullRequest(repoRoot, ref, githubBaseRef) {
241
350
  if (githubBaseRef === undefined || githubBaseRef === '') {
242
351
  return null;
243
352
  }
244
- const expectedRef = `origin/${githubBaseRef}`;
353
+ const dashed = refuseDashLeadingRef(ref);
354
+ if (dashed !== null) {
355
+ return dashed;
356
+ }
357
+ const ambiguous = refuseAmbiguousRef(repoRoot, ref);
358
+ if (ambiguous !== null) {
359
+ return ambiguous;
360
+ }
361
+ // SPELLED IN FULL, and read with show-ref (resolveRev does that for every
362
+ // refs/ name): a short origin/<base> would resolve through
363
+ // refs/tags/origin/<base> first, and a refs/ name through a tag of that
364
+ // name when the ref is absent.
365
+ const expectedRef = `refs/remotes/origin/${githubBaseRef}`;
245
366
  const expectedCommit = resolveRev(repoRoot, expectedRef, 'commit');
367
+ const privateCommit = resolveRev(repoRoot, PRIVATE_TRUST_BASE_REF, 'commit');
368
+ // THE ACTION PASSES A FULL COMMIT ID, never a ref name (a full object id is
369
+ // not subject to name resolution). It is accepted only when it IS the
370
+ // private ref's commit (the authority, fetched and verified by the action's
371
+ // fetch step) or, ONLY when the private ref does not exist, the commit of
372
+ // refs/remotes/origin/<base> (both read with show-ref).
373
+ if (isFullObjectId(ref)) {
374
+ const given = resolveRev(repoRoot, ref, 'commit');
375
+ if (given === null) {
376
+ return null;
377
+ }
378
+ // The private ref is the ONLY acceptable answer when it exists: pull-request
379
+ // code can move refs/remotes/origin/<base>, so an id that matches only that
380
+ // ref is the attack, not a second answer. The remote-tracking ref is the
381
+ // reference only when the private ref is absent.
382
+ if (privateCommit !== null ? given === privateCommit : given === expectedCommit) {
383
+ return null;
384
+ }
385
+ if (privateCommit === null && expectedCommit === null) {
386
+ return (`cannot verify "${ref}" as the trust base: neither ${PRIVATE_TRUST_BASE_REF} (the ` +
387
+ `composite action's fetch of the base branch) nor "${expectedRef}" exists in this ` +
388
+ 'repository, so there is nothing to compare it against. Nothing was checked. In CI, fetch ' +
389
+ 'the base branch (actions/checkout with fetch-depth: 0) before running the gates.');
390
+ }
391
+ return (`refusing "${ref}" as the trust base: GITHUB_BASE_REF is set to "${githubBaseRef}", so this ` +
392
+ 'run is a pull request, and on a pull request the trust base must be the base branch and ' +
393
+ `nothing else. It equals neither ${PRIVATE_TRUST_BASE_REF} (${privateCommit ?? 'absent'}) ` +
394
+ `nor ${expectedRef} (${expectedCommit ?? 'absent'}). Nothing was checked.`);
395
+ }
396
+ // THE PRIVATE REF IS THE AUTHORITY, and nothing reads
397
+ // refs/remotes/origin/<base> for trust. That ref is fixed at checkout time
398
+ // and is the side pull-request code can move, while the private ref is
399
+ // fetched later by the action: comparing them adds a false refusal whenever
400
+ // the base branch advances in between, and no protection. Only an explicit
401
+ // trust base (below) has the remote-tracking ref as its one reference.
402
+ if (ref === PRIVATE_TRUST_BASE_REF) {
403
+ if (privateCommit !== null) {
404
+ return null;
405
+ }
406
+ return (`refusing "${ref}" as the trust base: no such ref exists in this repository (a tag or ` +
407
+ 'branch of that name does not count: only the exact ref the action fetched does). The ' +
408
+ 'action\'s fetch of the base branch did not run or did not succeed. Nothing was checked.');
409
+ }
246
410
  if (expectedCommit === null) {
247
411
  return (`cannot verify "${ref}" as the trust base: "${expectedRef}" does not resolve to a commit ` +
248
- 'in this repository, so there is nothing to compare it against. Nothing was checked. In ' +
249
- 'CI, fetch the base branch (actions/checkout with fetch-depth: 0) before running the gates.');
412
+ `in this repository, so there is nothing to compare it against, and only ` +
413
+ `${PRIVATE_TRUST_BASE_REF} (fetched by the composite action) is accepted without it. ` +
414
+ 'Nothing was checked. In CI, fetch the base branch (actions/checkout with ' +
415
+ 'fetch-depth: 0) before running the gates.');
250
416
  }
251
417
  const givenCommit = resolveRev(repoRoot, ref, 'commit');
252
418
  if (givenCommit === null) {
253
419
  return null;
254
420
  }
421
+ // A NAMED explicit trust base may equal refs/remotes/origin/<base> even
422
+ // while the private ref exists: the full-id rule above applies to the
423
+ // action's own id, not to a name the caller typed.
255
424
  if (givenCommit === expectedCommit) {
256
425
  return null;
257
426
  }
258
427
  return (`refusing "${ref}" as the trust base: GITHUB_BASE_REF is set to "${githubBaseRef}", so this ` +
259
428
  'run is a pull request, and on a pull request the trust base must be the base branch and ' +
260
429
  `nothing else. "${ref}" resolves to ${givenCommit}, and "${expectedRef}" resolves to ` +
261
- `${expectedCommit}, a different commit. Pass ${expectedRef} instead. Nothing was checked.`);
430
+ `${expectedCommit}, a different commit: something moved one of them, so neither can be ` +
431
+ `trusted. Pass ${expectedRef} or ${PRIVATE_TRUST_BASE_REF} instead. Nothing was checked.`);
262
432
  }
263
433
  /**
264
434
  * The policy file's contents at a ref, or null when that ref carries none.
@@ -270,7 +440,10 @@ export function refuseTrustBaseForPullRequest(repoRoot, ref, githubBaseRef) {
270
440
  * be from somewhere else.
271
441
  */
272
442
  export function readPolicyAtRef(repoRoot, ref) {
273
- const child = spawnSync('git', ['show', `${ref}:./${POLICY_FILE_NAME}`], {
443
+ if (ref.startsWith('-')) {
444
+ return null;
445
+ }
446
+ const child = spawnSync('git', ['show', '--end-of-options', `${ref}:./${POLICY_FILE_NAME}`], {
274
447
  cwd: repoRoot,
275
448
  encoding: 'utf8',
276
449
  maxBuffer: 32 * 1024 * 1024,
@@ -323,7 +496,10 @@ export const POLICY_PROPOSAL_LINE = 'policy changed in this pull request';
323
496
  * symlink, a submodule or a directory in the same read.
324
497
  */
325
498
  export function treeEntryAt(repoRoot, ref, relativePath) {
326
- const child = spawnSync('git', ['ls-tree', ref, '--', `./${relativePath}`], {
499
+ if (ref.startsWith('-')) {
500
+ return null;
501
+ }
502
+ const child = spawnSync('git', ['ls-tree', '--end-of-options', ref, '--', `./${relativePath}`], {
327
503
  cwd: repoRoot,
328
504
  encoding: 'utf8',
329
505
  });
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@vaultcompass/conductor",
3
- "version": "0.6.0",
3
+ "version": "0.8.0",
4
4
  "type": "module",
5
5
  "description": "Umbrella installer and combined report over the independently installable guardrail gates.",
6
6
  "keywords": [