@agent-corpus/policy-manager 0.5.0 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/flow.js CHANGED
@@ -1,8 +1,10 @@
1
+ import { accessSync, constants, statSync } from "node:fs";
1
2
  import { homedir } from "node:os";
2
- import { basename, join, resolve } from "node:path";
3
+ import { basename, isAbsolute, join, posix, resolve } from "node:path";
4
+ import { canonical, resolveWord, UNKNOWN_CWD } from "./evidence.js";
3
5
  import { BANNED_ENV, human, redirectDecision, simpleDecision, unwrap } from "./permissive.js";
4
6
  import { result } from "./policy.js";
5
- import { parseScript, SUBSTITUTION, } from "./script.js";
7
+ import { applyParamOp, parseScript, SUBSTITUTION, } from "./script.js";
6
8
  /**
7
9
  * Walks a parsed script and judges every command that could run. The state carried along is the
8
10
  * set of directories the next command could run in and the variables whose value is known. A
@@ -20,8 +22,26 @@ const MAX_JUDGEMENTS = 400;
20
22
  const SIMPLE_VALUE = /^[A-Za-z0-9_@%+=:,./-]+$/;
21
23
  const NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
22
24
  const UNSUPPORTED = "Unsupported shell syntax; expansions and subshells need human review";
23
- const copy = (state) => ({ cwds: [...state.cwds], vars: new Map(state.vars) });
25
+ const MAX_CALL_DEPTH = 4;
26
+ /** Positional parameters: never from the environment, unknown unless `set --` or a call set them. */
27
+ const POSITIONAL = /^(?:[0-9]+|[@*])$/;
28
+ /** Prefix of an entry in an assigned-name set that stands for a function definition. */
29
+ const FUNCTION_MARK = "()";
30
+ const copy = (state) => ({
31
+ cwds: [...state.cwds],
32
+ ...(state.failed ? { failed: [...state.failed] } : {}),
33
+ vars: new Map(state.vars),
34
+ funcs: new Map(state.funcs),
35
+ });
36
+ /** The last `cd` may have failed: every directory it could have left the shell in is possible. */
37
+ function settle(state) {
38
+ if (state.failed)
39
+ state.cwds = [...new Set([...state.cwds, ...state.failed])];
40
+ delete state.failed;
41
+ }
42
+ /** Every directory either state could be in; neither input is changed. */
24
43
  function merge(a, b) {
44
+ const cwds = [...a.cwds, ...(a.failed ?? []), ...b.cwds, ...(b.failed ?? [])];
25
45
  const vars = new Map();
26
46
  for (const [name, left] of a.vars) {
27
47
  if (!b.vars.has(name))
@@ -30,11 +50,21 @@ function merge(a, b) {
30
50
  const union = left && right ? [...new Set([...left, ...right])] : null;
31
51
  vars.set(name, union && union.length <= MAX_VARIANTS ? union : null);
32
52
  }
33
- return { cwds: [...new Set([...a.cwds, ...b.cwds])], vars };
53
+ const funcs = new Map();
54
+ for (const name of new Set([...a.funcs.keys(), ...b.funcs.keys()])) {
55
+ const left = a.funcs.get(name);
56
+ funcs.set(name, left && left === b.funcs.get(name) ? left : null);
57
+ }
58
+ return { cwds: [...new Set(cwds)], vars, funcs };
34
59
  }
35
60
  function replace(target, source) {
36
61
  target.cwds = source.cwds;
62
+ if (source.failed)
63
+ target.failed = source.failed;
64
+ else
65
+ delete target.failed;
37
66
  target.vars = source.vars;
67
+ target.funcs = source.funcs;
38
68
  }
39
69
  // --- words ------------------------------------------------------------------------------------
40
70
  const isKnown = (values) => !!values?.length && values.every((v) => SIMPLE_VALUE.test(v));
@@ -60,22 +90,61 @@ const ENVIRONMENT_OK = new Set([
60
90
  "COLUMNS",
61
91
  "LINES",
62
92
  ]);
93
+ /**
94
+ * Programs whose output depends only on their literal arguments (and the directory), so a
95
+ * substitution of one can be computed: `$(dirname /a/b)` is `/a`. A function of the same name
96
+ * replaces the program, so a defined one makes the output unknown again.
97
+ */
98
+ const PURE = new Set(["dirname", "basename", "pwd"]);
99
+ const pureCache = new Map();
100
+ /** The single `dirname x`, `basename x [suffix]` or `pwd` command a substitution runs, if it is. */
101
+ function pureCommand(inner) {
102
+ let cached = pureCache.get(inner);
103
+ if (cached === undefined) {
104
+ const script = parseScript(inner);
105
+ const item = script?.items.length === 1 ? script.items[0] : undefined;
106
+ const node = item && !item.background && !item.node.rest.length ? item.node.first : undefined;
107
+ const stage = node && !node.negated && node.stages.length === 1 ? node.stages[0] : undefined;
108
+ const name = stage?.kind === "simple" ? plainText(stage.argv[0]) : undefined;
109
+ cached =
110
+ stage?.kind === "simple" &&
111
+ name !== undefined &&
112
+ PURE.has(name) &&
113
+ !stage.assigns.length &&
114
+ !stage.redirects.length &&
115
+ stage.argv.every((w) => !w.subs.length && !w.glob)
116
+ ? stage
117
+ : null;
118
+ if (pureCache.size > 256)
119
+ pureCache.clear();
120
+ pureCache.set(inner, cached);
121
+ }
122
+ return cached ?? undefined;
123
+ }
124
+ function wordNames(word, out) {
125
+ for (const part of word.parts)
126
+ if (typeof part === "object" && "name" in part)
127
+ out.add(part.name);
128
+ else if (typeof part === "object" && part.inner !== undefined) {
129
+ const pure = pureCommand(part.inner);
130
+ if (pure)
131
+ for (const w of pure.argv)
132
+ wordNames(w, out);
133
+ }
134
+ }
63
135
  function environmentRefs(ctx, words, state) {
136
+ const names = new Set();
64
137
  for (const word of words)
65
- for (const part of word.parts)
66
- if (typeof part === "object" &&
67
- "name" in part &&
68
- !state.vars.has(part.name) &&
69
- !ENVIRONMENT_OK.has(part.name))
70
- return human(ctx.request, "unknown", "An environment variable of unknown content requires human review");
138
+ wordNames(word, names);
139
+ for (const name of names)
140
+ if (!state.vars.has(name) && !ENVIRONMENT_OK.has(name) && !POSITIONAL.test(name))
141
+ return human(ctx.request, "unknown", "An environment variable of unknown content requires human review");
71
142
  return undefined;
72
143
  }
73
144
  function knownVariables(words, state) {
74
145
  const names = new Set();
75
146
  for (const word of words)
76
- for (const part of word.parts)
77
- if (typeof part === "object" && "name" in part)
78
- names.add(part.name);
147
+ wordNames(word, names);
79
148
  const known = [...names].filter((name) => isKnown(state.vars.get(name)));
80
149
  const size = (list) => list.reduce((n, k) => n * (state.vars.get(k)?.length ?? 1), 1);
81
150
  known.sort((a, b) => (state.vars.get(b)?.length ?? 0) - (state.vars.get(a)?.length ?? 0));
@@ -89,22 +158,54 @@ function combinations(known) {
89
158
  out = out.flatMap((env) => values.map((value) => ({ ...env, [name]: value })));
90
159
  return out;
91
160
  }
161
+ /** Output of a pure substitution for one choice of values, or undefined when it is unknown. */
162
+ function pureOutput(inner, known, env, state) {
163
+ const command = pureCommand(inner);
164
+ const name = command ? plainText(command.argv[0]) : undefined;
165
+ if (!command || name === undefined || state.funcs.has(name))
166
+ return undefined;
167
+ const args = [];
168
+ for (const word of command.argv.slice(1)) {
169
+ const { text } = instantiate(word, known, env, state);
170
+ if (!SIMPLE_VALUE.test(text) || text.startsWith("-"))
171
+ return undefined;
172
+ args.push(text);
173
+ }
174
+ let output;
175
+ if (name === "pwd")
176
+ output = args.length === 0 && state.cwds.length === 1 ? state.cwds[0] : "";
177
+ else if (name === "dirname" && args.length === 1)
178
+ output = posix.dirname(args[0]);
179
+ else if (name === "basename" && (args.length === 1 || args.length === 2)) {
180
+ const [path, suffix] = args;
181
+ const base = posix.basename(path);
182
+ output =
183
+ suffix && base !== suffix && base.endsWith(suffix) ? base.slice(0, -suffix.length) : base;
184
+ }
185
+ return output && SIMPLE_VALUE.test(output) ? output : undefined;
186
+ }
92
187
  /** Text of a word for one choice of variable values; unknown parts become SUBSTITUTION. */
93
- function instantiate(word, known, env) {
188
+ function instantiate(word, known, env, state) {
94
189
  let text = "";
95
190
  let loose = false;
96
191
  for (const part of word.parts) {
97
192
  if (typeof part === "string")
98
193
  text += part;
99
194
  else if ("unknown" in part) {
100
- text += SUBSTITUTION;
101
- loose ||= !part.quoted;
195
+ const output = state && part.inner !== undefined ? pureOutput(part.inner, known, env, state) : undefined;
196
+ if (output !== undefined)
197
+ text += output;
198
+ else {
199
+ text += SUBSTITUTION;
200
+ loose ||= !part.quoted;
201
+ }
102
202
  }
103
203
  else if (known.has(part.name))
104
- text += env[part.name] ?? "";
204
+ text += applyParamOp(env[part.name] ?? "", part.op);
105
205
  else {
106
206
  text += SUBSTITUTION;
107
- loose ||= !part.quoted;
207
+ // "$@" is one word per parameter even when quoted.
208
+ loose ||= !part.quoted || part.name === "@";
108
209
  }
109
210
  }
110
211
  return { text, loose };
@@ -154,11 +255,11 @@ function runRedirects(ctx, redirs, state) {
154
255
  for (const redir of redirs) {
155
256
  if (!redir.target)
156
257
  continue;
157
- const redirect = toRedirect(redir, instantiate(redir.target, known, env).text);
258
+ const redirect = toRedirect(redir, instantiate(redir.target, known, env, state).text);
158
259
  if (!redirect)
159
260
  continue;
160
261
  for (const cwd of state.cwds) {
161
- const check = redirectDecision(ctx.request, redirect, ctx.profile, cwd);
262
+ const check = redirectDecision(ctx.request, redirect, ctx.profile, cwd, fillFor(ctx, false));
162
263
  if (check)
163
264
  return check;
164
265
  }
@@ -221,14 +322,28 @@ function printTargets(args) {
221
322
  }
222
323
  return { names, unreadable: false };
223
324
  }
224
- function assignedInSimple(node, out) {
325
+ /** `$@` and `$*` are never stored, so they stay unknown (and `*` is the forget-everything mark). */
326
+ const POSITIONAL_NAMES = ["1", "2", "3", "4", "5", "6", "7", "8", "9"];
327
+ function assignedInSimple(node, out, funcs, seen) {
225
328
  if (!node.argv.length) {
226
329
  for (const a of node.assigns)
227
330
  out.add(a.name);
228
331
  return;
229
332
  }
230
- const name = basename(plainText(node.argv[0]) ?? "");
333
+ const literal = plainText(node.argv[0]);
334
+ const fn = literal === undefined ? undefined : funcs?.get(literal);
335
+ if (literal !== undefined && fn && !seen?.has(literal)) {
336
+ // A call runs the body in this shell, so what the body assigns is assigned here.
337
+ const visited = new Set([...(seen ?? []), literal]);
338
+ assignedInList(fn.body.body, out, funcs, visited);
339
+ }
340
+ else if (literal !== undefined && fn === null)
341
+ out.add("*");
342
+ const name = basename(literal ?? "");
231
343
  const args = node.argv.slice(1).map(plainText);
344
+ if (name === "set" || name === "shift")
345
+ for (const p of POSITIONAL_NAMES)
346
+ out.add(p);
232
347
  if (SPECIAL_BUILTINS.has(name))
233
348
  for (const a of node.assigns)
234
349
  out.add(a.name);
@@ -255,56 +370,72 @@ function assignedInSimple(node, out) {
255
370
  if (name === "read")
256
371
  out.add("REPLY");
257
372
  }
258
- function assignedInList(list, out) {
373
+ /**
374
+ * Names a list may assign, plus FUNCTION_MARK + name for each function it may define. With `funcs`,
375
+ * a call to a known function counts what its body assigns.
376
+ */
377
+ function assignedInList(list, out, funcs, seen) {
259
378
  for (const item of list.items) {
260
379
  const nodes = [item.node.first, ...item.node.rest.map((r) => r.node)];
261
380
  for (const node of nodes)
262
381
  for (const stage of node.stages)
263
- assignedInCommand(stage, out);
382
+ assignedInCommand(stage, out, funcs, seen);
264
383
  }
265
384
  }
266
- function assignedInCommand(command, out) {
385
+ function assignedInCommand(command, out, funcs, seen) {
386
+ const list = (l) => assignedInList(l, out, funcs, seen);
267
387
  switch (command.kind) {
268
388
  case "simple":
269
- assignedInSimple(command, out);
389
+ assignedInSimple(command, out, funcs, seen);
270
390
  return;
271
391
  case "subshell":
272
392
  case "group":
273
- assignedInList(command.body, out);
393
+ list(command.body);
274
394
  return;
275
395
  case "for":
276
396
  out.add(command.name);
277
- assignedInList(command.body, out);
397
+ list(command.body);
278
398
  return;
279
399
  case "while":
280
- assignedInList(command.cond, out);
281
- assignedInList(command.body, out);
400
+ list(command.cond);
401
+ list(command.body);
282
402
  return;
283
403
  case "if":
284
404
  for (const clause of command.clauses) {
285
- assignedInList(clause.cond, out);
286
- assignedInList(clause.body, out);
405
+ list(clause.cond);
406
+ list(clause.body);
287
407
  }
288
408
  if (command.otherwise)
289
- assignedInList(command.otherwise, out);
409
+ list(command.otherwise);
290
410
  return;
291
411
  case "case":
292
412
  for (const branch of command.branches)
293
- assignedInList(branch.body, out);
413
+ list(branch.body);
414
+ return;
415
+ case "function":
416
+ out.add(FUNCTION_MARK + command.name);
294
417
  return;
295
418
  }
296
419
  }
297
- /** An assignment to a name the analysis could not read (`*`) makes every variable unknown. */
420
+ /**
421
+ * An assignment to a name the analysis could not read (`*`) makes every variable unknown; a
422
+ * function that may have been redefined becomes uncertain.
423
+ */
298
424
  function forget(state, names) {
425
+ for (const name of names)
426
+ if (name.startsWith(FUNCTION_MARK))
427
+ state.funcs.set(name.slice(FUNCTION_MARK.length), null);
299
428
  if (names.has("*"))
300
429
  state.vars.clear();
301
430
  else
302
431
  for (const name of names)
303
- state.vars.set(name, null);
432
+ if (!name.startsWith(FUNCTION_MARK))
433
+ state.vars.set(name, null);
304
434
  }
305
435
  // --- simple commands --------------------------------------------------------------------------
306
436
  const STATEFUL = new Set([
307
437
  "cd",
438
+ "chdir",
308
439
  "pushd",
309
440
  "popd",
310
441
  "export",
@@ -330,6 +461,23 @@ function splitAssignment(word) {
330
461
  value: { ...word, parts: [first.slice(eq + 1), ...word.parts.slice(1)], subs: [] },
331
462
  };
332
463
  }
464
+ /** grep and rg options whose value is a file-name glob. */
465
+ const GLOB_VALUE_OPTIONS = {
466
+ grep: ["--include", "--exclude", "--exclude-dir"],
467
+ egrep: ["--include", "--exclude", "--exclude-dir"],
468
+ fgrep: ["--include", "--exclude", "--exclude-dir"],
469
+ rg: ["--glob", "--iglob", "-g"],
470
+ };
471
+ /**
472
+ * `--include=*.md` or rg's `-g*.ts`: the option name is literal, so expansion can only yield more
473
+ * words of the same option, never another option or program.
474
+ */
475
+ function globValuedOption(program, text) {
476
+ const options = program === undefined ? undefined : GLOB_VALUE_OPTIONS[basename(program)];
477
+ if (!options || text === undefined)
478
+ return false;
479
+ return options.some((option) => option.startsWith("--") ? text.startsWith(`${option}=`) : text.startsWith(option));
480
+ }
333
481
  function runSimple(ctx, node, state, stage, piped) {
334
482
  const { request, profile } = ctx;
335
483
  const refusal = runSubs(ctx, [
@@ -342,8 +490,10 @@ function runSimple(ctx, node, state, stage, piped) {
342
490
  // A glob in the command name or in a flag-like word expands to whatever file names exist, so
343
491
  // `r[m] -rf x` runs `rm` once a file called `rm` is there, and `--forc[e]` can become `--force`.
344
492
  const hasGlob = (word) => word.glob === true && plainText(word) !== "[" && plainText(word) !== "[[";
493
+ const program0 = plainText(node.argv[0]);
345
494
  const globbed = node.argv.find((word, index) => hasGlob(word) &&
346
- (index === 0 || word.parts.some((p) => typeof p === "string" && p.startsWith("-"))));
495
+ (index === 0 || word.parts.some((p) => typeof p === "string" && p.startsWith("-"))) &&
496
+ !(index > 0 && globValuedOption(program0, plainText(word))));
347
497
  if (globbed)
348
498
  return human(request, "unknown", "A pattern in a command name or option requires human review");
349
499
  const values = node.assigns.map((a) => a.value);
@@ -363,7 +513,7 @@ function runSimple(ctx, node, state, stage, piped) {
363
513
  const build = (env) => {
364
514
  const loose = [];
365
515
  const argv = node.argv.map((word) => {
366
- const expanded = instantiate(word, known, env);
516
+ const expanded = instantiate(word, known, env, state);
367
517
  loose.push(expanded.loose);
368
518
  return expanded.text;
369
519
  });
@@ -371,7 +521,7 @@ function runSimple(ctx, node, state, stage, piped) {
371
521
  for (const redir of node.redirects) {
372
522
  if (!redir.target)
373
523
  continue;
374
- const redirect = toRedirect(redir, instantiate(redir.target, known, env).text);
524
+ const redirect = toRedirect(redir, instantiate(redir.target, known, env, state).text);
375
525
  if (redirect)
376
526
  redirects.push(redirect);
377
527
  }
@@ -383,9 +533,9 @@ function runSimple(ctx, node, state, stage, piped) {
383
533
  if (only?.op === "<<")
384
534
  stdin = only.body ?? "";
385
535
  else if (only?.op === "<<<" && only.target)
386
- stdin = `${instantiate(only.target, known, env).text}\n`;
536
+ stdin = `${instantiate(only.target, known, env, state).text}\n`;
387
537
  return {
388
- env: node.assigns.map((a) => [a.name, instantiate(a.value, known, env).text]),
538
+ env: node.assigns.map((a) => [a.name, instantiate(a.value, known, env, state).text]),
389
539
  argv,
390
540
  redirects,
391
541
  subs: [],
@@ -395,10 +545,38 @@ function runSimple(ctx, node, state, stage, piped) {
395
545
  };
396
546
  // A builtin the analysis must track can hide behind a variable (`X=cd; $X /etc`) or a wrapper
397
547
  // that runs it in the current shell (`command cd /etc`, `time cd /etc`).
548
+ // Likewise a function: `time f` and `X=f; $X` run it, and only a direct call is followed.
398
549
  for (const env of envs) {
399
- const effective = basename(unwrap(build(env).argv).argv[0] ?? "");
550
+ const argv = build(env).argv;
551
+ const effective = basename(unwrap(argv).argv[0] ?? "");
400
552
  if (STATEFUL.has(effective) && name !== effective)
401
553
  return human(request, "unknown", "A builtin behind a variable or wrapper requires human review");
554
+ if ((state.funcs.has(effective) && literal !== effective) ||
555
+ (state.funcs.has(argv[0] ?? "") && literal !== argv[0]))
556
+ return human(request, "unknown", "A function behind a variable or wrapper requires human review");
557
+ // `unset name` removes a function when no variable has that name, and zsh has its own
558
+ // removers, so a recorded function could stop shadowing the real program.
559
+ const args = unwrap(argv).argv.slice(1);
560
+ if (state.funcs.size &&
561
+ (UNDEFINES.has(effective) ||
562
+ // bash and sh read options only before the first name: `unset touch -v` removes `touch`.
563
+ (effective === "unset" &&
564
+ !(args[0] === "-v" && args.slice(1).every((a) => !a.startsWith("-"))))))
565
+ return human(request, "unknown", "Removing a definition after defining a function requires human review");
566
+ }
567
+ if (literal !== undefined && state.funcs.has(literal)) {
568
+ const fn = state.funcs.get(literal);
569
+ if (!fn)
570
+ return human(request, "unknown", "A function that may or may not be defined here requires human review");
571
+ return callFunction(ctx, node, fn, state, known, envs);
572
+ }
573
+ if (literal === "set" && plainText(node.argv[1]) === "--" && !node.assigns.length) {
574
+ const refusal = runRedirects(ctx, node.redirects, state);
575
+ if (refusal)
576
+ return refusal;
577
+ setPositional(ctx, state, node.argv.slice(2), known, envs);
578
+ ctx.box.last = result(request, "code-read", "Positional parameters", true);
579
+ return undefined;
402
580
  }
403
581
  if (!node.argv.length) {
404
582
  // Assignments on their own, or redirections with no command.
@@ -411,17 +589,17 @@ function runSimple(ctx, node, state, stage, piped) {
411
589
  for (const redir of node.redirects) {
412
590
  if (!redir.target)
413
591
  continue;
414
- const redirect = toRedirect(redir, instantiate(redir.target, known, env).text);
592
+ const redirect = toRedirect(redir, instantiate(redir.target, known, env, state).text);
415
593
  if (!redirect)
416
594
  continue;
417
595
  for (const cwd of state.cwds) {
418
- const check = redirectDecision(request, redirect, profile, cwd);
596
+ const check = redirectDecision(request, redirect, profile, cwd, fillFor(ctx, piped));
419
597
  if (check)
420
598
  return check;
421
599
  }
422
600
  }
423
601
  for (const a of node.assigns) {
424
- const texts = envs.map((env) => instantiate(a.value, known, env).text);
602
+ const texts = envs.map((env) => instantiate(a.value, known, env, state).text);
425
603
  if (texts.length && texts.every((t) => SIMPLE_VALUE.test(t))) {
426
604
  const set = [...new Set(texts)];
427
605
  if (set.length <= MAX_VARIANTS) {
@@ -439,17 +617,35 @@ function runSimple(ctx, node, state, stage, piped) {
439
617
  for (const cwd of state.cwds) {
440
618
  if (++ctx.box.calls > MAX_JUDGEMENTS)
441
619
  return human(request, "unknown", "Too many commands to verify");
442
- const decision = simpleDecision(request, command, profile, ctx.depth, stage, cwd);
620
+ const fill = fillFor(ctx, piped);
621
+ const decision = simpleDecision(request, command, profile, ctx.depth, stage, cwd, fill);
443
622
  if (decision.decision !== "approve")
444
623
  return decision;
445
624
  ctx.box.last = decision;
625
+ if (!symlinkFree(unwrap(command.argv).argv)) {
626
+ if (ctx.box.script.approved)
627
+ return human(request, "unknown", "A command that can create symlinks may run before an approved temp path");
628
+ ctx.box.script.tainted = true;
629
+ }
630
+ for (const dir of createdDirectories(unwrap(command.argv).argv)) {
631
+ if (cwd === UNKNOWN_CWD && !isAbsolute(dir))
632
+ continue;
633
+ ctx.box.created ??= new Set();
634
+ ctx.box.created.add(resolve(cwd, dir));
635
+ }
446
636
  }
447
637
  }
448
638
  // A prefix assignment before a special builtin outlives the command in some shells.
449
639
  if (name && SPECIAL_BUILTINS.has(name))
450
640
  for (const a of node.assigns)
451
641
  state.vars.set(a.name, null);
452
- if (name === "cd")
642
+ // `shift` moves every positional parameter down, and `set` with a non-option word (`set -e
643
+ // pipefail`) replaces them; only `set --` is tracked.
644
+ if (name === "shift" || name === "set")
645
+ for (const p of POSITIONAL_NAMES)
646
+ state.vars.set(p, null);
647
+ // zsh `chdir` is `cd`; in bash it fails, which leaves the starting directory possible anyway.
648
+ if (name === "cd" || name === "chdir")
453
649
  return changeDirectory(ctx, state, piped, envs, build);
454
650
  if (name === "export")
455
651
  return exportVariables(ctx, node, state, piped, known, envs);
@@ -474,11 +670,173 @@ function runSimple(ctx, node, state, stage, piped) {
474
670
  }
475
671
  return undefined;
476
672
  }
673
+ /** In a loop, a pipeline or a background job, a later command can run first. */
674
+ function fillFor(ctx, piped) {
675
+ return { script: ctx.box.script, reorder: ctx.loop > 0 || piped || !!ctx.reorder };
676
+ }
677
+ /**
678
+ * Programs that create no symlink: they read, print, or write regular files only. Shells are here
679
+ * because the script they run is judged with the same state.
680
+ */
681
+ const SYMLINK_FREE = new Set([
682
+ ...[":", "[", "test", "true", "false", "echo", "printf", "print", "pwd", "sleep", "date"],
683
+ ...["cd", "chdir", "export", "set", "shift", "unset", "read", "local"],
684
+ ...["cat", "head", "tail", "wc", "sort", "uniq", "cut", "tr", "paste", "diff", "cmp", "jq"],
685
+ ...["grep", "egrep", "fgrep", "rg", "sed", "ls", "stat", "file", "which", "type"],
686
+ ...["basename", "dirname", "realpath", "readlink", "mkdir", "touch", "tee"],
687
+ ...["rm", "rmdir", "unlink", "bash", "sh", "zsh", "dash"],
688
+ ...["seq", "mktemp", "chmod", "find", "curl", "du", "df", "tree", "column", "nl"],
689
+ ...["tac", "rev", "comm", "join", "fold", "od", "xxd", "shasum", "sha256sum", "md5sum", "md5"],
690
+ ...["whoami", "id", "uname", "hostname"],
691
+ ]);
692
+ /** git subcommands that leave the working tree as it is, or only add a fresh `.git`. */
693
+ const GIT_SYMLINK_FREE = new Set([
694
+ ...["status", "log", "diff", "show", "add", "commit", "init", "rev-parse", "ls-files"],
695
+ ...["branch", "config", "fetch", "remote", "describe", "push", "rev-list", "merge-base"],
696
+ ...["ls-remote", "cat-file", "for-each-ref", "symbolic-ref", "shortlog", "blame", "grep"],
697
+ ]);
698
+ /** git options that run another program. */
699
+ const GIT_RUNS = /^(?:-O|--open-files-in-pager|--upload-pack|--receive-pack|--exec|--ext-diff)/;
700
+ /** gh commands that only talk to GitHub or print: `api`, or a group with one of its verbs. */
701
+ const GH_SYMLINK_FREE = {
702
+ pr: new Set(["view", "list", "diff", "checks", "status", "create", "comment", "edit", "ready"]),
703
+ issue: new Set(["view", "list", "status", "create", "comment", "edit", "close", "reopen"]),
704
+ run: new Set(["view", "list", "watch", "rerun", "cancel"]),
705
+ repo: new Set(["view", "list"]),
706
+ release: new Set(["view", "list"]),
707
+ workflow: new Set(["view", "list"]),
708
+ label: new Set(["list"]),
709
+ auth: new Set(["status"]),
710
+ search: new Set(["prs", "issues", "repos", "code", "commits"]),
711
+ };
712
+ /**
713
+ * Whether a command is known to create no symlink. Anything else may plant one anywhere, so
714
+ * later temp paths in the script are no longer trusted. `cp` without options that copy links
715
+ * (`-R`, `-a`, `-P`, `-d`, long options) writes a regular file.
716
+ */
717
+ function symlinkFree(argv) {
718
+ const [path = "", ...args] = argv;
719
+ const program = basename(path);
720
+ if (program === "cp")
721
+ return args.every((arg) => !arg.startsWith("-") || /^-[finpv]+$/.test(arg));
722
+ if (program === "git") {
723
+ // `-c` can set a pager or other program for this one command.
724
+ let index = 0;
725
+ while (args[index] === "-C" || args[index] === "--no-pager")
726
+ index += args[index] === "-C" ? 2 : 1;
727
+ const sub = args[index] ?? "";
728
+ const rest = args.slice(index + 1);
729
+ if (rest.some((arg) => GIT_RUNS.test(arg)) || (sub === "ls-remote" && rest.includes("-u")))
730
+ return false;
731
+ return GIT_SYMLINK_FREE.has(sub) || (sub === "worktree" && rest[0] === "list");
732
+ }
733
+ if (program === "gh") {
734
+ const [group = "", verb = ""] = args;
735
+ return group === "api" || !!GH_SYMLINK_FREE[group]?.has(verb);
736
+ }
737
+ return SYMLINK_FREE.has(program);
738
+ }
739
+ /** Where a loop or pipeline starts, so its end can tell whether it started a background job. */
740
+ function reorderMark(ctx) {
741
+ return { approved: ctx.box.script.approved, jobs: ctx.box.script.jobs };
742
+ }
743
+ /**
744
+ * Once a foreground loop or pipeline ends, nothing in it can run after a later command, unless
745
+ * it started a background job, which may still be running.
746
+ */
747
+ function endReorder(ctx, mark) {
748
+ if (ctx.loop === 0 && !ctx.reorder && ctx.box.script.jobs === mark.jobs)
749
+ ctx.box.script.approved = mark.approved;
750
+ }
751
+ /** git clone options that take a separate value. */
752
+ const CLONE_VALUES = new Set([
753
+ "-b",
754
+ "--branch",
755
+ "-o",
756
+ "--origin",
757
+ "-c",
758
+ "--config",
759
+ "--depth",
760
+ "--reference",
761
+ "--separate-git-dir",
762
+ "-u",
763
+ "--upload-pack",
764
+ "--template",
765
+ "-j",
766
+ "--jobs",
767
+ "--filter",
768
+ "--shallow-since",
769
+ "--shallow-exclude",
770
+ ]);
771
+ /** Positional words of `args`, skipping options and the values of those in `values`. */
772
+ function positionals(args, values) {
773
+ const out = [];
774
+ for (let index = 0; index < args.length; index++) {
775
+ const word = args[index] ?? "";
776
+ if (word === "--")
777
+ return [...out, ...args.slice(index + 1)];
778
+ if (values.has(word))
779
+ index++;
780
+ else if (!word.startsWith("-"))
781
+ out.push(word);
782
+ }
783
+ return out;
784
+ }
785
+ /**
786
+ * Directories a command creates (as written, relative to its cwd): `mkdir` (with `-p`, every
787
+ * ancestor too), `git clone <url> [dir]`, `git worktree add <path>`, and the destination of `cp -r`
788
+ * or `mv`.
789
+ */
790
+ function createdDirectories(argv) {
791
+ const [program, ...args] = argv;
792
+ if (program === "mkdir") {
793
+ const parents = args.some((arg) => arg === "--parents" || /^-[^-]*p/.test(arg));
794
+ return positionals(args, new Set(["-m", "--mode"])).flatMap((dir) => {
795
+ if (!parents)
796
+ return [dir];
797
+ const parts = dir.split("/");
798
+ return parts.map((_, index) => parts.slice(0, index + 1).join("/") || "/");
799
+ });
800
+ }
801
+ if (program === "git" && args[0] === "clone") {
802
+ const [url, dir] = positionals(args.slice(1), CLONE_VALUES);
803
+ if (dir)
804
+ return [dir];
805
+ const name = url
806
+ ?.replace(/[\\/]+$/, "")
807
+ .split(/[/:]/)
808
+ .pop()
809
+ ?.replace(/\.git$/, "");
810
+ return name ? [name] : [];
811
+ }
812
+ if (program === "git" && args[0] === "worktree" && args[1] === "add") {
813
+ const [path] = positionals(args.slice(2), new Set(["-b", "-B", "--reason"]));
814
+ return path ? [path] : [];
815
+ }
816
+ if ((program === "cp" && args.some((arg) => /^-[^-]*[rRa]/.test(arg))) || program === "mv") {
817
+ const rest = positionals(args, new Set(["-t", "-S", "--suffix"]));
818
+ return rest.length > 1 ? [rest[rest.length - 1]] : [];
819
+ }
820
+ return [];
821
+ }
822
+ /** A relative `cd` target that does not start with `.`: CDPATH and CDABLE_VARS can redirect it. */
823
+ function bareName(word) {
824
+ return !isAbsolute(word) && !/^(?:\.{1,2}(?:[\\/]|$)|[\\/])/.test(word);
825
+ }
826
+ function isDirectory(path) {
827
+ try {
828
+ return statSync(path).isDirectory();
829
+ }
830
+ catch {
831
+ return false;
832
+ }
833
+ }
477
834
  function changeDirectory(ctx, state, piped, envs, build) {
478
835
  const { request } = ctx;
479
836
  if (piped || ctx.loop > 0)
480
837
  return human(request, "unknown", "Directory change in a loop or pipeline requires human review");
481
- let cwds = [...state.cwds];
838
+ settle(state);
839
+ let cwds = [];
482
840
  for (const env of envs) {
483
841
  const target = build(env)
484
842
  .argv.slice(1)
@@ -490,13 +848,43 @@ function changeDirectory(ctx, state, piped, envs, build) {
490
848
  !word ||
491
849
  word.includes(SUBSTITUTION) ||
492
850
  /^~|[*?[\]]/.test(word) ||
493
- word.startsWith("-"))
851
+ // `-N` and zsh `+N` pick directory-stack entries.
852
+ /^[+-]/.test(word) ||
853
+ // CDPATH (from the environment the shell inherited) redirects a relative name.
854
+ (process.env.CDPATH && bareName(word)))
855
+ return human(request, "unknown", "Directory change requires human review");
856
+ // bash and zsh `cd` is logical: `..` drops the last written component. In physical mode (`cd
857
+ // -P`, `set -P`, `setopt chase_links`) it leaves the symlink's target. When the two differ, which
858
+ // one the shell uses is unknown here, so a person decides.
859
+ let next;
860
+ try {
861
+ next = state.cwds.map((cwd) => {
862
+ const logical = resolve(cwd, word);
863
+ if (canonical(logical) !== canonical(resolveWord(cwd, raw)))
864
+ throw new Error("Logical and physical directories differ");
865
+ // A bare name that is not a directory, and that no earlier command creates, fails in a
866
+ // plain shell; options set in rc files (zsh CDABLE_VARS, a CDPATH set there) can still send
867
+ // it anywhere. The shell is then somewhere unknown, so nothing relative is approved there.
868
+ // `created` is recorded when a command is judged, not when it runs; with CDABLE_VARS a
869
+ // variable of the same name wins when the directory was not made.
870
+ if (bareName(word) &&
871
+ !isDirectory(logical) &&
872
+ (!ctx.box.created?.has(logical) ||
873
+ state.vars.has(word) ||
874
+ process.env[word] !== undefined))
875
+ return UNKNOWN_CWD;
876
+ return logical;
877
+ });
878
+ }
879
+ catch {
494
880
  return human(request, "unknown", "Directory change requires human review");
495
- // `cd` can fail, so the directory it started from stays possible.
496
- cwds = [...new Set([...cwds, ...state.cwds.map((cwd) => resolve(cwd, word))])];
881
+ }
882
+ cwds = [...new Set([...cwds, ...next])];
497
883
  }
498
- if (cwds.length > MAX_DIRECTORIES)
884
+ if (!cwds.length || cwds.length + state.cwds.length > MAX_DIRECTORIES)
499
885
  return human(request, "unknown", "Too many directory changes to verify");
886
+ // `cd` can fail, so the directory it started from stays possible unless `&&` follows.
887
+ state.failed = state.cwds;
500
888
  state.cwds = cwds;
501
889
  ctx.box.last = result(request, "code-read", "Directory change", true);
502
890
  return undefined;
@@ -517,7 +905,7 @@ function exportVariables(ctx, node, state, piped, known, envs) {
517
905
  }
518
906
  if (BANNED_ENV.test(assignment.name))
519
907
  return human(request, "unknown", "Environment override requires human review");
520
- const texts = envs.map((env) => instantiate(assignment.value, known, env).text);
908
+ const texts = envs.map((env) => instantiate(assignment.value, known, env, state).text);
521
909
  if (texts.length && texts.every((t) => SIMPLE_VALUE.test(t)))
522
910
  state.vars.set(assignment.name, [...new Set(texts)]);
523
911
  else
@@ -525,8 +913,309 @@ function exportVariables(ctx, node, state, piped, known, envs) {
525
913
  }
526
914
  return undefined;
527
915
  }
916
+ // --- positional parameters and functions ------------------------------------------------------
917
+ function clearPositional(state) {
918
+ const saved = new Map();
919
+ for (const [name, values] of state.vars)
920
+ if (/^[0-9]+$/.test(name)) {
921
+ saved.set(name, values);
922
+ state.vars.delete(name);
923
+ }
924
+ return saved;
925
+ }
926
+ /**
927
+ * The values each argument word gives, in order. A word that could split into a different number
928
+ * of words (an unquoted unknown, a glob) makes every later position unknown. Known values are
929
+ * single plain words, so bash and zsh (which does not split unquoted parameters) agree.
930
+ */
931
+ function argumentSlots(words, state, known, envs) {
932
+ const slots = [];
933
+ const add = (values) => slots.push(values.size <= MAX_VARIANTS && [...values].every((v) => SIMPLE_VALUE.test(v))
934
+ ? [...values]
935
+ : null);
936
+ for (const word of words) {
937
+ const texts = envs.map((env) => instantiate(word, known, env, state));
938
+ if (word.glob || texts.some((t) => t.loose))
939
+ return slots;
940
+ add(new Set(texts.map((t) => t.text)));
941
+ }
942
+ return slots;
943
+ }
944
+ /** Stores positional values; with tracking off (the script names zsh's `argv`) they are unknown. */
945
+ function bindPositional(ctx, state, slots) {
946
+ for (const [index, values] of slots.entries())
947
+ if (index < POSITIONAL_NAMES.length)
948
+ state.vars.set(String(index + 1), ctx.positional ? values : null);
949
+ }
950
+ function setPositional(ctx, state, words, known, envs) {
951
+ const slots = argumentSlots(words, state, known, envs);
952
+ clearPositional(state);
953
+ bindPositional(ctx, state, slots);
954
+ }
955
+ /**
956
+ * A call runs the body in this shell with the arguments as positional parameters; the caller's
957
+ * parameters come back afterwards. Words were already checked by the caller.
958
+ */
959
+ function callFunction(ctx, node, fn, state, known, envs) {
960
+ const { request } = ctx;
961
+ if (node.assigns.length)
962
+ return human(request, "unknown", "An assignment before a function call requires human review");
963
+ if (ctx.calls >= MAX_CALL_DEPTH)
964
+ return human(request, "unknown", "Function calls are nested too deeply");
965
+ const refusal = runRedirects(ctx, node.redirects, state);
966
+ if (refusal)
967
+ return refusal;
968
+ const slots = argumentSlots(node.argv.slice(1), state, known, envs);
969
+ const saved = clearPositional(state);
970
+ bindPositional(ctx, state, slots);
971
+ // `return` can stop the body anywhere, so the state after the call is any point in it: what the
972
+ // body assigns is unknown, and a directory change in between cannot be followed.
973
+ const returns = mayRun(fn.body.body, new Set(["return"]), state.funcs);
974
+ const moves = mayRun(fn.body.body, new Set(["cd", "chdir", "pushd", "popd"]), state.funcs);
975
+ const inner = { ...ctx, calls: ctx.calls + 1 };
976
+ const target = fn.body.kind === "subshell" ? copy(state) : state;
977
+ const body = runList(inner, fn.body.body, target);
978
+ if (body)
979
+ return body;
980
+ if (returns && moves && fn.body.kind === "group")
981
+ return human(request, "unknown", "A function that can return early and change directory requires human review");
982
+ if (returns) {
983
+ const changed = new Set();
984
+ assignedInList(fn.body.body, changed, state.funcs);
985
+ forget(state, changed);
986
+ }
987
+ clearPositional(state);
988
+ for (const [name, values] of saved)
989
+ state.vars.set(name, values);
990
+ return undefined;
991
+ }
992
+ /**
993
+ * True when a command named in `names`, or one whose name is not a literal, may run in the list,
994
+ * including in the bodies of known functions it calls. Substitutions run in a subshell and are
995
+ * not searched.
996
+ */
997
+ function mayRun(list, names, funcs, seen = new Set()) {
998
+ const lists = (ls) => ls.some((l) => mayRun(l, names, funcs, seen));
999
+ const command = (c) => {
1000
+ switch (c.kind) {
1001
+ case "simple": {
1002
+ if (!c.argv.length)
1003
+ return false;
1004
+ const program = plainText(c.argv[0]);
1005
+ if (program === undefined || names.has(basename(program)))
1006
+ return true;
1007
+ const fn = funcs.get(program);
1008
+ if (fn === null)
1009
+ return true;
1010
+ if (fn && !seen.has(program)) {
1011
+ seen.add(program);
1012
+ return mayRun(fn.body.body, names, funcs, seen);
1013
+ }
1014
+ return c.argv.slice(1).some((w) => names.has(plainText(w) ?? ""));
1015
+ }
1016
+ // A function the body defines or redefines may be called later in it.
1017
+ case "function":
1018
+ return mayRun(c.body.body, names, funcs, seen);
1019
+ case "subshell":
1020
+ return false;
1021
+ case "group":
1022
+ return lists([c.body]);
1023
+ case "for":
1024
+ return lists([c.body]);
1025
+ case "while":
1026
+ return lists([c.cond, c.body]);
1027
+ case "if":
1028
+ return lists([
1029
+ ...c.clauses.flatMap((cl) => [cl.cond, cl.body]),
1030
+ ...(c.otherwise ? [c.otherwise] : []),
1031
+ ]);
1032
+ case "case":
1033
+ return lists(c.branches.map((b) => b.body));
1034
+ }
1035
+ };
1036
+ return list.items.some((item) =>
1037
+ // zsh runs a pipeline's last stage in this shell, so every stage is searched.
1038
+ [item.node.first, ...item.node.rest.map((r) => r.node)].some((p) => p.stages.some(command)));
1039
+ }
1040
+ /**
1041
+ * Names a shell may resolve before a function of the same name: zsh reserved words and precommand
1042
+ * modifiers, and other builtins that run or look up commands.
1043
+ */
1044
+ const NOT_A_FUNCTION = new Set([
1045
+ "time",
1046
+ "command",
1047
+ "builtin",
1048
+ "exec",
1049
+ "noglob",
1050
+ "nocorrect",
1051
+ "coproc",
1052
+ "nohup",
1053
+ "source",
1054
+ "eval",
1055
+ "type",
1056
+ "whence",
1057
+ "which",
1058
+ "hash",
1059
+ "enable",
1060
+ "disable",
1061
+ "autoload",
1062
+ "functions",
1063
+ "unfunction",
1064
+ "alias",
1065
+ ]);
1066
+ /** Builtins that can remove or replace a function definition. */
1067
+ const UNDEFINES = new Set(["unfunction", "unhash", "disable", "enable", "functions", "autoload"]);
1068
+ /**
1069
+ * Functions a shell runs with no call: zsh's special functions (zshmisc "Special Functions": the
1070
+ * hooks and TRAPxxx traps) and the not-found handlers of zsh and bash.
1071
+ */
1072
+ const SHELL_HOOK = /^(?:TRAP[A-Z0-9]+|chpwd|precmd|preexec|periodic|zshexit|zshaddhistory|command_not_found_handler|command_not_found_handle)$/;
1073
+ function defineFunction(ctx, node, state) {
1074
+ // sh and dash find a special builtin before a function, so the call would not be followed.
1075
+ if (SPECIAL_BUILTINS.has(node.name) ||
1076
+ STATEFUL.has(node.name) ||
1077
+ NOT_A_FUNCTION.has(node.name) ||
1078
+ BANNED_ENV.test(node.name))
1079
+ return human(ctx.request, "unknown", "A function named like a builtin requires human review");
1080
+ if (SHELL_HOOK.test(node.name))
1081
+ return human(ctx.request, "unknown", "A shell hook function requires human review");
1082
+ state.funcs.set(node.name, node);
1083
+ ctx.box.last = result(ctx.request, "code-read", "Function definition", true);
1084
+ return undefined;
1085
+ }
1086
+ /** Programs that never read standard input. */
1087
+ const NO_INPUT = new Set([
1088
+ "echo",
1089
+ "printf",
1090
+ "true",
1091
+ "false",
1092
+ "test",
1093
+ "[",
1094
+ ":",
1095
+ "basename",
1096
+ "dirname",
1097
+ "pwd",
1098
+ "sleep",
1099
+ "ls",
1100
+ "mkdir",
1101
+ ]);
1102
+ const GH_NO_INPUT = new Set([
1103
+ "pr view",
1104
+ "pr list",
1105
+ "pr checks",
1106
+ "pr diff",
1107
+ "issue view",
1108
+ "issue list",
1109
+ "run view",
1110
+ "run list",
1111
+ "repo view",
1112
+ "release view",
1113
+ "release list",
1114
+ ]);
1115
+ /**
1116
+ * True when nothing in the list can read the standard input it inherits. A loop body that reads
1117
+ * it would consume part of what `read` was going to see, so `read` could return any part of a line.
1118
+ */
1119
+ function readsNoInput(list, funcs) {
1120
+ const words = (w) => w.every((word) => word.subs.every((inner) => {
1121
+ const script = parseScript(inner);
1122
+ return !!script && readsNoInput(script, funcs);
1123
+ }));
1124
+ const ownInput = (redirs) => redirs.some((r) => r.fd === "0" && (r.op === "<" || r.op === "<<" || r.op === "<<<"));
1125
+ const command = (c) => {
1126
+ if (c.kind !== "function" && !words(c.redirects.flatMap((r) => (r.target ? [r.target] : []))))
1127
+ return false;
1128
+ switch (c.kind) {
1129
+ case "simple": {
1130
+ if (!words([...c.argv, ...c.assigns.map((a) => a.value)]))
1131
+ return false;
1132
+ if (!c.argv.length || ownInput(c.redirects))
1133
+ return true;
1134
+ const [program, first, second] = c.argv.slice(0, 3).map(plainText);
1135
+ if (program === undefined || funcs.has(program))
1136
+ return false;
1137
+ return NO_INPUT.has(program) || (program === "gh" && GH_NO_INPUT.has(`${first} ${second}`));
1138
+ }
1139
+ case "function":
1140
+ return true;
1141
+ case "for":
1142
+ return words(c.words) && (ownInput(c.redirects) || readsNoInput(c.body, funcs));
1143
+ case "case":
1144
+ return (words([c.word]) &&
1145
+ (ownInput(c.redirects) || c.branches.every((b) => readsNoInput(b.body, funcs))));
1146
+ case "if":
1147
+ return (ownInput(c.redirects) ||
1148
+ (c.clauses.every((cl) => readsNoInput(cl.cond, funcs) && readsNoInput(cl.body, funcs)) &&
1149
+ (!c.otherwise || readsNoInput(c.otherwise, funcs))));
1150
+ case "while":
1151
+ return (ownInput(c.redirects) || (readsNoInput(c.cond, funcs) && readsNoInput(c.body, funcs)));
1152
+ case "subshell":
1153
+ case "group":
1154
+ return ownInput(c.redirects) || readsNoInput(c.body, funcs);
1155
+ }
1156
+ };
1157
+ return list.items.every((item) => [item.node.first, ...item.node.rest.map((r) => r.node)].every((p) => p.stages.every(command)));
1158
+ }
1159
+ /**
1160
+ * `while read a b; do ...; done <<< 'literal'` (or a quoted heredoc): what `read` assigns for each
1161
+ * line of the input.
1162
+ */
1163
+ function readValues(node, state) {
1164
+ if (node.until || !readsNoInput(node.body, state.funcs))
1165
+ return undefined;
1166
+ const item = node.cond.items.length === 1 ? node.cond.items[0] : undefined;
1167
+ const pipeline = item && !item.background && !item.node.rest.length ? item.node.first : undefined;
1168
+ const stage = pipeline?.stages.length === 1 && !pipeline.negated ? pipeline.stages[0] : undefined;
1169
+ if (stage?.kind !== "simple" || stage.assigns.length || stage.redirects.length)
1170
+ return undefined;
1171
+ const args = stage.argv.map(plainText);
1172
+ if (args[0] !== "read")
1173
+ return undefined;
1174
+ const raw = args.includes("-r");
1175
+ const names = args.slice(1).filter((a) => a !== "-r");
1176
+ if (!names.length || names.some((n) => n === undefined || !NAME.test(n) || BANNED_ENV.test(n)))
1177
+ return undefined;
1178
+ const inputs = node.redirects.filter((r) => r.fd === "0");
1179
+ const input = inputs.length === 1 ? inputs[0] : undefined;
1180
+ let text;
1181
+ if (input?.op === "<<")
1182
+ text = `${input.body ?? ""}\n`;
1183
+ else if (input?.op === "<<<" && input.target) {
1184
+ const known = knownVariables([input.target], state);
1185
+ const envs = combinations(known);
1186
+ if (envs.length !== 1)
1187
+ return undefined;
1188
+ text = `${instantiate(input.target, known, envs[0], state).text}\n`;
1189
+ }
1190
+ if (text === undefined || text.includes(SUBSTITUTION) || (!raw && text.includes("\\")))
1191
+ return undefined;
1192
+ const lines = text.split("\n").slice(0, -1);
1193
+ if (!lines.length || lines.length > MAX_VARIANTS)
1194
+ return undefined;
1195
+ return lines.map((line) => {
1196
+ const out = new Map();
1197
+ let rest = line.replace(/^[ \t]+|[ \t]+$/g, "");
1198
+ for (const [index, name] of names.entries()) {
1199
+ let value = rest;
1200
+ if (index < names.length - 1) {
1201
+ const match = /^(\S*)[ \t]*(.*)$/.exec(rest);
1202
+ value = match[1];
1203
+ rest = match[2];
1204
+ }
1205
+ out.set(name, SIMPLE_VALUE.test(value) ? [value] : null);
1206
+ }
1207
+ return out;
1208
+ });
1209
+ }
528
1210
  // --- compound commands ------------------------------------------------------------------------
529
1211
  function runCommand(ctx, command, state, stage, piped) {
1212
+ // A compound command's redirections are opened before its body runs, in the directory it
1213
+ // started in; a `cd` inside the body cannot move them.
1214
+ if (command.kind !== "simple" && command.kind !== "function") {
1215
+ const early = runRedirects(ctx, command.redirects, copy(state));
1216
+ if (early)
1217
+ return early;
1218
+ }
530
1219
  switch (command.kind) {
531
1220
  case "simple":
532
1221
  return runSimple(ctx, command, state, stage, piped);
@@ -542,11 +1231,14 @@ function runCommand(ctx, command, state, stage, piped) {
542
1231
  return runIf(ctx, command, state);
543
1232
  case "case":
544
1233
  return runCase(ctx, command, state);
1234
+ case "function":
1235
+ return defineFunction(ctx, command, state);
545
1236
  }
546
1237
  }
547
1238
  function runFor(ctx, node, state) {
548
1239
  if (BANNED_ENV.test(node.name))
549
1240
  return human(ctx.request, "unknown", "Environment override requires human review");
1241
+ const mark = reorderMark(ctx);
550
1242
  const refusal = runSubs(ctx, node.words.flatMap((w) => w.subs), state);
551
1243
  if (refusal)
552
1244
  return refusal;
@@ -558,7 +1250,7 @@ function runFor(ctx, node, state) {
558
1250
  let unknown = false;
559
1251
  for (const env of combinations(known))
560
1252
  for (const word of node.words) {
561
- const text = instantiate(word, known, env).text;
1253
+ const text = instantiate(word, known, env, state).text;
562
1254
  if (SIMPLE_VALUE.test(text))
563
1255
  values.add(text);
564
1256
  else
@@ -567,26 +1259,47 @@ function runFor(ctx, node, state) {
567
1259
  if (!values.size || values.size > MAX_VARIANTS)
568
1260
  unknown = true;
569
1261
  const changed = new Set([node.name]);
570
- assignedInList(node.body, changed);
571
- const inner = copy(state);
572
- forget(inner, changed);
573
- inner.vars.set(node.name, unknown ? null : [...values]);
574
- const body = runList({ ...ctx, loop: ctx.loop + 1 }, node.body, inner);
575
- if (body)
576
- return body;
1262
+ assignedInList(node.body, changed, state.funcs);
1263
+ // Each pass is judged on its own, from a start where everything the body assigns is unknown, so
1264
+ // values that belong together (the words of one item) stay together.
1265
+ for (const value of unknown ? [null] : [...values]) {
1266
+ if (++ctx.box.calls > MAX_JUDGEMENTS)
1267
+ return human(ctx.request, "unknown", "Too many commands to verify");
1268
+ const inner = copy(state);
1269
+ forget(inner, changed);
1270
+ inner.vars.set(node.name, value === null ? null : [value]);
1271
+ const body = runList({ ...ctx, loop: ctx.loop + 1 }, node.body, inner);
1272
+ if (body)
1273
+ return body;
1274
+ }
1275
+ endReorder(ctx, mark);
577
1276
  forget(state, changed);
578
1277
  return runRedirects(ctx, node.redirects, state);
579
1278
  }
580
1279
  function runWhile(ctx, node, state) {
581
1280
  const changed = new Set();
582
- assignedInList(node.cond, changed);
583
- assignedInList(node.body, changed);
1281
+ assignedInList(node.cond, changed, state.funcs);
1282
+ assignedInList(node.body, changed, state.funcs);
584
1283
  const inner = copy(state);
585
1284
  forget(inner, changed);
1285
+ const mark = reorderMark(ctx);
586
1286
  const loop = { ...ctx, loop: ctx.loop + 1 };
587
- const refusal = runList(loop, node.cond, inner) ?? runList(loop, node.body, inner);
1287
+ const refusal = runList(loop, node.cond, inner);
588
1288
  if (refusal)
589
1289
  return refusal;
1290
+ // With literal input, each pass is judged with what `read` took from its line.
1291
+ for (const line of readValues(node, state) ?? [undefined]) {
1292
+ if (++ctx.box.calls > MAX_JUDGEMENTS)
1293
+ return human(ctx.request, "unknown", "Too many commands to verify");
1294
+ const pass = line ? copy(inner) : inner;
1295
+ if (line)
1296
+ for (const [name, values] of line)
1297
+ pass.vars.set(name, values);
1298
+ const body = runList(loop, node.body, pass);
1299
+ if (body)
1300
+ return body;
1301
+ }
1302
+ endReorder(ctx, mark);
590
1303
  forget(state, changed);
591
1304
  return runRedirects(ctx, node.redirects, state);
592
1305
  }
@@ -596,12 +1309,16 @@ function runIf(ctx, node, state) {
596
1309
  for (const [index, clause] of node.clauses.entries()) {
597
1310
  // The first condition always runs; later ones only when every earlier one failed.
598
1311
  const conditionState = index === 0 ? current : copy(current);
599
- const refusal = runList(ctx, clause.cond, conditionState);
1312
+ const outcome = {};
1313
+ const refusal = runList(ctx, clause.cond, conditionState, outcome);
600
1314
  if (refusal)
601
1315
  return refusal;
602
1316
  if (index > 0)
603
1317
  current = merge(current, conditionState);
604
- const taken = copy(current);
1318
+ // The body runs only when the condition succeeded: an `a && b` condition ran both, and a `cd`
1319
+ // that ends the condition did change directory. Earlier clauses are already merged in.
1320
+ const taken = copy(outcome.success ?? current);
1321
+ delete taken.failed;
605
1322
  const body = runList(ctx, clause.body, taken);
606
1323
  if (body)
607
1324
  return body;
@@ -641,43 +1358,128 @@ function runCase(ctx, node, state) {
641
1358
  return runRedirects(ctx, node.redirects, state);
642
1359
  }
643
1360
  // --- lists, pipelines and the entry point -----------------------------------------------------
644
- function runList(ctx, list, state) {
645
- for (const item of list.items) {
1361
+ const ASSIGNABLE = /^[A-Z][A-Z0-9_]*$/;
1362
+ /** bash and zsh variables whose assignment can fail: read-only, numeric, or tied to the process. */
1363
+ const SHELL_SPECIAL = /^(?:BASH\w*|ZSH\w*|SHELLOPTS|EUID|UID|EGID|GID|GROUPS|PPID|USERNAME|ARGC|HISTCMD|LINENO|SECONDS|EPOCH\w*|S?RANDOM|ERRNO|OPTIND|OPTARG|TTYIDLE|SHLVL|COLUMNS|LINES|HISTSIZE|HISTFILESIZE|SAVEHIST|DIRSTACKSIZE|KEYTIMEOUT|LISTMAX|LOGCHECK|MAILCHECK|PERIOD|TMOUT|TRY_BLOCK_\w+|FUNCNAME|FUNCNEST|COMP_\w+|READLINE_\w+)$/;
1364
+ /**
1365
+ * True when the pipeline always succeeds: a literal assignment, `true`, `:`,
1366
+ * or `cd` to an absolute directory that exists
1367
+ * and can be entered now. Only used to know that an `&&` chain goes on past it; the directory it
1368
+ * started from is still kept as possible.
1369
+ */
1370
+ function cannotFail(ctx, node, state) {
1371
+ const stage = node.stages.length === 1 && !node.negated ? node.stages[0] : undefined;
1372
+ if (stage?.kind !== "simple" || stage.redirects.length)
1373
+ return false;
1374
+ // `S=/x && H=y; use $H`: a bare assignment with no substitution succeeds. Only uppercase names
1375
+ // that the shell does not reserve; zsh's lowercase specials and the read-only or numeric
1376
+ // specials of bash and zsh can refuse a value.
1377
+ if (!stage.argv.length)
1378
+ return (stage.assigns.length > 0 &&
1379
+ stage.assigns.every((a) => ASSIGNABLE.test(a.name) &&
1380
+ !SHELL_SPECIAL.test(a.name) &&
1381
+ !BANNED_ENV.test(a.name) &&
1382
+ !a.value.subs.length));
1383
+ if (stage.assigns.length)
1384
+ return false;
1385
+ const argv = stage.argv.map(plainText);
1386
+ const [program, target] = argv;
1387
+ if (program === undefined || state.funcs.has(program))
1388
+ return false;
1389
+ if ((program === "true" || program === ":") && argv.length === 1)
1390
+ return true;
1391
+ // An earlier command (`mv`, a background job) could remove the directory, so only the script's
1392
+ // first command is trusted. Another process can still change it before the script runs.
1393
+ if (program !== "cd" || argv.length !== 2 || target === undefined || node !== ctx.box.first)
1394
+ return false;
1395
+ const path = target === "~" || target.startsWith("~/") ? join(homedir(), target.slice(1)) : target;
1396
+ if (!path.startsWith("/") || /[*?[\]]/.test(path))
1397
+ return false;
1398
+ try {
1399
+ if (!statSync(path).isDirectory())
1400
+ return false;
1401
+ accessSync(path, constants.X_OK);
1402
+ return true;
1403
+ }
1404
+ catch {
1405
+ return false;
1406
+ }
1407
+ }
1408
+ /** With `outcome`, also reports the state when the list's exit status is success. */
1409
+ function runList(ctx, list, state, outcome) {
1410
+ for (const [index, item] of list.items.entries()) {
1411
+ const last = index === list.items.length - 1;
1412
+ // Each item runs whether or not the one before it succeeded.
1413
+ settle(state);
646
1414
  // A background job runs in a subshell of its own.
647
1415
  const target = item.background ? copy(state) : state;
648
1416
  const { first, rest } = item.node;
649
- const refusal = runPipeline(ctx, first, target);
1417
+ if (item.background)
1418
+ ctx.box.script.jobs++;
1419
+ const refusal = runPipeline(item.background ? { ...ctx, reorder: true } : ctx, first, target);
650
1420
  if (refusal)
651
1421
  return refusal;
652
- if (!rest.length)
1422
+ if (!rest.length) {
1423
+ if (last && outcome)
1424
+ outcome.success = copy(item.background ? state : target);
653
1425
  continue;
1426
+ }
654
1427
  // In `a && b || c` each later command runs only if the ones before it did, so it sees their
655
1428
  // effects, but the chain may stop after any of them: the state afterwards is every prefix's.
1429
+ // An all-`&&` chain cannot stop after a step that cannot fail, and succeeds only at the end.
1430
+ const chain = rest.every((r) => r.op === "&&");
656
1431
  let running = copy(target);
657
1432
  let possible = copy(target);
658
- for (const next of rest) {
1433
+ // Variables after the chain: the steps it can stop after. Directories always use `possible`.
1434
+ let assigned = chain && cannotFail(ctx, first, target) ? undefined : copy(target);
1435
+ // While every operator so far is `&&`, a command runs only if everything before it succeeded,
1436
+ // so a `cd` before it did change directory. After an `||` any earlier directory is possible.
1437
+ let onlyAnd = true;
1438
+ for (const [step, next] of rest.entries()) {
659
1439
  running = copy(running);
1440
+ onlyAnd &&= next.op === "&&";
1441
+ if (onlyAnd)
1442
+ delete running.failed;
1443
+ else {
1444
+ settle(running);
1445
+ running.cwds = [...new Set([...running.cwds, ...possible.cwds])];
1446
+ }
660
1447
  const skipped = runPipeline(ctx, next.node, running);
661
1448
  if (skipped)
662
1449
  return skipped;
663
1450
  possible = merge(possible, running);
1451
+ if (!chain || step === rest.length - 1 || !cannotFail(ctx, next.node, running))
1452
+ assigned = assigned ? merge(assigned, running) : copy(running);
664
1453
  if (possible.cwds.length > MAX_DIRECTORIES)
665
1454
  return human(ctx.request, "unknown", "Too many directory changes to verify");
666
1455
  }
1456
+ if (assigned) {
1457
+ possible.vars = assigned.vars;
1458
+ possible.funcs = assigned.funcs;
1459
+ }
1460
+ if (last && outcome)
1461
+ outcome.success = copy(item.background ? state : chain ? running : possible);
667
1462
  replace(target, possible);
668
1463
  }
669
1464
  return undefined;
670
1465
  }
671
1466
  function runPipeline(ctx, node, state) {
672
- if (node.stages.length === 1)
673
- return runCommand(ctx, node.stages[0], state, 0, false);
1467
+ if (node.stages.length === 1) {
1468
+ const refusal = runCommand(ctx, node.stages[0], state, 0, false);
1469
+ // `! cd x` succeeds exactly when the `cd` failed.
1470
+ if (node.negated)
1471
+ settle(state);
1472
+ return refusal;
1473
+ }
674
1474
  const changed = new Set();
1475
+ const mark = reorderMark(ctx);
675
1476
  for (const [index, stage] of node.stages.entries()) {
676
- assignedInCommand(stage, changed);
1477
+ assignedInCommand(stage, changed, state.funcs);
677
1478
  const refusal = runCommand(ctx, stage, copy(state), index, true);
678
1479
  if (refusal)
679
1480
  return refusal;
680
1481
  }
1482
+ endReorder(ctx, mark);
681
1483
  // The last stage may run in the current shell, so what the stages assign is unknown afterwards.
682
1484
  forget(state, changed);
683
1485
  return undefined;
@@ -687,12 +1489,24 @@ function runPipeline(ctx, node, state) {
687
1489
  * directory it could run in (before and after the `cd`, since `cd x || ...` may fail), so a command
688
1490
  * that only looks safe relative to the starting directory cannot hide behind a `cd`.
689
1491
  */
690
- export function commandDecision(request, command, profile, depth = 0, start = [request.cwd]) {
1492
+ export function commandDecision(request, command, profile, depth = 0, start = [request.cwd], fill) {
691
1493
  const script = parseScript(command);
692
1494
  if (!script)
693
1495
  return human(request, "unknown", UNSUPPORTED);
694
- const ctx = { request, profile, depth, loop: 0, box: { calls: 0 } };
695
- const refusal = runList(ctx, script, { cwds: [...start], vars: new Map() });
1496
+ const ctx = {
1497
+ request,
1498
+ profile,
1499
+ depth,
1500
+ loop: 0,
1501
+ calls: 0,
1502
+ positional: !/argv/.test(command),
1503
+ box: { calls: 0, script: fill?.script ?? { tainted: false, approved: false, jobs: 0 } },
1504
+ ...(fill?.reorder ? { reorder: true } : {}),
1505
+ };
1506
+ const opening = script.items[0];
1507
+ if (depth === 0 && opening && !opening.background)
1508
+ ctx.box.first = opening.node.first;
1509
+ const refusal = runList(ctx, script, { cwds: [...start], vars: new Map(), funcs: new Map() });
696
1510
  return refusal ?? ctx.box.last ?? human(request, "unknown", "Empty command");
697
1511
  }
698
1512
  //# sourceMappingURL=flow.js.map