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

{dev_bubble-0.6.20 → dev_bubble-0.7.2}/.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.
@@ -120,15 +120,26 @@ Bubbles can run on a remote machine instead of locally. The `--ssh HOST` flag (o
 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.2}/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)

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dev-bubble
-Version: 0.6.20
+Version: 0.7.2
 Summary: Containerized development environments powered by Incus
 Author-email: Kim Morrison <kim@tqft.net>
 License-Expression: Apache-2.0
@@ -346,6 +346,22 @@ The relay only allows opening repos already cloned in `~/.bubble/git/` — it ca
 - **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
+- **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. Disable API access with `bubble security set github-api off`
+- **Shared mathlib cache**: When `shared_cache` is enabled (the default), the mathlib cache at `~/.bubble/mathlib-cache/` is mounted **read-write** into every Mathlib-using Lean container. A compromised container could write poisoned build artifacts that would be picked up by subsequent containers running `lake exe cache get`. This cache is *not* shared with `lake exe cache` run outside a bubble — it only affects bubble containers. To prevent future poisoning, run `bubble security set shared-cache off`, which mounts the cache read-only. If you suspect the cache has already been compromised, delete `~/.bubble/mathlib-cache/`.
+
+### Known Limitations
+
+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 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. The token is scoped to one repository and access level for git and REST API requests, but GraphQL queries (level 3+) are not repo-scoped and can read any data the host token can access.
 
 ## License
 

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

@@ -312,6 +312,22 @@ The relay only allows opening repos already cloned in `~/.bubble/git/` — it ca
 - **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
+- **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. Disable API access with `bubble security set github-api off`
+- **Shared mathlib cache**: When `shared_cache` is enabled (the default), the mathlib cache at `~/.bubble/mathlib-cache/` is mounted **read-write** into every Mathlib-using Lean container. A compromised container could write poisoned build artifacts that would be picked up by subsequent containers running `lake exe cache get`. This cache is *not* shared with `lake exe cache` run outside a bubble — it only affects bubble containers. To prevent future poisoning, run `bubble security set shared-cache off`, which mounts the cache read-only. If you suspect the cache has already been compromised, delete `~/.bubble/mathlib-cache/`.
+
+### Known Limitations
+
+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 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. The token is scoped to one repository and access level for git and REST API requests, but GraphQL queries (level 3+) are not repo-scoped and can read any data the host token can access.
 
 ## License
 

{dev_bubble-0.6.20 → dev_bubble-0.7.2}/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
@@ -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
 
 ---
@@ -1085,12 +1105,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 |
 

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

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