projectwrap 202604.2__tar.gz → 202604.3__tar.gz

{projectwrap-202604.2 → projectwrap-202604.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: projectwrap
-Version: 202604.2
+Version: 202604.3
 Summary: Isolated project environments with bubblewrap sandboxing
 License: MIT
 Keywords: sandbox,bubblewrap,bwrap,isolation,development,security
@@ -59,7 +59,9 @@ _absolutely no warranty_.
 - Protect you from `root`
 
 **Dependencies:** Python 3.11+ (stdlib only, no pip dependencies),
-[bubblewrap](https://github.com/containers/bubblewrap) for sandboxing,
+[bubblewrap](https://github.com/containers/bubblewrap) ≥ 0.4 for sandboxing
+(encrypted volumes need `--unshare-user` / `--uid` support to drop back to
+the real uid inside the sandbox),
 [gocryptfs](https://nuetzlich.net/gocryptfs/) for encrypted volumes.
 
 **Design principles:**
@@ -113,6 +115,8 @@ blacklist = [  # can't be accessed at all from the sandbox
     "~/.aws",
     "~/.ssh",
     "~/projects/",  # hide all other projects
+    # trimmed for brevity — see the generated template (`pwrap --new`) for
+    # the full default blacklist (GCP, Azure, GPG, docker, npm, PyPI, /mnt).
 ]
 whitelist = [  # exceptions to the blacklist
     "~/.kube/myproject",
@@ -170,6 +174,95 @@ set -gx AICHAT_CONFIG_DIR vault/aichat
 
 ```
 
+##### Claude Code in sandbox #####
+
+Claude Code writes state to several paths under `~/` (`~/.claude`,
+`~/.claude.json.lock`, `~/.local/state/claude`, `~/.cache/claude-cli-nodejs`,
+`~/.npm`). Rather than making each of these writable, redirect all of Claude's
+state into the project directory:
+
+```toml
+[env]
+CLAUDE_CONFIG_DIR = "vault/claude"   # or any writable path inside the sandbox
+```
+
+This gives each project its own Claude state (settings, history, MCP logs) —
+no leakage between sandboxed projects. With an `[encrypted]` volume, Claude's
+state is encrypted at rest.
+
+##### Encrypted vault, minimal sandbox rules #####
+
+Minimal sandbox configuration — no custom blacklists or whitelists, no
+`clean_env`. The goal is to keep secrets (kubeconfig, shell history, LLM
+chat logs) encrypted at rest and isolated per project, without locking down
+the rest of the environment.
+
+```toml
+[project]
+name = "myproject"
+dir = "~/projects/myproject"
+shell = "/usr/bin/fish"
+
+[sandbox]
+enabled = true
+
+[encrypted]
+cipherdir = "encrypted"
+mountpoint = "~/projects/myproject/vault"
+
+[env]
+KUBECONFIG = "vault/kubeconfig"
+CLAUDE_CONFIG_DIR = "vault/claude"
+XDG_DATA_HOME = "vault/.config"   # fish history, tool state
+```
+
+`init.fish`:
+```fish
+source .venv/bin/activate.fish
+```
+
+`[sandbox] enabled = true` still applies the security defaults below: home
+is bound read-only, the config dir is blacklisted, the docker socket is
+masked, `/tmp` is a tmpfs, and PID/IPC namespaces are isolated. With no
+custom blacklist/whitelist/writable entries, the only writable paths are
+the project directory and the vault mountpoint — reads from anywhere else
+under home still work, but writes outside those two paths fail. Add entries
+to `writable` to poke rw holes in the read-only home if you need them. The
+encrypted vault holds project-specific secrets and history that disappear
+when the shell exits; `vault/` lives inside the project directory so it's
+writable by default.
+
+##### Maximum isolation #####
+
+Default-deny for both filesystem and environment. Nothing is visible or set
+unless explicitly allowed.
+
+```toml
+[project]
+name = "myproject"
+dir = "~/projects/myproject"
+shell = "/usr/bin/fish"
+
+[sandbox]
+enabled = true
+clean_env = true                  # only PATH/HOME/USER/SHELL/TERM/LANG
+blacklist = [
+    "~",                          # hide all dotfiles and home contents
+    "/mnt",                       # WSL: hide Windows drives
+]
+whitelist = [
+    "~/.config/fish",             # shell config (read-only)
+    "~/.pyenv",                   # python versions (read-only)
+]
+
+[env]
+XDG_DATA_HOME = ".config"        # fish history, tool state → project dir
+```
+
+The project directory is always writable regardless of blacklist. With
+`XDG_DATA_HOME` pointing inside it, fish history and XDG-aware tools write
+their state there instead of the (hidden) home directory.
+
 ##### GUI apps in sandbox #####
 
 To run emacs or other GUI apps inside the sandbox on WSL2:
@@ -216,12 +309,9 @@ with an `[encrypted]` section, pointing at the mountpoint. Use it from init
 scripts or app configs to redirect history/state into the vault without
 hardcoding paths per project.
 
-**You will appear as root.** Mounting gocryptfs unprivileged requires
-`unshare --user --map-root-user`, so `whoami` reports `root` and `id -u`
-reports `0` inside the sandbox. This is a user-namespace remapping only —
-you have no real privileges on the host and cannot escalate. Your files
-remain owned by your real uid. Scripts that gate on `$UID == 0` will
-misbehave; check `$PROJECT_WRAP` or `$PWRAP_VAULT_DIR` instead.
+**If `id -u` reports 0 inside the sandbox**, your bubblewrap is too old —
+run `pwrap --check-deps`. Encrypted vaults need `--unshare-user` / `--uid`
+support (bubblewrap ≥ 0.4) to drop back to your real uid.
 
 **Multiple terminals** (`shared = false`, default): each terminal gets an
 independent gocryptfs mount. Writes to different files merge on next
@@ -242,8 +332,7 @@ and the mount is released.
 pwrap                                      # list projects
 pwrap myproject                            # launch project
 pwrap -v myproject                         # verbose output
-pwrap --new ~/projects/myproject           # create config (name from dir)
-pwrap --new ~/projects/myproject custom    # create with explicit name
+pwrap --new ~/projects/myproject           # create config (name = dir basename)
 pwrap --new --shell /bin/bash ~/projects/x # specify shell
 pwrap --check-deps                         # check optional dependencies
 pwrap --version                            # show version
@@ -255,12 +344,17 @@ When sandboxing is enabled:
 
 - Home is **read-only**; only the project directory is writable
 - Config directory (`~/.config/pwrap`) is always blacklisted
+- Docker socket (`/run/docker.sock`) masked — `connect()` works on
+  ro-bound sockets, so an exposed docker socket is a full escape to root
+- Default template blacklists credential dirs (SSH, GPG, AWS, GCP, Azure,
+  Docker, npm, PyPI) and `/mnt` (WSL Windows drives)
 - PID and IPC namespaces are isolated
 - TIOCSTI injection blocked automatically on kernels < 6.2
-- XDG runtime directory isolated
+- XDG runtime directory isolated (D-Bus, Wayland, keyring sockets)
 - Sandbox dies with parent process
 - Encrypted volumes mount in isolated namespace (invisible on host)
-- All paths in shell commands are quoted to prevent injection
+- Writable paths are auto-created (as directories) if they don't exist;
+  paths that already exist are bound as-is, so a file entry binds that file
 
 Run your editor from inside the sandbox if it has any capacity to run
 linters, hooks, or anything else from the project environment. A

{projectwrap-202604.2 → projectwrap-202604.3}/README.md

@@ -35,7 +35,9 @@ _absolutely no warranty_.
 - Protect you from `root`
 
 **Dependencies:** Python 3.11+ (stdlib only, no pip dependencies),
-[bubblewrap](https://github.com/containers/bubblewrap) for sandboxing,
+[bubblewrap](https://github.com/containers/bubblewrap) ≥ 0.4 for sandboxing
+(encrypted volumes need `--unshare-user` / `--uid` support to drop back to
+the real uid inside the sandbox),
 [gocryptfs](https://nuetzlich.net/gocryptfs/) for encrypted volumes.
 
 **Design principles:**
@@ -89,6 +91,8 @@ blacklist = [  # can't be accessed at all from the sandbox
     "~/.aws",
     "~/.ssh",
     "~/projects/",  # hide all other projects
+    # trimmed for brevity — see the generated template (`pwrap --new`) for
+    # the full default blacklist (GCP, Azure, GPG, docker, npm, PyPI, /mnt).
 ]
 whitelist = [  # exceptions to the blacklist
     "~/.kube/myproject",
@@ -146,6 +150,95 @@ set -gx AICHAT_CONFIG_DIR vault/aichat
 
 ```
 
+##### Claude Code in sandbox #####
+
+Claude Code writes state to several paths under `~/` (`~/.claude`,
+`~/.claude.json.lock`, `~/.local/state/claude`, `~/.cache/claude-cli-nodejs`,
+`~/.npm`). Rather than making each of these writable, redirect all of Claude's
+state into the project directory:
+
+```toml
+[env]
+CLAUDE_CONFIG_DIR = "vault/claude"   # or any writable path inside the sandbox
+```
+
+This gives each project its own Claude state (settings, history, MCP logs) —
+no leakage between sandboxed projects. With an `[encrypted]` volume, Claude's
+state is encrypted at rest.
+
+##### Encrypted vault, minimal sandbox rules #####
+
+Minimal sandbox configuration — no custom blacklists or whitelists, no
+`clean_env`. The goal is to keep secrets (kubeconfig, shell history, LLM
+chat logs) encrypted at rest and isolated per project, without locking down
+the rest of the environment.
+
+```toml
+[project]
+name = "myproject"
+dir = "~/projects/myproject"
+shell = "/usr/bin/fish"
+
+[sandbox]
+enabled = true
+
+[encrypted]
+cipherdir = "encrypted"
+mountpoint = "~/projects/myproject/vault"
+
+[env]
+KUBECONFIG = "vault/kubeconfig"
+CLAUDE_CONFIG_DIR = "vault/claude"
+XDG_DATA_HOME = "vault/.config"   # fish history, tool state
+```
+
+`init.fish`:
+```fish
+source .venv/bin/activate.fish
+```
+
+`[sandbox] enabled = true` still applies the security defaults below: home
+is bound read-only, the config dir is blacklisted, the docker socket is
+masked, `/tmp` is a tmpfs, and PID/IPC namespaces are isolated. With no
+custom blacklist/whitelist/writable entries, the only writable paths are
+the project directory and the vault mountpoint — reads from anywhere else
+under home still work, but writes outside those two paths fail. Add entries
+to `writable` to poke rw holes in the read-only home if you need them. The
+encrypted vault holds project-specific secrets and history that disappear
+when the shell exits; `vault/` lives inside the project directory so it's
+writable by default.
+
+##### Maximum isolation #####
+
+Default-deny for both filesystem and environment. Nothing is visible or set
+unless explicitly allowed.
+
+```toml
+[project]
+name = "myproject"
+dir = "~/projects/myproject"
+shell = "/usr/bin/fish"
+
+[sandbox]
+enabled = true
+clean_env = true                  # only PATH/HOME/USER/SHELL/TERM/LANG
+blacklist = [
+    "~",                          # hide all dotfiles and home contents
+    "/mnt",                       # WSL: hide Windows drives
+]
+whitelist = [
+    "~/.config/fish",             # shell config (read-only)
+    "~/.pyenv",                   # python versions (read-only)
+]
+
+[env]
+XDG_DATA_HOME = ".config"        # fish history, tool state → project dir
+```
+
+The project directory is always writable regardless of blacklist. With
+`XDG_DATA_HOME` pointing inside it, fish history and XDG-aware tools write
+their state there instead of the (hidden) home directory.
+
 ##### GUI apps in sandbox #####
 
 To run emacs or other GUI apps inside the sandbox on WSL2:
@@ -192,12 +285,9 @@ with an `[encrypted]` section, pointing at the mountpoint. Use it from init
 scripts or app configs to redirect history/state into the vault without
 hardcoding paths per project.
 
-**You will appear as root.** Mounting gocryptfs unprivileged requires
-`unshare --user --map-root-user`, so `whoami` reports `root` and `id -u`
-reports `0` inside the sandbox. This is a user-namespace remapping only —
-you have no real privileges on the host and cannot escalate. Your files
-remain owned by your real uid. Scripts that gate on `$UID == 0` will
-misbehave; check `$PROJECT_WRAP` or `$PWRAP_VAULT_DIR` instead.
+**If `id -u` reports 0 inside the sandbox**, your bubblewrap is too old —
+run `pwrap --check-deps`. Encrypted vaults need `--unshare-user` / `--uid`
+support (bubblewrap ≥ 0.4) to drop back to your real uid.
 
 **Multiple terminals** (`shared = false`, default): each terminal gets an
 independent gocryptfs mount. Writes to different files merge on next
@@ -218,8 +308,7 @@ and the mount is released.
 pwrap                                      # list projects
 pwrap myproject                            # launch project
 pwrap -v myproject                         # verbose output
-pwrap --new ~/projects/myproject           # create config (name from dir)
-pwrap --new ~/projects/myproject custom    # create with explicit name
+pwrap --new ~/projects/myproject           # create config (name = dir basename)
 pwrap --new --shell /bin/bash ~/projects/x # specify shell
 pwrap --check-deps                         # check optional dependencies
 pwrap --version                            # show version
@@ -231,12 +320,17 @@ When sandboxing is enabled:
 
 - Home is **read-only**; only the project directory is writable
 - Config directory (`~/.config/pwrap`) is always blacklisted
+- Docker socket (`/run/docker.sock`) masked — `connect()` works on
+  ro-bound sockets, so an exposed docker socket is a full escape to root
+- Default template blacklists credential dirs (SSH, GPG, AWS, GCP, Azure,
+  Docker, npm, PyPI) and `/mnt` (WSL Windows drives)
 - PID and IPC namespaces are isolated
 - TIOCSTI injection blocked automatically on kernels < 6.2
-- XDG runtime directory isolated
+- XDG runtime directory isolated (D-Bus, Wayland, keyring sockets)
 - Sandbox dies with parent process
 - Encrypted volumes mount in isolated namespace (invisible on host)
-- All paths in shell commands are quoted to prevent injection
+- Writable paths are auto-created (as directories) if they don't exist;
+  paths that already exist are bound as-is, so a file entry binds that file
 
 Run your editor from inside the sandbox if it has any capacity to run
 linters, hooks, or anything else from the project environment. A

{projectwrap-202604.2 → projectwrap-202604.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "projectwrap"
-version = "202604.2"
+version = "202604.3"
 description = "Isolated project environments with bubblewrap sandboxing"
 readme = "README.md"
 license = "MIT"
@@ -54,4 +54,8 @@ strict = true
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
-addopts = "-v"
+addopts = "-v"
+markers = [
+    "integration: end-to-end tests that exec bwrap/gocryptfs/unshare (opt-in)",
+    "real_probe: tests that exercise the real bwrap feature probe (not stubbed)",
+]

{projectwrap-202604.2 → projectwrap-202604.3}/src/project_wrap/core.py

@@ -118,13 +118,17 @@ def build_bwrap_args(
     uid = os.getuid()
     args.extend(["--tmpfs", f"/run/user/{uid}"])
 
+    # Mask docker socket — connect() works on ro-bound sockets, so this
+    # is a full sandbox escape to root if docker is running
+    args.extend(["--ro-bind-try", "/dev/null", "/run/docker.sock"])
+
     # Always blacklist the config directory (prevents reading other project configs
     # or modifying sandbox rules from inside the sandbox)
     config_dir_resolved = get_config_dir().resolve()
     if config_dir_resolved.exists():
         args.extend(["--tmpfs", str(config_dir_resolved)])
 
-    # Blacklist paths by overlaying with tmpfs
+    # Blacklist paths by overlaying with tmpfs (dirs) or /dev/null (files)
     blacklist_paths: list[Path] = [config_dir_resolved]
     for path in sandbox.get("blacklist", []):
         p = expand_path(path)
@@ -135,7 +139,10 @@ def build_bwrap_args(
             )
         # bwrap can't mount tmpfs over symlinks — resolve to the real path
         mount_path = p.resolve()
-        args.extend(["--tmpfs", str(mount_path)])
+        if mount_path.is_file():
+            args.extend(["--ro-bind", "/dev/null", str(mount_path)])
+        else:
+            args.extend(["--tmpfs", str(mount_path)])
         blacklist_paths.append(mount_path)
 
     # Whitelist paths by binding them back (must be under a blacklisted path)
@@ -156,10 +163,7 @@ def build_bwrap_args(
     for path in sandbox.get("writable", []):
         p = expand_path(path)
         if not p.exists():
-            raise SystemExit(
-                f"Writable path does not exist: {p}\n"
-                f"Fix your config or remove this entry."
-            )
+            p.mkdir(parents=True, exist_ok=True)
         mount_path = p.resolve()
         args.extend(["--bind", str(mount_path), str(mount_path)])
 
@@ -204,6 +208,14 @@ def build_bwrap_args(
     if sandbox.get("unshare_pid", True):
         args.append("--unshare-pid")
 
+    # Clean environment: clear everything, pass through essentials
+    if sandbox.get("clean_env", False):
+        args.append("--clearenv")
+        for var in ("PATH", "HOME", "USER", "SHELL", "TERM", "LANG"):
+            val = os.environ.get(var)
+            if val is not None:
+                args.extend(["--setenv", var, val])
+
     # Set environment variables
     args.extend(["--setenv", "PROJECT_WRAP", "1"])
 

projectwrap-202604.3/src/project_wrap/deps.py

@@ -0,0 +1,159 @@
+"""Dependency checking for optional external tools."""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from enum import Enum
+
+
+class DepStatus(Enum):
+    """Dependency availability status."""
+
+    AVAILABLE = "available"
+    MISSING = "missing"
+    UNSUPPORTED = "unsupported"
+
+
+@dataclass
+class Dependency:
+    """External dependency information."""
+
+    name: str
+    binary: str
+    install_hint: str
+    required_for: str
+    # Optional feature probe: returns (ok, reason). Runs only if the binary
+    # is found on PATH. `reason` is shown to the user on failure.
+    feature_probe: Callable[[str], tuple[bool, str]] | None = field(
+        default=None, repr=False
+    )
+
+    def check(self) -> tuple[DepStatus, str]:
+        """Check if dependency is available and satisfies feature requirements.
+
+        Returns (status, detail). `detail` is empty on success, otherwise a
+        human-readable reason (missing flag, install hint, etc).
+        """
+        path = shutil.which(self.binary)
+        if not path:
+            return DepStatus.MISSING, ""
+        if self.feature_probe is not None:
+            ok, reason = self.feature_probe(path)
+            if not ok:
+                return DepStatus.UNSUPPORTED, reason
+        return DepStatus.AVAILABLE, ""
+
+
+_bwrap_probe_cache: tuple[bool, str] | None = None
+
+
+def _probe_bwrap(path: str) -> tuple[bool, str]:
+    """Check that bwrap supports --unshare-user and --uid.
+
+    These flags are required by the vault path (vault.py:_inject_uid) to
+    drop from the outer user-ns "root" back to the real uid inside the
+    sandbox. Result is cached per-process.
+    """
+    global _bwrap_probe_cache
+    if _bwrap_probe_cache is not None:
+        return _bwrap_probe_cache
+
+    try:
+        result = subprocess.run(
+            [path, "--help"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+    except (OSError, subprocess.TimeoutExpired) as e:
+        _bwrap_probe_cache = (False, f"could not run '{path} --help': {e}")
+        return _bwrap_probe_cache
+
+    help_text = result.stdout + result.stderr
+    missing = [f for f in ("--unshare-user", "--uid") if f not in help_text]
+    if missing:
+        _bwrap_probe_cache = (
+            False,
+            f"bwrap is missing required flags: {', '.join(missing)}. "
+            f"Upgrade bubblewrap (>= 0.4) — encrypted vaults need these to "
+            f"drop back to your real uid inside the sandbox.",
+        )
+        return _bwrap_probe_cache
+
+    _bwrap_probe_cache = (True, "")
+    return _bwrap_probe_cache
+
+
+# Known optional dependencies
+DEPS = {
+    "bwrap": Dependency(
+        name="bubblewrap",
+        binary="bwrap",
+        install_hint="sudo apt install bubblewrap",
+        required_for="sandbox isolation",
+        feature_probe=_probe_bwrap,
+    ),
+    "gocryptfs": Dependency(
+        name="gocryptfs",
+        binary="gocryptfs",
+        install_hint="sudo apt install gocryptfs",
+        required_for="encrypted volumes",
+    ),
+}
+
+
+class MissingDependencyError(Exception):
+    """Raised when a required dependency is not available."""
+
+    def __init__(self, dep: Dependency):
+        self.dep = dep
+        super().__init__(
+            f"{dep.name} is required for {dep.required_for} but is not installed.\n"
+            f"Install with: {dep.install_hint}"
+        )
+
+
+class UnsupportedDependencyError(Exception):
+    """Raised when a dependency is installed but lacks a required feature."""
+
+    def __init__(self, dep: Dependency, reason: str):
+        self.dep = dep
+        self.reason = reason
+        super().__init__(f"{dep.name}: {reason}")
+
+
+def require_dep(name: str) -> None:
+    """Ensure a dependency is available, raise if not."""
+    dep = DEPS.get(name)
+    if dep is None:
+        raise ValueError(f"Unknown dependency: {name}")
+
+    status, detail = dep.check()
+    if status == DepStatus.MISSING:
+        raise MissingDependencyError(dep)
+    if status == DepStatus.UNSUPPORTED:
+        raise UnsupportedDependencyError(dep, detail)
+
+
+def check_optional_deps(verbose: bool = False) -> dict[str, DepStatus]:
+    """Check all optional dependencies and return their status."""
+    results = {}
+
+    for name, dep in DEPS.items():
+        status, detail = dep.check()
+        results[name] = status
+
+        if verbose:
+            icon = "✓" if status == DepStatus.AVAILABLE else "✗"
+            status_text = status.value
+            print(f"  {icon} {dep.name} ({dep.binary}): {status_text}")
+            if status == DepStatus.MISSING:
+                print(f"      Install: {dep.install_hint}")
+                print(f"      Used for: {dep.required_for}")
+            elif status == DepStatus.UNSUPPORTED:
+                print(f"      {detail}")
+
+    return results

projectwrap-202604.3/src/project_wrap/templates/project.toml

@@ -0,0 +1,48 @@
+[project]
+name = "{name}"
+dir = "{dir}"
+shell = "{shell}"
+
+[sandbox]
+enabled = {sandbox_enabled}
+# Note: the config directory (~/.config/pwrap) is always blacklisted automatically.
+blacklist = [                     # Paths to hide (overlaid with tmpfs)
+    "~/.ssh",                     # SSH keys and agent config
+    "~/.gnupg",                   # GPG keys
+    "~/.aws",                     # AWS credentials and config
+    "~/.kube",                    # Kubernetes contexts and tokens
+    "~/.config/gcloud",           # GCP credentials and auth tokens
+    "~/.azure",                   # Azure CLI credentials
+    "~/.docker",                  # Docker config and auth tokens
+    "~/.npmrc",                   # npm auth tokens
+    "~/.pypirc",                  # PyPI upload tokens
+    "~/.boto",                    # Legacy GCS/S3 credentials
+    "/mnt",                       # WSL: Windows drives. Without this, cmd.exe and
+                                  # powershell.exe are callable via binfmt_misc
+                                  # interop — a full sandbox escape.
+]
+# whitelist = [                   # Exceptions to blacklist (bound back read-only)
+#     "~/.kube/{name}",
+#     "/mnt/wsl",                  # WSL config — /etc/resolv.conf symlinks here,
+#                                  # so DNS breaks without it when /mnt is blacklisted.
+#                                  # Add "/mnt/wslg/..." writable for GUI apps.
+# ]
+# writable = [                    # Extra writable paths (home is read-only)
+#     "~/.pyenv/shims",
+# ]
+# unshare_net = false             # Isolate network namespace
+# unshare_pid = true              # Isolate PID namespace (default: true)
+# new_session = true              # TIOCSTI protection (auto on kernels < 6.2)
+# clean_env = false               # Clear env, pass through only PATH/HOME/USER/
+#                                 # SHELL/TERM/LANG. Add others via [env].
+
+# [env]                             # environment variables (set before shell starts)
+# XDG_DATA_HOME = "vault/.config"  # ~ expanded for values starting with ~/
+# AICHAT_CONFIG_DIR = "~/.local/share/aichat"
+
+# [encrypted]                      # gocryptfs encrypted volume (sandbox only)
+# cipherdir = "encrypted"         # Relative to config dir, or absolute
+# mountpoint = "~/.local/share/myapp"  # Where decrypted files appear
+# shared = false                  # true = share one mount across terminals; first
+#                                 # terminal is primary, attached terminals die with it.
+# Inside the sandbox, $PWRAP_VAULT_DIR points at the mountpoint.

{projectwrap-202604.2 → projectwrap-202604.3}/src/project_wrap/validate.py

@@ -88,6 +88,7 @@ _SCHEMA: dict[str, dict[str, type]] = {
         "unshare_net": bool,
         "unshare_pid": bool,
         "new_session": bool,
+        "clean_env": bool,
         "writable": list,
     },
     "encrypted": {"cipherdir": str, "mountpoint": str, "shared": bool},

{projectwrap-202604.2 → projectwrap-202604.3}/src/project_wrap/vault.py

@@ -228,7 +228,10 @@ def _run_single(config: VaultConfig, bwrap_argv: list[str]) -> int:
         return 130
     os.set_inheritable(lock_fd, True)
 
-    bwrap_cmd = " ".join(shlex.quote(a) for a in bwrap_argv)
+    # Capture real uid/gid before entering --map-root-user namespace; inject
+    # into bwrap so the sandbox shell drops back to the real user identity.
+    bwrap_with_uid = _inject_uid(bwrap_argv, os.getuid(), os.getgid())
+    bwrap_cmd = " ".join(shlex.quote(a) for a in bwrap_with_uid)
     inner = (
         f"gocryptfs {shlex.quote(str(config.cipherdir))} "
         f"{shlex.quote(str(config.mountpoint))} && "
@@ -242,6 +245,31 @@ def _run_single(config: VaultConfig, bwrap_argv: list[str]) -> int:
     return 1  # unreachable
 
 
+def _inject_uid(bwrap_argv: list[str], uid: int, gid: int) -> list[str]:
+    """Inject --unshare-user --uid --gid so bwrap drops back to the real uid.
+
+    User-namespace mapping chain for the vault path:
+
+      1. Outer: `unshare --user --map-root-user` maps real uid -> 0 so we can
+         mount gocryptfs (FUSE requires "root" in the user ns).
+      2. gocryptfs mounts; files inside it are owned by uid 0 in the outer ns
+         (= the real uid on the host kernel).
+      3. bwrap creates a nested user ns via `--unshare-user` and writes a
+         uid_map of {outer 0 -> nested REAL_UID}. We can only do this because
+         we are "root" in the outer ns, which can write arbitrary mappings
+         for a child ns.
+      4. Processes inside the sandbox see files owned by REAL_UID and
+         `id -u` / `whoami` report the real user — not root.
+
+    Requires bwrap >= 0.4 with --unshare-user and --uid support; this is
+    verified at startup by deps._probe_bwrap. The end-to-end chain is
+    exercised by tests/test_vault_integration.py.
+    """
+    argv = list(bwrap_argv)
+    argv[1:1] = ["--unshare-user", "--uid", str(uid), "--gid", str(gid)]
+    return argv
+
+
 def _exec_primary_serve(
     config: VaultConfig, bwrap_argv: list[str], lock_fd: int
 ) -> None:
@@ -259,6 +287,8 @@ def _exec_primary_serve(
         "--mountpoint", str(config.mountpoint),
         "--project", config.project_name,
         "--sock-path", str(sock),
+        "--real-uid", str(os.getuid()),
+        "--real-gid", str(os.getgid()),
         "--bwrap-argv", json.dumps(bwrap_argv),
     ]
     os.execvp("unshare", argv)
@@ -325,7 +355,13 @@ def _inject_token(bwrap_argv: list[str], token: str) -> list[str]:
     return argv
 
 
-def serve(config: VaultConfig, sock_path: Path, bwrap_argv: list[str]) -> None:
+def serve(
+    config: VaultConfig,
+    sock_path: Path,
+    bwrap_argv: list[str],
+    real_uid: int,
+    real_gid: int,
+) -> None:
     """Primary session: mount, fork primary bwrap, accept attached clients.
 
     Called via `python -m project_wrap.vault serve ...` after unshare. Runs in
@@ -359,7 +395,7 @@ def serve(config: VaultConfig, sock_path: Path, bwrap_argv: list[str]) -> None:
     signal.signal(signal.SIGHUP, handle_signal)
     signal.signal(signal.SIGCHLD, signal.SIG_DFL)
 
-    primary_argv = _inject_token(bwrap_argv, token)
+    primary_argv = _inject_uid(_inject_token(bwrap_argv, token), real_uid, real_gid)
 
     primary_pid = os.fork()
     if primary_pid == 0:
@@ -452,7 +488,9 @@ def serve(config: VaultConfig, sock_path: Path, bwrap_argv: list[str]) -> None:
                         pass
                 continue
 
-            child_argv = _inject_token(msg["argv"], token)
+            child_argv = _inject_uid(
+                _inject_token(msg["argv"], token), real_uid, real_gid
+            )
 
             proxy_pid = os.fork()
             if proxy_pid == 0:
@@ -546,6 +584,8 @@ def main() -> None:
     parser.add_argument("--mountpoint", required=True)
     parser.add_argument("--project", required=True)
     parser.add_argument("--sock-path", required=True)
+    parser.add_argument("--real-uid", type=int, required=True)
+    parser.add_argument("--real-gid", type=int, required=True)
     parser.add_argument("--bwrap-argv", required=True)
     args = parser.parse_args()
 
@@ -556,7 +596,7 @@ def main() -> None:
         shared=True,
     )
     bwrap_argv = json.loads(args.bwrap_argv)
-    serve(config, Path(args.sock_path), bwrap_argv)
+    serve(config, Path(args.sock_path), bwrap_argv, args.real_uid, args.real_gid)
 
 
 if __name__ == "__main__":

projectwrap-202604.2/src/project_wrap/deps.py

@@ -1,87 +0,0 @@
-"""Dependency checking for optional external tools."""
-
-from __future__ import annotations
-
-import shutil
-from dataclasses import dataclass
-from enum import Enum
-
-
-class DepStatus(Enum):
-    """Dependency availability status."""
-
-    AVAILABLE = "available"
-    MISSING = "missing"
-
-
-@dataclass
-class Dependency:
-    """External dependency information."""
-
-    name: str
-    binary: str
-    install_hint: str
-    required_for: str
-
-    def check(self) -> DepStatus:
-        """Check if dependency is available."""
-        if shutil.which(self.binary):
-            return DepStatus.AVAILABLE
-        return DepStatus.MISSING
-
-
-# Known optional dependencies
-DEPS = {
-    "bwrap": Dependency(
-        name="bubblewrap",
-        binary="bwrap",
-        install_hint="sudo apt install bubblewrap",
-        required_for="sandbox isolation",
-    ),
-    "gocryptfs": Dependency(
-        name="gocryptfs",
-        binary="gocryptfs",
-        install_hint="sudo apt install gocryptfs",
-        required_for="encrypted volumes",
-    ),
-}
-
-
-class MissingDependencyError(Exception):
-    """Raised when a required dependency is not available."""
-
-    def __init__(self, dep: Dependency):
-        self.dep = dep
-        super().__init__(
-            f"{dep.name} is required for {dep.required_for} but is not installed.\n"
-            f"Install with: {dep.install_hint}"
-        )
-
-
-def require_dep(name: str) -> None:
-    """Ensure a dependency is available, raise if not."""
-    dep = DEPS.get(name)
-    if dep is None:
-        raise ValueError(f"Unknown dependency: {name}")
-
-    if dep.check() == DepStatus.MISSING:
-        raise MissingDependencyError(dep)
-
-
-def check_optional_deps(verbose: bool = False) -> dict[str, DepStatus]:
-    """Check all optional dependencies and return their status."""
-    results = {}
-
-    for name, dep in DEPS.items():
-        status = dep.check()
-        results[name] = status
-
-        if verbose:
-            icon = "✓" if status == DepStatus.AVAILABLE else "✗"
-            status_text = "available" if status == DepStatus.AVAILABLE else "missing"
-            print(f"  {icon} {dep.name} ({dep.binary}): {status_text}")
-            if status == DepStatus.MISSING:
-                print(f"      Install: {dep.install_hint}")
-                print(f"      Used for: {dep.required_for}")
-
-    return results

projectwrap-202604.2/src/project_wrap/templates/project.toml

@@ -1,36 +0,0 @@
-[project]
-name = "{name}"
-dir = "{dir}"
-shell = "{shell}"
-
-[sandbox]
-enabled = {sandbox_enabled}
-# Note: the config directory (~/.config/pwrap) is always blacklisted automatically.
-# blacklist = [                   # Additional paths to hide (overlaid with tmpfs)
-#     "~/.kube",
-#     "~/.aws",
-#     "~/.ssh",
-# ]
-# whitelist = [                   # Exceptions to blacklist (bound back)
-#     "~/.kube/{name}",
-# ]
-# writable = [                    # Extra writable paths (home is read-only)
-#     "~/.pyenv/shims",
-# ]
-# unshare_net = false             # Isolate network namespace
-# unshare_pid = true              # Isolate PID namespace (default: true)
-# new_session = true              # TIOCSTI protection (auto on kernels < 6.2)
-
-# [env]                             # environment variables (set before shell starts)
-# XDG_DATA_HOME = "vault/.config"  # ~ expanded for values starting with ~/
-# AICHAT_CONFIG_DIR = "~/.local/share/aichat"
-
-# [encrypted]                      # gocryptfs encrypted volume (sandbox only)
-# cipherdir = "encrypted"         # Relative to config dir, or absolute
-# mountpoint = "~/.local/share/myapp"  # Where decrypted files appear
-# shared = false                  # true = share one mount across terminals; first
-#                                 # terminal is primary, attached terminals die with it.
-# Inside the sandbox, $PWRAP_VAULT_DIR points at the mountpoint.
-# Note: encrypted volumes require unshare --user --map-root-user, so
-# `whoami` / `id -u` will report root inside the sandbox (user namespace only,
-# not real root).