update macos sandbox docs

Author: leafo

using/sandbox/macos.md

@@ -1,28 +1,95 @@
 
 # macOS sandboxing
 
-The itch.io sandbox uses built-in macOS facility `sandbox-exec`.
+The itch.io app uses macOS's built-in `sandbox-exec` facility to sandbox games. Each time a game launches, the app dynamically generates a sandbox policy written in Apple's Sandbox Profile Language (SBPL) and stores it at `{install_folder}/.itch/isolate-app.sb`.
 
-It dynamically generates sandbox policy when launching a game, which:
-
-  * gives read access to the usual things needed by games
-  * gives write access to a few ~/Library folders
-  * explicitly denies a few known sensitive locations
+The policy starts from a **deny-all** default and explicitly allows only the permissions a game needs to run.
 
 Here's the policy template the itch app uses:
 
-  * <https://github.com/itchio/itch/blob/master/src/constants/sandbox-policies/macos-template.js>
+  * <https://github.com/itchio/smaug/blob/master/runner/policies/sandboxexec.go>
+
+## How it works
+
+When a game launches with the sandbox enabled:
+
+1. The app generates an SBPL policy file tailored to the game's install location
+2. The environment is filtered to an allowlist of safe variables (`HOME`, `USER`, `PATH`, locale settings, `TMPDIR`, and itch.io launch variables)
+3. The game is launched through `sandbox-exec -f {policy_file}`
+
+For **app bundles** (`.app` directories), the app creates a temporary shim bundle that wraps the original binary with a shell script invoking `sandbox-exec`. This allows app bundles to launch through the standard macOS app mechanism while still being sandboxed.
+
+For **standalone executables**, `sandbox-exec` is invoked directly.
+
+## Policy modes
+
+The sandbox supports two policy modes:
+
+- **Balanced** (default) — A hardened profile that limits device access to `/dev/null`, `/dev/random`, and `/dev/urandom` only.
+- **Legacy** — A broader profile for compatibility with older games. Allows full `/dev` access and wider read access to `/private`.
+
+The policy mode can be configured in the app's preferences. If a game fails to launch under the balanced profile, try switching to legacy mode before reporting an issue.
+
+## What the sandbox allows
+
+### Filesystem write access
+
+- `~/Library` subpaths: Application Support, Preferences, Logs, Caches, KeyBindings, Saved Application State
+- The game's own install folder (full read-write)
+- `/var/folders` and `/private/var/folders` (macOS temp storage)
+
+### Filesystem read access
+
+- System libraries and binaries: `/usr/local`, `/usr/share`, `/usr/lib`, `/usr/bin`, `/bin`, `/System/Library`
+- Rosetta 2 translation support: `/usr/libexec/rosetta`, `/Library/Apple/usr/libexec/oah` (for running x86_64 games on Apple Silicon)
+- Java: `/Library/Java/JavaVirtualMachines`
+- System preferences: `/etc`, `/private/etc`, `/Library/Preferences`
+- Fonts and audio: `/Library/Audio`, `/Library/Fonts`, `~/Library/Fonts`
+- Input methods and keyboard layouts: `~/Library/Keyboard Layouts`, `~/Library/Input Methods`
+- `/Applications` (read-only)
+
+### Explicitly denied
+
+Even though `~/Library/Application Support` is writable, the following subpaths are explicitly blocked to prevent credential theft:
+
+- `~/Library/Application Support/itch` and `~/Library/Application Support/kitch` (itch.io app config)
+- `~/Library/Application Support/Google` (Chrome data)
+- `~/Library/Application Support/Mozilla` (Firefox data)
+
+### Network
+
+Network access (`network-bind` and `network-outbound`) is allowed by default. It can be disabled with the **Disable network access in sandbox** preference.
+
+### IPC and system access
+
+The following are allowed for compatibility with game frameworks like SDL2 and Electron:
+
+- Mach IPC (`mach-lookup`, `mach-register`)
+- POSIX shared memory (`ipc-posix*`)
+- System sockets (`system-socket`)
+- IOKit device access (`iokit-open`)
+- Process forking and execution (`process-fork`, `process-exec`)
+- Hardware/OS limit probing (`sysctl-read`)
+
+## Settings
+
+The sandbox can be configured from the itch.io app's preferences:
+
+- **Enable itch.io sandbox** — Master toggle to enable or disable sandboxing
+- **Disable network access in sandbox** — Prevents all network access from sandboxed games
+- **Policy mode** — Choose between **Balanced** (default) or **Legacy** for broader compatibility
+- **Allowed environment variable names** — A comma or whitespace-separated list of extra host environment variable names to pass into the sandbox
+
+Games can detect that they are running inside the sandbox by checking for the `ITCHIO_SANDBOX=1` environment variable.
 
 ## Troubleshooting
 
-If your game is broken by the itch.io sandbox on macOS, we recommend using
-the built-in `Console.app` to watch out for permission denials. Look in
-particular for `sandboxd` messages.
+If a game is broken by the sandbox:
+
+1. **Check Console.app.** Open the built-in Console.app and look for `sandboxd` messages to see which permissions are being denied. Shutting down other applications can help reduce noise in the logs.
+
+2. **Try legacy mode.** If the game fails under the default balanced policy, switch the policy mode to legacy in the app's preferences and try again.
 
-Since Console.app shows system-wide logs for all applications, it may be a bit
-chatty. Shutting down applications you don't actively use can help reduce
-the amount of irrelevant messages.
+3. **Inspect the policy.** Open `{install_folder}/.itch/isolate-app.sb` to see the exact SBPL policy being applied to the game.
 
-The default sandbox policy should be more than enough to get most games running,
-but if you run into an issue that you need help resolving, feel free to open
-an issue on our [Issue Tracker](https://github.com/itchio/itch/issues)
+4. **Report the issue.** If you can't resolve the problem, open an issue on our [issue tracker](https://github.com/itchio/itch/issues) with the Console.app output and the contents of the `.sb` file.