maf-sandbox-bubblewrap 0.1.0__tar.gz

maf_sandbox_bubblewrap-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SOKOLAI BV
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

maf_sandbox_bubblewrap-0.1.0/PKG-INFO

@@ -0,0 +1,71 @@
+Metadata-Version: 2.4
+Name: maf-sandbox-bubblewrap
+Version: 0.1.0
+Summary: Linux namespace and cgroup sandboxes without a container engine.
+Author: SOKOLAI BV
+Author-email: SOKOLAI BV <info@sokolai.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Typing :: Typed
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: POSIX :: Linux
+Requires-Dist: maf-sandbox>=0.47.0,<0.48
+Requires-Python: >=3.12, <3.15
+Project-URL: Homepage, https://www.sokol.ai
+Project-URL: Source, https://github.com/sokolaidev/maf-extensions
+Project-URL: Issues, https://github.com/sokolaidev/maf-extensions/issues
+Description-Content-Type: text/markdown
+
+# maf-sandbox-bubblewrap
+
+[![PyPI](https://img.shields.io/pypi/v/maf-sandbox-bubblewrap)](https://pypi.org/project/maf-sandbox-bubblewrap/) [![Python](https://img.shields.io/pypi/pyversions/maf-sandbox-bubblewrap)](https://pypi.org/project/maf-sandbox-bubblewrap/) [![License](https://img.shields.io/badge/license-MIT-green)](https://github.com/sokolaidev/maf-extensions/blob/main/packages/maf-sandbox-bubblewrap/LICENSE)
+
+> **Experimental.** Not yet released. `maf-sandbox-bubblewrap` may change or be removed without notice and emits `MafSandboxBubblewrapExperimentalWarning` on import.
+
+Experimental Linux sandbox backend using Bubblewrap and cgroup v2, without Docker, an OCI image or a container engine. The runtime is a separately provisioned, trusted Linux root directory. Runtime downloads never happen during a tool call.
+
+## Prerequisites
+
+- Linux with unprivileged user, mount, PID, network, IPC, UTS and cgroup namespaces; Bubblewrap supporting `--disable-userns`, `--assert-userns-disabled`, `--as-pid-1` and bounded tmpfs mounts. Missing support refuses startup.
+- A private cgroup v2 delegation with `cpu`, `memory` and `pids` enabled, `memory.swap.max` and `cgroup.kill`. The host process must already belong to that delegation so it can move children into sibling groups. A systemd service with `Delegate=cpu memory pids` can provide it; the host must place itself in a leaf and enable the controllers on its empty parent. This package does not grant privileges or change host-wide policy.
+- A trusted runtime directory containing `/usr/bin/python3` and `/bin/sh`, with no host credentials or sockets. Keep it immutable while sandboxes run. Runtime, cgroup and state paths and their ancestors must be controlled by the host administrator. State and cgroup roots must resolve outside the runtime. The state directory must be owned by the service user and mode `0700`.
+
+## Use
+
+```python
+from pathlib import Path
+from maf_sandbox import Isolation, SandboxRouter
+from maf_sandbox_bubblewrap import BubblewrapSandboxBackend, BubblewrapSandboxConfig
+
+async def make_router() -> SandboxRouter:
+    backend = await BubblewrapSandboxBackend.create(BubblewrapSandboxConfig(
+        runtime_root=Path("/opt/maf-runtime"),
+        state_root=Path("/var/lib/my-service/sandbox-state"),
+        cgroup_root=Path("/sys/fs/cgroup/my-service"),
+        runtime_id="drawio-native",
+    ))
+    return SandboxRouter([backend], min_isolation=Isolation.CONTAINER)
+```
+
+`SandboxSpec.image` is an optional exact match against the configured `runtime_id`, not an OCI reference. `image_id` is unsupported. The storage base is `/maf-sandbox/work`; only that explicit override or `None` is accepted. Relative working directories address the base. Commands are opaque; a string runs through `/bin/sh -c`, while a sequence executes directly.
+
+The protocol's `Isolation.CONTAINER` means Linux namespaces plus cgroups. It describes the boundary even though no container engine is used. The router's default `MICROVM` floor still refuses this backend. Keep a separate router or use per-spec routing for a native renderer alongside a stronger CodeAct backend; never lower a shared host floor implicitly.
+
+## Boundary and lifecycle
+
+Every sandbox gets mandatory private namespaces, no capabilities, disabled nested user namespaces, a new session and a cleared environment. The runtime is read-only. `/tmp`, `/run` and `/maf-sandbox` are separate bounded tmpfs mounts; aggregate memory, swap, process count and CPU are constrained before any guest starts. Default limits are 1 GiB memory, no swap, 256 processes, two CPU equivalents and 128 MiB per writable mount. No host home, display, network or cgroup filesystem is mounted. Only `Egress.CLOSED`, POSIX `EXEC`, `FILES_IN` and `FILES_OUT` are declared. This is a shared-kernel boundary, not a microVM or a claim of protection against kernel exploits. No seccomp syscall filter is currently supplied.
+
+A private PID 1 broker uses no-follow directory descriptors for transfers. It runs at guest filesystem authority; its stat responses are guest-side metadata, not host attestations. Its control descriptors are protected from ptrace, and commands receive separate stdin/stdout/stderr. Individual transfers are capped at 8 MiB; the router applies its collection count and aggregate byte limits. Combined command output is capped at 1 MiB by default; excess output fails explicitly. A command's descendants, including detached processes, are killed before its reply. Timeout or cancellation after dispatch destroys the entire sandbox; while queued, it refuses only the waiting request. There is no reclamation or snapshot capability; the router uses disposal.
+
+Key identity includes scope, thread, agent, call and kind. An exclusive host file lock prevents another backend object or process from acquiring a live instance. Repeated acquire within one backend can reuse a matching spec; another owner is refused. Files live only in tmpfs and disappear on owner death. Records allow a subsequent host to purge dead owners' cgroups; this is cleanup recovery, not restoration of guest state. Stale instance disposal cannot delete a replacement. A scope purge reports busy or failed records and retains them for retry. Hosts must stop new work across replicas before purging a conversation.
+
+Lock files remain after disposal so a concurrent owner cannot lock a replacement inode under the same name. Remove the state directory only after stopping all owners; long-lived deployments should account for those small files in retention policy.
+
+Ownership records are published atomically before cgroup creation, so a host that dies during startup leaves either no cgroup or a complete cleanup record. Failed setup removes its record after cgroup cleanup succeeds. Commands whose requested timeout exceeds `max_timeout` (180 seconds by default) are rejected with `ValueError` before execution. Accepted deadlines include time waiting for the request lock; only the remaining budget reaches the broker.
+
+## Offline Draw.io
+
+The [runtime provisioning script](https://github.com/sokolaidev/maf-extensions/blob/main/images/drawio-export/build-runtime.sh) uses debootstrap and the pinned Draw.io Desktop package directly, with the same offline assets, fonts and exporter as the image profile. Provisioning needs network access and root; rendering needs neither. Run the host outside that runtime and register this backend with `maf-sandbox-drawio`, passing the configured runtime id as `image`. Linux is the only supported host platform; native Windows and macOS backends are separate work.

maf_sandbox_bubblewrap-0.1.0/README.md

@@ -0,0 +1,50 @@
+# maf-sandbox-bubblewrap
+
+[![PyPI](https://img.shields.io/pypi/v/maf-sandbox-bubblewrap)](https://pypi.org/project/maf-sandbox-bubblewrap/) [![Python](https://img.shields.io/pypi/pyversions/maf-sandbox-bubblewrap)](https://pypi.org/project/maf-sandbox-bubblewrap/) [![License](https://img.shields.io/badge/license-MIT-green)](https://github.com/sokolaidev/maf-extensions/blob/main/packages/maf-sandbox-bubblewrap/LICENSE)
+
+> **Experimental.** Not yet released. `maf-sandbox-bubblewrap` may change or be removed without notice and emits `MafSandboxBubblewrapExperimentalWarning` on import.
+
+Experimental Linux sandbox backend using Bubblewrap and cgroup v2, without Docker, an OCI image or a container engine. The runtime is a separately provisioned, trusted Linux root directory. Runtime downloads never happen during a tool call.
+
+## Prerequisites
+
+- Linux with unprivileged user, mount, PID, network, IPC, UTS and cgroup namespaces; Bubblewrap supporting `--disable-userns`, `--assert-userns-disabled`, `--as-pid-1` and bounded tmpfs mounts. Missing support refuses startup.
+- A private cgroup v2 delegation with `cpu`, `memory` and `pids` enabled, `memory.swap.max` and `cgroup.kill`. The host process must already belong to that delegation so it can move children into sibling groups. A systemd service with `Delegate=cpu memory pids` can provide it; the host must place itself in a leaf and enable the controllers on its empty parent. This package does not grant privileges or change host-wide policy.
+- A trusted runtime directory containing `/usr/bin/python3` and `/bin/sh`, with no host credentials or sockets. Keep it immutable while sandboxes run. Runtime, cgroup and state paths and their ancestors must be controlled by the host administrator. State and cgroup roots must resolve outside the runtime. The state directory must be owned by the service user and mode `0700`.
+
+## Use
+
+```python
+from pathlib import Path
+from maf_sandbox import Isolation, SandboxRouter
+from maf_sandbox_bubblewrap import BubblewrapSandboxBackend, BubblewrapSandboxConfig
+
+async def make_router() -> SandboxRouter:
+    backend = await BubblewrapSandboxBackend.create(BubblewrapSandboxConfig(
+        runtime_root=Path("/opt/maf-runtime"),
+        state_root=Path("/var/lib/my-service/sandbox-state"),
+        cgroup_root=Path("/sys/fs/cgroup/my-service"),
+        runtime_id="drawio-native",
+    ))
+    return SandboxRouter([backend], min_isolation=Isolation.CONTAINER)
+```
+
+`SandboxSpec.image` is an optional exact match against the configured `runtime_id`, not an OCI reference. `image_id` is unsupported. The storage base is `/maf-sandbox/work`; only that explicit override or `None` is accepted. Relative working directories address the base. Commands are opaque; a string runs through `/bin/sh -c`, while a sequence executes directly.
+
+The protocol's `Isolation.CONTAINER` means Linux namespaces plus cgroups. It describes the boundary even though no container engine is used. The router's default `MICROVM` floor still refuses this backend. Keep a separate router or use per-spec routing for a native renderer alongside a stronger CodeAct backend; never lower a shared host floor implicitly.
+
+## Boundary and lifecycle
+
+Every sandbox gets mandatory private namespaces, no capabilities, disabled nested user namespaces, a new session and a cleared environment. The runtime is read-only. `/tmp`, `/run` and `/maf-sandbox` are separate bounded tmpfs mounts; aggregate memory, swap, process count and CPU are constrained before any guest starts. Default limits are 1 GiB memory, no swap, 256 processes, two CPU equivalents and 128 MiB per writable mount. No host home, display, network or cgroup filesystem is mounted. Only `Egress.CLOSED`, POSIX `EXEC`, `FILES_IN` and `FILES_OUT` are declared. This is a shared-kernel boundary, not a microVM or a claim of protection against kernel exploits. No seccomp syscall filter is currently supplied.
+
+A private PID 1 broker uses no-follow directory descriptors for transfers. It runs at guest filesystem authority; its stat responses are guest-side metadata, not host attestations. Its control descriptors are protected from ptrace, and commands receive separate stdin/stdout/stderr. Individual transfers are capped at 8 MiB; the router applies its collection count and aggregate byte limits. Combined command output is capped at 1 MiB by default; excess output fails explicitly. A command's descendants, including detached processes, are killed before its reply. Timeout or cancellation after dispatch destroys the entire sandbox; while queued, it refuses only the waiting request. There is no reclamation or snapshot capability; the router uses disposal.
+
+Key identity includes scope, thread, agent, call and kind. An exclusive host file lock prevents another backend object or process from acquiring a live instance. Repeated acquire within one backend can reuse a matching spec; another owner is refused. Files live only in tmpfs and disappear on owner death. Records allow a subsequent host to purge dead owners' cgroups; this is cleanup recovery, not restoration of guest state. Stale instance disposal cannot delete a replacement. A scope purge reports busy or failed records and retains them for retry. Hosts must stop new work across replicas before purging a conversation.
+
+Lock files remain after disposal so a concurrent owner cannot lock a replacement inode under the same name. Remove the state directory only after stopping all owners; long-lived deployments should account for those small files in retention policy.
+
+Ownership records are published atomically before cgroup creation, so a host that dies during startup leaves either no cgroup or a complete cleanup record. Failed setup removes its record after cgroup cleanup succeeds. Commands whose requested timeout exceeds `max_timeout` (180 seconds by default) are rejected with `ValueError` before execution. Accepted deadlines include time waiting for the request lock; only the remaining budget reaches the broker.
+
+## Offline Draw.io
+
+The [runtime provisioning script](https://github.com/sokolaidev/maf-extensions/blob/main/images/drawio-export/build-runtime.sh) uses debootstrap and the pinned Draw.io Desktop package directly, with the same offline assets, fonts and exporter as the image profile. Provisioning needs network access and root; rendering needs neither. Run the host outside that runtime and register this backend with `maf-sandbox-drawio`, passing the configured runtime id as `image`. Linux is the only supported host platform; native Windows and macOS backends are separate work.

maf_sandbox_bubblewrap-0.1.0/pyproject.toml

@@ -0,0 +1,75 @@
+[project]
+name = "maf-sandbox-bubblewrap"
+version = "0.1.0"
+description = "Linux namespace and cgroup sandboxes without a container engine."
+readme = "README.md"
+requires-python = ">=3.12,<3.15"
+license = "MIT"
+license-files = ["LICENSE"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Typing :: Typed",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Operating System :: POSIX :: Linux",
+]
+dependencies = ["maf-sandbox>=0.47.0,<0.48"]
+
+[[project.authors]]
+name = "SOKOLAI BV"
+email = "info@sokolai.com"
+
+[project.urls]
+Homepage = "https://www.sokol.ai"
+Source = "https://github.com/sokolaidev/maf-extensions"
+Issues = "https://github.com/sokolaidev/maf-extensions/issues"
+
+[tool.uv.sources.maf-sandbox]
+workspace = true
+
+[tool.uv.build-backend]
+module-name = "maf_sandbox_bubblewrap"
+module-root = "src"
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+extend-select = [
+    "I",
+    "UP",
+    "D100",
+    "D101",
+    "D103",
+    "D104",
+    "E501",
+    "W505",
+    "TD",
+    "FIX",
+    "ERA001",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = [
+    "D101",
+    "D103",
+    "E501",
+    "W505",
+]
+
+[tool.ruff.lint.pycodestyle]
+max-doc-length = 100
+
+[tool.pyright]
+include = ["src"]
+typeCheckingMode = "strict"
+pythonPlatform = "Linux"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[build-system]
+requires = ["uv_build>=0.11.24,<0.12.0"]
+build-backend = "uv_build"

maf_sandbox_bubblewrap-0.1.0/pyproject.toml.orig

@@ -0,0 +1,55 @@
+[project]
+name = "maf-sandbox-bubblewrap"
+version = "0.1.0"
+description = "Linux namespace and cgroup sandboxes without a container engine."
+readme = "README.md"
+requires-python = ">=3.12,<3.15"
+authors = [{ name = "SOKOLAI BV", email = "info@sokolai.com" }]
+license = "MIT"
+license-files = ["LICENSE"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Typing :: Typed",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Operating System :: POSIX :: Linux",
+]
+dependencies = ["maf-sandbox>=0.47.0,<0.48"]
+
+[project.urls]
+Homepage = "https://www.sokol.ai"
+Source = "https://github.com/sokolaidev/maf-extensions"
+Issues = "https://github.com/sokolaidev/maf-extensions/issues"
+
+[tool.uv.sources]
+maf-sandbox = { workspace = true }
+
+[tool.uv.build-backend]
+module-name = "maf_sandbox_bubblewrap"
+module-root = "src"
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+extend-select = ["I", "UP", "D100", "D101", "D103", "D104", "E501", "W505", "TD", "FIX", "ERA001"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["D101", "D103", "E501", "W505"]
+
+[tool.ruff.lint.pycodestyle]
+max-doc-length = 100
+
+[tool.pyright]
+include = ["src"]
+typeCheckingMode = "strict"
+pythonPlatform = "Linux"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[build-system]
+requires = ["uv_build>=0.11.24,<0.12.0"]
+build-backend = "uv_build"

maf_sandbox_bubblewrap-0.1.0/src/maf_sandbox_bubblewrap/__init__.py

@@ -0,0 +1,27 @@
+"""Linux Bubblewrap sandboxes with closed networking and mandatory cgroup limits."""
+
+import warnings as _warnings
+
+from ._backend import BubblewrapSandboxBackend
+from ._config import BubblewrapSandboxConfig
+
+__all__ = [
+    "BubblewrapSandboxBackend",
+    "BubblewrapSandboxConfig",
+    "MafSandboxBubblewrapExperimentalWarning",
+]
+
+
+class MafSandboxBubblewrapExperimentalWarning(UserWarning):
+    """The backend is experimental and requires host qualification."""
+
+
+try:
+    _warnings.warn(
+        "maf_sandbox_bubblewrap is experimental and may change without notice.",
+        MafSandboxBubblewrapExperimentalWarning,
+        stacklevel=2,
+    )
+except MafSandboxBubblewrapExperimentalWarning:
+    # An informational notice must not prevent imports under warnings-as-errors.
+    pass

maf_sandbox_bubblewrap-0.1.0/src/maf_sandbox_bubblewrap/_backend.py

@@ -0,0 +1,607 @@
+"""Engine-free Linux namespaces, with host-owned lifecycle records and cgroup supervision."""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import hashlib
+import json
+import math
+import os
+import stat
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, cast
+from uuid import uuid4
+
+from maf_sandbox import (
+    BackendDeclarations,
+    Capability,
+    DisposalFailure,
+    Egress,
+    EntryKind,
+    ExecResult,
+    Isolation,
+    IsolationScope,
+    OsFamily,
+    Sandbox,
+    SandboxBackend,
+    SandboxEntry,
+    SandboxKey,
+    SandboxSpec,
+    SandboxTransferCapExceeded,
+    ScopePurge,
+    fold_disposal_failures,
+)
+
+from ._config import BubblewrapSandboxConfig
+
+FILE_LIMIT = 8 * 1024 * 1024
+FRAME_LIMIT = 12 * 1024 * 1024
+_CAPABILITIES = frozenset({Capability.EXEC, Capability.FILES_IN, Capability.FILES_OUT})
+
+
+def _identity(key: SandboxKey, kind: str) -> list[str]:
+    return [key.scope, key.thread_id, key.agent_id, key.call_id, kind]
+
+
+def _digest(identity: list[str]) -> str:
+    return hashlib.sha256(json.dumps(identity).encode()).hexdigest()
+
+
+def _lock(path: Path) -> int:
+    import fcntl
+
+    fd = os.open(path, os.O_CREAT | os.O_RDWR | os.O_NOFOLLOW, 0o600)
+    try:
+        fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        return fd
+    except BaseException:
+        os.close(fd)
+        raise
+
+
+def _write_record(path: Path, value: dict[str, Any]) -> None:
+    """Publish complete ownership under the caller's exclusive record lock."""
+    pending = path.with_suffix(".pending")
+    fd = os.open(pending, os.O_WRONLY | os.O_CREAT | os.O_TRUNC | os.O_NOFOLLOW, 0o600)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as file:
+            json.dump(value, file)
+            file.flush()
+            os.fsync(file.fileno())
+        os.replace(pending, path)
+    finally:
+        pending.unlink(missing_ok=True)
+
+
+async def _finish(task: asyncio.Task[None]) -> None:
+    """Drain cleanup even if the owning task receives repeated cancellation."""
+    cancelled = False
+    while not task.done():
+        try:
+            await asyncio.shield(task)
+        except asyncio.CancelledError:
+            cancelled = True
+    task.result()
+    if cancelled:
+        raise asyncio.CancelledError
+
+
+async def _diagnostics(stream: asyncio.StreamReader) -> str:
+    retained = bytearray()
+    while chunk := await stream.read(4096):
+        retained.extend(chunk[: max(0, 8192 - len(retained))])
+    return retained.decode("utf-8", errors="replace")
+
+
+def _arguments(config: BubblewrapSandboxConfig) -> list[str]:
+    args = [str(config.bwrap)]
+    args.extend("--unshare-" + name for name in ("user", "pid", "net", "ipc", "uts", "cgroup"))
+    args.extend(
+        [
+            "--disable-userns",
+            "--assert-userns-disabled",
+            "--as-pid-1",
+            "--new-session",
+            "--die-with-parent",
+            "--cap-drop",
+            "ALL",
+            "--clearenv",
+            "--hostname",
+            "sandbox",
+            "--ro-bind",
+            str(config.runtime_root),
+            "/",
+            "--proc",
+            "/proc",
+            "--dev",
+            "/dev",
+        ]
+    )
+    for directory in ("/tmp", "/run", "/maf-sandbox"):
+        args.extend(["--size", str(config.workspace_bytes), "--tmpfs", directory])
+    args.extend(
+        [
+            "--ro-bind",
+            str(Path(__file__).with_name("_guest.py")),
+            "/run/maf-broker.py",
+            "--setenv",
+            "PATH",
+            "/usr/bin:/bin",
+            "--setenv",
+            "LANG",
+            "C.UTF-8",
+            "--setenv",
+            "HOME",
+            "/tmp",
+            "--setenv",
+            "TMPDIR",
+            "/tmp",
+            "--setenv",
+            "DRAWIO_DISABLE_UPDATE",
+            "true",
+            "--chdir",
+            "/",
+            "--",
+            "/usr/bin/python3",
+            "-I",
+            "/run/maf-broker.py",
+        ]
+    )
+    return args
+
+
+class _Sandbox:
+    """One supervised namespace; command output and transfer frames are independently bounded."""
+
+    def __init__(
+        self,
+        backend: BubblewrapSandboxBackend,
+        instance: str,
+        process: asyncio.subprocess.Process,
+        lock_fd: int,
+        record: Path,
+        spec: SandboxSpec,
+        diagnostics: asyncio.Task[str],
+    ) -> None:
+        self.backend = backend
+        self.instance_id = instance
+        self.process = process
+        self.lock_fd = lock_fd
+        self.record = record
+        self.spec = spec
+        self.diagnostics = diagnostics
+        self.dead = False
+        self._serial = asyncio.Lock()
+        self._sequence = 0
+
+    async def _request(
+        self,
+        op: str,
+        *,
+        transport_timeout: float = 10,
+        deadline: float | None = None,
+        **fields: Any,
+    ) -> dict[str, Any]:
+        loop = asyncio.get_running_loop()
+        if deadline is None:
+            deadline = loop.time() + transport_timeout
+        async with asyncio.timeout_at(deadline):
+            await self._serial.acquire()
+        try:
+            if self.dead or self.process.returncode is not None:
+                raise RuntimeError("Sandbox is no longer running")
+            remaining = deadline - loop.time()
+            if remaining <= 0:
+                raise TimeoutError("Request deadline expired before dispatch")
+            if op == "exec":
+                fields["timeout"] = min(fields["timeout"], remaining)
+            self._sequence += 1
+            payload = json.dumps({"id": self._sequence, "op": op, **fields}).encode() + b"\n"
+            if len(payload) > FRAME_LIMIT:
+                raise ValueError("Request exceeds transfer frame limit")
+            assert self.process.stdin is not None and self.process.stdout is not None
+            if loop.time() >= deadline:
+                raise TimeoutError("Request deadline expired before dispatch")
+            try:
+                async with asyncio.timeout_at(deadline):
+                    self.process.stdin.write(payload)
+                    await self.process.stdin.drain()
+                    frame = await self.process.stdout.readline()
+                    if not frame.endswith(b"\n") or len(frame) > FRAME_LIMIT:
+                        raise RuntimeError("Invalid guest response frame")
+                    response: dict[str, Any] = json.loads(frame)
+                    if type(response) is not dict or response.get("id") != self._sequence:
+                        raise RuntimeError("Invalid guest response identity")
+            except BaseException:
+                await _finish(asyncio.create_task(self.stop()))
+                raise
+            if "error" in response:
+                error = response["error"]
+                detail = str(response.get("detail", "Guest operation refused"))[:1024]
+                if error == "TransferCapExceeded":
+                    raise SandboxTransferCapExceeded(detail)
+                if error == "FileNotFoundError":
+                    raise FileNotFoundError(detail)
+                if error == "TimeoutError":
+                    await _finish(asyncio.create_task(self.stop()))
+                    raise TimeoutError(detail)
+                if error in {
+                    "OSError",
+                    "IsADirectoryError",
+                    "NotADirectoryError",
+                    "PermissionError",
+                }:
+                    errors: dict[str, type[OSError]] = {
+                        "OSError": OSError,
+                        "IsADirectoryError": IsADirectoryError,
+                        "NotADirectoryError": NotADirectoryError,
+                        "PermissionError": PermissionError,
+                    }
+                    raise errors[error](detail)
+                raise ValueError(detail)
+            result = response.get("result")
+            if not isinstance(result, dict):
+                await _finish(asyncio.create_task(self.stop()))
+                raise RuntimeError("Invalid guest result")
+            return cast(dict[str, Any], result)
+        finally:
+            self._serial.release()
+
+    async def stop(self) -> None:
+        """Terminate the whole resource group before releasing ownership."""
+        self.dead = True
+        await self.backend.kill_group(self.instance_id)
+        await asyncio.wait_for(self.process.wait(), 10)
+        await self.diagnostics
+        if self.process.stdin is not None:
+            self.process.stdin.close()
+
+    async def write_file(self, path: str, content: str | bytes, *, working_directory: str) -> None:
+        """Write a regular file through no-follow guest descriptors."""
+        data = content.encode("utf-8") if isinstance(content, str) else content
+        if len(data) > FILE_LIMIT:
+            raise SandboxTransferCapExceeded("File exceeds transfer limit")
+        await self._request(
+            "write", path=path, directory=working_directory, data=base64.b64encode(data).decode()
+        )
+
+    async def exec(
+        self,
+        command: str | Sequence[str],
+        *,
+        working_directory: str,
+        timeout: float,
+    ) -> ExecResult:
+        """Execute within the configured deadline and cap combined stdout/stderr bytes."""
+        if type(timeout) not in (int, float) or not 0 < timeout < math.inf:
+            raise ValueError("timeout must be finite and positive")
+        if timeout > self.backend.config.max_timeout:
+            raise ValueError("timeout exceeds configured max_timeout")
+        deadline = asyncio.get_running_loop().time() + timeout
+        result = await self._request(
+            "exec",
+            command=command if isinstance(command, str) else list(command),
+            directory=working_directory,
+            timeout=timeout,
+            transport_timeout=timeout,
+            deadline=deadline,
+            output_limit=self.backend.config.output_bytes,
+        )
+        stdout = base64.b64decode(result["stdout"], validate=True)
+        stderr = base64.b64decode(result["stderr"], validate=True)
+        if (
+            len(stdout) + len(stderr) > self.backend.config.output_bytes
+            or type(result["exit_code"]) is not int
+        ):
+            raise RuntimeError("Invalid guest execution result")
+        return ExecResult(stdout_bytes=stdout, stderr_bytes=stderr, exit_code=result["exit_code"])
+
+    async def stat_file(self, path: str, *, working_directory: str) -> SandboxEntry | None:
+        """Report a guest entry; the isolated broker is not a host filesystem attestation."""
+        try:
+            result = await self._request("stat", path=path, directory=working_directory)
+        except FileNotFoundError:
+            return None
+        if result.get("missing") is True:
+            return None
+        size = result["size"]
+        if size is not None and (type(size) is not int or size < 0):
+            raise RuntimeError("Invalid guest file size")
+        return SandboxEntry(path, EntryKind(result["kind"]), size)
+
+    async def read_file(self, path: str, *, working_directory: str, max_bytes: int) -> bytes:
+        """Read a bounded regular file without following links."""
+        if type(max_bytes) is not int or max_bytes < 0:
+            raise ValueError("max_bytes must be a nonnegative integer")
+        limit = min(max_bytes, FILE_LIMIT)
+        result = await self._request(
+            "read", path=path, directory=working_directory, max_bytes=limit
+        )
+        data = base64.b64decode(result["data"], validate=True)
+        if len(data) > limit:
+            raise SandboxTransferCapExceeded("File exceeds transfer limit")
+        return data
+
+    async def run_code(self, code: str, *, timeout: float) -> ExecResult:
+        """RUN_CODE is not supported; use EXEC with an installed interpreter."""
+        raise NotImplementedError
+
+    async def remove(self, path: str, *, working_directory: str, recursive: bool = False) -> None:
+        """FILES_DELETE is not declared."""
+        raise NotImplementedError
+
+    async def reclaim(self, directory: str, *, working_directory: str, timeout: float) -> None:
+        """Use disposal; no weaker cleanup capability is declared."""
+        raise NotImplementedError
+
+    async def list_dir(self, path: str, *, working_directory: str) -> tuple[SandboxEntry, ...]:
+        """FILES_LIST is not declared."""
+        raise NotImplementedError
+
+    async def reset(self, *, timeout: float) -> None:
+        """SNAPSHOT is not declared."""
+        raise NotImplementedError
+
+
+class BubblewrapSandboxBackend:
+    """A Linux backend requiring working namespaces and delegated cgroup v2 controllers.
+
+    Construct through create() to probe the actual boundary. Guest file metadata is broker
+    reported; no host file plane exists. Call admission is exclusive within one router, and
+    a host flock refuses simultaneous owners across backend objects or processes.
+    """
+
+    name = "bubblewrap"
+    isolation = Isolation.CONTAINER
+    declarations = BackendDeclarations(
+        capabilities=_CAPABILITIES,
+        egress_modes=frozenset({Egress.CLOSED}),
+        os_families=frozenset({OsFamily.POSIX}),
+        isolation_scopes=frozenset({IsolationScope.CALL, IsolationScope.CONVERSATION}),
+        requires_exclusive_admission=True,
+    )
+
+    def __init__(self, config: BubblewrapSandboxConfig) -> None:
+        if sys.platform != "linux":
+            raise RuntimeError("Bubblewrap requires Linux; no subprocess fallback is available")
+        self.config = config
+        self._sandboxes: dict[str, _Sandbox] = {}
+        self._serial = asyncio.Lock()
+
+    @classmethod
+    async def create(cls, config: BubblewrapSandboxConfig) -> BubblewrapSandboxBackend:
+        """Refuse missing runtime, resource controllers or namespace prerequisites."""
+        backend = cls(config)
+        runtime = config.runtime_root.resolve()
+        for name in ("state_root", "cgroup_root"):
+            if getattr(config, name).resolve().is_relative_to(runtime):
+                raise ValueError(f"{name} must be outside runtime_root")
+        for path in (config.runtime_root, config.cgroup_root, config.bwrap):
+            if path.is_symlink() or not path.exists():
+                raise ValueError(f"Missing or symlinked prerequisite: {path}")
+        config.state_root.mkdir(mode=0o700, parents=True, exist_ok=True)
+        info = config.state_root.lstat()
+        if not stat.S_ISDIR(info.st_mode) or info.st_uid != os.getuid() or info.st_mode & 0o077:
+            raise ValueError("state_root must be a private, owned directory")
+        if config.output_bytes > FILE_LIMIT:
+            raise ValueError("output_bytes must not exceed 8 MiB")
+        key = SandboxKey("probe-" + uuid4().hex, "probe", "probe")
+        sandbox = await backend.acquire(key, SandboxSpec(kind="probe", requires=_CAPABILITIES))
+        try:
+            result = await sandbox.exec(
+                ":", working_directory=".", timeout=min(10, config.max_timeout)
+            )
+            if result.exit_code != 0:
+                raise RuntimeError("Namespace probe failed")
+        finally:
+            failure = await backend.dispose(key)
+            if failure is not None:
+                raise RuntimeError(str(failure))
+        return backend
+
+    def _group(self, instance: str) -> Path:
+        if len(instance) != 32 or any(char not in "0123456789abcdef" for char in instance):
+            raise ValueError("Invalid sandbox instance identity")
+        return self.config.cgroup_root / ("maf-" + instance)
+
+    async def kill_group(self, instance: str) -> None:
+        """Kill an owned resource group and wait for its last process to leave."""
+        group = self._group(instance)
+        if not group.exists():
+            return
+        if not (group / "cgroup.kill").exists():
+            group.rmdir()
+            return
+        fd = os.open(group / "cgroup.kill", os.O_WRONLY | os.O_NOFOLLOW)
+        try:
+            os.write(fd, b"1")
+        finally:
+            os.close(fd)
+        async with asyncio.timeout(10):
+            while "populated 1" in (group / "cgroup.events").read_text("ascii"):
+                await asyncio.sleep(0.02)
+        group.rmdir()
+
+    async def acquire(self, key: SandboxKey, spec: SandboxSpec) -> _Sandbox:
+        """Get or create an exact key/kind; refuse conflicting specifications or owners."""
+        if (
+            spec.egress != Egress.CLOSED
+            or not spec.required_capabilities <= _CAPABILITIES
+            or spec.work_dir not in (None, "/maf-sandbox/work")
+            or spec.image not in (None, self.config.runtime_id)
+            or spec.image_id is not None
+        ):
+            raise ValueError("Unsupported Bubblewrap specification")
+        identity = _identity(key, spec.kind)
+        if len(json.dumps(identity).encode()) > 8192:
+            raise ValueError("Sandbox identity exceeds record limit")
+        digest = _digest(identity)
+        async with self._serial:
+            existing = self._sandboxes.get(digest)
+            if existing is not None:
+                if existing.dead or existing.spec != spec:
+                    raise RuntimeError("Dispose the prior sandbox before replacing it")
+                return existing
+            record = self.config.state_root / (digest + ".json")
+            lock_fd = _lock(record.with_suffix(".lock"))
+            instance = uuid4().hex
+            group = self._group(instance)
+            process: asyncio.subprocess.Process | None = None
+            diagnostics: asyncio.Task[str] | None = None
+            try:
+                if record.exists():
+                    previous = self._read_record(record)
+                    if previous["identity"] != identity:
+                        raise ValueError("Sandbox record identity mismatch")
+                    await self.kill_group(previous["instance"])
+                    record.unlink()
+                _write_record(
+                    record,
+                    {
+                        "identity": identity,
+                        "instance": instance,
+                        "cgroup_root": str(self.config.cgroup_root),
+                    },
+                )
+                group.mkdir(mode=0o700)
+                for name, value in (
+                    ("memory.max", str(self.config.memory_bytes)),
+                    ("memory.swap.max", "0"),
+                    ("memory.oom.group", "1"),
+                    ("pids.max", str(self.config.pids)),
+                    ("cpu.max", f"{self.config.cpu_quota} 100000"),
+                ):
+                    with (group / name).open("r+", encoding="ascii") as limit_file:
+                        limit_file.write(value)
+                if not (group / "cgroup.kill").exists():
+                    raise RuntimeError("cgroup v2 kill support is required")
+                process = await asyncio.create_subprocess_exec(
+                    sys.executable,
+                    "-I",
+                    str(Path(__file__).with_name("_launch.py")),
+                    str(os.getpid()),
+                    str(group),
+                    *_arguments(self.config),
+                    stdin=asyncio.subprocess.PIPE,
+                    stdout=asyncio.subprocess.PIPE,
+                    stderr=asyncio.subprocess.PIPE,
+                    limit=FRAME_LIMIT,
+                    env={"PATH": "/usr/bin:/bin", "LANG": "C.UTF-8"},
+                )
+                assert process.stdout is not None
+                assert process.stderr is not None
+                diagnostics = asyncio.create_task(_diagnostics(process.stderr))
+                async with asyncio.timeout(10):
+                    if await process.stdout.readline() != b'{"ready":1}\n':
+                        detail = await diagnostics
+                        raise RuntimeError("Bubblewrap startup failed: " + detail)
+                sandbox = _Sandbox(self, instance, process, lock_fd, record, spec, diagnostics)
+                self._sandboxes[digest] = sandbox
+                return sandbox
+            except BaseException:
+
+                async def cleanup() -> None:
+                    await self.kill_group(instance)
+                    if process is not None:
+                        await asyncio.wait_for(process.wait(), 10)
+                    if diagnostics is not None:
+                        await diagnostics
+                    if record.exists():
+                        owned = self._read_record(record)
+                        if owned["instance"] == instance:
+                            record.unlink()
+
+                try:
+                    await _finish(asyncio.create_task(cleanup()))
+                finally:
+                    os.close(lock_fd)
+                raise
+
+    def _read_record(self, path: Path) -> dict[str, Any]:
+        if path.is_symlink() or path.stat().st_size > 16384:
+            raise ValueError("Invalid sandbox record")
+        value: dict[str, Any] = json.loads(path.read_text("utf-8"))
+        if type(value["identity"]) is not list:
+            raise ValueError("Invalid sandbox record identity")
+        identity = cast(list[object], value["identity"])
+        if (
+            len(identity) != 5
+            or not all(isinstance(item, str) for item in identity)
+            or _digest(cast(list[str], identity)) != path.stem
+            or value["cgroup_root"] != str(self.config.cgroup_root)
+        ):
+            raise ValueError("Sandbox record ownership mismatch")
+        self._group(value["instance"])
+        return value
+
+    async def _dispose_record(self, record: Path, instance_id: str | None) -> bool:
+        local = self._sandboxes.get(record.stem)
+        lock_fd = local.lock_fd if local is not None else _lock(record.with_suffix(".lock"))
+        release = local is None
+        try:
+            if not record.exists():
+                return False
+            value = self._read_record(record)
+            if instance_id is not None and value["instance"] != instance_id:
+                return False
+            if local is not None:
+                await local.stop()
+                self._sandboxes.pop(record.stem)
+                release = True
+            else:
+                await self.kill_group(value["instance"])
+            record.unlink()
+            return True
+        finally:
+            if release:
+                os.close(lock_fd)
+
+    async def dispose(
+        self,
+        key: SandboxKey,
+        *,
+        kind: str | None = None,
+        instance_id: str | None = None,
+    ) -> DisposalFailure | None:
+        """Remove only matching owned records; a stale instance never targets its replacement."""
+        failures: list[DisposalFailure] = []
+        async with self._serial:
+            try:
+                for record in self.config.state_root.glob("*.json"):
+                    try:
+                        value = self._read_record(record)
+                        if value["identity"][:4] == _identity(key, "")[:4] and (
+                            kind is None or value["identity"][4] == kind
+                        ):
+                            await self._dispose_record(record, instance_id)
+                    except Exception as error:
+                        failures.append(DisposalFailure("refused", str(error)))
+            except Exception as error:
+                failures.append(DisposalFailure("refused", str(error)))
+        return fold_disposal_failures(failures)
+
+    async def dispose_scope(self, scope: str, thread_id: str) -> ScopePurge:
+        """Sweep persisted records, retaining failures and refusing another live owner's lock."""
+        failures: list[DisposalFailure] = []
+        disposed = 0
+        async with self._serial:
+            for record in self.config.state_root.glob("*.json"):
+                try:
+                    value = self._read_record(record)
+                    if value["identity"][:2] == [scope, thread_id]:
+                        disposed += await self._dispose_record(record, None)
+                except Exception as error:
+                    failures.append(DisposalFailure("refused", str(error)))
+        return ScopePurge(disposed, fold_disposal_failures(failures))
+
+
+if TYPE_CHECKING:
+    _: tuple[SandboxBackend, type[Sandbox]] = (
+        BubblewrapSandboxBackend(
+            BubblewrapSandboxConfig(Path("/runtime"), Path("/state"), Path("/cgroup"))
+        ),
+        _Sandbox,
+    )

maf_sandbox_bubblewrap-0.1.0/src/maf_sandbox_bubblewrap/_config.py

@@ -0,0 +1,42 @@
+"""Host-owned runtime and delegation settings."""
+
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class BubblewrapSandboxConfig:
+    """Use a trusted Linux root directory and a private delegated cgroup v2 subtree.
+
+    Runtime and control-directory ancestors must not be writable by untrusted principals.
+    State and cgroup roots must stay outside the runtime mounted into the guest. Provision the
+    runtime separately; no archive extraction, package download or engine fallback occurs here.
+    """
+
+    runtime_root: Path
+    state_root: Path
+    cgroup_root: Path
+    runtime_id: str = "native"
+    bwrap: Path = Path("/usr/bin/bwrap")
+    memory_bytes: int = 1024 * 1024 * 1024
+    pids: int = 256
+    cpu_quota: int = 200000
+    workspace_bytes: int = 128 * 1024 * 1024
+    output_bytes: int = 1024 * 1024
+    max_timeout: float = 180
+
+    def __post_init__(self) -> None:
+        for name in ("runtime_root", "state_root", "cgroup_root", "bwrap"):
+            path = getattr(self, name)
+            if not isinstance(path, Path) or not (
+                path.is_absolute() or (name == "bwrap" and path.as_posix().startswith("/"))
+            ):
+                raise ValueError(f"{name} must be an absolute Path")
+        for name in ("memory_bytes", "pids", "cpu_quota", "workspace_bytes", "output_bytes"):
+            value = getattr(self, name)
+            if type(value) is not int or value <= 0:
+                raise ValueError(f"{name} must be a positive integer")
+        if type(self.max_timeout) not in (int, float) or not 0 < self.max_timeout <= 3600:
+            raise ValueError("max_timeout must be positive and at most 3600 seconds")
+        if not self.runtime_id or "\x00" in self.runtime_id:
+            raise ValueError("runtime_id must be nonempty")

maf_sandbox_bubblewrap-0.1.0/src/maf_sandbox_bubblewrap/_guest.py

@@ -0,0 +1,240 @@
+"""Private PID-namespace broker; runs under the same filesystem authority as guest commands."""
+
+from __future__ import annotations
+
+import base64
+import ctypes
+import errno
+import json
+import os
+import posixpath
+import selectors
+import signal
+import stat
+import subprocess
+import sys
+import time
+from pathlib import PurePosixPath
+from typing import Any
+
+FILE_LIMIT = 8 * 1024 * 1024
+FRAME_LIMIT = 12 * 1024 * 1024
+BASE = "/maf-sandbox/work"
+
+
+class TransferCapExceeded(ValueError):
+    """Identify file transfer overflow separately from path confinement refusals."""
+
+
+def parts(path: str, directory: str) -> tuple[str, ...]:
+    """Normalize within two confinement boundaries, without following filesystem links."""
+
+    def confined(value: str, root: str) -> str:
+        candidate = posixpath.normpath(posixpath.join(root, value))
+        prefix = root if root.endswith("/") else root + "/"
+        if candidate != root and not candidate.startswith(prefix):
+            raise ValueError("Path escapes its boundary")
+        return candidate
+
+    if any("\x00" in value or "\\" in value for value in (path, directory)):
+        raise ValueError("Invalid guest path")
+    work = (
+        posixpath.normpath(directory) if posixpath.isabs(directory) else confined(directory, BASE)
+    )
+    return PurePosixPath(confined(path, work)).parts[1:]
+
+
+def parent(path: str, directory: str, *, create: bool = False) -> tuple[int, str]:
+    """Hold no-follow descriptors from the storage base to the operand's parent."""
+    components = parts(path, directory)
+    fd = os.open("/", os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW)
+    try:
+        for name in components[:-1]:
+            if create:
+                try:
+                    os.mkdir(name, mode=0o700, dir_fd=fd)
+                except FileExistsError:
+                    # The no-follow open below still validates the existing component.
+                    pass
+            try:
+                child = os.open(name, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW, dir_fd=fd)
+            except OSError:
+                if stat.S_ISLNK(os.stat(name, dir_fd=fd, follow_symlinks=False).st_mode):
+                    raise ValueError("A path component is a symlink") from None
+                raise
+            os.close(fd)
+            fd = child
+        return fd, components[-1] if components else "."
+    except BaseException:
+        os.close(fd)
+        raise
+
+
+def kill_children() -> None:
+    """Kill every other process in this PID namespace, including detached descendants."""
+    try:
+        os.kill(-1, signal.SIGKILL)
+    except ProcessLookupError:
+        # Children may exit before namespace cleanup sends the signal.
+        pass
+
+
+def execute(request: dict[str, Any]) -> dict[str, Any]:
+    """Drain both streams with bounded storage and remove all descendants before replying."""
+    directory = request["directory"]
+    fd, leaf = parent(".", directory)
+    try:
+        cwd = os.open(leaf, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW, dir_fd=fd)
+    finally:
+        os.close(fd)
+    command = request["command"]
+    if isinstance(command, str):
+        command = ["/bin/sh", "-c", command]
+    streams = [bytearray(), bytearray()]
+    deadline = time.monotonic() + request["timeout"]
+    try:
+        with subprocess.Popen(
+            command,
+            cwd=f"/proc/self/fd/{cwd}",
+            pass_fds=(cwd,),
+            stdin=subprocess.DEVNULL,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+        ) as process:
+            assert process.stdout is not None and process.stderr is not None
+            with selectors.DefaultSelector() as selector:
+                selector.register(process.stdout, selectors.EVENT_READ, 0)
+                selector.register(process.stderr, selectors.EVENT_READ, 1)
+                try:
+                    while selector.get_map():
+                        if time.monotonic() >= deadline:
+                            raise TimeoutError("Guest command exceeded deadline")
+                        if process.poll() is not None:
+                            kill_children()
+                        for key, _ in selector.select(0.02):
+                            data = os.read(key.fd, 65536)
+                            if not data:
+                                selector.unregister(key.fd)
+                            else:
+                                streams[int(key.data)].extend(data)
+                                if sum(map(len, streams)) > request["output_limit"]:
+                                    raise ValueError("Guest command exceeded output limit")
+                    while process.poll() is None:
+                        if time.monotonic() >= deadline:
+                            raise TimeoutError("Guest command exceeded deadline")
+                        time.sleep(0.01)
+                finally:
+                    kill_children()
+            return {
+                "exit_code": process.wait(),
+                "stdout": base64.b64encode(streams[0]).decode(),
+                "stderr": base64.b64encode(streams[1]).decode(),
+            }
+    finally:
+        os.close(cwd)
+        kill_children()
+        while True:
+            try:
+                os.waitpid(-1, 0)
+            except ChildProcessError:
+                break
+
+
+def dispatch(request: dict[str, Any]) -> dict[str, Any]:
+    """Serve only bounded file operations and command execution."""
+    operation = request["op"]
+    if operation == "exec":
+        try:
+            return execute(request)
+        except FileNotFoundError as error:
+            return {
+                "exit_code": 127,
+                "stdout": "",
+                "stderr": base64.b64encode(str(error).encode()).decode(),
+            }
+    if operation == "write" and parts(request["path"], request["directory"]) == parts(
+        ".", request["directory"]
+    ):
+        raise ValueError("Cannot replace the working directory")
+    fd, leaf = parent(request["path"], request["directory"], create=operation == "write")
+    try:
+        if operation == "stat":
+            try:
+                info = os.stat(leaf, dir_fd=fd, follow_symlinks=False)
+            except FileNotFoundError:
+                return {"missing": True}
+            kind = (
+                "file"
+                if stat.S_ISREG(info.st_mode)
+                else "directory"
+                if stat.S_ISDIR(info.st_mode)
+                else "symlink"
+                if stat.S_ISLNK(info.st_mode)
+                else "other"
+            )
+            return {"kind": kind, "size": info.st_size if kind == "file" else None}
+        flags = os.O_NOFOLLOW | os.O_NONBLOCK
+        flags |= os.O_WRONLY | os.O_CREAT if operation == "write" else os.O_RDONLY
+        with os.fdopen(
+            os.open(leaf, flags, 0o600, dir_fd=fd), "wb" if operation == "write" else "rb"
+        ) as file:
+            if not stat.S_ISREG(os.fstat(file.fileno()).st_mode):
+                raise OSError("Only regular files may cross the boundary")
+            if operation == "write":
+                data = base64.b64decode(request["data"], validate=True)
+                if len(data) > FILE_LIMIT:
+                    raise TransferCapExceeded("File exceeds transfer limit")
+                file.truncate(0)
+                file.write(data)
+                return {}
+            if operation != "read":
+                raise ValueError("Unknown operation")
+            limit = min(request["max_bytes"], FILE_LIMIT)
+            data = file.read(limit + 1)
+            if len(data) > limit:
+                raise TransferCapExceeded("File exceeds transfer limit")
+            return {"data": base64.b64encode(data).decode()}
+    except OSError as error:
+        if error.errno == errno.ELOOP and operation == "write":
+            raise ValueError("The file is a symlink") from None
+        raise
+    finally:
+        os.close(fd)
+
+
+def main() -> None:
+    """Keep control pipes private from guest commands and serve framed requests."""
+    if os.getpid() != 1:
+        raise RuntimeError("Broker requires a private PID namespace")
+    if ctypes.CDLL(None).prctl(4, 0, 0, 0, 0) != 0:
+        raise RuntimeError("Could not protect broker process descriptors")
+    os.makedirs(BASE, mode=0o700, exist_ok=True)
+    print('{"ready":1}', flush=True)
+    while True:
+        frame = sys.stdin.buffer.readline(FRAME_LIMIT + 1)
+        if not frame:
+            return
+        if len(frame) > FRAME_LIMIT or not frame.endswith(b"\n"):
+            raise ValueError("Invalid request frame")
+        request = json.loads(frame)
+        try:
+            result = dispatch(request)
+            response = {"id": request["id"], "result": result}
+        except (OSError, ValueError) as error:
+            response = {
+                "id": request["id"],
+                "error": type(error).__name__,
+                "detail": str(error)[:1024],
+            }
+        print(json.dumps(response, separators=(",", ":")), flush=True)
+        while True:
+            try:
+                pid, _ = os.waitpid(-1, os.WNOHANG)
+                if pid == 0:
+                    break
+            except ChildProcessError:
+                break
+
+
+if __name__ == "__main__":
+    main()

maf_sandbox_bubblewrap-0.1.0/src/maf_sandbox_bubblewrap/_launch.py

@@ -0,0 +1,20 @@
+"""Enter the preconfigured resource group before starting any guest process."""
+
+import ctypes
+import os
+import sys
+from pathlib import Path
+
+
+def main() -> None:
+    """Bind lifetime to the owner, join its cgroup and replace this helper with Bubblewrap."""
+    owner, group, *command = sys.argv[1:]
+    libc = ctypes.CDLL(None, use_errno=True)
+    if libc.prctl(1, 9, 0, 0, 0) != 0 or os.getppid() != int(owner):
+        raise RuntimeError("Could not establish owner-death supervision")
+    (Path(group) / "cgroup.procs").write_text(str(os.getpid()), encoding="ascii")
+    os.execv(command[0], command)
+
+
+if __name__ == "__main__":
+    main()