@vaultcompass/conductor 0.7.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 CHANGED
@@ -167,7 +167,7 @@ required.
167
167
  A commit with a staged credential in it prints the full report and exits 1:
168
168
 
169
169
  ```
170
- conductor 0.7.0
170
+ conductor 0.8.0
171
171
  verdict-token: blocked (1)
172
172
  conductor run: 2 gate(s), 1 finding(s)
173
173
 
@@ -473,7 +473,8 @@ proceeds normally without mentioning them.
473
473
  pull-request run passes both: `--base` decides which paths are judged,
474
474
  `--trust-base` decides what they are judged by. When `GITHUB_BASE_REF` is
475
475
  set, an explicit `--trust-base` is accepted only when it resolves to the
476
- same commit as `origin/$GITHUB_BASE_REF` (issue #58); anyone invoking the
476
+ same commit as `refs/remotes/origin/$GITHUB_BASE_REF`, or is the Action's
477
+ private `refs/conductor/trust-base` (issue #58); anyone invoking the
477
478
  CLI directly on a pull request, rather than through the Action, gets this
478
479
  as its own refusal, named below.
479
480
  - `--spec <path>` names the spec the intent gate imports its contract from.
@@ -571,6 +572,11 @@ code and the `enforce` flags the run already had.
571
572
 
572
573
  - `pass`: exit 0, and no gate, enforced or not, has a blocking finding or
573
574
  could not run.
575
+ - `nothing-checked`: exit 0, but no gate ran at all (none is enabled, or
576
+ every enabled one was deferred to a later stage, had nothing to judge, or
577
+ was skipped). The exit status is unchanged, since nothing failed, but this
578
+ is not a pass: nothing was verified. In the Action the `verdict` output
579
+ carries this token, so a workflow can tell it apart from `pass`.
574
580
  - `advisory-blocked (N)`: the run would have exited 1, and `--advisory` made
575
581
  it exit 0. N is the blocking findings on enforced gates.
576
582
  - `unenforced-findings (N)`: exit 0, but a gate with `enforce: false` had
@@ -580,11 +586,13 @@ code and the `enforce` flags the run already had.
580
586
  - `could-not-run`: exit 2, a refused trust base included.
581
587
 
582
588
  When several apply the order is `could-not-run`, then `blocked` or
583
- `advisory-blocked`, then `unenforced-findings`, then `pass`. A run with
589
+ `advisory-blocked`, then `unenforced-findings`, then `nothing-checked` (no gate
590
+ ran) or `pass`. A run with
584
591
  `--advisory` whose only blocking findings sit on an unenforced gate is
585
592
  `unenforced-findings`, not `advisory-blocked`, because the flag did nothing
586
593
  there. A gate skipped for want of a contract does not by itself move the token
587
- off `pass`; the verdict sentence is where "nothing was checked" is said. A
594
+ off `pass` when another gate ran; when no gate ran, the token is
595
+ `nothing-checked` and the verdict sentence says "nothing was checked". A
588
596
  gate that exited non-zero with no finding marked blocking counts as one in N,
589
597
  so a state that is not a pass never prints a count of zero. The one-line
590
598
  summary of a clean, non-verbose run has no token line, since it is one line by
@@ -737,15 +745,19 @@ to remove the input; see "The Action" below.
737
745
 
738
746
  **The CLI check catches a misconfigured or innocent-looking redirect when
739
747
  `GITHUB_BASE_REF` is set**, for anyone invoking the CLI directly in CI. When
740
- that variable is set, an explicit `--trust-base` is accepted only when it
741
- resolves to the same commit as `origin/$GITHUB_BASE_REF`, which is exactly
742
- what the Action itself always passes, so an ordinary pull-request run is
748
+ that variable is set, an explicit `--trust-base` is accepted only when it is
749
+ `refs/conductor/trust-base`, the private ref the Action fetches the base
750
+ branch into and always passes (that ref is the authority and is not compared
751
+ with anything), or resolves to the same commit as
752
+ `refs/remotes/origin/$GITHUB_BASE_REF`. So an ordinary pull-request run is
743
753
  unaffected. A ref naming the pull request's own branch, or anything else that
744
754
  disagrees, is refused with both refs and both commits named, through the same
745
755
  could-not-run path as every other trust-base refusal: exit 2, the report
746
- leads with the reason, and nothing is checked. When `origin/$GITHUB_BASE_REF`
747
- itself does not resolve, this fails closed too, naming it, for the same
748
- reason the fetch-depth remedy below exists.
756
+ leads with the reason, and nothing is checked. A short name that matches both
757
+ a tag and a branch or remote-tracking ref (a tag named `origin/main`) is
758
+ refused as ambiguous: spell the ref in full. When neither resolves, this fails
759
+ closed too, naming it, for the same reason the fetch-depth remedy below
760
+ exists.
749
761
 
750
762
  **Neither layer closes anything against a pull request that edits its own
751
763
  workflow file.** A CLI invocation on a pull request can simply omit
@@ -899,8 +911,11 @@ human step. That step is exactly what a pull request cannot carry, so at the
899
911
  branch changed since it forked, from
900
912
  `git diff --name-only --no-renames <base>...HEAD` in the repository root.
901
913
 
902
- With no `--base`, `GITHUB_BASE_REF` is used as `origin/<value>` when it is
903
- set, and the text report says so. With neither, the intent gate runs the way
914
+ With no `--base`, `GITHUB_BASE_REF` is used when it is set, spelled in full:
915
+ `refs/conductor/trust-base` (the Action's private fetch of the base) if that
916
+ exists, else `refs/remotes/origin/<value>`, so a tag of that name cannot
917
+ shadow it. The text report says which. An explicit `--base` that matches both
918
+ a tag and a branch is refused as ambiguous. With neither, the intent gate runs the way
904
919
  it does at a commit: against the staged index, or the paths you name.
905
920
 
906
921
  **This is why a local preview and a pull-request run can disagree about a
@@ -1098,8 +1113,11 @@ provenance even though all four packages publish it.
1098
1113
  umbrella reads `GITHUB_BASE_REF` itself and treats an empty value as "not a
1099
1114
  pull request", which is what a push build wants.
1100
1115
 
1101
- On a `pull_request` event the action passes
1102
- **`--trust-base origin/$GITHUB_BASE_REF`** of its own accord, so the run takes
1116
+ On a `pull_request` event a dedicated step fetches the base branch into a
1117
+ private ref and the action passes **`--trust-base <the fetched commit id>`**
1118
+ of its own accord (the job needs `contents: read`; a failed fetch fails the job
1119
+ rather than running without a trust base; the token exists only in that fetch
1120
+ step and never in the gates), so the run takes
1103
1121
  its configuration from the base branch and the pull request cannot change the
1104
1122
  rules it is judged by; a change to the rules shows as a proposal line and
1105
1123
  takes effect after merge. See "The pull-request trust boundary" above. On any
@@ -1113,7 +1131,8 @@ workflow file is the *base* branch's own instead, but the input is refused
1113
1131
  there too, because pull-request mode already derives the trust base on both
1114
1132
  events and an explicit redirect has no legitimate use on either. The refusal
1115
1133
  names the value that was given and the fix, which is to remove the input: the
1116
- action already derives `origin/$GITHUB_BASE_REF` itself on that event.
1134
+ action already derives the private `refs/conductor/trust-base` itself on that
1135
+ event.
1117
1136
 
1118
1137
  There is deliberately **no input that turns pull-request mode off**.
1119
1138
  Base-ref judging is the floor rather than a knob, and on a `pull_request`
@@ -1148,7 +1167,7 @@ jobs:
1148
1167
  with:
1149
1168
  node-version: '22.11.0'
1150
1169
  - id: conductor
1151
- uses: vaultcompasshq/conductor@v0.7.0
1170
+ uses: vaultcompasshq/conductor@v0.8.0
1152
1171
  with:
1153
1172
  output: conductor.sarif
1154
1173
  - uses: github/codeql-action/upload-sarif@v3
@@ -1191,7 +1210,6 @@ jobs:
1191
1210
  # clone, because on a pull request the rules are read from it: a
1192
1211
  # base ref that will not resolve is exit 2 for every enabled gate.
1193
1212
  fetch-depth: 0
1194
- - uses: pnpm/action-setup@v4
1195
1213
  - uses: actions/setup-node@v7
1196
1214
  with:
1197
1215
  # Not a bare major: Node 22.0.0 ships npm 10.5.1, which the action
@@ -1199,13 +1217,16 @@ jobs:
1199
1217
  # with. 22.1.0 or later, or 20.13.0 or later, carries an npm that
1200
1218
  # can verify.
1201
1219
  node-version: '22.11.0'
1202
- cache: pnpm
1203
- # Your own dependencies. The gates are NOT among the things this has to
1204
- # install: the action installs those itself, globally, at the versions
1205
- # pinned below.
1206
- - run: pnpm install --frozen-lockfile
1220
+ # NOTHING FROM THE PULL REQUEST RUNS BEFORE THE ACTION IN THIS JOB.
1221
+ # No `pnpm install`, `npm ci`, build or test step: an install runs the
1222
+ # repository's own lifecycle scripts (a root postinstall), and that code
1223
+ # could write the PATH the gates are resolved from, or the refs the
1224
+ # policy is read from, before the gates ever start. Your own
1225
+ # dependencies, build and tests belong in a separate job (see below).
1226
+ # The gates are not among the things that job has to install: the action
1227
+ # installs those itself, globally, at the versions pinned below.
1207
1228
  - id: conductor
1208
- uses: vaultcompasshq/conductor@v0.7.0
1229
+ uses: vaultcompasshq/conductor@v0.8.0
1209
1230
  with:
1210
1231
  output: conductor.sarif
1211
1232
  # Exact versions, never a range and never "latest". These four
@@ -1216,10 +1237,10 @@ jobs:
1216
1237
  # request of their own. Forward only on a pull request: the action
1217
1238
  # refuses a pin below what its tag ships, and the four lines can be
1218
1239
  # left out entirely to take that tag's own versions.
1219
- conductor-version: 0.7.0
1220
- dep-guard-version: 0.9.0
1221
- vault-guard-version: 1.8.0
1222
- intent-guard-version: 1.7.0
1240
+ conductor-version: 0.8.0
1241
+ dep-guard-version: 0.10.0
1242
+ vault-guard-version: 1.9.0
1243
+ intent-guard-version: 1.8.0
1223
1244
  - uses: github/codeql-action/upload-sarif@v3
1224
1245
  # Always: the log is most worth having on the run that failed.
1225
1246
  if: always()
@@ -1233,8 +1254,49 @@ jobs:
1233
1254
  continue-on-error: true
1234
1255
  with:
1235
1256
  sarif_file: ${{ steps.conductor.outputs.sarif }}
1257
+
1258
+ # Your own dependencies, build and tests: a different job, so the code they
1259
+ # run shares no runner, PATH or workspace with the gates.
1260
+ build:
1261
+ runs-on: ubuntu-latest
1262
+ steps:
1263
+ - uses: actions/checkout@v7
1264
+ - uses: pnpm/action-setup@v4
1265
+ - uses: actions/setup-node@v7
1266
+ with:
1267
+ node-version: '22.11.0'
1268
+ cache: pnpm
1269
+ - run: pnpm install --frozen-lockfile
1270
+ - run: pnpm test
1236
1271
  ```
1237
1272
 
1273
+ **Run the gates in a job that runs no code from the pull request.** Do not
1274
+ run `pnpm install`, `npm ci`, a build or a test step before the conductor
1275
+ action in the same job, and do not put the action in a job whose earlier steps
1276
+ run the repository's own scripts. Anything that runs first shares the runner
1277
+ with the gates: it can write to `GITHUB_PATH`, to the runner's temp directory
1278
+ where the action installs the gates, or to the git refs the base policy is
1279
+ read from, and then it is the pull request choosing the program that judges
1280
+ it. The action fetches the base branch into its own private ref and judges by
1281
+ that, which closes a moved or tag-shadowed base ref and nothing else. Only
1282
+ keeping pull-request code out of the job covers the rest: `GITHUB_ENV`
1283
+ (`NODE_OPTIONS=--require`, `GIT_CONFIG_*`, `GIT_DIR`), `GITHUB_PATH`,
1284
+ `.git/config` changes (a remote URL, `url.insteadOf`, `core.fsmonitor`,
1285
+ credential helpers, `core.sshCommand`), git hooks such as
1286
+ `reference-transaction`, and replace refs or grafts. Say it plainly:
1287
+ package.json lifecycle scripts (`preinstall`, `install`, `postinstall`,
1288
+ `prepare`) run by an install bypass "require review on `.github/workflows`",
1289
+ because the pull request supplies them, not the workflow file. Branch
1290
+ protection on the workflow directory does not stop them, so the gates must
1291
+ not share a job with head code that runs first.
1292
+
1293
+ **With gitleaks enabled the checkout must be `fetch-depth: 0`.** At the default
1294
+ depth of 1 the checkout is shallow, the range from the base to HEAD holds one
1295
+ grafted commit, and a secret added and then removed inside the pull request
1296
+ would never be seen. conductor detects a shallow checkout and reports the
1297
+ history gate as could-not-run, naming `fetch-depth: 0` (exit 2 on a pull
1298
+ request, whatever `enforce` says). It does not deepen the checkout for you.
1299
+
1238
1300
  **The two external gates are installed by your workflow, not by the
1239
1301
  Action.** The Action still installs exactly its four npm packages and has no
1240
1302
  input for gitleaks or osv-scanner; conductor downloads, pins and checksums
@@ -1259,12 +1321,15 @@ checksum, the same way you would for a standalone security job:
1259
1321
  echo "$bin" >> "$GITHUB_PATH"
1260
1322
  ```
1261
1323
 
1262
- `fetch-depth: 0` on the checkout matters more with gitleaks enabled: on a
1263
- pull request conductor scans `<base>..HEAD`, and a base that was never
1264
- fetched is a git error gitleaks itself would report as a clean scan of
1265
- nothing. conductor reads that error off gitleaks' log and reports the gate
1266
- as could-not-run instead. A missing tool is could-not-run as well, with the
1267
- install step named in the report.
1324
+ `fetch-depth: 0` on the checkout is required with gitleaks enabled: on a
1325
+ pull request conductor scans `<base>..HEAD`. At depth 1 the checkout is
1326
+ shallow and that range holds a single commit, so a secret added and removed
1327
+ inside the pull request would go unseen; conductor detects the shallow
1328
+ checkout and reports the gate as could-not-run instead of scanning it. (A
1329
+ base that was never fetched at all is a git error gitleaks itself would
1330
+ report as a clean scan of nothing; conductor reads that error off gitleaks'
1331
+ log and reports the gate as could-not-run too.) A missing tool is
1332
+ could-not-run as well, with the install step named in the report.
1268
1333
 
1269
1334
  The `@v4` pins there are readable, not safe: a tag moves, so pinning by one
1270
1335
  runs whatever its author pushes to it next. Pin every third-party action by
@@ -1311,15 +1376,16 @@ jobs:
1311
1376
  node-version: '22.11.0'
1312
1377
  - id: conductor
1313
1378
  timeout-minutes: 5
1314
- uses: vaultcompasshq/conductor@v0.7.0
1379
+ uses: vaultcompasshq/conductor@v0.8.0
1315
1380
  with:
1316
1381
  pr-comment: true
1317
1382
  advisory: true
1318
1383
  ```
1319
1384
 
1320
- `action.yml` already shallow-fetches the trust base itself as of 0.4.5 when
1321
- the checkout does not already carry it (see the changelog entry for that
1322
- version), so this recipe needs no separate "fetch the base ref" step. None of
1385
+ `action.yml` fetches the trust base itself on every pull-request run, into its
1386
+ own private ref (depth 1 only when the checkout is already shallow, and always,
1387
+ whether or not the checkout carries the base), so this recipe needs no separate
1388
+ "fetch the base ref" step. None of
1323
1389
  the three steps above swallows its own exit code: a checkout or setup-node
1324
1390
  failure is an infrastructure problem this recipe should still surface, and
1325
1391
  the `conductor` step's own advisory behaviour comes from `advisory: true`
@@ -1442,9 +1508,11 @@ step and add `pull-requests: write` to the job's `permissions`:
1442
1508
  security-events: write
1443
1509
  pull-requests: write
1444
1510
  steps:
1445
- # ... checkout, pnpm, setup-node, install, as in the example above ...
1511
+ # ... checkout and setup-node, as in the example above. Nothing from
1512
+ # the pull request runs before the action in this job: no install, build
1513
+ # or test step here; those belong in a separate job. ...
1446
1514
  - id: conductor
1447
- uses: vaultcompasshq/conductor@v0.7.0
1515
+ uses: vaultcompasshq/conductor@v0.8.0
1448
1516
  with:
1449
1517
  output: conductor.sarif
1450
1518
  pr-comment: true
@@ -1516,12 +1584,12 @@ per pull request.
1516
1584
 
1517
1585
  ```yaml
1518
1586
  - id: conductor-package-a
1519
- uses: vaultcompasshq/conductor@v0.7.0
1587
+ uses: vaultcompasshq/conductor@v0.8.0
1520
1588
  with:
1521
1589
  pr-comment: true
1522
1590
  pr-comment-marker: 'package-a'
1523
1591
  - id: conductor-package-b
1524
- uses: vaultcompasshq/conductor@v0.7.0
1592
+ uses: vaultcompasshq/conductor@v0.8.0
1525
1593
  with:
1526
1594
  pr-comment: true
1527
1595
  pr-comment-marker: 'package-b'
package/dist/cli.js CHANGED
@@ -7,7 +7,7 @@
7
7
  // decisions be tested without a subprocess.
8
8
  import { Command, CommanderError } from 'commander';
9
9
  import { execFileSync } from 'node:child_process';
10
- import { readFileSync, realpathSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
10
+ import { closeSync, constants as fsConstants, lstatSync, openSync, readFileSync, realpathSync, statSync, unlinkSync, writeSync, } from 'node:fs';
11
11
  import path from 'node:path';
12
12
  import { fileURLToPath } from 'node:url';
13
13
  import { EXIT_BLOCKED, EXIT_COULD_NOT_RUN, EXIT_OK } from './exit-codes.js';
@@ -19,6 +19,48 @@ import { refusedTrustBase, runAll } from './run.js';
19
19
  import { headTreeEqualsBase, policyDiffers, readPolicyAtRef, refuseTrustBaseForPullRequest, refuseTrustBaseRef, } from './trust-base.js';
20
20
  const pkgPath = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'package.json');
21
21
  const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
22
+ /**
23
+ * Refuses a report path that is a symbolic link, dangling or not.
24
+ *
25
+ * --output defaults to conductor.sarif in the checkout, and a pull request can
26
+ * commit a symlink by that name. writeFileSync follows it, so the run would
27
+ * overwrite whatever it points at (a hook, .git/config, a runner file) with
28
+ * report text. lstat, never stat: stat follows the link and reports the
29
+ * target. A missing path is fine, and so is an ordinary file.
30
+ */
31
+ function refuseSymlinkReportPath(target, what) {
32
+ let info;
33
+ try {
34
+ info = lstatSync(target);
35
+ }
36
+ catch (err) {
37
+ if (err.code === 'ENOENT') {
38
+ return;
39
+ }
40
+ throw err;
41
+ }
42
+ if (info.isSymbolicLink()) {
43
+ throw new PolicyError(`refusing to write ${what} to ${target}: it is a symbolic link, and writing would follow it ` +
44
+ 'to whatever it points at. Remove the link or choose another path.');
45
+ }
46
+ }
47
+ /**
48
+ * Writes a report file without ever following a symbolic link at the final
49
+ * path: the lstat refusal above for the message, plus O_NOFOLLOW where the
50
+ * platform has it so a link swapped in between the check and the open is
51
+ * refused by the kernel rather than followed.
52
+ */
53
+ function writeReportFile(target, what, body) {
54
+ refuseSymlinkReportPath(target, what);
55
+ const noFollow = fsConstants.O_NOFOLLOW ?? 0;
56
+ const fd = openSync(target, fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_TRUNC | noFollow, 0o666);
57
+ try {
58
+ writeSync(fd, body);
59
+ }
60
+ finally {
61
+ closeSync(fd);
62
+ }
63
+ }
22
64
  /**
23
65
  * The working-tree root, or a thrown one-line diagnosis of why there is none.
24
66
  *
@@ -212,8 +254,8 @@ function policyForRun(root, trustBase, overrides, githubBaseRef) {
212
254
  // the same rule for anyone invoking the CLI directly in CI, bypassing that
213
255
  // step. Checked BEFORE refuseTrustBaseRef and deliberately narrower than
214
256
  // it: it says nothing about HEAD or about tree equality, only about
215
- // whether the given ref agrees with origin/<GITHUB_BASE_REF>, which is
216
- // exactly what the composite action itself always passes. So on an
257
+ // whether the given ref agrees with the base branch (the full commit id the
258
+ // composite action's fetch step published). So on an
217
259
  // ordinary pull-request run this returns null immediately and
218
260
  // refuseTrustBaseRef runs its own checks unchanged, the equal-tree
219
261
  // first-parent exception (issue #69/#73) included.
@@ -432,10 +474,10 @@ export function buildProgram() {
432
474
  .option('--staged', 'gate the git index against HEAD, the way the pre-commit hook does')
433
475
  .option('--format <format>', 'output format: text or sarif')
434
476
  .option('--stage <stage>', `which stopping point this run is: ${GATE_STAGES.join(', ')}. Stages are cumulative, so a gate runs at its own stage and every later one. Omit it to run every enabled gate.`)
435
- .option('--base <ref>', 'measure the intent gate against what this branch changed since <ref>, rather than against the index. In Actions this defaults to origin/<GITHUB_BASE_REF> when it is set.')
436
- .option('--trust-base <ref>', 'pull-request mode: read .guardrails.yaml from this ref instead of from the tree being judged, and pass the same ref to every gate that supports it. A policy change in the pull request is reported as a proposal and never takes effect for the run, so a pull request cannot change the rules it is judged by. In Actions the composite action passes origin/<GITHUB_BASE_REF> on a pull_request event.')
477
+ .option('--base <ref>', 'measure the intent gate against what this branch changed since <ref>, rather than against the index. In Actions this defaults to the base branch (refs/conductor/trust-base, else refs/remotes/origin/<GITHUB_BASE_REF>, as a commit id) when GITHUB_BASE_REF is set.')
478
+ .option('--trust-base <ref>', 'pull-request mode: read .guardrails.yaml from this ref instead of from the tree being judged, and pass the same ref to every gate that supports it. A policy change in the pull request is reported as a proposal and never takes effect for the run, so a pull request cannot change the rules it is judged by. In Actions the composite action fetches the base branch and passes its full commit id on a pull_request event.')
437
479
  .option('--output <path>', 'write the report to this file instead of to stdout, for a CI step that uploads it')
438
- .option('--text-report <path>', 'with --format sarif, also write the text report to this file, from the same run: exactly what --format text would have rendered for this result, --verbose, --compact-on-refusal and --advisory respected, and no gate is run a second time. In a full report (any run that is not fully clean, or any run with --verbose) the second line is "verdict-token: <token>"; the one-line summary of a clean run without --verbose has none. The token is a label for this run\'s own exit decision: pass, advisory-blocked (N), unenforced-findings (N), blocked (N) or could-not-run. Only meaningful with --format sarif: with --format text the text report is already the output, so the combination is a usage error (exit 2).')
480
+ .option('--text-report <path>', 'with --format sarif, also write the text report to this file, from the same run: exactly what --format text would have rendered for this result, --verbose, --compact-on-refusal and --advisory respected, and no gate is run a second time. In a full report (any run that is not fully clean, or any run with --verbose) the second line is "verdict-token: <token>"; the one-line summary of a clean run without --verbose has none. The token is a label for this run\'s own exit decision: pass, nothing-checked (exit 0 but no gate ran), advisory-blocked (N), unenforced-findings (N), blocked (N) or could-not-run. Only meaningful with --format sarif: with --format text the text report is already the output, so the combination is a usage error (exit 2).')
439
481
  .option('--spec <path>', 'the spec the intent gate imports its contract from, outranking a Spec: line in the pull request body and the branch-name convention')
440
482
  .option('--verbose', 'print the full per-gate report even when the run is clean. A clean run prints one summary line by default, because a pre-commit hook that prints a screenful on every commit is a hook a team switches off. Text output only; SARIF is unaffected.')
441
483
  .option('--compact-on-refusal', 'when the trust base was refused and no gate ran, print a short body instead of the full refusal report: the version, the verdict, and the refusal reason (with its remedy, when one applies), never the full per-gate report. Built for the pull-request-comment step; every other run is unaffected, whatever --verbose says. Text output only; SARIF is unaffected.')
@@ -507,7 +549,7 @@ export function buildProgram() {
507
549
  // own. Reporting exit 0 next to a report nobody can read is the
508
550
  // worst of the available answers: the upload step downstream would
509
551
  // fail on a missing file with no explanation here.
510
- writeFileSync(options.output, rendered);
552
+ writeReportFile(options.output, 'the report', rendered);
511
553
  }
512
554
  // WRITTEN LAST, after the SARIF log or stdout, and removed again in
513
555
  // the catch below if anything after it throws. A run that exits 2
@@ -516,8 +558,11 @@ export function buildProgram() {
516
558
  // post it as a comment, beside a red job. A text report that cannot
517
559
  // be written takes the could-not-run code, like an unwritable --output.
518
560
  if (options.textReport !== undefined && textReport !== undefined) {
561
+ // Checked BEFORE textReportPath is set, so the catch below never
562
+ // unlinks a path this run refused to touch.
563
+ refuseSymlinkReportPath(options.textReport, 'the text report');
519
564
  textReportPath = options.textReport;
520
- writeFileSync(options.textReport, textReport);
565
+ writeReportFile(options.textReport, 'the text report', textReport);
521
566
  }
522
567
  if (options.output !== undefined) {
523
568
  // One line, so a CI job whose only product is an uploaded artifact
@@ -62,7 +62,13 @@ export function extendPath(config) {
62
62
  }
63
63
  /** A file's contents at a ref, or null when the ref does not have it. */
64
64
  function showAtRef(repoRoot, ref, file) {
65
- const child = spawnSync('git', ['show', `${ref}:${file}`], { cwd: repoRoot, encoding: 'utf8' });
65
+ if (ref.startsWith('-')) {
66
+ return null;
67
+ }
68
+ const child = spawnSync('git', ['show', '--end-of-options', `${ref}:${file}`], {
69
+ cwd: repoRoot,
70
+ encoding: 'utf8',
71
+ });
66
72
  return child.status === 0 && typeof child.stdout === 'string' ? child.stdout : null;
67
73
  }
68
74
  function headCopy(repoRoot, file) {
@@ -36,7 +36,15 @@ export type CouldNotRunReason = 'binary-missing' | 'configured-command-missing'
36
36
  * verdict to is not there. Only a tool whose output is a report file can
37
37
  * land here.
38
38
  */
39
- | 'report-missing';
39
+ | 'report-missing'
40
+ /**
41
+ * The gate reads git history and the checkout is shallow, so the history it
42
+ * would read is truncated (at depth 1 the pull request's merge commit is
43
+ * grafted, and base..HEAD holds one commit: a secret added and removed
44
+ * inside the pull request is never seen). Never unshallowed automatically:
45
+ * the remedy is a checkout setting, fetch-depth: 0.
46
+ */
47
+ | 'history-shallow';
40
48
  export interface CouldNotRun {
41
49
  reason: CouldNotRunReason;
42
50
  detail: string;
@@ -274,9 +274,10 @@ external = {}) {
274
274
  // with cwd at the repository root anyway. Passing one would also risk
275
275
  // a passthrough value being read as the positional.
276
276
  //
277
- // `scan` takes --trust-base from 1.7.0, and on exit 2 it prints one
278
- // line on stderr and NO document at all, which the could-not-run path
279
- // above already handles before JSON.parse is reached.
277
+ // `scan` takes --trust-base from 1.7.0. On exit 2 it prints a line on
278
+ // stderr and may also write a JSON document (it can on a staged run);
279
+ // conductor never parses stdout on exit 2, so the could-not-run path
280
+ // above handles both before JSON.parse is reached.
280
281
  return [...(staged ? ['--staged'] : []), '-f', 'json', ...trust, ...passthrough];
281
282
  case 'intent-guard': {
282
283
  if (intent === undefined) {
@@ -484,7 +485,10 @@ function missingGateRemedy(product, skipNodeModules, skipped) {
484
485
  return ` ${profile.remedy(skipNodeModules)}`;
485
486
  }
486
487
  if (!skipNodeModules) {
487
- return '';
488
+ // Named on a local run too: the scoped package is the only correct
489
+ // install target, and the finding's own sentence must not be the only
490
+ // place a reader could take a bare name from.
491
+ return ` ${profile.remedy(false)}`;
488
492
  }
489
493
  return (' On a pull-request run node_modules/.bin is not consulted at all: what is installed there ' +
490
494
  'is chosen by the head own manifest and lockfile, so no ref approves it.' +
@@ -559,6 +563,18 @@ export function runGate(gate, options) {
559
563
  };
560
564
  }
561
565
  }
566
+ /**
567
+ * Whether git says the repository at `repoRoot` is shallow. Anything other
568
+ * than a clear "true" (no git, an old git that does not know the flag) is
569
+ * not shallow: those runs have their own failure paths.
570
+ */
571
+ function isShallowRepository(repoRoot) {
572
+ const probe = spawnSync('git', ['rev-parse', '--is-shallow-repository'], {
573
+ cwd: repoRoot,
574
+ encoding: 'utf8',
575
+ });
576
+ return probe.status === 0 && typeof probe.stdout === 'string' && probe.stdout.trim() === 'true';
577
+ }
562
578
  function runGateInner(gate, options, started, progress) {
563
579
  const timeoutMs = options.timeoutMs ?? profileFor(gate.product).timeoutMs;
564
580
  // ONE PLACE DECIDES WHAT PULL-REQUEST MODE IS, and it is the presence of a
@@ -611,7 +627,9 @@ function runGateInner(gate, options, started, progress) {
611
627
  // not a location this run has.
612
628
  detail: (skipNodeModules
613
629
  ? `no ${gate.product} binary on PATH`
614
- : `no ${gate.product} binary in node_modules/.bin or on PATH`) + remedy,
630
+ : `no ${gate.product} binary in node_modules/.bin or on PATH`) +
631
+ (remedy === '' ? '' : '.') +
632
+ remedy,
615
633
  },
616
634
  // A missing enabled gate is a finding of the umbrella's own, never a
617
635
  // silent skip. Skipping is how a gate ends up switched on in the
@@ -642,6 +660,27 @@ function runGateInner(gate, options, started, progress) {
642
660
  };
643
661
  }
644
662
  }
663
+ // A history gate cannot vouch for history it was not given. Checked before
664
+ // the version probe so nothing is executed for a run that cannot be honest.
665
+ if (profileFor(gate.product).readsHistory && isShallowRepository(options.repoRoot)) {
666
+ const detail = `this checkout is shallow, so the git history ${gate.product} reads is truncated: ` +
667
+ 'with the default actions/checkout depth of 1 the range from the base to HEAD holds a ' +
668
+ 'single grafted commit, and a secret added and then removed inside the pull request ' +
669
+ 'would never be seen. Check out with fetch-depth: 0 (actions/checkout) or run ' +
670
+ 'git fetch --unshallow, then run again. conductor does not deepen the checkout itself.';
671
+ return {
672
+ ...base,
673
+ // Under a trust base this is enforced whatever the policy says: the
674
+ // gate produced nothing for `enforce: false` to be a decision about.
675
+ // A local run keeps the policy's own value.
676
+ enforce: options.trustBase !== undefined ? true : gate.enforce,
677
+ durationMs: Date.now() - started,
678
+ couldNotRun: { reason: 'history-shallow', detail },
679
+ findings: [normalizeFailedGate(gate.role, gate.product, detail)],
680
+ run: EMPTY_RUN,
681
+ diagnostics: [],
682
+ };
683
+ }
645
684
  const version = probeVersion(binary, gate.product, options.repoRoot, timeoutMs);
646
685
  // The command-line floor. Only the external tools have one: the umbrella
647
686
  // writes flags they grew at a known release (gitleaks' git subcommand,
@@ -895,6 +934,11 @@ function spawnAndRead(ctx) {
895
934
  encoding: 'utf8',
896
935
  timeout: timeoutMs,
897
936
  maxBuffer: 64 * 1024 * 1024,
937
+ // A history gate reads git history, and replace refs or grafts can cut
938
+ // that history without making the repository shallow. Ignoring replace
939
+ // objects makes it read the real commits. Other gates keep the
940
+ // inherited environment untouched.
941
+ ...(profile.readsHistory ? { env: { ...process.env, GIT_NO_REPLACE_OBJECTS: '1' } } : {}),
898
942
  });
899
943
  const withRun = {
900
944
  ...base,
@@ -2,6 +2,7 @@ import { statSync } from 'node:fs';
2
2
  import path from 'node:path';
3
3
  import { NATIVE_CONTRACT_PATH } from './intent-prepare.js';
4
4
  import { DEFAULT_STAGE_FOR_ROLE, GATE_ROLES, POLICY_FILE_NAME, PRODUCT_FOR_ROLE } from './policy.js';
5
+ import { installName } from './normalize.js';
5
6
  import { CANDIDATES } from './resolve.js';
6
7
  export { POLICY_FILE_NAME };
7
8
  /** Names of the gates whose binary resolves right now. */
@@ -96,7 +97,7 @@ export function renderPolicy(detected, frozenContractPath) {
96
97
  const enabled = detected.has(role);
97
98
  lines.push(` # ${ROLE_DESCRIPTION[role]}`);
98
99
  if (!enabled) {
99
- lines.push(` # not found in node_modules/.bin or on PATH. Install ${product}, then set enabled: true.`);
100
+ lines.push(` # not found in node_modules/.bin or on PATH. Install ${installName(product)}, then set enabled: true.`);
100
101
  }
101
102
  lines.push(` ${role}:`);
102
103
  lines.push(` product: ${product}`);
@@ -23,6 +23,35 @@ export declare function resolveBaseRef(options: {
23
23
  base?: string;
24
24
  env: NodeJS.ProcessEnv;
25
25
  }): BaseResolution | null;
26
+ export type ResolvedBase = {
27
+ ok: true;
28
+ base: BaseResolution | null;
29
+ } | {
30
+ ok: false;
31
+ detail: string;
32
+ };
33
+ /**
34
+ * The base to diff against, resolved against the repository and always
35
+ * spelled so a tag cannot shadow it (the same class as the trust base: git
36
+ * resolves a short origin/<base> through refs/tags/ first, so a tag at
37
+ * HEAD~1 would narrow the change set to the last commit).
38
+ *
39
+ * - An explicit --base keeps its meaning, but a short name that matches
40
+ * more than one kind of ref is refused (refuseAmbiguousRef).
41
+ * - Otherwise, on a pull request: refs/conductor/trust-base (the composite
42
+ * action's private fetch) when it exists, else refs/remotes/origin/<base>,
43
+ * both in full. The private ref wins and is not compared against the
44
+ * remote-tracking ref. If neither exists the spelled remote ref is returned and the
45
+ * diff fails closed, naming fetch-depth: 0.
46
+ * - Null outside a pull request.
47
+ *
48
+ * Nothing is deepened here: a depth-1 private ref has no merge base and the
49
+ * diff fails closed, the same outcome as a depth-1 origin/<base> always had.
50
+ */
51
+ export declare function resolveBaseRefInRepo(repoRoot: string, options: {
52
+ base?: string;
53
+ env: NodeJS.ProcessEnv;
54
+ }): ResolvedBase;
26
55
  /**
27
56
  * The branch this run is about.
28
57
  *
@@ -16,6 +16,7 @@
16
16
  // the flags below are copied from intent-guard 1.2.1 so the two agree on what
17
17
  // "changed" means rather than agreeing by coincidence.
18
18
  import { spawnSync } from 'node:child_process';
19
+ import { PRIVATE_TRUST_BASE_REF, exactRefObject, refuseAmbiguousRef } from './trust-base.js';
19
20
  /**
20
21
  * The ref to diff against, or null for a run that is not a pull request.
21
22
  *
@@ -35,6 +36,77 @@ export function resolveBaseRef(options) {
35
36
  }
36
37
  return null;
37
38
  }
39
+ /**
40
+ * The base to diff against, resolved against the repository and always
41
+ * spelled so a tag cannot shadow it (the same class as the trust base: git
42
+ * resolves a short origin/<base> through refs/tags/ first, so a tag at
43
+ * HEAD~1 would narrow the change set to the last commit).
44
+ *
45
+ * - An explicit --base keeps its meaning, but a short name that matches
46
+ * more than one kind of ref is refused (refuseAmbiguousRef).
47
+ * - Otherwise, on a pull request: refs/conductor/trust-base (the composite
48
+ * action's private fetch) when it exists, else refs/remotes/origin/<base>,
49
+ * both in full. The private ref wins and is not compared against the
50
+ * remote-tracking ref. If neither exists the spelled remote ref is returned and the
51
+ * diff fails closed, naming fetch-depth: 0.
52
+ * - Null outside a pull request.
53
+ *
54
+ * Nothing is deepened here: a depth-1 private ref has no merge base and the
55
+ * diff fails closed, the same outcome as a depth-1 origin/<base> always had.
56
+ */
57
+ export function resolveBaseRefInRepo(repoRoot, options) {
58
+ if (options.base !== undefined && options.base !== '') {
59
+ // A base that starts with a dash is an OPTION to git, not a ref:
60
+ // "--output=/x" made "git diff --output=/x...HEAD" write that file and
61
+ // print nothing, an empty change set the intent gate then judged as clean.
62
+ // Refused here, and changedPathsSince passes --end-of-options as well.
63
+ if (options.base.startsWith('-')) {
64
+ return {
65
+ ok: false,
66
+ detail: `refusing "${options.base}" as the intent gate base: it starts with a dash, so git would ` +
67
+ 'read it as an option rather than a ref. Nothing was checked.',
68
+ };
69
+ }
70
+ const ambiguous = refuseAmbiguousRef(repoRoot, options.base, 'the intent gate base');
71
+ if (ambiguous !== null) {
72
+ return { ok: false, detail: ambiguous };
73
+ }
74
+ // A refs/ name is checked with show-ref: git's name resolution would
75
+ // otherwise fall back to refs/tags/<that name> when the ref is absent.
76
+ if (options.base.startsWith('refs/') && exactRefObject(repoRoot, options.base) === null) {
77
+ return {
78
+ ok: false,
79
+ detail: `refusing "${options.base}" as the intent gate base: no such ref exists in this ` +
80
+ 'repository (a tag of that name does not count). Nothing was checked.',
81
+ };
82
+ }
83
+ return { ok: true, base: { ref: options.base, source: 'flag' } };
84
+ }
85
+ const fromGithub = options.env.GITHUB_BASE_REF;
86
+ if (fromGithub === undefined || fromGithub === '') {
87
+ return { ok: true, base: null };
88
+ }
89
+ const remoteRef = `refs/remotes/origin/${fromGithub}`;
90
+ // The private ref is the authority when it exists; refs/remotes/origin/<base>
91
+ // is fixed at checkout time, is the side pull-request code can move, and is
92
+ // not compared against it (a merge to the base in between would be a false
93
+ // refusal). It is the base only when the private ref is absent. Both are
94
+ // read with show-ref (the EXACT ref, never git's name resolution, which
95
+ // would take a tag of that name) and the base handed on is the commit id.
96
+ const priv = exactRefObject(repoRoot, PRIVATE_TRUST_BASE_REF);
97
+ const remote = exactRefObject(repoRoot, remoteRef);
98
+ const chosen = priv ?? remote;
99
+ if (chosen === null) {
100
+ return {
101
+ ok: false,
102
+ detail: `neither ${PRIVATE_TRUST_BASE_REF} (the composite action's fetch of the base branch) nor ` +
103
+ `${remoteRef} exists in this repository, so there is no base to measure the intent gate ` +
104
+ 'against. Nothing was checked. In CI, check out with fetch-depth: 0, or fetch the base ' +
105
+ 'ref before the run.',
106
+ };
107
+ }
108
+ return { ok: true, base: { ref: chosen, source: 'github' } };
109
+ }
38
110
  /**
39
111
  * The branch this run is about.
40
112
  *
@@ -83,7 +155,15 @@ export function changedPathsSince(repoRoot, base) {
83
155
  'core.quotePath=false',
84
156
  'diff',
85
157
  '--name-only',
158
+ // NUL-terminated, so a name with a quote, a backslash, a tab or a
159
+ // newline arrives byte for byte instead of C-quoted ("a\"b.txt"), which
160
+ // names no file and which intent-guard refuses outright (backslash).
161
+ '-z',
86
162
  '--no-renames',
163
+ // Everything after this is a revision, never an option, whatever the
164
+ // caller-given base looks like (the second line of defence behind the
165
+ // dash refusal in resolveBaseRefInRepo).
166
+ '--end-of-options',
87
167
  `${base}...HEAD`,
88
168
  ], { cwd: repoRoot, encoding: 'utf8' });
89
169
  if (child.error !== undefined) {
@@ -102,11 +182,11 @@ export function changedPathsSince(repoRoot, base) {
102
182
  'check out with fetch-depth: 0, or fetch the base ref before the run.',
103
183
  };
104
184
  }
105
- // Split on newlines and NOTHING else. Trimming each line was corrupting a
185
+ // Split on NUL and NOTHING else. Trimming each entry was corrupting a
106
186
  // filename with leading or trailing whitespace into a different filename,
107
187
  // which is worse than refusing it: the gate would then check a path that
108
188
  // does not exist and never check the one that changed.
109
- const paths = (child.stdout ?? '').split('\n').filter((line) => line.length > 0);
189
+ const paths = (child.stdout ?? '').split('\0').filter((line) => line.length > 0);
110
190
  for (const entry of paths) {
111
191
  // Fail closed rather than hand over a path the encoding cannot carry.
112
192
  // `--paths` is comma-joined, which is the only shape intent-guard 1.2.1
@@ -122,6 +202,20 @@ export function changedPathsSince(repoRoot, base) {
122
202
  'Nothing was checked, rather than checking a path that does not exist.',
123
203
  };
124
204
  }
205
+ // intent-guard refuses ANY explicit --paths entry containing a backslash
206
+ // (skill/src/changed-paths.ts, explicitPathIssue: "it contains a
207
+ // backslash"), and exits 2 with a message that names the flag rather than
208
+ // the file. Said here instead, naming the file. A newline, tab or quote
209
+ // inside a path is accepted by intent-guard (it splits on commas only) and
210
+ // passes through intact.
211
+ if (entry.includes('\\')) {
212
+ return {
213
+ ok: false,
214
+ detail: `the changed path "${entry}" contains a backslash, and intent-guard refuses an explicit ` +
215
+ 'path list entry with one (--paths), so it cannot judge this change. Nothing was ' +
216
+ 'checked. Rename the file, or run the intent gate against the index instead.',
217
+ };
218
+ }
125
219
  if (entry !== entry.trim()) {
126
220
  return {
127
221
  ok: false,
@@ -34,7 +34,7 @@ import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, rmSync, st
34
34
  import os from 'node:os';
35
35
  import path from 'node:path';
36
36
  import { parse as parseYaml } from 'yaml';
37
- import { changedPathsSince, currentBranch, resolveBaseRef } from './intent-base.js';
37
+ import { changedPathsSince, currentBranch, resolveBaseRefInRepo } from './intent-base.js';
38
38
  import { summariseStderr } from './normalize.js';
39
39
  import { SPEC_DIR, discoverSpec, prBodyFromEvent } from './intent-spec.js';
40
40
  /** Prefix of the per-run directory, exported so a test can count leaks. */
@@ -383,10 +383,14 @@ export function prepareIntent(options) {
383
383
  'Name one with a "Spec: <path>" line in the pull request body, or pass --spec.',
384
384
  };
385
385
  }
386
- const base = resolveBaseRef({
386
+ const resolvedBase = resolveBaseRefInRepo(repoRoot, {
387
387
  ...(options.base === undefined ? {} : { base: options.base }),
388
388
  env,
389
389
  });
390
+ if (!resolvedBase.ok) {
391
+ return { kind: 'failed', step: 'base', detail: resolvedBase.detail };
392
+ }
393
+ const base = resolvedBase.base;
390
394
  let paths = null;
391
395
  if (base !== null) {
392
396
  const changed = changedPathsSince(repoRoot, base.ref);
@@ -54,6 +54,15 @@ roots?: readonly string[],
54
54
  /** The lockfiles the umbrella passed with --lockfile, repository-relative. */
55
55
  lockfiles?: readonly string[]): NormalizedGateOutput;
56
56
  export type GateProblemRule = 'conductor/gate-missing' | 'conductor/gate-output-unparseable' | 'conductor/gate-failed';
57
+ /**
58
+ * What to install for a product, spelled so it cannot be mistaken for
59
+ * another package. The three npm gates are published under the
60
+ * @vaultcompass scope only: the unscoped dep-guard and intent-guard names are
61
+ * unclaimed on npm, so a reader (or an agent) told to install the bare name
62
+ * could install a squatted package. The external tools are not npm packages
63
+ * of this family and keep their own names.
64
+ */
65
+ export declare function installName(product: Product): string;
57
66
  /**
58
67
  * The finding raised when an ENABLED gate's binary cannot be found.
59
68
  *
package/dist/normalize.js CHANGED
@@ -14,6 +14,7 @@
14
14
  // own reported count says otherwise.
15
15
  import { createHash } from 'node:crypto';
16
16
  import { NormalizeError, atOrAboveThreshold, } from './envelope.js';
17
+ import { profileFor } from './products.js';
17
18
  const BLOCKING_MISMATCH = 'conductor/blocking-count-mismatch';
18
19
  const THRESHOLD_UNKNOWN = 'conductor/blocking-threshold-unknown';
19
20
  function isRecord(value) {
@@ -1045,6 +1046,17 @@ function gateProblem(ruleId, role, product, message, details) {
1045
1046
  details: { role, product, ...details },
1046
1047
  };
1047
1048
  }
1049
+ /**
1050
+ * What to install for a product, spelled so it cannot be mistaken for
1051
+ * another package. The three npm gates are published under the
1052
+ * @vaultcompass scope only: the unscoped dep-guard and intent-guard names are
1053
+ * unclaimed on npm, so a reader (or an agent) told to install the bare name
1054
+ * could install a squatted package. The external tools are not npm packages
1055
+ * of this family and keep their own names.
1056
+ */
1057
+ export function installName(product) {
1058
+ return profileFor(product).managed ? `@vaultcompass/${product}` : product;
1059
+ }
1048
1060
  /**
1049
1061
  * The finding raised when an ENABLED gate's binary cannot be found.
1050
1062
  *
@@ -1066,7 +1078,7 @@ export function normalizeMissingGate(role, product, candidates,
1066
1078
  */
1067
1079
  remedy = '') {
1068
1080
  return gateProblem('conductor/gate-missing', role, product, `The "${role}" gate is enabled but no ${product} binary was found. ` +
1069
- `Looked for: ${candidates.join(', ')}. Install it, point the gate at a build with an ` +
1081
+ `Looked for: ${candidates.join(', ')}. Install ${installName(product)}, point the gate at a build with an ` +
1070
1082
  `absolute "command:", or set enabled: false to switch the gate off on purpose.${remedy}`, { candidates });
1071
1083
  }
1072
1084
  /**
@@ -31,6 +31,8 @@ export declare function jobLogSummary(result: RunResult): string;
31
31
  * the state without parsing the verdict sentence.
32
32
  *
33
33
  * pass exit 0 and nothing was hidden by it
34
+ * nothing-checked exit 0, but no gate ran at all (none enabled,
35
+ * or every one deferred, tree-unchanged or skipped)
34
36
  * advisory-blocked (N) exit 1 that --advisory turned into exit 0
35
37
  * unenforced-findings (N) exit 0, but enforce: false gates blocked or
36
38
  * could not run
@@ -51,8 +53,8 @@ export declare function jobLogSummary(result: RunResult): string;
51
53
  *
52
54
  * A SKIPPED gate (no contract, or a waived spec) is in result.skipped rather
53
55
  * than result.gates, is neither a blocking finding nor a could-not-run, and
54
- * so does not by itself move the token off pass. The verdict sentence is
55
- * where "nothing was checked" is said.
56
+ * so does not by itself move the token off pass when another gate ran. When
57
+ * NO gate ran, the token is nothing-checked, matching the verdict sentence.
56
58
  *
57
59
  * Any exit code outside 0, 1 and 2 is could-not-run: an unknown state is
58
60
  * not a pass.
@@ -405,6 +405,8 @@ function blockingCount(gate) {
405
405
  * the state without parsing the verdict sentence.
406
406
  *
407
407
  * pass exit 0 and nothing was hidden by it
408
+ * nothing-checked exit 0, but no gate ran at all (none enabled,
409
+ * or every one deferred, tree-unchanged or skipped)
408
410
  * advisory-blocked (N) exit 1 that --advisory turned into exit 0
409
411
  * unenforced-findings (N) exit 0, but enforce: false gates blocked or
410
412
  * could not run
@@ -425,8 +427,8 @@ function blockingCount(gate) {
425
427
  *
426
428
  * A SKIPPED gate (no contract, or a waived spec) is in result.skipped rather
427
429
  * than result.gates, is neither a blocking finding nor a could-not-run, and
428
- * so does not by itself move the token off pass. The verdict sentence is
429
- * where "nothing was checked" is said.
430
+ * so does not by itself move the token off pass when another gate ran. When
431
+ * NO gate ran, the token is nothing-checked, matching the verdict sentence.
430
432
  *
431
433
  * Any exit code outside 0, 1 and 2 is could-not-run: an unknown state is
432
434
  * not a pass.
@@ -443,6 +445,13 @@ export function verdictToken(result, advisory) {
443
445
  .reduce((total, gate) => total + blockingCount(gate), 0);
444
446
  return advisory ? `advisory-blocked (${count})` : `blocked (${count})`;
445
447
  }
448
+ // Exit 0 with no gate having run at all (none enabled, every one deferred,
449
+ // tree-unchanged or skipped): the exit code stays 0, since nothing failed,
450
+ // but the label must not say pass. It is the same condition the verdict
451
+ // sentence words as "nothing was checked".
452
+ if (result.gates.length === 0) {
453
+ return 'nothing-checked';
454
+ }
446
455
  const unenforced = result.gates
447
456
  .filter((gate) => !gate.enforce)
448
457
  .reduce((total, gate) => total + (gate.couldNotRun !== null ? 1 : blockingCount(gate)), 0);
package/dist/products.js CHANGED
@@ -39,7 +39,7 @@ function managedRemedy(product) {
39
39
  ? `Install the gate outside the tree with npm install -g @vaultcompass/${product}. The ` +
40
40
  `conductor Action does exactly that, at the version its ${product}-version input pins, and ` +
41
41
  'that pin lives in the workflow file on the base branch.'
42
- : `Install it with npm install -g @vaultcompass/${product}, or add it to the repository's devDependencies.`;
42
+ : `The package is @vaultcompass/${product}, never the unscoped name: install it with npm install -g @vaultcompass/${product}, or add @vaultcompass/${product} to the repository's devDependencies.`;
43
43
  }
44
44
  function managedProfile(product) {
45
45
  return {
@@ -1,3 +1,49 @@
1
+ /**
2
+ * The private, fully spelled ref the composite action fetches the base branch
3
+ * into (action.yml, gates step). Nothing else writes it and no short name can
4
+ * shadow it: git resolves a short name like origin/main through refs/tags/
5
+ * BEFORE refs/remotes/, so a tag pushed by anyone able to push tags would
6
+ * otherwise choose the commit the rules are read from.
7
+ */
8
+ export declare const PRIVATE_TRUST_BASE_REF = "refs/conductor/trust-base";
9
+ /**
10
+ * The object id a fully spelled ref EXACTLY names, or null when there is no
11
+ * such ref. `show-ref --verify` looks at that ref and nothing else: it does
12
+ * not run git's name-resolution rules, so a tag stored as
13
+ * refs/tags/refs/conductor/trust-base is never taken for
14
+ * refs/conductor/trust-base.
15
+ */
16
+ export declare function exactRefObject(repoRoot: string, fullRef: string): string | null;
17
+ /**
18
+ * A caller-given trust base that starts with "-", or null. Git allows a tag
19
+ * named refs/tags/--output=x, and such a name handed to git as an argument is
20
+ * read as an option, not a revision. Refused before any git call sees it; the
21
+ * git calls below also pass --end-of-options as a second line of defence.
22
+ */
23
+ export declare function refuseDashLeadingRef(ref: string): string | null;
24
+ /** A full 40- or 64-hex object id: never subject to ref name resolution. */
25
+ export declare function isFullObjectId(value: string): boolean;
26
+ /**
27
+ * Why a SHORT ref name cannot be trusted as spelled, or null.
28
+ *
29
+ * A name that matches more than one kind of ref (a tag and a remote-tracking
30
+ * ref or a branch) is resolved by git in its own precedence order, tags
31
+ * first, with no warning under --quiet. That is a choice made by whoever can
32
+ * create the tag, so it is refused rather than resolved. A ref already spelled
33
+ * from refs/ is unambiguous, and revision expressions (HEAD, HEAD~1, a sha) are
34
+ * not names and are left to the callers' own checks.
35
+ */
36
+ export declare function refuseAmbiguousRef(repoRoot: string, ref: string,
37
+ /** What the ref is used as, for the message: "the trust base", "the intent base". */
38
+ noun?: string): string | null;
39
+ /**
40
+ * What a rev resolves to at this repository, or null when it does not.
41
+ *
42
+ * `--quiet` suppresses git's own explanation, so there is nothing worth
43
+ * forwarding on failure: the caller writes a sentence a reader can act on
44
+ * rather than repeating the command line that failed.
45
+ */
46
+ export declare function resolveRev(repoRoot: string, rev: string, kind: 'commit' | 'tree'): string | null;
1
47
  /**
2
48
  * Whether HEAD's tree is byte-identical to the trust base's tree.
3
49
  *
@@ -54,11 +100,12 @@ export declare function refuseTrustBaseRef(repoRoot: string, ref: string): strin
54
100
  * NAME on a pull_request or pull_request_target event, and empty everywhere
55
101
  * else -- a push, a schedule, workflow_dispatch, merge_group, a local run, or
56
102
  * a platform that never sets it. When it is set, the given ref is accepted
57
- * only when it resolves to the SAME COMMIT as origin/<githubBaseRef>, which
58
- * is exactly what the composite action itself always passes
59
- * (`--trust-base "origin/$GITHUB_BASE_REF"` in action.yml's gates step). So
60
- * an ordinary pull-request run sees the given ref and the expected ref as the
61
- * identical spelling and this returns null immediately, before
103
+ * only when it is the FULL COMMIT ID the composite action's "Fetch the trust
104
+ * base" step published (which must equal refs/conductor/trust-base, the
105
+ * authority, or refs/remotes/origin/<githubBaseRef>, both read with show-ref),
106
+ * or is that private ref itself, or -- for an explicit trust base -- resolves
107
+ * to the same commit as refs/remotes/origin/<githubBaseRef>. So an ordinary
108
+ * pull-request run through the action returns null here, before
62
109
  * refuseTrustBaseRef's own checks -- HEAD, and the equal-tree exception from
63
110
  * issue #69/#73 -- ever run: this check is narrower than those and says
64
111
  * nothing about HEAD or about tree equality, only about whether the given ref
@@ -66,11 +113,11 @@ export declare function refuseTrustBaseRef(repoRoot: string, ref: string): strin
66
113
  * request's own branch, or anything else that disagrees, is refused with both
67
114
  * refs and both commits named.
68
115
  *
69
- * FAILS CLOSED when origin/<githubBaseRef> itself does not resolve, naming
70
- * it: reachable on the default actions/checkout (fetch-depth: 1), which does
71
- * not carry the base branch at all. The README already asks for
72
- * fetch-depth: 0, and a checkout that does not carry the base branch is not a
73
- * reason to skip the comparison.
116
+ * FAILS CLOSED when neither the private ref nor refs/remotes/origin/
117
+ * <githubBaseRef> exists, naming them: reachable through the CLI on the
118
+ * default actions/checkout (fetch-depth: 1), which does not carry the base
119
+ * branch at all. The README already asks for fetch-depth: 0, and a checkout
120
+ * that does not carry the base branch is not a reason to skip the comparison.
74
121
  *
75
122
  * When the GIVEN ref does not resolve at all, this returns null rather than
76
123
  * refusing: refuseTrustBaseRef is the function with its own sentence for an
@@ -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.7.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": [