@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.
- package/README.md +200 -48
- package/dist/cli.js +96 -16
- package/dist/external-config.js +7 -1
- package/dist/gate-runner.d.ts +9 -1
- package/dist/gate-runner.js +49 -5
- package/dist/init-policy.js +2 -1
- package/dist/intent-base.d.ts +29 -0
- package/dist/intent-base.js +96 -2
- package/dist/intent-prepare.js +6 -2
- package/dist/normalize.d.ts +9 -0
- package/dist/normalize.js +13 -1
- package/dist/output-text.d.ts +35 -0
- package/dist/output-text.js +89 -2
- package/dist/products.js +1 -1
- package/dist/trust-base.d.ts +57 -10
- package/dist/trust-base.js +194 -18
- package/package.json +1 -1
package/dist/trust-base.js
CHANGED
|
@@ -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
|
-
|
|
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
|
|
215
|
-
*
|
|
216
|
-
*
|
|
217
|
-
*
|
|
218
|
-
*
|
|
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
|
|
227
|
-
*
|
|
228
|
-
*
|
|
229
|
-
* fetch-depth: 0, and a checkout
|
|
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
|
|
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
|
-
|
|
249
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
});
|