feat(validation): enforce HF certification isolation

Author: zkwentz

docs/source/guides/runtime-providers.md

@@ -164,7 +164,8 @@ provider = DockerSwarmProvider()
 
 Runs a registry image in a Hugging Face Sandbox. Pooled mode is the default and
 is appropriate for trusted same-user rollout fan-out. Dedicated mode allocates
-one VM per sandbox and is suited to untrusted or GPU workloads.
+one VM per sandbox and is suited to untrusted or GPU workloads. Official
+validation requires dedicated mode and rejects pooled execution.
 
 ```python
 from openenv.core.containers.runtime.hf_sandbox_provider import HFSandboxProvider
@@ -178,7 +179,8 @@ provider.wait_for_ready(base_url)
 ```
 
 Plain `env_vars` are visible as Job environment metadata. Use the dedicated
-mode's `secrets=` argument for encrypted runtime secrets.
+mode's `secrets=` argument for encrypted runtime secrets. Official validation
+does not forward coordinator secrets through either channel.
 
 ### KubernetesProvider
 

src/openenv/validation/__init__.py

@@ -18,6 +18,7 @@
     ValidationStatus,
 )
 from .planner import build_validation_plan, VALIDATION_POLICY_VERSION
+from .security import ensure_official_hf_sandbox
 from .task_manifest import (
     ArtifactSpec,
     EnvironmentConfig,
@@ -54,6 +55,7 @@
     "ValidationSeverity",
     "ValidationStatus",
     "build_validation_plan",
+    "ensure_official_hf_sandbox",
     "execute_validation_plan",
     "format_shared_validation_report",
     "load_task_manifest",

src/openenv/validation/security.py

@@ -0,0 +1,42 @@
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""Fail-closed trust-boundary guards used by remote certification."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+
+_CREDENTIAL_NAME = re.compile(
+    r"(?i)(authorization|credential|password|private.?key|secret|token|api.?key)"
+)
+
+
+def ensure_official_hf_sandbox(provider: Any) -> None:
+    """Reject shared HF pools for official certification workloads."""
+    if getattr(provider, "isolation_mode", None) != "dedicated":
+        raise RuntimeError(
+            "Official certification requires a dedicated Hugging Face sandbox; "
+            "pooled execution is a same-user trust boundary."
+        )
+    if getattr(provider, "secrets", None):
+        raise RuntimeError(
+            "Official subject sandboxes cannot receive coordinator secrets."
+        )
+    env_vars = getattr(provider, "env_vars", None) or {}
+    credential_names = sorted(
+        str(name) for name in env_vars if _CREDENTIAL_NAME.search(str(name))
+    )
+    if credential_names:
+        raise RuntimeError(
+            "Official subject sandboxes cannot receive credential-like "
+            f"environment variables: {', '.join(credential_names)}"
+        )
+    lock = getattr(provider, "_lock_for_official_certification", None)
+    if not callable(lock):
+        raise RuntimeError(
+            "Official certification requires a provider that can lock its "
+            "validated execution settings."
+        )
+    lock()

tests/test_validation/test_security.py

@@ -0,0 +1,83 @@
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""Tests for validation certification trust-boundary enforcement."""
+
+from __future__ import annotations
+
+from unittest.mock import MagicMock, patch
+
+import pytest
+from openenv.core.containers.runtime import hf_sandbox_provider as provider_module
+from openenv.core.containers.runtime.hf_sandbox_provider import HFSandboxProvider
+from openenv.validation.security import ensure_official_hf_sandbox
+
+
+def test_official_certification_rejects_pooled_hf_sandbox() -> None:
+    pooled = HFSandboxProvider(image="example")
+    dedicated = HFSandboxProvider(image="example", mode="dedicated")
+
+    with pytest.raises(RuntimeError, match="dedicated"):
+        ensure_official_hf_sandbox(pooled)
+
+    ensure_official_hf_sandbox(dedicated)
+
+
+def test_official_certification_rejects_forwarded_credentials() -> None:
+    provider = HFSandboxProvider(
+        image="example",
+        mode="dedicated",
+        env_vars={"HF_TOKEN": "secret"},
+    )
+
+    with pytest.raises(RuntimeError, match="credential-like"):
+        ensure_official_hf_sandbox(provider)
+
+
+def test_official_certification_locks_start_environment() -> None:
+    provider = HFSandboxProvider(
+        image="example",
+        mode="dedicated",
+        env_vars={"MODE": "certify"},
+    )
+    ensure_official_hf_sandbox(provider)
+
+    with pytest.raises(RuntimeError, match="environment overrides"):
+        provider.start_container(env_vars={"HF_TOKEN": "secret"})
+
+
+def test_official_start_rejects_unverifiable_runtime_isolation() -> None:
+    class SandboxWithoutHostIdentity:
+        proxy_headers: dict[str, str] = {}
+
+        def run(self, *args: object, **kwargs: object) -> MagicMock:
+            return MagicMock()
+
+        def proxy_url_for(self, port: int, path: str) -> str:
+            return "https://sandbox.example/proxy"
+
+        def kill(self) -> None:
+            self._killed = True
+
+    sandbox = SandboxWithoutHostIdentity()
+    sandbox_cls = MagicMock()
+    sandbox_cls.create.return_value = sandbox
+    provider = HFSandboxProvider(image="example", mode="dedicated")
+    ensure_official_hf_sandbox(provider)
+
+    with patch.object(provider_module, "_get_sandbox_cls", return_value=sandbox_cls):
+        with pytest.raises(RuntimeError, match="verify dedicated isolation"):
+            provider.start_container()
+
+    assert provider._sandbox is None
+
+
+def test_official_certification_cannot_lock_active_sandbox() -> None:
+    provider = HFSandboxProvider(image="example", mode="dedicated")
+    sandbox = MagicMock()
+    sandbox.host_id = None
+    provider._sandbox = sandbox
+
+    with pytest.raises(RuntimeError, match="before.*started"):
+        ensure_official_hf_sandbox(provider)
+
+    assert provider._official_certification is False