dev-bubble 0.6.20__tar.gz → 0.7.3__tar.gz

{dev_bubble-0.6.20 → dev_bubble-0.7.3}/.claude/CLAUDE.md

@@ -72,7 +72,7 @@ Images are defined in `builder.py`'s `IMAGES` dict with script and parent refere
 Tools are installed in container images via the `[tools]` config section. Each tool has a self-contained install script in `bubble/images/scripts/tools/` and is registered in the `TOOLS` dict in `tools.py` with its script filename, host detection command, required network domains, and a priority for install ordering. Tools include:
 
 - **Language tools** (priority 10): `elan` — auto-detected if elan is on the host
-- **General tools** (priority 50): `claude`, `codex` — auto-detected via host commands
+- **General tools** (priority 50): `claude`, `codex`, `gh` — auto-detected via host commands
 - **Editors** (priority 90): `vscode`, `emacs`, `neovim` — driven by the `editor` config key
 
 Config values are `"yes"`, `"no"`, or `"auto"` (default). Editor tools are special: the configured editor (default: vscode) is treated as `"yes"` unless explicitly `"no"` in `[tools]`. Tools are installed into the `base` image during `build_image("base")` in priority order (language tools before editors, so vscode can detect elan and install Lean extensions). When the resolved tool set changes (detected via a content-aware hash stored in `~/.bubble/tools-hash`), the `base` image is rebuilt synchronously, and stale derived images are purged.
@@ -114,21 +114,32 @@ Bubbles can run on a remote machine instead of locally. The `--ssh HOST` flag (o
 
 **Priority chain for remote host resolution:** `--local` > `--ssh HOST` > `--cloud` > `[cloud] default` > `[remote] default_host`
 
-**State:** `~/.bubble/cloud.json` tracks server ID, IP, SSH key ID. Token comes from `HETZNER_TOKEN` env var (never stored).
+**State:** `~/.bubble/cloud.json` tracks server ID, IP, SSH key ID. Token comes from `HCLOUD_TOKEN` env var (never stored).
 
 ### User Customization Script
 Users can place a `customize.sh` script at `~/.bubble/customize.sh` to run custom setup in all container images. The script runs as root as the final step when building any image (base, lean, lean-v4.X.Y). This lets users add tools, dotfiles, shell config, etc. without forking image scripts. The script's content hash is tracked in `~/.bubble/customize-hash`; on `bubble open`, if the hash differs from the stored value, a background rebuild of the base image is triggered (same pattern as VS Code commit hash drift). Code is in `builder.py` (`customize_hash()`, `_run_customize_script()`).
 
 ### GitHub Auth Proxy
-The auth proxy (`auth_proxy.py`) provides repo-scoped GitHub authentication without injecting the host's token into containers. It's an HTTP reverse proxy that runs on the host.
+The auth proxy (`auth_proxy.py`) provides repo-scoped GitHub authentication without injecting the host's token into containers. It's an HTTP reverse proxy that runs on the host with graduated access levels:
 
-**Flow:** Container git → `url.insteadOf` rewrites to `http://127.0.0.1:7654/git/...` → proxy validates `X-Bubble-Token` header → checks path matches allowed `owner/repo` → adds `Authorization: token <real-token>` → forwards to `https://github.com` → returns response.
+| Level | Description | Routes |
+|-------|-------------|--------|
+| 1 | Git only | `/git/{owner}/{repo}/...` (smart HTTP) |
+| 2 | Git + REST read | + `GET /repos/{owner}/{repo}/...` |
+| 3 | Git + gh read-only (default) | + `POST /graphql` (queries only, mutations blocked) |
+| 4 | Git + gh read-write | + mutations + REST POST/PATCH/DELETE |
 
-**Local bubbles:** Exposed into containers via Incus proxy device (`incus config device add ... proxy connect=tcp:host:7654 listen=tcp:127.0.0.1:7654`).
+**Git flow:** Container git → `url.insteadOf` rewrites to `http://127.0.0.1:7654/git/...` → proxy validates `X-Bubble-Token` header → checks path matches allowed `owner/repo` → adds `Authorization: token <real-token>` → forwards to `https://github.com` → returns response.
 
-**Remote/cloud bubbles:** An SSH reverse tunnel (`ssh -R 7654:127.0.0.1:7654 remote`) forwards the local proxy port to the remote host. An Incus proxy device on the remote then exposes it into the container. Tunnels are per-remote-host (shared across containers) with PID files in `~/.bubble/tunnels/`. Code is in `tunnel.py`.
+**gh CLI flow:** `gh` configured with `http_unix_socket: /bubble/gh-proxy.sock` (via `GH_CONFIG_DIR=/etc/bubble/gh`) → sends requests through Unix socket → proxy validates token from `Authorization` header → enforces access level (REST repo-scoping, GraphQL mutation filtering) → adds real token → forwards to `https://api.github.com`.
 
-**Token management:** Per-container tokens in `~/.bubble/auth-tokens.json` map to `{container, owner, repo}`. Tokens are cleaned up on `bubble pop`. The daemon is managed via launchd/systemd.
+**API security:** REST paths validated against `/repos/{owner}/{repo}/...` (repo-scoped). GraphQL scans ALL operations in a document and classifies by the most dangerous one — `query` allowed at level 3, `mutation` requires level 4. This prevents `operationName`-based bypasses where a query is listed first but a mutation is selected for execution. Batched requests, subscriptions, and malformed bodies rejected. Note: GraphQL is NOT repo-scoped — queries can access any data the host token can read (GitHub's GraphQL API doesn't support path-based scoping). API redirects (e.g. CI log downloads) followed with hardened rules: GET/HEAD only, HTTPS only, allowlisted hosts, max 2 hops, auth headers stripped. GitHub 4xx errors are passed through to clients (not collapsed to 502).
+
+**Local bubbles:** Exposed via Incus proxy devices — TCP for git, Unix socket for gh (`listen=unix:/bubble/gh-proxy.sock`).
+
+**Remote/cloud bubbles:** SSH reverse tunnel forwards the local proxy port. Incus proxy devices on the remote expose both TCP and Unix socket endpoints.
+
+**Token management:** Per-container tokens in `~/.bubble/auth-tokens.json` map to `{container, owner, repo, level}`. Tokens are cleaned up on `bubble pop`. The daemon is managed via launchd/systemd.
 
 ### Security Model
 The `user` account has no sudo and a locked password. Network allowlisting is applied on container creation. SSH keys are injected via `incus file push` (not shell interpolation). All user-supplied values in shell commands are quoted with `shlex.quote()`. Each container mounts only its specific bare repo, not the entire git store.
@@ -241,10 +252,6 @@ VS Code must be restarted after modifying this database.
 ### Pre-baked VS Code Server
 When vscode is enabled as a tool (the default), the base image pre-installs the VS Code Server binary matching the host's `code --version` commit hash. On each `bubble open`, if the hash has changed (VS Code updated), a background `bubble images build base` is triggered. The current bubble proceeds immediately; the next one gets the pre-baked server.
 
-## Changelog
-
-`CHANGELOG.md` in the project root tracks user-visible changes by version. When making changes that will be released, add a brief entry under the current version heading. When tagging a new release, add a new version heading.
-
 ## PyPI Publishing
 
 The package is published to PyPI as **`dev-bubble`** (the CLI command is still `bubble`). Users install with `pipx install dev-bubble` or `uv tool install dev-bubble`.

{dev_bubble-0.6.20 → dev_bubble-0.7.3}/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## 0.7.1 — 2026-03-12
+- Deprecate `config security`, `config lockdown`, `config accept-risks` in favor of `security` subcommands (#150)
+  - Add deprecation warnings (to stderr) when deprecated commands are used
+  - Deprecation notes explain behavioral differences (`config lockdown`/`accept-risks` only pin `auto` settings vs `security lockdown`/`permissive` which set all)
+  - Update error messages to suggest `bubble security set` instead of `bubble config set`
+  - Keep `config set security.<name>` as a supported alias
+
+## 0.7.0 — 2026-03-12
+- GitHub API access via auth proxy: `gh` CLI shim using `http_unix_socket` (#123)
+  - Graduated access level model: level 1 (git only), level 2 (REST read), level 3 (gh read-only, default), level 4 (gh read-write)
+  - `gh` CLI installed as a tool (`auto` mode, detected from host) and configured to route through auth proxy
+  - REST API requests validated against `/repos/{owner}/{repo}/...` (repo-scoped)
+  - GraphQL requests parsed and classified: `query` operations allowed at level 3, `mutation` operations blocked
+  - GraphQL security: scans ALL operations in multi-operation documents to prevent `operationName`-based mutation bypass
+  - GraphQL validation: rejects malformed JSON, batched requests, and subscriptions
+  - GraphQL is NOT repo-scoped (queries can access any data the host token can read)
+  - Redirect following for API responses (CI log downloads): GET/HEAD only, HTTPS only, allowlisted hosts, max 2 hops, auth headers stripped
+  - GitHub 4xx errors (401, 403, 404, 422) passed through to clients instead of being collapsed to 502
+  - Auth proxy accepts tokens from `Authorization` header (gh traffic) in addition to `X-Bubble-Token` (git traffic)
+  - Unix socket proxy device exposes auth proxy to `gh` at `/bubble/gh-proxy.sock` inside containers
+  - `GH_CONFIG_DIR` and `GH_TOKEN` configured via `/etc/profile.d/bubble-gh.sh`
+  - New `security.github_api` setting controls API access level (auto defaults to on = level 3)
+  - Host GitHub token never enters containers; all API access goes through the auth proxy
+  - Works with remote/cloud bubbles via existing SSH tunnel infrastructure
+
+## 0.6.23 — 2026-03-12
+- Add `bubble config show` command to display effective configuration with origin annotations (#149)
+
+## 0.6.22 — 2026-03-12
+- Add heartbeat messages for slow image builds (#145)
+  - Prints `still building...` / `still installing tools...` to stderr every 10s after 5s of silence
+  - Automatically disabled for non-TTY output (piped, `--machine-readable`, CI)
+
+## 0.6.21 — 2026-03-12
+- Hide `skill`, `claude`, `codex` from top-level help; hide `config security`, `config lockdown`, `config accept-risks` as deprecated aliases (#142)
+  - All commands remain fully functional, just not listed in `--help`
+  - Reduces visual noise: 15+ command groups → 12 visible in top-level help
+
 ## 0.6.20 — 2026-03-12
 - Normalize CLI setting names to hyphens (#143)
   - `bubble security set` and `bubble config set` now accept hyphenated names (e.g. `github-auth`, `claude-credentials`)
@@ -24,6 +62,10 @@
   - Extracted shared `_power_on_and_wait()` helper used by both `start_server()` and `get_cloud_remote_host()`
 
 ## 0.6.16 — 2026-03-12
+- Consistent indentation in `bubble open` progress output (#144)
+  - Introduce `step()` / `detail()` helpers in `output.py` for two-level output formatting
+  - Top-level steps have no indent; sub-details get 2-space indent
+  - Applied consistently across local, native, and remote code paths
 - Print a welcome banner on first run when `config.toml` is created (#139)
 - Split README Quick Start into a short 3-command section plus a detailed Examples section (#154)
 - Standardize error handling across the codebase (#155)
@@ -236,8 +278,8 @@
 - `bubble config accept-risks` silences on-by-default warnings; `bubble config lockdown` disables off-by-default features
 - Security warnings printed to stderr for all `auto` settings during `bubble open`
 - `BUBBLE_QUIET_SECURITY=1` env var suppresses warnings for CI/automation
-- Settings: `shared_cache`, `user_mounts`, `network_github`, `relay`, `claude_credentials`, `host_key_trust`, `git_manifest_trust`
-- When `shared_cache=off`, shared mounts are read-only; when `network_github=off`, GitHub domains stripped from allowlist
+- Settings: `shared_cache`, `user_mounts`, `relay`, `claude_credentials`, `host_key_trust`, `git_manifest_trust`
+- When `shared_cache=off`, shared mounts are read-only
 - When `user_mounts=off` or `claude_credentials=off`, corresponding CLI flags are rejected
 - Relay enable/disable migrated to `[security] relay` with backwards compatibility for `[relay] enabled`
 - Replaces ad-hoc "Tip: use --claude-credentials" message with unified security warning system

{dev_bubble-0.6.20/dev_bubble.egg-info → dev_bubble-0.7.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dev-bubble
-Version: 0.6.20
+Version: 0.7.3
 Summary: Containerized development environments powered by Incus
 Author-email: Kim Morrison <kim@tqft.net>
 License-Expression: Apache-2.0
@@ -34,7 +34,10 @@ Dynamic: license-file
 
 # bubble
 
-Containerized development environments for the Lean language, powered by [Incus](https://linuxcontainers.org/incus/).
+Containerized development environments,
+with opinionated presets for users of the [Lean](https://lean-lang.org/) programming language,
+powered by [Incus](https://linuxcontainers.org/incus/).
+We assume that you work using VSCode, emacs, or neovim, and that you collaborate via GitHub.
 
 ## Quick Start
 
@@ -51,6 +54,29 @@ bubble list
 
 See [Examples](#examples) for branches, local repos, issues, remote, and non-interactive use.
 
+## Use cases
+
+You might be worried about:
+* Reviewing and running Lean code from strangers.
+* Running an AI agent like Claude in "yolo" mode.
+* Managing work and AI threads across many repositories and branches.
+
+The `bubble` tool attempts to provide a fast, low-friction, secure solution to these problems.
+It launches containers pre-built for working with Lean (and your favorite AI tools),
+and handles repository management and caches behind the scenes.
+
+By working in containers, you can prevent AI tools from accidentally damaging your system
+(or other repositories you have access to)
+and handle potentially adversarial code from other humans or agents.
+Opening Lean files from untrusted sources
+(e.g. reviewing code, or supply chain attacks on your upstream dependencies)
+can execute arbitrary code, so if you regularly do this you should be using containers.
+
+`bubble` also allows you to limit how your GitHub access can be used:
+containers don't have direct access to GitHub, and never see your authorization token,
+but interact through a restricted proxy.
+You can choose via the `bubble security` tool the capability/security trade-off you prefer.
+
 ## Examples
 
 ```bash
@@ -121,7 +147,7 @@ Each "bubble" is a lightweight Linux container (via Incus) with:
 
 **Language hooks**: bubble automatically detects the project's language and selects the right image. For Lean 4 projects (detected via `lean-toolchain`), the container includes elan, pre-installed VS Code extensions, and auto-downloads the mathlib cache when needed.
 
-**Network allowlisting**: Containers can only reach allowed domains (GitHub by default, plus language-specific domains like `releases.lean-lang.org` for Lean). IPv6 is blocked, DNS is restricted to the container resolver, and outbound SSH is blocked. Configurable in `~/.bubble/config.toml`.
+**Network allowlisting**: Containers can only reach allowed domains (language-specific domains like `releases.lean-lang.org` for Lean, plus any configured in `~/.bubble/config.toml`). Direct GitHub access is blocked by iptables — all GitHub traffic is forced through the auth proxy, which enforces repo-scoping and rate limits. IPv6 is blocked, DNS is restricted to the container resolver, and outbound SSH is blocked.
 
 ## Requirements
 
@@ -148,21 +174,37 @@ Each "bubble" is a lightweight Linux container (via Incus) with:
 | `bubble cloud default on\|off` | Set cloud as the default for all bubbles |
 | `bubble cloud ssh` | SSH directly to the cloud server |
 | `bubble tools list\|set\|status` | Manage tools installed in container images |
+| `bubble security [set\|permissive\|lockdown\|default]` | Review and manage security posture |
 | `bubble doctor` | Diagnose and fix common issues |
 
+## Security
+
+- **No sudo**: The `user` account has no sudo access and a locked password
+- **Network allowlisting**: iptables rules restrict outbound connections to allowed domains only
+- **IPv6 blocked**: All IPv6 traffic is dropped
+- **DNS restricted**: DNS queries only go to the container's configured resolver
+- **No outbound SSH**: Containers cannot SSH out (VSCode uses `incus exec` ProxyCommand)
+- **SSH key-only auth**: Password authentication is disabled
+- **Shell injection hardening**: All user-supplied values are quoted with `shlex.quote()`
+- **Per-repo git mount**: Each container only sees its own bare repo, not the entire git store
+- **Bubble-in-bubble relay**: Containers can open new bubbles on the host, but only for repos already cloned in `~/.bubble/git/`. Disable with `bubble security set relay off`
+- **GitHub auth proxy**: Host token never enters containers. Git and REST API are repo-scoped. **GraphQL queries are read-only but account-wide** — can read any data the host token can access. API access can be set to `off`, `on` (read-only, the default), or `read-write` (enables mutations) via `bubble security set github-api`
+- **Shared mathlib cache**: The mathlib cache at `~/.bubble/mathlib-cache/` is shared across Lean containers. Modes: `on` (default) = read-write (a compromised container could poison cached artifacts), `off` = read-only (prevents poisoning), `overlay` = read-only with per-container writable overlay. This cache is *not* shared with `lake exe cache` run outside a bubble. Configure with `bubble security set shared-cache`. If you suspect poisoning, delete `~/.bubble/mathlib-cache/`.
+
 ## Images
 
-Images are built automatically on first use.
+Images are built automatically on first use. Any enabled [tools](#tools) are installed in the `base` image and inherited by all derived images.
 
 | Image | Contents |
 |-------|----------|
-| `base` | Ubuntu 24.04, git, openssh-server, build-essential, pre-baked VS Code Server |
-| `lean` | base + elan, leantar, VS Code Lean 4 extension, auto-cache extension |
+| `base` | Ubuntu 24.04, git, openssh-server, build-essential, plus configured tools |
+| `lean` | base + leantar (+ elan fallback if not installed as a tool) |
+| `python` | base + uv, ruff |
 | `lean-v4.X.Y` | lean + specific toolchain pre-installed (built lazily on demand) |
 
-`base` and `lean` are static images you can rebuild with `bubble images build <name>`. Versioned `lean-v4.X.Y` images are built automatically in the background when a project uses a stable/RC toolchain not yet cached — the current bubble proceeds immediately with elan downloading the toolchain on demand, and the next bubble for that version starts instantly.
+`base`, `lean`, and `python` are static images you can rebuild with `bubble images build <name>`. Versioned `lean-v4.X.Y` images are built automatically in the background when a project uses a stable/RC toolchain not yet cached — the current bubble proceeds immediately with elan downloading the toolchain on demand, and the next bubble for that version starts instantly.
 
-For mathlib or mathlib-dependent projects, a VS Code terminal automatically runs `lake exe cache get` when the workspace opens.
+When VS Code is the configured editor and elan is installed, the base image also includes pre-baked VS Code Lean 4 extensions and an auto-cache extension. For mathlib or mathlib-dependent projects, a VS Code terminal automatically runs `lake exe cache get` when the workspace opens.
 
 ## Configuration
 
@@ -203,7 +245,7 @@ Tools like Claude Code and OpenAI Codex can be installed in container images. Ea
 
 ```bash
 bubble tools list                  # show all tools and their settings
-bubble tools set claude yes   # always install
+bubble tools set claude yes        # always install
 bubble tools set codex no          # never install
 bubble tools status                # show what would actually be installed
 ```
@@ -239,7 +281,7 @@ Run bubbles on auto-provisioned Hetzner Cloud servers. The server shuts down aut
 2. Go to your project → Security → API Tokens → Generate API Token (read/write)
 3. Set the token in your environment:
    ```bash
-   export HETZNER_TOKEN="your-token-here"
+   export HCLOUD_TOKEN="your-token-here"
    ```
 4. Install the cloud dependency:
    ```bash
@@ -319,33 +361,33 @@ location = "fsn1"            # datacenter: fsn1, nbg1, hel1, ash, hil
 idle_timeout = 900           # seconds before idle shutdown (default: 900 = 15min)
 ```
 
-The `HETZNER_TOKEN` environment variable is always required — the token is never stored on disk.
+The `HCLOUD_TOKEN` environment variable is always required — the token is never stored on disk.
 
 ## Bubble-in-Bubble
 
-You can run `bubble` from inside a container to open another bubble on the host. This is useful when reviewing a related PR while working on a feature branch.
+You can run `bubble` from inside a container to open another bubble on the host. This is enabled by default and is useful when reviewing a related PR while working on a feature branch.
 
 ```bash
-# On the host: enable the relay (one-time setup)
-bubble relay enable
-
 # Inside a container: open another bubble
 bubble leanprover/lean4/pull/456
 bubble mathlib4
 ```
 
-The relay only allows opening repos already cloned in `~/.bubble/git/` — it cannot trigger cloning of new repos. Local paths are rejected. Existing bubbles need to be recreated after enabling the relay to get the relay socket.
+The relay only allows opening repos already cloned in `~/.bubble/git/` — it cannot trigger cloning of new repos. Local paths are rejected. To disable the relay, run `bubble security set relay off`.
 
-## Security
+## Other Security Limitations
 
-- **No sudo**: The `user` account has no sudo access and a locked password
-- **Network allowlisting**: iptables rules restrict outbound connections to allowed domains only
-- **IPv6 blocked**: All IPv6 traffic is dropped
-- **DNS restricted**: DNS queries only go to the container's configured resolver
-- **No outbound SSH**: Containers cannot SSH out (VSCode uses `incus exec` ProxyCommand)
-- **SSH key-only auth**: Password authentication is disabled
-- **Shell injection hardening**: All user-supplied values are quoted with `shlex.quote()`
-- **Per-repo git mount**: Each container only sees its own bare repo, not the entire git store
+These are inherent consequences of the architecture, not bugs. Understanding them helps you make informed trust decisions.
+
+1. **DNS exfiltration**: The network allowlist restricts IP connectivity, but DNS queries still reach the internet via the container resolver. Data can be encoded in DNS queries to exfiltrate information. This is inherent to any iptables-based approach that allows DNS.
+
+2. **/24 CIDR over-allowance**: Domain allowlisting resolves to /24 CIDR blocks (256 IPs) to handle CDN IP rotation. Other services sharing the same /24 block are also reachable.
+
+3. **iptables defense depth**: Network rules are enforced by iptables inside the container. The `user` account cannot modify them (no sudo), but a kernel exploit or other root escalation within the container could flush the rules. There is no external enforcement layer (e.g., Incus ACLs).
+
+4. **Boot-time network window**: There is a brief window between container launch and iptables rule application during which the container has unrestricted network access. No user code runs during this window with stock images.
+
+5. **Auth proxy token visibility**: The per-container auth proxy token (an internal bubble token, not a GitHub token) is stored in the user's git config and in `/etc/profile.d/bubble-gh.sh` (mode 644). Any process in the container can read it and use it to make requests through the auth proxy. The proxy enforces repo-scoping for git and REST API requests, but GraphQL queries (level 3+) are not repo-scoped and can read any data the host's GitHub token can access.
 
 ## License
 

{dev_bubble-0.6.20 → dev_bubble-0.7.3}/README.md

@@ -1,6 +1,9 @@
 # bubble
 
-Containerized development environments for the Lean language, powered by [Incus](https://linuxcontainers.org/incus/).
+Containerized development environments,
+with opinionated presets for users of the [Lean](https://lean-lang.org/) programming language,
+powered by [Incus](https://linuxcontainers.org/incus/).
+We assume that you work using VSCode, emacs, or neovim, and that you collaborate via GitHub.
 
 ## Quick Start
 
@@ -17,6 +20,29 @@ bubble list
 
 See [Examples](#examples) for branches, local repos, issues, remote, and non-interactive use.
 
+## Use cases
+
+You might be worried about:
+* Reviewing and running Lean code from strangers.
+* Running an AI agent like Claude in "yolo" mode.
+* Managing work and AI threads across many repositories and branches.
+
+The `bubble` tool attempts to provide a fast, low-friction, secure solution to these problems.
+It launches containers pre-built for working with Lean (and your favorite AI tools),
+and handles repository management and caches behind the scenes.
+
+By working in containers, you can prevent AI tools from accidentally damaging your system
+(or other repositories you have access to)
+and handle potentially adversarial code from other humans or agents.
+Opening Lean files from untrusted sources
+(e.g. reviewing code, or supply chain attacks on your upstream dependencies)
+can execute arbitrary code, so if you regularly do this you should be using containers.
+
+`bubble` also allows you to limit how your GitHub access can be used:
+containers don't have direct access to GitHub, and never see your authorization token,
+but interact through a restricted proxy.
+You can choose via the `bubble security` tool the capability/security trade-off you prefer.
+
 ## Examples
 
 ```bash
@@ -87,7 +113,7 @@ Each "bubble" is a lightweight Linux container (via Incus) with:
 
 **Language hooks**: bubble automatically detects the project's language and selects the right image. For Lean 4 projects (detected via `lean-toolchain`), the container includes elan, pre-installed VS Code extensions, and auto-downloads the mathlib cache when needed.
 
-**Network allowlisting**: Containers can only reach allowed domains (GitHub by default, plus language-specific domains like `releases.lean-lang.org` for Lean). IPv6 is blocked, DNS is restricted to the container resolver, and outbound SSH is blocked. Configurable in `~/.bubble/config.toml`.
+**Network allowlisting**: Containers can only reach allowed domains (language-specific domains like `releases.lean-lang.org` for Lean, plus any configured in `~/.bubble/config.toml`). Direct GitHub access is blocked by iptables — all GitHub traffic is forced through the auth proxy, which enforces repo-scoping and rate limits. IPv6 is blocked, DNS is restricted to the container resolver, and outbound SSH is blocked.
 
 ## Requirements
 
@@ -114,21 +140,37 @@ Each "bubble" is a lightweight Linux container (via Incus) with:
 | `bubble cloud default on\|off` | Set cloud as the default for all bubbles |
 | `bubble cloud ssh` | SSH directly to the cloud server |
 | `bubble tools list\|set\|status` | Manage tools installed in container images |
+| `bubble security [set\|permissive\|lockdown\|default]` | Review and manage security posture |
 | `bubble doctor` | Diagnose and fix common issues |
 
+## Security
+
+- **No sudo**: The `user` account has no sudo access and a locked password
+- **Network allowlisting**: iptables rules restrict outbound connections to allowed domains only
+- **IPv6 blocked**: All IPv6 traffic is dropped
+- **DNS restricted**: DNS queries only go to the container's configured resolver
+- **No outbound SSH**: Containers cannot SSH out (VSCode uses `incus exec` ProxyCommand)
+- **SSH key-only auth**: Password authentication is disabled
+- **Shell injection hardening**: All user-supplied values are quoted with `shlex.quote()`
+- **Per-repo git mount**: Each container only sees its own bare repo, not the entire git store
+- **Bubble-in-bubble relay**: Containers can open new bubbles on the host, but only for repos already cloned in `~/.bubble/git/`. Disable with `bubble security set relay off`
+- **GitHub auth proxy**: Host token never enters containers. Git and REST API are repo-scoped. **GraphQL queries are read-only but account-wide** — can read any data the host token can access. API access can be set to `off`, `on` (read-only, the default), or `read-write` (enables mutations) via `bubble security set github-api`
+- **Shared mathlib cache**: The mathlib cache at `~/.bubble/mathlib-cache/` is shared across Lean containers. Modes: `on` (default) = read-write (a compromised container could poison cached artifacts), `off` = read-only (prevents poisoning), `overlay` = read-only with per-container writable overlay. This cache is *not* shared with `lake exe cache` run outside a bubble. Configure with `bubble security set shared-cache`. If you suspect poisoning, delete `~/.bubble/mathlib-cache/`.
+
 ## Images
 
-Images are built automatically on first use.
+Images are built automatically on first use. Any enabled [tools](#tools) are installed in the `base` image and inherited by all derived images.
 
 | Image | Contents |
 |-------|----------|
-| `base` | Ubuntu 24.04, git, openssh-server, build-essential, pre-baked VS Code Server |
-| `lean` | base + elan, leantar, VS Code Lean 4 extension, auto-cache extension |
+| `base` | Ubuntu 24.04, git, openssh-server, build-essential, plus configured tools |
+| `lean` | base + leantar (+ elan fallback if not installed as a tool) |
+| `python` | base + uv, ruff |
 | `lean-v4.X.Y` | lean + specific toolchain pre-installed (built lazily on demand) |
 
-`base` and `lean` are static images you can rebuild with `bubble images build <name>`. Versioned `lean-v4.X.Y` images are built automatically in the background when a project uses a stable/RC toolchain not yet cached — the current bubble proceeds immediately with elan downloading the toolchain on demand, and the next bubble for that version starts instantly.
+`base`, `lean`, and `python` are static images you can rebuild with `bubble images build <name>`. Versioned `lean-v4.X.Y` images are built automatically in the background when a project uses a stable/RC toolchain not yet cached — the current bubble proceeds immediately with elan downloading the toolchain on demand, and the next bubble for that version starts instantly.
 
-For mathlib or mathlib-dependent projects, a VS Code terminal automatically runs `lake exe cache get` when the workspace opens.
+When VS Code is the configured editor and elan is installed, the base image also includes pre-baked VS Code Lean 4 extensions and an auto-cache extension. For mathlib or mathlib-dependent projects, a VS Code terminal automatically runs `lake exe cache get` when the workspace opens.
 
 ## Configuration
 
@@ -169,7 +211,7 @@ Tools like Claude Code and OpenAI Codex can be installed in container images. Ea
 
 ```bash
 bubble tools list                  # show all tools and their settings
-bubble tools set claude yes   # always install
+bubble tools set claude yes        # always install
 bubble tools set codex no          # never install
 bubble tools status                # show what would actually be installed
 ```
@@ -205,7 +247,7 @@ Run bubbles on auto-provisioned Hetzner Cloud servers. The server shuts down aut
 2. Go to your project → Security → API Tokens → Generate API Token (read/write)
 3. Set the token in your environment:
    ```bash
-   export HETZNER_TOKEN="your-token-here"
+   export HCLOUD_TOKEN="your-token-here"
    ```
 4. Install the cloud dependency:
    ```bash
@@ -285,33 +327,33 @@ location = "fsn1"            # datacenter: fsn1, nbg1, hel1, ash, hil
 idle_timeout = 900           # seconds before idle shutdown (default: 900 = 15min)
 ```
 
-The `HETZNER_TOKEN` environment variable is always required — the token is never stored on disk.
+The `HCLOUD_TOKEN` environment variable is always required — the token is never stored on disk.
 
 ## Bubble-in-Bubble
 
-You can run `bubble` from inside a container to open another bubble on the host. This is useful when reviewing a related PR while working on a feature branch.
+You can run `bubble` from inside a container to open another bubble on the host. This is enabled by default and is useful when reviewing a related PR while working on a feature branch.
 
 ```bash
-# On the host: enable the relay (one-time setup)
-bubble relay enable
-
 # Inside a container: open another bubble
 bubble leanprover/lean4/pull/456
 bubble mathlib4
 ```
 
-The relay only allows opening repos already cloned in `~/.bubble/git/` — it cannot trigger cloning of new repos. Local paths are rejected. Existing bubbles need to be recreated after enabling the relay to get the relay socket.
+The relay only allows opening repos already cloned in `~/.bubble/git/` — it cannot trigger cloning of new repos. Local paths are rejected. To disable the relay, run `bubble security set relay off`.
 
-## Security
+## Other Security Limitations
 
-- **No sudo**: The `user` account has no sudo access and a locked password
-- **Network allowlisting**: iptables rules restrict outbound connections to allowed domains only
-- **IPv6 blocked**: All IPv6 traffic is dropped
-- **DNS restricted**: DNS queries only go to the container's configured resolver
-- **No outbound SSH**: Containers cannot SSH out (VSCode uses `incus exec` ProxyCommand)
-- **SSH key-only auth**: Password authentication is disabled
-- **Shell injection hardening**: All user-supplied values are quoted with `shlex.quote()`
-- **Per-repo git mount**: Each container only sees its own bare repo, not the entire git store
+These are inherent consequences of the architecture, not bugs. Understanding them helps you make informed trust decisions.
+
+1. **DNS exfiltration**: The network allowlist restricts IP connectivity, but DNS queries still reach the internet via the container resolver. Data can be encoded in DNS queries to exfiltrate information. This is inherent to any iptables-based approach that allows DNS.
+
+2. **/24 CIDR over-allowance**: Domain allowlisting resolves to /24 CIDR blocks (256 IPs) to handle CDN IP rotation. Other services sharing the same /24 block are also reachable.
+
+3. **iptables defense depth**: Network rules are enforced by iptables inside the container. The `user` account cannot modify them (no sudo), but a kernel exploit or other root escalation within the container could flush the rules. There is no external enforcement layer (e.g., Incus ACLs).
+
+4. **Boot-time network window**: There is a brief window between container launch and iptables rule application during which the container has unrestricted network access. No user code runs during this window with stock images.
+
+5. **Auth proxy token visibility**: The per-container auth proxy token (an internal bubble token, not a GitHub token) is stored in the user's git config and in `/etc/profile.d/bubble-gh.sh` (mode 644). Any process in the container can read it and use it to make requests through the auth proxy. The proxy enforces repo-scoping for git and REST API requests, but GraphQL queries (level 3+) are not repo-scoped and can read any data the host's GitHub token can access.
 
 ## License
 

{dev_bubble-0.6.20 → dev_bubble-0.7.3}/SPEC.md

@@ -57,8 +57,8 @@ equivalent to `bubble open <url>`.
 | `--base` | string | | Base branch for `-b` |
 | `--mount` | string (repeatable) | | Mount host dir into container |
 | `--claude-config/--no-claude-config` | flag | enabled | Mount ~/.claude config read-only |
-| `--claude-credentials/--no-claude-credentials` | flag | disabled | Mount Claude credentials |
-| `--codex-credentials/--no-codex-credentials` | flag | disabled | Mount Codex credentials |
+| `--claude-credentials/--no-claude-credentials` | flag | enabled | Mount Claude credentials |
+| `--codex-credentials/--no-codex-credentials` | flag | enabled | Mount Codex credentials |
 | `--ssh HOST` | string | | Run on remote host |
 | `--cloud` | flag | | Run on Hetzner Cloud server |
 | `--local` | flag | | Force local execution |
@@ -335,8 +335,16 @@ of the versioned image for next time.
 - `~/.bubble/mathlib-cache/` ↔ `/shared/mathlib-cache/` (read-write)
 - Environment variable `MATHLIB_CACHE_DIR=/shared/mathlib-cache`
 
+> **Security note:** The shared cache is mounted read-write by default, so a
+> compromised container could write poisoned `.olean` files that subsequent
+> containers would pick up via `lake exe cache get`. The cache is *not* shared
+> with `lake exe cache` run on the host — only bubble containers are affected.
+> Set `shared-cache` to `off` (via `bubble security set shared-cache off`) to
+> mount the cache read-only and prevent future poisoning. If you suspect the
+> cache has already been compromised, delete `~/.bubble/mathlib-cache/`.
+
 **Post-clone behavior:**
-- Pre-populate Lake dependencies from `lake-manifest.json` (see 2.3)
+- Pre-populate Lake dependencies from `lake-manifest.json` (see 2.4)
 - Write auto-build command to `~/.bubble-fetch-cache` marker file
 - For Mathlib-using projects: `cd <dir> && lake exe cache get && lake build`
 - For the lean4 repo itself: cmake + make build
@@ -769,7 +777,7 @@ entry has a `remote_host` field. The command is forwarded via
 
 ### 8.1 Requirements
 
-- `HETZNER_TOKEN` environment variable (never stored)
+- `HCLOUD_TOKEN` environment variable (never stored)
 - `hcloud` Python package (optional dependency)
 
 ### 8.2 Commands
@@ -908,9 +916,8 @@ When `--claude-config` is enabled (default), mount specific items from
 `~/.claude/` into `/home/user/.claude/` read-only:
 - `CLAUDE.md`, `settings.json`, `skills/`, `keybindings.json`, `commands/`
 
-Credential files (`.credentials.json`) are only mounted when
-`--claude-credentials` is explicitly enabled or the config `claude.credentials`
-is true.
+Credential files (`.credentials.json`) are mounted by default. Disable with
+`--no-claude-credentials` or set `claude.credentials = false` in config.
 
 **Symlink safety:** Reject symlinks that escape `~/.claude/` to prevent
 exposing arbitrary host files.
@@ -918,7 +925,7 @@ exposing arbitrary host files.
 ### 10.2 Codex config mounting
 
 Similar to Claude. Config: `config.toml` (read-only). Credentials: `auth.json`
-(opt-in via `--codex-credentials` or config).
+(mounted by default; disable via `--no-codex-credentials` or config).
 
 ### 10.3 Editor config mounting
 
@@ -933,8 +940,10 @@ Similar to Claude. Config: `config.toml` (read-only). Credentials: `auth.json`
 
 ### 10.4 GitHub auth proxy
 
-An HTTP reverse proxy on the host provides repo-scoped GitHub authentication.
-The host's GitHub token never enters the container.
+An HTTP reverse proxy on the host provides GitHub authentication without
+exposing the host's token. Git and REST API requests are repo-scoped;
+GraphQL requests are operation-validated (queries vs mutations) but not
+repo-scoped — see access levels below.
 
 **Port:** 7654 (default, configurable).
 
@@ -942,7 +951,7 @@ The host's GitHub token never enters the container.
 1. Container git is configured with `url.insteadOf` to route HTTPS through the proxy
 2. Container sends request with `X-Bubble-Token` header
 3. Proxy validates token against `~/.bubble/auth-tokens.json` (mode 0600)
-4. Proxy checks path matches the allowed `owner/repo`
+4. For git/REST: proxy checks path matches the allowed `owner/repo`. For GraphQL: proxy validates operation type (queries allowed at level 3, mutations require level 4) but does not scope to a specific repo
 5. Proxy adds `Authorization: token <real-token>` header
 6. Proxy forwards to `https://github.com`
 7. Response returned to container
@@ -960,6 +969,19 @@ The host's GitHub token never enters the container.
 - `POST /git/{owner}/{repo}[.git]/git-upload-pack`
 - `POST /git/{owner}/{repo}[.git]/git-receive-pack`
 
+**Access levels (per-container):**
+| Level | Description | Scope |
+|-------|-------------|-------|
+| 1 | Git smart HTTP only (push/pull) | Repo-scoped |
+| 2 | Git + REST API read-only | Repo-scoped (REST paths validated against `/repos/{owner}/{repo}/...`) |
+| 3 (default) | Git + gh read-only (REST read + GraphQL queries) | Git and REST are repo-scoped; **GraphQL is account-wide** — queries can read any data the host token can access |
+| 4 | Git + gh read-write (REST + GraphQL + mutations) | Git and REST are repo-scoped; **GraphQL queries and mutations are account-wide** |
+
+> **Note:** GitHub's GraphQL API does not support path-based scoping.
+> At the default level 3, a container can query any repository, org membership,
+> or user data readable by the host token. To restrict containers to git-only
+> access, use `bubble security set github-api off`.
+
 **Security:**
 - Path canonicalization: reject encoded separators, dot-segments, duplicate slashes
 - No redirect following (returns redirects as-is to prevent token leakage)
@@ -1046,10 +1068,10 @@ server_name = "bubble-cloud"
 default = false
 
 [claude]
-credentials = false
+credentials = true
 
 [codex]
-credentials = false
+credentials = true
 
 [security]
 # All settings default to "auto"
@@ -1069,8 +1091,6 @@ get/set interface:
 - `bubble codex credentials on|off` — toggle Codex credential mounting
 - `bubble security set NAME on|off|auto` — configure security settings
 - `bubble config set KEY VALUE` — set security settings (alias)
-- `bubble config lockdown` — disable all off-by-default security features
-- `bubble config accept-risks` — enable all on-by-default risk features
 - `bubble config symlink-claude-projects` — symlink Claude projects directory
 
 ---
@@ -1084,13 +1104,14 @@ values: `auto`, `on`, `off`.
 
 | Setting | Auto default | Description |
 |---------|-------------|-------------|
-| `network-github` | on | GitHub domains in network allowlist |
-| `shared-cache` | on | Writable shared mounts (mathlib cache) |
+| `shared-cache` | on | Writable shared mounts (mathlib cache) — see [Lean 4 hook](#22-lean-4-hook) security note |
 | `user-mounts` | on | `--mount` flag support |
 | `git-manifest-trust` | on | Auto-clone Lake manifest dependencies |
-| `claude-credentials` | off | Mount Claude credentials into containers |
-| `codex-credentials` | off | Mount Codex credentials into containers |
-| `github-auth` | on | Repo-scoped GitHub auth via proxy |
+| `claude-credentials` | on | Mount Claude credentials into containers |
+| `codex-credentials` | on | Mount Codex credentials into containers |
+| `github-auth` | on | Repo-scoped GitHub auth via proxy (git push/pull) |
+| `github-api` | on | GitHub API access via auth proxy: REST is repo-scoped; **GraphQL queries are read-only but account-wide** (can read any repo the host token can access). Set to `off` for git-only, or `read-write` for mutations |
+| `github-token-inject` | off | Direct GitHub token injection (bypasses proxy) |
 | `relay` | on | Bubble-in-bubble relay |
 | `host-key-trust` | on | Disable SSH StrictHostKeyChecking |
 
@@ -1104,8 +1125,10 @@ user to `bubble security`. Suppressed by `BUBBLE_QUIET_SECURITY=1`.
 - `bubble security lockdown` — set all to `off`
 - `bubble security default` — reset all to `auto`
 
-When `network-github` is `off`, all GitHub-related domains are stripped from the
-network allowlist.
+**GitHub network access:** Direct GitHub network access (via iptables) is only
+allowed when `github-token-inject` is enabled (level 5). At all other auth
+levels (0–4), iptables blocks direct GitHub traffic and forces it through the
+auth proxy on loopback, which enforces repo-scoping and rate limits.
 
 ---
 

{dev_bubble-0.6.20 → dev_bubble-0.7.3}/bubble/__init__.py

@@ -1,3 +1,3 @@
 """bubble: Containerized development environments."""
 
-__version__ = "0.6.20"
+__version__ = "0.7.3"