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

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

@@ -23,6 +23,7 @@ bubble/
 ├── automation.py       # Periodic jobs: launchd (macOS), systemd (Linux)
 ├── relay.py            # Bubble-in-bubble relay daemon (Unix socket, validation, rate limiting)
 ├── auth_proxy.py       # HTTP reverse proxy for repo-scoped GitHub auth (token stays on host)
+├── graphql_validator.py # GraphQL tokenizer, parser, and allowlist validation for auth proxy
 ├── tunnel.py           # SSH reverse tunnel management for remote auth proxy access
 ├── remote.py           # Remote SSH host support: run bubbles on remote machines
 ├── cloud.py            # Hetzner Cloud auto-provisioning (provision, destroy, start, stop)
@@ -133,13 +134,15 @@ The auth proxy (`auth_proxy.py`) provides repo-scoped GitHub authentication with
 
 **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`.
 
-**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).
+**GraphQL validation** (`graphql_validator.py`): GraphQL access is controlled by two independent axes — `graphql_read` and `graphql_write` — each supporting `whitelisted`, `unrestricted`, or `none` modes. The default is `whitelisted` for both. In whitelisted mode, a lightweight tokenizer/parser validates structure (single operation, single top-level field, no aliases/directives, no fragments in mutations) and semantics. Read validation repo-scopes `repository` queries via variables, verifies `node` queries via pre-flight ownership checks, and checks second-level fields against an allowlist. Write validation checks mutations against an allowlist (createPullRequest, addComment, mergePullRequest, etc.) with repo-scoping via repositoryId comparison or pre-flight node ownership verification. Old tokens without `graphql_*` fields derive policies from the legacy `level` field for backward compatibility.
+
+**REST security:** REST paths validated against `/repos/{owner}/{repo}/...` (repo-scoped). REST level defaults to `LEVEL_GH_READWRITE` since path validation already constrains access. 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.
+**Token management:** Per-container tokens in `~/.bubble/auth-tokens.json` map to `{container, owner, repo, level, graphql_read, graphql_write}`. 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.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dev-bubble
-Version: 0.7.3
+Version: 0.7.6
 Summary: Containerized development environments powered by Incus
 Author-email: Kim Morrison <kim@tqft.net>
 License-Expression: Apache-2.0

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

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

{dev_bubble-0.7.3 → dev_bubble-0.7.6}/bubble/auth_proxy.py

@@ -141,16 +141,29 @@ logger = logging.getLogger("bubble.auth_proxy")
 
 
 def generate_auth_token(
-    container_name: str, owner: str, repo: str, level: int = DEFAULT_LEVEL
+    container_name: str,
+    owner: str,
+    repo: str,
+    level: int = DEFAULT_LEVEL,
+    graphql_read: str = "whitelisted",
+    graphql_write: str = "whitelisted",
 ) -> str:
     """Generate an auth proxy token for a container.
 
-    The token maps to (container_name, owner, repo, level) — the proxy
-    uses this to validate requests and enforce the access level.
+    The token maps to (container_name, owner, repo, level, graphql_read,
+    graphql_write) — the proxy uses this to validate requests and enforce
+    the access policy.
     Uses file locking to prevent read-modify-write races.
     """
     return TokenStore(AUTH_PROXY_TOKENS).generate(
-        {"container": container_name, "owner": owner, "repo": repo, "level": level}
+        {
+            "container": container_name,
+            "owner": owner,
+            "repo": repo,
+            "level": level,
+            "graphql_read": graphql_read,
+            "graphql_write": graphql_write,
+        }
     )
 
 
@@ -420,6 +433,31 @@ def _parse_graphql_op_type(query: str) -> str | None:
     return "query"
 
 
+def _resolve_graphql_policies(info: dict) -> tuple[str, str]:
+    """Extract GraphQL policies from token info, with backward compat.
+
+    Returns (graphql_read, graphql_write).
+    For tokens created before the graphql_read/graphql_write fields
+    existed, derives policies from the legacy level field.
+    """
+    from .graphql_validator import VALID_GRAPHQL_POLICIES
+
+    graphql_read = info.get("graphql_read")
+    graphql_write = info.get("graphql_write")
+
+    if graphql_read in VALID_GRAPHQL_POLICIES and graphql_write in VALID_GRAPHQL_POLICIES:
+        return graphql_read, graphql_write
+
+    # Backward compat: derive from level
+    level = info.get("level", LEVEL_GIT_ONLY)
+    if level < LEVEL_GH_READ:
+        return "none", "none"
+    elif level < LEVEL_GH_READWRITE:
+        return "unrestricted", "none"
+    else:
+        return "unrestricted", "unrestricted"
+
+
 def classify_graphql(body: bytes) -> tuple[str | None, str | None]:
     """Classify a GraphQL request body.
 
@@ -605,6 +643,10 @@ class AuthProxyHandler(BaseHTTPRequestHandler):
     rate_limiter: ProxyRateLimiter
     token_refresher: GitHubTokenRefresher
 
+    # Thread-safe caches for pre-flight queries (shared across handler instances)
+    _repo_node_id_cache: dict[tuple[str, str], str] = {}
+    _repo_node_id_lock = threading.Lock()
+
     def log_message(self, format, *args):
         """Route HTTP server logs to our logger."""
         logger.info(format, *args)
@@ -663,6 +705,7 @@ class AuthProxyHandler(BaseHTTPRequestHandler):
         owner = info["owner"]
         repo = info["repo"]
         level = info.get("level", LEVEL_GIT_ONLY)
+        graphql_read, graphql_write = _resolve_graphql_policies(info)
 
         # Rate limit
         if not self.rate_limiter.check(container):
@@ -689,7 +732,7 @@ class AuthProxyHandler(BaseHTTPRequestHandler):
 
         # Route: GraphQL (/graphql)
         if path == "/graphql" and method == "POST":
-            self._handle_graphql_request(body, container, owner, repo, level)
+            self._handle_graphql_request(body, container, owner, repo, graphql_read, graphql_write)
             return
 
         # Route: REST API (/repos/{owner}/{repo}/...)
@@ -756,33 +799,184 @@ class AuthProxyHandler(BaseHTTPRequestHandler):
             follow_redirects=(method in ("GET", "HEAD")),
         )
 
-    def _handle_graphql_request(self, body, container, owner, repo, level):
-        """Handle GraphQL requests (level 3+)."""
-        if level < LEVEL_GH_READ:
-            self._send_error(403, "GraphQL access not enabled at this access level")
-            logger.info("BLOCKED POST /graphql container=%s reason=level_%d", container, level)
+    def _handle_graphql_request(self, body, container, owner, repo, graphql_read, graphql_write):
+        """Handle GraphQL requests with policy-based access control.
+
+        graphql_read/graphql_write: "whitelisted", "unrestricted", or "none".
+        """
+        if graphql_read == "none" and graphql_write == "none":
+            self._send_error(403, "GraphQL access not enabled")
+            logger.info("BLOCKED POST /graphql container=%s reason=graphql_disabled", container)
             return
 
         if not body:
             self._send_error(400, "Missing request body for GraphQL")
             return
 
-        op_type, error = classify_graphql(body)
+        # For unrestricted mode, use the simpler classify_graphql path
+        if graphql_read == "unrestricted" and graphql_write == "unrestricted":
+            op_type, error = classify_graphql(body)
+            if error:
+                self._send_error(400, f"GraphQL validation failed: {error}")
+                logger.info("BLOCKED POST /graphql container=%s reason=%s", container, error)
+                return
+            # Both unrestricted: allow any query or mutation
+            upstream_url = f"{GITHUB_API_URL}/graphql"
+            self._forward_to_github(
+                "POST", upstream_url, body, container, "/graphql", host=GITHUB_API_HOST
+            )
+            return
+
+        if graphql_read == "unrestricted" and graphql_write == "none":
+            # Legacy level 3 behavior: unrestricted reads, no writes
+            op_type, error = classify_graphql(body)
+            if error:
+                self._send_error(400, f"GraphQL validation failed: {error}")
+                logger.info("BLOCKED POST /graphql container=%s reason=%s", container, error)
+                return
+            if op_type == "mutation":
+                self._send_error(403, "Mutations not allowed at this access level")
+                logger.info(
+                    "BLOCKED POST /graphql container=%s reason=mutation_rejected", container
+                )
+                return
+            upstream_url = f"{GITHUB_API_URL}/graphql"
+            self._forward_to_github(
+                "POST", upstream_url, body, container, "/graphql", host=GITHUB_API_HOST
+            )
+            return
+
+        # Whitelisted mode: full structural + semantic validation
+        from .graphql_validator import (
+            _count_operations,
+            _tokenize,
+            parse_graphql,
+            validate_read,
+            validate_structure,
+            validate_write,
+        )
+
+        parsed, error = parse_graphql(body)
         if error:
             self._send_error(400, f"GraphQL validation failed: {error}")
             logger.info("BLOCKED POST /graphql container=%s reason=%s", container, error)
             return
 
-        if op_type == "mutation" and level < LEVEL_GH_READWRITE:
-            self._send_error(403, "Mutations not allowed at this access level")
-            logger.info("BLOCKED POST /graphql container=%s reason=mutation_rejected", container)
+        # Count operations for structural validation
+        tokens = _tokenize(parsed.query_str)
+        op_count = _count_operations(tokens)
+
+        # Structural validation
+        error = validate_structure(parsed, op_count=op_count)
+        if error:
+            self._send_error(403, f"GraphQL structural validation failed: {error}")
+            logger.info("BLOCKED POST /graphql container=%s reason=structural_%s", container, error)
             return
 
+        if parsed.op_type == "mutation":
+            if graphql_write == "none":
+                self._send_error(403, "Mutations not allowed")
+                logger.info(
+                    "BLOCKED POST /graphql container=%s reason=mutation_rejected", container
+                )
+                return
+
+            if graphql_write == "whitelisted":
+                error = validate_write(
+                    parsed,
+                    owner,
+                    repo,
+                    preflight_fn=self._preflight_check,
+                    repo_node_id_fn=self._get_repo_node_id,
+                )
+                if error:
+                    self._send_error(403, f"GraphQL mutation validation failed: {error}")
+                    logger.info(
+                        "BLOCKED POST /graphql container=%s mutation=%s reason=%s",
+                        container,
+                        parsed.top_level_fields[0].name if parsed.top_level_fields else "?",
+                        error,
+                    )
+                    return
+            # "unrestricted" write: structural validation already passed
+        else:
+            # Query
+            if graphql_read == "none":
+                self._send_error(403, "Queries not allowed")
+                logger.info("BLOCKED POST /graphql container=%s reason=query_rejected", container)
+                return
+
+            if graphql_read == "whitelisted":
+                error = validate_read(
+                    parsed,
+                    owner,
+                    repo,
+                    preflight_fn=self._preflight_check,
+                )
+                if error:
+                    self._send_error(403, f"GraphQL read validation failed: {error}")
+                    logger.info("BLOCKED POST /graphql container=%s reason=%s", container, error)
+                    return
+            # "unrestricted" read: structural validation already passed
+
         upstream_url = f"{GITHUB_API_URL}/graphql"
         self._forward_to_github(
             "POST", upstream_url, body, container, "/graphql", host=GITHUB_API_HOST
         )
 
+    def _github_graphql_query(self, query: str, variables: dict) -> dict:
+        """Make a GraphQL query to GitHub API. Returns parsed JSON response.
+
+        Used for pre-flight ownership checks and repo node ID resolution.
+        """
+        github_token = self.token_refresher.token
+        body = json.dumps({"query": query, "variables": variables}).encode()
+
+        req = Request(f"{GITHUB_API_URL}/graphql", data=body, method="POST")
+        req.add_header("Authorization", f"token {github_token}")
+        req.add_header("Content-Type", "application/json")
+        req.add_header("Host", GITHUB_API_HOST)
+
+        ctx = ssl.create_default_context()
+        opener = build_opener(ProxyHandler({}), HTTPSHandler(context=ctx))
+        resp = opener.open(req, timeout=30)
+        return json.loads(resp.read())
+
+    def _get_repo_node_id(self, owner: str, repo: str) -> str | None:
+        """Get the GitHub node ID for a repository. Cached."""
+        key = (owner.lower(), repo.lower())
+        with self._repo_node_id_lock:
+            cached = self._repo_node_id_cache.get(key)
+            if cached is not None:
+                return cached
+
+        from .graphql_validator import REPO_ID_QUERY
+
+        try:
+            data = self._github_graphql_query(REPO_ID_QUERY, {"owner": owner, "name": repo})
+            node_id = data.get("data", {}).get("repository", {}).get("id")
+            if node_id:
+                with self._repo_node_id_lock:
+                    self._repo_node_id_cache[key] = node_id
+            return node_id
+        except Exception:
+            logger.info("PREFLIGHT repo_node_id failed for %s/%s", owner, repo)
+            return None
+
+    def _preflight_check(self, node_id: str) -> str | None:
+        """Check which repo a node belongs to.
+
+        Returns "owner/repo" string or None on failure.
+        """
+        from .graphql_validator import PREFLIGHT_QUERY, extract_repo_from_preflight
+
+        try:
+            data = self._github_graphql_query(PREFLIGHT_QUERY, {"id": node_id})
+            return extract_repo_from_preflight(data)
+        except Exception:
+            logger.info("PREFLIGHT check failed for node %s", node_id)
+            return None
+
     def _forward_to_github(
         self,
         method,

{dev_bubble-0.7.3 → dev_bubble-0.7.6}/bubble/github_token.py

@@ -107,20 +107,52 @@ def _ensure_auth_proxy_running() -> int | None:
 
 
 def _resolve_access_level(config: dict, gh_enabled: bool) -> int:
-    """Determine the auth proxy access level for a container.
+    """Determine the auth proxy REST access level for a container.
 
-    Returns the access level (1-4) based on config and tool availability.
+    Returns the REST access level (1 or 4) based on config and tool
+    availability.  GraphQL policies are resolved separately by
+    _resolve_graphql_config().
     """
-    from .auth_proxy import DEFAULT_LEVEL, LEVEL_GH_READWRITE, LEVEL_GIT_ONLY
-    from .security import get_setting, is_enabled
+    from .auth_proxy import LEVEL_GH_READWRITE, LEVEL_GIT_ONLY
+    from .security import is_enabled
 
     if not gh_enabled or not is_enabled(config, "github_api"):
         return LEVEL_GIT_ONLY
 
+    # REST is already repo-scoped by path validation, so read-write is
+    # safe by default.  This enables REST POST operations like
+    # gh run rerun (/repos/{owner}/{repo}/actions/runs/{id}/rerun).
+    return LEVEL_GH_READWRITE
+
+
+def _resolve_graphql_config(config: dict, gh_enabled: bool) -> tuple[str, str]:
+    """Determine GraphQL policies for a container.
+
+    Returns (graphql_read, graphql_write).
+    """
+    from .security import get_setting, is_enabled
+
+    if not gh_enabled or not is_enabled(config, "github_api"):
+        return "none", "none"
+
     if get_setting(config, "github_api") == "read-write":
-        return LEVEL_GH_READWRITE
+        return "unrestricted", "unrestricted"
+
+    # Default: whitelisted for both — repo-scoped reads, allowlisted mutations
+    return "whitelisted", "whitelisted"
 
-    return DEFAULT_LEVEL  # LEVEL_GH_READ (3)
+
+def _describe_graphql_mode(graphql_read: str, graphql_write: str) -> str:
+    """Human-readable description of GraphQL access mode."""
+    if graphql_read == "whitelisted" and graphql_write == "whitelisted":
+        return "repo-scoped (allowlisted GraphQL)"
+    if graphql_read == "unrestricted" and graphql_write == "unrestricted":
+        return "unrestricted GraphQL read-write"
+    if graphql_read == "unrestricted" and graphql_write == "none":
+        return "unrestricted GraphQL read-only"
+    if graphql_read == "none" and graphql_write == "none":
+        return "git only"
+    return f"GraphQL read={graphql_read}, write={graphql_write}"
 
 
 def _wait_for_proxy_device(runtime: ContainerRuntime, container: str, port: int):
@@ -168,6 +200,7 @@ def setup_auth_proxy(
     from .auth_proxy import generate_auth_token
 
     level = _resolve_access_level(config or {}, gh_enabled)
+    graphql_read, graphql_write = _resolve_graphql_config(config or {}, gh_enabled)
 
     port = _ensure_auth_proxy_running()
     if not port:
@@ -177,7 +210,14 @@ def setup_auth_proxy(
         return False
 
     # Generate per-container token with appropriate access level
-    token = generate_auth_token(container, owner, repo, level=level)
+    token = generate_auth_token(
+        container,
+        owner,
+        repo,
+        level=level,
+        graphql_read=graphql_read,
+        graphql_write=graphql_write,
+    )
 
     # Add Incus proxy device: expose host TCP port into container
     # On macOS (Colima), need to use the host IP from the VM's perspective
@@ -234,11 +274,8 @@ def setup_auth_proxy(
         _setup_gh_proxy(runtime, container, token, connect_addr, machine_readable)
 
     if not machine_readable:
-        level_desc = {1: "git only", 2: "REST read-only", 3: "gh read-only", 4: "gh read-write"}
-        detail(
-            f"GitHub auth proxy configured"
-            f" (scoped to {owner}/{repo}, level {level}: {level_desc.get(level, '?')})."
-        )
+        mode_desc = _describe_graphql_mode(graphql_read, graphql_write)
+        detail(f"GitHub auth proxy configured (scoped to {owner}/{repo}, {mode_desc}).")
     return True
 
 
@@ -316,6 +353,7 @@ def setup_auth_proxy_remote(
     from .tunnel import start_tunnel
 
     level = _resolve_access_level(config or {}, gh_enabled)
+    graphql_read, graphql_write = _resolve_graphql_config(config or {}, gh_enabled)
 
     port = _ensure_auth_proxy_running()
     if not port:
@@ -331,7 +369,14 @@ def setup_auth_proxy_remote(
         return False
 
     # Generate per-container token with appropriate access level
-    token = generate_auth_token(container, owner, repo, level=level)
+    token = generate_auth_token(
+        container,
+        owner,
+        repo,
+        level=level,
+        graphql_read=graphql_read,
+        graphql_write=graphql_write,
+    )
 
     # Add Incus proxy device on the remote: tunneled port → container
     from .tunnel import TUNNEL_REMOTE_PORT
@@ -398,11 +443,9 @@ def setup_auth_proxy_remote(
         _setup_gh_proxy_remote(remote_host, container, token, connect_addr, machine_readable)
 
     if not machine_readable:
-        level_desc = {1: "git only", 2: "REST read-only", 3: "gh read-only", 4: "gh read-write"}
+        mode_desc = _describe_graphql_mode(graphql_read, graphql_write)
         detail(
-            f"GitHub auth proxy configured"
-            f" (scoped to {owner}/{repo}, level {level}: {level_desc.get(level, '?')}"
-            f", via SSH tunnel)."
+            f"GitHub auth proxy configured (scoped to {owner}/{repo}, {mode_desc}, via SSH tunnel)."
         )
     return True