aegiscode 7.0.30 → 7.0.32

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 (38) hide show
  1. package/LICENSING.md +186 -0
  2. package/package.json +4 -2
  3. package/src/app.js +1 -1
  4. package/src/chatflow.js +1 -1
  5. package/src/commands.js +3 -1
  6. package/src/config.js +1 -1
  7. package/src/engine.js +1 -1
  8. package/src/history.js +1 -1
  9. package/src/models.js +1 -1
  10. package/src/overlays.js +1 -1
  11. package/src/panels.js +1 -1
  12. package/vendor/client/brain-catalog.js +1 -1
  13. package/vendor/client/byok-catalog.js +1 -1
  14. package/vendor/client/credits.js +45 -0
  15. package/vendor/client/foreign-sessions.js +3 -0
  16. package/vendor/client/naming.js +1 -1
  17. package/vendor/client/prefs.js +1 -1
  18. package/vendor/client/session-search.js +3 -0
  19. package/vendor/desktop/lib/local/claude-pro.js +1 -1
  20. package/vendor/desktop/lib/local/engine.js +1 -1
  21. package/vendor/desktop/lib/local/integrity.js +42 -2
  22. package/vendor/desktop/lib/local/perm-rules.js +206 -0
  23. package/vendor/desktop/lib/local/perm-store.js +298 -0
  24. package/vendor/desktop/lib/local/perm-write.js +199 -0
  25. package/vendor/desktop/lib/local/pro-sessions.js +3 -0
  26. package/vendor/desktop/lib/local/sandbox-appcontainer.js +242 -0
  27. package/vendor/desktop/lib/local/sandbox-bwrap.js +316 -0
  28. package/vendor/desktop/lib/local/sandbox-seatbelt.js +380 -0
  29. package/vendor/desktop/lib/local/sandbox.js +493 -0
  30. package/vendor/desktop/lib/local/shell.js +155 -20
  31. package/vendor/desktop/lib/local/tools.js +29 -4
  32. package/vendor/desktop/lib/settings.js +1 -1
  33. package/vendor/desktop/main.js +774 -37
  34. package/vendor/desktop/renderer/usage.js +1 -1
  35. package/vendor/mcp/admission.js +3 -0
  36. package/vendor/mcp/server.js +1 -1
  37. package/vendor/one/src/child.js +1 -1
  38. package/vendor/one/src/permissions.js +1 -1
@@ -0,0 +1,493 @@
1
+ // SPDX-License-Identifier: AGPL-3.0-or-later
2
+ // Copyright (C) 2026 Niklas Borneklint — AEGIS Code (aegiscode) / Aegiscloud.
3
+ // AEGIS Code (aegiscode) — source: https://github.com/aegisinfo/aegiscode-plugin
4
+ // Conveying a modified copy, or running one as a network service, owes the
5
+ // corresponding source under this licence (§5/§13) — see LICENSING.md.
6
+ 'use strict';
7
+
8
+ /**
9
+ * sandbox.js — bound what a shell command can DO, not only what it may ask.
10
+ *
11
+ * The approval card (`gatedExecuteTool` in engine.js) ratifies a DECISION: the
12
+ * user sees a command and says yes or no. It cannot bound the OUTCOME, because
13
+ * a command approved once runs to completion and an injected model can put
14
+ * anything after the `&&`. This module is the other half: a policy the kernel
15
+ * enforces, so "yes" means "yes, inside this boundary".
16
+ *
17
+ * Phase 1b of ~/plan/agent-safety-plan.md. This file is the POLICY (what a batch
18
+ * may reach) and the one place a spawn decides whether it is confined. The
19
+ * per-OS mechanism lives beside it — `sandbox-seatbelt.js` (Seatbelt) and
20
+ * `sandbox-appcontainer.js` (AppContainer) — because the kernel half genuinely differs
21
+ * per platform while the policy vocabulary does not.
22
+ *
23
+ * Linux/bubblewrap is the only mechanism verifiable on this host. The others are
24
+ * NOT faked: an unsupported host reports `reason`, never a silent no-op, and
25
+ * `describe()` prints what actually ran rather than a mode name.
26
+ *
27
+ * ── The rule this file exists to obey ────────────────────────────────────────
28
+ *
29
+ * A sandbox that silently does nothing is WORSE than no sandbox: it is a false
30
+ * assurance, and the user reads "sandboxed" in the UI while the command has
31
+ * full write access to their home directory. So every path here is fail-LOUD:
32
+ *
33
+ * · `detect()` really executes `bwrap` once and reports what happened.
34
+ * · a policy that cannot be enforced yields `{ ok: false, reason }`, and the
35
+ * caller must surface that — `wrap()` returns null rather than pretending.
36
+ * · `describe()` is what the UI prints, and it never claims more than the
37
+ * enforcement that actually ran.
38
+ *
39
+ * ── Why bwrap, and what it is not ────────────────────────────────────────────
40
+ *
41
+ * bubblewrap is a setuid-free user-namespace wrapper: `--ro-bind / /` makes the
42
+ * whole filesystem read-only, and each `--bind` re-opens exactly the paths the
43
+ * policy grants write. That is a capability grant, not a path blacklist — a
44
+ * blacklist is what a determined command walks around.
45
+ *
46
+ * It is NOT a defence against a kernel user-namespace escape, and it is not a
47
+ * network firewall (see `network: 'restricted'` — `--unshare-net` removes the
48
+ * interface, which stops TCP/UDP but leaves nothing to leak through because
49
+ * there is no interface to bind).
50
+ *
51
+ * Unprivileged user namespaces are restricted by AppArmor on Ubuntu 23.10+ and
52
+ * in most container images. When that happens the probe FAILS and the caller
53
+ * gets a loud degrade, not a quiet pass — this machine allows them
54
+ * (`kernel.apparmor_restrict_unprivileged_userns=0`, `max_user_namespaces`
55
+ * large), which is why the tests can spawn a real sandbox here.
56
+ */
57
+
58
+ const fs = require('node:fs');
59
+ const path = require('node:path');
60
+
61
+ /** Policy modes, weakest to strongest. `off` is explicit, never a default. */
62
+ const MODES = Object.freeze(['off', 'read-only', 'workspace-write', 'managed']);
63
+
64
+ /** Where a vendored bwrap would live, relative to the app dir. */
65
+ const VENDOR_REL = path.join('vendor', 'sandbox');
66
+
67
+ /**
68
+ * The per-platform mechanisms, loaded lazily and named for the MECHANISM rather
69
+ * than the OS.
70
+ *
71
+ * Two reasons for the mechanism names. First, they are what the file actually
72
+ * owns: `sandbox-seatbelt.js` describes a policy translation, and "darwin" adds
73
+ * nothing a reader does not already get from `platform === 'darwin'` on the line
74
+ * above it. Second, `one/scripts/predist.mjs` is held to an OS-blind rule (the
75
+ * stager may not know what platform it is running on), and a file NAMED after an
76
+ * OS drags that vocabulary into its staging list. Renaming the modules keeps the
77
+ * stager honest instead of weakening the guard — the test that catches this is
78
+ * `one-vendor.test.mjs`.
79
+ */
80
+ function mechanism(platform) {
81
+ if (platform === 'linux') return require('./sandbox-bwrap.js');
82
+ if (platform === 'darwin') return require('./sandbox-seatbelt.js');
83
+ if (platform === 'win32') return require('./sandbox-appcontainer.js');
84
+ return null;
85
+ }
86
+
87
+ /**
88
+ * True when this platform has a mechanism that can actually enforce a policy.
89
+ *
90
+ * `sandbox-appcontainer.js` is loaded but reports `implemented: false`: AppContainer
91
+ * has no command-line wrapper, so there is nothing to ship until a signed
92
+ * helper exists. Counting its presence as support would be exactly the false
93
+ * assurance this file's header forbids.
94
+ */
95
+ function supported(platform = process.platform) {
96
+ const mod = mechanism(platform);
97
+ return Boolean(mod && mod.implemented !== false);
98
+ }
99
+
100
+ /**
101
+ * Execute a probe for real, on THIS platform's mechanism. Never throws.
102
+ *
103
+ * Injectable `probe` so the "unavailable" branch is testable without breaking
104
+ * the host's own user namespaces.
105
+ *
106
+ * @returns {{ available: boolean, path: string|null, reason: string|null, probed: boolean }}
107
+ */
108
+ function detect({ appDir, env = process.env, platform = process.platform, probe } = {}) {
109
+ const mod = mechanism(platform);
110
+ if (!mod) {
111
+ return {
112
+ available: false,
113
+ path: null,
114
+ reason: `no sandbox implementation for ${platform} yet`,
115
+ probed: false,
116
+ };
117
+ }
118
+ // A module that exists but is unimplemented still owns the REASON string —
119
+ // it knows why it cannot confine, and duplicating that sentence here would
120
+ // let the two drift apart.
121
+ return mod.detect({ appDir, env, platform, probe });
122
+ }
123
+
124
+ /**
125
+ * `detect()` behind a cache, for the POSTURE CARD.
126
+ *
127
+ * The probe is a real `spawnSync` with a 5s timeout (`sandbox-bwrap.js`), and
128
+ * `detect()` deliberately re-runs it every call so a transcript never quotes a
129
+ * stale answer. That is the right trade for a spawn decision and the wrong one
130
+ * for a pane that repaints on every mode switch and every settings save: the
131
+ * window thread would block on a subprocess each time, and a host where bwrap
132
+ * hangs would make the posture switch feel broken.
133
+ *
134
+ * The cache is keyed on what could actually change the answer — the binary's
135
+ * path AND its mtime — so upgrading bwrap on disk re-probes without a restart,
136
+ * and `invalidate()` exists for the one case the key cannot see: the binary
137
+ * replaced by a file with an identical timestamp. A TTL is deliberately NOT
138
+ * used; a sandbox state that expires is a state that can go stale silently.
139
+ *
140
+ * Only `detect()` is cached. `wrap()`/`spawnPlan()` keep their own fresh probe
141
+ * via `detect()` directly, because a spawn that decides from a cached verdict
142
+ * is exactly the false assurance this file forbids.
143
+ */
144
+ const probeCache = new Map();
145
+
146
+ function cacheKey(appDir, platform) {
147
+ return `${platform}\u0000${appDir ? path.resolve(String(appDir)) : ''}`;
148
+ }
149
+
150
+ /**
151
+ * A `detect()` whose answer is memoised until the binary changes.
152
+ *
153
+ * @returns {{ available: boolean, path: string|null, reason: string|null, probed: boolean, cached?: boolean }}
154
+ */
155
+ function detectCached({ appDir, env = process.env, platform = process.platform, probe } = {}) {
156
+ // An injected probe is a TEST seam: caching it would make the stub's second
157
+ // answer depend on the first, so it always runs live and never touches the
158
+ // cache. Same reasoning for any non-default env.
159
+ if (typeof probe === 'function') return detect({ appDir, env, platform, probe });
160
+ const key = cacheKey(appDir, platform);
161
+ const hit = probeCache.get(key);
162
+ if (hit && hit.env === env) {
163
+ // vouch for the binary still being the one that was probed
164
+ let same = false;
165
+ try {
166
+ same = Boolean(hit.path) && fs.statSync(hit.path).mtimeMs === hit.mtimeMs;
167
+ } catch {
168
+ same = !hit.path;
169
+ }
170
+ if (same) return { ...hit.state, cached: true };
171
+ probeCache.delete(key);
172
+ }
173
+ const state = detect({ appDir, env, platform });
174
+ let mtimeMs = null;
175
+ if (state.path) {
176
+ try {
177
+ mtimeMs = fs.statSync(state.path).mtimeMs;
178
+ } catch {
179
+ mtimeMs = null;
180
+ }
181
+ }
182
+ probeCache.set(key, { state, path: state.path, mtimeMs, env });
183
+ return state;
184
+ }
185
+
186
+ /** Drop a memoised probe. Called when a policy save could change the answer. */
187
+ function invalidateProbe(appDir, platform = process.platform) {
188
+ if (appDir === undefined) return probeCache.clear();
189
+ return probeCache.delete(cacheKey(appDir, platform));
190
+ }
191
+
192
+ /**
193
+ * The default policy: workspace-write.
194
+ *
195
+ * Expressed with the same vocabulary as the comparison set's `sandbox_policy`
196
+ * (per-path access grants, `missingPathBehavior`, network as its own axis), so
197
+ * a future settings UI and a future import have one shape to learn rather than
198
+ * two. See ~/plan/agent-safety-plan.md §1a.
199
+ */
200
+ function defaultPolicy(workspace) {
201
+ const ws = workspace ? path.resolve(workspace) : null;
202
+ const entries = [{ path: { type: 'special', value: { kind: 'root' } }, access: 'read' }];
203
+ if (ws) entries.push({ path: { type: 'path', path: ws }, access: 'write' });
204
+ entries.push({ path: { type: 'special', value: { kind: 'slash_tmp' } }, access: 'write' });
205
+ if (ws) {
206
+ entries.push({
207
+ path: { type: 'path', path: path.join(ws, '.git') },
208
+ access: 'read',
209
+ missingPathBehavior: 'skip',
210
+ });
211
+ }
212
+ return { mode: 'workspace-write', fileSystem: { entries, denies: [] }, network: 'restricted' };
213
+ }
214
+
215
+ /**
216
+ * The paths every model class needs in order to RUN, granted automatically.
217
+ *
218
+ * The problem this solves is concrete: a confined turn that cannot read the
219
+ * model table, the credentials file or a local model's own weights does not
220
+ * fail loudly — it fails as "the model is broken", because the child process
221
+ * gets EACCES on an open() it never reports to the transcript. So the grants
222
+ * that make `aegis`, `byok`, `local` and `pro` work are seeded for EVERY class
223
+ * rather than left for the user to discover one denial at a time.
224
+ *
225
+ * `access` is deliberately read-only for the shared state: a turn needs to READ
226
+ * `models.json` and `credentials.json`, never rewrite them mid-run. Granting
227
+ * write there would let one injected turn redefine the next turn's model table
228
+ * — and, worse, rewrite its own sandbox policy, which is the one file the
229
+ * sandbox must not be able to unlock itself with.
230
+ *
231
+ * `/tmp` is write because every toolchain (npm, pip, cc, git) stages there, and
232
+ * a read-only /tmp breaks builds in a way that reads as a sandbox bug.
233
+ *
234
+ * Entries that do not exist are `missingPathBehavior: 'skip'` — a fresh install
235
+ * has no `models.json` yet, and a hard failure on a path that is legitimately
236
+ * absent would refuse every command on first run.
237
+ *
238
+ * @param {string} workspace the turn's cwd
239
+ * @param {{home?: string, gitRoot?: string, addDirs?: string[]}} [opts]
240
+ * @returns {object[]} entries in the same vocabulary `normalize()` accepts
241
+ */
242
+ function autoGrants(workspace, opts = {}) {
243
+ const out = [];
244
+ const seen = new Set();
245
+ const push = (p, access) => {
246
+ if (!p) return;
247
+ let abs;
248
+ try {
249
+ abs = path.resolve(String(p));
250
+ } catch {
251
+ return;
252
+ }
253
+ // A grant on the filesystem root is a no-op that claims to be a bound (the
254
+ // mechanisms refuse it outright). Dropping here means one bad addDir cannot
255
+ // turn the whole policy into a loud policyFault and refuse every command.
256
+ if (abs === path.parse(abs).root) return;
257
+ const k = `${access}:${abs}`;
258
+ if (seen.has(k)) return;
259
+ seen.add(k);
260
+ out.push({ path: { type: 'path', path: abs }, access, missingPathBehavior: 'skip' });
261
+ };
262
+
263
+ // The workspace itself, and the repository that contains it. A turn that can
264
+ // edit a file but not read `.git` cannot commit, diff or resolve a conflict —
265
+ // which is most of what an agent is asked to do in a repo.
266
+ push(workspace, 'write');
267
+ push(opts.gitRoot || workspace, 'write');
268
+ for (const d of Array.isArray(opts.addDirs) ? opts.addDirs : []) push(d, 'write');
269
+
270
+ const home = opts.home || null;
271
+ if (home) {
272
+ // Read-only shared state: the model table, the pinned class, the credentials
273
+ // and the workspace-scoped memory all live under the aegis data dir.
274
+ push(path.join(home, '.aegiscode'), 'read');
275
+ // Local models added by the user. Ollama's own blob store is under
276
+ // ~/.ollama; a user-added model served from a file path is granted by
277
+ // `addDirs` above, since only the caller knows where it put it.
278
+ push(path.join(home, '.ollama'), 'read');
279
+ }
280
+
281
+ // Write: every toolchain stages there.
282
+ push('/tmp', 'write');
283
+ return out;
284
+ }
285
+
286
+ /** Resolve an entry's absolute path, or null when it names a special location. */
287
+ function entryPath(entry) {
288
+ const p = entry && entry.path;
289
+ if (!p) return null;
290
+ if (p.type === 'path') return typeof p.path === 'string' && p.path ? p.path : null;
291
+ return null;
292
+ }
293
+
294
+ /** Is this a special we know how to map onto bwrap argv? */
295
+ function isSpecial(entry, kind) {
296
+ const p = entry && entry.path;
297
+ return Boolean(p && p.type === 'special' && p.value && p.value.kind === kind);
298
+ }
299
+
300
+ /**
301
+ * Normalise whatever a settings file held into a policy we would enforce.
302
+ *
303
+ * Unknown modes, non-array entries and junk accesses are DROPPED rather than
304
+ * coerced into something permissive: a policy that fails to parse must not
305
+ * become "everything writable". A dropped entry means a narrower sandbox, and
306
+ * narrow is the safe direction to be wrong in.
307
+ */
308
+ function normalize(raw, workspace) {
309
+ if (!raw || typeof raw !== 'object') return defaultPolicy(workspace);
310
+ const mode = MODES.includes(raw.mode) ? raw.mode : 'workspace-write';
311
+ if (mode === 'off') return { mode: 'off', fileSystem: { entries: [] }, network: 'open' };
312
+ const src = raw.fileSystem && Array.isArray(raw.fileSystem.entries) ? raw.fileSystem.entries : null;
313
+ const base = defaultPolicy(workspace);
314
+ // The MODE is the outer bound, and it wins over the entries.
315
+ //
316
+ // `read-only` with no explicit entries used to fall through to
317
+ // defaultPolicy(), which is a workspace-WRITE policy — so a caller who asked
318
+ // for read-only was handed the ONE writable workspace tree and a writable
319
+ // /tmp while the state still reported `read-only`. That is precisely the
320
+ // failure this file is not allowed to have: reporting a narrower sandbox
321
+ // than the one enforced. A mode that names an upper bound now imposes it,
322
+ // whatever the entries say; the entries can only narrow further.
323
+ const modeBansWrite = mode === 'read-only';
324
+ const entries = [];
325
+ const denies = [];
326
+ for (const e of src || base.fileSystem.entries) {
327
+ if (modeBansWrite && e && e.access === 'write') continue;
328
+ if (!e || typeof e !== 'object') continue;
329
+ // `none` is the DENY vocabulary, and it is a separate list rather than a
330
+ // third access value. bwrap expresses it as `--tmpfs <path>` emitted AFTER
331
+ // every bind, because later mounts shadow earlier ones — so a deny is an
332
+ // overlay, not a grant, and collapsing it into the grant list would let the
333
+ // emit loop bind and then re-bind the same path in an order that depends on
334
+ // array position. Kept apart so the ordering rule lives in one place.
335
+ if (e.access === 'none') {
336
+ const dp = e.path;
337
+ if (!dp || typeof dp !== 'object' || dp.type !== 'path') continue;
338
+ if (typeof dp.path !== 'string' || !dp.path) continue;
339
+ denies.push({ path: path.resolve(dp.path) });
340
+ continue;
341
+ }
342
+ const access = e.access === 'write' ? 'write' : e.access === 'read' ? 'read' : null;
343
+ if (!access) continue;
344
+ const p = e.path;
345
+ if (!p || typeof p !== 'object') continue;
346
+ if (p.type !== 'path' && p.type !== 'special') continue;
347
+ if (p.type === 'path' && (typeof p.path !== 'string' || !p.path)) continue;
348
+ const out = { path: p, access };
349
+ if (e.missingPathBehavior === 'skip') out.missingPathBehavior = 'skip';
350
+ entries.push(out);
351
+ }
352
+ const network = raw.network === 'open' ? 'open' : 'restricted';
353
+ return { mode, fileSystem: { entries, denies }, network };
354
+ }
355
+
356
+ /**
357
+ * Build the argv prefix for one command, using THIS platform's mechanism.
358
+ *
359
+ * Delegates, because the argv shape is the one thing that genuinely cannot be
360
+ * shared: bwrap is `[bwrap, flags…, --, cmd]`, Seatbelt is
361
+ * `[sandbox-exec, -p, profile, cmd]`, and the Windows helper is
362
+ * `[host.exe, --grant-write, …, --, cmd]`. `spawnPlan` below knows how to split
363
+ * all three back apart because each appends `argv` then the command last.
364
+ *
365
+ * Takes an ALREADY-NORMALISED policy: the mode bound lives in `normalize()` and
366
+ * is enforced for every platform in one place.
367
+ */
368
+ function wrap(policyInput, command, opts = {}) {
369
+ const platform = opts.platform || process.platform;
370
+ const mod = mechanism(platform);
371
+ if (!mod) return { ok: false, reason: `no sandbox implementation for ${platform}` };
372
+ const policy = normalize(policyInput, opts.workspace);
373
+ if (policy.mode === 'off') return { ok: false, reason: 'sandbox disabled by policy' };
374
+ // Each mechanism names its own binary option; `bwrap` is kept as the shared
375
+ // spelling so existing callers (and the sandbox seam in shell.js/tools.js)
376
+ // did not have to learn a new key per platform.
377
+ const bin = opts.bwrap || opts.seatbelt || opts.host;
378
+ return mod.wrap(policy, command, { ...opts, bwrap: bin, seatbelt: bin, host: bin, policy });
379
+ }
380
+
381
+ /**
382
+ * The one place a spawn decides whether it is sandboxed.
383
+ *
384
+ * Both shell paths (the persistent `ShellSession` and the one-shot fallback)
385
+ * call this, so "is this command confined" has ONE answer rather than two that
386
+ * can drift. Returns:
387
+ *
388
+ * { ok: true, file, args, degraded } spawn this; `degraded` is the reason
389
+ * when nothing confined it (null when
390
+ * the sandbox really applied)
391
+ * { ok: false, reason } do NOT spawn — policy says refuse
392
+ *
393
+ * The `strict` flag is the difference between those two failure responses: by
394
+ * default an unavailable sandbox DEGRADES (and says so, loudly, through
395
+ * `degraded`), because refusing every command on AppArmor-restricted Ubuntu
396
+ * would brick the product rather than protect it. `strict: true` refuses
397
+ * instead, which is the setting for someone who would rather have no shell
398
+ * than an unconfined one.
399
+ *
400
+ * @param {{state?: object, policy?: object, strict?: boolean, workspace?: string, bwrap?: string, platform?: string}|null} cfg
401
+ * @param {string} cmd the shell binary
402
+ * @param {string[]} args
403
+ * @param {{cwd?: string}} opts
404
+ */
405
+ function spawnPlan(cfg, cmd, args, opts = {}) {
406
+ const strict = Boolean(cfg && cfg.strict);
407
+ const policy = cfg && cfg.policy ? cfg.policy : null;
408
+
409
+ // No policy at all means the caller did not ask for a sandbox (a bare
410
+ // `executeTool` in a test, say). Not an error, and not a degrade — silence.
411
+ if (!cfg || !policy || policy.mode === 'off') {
412
+ return { ok: true, file: cmd, args: args.slice(), degraded: null };
413
+ }
414
+
415
+ const state = cfg.state || detect({ appDir: cfg.appDir, env: cfg.env, platform: cfg.platform });
416
+ if (!state.available) {
417
+ if (strict) return { ok: false, reason: describe(state, policy) };
418
+ return { ok: true, file: cmd, args: args.slice(), degraded: describe(state, policy) };
419
+ }
420
+
421
+ const bin = state.path || cfg.bwrap;
422
+ // The shell itself is the mechanism's payload: the wrapper argv ends with the
423
+ // command, and the split below moves it in front of the caller's args.
424
+ const wrapped = wrap(policy, cmd, {
425
+ bwrap: bin,
426
+ workspace: cfg.workspace,
427
+ cwd: opts.cwd,
428
+ platform: cfg.platform,
429
+ });
430
+ if (!wrapped.ok) {
431
+ // A policy fault is NOT the same failure as "this machine cannot sandbox".
432
+ // `degraded` exists so an unavailable mechanism (AppArmor, no bwrap) does not
433
+ // brick the product; but a policy that can never be honoured — a write grant
434
+ // on a missing path, a write grant on the filesystem root, a path that cannot
435
+ // be expressed in a Seatbelt profile — is a caller error, and running it
436
+ // unconfined would silently grant access the policy was written to forbid.
437
+ // So this refuses regardless of `strict`, and does so BEFORE the workspace
438
+ // is spawned rather than after.
439
+ if (wrapped.policyFault) {
440
+ return { ok: false, reason: `sandbox policy cannot be honoured: ${wrapped.reason}` };
441
+ }
442
+ if (strict) return { ok: false, reason: wrapped.reason };
443
+ return { ok: true, file: cmd, args: args.slice(), degraded: `sandbox policy not enforceable: ${wrapped.reason}` };
444
+ }
445
+ // wrap() appended the caller's argv then `cmd` as the LAST element; for a
446
+ // spawn we need file + args, so the trailing placeholder is dropped and the
447
+ // real `cmd`/`args` are appended after whatever prefix the mechanism built.
448
+ // Every mechanism obeys that shape (bwrap's `--`, Seatbelt's profile, the
449
+ // Windows helper's `--` all sit earlier in the argv), which is why this is one
450
+ // line rather than a per-platform split.
451
+ const argv = wrapped.argv.slice(0, wrapped.argv.length - 1).concat([cmd], args);
452
+ return { ok: true, file: argv[0], args: argv.slice(1), degraded: null };
453
+ }
454
+
455
+ /**
456
+ * The sentence the UI and the transcript print.
457
+ *
458
+ * Delegates to the mechanism, because the GUARANTEE differs: bwrap is a
459
+ * capability grant, Seatbelt is a strong blacklist, and Windows has nothing.
460
+ * Printing one shared sentence would claim bwrap's guarantee on macOS, and a
461
+ * lie here costs more than the sandbox buys — it transfers trust the user never
462
+ * granted.
463
+ */
464
+ function describe(state, policy, platform = process.platform) {
465
+ const mod = mechanism(platform);
466
+ if (mod && typeof mod.describe === 'function') return mod.describe(state, policy);
467
+ if (!state || !state.available) {
468
+ return `sandbox: OFF — ${(state && state.reason) || 'unavailable'} (commands run with full user access)`;
469
+ }
470
+ return `sandbox: ${(policy && policy.mode) || 'workspace-write'} — mechanism unknown`;
471
+ }
472
+
473
+ module.exports = {
474
+ MODES,
475
+ VENDOR_REL,
476
+ supported,
477
+ mechanism,
478
+ detect,
479
+ detectCached,
480
+ invalidateProbe,
481
+ defaultPolicy,
482
+ autoGrants,
483
+ normalize,
484
+ wrap,
485
+ spawnPlan,
486
+ describe,
487
+ // Exported for tests only — deliberately NOT part of the enforced surface.
488
+ // Reading a policy's shape ("did the default pin .git read-only?") is a
489
+ // question a test must be able to ask without re-deriving the vocabulary it
490
+ // is asserting on, which would let the test and the module drift together.
491
+ entryPath,
492
+ isSpecial,
493
+ };