projectwrap 202604.1__py3-none-any.whl

project_wrap/__init__.py

@@ -0,0 +1,3 @@
+"""project-wrap: Isolated project environments with bubblewrap sandboxing."""
+
+__version__ = "202604.1"

project_wrap/cli.py

@@ -0,0 +1,115 @@
+"""CLI entry point for project-wrap."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from . import __version__
+from .core import (
+    create_project,
+    ensure_templates,
+    get_config_dir,
+    list_projects,
+    run_project,
+)
+from .deps import check_optional_deps
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Main entry point."""
+    parser = argparse.ArgumentParser(
+        prog="pwrap",
+        description="Isolated project environments with bubblewrap sandboxing",
+    )
+    parser.add_argument(
+        "project",
+        nargs="?",
+        help="Project name to load",
+    )
+    parser.add_argument(
+        "--new",
+        metavar="DIR",
+        help="Create a new project config with DIR as the project directory",
+    )
+    parser.add_argument(
+        "--no-sandbox",
+        action="store_true",
+        help="Disable sandbox in generated config (use with --new)",
+    )
+    parser.add_argument(
+        "--shell",
+        metavar="SHELL",
+        help="Shell to configure (use with --new, defaults to $SHELL)",
+    )
+    parser.add_argument(
+        "-l",
+        "--list",
+        action="store_true",
+        help="List available projects",
+    )
+    parser.add_argument(
+        "--check-deps",
+        action="store_true",
+        help="Check availability of optional dependencies",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+    parser.add_argument(
+        "-v",
+        "--verbose",
+        action="store_true",
+        help="Verbose output",
+    )
+
+    args = parser.parse_args(argv)
+
+    try:
+        if args.check_deps:
+            check_optional_deps(verbose=True)
+            return 0
+
+        if args.new:
+            if ensure_templates():
+                config_dir = get_config_dir()
+                print("Templates created:")
+                for name in ["project.tpl.toml", "init.tpl.fish", "init.tpl.sh"]:
+                    print(f"  {config_dir / name}")
+                print("Edit these templates, then run pwrap --new again.")
+                return 0
+
+            print(f"Using template {get_config_dir() / 'project.tpl.toml'}")
+            config_path = create_project(
+                args.new,
+                name=args.project or None,
+                sandbox=not args.no_sandbox,
+                shell=args.shell,
+            )
+            print(f"Created {config_path}")
+            return 0
+
+        if args.list or not args.project:
+            list_projects()
+            return 0
+
+        run_project(args.project, verbose=args.verbose)
+        return 0  # Won't reach here if exec succeeds
+
+    except KeyboardInterrupt:
+        print("\nAborted.")
+        return 130
+    except SystemExit as e:
+        if isinstance(e.code, int):
+            return e.code
+        print(f"Error: {e.code}", file=sys.stderr)
+        return 1
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

project_wrap/core.py

@@ -0,0 +1,566 @@
+"""Core functionality for project-wrap."""
+
+from __future__ import annotations
+
+import os
+import shlex
+import subprocess
+import sys
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from .deps import require_dep
+from .validate import (
+    check_config_permissions,
+    tiocsti_vulnerable,
+    validate_config,
+    validate_project_name,
+    validate_shell,
+)
+from .vault import VaultConfig
+
+
+@dataclass
+class ProjectExec:
+    """Everything needed to exec into a project environment."""
+
+    display_name: str
+    program: str
+    argv: list[str]
+    is_sandboxed: bool = False
+    verbose_info: str | None = None
+    vault_config: VaultConfig | None = None
+
+
+def get_config_dir() -> Path:
+    """Get the project configuration directory."""
+    # Support XDG, fall back to ~/.config
+    xdg_config = os.environ.get("XDG_CONFIG_HOME")
+    if xdg_config:
+        base = Path(xdg_config)
+    else:
+        base = Path.home() / ".config"
+    return base / "pwrap"
+
+
+def expand_path(path: str) -> Path:
+    """Expand ~ and environment variables in path."""
+    return Path(os.path.expandvars(os.path.expanduser(path)))
+
+
+
+def load_config(name: str) -> dict[str, Any]:
+    """Load project configuration."""
+    validate_project_name(name)
+    config_dir = get_config_dir()
+    project_path = config_dir / name
+
+    if not project_path.is_dir():
+        raise SystemExit(f"Unknown project: {name}")
+
+    config_file = project_path / "project.toml"
+    if not config_file.exists():
+        raise SystemExit(f"Missing config: {config_file}")
+
+    check_config_permissions(config_file)
+
+    with open(config_file, "rb") as f:
+        config: dict[str, Any] = tomllib.load(f)
+
+    validate_config(config)
+    config["_config_dir"] = project_path
+    return config
+
+
+
+def build_bwrap_args(
+    sandbox: dict[str, Any],
+    project_dir: Path,
+    init_script: Path | None = None,
+    ro_bind_extra: list[Path] | None = None,
+    rw_bind_extra: list[Path] | None = None,
+) -> list[str]:
+    """Build bubblewrap command arguments.
+
+    Args:
+        sandbox: Sandbox configuration dict
+        project_dir: Project working directory
+        init_script: Optional init script to bind-mount read-only into sandbox
+        ro_bind_extra: Additional paths to bind-mount read-only
+        rw_bind_extra: Additional paths to bind-mount read-write (e.g. encrypted mountpoint)
+
+    Returns:
+        List of bwrap arguments
+    """
+    args = [
+        "bwrap",
+        # Base filesystem (read-only root, read-only home, writable project dir)
+        "--ro-bind",
+        "/",
+        "/",
+        "--dev",
+        "/dev",
+        "--proc",
+        "/proc",
+        "--tmpfs",
+        "/tmp",
+        "--ro-bind",
+        str(Path.home()),
+        str(Path.home()),
+        # Hardening
+        "--die-with-parent",
+        "--unshare-ipc",
+    ]
+
+    # Isolate XDG runtime dir (D-Bus, Wayland, SSH/GPG agent sockets)
+    uid = os.getuid()
+    args.extend(["--tmpfs", f"/run/user/{uid}"])
+
+    # 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: list[Path] = [config_dir_resolved]
+    for path in sandbox.get("blacklist", []):
+        p = expand_path(path)
+        if not p.exists():
+            raise SystemExit(
+                f"Blacklist path does not exist: {p}\n"
+                f"Fix your config or remove this entry."
+            )
+        # bwrap can't mount tmpfs over symlinks — resolve to the real path
+        mount_path = p.resolve()
+        args.extend(["--tmpfs", str(mount_path)])
+        blacklist_paths.append(mount_path)
+
+    # Whitelist paths by binding them back (must be under a blacklisted path)
+    for path in sandbox.get("whitelist", []):
+        p = expand_path(path)
+        if not p.exists():
+            continue
+        # Resolve once to prevent symlink TOCTOU
+        resolved = p.resolve()
+        if not any(resolved == bl or bl in resolved.parents for bl in blacklist_paths):
+            raise SystemExit(
+                f"Whitelist path {p} is not under any blacklisted path. "
+                f"Blacklisted: {[str(bl) for bl in blacklist_paths]}"
+            )
+        args.extend(["--bind", str(resolved), str(resolved)])
+
+    # Extra writable paths (e.g. ~/.pyenv/shims, ~/.keychain)
+    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."
+            )
+        mount_path = p.resolve()
+        args.extend(["--bind", str(mount_path), str(mount_path)])
+
+    # Project dir writable (after blacklist/whitelist so it's not overwritten)
+    args.extend(["--bind", str(project_dir), str(project_dir)])
+
+    # Bind-mount init script read-only (config dir may be blacklisted)
+    if init_script is not None:
+        args.extend(["--ro-bind", str(init_script), str(init_script)])
+
+    # Bind-mount extra read-only paths (e.g. secrets identity file)
+    for path in ro_bind_extra or []:
+        args.extend(["--ro-bind", str(path), str(path)])
+
+    # Bind-mount extra read-write paths (e.g. writeback archive)
+    for path in rw_bind_extra or []:
+        args.extend(["--bind", str(path), str(path)])
+
+    # TIOCSTI protection (--new-session breaks fish TTY, so only enable when needed)
+    vulnerable = tiocsti_vulnerable()
+    new_session_cfg = sandbox.get("new_session")
+    if new_session_cfg is True:
+        args.append("--new-session")
+    elif new_session_cfg is None and vulnerable:
+        # Default: auto-enable on vulnerable kernels
+        args.append("--new-session")
+    elif new_session_cfg is False and vulnerable:
+        import sys
+
+        print(
+            "Warning: new_session disabled but kernel is vulnerable to TIOCSTI "
+            f"(Linux {os.uname().release}). Upgrade to 6.2+ or set "
+            "new_session = true.",
+            file=sys.stderr,
+        )
+
+    # Network isolation
+    if sandbox.get("unshare_net", False):
+        args.append("--unshare-net")
+
+    # PID namespace isolation (default: on)
+    if sandbox.get("unshare_pid", True):
+        args.append("--unshare-pid")
+
+    # Set environment variables
+    args.extend(["--setenv", "PROJECT_WRAP", "1"])
+
+    # Set working directory
+    args.extend(["--chdir", str(project_dir)])
+
+    return args
+
+
+def get_init_script(config_dir: Path, shell: str) -> Path | None:
+    """Find shell-specific init script.
+
+    Looks for init.{shell} (e.g., init.fish) then falls back to init.sh.
+    """
+    shell_name = Path(shell).name
+
+    candidates = [
+        config_dir / f"init.{shell_name}",
+        config_dir / "init.sh",
+    ]
+
+    for candidate in candidates:
+        if candidate.exists():
+            return candidate
+
+    return None
+
+
+def _build_init_commands(
+    project_dir: Path,
+    config_dir: Path,
+    shell: str,
+) -> list[str]:
+    """Build setup commands (cd, init script sourcing).
+
+    Returns list of shell commands — does NOT include the final exec/shell launch.
+    """
+    commands: list[str] = []
+
+    commands.append(f"cd {shlex.quote(str(project_dir))}")
+
+    # Custom init script
+    if init_script := get_init_script(config_dir, shell):
+        commands.append(f"source {shlex.quote(str(init_script))}")
+
+    return commands
+
+
+def build_shell_argv(
+    project_dir: Path,
+    config_dir: Path,
+    shell: str,
+) -> list[str]:
+    """Build the full argv to launch an interactive shell with project setup.
+
+    Uses shell-specific mechanisms so setup runs inside the interactive shell:
+    - fish: --init-command (runs after config.fish, before prompt)
+    - other shells: -c "setup; exec shell"
+    """
+    commands = _build_init_commands(project_dir, config_dir, shell)
+    shell_name = Path(shell).name
+
+    if shell_name == "fish":
+        return [shell, "--init-command", "; ".join(commands)]
+
+    commands.append(f"exec {shlex.quote(shell)}")
+    return [shell, "-c", "; ".join(commands)]
+
+
+def redact_bwrap_args(args: list[str]) -> list[str]:
+    """Redact --setenv values from bwrap args for display."""
+    redacted = list(args)
+    i = 0
+    while i < len(redacted):
+        if redacted[i] == "--setenv" and i + 2 < len(redacted):
+            redacted[i + 2] = "***"
+            i += 3
+        else:
+            i += 1
+    return redacted
+
+
+def rename_tmux_window(name: str) -> None:
+    """Rename current tmux window if in tmux session."""
+    if os.environ.get("TMUX"):
+        subprocess.run(
+            ["tmux", "rename-window", name],
+            capture_output=True,
+        )
+
+
+def prepare_project(name: str, verbose: bool = False) -> ProjectExec:
+    """Prepare a project environment for execution.
+
+    Loads config, renames tmux window, and returns everything needed
+    to exec into the project shell.
+    """
+    config = load_config(name)
+
+    # Extract config sections
+    project_cfg = config.get("project", {})
+    sandbox_cfg = config.get("sandbox", {})
+    encrypted_cfg = config.get("encrypted", {})
+    config_dir: Path = config["_config_dir"]
+
+    # Resolve settings
+    display_name = project_cfg.get("name", name)
+    project_dir = expand_path(project_cfg.get("dir", f"~/projects/{name}"))
+    shell = project_cfg.get("shell", os.environ.get("SHELL", "/bin/bash"))
+    validate_shell(shell)
+    sandbox_enabled = sandbox_cfg.get("enabled", False)
+
+    # Verify project directory exists
+    if not project_dir.exists():
+        raise SystemExit(f"Project directory does not exist: {project_dir}")
+
+    # Encrypted volumes require sandbox
+    if encrypted_cfg and not sandbox_enabled:
+        raise SystemExit(
+            "[encrypted] requires sandbox to be enabled"
+        )
+
+    # Resolve encrypted volume config
+    vault_config: VaultConfig | None = None
+    if encrypted_cfg:
+        require_dep("gocryptfs")
+
+        cipherdir_raw = encrypted_cfg["cipherdir"]
+        cipherdir_path = expand_path(cipherdir_raw)
+        if not cipherdir_path.is_absolute():
+            cipherdir_path = config_dir / cipherdir_raw
+        cipherdir = cipherdir_path.resolve()
+
+        if not cipherdir.is_dir():
+            raise SystemExit(
+                f"Encrypted cipherdir does not exist: {cipherdir}\n"
+                f"Initialize it with: mkdir -p '{cipherdir}' && "
+                f"gocryptfs -init '{cipherdir}'"
+            )
+
+        mountpoint = expand_path(encrypted_cfg["mountpoint"])
+        mountpoint.mkdir(parents=True, exist_ok=True)
+
+        vault_config = VaultConfig(
+            cipherdir=cipherdir,
+            mountpoint=mountpoint.resolve(),
+            project_name=name,
+            shared=encrypted_cfg.get("shared", False),
+        )
+
+    # Rename tmux window
+    rename_tmux_window(display_name)
+
+    # Resolve init script and build shell argv
+    init_script = get_init_script(config_dir, shell)
+    shell_argv = build_shell_argv(project_dir, config_dir, shell)
+
+    # Non-sandboxed execution
+    if not sandbox_enabled:
+        return ProjectExec(
+            display_name=display_name,
+            program=shell,
+            argv=shell_argv,
+        )
+
+    # Sandboxed execution - verify bwrap is available
+    require_dep("bwrap")
+
+    # If encrypted volume, bind the mountpoint into the sandbox
+    rw_bind_extra: list[Path] = []
+    if vault_config:
+        rw_bind_extra = [vault_config.mountpoint]
+
+    bwrap_args = build_bwrap_args(
+        sandbox_cfg, project_dir,
+        init_script=init_script, rw_bind_extra=rw_bind_extra,
+    )
+    if vault_config:
+        bwrap_args.extend(["--setenv", "PWRAP_VAULT_DIR", str(vault_config.mountpoint)])
+    bwrap_args.extend(shell_argv)
+
+    verbose_info = None
+    if verbose:
+        verbose_info = f"Exec: {' '.join(redact_bwrap_args(bwrap_args))}"
+
+    return ProjectExec(
+        display_name=display_name,
+        program="bwrap",
+        argv=bwrap_args,
+        is_sandboxed=True,
+        verbose_info=verbose_info,
+        vault_config=vault_config,
+    )
+
+
+def run_project(name: str, verbose: bool = False) -> None:
+    """Load and run a project environment.
+
+    This function does not return on success (execs into new shell).
+    """
+    from .vault import run_vault
+
+    result = prepare_project(name, verbose)
+
+    label = result.display_name
+    if result.is_sandboxed:
+        label += " (sandboxed)"
+        if result.vault_config is not None:
+            if result.vault_config.shared:
+                label += " (shared vault)"
+            else:
+                label += " (vault)"
+    print(f"Loading {label}")
+
+    if result.verbose_info:
+        print(result.verbose_info)
+
+    if result.vault_config:
+        sys.exit(run_vault(result.vault_config, result.argv))
+    else:
+        os.execvp(result.program, result.argv)
+
+
+
+TEMPLATE_NAMES = ["project.tpl.toml", "init.tpl.fish", "init.tpl.sh"]
+
+
+def _load_package_template(name: str) -> str:
+    """Load a template file from the package templates directory."""
+    from importlib.resources import files
+
+    # Package templates use plain names (project.toml), user templates use .tpl. names
+    return (files("project_wrap") / "templates" / name).read_text()
+
+
+def ensure_templates() -> bool:
+    """Ensure user-editable templates exist in the config directory.
+
+    On first run, copies package templates to ~/.config/pwrap/ with .tpl. names.
+    Returns True if templates were just created (caller should pause for editing).
+    """
+    config_dir = get_config_dir()
+    marker = config_dir / "project.tpl.toml"
+
+    if marker.exists():
+        return False
+
+    config_dir.mkdir(parents=True, exist_ok=True)
+
+    # Map .tpl. names to package template names
+    pkg_names = {"project.tpl.toml": "project.toml", "init.tpl.fish": "init.fish",
+                 "init.tpl.sh": "init.sh"}
+    for tpl_name, pkg_name in pkg_names.items():
+        (config_dir / tpl_name).write_text(_load_package_template(pkg_name))
+
+    return True
+
+
+def _load_template(name: str) -> str:
+    """Load a template, preferring user-editable version over package default.
+
+    Maps template names: project.toml -> project.tpl.toml, init.fish -> init.tpl.fish
+    """
+    tpl_name = name.replace(".", ".tpl.", 1)  # project.toml -> project.tpl.toml
+    user_tpl = get_config_dir() / tpl_name
+    if user_tpl.exists():
+        return user_tpl.read_text()
+    return _load_package_template(name)
+
+
+def create_project(
+    project_dir: str,
+    name: str | None = None,
+    sandbox: bool = True,
+    shell: str | None = None,
+) -> Path:
+    """Create a new project config directory with templates.
+
+    Args:
+        project_dir: Path to the project working directory.
+        name: Project name. Defaults to the directory basename.
+        sandbox: Whether to enable sandbox in the generated config.
+        shell: Shell path. Defaults to $SHELL.
+
+    Returns the path to the created config directory.
+    """
+    resolved_dir = expand_path(project_dir).resolve()
+    if not resolved_dir.is_dir():
+        raise SystemExit(f"Project directory does not exist: {resolved_dir}")
+
+    if name is None:
+        name = resolved_dir.name
+
+    if shell is None:
+        shell = os.environ.get("SHELL", "/bin/bash")
+
+    validate_project_name(name)
+    config_dir = get_config_dir() / name
+
+    if config_dir.exists():
+        raise SystemExit(f"Project already exists: {config_dir}")
+
+    sandbox_enabled = "true" if sandbox else "false"
+
+    toml = _load_template("project.toml").format(
+        name=name, dir=resolved_dir, sandbox_enabled=sandbox_enabled, shell=shell
+    )
+
+    config_dir.mkdir(parents=True)
+    (config_dir / "project.toml").write_text(toml)
+
+    # Copy matching init template
+    shell_name = Path(shell).name
+    if shell_name == "fish":
+        (config_dir / "init.fish").write_text(_load_template("init.fish"))
+    else:
+        (config_dir / "init.sh").write_text(_load_template("init.sh"))
+
+    return config_dir
+
+
+def list_projects() -> None:
+    """List all available projects."""
+    config_dir = get_config_dir()
+
+    if not config_dir.exists():
+        print(f"No projects configured. Create configs in: {config_dir}")
+        return
+
+    print("Projects:")
+
+    items = sorted(config_dir.iterdir())
+    if not items:
+        print("  (none)")
+        return
+
+    for item in items:
+        if item.name.startswith("."):
+            continue
+
+        if item.is_dir():
+            # Check for valid config
+            config_file = item / "project.toml"
+            if config_file.exists():
+                # Try to load to show name
+                try:
+                    with open(config_file, "rb") as f:
+                        cfg = tomllib.load(f)
+                    display_name = cfg.get("project", {}).get("name", item.name)
+                    sandboxed = cfg.get("sandbox", {}).get("enabled", False)
+                    marker = " [sandboxed]" if sandboxed else ""
+                    print(f"  {item.name}/{marker}")
+                    if display_name != item.name:
+                        print(f"      → {display_name}")
+                except Exception:
+                    print(f"  {item.name}/ (invalid config)")
+            else:
+                print(f"  {item.name}/ (missing project.toml)")
+
+