@venizia/vulcan 0.4.10-20 → 0.4.10-21
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/base/claude/settings.json +5 -5
- package/base/extensions/vulcan-guards.ts +79 -17
- package/base/hooks/guard-git.ts +59 -11
- package/base/hooks/guard-outside.ts +75 -14
- package/base/hooks/guard-writes.ts +5 -1
- package/package.json +3 -3
- package/src/agents/codex-hooks.ts +1 -1
- package/src/agents/hooks-json.ts +22 -3
- package/src/common/env-variables.ts +4 -0
- package/src/config/schema.ts +33 -3
- package/src/hooks/common/constants.ts +26 -0
- package/src/hooks/common/types.ts +2 -0
- package/src/hooks/decision.ts +30 -12
- package/src/hooks/guard-outside.ts +53 -1
- package/src/hooks/guard-writes.ts +3 -1
- package/src/hooks/project-guards.ts +54 -6
- package/src/hooks/shell-writes.ts +72 -0
- package/src/manifest/render.ts +3 -2
|
@@ -8,7 +8,7 @@
|
|
|
8
8
|
"hooks": [
|
|
9
9
|
{
|
|
10
10
|
"type": "command",
|
|
11
|
-
"command": "f=\"${CLAUDE_PROJECT_DIR:-$PWD}/node_modules/@venizia/vulcan/base/hooks/session-start.ts\"; if [ -f \"$f\" ] && command -v bun >/dev/null 2>&1; then bun \"$f\"; s=$?; [ \"$s\" -eq 0 ] && exit 0; exit 2; fi; if [ ! -f \"$f\" ] && [ -f \"${f%/*/*/*}/package.json\" ]; then echo \"vulcan: the session-start hook is not in this node_modules/@venizia/vulcan - the call passes; run bun node_modules/.bin/vulcan sync to drop its entry\" >&2; exit 0; fi; [ -f \"$f\" ] || echo \"vulcan: the session-start hook cannot run: node_modules/@venizia/vulcan is missing - run bun install\" >&2; command -v bun >/dev/null 2>&1 || echo \"vulcan: the session-start hook cannot run: bun is not on PATH - put bun on PATH (Claude Code may have started without your shell's PATH)\" >&2; exit 2"
|
|
11
|
+
"command": "f=\"${CLAUDE_PROJECT_DIR:-$PWD}/node_modules/@venizia/vulcan/base/hooks/session-start.ts\"; if [ -f \"$f\" ] && command -v bun >/dev/null 2>&1; then bun --no-env-file --config=/dev/null \"$f\"; s=$?; [ \"$s\" -eq 0 ] && exit 0; exit 2; fi; if [ ! -f \"$f\" ] && [ -f \"${f%/*/*/*}/package.json\" ]; then echo \"vulcan: the session-start hook is not in this node_modules/@venizia/vulcan - the call passes; run bun node_modules/.bin/vulcan sync to drop its entry\" >&2; exit 0; fi; [ -f \"$f\" ] || echo \"vulcan: the session-start hook cannot run: node_modules/@venizia/vulcan is missing - run bun install\" >&2; command -v bun >/dev/null 2>&1 || echo \"vulcan: the session-start hook cannot run: bun is not on PATH - put bun on PATH (Claude Code may have started without your shell's PATH)\" >&2; exit 2"
|
|
12
12
|
}
|
|
13
13
|
]
|
|
14
14
|
}
|
|
@@ -19,7 +19,7 @@
|
|
|
19
19
|
"hooks": [
|
|
20
20
|
{
|
|
21
21
|
"type": "command",
|
|
22
|
-
"command": "f=\"${CLAUDE_PROJECT_DIR:-$PWD}/node_modules/@venizia/vulcan/base/hooks/guard-writes.ts\"; in=$(cat); ok() { printf '%s' \"$in\" | grep -Eq '\"command\" *: *\"bun (install|i)( (--frozen-lockfile|--production|-p|--no-save|--ignore-scripts|--force|--verbose|--silent))*\"'; }; if [ -f \"$f\" ] && command -v bun >/dev/null 2>&1; then printf '%s' \"$in\" | bun \"$f\"; s=$?; [ \"$s\" -eq 0 ] && exit 0; ok && exit 0; exit 2; fi; if [ ! -f \"$f\" ] && [ -f \"${f%/*/*/*}/package.json\" ]; then echo \"vulcan: the guard-writes hook is not in this node_modules/@venizia/vulcan - the call passes; run bun node_modules/.bin/vulcan sync to drop its entry\" >&2; exit 0; fi; ok && exit 0; [ -f \"$f\" ] || echo \"vulcan: the guard-writes hook cannot run: node_modules/@venizia/vulcan is missing - run bun install (the one command that passes until then)\" >&2; command -v bun >/dev/null 2>&1 || echo \"vulcan: the guard-writes hook cannot run: bun is not on PATH - put bun on PATH (Claude Code may have started without your shell's PATH)\" >&2; exit 2"
|
|
22
|
+
"command": "f=\"${CLAUDE_PROJECT_DIR:-$PWD}/node_modules/@venizia/vulcan/base/hooks/guard-writes.ts\"; in=$(cat); ok() { printf '%s' \"$in\" | grep -Eq '\"command\" *: *\"bun (install|i)( (--frozen-lockfile|--production|-p|--no-save|--ignore-scripts|--force|--verbose|--silent))*\"'; }; if [ -f \"$f\" ] && command -v bun >/dev/null 2>&1; then printf '%s' \"$in\" | bun --no-env-file --config=/dev/null \"$f\"; s=$?; [ \"$s\" -eq 0 ] && exit 0; ok && exit 0; exit 2; fi; if [ ! -f \"$f\" ] && [ -f \"${f%/*/*/*}/package.json\" ]; then echo \"vulcan: the guard-writes hook is not in this node_modules/@venizia/vulcan - the call passes; run bun node_modules/.bin/vulcan sync to drop its entry\" >&2; exit 0; fi; ok && exit 0; [ -f \"$f\" ] || echo \"vulcan: the guard-writes hook cannot run: node_modules/@venizia/vulcan is missing - run bun install (the one command that passes until then)\" >&2; command -v bun >/dev/null 2>&1 || echo \"vulcan: the guard-writes hook cannot run: bun is not on PATH - put bun on PATH (Claude Code may have started without your shell's PATH)\" >&2; exit 2"
|
|
23
23
|
}
|
|
24
24
|
]
|
|
25
25
|
},
|
|
@@ -28,7 +28,7 @@
|
|
|
28
28
|
"hooks": [
|
|
29
29
|
{
|
|
30
30
|
"type": "command",
|
|
31
|
-
"command": "f=\"${CLAUDE_PROJECT_DIR:-$PWD}/node_modules/@venizia/vulcan/base/hooks/guard-git.ts\"; if [ -f \"$f\" ] && command -v bun >/dev/null 2>&1; then
|
|
31
|
+
"command": "f=\"${CLAUDE_PROJECT_DIR:-$PWD}/node_modules/@venizia/vulcan/base/hooks/guard-git.ts\"; in=$(cat); ok() { printf '%s' \"$in\" | grep -Eq '\"tool_name\" *: *\"Bash\"' && printf '%s' \"$in\" | grep -Eq '\"command\" *: *\"(bun (install|i)( (--frozen-lockfile|--production|-p|--no-save|--ignore-scripts|--force|--verbose|--silent))*|bun node_modules/[.]bin/vulcan sync( --?[a-z][a-z-]*( [[:alnum:]_./@-]+)?)*)\"'; }; if [ -f \"$f\" ] && command -v bun >/dev/null 2>&1; then t=; command -v timeout >/dev/null 2>&1 && t=\"timeout 30\"; out=$(printf '%s' \"$in\" | $t bun --no-env-file --config=/dev/null \"$f\"); s=$?; [ \"$s\" -eq 0 ] && { printf '%s' \"$out\"; exit 0; }; if printf '%s' \"$in\" | grep -Eq '(^|[^[:alnum:]_]|\\\\[ntr]|\\\\u00[0-9a-fA-F]{2})(git|gh)([^[:alnum:]_]|$)'; then m=\"${CLAUDE_PROJECT_DIR:-$PWD}/.agents/vulcan.manifest.json\"; [ \"$VULCAN_GUARD_ASKS\" = deny ] || { [ -f \"$m\" ] && ! M=\"$m\" bun --no-env-file --config=/dev/null -e 'const v = JSON.parse(require(\"node:fs\").readFileSync(process.env.M, \"utf8\")); if (typeof v !== \"object\" || v === null || Array.isArray(v)) process.exit(1)' >/dev/null 2>&1; } || grep -Eq '\"asks\" *: *\"deny\"' \"$m\" 2>/dev/null; if [ $? -eq 0 ]; then printf '%s\\n' '{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"deny\",\"permissionDecisionReason\":\"The guard-git hook crashed or timed out, so this command was not checked, and every call that would need a human to confirm it is denied here (VULCAN_GUARD_ASKS=deny, guard.asks: deny, or a manifest that cannot be read). Nothing was run: run bun install to repair the install.\"}}'; else printf '%s\\n' '{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"ask\",\"permissionDecisionReason\":\"The guard-git hook crashed or timed out, so this command was not checked. Confirm only if the owner asked for exactly this; VULCAN_GUARDS=off switches the guards off for a session.\"}}'; fi; exit 0; fi; echo \"vulcan: the guard-git hook failed - the call passes\" >&2; exit 0; fi; if printf '%s' \"$in\" | grep -Eq '(^|[^[:alnum:]_]|\\\\[ntr]|\\\\u00[0-9a-fA-F]{2})(git|gh)([^[:alnum:]_]|$)'; then ok && exit 0; echo \"vulcan: VULCAN guards unavailable: the guard-git hook cannot run (node_modules/@venizia/vulcan or bun is missing, or the hook is not in the installed package): finish bun install, or run bun node_modules/.bin/vulcan sync - the commands that pass until then\" >&2; exit 2; fi; echo \"vulcan: the guard-git hook cannot run, and this call names no git or gh - the call passes\" >&2; exit 0"
|
|
32
32
|
}
|
|
33
33
|
]
|
|
34
34
|
},
|
|
@@ -37,7 +37,7 @@
|
|
|
37
37
|
"hooks": [
|
|
38
38
|
{
|
|
39
39
|
"type": "command",
|
|
40
|
-
"command": "f=\"${CLAUDE_PROJECT_DIR:-$PWD}/node_modules/@venizia/vulcan/base/hooks/guard-outside.ts\"; if [ -f \"$f\" ] && command -v bun >/dev/null 2>&1; then
|
|
40
|
+
"command": "f=\"${CLAUDE_PROJECT_DIR:-$PWD}/node_modules/@venizia/vulcan/base/hooks/guard-outside.ts\"; in=$(cat); ok() { printf '%s' \"$in\" | grep -Eq '\"tool_name\" *: *\"Bash\"' && printf '%s' \"$in\" | grep -Eq '\"command\" *: *\"(bun (install|i)( (--frozen-lockfile|--production|-p|--no-save|--ignore-scripts|--force|--verbose|--silent))*|bun node_modules/[.]bin/vulcan sync( --?[a-z][a-z-]*( [[:alnum:]_./@-]+)?)*)\"'; }; if [ -f \"$f\" ] && command -v bun >/dev/null 2>&1; then t=; command -v timeout >/dev/null 2>&1 && t=\"timeout 30\"; out=$(printf '%s' \"$in\" | $t bun --no-env-file --config=/dev/null \"$f\"); s=$?; [ \"$s\" -eq 0 ] && { printf '%s' \"$out\"; exit 0; }; m=\"${CLAUDE_PROJECT_DIR:-$PWD}/.agents/vulcan.manifest.json\"; [ \"$VULCAN_GUARD_ASKS\" = deny ] || { [ -f \"$m\" ] && ! M=\"$m\" bun --no-env-file --config=/dev/null -e 'const v = JSON.parse(require(\"node:fs\").readFileSync(process.env.M, \"utf8\")); if (typeof v !== \"object\" || v === null || Array.isArray(v)) process.exit(1)' >/dev/null 2>&1; } || grep -Eq '\"asks\" *: *\"deny\"' \"$m\" 2>/dev/null; if [ $? -eq 0 ]; then printf '%s\\n' '{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"deny\",\"permissionDecisionReason\":\"The guard-outside hook crashed or timed out, so this call was not checked, and every call that would need a human to confirm it is denied here (VULCAN_GUARD_ASKS=deny, guard.asks: deny, or a manifest that cannot be read). Nothing was run: run bun install to repair the install.\"}}'; else printf '%s\\n' '{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"ask\",\"permissionDecisionReason\":\"The guard-outside hook crashed or timed out, so this call was not checked. Confirm only if the owner asked for exactly this; VULCAN_GUARDS=off switches the guards off for a session.\"}}'; fi; exit 0; fi; ok && exit 0; echo \"vulcan: VULCAN guards unavailable: the guard-outside hook cannot run (node_modules/@venizia/vulcan or bun is missing, or the hook is not in the installed package): finish bun install, or run bun node_modules/.bin/vulcan sync - the commands that pass until then\" >&2; exit 2"
|
|
41
41
|
}
|
|
42
42
|
]
|
|
43
43
|
}
|
|
@@ -47,7 +47,7 @@
|
|
|
47
47
|
"hooks": [
|
|
48
48
|
{
|
|
49
49
|
"type": "command",
|
|
50
|
-
"command": "f=\"${CLAUDE_PROJECT_DIR:-$PWD}/node_modules/@venizia/vulcan/base/hooks/subagent-start.ts\"; if [ -f \"$f\" ] && command -v bun >/dev/null 2>&1; then bun \"$f\"; s=$?; [ \"$s\" -eq 0 ] && exit 0; exit 2; fi; if [ ! -f \"$f\" ] && [ -f \"${f%/*/*/*}/package.json\" ]; then echo \"vulcan: the subagent-start hook is not in this node_modules/@venizia/vulcan - the call passes; run bun node_modules/.bin/vulcan sync to drop its entry\" >&2; exit 0; fi; [ -f \"$f\" ] || echo \"vulcan: the subagent-start hook cannot run: node_modules/@venizia/vulcan is missing - run bun install\" >&2; command -v bun >/dev/null 2>&1 || echo \"vulcan: the subagent-start hook cannot run: bun is not on PATH - put bun on PATH (Claude Code may have started without your shell's PATH)\" >&2; exit 2"
|
|
50
|
+
"command": "f=\"${CLAUDE_PROJECT_DIR:-$PWD}/node_modules/@venizia/vulcan/base/hooks/subagent-start.ts\"; if [ -f \"$f\" ] && command -v bun >/dev/null 2>&1; then bun --no-env-file --config=/dev/null \"$f\"; s=$?; [ \"$s\" -eq 0 ] && exit 0; exit 2; fi; if [ ! -f \"$f\" ] && [ -f \"${f%/*/*/*}/package.json\" ]; then echo \"vulcan: the subagent-start hook is not in this node_modules/@venizia/vulcan - the call passes; run bun node_modules/.bin/vulcan sync to drop its entry\" >&2; exit 0; fi; [ -f \"$f\" ] || echo \"vulcan: the subagent-start hook cannot run: node_modules/@venizia/vulcan is missing - run bun install\" >&2; command -v bun >/dev/null 2>&1 || echo \"vulcan: the subagent-start hook cannot run: bun is not on PATH - put bun on PATH (Claude Code may have started without your shell's PATH)\" >&2; exit 2"
|
|
51
51
|
}
|
|
52
52
|
]
|
|
53
53
|
}
|
|
@@ -4,13 +4,14 @@
|
|
|
4
4
|
// tool call it runs the same guard scripts Claude Code runs (node_modules/@venizia/vulcan/base/hooks/*.ts),
|
|
5
5
|
// with a Claude-shaped event on stdin, and turns the answer into this agent's: `deny` blocks, `ask` asks
|
|
6
6
|
// the owner (and blocks when there is no UI to ask). A guard that cannot give an answer follows the same
|
|
7
|
-
// policy as the Claude wrappers: the safety guards block, the others ask, and a missing install
|
|
8
|
-
//
|
|
9
|
-
// is gone from an installed package passes: there is nothing
|
|
7
|
+
// policy as the Claude wrappers: the safety guards block, the others ask, and a missing install blocks
|
|
8
|
+
// too - bar a bare `bun install` or `vulcan sync`, the way to repair it (guard-git only for a git or gh line).
|
|
9
|
+
// A guard that is gone from an installed package blocks, except guard-writes, which passes: there is nothing
|
|
10
|
+
// to run. A project that sets `guard.asks: 'deny'` has every ask answered as a block.
|
|
10
11
|
// Only node: modules are imported, so any host that loads TypeScript can load it.
|
|
11
12
|
|
|
12
13
|
import { spawnSync } from 'node:child_process';
|
|
13
|
-
import { existsSync } from 'node:fs';
|
|
14
|
+
import { existsSync, readFileSync } from 'node:fs';
|
|
14
15
|
import { dirname, join } from 'node:path';
|
|
15
16
|
|
|
16
17
|
class Tools {
|
|
@@ -60,6 +61,10 @@ interface IGuard {
|
|
|
60
61
|
name: string;
|
|
61
62
|
tools: string[];
|
|
62
63
|
onFailure: string;
|
|
64
|
+
/** Whether the call is blocked when the package is installed and only this guard is gone from it. */
|
|
65
|
+
isClosedWhenGone: boolean;
|
|
66
|
+
/** The lines the guard covers when it is missing: a line that does not match passes. Every line when absent. */
|
|
67
|
+
onlyLines?: RegExp;
|
|
63
68
|
}
|
|
64
69
|
|
|
65
70
|
interface IAnswer {
|
|
@@ -70,15 +75,31 @@ interface IAnswer {
|
|
|
70
75
|
const PACKAGE_DIRECTORY = join('node_modules', '@venizia', 'vulcan');
|
|
71
76
|
const HOOKS_DIRECTORY = join(PACKAGE_DIRECTORY, 'base', 'hooks');
|
|
72
77
|
const TIMEOUT_MS = 30_000;
|
|
73
|
-
/** The
|
|
74
|
-
const
|
|
75
|
-
/^\s*bun (install|i)( (--frozen-lockfile|--production|-p|--no-save|--ignore-scripts|--force|--verbose|--silent))
|
|
78
|
+
/** The commands that pass while the install is missing or out of step: they are how it is repaired (`bun install`, `vulcan sync`). */
|
|
79
|
+
const REPAIR =
|
|
80
|
+
/^\s*(bun (install|i)( (--frozen-lockfile|--production|-p|--no-save|--ignore-scripts|--force|--verbose|--silent))*|bun node_modules\/\.bin\/vulcan sync( --?[a-z][a-z-]*( [\w./@-]+)?)*)\s*$/;
|
|
81
|
+
/** A command line that names git or gh as a word. */
|
|
82
|
+
const GIT_LINE = /(^|[^A-Za-z0-9_])(git|gh)([^A-Za-z0-9_]|$)/;
|
|
83
|
+
const MANIFEST_FILE = join('.agents', 'vulcan.manifest.json');
|
|
84
|
+
const HELD_ASK =
|
|
85
|
+
'Every call that would need a human to confirm it is denied here (guard.asks: deny, VULCAN_GUARD_ASKS=deny, or a manifest that cannot be read). Nothing was run: hand this to the owner.';
|
|
76
86
|
|
|
77
87
|
/** The guards of `.claude/settings.json`, with the tools each covers and what each does when it cannot answer. */
|
|
78
88
|
const GUARDS: IGuard[] = [
|
|
79
|
-
{ name: 'guard-writes', tools: [Tools.BASH], onFailure: Failures.BLOCK },
|
|
80
|
-
{
|
|
81
|
-
|
|
89
|
+
{ name: 'guard-writes', tools: [Tools.BASH], onFailure: Failures.BLOCK, isClosedWhenGone: false },
|
|
90
|
+
{
|
|
91
|
+
name: 'guard-git',
|
|
92
|
+
tools: [Tools.BASH],
|
|
93
|
+
onFailure: Failures.ASK,
|
|
94
|
+
isClosedWhenGone: true,
|
|
95
|
+
onlyLines: GIT_LINE,
|
|
96
|
+
},
|
|
97
|
+
{
|
|
98
|
+
name: 'guard-outside',
|
|
99
|
+
tools: [Tools.BASH, Tools.WRITE, Tools.EDIT],
|
|
100
|
+
onFailure: Failures.ASK,
|
|
101
|
+
isClosedWhenGone: true,
|
|
102
|
+
},
|
|
82
103
|
];
|
|
83
104
|
|
|
84
105
|
const isRecord = (value: unknown): value is Record<string, unknown> =>
|
|
@@ -103,6 +124,31 @@ const rootOf = (opts: { cwd: string }): string => {
|
|
|
103
124
|
}
|
|
104
125
|
};
|
|
105
126
|
|
|
127
|
+
/**
|
|
128
|
+
* Whether every ask is a deny in the project at `root`: the launch environment says `VULCAN_GUARD_ASKS=deny`, the manifest sets
|
|
129
|
+
* `guard.asks` to `deny`, or the manifest exists and cannot be read. No manifest means asks stay asks.
|
|
130
|
+
*/
|
|
131
|
+
const isHeldIn = (opts: { root: string }): boolean => {
|
|
132
|
+
if (process.env.VULCAN_GUARD_ASKS === Answers.DENY) {
|
|
133
|
+
return true;
|
|
134
|
+
}
|
|
135
|
+
|
|
136
|
+
const file = join(opts.root, MANIFEST_FILE);
|
|
137
|
+
|
|
138
|
+
if (!existsSync(file)) {
|
|
139
|
+
return false;
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
try {
|
|
143
|
+
const manifest: unknown = JSON.parse(readFileSync(file, 'utf8'));
|
|
144
|
+
const guard = isRecord(manifest) ? manifest.guard : undefined;
|
|
145
|
+
|
|
146
|
+
return !isRecord(manifest) || (isRecord(guard) && guard.asks === Answers.DENY);
|
|
147
|
+
} catch {
|
|
148
|
+
return true;
|
|
149
|
+
}
|
|
150
|
+
};
|
|
151
|
+
|
|
106
152
|
/** The event Claude Code sends: snake_case keys on the wire, written through string-literal keys. */
|
|
107
153
|
const wireEventOf = (opts: {
|
|
108
154
|
tool: string;
|
|
@@ -183,15 +229,24 @@ const runGuard = (opts: {
|
|
|
183
229
|
const script = join(opts.root, HOOKS_DIRECTORY, `${opts.guard.name}.ts`);
|
|
184
230
|
|
|
185
231
|
if (!existsSync(script)) {
|
|
186
|
-
// The package is installed and only this guard is gone from it: nothing to run, the
|
|
232
|
+
// The package is installed and only this guard is gone from it: guard-writes passes (nothing to run), the others block.
|
|
187
233
|
if (existsSync(join(opts.root, PACKAGE_DIRECTORY, 'package.json'))) {
|
|
188
|
-
return
|
|
234
|
+
return opts.guard.isClosedWhenGone
|
|
235
|
+
? {
|
|
236
|
+
kind: Answers.MISSING,
|
|
237
|
+
reason: `VULCAN guards unavailable: ${opts.guard.name} is not in the installed package; run bun node_modules/.bin/vulcan sync`,
|
|
238
|
+
}
|
|
239
|
+
: { kind: Answers.ALLOW, reason: '' };
|
|
189
240
|
}
|
|
190
241
|
|
|
191
|
-
return {
|
|
242
|
+
return {
|
|
243
|
+
kind: Answers.MISSING,
|
|
244
|
+
reason: `VULCAN guards unavailable: ${opts.guard.name} is missing; finish bun install`,
|
|
245
|
+
};
|
|
192
246
|
}
|
|
193
247
|
|
|
194
|
-
|
|
248
|
+
// bun reads `.env` and `bunfig.toml` from the working directory: a file an agent writes there (a `VULCAN_GUARDS=off`, a preload) must not reach a guard.
|
|
249
|
+
const result = spawnSync('bun', ['--no-env-file', '--config=/dev/null', script], {
|
|
195
250
|
input: JSON.stringify(opts.claudeEvent),
|
|
196
251
|
encoding: 'utf8',
|
|
197
252
|
timeout: TIMEOUT_MS,
|
|
@@ -253,10 +308,13 @@ export class GuardVerdict {
|
|
|
253
308
|
}
|
|
254
309
|
|
|
255
310
|
if (answer.kind === Answers.MISSING) {
|
|
256
|
-
const
|
|
257
|
-
|
|
311
|
+
const command = String(opts.input.command);
|
|
312
|
+
const isRepair = opts.toolName === Tools.BASH && REPAIR.test(command);
|
|
313
|
+
const isCovered =
|
|
314
|
+
guard.onlyLines === undefined ||
|
|
315
|
+
(opts.toolName === Tools.BASH && guard.onlyLines.test(command));
|
|
258
316
|
|
|
259
|
-
if (
|
|
317
|
+
if (!isRepair && isCovered) {
|
|
260
318
|
return { kind: Verdicts.DENY, reason: answer.reason };
|
|
261
319
|
}
|
|
262
320
|
}
|
|
@@ -270,6 +328,10 @@ export class GuardVerdict {
|
|
|
270
328
|
}
|
|
271
329
|
}
|
|
272
330
|
|
|
331
|
+
if (asks.length > 0 && isHeldIn({ root })) {
|
|
332
|
+
return { kind: Verdicts.DENY, reason: `${asks.join('\n\n')}\n\n${HELD_ASK}` };
|
|
333
|
+
}
|
|
334
|
+
|
|
273
335
|
return asks.length > 0
|
|
274
336
|
? { kind: Verdicts.ASK, reason: asks.join('\n\n') }
|
|
275
337
|
: { kind: Verdicts.ALLOW, reason: '' };
|
package/base/hooks/guard-git.ts
CHANGED
|
@@ -5,11 +5,12 @@
|
|
|
5
5
|
* `reset --hard`, other force-pushes, `branch -D` of an unmerged branch and `gh pr create` with no `--base`
|
|
6
6
|
* (ask: the pull request would land on the default branch).
|
|
7
7
|
*
|
|
8
|
-
* It guards against drift, it is not the last line of defence,
|
|
9
|
-
*
|
|
10
|
-
*
|
|
11
|
-
*
|
|
12
|
-
* `
|
|
8
|
+
* It guards against drift, it is not the last line of defence. A missing package, `bun` or hook file is the settings wrapper's
|
|
9
|
+
* to answer: it blocks a command that names `git` or `gh`, bar `bun install` and `vulcan sync`. Input it cannot read ASKS,
|
|
10
|
+
* because nothing was checked. A guard that started and then failed - a crash or a timeout, here an internal error or an
|
|
11
|
+
* unloadable module - ASKS about a command that names `git` or `gh`, instead of passing it unchecked. Where the project
|
|
12
|
+
* (`guard.asks: 'deny'`) or the launch environment (`VULCAN_GUARD_ASKS=deny`) holds every ask, each ask is a deny, and so is a
|
|
13
|
+
* crash when the manifest exists and cannot be read. `VULCAN_GUARDS=off` switches it off, read before anything is
|
|
13
14
|
* imported. It imports only the modules it needs - no config, no zod. The branches the project lists in
|
|
14
15
|
* `guard.git.askPush` are read from the manifest, and a plain push to one of them asks.
|
|
15
16
|
*/
|
|
@@ -49,6 +50,8 @@ try {
|
|
|
49
50
|
|
|
50
51
|
if (hits.length > 0) {
|
|
51
52
|
const denied = hits.some((hit) => hit.decision === GuardDecisions.DENY);
|
|
53
|
+
// A project that sets guard.asks to deny refuses what would ask a human, with the owner to hand it to.
|
|
54
|
+
const isHeld = !denied && policy.asks === GuardDecisions.DENY;
|
|
52
55
|
// A denial the agent can repair says how; one that is the owner's to decide is handed to the owner.
|
|
53
56
|
const fixes = [
|
|
54
57
|
...new Set(
|
|
@@ -64,11 +67,15 @@ try {
|
|
|
64
67
|
console.log(
|
|
65
68
|
JSON.stringify(
|
|
66
69
|
HookDecision.buildTool({
|
|
67
|
-
|
|
70
|
+
asks: policy.asks,
|
|
71
|
+
asksNote: policy.asksNote,
|
|
72
|
+
decision: denied || isHeld ? GuardDecisions.DENY : GuardDecisions.ASK,
|
|
68
73
|
reason: [
|
|
69
74
|
denied
|
|
70
75
|
? 'This command is refused by the base rules:'
|
|
71
|
-
:
|
|
76
|
+
: isHeld
|
|
77
|
+
? 'This command needs a human to confirm, and every ask is denied here:'
|
|
78
|
+
: 'This command needs a human to confirm:',
|
|
72
79
|
...hits.map((hit) => ` - ${hit.rule}: ${hit.message}`),
|
|
73
80
|
'',
|
|
74
81
|
...(denied
|
|
@@ -82,7 +89,12 @@ try {
|
|
|
82
89
|
]
|
|
83
90
|
: []),
|
|
84
91
|
]
|
|
85
|
-
:
|
|
92
|
+
: isHeld
|
|
93
|
+
? [
|
|
94
|
+
'Nothing was run. Hand the exact command to the owner instead (V-W-06).',
|
|
95
|
+
...(policy.asksNote === undefined ? [] : [policy.asksNote]),
|
|
96
|
+
]
|
|
97
|
+
: ['Confirm only if the owner asked for exactly this.']),
|
|
86
98
|
],
|
|
87
99
|
}),
|
|
88
100
|
),
|
|
@@ -93,18 +105,54 @@ try {
|
|
|
93
105
|
|
|
94
106
|
console.error(`vulcan: the guard-git hook failed (${message}); run bun install`);
|
|
95
107
|
|
|
96
|
-
// The imports may be what failed, so the answer is written by hand
|
|
108
|
+
// The imports may be what failed, so the answer is written by hand, and a project that sets guard.asks to deny is read from the manifest by hand too.
|
|
97
109
|
if (/(^|[^A-Za-z0-9_])(git|gh)([^A-Za-z0-9_]|$)/.test(text)) {
|
|
110
|
+
let isHeldOnCrash = false;
|
|
111
|
+
|
|
112
|
+
try {
|
|
113
|
+
const { existsSync, readFileSync } = await import('node:fs');
|
|
114
|
+
const root = process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
|
|
115
|
+
const file = `${root}/.agents/vulcan.manifest.json`;
|
|
116
|
+
|
|
117
|
+
isHeldOnCrash = process.env.VULCAN_GUARD_ASKS === 'deny';
|
|
118
|
+
|
|
119
|
+
if (!isHeldOnCrash && existsSync(file)) {
|
|
120
|
+
try {
|
|
121
|
+
const manifest: unknown = JSON.parse(readFileSync(file, 'utf8'));
|
|
122
|
+
const guard =
|
|
123
|
+
typeof manifest === 'object' && manifest !== null && 'guard' in manifest
|
|
124
|
+
? manifest.guard
|
|
125
|
+
: undefined;
|
|
126
|
+
|
|
127
|
+
isHeldOnCrash =
|
|
128
|
+
typeof manifest !== 'object' ||
|
|
129
|
+
manifest === null ||
|
|
130
|
+
Array.isArray(manifest) ||
|
|
131
|
+
(typeof guard === 'object' &&
|
|
132
|
+
guard !== null &&
|
|
133
|
+
'asks' in guard &&
|
|
134
|
+
guard.asks === 'deny');
|
|
135
|
+
} catch {
|
|
136
|
+
// A manifest that exists and cannot be read holds every ask.
|
|
137
|
+
isHeldOnCrash = true;
|
|
138
|
+
}
|
|
139
|
+
}
|
|
140
|
+
} catch {
|
|
141
|
+
isHeldOnCrash = false;
|
|
142
|
+
}
|
|
143
|
+
|
|
98
144
|
console.log(
|
|
99
145
|
JSON.stringify({
|
|
100
146
|
hookSpecificOutput: {
|
|
101
147
|
hookEventName: 'PreToolUse',
|
|
102
|
-
permissionDecision: 'ask',
|
|
148
|
+
permissionDecision: isHeldOnCrash ? 'deny' : 'ask',
|
|
103
149
|
permissionDecisionReason: [
|
|
104
150
|
'The guard-git hook failed, so this command was not checked:',
|
|
105
151
|
` - ${message}`,
|
|
106
152
|
'',
|
|
107
|
-
|
|
153
|
+
isHeldOnCrash
|
|
154
|
+
? 'This project denies every call that would need a human to confirm it (guard.asks: deny). Nothing was run: run bun install to repair the install.'
|
|
155
|
+
: 'Confirm only if the owner asked for exactly this; run bun install to repair the install, or VULCAN_GUARDS=off to switch the guards off for a session.',
|
|
108
156
|
].join('\n'),
|
|
109
157
|
},
|
|
110
158
|
}),
|
|
@@ -10,11 +10,15 @@
|
|
|
10
10
|
* reason says how. Literal assignments of the same line (`S=dir; ... > $S/a`, `export X=dir`, `for i in 1 2`) are
|
|
11
11
|
* resolved first, so the usual safe forms are read.
|
|
12
12
|
*
|
|
13
|
-
*
|
|
14
|
-
* is
|
|
15
|
-
*
|
|
16
|
-
*
|
|
17
|
-
*
|
|
13
|
+
* A write to a file the guards read their policy from (the manifest, the config, `.claude/settings*.json` and the installed
|
|
14
|
+
* package) is always DENIED: an agent that can write one can switch a guard off, and the owner changes them by hand or through
|
|
15
|
+
* `vulcan sync`. A missing package, `bun` or hook file is the settings wrapper's to answer: it blocks, bar `bun install` and
|
|
16
|
+
* `vulcan sync`.
|
|
17
|
+
*
|
|
18
|
+
* It guards against drift, not against an attacker. A hook input it cannot read ASKS, because nothing was checked and the agent
|
|
19
|
+
* cannot repair that. A guard that started and then failed - a crash or a timeout, here an internal error or an unloadable
|
|
20
|
+
* module - ASKS instead of passing the call unchecked. Where the project (`guard.asks: 'deny'`) or the launch environment
|
|
21
|
+
* (`VULCAN_GUARD_ASKS=deny`) holds every ask, each is a deny; a manifest that exists and cannot be read holds them too. `VULCAN_GUARDS=off` switches it off,
|
|
18
22
|
* read before anything is imported. It reads what the project set (`guard.outside`, `guard.toolOwnedPaths`)
|
|
19
23
|
* from the manifest `vulcan sync` wrote, never from the config: a config a newer release wrote, which this
|
|
20
24
|
* VULCAN cannot parse, then changes nothing here.
|
|
@@ -36,12 +40,20 @@ try {
|
|
|
36
40
|
const { HookInput } = await import('../../src/hooks/hook-input.ts');
|
|
37
41
|
const { ProjectTmp } = await import('../../src/hooks/project-tmp.ts');
|
|
38
42
|
const { relative } = await import('node:path');
|
|
43
|
+
const { ProjectGuards } = await import('../../src/hooks/project-guards.ts');
|
|
39
44
|
const input = HookInput.parse({ text });
|
|
45
|
+
const projectRoot = process.env.CLAUDE_PROJECT_DIR ?? input?.cwd ?? process.cwd();
|
|
46
|
+
const { toolOwnedPaths, outside, asks, asksNote } = ProjectGuards.readPolicy({
|
|
47
|
+
root: projectRoot,
|
|
48
|
+
});
|
|
49
|
+
const isHeld = asks === GuardDecisions.DENY;
|
|
40
50
|
|
|
41
51
|
if (!input) {
|
|
42
52
|
console.log(
|
|
43
53
|
JSON.stringify(
|
|
44
54
|
HookDecision.buildTool({
|
|
55
|
+
asks,
|
|
56
|
+
asksNote,
|
|
45
57
|
decision: GuardDecisions.ASK,
|
|
46
58
|
reason: [
|
|
47
59
|
'The hook input could not be read, so this call was not checked for files outside the project (V-B-08).',
|
|
@@ -51,10 +63,6 @@ try {
|
|
|
51
63
|
),
|
|
52
64
|
);
|
|
53
65
|
} else {
|
|
54
|
-
const projectRoot = process.env.CLAUDE_PROJECT_DIR ?? input.cwd ?? process.cwd();
|
|
55
|
-
const { ProjectGuards } = await import('../../src/hooks/project-guards.ts');
|
|
56
|
-
const { toolOwnedPaths, outside } = ProjectGuards.readPolicy({ root: projectRoot });
|
|
57
|
-
|
|
58
66
|
const hits = OutsideGuard.inspect({ input, projectRoot, toolOwnedPaths });
|
|
59
67
|
|
|
60
68
|
if (hits.length > 0) {
|
|
@@ -78,11 +86,14 @@ try {
|
|
|
78
86
|
];
|
|
79
87
|
// A link to a path outside the project is a way to write there with a name inside it: denied, as the agent can copy or link inside.
|
|
80
88
|
const linkHits = read.filter((hit) => hit.isLink === true);
|
|
89
|
+
// A file the guards read their policy from: denied, so no agent loosens a guard by editing it.
|
|
90
|
+
const protectedHits = read.filter((hit) => hit.isProtected === true);
|
|
81
91
|
const isDeny =
|
|
82
92
|
isScratchpad ||
|
|
93
|
+
protectedHits.length > 0 ||
|
|
83
94
|
linkHits.length > 0 ||
|
|
84
95
|
unreadHits.length > 0 ||
|
|
85
|
-
(outside === GuardDecisions.DENY && read.length > 0);
|
|
96
|
+
((outside === GuardDecisions.DENY || isHeld) && read.length > 0);
|
|
86
97
|
let reason: string[];
|
|
87
98
|
|
|
88
99
|
if (unreadHits.length > 0 && !isScratchpad) {
|
|
@@ -108,6 +119,21 @@ try {
|
|
|
108
119
|
'',
|
|
109
120
|
`That folder is under /tmp, and V-B-08 overrides the tool line that says to use it. Nothing was written. ${places} Read a fetched file through a pipe (for example gh api ... | grep) rather than saving it.`,
|
|
110
121
|
];
|
|
122
|
+
} else if (protectedHits.length > 0) {
|
|
123
|
+
reason = [
|
|
124
|
+
'This would change a file the guards read their policy from (V-B-08):',
|
|
125
|
+
...linesOf(protectedHits),
|
|
126
|
+
...(read.length > protectedHits.length
|
|
127
|
+
? [
|
|
128
|
+
'',
|
|
129
|
+
'It would also create files outside the project:',
|
|
130
|
+
...linesOf(read.filter((hit) => hit.isProtected !== true)),
|
|
131
|
+
]
|
|
132
|
+
: []),
|
|
133
|
+
...unread,
|
|
134
|
+
'',
|
|
135
|
+
'Nothing was run. These files are changed by the owner, by hand or through bun node_modules/.bin/vulcan sync; an agent that could edit them could switch a guard off.',
|
|
136
|
+
];
|
|
111
137
|
} else if (linkHits.length > 0) {
|
|
112
138
|
reason = [
|
|
113
139
|
'This would hard-link a path outside the project (V-B-08); a hard link cannot be told from the file, so a write through it changes that path later too:',
|
|
@@ -125,11 +151,12 @@ try {
|
|
|
125
151
|
];
|
|
126
152
|
} else if (isDeny) {
|
|
127
153
|
reason = [
|
|
128
|
-
|
|
154
|
+
`This would create files outside the project (V-B-08), and this project denies it (${isHeld ? 'guard.asks' : 'guard.outside'}):`,
|
|
129
155
|
...linesOf(read),
|
|
130
156
|
...unread,
|
|
131
157
|
'',
|
|
132
158
|
`Nothing was written. ${places}`,
|
|
159
|
+
...(isHeld && asksNote !== undefined ? ['', asksNote] : []),
|
|
133
160
|
owned,
|
|
134
161
|
];
|
|
135
162
|
} else {
|
|
@@ -146,6 +173,7 @@ try {
|
|
|
146
173
|
console.log(
|
|
147
174
|
JSON.stringify(
|
|
148
175
|
HookDecision.buildTool({
|
|
176
|
+
asks,
|
|
149
177
|
decision: isDeny ? GuardDecisions.DENY : GuardDecisions.ASK,
|
|
150
178
|
reason,
|
|
151
179
|
}),
|
|
@@ -158,17 +186,50 @@ try {
|
|
|
158
186
|
|
|
159
187
|
console.error(`vulcan: the guard-outside hook failed (${message}); run bun install`);
|
|
160
188
|
|
|
161
|
-
// The imports may be what failed, so the answer is written by hand
|
|
189
|
+
// The imports may be what failed, so the answer is written by hand, and a project that sets guard.asks to deny is read from the manifest by hand too.
|
|
190
|
+
let isHeldOnCrash = false;
|
|
191
|
+
|
|
192
|
+
try {
|
|
193
|
+
const { existsSync, readFileSync } = await import('node:fs');
|
|
194
|
+
const root = process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
|
|
195
|
+
const file = `${root}/.agents/vulcan.manifest.json`;
|
|
196
|
+
|
|
197
|
+
isHeldOnCrash = process.env.VULCAN_GUARD_ASKS === 'deny';
|
|
198
|
+
|
|
199
|
+
if (!isHeldOnCrash && existsSync(file)) {
|
|
200
|
+
try {
|
|
201
|
+
const manifest: unknown = JSON.parse(readFileSync(file, 'utf8'));
|
|
202
|
+
const guard =
|
|
203
|
+
typeof manifest === 'object' && manifest !== null && 'guard' in manifest
|
|
204
|
+
? manifest.guard
|
|
205
|
+
: undefined;
|
|
206
|
+
|
|
207
|
+
isHeldOnCrash =
|
|
208
|
+
typeof manifest !== 'object' ||
|
|
209
|
+
manifest === null ||
|
|
210
|
+
Array.isArray(manifest) ||
|
|
211
|
+
(typeof guard === 'object' && guard !== null && 'asks' in guard && guard.asks === 'deny');
|
|
212
|
+
} catch {
|
|
213
|
+
// A manifest that exists and cannot be read holds every ask.
|
|
214
|
+
isHeldOnCrash = true;
|
|
215
|
+
}
|
|
216
|
+
}
|
|
217
|
+
} catch {
|
|
218
|
+
isHeldOnCrash = false;
|
|
219
|
+
}
|
|
220
|
+
|
|
162
221
|
console.log(
|
|
163
222
|
JSON.stringify({
|
|
164
223
|
hookSpecificOutput: {
|
|
165
224
|
hookEventName: 'PreToolUse',
|
|
166
|
-
permissionDecision: 'ask',
|
|
225
|
+
permissionDecision: isHeldOnCrash ? 'deny' : 'ask',
|
|
167
226
|
permissionDecisionReason: [
|
|
168
227
|
'The guard-outside hook failed, so this call was not checked for files outside the project (V-B-08):',
|
|
169
228
|
` - ${message}`,
|
|
170
229
|
'',
|
|
171
|
-
|
|
230
|
+
isHeldOnCrash
|
|
231
|
+
? 'This project denies every call that would need a human to confirm it (guard.asks: deny). Nothing was run: run bun install to repair the install.'
|
|
232
|
+
: 'Confirm only if the call stays inside the project; run bun install to repair the install, or VULCAN_GUARDS=off to switch the guards off for a session.',
|
|
172
233
|
].join('\n'),
|
|
173
234
|
},
|
|
174
235
|
}),
|
|
@@ -31,7 +31,11 @@ try {
|
|
|
31
31
|
];
|
|
32
32
|
|
|
33
33
|
if (hits.length > 0) {
|
|
34
|
-
console.log(
|
|
34
|
+
console.log(
|
|
35
|
+
JSON.stringify(
|
|
36
|
+
WriteGuard.buildDecision({ hits, asks: policy.asks, asksNote: policy.asksNote }),
|
|
37
|
+
),
|
|
38
|
+
);
|
|
35
39
|
}
|
|
36
40
|
} catch (error) {
|
|
37
41
|
console.error(
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@venizia/vulcan",
|
|
3
|
-
"version": "0.4.10-
|
|
3
|
+
"version": "0.4.10-21",
|
|
4
4
|
"description": "VULCAN - one setup, one workflow for every project: init, sync, doctor, upgrade, and `vulcan x` for the shipped tools. Bun-only.",
|
|
5
5
|
"homepage": "https://github.com/VENIZIA-AI/vulcan/tree/main/packages/cli",
|
|
6
6
|
"bugs": {
|
|
@@ -45,8 +45,8 @@
|
|
|
45
45
|
},
|
|
46
46
|
"dependencies": {
|
|
47
47
|
"@clack/prompts": "1.8.1",
|
|
48
|
-
"@venizia/vulcan-atlas": "0.4.10-
|
|
49
|
-
"@venizia/vulcan-okf": "0.4.10-
|
|
48
|
+
"@venizia/vulcan-atlas": "0.4.10-21",
|
|
49
|
+
"@venizia/vulcan-okf": "0.4.10-21",
|
|
50
50
|
"zod": "^4.6.7"
|
|
51
51
|
},
|
|
52
52
|
"devDependencies": {
|
|
@@ -22,7 +22,7 @@ const GUARD_COMMAND = [
|
|
|
22
22
|
'd=$(git rev-parse --show-toplevel 2>/dev/null || pwd);',
|
|
23
23
|
`f="$d/node_modules/@venizia/vulcan/base/hooks/${GUARD_SCRIPT}";`,
|
|
24
24
|
'if [ -f "$f" ] && command -v bun >/dev/null 2>&1; then',
|
|
25
|
-
'in=$(cat); out=$(printf \'%s\' "$in" | bun "$f"); s=$?;',
|
|
25
|
+
'in=$(cat); out=$(printf \'%s\' "$in" | bun --no-env-file --config=/dev/null "$f"); s=$?;',
|
|
26
26
|
`if [ "$s" -eq 0 ]; then printf '%s' "$out"; exit 0; fi;`,
|
|
27
27
|
`printf '%s\\n' '${DENY_ON_CRASH}'; exit 0; fi;`,
|
|
28
28
|
'cat >/dev/null; echo "vulcan: the guards cannot run: node_modules/@venizia/vulcan or bun is missing - the call passes" >&2',
|
package/src/agents/hooks-json.ts
CHANGED
|
@@ -13,16 +13,35 @@ const ASK_ON_CRASH = JSON.stringify({
|
|
|
13
13
|
'The VULCAN guard crashed, so this call was not checked. Confirm only if the owner asked for exactly this; VULCAN_GUARDS=off switches the guards off for a session.',
|
|
14
14
|
});
|
|
15
15
|
|
|
16
|
+
/** The answer of a crashed adapter where every ask is a deny: `VULCAN_GUARD_ASKS=deny`, `guard.asks: 'deny'` or a manifest that cannot be read. */
|
|
17
|
+
const DENY_ON_CRASH = JSON.stringify({
|
|
18
|
+
decision: 'deny',
|
|
19
|
+
reason:
|
|
20
|
+
'The VULCAN guard crashed, so this call was not checked, and every call that would need a human to confirm it is denied here (VULCAN_GUARD_ASKS=deny, guard.asks: deny, or a manifest that cannot be read). Nothing was run: hand this to the owner.',
|
|
21
|
+
});
|
|
22
|
+
|
|
23
|
+
/**
|
|
24
|
+
* Succeeds when the environment or the manifest (the hooks file's folder is `.agents`) holds every ask: `VULCAN_GUARD_ASKS=deny`,
|
|
25
|
+
* `guard.asks: 'deny'`, or a manifest that exists and does not parse as an object.
|
|
26
|
+
*/
|
|
27
|
+
const IS_HELD = [
|
|
28
|
+
'm="$PWD/vulcan.manifest.json";',
|
|
29
|
+
'[ "$VULCAN_GUARD_ASKS" = deny ]',
|
|
30
|
+
`|| { [ -f "$m" ] && ! M="$m" bun --no-env-file --config=/dev/null -e 'const v = JSON.parse(require("node:fs").readFileSync(process.env.M, "utf8")); if (typeof v !== "object" || v === null || Array.isArray(v)) process.exit(1)' >/dev/null 2>&1; }`,
|
|
31
|
+
`|| grep -Eq '"asks" *: *"deny"' "$m" 2>/dev/null;`,
|
|
32
|
+
].join(' ');
|
|
33
|
+
|
|
16
34
|
/**
|
|
17
35
|
* The hook command. Antigravity runs it from the folder of the hooks file (`.agents`), so the install is
|
|
18
|
-
* `../node_modules`. A missing package or bun passes with a note; a script that started
|
|
36
|
+
* `../node_modules`. A missing package or bun passes with a note (unlike the Claude wrappers, which block); a script that started
|
|
37
|
+
* and crashed asks, or denies where every ask is held.
|
|
19
38
|
*/
|
|
20
39
|
const GUARD_COMMAND = [
|
|
21
40
|
'f="$PWD/../node_modules/@venizia/vulcan/base/hooks/antigravity-guards.ts";',
|
|
22
41
|
'if [ -f "$f" ] && command -v bun >/dev/null 2>&1; then',
|
|
23
|
-
'in=$(cat); out=$(printf \'%s\' "$in" | bun "$f"); s=$?;',
|
|
42
|
+
'in=$(cat); out=$(printf \'%s\' "$in" | bun --no-env-file --config=/dev/null "$f"); s=$?;',
|
|
24
43
|
`if [ "$s" -eq 0 ]; then printf '%s' "$out"; exit 0; fi;`,
|
|
25
|
-
|
|
44
|
+
`${IS_HELD} if [ $? -eq 0 ]; then printf '%s\\n' '${DENY_ON_CRASH}'; else printf '%s\\n' '${ASK_ON_CRASH}'; fi; exit 0; fi;`,
|
|
26
45
|
'cat >/dev/null; echo "vulcan: the guards cannot run: node_modules/@venizia/vulcan or bun is missing - the call passes" >&2;',
|
|
27
46
|
`printf '%s\\n' '{"decision":"allow"}'`,
|
|
28
47
|
].join(' ');
|
|
@@ -8,6 +8,10 @@ export class EnvVariables {
|
|
|
8
8
|
static readonly VULCAN_OWNER_REPLY = 'VULCAN_OWNER_REPLY';
|
|
9
9
|
/** `off` switches the guard hooks off for one session. */
|
|
10
10
|
static readonly VULCAN_GUARDS = 'VULCAN_GUARDS';
|
|
11
|
+
/** `deny` makes every guard refuse what it would ask a person about; the strictest of this and `guard.asks` holds, so the project cannot loosen it. Set it where the agent is launched. */
|
|
12
|
+
static readonly VULCAN_GUARD_ASKS = 'VULCAN_GUARD_ASKS';
|
|
13
|
+
/** `deny` makes `guard-outside` refuse a write outside the project; the strictest of this and `guard.outside` holds. Set it where the agent is launched. */
|
|
14
|
+
static readonly VULCAN_GUARD_OUTSIDE = 'VULCAN_GUARD_OUTSIDE';
|
|
11
15
|
/** `1` makes `init`, `add` and `upgrade` print the install, `git init`, `sync` and the checks as skipped; for tests. */
|
|
12
16
|
static readonly VULCAN_NO_INSTALL = 'VULCAN_NO_INSTALL';
|
|
13
17
|
/** Set by `vulcan x` for okf and atlas: the resolved project config as JSON. */
|
package/src/config/schema.ts
CHANGED
|
@@ -558,7 +558,26 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
|
|
|
558
558
|
doctor: DOCTOR_SCHEMA.default({ privateValues: { acknowledged: [] } }),
|
|
559
559
|
/** Team-shared Claude settings (permissions, env, enabledPlugins...), merged by sync over personal keys. */
|
|
560
560
|
claude: z
|
|
561
|
-
.strictObject({
|
|
561
|
+
.strictObject({
|
|
562
|
+
/** The Claude settings merged into `.claude/settings.json`; an `env` that sets a `VULCAN_GUARD*` variable is refused. */
|
|
563
|
+
settings: z
|
|
564
|
+
.record(z.string(), z.unknown())
|
|
565
|
+
.superRefine((settings, context) => {
|
|
566
|
+
const env = settings['env'];
|
|
567
|
+
|
|
568
|
+
if (typeof env !== 'object' || env === null || Array.isArray(env)) {
|
|
569
|
+
return;
|
|
570
|
+
}
|
|
571
|
+
|
|
572
|
+
for (const name of Object.keys(env).filter((key) => /^VULCAN_GUARD/.test(key))) {
|
|
573
|
+
context.addIssue({
|
|
574
|
+
code: 'custom',
|
|
575
|
+
message: `${name} is the owner's choice and belongs in the environment that launches the agent, not in the project's Claude settings, which an agent can edit`,
|
|
576
|
+
});
|
|
577
|
+
}
|
|
578
|
+
})
|
|
579
|
+
.default({}),
|
|
580
|
+
})
|
|
562
581
|
.default({ settings: {} }),
|
|
563
582
|
/** The session-start digest: the rule IDs it repeats as "the rules sessions drop most" - base or the project's own. */
|
|
564
583
|
digest: z
|
|
@@ -579,8 +598,16 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
|
|
|
579
598
|
* compound commands too), and `git.askPush` lists the branches a plain `git push` asks about; `vulcan sync`
|
|
580
599
|
* writes both to the manifest, where the hooks read them, and writes `outside` (when it is `deny`) and
|
|
581
600
|
* `toolOwnedPaths` there too, so a config this VULCAN cannot parse changes no guard. `outside` is what
|
|
582
|
-
* `guard-outside` does with a write outside the project: `ask` (the default) or `deny`.
|
|
583
|
-
*
|
|
601
|
+
* `guard-outside` does with a write outside the project: `ask` (the default) or `deny`. `asks` is the same choice for every guard:
|
|
602
|
+
* `deny` makes each answer that would ask a human (a command of guard-writes, a push target of `git.askPush`, `git push --mirror`,
|
|
603
|
+
* `git reset --hard`, a force-push to a branch that is not protected, a force-delete of an unmerged branch, a write outside the
|
|
604
|
+
* project, a part of a call a guard cannot read, a guard that crashed or timed out) a refusal with the same hint. Where the agent
|
|
605
|
+
* runs in an auto mode an ask can be approved without the owner seeing it, so a project that runs agents there sets `asks: 'deny'`.
|
|
606
|
+
* Both are a drift guard, not a boundary: the owner's choice belongs in the launch environment (`VULCAN_GUARD_ASKS=deny`,
|
|
607
|
+
* `VULCAN_GUARD_OUTSIDE=deny`), where the strictest of the environment and the manifest holds and nothing in the project can
|
|
608
|
+
* loosen it (it also ignores `toolOwnedPaths` and `runners.allow` of the manifest, and every hook runs with `bun --no-env-file
|
|
609
|
+
* --config=/dev/null`). `guard-outside` denies an agent's write to the manifest, `.configs/vulcan.config.*`, `.claude/settings*.json` and
|
|
610
|
+
* `node_modules/@venizia/vulcan`.
|
|
584
611
|
*/
|
|
585
612
|
guard: z
|
|
586
613
|
.strictObject({
|
|
@@ -588,6 +615,8 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
|
|
|
588
615
|
toolOwnedPaths: z.array(z.string().min(1)).default([]),
|
|
589
616
|
/** What guard-outside does with a write outside the project: `ask` or `deny`; default `ask`. */
|
|
590
617
|
outside: z.enum([GuardDecisions.ASK, GuardDecisions.DENY]).default(GuardDecisions.ASK),
|
|
618
|
+
/** What every guard does with a call that needs a human to confirm it: `ask` or `deny`; default `ask`. Set `deny` where the agent runs in an auto mode; `VULCAN_GUARD_ASKS=deny` in the launch environment holds it where the project cannot. */
|
|
619
|
+
asks: z.enum([GuardDecisions.ASK, GuardDecisions.DENY]).default(GuardDecisions.ASK),
|
|
591
620
|
/** Write guard list: the project's own deploy and migrate commands; default `[]`. */
|
|
592
621
|
writes: z
|
|
593
622
|
.strictObject({
|
|
@@ -618,6 +647,7 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
|
|
|
618
647
|
.default({
|
|
619
648
|
toolOwnedPaths: [],
|
|
620
649
|
outside: GuardDecisions.ASK,
|
|
650
|
+
asks: GuardDecisions.ASK,
|
|
621
651
|
writes: { commands: [] },
|
|
622
652
|
git: { askPush: [] },
|
|
623
653
|
runners: { allow: [] },
|
|
@@ -20,6 +20,32 @@ export class HookConstants {
|
|
|
20
20
|
* unintended files into one commit; on this repository's develop the median commit touches 7 files and 2.2% touch more than 50.
|
|
21
21
|
*/
|
|
22
22
|
static readonly BLANKET_STAGE_PATHS = 50;
|
|
23
|
+
/** The environment variable that makes every guard refuse what it would ask about; the launch environment sets it, the project cannot loosen it. */
|
|
24
|
+
static readonly ENV_ASKS = 'VULCAN_GUARD_ASKS';
|
|
25
|
+
/** The environment variable that makes guard-outside refuse a write outside the project; as `ENV_ASKS`. */
|
|
26
|
+
static readonly ENV_OUTSIDE = 'VULCAN_GUARD_OUTSIDE';
|
|
27
|
+
/** What an answer says when the project (`guard.asks: 'deny'`) holds every ask. */
|
|
28
|
+
static readonly HELD_ASK =
|
|
29
|
+
'This project denies every call that would need a human to confirm it (guard.asks: deny). Nothing was run: hand this to the owner.';
|
|
30
|
+
/** What an answer says when the launch environment (`VULCAN_GUARD_ASKS=deny`) holds every ask. */
|
|
31
|
+
static readonly HELD_ASK_ENV =
|
|
32
|
+
'This session denies every call that would need a human to confirm it (VULCAN_GUARD_ASKS=deny). Nothing was run: hand this to the owner.';
|
|
33
|
+
/** What an answer says when the manifest exists and cannot be read: the hooks cannot tell what the project asked for, so an ask is a deny. */
|
|
34
|
+
static readonly MANIFEST_UNREADABLE =
|
|
35
|
+
'The manifest .agents/vulcan.manifest.json exists but cannot be read, so every call that would need a human to confirm it is denied. Nothing was run: the owner repairs the file or runs bun node_modules/.bin/vulcan sync.';
|
|
36
|
+
/**
|
|
37
|
+
* The files the guards read their policy from, relative to the project root: the manifest, the config, Claude Code's
|
|
38
|
+
* project settings and the installed package with its hooks. An agent that can write one can switch a guard off, so
|
|
39
|
+
* guard-outside denies a write to any of them; the owner changes them by hand, or through `vulcan sync`.
|
|
40
|
+
*/
|
|
41
|
+
static readonly PROTECTED_FILES = [
|
|
42
|
+
'.agents/vulcan.manifest.json',
|
|
43
|
+
'.configs/vulcan.config.*',
|
|
44
|
+
'.claude/settings.json',
|
|
45
|
+
'.claude/settings.local.json',
|
|
46
|
+
'node_modules/@venizia/vulcan',
|
|
47
|
+
'node_modules/@venizia/vulcan/**',
|
|
48
|
+
];
|
|
23
49
|
/** Branches no agent deletes or force-pushes (V-W-06). */
|
|
24
50
|
static readonly PROTECTED_BRANCHES = new Set(['develop', 'main']);
|
|
25
51
|
/**
|
|
@@ -57,4 +57,6 @@ export interface IOutsideHit {
|
|
|
57
57
|
isUnread: boolean;
|
|
58
58
|
/** Whether the path is what an `ln` of the line links to: a write through the link changes it, so the hook denies and says how to link a path inside. */
|
|
59
59
|
isLink?: boolean;
|
|
60
|
+
/** Whether the path is one of the files the guards read their policy from: the hook denies a write to it, whatever the project sets. */
|
|
61
|
+
isProtected?: boolean;
|
|
60
62
|
}
|
package/src/hooks/decision.ts
CHANGED
|
@@ -12,20 +12,31 @@ interface IDecisionOutput {
|
|
|
12
12
|
export class HookDecision {
|
|
13
13
|
/**
|
|
14
14
|
* The decision as every host that reads our hooks understands it. Claude Code and Cursor read
|
|
15
|
-
*
|
|
16
|
-
* too (Claude Code ignores them: checked). Cursor does not enforce an
|
|
17
|
-
* says it is running the hook (
|
|
15
|
+
* `hookSpecificOutput`; Copilot documents the same two fields at the top level, so they are written there
|
|
16
|
+
* too (Claude Code ignores them: checked). Cursor does not enforce an `ask` on a tool call, so where it
|
|
17
|
+
* says it is running the hook (`CURSOR_PROJECT_DIR`) an ask is a deny that says why. A project that sets `guard.asks: 'deny'`
|
|
18
|
+
* (`asks`) gets every ask as a deny too, because where the agent runs in an auto mode an ask can be approved with no human.
|
|
18
19
|
*/
|
|
19
|
-
static forHost(opts: {
|
|
20
|
+
static forHost(opts: {
|
|
21
|
+
output: IDecisionOutput;
|
|
22
|
+
env?: Record<string, string | undefined>;
|
|
23
|
+
asks?: string;
|
|
24
|
+
/** What the added line says when the ask is held; the project's own wording when it is not given. */
|
|
25
|
+
asksNote?: string;
|
|
26
|
+
}) {
|
|
20
27
|
const specific = opts.output.hookSpecificOutput;
|
|
21
28
|
const env = opts.env ?? process.env;
|
|
22
|
-
const
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
const decision = isCursorAsk ? GuardDecisions.DENY : specific.permissionDecision;
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
+
const isAsk = specific.permissionDecision === GuardDecisions.ASK;
|
|
30
|
+
const isHeld = isAsk && opts.asks === GuardDecisions.DENY;
|
|
31
|
+
const isCursorAsk = isAsk && env[HookConstants.CURSOR_PROJECT_DIR_ENV] !== undefined;
|
|
32
|
+
const decision = isHeld || isCursorAsk ? GuardDecisions.DENY : specific.permissionDecision;
|
|
33
|
+
let reason = specific.permissionDecisionReason;
|
|
34
|
+
|
|
35
|
+
if (isHeld) {
|
|
36
|
+
reason = `${reason}\n\n${opts.asksNote ?? HookConstants.HELD_ASK}`;
|
|
37
|
+
} else if (isCursorAsk) {
|
|
38
|
+
reason = `${reason}\n(Cursor cannot ask about a tool call: hand this to the owner)`;
|
|
39
|
+
}
|
|
29
40
|
|
|
30
41
|
return {
|
|
31
42
|
hookSpecificOutput: {
|
|
@@ -39,8 +50,15 @@ export class HookDecision {
|
|
|
39
50
|
}
|
|
40
51
|
|
|
41
52
|
/** The PreToolUse answer Claude Code reads from stdout: the decision and why, shown to the human or to the model. */
|
|
42
|
-
static buildTool(opts: {
|
|
53
|
+
static buildTool(opts: {
|
|
54
|
+
decision: TGuardDecision;
|
|
55
|
+
reason: string[];
|
|
56
|
+
asks?: string;
|
|
57
|
+
asksNote?: string;
|
|
58
|
+
}) {
|
|
43
59
|
return HookDecision.forHost({
|
|
60
|
+
asks: opts.asks,
|
|
61
|
+
asksNote: opts.asksNote,
|
|
44
62
|
output: {
|
|
45
63
|
hookSpecificOutput: {
|
|
46
64
|
hookEventName: HookConstants.PRE_TOOL_USE,
|
|
@@ -102,6 +102,31 @@ const matchesNothing = (opts: { word: string; base: string }): boolean => {
|
|
|
102
102
|
const isInside = (opts: { path: string; root: string }): boolean =>
|
|
103
103
|
opts.path === opts.root || opts.path.startsWith(`${opts.root}${sep}`);
|
|
104
104
|
|
|
105
|
+
/**
|
|
106
|
+
* Whether `path` is one of the files the guards read their policy from (`HookConstants.PROTECTED_FILES`), relative to the project
|
|
107
|
+
* root. A removal or a move also takes a folder that holds one of them (`rm -rf .claude`), bar `node_modules`, whose removal leaves
|
|
108
|
+
* the guards missing and the call blocked until `bun install`.
|
|
109
|
+
*/
|
|
110
|
+
const isProtectedFile = (opts: { path: string; root: string; isRemoval: boolean }): boolean => {
|
|
111
|
+
if (!isInside({ path: opts.path, root: opts.root }) || opts.path === opts.root) {
|
|
112
|
+
return false;
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
// Without regard to case: on a case-insensitive file system `.claude/Settings.local.json` is the real file.
|
|
116
|
+
const relative = opts.path.slice(opts.root.length + 1).toLowerCase();
|
|
117
|
+
const globs = HookConstants.PROTECTED_FILES.map((pattern) => pattern.toLowerCase());
|
|
118
|
+
|
|
119
|
+
if (globs.some((pattern) => new Bun.Glob(pattern).match(relative))) {
|
|
120
|
+
return true;
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
return (
|
|
124
|
+
opts.isRemoval &&
|
|
125
|
+
!relative.startsWith('node_modules') &&
|
|
126
|
+
globs.some((pattern) => pattern.startsWith(`${relative}/`))
|
|
127
|
+
);
|
|
128
|
+
};
|
|
129
|
+
|
|
105
130
|
/**
|
|
106
131
|
* A tool-owned pattern as an absolute glob: `~` and variables expanded, a bare directory taking everything
|
|
107
132
|
* below it. A pattern with an unset variable is dropped - it would otherwise match from the root.
|
|
@@ -248,7 +273,7 @@ export class OutsideGuard {
|
|
|
248
273
|
];
|
|
249
274
|
|
|
250
275
|
for (const target of targets) {
|
|
251
|
-
if (target.hasUnreadBrace === true) {
|
|
276
|
+
if (target.hasUnreadBrace === true && target.isProtectedOnly !== true) {
|
|
252
277
|
hits.push({
|
|
253
278
|
path: target.word,
|
|
254
279
|
message: `${target.message}: the word has a brace pattern this check cannot expand`,
|
|
@@ -294,6 +319,11 @@ export class OutsideGuard {
|
|
|
294
319
|
cwd: target.pwd,
|
|
295
320
|
});
|
|
296
321
|
|
|
322
|
+
if (expanded === undefined && target.isProtectedOnly === true) {
|
|
323
|
+
// A removal or an edit in place of a word this check cannot work out: nothing says it is a guard file.
|
|
324
|
+
continue;
|
|
325
|
+
}
|
|
326
|
+
|
|
297
327
|
if (expanded === undefined) {
|
|
298
328
|
// Part of the word is unknown, but the folder in front of it may not be: that folder decides.
|
|
299
329
|
const lands = ShellFolders.folderOfUnknown({
|
|
@@ -407,6 +437,28 @@ export class OutsideGuard {
|
|
|
407
437
|
continue;
|
|
408
438
|
}
|
|
409
439
|
|
|
440
|
+
// A write to a file the guards read their policy from switches a guard off: denied whatever the project sets.
|
|
441
|
+
const isRemoval = target.isProtectedOnly === true;
|
|
442
|
+
|
|
443
|
+
if (
|
|
444
|
+
isProtectedFile({ path, root, isRemoval }) ||
|
|
445
|
+
isProtectedFile({ path: resolve(written), root, isRemoval })
|
|
446
|
+
) {
|
|
447
|
+
hits.push({
|
|
448
|
+
path,
|
|
449
|
+
message: `${target.message}: it is one of the files the guards read their policy from`,
|
|
450
|
+
isAgentToolScratchpad: false,
|
|
451
|
+
isUnread: false,
|
|
452
|
+
isProtected: true,
|
|
453
|
+
});
|
|
454
|
+
|
|
455
|
+
continue;
|
|
456
|
+
}
|
|
457
|
+
|
|
458
|
+
if (isRemoval) {
|
|
459
|
+
continue;
|
|
460
|
+
}
|
|
461
|
+
|
|
410
462
|
if (!isInside({ path, root }) && !matchesAny({ path, patterns })) {
|
|
411
463
|
hits.push({
|
|
412
464
|
path,
|
|
@@ -131,11 +131,13 @@ export class WriteGuard {
|
|
|
131
131
|
/** The hits the reason lists; a line of many commands can find dozens. */
|
|
132
132
|
private static readonly MAX_LISTED_HITS = 20;
|
|
133
133
|
|
|
134
|
-
static buildDecision(opts: { hits: IWriteHit[] }) {
|
|
134
|
+
static buildDecision(opts: { hits: IWriteHit[]; asks?: string; asksNote?: string }) {
|
|
135
135
|
const listed = opts.hits.slice(0, WriteGuard.MAX_LISTED_HITS);
|
|
136
136
|
const unlisted = opts.hits.length - listed.length;
|
|
137
137
|
|
|
138
138
|
return HookDecision.forHost({
|
|
139
|
+
asks: opts.asks,
|
|
140
|
+
asksNote: opts.asksNote,
|
|
139
141
|
output: {
|
|
140
142
|
hookSpecificOutput: {
|
|
141
143
|
hookEventName: HookConstants.PRE_TOOL_USE,
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { existsSync, readFileSync } from 'node:fs';
|
|
2
2
|
import { join } from 'node:path';
|
|
3
|
-
import { GuardDecisions } from './common/index.ts';
|
|
3
|
+
import { GuardDecisions, HookConstants } from './common/index.ts';
|
|
4
4
|
|
|
5
5
|
/** A command the project says is a database write or a deploy: guard-writes asks on a match. */
|
|
6
6
|
export interface IProjectCommandCheck {
|
|
@@ -13,8 +13,15 @@ export interface IProjectCommandCheck {
|
|
|
13
13
|
interface IGuardPolicy {
|
|
14
14
|
commands: IProjectCommandCheck[];
|
|
15
15
|
askPush: string[];
|
|
16
|
-
/** `guard.outside`: what guard-outside does with a write outside the project; `
|
|
16
|
+
/** `guard.outside`: what guard-outside does with a write outside the project; the strictest of `VULCAN_GUARD_OUTSIDE` and the manifest, `ask` when neither says `deny`. */
|
|
17
17
|
outside: string;
|
|
18
|
+
/**
|
|
19
|
+
* `guard.asks`: `deny` makes every answer that would ask a human a refusal. The strictest of the launch environment
|
|
20
|
+
* (`VULCAN_GUARD_ASKS`), the manifest, and a manifest that exists but cannot be read; `ask` when none says otherwise.
|
|
21
|
+
*/
|
|
22
|
+
asks: string;
|
|
23
|
+
/** What the answer adds when an ask is held: which of the three held it; `undefined` when asks stay asks. */
|
|
24
|
+
asksNote?: string;
|
|
18
25
|
/** `guard.toolOwnedPaths`: stores a tool manages itself, which guard-outside lets through. */
|
|
19
26
|
toolOwnedPaths: string[];
|
|
20
27
|
/** `guard.runners.allow`: the package names bunx, `bun x`, npx and `pnpm dlx` may run beyond `@venizia/*`. */
|
|
@@ -78,15 +85,47 @@ export class ProjectGuards {
|
|
|
78
85
|
* manifest, or none of the block, has none; an entry that cannot be used is skipped, said once on
|
|
79
86
|
* stderr, and the others stay.
|
|
80
87
|
*/
|
|
81
|
-
static readPolicy(opts: {
|
|
88
|
+
static readPolicy(opts: {
|
|
89
|
+
root: string;
|
|
90
|
+
env?: Record<string, string | undefined>;
|
|
91
|
+
}): IGuardPolicy {
|
|
92
|
+
const policy = ProjectGuards.readManifest({ root: opts.root });
|
|
93
|
+
const env = opts.env ?? process.env;
|
|
94
|
+
const isEnvAsks = env[HookConstants.ENV_ASKS] === GuardDecisions.DENY;
|
|
95
|
+
const isEnvOutside = env[HookConstants.ENV_OUTSIDE] === GuardDecisions.DENY;
|
|
96
|
+
const isAsksDenied = isEnvAsks || policy.asks === GuardDecisions.DENY;
|
|
97
|
+
// Where the environment holds deny, the manifest is not trusted to loosen anything: the stores it would allow and the runners it would add are ignored.
|
|
98
|
+
const isEnvHeld = isEnvAsks || isEnvOutside;
|
|
99
|
+
|
|
100
|
+
return {
|
|
101
|
+
...policy,
|
|
102
|
+
toolOwnedPaths: isEnvHeld ? [] : policy.toolOwnedPaths,
|
|
103
|
+
runnersAllow: isEnvHeld ? [] : policy.runnersAllow,
|
|
104
|
+
asks: isAsksDenied ? GuardDecisions.DENY : GuardDecisions.ASK,
|
|
105
|
+
asksNote: isEnvAsks ? HookConstants.HELD_ASK_ENV : policy.asksNote,
|
|
106
|
+
outside:
|
|
107
|
+
isEnvOutside || policy.outside === GuardDecisions.DENY
|
|
108
|
+
? GuardDecisions.DENY
|
|
109
|
+
: GuardDecisions.ASK,
|
|
110
|
+
};
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
/** What the manifest sets, before the launch environment tightens it. A manifest that exists and cannot be read holds every ask. */
|
|
114
|
+
private static readManifest(opts: { root: string }): IGuardPolicy {
|
|
82
115
|
const path = join(opts.root, GUARD_MANIFEST_FILE);
|
|
83
116
|
const empty: IGuardPolicy = {
|
|
84
117
|
commands: [],
|
|
85
118
|
askPush: [],
|
|
86
119
|
outside: GuardDecisions.ASK,
|
|
120
|
+
asks: GuardDecisions.ASK,
|
|
87
121
|
toolOwnedPaths: [],
|
|
88
122
|
runnersAllow: [],
|
|
89
123
|
};
|
|
124
|
+
const unreadable: IGuardPolicy = {
|
|
125
|
+
...empty,
|
|
126
|
+
asks: GuardDecisions.DENY,
|
|
127
|
+
asksNote: HookConstants.MANIFEST_UNREADABLE,
|
|
128
|
+
};
|
|
90
129
|
|
|
91
130
|
if (!existsSync(path)) {
|
|
92
131
|
return empty;
|
|
@@ -98,14 +137,21 @@ export class ProjectGuards {
|
|
|
98
137
|
manifest = JSON.parse(readFileSync(path, 'utf8'));
|
|
99
138
|
} catch (error) {
|
|
100
139
|
note({
|
|
101
|
-
message: `the manifest could not be read, so the project's own patterns are off (${error instanceof Error ? error.message : String(error)})`,
|
|
140
|
+
message: `the manifest could not be read, so the project's own patterns are off and every ask is a deny (${error instanceof Error ? error.message : String(error)})`,
|
|
102
141
|
});
|
|
103
142
|
|
|
104
|
-
return
|
|
143
|
+
return unreadable;
|
|
105
144
|
}
|
|
106
145
|
|
|
107
146
|
const top = { value: manifest };
|
|
108
|
-
|
|
147
|
+
|
|
148
|
+
if (!isRecord(top)) {
|
|
149
|
+
note({ message: 'the manifest is not an object, so every ask is a deny' });
|
|
150
|
+
|
|
151
|
+
return unreadable;
|
|
152
|
+
}
|
|
153
|
+
|
|
154
|
+
const guard = { value: top.value['guard'] };
|
|
109
155
|
|
|
110
156
|
if (!isRecord(guard)) {
|
|
111
157
|
return empty;
|
|
@@ -131,6 +177,8 @@ export class ProjectGuards {
|
|
|
131
177
|
askPush: words(targets),
|
|
132
178
|
outside:
|
|
133
179
|
guard.value['outside'] === GuardDecisions.DENY ? GuardDecisions.DENY : GuardDecisions.ASK,
|
|
180
|
+
asks: guard.value['asks'] === GuardDecisions.DENY ? GuardDecisions.DENY : GuardDecisions.ASK,
|
|
181
|
+
asksNote: guard.value['asks'] === GuardDecisions.DENY ? HookConstants.HELD_ASK : undefined,
|
|
134
182
|
toolOwnedPaths: words(owned),
|
|
135
183
|
runnersAllow: isRecord(runners) ? words(runners.value['allow']) : [],
|
|
136
184
|
};
|
|
@@ -33,6 +33,11 @@ export interface IWriteTarget {
|
|
|
33
33
|
hasUnknownLink?: boolean;
|
|
34
34
|
/** A `$` of the word was quoted or escaped: it is a character, and the word's text reads it as a variable. */
|
|
35
35
|
hasLiteralDollar?: boolean;
|
|
36
|
+
/**
|
|
37
|
+
* A removal or an in-place edit (`rm`, `sed -i`, `mv` of a source...): it creates nothing, so only a file the guards read
|
|
38
|
+
* their policy from counts. Every other path of such a word is left to the owner.
|
|
39
|
+
*/
|
|
40
|
+
isProtectedOnly?: boolean;
|
|
36
41
|
}
|
|
37
42
|
|
|
38
43
|
/** The most words one word may make of its brace lists before the guard stops expanding it. */
|
|
@@ -414,6 +419,68 @@ export class ShellWrites {
|
|
|
414
419
|
],
|
|
415
420
|
},
|
|
416
421
|
};
|
|
422
|
+
/** The programs that remove or empty the files they are given. */
|
|
423
|
+
private static readonly REMOVERS = new Set(['rm', 'unlink', 'rmdir', 'shred', 'truncate']);
|
|
424
|
+
/** The `git` subcommands that remove, move or restore the files they are given. */
|
|
425
|
+
private static readonly GIT_FILE_COMMANDS = new Set(['rm', 'mv', 'restore', 'checkout']);
|
|
426
|
+
|
|
427
|
+
/**
|
|
428
|
+
* The words of a command that removes, moves away or edits in place the files it names: `rm`, `unlink`, `rmdir`, `shred`,
|
|
429
|
+
* `truncate`, `sed -i`, `perl -i`, the sources of `mv`, and `git rm`, `git mv`, `git restore` and `git checkout`. Each non-option
|
|
430
|
+
* word is a candidate; the guard keeps only those that are a file it protects.
|
|
431
|
+
*/
|
|
432
|
+
private static protectedWordsOf(opts: {
|
|
433
|
+
name: string;
|
|
434
|
+
args: string[];
|
|
435
|
+
values?: IOptionValues;
|
|
436
|
+
}): { word: string; message: string }[] {
|
|
437
|
+
const { name, args } = opts;
|
|
438
|
+
const words = (list: string[]): string[] => list.filter((word) => !word.startsWith('-'));
|
|
439
|
+
const named = (list: string[], what: string): { word: string; message: string }[] =>
|
|
440
|
+
words(list).map((word) => ({ word, message: `${what} ${word}` }));
|
|
441
|
+
|
|
442
|
+
if (ShellWrites.REMOVERS.has(name)) {
|
|
443
|
+
return named(args, `${name} removes or empties`);
|
|
444
|
+
}
|
|
445
|
+
|
|
446
|
+
if (
|
|
447
|
+
name === 'sed' &&
|
|
448
|
+
args.some(
|
|
449
|
+
(word) =>
|
|
450
|
+
word === '--in-place' || word.startsWith('--in-place=') || /^-[a-zA-Z]*i/.test(word),
|
|
451
|
+
)
|
|
452
|
+
) {
|
|
453
|
+
return named(args, 'sed edits in place');
|
|
454
|
+
}
|
|
455
|
+
|
|
456
|
+
if (name === 'perl' && args.some((word) => /^-[a-zA-Z]*i/.test(word))) {
|
|
457
|
+
return named(args, 'perl edits in place');
|
|
458
|
+
}
|
|
459
|
+
|
|
460
|
+
if (name === 'mv') {
|
|
461
|
+
const directory = valueOf({
|
|
462
|
+
args,
|
|
463
|
+
long: ['--target-directory'],
|
|
464
|
+
short: ['t'],
|
|
465
|
+
valued: opts.values?.shorts,
|
|
466
|
+
});
|
|
467
|
+
const sources = positional({ args, values: opts.values });
|
|
468
|
+
|
|
469
|
+
return named(directory === undefined ? sources.slice(0, -1) : sources, 'mv moves away');
|
|
470
|
+
}
|
|
471
|
+
|
|
472
|
+
if (name === 'git') {
|
|
473
|
+
const { rest } = gitArguments({ args });
|
|
474
|
+
const [sub, ...after] = rest;
|
|
475
|
+
|
|
476
|
+
return sub !== undefined && ShellWrites.GIT_FILE_COMMANDS.has(sub)
|
|
477
|
+
? named(after, `git ${sub} changes`)
|
|
478
|
+
: [];
|
|
479
|
+
}
|
|
480
|
+
|
|
481
|
+
return [];
|
|
482
|
+
}
|
|
483
|
+
|
|
417
484
|
/** The words a simple command would create or write, with a name for what writes them. */
|
|
418
485
|
static targetsOf(opts: { command: ISimpleCommand; base: string; tmp: string }): IWriteTarget[] {
|
|
419
486
|
const program = ShellParser.programOf({ command: opts.command });
|
|
@@ -558,6 +625,11 @@ export class ShellWrites {
|
|
|
558
625
|
}
|
|
559
626
|
}
|
|
560
627
|
|
|
628
|
+
// A removal or an in-place edit makes nothing outside the project, but it is how an agent loosens a guard.
|
|
629
|
+
for (const { word, message } of ShellWrites.protectedWordsOf({ name, args, values })) {
|
|
630
|
+
targets.push({ word, base, message, isProtectedOnly: true });
|
|
631
|
+
}
|
|
632
|
+
|
|
561
633
|
const own = maker !== undefined && maker.names.length > 0 ? maker.destination : undefined;
|
|
562
634
|
|
|
563
635
|
return [...assigned, ...targets]
|
package/src/manifest/render.ts
CHANGED
|
@@ -24,14 +24,14 @@ const HASH_LENGTH = 8;
|
|
|
24
24
|
|
|
25
25
|
/**
|
|
26
26
|
* The manifest's `guard` block: what the project sets for the guards, as data a hook reads without the config, so a
|
|
27
|
-
* config this VULCAN cannot parse never changes a guard: `outside` (when
|
|
27
|
+
* config this VULCAN cannot parse never changes a guard: `outside` and `asks` (when not the default), `toolOwnedPaths`,
|
|
28
28
|
* the commands of guard-writes, the push targets of guard-git, the runners the runner guard accepts.
|
|
29
29
|
*/
|
|
30
30
|
const guardBlockOf = (opts: { config: TResolvedConfig }): { guard?: Record<string, unknown> } => {
|
|
31
31
|
const { commands } = opts.config.guard.writes;
|
|
32
32
|
const { askPush } = opts.config.guard.git;
|
|
33
33
|
const { allow } = opts.config.guard.runners;
|
|
34
|
-
const { outside, toolOwnedPaths } = opts.config.guard;
|
|
34
|
+
const { outside, asks, toolOwnedPaths } = opts.config.guard;
|
|
35
35
|
const writes = {
|
|
36
36
|
...(commands.length === 0
|
|
37
37
|
? {}
|
|
@@ -46,6 +46,7 @@ const guardBlockOf = (opts: { config: TResolvedConfig }): { guard?: Record<strin
|
|
|
46
46
|
};
|
|
47
47
|
const block = {
|
|
48
48
|
...(outside === GuardDecisions.ASK ? {} : { outside }),
|
|
49
|
+
...(asks === GuardDecisions.ASK ? {} : { asks }),
|
|
49
50
|
...(toolOwnedPaths.length === 0 ? {} : { toolOwnedPaths }),
|
|
50
51
|
...(Object.keys(writes).length === 0 ? {} : { writes }),
|
|
51
52
|
...(askPush.length === 0 ? {} : { git: { askPush } }),
|