centralize sandbox config, add new type selector for sandbox type

Author: leafo

README.md

@@ -26,15 +26,27 @@ Built for the [itch.io app](https://itch.io/itch) to launch game binaries, smaug
 
 ### Linux
 
-Three sandbox backends are supported. `GetRunner()` selects one automatically when `Sandbox` is enabled:
+Three sandbox backends are supported when `Sandbox` is enabled.
+Shared sandbox settings are configured through `RunnerParams.SandboxConfig`:
+- `Type`: explicit backend (`"bubblewrap"`, `"firejail"`, `"flatpak"`) or auto (`""`)
+- `NoNetwork`: disable network access for the selected backend
+- `AllowEnv`: additional environment variable names to pass through from the host
 
-1. **Flatpak-spawn** — chosen when running inside a [Flatpak](https://flatpak.org/) environment (detected by the presence of `/.flatpak-info`). Uses `flatpak-spawn --sandbox` to create a sub-sandbox within the Flatpak container. Supports environment variable forwarding (`--env`), working directory (`--directory`), and optional network isolation (`--no-network`). The `--watch-bus` flag ties the sandboxed process lifetime to the caller's session bus.
+Sandbox backends:
 
-2. **Bubblewrap** — chosen when `BubblewrapParams.BinaryPath` is set (and not inside a Flatpak). Uses [bubblewrap](https://github.com/containers/bubblewrap) to create a lightweight user-namespace sandbox. Mounts system directories read-only, bind-mounts the game's install folder read-write, and forwards display/audio sockets (X11, Wayland, PulseAudio, PipeWire). Namespace isolation covers user, PID, and UTS; IPC stays shared for X11 MIT-SHM compatibility. Network access is shared by default, with optional isolation via `BubblewrapParams.NoNetwork`.
+1. **Flatpak-spawn** — uses `flatpak-spawn --sandbox` to create a sub-sandbox within the Flatpak container. Supports environment variable forwarding (`--env`), working directory (`--directory`), and optional network isolation via `SandboxConfig.NoNetwork` (`--no-network`). The `--watch-bus` flag ties the sandboxed process lifetime to the caller's session bus.
 
-3. **Firejail** — the fallback when neither of the above apply. Uses [firejail](https://firejail.wordpress.com/) with a generated profile at `{InstallFolder}/.itch/isolate-app.profile` that blacklists sensitive directories and whitelists the game's install folder and temp directory. Environment forwarding follows the same allowlist baseline as bubblewrap (including itch launch vars and temp vars), and network access can be disabled with `FirejailParams.NoNetwork`. Per-game local overrides can be placed in `/etc/firejail/` (e.g. `itch_game_{name}.local`), and a global override file `itch_games_globals.local` is also included if present.
+2. **Bubblewrap** — uses [bubblewrap](https://github.com/containers/bubblewrap) to create a lightweight user-namespace sandbox. Mounts system directories read-only, bind-mounts the game's install folder read-write, and forwards display/audio sockets (X11, Wayland, PulseAudio, PipeWire). Namespace isolation covers user, PID, and UTS; IPC stays shared for X11 MIT-SHM compatibility. Network access is shared by default, with optional isolation via `SandboxConfig.NoNetwork`.
 
-Selection priority: **Flatpak-spawn > Bubblewrap > Firejail**.
+3. **Firejail** — uses [firejail](https://firejail.wordpress.com/) with a generated profile at `{InstallFolder}/.itch/isolate-app.profile` that blacklists sensitive directories and whitelists the game's install folder and temp directory. Environment forwarding follows the same allowlist baseline as bubblewrap (including itch launch vars and temp vars), supports additional passthrough via `SandboxConfig.AllowEnv`, and network access can be disabled with `SandboxConfig.NoNetwork`. Per-game local overrides can be placed in `/etc/firejail/` (e.g. `itch_game_{name}.local`), and a global override file `itch_games_globals.local` is also included if present.
+
+Backend selection:
+- Explicit selection: set `SandboxConfig.Type` to `"flatpak"`, `"bubblewrap"`, or `"firejail"`.
+- Auto selection: leave `SandboxConfig.Type` empty (`""`).
+- Linux auto priority: **Flatpak-spawn > Bubblewrap > Firejail**.
+- Linux auto rule: choose Flatpak-spawn when running inside a [Flatpak](https://flatpak.org/) environment (`/.flatpak-info` present).
+- Linux auto rule: choose Bubblewrap when `BubblewrapParams.BinaryPath` is configured.
+- Linux auto rule: choose Firejail otherwise.
 
 ### macOS
 

runner/bubblewrap_linux.go

@@ -180,7 +180,7 @@ func (br *bubblewrapRunner) Run() error {
 	// - keep IPC shared for X11 MIT-SHM compatibility
 	// - optionally isolate network when NoNetwork is requested
 	args = append(args, "--unshare-user")
-	if params.BubblewrapParams.NoNetwork {
+	if params.SandboxConfig.NoNetwork {
 		args = append(args, "--unshare-net")
 	}
 	args = append(args, "--unshare-pid")
@@ -195,7 +195,14 @@ func (br *bubblewrapRunner) Run() error {
 
 	// Environment passthrough
 	for _, key := range SandboxEnvAllowlist() {
-		if val := envLookup(params.Env, key); val != "" {
+		if val, found := envLookupWithPresence(params.Env, key); found {
+			args = append(args, "--setenv", key, val)
+		} else if val := os.Getenv(key); val != "" {
+			args = append(args, "--setenv", key, val)
+		}
+	}
+	for _, key := range params.SandboxConfig.AllowEnv {
+		if val, found := envLookupWithPresence(params.Env, key); found {
 			args = append(args, "--setenv", key, val)
 		} else if val := os.Getenv(key); val != "" {
 			args = append(args, "--setenv", key, val)
@@ -241,17 +248,6 @@ func (br *bubblewrapRunner) Run() error {
 	return nil
 }
 
-// envLookup looks up a key in a []string{"KEY=VALUE", ...} slice.
-func envLookup(env []string, key string) string {
-	prefix := key + "="
-	for _, e := range env {
-		if strings.HasPrefix(e, prefix) {
-			return e[len(prefix):]
-		}
-	}
-	return ""
-}
-
 func ensureSandboxParentDirs(args *[]string, seen map[string]struct{}, path string) {
 	cleanPath := filepath.Clean(path)
 	if cleanPath == "" || cleanPath == "." || !filepath.IsAbs(cleanPath) {

runner/bubblewrap_linux_test.go

@@ -12,6 +12,16 @@ import (
 	"github.com/stretchr/testify/require"
 )
 
+func bubblewrapSetenvValues(args []string, key string) []string {
+	out := make([]string, 0, 1)
+	for i := 0; i+2 < len(args); i++ {
+		if args[i] == "--setenv" && args[i+1] == key {
+			out = append(out, args[i+2])
+		}
+	}
+	return out
+}
+
 func TestEnsureSandboxParentDirs(t *testing.T) {
 	var args []string
 	seen := make(map[string]struct{})
@@ -102,8 +112,8 @@ func TestBubblewrapNoNetworkAddsUnshareNet(t *testing.T) {
 			Ctx:      context.Background(),
 			BubblewrapParams: BubblewrapParams{
 				BinaryPath: "/fake/bwrap",
-				NoNetwork:  true,
 			},
+			SandboxConfig:  SandboxConfig{NoNetwork: true},
 			FullTargetPath: "/bin/true",
 		},
 	}
@@ -131,7 +141,6 @@ func TestBubblewrapNoNetworkDisabledOmitsUnshareNet(t *testing.T) {
 			Ctx:      context.Background(),
 			BubblewrapParams: BubblewrapParams{
 				BinaryPath: "/fake/bwrap",
-				NoNetwork:  false,
 			},
 			FullTargetPath: "/bin/true",
 		},
@@ -140,3 +149,66 @@ func TestBubblewrapNoNetworkDisabledOmitsUnshareNet(t *testing.T) {
 	require.NoError(t, br.Run())
 	assert.NotContains(t, gotArgs, "--unshare-net")
 }
+
+func TestBubblewrapAllowlistEnvEmptyValueOverridesHost(t *testing.T) {
+	origCommand := bubblewrapCommand
+	t.Cleanup(func() {
+		bubblewrapCommand = origCommand
+	})
+
+	var gotArgs []string
+	bubblewrapCommand = func(name string, args ...string) *exec.Cmd {
+		gotArgs = append([]string{}, args...)
+		return exec.Command("sh", "-c", "true")
+	}
+
+	t.Setenv("LANG", "host-lang")
+
+	br := &bubblewrapRunner{
+		params: RunnerParams{
+			Consumer: &state.Consumer{OnMessage: func(string, string) {}},
+			Ctx:      context.Background(),
+			BubblewrapParams: BubblewrapParams{
+				BinaryPath: "/fake/bwrap",
+			},
+			Env:            []string{"LANG="},
+			FullTargetPath: "/bin/true",
+		},
+	}
+
+	require.NoError(t, br.Run())
+	assert.Equal(t, []string{""}, bubblewrapSetenvValues(gotArgs, "LANG"))
+}
+
+func TestBubblewrapAllowEnvEmptyValueOverridesHost(t *testing.T) {
+	origCommand := bubblewrapCommand
+	t.Cleanup(func() {
+		bubblewrapCommand = origCommand
+	})
+
+	var gotArgs []string
+	bubblewrapCommand = func(name string, args ...string) *exec.Cmd {
+		gotArgs = append([]string{}, args...)
+		return exec.Command("sh", "-c", "true")
+	}
+
+	t.Setenv("SMAUG_ALLOW_ENV_EMPTY", "host")
+
+	br := &bubblewrapRunner{
+		params: RunnerParams{
+			Consumer: &state.Consumer{OnMessage: func(string, string) {}},
+			Ctx:      context.Background(),
+			BubblewrapParams: BubblewrapParams{
+				BinaryPath: "/fake/bwrap",
+			},
+			Env: []string{"SMAUG_ALLOW_ENV_EMPTY="},
+			SandboxConfig: SandboxConfig{
+				AllowEnv: []string{"SMAUG_ALLOW_ENV_EMPTY"},
+			},
+			FullTargetPath: "/bin/true",
+		},
+	}
+
+	require.NoError(t, br.Run())
+	assert.Equal(t, []string{""}, bubblewrapSetenvValues(gotArgs, "SMAUG_ALLOW_ENV_EMPTY"))
+}

runner/env_allowlist_linux.go

@@ -2,6 +2,8 @@
 
 package runner
 
+import "strings"
+
 // BaseSandboxEnvVars are platform/session vars required by sandboxed games.
 var BaseSandboxEnvVars = []string{
 	"DISPLAY",
@@ -26,17 +28,36 @@ func SandboxEnvAllowlist() []string {
 	return allowlist
 }
 
-func collectAllowedEnv(paramsEnv []string, hostEnv []string) []string {
+func collectAllowedEnv(paramsEnv []string, hostEnv []string, extraKeys []string) []string {
 	allowlist := SandboxEnvAllowlist()
+	allowlist = append(allowlist, extraKeys...)
 	out := make([]string, 0, len(allowlist))
 	for _, key := range allowlist {
-		if val := envLookup(paramsEnv, key); val != "" {
+		if val, found := envLookupWithPresence(paramsEnv, key); found {
 			out = append(out, key+"="+val)
 			continue
 		}
-		if val := envLookup(hostEnv, key); val != "" {
+		if val, found := envLookupWithPresence(hostEnv, key); found {
 			out = append(out, key+"="+val)
 		}
 	}
 	return out
 }
+
+// envLookup looks up a key in a []string{"KEY=VALUE", ...} slice.
+func envLookup(env []string, key string) string {
+	val, _ := envLookupWithPresence(env, key)
+	return val
+}
+
+// envLookupWithPresence returns the value for KEY and whether KEY was present.
+// Presence is true even when KEY is explicitly set to an empty value ("KEY=").
+func envLookupWithPresence(env []string, key string) (string, bool) {
+	prefix := key + "="
+	for _, e := range env {
+		if strings.HasPrefix(e, prefix) {
+			return e[len(prefix):], true
+		}
+	}
+	return "", false
+}

runner/env_allowlist_linux_test.go

@@ -0,0 +1,41 @@
+//go:build linux
+
+package runner
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestCollectAllowedEnvParamsEmptyOverridesHostBaseKey(t *testing.T) {
+	got := collectAllowedEnv(
+		[]string{"LANG="},
+		[]string{"LANG=host-lang"},
+		nil,
+	)
+
+	assert.Contains(t, got, "LANG=")
+	assert.NotContains(t, got, "LANG=host-lang")
+}
+
+func TestCollectAllowedEnvParamsEmptyOverridesHostExtraKey(t *testing.T) {
+	got := collectAllowedEnv(
+		[]string{"SMAUG_EXTRA_ENV="},
+		[]string{"SMAUG_EXTRA_ENV=host"},
+		[]string{"SMAUG_EXTRA_ENV"},
+	)
+
+	assert.Contains(t, got, "SMAUG_EXTRA_ENV=")
+	assert.NotContains(t, got, "SMAUG_EXTRA_ENV=host")
+}
+
+func TestCollectAllowedEnvExtraKeyFallsBackToHost(t *testing.T) {
+	got := collectAllowedEnv(
+		nil,
+		[]string{"SMAUG_EXTRA_ENV=host"},
+		[]string{"SMAUG_EXTRA_ENV"},
+	)
+
+	assert.Contains(t, got, "SMAUG_EXTRA_ENV=host")
+}

runner/firejail_linux.go

@@ -68,7 +68,7 @@ func (fr *firejailRunner) Run() error {
 
 	var args []string
 	args = append(args, fmt.Sprintf("--profile=%s", sandboxProfilePath))
-	if params.FirejailParams.NoNetwork {
+	if params.SandboxConfig.NoNetwork {
 		args = append(args, "--net=none")
 	}
 	args = append(args, "--")
@@ -77,7 +77,7 @@ func (fr *firejailRunner) Run() error {
 
 	cmd := firejailCommand(firejailPath, args...)
 	cmd.Dir = params.Dir
-	cmd.Env = collectAllowedEnv(params.Env, os.Environ())
+	cmd.Env = collectAllowedEnv(params.Env, os.Environ(), params.SandboxConfig.AllowEnv)
 	cmd.Stdout = params.Stdout
 	cmd.Stderr = params.Stderr
 

runner/firejail_linux_test.go

@@ -37,8 +37,8 @@ func newFirejailTestRunner(t *testing.T, noNetwork bool) *firejailRunner {
 			TempDir:        t.TempDir(),
 			FirejailParams: FirejailParams{
 				BinaryPath: "/fake/firejail",
-				NoNetwork:  noNetwork,
 			},
+			SandboxConfig: SandboxConfig{NoNetwork: noNetwork},
 		},
 	}
 }

runner/flatpakspawn_linux.go

@@ -47,7 +47,7 @@ func (fr *flatpakSpawnRunner) Run() error {
 	var args []string
 	args = append(args, "--sandbox")
 
-	if params.FlatpakSpawnParams.NoNetwork {
+	if params.SandboxConfig.NoNetwork {
 		args = append(args, "--no-network")
 	}
 
@@ -58,6 +58,14 @@ func (fr *flatpakSpawnRunner) Run() error {
 	for _, e := range params.Env {
 		args = append(args, "--env="+e)
 	}
+	for _, key := range params.SandboxConfig.AllowEnv {
+		if _, found := envLookupWithPresence(params.Env, key); found {
+			continue
+		}
+		if val := os.Getenv(key); val != "" {
+			args = append(args, "--env="+key+"="+val)
+		}
+	}
 
 	// Working directory
 	if params.Dir != "" {