@agent-corpus/policy-manager 0.9.0 → 0.11.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.
Files changed (47) hide show
  1. package/README.md +126 -29
  2. package/dist/adapters.d.ts +3 -1
  3. package/dist/adapters.js +37 -18
  4. package/dist/classifier.d.ts +98 -0
  5. package/dist/classifier.js +343 -0
  6. package/dist/cli.js +66 -7
  7. package/dist/config.d.ts +2 -0
  8. package/dist/config.js +6 -2
  9. package/dist/evidence.d.ts +1 -0
  10. package/dist/evidence.js +60 -0
  11. package/dist/flow.d.ts +4 -0
  12. package/dist/flow.js +91 -18
  13. package/dist/gitalias.d.ts +13 -0
  14. package/dist/gitalias.js +33 -0
  15. package/dist/grants.d.ts +9 -9
  16. package/dist/grants.js +46 -30
  17. package/dist/hard.d.ts +63 -0
  18. package/dist/hard.js +1637 -0
  19. package/dist/helpers.d.ts +59 -0
  20. package/dist/helpers.js +304 -0
  21. package/dist/merged.d.ts +6 -0
  22. package/dist/merged.js +23 -0
  23. package/dist/nativerules.d.ts +44 -0
  24. package/dist/nativerules.js +653 -0
  25. package/dist/permissive.js +179 -7
  26. package/dist/policy.d.ts +12 -0
  27. package/dist/policy.js +228 -45
  28. package/dist/profile.d.ts +7 -0
  29. package/dist/profile.js +32 -1
  30. package/dist/prompt.d.ts +32 -0
  31. package/dist/prompt.js +334 -0
  32. package/dist/reads.d.ts +46 -0
  33. package/dist/reads.js +812 -0
  34. package/dist/replay.d.ts +42 -0
  35. package/dist/replay.js +174 -1
  36. package/dist/service.d.ts +12 -1
  37. package/dist/service.js +23 -6
  38. package/dist/session.d.ts +76 -13
  39. package/dist/session.js +373 -116
  40. package/dist/shell.d.ts +2 -0
  41. package/dist/shell.js +1 -1
  42. package/dist/shellscan.d.ts +58 -0
  43. package/dist/shellscan.js +395 -0
  44. package/dist/statepaths.d.ts +41 -0
  45. package/dist/statepaths.js +706 -0
  46. package/dist/types.d.ts +11 -1
  47. package/package.json +1 -1
package/dist/flow.js CHANGED
@@ -18,8 +18,12 @@ const MAX_VARIANTS = 16;
18
18
  const MAX_SUBSTITUTION_DEPTH = 3;
19
19
  /** Commands one script may be judged as; past this it is too large to verify in time. */
20
20
  const MAX_JUDGEMENTS = 400;
21
- /** No whitespace, glob, quote, expansion or tilde characters: the value is exactly one word. */
22
- const SIMPLE_VALUE = /^[A-Za-z0-9_@%+=:,./-]+$/;
21
+ /**
22
+ * No whitespace, glob, quote or expansion characters: the value is exactly one word. A `~` is
23
+ * allowed only right after a letter or digit, where no shell expands it (a Windows short name
24
+ * such as `RUNNER~1`); at the start or after `=` or `:` it would become a home directory.
25
+ */
26
+ const SIMPLE_VALUE = /^(?:[A-Za-z0-9_@%+=:,./-]|(?<=[A-Za-z0-9])~)+$/;
23
27
  const NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
24
28
  const UNSUPPORTED = "Unsupported shell syntax; expansions and subshells need human review";
25
29
  const MAX_CALL_DEPTH = 4;
@@ -30,18 +34,26 @@ const FUNCTION_MARK = "()";
30
34
  const copy = (state) => ({
31
35
  cwds: [...state.cwds],
32
36
  ...(state.failed ? { failed: [...state.failed] } : {}),
37
+ ...(state.sure ? { sure: true } : {}),
33
38
  vars: new Map(state.vars),
34
39
  funcs: new Map(state.funcs),
35
40
  });
36
41
  /** 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)
42
+ function settle(state, failure = false) {
43
+ // After `;`, a newline or `&`, a `cd` that cannot fail did not; after `||` or `!` it did.
44
+ if (state.failed && (failure || !state.sure))
39
45
  state.cwds = [...new Set([...state.cwds, ...state.failed])];
40
46
  delete state.failed;
47
+ delete state.sure;
41
48
  }
42
49
  /** Every directory either state could be in; neither input is changed. */
43
50
  function merge(a, b) {
44
- const cwds = [...a.cwds, ...(a.failed ?? []), ...b.cwds, ...(b.failed ?? [])];
51
+ const cwds = [
52
+ ...a.cwds,
53
+ ...(a.sure ? [] : (a.failed ?? [])),
54
+ ...b.cwds,
55
+ ...(b.sure ? [] : (b.failed ?? [])),
56
+ ];
45
57
  const vars = new Map();
46
58
  for (const [name, left] of a.vars) {
47
59
  if (!b.vars.has(name))
@@ -63,6 +75,10 @@ function replace(target, source) {
63
75
  target.failed = source.failed;
64
76
  else
65
77
  delete target.failed;
78
+ if (source.sure)
79
+ target.sure = true;
80
+ else
81
+ delete target.sure;
66
82
  target.vars = source.vars;
67
83
  target.funcs = source.funcs;
68
84
  }
@@ -557,6 +573,7 @@ function runSimple(ctx, node, state, stage, piped) {
557
573
  redirects,
558
574
  subs: [],
559
575
  loose,
576
+ glob: node.argv.map((word) => word.glob === true),
560
577
  ...(stdin === undefined ? {} : { stdin }),
561
578
  };
562
579
  };
@@ -646,7 +663,13 @@ function runSimple(ctx, node, state, stage, piped) {
646
663
  if (decision.decision !== "approve")
647
664
  return decision;
648
665
  ctx.box.last = decision;
649
- if (!symlinkFree(unwrap(command.argv).argv)) {
666
+ if (decision.credentialHelpers?.length) {
667
+ ctx.box.helpers ??= new Set();
668
+ for (const helper of decision.credentialHelpers)
669
+ ctx.box.helpers.add(helper);
670
+ }
671
+ // A listed credential helper only reads a secret and talks to its service.
672
+ if (!decision.credentialHelpers?.length && !symlinkFree(unwrap(command.argv).argv)) {
650
673
  if (ctx.box.script.approved)
651
674
  return human(request, "unknown", "A command that can create symlinks may run before an approved temp path");
652
675
  ctx.box.script.tainted = true;
@@ -864,6 +887,7 @@ function changeDirectory(ctx, state, piped, envs, build) {
864
887
  return human(request, "unknown", "Directory change in a loop or pipeline requires human review");
865
888
  settle(state);
866
889
  let cwds = [];
890
+ let absolute = true;
867
891
  for (const env of envs) {
868
892
  const target = build(env)
869
893
  .argv.slice(1)
@@ -871,6 +895,8 @@ function changeDirectory(ctx, state, piped, envs, build) {
871
895
  // A bare `cd` and `~` or `~/x` go to the home directory; `~user` and `-` stay with a human.
872
896
  const raw = target.length === 0 ? "~" : target[0];
873
897
  const word = raw === "~" || raw?.startsWith("~/") ? join(homedir(), raw.slice(1)) : raw;
898
+ if (!word || !isAbsolute(word))
899
+ absolute = false;
874
900
  if (target.length > 1 ||
875
901
  !word ||
876
902
  word.includes(SUBSTITUTION) ||
@@ -910,8 +936,26 @@ function changeDirectory(ctx, state, piped, envs, build) {
910
936
  }
911
937
  if (!cwds.length || cwds.length + state.cwds.length > MAX_DIRECTORIES)
912
938
  return human(request, "unknown", "Too many directory changes to verify");
913
- // `cd` can fail, so the directory it started from stays possible unless `&&` follows.
939
+ // `cd` can fail, so the directory it started from stays possible unless `&&` follows. As the
940
+ // script's first command (nothing earlier could remove it), into an absolute directory that
941
+ // exists and that this user may enter, it does not fail: the next command runs there whatever
942
+ // joins it (`cd /x && a; b`, or a newline after a here-document).
943
+ const certain = ctx.depth === 0 &&
944
+ ctx.box.current === ctx.box.first &&
945
+ absolute &&
946
+ cwds.every((dir) => {
947
+ try {
948
+ return isDirectory(dir) && (accessSync(dir, constants.X_OK), true);
949
+ }
950
+ catch {
951
+ return false;
952
+ }
953
+ });
914
954
  state.failed = state.cwds;
955
+ if (certain)
956
+ state.sure = true;
957
+ else
958
+ delete state.sure;
915
959
  state.cwds = cwds;
916
960
  ctx.box.last = result(request, "code-read", "Directory change", true);
917
961
  return undefined;
@@ -1346,6 +1390,7 @@ function runIf(ctx, node, state) {
1346
1390
  // that ends the condition did change directory. Earlier clauses are already merged in.
1347
1391
  const taken = copy(outcome.success ?? current);
1348
1392
  delete taken.failed;
1393
+ delete taken.sure;
1349
1394
  const body = runList(ctx, clause.body, taken);
1350
1395
  if (body)
1351
1396
  return body;
@@ -1420,7 +1465,9 @@ function cannotFail(ctx, node, state) {
1420
1465
  if (program !== "cd" || argv.length !== 2 || target === undefined || node !== ctx.box.first)
1421
1466
  return false;
1422
1467
  const path = target === "~" || target.startsWith("~/") ? join(homedir(), target.slice(1)) : target;
1423
- if (!path.startsWith("/") || /[*?[\]]/.test(path))
1468
+ // On Windows an absolute path starts with a drive (`C:/x` or `C:\x`), including the home directory.
1469
+ const absolute = path.startsWith("/") || (process.platform === "win32" && /^[A-Za-z]:[\\/]/.test(path));
1470
+ if (!absolute || /[*?[\]]/.test(path))
1424
1471
  return false;
1425
1472
  try {
1426
1473
  if (!statSync(path).isDirectory())
@@ -1433,8 +1480,15 @@ function cannotFail(ctx, node, state) {
1433
1480
  }
1434
1481
  }
1435
1482
  /** With `outcome`, also reports the state when the list's exit status is success. */
1483
+ /** How long one evaluation may take before it asks instead. */
1484
+ export const TIME_BUDGET_MS = 5_000;
1485
+ export const TIME_BUDGET_REASON = "Command took too long to check";
1486
+ /** When the evaluation in progress must stop, checked between commands. */
1487
+ let deadline = 0;
1436
1488
  function runList(ctx, list, state, outcome) {
1437
1489
  for (const [index, item] of list.items.entries()) {
1490
+ if (deadline && Date.now() > deadline)
1491
+ return human(ctx.request, "unknown", TIME_BUDGET_REASON);
1438
1492
  const last = index === list.items.length - 1;
1439
1493
  // Each item runs whether or not the one before it succeeded.
1440
1494
  settle(state);
@@ -1465,11 +1519,14 @@ function runList(ctx, list, state, outcome) {
1465
1519
  for (const [step, next] of rest.entries()) {
1466
1520
  running = copy(running);
1467
1521
  onlyAnd &&= next.op === "&&";
1468
- if (onlyAnd)
1522
+ if (onlyAnd) {
1469
1523
  delete running.failed;
1524
+ delete running.sure;
1525
+ }
1470
1526
  else {
1471
- settle(running);
1472
- running.cwds = [...new Set([...running.cwds, ...possible.cwds])];
1527
+ settle(running, true);
1528
+ // An `||` runs when something before it failed, a `cd` that cannot otherwise fail included.
1529
+ running.cwds = [...new Set([...running.cwds, ...possible.cwds, ...(target.failed ?? [])])];
1473
1530
  }
1474
1531
  const skipped = runPipeline(ctx, next.node, running);
1475
1532
  if (skipped)
@@ -1492,10 +1549,11 @@ function runList(ctx, list, state, outcome) {
1492
1549
  }
1493
1550
  function runPipeline(ctx, node, state) {
1494
1551
  if (node.stages.length === 1) {
1552
+ ctx.box.current = node;
1495
1553
  const refusal = runCommand(ctx, node.stages[0], state, 0, false);
1496
1554
  // `! cd x` succeeds exactly when the `cd` failed.
1497
1555
  if (node.negated)
1498
- settle(state);
1556
+ settle(state, true);
1499
1557
  return refusal;
1500
1558
  }
1501
1559
  const changed = new Set();
@@ -1536,11 +1594,26 @@ export function commandDecision(request, command, profile, depth = 0, start = [r
1536
1594
  const opening = script.items[0];
1537
1595
  if (depth === 0 && opening && !opening.background)
1538
1596
  ctx.box.first = opening.node.first;
1539
- const refusal = runList(ctx, script, {
1540
- cwds: [...start],
1541
- vars: new Map(),
1542
- funcs: new Map(),
1543
- });
1544
- return refusal ?? ctx.box.last ?? human(request, "unknown", "Empty command");
1597
+ const outer = depth === 0 && !deadline;
1598
+ if (outer)
1599
+ deadline = Date.now() + TIME_BUDGET_MS;
1600
+ let refusal;
1601
+ try {
1602
+ refusal = runList(ctx, script, {
1603
+ cwds: [...start],
1604
+ vars: new Map(),
1605
+ funcs: new Map(),
1606
+ });
1607
+ }
1608
+ finally {
1609
+ if (outer)
1610
+ deadline = 0;
1611
+ }
1612
+ if (refusal)
1613
+ return refusal;
1614
+ const last = ctx.box.last ?? human(request, "unknown", "Empty command");
1615
+ return ctx.box.helpers?.size && last.decision === "approve"
1616
+ ? { ...last, credentialHelpers: [...ctx.box.helpers] }
1617
+ : last;
1545
1618
  }
1546
1619
  //# sourceMappingURL=flow.js.map
@@ -0,0 +1,13 @@
1
+ /** Git's own subcommands. Any other word after `git` is an alias or an external `git-<name>`. */
2
+ export declare const KNOWN_GIT: Set<string>;
3
+ /**
4
+ * What `git <name>` runs when `name` is an alias, read with `git config --get alias.<name>` in
5
+ * `cwd` (repository, global and system configuration, as Git reads them). Undefined when it is
6
+ * not an alias or cannot be read. A value starting with `!` is a shell command.
7
+ */
8
+ export declare function gitAlias(cwd: string, name: string): string | undefined;
9
+ /** The directory Git runs a `!` alias in: the top level of the work tree, or `cwd` outside one. */
10
+ export declare function aliasDirectory(cwd: string): string;
11
+ /** `args` as shell words, single-quoted, the way Git appends them to a `!` alias. */
12
+ export declare function shellArgs(args: string[]): string;
13
+ //# sourceMappingURL=gitalias.d.ts.map
@@ -0,0 +1,33 @@
1
+ import { git } from "./evidence.js";
2
+ /** Git's own subcommands. Any other word after `git` is an alias or an external `git-<name>`. */
3
+ export const KNOWN_GIT = new Set("add am annotate apply archive bisect blame branch bugreport bundle cat-file check-attr check-ignore check-ref-format checkout cherry cherry-pick clean clone column commit commit-tree config count-objects credential describe diff diff-files diff-index diff-tree difftool fetch filter-branch for-each-ref format-patch fsck gc grep hash-object help init interpret-trailers log ls-files ls-remote ls-tree maintenance merge merge-base merge-file merge-tree mergetool mktag mktree mv name-rev notes prune pull push range-diff read-tree rebase reflog remote repack replace request-pull rerere reset restore rev-list rev-parse revert rm send-email shortlog show show-branch show-ref sparse-checkout stage stash status submodule switch symbolic-ref tag update-index update-ref var verify-commit verify-pack verify-tag version whatchanged worktree write-tree".split(" "));
4
+ /**
5
+ * What `git <name>` runs when `name` is an alias, read with `git config --get alias.<name>` in
6
+ * `cwd` (repository, global and system configuration, as Git reads them). Undefined when it is
7
+ * not an alias or cannot be read. A value starting with `!` is a shell command.
8
+ */
9
+ export function gitAlias(cwd, name) {
10
+ if (!/^[A-Za-z0-9][A-Za-z0-9_.-]*$/.test(name))
11
+ return undefined;
12
+ try {
13
+ const value = git(cwd, ["config", "--get", `alias.${name}`]);
14
+ return value.trim() ? value : undefined;
15
+ }
16
+ catch {
17
+ return undefined;
18
+ }
19
+ }
20
+ /** The directory Git runs a `!` alias in: the top level of the work tree, or `cwd` outside one. */
21
+ export function aliasDirectory(cwd) {
22
+ try {
23
+ return git(cwd, ["rev-parse", "--show-toplevel"]);
24
+ }
25
+ catch {
26
+ return cwd;
27
+ }
28
+ }
29
+ /** `args` as shell words, single-quoted, the way Git appends them to a `!` alias. */
30
+ export function shellArgs(args) {
31
+ return args.map((arg) => `'${arg.replace(/'/g, `'\\''`)}'`).join(" ");
32
+ }
33
+ //# sourceMappingURL=gitalias.js.map
package/dist/grants.d.ts CHANGED
@@ -3,16 +3,16 @@ import type { Decision, Request } from "./types.js";
3
3
  export declare const PROTECTED_PATH = "Protected path requires human approval";
4
4
  export declare const HUMAN_PATTERN = "Matches an organization human-approval pattern";
5
5
  /**
6
- * The scope a `--session` approval of this human decision covers, or undefined when it can only
7
- * be approved once. Credential and secret reads, possible unrecoverable loss and anything whose
8
- * targets cannot be read from the request stay one-time. Scopes:
9
- * - a protected-path write: the protected roots it touches (`<worktree>/.agent-config`);
10
- * - a humanPatterns match: the matching patterns, in the same checkout;
11
- * - any other human rule for a simple command: that exact command, same checkout.
12
- * Category unknown (the engine could not rule out loss) is approved once only.
13
- * Shell scopes need a simple command, so nothing else in the script hides behind the rule.
6
+ * The scope a session approval of this human decision covers, or undefined when it can only be
7
+ * approved once. A scope is always the same rule and the same exact target:
8
+ * - a protected-path write: the exact files it writes, in the same checkout;
9
+ * - any other rule for a simple command (a humanPatterns match included): that exact command, in
10
+ * the same checkout.
11
+ * Category unknown, sensitive or destructive, the ONCE_ONLY hard items, and anything whose targets
12
+ * cannot be read from the request are approved once only. Shell scopes need a simple command, so
13
+ * nothing else in the script hides behind the rule.
14
14
  */
15
15
  export declare function grantScope(request: Request, decision: Decision, profile: Profile): string | undefined;
16
16
  /** What a session scope covers, in words the user can check before approving it. */
17
- export declare function scopeLabel(scope: string, profile: Profile): string;
17
+ export declare function scopeLabel(scope: string, _profile: Profile): string;
18
18
  //# sourceMappingURL=grants.d.ts.map
package/dist/grants.js CHANGED
@@ -85,22 +85,46 @@ function simple(request) {
85
85
  return argv?.length ? argv : undefined;
86
86
  }
87
87
  /**
88
- * The scope a `--session` approval of this human decision covers, or undefined when it can only
89
- * be approved once. Credential and secret reads, possible unrecoverable loss and anything whose
90
- * targets cannot be read from the request stay one-time. Scopes:
91
- * - a protected-path write: the protected roots it touches (`<worktree>/.agent-config`);
92
- * - a humanPatterns match: the matching patterns, in the same checkout;
93
- * - any other human rule for a simple command: that exact command, same checkout.
94
- * Category unknown (the engine could not rule out loss) is approved once only.
95
- * Shell scopes need a simple command, so nothing else in the script hides behind the rule.
88
+ * Hard items a session grant never covers: possible unrecoverable loss, credentials, the policy
89
+ * manager's own guards, deterministic-floor items, and every file that changes what the harness
90
+ * allows (settings, hooks, permission rules, the policy profile). Each is asked every time.
91
+ */
92
+ const ONCE_ONLY = new Set([
93
+ "force-push",
94
+ "delete-unmerged-branch",
95
+ "remove-worktree-force",
96
+ "git-clean",
97
+ "credential-read",
98
+ "harness-settings",
99
+ "policy-profile",
100
+ "policy-state",
101
+ "opaque-script",
102
+ "self-approve",
103
+ "foreign-classification-record",
104
+ "cloud-write",
105
+ "repo-delete",
106
+ "publish",
107
+ "rm-outside",
108
+ ]);
109
+ /**
110
+ * The scope a session approval of this human decision covers, or undefined when it can only be
111
+ * approved once. A scope is always the same rule and the same exact target:
112
+ * - a protected-path write: the exact files it writes, in the same checkout;
113
+ * - any other rule for a simple command (a humanPatterns match included): that exact command, in
114
+ * the same checkout.
115
+ * Category unknown, sensitive or destructive, the ONCE_ONLY hard items, and anything whose targets
116
+ * cannot be read from the request are approved once only. Shell scopes need a simple command, so
117
+ * nothing else in the script hides behind the rule.
96
118
  */
97
119
  export function grantScope(request, decision, profile) {
98
120
  try {
121
+ if (decision.hard && ONCE_ONLY.has(decision.hard))
122
+ return undefined;
99
123
  if (decision.reason === PROTECTED_PATH) {
100
124
  const paths = targets(request) ?? shellPaths(request);
101
125
  if (!paths?.length)
102
126
  return undefined;
103
- const roots = new Set();
127
+ const files = new Set();
104
128
  let top;
105
129
  for (const path of paths) {
106
130
  const lexical = resolveWord(request.cwd, path);
@@ -109,28 +133,28 @@ export function grantScope(request, decision, profile) {
109
133
  const resolved = canonical(lexical);
110
134
  if (sensitive(resolved) || policyState(resolved))
111
135
  return undefined;
112
- const root = protectedRoot(resolved);
136
+ // A word that is not under a protected root (`printf test >> AGENTS.md`) is not the write.
137
+ if (!protectedRoot(resolved))
138
+ continue;
113
139
  const checkout = topLevel(resolved);
114
140
  if (top !== undefined && checkout !== top)
115
141
  return undefined;
116
142
  top = checkout;
117
- if (root)
118
- roots.add(root);
143
+ files.add(resolved);
119
144
  }
120
- return roots.size ? `protected:${[...roots].sort().join("\u0000")}` : undefined;
145
+ return files.size ? `protected:${[...files].sort().join("\u0000")}` : undefined;
121
146
  }
122
147
  const argv = simple(request);
123
148
  if (!argv)
124
149
  return undefined;
125
150
  const checkout = topLevel(request.cwd);
126
- if (decision.reason === HUMAN_PATTERN) {
127
- const joined = argv.join(" ");
128
- const matched = profile.humanPatterns.flatMap((pattern, index) => pattern.test(joined) ? [index] : []);
129
- return matched.length ? `pattern:${matched.join(",")}:${checkout}` : undefined;
151
+ if (decision.reason !== HUMAN_PATTERN) {
152
+ if (decision.category === "sensitive" ||
153
+ decision.category === "destructive" ||
154
+ decision.category === "unknown")
155
+ return undefined;
130
156
  }
131
- if (decision.category === "sensitive" ||
132
- decision.category === "destructive" ||
133
- decision.category === "unknown")
157
+ else if (!profile.humanPatterns.some((pattern) => pattern.test(argv.join(" "))))
134
158
  return undefined;
135
159
  if (argv.slice(1).some((word) => sensitive(word)))
136
160
  return undefined;
@@ -141,17 +165,9 @@ export function grantScope(request, decision, profile) {
141
165
  }
142
166
  }
143
167
  /** What a session scope covers, in words the user can check before approving it. */
144
- export function scopeLabel(scope, profile) {
168
+ export function scopeLabel(scope, _profile) {
145
169
  if (scope.startsWith("protected:"))
146
- return `writes under ${scope.slice("protected:".length).split("\u0000").join(", ")}`;
147
- if (scope.startsWith("pattern:")) {
148
- const [, indexes = "", ...checkout] = scope.split(":");
149
- const patterns = indexes
150
- .split(",")
151
- .map((index) => profile.humanPatterns[Number(index)]?.source ?? index)
152
- .join(", ");
153
- return `commands matching ${patterns} in ${checkout.join(":")}`;
154
- }
170
+ return `writes to ${scope.slice("protected:".length).split("\u0000").join(", ")}`;
155
171
  const rest = scope.slice(scope.indexOf(":[") + 1);
156
172
  const end = rest.lastIndexOf("]:");
157
173
  const argv = JSON.parse(rest.slice(0, end + 1));
package/dist/hard.d.ts ADDED
@@ -0,0 +1,63 @@
1
+ import { type Command } from "./shellscan.js";
2
+ import type { Decision, Request } from "./types.js";
3
+ /**
4
+ * Hard human items: requests that always go to a person, are never sent to the AI classifier, and
5
+ * that no classification can approve. Credentials, protected configuration, unrecoverable loss and
6
+ * the profile's humanPatterns, plus two built-in guards on the policy manager's own approvals.
7
+ */
8
+ export declare const HARD_RULES: readonly [
9
+ /** Credential or secret retrieval, and reads of credential paths. */
10
+ "credential-read",
11
+ /** Writes to harness permission and hook settings. */
12
+ "harness-settings",
13
+ /** Writes to the policy profile itself. */
14
+ "policy-profile",
15
+ /**
16
+ * Writing, moving, deleting or changing the policy service's own state (`acp-<uid>-*` in the
17
+ * temp directory: audit logs, token, socket, grants, cache). Reading the audit logs is allowed.
18
+ */
19
+ "policy-state",
20
+ /**
21
+ * A shell or interpreter that reads its script from standard input, a here-string or a file the
22
+ * policy cannot read (`cat x.sh | sh`, `sh < x.sh`, `. <(curl ...)`, `| pwsh`). A literal
23
+ * `echo`, `printf` or quoted here-document piped in is unwrapped and judged instead.
24
+ */
25
+ "opaque-script",
26
+ /** `git push --force`/`--mirror`, and `+` refspecs: they overwrite remote history. */
27
+ "force-push",
28
+ /** Deleting a local or remote branch whose commits are not verified merged. */
29
+ "delete-unmerged-branch",
30
+ /** `git worktree remove --force`/`prune`: discards a worktree's uncommitted and untracked work. */
31
+ "remove-worktree-force",
32
+ /** `git clean`: deletes untracked files. */
33
+ "git-clean",
34
+ /** A command matching the profile's `humanPatterns`. */
35
+ "human-patterns",
36
+ /**
37
+ * The deterministic floor under the classifier: cloud and infrastructure writes and deletes
38
+ * (az, aws, gcloud, kubectl, helm, terraform, pulumi...), GitHub repository, release and secret
39
+ * deletion, package publishing, and a recursive `rm` outside a linked feature worktree, the
40
+ * temp directory and the profile's scratch roots. None of these is provably recoverable.
41
+ */
42
+ "cloud-write", "repo-delete", "publish", "rm-outside",
43
+ /** Any other decision the engine filed as sensitive: protected paths and configuration. */
44
+ "protected",
45
+ /** An agent running `approve` itself. */
46
+ "self-approve",
47
+ /** A classification record for another session or CLI, or with anything added. */
48
+ "foreign-classification-record"];
49
+ export type HardRule = (typeof HARD_RULES)[number];
50
+ /** The reason of session's approve guard (an agent running `approve`). */
51
+ export declare const APPROVE_GUARD = "Only the user may approve a request, by running approve in their own terminal";
52
+ export declare const policyStatePath: (path: string) => boolean;
53
+ /** Whether a command (after wrappers) can run text as code. Unknown programs count. */
54
+ export declare function runsText(cmd: Command): boolean;
55
+ /** Whether any command of a script can run text as code, or the script could not be read. */
56
+ export declare function scriptRunsText(script: string): boolean;
57
+ /** The hard rules a shell script falls under, judged in its working directory. */
58
+ export declare function scriptRules(script: string, cwd: string, scratchRoots?: string[]): Set<HardRule>;
59
+ /** Every hard rule a decision that needs a person falls under, built-in guards first. */
60
+ export declare function hardRules(request: Request, decision: Decision, scratchRoots?: string[]): HardRule[];
61
+ /** The first hard rule a decision that needs a person falls under, or undefined. */
62
+ export declare function hardRule(request: Request, decision: Decision, scratchRoots?: string[]): HardRule | undefined;
63
+ //# sourceMappingURL=hard.d.ts.map