rungate 0.8.1 → 0.8.3
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/bin/rungate.ts +11 -6
- package/config/prove-evidence.schema.json +21 -3
- package/gates/.gate-salt +1 -1
- package/gates/gate-executor.ts +153 -1
- package/gates/prove.test.ts +12 -6
- package/gates/schema.ts +69 -6
- package/gates/workflow.test.ts +12 -5
- package/hooks/BashWriteGuard.hook.ts +19 -0
- package/hooks/DocHygiene.hook.ts +2 -1
- package/hooks/GateResultProtection.hook.ts +28 -7
- package/hooks/HookCurrency.hook.ts +48 -1
- package/hooks/VerifyPhaseLock.hook.ts +68 -11
- package/hooks/WorkflowStateGuard.hook.ts +24 -7
- package/lib/ai-review-jury.ts +725 -0
- package/lib/ai-review-rounds.ts +1249 -0
- package/lib/ai-review-unmeasured.ts +361 -0
- package/lib/bash-file-read.ts +17 -3
- package/lib/bash-write-guard.ts +2165 -51
- package/lib/cli-commands.ts +252 -11
- package/lib/closing-reference-audit.ts +163 -0
- package/lib/conformity.ts +12 -0
- package/lib/create-sc.ts +45 -12
- package/lib/derived-spec.ts +206 -0
- package/lib/distribution-standing.ts +75 -4
- package/lib/failure-intake.ts +12 -4
- package/lib/file-claims.ts +335 -0
- package/lib/file-extensions.ts +81 -0
- package/lib/finding-arbiter.ts +1489 -0
- package/lib/finding-jury.ts +584 -0
- package/lib/finding-pr-routing.ts +333 -0
- package/lib/frontmatter.ts +16 -0
- package/lib/gate-check-audit.ts +259 -0
- package/lib/generators/agents-md.ts +29 -0
- package/lib/github.ts +160 -0
- package/lib/hook-tree-currency.ts +494 -0
- package/lib/interpreters.ts +64 -0
- package/lib/issue-closure-audit.ts +161 -14
- package/lib/issue-create-override.ts +122 -11
- package/lib/issue-filing-gate.ts +1602 -0
- package/lib/local-review-rounds.ts +523 -0
- package/lib/organize.ts +10 -0
- package/lib/project-state-shape.ts +56 -5
- package/lib/publish-window.ts +287 -0
- package/lib/repo-path.ts +94 -0
- package/lib/report-provenance.ts +65 -3
- package/lib/risk-tier.ts +302 -0
- package/lib/rounds-to-pass.ts +274 -0
- package/lib/rule-row-drift.ts +199 -0
- package/lib/sc-claim-forms.ts +33 -5
- package/lib/sc-guard.ts +11 -1
- package/lib/sc-id-cross-tree.ts +17 -2
- package/lib/sc-ids.ts +71 -6
- package/lib/sc-reservations.ts +158 -14
- package/lib/scaffold/ai-review-findings.ts +1157 -18
- package/lib/scaffold/ai-review-step.ts +4672 -85
- package/lib/scaffold/ai-review-unmeasured-workflow.ts +243 -0
- package/lib/scaffold/managed-workflow.ts +163 -4
- package/lib/scaffold/owned-files.ts +14 -0
- package/lib/scaffold/steps.ts +462 -108
- package/lib/scanner.ts +10 -3
- package/lib/scratch-roots.ts +93 -3
- package/lib/spec-updater.ts +16 -0
- package/lib/ticked-sc-symbols.ts +361 -0
- package/lib/validators/spec-validators.ts +28 -2
- package/lib/workflow-actions.ts +18 -0
- package/package.json +3 -1
- package/scripts/ai-review-findings.ts +41 -1
- package/scripts/arbitrate-finding.ts +542 -0
- package/scripts/audit-specs.ts +225 -23
- package/scripts/create-sc.ts +11 -0
- package/scripts/detect-sc-drift.ts +10 -2
- package/scripts/generate-code-map.ts +6 -3
- package/scripts/record-ai-review-unmeasured.ts +370 -0
- package/scripts/split-spec.ts +12 -0
- package/scripts/sync-sc-status.ts +93 -8
package/lib/bash-write-guard.ts
CHANGED
|
@@ -47,8 +47,50 @@
|
|
|
47
47
|
* Using `stripQuoted` for both would let an attacker quote the path; using
|
|
48
48
|
* `dequote` for both reinstates all four false positives. Each test below
|
|
49
49
|
* names which one it uses and why.
|
|
50
|
+
*
|
|
51
|
+
* ## The names are global; the artifacts are not (#1175)
|
|
52
|
+
*
|
|
53
|
+
* `PROTECTED_FILES` is a list of NAMES, and until #1175 a name matched in any
|
|
54
|
+
* tree. A fixture at `/tmp/rg-abc/workflow-state.json` was refused as readily
|
|
55
|
+
* as a live run's state, which is a true positive against the rule and a false
|
|
56
|
+
* positive against intent — agents on this repo build such fixtures
|
|
57
|
+
* constantly, including fixtures for this module.
|
|
58
|
+
*
|
|
59
|
+
* The scoping is by SCRATCH TREE rather than by project root, and that is a
|
|
60
|
+
* measurement and not a preference. #1175's acceptance asked for "the path
|
|
61
|
+
* relative to the project root". Swept over 5,531 real commands, the gate
|
|
62
|
+
* artifacts named in them resolve like this:
|
|
63
|
+
*
|
|
64
|
+
* 2,620 under the run store (`$RUNGATE_WORK_DIR`, i.e. `~/.rungate`)
|
|
65
|
+
* 521 under a former run store (`~/.pai-work`) or `~/.claude`
|
|
66
|
+
* 1,724 no resolvable path at all — a bare basename, or built by `join`
|
|
67
|
+
* 83 under an OS temp root
|
|
68
|
+
* 65 relative
|
|
69
|
+
* 16 under a repository tree
|
|
70
|
+
*
|
|
71
|
+
* A live `workflow-state.json` is almost never inside the project root: it is
|
|
72
|
+
* in the run store, one level up and sideways. "Protect what is under the
|
|
73
|
+
* root" would therefore have stopped protecting 3,141 of 3,240 absolute
|
|
74
|
+
* references — reopening `pai-config#473` C1, the forge-a-gate-result attack
|
|
75
|
+
* this guard was built for. The root-relative reading is recorded here as
|
|
76
|
+
* MEASURED WRONG rather than merely not chosen.
|
|
77
|
+
*
|
|
78
|
+
* So the question asked is the fail-closed one: can this path be shown to be
|
|
79
|
+
* in a scratch tree? Only then is it a fixture. Every other answer —
|
|
80
|
+
* elsewhere, relative, or not a path at all — keeps the old refusal. An
|
|
81
|
+
* allowlist is normally the wrong shape here and `pai-config#474`'s
|
|
82
|
+
* read-only-prefix list is why: a PREFIX says nothing about what a command
|
|
83
|
+
* writes. A scratch root says something about the DESTINATION, is consulted
|
|
84
|
+
* only after the destination has been extracted, and is not a judgement call
|
|
85
|
+
* — each entry is a value `mktemp -d` returns on a supported platform.
|
|
86
|
+
* Narrowing it over-blocks; it cannot open a hole.
|
|
50
87
|
*/
|
|
51
88
|
|
|
89
|
+
import { realpathSync, statSync } from 'fs';
|
|
90
|
+
import { tmpdir } from 'os';
|
|
91
|
+
import { basename, dirname, join, resolve } from 'path';
|
|
92
|
+
import { isInterpreterWord, isShellWord } from './interpreters';
|
|
93
|
+
|
|
52
94
|
/** Gate artifacts. A write to any of these must come from the gate runner. */
|
|
53
95
|
export const PROTECTED_FILES = ['workflow-state.json', '.gate-salt', '/witnesses/'];
|
|
54
96
|
|
|
@@ -62,6 +104,595 @@ export interface BashWriteDecision {
|
|
|
62
104
|
|
|
63
105
|
const ALLOW: BashWriteDecision = { blocked: false };
|
|
64
106
|
|
|
107
|
+
/**
|
|
108
|
+
* The trees an OS temporary directory can be in.
|
|
109
|
+
*
|
|
110
|
+
* `/tmp` and `/private/tmp` are both listed because on macOS they are the
|
|
111
|
+
* same directory under two names and a command may spell either; `resolve()`
|
|
112
|
+
* normalises `..` but does not follow links, and the link cannot be followed
|
|
113
|
+
* here because the path being judged usually does not exist yet — it is about
|
|
114
|
+
* to be created. `/var/folders` is where macOS puts a per-user `$TMPDIR`, and
|
|
115
|
+
* `tmpdir()` covers whatever the platform or the environment says, which is
|
|
116
|
+
* what `mkdtemp`, `mkstemp` and `mktemp -d` all build on.
|
|
117
|
+
*
|
|
118
|
+
* Each root is also recorded in its REALPATH form. On macOS `/var` is a
|
|
119
|
+
* symlink to `/private/var`, so `tmpdir()` hands back `/var/folders/…/T`
|
|
120
|
+
* while the resolution below hands back `/private/var/folders/…/T`, and a
|
|
121
|
+
* list holding only the first form answers `false` for every path spelled
|
|
122
|
+
* the way `mkdtemp` hands it to a program.
|
|
123
|
+
*
|
|
124
|
+
* The corpus does NOT show this, and saying so is the point: real commands
|
|
125
|
+
* spell `/tmp` literally, so all 37 fixture commands clear either way. It
|
|
126
|
+
* was found by `isScratchPath, asserted directly` calling `tmpdir()`, which
|
|
127
|
+
* is what a program does and what a person does not. A sweep over what
|
|
128
|
+
* people typed cannot see a defect in what their programs compute.
|
|
129
|
+
*
|
|
130
|
+
* Read at call time rather than frozen at import, because `TMPDIR` is what a
|
|
131
|
+
* test harness moves when it wants its own scratch space, and a guard that
|
|
132
|
+
* cached the old value would refuse the new one.
|
|
133
|
+
*
|
|
134
|
+
* ## `TMPDIR` is the writer's variable, so it is not trusted
|
|
135
|
+
*
|
|
136
|
+
* The first version of this took `process.env.TMPDIR` as given. Measured:
|
|
137
|
+
*
|
|
138
|
+
* TMPDIR unset isScratchPath(…/.rungate/x/…) = false
|
|
139
|
+
* TMPDIR=$HOME/.rungate = true
|
|
140
|
+
*
|
|
141
|
+
* The agent whose write is being judged sets the variable that decides
|
|
142
|
+
* whether the write is exempt, and pointing it at the run store switches the
|
|
143
|
+
* guard off for the one directory it exists to protect. `tmpdir()` is the
|
|
144
|
+
* same hole wearing a function call — on POSIX it READS `TMPDIR`.
|
|
145
|
+
*
|
|
146
|
+
* So `FIXED` is the whole of the trust, and the environment can only ever
|
|
147
|
+
* SELECT within it: a `TMPDIR` that does not already resolve inside a fixed
|
|
148
|
+
* root is dropped. A platform whose temp directory is somewhere else
|
|
149
|
+
* over-blocks, which is the direction this module is allowed to be wrong in.
|
|
150
|
+
*/
|
|
151
|
+
const FIXED_SCRATCH_ROOTS = ['/tmp', '/private/tmp', '/var/folders'];
|
|
152
|
+
|
|
153
|
+
/**
|
|
154
|
+
* Trees that hold LIVE artifacts, wherever on the disk they are.
|
|
155
|
+
*
|
|
156
|
+
* This is SUBTRACTED from the exemption in `isScratchPath`, not merely used
|
|
157
|
+
* to vet the root list. The difference matters: vetting roots is a proxy for
|
|
158
|
+
* the property, and it only holds for roots somebody thought of. Subtracting
|
|
159
|
+
* the trees themselves IS the property — "a live artifact is never exempt" —
|
|
160
|
+
* and it keeps holding when a root is added later by someone who has not
|
|
161
|
+
* read this comment.
|
|
162
|
+
*
|
|
163
|
+
* The two mechanisms are also not interchangeable, and conflating them was
|
|
164
|
+
* measured. Dropping a ROOT because it contains a protected tree removes
|
|
165
|
+
* `/tmp` wholesale the moment `RUNGATE_WORK_DIR` points inside it — which a
|
|
166
|
+
* real corpus command does — and refuses every fixture on the machine.
|
|
167
|
+
* Subtracting the TREE removes only that subtree and leaves the rest of
|
|
168
|
+
* `/tmp` exempt. So the root list is vetted only against trees that are not
|
|
169
|
+
* themselves scratch, and the subtraction below applies unconditionally.
|
|
170
|
+
*
|
|
171
|
+
* ## The hook directories are here because a checkout CAN be the live hook
|
|
172
|
+
*
|
|
173
|
+
* A review argued that `PROTECTED_HOOKS` should lose the scratch exemption
|
|
174
|
+
* entirely, on the grounds that a `.hook.ts` under `/tmp` is as likely to be
|
|
175
|
+
* a real checkout as a fixture — worktrees under `/tmp` are routine here.
|
|
176
|
+
* The counter-argument offered was that a hook source in a checkout is not
|
|
177
|
+
* the live hook, so compromising one does nothing until it is deployed.
|
|
178
|
+
*
|
|
179
|
+
* That counter-argument is FALSE on this machine, and `lib/hook-target-tree.ts`
|
|
180
|
+
* is where it was measured: every registration in `~/.claude/settings.json`
|
|
181
|
+
* is spelled `${PAI_HOOKS_DIR}/…` or `${RUNGATE_HOOKS_DIR}/…`, and
|
|
182
|
+
* `RUNGATE_HOOKS_DIR` resolved to *a checkout that is not this one*, with
|
|
183
|
+
* fourteen hooks executing from it. #999's shell-injection fix never reached
|
|
184
|
+
* the bytes that run. A checkout is the live hook exactly when a variable
|
|
185
|
+
* says it is.
|
|
186
|
+
*
|
|
187
|
+
* So the answer is neither "refuse the exemption for hooks" nor "trust the
|
|
188
|
+
* checkout": resolve where the registrations actually point and subtract
|
|
189
|
+
* THAT, wherever it is — including when it is under `/tmp`. A hook in a
|
|
190
|
+
* worktree nothing registers stays a fixture, which is the case #1175 exists
|
|
191
|
+
* for; a hook in the tree that is actually wired stays protected, which is
|
|
192
|
+
* the case the review was worried about.
|
|
193
|
+
*
|
|
194
|
+
* `process.cwd()` is deliberately NOT here, and the reason is measured. A
|
|
195
|
+
* checkout under `/tmp` is ordinary on this machine — the worktree this was
|
|
196
|
+
* written in is `/private/tmp/rg-1175-wt` — so treating the working
|
|
197
|
+
* directory as protected drops `/private/tmp` from the roots, and because
|
|
198
|
+
* `/tmp` realpaths to it the walk then refuses every `/tmp` path as well.
|
|
199
|
+
* 12 of 145 tests red, measured.
|
|
200
|
+
*
|
|
201
|
+
* ## BOTH spellings, which #1175 got wrong
|
|
202
|
+
*
|
|
203
|
+
* `resolve()` normalises `.` and `..`; it does not follow a symlink. So a
|
|
204
|
+
* tree named `/tmp/e2e` stayed in this list as `/tmp/e2e` while a path
|
|
205
|
+
* through the same inode reads `/private/tmp/e2e/…`, and `inAnyTree`
|
|
206
|
+
* matches neither spelling against the other. Executed against the module
|
|
207
|
+
* as merged, with `RUNGATE_WORK_DIR=/tmp/e2e`:
|
|
208
|
+
*
|
|
209
|
+
* /tmp/e2e/s/workflow-state.json blocked
|
|
210
|
+
* /private/tmp/e2e/s/workflow-state.json ALLOWED ← the run store
|
|
211
|
+
*
|
|
212
|
+
* The same for `RUNGATE_HOOKS_DIR`, and `/tmp` is a symlink to
|
|
213
|
+
* `/private/tmp` on every macOS install, so the second spelling is not
|
|
214
|
+
* exotic — it is what `realpath` prints.
|
|
215
|
+
*
|
|
216
|
+
* `scratchRoots()` below already recorded both spellings for the fixed
|
|
217
|
+
* roots, so the asymmetry was inside one file: the roots a write may land
|
|
218
|
+
* in were realpathed and the trees it may not were not. A `catch` here
|
|
219
|
+
* means the tree is not on disk, which is ordinary for a variable pointing
|
|
220
|
+
* at a directory the command is about to create, and the resolved spelling
|
|
221
|
+
* stands on its own.
|
|
222
|
+
*/
|
|
223
|
+
function protectedTrees(): string[] {
|
|
224
|
+
const home = process.env.HOME || '';
|
|
225
|
+
const spellings: string[] = [];
|
|
226
|
+
for (const p of [
|
|
227
|
+
// The run store — where 2,620 of 3,240 absolute artifact references live.
|
|
228
|
+
process.env.RUNGATE_WORK_DIR || '',
|
|
229
|
+
home ? join(home, '.rungate') : '',
|
|
230
|
+
home ? join(home, '.claude') : '',
|
|
231
|
+
// The trees a hook registration resolves to. Read from the environment
|
|
232
|
+
// because that is what the registrations are spelled with.
|
|
233
|
+
process.env.PAI_HOOKS_DIR || '',
|
|
234
|
+
process.env.RUNGATE_HOOKS_DIR || '',
|
|
235
|
+
home ? join(home, '.pai', 'hooks') : '',
|
|
236
|
+
].filter(Boolean)) {
|
|
237
|
+
const normalised = resolve(p);
|
|
238
|
+
spellings.push(normalised);
|
|
239
|
+
try {
|
|
240
|
+
const real = realpathSync(normalised);
|
|
241
|
+
if (real !== normalised) spellings.push(real);
|
|
242
|
+
} catch {
|
|
243
|
+
// Not on disk. The resolved spelling above still stands.
|
|
244
|
+
}
|
|
245
|
+
}
|
|
246
|
+
return spellings;
|
|
247
|
+
}
|
|
248
|
+
|
|
249
|
+
/** Is `p` inside, or equal to, any of `trees`? */
|
|
250
|
+
function inAnyTree(p: string, trees: string[]): boolean {
|
|
251
|
+
return trees.some(t => p === t || p.startsWith(t + '/'));
|
|
252
|
+
}
|
|
253
|
+
|
|
254
|
+
function scratchRoots(): string[] {
|
|
255
|
+
const out: string[] = [];
|
|
256
|
+
const contains = (root: string, p: string) => p === root || p.startsWith(root + '/');
|
|
257
|
+
|
|
258
|
+
const fixed: string[] = [];
|
|
259
|
+
for (const r of FIXED_SCRATCH_ROOTS) {
|
|
260
|
+
const n = resolve(r);
|
|
261
|
+
fixed.push(n);
|
|
262
|
+
try {
|
|
263
|
+
fixed.push(realpathSync(n));
|
|
264
|
+
} catch {
|
|
265
|
+
// A root that is not on this disk is still a name a command can spell.
|
|
266
|
+
}
|
|
267
|
+
}
|
|
268
|
+
|
|
269
|
+
// A protected tree that is ITSELF inside a fixed scratch root is not a
|
|
270
|
+
// reason to drop that root. `RUNGATE_WORK_DIR=/tmp/e2e-gate-test` is a real
|
|
271
|
+
// corpus command — a harness deliberately putting the run store in scratch
|
|
272
|
+
// for a test — and without this clause it drops `/tmp` and refuses every
|
|
273
|
+
// fixture on the machine, which is the same self-defeat `process.cwd()`
|
|
274
|
+
// caused. Measured: `isScratchPath('/tmp/p/x')` goes false under that one
|
|
275
|
+
// environment variable.
|
|
276
|
+
const guarded = protectedTrees().filter(t => !fixed.some(f => contains(f, t)));
|
|
277
|
+
const add = (p: string) => {
|
|
278
|
+
if (p === '/' || out.includes(p)) return;
|
|
279
|
+
// The invariant, enforced rather than documented: an exemption root that
|
|
280
|
+
// contains a protected tree is not an exemption root.
|
|
281
|
+
if (guarded.some(t => contains(p, t))) return;
|
|
282
|
+
out.push(p);
|
|
283
|
+
};
|
|
284
|
+
|
|
285
|
+
for (const f of fixed) add(f);
|
|
286
|
+
|
|
287
|
+
// The environment SELECTS within the fixed set; it cannot extend it.
|
|
288
|
+
for (const r of [tmpdir(), process.env.TMPDIR ?? '']) {
|
|
289
|
+
if (!r || !r.startsWith('/')) continue;
|
|
290
|
+
const n = resolve(r);
|
|
291
|
+
let real = n;
|
|
292
|
+
try {
|
|
293
|
+
real = realpathSync(n);
|
|
294
|
+
} catch {
|
|
295
|
+
/* not on this disk; judge the spelling */
|
|
296
|
+
}
|
|
297
|
+
if (!fixed.some(f => contains(f, n) || contains(f, real))) continue;
|
|
298
|
+
add(n);
|
|
299
|
+
add(real);
|
|
300
|
+
}
|
|
301
|
+
return out;
|
|
302
|
+
}
|
|
303
|
+
|
|
304
|
+
/**
|
|
305
|
+
* Is this path demonstrably inside a scratch tree?
|
|
306
|
+
*
|
|
307
|
+
* Only an ABSOLUTE path can be placed in a tree, so everything else — a bare
|
|
308
|
+
* basename, a relative path, a `join(dir, "workflow-state.json")` whose `dir`
|
|
309
|
+
* lives in a variable — answers `false` and stays refused. That is the whole
|
|
310
|
+
* fail-closed property: this function's job is to say YES, and silence means
|
|
311
|
+
* the old behaviour.
|
|
312
|
+
*
|
|
313
|
+
* `resolve()` first, per #1129: a destination spelled `/tmp/../Users/me/
|
|
314
|
+
* .rungate/x/workflow-state.json` is not in `/tmp`, and comparing the
|
|
315
|
+
* unnormalised string would say it is.
|
|
316
|
+
*
|
|
317
|
+
* The deepest EXISTING ancestor is then realpath'd, which is the half
|
|
318
|
+
* `resolve()` cannot do. Without it, `ln -s ~/.rungate/slug /tmp/esc` followed
|
|
319
|
+
* by a write to `/tmp/esc/workflow-state.json` is a two-command bypass of the
|
|
320
|
+
* thing this guard protects. The stat happens only after a protected NAME has
|
|
321
|
+
* already matched, so the common command pays nothing for it.
|
|
322
|
+
*
|
|
323
|
+
* It does NOT close the case where the link is made by the SAME command —
|
|
324
|
+
* see `exemptionIsVoid`, which is where that is handled, because the answer
|
|
325
|
+
* is a property of the command and not of the path.
|
|
326
|
+
*
|
|
327
|
+
* An UNEXPANDED expansion is refused. `/tmp/$X/workflow-state.json` is not a
|
|
328
|
+
* path, it is a path the shell will build, and `$X` may be `../../Users/me/
|
|
329
|
+
* .rungate/slug`. Five of the six spellings a review raised were already
|
|
330
|
+
* refused by `resolve()` and the `startsWith('/')` precondition — `${X}`, the
|
|
331
|
+
* backtick form, `/tmp/../…`, `$HOME/…` and `~/…` — and this is the sixth.
|
|
332
|
+
* Measured cost of refusing it: 0 of the 37 commands this branch clears, with
|
|
333
|
+
* 209 corpus-wide carrying a `$` in an artifact path, none of them in the
|
|
334
|
+
* population at stake.
|
|
335
|
+
*
|
|
336
|
+
* Both exits below return `false`. They are all but unreachable — the
|
|
337
|
+
* deepest artifact path in the corpus is 6 components against a cap of 64,
|
|
338
|
+
* and the walk only runs out of parents if `realpathSync('/')` throws — but
|
|
339
|
+
* an unreachable fail-OPEN in a fail-closed module is a line that reads as
|
|
340
|
+
* permission, and the next person to make the walk reachable inherits it.
|
|
341
|
+
*/
|
|
342
|
+
|
|
343
|
+
/**
|
|
344
|
+
* Glob and brace metacharacters, tested against the DIRECTORY part only.
|
|
345
|
+
*
|
|
346
|
+
* `echo '{}' > /tmp/sym*/workflow-state.json`, with `/tmp/syma` a symlink
|
|
347
|
+
* into the run store: `/tmp/sym*` does not exist, the walk climbs past it to
|
|
348
|
+
* `/tmp`, and the path is exempted — then the shell expands the glob and the
|
|
349
|
+
* write goes through the link. Same escape as the symlink case with no `ln`
|
|
350
|
+
* in the command for `exemptionIsVoid` to see.
|
|
351
|
+
*
|
|
352
|
+
* Only the directory part is tested, and that is measured rather than
|
|
353
|
+
* cautious. A glob in the BASENAME is already safe, because the directory
|
|
354
|
+
* above it is the thing `resolveThroughLinks` resolves — built and executed:
|
|
355
|
+
* with `SRC/syma` linked out of scratch, `SRC/syma/*.json` answers false and
|
|
356
|
+
* `SRC/sym*/x` answered true. So the basename case needs no refusal, and
|
|
357
|
+
* refusing it anyway costs a real command: `rm -f /tmp/713-battery/
|
|
358
|
+
* pai-wrongfix/*.hook.ts` is 1 of the 37 this branch clears, and a blanket
|
|
359
|
+
* metacharacter class takes it back. Restricting the test to the directory
|
|
360
|
+
* part closes the escape at a measured cost of 0.
|
|
361
|
+
*
|
|
362
|
+
* The exact class a review proposed, `[$`*?[]{}~]` tested against the whole
|
|
363
|
+
* path, was swept over the same 5,573-command corpus: it takes back 1 of the
|
|
364
|
+
* 37, that `rm -f`. It does not ship on caution either way — it ships on the
|
|
365
|
+
* reading, and the reading is 1 against 0.
|
|
366
|
+
*/
|
|
367
|
+
const UNRESOLVED_DIR = /[*?[\]{}]/;
|
|
368
|
+
export function isScratchPath(path: string): boolean {
|
|
369
|
+
if (!path || !path.startsWith('/')) return false;
|
|
370
|
+
if (/[$`]/.test(path)) return false;
|
|
371
|
+
// A glob in a DIRECTORY component is unresolvable and escapes; one in the
|
|
372
|
+
// basename does not. See `UNRESOLVED_DIR` for the measurement.
|
|
373
|
+
if (UNRESOLVED_DIR.test(dirname(path))) return false;
|
|
374
|
+
|
|
375
|
+
const normalised = resolve(path);
|
|
376
|
+
const real = resolveThroughLinks(normalised);
|
|
377
|
+
if (real === null) return false;
|
|
378
|
+
|
|
379
|
+
// The subtraction, applied to BOTH the spelling and the resolved path. A
|
|
380
|
+
// live artifact is never exempt, whichever of the two names it.
|
|
381
|
+
const live = protectedTrees();
|
|
382
|
+
if (inAnyTree(normalised, live) || inAnyTree(real, live)) return false;
|
|
383
|
+
|
|
384
|
+
const roots = scratchRoots();
|
|
385
|
+
return inAnyTree(normalised, roots) && inAnyTree(real, roots);
|
|
386
|
+
}
|
|
387
|
+
|
|
388
|
+
/**
|
|
389
|
+
* The path with its deepest EXISTING ancestor resolved through symlinks, and
|
|
390
|
+
* the not-yet-created tail re-attached. `null` when nothing in the chain can
|
|
391
|
+
* be resolved — which is the fail-closed answer, not a missing one.
|
|
392
|
+
*/
|
|
393
|
+
function resolveThroughLinks(normalised: string): string | null {
|
|
394
|
+
let dir = normalised;
|
|
395
|
+
let suffix = '';
|
|
396
|
+
for (let i = 0; i < 64; i++) {
|
|
397
|
+
try {
|
|
398
|
+
const real = realpathSync(dir);
|
|
399
|
+
return suffix ? resolve(real, suffix) : real;
|
|
400
|
+
} catch {
|
|
401
|
+
const parent = dirname(dir);
|
|
402
|
+
if (parent === dir) return null;
|
|
403
|
+
suffix = suffix ? join(basename(dir), suffix) : basename(dir);
|
|
404
|
+
dir = parent;
|
|
405
|
+
}
|
|
406
|
+
}
|
|
407
|
+
return null;
|
|
408
|
+
}
|
|
409
|
+
|
|
410
|
+
/**
|
|
411
|
+
* Does this command do something that makes a resolved path untrustworthy?
|
|
412
|
+
*
|
|
413
|
+
* `isScratchPath` resolves the destination's existing ancestors at DECISION
|
|
414
|
+
* time. A command that creates a symbolic link before it writes invalidates
|
|
415
|
+
* that resolution between the decision and the execution, and the whole
|
|
416
|
+
* thing fits in one command:
|
|
417
|
+
*
|
|
418
|
+
* ln -s ~/.rungate/victim /tmp/esc && echo '{}' > /tmp/esc/workflow-state.json
|
|
419
|
+
*
|
|
420
|
+
* At decision time `/tmp/esc` does not exist, the walk reaches `/tmp`, and
|
|
421
|
+
* the write is exempted. Then the shell creates the link and the write lands
|
|
422
|
+
* in the run store. Both halves were executed: the module allowed the
|
|
423
|
+
* command, and a real shell put the bytes through the link. This is a
|
|
424
|
+
* bypass, not a race — no second actor is required.
|
|
425
|
+
*
|
|
426
|
+
* `mkdir -p` is the overwhelmingly common thing a fixture does to a path that
|
|
427
|
+
* does not exist yet, and a directory cannot point out of its tree. Only a
|
|
428
|
+
* LINK can, so only link creation voids the exemption. Measured: 0 of the 37
|
|
429
|
+
* commands this branch clears create one, and 9 commands in the whole 5,550
|
|
430
|
+
* corpus match at all.
|
|
431
|
+
*
|
|
432
|
+
* ## The verb is resolved, not pattern-matched
|
|
433
|
+
*
|
|
434
|
+
* The first version tested `/(?:^|[\s;&|(])ln\s/` against the raw command,
|
|
435
|
+
* which requires whitespace or a separator immediately before `ln`. Measured:
|
|
436
|
+
* `ln -s`, `sudo ln` and `find -exec ln` voided, but **`/bin/ln -s … /tmp/x`
|
|
437
|
+
* and `\ln -s … /tmp/x` did not** — two spellings the shell resolves
|
|
438
|
+
* identically to the one that did, walking past the control the whole
|
|
439
|
+
* exemption rests on.
|
|
440
|
+
*
|
|
441
|
+
* `commandWord` already strips a leading path and a leading `\` or `(`, and
|
|
442
|
+
* already skips `sudo`, `env`, `xargs` and the other wrappers, because
|
|
443
|
+
* #1120 and #1184 taught it to. Running it per segment is one tokeniser
|
|
444
|
+
* instead of two and gets all of that for free, so the segment's resolved
|
|
445
|
+
* VERB is the primary test.
|
|
446
|
+
*
|
|
447
|
+
* `LINK_CREATION` stays as a second, broader net for the positions a command
|
|
448
|
+
* word cannot reach: `find . -exec ln …` resolves to `find`, and
|
|
449
|
+
* `symlinkSync` lives inside an interpreter body this module does not parse.
|
|
450
|
+
* It is read off the raw command for that reason — the link and the write
|
|
451
|
+
* are in different segments by construction.
|
|
452
|
+
*
|
|
453
|
+
* `mkdir -p` is the overwhelmingly common thing a fixture does to a path that
|
|
454
|
+
* does not exist yet, and a directory cannot point out of its tree. Only a
|
|
455
|
+
* LINK can, so only link creation voids the exemption. Measured: 0 of the 37
|
|
456
|
+
* commands this branch clears create one.
|
|
457
|
+
*/
|
|
458
|
+
const LINK_CREATION = /\bln\s|\bsymlinkSync\b|\bos\.symlink\b|\bsymlink\s*\(/;
|
|
459
|
+
|
|
460
|
+
/**
|
|
461
|
+
* `ln` is not the only verb that makes a link (#1411, raised as a CRITICAL
|
|
462
|
+
* by the review on #1354).
|
|
463
|
+
*
|
|
464
|
+
* GNU and BSD `cp` create links on request and spell none of
|
|
465
|
+
* `LINK_CREATION`'s four alternatives, so every one of these was ALLOWED —
|
|
466
|
+
* the bypass in the docblock above, reachable by a different verb:
|
|
467
|
+
*
|
|
468
|
+
* cp -s ~/.rungate/victim /tmp/esc && echo '{}' > /tmp/esc/workflow-state.json
|
|
469
|
+
*
|
|
470
|
+
* Measured before the fix, all allowed: `cp -s`, `cp --symbolic-link`,
|
|
471
|
+
* `cp -l`, `cp --link`, `cp -rs`, `cp -as`, `cp -sv`, `/bin/cp -s`,
|
|
472
|
+
* `sudo cp -s`, `install -l s`. `-l` belongs with `-s`: a hard link to a
|
|
473
|
+
* file inside the run store aims a later write at the victim's inode just
|
|
474
|
+
* as a symlink aims it at the victim's path.
|
|
475
|
+
*
|
|
476
|
+
* ## The FAMILY, not the spelling
|
|
477
|
+
*
|
|
478
|
+
* A test for the literal `cp -s` is the cheapest wrong fix — seven of the
|
|
479
|
+
* ten rows above walk around it. So the reading is token-level: a short
|
|
480
|
+
* cluster is any `-…` containing a lower-case `s` or `l`, which is what
|
|
481
|
+
* makes `-rs`, `-as` and `-sv` fall out of one rule rather than three; a
|
|
482
|
+
* long option is matched by PREFIX, because GNU accepts any unambiguous
|
|
483
|
+
* abbreviation and `--sym` is as real as `--symbolic-link`.
|
|
484
|
+
*
|
|
485
|
+
* Case matters: `cp -L` dereferences links in the SOURCE and creates none,
|
|
486
|
+
* so only the lower-case letters count. `cp -r`, `cp -p`, `cp -a` and
|
|
487
|
+
* `mkdir -p` are CONTROL rows and must stay exempt.
|
|
488
|
+
*
|
|
489
|
+
* The scan is position-independent rather than keyed to the resolved verb,
|
|
490
|
+
* so `find . -exec cp -s …` is covered — the same position `LINK_CREATION`
|
|
491
|
+
* exists to reach for `ln`, where `commandWord` resolves to `find`.
|
|
492
|
+
*
|
|
493
|
+
* ## And the `ln` boundary, since it was asked
|
|
494
|
+
*
|
|
495
|
+
* `\bln\s` needs a following character, so it misses an `ln` that ends a
|
|
496
|
+
* segment. Measured over five spellings: the regex misses four, and the
|
|
497
|
+
* segment-verb net catches three of those four (`ln`, `echo x && ln`,
|
|
498
|
+
* `sudo ln`). The one neither catches is `find . -exec ln` with no
|
|
499
|
+
* terminator, which `find(1)` refuses — "the expression must be terminated
|
|
500
|
+
* by a semicolon" — so it is a syntax error, not a bypass. Count: ONE
|
|
501
|
+
* spelling missed by both nets, ZERO executable. No change made.
|
|
502
|
+
*
|
|
503
|
+
* ## The FOUR transforms a shell applies before `cp` sees a flag
|
|
504
|
+
*
|
|
505
|
+
* Every bypass found in this family so far has been the same question asked
|
|
506
|
+
* about a different transform, and each was rediscovered separately because
|
|
507
|
+
* nothing wrote the list down. There are three, and a reading of a token is
|
|
508
|
+
* only correct if it survives all of them:
|
|
509
|
+
*
|
|
510
|
+
* | transform | what the shell does | where this module does it |
|
|
511
|
+
* |---|---|---|
|
|
512
|
+
* | quote removal | `'-s'`, `"-s"`, `-'s'`, `c""p` all arrive bare | `readWord`, via `scanSegment` (#1429) |
|
|
513
|
+
* | escape removal | `-\s`, `-r\s`, `-\-symbolic-link`, `--sy\mbolic-link` arrive as `-s`, `-rs`, `--symbolic-link` | `isLinkFlag`, before EITHER branch |
|
|
514
|
+
* | substitution grouping | `` `…` `` and `$(…)` hand their text to ANOTHER shell, and `$(…)` nests | `nestedCommands` |
|
|
515
|
+
* | ANSI-C quoting | `$'-s'` is the word `-s`, and `$'-\163'` is too | `readWord`, via `decodeAnsiC` |
|
|
516
|
+
*
|
|
517
|
+
* Measured against `/bin/bash` rather than assumed: `printf '[%s]' -\s -\l
|
|
518
|
+
* -r\s -\-symbolic-link --sy\mbolic-link $'-s' $'-\163' $'cp'` prints
|
|
519
|
+
* `[-s][-l][-rs][--symbolic-link][--symbolic-link][-s][-s][cp]`. Every one
|
|
520
|
+
* of those was ALLOWED before its transform was read, as were
|
|
521
|
+
* `` `cp -s …` ``, ``eval `cp -s …` ``, a `$(…)` containing a second
|
|
522
|
+
* `$(…)`, and a `$(…)` wrapping a parenthesised subshell.
|
|
523
|
+
*
|
|
524
|
+
* The fourth arrived the way the second and third did — a review round
|
|
525
|
+
* after the table said three — which is the argument for the table rather
|
|
526
|
+
* than against it. If a fifth turns up, add the row. The point is that the
|
|
527
|
+
* next reader checks all of them at once instead of finding them one review
|
|
528
|
+
* at a time.
|
|
529
|
+
*
|
|
530
|
+
* ANSI-C is the one that hides a VERB as well as a flag: `$'cp' -s` leaves
|
|
531
|
+
* `verbToken` nothing to match, so it is read in `readWord` — the module's
|
|
532
|
+
* one quote reader — rather than in `isLinkFlag`, which a hidden verb never
|
|
533
|
+
* reaches. Unlike the other substitution syntaxes it is settled at parse
|
|
534
|
+
* time, so decoding it makes a word more readable rather than guessing at
|
|
535
|
+
* one, and an unexpanded `$(…)` goes on reading as unprovable.
|
|
536
|
+
*/
|
|
537
|
+
const LINK_VERBS = new Set(['cp', 'install']);
|
|
538
|
+
|
|
539
|
+
/** A token's verb name: `/bin/cp` and `\cp` are both `cp`. */
|
|
540
|
+
function verbToken(token: string): string {
|
|
541
|
+
const bare = token.replace(/^[\\(]+/, '');
|
|
542
|
+
return bare.slice(bare.lastIndexOf('/') + 1);
|
|
543
|
+
}
|
|
544
|
+
|
|
545
|
+
function isLinkFlag(raw: string): boolean {
|
|
546
|
+
// ESCAPE REMOVAL, the second of the three transforms in the table above,
|
|
547
|
+
// and it governs BOTH branches below rather than only the short one.
|
|
548
|
+
// `cp -\s` reaches `cp` as `-s` and `cp --sy\mbolic-link` reaches it as
|
|
549
|
+
// `--symbolic-link`; against the raw token the letter run reads `''` and
|
|
550
|
+
// the long name fails its prefix test, so all five escaped spellings were
|
|
551
|
+
// measured ALLOWED.
|
|
552
|
+
//
|
|
553
|
+
// A backslash inside a QUOTED word is literal to the shell, and `readWord`
|
|
554
|
+
// has already removed the quotes by the time the token arrives, so this
|
|
555
|
+
// cannot tell `-\s` from `'-\s'` and treats both as `-s`. That is the
|
|
556
|
+
// fail-closed direction and it costs a token that `cp` itself rejects as
|
|
557
|
+
// an invalid option. The control that keeps it honest is an ordinary
|
|
558
|
+
// quoted filename containing a backslash, which carries no leading `-`
|
|
559
|
+
// and so never reaches either branch.
|
|
560
|
+
const token = raw.replace(/\\(.)/g, '$1');
|
|
561
|
+
if (token.startsWith('--')) {
|
|
562
|
+
const name = token.slice(2).split('=')[0];
|
|
563
|
+
if (!name) return false;
|
|
564
|
+
return 'symbolic-link'.startsWith(name) || 'link'.startsWith(name);
|
|
565
|
+
}
|
|
566
|
+
if (!token.startsWith('-') || token.length < 2) return false;
|
|
567
|
+
// A flag whose letters this module cannot read — `-$F`, `-${X}`, `-`+a
|
|
568
|
+
// substitution — is one it cannot rule OUT, and the verb is already known
|
|
569
|
+
// to make links on request. Same fail-closed shape as an unplaceable
|
|
570
|
+
// literal in `placeLiteral`: declining to clear is cheap and visible,
|
|
571
|
+
// clearing something unread is neither.
|
|
572
|
+
if (/[$`]/.test(token)) return true;
|
|
573
|
+
// The LEADING LETTER RUN, not the whole token. `cp -st/tmp/esc` bundles
|
|
574
|
+
// `-s` with `-t`'s attached argument and `cp -sS.bak` bundles it with
|
|
575
|
+
// `-S`'s, and an anchored `^-[A-Za-z]+$` rejected both on the `/` and the
|
|
576
|
+
// `.` without ever reading the `s`. Both were measured ALLOWED. The
|
|
577
|
+
// controls are the same bundles without the link letter — `-t/tmp/p` and
|
|
578
|
+
// `-S.bak` — which must stay exempt, and do.
|
|
579
|
+
//
|
|
580
|
+
// Lower case only: `-L` follows links in the SOURCE and creates none.
|
|
581
|
+
const letters = /^-([A-Za-z]*)/.exec(token)?.[1] ?? '';
|
|
582
|
+
return /[sl]/.test(letters);
|
|
583
|
+
}
|
|
584
|
+
|
|
585
|
+
/**
|
|
586
|
+
* The tokens come from `scanSegment`, the module's ONE quote-aware pass.
|
|
587
|
+
*
|
|
588
|
+
* The first spelling of this used `stripQuoted`, which deletes a quoted
|
|
589
|
+
* span's content rather than removing the quotes, and the #1429 review was
|
|
590
|
+
* right that it defeated the whole check: `cp '-s'`, `cp "-s"`, `"cp" -s`,
|
|
591
|
+
* `c""p -s` and `cp --'s'ymbolic-link` were all measured ALLOWED, each one
|
|
592
|
+
* a command the shell runs identically to the one that was refused.
|
|
593
|
+
*
|
|
594
|
+
* The second spelling was a tokeniser of my own, and that was the wrong
|
|
595
|
+
* repair even though it worked. `commandWord` already resolves `"cp"`
|
|
596
|
+
* correctly, through `scanSegment`, because #1184 and #1196 taught it to
|
|
597
|
+
* after `stripQuoted` deleted `"chmod"` outright. A second tokeniser beside
|
|
598
|
+
* it is two deciders answering one question — the fourth shape in
|
|
599
|
+
* `.claude/rules/checks-must-be-able-to-fail.md` — and a mutation of either
|
|
600
|
+
* leaves the other holding every case up. One tokeniser.
|
|
601
|
+
*/
|
|
602
|
+
function flagMakesLink(segment: string): boolean {
|
|
603
|
+
const words = scanSegment(segment).words;
|
|
604
|
+
if (!words.some(w => LINK_VERBS.has(verbToken(w)))) return false;
|
|
605
|
+
return words.some(isLinkFlag);
|
|
606
|
+
}
|
|
607
|
+
|
|
608
|
+
/**
|
|
609
|
+
* Text a segment will hand to ANOTHER shell: the contents of its quoted
|
|
610
|
+
* words and of its command substitutions (#1429).
|
|
611
|
+
*
|
|
612
|
+
* `ln` is caught inside `bash -c '…'`, `$( … )` and `eval '…'` today, but
|
|
613
|
+
* only because `LINK_CREATION` is a regex read off the raw text and a regex
|
|
614
|
+
* does not care about nesting. A reading built on segments and tokens does,
|
|
615
|
+
* and all four spellings of `cp -s` were measured ALLOWED while their `ln`
|
|
616
|
+
* twins were refused — so this is not a new hole, it is the old net's reach
|
|
617
|
+
* that the new one had to be given too.
|
|
618
|
+
*
|
|
619
|
+
* `interpreterPrograms` was the obvious place and is the wrong one: it
|
|
620
|
+
* reaches a heredoc body and returns NOTHING for `bash -c 'cp -s …'`,
|
|
621
|
+
* `sh -c "…"`, `$( … )` or `eval '…'` — measured, all four empty, against
|
|
622
|
+
* a heredoc control that returns the body. Widening it would change what
|
|
623
|
+
* every other arm reads. This is local to the void check.
|
|
624
|
+
*/
|
|
625
|
+
function nestedCommands(view: string): string[] {
|
|
626
|
+
const out: string[] = [];
|
|
627
|
+
for (const m of view.matchAll(/'([^']*)'|"([^"]*)"/g)) out.push(m[1] ?? m[2] ?? '');
|
|
628
|
+
// Backticks are the OTHER substitution syntax and were missing entirely:
|
|
629
|
+
// `` `cp -s …` `` and ``eval `cp -s …` `` were measured ALLOWED while
|
|
630
|
+
// their `ln` twins were refused, for the same reason the `$(…)` rows were
|
|
631
|
+
// — `LINK_CREATION` is a raw-text regex that does not care about nesting
|
|
632
|
+
// and this reading is built on segments. They do not nest in bash, so a
|
|
633
|
+
// flat match is the whole grammar here.
|
|
634
|
+
for (const m of view.matchAll(/`([^`]*)`/g)) out.push(m[1]);
|
|
635
|
+
// `$(…)` DOES nest, so it gets the module's one substitution walk rather
|
|
636
|
+
// than a second spelling of it. Every `$(` position is examined — the
|
|
637
|
+
// index is not advanced past a substitution that was just read — so an
|
|
638
|
+
// inner body is collected as well as the outer one it sits in.
|
|
639
|
+
for (let i = 0; i < view.length; i++) {
|
|
640
|
+
if (view[i] !== '$' || view[i + 1] !== '(') continue;
|
|
641
|
+
const end = endOfSubstitution(view, i);
|
|
642
|
+
const body = view.slice(i + 2, end);
|
|
643
|
+
out.push(body.endsWith(')') ? body.slice(0, -1) : body); // unterminated keeps all of it
|
|
644
|
+
}
|
|
645
|
+
return out.filter(s => /\s/.test(s));
|
|
646
|
+
}
|
|
647
|
+
|
|
648
|
+
/**
|
|
649
|
+
* #1240: both tests read a view that KEEPS the text an interpreter is going
|
|
650
|
+
* to run. `stripHeredocs` deletes a heredoc body, so an `ln` inside
|
|
651
|
+
* `bash <<'EOF'` was invisible to the first test; `segments(cmd)` over the
|
|
652
|
+
* raw command does not make a body's lines into segments, so it was
|
|
653
|
+
* invisible to the second as well. One view, built once, fed to both.
|
|
654
|
+
*/
|
|
655
|
+
function exemptionIsVoid(cmd: string): boolean {
|
|
656
|
+
const programs = interpreterPrograms(cmd).map(p => p.program);
|
|
657
|
+
const view = [stripHeredocs(cmd), ...programs].join('\n');
|
|
658
|
+
if (LINK_CREATION.test(view)) return true;
|
|
659
|
+
const all = [...segments(view), ...nestedCommands(view).flatMap(inner => segments(inner))];
|
|
660
|
+
return all.some(seg => commandWord(seg) === 'ln' || flagMakesLink(seg));
|
|
661
|
+
}
|
|
662
|
+
|
|
663
|
+
/**
|
|
664
|
+
* Path-like words in `text` that contain `needle`.
|
|
665
|
+
*
|
|
666
|
+
* A word here ends at whitespace or at a character that cannot be inside a
|
|
667
|
+
* shell or source-literal path — a quote, a comma, a bracket, a semicolon.
|
|
668
|
+
* That is deliberately crude and deliberately in the refusing direction: when
|
|
669
|
+
* a path is assembled rather than written out, the word this returns is the
|
|
670
|
+
* fragment that WAS written, which is relative, which `isScratchPath` refuses
|
|
671
|
+
* to exempt.
|
|
672
|
+
*
|
|
673
|
+
* Case-folded for the same reason `names()` is (#1184): the default macOS
|
|
674
|
+
* filesystem resolves `WORKFLOW-STATE.JSON` and `workflow-state.json` to one
|
|
675
|
+
* inode, so a case-sensitive search here would find no path word for the
|
|
676
|
+
* uppercase spelling, and a name with no path words is not exempted — it
|
|
677
|
+
* would refuse rather than leak. Folding keeps the two readings agreeing
|
|
678
|
+
* instead of agreeing by accident.
|
|
679
|
+
*/
|
|
680
|
+
function pathWordsContaining(text: string, needle: string): string[] {
|
|
681
|
+
const out: string[] = [];
|
|
682
|
+
const hay = text.toLowerCase();
|
|
683
|
+
const pin = needle.toLowerCase();
|
|
684
|
+
let i = 0;
|
|
685
|
+
while ((i = hay.indexOf(pin, i)) !== -1) {
|
|
686
|
+
let s = i;
|
|
687
|
+
while (s > 0 && !/[\s'"`,;(){}[\]]/.test(hay[s - 1])) s--;
|
|
688
|
+
let e = i + pin.length;
|
|
689
|
+
while (e < hay.length && !/[\s'"`,;(){}[\]]/.test(hay[e])) e++;
|
|
690
|
+
out.push(text.slice(s, e)); // the ORIGINAL case: this is a path to resolve
|
|
691
|
+
i = e;
|
|
692
|
+
}
|
|
693
|
+
return out;
|
|
694
|
+
}
|
|
695
|
+
|
|
65
696
|
/**
|
|
66
697
|
* Split a command at top-level `;`, `&&`, `||`, `|` and newline, leaving
|
|
67
698
|
* separators inside quotes alone.
|
|
@@ -87,7 +718,27 @@ export function segments(cmd: string): string[] {
|
|
|
87
718
|
const c = cmd[i];
|
|
88
719
|
if (quote) {
|
|
89
720
|
cur += c;
|
|
90
|
-
|
|
721
|
+
// #1203: inside SINGLE quotes nothing is escaped, not even a backslash,
|
|
722
|
+
// so the first `'` always closes. Treating `\'` as an escape there kept
|
|
723
|
+
// the span open past its real end, and everything after it — the
|
|
724
|
+
// separator AND the write verb — was swallowed into one segment where
|
|
725
|
+
// `commandWord` could never reach the verb. Inside DOUBLE quotes `\"`
|
|
726
|
+
// IS an escape, which is why the two cases are told apart rather than
|
|
727
|
+
// handled by one rule.
|
|
728
|
+
//
|
|
729
|
+
// #1249: inside DOUBLE quotes, consume the escape PAIR rather than
|
|
730
|
+
// looking one character back. `\\` is an escaped BACKSLASH — a
|
|
731
|
+
// complete pair — and the `"` after it closes the span. A lookbehind
|
|
732
|
+
// cannot tell that `"` from the escaped one in `\"`, so `"x\\"` was
|
|
733
|
+
// read as still open and the rest of the command, separator and write
|
|
734
|
+
// verb together, became one segment whose command word is `echo`. The
|
|
735
|
+
// outside-quote branch below already consumes the pair, for this same
|
|
736
|
+
// reason; this is that rule applied inside the span.
|
|
737
|
+
if (quote === '"' && c === '\\' && i + 1 < cmd.length) {
|
|
738
|
+
cur += cmd[++i];
|
|
739
|
+
continue;
|
|
740
|
+
}
|
|
741
|
+
if (c === quote) quote = null;
|
|
91
742
|
continue;
|
|
92
743
|
}
|
|
93
744
|
if (c === '"' || c === "'") {
|
|
@@ -95,6 +746,31 @@ export function segments(cmd: string): string[] {
|
|
|
95
746
|
cur += c;
|
|
96
747
|
continue;
|
|
97
748
|
}
|
|
749
|
+
// #1203: a backslash-newline is a LINE CONTINUATION. The shell joins the
|
|
750
|
+
// two lines into one command before it looks for anything else, so
|
|
751
|
+
// splitting on that newline put the verb in one segment and its target in
|
|
752
|
+
// the next, and `cp x \<nl> /r/workflow-state.json` reached the `cp` arm
|
|
753
|
+
// with a single operand. Same class as #1176 and #1184 — a check reading a
|
|
754
|
+
// transformed view whose transformation relocated the token — except this
|
|
755
|
+
// one relocates it across a SEGMENT boundary rather than into a quote.
|
|
756
|
+
//
|
|
757
|
+
// Joining with NOTHING, not with a space, because that is what the shell
|
|
758
|
+
// does: `ch\<nl>mod 777 x.hook.ts` runs chmod, so `commandWord` has to
|
|
759
|
+
// resolve `chmod` too. Inserting a space would read the verb as `ch`.
|
|
760
|
+
//
|
|
761
|
+
// Only outside a quote. Inside single quotes the backslash is literal and
|
|
762
|
+
// the newline is data, which is the negative control this must not break.
|
|
763
|
+
if (c === '\\') {
|
|
764
|
+
if (cmd[i + 1] === '\n') {
|
|
765
|
+
i++;
|
|
766
|
+
continue;
|
|
767
|
+
}
|
|
768
|
+
// An ESCAPED backslash. Consume the pair, so `\\` at end of line leaves
|
|
769
|
+
// no dangling `\` to swallow the newline that genuinely separates.
|
|
770
|
+
cur += c;
|
|
771
|
+
if (i + 1 < cmd.length) cur += cmd[++i];
|
|
772
|
+
continue;
|
|
773
|
+
}
|
|
98
774
|
if (c === ';' || c === '\n' || c === '|' || c === '&') {
|
|
99
775
|
if (cmd[i + 1] === c) i++; // `&&`, `||` are one separator, not two
|
|
100
776
|
out.push(cur);
|
|
@@ -171,24 +847,156 @@ export function stripHeredocs(s: string): string {
|
|
|
171
847
|
}
|
|
172
848
|
|
|
173
849
|
/**
|
|
174
|
-
*
|
|
850
|
+
* Which character positions on this line are OUTSIDE every quoted span.
|
|
851
|
+
*
|
|
852
|
+
* A `$(` opens a COMMAND SUBSTITUTION, and the shell parses its contents as a
|
|
853
|
+
* fresh command with fresh quoting — so text inside `"$( … )"` is unquoted
|
|
854
|
+
* even though it sits between double quotes. That one rule is the whole
|
|
855
|
+
* difference between the two cases in #1196's H6, and it is why this is a
|
|
856
|
+
* small stack rather than a boolean. Single quotes do not substitute, so a
|
|
857
|
+
* `$(` inside them is literal and opens nothing.
|
|
175
858
|
*
|
|
176
|
-
*
|
|
177
|
-
*
|
|
178
|
-
*
|
|
179
|
-
*
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
859
|
+
* Deliberately per-line, matching its only caller: a quote opened on an
|
|
860
|
+
* earlier line reads as unquoted here. That is the behaviour this function
|
|
861
|
+
* replaced — which was not quote-aware at all — so no case gets worse, and
|
|
862
|
+
* the direction it is wrong in deletes text rather than admitting it.
|
|
863
|
+
*/
|
|
864
|
+
function unquotedPositions(line: string): boolean[] {
|
|
865
|
+
const open = new Array<boolean>(line.length).fill(false);
|
|
866
|
+
const stack: string[] = ['']; // quote state per substitution depth
|
|
867
|
+
let i = 0;
|
|
868
|
+
while (i < line.length) {
|
|
869
|
+
const q = stack[stack.length - 1];
|
|
870
|
+
const c = line[i];
|
|
871
|
+
if (q === "'") {
|
|
872
|
+
if (c === "'") stack[stack.length - 1] = '';
|
|
873
|
+
i++;
|
|
874
|
+
} else if (q === '"') {
|
|
875
|
+
if (c === '\\') i += 2;
|
|
876
|
+
else if (c === '$' && line[i + 1] === '(') (stack.push(''), (i += 2));
|
|
877
|
+
else if (c === '"') (stack[stack.length - 1] = ''), i++;
|
|
878
|
+
else i++;
|
|
879
|
+
} else if (c === '\\') {
|
|
880
|
+
i += 2;
|
|
881
|
+
} else if (c === '$' && line[i + 1] === '(') {
|
|
882
|
+
open[i] = open[i + 1] = true;
|
|
883
|
+
stack.push('');
|
|
884
|
+
i += 2;
|
|
885
|
+
} else if (c === ')' && stack.length > 1) {
|
|
886
|
+
stack.pop();
|
|
887
|
+
i++;
|
|
888
|
+
} else if (c === '"' || c === "'") {
|
|
889
|
+
stack[stack.length - 1] = c;
|
|
890
|
+
i++;
|
|
891
|
+
} else {
|
|
892
|
+
open[i] = true;
|
|
893
|
+
i++;
|
|
894
|
+
}
|
|
895
|
+
}
|
|
896
|
+
return open;
|
|
897
|
+
}
|
|
898
|
+
|
|
899
|
+
/**
|
|
900
|
+
* The delimiter word of a `<<WORD` on this line, if any — at a position the
|
|
901
|
+
* shell would read as an operator rather than as text.
|
|
902
|
+
*
|
|
903
|
+
* #1176 left this NOT quote-aware on purpose, because the obvious hardening
|
|
904
|
+
* ("must be top-level") REDDENS the recorded `pai-config#474` false positive,
|
|
905
|
+
* whose heredoc is legitimately nested inside `"$(cat <<'EOF' … )"`. That
|
|
906
|
+
* reasoning was right about the fix it tried and wrong about the conclusion:
|
|
907
|
+
* the distinction is not depth, it is whether a command substitution has
|
|
908
|
+
* reset the quoting. #1196 pays for the small stack that tells them apart.
|
|
909
|
+
*
|
|
910
|
+
* What it buys: `bun -e 'x = "<<EOF"'` opened a heredoc, so every following
|
|
911
|
+
* line up to a bare `EOF` was deleted as a document — a quoted STRING chose
|
|
912
|
+
* what the guard could see. H5 was this same body-drop reached through the
|
|
913
|
+
* wrong character position (`<<<`); this is the wrong quoting position.
|
|
185
914
|
*/
|
|
186
915
|
function heredocDelimiter(line: string): string | null {
|
|
187
916
|
// #1184: `(?<!<)` and `(?!<)` exclude a `<<<` HERESTRING, which has no
|
|
188
917
|
// terminator at all. Matching one invented a delimiter from the quoted text
|
|
189
918
|
// after it and then ran straight into the unterminated case above.
|
|
190
|
-
const
|
|
191
|
-
|
|
919
|
+
const re = /(?<!<)<<(?!<)-?\s*(['"]?)([A-Za-z_][A-Za-z0-9_]*)\1/g;
|
|
920
|
+
const open = unquotedPositions(line);
|
|
921
|
+
for (let m = re.exec(line); m; m = re.exec(line)) {
|
|
922
|
+
if (open[m.index]) return m[2];
|
|
923
|
+
}
|
|
924
|
+
return null;
|
|
925
|
+
}
|
|
926
|
+
|
|
927
|
+
/**
|
|
928
|
+
* Does the heredoc opened on this line hand its body to an interpreter?
|
|
929
|
+
*
|
|
930
|
+
* Two ways it can. The segment carrying the operator IS an interpreter
|
|
931
|
+
* (`bash <<'EOF'`), or the operator's segment is piped into one
|
|
932
|
+
* (`cat <<'EOF' | bash`). Everything else — `cat > doc.md <<'EOF'`,
|
|
933
|
+
* `gh issue comment --body-file - <<'EOF'` — is a DOCUMENT, and stripping
|
|
934
|
+
* those bodies is what stopped 1,860 real commands from being refused for
|
|
935
|
+
* quoting the words this guard looks for. That distinction is the whole
|
|
936
|
+
* reason this is a predicate rather than "stop stripping heredocs".
|
|
937
|
+
*/
|
|
938
|
+
function heredocInterpreter(line: string): string | null {
|
|
939
|
+
const segs = segments(line);
|
|
940
|
+
const ownerIdx = segs.findIndex(s => heredocDelimiter(s) !== null);
|
|
941
|
+
if (ownerIdx === -1) return null;
|
|
942
|
+
const owner = commandWord(segs[ownerIdx]);
|
|
943
|
+
if (isInterpreterWord(owner)) return owner;
|
|
944
|
+
const opAt = line.search(/(?<!<)<<(?!<)/);
|
|
945
|
+
if (opAt === -1 || !line.slice(opAt).includes('|')) return null;
|
|
946
|
+
return segs.slice(ownerIdx + 1).map(commandWord).find(isInterpreterWord) ?? null;
|
|
947
|
+
}
|
|
948
|
+
|
|
949
|
+
/**
|
|
950
|
+
* The program text this command hands to an interpreter on stdin (#1240).
|
|
951
|
+
*
|
|
952
|
+
* A heredoc body fed to an interpreter, and a herestring operand of one.
|
|
953
|
+
* Deliberately NOT the `-c`/`-e` form: arm 3a already reads that, and
|
|
954
|
+
* returning it here would decide it twice.
|
|
955
|
+
*
|
|
956
|
+
* An UNTERMINATED heredoc is not returned. `stripHeredocs` already emits
|
|
957
|
+
* those lines unchanged — the #1184 fail-closed direction — so every arm
|
|
958
|
+
* can already see them, and returning them again would double-count a body
|
|
959
|
+
* that is not hidden in the first place.
|
|
960
|
+
*/
|
|
961
|
+
export function interpreterPrograms(cmd: string): Array<{ shell: boolean; program: string }> {
|
|
962
|
+
const out: Array<{ shell: boolean; program: string }> = [];
|
|
963
|
+
const lines = cmd.split('\n');
|
|
964
|
+
let i = 0;
|
|
965
|
+
while (i < lines.length) {
|
|
966
|
+
const line = lines[i];
|
|
967
|
+
i++;
|
|
968
|
+
if (/^\s*#/.test(line)) continue; // a comment cannot open either form
|
|
969
|
+
|
|
970
|
+
// A HERESTRING has no body and no terminator, which is why
|
|
971
|
+
// `heredocDelimiter` excludes it (#1184). It is still a program, and it
|
|
972
|
+
// is invisible for the other half of the mechanism: the `>` inside it
|
|
973
|
+
// sits in a quoted span that the VERB view removes.
|
|
974
|
+
const hs = /(?<!<)<<<(?!<)([\s\S]*)$/.exec(line);
|
|
975
|
+
if (hs) {
|
|
976
|
+
const owner = segments(line).find(s => /(?<!<)<<<(?!<)/.test(s));
|
|
977
|
+
const word = owner ? commandWord(owner) : '';
|
|
978
|
+
if (isInterpreterWord(word)) {
|
|
979
|
+
out.push({ shell: isShellWord(word), program: dequote(hs[1]).trim() });
|
|
980
|
+
}
|
|
981
|
+
}
|
|
982
|
+
|
|
983
|
+
const delim = heredocDelimiter(line);
|
|
984
|
+
if (!delim) continue;
|
|
985
|
+
const body: string[] = [];
|
|
986
|
+
let j = i;
|
|
987
|
+
while (j < lines.length && lines[j].trim() !== delim) {
|
|
988
|
+
body.push(lines[j]);
|
|
989
|
+
j++;
|
|
990
|
+
}
|
|
991
|
+
if (j < lines.length) {
|
|
992
|
+
const word = heredocInterpreter(line);
|
|
993
|
+
if (word) out.push({ shell: isShellWord(word), program: body.join('\n') });
|
|
994
|
+
i = j + 1;
|
|
995
|
+
} else {
|
|
996
|
+
i = j; // unterminated: already visible, see the docblock
|
|
997
|
+
}
|
|
998
|
+
}
|
|
999
|
+
return out.filter(p => p.program !== '');
|
|
192
1000
|
}
|
|
193
1001
|
|
|
194
1002
|
/** Remove quote characters, keep the contents. Use when looking for a TARGET. */
|
|
@@ -199,6 +1007,13 @@ export function dequote(s: string): string {
|
|
|
199
1007
|
/** Wrappers that delegate to the real command word rather than being one. */
|
|
200
1008
|
const WRAPPERS = /^(?:sudo|env|nohup|time|command|xargs)$/;
|
|
201
1009
|
|
|
1010
|
+
/**
|
|
1011
|
+
* A variable assignment prefix, by the POSIX shape: an identifier, an
|
|
1012
|
+
* optional array subscript, then `=`. Read on the raw token — see
|
|
1013
|
+
* `commandWord`, where recognising it only after the path strip was a bypass.
|
|
1014
|
+
*/
|
|
1015
|
+
const ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*(?:\[[^\]]*\])?=/;
|
|
1016
|
+
|
|
202
1017
|
/**
|
|
203
1018
|
* The command word of a segment — the first token that is not a wrapper, an
|
|
204
1019
|
* assignment or an option. Read off `stripQuoted`, because a quoted token is
|
|
@@ -215,7 +1030,39 @@ export function commandWord(segment: string): string {
|
|
|
215
1030
|
// The grep-PATTERN false positive this function was protecting against is
|
|
216
1031
|
// unaffected: `grep -nE "chmod" f` still resolves to `grep`, because the
|
|
217
1032
|
// real verb comes FIRST and a pattern is never in first position.
|
|
218
|
-
|
|
1033
|
+
//
|
|
1034
|
+
// #1196: the TOKENS come from `scanSegment`, the same quote-aware pass the
|
|
1035
|
+
// redirect scan uses. The #1184 spelling was `dequote(...).split(/\s+/)`,
|
|
1036
|
+
// which removes the quote characters and THEN splits on whitespace — so a
|
|
1037
|
+
// quoted value's internal spaces become token boundaries. `A="1 grep" cp
|
|
1038
|
+
// <protected> /tmp/x` split to `A=1`, `grep`, `cp`, …: the `=` skip
|
|
1039
|
+
// consumed only `A=1` and the verb resolved to `grep`, which is on the
|
|
1040
|
+
// read-only side, so the `cp` was allowed. A quoted span must stay inside
|
|
1041
|
+
// its word; `readWord` already does that, and now there is one tokeniser
|
|
1042
|
+
// rather than two spellings of the idea.
|
|
1043
|
+
for (const raw of scanSegment(segment).words) {
|
|
1044
|
+
// A token carrying WHITESPACE is not a verb. It is what the quote-aware
|
|
1045
|
+
// tokeniser above is for — `A="1 grep"` is one word — and the same
|
|
1046
|
+
// property makes `--body "## Goal … chflags uchg …"` one word too. The
|
|
1047
|
+
// first spelling of this fix returned that whole document as the command
|
|
1048
|
+
// word, and `decideBashWrite` tests `IN_PLACE` against `${word} ${code}`:
|
|
1049
|
+
// a `gh issue create` whose body described chflags on a hook was refused,
|
|
1050
|
+
// which is the recorded `pai-config#474` family. The shell cannot run a
|
|
1051
|
+
// verb named `chmod 777` either, so nothing executable is lost.
|
|
1052
|
+
if (/\s/.test(raw)) continue;
|
|
1053
|
+
// An assignment prefix is recognised on the RAW token, before the path
|
|
1054
|
+
// strip. #1196: the strip runs `^.*\/` and takes the `=` away with the
|
|
1055
|
+
// directory part, so `FOO=/x/grep` arrived at the `includes('=')` test
|
|
1056
|
+
// spelled `grep` and was returned as the command word — a fake verb in
|
|
1057
|
+
// front of the real one. `FOO=/x/grep chmod 777 <hook>` was ALLOW on
|
|
1058
|
+
// main and ALLOW behind the first #1196 fix; `chmod 777 <hook>` BLOCKs.
|
|
1059
|
+
// Four arms were reachable this way. Same defect this issue names, a
|
|
1060
|
+
// different assignment shape: the prefix hides the verb either way.
|
|
1061
|
+
//
|
|
1062
|
+
// Matched by the POSIX shape rather than by `includes('=')` so a real
|
|
1063
|
+
// path is not mistaken for one — `/opt/a=b/bin/tool` does not start
|
|
1064
|
+
// with an identifier, and the test below still catches the rest.
|
|
1065
|
+
if (ASSIGNMENT.test(raw)) continue;
|
|
219
1066
|
const tok = raw
|
|
220
1067
|
.replace(/^[({\\]+/, '') // `(cmd …`, `{ cmd …`, `\cmd` — alias bypass
|
|
221
1068
|
.replace(/^.*\//, ''); // `/usr/bin/python3` -> `python3`
|
|
@@ -234,23 +1081,375 @@ export function commandWord(segment: string): string {
|
|
|
234
1081
|
* then dequoted, because `> "x/.gate-salt"` writes the same file as `>
|
|
235
1082
|
* x/.gate-salt`.
|
|
236
1083
|
*/
|
|
1084
|
+
|
|
1085
|
+
/**
|
|
1086
|
+
* The index just past a quoted span whose OPENING quote is at `i`.
|
|
1087
|
+
*
|
|
1088
|
+
* #1239: both scanners below used to find the partner with `indexOf`, and
|
|
1089
|
+
* `indexOf` cannot tell `"` from `\"`. Inside a double-quoted span the
|
|
1090
|
+
* escaped quote was read as the closing one, every subsequent quote was
|
|
1091
|
+
* paired off by one, and the scanner ran off the end of the line — taking
|
|
1092
|
+
* the `>` operator with it. No operator, no target, ALLOW. Seven spellings
|
|
1093
|
+
* that bash runs and that overwrite the file reached a real write that way,
|
|
1094
|
+
* across both call sites; `test/bash-write-guard.test.ts` holds the table.
|
|
1095
|
+
*
|
|
1096
|
+
* The asymmetry is bash's and is the whole of the fix: a single-quoted span
|
|
1097
|
+
* takes NO escapes, so `'a\'` is a complete span whose contents are `a\`,
|
|
1098
|
+
* while in a double-quoted span `\` escapes whatever follows it.
|
|
1099
|
+
*
|
|
1100
|
+
* Unterminated spans run to `s.length` — the pre-existing, fail-closed
|
|
1101
|
+
* direction. Those spellings are syntax errors that bash refuses to run, so
|
|
1102
|
+
* nothing executable depends on the choice.
|
|
1103
|
+
*
|
|
1104
|
+
* ## #1471: `end` alone could not say which of those two happened
|
|
1105
|
+
*
|
|
1106
|
+
* This used to return a bare number, and for a span that closes at the very
|
|
1107
|
+
* LAST character of the string that number is `s.length` — the same value
|
|
1108
|
+
* an unterminated span returns. The one caller that strips the quotes
|
|
1109
|
+
* resolved the ambiguity with `end === s.length ? s.length : end - 1`, which
|
|
1110
|
+
* cannot be right: it takes the unterminated branch for a correctly closed
|
|
1111
|
+
* final word and keeps the closing quote inside the word.
|
|
1112
|
+
*
|
|
1113
|
+
* Measured on `5d0bf00e` before this fix, and **one trailing space is the
|
|
1114
|
+
* entire difference** — `segments()` trims it, so the spaced form is simply
|
|
1115
|
+
* the same command without a final-word quote:
|
|
1116
|
+
*
|
|
1117
|
+
* cp /tmp/evil.hook.ts /repo/hooks/ → targets 2, BLOCKED
|
|
1118
|
+
* cp /tmp/evil.hook.ts "/repo/hooks/" → targets 1, ALLOWED
|
|
1119
|
+
*
|
|
1120
|
+
* The consequence is sharper than a cosmetic trailing quote. `/repo/hooks/"`
|
|
1121
|
+
* does not end with `/`, so `isDirDestination` reads a DIRECTORY as a plain
|
|
1122
|
+
* file, the `dest/basename(src)` expansion never happens, and the target
|
|
1123
|
+
* that would have named `.hook.ts` is never produced. That is #1184's H4
|
|
1124
|
+
* arriving through a new door.
|
|
1125
|
+
*
|
|
1126
|
+
* It is #1239's defect one level down: there, `indexOf` could not tell `"`
|
|
1127
|
+
* from `\"`; here, `s.length` could not tell *closed at the end* from
|
|
1128
|
+
* *never closed*. One value carrying two meanings — and
|
|
1129
|
+
* `.claude/rules/checks-must-be-able-to-fail.md` names the shape: *a status
|
|
1130
|
+
* code is almost never specific to one mechanism*.
|
|
1131
|
+
*
|
|
1132
|
+
* So the span reports BOTH boundaries and no caller recomputes either.
|
|
1133
|
+
* `contentEnd` is where the span's contents stop; `end` is where the next
|
|
1134
|
+
* word starts. For a terminated span they differ by the closing quote, and
|
|
1135
|
+
* for an unterminated one they are equal. The three callers read the field
|
|
1136
|
+
* they need and none of them owns a ternary — which is the point, because
|
|
1137
|
+
* a `terminated` flag computed at each call site would be three deciders
|
|
1138
|
+
* over one question, and that is how this family keeps coming back.
|
|
1139
|
+
*
|
|
1140
|
+
* One function, three callers, so a mutation of it moves all of them.
|
|
1141
|
+
*/
|
|
1142
|
+
interface QuotedSpan {
|
|
1143
|
+
/** The index just past the closing quote, or `s.length` if there is none. */
|
|
1144
|
+
end: number;
|
|
1145
|
+
/** Where the span's CONTENTS stop — `end - 1` when terminated, else `end`. */
|
|
1146
|
+
contentEnd: number;
|
|
1147
|
+
}
|
|
1148
|
+
|
|
1149
|
+
function endOfQuoted(s: string, i: number): QuotedSpan {
|
|
1150
|
+
const q = s[i];
|
|
1151
|
+
for (let j = i + 1; j < s.length; j++) {
|
|
1152
|
+
// Every span except the single-quoted one takes escapes — that is the
|
|
1153
|
+
// asymmetry stated above, and spelling it as "not `'`" rather than as a
|
|
1154
|
+
// list is what let the BACKTICK span join without a second scanner.
|
|
1155
|
+
if (q !== "'" && s[j] === '\\') {
|
|
1156
|
+
j++; // the escaped character, whatever it is, is not a delimiter
|
|
1157
|
+
continue;
|
|
1158
|
+
}
|
|
1159
|
+
if (s[j] === q) return { end: j + 1, contentEnd: j };
|
|
1160
|
+
}
|
|
1161
|
+
return { end: s.length, contentEnd: s.length };
|
|
1162
|
+
}
|
|
1163
|
+
|
|
237
1164
|
/**
|
|
238
1165
|
* Read one word starting at `i`, honouring quotes. Returns the word's
|
|
239
1166
|
* CONTENTS — quote characters removed, contents kept — and the index after
|
|
240
1167
|
* it, so `dir/"workflow-state.json"` reads as one word and not as two halves
|
|
241
1168
|
* either side of a span that was deleted.
|
|
242
1169
|
*/
|
|
1170
|
+
/**
|
|
1171
|
+
* The index just past the `)` that closes the `$(` at `i`, or the end of
|
|
1172
|
+
* the string if it never closes.
|
|
1173
|
+
*
|
|
1174
|
+
* A parenthesis inside a STRING LITERAL is data, not grammar. Counting it
|
|
1175
|
+
* dropped the depth to zero early, ended the word in the middle of the
|
|
1176
|
+
* substitution, and left a `"` whose partner had already been consumed — so
|
|
1177
|
+
* `readWord`'s quote branch then took `close === -1` and swallowed the rest
|
|
1178
|
+
* of the line INCLUDING the `>` operator. No operator, no target, allow:
|
|
1179
|
+
*
|
|
1180
|
+
* echo $(echo "x)") > <protected> ran, and wrote
|
|
1181
|
+
*
|
|
1182
|
+
* That is #1205's own sentence a second time — the bug is what the scanner
|
|
1183
|
+
* cannot see, not the substitution — so it was fixed the same way rather
|
|
1184
|
+
* than by special-casing the literal that exposed it.
|
|
1185
|
+
*
|
|
1186
|
+
* Extracted from `readWord` so `nestedCommands` can reuse the walk. The
|
|
1187
|
+
* alternative was a second flat `/\$\(([^()]*)\)/`, which is two deciders
|
|
1188
|
+
* answering one question about substitution structure — the fourth shape in
|
|
1189
|
+
* `.claude/rules/checks-must-be-able-to-fail.md` — and the flat one is the
|
|
1190
|
+
* weaker: it cannot match a substitution containing parentheses at all, so
|
|
1191
|
+
* `$(cp -s $(echo V) /tmp/esc)` matched only the INNER one and the outer
|
|
1192
|
+
* body was never read. One reader.
|
|
1193
|
+
*
|
|
1194
|
+
* ## The escape handling is #1239's and it is load-bearing here (#1361)
|
|
1195
|
+
*
|
|
1196
|
+
* This function was extracted on `main` from a copy of the walk that
|
|
1197
|
+
* predated #1239, so it opened spans on `\"` and found their ends with
|
|
1198
|
+
* `indexOf`. Merging the two branches by taking the extraction unchanged
|
|
1199
|
+
* would have reinstated the bypass it had already fixed on the other side:
|
|
1200
|
+
* `echo \" > <protected>` opens a span that never closes, the scanner
|
|
1201
|
+
* swallows the `>`, no operator means no target, and the write is allowed.
|
|
1202
|
+
* One reader is still right — the reader just has to be the fixed one.
|
|
1203
|
+
*
|
|
1204
|
+
* So: a backslash OUTSIDE a span escapes the next character, and the end of
|
|
1205
|
+
* a span is `endOfQuoted`, which honours `\"` inside double quotes and
|
|
1206
|
+
* correctly does not inside single ones, because bash processes no escapes
|
|
1207
|
+
* there.
|
|
1208
|
+
*/
|
|
1209
|
+
function endOfSubstitution(s: string, i: number): number {
|
|
1210
|
+
let depth = 0;
|
|
1211
|
+
let j = i;
|
|
1212
|
+
for (; j < s.length; j++) {
|
|
1213
|
+
const q = s[j];
|
|
1214
|
+
// #1239: outside a quoted span a backslash escapes the next character,
|
|
1215
|
+
// so `\"` does not OPEN a span and `\)` does not close the substitution.
|
|
1216
|
+
if (q === '\\') {
|
|
1217
|
+
j++; // the loop's j++ steps past the escaped character
|
|
1218
|
+
continue;
|
|
1219
|
+
}
|
|
1220
|
+
if (q === "'" || q === '"') {
|
|
1221
|
+
// `endOfQuoted` returns the index AFTER the closing quote; the loop's
|
|
1222
|
+
// j++ would then step over the character following it, so back up one.
|
|
1223
|
+
j = endOfQuoted(s, j).end - 1;
|
|
1224
|
+
continue;
|
|
1225
|
+
}
|
|
1226
|
+
if (s[j] === '(') depth++;
|
|
1227
|
+
else if (s[j] === ')' && --depth === 0) {
|
|
1228
|
+
j++;
|
|
1229
|
+
break;
|
|
1230
|
+
}
|
|
1231
|
+
}
|
|
1232
|
+
return j;
|
|
1233
|
+
}
|
|
1234
|
+
|
|
1235
|
+
/**
|
|
1236
|
+
* ANSI-C quoting: the value of a `$'…'` word.
|
|
1237
|
+
*
|
|
1238
|
+
* Unlike `$(…)` and `` `…` ``, this is settled at parse time — no command
|
|
1239
|
+
* runs and nothing is looked up — so decoding it makes a word MORE readable
|
|
1240
|
+
* rather than guessing at one. `$'-\163'` is the string `-s` on every run.
|
|
1241
|
+
*
|
|
1242
|
+
* An escape this does not recognise keeps its backslash, which is what bash
|
|
1243
|
+
* does with one.
|
|
1244
|
+
*
|
|
1245
|
+
* ## Octal and `\x` are BYTES, so the decode assembles bytes
|
|
1246
|
+
*
|
|
1247
|
+
* Measured: `printf '%s' $'\303\251' | od -An -tx1` gives `c3 a9`, and so
|
|
1248
|
+
* do `$'\xc3\xa9'` and a literal `é` — all three are the UTF-8 encoding of
|
|
1249
|
+
* one character. A per-escape `String.fromCharCode` gives U+00C3 followed
|
|
1250
|
+
* by U+00A9, a different string of four bytes, so above 0x7F that spelling
|
|
1251
|
+
* hands the module a token the shell never produced. Same defect as the
|
|
1252
|
+
* transforms this function exists to close, pointing the other way.
|
|
1253
|
+
*
|
|
1254
|
+
* It is a live one, not a cosmetic differential. With a symlink named
|
|
1255
|
+
* `café` under a scratch root pointing into the run store, the write
|
|
1256
|
+
* through it is REFUSED when spelled literally and when spelled
|
|
1257
|
+
* `$'café'`, and was ALLOWED when spelled `$'caf\303\251'` or
|
|
1258
|
+
* `$'caf\xc3\xa9'` — the module looked for a directory nobody had made,
|
|
1259
|
+
* found nothing to resolve, and exempted it as ordinary scratch. That is
|
|
1260
|
+
* #1175's escape with a name the decoder disagreed about.
|
|
1261
|
+
*
|
|
1262
|
+
* So escapes are decoded into BYTES and the byte string is decoded as
|
|
1263
|
+
* UTF-8 once, at the end. Refusing to decode above 0x80 was the first
|
|
1264
|
+
* repair and it does NOT close this: an undecoded `caf\303\251` is just
|
|
1265
|
+
* another directory that does not exist, which is exempt. The conservative
|
|
1266
|
+
* answer and the wrong answer are the same answer here.
|
|
1267
|
+
*
|
|
1268
|
+
* `\u` and `\U` stay code points, because that is what bash defines them
|
|
1269
|
+
* as — it emits their UTF-8 encoding, which is what they mean once the
|
|
1270
|
+
* command text has itself been decoded from UTF-8.
|
|
1271
|
+
*
|
|
1272
|
+
* What remains: a byte sequence that is not valid UTF-8, such as a lone
|
|
1273
|
+
* `$'\303'`, becomes U+FFFD here and names a file this module cannot
|
|
1274
|
+
* spell. Closing that needs byte-level paths throughout, which is a
|
|
1275
|
+
* different change; the residue is one unmatched character in a position
|
|
1276
|
+
* that is then unprovable rather than wrongly exempt.
|
|
1277
|
+
*/
|
|
1278
|
+
const ANSI_C_SHORT: Record<string, string> = {
|
|
1279
|
+
a: '\x07',
|
|
1280
|
+
b: '\b',
|
|
1281
|
+
e: '\x1b',
|
|
1282
|
+
E: '\x1b',
|
|
1283
|
+
f: '\f',
|
|
1284
|
+
n: '\n',
|
|
1285
|
+
r: '\r',
|
|
1286
|
+
t: '\t',
|
|
1287
|
+
v: '\v',
|
|
1288
|
+
'\\': '\\',
|
|
1289
|
+
"'": "'",
|
|
1290
|
+
'"': '"',
|
|
1291
|
+
'?': '?',
|
|
1292
|
+
};
|
|
1293
|
+
|
|
1294
|
+
function decodeAnsiC(body: string): string {
|
|
1295
|
+
const bytes: number[] = [];
|
|
1296
|
+
// Plain text accumulates and is encoded in runs rather than per character,
|
|
1297
|
+
// so a surrogate PAIR is encoded as the one code point it spells instead
|
|
1298
|
+
// of as two lone halves.
|
|
1299
|
+
let pending = '';
|
|
1300
|
+
const flush = () => {
|
|
1301
|
+
if (!pending) return;
|
|
1302
|
+
for (const b of new TextEncoder().encode(pending)) bytes.push(b);
|
|
1303
|
+
pending = '';
|
|
1304
|
+
};
|
|
1305
|
+
for (let k = 0; k < body.length; k++) {
|
|
1306
|
+
if (body[k] !== '\\' || k + 1 >= body.length) {
|
|
1307
|
+
pending += body[k];
|
|
1308
|
+
continue;
|
|
1309
|
+
}
|
|
1310
|
+
const n = body[k + 1];
|
|
1311
|
+
const short = ANSI_C_SHORT[n];
|
|
1312
|
+
if (short !== undefined) {
|
|
1313
|
+
pending += short;
|
|
1314
|
+
k++;
|
|
1315
|
+
continue;
|
|
1316
|
+
}
|
|
1317
|
+
if (n >= '0' && n <= '7') {
|
|
1318
|
+
const oct = /^[0-7]{1,3}/.exec(body.slice(k + 1))?.[0] ?? '';
|
|
1319
|
+
flush();
|
|
1320
|
+
bytes.push(parseInt(oct, 8) & 0xff); // a BYTE
|
|
1321
|
+
k += oct.length;
|
|
1322
|
+
continue;
|
|
1323
|
+
}
|
|
1324
|
+
if (n === 'x' || n === 'u' || n === 'U') {
|
|
1325
|
+
const width = n === 'x' ? 2 : n === 'u' ? 4 : 8;
|
|
1326
|
+
const hex = new RegExp(`^[0-9a-fA-F]{1,${width}}`).exec(body.slice(k + 2))?.[0] ?? '';
|
|
1327
|
+
if (hex) {
|
|
1328
|
+
const value = parseInt(hex, 16);
|
|
1329
|
+
if (n === 'x') {
|
|
1330
|
+
flush();
|
|
1331
|
+
bytes.push(value & 0xff); // a BYTE
|
|
1332
|
+
} else {
|
|
1333
|
+
pending += String.fromCodePoint(value); // a CODE POINT
|
|
1334
|
+
}
|
|
1335
|
+
k += 1 + hex.length;
|
|
1336
|
+
continue;
|
|
1337
|
+
}
|
|
1338
|
+
}
|
|
1339
|
+
pending += body[k]; // an escape bash does not recognise keeps its backslash
|
|
1340
|
+
}
|
|
1341
|
+
flush();
|
|
1342
|
+
return new TextDecoder('utf-8').decode(new Uint8Array(bytes));
|
|
1343
|
+
}
|
|
1344
|
+
|
|
243
1345
|
function readWord(s: string, i: number): [string, number] {
|
|
244
1346
|
let w = '';
|
|
245
1347
|
while (i < s.length) {
|
|
246
1348
|
const c = s[i];
|
|
247
1349
|
if (c === ' ' || c === '\t' || c === '\n') break;
|
|
248
1350
|
if (c === '>' || c === '<') break; // an operator ends a word
|
|
1351
|
+
// #1239: a backslash escapes the next character, so `\"` is a literal
|
|
1352
|
+
// quote and does not open a span. Without this, `echo \" > <protected>`
|
|
1353
|
+
// opened a span that never closed and the scanner swallowed the `>` —
|
|
1354
|
+
// the shortest bypass in the family, needing no `$( )` at all. The text
|
|
1355
|
+
// is kept verbatim because this module expands nothing; what matters is
|
|
1356
|
+
// that the escaped character cannot act as a delimiter.
|
|
1357
|
+
if (c === '\\' && i + 1 < s.length) {
|
|
1358
|
+
w += c + s[i + 1];
|
|
1359
|
+
i += 2;
|
|
1360
|
+
continue;
|
|
1361
|
+
}
|
|
1362
|
+
// ANSI-C quoting, the FOURTH transform. `$'-s'` is the word `-s`, and
|
|
1363
|
+
// reading the `$` as an ordinary character left the token `$-s`, which
|
|
1364
|
+
// fails `isLinkFlag`'s `startsWith('-')` precondition before any flag
|
|
1365
|
+
// letter is looked at. Handled here rather than in `isLinkFlag` because
|
|
1366
|
+
// it is a QUOTING rule and this is the module's quote reader — and
|
|
1367
|
+
// because doing it here also fixes `$'cp'`, where the thing hidden is
|
|
1368
|
+
// the VERB and `isLinkFlag` is never consulted at all.
|
|
1369
|
+
//
|
|
1370
|
+
// A `\'` inside the body is an escaped quote, so the closing quote is
|
|
1371
|
+
// found by walking rather than by `indexOf`.
|
|
1372
|
+
//
|
|
1373
|
+
// ORDER AGAINST THE CLAUSE ABOVE DOES NOT MATTER and the merge that put
|
|
1374
|
+
// them together should say so: one tests `\` and the other `$`, so no
|
|
1375
|
+
// input reaches both. What does matter is that BOTH precede the quote
|
|
1376
|
+
// clause below, or an escaped or ANSI-C quote opens a span and the
|
|
1377
|
+
// scanner swallows the redirect — which is #1239's bypass arriving by a
|
|
1378
|
+
// second route (#1361 merge).
|
|
1379
|
+
if (c === '$' && s[i + 1] === "'") {
|
|
1380
|
+
let k = i + 2;
|
|
1381
|
+
for (; k < s.length && s[k] !== "'"; k++) if (s[k] === '\\') k++;
|
|
1382
|
+
w += decodeAnsiC(s.slice(i + 2, Math.min(k, s.length)));
|
|
1383
|
+
i = k + 1; // unterminated leaves i past the end, which ends the word
|
|
1384
|
+
continue;
|
|
1385
|
+
}
|
|
1386
|
+
// #1239: `echo "x\"" > <protected>` needs no substitution at all — the
|
|
1387
|
+
// shortest bypass in the family, and the issue that filed the `$( )`
|
|
1388
|
+
// spellings did not name it. `endOfQuoted` honours the backslash.
|
|
249
1389
|
if (c === "'" || c === '"') {
|
|
250
|
-
const
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
1390
|
+
const span = endOfQuoted(s, i);
|
|
1391
|
+
// The span's CONTENTS, outer quotes removed. The escape is kept rather
|
|
1392
|
+
// than resolved: this module expands nothing, and keeping the text
|
|
1393
|
+
// verbatim is what lets `isScratchPath` go on reading an unexpanded
|
|
1394
|
+
// path as unprovable (#1175). What had to be right here is the word
|
|
1395
|
+
// BOUNDARY, so the operator after it is still seen.
|
|
1396
|
+
//
|
|
1397
|
+
// #1471: this read `end === s.length ? s.length : end - 1`, which is
|
|
1398
|
+
// the ambiguity `endOfQuoted` now resolves for it. `contentEnd` is the
|
|
1399
|
+
// answer, not a ternary this site re-derives.
|
|
1400
|
+
w += s.slice(i + 1, span.contentEnd);
|
|
1401
|
+
i = span.end;
|
|
1402
|
+
continue;
|
|
1403
|
+
}
|
|
1404
|
+
// #1205: a command substitution is part of the word it sits in, however
|
|
1405
|
+
// much whitespace is inside it. Ending the word at the first space split
|
|
1406
|
+
// `> /tmp/`id -un`/workflow-state.json` into the target `/tmp/`id` — which
|
|
1407
|
+
// names no protected artifact, so arm 1 never fired at all and a write to
|
|
1408
|
+
// a live run-store path was allowed. The space-free spelling was caught,
|
|
1409
|
+
// which is why this survived: the bug is the SPACE, not the substitution.
|
|
1410
|
+
//
|
|
1411
|
+
// The text is kept verbatim rather than expanded. This module does not
|
|
1412
|
+
// expand anything, and keeping the `$`/backtick is what lets #1175's
|
|
1413
|
+
// `isScratchPath` go on reading an unexpanded path as unprovable.
|
|
1414
|
+
if (c === '`') {
|
|
1415
|
+
// #1361's AI review found this one, and it is right: this was the last
|
|
1416
|
+
// `indexOf` partner-finder in the module. `indexOf` cannot tell `` ` ``
|
|
1417
|
+
// from ``\` ``, so an escaped backtick inside the substitution was read
|
|
1418
|
+
// as the closer, the word ended in the wrong place, and the `>` that
|
|
1419
|
+
// followed was never seen. No operator, no target, ALLOW — the exact
|
|
1420
|
+
// shape #1239 fixed for `"`, `'` and `$(...)`, surviving in the one
|
|
1421
|
+
// branch those fixes did not touch.
|
|
1422
|
+
//
|
|
1423
|
+
// Verified both halves before fixing, because a guard missing a command
|
|
1424
|
+
// bash refuses to run is not a bypass. All three spellings return no
|
|
1425
|
+
// targets at all AND are performed by bash:
|
|
1426
|
+
//
|
|
1427
|
+
// echo `echo a\`b` > <run-store>/workflow-state.json
|
|
1428
|
+
// echo `echo \`` > <run-store>/workflow-state.json
|
|
1429
|
+
// echo `echo \`\`x` > <run-store>/workflow-state.json
|
|
1430
|
+
//
|
|
1431
|
+
// `endOfQuoted` already walks escapes; a backtick span escapes exactly
|
|
1432
|
+
// as a double-quoted one does, so this is a third caller of the one
|
|
1433
|
+
// scanner rather than a fourth hand-rolled one. It returns `s.length`
|
|
1434
|
+
// for an unterminated span, which is the same fail-closed direction
|
|
1435
|
+
// this branch already took.
|
|
1436
|
+
// Keeps the backticks, so it reads `end` and never `contentEnd` — the
|
|
1437
|
+
// whole span verbatim is the point here (#1175).
|
|
1438
|
+
const span = endOfQuoted(s, i);
|
|
1439
|
+
w += s.slice(i, span.end);
|
|
1440
|
+
i = span.end;
|
|
1441
|
+
continue;
|
|
1442
|
+
}
|
|
1443
|
+
if (c === '$' && s[i + 1] === '(') {
|
|
1444
|
+
// #1361 merge: main extracted this walk into `endOfSubstitution` so
|
|
1445
|
+
// `nestedCommands` could reuse it — one reader, which is the right
|
|
1446
|
+
// call and is kept. #1239's backslash handling, which this branch had
|
|
1447
|
+
// added to the inline copy, is ported INTO that function rather than
|
|
1448
|
+
// left behind here. Taking main's line unchanged would have silently
|
|
1449
|
+
// reinstated the bypass.
|
|
1450
|
+
const j = endOfSubstitution(s, i);
|
|
1451
|
+
w += s.slice(i, j); // unterminated falls out here with j === s.length
|
|
1452
|
+
i = j;
|
|
254
1453
|
continue;
|
|
255
1454
|
}
|
|
256
1455
|
w += c;
|
|
@@ -283,7 +1482,18 @@ function isWriteOperand(op: string): boolean {
|
|
|
283
1482
|
* was seen by neither pass. Scanning finds the operator at a position and
|
|
284
1483
|
* then reads the operand as a word, which is the same rule the shell uses.
|
|
285
1484
|
*/
|
|
286
|
-
|
|
1485
|
+
/**
|
|
1486
|
+
* One left-to-right pass over a segment, returning its WORDS and its
|
|
1487
|
+
* redirect TARGETS.
|
|
1488
|
+
*
|
|
1489
|
+
* #1196 made this the single tokeniser. `commandWord` previously did its own
|
|
1490
|
+
* `dequote(...).split(/\s+/)`, which is not tokenisation: it let a quoted
|
|
1491
|
+
* multi-word assignment VALUE break into separate tokens, so
|
|
1492
|
+
* `A="1 grep" cp …` dropped only `A=1` on the `includes('=')` skip and
|
|
1493
|
+
* resolved the verb to `grep`. Here a quoted span stays INSIDE its word, so
|
|
1494
|
+
* the same input yields the single token `A=1 grep`, which is skipped whole.
|
|
1495
|
+
*/
|
|
1496
|
+
function scanSegment(segment: string): { words: string[]; targets: string[] } {
|
|
287
1497
|
const targets: string[] = [];
|
|
288
1498
|
const words: string[] = [];
|
|
289
1499
|
const s = stripHeredocs(segment);
|
|
@@ -316,8 +1526,26 @@ export function writeTargets(segment: string): string[] {
|
|
|
316
1526
|
}
|
|
317
1527
|
const [w, next] = readWord(s, i);
|
|
318
1528
|
i = next === i ? i + 1 : next;
|
|
1529
|
+
// #1196 R3: an IO NUMBER is not a word. POSIX: an unquoted digit string
|
|
1530
|
+
// immediately preceding `<` or `>` names a file descriptor, so the `2`
|
|
1531
|
+
// in `2>/dev/null` belongs to the redirect. Emitting it as a word put it
|
|
1532
|
+
// in LAST position among a `cp`'s arguments, which is where this module
|
|
1533
|
+
// looks for the destination — so `cp /tmp/x.json /r/<protected>
|
|
1534
|
+
// 2>/dev/null` read its destination as `2` and the real one was demoted
|
|
1535
|
+
// to a source. Measured on the corpus: four genuine writes to a gate
|
|
1536
|
+
// artifact or a hook, allowed by #1188, and found only because a
|
|
1537
|
+
// classifier written for a different question made the same mistake.
|
|
1538
|
+
if (w && /^\d+$/.test(w) && (s[i] === '>' || s[i] === '<')) continue;
|
|
319
1539
|
if (w) words.push(w);
|
|
320
1540
|
}
|
|
1541
|
+
return { words, targets };
|
|
1542
|
+
}
|
|
1543
|
+
|
|
1544
|
+
/**
|
|
1545
|
+
* Paths a segment writes through shell redirection or a copying verb.
|
|
1546
|
+
*/
|
|
1547
|
+
export function writeTargets(segment: string, whole: string = segment): string[] {
|
|
1548
|
+
const { words, targets } = scanSegment(segment);
|
|
321
1549
|
|
|
322
1550
|
// `tee` takes MANY files. Reading only the first operand let
|
|
323
1551
|
// `tee /tmp/a <protected>` through (#1176).
|
|
@@ -336,11 +1564,9 @@ export function writeTargets(segment: string): string[] {
|
|
|
336
1564
|
if (args.length >= 2) {
|
|
337
1565
|
const dest = args[args.length - 1];
|
|
338
1566
|
targets.push(dest);
|
|
339
|
-
//
|
|
340
|
-
// `dest/basename(src)`, for every source.
|
|
341
|
-
|
|
342
|
-
// artifact in its last argument and writes one.
|
|
343
|
-
if (isDirDestination(dest)) {
|
|
1567
|
+
// When the destination is a DIRECTORY the real sink is
|
|
1568
|
+
// `dest/basename(src)`, for every source (#1184).
|
|
1569
|
+
if (isDirDestination(dest, args, whole)) {
|
|
344
1570
|
for (const src of args.slice(0, -1)) {
|
|
345
1571
|
targets.push(`${dest.replace(/\/+$/, '')}/${src.replace(/^.*\//, '')}`);
|
|
346
1572
|
}
|
|
@@ -351,23 +1577,56 @@ export function writeTargets(segment: string): string[] {
|
|
|
351
1577
|
}
|
|
352
1578
|
|
|
353
1579
|
/**
|
|
354
|
-
* Does this destination name a
|
|
355
|
-
*
|
|
356
|
-
*
|
|
357
|
-
*
|
|
1580
|
+
* Does this destination name a DIRECTORY? Four oracles, three of them
|
|
1581
|
+
* syntactic, in the order they settle the question cheaply.
|
|
1582
|
+
*
|
|
1583
|
+
* #1184 asked only the fourth, `statSync`, and that is #1196's R2: a
|
|
1584
|
+
* PreToolUse hook decides before ANY of the command has run, so in
|
|
1585
|
+
* `mkdir -p d && cp <protected> d` the directory never exists at decision
|
|
1586
|
+
* time. Measured both ways on the same command — directory absent ALLOW,
|
|
1587
|
+
* directory present BLOCK. A guard whose answer depends on a directory the
|
|
1588
|
+
* same command is about to create is not a guard.
|
|
1589
|
+
*
|
|
1590
|
+
* The reviewer's simpler repair was to delete the test and push
|
|
1591
|
+
* `dest/basename(src)` unconditionally. Measured on 5,543 corpus commands
|
|
1592
|
+
* naming a protected artifact, that refuses 19 real commands and catches no
|
|
1593
|
+
* real write that the oracles below miss — every one of the 19 is a
|
|
1594
|
+
* protected file copied OUT to a plain destination, and 11 of those are the
|
|
1595
|
+
* `cp hooks/X.hook.ts /tmp/x.bak` backup that
|
|
1596
|
+
* `.claude/rules/checks-must-be-able-to-fail.md` requires before a mutation
|
|
1597
|
+
* battery. A guard that refuses the repository's own mandated practice gets
|
|
1598
|
+
* switched off. So the test stays and gains the readings it was missing.
|
|
358
1599
|
*/
|
|
359
|
-
//
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
function isDirDestination(dest: string): boolean {
|
|
363
|
-
if (dest.endsWith('/')) return true;
|
|
1600
|
+
// #1175 moved `statSync` to the import block at the top, which `isScratchPath`
|
|
1601
|
+
// also reads from. Two `from 'fs'` statements in one module is legal and is
|
|
1602
|
+
// still one import of one module; one of them is what a reader greps for.
|
|
1603
|
+
function isDirDestination(dest: string, args: string[], whole: string): boolean {
|
|
1604
|
+
if (dest.endsWith('/')) return true; // `cp x d/` — the shell requires a dir
|
|
1605
|
+
if (args.length > 2) return true; // `cp a b c d` — d MUST be a directory
|
|
1606
|
+
if (createdAsDirectory(dest, whole)) return true; // `mkdir -p d && cp x d`
|
|
364
1607
|
try {
|
|
365
1608
|
return statSync(dest).isDirectory();
|
|
366
1609
|
} catch {
|
|
367
|
-
return false;
|
|
1610
|
+
return false; // unreadable reads as a plain file; that is the last-arg case
|
|
1611
|
+
}
|
|
1612
|
+
}
|
|
1613
|
+
|
|
1614
|
+
/** Does some earlier segment of this same command `mkdir` the destination? */
|
|
1615
|
+
function createdAsDirectory(dest: string, whole: string): boolean {
|
|
1616
|
+
const want = dest.replace(/\/+$/, '');
|
|
1617
|
+
for (const seg of segments(whole)) {
|
|
1618
|
+
if (commandWord(seg) !== 'mkdir') continue;
|
|
1619
|
+
for (const a of scanSegment(seg).words.slice(1)) {
|
|
1620
|
+
if (!a.startsWith('-') && a.replace(/\/+$/, '') === want) return true;
|
|
1621
|
+
}
|
|
368
1622
|
}
|
|
1623
|
+
return false;
|
|
369
1624
|
}
|
|
370
1625
|
|
|
1626
|
+
// `statSync` used to be declared here, beside its only reader. #1175 gave it
|
|
1627
|
+
// a second reader in `isScratchPath` at the top of the module, so the import
|
|
1628
|
+
// moved to the import block rather than being written twice.
|
|
1629
|
+
|
|
371
1630
|
/**
|
|
372
1631
|
* Non-option arguments of a segment, dequoted. This is what an in-place verb
|
|
373
1632
|
* actually operates on — as opposed to its script, which is an argument too
|
|
@@ -417,10 +1676,35 @@ const IN_PLACE = [
|
|
|
417
1676
|
/\brm\b/,
|
|
418
1677
|
/\bln\b/,
|
|
419
1678
|
/\bgit\s+(?:checkout|restore)\b/,
|
|
1679
|
+
// #1146: extended attributes are file metadata, and `com.apple.provenance`
|
|
1680
|
+
// is what was blocking writes to the hooks on this machine — so removing it
|
|
1681
|
+
// is a mutation of hook integrity by any reading.
|
|
1682
|
+
//
|
|
1683
|
+
// The mutating forms are read off `xattr --help`, not guessed:
|
|
1684
|
+
//
|
|
1685
|
+
// xattr [-lrsvx] file … list READ
|
|
1686
|
+
// xattr -p [-lrsvx] attr file … print READ
|
|
1687
|
+
// xattr -w [-rsx] attr value file set MUTATES
|
|
1688
|
+
// xattr -d [-rsv] attr file … delete MUTATES
|
|
1689
|
+
// xattr -c [-rsv] file … clear ALL MUTATES
|
|
1690
|
+
//
|
|
1691
|
+
// So the letters are `c`, `d`, `w` — and they may sit ANYWHERE in a flag
|
|
1692
|
+
// cluster, which is why this does not read a single letter. The first
|
|
1693
|
+
// revision of this PR shipped `-[dws]`, wrong in both directions against
|
|
1694
|
+
// that table: it missed `-c`, which deletes every attribute on the file,
|
|
1695
|
+
// and it refused `-s`, which only says "act on the symbolic link itself".
|
|
1696
|
+
// Seven of fifteen spellings were decided wrongly.
|
|
1697
|
+
//
|
|
1698
|
+
// A bare invocation carries no leading dash, so the READ that this arm
|
|
1699
|
+
// must not refuse — two real corpus commands run `xattr <hook>` to inspect
|
|
1700
|
+
// the attribute list — is excluded by construction rather than by a list.
|
|
1701
|
+
/\bxattr\b[^\n]*\s-[A-Za-z]*[cdw][A-Za-z]*\b/,
|
|
420
1702
|
];
|
|
421
1703
|
|
|
422
|
-
|
|
423
|
-
|
|
1704
|
+
// #1240: the list moved to `lib/interpreters.ts`, which `lib/bash-file-read.ts`
|
|
1705
|
+
// now reads too. Two modules were answering "is this an interpreter" with two
|
|
1706
|
+
// different lists, and the narrower one was why a `python3` heredoc read as a
|
|
1707
|
+
// document.
|
|
424
1708
|
|
|
425
1709
|
/**
|
|
426
1710
|
* Interpreters whose `-c` argument is SHELL — which this module can read.
|
|
@@ -429,8 +1713,9 @@ const INTERPRETERS = /^(?:python[23]?|perl|ruby|node|bun|deno|osascript|sh|bash|
|
|
|
429
1713
|
* Python idioms, so `bash -c 'echo x > <protected>'` matched nothing and was
|
|
430
1714
|
* allowed. Arm 1 could not see it either, because the body is quoted. The
|
|
431
1715
|
* body is shell, the module parses shell, so it recurses instead of guessing.
|
|
1716
|
+
*
|
|
1717
|
+
* #1240: also in `lib/interpreters.ts` as `isShellWord`.
|
|
432
1718
|
*/
|
|
433
|
-
const SHELLS = /^(?:sh|bash|zsh|dash|ksh)$/;
|
|
434
1719
|
|
|
435
1720
|
/** The `-c` body of a shell invocation, dequoted. */
|
|
436
1721
|
function shellBody(segment: string): string {
|
|
@@ -457,6 +1742,68 @@ function shellBody(segment: string): string {
|
|
|
457
1742
|
* and `.claude/rules/checks-must-be-able-to-fail.md` would call it a
|
|
458
1743
|
* detector narrower than what it detects. It is the widest setting the
|
|
459
1744
|
* measured false-positive rate allows.
|
|
1745
|
+
*
|
|
1746
|
+
* ## #1214: an imported project function is outside what this arm can decide
|
|
1747
|
+
*
|
|
1748
|
+
* The concession above says an interpreter can evade this arm by calling
|
|
1749
|
+
* through a variable or putting the program in a file. #1214 filed a case
|
|
1750
|
+
* needing neither — a plain call to a project function the enumeration has
|
|
1751
|
+
* never heard of:
|
|
1752
|
+
*
|
|
1753
|
+
* bun -e "
|
|
1754
|
+
* import {initWorkflow, writeACs} from '<harness>/gates/orchestrator.ts';
|
|
1755
|
+
* const sf = '<run store>/workflow-state.json';
|
|
1756
|
+
* initWorkflow(sf, {…});
|
|
1757
|
+
* writeACs(sf, JSON.parse(process.argv[1]));"
|
|
1758
|
+
*
|
|
1759
|
+
* `initWorkflow` and `writeACs` both write `sf`, `sf` is a live run-store
|
|
1760
|
+
* artifact, and nothing in the list above matches. ALLOW.
|
|
1761
|
+
*
|
|
1762
|
+
* The issue's framing 1 — derive the suspicious-call set from the body's OWN
|
|
1763
|
+
* `import` statement, so the module enumerates nothing and stays
|
|
1764
|
+
* project-agnostic — was implemented and swept over 130,247 real commands
|
|
1765
|
+
* from this machine's 31,793 transcripts:
|
|
1766
|
+
*
|
|
1767
|
+
* newly BLOCKED 616 newly ALLOWED 0
|
|
1768
|
+
* 600 call a writing orchestrator symbol (writeWorkflowState 301,
|
|
1769
|
+
* initWorkflow+writeACs 285, the rest in ones and twos)
|
|
1770
|
+
* 10 call a reading one (readWorkflow, loadWorkflow, …)
|
|
1771
|
+
* 6 probe this module or take a hook census
|
|
1772
|
+
* 0 of the 616 are scratch fixtures; every one names the live run store.
|
|
1773
|
+
*
|
|
1774
|
+
* 97% precision by that reading, and it is still **not shippable** — for a
|
|
1775
|
+
* reason no count could show. The 600 are not evasions. They are this
|
|
1776
|
+
* harness's own prescribed mechanism:
|
|
1777
|
+
*
|
|
1778
|
+
* - `workflows/ship.js` EMITS the filed command, at the GOAL phase, under
|
|
1779
|
+
* an instruction reading "Run this EXACTLY as written". The payload
|
|
1780
|
+
* spelling `JSON.parse(process.argv[1])` is generated by
|
|
1781
|
+
* `acPayloadReadExpression()` in `lib/evidence-command-transport.ts`, so
|
|
1782
|
+
* the fingerprint belongs to the harness and to nothing else.
|
|
1783
|
+
* - `gates/SCHEMA-GUIDE.md` prescribes `writeWorkflowState` via `bun -e`
|
|
1784
|
+
* in place of the Write tool or `cat >`.
|
|
1785
|
+
* - `lib/gate-result-protection.ts` and `lib/gate-enforcement.ts` PRINT
|
|
1786
|
+
* that command to the agent as the sanctioned repair.
|
|
1787
|
+
*
|
|
1788
|
+
* So the predicate would refuse the GOAL phase of every run, and the guard
|
|
1789
|
+
* would be refusing the exact command its sibling modules hand out as the
|
|
1790
|
+
* remedy. The filed case and the sanctioned repair are the same operation,
|
|
1791
|
+
* differing only in which orchestrator symbol is called — and separating
|
|
1792
|
+
* them means enumerating one consumer's API, which is what #1214 forbids and
|
|
1793
|
+
* is wrong in every other tree besides.
|
|
1794
|
+
*
|
|
1795
|
+
* **The result is therefore framing 2, and it belongs here rather than in an
|
|
1796
|
+
* open issue: a program that imports project code is outside what a
|
|
1797
|
+
* command-line guard can decide.** Nothing read off the command line
|
|
1798
|
+
* distinguishes a sanctioned write from an unsanctioned one when both are
|
|
1799
|
+
* the same call to the same function on the same path. That is a question
|
|
1800
|
+
* about the command's PROVENANCE, not its text, so closing it needs the
|
|
1801
|
+
* harness to mark the commands it issued — a different mechanism from
|
|
1802
|
+
* parsing, and not one this module can reach.
|
|
1803
|
+
*
|
|
1804
|
+
* `test/bash-write-guard.test.ts` pins the conclusion rather than leaving it
|
|
1805
|
+
* as prose: the sanctioned commands must stay ALLOWED, so the next person to
|
|
1806
|
+
* reach for the obvious fix gets a red suite naming what it costs.
|
|
460
1807
|
*/
|
|
461
1808
|
const WRITE_INTENT =
|
|
462
1809
|
/\b(?:writeFileSync|appendFileSync|createWriteStream|copyFileSync|renameSync|unlinkSync|rmSync|truncateSync|write_text|json\.dump|os\.remove|os\.rename|os\.replace|os\.unlink|shutil\.(?:copy|move|rmtree))\b|(?<!stdout)(?<!stderr)\.write\s*\(|\bopen\s*\([^)]*['"][wax]\+?['"]/;
|
|
@@ -498,6 +1845,678 @@ function names(text: string, list: string[]): string | null {
|
|
|
498
1845
|
return null;
|
|
499
1846
|
}
|
|
500
1847
|
|
|
1848
|
+
/**
|
|
1849
|
+
* Protected artifacts this text names somewhere OTHER than a scratch tree
|
|
1850
|
+
* (#1175).
|
|
1851
|
+
*
|
|
1852
|
+
* A name is exempted only when EVERY path word carrying it is scratch. One
|
|
1853
|
+
* mention of the live artifact alongside ten fixtures still refuses, which is
|
|
1854
|
+
* the direction a guard should err in and also the common real shape: a
|
|
1855
|
+
* command that copies a fixture over a run's state names both.
|
|
1856
|
+
*/
|
|
1857
|
+
function namesOutsideScratch(text: string, list: string[], exempt: boolean): string[] {
|
|
1858
|
+
const out: string[] = [];
|
|
1859
|
+
for (const p of list) {
|
|
1860
|
+
const words = pathWordsContaining(text, p);
|
|
1861
|
+
if (words.length === 0) continue;
|
|
1862
|
+
if (exempt && words.every(isScratchPath)) continue;
|
|
1863
|
+
out.push(p);
|
|
1864
|
+
}
|
|
1865
|
+
return out;
|
|
1866
|
+
}
|
|
1867
|
+
|
|
1868
|
+
/**
|
|
1869
|
+
* Protected names in a program body, counting only ABSOLUTE spellings
|
|
1870
|
+
* outside a scratch tree (#1240).
|
|
1871
|
+
*
|
|
1872
|
+
* The stricter reading exists because of what it costs otherwise, measured
|
|
1873
|
+
* rather than reasoned: scanning an interpreter body for a protected NAME
|
|
1874
|
+
* newly refused **23** real commands, and every one of them was an agent
|
|
1875
|
+
* building hook FIXTURES in a `/tmp` tree with an assembled path —
|
|
1876
|
+
* `open(os.path.join(dst, n), "w")`, where the only word carrying
|
|
1877
|
+
* `.hook.ts` is the relative suffix itself. A relative fragment cannot be
|
|
1878
|
+
* shown to be scratch, so the fail-closed reading in `isScratchPath`
|
|
1879
|
+
* correctly refuses to exempt it, and the result is that the fixture work
|
|
1880
|
+
* #1175 exists to unblock gets refused by the arm added beside it.
|
|
1881
|
+
*
|
|
1882
|
+
* So this arm asks for an absolute path. The spelling it is there to catch
|
|
1883
|
+
* — `open("<run store>/workflow-state.json", "w")` inside a heredoc — is
|
|
1884
|
+
* absolute, and the 23 are not. The arm it mirrors (arm 3, the `-c` form)
|
|
1885
|
+
* keeps its looser reading: that behaviour is pre-existing and measured,
|
|
1886
|
+
* and tightening it is not this change's business.
|
|
1887
|
+
*/
|
|
1888
|
+
function absoluteNamesOutsideScratch(text: string, exempt: boolean): string[] {
|
|
1889
|
+
const out: string[] = [];
|
|
1890
|
+
for (const p of ALL_PROTECTED) {
|
|
1891
|
+
const words = pathWordsContaining(text, p).filter(w => w.startsWith('/'));
|
|
1892
|
+
if (words.length === 0) continue;
|
|
1893
|
+
if (exempt && words.every(isScratchPath)) continue;
|
|
1894
|
+
out.push(p);
|
|
1895
|
+
}
|
|
1896
|
+
return out;
|
|
1897
|
+
}
|
|
1898
|
+
|
|
1899
|
+
/**
|
|
1900
|
+
* The `-c`/`-e` program of an interpreter segment, with only its OUTER
|
|
1901
|
+
* quoting removed (#1277).
|
|
1902
|
+
*
|
|
1903
|
+
* `shellBody` next door `dequote`s, which is right for a shell body about to
|
|
1904
|
+
* be re-parsed as shell and wrong for every other language: it deletes the
|
|
1905
|
+
* only thing that marks where one string literal ends and the next
|
|
1906
|
+
* expression begins. `bodyTargets` is the whole point of this function, and
|
|
1907
|
+
* it cannot answer its question on a view with no quotes in it.
|
|
1908
|
+
*
|
|
1909
|
+
* An unmatched outer quote leaves the text as it stands. `bodyTargets` then
|
|
1910
|
+
* reports the body `unreadable` rather than guessing, which is the
|
|
1911
|
+
* fail-closed direction.
|
|
1912
|
+
*/
|
|
1913
|
+
export function programBody(segment: string): string {
|
|
1914
|
+
const m = /\s-[a-z]*[ce]\s+([\s\S]+)$/.exec(segment);
|
|
1915
|
+
if (!m) return '';
|
|
1916
|
+
const raw = m[1].trim();
|
|
1917
|
+
const q = raw[0];
|
|
1918
|
+
if ((q === "'" || q === '"') && raw.length > 1 && raw[raw.length - 1] === q) {
|
|
1919
|
+
return raw.slice(1, -1);
|
|
1920
|
+
}
|
|
1921
|
+
return raw;
|
|
1922
|
+
}
|
|
1923
|
+
|
|
1924
|
+
/**
|
|
1925
|
+
* A literal that STANDS ALONE as an argument is one nothing transforms, so
|
|
1926
|
+
* the path it spells is the path the program hands to the filesystem.
|
|
1927
|
+
*
|
|
1928
|
+
* Both sets are closed-world and that is the point. They enumerate what may
|
|
1929
|
+
* legally DELIMIT an argument, not what may operate on one — so a language
|
|
1930
|
+
* whose concatenation operator nobody here thought of reads as "not
|
|
1931
|
+
* delimited", which refuses. The other spelling, a denylist of operators
|
|
1932
|
+
* (`+`, `%`, `.replace`, an f-string, …), is a detector narrower than what
|
|
1933
|
+
* it detects — `.claude/rules/checks-must-be-able-to-fail.md` — and it is
|
|
1934
|
+
* what #1276's stopgap was a second attempt at.
|
|
1935
|
+
*
|
|
1936
|
+
* ## `=` and `:` ARE openers, and the rebinding question moved (#1371)
|
|
1937
|
+
|
|
1938
|
+
* A round of #1371 dropped them, on the finding that `p = "/tmp/x"` records
|
|
1939
|
+
* a target nothing then follows through its reassignment:
|
|
1940
|
+
*
|
|
1941
|
+
* p = '/tmp/fix/workflow-state.json'
|
|
1942
|
+
* p = p.replace('/tmp/fix', os.environ['RUNGATE_WORK_DIR'])
|
|
1943
|
+
* open(p, 'w').write('{}')
|
|
1944
|
+
*
|
|
1945
|
+
* Dropping them worked and was the wrong place to answer it. `inWritePosition`
|
|
1946
|
+
* answers the same question generally — a binding at statement level is an
|
|
1947
|
+
* argument of no call, so it is not a write position — and it also catches the
|
|
1948
|
+
* dict KEY, the ternary branch, and the inner call's default that the `:` drop
|
|
1949
|
+
* reached only by accident or not at all. Measured: with `inWritePosition` in
|
|
1950
|
+
* place, restoring `=` and `:` moves nothing — 0 newly blocked and 0 newly
|
|
1951
|
+
* allowed over 132,196 real commands, and the same exemption population.
|
|
1952
|
+
*
|
|
1953
|
+
* So they are restored, because two deciders answering one question are
|
|
1954
|
+
* behaviourally one, no behavioural test can tell them apart, and the next
|
|
1955
|
+
* reader deletes whichever looks redundant — the fourth shape in
|
|
1956
|
+
* `.claude/rules/checks-must-be-able-to-fail.md`. The measurement above is
|
|
1957
|
+
* exactly the evidence that they WERE two deciders.
|
|
1958
|
+
*
|
|
1959
|
+
* What this set still answers alone is ADJACENCY: `x + "/tmp/…"` has an
|
|
1960
|
+
* operator against the literal, and no question about write position can see
|
|
1961
|
+
* that.
|
|
1962
|
+
*
|
|
1963
|
+
* A closing bracket is neither an opener nor a closer. It ENDS the group the
|
|
1964
|
+
* literal sits in and leaves the outer expression still running, so the walk
|
|
1965
|
+
* steps past it and keeps asking — which is how `Path("/tmp/x")
|
|
1966
|
+
* .relative_to(…)` is told from `shutil.copy(src, "/tmp/x")`. The first
|
|
1967
|
+
* version of this stopped at the `)` and reported the pathlib spelling as a
|
|
1968
|
+
* target; its own CONTROL row caught it, and that row is in the tests.
|
|
1969
|
+
*/
|
|
1970
|
+
const ARG_OPENS = new Set(['(', ',', '[', '{', '=', ':', ';']);
|
|
1971
|
+
const ARG_CLOSES = new Set([')', ',', ']', '}', ';', ':']);
|
|
1972
|
+
const GROUP_CLOSES = new Set([')', ']', '}']);
|
|
1973
|
+
|
|
1974
|
+
export interface BodyTargets {
|
|
1975
|
+
/** Carrying literals that stand alone — the paths the program can write. */
|
|
1976
|
+
targets: string[];
|
|
1977
|
+
/** Carrying literals an expression consumes. The destination is NOT these. */
|
|
1978
|
+
fragments: string[];
|
|
1979
|
+
/**
|
|
1980
|
+
* Literals resolving inside a protected tree, whatever they spell and
|
|
1981
|
+
* whether or not anything transforms them (#1371).
|
|
1982
|
+
*
|
|
1983
|
+
* `targets` and `fragments` are both filtered by `ALL_PROTECTED`, so
|
|
1984
|
+
* `targets.every(isScratchPath)` quantifies over a set the caller chose the
|
|
1985
|
+
* membership of. This one is not filtered by a name list at all, which is
|
|
1986
|
+
* the point: the property it reports does not depend on `ALL_PROTECTED`
|
|
1987
|
+
* being complete, and completeness is what failed.
|
|
1988
|
+
*/
|
|
1989
|
+
protectedLiterals: string[];
|
|
1990
|
+
/**
|
|
1991
|
+
* Path-shaped literals the reader could NOT place — an expansion it cannot
|
|
1992
|
+
* perform, a backtick, or a relative path whose meaning depends on a
|
|
1993
|
+
* working directory. Kept on their own list rather than folded into
|
|
1994
|
+
* `protectedLiterals`, so that afterwards the reason a body was refused is
|
|
1995
|
+
* still readable: "it names a live tree" and "I could not tell" are
|
|
1996
|
+
* different facts and only one of them is a finding about the command.
|
|
1997
|
+
*/
|
|
1998
|
+
unplaceable: string[];
|
|
1999
|
+
/** The body does not read as a sequence of complete literals. */
|
|
2000
|
+
unreadable: boolean;
|
|
2001
|
+
}
|
|
2002
|
+
|
|
2003
|
+
/**
|
|
2004
|
+
* Where a literal sits, as THREE readings and not two (#1371, second round).
|
|
2005
|
+
*
|
|
2006
|
+
* The first version of this returned a boolean behind
|
|
2007
|
+
* `if (!value.startsWith('/')) return false`, and the review was right that
|
|
2008
|
+
* the word *absolute* in the remedy I was given is where the hole came
|
|
2009
|
+
* from. `~/.rungate/run`, `$HOME/.rungate/run` and `${HOME}/.claude` all
|
|
2010
|
+
* took that early exit, and the caller read `false` as **not a protected
|
|
2011
|
+
* target** rather than as **I could not place this** — a silent skip, one
|
|
2012
|
+
* layer inside the remedy for silent skips.
|
|
2013
|
+
*
|
|
2014
|
+
* The asymmetry that settles it: a false `unplaceable` costs a refused
|
|
2015
|
+
* exemption, which somebody notices and fixes. A false `elsewhere` costs a
|
|
2016
|
+
* bypass, which nobody notices.
|
|
2017
|
+
*
|
|
2018
|
+
* Expansion handles the spellings we thought of; `unplaceable` handles the
|
|
2019
|
+
* ones we did not, and it is the half that matters. Both are kept because
|
|
2020
|
+
* expansion is what stops the fail-closed half from refusing every ordinary
|
|
2021
|
+
* `~/`-spelled read.
|
|
2022
|
+
*/
|
|
2023
|
+
type Placement = 'protected' | 'unplaceable' | 'elsewhere';
|
|
2024
|
+
|
|
2025
|
+
/** A leading `~`, `$HOME` or `${HOME}`, which the runtime or shell expands. */
|
|
2026
|
+
const HOME_PREFIX = /^(?:~|\$HOME|\$\{HOME\})(?=\/|$)/;
|
|
2027
|
+
|
|
2028
|
+
/**
|
|
2029
|
+
* Path-shaped and NOT placeable: an expansion we cannot perform, a backtick,
|
|
2030
|
+
* or a relative path whose meaning depends on a working directory this
|
|
2031
|
+
* module cannot see. `isScratchPath` already gives a relative path exactly
|
|
2032
|
+
* this reading — "only an ABSOLUTE path can be placed in a tree" — so this
|
|
2033
|
+
* is that rule applied on the other side of the same question.
|
|
2034
|
+
*/
|
|
2035
|
+
const UNPLACEABLE = /[$`~]/;
|
|
2036
|
+
|
|
2037
|
+
function expandHome(value: string): string {
|
|
2038
|
+
const home = process.env.HOME || '';
|
|
2039
|
+
if (!home) return value;
|
|
2040
|
+
return value.replace(HOME_PREFIX, home);
|
|
2041
|
+
}
|
|
2042
|
+
|
|
2043
|
+
/**
|
|
2044
|
+
* One site per reading, so a mutation battery can remove the live-tree
|
|
2045
|
+
* reading without removing the fail-closed one and report which rows each
|
|
2046
|
+
* is actually holding up. Inlining either verdict at a second site would
|
|
2047
|
+
* let a refusal bypass the mutation and the rows would go green having
|
|
2048
|
+
* witnessed nothing — `.claude/rules/checks-must-be-able-to-fail.md`.
|
|
2049
|
+
*/
|
|
2050
|
+
const IN_LIVE_TREE: Placement = 'protected';
|
|
2051
|
+
const CANNOT_PLACE: Placement = 'unplaceable';
|
|
2052
|
+
|
|
2053
|
+
/**
|
|
2054
|
+
* ## The case comparison is the VOLUME's to make, and it makes it (#1371)
|
|
2055
|
+
*
|
|
2056
|
+
* The review asked for both sides of the live-tree comparison to be
|
|
2057
|
+
* case-folded, as `names()` already is, because `/Users/JHORN/…` and
|
|
2058
|
+
* `/Users/jhorn/…` are one file and two strings on this volume. It was
|
|
2059
|
+
* built, and then the mutation battery refused to witness it: removing the
|
|
2060
|
+
* fold left the SHOUTED row refused anyway, because `resolveThroughLinks`
|
|
2061
|
+
* climbs to the deepest EXISTING ancestor and `realpathSync` returns the
|
|
2062
|
+
* canonical case — `/USERS` comes back `/Users`. So the fold decided
|
|
2063
|
+
* nothing that the resolution had not already decided.
|
|
2064
|
+
*
|
|
2065
|
+
* It is not shipped, and the reason is not thrift. Two deciders answering
|
|
2066
|
+
* one question are behaviourally one, no test can tell them apart, and the
|
|
2067
|
+
* next reader deletes whichever looks redundant. And on a case-SENSITIVE
|
|
2068
|
+
* volume the fold is the wrong answer rather than a spare one: there
|
|
2069
|
+
* `/Users/JHORN/x` really is a different file, which the fold would report
|
|
2070
|
+
* as live. `names()` folds for a different situation — it matches a
|
|
2071
|
+
* basename inside a command string where nothing resolves anything.
|
|
2072
|
+
*
|
|
2073
|
+
* CI proved both halves of that, and corrected the heading this note used
|
|
2074
|
+
* to carry. It said the differential "does not exist here", measured on
|
|
2075
|
+
* macOS — and the SHOUTED row went red on the Linux runner, where
|
|
2076
|
+
* `/HOME/RUNNER/.rungate/run` is a path that does not exist and is not the
|
|
2077
|
+
* artifact. The guard was right on both volumes; the claim was macOS's,
|
|
2078
|
+
* read as universal. The row now probes the volume and asserts the verdict
|
|
2079
|
+
* tracks it in BOTH directions, so a blind `.toLowerCase()` fold reddens it
|
|
2080
|
+
* on Linux and dropping the resolution reddens it on macOS.
|
|
2081
|
+
*
|
|
2082
|
+
* #1211 / #1358 is the same QUESTION about `WorkflowStateGuard` and may
|
|
2083
|
+
* well have a different answer, because that matcher has no resolution step
|
|
2084
|
+
* to fall back on. Worth reading this note before fixing it there.
|
|
2085
|
+
*/
|
|
2086
|
+
function placeLiteral(value: string, live: string[]): Placement {
|
|
2087
|
+
const expanded = expandHome(value);
|
|
2088
|
+
// UNPLACEABLE is asked FIRST, and the order is the fix for a hole the
|
|
2089
|
+
// other way round left open (#1411 review): `"$RG"` carries no slash, so
|
|
2090
|
+
// a slash test in front of this one answered `elsewhere` — "I placed it,
|
|
2091
|
+
// and it is not protected" — for a value nothing had placed. Witnessed:
|
|
2092
|
+
// `shutil.copy("/tmp/fix/workflow-state.json", os.path.expandvars("$RG"))`
|
|
2093
|
+
// was ALLOWED before this swap and is refused after it. The slash-bearing
|
|
2094
|
+
// spelling of the same command was already refused, which is what made
|
|
2095
|
+
// the gap invisible.
|
|
2096
|
+
if (UNPLACEABLE.test(expanded)) return CANNOT_PLACE;
|
|
2097
|
+
// Not path-shaped at all: a mode string, a JSON blob, a module name. The
|
|
2098
|
+
// exemption would never apply again if these ended it.
|
|
2099
|
+
if (!expanded.includes('/')) return 'elsewhere';
|
|
2100
|
+
// A RELATIVE path-shaped literal stays `elsewhere`, and that is measured
|
|
2101
|
+
// rather than comfortable. Treating one as unplaceable costs 7 real
|
|
2102
|
+
// commands and halves the exemption population (13 segments to 6),
|
|
2103
|
+
// because `'hornjason/pai-config'` and `'./lib/x.ts'` are slash-bearing
|
|
2104
|
+
// and are not paths — and it does not even close the class it was
|
|
2105
|
+
// widened for, since `'.'` and `'x'` carry no slash at all. The honest
|
|
2106
|
+
// closure for a relative destination is `inWritePosition`, which asks
|
|
2107
|
+
// only about literals the write actually consumes.
|
|
2108
|
+
if (!expanded.startsWith('/')) return 'elsewhere';
|
|
2109
|
+
const normalised = resolve(expanded);
|
|
2110
|
+
if (inAnyTree(normalised, live)) return IN_LIVE_TREE;
|
|
2111
|
+
const real = resolveThroughLinks(normalised);
|
|
2112
|
+
// Nothing in the chain resolved, so this is a path we could not place —
|
|
2113
|
+
// not a path we placed outside the live trees. The distinction is the
|
|
2114
|
+
// whole of #1371's third round, and `isScratchPath` already notes that an
|
|
2115
|
+
// unreachable fail-OPEN in a fail-closed module reads as permission.
|
|
2116
|
+
if (real === null) return CANNOT_PLACE;
|
|
2117
|
+
// Both spellings, for the reason `protectedTrees` gives at length:
|
|
2118
|
+
// `resolve` normalises `..` and does not follow a link, so a pre-existing
|
|
2119
|
+
// symlink out of scratch is invisible to the first reading.
|
|
2120
|
+
if (inAnyTree(real, live)) return IN_LIVE_TREE;
|
|
2121
|
+
return 'elsewhere';
|
|
2122
|
+
}
|
|
2123
|
+
|
|
2124
|
+
/**
|
|
2125
|
+
* Which path literals in an interpreter body can be shown to be the write
|
|
2126
|
+
* TARGET, and which are merely fragments of an expression that computes one
|
|
2127
|
+
* (#1277).
|
|
2128
|
+
*
|
|
2129
|
+
* ## The mistake this replaces
|
|
2130
|
+
*
|
|
2131
|
+
* Every escape in this family is the same one wearing a different costume:
|
|
2132
|
+
* the exemption read a path LITERAL off the command line and treated it as
|
|
2133
|
+
* the destination. #1276 shipped a labelled stopgap — "is every absolute
|
|
2134
|
+
* literal in the body scratch" — which closed the one spelling that had been
|
|
2135
|
+
* measured and left the class open, because a computed destination need not
|
|
2136
|
+
* leave a non-scratch literal behind. Four spellings that it exempts and
|
|
2137
|
+
* this refuses are asserted in `test/bash-write-guard.test.ts`; the one that
|
|
2138
|
+
* matters least is also the one that reads worst:
|
|
2139
|
+
*
|
|
2140
|
+
* bun -e 'writeFileSync("/tmp/x/workflow-state.json"
|
|
2141
|
+
* .replace("/tmp/x", process.env.RUNGATE_WORK_DIR), "{}")'
|
|
2142
|
+
*
|
|
2143
|
+
* Every absolute literal in it is scratch. The write lands in the run store.
|
|
2144
|
+
*
|
|
2145
|
+
* ## What is asked instead
|
|
2146
|
+
*
|
|
2147
|
+
* A literal is a target only when nothing between it and the filesystem
|
|
2148
|
+
* transforms it — then, and only then, `isScratchPath` resolving it answers
|
|
2149
|
+
* the real question. A carrying literal that does NOT stand alone is not
|
|
2150
|
+
* evidence against the write, it is the ABSENCE of evidence for it, so it
|
|
2151
|
+
* ends the exemption rather than being ignored. That is the same fail-closed
|
|
2152
|
+
* reading `isScratchPath` already applies to a relative path.
|
|
2153
|
+
*
|
|
2154
|
+
* The three things this still does not do are stated rather than hidden.
|
|
2155
|
+
* It cannot see an assembled NAME (`'workflow' + '-state.json'`) — no
|
|
2156
|
+
* literal carries the artifact, so arm 3 never receives a candidate, which
|
|
2157
|
+
* is a limit of the candidate search and has its own asserted row. It does
|
|
2158
|
+
* not read a program in a FILE. And `eval` defeats it, as it defeats any
|
|
2159
|
+
* reading of a program that does not run it.
|
|
2160
|
+
*/
|
|
2161
|
+
export function bodyTargets(body: string): BodyTargets {
|
|
2162
|
+
const targets: string[] = [];
|
|
2163
|
+
const fragments: string[] = [];
|
|
2164
|
+
const protectedLiterals: string[] = [];
|
|
2165
|
+
const unplaceable: string[] = [];
|
|
2166
|
+
/** Every literal span read so far, so the backward walk can step over one. */
|
|
2167
|
+
const spans: [number, number][] = [];
|
|
2168
|
+
// Read once per body rather than once per literal: each call realpaths up
|
|
2169
|
+
// to six trees, and a body has as many literals as it likes.
|
|
2170
|
+
const live = protectedTrees();
|
|
2171
|
+
let i = 0;
|
|
2172
|
+
while (i < body.length) {
|
|
2173
|
+
const q = body[i];
|
|
2174
|
+
if (q !== "'" && q !== '"') {
|
|
2175
|
+
i++;
|
|
2176
|
+
continue;
|
|
2177
|
+
}
|
|
2178
|
+
let j = i + 1;
|
|
2179
|
+
let value = '';
|
|
2180
|
+
let closed = false;
|
|
2181
|
+
while (j < body.length) {
|
|
2182
|
+
const c = body[j];
|
|
2183
|
+
// Only a DOUBLE-quoted literal escapes. Inside single quotes a
|
|
2184
|
+
// backslash is literal in both shell and Python, and treating it as an
|
|
2185
|
+
// escape keeps the span open past its real end — #1203's defect, one
|
|
2186
|
+
// layer down.
|
|
2187
|
+
if (q === '"' && c === '\\' && j + 1 < body.length) {
|
|
2188
|
+
value += body[j + 1];
|
|
2189
|
+
j += 2;
|
|
2190
|
+
continue;
|
|
2191
|
+
}
|
|
2192
|
+
if (c === q) {
|
|
2193
|
+
closed = true;
|
|
2194
|
+
break;
|
|
2195
|
+
}
|
|
2196
|
+
value += c;
|
|
2197
|
+
j++;
|
|
2198
|
+
}
|
|
2199
|
+
// An unterminated literal means every boundary after it is a guess.
|
|
2200
|
+
if (!closed) return { targets: [], fragments: [], protectedLiterals: [], unplaceable: [], unreadable: true };
|
|
2201
|
+
spans.push([i, j]);
|
|
2202
|
+
const where = placeLiteral(value, live);
|
|
2203
|
+
if (where === 'protected') protectedLiterals.push(value);
|
|
2204
|
+
if (where === 'unplaceable') unplaceable.push(value);
|
|
2205
|
+
if (ALL_PROTECTED.some(p => value.toLowerCase().includes(p.toLowerCase()))) {
|
|
2206
|
+
const pos = standsAlone(body, i, j) ? inWritePosition(body, i, spans) : UNPROVEN;
|
|
2207
|
+
if (pos === 'destination') targets.push(value);
|
|
2208
|
+
// `argument` is deliberately in neither list — see `inWritePosition`.
|
|
2209
|
+
else if (pos === 'unproven') fragments.push(value);
|
|
2210
|
+
}
|
|
2211
|
+
i = j + 1;
|
|
2212
|
+
}
|
|
2213
|
+
return { targets, fragments, protectedLiterals, unplaceable, unreadable: false };
|
|
2214
|
+
}
|
|
2215
|
+
|
|
2216
|
+
/**
|
|
2217
|
+
* Whitespace, including a newline. See `standsAlone` for why the newline is
|
|
2218
|
+
* in here rather than carrying a rule of its own.
|
|
2219
|
+
*/
|
|
2220
|
+
const WHITESPACE = new Set([' ', '\t', '\n', '\r']);
|
|
2221
|
+
|
|
2222
|
+
/**
|
|
2223
|
+
* The callees a literal may be a direct argument of and still be the write
|
|
2224
|
+
* TARGET (#1371, second round).
|
|
2225
|
+
*
|
|
2226
|
+
* This is a WHITELIST OF POSITIONS, which is why it is allowed to exist at
|
|
2227
|
+
* all. The thing refused twice on this PR is a denylist of TRANSFORMS —
|
|
2228
|
+
* `.replace(`, `+`, `%`, an f-string — because a transform nobody listed
|
|
2229
|
+
* reads as "no transform" and the exemption holds; `Path("/tmp/x")
|
|
2230
|
+
* .relative_to(…)` is the standing proof and it is a CONTROL row. A
|
|
2231
|
+
* whitelist fails the other way: a callee nobody listed is not a recognised
|
|
2232
|
+
* write position, so the literal is a fragment and the exemption ends.
|
|
2233
|
+
*
|
|
2234
|
+
* The names are not a new list. They are the names already in
|
|
2235
|
+
* `WRITE_INTENT`, which is what makes a command a candidate for arm 3 in
|
|
2236
|
+
* the first place — so a verb missing here is a verb that never brought a
|
|
2237
|
+
* command to this question.
|
|
2238
|
+
*
|
|
2239
|
+
* `remove`, `rename`, `replace`, `unlink` and `write` are qualified rather
|
|
2240
|
+
* than matched bare: `str.replace` and `stdout.write` are not writes to a
|
|
2241
|
+
* file, and a bare match would read a transform as a write position, which
|
|
2242
|
+
* is the denylist's failure wearing a whitelist's clothes.
|
|
2243
|
+
*/
|
|
2244
|
+
const WRITE_CALLEES = new Set([
|
|
2245
|
+
'writeFileSync',
|
|
2246
|
+
'appendFileSync',
|
|
2247
|
+
'createWriteStream',
|
|
2248
|
+
'copyFileSync',
|
|
2249
|
+
'renameSync',
|
|
2250
|
+
'unlinkSync',
|
|
2251
|
+
'rmSync',
|
|
2252
|
+
'truncateSync',
|
|
2253
|
+
'write_text',
|
|
2254
|
+
'open',
|
|
2255
|
+
'dump',
|
|
2256
|
+
'copy',
|
|
2257
|
+
'copyfile',
|
|
2258
|
+
'copytree',
|
|
2259
|
+
'move',
|
|
2260
|
+
'rmtree',
|
|
2261
|
+
]);
|
|
2262
|
+
const QUALIFIED_WRITE_CALLEES = new Set([
|
|
2263
|
+
'os.remove',
|
|
2264
|
+
'os.rename',
|
|
2265
|
+
'os.replace',
|
|
2266
|
+
'os.unlink',
|
|
2267
|
+
'os.rmdir',
|
|
2268
|
+
'shutil.copy',
|
|
2269
|
+
'shutil.copyfile',
|
|
2270
|
+
'shutil.copytree',
|
|
2271
|
+
'shutil.move',
|
|
2272
|
+
'shutil.rmtree',
|
|
2273
|
+
'json.dump',
|
|
2274
|
+
]);
|
|
2275
|
+
|
|
2276
|
+
/**
|
|
2277
|
+
* WHICH argument of a recognised write call is the destination (#1411).
|
|
2278
|
+
*
|
|
2279
|
+
* Recognising the callee is not enough, because most of these take a SOURCE
|
|
2280
|
+
* as well: `shutil.copy("/tmp/fix/workflow-state.json", dest)` put a scratch
|
|
2281
|
+
* literal in `targets` while the destination was a name nothing tracks, and
|
|
2282
|
+
* `targets.every(isScratchPath)` then exempted a copy whose destination was
|
|
2283
|
+
* unknown. Witnessed allowed before this map and refused after it.
|
|
2284
|
+
*
|
|
2285
|
+
* `-1` means NO argument of that callee is ever a destination path:
|
|
2286
|
+
* `json.dump(obj, fp)` writes to a file object, and `p.write_text(data)`
|
|
2287
|
+
* writes to its RECEIVER. A literal argument of either is data, and reading
|
|
2288
|
+
* it as a target is the same defect pointed the other way.
|
|
2289
|
+
*
|
|
2290
|
+
* The default is 0 rather than "unknown", because every remaining name in
|
|
2291
|
+
* `WRITE_CALLEES` takes its path first and a name that reaches here has
|
|
2292
|
+
* already passed the whitelist.
|
|
2293
|
+
*/
|
|
2294
|
+
const DEST_INDEX = new Map<string, number>([
|
|
2295
|
+
['copy', 1],
|
|
2296
|
+
['copyfile', 1],
|
|
2297
|
+
['copytree', 1],
|
|
2298
|
+
['copyFileSync', 1],
|
|
2299
|
+
['move', 1],
|
|
2300
|
+
['rename', 1],
|
|
2301
|
+
['renameSync', 1],
|
|
2302
|
+
['replace', 1],
|
|
2303
|
+
['dump', -1],
|
|
2304
|
+
['write_text', -1],
|
|
2305
|
+
]);
|
|
2306
|
+
|
|
2307
|
+
function destIndexOf(name: string): number {
|
|
2308
|
+
const last = name.slice(name.lastIndexOf('.') + 1);
|
|
2309
|
+
const at = DEST_INDEX.get(last);
|
|
2310
|
+
return at === undefined ? 0 : at;
|
|
2311
|
+
}
|
|
2312
|
+
|
|
2313
|
+
function isWriteCallee(name: string): boolean {
|
|
2314
|
+
if (!name) return false;
|
|
2315
|
+
if (QUALIFIED_WRITE_CALLEES.has(name)) return true;
|
|
2316
|
+
const last = name.slice(name.lastIndexOf('.') + 1);
|
|
2317
|
+
return WRITE_CALLEES.has(last);
|
|
2318
|
+
}
|
|
2319
|
+
|
|
2320
|
+
/**
|
|
2321
|
+
* Is the literal beginning at `start` a DIRECT argument of a recognised
|
|
2322
|
+
* write call?
|
|
2323
|
+
*
|
|
2324
|
+
* The walk goes backwards to the opener of the group the literal sits in,
|
|
2325
|
+
* stepping over balanced groups and over literal spans already read — a
|
|
2326
|
+
* `(` inside a string is not a bracket. Three endings, and only the first
|
|
2327
|
+
* is a yes:
|
|
2328
|
+
*
|
|
2329
|
+
* a `(` at depth 0 the literal is an argument of that call; read the
|
|
2330
|
+
* callee in front of it and ask the whitelist
|
|
2331
|
+
* a `[` or `{` at 0 the literal is an element of a list or an entry
|
|
2332
|
+
* in a dict, not an argument of anything
|
|
2333
|
+
* the start of the body the literal is at statement level: a binding, a
|
|
2334
|
+
* bare expression, a dict key with no enclosing call
|
|
2335
|
+
*
|
|
2336
|
+
* This is what makes the exemption a claim about the WRITE rather than
|
|
2337
|
+
* about a path that appears somewhere near one, and it is what the two
|
|
2338
|
+
* earlier rounds were each reaching for with a cheaper instrument.
|
|
2339
|
+
*
|
|
2340
|
+
* ## Three answers, because two of them conflated placed with unreadable
|
|
2341
|
+
*
|
|
2342
|
+
* `argument` is a literal that IS a direct argument of a recognised write
|
|
2343
|
+
* call and is NOT at the destination index — `shutil.copy`'s source, or
|
|
2344
|
+
* `json.dump`'s object. A boolean had to call that `unproven`, which is a
|
|
2345
|
+
* fragment, which ends the exemption: with the index map added and two
|
|
2346
|
+
* answers available, `shutil.copy('/tmp/a/x', '/tmp/b/x')` went from
|
|
2347
|
+
* allowed to refused, and that command is the exact shape #1175 exists to
|
|
2348
|
+
* unblock. It is three CONTROL rows across three describes and all three
|
|
2349
|
+
* went red together, which is what a control is for.
|
|
2350
|
+
*
|
|
2351
|
+
* So: `destination` counts as a target, `unproven` ends the exemption, and
|
|
2352
|
+
* `argument` does neither — the literal is placed, and placed somewhere
|
|
2353
|
+
* that is not the write. A command whose ONLY literal is an `argument`
|
|
2354
|
+
* still reaches `targets.length === 0` and is refused.
|
|
2355
|
+
*/
|
|
2356
|
+
type Position = 'destination' | 'argument' | 'unproven';
|
|
2357
|
+
const IS_DESTINATION: Position = 'destination';
|
|
2358
|
+
const UNPROVEN: Position = 'unproven';
|
|
2359
|
+
|
|
2360
|
+
function inWritePosition(body: string, start: number, spans: [number, number][]): Position {
|
|
2361
|
+
let i = start - 1;
|
|
2362
|
+
let depth = 0;
|
|
2363
|
+
/** Depth-0 commas between the opener and the literal: its argument index. */
|
|
2364
|
+
let index = 0;
|
|
2365
|
+
while (i >= 0) {
|
|
2366
|
+
const span = spans.find(([s, e]) => i >= s && i <= e);
|
|
2367
|
+
if (span) {
|
|
2368
|
+
i = span[0] - 1;
|
|
2369
|
+
continue;
|
|
2370
|
+
}
|
|
2371
|
+
const c = body[i];
|
|
2372
|
+
if (c === ')' || c === ']' || c === '}') {
|
|
2373
|
+
depth++;
|
|
2374
|
+
} else if (c === '(') {
|
|
2375
|
+
if (depth === 0) {
|
|
2376
|
+
const callee = calleeBefore(body, i);
|
|
2377
|
+
if (!isWriteCallee(callee)) return UNPROVEN;
|
|
2378
|
+
return index === destIndexOf(callee) ? IS_DESTINATION : 'argument';
|
|
2379
|
+
}
|
|
2380
|
+
depth--;
|
|
2381
|
+
} else if (c === '[' || c === '{') {
|
|
2382
|
+
if (depth === 0) return UNPROVEN;
|
|
2383
|
+
depth--;
|
|
2384
|
+
} else if (c === ',') {
|
|
2385
|
+
if (depth === 0) index++;
|
|
2386
|
+
} else if (c === '?') {
|
|
2387
|
+
// A ternary BRANCH is not a destination, it is one of two candidates,
|
|
2388
|
+
// and the guard has no way to say which runs. `:` is an `ARG_OPEN`, so
|
|
2389
|
+
// the false branch read as a complete argument and the walk continued
|
|
2390
|
+
// past `?` to the write call's own paren — witnessed:
|
|
2391
|
+
// `writeFileSync(x ? d : "/tmp/fix/workflow-state.json", "{}")` was
|
|
2392
|
+
// ALLOWED, while the same command with the literal in the TRUE branch
|
|
2393
|
+
// was already refused, because `?` is not an `ARG_OPEN` and the
|
|
2394
|
+
// literal fell out as a fragment. That asymmetry is the whole finding:
|
|
2395
|
+
// one spelling of one expression was fail-closed by accident and the
|
|
2396
|
+
// other was not.
|
|
2397
|
+
if (depth === 0) return UNPROVEN;
|
|
2398
|
+
}
|
|
2399
|
+
i--;
|
|
2400
|
+
}
|
|
2401
|
+
return UNPROVEN;
|
|
2402
|
+
}
|
|
2403
|
+
|
|
2404
|
+
/** The dotted name immediately in front of an opening parenthesis. */
|
|
2405
|
+
function calleeBefore(body: string, openIndex: number): string {
|
|
2406
|
+
let i = openIndex - 1;
|
|
2407
|
+
while (i >= 0 && WHITESPACE.has(body[i])) i--;
|
|
2408
|
+
let end = i + 1;
|
|
2409
|
+
while (i >= 0 && /[A-Za-z0-9_$.]/.test(body[i])) i--;
|
|
2410
|
+
return body.slice(i + 1, end);
|
|
2411
|
+
}
|
|
2412
|
+
|
|
2413
|
+
/**
|
|
2414
|
+
* Is the literal spanning `[start, end]` a complete argument on both sides,
|
|
2415
|
+
* and is every expression ENCLOSING it also complete?
|
|
2416
|
+
*
|
|
2417
|
+
* ## A newline is whitespace, not a delimiter (#1371)
|
|
2418
|
+
*
|
|
2419
|
+
* It used to be one: a newline at the literal's own depth ENDED the
|
|
2420
|
+
* expression, on the reading that a newline ends a statement. The AI review
|
|
2421
|
+
* on #1371 found what that costs, and it is the whole of #1277 — the
|
|
2422
|
+
* headline escape, with one newline inserted:
|
|
2423
|
+
*
|
|
2424
|
+
* writeFileSync("/tmp/x/workflow-state.json"
|
|
2425
|
+
* .replace("/tmp/x", process.env.RUNGATE_WORK_DIR), "{}")
|
|
2426
|
+
*
|
|
2427
|
+
* The literal is followed by a newline, so it read as a complete argument;
|
|
2428
|
+
* the `.replace` on the next line was never looked at. Both JavaScript and
|
|
2429
|
+
* Python continue an expression across a newline, so "a newline ends a
|
|
2430
|
+
* statement" is true only of a statement nothing encloses — which this walk
|
|
2431
|
+
* cannot tell apart from a line break inside one. A detector a reformat
|
|
2432
|
+
* defeats is the second shape in
|
|
2433
|
+
* `.claude/rules/checks-must-be-able-to-fail.md`, and it defeated the exact
|
|
2434
|
+
* witness the PR was written for.
|
|
2435
|
+
*
|
|
2436
|
+
* So the walk looks THROUGH whitespace in both directions to the real
|
|
2437
|
+
* delimiter, which is the same question it was always asking. It keeps the
|
|
2438
|
+
* ordinary multi-line fixture, because looking back through a newline from
|
|
2439
|
+
* a literal that starts a line lands on the `(` or `,` that really opened
|
|
2440
|
+
* it.
|
|
2441
|
+
*
|
|
2442
|
+
* ## The LEADING half has no witness, and that is said rather than implied
|
|
2443
|
+
*
|
|
2444
|
+
* The trailing half is the escape above, executed. The leading half —
|
|
2445
|
+
* `x +\n "…"`, where a literal opening a line read as unconsumed — is
|
|
2446
|
+
* symmetry, and no harmful instance of it exists that I could write: for it
|
|
2447
|
+
* to matter the literal must be scratch AND carry a protected artifact AND
|
|
2448
|
+
* be the right operand of a concatenation, and a scratch absolute path is
|
|
2449
|
+
* not a suffix of anything. It is kept because the two halves ask one
|
|
2450
|
+
* question and an asymmetric rule invites the next reader to restore the
|
|
2451
|
+
* half that looks arbitrary. Measured cost over 131,942 real commands:
|
|
2452
|
+
* 0 newly blocked, 0 newly allowed, and the exemption population does not
|
|
2453
|
+
* move. `bodyTargets` reporting it as a fragment is asserted in the tests;
|
|
2454
|
+
* no verdict claim is made for it, because none was earned.
|
|
2455
|
+
*/
|
|
2456
|
+
function standsAlone(body: string, start: number, end: number): boolean {
|
|
2457
|
+
let a = start - 1;
|
|
2458
|
+
while (a >= 0 && WHITESPACE.has(body[a])) a--;
|
|
2459
|
+
if (a >= 0 && !ARG_OPENS.has(body[a])) return false;
|
|
2460
|
+
|
|
2461
|
+
let b = end + 1;
|
|
2462
|
+
for (;;) {
|
|
2463
|
+
while (b < body.length && WHITESPACE.has(body[b])) b++;
|
|
2464
|
+
if (b >= body.length) return true;
|
|
2465
|
+
const c = body[b];
|
|
2466
|
+
if (GROUP_CLOSES.has(c)) {
|
|
2467
|
+
b++;
|
|
2468
|
+
continue;
|
|
2469
|
+
}
|
|
2470
|
+
return ARG_CLOSES.has(c);
|
|
2471
|
+
}
|
|
2472
|
+
}
|
|
2473
|
+
|
|
2474
|
+
/**
|
|
2475
|
+
* Can every write this body could make to a protected artifact be shown to
|
|
2476
|
+
* land in a scratch tree?
|
|
2477
|
+
*
|
|
2478
|
+
* Five ways to answer no, and all five are the absence of evidence rather
|
|
2479
|
+
* than evidence of harm: the body cannot be read, a carrying literal is
|
|
2480
|
+
* consumed by an expression, the body names a live tree, the body names a
|
|
2481
|
+
* path the reader cannot PLACE, or no literal carries the artifact at all.
|
|
2482
|
+
* The exemption's job is to say YES.
|
|
2483
|
+
*
|
|
2484
|
+
* With five refusals stacked, the failure that costs us is no longer a
|
|
2485
|
+
* bypass — it is an exemption that silently never applies again, and every
|
|
2486
|
+
* refusal row stays green through exactly that. So the CONTROL rows are the
|
|
2487
|
+
* load-bearing half of the suite, and the corpus reading that matters most
|
|
2488
|
+
* is `exempt > 0`, not `newly blocked == 0`.
|
|
2489
|
+
*
|
|
2490
|
+
* ## Why the live-tree reading is a separate question (#1371)
|
|
2491
|
+
*
|
|
2492
|
+
* The last line is `every` over `targets`, and `targets` only ever receives
|
|
2493
|
+
* literals that matched `ALL_PROTECTED`. So the quantifier ranges over a set
|
|
2494
|
+
* the command's author chooses the membership of, and the two readings come
|
|
2495
|
+
* apart on a body that writes a protected artifact into scratch AND touches
|
|
2496
|
+
* a live tree under a name no list has:
|
|
2497
|
+
*
|
|
2498
|
+
* shutil.copy('/tmp/fix/workflow-state.json', '$HOME/.rungate/run')
|
|
2499
|
+
*
|
|
2500
|
+
* Every member of `targets` is scratch, so `every` says yes; the copy lands
|
|
2501
|
+
* in the run store. `main` refused this, this module allowed it until
|
|
2502
|
+
* #1371, and 50,189 real commands could not see it — an honest caller does
|
|
2503
|
+
* not write it, which is exactly who it is worth something to.
|
|
2504
|
+
*
|
|
2505
|
+
* `protectedLiterals` is the reading that does not go through a name list,
|
|
2506
|
+
* so it cannot be walked around by choosing a basename. The alternative on
|
|
2507
|
+
* the table was a second whole-body gate ANDed with this one, and it was
|
|
2508
|
+
* refused: two deciders answering one question are behaviourally one, no
|
|
2509
|
+
* test can tell them apart, and the next reader deletes the live half —
|
|
2510
|
+
* `.claude/rules/checks-must-be-able-to-fail.md`, the fourth shape.
|
|
2511
|
+
*/
|
|
2512
|
+
function bodyTargetsAreScratch(body: string): boolean {
|
|
2513
|
+
const { targets, fragments, protectedLiterals, unplaceable, unreadable } = bodyTargets(body);
|
|
2514
|
+
if (unreadable || fragments.length > 0) return false;
|
|
2515
|
+
if (protectedLiterals.length > 0 || unplaceable.length > 0) return false;
|
|
2516
|
+
if (targets.length === 0) return false;
|
|
2517
|
+
return targets.every(isScratchPath);
|
|
2518
|
+
}
|
|
2519
|
+
|
|
501
2520
|
const ALL_PROTECTED = [...PROTECTED_FILES, ...PROTECTED_HOOKS];
|
|
502
2521
|
|
|
503
2522
|
/**
|
|
@@ -508,12 +2527,53 @@ const ALL_PROTECTED = [...PROTECTED_FILES, ...PROTECTED_HOOKS];
|
|
|
508
2527
|
* reason the checks above are structural: a guard tuned so wide that people
|
|
509
2528
|
* work around it protects nothing, and four real refusals of read-only work
|
|
510
2529
|
* is already a pattern.
|
|
2530
|
+
*
|
|
2531
|
+
* `exempt` is computed once from the WHOLE command and handed down, rather
|
|
2532
|
+
* than recomputed per segment or per recursion. The command that voids the
|
|
2533
|
+
* exemption puts the `ln` in one segment and the write in another, so a
|
|
2534
|
+
* per-segment answer would never see both.
|
|
511
2535
|
*/
|
|
512
|
-
export function decideBashWrite(cmd: string, depth = 0): BashWriteDecision {
|
|
2536
|
+
export function decideBashWrite(cmd: string, depth = 0, exemptIn?: boolean): BashWriteDecision {
|
|
513
2537
|
if (!cmd) return ALLOW;
|
|
514
2538
|
// A shell body can contain a shell body. Bounded so a crafted nest costs a
|
|
515
2539
|
// fixed amount of work rather than the session.
|
|
516
2540
|
if (depth > 3) return ALLOW;
|
|
2541
|
+
const exempt = exemptIn ?? !exemptionIsVoid(cmd);
|
|
2542
|
+
|
|
2543
|
+
// #1240: a program handed to an interpreter on stdin. `stripHeredocs`
|
|
2544
|
+
// deletes the body before every arm below, and arm 3a only reads a body
|
|
2545
|
+
// back when the segment also carries `-c`/`-e` — which `bash <<'EOF'` does
|
|
2546
|
+
// not. The result was that the guard decided on the single word `bash`
|
|
2547
|
+
// while the program underneath wrote whatever it liked. Each program is
|
|
2548
|
+
// re-entered as a command in its own right, and recomputes its own
|
|
2549
|
+
// exemption: an `ln` in the body is the body's business.
|
|
2550
|
+
// A SHELL body is read as shell; anything else gets the treatment arm 3
|
|
2551
|
+
// gives a `-c` body it cannot parse — a declared write verb near the name
|
|
2552
|
+
// of a protected artifact. Reading a Python body as shell finds nothing,
|
|
2553
|
+
// which is how `python3 <<'PY'` stayed allowed after the shell spellings
|
|
2554
|
+
// were closed.
|
|
2555
|
+
for (const { shell, program } of interpreterPrograms(cmd)) {
|
|
2556
|
+
if (shell) {
|
|
2557
|
+
const inner = decideBashWrite(program, depth + 1, exempt && !exemptionIsVoid(program));
|
|
2558
|
+
if (inner.blocked) return inner;
|
|
2559
|
+
continue;
|
|
2560
|
+
}
|
|
2561
|
+
// #1277: the same target question as arm 3 below. A stdin program is
|
|
2562
|
+
// the arm 3 body reached by another route, and it had NO body gate at
|
|
2563
|
+
// all — so the `.replace` spelling #1276 closed for `-e` was still open
|
|
2564
|
+
// here, in a heredoc, for as long as the stopgap existed.
|
|
2565
|
+
const pf = absoluteNamesOutsideScratch(program, exempt && bodyTargetsAreScratch(program)).find(p =>
|
|
2566
|
+
writesNear(program, p),
|
|
2567
|
+
);
|
|
2568
|
+
if (pf) {
|
|
2569
|
+
return {
|
|
2570
|
+
blocked: true,
|
|
2571
|
+
reason:
|
|
2572
|
+
`Bash command runs an interpreter or a mutating \`find\` naming "${pf}". ` +
|
|
2573
|
+
`What it writes cannot be read off the command line, so it is refused.`,
|
|
2574
|
+
};
|
|
2575
|
+
}
|
|
2576
|
+
}
|
|
517
2577
|
|
|
518
2578
|
for (const seg of segments(cmd)) {
|
|
519
2579
|
const bare = dequote(seg); // TARGET view: contents kept
|
|
@@ -522,7 +2582,12 @@ export function decideBashWrite(cmd: string, depth = 0): BashWriteDecision {
|
|
|
522
2582
|
|
|
523
2583
|
// 1. Shell redirection and copying verbs. Never exempted by anything:
|
|
524
2584
|
// this is the arm the old allowlist sat above, which is #1120.
|
|
525
|
-
|
|
2585
|
+
// The whole command is passed so the directory test can see a `mkdir`
|
|
2586
|
+
// in an EARLIER segment (#1196 R2). Everything else is per-segment.
|
|
2587
|
+
for (const target of writeTargets(seg, cmd)) {
|
|
2588
|
+
// #1175: the target IS a path, so the tree question is asked directly
|
|
2589
|
+
// here rather than through `namesOutsideScratch`.
|
|
2590
|
+
if (exempt && isScratchPath(target)) continue;
|
|
526
2591
|
const pf = names(target, PROTECTED_FILES);
|
|
527
2592
|
if (pf) {
|
|
528
2593
|
return {
|
|
@@ -546,7 +2611,7 @@ export function decideBashWrite(cmd: string, depth = 0): BashWriteDecision {
|
|
|
546
2611
|
// text contains it, and `grep "rm -rf …"` must stay a grep.
|
|
547
2612
|
const verbView = `${word} ${code}`;
|
|
548
2613
|
if (IN_PLACE.some(p => p.test(verbView))) {
|
|
549
|
-
const pf =
|
|
2614
|
+
const pf = namesOutsideScratch(argumentsOf(seg).join(' '), ALL_PROTECTED, exempt)[0];
|
|
550
2615
|
if (pf) {
|
|
551
2616
|
return {
|
|
552
2617
|
blocked: true,
|
|
@@ -560,23 +2625,47 @@ export function decideBashWrite(cmd: string, depth = 0): BashWriteDecision {
|
|
|
560
2625
|
// this asks for a declared write verb rather than refusing every
|
|
561
2626
|
// interpreter that names a protected artifact, and for what that
|
|
562
2627
|
// concession costs.
|
|
563
|
-
const isInterpreter =
|
|
2628
|
+
const isInterpreter = isInterpreterWord(word) && /\s-[a-z]*[ce]\b/.test(code);
|
|
564
2629
|
const isMutatingFind = word === 'find' && FIND_MUTATING.test(code);
|
|
565
2630
|
|
|
566
2631
|
// 3a. A shell `-c` body is shell. Read it as shell rather than scanning
|
|
567
2632
|
// it for Node and Python idioms it will never contain (#1176).
|
|
568
|
-
if (isInterpreter &&
|
|
2633
|
+
if (isInterpreter && isShellWord(word)) {
|
|
569
2634
|
const body = shellBody(seg);
|
|
570
2635
|
if (body) {
|
|
571
|
-
const inner = decideBashWrite(body, depth + 1);
|
|
2636
|
+
const inner = decideBashWrite(body, depth + 1, exempt);
|
|
572
2637
|
if (inner.blocked) return inner;
|
|
573
2638
|
}
|
|
574
2639
|
}
|
|
575
2640
|
|
|
576
2641
|
if (isInterpreter || isMutatingFind) {
|
|
2642
|
+
// #1214 asked for a third reading here — an imported project symbol
|
|
2643
|
+
// called with a protected path — and it was built, measured and
|
|
2644
|
+
// REJECTED. See `WRITE_INTENT` for the numbers and for the one fact
|
|
2645
|
+
// that decided it.
|
|
2646
|
+
//
|
|
2647
|
+
// #1361 merge: this branch read the exemption with `bodyIsAllScratch`
|
|
2648
|
+
// (#1269). `main` has since replaced that with the TARGET question
|
|
2649
|
+
// below (#1277), which its own comment says closes the class #1269's
|
|
2650
|
+
// predicate only sampled. Main's is kept and `bodyIsAllScratch` is
|
|
2651
|
+
// deleted rather than left defined-and-uncalled — a superseded
|
|
2652
|
+
// predicate still in the file is the next reader's second decider.
|
|
2653
|
+
// #1277: the exemption asks whether the body's write TARGET can be
|
|
2654
|
+
// shown to be scratch — see `bodyTargets`. It replaces #1276's
|
|
2655
|
+
// all-absolute-literals stopgap, which this closes the class of.
|
|
2656
|
+
//
|
|
2657
|
+
// Two cases keep the plain `exempt`, because their destinations are
|
|
2658
|
+
// SHELL WORDS and not source literals, so `namesOutsideScratch`
|
|
2659
|
+
// already asks the target question of them directly: a mutating
|
|
2660
|
+
// `find`, whose operands are on the command line, and a shell `-c`
|
|
2661
|
+
// body, which arm 3a re-enters as shell. Handing either to a reader of
|
|
2662
|
+
// string literals would refuse them for having none.
|
|
2663
|
+
const bodyExempt =
|
|
2664
|
+
isMutatingFind || isShellWord(word) ? exempt : exempt && bodyTargetsAreScratch(programBody(seg));
|
|
2665
|
+
const candidates = namesOutsideScratch(bare, ALL_PROTECTED, bodyExempt);
|
|
577
2666
|
const pf = isMutatingFind
|
|
578
|
-
?
|
|
579
|
-
: (
|
|
2667
|
+
? (candidates[0] ?? null)
|
|
2668
|
+
: (candidates.find(p => writesNear(bare, p)) ?? null);
|
|
580
2669
|
if (pf) {
|
|
581
2670
|
return {
|
|
582
2671
|
blocked: true,
|
|
@@ -587,12 +2676,37 @@ export function decideBashWrite(cmd: string, depth = 0): BashWriteDecision {
|
|
|
587
2676
|
}
|
|
588
2677
|
}
|
|
589
2678
|
|
|
590
|
-
// 4. Permission changes on a
|
|
591
|
-
// verb — not merely a `chmod` somewhere in the string, which is
|
|
592
|
-
// refused four read-only commands. The target is read off `bare`,
|
|
593
|
-
// quoting the path does not hide it.
|
|
594
|
-
|
|
595
|
-
|
|
2679
|
+
// 4. Permission changes on a protected artifact. The COMMAND WORD must be
|
|
2680
|
+
// the verb — not merely a `chmod` somewhere in the string, which is
|
|
2681
|
+
// what refused four read-only commands. The target is read off `bare`,
|
|
2682
|
+
// so quoting the path does not hide it.
|
|
2683
|
+
//
|
|
2684
|
+
// #1146: the TARGET list widened from PROTECTED_HOOKS to every
|
|
2685
|
+
// protected artifact; the VERB test is untouched, and that asymmetry is
|
|
2686
|
+
// the point. There was no reason for a `chmod` on `.gate-salt` to be
|
|
2687
|
+
// allowed while a `chmod` on a `.hook.ts` was refused — mode bits are
|
|
2688
|
+
// how a file stops being writable, so a permission change on the gate
|
|
2689
|
+
// salt is a step toward writing it. Measured on the 5,059 allowed
|
|
2690
|
+
// commands naming a protected artifact, the widening newly blocks
|
|
2691
|
+
// exactly one, and that one is real:
|
|
2692
|
+
// `chmod 600 …/worktrees/agent-abbce…/hooks/lib/.gate-salt`
|
|
2693
|
+
//
|
|
2694
|
+
// #1175 composes with that widening rather than replacing it: the
|
|
2695
|
+
// target list stays `ALL_PROTECTED` and the lookup moves to
|
|
2696
|
+
// `namesOutsideScratch`, so a `chmod` on a FIXTURE in a scratch tree
|
|
2697
|
+
// is not a permission change on a protected artifact. The widened
|
|
2698
|
+
// list and the tree scoping are independent and both are kept — a
|
|
2699
|
+
// textual merge that took either side alone would have silently
|
|
2700
|
+
// dropped one of them.
|
|
2701
|
+
const permTarget =
|
|
2702
|
+
word === 'chmod' || word === 'chflags'
|
|
2703
|
+
? (namesOutsideScratch(bare, ALL_PROTECTED, exempt)[0] ?? null)
|
|
2704
|
+
: null;
|
|
2705
|
+
if (permTarget) {
|
|
2706
|
+
return {
|
|
2707
|
+
blocked: true,
|
|
2708
|
+
reason: `Permission change on protected artifact "${permTarget}" blocked. Integrity is protected.`,
|
|
2709
|
+
};
|
|
596
2710
|
}
|
|
597
2711
|
|
|
598
2712
|
// 5. The gate salt in the Keychain. Exempted by nothing — unlike `chmod`,
|