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

snowflake/sandbox/mcp.py

@@ -0,0 +1,480 @@
+"""External MCP servers exposed to the sandbox.
+
+An **EXTERNAL MCP SERVER** is a Snowflake schema-level object (``DB.SCHEMA.NAME``)
+that points at a remote MCP endpoint through an API INTEGRATION whose
+``api_provider`` is ``external_mcp``. Declaring one on a sandbox is addressing
+only — you name the object, and Snowflake resolves everything else:
+
+    from snowflake.sandbox import Sandbox
+
+    with Sandbox.create(mcp_servers=["MYDB.MYSCHEMA.GITHUB_MCP_SERVER"]) as sb:
+        sb.exec(["python", "agent.py"])
+
+That is the same shape every other Snowflake surface takes — Cortex Agents accept
+``mcp_servers`` as a list of FQN strings and Snowflake resolves them server-side, per
+invoking user. Pass `McpServer` instead of a bare string only to override the
+client-facing ``name`` or the transport ``profile``:
+
+    from snowflake.sandbox import McpServer
+
+    gh = McpServer.external("MYDB.MYSCHEMA.GITHUB_MCP_SERVER", name="github")
+
+**What the SDK sends, and what it must never send.** The wire entry has seven
+fields, and the SDK populates three of them (``kind``, ``name``, ``fqn``) plus
+``profile``. The other three — ``url``, ``api_integration``, ``secret_entity_id``
+— are filled in by Snowflake *after* it has resolved the server under the calling user's
+own identity. They are not caller input: accepting them would let one user point
+a sandbox at another user's OAuth secret, so the SDK rejects them up front and
+the platform rejects them again with a 400. That double rejection is the security
+boundary of this feature, and `validate_mcp_servers` is the client half of it.
+
+The per-user OAuth token itself never enters the container: the platform injects a
+dummy into ``SANDBOX_MCP_TOKEN_<NAME>`` (see `mcp_token_env_var`) and the egress
+proxy swaps in the real token on the wire, the same mechanism `Secret` uses.
+
+Use `list_mcp_servers` to see what this account has and whether *you* have
+authorized it — connecting is a one-time per-user OAuth flow done in Snowsight,
+and a server you have not authorized is silently omitted from the sandbox rather
+than handed over with an empty token.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from typing import Literal, NoReturn, cast, get_args
+
+from snowflake.sandbox._mcp_discovery import (  # noqa: F401
+    _auth_statuses,
+    _auth_statuses_call,
+    _column_index,
+    _is_privilege_error,
+    _mcp_discovery_error,
+    _server_row,
+    list_mcp_servers,
+)
+from snowflake.sandbox._mcp_status import (  # noqa: F401
+    MCP_STATUS_LIVE,
+    MCP_STATUS_PATH,
+    MCP_STATUS_RECONNECT_REQUIRED,
+    MCP_STATUS_UNKNOWN,
+    McpConnectionStatus,
+    _load_status_doc,
+    _status_entry,
+    mcp_server_status,
+)
+from snowflake.sandbox.exceptions import SandboxError
+
+# `list_mcp_servers` and its SQL helpers now live in `_mcp_discovery`; the
+# in-sandbox status surface (`mcp_server_status`, `McpConnectionStatus`, the
+# ``MCP_STATUS_*`` vocabulary) lives in `_mcp_status`. Both are re-exported above
+# so ``from snowflake.sandbox.mcp import ...`` and __init__'s ``_LAZY`` map keep
+# resolving them here unchanged. The re-export edge is one-way — those modules
+# reach back for mcp's value objects only inside function bodies — which keeps
+# the package's import graph acyclic (see test_module_layout).
+
+__all__ = [
+    "McpServer",
+    "McpServerInfo",
+    "McpConnectionStatus",
+    "MCP_SERVER_KIND",
+    "DEFAULT_MCP_PROFILE",
+    "MCP_STATUS_PATH",
+    "MCP_STATUS_LIVE",
+    "MCP_STATUS_RECONNECT_REQUIRED",
+    "MCP_STATUS_UNKNOWN",
+    "list_mcp_servers",
+    "mcp_server_status",
+    "mcp_token_env_var",
+    "validate_mcp_servers",
+]
+
+
+# The only kind on the wire. There is no "nova" kind: Nova is at most a provider
+# behind an API INTEGRATION, never the abstraction a caller addresses.
+MCP_SERVER_KIND: Literal["external_mcp"] = "external_mcp"
+
+# Transport profile the runtime renders into ``mcp.json``. Streamable HTTP is what
+# the shipped runtime speaks; the field exists so a future transport does not need
+# a new SDK release.
+DEFAULT_MCP_PROFILE = "streamablehttp"
+
+# Prefix for the dummy-token env var, per the SANDBOX_MCP_SERVERS contract. The
+# SANDBOX_ prefix is server-reserved on the create body's `env` MAP and permitted
+# only on `sandbox_env`, which is where the server delivers these — see
+# `_env._PLATFORM_ENV_PREFIXES`.
+_MCP_TOKEN_ENV_PREFIX = "SANDBOX_MCP_TOKEN_"
+
+# Fields Snowflake resolves per user, server-side. A caller cannot know them (the OAuth
+# SECRET is an invisible entity in a parentless per-user schema with a
+# deliberately meaningless name) and must not be able to assert them.
+_GS_RESOLVED_FIELDS: tuple[str, ...] = ("url", "api_integration", "secret_entity_id")
+
+
+# One FQN part: an unquoted Snowflake identifier or a "quoted identifier".
+_FQN_PART = re.compile(r'^(?:[A-Za-z_][A-Za-z0-9_$]*|"[^"]+")$')
+
+# Client-facing name: what mcp.json keys on and what the dummy env var is derived
+# from. Kept to a charset that survives that derivation legibly.
+_MCP_NAME_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_.\-]*$")
+
+# Transport profile: a lowercase token, no punctuation beyond _ and -.
+_MCP_PROFILE_RE = re.compile(r"^[a-z0-9][a-z0-9_\-]*$")
+
+
+def mcp_token_env_var(name: str) -> str:
+    """The environment variable an MCP server's dummy token lands in.
+
+    Non-alphanumeric characters become underscores and the name is uppercased, so
+    a server named ``github`` gets ``SANDBOX_MCP_TOKEN_GITHUB`` and one named
+    ``jira-cloud`` gets ``SANDBOX_MCP_TOKEN_JIRA_CLOUD``. The value in the
+    container is a dummy; the egress proxy substitutes the real per-user OAuth
+    token on requests to that server's host.
+    """
+    return _MCP_TOKEN_ENV_PREFIX + re.sub(r"[^A-Za-z0-9]", "_", name).upper()
+
+
+def _reject_removed(where: str, keys: Sequence[str]) -> None:
+    """Raise for any Snowflake-resolved field the caller must not assert.
+
+    ``url`` / ``api_integration`` / ``secret_entity_id`` are filled in server-side from
+    the EXTERNAL MCP SERVER named by ``fqn``, under the calling user's own OAuth
+    authorization — accepting them from a caller would let one user point a sandbox at
+    another user's secret. Every other unrecognized keyword is caught by the strict
+    constructor / mapping validators (a plain "unexpected keyword" / "unknown field"),
+    so superseded spellings like ``secret_fqn=`` / ``connector=`` now fail there.
+    """
+    for key in keys:
+        if key in _GS_RESOLVED_FIELDS:
+            raise SandboxError(
+                f"{where}: {key!r} is resolved by Snowflake, not by the caller. "
+                f"url, api_integration, and secret_entity_id are filled in "
+                f"server-side from the EXTERNAL MCP SERVER named by fqn, under the "
+                f"calling user's own OAuth authorization — accepting them from a "
+                f"caller would let one user point a sandbox at another user's "
+                f"secret, so the platform rejects them with a 400 as well. Pass only "
+                f"fqn (and optionally name / profile)."
+            )
+
+
+def _validate_fqn(fqn: str) -> str:
+    """Return *fqn* if it is a three-part Snowflake object name, else raise."""
+    raw = fqn.strip()
+    if not raw:
+        raise SandboxError("MCP server fqn must not be empty")
+    parts = raw.split(".")
+    if len(parts) != 3 or not all(_FQN_PART.match(p) for p in parts):
+        raise SandboxError(
+            f"MCP server fqn {fqn!r} is not a fully-qualified Snowflake object name: "
+            "expected DB.SCHEMA.SERVER (letters, digits, '_' or '$' per part; a "
+            'double-quoted "identifier" is also accepted). Run '
+            "snowflake.sandbox.list_mcp_servers() to see the FQNs this account has."
+        )
+    return raw
+
+
+def _name_from_fqn(fqn: str) -> str:
+    """Derive a client-facing name from an FQN's last part.
+
+    Unquoted, lowercased, and squashed to the name charset — a quoted identifier
+    can hold spaces and punctuation that an explicitly-passed name is not allowed
+    to, and a derived name failing validation would report a name the caller never
+    typed. Pass ``name=`` to choose your own.
+    """
+    last = fqn.split(".")[-1]
+    if last.startswith('"') and last.endswith('"'):
+        last = last[1:-1]
+    squashed = re.sub(r"[^A-Za-z0-9_.\-]", "_", last.lower()).lstrip("_.-")
+    return squashed or "mcp"
+
+
+@dataclass(frozen=True, init=False)
+class McpServer:
+    """An EXTERNAL MCP SERVER to expose to the sandbox, referenced by FQN.
+
+    A bare FQN string is the common case and needs none of this —
+    ``mcp_servers=["MYDB.MYSCHEMA.GITHUB_MCP_SERVER"]`` is equivalent to
+    ``mcp_servers=[McpServer.external("MYDB.MYSCHEMA.GITHUB_MCP_SERVER")]``.
+    Construct one explicitly to override the client-facing `name` (which
+    ``mcp.json`` keys on, and from which the dummy-token env var is derived) or the
+    transport `profile`.
+
+    Example:
+        gh = McpServer.external(
+            "MYDB.MYSCHEMA.GITHUB_MCP_SERVER",
+            name="github",           # -> SANDBOX_MCP_TOKEN_GITHUB
+        )
+        with Sandbox.create(mcp_servers=[gh]) as sb:
+            sb.exec(["python", "agent.py"])
+
+    `url`, `api_integration`, and `secret_entity_id` are deliberately absent: Snowflake
+    resolves them per calling user and the SDK is not allowed to assert them.
+    """
+
+    fqn: str
+    name: str | None = None
+    profile: str = DEFAULT_MCP_PROFILE
+
+    def __init__(
+        self,
+        fqn: str,
+        name: str | None = None,
+        profile: str = DEFAULT_MCP_PROFILE,
+        **removed: object,
+    ) -> None:
+        # Hand-written so a superseded or Snowflake-resolved keyword raises the message
+        # that names its replacement, rather than a bare TypeError from the
+        # generated __init__ (or, worse, being accepted and dropped).
+        _reject_removed("McpServer", list(removed))
+        if removed:
+            raise SandboxError(
+                f"McpServer got unexpected keyword(s) {sorted(removed)!r}: it takes "
+                "fqn, name, and profile only."
+            )
+        object.__setattr__(self, "fqn", _validate_fqn(fqn))
+        object.__setattr__(self, "name", name)
+        object.__setattr__(self, "profile", profile)
+        self._validate()
+
+    def _validate(self) -> None:
+        name = self.name if self.name is not None else _name_from_fqn(self.fqn)
+        if not _MCP_NAME_RE.match(name):
+            raise SandboxError(
+                f"MCP server name {name!r} is not usable: expected letters, digits, "
+                "'_', '.' or '-', starting with a letter or digit. The name keys "
+                "mcp.json and is uppercased into the dummy-token env var "
+                f"({_MCP_TOKEN_ENV_PREFIX}<NAME>)."
+            )
+        object.__setattr__(self, "name", name)
+        if not _MCP_PROFILE_RE.match(self.profile):
+            raise SandboxError(
+                f"MCP server profile {self.profile!r} is not a transport profile: "
+                f'expected a lowercase token such as "{DEFAULT_MCP_PROFILE}".'
+            )
+
+    @property
+    def kind(self) -> Literal["external_mcp"]:
+        """The wire kind — always ``external_mcp``."""
+        return MCP_SERVER_KIND
+
+    @property
+    def token_env_var(self) -> str:
+        """The env var this server's dummy token lands in inside the container."""
+        return mcp_token_env_var(str(self.name))
+
+    @staticmethod
+    def external(
+        fqn: str,
+        *,
+        name: str | None = None,
+        profile: str = DEFAULT_MCP_PROFILE,
+        **removed: object,
+    ) -> McpServer:
+        """Declare an EXTERNAL MCP SERVER by fully-qualified name.
+
+        Parameters
+        ----------
+        fqn:
+            ``DB.SCHEMA.SERVER`` — the EXTERNAL MCP SERVER object. This is the only
+            required field, and the only addressing the platform accepts; the URL,
+            API integration, and per-user OAuth secret behind it are resolved
+            server-side under the calling user's identity.
+        name:
+            Client-facing name: the key in ``mcp.json`` and the source of the
+            dummy-token env var. Defaults to the FQN's last part, lowercased.
+        profile:
+            Transport profile. Defaults to ``"streamablehttp"``.
+        """
+        _reject_removed("McpServer.external", list(removed))
+        if removed:
+            raise SandboxError(
+                f"McpServer.external got unexpected keyword(s) "
+                f"{sorted(removed)!r}: it takes fqn, name, and profile only."
+            )
+        return McpServer(fqn=fqn, name=name, profile=profile)
+
+    @staticmethod
+    def nova(*_args: object, **_kwargs: object) -> NoReturn:
+        """Removed — raises `SandboxError` naming the replacement."""
+        raise SandboxError(
+            "McpServer.nova() has been removed: 'nova' was never the object a caller "
+            "addresses (it is at most a provider behind an API INTEGRATION), and its "
+            "secret_fqn= argument was impossible to populate. Use "
+            'McpServer.external("DB.SCHEMA.SERVER") — or just pass the FQN string: '
+            'mcp_servers=["DB.SCHEMA.SERVER"].'
+        )
+
+    @staticmethod
+    def account(*_args: object, **_kwargs: object) -> NoReturn:
+        """Removed — raises `SandboxError` naming the replacement."""
+        raise SandboxError(
+            "McpServer.account() has been removed: its database/schema/server triple "
+            'is the one FQN this surface takes. Use McpServer.external("DB.SCHEMA.'
+            'SERVER") — or just pass the FQN string: mcp_servers=["DB.SCHEMA.SERVER"].'
+        )
+
+    def to_wire(self) -> dict[str, str]:
+        """Serialize to the caller-supplied half of the ``SANDBOX_MCP_SERVERS`` entry.
+
+        Exactly four keys: ``kind``, ``name``, ``fqn``, ``profile``. Snowflake adds
+        ``url``, ``api_integration``, and ``secret_entity_id`` after resolving the
+        server for the calling user; the SDK never sends those.
+        """
+        return {
+            "kind": MCP_SERVER_KIND,
+            "name": str(self.name),
+            "fqn": self.fqn,
+            "profile": self.profile,
+        }
+
+
+def _server_from_mapping(srv: Mapping[str, object]) -> McpServer:
+    """Build an `McpServer` from one mapping entry of ``mcp_servers=``.
+
+    Only ``kind``/``fqn``/``name``/``profile`` are accepted, and ``kind`` only as
+    the single supported value: a mapping is the form a caller is most likely to
+    hand-assemble (or paste from another surface), so an unrecognised key is an
+    error rather than something silently dropped.
+    """
+    keys = [str(k) for k in srv]
+    _reject_removed("mcp_servers entry", keys)
+    unknown = [k for k in keys if k not in ("kind", "fqn", "name", "profile")]
+    if unknown:
+        raise SandboxError(
+            f"mcp_servers entry has unknown field(s) {sorted(unknown)!r}: an "
+            "entry carries fqn (required) and optionally name and profile."
+        )
+    kind = srv.get("kind", MCP_SERVER_KIND)
+    if kind != MCP_SERVER_KIND:
+        raise SandboxError(
+            f"mcp_servers entry kind {kind!r} is not supported: the only kind "
+            f"is {MCP_SERVER_KIND!r} (an EXTERNAL MCP SERVER named by fqn)."
+        )
+    fqn = srv.get("fqn")
+    if not isinstance(fqn, str) or not fqn:
+        raise SandboxError(
+            "mcp_servers entry requires fqn='DB.SCHEMA.SERVER' (the EXTERNAL "
+            "MCP SERVER object; everything else is resolved server-side)."
+        )
+    raw_name = srv.get("name")
+    raw_profile = srv.get("profile", DEFAULT_MCP_PROFILE)
+    return McpServer(
+        fqn=fqn,
+        name=str(raw_name) if raw_name is not None else None,
+        profile=str(raw_profile),
+    )
+
+
+def validate_mcp_servers(
+    servers: Sequence[str | McpServer | Mapping[str, object]],
+) -> list[dict[str, str]]:
+    """Validate ``mcp_servers=`` and convert it to wire entries.
+
+    Accepts a bare FQN string (the common case), an `McpServer`, or a mapping with
+    ``fqn`` and optionally ``name`` / ``profile``. Raises `SandboxError` for a
+    field the caller cannot legitimately supply — the Snowflake-resolved ``url`` /
+    ``api_integration`` / ``secret_entity_id`` — and for any other unrecognized
+    keyword (a plain "unexpected keyword" / "unknown field"), which is how the
+    superseded ``secret_fqn=`` / ``connector=`` / ``database=`` spellings now fail.
+
+    Duplicate names, duplicate FQNs, and two names that collapse to the same dummy
+    env var are all rejected: each would be a last-one-wins overwrite in the
+    container rather than an error.
+    """
+    entries: list[dict[str, str]] = []
+    names_seen: set[str] = set()
+    fqns_seen: set[str] = set()
+    env_vars_seen: dict[str, str] = {}
+
+    for srv in servers:
+        if isinstance(srv, McpServer):
+            entry = srv.to_wire()
+        elif isinstance(srv, str):
+            entry = McpServer(fqn=srv).to_wire()
+        elif isinstance(srv, Mapping):
+            entry = _server_from_mapping(srv).to_wire()
+        else:
+            raise SandboxError(
+                f"mcp_servers entry must be an FQN string, McpServer, or mapping, got "
+                f"{type(srv).__name__}"
+            )
+
+        name = entry["name"]
+        if name in names_seen:
+            raise SandboxError(f"duplicate MCP server name: {name!r}")
+        names_seen.add(name)
+        if entry["fqn"] in fqns_seen:
+            raise SandboxError(f"duplicate MCP server fqn: {entry['fqn']!r}")
+        fqns_seen.add(entry["fqn"])
+        env_var = mcp_token_env_var(name)
+        clash = env_vars_seen.get(env_var)
+        if clash is not None:
+            raise SandboxError(
+                f"MCP server names {clash!r} and {name!r} both derive the dummy-token "
+                f"env var {env_var}, so one token would overwrite the other in the "
+                "container. Give them names that differ by more than punctuation."
+            )
+        env_vars_seen[env_var] = name
+
+        entries.append(entry)
+
+    return entries
+
+
+# --------------------------------------------------------------------------- #
+# Discovery
+# --------------------------------------------------------------------------- #
+
+# Statuses SYSTEM$GET_USER_INTEGRATION_AUTHORIZATIONS returns, plus the SDK's own
+# "could not determine" value.
+MCP_AUTH_CONNECTED: Literal["CONNECTED"] = "CONNECTED"
+MCP_AUTH_NOT_CONNECTED: Literal["NOT_CONNECTED"] = "NOT_CONNECTED"
+MCP_AUTH_NEEDS_REAUTH: Literal["NEEDS_REAUTH"] = "NEEDS_REAUTH"
+MCP_AUTH_INTEGRATION_NOT_FOUND: Literal["INTEGRATION_NOT_FOUND"] = "INTEGRATION_NOT_FOUND"
+MCP_AUTH_UNKNOWN: Literal["UNKNOWN"] = "UNKNOWN"
+
+McpAuthStatus = Literal[
+    "CONNECTED", "NOT_CONNECTED", "NEEDS_REAUTH", "INTEGRATION_NOT_FOUND", "UNKNOWN"
+]
+"""Per-user authorization status of an EXTERNAL MCP SERVER (`McpServerInfo.status`)."""
+
+
+def _coerce_auth_status(raw: object) -> McpAuthStatus:
+    """Clamp a wire authorization value to the known set; unknown -> ``UNKNOWN``."""
+    return cast("McpAuthStatus", raw) if raw in get_args(McpAuthStatus) else MCP_AUTH_UNKNOWN
+
+
+@dataclass(frozen=True)
+class McpServerInfo:
+    """One EXTERNAL MCP SERVER in the account, with *your* authorization status.
+
+    `status` is per calling user, because the OAuth authorization is: the same
+    server reads ``CONNECTED`` for one user and ``NOT_CONNECTED`` for the next.
+    Values are ``CONNECTED``, ``NOT_CONNECTED``, ``NEEDS_REAUTH``,
+    ``INTEGRATION_NOT_FOUND``, or ``UNKNOWN`` when the status could not be read
+    (no API integration on the server, or the account does not expose the
+    ``api_integration`` column of ``SHOW EXTERNAL MCP SERVERS``).
+
+    This is the *account authorization* view, and it can lag reality: a grant
+    revoked on the provider side still reads ``CONNECTED`` here until Snowflake
+    next tries to use the token. From inside a sandbox, `mcp_server_status` reads
+    the hostagent's own most-recent fetch result instead, which is the signal
+    that actually tells you whether a tool call will work right now.
+    """
+
+    name: str
+    fqn: str
+    api_integration: str | None
+    status: McpAuthStatus
+    enabled: bool | None = None
+    comment: str | None = None
+
+    @property
+    def connected(self) -> bool:
+        """True when this user has a live OAuth authorization for the server."""
+        return self.status == MCP_AUTH_CONNECTED
+
+    def as_mcp_server(self, *, name: str | None = None) -> McpServer:
+        """The `McpServer` to pass to ``mcp_servers=`` for this entry."""
+        return McpServer.external(self.fqn, name=name)

snowflake/sandbox/mount.py

@@ -0,0 +1,161 @@
+"""FUSE stage/workspace mounts.
+
+``StageMount`` is a Snowflake stage or workspace mounted into the container's
+filesystem. Its counterpart in the other direction — ``Bundle``, the local
+project tree shipped *up* to a stage — used to live here as well; it now sits in
+``_assemble`` next to the code that packages it.
+
+    from snowflake.sandbox import StageMount
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+
+from snowflake.sandbox.exceptions import SandboxError
+
+__all__ = ["StageMount", "validate_stage_mounts"]
+
+# Container paths a stage must not be mounted over: a writable FUSE mount here
+# would shadow the TLS trust store / CA bundle (defeating egress verification),
+# the connector config + Snowflake credential dir, or core system binaries — i.e.
+# turn a stage mount into a container-integrity / privilege-escalation primitive.
+# The platform already rejects "/" and ".." for *secret file* mounts, but stage
+# mounts have no such guard server-side. Reject the root itself and any path
+# beneath it.
+_DENIED_MOUNT_ROOTS: tuple[str, ...] = (
+    "/etc",
+    "/usr",
+    "/bin",
+    "/sbin",
+    "/lib",
+    "/lib64",
+    "/proc",
+    "/sys",
+    "/dev",
+    "/boot",
+    "/snowflake",
+)
+
+
+def _normalize_mount_path(mount_path: str) -> str:
+    """Validate a stage ``mount_path`` and return its normalized form.
+
+    Requires an absolute POSIX path with no ``..`` component and no NUL/newline,
+    and refuses the filesystem root and the system roots in
+    `_DENIED_MOUNT_ROOTS` (and anything beneath them). Raises `SandboxError`.
+    Callers pass only a non-empty path (empty means "let the platform default").
+    """
+    from posixpath import normpath
+
+    if any(c in mount_path for c in "\x00\n\r"):
+        raise SandboxError("stage mount_path must not contain NUL or newline characters")
+    if not mount_path.startswith("/"):
+        raise SandboxError(
+            f"stage mount_path {mount_path!r} must be an absolute path (start with '/')"
+        )
+    if ".." in mount_path.split("/"):
+        raise SandboxError(f"stage mount_path {mount_path!r} must not contain a '..' component")
+    # posixpath.normpath preserves exactly two leading slashes ('//etc' stays
+    # '//etc'), which Linux resolves to '/etc' — so collapse leading slashes before
+    # the root/denylist checks, or '//etc' / '//' would slip past them.
+    norm = "/" + normpath(mount_path).lstrip("/")
+    if norm == "/":
+        raise SandboxError("stage mount_path must not be the filesystem root '/'")
+    lowered = norm.lower()
+    for root in _DENIED_MOUNT_ROOTS:
+        if lowered == root or lowered.startswith(root + "/"):
+            raise SandboxError(
+                f"stage mount_path {mount_path!r} is under the reserved system path "
+                f"{root!r}; mounting a stage there would shadow system files "
+                "(TLS trust store, credentials, or binaries). Choose a path like "
+                "'/workspace' or '/data'."
+            )
+    return norm
+
+
+def validate_stage_mounts(mounts: Sequence[StageMount]) -> None:
+    """Reject two mounts that target the same ``mount_path``.
+
+    Each `StageMount` already validates its own path at construction; this is the
+    cross-mount check (two stages mounted at the same point is a silent
+    last-one-wins on the platform). Raises `SandboxError`.
+    """
+    seen: dict[str, str] = {}
+    for m in mounts:
+        if not m.mount_path:
+            continue
+        norm = _normalize_mount_path(m.mount_path)
+        if norm in seen:
+            raise SandboxError(
+                f"stage mounts collide on mount_path {norm!r}: {seen[norm]!r} and "
+                f"{m.stage_name!r} would mount at the same point"
+            )
+        seen[norm] = m.stage_name
+
+
+@dataclass(frozen=True)
+class StageMount:
+    """A Snowflake stage or workspace FUSE-mounted into the container.
+
+    The mount is fully ready before the container command starts.
+
+    Example:
+        mount = StageMount.from_workspace("MY_WS", mount_path="/workspace")
+        data  = StageMount.from_stage("MY_STAGE", mount_path="/data", readonly=True)
+    """
+
+    stage_name: str
+    mount_path: str = ""
+    readonly: bool = False
+    # Internal fields — set by named constructors, not exposed to users.
+    _is_vstage: bool = field(default=False, repr=False)
+    _vstage_namespace: str = field(default="", repr=False)
+    _vstage_version: str = field(default="live", repr=False)
+
+    def __post_init__(self) -> None:
+        # A non-empty mount_path is validated at construction so an unsafe target
+        # (system root, ``..``, non-absolute) fails at author time rather than
+        # mounting a writable stage over the TLS store / credentials / binaries.
+        # An empty mount_path is left for the platform to default.
+        if self.mount_path:
+            _normalize_mount_path(self.mount_path)
+
+    @staticmethod
+    def from_stage(name: str, *, mount_path: str = "", readonly: bool = False) -> StageMount:
+        """Mount a regular Snowflake stage."""
+        return StageMount(stage_name=name, mount_path=mount_path, readonly=readonly)
+
+    @staticmethod
+    def from_workspace(name: str, *, mount_path: str = "", readonly: bool = False) -> StageMount:
+        """Mount a Snowflake Workspace.
+
+        ``readonly=False`` (default) ensures a writable live version exists
+        before mounting.  ``readonly=True`` mounts the head version read-only.
+        """
+        return StageMount(
+            stage_name=name,
+            mount_path=mount_path,
+            readonly=readonly,
+            _is_vstage=True,
+            _vstage_namespace="workspace",
+            _vstage_version="head" if readonly else "live",
+        )
+
+    def to_api_dict(self) -> dict[str, object]:
+        """Serialize to the REST request shape."""
+        d: dict[str, object] = {"stage_name": self.stage_name}
+        if self._is_vstage:
+            d["is_vstage"] = True
+            d["vstage_namespace"] = self._vstage_namespace
+            d["vstage_version"] = self._vstage_version
+        if self.mount_path:
+            d["mount_path"] = self.mount_path
+        if self.readonly:
+            # Omitted when False so the request shape is unchanged for the common
+            # case. Sending it when True is load-bearing: the flag was once accepted
+            # here and never emitted, so a mount asked to be read-only was mounted
+            # writable.
+            d["readonly"] = True
+        return d