snowflake-sandbox-python 0.2.1a1__py3-none-any.whl

snowflake/sandbox/_diagnostics.py

@@ -0,0 +1,501 @@
+"""Tell the user why a deploy will not work, or did not work.
+
+Three stages, in the order a deploy meets them: `preflight_checks` validates a
+`DeploySpec` client-side before anything is packaged, `diagnose_failure` maps a
+known failure signature to its fix deterministically, and `explain_failure` is
+the fallback for everything else — a best-effort ``snow cortex complete`` call.
+`scaffold_module` (what ``snow sandbox init`` writes) lives here too because it
+shares the inference machinery: ``_infer_egress_comment`` asks the same LLM which
+hosts a project reaches.
+
+So this module DOES make model calls. They are all best-effort and never raise —
+a missing ``snow`` CLI degrades to a sentinel string — but nothing here is on the
+deterministic deploy path, which is exactly why it is not in ``deploy``.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from snowflake.sandbox._deploy_spec import DeploySpec
+    from snowflake.sandbox.deploy import DeployResult
+
+from snowflake.sandbox._hosts import egress_group_for
+from snowflake.sandbox.exceptions import SandboxError
+
+
+@dataclass
+class Problem:
+    """A preflight finding. ``error`` aborts the deploy; ``warn`` is advisory."""
+
+    severity: str  # "error" | "warn"
+    message: str
+    fix: str = ""
+
+
+def _stack_reachable() -> bool | None:
+    """Best-effort reachability probe of the **configured** sandbox endpoint.
+
+    ``None`` = not checked (which is the answer for a real Snowflake host).
+
+    Two things were wrong before. It probed a stale ``GS_HOST`` env var over
+    plain HTTP rather than the configured target, so preflight failed the deploy
+    naming a host that had nothing to do with it; and an unauthenticated GET of
+    one path is far too weak to justify refusing to deploy at all.
+
+    So the probe now runs only for a local stack (local dev mode), where
+    ``http://host/healthz`` is real, fast, and genuinely diagnostic, and it reads
+    the address out of the resolved config. Against a managed host it is skipped:
+    a 401/404 there says nothing, and a 5s connect timeout on every deploy buys
+    nothing. Any HTTP response counts as reachable; only a connection-level
+    failure does not.
+    """
+    from snowflake.sandbox.config import effective_config
+
+    try:
+        cfg = effective_config()
+        if not cfg.cws_dev:
+            return None
+        base = cfg.base_url.rstrip("/")
+    except Exception:
+        return None
+    if not base:
+        return None
+    try:
+        with urllib.request.urlopen(f"{base}/healthz", timeout=5) as r:
+            return bool(r.status)
+    except urllib.error.HTTPError:
+        # The server answered, which is all this probe can honestly assert.
+        return True
+    except Exception:
+        return False
+
+
+def preflight_checks(spec: DeploySpec, bundle_root: Path | None = None) -> list[Problem]:
+    """Cheap, client-side validation of a `DeploySpec`.
+
+    Catches the common misconfigs before we package and ship anything. The one
+    trap we *can't* see from here (the backend's credentials mode) is handled by
+    diagnose_failure."""
+    problems: list[Problem] = []
+
+    if not spec.entry:
+        problems.append(
+            Problem("error", "entry is required", 'add e.g. entry=["python3", "main.py"]')
+        )
+    elif (
+        bundle_root is not None and len(spec.entry) >= 2 and not str(spec.entry[0]).startswith("/")
+    ):
+        # entry like ["python3","main.py"] / ["/bin/bash","setup.sh"] -> the
+        # script (last arg) should exist in the bundle.
+        script = bundle_root / str(spec.entry[-1])
+        if not script.exists():
+            problems.append(
+                Problem(
+                    "error",
+                    f"entry script not found in bundle: {spec.entry[-1]}",
+                    f"create {spec.entry[-1]} in {bundle_root}",
+                )
+            )
+
+    if not spec.image:
+        problems.append(
+            Problem("error", "image is required", 'set image=Image.from_catalog("sandbox-base")')
+        )
+
+    if not spec.code_stage:
+        problems.append(
+            Problem(
+                "warn",
+                "code_stage not set",
+                "set code_stage for presigned code delivery in a hosted deployment",
+            )
+        )
+
+    # Egress + secrets: Snowflake's own rules (env var legality, collisions, per-app
+    # cap, host shape), so a bad declaration fails here rather than at StartApp.
+    try:
+        spec.egress_body()
+    except SandboxError as exc:
+        problems.append(Problem("error", str(exc)))
+
+    # A secret's `host` and Snowflake reachability are different controls: the first is
+    # enforced at the credential swap, the second by allow_internet / the group
+    # booleans. A secret scoped to a host the sandbox cannot reach on Snowflake is
+    # silently useless, so say so. (eai_hosts is the SPCS perimeter and does not
+    # affect Snowflake reachability, so it is deliberately not consulted here.)
+    # Only warn when egress was *explicitly* closed AND no EAI was granted:
+    #   - allow_internet is tri-state: left unset the platform applies its permissive
+    #     default, and actual reachability is then an Istio question we cannot answer
+    #     from here — warning on it would be noise on the common path.
+    #   - allow_github / allow_pypi are NOT credited here, and now never could be: both
+    #     are inert, so neither makes a host reachable in any mode. The retired
+    #     allowed_egress_hosts is likewise not consulted — hosts named there are ignored
+    #     platform-side.
+    #   - Under allow_internet=False the only grant left is an EAI, whose network rules
+    #     live in Snowflake and cannot be resolved from here — so an EAI being present is
+    #     taken as "the caller has said how" (loop-invariant, hence hoisted out below).
+    eg = spec.egress
+    if (
+        eg is not None
+        and eg.default_egress_allowed is False
+        and not eg.external_access_integrations
+    ):
+        for s in spec.secrets:
+            for h in s.hosts:
+                hint = (
+                    f"grant {h!r} with an External Access Integration and pass "
+                    f'external_access_integrations=("MY_EAI",) — under '
+                    f"allow_internet=False that is the only grant the platform applies"
+                )
+                problems.append(
+                    Problem(
+                        "warn",
+                        f"secret {s.fqn!r} is scoped to host {h!r}, which the sandbox cannot "
+                        f"reach with allow_internet=False — the credential could never be used",
+                        hint,
+                    )
+                )
+
+    reachable = _stack_reachable()
+    if reachable is False:
+        # A warn, not an error: this is an unauthenticated probe of one path, so a
+        # negative is weak evidence. Failing the deploy on it meant a working
+        # target was refused (`deployed=False`, CLI exit 2) on the strength of a
+        # single unauthenticated GET.
+        try:
+            from snowflake.sandbox.config import effective_config
+
+            target = effective_config().base_url
+        except Exception:  # pragma: no cover - only when nothing is configured
+            target = "the configured host"
+        problems.append(
+            Problem(
+                "warn",
+                f"sandbox backend did not answer at {target}",
+                "check the host/credentials, or start the local stack",
+            )
+        )
+    return problems
+
+
+def diagnose_failure(exit_code: int | None, stdout: str, stderr: str) -> str:
+    """Interpret a failed run. Returns a human fix string, or ''.
+
+    The signature trap: the entry runs but its script isn't there because the
+    code bundle never extracted into the container. Two platform-side causes share
+    this exact symptom (exit 127 from bash, or exit 2 'can't open file' from python):
+      1. backend not in real-credentials mode (the MITM proxy rewrites the S3
+         SigV4 presigned GET -> 403 -> empty bundle); or
+      2. the backend's seeded session token expired (stage-S3 egress allowlisting
+         lapses -> the presigned GET is blocked -> empty bundle)."""
+    if exit_code in (0, None):
+        return ""
+    blob = f"{stdout}\n{stderr}".lower()
+    bundle_missing = (
+        "no such file or directory" in blob or "can't open file" in blob or "cannot open" in blob
+    )
+    if bundle_missing:
+        return (
+            "the entry script wasn't found — the code bundle never extracted. On "
+            "the hosted backend check both: (1) the backend runs in real-credentials "
+            "mode (else the MITM proxy breaks the presigned S3 GET -> 403), and (2) "
+            "its seeded session token hasn't expired (restart the backend to refresh "
+            "it). Both yield an empty bundle with this exact symptom."
+        )
+    if "presigned code download failed" in blob or ("403" in blob and "s3" in blob):
+        return (
+            "presigned code download failed (S3 403) — the hosted backend must run "
+            "in real-credentials mode and have a non-expired session token."
+        )
+    return ""
+
+
+def explain_failure(result: DeployResult, manifest_summary: str = "") -> str:
+    """Best-effort LLM explanation of a deploy failure.
+
+    Only call this when ``result.exit_code != 0`` AND ``result.diagnosis == ""``.
+    Uses ``snow cortex complete`` (Snowflake CLI) for a one-shot prompt.
+    Returns a non-empty string in all cases — either an LLM explanation or a
+    graceful sentinel when no LLM is available or the call errors.
+
+    Never raises.
+    """
+    _TAIL = 2000  # ~2 KB of context
+
+    def _tail(text: str) -> str:
+        return text[-_TAIL:] if len(text) > _TAIL else text
+
+    stderr_tail = _tail(result.stderr)
+    stdout_tail = _tail(result.stdout)
+    context_parts = [f"exit_code: {result.exit_code}"]
+    if manifest_summary:
+        context_parts.append(f"manifest: {manifest_summary}")
+    if stderr_tail:
+        context_parts.append(f"stderr (tail):\n{stderr_tail}")
+    if stdout_tail:
+        context_parts.append(f"stdout (tail):\n{stdout_tail}")
+    context_block = "\n".join(context_parts)
+
+    prompt = (
+        "A sandbox deploy failed. Given this context, explain the most likely "
+        "cause and the fix in 2-3 sentences.\n\n"
+        f"{context_block}"
+    )
+
+    snow_bin = shutil.which("snow") or shutil.which("snowcli")
+    if snow_bin is None:
+        return (
+            "[explain] no local LLM available (snow / snowcli CLI not found); "
+            "see the raw failure output above."
+        )
+
+    try:
+        proc = subprocess.run(
+            [snow_bin, "cortex", "complete", prompt, "--silent"],
+            capture_output=True,
+            text=True,
+            timeout=30,
+        )
+        output = (proc.stdout or "").strip()
+        if output:
+            return output
+        # Non-zero exit or empty response → fall through to sentinel
+        err_snippet = (proc.stderr or "").strip()[:200]
+        return (
+            f"[explain] LLM call returned no output (exit {proc.returncode})"
+            + (f": {err_snippet}" if err_snippet else "")
+            + "; see the raw failure output above."
+        )
+    except subprocess.TimeoutExpired:
+        return (
+            "[explain] LLM call timed out (snow cortex complete); see the raw failure output above."
+        )
+    except Exception as exc:  # noqa: BLE001
+        return (
+            f"[explain] LLM call failed ({type(exc).__name__}: {exc}); "
+            "see the raw failure output above."
+        )
+
+
+def scaffold_module(
+    project_name: str = "my-agent",
+    infer_dir: str | Path | None = None,
+    source_dir: str | Path | None = None,
+) -> str:
+    """Return starter Python defining a deployable App — what ``init`` writes.
+
+    There is no manifest: the module *is* the contract.
+
+    The entry is detected from *source_dir* (default: the module's own directory
+    via *infer_dir*, else a ``main.py`` placeholder): ``setup.sh`` wins, else the
+    first of ``main.py`` / ``app.py`` / ``agent.py`` / ``__main__.py`` / ``run.py``.
+
+    ``infer_dir``, when set, appends a commented ``Egress(...)`` suggestion
+    inferred from the project's imports (advisory only, never active config).
+    """
+    probe = (
+        Path(source_dir)
+        if source_dir is not None
+        else (Path(infer_dir) if infer_dir is not None else None)
+    )
+    entry_repr = '["python3", "main.py"]'
+    req_note = ""
+    if probe is not None and probe.is_dir():
+        if (probe / "setup.sh").exists():
+            entry_repr = '["/bin/bash", "setup.sh"]'
+        else:
+            for cand in ("main.py", "app.py", "agent.py", "__main__.py", "run.py"):
+                if (probe / cand).exists():
+                    entry_repr = f'["python3", "{cand}"]'
+                    break
+        if (probe / "requirements.txt").exists():
+            req_note = (
+                "    # requirements.txt detected — the base pip-installs it at startup,\n"
+                "    # before entry runs.\n"
+            )
+    text = f'''"""A deployable sandbox agent.
+
+Deploy it with:  snow sandbox deploy {{__file__}}
+"""
+
+from snowflake.sandbox import App, Bundle, Egress, Image, Secret
+
+app = App("{project_name}")
+
+
+@app.function(
+    # The base image (a reference to a catalog base).
+    image=Image.from_catalog("sandbox-base"),
+    memory="4g",
+    # What the container runs. Drop `entry=` to run this function's body in the
+    # sandbox instead (the body becomes the remote payload).
+{req_note}    entry={entry_repr},
+    # Files to ship. Add include= globs to slice a monorepo.
+    bundle=Bundle.from_dir("."),
+    # Presigned code delivery (needed in a hosted deployment).
+    # code_stage="TEMP.MY_DB.SANDBOX_CODE",
+    # Static env vars.
+    env={{}},
+    # What the sandbox may reach. The default reaches Snowflake, the stages, and ~43
+    # package-manager hosts (incl. public PyPI). Anything else — GitHub included — needs
+    # an External Access Integration:
+    #   Egress(external_access_integrations=("MY_EAI",))
+    egress=Egress(),
+    # Snowflake SECRETs to broker in. The sandbox gets a dummy; the egress proxy
+    # swaps in the real value on requests to `host`, so the credential never
+    # enters the sandbox. Create the SECRET first:
+    #   CREATE SECRET <db>.<schema>.<name> TYPE = GENERIC_STRING SECRET_STRING = '<v>';
+    # `host` is a scope: a bare host also covers its subdomains. Use hosts=[...]
+    # when one listed host covers the rest. The host must also be reachable per
+    # `egress` above, or preflight warns.
+    secrets=[
+        # Secret.from_name("DB.SCHEMA.MY_TOKEN", env_var="MY_TOKEN",
+        #                  host="api.example.com"),
+    ],
+)
+def agent() -> None:
+    """Runs locally when called directly; deployed with .remote()."""
+    print("hello from the agent")
+
+
+if __name__ == "__main__":
+    import asyncio
+
+    print(asyncio.run(agent.remote()).stdout)
+'''
+    if infer_dir is not None:
+        text += f"\n{_infer_egress_comment(Path(infer_dir))}\n"
+    return text
+
+
+def _infer_advice(host_list_literal: str) -> str:
+    """Render detected hosts as advice naming the option that enables them.
+
+    Hosts outside the two platform-backed groups are suggested as an **External Access
+    Integration**. They briefly got ``allowed_egress_hosts=[...]`` instead, but Snowflake
+    retired that list (hosts named there are ignored), so emitting it would hand the caller
+    a snippet that now raises — and before the SDK started refusing it, one that started a
+    sandbox which silently could not reach them.
+    """
+    import ast as _ast
+
+    try:
+        hosts = [str(h) for h in _ast.literal_eval(host_list_literal)]
+    except (ValueError, SyntaxError):
+        return f"# [infer] hosts the agent may need: {host_list_literal}"
+
+    groups = {g for g in (egress_group_for(h) for h in hosts) if g}
+    # github/dbt hosts count as ungrouped now: the flag that granted them is inert, so they
+    # need an EAI like any host outside the package-managers group — which means listing them
+    # in the CREATE NETWORK RULE printed below.
+    other = [h for h in hosts if egress_group_for(h) in (None, "github/dbt")]
+
+    lines = [f"# [infer] hosts detected: {', '.join(hosts) or '(none)'}"]
+    knobs = []
+    if "pypi" in groups:
+        # Public PyPI is in the always-on package-managers group — reachable by default,
+        # with no flag. allow_pypi is deprecated and inert, so it is not suggested here.
+        lines.append(
+            "# [infer] PyPI hosts are reachable by default (package-managers group); "
+            "no egress flag needed"
+        )
+    if other:
+        knobs.append('external_access_integrations=("MY_EAI",)')
+        lines.append(f"# [infer] not in a platform-backed group: {', '.join(other)}")
+        lines.append("# [infer] grant them with an EAI (a caller-supplied host list is retired):")
+        lines.append("#   CREATE NETWORK RULE db.schema.my_rule MODE = EGRESS TYPE = HOST_PORT")
+        lines.append("#       VALUE_LIST = (" + ", ".join(f"'{h}:443'" for h in other) + ");")
+        lines.append("#   CREATE EXTERNAL ACCESS INTEGRATION my_eai")
+        lines.append("#       ALLOWED_NETWORK_RULES = (db.schema.my_rule) ENABLED = TRUE;")
+    if knobs:
+        lines.append(f"# [infer] suggested: Egress({', '.join(knobs)})")
+    return "\n".join(lines)
+
+
+def _infer_egress_comment(src: Path) -> str:
+    """Scan *.py in *src* for egress hints; ask the LLM which hosts it reaches.
+
+    Returns a COMMENT block — never active config.  Always returns something
+    (degrades gracefully when no LLM is available).
+    """
+    # ── Collect hints from source files ──────────────────────────────────────
+    import re
+
+    hints: list[str] = []
+    url_re = re.compile(r"https?://([a-zA-Z0-9.\-]+)")
+    import_re = re.compile(r"(?:import|from)\s+(requests|httpx|urllib|aiohttp)")
+    saas_re = re.compile(
+        r"\b(github|atlassian|jira|slack|confluence|grafana|stripe|twilio|sendgrid)\b", re.I
+    )
+
+    for py_file in sorted(src.glob("*.py")):
+        try:
+            text = py_file.read_text(errors="replace")
+        except OSError:
+            continue
+        for m in url_re.finditer(text):
+            hints.append(f"url:{m.group(1)}")
+        for m in import_re.finditer(text):
+            hints.append(f"import:{m.group(1)}")
+        for m in saas_re.finditer(text):
+            hints.append(f"ref:{m.group(1).lower()}")
+
+    # Deduplicate while preserving order.
+    seen: set[str] = set()
+    unique_hints: list[str] = []
+    for h in hints:
+        if h not in seen:
+            seen.add(h)
+            unique_hints.append(h)
+
+    if not unique_hints:
+        return "# [infer] no egress hints found in *.py files; review [egress] manually."
+
+    hints_str = ", ".join(unique_hints[:40])  # keep prompt short
+
+    prompt = (
+        "A Python agent project has these egress hints extracted from its source: "
+        f"{hints_str}. "
+        "Based on these hints, list the external hostnames it needs to reach. "
+        "Reply with ONLY a python list literal "
+        'like: ["domain1.com", "domain2.com"]. No explanation.'
+    )
+
+    snow_bin = shutil.which("snow") or shutil.which("snowcli")
+    if snow_bin is None:
+        return (
+            "# [infer] no local LLM available (snow / snowcli not found);\n"
+            "# review the Egress(...) settings manually based on your agent's imports."
+        )
+
+    try:
+        proc = subprocess.run(
+            [snow_bin, "cortex", "complete", prompt, "--silent"],
+            capture_output=True,
+            text=True,
+            timeout=30,
+        )
+        output = (proc.stdout or "").strip()
+        if output:
+            return _infer_advice(output)
+        err_snippet = (proc.stderr or "").strip().replace("\n", " ").replace("\r", "")[:200]
+        return (
+            "# [infer] LLM returned no output"
+            + (f" ({err_snippet})" if err_snippet else "")
+            + "; review the Egress(...) settings manually based on your agent's imports."
+        )
+    except subprocess.TimeoutExpired:
+        return "# [infer] LLM call timed out; review the Egress(...) settings manually based on your agent's imports."
+    except Exception as exc:  # noqa: BLE001
+        return (
+            f"# [infer] LLM call failed ({type(exc).__name__}: {exc}); "
+            "review the Egress(...) settings manually based on your agent's imports."
+        )

snowflake/sandbox/_env.py

@@ -0,0 +1,143 @@
+"""Environment-variable validation for author-time surfaces.
+
+The reserved-name policy for ``Sandbox.create(env=)``:
+a value baked in can redirect the sandbox's Snowflake identity, defeat
+the egress proxy, or hijack code execution, so both go through here.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+
+from snowflake.sandbox.exceptions import SandboxError
+
+__all__ = ["is_platform_env_key", "validate_env_mapping"]
+
+
+# Mirrors Snowflake's server-side env var name rule.
+_ENV_VAR_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+
+# Snowflake reserves this prefix for its own default (non-vanity) secret env vars.
+_RESERVED_ENV_PREFIX = "CNG_SECRET_"
+
+# Env-var names/prefixes an untrusted-code surface must not be able to set.
+# create(env=) reaches the container's environment (merged in CreateContainer). A value
+# baked here can redirect the sandbox's Snowflake identity (SNOWFLAKE_*), pre-occupy
+# a brokered-secret slot (CNG_SECRET_*), defeat the egress proxy / MITM-CA trust
+# (the proxy + TLS vars), or hijack code execution (PATH / LD_*). Reject them on the
+# author-time surface so an env map can't quietly disable a security
+# control. Names are compared case-insensitively (proxy vars are honoured in either
+# case) and prefixes likewise.
+_RESERVED_ENV_PREFIXES: tuple[str, ...] = ("SNOWFLAKE_", _RESERVED_ENV_PREFIX)
+
+_RESERVED_ENV_NAMES: frozenset[str] = frozenset(
+    {
+        "PATH",
+        "LD_PRELOAD",
+        "LD_LIBRARY_PATH",
+        "HTTP_PROXY",
+        "HTTPS_PROXY",
+        "ALL_PROXY",
+        "NO_PROXY",
+        "REQUESTS_CA_BUNDLE",
+        "SSL_CERT_FILE",
+        "SSL_CERT_DIR",
+        "CURL_CA_BUNDLE",
+    }
+)
+
+
+def _reserved_env_reason(name: str) -> str | None:
+    """Why *name* is reserved (a human phrase), or ``None`` if it is allowed.
+
+    Checks the reserved exact-name set (case-insensitive) and the reserved
+    prefixes (SNOWFLAKE_ / CNG_SECRET_, case-insensitive). Does NOT check the
+    identifier charset — callers that care validate that separately, since the
+    secret-env path and the plain-env path word it differently.
+    """
+    upper = name.upper()
+    if upper in _RESERVED_ENV_NAMES:
+        return (
+            f"{name!r} is a reserved environment variable — setting it can disable "
+            "the egress proxy, the TLS trust store, or the executable search path"
+        )
+    for prefix in _RESERVED_ENV_PREFIXES:
+        if upper.startswith(prefix):
+            if prefix == _RESERVED_ENV_PREFIX:
+                return (
+                    f"{name!r} starts with the reserved {_RESERVED_ENV_PREFIX!r} "
+                    "prefix (Snowflake's brokered-secret namespace) — a baked value there "
+                    "pre-occupies a secret slot"
+                )
+            return (
+                f"{name!r} starts with the reserved {prefix!r} prefix — a baked "
+                "value there can redirect the sandbox's Snowflake identity"
+            )
+    return None
+
+
+# Server-reserved env prefixes that the PLATFORM itself injects, and which therefore
+# MUST travel on the create body's `sandbox_env` LIST — never the user `env` MAP. The
+# server rejects (400) a key under these on the `env` map but accepts the platform
+# prefixes on `sandbox_env`:
+#   SNOWFLAKE_, SANDBOX_ -> platform-env prefixes: blocked on the `env` map, allowed on
+#     `sandbox_env`; the code-delivery keys SNOWFLAKE_CODE_URL / SNOWFLAKE_CODE_STAGE_PATH
+#     are recognized platform keys.
+#   CNG_SECRET_ -> Snowflake's brokered-secret injection namespace. Platform-owned: an
+#     SDK-minted key here must not collide on the user env map.
+# A create with env={"SANDBOX_FOO"} or env={"SNOWFLAKE_FOO"} returns HTTP 400
+# 'env key "…" is reserved'; env={"FOO"} is accepted.
+# This is the list the reserved-env-guard scan test enforces against every public
+# entry point's create/deploy body; keep it in lockstep with the server's own rules.
+_PLATFORM_ENV_PREFIXES: tuple[str, ...] = ("SANDBOX_", "SNOWFLAKE_", "CNG_SECRET_")
+
+
+def is_platform_env_key(name: str) -> bool:
+    """True if *name* carries a server-reserved platform prefix.
+
+    See `_PLATFORM_ENV_PREFIXES`. Such a key must ride the `sandbox_env` LIST
+    rather than the user `env` map -- the server 400s a reserved-prefix key on
+    the `env` map.
+    """
+    upper = name.upper()
+    return any(upper.startswith(prefix) for prefix in _PLATFORM_ENV_PREFIXES)
+
+
+def validate_env_mapping(
+    env: Mapping[str, object] | None,
+    *,
+    context: str,
+    allow: frozenset[str] = frozenset(),
+) -> dict[str, str]:
+    """Validate and normalise a user-supplied environment mapping.
+
+    Rejects non-identifier keys, the reserved names/prefixes (see
+    `_reserved_env_reason`), and non-string values (a silent ``str(123)`` /
+    ``str(False)`` coercion is a footgun — ``env(DEBUG=False)`` would bake the
+    string ``"False"``, which is truthy). *allow* names keys that are exempt
+    from the reserved check because the SDK sets them itself (e.g.
+    ``SNOWFLAKE_CODE_URL``, the presigned-download URL ``from_local`` injects).
+    Returns a plain ``dict[str, str]``. Raises `SandboxError`.
+    """
+    if not env:
+        return {}
+    out: dict[str, str] = {}
+    for key, value in env.items():
+        if not isinstance(key, str) or not _ENV_VAR_RE.match(key):
+            raise SandboxError(
+                f"{context}: {key!r} is not a legal environment variable name "
+                "(must match ^[A-Za-z_][A-Za-z0-9_]*$)"
+            )
+        if key not in allow:
+            reason = _reserved_env_reason(key)
+            if reason is not None:
+                raise SandboxError(f"{context}: {reason}")
+        if not isinstance(value, str):
+            raise SandboxError(
+                f"{context}: value for {key!r} must be a string, not "
+                f"{type(value).__name__} (pass '{value}' explicitly if that is what "
+                "you meant — the SDK will not coerce it for you)"
+            )
+        out[key] = value
+    return out